@fitlab-ai/agent-infra 0.9.8 → 0.9.9

package/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.ts

@@ -6,11 +6,22 @@ import path from 'node:path';
 import semver from 'semver';
 import * as toml from 'smol-toml';
 
-import { requestSandboxControl } from '../../../sandbox/control/client.ts';
+import {
+  requestCodexControllerClose,
+  requestCodexControllerOpen,
+  requestCodexControllerVerify,
+  requestSandboxControl
+} from '../../../sandbox/control/client.ts';
 import { readSandboxControlStatus } from '../../../sandbox/control/state.ts';
-import { getProcessStartTime, isProcessAlive } from '../../../server/process-state.ts';
+import { getProcessStartTime, type ProcessIdentity } from '../../../server/process-state.ts';
 import { computeLifecycleBuildIdentity } from './build-identity.ts';
-import type { LifecycleBuildIdentity } from './build-identity.ts';
+import {
+  contextFromControllerLease,
+  controllerProofFromContext,
+  verifyCodexSandboxControllerContext as verifyContextFile,
+  writeCodexSandboxControllerContext,
+  type CodexSandboxControllerContextV2
+} from './controller-context.ts';
 
 type ControllerControl = Readonly<{
   token: string;
@@ -20,23 +31,7 @@ type ControllerControl = Readonly<{
   runtimeDir: string;
 }>;
 
-type CodexSandboxControllerContext = Readonly<{
-  version: 1;
-  taskId: string;
-  controlGeneration: string;
-  controllerInstanceDigest: string;
-  parentPid: number;
-  parentStartTime: number;
-  issuedAt: number;
-  expiresAt: number;
-  buildIdentity: LifecycleBuildIdentity;
-  hookDefinitionHash: string;
-  lifecycleProfilesHash: string;
-}>;
-
 type ControllerInput = Readonly<{
-  taskId: string;
-  taskRef: string;
   executorModel?: string;
   executorReasoningEffort?: string;
   reviewerModel?: string;
@@ -51,6 +46,8 @@ type ControllerOptions = Readonly<{
   now?: () => number;
   codexVersion?: () => string;
   verifyTaskBinding?: (taskId: string, control: ControllerControl) => void;
+  openController?: typeof requestCodexControllerOpen;
+  closeController?: typeof requestCodexControllerClose;
   environment?: NodeJS.ProcessEnv;
 }>;
 
@@ -60,11 +57,18 @@ type PreparedCodexSandboxController = Readonly<{
   env: NodeJS.ProcessEnv;
   home: string;
   contextPath: string;
-  context: CodexSandboxControllerContext;
+  context: CodexSandboxControllerContextV2;
   cleanup: () => void;
 }>;
 
-const CONTEXT_TTL_MS = 4 * 60 * 60 * 1_000;
+type VerifyContextOptions = Readonly<{
+  repoRoot?: string;
+  now?: number;
+  generation?: string;
+  probeProcess?: (identity: ProcessIdentity) => 'alive' | 'dead' | 'unknown';
+  control?: ControllerControl;
+  requestControllerVerify?: typeof requestCodexControllerVerify;
+}>;
 
 function digestFiles(files: readonly string[]): string {
   const hash = crypto.createHash('sha256');
@@ -162,6 +166,30 @@ function verifyControl(taskId: string, control: ControllerControl): void {
   if (payload.taskId !== taskId) throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_BINDING_INVALID');
 }
 
+function verifyCodexSandboxControllerContext(
+  contextPath: string,
+  options: VerifyContextOptions = {}
+): CodexSandboxControllerContextV2 {
+  const control = options.control ?? controlFromEnvironment();
+  const context = verifyContextFile(contextPath, {
+    repoRoot: options.repoRoot,
+    now: options.now,
+    generation: control.generation,
+    probeProcess: options.probeProcess
+  });
+  const verified = (options.requestControllerVerify ?? requestCodexControllerVerify)({
+    controllerProof: controllerProofFromContext(context),
+    ...control,
+    timeoutMs: 30_000
+  });
+  if (verified.binding.taskId !== context.taskId
+    || verified.binding.controlGeneration !== context.controlGeneration
+    || verified.binding.controllerInstanceDigest !== context.controllerInstanceDigest) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+  }
+  return context;
+}
+
 function detectedCodexVersion(): string {
   const result = spawnSync('codex', ['--version'], { encoding: 'utf8' });
   const version = /codex-cli\s+(\d+\.\d+\.\d+)/u.exec(result.stdout ?? '')?.[1];
@@ -256,7 +284,6 @@ function prepareCodexSandboxController(
   const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
   const sourceHome = path.resolve(options.codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex'));
   const control = options.control ?? controlFromEnvironment();
-  (options.verifyTaskBinding ?? verifyControl)(input.taskId, control);
   const version = (options.codexVersion ?? detectedCodexVersion)();
   if (!semver.gte(version, '0.147.0')) throw new Error('CODEX_SANDBOX_CONTROLLER_CODEX_UNSUPPORTED');
 
@@ -265,46 +292,33 @@ function prepareCodexSandboxController(
   fs.mkdirSync(runtimeRoot, { recursive: true, mode: 0o700 });
   fs.chmodSync(runtimeRoot, 0o700);
   const key = crypto.createHash('sha256')
-    .update(`${input.taskId}\0${control.generation}`)
+    .update(`${process.pid}\0${control.generation}`)
     .digest('hex');
-  const leasePath = path.join(runtimeRoot, `${key}.lease.json`);
-  if (fs.existsSync(leasePath)) {
-    const lease = JSON.parse(fs.readFileSync(leasePath, 'utf8')) as { pid?: number; startTime?: number };
-    if (Number.isSafeInteger(lease.pid) && typeof lease.startTime === 'number'
-      && getProcessStartTime(lease.pid!) === lease.startTime) {
-      throw new Error('CODEX_SANDBOX_CONTROLLER_BUSY');
-    }
-    fs.unlinkSync(leasePath);
-  }
-
   const parentStartTime = getProcessStartTime(process.pid);
   if (!parentStartTime) throw new Error('CODEX_SANDBOX_CONTROLLER_PROCESS_IDENTITY_INVALID');
-  const instanceDigest = crypto.randomBytes(32).toString('hex');
-  fs.writeFileSync(leasePath, `${JSON.stringify({
-    version: 1,
-    pid: process.pid,
-    startTime: parentStartTime,
-    taskId: input.taskId,
-    generation: control.generation,
-    instanceDigest
-  })}\n`, { mode: 0o600, flag: 'wx' });
-
   const home = fs.mkdtempSync(path.join(runtimeRoot, `${key}-`));
   fs.chmodSync(home, 0o700);
   let cleaned = false;
+  let context: CodexSandboxControllerContextV2 | null = null;
   const cleanup = () => {
     if (cleaned) return;
     cleaned = true;
+    if (context) {
+      try {
+        (options.closeController ?? requestCodexControllerClose)({
+          controllerProcess: context.controllerProcess,
+          controllerProof: controllerProofFromContext(context),
+          ...control,
+          timeoutMs: 30_000
+        });
+      } catch {
+        // The wrapper is exiting; dead-process recovery safely handles an unknown close result.
+      }
+    }
     const relative = path.relative(runtimeRoot, home);
     if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
       fs.rmSync(home, { recursive: true, force: true });
     }
-    try {
-      const lease = JSON.parse(fs.readFileSync(leasePath, 'utf8')) as { instanceDigest?: string };
-      if (lease.instanceDigest === instanceDigest) fs.unlinkSync(leasePath);
-    } catch {
-      // A missing or replaced lease is owned by another cleanup path.
-    }
   };
 
   try {
@@ -333,22 +347,25 @@ function prepareCodexSandboxController(
     }
 
     const buildIdentity = computeLifecycleBuildIdentity(repoRoot);
-    const now = (options.now ?? Date.now)();
-    const context: CodexSandboxControllerContext = Object.freeze({
-      version: 1,
-      taskId: input.taskId,
-      controlGeneration: control.generation,
-      controllerInstanceDigest: instanceDigest,
-      parentPid: process.pid,
-      parentStartTime,
-      issuedAt: now,
-      expiresAt: now + CONTEXT_TTL_MS,
-      buildIdentity,
+    const opened = (options.openController ?? requestCodexControllerOpen)({
+      controllerProcess: { pid: process.pid, startTime: parentStartTime },
+      ...control,
+      timeoutMs: 30_000
+    });
+    const taskId = opened.lease.taskId;
+    context = contextFromControllerLease(opened.lease, {
       hookDefinitionHash: crypto.createHash('sha256').update(fs.readFileSync(hooks)).digest('hex'),
       lifecycleProfilesHash: digestFiles([executor, reviewer])
     });
+    if (opened.lease.controlGeneration !== control.generation
+      || opened.lease.controllerProcess.pid !== process.pid
+      || opened.lease.controllerProcess.startTime !== parentStartTime
+      || JSON.stringify(opened.lease.buildIdentity) !== JSON.stringify(buildIdentity)) {
+      throw new Error('SANDBOX_CONTROL_RESULT_INVALID');
+    }
+    (options.verifyTaskBinding ?? verifyControl)(taskId, control);
     const contextPath = path.join(home, 'controller-context.json');
-    fs.writeFileSync(contextPath, `${JSON.stringify(context, null, 2)}\n`, { mode: 0o600 });
+    writeCodexSandboxControllerContext(contextPath, context);
 
     const shimDir = path.join(home, 'bin');
     fs.mkdirSync(shimDir, { mode: 0o700 });
@@ -364,7 +381,7 @@ function prepareCodexSandboxController(
       input.reviewerModel ? `--reviewer-model ${input.reviewerModel}` : '',
       input.reviewerReasoningEffort ? `--reviewer-reasoning-effort ${input.reviewerReasoningEffort}` : ''
     ].filter(Boolean).join(' ');
-    const prompt = `$run-task ${input.taskRef}${policy ? ` ${policy}` : ''}`;
+    const prompt = `$run-task ${taskId}${policy ? ` ${policy}` : ''}`;
     const args = Object.freeze([
       'exec',
       '--enable', 'hooks',
@@ -379,7 +396,7 @@ function prepareCodexSandboxController(
       home,
       shimDir,
       contextPath,
-      input.taskId,
+      taskId,
       control,
       providerEnvironment,
       options.environment ?? process.env
@@ -399,32 +416,6 @@ function prepareCodexSandboxController(
   }
 }
 
-function verifyCodexSandboxControllerContext(
-  contextPath: string,
-  taskId: string,
-  options: Readonly<{ repoRoot?: string; now?: number; generation?: string }> = {}
-): CodexSandboxControllerContext {
-  const stat = fs.lstatSync(contextPath);
-  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0) {
-    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
-  }
-  const context = JSON.parse(fs.readFileSync(contextPath, 'utf8')) as CodexSandboxControllerContext;
-  const generation = options.generation ?? process.env.AGENT_INFRA_CONTROL_GENERATION;
-  if (context.version !== 1
-    || context.taskId !== taskId
-    || context.controlGeneration !== generation
-    || context.expiresAt < (options.now ?? Date.now())
-    || getProcessStartTime(context.parentPid) !== context.parentStartTime
-    || !isProcessAlive(context.parentPid)) {
-    throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
-  }
-  const current = computeLifecycleBuildIdentity(options.repoRoot ?? process.cwd());
-  if (JSON.stringify(current) !== JSON.stringify(context.buildIdentity)) {
-    throw new Error('CODEX_SANDBOX_CONTROLLER_BUNDLE_MISMATCH');
-  }
-  return Object.freeze(context);
-}
-
 async function runCodexSandboxController(
   input: ControllerInput,
   options: ControllerOptions = {}
@@ -469,10 +460,11 @@ async function runCodexSandboxController(
 export {
   prepareCodexSandboxController,
   runCodexSandboxController,
-  verifyCodexSandboxControllerContext
+  verifyCodexSandboxControllerContext,
+  controllerProofFromContext
 };
 export type {
-  CodexSandboxControllerContext,
+  CodexSandboxControllerContextV2 as CodexSandboxControllerContext,
   ControllerControl,
   ControllerInput,
   ControllerOptions,

package/lib/git/workflow.ts

@@ -105,7 +105,7 @@ function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; mes
   return { status: 'applied' as const, changed: true, snapshot: after.snapshot, operations: [{ name: 'stage', status: 'applied' as const }, { name: 'commit', status: 'applied' as const }], error: null };
 }
 
-function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string[] }, runner: GitRunner = defaultRunner) {
+function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string[]; expectedSha?: string }, runner: GitRunner = defaultRunner) {
   if (!input.remote || input.refs.length === 0) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [], error: { code: 'GIT_PUSH_INPUT_INVALID', message: 'Remote and refs are required' } };
   const operations: GitOperation[] = [];
   for (const ref of input.refs) {
@@ -120,7 +120,16 @@ function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string
     }
     const canonical = ref.startsWith('refs/') ? ref : `refs/heads/${ref}`;
     const remoteFact = run(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, canonical]);
-    operations.push({ name: 'push', ref, status: remoteFact.status === 0 ? 'applied' : 'failed', message: remoteFact.status === 0 ? undefined : 'Remote ref verification failed' });
+    const remoteSha = remoteFact.status === 0 ? remoteFact.stdout.trim().split(/\s+/)[0] ?? null : null;
+    const verified = remoteFact.status === 0 && (!input.expectedSha || remoteSha === input.expectedSha);
+    operations.push({
+      name: 'push',
+      ref,
+      status: verified ? 'applied' : 'failed',
+      message: verified ? undefined : input.expectedSha
+        ? `Remote ref verification failed: expected ${input.expectedSha}, received ${remoteSha ?? 'unavailable'}`
+        : 'Remote ref verification failed'
+    });
   }
   const failures = operations.filter((item) => item.status === 'failed').length;
   return { status: failures === 0 ? 'applied' as const : failures === operations.length ? 'failed' as const : 'degraded' as const, changed: failures < operations.length, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations, error: failures ? { code: 'GIT_PUSH_PARTIAL', message: `${failures} ref push operation(s) failed` } : null };

package/lib/internal/codex-lifecycle.ts

@@ -14,6 +14,7 @@ import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-l
 import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 import type { CodexLifecycleEvent } from '../agent-clients/adapters/codex-lifecycle/evidence.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { hasSealableOrchestrationDelegation } from '../task/orchestration.ts';
 import {
   activateCodexOrchestrationDelegation,
   activateCodexSpawnDelegation,
@@ -100,7 +101,7 @@ function hookDefinitionHash(): string {
 function controllerBinding(taskId: string) {
   const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
   if (!contextPath) return undefined;
-  const context = verifyCodexSandboxControllerContext(contextPath, taskId, { repoRoot: process.cwd() });
+  const context = verifyCodexSandboxControllerContext(contextPath, { repoRoot: process.cwd() });
   return {
     instanceDigest: context.controllerInstanceDigest,
     controlGeneration: context.controlGeneration
@@ -139,7 +140,8 @@ function recordFromPayload(phase: string, payload: unknown): CodexLifecycleEvent
     sessionId: text('sessionId'),
     turnId: text('turnId'),
     childThreadId: text('childThreadId'),
-    nativeAgent: text('nativeAgent')
+    nativeAgent: text('nativeAgent'),
+    source: 'hook'
   };
   if (phase === 'subagent-stop') return {
     type: 'hook-stop',
@@ -326,8 +328,17 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       }
       const result = store.apply(event);
       if (parsed.values['--bridge'] === 'true' && event.type === 'hook-stop') {
-        const bridged = await sealCodexOrchestrationDelegation(event.childThreadId, { store });
-        outputBridgeResult(bridged);
+        if (!hasSealableOrchestrationDelegation('codex', event.childThreadId, { repoRoot: process.cwd() })) {
+          output({ status: 'ignored', changed: false, evidence: null, diagnostics: [], error: null });
+          return;
+        }
+        output({
+          status: result.state.status,
+          changed: true,
+          evidence: result.state,
+          diagnostics: [],
+          error: result.state.error
+        });
         return;
       }
       output({ status: result.state.status, changed: true, evidence: result.state, diagnostics: [], error: result.state.error });
@@ -350,7 +361,9 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       return;
     }
     if (parsed.operation === 'resolve-stop') {
-      const terminal = await resolveCodexTerminal(childThreadId);
+      const stopTurnId = store.read(childThreadId).state.stop?.turnId;
+      if (!stopTurnId) throw new Error('Codex lifecycle stop hook is not available');
+      const terminal = await resolveCodexTerminal(childThreadId, stopTurnId);
       const latest = store.apply(terminal);
       if (latest.state.status !== 'stop-ready') {
         throw new Error(`Codex lifecycle stop evidence is not ready (status=${latest.state.status})`);

package/lib/internal/codex-sandbox-controller.ts

@@ -26,8 +26,6 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
     return null;
   }
   const allowed = new Set([
-    '--task-id',
-    '--task-ref',
     '--context',
     '--executor-model',
     '--executor-reasoning-effort',
@@ -37,6 +35,11 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
   const values: Record<string, string> = {};
   for (let index = 1; index < args.length; index += 1) {
     const flag = args[index]!;
+    if (flag === '--task-id' || flag.startsWith('--task-id=')
+      || flag === '--task-ref' || flag.startsWith('--task-ref=')) {
+      fail('CODEX_SANDBOX_CONTROLLER_IDENTITY_OPTION_UNSUPPORTED', 'controller task identity options are not supported', 2);
+      return null;
+    }
     const value = args[++index];
     if (!allowed.has(flag) || Object.hasOwn(values, flag) || !value || value.startsWith('--')) {
       fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', `invalid option '${flag}'`, 2);
@@ -50,17 +53,12 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
 async function codexSandboxController(args: string[] = []): Promise<void> {
   const parsed = parse(args);
   if (!parsed || process.exitCode) return;
-  const taskId = parsed.values['--task-id'];
-  if (!taskId) {
-    fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', '--task-id is required', 2);
-    return;
-  }
   try {
     if (parsed.operation === 'verify-context') {
       const contextPath = parsed.values['--context']
         ?? process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
       if (!contextPath) throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_MISSING');
-      const context = verifyCodexSandboxControllerContext(contextPath, taskId);
+      const context = verifyCodexSandboxControllerContext(contextPath);
       process.stdout.write(`${JSON.stringify({
         status: 'ready',
         changed: false,
@@ -77,8 +75,6 @@ async function codexSandboxController(args: string[] = []): Promise<void> {
       })}\n`);
       return;
     }
-    const taskRef = parsed.values['--task-ref'];
-    if (!taskRef) throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_REF_REQUIRED');
     const policy = [
       '--executor-model',
       '--executor-reasoning-effort',
@@ -90,8 +86,6 @@ async function codexSandboxController(args: string[] = []): Promise<void> {
       throw new Error('CODEX_SANDBOX_CONTROLLER_MODEL_POLICY_INVALID');
     }
     const exitCode = await runCodexSandboxController({
-      taskId,
-      taskRef,
       executorModel: parsed.values['--executor-model'],
       executorReasoningEffort: parsed.values['--executor-reasoning-effort'],
       reviewerModel: parsed.values['--reviewer-model'],

package/lib/internal/git-workflow.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
-import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch } from '../git/workflow.ts';
+import { inspectGitWorkflow, pushRebasedBranch } from '../git/workflow.ts';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
+import { executeCommitOperation } from '../task/commit-operation.ts';
 
 function output(value: unknown): void { process.stdout.write(`${JSON.stringify(value)}\n`); }
 
@@ -18,11 +19,9 @@ function gitWorkflow(args: string[] = []): void {
   else if (action === 'commit') {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
-    result = input ? commitExplicitPaths({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-  } else if (action === 'push') {
-    const inputIndex = rest.indexOf('--input');
-    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
-    result = input ? pushGitRefs({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
+    result = input
+      ? executeCommitOperation({ cwd: cwd ?? process.cwd(), ...input })
+      : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
   } else if (action === 'push-rebased') {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;

package/lib/internal/platform-pr.ts

@@ -17,13 +17,13 @@ const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd
        agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <N>] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr create <task-ref> --agent <agent> --base <branch> --head <branch> --title-file <path|-> --body-file <path|-> [--draft] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr bind <task-ref> --pr <N> --agent <agent> [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-context <task-ref> [--cwd <path>]
-       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
 `;
 
 const BOOLEAN_FLAGS = new Set(['--draft', '--dry-run', '--metadata', '--closing-issue']);
-const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--pr']);
+const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--pr', '--result']);
 
 function key(flag: string): string {
   return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
@@ -76,9 +76,9 @@ function platformPr(args: string[] = []): void {
     'resolve-external': ['cwd', 'agent', 'pr', 'dryRun'],
     create: ['cwd', 'agent', 'base', 'head', 'titleFile', 'bodyFile', 'draft', 'dryRun'],
     bind: ['cwd', 'agent', 'pr', 'dryRun'],
-    sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'dryRun'],
+    sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'result', 'dryRun'],
     'summary-context': ['cwd'],
-    'summary-sync': ['cwd', 'agent', 'bodyFile', 'dryRun']
+    'summary-sync': ['cwd', 'agent', 'bodyFile', 'result', 'dryRun']
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
@@ -88,6 +88,11 @@ function platformPr(args: string[] = []): void {
   const agent = normalizeAgentToken(values.agent);
   if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
+  const primaryResult = values.result === undefined ? undefined : values.result;
+  if (primaryResult !== undefined && !['pr_created', 'pr_reused', 'no_op'].includes(primaryResult as string)) {
+    fail('--result must be pr_created, pr_reused, or no_op');
+    return;
+  }
   if (operation === 'resolve-external') {
     const pr = values.pr === undefined ? undefined : Number(values.pr);
     if (pr !== undefined && (!Number.isInteger(pr) || pr <= 0)) { fail('resolve-external requires a positive --pr'); return; }
@@ -102,13 +107,15 @@ function platformPr(args: string[] = []): void {
   }
   if (operation === 'sync') {
     if (values.metadata !== true && values.closingIssue !== true) { fail('sync requires --metadata or --closing-issue'); return; }
-    finish(syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, dryRun: values.dryRun === true }));
+    if (!primaryResult) { fail('sync requires --result pr_created, pr_reused, or no_op'); return; }
+    finish(syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
     return;
   }
   if (operation === 'summary-sync') {
     if (typeof values.bodyFile !== 'string') { fail('summary-sync requires --body-file'); return; }
+    if (!primaryResult) { fail('summary-sync requires --result pr_created, pr_reused, or no_op'); return; }
     try {
-      finish(syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), dryRun: values.dryRun === true }));
+      finish(syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
     } catch (error) {
       fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
     }

package/lib/internal/release-workflow.ts

@@ -25,12 +25,13 @@ type DemoResult = {
   outputPath: string | null;
 };
 
+// The tape is the canonical init interaction contract. Do not hash all of
+// lib/init.ts: non-visual config serialization changes must not re-record it.
 const DEMO_INPUT_PATHS = [
   'assets/demo-init.tape',
   'scripts/demo-regen.sh',
   'scripts/normalize-gif-duration.py',
   'bin/cli.ts',
-  'lib/init.ts',
   'lib/log.ts',
   'lib/prompt.ts',
   'lib/paths.ts',

package/lib/internal/sandbox-control.ts

@@ -1,6 +1,84 @@
-import { requestSandboxControl, SandboxControlClientError } from '../sandbox/control/client.ts';
+import {
+  requestSandboxControl,
+  requestSandboxTaskFinalization,
+  requestSandboxTaskControl,
+  SandboxControlClientError
+} from '../sandbox/control/client.ts';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { serveSandboxControl } from '../sandbox/control/server.ts';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.ts';
+import {
+  controllerProofFromContext,
+  verifyCodexSandboxControllerContext
+} from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+
+function isCanonicalCodexPrepare(args: readonly string[]): boolean {
+  if (args[1] !== 'prepare') return false;
+  const clients: string[] = [];
+  for (let index = 2; index < args.length; index += 1) {
+    if (args[index] === '--client') clients.push(args[index + 1] ?? '');
+    else if (args[index]?.startsWith('--client=')) clients.push(args[index]!.slice('--client='.length));
+  }
+  return clients.length === 1 && clients[0] === 'codex';
+}
+
+type FinalizationStatus = 'completed' | 'failed' | 'blocked' | 'unknown';
+
+function writeFinalizationEnvelope(
+  status: FinalizationStatus,
+  accepted: boolean,
+  error: { code: string; message: string; retryable: boolean },
+  changed = false,
+  result: unknown = null
+): void {
+  process.stdout.write(`${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`);
+}
+
+function finalizationErrorStatus(error: { retryable: boolean; code: string }): FinalizationStatus {
+  if (error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') return 'unknown';
+  return error.retryable ? 'blocked' : 'failed';
+}
+
+function sandboxFinalizationClient(args: string[]): void {
+  if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
+    const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'task ref, complete intent, and --agent are required', retryable: false };
+    writeFinalizationEnvelope('failed', false, error);
+    process.stderr.write('Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n');
+    process.exitCode = 1;
+    return;
+  }
+  const agent = normalizeAgentToken(args[3]);
+  if (!agent) {
+    const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: `invalid --agent: ${AGENT_USAGE_HINT}`, retryable: false };
+    writeFinalizationEnvelope('failed', false, error);
+    process.exitCode = 1;
+    return;
+  }
+  let response;
+  try {
+    response = requestSandboxTaskFinalization({ agent });
+  } catch (error) {
+    if (!(error instanceof SandboxControlClientError)) throw error;
+    writeFinalizationEnvelope(finalizationErrorStatus(error.detail), error.accepted, error.detail);
+    process.stderr.write(`${error.detail.message}\n`);
+    process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
+    return;
+  }
+  if (response.phase === 'rejected') {
+    const error = response.error ?? {
+      code: 'SANDBOX_CONTROL_REJECTED',
+      message: 'sandbox control rejected the finalization request',
+      retryable: false
+    };
+    writeFinalizationEnvelope(finalizationErrorStatus(error), error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN', error);
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
+    return;
+  }
+  process.stdout.write(response.stdout);
+  process.stderr.write(response.stderr);
+  process.exitCode = response.exitCode ?? 1;
+}
 
 async function sandboxControl(args: string[]): Promise<void> {
   const [operation, ...rest] = args;
@@ -31,9 +109,21 @@ async function sandboxControl(args: string[]): Promise<void> {
   }
   if (operation === 'client') {
     const [family = '', ...commandArgs] = rest;
+    if (family === 'task-finalization') {
+      sandboxFinalizationClient(commandArgs);
+      return;
+    }
     let response;
     try {
-      response = requestSandboxControl({ family, args: commandArgs });
+      if (family === 'task-orchestration' && isCanonicalCodexPrepare(commandArgs)) {
+        const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+        const proof = contextPath
+          ? controllerProofFromContext(verifyCodexSandboxControllerContext(contextPath))
+          : null;
+        response = requestSandboxTaskControl({ family, args: commandArgs, controllerProof: proof });
+      } else {
+        response = requestSandboxControl({ family, args: commandArgs });
+      }
     } catch (error) {
       if (!(error instanceof SandboxControlClientError)) throw error;
       process.stderr.write(`${error.detail.message}\n`);