chati-dev 4.5.16 → 4.5.27

package/src/terminal/run-rail-adjudication.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { validateAdjudicationDecision } from '@chati/review-council';
+import { sha256 } from '@chati/core';
+import { adjudicationEntriesAgree, deriveAdjudicationConsensus } from '@chati/rail';
+import {
+  buildSpawnCommand, getTerminalCompletionAuthorityReceipt, getTerminalLaunchAuthorityReceipt,
+  isTransientFailure, killTerminal, spawnTerminal, waitForTerminal,
+} from './spawner.js';
+import { checkProviderReadiness } from './provider-preflight.js';
+import { getRateLimiter } from './rate-limiter.js';
+import { startClaimHeartbeat } from './run-rail-task.js';
+import {
+  acquireRailTaskSupervisor, createProjectRailEngine, recordRailAdjudication,
+  recordRailAdjudicationDispatch, recordRailAdjudicationObservation,
+  relinquishRailTask, resolveRailAttemptContext,
+} from '../orchestrator/rail-runtime.js';
+import { listRailExecutionEvidence } from '../orchestrator/rail-runtime.js';
+import { listRailReviewEvidence, resolveReviewGitSubject } from '../orchestrator/review-runtime.js';
+import { persistRailAdjudicationEvidence } from '../orchestrator/rail-adjudication-evidence.js';
+import { buildRailAdjudicationPrompt } from './rail-prompts.js';
+import {
+  assertRailReadOnlyCommitWorkspaceUnchanged, cleanupRailReadOnlyCommitWorkspace,
+  createRailReadOnlyCommitWorkspace,
+} from './rail-readonly-workspace.js';
+import {
+  loadRuntimeInstallationV2, resolveRuntimeExecutableBindingV2,
+} from '../orchestrator/runtime-installation-v2.js';
+
+export { buildRailAdjudicationPrompt } from './rail-prompts.js';
+
+function fail(code, message, details = {}) { const error = new Error(message); error.code = code; error.details = details; throw error; }
+
+function parseDecision(text) {
+  const startToken = '<CHATI_RAIL_ADJUDICATION>';
+  const endToken = '</CHATI_RAIL_ADJUDICATION>';
+  const starts = [...text.matchAll(new RegExp(startToken, 'g'))];
+  const ends = [...text.matchAll(new RegExp(endToken, 'g'))];
+  if (starts.length !== 1 || ends.length !== 1) {
+    return fail('RAIL_ADJUDICATION_OUTPUT_INVALID', 'adjudicator must return exactly one required envelope');
+  }
+  const start = starts[0].index;
+  const end = text.indexOf(endToken, start + startToken.length);
+  if (end < start) return fail('RAIL_ADJUDICATION_OUTPUT_INVALID', 'adjudicator returned malformed envelope ordering');
+  try { return validateAdjudicationDecision(JSON.parse(text.slice(start + startToken.length, end).trim())); }
+  catch (error) { return fail(error.code || 'RAIL_ADJUDICATION_OUTPUT_INVALID', error.message); }
+}
+
+function latestAdjudicationPlan(context) {
+  const latest = context.records.filter((record) => record.type === 'review_decided'
+    && record.payload?.attempt_id === context.attempt.attempt_id).at(-1);
+  if (latest?.payload?.decision?.decision !== 'AI_ADJUDICATION') {
+    fail('RAIL_ADJUDICATION_NOT_AUTHORIZED', 'the latest canonical review decision does not authorize AI adjudication');
+  }
+  return latest.payload;
+}
+
+async function invokeAdjudicator({ projectDir, artifact, context, plan, review_ref, invocation: selectedInvocation, reviews, executions, priorDecisions, round, timeout, max_retries, onHandle, reviewWorkspace, reviewSubject, assertLease = () => {} }) {
+  const providerExecutableBinding = resolveRuntimeExecutableBindingV2({
+    artifact, provider_id: selectedInvocation.provider_id, harness_id: selectedInvocation.harness_id,
+  });
+  const readiness = checkProviderReadiness(selectedInvocation.harness_id, {
+    workingDir: projectDir, executableBinding: providerExecutableBinding,
+  });
+  if (!readiness.ready) fail(readiness.code || 'PROVIDER_NOT_READY', readiness.detail || `${selectedInvocation.harness_id} is not ready`);
+  const spawnAdjudicationAttempt = async (retry) => {
+    const invocationDraft = {
+      ...selectedInvocation,
+      attempt_id: context.attempt.attempt_id,
+      invocation_id: `rail-adjudication-${context.attempt.attempt_id}-${round}-${selectedInvocation.provider_id}-${retry + 1}`,
+      launch_nonce: randomUUID(),
+      adjudication_round: round,
+      prior_decisions_digest: sha256(priorDecisions),
+      language: context.language,
+    };
+    const prompt = buildRailAdjudicationPrompt({
+      projectDir: reviewWorkspace.subject_dir,
+      context,
+      plan,
+      invocation: invocationDraft,
+      reviews,
+      executions,
+      priorDecisions,
+      round,
+      reviewSubject,
+    });
+    const exactInvocation = Object.freeze({ ...invocationDraft, prompt_digest: sha256(prompt) });
+    const config = {
+      agent: 'rail-adjudication', taskId: context.task.task_id,
+      provider: exactInvocation.harness_id, providerId: exactInvocation.provider_id,
+      model: exactInvocation.model_pin.model_id,
+      reasoningConfiguration: exactInvocation.model_pin.reasoning_configuration,
+      catalogSnapshotRef: exactInvocation.model_pin.catalog_snapshot_ref,
+      providerExecutableBinding,
+      prompt,
+      workingDir: reviewWorkspace.subject_dir, timeout, writeScope: [],
+      auditProjectDir: projectDir,
+      maskedReadPaths: [projectDir],
+      authorityContext: {
+        authority_kind: 'rail_adjudication', invocation_id: exactInvocation.invocation_id,
+        launch_nonce: exactInvocation.launch_nonce, provider_id: exactInvocation.provider_id,
+      },
+      beforeProcessSpawn: () => assertRailReadOnlyCommitWorkspaceUnchanged({
+        workspace: reviewWorkspace,
+        label: 'RAIL adjudication pre-spawn',
+      }),
+    };
+    const built = buildSpawnCommand(config);
+    if (built.actualProvider !== config.provider || built.actualModel !== config.model
+      || built.actualReasoningConfiguration !== config.reasoningConfiguration) {
+      fail('RAIL_ADJUDICATION_ROUTE_MISMATCH', 'terminal adapter changed a selected adjudicator binding');
+    }
+    await getRateLimiter(exactInvocation.harness_id).waitForSlot();
+    assertLease();
+    const handle = spawnTerminal(config);
+    // Publish the handle before the first fallible journal operation so outer
+    // cleanup never treats an unreturned spawned process as already absent.
+    onHandle?.(handle);
+    try {
+      recordRailAdjudicationDispatch({
+        projectDir, handoff_id: context.handoff.handoff_id,
+        attempt_id: context.attempt.attempt_id, review_ref, invocation: exactInvocation,
+        launch_receipt: getTerminalLaunchAuthorityReceipt(handle),
+        prompt,
+        reviewWorkspace,
+      });
+    } catch (error) {
+      await killTerminal(handle);
+      throw error;
+    }
+    return { handle, exactInvocation };
+  };
+  let { handle, exactInvocation } = await spawnAdjudicationAttempt(0);
+  let retries = 0;
+  await waitForTerminal(handle);
+  assertRailReadOnlyCommitWorkspaceUnchanged({ workspace: reviewWorkspace, label: 'RAIL adjudication' });
+  while (handle.exitCode !== 0 && retries < max_retries && isTransientFailure(handle.exitCode, [...handle.stdout, ...handle.stderr])) {
+    assertLease();
+    retries += 1;
+    await new Promise((done) => setTimeout(done, 2_000 * (2 ** (retries - 1))));
+    assertLease();
+    ({ handle, exactInvocation } = await spawnAdjudicationAttempt(retries));
+    await waitForTerminal(handle);
+    assertRailReadOnlyCommitWorkspaceUnchanged({ workspace: reviewWorkspace, label: 'RAIL adjudication retry' });
+  }
+  const adjudicationOutput = (handle.stdout || []).join('');
+  const terminalOutput = `${adjudicationOutput}${(handle.stderr || []).join('')}`;
+  if (handle.exitCode !== 0) fail('RAIL_ADJUDICATOR_FAILED', `${exactInvocation.harness_id} exited with status ${handle.exitCode}`, { output: terminalOutput.slice(0, 10_000) });
+  return Object.freeze({
+    invocation: exactInvocation,
+    decision: parseDecision(adjudicationOutput),
+    adjudication_output: adjudicationOutput,
+    terminal_authority_receipt: getTerminalCompletionAuthorityReceipt(handle),
+    retry_count: retries,
+  });
+}
+
+function unanimous(entries) {
+  return adjudicationEntriesAgree(entries);
+}
+
+export async function executeRailAdjudication({
+  projectDir, handoff_id, attempt_id,
+  timeout = 30 * 60 * 1000, max_retries = 2, lease_ttl_ms = 5 * 60 * 1000,
+} = {}) {
+  if (!projectDir || !handoff_id || !attempt_id) fail('RAIL_ADJUDICATION_INPUT_REQUIRED', 'projectDir, handoff_id and attempt_id are required');
+  let context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id });
+  if (context.state !== 'active') fail('RAIL_ADJUDICATION_ATTEMPT_INACTIVE', `attempt is ${context.state}`);
+  if (context.records.some((record) => record.type === 'adjudication_decided' && record.payload?.attempt_id === attempt_id)) {
+    fail('RAIL_ADJUDICATION_ALREADY_RECORDED', 'this attempt already has an immutable adjudication decision');
+  }
+  const plan = latestAdjudicationPlan(context);
+  const artifact = loadRuntimeInstallationV2(projectDir);
+  const reviews = listRailReviewEvidence({ projectDir, attempt_id });
+  const executions = listRailExecutionEvidence({ projectDir, attempt_id });
+  const ownership = acquireRailTaskSupervisor({ projectDir, handoff_id, attempt_id, lease_ttl_ms });
+  context = ownership.context;
+  const renewed = ownership.renewed;
+  let activeHandle = null;
+  let attemptClosed = false;
+  let reviewWorkspace = null;
+  try {
+  const resolvedReviewSubject = resolveReviewGitSubject({ projectDir, attempt_id });
+  reviewWorkspace = createRailReadOnlyCommitWorkspace({
+    projectDir,
+    baseCommitRef: resolvedReviewSubject.base_commit_ref,
+    resultCommitRef: resolvedReviewSubject.result_commit_ref,
+  });
+  const immutableReviewSubject = Object.freeze({
+    base_commit_ref: resolvedReviewSubject.base_commit_ref,
+    result_commit_ref: resolvedReviewSubject.result_commit_ref,
+    workspace_digest: sha256(reviewWorkspace.baseline),
+  });
+  const heartbeat = startClaimHeartbeat({
+    projectDir, handoff_id, attempt_id, claim_id: context.claim.claim_id,
+    operator_id: ownership.operator_id, lease_ttl_ms, initial_lease: renewed.lease,
+    activeHandle: () => activeHandle,
+  });
+  const observed = createProjectRailEngine({ projectDir }).records
+    .filter((record) => record.type === 'adjudication_observed'
+      && record.payload?.attempt_id === attempt_id
+      && record.payload?.review_ref === plan.review_ref)
+    .map((record) => record.payload.observation);
+  const rounds = [];
+  try {
+    for (let round = 1; round <= 2; round += 1) {
+      const priorDecisions = round === 1 ? [] : rounds[0].map((entry, index) => ({
+        anonymous_ref: `independent-decision-${index + 1}`,
+        decision: entry.decision,
+      }));
+      const entries = plan.decision.adjudicators.map((candidate) => observed.find((entry) =>
+        entry.round === round
+        && entry.invocation.provider_id === candidate.provider_id
+        && entry.invocation.harness_id === candidate.harness_id
+        && sha256(entry.invocation.model_pin) === sha256(candidate.model_pin))).filter(Boolean);
+      for (const invocation of plan.decision.adjudicators) {
+        if (entries.some((entry) => entry.invocation.provider_id === invocation.provider_id
+          && entry.invocation.harness_id === invocation.harness_id)) continue;
+        const entry = await invokeAdjudicator({
+          projectDir, artifact, context, plan: plan.decision, invocation, reviews, executions,
+          review_ref: plan.review_ref, priorDecisions, round, timeout, max_retries,
+          reviewWorkspace,
+          reviewSubject: immutableReviewSubject,
+          onHandle: (handle) => { activeHandle = handle; },
+          assertLease: () => {
+            if (heartbeat.evidence().failure) fail('RAIL_LEASE_HEARTBEAT_FAILED', 'adjudication lost its RAIL claim heartbeat');
+          },
+        });
+        activeHandle = null;
+        recordRailAdjudicationObservation({
+          projectDir, handoff_id, attempt_id, review_ref: plan.review_ref, entry,
+        });
+        entries.push(entry);
+      }
+      rounds.push(entries);
+      if (unanimous(entries)) break;
+    }
+  } finally { heartbeat.stop(); }
+  const heartbeatEvidence = heartbeat.evidence();
+  if (heartbeatEvidence.failure) fail('RAIL_LEASE_HEARTBEAT_FAILED', 'adjudication lost its RAIL claim heartbeat');
+  const finalEntries = rounds.at(-1);
+  if (!unanimous(finalEntries)) {
+    fail('RAIL_ADJUDICATION_NO_CONSENSUS', 'selected top-tier adjudicators did not reach consensus after reconciliation', { rounds });
+  }
+  const expectedDecision = deriveAdjudicationConsensus({ handoff_id, attempt_id, evidence: finalEntries });
+  const persisted = persistRailAdjudicationEvidence({
+    projectDir, handoff_id, attempt_id, review_ref: plan.review_ref,
+    rounds, final_decision: expectedDecision,
+  });
+  const journal = recordRailAdjudication({
+    projectDir, handoff_id, attempt_id, review_ref: plan.review_ref, evidence: finalEntries,
+  });
+  attemptClosed = journal.decision.outcome === 'handoff-revision';
+  if (sha256(journal.decision) !== sha256(expectedDecision)) {
+    fail('RAIL_ADJUDICATION_DECISION_MISMATCH', 'persisted adjudication consensus differs from the canonical journal');
+  }
+  const next = {
+    'bounded-correction': 'rail_rework_required',
+    'handoff-revision': 'planning_handoff_revision_required',
+    'blocked-authority': 'human_authority_required',
+  }[journal.decision.outcome];
+  return Object.freeze({
+    ok: true, action: 'rail_adjudication_recorded', handoff_id,
+    task_id: context.task.task_id, attempt_id,
+    adjudication_ref: journal.adjudication_ref,
+    adjudication_evidence_ref: persisted.evidence_ref,
+    decision: journal.decision,
+    council_size: finalEntries.length, rounds: rounds.length,
+    journal_event_id: journal.event_id,
+    lease_heartbeat_count: heartbeatEvidence.heartbeat_count,
+    next_required_action: next,
+  });
+  } finally {
+    let cleanupProven = !activeHandle;
+    try {
+      if (activeHandle) { await killTerminal(activeHandle); cleanupProven = true; }
+    } finally {
+      try {
+        if (cleanupProven && reviewWorkspace) cleanupRailReadOnlyCommitWorkspace(reviewWorkspace);
+      } finally {
+        if (cleanupProven && !attemptClosed) {
+          relinquishRailTask({
+            projectDir, handoff_id, attempt_id,
+            claim_id: context.claim.claim_id,
+            operator_id: ownership.operator_id,
+            reason: 'action_complete',
+          });
+        }
+      }
+    }
+  }
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 2; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) continue;
+    const value = argv[index + 1];
+    if (value && !value.startsWith('--')) { args[token.slice(2)] = value; index += 1; } else args[token.slice(2)] = true;
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  try {
+    const result = await executeRailAdjudication({
+      projectDir: resolve(args['project-dir'] || process.cwd()),
+      handoff_id: args['handoff-id'], attempt_id: args['attempt-id'],
+      ...(args.timeout ? { timeout: Number(args.timeout) } : {}),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ ok: false, action: 'error', code: error.code || 'RAIL_ADJUDICATION_FAILED', error: error.message, details: error.details })}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) await main();

package/src/terminal/run-rail-review.js

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { sha256 } from '@chati/core';
+import {
+  buildSpawnCommand, getTerminalCompletionAuthorityReceipt, getTerminalLaunchAuthorityReceipt,
+  isTransientFailure, killTerminal, spawnTerminal, waitForTerminal,
+} from './spawner.js';
+import { checkProviderReadiness } from './provider-preflight.js';
+import { getRateLimiter } from './rate-limiter.js';
+import { startClaimHeartbeat } from './run-rail-task.js';
+import {
+  acquireRailTaskSupervisor, relinquishRailTask, resolveRailAttemptContext,
+} from '../orchestrator/rail-runtime.js';
+import {
+  listRailReviewEvidence, recordRailReview, recordRailReviewDispatch, resolveReviewGitSubject,
+} from '../orchestrator/review-runtime.js';
+import {
+  loadRuntimeInstallationV2, resolveRuntimeExecutableBindingV2, resolveRuntimeRailReviewerV2,
+} from '../orchestrator/runtime-installation-v2.js';
+import { buildRailReviewPrompt } from './rail-prompts.js';
+import {
+  assertRailReadOnlyCommitWorkspaceUnchanged, cleanupRailReadOnlyCommitWorkspace,
+  createRailReadOnlyCommitWorkspace,
+} from './rail-readonly-workspace.js';
+
+export { buildRailReviewPrompt } from './rail-prompts.js';
+
+function fail(code, message, details = {}) { const error = new Error(message); error.code = code; error.details = details; throw error; }
+
+function output(handle) { return [...(handle.stdout || []), ...(handle.stderr || [])].join(''); }
+
+export function assertRailReviewIndependenceAvailable({ task, attained_independence_level } = {}) {
+  const required = task?.required_independence_level ?? 'A';
+  const order = { A: 3, B: 2, C: 1 };
+  if (!Object.hasOwn(order, required) || !Object.hasOwn(order, attained_independence_level)) {
+    fail('RAIL_REVIEW_INDEPENDENCE_POLICY_INVALID', 'review independence policy must declare A, B or C');
+  }
+  if (order[attained_independence_level] < order[required]) {
+    fail(
+      'RAIL_REVIEW_INDEPENDENCE_UNAVAILABLE',
+      `sealed routing policy requires independence ${required}, but the strongest eligible reviewer attains ${attained_independence_level}`,
+      { routing_constraints_ref: task?.routing_constraints_ref, required, attained: attained_independence_level },
+    );
+  }
+  return required;
+}
+
+function parseReviewPayload(text) {
+  const startToken = '<CHATI_RAIL_REVIEW>';
+  const endToken = '</CHATI_RAIL_REVIEW>';
+  const start = text.lastIndexOf(startToken);
+  const end = text.indexOf(endToken, start + startToken.length);
+  if (start === -1 || end === -1) return fail('RAIL_REVIEW_OUTPUT_INVALID', 'reviewer did not return the required CHATI_RAIL_REVIEW envelope');
+  try { return JSON.parse(text.slice(start + startToken.length, end).trim()); }
+  catch (error) { return fail('RAIL_REVIEW_OUTPUT_INVALID', `reviewer returned invalid JSON: ${error.message}`); }
+}
+
+export async function executeRailReview({
+  projectDir,
+  handoff_id,
+  attempt_id,
+  timeout = 30 * 60 * 1000,
+  max_retries = 2,
+  lease_ttl_ms = 5 * 60 * 1000,
+} = {}) {
+  if (!projectDir || !handoff_id || !attempt_id) fail('RAIL_REVIEW_INPUT_REQUIRED', 'projectDir, handoff_id and attempt_id are required');
+  let context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id });
+  if (!['active', 'ready_to_merge'].includes(context.state)) fail('RAIL_REVIEW_ATTEMPT_INACTIVE', `attempt is ${context.state}`);
+  const artifact = loadRuntimeInstallationV2(projectDir);
+  const builder_identity = {
+    provider_id: context.task.execution_binding.provider_id,
+    model_id: context.task.execution_binding.model_id,
+  };
+  const selected = resolveRuntimeRailReviewerV2({ artifact, builder_identity });
+  const providerExecutableBinding = resolveRuntimeExecutableBindingV2({
+    artifact, provider_id: selected.provider_id, harness_id: selected.harness_id,
+  });
+  const requiredIndependence = assertRailReviewIndependenceAvailable({
+    task: context.task,
+    attained_independence_level: selected.independence_level,
+  });
+  const existing = listRailReviewEvidence({ projectDir, attempt_id });
+  const round = existing.length + 1;
+  const readiness = checkProviderReadiness(selected.harness_id, {
+    workingDir: projectDir, executableBinding: providerExecutableBinding,
+  });
+  if (!readiness.ready) fail(readiness.code || 'PROVIDER_NOT_READY', readiness.detail || `${selected.harness_id} is not ready`);
+  const reviewSubject = resolveReviewGitSubject({ projectDir, attempt_id });
+  const ownership = acquireRailTaskSupervisor({ projectDir, handoff_id, attempt_id, lease_ttl_ms });
+  context = ownership.context;
+  const renewed = ownership.renewed;
+  let handle;
+  let reviewWorkspace;
+  try {
+  reviewWorkspace = createRailReadOnlyCommitWorkspace({
+    projectDir,
+    baseCommitRef: reviewSubject.base_commit_ref,
+    resultCommitRef: reviewSubject.result_commit_ref,
+  });
+  const immutableReviewSubject = Object.freeze({
+    ...reviewSubject,
+    workspace_digest: sha256(reviewWorkspace.baseline),
+  });
+  const spawnReviewAttempt = async (retry, assertLease = () => {}) => {
+    const invocationDraft = {
+      provider_id: selected.provider_id, harness_id: selected.harness_id,
+      action: 'review', attempt_id, model_pin: selected.model_pin,
+      invocation_id: `rail-review-${attempt_id}-${round}-${retry + 1}`,
+      launch_nonce: randomUUID(),
+      language: context.language,
+    };
+    const prompt = buildRailReviewPrompt({
+      projectDir: reviewWorkspace.subject_dir,
+      context,
+      invocation: invocationDraft,
+      reviewSubject: immutableReviewSubject,
+      round,
+    });
+    const invocation = Object.freeze({ ...invocationDraft, prompt_digest: sha256(prompt) });
+    const config = {
+      agent: 'rail-review', taskId: context.task.task_id,
+      provider: invocation.harness_id, providerId: invocation.provider_id,
+      model: invocation.model_pin.model_id,
+      reasoningConfiguration: invocation.model_pin.reasoning_configuration,
+      catalogSnapshotRef: invocation.model_pin.catalog_snapshot_ref,
+      providerExecutableBinding,
+      prompt,
+      workingDir: reviewWorkspace.subject_dir, timeout, writeScope: [],
+      auditProjectDir: projectDir,
+      maskedReadPaths: [projectDir],
+      authorityContext: {
+        authority_kind: 'rail_review', invocation_id: invocation.invocation_id,
+        launch_nonce: invocation.launch_nonce, provider_id: invocation.provider_id,
+      },
+      beforeProcessSpawn: () => assertRailReadOnlyCommitWorkspaceUnchanged({
+        workspace: reviewWorkspace,
+        label: 'RAIL review pre-spawn',
+      }),
+    };
+    const built = buildSpawnCommand(config);
+    if (built.actualProvider !== config.provider || built.actualModel !== config.model
+      || built.actualReasoningConfiguration !== config.reasoningConfiguration) {
+      fail('RAIL_REVIEW_ROUTE_MISMATCH', 'terminal adapter changed the selected review binding');
+    }
+    await getRateLimiter(invocation.harness_id).waitForSlot();
+    assertLease();
+    handle = spawnTerminal(config);
+    try {
+      recordRailReviewDispatch({
+        projectDir, attempt_id, invocation,
+        launch_receipt: getTerminalLaunchAuthorityReceipt(handle),
+        prompt,
+        reviewWorkspace,
+      });
+    } catch (error) {
+      await killTerminal(handle);
+      throw error;
+    }
+    return { handle, invocation };
+  };
+  let invocation;
+  const heartbeat = startClaimHeartbeat({
+    projectDir, handoff_id, attempt_id, claim_id: context.claim.claim_id,
+    operator_id: ownership.operator_id, lease_ttl_ms, initial_lease: renewed.lease,
+    activeHandle: () => handle,
+  });
+  let retries = 0;
+  try {
+    ({ handle, invocation } = await spawnReviewAttempt(0, () => {
+      if (heartbeat.evidence().failure) fail('RAIL_LEASE_HEARTBEAT_FAILED', 'review lost its RAIL claim heartbeat');
+    }));
+    await waitForTerminal(handle);
+    assertRailReadOnlyCommitWorkspaceUnchanged({ workspace: reviewWorkspace, label: 'RAIL review' });
+    while (handle.exitCode !== 0 && retries < max_retries && isTransientFailure(handle.exitCode, [...handle.stdout, ...handle.stderr])) {
+      if (heartbeat.evidence().failure) break;
+      retries += 1;
+      await new Promise((done) => setTimeout(done, 2_000 * (2 ** (retries - 1))));
+      if (heartbeat.evidence().failure) break;
+      ({ handle, invocation } = await spawnReviewAttempt(retries, () => {
+        if (heartbeat.evidence().failure) fail('RAIL_LEASE_HEARTBEAT_FAILED', 'review lost its RAIL claim heartbeat');
+      }));
+      await waitForTerminal(handle);
+      assertRailReadOnlyCommitWorkspaceUnchanged({ workspace: reviewWorkspace, label: 'RAIL review retry' });
+    }
+  } finally { heartbeat.stop(); }
+  const heartbeatEvidence = heartbeat.evidence();
+  if (heartbeatEvidence.failure) fail('RAIL_LEASE_HEARTBEAT_FAILED', 'review lost its RAIL claim heartbeat');
+  if (handle.exitCode !== 0) fail('RAIL_REVIEW_PROVIDER_FAILED', `reviewer exited with status ${handle.exitCode}`, { output: output(handle).slice(0, 10_000) });
+  const payload = parseReviewPayload(output(handle));
+  const review_id = `review-${round}-${sha256(payload).slice(0, 16)}`;
+  const review = {
+    review_id,
+    attempt_id,
+    reviewer_invocation_ref: invocation.invocation_id,
+    rubric_ref: context.task.routing_constraints_ref,
+    review_round: round,
+    required_independence_level: requiredIndependence,
+    attained_independence_level: selected.independence_level,
+    builder_identity,
+    reviewer_identity: { provider_id: invocation.provider_id, model_id: invocation.model_pin.model_id },
+    clean_context: true,
+    degradation: { status: 'none' },
+    findings: payload.findings ?? [],
+    verdict: payload.verdict,
+    impasse: payload.impasse ?? { kind: 'none' },
+    ...(payload.authority_reason ? { authority_reason: payload.authority_reason } : {}),
+    ...(payload.authority_reason_ref ? { authority_reason_ref: payload.authority_reason_ref } : {}),
+  };
+  const recorded = recordRailReview({
+    projectDir,
+    review,
+    review_output: (handle.stdout || []).join(''),
+    terminal_authority_receipt: getTerminalCompletionAuthorityReceipt(handle),
+    invocation,
+    result_commit_ref: reviewSubject.result_commit_ref,
+  });
+  const next = {
+    accept: 'rail_completion_required',
+    'normal-rework': 'rail_rework_required',
+    AI_ADJUDICATION: 'rail_adjudication_required',
+    'required-human-decision': 'human_authority_required',
+    blocked: 'rail_blocked',
+  }[recorded.decision.decision] || 'rail_blocked';
+  return Object.freeze({
+    ok: recorded.decision.decision === 'accept',
+    action: 'rail_review_recorded',
+    handoff_id,
+    task_id: context.task.task_id,
+    attempt_id,
+    invocation,
+    review_ref: recorded.review_ref,
+    decision: recorded.decision,
+    review: recorded.review,
+    retry_count: retries,
+    lease_heartbeat_count: heartbeatEvidence.heartbeat_count,
+    next_required_action: next,
+  });
+  } finally {
+    let cleanupProven = !handle;
+    try {
+      if (handle) { await killTerminal(handle); cleanupProven = true; }
+    } finally {
+      try {
+        if (cleanupProven && reviewWorkspace) cleanupRailReadOnlyCommitWorkspace(reviewWorkspace);
+      } finally {
+        if (cleanupProven) {
+          relinquishRailTask({
+            projectDir, handoff_id, attempt_id,
+            claim_id: context.claim.claim_id,
+            operator_id: ownership.operator_id,
+            reason: 'action_complete',
+          });
+        }
+      }
+    }
+  }
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 2; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) continue;
+    const value = argv[index + 1];
+    if (value && !value.startsWith('--')) { args[token.slice(2)] = value; index += 1; }
+    else args[token.slice(2)] = true;
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  try {
+    const result = await executeRailReview({
+      projectDir: resolve(args['project-dir'] || process.cwd()),
+      handoff_id: args['handoff-id'],
+      attempt_id: args['attempt-id'],
+      ...(args.timeout ? { timeout: Number(args.timeout) } : {}),
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (!result.ok && !['rail_rework_required', 'rail_adjudication_required', 'human_authority_required'].includes(result.next_required_action)) process.exitCode = 1;
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ ok: false, action: 'error', code: error.code || 'RAIL_REVIEW_FAILED', error: error.message })}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) await main();