Skill Tracer
Skills › Compound Engineering › ce-work › cross-model-execution.md

cross-model-execution.md

191 lines · skills/ce-work/references/cross-model-execution.md at 3449230

Open on GitHub

Most marks come from matching words in the file, so treat them as pointers.

1# Cross-Model Execution Contract
2
3Read this reference only when `references/execution-engines.md` finds an applicable external route, or when you are recovering an existing external run. It defines how the host picks one fixed route, what authority the external worker gets, when native fallback is allowed, how requested and actual identity are kept apart, what the run record must contain, and how one unit moves through the controller one transaction at a time. The host drives the bundled controller, detached runner, and adapter; no worker response or process exit can substitute for controller and Git evidence.
4
5When this file records that the run leaves the host, that record is the egress: sending repository content, or the authority to change it, to an external process. When this file records a receipt, that is a fact the controller wrote, not something the worker or the host inferred.
6

Cross-Model Execution Contract

Read this reference only when references/execution-engines.md finds an applicable external route, or when you are recovering an existing external run. It defines how the host picks one fixed route, what authority the external worker gets, when native fallback is allowed, how requested and actual identity are kept apart, what the run record must contain, and how one unit moves through the controller one transaction at a time. The host drives the bundled controller, detached runner, and adapter; no worker response or process exit can substitute for controller and Git evidence.

When this file records that the run leaves the host, that record is the egress: sending repository content, or the authority to change it, to an external process. When this file records a receipt, that is a fact the controller wrote, not something the worker or the host inferred.

Raw lines 1 to 6
7## Interpret route intent and standing configuration
8
9`references/execution-engines.md` decides whether an external route applies and which source has authority. This section turns that source into ordered candidates.
11A live request such as "use Codex" is preference-strength by default. Interpret unambiguous strict intent such as "must use Codex" or "only use Codex" as requirement-strength; intent is the contract, not any single keyword. The resolved mode is `prefer` or `require`. Requirement strength fixes the requested external identity while that route is viable; it never authorizes another external recipient and does not turn route unavailability into a blocker.
13Live or contextual intent may name one route or an ordered fallback list (for example, "prefer Cursor with Grok, then Codex"). Preserve that order and normalize each harness/model candidate with the same rules as standing configuration. A typed caller binding remains a single already-selected candidate; do not widen its exact four-field grammar into a list.
15Standing configuration uses one mode plus an ordered route list. Resolve `work_engine_mode` and `work_engine_preferences` independently from the two repo files (`config.local.yaml` then `config.yaml`); a present local list, including `[]`, replaces the team list. Do not pick one file for the whole group.
17```yaml
18work_engine_mode: prefer
19work_engine_preferences:
20 - harness: cursor
21 model: composer
22 - harness: codex
23 model: gpt-6.1-sol
24 - harness: claude
25work_engine_effort:
26 codex: xhigh
27 claude: max
28```
30- `work_engine_mode`: `off | prefer | require`
31- `work_engine_preferences`: one or more ordered candidate objects
32- `harness`: `codex | claude | grok | cursor | opencode | antigravity`
33- optional `model`: a model id or family understood by that harness; omission means its configured default
34- optional `work_engine_effort`: a map from harness to the reasoning effort its external worker runs at, written in that harness's own levels (Antigravity takes `low | medium | high`); a harness left out keeps its default
36Do not put CLI commands or flags in configuration. The list expresses implementation intent; the skill's adapter recipes and local inspection determine how to invoke it. Composer is therefore `{ harness: cursor, model: composer }`, while `{ harness: cursor }` means Cursor's configured default.
38Normalize a qualified candidate to the controller's fixed route: Codex -> `codex`, Claude -> `claude`, native Grok -> `grok-cli`, Cursor with no model -> `cursor`, a Composer-family Cursor model -> `composer`, a Grok-family Cursor model -> `grok-cursor`, another explicit Cursor model -> `cursor` with that controller-authorized model selector, OpenCode -> `opencode`, and Antigravity -> `antigravity`. A model selector is data, never shell syntax; if it cannot be represented by the fixed adapter's safe model token, the candidate is unavailable. A Cursor model selector is one of Cursor's own model ids, which may end in a bracketed preset such as `grok-4.7[context=256k,reasoning_effort=high,fast=true]`; record that id as the requested model, since Cursor routes take no separate effort. With no model pin, `grok-cursor` requests that high/fast Grok preset and `composer` requests `composer-2.5[fast=true]`. The `antigravity` route runs only `gemini-*` models, because Antigravity also serves other vendors' models. An Antigravity candidate with no model becomes two exact candidates in this order: `gemini-4-argon`, then `gemini-3.8-flash`. Accounts differ in which Gemini models they offer, and once `init` records a model the run cannot change it, so the preflight model check below settles which one runs. A configured Antigravity model stays exact like any other pin.
40`work_engine_effort` resolves on its own under the same two-file rule, and a present local map replaces the team map. It requests an effort for every candidate of that harness, including a candidate a caller binding or live intent selected, and it applies whatever `work_engine_mode` says. A candidate that cannot run at the effort requested for it is unavailable before any work is sent, the same as any other unavailable candidate, and nothing runs at a different effort than the one requested. The adapter script owns which levels each route accepts; ask it at preflight rather than judging the value yourself. A candidate that collapses to native execution runs at the session's own effort, so say that the configured effort was not applied. A value that is not a harness map requests nothing: say once that it was ignored and continue with each route's default.
42An enabled mode without a valid candidate list is unavailable rather than guessed. When the list is exhausted, both `prefer` and `require` disclose every attempted route and reason once, then continue natively on the current harness and session model. A required route is never replaced by another unrequested external recipient. Standing configuration supplies defaults, not permission to change recipient or broaden authority.

Interpret route intent and standing configuration

references/execution-engines.md decides whether an external route applies and which source has authority. This section turns that source into ordered candidates.

A live request such as "use Codex" is preference-strength by default. Interpret unambiguous strict intent such as "must use Codex" or "only use Codex" as requirement-strength; intent is the contract, not any single keyword. The resolved mode is prefer or require. Requirement strength fixes the requested external identity while that route is viable; it never authorizes another external recipient and does not turn route unavailability into a blocker.

Live or contextual intent may name one route or an ordered fallback list (for example, "prefer Cursor with Grok, then Codex"). Preserve that order and normalize each harness/model candidate with the same rules as standing configuration. A typed caller binding remains a single already-selected candidate; do not widen its exact four-field grammar into a list.

Standing configuration uses one mode plus an ordered route list. Resolve work_engine_mode and work_engine_preferences independently from the two repo files (config.local.yaml then config.yaml); a present local list, including [], replaces the team list. Do not pick one file for the whole group.

work_engine_mode: prefer
work_engine_preferences:
  - harness: cursor
    model: composer
  - harness: codex
    model: gpt-6.1-sol
  - harness: claude
work_engine_effort:
  codex: xhigh
  claude: max
  • work_engine_mode: off | prefer | require
  • work_engine_preferences: one or more ordered candidate objects
  • harness: codex | claude | grok | cursor | opencode | antigravity
  • optional model: a model id or family understood by that harness; omission means its configured default
  • optional work_engine_effort: a map from harness to the reasoning effort its external worker runs at, written in that harness's own levels (Antigravity takes low | medium | high); a harness left out keeps its default

Do not put CLI commands or flags in configuration. The list expresses implementation intent; the skill's adapter recipes and local inspection determine how to invoke it. Composer is therefore { harness: cursor, model: composer }, while { harness: cursor } means Cursor's configured default.

Normalize a qualified candidate to the controller's fixed route: Codex -> codex, Claude -> claude, native Grok -> grok-cli, Cursor with no model -> cursor, a Composer-family Cursor model -> composer, a Grok-family Cursor model -> grok-cursor, another explicit Cursor model -> cursor with that controller-authorized model selector, OpenCode -> opencode, and Antigravity -> antigravity. A model selector is data, never shell syntax; if it cannot be represented by the fixed adapter's safe model token, the candidate is unavailable. A Cursor model selector is one of Cursor's own model ids, which may end in a bracketed preset such as grok-4.7[context=256k,reasoning_effort=high,fast=true]; record that id as the requested model, since Cursor routes take no separate effort. With no model pin, grok-cursor requests that high/fast Grok preset and composer requests composer-2.5[fast=true]. The antigravity route runs only gemini-* models, because Antigravity also serves other vendors' models. An Antigravity candidate with no model becomes two exact candidates in this order: gemini-4-argon, then gemini-3.8-flash. Accounts differ in which Gemini models they offer, and once init records a model the run cannot change it, so the preflight model check below settles which one runs. A configured Antigravity model stays exact like any other pin.

work_engine_effort resolves on its own under the same two-file rule, and a present local map replaces the team map. It requests an effort for every candidate of that harness, including a candidate a caller binding or live intent selected, and it applies whatever work_engine_mode says. A candidate that cannot run at the effort requested for it is unavailable before any work is sent, the same as any other unavailable candidate, and nothing runs at a different effort than the one requested. The adapter script owns which levels each route accepts; ask it at preflight rather than judging the value yourself. A candidate that collapses to native execution runs at the session's own effort, so say that the configured effort was not applied. A value that is not a harness map requests nothing: say once that it was ignored and continue with each route's default.

An enabled mode without a valid candidate list is unavailable rather than guessed. When the list is exhausted, both prefer and require disclose every attempted route and reason once, then continue natively on the current harness and session model. A required route is never replaced by another unrequested external recipient. Standing configuration supplies defaults, not permission to change recipient or broaden authority.

Raw lines 7 to 43
44## Resolve one requested route
46Use only these targets: `codex`, `claude`, `grok`, `cursor`, `composer`, `opencode`, and `antigravity`. Keep five identity facts separate in every disclosure and receipt: target, harness/intermediary route, requested model, actual model, and receipt status.
48**Fixed controller route tokens:** record exactly `codex`, `claude`, `grok-cli`, `cursor`, `composer`, `grok-cursor`, `opencode`, or `antigravity` in the egress record the controller stores. `grok-cli` maps target `grok` to its native harness; `grok-cursor` maps target `grok` through intermediary `cursor`. These controller tokens are exact values, not descriptive labels.
50- `cursor` means the Cursor harness with its configured default model.
51- `composer` means a Composer-family model through Cursor.
52- `grok` prefers its fixed native route; a Grok model through Cursor is a different intermediary and must be separately permitted and recorded.
54When a standing preference lists candidates in order, preflight them in that order without sending anything out. Skip a candidate only when its harness and requested/default model are equivalent to the current host, or when observed evidence shows it is unavailable. An explicit different model in the same harness is still a distinct candidate. After skipping a candidate, record why and continue to the next candidate. Attempt the documented adapter recipe first. Local CLI help or version information may refine a compatible mapping, but only inside the same sanctioned harness/model family and only if the fixed adapter still enforces every restriction. An explicit model pin cannot become another model. When `work_engine_effort` requests an effort for the candidate's harness, preflight also asks the adapter whether that route can run at it. The effort is data, never shell syntax, the same as a model selector: only a plain token that starts with a letter or digit and continues with letters, digits, `-`, or `_` may appear in a command, and any other value makes the candidate unavailable without running anything. Ask with this skill's bundled script by its absolute path under the skill directory, because it is not on `PATH`: `CROSS_MODEL_EFFORT_OVERRIDE='<token>' "<skill-dir>/scripts/cross-model-work.sh" --emit-adapter <route>`. Exit 2 naming the effort means the route cannot run at it, and the candidate is unavailable with that reason. A script that cannot be found or run is a broken preflight to report, not evidence about the route. For each `antigravity` candidate, also run `"<skill-dir>/scripts/cross-model-work.sh" --check-model antigravity <model>` before `init`. It opens an Antigravity session for that model and sends no prompt. Exit 0 means the account offers the model. Exit 2 means the candidate is unavailable, with the reason on stderr (for example, the models the account does offer, or a missing Google sign-in); continue to the next candidate. The first qualified candidate becomes the one fixed recipient.
56Every route reaches its agent through a supported acpx version, run with `npx`, so each needs Node 22.13 or newer, `npx`, and `jq` besides its own agent CLI. When one is missing, npm cannot fetch acpx, an acpx config file replaces the route's agent launch, or the agent rejects the model before the prompt, the adapter sends nothing and publishes an unavailable receipt whose reason starts `transport unavailable (pre-egress, `. Handle it like any other unavailable route.
58Before egress, you may keep moving down the list after a candidate is proven unavailable. After dispatch starts, the adapter receives one fixed recipient and must never switch recipients, providers, or intermediaries internally. A different recipient requires a separately resolved and recorded attempt, and only after the first attempt reaches an authoritative terminal or reaped state; it is never an in-flight fallback.
60Disclose any compatible model alias or substitution, and never relabel an unverified served model.
62If a target asks for the same-host default with no distinct serving route or model, collapse to native execution. Record the target as requested and native as actual; do not create an external job merely to call the current host's default model through itself.

Resolve one requested route

Use only these targets: codex, claude, grok, cursor, composer, opencode, and antigravity. Keep five identity facts separate in every disclosure and receipt: target, harness/intermediary route, requested model, actual model, and receipt status.

Fixed controller route tokens: record exactly codex, claude, grok-cli, cursor, composer, grok-cursor, opencode, or antigravity in the egress record the controller stores. grok-cli maps target grok to its native harness; grok-cursor maps target grok through intermediary cursor. These controller tokens are exact values, not descriptive labels.

  • cursor means the Cursor harness with its configured default model.
  • composer means a Composer-family model through Cursor.
  • grok prefers its fixed native route; a Grok model through Cursor is a different intermediary and must be separately permitted and recorded.

When a standing preference lists candidates in order, preflight them in that order without sending anything out. Skip a candidate only when its harness and requested/default model are equivalent to the current host, or when observed evidence shows it is unavailable. An explicit different model in the same harness is still a distinct candidate. After skipping a candidate, record why and continue to the next candidate. Attempt the documented adapter recipe first. Local CLI help or version information may refine a compatible mapping, but only inside the same sanctioned harness/model family and only if the fixed adapter still enforces every restriction. An explicit model pin cannot become another model. When work_engine_effort requests an effort for the candidate's harness, preflight also asks the adapter whether that route can run at it. The effort is data, never shell syntax, the same as a model selector: only a plain token that starts with a letter or digit and continues with letters, digits, -, or _ may appear in a command, and any other value makes the candidate unavailable without running anything. Ask with this skill's bundled script by its absolute path under the skill directory, because it is not on PATH: CROSS_MODEL_EFFORT_OVERRIDE='<token>' "<skill-dir>/scripts/cross-model-work.sh" --emit-adapter <route>. Exit 2 naming the effort means the route cannot run at it, and the candidate is unavailable with that reason. A script that cannot be found or run is a broken preflight to report, not evidence about the route. For each antigravity candidate, also run "<skill-dir>/scripts/cross-model-work.sh" --check-model antigravity <model> before init. It opens an Antigravity session for that model and sends no prompt. Exit 0 means the account offers the model. Exit 2 means the candidate is unavailable, with the reason on stderr (for example, the models the account does offer, or a missing Google sign-in); continue to the next candidate. The first qualified candidate becomes the one fixed recipient.

Every route reaches its agent through a supported acpx version, run with npx, so each needs Node 22.13 or newer, npx, and jq besides its own agent CLI. When one is missing, npm cannot fetch acpx, an acpx config file replaces the route's agent launch, or the agent rejects the model before the prompt, the adapter sends nothing and publishes an unavailable receipt whose reason starts transport unavailable (pre-egress, . Handle it like any other unavailable route.

Before egress, you may keep moving down the list after a candidate is proven unavailable. After dispatch starts, the adapter receives one fixed recipient and must never switch recipients, providers, or intermediaries internally. A different recipient requires a separately resolved and recorded attempt, and only after the first attempt reaches an authoritative terminal or reaped state; it is never an in-flight fallback.

Disclose any compatible model alias or substitution, and never relabel an unverified served model.

If a target asks for the same-host default with no distinct serving route or model, collapse to native execution. Record the target as requested and native as actual; do not create an external job merely to call the current host's default model through itself.

Raw lines 44 to 63
Runs code scripts/cross-model-work.sh :54
Starts an agent dispatch :58
64## Apply preference or requirement strength
66Cross-model implementation routes are write- and shell-capable. Never request broader host permissions merely to make one reachable. If the current host boundary makes a route unavailable, apply the native fallback for its resolved mode instead of escaping that boundary.
68**Preference-strength (`prefer`):** attempt the fixed route in both direct and automatic workflows. If preflight proves it unavailable, continue with native execution and prominently report requested versus actual route/model plus the observed `fallback_reason`.
70**Requirement-strength (`require`):** keep the requested external identity fixed while the route is viable. If preflight proves it unavailable, disclose the reason once and continue on the current harness and session model without prompting, erroring, elevating the host boundary, or substituting another external recipient. A started attempt is not preflight-unavailable: no fallback begins until it reaches an authoritative terminal or reaped state.

Apply preference or requirement strength

Cross-model implementation routes are write- and shell-capable. Never request broader host permissions merely to make one reachable. If the current host boundary makes a route unavailable, apply the native fallback for its resolved mode instead of escaping that boundary.

**Preference-strength (prefer):** attempt the fixed route in both direct and automatic workflows. If preflight proves it unavailable, continue with native execution and prominently report requested versus actual route/model plus the observed fallback_reason.

**Requirement-strength (require):** keep the requested external identity fixed while the route is viable. If preflight proves it unavailable, disclose the reason once and continue on the current harness and session model without prompting, erroring, elevating the host boundary, or substituting another external recipient. A started attempt is not preflight-unavailable: no fallback begins until it reaches an authoritative terminal or reaped state.

Raw lines 64 to 71
72## Sanction before egress
74Before repository content or bounded mutation authority leaves the host, disclose and durably record:
76- the binding `source` that authorizes external execution;
77- the fixed recipient, provider, harness route, and every intermediary;
78- the repository/unit material exposed, including the bounded source/unit packet, workspace content, and any cited local prototype artifacts the worker may read;
79- the caller restrictions and which are adapter-enforced versus cooperative; and
80- that linked worktree isolation contains accidental concurrent mutation but is not an OS security sandbox.
82Treat a required restriction the adapter cannot enforce as route unavailable; apply `prefer` or `require` instead of weakening it silently. This record is route-specific.
84No route currently confines the worker to its workspace, so every route records `restriction_posture: cooperative`, and a run that requires enforced confinement finds every route unavailable. The worker runs with every permission request approved, as the same OS user. What each route still limits, observed through acpx 0.19.4:
86| Route | Limits that hold |
87|---|---|
88| `codex` | Shell commands run in Codex's `workspace-write` sandbox: no network, `.git` read-only, no writes outside the workspace and temp dirs. Codex's own auto-review can still approve a file edit outside the workspace. |
89| `grok-cli` | File edits through acpx stay inside the workspace. Shell commands are unconfined. |
90| `claude` | None beyond the packet. It runs with `--safe-mode`, so the checkout's project settings and hooks do not apply. |
91| `cursor`, `composer`, `grok-cursor`, `opencode` | None beyond the packet. |
92| `antigravity` | None beyond the packet. It runs in Antigravity's `auto_edit` mode with a private settings home, so the user's own Antigravity or Gemini settings, skills, and API keys do not apply. |
94Any retry that changes a recipient or intermediary requires a newly resolved and recorded job.

Sanction before egress

Before repository content or bounded mutation authority leaves the host, disclose and durably record:

  • the binding source that authorizes external execution;
  • the fixed recipient, provider, harness route, and every intermediary;
  • the repository/unit material exposed, including the bounded source/unit packet, workspace content, and any cited local prototype artifacts the worker may read;
  • the caller restrictions and which are adapter-enforced versus cooperative; and
  • that linked worktree isolation contains accidental concurrent mutation but is not an OS security sandbox.

Treat a required restriction the adapter cannot enforce as route unavailable; apply prefer or require instead of weakening it silently. This record is route-specific.

No route currently confines the worker to its workspace, so every route records restriction_posture: cooperative, and a run that requires enforced confinement finds every route unavailable. The worker runs with every permission request approved, as the same OS user. What each route still limits, observed through acpx 0.19.4:

RouteLimits that hold
codexShell commands run in Codex's workspace-write sandbox: no network, .git read-only, no writes outside the workspace and temp dirs. Codex's own auto-review can still approve a file edit outside the workspace.
grok-cliFile edits through acpx stay inside the workspace. Shell commands are unconfined.
claudeNone beyond the packet. It runs with --safe-mode, so the checkout's project settings and hooks do not apply.
cursor, composer, grok-cursor, opencodeNone beyond the packet.
antigravityNone beyond the packet. It runs in Antigravity's auto_edit mode with a private settings home, so the user's own Antigravity or Gemini settings, skills, and API keys do not apply.

Any retry that changes a recipient or intermediary requires a newly resolved and recorded job.

Raw lines 72 to 95
96## Bound worker authority
98The worker receives one unit, one workspace, one fixed recipient, and only inherited authority. It may narrow scope or authority, never broaden either. Its packet grants no canonical commit, push, PR, shipping, recipient-switch, fallback, peer scheduling, or scope-expansion authority.
100An external worker may edit only inside its controller-owned detached worktree. Do not instruct it to run `git add`, `git commit`, or another Git index write. Leave the completed working tree uncommitted; the host snapshots the tree. Codex's `workspace-write` shell sandbox cannot write the linked-worktree Git admin dir, because the index lives in the shared Git common dir outside the workspace. Worker commits are never required. When the worker finishes, the controller turns the complete working tree into an isolated transport commit for the host to inspect. Only the host may apply output to the canonical checkout, run authoritative verification, create a host-only canonical commit, or continue into the shipping steps that follow implementation, whether `ce-work` runs those itself or returns them to a caller.
102A Codex `workspace-write` packet must also treat socket binds, OS permission checks, and peer-credential probes as host-owned. Preserve the host command and observed result; do not treat a sandbox `EPERM` as proof the host lacks the capability.
104Ordinary synchronous native units stay in the active checkout. Ordinary native subagent isolation remains harness-owned. Only the external cross-model controller may create detached sibling worktrees under its private run root; this exception does not authorize `ce-work` to create worktrees for native execution. An active checkout that is already a linked worktree does not disable this route: the controller registers another detached **sibling** through the shared Git common directory under `/tmp/compound-engineering-<effective-uid>/ce-work/<run-id>/`, never a nested worktree beneath the active checkout.

Bound worker authority

The worker receives one unit, one workspace, one fixed recipient, and only inherited authority. It may narrow scope or authority, never broaden either. Its packet grants no canonical commit, push, PR, shipping, recipient-switch, fallback, peer scheduling, or scope-expansion authority.

An external worker may edit only inside its controller-owned detached worktree. Do not instruct it to run git add, git commit, or another Git index write. Leave the completed working tree uncommitted; the host snapshots the tree. Codex's workspace-write shell sandbox cannot write the linked-worktree Git admin dir, because the index lives in the shared Git common dir outside the workspace. Worker commits are never required. When the worker finishes, the controller turns the complete working tree into an isolated transport commit for the host to inspect. Only the host may apply output to the canonical checkout, run authoritative verification, create a host-only canonical commit, or continue into the shipping steps that follow implementation, whether ce-work runs those itself or returns them to a caller.

A Codex workspace-write packet must also treat socket binds, OS permission checks, and peer-credential probes as host-owned. Preserve the host command and observed result; do not treat a sandbox EPERM as proof the host lacks the capability.

Ordinary synchronous native units stay in the active checkout. Ordinary native subagent isolation remains harness-owned. Only the external cross-model controller may create detached sibling worktrees under its private run root; this exception does not authorize ce-work to create worktrees for native execution. An active checkout that is already a linked worktree does not disable this route: the controller registers another detached sibling through the shared Git common directory under /tmp/compound-engineering-<effective-uid>/ce-work/<run-id>/, never a nested worktree beneath the active checkout.

Raw lines 96 to 105
Starts an agent subagent :104
106## Preserve route and lifecycle receipts
108Direct runs and return-to-caller runs record the same facts, even though what they say to the user and what shipping steps follow differ:
110- `implementation_engine_binding`: resolved `mode`, `target`, `model`, and `source`;
111- `requested_route` and `actual_route`, including every intermediary;
112- `requested_model`, `actual_model`, and served-model receipt status;
113- `requested_effort` or `null`; served effort is never verified, so report it as `unverified`;
114- `fallback_reason` or `null`;
115- `source_kind` (`plan` or `prompt`) and its controller-recorded digest;
116- `run_id` and per-unit `unit_receipts` that distinguish process terminal state, integration, authoritative verification, host canonical commit, and cleanup;
117- `plan_checkpoint`: a disclosed host commit only when the resolved selected plan was the sole canonical dirt;
118- `blockers`; and
119- `recovery_path` for preserved inspectable state.
121Never infer success from detached-process completion alone. The run receipt is complete only after every required unit reaches its host-owned canonical state. A plan-only checkpoint is disclosed to the direct user or returned to an automatic caller; unrelated dirt never receives an implicit checkpoint and instead makes the external route unavailable.

Preserve route and lifecycle receipts

Direct runs and return-to-caller runs record the same facts, even though what they say to the user and what shipping steps follow differ:

  • implementation_engine_binding: resolved mode, target, model, and source;
  • requested_route and actual_route, including every intermediary;
  • requested_model, actual_model, and served-model receipt status;
  • requested_effort or null; served effort is never verified, so report it as unverified;
  • fallback_reason or null;
  • source_kind (plan or prompt) and its controller-recorded digest;
  • run_id and per-unit unit_receipts that distinguish process terminal state, integration, authoritative verification, host canonical commit, and cleanup;
  • plan_checkpoint: a disclosed host commit only when the resolved selected plan was the sole canonical dirt;
  • blockers; and
  • recovery_path for preserved inspectable state.

Never infer success from detached-process completion alone. The run receipt is complete only after every required unit reaches its host-owned canonical state. A plan-only checkpoint is disclosed to the direct user or returned to an automatic caller; unrelated dirt never receives an implicit checkpoint and instead makes the external route unavailable.

Raw lines 106 to 122
123## Build a source for bare-prompt work
125A formal plan is not required when Phase 0 (Input Triage) has already judged a bare prompt concrete enough to execute. Before controller initialization, write one bounded implementation brief directly to OS temp outside the repository. The brief is a distilled statement of what the worker is allowed to do, not a transcript: never include raw conversation history, unrelated session context, credentials, or speculative scope.
127Populate these headings with concrete evidence from the request and Phase 0 discovery:
129- `Request` — the current implementation request, paraphrased only to remove unrelated conversation;
130- `Goal` — one observable outcome;
131- `Scope` — expected files or areas of the code, and discovered patterns/tests;
132- `Acceptance and verification` — behavior and authoritative checks that prove completion;
133- `Constraints and exclusions` — inherited restrictions, non-goals, and unresolved boundaries; and
134- `Units` — use one conservative `P1` unit by default; create more only when discovery establishes distinct goals, dependencies, expected files, and verification without guessing.
136If any of Goal, bounded Scope, or Acceptance and verification cannot be populated, do not initialize the controller or send anything out. Return to Phase 0 clarification or planning. Compute the brief's SHA-256, call controller `init` with `--prompt-brief <temp-path> --prompt-digest <sha256>`, and use the controller-owned private copy and digest thereafter. The caller's temp path is never authoritative after initialization. Invocation origin does not change this contract.

Build a source for bare-prompt work

A formal plan is not required when Phase 0 (Input Triage) has already judged a bare prompt concrete enough to execute. Before controller initialization, write one bounded implementation brief directly to OS temp outside the repository. The brief is a distilled statement of what the worker is allowed to do, not a transcript: never include raw conversation history, unrelated session context, credentials, or speculative scope.

Populate these headings with concrete evidence from the request and Phase 0 discovery:

  • Request — the current implementation request, paraphrased only to remove unrelated conversation;
  • Goal — one observable outcome;
  • Scope — expected files or areas of the code, and discovered patterns/tests;
  • Acceptance and verification — behavior and authoritative checks that prove completion;
  • Constraints and exclusions — inherited restrictions, non-goals, and unresolved boundaries; and
  • Units — use one conservative P1 unit by default; create more only when discovery establishes distinct goals, dependencies, expected files, and verification without guessing.

If any of Goal, bounded Scope, or Acceptance and verification cannot be populated, do not initialize the controller or send anything out. Return to Phase 0 clarification or planning. Compute the brief's SHA-256, call controller init with --prompt-brief <temp-path> --prompt-digest <sha256>, and use the controller-owned private copy and digest thereafter. The caller's temp path is never authoritative after initialization. Invocation origin does not change this contract.

Raw lines 123 to 137
138## Serial external-unit protocol
140Run this protocol from the host checkout for one ready unit at a time. Resolve each bundled script from this skill's directory. The host remains the orchestrator throughout; the external CLI only authors the bounded unit. Use `git -C <canonical-checkout>` for every host Git operation; never rely on the shell's current directory after resolving or running a bundled script.
142**Visibility and stop invariant:** use separate host tool calls and invoke only one state-changing controller transition per call until terminal scope inspection. Never generate or run a shell script that spans `start` through waiting or integration, spans multiple units, loops over the external runtime, or conditionally continues into another transition. `start` must return before supervision. Cap each runner wait at 60 seconds, then sync and publish progress in later host tool calls. After scope inspection, use the controller's single fail-stop `integrate` transaction; do not manually chain its internal Git/controller transitions. A nonzero controller, runner, verification, or Git exit ends that host tool call; inspect controller status and enter its prescribed restoration or recovery path before any later transition.
144When set, `CE_WORK_RUNS_ROOT` is the parent CE Work directory containing all `<run-id>/` directories, not an individual run directory.
1461. **Resolve, preflight, and sanction.** Apply the authority-and-scope resolution in `execution-engines.md`. For an ordered standing preference, skip a candidate equivalent to the current host and preflight each remaining candidate until the first qualifies; record every rejected candidate and reason. Verify the fixed adapter and caller restrictions, then disclose the authorizing source, the route and its intermediaries, the material exposed, and which restrictions are enforced versus cooperative. The controller `init` egress object uses the exact plural keys `route`, `intermediaries`, and `restrictions`: direct `codex`, `claude`, `grok-cli`, `cursor`, `opencode`, and `antigravity` routes use `intermediaries: []`, while `composer` and `grok-cursor` use `intermediaries: ["cursor"]`. When an effort was requested for the fixed recipient, add it to that egress object as `effort` and name it in the disclosure. The controller records it at `init` and writes it into every attempt's authorization, so each unit, retry, and resume of the run uses the recorded value; do not resolve it again from config after `init`. If all candidates are unavailable, both `prefer` and `require` disclose the attempted routes and reasons once, then continue natively on the current harness and session model without starting an external controller run.
1472. **Establish the durable source and clean canonical state.** Initialize the private run with `unit-workspace.py` `init`; the controller creates `/tmp/compound-engineering-<effective-uid>/ce-work/<run-id>` itself (under `$TMPDIR/compound-engineering-<effective-uid>/` instead when `/tmp` cannot host a writable private root, as in a sandbox that only allowlists `$TMPDIR`; `unit-workspace.py` resolves that itself). Do not pre-create the run directory. For a repository plan, pass `--plan <path> --plan-digest <sha256>`; the selected plan may be the only dirty path, and `unit-workspace.py` `checkpoint-plan` records that exact plan-only checkpoint. That exact plan-only state is checkpointable, not a route blocker. For a bounded prompt brief, pass `--prompt-brief <temp-path> --prompt-digest <sha256>`; the controller copies it into private run state, and the canonical checkout must already be clean because no repository source is eligible for checkpointing. Only checkpoint failure or unrelated dirt makes the route unavailable. Re-read canonical repository, branch, HEAD, source kind/digest, and cleanliness before preparing a unit.
148 Once `init` returns `READY`, the engine decision is closed for that unit. The next implementation path is `prepare` then the fixed-author start, or a blocker that preserves the returned recovery path. Expected latency, orchestration cost, or a later judgment that native work would be simpler is not route unavailability and never authorizes canonical writes. Native implementation becomes eligible only through the controller's `claim-fallback` check described later under "Resume and fallback exactly once".
1493. **Prepare one bounded unit packet.** For a plan, include only the Goal Capsule, Definition of Done, active unit, relevant Verification Contract rows, cited R/F/AE/KTD excerpts, any Product Contract Key Decision whose exact `Governs R…` links name the active unit's cited R-IDs, inherited restrictions, expected files, evidence strategy, and explicit exclusions. Include the active unit's prototype source citations with their qualifications about locality, availability, and the authority of requirements. Instruct the worker to inspect accessible, explicitly cited prototype decisions and selected screens or states before implementing the affected behavior, including when those sources are in another worktree. Keep edits and tests inside the assigned workspace. For a prompt brief, include only the matching P-unit's Goal, Scope, Acceptance and verification, Constraints and exclusions, expected files, and evidence strategy. For either source, also include the text and citation of each Compound Pack rule matched to the unit's files (`references/work-intake.md`), given as team rules to honor that never widen the unit or its authority. Do not expose the whole plan, prompt brief, or conversation by default. Write the packet source directly to OS temp outside the canonical checkout, such as a source file beneath the controller-returned recovery path; never draft it inside the repository and move or copy it later. Call `unit-workspace.py` `prepare` with that packet source path, unit id, recorded base, dependencies, wave fields, and the activity kind the route qualifies for (`incremental` or `hard-only`). Every route streams its ACP session, so `incremental` is the default. Use only the controller-returned `attempt_id`, controller-owned `packet_path`, and computed `packet_digest` for dispatch; never substitute the caller's source path, a caller-computed digest, or an assumed attempt name.
150 `prepare` refuses only on unrelated dirt or a moved HEAD; the size and shape of the canonical checkout's git-ignored inventory (installed dependencies, virtualenvs, build caches, symlinks) never make the route unavailable.
1514. **Start one fixed author.** The controller-issued authorization schema binds `run_id`, `unit_id`, and `attempt_id` to the fixed route/model/intermediary and packet contract. Call `peer-job-runner.py` `start --no-sweep --input-digest <controller-packet-digest>` with skill `ce-work`; the runner label must equal the unit id exactly, without the attempt id or another suffix, and `--result-path` must be `<controller-result-dir>/implementation-result.json`. Both `--input-digest` and the adapter's expected-packet argument must use the exact `packet_digest` returned by `prepare`; omitting the runner flag or recomputing/substituting either value makes the job ineligible for `record-job`. The runner and controller share the same root automatically: `CE_WORK_RUNS_ROOT` wins when set, otherwise both derive CE Work state from `CE_PEER_JOBS_ROOT`. Set `CE_PEER_HARD_SECS=7200` on every production CE Work runner start rather than relying on the shared runner default. Set `CE_PEER_IDLE_SECS=600` for route-qualified `incremental` activity and `CE_PEER_IDLE_SECS=0` for `hard-only` or otherwise untrustworthy activity. The 600-second window resets on progress and detects a stall; it is not a wall-clock maximum. Its production worker command is `cross-model-work.sh <authorization_path> <workspace> <unit-packet> <expected-packet-sha256> <result-dir>`; invoke the returned adapter path directly as the first worker argv, without a `bash`, `sh`, or `env` prefix, and pass only the controller-returned `authorization_path`, never a caller-supplied route string or an ambient model or effort override. The runner exports its controller-visible job id to the worker. Before prompt construction or external CLI start, the adapter must pass that runner-exported job id and obtain controller `authorize-dispatch` success by calling `unit-workspace.py` `authorize-dispatch`. That success reads the actual runner metadata and exact worker argv, rejecting a shell prefix or substituted adapter before anything is sent out, then atomically binds that job id to the exact attempt before egress along with the authorization digest, workspace, packet path and digest, and result directory while revalidating the controller-owned exact route, model, and intermediary contract. A second job for the attempt is refused. A missing or refused handshake, including hand-authored or cross-attempt authorization, means nothing is sent out. Model pins and the requested effort come only from the authorized projection. The adapter's `--emit-adapter` mode remains introspection only and never authorizes production dispatch. Capture the returned job id immediately with `unit-workspace.py` `record-job`, using the controller-returned `attempt_id` verbatim; this idempotently confirms the same validated binding. Never hold one host tool call open for the external runtime and never let the adapter select another recipient.
1525. **Observe without steering.** Interleave runner `status --skill ce-work` or `wait --skill ce-work --max-secs 60` calls with separate `unit-workspace.py` `sync-job` calls; every bare-job-id runner `status`, `wait`, `result`, or `reap` call must carry `--skill ce-work` under the same `CE_WORK_RUNS_ROOT` / `CE_PEER_JOBS_ROOT` selection used at start. Report unit, route, elapsed time, latest meaningful activity, the activity kind in effect, and terminal state after each cycle. When a unit's activity cannot be trusted to show progress within the idle window, `hard-only` is the normal posture: disable idle timeout, retain the universal hard cap, and never infer failure or fallback merely from absent incremental activity. A live or temporarily unreachable attempt is still authoritative: do not start fallback or duplicate work. Reap only through the explicit controller/runner path and retain its workspace.
1536. **Terminalize complete Git output.** On authoritative `done`, call `unit-workspace.py` `terminalize`. Require its pinned synthetic transport commit to have the recorded base as sole parent and the complete final workspace tree. In a later host call, inspect the actual transport diff, changed paths, binary/mode/rename/delete evidence, adapter result, packet expected scope, and any scope-expansion request. A generated byproduct or any unexplained difference between actual transport paths, expected scope, and the worker's evidence is unexpected scope: preserve it for host resolution and do not take the integration lock.
1547. **Integrate through the fail-stop controller transaction.** After the separate scope-inspection call accepts the complete transport, invoke `unit-workspace.py integrate --run-id <run-id> --unit-id <unit-id> --commit-message <message> --verification-summary <summary> [--allowed-head <recorded-head>] -- <verification-command-and-argv>`. Pass a simple Verification Contract command as direct argv. If it contains shell syntax such as `$(...)`, a pipe, `&&`, a redirect, or a glob, invoke an explicit shell with pipe-failure handling on the first attempt, for example `-- bash -o pipefail -c 'test "$(cat delegated.txt)" = "expected"'`; quoting `$(...)` as a direct argument does not expand it. Do not manually chain or conditionally reproduce this transaction.
1558. **Let `integrate` perform every canonical change.** It performs `unit-workspace.py` `integration-acquire`, `unit-workspace.py` `preflight`, `git cherry-pick --no-commit`, `unit-workspace.py` `mark-applied`, authoritative canonical verification with Python bytecode disabled, exact canonical-state reconciliation, `unit-workspace.py` `mark-verified`, one host-owned commit, and `unit-workspace.py` `mark-committed`. For a wave it also records `wave-advance`; after a reconciled commit it performs `unit-workspace.py` `cleanup` and `unit-workspace.py` `integration-release`.
1569. **Treat its outcome as authoritative.** Capture the authoritative command's exit status directly; never infer a pass from stdout. Any change to tracked state — HEAD, branch, index, or status-visible paths — fails reconciliation. Git-ignored state is not part of that proof. The controller inventories ignored entries by metadata before and after verification and discloses `changed`, `removed`, and `created` counts with a bounded path sample as `ignored_state` in every verification receipt and return body. It never copies, restores, or deletes ignored files, so a verification command that mutates a cache or a local database changes only what native units already could. Ignored files the command creates stay in place. Empty ignored directories are not inventoried. `.env`-class files and local databases receive no protection from a misbehaving verification command. Verification and clean-state reconciliation happen before `mark-verified`. A rejected verification or a failed pre-commit controller/Git step forbids the commit, calls `unit-workspace.py` `restore`, proves exact pre-fold equality, and releases the lock before fallback, retry, or another unit. If exact restoration cannot be proven, it retains the lock, workspace, transport ref, and recovery path. A crash after the canonical commit remains resumable evidence and must not be redispatched.
15710. **Run the source-wide checks through the controller.** After every external unit is committed and cleaned, invoke `unit-workspace.py verify-run --run-id <run-id> --verification-summary <summary> -- <verification-command-and-argv>` for the plan-wide Verification Contract gates or the prompt brief's authoritative checks. Do not run those final commands directly in the canonical checkout or hide their status behind a later command. `verify-run` starts only from a clean canonical snapshot, captures the command's exit status directly with Python bytecode disabled, restores tracked state to the exact starting snapshot, discloses ignored-state divergence as `ignored_state` per step 9, and records a durable receipt. A failing check retains its private log and blocks the return to the caller or the shipping steps even after cleanup succeeds.
159Report every transition in the direct commentary or in the structured return to the caller: resolved source kind, route, plan checkpoint when applicable, dispatch, activity, terminal result, transport/scope inspection, integration, restoration if any, authoritative verification, canonical commit, cleanup, blocker, and recovery path. The serial protocol does not authorize parallel waves or automatic redispatch; those require the checks in the next two sections.

Serial external-unit protocol

Run this protocol from the host checkout for one ready unit at a time. Resolve each bundled script from this skill's directory. The host remains the orchestrator throughout; the external CLI only authors the bounded unit. Use git -C <canonical-checkout> for every host Git operation; never rely on the shell's current directory after resolving or running a bundled script.

Visibility and stop invariant: use separate host tool calls and invoke only one state-changing controller transition per call until terminal scope inspection. Never generate or run a shell script that spans start through waiting or integration, spans multiple units, loops over the external runtime, or conditionally continues into another transition. start must return before supervision. Cap each runner wait at 60 seconds, then sync and publish progress in later host tool calls. After scope inspection, use the controller's single fail-stop integrate transaction; do not manually chain its internal Git/controller transitions. A nonzero controller, runner, verification, or Git exit ends that host tool call; inspect controller status and enter its prescribed restoration or recovery path before any later transition.

When set, CE_WORK_RUNS_ROOT is the parent CE Work directory containing all <run-id>/ directories, not an individual run directory.

  1. Resolve, preflight, and sanction. Apply the authority-and-scope resolution in execution-engines.md. For an ordered standing preference, skip a candidate equivalent to the current host and preflight each remaining candidate until the first qualifies; record every rejected candidate and reason. Verify the fixed adapter and caller restrictions, then disclose the authorizing source, the route and its intermediaries, the material exposed, and which restrictions are enforced versus cooperative. The controller init egress object uses the exact plural keys route, intermediaries, and restrictions: direct codex, claude, grok-cli, cursor, opencode, and antigravity routes use intermediaries: [], while composer and grok-cursor use intermediaries: ["cursor"]. When an effort was requested for the fixed recipient, add it to that egress object as effort and name it in the disclosure. The controller records it at init and writes it into every attempt's authorization, so each unit, retry, and resume of the run uses the recorded value; do not resolve it again from config after init. If all candidates are unavailable, both prefer and require disclose the attempted routes and reasons once, then continue natively on the current harness and session model without starting an external controller run.
  2. Establish the durable source and clean canonical state. Initialize the private run with unit-workspace.py init; the controller creates /tmp/compound-engineering-<effective-uid>/ce-work/<run-id> itself (under $TMPDIR/compound-engineering-<effective-uid>/ instead when /tmp cannot host a writable private root, as in a sandbox that only allowlists $TMPDIR; unit-workspace.py resolves that itself). Do not pre-create the run directory. For a repository plan, pass --plan <path> --plan-digest <sha256>; the selected plan may be the only dirty path, and unit-workspace.py checkpoint-plan records that exact plan-only checkpoint. That exact plan-only state is checkpointable, not a route blocker. For a bounded prompt brief, pass --prompt-brief <temp-path> --prompt-digest <sha256>; the controller copies it into private run state, and the canonical checkout must already be clean because no repository source is eligible for checkpointing. Only checkpoint failure or unrelated dirt makes the route unavailable. Re-read canonical repository, branch, HEAD, source kind/digest, and cleanliness before preparing a unit. Once init returns READY, the engine decision is closed for that unit. The next implementation path is prepare then the fixed-author start, or a blocker that preserves the returned recovery path. Expected latency, orchestration cost, or a later judgment that native work would be simpler is not route unavailability and never authorizes canonical writes. Native implementation becomes eligible only through the controller's claim-fallback check described later under "Resume and fallback exactly once".
  3. Prepare one bounded unit packet. For a plan, include only the Goal Capsule, Definition of Done, active unit, relevant Verification Contract rows, cited R/F/AE/KTD excerpts, any Product Contract Key Decision whose exact Governs R… links name the active unit's cited R-IDs, inherited restrictions, expected files, evidence strategy, and explicit exclusions. Include the active unit's prototype source citations with their qualifications about locality, availability, and the authority of requirements. Instruct the worker to inspect accessible, explicitly cited prototype decisions and selected screens or states before implementing the affected behavior, including when those sources are in another worktree. Keep edits and tests inside the assigned workspace. For a prompt brief, include only the matching P-unit's Goal, Scope, Acceptance and verification, Constraints and exclusions, expected files, and evidence strategy. For either source, also include the text and citation of each Compound Pack rule matched to the unit's files (references/work-intake.md), given as team rules to honor that never widen the unit or its authority. Do not expose the whole plan, prompt brief, or conversation by default. Write the packet source directly to OS temp outside the canonical checkout, such as a source file beneath the controller-returned recovery path; never draft it inside the repository and move or copy it later. Call unit-workspace.py prepare with that packet source path, unit id, recorded base, dependencies, wave fields, and the activity kind the route qualifies for (incremental or hard-only). Every route streams its ACP session, so incremental is the default. Use only the controller-returned attempt_id, controller-owned packet_path, and computed packet_digest for dispatch; never substitute the caller's source path, a caller-computed digest, or an assumed attempt name. prepare refuses only on unrelated dirt or a moved HEAD; the size and shape of the canonical checkout's git-ignored inventory (installed dependencies, virtualenvs, build caches, symlinks) never make the route unavailable.
  4. Start one fixed author. The controller-issued authorization schema binds run_id, unit_id, and attempt_id to the fixed route/model/intermediary and packet contract. Call peer-job-runner.py start --no-sweep --input-digest <controller-packet-digest> with skill ce-work; the runner label must equal the unit id exactly, without the attempt id or another suffix, and --result-path must be <controller-result-dir>/implementation-result.json. Both --input-digest and the adapter's expected-packet argument must use the exact packet_digest returned by prepare; omitting the runner flag or recomputing/substituting either value makes the job ineligible for record-job. The runner and controller share the same root automatically: CE_WORK_RUNS_ROOT wins when set, otherwise both derive CE Work state from CE_PEER_JOBS_ROOT. Set CE_PEER_HARD_SECS=7200 on every production CE Work runner start rather than relying on the shared runner default. Set CE_PEER_IDLE_SECS=600 for route-qualified incremental activity and CE_PEER_IDLE_SECS=0 for hard-only or otherwise untrustworthy activity. The 600-second window resets on progress and detects a stall; it is not a wall-clock maximum. Its production worker command is cross-model-work.sh <authorization_path> <workspace> <unit-packet> <expected-packet-sha256> <result-dir>; invoke the returned adapter path directly as the first worker argv, without a bash, sh, or env prefix, and pass only the controller-returned authorization_path, never a caller-supplied route string or an ambient model or effort override. The runner exports its controller-visible job id to the worker. Before prompt construction or external CLI start, the adapter must pass that runner-exported job id and obtain controller authorize-dispatch success by calling unit-workspace.py authorize-dispatch. That success reads the actual runner metadata and exact worker argv, rejecting a shell prefix or substituted adapter before anything is sent out, then atomically binds that job id to the exact attempt before egress along with the authorization digest, workspace, packet path and digest, and result directory while revalidating the controller-owned exact route, model, and intermediary contract. A second job for the attempt is refused. A missing or refused handshake, including hand-authored or cross-attempt authorization, means nothing is sent out. Model pins and the requested effort come only from the authorized projection. The adapter's --emit-adapter mode remains introspection only and never authorizes production dispatch. Capture the returned job id immediately with unit-workspace.py record-job, using the controller-returned attempt_id verbatim; this idempotently confirms the same validated binding. Never hold one host tool call open for the external runtime and never let the adapter select another recipient.
  5. Observe without steering. Interleave runner status --skill ce-work or wait --skill ce-work --max-secs 60 calls with separate unit-workspace.py sync-job calls; every bare-job-id runner status, wait, result, or reap call must carry --skill ce-work under the same CE_WORK_RUNS_ROOT / CE_PEER_JOBS_ROOT selection used at start. Report unit, route, elapsed time, latest meaningful activity, the activity kind in effect, and terminal state after each cycle. When a unit's activity cannot be trusted to show progress within the idle window, hard-only is the normal posture: disable idle timeout, retain the universal hard cap, and never infer failure or fallback merely from absent incremental activity. A live or temporarily unreachable attempt is still authoritative: do not start fallback or duplicate work. Reap only through the explicit controller/runner path and retain its workspace.
  6. Terminalize complete Git output. On authoritative done, call unit-workspace.py terminalize. Require its pinned synthetic transport commit to have the recorded base as sole parent and the complete final workspace tree. In a later host call, inspect the actual transport diff, changed paths, binary/mode/rename/delete evidence, adapter result, packet expected scope, and any scope-expansion request. A generated byproduct or any unexplained difference between actual transport paths, expected scope, and the worker's evidence is unexpected scope: preserve it for host resolution and do not take the integration lock.
  7. Integrate through the fail-stop controller transaction. After the separate scope-inspection call accepts the complete transport, invoke unit-workspace.py integrate --run-id <run-id> --unit-id <unit-id> --commit-message <message> --verification-summary <summary> [--allowed-head <recorded-head>] -- <verification-command-and-argv>. Pass a simple Verification Contract command as direct argv. If it contains shell syntax such as $(...), a pipe, &&, a redirect, or a glob, invoke an explicit shell with pipe-failure handling on the first attempt, for example -- bash -o pipefail -c 'test "$(cat delegated.txt)" = "expected"'; quoting $(...) as a direct argument does not expand it. Do not manually chain or conditionally reproduce this transaction.
  8. **Let integrate perform every canonical change.** It performs unit-workspace.py integration-acquire, unit-workspace.py preflight, git cherry-pick --no-commit, unit-workspace.py mark-applied, authoritative canonical verification with Python bytecode disabled, exact canonical-state reconciliation, unit-workspace.py mark-verified, one host-owned commit, and unit-workspace.py mark-committed. For a wave it also records wave-advance; after a reconciled commit it performs unit-workspace.py cleanup and unit-workspace.py integration-release.
  9. Treat its outcome as authoritative. Capture the authoritative command's exit status directly; never infer a pass from stdout. Any change to tracked state — HEAD, branch, index, or status-visible paths — fails reconciliation. Git-ignored state is not part of that proof. The controller inventories ignored entries by metadata before and after verification and discloses changed, removed, and created counts with a bounded path sample as ignored_state in every verification receipt and return body. It never copies, restores, or deletes ignored files, so a verification command that mutates a cache or a local database changes only what native units already could. Ignored files the command creates stay in place. Empty ignored directories are not inventoried. .env-class files and local databases receive no protection from a misbehaving verification command. Verification and clean-state reconciliation happen before mark-verified. A rejected verification or a failed pre-commit controller/Git step forbids the commit, calls unit-workspace.py restore, proves exact pre-fold equality, and releases the lock before fallback, retry, or another unit. If exact restoration cannot be proven, it retains the lock, workspace, transport ref, and recovery path. A crash after the canonical commit remains resumable evidence and must not be redispatched.
  10. Run the source-wide checks through the controller. After every external unit is committed and cleaned, invoke unit-workspace.py verify-run --run-id <run-id> --verification-summary <summary> -- <verification-command-and-argv> for the plan-wide Verification Contract gates or the prompt brief's authoritative checks. Do not run those final commands directly in the canonical checkout or hide their status behind a later command. verify-run starts only from a clean canonical snapshot, captures the command's exit status directly with Python bytecode disabled, restores tracked state to the exact starting snapshot, discloses ignored-state divergence as ignored_state per step 9, and records a durable receipt. A failing check retains its private log and blocks the return to the caller or the shipping steps even after cleanup succeeds.

Report every transition in the direct commentary or in the structured return to the caller: resolved source kind, route, plan checkpoint when applicable, dispatch, activity, terminal result, transport/scope inspection, integration, restoration if any, authoritative verification, canonical commit, cleanup, blocker, and recovery path. The serial protocol does not authorize parallel waves or automatic redispatch; those require the checks in the next two sections.

Raw lines 138 to 160
Starts an agent dispatch :149
161## Parallel external-wave protocol
163Use a wave only after the always-loaded Parallel Safety Check proves the ready units independent across dependencies, declared files, shared contracts/interfaces, migrations, lockfiles, generated, registry, or config files, environment singletons, and expected merge cost. Uncertainty selects serial execution. The host stays the scheduler: workers cannot add peers, broaden the wave, or change their own dependencies. Cap the wave at 3-5 workers.
1651. Record one wave id, dependency order, and **one recorded wave base** from a clean canonical checkout. Prepare every member from that same base with distinct controller-owned workspaces. Synchronous native work remains in the active checkout; every concurrent worker is isolated.
1662. Start the fixed-route jobs concurrently, observe them without steering, and terminalize every worker into its base-parented synthetic transport commit **before the first fold-in**. If any worker has not terminalized, integrate none. Inspect all actual transport inventories before mutation; same-path changes stop the wave, while shared-interface or other semantic contention returns to host resolution even when paths differ.
1673. Integrate results sequentially in dependency order under the canonical integration lock. The first unit preflights against the wave base. A clean textual apply is not semantic compatibility: inspect scope, run that unit's authoritative verification against the advancing canonical tree, and create one host-owned canonical commit.
1684. While that unit's lock is still held, call `unit-workspace.py` `wave-advance` with its exact recorded canonical commit. The controller accepts only the manifest-confirmed commit whose parent is the recorded pre-fold HEAD, then adds it to later siblings as one of the **exact earlier host-owned canonical commits**. Clean and release the completed unit before acquiring the next sibling's lock.
1695. For each later result, pass only the current exact recorded wave commit to `preflight`. Unknown HEAD movement blocks. Even when three-way application is clean, repeat actual-scope inspection, semantic revalidation, authoritative verification, and a separate host commit. A transport commit is never merged or committed directly.
1706. Conflict, scope expansion, semantic collision, test failure, or commit failure enters the serial protocol's exact restoration while the lock remains held. No sibling, retry, or fallback starts until restoration is proven and the lock is released; affected dependents remain queued. After readiness is recomputed, unaffected siblings may continue. The affected unit requires explicit host resolution, re-dispatch on the new base, or serial fallback; never blind-merge a colliding or stale result.
1717. Repeated collision, broad unplanned edits, or inability to prove exact restoration disables more waves for the run. Preserve inspectable workspaces and refs; failure of one unit does not discard an unaffected sibling, but it never authorizes a dependent unit early.

Parallel external-wave protocol

Use a wave only after the always-loaded Parallel Safety Check proves the ready units independent across dependencies, declared files, shared contracts/interfaces, migrations, lockfiles, generated, registry, or config files, environment singletons, and expected merge cost. Uncertainty selects serial execution. The host stays the scheduler: workers cannot add peers, broaden the wave, or change their own dependencies. Cap the wave at 3-5 workers.

  1. Record one wave id, dependency order, and one recorded wave base from a clean canonical checkout. Prepare every member from that same base with distinct controller-owned workspaces. Synchronous native work remains in the active checkout; every concurrent worker is isolated.
  2. Start the fixed-route jobs concurrently, observe them without steering, and terminalize every worker into its base-parented synthetic transport commit before the first fold-in. If any worker has not terminalized, integrate none. Inspect all actual transport inventories before mutation; same-path changes stop the wave, while shared-interface or other semantic contention returns to host resolution even when paths differ.
  3. Integrate results sequentially in dependency order under the canonical integration lock. The first unit preflights against the wave base. A clean textual apply is not semantic compatibility: inspect scope, run that unit's authoritative verification against the advancing canonical tree, and create one host-owned canonical commit.
  4. While that unit's lock is still held, call unit-workspace.py wave-advance with its exact recorded canonical commit. The controller accepts only the manifest-confirmed commit whose parent is the recorded pre-fold HEAD, then adds it to later siblings as one of the exact earlier host-owned canonical commits. Clean and release the completed unit before acquiring the next sibling's lock.
  5. For each later result, pass only the current exact recorded wave commit to preflight. Unknown HEAD movement blocks. Even when three-way application is clean, repeat actual-scope inspection, semantic revalidation, authoritative verification, and a separate host commit. A transport commit is never merged or committed directly.
  6. Conflict, scope expansion, semantic collision, test failure, or commit failure enters the serial protocol's exact restoration while the lock remains held. No sibling, retry, or fallback starts until restoration is proven and the lock is released; affected dependents remain queued. After readiness is recomputed, unaffected siblings may continue. The affected unit requires explicit host resolution, re-dispatch on the new base, or serial fallback; never blind-merge a colliding or stale result.
  7. Repeated collision, broad unplanned edits, or inability to prove exact restoration disables more waves for the run. Preserve inspectable workspaces and refs; failure of one unit does not discard an unaffected sibling, but it never authorizes a dependent unit early.
Raw lines 161 to 172
Starts an agent dispatch :170
173## Resume and fallback exactly once
175When the caller supplies a run id directly or through return-to-caller `implementation_run:<safe-id>`, use `unit-workspace.py` `resume --run-id <id>` and treat that id as authoritative. This recovery step happens before ordinary input classification and must not dispatch new work. Without a supplied run id, a plan-backed run must use `resume --repo <canonical-checkout> --plan-digest <selected-plan-digest>` for discovery; never infer or select a run id by listing the shared run root. Prompt-backed runs require their disclosed run id; do not rediscover them from conversation text or a caller temp path. Resume only a single unfinished plan-backed run matching repository identity, branch, and plan digest; if several match, list the matching run ids and recovery paths and block selection rather than choosing one. Do not dispatch a new third run while matching unfinished state remains ambiguous. An unsafe or foreign-mode manifest is a blocker, not a candidate to skip.
177When all units are terminal (`cleaned` or `native-completed`) and a successful plan-wide verification receipt already exists, the completed run is observation-only. Build the structured return from the manifest and stored receipts; recovery must not rerun a Verification Contract gate, call `verify-run`, or execute test/build/format/install/generation commands merely to reconfirm completed evidence. A missing required receipt is a reported recovery blocker, not permission to improvise a loose verification step.
179Resume reconciles durable evidence, but must not redispatch, reapply, recommit, or run either owning tail (the standalone shipping steps or the caller's). It may adopt exactly one matching unbound runner job, monitor a recorded live job, terminalize authoritative `done` output, continue an interrupted exact restoration, or record a verified canonical commit whose parent and tree match the pre-fold evidence. A transport ref written before its manifest row is reusable only when its sole parent and final tree match. Preflight records the expected post-apply tree and changed-path set: an exact match may reconcile an apply that landed before its manifest row, while unknown dirt blocks without destructive restoration.
181Use the controller's `status`, `reap`, and `cleanup` operations for preserved work. Loss of contact leaves a recorded job live until runner evidence becomes terminal or an explicit reap records termination. Cleanup is idempotent after an interrupted worktree removal. Explicit abandonment requires the exact transport SHA, or the exact terminal job id when a failed/reaped attempt produced no transport.
183After exact restoration, exact abandonment cleanup, and integration-lock release, re-dispatch a corrected unit under the same scalar `run_id` by calling `prepare` with a fresh `attempt_id`. Preserve the earlier attempt receipts; do not mint another run id or represent one logical run as a list of run ids. The controller refuses a retry that changes the unit's recorded dependency or wave/base contract.
185Post-start fallback is a separate atomic check. After authoritative failure, timeout, `died-without-result`, or exact restoration and lock release, disclose the unavailable route once and call `unit-workspace.py` `claim-fallback` before native implementation. The first `prefer` or `require` claim authorizes exactly one fallback on the current harness and session model; `FALLBACK_ALREADY_AUTHORIZED` means do not start it again. Requirement strength prevents external recipient substitution while the route is viable, but never turns an unavailable route into an error or user-choice gate. A live job or successful unreconciled output refuses the claim. If integration began, no retry, sibling, or fallback claim is eligible until exact restoration is recorded and the canonical checkout still equals that snapshot. After the claimed native implementation is committed and locally verified, call `unit-workspace.py` `complete-fallback` with the accepted HEAD, a SHA-256 digest of the local verification evidence, and a bounded summary; both `prefer` and `require` claims can complete. `FALLBACK_COMPLETED` closes that unit only. Once every unit is terminal, run the plan-wide Verification Contract through `verify-run`; do not report the run complete until the controller returns `RUN_VERIFIED` and stores its successful receipt.

Resume and fallback exactly once

When the caller supplies a run id directly or through return-to-caller implementation_run:<safe-id>, use unit-workspace.py resume --run-id <id> and treat that id as authoritative. This recovery step happens before ordinary input classification and must not dispatch new work. Without a supplied run id, a plan-backed run must use resume --repo <canonical-checkout> --plan-digest <selected-plan-digest> for discovery; never infer or select a run id by listing the shared run root. Prompt-backed runs require their disclosed run id; do not rediscover them from conversation text or a caller temp path. Resume only a single unfinished plan-backed run matching repository identity, branch, and plan digest; if several match, list the matching run ids and recovery paths and block selection rather than choosing one. Do not dispatch a new third run while matching unfinished state remains ambiguous. An unsafe or foreign-mode manifest is a blocker, not a candidate to skip.

When all units are terminal (cleaned or native-completed) and a successful plan-wide verification receipt already exists, the completed run is observation-only. Build the structured return from the manifest and stored receipts; recovery must not rerun a Verification Contract gate, call verify-run, or execute test/build/format/install/generation commands merely to reconfirm completed evidence. A missing required receipt is a reported recovery blocker, not permission to improvise a loose verification step.

Resume reconciles durable evidence, but must not redispatch, reapply, recommit, or run either owning tail (the standalone shipping steps or the caller's). It may adopt exactly one matching unbound runner job, monitor a recorded live job, terminalize authoritative done output, continue an interrupted exact restoration, or record a verified canonical commit whose parent and tree match the pre-fold evidence. A transport ref written before its manifest row is reusable only when its sole parent and final tree match. Preflight records the expected post-apply tree and changed-path set: an exact match may reconcile an apply that landed before its manifest row, while unknown dirt blocks without destructive restoration.

Use the controller's status, reap, and cleanup operations for preserved work. Loss of contact leaves a recorded job live until runner evidence becomes terminal or an explicit reap records termination. Cleanup is idempotent after an interrupted worktree removal. Explicit abandonment requires the exact transport SHA, or the exact terminal job id when a failed/reaped attempt produced no transport.

After exact restoration, exact abandonment cleanup, and integration-lock release, re-dispatch a corrected unit under the same scalar run_id by calling prepare with a fresh attempt_id. Preserve the earlier attempt receipts; do not mint another run id or represent one logical run as a list of run ids. The controller refuses a retry that changes the unit's recorded dependency or wave/base contract.

Post-start fallback is a separate atomic check. After authoritative failure, timeout, died-without-result, or exact restoration and lock release, disclose the unavailable route once and call unit-workspace.py claim-fallback before native implementation. The first prefer or require claim authorizes exactly one fallback on the current harness and session model; FALLBACK_ALREADY_AUTHORIZED means do not start it again. Requirement strength prevents external recipient substitution while the route is viable, but never turns an unavailable route into an error or user-choice gate. A live job or successful unreconciled output refuses the claim. If integration began, no retry, sibling, or fallback claim is eligible until exact restoration is recorded and the canonical checkout still equals that snapshot. After the claimed native implementation is committed and locally verified, call unit-workspace.py complete-fallback with the accepted HEAD, a SHA-256 digest of the local verification evidence, and a bounded summary; both prefer and require claims can complete. FALLBACK_COMPLETED closes that unit only. Once every unit is terminal, run the plan-wide Verification Contract through verify-run; do not report the run complete until the controller returns RUN_VERIFIED and stores its successful receipt.

Raw lines 173 to 186
Starts an agent dispatch :175
187## Preserve tail ownership
189The engine changes only who writes the implementation. A standalone invocation resumes `ce-work`'s quality and shipping workflow after local implementation. `mode:return-to-caller` returns implementation and local-verification receipts with `standalone_shipping_skipped: true`; it never runs the simplify, review, PR, or CI steps that belong to the caller. External workers never inherit either set of shipping steps.
191**A successful controller `init` locks that unit to the selected cross-model engine.** From that point, advance it through this controller protocol or return blocked with its recovery path. Never reclassify it as trivial, abandon it for speed, or implement it natively unless the protocol later returns an explicit fallback authorization.

Preserve tail ownership

The engine changes only who writes the implementation. A standalone invocation resumes ce-work's quality and shipping workflow after local implementation. mode:return-to-caller returns implementation and local-verification receipts with standalone_shipping_skipped: true; it never runs the simplify, review, PR, or CI steps that belong to the caller. External workers never inherit either set of shipping steps.

**A successful controller init locks that unit to the selected cross-model engine.** From that point, advance it through this controller protocol or return blocked with its recovery path. Never reclassify it as trivial, abandon it for speed, or implement it natively unless the protocol later returns an explicit fallback authorization.

Raw lines 187 to 191