AIWG 2026.10.3 - Direct worker orchestration, safer automation, and security hardening

AIWG 2026.10.3 brings a substantial direct-worker orchestration foundation: model and CLI selection, isolated execution, health reporting, verification, and provider-specific headless profiles. It also improves MCP configuration, unattended CLI workflows, decision visibility, session collection, memory, and deployment diagnostics, alongside a broad CodeQL security sweep.

About the version number: `v2026.10.2` was tagged but never published,

because its publish jobs failed tests that depended on the CI runner's Node

installation. 2026.10.3 contains everything planned for 2026.10.2 plus those

fixes: runner-independent publish tests, a script-runner fix that always

drains child output (large outputs could previously hang), and clearer

failures in the GitHub release mirror's tag check.

Upgrading is recommended, including refreshing deployed agent-loop hooks. The `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 a project.

Multi-CLI selection and orchestration

Direct dispatch can place bounded work onto configured CLI installations, with explicit group, member, model, effort, account and quota scopes. Policy layers preserve inherited restrictions; selection rejects unavailable, retired, stale or unqualified choices and explains exclusions. Codex and Muse model discovery records scoped lifecycle, effort and data-use observations, keeps conflicting evidence visible, and preserves prior evidence after an incomplete refresh. Missing model pins are reported rather than rewritten.

`aiwg models resolve` produces an exact shell plan or MCP descriptor without launching a worker. Trusted adapter modules are checked for version, digest, exports and installation-path safety before loading. Versioned worker contracts are negotiated at Mission, Flow, MCP, serve, UHP and cockpit boundaries, so an unsupported consumer refuses a payload before execution. Generated context now describes configured groups, caps and health settings, and conductor guidance covers selection, check-ins and bounded decisions.

This makes worker placement inspectable before it consumes another account's quota. Direct dispatch remains off by default. Review account usage, parallelism limits and qualification before opting in; existing native subagent delegation remains available. See the direct worker dispatch guide. Managed activation and durable lease scheduling remain later work.

Worker execution, isolation and verification

Direct shell handoffs and the existing MCP orchestration tools now share resource admission and typed invocations. Admission checks live memory, pressure, load, worker counts and free disk space. Workers run with explicit arguments, private stdin and output, allowlisted caller environment values, and systemd memory limits where supported. Generated per-run files are bounded, created privately and recorded by digest; previews write nothing.

Writer worktrees start from an exact base commit, and file/port claims catch overlapping writers. Dirty work is retained. Acceptance checks are defined by the conductor, run outside worker authority, and bind their result to the verified tree digest. Structured finals accept worker claims only; observed execution, identity, usage, verification and acceptance come from their respective producers. Duplicate, malformed, oversized or post-terminal finals are refused. Private receipts and digest-only effect links make the result reviewable without copying the brief into every record.

Output frames and individual artifacts are capped at 10 MiB; tree hashing also has aggregate size, entry and depth limits. Cancellation and deadlines escalate to termination, and capacity stays reserved until termination is confirmed. Uncertain runs retain evidence and cancel/recheck controls. Systemd control calls are bounded and use conductor-owned connections; loader/bootstrap controls are rejected from worker environments. Verification reports arbitrary-path reads as degraded even when home/tmp isolation works.

For operators, this reduces accidental overlap and prevents a timeout from being mistaken for a free slot or a successful result. Hosts lacking required isolation refuse affected checks unless degraded operation is explicitly selected. Keep conductor PATH directories and executable targets trusted.

Provider worker profiles and qualification

The direct-worker series adds profiles for Codex, Muse, Claude Code, Hermes, OpenCode, Pi, OMP, Factory droid, GitHub Copilot, Cursor Agent, Grok Build, OpenClaw, Antigravity, DeepSeek Harness and Warp. Each profile maps its CLI's invocation, prompt transport, output and health conventions into the shared worker contract. Version-banner parsing, adapter-supplied stdin frames and generated configuration artifacts close common launch gaps; all direct-profile finals use the same claims validator.

Coverage records now distinguish documented interfaces, observed identity and live qualification. OpenHuman has a version-bound profile with controls still unqualified; Grok Bot and Devin Desktop remain excluded from direct worker dispatch where their interfaces do not meet the contract. A supported provider or an installed binary does not, by itself, qualify a worker route.

The new local Ollama transport is text-only, requires an explicit model and canonical loopback/private IPv4 endpoint, and bounds requests and replies. It refuses cloud selectors, redirects and ambient proxy configuration. It remains unqualified and inactive in the bundled worker registry; restricting the endpoint does not prove local inference or prevent server-side downloads. See the Ollama profile and limitations and provider route inventory. Check the installed version and required controls before enabling any route.

Provider deployment and configuration

Explicit addon deployment now discovers the addon's own skills for Hermes and the shared adapters used by Pi, OpenCode, Copilot, DeepSeek Harness and Windsurf. Hermes migration respects `HERMES_HOME`. Grok Bot project deployments no longer write into the configured user skill root; populating that root requires user scope. OMP deployment and removal, and other shipped tools, resolve their imports correctly from installed packages.

Provider configuration accepts comma-separated or JSON string arrays instead of storing a provider list as one string. Claude detection is shared across runtime info, steward, teams and sync, using current session markers rather than treating an Anthropic API key as proof of a Claude session.

`clean:providers` preserves Claude-owned settings and worktrees, and removes only managed entries from Cursor/Antigravity MCP files and OpenCode instructions. Invalid or unreadable merge targets are left intact with a diagnostic. Redeploy affected addons after upgrading if an earlier explicit addon install omitted their skills; broader addon fixes for other adapters are not claimed by this change.

Ralph external health and recovery

Ralph external workers now have separate observation, activity, progress and heartbeat clocks. Keepalives, repeated errors, CPU spin and unrelated output do not count as progress. Status can report one worker or all runs, including threshold origins, progress ages, coverage, breaker scope and remaining time. Default status is read-only; watch requires a finite deadline, and observation writes require the explicit observe mode.

Process identity is pinned at launch and signal authority requires verified ownership. Fast exits and delayed transport status no longer lose the actual delivered signal. Grok's legacy observer now follows its ACP terminal/error grammar, and bounded replay history detects rotating progress-key churn. A quiet worker calls for diagnosis; a no-progress stop requires the stall window and grace period, and only its owner can stop it. Lost observation remains unknown. Grok grammar alignment is documentation-backed; live capture remains outstanding.

Mission codecs also define how health maps to lease reconciliation: stale finals cannot settle a newer generation, and expiry alone does not prove a worker stopped. This is a tested contract mapping, not a newly wired managed scheduler. Existing legacy Ralph status remains unchanged; use the worker status/watch options when supervising direct runs.

MCP profiles, filters and credentials

`AIWG_CONFIG_LAYERS` combines organisation defaults with identity overlays, lowest precedence first, writing only to the final directory. Profiles can `extend` other profiles across layers. Imports validate the complete graph; cycles, missing bases and removal of a still-required base are refused. Empty profiles now inject zero servers. Removing an override cannot silently restore a lower entry's worker qualification.

Tool filters now reach provider configuration instead of only appearing in profile displays. Claude receives deny rules, Codex enabled/disabled tools, OpenCode its tool map, and Factory, Windsurf and Antigravity disabled-tool lists. Unsupported filters warn; Claude `toolAllow` is refused because its allow rules pre-approve tools rather than enforce a restrictive allowlist. Managed Claude deny rules track ownership across profile changes while preserving manual edits, and profile sessions load the permission sidecar.

Environment and header references render in supported provider syntax. Antigravity and Warp refuse references where interpolation is undocumented. OpenCode receives `environment`, and Codex respects `CODEX_HOME` for config, login, isolated sessions and hook translation. Codex runtime homes exclude global MCP servers and refuse malformed base TOML, so a profile cannot silently inherit unrelated servers.

Credential policy can require references or prohibit credential-bearing fields. The strictest lower-layer organisation policy is an enforced floor; an identity's personal default can still be changed for one invocation within that floor. Claude project servers now go to `.mcp.json`, user servers to `~/.claude.json`, and HTTP/SSE entries include their transport type.

Writes use destination checks, private modes where required, atomic replacement and rollback on reported multi-file failures. Project destinations, including explicit ephemeral output paths, refuse detected literal credentials in values, URLs and arguments. Displays redact those values. Providers without a private user destination refuse `--scope user` instead of writing a project file. References and empty env/header values remain usable; populated `auth`/`oauth` fields other than `type` are refused at project scope.

Re-inject affected profiles after upgrading, remove Claude allowlists or scope them to supported providers, and move project literals to supported references or a genuine user destination. See the Codex profile guide.

MCP artifact containment

Artifact reads, atomic writes and directory creation now pin the trusted project and store, resolve external locations per project, and reject caller-selected projects inside artifact trees. Linux uses verified procfs directory descriptors; macOS and Windows use static containment checks. Symlink and hard-link checks, bounded hashing and mode preservation protect ordinary artifact operations. Unavailable configured stores stay unavailable; location-pointer writes are refused.

These checks limit what a caller-supplied path can reach. They do not provide a sandbox against another local process concurrently moving or replacing the artifact tree. Failed writes can leave temporary files. Operators using external stores should keep those stores available and avoid concurrent tree relocation; no store migration is required.

Doctor and worker readiness

`aiwg doctor --probe-workers` reports installation, version, supported range, readiness and the reason a configured CLI is ineligible. With `--json`, stdout contains exactly one JSON document, including dispatch state and an explicit empty state. Disabled dispatch reports skipped probes. Model resolution now explains the disabled setting before reporting qualification failures.

Init and setup offer direct dispatch when multiple worker CLIs are detected, default to no, and remember a decline. Scripts can answer with `--worker-dispatch enable|decline`; regenerate, refresh and doctor provide consistent hints and generated context states the setting.

Doctor also checks the actual shipped MCP entrypoint, bounds workspace context walks, distinguishes skill containers from skills, avoids self-comparison in local artifact audits, and includes Grok Build in the context/memory firewall. These fixes make diagnostics useful on installed packages and large home trees. Use worker readiness before enabling dispatch; unknown doctor flags now fail, and doctor `--json` requires `--probe-workers`.

Headless CLI workflows and safer login

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. Timeout, signal and failed-spawn results are failures even when a late status appears clean. The synchronous helper guarantees termination of the direct child; it does not claim to terminate every descendant.

Session prompts, config path lookup, init/setup choices and contributor conflict handling have explicit unattended inputs. `aiwg session --prompt` or `--prompt-file` uses documented headless transports for Claude, Codex, DeepSeek Harness and OpenCode, keeping prompt content off child argv. Unsupported providers refuse before preflight or launch. `aiwg config edit --print-path` returns the config path without an editor. Init accepts providers, default and custom script choices, repeatable scripts and the dispatch choice; setup honours supplied values without asking again.

Setup-run preflights its selected steps before execution. Parameter-complete ask/interactive steps can run headless; unresolved inputs, parameterless ask steps and unsupported agentic/chain steps refuse. Recovery is preflighted only when a failure selects it, and recovery cycles fail validation. Unattended setup writes require `--yes` or a dry run. Contributor conflict resolution accepts `--on-conflict 1-4`; choosing an editor still requires a terminal.

Codex profile login accepts one of `--api-key-stdin`, `--api-key-file` or `--api-key-env`, with interactive OAuth still available at a terminal. File input must be a private, owned, regular, singly linked file. Keys reach Codex through stdin; startup and child-process diagnostics no longer expose them. Broken stdin and early child exits return ordinary failure results. Scripts should supply required inputs explicitly and consult the login input guidance when choosing a credential source.

Decision engine and Jev visibility

Every completed `aiwg decision ask` call, including fallback and unconfigured outcomes, records a redacted local ledger entry. Questions/context are hashed; `--record-text` additionally stores bounded, redacted text. Recording is bounded and cannot change the decision result. `history` and `stats` read offline, report skipped invalid records, and group by provider, session, kind or caller. Exact caller, trailing-wildcard prefix and missing-caller filters make adoption measurable per workflow checkpoint.

Address-issues, Mission and direct-handoff guidance now tag worker/model/effort selection, failure triage and applicable review follow-ups. Jev-first decisions still fall back to the prior decision path when unavailable. Response parsing uses structural bounds instead of load-sensitive wall-clock limits, entry admission uses per-thread CPU time, and the D17-MF study reproduces its D17 calibrator from the sealed source checkout.

Try `aiwg decision stats --group-by caller` to see where offload is used. The ledger has no built-in retention; plan local rotation if needed. Caller and session identifiers are validated, and history/stats reject unknown flags and positional arguments.

Session discovery and interchange

Grok Bot desktop discovery reads transcript replicas from an explicitly chosen cache root, imports truncated windows as provisional, and adds only new entries on re-import. Muse discovery handles logs beyond 100 records and newer runtime mode records, with bounded inspection receipts. Pi v3 imports work again and stay scoped to the current workspace's session directory.

Collection now compares an explicit expected-provider set with adapter support, authorization, source scope and runtime alignment. Missing adapters, export requirements, incomplete scope and stale runtimes remain visible instead of producing a misleading complete result. No automatic runtime upgrade follows.

Interchange errors identify the failing header or source identity; imports name the catalog workspace and warn about mismatches. Listing exposes counts for other workspaces hidden by the current scope, and show accepts native session IDs and unique prefixes while reporting ambiguity. Grok list/search/export find binaries under `GROK_HOME/bin` and distinguish missing binaries, timeouts and non-zero exits. Supply the expected providers when claiming complete collection, and review workspace selection when importing elsewhere.

Memory and text fidelity

Concurrent line-memory additions now wait up to 30 seconds for a live project lock, preventing valid additions from exhausting short retries under load. Structural session labels accept CRLF and Unicode-normalized case variants while retaining exact evidence offsets. Writing-fidelity checks include unpunctuated spans ending at a newline; Logseq removes final-line block IDs and preserves body lines after empty property values.

Linear scans replace expensive regular expressions in these external-text paths without changing ordinary output. Large decision-interop log values above 65,536 UTF-16 code units are redacted in full. These changes improve memory ingestion and review reliability without requiring content migration.

Cockpit bridge

The bridge escapes HTML attributes and renders role badges and session options as safe text. Executor requests are restricted to the operator-configured origin and refuse redirects; request data and AgentCards cannot add an outbound destination. Public errors expose safe projections, with validated inventory codes and retry metadata retained. Upstream diagnostics are bounded and redacted, and workspace-status returns a fixed error instead of exception text.

This protects both the browser surface and executor boundary. Operators whose executor endpoint redirects should configure the intended origin directly.

Security sweep and vision-template migration

The CodeQL sweep replaces shell-string interpolation with separate arguments across hooks, Git/GitHub callers, tmux, remote topology, disk checks and runtime tools. Follow-ups retain Windows npm shims, editor quoting, executable resolution and symlinked script entrypoints while rejecting Git push options supplied as operands. Edge-channel clone paths must be absolute.

Configuration rejects prototype-polluting nested keys and dotted paths, follows own properties, and refuses to overwrite unreadable or malformed config. OPA projection rejects `__proto__` pointer segments while preserving ordinary `constructor`/`prototype` data. Generated JavaScript tests, OpenClaw comments, TOML hooks/MCP entries and YAML metadata encode values correctly. Skill platform restrictions are parsed as YAML, including scalar restrictions and comments; malformed restrictions fail closed and YAML boolean words are quoted. Vault provisioning now warns when TLS verification is disabled.

AIWG_VISION_COMMAND — behaviour change

Custom `vision-extract` templates using `AIWG_VISION_COMMAND` or `--command` need review. Unquoted, unescaped `{image}`, `{prompt_file}` and `{out}` map to `"$1"`, `"$2"` and `"$3"`; paths arrive as separate shell arguments. For example, replace a template that quoted the old placeholders with positional arguments:

# Before: quoted placeholders are now rejected with an error.
export AIWG_VISION_COMMAND='vision-tool --image "{image}" --prompt-file "{prompt_file}" --out "{out}"'
# After: the shell receives each path as a separate argument.
export AIWG_VISION_COMMAND='vision-tool --image "$1" --prompt-file "$2" --out "$3"'

Only those three positional parameters and `AIWG_VISION_IMAGE`, `AIWG_VISION_PROMPT_FILE`, `AIWG_VISION_OUT` may expand, including braced forms. Other dollar expansions are rejected; dollars inside single quotes are literal. Command substitution, backticks, `eval`, nested shells with short `-c` option clusters, here-documents/here-strings, comments outside single quotes, backslash-newline continuations and templates over 4096 characters are refused. Move complex logic into a trusted wrapper script. Templates remain executable code and must not re-parse path values as shell source.

Documentation and discoverability

New multi-project guidance explains workspace boundaries, shared configuration and how to work across projects. The README now features decision support and corrected provider lists; decision and session documentation joins the site, page descriptions improve navigation, and broken internal links and stale manifest entries are repaired. The September report was prepared for scheduled publication and rewritten as connected prose. npm keywords now cover decision support, session search and newer providers.

These updates make existing capabilities easier to find and apply. Start with the updated guides when configuring multiple projects or evaluating direct workers; no documentation migration is required.

Reliability & internals

The release removes load-dependent test failures in launchers, transport, held-out collectors and cockpit deadlines. Pi timeout fixtures publish receipts only after writes finish; executable fixtures avoid writable-descriptor races and report broken-pipe child status. CLI startup checks use CPU time, session export failures report step timing, and stalled CI suites name the files still running. Temporary directories, provider homes and TLS settings are isolated or restored, and test subprocesses avoid shell interpolation.

Nine formerly manual scenarios now run in the CI-safe stub UAT lane. Worker readiness fixtures, provider profile pack fragments, dispatch-gate pinning, worker vocabulary/contract fixtures and orchestration conformance gates expand coverage. Process-group hang guards clean up descendants on timeout and normal exit. Installed-package checks cover shipped imports; qualification and benchmark tooling is excluded from npm payloads.

Dependency resolutions address the security-advisory sweep across the MCP SDK, droid-bridge and transitive HTTP, URI, address and glob packages within declared ranges. Upgrade installed packages and deployed plugin copies to receive those fixes. These internal changes improve delivery reliability without a new workflow to configure.

Upgrade notes / behaviour changes

• Refresh deployed hooks and addons: update the agent-loop `ralph-commit`

hook and affected provider addon copies as well as the package. Review custom vision templates using the migration above.

• Direct workers are opt-in: review group policy, qualification, resource

limits and account quotas. Unknown/unsupported contracts and unsafe finals refuse; cancellation retains capacity until stop proof. Project `defaults.*` model edits belong in `models.json`, not `aiwg config set`.

• Headless inputs and flags: missing inputs now refuse before launch;

malformed/repeated value flags are validated, empty prompt/login-env/dispatch values refuse, and `--` ends option recognition. Use `--flag=--literal` for a value beginning with `--`. Session flags keep last-occurrence precedence; other touched commands keep first-occurrence precedence. Doctor JSON requires worker probing; doctor and decision history/stats reject unknown arguments.

• Deadlines and setup: timeouts/failed spawns now fail. Long synchronous

bounds use `AIWG_SYNC_LONG_TIMEOUT_MS` (its explicit `0` override disables the long bound); an individual zero timeout cannot disable a bound. Supply setup inputs and `--yes` for unattended writes; selected steps and selected recovery preflight separately, and recovery cycles refuse. Editor choices still need a terminal.

• Login and runtime homes: choose exactly one Codex API-key input mode for

headless login, meet private-file checks, and review `CODEX_HOME` when using custom locations. Profile sessions discard global MCP server definitions and refuse malformed base TOML or policy violations before launch.

• MCP destinations and filters: re-inject Claude servers into `.mcp.json`;

remove or re-scope Claude allowlists. Unsupported references refuse, unsupported filters warn, and Codex warns when a per-server allowlist leaves other servers unrestricted. Empty profiles inject no servers; dependent bases cannot be removed. OpenCode now receives `environment`.

• MCP policy and storage: project destinations refuse detected literals,

including explicit ephemeral output; populated auth/OAuth fields are more restrictive. Use supported references or a true private destination. Organisation floors cannot be relaxed by an overlay; personal defaults can. Layer paths must not overlap or use symlinked descendants; Windows current-drive-relative layer paths refuse. Private/atomic writes and stricter malformed-config checks apply.

• Artifact and worker bounds: linked/unsafe artifact paths and unavailable

stores refuse; worker frames/files and tree hashing are bounded. Concurrent local tree mutation remains outside containment guarantees. Cockpit executor redirects now refuse.

• Provider deployment and cleanup: Grok Bot user-root writes require user

scope, provider lists are stored as arrays, and shared Claude detection no longer relies on API-key presence. Cleanup preserves operator-owned settings and merged configuration rather than deleting whole directories.

• Session completeness: provide expected-provider scope; incomplete adapters,

authorization or runtime alignment prevent a complete result. Pi discovery is workspace-scoped, Grok Bot truncated imports are provisional, and cross-workspace imports report their catalog destination. Worker health distinguishes quiet, replayed progress and unknown ownership from confirmed failure.

• Decision records: completed calls now create a redacted local ledger with

no automatic retention; text storage is opt-in. Session/caller tags are validated. D17-MF reproduction needs the sealed D17 source checkout.

• Parsing and configuration: malformed platform restrictions and config files

now refuse, protected config keys and OPA pointer segments reject, generator inputs are validated, oversized log values redact fully, and edge paths must be absolute. Line-memory waits longer under lock contention; Vault TLS opt-outs emit a warning.

Try it

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

After updating, refresh deployed components using your normal deployment workflow. Follow the direct dispatch setup guide to review configuration before enabling workers. The full change history is in the changelog.