@fitlab-ai/agent-infra 0.9.4 → 0.9.6

package/lib/task/orchestration.ts

@@ -36,6 +36,8 @@ import {
   diffWorkspaceSnapshots
 } from './workspace-snapshot.ts';
 import type { RepositorySnapshot } from './workspace-snapshot.ts';
+import type { WorkspaceSnapshotContext } from './workspace-snapshot.ts';
+import { assertGitRepositoryBinding } from '../git/worktree-identity.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import {
   CommitIntentError,
@@ -55,6 +57,12 @@ import {
 } from './commit-finalization.ts';
 import type { CommitFinalizationInspection } from './commit-finalization.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import {
+  appendActivityEntry,
+  commitAttemptStartedNote,
+  locateActivityLog,
+  pairEntries
+} from './activity-log.ts';
 
 type OrchestrationStatus = 'running' | 'paused' | 'completed';
 type LegacyOrchestrationModelPolicy = Readonly<{
@@ -66,7 +74,7 @@ type ModelPolicySource = Readonly<{
   client: AgentClientId;
   resolvedAt: string;
 }>;
-type OrchestrationRecovery = Readonly<{
+type ModelPolicyRecovery = Readonly<{
   code: 'MODEL_POLICY_SUPPLEMENTED';
   recoveredAt: string;
   previousSchemaVersion: 1;
@@ -77,6 +85,26 @@ type OrchestrationRecovery = Readonly<{
   pendingDelegation: false;
   resultingStatus: OrchestrationStatus;
 }>;
+type ClientCapabilityRecovery = Readonly<{
+  code: 'CLIENT_CAPABILITY_ENABLED';
+  recoveredAt: string;
+  previousSchemaVersion: 2;
+  previousStatus: 'paused';
+  previousPause: Readonly<{ code: 'ORCHESTRATION_CLIENT_UNSUPPORTED'; message: string; recoverable: boolean }>;
+  client: 'codex';
+  guards: Readonly<{
+    stepCount: 0;
+    nextStage: null;
+    baselineEmpty: true;
+    receiptCount: 0;
+    pendingDelegation: false;
+    commitAuthorizationUnused: true;
+    completionEvidenceAbsent: true;
+    commitIntentAbsent: true;
+  }>;
+  resultingStatus: 'running';
+}>;
+type OrchestrationRecovery = ModelPolicyRecovery | ClientCapabilityRecovery;
 type CleanCompletionEvidence = Readonly<{
   kind: 'reviewed-head-clean';
   observedAt: string;
@@ -147,12 +175,13 @@ type OrchestrationCompletionPlanResult = Readonly<{
 }>;
 type OrchestrationOptions = {
   repoRoot?: string;
+  gitWorktreeRoot?: string;
   id?: () => string;
   now?: () => string;
   maxSteps?: number;
   client?: AgentClientId;
   modelPolicy?: OrchestrationModelPolicy;
-  captureWorkspace?: (repoRoot: string, taskId: string | null) => string;
+  captureWorkspace?: (context: WorkspaceSnapshotContext) => string;
   captureRepository?: (repoRoot: string) => RepositorySnapshot;
   inspectPullRequest?: (taskId: string, options: { cwd: string }) => Readonly<{
     status: string;
@@ -188,6 +217,7 @@ type CommitIntentResult = Readonly<{
     committedHead: string | null;
     needsAnchor: boolean;
     needsLog: boolean;
+    attempt: Readonly<{ attempt: string; baseline: string; agent: string }> | null;
   }>;
   token?: string;
   error: Readonly<{ code: string; message: string }> | null;
@@ -259,6 +289,11 @@ function repositoryHead(repoRoot: string): string {
   }).trim();
 }
 
+function gitRootFor(stateRoot: string, options: OrchestrationOptions): string {
+  if (!options.gitWorktreeRoot) return stateRoot;
+  return assertGitRepositoryBinding(stateRoot, options.gitWorktreeRoot).worktreeRoot;
+}
+
 function isAncestor(repoRoot: string, ancestor: string, descendant: string): boolean {
   return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
     cwd: repoRoot,
@@ -287,7 +322,8 @@ function commitFinalizationView(inspection: CommitFinalizationInspection): NonNu
     currentHead: inspection.currentHead,
     committedHead: inspection.committedHead,
     needsAnchor: inspection.needsAnchor,
-    needsLog: inspection.needsLog
+    needsLog: inspection.needsLog,
+    attempt: inspection.attempt
   };
 }
 
@@ -353,6 +389,23 @@ function resolveProjectPolicy(repoRoot: string, client: AgentClientId): Orchestr
   return normalizeAgentClients(raw).state[client].orchestration;
 }
 
+function canRecoverCodexUnsupportedPause(run: OrchestrationRun, taskDir: string): boolean {
+  return run.schemaVersion === 2
+    && run.status === 'paused'
+    && run.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+    && run.modelPolicySource?.client === 'codex'
+    && run.stepCount === 0
+    && run.nextStage === null
+    && run.baseline === ''
+    && run.pendingDelegation === null
+    && run.receipts.length === 0
+    && run.commitAuthorization?.issuedAt === null
+    && run.commitAuthorization?.consumedAt === null
+    && run.completionEvidence == null
+    && !fs.existsSync(commitIntentPath(taskDir))
+    && (run.recoveryHistory ?? []).every((entry) => entry.code === 'MODEL_POLICY_SUPPLEMENTED');
+}
+
 function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
@@ -399,6 +452,39 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
           return failed('ORCHESTRATION_MODEL_POLICY_MISMATCH', 'provided model policy does not match the persisted run policy', resolved.taskId);
         }
       }
+      if (existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED') {
+        if (!canRecoverCodexUnsupportedPause(existing, resolved.taskDir)) {
+          return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+        }
+        const now = (options.now ?? (() => new Date().toISOString()))();
+        const previousPause = existing.pause as ClientCapabilityRecovery['previousPause'];
+        const recovery: ClientCapabilityRecovery = {
+          code: 'CLIENT_CAPABILITY_ENABLED',
+          recoveredAt: now,
+          previousSchemaVersion: 2,
+          previousStatus: 'paused',
+          previousPause,
+          client: 'codex',
+          guards: {
+            stepCount: 0,
+            nextStage: null,
+            baselineEmpty: true,
+            receiptCount: 0,
+            pendingDelegation: false,
+            commitAuthorizationUnused: true,
+            completionEvidenceAbsent: true,
+            commitIntentAbsent: true
+          },
+          resultingStatus: 'running'
+        };
+        const resumed = withUpdatedRun(existing, {
+          status: 'running',
+          pause: null,
+          recoveryHistory: Object.freeze([...(existing.recoveryHistory ?? []), recovery])
+        }, () => now);
+        saveRun(resolved.taskDir, resumed);
+        return { status: 'running', changed: true, taskId: resolved.taskId, run: resumed, next: null, error: null };
+      }
       if (existing.status === 'paused' && existing.pause?.recoverable && existing.pendingDelegation === null) {
         const resumed = withUpdatedRun(existing, { status: 'running', pause: null });
         saveRun(resolved.taskDir, resumed);
@@ -607,6 +693,12 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
 function routeOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  let gitRoot: string;
+  try {
+    gitRoot = gitRootFor(resolved.repoRoot, options);
+  } catch (error) {
+    return failed('ORCHESTRATION_WORKTREE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
   let content: string;
   try {
     content = fs.readFileSync(resolved.taskMdPath, 'utf8');
@@ -677,7 +769,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     const capture = options.captureRepository ?? captureRepositorySnapshot;
     let before: RepositorySnapshot;
     try {
-      before = capture(resolved.repoRoot);
+      before = capture(gitRoot);
     } catch (error) {
       return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
@@ -693,7 +785,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
       options.inspectPullRequest ?? inspectPlatformPullRequest;
     let inspection: ReturnType<NonNullable<OrchestrationOptions['inspectPullRequest']>>;
     try {
-      inspection = inspect(resolved.taskId, { cwd: resolved.repoRoot });
+      inspection = inspect(resolved.taskId, { cwd: gitRoot });
     } catch (error) {
       return failed('ORCHESTRATION_PR_INSPECTION_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
@@ -714,7 +806,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
 
     let after: RepositorySnapshot;
     try {
-      after = capture(resolved.repoRoot);
+      after = capture(gitRoot);
     } catch (error) {
       return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
@@ -748,16 +840,119 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
   return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
 }
 
+function appendCommitActivity(
+  resolved: Extract<ReturnType<typeof resolveTaskRef>, { ok: true }>,
+  step: string,
+  agent: string,
+  note: string
+): Readonly<{ code: string; message: string }> | null {
+  const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  const activity = locateActivityLog(taskContent);
+  if (!activity) return { code: 'ORCHESTRATION_TASK_INVALID', message: 'task activity log is missing or ambiguous' };
+  const metadata = captureTaskWriteMetadata();
+  const written = writeTask({
+    taskRef: resolved.taskId,
+    expectedState: 'active',
+    mutations: [{
+      kind: 'section',
+      aliases: ['活动日志', 'Activity Log'],
+      heading: activity.heading,
+      body: appendActivityEntry(activity, { time: metadata.timestamp, step, agent, note })
+    }]
+  }, { repoRoot: resolved.repoRoot, metadataProvider: () => metadata });
+  return written.status === 'failed' ? written.error : null;
+}
+
+function startCommitAttempt(
+  taskRef: string,
+  input: Readonly<{ agent: string }>,
+  options: OrchestrationOptions = {}
+): CommitIntentResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+  try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
+    return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-attempt.start', () => {
+      if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists', resolved.taskId);
+      }
+      const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+      const activity = locateActivityLog(taskContent);
+      if (!activity) return commitIntentFailed('ORCHESTRATION_TASK_INVALID', 'task activity log is missing or ambiguous', resolved.taskId);
+      const open = pairEntries(activity.entries).filter((row) => row.step === 'Commit' && row.started !== '' && row.done === '');
+      if (open.length > 0) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_ATTEMPT_BUSY', 'an open Commit activity entry already exists', resolved.taskId);
+      }
+      const currentHead = repositoryHead(gitRoot);
+      const attempt = (options.id ?? randomUUID)();
+      const error = appendCommitActivity(resolved, 'Commit [started]', input.agent, commitAttemptStartedNote({
+        attempt,
+        baseline: currentHead,
+        agent: input.agent
+      }));
+      if (error) return commitIntentFailed(error.code, error.message, resolved.taskId);
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      return {
+        status: 'ready', changed: true, taskId: resolved.taskId, intent: null,
+        finalization: commitFinalizationView(inspection), error: null
+      };
+    });
+  } catch (error) {
+    return mapCommitIntentError(error, resolved.taskId);
+  }
+}
+
+function terminateCommitAttempt(
+  taskRef: string,
+  input: Readonly<{ attempt: string; agent: string; code: string }>,
+  options: OrchestrationOptions = {}
+): CommitIntentResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+  try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
+    return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-attempt.terminate', () => {
+      if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'an active commit intent must be aborted or recovered first', resolved.taskId);
+      }
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      if (
+        inspection.disposition !== 'retryable-start'
+        || inspection.attempt?.attempt !== input.attempt
+        || inspection.attempt.agent !== input.agent
+        || inspection.attempt.baseline !== inspection.currentHead
+      ) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'commit attempt identity or repository HEAD has drifted', resolved.taskId);
+      }
+      const error = appendCommitActivity(
+        resolved,
+        'Commit [aborted]',
+        input.agent,
+        `aborted; attempt=${input.attempt}; code=${input.code}`
+      );
+      if (error) return commitIntentFailed(error.code, error.message, resolved.taskId);
+      return {
+        status: 'ready', changed: true, taskId: resolved.taskId, intent: null,
+        finalization: commitFinalizationView(inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId)),
+        error: null
+      };
+    });
+  } catch (error) {
+    return mapCommitIntentError(error, resolved.taskId);
+  }
+}
+
 function beginCommitIntent(
   taskRef: string,
-  input: Readonly<{ agent: string; orchestrated: boolean; baselineHead: string }>,
+  input: Readonly<{ agent: string; orchestrated: boolean; baselineHead: string; attempt: string }>,
   options: OrchestrationOptions = {}
 ): CommitIntentResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.begin', () => {
-      const currentHead = repositoryHead(resolved.repoRoot);
+      const currentHead = repositoryHead(gitRoot);
       if (currentHead !== input.baselineHead) {
         return commitIntentFailed('ORCHESTRATION_COMMIT_BASELINE_MISMATCH', 'baseline HEAD does not match the repository HEAD', resolved.taskId);
       }
@@ -769,7 +964,19 @@ function beginCommitIntent(
         }
         return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists', resolved.taskId);
       }
-
+      const attemptInspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      if (
+        attemptInspection.disposition !== 'retryable-start'
+        || attemptInspection.attempt?.attempt !== input.attempt
+        || attemptInspection.attempt.agent !== input.agent
+        || attemptInspection.attempt.baseline !== input.baselineHead
+      ) {
+        return commitIntentFailed(
+          'ORCHESTRATION_COMMIT_ATTEMPT_MISMATCH',
+          'commit begin requires one matching retryable Commit attempt',
+          resolved.taskId
+        );
+      }
       const runFile = orchestrationPath(resolved.taskDir);
       let run: OrchestrationRun | null = null;
       let sourceRunBytes: string | null = null;
@@ -883,13 +1090,14 @@ function checkpointCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.checkpoint', () => {
       const intent = readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
-      const currentHead = repositoryHead(resolved.repoRoot);
+      const currentHead = repositoryHead(gitRoot);
       if (currentHead !== input.head) {
         return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'checkpoint HEAD does not match the repository HEAD', resolved.taskId);
       }
-      if (input.kind === 'committed' && !isAncestor(resolved.repoRoot, intent.baselineHead, input.head)) {
+      if (input.kind === 'committed' && !isAncestor(gitRoot, intent.baselineHead, input.head)) {
         return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'committed HEAD does not descend from the baseline', resolved.taskId);
       }
       if (input.kind === 'pushed') {
@@ -1016,9 +1224,10 @@ function completeCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.complete', () => {
       readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
-      const inspection = inspectCommitFinalization(resolved.taskDir, resolved.repoRoot, resolved.taskId);
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
       return finalizeCommitIntentUnlocked(resolved, inspection, input.agent, () => {
         removeCommitIntent(resolved.taskDir, resolved.taskId, input.token);
       });
@@ -1036,8 +1245,15 @@ function recoverCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.recover', () => {
-      const inspection = inspectCommitFinalization(resolved.taskDir, resolved.repoRoot, resolved.taskId);
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      if (inspection.disposition === 'retryable-start') {
+        return {
+          status: 'ready', changed: false, taskId: resolved.taskId, intent: null,
+          finalization: commitFinalizationView(inspection), error: null
+        };
+      }
       if (inspection.disposition === 'prepared' && inspection.intentDigest) {
         removeCommitIntentByDigest(resolved.taskDir, resolved.taskId, inspection.intentDigest);
         return { status: 'ready', changed: true, taskId: resolved.taskId, intent: null, error: null };
@@ -1066,9 +1282,10 @@ function abortCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.abort', () => {
       const intent = readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
-      const currentHead = repositoryHead(resolved.repoRoot);
+      const currentHead = repositoryHead(gitRoot);
       if (
         intent.phase !== 'prepared'
         || intent.pushEvidence !== null
@@ -1088,7 +1305,13 @@ function abortCommitIntent(
 function statusCommitIntent(taskRef: string, options: OrchestrationOptions = {}): CommitIntentResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
-  const inspection = inspectCommitFinalization(resolved.taskDir, resolved.repoRoot, resolved.taskId);
+  let gitRoot: string;
+  try {
+    gitRoot = gitRootFor(resolved.repoRoot, options);
+  } catch (error) {
+    return commitIntentFailed('ORCHESTRATION_WORKTREE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
+  const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
   return {
     status: 'ready',
     changed: false,
@@ -1156,7 +1379,11 @@ function prepareOrchestrationDelegationUnlocked(
   }
   let beforeFingerprint: string;
   try {
-    beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot, resolved.taskId);
+    beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+      gitRoot: gitRootFor(resolved.repoRoot, options),
+      stateRoot: resolved.repoRoot,
+      taskId: resolved.taskId
+    });
   } catch (error) {
     return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
   }
@@ -1220,7 +1447,7 @@ function matchingDelegations(
     .filter((entry) => entry.isDirectory())
     .flatMap((entry) => {
       const run = readRun(path.join(activeRoot, entry.name));
-      if (!run?.pendingDelegation) return [];
+      if (run?.status !== 'running' || !run.pendingDelegation) return [];
       const receipt = run.pendingDelegation;
       return predicate(receipt)
         ? [{ taskId: entry.name, run }]
@@ -1254,13 +1481,44 @@ function activateMatchingOrchestrationDelegation(
     (receipt) => receipt.status === 'prepared',
     options
   );
-  if ('status' in matched) return matched;
+  if ('status' in matched) {
+    if (matched.error?.code !== 'ORCHESTRATION_DELEGATION_MISSING') return matched;
+    const replay = uniqueMatchingDelegation(
+      client,
+      (receipt) => receipt.childId === event.childId && ['activated', 'stage-completed'].includes(receipt.status),
+      options
+    );
+    if ('status' in replay) return matched;
+    const receipt = replay.run.pendingDelegation!;
+    const sameEvidence = receipt.parentId === event.parentId
+      && receipt.spawnMode === event.spawnMode
+      && receipt.actualModel === event.actualModel
+      && receipt.actualReasoningEffort === event.actualReasoningEffort
+      && receipt.modelFallbackReason === (event.modelFallbackReason ?? null)
+      && receipt.reasoningEffortFallbackReason === (event.reasoningEffortFallbackReason ?? null)
+      && receipt.hostEvidence?.hookDefinitionHash === event.hostEvidence?.hookDefinitionHash;
+    if (!sameEvidence) {
+      return pauseOrchestration(replay.taskId, 'DELEGATION_REPLAY_CONFLICT', 'replayed native start evidence conflicts with the active receipt', true, options);
+    }
+    return { status: replay.run.status, changed: false, taskId: replay.taskId, run: replay.run, next: null, error: null };
+  }
   if (matched.run.receipts.some((receipt) => receipt.childId === event.childId)) {
     return pauseOrchestration(matched.taskId, 'DELEGATION_IDENTITY_REUSED', 'native child identity was already used by this run', true, options);
   }
   return activateOrchestrationDelegation(matched.taskId, event, options);
 }
 
+function pauseMatchingOrchestrationDelegation(
+  client: AgentClientId,
+  code: string,
+  message: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const matched = uniqueMatchingDelegation(client, () => true, options);
+  if ('status' in matched) return matched;
+  return pauseOrchestration(matched.taskId, code, message, true, options);
+}
+
 function sealMatchingOrchestrationDelegation(
   client: AgentClientId,
   event: Readonly<{ nativeAgent: string; childId: string }>,
@@ -1280,9 +1538,14 @@ function sealMatchingOrchestrationDelegation(
   }
   const repoRoot = options.repoRoot ?? process.cwd();
   try {
+    const gitRoot = gitRootFor(repoRoot, options);
     const snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
-    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot, snapshotTaskId);
-    const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(repoRoot, receipt.beforeFingerprint, afterFingerprint);
+    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+      gitRoot,
+      stateRoot: repoRoot,
+      taskId: snapshotTaskId
+    });
+    const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(gitRoot, receipt.beforeFingerprint, afterFingerprint);
     return sealOrchestrationDelegation(matched.taskId, {
       childId: event.childId,
       exitCode: 0,
@@ -1300,6 +1563,96 @@ function sealMatchingOrchestrationDelegation(
   }
 }
 
+function sealMatchingOrchestrationDelegationWithHostEvidence(
+  client: AgentClientId,
+  event: Readonly<{ nativeAgent: string; childId: string }>,
+  consumeEvidence: (receipt: DelegationReceipt) => Readonly<{
+    stopRevision: number;
+    consumer: string;
+    consumedAt: string;
+  }>,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const role = managedDelegationRole(event.nativeAgent);
+  if (!role) return failed('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
+  const matched = uniqueMatchingDelegation(
+    client,
+    (receipt) => (
+      (receipt.status === 'stage-completed' || receipt.status === 'sealed')
+      && receipt.childId === event.childId
+    ),
+    options
+  );
+  if ('status' in matched) return matched;
+  const receipt = matched.run.pendingDelegation!;
+  if (receipt.status === 'sealed') {
+    return reconcileMatchingOrchestrationDelegation(client, event.childId, options);
+  }
+  if (receipt.role !== role) {
+    return pauseOrchestration(matched.taskId, 'DELEGATION_ROLE_MISMATCH', `managed role ${role} does not match ${receipt.role}`, true, options);
+  }
+  const repoRoot = options.repoRoot ?? process.cwd();
+  try {
+    const gitRoot = gitRootFor(repoRoot, options);
+    const snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
+    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+      gitRoot,
+      stateRoot: repoRoot,
+      taskId: snapshotTaskId
+    });
+    const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(gitRoot, receipt.beforeFingerprint, afterFingerprint);
+    const baseEvent = { childId: event.childId, exitCode: 0, afterFingerprint, changedPaths };
+    const validated = sealDelegation(receipt, baseEvent, { now: options.now });
+    if (!validated.ok) {
+      return pauseOrchestration(matched.taskId, validated.code, validated.message, true, options);
+    }
+    const hostEvidence = consumeEvidence(receipt);
+    const sealed = sealDelegation(receipt, { ...baseEvent, hostEvidence }, { now: options.now });
+    if (!sealed.ok) return pauseOrchestration(matched.taskId, sealed.code, sealed.message, true, options);
+    const resolved = resolveTaskRef(matched.taskId, { repoRoot });
+    if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+    const updated = withUpdatedRun(matched.run, { pendingDelegation: sealed.receipt }, options.now);
+    saveRun(resolved.taskDir, updated);
+    return { status: 'running', changed: true, taskId: matched.taskId, run: updated, next: null, error: null };
+  } catch (error) {
+    return pauseOrchestration(
+      matched.taskId,
+      'ORCHESTRATION_CODEX_EVIDENCE_FAILED',
+      error instanceof Error ? error.message : String(error),
+      true,
+      options
+    );
+  }
+}
+
+function reconcileMatchingOrchestrationDelegation(
+  client: AgentClientId,
+  childId: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const matched = uniqueMatchingDelegation(
+    client,
+    (receipt) => receipt.childId === childId,
+    options
+  );
+  if ('status' in matched) return matched;
+  const receipt = matched.run.pendingDelegation!;
+  if (
+    receipt.status !== 'sealed'
+    || receipt.hostEvidence?.consumer !== receipt.id
+    || receipt.hostEvidence.consumedAt === null
+  ) {
+    return pauseOrchestration(
+      matched.taskId,
+      'ORCHESTRATION_CODEX_RECONCILIATION_FAILED',
+      'Codex native spawn did not produce one sealed receipt with consumed host evidence',
+      true,
+      options
+    );
+  }
+  return { status: matched.run.status, changed: false, taskId: matched.taskId, run: matched.run, next: null, error: null };
+}
+
 function activateOrchestrationDelegation(
   taskRef: string,
   event: Parameters<typeof activateDelegation>[1],
@@ -1466,16 +1819,21 @@ export {
   completeOrchestrationStage,
   inspectOrchestrationStage,
   orchestrationPath,
+  pauseMatchingOrchestrationDelegation,
   pauseOrchestration,
   planOrchestrationStageCompletion,
   prepareOrchestrationDelegation,
   readRun,
+  reconcileMatchingOrchestrationDelegation,
   recoverCommitIntent,
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
+  sealMatchingOrchestrationDelegationWithHostEvidence,
   sealOrchestrationDelegation,
+  startCommitAttempt,
   statusCommitIntent,
-  statusOrchestration
+  statusOrchestration,
+  terminateCommitAttempt
 };
 export type {
   CommitIntentResult,
@@ -1486,5 +1844,6 @@ export type {
   OrchestrationRun,
   OrchestrationStageCompletion,
   OrchestrationStageIdentity,
-  OrchestrationStatus
+  OrchestrationStatus,
+  OrchestrationOptions
 };

package/lib/task/review-fingerprint.ts

@@ -3,6 +3,13 @@ import path from "node:path";
 
 import { artifactName, maxRound } from "./review-artifacts.ts";
 
+type ReviewedGitTree = string & { readonly __reviewedGitTree: unique symbol };
+const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
+
+export function parseReviewedGitTree(value: string): ReviewedGitTree | null {
+  return REVIEWED_TREE_RE.test(value) ? value as ReviewedGitTree : null;
+}
+
 // Paths excluded from the post-review coverage gate. Fail-closed: the gate
 // covers ALL tracked changes by default. This default denylist is EMPTY —
 // projects opt into exclusions explicitly via review.post_review_exclude_globs.
@@ -71,6 +78,8 @@ export function extractReviewedSnapshotTree(content: string): string {
   return match ? match[1]!.trim().replace(/`/g, "") : "";
 }
 
+export type { ReviewedGitTree };
+
 export function parseReviewVerdict(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.*?)\s*$/m);
   return match ? match[1]!.trim() : "";