@fitlab-ai/agent-infra 0.9.15 → 0.11.0

package/lib/task/artifact-repair-intent.ts

@@ -3,36 +3,63 @@ import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
 import type { ArtifactSchemaFamily } from './artifact-schema.ts';
+import { parseArtifactName } from './artifact-name.ts';
 
-export type ArtifactRepairPhase =
+export type ArtifactRecoveryPhase =
   | 'orchestration.prepare'
   | 'artifact.finalize-local'
   | 'task-event.completed';
-export type ArtifactRepairState = 'awaiting-repair' | 'finalize-ready' | 'commit-started' | 'passed' | 'consumed';
+export type ArtifactRecoveryState =
+  | 'awaiting-preflight-recovery'
+  | 'preflight-ready'
+  | 'preflight-commit-started'
+  | 'preflight-passed'
+  | 'full-finalizer-ready'
+  | 'commit-started'
+  | 'passed'
+  | 'consumption-started'
+  | 'consumed'
+  | 'aborted';
 
-export type ArtifactRepairIntent = Readonly<{
-  version: 2;
+export type ArtifactRecoveryIntent = Readonly<{
+  version: 4;
   taskId: string;
   family: ArtifactSchemaFamily;
   artifact: string;
-  state: ArtifactRepairState;
-  baselineSemanticDigest: string | null;
-  artifactSha256: string;
-  semanticDigest: string;
-  recoveryOperationId: string | null;
-  phase: ArtifactRepairPhase | null;
+  round: number;
+  state: ArtifactRecoveryState;
+  baselineSha256: string;
+  baselineSemanticDigest: string;
+  stagingId: string;
+  candidateSha256: string | null;
+  preflightArtifactSha256: string | null;
+  preflightSemanticDigest: string | null;
+  activeGenerationSha256: string | null;
+  activeGenerationSemanticDigest: string | null;
+  pendingGenerationSha256: string | null;
+  pendingGenerationSemanticDigest: string | null;
+  finalArtifactSha256: string | null;
+  finalSemanticDigest: string | null;
+  recoveryOperationId: string;
+  phase: ArtifactRecoveryPhase | null;
   authorityDigest: string | null;
   requestId: string;
+  errorCode: string | null;
+  errorMessage: string | null;
   createdAt: number;
   updatedAt: number;
 }>;
 
-function intentRoot(repoRoot: string): string {
+export function artifactRecoveryIntentRoot(repoRoot: string): string {
   return path.join(repoRoot, '.agents', 'workspace', '.local-artifact-finalization-intents');
 }
 
+export function artifactRecoveryRoot(taskDir: string, stagingId: string): string {
+  return path.join(taskDir, '.local-artifact-recovery', stagingId);
+}
+
 function intentPath(repoRoot: string, taskId: string, family: ArtifactSchemaFamily, artifact: string): string {
-  return path.join(intentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
+  return path.join(artifactRecoveryIntentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
 }
 
 function validDigest(value: unknown): value is string {
@@ -43,82 +70,132 @@ function validTaskId(value: unknown): value is string {
   return typeof value === 'string' && /^TASK-\d{8}-\d{6}$/u.test(value);
 }
 
+function validToken(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && !/[\r\n]/u.test(value);
+}
+
+function validRecoveryId(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f0-9-]{16,64}$/u.test(value);
+}
+
+function validArtifact(value: unknown, family: unknown, round: unknown): value is string {
+  if (typeof value !== 'string' || path.basename(value) !== value || !value.endsWith('.md')) return false;
+  const parsed = parseArtifactName(value);
+  return Boolean(parsed && parsed.family === family && parsed.round === round);
+}
+
 function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
   return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
 }
 
-export function isArtifactRepairIntent(value: unknown): value is ArtifactRepairIntent {
+export function isArtifactRecoveryIntent(value: unknown): value is ArtifactRecoveryIntent {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const intent = value as Record<string, unknown>;
   return exactKeys(intent, [
-    'artifact', 'artifactSha256', 'authorityDigest', 'baselineSemanticDigest', 'createdAt',
-    'family', 'phase', 'recoveryOperationId', 'requestId', 'semanticDigest', 'state',
-    'taskId', 'updatedAt', 'version'
+    'activeGenerationSemanticDigest', 'activeGenerationSha256', 'artifact', 'authorityDigest', 'baselineSemanticDigest', 'baselineSha256', 'candidateSha256',
+    'createdAt', 'errorCode', 'errorMessage', 'family', 'finalArtifactSha256', 'finalSemanticDigest',
+    'pendingGenerationSemanticDigest', 'pendingGenerationSha256', 'phase', 'preflightArtifactSha256', 'preflightSemanticDigest', 'recoveryOperationId', 'requestId', 'round', 'stagingId', 'state', 'taskId', 'updatedAt',
+    'version'
   ])
-    && intent.version === 2
+    && intent.version === 4
     && validTaskId(intent.taskId)
     && typeof intent.family === 'string'
     && ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(intent.family)
-    && typeof intent.artifact === 'string' && intent.artifact.length > 0
-    && ['awaiting-repair', 'finalize-ready', 'commit-started', 'passed', 'consumed'].includes(String(intent.state))
-    && (intent.baselineSemanticDigest === null || validDigest(intent.baselineSemanticDigest))
-    && validDigest(intent.artifactSha256)
-    && validDigest(intent.semanticDigest)
-    && (intent.recoveryOperationId === null || (typeof intent.recoveryOperationId === 'string' && /^[a-f0-9-]{16,64}$/u.test(intent.recoveryOperationId)))
+    && Number.isSafeInteger(intent.round) && (intent.round as number) > 0
+    && validArtifact(intent.artifact, intent.family, intent.round)
+    && ['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started', 'passed', 'consumption-started', 'consumed', 'aborted'].includes(String(intent.state))
+    && validDigest(intent.baselineSha256)
+    && validDigest(intent.baselineSemanticDigest)
+    && validRecoveryId(intent.stagingId)
+    && (intent.candidateSha256 === null || validDigest(intent.candidateSha256))
+    && (intent.preflightArtifactSha256 === null || validDigest(intent.preflightArtifactSha256))
+    && (intent.preflightSemanticDigest === null || validDigest(intent.preflightSemanticDigest))
+    && (intent.activeGenerationSha256 === null || validDigest(intent.activeGenerationSha256))
+    && (intent.activeGenerationSemanticDigest === null || validDigest(intent.activeGenerationSemanticDigest))
+    && (intent.pendingGenerationSha256 === null || validDigest(intent.pendingGenerationSha256))
+    && (intent.pendingGenerationSemanticDigest === null || validDigest(intent.pendingGenerationSemanticDigest))
+    && (intent.finalArtifactSha256 === null || validDigest(intent.finalArtifactSha256))
+    && (intent.finalSemanticDigest === null || validDigest(intent.finalSemanticDigest))
+    && validRecoveryId(intent.recoveryOperationId)
+    && intent.stagingId === intent.recoveryOperationId
     && (intent.phase === null || ['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(String(intent.phase)))
     && (intent.authorityDigest === null || validDigest(intent.authorityDigest))
-    && typeof intent.requestId === 'string' && intent.requestId.length > 0 && !/[\r\n]/u.test(intent.requestId)
-    && Number.isSafeInteger(intent.createdAt) && Number.isSafeInteger(intent.updatedAt)
-    && (intent.state === 'awaiting-repair' ? intent.baselineSemanticDigest === intent.semanticDigest : true);
+    && validToken(intent.requestId)
+    && (intent.errorCode === null || validToken(intent.errorCode))
+    && (intent.errorMessage === null || validToken(intent.errorMessage))
+    && Number.isSafeInteger(intent.createdAt)
+    && Number.isSafeInteger(intent.updatedAt)
+    && (intent.state === 'awaiting-preflight-recovery'
+      ? intent.preflightArtifactSha256 === null && intent.preflightSemanticDigest === null
+        && intent.activeGenerationSha256 === null && intent.activeGenerationSemanticDigest === null
+        && intent.pendingGenerationSha256 === null && intent.pendingGenerationSemanticDigest === null
+        && intent.finalArtifactSha256 === null && intent.finalSemanticDigest === null
+      : true)
+    && (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started' || intent.state === 'preflight-passed' || intent.state === 'full-finalizer-ready' || intent.state === 'commit-started' || intent.state === 'passed' || intent.state === 'consumed'
+      ? validDigest(intent.candidateSha256) && validDigest(intent.preflightArtifactSha256) && validDigest(intent.preflightSemanticDigest)
+        && validDigest(intent.activeGenerationSha256) && validDigest(intent.activeGenerationSemanticDigest)
+      : true)
+    && (intent.state === 'full-finalizer-ready' || intent.state === 'commit-started'
+      ? validDigest(intent.pendingGenerationSha256) && validDigest(intent.pendingGenerationSemanticDigest)
+        && validDigest(intent.finalArtifactSha256) && validDigest(intent.finalSemanticDigest)
+      : true)
+    && (intent.state === 'passed' || intent.state === 'consumption-started' || intent.state === 'consumed'
+      ? validDigest(intent.finalArtifactSha256) && validDigest(intent.finalSemanticDigest)
+      : true)
+    && (intent.state === 'aborted' ? intent.errorCode !== null && intent.errorMessage !== null : true);
 }
 
-function readArtifactRepairIntent(
+export function readArtifactRecoveryIntent(
   repoRoot: string,
   taskId: string,
   family: ArtifactSchemaFamily,
   artifact: string
-): ArtifactRepairIntent | null {
+): ArtifactRecoveryIntent | null {
+  if (!validTaskId(taskId) || !validArtifact(artifact, family, parseArtifactName(artifact)?.round)) {
+    throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal identity is invalid');
+  }
   const target = intentPath(repoRoot, taskId, family, artifact);
   if (!fs.existsSync(target)) return null;
   let value: unknown;
   try { value = JSON.parse(fs.readFileSync(target, 'utf8')) as unknown; }
-  catch (error) { throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`); }
-  if (!isArtifactRepairIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
-    throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+  catch (error) { throw new Error(`ARTIFACT_RECOVERY_INTENT_INVALID: ${String(error)}`); }
+  if (!isArtifactRecoveryIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
+    throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
   }
   return value;
 }
 
-export function writeArtifactRepairIntent(
+export function writeArtifactRecoveryIntent(
   repoRoot: string,
-  value: ArtifactRepairIntent,
-  options: Readonly<{ expected?: ArtifactRepairIntent | null }> = {}
+  value: unknown,
+  options: Readonly<{ expected?: ArtifactRecoveryIntent | null }> = {}
 ): void {
-  if (!isArtifactRepairIntent(value)) throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
-  const directory = intentRoot(repoRoot);
+  if (!isArtifactRecoveryIntent(value)) throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
+  const intent = value;
+  const directory = artifactRecoveryIntentRoot(repoRoot);
   fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-  const target = intentPath(repoRoot, value.taskId, value.family, value.artifact);
+  const target = intentPath(repoRoot, intent.taskId, intent.family, intent.artifact);
   const lock = `${target}.lock`;
   let descriptor: number;
   try { descriptor = fs.openSync(lock, 'wx', 0o600); }
   catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
-      throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: another provenance writer owns the intent');
+      throw new Error('ARTIFACT_RECOVERY_INTENT_CONFLICT: another journal writer owns the intent');
     }
     throw error;
   }
   try {
     const current = fs.existsSync(target)
-      ? readArtifactRepairIntent(repoRoot, value.taskId, value.family, value.artifact)
+      ? readArtifactRecoveryIntent(repoRoot, intent.taskId, intent.family, intent.artifact)
       : null;
     if (!isDeepStrictEqual(current, options.expected ?? null)) {
-      throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: repair provenance changed during finalization');
+      throw new Error('ARTIFACT_RECOVERY_INTENT_CONFLICT: recovery journal changed during finalization');
     }
     const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    fs.writeFileSync(temporary, `${JSON.stringify(intent)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
     try { fs.renameSync(temporary, target); }
     catch (error) {
-      try { fs.unlinkSync(temporary); } catch { /* preserve primary error */ }
+      try { fs.unlinkSync(temporary); } catch { /* preserve the primary error */ }
       throw error;
     }
   } finally {
@@ -127,14 +204,12 @@ export function writeArtifactRepairIntent(
   }
 }
 
-export function findArtifactRepairIntentsByOperation(
+export function findArtifactRecoveryIntentsByOperation(
   repoRoot: string,
   operationId: string
-): readonly ArtifactRepairIntent[] {
-  if (!operationId || /[\r\n]/u.test(operationId)) {
-    throw new Error('ARTIFACT_REPAIR_OPERATION_INVALID: recovery operation id is invalid');
-  }
-  const directory = intentRoot(repoRoot);
+): readonly ArtifactRecoveryIntent[] {
+  if (!validToken(operationId)) throw new Error('ARTIFACT_RECOVERY_OPERATION_INVALID: recovery operation id is invalid');
+  const directory = artifactRecoveryIntentRoot(repoRoot);
   if (!fs.existsSync(directory)) return Object.freeze([]);
   return Object.freeze(fs.readdirSync(directory)
     .filter((name) => name.endsWith('.json'))
@@ -142,11 +217,11 @@ export function findArtifactRepairIntentsByOperation(
       const target = path.join(directory, name);
       let value: unknown;
       try { value = JSON.parse(fs.readFileSync(target, 'utf8')) as unknown; }
-      catch (error) { throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`); }
-      if (!isArtifactRepairIntent(value)) throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+      catch (error) { throw new Error(`ARTIFACT_RECOVERY_INTENT_INVALID: ${String(error)}`); }
+      if (!isArtifactRecoveryIntent(value)) throw new Error('ARTIFACT_RECOVERY_INTENT_INVALID: recovery journal schema is invalid');
       return value;
     })
     .filter((value) => value.recoveryOperationId === operationId));
 }
 
-export { readArtifactRepairIntent };
+export { intentPath as artifactRecoveryIntentPath };

package/lib/task/commit-operation.ts

@@ -32,6 +32,8 @@ type CommitOperationInput = Readonly<{
   agent?: string;
   mode?: CommitExecutionMode;
   round?: number;
+  /** Permit one retry to rebase a prepared intent's expected tree while HEAD and intent identity remain unchanged. */
+  recoverPreparedIntent?: boolean;
   delivery?: Readonly<{
     mode: 'local' | 'push';
     remote: string;
@@ -280,6 +282,20 @@ function checkpointTimestamp(): string {
   return new Date().toISOString();
 }
 
+function samePreparedCheckpointIdentity(
+  pending: NonNullable<ReturnType<typeof readCheckpointIntent>>,
+  identity: Parameters<typeof checkpointIntentDigest>[0]
+): boolean {
+  return pending.state === 'prepared'
+    && pending.taskId === identity.taskId
+    && pending.branch === identity.branch
+    && pending.mode === identity.mode
+    && pending.expectedHead === identity.expectedHead
+    && pending.message === identity.message
+    && pending.round === identity.round
+    && JSON.stringify(pending.paths) === JSON.stringify(identity.paths);
+}
+
 function executeUnlocked(input: CommitOperationInput, task: BoundTask | null, mode: CommitExecutionMode): CommitOperationResult {
   const inspected = inspectGitWorkflow(input.cwd);
   if (!inspected.snapshot) return failure(input, mode, task?.taskId ?? null, 'GIT_INSPECT_FAILED', 'Unable to inspect Git repository');
@@ -313,10 +329,25 @@ function executeUnlocked(input: CommitOperationInput, task: BoundTask | null, mo
           error: { code: 'COMMIT_INTENT_INVALID', message: error instanceof Error ? error.message : String(error) }
         };
       }
-      if (pendingIntent && !sameCheckpointIntent(pendingIntent, identity)) return {
-        status: 'failed' as const, changed: false, snapshot: inspected.snapshot, operations: [],
-        error: { code: 'COMMIT_INTENT_CONFLICT', message: 'A different checkpoint intent is still pending for this task' }
-      };
+      if (pendingIntent && !sameCheckpointIntent(pendingIntent, identity)) {
+        if (!input.recoverPreparedIntent || !samePreparedCheckpointIdentity(pendingIntent, identity)) return {
+          status: 'failed' as const, changed: false, snapshot: inspected.snapshot, operations: [],
+          error: { code: 'COMMIT_INTENT_CONFLICT', message: 'A different checkpoint intent is still pending for this task' }
+        };
+        pendingIntent = {
+          ...pendingIntent,
+          expectedTree: identity.expectedTree,
+          digest: checkpointIntentDigest(identity),
+          updatedAt: checkpointTimestamp()
+        };
+        try { writeCheckpointIntent(task!.repoRoot, pendingIntent); }
+        catch (error) {
+          return {
+            status: 'failed' as const, changed: false, snapshot: inspected.snapshot, operations: [],
+            error: { code: 'COMMIT_INTENT_WRITE_FAILED', message: error instanceof Error ? error.message : String(error) }
+          };
+        }
+      }
       if (!pendingIntent) {
         const timestamp = checkpointTimestamp();
         pendingIntent = {

package/lib/task/control-authority.ts

@@ -39,15 +39,21 @@ import {
   type TaskLifecycleRequest,
   type TaskLifecycleResult
 } from './lifecycle.ts';
+import {
+  recoverStartedLifecycleUnderLock,
+  recoveryFailure,
+  type LifecycleRecoveryResult
+} from './lifecycle-recovery.ts';
+import type { LifecycleRecoveryRequest } from './lifecycle-recovery.ts';
 import { locateActivityLog } from './activity-log.ts';
 import { resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { verifyTaskEvent } from './verification.ts';
 import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.ts';
 import {
-  findArtifactRepairIntentsByOperation,
-  writeArtifactRepairIntent,
-  type ArtifactRepairIntent
+  findArtifactRecoveryIntentsByOperation,
+  writeArtifactRecoveryIntent,
+  type ArtifactRecoveryIntent
 } from './artifact-repair-intent.ts';
 import {
   computeLifecycleBuildIdentity,
@@ -333,7 +339,7 @@ export function queryLifecycleRecoveryOperation(
   const store = options.capabilityStore ?? createCodexCapabilityStore();
   const registry = authorityOperationMap.get(store);
   const known = [...(registry?.values() ?? [])].filter((value) => value.operationId === operationId);
-  const intents = options.repoRoot ? findArtifactRepairIntentsByOperation(options.repoRoot, operationId) : [];
+  const intents = options.repoRoot ? findArtifactRecoveryIntentsByOperation(options.repoRoot, operationId) : [];
   const capabilities = store.findByRecoveryOperation(operationId);
   const phaseMap = new Map<string, LifecycleRecoveryOperationQueryV1['phases'][number]>();
   for (const capability of capabilities) {
@@ -416,13 +422,13 @@ function lifecycleRecoveryEventCommitted(
 }
 
 function lifecycleRecoveryIntentMatches(
-  intent: ArtifactRepairIntent,
+  intent: ArtifactRecoveryIntent,
   selector: LifecycleAuthorityRequestV1
 ): boolean {
   return intent.taskId === selector.taskId
     && intent.family === selector.family
     && intent.artifact === selector.artifact
-    && (intent.state === 'commit-started' || intent.state === 'consumed');
+    && (intent.state === 'commit-started' || intent.state === 'consumption-started' || intent.state === 'consumed');
 }
 
 /**
@@ -473,19 +479,19 @@ export function recoverLifecycleRecoveryOperation(
   if (!phase) {
     throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_PHASE_MISSING', 'durable task completion phase is missing');
   }
-  const intents = findArtifactRepairIntentsByOperation(options.repoRoot, selector.operationId)
+  const intents = findArtifactRecoveryIntentsByOperation(options.repoRoot, selector.operationId)
     .filter((intent) => intent.taskId === selector.taskId
       && intent.family === selector.family
       && intent.artifact === selector.artifact);
   if (intents.length !== 1) {
-    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact repair intent does not identify this task event');
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact recovery intent does not identify this task event');
   }
   const intent = intents[0]!;
   if (!lifecycleRecoveryIntentMatches(intent, selector)
     || intent.phase !== selector.phase
     || intent.requestId !== selector.lifecycleRequestId
     || intent.authorityDigest === null) {
-    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact repair intent does not match the recovery request');
+    throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_INTENT_INVALID', 'durable artifact recovery intent does not match the recovery request');
   }
   if (!lifecycleRecoveryEventCommitted(selector, options.repoRoot)) {
     throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_COMMIT_UNCONFIRMED', 'task completion is not durably present; compensation is not allowed');
@@ -499,7 +505,7 @@ export function recoverLifecycleRecoveryOperation(
     throw lifecycleRecoveryCompensationError('LIFECYCLE_RECOVERY_STATE_INVALID', 'consumed capability has an unconsumed completion phase');
   }
   if (intent.state !== 'consumed') {
-    writeArtifactRepairIntent(options.repoRoot, {
+    writeArtifactRecoveryIntent(options.repoRoot, {
       ...intent,
       state: 'consumed',
       updatedAt: (options.now ?? Date.now)()
@@ -565,7 +571,7 @@ export type TaskControlOperation =
       options?: Omit<OrchestrationOptions, 'repoRoot'>;
     }>;
 
-export type TaskControlDispatchResult = TaskLifecycleResult | TaskFinalizationResult | OrchestrationResult;
+export type TaskControlDispatchResult = TaskLifecycleResult | LifecycleRecoveryResult | TaskFinalizationResult | OrchestrationResult;
 
 export function taskControlOperationKey(operation: TaskControlOperation): string {
   if (operation.family === 'task-finalization') return 'complete';
@@ -712,12 +718,15 @@ function lifecycleTaskId(request: TaskLifecycleControlRequest, repoRoot: string)
 async function applyLifecycleWithAuthority(
   context: TaskControlExecutionContext,
   request: TaskLifecycleControlRequest
-): Promise<TaskLifecycleResult & { humanOverride?: unknown }> {
+): Promise<(TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown }> {
   const conflict = overrideDryRunConflict(request as unknown as Record<string, unknown>);
   if (conflict) {
     return taskLifecycleFailure(request, { code: 'LIFECYCLE_PAYLOAD_INVALID', message: conflict.message });
   }
-  const execute = async (): Promise<TaskLifecycleResult & { humanOverride?: unknown }> => {
+  const execute = async (): Promise<(TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown }> => {
+    if (request.intent === 'recover-started') {
+      return recoverStartedLifecycleUnderLock(request as LifecycleRecoveryRequest, { repoRoot: context.repoRoot });
+    }
     const lifecycleResult = applyTaskLifecycle(request, { repoRoot: context.repoRoot });
     if (lifecycleResult.status !== 'failed' || !request.overrideTicket) return lifecycleResult;
     if (!request.overrideTarget || !request.overrideScope) {
@@ -751,6 +760,9 @@ async function applyLifecycleWithAuthority(
     );
   } catch (error) {
     if (!(error instanceof TaskExecutionLockError)) throw error;
+    if (request.intent === 'recover-started') {
+      return recoveryFailure(request as LifecycleRecoveryRequest, 'owner-unknown', error.code, error.message);
+    }
     return taskLifecycleFailure(request, { code: error.code, message: error.message }, taskId);
   }
 }
@@ -829,7 +841,7 @@ function orchestrationFailure(error: unknown): OrchestrationResult {
 export function dispatchTaskControlOperation(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-lifecycle' }>
-): Promise<TaskLifecycleResult & { humanOverride?: unknown }>;
+): Promise<(TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown }>;
 export function dispatchTaskControlOperation(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-finalization' }>
@@ -892,7 +904,7 @@ function operationInvalid(message: string): never {
 
 const LIFECYCLE_FLAGS = new Set([
   '--agent', '--reason', '--unblock-condition', '--note', '--alert-number', '--staging-dir', '--issue-number',
-  '--override-ticket', '--override-target', '--override-scope', '--dry-run'
+  '--stage', '--round', '--artifact', '--override-ticket', '--override-target', '--override-scope', '--dry-run'
 ]);
 
 const FINALIZATION_FLAGS = new Set(['--agent']);
@@ -972,8 +984,29 @@ export function parseTaskControlOperation(
       ...(value(values, '--override-scope') ? { overrideScope: value(values, '--override-scope') } : {}),
       ...(value(values, '--alert-number') ? { alertNumber: Number(value(values, '--alert-number')) } : {}),
       ...(value(values, '--issue-number') ? { issueNumber: Number(value(values, '--issue-number')) } : {}),
+      ...(value(values, '--stage') ? { stage: value(values, '--stage') } : {}),
+      ...(value(values, '--round') ? { round: Number(value(values, '--round')) } : {}),
+      ...(value(values, '--artifact') ? { artifact: value(values, '--artifact') } : {}),
       ...(values['--dry-run'] === true ? { dryRun: true } : {})
     };
+    if (intent === 'recover-started') {
+      const recoveryFlags = new Set(['--agent', '--stage', '--round', '--artifact', '--reason']);
+      for (const flag of Object.keys(values)) {
+        if (!recoveryFlags.has(flag)) operationInvalid(`option '${flag}' is not supported for recover-started`);
+      }
+      required(values, ['--stage', '--round', '--artifact', '--reason']);
+      const stage = value(values, '--stage');
+      if (!['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(stage ?? '')) {
+        operationInvalid('--stage must be a supported lifecycle stage');
+      }
+      const round = Number(value(values, '--round'));
+      if (!Number.isSafeInteger(round) || round < 1) operationInvalid('--round must be a positive integer');
+      if (value(values, '--reason')!.includes('\n') || value(values, '--reason')!.includes('\r')) {
+        operationInvalid('--reason must be a single line');
+      }
+    } else if (values['--stage'] !== undefined || values['--round'] !== undefined || values['--artifact'] !== undefined) {
+      operationInvalid('--stage, --round, and --artifact are only supported for recover-started');
+    }
     return { family, request: input as unknown as TaskLifecycleControlRequest };
   }
 

package/lib/task/control-recovery.ts

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { isCompletionEvidence } from './orchestration.ts';
 import { TASK_WORKFLOW_OPERATIONS } from './workflow-command.ts';
+import { sameRecoveryWarning } from './recovery-warning.ts';
 
 export type ControlRecoveryOutcome = 'not-executed' | 'in-progress' | 'success' | 'failure' | 'unknown' | 'rejected';
 
@@ -53,7 +54,7 @@ export type ControlRecoveryDecision = Readonly<{
   reasonCode: string;
 }>;
 
-const LIFECYCLE_INTENTS = ['block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore'] as const;
+const LIFECYCLE_INTENTS = ['block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore', 'recover-started'] as const;
 const ORCHESTRATION_INTENTS = [
   'begin-or-resume', 'route.read', 'route.clean-completion', 'status', 'prepare', 'dispatch',
   'await-activation', 'recover-prepared', 'hook-start', 'hook-stop', 'advance', 'pause'
@@ -107,6 +108,15 @@ function domainEvidenceMatches(
       && snapshot.worktreeTree === completion.worktreeTree
       && lastReviewedCommit === completion.lastReviewedCommit;
   }
+  if (operation.family === 'task-lifecycle' && operation.intent === 'recover-started') {
+    const retryRequired = domain.recoveryState === 'retry-required'
+      && sameRecoveryWarning(domain.warning, result.warning);
+    return result.targetState === 'active'
+      && ['applied', 'no-op'].includes(String(result.status))
+      && domain.recovery === true
+      && domain.targetState === 'active'
+      && (domain.recoveryState === 'released' || retryRequired);
+  }
   if (operation.class === 'read-only') return result.changed === false && domain.snapshotValid === true;
   return true;
 }
@@ -159,6 +169,8 @@ export function classifySandboxControlRecovery(input: ControlRecoveryInput): Con
     responseReconstructable: true,
     reasonCode: input.operation.class === 'route.clean-completion' && result.changed === false
       ? 'RECOVERY_ROUTE_COMPLETION_NOOP'
+      : input.operation.intent === 'recover-started' && input.domain?.recoveryState === 'retry-required'
+        ? 'RECOVERY_RELEASE_RETRY_REQUIRED'
       : 'RECOVERY_TERMINAL_AND_DOMAIN_MATCH'
   };
 }

package/lib/task/create-service.ts

@@ -1,6 +1,3 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
 import { syncPlatformComment } from '../platform/issue-comments.ts';
 import { createPlatformIssue, syncPlatformIssue } from '../platform/issues.ts';
 import type { PlatformResult } from '../platform/types.ts';
@@ -190,12 +187,6 @@ function platformOperations(prefix: string, operations: readonly { name: string;
   }));
 }
 
-function issueFromTask(repoRoot: string, taskId: string): { number: number; url: string } | null {
-  const content = fs.readFileSync(path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md'), 'utf8');
-  const match = /^issue_number:\s*(\d+)\s*$/m.exec(content);
-  return match ? { number: Number(match[1]), url: '' } : null;
-}
-
 async function createTask(value: unknown, options: CreateTaskOptions): Promise<TaskCreateResult> {
   const dependencies = { ...DEFAULT_DEPENDENCIES, ...options.dependencies };
   let candidate: TaskCreateCandidateV1;
@@ -215,7 +206,7 @@ async function createTask(value: unknown, options: CreateTaskOptions): Promise<T
   const operations: TaskCreateOperation[] = [{
     name: 'task:local', status: local.status, reasonCode: null
   }];
-  let issue = issueFromTask(options.repoRoot, local.task.id);
+  let issue: TaskCreateResult['issue'] = null;
   const created = await dependencies.createIssue(local.task.id, { cwd: options.repoRoot, agent: candidate.agent });
   operations.push(...platformOperations('platform-create', created.operations));
   if (created.issue) issue = { number: created.issue.number, url: created.issue.url };