chati-dev 4.5.27 → 4.5.29

package/src/orchestrator/rail-runtime.js

@@ -1,17 +1,34 @@
 import {
-  closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, mkdirSync, openSync,
-  readSync, unlinkSync, writeSync, realpathSync,
+  closeSync, constants, existsSync, fstatSync, fsyncSync, openSync,
+  readSync, writeSync, realpathSync,
 } from 'node:fs';
 import { basename, dirname, join, parse, resolve, sep } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { sha256 } from '@chati/core';
-import { adjudicationAttemptState, adjudicationEntriesAgree, RailEngine } from '@chati/rail';
-import { validateSealedHandoff } from '@chati/planning';
+import {
+  canonicalSerialize, canonicalize, directoryPathSync, linkAtSync, mkdirAtSync,
+  openAtSync, sha256, unlinkAtSync,
+} from '@chati/core';
+import { adjudicationAttemptState, adjudicationEntriesAgree, attemptExecutionBase, attemptJournalRevision, RailEngine } from '@chati/rail';
+import { validatePlanningMaterial, validateSealedHandoff } from '@chati/planning';
 import { validateAdjudicationDecision } from '@chati/review-council';
-import { loadRuntimeInstallationV2, resolveRuntimeRailInvocationV2 } from './runtime-installation-v2.js';
+import {
+  loadRuntimeInstallationV2,
+  resolveRuntimeCouncilGatePolicyV2,
+  resolveRuntimeRailInvocationV2,
+} from './runtime-installation-v2.js';
+import { assertCouncilGateApproved } from './council-gate-runtime.js';
+import {
+  persistImmutableInstallationFile,
+  readSafeInstallationStorageFile,
+} from '../installer-v2/catalog-client.js';
+import { signHostAuthorityPayload, verifyHostAuthorityPayload } from '../installer-v2/installation-authority.js';
 import { createProjectBrowserSession, launchProjectBrowserSession } from './browser-runtime.js';
 import { enqueueClickUpProjectionFromState } from './clickup-projection.js';
 import { verifyTerminalAuthorityReceipt } from '../terminal/spawner.js';
+import { captureRailWorktreeCheckpoint, readRailWorktreeCheckpoint } from '../terminal/rail-worktree-checkpoint.js';
+import { restoreRailWorktreeCheckpoint, readRailWorktreeRestoration } from '../terminal/rail-worktree-restoration.js';
+import { verifyHumanEffortReceipt } from './rail-human-effort-authority.js';
+import { assertLocalBrowserArtifacts } from './browser-artifact-store.js';
 import { buildRailAdjudicationPrompt, buildRailReworkPrompt, buildRailTaskPrompt } from '../terminal/rail-prompts.js';
 import { readSessionSafe } from './session-manager.js';
 import { assertRailReadOnlyCommitWorkspaceUnchanged } from '../terminal/rail-readonly-workspace.js';
@@ -22,7 +39,9 @@ import {
 } from '@chati/tracking-clickup';
 
 export const RAIL_V2_DIR = '.chati/v2/rail';
+export const RAIL_COUNCIL_BINDING_AUTHORITY_DOMAIN = 'chati.rail-execution-design-binding.v1';
 const HANDOFF_MAX_BYTES = 4 * 1024 * 1024;
+const EXECUTION_DESIGN_TASK_GRAPH_PATH = '.chati/v2/planning/tasks.json';
 
 function fail(code, message, cause) {
   const error = new Error(message, cause ? { cause } : undefined);
@@ -91,8 +110,8 @@ function readDescriptorBounded(descriptor, maxBytes) {
 }
 
 function openPinnedHandoffDirectory(path, { create = false } = {}) {
-  if (process.platform !== 'linux') {
-    fail('UNSUPPORTED_HANDOFF_STORAGE_PLATFORM', 'RAIL handoff authority storage requires Linux descriptor-relative filesystem operations');
+  if (!['linux', 'darwin'].includes(process.platform)) {
+    fail('UNSUPPORTED_HANDOFF_STORAGE_PLATFORM', `RAIL handoff authority storage requires descriptor-relative operations; unsupported platform: ${process.platform}`);
   }
   const absolute = resolve(path);
   const root = parse(absolute).root;
@@ -100,10 +119,9 @@ function openPinnedHandoffDirectory(path, { create = false } = {}) {
   let descriptor = openSync(root, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
   try {
     for (const segment of segments) {
-      const childPath = join(`/proc/self/fd/${descriptor}`, segment);
       let childDescriptor;
       try {
-        childDescriptor = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        childDescriptor = openAtSync(descriptor, segment, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
       } catch (error) {
         if (error?.code !== 'ENOENT' || !create) {
           if (['ELOOP', 'ENOTDIR'].includes(error?.code)) {
@@ -111,9 +129,9 @@ function openPinnedHandoffDirectory(path, { create = false } = {}) {
           }
           throw error;
         }
-        try { mkdirSync(childPath, { mode: 0o700 }); }
+        try { mkdirAtSync(descriptor, segment, { mode: 0o700 }); }
         catch (mkdirError) { if (mkdirError?.code !== 'EEXIST') throw mkdirError; }
-        childDescriptor = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+        childDescriptor = openAtSync(descriptor, segment, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
       }
       const stat = fstatSync(childDescriptor);
       if (!stat.isDirectory()) {
@@ -127,7 +145,6 @@ function openPinnedHandoffDirectory(path, { create = false } = {}) {
       absolute,
       descriptor,
       identity: fstatSync(descriptor),
-      reference: `/proc/self/fd/${descriptor}`,
     });
   } catch (error) {
     closeSync(descriptor);
@@ -135,13 +152,6 @@ function openPinnedHandoffDirectory(path, { create = false } = {}) {
   }
 }
 
-function handoffEntryPath(directory, name) {
-  if (basename(name) !== name || name === '.' || name === '..') {
-    fail('UNSAFE_HANDOFF_STORAGE', 'handoff storage entry must be one path segment');
-  }
-  return join(directory.reference, name);
-}
-
 function assertPinnedHandoffDirectory(directory) {
   const descriptorStat = fstatSync(directory.descriptor);
   if (!descriptorStat.isDirectory() || !sameIdentity(descriptorStat, directory.identity)) {
@@ -167,11 +177,10 @@ function readHandoffContent(path, { allowMissing = false, directory = null } = {
     try { activeDirectory = openPinnedHandoffDirectory(dirname(path)); }
     catch (error) { if (allowMissing && error?.code === 'ENOENT') return null; throw error; }
   }
-  const entry = handoffEntryPath(activeDirectory, basename(path));
   runSecurityTestHook('beforeHandoffOpen', { path, directory: activeDirectory.absolute });
   let descriptor;
   try {
-    descriptor = openSync(entry, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    descriptor = openAtSync(activeDirectory.descriptor, basename(path), constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
   } catch (error) {
     if (ownedDirectory) closeSync(activeDirectory.descriptor);
     if (allowMissing && error?.code === 'ENOENT') return null;
@@ -218,6 +227,143 @@ export function getRailPaths(projectDir) {
   });
 }
 
+function railCouncilBindingPath(projectDir, handoff_id) {
+  return join(getRailPaths(projectDir).root, 'council', `${handoff_id}.json`);
+}
+
+function approvedTaskGraphReference(approval) {
+  const taskGraph = approval?.plan?.artifacts?.find((artifact) => artifact.path === EXECUTION_DESIGN_TASK_GRAPH_PATH);
+  if (!taskGraph || !/^[a-f0-9]{64}$/i.test(taskGraph.sha256)) {
+    fail('RAIL_COUNCIL_BINDING_INVALID', 'RAIL execution-design council approval has no valid frozen task graph digest');
+  }
+  return `local-artifact://sha256/${taskGraph.sha256}`;
+}
+
+function railCouncilBindingMaterial(handoff, approval) {
+  const validated = validateSealedHandoff(handoff);
+  if (!approval?.plan?.gate_id || !approval?.decision) {
+    fail('RAIL_COUNCIL_BINDING_INVALID', 'RAIL council binding requires an approved execution-design decision');
+  }
+  const task_graph_ref = approvedTaskGraphReference(approval);
+  if (validated.task_graph_ref !== task_graph_ref) {
+    fail('RAIL_COUNCIL_TASK_GRAPH_MISMATCH', 'RAIL handoff task graph is not the exact task graph approved by the execution-design council', {
+      handoff_task_graph_ref: validated.task_graph_ref,
+      council_task_graph_ref: task_graph_ref,
+    });
+  }
+  if (approval.plan.handoff_manifest_digest !== validated.seal.manifest_digest) {
+    fail('RAIL_COUNCIL_HANDOFF_MISMATCH', 'RAIL handoff is not the exact executable manifest reviewed by the execution-design council', {
+      handoff_manifest_digest: validated.seal.manifest_digest,
+      council_handoff_manifest_digest: approval.plan.handoff_manifest_digest,
+    });
+  }
+  return canonicalize({
+    record_type: 'chati-rail-execution-design-binding',
+    handoff_id: validated.handoff_id,
+    handoff_manifest_digest: validated.seal.manifest_digest,
+    task_graph_ref,
+    council_gate_id: approval.plan.gate_id,
+    council_decision_digest: sha256(canonicalSerialize(approval.decision)),
+  });
+}
+
+function signRailCouncilBinding(material, authorityDirectory) {
+  const signed = signHostAuthorityPayload(material, {
+    domain: RAIL_COUNCIL_BINDING_AUTHORITY_DOMAIN,
+    authorityDirectory,
+  });
+  return canonicalize({
+    ...material,
+    authority_receipt: {
+      schema_version: 1,
+      authority_id: signed.authority_id,
+      signature: signed.signature,
+    },
+  });
+}
+
+function verifyRailCouncilBinding(record, expected, authorityDirectory) {
+  const allowed = new Set([
+    'record_type', 'handoff_id', 'handoff_manifest_digest', 'council_gate_id',
+    'task_graph_ref', 'council_decision_digest', 'authority_receipt',
+  ]);
+  if (!record || typeof record !== 'object' || Array.isArray(record)
+    || Object.keys(record).some((key) => !allowed.has(key))) {
+    fail('RAIL_COUNCIL_BINDING_INVALID', 'RAIL council binding has an invalid closed schema');
+  }
+  const receipt = record.authority_receipt;
+  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)
+    || receipt.schema_version !== 1
+    || typeof receipt.authority_id !== 'string'
+    || typeof receipt.signature !== 'string') {
+    fail('RAIL_COUNCIL_BINDING_UNTRUSTED', 'RAIL council binding has no valid host authority receipt');
+  }
+  const canonical = canonicalize({
+    record_type: record.record_type,
+    handoff_id: record.handoff_id,
+    handoff_manifest_digest: record.handoff_manifest_digest,
+    task_graph_ref: record.task_graph_ref,
+    council_gate_id: record.council_gate_id,
+    council_decision_digest: record.council_decision_digest,
+  });
+  if (!verifyHostAuthorityPayload(canonical, {
+    domain: RAIL_COUNCIL_BINDING_AUTHORITY_DOMAIN,
+    authorityId: receipt.authority_id,
+    signature: receipt.signature,
+    authorityDirectory,
+  })) {
+    fail('RAIL_COUNCIL_BINDING_UNTRUSTED', 'RAIL council binding authority receipt is invalid');
+  }
+  if (canonicalSerialize(canonical) !== canonicalSerialize(expected)) {
+    fail('RAIL_COUNCIL_BINDING_STALE', 'RAIL handoff is not bound to the current approved execution-design council decision');
+  }
+}
+
+/**
+ * Persists the host-signed link between an accepted execution-design council
+ * decision and the exact immutable RAIL handoff that the compiler produced.
+ */
+export function persistRailHandoffCouncilBinding({
+  projectDir, handoff, artifact, policy, authorityDirectory, clock = () => new Date(),
+} = {}) {
+  const validated = validateSealedHandoff(handoff);
+  const approval = assertCouncilGateApproved({
+    projectDir,
+    stage: 'execution-design',
+    artifact,
+    policy,
+    handoff: validated,
+    authorityDirectory,
+    clock,
+  });
+  const material = railCouncilBindingMaterial(validated, approval);
+  const record = signRailCouncilBinding(material, authorityDirectory);
+  const path = railCouncilBindingPath(projectDir, material.handoff_id);
+  persistImmutableInstallationFile(path, `${canonicalSerialize(record)}\n`, {
+    conflictCode: 'RAIL_COUNCIL_BINDING_CONFLICT',
+    label: 'RAIL execution-design council binding',
+  });
+  return Object.freeze({ path, record, approval });
+}
+
+/** Verifies the signed execution-design approval is bound to this exact handoff. */
+export function assertRailHandoffCouncilBinding({ projectDir, handoff, approval, authorityDirectory } = {}) {
+  const expected = railCouncilBindingMaterial(handoff, approval);
+  const path = railCouncilBindingPath(projectDir, expected.handoff_id);
+  const source = readSafeInstallationStorageFile(path, {
+    allowMissing: true,
+    label: 'RAIL execution-design council binding',
+  });
+  if (source === null) {
+    fail('RAIL_COUNCIL_BINDING_MISSING', `RAIL handoff ${expected.handoff_id} has no execution-design council binding`);
+  }
+  let record;
+  try { record = JSON.parse(source.content); }
+  catch { fail('RAIL_COUNCIL_BINDING_INVALID', 'RAIL council binding is not valid JSON'); }
+  verifyRailCouncilBinding(record, expected, authorityDirectory);
+  return Object.freeze({ path, record: canonicalize(record) });
+}
+
 /** Persist one sealed planning handoff. Conflicting material is never overwritten. */
 export function persistRailHandoff({ projectDir, handoff }) {
   const validated = validateSealedHandoff(handoff);
@@ -227,8 +373,8 @@ export function persistRailHandoff({ projectDir, handoff }) {
   const directory = openPinnedHandoffDirectory(getRailPaths(projectDir).handoffs, { create: true });
   const name = basename(path);
   const temporaryName = `${name}.${process.pid}.${randomUUID()}.tmp`;
-  const temporary = handoffEntryPath(directory, temporaryName);
-  const destination = handoffEntryPath(directory, name);
+  // Diagnostic/test-hook path only. Actual reads and mutations use *at ops.
+  const temporary = join(directoryPathSync(directory.descriptor), temporaryName);
   let temporaryDescriptor;
   try {
     const existing = readHandoffContent(path, { allowMissing: true, directory });
@@ -238,7 +384,7 @@ export function persistRailHandoff({ projectDir, handoff }) {
       fail('HANDOFF_STORAGE_CONFLICT', `sealed handoff ${validated.handoff_id} already exists with different material`);
     }
     runSecurityTestHook('beforeHandoffTempOpen', { path, temporary, directory: directory.absolute });
-    temporaryDescriptor = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    temporaryDescriptor = openAtSync(directory.descriptor, temporaryName, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
     runSecurityTestHook('afterHandoffTempOpen', { path, temporary, directory: directory.absolute });
     const bytes = Buffer.from(content);
     let offset = 0;
@@ -248,7 +394,7 @@ export function persistRailHandoff({ projectDir, handoff }) {
     temporaryDescriptor = undefined;
     assertPinnedHandoffDirectory(directory);
     runSecurityTestHook('beforeHandoffCommit', { path, temporary, directory: directory.absolute });
-    try { linkSync(temporary, destination); }
+    try { linkAtSync(directory.descriptor, temporaryName, directory.descriptor, name); }
     catch (error) {
       if (error?.code !== 'EEXIST') throw error;
       const raced = readHandoffContent(path, { directory });
@@ -262,7 +408,7 @@ export function persistRailHandoff({ projectDir, handoff }) {
   } finally {
     if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
     try {
-      try { unlinkSync(temporary); fsyncSync(directory.descriptor); }
+      try { unlinkAtSync(directory.descriptor, temporaryName); fsyncSync(directory.descriptor); }
       catch { /* a descriptor-bound temporary may remain after a failed operation */ }
     } finally { closeSync(directory.descriptor); }
   }
@@ -280,15 +426,34 @@ export function loadRailHandoff({ projectDir, handoff_id }) {
   }
 }
 
-export function createProjectRailEngine({ projectDir, clock = () => new Date() }) {
+export function createProjectRailEngine({ projectDir, clock = () => new Date(), humanAuthorityDirectory }) {
   let evidenceAuthority;
   return new RailEngine({
     journal_path: getRailPaths(projectDir).journal,
     clock,
-    authority_verifier: ({ kind, receipt, expected }) => {
+    execution_checkpoint_writer: captureRailWorktreeCheckpoint,
+    execution_restoration_writer: restoreRailWorktreeCheckpoint,
+    authority_verifier: ({ kind, receipt, expected, context }) => {
+      if (kind === 'execution_restoration') {
+        readRailWorktreeRestoration({ projectDir, receipt, expected,
+          checkpointReceipt: context.checkpoint_receipt, current: context.current === true });
+        return true;
+      }
+      if (kind === 'execution_checkpoint') {
+        readRailWorktreeCheckpoint({ projectDir, receipt, expected });
+        return true;
+      }
+      if (kind === 'human_effort') return verifyHumanEffortReceipt(receipt, { projectDir,
+        authorityDirectory: humanAuthorityDirectory, expected });
       if (['ci_evidence', 'acceptance_evidence', 'browser_evidence'].includes(kind)) {
         evidenceAuthority ??= loadProjectRailEvidenceAuthority({ projectDir, clock });
-        return verifyRailEvidenceReceipt(evidenceAuthority, receipt, expected, clock);
+        const valid = verifyRailEvidenceReceipt(evidenceAuthority, receipt, expected, clock);
+        if (valid && kind === 'browser_evidence') {
+          assertLocalBrowserArtifacts({ projectDir, projectId: receipt.project_id, artifacts: context.artifacts, clock,
+            expected: { attempt_id: expected.attempt_id, commit_ref: expected.commit_ref, policy_ref: context.policy_ref,
+              browser_session_id: context.browser_session_id, captured_at: context.captured_at } });
+        }
+        return valid;
       }
       return verifyTerminalAuthorityReceipt(receipt, expected);
     },
@@ -300,6 +465,39 @@ function loadProjectRail({ projectDir, handoff_id, clock }) {
   return Object.freeze({ handoff: stored.handoff, handoff_path: stored.path, engine: createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) }) });
 }
 
+export function recordRailProviderProcessObservation({ projectDir, attempt_id, terminal_authority_receipt, terminal_output, clock } = {}) {
+  return createProjectRailEngine({ projectDir, clock }).recordProviderProcessObservation({ attempt_id, terminal_authority_receipt, terminal_output });
+}
+
+export function reconcileRailObservedExecution({ projectDir, handoff_id, attempt_id, launch_nonce, expected_attempt_event_id, clock } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.reconcileObservedExecution({ attempt_id, launch_nonce, git_dir: projectDir, expected_attempt_event_id });
+}
+
+export function observeRailInterruptedExecution({ projectDir, handoff_id, attempt_id, launch_nonce, expected_attempt_event_id, clock, termination_attestation } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.observeInterruptedExecution({ attempt_id, launch_nonce, git_dir: projectDir, expected_attempt_event_id,
+    ...(termination_attestation ? { termination_attestation } : {}) });
+}
+
+export function preserveRailInterruptedExecution({ projectDir, handoff_id, attempt_id, launch_nonce, expected_attempt_event_id, clock } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.preserveInterruptedExecution({ attempt_id, launch_nonce, git_dir: projectDir, expected_attempt_event_id });
+}
+
+export function collectRailProviderProcessing({ projectDir, attempt_id, clock } = {}) {
+  return createProjectRailEngine({ projectDir, clock }).providerProcessingForAttempt(attempt_id);
+}
+
+export function restoreRailInterruptedExecution({ projectDir, handoff_id, attempt_id, launch_nonce, expected_attempt_event_id, clock } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.restoreInterruptedExecution({ attempt_id, launch_nonce, git_dir: projectDir, expected_attempt_event_id });
+}
+
 function internalTrackingInstallation(projectDir, clock) {
   const artifact = loadRuntimeInstallationV2(projectDir, { ...(clock === undefined ? {} : { clock }) });
   return artifact?.installation?.external_integrations?.clickup === 'required';
@@ -518,15 +716,34 @@ export function selectRailReleaseReadiness({ projectDir, handoff_id, clock } = {
  * harness adapter with the installation-selected binding. There is no provider
  * fallback and no direct CLI invocation in this boundary.
  */
-export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt_id, operator_id, adapter, browser_request, git_dir = projectDir, lease_ttl_ms, recover_expired = false, clock } = {}) {
+export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt_id, operator_id, adapter, browser_request, git_dir = projectDir, lease_ttl_ms, recover_expired = false, clock, expected_attempt_event_id } = {}) {
   if (!adapter || typeof adapter.invoke !== 'function') fail('HARNESS_ADAPTER_UNAVAILABLE', 'RAIL dispatch requires an injected harness adapter');
   const installation = loadRuntimeInstallationV2(projectDir, { ...(clock === undefined ? {} : { clock }) });
   if (!installation) fail('V2_INSTALLATION_REQUIRED', 'RAIL dispatch requires a v2 installation');
-  const language = projectRailLanguage(projectDir);
   const { handoff, handoff_path, engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  // Old reference-only handoffs remain readable for history/recovery, but must
+  // be regenerated before dispatch. Fail before a claim or provider side effect.
+  validatePlanningMaterial(handoff, { required: true });
+  const council = resolveRuntimeCouncilGatePolicyV2({ artifact: installation, stage: 'execution-design' });
+  if (!council.enabled && council.reason === 'GUIDED_COUNCIL_REQUIRED') {
+    fail('GUIDED_COUNCIL_REQUIRED', 'RAIL dispatch requires installation reconfiguration with two selected review providers');
+  }
+  const councilApproval = council.enabled
+    ? assertCouncilGateApproved({
+      projectDir,
+      stage: 'execution-design',
+      artifact: installation,
+      policy: council.policy,
+      handoff,
+      ...(clock === undefined ? {} : { clock }),
+    })
+    : null;
+  const language = projectRailLanguage(projectDir);
+  if (councilApproval) assertRailHandoffCouncilBinding({ projectDir, handoff, approval: councilApproval });
   const priorClaim = engine.records.find((record) => record.type === 'attempt_claimed'
     && record.payload?.attempt?.attempt_id === attempt_id);
   let resumedContext = null;
+  let expectedRevision = expected_attempt_event_id ?? attemptJournalRevision(engine.records, attempt_id);
   let selection = null;
   if (priorClaim) {
     resumedContext = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
@@ -544,13 +761,16 @@ export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt
           supervisor_process_id: currentProcessId,
         });
       }
+      globalThis[Symbol.for('chati.rail.security-test-hooks')]?.beforeRecoveryAcquisition?.({ attempt_id });
       engine.recoverAttempt({
         attempt_id,
         operator_id,
         harness_process_id: currentProcessId,
         git_dir,
+        expected_attempt_event_id: expectedRevision,
         ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
       });
+      expectedRevision = undefined;
       resumedContext = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
     } else if (resumedContext.claim.operator_id !== operator_id) {
       fail('CLAIM_OWNER_MISMATCH', 'retry requires the active claim owner');
@@ -586,6 +806,7 @@ export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt
       claim_id: resumedContext.claim.claim_id,
       operator_id,
       harness_process_id: `process://chati/${process.pid}`,
+      expected_attempt_event_id: expectedRevision,
       ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
     });
     claim = Object.freeze({
@@ -614,10 +835,11 @@ export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt
     invocation: invocationDraft,
     browserManifest: browser?.manifest ?? null,
     language,
+    executionBaseCommitRef: attemptExecutionBase(claim.attempt),
   });
   const invocation = Object.freeze({ ...invocationDraft, prompt_digest: sha256(prompt) });
   let launchReserved = false;
-  const reserve_launch = () => {
+  const reserve_launch = ({ admission_receipt = null } = {}) => {
     if (launchReserved) fail('EXECUTION_LAUNCH_RESERVATION_REUSED', 'terminal attempted to reserve the same provider launch more than once');
     engine.reserveExecutionLaunch({
       attempt_id,
@@ -625,16 +847,34 @@ export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt
       operator_id: claim.claim.operator_id,
       harness_process_id: `process://chati/${process.pid}`,
       invocation,
+      project_dir: projectDir, admission_receipt,
     });
     launchReserved = true;
   };
+  let dispatch;
+  const record_dispatch = (receipt) => {
+    if (!launchReserved) fail('EXECUTION_LAUNCH_NOT_RESERVED', 'terminal authority must reserve before committing dispatch');
+    if (dispatch) fail('EXECUTION_DISPATCH_CALLBACK_REUSED', 'terminal must commit a launch exactly once');
+    dispatch = engine.recordExecutionDispatch({
+      attempt_id,
+      claim_id: claim.claim.claim_id,
+      operator_id: claim.claim.operator_id,
+      invocation,
+      launch_receipt: receipt,
+      project_dir: projectDir,
+      browser_manifest: browser?.manifest ?? null,
+    });
+    return dispatch;
+  };
   const receipt = adapter.invoke({
+    attempt: claim.attempt,
     installation: installation.installation,
     snapshot: installation.capability_snapshot,
     invocation,
     prompt,
     browser_manifest: browser?.manifest ?? null,
     reserve_launch,
+    record_dispatch,
   });
   if (!launchReserved) fail('EXECUTION_LAUNCH_NOT_RESERVED', 'terminal authority must reserve the provider launch at the final pre-spawn boundary');
   if (!verifyTerminalAuthorityReceipt(receipt, {
@@ -647,15 +887,10 @@ export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt
     working_dir: resolve(projectDir),
     prompt_digest: invocation.prompt_digest,
   })) fail('UNTRUSTED_EXECUTION_DISPATCH', 'execution dispatch requires a launch receipt minted by the terminal authority');
-  const dispatch = engine.recordExecutionDispatch({
-    attempt_id,
-    claim_id: claim.claim.claim_id,
-    operator_id: claim.claim.operator_id,
-    invocation,
-    launch_receipt: receipt,
-    project_dir: projectDir,
-    browser_manifest: browser?.manifest ?? null,
-  });
+  if (!dispatch) record_dispatch(receipt);
+  else if (sha256(dispatch.launch_receipt) !== sha256(receipt)) {
+    fail('EXECUTION_DISPATCH_RECEIPT_MISMATCH', 'terminal returned a different receipt after canonical admission');
+  }
   return Object.freeze({ claim, invocation, receipt, dispatch, task_id, handoff_id, resumed: Boolean(resumedContext), browser_manifest: browser?.manifest ?? null });
 }
 
@@ -694,10 +929,11 @@ export function claimRailTask({ projectDir, handoff_id, task_id, attempt_id, ope
 }
 
 /** Renew a claim lease against the local project journal and sealed handoff. */
-export function heartbeatRailTask({ projectDir, handoff_id, attempt_id, claim_id, operator_id, lease_ttl_ms, clock } = {}) {
+export function heartbeatRailTask({ projectDir, handoff_id, attempt_id, claim_id, operator_id, lease_ttl_ms, clock, expected_attempt_event_id } = {}) {
   const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
   return engine.heartbeat({
     attempt_id, claim_id, operator_id,
+    expected_attempt_event_id,
     harness_process_id: `process://chati/${process.pid}`,
     ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
   });
@@ -710,7 +946,7 @@ export function heartbeatRailTask({ projectDir, handoff_id, attempt_id, claim_id
  */
 export function acquireRailTaskSupervisor({
   projectDir, handoff_id, attempt_id, operator_id, git_dir = projectDir,
-  lease_ttl_ms, clock,
+  lease_ttl_ms, clock, expected_attempt_event_id,
 } = {}) {
   let context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
   const effectiveOperator = operator_id ?? context.claim.operator_id;
@@ -718,10 +954,12 @@ export function acquireRailTaskSupervisor({
   const observedNow = typeof clock === 'function' ? clock() : new Date();
   const observedNowMs = observedNow instanceof Date ? observedNow.getTime() : Date.parse(observedNow);
   let recovered = false;
+  const expectedRevision = expected_attempt_event_id ?? attemptJournalRevision(context.records, attempt_id);
   if (context.claim.harness_process_id !== currentProcessId
     || Date.parse(context.claim.lease.expires_at) <= observedNowMs) {
     recoverRailTask({
       projectDir, handoff_id, attempt_id, operator_id: effectiveOperator, git_dir,
+      expected_attempt_event_id: expectedRevision,
       ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
       ...(clock === undefined ? {} : { clock }),
     });
@@ -731,6 +969,7 @@ export function acquireRailTaskSupervisor({
   const renewed = heartbeatRailTask({
     projectDir, handoff_id, attempt_id,
     claim_id: context.claim.claim_id, operator_id: effectiveOperator,
+    ...(!recovered ? { expected_attempt_event_id: expectedRevision } : {}),
     ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
     ...(clock === undefined ? {} : { clock }),
   });
@@ -799,6 +1038,7 @@ export function reserveRailRework({
 /** Persist the fail-closed rework launch intent before a provider process is created. */
 export function reserveRailReworkLaunch({
   projectDir, handoff_id, attempt_id, source_decision_ref, reservation_id, invocation, clock,
+  admission_receipt = null,
 } = {}) {
   const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
   const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
@@ -810,6 +1050,7 @@ export function reserveRailReworkLaunch({
     source_decision_ref,
     reservation_id,
     invocation,
+    project_dir: projectDir, admission_receipt,
   });
 }
 
@@ -873,7 +1114,7 @@ export function recordRailExecutionEvidence({
 
 /** Persist the fail-closed initial launch intent before a provider process is created. */
 export function reserveRailExecutionLaunch({
-  projectDir, handoff_id, attempt_id, invocation, clock,
+  projectDir, handoff_id, attempt_id, invocation, clock, admission_receipt = null,
 } = {}) {
   const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
   const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
@@ -883,6 +1124,7 @@ export function reserveRailExecutionLaunch({
     operator_id: context.claim.operator_id,
     harness_process_id: `process://chati/${process.pid}`,
     invocation,
+    project_dir: projectDir, admission_receipt,
   });
 }
 
@@ -917,10 +1159,11 @@ export function recordRailExecutionDispatch({
       projectDir, context, sourceReview, sourceAdjudication, executionHistory, baseCommitRef, invocation,
     });
   } else {
-    canonicalBaseCommitRef = context.attempt.git_commit_ref;
+    canonicalBaseCommitRef = attemptExecutionBase(context.attempt);
     canonicalPrompt = buildRailTaskPrompt({
       projectDir, stored: { path: handoff_path, handoff }, task: context.task, invocation,
       browserManifest: browser_manifest, language: invocation?.language ?? context.language,
+      executionBaseCommitRef: canonicalBaseCommitRef,
     });
   }
   if (prompt !== canonicalPrompt || invocation?.prompt_digest !== sha256(canonicalPrompt)) {
@@ -971,10 +1214,11 @@ export function loadLatestRailExecutionEvidence({ projectDir, attempt_id, clock
 }
 
 /** Recover an expired attempt only from observations derived by the canonical engine. */
-export function recoverRailTask({ projectDir, handoff_id, attempt_id, operator_id, git_dir = projectDir, lease_ttl_ms, clock } = {}) {
+export function recoverRailTask({ projectDir, handoff_id, attempt_id, operator_id, git_dir = projectDir, lease_ttl_ms, clock, expected_attempt_event_id } = {}) {
   const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
   return engine.recoverAttempt({
     attempt_id, operator_id, harness_process_id: `process://chati/${process.pid}`, git_dir,
+    expected_attempt_event_id,
     ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
   });
 }