@fitlab-ai/agent-infra 0.9.4 → 0.9.6

package/lib/task/create.ts

@@ -0,0 +1,372 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { loadShortIdByTaskId, mutateShortIdRegistry } from './short-id.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
+
+const AGENTS = ['claude', 'codex', 'antigravity', 'opencode', 'cursor'] as const;
+const TYPES = ['feature', 'bugfix', 'refactor', 'docs', 'chore'] as const;
+const PRIORITIES = ['Urgent', 'High', 'Medium', 'Low'] as const;
+const EFFORTS = ['High', 'Medium', 'Low'] as const;
+const TASK_INPUT_KEYS = [
+  'sources', 'facts', 'constraints', 'decisions', 'alternatives',
+  'acceptanceCriteria', 'openQuestions'
+] as const;
+
+type TaskAgent = typeof AGENTS[number];
+type TaskType = typeof TYPES[number];
+type TaskPriority = typeof PRIORITIES[number];
+type TaskEffort = typeof EFFORTS[number];
+
+type TaskCreateCandidateV1 = Readonly<{
+  version: 1;
+  idempotencyKey: string;
+  agent: TaskAgent;
+  title: string;
+  type: TaskType;
+  branchSlug: string;
+  priority: TaskPriority;
+  effort: TaskEffort;
+  description: string;
+  taskInput: Readonly<Record<typeof TASK_INPUT_KEYS[number], readonly string[]>>;
+}>;
+
+type LocalTaskCreateResult = Readonly<{
+  status: 'applied' | 'no-op';
+  changed: boolean;
+  task: { id: string; shortId: string };
+}>;
+
+type LocalTaskCreateOptions = Readonly<{
+  repoRoot: string;
+  now?: () => Date;
+  agentInfraVersion?: string;
+}>;
+
+function payloadError(message: string): never {
+  throw new Error(`TASK_CREATE_PAYLOAD_INVALID: ${message}`);
+}
+
+function exactKeys(value: Record<string, unknown>, expected: readonly string[], label: string): void {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    payloadError(`${label} has unknown or missing fields`);
+  }
+}
+
+function cleanString(value: unknown, label: string, maxBytes: number, oneLine = false): string {
+  if (typeof value !== 'string' || value.length === 0 || Buffer.byteLength(value, 'utf8') > maxBytes) {
+    payloadError(`${label} must be a non-empty string within ${maxBytes} bytes`);
+  }
+  if (/\0|[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/u.test(value) || (oneLine && /[\r\n]/u.test(value))) {
+    payloadError(`${label} contains unsupported control characters`);
+  }
+  return value;
+}
+
+function enumValue<T extends string>(value: unknown, allowed: readonly T[], label: string): T {
+  if (typeof value !== 'string' || !allowed.includes(value as T)) payloadError(`${label} is invalid`);
+  return value as T;
+}
+
+function validateTaskCreateCandidate(value: unknown): TaskCreateCandidateV1 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) payloadError('candidate must be an object');
+  const candidate = value as Record<string, unknown>;
+  exactKeys(candidate, [
+    'version', 'idempotencyKey', 'agent', 'title', 'type', 'branchSlug',
+    'priority', 'effort', 'description', 'taskInput'
+  ], 'candidate');
+  if (candidate.version !== 1) payloadError('version must be 1');
+  const idempotencyKey = cleanString(candidate.idempotencyKey, 'idempotencyKey', 64, true);
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(idempotencyKey)) {
+    payloadError('idempotencyKey must be a UUID v4');
+  }
+  const title = cleanString(candidate.title, 'title', 400, true);
+  if ([...title].length > 100) payloadError('title exceeds 100 Unicode code points');
+  const branchSlug = cleanString(candidate.branchSlug, 'branchSlug', 64, true);
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)+$/.test(branchSlug) || branchSlug.length < 3) {
+    payloadError('branchSlug must be lowercase ASCII kebab-case with length 3-64');
+  }
+  const description = cleanString(candidate.description, 'description', 8 * 1024);
+  if (!candidate.taskInput || typeof candidate.taskInput !== 'object' || Array.isArray(candidate.taskInput)) {
+    payloadError('taskInput must be an object');
+  }
+  const rawInput = candidate.taskInput as Record<string, unknown>;
+  exactKeys(rawInput, TASK_INPUT_KEYS, 'taskInput');
+  const taskInput = Object.fromEntries(TASK_INPUT_KEYS.map((key) => {
+    const list = rawInput[key];
+    if (!Array.isArray(list) || list.length > 50) payloadError(`taskInput.${key} must contain at most 50 items`);
+    return [key, list.map((item, index) => cleanString(item, `taskInput.${key}[${index}]`, 2 * 1024, true))];
+  })) as unknown as TaskCreateCandidateV1['taskInput'];
+  return {
+    version: 1,
+    idempotencyKey,
+    agent: enumValue(candidate.agent, AGENTS, 'agent'),
+    title,
+    type: enumValue(candidate.type, TYPES, 'type'),
+    branchSlug,
+    priority: enumValue(candidate.priority, PRIORITIES, 'priority'),
+    effort: enumValue(candidate.effort, EFFORTS, 'effort'),
+    description,
+    taskInput
+  };
+}
+
+function canonicalTaskCreateCandidate(candidate: TaskCreateCandidateV1): string {
+  const valid = validateTaskCreateCandidate(candidate);
+  return JSON.stringify({
+    version: valid.version,
+    idempotencyKey: valid.idempotencyKey,
+    agent: valid.agent,
+    title: valid.title,
+    type: valid.type,
+    branchSlug: valid.branchSlug,
+    priority: valid.priority,
+    effort: valid.effort,
+    description: valid.description,
+    taskInput: Object.fromEntries(TASK_INPUT_KEYS.map((key) => [key, valid.taskInput[key]]))
+  });
+}
+
+function sha256(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function formatTimestamp(date: Date): string {
+  const pad = (value: number) => String(value).padStart(2, '0');
+  const offsetMinutes = -date.getTimezoneOffset();
+  const sign = offsetMinutes >= 0 ? '+' : '-';
+  const offset = Math.abs(offsetMinutes);
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}${sign}${pad(Math.floor(offset / 60))}:${pad(offset % 60)}`;
+}
+
+function taskIdFor(date: Date): string {
+  const pad = (value: number) => String(value).padStart(2, '0');
+  return `TASK-${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function yamlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function markdownBlock(value: string): string {
+  return value.split(/\r?\n/).map((line) => /^(?:#{1,6}\s|```)/.test(line) ? `\\${line}` : line).join('\n');
+}
+
+function renderList(items: readonly string[]): string {
+  return items.map((item) => `- ${item}`).join('\n');
+}
+
+function replaceEmptySubsection(content: string, heading: string, items: readonly string[]): string {
+  if (items.length === 0) return content;
+  return content.replace(`${heading}\n`, `${heading}\n\n${renderList(items)}\n`);
+}
+
+function renderTask(params: Readonly<{
+  template: string;
+  candidate: TaskCreateCandidateV1;
+  taskId: string;
+  project: string;
+  timestamp: string;
+  agentInfraVersion: string;
+  keyDigest: string;
+  candidateDigest: string;
+}>): string {
+  const { candidate } = params;
+  const workflow = candidate.type === 'bugfix' ? 'bug-fix' : candidate.type === 'refactor' ? 'refactoring' : 'feature-development';
+  const branch = `${params.project}-${candidate.type}-${candidate.branchSlug}`;
+  const frontmatter = [
+    '---',
+    `id: ${params.taskId}`,
+    `type: ${candidate.type}`,
+    `branch: ${branch}`,
+    `workflow: ${workflow}`,
+    'status: active',
+    `created_at: ${params.timestamp}`,
+    `updated_at: ${params.timestamp}`,
+    `agent_infra_version: ${params.agentInfraVersion}`,
+    `priority: ${candidate.priority}`,
+    `effort: ${candidate.effort}`,
+    'start_date:',
+    'target_date:',
+    'current_step: requirement-analysis',
+    `assigned_to: ${candidate.agent}`,
+    'pr_status: pending',
+    `task_create_key_digest: ${params.keyDigest}`,
+    `task_create_candidate_digest: ${params.candidateDigest}`,
+    '---'
+  ].join('\n');
+  let content = params.template.replace(/^---\n[\s\S]*?\n---/, frontmatter);
+  content = content.replace('# 任务：[标题]', `# 任务：${candidate.title}`);
+  content = content.replace('[清晰简洁地描述任务。]', markdownBlock(candidate.description));
+  const sections: Array<[string, keyof TaskCreateCandidateV1['taskInput']]> = [
+    ['### 来源', 'sources'], ['### 已确认事实与证据', 'facts'], ['### 约束', 'constraints'],
+    ['### 已确认决策', 'decisions'], ['### 候选与否决方案', 'alternatives'],
+    ['### 验收标准', 'acceptanceCriteria'], ['### 未决事项', 'openQuestions']
+  ];
+  for (const [heading, key] of sections) content = replaceEmptySubsection(content, heading, candidate.taskInput[key]);
+  content = content.replace('- **关联 Issue**：#XXX', '- **关联 Issue**：N/A');
+  content = content.replace('- **关联 PR**：#XXX', '- **关联 PR**：N/A');
+  content = content.replace('- **分支**：`feature/xxx`', `- **分支**：\`${branch}\``);
+  const log = [
+    `- ${params.timestamp} — **Create Task [started]** by ${candidate.agent} — started`,
+    `- ${params.timestamp} — **Create Task** by ${candidate.agent} — Task created from structured candidate`
+  ].join('\n');
+  content = content.replace('\n## 完成检查清单', `\n${log}\n\n## 完成检查清单`);
+  return `${content.trimEnd()}\n`;
+}
+
+function readProject(repoRoot: string): string {
+  const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8')) as { project?: unknown };
+  if (typeof config.project !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(config.project)) {
+    throw new Error('TASK_CREATE_CONFIG_INVALID: project is missing or invalid');
+  }
+  return config.project;
+}
+
+function assertRealDirectory(directory: string, code: string): void {
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(code);
+}
+
+function withCreateLock<T>(repoRoot: string, workspaceRoot: string, operation: () => T): T {
+  const lockRoot = path.join(workspaceRoot, '.task-create.lock');
+  fs.mkdirSync(lockRoot, { recursive: true, mode: 0o700 });
+  assertRealDirectory(lockRoot, 'TASK_CREATE_LOCK_FAILED');
+  let callbackError: unknown;
+  try {
+    return withTaskExecutionLock(repoRoot, 'task-create', 'task-create', () => {
+      try { return operation(); }
+      catch (error) { callbackError = error; throw error; }
+    }, { lockRoot });
+  } catch (error) {
+    if (callbackError !== undefined) throw callbackError;
+    if (error instanceof TaskExecutionLockError && error.code === 'ORCHESTRATION_LOCK_BUSY') {
+      throw new Error('TASK_CREATE_LOCK_TIMEOUT');
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`TASK_CREATE_LOCK_FAILED: ${message}`);
+  }
+}
+
+function writeReceipt(receiptPath: string, value: unknown): void {
+  const temporary = `${receiptPath}.tmp.${process.pid}.${randomUUID()}`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { flag: 'wx', mode: 0o600 });
+  try { fs.renameSync(temporary, receiptPath); }
+  catch (error) {
+    try { fs.unlinkSync(temporary); } catch { /* best effort */ }
+    throw error;
+  }
+}
+
+function recoverPublishedTask(activeRoot: string, repoRoot: string, keyDigest: string, candidateDigest: string): { taskId: string; shortId: string } | null {
+  for (const name of fs.readdirSync(activeRoot)) {
+    if (!/^TASK-\d{8}-\d{6}$/.test(name)) continue;
+    const taskDir = path.join(activeRoot, name);
+    const stat = fs.lstatSync(taskDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) continue;
+    const taskMd = path.join(taskDir, 'task.md');
+    if (!fs.existsSync(taskMd)) continue;
+    const taskStat = fs.lstatSync(taskMd);
+    if (!taskStat.isFile() || taskStat.isSymbolicLink()) continue;
+    const content = fs.readFileSync(taskMd, 'utf8');
+    if (!content.includes(`task_create_key_digest: ${keyDigest}`)) continue;
+    if (!content.includes(`task_create_candidate_digest: ${candidateDigest}`)) {
+      throw new Error('TASK_CREATE_IDEMPOTENCY_CONFLICT');
+    }
+    const shortId = loadShortIdByTaskId(repoRoot).get(name)
+      ?? mutateShortIdRegistry(repoRoot, name, 'alloc').shortId;
+    if (!shortId) throw new Error('TASK_CREATE_RECEIPT_INVALID');
+    return { taskId: name, shortId };
+  }
+  return null;
+}
+
+function createLocalTask(value: unknown, options: LocalTaskCreateOptions): LocalTaskCreateResult {
+  const candidate = validateTaskCreateCandidate(value);
+  const repoRoot = fs.realpathSync.native(options.repoRoot);
+  const workspaceRoot = path.join(repoRoot, '.agents', 'workspace');
+  const activeRoot = path.join(workspaceRoot, 'active');
+  assertRealDirectory(workspaceRoot, 'TASK_CREATE_WORKSPACE_INVALID');
+  assertRealDirectory(activeRoot, 'TASK_CREATE_WORKSPACE_INVALID');
+  const project = readProject(repoRoot);
+  const canonical = canonicalTaskCreateCandidate(candidate);
+  const candidateDigest = sha256(canonical);
+  const keyDigest = sha256(candidate.idempotencyKey);
+  const receipts = path.join(workspaceRoot, '.task-create');
+
+  return withCreateLock(repoRoot, workspaceRoot, () => {
+    if (fs.existsSync(receipts)) assertRealDirectory(receipts, 'TASK_CREATE_RECEIPT_INVALID');
+    else fs.mkdirSync(receipts, { mode: 0o700 });
+    const receiptPath = path.join(receipts, `${keyDigest}.json`);
+    if (fs.existsSync(receiptPath)) {
+      const stat = fs.lstatSync(receiptPath);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('TASK_CREATE_RECEIPT_INVALID');
+      const receipt = JSON.parse(fs.readFileSync(receiptPath, 'utf8')) as { candidateDigest?: string; taskId?: string; shortId?: string };
+      if (receipt.candidateDigest !== candidateDigest) throw new Error('TASK_CREATE_IDEMPOTENCY_CONFLICT');
+      if (!receipt.taskId || !receipt.shortId || !fs.existsSync(path.join(activeRoot, receipt.taskId, 'task.md'))) {
+        throw new Error('TASK_CREATE_RECEIPT_INVALID');
+      }
+      return { status: 'no-op', changed: false, task: { id: receipt.taskId, shortId: receipt.shortId } };
+    }
+
+    const recovered = recoverPublishedTask(activeRoot, repoRoot, keyDigest, candidateDigest);
+    if (recovered) {
+      writeReceipt(receiptPath, {
+        version: 1, candidateDigest, taskId: recovered.taskId, shortId: recovered.shortId, status: 'recovered'
+      });
+      return { status: 'no-op', changed: false, task: { id: recovered.taskId, shortId: recovered.shortId } };
+    }
+
+    const base = options.now?.() ?? new Date();
+    let taskDate = new Date(base.getTime());
+    let taskId = taskIdFor(taskDate);
+    while (fs.existsSync(path.join(activeRoot, taskId))) {
+      taskDate = new Date(taskDate.getTime() + 1_000);
+      taskId = taskIdFor(taskDate);
+    }
+    const timestamp = formatTimestamp(base);
+    const templatePath = path.join(repoRoot, '.agents', 'templates', 'task.md');
+    const templateStat = fs.lstatSync(templatePath);
+    if (!templateStat.isFile() || templateStat.isSymbolicLink()) throw new Error('TASK_CREATE_TEMPLATE_INVALID');
+    const rendered = renderTask({
+      template: fs.readFileSync(templatePath, 'utf8'), candidate, taskId, project, timestamp,
+      agentInfraVersion: options.agentInfraVersion ?? 'unknown', keyDigest, candidateDigest
+    });
+    const temporary = path.join(workspaceRoot, `.task-create.tmp.${process.pid}.${randomUUID()}`);
+    fs.mkdirSync(temporary, { mode: 0o700 });
+    fs.writeFileSync(path.join(temporary, 'task.md'), rendered, { flag: 'wx', mode: 0o600 });
+    const destination = path.join(activeRoot, taskId);
+    fs.renameSync(temporary, destination);
+    let shortId: string;
+    try {
+      const allocated = mutateShortIdRegistry(repoRoot, taskId, 'alloc');
+      if (!allocated.shortId) throw new Error('TASK_CREATE_SHORT_ID_FAILED');
+      shortId = allocated.shortId;
+    } catch (error) {
+      fs.rmSync(destination, { recursive: true, force: true });
+      throw error;
+    }
+    try {
+      writeReceipt(receiptPath, { version: 1, candidateDigest, taskId, shortId, status: 'created' });
+    } catch (error) {
+      mutateShortIdRegistry(repoRoot, taskId, 'release');
+      fs.rmSync(destination, { recursive: true, force: true });
+      throw error;
+    }
+    return { status: 'applied', changed: true, task: { id: taskId, shortId } };
+  });
+}
+
+export {
+  canonicalTaskCreateCandidate,
+  createLocalTask,
+  validateTaskCreateCandidate
+};
+export type {
+  LocalTaskCreateOptions,
+  LocalTaskCreateResult,
+  TaskCreateCandidateV1
+};

package/lib/task/delegation-receipts.ts

@@ -6,6 +6,14 @@ import { normalizeAgentToken } from '../agent-clients/tokens.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 DelegationHostEvidence = Readonly<{
+  kind: 'codex-lifecycle-v1';
+  hookDefinitionHash: string;
+  startRevision: number;
+  stopRevision: number | null;
+  consumer: string | null;
+  consumedAt: string | null;
+}>;
 
 type DelegationReceipt = Readonly<{
   id: string;
@@ -28,6 +36,7 @@ type DelegationReceipt = Readonly<{
   agent: string | null;
   status: DelegationStatus;
   workspaceSnapshotScope?: 'task';
+  hostEvidence?: DelegationHostEvidence | null;
   beforeFingerprint: string;
   afterFingerprint: string | null;
   changedPaths: readonly string[];
@@ -55,7 +64,7 @@ function fail(code: string, message: string): ReceiptFailure {
 }
 
 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 }>,
+  input: Omit<DelegationReceipt, 'id' | 'requestedModel' | 'requestedReasoningEffort' | 'actualModel' | 'actualReasoningEffort' | 'modelFallbackReason' | 'reasoningEffortFallbackReason' | 'parentId' | 'childId' | 'spawnMode' | 'agent' | 'status' | 'hostEvidence' | 'afterFingerprint' | 'changedPaths' | 'createdAt' | 'activatedAt' | 'sealedAt' | 'consumedAt'> & Readonly<{ requestedModel: string; requestedReasoningEffort: string }>,
   options: { id?: () => string; now?: () => string } = {}
 ): DelegationReceipt {
   return Object.freeze({
@@ -70,6 +79,7 @@ function prepareDelegation(
     spawnMode: null,
     agent: null,
     status: 'prepared' as const,
+    hostEvidence: null,
     afterFingerprint: null,
     changedPaths: Object.freeze([]),
     createdAt: (options.now ?? (() => new Date().toISOString()))(),
@@ -90,6 +100,11 @@ function activateDelegation(
     actualReasoningEffort?: string;
     modelFallbackReason?: string;
     reasoningEffortFallbackReason?: string;
+    hostEvidence?: Readonly<{
+      kind: 'codex-lifecycle-v1';
+      hookDefinitionHash: string;
+      startRevision: number;
+    }>;
   }>,
   options: { now?: () => string } = {}
 ): ReceiptResult {
@@ -124,6 +139,15 @@ function activateDelegation(
   if (actualReasoningEffort === receipt.requestedReasoningEffort && event.reasoningEffortFallbackReason) {
     return fail('DELEGATION_REASONING_EFFORT_FALLBACK_INVALID', 'reasoning-effort fallback reason is only valid when actual effort differs');
   }
+  if (
+    event.hostEvidence
+    && (
+      receipt.client !== 'codex'
+      || !event.hostEvidence.hookDefinitionHash.trim()
+      || !Number.isSafeInteger(event.hostEvidence.startRevision)
+      || event.hostEvidence.startRevision < 1
+    )
+  ) return fail('DELEGATION_HOST_EVIDENCE_INVALID', 'Codex start evidence reference is invalid');
   return { ok: true, receipt: Object.freeze({
     ...receipt,
     status: 'activated',
@@ -134,6 +158,12 @@ function activateDelegation(
     actualReasoningEffort,
     modelFallbackReason: event.modelFallbackReason ?? null,
     reasoningEffortFallbackReason: event.reasoningEffortFallbackReason ?? null,
+    hostEvidence: event.hostEvidence ? Object.freeze({
+      ...event.hostEvidence,
+      stopRevision: null,
+      consumer: null,
+      consumedAt: null
+    }) : receipt.hostEvidence ?? null,
     activatedAt: (options.now ?? (() => new Date().toISOString()))()
   }) };
 }
@@ -154,7 +184,13 @@ function completeDelegationStage(
 
 function sealDelegation(
   receipt: DelegationReceipt,
-  event: Readonly<{ childId: string; exitCode: number; afterFingerprint: string; changedPaths: readonly string[] }>,
+  event: Readonly<{
+    childId: string;
+    exitCode: number;
+    afterFingerprint: string;
+    changedPaths: readonly string[];
+    hostEvidence?: Readonly<{ stopRevision: number; consumer: string; consumedAt: string }>;
+  }>,
   options: { now?: () => string } = {}
 ): ReceiptResult {
   if (receipt.status !== 'stage-completed') return fail('DELEGATION_STATE_INVALID', `delegation ${receipt.id} is ${receipt.status}, expected stage-completed`);
@@ -169,11 +205,24 @@ function sealDelegation(
     const disallowed = event.changedPaths.find((entry) => !allowed.has(entry));
     if (disallowed) return fail('DELEGATION_REVIEWER_WRITE_FORBIDDEN', `reviewer changed forbidden path '${disallowed}'`);
   }
+  if (event.hostEvidence) {
+    if (
+      !receipt.hostEvidence
+      || !Number.isSafeInteger(event.hostEvidence.stopRevision)
+      || event.hostEvidence.stopRevision <= receipt.hostEvidence.startRevision
+      || event.hostEvidence.consumer !== receipt.id
+      || !event.hostEvidence.consumedAt.trim()
+    ) return fail('DELEGATION_HOST_EVIDENCE_INVALID', 'Codex stop evidence reference is invalid');
+  }
   return { ok: true, receipt: Object.freeze({
     ...receipt,
     status: 'sealed',
     afterFingerprint: event.afterFingerprint,
     changedPaths: Object.freeze([...event.changedPaths]),
+    hostEvidence: event.hostEvidence && receipt.hostEvidence ? Object.freeze({
+      ...receipt.hostEvidence,
+      ...event.hostEvidence
+    }) : receipt.hostEvidence ?? null,
     sealedAt: (options.now ?? (() => new Date().toISOString()))()
   }) };
 }
@@ -196,4 +245,4 @@ export {
   prepareDelegation,
   sealDelegation
 };
-export type { DelegationReceipt, DelegationRole, DelegationStage, DelegationStatus, ReceiptResult };
+export type { DelegationHostEvidence, DelegationReceipt, DelegationRole, DelegationStage, DelegationStatus, ReceiptResult };

package/lib/task/events.ts

@@ -35,7 +35,8 @@ const eventCatalog = [
   'review-plan.started', 'review-plan.completed',
   'code.started', 'code.completed',
   'review-code.started', 'review-code.completed',
-  'manual-validation.started', 'manual-validation.completed'
+  'manual-validation.started', 'manual-validation.completed',
+  'validation-run.started', 'validation-run.completed'
 ] as const;
 type TaskEventName = (typeof eventCatalog)[number];
 type Verdict = 'approved' | 'changes-requested' | 'rejected';
@@ -83,7 +84,9 @@ const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[]
   'review-code.started': { optional: ['round'] },
   'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'manual-validation.started': { optional: ['round'] },
-  'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] }
+  'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] },
+  'validation-run.started': { optional: ['round'] },
+  'validation-run.completed': { required: ['artifact'], optional: ['round'] }
 };
 
 function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | null {
@@ -121,7 +124,8 @@ const FAMILY = {
   'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
   code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
   'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
-  'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' }
+  'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' },
+  'validation-run': { artifact: 'validation-run', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Run Manual Validation' }
 } as const;
 type EventFamily = keyof typeof FAMILY;
 
@@ -217,6 +221,7 @@ function identity(request: TaskEventRequest) {
   else if (family === 'plan') note = `Plan completed, awaiting human review → ${request.artifact}`;
   else if (family === 'code' && request.fixFor) note = `Fixed ${request.blockers} blockers, ${request.major} major, ${request.minor} minor issues${request.manualValidation ? `, skipped ${request.manualValidation} manual-validation` : ''} → ${request.artifact}`;
   else if (family === 'code') note = `Code implemented, ${request.filesModified} files modified, ${request.testsPassed} tests passed → ${request.artifact}`;
+  else if (family === 'validation-run') note = `Validation evidence recorded → ${request.artifact}`;
   else {
     const verdict = request.verdict === 'approved' ? 'Approved' : request.verdict === 'changes-requested' ? 'Changes Requested' : 'Rejected';
     note = `Verdict: ${verdict}, blockers: ${request.blockers}, major: ${request.major}, minor: ${request.minor}, Manual-validation: ${request.manualValidation} → ${request.artifact}`;
@@ -342,7 +347,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   );
   if (findingCountError) return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   let orchestrationCompletion: OrchestrationStageCompletion | null = null;
-  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation') {
+  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation' && eventIdentity.family !== 'validation-run') {
     const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
     const execution = validateLifecycleExecution(normalized.taskRef, {
       mode: normalized.orchestrated ? 'orchestrated' : 'standalone',

package/lib/task/finalization-artifacts.ts

@@ -16,7 +16,8 @@ const COMPLETION_BACKFILL_FAMILIES = [
   'review-plan',
   'code',
   'review-code',
-  'manual-validation'
+  'manual-validation',
+  'validation-run'
 ] as const satisfies readonly ArtifactFamily[];
 
 type CompletionArtifactResult = {

package/lib/task/implementation-inputs.ts

@@ -131,13 +131,9 @@ function finalizeImplementationInput(
 }
 
 function selectPendingImplementationInput(
-  rows: readonly ImplementationInput[], reviewCompletedAt: string
+  rows: readonly ImplementationInput[]
 ): ImplementationInput | null {
-  const reviewEpoch = Date.parse(reviewCompletedAt.replace(' ', 'T'));
-  if (!Number.isFinite(reviewEpoch)) throw new Error('latest review completion time is invalid');
   const pending = rows.filter((row) => row.needsImplementation && row.status === 'pending');
-  const stale = pending.find((row) => Date.parse(row.decidedAt.replace(' ', 'T')) <= reviewEpoch);
-  if (stale) throw new Error(`implementation input ${stale.id} is not later than the latest approved review`);
   return [...pending].sort((left, right) => {
     const time = Date.parse(left.decidedAt.replace(' ', 'T')) - Date.parse(right.decidedAt.replace(' ', 'T'));
     return time || Number.parseInt(left.id.slice(3), 10) - Number.parseInt(right.id.slice(3), 10);

package/lib/task/index.ts

@@ -10,6 +10,7 @@ Commands:
   ls [--all | --blocked | --completed]   List tasks (default: active)
   show [--task <ref>]                    Print a task.md
   status [--task <ref>]                  Aggregated status view (metadata / artifacts / git / platform)
+  validate <ref> [options] -- <command>  Run host validation in snapshot or inplace scope
 
 Examples:
   ai task cat 11 analysis
@@ -29,6 +30,7 @@ Examples:
   ai task show 11
   ai task show TASK-20260612-162737
   ai task status 11
+  ai task validate 11 -- npm test
 
 Run 'ai task <command> --help' for details.`;
 
@@ -93,6 +95,12 @@ export async function runTask(args: string[]): Promise<void> {
       status(rest);
       break;
     }
+    case 'validate': {
+      const { validate } = await import('./commands/validate.ts');
+      const exitCode = await validate(rest);
+      if (exitCode !== 0) process.exitCode = exitCode;
+      break;
+    }
     default:
       process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
       process.stdout.write(`${USAGE}\n`);