codex-workflow-v2 2.0.0-beta.13.7 → 2.0.0-beta.13.9

package/docs/change-model.md

@@ -0,0 +1,118 @@
+# Execution context and change explanation
+
+A change is explained before it is attempted. The explanation is not an approval, a new grant,
+or a replacement lifecycle. Existing Core `next` remains authoritative.
+
+## One execution context
+
+App dispatch defaults to a worktree. An explicitly requested `executionMode: "local"` creates
+in the saved project instead. Use local only when the user requested that execution environment.
+The dispatch prompt separates repository identity from the child's actual write destination.
+Correlated App readback records the real checkout root. A second readback cannot silently move
+that bound Worker into another checkout, even when both share a Git common directory.
+
+Before the first write and after a branch/cwd change, call the packaged registry action
+`dispatch-context-check --reservation-id ... --file ... --project-id ...` with:
+
+```json
+{
+  "observation": { "thread": {
+    "id": "actual-bound-thread-uuid", "kind": "codex", "hostId": "local",
+    "cwd": "/absolute/actual/worker/checkout"
+  } },
+  "writeRoot": "/absolute/actual/worker/checkout",
+  "expectedBranch": "exact-branch-from-fresh-Task"
+}
+```
+
+Use a fresh App `read_thread` observation, never a fabricated cwd. This read-only check detects
+repository, checkout, write-root and branch mismatch. It does not replace Task revision, actor,
+lease/credential or external permission checks. Do not send another create request, change the
+target directory, or hand off an active writer merely to clear a mismatch. Reconcile the existing
+Worker and Workflow context. Tracked dispatch without recorded executionContext needs a correlated `dispatch-observe` before
+this check can match; it does not invent an existing checkout binding.
+
+## One change card
+
+`change explain --task TASK-ID --file proposal.json --repo /actual/checkout --json` reads the
+current Task and `next` from one observation. It changes no workflow state or product file.
+
+```json
+{
+  "reason": "The current check requires one additional support file.",
+  "paths": ["tools/check-support.ts"],
+  "intent": "implementation",
+  "expectedRevision": 12,
+  "executionContext": {
+    "cwd": "/absolute/actual/worker/checkout",
+    "writeRoot": "/absolute/actual/worker/checkout",
+    "expectedBranch": "exact-task-branch"
+  },
+  "externalDecision": "unknown"
+}
+```
+
+`paths` are exact normalized relative file paths, not globs. `expectedPlanHash` is also accepted.
+Inputs are closed; an agent cannot add a `supportProven` or `approved` flag. `externalDecision:
+"denied"` preserves an external denial as a separate blocker. It does not call or emulate the
+external permission service. `intent` may instead be `membership` or `semantic-scope`; declaring
+intent never proves semantic safety. Omitted context is reported as not supplied, not verified.
+
+The card binds Task revision/Plan, HEAD, request and bytes of proposed plus observed dirty paths.
+Undeclared dirty files are included; escaping symlinks block byte inspection. The output contains
+no confirmation/claim/writer values and no proposed file contents. A proposal hash is a diagnostic
+binding, not an apply token; always refresh `next` and ordinary mutation preconditions.
+
+## Adaptation routes
+
+- Implementation fixes continue within the same Task when the current Core route permits it.
+  Review count alone does not select corrective planning.
+- `bounded-plan-amendment` appears only when Core advertises the exact eligible check-support
+  scope extension and every out-of-Step file is covered by that evidence. Execute the existing
+  `task plan-integrity-recover` route and fresh `next`; its existing atomic evidence and authority
+  rules apply. The card never edits `allowedWrites`, enlarges a grant, or supplies an arbitrary
+  new Plan. This release reuses the proven bounded amendment mechanism rather than adding a
+  competing mutation protocol.
+- An unproved additional file requires Plan review. No broad glob or diff-size rule grants
+  automatic extension. Runtime changes and component-owner recovery retain their current audits.
+- Corrective planning and downstream recovery retain existing Task/Worker identity and historical
+  evidence. A Knowledge context refresh does not resolve a Plan conflict.
+- Membership is distinct from implementation. Existing audited remediation and full-contract
+  membership evolution remain the only corresponding machine routes. A reported membership
+  intent does not authorize deletion of a required Task or weakened acceptance.
+- Semantic scope requires an explicit user decision. External denial remains independent of
+  Workflow grants and file scope.
+
+`requiresUser: null` means the card has not established a specific human gate, not that all
+checks passed. The card is advisory and cannot intercept arbitrary editor/tool writes. Gateway
+agents must invoke the context check and fresh Core route before writing. No claim is made that
+an external approval system will accept the resulting operation.
+
+For a legacy Worker already bound before dispatch markers existed, the read-only context check
+uses its existing thread/host plus a freshly supplied Task repository root. It explicitly reports
+that historical checkout provenance is unavailable, preserves the legacy registry bytes and
+never creates or adopts another Worker. A tracked Worker whose checkout changes still reports a
+mismatch; no automatic App handoff or silent registry migration is performed.
+
+## Later independent corrective evidence after a fix review
+
+A failed guarded Step can reveal a Plan obstruction after its immutable strict review recorded
+`fix` without a Plan conflict. On a clean current Task checkout, after at least two real remediation
+failures and with no decision already bound to the current ordinal, `next` can expose the optional
+`correctiveDecisionOption`. The ordinary fix action remains the default. No failure, repeated run,
+review rewrite or arbitrary scope extension is required to obtain an independent corrective audit.
+The option is absent while a Step runs, a pending handoff exists, or an earlier navigation gate
+blocks ordinary continuation. Existing writer/C1 actor and token requirements still apply; a
+legitimate claimed Worker credential does not disable this independent audit route.
+
+Only a genuine independent audit justifies using the existing `task corrective-decision` command.
+Its resulting append-only decision preserves the original review and completed Steps. A decision
+requiring replan leads to the existing corrective yield/prepare/confirmation route, including its
+separate Human gate; the option supplies no replacement authority, grant or permission to write
+additional files. A conflicting existing decision cannot be overwritten.
+
+The option's revision, Brief/Plan/HEAD and remediation event hashes describe the observation used
+for the audit. They are not a new apply token or additional executor-enforced hash contract: the
+existing executor checks its revision, current decision ordinal, audit independence and actor/token
+preconditions. Refresh `next` and audit evidence before recording, including after a HEAD change
+that does not change the Task revision. Never treat stale option output as authorization.

package/docs/delegated-approval.md

@@ -66,6 +66,32 @@ half of an atomic content-only Task context refresh in that Milestone. Standalon
 approval remains project-scoped. The contract does not add a generic delegation transition:
 outcome, success signal, acceptance, checks, discovery, and base branch remain immutable.
 
+## Full contract during an active Milestone
+
+The human may request `milestone autonomy-prepare` / `milestone autonomy-grant` while a
+Milestone is `active`, as well as before its initial execution. This supports first full
+issuance or replacement after expiry/revocation without resetting the Milestone, altering
+its Plan or completed Task evidence, or recreating its Worker. Planning, blocked, validating,
+final-acceptance and terminal Milestones are not eligible for this route.
+
+Preparation is read-only. It requires a coherent registered repository, a complete current
+Plan and active Knowledge Map. Its MAC binds the status, revision, Plan, semantic scope,
+principal, delegate, exact expiry (at most 72 hours), policy and previous authority state.
+Show this complete contract and obtain a separate exact human confirmation. Never renew a
+contract automatically or treat general delegated execution as permission to issue authority.
+
+A still-valid full contract cannot be replaced. An explicitly revoked or expired contract
+may be replaced using a freshly prepared MAC. The previous confirmed code cannot undo a
+revocation. Exact retries retain the same contract/grant; an interrupted event-first write
+can be completed only with its original matching confirmation. Issuance and milestone grant
+revocation share a Milestone lock. History remains append-only.
+
+`next` exposes optional `activeMilestoneAutonomyOptions` even when a linked Task is selected;
+this does not change the immediate Task action or waive its credential/review/recovery gates.
+A coexisting generic grant remains unchanged and does not gain membership evolution or atomic
+context-refresh authority. The new full contract carries those existing bounded capabilities;
+it never grants standalone Project Knowledge approval or a semantic scope change.
+
 ## Starting a delegate chat
 
 A grant does not start an agent and is not attached to a Codex chat automatically. Open a new

package/docs/pdf/sources/codex-workflow-v2-architecture-ru.md

@@ -463,7 +463,7 @@ Restart Docker Desktop требует отдельного разрешения
 # 10. Operational checklist
 
 - exact package version установлен, bundled gateway соответствует release и переустановлен;
-- handshake подтверждает `packageVersion=2.0.0-beta.13.5`, protocol 2, state schema 2 и beta.13
+- handshake подтверждает `packageVersion=2.0.0-beta.13.9`, protocol 2, state schema 2 и beta.13
   capabilities;
 - routine observation начинается с компактного `status`; `status --full` запрашивается только для
   расследования, которому действительно нужна полная historical projection;

package/docs/pdf/sources/codex-workflow-v2-chat-only-guide-ru.md

@@ -57,7 +57,7 @@ AGENTS.md
 -> doctor только как дополнительная диагностика
 ```
 
-Handshake beta.13.5 должен сообщать `packageVersion=2.0.0-beta.13.5`, `protocolVersion=2`,
+Handshake beta.13.9 должен сообщать `packageVersion=2.0.0-beta.13.9`, `protocolVersion=2`,
 `stateSchemaVersion=2`, dependency DAG, initial Plan transaction, mechanical feasibility,
 Milestone autonomy, host-safe credential reference, failed-Step continuation transaction,
 cause-bound rolling refinement, structural production edge, compact status, reviewer runtime preflight,
@@ -168,8 +168,6 @@ base HEAD. Final acceptance выполняй только по exact eligible gr
 текущему MSA-code; иначе покажи полный requiredHumanGate и остановись.
 ```
 
-<!-- pagebreak -->
-
 ## 4.1. Что должно получиться до autonomy gate
 
 - Discovery без blocking unknowns;
@@ -481,8 +479,8 @@ Task/project DGR. `dependencyBinding` для standalone handoff равен null.
 
 # 14. Итоговый checklist пользователя
 
-- beta.13.1 exact package и новый bundled gateway установлены; handshake показывает
-  `packageVersion=2.0.0-beta.13.5`, protocol/state schema `2/2` и beta.13 capabilities;
+- beta.13.9 exact package и новый bundled gateway установлены; handshake показывает
+  `packageVersion=2.0.0-beta.13.9`, protocol/state schema `2/2` и beta.13 capabilities;
 - новый Coordinator chat не является fork старого Milestone;
 - bootstrap DGR, если нужен, выдан отдельным exact human confirmation;
 - Discovery не materialized при blocking unknowns;

package/docs/pdf/sources/codex-workflow-v2-technical-reference-ru.md

@@ -15,7 +15,7 @@ authority сами: mutating permission определяется runtime state
 
 | Параметр beta.13 | Значение |
 |---|---|
-| npm package | `codex-workflow-v2@2.0.0-beta.13.5` |
+| npm package | `codex-workflow-v2@2.0.0-beta.13.9` |
 | protocolVersion | 2 |
 | stateSchemaVersion | 2 |
 | lifecycle epoch | 2 |
@@ -767,7 +767,7 @@ dirty update.
 observed-route matrix/compact-status/reviewer-runtime tests, legacy compatibility regressions,
 `npm run test:signal-t10-check-support-e2e`, `npm run test:signal-remediation-e2e`,
 `npm run pack:check`, `npm run smoke:downstream`, `npm run plugin:check`, official plugin/skill validators,
-`npm run docs:pdf:check` и `npm run release:check` с exact `v2.0.0-beta.13.5` tag binding и append-only
+`npm run docs:pdf:check` и `npm run release:check` с exact `v2.0.0-beta.13.9` tag binding и append-only
 real-agent lifecycle log. Candidate проверяется из clean source checkout; missing built module не должен
 превращаться в stack trace, а обязан быть детерминированно собран или диагностирован release gate.
 

package/docs/release.md

@@ -4,6 +4,78 @@ The npm package is `codex-workflow-v2` with public visibility. Consumers must pi
 an exact version. Stable compatibility covers the latest minor release of the current
 major only; older minors are unsupported unless a release note explicitly says otherwise.
 
+## beta.13.9: failed-Step planning recovery after Knowledge rebind
+
+A started Task can retain completed Steps and a failed guarded Step while a Knowledge
+rebind supersedes its execution authorization. A truthful blocking Plan Risk Audit must
+not require a false approval to reach corrective planning. This recovery uses the current
+blocking audit as planning evidence and proves its unchanged safety baseline through
+hash-checked Knowledge-only Plan history and the historical superseded authorization.
+It never treats either record as current execution authority.
+
+Fresh navigation can then advertise the existing independent corrective-decision route.
+The ordinary corrective yield, independent replacement validation and risk audit, exact
+human corrective-replan confirmation, and fresh execution authorization remain mandatory.
+An ordinary `plan-set` cannot bypass that chain. `continue-fix` is not a valid decision
+for this stopped planning posture; ordinary execution repair retains its existing choices.
+The additive upstream-remediation route remains limited to genuinely unstarted Tasks.
+
+Release evidence must exercise the complete callable recovery chain, including original
+Worker credential replacement and yield, repeated Knowledge rebind, unchanged completed
+Step and failed review evidence, and rejection of damaged Plan/audit/authorization history.
+
+The exact beta.13.9 runner retains the consumed-carryover compatibility profile from
+beta.13.6 with beta.13.9 as its pinned target. The source, ownership, lease, candidate
+Plan, provenance and transaction checks are unchanged. Historical beta.13.7 and
+beta.13.8 transcripts remain bound to their original targets.
+
+## beta.13.8: explain changes and continue active Milestones
+
+Full autonomy can be issued during an active Milestone using an exact new human-confirmed
+contract. Interrupted event-first issuance remains recoverable after expiry or revision change:
+a fresh confirmation may supersede an inert missing grant, preserving its event and creating a
+new grant identity. Known unpublished grant directories carry no authority; malformed state and
+unknown incomplete delegations still fail closed.
+
+The read-only `change explain` command separates execution context, external approval, semantic
+scope, bounded check-support amendment, Plan correction, membership and context refresh. It
+preserves the current Core route, including credential prerequisites and effective Step scope.
+Its proposal hash is diagnostic evidence, not permission to apply a patch.
+
+Chat dispatch records the observed child checkout and offers an advisory context check before
+writes. Existing Workers are preserved; a parent repository path does not authorize writing
+outside the actual child checkout. Model and reasoning selection remain task-specific.
+
+The exact beta.13.8 runner retains the tested beta.13.6 consumed-carryover source
+recovery profile with beta.13.8 as its pinned target. It does not admit a beta.13.7
+source or a running Step; historical beta.13.7 transcript evidence remains separately
+valid for its original target.
+
+All ordinary release gates below apply to the exact versioned candidate. Historical failed
+real-agent runs remain failed evidence; prior one-time release exceptions are not reused.
+Signal deployment additionally requires a fresh safe update boundary, exact installed provenance
+and verified continuation by the original Worker. This release does not waive external approval
+or claim to prevent every future product failure.
+
+## Active Milestone autonomy contract issuance
+
+The candidate extends full human-confirmed autonomy to an already active Milestone.
+Release evidence must cover both initial active issuance and replacement after revocation
+or expiry, without resetting Task state, changing membership/semantic scope, or replacing
+an existing Worker. A generic delegation is neither upgraded nor revoked implicitly.
+
+The MAC includes the previous contract/grant snapshot so a revoked confirmation cannot
+restore authority. Exact successful and interrupted-write retries must preserve identity;
+legacy event-first records retain their bounded pre-execution recovery. Shared Milestone
+exclusion protects issuance, revocation and scope/status transitions.
+
+Acceptance must continue through same-Worker execution and guarded atomic context refresh
+using the new full contract, with the old grant rejected without Task/Knowledge mutations.
+Include read-only preparation, stale bindings, valid-contract replacement refusal, malformed
+actors/expiry, unavailable Knowledge and disallowed Milestone states. Optional Task-first
+navigation must not replace the current execution/recovery action. Run the full test suite,
+release checks, downstream package smoke and plugin validation on the final candidate.
+
 ## beta.13.7 candidate: retire completed carryover authority
 
 After a recovered Step passed review, its recorded dirty-work permission still

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-workflow-v2",
-  "version": "2.0.0-beta.13.7",
+  "version": "2.0.0-beta.13.9",
   "description": "Requirements-first Codex development workflow with local state and explicit Git ownership.",
   "repository": {
     "type": "git",

package/plugins/codex-workflow-gateway/references/chat-dispatch.md

@@ -126,3 +126,79 @@ then mechanical lifecycle work Mini/low. Do not create another Task just to swit
 Keep the previous selection unless the phase/risk/scope changes materially. The journal records
 requested settings; tool acceptance/runtime readback, when available, is required to claim the
 actual model used. A model change never changes role, scope, credentials or approval authority.
+
+## Execution context before product writes
+
+`dispatch-begin` accepts optional `executionMode: "local" | "worktree"` (default `worktree`).
+Choose local only for an explicit user request to execute in the saved checkout. The observed
+child checkout, not an absolute path copied from the parent's prompt, is the write destination.
+`dispatch-observe` records it and refuses silent movement of a bound child.
+
+Before the first write, and after any branch/cwd change, use read-only `dispatch-context-check`
+with a fresh App observation, `writeRoot`, and `expectedBranch` from the current Core Task.
+Require `matched=true`, then refresh Core next and writer authority. Mismatch means reconcile the
+same Worker context; it never permits another create, an indirect write or an automatic handoff.
+A matched context does not authorize external operations. See packaged `docs/change-model.md`.
+
+### Existing legacy bindings
+
+`dispatch-context-check` also accepts an already bound legacy entry with no dispatch marker.
+Supply the exact current Task `repositoryRoot` in addition to the fresh actual Worker observation,
+`writeRoot`, and `expectedBranch`. The check verifies the bound thread/host, common Git repository,
+actual checkout/write root and Task branch without changing the registry. It reports
+`contextBinding=legacy-current-observation` and `historicalCheckoutVerified=false`: no historical
+creation marker or checkout provenance is invented. It never enables another create permit.
+This observation does not move a chat, authorize a write or reconcile a tracked dispatch whose
+previous checkout changed; those remain explicit App/context operations followed by fresh checks.
+
+### Explicit App handoff reconciliation
+
+An App handoff can return a new destination thread ID while retaining the task history.
+`bind` still rejects replacing a bound child. After the App operation succeeds, use the
+separate `dispatch-handoff-reconcile --reservation-id ... --file ... --project-id ...` route:
+
+```json
+{
+  "sourceThreadId": "actual-source-thread-uuid-from-the-handoff-call",
+  "sourceHostId": "local",
+  "repositoryRoot": "/absolute/repository-from-fresh-Task",
+  "expectedBranch": "exact-task-branch",
+  "receipt": {
+    "operationId": "actual-operation-id",
+    "revision": 12,
+    "status": "success",
+    "destinationThreadId": "actual-destination-thread-uuid",
+    "destinationHostId": "local",
+    "destinationCwd": "/absolute/destination-checkout",
+    "threadTitle": "exact-current-bound-title"
+  },
+  "observation": { "thread": {
+    "id": "actual-destination-thread-uuid",
+    "hostId": "local",
+    "kind": "codex",
+    "cwd": "/absolute/destination-checkout",
+    "title": "exact-current-bound-title"
+  } }
+}
+```
+
+Copy the complete successful `get_handoff_status` receipt, including any extra returned fields,
+and obtain a fresh destination `read_thread`. Preserve the source `handoff_thread` tool call:
+its source ID is supplied separately because the result need not contain it. Pending, failed,
+cancelled or inconsistent results cannot change the registry. The destination must match the
+bound title, actual Git repository and current Task branch, and cannot belong to another entry.
+
+This route changes only the existing reservation's current thread/host and, for tracked dispatch,
+current execution context. An append-only `handoffHistory` retains the receipt, source and prior
+dispatch snapshot; the original creation marker is never fabricated for legacy entries. Existing
+observations and selection history are preserved. A tracked supervisor's old cursor is cleared
+so it must observe the destination again. No create permit, grant, Task claim or lifecycle
+transition is issued. Ordinary `dispatch-observe` still rejects an unexplained checkout change.
+An exact retry of the latest handoff leaves registry bytes unchanged; changed receipts or replay
+of a superseded handoff are rejected. Refresh Core status/next and writer authority after handoff.
+
+These caller-supplied App results are coherence evidence, not cryptographic proof of origin or
+external write authority. The coordinator must obtain genuine tool results and independently
+check retained history and the safe writer boundary. The package does not execute a handoff,
+verify arbitrary transcript continuity, or authorize writes merely because reconciliation passes.
+Only destinations readable on the checking host with the same Git common directory are supported.

package/plugins/codex-workflow-gateway/scripts/chat-dispatch.mjs

@@ -5,6 +5,8 @@ import path from 'node:path';
 import { selectChatModel } from './chat-model-policy.mjs';
 
 const hash = text => createHash('sha256').update(text).digest('hex');
+const canonical = value => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+  ? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item);
 const text = (value, name) => {
   if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} is required.`);
   return value.trim();
@@ -31,10 +33,12 @@ function promptMatches(value, digest) {
 }
 function view(entry) {
   const d = entry.dispatch;
+
   return {
     reservationId: entry.reservationId, state: d?.state ?? (entry.threadId ? 'legacy-bound' : 'untracked'),
     createAllowed: false, dispatchId: d?.id ?? null, clientThreadId: d?.clientThreadId ?? null,
     threadId: entry.threadId ?? d?.candidateThreadId ?? null, hostId: d?.hostId ?? entry.hostId ?? null,
+    executionContext: d?.executionContext ?? null,
     selection: d?.selection ?? null, supervision: d?.supervision ?? null,
     candidates: d?.candidates ?? [],
     nextAction: entry.threadId ? 'supervise-existing' : d?.state === 'resolved' ? 'title-readback-and-bind'
@@ -49,6 +53,8 @@ export function dispatchAction(action, entry, input = {}) {
     if (entry.status === 'abandoned' || entry.status === 'blocked') throw new Error('Reservation is not dispatchable.');
     const repositoryRoot = realpathSync(text(input.repositoryRoot, 'repositoryRoot'));
     const gitDir = commonGitDir(repositoryRoot);
+    const executionMode = input.executionMode ?? 'worktree';
+    if (!['local', 'worktree'].includes(executionMode)) throw new Error('executionMode must be local or worktree.');
     const appProjectId = text(input.appProjectId, 'appProjectId');
     const hostId = text(input.hostId, 'hostId');
     const promptPath = realpathSync(text(input.promptFile, 'promptFile'));
@@ -58,19 +64,116 @@ export function dispatchAction(action, entry, input = {}) {
     const selection = selectChatModel(entry.type, input.modelRequest);
     const id = randomUUID();
     const marker = `[workflow-dispatch:${id}:${hash(prompt)}]`;
-    const dispatchedPrompt = `${marker}\n${prompt}`;
+    const dispatchedPrompt = `${marker}\n${prompt}\nExecution boundary: use the actual child checkout returned by App readback. Before any write, reconcile it with the exact Task branch and run dispatch-context-check. A repository path in this packet is identity context, not authorization to write outside that checkout.`;
     entry.dispatch = {
-      version: 1, id, state: 'creating', appProjectId, hostId, repositoryRoot, gitDir,
+      version: 1, id, state: 'creating', appProjectId, hostId, repositoryRoot, gitDir, executionMode,
       promptPath, promptHash: hash(prompt), dispatchedPromptHash: hash(dispatchedPrompt), marker,
       selection, selectionHistory: [selection], clientThreadId: null, candidateThreadId: null,
       candidates: [], observations: [], createdAt: new Date().toISOString(),
     };
     return { ...view(entry), createAllowed: true, nextAction: 'create-thread-once', createArgs: {
-      target: { type: 'project', projectId: appProjectId, environment: { type: 'worktree' } },
+      target: { type: 'project', projectId: appProjectId, environment: { type: executionMode } },
       title: entry.requestedTitle, prompt: dispatchedPrompt, model: selection.model, thinking: selection.thinking,
     } };
   }
   const d = entry.dispatch;
+  if (action === 'dispatch-handoff-reconcile') {
+    const receipt = input.receipt;
+    const t = input.observation?.thread;
+    const sourceThreadId = actualId(input.sourceThreadId);
+    const sourceHostId = text(input.sourceHostId, 'sourceHostId');
+    const operationId = text(receipt?.operationId, 'handoff operationId');
+    if (receipt?.status !== 'success' || !Number.isSafeInteger(receipt.revision) || receipt.revision < 1
+      || !Array.isArray(receipt.steps) || receipt.steps.length === 0
+      || receipt.steps.some(step => !step || typeof step.id !== 'string' || !step.id || step.status !== 'done')) {
+      throw new Error('Require a successful completed App handoff receipt.');
+    }
+    const destinationThreadId = actualId(receipt.destinationThreadId);
+    const destinationHostId = text(receipt.destinationHostId, 'destinationHostId');
+    if (!entry.titleVerified || entry.status !== 'bound' || !entry.threadId
+      || receipt.threadTitle !== entry.observedTitle || receipt.threadTitle !== entry.requestedTitle
+      || t?.kind !== 'codex' || t.id !== destinationThreadId || t.hostId !== destinationHostId
+      || t.title !== receipt.threadTitle) throw new Error('Handoff requires the exact bound title and destination readback.');
+    const cwd = realpathSync(text(t.cwd, 'destination cwd'));
+    if (cwd !== realpathSync(text(receipt.destinationCwd, 'receipt destinationCwd'))) {
+      throw new Error('Handoff destination cwd does not match its receipt.');
+    }
+    const root = realpathSync(execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', timeout: 5000 }).trim());
+    const repositoryRoot = realpathSync(text(input.repositoryRoot, 'repositoryRoot from fresh Task'));
+    const gitDir = commonGitDir(repositoryRoot);
+    const expectedBranch = text(input.expectedBranch, 'expectedBranch from fresh Task');
+    if (commonGitDir(root) !== gitDir || (d && d.gitDir !== gitDir)
+      || execFileSync('git', ['branch', '--show-current'], { cwd: root, encoding: 'utf8', timeout: 5000 }).trim() !== expectedBranch) {
+      throw new Error('Handoff repository or Task branch mismatch.');
+    }
+    const binding = { sourceThreadId, sourceHostId, receipt, repositoryRoot, expectedBranch,
+      destination: { threadId: destinationThreadId, hostId: destinationHostId, cwd, checkoutRoot: root, title: t.title } };
+    const bindingHash = hash(canonical(binding));
+    const history = entry.handoffHistory ?? [];
+    const previous = history.find(event => event.operationId === operationId);
+    if (previous) {
+      if (previous.bindingHash !== bindingHash || history.at(-1) !== previous
+        || entry.threadId !== destinationThreadId || entry.hostId !== destinationHostId) {
+        throw new Error('Handoff operation was already recorded with a different binding or superseded.');
+      }
+      return { ...view(entry), handoffOperationId: operationId, idempotentRetry: true };
+    }
+    if (entry.threadId !== sourceThreadId || entry.hostId !== sourceHostId
+      || (d && (d.hostId !== sourceHostId || d.candidateThreadId !== sourceThreadId))) {
+      throw new Error('Handoff source must match the currently bound Worker.');
+    }
+    const recordedAt = new Date().toISOString();
+    // Receipt input is coherence evidence, not a signed App capability. Preserve the
+    // complete prior dispatch instead of relabeling its original creation history.
+    entry.handoffHistory = [...history, { operationId, bindingHash, ...binding, recordedAt,
+      priorDispatch: d ? structuredClone(d) : null }];
+    entry.threadId = destinationThreadId;
+    entry.hostId = destinationHostId;
+    if (d) {
+      d.hostId = destinationHostId;
+      d.candidateThreadId = destinationThreadId;
+      d.executionContext = { checkoutRoot: root, gitDir, threadId: destinationThreadId, hostId: destinationHostId };
+      d.executionMode = root === d.repositoryRoot ? 'local' : 'worktree';
+      d.candidates = [];
+      d.duplicateDisposition = null;
+      d.state = 'resolved';
+      d.observations.push({ threadId: destinationThreadId, hostId: destinationHostId, cwd, title: t.title,
+        observedAt: recordedAt, handoffOperationId: operationId });
+      if (d.supervision) d.supervision = { ...d.supervision, cursor: null,
+        state: 'attention', nextAction: 'refresh-destination-observation-and-core-next', updatedAt: recordedAt };
+    }
+    return { ...view(entry), handoffOperationId: operationId, idempotentRetry: false };
+  }
+  if (action === 'dispatch-context-check') {
+    // A fresh observation is mandatory; prior readback is not a filesystem capability.
+    const t = input.observation?.thread;
+    if (!entry.threadId || t?.id !== entry.threadId || t.kind !== 'codex' || t.hostId !== (d?.hostId ?? entry.hostId)) {
+      throw new Error('Require a fresh observation of the bound Worker.');
+    }
+    const cwd = realpathSync(text(t.cwd, 'thread cwd'));
+    const writeRoot = realpathSync(text(input.writeRoot, 'writeRoot'));
+    const root = realpathSync(execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd, encoding: 'utf8', timeout: 5000,
+    }).trim());
+    const branch = execFileSync('git', ['branch', '--show-current'], {
+      cwd: root, encoding: 'utf8', timeout: 5000,
+    }).trim();
+    const expectedBranch = text(input.expectedBranch, 'expectedBranch from fresh Task');
+    const reasons = [];
+    const expectedGitDir = d?.gitDir ?? commonGitDir(realpathSync(text(input.repositoryRoot, 'repositoryRoot from fresh Task')));
+    if (commonGitDir(root) !== expectedGitDir) reasons.push('REPOSITORY_MISMATCH');
+    if (d && d.executionContext?.checkoutRoot !== root) reasons.push('WORKER_CHECKOUT_CHANGED');
+    if (writeRoot !== root) reasons.push('WRITE_ROOT_MISMATCH');
+    if (branch !== expectedBranch) reasons.push('TASK_BRANCH_MISMATCH');
+    return { kind: 'execution-context-check', readOnly: true, authority: 'none',
+      matched: reasons.length === 0, reasons, threadId: entry.threadId,
+      contextBinding: d ? 'tracked-dispatch' : 'legacy-current-observation',
+      historicalCheckoutVerified: Boolean(d?.executionContext),
+      checkoutRoot: root, writeRoot, branch, expectedBranch,
+      nextAction: reasons.length ? 'reconcile-existing-worker-context' : 'refresh-core-next-and-writer-authority',
+      limitations: ['This check does not grant filesystem access or override external approval.',
+        'Recheck before a write after cwd or branch changes. No automatic handoff or duplicate dispatch.'] };
+  }
   if (!d) throw new Error('No tracked dispatch; reconcile legacy chats manually, never assume creation failed.');
   if (action === 'dispatch-result') {
     const result = input.result;
@@ -157,6 +260,16 @@ export function dispatchAction(action, entry, input = {}) {
       || (candidate && realpathSync(t.cwd) !== candidate.cwd)) throw new Error('Readback repository/cwd mismatch.');
     if (t.projectId !== undefined && t.projectId !== d.appProjectId) throw new Error('Readback App project mismatch.');
     if (d.candidateThreadId && d.candidateThreadId !== id) throw new Error('Readback differs from create result.');
+    const checkoutRoot = realpathSync(execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: t.cwd, encoding: 'utf8', timeout: 5000,
+    }).trim());
+    if (d.executionMode === 'local' && checkoutRoot !== d.repositoryRoot) {
+      throw new Error('Local dispatch readback checkout mismatch.');
+    }
+    if (d.executionContext && d.executionContext.checkoutRoot !== checkoutRoot) {
+      throw new Error('Bound Worker checkout changed; reconcile context without replacing the child.');
+    }
+    d.executionContext = { checkoutRoot, gitDir: d.gitDir, threadId: id, hostId: d.hostId };
     d.candidateThreadId = id;
     d.state = 'resolved';
     d.observations.push({ threadId: id, hostId: t.hostId, cwd: realpathSync(t.cwd),

package/plugins/codex-workflow-gateway/scripts/chat-registry.mjs

@@ -170,8 +170,13 @@ export function dispatchChat(options) {
   return withRegistryLock(options.projectId, options.registryHome, file => {
     const registry = readRegistry(file, options.projectId);
     const entry = requireEntry(registry, options.reservationId);
+    if (options.action === 'dispatch-handoff-reconcile') {
+      const destination = options.input?.observation?.thread;
+      if (registry.entries.some(other => other !== entry && other.threadId === destination?.id
+        && other.hostId === destination?.hostId)) throw new Error('Handoff destination already belongs to another reservation.');
+    }
     const result = dispatchAction(options.action, entry, options.input);
-    if (options.action !== 'dispatch-status') {
+    if (!['dispatch-status', 'dispatch-context-check'].includes(options.action) && result.idempotentRetry !== true) {
       entry.updatedAt = new Date().toISOString();
       writeRegistry(file, registry);
     }