@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/lib/task/review-finalization.ts

@@ -8,7 +8,8 @@ import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.
 import type { LedgerStageStatus, ReviewStage } from './ledger.ts';
 import { finalizeReviewSummaryContent } from './review-artifacts.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
-import { validateOrchestrationStage } from './orchestration.ts';
+import { validateLifecycleExecution } from './lifecycle-execution.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import type { ResolveTaskRefErrorCode } from './resolve-ref.ts';
 
 type ReviewFinalizationErrorCode =
@@ -31,6 +32,7 @@ type ReviewFinalizationRequest = {
   taskRef: string;
   stage: string;
   artifact: string;
+  orchestrated?: boolean;
   dryRun?: boolean;
 };
 type ReviewFinalizationResult = {
@@ -113,7 +115,7 @@ function cleanupTemp(fileSystem: ReviewFileSystem, tempPath: string): void {
   }
 }
 
-function finalizeReviewSummary(
+function finalizeReviewSummaryUnlocked(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
@@ -167,17 +169,21 @@ function finalizeReviewSummary(
       resolved.taskId
     );
   }
-  const provenance = validateOrchestrationStage(request.taskRef, {
-    stage: spec.family,
-    round: parsedArtifact.round,
-    artifact: request.artifact,
-    role: 'reviewer'
+  const execution = validateLifecycleExecution(request.taskRef, {
+    mode: request.orchestrated ? 'orchestrated' : 'standalone',
+    identity: {
+      stage: spec.family,
+      round: parsedArtifact.round,
+      artifact: request.artifact,
+      role: 'reviewer'
+    },
+    dryRun: request.dryRun
   }, { repoRoot: options.repoRoot });
-  if (provenance.status === 'failed' || provenance.status === 'paused') {
+  if (!execution.ok) {
     return failed(
       request,
       'REVIEW_PROVENANCE_INVALID',
-      provenance.error?.message ?? provenance.run?.pause?.message ?? 'orchestration provenance validation failed',
+      `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`,
       resolved.taskId
     );
   }
@@ -265,6 +271,31 @@ function finalizeReviewSummary(
   };
 }
 
+function finalizeReviewSummary(
+  request: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewFinalizationResult {
+  if (request.dryRun) return finalizeReviewSummaryUnlocked(request, options);
+  const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, options);
+  try {
+    return withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      'task-review.finalize-summary',
+      () => finalizeReviewSummaryUnlocked(request, options)
+    );
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    return failed(
+      request,
+      'REVIEW_PROVENANCE_INVALID',
+      `${error.code}: ${error.message}`,
+      resolved.taskId
+    );
+  }
+}
+
 export { finalizeReviewSummary };
 export type {
   ReviewFinalizationError,

package/lib/task/task-execution-lock.ts

@@ -0,0 +1,296 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+import { getProcessStartTime, processIdentityMatches } from '../server/process-state.ts';
+
+type TaskExecutionLockErrorCode =
+  | 'ORCHESTRATION_LOCK_BUSY'
+  | 'ORCHESTRATION_LOCK_UNSUPPORTED'
+  | 'ORCHESTRATION_LOCK_FAILED';
+
+type TaskExecutionLockOwner = Readonly<{
+  version: 1;
+  pid: number;
+  startTime: string;
+  token: string;
+  owner: string;
+  canonicalRepoRoot: string;
+  taskId: string;
+  acquiredAt: string;
+}>;
+
+type LinkOperation = 'acquire' | 'quarantine';
+type LinkDisposition = 'exists' | 'missing' | TaskExecutionLockError;
+
+type TaskExecutionLockOptions = Readonly<{
+  lockRoot?: string;
+  token?: () => string;
+  now?: () => string;
+  getStartTime?: (pid: number) => string | null;
+  identityMatches?: (record: { version: 1; pid: number; startTime: string }) => boolean;
+  linkSync?: (existingPath: string, newPath: string) => void;
+}>;
+
+class TaskExecutionLockError extends Error {
+  readonly code: TaskExecutionLockErrorCode;
+  readonly detail: Readonly<{ operation: string; errno: string | null; key: string }>;
+
+  constructor(
+    code: TaskExecutionLockErrorCode,
+    message: string,
+    detail: Readonly<{ operation: string; errno: string | null; key: string }>
+  ) {
+    super(message);
+    this.name = 'TaskExecutionLockError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+function errno(error: unknown): string | null {
+  const value = (error as NodeJS.ErrnoException | null)?.code;
+  return typeof value === 'string' ? value : null;
+}
+
+function mapLinkError(operation: LinkOperation, error: unknown, key: string): LinkDisposition {
+  const code = errno(error);
+  if (code === 'EEXIST') return 'exists';
+  if (operation === 'quarantine' && code === 'ENOENT') return 'missing';
+  const detail = { operation, errno: code, key };
+  if (['EPERM', 'EACCES', 'ENOSYS', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV'].includes(code ?? '')) {
+    return new TaskExecutionLockError(
+      'ORCHESTRATION_LOCK_UNSUPPORTED',
+      `lifecycle lock hard-link operation '${operation}' is unsupported`,
+      detail
+    );
+  }
+  return new TaskExecutionLockError(
+    'ORCHESTRATION_LOCK_FAILED',
+    `lifecycle lock hard-link operation '${operation}' failed`,
+    detail
+  );
+}
+
+function lockKey(repoRoot: string, taskId: string): Readonly<{ canonicalRepoRoot: string; key: string }> {
+  const canonicalRepoRoot = fs.realpathSync.native(repoRoot);
+  const key = createHash('sha256').update(`${canonicalRepoRoot}\0${taskId}`).digest('hex');
+  return { canonicalRepoRoot, key };
+}
+
+function parseOwner(raw: string, key: string): TaskExecutionLockOwner {
+  try {
+    const value = JSON.parse(raw) as Partial<TaskExecutionLockOwner> | null;
+    if (
+      value !== null
+      && value.version === 1
+      && Number.isSafeInteger(value.pid)
+      && (value.pid ?? 0) > 0
+      && typeof value.startTime === 'string'
+      && value.startTime.length > 0
+      && typeof value.token === 'string'
+      && value.token.length > 0
+      && typeof value.owner === 'string'
+      && typeof value.canonicalRepoRoot === 'string'
+      && typeof value.taskId === 'string'
+      && typeof value.acquiredAt === 'string'
+    ) {
+      return value as TaskExecutionLockOwner;
+    }
+  } catch {
+    // Fall through to the stable lock failure below.
+  }
+  throw new TaskExecutionLockError(
+    'ORCHESTRATION_LOCK_FAILED',
+    'lifecycle lock owner record is invalid',
+    { operation: 'read', errno: null, key }
+  );
+}
+
+function unlinkIfPresent(file: string): void {
+  try {
+    fs.unlinkSync(file);
+  } catch (error) {
+    if (errno(error) !== 'ENOENT') throw error;
+  }
+}
+
+function sameInode(left: fs.Stats, right: fs.Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function reclaimStaleLock(
+  fixed: string,
+  quarantine: string,
+  snapshot: string,
+  key: string,
+  link: (existingPath: string, newPath: string) => void
+): void {
+  let linked = false;
+  try {
+    link(fixed, quarantine);
+    linked = true;
+  } catch (error) {
+    const disposition = mapLinkError('quarantine', error, key);
+    if (disposition === 'missing') return;
+    if (disposition === 'exists') {
+      try {
+        const quarantineSnapshot = fs.readFileSync(quarantine, 'utf8');
+        const fixedStat = fs.statSync(fixed);
+        const quarantineStat = fs.statSync(quarantine);
+        if (quarantineSnapshot === snapshot && sameInode(fixedStat, quarantineStat)) {
+          unlinkIfPresent(quarantine);
+        }
+      } catch (readError) {
+        if (errno(readError) !== 'ENOENT') throw readError;
+      }
+      return;
+    }
+    if (disposition instanceof TaskExecutionLockError) throw disposition;
+  }
+  try {
+    const fixedSnapshot = fs.readFileSync(fixed, 'utf8');
+    const fixedStat = fs.statSync(fixed);
+    const quarantineStat = fs.statSync(quarantine);
+    if (fixedSnapshot === snapshot && sameInode(fixedStat, quarantineStat)) unlinkIfPresent(fixed);
+  } catch (error) {
+    if (errno(error) !== 'ENOENT') throw error;
+  } finally {
+    if (linked) unlinkIfPresent(quarantine);
+  }
+}
+
+function cleanStaleCandidates(
+  lockRoot: string,
+  key: string,
+  identityMatches: (record: { version: 1; pid: number; startTime: string }) => boolean
+): void {
+  const prefix = `${key}.candidate.`;
+  for (const name of fs.readdirSync(lockRoot)) {
+    if (!name.startsWith(prefix)) continue;
+    const candidate = path.join(lockRoot, name);
+    try {
+      const owner = parseOwner(fs.readFileSync(candidate, 'utf8'), key);
+      if (!identityMatches(owner)) unlinkIfPresent(candidate);
+    } catch {
+      // A malformed candidate never owns the fixed lock and is left for manual diagnosis.
+    }
+  }
+}
+
+function withTaskExecutionLock<T>(
+  repoRoot: string,
+  taskId: string,
+  ownerName: string,
+  callback: () => T,
+  options: TaskExecutionLockOptions = {}
+): T {
+  let identity: Readonly<{ canonicalRepoRoot: string; key: string }>;
+  try {
+    identity = lockKey(repoRoot, taskId);
+  } catch (error) {
+    throw new TaskExecutionLockError(
+      'ORCHESTRATION_LOCK_FAILED',
+      'failed to canonicalize the repository for lifecycle locking',
+      { operation: 'canonicalize', errno: errno(error), key: 'unresolved' }
+    );
+  }
+  const { canonicalRepoRoot, key } = identity;
+  const lockRoot = options.lockRoot ?? path.join(os.tmpdir(), 'agent-infra-lifecycle-locks');
+  const token = (options.token ?? randomUUID)();
+  const candidate = path.join(lockRoot, `${key}.candidate.${process.pid}.${token}`);
+  const fixed = path.join(lockRoot, `${key}.lock`);
+  const link = options.linkSync ?? fs.linkSync;
+  const startTime = (options.getStartTime ?? getProcessStartTime)(process.pid);
+  if (startTime === null) {
+    throw new TaskExecutionLockError(
+      'ORCHESTRATION_LOCK_FAILED',
+      'current process start time is unavailable',
+      { operation: 'identity', errno: null, key }
+    );
+  }
+  const owner: TaskExecutionLockOwner = {
+    version: 1,
+    pid: process.pid,
+    startTime,
+    token,
+    owner: ownerName,
+    canonicalRepoRoot,
+    taskId,
+    acquiredAt: (options.now ?? (() => new Date().toISOString()))()
+  };
+  const serialized = `${JSON.stringify(owner)}\n`;
+  let ownsFixed = false;
+  try {
+    fs.mkdirSync(lockRoot, { recursive: true });
+    cleanStaleCandidates(lockRoot, key, options.identityMatches ?? processIdentityMatches);
+    const descriptor = fs.openSync(candidate, 'wx', 0o600);
+    try {
+      fs.writeFileSync(descriptor, serialized);
+      fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+    for (let attempt = 0; attempt < 16; attempt += 1) {
+      try {
+        link(candidate, fixed);
+        ownsFixed = true;
+        break;
+      } catch (error) {
+        const disposition = mapLinkError('acquire', error, key);
+        if (disposition instanceof TaskExecutionLockError) throw disposition;
+        let snapshot: string;
+        let current: TaskExecutionLockOwner;
+        try {
+          snapshot = fs.readFileSync(fixed, 'utf8');
+          current = parseOwner(snapshot, key);
+        } catch (readError) {
+          if (errno(readError) === 'ENOENT') continue;
+          throw readError;
+        }
+        if ((options.identityMatches ?? processIdentityMatches)(current)) {
+          throw new TaskExecutionLockError(
+            'ORCHESTRATION_LOCK_BUSY',
+            'another lifecycle operation holds the task lock',
+            { operation: 'acquire', errno: 'EEXIST', key }
+          );
+        }
+        reclaimStaleLock(fixed, `${fixed}.quarantine.${current.token}`, snapshot, key, link);
+      }
+    }
+    if (!ownsFixed) {
+      throw new TaskExecutionLockError(
+        'ORCHESTRATION_LOCK_BUSY',
+        'lifecycle task lock could not be acquired after stale recovery',
+        { operation: 'acquire', errno: 'EEXIST', key }
+      );
+    }
+    unlinkIfPresent(candidate);
+    return callback();
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) throw error;
+    throw new TaskExecutionLockError(
+      'ORCHESTRATION_LOCK_FAILED',
+      'lifecycle task lock operation failed',
+      { operation: ownsFixed ? 'callback' : 'acquire', errno: errno(error), key }
+    );
+  } finally {
+    try {
+      unlinkIfPresent(candidate);
+    } catch {
+      // Candidate cleanup is best-effort and must not replace the primary result.
+    }
+    if (ownsFixed) {
+      try {
+        const current = parseOwner(fs.readFileSync(fixed, 'utf8'), key);
+        if (current.token === token) unlinkIfPresent(fixed);
+      } catch {
+        // A missing or replaced fixed lock is not owned by this invocation.
+      }
+    }
+  }
+}
+
+export { TaskExecutionLockError, lockKey, mapLinkError, withTaskExecutionLock };
+export type { LinkDisposition, LinkOperation, TaskExecutionLockErrorCode, TaskExecutionLockOptions, TaskExecutionLockOwner };

package/lib/task/verification-checks.ts

@@ -1,6 +1,6 @@
 const LOCAL_VERIFICATION_CHECKS = [
   'task-meta', 'artifact', 'implementation-input', 'activity-log', 'completion-checklist',
-  'orchestration-state'
+  'orchestration-state', 'orchestration-evidence'
 ] as const;
 
 function isLocalVerificationCheck(value: string): value is typeof LOCAL_VERIFICATION_CHECKS[number] {

package/lib/task/verification-engine.ts

@@ -114,6 +114,8 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkCompletionChecklist(context);
     case "review-ledger":
       return checkReviewLedger(context);
+    case "manual-validation":
+      return checkManualValidation(context);
     case "review-summary":
       return checkReviewSummary(context);
     case "review-fact":
@@ -122,6 +124,8 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkPostReviewCommit(context);
     case "orchestration-state":
       return checkOrchestrationState(context);
+    case "orchestration-evidence":
+      return checkOrchestrationEvidence(context);
     default: {
       const adapter = PLATFORM_ADAPTERS[type];
       if (!adapter) {
@@ -137,6 +141,25 @@ function runCheck(type: any, context: any, shared: any): any {
   }
 }
 
+function isFailClosedLegacyPause(run: any): boolean {
+  if (
+    run.schemaVersion !== 1
+    || run.status !== 'paused'
+    || run.pause?.recoverable !== false
+    || !exactText(run.pause?.message)
+    || !Array.isArray(run.receipts)
+  ) {
+    return false;
+  }
+  if (run.pause.code === 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED') {
+    return run.receipts.length > 0 && run.pendingDelegation === null;
+  }
+  if (run.pause.code === 'ORCHESTRATION_DELEGATION_BUSY') {
+    return run.pendingDelegation != null && run.pendingDelegation.status !== 'sealed';
+  }
+  return false;
+}
+
 function checkOrchestrationState({ taskDir }: any): any {
   const file = path.join(taskDir, 'orchestration.json');
   const stat = safeStat(file);
@@ -147,22 +170,177 @@ function checkOrchestrationState({ taskDir }: any): any {
   } catch (error) {
     return failResult('orchestration-state', `Invalid orchestration.json: ${String(error)}`);
   }
-  if (run.schemaVersion !== 1 || !['paused', 'completed'].includes(run.status)) {
+  if (isFailClosedLegacyPause(run)) {
+    return passResult('orchestration-state', 'Legacy orchestration run is safely paused');
+  }
+  if (run.schemaVersion !== 2 || !['paused', 'completed'].includes(run.status)) {
     return failResult('orchestration-state', `Expected paused or completed run, received '${run.status}'`);
   }
   if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
     return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
   }
   if (run.status === 'completed') {
-    if (run.pendingDelegation !== null || !run.commitAuthorization?.consumedAt) {
+    if (run.completionEvidence != null) {
+      const evidenceError = validateCleanCompletionEvidence(run);
+      if (evidenceError) return failResult('orchestration-state', evidenceError);
+    } else if (run.pendingDelegation !== null || !run.commitAuthorization?.consumedAt) {
       return failResult('orchestration-state', 'Completed run must consume commit authorization and clear pending delegation');
     }
+  } else if (run.completionEvidence != null) {
+    return failResult('orchestration-state', 'Clean completion evidence requires a completed run');
   } else if (run.pendingDelegation?.status === 'sealed') {
     return failResult('orchestration-state', 'Paused run has a sealed delegation that could still advance');
   }
   return passResult('orchestration-state', `Orchestration run is safely ${run.status}`);
 }
 
+function exactText(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.trim() === value;
+}
+
+function validateCleanCompletionEvidence(run: any): string | null {
+  const evidence = run.completionEvidence;
+  const shaPattern = /^[0-9a-f]{40}$/i;
+  if (
+    evidence?.kind !== 'reviewed-head-clean'
+    || !exactText(evidence.observedAt)
+    || Number.isNaN(Date.parse(evidence.observedAt))
+    || !shaPattern.test(evidence.head)
+    || !shaPattern.test(evidence.headTree)
+    || !shaPattern.test(evidence.worktreeTree)
+    || !shaPattern.test(evidence.lastReviewedCommit)
+    || !Number.isInteger(evidence.prNumber)
+    || evidence.prNumber <= 0
+    || !shaPattern.test(evidence.prHead)
+  ) {
+    return 'Clean completion evidence has an invalid structure';
+  }
+  if (
+    evidence.head !== evidence.lastReviewedCommit
+    || evidence.head !== evidence.prHead
+    || evidence.headTree !== evidence.worktreeTree
+  ) {
+    return 'Clean completion evidence does not bind matching commit and tree identities';
+  }
+  if (
+    run.status !== 'completed'
+    || run.pendingDelegation !== null
+    || run.commitAuthorization?.issuedAt !== null
+    || run.commitAuthorization?.consumedAt !== null
+    || !Array.isArray(run.receipts)
+    || run.receipts.some((receipt: any) => receipt.stage === 'commit')
+  ) {
+    return 'Clean completion evidence conflicts with commit delegation state';
+  }
+  return null;
+}
+
+function checkOrchestrationEvidence({ taskDir }: any): any {
+  const file = path.join(taskDir, 'orchestration.json');
+  const stat = safeStat(file);
+  if (!stat?.isFile()) return failResult('orchestration-evidence', 'orchestration.json is missing');
+  let run: any;
+  try {
+    run = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    return failResult('orchestration-evidence', `Invalid orchestration.json: ${String(error)}`);
+  }
+  if (isFailClosedLegacyPause(run)) {
+    return passResult('orchestration-evidence', 'Legacy orchestration evidence is preserved in a fail-closed pause');
+  }
+  const policy = run.modelPolicy;
+  if (
+    !policy
+    || !exactText(policy.executor?.model)
+    || !exactText(policy.executor?.reasoningEffort)
+    || !exactText(policy.reviewer?.model)
+    || !exactText(policy.reviewer?.reasoningEffort)
+  ) {
+    return failResult('orchestration-evidence', 'Run model policy requires exact executor and reviewer model and effort');
+  }
+  if (
+    !run.modelPolicySource
+    || !['explicit', 'project-config'].includes(run.modelPolicySource.kind)
+    || !exactText(run.modelPolicySource.client)
+    || !exactText(run.modelPolicySource.resolvedAt)
+    || !Array.isArray(run.recoveryHistory)
+  ) {
+    return failResult('orchestration-evidence', 'Run model policy source or recovery history is invalid');
+  }
+  for (const recovery of run.recoveryHistory) {
+    if (
+      recovery.code !== 'MODEL_POLICY_SUPPLEMENTED'
+      || recovery.previousSchemaVersion !== 1
+      || recovery.receiptCount !== 0
+      || recovery.pendingDelegation !== false
+      || !exactText(recovery.recoveredAt)
+      || !recovery.policySource
+    ) {
+      return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
+    }
+  }
+  if (!Array.isArray(run.receipts)) {
+    return failResult('orchestration-evidence', 'Run receipts must be an array');
+  }
+  if (run.completionEvidence != null) {
+    const evidenceError = validateCleanCompletionEvidence(run);
+    if (evidenceError) return failResult('orchestration-evidence', evidenceError);
+  } else if (run.status === 'completed' && (
+      run.receipts.length === 0
+      || run.receipts.at(-1)?.stage !== 'commit'
+      || run.receipts.at(-1)?.status !== 'consumed'
+    )) {
+      return failResult('orchestration-evidence', 'Completed run requires a final consumed commit receipt');
+  }
+  if (run.pendingDelegation && !['prepared', 'activated', 'stage-completed'].includes(run.pendingDelegation.status)) {
+    return failResult('orchestration-evidence', `Pending receipt has unsafe status '${run.pendingDelegation.status}'`);
+  }
+  const receipts = [...run.receipts, ...(run.pendingDelegation ? [run.pendingDelegation] : [])];
+  for (const receipt of receipts) {
+    const expectedPolicy = policy[receipt.role];
+    if (!expectedPolicy || receipt.requestedModel !== expectedPolicy.model) {
+      return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' requested model does not match its role policy`);
+    }
+    if (receipt.requestedReasoningEffort !== expectedPolicy.reasoningEffort) {
+      return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' requested reasoning effort does not match its role policy`);
+    }
+    const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
+    if (activated) {
+      if (!exactText(receipt.actualModel)) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+      }
+      if (!exactText(receipt.actualReasoningEffort)) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+      }
+      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId || receipt.spawnMode !== 'fresh') {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
+      }
+      if (receipt.actualModel !== receipt.requestedModel && !exactText(receipt.modelFallbackReason)) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+      }
+      if (receipt.actualModel === receipt.requestedModel && receipt.modelFallbackReason !== null) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      }
+      if (
+        receipt.actualReasoningEffort !== receipt.requestedReasoningEffort
+        && !exactText(receipt.reasoningEffortFallbackReason)
+      ) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+      }
+      if (
+        receipt.actualReasoningEffort === receipt.requestedReasoningEffort
+        && receipt.reasoningEffortFallbackReason !== null
+      ) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
+      }
+    }
+  }
+  if (run.receipts.some((receipt: any) => receipt.status !== 'consumed')) {
+    return failResult('orchestration-evidence', 'Historical receipts must be consumed');
+  }
+  return passResult('orchestration-evidence', 'Persisted orchestration model and delegation evidence is internally consistent');
+}
+
 // === Check Functions ===
 
 function checkTaskMeta({ taskDir, config }: any): any {
@@ -740,6 +918,75 @@ function checkReviewLedger({ taskDir, config }: any): any {
   return passResult("review-ledger", `Disagreement ledger clean (${inScopeCount} in-scope entries terminal${scopeLabel})`);
 }
 
+function checkManualValidation({ taskDir }: any): any {
+  // 1. Latest review-code artifact; none -> pass (no review, check not applicable).
+  const review = findAuthoritativeReviewCodeArtifact(taskDir);
+  if (!review.ok) {
+    return passResult("manual-validation", "No review-code artifact; manual validation not applicable");
+  }
+  // 2. Parse the numeric manual-validation count; unparseable/null -> fail closed
+  //    (review-code.completed already enforces a numeric count on the normal path).
+  const parsed = parseReviewSummary(fs.readFileSync(review.path!, "utf8"));
+  if (!parsed.ok || parsed.summary.manualValidation === null) {
+    return failResult("manual-validation", "Latest review-code has no numeric manual-validation count");
+  }
+  // 3. Count 0 -> pass (no pending items to cover).
+  if (parsed.summary.manualValidation === 0) {
+    return passResult("manual-validation", "No pending manual validation items");
+  }
+  // 4. Highest-round manual-validation artifact; none -> fail (items pending,
+  //    run complete-manual-validation first). A falsy artifactFile goes through
+  //    pattern parsing; resolveArtifactPath only returns { ok, path }.
+  const resolved = resolveArtifactPath(taskDir, "manual-validation.md|manual-validation-r{N}.md", "");
+  if (!resolved.ok) {
+    return failResult(
+      "manual-validation",
+      `${parsed.summary.manualValidation} manual validation item(s) pending: run /complete-manual-validation`
+    );
+  }
+  // 5. The Activity Log must record the matching completion entry; the file name
+  //    is derived with path.basename (resolveArtifactPath does not return fileName).
+  const artifactName = path.basename(resolved.path);
+  const task = loadTask(taskDir);
+  if (!task.ok) return failResult("manual-validation", task.message);
+  const log = getSectionContent(task.content, ["活动日志", "Activity Log"]);
+  const completed = new RegExp(
+    `\\*\\*Complete Manual Validation\\*\\*[\\s\\S]*?Manual validation passed → ${escapeRegExp(artifactName)};`
+  );
+  if (!completed.test(log)) {
+    return failResult(
+      "manual-validation",
+      `Manual validation artifact exists but completion is not recorded for ${artifactName}: re-run /complete-manual-validation`
+    );
+  }
+  // 6. Timing correlation (PL-3 fix, PL-4 corrected): the completion entry must
+  //    sit AFTER the latest review-code round's completion entry in the
+  //    append-only Activity Log. indexOf is a literal search, so the artifactName
+  //    must NOT be passed through escapeRegExp here (that escapes '.' to '\.',
+  //    which indexOf never matches). Not reusing completed.exec().index: exec
+  //    anchors to the first '**Complete Manual Validation**' heading, which can
+  //    belong to an earlier round's entry and misorder the standard path.
+  const reviewDoneIndex = log.indexOf(`**Review Code (Round ${review.round})** by `);
+  const completedIndex = log.indexOf(`Manual validation passed → ${artifactName};`);
+  if (reviewDoneIndex === -1) {
+    // The latest review-code round's completion entry is missing entirely (abnormal
+    // state, e.g. a restored/historical task without a review-code.completed record).
+    // Re-running complete-manual-validation cannot restore it, so the remediation
+    // targets the review record itself. Fail closed either way.
+    return failResult(
+      "manual-validation",
+      `Latest review-code (round ${review.round}) completion entry is missing from the Activity Log (abnormal state): re-run review-code or restore the completion record`
+    );
+  }
+  if (completedIndex < reviewDoneIndex) {
+    return failResult(
+      "manual-validation",
+      `Latest review-code (round ${review.round}) came after the manual validation completion recorded for ${artifactName}: re-run /complete-manual-validation to cover new pending items`
+    );
+  }
+  return passResult("manual-validation", `Manual validation completed → ${artifactName}`);
+}
+
 function checkPostReviewCommit({ taskDir, config }: any): any {
   const reviewArtifact = findAuthoritativeReviewCodeArtifact(taskDir);
   if (!reviewArtifact.ok) {