@fitlab-ai/agent-infra 0.9.2 → 0.9.3

package/lib/task/orchestration.ts

@@ -16,24 +16,75 @@ import {
   sealDelegation
 } from './delegation-receipts.ts';
 import type { DelegationReceipt, DelegationRole, DelegationStage } from './delegation-receipts.ts';
-import { getAgentClientCapability } from '../agent-clients/registry.ts';
-import type { AgentClientId } from '../agent-clients/types.ts';
-import { captureWorkspaceSnapshot, diffWorkspaceSnapshots } from './workspace-snapshot.ts';
+import { normalizeAgentClients } from '../agent-clients/config.ts';
+import { inspectPlatformPullRequest } from '../platform/pull-requests.ts';
+import {
+  getAgentClientCapability,
+  getAgentClientDelegationEvidence,
+  getAgentClientModelSelection
+} from '../agent-clients/registry.ts';
+import { isAgentClientId } from '../agent-clients/types.ts';
+import type {
+  AgentClientId,
+  OrchestrationModelPolicy,
+  OrchestrationRolePolicy
+} from '../agent-clients/types.ts';
+import {
+  captureRepositorySnapshot,
+  captureWorkspaceSnapshot,
+  diffWorkspaceSnapshots
+} from './workspace-snapshot.ts';
+import type { RepositorySnapshot } from './workspace-snapshot.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 
 type OrchestrationStatus = 'running' | 'paused' | 'completed';
+type LegacyOrchestrationModelPolicy = Readonly<{
+  executor: string;
+  reviewer: string;
+}>;
+type ModelPolicySource = Readonly<{
+  kind: 'explicit' | 'project-config';
+  client: AgentClientId;
+  resolvedAt: string;
+}>;
+type OrchestrationRecovery = Readonly<{
+  code: 'MODEL_POLICY_SUPPLEMENTED';
+  recoveredAt: string;
+  previousSchemaVersion: 1;
+  previousStatus: OrchestrationStatus;
+  previousPause: Readonly<{ code: string; message: string; recoverable: boolean }> | null;
+  policySource: ModelPolicySource;
+  receiptCount: 0;
+  pendingDelegation: false;
+  resultingStatus: OrchestrationStatus;
+}>;
+type CleanCompletionEvidence = Readonly<{
+  kind: 'reviewed-head-clean';
+  observedAt: string;
+  head: string;
+  headTree: string;
+  worktreeTree: string;
+  lastReviewedCommit: string;
+  prNumber: number;
+  prHead: string;
+}>;
 type OrchestrationRun = Readonly<{
-  schemaVersion: 1;
+  schemaVersion: 1 | 2;
   taskId: string;
   runId: string;
   status: OrchestrationStatus;
   nextStage: DelegationStage | null;
   stepCount: number;
   maxSteps: number;
+  modelPolicy?: OrchestrationModelPolicy | LegacyOrchestrationModelPolicy;
+  modelPolicySource?: ModelPolicySource;
+  recoveryHistory?: readonly OrchestrationRecovery[];
   baseline: string;
   pendingDelegation: DelegationReceipt | null;
   receipts: readonly DelegationReceipt[];
   pause: Readonly<{ code: string; message: string; recoverable: boolean }> | null;
   commitAuthorization: Readonly<{ issuedAt: string | null; consumedAt: string | null }>;
+  completionEvidence?: CleanCompletionEvidence | null;
   createdAt: string;
   updatedAt: string;
 }>;
@@ -43,6 +94,8 @@ type OrchestrationNext = Readonly<{
   stage: DelegationStage;
   round: number;
   artifact: string;
+  requestedModel: string | null;
+  requestedReasoningEffort: string | null;
 }>;
 type OrchestrationResult = Readonly<{
   status: OrchestrationStatus | 'failed';
@@ -50,17 +103,56 @@ type OrchestrationResult = Readonly<{
   taskId: string | null;
   run: OrchestrationRun | null;
   next: OrchestrationNext | null;
-  error: Readonly<{ code: string; message: string }> | null;
+  error: Readonly<{
+    code: string;
+    message: string;
+    client?: AgentClientId;
+    missingFields?: readonly string[];
+    modelSelectionContext?: ReturnType<typeof getAgentClientModelSelection>;
+  }> | null;
+}>;
+type OrchestrationStageIdentity = Readonly<{
+  stage: DelegationStage;
+  round: number;
+  artifact: string;
+  role: DelegationRole;
+}>;
+type OrchestrationStageCompletion = Readonly<{
+  taskId: string;
+  taskDir: string;
+  updatedRun: OrchestrationRun;
+}>;
+type OrchestrationCompletionPlanResult = Readonly<{
+  result: OrchestrationResult;
+  plan: OrchestrationStageCompletion | null;
 }>;
 type OrchestrationOptions = {
   repoRoot?: string;
   id?: () => string;
   now?: () => string;
   maxSteps?: number;
-  captureWorkspace?: (repoRoot: string) => string;
+  client?: AgentClientId;
+  modelPolicy?: OrchestrationModelPolicy;
+  captureWorkspace?: (repoRoot: string, taskId: string | null) => string;
+  captureRepository?: (repoRoot: string) => RepositorySnapshot;
+  inspectPullRequest?: (taskId: string, options: { cwd: string }) => Readonly<{
+    status: string;
+    task?: Readonly<{ prNumber?: number | null }>;
+    prNumber?: number | null;
+    pullRequest?: Readonly<{ head?: Readonly<{ sha?: string }> }> | null;
+    error?: Readonly<{ message?: string }> | null;
+  }>;
   diffWorkspace?: (repoRoot: string, before: string, after: string) => string[];
+  supportsLifecycleDelegation?: (client: AgentClientId) => boolean;
 };
 
+function supportsLifecycleDelegation(client: AgentClientId): boolean {
+  return getAgentClientCapability(client, 'subagents').level !== 'unsupported'
+    && getAgentClientCapability(client, 'orchestration').level !== 'unsupported'
+    && getAgentClientDelegationEvidence(client).actualModel !== 'unavailable'
+    && getAgentClientDelegationEvidence(client).actualReasoningEffort !== 'unavailable';
+}
+
 function orchestrationPath(taskDir: string): string {
   return path.join(taskDir, 'orchestration.json');
 }
@@ -68,7 +160,21 @@ function orchestrationPath(taskDir: string): string {
 function readRun(taskDir: string): OrchestrationRun | null {
   const file = orchestrationPath(taskDir);
   if (!fs.existsSync(file)) return null;
-  return JSON.parse(fs.readFileSync(file, 'utf8')) as OrchestrationRun;
+  const run = JSON.parse(fs.readFileSync(file, 'utf8')) as OrchestrationRun;
+  if (run.schemaVersion !== 2 || !isV2Policy(run.modelPolicy)) return run;
+  return {
+    ...run,
+    modelPolicy: {
+      executor: {
+        model: run.modelPolicy.executor.model,
+        reasoningEffort: run.modelPolicy.executor.reasoningEffort
+      },
+      reviewer: {
+        model: run.modelPolicy.reviewer.model,
+        reasoningEffort: run.modelPolicy.reviewer.reasoningEffort
+      }
+    }
+  };
 }
 
 function atomicWrite(file: string, value: unknown): void {
@@ -85,36 +191,224 @@ function withUpdatedRun(run: OrchestrationRun, updates: Partial<OrchestrationRun
   return Object.freeze({ ...run, ...updates, updatedAt: new Date().toISOString() });
 }
 
-function failed(code: string, message: string, taskId: string | null = null): OrchestrationResult {
-  return { status: 'failed', changed: false, taskId, run: null, next: null, error: { code, message } };
+function failed(
+  code: string,
+  message: string,
+  taskId: string | null = null,
+  details: Omit<NonNullable<OrchestrationResult['error']>, 'code' | 'message'> = {}
+): OrchestrationResult {
+  return { status: 'failed', changed: false, taskId, run: null, next: null, error: { code, message, ...details } };
+}
+
+function validModel(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0 && value.trim() === value;
+}
+
+function validateModelPolicy(policy: OrchestrationModelPolicy | undefined): Readonly<{ code: string; message: string }> | null {
+  if (
+    !policy
+    || !validModel(policy.executor?.model)
+    || !validModel(policy.executor?.reasoningEffort)
+    || !validModel(policy.reviewer?.model)
+    || !validModel(policy.reviewer?.reasoningEffort)
+  ) {
+    return { code: 'ORCHESTRATION_MODEL_POLICY_REQUIRED', message: 'executor and reviewer model and reasoning effort are required' };
+  }
+  return null;
+}
+
+function sameModelPolicy(left: OrchestrationModelPolicy, right: OrchestrationModelPolicy): boolean {
+  return left.executor.model === right.executor.model
+    && left.executor.reasoningEffort === right.executor.reasoningEffort
+    && left.reviewer.model === right.reviewer.model
+    && left.reviewer.reasoningEffort === right.reviewer.reasoningEffort;
+}
+
+function isV2Policy(policy: OrchestrationRun['modelPolicy']): policy is OrchestrationModelPolicy {
+  return typeof policy?.executor === 'object' && typeof policy?.reviewer === 'object';
+}
+
+function rolePolicy(run: OrchestrationRun, role: DelegationRole): OrchestrationRolePolicy | null {
+  return isV2Policy(run.modelPolicy) ? run.modelPolicy[role] : null;
+}
+
+function resolveProjectPolicy(repoRoot: string, client: AgentClientId): OrchestrationModelPolicy | undefined {
+  const configPath = path.join(repoRoot, '.agents', '.airc.json');
+  if (!fs.existsSync(configPath)) return undefined;
+  const raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as Record<string, unknown>;
+  return normalizeAgentClients(raw).state[client].orchestration;
 }
 
 function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
-  const existing = readRun(resolved.taskDir);
+  if (!isAgentClientId(options.client)) {
+    return failed('ORCHESTRATION_PAYLOAD_INVALID', 'begin-or-resume requires a known client', resolved.taskId);
+  }
+  let existing: OrchestrationRun | null;
+  try {
+    existing = readRun(resolved.taskDir);
+  } catch (error) {
+    return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
   if (existing) {
-    if (existing.status === 'paused' && existing.pause?.recoverable && existing.pendingDelegation === null) {
-      const resumed = withUpdatedRun(existing, { status: 'running', pause: null });
-      saveRun(resolved.taskDir, resumed);
-      return { status: 'running', changed: true, taskId: resolved.taskId, run: resumed, next: null, error: null };
+    if (
+      ![1, 2].includes(existing.schemaVersion)
+      || !Array.isArray(existing.receipts)
+      || !Object.prototype.hasOwnProperty.call(existing, 'pendingDelegation')
+    ) {
+      return failed('ORCHESTRATION_STATE_INVALID', 'orchestration state has an invalid schema', resolved.taskId);
+    }
+    if (existing.status === 'completed' && existing.schemaVersion === 1) {
+      return { status: 'completed', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+    }
+    if (existing.schemaVersion === 2) {
+      const policyError = validateModelPolicy(isV2Policy(existing.modelPolicy) ? existing.modelPolicy : undefined);
+      if (
+        policyError
+        || !existing.modelPolicySource
+        || !isAgentClientId(existing.modelPolicySource.client)
+        || !Array.isArray(existing.recoveryHistory)
+      ) {
+        return failed('ORCHESTRATION_STATE_INVALID', 'schemaVersion 2 orchestration state is incomplete', resolved.taskId);
+      }
+      if (existing.status === 'completed') {
+        return { status: 'completed', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+      }
+      if (existing.modelPolicySource.client !== options.client) {
+        return failed('ORCHESTRATION_CLIENT_MISMATCH', 'provided client does not match the persisted run policy source', resolved.taskId);
+      }
+      if (options.modelPolicy) {
+        const suppliedError = validateModelPolicy(options.modelPolicy);
+        if (suppliedError) return failed(suppliedError.code, suppliedError.message, resolved.taskId);
+        if (!sameModelPolicy(existing.modelPolicy as OrchestrationModelPolicy, options.modelPolicy)) {
+          return failed('ORCHESTRATION_MODEL_POLICY_MISMATCH', 'provided model policy does not match the persisted run policy', resolved.taskId);
+        }
+      }
+      if (existing.status === 'paused' && existing.pause?.recoverable && existing.pendingDelegation === null) {
+        const resumed = withUpdatedRun(existing, { status: 'running', pause: null });
+        saveRun(resolved.taskDir, resumed);
+        return { status: 'running', changed: true, taskId: resolved.taskId, run: resumed, next: null, error: null };
+      }
+      return { status: existing.status, changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+    }
+
+    let policy: OrchestrationModelPolicy | undefined = options.modelPolicy;
+    let sourceKind: ModelPolicySource['kind'] = 'explicit';
+    if (!policy) {
+      try {
+        policy = resolveProjectPolicy(resolved.repoRoot, options.client);
+        sourceKind = 'project-config';
+      } catch (error) {
+        return failed('ORCHESTRATION_CONFIG_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+      }
+    }
+    const policyError = validateModelPolicy(policy);
+    if (policyError) {
+      return failed(policyError.code, policyError.message, resolved.taskId, {
+        client: options.client,
+        missingFields: ['executor.model', 'executor.reasoningEffort', 'reviewer.model', 'reviewer.reasoningEffort'],
+        modelSelectionContext: getAgentClientModelSelection(options.client)
+      });
+    }
+    if (existing.pendingDelegation !== null) {
+      const alreadyPaused = existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_DELEGATION_BUSY';
+      if (alreadyPaused) return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+      const paused = withUpdatedRun(existing, {
+        status: 'paused',
+        pause: { code: 'ORCHESTRATION_DELEGATION_BUSY', message: 'legacy run has a pending delegation', recoverable: false }
+      });
+      saveRun(resolved.taskDir, paused);
+      return { status: 'paused', changed: true, taskId: resolved.taskId, run: paused, next: null, error: null };
+    }
+    if (existing.receipts.length > 0) {
+      const alreadyPaused = existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED';
+      if (alreadyPaused) return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+      const paused = withUpdatedRun(existing, {
+        status: 'paused',
+        pause: {
+          code: 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED',
+          message: 'legacy receipts do not contain actual reasoning-effort evidence',
+          recoverable: false
+        }
+      });
+      saveRun(resolved.taskDir, paused);
+      return { status: 'paused', changed: true, taskId: resolved.taskId, run: paused, next: null, error: null };
+    }
+    if (
+      existing.modelPolicy
+      && typeof existing.modelPolicy.executor === 'string'
+      && (
+        existing.modelPolicy.executor !== policy!.executor.model
+        || existing.modelPolicy.reviewer !== policy!.reviewer.model
+      )
+    ) {
+        return failed('ORCHESTRATION_MODEL_POLICY_MISMATCH', 'provided model policy does not match the persisted run policy', resolved.taskId);
+    }
+    const now = (options.now ?? (() => new Date().toISOString()))();
+    const source: ModelPolicySource = { kind: sourceKind, client: options.client, resolvedAt: now };
+    const clearsModelPause = existing.pause?.code === 'ORCHESTRATION_MODEL_EVIDENCE_MISSING';
+    const resultingStatus = clearsModelPause ? 'running' : existing.status;
+    const recovery: OrchestrationRecovery = {
+      code: 'MODEL_POLICY_SUPPLEMENTED',
+      recoveredAt: now,
+      previousSchemaVersion: 1,
+      previousStatus: existing.status,
+      previousPause: existing.pause,
+      policySource: source,
+      receiptCount: 0,
+      pendingDelegation: false,
+      resultingStatus
+    };
+    const recovered: OrchestrationRun = Object.freeze({
+      ...existing,
+      schemaVersion: 2,
+      status: resultingStatus,
+      modelPolicy: policy!,
+      modelPolicySource: source,
+      recoveryHistory: Object.freeze([recovery]),
+      pause: clearsModelPause ? null : existing.pause,
+      updatedAt: now
+    });
+    saveRun(resolved.taskDir, recovered);
+    return { status: resultingStatus, changed: true, taskId: resolved.taskId, run: recovered, next: null, error: null };
+  }
+
+  let policy = options.modelPolicy;
+  let sourceKind: ModelPolicySource['kind'] = 'explicit';
+  if (!policy) {
+    try {
+      policy = resolveProjectPolicy(resolved.repoRoot, options.client);
+      sourceKind = 'project-config';
+    } catch (error) {
+      return failed('ORCHESTRATION_CONFIG_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
-    return { status: existing.status, changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
   }
+  const policyError = validateModelPolicy(policy);
+  if (policyError) return failed(policyError.code, policyError.message, resolved.taskId, {
+    client: options.client,
+    missingFields: ['executor.model', 'executor.reasoningEffort', 'reviewer.model', 'reviewer.reasoningEffort'],
+    modelSelectionContext: getAgentClientModelSelection(options.client)
+  });
   const now = (options.now ?? (() => new Date().toISOString()))();
+  const source: ModelPolicySource = { kind: sourceKind, client: options.client, resolvedAt: now };
   const run: OrchestrationRun = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     taskId: resolved.taskId,
     runId: (options.id ?? randomUUID)(),
     status: 'running',
     nextStage: null,
     stepCount: 0,
     maxSteps: options.maxSteps ?? 24,
+    modelPolicy: policy!,
+    modelPolicySource: source,
+    recoveryHistory: [],
     baseline: '',
     pendingDelegation: null,
     receipts: [],
     pause: null,
     commitAuthorization: { issuedAt: null, consumedAt: null },
+    completionEvidence: null,
     createdAt: now,
     updatedAt: now
   };
@@ -150,7 +444,7 @@ function latestReviewApproved(taskDir: string, family: 'review-analysis' | 'revi
   return parsed.ok && parsed.summary.verdict === 'Approved' && parsed.summary.counts !== null;
 }
 
-function routeFromFacts(taskDir: string): OrchestrationNext | null {
+function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedModel' | 'requestedReasoningEffort'> | null {
   const analysisRound = highestRound(taskDir, 'analysis');
   const analysisReviewRound = highestRound(taskDir, 'review-analysis');
   const planRound = highestRound(taskDir, 'plan');
@@ -205,13 +499,21 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
   } catch (error) {
     return failed('ORCHESTRATION_TASK_READ_FAILED', String(error), resolved.taskId);
   }
+  let metadata: ReturnType<typeof parseTypedTaskFrontmatter>;
   try {
-    parseTypedTaskFrontmatter(content);
+    metadata = parseTypedTaskFrontmatter(content);
   } catch (error) {
     return failed('ORCHESTRATION_TASK_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
   }
-  const next = routeFromFacts(resolved.taskDir);
-  if (!next) return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
+  const routed = routeFromFacts(resolved.taskDir);
+  if (!routed) return failed('ORCHESTRATION_ROUTE_UNKNOWN', 'cannot determine a unique lifecycle action', resolved.taskId);
+  const run = readRun(resolved.taskDir);
+  const policy = run ? rolePolicy(run, routed.role) : null;
+  const next: OrchestrationNext = {
+    ...routed,
+    requestedModel: policy?.model ?? null,
+    requestedReasoningEffort: policy?.reasoningEffort ?? null
+  };
   if (next.stage === 'commit') {
     const reviewRound = highestRound(resolved.taskDir, 'review-code');
     const review = parseReviewSummary(fs.readFileSync(
@@ -221,17 +523,115 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     if (!review.ok || review.summary.manualValidation === null) {
       return failed('ORCHESTRATION_REVIEW_INVALID', 'latest code review has no numeric manual-validation count', resolved.taskId);
     }
-    if (review.summary.manualValidation > 0) {
-      return failed('ORCHESTRATION_MANUAL_VALIDATION_PENDING', 'manual validation must be completed before commit', resolved.taskId);
-    }
     const rows = parseLedger(content);
     const ledgerError = validateLedgerRows(rows);
     if (ledgerError) return failed('ORCHESTRATION_LEDGER_INVALID', ledgerError.message, resolved.taskId);
     if (!summarizeLedgerStage(rows, 'code').canAdvance) {
       return failed('ORCHESTRATION_LEDGER_BLOCKED', 'code review ledger has unresolved findings or human decisions', resolved.taskId);
     }
+    if (run?.status === 'completed') {
+      return { status: 'completed', changed: false, taskId: resolved.taskId, run, next: null, error: null };
+    }
+
+    let config: unknown;
+    try {
+      config = JSON.parse(fs.readFileSync(path.join(resolved.repoRoot, '.agents', '.airc.json'), 'utf8'));
+    } catch (error) {
+      return failed('ORCHESTRATION_CONFIG_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+      return failed('ORCHESTRATION_CONFIG_INVALID', 'project configuration must be an object', resolved.taskId);
+    }
+    const projectConfig = config as Record<string, unknown>;
+    if (!Object.hasOwn(projectConfig, 'prFlow') || projectConfig.prFlow === 'disabled') {
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+    }
+    if (projectConfig.prFlow !== 'required') {
+      return failed('ORCHESTRATION_CONFIG_INVALID', "project configuration 'prFlow' must be 'required' or 'disabled'", resolved.taskId);
+    }
+    const prNumber = Number(metadata.pr_number);
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+    }
+    if (!run) {
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+    }
+    if (run.status !== 'running' || run.pendingDelegation !== null) {
+      return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'clean completion requires an idle running orchestration', resolved.taskId);
+    }
+
+    const capture = options.captureRepository ?? captureRepositorySnapshot;
+    let before: RepositorySnapshot;
+    try {
+      before = capture(resolved.repoRoot);
+    } catch (error) {
+      return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    if (before.headTree !== before.worktreeTree) {
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+    }
+    const lastReviewedCommit = String(metadata.last_reviewed_commit ?? '');
+    if (before.head !== lastReviewedCommit) {
+      return failed('ORCHESTRATION_REVIEWED_HEAD_MISMATCH', 'local HEAD does not match last_reviewed_commit', resolved.taskId);
+    }
+
+    const inspect: NonNullable<OrchestrationOptions['inspectPullRequest']> =
+      options.inspectPullRequest ?? inspectPlatformPullRequest;
+    let inspection: ReturnType<NonNullable<OrchestrationOptions['inspectPullRequest']>>;
+    try {
+      inspection = inspect(resolved.taskId, { cwd: resolved.repoRoot });
+    } catch (error) {
+      return failed('ORCHESTRATION_PR_INSPECTION_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    if (inspection.status === 'blocked') {
+      return failed('ORCHESTRATION_PR_INSPECTION_BLOCKED', inspection.error?.message ?? 'pull request inspection is blocked', resolved.taskId);
+    }
+    if (inspection.status === 'failed') {
+      return failed('ORCHESTRATION_PR_INSPECTION_FAILED', inspection.error?.message ?? 'pull request inspection failed', resolved.taskId);
+    }
+    const inspectedPrNumber = inspection.task?.prNumber ?? inspection.prNumber;
+    const prHead = inspection.pullRequest?.head?.sha;
+    if (typeof prHead !== 'string') {
+      return failed('ORCHESTRATION_PR_INSPECTION_INVALID', 'pull request inspection returned incomplete identity evidence', resolved.taskId);
+    }
+    if (inspectedPrNumber !== prNumber || prHead !== before.head) {
+      return failed('ORCHESTRATION_PR_HEAD_MISMATCH', 'pull request identity does not match the reviewed local HEAD', resolved.taskId);
+    }
+
+    let after: RepositorySnapshot;
+    try {
+      after = capture(resolved.repoRoot);
+    } catch (error) {
+      return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    if (after.headTree !== after.worktreeTree) {
+      return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
+    }
+    if (after.head !== before.head || after.headTree !== before.headTree) {
+      return failed('ORCHESTRATION_REPOSITORY_CHANGED', 'repository changed while clean completion evidence was collected', resolved.taskId);
+    }
+
+    const observedAt = (options.now ?? (() => new Date().toISOString()))();
+    const completionEvidence: CleanCompletionEvidence = {
+      kind: 'reviewed-head-clean',
+      observedAt,
+      head: after.head,
+      headTree: after.headTree,
+      worktreeTree: after.worktreeTree,
+      lastReviewedCommit,
+      prNumber,
+      prHead
+    };
+    const completed = withUpdatedRun(run, {
+      status: 'completed',
+      nextStage: null,
+      pause: null,
+      completionEvidence
+    });
+    saveRun(resolved.taskDir, completed);
+    return { status: 'completed', changed: true, taskId: resolved.taskId, run: completed, next: null, error: null };
   }
-  return { status: 'running', changed: false, taskId: resolved.taskId, run: readRun(resolved.taskDir), next, error: null };
+  return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
 }
 
 function statusOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
@@ -242,21 +642,19 @@ function statusOrchestration(taskRef: string, options: OrchestrationOptions = {}
   return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
 }
 
-function prepareOrchestrationDelegation(
+function prepareOrchestrationDelegationUnlocked(
   taskRef: string,
-  input: Readonly<{ client: AgentClientId; requestedModel?: string }>,
+  input: Readonly<{ client: AgentClientId; requestedModel?: string; requestedReasoningEffort?: string }>,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
-  if (
-    getAgentClientCapability(input.client, 'subagents').level === 'unsupported'
-    || getAgentClientCapability(input.client, 'orchestration').level === 'unsupported'
-  ) {
+  if (!(options.supportsLifecycleDelegation ?? supportsLifecycleDelegation)(input.client)) {
     return failed('ORCHESTRATION_CLIENT_UNSUPPORTED', `client '${input.client}' does not support lifecycle orchestration`, resolved.taskId);
   }
   const run = readRun(resolved.taskDir);
   if (!run || run.status !== 'running') return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'a running orchestration is required', resolved.taskId);
+  if (!isV2Policy(run.modelPolicy)) return failed('ORCHESTRATION_MODEL_EVIDENCE_MISSING', 'running orchestration has no persisted model policy', resolved.taskId);
   if (run.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_BUSY', 'the run already has a pending delegation', resolved.taskId);
   const repositoryPending = (['claude-code', 'codex'] as AgentClientId[])
     .flatMap((client) => matchingDelegations(client, () => true, options));
@@ -267,9 +665,22 @@ function prepareOrchestrationDelegation(
   const routed = routeOrchestration(taskRef, options);
   if (!routed.next) return routed;
   const next = routed.next;
+  if (!validModel(input.requestedModel)) {
+    return failed('ORCHESTRATION_REQUESTED_MODEL_REQUIRED', 'prepare requires the exact requested model identity', resolved.taskId);
+  }
+  if (!validModel(input.requestedReasoningEffort)) {
+    return failed('ORCHESTRATION_REQUESTED_REASONING_EFFORT_REQUIRED', 'prepare requires the exact requested reasoning effort', resolved.taskId);
+  }
+  const expectedPolicy = run.modelPolicy[next.role];
+  if (input.requestedModel !== expectedPolicy.model) {
+    return failed('ORCHESTRATION_REQUESTED_MODEL_MISMATCH', `requested model does not match the persisted ${next.role} model`, resolved.taskId);
+  }
+  if (input.requestedReasoningEffort !== expectedPolicy.reasoningEffort) {
+    return failed('ORCHESTRATION_REQUESTED_REASONING_EFFORT_MISMATCH', `requested reasoning effort does not match the persisted ${next.role} policy`, resolved.taskId);
+  }
   let beforeFingerprint: string;
   try {
-    beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot);
+    beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot, resolved.taskId);
   } catch (error) {
     return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
   }
@@ -281,7 +692,9 @@ function prepareOrchestrationDelegation(
     round: next.round,
     artifact: next.artifact,
     client: input.client,
-    requestedModel: input.requestedModel ?? null,
+    requestedModel: input.requestedModel,
+    requestedReasoningEffort: input.requestedReasoningEffort,
+    workspaceSnapshotScope: 'task',
     beforeFingerprint
   }, { id: options.id, now: options.now });
   const updated = withUpdatedRun(run, {
@@ -295,6 +708,26 @@ function prepareOrchestrationDelegation(
   return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next, error: null };
 }
 
+function prepareOrchestrationDelegation(
+  taskRef: string,
+  input: Readonly<{ client: AgentClientId; requestedModel?: string; requestedReasoningEffort?: string }>,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  try {
+    return withTaskExecutionLock(
+      resolved.repoRoot,
+      resolved.taskId,
+      'task-orchestration.prepare',
+      () => prepareOrchestrationDelegationUnlocked(taskRef, input, options)
+    );
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) return failed(error.code, error.message, resolved.taskId);
+    throw error;
+  }
+}
+
 function matchingDelegations(
   client: AgentClientId,
   predicate: (receipt: DelegationReceipt) => boolean,
@@ -364,7 +797,8 @@ function sealMatchingOrchestrationDelegation(
   }
   const repoRoot = options.repoRoot ?? process.cwd();
   try {
-    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot);
+    const snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
+    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot, snapshotTaskId);
     const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(repoRoot, receipt.beforeFingerprint, afterFingerprint);
     return sealOrchestrationDelegation(matched.taskId, {
       childId: event.childId,
@@ -419,36 +853,20 @@ function completeOrchestrationStage(
   return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
 }
 
-function completeCommitOrchestrationStage(
+function inspectOrchestrationStage(
   taskRef: string,
-  agent: string,
+  event: OrchestrationStageIdentity,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
-  const run = readRun(resolved.taskDir);
-  if (!run) return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
-  const receipt = run.pendingDelegation;
-  if (!receipt || receipt.stage !== 'commit') {
-    return failed('ORCHESTRATION_DELEGATION_MISSING', 'active run has no pending commit delegation', resolved.taskId);
+  let run: OrchestrationRun | null;
+  try {
+    run = readRun(resolved.taskDir);
+  } catch (error) {
+    return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
   }
-  return completeOrchestrationStage(taskRef, {
-    stage: receipt.stage,
-    round: receipt.round,
-    artifact: receipt.artifact,
-    agent
-  }, options);
-}
-
-function validateOrchestrationStage(
-  taskRef: string,
-  event: Readonly<{ stage: DelegationStage; round: number; artifact: string; role: DelegationRole }>,
-  options: OrchestrationOptions = {}
-): OrchestrationResult {
-  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
-  if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
-  const run = readRun(resolved.taskDir);
-  if (!run) return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
+  if (!run) return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
   const receipt = run.pendingDelegation;
   if (
     !receipt
@@ -458,17 +876,67 @@ function validateOrchestrationStage(
     || receipt.artifact !== event.artifact
     || receipt.role !== event.role
   ) {
-    return pauseOrchestration(
-      taskRef,
+    return failed(
       'ORCHESTRATION_PROVENANCE_MISMATCH',
       'active run does not have one matching activated delegation',
-      true,
-      options
+      resolved.taskId
     );
   }
   return { status: 'running', changed: false, taskId: resolved.taskId, run, next: null, error: null };
 }
 
+function planOrchestrationStageCompletion(
+  taskRef: string,
+  event: Readonly<{ stage: DelegationStage; round: number; artifact: string; role: DelegationRole; agent: string }>,
+  options: OrchestrationOptions = {}
+): OrchestrationCompletionPlanResult {
+  const inspected = inspectOrchestrationStage(taskRef, event, options);
+  if (inspected.status === 'failed' || !inspected.run?.pendingDelegation) {
+    return { result: inspected, plan: null };
+  }
+  const receipt = inspected.run.pendingDelegation;
+  const completed = completeDelegationStage(receipt, event);
+  if (!completed.ok) {
+    return { result: failed(completed.code, completed.message, inspected.taskId), plan: null };
+  }
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return { result: failed(resolved.code, resolved.message, resolved.taskId), plan: null };
+  const updatedRun = withUpdatedRun(inspected.run, { pendingDelegation: completed.receipt });
+  return {
+    result: { status: 'running', changed: true, taskId: resolved.taskId, run: updatedRun, next: null, error: null },
+    plan: {
+      taskId: resolved.taskId,
+      taskDir: resolved.taskDir,
+      updatedRun
+    }
+  };
+}
+
+function commitOrchestrationStageCompletion(plan: OrchestrationStageCompletion): void {
+  saveRun(plan.taskDir, plan.updatedRun);
+}
+
+function completeCommitOrchestrationStage(
+  taskRef: string,
+  agent: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  const run = readRun(resolved.taskDir);
+  if (!run) return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
+  const receipt = run.pendingDelegation;
+  if (!receipt || receipt.stage !== 'commit') {
+    return failed('ORCHESTRATION_DELEGATION_MISSING', 'active run has no pending commit delegation', resolved.taskId);
+  }
+  return completeOrchestrationStage(taskRef, {
+    stage: receipt.stage,
+    round: receipt.round,
+    artifact: receipt.artifact,
+    agent
+  }, options);
+}
+
 function sealOrchestrationDelegation(
   taskRef: string,
   event: Parameters<typeof sealDelegation>[1],
@@ -528,16 +996,27 @@ export {
   activateOrchestrationDelegation,
   advanceOrchestration,
   beginOrResumeOrchestration,
+  commitOrchestrationStageCompletion,
   completeCommitOrchestrationStage,
   completeOrchestrationStage,
+  inspectOrchestrationStage,
   orchestrationPath,
   pauseOrchestration,
+  planOrchestrationStageCompletion,
   prepareOrchestrationDelegation,
   readRun,
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
   sealOrchestrationDelegation,
-  statusOrchestration,
-  validateOrchestrationStage
+  statusOrchestration
+};
+export type {
+  OrchestrationCompletionPlanResult,
+  OrchestrationModelPolicy,
+  OrchestrationNext,
+  OrchestrationResult,
+  OrchestrationRun,
+  OrchestrationStageCompletion,
+  OrchestrationStageIdentity,
+  OrchestrationStatus
 };
-export type { OrchestrationNext, OrchestrationResult, OrchestrationRun, OrchestrationStatus };