@fitlab-ai/agent-infra 0.9.5 → 0.9.6

package/lib/task/commands/status.ts

@@ -71,6 +71,7 @@ const STAGE_ORDER = [
   'review-plan',
   'code',
   'review-code',
+  'validation-run',
   'task',
   'other'
 ] as const;
@@ -81,6 +82,7 @@ function stageOf(name: string): string {
   if (stem.startsWith('review-analysis')) return 'review-analysis';
   if (stem.startsWith('review-plan')) return 'review-plan';
   if (stem.startsWith('review-code')) return 'review-code';
+  if (stem.startsWith('validation-run')) return 'validation-run';
   if (stem.startsWith('analysis')) return 'analysis';
   if (stem.startsWith('plan')) return 'plan';
   if (stem.startsWith('code')) return 'code';

package/lib/task/commands/validate.ts

@@ -0,0 +1,282 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadConfig } from '../../sandbox/config.ts';
+import { detectEngine } from '../../sandbox/engine.ts';
+import { runEngine } from '../../sandbox/shell.ts';
+import { sandboxBranchLabel, sandboxLabel } from '../../sandbox/constants.ts';
+import { fetchSandboxRows, selectSandboxContainer } from '../../sandbox/commands/list-running.ts';
+import { containerNameCandidates } from '../../sandbox/constants.ts';
+import { resolveSandboxTarget } from '../../sandbox/workspace-identity.ts';
+import { sandboxControlPaths } from '../../sandbox/workspace-view.ts';
+import {
+  appendSandboxControlAudit,
+  readActiveLease,
+  readSandboxControlStatus
+} from '../../sandbox/control/state.ts';
+import type { SandboxControlLease, SandboxControlManifest } from '../../sandbox/control/protocol.ts';
+import {
+  SANDBOX_CONTROL_FUTURE_SKEW_MS,
+  SANDBOX_CONTROL_STATUS_STALE_MS
+} from '../../sandbox/control/protocol.ts';
+import { getProcessStartTime } from '../../server/process-state.ts';
+import { assertGitWorktreeBinding } from '../../git/worktree-identity.ts';
+
+const USAGE = `Usage: ai task validate <branch | TASK-id | N> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] -- <command> [args...]`;
+const MAX_TIMEOUT_MS = 60 * 60 * 1000;
+const RECOVERY_GRACE_MS = 30_000;
+
+type ValidateOptions = {
+  target: string;
+  scope: 'snapshot' | 'inplace';
+  timeoutMs: number;
+  format: 'text' | 'json';
+  command: string[];
+  help: boolean;
+};
+
+export function parseValidateArgs(args: string[]): ValidateOptions {
+  if (args.includes('--help') || args.includes('-h')) {
+    return { target: '', scope: 'snapshot', timeoutMs: 300_000, format: 'text', command: [], help: true };
+  }
+  const separator = args.indexOf('--');
+  if (separator < 0) throw new Error(`${USAGE}\nA literal -- must separate validation options from the command.`);
+  const optionArgs = args.slice(0, separator);
+  const command = args.slice(separator + 1);
+  let scope: ValidateOptions['scope'] = 'snapshot';
+  let timeoutMs = 300_000;
+  let format: ValidateOptions['format'] = 'text';
+  const positionals: string[] = [];
+  for (let index = 0; index < optionArgs.length; index += 1) {
+    const arg = optionArgs[index]!;
+    if (arg === '--scope') {
+      const value = optionArgs[++index];
+      if (value !== 'snapshot' && value !== 'inplace') throw new Error('validate --scope must be snapshot or inplace');
+      scope = value;
+    } else if (arg === '--timeout') {
+      const value = Number(optionArgs[++index]);
+      if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMEOUT_MS) throw new Error(`validate --timeout must be 1..${MAX_TIMEOUT_MS}`);
+      timeoutMs = value;
+    } else if (arg === '--format') {
+      const value = optionArgs[++index];
+      if (value !== 'text' && value !== 'json') throw new Error('validate --format must be text or json');
+      format = value;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  if (positionals.length !== 1 || command.length === 0) throw new Error(USAGE);
+  return { target: positionals[0]!, scope, timeoutMs, format, command, help: false };
+}
+
+function runValidationCommand(command: string[], cwd: string, scope: string, timeoutMs: number, json: boolean) {
+  const [file, ...args] = command;
+  const result = spawnSync(file!, args, {
+    cwd,
+    env: { ...process.env, AGENT_INFRA_VALIDATION_SCOPE: scope },
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['inherit', 'pipe', 'pipe'],
+    shell: process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(file!)
+  });
+  if (json) {
+    if (result.stdout) process.stderr.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  } else {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+  }
+  return { exitCode: result.status ?? 1, signal: result.signal ?? null };
+}
+
+function git(root: string, args: string[]): string {
+  return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function waitForState(statusDir: string, predicate: (state: ReturnType<typeof readSandboxControlStatus>) => boolean, timeoutMs = 5_000): void {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const status = readSandboxControlStatus(statusDir);
+      if (predicate(status)) return;
+    } catch {
+      // Atomic status publication may be between renames.
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+  }
+  throw new Error('SANDBOX_VALIDATION_BROKER_STATE_TIMEOUT');
+}
+
+function snapshotValidation(repoRoot: string, commit: string, options: ValidateOptions) {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-validation-'));
+  const worktree = path.join(tempRoot, 'worktree');
+  let cleanup = 'not-created';
+  try {
+    git(repoRoot, ['worktree', 'add', '--detach', worktree, commit]);
+    cleanup = 'pending';
+    return { ...runValidationCommand(options.command, worktree, 'snapshot', options.timeoutMs, options.format === 'json'), cleanup: () => cleanup };
+  } finally {
+    let cleanupError: unknown = null;
+    if (fs.existsSync(worktree)) {
+      try {
+        git(repoRoot, ['worktree', 'remove', '--force', worktree]);
+        cleanup = 'completed';
+      } catch (error) {
+        cleanupError = error;
+      }
+    }
+    try {
+      git(repoRoot, ['worktree', 'prune']);
+    } catch (error) {
+      cleanupError ??= error;
+    }
+    try {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    } catch (error) {
+      cleanupError ??= error;
+    }
+    if (cleanupError) throw cleanupError;
+  }
+}
+
+function inplaceValidation(config: ReturnType<typeof loadConfig>, target: ReturnType<typeof resolveSandboxTarget>, options: ValidateOptions) {
+  const engine = detectEngine(config);
+  const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+  const row = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, target.branch));
+  if (!row) throw new Error('SANDBOX_VALIDATION_CONTAINER_NOT_FOUND');
+  const control = sandboxControlPaths({
+    base: config.controlBase, project: config.project,
+    container: row.name, identity: target.workspace
+  });
+  const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8')) as SandboxControlManifest;
+  const initial = readSandboxControlStatus(control.statusDir);
+  const now = Date.now();
+  if (initial.generation !== manifest.generation
+    || now - initial.updatedAt > SANDBOX_CONTROL_STATUS_STALE_MS
+    || initial.updatedAt > now + SANDBOX_CONTROL_FUTURE_SKEW_MS) {
+    throw new Error('SANDBOX_VALIDATION_BROKER_STATUS_STALE');
+  }
+  if (initial.state !== 'healthy' || initial.activeRequestId !== null) {
+    throw new Error('SANDBOX_VALIDATION_BROKER_NOT_IDLE');
+  }
+  const startTime = getProcessStartTime(process.pid);
+  if (!startTime) throw new Error('SANDBOX_VALIDATION_OWNER_IDENTITY_UNAVAILABLE');
+  const leasePath = path.join(control.root, 'lease.json');
+  const nonce = randomUUID();
+  const issuedAt = Date.now();
+  const lease: SandboxControlLease = {
+    version: 1, generation: manifest.generation, nonce,
+    owner: { pid: process.pid, startTime }, issuedAt,
+    expiresAt: issuedAt + Math.min(options.timeoutMs + RECOVERY_GRACE_MS, MAX_TIMEOUT_MS + RECOVERY_GRACE_MS),
+    taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
+    branch: target.branch, reason: 'manual-validation'
+  };
+  const originalBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const originalHead = git(manifest.worktreeRoot, ['rev-parse', 'HEAD']);
+  fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
+  let stopped = false;
+  let restored = false;
+  try {
+    appendSandboxControlAudit(manifest, 'lease-acquire', { ownerPid: process.pid });
+    waitForState(control.statusDir, (status) => status.state === 'parked' && status.reasonCode === 'SANDBOX_CONTROL_HANDOFF_ACTIVE');
+    if (row.running) {
+      runEngine(engine, 'docker', ['stop', row.name]);
+      stopped = true;
+    }
+    const refreshedRows = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+    const refreshed = selectSandboxContainer(
+      [...refreshedRows.running, ...refreshedRows.nonRunning],
+      containerNameCandidates(config, target.branch)
+    );
+    if (!refreshed || refreshed.running) throw new Error('SANDBOX_VALIDATION_CONTAINER_STILL_RUNNING');
+    const activeLease = readActiveLease(manifest);
+    if (!activeLease || activeLease.nonce !== nonce) throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
+    assertGitWorktreeBinding(config.repoRoot, manifest.worktreeRoot, target.branch);
+    const result = runValidationCommand(options.command, manifest.worktreeRoot, 'inplace', options.timeoutMs, options.format === 'json');
+    return { ...result, cleanup: () => restored ? 'completed' : 'pending' };
+  } finally {
+    const recoveryErrors: string[] = [];
+    try {
+      const currentBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+      if (currentBranch !== originalBranch) git(manifest.worktreeRoot, ['switch', originalBranch]);
+    } catch {
+      try {
+        git(manifest.worktreeRoot, ['checkout', '--detach', originalHead]);
+        git(manifest.worktreeRoot, ['switch', originalBranch]);
+      } catch (fallbackError) {
+        recoveryErrors.push(`git binding restore failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
+      }
+    }
+    if (stopped) {
+      try {
+        runEngine(engine, 'docker', ['start', row.name]);
+      } catch (error) {
+        recoveryErrors.push(`container start failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    try {
+      const currentLease = JSON.parse(fs.readFileSync(leasePath, 'utf8')) as { nonce?: unknown };
+      if (currentLease.nonce !== nonce) throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
+    } catch (error) {
+      recoveryErrors.push(error instanceof Error ? error.message : String(error));
+    }
+    if (recoveryErrors.length === 0) {
+      try {
+        fs.unlinkSync(leasePath);
+        appendSandboxControlAudit(manifest, 'lease-release', { ownerPid: process.pid });
+        waitForState(control.statusDir, (status) => status.state === 'healthy');
+        restored = true;
+      } catch (error) {
+        try {
+          if (!fs.existsSync(leasePath)) {
+            fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
+          }
+          appendSandboxControlAudit(manifest, 'lease-release-failed', { ownerPid: process.pid });
+        } catch (leaseError) {
+          recoveryErrors.push(`lease preservation failed: ${leaseError instanceof Error ? leaseError.message : String(leaseError)}`);
+        }
+        recoveryErrors.push(error instanceof Error ? error.message : String(error));
+      }
+    }
+    if (recoveryErrors.length > 0) {
+      throw new Error(
+        `SANDBOX_VALIDATION_RECOVERY_INCOMPLETE: ${recoveryErrors.join('; ')}; run 'ai sandbox start ${target.branch}'`
+      );
+    }
+  }
+}
+
+export async function validate(args: string[]): Promise<number> {
+  const options = parseValidateArgs(args);
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const config = loadConfig();
+  const target = resolveSandboxTarget(options.target, config.repoRoot);
+  const commit = git(config.repoRoot, ['rev-parse', target.branch]);
+  const startedAt = new Date().toISOString();
+  const result = options.scope === 'snapshot'
+    ? snapshotValidation(config.repoRoot, commit, options)
+    : inplaceValidation(config, target, options);
+  const evidence = {
+    version: 1,
+    taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
+    branch: target.branch,
+    scope: options.scope,
+    commit,
+    command: path.basename(options.command[0]!),
+    startedAt,
+    completedAt: new Date().toISOString(),
+    exitCode: result.exitCode,
+    signal: result.signal,
+    cleanup: result.cleanup()
+  };
+  if (options.format === 'json') process.stdout.write(`${JSON.stringify(evidence)}\n`);
+  else process.stdout.write(`Validation ${result.exitCode === 0 ? 'passed' : 'failed'} (${options.scope}, ${evidence.command}, cleanup=${evidence.cleanup}).\n`);
+  return result.exitCode;
+}

package/lib/task/commit-finalization.ts

@@ -12,7 +12,7 @@ import type { CommitAttempt } from './activity-log.ts';
 import { commitIntentPath, digest, readCommitIntent } from './commit-intent.ts';
 import type { CommitIntent } from './commit-intent.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
-import { parseReviewSummary } from './review-artifacts.ts';
+import { artifactName, maxRound, parseReviewSummary } from './review-artifacts.ts';
 import {
   extractReviewBaseline,
   extractReviewedSnapshotTree,
@@ -43,6 +43,7 @@ type CommitFinalizationInspection = Readonly<{
   currentHead: string;
   committedHead: string | null;
   commitNote: string | null;
+  activityNote: string | null;
   needsAnchor: boolean;
   needsLog: boolean;
   intent: CommitIntent | null;
@@ -87,6 +88,28 @@ function isAncestor(repoRoot: string, ancestor: string, descendant: string): boo
   }).status === 0;
 }
 
+function hasMatchingApprovedReview(
+  taskDir: string,
+  beforeRound: number,
+  baseline: string,
+  tree: string
+): boolean {
+  const entries = fs.readdirSync(taskDir);
+  for (let round = Math.min(beforeRound - 1, maxRound(entries, 'review-code')); round >= 1; round -= 1) {
+    const file = path.join(taskDir, artifactName('review-code', round));
+    if (!fs.existsSync(file)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const summary = parseReviewSummary(content);
+    if (
+      summary.ok
+      && summary.summary.verdict === 'Approved'
+      && extractReviewBaseline(content) === baseline
+      && extractReviewedSnapshotTree(content) === tree
+    ) return true;
+  }
+  return false;
+}
+
 function outcome(
   disposition: CommitFinalizationDisposition,
   overrides: Partial<CommitFinalizationInspection> = {}
@@ -98,6 +121,7 @@ function outcome(
     currentHead: '',
     committedHead: null,
     commitNote: null,
+    activityNote: null,
     needsAnchor: false,
     needsLog: false,
     intent: null,
@@ -212,6 +236,12 @@ function inspectCommitFinalization(
     });
   }
 
+  const commitNote = git(repoRoot, ['show', '-s', '--format=%h%x20%s', intent.committedHead]);
+  const matchingDone = commitRows.filter((row) => row.done !== '' && row.note === commitNote);
+  const pushOnlyRetry = intent.phase === 'pushed'
+    && intent.baselineHead === intent.committedHead
+    && matchingDone.length === 1
+    && openRows.length === 1;
   const review = findAuthoritativeReviewCodeArtifact(taskDir);
   let needsAnchor = false;
   if (review.ok && review.path) {
@@ -228,7 +258,16 @@ function inspectCommitFinalization(
       return invalid('authoritative review-code evidence is not a valid approved snapshot', currentHead, 'COMMIT_FINALIZATION_EVIDENCE_INVALID', shared);
     }
     const committedTree = git(repoRoot, ['rev-parse', `${intent.committedHead}^{tree}`]);
-    if (reviewBaseline !== intent.baselineHead || reviewTree !== committedTree) {
+    const matchingCurrentReview = reviewBaseline === intent.baselineHead && reviewTree === committedTree;
+    if (
+      !matchingCurrentReview
+      && !hasMatchingApprovedReview(
+        taskDir,
+        review.round,
+        intent.baselineHead,
+        committedTree
+      )
+    ) {
       return outcome('conflict', {
         ...shared,
         code: 'COMMIT_FINALIZATION_CONFLICT',
@@ -237,18 +276,16 @@ function inspectCommitFinalization(
     }
 
     const anchor = String(metadata.last_reviewed_commit ?? '').trim();
-    if (anchor && anchor !== intent.committedHead) {
+    if (anchor && anchor !== intent.committedHead && anchor !== intent.baselineHead) {
       return outcome('conflict', {
         ...shared,
         code: 'COMMIT_FINALIZATION_CONFLICT',
         message: 'task review anchor conflicts with the committed intent'
       });
     }
-    needsAnchor = anchor === '';
+    needsAnchor = anchor !== intent.committedHead;
   }
-  const commitNote = git(repoRoot, ['show', '-s', '--format=%h%x20%s', intent.committedHead]);
-  const matchingDone = commitRows.filter((row) => row.done !== '' && row.note === commitNote);
-  const needsLog = matchingDone.length === 0 && openRows.length === 1;
+  const needsLog = (matchingDone.length === 0 && openRows.length === 1) || pushOnlyRetry;
   if (!(needsLog || (matchingDone.length === 1 && openRows.length === 0))) {
     return outcome('conflict', {
       ...shared,
@@ -261,6 +298,7 @@ function inspectCommitFinalization(
     ...shared,
     message: 'commit finalization can be recovered',
     commitNote,
+    activityNote: pushOnlyRetry ? `Pushed ${commitNote}` : commitNote,
     needsAnchor,
     needsLog
   });
@@ -272,7 +310,12 @@ function planCommitTaskFinalization(
   agent: string,
   timestamp: string
 ): CommitTaskFinalizationPlan {
-  if (inspection.disposition !== 'recoverable' || !inspection.committedHead || !inspection.commitNote) {
+  if (
+    inspection.disposition !== 'recoverable'
+    || !inspection.committedHead
+    || !inspection.commitNote
+    || !inspection.activityNote
+  ) {
     throw new Error('commit finalization task mutations require a recoverable inspection');
   }
   const taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
@@ -293,7 +336,7 @@ function planCommitTaskFinalization(
         time: timestamp,
         step: 'Commit',
         agent,
-        note: inspection.commitNote
+        note: inspection.activityNote
       })
     });
   }

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`);