@fitlab-ai/agent-infra 0.10.0 → 0.11.0

package/dist/lib/sandbox/control/executor.js

@@ -125,7 +125,9 @@ export async function prepareSandboxControlExecution(params) {
                 owner: gateOwner,
                 requestId: params.request.id,
                 operationId: authority?.operationId ?? params.request.id,
-                phase: authority?.phase ?? (params.request.family === 'task-workflow' ? 'artifact.finalize-local' : 'orchestration.prepare'),
+                phase: authority?.phase ?? (params.request.family === 'task-workflow'
+                    && params.request.workflow?.operation === 'artifact-preflight' ? 'artifact.preflight'
+                    : params.request.family === 'task-workflow' ? 'artifact.finalize-local' : 'orchestration.prepare'),
                 authority
             });
         },
@@ -163,7 +165,7 @@ function waitForGate(nonce, timeoutMs = 2_000) {
                 return;
             }
             if (typeof value.requestId !== 'string' || typeof value.operationId !== 'string'
-                || !['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(value.phase)
+                || !['orchestration.prepare', 'artifact.preflight', 'artifact.finalize-local', 'task-event.completed'].includes(value.phase)
                 || (value.authority !== null && value.authority !== undefined && (() => {
                     try {
                         validateLifecycleRecoveryAttestation(value.authority);

package/dist/lib/sandbox/control/task-workflow.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { readStableFile, SecureFileError, writeAtomicFile } from '../../host-control/secure-fs.js';
+import { readStableFile, SecureFileError, writeAtomicFile } from '../../task/secure-fs.js';
 import { TASK_WORKFLOW_COMMANDS, TASK_WORKFLOW_OPERATIONS } from '../../task/workflow-command.js';
 export function validateTaskWorkflowRequest(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))

package/dist/lib/sandbox/control/workflow-executor.js

@@ -1,10 +1,11 @@
 import { TASK_WORKFLOW_COMMANDS } from '../../task/workflow-command.js';
 import { parseArtifactCommand, executeArtifactCommand } from '../../task/artifact-command.js';
 import { parseReviewCommand } from '../../task/review-command.js';
-import { prepareLocalArtifact, commitLocalArtifactProvenance } from '../../task/local-artifact-finalization.js';
+import { prepareLocalArtifact, preflightLocalArtifact, commitLocalArtifactProvenance } from '../../task/local-artifact-finalization.js';
 import { prepareReviewSummaryCandidate, commitReviewSummaryProvenance } from '../../task/review-finalization.js';
+import { readArtifactRecoveryIntent } from '../../task/artifact-repair-intent.js';
 import { withTaskExecutionLock } from '../../task/task-execution-lock.js';
-import { dispatchHostControlCommand } from '../../host-control/command.js';
+import { dispatchWorkflowCommand } from '../../task/workflow-dispatch.js';
 import { assertSandboxTaskSource } from '../workspace-view.js';
 import { appendDiagnosticAudit } from './audit.js';
 import { readTaskArtifact } from './task-workflow.js';
@@ -14,9 +15,32 @@ function executionResult(result) {
     return { exitCode: result.status === 'failed' || result.status === 'refused' ? 1 : 0, stdout: `${JSON.stringify(result)}\n`, stderr: '' };
 }
 /** The broker already authorized this host executor; domain operations own validation. */
-export async function executeTaskWorkflow(manifest, request, lifecycleRecoveryAttestation = null) {
-    let publicationStarted = false;
+export async function executeTaskWorkflow(manifest, request, lifecycleRecoveryAttestation = null, options = {}) {
+    let publicationCommitted = false;
+    let recoveryObservation = null;
+    const observeRecoveryPublication = () => {
+        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) => {
+        if (faultTriggered || options.faultWindow !== window)
+            return;
+        faultTriggered = true;
+        throw new Error(`TASK_WORKFLOW_FAULT_INJECTED:${window}`);
+    };
+    const response = (result) => {
+        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') {
@@ -24,66 +48,104 @@ export async function executeTaskWorkflow(manifest, request, lifecycleRecoveryAt
             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;
             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 };
+                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);
+                observeRecoveryPublication();
+                const commitOptions = { afterPublish: () => fault('after-atomic-rename') };
                 if (prepared.result.status === 'failed')
-                    return executionResult(commitLocalArtifactProvenance(prepared));
-                publicationStarted = true;
-                result = commitLocalArtifactProvenance(prepared);
+                    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}`;
+                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);
+                const commitOptions = { afterPublish: () => fault('after-atomic-rename') };
                 if (prepared.result.status === 'failed')
-                    return executionResult(commitReviewSummaryProvenance(prepared, manifest.repoRoot));
-                publicationStarted = true;
-                result = commitReviewSummaryProvenance(prepared, manifest.repoRoot);
+                    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, semanticDigest: result.semanticDigest
                 });
-            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?.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 } });
     }
 }
 //# sourceMappingURL=workflow-executor.js.map

package/dist/lib/server/process-state.js

@@ -97,7 +97,7 @@ export function getProcessStartTime(pid, platform = process.platform) {
         return null;
     }
 }
-export function getProcessIdentityState(identity, platform = process.platform) {
+export function getProcessIdentityState(identity, platform = process.platform, runtime = {}) {
     if (!Number.isInteger(identity.pid) || identity.pid <= 0 || !Number.isSafeInteger(identity.startTime)) {
         return 'dead';
     }
@@ -114,8 +114,9 @@ export function getProcessIdentityState(identity, platform = process.platform) {
             return error.code === 'ENOENT' ? 'dead' : 'unknown';
         }
     }
+    const probePid = runtime.probePid ?? ((pid) => process.kill(pid, 0));
     try {
-        process.kill(identity.pid, 0);
+        probePid(identity.pid);
     }
     catch (error) {
         const code = error.code;
@@ -128,23 +129,34 @@ export function getProcessIdentityState(identity, platform = process.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';
+            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';
+            return recheckDarwinProcessExit(identity.pid, platform, probePid);
         return startTime === identity.startTime ? 'alive' : 'dead';
     }
     catch {
+        return recheckDarwinProcessExit(identity.pid, platform, probePid);
+    }
+}
+function recheckDarwinProcessExit(pid, platform, probePid) {
+    if (platform !== 'darwin')
         return 'unknown';
+    try {
+        probePid(pid);
+        return 'unknown';
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'dead' : 'unknown';
     }
 }
 function parsePidRecord(raw) {

package/dist/lib/task/artifact-command.js

@@ -3,18 +3,19 @@ import { resolveArtifactContext, hasOpenArtifactRound } from './artifact-lifecyc
 import { parseArtifactName } from './artifact-name.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { getArtifactSchema } from './artifact-schema.js';
-import { finalizeLocalArtifact } from './local-artifact-finalization.js';
+import { finalizeLocalArtifact, preflightLocalArtifact } from './local-artifact-finalization.js';
 import { initializeArtifactSkeleton } from './artifact-operations.js';
 /** One option contract for the CLI and trusted projection executor. */
 export function parseArtifactCommand(args) {
     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 = {};
     const allowed = {
         inspect: ['--family'],
         init: ['--family', '--artifact', '--locale'],
+        'preflight': ['--family', '--artifact', '--recovery-id'],
         'finalize-local': ['--family', '--artifact', '--recovery-id']
     }[operation];
     for (let index = 2; index < args.length; index += 1) {
@@ -72,8 +73,10 @@ export function executeArtifactCommand(command, options = {}) {
         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 }) };
 }
 //# sourceMappingURL=artifact-command.js.map

package/dist/lib/task/artifact-operations.js

@@ -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.js';
+import { readStableFileSync } from './secure-fs.js';
 import { parseArtifactName } from './artifact-name.js';
 import { scanVisibleMarkdown } from './markdown.js';
 import { getArtifactSchema, renderArtifactSkeleton } from './artifact-schema.js';

package/dist/lib/task/artifact-recovery.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { writeDurableFile } from '../fs/durable-write.js';
-import { readStableFileSync } from '../host-control/secure-fs.js';
+import { readStableFileSync } from './secure-fs.js';
 import { parseArtifactName } from './artifact-name.js';
 import { canonicalSemanticDigest, sha256Content } from './artifact-operations.js';
 import { artifactRecoveryRoot, readArtifactRecoveryIntent, writeArtifactRecoveryIntent } from './artifact-repair-intent.js';
@@ -139,7 +139,7 @@ function contextPaths(tuple, options, recoveryId) {
         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: ''
     };
@@ -167,16 +167,22 @@ function contextWithIntent(context, intent) {
 }
 function createIntent(context, now) {
     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,
@@ -209,7 +215,7 @@ export function beginArtifactRecovery(tuple, baselineBytes, options) {
             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);
@@ -225,6 +231,7 @@ export function recordArtifactRecoveryPassed(tuple, options) {
     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,
@@ -244,18 +251,18 @@ export function recordArtifactRecoveryPassed(tuple, options) {
             && 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 = {
-            ...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);
 }
@@ -263,7 +270,7 @@ export function stageArtifactCandidate(context, candidateBytes, options = {}) {
     return runLocked(context, 'task-artifact.recovery.stage', () => {
         assertRecoveryRoot(context);
         const intent = readIntentForContext(context);
-        if (intent.state !== 'awaiting-recovery')
+        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'));
@@ -273,30 +280,69 @@ export function stageArtifactCandidate(context, candidateBytes, options = {}) {
         return { recoveryId: context.recoveryId, candidateSha256, semanticDigest, path: context.stagingPath };
     }, options.lockAlreadyHeld);
 }
+function generationPath(context, sha256) {
+    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, bytes, sha256, semanticDigest) {
+    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, sha256, semanticDigest, baselineSha256) {
+    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, finalSha256, finalSemanticDigest, options = {}) {
     assertDigest(finalSha256, 'final artifact digest');
     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 = {
             ...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()
@@ -306,11 +352,11 @@ export function prepareArtifactRecoveryCommit(context, finalSha256, finalSemanti
     }, options.lockAlreadyHeld);
 }
 function markCommitStarted(context, intent) {
-    if (intent.state === 'commit-started')
+    if (intent.state === 'preflight-commit-started' || intent.state === 'commit-started')
         return intent;
-    if (intent.state !== 'finalize-ready')
+    if (intent.state !== 'preflight-ready' && intent.state !== 'full-finalizer-ready')
         fail('ARTIFACT_RECOVERY_STATE_INVALID', `cannot commit from '${intent.state}'`);
-    const next = { ...intent, state: 'commit-started', updatedAt: Date.now() };
+    const next = { ...intent, state: intent.state === 'preflight-ready' ? 'preflight-commit-started' : 'commit-started', updatedAt: Date.now() };
     writeArtifactRecoveryIntent(context.repoRoot, next, { expected: intent });
     return next;
 }
@@ -321,44 +367,41 @@ export function commitArtifactRecovery(context, options = {}) {
             return intent;
         assertRecoveryRoot(context);
         intent = markCommitStarted(context, intent);
-        const target = readStableFileSync(context.formalPath, { maxBytes: MAX_ARTIFACT_BYTES });
-        if (target.sha256 === intent.finalArtifactSha256) {
-            const passed = { ...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', 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 = { ...intent, state: 'passed', updatedAt: Date.now() };
+        publishGeneration(context, intent.pendingGenerationSha256, intent.pendingGenerationSemanticDigest, intent.activeGenerationSha256);
+        options.afterPublish?.();
+        const passed = {
+            ...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, finalBytes, options = {}) {
+    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 = {
+            ...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, code, message, options = {}) {
     return runLocked(context, 'task-artifact.recovery.abort', () => {
         const intent = readIntentForContext(context);
@@ -383,16 +426,19 @@ export function abortArtifactRecovery(context, code, message, options = {}) {
 export function reconcileArtifactRecovery(context, options = {}) {
     return runLocked(context, 'task-artifact.recovery.reconcile', () => {
         const intent = readIntentForContext(context);
-        if (intent.state !== 'commit-started')
+        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 = { ...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', updatedAt: Date.now() }
+                : { ...intent, state: 'passed', 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) {