codex-workflow-v2 2.0.0-beta.13.1 → 2.0.0-beta.13.11

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

@@ -0,0 +1,204 @@
+# Durable App dispatch and explicit model selection
+
+This is an App orchestration journal, not Workflow authority. It does not call the App, approve
+Git writes, renew grants, mint credentials, or replace Core status/next. All commands below use
+`node <exact-package>/plugins/codex-workflow-gateway/scripts/chat-registry.mjs` and the existing
+24-hex Workflow `--project-id`. The App project ID is a separate field.
+
+## One reservation, one creation attempt
+
+`allocate` reuses the same non-abandoned role/entity/membership/attempt reservation. Task and
+Coordinator allocations also reuse it when a caller changes the attempt number. Review attempts
+advance only after the actual Workflow review cycle advances. Never invent a new attempt or
+reservation to bypass unresolved creation. Existing v1 registries remain readable; legacy bound
+threads remain usable with explicit model/thinking arguments from the same policy; `model-select`
+and `supervision-record` currently require a tracked dispatch and do not retrofit legacy evidence.
+Legacy unbound reservations may have already created a chat: reconcile
+those using real App/source evidence before using the new dispatch flow.
+
+1. Save the closed context packet to a private local file. Do not include bearer credentials,
+   parent transcript, or approval narratives. Prepare a private dispatch request JSON:
+
+   ```json
+   {
+     "repositoryRoot": "/absolute/canonical/repository",
+     "appProjectId": "project-id-from-list-projects",
+     "hostId": "local",
+     "promptFile": "/private/tmp/task-context.txt",
+     "modelRequest": {
+       "phase": "planning",
+       "complexity": "standard",
+       "highRisk": false,
+       "rationale": "New multi-file implementation plan with established requirements.",
+       "availableModels": [
+         {"id": "gpt-5.6-sol", "reasoningEfforts": ["low", "medium", "high", "xhigh", "max", "ultra"]}
+       ]
+     }
+   }
+   ```
+
+   Populate `availableModels` from the destination App tool's actual model/effort contract, not
+   this example, the parent's settings, API pricing pages, or a guessed alias. Explicit user
+   authorization to select models is required; journal input is not user authorization.
+2. Run `dispatch-begin --reservation-id ID --file request.json` **before** `create_thread`.
+   Save its complete output to a mode-600 file. It atomically persists a creation marker, packet
+   hashes, repository binding and requested model selection, then returns `createAllowed:true`
+   and exact `createArgs` including `model` and App field `thinking`.
+3. Only the process receiving that one permission may make **one** `create_thread(createArgs)`
+   call. A second begin, even after restart or timeout, returns `createAllowed:false` and no
+   create arguments. Do not reissue the external call after a lost/ambiguous response. The marker
+   prepended to the packet is routing provenance, not parent history.
+4. Save the full App result locally, normalize its successful tool text JSON to
+   `{"result":{"clientThreadId":"client-new-thread:...","hostId":"local"}}` or
+   `{"result":{"threadId":"actual-uuid","hostId":"local"}}`, and run `dispatch-result`.
+   Preserve raw evidence separately. Never parse truncated displayed stdout as the full receipt.
+   Invalid JSON cannot change the journal. A pending client ID is never a usable thread ID.
+5. Use `dispatch-status` to resume. Missing `list_threads` results are not proof of failure.
+   If the actual ID is unavailable, identify candidate rollout files from creation-time/worktree
+   evidence and run `dispatch-discover --file candidates.json`, where the file is
+   `{"sessionFiles":["/absolute/rollout.jsonl"]}`. The helper reads only supplied files, checks
+   actual session metadata, exact original dispatched prompt (including the App's routing XML),
+   and the Git common directory. It ignores guardian/subagent sessions and unrelated prompts.
+   It prints candidate IDs/paths only, never transcripts or reasoning. Use bounded candidate
+   lists, not vault searches. Malformed, oversized or partially written files need a later fresh
+   read; they never authorize another creation.
+6. Confirm a correlated candidate using `read_thread`. Save its full response as
+   `{"observation": <parsed read_thread JSON>}` and run `dispatch-observe`. It checks actual UUID,
+   host, repository/worktree and App project when supplied. One candidate still requires App
+   readback; several candidates produce a duplicate conflict and require explicit disposition,
+   not arbitrary selection. After confirming one canonical child, inspect every other candidate,
+   reconcile any work it performed, and archive only idle duplicates. Record
+   `dispatch-resolve-duplicates` with `canonicalThreadId` and `dispositions`, one object per duplicate:
+   `{threadId, observation: <read_thread JSON>, archiveResult: {threadId, archived: true}}`.
+   Preserve the actual archive tool receipt; never fabricate it. Repeat canonical readback and bind.
+   Candidate history is retained and no creation permit is restored. This is a local evidence
+   check, not independent App attestation.
+7. Run ordinary title `readback`/rename until exact match. After any rename, repeat
+   `dispatch-observe` with fresh App readback, then `readback` and `bind`. Binding a tracked
+   dispatch requires the same actual ID, host and observed title. Rebinding it to another child,
+   binding a client ID or sharing one child between reservations is rejected.
+8. Run `supervision-record --file report.json` with `threadId`, `ownerThreadId`, `state`
+   (`active|attention|completed`), `cursor` and `nextAction`. Persist significant wait boundaries;
+   only that supervisor waits for this child. The journal stores routing state, not a Workflow
+   verdict. Do not put secrets, CREFs or confirmation codes in it. On restart, read the child and
+   fresh Core status/next before continuing. Worker reports stay local; the coordinator pulls.
+
+A crash between durable begin and actual submission is deliberately ambiguous. There is no
+App idempotency-key API here, so this provides **at most one create permit per reservation**,
+not an exactly-once guarantee. Never clear the marker, abandon it, or expire it by time to retry.
+If no positive creation evidence can be found, report that exact unresolved App operation. A
+permission denial is a separate real gate; do not reroute it through another chat. Fresh user
+approval does not establish that an ambiguous prior creation never happened.
+
+## Model matrix
+
+The versioned policy is `scripts/chat-model-policy.mjs`. It expresses a conservative relative
+cost/latency preference, not measured savings or guaranteed account availability:
+
+| Work | Preferred model | App thinking | Compatible fallback |
+| --- | --- | --- | --- |
+| Routine mechanical transitions, formatting, retrieval | gpt-5.4-mini | low | gpt-5.6-luna / low |
+| Coordinator supervision; small implementation | gpt-5.6-luna | medium | gpt-5.6-terra / medium |
+| Standard implementation | gpt-5.6-terra | medium | gpt-5.6-sol / medium |
+| Task planning | gpt-5.6-sol | medium | gpt-6-astra / medium |
+| Routine Step review | gpt-5.6-terra | medium | gpt-5.6-sol / medium |
+| Standard Step review, final review, plan/corrective audit | gpt-5.6-sol | high | gpt-6-astra / high |
+| Complex work or high risk, any role | gpt-6-astra | high | gpt-5.6-sol / high |
+
+`routine` means a small, well-specified change or mechanical action with an existing check;
+`standard` is ordinary multi-file work; `complex` covers new architecture, unresolved concurrency,
+recovery/provenance or distributed state. Mark `highRisk` for authorization, security-sensitive
+paths, data-loss exposure or irreversible migrations. The coordinator records the concrete
+rationale; classification is a human/agent judgment, not an automatic risk detector. Unknown
+complexity is not routine. Review/audit role floors override a falsely mechanical phase. No
+automatic xhigh/max/ultra, and no escalation merely because a review failed or a tool timed out.
+
+The policy chooses only a listed supported pair. If neither preferred nor fallback pair is
+available, stop selection rather than silently inheriting the coordinator or lowering the review
+floor. API docs explain the reasoning/latency tradeoff, while App availability and accepted field
+names come from the live App tool contract:
+https://developers.openai.com/api/docs/guides/latest-model
+
+For a phase change in an existing bound chat, call `model-select` with its same `threadId` and
+fresh `modelRequest`; copy the returned `followUpArgs` into `send_message_to_thread` with the
+closed follow-up prompt. For example, planning uses Sol/medium, implementation Terra/medium,
+then mechanical lifecycle work Mini/low. Do not create another Task just to switch model.
+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/references/protocol.md

@@ -56,10 +56,21 @@
   A provenance recovery recorded after the final context-refresh audit may explain exactly one
   additional Task revision only when it belongs to that verified Git chain. Any unexplained
   revision remains a `doctor` boundary.
+- Before a credential-consuming mutation, check the public `writerCredentialReference.expiresAt`
+  against the current time and its actor/action binding. Lease heartbeat or renewal does not
+  extend that reference's expiry. An expired, missing, consumed or unverifiable reference requires
+  the simultaneously advertised `next.writerCredentialRecovery` action with its exact Task,
+  revision and `requiredActor`, followed by fresh `status` and `next`; use the new reference.
+  If no recovery is advertised, stop before mutation. Never read or patch the vault, extend expiry
+  manually, or reuse the old reference. This check also applies after independent reviews and pauses.
 - `milestone progress --id <MS-ID>` is a read-only projection and the sole source for Coordinator
   progress tables. It preserves cancelled/replacement Tasks as distinct membership rows.
 - `scripts/chat-registry.mjs` atomically allocates project-monotonic `#NNN`, builds all six title
   families, verifies exact readback, supplies deterministic fallbacks, and binds the verified chat.
+  It also journals a single creation permit, pending/actual IDs, evidence-based resolution and
+  supervision cursors. Missing App listings never permit a retry. See `chat-dispatch.md` for
+  dispatch commands and the explicit role/phase model + thinking policy. These are App routing
+  helpers; they do not change Workflow protocol/state schema or grant approval authority.
 
 ## Handshake
 

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

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+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();
+};
+const actualId = value => {
+  const id = text(value, 'actual threadId');
+  if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(id)) throw new Error('Expected actual thread UUID, not clientThreadId.');
+  return id;
+};
+function jsonFile(file) {
+  if (statSync(file).size > 16 * 1024 * 1024) throw new Error('Input file exceeds 16 MiB.');
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+function commonGitDir(cwd) {
+  return realpathSync(execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+    cwd, encoding: 'utf8', timeout: 5000, maxBuffer: 1024 * 1024,
+  }).trim());
+}
+function promptMatches(value, digest) {
+  if (typeof value !== 'string') return false;
+  if (hash(value) === digest) return true;
+  const wrapped = /^<codex_delegation>\s*<source_thread_id>[^<]+<\/source_thread_id>\s*<input>([\s\S]*)<\/input>\s*<\/codex_delegation>$/.exec(value);
+  return wrapped !== null && hash(wrapped[1]) === 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'
+      : d ? 'resolve-existing-creation' : 'dispatch-begin',
+  };
+}
+export function dispatchAction(action, entry, input = {}) {
+  if (action === 'dispatch-status') return view(entry);
+  if (action === 'dispatch-begin') {
+    // A durable marker is committed BEFORE the external call. Even a lost response never permits another call.
+    if (entry.dispatch || entry.threadId) return view(entry);
+    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'));
+    if (statSync(promptPath).size > 1024 * 1024) throw new Error('TaskContextPacket exceeds 1 MiB.');
+    const prompt = readFileSync(promptPath, 'utf8');
+    if (!prompt.trim() || !prompt.includes(entry.entityId)) throw new Error('Prompt must include the exact entity ID.');
+    const selection = selectChatModel(entry.type, input.modelRequest);
+    const id = randomUUID();
+    const marker = `[workflow-dispatch:${id}:${hash(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, 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: 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;
+    if (!result || result.hostId !== d.hostId) throw new Error('Create result host mismatch.');
+    if (result.threadId && result.clientThreadId) throw new Error('Ambiguous create result.');
+    if (result.threadId) {
+      const id = actualId(result.threadId);
+      if (d.candidateThreadId && d.candidateThreadId !== id) throw new Error('Conflicting actual thread IDs.');
+      d.candidateThreadId = id;
+    } else {
+      const id = text(result.clientThreadId, 'clientThreadId');
+      if (!id.startsWith('client-new-thread:')) throw new Error('Invalid pending clientThreadId.');
+      if (d.clientThreadId && d.clientThreadId !== id) throw new Error('Conflicting creation attempts; reconcile duplicates.');
+      d.clientThreadId = id;
+    }
+    if (d.state === 'creating') d.state = 'pending';
+    return view(entry);
+  }
+  if (action === 'dispatch-discover') {
+    // Read only specifically supplied session files; never scan credential stores or print transcripts/reasoning.
+    if (!Array.isArray(input.sessionFiles) || input.sessionFiles.length > 200) throw new Error('Supply at most 200 candidate session files.');
+    const found = new Map(d.candidates.map(c => [c.threadId, c]));
+    for (const file of input.sessionFiles) {
+      if (statSync(file).size > 16 * 1024 * 1024) throw new Error('Session exceeds 16 MiB; narrow evidence required.');
+      const lines = readFileSync(file, 'utf8').split('\n');
+      const meta = JSON.parse(lines[0]).payload;
+      if (!meta || !['vscode', 'cli'].includes(meta.source) || typeof meta.cwd !== 'string') continue;
+      const rows = lines.slice(1).filter(Boolean).map(line => JSON.parse(line));
+      const bound = rows.some(row => {
+        if (row.type !== 'response_item') return false;
+        const p = row.payload;
+        // Actual App rollout format: a create_thread function output containing routing-only XML.
+        if (p?.type === 'function_call_output' && p.name === 'create_thread' && p.namespace === 'codex_app') {
+          return promptMatches(p.output, d.dispatchedPromptHash);
+        }
+        return p?.type === 'message' && p.role === 'user' && p.content?.some(c =>
+          ['input_text', 'text'].includes(c.type) && promptMatches(c.text, d.dispatchedPromptHash));
+      });
+      if (!bound) continue;
+      if (commonGitDir(meta.cwd) !== d.gitDir) throw new Error('Session belongs to another repository.');
+      const id = actualId(meta.id);
+      found.set(id, { threadId: id, cwd: realpathSync(meta.cwd), sourceFile: realpathSync(file) });
+    }
+    d.candidates = [...found.values()];
+    if (d.candidates.length > 1) d.state = 'duplicate-conflict';
+    return view(entry);
+  }
+  if (action === 'dispatch-resolve-duplicates') {
+    const canonical = actualId(input.canonicalThreadId);
+    if (entry.threadId && entry.threadId !== canonical) throw new Error('Cannot replace a bound child.');
+    if (d.candidateThreadId && d.candidateThreadId !== canonical) throw new Error('Cannot replace the correlated create result.');
+    if (!d.candidates.some(c => c.threadId === canonical)) throw new Error('Canonical child must be a discovered candidate.');
+    const others = d.candidates.filter(c => c.threadId !== canonical);
+    if (!others.length || !Array.isArray(input.dispositions) || input.dispositions.length !== others.length) {
+      throw new Error('Require one idle readback and archive receipt for every duplicate.');
+    }
+    const receipts = others.map(candidate => {
+      const matching = input.dispositions.filter(x => x?.threadId === candidate.threadId);
+      if (matching.length !== 1) throw new Error('Duplicate disposition missing or repeated.');
+      const item = matching[0];
+      const t = item.observation?.thread;
+      if (t?.id !== candidate.threadId || t.kind !== 'codex' || t.hostId !== d.hostId
+        || t.status?.type !== 'idle' || realpathSync(text(t.cwd, 'duplicate cwd')) !== candidate.cwd
+        || commonGitDir(t.cwd) !== d.gitDir || item.archiveResult?.threadId !== candidate.threadId
+        || item.archiveResult?.archived !== true) throw new Error('Duplicate requires matching idle readback and successful archive receipt.');
+      return { threadId: candidate.threadId, archived: true, recordedAt: new Date().toISOString() };
+    });
+    d.duplicateDisposition = { canonicalThreadId: canonical, archived: receipts };
+    d.state = 'pending';
+    return view(entry);
+  }
+  if (action === 'dispatch-observe') {
+    const observation = input.observation;
+    const t = observation?.thread;
+    if (!t || t.kind !== 'codex' || t.hostId !== d.hostId) throw new Error('Require actual Codex read_thread observation on the bound host.');
+    const id = actualId(t.id);
+    if (d.candidates.length > 1 && (d.duplicateDisposition?.canonicalThreadId !== id
+      || d.candidates.some(c => c.threadId !== id && !d.duplicateDisposition.archived.some(a => a.threadId === c.threadId)))) {
+      throw new Error('Multiple candidates: explicit duplicate disposition required before binding.');
+    }
+    const candidate = d.candidates.find(c => c.threadId === id);
+    if (id !== d.candidateThreadId && !candidate) throw new Error('Uncorrelated thread; require create result or exact session prompt evidence.');
+    if (commonGitDir(text(t.cwd, 'thread cwd')) !== d.gitDir
+      || (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),
+      title: text(t.title, 'observed title'), observedAt: new Date().toISOString() });
+    return view(entry);
+  }
+  if (action === 'supervision-record') {
+    if (!entry.threadId || input.threadId !== entry.threadId || input.ownerThreadId === entry.threadId) throw new Error('Require bound child and separate supervisor.');
+    const owner = actualId(input.ownerThreadId);
+    if (d.supervision && d.supervision.ownerThreadId !== owner) throw new Error('Supervisor already assigned; no parallel wait owner.');
+    if (!['active', 'attention', 'completed'].includes(input.state)) throw new Error('Invalid supervision state.');
+    d.supervision = { ownerThreadId: owner, state: input.state, cursor: input.cursor == null ? null : text(input.cursor, 'cursor'),
+      nextAction: text(input.nextAction, 'nextAction'), updatedAt: new Date().toISOString() };
+    return view(entry);
+  }
+  if (action === 'model-select') {
+    if (!entry.threadId || input.threadId !== entry.threadId) throw new Error('Phase changes require the same bound thread.');
+    const selection = selectChatModel(entry.type, input.modelRequest);
+    d.selection = selection;
+    d.selectionHistory.push(selection);
+    return { ...view(entry), followUpArgs: { threadId: entry.threadId, hostId: entry.hostId,
+      model: selection.model, thinking: selection.thinking } };
+  }
+  throw new Error(`Unknown dispatch action: ${action}`);
+}
+export function dispatchInput(file) { return jsonFile(file); }

package/plugins/codex-workflow-gateway/scripts/chat-model-policy.mjs

@@ -0,0 +1,43 @@
+// Relative cost/latency policy, not a price list or an availability oracle.
+export const MODEL_POLICY_VERSION = 'chat-model-policy-v1';
+const PROFILES = {
+  mechanical: [['gpt-5.4-mini', 'low'], ['gpt-5.6-luna', 'low']],
+  scoped: [['gpt-5.6-luna', 'medium'], ['gpt-5.6-terra', 'medium']],
+  implementation: [['gpt-5.6-terra', 'medium'], ['gpt-5.6-sol', 'medium']],
+  planning: [['gpt-5.6-sol', 'medium'], ['gpt-6-astra', 'medium']],
+  review: [['gpt-5.6-sol', 'high'], ['gpt-6-astra', 'high']],
+  'scoped-review': [['gpt-5.6-terra', 'medium'], ['gpt-5.6-sol', 'medium']],
+  complex: [['gpt-6-astra', 'high'], ['gpt-5.6-sol', 'high']],
+};
+const TYPES = ['coordinator', 'task', 'step-review', 'final-review', 'corrective-audit', 'plan-audit'];
+export function selectChatModel(type, request) {
+  if (!TYPES.includes(type)) throw new Error('Unknown chat type.');
+  if (!request || !['routine', 'standard', 'complex'].includes(request.complexity)
+    || !['planning', 'implementation', 'mechanical', 'review', 'coordination'].includes(request.phase)
+    || typeof request.rationale !== 'string' || !request.rationale.trim()
+    || typeof request.highRisk !== 'boolean') throw new Error('Explicit phase, complexity, highRisk and rationale are required.');
+  if (!Array.isArray(request.availableModels) || request.availableModels.length === 0
+    || request.availableModels.some(m => !m || typeof m.id !== 'string' || !Array.isArray(m.reasoningEfforts)
+      || m.reasoningEfforts.some(e => typeof e !== 'string'))
+    || new Set(request.availableModels.map(m => m.id)).size !== request.availableModels.length) {
+    throw new Error('Provide the destination host model/effort catalog; never infer availability.');
+  }
+  const reviewRole = type.endsWith('review') || type.endsWith('audit');
+  let profile;
+  if (request.highRisk || request.complexity === 'complex') profile = 'complex';
+  else if (type === 'step-review' && request.complexity === 'routine') profile = 'scoped-review';
+  else if (reviewRole || request.phase === 'review') profile = 'review';
+  else if (request.phase === 'planning') profile = 'planning';
+  else if (request.phase === 'mechanical') {
+    if (request.complexity !== 'routine') throw new Error('Mechanical phase requires routine complexity.');
+    profile = 'mechanical';
+  } else if (type === 'coordinator' || request.phase === 'coordination' || request.complexity === 'routine') profile = 'scoped';
+  else profile = 'implementation';
+  const selected = PROFILES[profile].find(([id, effort]) => request.availableModels.some(m => m.id === id && m.reasoningEfforts.includes(effort)));
+  if (!selected) throw new Error(`No supported model/effort for ${profile}; explicit policy revision required, never inherit coordinator settings.`);
+  return {
+    policyVersion: MODEL_POLICY_VERSION, profile, model: selected[0], thinking: selected[1],
+    phase: request.phase, complexity: request.complexity, highRisk: request.highRisk,
+    rationale: request.rationale.trim(), fallback: selected !== PROFILES[profile][0],
+  };
+}