@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/lib/task/finalization.ts

@@ -85,6 +85,13 @@ type TaskFinalizationStep = Readonly<{
   pendingSteps?: readonly string[];
 }>;
 
+type TaskCommentSyncOutcome = Readonly<{
+  receipt: TaskFinalizationReceipt;
+  step: TaskFinalizationStep;
+  changed: boolean;
+  error: FinalizationError | null;
+}>;
+
 type TaskFinalizationResult = Readonly<{
   status: 'completed' | 'failed' | 'blocked';
   changed: boolean;
@@ -390,11 +397,18 @@ function mutationPatch(current: TaskFinalizationReceipt, mutation: FinalizationM
   }
   if (mutation.scope === 'verification') {
     if (mutation.operation === 'succeeded') {
+      const resolvedTaskWarning = current.warnings.some((warning) => warning.step === 'verification' && warning.status === 'open');
       const warnings = resolveStepWarnings(current, 'verification');
-      return { verification: 'done', warningProjection: warnings.length > 0 ? 'pending' : 'done', warnings, lastError: null };
+      return {
+        verification: 'done',
+        taskComment: resolvedTaskWarning ? 'pending' : current.taskComment,
+        warningProjection: warnings.length > 0 ? 'pending' : 'done',
+        warnings,
+        lastError: null
+      };
     }
     const warnings = replaceWarning(current, warningFromError('verification', mutation.error), 'open');
-    return { verification: 'pending', warningProjection: 'pending', warnings, lastError: mutation.error };
+    return { verification: 'pending', taskComment: 'pending', warningProjection: 'pending', warnings, lastError: mutation.error };
   }
   return mutation.operation === 'succeeded'
     ? { warningProjection: 'done', lastError: null }
@@ -472,6 +486,56 @@ function reconcileWarningProjection(repoRoot: string, taskId: string, receipt: T
   catch { return receipt; }
 }
 
+function syncPendingTaskComment(input: {
+  repoRoot: string;
+  taskId: string;
+  agent: string;
+  receipt: TaskFinalizationReceipt;
+  commentSync: typeof syncPlatformComment;
+  consumedCapabilities: Set<string>;
+}): TaskCommentSyncOutcome {
+  const { repoRoot, taskId, agent, commentSync, consumedCapabilities } = input;
+  let receipt = input.receipt;
+  if (receipt.taskComment !== 'pending') {
+    return {
+      receipt,
+      step: { status: receipt.taskComment === 'skipped' ? 'skipped' : 'no-op', changed: false, error: null },
+      changed: false,
+      error: null
+    };
+  }
+  try {
+    const result = commentSync(taskId, { kind: 'task', agent, cwd: repoRoot });
+    const step = commentStep(result);
+    if (result.status === 'applied' || result.status === 'no-op') {
+      const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
+      const capability = issueCapability(receipt, 'task-comment');
+      receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+        scope: 'task-comment', operation: 'succeeded', state: skipped ? 'skipped' : 'done'
+      }, consumedCapabilities);
+      receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+      return { receipt, step: skipped ? { ...step, status: 'skipped' } : step, changed: result.changed, error: null };
+    }
+    const detail = step.error ?? { code: 'COMMENT_SYNC_FAILED', message: 'task comment synchronization failed', retryable: true };
+    const capability = issueCapability(receipt, 'task-comment');
+    receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+      scope: 'task-comment', operation: 'failed', error: detail
+    }, consumedCapabilities);
+    receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+    return { receipt, step, changed: result.changed, error: detail };
+  } catch (error) {
+    const detail = errorOf(error, 'COMMENT_SYNC_FAILED', true);
+    try {
+      const capability = issueCapability(receipt, 'task-comment');
+      receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
+        scope: 'task-comment', operation: 'failed', error: detail
+      }, consumedCapabilities);
+      receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+    } catch { /* preserve the primary error */ }
+    return { receipt, step: { status: 'blocked', changed: false, error: detail }, changed: false, error: detail };
+  }
+}
+
 function terminalResult(
   taskId: string,
   receipt: TaskFinalizationReceipt,
@@ -603,46 +667,15 @@ function applyUnderLock(
   }
 
   let taskComment: TaskFinalizationStep | null = null;
-  try {
-    receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    if (receipt.taskComment !== 'pending') {
-      taskComment = {
-        status: receipt.taskComment === 'skipped' ? 'skipped' : 'no-op',
-        changed: false,
-        error: null
-      };
-    } else {
-      const result = commentSync(taskId, { kind: 'task', agent: request.agent, cwd: repoRoot });
-      taskComment = commentStep(result);
-      if (result.status === 'applied' || result.status === 'no-op') {
-        const skipped = result.error?.code === 'ISSUE_NOT_LINKED';
-        const capability = issueCapability(receipt, 'task-comment');
-        receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
-          scope: 'task-comment', operation: 'succeeded', state: skipped ? 'skipped' : 'done'
-        }, consumedCapabilities);
-        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        taskComment = skipped ? { ...taskComment, status: 'skipped' } : taskComment;
-        changed = changed || result.changed;
-      } else {
-        const detail = taskComment.error ?? { code: 'COMMENT_SYNC_FAILED', message: 'task comment synchronization failed', retryable: true };
-        const capability = issueCapability(receipt, 'task-comment');
-        receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
-          scope: 'task-comment', operation: 'failed', error: detail
-        }, consumedCapabilities);
-        receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-        return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: null }, changed, taskComment.error);
-      }
-    }
-  } catch (error) {
-    const detail = errorOf(error, 'COMMENT_SYNC_FAILED', true);
-    try {
-      const capability = issueCapability(receipt, 'task-comment');
-      receipt = applyFinalizationReceiptMutationUnderLock(repoRoot, receipt, capability, {
-        scope: 'task-comment', operation: 'failed', error: detail
-      }, consumedCapabilities);
-      receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
-    } catch { /* preserve the primary error */ }
-    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment: { status: 'blocked', changed: false, error: detail }, verification: null }, changed, detail);
+  receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+  const initialComment = syncPendingTaskComment({
+    repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+  });
+  receipt = initialComment.receipt;
+  taskComment = initialComment.step;
+  changed = changed || initialComment.changed;
+  if (initialComment.error) {
+    return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification: null }, changed, initialComment.error);
   }
 
   let verification: TaskFinalizationStep | null = null;
@@ -662,6 +695,15 @@ function applyUnderLock(
           scope: 'verification', operation: 'succeeded'
         }, consumedCapabilities);
         receipt = reconcileWarningProjection(repoRoot, taskId, receipt, consumedCapabilities);
+        const finalComment = syncPendingTaskComment({
+          repoRoot, taskId, agent: request.agent, receipt, commentSync, consumedCapabilities
+        });
+        receipt = finalComment.receipt;
+        if (finalComment.step.status !== 'no-op') taskComment = finalComment.step;
+        changed = changed || finalComment.changed;
+        if (finalComment.error) {
+          return terminalResult(taskId, receipt, { lifecycle: lifecycleResult, taskComment, verification }, changed, finalComment.error);
+        }
       } else {
         const detail = verification.error ?? { code: 'VERIFY_FAILED', message: 'verification failed', retryable: true };
         const capability = issueCapability(receipt, 'verification');

package/lib/task/index.ts

@@ -1,36 +1,33 @@
 const USAGE = `Usage: ai task <command> [options]
 
 Commands:
-  cat [--task <ref>] <artifact | N>      Print a task artifact (by name or number)
-  decisions, d [--task <ref>] [-i item]  List review decisions, or show one item's detail
-  files [--task <ref>]                   List artifacts in a task dir (numbered)
-  grep <pattern> [--current|--task <ref>] Literal search across task artifacts (global by default)
-  issue-body [--task <ref>] [--template] Print a deterministic Issue body from task.md
-  log [--task <ref>]                     Render a task's activity log as a timeline
+  cat [--task <ref> | -t <ref>] <artifact | N> Print a task artifact (by name or number)
+  decisions, d [--task <ref> | -t <ref>] [--item <selector> | -i <selector>] List review decisions, or show one item's detail
+  files [--task <ref> | -t <ref>]        List artifacts in a task dir (numbered)
+  grep [--current | --task <ref> | -t <ref>] <pattern> Literal search in the current or selected task
+  issue-body [--task <ref> | -t <ref>] [--template <path>] Print a deterministic Issue body from task.md
+  log [--task <ref> | -t <ref>]          Render a task's activity log as a timeline
   ls [--all | --blocked | --completed]   List tasks (default: active)
-  show [--task <ref>]                    Print a task.md
-  status [--task <ref>]                  Aggregated status view (metadata / artifacts / git / platform)
-  validate <ref> [options] -- <command>  Run host validation in snapshot or inplace scope
+  show [--task <ref> | -t <ref>]         Print a task.md
+  status [--task <ref> | -t <ref>]       Aggregated status view (metadata / artifacts / git / platform)
 
 Examples:
-  ai task cat 11 analysis
   ai task cat analysis
-  ai task cat 11 3
-  ai task decisions 11
+  ai task cat --task 11 analysis
+  ai task decisions --task 11
   ai task decisions --item 1
-  ai task d 11 PL-3 --format markdown
-  ai task files 11
+  ai task d --task 11 --item PL-3 --format markdown
+  ai task files --task 11
   ai task grep resolveArtifact
   ai task grep resolveArtifact --current
-  ai task grep resolveArtifact 11
-  ai task issue-body 11
-  ai task issue-body 11 --template .github/ISSUE_TEMPLATE/05_other.yml
-  ai task log 11
+  ai task grep resolveArtifact --task 11
+  ai task issue-body --task 11
+  ai task issue-body --task 11 --template .github/ISSUE_TEMPLATE/05_other.yml
+  ai task log --task 11
   ai task ls
-  ai task show 11
-  ai task show TASK-20260612-162737
-  ai task status 11
-  ai task validate 11 -- npm test
+  ai task show --task 11
+  ai task show --task TASK-20260612-162737
+  ai task status --task 11
 
 Run 'ai task <command> --help' for details.`;
 
@@ -95,12 +92,6 @@ export async function runTask(args: string[]): Promise<void> {
       status(rest);
       break;
     }
-    case 'validate': {
-      const { validate } = await import('./commands/validate.ts');
-      const exitCode = await validate(rest);
-      if (exitCode !== 0) process.exitCode = exitCode;
-      break;
-    }
     default:
       process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
       process.stdout.write(`${USAGE}\n`);

package/lib/task/ledger-intents.ts

@@ -7,7 +7,7 @@ import {
   parseImplementationInputs,
   renderImplementationInputs
 } from './implementation-inputs.ts';
-import { LEDGER_COLUMNS, LEDGER_HEADINGS, nextHdId, parseLedger, validateLedgerRows } from './ledger.ts';
+import { LEDGER_COLUMNS, LEDGER_HEADINGS, LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, nextHdId, parseLedgerDocument, validateLedgerRows } from './ledger.ts';
 import type { LedgerRow, ReviewStage } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { writeTask } from './write.ts';
@@ -61,6 +61,7 @@ function normalizedEvidence(value: string): string {
 
 function ledgerReadErrorCode(error: unknown): string {
   const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+  if (code === LEDGER_SECTION_MISSING_CODE) return code;
   return code === 'TABLE_DUPLICATE_KEY' ? 'LEDGER_DUPLICATE_ID' : 'LEDGER_DOCUMENT_INVALID';
 }
 
@@ -96,12 +97,7 @@ function rowMutation(row: LedgerRow): TaskMutation {
 }
 
 function ledgerSectionMutation(content: string): TaskMutation[] {
-  if (/^##\s+(审查分歧账本|Review Disagreement Ledger)\s*$/m.test(content)) return [];
-  const english = /^##\s+Activity Log\s*$/m.test(content);
-  return [{
-    kind: 'section', aliases: LEDGER_HEADINGS, heading: english ? 'Review Disagreement Ledger' : '审查分歧账本',
-    body: `| ${LEDGER_COLUMNS.join(' | ')} |\n|----|-------|-------|----------|--------|----------|`
-  }];
+  return [];
 }
 
 function implementationInputMutation(content: string, rows: Parameters<typeof renderImplementationInputs>[0]): TaskMutation {
@@ -127,7 +123,9 @@ function applyLedgerIntent(intent: LedgerIntent, options: TaskWriteOptions = {})
   let rows: LedgerRow[];
   try {
     content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    rows = parseLedger(content);
+    const ledger = parseLedgerDocument(content);
+    if (!ledger.present) return failed(intent, LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, resolved.taskId);
+    rows = ledger.rows as LedgerRow[];
   } catch (error) {
     return failed(intent, ledgerReadErrorCode(error), error instanceof Error ? error.message : String(error), resolved.taskId);
   }

package/lib/task/ledger.ts

@@ -20,6 +20,10 @@ type LedgerRow = {
   /** Zero-based line within the normalized ledger section body. */
   sourceLine: number;
 };
+type LedgerDocument = {
+  present: boolean;
+  rows: readonly LedgerRow[];
+};
 
 type ReviewStage = 'analysis' | 'plan' | 'code';
 type ReviewSeverity = 'blocker' | 'major' | 'minor';
@@ -40,6 +44,8 @@ const LEDGER_TERMINAL = new Set(['confirmed', 'closed', 'human-decided']);
 // Statuses that represent a decision row awaiting or carrying a human ruling.
 const HUMAN_DECISION_STATUSES = new Set(['needs-human-decision', 'human-decided']);
 const FINDING_STATUSES = new Set(['open', 'accepted', 'adjusted', 'refuted', 'cannot-judge', 'confirmed', 'needs-human-decision', 'closed', 'human-decided']);
+const LEDGER_SECTION_MISSING_CODE = 'LEDGER_SECTION_MISSING';
+const LEDGER_SECTION_MISSING_MESSAGE = 'review disagreement ledger section is missing';
 
 function isReviewStage(stage: string): stage is ReviewStage {
   return stage === 'analysis' || stage === 'plan' || stage === 'code';
@@ -48,12 +54,16 @@ function isReviewStage(stage: string): stage is ReviewStage {
 // Parse all rows of the disagreement ledger table. Skips the heading, the
 // header row (`| id | ... |`) and the `|---|` separator; ignores non-`|` lines.
 // Rows with fewer than 6 columns are skipped (mirrors the JS gate parser).
-function parseLedger(content: string): LedgerRow[] {
+function parseLedgerDocument(content: string): LedgerDocument {
   const table = parseTable(content, { sectionAliases: LEDGER_HEADINGS, columns: LEDGER_COLUMNS });
-  return table?.rows.map(({ values, sourceLine }) => ({
-    id: values.id!, stage: values.stage!, round: values.round!, severity: values.severity!,
-    status: values.status!, evidence: values.evidence!, sourceLine
-  })) ?? [];
+  if (!table) return { present: false, rows: [] };
+  return {
+    present: true,
+    rows: table.rows.map(({ values, sourceLine }) => ({
+      id: values.id!, stage: values.stage!, round: values.round!, severity: values.severity!,
+      status: values.status!, evidence: values.evidence!, sourceLine
+    }))
+  };
 }
 
 function validateLedgerRows(rows: readonly LedgerRow[]): LedgerValidationError | null {
@@ -130,5 +140,5 @@ function nextHdId(rows: readonly LedgerRow[]): string {
   return `HD-${max + 1}`;
 }
 
-export { LEDGER_HEADINGS, LEDGER_COLUMNS, parseLedger, nextHdId, isReviewStage, validateLedgerRows, summarizeLedgerStage, LEDGER_TERMINAL, HUMAN_DECISION_STATUSES };
-export type { LedgerRow, ReviewStage, ReviewSeverity, LedgerValidationError, LedgerStageStatus };
+export { LEDGER_HEADINGS, LEDGER_COLUMNS, parseLedgerDocument, nextHdId, isReviewStage, validateLedgerRows, summarizeLedgerStage, LEDGER_TERMINAL, HUMAN_DECISION_STATUSES, LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE };
+export type { LedgerRow, LedgerDocument, ReviewStage, ReviewSeverity, LedgerValidationError, LedgerStageStatus };

package/lib/task/lifecycle.ts

@@ -12,6 +12,8 @@ import {
 } from './short-id.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskFileSystem, TaskMutation, TaskOperationSummary, TaskWriteMetadata } from './write.ts';
+import { validateCurrentTaskContract } from './current-contract.ts';
+import { isValidAgentInfraVersion } from '../version.ts';
 
 const lifecycleIntentCatalog = [
   'block', 'activate', 'cancel', 'complete', 'close-codescan', 'close-dependabot', 'restore'
@@ -126,6 +128,14 @@ function failed(request: Pick<TaskLifecycleRequest, 'taskRef' | 'intent'>, error
   };
 }
 
+export function taskLifecycleFailure(
+  request: Pick<TaskLifecycleRequest, 'taskRef' | 'intent'>,
+  error: LifecycleError,
+  taskId: string | null = null
+): TaskLifecycleResult {
+  return failed(request, error, { taskId });
+}
+
 function normalizedRequest(request: TaskLifecycleRequest): TaskLifecycleRequest | LifecycleError {
   if (!request || typeof request !== 'object' || !lifecycleIntentCatalog.includes(request.intent as TaskLifecycleIntent)) {
     return { code: 'LIFECYCLE_PAYLOAD_INVALID', message: 'intent is not in the lifecycle catalog' };
@@ -385,6 +395,10 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   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 (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 });
+  }
   const registryRequest = executeShortIdCommand({
     operation: 'list', activeDir: path.join(repoRoot, '.agents', 'workspace', 'active'),
     shortIdLength: configuredShortIdLength(repoRoot)
@@ -408,6 +422,9 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     try { journal = parseJournal(io.readFileSync(initialJournalPath)); }
     catch (error) { return failed(request, { code: 'LIFECYCLE_JOURNAL_INVALID', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath }); }
     if (journal.taskId !== taskId || journal.intent !== request.intent) 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 (spec.target === 'active' && !isValidAgentInfraVersion(journal.metadata.agentInfraVersion)) {
+      return failed(request, { code: 'LIFECYCLE_DOCUMENT_INVALID', message: `journal metadata agentInfraVersion must be a valid v-prefixed semver (received ${journal.metadata.agentInfraVersion})` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath });
+    }
     if (request.dryRun) {
       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)) });
@@ -418,6 +435,9 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     let metadata: TaskWriteMetadata;
     try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
     catch (error) { return failed(request, { code: 'LIFECYCLE_METADATA_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath }); }
+    if (spec.target === 'active' && !isValidAgentInfraVersion(metadata.agentInfraVersion)) {
+      return failed(request, { code: 'LIFECYCLE_DOCUMENT_INVALID', message: `metadata agentInfraVersion must be a valid v-prefixed semver (received ${metadata.agentInfraVersion})` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
+    }
     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'));

package/lib/task/orchestration.ts

@@ -3,9 +3,11 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
-import { parseReviewSummary } from './review-artifacts.ts';
+import { validateCurrentTaskContract } from './current-contract.ts';
+import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
 import { inspectArtifactDirectory } from './artifact-lifecycle.ts';
-import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import type { LedgerDocument } from './ledger.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import {
   activateDelegation,
@@ -119,6 +121,7 @@ type OrchestrationResult = Readonly<{
   taskId: string | null;
   run: OrchestrationRun | null;
   next: OrchestrationNext | null;
+  warnings?: readonly Readonly<{ code: string; message: string; action: string }>[];
   error: Readonly<{
     code: string;
     message: string;
@@ -181,7 +184,7 @@ function orchestrationPath(taskDir: string): string {
   return path.join(taskDir, 'orchestration.json');
 }
 
-const ORCHESTRATION_STATE_INVALID_MESSAGE = 'orchestration.json does not match the current runtime structure; finish or clear active runs before upgrading';
+const ORCHESTRATION_STATE_INVALID_MESSAGE = 'orchestration.json does not match the current runtime structure; the file was left unchanged; rebuild the sandbox or manually repair the state before retrying';
 
 class OrchestrationStateError extends Error {
   readonly code = 'ORCHESTRATION_STATE_INVALID';
@@ -529,14 +532,20 @@ function hasReviewAfterArtifact(taskDir: string, family: string, reviewFamily: s
     && review.reviewedInput?.name === artifact.latest.name;
 }
 
-function latestReviewApproved(taskDir: string, family: 'review-analysis' | 'review-plan' | 'review-code'): boolean {
+function latestReviewApproved(taskDir: string, family: 'review-analysis' | 'review-plan' | 'review-code'): { approved: boolean; error: string | null } {
   const round = highestRound(taskDir, family);
-  if (round === 0) return false;
-  const parsed = parseReviewSummary(fs.readFileSync(path.join(taskDir, artifactName(family, round)), 'utf8'));
-  return parsed.ok && parsed.summary.verdict === 'Approved' && parsed.summary.counts !== null;
+  if (round === 0) return { approved: false, error: null };
+  let content: string;
+  try { content = fs.readFileSync(path.join(taskDir, artifactName(family, round)), 'utf8'); }
+  catch (error) { return { approved: false, error: String(error) }; }
+  const parsed = parseReviewSummary(content);
+  if (!parsed.ok) return { approved: false, error: `${parsed.code}: ${parsed.message}` };
+  const verdict = resolveCanonicalVerdict(parsed.summary);
+  if (!verdict.ok) return { approved: false, error: `${verdict.code}: ${verdict.message}` };
+  return { approved: verdict.verdict === 'Approved', error: null };
 }
 
-function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | null {
+function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | { error: string } | null {
   const analysisRound = highestRound(taskDir, 'analysis');
   const analysisReviewRound = highestRound(taskDir, 'review-analysis');
   const planRound = highestRound(taskDir, 'plan');
@@ -551,7 +560,9 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
     const round = analysisReviewRound + 1;
     return { action: 'review-analysis', role: 'reviewer', stage: 'review-analysis', round, artifact: artifactName('review-analysis', round) };
   }
-  if (!latestReviewApproved(taskDir, 'review-analysis')) {
+  const analysisVerdict = latestReviewApproved(taskDir, 'review-analysis');
+  if (analysisVerdict.error) return { error: analysisVerdict.error };
+  if (!analysisVerdict.approved) {
     const round = analysisRound + 1;
     return { action: 'analyze-task', role: 'executor', stage: 'analysis', round, artifact: artifactName('analysis', round) };
   }
@@ -563,7 +574,9 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
     const round = planReviewRound + 1;
     return { action: 'review-plan', role: 'reviewer', stage: 'review-plan', round, artifact: artifactName('review-plan', round) };
   }
-  if (!latestReviewApproved(taskDir, 'review-plan')) {
+  const planVerdict = latestReviewApproved(taskDir, 'review-plan');
+  if (planVerdict.error) return { error: planVerdict.error };
+  if (!planVerdict.approved) {
     const round = planRound + 1;
     return { action: 'plan-task', role: 'executor', stage: 'plan', round, artifact: artifactName('plan', round) };
   }
@@ -575,7 +588,9 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
     const round = codeReviewRound + 1;
     return { action: 'review-code', role: 'reviewer', stage: 'review-code', round, artifact: artifactName('review-code', round) };
   }
-  if (!latestReviewApproved(taskDir, 'review-code')) {
+  const codeVerdict = latestReviewApproved(taskDir, 'review-code');
+  if (codeVerdict.error) return { error: codeVerdict.error };
+  if (!codeVerdict.approved) {
     const round = codeRound + 1;
     return { action: 'code-task', role: 'executor', stage: 'code', round, artifact: artifactName('code', round) };
   }
@@ -598,12 +613,21 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     return failed('ORCHESTRATION_TASK_READ_FAILED', String(error), resolved.taskId);
   }
   let metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
-  try {
-    metadata = parseTypedTaskFrontmatter(content);
-  } catch (error) {
-    return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  let currentLedger: LedgerDocument | null = null;
+  if (resolved.state === 'active') {
+    const contract = validateCurrentTaskContract(content);
+    if (!contract.ok) return failed('ORCHESTRATION_CURRENT_CONTRACT_INVALID', contract.message, resolved.taskId);
+    metadata = contract.metadata;
+    currentLedger = contract.ledger;
+  } else {
+    try {
+      metadata = parseTypedTaskFrontmatter(content);
+    } catch (error) {
+      return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
   }
   const routed = routeFromFacts(resolved.taskDir);
+  if (routed && 'error' in routed) return failed('ORCHESTRATION_REVIEW_INVALID', routed.error, resolved.taskId);
   if (!routed) return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
   const run = readRun(resolved.taskDir);
   const policy = run ? rolePolicy(run, routed.role) : null;
@@ -621,7 +645,9 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     if (!review.ok || review.summary.manualValidation === null) {
       return failed('ORCHESTRATION_REVIEW_INVALID', 'latest code review has no numeric manual-validation count', resolved.taskId);
     }
-    const rows = parseLedger(content);
+    const ledger = currentLedger ?? parseLedgerDocument(content);
+    if (!ledger.present) return failed('ORCHESTRATION_CURRENT_CONTRACT_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`, resolved.taskId);
+    const rows = ledger.rows;
     const ledgerError = validateLedgerRows(rows);
     if (ledgerError) return failed('ORCHESTRATION_LEDGER_INVALID', ledgerError.message, resolved.taskId);
     if (!summarizeLedgerStage(rows, 'code').canAdvance) {

package/lib/task/review-artifacts.ts

@@ -18,6 +18,21 @@ type ReviewSummaryErrorCode =
   | 'REVIEW_SUMMARY_NOT_FOUND'
   | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
   | 'REVIEW_SUMMARY_COUNT_MISMATCH';
+type VerdictSemanticErrorCode =
+  | 'REVIEW_VERDICT_FINDING_MISMATCH'
+  | 'REVIEW_FINDING_COUNTS_NOT_FINALIZED';
+type CanonicalVerdictResult =
+  | { ok: true; verdict: ReviewVerdict }
+  | { ok: false; verdict: null; code: VerdictSemanticErrorCode; message: string };
+type PathVerdictErrorCode =
+  | 'REVIEW_ARTIFACT_NOT_FOUND'
+  | 'REVIEW_ARTIFACT_READ_FAILED'
+  | 'REVIEW_SUMMARY_NOT_FOUND'
+  | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
+  | VerdictSemanticErrorCode;
+type PathVerdictResult =
+  | { ok: true; verdict: ReviewVerdict }
+  | { ok: false; verdict: null; code: PathVerdictErrorCode; message: string };
 type ReviewSummaryParseResult =
   | { ok: true; summary: ReviewSummary; findingsStart: number; findingsEnd: number }
   | { ok: false; code: ReviewSummaryErrorCode; message: string };
@@ -203,28 +218,46 @@ function finalizeReviewSummaryContent(
   };
 }
 
-function parseVerdict(reviewPath: string):
-  | { ok: true; verdict: 'Approved' | 'Approved-with-issues' | 'Changes Requested' | 'Rejected' }
-  | { ok: false; verdict: null; message: string } {
+function resolveCanonicalVerdict(summary: ReviewSummary): CanonicalVerdictResult {
+  if (summary.counts === null) {
+    return {
+      ok: false,
+      verdict: null,
+      code: 'REVIEW_FINDING_COUNTS_NOT_FINALIZED',
+      message: 'review summary finding counts are not finalized'
+    };
+  }
+  if (summary.verdict === 'Approved' && !equalCounts(summary.counts, { blocker: 0, major: 0, minor: 0 })) {
+    return {
+      ok: false,
+      verdict: null,
+      code: 'REVIEW_VERDICT_FINDING_MISMATCH',
+      message: 'Approved verdict requires zero finalized findings'
+    };
+  }
+  return { ok: true, verdict: summary.verdict };
+}
+
+function parseVerdict(reviewPath: string): PathVerdictResult {
   if (!fs.existsSync(reviewPath)) {
-    return { ok: false, verdict: null, message: `Review artifact not found: ${path.basename(reviewPath)}` };
+    return { ok: false, verdict: null, code: 'REVIEW_ARTIFACT_NOT_FOUND', message: `Review artifact not found: ${path.basename(reviewPath)}` };
+  }
+  let content: string;
+  try {
+    content = fs.readFileSync(reviewPath, 'utf8');
+  } catch (error) {
+    return { ok: false, verdict: null, code: 'REVIEW_ARTIFACT_READ_FAILED', message: `Review artifact could not be read: ${String(error)}` };
   }
-  const parsed = parseReviewSummary(fs.readFileSync(reviewPath, 'utf8'));
+  const parsed = parseReviewSummary(content);
   if (!parsed.ok) {
     return {
       ok: false,
       verdict: null,
+      code: parsed.code === 'REVIEW_SUMMARY_PLACEHOLDER_INVALID' ? parsed.code : 'REVIEW_SUMMARY_NOT_FOUND',
       message: `cannot parse review summary in ${path.basename(reviewPath)}: ${parsed.message}`
     };
   }
-  const { verdict, counts } = parsed.summary;
-  if (verdict !== 'Approved') return { ok: true, verdict };
-  return {
-    ok: true,
-    verdict: counts && equalCounts(counts, { blocker: 0, major: 0, minor: 0 })
-      ? 'Approved'
-      : 'Approved-with-issues'
-  };
+  return resolveCanonicalVerdict(parsed.summary);
 }
 
 export {
@@ -236,13 +269,18 @@ export {
   maxRound,
   normalizeVerdict,
   parseReviewSummary,
-  parseVerdict
+  parseVerdict,
+  resolveCanonicalVerdict
 };
 export type {
+  CanonicalVerdictResult,
+  PathVerdictErrorCode,
+  PathVerdictResult,
   ReviewFindingCounts,
   ReviewSummary,
   ReviewSummaryErrorCode,
   ReviewSummaryFinalizeResult,
   ReviewSummaryParseResult,
-  ReviewVerdict
+  ReviewVerdict,
+  VerdictSemanticErrorCode
 };