Enforced worker delivery

Use the agent-owned ralph-external operation for Tier 0 runs whose deliverables must contain only verifier-accepted bytes.

Enforced worker delivery

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

First time using AIWG? Begin with Install, Connect, and Verify.

Use the agent-owned ralph-external operation for Tier 0 runs whose deliverables must contain only verifier-accepted bytes. The operator starts the existing MCP server outside the conductor unit. No additional daemon or socket service is needed.

The host must enforce systemd user-unit namespaces. On affected Ubuntu hosts, #4128's systemd-executor AppArmor configuration is required. The live isolation probe must report enforced write confinement, home-read isolation and tmp isolation; otherwise launch fails with `ISOLATION_UNAVAILABLE`, with no degraded override. Verification additionally requires network isolation for protected checks.

Create a dedicated deliverable directory before launch. Protect that directory, so renames, newly created files and editor writes are covered together. Each grant must be an existing canonical absolute path without systemd path metacharacters. The conductor root and repeatable the bind option directories get `BindPaths=` and `ReadWritePaths=`; `ReadWritePaths=` alone cannot reveal paths hidden by `ProtectHome=tmpfs` or `PrivateTmp=yes` (#4130). Each repeatable the deliverable option gets `ReadOnlyPaths=`. Use repeatable `the bind-ro option ABS_DIR` for CLI installation directories and the AIWG build: these get `BindReadOnlyPaths=` and remain readable without becoming writable. Writable grants cannot equal or sit inside a read-only bind. Network remains enabled for APIs and localhost MCP.

The launcher loads the conductor root's existing model and parallelism data policy, including inherited `localOnlyPaths`, and adds `InaccessiblePaths=` for each existing declared file or directory under that root. These paths are hidden from shell commands as well as native reads. MCP `worker-invoke` also refuses a prepared tree containing a declared path unless the selected tuple has qualified local processing facts; the refusal names paths with `LOCAL_ONLY_PATH_EXPOSED` without reading contents.

The confined unit is named `aiwg-conductor-<pid>-<time>`. When `systemd-run` returns for any reason, including a SIGTERM, SIGINT or SIGHUP sent to the wrapper's process group, the wrapper stops that unit from outside, so a supervisor's timeout cannot leave the conductor running. Add `the max-runtime-seconds option N` (`RuntimeMaxSec=`) as a hard cap that holds even if the wrapper itself is killed with SIGKILL.

Pass real paths for every grant. When `$HOME` or an install directory is a symlink from `/home` to `/srv`, resolve it with `realpath` in the operator shell and pass the resulting `/srv/...` path; symlink spellings are refused.

Use AIWG to complete this documented outcome: Pass real paths for every grant. When $HOME or an install directory is a symlink from /home to /srv, resolve it with realpath in the operator shell and pass the resulting /srv/... path; symlink spellings are refused.
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The HTTP listener requires bearer authentication and rejects non-localhost binds when `workers` is enabled, even with the allow-remote-bind option. Its workers exposure is `worker-invoke` (including its `status` operation) and `worker-verify-deliver`. `artifact-write` is disabled for that listener to prevent an alternate publication route. The conductor unit hides `/run/user` and `/run/dbus`, clears manager connection environment variables, and asserts the user-manager bus is unreachable before executing the conductor. Never grant manager sockets through another path.

Inside the unit, call `worker-invoke` with `operation: "run"` and the bounded brief's `role`, `task`, `group`, `brief`, `workdir`, `final_output`, `request_id` and selected worker `transport` (normally `"shell"` for a CLI worker). Preflight the tuple with the agent-owned models operation; `the transport option mcp` selects an MCP-server worker and is refused for native-sandbox groups. The tool resolves the selection on the external server before launch. Keep the MCP session ID for subsequent `worker-invoke` calls with `operation: "status"` and `invocation_id` set to the returned `invocationId`. Native shell workers return an absolute `run_dir` in the run response and status. Always supply `run_dir` for shell workers. It selects the owned-capture path, where the launcher records the exit status and final output. Without it, a systemd worker's clean exit cannot be observed (systemd collects units that exit successfully): the run ends `OG_WORKER_EXIT_UNOBSERVED` with the worker tree retained. Pass it unchanged to `worker-verify-deliver` after confirmed termination. Optionally choose an absolute `run_dir` in the served project when invoking the worker; its parent must exist and the directory must be absent or empty, private and owned. The launcher refuses run metadata inside any qualified worker-writable root. The server must remain outside the unit: it launches workers with their selected native sandbox or systemd isolation. Launching a worker CLI or the launch-worker option inside the conductor unit nests sandboxes and cannot reach the hidden user-manager bus. The unit sets `AIWG_CONFINED_CONDUCTOR=1`, and the launch-worker option refuses there with `OG_CONFINED_LAUNCH_REFUSED` before any worker starts; this guards against mistakes and is not a security boundary. The served project must contain the brief, prepared worker worktree and final output path. Worker context deployment selects only that worker's provider, uses project scope and keeps deploy-time state in the worker tree; an already present provider bootstrap skips deployment.

Call `worker-verify-deliver` with `run_dir`, `deliverable_path`, explicit `artifact_path`, and a nonempty `checks` array. Each check has a unique `id`, an absolute `command`, and optional `args`, `cwd`, `envNames`, `timeoutMs`. These checks belong to conductor policy; worker claims and manifests never define them. Derive them from the task's done criteria: each stated requirement, including edge and rejection cases, needs a check that fails if it is missed. The worker's own tests alone are not enough, because they share the worker's reading of the task. All artifact/run/destination paths are constrained to the served project root. Use existing launcher-owned run records and confirmed-stop evidence. Workers must have independently qualified writable roots; deliverables must be outside those roots. Workers launched by the external server use their normal worker isolation; the confinement wrapper does not change their sandbox policy.

Publication has three requirements, enforced before any protected check runs:

  • Name the actual deliverable with `artifact_path` (CLI: the artifact option). The worker

final or handoff wrapper cannot be published, even when named explicitly or through another path (`ARTIFACT_REQUIRED`). Verification without publication may still default to the worker final.

  • The artifact must already exist at the worker's confirmed exit. Launcher

`exit.json` must contain an ISO `endedAt` (`EXIT_EVIDENCE_MISSING`). Neither the artifact's change time nor modification time may exceed that timestamp by more than two seconds. If the worker final claims a digest for the chosen artifact, its bytes must match (`ARTIFACT_CHANGED_AFTER_EXIT`).

  • Include at least one content check referencing the artifact path, basename,

or a containing directory in its arguments (`CHECKS_CONTENT_FREE`). The narrow filter treats `test`, `[`, `stat`, `ls`, `true`, `file`, and `wc` with only path/flag arguments as content-free. A check whose arguments mention none of those artifact references is also content-free. Node, jq, or Python checks that inspect artifact contents can qualify. This filter cannot prove that a check asserts the task's done criteria; the conductor still owns that.

Native shell launches and shell calls supplying `run_dir` use the same one-shot launcher and capture owner as the launch-worker option: `invocation.json`, `.launch-owner`, kernel termination records, final evidence and sealed captures belong to that owner. Status and worker claims are observations; the verifier independently authenticates the returned run. The probe below launches a fake CLI through MCP, lets it create the artifact in its own tree, then passes that launch's returned `run_dir` to MCP verification and delivery.

Only `accepted` results publish. The verifier reopens the source and checks the bytes against `artifactDigest` immediately before atomic publication. Blocked, rejected or changed artifacts leave the destination untouched. A signed effect intent precedes publication; a completed delivery record follows and includes the digest, destination, verifier ID, run directory and invocation ID.

Use AIWG to complete this documented outcome: Only accepted results publish. The verifier reopens the source and checks the bytes against artifactDigest immediately before atomic publication. Blocked, rejected or changed artifacts leave the destination untouched. A signed effect intent
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Run the helper from the same served project directory. It exits zero only when the current digest matches a completed, signature-checked delivery record. Missing records and later edits are unverified. A crash or ledger failure after rename can leave delivered bytes without a completed receipt; the helper reports them unverified. Installed CLI/server code, ledger configuration, signing keys and ledger storage must remain outside conductor-writable grants (use an external artifact root when necessary). The ledger proves recorded delivery, not that the checks were sufficient.

Publishing a typed stop

When policy or transport selection requires stopping before any worker launch, call the same `worker-verify-deliver` tool with this alternative request:

{
  "deliverable_path": "/absolute/project/control/deliver/answer.json",
  "typed_stop": {
    "status": "blocked",
    "code": "NO_ELIGIBLE_FALLBACK",
    "blocking_rule": "No eligible worker satisfies the required local transport policy.",
    "launch_count": 0
  }
}

Use `denied` or `blocked`, an uppercase code matching `[A-Z][A-Z0-9_]{2,63}`, and a nonempty `blocking_rule` of at most 2000 characters. Optional `reason` and `uncertainty_statement` strings allow at most 4000 characters each. Do not include `run_dir`, `artifact_path`, or `checks`; invalid or mixed requests are refused with `TYPED_STOP_INVALID`.

The external server publishes only the validated stop object as sorted-key JSON with a trailing newline, outside configured worker-writable roots, using an atomic rename. A prior delivery record for the destination (including an unfinished intent) refuses the stop, even if the file changed or disappeared. A typed stop also prevents later worker publication to that destination. The signed receipt has `kind: "typed-stop"`, verifier `typed-stop@1`, and no worker invocation ID. The delivery-status command above reports `verified: true` and `kind: "typed-stop"` only while the published bytes match that completed receipt. Its verification confirms publication of the refusal; it does not establish the policy claim independently.

Confinement covers declared paths, not other conductor behavior, remote effects, or unprotected output. An operator or another host process can still alter files. File-only bind mounts may retain the old inode after server replacement: protect the containing deliverable directory to see published replacements. The optional `AIWG_LIVE_CONDUCTOR_PROBE=1 node tools/testing/probe-conductor.mjs` uses synthetic files, `/bin/sh`, a fake worker CLI exercising native bwrap, and local MCP; it checks read-only binds and that the worker runs outside the conductor's cgroup. It skips hosts without enforced namespaces. No model CLI or paid API call is involved. #2918 direct-02/direct-19 reruns on noodle remain an operator acceptance step before the 40-row study.