@fitlab-ai/agent-infra 0.10.0 → 0.11.0

package/lib/sandbox/control/workflow-executor.ts

@@ -2,10 +2,11 @@ import { TASK_WORKFLOW_COMMANDS } from '../../task/workflow-command.ts';
 
 import { parseArtifactCommand, executeArtifactCommand } from '../../task/artifact-command.ts';
 import { parseReviewCommand } from '../../task/review-command.ts';
-import { prepareLocalArtifact, commitLocalArtifactProvenance } from '../../task/local-artifact-finalization.ts';
+import { prepareLocalArtifact, preflightLocalArtifact, commitLocalArtifactProvenance } from '../../task/local-artifact-finalization.ts';
 import { prepareReviewSummaryCandidate, commitReviewSummaryProvenance } from '../../task/review-finalization.ts';
+import { readArtifactRecoveryIntent } from '../../task/artifact-repair-intent.ts';
 import { withTaskExecutionLock } from '../../task/task-execution-lock.ts';
-import { dispatchHostControlCommand } from '../../host-control/command.ts';
+import { dispatchWorkflowCommand } from '../../task/workflow-dispatch.ts';
 import { assertSandboxTaskSource } from '../workspace-view.ts';
 import { appendDiagnosticAudit } from './audit.ts';
 import {
@@ -17,6 +18,17 @@ import type { LifecycleRecoveryAttestationV1 } from '../../task/control-authorit
 import { applyTaskEvent } from '../../task/events.ts';
 import { parseTaskEventRequest } from '../../internal/task-event.ts';
 
+export type TaskWorkflowFaultWindow =
+  | 'before-call'
+  | 'before-domain-write'
+  | 'after-atomic-rename'
+  | 'before-result-return';
+
+export type TaskWorkflowExecutionOptions = Readonly<{
+  /** Deterministic test seam; production callers leave this unset. */
+  faultWindow?: TaskWorkflowFaultWindow;
+}>;
+
 function executionResult(result: Record<string, unknown>): SandboxControlExecutionResult {
   return { exitCode: result.status === 'failed' || result.status === 'refused' ? 1 : 0, stdout: `${JSON.stringify(result)}\n`, stderr: '' };
 }
@@ -25,10 +37,41 @@ function executionResult(result: Record<string, unknown>): SandboxControlExecuti
 export async function executeTaskWorkflow(
   manifest: SandboxControlManifest,
   request: TaskWorkflowRequest,
-  lifecycleRecoveryAttestation: LifecycleRecoveryAttestationV1 | null = null
+  lifecycleRecoveryAttestation: LifecycleRecoveryAttestationV1 | null = null,
+  options: TaskWorkflowExecutionOptions = {}
 ): Promise<SandboxControlExecutionResult> {
-  let publicationStarted = false;
+  let publicationCommitted = false;
+  let recoveryObservation: Readonly<{
+    family: 'analysis' | 'plan' | 'code' | 'review-analysis' | 'review-plan' | 'review-code';
+    artifact: string;
+    wasPassed: boolean;
+  }> | null = null;
+  const observeRecoveryPublication = (): void => {
+    if (!recoveryObservation || recoveryObservation.wasPassed) return;
+    const intent = readArtifactRecoveryIntent(
+      manifest.repoRoot,
+      request.taskId,
+      recoveryObservation.family,
+      recoveryObservation.artifact
+    );
+    publicationCommitted ||= intent?.state === 'preflight-ready'
+      || intent?.state === 'preflight-commit-started'
+      || intent?.state === 'preflight-passed'
+      || intent?.state === 'passed'
+      || intent?.state === 'commit-started';
+  };
+  let faultTriggered = false;
+  const fault = (window: TaskWorkflowFaultWindow): void => {
+    if (faultTriggered || options.faultWindow !== window) return;
+    faultTriggered = true;
+    throw new Error(`TASK_WORKFLOW_FAULT_INJECTED:${window}`);
+  };
+  const response = (result: Record<string, unknown>): SandboxControlExecutionResult => {
+    fault('before-result-return');
+    return executionResult(result);
+  };
   try {
+    fault('before-call');
     const taskDir = assertSandboxTaskSource(manifest.repoRoot, request.taskId);
     const [command] = TASK_WORKFLOW_COMMANDS[request.operation];
     if (request.operation === 'event') {
@@ -36,57 +79,95 @@ export async function executeTaskWorkflow(
       const boundEventRequest = lifecycleRecoveryAttestation && eventRequest.requestId === undefined
         ? { ...eventRequest, requestId: lifecycleRecoveryAttestation.lifecycleRequestId }
         : eventRequest;
+      fault('before-domain-write');
       const result = applyTaskEvent(boundEventRequest, {
         repoRoot: manifest.repoRoot,
         lifecycleRecoveryAttestation,
         deferLifecycleRecoveryConsumption: true
       });
-      return executionResult(result);
+      publicationCommitted = result.changed;
+      fault('after-atomic-rename');
+      return response(result);
     }
     if (command !== 'task-artifact' && command !== 'task-review') {
-      publicationStarted = true;
-      // Inherit this executor's process group so its existing recovery owns the worker too.
-      const result = await dispatchHostControlCommand({
-        operation: command, payload: { workingDirectory: manifest.repoRoot, args: request.args }
-      });
-      return result;
+      // The broker owns this short-lived executor; no global service or worker
+      // credential participates in the command's authority or recovery path.
+      fault('before-domain-write');
+      const result = dispatchWorkflowCommand(manifest.repoRoot, request.operation, request.args);
+      publicationCommitted = result.changed === true;
+      fault('after-atomic-rename');
+      return response(result);
     }
     const input = command === 'task-artifact' ? parseArtifactCommand(request.args) : parseReviewCommand(request.args);
     if (command === 'task-artifact' && 'operation' in input && input.operation === 'inspect') {
-      return executionResult(executeArtifactCommand(input, { repoRoot: manifest.repoRoot }));
+      fault('before-domain-write');
+      const result = executeArtifactCommand(input, { repoRoot: manifest.repoRoot });
+      publicationCommitted = result.changed === true;
+      fault('after-atomic-rename');
+      return response(result);
     }
     if ('operation' in input && input.operation === 'init') {
-      return executionResult(executeArtifactCommand(input, { repoRoot: manifest.repoRoot, artifactDir: taskDir }));
+      fault('before-domain-write');
+      const result = executeArtifactCommand(input, { repoRoot: manifest.repoRoot, artifactDir: taskDir });
+      publicationCommitted = result.changed === true;
+      fault('after-atomic-rename');
+      return response(result);
     }
     return await withTaskExecutionLock(manifest.repoRoot, request.taskId, `sandbox-control.${request.operation}`, async () => {
       const artifact = await readTaskArtifact(taskDir, { artifact: input.artifact });
       const content = artifact.bytes.toString('utf8');
+      fault('before-domain-write');
       let result: Record<string, unknown>;
       if ('operation' in input) {
         const { family } = input;
         if (family !== 'analysis' && family !== 'plan' && family !== 'code') throw new Error('ARTIFACT_IDENTITY_INVALID');
         const local = { taskRef: request.taskId, family, artifact: input.artifact, repoRoot: manifest.repoRoot, recoveryId: input.recoveryId, lockAlreadyHeld: true } as const;
+        if (input.operation === 'preflight') {
+          // Preflight only seals a verified generation. It must not publish the
+          // formal artifact, set publicationStarted, or append finalizer audit.
+          const result = preflightLocalArtifact(local);
+          recoveryObservation = { family, artifact: input.artifact, wasPassed: false };
+          observeRecoveryPublication();
+          return response(result);
+        }
+        recoveryObservation = {
+          family,
+          artifact: input.artifact,
+          wasPassed: readArtifactRecoveryIntent(manifest.repoRoot, request.taskId, family, input.artifact)?.state === 'passed'
+        };
         const prepared = prepareLocalArtifact(local, content, lifecycleRecoveryAttestation ?? undefined);
-        if (prepared.result.status === 'failed') return executionResult(commitLocalArtifactProvenance(prepared));
-        publicationStarted = true;
-        result = commitLocalArtifactProvenance(prepared);
+        observeRecoveryPublication();
+        const commitOptions = { afterPublish: () => fault('after-atomic-rename') };
+        if (prepared.result.status === 'failed') return executionResult(commitLocalArtifactProvenance(prepared, commitOptions));
+        result = commitLocalArtifactProvenance(prepared, commitOptions);
       } else {
         if (input.overrideTicket) throw new Error('TASK_WORKFLOW_OVERRIDE_UNSUPPORTED');
+        const family = `review-${input.stage}` as 'review-analysis' | 'review-plan' | 'review-code';
+        recoveryObservation = {
+          family,
+          artifact: input.artifact,
+          wasPassed: readArtifactRecoveryIntent(manifest.repoRoot, request.taskId, family, input.artifact)?.state === 'passed'
+        };
         const prepared = prepareReviewSummaryCandidate(input, content, { repoRoot: manifest.repoRoot, lockAlreadyHeld: true, startRecovery: true });
+        observeRecoveryPublication();
         if (input.dryRun || prepared.result.status === 'planned') return executionResult(prepared.result);
-        if (prepared.result.status === 'failed') return executionResult(commitReviewSummaryProvenance(prepared, manifest.repoRoot));
-        publicationStarted = true;
-        result = commitReviewSummaryProvenance(prepared, manifest.repoRoot);
+        const commitOptions = { afterPublish: () => fault('after-atomic-rename') };
+        if (prepared.result.status === 'failed') return executionResult(commitReviewSummaryProvenance(prepared, manifest.repoRoot, commitOptions));
+        result = commitReviewSummaryProvenance(prepared, manifest.repoRoot, commitOptions);
       }
+      observeRecoveryPublication();
+      publicationCommitted ||= result.changed === true;
       if (result.status !== 'failed') appendDiagnosticAudit(manifest, 'task-workflow-artifact-finalized', {
         requestId: request.id, sandboxTaskId: request.taskId, workflowOperation: request.operation,
         artifact: input.artifact, sha256: result.artifactSha256 as string, semanticDigest: result.semanticDigest as string
       });
-      return executionResult({ ...result, changed: true });
+      fault('after-atomic-rename');
+      return response(result);
     });
   } catch (error) {
+    observeRecoveryPublication();
     const message = error instanceof Error ? error.message : String(error);
     const code = (error as { code?: string })?.code ?? /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'TASK_WORKFLOW_REQUEST_INVALID';
-    return executionResult({ status: 'failed', changed: publicationStarted ? null : false, error: { code, message } });
+    return executionResult({ status: 'failed', changed: publicationCommitted ? null : false, error: { code, message } });
   }
 }

package/lib/server/process-state.ts

@@ -12,6 +12,11 @@ export type ProcessIdentity = Readonly<{
 export type ProcessIdentityState = 'alive' | 'dead' | 'unknown';
 export type ProcessIdentityProbe = (identity: ProcessIdentity) => ProcessIdentityState;
 
+type ProcessIdentityRuntime = Readonly<{
+  probePid?: (pid: number) => void;
+  execFileSync?: typeof execFileSync;
+}>;
+
 export type PidRecord = ProcessIdentity & {
   version: 2;
 };
@@ -132,7 +137,8 @@ export function getProcessStartTime(
 
 export function getProcessIdentityState(
   identity: ProcessIdentity,
-  platform: NodeJS.Platform = process.platform
+  platform: NodeJS.Platform = process.platform,
+  runtime: ProcessIdentityRuntime = {}
 ): ProcessIdentityState {
   if (!Number.isInteger(identity.pid) || identity.pid <= 0 || !Number.isSafeInteger(identity.startTime)) {
     return 'dead';
@@ -147,8 +153,9 @@ export function getProcessIdentityState(
       return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'dead' : 'unknown';
     }
   }
+  const probePid = runtime.probePid ?? ((pid: number) => process.kill(pid, 0));
   try {
-    process.kill(identity.pid, 0);
+    probePid(identity.pid);
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code;
     if (code === 'ESRCH') return 'dead';
@@ -157,20 +164,34 @@ export function getProcessIdentityState(
   const query = buildProcessStartTimeQuery(identity.pid, platform);
   if (query === null) return 'unknown';
   try {
-    const output = execFileSync(query.command, query.args, {
+    const output = (runtime.execFileSync ?? execFileSync)(query.command, query.args, {
       encoding: 'utf8',
       env: platform === 'darwin' ? { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } : process.env
     }).trim();
-    if (output.length === 0) return 'unknown';
+    if (output.length === 0) return recheckDarwinProcessExit(identity.pid, platform, probePid);
     const startTime = platform === 'win32'
       ? new Date(output).getTime()
       : platform === 'darwin'
         ? parseDarwinStartTime(output)
         : null;
-    if (startTime === null || Number.isNaN(startTime)) return 'unknown';
+    if (startTime === null || Number.isNaN(startTime)) return recheckDarwinProcessExit(identity.pid, platform, probePid);
     return startTime === identity.startTime ? 'alive' : 'dead';
   } catch {
+    return recheckDarwinProcessExit(identity.pid, platform, probePid);
+  }
+}
+
+function recheckDarwinProcessExit(
+  pid: number,
+  platform: NodeJS.Platform,
+  probePid: (pid: number) => void
+): ProcessIdentityState {
+  if (platform !== 'darwin') return 'unknown';
+  try {
+    probePid(pid);
     return 'unknown';
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ESRCH' ? 'dead' : 'unknown';
   }
 }
 

package/lib/task/artifact-command.ts

@@ -4,12 +4,12 @@ import { resolveArtifactContext, hasOpenArtifactRound } from './artifact-lifecyc
 import { parseArtifactName } from './artifact-name.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
-import { finalizeLocalArtifact } from './local-artifact-finalization.ts';
+import { finalizeLocalArtifact, preflightLocalArtifact } from './local-artifact-finalization.ts';
 import { initializeArtifactSkeleton } from './artifact-operations.ts';
 
 export type ArtifactCommand = Readonly<{
   taskRef: string;
-  operation: 'inspect' | 'init' | 'finalize-local';
+  operation: 'inspect' | 'init' | 'preflight' | 'finalize-local';
   family: string;
   artifact: string;
   locale?: 'zh-CN' | 'en';
@@ -19,13 +19,14 @@ export type ArtifactCommand = Readonly<{
 /** One option contract for the CLI and trusted projection executor. */
 export function parseArtifactCommand(args: readonly string[]): ArtifactCommand {
   const [taskRef, operation] = args;
-  if (!taskRef || !['inspect', 'init', 'finalize-local'].includes(operation ?? '')) {
+  if (!taskRef || !['inspect', 'init', 'preflight', 'finalize-local'].includes(operation ?? '')) {
     throw new Error('task ref and a supported artifact operation are required');
   }
   const fields: Record<string, string> = {};
   const allowed = {
     inspect: ['--family'],
     init: ['--family', '--artifact', '--locale'],
+    'preflight': ['--family', '--artifact', '--recovery-id'],
     'finalize-local': ['--family', '--artifact', '--recovery-id']
   }[operation as ArtifactCommand['operation']];
   for (let index = 2; index < args.length; index += 1) {
@@ -79,7 +80,8 @@ export function executeArtifactCommand(
     return { ...initializeArtifactSkeleton({ ...input, ...(locale ? { locale } : {}) }), ...identity };
   }
   if (family !== 'analysis' && family !== 'plan' && family !== 'code') {
-    return fail('ARTIFACT_PAYLOAD_INVALID', "finalize-local only supports 'analysis', 'plan', and 'code'");
+    return fail('ARTIFACT_PAYLOAD_INVALID', "preflight and finalize-local only support 'analysis', 'plan', and 'code'");
   }
+  if (operation === 'preflight') return { ...preflightLocalArtifact({ taskRef, family, artifact, repoRoot: resolved.repoRoot, recoveryId }) };
   return { ...finalizeLocalArtifact({ taskRef, family, artifact, repoRoot: resolved.repoRoot, recoveryId }) };
 }

package/lib/task/artifact-operations.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import { readStableFileSync } from '../host-control/secure-fs.ts';
+import { readStableFileSync } from './secure-fs.ts';
 import { parseArtifactName } from './artifact-name.ts';
 
 import { scanVisibleMarkdown, type VisibleMarkdown, type VisibleHeading } from './markdown.ts';

package/lib/task/artifact-recovery.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import { writeDurableFile } from '../fs/durable-write.ts';
-import { readStableFileSync } from '../host-control/secure-fs.ts';
+import { readStableFileSync } from './secure-fs.ts';
 import { parseArtifactName } from './artifact-name.ts';
 import { canonicalSemanticDigest, sha256Content } from './artifact-operations.ts';
 import {
@@ -39,7 +39,7 @@ export type ArtifactRecoveryContext = Readonly<ArtifactRecoveryTuple & {
   formalPath: string;
   stagingPath: string;
   baselinePath: string;
-  finalPath: string;
+  generationsPath: string;
   baselineSha256: string;
   baselineSemanticDigest: string;
 }>;
@@ -191,7 +191,7 @@ function contextPaths(
     formalPath: path.join(taskDir, tuple.artifact),
     stagingPath: path.join(root, 'candidate.md'),
     baselinePath: path.join(root, 'baseline.md'),
-    finalPath: path.join(root, 'final.md'),
+    generationsPath: path.join(root, 'generations'),
     baselineSha256: '',
     baselineSemanticDigest: ''
   };
@@ -221,16 +221,22 @@ function contextWithIntent(context: ArtifactRecoveryContext, intent: ArtifactRec
 
 function createIntent(context: ArtifactRecoveryContext, now: number): ArtifactRecoveryIntent {
   return {
-    version: 3,
+    version: 4,
     taskId: context.taskId,
     family: context.family,
     artifact: context.artifact,
     round: context.round,
-    state: 'awaiting-recovery',
+    state: 'awaiting-preflight-recovery',
     baselineSha256: context.baselineSha256,
     baselineSemanticDigest: context.baselineSemanticDigest,
     stagingId: context.stagingId,
     candidateSha256: context.baselineSha256,
+    preflightArtifactSha256: null,
+    preflightSemanticDigest: null,
+    activeGenerationSha256: null,
+    activeGenerationSemanticDigest: null,
+    pendingGenerationSha256: null,
+    pendingGenerationSemanticDigest: null,
     finalArtifactSha256: null,
     finalSemanticDigest: null,
     recoveryOperationId: context.recoveryId,
@@ -267,7 +273,7 @@ export function beginArtifactRecovery(
       fail('ARTIFACT_RECOVERY_BASELINE_MISMATCH', 'formal artifact does not match the recovery baseline');
     }
     const existing = readArtifactRecoveryIntent(prepared.repoRoot, prepared.taskId, prepared.family, prepared.artifact);
-    if (existing && existing.state !== 'aborted' && existing.state !== 'consumed') {
+    if (existing && !['aborted', 'consumed', 'passed'].includes(existing.state)) {
       fail('ARTIFACT_RECOVERY_CONFLICT', 'an active recovery journal already exists for this artifact');
     }
     writeBytes(prepared.baselinePath, baselineBytes);
@@ -287,6 +293,7 @@ export function recordArtifactRecoveryPassed(
   assertRecoveryId(context.recoveryId);
   assertRegular(context.formalPath, 'formal artifact');
   return runLocked(context, 'task-artifact.recovery.record-passed', () => {
+    assertRecoveryRoot(context);
     const current = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
     const prepared = {
       ...context,
@@ -306,18 +313,18 @@ export function recordArtifactRecoveryPassed(
       && existing.finalSemanticDigest === prepared.baselineSemanticDigest) {
       return recoveryContextFromIntent(prepared.repoRoot, prepared.taskDir, existing);
     }
-    if (existing && existing.state !== 'aborted') {
+    if (existing && existing.state !== 'aborted' && existing.state !== 'passed') {
       fail('ARTIFACT_RECOVERY_CONFLICT', 'an active recovery journal already exists for this artifact');
     }
-    const now = Date.now();
-    const next: ArtifactRecoveryIntent = {
-      ...createIntent(prepared, now),
-      state: 'passed',
-      candidateSha256: prepared.baselineSha256,
-      finalArtifactSha256: prepared.baselineSha256,
-      finalSemanticDigest: prepared.baselineSemanticDigest
-    };
-    writeArtifactRecoveryIntent(prepared.repoRoot, next, { expected: existing });
+    const base = createIntent(prepared, Date.now());
+    writeBytes(prepared.baselinePath, current.bytes);
+    writeBytes(prepared.stagingPath, current.bytes);
+    writeArtifactRecoveryIntent(prepared.repoRoot, base, { expected: existing });
+    const staged = stageArtifactCandidate(prepared, current.bytes, { lockAlreadyHeld: true });
+    prepareArtifactRecoveryCommit(prepared, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: true });
+    commitArtifactRecovery(prepared, { lockAlreadyHeld: true });
+    prepareArtifactRecoveryFinal(prepared, current.bytes, { lockAlreadyHeld: true });
+    commitArtifactRecovery(prepared, { lockAlreadyHeld: true });
     return prepared;
   }, options.lockAlreadyHeld);
 }
@@ -330,7 +337,7 @@ export function stageArtifactCandidate(
   return runLocked(context, 'task-artifact.recovery.stage', () => {
     assertRecoveryRoot(context);
     const intent = readIntentForContext(context);
-    if (intent.state !== 'awaiting-recovery') fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot stage a candidate from '${intent.state}'`);
+    if (intent.state !== 'awaiting-preflight-recovery') fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot stage a candidate from '${intent.state}'`);
     const candidateSha256 = sha256Content(candidateBytes.toString('utf8'));
     const semanticDigest = canonicalSemanticDigest(candidateBytes.toString('utf8'));
     writeBytes(context.stagingPath, candidateBytes);
@@ -340,6 +347,49 @@ export function stageArtifactCandidate(
   }, options.lockAlreadyHeld);
 }
 
+function generationPath(context: ArtifactRecoveryContext, sha256: string): string {
+  assertDigest(sha256, 'generation digest');
+  return path.join(context.generationsPath, `${sha256}.md`);
+}
+
+/** Persist and verify an immutable digest-addressed snapshot before it is journaled. */
+function writeGeneration(context: ArtifactRecoveryContext, bytes: Buffer, sha256: string, semanticDigest: string): void {
+  ensureOwnedDirectoryTree(context.repoRoot, context.generationsPath);
+  const target = generationPath(context, sha256);
+  if (fs.existsSync(target)) {
+    const existing = readStableFileSync(target, { maxBytes: MAX_ARTIFACT_BYTES, expectedSha256: sha256 });
+    if (canonicalSemanticDigest(existing.bytes.toString('utf8')) !== semanticDigest) {
+      fail('ARTIFACT_RECOVERY_CONFLICT', 'existing generation does not match its semantic digest');
+    }
+    return;
+  }
+  writeBytes(target, bytes);
+  fs.chmodSync(target, 0o400);
+  const sealed = readStableFileSync(target, { maxBytes: MAX_ARTIFACT_BYTES, expectedSha256: sha256 });
+  if (canonicalSemanticDigest(sealed.bytes.toString('utf8')) !== semanticDigest) {
+    fail('ARTIFACT_RECOVERY_CANDIDATE_MISMATCH', 'generation does not match its validated semantic digest');
+  }
+}
+
+function publishGeneration(context: ArtifactRecoveryContext, sha256: string, semanticDigest: string, baselineSha256: string): void {
+  const target = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
+  const generation = readStableFileSync(generationPath(context, sha256), { maxBytes: MAX_ARTIFACT_BYTES, expectedSha256: sha256 });
+  if (canonicalSemanticDigest(generation.bytes.toString('utf8')) !== semanticDigest) {
+    fail('ARTIFACT_RECOVERY_CONFLICT', 'generation semantic digest does not match the journal');
+  }
+  if (target.sha256 === sha256) return;
+  if (target.sha256 !== baselineSha256) fail('ARTIFACT_RECOVERY_CONFLICT', 'formal artifact changed outside the expected generation');
+  const publishPath = path.join(path.dirname(context.stagingPath), 'publish.md');
+  unlinkIfPresent(publishPath);
+  writeBytes(publishPath, generation.bytes);
+  fs.chmodSync(publishPath, 0o400);
+  fs.renameSync(publishPath, context.formalPath);
+  const published = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES, expectedSha256: sha256 });
+  if (canonicalSemanticDigest(published.bytes.toString('utf8')) !== semanticDigest) {
+    fail('ARTIFACT_RECOVERY_CONFLICT', 'published artifact does not match its generation');
+  }
+}
+
 export function prepareArtifactRecoveryCommit(
   context: ArtifactRecoveryContext,
   finalSha256: string,
@@ -350,24 +400,21 @@ export function prepareArtifactRecoveryCommit(
   assertDigest(finalSemanticDigest, 'final semantic digest');
   return runLocked(context, 'task-artifact.recovery.prepare', () => {
     const intent = readIntentForContext(context);
-    if (intent.state !== 'awaiting-recovery') fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot prepare a commit from '${intent.state}'`);
+    if (intent.state !== 'awaiting-preflight-recovery') fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot prepare a preflight from '${intent.state}'`);
     assertRecoveryRoot(context);
     const staged = readStableFileSync(context.stagingPath, { maxBytes: MAX_ARTIFACT_BYTES });
     if (staged.sha256 !== finalSha256 || canonicalSemanticDigest(staged.bytes.toString('utf8')) !== finalSemanticDigest) {
       fail('ARTIFACT_RECOVERY_CANDIDATE_MISMATCH', 'staged candidate does not match the finalizer digest');
     }
-    writeBytes(context.finalPath, staged.bytes);
-    fs.chmodSync(context.finalPath, 0o400);
-    const sealed = readStableFileSync(context.finalPath, { maxBytes: MAX_ARTIFACT_BYTES });
-    if (sealed.sha256 !== finalSha256 || canonicalSemanticDigest(sealed.bytes.toString('utf8')) !== finalSemanticDigest) {
-      fail('ARTIFACT_RECOVERY_CANDIDATE_MISMATCH', 'sealed candidate does not match the finalizer digest');
-    }
+    writeGeneration(context, staged.bytes, finalSha256, finalSemanticDigest);
     const next: ArtifactRecoveryIntent = {
       ...intent,
-      state: 'finalize-ready',
+      state: 'preflight-ready',
       candidateSha256: staged.sha256,
-      finalArtifactSha256: finalSha256,
-      finalSemanticDigest,
+      preflightArtifactSha256: finalSha256,
+      preflightSemanticDigest: finalSemanticDigest,
+      activeGenerationSha256: finalSha256,
+      activeGenerationSemanticDigest: finalSemanticDigest,
       errorCode: null,
       errorMessage: null,
       updatedAt: Date.now()
@@ -378,59 +425,61 @@ export function prepareArtifactRecoveryCommit(
 }
 
 function markCommitStarted(context: ArtifactRecoveryContext, intent: ArtifactRecoveryIntent): ArtifactRecoveryIntent {
-  if (intent.state === 'commit-started') return intent;
-  if (intent.state !== 'finalize-ready') fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot commit from '${intent.state}'`);
-  const next: ArtifactRecoveryIntent = { ...intent, state: 'commit-started', updatedAt: Date.now() };
+  if (intent.state === 'preflight-commit-started' || intent.state === 'commit-started') return intent;
+  if (intent.state !== 'preflight-ready' && intent.state !== 'full-finalizer-ready') fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot commit from '${intent.state}'`);
+  const next: ArtifactRecoveryIntent = { ...intent, state: intent.state === 'preflight-ready' ? 'preflight-commit-started' : 'commit-started', updatedAt: Date.now() };
   writeArtifactRecoveryIntent(context.repoRoot, next, { expected: intent });
   return next;
 }
 
 export function commitArtifactRecovery(
   context: ArtifactRecoveryContext,
-  options: Readonly<{ lockAlreadyHeld?: boolean }> = {}
+  options: Readonly<{ lockAlreadyHeld?: boolean; afterPublish?: () => void }> = {}
 ): ArtifactRecoveryIntent {
   return runLocked(context, 'task-artifact.recovery.commit', () => {
     let intent = readIntentForContext(context);
     if (intent.state === 'passed' || intent.state === 'consumed') return intent;
     assertRecoveryRoot(context);
     intent = markCommitStarted(context, intent);
-    const target = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
-    if (target.sha256 === intent.finalArtifactSha256) {
-      const passed: ArtifactRecoveryIntent = { ...intent, state: 'passed', updatedAt: Date.now() };
+    if (intent.state === 'preflight-commit-started') {
+      publishGeneration(context, intent.activeGenerationSha256!, intent.activeGenerationSemanticDigest!, intent.baselineSha256);
+      const passed = { ...intent, state: 'preflight-passed' as const, updatedAt: Date.now() };
       writeArtifactRecoveryIntent(context.repoRoot, passed, { expected: intent });
       return passed;
     }
-    if (target.sha256 !== intent.baselineSha256) fail('ARTIFACT_RECOVERY_CONFLICT', 'formal artifact changed outside the recovery baseline');
-    const sealed = readStableFileSync(context.finalPath, {
-      maxBytes: MAX_ARTIFACT_BYTES,
-      expectedSha256: intent.finalArtifactSha256!
-    });
-    if (canonicalSemanticDigest(sealed.bytes.toString('utf8')) !== intent.finalSemanticDigest) {
-      fail('ARTIFACT_RECOVERY_CONFLICT', 'sealed artifact does not match the staged final semantic digest');
-    }
-    // Publish the bytes that were validated above. The sealed path is only a
-    // recovery input; renaming it directly would reopen a same-uid path swap
-    // between validation and publication.
-    const publishPath = path.join(path.dirname(context.finalPath), 'publish.md');
-    unlinkIfPresent(publishPath);
-    writeBytes(publishPath, sealed.bytes);
-    fs.chmodSync(publishPath, 0o400);
-    const publish = readStableFileSync(publishPath, {
-      maxBytes: MAX_ARTIFACT_BYTES,
-      expectedSha256: intent.finalArtifactSha256!
-    });
-    if (canonicalSemanticDigest(publish.bytes.toString('utf8')) !== intent.finalSemanticDigest) {
-      fail('ARTIFACT_RECOVERY_CONFLICT', 'publish artifact does not match the staged final semantic digest');
-    }
-    fs.renameSync(publishPath, context.formalPath);
-    const published = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
-    if (published.sha256 !== intent.finalArtifactSha256) fail('ARTIFACT_RECOVERY_CONFLICT', 'formal artifact does not match the staged final digest');
-    const passed: ArtifactRecoveryIntent = { ...intent, state: 'passed', updatedAt: Date.now() };
+    publishGeneration(context, intent.pendingGenerationSha256!, intent.pendingGenerationSemanticDigest!, intent.activeGenerationSha256!);
+    options.afterPublish?.();
+    const passed: ArtifactRecoveryIntent = {
+      ...intent, state: 'passed', activeGenerationSha256: intent.pendingGenerationSha256,
+      activeGenerationSemanticDigest: intent.pendingGenerationSemanticDigest,
+      pendingGenerationSha256: null, pendingGenerationSemanticDigest: null, updatedAt: Date.now()
+    };
     writeArtifactRecoveryIntent(context.repoRoot, passed, { expected: intent });
     return passed;
   }, options.lockAlreadyHeld);
 }
 
+export function prepareArtifactRecoveryFinal(
+  context: ArtifactRecoveryContext,
+  finalBytes: Buffer,
+  options: Readonly<{ lockAlreadyHeld?: boolean }> = {}
+): ArtifactRecoveryIntent {
+  return runLocked(context, 'task-artifact.recovery.finalize', () => {
+    const intent = readIntentForContext(context);
+    if (intent.state !== 'preflight-passed') fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot finalize from '${intent.state}'`);
+    const finalSha256 = sha256Content(finalBytes.toString('utf8'));
+    const finalSemanticDigest = canonicalSemanticDigest(finalBytes.toString('utf8'));
+    if (finalSha256 !== intent.activeGenerationSha256) writeGeneration(context, finalBytes, finalSha256, finalSemanticDigest);
+    const next: ArtifactRecoveryIntent = {
+      ...intent, state: 'full-finalizer-ready', pendingGenerationSha256: finalSha256,
+      pendingGenerationSemanticDigest: finalSemanticDigest, finalArtifactSha256: finalSha256,
+      finalSemanticDigest, updatedAt: Date.now()
+    };
+    writeArtifactRecoveryIntent(context.repoRoot, next, { expected: intent });
+    return next;
+  }, options.lockAlreadyHeld);
+}
+
 export function abortArtifactRecovery(
   context: ArtifactRecoveryContext,
   code: string,
@@ -462,19 +511,23 @@ export function reconcileArtifactRecovery(
     lockAlreadyHeld?: boolean;
     validateFinal?: () => boolean;
     restoreBaseline?: boolean;
+    afterPublish?: () => void;
   }> = {}
 ): ArtifactRecoveryReconcileResult {
   return runLocked(context, 'task-artifact.recovery.reconcile', () => {
     const intent = readIntentForContext(context);
-    if (intent.state !== 'commit-started') return { status: intent.state, intent };
+    if (intent.state !== 'preflight-commit-started' && intent.state !== 'commit-started') return { status: intent.state, intent };
     const target = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
-    if (target.sha256 === intent.finalArtifactSha256 && (options.validateFinal?.() ?? true)) {
-      const passed: ArtifactRecoveryIntent = { ...intent, state: 'passed', updatedAt: Date.now() };
-      writeArtifactRecoveryIntent(context.repoRoot, passed, { expected: intent });
-      return { status: 'passed', intent: passed };
+    const expected = intent.state === 'preflight-commit-started' ? intent.activeGenerationSha256! : intent.pendingGenerationSha256!;
+    if (target.sha256 === expected && (options.validateFinal?.() ?? true)) {
+      const next = intent.state === 'preflight-commit-started'
+        ? { ...intent, state: 'preflight-passed' as const, updatedAt: Date.now() }
+        : { ...intent, state: 'passed' as const, activeGenerationSha256: intent.pendingGenerationSha256, activeGenerationSemanticDigest: intent.pendingGenerationSemanticDigest, pendingGenerationSha256: null, pendingGenerationSemanticDigest: null, updatedAt: Date.now() };
+      writeArtifactRecoveryIntent(context.repoRoot, next, { expected: intent });
+      return { status: next.state, intent: next };
     }
-    if (target.sha256 === intent.baselineSha256) {
-      const retried = commitArtifactRecovery(context, { lockAlreadyHeld: true });
+    if (target.sha256 === (intent.state === 'preflight-commit-started' ? intent.baselineSha256 : intent.activeGenerationSha256)) {
+      const retried = commitArtifactRecovery(context, { lockAlreadyHeld: true, afterPublish: options.afterPublish });
       return { status: retried.state, intent: retried };
     }
     if (options.restoreBaseline) {