@fitlab-ai/agent-infra 0.9.10 → 0.9.12

package/lib/task/delivery.ts

@@ -0,0 +1,160 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+import { parseTaskFrontmatter } from './frontmatter.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { resolveDeliveryTarget, resolveDiffBase, resolveTargetHead, validateBaseRef, validateRemote } from './delivery-target.ts';
+import { extractReviewBaseline, extractReviewDiffBase, extractReviewTargetHead, extractReviewedHead, findAuthoritativeReviewCodeArtifact } from './review-fingerprint.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import { withRepositoryMutationLock, withTaskExecutionLock } from './task-execution-lock.ts';
+
+export type DeliveryState = 'absent' | 'same' | 'known-old' | 'unknown-drift';
+
+export type DeliveryClassification = Readonly<{
+  state: DeliveryState;
+  shouldPush: boolean;
+}>;
+
+export type TaskBranchDeliveryResult = Readonly<{
+  status: 'applied' | 'no-op' | 'failed' | 'blocked' | 'planned';
+  changed: boolean;
+  taskId: string | null;
+  remoteHead: string | null;
+  localHead: string | null;
+  state: DeliveryState | null;
+  error: { code: string; message: string; retryable: boolean } | null;
+}>;
+
+function classifyDeliveryState(localHead: string, remoteHead: string | null, lastDelivered: string | null): DeliveryClassification {
+  if (remoteHead === null) return { state: 'absent', shouldPush: true };
+  if (remoteHead === localHead) return { state: 'same', shouldPush: false };
+  if (lastDelivered && remoteHead === lastDelivered) return { state: 'known-old', shouldPush: true };
+  return { state: 'unknown-drift', shouldPush: false };
+}
+
+function git(cwd: string, args: readonly string[]): { status: number | null; stdout: string; stderr: string } {
+  const result = spawnSync('git', [...args], { cwd, encoding: 'utf8' });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+
+function gitValue(cwd: string, args: readonly string[]): string | null {
+  const result = git(cwd, args);
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function validateBranch(cwd: string, branch: string): boolean {
+  return git(cwd, ['check-ref-format', `refs/heads/${branch}`]).status === 0;
+}
+
+function validateReviewTargetCompatibility(
+  repoRoot: string,
+  taskDir: string,
+  target: { remote: string; baseRef: string },
+  reviewedHead: string
+): { ok: true } | { ok: false; code: string; message: string } {
+  const artifact = findAuthoritativeReviewCodeArtifact(taskDir);
+  if (!artifact.ok || !artifact.path) return { ok: false, code: 'DELIVERY_REVIEW_REQUIRED', message: 'A current review-code artifact is required before delivery' };
+  let content: string;
+  try { content = fs.readFileSync(artifact.path, 'utf8'); }
+  catch (error) { return { ok: false, code: 'DELIVERY_REVIEW_REQUIRED', message: error instanceof Error ? error.message : String(error) }; }
+  const savedReviewedHead = extractReviewedHead(content) || extractReviewBaseline(content);
+  const savedTargetHead = extractReviewTargetHead(content);
+  const savedDiffBase = extractReviewDiffBase(content);
+  if (!savedReviewedHead || !savedTargetHead || !savedDiffBase) {
+    return { ok: false, code: 'DELIVERY_REVIEW_TARGET_INVALID', message: 'review-code must save reviewed head, target head, and diff base before delivery' };
+  }
+  if (savedReviewedHead !== reviewedHead) {
+    return { ok: false, code: 'DELIVERY_REVIEW_REQUIRED', message: 'review-code reviewed head does not match last_reviewed_commit' };
+  }
+  const saved = resolveDiffBase(repoRoot, reviewedHead, savedTargetHead);
+  if (!saved.ok || saved.diffBase !== savedDiffBase) {
+    return { ok: false, code: 'DELIVERY_REVIEW_TARGET_INVALID', message: saved.ok ? 'saved review diff base does not match saved target head' : saved.message };
+  }
+  const currentTarget = resolveTargetHead(repoRoot, target);
+  if (!currentTarget.ok) return { ok: false, code: currentTarget.code, message: currentTarget.message };
+  const current = resolveDiffBase(repoRoot, reviewedHead, currentTarget.head!);
+  if (!current.ok) return { ok: false, code: current.code, message: current.message };
+  if (current.diffBase !== savedDiffBase) {
+    return { ok: false, code: 'DELIVERY_REVIEW_TARGET_CHANGED', message: 'current delivery target changed the reviewed diff base; re-run review-code' };
+  }
+  return { ok: true };
+}
+
+function failure(taskId: string | null, code: string, message: string, retryable = false, status: 'failed' | 'blocked' = retryable ? 'blocked' : 'failed'): TaskBranchDeliveryResult {
+  return { status, changed: false, taskId, remoteHead: null, localHead: null, state: null, error: { code, message, retryable } };
+}
+
+function deliverUnlocked(
+  taskId: string,
+  taskDir: string,
+  repoRoot: string,
+  options: { agent: string; remote?: string; baseRef?: string; dryRun?: boolean }
+): TaskBranchDeliveryResult {
+  let frontmatter: ReturnType<typeof parseTaskFrontmatter>;
+  try { frontmatter = parseTaskFrontmatter(fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8')); }
+  catch (error) { return failure(taskId, 'TASK_CONTEXT_UNREADABLE', error instanceof Error ? error.message : String(error)); }
+  if (frontmatter.status !== 'active') return failure(taskId, 'TASK_STATE_INVALID', 'task branch delivery requires an active task');
+  const branch = frontmatter.branch ?? '';
+  if (!branch) return failure(taskId, 'DELIVERY_BRANCH_MISSING', 'task branch is missing');
+  if (!validateBranch(repoRoot, branch)) return failure(taskId, 'DELIVERY_BRANCH_INVALID', 'task branch is invalid');
+  if (!frontmatter.delivery_remote || !frontmatter.delivery_base_ref) {
+    return failure(taskId, 'DELIVERY_TARGET_MISSING', 'task delivery target is not bound; recreate or repair task metadata before delivery');
+  }
+  const target = resolveDeliveryTarget(repoRoot, {
+    remote: frontmatter.delivery_remote,
+    baseRef: frontmatter.delivery_base_ref
+  }, {
+    ...(options.remote === undefined ? {} : { remote: options.remote }),
+    ...(options.baseRef === undefined ? {} : { baseRef: options.baseRef })
+  });
+  if (!target.ok) return failure(taskId, target.code, target.message);
+  if (!validateRemote(target.value.remote) || !validateBaseRef(target.value.baseRef)) return failure(taskId, 'DELIVERY_TARGET_INVALID', 'task delivery target is invalid');
+  const localHead = gitValue(repoRoot, ['rev-parse', 'HEAD']);
+  if (!localHead) return failure(taskId, 'DELIVERY_LOCAL_HEAD_UNAVAILABLE', 'Unable to resolve local HEAD');
+  const status = git(repoRoot, ['status', '--porcelain=v1']);
+  if (status.status !== 0) return failure(taskId, 'DELIVERY_GIT_INSPECT_FAILED', status.stderr.trim() || 'Unable to inspect Git state');
+  if (status.stdout.trim()) return failure(taskId, 'DELIVERY_WORKTREE_DIRTY', 'Working tree must be clean before branch delivery');
+  const reviewed = frontmatter.last_reviewed_commit ?? '';
+  if (reviewed !== localHead) return failure(taskId, 'DELIVERY_REVIEW_REQUIRED', 'Local HEAD must equal last_reviewed_commit before delivery');
+  const reviewTarget = validateReviewTargetCompatibility(repoRoot, taskDir, target.value, reviewed);
+  if (!reviewTarget.ok) return failure(taskId, reviewTarget.code, reviewTarget.message, reviewTarget.code.includes('UNAVAILABLE'), reviewTarget.code.includes('UNAVAILABLE') ? 'blocked' : 'failed');
+  const ref = `refs/heads/${branch}`;
+  const remoteOutput = git(repoRoot, ['ls-remote', '--refs', target.value.remote, ref]);
+  if (remoteOutput.status !== 0) return failure(taskId, 'DELIVERY_REMOTE_UNAVAILABLE', remoteOutput.stderr.trim() || 'Unable to inspect the delivery remote', true);
+  const remoteHead = remoteOutput.stdout.trim().split(/\s+/)[0] || null;
+  const classification = classifyDeliveryState(localHead, remoteHead, frontmatter.delivery_remote_head ?? null);
+  if (classification.state === 'unknown-drift') return failure(taskId, 'DELIVERY_REMOTE_DRIFT', `Remote branch ${branch} has an unexpected head; refusing to overwrite it`);
+  if (options.dryRun) return { status: 'planned', changed: classification.shouldPush, taskId, remoteHead, localHead, state: classification.state, error: null };
+  if (classification.shouldPush) {
+    const args = classification.state === 'known-old'
+      ? ['push', `--force-with-lease=${ref}:${frontmatter.delivery_remote_head}`, target.value.remote, `HEAD:${ref}`]
+      : ['push', `--force-with-lease=${ref}:`, target.value.remote, `HEAD:${ref}`];
+    const pushed = git(repoRoot, args);
+    if (pushed.status !== 0) return failure(taskId, 'DELIVERY_PUSH_FAILED', pushed.stderr.trim() || 'Task branch delivery was rejected', true, 'blocked');
+  }
+  const verified = gitValue(repoRoot, ['ls-remote', '--refs', target.value.remote, ref])?.split(/\s+/)[0] ?? null;
+  if (verified !== localHead) return failure(taskId, 'DELIVERY_REMOTE_VERIFY_FAILED', `Expected remote head ${localHead}, received ${verified ?? 'unavailable'}`, true, 'blocked');
+  const written = writeTask({
+    taskRef: taskId,
+    expectedState: 'active',
+    mutations: [{ kind: 'frontmatter', set: { delivery_remote: target.value.remote, delivery_base_ref: target.value.baseRef, delivery_remote_head: localHead, assigned_to: options.agent } }]
+  }, { repoRoot, metadataProvider: captureTaskWriteMetadata });
+  if (written.status === 'failed') return failure(taskId, 'DELIVERY_TASK_SYNC_FAILED', written.error.message, true, 'blocked');
+  return { status: classification.shouldPush ? 'applied' : 'no-op', changed: classification.shouldPush || written.changed, taskId, remoteHead: localHead, localHead, state: classification.state, error: null };
+}
+
+function deliverTaskBranch(taskRef: string, options: { repoRoot?: string; agent: string; remote?: string; baseRef?: string; dryRun?: boolean }): TaskBranchDeliveryResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failure(resolved.taskId, resolved.code, resolved.message);
+  try {
+    return withRepositoryMutationLock(resolved.repoRoot, () => withTaskExecutionLock(
+      resolved.repoRoot, resolved.taskId, 'task-delivery',
+      () => deliverUnlocked(resolved.taskId, resolved.taskDir, resolved.repoRoot, options)
+    ));
+  } catch (error) {
+    return failure(resolved.taskId, 'DELIVERY_LOCK_FAILED', error instanceof Error ? error.message : String(error), true, 'blocked');
+  }
+}
+
+export { classifyDeliveryState, deliverTaskBranch };

package/lib/task/events.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 
-import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-log.ts';
+import { appendActivityEntry, locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import {
   buildArtifactLinkSection,
   artifactName,
@@ -21,9 +21,9 @@ import {
   parseImplementationInputs,
   renderImplementationInputs
 } from './implementation-inputs.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 { ReviewStage } from './ledger.ts';
-import { parseReviewSummary } from './review-artifacts.ts';
+import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import { findSectionHeading } from './sections.ts';
 import { validateLifecycleExecution } from './lifecycle-execution.ts';
@@ -50,6 +50,7 @@ type TaskEventErrorCode =
   | 'EVENT_UNKNOWN' | 'EVENT_PAYLOAD_INVALID' | 'EVENT_TRANSITION_INVALID'
   | 'EVENT_LOG_MISSING' | 'EVENT_START_MISSING' | 'EVENT_ALREADY_COMPLETED'
   | 'EVENT_LOG_CONFLICT' | 'EVENT_ARTIFACT_CONFLICT' | 'EVENT_FINDING_COUNT_MISMATCH'
+  | 'EVENT_VERDICT_INVALID'
   | 'EVENT_ORCHESTRATION_COMMIT_FAILED'
   | ArtifactErrorCode | TaskWriteErrorCode;
 type TaskEventRequest = {
@@ -151,7 +152,9 @@ function validateReviewFindingCounts(
 ): TaskEventError | null {
   const stage = REVIEW_LEDGER_STAGES[family];
   if (!stage || !artifactPath) return null;
-  const rows = parseLedger(content);
+  const ledger = parseLedgerDocument(content);
+  if (!ledger.present) return { code: 'EVENT_FINDING_COUNT_MISMATCH', message: `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}` };
+  const rows = ledger.rows;
   const invalid = validateLedgerRows(rows);
   if (invalid) return { code: 'TASK_DOCUMENT_INVALID', message: `${invalid.code}: ${invalid.message}` };
   const expected = summarizeLedgerStage(rows, stage).unresolvedFindingCounts;
@@ -173,6 +176,8 @@ function validateReviewFindingCounts(
       message: parsed.ok ? 'review summary finding counts are not finalized' : parsed.message
     };
   }
+  const canonical = resolveCanonicalVerdict(parsed.summary);
+  if (!canonical.ok) return { code: 'EVENT_VERDICT_INVALID', message: `${canonical.code}: ${canonical.message}` };
   const report = parsed.summary.counts;
   const reportVerdict = parsed.summary.verdict === 'Approved'
     ? 'approved'
@@ -370,7 +375,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   catch (error) { return failed(request, { code: 'TASK_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
   const section = locateActivityLog(content);
   if (!section) return failed(request, { code: 'EVENT_LOG_MISSING', message: 'task has no unique Activity Log section' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath });
-  const rows = pairEntries(section.entries);
+  const rows = startedBackedRows(pairEntries(section.entries));
   let normalized = request;
   let artifactContext: ArtifactContextResult | null = null;
   const initialParts = eventParts(request.event);

package/lib/task/human-override.ts

@@ -24,6 +24,7 @@ import { verifyTaskEvent } from './verification.ts';
 import { verifyInProcess } from './verification-engine.ts';
 import { canonicalTimestamp, writeTask } from './write.ts';
 import type { TaskFileSystem, TaskWriteMetadata, TaskWriteResult } from './write.ts';
+import { readPrDeliveryFact } from './pr-delivery-fact.ts';
 
 type Eligibility = 'eligible' | 'repair-only' | 'runtime-recovery-only' | 'never-overridable';
 type OutcomeEffect = 'apply-target' | 'retry-same-intent' | 'record-only' | 'no-write';
@@ -614,7 +615,8 @@ function resourceForSnapshot(
     return number === null ? null : { kind: 'issue', number };
   }
   if (policy.producerId === 'platform.pull-request') {
-    const number = options.probePullRequestNumber ?? toPositiveInteger(frontmatter?.pr_number);
+    const fact = frontmatter ? readPrDeliveryFact(frontmatter) : null;
+    const number = options.probePullRequestNumber ?? (fact?.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
     return number === null ? null : { kind: 'pull-request', number };
   }
   return null;
@@ -705,7 +707,8 @@ function probePlatformFailure(
     return error('OVERRIDE_DOCUMENT_INVALID', cause instanceof Error ? cause.message : String(cause));
   }
   const issueNumber = options.probeIssueNumber ?? toPositiveInteger(frontmatter.issue_number);
-  const pullRequestNumber = options.probePullRequestNumber ?? toPositiveInteger(frontmatter.pr_number);
+  const fact = readPrDeliveryFact(frontmatter);
+  const pullRequestNumber = options.probePullRequestNumber ?? (fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null);
   const operation = policy.producerId === 'platform.issue'
     ? issueNumber === null
       ? null

package/lib/task/index.ts

@@ -1,34 +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)
+  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 show --task 11
+  ai task show --task TASK-20260612-162737
+  ai task status --task 11
 
 Run 'ai task <command> --help' for details.`;
 

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,12 +12,15 @@ 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'
 ] as const;
 const lifecycleFailureCatalog = [
   'LIFECYCLE_DIRECTORY_RENAME_FAILED',
+  'LIFECYCLE_DIRECTORY_COPY_FAILED',
   'LIFECYCLE_DOCUMENT_INVALID',
   'LIFECYCLE_FINAL_STATE_INVALID',
   'LIFECYCLE_IDENTITY_CONFLICT',
@@ -126,6 +129,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' };
@@ -326,6 +337,62 @@ function parseJournal(content: string): LifecycleJournal {
   return value as LifecycleJournal;
 }
 
+type DirectoryEntry = Readonly<{ relativePath: string; kind: 'file' | 'directory'; size: number; digest: string }>;
+
+function directoryManifest(root: string): DirectoryEntry[] {
+  const entries: DirectoryEntry[] = [];
+  const visit = (current: string, relative = '') => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      const relativePath = relative ? path.join(relative, entry.name) : entry.name;
+      const absolute = path.join(current, entry.name);
+      const stat = fs.lstatSync(absolute);
+      if (stat.isSymbolicLink()) throw new Error(`symbolic link is not allowed in lifecycle directory: ${relativePath}`);
+      if (entry.isDirectory()) {
+        entries.push({ relativePath, kind: 'directory', size: 0, digest: '' });
+        visit(absolute, relativePath);
+      } else if (entry.isFile()) {
+        const digest = createHash('sha256').update(fs.readFileSync(absolute)).digest('hex');
+        entries.push({ relativePath, kind: 'file', size: stat.size, digest });
+      } else {
+        throw new Error(`unsupported lifecycle directory entry: ${relativePath}`);
+      }
+    }
+  };
+  visit(root);
+  return entries;
+}
+
+function copyDirectoryVerified(source: string, target: string): void {
+  if (fs.existsSync(target)) throw new Error(`target directory already exists: ${target}`);
+  const copy = (currentSource: string, currentTarget: string) => {
+    fs.mkdirSync(currentTarget);
+    for (const entry of fs.readdirSync(currentSource, { withFileTypes: true })) {
+      const sourcePath = path.join(currentSource, entry.name);
+      const targetPath = path.join(currentTarget, entry.name);
+      const stat = fs.lstatSync(sourcePath);
+      if (stat.isSymbolicLink()) throw new Error(`symbolic link is not allowed in lifecycle directory: ${entry.name}`);
+      if (entry.isDirectory()) copy(sourcePath, targetPath);
+      else if (entry.isFile()) fs.copyFileSync(sourcePath, targetPath);
+      else throw new Error(`unsupported lifecycle directory entry: ${entry.name}`);
+    }
+  };
+  copy(source, target);
+  const sourceManifest = directoryManifest(source);
+  const targetManifest = directoryManifest(target);
+  if (JSON.stringify(sourceManifest) !== JSON.stringify(targetManifest)) {
+    throw new Error('copied lifecycle directory failed manifest verification');
+  }
+}
+
+function removeCopiedSource(source: string, target: string): void {
+  const sourceManifest = directoryManifest(source);
+  const targetManifest = directoryManifest(target);
+  if (JSON.stringify(sourceManifest) !== JSON.stringify(targetManifest)) {
+    throw new Error('lifecycle source and target diverged before source cleanup');
+  }
+  fs.rmSync(source, { recursive: true, force: false });
+}
+
 function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLifecycleOptions = {}): TaskLifecycleResult {
   const normalized = normalizedRequest(requestInput);
   if ('code' in normalized) return failed(requestInput, normalized);
@@ -376,7 +443,7 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
   if (!spec.sources.includes(sourceState) && !existingJournal && !allowsManualOverride(options, 'LIFECYCLE_SOURCE_INVALID')) {
     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)) {
+  if (sourcePath !== targetPath && fs.existsSync(targetPath) && !existingJournal) {
     return failed(request, { code: 'LIFECYCLE_TARGET_CONFLICT', message: `target directory already exists: ${targetPath}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath });
   }
   const content = io.readFileSync(currentTaskFile);
@@ -385,6 +452,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 +479,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 +492,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'));
@@ -478,13 +555,45 @@ function applyTaskLifecycle(requestInput: TaskLifecycleRequest, options: TaskLif
     if (fs.existsSync(targetPath)) return failed(request, { code: 'LIFECYCLE_TARGET_CONFLICT', message: `target directory already exists: ${targetPath}` }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
     try { (options.directoryRenameSync ?? io.renameSync)(sourcePath, targetPath); }
     catch (error) {
+      if ((error as { code?: string }).code === 'EXDEV') {
+        try {
+          copyDirectoryVerified(sourcePath, targetPath);
+          completed.add('directory-moved');
+          journal.completedSteps = [...completed];
+          const copiedJournalPath = path.join(targetPath, '.task-lifecycle.json');
+          writeJournal(initialJournalPath, journal, io);
+          writeJournal(copiedJournalPath, journal, io);
+          removeCopiedSource(sourcePath, targetPath);
+          journalPath = copiedJournalPath;
+        } catch (copyError) {
+          if (fs.existsSync(targetPath)) fs.rmSync(targetPath, { recursive: true, force: false });
+          const failure = { code: 'LIFECYCLE_DIRECTORY_COPY_FAILED', message: String(copyError) } as const;
+          rememberJournalFailure(initialJournalPath, journal, io, failure);
+          return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath: initialJournalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+        }
+      } else {
       const failure = { code: 'LIFECYCLE_DIRECTORY_RENAME_FAILED', message: String(error) } as const;
       rememberJournalFailure(journalPath, journal, io, failure);
       return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
+      }
+    }
+    if (completed.has('directory-moved') && !fs.existsSync(sourcePath)) {
+      journalPath = path.join(targetPath, '.task-lifecycle.json');
+    } else if (!completed.has('directory-moved')) {
+      completed.add('directory-moved'); journal.completedSteps = [...completed]; journalPath = path.join(targetPath, '.task-lifecycle.json');
+      try { writeJournal(journalPath, journal, io); }
+      catch (error) { return failed(request, { code: 'LIFECYCLE_JOURNAL_WRITE_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, directory: { effect: 'move', changed: true }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion }); }
+    }
+  }
+  if (completed.has('directory-moved') && sourcePath !== targetPath && fs.existsSync(sourcePath) && fs.existsSync(targetPath)) {
+    try {
+      removeCopiedSource(sourcePath, targetPath);
+      journalPath = path.join(targetPath, '.task-lifecycle.json');
+    } catch (error) {
+      const failure = { code: 'LIFECYCLE_DIRECTORY_COPY_FAILED', message: String(error) } as const;
+      rememberJournalFailure(journalPath, journal, io, failure);
+      return failed(request, failure, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion });
     }
-    completed.add('directory-moved'); journal.completedSteps = [...completed]; journalPath = path.join(targetPath, '.task-lifecycle.json');
-    try { writeJournal(journalPath, journal, io); }
-    catch (error) { return failed(request, { code: 'LIFECYCLE_JOURNAL_WRITE_FAILED', message: String(error) }, { taskId, sourceState, targetState: spec.target, sourcePath, targetPath, journalPath, task: { operations: taskOperations }, directory: { effect: 'move', changed: true }, changed: true, completedSteps: [...completed], timestamp: journal.metadata.timestamp, agentInfraVersion: journal.metadata.agentInfraVersion }); }
   }
   let shortId: TaskLifecycleResult['shortId'] = { effect: 'unchanged', shortId: null, changed: false };
   if (!completed.has('registry-committed')) {