codex-workflow-v2 2.0.0-beta.13 → 2.0.0-beta.13.10

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],
+  };
+}

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

@@ -12,6 +12,7 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { randomUUID } from 'node:crypto';
+import { dispatchAction, dispatchInput } from './chat-dispatch.mjs';
 
 const TYPES = new Set(['coordinator', 'task', 'step-review', 'final-review', 'corrective-audit', 'plan-audit']);
 const LOCK_STALE_MS = 30_000;
@@ -25,6 +26,14 @@ export function allocateChat(options) {
     const sequence = registry.nextSequence;
     const reservationId = randomUUID();
     const candidates = buildTitleCandidates({ ...options, sequence });
+    const existing = registry.entries.find(entry => entry.status !== 'abandoned'
+      && entry.type === options.type && entry.entityId === options.entityId
+      && entry.milestoneOrdinal === requiredOrdinal(options.milestoneOrdinal, 'M')
+      && entry.taskOrdinal === optionalOrdinal(options.taskOrdinal, 'T')
+      && entry.stepOrdinal === optionalOrdinal(options.stepOrdinal, 'S')
+      && (['task', 'coordinator'].includes(options.type)
+        || entry.attempt === positiveInteger(options.attempt ?? 1, 'attempt')));
+    if (existing) return { ...publicEntry(existing), reused: true };
     const entry = {
       sequence,
       reservationId,
@@ -92,6 +101,17 @@ export function bindChat(options) {
     const registry = readRegistry(file, options.projectId);
     const entry = requireEntry(registry, options.reservationId);
     if (!entry.titleVerified) throw new Error('Chat title must pass exact readback before binding.');
+    if (options.threadId?.startsWith('client-')) throw new Error('Cannot bind a pending clientThreadId.');
+    if (entry.threadId && (entry.threadId !== options.threadId || entry.hostId !== options.hostId)) {
+      throw new Error('Reservation already bound to another thread.');
+    }
+    if (registry.entries.some(other => other !== entry && other.threadId === options.threadId
+      && other.hostId === options.hostId)) throw new Error('Thread already belongs to another reservation.');
+    if (entry.dispatch && (entry.dispatch.state !== 'resolved' || entry.dispatch.candidateThreadId !== options.threadId
+      || entry.dispatch.hostId !== options.hostId
+      || entry.dispatch.observations.at(-1)?.title !== entry.observedTitle)) {
+      throw new Error('Tracked creation must pass correlated read_thread observation before binding.');
+    }
     entry.threadId = requiredText(options.threadId, 'threadId');
     entry.hostId = requiredText(options.hostId, 'hostId');
     entry.status = 'bound';
@@ -106,6 +126,9 @@ export function retitleChat(options) {
   return withRegistryLock(options.projectId, options.registryHome, (file) => {
     const registry = readRegistry(file, options.projectId);
     const entry = requireEntry(registry, options.reservationId);
+    if (entry.dispatch && options.entityId !== entry.entityId) {
+      throw new Error('Tracked dispatch entity is immutable; retitle cannot replace its identity.');
+    }
     entry.entityId = requiredText(options.entityId, 'entityId');
     entry.semanticTitle = requiredText(options.semanticTitle, 'semanticTitle');
     entry.candidates = buildTitleCandidates({
@@ -134,6 +157,7 @@ export function abandonChat(options) {
   return withRegistryLock(options.projectId, options.registryHome, (file) => {
     const registry = readRegistry(file, options.projectId);
     const entry = requireEntry(registry, options.reservationId);
+    if (entry.dispatch || entry.threadId) throw new Error('Cannot abandon a started creation or bound chat to enable a duplicate.');
     entry.status = 'abandoned';
     entry.updatedAt = new Date().toISOString();
     writeRegistry(file, registry);
@@ -141,6 +165,25 @@ export function abandonChat(options) {
   });
 }
 
+export function dispatchChat(options) {
+  validateProjectId(options.projectId);
+  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 (!['dispatch-status', 'dispatch-context-check'].includes(options.action) && result.idempotentRetry !== true) {
+      entry.updatedAt = new Date().toISOString();
+      writeRegistry(file, registry);
+    }
+    return result;
+  });
+}
+
 export function showRegistry(options) {
   validateProjectId(options.projectId);
   const file = registryFile(options.projectId, options.registryHome);
@@ -217,7 +260,10 @@ function withRegistryLock(projectId, registryHome, operation) {
 
 function lockIsStale(lock) {
   try {
-    return Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS;
+    if (Date.now() - statSync(lock).mtimeMs <= LOCK_STALE_MS) return false;
+    const owner = JSON.parse(readFileSync(path.join(lock, 'owner.json'), 'utf8'));
+    if (!Number.isSafeInteger(owner.pid) || owner.pid < 1) return false;
+    try { process.kill(owner.pid, 0); return false; } catch (error) { return error?.code === 'ESRCH'; }
   } catch {
     return false;
   }
@@ -253,7 +299,7 @@ function readRegistry(file, projectId) {
 
 function writeRegistry(file, registry) {
   const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify(registry, null, 2)}\n`, { flag: 'wx' });
+  writeFileSync(temporary, `${JSON.stringify(registry, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
   renameSync(temporary, file);
 }
 
@@ -275,6 +321,7 @@ function publicEntry(entry) {
     threadId: entry.threadId,
     hostId: entry.hostId,
     status: entry.status,
+    dispatchState: entry.dispatch?.state ?? null,
   };
 }
 
@@ -334,6 +381,11 @@ function cli() {
     projectId: option(args, 'project-id'),
     registryHome: option(args, 'registry-home'),
   };
+  if (action?.startsWith('dispatch-') || action === 'supervision-record' || action === 'model-select') {
+    const file = option(args, 'file');
+    return dispatchChat({ ...common, action, reservationId: option(args, 'reservation-id'),
+      input: file ? dispatchInput(file) : {} });
+  }
   if (action === 'allocate') return allocateChat({
     ...common,
     type: option(args, 'type'),
@@ -363,7 +415,7 @@ function cli() {
   });
   if (action === 'abandon') return abandonChat({ ...common, reservationId: option(args, 'reservation-id') });
   if (action === 'show') return showRegistry(common);
-  throw new Error('Use allocate, retitle, readback, bind, abandon, or show.');
+  throw new Error('Use allocate, retitle, readback, bind, abandon, show, dispatch-begin/result/discover/resolve-duplicates/observe/status, supervision-record, or model-select.');
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname)) {