@fitlab-ai/agent-infra 0.11.4 → 0.11.5

package/lib/task/finalization.ts

@@ -10,6 +10,7 @@ import { taskIssueIdentity } from '../platform/task-identities.ts';
 import { parseTaskFrontmatter } from './frontmatter.ts';
 import {
   applyTaskLifecycle,
+  inspectTaskLifecycleProgress,
   type TaskLifecycleOptions,
   type TaskLifecycleRequest,
   type TaskLifecycleResult
@@ -25,6 +26,9 @@ import {
   type OperationWarning,
   type OperationWarningSeverity
 } from './operation-outcome.ts';
+import { readTaskFinalizationHandoff } from './finalization-handoff.ts';
+import { readSandboxControlManifest } from '../sandbox/control/lifecycle.ts';
+import { validateSandboxControlIdentity } from '../sandbox/control/identity-sentinel.ts';
 
 const RECEIPT_VERSION = 4 as const;
 const FINALIZATION_STEPS = ['lifecycle', 'task-comment', 'verification', 'summary'] as const;
@@ -55,11 +59,14 @@ type TaskFinalizationRequest = Readonly<{
   taskRef: string;
   intent: 'complete';
   agent: string;
+  handoffSha256?: string;
 }>;
 
 type TaskFinalizationOptions = Readonly<{
   repoRoot: string;
   controlBinding?: Readonly<{ generation: string; requestId: string }>;
+  handoffDirectory?: string;
+  manifestPath?: string;
   metadataProvider?: TaskLifecycleOptions['metadataProvider'];
   lifecycle?: typeof applyTaskLifecycle;
   backfill?: typeof backfillCompletionComments;
@@ -198,20 +205,32 @@ function validateReceipt(value: unknown, taskId: string): TaskFinalizationReceip
   const receipt = value as Record<string, unknown>;
   const controlBinding = receipt.controlBinding as Record<string, unknown> | null | undefined;
   const states = ['pending', 'done', 'skipped'];
+  const requiredKeys = [
+    'version', 'taskId', 'intent', 'receiptId', 'revision', 'lifecycle', 'taskComment',
+    'verification', 'summary', 'warningProjection', 'warnings', 'updatedAt', 'lastError'
+  ];
+  if (receipt.controlBinding !== undefined) requiredKeys.push('controlBinding');
   if (
+    Object.keys(receipt).sort().join('\0') !== requiredKeys.sort().join('\0')
+    ||
     receipt.version !== RECEIPT_VERSION || receipt.taskId !== taskId || receipt.intent !== 'complete'
     || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
     || !Number.isSafeInteger(receipt.revision) || Number(receipt.revision) < 0
-    || !states.includes(String(receipt.lifecycle))
-    || !states.includes(String(receipt.taskComment))
-    || !states.includes(String(receipt.verification))
-    || !states.includes(String(receipt.summary))
-    || !['pending', 'done'].includes(String(receipt.warningProjection))
+    || !states.includes(receipt.lifecycle as string)
+    || !states.includes(receipt.taskComment as string)
+    || !states.includes(receipt.verification as string)
+    || !states.includes(receipt.summary as string)
+    || !['pending', 'done'].includes(receipt.warningProjection as string)
     || !Array.isArray(receipt.warnings) || receipt.warnings.some((warning) => !validWarning(warning))
-    || typeof receipt.updatedAt !== 'string'
-    || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)))
+    || typeof receipt.updatedAt !== 'string' || receipt.updatedAt.length === 0
+    || (receipt.lastError !== null && (typeof receipt.lastError !== 'object' || Array.isArray(receipt.lastError)
+      || Object.keys(receipt.lastError).sort().join('\0') !== ['code', 'message', 'retryable'].join('\0')
+      || typeof (receipt.lastError as Record<string, unknown>).code !== 'string'
+      || typeof (receipt.lastError as Record<string, unknown>).message !== 'string'
+      || typeof (receipt.lastError as Record<string, unknown>).retryable !== 'boolean'))
     || (receipt.controlBinding !== undefined && (!controlBinding || typeof controlBinding !== 'object'
       || Array.isArray(controlBinding)
+      || Object.keys(controlBinding).sort().join('\0') !== ['generation', 'requestId'].join('\0')
       || typeof controlBinding.generation !== 'string' || controlBinding.generation.length === 0
       || typeof controlBinding.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId)))
   ) throw new Error('receipt schema is invalid');
@@ -243,6 +262,14 @@ function writeReceipt(repoRoot: string, receipt: TaskFinalizationReceipt): void
   }
 }
 
+export function bindTaskFinalizationReceipt(
+  repoRoot: string, taskId: string, controlBinding: Readonly<{ generation: string; requestId: string }>
+): TaskFinalizationReceipt {
+  const receipt = readReceipt(path.resolve(repoRoot), taskId);
+  if (!receipt) throw new Error('TASK_FINALIZATION_PREPARATION_REQUIRED');
+  return updateReceipt(path.resolve(repoRoot), receipt, { controlBinding, lastError: null });
+}
+
 function updateReceipt(
   repoRoot: string,
   receipt: TaskFinalizationReceipt,
@@ -798,10 +825,16 @@ async function prepareUnderLock(
   } catch (error) {
     return failed(taskId, errorOf(error, 'TASK_FINALIZATION_RECEIPT_INVALID'));
   }
-  if (options.controlBinding && (
-    receipt.controlBinding?.generation !== options.controlBinding.generation
-    || receipt.controlBinding.requestId !== options.controlBinding.requestId
-  )) receipt = updateReceipt(repoRoot, receipt, { controlBinding: options.controlBinding });
+  if (options.controlBinding && (receipt.controlBinding?.generation !== options.controlBinding.generation
+    || receipt.controlBinding.requestId !== options.controlBinding.requestId)) {
+    const state = resolveTaskRef(taskId, { repoRoot });
+    if (!(receipt.lifecycle === 'done' && state.ok && state.state === 'completed')) {
+      return failed(taskId, {
+        code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+        message: 'canonical receipt is not bound to the current sandbox request', retryable: false
+      });
+    }
+  }
 
   const preflightState = resolveTaskRef(taskId, { repoRoot });
   if (options.preflight && preflightState.ok && preflightState.state === 'active') {
@@ -1043,13 +1076,88 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
   if (!resolved.ok) return failed(resolved.taskId, { code: resolved.code, message: resolved.message, retryable: false });
   try {
     return await withTaskExecutionLock(repoRoot, resolved.taskId, 'task-finalization.commit', () => {
-      const receipt = readReceipt(repoRoot, resolved.taskId);
+      if (options.controlBinding && options.manifestPath) {
+        try {
+          const manifest = readSandboxControlManifest(options.manifestPath);
+          const identity = validateSandboxControlIdentity({
+            publicStatusDir: manifest.publicStatusDir,
+            root: path.dirname(path.resolve(options.manifestPath)),
+            mode: manifest.mode,
+            taskId: manifest.taskId,
+            generation: manifest.generation,
+            controlRootId: manifest.controlRootId
+          });
+          if (identity.state !== 'valid' || manifest.taskId !== resolved.taskId
+            || manifest.generation !== options.controlBinding.generation
+            || fs.realpathSync.native(manifest.repoRoot) !== fs.realpathSync.native(repoRoot)) {
+            throw new Error('current sandbox manifest does not match finalization request');
+          }
+        } catch (error) {
+          return failed(resolved.taskId, {
+            code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+            message: error instanceof Error ? error.message : String(error), retryable: false
+          });
+        }
+      }
+      let receipt = readReceipt(repoRoot, resolved.taskId);
+      if (!receipt && options.controlBinding && options.handoffDirectory && request.handoffSha256) {
+        try {
+          const handoff = readTaskFinalizationHandoff(
+            options.handoffDirectory, resolved.taskId, options.controlBinding, request.handoffSha256
+          );
+          receipt = validateReceipt(handoff.receipt, resolved.taskId);
+          if (receipt.lifecycle !== 'pending') throw new Error('handoff lifecycle must be pending');
+          if (inspectTaskLifecycleProgress(repoRoot, resolved.taskId, request.agent) === 'unknown') {
+            throw new Error('TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE');
+          }
+          writeReceipt(repoRoot, receipt);
+          try { handoff.cleanup(); } catch { /* keep the persisted canonical receipt usable */ }
+        } catch (error) {
+          return failed(resolved.taskId, {
+            code: 'TASK_FINALIZATION_HANDOFF_INVALID',
+            message: error instanceof Error ? error.message : String(error), retryable: false
+          });
+        }
+      }
       if (!receipt) return failed(resolved.taskId, {
         code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation receipt is unavailable', retryable: true
       });
       if (receipt.lifecycle === 'done' && resolved.state === 'completed') {
         return terminalResult(resolved.taskId, receipt, { lifecycle: { status: 'no-op', changed: false, error: null } }, false);
       }
+      if (options.controlBinding) {
+        const proof = inspectTaskLifecycleProgress(repoRoot, resolved.taskId, request.agent);
+        const oldBinding = receipt.controlBinding;
+        if (!oldBinding || oldBinding.generation !== options.controlBinding.generation || proof === 'unknown') {
+          return failed(resolved.taskId, {
+            code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+            message: 'canonical receipt has no valid host recovery proof', retryable: false
+          });
+        }
+        if (oldBinding.requestId !== options.controlBinding.requestId && proof === 'not-started') {
+          if (receipt.lifecycle !== 'pending' || !options.handoffDirectory || !request.handoffSha256) {
+            return failed(resolved.taskId, {
+              code: 'TASK_FINALIZATION_RECOVERY_PROOF_UNAVAILABLE',
+              message: 'pending receipt cannot be rebound without a current handoff', retryable: false
+            });
+          }
+          try {
+            const handoff = readTaskFinalizationHandoff(
+              options.handoffDirectory, resolved.taskId, options.controlBinding, request.handoffSha256
+            );
+            const nextReceipt = validateReceipt(handoff.receipt, resolved.taskId);
+            if (nextReceipt.receiptId !== receipt.receiptId || nextReceipt.intent !== receipt.intent
+              || nextReceipt.lifecycle !== 'pending') throw new Error('handoff is not continuous with canonical receipt');
+            receipt = updateReceipt(repoRoot, receipt, { controlBinding: options.controlBinding });
+            try { handoff.cleanup(); } catch { /* keep the persisted canonical receipt usable */ }
+          } catch (error) {
+            return failed(resolved.taskId, {
+              code: 'TASK_FINALIZATION_HANDOFF_INVALID',
+              message: error instanceof Error ? error.message : String(error), retryable: false
+            });
+          }
+        }
+      }
       if (receipt.taskComment === 'pending' || receipt.verification === 'pending' || receipt.summary === 'pending' || receipt.warningProjection === 'pending') {
         return failed(resolved.taskId, {
           code: 'TASK_FINALIZATION_PREPARATION_REQUIRED', message: 'sandbox preparation has pending external steps', retryable: true

package/lib/task/intermediate-cleanup.ts

@@ -14,26 +14,14 @@ import {
   readTaskFinalizationReceipt,
   type TaskFinalizationReceipt
 } from './finalization.ts';
-import {
-  semanticDigest,
-  sha256Content
-} from './local-artifact-finalization.ts';
-import { artifactRecoveryRoot, readArtifactRecoveryIntent } from './artifact-repair-intent.ts';
-import type { ArtifactRecoveryIntent } from './artifact-repair-intent.ts';
-import { parseArtifactName } from './artifact-name.ts';
-import type { ArtifactSchemaFamily } from './artifact-schema.ts';
 import { enumerateAllTaskDirs, type TaskWorkspaceState } from './resolve-ref.ts';
 import type { TaskControlBindingEvidence } from './finalization-state.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
-const LOCAL_INTENT_RE = /^(TASK-\d{8}-\d{6})-(analysis|review-analysis|plan|review-plan|code|review-code)-(.+\.md)\.json$/;
 const COMMIT_INTENT_RE = /^(TASK-\d{8}-\d{6})\.json$/;
-const AUXILIARY_ROOTS = [
-  '.local-artifact-finalization-intents',
-  '.task-commit-intents'
-] as const;
+const AUXILIARY_ROOTS = ['.task-commit-intents'] as const;
 
-type CleanupKind = 'LFAI-CONSUMED' | 'COMMIT-SYNCED' | 'EMPTY-AUX-PARENT';
+type CleanupKind = 'COMMIT-SYNCED' | 'EMPTY-AUX-PARENT';
 type CleanupDisposition = 'planned' | 'protected' | 'skipped' | 'deleted' | 'failed';
 type FileIdentity = Readonly<{ dev: string; ino: string; size: number; mtimeMs: number }>;
 
@@ -153,47 +141,6 @@ function receiptGate(
   return null;
 }
 
-function canonicalLocalIntentPath(taskId: string, family: string, artifact: string): string {
-  return `${taskId}-${family}-${artifact}.json`;
-}
-
-function localIntentCandidate(
-  repoRoot: string,
-  task: TaskRecord | undefined,
-  filePath: string,
-  taskId: string,
-  family: ArtifactSchemaFamily,
-  artifact: string,
-  identity: FileIdentity,
-  options: ScanOptions
-): IntermediateCleanupItem {
-  const protectedReason = taskGate(task);
-  if (protectedReason) return item('LFAI-CONSUMED', taskId, filePath, 'protected', protectedReason, identity);
-  if (path.basename(filePath) !== canonicalLocalIntentPath(taskId, family, artifact)
-    || !parseArtifactName(artifact)?.family || parseArtifactName(artifact)!.family !== family) {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity);
-  }
-  let intent: ArtifactRecoveryIntent | null;
-  try { intent = readArtifactRecoveryIntent(repoRoot, taskId, family, artifact); }
-  catch { return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'LFAI_SCHEMA_INVALID', identity); }
-  if (!intent || intent.state !== 'consumed') {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'LFAI_STATE_PROTECTED', identity);
-  }
-  const artifactPath = path.join(task!.taskDir, artifact);
-  if (safeLstat(task!.taskDir, artifactPath, 'file') === null) {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'ARTIFACT_IDENTITY_MISMATCH', identity);
-  }
-  let content: string;
-  try { content = fs.readFileSync(artifactPath, 'utf8'); }
-  catch { return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'ARTIFACT_UNREADABLE', identity); }
-  if (intent.finalArtifactSha256 !== sha256Content(content) || intent.finalSemanticDigest !== semanticDigest(content)) {
-    return item('LFAI-CONSUMED', taskId, filePath, 'protected', 'ARTIFACT_DIGEST_MISMATCH', identity);
-  }
-  const receiptReason = receiptGate(repoRoot, task!, options);
-  if (receiptReason) return item('LFAI-CONSUMED', taskId, filePath, 'protected', receiptReason, identity);
-  return item('LFAI-CONSUMED', taskId, filePath, 'planned', 'LFAI_CONSUMED_AND_VERIFIED', identity);
-}
-
 function commitIntentCandidate(
   repoRoot: string,
   task: TaskRecord | undefined,
@@ -258,23 +205,12 @@ function readAuxiliaryCandidates(
         candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH'));
         continue;
       }
-      if (rootName === '.local-artifact-finalization-intents') {
-        const match = LOCAL_INTENT_RE.exec(entry.name);
-        if (!match || (selected && !selected.has(match[1]!))) {
-          if (!selected || !match) candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity));
-          continue;
-        }
-        candidates.push(localIntentCandidate(
-          repoRoot, tasks.get(match[1]!), filePath, match[1]!, match[2] as 'analysis' | 'plan' | 'code', match[3]!, identity, options
-        ));
-      } else {
-        const match = COMMIT_INTENT_RE.exec(entry.name);
-        if (!match || (selected && !selected.has(match[1]!))) {
-          if (!selected || !match) candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity));
-          continue;
-        }
-        candidates.push(commitIntentCandidate(repoRoot, tasks.get(match[1]!), filePath, match[1]!, identity, options));
+      const match = COMMIT_INTENT_RE.exec(entry.name);
+      if (!match || (selected && !selected.has(match[1]!))) {
+        if (!selected || !match) candidates.push(item('AUXILIARY-UNKNOWN', null, filePath, 'protected', 'PATH_IDENTITY_MISMATCH', identity));
+        continue;
       }
+      candidates.push(commitIntentCandidate(repoRoot, tasks.get(match[1]!), filePath, match[1]!, identity, options));
     }
     if (entries.length === 0) {
       candidates.push(item('EMPTY-AUX-PARENT', null, root, 'planned', 'EMPTY_CANONICAL_AUXILIARY_ROOT', rootIdentity));
@@ -307,56 +243,7 @@ function scanIntermediateCleanup(repoRoot: string, options: ScanOptions = {}): I
   return buildIntermediateCleanupReport(candidates, true);
 }
 
-function cleanupConsumedRecoveryFiles(repoRoot: string, task: TaskRecord | undefined, candidate: IntermediateCleanupItem): boolean {
-  if (candidate.kind !== 'LFAI-CONSUMED' || !candidate.taskId) return true;
-  if (!task) return false;
-  const match = LOCAL_INTENT_RE.exec(path.basename(candidate.path));
-  if (!match) return false;
-  let intent: ReturnType<typeof readArtifactRecoveryIntent>;
-  try { intent = readArtifactRecoveryIntent(repoRoot, candidate.taskId, match[2] as ArtifactSchemaFamily, match[3]!); }
-  catch { return false; }
-  if (!intent || intent.state !== 'consumed') return false;
-
-  const recovery = artifactRecoveryRoot(task.taskDir, intent.recoveryOperationId);
-  let stat: fs.Stats | null = null;
-  try { stat = fs.lstatSync(recovery); } catch (error) {
-    if (errorCode(error) === 'ENOENT') return true;
-    return false;
-  }
-  if (!stat.isDirectory() || stat.isSymbolicLink()) return false;
-  let entries: fs.Dirent[];
-  try { entries = fs.readdirSync(recovery, { withFileTypes: true }); } catch { return false; }
-  for (const entry of entries) {
-    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) {
-      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);
-    return true;
-  } catch (error) {
-    return errorCode(error) === 'ENOENT';
-  }
-}
-
-function removeCandidate(repoRoot: string, candidate: IntermediateCleanupItem, task?: TaskRecord): IntermediateCleanupItem {
+function removeCandidate(repoRoot: string, candidate: IntermediateCleanupItem): IntermediateCleanupItem {
   if (candidate.disposition !== 'planned') return candidate;
   const root = candidate.kind === 'EMPTY-AUX-PARENT'
     ? path.dirname(path.dirname(candidate.path))
@@ -373,9 +260,6 @@ function removeCandidate(repoRoot: string, candidate: IntermediateCleanupItem, t
   const actual = safeLstat(root, candidate.path, candidate.kind === 'EMPTY-AUX-PARENT' ? 'directory' : 'file');
   if (!actual) return { ...candidate, disposition: 'protected', reason: 'PATH_IDENTITY_CHANGED' };
   if (!sameFileIdentity(expected, actual)) return { ...candidate, disposition: 'protected', reason: 'PATH_IDENTITY_CHANGED' };
-  if (!cleanupConsumedRecoveryFiles(repoRoot, task, candidate)) {
-    return { ...candidate, disposition: 'protected', reason: 'RECOVERY_STAGING_NOT_SAFE_TO_REMOVE' };
-  }
   try {
     if (candidate.kind === 'EMPTY-AUX-PARENT') {
       if (fs.readdirSync(candidate.path).length !== 0) return { ...candidate, disposition: 'protected', reason: 'AUXILIARY_ROOT_NOT_EMPTY' };
@@ -434,7 +318,7 @@ function cleanupIntermediateUnderRemovalCoordinator(
         if (initialCandidate.disposition !== 'planned') continue;
         const current = refreshedByKey.get(intermediateCleanupKey(initialCandidate));
         items[index] = current
-          ? removeCandidate(repoRoot, current, tasks.get(taskId))
+          ? removeCandidate(repoRoot, current)
           : { ...initialCandidate, disposition: 'protected', reason: 'CANDIDATE_NO_LONGER_ELIGIBLE' };
       }
     };

package/lib/task/ledger-intents.ts

@@ -14,7 +14,6 @@ import type { LedgerRow, ReviewStage } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
-import { allowsManualOverride } from './guard-override.ts';
 import { parseLegacyReworkIntentDocument, parseReworkIntentDocument, reworkIntentMutation, upsertReworkIntent } from './rework-intent.ts';
 import type { ReworkClassification, ReworkIntent, ReworkTarget } from './rework-intent.ts';
 import { extractSection, extractSubSection } from './sections.ts';
@@ -149,8 +148,7 @@ function mapWrite(intent: LedgerIntent, entityId: string, before: LedgerRow | nu
 function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {}): LedgerIntentResult {
   const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
-  const stateOverride = allowsManualOverride(options.manualOverride, 'ledger-intent', 'TASK_STATE_MISMATCH');
-  if (resolved.state !== 'active' && !stateOverride) return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  if (resolved.state !== 'active') return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   let content: string;
   let rows: LedgerRow[];
   try {
@@ -353,8 +351,7 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
             ? new Set(['confirmed', 'open', 'needs-human-decision'])
             : before.status === 'cannot-judge' ? new Set(['open', 'needs-human-decision']) : new Set<string>();
         const sameRoundMinorClose = before.status === 'open' && before.severity === 'minor' && intent.status === 'closed';
-        if ((!sameRoundMinorClose && !allowed.has(intent.status))
-          && !allowsManualOverride(options.manualOverride, 'ledger-intent', 'LEDGER_TRANSITION_INVALID')) {
+        if (!sameRoundMinorClose && !allowed.has(intent.status)) {
           return failed(intent, 'LEDGER_TRANSITION_INVALID', `finding '${intent.id}' cannot transition from ${before.status} to ${intent.status}`, resolved.taskId, intent.id);
         }
         after = { ...before, status: intent.status, evidence };
@@ -388,7 +385,7 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
   }
 
   const result = writeTask({
-    taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active',
+    taskRef: intent.taskRef, expectedState: 'active',
     mutations: [rowMutation(after), ...(implementationMutation ? [implementationMutation] : [])],
     dryRun: 'dryRun' in intent ? intent.dryRun : false
   }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state } });

package/lib/task/lifecycle.ts

@@ -107,16 +107,11 @@ type TaskLifecycleOptions = {
   fileSystem?: Partial<LifecycleFileSystem>;
   taskFileSystem?: Partial<TaskFileSystem>;
   directoryRenameSync?: (source: string, target: string) => void;
-  manualOverride?: Readonly<{ failureId: string; operator: string; reason: string }>;
   /** Write the terminal task document and durable journal, but leave the move
    * and short-id mutation for a separately authorized commit. */
   prepareOnly?: boolean;
 };
 
-function allowsManualOverride(options: TaskLifecycleOptions, code: string): boolean {
-  return options.manualOverride?.failureId === `lifecycle.apply:${code}`;
-}
-
 const STEPS: readonly LifecycleStep[] = ['task-written', 'directory-moved', 'registry-committed'];
 const DEFAULT_IO: LifecycleFileSystem = {
   renameSync: (source, target) => fs.renameSync(source, target),
@@ -362,6 +357,44 @@ export function readLifecycleJournalEvidence(repoRoot: string, taskId: string):
   } catch { return { exists: true, completedSteps: [], failure: 'SANDBOX_CONTROL_LIFECYCLE_JOURNAL_INVALID' }; }
 }
 
+export function inspectTaskLifecycleProgress(
+  repoRoot: string, taskId: string, agent: string
+): 'not-started' | 'started-recoverable' | 'unknown' {
+  try {
+    const hot = locateHotTaskDirs(repoRoot, taskId);
+    if (hot.length !== 1 || (hot[0]!.state !== 'active' && hot[0]!.state !== 'completed')) return 'unknown';
+    const { state, taskDir } = hot[0]!;
+    const content = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
+    const frontmatter = parseTypedTaskFrontmatter(content);
+    if (frontmatter.id !== taskId) return 'unknown';
+    const journalPath = path.join(taskDir, '.task-lifecycle.json');
+    if (!fs.existsSync(journalPath)) {
+      if (state === 'active') return frontmatter.status === 'active' ? 'not-started' : 'unknown';
+      return matchingCompletion(content, { taskRef: taskId, intent: 'complete', agent })
+        ? 'started-recoverable' : 'unknown';
+    }
+    const journal = parseJournal(fs.readFileSync(journalPath, 'utf8'));
+    const request: TaskLifecycleRequest = { taskRef: taskId, intent: 'complete', agent };
+    if (journal.taskId !== taskId || journal.intent !== 'complete'
+      || journal.intentDigest !== intentIdentity(request, taskId)
+      || journal.sourceState !== 'active' || journal.targetState !== 'completed') return 'unknown';
+    if (journal.completedSteps.some((step, index) => STEPS[index] !== step)) return 'unknown';
+    const directoryMoved = journal.completedSteps.includes('directory-moved');
+    const registryCommitted = journal.completedSteps.includes('registry-committed');
+    const hasShortId = loadShortIdByTaskId(repoRoot).has(taskId);
+    if (state === 'active' && (directoryMoved || !hasShortId)) return 'unknown';
+    if (state === 'completed' && (!journal.completedSteps.includes('task-written')
+      || !matchingCompletion(content, request) || (registryCommitted && hasShortId))) return 'unknown';
+    if (frontmatter.status !== state
+      && !(state === 'active' && frontmatter.status === 'completed' && matchingCompletion(content, request))) {
+      return 'unknown';
+    }
+    return 'started-recoverable';
+  } catch {
+    return 'unknown';
+  }
+}
+
 type DirectoryEntry = Readonly<{ relativePath: string; kind: 'file' | 'directory'; size: number; digest: string }>;
 
 function directoryManifest(root: string): DirectoryEntry[] {
@@ -468,7 +501,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     }
     return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: `task ${taskId} is already ${spec.target} with a different lifecycle intent` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
-  if (!spec.sources.includes(sourceState) && !existingJournal && !allowsManualOverride(options, 'LIFECYCLE_SOURCE_INVALID')) {
+  if (!spec.sources.includes(sourceState) && !existingJournal) {
     return failed(request, { code: 'LIFECYCLE_SOURCE_INVALID', message: `${request.intent} is not allowed from ${sourceState}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
   if (sourcePath !== targetPath && fs.existsSync(targetPath) && !existingJournal) {
@@ -479,7 +512,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   try { frontmatter = parseTypedTaskFrontmatter(content); }
   catch (error) { return failed(request, { code: 'LIFECYCLE_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath }); }
   if (frontmatter.id !== taskId) return failed(request, { code: 'LIFECYCLE_IDENTITY_INVALID', message: 'task.md id does not match its lifecycle task id' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
-  if (!locateActivityLog(content) && !allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING')) return failed(request, { code: 'LIFECYCLE_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
+  if (!locateActivityLog(content)) return failed(request, { code: 'LIFECYCLE_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   if (spec.target === 'active') {
     const contract = validateCurrentTaskContract(content);
     if (!contract.ok) return failed(request, { code: 'LIFECYCLE_DOCUMENT_INVALID', message: contract.message }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
@@ -493,10 +526,10 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   }
   const registry = JSON.parse(registryRequest.output || '{"version":1,"ids":{}}') as { ids: Record<string, string> };
   const registeredKey = Object.entries(registry.ids).find(([, candidate]) => candidate === taskId)?.[0];
-  if (spec.registry === 'release' && sourceState === 'active' && !registeredKey && !allowsManualOverride(options, 'LIFECYCLE_SHORT_ID_PRECONDITION')) {
+  if (spec.registry === 'release' && sourceState === 'active' && !registeredKey) {
     return failed(request, { code: 'LIFECYCLE_SHORT_ID_PRECONDITION', message: 'active source has no short-id registry entry' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
-  if (spec.registry === 'alloc' && !registeredKey && Object.keys(registry.ids).length >= 10 ** configuredShortIdLength(repoRoot) - 1 && !allowsManualOverride(options, 'SHORT_ID_CAPACITY_EXCEEDED')) {
+  if (spec.registry === 'alloc' && !registeredKey && Object.keys(registry.ids).length >= 10 ** configuredShortIdLength(repoRoot) - 1) {
     return failed(request, { code: 'SHORT_ID_CAPACITY_EXCEEDED', message: 'short-id registry has no free slot' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
   const digest = intentIdentity(request, taskId);
@@ -514,8 +547,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
       if (!journal.failure) return failed(request, { code: 'LIFECYCLE_JOURNAL_INVALID', message: 'existing lifecycle journal has no durable failure evidence for a read-only probe' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
       return failed(request, journal.failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath, completedSteps: journal.completedSteps, pendingSteps: STEPS.filter((step) => !journal.completedSteps.includes(step)) });
     }
-    const overrideResumesRecordedFailure = journal.failure && allowsManualOverride(options, journal.failure.code);
-    if (journal.intentDigest !== digest && !overrideResumesRecordedFailure) return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
+    if (journal.intentDigest !== digest) return failed(request, { code: 'LIFECYCLE_INTENT_CONFLICT', message: 'an in-progress lifecycle journal belongs to a different request' }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
   } else {
     let metadata: TaskWriteMetadata;
     try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
@@ -525,7 +557,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     }
     journal = { version: 1, taskId, intent: request.intent, intentDigest: digest, sourceState, targetState: spec.target, metadata, completedSteps: [] };
     if (request.dryRun) {
-      const plannedMutations = mutationsFor(request, content, metadata, restoredFiles, allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING'));
+      const plannedMutations = mutationsFor(request, content, metadata, restoredFiles, false);
       if ('code' in plannedMutations) return failed(request, plannedMutations, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
       const taskPlan = writeTask(
         { taskRef: taskId, expectedState: sourceState === 'blocked' ? 'blocked' : 'active', mutations: plannedMutations, dryRun: true },
@@ -561,7 +593,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   if (matchingCompletion(io.readFileSync(path.join(sourcePath, 'task.md')), request, restoredFiles)) completed.add('task-written');
   if (!completed.has('task-written')) {
     const current = io.readFileSync(path.join(sourcePath, 'task.md'));
-    const mutations = mutationsFor(request, current, journal.metadata, restoredFiles, allowsManualOverride(options, 'LIFECYCLE_LOG_MISSING'));
+    const mutations = mutationsFor(request, current, journal.metadata, restoredFiles, false);
     if ('code' in mutations) return failed(request, mutations, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, completedSteps: [...completed], changed: completed.size > 0 });
     const writeResult = writeTask(
       { taskRef: taskId, expectedState: sourceState === 'blocked' ? 'blocked' : 'active', mutations },

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

@@ -2,10 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { inspectDecisionDetailDuplicates } from './decision-details.ts';
-import { scanVisibleMarkdown } from './markdown.ts';
 import { parseArtifactName } from './artifact-name.ts';
+import { parseLifecyclePathDecision } from './lifecycle-path.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
-import { canonicalSemanticDigest, inspectArtifactPatterns, inspectArtifactStructure, sha256Content } from './artifact-operations.ts';
+import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 
 type LocalArtifactFamily = 'analysis' | 'plan' | 'code';
@@ -24,7 +24,8 @@ type LocalArtifactDiagnosticCode =
   | 'LOCAL_DECISION_DETAIL_DUPLICATE'
   | 'LOCAL_REQUIRED_PATTERN_MISSING'
   | 'LOCAL_STRUCTURAL_INVALID'
-  | 'LOCAL_SECTION_HEADING_TRAILING_PUNCTUATION';
+  | 'LOCAL_SECTION_HEADING_TRAILING_PUNCTUATION'
+  | 'LOCAL_FLOW_DECISION_INVALID';
 
 type LocalArtifactDiagnostic = {
   code: LocalArtifactDiagnosticCode;
@@ -71,7 +72,9 @@ function localDiagnosticCode(code: string): LocalArtifactDiagnosticCode {
     ARTIFACT_EMPTY: 'LOCAL_ARTIFACT_EMPTY',
     ARTIFACT_MISSING_SECTION: 'LOCAL_ARTIFACT_MISSING_SECTION',
     ARTIFACT_DUPLICATE_SECTION: 'LOCAL_ARTIFACT_DUPLICATE_SECTION',
-    ARTIFACT_HEADING_TRAILING_PUNCTUATION: 'LOCAL_SECTION_HEADING_TRAILING_PUNCTUATION'
+    ARTIFACT_HEADING_TRAILING_PUNCTUATION: 'LOCAL_SECTION_HEADING_TRAILING_PUNCTUATION',
+    ARTIFACT_STATE_CHECK_PATTERN_MISSING: 'LOCAL_STATUS_COMMAND_MISSING',
+    ARTIFACT_REQUIRED_PATTERN_MISSING: 'LOCAL_REQUIRED_PATTERN_MISSING'
   };
   return map[code] ?? 'LOCAL_STRUCTURAL_INVALID';
 }
@@ -80,47 +83,25 @@ function localDiagnostic(item: { code: string; message: string; line: number | n
   return { code: localDiagnosticCode(item.code), message: item.message, line: item.line };
 }
 
-function isStatusPattern(pattern: string): boolean {
-  return pattern === '^\\$ ';
-}
-
 function validateLocalArtifact(
   content: string,
   options: LocalArtifactValidationOptions
 ): LocalArtifactValidationResult {
   const schema = getArtifactSchema(options.family)!;
   const diagnostics: LocalArtifactDiagnostic[] = [];
-  const scanned = scanVisibleMarkdown(content);
-  const structure = inspectArtifactStructure(content, schema);
-  for (const item of structure.diagnostics) diagnostics.push(localDiagnostic(item));
-
-  const statusSection = schema.sections.find((section) => section.id === 'state-check');
-  if (statusSection) {
-    const statusHeading = scanned.headings.find((heading) => (
-      heading.level === 2 && [statusSection.headings.zh, statusSection.headings.en].some((name) => (
-        heading.text === name || heading.text === `${name}:` || heading.text === `${name}：`
-      ))
-    ));
-    if (statusHeading) {
-      const next = scanned.headings.find((candidate) => candidate.start > statusHeading.start && candidate.level <= 2);
-      const body = content.slice(statusHeading.end, next?.start ?? content.length);
-      for (const pattern of schema.requiredPatterns.filter(isStatusPattern)) {
-        if (!new RegExp(pattern, 'm').test(body)) {
-          diagnostics.push({ code: 'LOCAL_STATUS_COMMAND_MISSING', message: `status section '${statusHeading.text}' is missing required command output`, line: content.slice(0, statusHeading.start).split('\n').length });
-        }
-      }
-    }
-  }
-
-  const patternInspection = inspectArtifactPatterns(content, {
-    ...schema,
-    requiredPatterns: schema.requiredPatterns.filter((item) => !isStatusPattern(item))
-  });
-  for (const item of patternInspection.diagnostics) diagnostics.push({ code: 'LOCAL_REQUIRED_PATTERN_MISSING', message: item.message, line: null });
+  const inspection = inspectArtifactContract(content, schema, { scopeStateCheckSection: true });
+  for (const item of inspection.diagnostics) diagnostics.push(localDiagnostic(item));
 
   const decisionDetails = inspectDecisionDetailDuplicates(content);
   if (!decisionDetails.ok) diagnostics.push({ code: 'LOCAL_DECISION_DETAIL_DUPLICATE', message: decisionDetails.message, line: null });
 
+  if (options.family === 'analysis') {
+    const flowDecision = parseLifecyclePathDecision(content);
+    if (flowDecision.status !== 'valid') {
+      diagnostics.push({ code: 'LOCAL_FLOW_DECISION_INVALID', message: flowDecision.message, line: null });
+    }
+  }
+
   return {
     ok: diagnostics.length === 0,
     family: options.family,

package/lib/task/review-command.ts

@@ -1,13 +1,10 @@
 import type { ReviewFinalizationRequest } from './review-finalization.ts';
 
-export function parseReviewCommand(args: readonly string[]): ReviewFinalizationRequest & {
-  overrideTicket?: string; overrideTarget?: string; overrideScope?: string;
-} {
+export function parseReviewCommand(args: readonly string[]): ReviewFinalizationRequest {
   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',
-    '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
+    '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun'
   } as const;
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;