@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/server/daemon.ts

@@ -139,7 +139,7 @@ export async function runDaemon(): Promise<void> {
       logger.close();
       if (ownStartTime !== null) {
         removePidRecordIfMatches(config.pidFile, {
-          version: 1,
+          version: 2,
           pid: process.pid,
           startTime: ownStartTime
         });

package/lib/server/process-control.ts

@@ -11,7 +11,7 @@ import {
   removePidFileIfMatches,
   writePidRecord
 } from './process-state.ts';
-import type { PidRecord } from './process-state.ts';
+import type { PidRecord, ProcessIdentity, ProcessState } from './process-state.ts';
 
 export { isProcessAlive } from './process-state.ts';
 
@@ -51,13 +51,13 @@ async function waitForProcessIdentity(pid: number, timeoutMs = 2000): Promise<Pi
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     const startTime = getProcessStartTime(pid);
-    if (startTime !== null) return { version: 1, pid, startTime };
+    if (startTime !== null) return { version: 2, pid, startTime };
     await delay(25);
   }
   return null;
 }
 
-function terminateIfMatching(record: PidRecord): void {
+function terminateIfMatching(record: ProcessIdentity): void {
   if (!processIdentityMatches(record)) return;
   const command = buildStopCommand(record.pid, process.platform);
   try {
@@ -83,6 +83,9 @@ export async function start({ foreground = false }: StartOptions = {}): Promise<
     process.stdout.write(`server already running (pid ${existing.record.pid})\n`);
     return;
   }
+  if (existing.kind === 'legacy-json' || existing.kind === 'legacy-pid-only' || existing.kind === 'legacy-unknown') {
+    throw new Error('server: legacy pid record requires the matching previous version to stop it before starting');
+  }
   if (existing.kind !== 'missing') {
     removePidFileIfMatches(pidPath, existing.snapshot);
   }
@@ -135,6 +138,9 @@ export async function stop(): Promise<void> {
     return;
   }
   if (state.kind !== 'running') {
+    if (state.kind === 'legacy-json' || state.kind === 'legacy-pid-only' || state.kind === 'legacy-unknown') {
+      throw new Error('server: legacy pid record requires the matching previous version to stop it');
+    }
     removePidFileIfMatches(config.pidFile, state.snapshot);
     process.stdout.write('server is not running (removed stale pid file)\n');
     return;
@@ -170,6 +176,10 @@ export function status(): void {
   const state = readProcessState(config.pidFile);
 
   if (state.kind !== 'running') {
+    if (state.kind === 'legacy-json' || state.kind === 'legacy-pid-only' || state.kind === 'legacy-unknown') {
+      process.stdout.write('server: legacy pid record requires the matching previous version to stop it\n');
+      return;
+    }
     if (state.kind !== 'missing') removePidFileIfMatches(config.pidFile, state.snapshot);
     process.stdout.write('server: stopped\n');
     return;

package/lib/server/process-state.ts

@@ -2,22 +2,37 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 
-export type PidRecord = {
-  version: 1;
+export type ProcessStartTime = number;
+
+export type ProcessIdentity = Readonly<{
   pid: number;
-  startTime: string;
+  startTime: ProcessStartTime;
+}>;
+
+export type ProcessIdentityState = 'alive' | 'dead' | 'unknown';
+export type ProcessIdentityProbe = (identity: ProcessIdentity) => ProcessIdentityState;
+
+export type PidRecord = ProcessIdentity & {
+  version: 2;
 };
 
 export type ProcessStartTimeQuery = { command: string; args: string[] };
 
 export type ProcessState =
   | { kind: 'missing'; snapshot: null }
-  | { kind: 'invalid'; snapshot: string }
-  | { kind: 'legacy'; snapshot: string; pid: number }
+  | { kind: 'legacy-json'; snapshot: string; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-pid-only'; snapshot: string; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-unknown'; snapshot: string; legacy: LegacyProcessSnapshot; reason: string }
   | { kind: 'stale'; snapshot: string; record: PidRecord }
   | { kind: 'running'; snapshot: string; record: PidRecord };
 
-export type LinuxProcessStat = { state: string; startTime: string };
+export type LegacyProcessSnapshot = Readonly<{
+  pid?: number;
+  raw: string;
+  format: 'json-v1' | 'pid-only' | 'malformed';
+}>;
+
+export type LinuxProcessStat = { state: string; startTime: number };
 
 export function parseLinuxProcessStat(raw: string): LinuxProcessStat | null {
   const closeParen = raw.lastIndexOf(')');
@@ -28,7 +43,9 @@ export function parseLinuxProcessStat(raw: string): LinuxProcessStat | null {
   if (typeof state !== 'string' || state.length !== 1 || !/^\d+$/.test(startTime ?? '')) {
     return null;
   }
-  return { state, startTime: startTime! };
+  const numericStartTime = Number(startTime);
+  if (!Number.isSafeInteger(numericStartTime)) return null;
+  return { state, startTime: numericStartTime };
 }
 
 export function buildProcessStartTimeQuery(
@@ -68,10 +85,22 @@ export function isProcessAlive(pid: number, platform: NodeJS.Platform = process.
   }
 }
 
+function parseDarwinStartTime(output: string): number | null {
+  const match = output.trim().match(/^(?:Sun|Mon|Tue|Wed|Thu|Fri|Sat) ([A-Z][a-z]{2}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4})$/);
+  if (!match) return null;
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const month = months.indexOf(match[1]!);
+  if (month < 0) return null;
+  const timestamp = Date.UTC(
+    Number(match[6]), month, Number(match[2]), Number(match[3]), Number(match[4]), Number(match[5])
+  );
+  return Number.isNaN(timestamp) ? null : timestamp;
+}
+
 export function getProcessStartTime(
   pid: number,
   platform: NodeJS.Platform = process.platform
-): string | null {
+): ProcessStartTime | null {
   if (!Number.isInteger(pid) || pid <= 0) return null;
   if (platform === 'linux') {
     try {
@@ -85,43 +114,115 @@ export function getProcessStartTime(
   const query = buildProcessStartTimeQuery(pid, platform);
   if (query === null) return null;
   try {
-    const output = execFileSync(query.command, query.args, { encoding: 'utf8' }).trim();
+    const output = execFileSync(query.command, query.args, {
+      encoding: 'utf8',
+      env: platform === 'darwin' ? { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } : process.env
+    }).trim();
     if (output.length === 0) return null;
     if (platform === 'win32') {
       const timestamp = new Date(output);
-      return Number.isNaN(timestamp.getTime()) ? null : timestamp.toISOString();
+      return Number.isNaN(timestamp.getTime()) ? null : timestamp.getTime();
     }
-    return output;
+    if (platform === 'darwin') return parseDarwinStartTime(output);
+    return null;
   } catch {
     return null;
   }
 }
 
-function parsePidRecord(raw: string): { kind: 'invalid' } | { kind: 'legacy'; pid: number } | { kind: 'record'; record: PidRecord } {
+export function getProcessIdentityState(
+  identity: ProcessIdentity,
+  platform: NodeJS.Platform = process.platform
+): ProcessIdentityState {
+  if (!Number.isInteger(identity.pid) || identity.pid <= 0 || !Number.isSafeInteger(identity.startTime)) {
+    return 'dead';
+  }
+  if (platform === 'linux') {
+    try {
+      const stat = parseLinuxProcessStat(fs.readFileSync(`/proc/${identity.pid}/stat`, 'utf8'));
+      if (stat === null) return 'unknown';
+      if (stat.state === 'Z') return 'dead';
+      return stat.startTime === identity.startTime ? 'alive' : 'dead';
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'dead' : 'unknown';
+    }
+  }
+  try {
+    process.kill(identity.pid, 0);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ESRCH') return 'dead';
+    if (code !== 'EPERM') return 'unknown';
+  }
+  const query = buildProcessStartTimeQuery(identity.pid, platform);
+  if (query === null) return 'unknown';
+  try {
+    const output = execFileSync(query.command, query.args, {
+      encoding: 'utf8',
+      env: platform === 'darwin' ? { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } : process.env
+    }).trim();
+    if (output.length === 0) return 'unknown';
+    const startTime = platform === 'win32'
+      ? new Date(output).getTime()
+      : platform === 'darwin'
+        ? parseDarwinStartTime(output)
+        : null;
+    if (startTime === null || Number.isNaN(startTime)) return 'unknown';
+    return startTime === identity.startTime ? 'alive' : 'dead';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function parsePidRecord(
+  raw: string
+):
+  | { kind: 'legacy-json'; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-pid-only'; legacy: LegacyProcessSnapshot }
+  | { kind: 'legacy-unknown'; legacy: LegacyProcessSnapshot; reason: string }
+  | { kind: 'record'; record: PidRecord } {
   const trimmed = raw.trim();
   if (/^[1-9]\d*$/.test(trimmed)) {
     const pid = Number(trimmed);
-    return Number.isSafeInteger(pid) ? { kind: 'legacy', pid } : { kind: 'invalid' };
+    return Number.isSafeInteger(pid)
+      ? { kind: 'legacy-pid-only', legacy: { pid, raw, format: 'pid-only' } }
+      : { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'pid is not a safe integer' };
   }
   try {
-    const value = JSON.parse(trimmed) as Partial<PidRecord> | null;
+    const value = JSON.parse(trimmed) as { version?: unknown; pid?: unknown; startTime?: unknown } | null;
+    const pidValue: unknown = value?.pid;
+    const startTimeValue: unknown = value?.startTime;
     if (
       value !== null &&
-      value.version === 1 &&
-      Number.isSafeInteger(value.pid) &&
-      (value.pid ?? 0) > 0 &&
-      typeof value.startTime === 'string' &&
-      value.startTime.length > 0
+      value.version === 2 &&
+      typeof pidValue === 'number' &&
+      Number.isSafeInteger(pidValue) &&
+      pidValue > 0 &&
+      typeof startTimeValue === 'number' &&
+      Number.isSafeInteger(startTimeValue) &&
+      startTimeValue >= 0
     ) {
+      const startTime = startTimeValue as number;
       return {
         kind: 'record',
-        record: { version: 1, pid: value.pid!, startTime: value.startTime }
+        record: { version: 2, pid: pidValue, startTime }
       };
     }
+    if (
+      value !== null &&
+      value.version === 1 &&
+      typeof pidValue === 'number' &&
+      Number.isSafeInteger(pidValue) &&
+      pidValue > 0 &&
+      typeof value.startTime === 'string' &&
+      value.startTime.length > 0
+    ) {
+      return { kind: 'legacy-json', legacy: { pid: pidValue, raw, format: 'json-v1' } };
+    }
+    return { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'unsupported PID record schema' };
   } catch {
-    // Invalid JSON is an invalid PID record.
+    return { kind: 'legacy-unknown', legacy: { raw, format: 'malformed' }, reason: 'invalid PID record JSON' };
   }
-  return { kind: 'invalid' };
 }
 
 export function readProcessState(pidFile: string): ProcessState {
@@ -130,12 +231,13 @@ export function readProcessState(pidFile: string): ProcessState {
     snapshot = fs.readFileSync(pidFile, 'utf8');
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'missing', snapshot: null };
-    return { kind: 'invalid', snapshot: '' };
+    return { kind: 'legacy-unknown', snapshot: '', legacy: { raw: '', format: 'malformed' }, reason: 'PID record cannot be read' };
   }
 
   const parsed = parsePidRecord(snapshot);
-  if (parsed.kind === 'invalid') return { kind: 'invalid', snapshot };
-  if (parsed.kind === 'legacy') return { kind: 'legacy', snapshot, pid: parsed.pid };
+  if (parsed.kind === 'legacy-json') return { kind: parsed.kind, snapshot, legacy: parsed.legacy };
+  if (parsed.kind === 'legacy-pid-only') return { kind: parsed.kind, snapshot, legacy: parsed.legacy };
+  if (parsed.kind === 'legacy-unknown') return { kind: parsed.kind, snapshot, legacy: parsed.legacy, reason: parsed.reason };
 
   const currentStartTime = getProcessStartTime(parsed.record.pid);
   if (currentStartTime === null || currentStartTime !== parsed.record.startTime) {
@@ -178,6 +280,6 @@ export function removePidRecordIfMatches(pidFile: string, expected: PidRecord):
   return removePidFileIfMatches(pidFile, state.snapshot);
 }
 
-export function processIdentityMatches(record: PidRecord): boolean {
-  return getProcessStartTime(record.pid) === record.startTime;
+export function processIdentityMatches(identity: ProcessIdentity): boolean {
+  return getProcessIdentityState(identity) === 'alive';
 }

package/lib/task/activity-intent.ts

@@ -14,6 +14,7 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import type { TaskExecutionLockOptions } from './task-execution-lock.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+import { allowsManualOverride } from './guard-override.ts';
 
 type PrReviewVerdict = 'approved' | 'changes-requested' | 'commented';
 type PrReviewOutcome = 'aborted' | 'superseded';
@@ -95,7 +96,7 @@ export type PrReviewInspectionResult = {
   error: { code: string; message: string } | null;
 };
 
-type ActivityIntentOptions = TaskWriteOptions & { lockOptions?: TaskExecutionLockOptions };
+type ActivityIntentOptions = TaskWriteOptions & { lockOptions?: TaskExecutionLockOptions; lockAlreadyHeld?: boolean };
 type ArtifactRecord = { identity: ArtifactIdentity; head: string; status: PrReviewArtifactStatus };
 type RoundState = ArtifactRecord & {
   startedAgent: string | null;
@@ -397,9 +398,10 @@ export function applyPrReviewActivityIntent(intent: PrReviewActivityIntent, opti
   if ('code' in validated) return failed(intent, validated.code, validated.message);
   const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') {
+  if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'activity-intent', 'TASK_STATE_MISMATCH')) {
     return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   }
+  if (options.lockAlreadyHeld) return applyLocked(intent, validated.agent, { ...options, repoRoot: resolved.repoRoot });
   try {
     return withTaskExecutionLock(
       resolved.repoRoot,

package/lib/task/artifact-lifecycle.ts

@@ -7,6 +7,7 @@ import { locateActivityLog } from './activity-log.ts';
 import { parseImplementationInputs, selectPendingImplementationInput } from './implementation-inputs.ts';
 import { parseVerdict } from './review-artifacts.ts';
 import { extractSection, findSectionHeading } from './sections.ts';
+import { receiptForOutput, sha256File } from './artifact-receipts.ts';
 
 const artifactFamilyCatalog = [
   { family: 'analysis', sectionAliases: ['分析', 'Analysis'], heading: '分析', labels: ['需求分析报告', 'Requirements Analysis'] },
@@ -218,11 +219,7 @@ function resolveReviewedInput(
     diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, String(error)));
     return null;
   }
-  const lines = content.split(/\r?\n/);
-  const header = lines.findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
-  const referenceBlock = header >= 0 ? lines.slice(header, header + 12).join('\n') : '';
-  const candidates = [...referenceBlock.matchAll(/`([^`]+\.md)`/g)].map((match) => match[1]!);
-  const parsed = candidates.map((name) => parseArtifactName(name)).find((item) => item?.family === expectedFamily);
+  const parsed = parseReviewedInputReference(content, expectedFamily);
   if (!parsed) {
     diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${review.name} does not reference a canonical ${expectedFamily} artifact`));
     return null;
@@ -231,9 +228,16 @@ function resolveReviewedInput(
   try {
     const stat = fs.lstatSync(abs);
     if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('referenced input is not a regular file');
-    if (stat.mtimeMs > review.mtimeMs) {
-      diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${parsed.name} is newer than ${review.name}`));
-      return null;
+    const taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
+    const receipt = receiptForOutput(taskContent, review.name);
+    if (!receipt) throw new Error(`receipt for ${review.name} is missing`);
+    const expectedEvent = reviewEventName(review.family);
+    if (receipt.event !== expectedEvent || receipt.input !== parsed.name) {
+      throw new Error(`receipt for ${review.name} does not match ${parsed.name}`);
+    }
+    const actualSha256 = sha256File(abs);
+    if (actualSha256 !== receipt.inputSha256) {
+      throw new Error(`${parsed.name} content digest does not match receipt`);
     }
     return { ...parsed, path: abs, size: stat.size, mtimeMs: stat.mtimeMs };
   } catch (error) {
@@ -242,6 +246,54 @@ function resolveReviewedInput(
   }
 }
 
+function parseReviewedInputReference(content: string, expectedFamily: ArtifactFamily): { family: ArtifactFamily; round: number; name: string } | null {
+  const lines = content.split(/\r?\n/);
+  const header = lines.findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
+  const referenceBlock = header >= 0 ? lines.slice(header, header + 12).join('\n') : '';
+  const candidates = [...referenceBlock.matchAll(/`([^`]+\.md)`/g)].map((match) => match[1]!);
+  return candidates
+    .map((name) => parseArtifactName(name))
+    .find((item) => item?.family === expectedFamily) ?? null;
+}
+
+function parseCodePlanInputReference(content: string): { family: 'plan'; round: number; name: string } | null {
+  const lines = content.split(/\r?\n/);
+  const sectionStart = lines.findIndex((line) => /^##\s+(?:实现输入|Implementation Input)\s*$/.test(line.trim()));
+  if (sectionStart < 0) return null;
+  const bodyLines = lines.slice(sectionStart + 1);
+  const nextSection = bodyLines.findIndex((line) => /^##\s+/.test(line.trim()));
+  const body = (nextSection < 0 ? bodyLines : bodyLines.slice(0, nextSection)).join('\n');
+  const match = body.match(/\*\*(?:方案输入|Plan Input)\*\*[:：]\s*`([^`]+\.md)`/);
+  if (!match) return null;
+  const parsed = parseArtifactName(match[1]!);
+  return parsed?.family === 'plan' ? { ...parsed, family: 'plan' } : null;
+}
+
+function reviewEventName(family: ArtifactFamily): 'review-analysis.completed' | 'review-plan.completed' | 'review-code.completed' {
+  if (family === 'review-analysis') return 'review-analysis.completed';
+  if (family === 'review-plan') return 'review-plan.completed';
+  if (family === 'review-code') return 'review-code.completed';
+  throw new Error(`unsupported review family '${family}'`);
+}
+
+function resolveCodeInputReceipt(taskDir: string, code: ArtifactIdentity): { input: ArtifactIdentity; inputSha256: string } | null {
+  let taskContent: string;
+  try { taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8'); }
+  catch { return null; }
+  let receipt;
+  try { receipt = receiptForOutput(taskContent, code.name); }
+  catch { return null; }
+  if (!receipt || receipt.event !== 'code.completed') return null;
+  const plan = inspectArtifactDirectory(taskDir, 'plan');
+  if (plan.status !== 'ready') return null;
+  const input = plan.artifacts.find((artifact) => artifact.name === receipt.input);
+  return input ? { input, inputSha256: receipt.inputSha256 } : null;
+}
+
+function resolveCodePlanInput(taskDir: string, code: ArtifactIdentity): { input: ArtifactIdentity; inputSha256: string } | null {
+  return resolveCodeInputReceipt(taskDir, code);
+}
+
 function assertWritableInventory(inventory: ArtifactInventoryResult): ArtifactError | null {
   if (inventory.status === 'failed') return inventory.error;
   const blockers = inventory.diagnostics.filter((item) => BLOCKING_DIAGNOSTICS.has(item.code));
@@ -312,11 +364,21 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
     return withCodeMode(inventory, inputs, 'ready', 'init', codeMax, reviewMax, null, null,
       'No prior code artifact. Starting initial implementation (round 1 -> code.md).');
   }
+  const codePlanInput = resolveCodePlanInput(inventory.taskDir!, latestCode);
+  if (!codePlanInput) {
+    return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `code completion receipt for ${latestCode.name} is missing or does not match the current plan`, latestCode.name);
+  }
+  if (reviewPlan.latest && !reviewPlan.reviewedInput) {
+    return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `${reviewPlan.latest.name} has no valid reviewed input`, reviewPlan.latest.name);
+  }
   if (reviewPlan.latest && reviewPlan.reviewedInput?.name === plan.latest.name) {
     const verdict = parseVerdict(reviewPlan.latest.path);
-    if (verdict.ok && verdict.verdict === 'Approved' && reviewPlan.latest.mtimeMs > latestCode.mtimeMs) {
+    const reviewedPlanSha256 = sha256File(reviewPlan.reviewedInput.path);
+    if (verdict.ok && verdict.verdict === 'Approved' && (
+      codePlanInput.input.name !== plan.latest.name || codePlanInput.inputSha256 !== reviewedPlanSha256
+    )) {
       return withCodeMode(inventory, inputs, 'ready', 'init', codeMax, reviewMax, verdict.verdict, reviewPlan.latest.name,
-        `Latest ${reviewPlan.latest.name} is approved and newer than the latest code artifact. Entering replan-driven init.`);
+        `Latest ${reviewPlan.latest.name} approves plan content not captured by the latest code input receipt. Entering replan-driven init.`);
     }
   }
   if (reviewMax < codeMax) {
@@ -440,6 +502,7 @@ function buildArtifactLinkSection(content: string, artifact: ArtifactIdentity):
 export {
   artifactFamilyCatalog, artifactName, parseArtifactName, familySpec,
   inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext,
+  parseReviewedInputReference, parseCodePlanInputReference, resolveCodePlanInput, reviewEventName,
   assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection
 };
 export type {

package/lib/task/artifact-receipts.ts

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+
+import { extractSection, findSectionHeading, parseTable } from './sections.ts';
+
+const RECEIPT_SECTION_ALIASES = ['产物生命周期收据', 'Artifact Lifecycle Receipts'] as const;
+const RECEIPT_COLUMNS = ['event', 'output', 'input', 'input_sha256', 'completed_at'] as const;
+const RECEIPT_EVENTS = new Set([
+  'review-analysis.completed',
+  'review-plan.completed',
+  'review-code.completed',
+  'code.completed'
+]);
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const ARTIFACT_NAME_RE = /^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|validation-run|pr-review)(?:-r([2-9]|[1-9]\d+))?\.md$/;
+const RECEIPT_SHAPES = {
+  'review-analysis.completed': { output: 'review-analysis', input: 'analysis' },
+  'review-plan.completed': { output: 'review-plan', input: 'plan' },
+  'review-code.completed': { output: 'review-code', input: 'code' },
+  'code.completed': { output: 'code', input: 'plan' }
+} as const;
+
+type ArtifactReceiptEvent =
+  | 'review-analysis.completed'
+  | 'review-plan.completed'
+  | 'review-code.completed'
+  | 'code.completed';
+type ArtifactReceipt = {
+  event: ArtifactReceiptEvent;
+  output: string;
+  input: string;
+  inputSha256: string;
+  completedAt: string;
+};
+type ArtifactReceiptParseResult = {
+  present: boolean;
+  rows: readonly ArtifactReceipt[];
+};
+type ReceiptSectionMutation = {
+  aliases: readonly string[];
+  heading: string;
+  body: string;
+};
+
+class ArtifactReceiptError extends Error {
+  readonly code = 'ARTIFACT_RECEIPT_INVALID';
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ArtifactReceiptError';
+  }
+}
+
+function sha256Bytes(value: Buffer): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function sha256File(filePath: string): string {
+  return sha256Bytes(fs.readFileSync(filePath));
+}
+
+function parseReceiptArtifactName(name: string): { family: string } | null {
+  const match = ARTIFACT_NAME_RE.exec(name);
+  if (!match) return null;
+  const roundText = match[2];
+  if (roundText !== undefined) {
+    const round = Number(roundText);
+    if (!Number.isSafeInteger(round) || String(round) !== roundText) return null;
+  }
+  return { family: match[1]! };
+}
+
+function validateReceiptShape(event: ArtifactReceiptEvent, output: string, input: string): void {
+  const outputIdentity = parseReceiptArtifactName(output);
+  const inputIdentity = parseReceiptArtifactName(input);
+  if (!outputIdentity || !inputIdentity) throw new ArtifactReceiptError(`receipt artifact identity is invalid: ${output} -> ${input}`);
+  const shape = RECEIPT_SHAPES[event];
+  if (outputIdentity.family !== shape.output || inputIdentity.family !== shape.input) {
+    throw new ArtifactReceiptError(`receipt event '${event}' does not match ${output} -> ${input}`);
+  }
+}
+
+function parseArtifactReceipts(content: string): ArtifactReceiptParseResult {
+  const section = extractSection(content, [...RECEIPT_SECTION_ALIASES]);
+  if (!section) return { present: false, rows: [] };
+
+  let table;
+  try {
+    table = parseTable(content, {
+      sectionAliases: [...RECEIPT_SECTION_ALIASES],
+      columns: [...RECEIPT_COLUMNS],
+      keyColumn: 'output'
+    });
+  } catch (error) {
+    throw new ArtifactReceiptError(error instanceof Error ? error.message : String(error));
+  }
+  if (!table) throw new ArtifactReceiptError('receipt section has no receipt table');
+
+  const rows = table.rows.map((row) => {
+    const event = row.values.event ?? '';
+    const output = row.values.output ?? '';
+    const input = row.values.input ?? '';
+    const inputSha256 = row.values.input_sha256 ?? '';
+    const completedAt = row.values.completed_at ?? '';
+    if (!RECEIPT_EVENTS.has(event)) throw new ArtifactReceiptError(`unknown receipt event '${event}'`);
+    if (!output || !input) throw new ArtifactReceiptError('receipt output and input are required');
+    validateReceiptShape(event as ArtifactReceiptEvent, output, input);
+    if (!SHA256_RE.test(inputSha256)) throw new ArtifactReceiptError(`receipt digest for '${output}' is invalid`);
+    if (!completedAt || Number.isNaN(Date.parse(completedAt.replace(' ', 'T')))) {
+      throw new ArtifactReceiptError(`receipt completion time for '${output}' is invalid`);
+    }
+    return {
+      event: event as ArtifactReceiptEvent,
+      output,
+      input,
+      inputSha256,
+      completedAt
+    };
+  });
+  return { present: true, rows };
+}
+
+function receiptForOutput(content: string, output: string): ArtifactReceipt | null {
+  const parsed = parseArtifactReceipts(content);
+  return parsed.rows.find((row) => row.output === output) ?? null;
+}
+
+function upsertArtifactReceipt(content: string, receipt: ArtifactReceipt): ReceiptSectionMutation {
+  if (!RECEIPT_EVENTS.has(receipt.event)) throw new ArtifactReceiptError(`unknown receipt event '${receipt.event}'`);
+  if (!receipt.output || !receipt.input) throw new ArtifactReceiptError('receipt output and input are required');
+  validateReceiptShape(receipt.event, receipt.output, receipt.input);
+  if (!SHA256_RE.test(receipt.inputSha256)) throw new ArtifactReceiptError(`receipt digest for '${receipt.output}' is invalid`);
+  if (!receipt.completedAt || Number.isNaN(Date.parse(receipt.completedAt.replace(' ', 'T')))) {
+    throw new ArtifactReceiptError(`receipt completion time for '${receipt.output}' is invalid`);
+  }
+
+  const existing = parseArtifactReceipts(content).rows;
+  const previous = existing.find((row) => row.output === receipt.output);
+  if (previous && JSON.stringify(previous) !== JSON.stringify(receipt)) {
+    throw new ArtifactReceiptError(`receipt for '${receipt.output}' already exists with different evidence`);
+  }
+  const rows = previous ? existing : [...existing, receipt];
+  const heading = findSectionHeading(content, [...RECEIPT_SECTION_ALIASES]);
+  const body = [
+    `| ${RECEIPT_COLUMNS.join(' | ')} |`,
+    `| ${RECEIPT_COLUMNS.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => `| ${row.event} | ${row.output} | ${row.input} | ${row.inputSha256} | ${row.completedAt} |`)
+  ].join('\n');
+  return { aliases: [...RECEIPT_SECTION_ALIASES], heading, body };
+}
+
+export {
+  ArtifactReceiptError,
+  RECEIPT_SECTION_ALIASES,
+  parseArtifactReceipts,
+  receiptForOutput,
+  sha256Bytes,
+  sha256File,
+  upsertArtifactReceipt
+};
+export type { ArtifactReceipt, ArtifactReceiptEvent, ArtifactReceiptParseResult, ReceiptSectionMutation };