chati-dev 4.5.16 → 4.5.27

package/src/orchestrator/rail-runtime.js

@@ -1,13 +1,28 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import {
+  closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, mkdirSync, openSync,
+  readSync, unlinkSync, 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 { RailEngine } from '@chati/rail';
+import { adjudicationAttemptState, adjudicationEntriesAgree, RailEngine } from '@chati/rail';
 import { validateSealedHandoff } from '@chati/planning';
-import { loadRuntimeInstallationV2, resolveRuntimeInvocationV2 } from './runtime-installation-v2.js';
+import { validateAdjudicationDecision } from '@chati/review-council';
+import { loadRuntimeInstallationV2, resolveRuntimeRailInvocationV2 } from './runtime-installation-v2.js';
 import { createProjectBrowserSession, launchProjectBrowserSession } from './browser-runtime.js';
 import { enqueueClickUpProjectionFromState } from './clickup-projection.js';
+import { verifyTerminalAuthorityReceipt } from '../terminal/spawner.js';
+import { buildRailAdjudicationPrompt, buildRailReworkPrompt, buildRailTaskPrompt } from '../terminal/rail-prompts.js';
+import { readSessionSafe } from './session-manager.js';
+import { assertRailReadOnlyCommitWorkspaceUnchanged } from '../terminal/rail-readonly-workspace.js';
+import { loadProjectRailEvidenceAuthority, verifyRailEvidenceReceipt } from './rail-evidence-authority.js';
+import {
+  listClickUpDocumentPaths, persistImmutableClickUpDocument,
+  readClickUpDocument, removeImmutableClickUpDocument,
+} from '@chati/tracking-clickup';
 
 export const RAIL_V2_DIR = '.chati/v2/rail';
+const HANDOFF_MAX_BYTES = 4 * 1024 * 1024;
 
 function fail(code, message, cause) {
   const error = new Error(message, cause ? { cause } : undefined);
@@ -15,6 +30,173 @@ function fail(code, message, cause) {
   throw error;
 }
 
+function projectRailLanguage(projectDir) {
+  const loaded = readSessionSafe(projectDir);
+  if (!loaded.loaded) fail('RAIL_SESSION_LANGUAGE_UNAVAILABLE', `RAIL requires canonical session language: ${loaded.error}`);
+  const language = loaded.session?.language;
+  if (!['en', 'pt', 'es', 'fr'].includes(language)) {
+    fail('RAIL_SESSION_LANGUAGE_INVALID', `unsupported canonical RAIL language: ${language}`);
+  }
+  return language;
+}
+
+function parseAuthorizedAdjudicationOutput(text) {
+  if (typeof text !== 'string') fail('RAIL_ADJUDICATION_OUTPUT_INVALID', 'adjudication_output must be a string');
+  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 || ends[0].index < starts[0].index) {
+    fail('RAIL_ADJUDICATION_OUTPUT_INVALID', 'adjudication_output must contain exactly one ordered envelope');
+  }
+  try {
+    return validateAdjudicationDecision(JSON.parse(text.slice(
+      starts[0].index + startToken.length,
+      ends[0].index,
+    ).trim()));
+  } catch (error) {
+    return fail(error.code || 'RAIL_ADJUDICATION_OUTPUT_INVALID', error.message, error);
+  }
+}
+
+function sameIdentity(left, right) {
+  return left?.dev === right?.dev && left?.ino === right?.ino;
+}
+
+function sameSnapshot(left, right) {
+  return sameIdentity(left, right)
+    && left?.mode === right?.mode
+    && left?.uid === right?.uid
+    && left?.gid === right?.gid
+    && left?.nlink === right?.nlink
+    && left?.size === right?.size
+    && left?.mtimeMs === right?.mtimeMs
+    && left?.ctimeMs === right?.ctimeMs;
+}
+
+function runSecurityTestHook(name, payload) {
+  const hook = globalThis[Symbol.for('chati.rail-runtime.security-test-hooks')]?.[name];
+  if (typeof hook === 'function') hook(payload);
+}
+
+function readDescriptorBounded(descriptor, maxBytes) {
+  const bytes = Buffer.allocUnsafe(maxBytes + 1);
+  let offset = 0;
+  while (offset < bytes.length) {
+    const count = readSync(descriptor, bytes, offset, bytes.length - offset, null);
+    if (count === 0) break;
+    offset += count;
+  }
+  return bytes.subarray(0, offset);
+}
+
+function openPinnedHandoffDirectory(path, { create = false } = {}) {
+  if (process.platform !== 'linux') {
+    fail('UNSUPPORTED_HANDOFF_STORAGE_PLATFORM', 'RAIL handoff authority storage requires Linux descriptor-relative filesystem operations');
+  }
+  const absolute = resolve(path);
+  const root = parse(absolute).root;
+  const segments = absolute.slice(root.length).split(sep).filter(Boolean);
+  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));
+      } catch (error) {
+        if (error?.code !== 'ENOENT' || !create) {
+          if (['ELOOP', 'ENOTDIR'].includes(error?.code)) {
+            fail('UNSAFE_HANDOFF_STORAGE', 'handoff directory chain must contain only real directories');
+          }
+          throw error;
+        }
+        try { mkdirSync(childPath, { mode: 0o700 }); }
+        catch (mkdirError) { if (mkdirError?.code !== 'EEXIST') throw mkdirError; }
+        childDescriptor = openSync(childPath, constants.O_RDONLY | (constants.O_DIRECTORY || 0) | (constants.O_NOFOLLOW || 0));
+      }
+      const stat = fstatSync(childDescriptor);
+      if (!stat.isDirectory()) {
+        closeSync(childDescriptor);
+        fail('UNSAFE_HANDOFF_STORAGE', 'handoff directory chain must contain only real directories');
+      }
+      closeSync(descriptor);
+      descriptor = childDescriptor;
+    }
+    return Object.freeze({
+      absolute,
+      descriptor,
+      identity: fstatSync(descriptor),
+      reference: `/proc/self/fd/${descriptor}`,
+    });
+  } catch (error) {
+    closeSync(descriptor);
+    throw error;
+  }
+}
+
+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)) {
+    fail('UNSAFE_HANDOFF_STORAGE', 'pinned handoff directory descriptor changed');
+  }
+  let current;
+  try { current = openPinnedHandoffDirectory(directory.absolute); }
+  catch (error) {
+    if (error?.code === 'UNSAFE_HANDOFF_STORAGE') throw error;
+    fail('UNSAFE_HANDOFF_STORAGE', 'handoff directory chain changed during storage', error);
+  }
+  try {
+    if (!sameIdentity(current.identity, directory.identity)) {
+      fail('UNSAFE_HANDOFF_STORAGE', 'handoff directory chain changed during storage');
+    }
+  } finally { closeSync(current.descriptor); }
+}
+
+function readHandoffContent(path, { allowMissing = false, directory = null } = {}) {
+  let activeDirectory = directory;
+  const ownedDirectory = activeDirectory === null;
+  if (ownedDirectory) {
+    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));
+  } catch (error) {
+    if (ownedDirectory) closeSync(activeDirectory.descriptor);
+    if (allowMissing && error?.code === 'ENOENT') return null;
+    if (['ELOOP', 'ENXIO', 'EISDIR'].includes(error?.code)) fail('UNSAFE_HANDOFF_STORAGE', 'handoff must not be a symlink, FIFO or directory');
+    throw error;
+  }
+  try {
+    const before = fstatSync(descriptor);
+    if (!before.isFile() || before.nlink !== 1) fail('UNSAFE_HANDOFF_STORAGE', 'handoff must be a regular single-link file');
+    if (before.size > HANDOFF_MAX_BYTES) fail('HANDOFF_SIZE_LIMIT', 'handoff exceeds the 4 MiB safety limit');
+    runSecurityTestHook('afterHandoffStat', { path, descriptor });
+    const content = readDescriptorBounded(descriptor, HANDOFF_MAX_BYTES);
+    if (content.length > HANDOFF_MAX_BYTES) fail('HANDOFF_SIZE_LIMIT', 'handoff exceeds the 4 MiB safety limit');
+    const after = fstatSync(descriptor);
+    if (!after.isFile() || after.nlink !== 1 || !sameSnapshot(before, after)) {
+      fail('HANDOFF_STORAGE_CONFLICT', 'handoff changed while it was being read');
+    }
+    assertPinnedHandoffDirectory(activeDirectory);
+    return content.toString('utf8');
+  } finally {
+    closeSync(descriptor);
+    if (ownedDirectory) closeSync(activeDirectory.descriptor);
+  }
+}
+
 function handoffPath(projectDir, handoffId) {
   if (typeof handoffId !== 'string' || handoffId.trim() === '') fail('INVALID_HANDOFF_ID', 'handoff_id is required');
   if (!/^[A-Za-z0-9._-]+$/.test(handoffId)) fail('INVALID_HANDOFF_ID', 'handoff_id contains unsupported path characters');
@@ -41,33 +223,57 @@ export function persistRailHandoff({ projectDir, handoff }) {
   const validated = validateSealedHandoff(handoff);
   const path = handoffPath(projectDir, validated.handoff_id);
   const content = `${JSON.stringify(validated, null, 2)}\n`;
-  if (existsSync(path)) {
-    const existing = readFileSync(path, 'utf8');
-    if (existing === content) return Object.freeze({ path, handoff: validated, written: false });
-    fail('HANDOFF_STORAGE_CONFLICT', `sealed handoff ${validated.handoff_id} already exists with different material`);
-  }
-  mkdirSync(getRailPaths(projectDir).handoffs, { recursive: true, mode: 0o700 });
-  const temporary = `${path}.${process.pid}.tmp`;
+  if (Buffer.byteLength(content) > HANDOFF_MAX_BYTES) fail('HANDOFF_SIZE_LIMIT', 'sealed handoff exceeds the 4 MiB safety limit');
+  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);
+  let temporaryDescriptor;
   try {
-    writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
-    linkSync(temporary, path);
-  } catch (error) {
-    if (error?.code === 'EEXIST' && existsSync(path) && readFileSync(path, 'utf8') === content) {
-      return Object.freeze({ path, handoff: validated, written: false });
+    const existing = readHandoffContent(path, { allowMissing: true, directory });
+    assertPinnedHandoffDirectory(directory);
+    if (existing !== null) {
+      if (existing === content) return Object.freeze({ path, handoff: validated, written: false });
+      fail('HANDOFF_STORAGE_CONFLICT', `sealed handoff ${validated.handoff_id} already exists with different material`);
     }
-    if (error?.code === 'EEXIST') fail('HANDOFF_STORAGE_CONFLICT', `sealed handoff ${validated.handoff_id} already exists`, error);
-    throw error;
+    runSecurityTestHook('beforeHandoffTempOpen', { path, temporary, directory: directory.absolute });
+    temporaryDescriptor = openSync(temporary, 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;
+    while (offset < bytes.length) offset += writeSync(temporaryDescriptor, bytes, offset, bytes.length - offset);
+    fsyncSync(temporaryDescriptor);
+    closeSync(temporaryDescriptor);
+    temporaryDescriptor = undefined;
+    assertPinnedHandoffDirectory(directory);
+    runSecurityTestHook('beforeHandoffCommit', { path, temporary, directory: directory.absolute });
+    try { linkSync(temporary, destination); }
+    catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      const raced = readHandoffContent(path, { directory });
+      if (raced === content) return Object.freeze({ path, handoff: validated, written: false });
+      fail('HANDOFF_STORAGE_CONFLICT', `sealed handoff ${validated.handoff_id} raced with different material`, error);
+    }
+    runSecurityTestHook('afterHandoffCommit', { path, temporary, directory: directory.absolute });
+    assertPinnedHandoffDirectory(directory);
+    fsyncSync(directory.descriptor);
+    return Object.freeze({ path, handoff: validated, written: true });
   } finally {
-    if (existsSync(temporary)) unlinkSync(temporary);
+    if (temporaryDescriptor !== undefined) closeSync(temporaryDescriptor);
+    try {
+      try { unlinkSync(temporary); fsyncSync(directory.descriptor); }
+      catch { /* a descriptor-bound temporary may remain after a failed operation */ }
+    } finally { closeSync(directory.descriptor); }
   }
-  return Object.freeze({ path, handoff: validated, written: true });
 }
 
 export function loadRailHandoff({ projectDir, handoff_id }) {
   const path = handoffPath(projectDir, handoff_id);
-  if (!existsSync(path)) fail('HANDOFF_NOT_FOUND', `no sealed handoff exists for ${handoff_id}`);
   try {
-    return Object.freeze({ path, handoff: validateSealedHandoff(JSON.parse(readFileSync(path, 'utf8'))) });
+    const content = readHandoffContent(path, { allowMissing: true });
+    if (content === null) fail('HANDOFF_NOT_FOUND', `no sealed handoff exists for ${handoff_id}`);
+    return Object.freeze({ path, handoff: validateSealedHandoff(JSON.parse(content)) });
   } catch (error) {
     if (error?.code) throw error;
     return fail('INVALID_STORED_HANDOFF', `sealed handoff ${handoff_id} cannot be read`, error);
@@ -75,12 +281,23 @@ export function loadRailHandoff({ projectDir, handoff_id }) {
 }
 
 export function createProjectRailEngine({ projectDir, clock = () => new Date() }) {
-  return new RailEngine({ journal_path: getRailPaths(projectDir).journal, clock });
+  let evidenceAuthority;
+  return new RailEngine({
+    journal_path: getRailPaths(projectDir).journal,
+    clock,
+    authority_verifier: ({ kind, receipt, expected }) => {
+      if (['ci_evidence', 'acceptance_evidence', 'browser_evidence'].includes(kind)) {
+        evidenceAuthority ??= loadProjectRailEvidenceAuthority({ projectDir, clock });
+        return verifyRailEvidenceReceipt(evidenceAuthority, receipt, expected, clock);
+      }
+      return verifyTerminalAuthorityReceipt(receipt, expected);
+    },
+  });
 }
 
 function loadProjectRail({ projectDir, handoff_id, clock }) {
   const stored = loadRailHandoff({ projectDir, handoff_id });
-  return Object.freeze({ handoff: stored.handoff, engine: createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) }) });
+  return Object.freeze({ handoff: stored.handoff, handoff_path: stored.path, engine: createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) }) });
 }
 
 function internalTrackingInstallation(projectDir, clock) {
@@ -120,15 +337,7 @@ function trackingIntentPath(projectDir, intent) {
 function prepareTrackingIntent(projectDir, intent) {
   const normalized = Object.freeze({ schema_version: 1, ...intent });
   const path = trackingIntentPath(projectDir, normalized);
-  const content = `${JSON.stringify(normalized, null, 2)}\n`;
-  mkdirSync(trackingIntentDirectory(projectDir), { recursive: true, mode: 0o700 });
-  if (existsSync(path)) {
-    if (readFileSync(path, 'utf8') !== content) fail('TRACKING_INTENT_CONFLICT', 'tracking intent path contains different material');
-    return path;
-  }
-  const temporary = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
-  renameSync(temporary, path);
+  persistImmutableClickUpDocument(path, normalized, { maxBytes: 64 * 1024 });
   return path;
 }
 
@@ -137,7 +346,7 @@ function discardTrackingIntentWhenMutationAbsent({ intentPath, engine, matchesMu
   // If append reached the journal but checkpointing failed, the durable intent
   // must survive so recovery can reconcile the two local stores. Only discard
   // it when the in-memory canonical record set proves no mutation was appended.
-  if (!engine.records.some(matchesMutation)) unlinkSync(intentPath);
+  if (!engine.records.some(matchesMutation)) removeImmutableClickUpDocument(intentPath, { maxBytes: 64 * 1024 });
 }
 
 /** Replays durable local projection intents from canonical RAIL journal state. */
@@ -145,10 +354,9 @@ export function replayPendingClickUpProjections({ projectDir, handoff_id, clock
   const directory = trackingIntentDirectory(projectDir);
   if (!existsSync(directory)) return Object.freeze([]);
   const outcomes = [];
-  for (const filename of readdirSync(directory).filter((name) => name.endsWith('.json')).sort()) {
-    const path = join(directory, filename);
+  for (const path of listClickUpDocumentPaths(directory)) {
     let intent;
-    try { intent = JSON.parse(readFileSync(path, 'utf8')); } catch (error) {
+    try { intent = readClickUpDocument(path, { maxBytes: 64 * 1024 }); } catch (error) {
       outcomes.push(Object.freeze({ path, state: 'blocked', error_code: 'TRACKING_INTENT_CORRUPT', message: error.message }));
       continue;
     }
@@ -217,6 +425,9 @@ function attemptIdsForHandoff(records, handoffId) {
 
 function taskStates(engine, handoffId) {
   const attemptIds = attemptIdsForHandoff(engine.records, handoffId);
+  const taskIdsByAttempt = new Map(engine.records
+    .filter((record) => record.type === 'attempt_claimed' && record.payload?.attempt?.handoff_id === handoffId)
+    .map((record) => [record.payload.attempt.attempt_id, record.payload.attempt.task_id]));
   const states = new Map();
   for (const record of engine.records) {
     if (record.type === 'attempt_claimed' && record.payload?.attempt?.handoff_id === handoffId) {
@@ -226,6 +437,26 @@ function taskStates(engine, handoffId) {
       const completion = record.payload.completion;
       states.set(completion.task_id, { task_id: completion.task_id, attempt_id: completion.attempt_id, state: completion.state });
     }
+    const attemptId = record.payload?.attempt_id;
+    const taskId = taskIdsByAttempt.get(attemptId);
+    if (taskId && record.type === 'attempt_blocked') {
+      states.set(taskId, { task_id: taskId, attempt_id: attemptId, state: 'blocked' });
+    }
+    if (taskId && record.type === 'adjudication_decided'
+      && adjudicationAttemptState(record.payload?.decision) === 'cancelled') {
+      states.set(taskId, {
+        task_id: taskId, attempt_id: attemptId, state: 'cancelled',
+        adjudication_ref: record.payload.adjudication_ref,
+        handoff_revision_ref: record.payload.decision.handoff_revision_ref,
+      });
+    }
+    if (taskId && record.type === 'attempt_cancelled') {
+      states.set(taskId, {
+        task_id: taskId, attempt_id: attemptId, state: 'cancelled',
+        adjudication_ref: record.payload.adjudication_ref,
+        handoff_revision_ref: record.payload.handoff_revision_ref,
+      });
+    }
   }
   return states;
 }
@@ -239,13 +470,23 @@ export function selectReadyRailTasks({ projectDir, handoff_id, clock } = {}) {
   const { handoff, engine } = loadProjectRail({ projectDir, handoff_id, clock });
   const states = taskStates(engine, handoff.handoff_id);
   const merged = new Set([...states.values()].filter((item) => item.state === 'merged').map((item) => item.task_id));
-  const ready = handoff.tasks.filter((task) => !states.has(task.task_id)
+  const cancelled = [...states.values()].filter((item) => item.state === 'cancelled');
+  const handoffRevisionRequired = cancelled.length > 0;
+  const ready = handoffRevisionRequired ? [] : handoff.tasks.filter((task) => !states.has(task.task_id)
     && task.dependency_ids.every((dependency) => merged.has(dependency)));
+  const blocked = handoffRevisionRequired
+    ? handoff.tasks.filter((task) => !merged.has(task.task_id))
+    : handoff.tasks.filter((task) => !states.has(task.task_id) && !ready.includes(task));
   return Object.freeze({
     handoff_id: handoff.handoff_id,
     completed_task_ids: Object.freeze([...merged].sort()),
     ready_task_ids: Object.freeze(ready.map((task) => task.task_id)),
-    blocked_task_ids: Object.freeze(handoff.tasks.filter((task) => !states.has(task.task_id) && !ready.includes(task)).map((task) => task.task_id)),
+    blocked_task_ids: Object.freeze(blocked.map((task) => task.task_id)),
+    ...(handoffRevisionRequired ? {
+      next_required_action: 'planning_handoff_revision_required',
+      cancelled_task_ids: Object.freeze(cancelled.map((item) => item.task_id).sort()),
+      handoff_revision_refs: Object.freeze([...new Set(cancelled.map((item) => item.handoff_revision_ref).filter(Boolean))].sort()),
+    } : {}),
   });
 }
 
@@ -277,13 +518,47 @@ 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, harness_process_id, adapter, browser_request, git_dir = projectDir, lease_ttl_ms, 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 } = {}) {
   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 selection = selectReadyRailTasks({ projectDir, handoff_id, clock });
-  if (!selection.ready_task_ids.includes(task_id)) fail('TASK_NOT_DISPATCHABLE', 'task is not dependency-ready for dispatch', { task_id, ready_task_ids: selection.ready_task_ids });
-  const { handoff } = loadProjectRail({ projectDir, handoff_id, clock });
+  const language = projectRailLanguage(projectDir);
+  const { handoff, handoff_path, engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const priorClaim = engine.records.find((record) => record.type === 'attempt_claimed'
+    && record.payload?.attempt?.attempt_id === attempt_id);
+  let resumedContext = null;
+  let selection = null;
+  if (priorClaim) {
+    resumedContext = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+    if (resumedContext.task.task_id !== task_id) fail('ATTEMPT_TASK_MISMATCH', 'retry attempt is bound to a different task');
+    if (resumedContext.state !== 'active') fail('RAIL_RETRY_ATTEMPT_INACTIVE', `attempt is ${resumedContext.state}`);
+    if (engine.executionEvidenceForAttempt(attempt_id, { successful_only: true }).length > 0) {
+      fail('RAIL_EXECUTION_ALREADY_SUCCEEDED', 'attempt already has a successful canonical execution');
+    }
+    const currentProcessId = `process://chati/${process.pid}`;
+    if (resumedContext.claim.harness_process_id !== currentProcessId) {
+      if (!recover_expired) {
+        fail('RAIL_CLAIM_PROCESS_MISMATCH', 'retry requires the same live supervisor process; use the atomic recovery runner after lease expiry', {
+          attempt_id,
+          claim_process_id: resumedContext.claim.harness_process_id,
+          supervisor_process_id: currentProcessId,
+        });
+      }
+      engine.recoverAttempt({
+        attempt_id,
+        operator_id,
+        harness_process_id: currentProcessId,
+        git_dir,
+        ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
+      });
+      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');
+    }
+  } else {
+    selection = selectReadyRailTasks({ projectDir, handoff_id, clock });
+    if (!selection.ready_task_ids.includes(task_id)) fail('TASK_NOT_DISPATCHABLE', 'task is not dependency-ready for dispatch', { task_id, ready_task_ids: selection.ready_task_ids });
+  }
   const task = handoff.tasks.find((item) => item.task_id === task_id);
   if (!task.execution_binding || typeof task.execution_binding !== 'object'
     || ['provider_id', 'harness_id', 'model_id', 'reasoning_configuration']
@@ -295,33 +570,100 @@ export function dispatchReadyRailTask({ projectDir, handoff_id, task_id, attempt
     ? launchProjectBrowserSession({ session: createProjectBrowserSession({ task, request: browser_request }), request: browser_request })
     : null;
   const selectedBinding = { provider_id: task.execution_binding.provider_id, harness_id: task.execution_binding.harness_id };
-  const invocationBase = resolveRuntimeInvocationV2({
+  const invocationBase = resolveRuntimeRailInvocationV2({
     artifact: installation,
-    agent: 'dev',
+    action: 'build',
     binding: selectedBinding,
     model_id: task.execution_binding.model_id,
     reasoning_configuration: task.execution_binding.reasoning_configuration,
     ...(clock === undefined ? {} : { clock }),
   });
   if (adapter.harness_id && adapter.harness_id !== invocationBase.harness_id) fail('HARNESS_MISMATCH', 'selected installation binding does not match the injected adapter');
-  const claim = claimRailTask({ projectDir, handoff_id, task_id, attempt_id, operator_id, harness_process_id, completed_task_ids: selection.completed_task_ids, git_dir, ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }), ...(clock === undefined ? {} : { clock }) });
-  const invocation = Object.freeze({
+  let claim;
+  if (resumedContext) {
+    const renewed = engine.heartbeat({
+      attempt_id,
+      claim_id: resumedContext.claim.claim_id,
+      operator_id,
+      harness_process_id: `process://chati/${process.pid}`,
+      ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
+    });
+    claim = Object.freeze({
+      attempt: resumedContext.attempt,
+      claim: Object.freeze({ ...resumedContext.claim, lease: renewed.lease }),
+      event_id: renewed.event_id,
+      resumed: true,
+    });
+  } else {
+    claim = claimRailTask({ projectDir, handoff_id, task_id, attempt_id, operator_id, completed_task_ids: selection.completed_task_ids, git_dir, ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }), ...(clock === undefined ? {} : { clock }) });
+  }
+  const invocationDraft = {
     ...invocationBase,
     invocation_id: `rail-invocation-${attempt_id}`,
     attempt_id,
+    launch_nonce: randomUUID(),
     tool_policy_ref: task.routing_constraints_ref,
     input_ref: task.execution_scope_ref,
     expected_output_schema: 'rail-task-execution/v1',
+    language,
+  };
+  const prompt = buildRailTaskPrompt({
+    projectDir,
+    stored: { path: handoff_path, handoff },
+    task,
+    invocation: invocationDraft,
+    browserManifest: browser?.manifest ?? null,
+    language,
+  });
+  const invocation = Object.freeze({ ...invocationDraft, prompt_digest: sha256(prompt) });
+  let launchReserved = false;
+  const reserve_launch = () => {
+    if (launchReserved) fail('EXECUTION_LAUNCH_RESERVATION_REUSED', 'terminal attempted to reserve the same provider launch more than once');
+    engine.reserveExecutionLaunch({
+      attempt_id,
+      claim_id: claim.claim.claim_id,
+      operator_id: claim.claim.operator_id,
+      harness_process_id: `process://chati/${process.pid}`,
+      invocation,
+    });
+    launchReserved = true;
+  };
+  const receipt = adapter.invoke({
+    installation: installation.installation,
+    snapshot: installation.capability_snapshot,
+    invocation,
+    prompt,
+    browser_manifest: browser?.manifest ?? null,
+    reserve_launch,
+  });
+  if (!launchReserved) fail('EXECUTION_LAUNCH_NOT_RESERVED', 'terminal authority must reserve the provider launch at the final pre-spawn boundary');
+  if (!verifyTerminalAuthorityReceipt(receipt, {
+    purpose: 'terminal_launch', authority_kind: 'rail_execution',
+    invocation_id: invocation.invocation_id, launch_nonce: invocation.launch_nonce,
+    provider_id: invocation.provider_id, harness_id: invocation.harness_id,
+    model_id: invocation.model_pin.model_id,
+    reasoning_configuration: invocation.model_pin.reasoning_configuration,
+    task_id: task.task_id,
+    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,
   });
-  const receipt = adapter.invoke({ installation: installation.installation, snapshot: installation.capability_snapshot, invocation });
-  return Object.freeze({ claim, invocation, receipt, task_id, handoff_id, browser_manifest: browser?.manifest ?? null });
+  return Object.freeze({ claim, invocation, receipt, dispatch, task_id, handoff_id, resumed: Boolean(resumedContext), browser_manifest: browser?.manifest ?? null });
 }
 
 /**
  * Entry point used by the CHATI runtime after a sealed planning handoff is
  * present. It creates an auditable RAIL claim before any task executor runs.
  */
-export function claimRailTask({ projectDir, handoff_id, task_id, attempt_id, operator_id, harness_process_id, git_dir = projectDir, lease_ttl_ms, clock } = {}) {
+export function claimRailTask({ projectDir, handoff_id, task_id, attempt_id, operator_id, git_dir = projectDir, lease_ttl_ms, clock } = {}) {
   const { handoff, engine } = loadProjectRail({ projectDir, handoff_id, clock });
   const states = taskStates(engine, handoff.handoff_id);
   const completed_task_ids = [...states.values()].filter((item) => item.state === 'merged').map((item) => item.task_id);
@@ -332,7 +674,7 @@ export function claimRailTask({ projectDir, handoff_id, task_id, attempt_id, ope
   let claim;
   try {
     claim = engine.claimTask({
-      handoff, task_id, attempt_id, operator_id, harness_process_id,
+      handoff, task_id, attempt_id, operator_id, harness_process_id: `process://chati/${process.pid}`,
       completed_task_ids, git_dir, ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
     });
   } catch (error) {
@@ -356,25 +698,449 @@ export function heartbeatRailTask({ projectDir, handoff_id, attempt_id, claim_id
   const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
   return engine.heartbeat({
     attempt_id, claim_id, operator_id,
+    harness_process_id: `process://chati/${process.pid}`,
     ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
   });
 }
 
-/** Recover an expired attempt only after the caller supplies explicit reconciliation evidence. */
-export function recoverRailTask({ projectDir, handoff_id, attempt_id, operator_id, harness_process_id, reconciliation, git_dir = projectDir, lease_ttl_ms, clock } = {}) {
+/**
+ * Acquires the attempt for the current long-lived action supervisor. An
+ * explicitly relinquished claim can move immediately; an abrupt exit still
+ * requires both lease expiry and proof that the prior supervisor stopped.
+ */
+export function acquireRailTaskSupervisor({
+  projectDir, handoff_id, attempt_id, operator_id, git_dir = projectDir,
+  lease_ttl_ms, clock,
+} = {}) {
+  let context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  const effectiveOperator = operator_id ?? context.claim.operator_id;
+  const currentProcessId = `process://chati/${process.pid}`;
+  const observedNow = typeof clock === 'function' ? clock() : new Date();
+  const observedNowMs = observedNow instanceof Date ? observedNow.getTime() : Date.parse(observedNow);
+  let recovered = false;
+  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,
+      ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
+      ...(clock === undefined ? {} : { clock }),
+    });
+    context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+    recovered = true;
+  }
+  const renewed = heartbeatRailTask({
+    projectDir, handoff_id, attempt_id,
+    claim_id: context.claim.claim_id, operator_id: effectiveOperator,
+    ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
+    ...(clock === undefined ? {} : { clock }),
+  });
+  context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return Object.freeze({ context, renewed, recovered, operator_id: effectiveOperator });
+}
+
+/** Resolve the latest canonical claim and task binding for an active attempt. */
+export function resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock } = {}) {
+  const { handoff, engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const claimed = engine.records.find((record) => record.type === 'attempt_claimed'
+    && record.payload?.attempt?.attempt_id === attempt_id);
+  if (!claimed) fail('RAIL_ATTEMPT_NOT_FOUND', `attempt ${attempt_id} is absent from the RAIL journal`);
+  if (claimed.payload.attempt.handoff_id !== handoff_id) fail('RAIL_ATTEMPT_HANDOFF_MISMATCH', 'attempt does not belong to the requested handoff');
+  let claim = claimed.payload.claim;
+  let state = 'active';
+  for (const record of engine.records) {
+    if (record.payload?.attempt_id === attempt_id && record.type === 'attempt_heartbeat') claim = { ...claim, lease: record.payload.lease };
+    if (record.payload?.attempt_id === attempt_id && record.type === 'attempt_relinquished') claim = { ...claim, lease: record.payload.lease };
+    if (record.payload?.attempt_id === attempt_id && record.type === 'attempt_recovered') { claim = record.payload.claim; state = record.payload.resume_state ?? 'active'; }
+    if (record.type === 'attempt_completed' && record.payload?.completion?.attempt_id === attempt_id) state = record.payload.completion.state;
+    if (record.payload?.attempt_id === attempt_id && record.type === 'attempt_blocked') state = 'blocked';
+    if (record.payload?.attempt_id === attempt_id && record.type === 'adjudication_decided'
+      && adjudicationAttemptState(record.payload?.decision) === 'cancelled') state = 'cancelled';
+    if (record.payload?.attempt_id === attempt_id && record.type === 'attempt_cancelled') state = 'cancelled';
+  }
+  const task = handoff.tasks.find((item) => item.task_id === claimed.payload.attempt.task_id);
+  if (!task) fail('TASK_NOT_FOUND', 'attempt task is absent from the sealed handoff');
+  return Object.freeze({
+    handoff,
+    task,
+    attempt: claimed.payload.attempt,
+    claim: Object.freeze(claim),
+    state,
+    records: engine.records,
+    language: projectRailLanguage(projectDir),
+  });
+}
+
+/** Expire the current supervisor lease without transferring process ownership. */
+export function relinquishRailTask({ projectDir, handoff_id, attempt_id, claim_id, operator_id, reason, clock } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  return engine.relinquishAttempt({
+    attempt_id, claim_id, operator_id,
+    harness_process_id: `process://chati/${process.pid}`,
+    ...(reason === undefined ? {} : { reason }),
+  });
+}
+
+/** Atomically reserves one mutating rework for the active claim generation. */
+export function reserveRailRework({
+  projectDir, handoff_id, attempt_id, source_decision_ref, reservation_id, clock,
+} = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.reserveRework({
+    attempt_id,
+    claim_id: context.claim.claim_id,
+    operator_id: context.claim.operator_id,
+    harness_process_id: `process://chati/${process.pid}`,
+    source_decision_ref,
+    reservation_id,
+  });
+}
+
+/** 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,
+} = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.reserveReworkLaunch({
+    attempt_id,
+    claim_id: context.claim.claim_id,
+    operator_id: context.claim.operator_id,
+    harness_process_id: `process://chati/${process.pid}`,
+    source_decision_ref,
+    reservation_id,
+    invocation,
+  });
+}
+
+/** Releases a rework reservation only after this supervisor stopped its provider. */
+export function releaseRailReworkReservation({
+  projectDir, handoff_id, attempt_id, source_decision_ref, reservation_id, reason, clock,
+} = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.releaseReworkReservation({
+    attempt_id,
+    claim_id: context.claim.claim_id,
+    operator_id: context.claim.operator_id,
+    harness_process_id: `process://chati/${process.pid}`,
+    source_decision_ref,
+    reservation_id,
+    ...(reason === undefined ? {} : { reason }),
+  });
+}
+
+/** Persist executor output only through the claim-bound canonical RAIL journal. */
+export function recordRailExecutionEvidence({
+  projectDir, handoff_id, attempt_id, invocation, execution, base_commit_ref,
+  result_commit_ref = null, run_kind = 'initial', source_decision_ref = null,
+  clock,
+} = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  if (!verifyTerminalAuthorityReceipt(execution?.terminal_authority_receipt, {
+    purpose: 'terminal_completion', authority_kind: 'rail_execution',
+    invocation_id: invocation?.invocation_id, launch_nonce: invocation?.launch_nonce,
+    terminal_id: execution?.terminal_id, provider_id: invocation?.provider_id,
+    harness_id: invocation?.harness_id, model_id: invocation?.model_pin?.model_id,
+    reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+    exit_status: execution?.exit_status,
+    execution_base_commit_ref: base_commit_ref,
+  })) fail('UNTRUSTED_EXECUTION_EVIDENCE', 'execution evidence requires a completion receipt minted by the terminal authority');
+  if (typeof execution?.stdout !== 'string' || typeof execution?.stderr !== 'string'
+    || execution.terminal_authority_receipt.stdout_digest !== sha256(execution.stdout)
+    || execution.terminal_authority_receipt.stderr_digest !== sha256(execution.stderr)) {
+    fail('EXECUTION_TERMINAL_OUTPUT_MISMATCH', 'execution logs must be the exact stdout and stderr signed by the terminal authority');
+  }
+  const evidence = engine.recordExecutionEvidence({
+    attempt_id,
+    claim_id: context.claim.claim_id,
+    operator_id: context.claim.operator_id,
+    invocation,
+    execution,
+    base_commit_ref,
+    result_commit_ref,
+    run_kind,
+    source_decision_ref,
+    receipt_nonce: invocation?.launch_nonce,
+    git_dir: projectDir,
+  });
+  return Object.freeze({
+    ...evidence,
+    evidence_ref: `rail-execution://${handoff_id}/${attempt_id}/${evidence.evidence_id}`,
+  });
+}
+
+/** Persist the fail-closed initial launch intent before a provider process is created. */
+export function reserveRailExecutionLaunch({
+  projectDir, handoff_id, attempt_id, invocation, clock,
+} = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  return engine.reserveExecutionLaunch({
+    attempt_id,
+    claim_id: context.claim.claim_id,
+    operator_id: context.claim.operator_id,
+    harness_process_id: `process://chati/${process.pid}`,
+    invocation,
+  });
+}
+
+/** Journal the exact launched terminal binding before any output may become evidence. */
+export function recordRailExecutionDispatch({
+  projectDir, handoff_id, attempt_id, invocation, launch_receipt, prompt,
+  browser_manifest = null, run_kind = 'initial', clock,
+} = {}) {
+  const { engine, handoff, handoff_path } = loadProjectRail({ projectDir, handoff_id, clock });
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  let canonicalPrompt;
+  let canonicalBaseCommitRef;
+  if (run_kind === 'rework') {
+    const latestControl = context.records.filter((record) => ['review_decided', 'adjudication_decided'].includes(record.type)
+      && record.payload?.attempt_id === attempt_id).at(-1);
+    const reviewRef = latestControl?.type === 'review_decided' ? latestControl.payload.review_ref : latestControl?.payload?.review_ref;
+    const sourceReview = engine.reviewEvidenceForAttempt(attempt_id)
+      .find((entry) => `rail-review://${handoff_id}/${attempt_id}/${entry.review?.review_id}` === reviewRef)?.review;
+    const sourceAdjudication = latestControl?.type === 'adjudication_decided'
+      ? {
+          adjudication_ref: latestControl.payload.adjudication_ref,
+          review_ref: latestControl.payload.review_ref,
+          decision: latestControl.payload.decision,
+          evidence: latestControl.payload.evidence,
+        }
+      : null;
+    const executionHistory = engine.executionEvidenceForAttempt(attempt_id);
+    const baseCommitRef = executionHistory.filter((entry) => typeof entry.result_commit_ref === 'string').at(-1)?.result_commit_ref;
+    if (!sourceReview || !baseCommitRef) fail('NONCANONICAL_EXECUTION_PROMPT', 'rework prompt requires its canonical review and base execution');
+    canonicalBaseCommitRef = baseCommitRef;
+    canonicalPrompt = buildRailReworkPrompt({
+      projectDir, context, sourceReview, sourceAdjudication, executionHistory, baseCommitRef, invocation,
+    });
+  } else {
+    canonicalBaseCommitRef = context.attempt.git_commit_ref;
+    canonicalPrompt = buildRailTaskPrompt({
+      projectDir, stored: { path: handoff_path, handoff }, task: context.task, invocation,
+      browserManifest: browser_manifest, language: invocation?.language ?? context.language,
+    });
+  }
+  if (prompt !== canonicalPrompt || invocation?.prompt_digest !== sha256(canonicalPrompt)) {
+    fail('NONCANONICAL_EXECUTION_PROMPT', 'execution dispatch must use the exact canonical prompt for this attempt');
+  }
+  if (!verifyTerminalAuthorityReceipt(launch_receipt, {
+    purpose: 'terminal_launch', authority_kind: 'rail_execution',
+    invocation_id: invocation?.invocation_id, launch_nonce: invocation?.launch_nonce,
+    provider_id: invocation?.provider_id, harness_id: invocation?.harness_id,
+    model_id: invocation?.model_pin?.model_id,
+    reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+    task_id: context.task.task_id,
+    working_dir: resolve(projectDir),
+    prompt_digest: invocation.prompt_digest,
+    execution_base_commit_ref: canonicalBaseCommitRef,
+    execution_launch_head_ref: canonicalBaseCommitRef,
+    execution_worktree_clean: true,
+  })) fail('UNTRUSTED_EXECUTION_DISPATCH', 'execution dispatch requires a launch receipt minted by the terminal authority');
+  if (!/^[a-f0-9]{64}$/.test(launch_receipt.execution_repository_identity_digest || '')
+    || !/^[a-f0-9]{64}$/.test(launch_receipt.execution_preexisting_commits_digest || '')) {
+    fail('UNTRUSTED_EXECUTION_DISPATCH', 'execution dispatch requires signed repository and preexisting-object baselines');
+  }
+  return engine.recordExecutionDispatch({
+    attempt_id,
+    claim_id: context.claim.claim_id,
+    operator_id: context.claim.operator_id,
+    invocation,
+    launch_receipt,
+    project_dir: projectDir,
+    browser_manifest,
+    run_kind,
+    ...(run_kind === 'rework' ? {
+      source_decision_ref: invocation?.source_decision_ref,
+      rework_reservation_id: invocation?.rework_reservation_id,
+    } : {}),
+  });
+}
+
+export function listRailExecutionEvidence({ projectDir, attempt_id, successful_only = false, clock } = {}) {
+  const engine = createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) });
+  return engine.executionEvidenceForAttempt(attempt_id, { successful_only });
+}
+
+export function loadLatestRailExecutionEvidence({ projectDir, attempt_id, clock } = {}) {
+  const records = listRailExecutionEvidence({ projectDir, attempt_id, successful_only: true, clock });
+  if (records.length === 0) fail('RAIL_EXECUTION_EVIDENCE_REQUIRED', `attempt ${attempt_id} has no successful canonical execution evidence`);
+  return records.at(-1);
+}
+
+/** 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 } = {}) {
   const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
   return engine.recoverAttempt({
-    attempt_id, operator_id, harness_process_id, reconciliation, git_dir,
+    attempt_id, operator_id, harness_process_id: `process://chati/${process.pid}`, git_dir,
     ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
   });
 }
 
+function canonicalAdjudicationRound(records, attemptId, reviewRef, selected) {
+  const observations = records
+    .filter((record) => record.type === 'adjudication_observed'
+      && record.payload?.attempt_id === attemptId
+      && record.payload?.review_ref === reviewRef)
+    .map((record) => record.payload.observation);
+  const orderedRound = (round) => selected.map((candidate) => observations.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);
+  const roundOne = orderedRound(1);
+  if (roundOne.length < selected.length) return { round: 1, prior_decisions: [] };
+  if (adjudicationEntriesAgree(roundOne)) {
+    fail('ADJUDICATION_ROUND_COMPLETE', 'the canonical first adjudication round already reached consensus');
+  }
+  const roundTwo = orderedRound(2);
+  if (roundTwo.length === selected.length) fail('ADJUDICATION_ROUND_COMPLETE', 'the canonical second adjudication round is complete');
+  return {
+    round: 2,
+    prior_decisions: roundOne.map((entry, index) => ({
+      anonymous_ref: `independent-decision-${index + 1}`,
+      decision: entry.decision,
+    })),
+  };
+}
+
+/** Records only a unanimous, selected-model adjudication against an active attempt. */
+export function recordRailAdjudicationDispatch({
+  projectDir, handoff_id, attempt_id, review_ref, invocation, launch_receipt,
+  prompt, reviewWorkspace, clock,
+} = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const context = resolveRailAttemptContext({ projectDir, handoff_id, attempt_id, clock });
+  const plan = context.records.filter((record) => record.type === 'review_decided'
+    && record.payload?.attempt_id === attempt_id).at(-1)?.payload?.decision;
+  if (plan?.decision !== 'AI_ADJUDICATION' || !Array.isArray(plan.adjudicators) || plan.adjudicators.length === 0) {
+    fail('RAIL_ADJUDICATION_NOT_AUTHORIZED', 'the latest canonical review decision does not authorize adjudication');
+  }
+  const roundState = canonicalAdjudicationRound(
+    engine.records, attempt_id, review_ref, plan?.adjudicators || [],
+  );
+  const execution = loadLatestRailExecutionEvidence({ projectDir, attempt_id, clock });
+  if (!reviewWorkspace
+    || reviewWorkspace.canonical_project_dir !== realpathSync(resolve(projectDir))
+    || reviewWorkspace.result_commit_ref !== execution.result_commit_ref) {
+    fail('RAIL_ADJUDICATION_WORKSPACE_MISMATCH', 'adjudication requires an immutable workspace for the exact result commit');
+  }
+  const workspaceState = assertRailReadOnlyCommitWorkspaceUnchanged({
+    workspace: reviewWorkspace,
+    label: 'RAIL adjudication dispatch',
+  });
+  const reviewSubject = {
+    result_commit_ref: execution.result_commit_ref,
+    workspace_digest: sha256(workspaceState),
+  };
+  const canonicalPrompt = buildRailAdjudicationPrompt({
+    projectDir: reviewWorkspace.subject_dir, context, plan, invocation,
+    reviews: engine.reviewEvidenceForAttempt(attempt_id),
+    executions: engine.executionEvidenceForAttempt(attempt_id),
+    priorDecisions: roundState.prior_decisions,
+    round: roundState.round,
+    reviewSubject,
+  });
+  if (prompt !== canonicalPrompt || invocation?.prompt_digest !== sha256(canonicalPrompt)
+    || invocation?.adjudication_round !== roundState.round
+    || invocation?.prior_decisions_digest !== sha256(roundState.prior_decisions)) {
+    fail('NONCANONICAL_ADJUDICATION_PROMPT', 'adjudication dispatch must use the exact canonical prompt for this attempt and round');
+  }
+  if (!verifyTerminalAuthorityReceipt(launch_receipt, {
+    purpose: 'terminal_launch', authority_kind: 'rail_adjudication',
+    invocation_id: invocation?.invocation_id, launch_nonce: invocation?.launch_nonce,
+    provider_id: invocation?.provider_id, harness_id: invocation?.harness_id,
+    model_id: invocation?.model_pin?.model_id,
+    reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+    task_id: context.task.task_id,
+    working_dir: resolve(reviewWorkspace.subject_dir),
+    prompt_digest: invocation.prompt_digest,
+  })) fail('UNTRUSTED_ADJUDICATION_LAUNCH', 'adjudication dispatch requires a terminal-authority launch receipt');
+  return engine.recordAdjudicationDispatch({
+    attempt_id, review_ref, invocation, launch_receipt,
+    project_dir: projectDir,
+    working_dir: reviewWorkspace.subject_dir,
+  });
+}
+
+export function recordRailAdjudicationObservation({
+  projectDir, handoff_id, attempt_id, review_ref, entry, clock,
+} = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const parsedDecision = parseAuthorizedAdjudicationOutput(entry?.adjudication_output);
+  if (sha256(parsedDecision) !== sha256(validateAdjudicationDecision(entry?.decision))) {
+    fail('RAIL_ADJUDICATION_PAYLOAD_MISMATCH', 'caller decision differs from the terminal-authorized adjudication output');
+  }
+  const receipt = entry?.terminal_authority_receipt;
+  const invocation = entry?.invocation;
+  if (!verifyTerminalAuthorityReceipt(receipt, {
+    purpose: 'terminal_completion', authority_kind: 'rail_adjudication',
+    invocation_id: invocation?.invocation_id, launch_nonce: invocation?.launch_nonce,
+    provider_id: invocation?.provider_id, harness_id: invocation?.harness_id,
+    model_id: invocation?.model_pin?.model_id,
+    reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+    exit_status: 0,
+  }) || receipt.stdout_digest !== sha256(entry.adjudication_output)) {
+    fail('UNTRUSTED_ADJUDICATION_EVIDENCE', 'adjudication observation is not bound to an authorized terminal completion');
+  }
+  return engine.recordAdjudicationObservation({
+    attempt_id, review_ref, invocation, decision: parsedDecision,
+    adjudication_output: entry.adjudication_output,
+    terminal_authority_receipt: receipt,
+  });
+}
+
+export function recordRailAdjudication({ projectDir, handoff_id, attempt_id, review_ref, evidence, clock } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  if (!Array.isArray(evidence) || evidence.length === 0) fail('INVALID_ADJUDICATION_RECORD', 'adjudication evidence must be a non-empty array');
+  const authorizedEvidence = evidence.map((entry) => {
+    const invocation = entry?.invocation;
+    const receipt = entry?.terminal_authority_receipt;
+    const parsedDecision = parseAuthorizedAdjudicationOutput(entry?.adjudication_output);
+    if (sha256(parsedDecision) !== sha256(validateAdjudicationDecision(entry?.decision))) {
+      fail('RAIL_ADJUDICATION_PAYLOAD_MISMATCH', 'caller decision differs from the terminal-authorized adjudication output');
+    }
+    const expected = {
+      purpose: 'terminal_completion', authority_kind: 'rail_adjudication',
+      invocation_id: invocation?.invocation_id, launch_nonce: invocation?.launch_nonce,
+      provider_id: invocation?.provider_id, harness_id: invocation?.harness_id,
+      model_id: invocation?.model_pin?.model_id,
+      reasoning_configuration: invocation?.model_pin?.reasoning_configuration,
+      exit_status: 0,
+    };
+    if (!verifyTerminalAuthorityReceipt(receipt, expected)
+      || receipt.stdout_digest !== sha256(entry.adjudication_output)) {
+      fail('UNTRUSTED_ADJUDICATION_EVIDENCE', 'adjudication evidence is not bound to a successful authorized terminal completion');
+    }
+    return Object.freeze({
+      invocation,
+      decision: parsedDecision,
+      adjudication_output: entry.adjudication_output,
+      terminal_authority_receipt: receipt,
+    });
+  });
+  return engine.recordAdjudicationDecision({ attempt_id, review_ref, evidence: authorizedEvidence });
+}
+
 /**
  * Write an immutable C-06 completion record. Git, CI, review and acceptance
  * evidence are validated by RailEngine against the project-local journal.
  */
-export function completeRailTask({ projectDir, handoff_id, completion_id, attempt_id, claim_id, operator_id, state, git, ci, reviews, acceptance_evidence_refs, completed_at, metrics, clock } = {}) {
+export function completeRailTask({
+  projectDir, handoff_id, completion_id, attempt_id, claim_id, operator_id, state,
+  git, ci, reviews, acceptance_evidence_refs, acceptance_authority_receipt,
+  browser_evidence, completed_at, metrics, clock,
+} = {}) {
   const { handoff, engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const ownership = acquireRailTaskSupervisor({
+    projectDir, handoff_id, attempt_id, operator_id,
+    ...(clock === undefined ? {} : { clock }),
+  });
+  if (claim_id !== ownership.context.claim.claim_id) fail('CLAIM_OWNER_MISMATCH', 'completion claim_id does not match the canonical attempt claim');
+  let shouldRelinquish = true;
+  try {
   const trackingRequired = internalTrackingInstallation(projectDir, clock);
   if (trackingRequired && state === 'merged') assertCompletionMetricsEvidence(metrics, reviews, acceptance_evidence_refs, engine.records, attempt_id);
   const taskId = engine.records.find((record) => record.type === 'attempt_claimed' && record.payload?.attempt?.attempt_id === attempt_id)?.payload?.attempt?.task_id;
@@ -384,7 +1150,9 @@ export function completeRailTask({ projectDir, handoff_id, completion_id, attemp
   let completion;
   try {
     completion = engine.completeAttempt({
-      completion_id, attempt_id, claim_id, operator_id, state, git: { ...git, git_dir: projectDir }, ci, reviews, acceptance_evidence_refs,
+      completion_id, attempt_id, claim_id, operator_id: ownership.operator_id, state, git: { ...git, git_dir: projectDir }, ci, reviews, acceptance_evidence_refs,
+      acceptance_authority_receipt,
+      ...(browser_evidence === undefined ? {} : { browser_evidence }),
       ...(completed_at === undefined ? {} : { completed_at }), ...(metrics === undefined ? {} : { metrics }), handoff,
     });
   } catch (error) {
@@ -401,7 +1169,19 @@ export function completeRailTask({ projectDir, handoff_id, completion_id, attemp
   const tracking_projection = trackingRequired
     ? replayPendingClickUpProjections({ projectDir, handoff_id, ...(clock === undefined ? {} : { clock }) }).find((item) => item.path === intentPath)
     : undefined;
+  if (['merged', 'blocked', 'cancelled'].includes(completion.state)) shouldRelinquish = false;
   return Object.freeze({ ...result, ...(tracking_projection ? { tracking_projection } : {}) });
+  } finally {
+    if (shouldRelinquish) {
+      relinquishRailTask({
+        projectDir, handoff_id, attempt_id,
+        claim_id: ownership.context.claim.claim_id,
+        operator_id: ownership.operator_id,
+        reason: 'action_complete',
+        ...(clock === undefined ? {} : { clock }),
+      });
+    }
+  }
 }
 
 /** Resolves only a completion that exists in the immutable project-local journal. */