@fitlab-ai/agent-infra 0.10.0 → 0.11.0

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

@@ -10,15 +10,19 @@ export type ArtifactRecoveryPhase =
   | 'artifact.finalize-local'
   | 'task-event.completed';
 export type ArtifactRecoveryState =
-  | 'awaiting-recovery'
-  | 'finalize-ready'
+  | 'awaiting-preflight-recovery'
+  | 'preflight-ready'
+  | 'preflight-commit-started'
+  | 'preflight-passed'
+  | 'full-finalizer-ready'
   | 'commit-started'
   | 'passed'
+  | 'consumption-started'
   | 'consumed'
   | 'aborted';
 
 export type ArtifactRecoveryIntent = Readonly<{
-  version: 3;
+  version: 4;
   taskId: string;
   family: ArtifactSchemaFamily;
   artifact: string;
@@ -28,6 +32,12 @@ export type ArtifactRecoveryIntent = Readonly<{
   baselineSemanticDigest: string;
   stagingId: string;
   candidateSha256: string | null;
+  preflightArtifactSha256: string | null;
+  preflightSemanticDigest: string | null;
+  activeGenerationSha256: string | null;
+  activeGenerationSemanticDigest: string | null;
+  pendingGenerationSha256: string | null;
+  pendingGenerationSemanticDigest: string | null;
   finalArtifactSha256: string | null;
   finalSemanticDigest: string | null;
   recoveryOperationId: string;
@@ -82,22 +92,28 @@ export function isArtifactRecoveryIntent(value: unknown): value is ArtifactRecov
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const intent = value as Record<string, unknown>;
   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 as number) > 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)
@@ -109,11 +125,22 @@ export function isArtifactRecoveryIntent(value: unknown): value is ArtifactRecov
     && (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/lib/task/control-authority.ts

@@ -428,7 +428,7 @@ function lifecycleRecoveryIntentMatches(
   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');
 }
 
 /**

package/lib/task/events.ts

@@ -402,7 +402,7 @@ function reconcileReviewCompletionReplay(
       }
       intent = reconciled.intent;
     }
-    if (!['passed', 'consumed'].includes(intent.state)) {
+    if (!['passed', 'consumption-started', 'consumed'].includes(intent.state)) {
       return {
         code: 'EVENT_ARTIFACT_CONFLICT',
         message: `review finalizer provenance is incomplete for ${artifact}`
@@ -423,7 +423,7 @@ function reconcileReviewCompletionReplay(
         message: `review finalizer provenance does not match ${artifact}`
       };
     }
-    if (intent.state === 'passed') {
+    if (intent.state === 'passed' || intent.state === 'consumption-started') {
       const consumed = { ...intent, state: 'consumed' as const, updatedAt: Date.now() };
       writeArtifactRecoveryIntent(repoRoot, consumed, { expected: intent });
     }
@@ -963,7 +963,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
         );
         if (reconciled.status === 'passed' || reconciled.status === 'consumed') reviewFinalizationIntent = reconciled.intent;
       }
-      if (!reviewFinalizationIntent || !['passed', 'consumed'].includes(reviewFinalizationIntent.state)) {
+      if (!reviewFinalizationIntent || !['passed', 'consumption-started', 'consumed'].includes(reviewFinalizationIntent.state)) {
         return failed(normalized, {
           code: 'EVENT_ARTIFACT_CONFLICT',
           message: `review finalizer provenance is missing or incomplete for ${completedArtifact.name}`
@@ -1116,7 +1116,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
         const expectedIntent = localFinalizationIntent;
         localFinalizationIntent = {
           ...localFinalizationIntent,
-          state: 'commit-started',
+          state: 'consumption-started',
           phase: 'task-event.completed',
           authorityDigest: lifecycleRecoveryAttestationDigest(lifecycleAuthority),
           requestId: lifecycleAuthority.lifecycleRequestId,
@@ -1146,7 +1146,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
       const expectedIntent = reviewFinalizationIntent;
       reviewFinalizationIntent = {
         ...reviewFinalizationIntent,
-        state: 'commit-started',
+        state: 'consumption-started',
         phase: 'task-event.completed',
         updatedAt: Date.now()
       };
@@ -1183,7 +1183,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   }
   if (!normalized.dryRun && reviewFinalizationIntent && completedArtifact) {
     try {
-      if (reviewFinalizationIntent.state === 'commit-started') {
+      if (reviewFinalizationIntent.state === 'consumption-started') {
         const consumed = { ...reviewFinalizationIntent, state: 'consumed' as const, updatedAt: Date.now() };
         writeArtifactRecoveryIntent(resolved.repoRoot, consumed, { expected: reviewFinalizationIntent });
       }

package/lib/task/intermediate-cleanup.ts

@@ -327,10 +327,26 @@ function cleanupConsumedRecoveryFiles(repoRoot: string, task: TaskRecord | undef
   let entries: fs.Dirent[];
   try { entries = fs.readdirSync(recovery, { withFileTypes: true }); } catch { return false; }
   for (const entry of entries) {
-    if (entry.isSymbolicLink() || !entry.isFile() || !['baseline.md', 'candidate.md', 'final.md', 'publish.md'].includes(entry.name)) return false;
+    if (entry.isSymbolicLink()) return false;
+    if (entry.isFile()) {
+      if (!['baseline.md', 'candidate.md', 'final.md', 'publish.md'].includes(entry.name)) return false;
+      continue;
+    }
+    if (!entry.isDirectory() || entry.name !== 'generations') return false;
+    let generations: fs.Dirent[];
+    try { generations = fs.readdirSync(path.join(recovery, entry.name), { withFileTypes: true }); } catch { return false; }
+    if (generations.some((generation) => generation.isSymbolicLink()
+      || !generation.isFile() || !/^[a-f0-9]{64}\.md$/u.test(generation.name))) return false;
   }
   try {
-    for (const entry of entries) fs.unlinkSync(path.join(recovery, entry.name));
+    for (const entry of entries) {
+      const target = path.join(recovery, entry.name);
+      if (entry.isFile()) fs.unlinkSync(target);
+      else {
+        for (const generation of fs.readdirSync(target, { withFileTypes: true })) fs.unlinkSync(path.join(target, generation.name));
+        fs.rmdirSync(target);
+      }
+    }
     fs.rmdirSync(recovery);
     const recoveryRoot = path.dirname(recovery);
     if (fs.readdirSync(recoveryRoot).length === 0) fs.rmdirSync(recoveryRoot);

package/lib/task/local-artifact-finalization.ts

@@ -19,8 +19,10 @@ import {
   beginArtifactRecovery,
   commitArtifactRecovery,
   consumeArtifactRecovery,
+  prepareArtifactRecoveryFinal,
   prepareArtifactRecoveryCommit,
   recordArtifactRecoveryPassed,
+  reconcileArtifactRecovery,
   recoveryContextFromIntent,
   stageArtifactCandidate
 } from './artifact-recovery.ts';
@@ -265,7 +267,8 @@ function tupleFor(
 function prepareLocalArtifact(
   request: LocalArtifactFinalizationRequest,
   candidate?: string,
-  authority?: LifecycleRecoveryAttestationV1
+  authority?: LifecycleRecoveryAttestationV1,
+  preflightOnly = false
 ): LocalArtifactPreparation {
   const failed = (code: string, message: string, extra: Partial<LocalArtifactFinalizationResult> = {}): LocalArtifactPreparation => ({
     result: failedFinalization(request, { code, message }, extra), content: candidate ?? ''
@@ -281,12 +284,14 @@ function prepareLocalArtifact(
   let taskContent: string;
   let content: string;
   let recovery: ArtifactRecoveryContext | undefined;
+  let recoveryState: ArtifactRecoveryIntent['state'] | undefined;
   try {
     taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
     if (request.recoveryId) {
       const intent = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
       if (!intent || intent.recoveryOperationId !== request.recoveryId) return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'recovery id does not match the artifact journal');
-      if (!['awaiting-recovery', 'finalize-ready', 'commit-started'].includes(intent.state)) return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `recovery journal is in '${intent.state}' state`);
+      if (!['awaiting-preflight-recovery', 'preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready', 'commit-started'].includes(intent.state)) return failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `recovery journal is in '${intent.state}' state`);
+      recoveryState = intent.state;
       recovery = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, intent);
       content = fs.existsSync(recovery.stagingPath)
         ? fs.readFileSync(recovery.stagingPath, 'utf8')
@@ -315,26 +320,66 @@ function prepareLocalArtifact(
 
   if (request.recoveryId) {
     if (!validation.ok) return { result, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+    if (preflightOnly && recovery && recoveryState === 'awaiting-preflight-recovery') {
+      const staged = stageArtifactCandidate(recovery, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+      prepareArtifactRecoveryCommit(recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+    }
     return {
-      result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(recovery!) },
+      result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(recovery!) },
       content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld
     };
   }
 
   const existing = readArtifactRecoveryIntent(resolved.repoRoot, resolved.taskId, request.family, request.artifact);
   if (existing?.state === 'passed' || existing?.state === 'consumed') {
-    if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+    if (existing.state === 'consumed' && (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest)) {
       return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match its completed recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
     }
+    if (existing.finalArtifactSha256 === artifactSha256 && existing.finalSemanticDigest === validation.semanticDigest) {
+      const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+      return {
+        result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+        content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+      };
+    }
+  }
+
+  if (existing && ['preflight-ready', 'preflight-commit-started', 'preflight-passed', 'full-finalizer-ready'].includes(existing.state)) {
     const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
     return {
-      result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) },
+      result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
+      content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
+    };
+  }
+  if (existing?.state === 'commit-started') {
+    if (existing.finalArtifactSha256 !== artifactSha256 || existing.finalSemanticDigest !== validation.semanticDigest) {
+      return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', 'formal artifact does not match the interrupted recovery journal'), content, repoRoot: resolved.repoRoot, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+    }
+    const context = recoveryContextFromIntent(resolved.repoRoot, resolved.taskDir, existing);
+    const reconciled = reconcileArtifactRecovery(context, {
+      lockAlreadyHeld: request.lockAlreadyHeld,
+      validateFinal: () => validation.semanticDigest === existing.finalSemanticDigest
+    });
+    if (reconciled.status !== 'passed') {
+      return { ...failed('LOCAL_RECOVERY_PROVENANCE_CONFLICT', `interrupted recovery could not be reconciled: ${reconciled.status}`), content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+    }
+    return {
+      result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) },
       content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld
     };
   }
 
   try {
     if (validation.ok) {
+      if (preflightOnly) {
+        const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
+          repoRoot: resolved.repoRoot, taskDir: resolved.taskDir,
+          ...(authority ? { recoveryId: authority.operationId } : {}), lockAlreadyHeld: request.lockAlreadyHeld
+        });
+        const staged = stageArtifactCandidate(context, Buffer.from(content, 'utf8'), { lockAlreadyHeld: request.lockAlreadyHeld });
+        prepareArtifactRecoveryCommit(context, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: request.lockAlreadyHeld });
+        return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery: context, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+      }
       const context = recordArtifactRecoveryPassed(tupleFor(request, resolved.taskId, authority), {
         repoRoot: resolved.repoRoot,
         taskDir: resolved.taskDir,
@@ -344,7 +389,7 @@ function prepareLocalArtifact(
         lockAlreadyHeld: request.lockAlreadyHeld
       });
       recovery = context;
-      return { result: { ...result, status: 'passed', error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
+      return { result: { ...result, status: 'passed', changed: false, error: null, recovery: recoveryInfo(context) }, content, repoRoot: resolved.repoRoot, recovery, authority, lockAlreadyHeld: request.lockAlreadyHeld };
     }
     const context = beginArtifactRecovery(tupleFor(request, resolved.taskId, authority), Buffer.from(content, 'utf8'), {
       repoRoot: resolved.repoRoot,
@@ -362,7 +407,10 @@ function prepareLocalArtifact(
   }
 }
 
-function commitLocalArtifactProvenance(prepared: LocalArtifactPreparation): LocalArtifactFinalizationResult {
+function commitLocalArtifactProvenance(
+  prepared: LocalArtifactPreparation,
+  options: Readonly<{ afterPublish?: () => void }> = {}
+): LocalArtifactFinalizationResult {
   if (!prepared.recovery || !prepared.repoRoot || prepared.result.status === 'failed' && !prepared.result.recovery) return prepared.result;
   if (prepared.result.status === 'failed') return prepared.result;
   try {
@@ -372,26 +420,42 @@ function commitLocalArtifactProvenance(prepared: LocalArtifactPreparation): Loca
     if (intent.state === 'passed' || intent.state === 'consumed') {
       return {
         ...prepared.result,
+        changed: false,
         artifactSha256: intent.finalArtifactSha256,
         semanticDigest: intent.finalSemanticDigest,
         error: null
       };
-    } else if (intent.state === 'finalize-ready' || intent.state === 'commit-started') {
-      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
-    } else {
+    } else if (intent.state === 'commit-started') {
+      const reconciled = reconcileArtifactRecovery(prepared.recovery, {
+        lockAlreadyHeld: prepared.lockAlreadyHeld,
+        afterPublish: options.afterPublish
+      });
+      committed = reconciled.intent;
+    } else if (intent.state === 'awaiting-preflight-recovery') {
       const staged = stageArtifactCandidate(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
       prepareArtifactRecoveryCommit(prepared.recovery, staged.candidateSha256, staged.semanticDigest, { lockAlreadyHeld: prepared.lockAlreadyHeld });
       committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
     }
-    if (committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed.state}'`);
+    if (intent.state === 'preflight-ready' || intent.state === 'preflight-commit-started') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld });
+    }
+    if (committed?.state === 'preflight-passed' || intent.state === 'preflight-passed') {
+      prepareArtifactRecoveryFinal(prepared.recovery, Buffer.from(prepared.content, 'utf8'), { lockAlreadyHeld: prepared.lockAlreadyHeld });
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+    } else if (intent.state === 'full-finalizer-ready') {
+      committed = commitArtifactRecovery(prepared.recovery, { lockAlreadyHeld: prepared.lockAlreadyHeld, afterPublish: options.afterPublish });
+    }
+    if (!committed || committed.state !== 'passed') throw new Error(`ARTIFACT_RECOVERY_STATE_INVALID: commit ended in '${committed?.state ?? intent.state}'`);
     return {
       ...prepared.result,
       status: 'passed',
+      changed: false,
       artifactSha256: committed.finalArtifactSha256,
       semanticDigest: committed.finalSemanticDigest,
       error: null
     };
   } catch (error) {
+    if (error instanceof Error && error.message.startsWith('TASK_WORKFLOW_FAULT_INJECTED:')) throw error;
     return { ...prepared.result, status: 'failed', error: {
       code: 'LOCAL_RECOVERY_COMMIT_FAILED', message: String(error)
     } };
@@ -417,10 +481,20 @@ function finalizeLocalArtifact(
   return result;
 }
 
+/** Validate and seal an immutable preflight generation without publishing the formal artifact. */
+function preflightLocalArtifact(
+  request: LocalArtifactFinalizationRequest,
+  authority?: LifecycleRecoveryAttestationV1
+): LocalArtifactFinalizationResult {
+  const prepared = prepareLocalArtifact(request, undefined, authority, true);
+  return prepared.result;
+}
+
 export {
   LOCAL_ARTIFACT_REQUIRED_SECTIONS,
   consumeLocalArtifactFinalizationIntent,
   finalizeLocalArtifact,
+  preflightLocalArtifact,
   prepareLocalArtifact,
   commitLocalArtifactProvenance,
   readArtifactRecoveryIntent as readLocalArtifactFinalizationIntent,

package/lib/task/review-command.ts

@@ -3,7 +3,7 @@ import type { ReviewFinalizationRequest } from './review-finalization.ts';
 export function parseReviewCommand(args: readonly string[]): ReviewFinalizationRequest & {
   overrideTicket?: string; overrideTarget?: string; overrideScope?: string;
 } {
-  if (!args[0] || args[1] !== 'finalize-summary') throw new Error('task ref and finalize-summary are required');
+  if (!args[0] || !['preflight', 'finalize-summary'].includes(args[1] ?? '')) throw new Error('task ref and a supported review operation are required');
   const values: Record<string, string | boolean> = {};
   const flags = {
     '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',