@fitlab-ai/agent-infra 0.9.1 → 0.9.3

package/lib/task/activity-intent.ts

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { resolveTaskRef } from './resolve-ref.ts';
+import { locateActivityLog, appendActivityEntry } from './activity-log.ts';
+import { buildArtifactLinkSection, parseArtifactName } from './artifact-lifecycle.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+
+export type ActivityAppendIntent = {
+  kind: 'append';
+  taskRef: string;
+  step: string;
+  agent: string;
+  note: string;
+  artifact?: string;
+  dryRun?: boolean;
+};
+
+export type ActivityIntentResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  intent: 'append';
+  taskId: string | null;
+  artifact: string | null;
+  operations: readonly TaskOperationSummary[];
+  error: { code: string; message: string } | null;
+};
+
+function failed(intent: ActivityAppendIntent, code: string, message: string, taskId: string | null = null): ActivityIntentResult {
+  return {
+    status: 'failed', changed: false, intent: 'append', taskId,
+    artifact: intent.artifact ?? null, operations: [], error: { code, message }
+  };
+}
+
+function oneLine(value: string): string {
+  return value.replace(/\s*\r?\n\s*/g, ' ').trim();
+}
+
+/**
+ * Append an Activity Log entry (and, optionally, a `## 审查反馈` artifact link)
+ * to an active task via the atomic `writeTask` path. `current_step` is never
+ * touched (PL-2): review-pr does not join the standard stage chain.
+ */
+export function applyActivityAppendIntent(intent: ActivityAppendIntent, options: TaskWriteOptions = {}): ActivityIntentResult {
+  if (intent.kind !== 'append') return failed(intent, 'ACTIVITY_INTENT_INVALID', 'intent kind must be append');
+  const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
+  if (resolved.state !== 'active') {
+    return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  }
+  const step = oneLine(intent.step);
+  const agent = oneLine(intent.agent);
+  const note = oneLine(intent.note);
+  if (!step || !agent || !note || /[\r\n]/.test(intent.step) || /[\r\n]/.test(intent.agent) || /[\r\n]/.test(intent.note)) {
+    return failed(intent, 'ACTIVITY_INTENT_INVALID', 'step, agent and note must be non-empty single-line values', resolved.taskId);
+  }
+
+  let artifact: ReturnType<typeof parseArtifactName> | null = null;
+  if (intent.artifact !== undefined) {
+    artifact = parseArtifactName(intent.artifact);
+    if (!artifact || artifact.family !== 'pr-review') {
+      return failed(intent, 'ACTIVITY_ARTIFACT_INVALID', `artifact '${intent.artifact}' is not a canonical pr-review artifact`, resolved.taskId);
+    }
+  }
+
+  let content: string;
+  try {
+    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  } catch (error) {
+    return failed(intent, 'TASK_READ_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
+  const section = locateActivityLog(content);
+  if (!section) {
+    return failed(intent, 'ACTIVITY_SECTION_MISSING', 'task has no unique Activity Log section', resolved.taskId);
+  }
+
+  let metadata;
+  try {
+    metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+  } catch (error) {
+    return failed(intent, 'METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
+
+  const mutations: TaskMutation[] = [];
+  const activityBody = appendActivityEntry(section, { time: metadata.timestamp, step, agent, note });
+  mutations.push({ kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: section.heading, body: activityBody });
+  if (artifact) {
+    const link = buildArtifactLinkSection(content, {
+      ...artifact,
+      path: path.join(resolved.taskDir, artifact.name),
+      size: 0,
+      mtimeMs: 0
+    });
+    mutations.push({ kind: 'section', aliases: link.aliases, heading: link.heading, body: link.body });
+  }
+
+  const writeResult = writeTask({
+    taskRef: intent.taskRef,
+    expectedState: 'active',
+    mutations,
+    dryRun: intent.dryRun
+  }, {
+    ...options,
+    taskLocation: {
+      repoRoot: resolved.repoRoot,
+      taskId: resolved.taskId,
+      taskMdPath: resolved.taskMdPath,
+      state: resolved.state
+    },
+    metadataProvider: () => metadata
+  });
+  if (writeResult.status === 'failed') {
+    return failed(intent, writeResult.error.code, writeResult.error.message, writeResult.taskId);
+  }
+  return {
+    status: writeResult.status,
+    changed: writeResult.changed,
+    intent: 'append',
+    taskId: writeResult.taskId,
+    artifact: intent.artifact ?? null,
+    operations: writeResult.operations,
+    error: null
+  };
+}
+
+export type { TaskWriteOptions } from './write.ts';

package/lib/task/artifact-lifecycle.ts

@@ -5,6 +5,7 @@ import { resolveTaskRef } from './resolve-ref.ts';
 import type { ResolveTaskRefErrorCode, TaskWorkspaceState } from './resolve-ref.ts';
 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';
 
 const artifactFamilyCatalog = [
@@ -14,7 +15,8 @@ const artifactFamilyCatalog = [
   { family: 'review-plan', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['技术方案审查', 'Plan Review'] },
   { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
   { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
-  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] }
+  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
+  { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
 ] as const;
 
 type ArtifactFamily = (typeof artifactFamilyCatalog)[number]['family'];
@@ -239,21 +241,6 @@ function resolveReviewedInput(
   }
 }
 
-function extractMarkdownSection(content: string, names: readonly string[]): string {
-  const lines = content.split(/\r?\n/);
-  const allowed = new Set(names);
-  const start = lines.findIndex((line) => {
-    const match = /^##\s+(.+?)\s*$/.exec(line.trim());
-    return Boolean(match?.[1] && allowed.has(match[1]));
-  });
-  if (start === -1) return '';
-  let end = lines.length;
-  for (let index = start + 1; index < lines.length; index += 1) {
-    if (/^##\s+/.test(lines[index]!)) { end = index; break; }
-  }
-  return lines.slice(start + 1, end).join('\n');
-}
-
 function assertWritableInventory(inventory: ArtifactInventoryResult): ArtifactError | null {
   if (inventory.status === 'failed') return inventory.error;
   const blockers = inventory.diagnostics.filter((item) => BLOCKING_DIAGNOSTICS.has(item.code));
@@ -398,29 +385,6 @@ function resolveDecisionImplementationInput(
   catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
 }
 
-function normalizeVerdict(value: string): 'Approved' | 'Changes Requested' | 'Rejected' | null {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === '通过' || normalized === 'approved') return 'Approved';
-  if (normalized === '需要修改' || normalized === 'changes requested') return 'Changes Requested';
-  if (normalized === '拒绝' || normalized === 'rejected') return 'Rejected';
-  return null;
-}
-
-function parseVerdict(file: string): { ok: true; verdict: string } | { ok: false; message: string } {
-  let content: string;
-  try { content = fs.readFileSync(file, 'utf8'); }
-  catch (error) { return { ok: false, message: String(error) }; }
-  const summary = extractMarkdownSection(content, ['审查摘要', 'Review Summary']);
-  const verdictMatch = /^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.+?)\s*$/im.exec(summary);
-  const verdict = verdictMatch?.[1] ? normalizeVerdict(verdictMatch[1]) : null;
-  if (!verdict) return { ok: false, message: `cannot parse verdict in ${path.basename(file)}` };
-  if (verdict !== 'Approved') return { ok: true, verdict };
-  const findings = /^[-*]?\s*\*\*(?:发现（AI 可处理）|Findings \(AI-actionable\))\*\*[:：]\s*(.+?)\s*$/im.exec(summary)?.[1];
-  const counts = findings?.match(/(\d+)\s*(?:阻塞项|blockers?).*?(\d+)\s*(?:主要|majors?).*?(\d+)\s*(?:次要|minors?)/i);
-  if (!counts) return { ok: false, message: `cannot parse findings count in ${path.basename(file)}` };
-  return { ok: true, verdict: counts.slice(1).some((value) => Number(value) > 0) ? 'Approved-with-issues' : 'Approved' };
-}
-
 function validateCompletedArtifact(taskDir: string, family: ArtifactFamily, name: string, round?: number): { ok: true; artifact: ArtifactIdentity } | { ok: false; error: ArtifactError } {
   if (path.basename(name) !== name) return { ok: false, error: { code: 'ARTIFACT_PATH_INVALID', message: 'artifact must be a top-level basename' } };
   const parsed = parseArtifactName(name);

package/lib/task/commands/decisions.ts

@@ -10,8 +10,9 @@ import { extractSubSection } from '../sections.ts';
 const USAGE = `Usage: ai task decisions [--task <ref> | -t <ref>] [--item <selector> | -i <selector>] [options]
        ai task decisions <ref> [selector] [options]
 
-Lists decision items recorded in a task's review disagreement
-ledger, or prints the full detail block for a single item. Read-only.
+Shows what still needs a maintainer's decision. Without a selector, it lists
+the choices. With a selector, it shows the explanation and how to respond.
+Read-only.
 
   Omit <ref>     Resolve the unique active task for the current branch.
   <ref>          Legacy positional task ref.
@@ -150,29 +151,31 @@ function findDecisionRecord(id: string, content: string): string[] {
 function titleOf(row: LedgerRow, taskDir: string): string {
   const block = findDetailBlock(row, taskDir);
   if (block) {
-    return block
+    const title = block
       .split('\n')[0]!
       .replace(/^###\s+/, '')
       .replace(/\s*\[needs-human-decision\]\s*$/, '')
       .trim();
+    return title.replace(new RegExp(`^${row.id}\\s*[:：]\\s*`, 'i'), '').trim();
   }
-  return row.evidence || '(无详情)';
+  return '(explanation unavailable)';
+}
+
+function trackingOf(row: LedgerRow): string {
+  return `stage=${row.stage} · severity=${row.severity} · status=${row.status} · evidence=${row.evidence}`;
 }
 
 function renderList(rows: LedgerRow[], format: string, taskDir: string): void {
   if (rows.length === 0) {
-    process.stdout.write('无待裁决项。\n');
+    process.stdout.write('No pending decisions.\n');
     return;
   }
-  const headers = ['#', 'ID', 'STAGE', 'SEVERITY', 'STATUS', 'EVIDENCE', 'TITLE'];
+  const headers = ['#', 'CHOICE', 'WHAT NEEDS A DECISION', 'TRACKING'];
   const data = rows.map((r, i) => [
     String(i + 1),
     r.id,
-    r.stage,
-    r.severity,
-    r.status,
-    r.evidence,
-    titleOf(r, taskDir)
+    titleOf(r, taskDir),
+    trackingOf(r)
   ]);
   if (format === 'markdown') {
     const sep = headers.map(() => '---');
@@ -181,10 +184,29 @@ function renderList(rows: LedgerRow[], format: string, taskDir: string): void {
       `| ${sep.join(' | ')} |`,
       ...data.map((row) => `| ${row.join(' | ')} |`)
     ];
-    process.stdout.write(`${md.join('\n')}\n`);
+    process.stdout.write(`${md.join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
     return;
   }
-  process.stdout.write(`${formatTable(headers, data).join('\n')}\n`);
+  process.stdout.write(`${formatTable(headers, data).join('\n')}\n\nView one item: ai task decisions <task-ref> <ordinal|ledger-id>\n`);
+}
+
+function renderTracking(row: LedgerRow, format: string): string[] {
+  if (format === 'markdown') {
+    return [
+      '**Tracking**',
+      `- stage: \`${row.stage}\``,
+      `- severity: \`${row.severity}\``,
+      `- status: \`${row.status}\``,
+      `- evidence: \`${row.evidence}\``
+    ];
+  }
+  return [
+    'Tracking:',
+    `stage: ${row.stage}`,
+    `severity: ${row.severity}`,
+    `status: ${row.status}`,
+    `evidence: ${row.evidence}`
+  ];
 }
 
 function renderDetail(
@@ -201,25 +223,36 @@ function renderDetail(
   }
   const r = selected.row;
   const block = findDetailBlock(r, taskDir);
+  const title = titleOf(r, taskDir);
   const lines: string[] = [];
+  const decided = r.status === 'human-decided';
   if (format === 'markdown') {
-    lines.push(`**${r.id}** (${r.stage}/${r.severity}) · status=\`${r.status}\` · evidence: \`${r.evidence}\``, '');
+    lines.push(`## ${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
+    if (!decided) {
+      lines.push('**How to record your choice**', `\`ai decide <task-ref> ${r.id} <your choice and rationale>\``, '');
+    }
+    lines.push('**Original context**', '');
   } else {
-    lines.push(`${r.id} (${r.stage}/${r.severity}) status=${r.status}`, `evidence: ${r.evidence}`, '');
+    lines.push(`${decided ? 'Decision already recorded' : 'Decision needed'}: ${title}`, '');
+    if (!decided) {
+      lines.push('How to record your choice:', `ai decide <task-ref> ${r.id} <your choice and rationale>`, '');
+    }
+    lines.push('Original context:');
   }
   if (block) {
     lines.push(block);
   } else {
     lines.push(
-      `（详情块未找到：未在任务产物中定位到 \`### ${r.id}\` 锚点，可能为历史产物或尚未写入；evidence 指向 ${r.evidence}）`
+      `This older task does not include a full explanation for ${r.id}.`,
+      'Use the tracking reference below to find the original context.'
     );
   }
-  if (r.status === 'human-decided') {
+  if (decided) {
     const record = findDecisionRecord(r.id, content);
-    if (record.length) {
-      lines.push('', '人工裁定：', ...record);
-    }
+    lines.push('', format === 'markdown' ? '**Recorded choice**' : 'Recorded choice:');
+    lines.push(...(record.length ? record : ['No separate ruling record was found.']));
   }
+  lines.push('', ...renderTracking(r, format));
   process.stdout.write(`${lines.join('\n')}\n`);
 }
 

package/lib/task/commands/log.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { classifyAgent } from '../../agent-clients/tokens.ts';
 import { formatTable } from '../../table.ts';
 import { parseTaskScope } from '../command-options.ts';
 import { resolveTaskContext } from '../resolve-ref.ts';
@@ -34,11 +35,11 @@ const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'] as const
 // with ` [started]`; the matching done entry carries the identical base action
 // without the suffix. Pairing therefore keys on the base action (including any
 // `(Round N)`), so every round and every repeated execution pairs on its own.
-// Short agent tokens that actually appear in activity logs for AI executors
-// (workflow recommended_agents claude/codex/gemini/cursor + enabled TUI opencode;
-// note these differ from the `.airc.json` long names claude-code/gemini-cli).
-// Any other executor token (a human name, possibly CJK) is treated as human.
-const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'gemini', 'opencode', 'cursor']);
+// Known AI tokens, long-name mapping, and loose rendering classification live
+// in lib/agent-clients/tokens.ts (single source of truth shared with the
+// write-side internal commands). Any other executor token (a human name,
+// possibly CJK, or an unknown value) is rendered as human with a visible
+// `(unknown)` marker.
 const REVIEW_STAGE_PREFIXES: { prefix: string; stage: ReviewStage }[] = [
   { prefix: 'Review Analysis', stage: 'analysis' },
   { prefix: 'Review Plan', stage: 'plan' },
@@ -90,12 +91,11 @@ function isHumanCountField(field: string): boolean {
   return fieldNumber(field, 'manual-validation') !== undefined || fieldNumber(field, 'human-decision') !== undefined;
 }
 
-// A step is human-executed when its agent token is not a known AI token. Take
-// the first whitespace-delimited token and drop any trailing parenthetical
-// annotation (e.g. `张三 (executed on host)` -> `张三`) before the lookup.
-function isHumanAgent(agent: string): boolean {
-  const token = agent.trim().split(/\s+/)[0]?.replace(/\(.*$/, '') ?? '';
-  return token !== '' && !KNOWN_AI_AGENTS.has(token);
+// A step is human-executed when its agent token is not a known AI token.
+// Known long names (claude-code -> claude, gemini-cli -> gemini) classify as
+// AI; empty or unknown tokens classify as non-AI (human).
+export function isHumanAgent(agent: string): boolean {
+  return classifyAgent(agent).status !== 'ai';
 }
 
 // Fold the two human counts into a review row's verdict NOTE: comma-joined, right
@@ -152,8 +152,9 @@ function log(args: string[] = []): void {
     const note = stage
       ? foldHumanCounts(s.note, humanDecisionCounts.get(stage) ?? 0, humanValidationCount(s.note))
       : s.note;
-    const human = isHumanAgent(s.agent);
-    const agent = human ? 'human' : s.agent;
+    const { status, display } = classifyAgent(s.agent);
+    const human = status !== 'ai';
+    const agent = status === 'unknown' ? `${display} (unknown)` : display;
     const started = s.started || (human ? '-' : '');
     return [String(idx + 1), s.step, agent, started, s.done || (s.started ? '(in progress)' : ''), note];
   });
@@ -163,4 +164,4 @@ function log(args: string[] = []): void {
   process.stdout.write(`Total: ${steps.length} steps\n`);
 }
 
-export { log, isHumanAgent };
+export { log };

package/lib/task/delegation-receipts.ts

@@ -0,0 +1,199 @@
+import { randomUUID } from 'node:crypto';
+
+import type { AgentClientId } from '../agent-clients/types.ts';
+
+type DelegationRole = 'executor' | 'reviewer';
+type DelegationStage = 'analysis' | 'review-analysis' | 'plan' | 'review-plan' | 'code' | 'review-code' | 'commit';
+type DelegationStatus = 'prepared' | 'activated' | 'stage-completed' | 'sealed' | 'consumed' | 'aborted' | 'expired';
+
+type DelegationReceipt = Readonly<{
+  id: string;
+  taskId: string;
+  runId: string;
+  role: DelegationRole;
+  stage: DelegationStage;
+  round: number;
+  artifact: string;
+  client: AgentClientId;
+  requestedModel: string | null;
+  requestedReasoningEffort: string | null;
+  actualModel: string | null;
+  actualReasoningEffort: string | null;
+  modelFallbackReason: string | null;
+  reasoningEffortFallbackReason: string | null;
+  parentId: string | null;
+  childId: string | null;
+  spawnMode: string | null;
+  agent: string | null;
+  status: DelegationStatus;
+  workspaceSnapshotScope?: 'task';
+  beforeFingerprint: string;
+  afterFingerprint: string | null;
+  changedPaths: readonly string[];
+  createdAt: string;
+  activatedAt: string | null;
+  sealedAt: string | null;
+  consumedAt: string | null;
+}>;
+
+type ReceiptFailure = Readonly<{ ok: false; code: string; message: string; receipt?: never }>;
+type ReceiptSuccess = Readonly<{ ok: true; receipt: DelegationReceipt; code?: never; message?: never }>;
+type ReceiptResult = ReceiptSuccess | ReceiptFailure;
+
+const MANAGED_AGENTS = {
+  'agent-infra-lifecycle-executor': 'executor',
+  'agent-infra-lifecycle-reviewer': 'reviewer'
+} as const;
+
+function managedDelegationRole(nativeAgent: string): DelegationRole | null {
+  return MANAGED_AGENTS[nativeAgent as keyof typeof MANAGED_AGENTS] ?? null;
+}
+
+function fail(code: string, message: string): ReceiptFailure {
+  return { ok: false, code, message };
+}
+
+function prepareDelegation(
+  input: Omit<DelegationReceipt, 'id' | 'requestedModel' | 'requestedReasoningEffort' | 'actualModel' | 'actualReasoningEffort' | 'modelFallbackReason' | 'reasoningEffortFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'> & Readonly<{ requestedModel: string; requestedReasoningEffort: string }>,
+  options: { id?: () => string; now?: () => string } = {}
+): DelegationReceipt {
+  return Object.freeze({
+    ...input,
+    id: (options.id ?? randomUUID)(),
+    actualModel: null,
+    actualReasoningEffort: null,
+    modelFallbackReason: null,
+    reasoningEffortFallbackReason: null,
+    parentId: null,
+    childId: null,
+    spawnMode: null,
+    agent: null,
+    status: 'prepared' as const,
+    afterFingerprint: null,
+    changedPaths: Object.freeze([]),
+    createdAt: (options.now ?? (() => new Date().toISOString()))(),
+    activatedAt: null,
+    sealedAt: null,
+    consumedAt: null
+  });
+}
+
+function activateDelegation(
+  receipt: DelegationReceipt,
+  event: Readonly<{
+    nativeAgent: string;
+    childId: string;
+    parentId: string;
+    spawnMode: string;
+    actualModel?: string;
+    actualReasoningEffort?: string;
+    modelFallbackReason?: string;
+    reasoningEffortFallbackReason?: string;
+  }>,
+  options: { now?: () => string } = {}
+): ReceiptResult {
+  const managedRole = managedDelegationRole(event.nativeAgent);
+  if (!managedRole) return fail('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
+  if (receipt.status !== 'prepared') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected prepared`);
+  if (managedRole !== receipt.role) return fail('DELEGATION_ROLE_MISMATCH', `managed role ${managedRole} does not match ${receipt.role}`);
+  if (!event.parentId || (receipt.parentId !== null && event.parentId !== receipt.parentId) || !event.childId || event.childId === event.parentId) {
+    return fail('DELEGATION_IDENTITY_INVALID', 'native parent/child identity does not match the prepared delegation');
+  }
+  if (event.spawnMode !== 'fresh') return fail('DELEGATION_FORK_FORBIDDEN', `spawn mode '${event.spawnMode}' is not fresh`);
+  const actualModel = event.actualModel;
+  if (!actualModel || actualModel.trim() !== actualModel) {
+    return fail('DELEGATION_MODEL_IDENTITY_MISSING', 'native start event must provide a non-empty actual model identity');
+  }
+  if (actualModel !== receipt.requestedModel && (!event.modelFallbackReason || event.modelFallbackReason.trim() === '')) {
+    return fail('DELEGATION_MODEL_FALLBACK_UNRECORDED', 'actual model differs from requested model without a fallback reason');
+  }
+  const actualReasoningEffort = event.actualReasoningEffort;
+  if (!actualReasoningEffort || actualReasoningEffort.trim() !== actualReasoningEffort) {
+    return fail('DELEGATION_REASONING_EFFORT_MISSING', 'native start event must provide a non-empty actual reasoning effort');
+  }
+  if (
+    actualReasoningEffort !== receipt.requestedReasoningEffort
+    && (!event.reasoningEffortFallbackReason || event.reasoningEffortFallbackReason.trim() === '')
+  ) {
+    return fail('DELEGATION_REASONING_EFFORT_FALLBACK_UNRECORDED', 'actual reasoning effort differs from requested effort without a fallback reason');
+  }
+  if (actualModel === receipt.requestedModel && event.modelFallbackReason) {
+    return fail('DELEGATION_MODEL_FALLBACK_INVALID', 'model fallback reason is only valid when actual model differs');
+  }
+  if (actualReasoningEffort === receipt.requestedReasoningEffort && event.reasoningEffortFallbackReason) {
+    return fail('DELEGATION_REASONING_EFFORT_FALLBACK_INVALID', 'reasoning-effort fallback reason is only valid when actual effort differs');
+  }
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'activated',
+    parentId: event.parentId,
+    childId: event.childId,
+    spawnMode: event.spawnMode,
+    actualModel,
+    actualReasoningEffort,
+    modelFallbackReason: event.modelFallbackReason ?? null,
+    reasoningEffortFallbackReason: event.reasoningEffortFallbackReason ?? null,
+    activatedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+function completeDelegationStage(
+  receipt: DelegationReceipt,
+  event: Readonly<{ stage: DelegationStage; round: number; artifact: string; agent: string }>
+): ReceiptResult {
+  if (receipt.status !== 'activated') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected activated`);
+  if (event.stage !== receipt.stage || event.round !== receipt.round || event.artifact !== receipt.artifact) {
+    return fail('DELEGATION_STAGE_MISMATCH', 'stage completion identity does not match the active delegation');
+  }
+  const acceptedAgents = receipt.client === 'claude-code' ? ['claude', 'claude-code'] : [receipt.client];
+  if (!acceptedAgents.includes(event.agent)) {
+    return fail('DELEGATION_AGENT_MISMATCH', `stage agent '${event.agent}' does not match client '${receipt.client}'`);
+  }
+  return { ok: true, receipt: Object.freeze({ ...receipt, status: 'stage-completed', agent: event.agent }) };
+}
+
+function sealDelegation(
+  receipt: DelegationReceipt,
+  event: Readonly<{ childId: string; exitCode: number; afterFingerprint: string; changedPaths: readonly string[] }>,
+  options: { now?: () => string } = {}
+): ReceiptResult {
+  if (receipt.status !== 'stage-completed') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected stage-completed`);
+  if (event.childId !== receipt.childId || event.exitCode !== 0) return fail('DELEGATION_STOP_INVALID', 'native stop identity or exit status is invalid');
+  if (receipt.role === 'reviewer') {
+    const taskRoot = `.agents/workspace/active/${receipt.taskId}/`;
+    const allowed = new Set([
+      `${taskRoot}${receipt.artifact}`,
+      `${taskRoot}task.md`,
+      `${taskRoot}orchestration.json`
+    ]);
+    const disallowed = event.changedPaths.find((entry) => !allowed.has(entry));
+    if (disallowed) return fail('DELEGATION_REVIEWER_WRITE_FORBIDDEN', `reviewer changed forbidden path '${disallowed}'`);
+  }
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'sealed',
+    afterFingerprint: event.afterFingerprint,
+    changedPaths: Object.freeze([...event.changedPaths]),
+    sealedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+function consumeDelegation(receipt: DelegationReceipt, options: { now?: () => string } = {}): ReceiptResult {
+  if (receipt.status === 'consumed') return fail('DELEGATION_REPLAY', `delegation ${receipt.id} was already consumed`);
+  if (receipt.status !== 'sealed') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected sealed`);
+  return { ok: true, receipt: Object.freeze({
+    ...receipt,
+    status: 'consumed',
+    consumedAt: (options.now ?? (() => new Date().toISOString()))()
+  }) };
+}
+
+export {
+  activateDelegation,
+  completeDelegationStage,
+  consumeDelegation,
+  managedDelegationRole,
+  prepareDelegation,
+  sealDelegation
+};
+export type { DelegationReceipt, DelegationRole, DelegationStage, DelegationStatus, ReceiptResult };