← All build notes

October 15, 2026 · 6 min read

AIWG v2026.10.3: direct workers with inspectable placement

AIWG adds direct dispatch to configured coding CLIs, conductor-owned acceptance checks, stricter unattended operation, and security fixes that require...

  • ai-coding
  • developer-tools
  • releases
  • worker-orchestration
  • mcp

With AIWG v2026.10.3, we can hand bounded work directly to the AI coding CLIs you already have configured. You can inspect placement before launch with aiwg models resolve, review the model, account and quota scopes, and see why other choices were excluded. Execution adds resource admission, isolation and acceptance checks owned by the conductor.

Direct dispatch is off by default. Review account usage, parallelism limits and worker qualification before enabling it; native subagent delegation remains available. This release also tightens unattended operation, carries MCP tool filters into provider configuration, records decision outcomes locally, and replaces shell-string interpolation across hooks and runtime tools.

Inspect placement before launch

Choosing a worker involves more than finding an installed binary. Direct dispatch selects within explicit group, member, model, effort, account and quota scopes. Policy layers preserve inherited restrictions, and selection rejects unavailable, retired, stale or unqualified choices with an explanation.

aiwg models resolve produces the exact shell plan or MCP descriptor without launching a worker. You can inspect the proposed handoff before it consumes another account's quota. Missing model pins are reported rather than rewritten, so resolution leaves a configuration problem visible for the operator to address.

We added worker profiles for CLIs including Codex, Muse, Claude Code, Pi, OMP and DeepSeek Harness. Each profile maps invocation, prompt transport, output and health conventions into the shared contract. Coverage distinguishes documented interfaces, observed identity and live qualification; provider support or an installed CLI alone does not qualify a route.

Start with the direct worker dispatch guide and worker readiness diagnostics before opting in. Managed activation and durable lease scheduling remain later work.

Admission, isolation and acceptance

Before admitting work, direct shell handoffs and MCP orchestration check live memory, pressure, load, worker counts and free disk space. Workers receive explicit arguments, private stdin and output, and allowlisted caller environment values. Systemd memory limits apply where supported.

Writer worktrees start from an exact base commit. File and port claims detect overlapping writers, and dirty work is retained. Hosts lacking required isolation refuse the affected checks unless degraded operation is explicitly selected; isolation capabilities still depend on the host.

The conductor defines acceptance checks and runs them outside worker authority. Their results bind to the verified tree digest, tying acceptance to the tree that was checked. A worker's structured final contains its claims; observed execution, identity, usage, verification and acceptance come from their respective producers. Malformed, duplicate, oversized and post-terminal finals are refused.

Cancellation and deadlines escalate to termination, with capacity reserved until termination is confirmed. A timeout therefore cannot be treated as an available slot while the worker may still be running. Uncertain runs retain evidence and cancel/recheck controls.

Unattended runs and Ralph health

Non-interactive synchronous child processes now have explicit deadlines: 30 seconds for quick calls, two minutes for network calls and ten minutes for long work. Timeouts, signals and failed spawns return failures even if a late status appears clean. The synchronous helper guarantees termination of the direct child; that guarantee does not extend to every descendant.

We also added explicit unattended inputs for session prompts, config path lookup, init/setup choices and contributor conflicts. Supported headless session transports keep prompt content off child argv. Setup preflights selected steps before execution, refuses unresolved inputs, and requires --yes or a dry run for unattended writes. Scripts need to supply the choices an interactive operator would otherwise make.

Ralph external worker health now separates observation, activity, progress and heartbeat clocks. Keepalives, repeated errors, CPU spin and unrelated output do not count as progress. A quiet worker calls for diagnosis; stopping for lack of progress requires the stall window and grace period, with verified ownership before signalling. Lost observation remains unknown.

Default status is read-only, and watch requires a finite deadline. Existing legacy Ralph status is unchanged; use the worker status/watch options when supervising direct runs.

MCP configuration and decision records

MCP tool filters now reach provider configuration. Claude receives deny rules, Codex enabled/disabled tools, and OpenCode its tool map. Unsupported filters warn. Claude toolAllow is refused because Claude's allow rules pre-approve tools rather than enforce a restrictive allowlist.

Layered configuration combines organisation defaults with identity overlays, and profiles can extend bases across layers. Imports validate the complete graph, refusing cycles and missing bases. Empty profiles inject zero servers. Credential policy enforces the strictest lower-layer organisation floor, and project destinations refuse detected literal credentials. Supported references or a genuine private user destination are the paths for those credentials.

Every completed aiwg decision ask call now records a redacted local ledger entry, including fallback and unconfigured outcomes. Questions and context are hashed; --record-text opts into bounded, redacted text storage. Offline history and stats can group by provider, session, kind or caller, so you can inspect which workflow checkpoints use decision offload. The ledger has no built-in retention; plan local rotation if needed.

Security fixes across hooks and runtime tools

The CodeQL sweep replaces shell-string interpolation with separate arguments across hooks, Git/GitHub callers, tmux, remote topology, disk checks and runtime tools. Configuration also rejects prototype-polluting keys and refuses to overwrite unreadable or malformed files.

One fix needs a project refresh: the agent-loop ralph-commit hook now passes commit messages on stdin instead of interpolating changed filenames into a shell command. Updating the package alone does not replace copies already deployed into your projects.

Custom vision templates need review too. Quoted placeholders are now rejected, and paths arrive as separate shell arguments. Complex logic belongs in a trusted wrapper script; the release notes include the migration example and the allowed template syntax.

Upgrading

Install the pinned release:

npm install -g [email protected]

Then refresh deployed components through your normal deployment workflow, including the agent-loop ralph-commit hook, affected provider addons and deployed plugin copies. Re-inject affected MCP profiles after reviewing their filters, destinations and credentials.

Check these behaviour changes against your setup:

  • Worker configuration: review group policy, qualification, resource limits and account quotas before enabling dispatch. Project defaults.* model edits belong in models.json, not aiwg config set.
  • Headless scripts: missing inputs and malformed value flags now refuse. Use --flag=--literal for a value beginning with --. Supply setup inputs and --yes for unattended writes; editor choices still require a terminal.
  • Timeout handling: timeouts and failed spawns now fail. AIWG_SYNC_LONG_TIMEOUT_MS controls the long synchronous bound; its explicit 0 override disables that bound. An individual zero timeout cannot disable a bound.
  • MCP profiles and login: re-inject Claude project servers into .mcp.json, remove or re-scope Claude allowlists, and move project credential literals to supported references or a true private destination. For headless Codex login, select exactly one API-key input mode and review custom CODEX_HOME settings. Profile sessions discard global MCP server definitions and refuse malformed base TOML.
  • Vision templates: migrate custom AIWG_VISION_COMMAND or --command templates that quote the old placeholders. Follow the release-note example using "$1", "$2" and "$3" for image, prompt-file and output paths.
  • Diagnostics and records: doctor JSON requires worker probing; doctor and decision history/stats reject unknown arguments. Account for the new local decision ledger when planning retention.

The version is 2026.10.3 because 2026.10.2 was tagged but never published: publish jobs failed tests that depended on the CI runner's Node installation. This release includes the planned changes plus those fixes.

Try it

npm install -g [email protected]
aiwg doctor --probe-workers --json
aiwg decision stats --group-by caller

Disabled dispatch reports skipped worker probes. Follow the worker dispatch setup guide to review configuration before enabling workers. The full release notes cover the remaining upgrade changes, session collection, artifact containment and provider fixes; the GitHub changelog has the full change history.