@fitlab-ai/agent-infra 0.9.7 → 0.9.8

package/lib/task/ledger-intents.ts

@@ -12,6 +12,7 @@ import type { LedgerRow, ReviewStage } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+import { allowsManualOverride } from './guard-override.ts';
 
 type ReviewSeverity = 'blocker' | 'major' | 'minor';
 type ExecutorResponse = 'accepted' | 'adjusted' | 'refuted' | 'cannot-judge';
@@ -120,7 +121,8 @@ function mapWrite(intent: LedgerIntent, entityId: string, before: LedgerRow | nu
 function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {}): LedgerIntentResult {
   const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  const stateOverride = allowsManualOverride(options.manualOverride, 'ledger-intent', 'TASK_STATE_MISMATCH');
+  if (resolved.state !== 'active' && !stateOverride) return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   let content: string;
   let rows: LedgerRow[];
   try {
@@ -196,7 +198,8 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
             ? new Set(['confirmed', 'open', 'needs-human-decision'])
             : before.status === 'cannot-judge' ? new Set(['open', 'needs-human-decision']) : new Set<string>();
         const sameRoundMinorClose = before.status === 'open' && before.severity === 'minor' && intent.status === 'closed';
-        if ((!sameRoundMinorClose && !allowed.has(intent.status)) || (intent.status === 'open' && Number(before.round) >= maxHandshakeRounds(resolved.repoRoot))) {
+        if (((!sameRoundMinorClose && !allowed.has(intent.status)) || (intent.status === 'open' && Number(before.round) >= maxHandshakeRounds(resolved.repoRoot)))
+          && !allowsManualOverride(options.manualOverride, 'ledger-intent', 'LEDGER_TRANSITION_INVALID')) {
           return failed(intent, 'LEDGER_TRANSITION_INVALID', `finding '${intent.id}' cannot transition from ${before.status} to ${intent.status}`, resolved.taskId, intent.id);
         }
         after = { ...before, status: intent.status, evidence };
@@ -230,7 +233,7 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
   }
 
   const result = writeTask({
-    taskRef: intent.taskRef, expectedState: 'active',
+    taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active',
     mutations: [...ledgerSectionMutation(content), rowMutation(after), ...(implementationMutation ? [implementationMutation] : [])],
     dryRun: 'dryRun' in intent ? intent.dryRun : false
   }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });

package/lib/task/lifecycle.ts

@@ -16,6 +16,33 @@ import type { TaskFileSystem, TaskMutation, TaskOperationSummary, TaskWriteMetad
 const lifecycleIntentCatalog = [
   'block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore'
 ] as const;
+const lifecycleFailureCatalog = [
+  'LIFECYCLE_DIRECTORY_RENAME_FAILED',
+  'LIFECYCLE_DOCUMENT_INVALID',
+  'LIFECYCLE_FINAL_STATE_INVALID',
+  'LIFECYCLE_IDENTITY_CONFLICT',
+  'LIFECYCLE_IDENTITY_INVALID',
+  'LIFECYCLE_INTENT_CONFLICT',
+  'LIFECYCLE_JOURNAL_CLEANUP_FAILED',
+  'LIFECYCLE_JOURNAL_INVALID',
+  'LIFECYCLE_JOURNAL_WRITE_FAILED',
+  'LIFECYCLE_LOG_MISSING',
+  'LIFECYCLE_METADATA_FAILED',
+  'LIFECYCLE_PAYLOAD_INVALID',
+  'LIFECYCLE_SHORT_ID_FAILED',
+  'LIFECYCLE_SHORT_ID_PRECONDITION',
+  'LIFECYCLE_SOURCE_INVALID',
+  'LIFECYCLE_STAGING_IDENTITY_INVALID',
+  'LIFECYCLE_STAGING_INVALID',
+  'LIFECYCLE_TARGET_CONFLICT',
+  'LIFECYCLE_TASK_NOT_FOUND',
+  'SHORT_ID_CAPACITY_EXCEEDED'
+] as const;
+const lifecycleProducerCatalog = lifecycleFailureCatalog.map((code) => ({
+  producerId: 'lifecycle.apply' as const,
+  guardId: 'G-03' as const,
+  code
+}));
 type TaskLifecycleIntent = (typeof lifecycleIntentCatalog)[number];
 type TaskLifecycleRequest =
   | { taskRef: string; intent: 'block'; agent: string; reason: string; unblockCondition: string; dryRun?: boolean }
@@ -39,6 +66,7 @@ type LifecycleJournal = {
   targetState: HotState;
   metadata: TaskWriteMetadata;
   completedSteps: LifecycleStep[];
+  failure?: LifecycleError;
 };
 type TaskLifecycleResult = {
   status: 'planned' | 'applied' | 'no-op' | 'failed';
@@ -72,8 +100,13 @@ type TaskLifecycleOptions = {
   fileSystem?: Partial<LifecycleFileSystem>;
   taskFileSystem?: Partial<TaskFileSystem>;
   directoryRenameSync?: (source: string, target: string) => void;
+  manualOverride?: Readonly<{ failureId: string; operator: string; reason: string }>;
 };
 
+function allowsManualOverride(options: TaskLifecycleOptions, code: string): boolean {
+  return options.manualOverride?.failureId === `lifecycle.apply:${code}`;
+}
+
 const STEPS: readonly LifecycleStep[] = ['task-written', 'directory-moved', 'registry-committed'];
 const DEFAULT_IO: LifecycleFileSystem = {
   renameSync: (source, target) => fs.renameSync(source, target),
@@ -172,10 +205,16 @@ function matchingCompletion(content: string, request: TaskLifecycleRequest, rest
 }
 
 function validateRestoreStaging(request: Extract<TaskLifecycleRequest, { intent: 'restore' }>, repoRoot: string, taskId: string): LifecycleError | { stagingDir: string; fileCount: number } {
-  const workspace = path.resolve(repoRoot, '.agents', 'workspace');
-  const stagingDir = path.resolve(request.stagingDir);
+  let workspace: string;
+  let stagingDir: string;
+  try {
+    workspace = fs.realpathSync.native(path.resolve(repoRoot, '.agents', 'workspace'));
+    stagingDir = fs.realpathSync.native(path.resolve(request.stagingDir));
+  } catch (error) {
+    return { code: 'LIFECYCLE_STAGING_INVALID', message: String(error) };
+  }
   const relative = path.relative(workspace, stagingDir);
-  if (!relative || relative.startsWith('..') || path.isAbsolute(relative) || path.basename(stagingDir) === taskId) {
+  if (!relative || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative) || path.basename(stagingDir) === taskId) {
     return { code: 'LIFECYCLE_STAGING_INVALID', message: 'restore staging must be a non-final directory inside .agents/workspace' };
   }
   let entries: fs.Dirent[];
@@ -213,8 +252,8 @@ function validateRestoreStaging(request: Extract<TaskLifecycleRequest, { intent:
   return { stagingDir, fileCount: entries.filter((entry) => !entry.name.startsWith('.')).length };
 }
 
-function mutationsFor(request: TaskLifecycleRequest, content: string, metadata: TaskWriteMetadata, restoredFiles: number): TaskMutation[] | LifecycleError {
-  const section = locateActivityLog(content);
+function mutationsFor(request: TaskLifecycleRequest, content: string, metadata: TaskWriteMetadata, restoredFiles: number, allowMissingActivityLog = false): TaskMutation[] | LifecycleError {
+  const section = locateActivityLog(content) ?? (allowMissingActivityLog ? { heading: 'Activity Log', body: '', entries: [] } : null);
   if (!section) return { code: 'LIFECYCLE_LOG_MISSING', message: 'task has no unique Activity Log section' };
   const identity = actionAndNote(request, restoredFiles);
   let body = appendActivityEntry(section, { time: metadata.timestamp, step: `${identity.action} [started]`, agent: request.agent, note: 'started' });
@@ -261,6 +300,14 @@ function writeJournal(file: string, journal: LifecycleJournal, io: LifecycleFile
   }
 }
 
+function rememberJournalFailure(file: string, journal: LifecycleJournal, io: LifecycleFileSystem, failure: LifecycleError): void {
+  try {
+    writeJournal(file, { ...journal, failure }, io);
+  } catch {
+    // Preserve the original lifecycle failure when the diagnostic receipt cannot be updated.
+  }
+}
+
 function parseJournal(content: string): LifecycleJournal {
   const value = JSON.parse(content) as Partial<LifecycleJournal>;
   if (
@@ -326,7 +373,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     }
     return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: `task ${taskId} is already ${spec.target} with a different lifecycle intent` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
-  if (!spec.sources.includes(sourceState) && !existingJournal) {
+  if (!spec.sources.includes(sourceState) && !existingJournal && !allowsManualOverride(options, 'LIFECYCLE_SOURCE_INVALID')) {
     return failed(request, { code: 'LIFECYCLE_SOURCE_INVALID', message: `${request.intent} is not allowed from ${sourceState}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
   if (sourcePath !== targetPath && fs.existsSync(targetPath)) {
@@ -337,7 +384,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   try { frontmatter = parseTypedTaskFrontmatter(content); }
   catch (error) { return failed(request, { code: 'LIFECYCLE_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath }); }
   if (frontmatter.id !== taskId) return failed(request, { code: 'LIFECYCLE_IDENTITY_INVALID', message: 'task.md id does not match its lifecycle task id' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
-  if (!locateActivityLog(content)) return failed(request, { code: 'LIFECYCLE_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
+  if (!locateActivityLog(content) && !allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING')) return failed(request, { code: 'LIFECYCLE_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   const registryRequest = executeShortIdCommand({
     operation: 'list', activeDir: path.join(repoRoot, '.agents', 'workspace', 'active'),
     shortIdLength: configuredShortIdLength(repoRoot)
@@ -347,10 +394,10 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   }
   const registry = JSON.parse(registryRequest.output || '{"version":1,"ids":{}}') as { ids: Record<string, string> };
   const registeredKey = Object.entries(registry.ids).find(([, candidate]) => candidate === taskId)?.[0];
-  if (spec.registry === 'release' && sourceState === 'active' && !registeredKey) {
+  if (spec.registry === 'release' && sourceState === 'active' && !registeredKey && !allowsManualOverride(options, 'LIFECYCLE_SHORT_ID_PRECONDITION')) {
     return failed(request, { code: 'LIFECYCLE_SHORT_ID_PRECONDITION', message: 'active source has no short-id registry entry' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
-  if (spec.registry === 'alloc' && !registeredKey && Object.keys(registry.ids).length >= 10 ** configuredShortIdLength(repoRoot) - 1) {
+  if (spec.registry === 'alloc' && !registeredKey && Object.keys(registry.ids).length >= 10 ** configuredShortIdLength(repoRoot) - 1 && !allowsManualOverride(options, 'SHORT_ID_CAPACITY_EXCEEDED')) {
     return failed(request, { code: 'SHORT_ID_CAPACITY_EXCEEDED', message: 'short-id registry has no free slot' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
   const digest = intentIdentity(request, taskId);
@@ -360,14 +407,20 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   if (fs.existsSync(initialJournalPath)) {
     try { journal = parseJournal(io.readFileSync(initialJournalPath)); }
     catch (error) { return failed(request, { code: 'LIFECYCLE_JOURNAL_INVALID', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath }); }
-    if (journal.intentDigest !== digest || journal.taskId !== taskId) return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
+    if (journal.taskId !== taskId || journal.intent !== request.intent) return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
+    if (request.dryRun) {
+      if (!journal.failure) return failed(request, { code: 'LIFECYCLE_JOURNAL_INVALID', message: 'existing lifecycle journal has no durable failure evidence for a read-only probe' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
+      return failed(request, journal.failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath, completedSteps: journal.completedSteps, pendingSteps: STEPS.filter((step) => !journal.completedSteps.includes(step)) });
+    }
+    const overrideResumesRecordedFailure = journal.failure && allowsManualOverride(options, journal.failure.code);
+    if (journal.intentDigest !== digest && !overrideResumesRecordedFailure) return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
   } else {
     let metadata: TaskWriteMetadata;
     try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
     catch (error) { return failed(request, { code: 'LIFECYCLE_METADATA_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath }); }
     journal = { version: 1, taskId, intent: request.intent, intentDigest: digest, sourceState, targetState: spec.target, metadata, completedSteps: [] };
     if (request.dryRun) {
-      const plannedMutations = mutationsFor(request, content, metadata, restoredFiles);
+      const plannedMutations = mutationsFor(request, content, metadata, restoredFiles, allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING'));
       if ('code' in plannedMutations) return failed(request, plannedMutations, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
       const taskPlan = writeTask(
         { taskRef: taskId, expectedState: sourceState === 'blocked' ? 'blocked' : 'active', mutations: plannedMutations, dryRun: true },
@@ -403,7 +456,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   if (matchingCompletion(io.readFileSync(path.join(sourcePath, 'task.md')), request, restoredFiles)) completed.add('task-written');
   if (!completed.has('task-written')) {
     const current = io.readFileSync(path.join(sourcePath, 'task.md'));
-    const mutations = mutationsFor(request, current, journal.metadata, restoredFiles);
+    const mutations = mutationsFor(request, current, journal.metadata, restoredFiles, allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING'));
     if ('code' in mutations) return failed(request, mutations, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, completedSteps: [...completed], changed: completed.size > 0 });
     const writeResult = writeTask(
       { taskRef: taskId, expectedState: sourceState === 'blocked' ? 'blocked' : 'active', mutations },
@@ -424,7 +477,11 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     fs.mkdirSync(path.dirname(targetPath), { recursive: true });
     if (fs.existsSync(targetPath)) return failed(request, { code: 'LIFECYCLE_TARGET_CONFLICT', message: `target directory already exists: ${targetPath}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
     try { (options.directoryRenameSync ?? io.renameSync)(sourcePath, targetPath); }
-    catch (error) { return failed(request, { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion }); }
+    catch (error) {
+      const failure = { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) } as const;
+      rememberJournalFailure(journalPath, journal, io, failure);
+      return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+    }
     completed.add('directory-moved'); journal.completedSteps = [...completed]; journalPath = path.join(targetPath, '.task-lifecycle.json');
     try { writeJournal(journalPath, journal, io); }
     catch (error) { return failed(request, { code: 'LIFECYCLE_JOURNAL_WRITE_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, directory: { effect: 'move', changed: true }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion }); }
@@ -451,7 +508,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   };
 }
 
-export { lifecycleIntentCatalog, applyTaskLifecycle };
+export { lifecycleIntentCatalog, lifecycleFailureCatalog, lifecycleProducerCatalog, applyTaskLifecycle };
 export type {
   TaskLifecycleIntent, TaskLifecycleRequest, TaskLifecycleResult, TaskLifecycleOptions,
   LifecycleError, LifecycleJournal, LifecycleStep

package/lib/task/orchestration.ts

@@ -14,6 +14,7 @@ import {
   completeDelegationStage,
   consumeDelegation,
   dispatchDelegation,
+  foldBlankToNull,
   managedDelegationRole,
   prepareDelegation,
   sealDelegation
@@ -25,6 +26,7 @@ import type {
   DelegationStage
 } from './delegation-receipts.ts';
 import { normalizeAgentClients } from '../agent-clients/config.ts';
+import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.ts';
 import { inspectPlatformPullRequest } from '../platform/pull-requests.ts';
 import {
   getAgentClientCapability,
@@ -112,6 +114,25 @@ type ClientCapabilityRecovery = Readonly<{
   }>;
   resultingStatus: 'running';
 }>;
+type ClaudeCodeCapabilityRecovery = Readonly<{
+  code: 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION';
+  recoveredAt: string;
+  previousSchemaVersion: 3;
+  previousStatus: 'paused';
+  previousPause: Readonly<{ code: 'ORCHESTRATION_CLIENT_UNSUPPORTED'; message: string; recoverable: boolean }>;
+  client: 'claude-code';
+  guards: Readonly<{
+    stepCount: 0;
+    nextStage: null;
+    baselineEmpty: true;
+    receiptCount: 0;
+    pendingDelegation: false;
+    commitAuthorizationUnused: true;
+    completionEvidenceAbsent: true;
+    commitIntentAbsent: true;
+  }>;
+  resultingStatus: 'running';
+}>;
 type SchemaMigrationRecovery = Readonly<{
   code: 'SCHEMA_V3_MIGRATED';
   recoveredAt: string;
@@ -130,7 +151,7 @@ type SchemaMigrationRecovery = Readonly<{
   }>;
   resultingStatus: 'running';
 }>;
-type OrchestrationRecovery = ModelPolicyRecovery | ClientCapabilityRecovery | SchemaMigrationRecovery;
+type OrchestrationRecovery = ModelPolicyRecovery | ClientCapabilityRecovery | ClaudeCodeCapabilityRecovery | SchemaMigrationRecovery;
 type CleanCompletionEvidence = Readonly<{
   kind: 'reviewed-head-clean';
   observedAt: string;
@@ -435,6 +456,23 @@ function canRecoverCodexUnsupportedPause(run: OrchestrationRun, taskDir: string)
     && (run.recoveryHistory ?? []).every((entry) => entry.code === 'MODEL_POLICY_SUPPLEMENTED');
 }
 
+function canRecoverClaudeCodeUnsupportedPause(run: OrchestrationRun, taskDir: string): boolean {
+  return run.schemaVersion === 3
+    && run.status === 'paused'
+    && run.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+    && run.modelPolicySource?.client === 'claude-code'
+    && 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 ?? []).length === 0;
+}
+
 function canMigrateRecoverableV2Pause(run: OrchestrationRun, taskDir: string): boolean {
   return run.schemaVersion === 2
     && run.status === 'paused'
@@ -504,6 +542,39 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
         }
       }
       if (existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED') {
+        if (existing.modelPolicySource.client === 'claude-code') {
+          if (!canRecoverClaudeCodeUnsupportedPause(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 ClaudeCodeCapabilityRecovery['previousPause'];
+          const recovery: ClaudeCodeCapabilityRecovery = {
+            code: 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION',
+            recoveredAt: now,
+            previousSchemaVersion: 3,
+            previousStatus: 'paused',
+            previousPause,
+            client: 'claude-code',
+            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 (!canRecoverCodexUnsupportedPause(existing, resolved.taskDir)) {
           return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
         }
@@ -1667,9 +1738,9 @@ function activateMatchingOrchestrationDelegation(
     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.spawnMode ?? null) === (event.spawnMode ?? null)
+      && (receipt.actualModel ?? null) === foldBlankToNull(event.actualModel)
+      && (receipt.actualReasoningEffort ?? null) === foldBlankToNull(event.actualReasoningEffort)
       && receipt.modelFallbackReason === (event.modelFallbackReason ?? null)
       && receipt.reasoningEffortFallbackReason === (event.reasoningEffortFallbackReason ?? null)
       && receipt.hostEvidence?.hookDefinitionHash === event.hostEvidence?.hookDefinitionHash;
@@ -1697,7 +1768,14 @@ function pauseMatchingOrchestrationDelegation(
 
 function sealMatchingOrchestrationDelegation(
   client: AgentClientId,
-  event: Readonly<{ nativeAgent: string; childId: string }>,
+  event: Readonly<{
+    nativeAgent: string;
+    childId: string;
+    actualModel?: string;
+    actualReasoningEffort?: string;
+    modelFallbackReason?: string;
+    reasoningEffortFallbackReason?: string;
+  }>,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
   const role = managedDelegationRole(event.nativeAgent);
@@ -1726,7 +1804,11 @@ function sealMatchingOrchestrationDelegation(
       childId: event.childId,
       exitCode: 0,
       afterFingerprint,
-      changedPaths
+      changedPaths,
+      actualModel: event.actualModel,
+      actualReasoningEffort: event.actualReasoningEffort,
+      modelFallbackReason: event.modelFallbackReason,
+      reasoningEffortFallbackReason: event.reasoningEffortFallbackReason
     }, options);
   } catch (error) {
     return pauseOrchestration(
@@ -1955,7 +2037,7 @@ function recoverPreparedOrchestrationDelegation(
           receipt.client === 'codex'
           && receipt.lifecycleProvenance
           && hasActiveCodexLifecycleEvidence(
-            path.join(resolved.repoRoot, '.agents', 'workspace', '.runtime', 'codex-lifecycle'),
+          resolveAgentRuntimeStoreRoot({ repoRoot: resolved.repoRoot, store: 'lifecycle' }),
             {
               nativeAgent: `agent-infra-lifecycle-${receipt.role}`,
               hookDefinitionHash: receipt.lifecycleProvenance.hookDefinitionHash

package/lib/task/review-finalization.ts

@@ -11,6 +11,8 @@ import { resolveTaskRef } from './resolve-ref.ts';
 import { validateLifecycleExecution } from './lifecycle-execution.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import type { ResolveTaskRefErrorCode } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -62,6 +64,8 @@ type ReviewFinalizationOptions = {
   repoRoot?: string;
   randomSuffix?: () => string;
   fileSystem?: Partial<ReviewFileSystem>;
+  manualOverride?: ManualOverrideCapability;
+  lockAlreadyHeld?: boolean;
 };
 
 const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code'; action: string }> = {
@@ -127,7 +131,7 @@ function finalizeReviewSummaryUnlocked(
   }
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(request, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') {
+  if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'review-finalization', 'TASK_STATE_MISMATCH')) {
     return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   }
   const parsedArtifact = parseArtifactName(request.artifact);
@@ -275,7 +279,7 @@ function finalizeReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
-  if (request.dryRun) return finalizeReviewSummaryUnlocked(request, options);
+  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, options);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, options);
   try {

package/lib/task/verification-engine.ts

@@ -291,7 +291,22 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
       && guards?.commitAuthorizationUnused === true
       && guards?.completionEvidenceAbsent === true
       && guards?.commitIntentAbsent === true;
-    if (!validModelRecovery && !validCapabilityRecovery) {
+    const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION'
+      && recovery.previousSchemaVersion === 3
+      && recovery.previousStatus === 'paused'
+      && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+      && recovery.client === 'claude-code'
+      && recovery.resultingStatus === 'running'
+      && exactText(recovery.recoveredAt)
+      && guards?.stepCount === 0
+      && guards?.nextStage === null
+      && guards?.baselineEmpty === true
+      && guards?.receiptCount === 0
+      && guards?.pendingDelegation === false
+      && guards?.commitAuthorizationUnused === true
+      && guards?.completionEvidenceAbsent === true
+      && guards?.commitIntentAbsent === true;
+    if (!validModelRecovery && !validCapabilityRecovery && !validClaudeCodeRecovery) {
       return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
     }
   }
@@ -322,29 +337,40 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     }
     const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
     if (activated) {
-      if (!exactText(receipt.actualModel)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+      const isClaudeCode = receipt.client === 'claude-code';
+      if (!isClaudeCode) {
+        if (!exactText(receipt.actualModel)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+        }
+        if (!exactText(receipt.actualReasoningEffort)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+        }
       }
-      if (!exactText(receipt.actualReasoningEffort)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+      // parentId/childId 校验对所有 client 保持统一（不新增分支）；spawnMode 检查按 client 判断
+      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid delegation identity`);
       }
-      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId || receipt.spawnMode !== 'fresh') {
+      if (!isClaudeCode && receipt.spawnMode !== 'fresh') {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
       }
-      if (receipt.actualModel !== receipt.requestedModel && !exactText(receipt.modelFallbackReason)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
-      }
-      if (receipt.actualModel === receipt.requestedModel && receipt.modelFallbackReason !== null) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      if (receipt.actualModel != null && receipt.actualModel !== receipt.requestedModel) {
+        if (!isClaudeCode && !exactText(receipt.modelFallbackReason)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+        }
       }
       if (
-        receipt.actualReasoningEffort !== receipt.requestedReasoningEffort
-        && !exactText(receipt.reasoningEffortFallbackReason)
+        (receipt.actualModel == null || receipt.actualModel === receipt.requestedModel)
+        && receipt.modelFallbackReason !== null
       ) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      }
+      if (receipt.actualReasoningEffort != null && receipt.actualReasoningEffort !== receipt.requestedReasoningEffort) {
+        if (!isClaudeCode && !exactText(receipt.reasoningEffortFallbackReason)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+        }
       }
       if (
-        receipt.actualReasoningEffort === receipt.requestedReasoningEffort
+        (receipt.actualReasoningEffort == null || receipt.actualReasoningEffort === receipt.requestedReasoningEffort)
         && receipt.reasoningEffortFallbackReason !== null
       ) {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
@@ -902,7 +928,7 @@ function checkReviewLedger({ taskDir, config }: any): any {
   }
 
   const stageScope = Array.isArray(config.stage_scope) ? config.stage_scope : null;
-  const maxRounds = Number(resolveReviewSetting(config, "max_handshake_rounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
+  const maxRounds = Number(resolveReviewSetting(config, "maxHandshakeRounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
   const problems = [];
   let inScopeCount = 0;
 

package/lib/task/verification.ts

@@ -7,6 +7,8 @@ import { parseArtifactName } from './artifact-lifecycle.ts';
 import type { ArtifactFamily } from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import type { TaskWorkspaceState } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 
 type VerificationEvent =
   | 'analyze.awaiting-input' | 'analyze.completed'
@@ -48,6 +50,7 @@ type TaskVerificationResult = {
 type VerificationOptions = {
   repoRoot?: string;
   engine?: typeof verifyInProcess;
+  manualOverride?: ManualOverrideCapability;
 };
 
 const gate = (skill: string, expectedState: VerificationSpec['expectedState'], artifactFamily?: ArtifactFamily): VerificationSpec => ({
@@ -93,7 +96,7 @@ function verifyTaskEvent(request: { taskRef: string; event: string; artifact?: s
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failure(request, resolved.code, resolved.message, { taskId: resolved.taskId, skill: spec.skill, mode: spec.mode });
   const identity = { taskId: resolved.taskId, taskDir: resolved.taskDir, taskState: resolved.state, skill: spec.skill, mode: spec.mode } as const;
-  if (resolved.state !== spec.expectedState) {
+  if (resolved.state !== spec.expectedState && !allowsManualOverride(options.manualOverride, 'task-verify', 'VERIFY_TASK_STATE_MISMATCH')) {
     return failure(request, 'VERIFY_TASK_STATE_MISMATCH', `event '${request.event}' requires workspace '${spec.expectedState}', received '${resolved.state}'`, identity);
   }
   if (spec.artifactFamily) {
@@ -111,11 +114,22 @@ function verifyTaskEvent(request: { taskRef: string; event: string; artifact?: s
   if (spec.mode === 'gate') {
     const payload = engine({ mode: 'gate', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [], repositoryRoot: resolved.repoRoot }) as Record<string, unknown>;
     const status = payload.gate as 'pass' | 'fail' | 'blocked';
+    if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+      invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, gate: 'pass', humanOverride: 'human-approved', originalGate: status } });
+      return {
+        status: 'pass', changed: false, event: request.event, requestRef: request.taskRef,
+        ...identity, artifact: request.artifact ?? null, invocations, error: null
+      };
+    }
     invocations.push({ status, exitCode: ({ pass: 0, fail: 1, blocked: 2 } as const)[status], payload });
   } else {
     for (const check of spec.checks ?? []) {
       const payload = engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot }) as Record<string, unknown>;
       const status = payload.status as 'pass' | 'fail' | 'blocked';
+      if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+        invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, status: 'pass', humanOverride: 'human-approved', originalStatus: status } });
+        break;
+      }
       invocations.push({ status, exitCode: ({ pass: 0, fail: 1, blocked: 2 } as const)[status], payload });
       if (status !== 'pass') break;
     }

package/lib/task/workflow-warning-intents.ts

@@ -11,6 +11,7 @@ import {
 import type { WorkflowWarning } from './workflow-warnings.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+import { allowsManualOverride } from './guard-override.ts';
 
 type WarningSeverity = 'IMPORTANT' | 'ACTION_REQUIRED';
 type WarningStatus = 'open' | 'resolved' | 'ignored';
@@ -79,7 +80,8 @@ function rowMutation(row: WorkflowWarning): TaskMutation {
 function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: TaskWriteOptions = {}): WorkflowWarningIntentResult {
   const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  const stateOverride = allowsManualOverride(options.manualOverride, 'workflow-warning', 'TASK_STATE_MISMATCH');
+  if (resolved.state !== 'active' && !stateOverride) return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   let content: string;
   let rows: WorkflowWarning[];
   try {
@@ -125,7 +127,7 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
   }
 
   const writeResult = writeTask({
-    taskRef: intent.taskRef, expectedState: 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
+    taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
   }, {
     ...options,
     taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },

package/lib/task/write.ts

@@ -12,6 +12,8 @@ import type {
   ResolveTaskRefErrorCode,
   TaskWorkspaceState
 } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 import { mutateTableRow, upsertSection } from './sections.ts';
 import type {
   TableRowDeleteMutation,
@@ -156,6 +158,7 @@ type TaskWriteOptions = {
   metadataProvider?: () => TaskWriteMetadata;
   randomSuffix?: () => string;
   fileSystem?: Partial<TaskFileSystem>;
+  manualOverride?: ManualOverrideCapability;
 };
 
 const DEFAULT_FILE_SYSTEM: TaskFileSystem = {
@@ -241,7 +244,7 @@ function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): T
     taskMdPath: resolved.taskMdPath,
     actualState: resolved.state
   };
-  if (resolved.state !== request.expectedState) {
+  if (resolved.state !== request.expectedState && !allowsManualOverride(options.manualOverride, 'task.write', 'TASK_STATE_MISMATCH')) {
     return failure(
       request,
       identity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.7",
+  "version": "0.9.8",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",