@fitlab-ai/agent-infra 0.10.0 → 0.11.1

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) {

package/dist/lib/task/artifact-repair-intent.js

@@ -37,22 +37,28 @@ export function isArtifactRecoveryIntent(value) {
         return false;
     const intent = value;
     return exactKeys(intent, [
-        'artifact', 'authorityDigest', 'baselineSemanticDigest', 'baselineSha256', 'candidateSha256',
+        'activeGenerationSemanticDigest', 'activeGenerationSha256', 'artifact', 'authorityDigest', 'baselineSemanticDigest', 'baselineSha256', 'candidateSha256',
         'createdAt', 'errorCode', 'errorMessage', 'family', 'finalArtifactSha256', 'finalSemanticDigest',
-        'phase', 'recoveryOperationId', 'requestId', 'round', 'stagingId', 'state', 'taskId', 'updatedAt',
+        'pendingGenerationSemanticDigest', 'pendingGenerationSha256', 'phase', 'preflightArtifactSha256', 'preflightSemanticDigest', 'recoveryOperationId', 'requestId', 'round', 'stagingId', 'state', 'taskId', 'updatedAt',
         'version'
     ])
-        && intent.version === 3
+        && intent.version === 4
         && validTaskId(intent.taskId)
         && typeof intent.family === 'string'
         && ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(intent.family)
         && Number.isSafeInteger(intent.round) && intent.round > 0
         && validArtifact(intent.artifact, intent.family, intent.round)
-        && ['awaiting-recovery', 'finalize-ready', 'commit-started', 'passed', 'consumed', 'aborted'].includes(String(intent.state))
+        && ['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)
@@ -64,11 +70,22 @@ export function isArtifactRecoveryIntent(value) {
         && (intent.errorMessage === null || validToken(intent.errorMessage))
         && Number.isSafeInteger(intent.createdAt)
         && Number.isSafeInteger(intent.updatedAt)
-        && (intent.state === 'awaiting-recovery'
-            ? intent.finalArtifactSha256 === null && intent.finalSemanticDigest === null
+        && (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 === 'finalize-ready' || intent.state === 'commit-started' || intent.state === 'passed' || intent.state === 'consumed'
-            ? validDigest(intent.candidateSha256) && validDigest(intent.finalArtifactSha256) && validDigest(intent.finalSemanticDigest)
+        && (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);
 }

package/dist/lib/task/capabilities.js

@@ -146,8 +146,6 @@ function qualificationRecoveryAction(facts) {
     return QUALIFICATION_RECOVERY_ORDER.find(({ pattern }) => stale.some((name) => pattern.test(name)))?.action ?? null;
 }
 function recommendNext(facts) {
-    if (invalidationBlocks(facts.invalidation))
-        return { action: null, reasonCode: 'INVALIDATION_INCOMPLETE', evidence: ['reconcile task invalidation before routing'] };
     if (facts.qualificationStale) {
         const action = qualificationRecoveryAction(facts);
         return {

package/dist/lib/task/control-authority.js

@@ -266,7 +266,7 @@ function lifecycleRecoveryIntentMatches(intent, selector) {
     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');
 }
 /**
  * Completes only the durable tail of a committed task event after a process