chati-dev 4.4.1 → 4.5.2

package/src/orchestrator/rail-runtime.js

@@ -0,0 +1,421 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sha256 } from '@chati/core';
+import { RailEngine } from '@chati/rail';
+import { validateSealedHandoff } from '@chati/planning';
+import { loadRuntimeInstallationV2, resolveRuntimeInvocationV2 } from './runtime-installation-v2.js';
+import { createProjectBrowserSession, launchProjectBrowserSession } from './browser-runtime.js';
+import { enqueueClickUpProjectionFromState } from './clickup-projection.js';
+
+export const RAIL_V2_DIR = '.chati/v2/rail';
+
+function fail(code, message, cause) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.code = code;
+  throw error;
+}
+
+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');
+  return join(projectDir, RAIL_V2_DIR, 'handoffs', `${handoffId}.json`);
+}
+
+function completionReference(handoffId, attemptId, completionId) {
+  for (const [label, value] of Object.entries({ handoff_id: handoffId, attempt_id: attemptId, completion_id: completionId })) {
+    if (typeof value !== 'string' || !/^[A-Za-z0-9._-]+$/.test(value)) fail('INVALID_COMPLETION_REFERENCE', `${label} contains unsupported reference characters`);
+  }
+  return `rail-completion://${handoffId}/${attemptId}/${completionId}`;
+}
+
+export function getRailPaths(projectDir) {
+  return Object.freeze({
+    root: join(projectDir, RAIL_V2_DIR),
+    handoffs: join(projectDir, RAIL_V2_DIR, 'handoffs'),
+    journal: join(projectDir, RAIL_V2_DIR, 'journal.jsonl'),
+  });
+}
+
+/** Persist one sealed planning handoff. Conflicting material is never overwritten. */
+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`;
+  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 });
+    }
+    if (error?.code === 'EEXIST') fail('HANDOFF_STORAGE_CONFLICT', `sealed handoff ${validated.handoff_id} already exists`, error);
+    throw error;
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+  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'))) });
+  } catch (error) {
+    if (error?.code) throw error;
+    return fail('INVALID_STORED_HANDOFF', `sealed handoff ${handoff_id} cannot be read`, error);
+  }
+}
+
+export function createProjectRailEngine({ projectDir, clock = () => new Date() }) {
+  return new RailEngine({ journal_path: getRailPaths(projectDir).journal, clock });
+}
+
+function loadProjectRail({ projectDir, handoff_id, clock }) {
+  const stored = loadRailHandoff({ projectDir, handoff_id });
+  return Object.freeze({ handoff: stored.handoff, engine: createProjectRailEngine({ projectDir, ...(clock === undefined ? {} : { clock }) }) });
+}
+
+function internalTrackingInstallation(projectDir, clock) {
+  const artifact = loadRuntimeInstallationV2(projectDir, { ...(clock === undefined ? {} : { clock }) });
+  return artifact?.installation?.profile === 'focus-ai-internal'
+    && artifact.installation.external_integrations?.clickup === 'required';
+}
+
+function assertCompletionMetricsEvidence(metrics, reviews, acceptanceEvidenceRefs, records, attemptId) {
+  if (!metrics || typeof metrics !== 'object' || Array.isArray(metrics)) fail('COMPLETION_METRICS_REQUIRED', 'internal merged completion requires human effort, AI processing and rework metrics');
+  const evidenceRefs = [metrics.actual_human_effort?.evidence_ref, metrics.actual_ai_processing?.evidence_ref];
+  if (!evidenceRefs.every((ref) => typeof ref === 'string' && acceptanceEvidenceRefs?.includes(ref))) {
+    fail('COMPLETION_METRICS_EVIDENCE_REQUIRED', 'effort metrics evidence must be included in acceptance_evidence_refs');
+  }
+  if (!Array.isArray(metrics.rework_review_refs) || !metrics.rework_review_refs.every((ref) => reviews?.includes(ref))) {
+    fail('COMPLETION_REWORK_EVIDENCE_REQUIRED', 'rework metric references must be included in completion reviews');
+  }
+  const journalReworkRefs = records
+    .filter((record) => record.type === 'review_decided'
+      && record.payload?.attempt_id === attemptId
+      && record.payload?.decision?.decision === 'normal-rework')
+    .map((record) => record.payload.review_ref);
+  if (metrics.rework_cycles !== journalReworkRefs.length
+    || new Set(metrics.rework_review_refs).size !== metrics.rework_review_refs.length
+    || !journalReworkRefs.every((ref) => metrics.rework_review_refs.includes(ref))) {
+    fail('COMPLETION_REWORK_JOURNAL_MISMATCH', 'rework metrics must exactly match normal-rework decisions in the canonical journal');
+  }
+}
+
+function trackingIntentDirectory(projectDir) {
+  return join(projectDir, '.chati/v2/tracking/pending-projections');
+}
+
+function trackingIntentPath(projectDir, intent) {
+  return join(trackingIntentDirectory(projectDir), `${sha256(intent).slice(0, 32)}.json`);
+}
+
+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);
+  return path;
+}
+
+function discardTrackingIntentWhenMutationAbsent({ intentPath, engine, matchesMutation }) {
+  if (!intentPath || !existsSync(intentPath)) return;
+  // 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);
+}
+
+/** Replays durable local projection intents from canonical RAIL journal state. */
+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);
+    let intent;
+    try { intent = JSON.parse(readFileSync(path, 'utf8')); } catch (error) {
+      outcomes.push(Object.freeze({ path, state: 'blocked', error_code: 'TRACKING_INTENT_CORRUPT', message: error.message }));
+      continue;
+    }
+    if (handoff_id && intent.handoff_id !== handoff_id) continue;
+    try {
+      const { handoff, engine } = loadProjectRail({ projectDir, handoff_id: intent.handoff_id, clock });
+      const task = handoff.tasks.find((item) => item.task_id === intent.task_id);
+      if (!task?.clickup_ref) fail('MISSING_CLICKUP_REFERENCE', 'internal tracking intent requires task.clickup_ref');
+      const claimRecord = engine.records.find((record) => record.type === 'attempt_claimed'
+        && record.payload?.attempt?.attempt_id === intent.attempt_id
+        && record.payload.attempt.task_id === intent.task_id);
+      if (!claimRecord) {
+        outcomes.push(Object.freeze({ path, state: 'waiting-for-journal' }));
+        continue;
+      }
+      let operation = 'update';
+      let payload = { status: 'in_progress', started_at: claimRecord.payload.claim.lease.acquired_at };
+      let completion;
+      if (intent.completion_id) {
+        const completionRecord = engine.records.find((record) => record.type === 'attempt_completed'
+          && record.payload?.completion?.completion_id === intent.completion_id
+          && record.payload.completion.attempt_id === intent.attempt_id);
+        if (!completionRecord) {
+          outcomes.push(Object.freeze({ path, state: 'waiting-for-journal' }));
+          continue;
+        }
+        const stored = completionRecord.payload.completion;
+        completion = Object.freeze({
+          ...stored,
+          event_id: completionRecord.event_id,
+          immutable_ref: completionReference(handoff.handoff_id, stored.attempt_id, stored.completion_id),
+        });
+        operation = stored.state === 'merged' ? 'close' : 'update';
+        payload = stored.state === 'merged'
+          ? { status: 'done', end_date: stored.completed_at, ...stored.metrics }
+          : { status: 'ready_to_merge' };
+      }
+      const projection = enqueueClickUpProjectionFromState({
+        projectDir, handoff, records: engine.records, task_id: intent.task_id, attempt_id: intent.attempt_id,
+        operation, payload, ...(completion ? { completion } : {}), ...(clock === undefined ? {} : { clock }),
+      });
+      // Keep the intent as durable reconstruction material. The projection is
+      // idempotent, so an hourly reconciliation can rebuild a deleted outbox
+      // from the canonical journal without waiting for another task mutation.
+      outcomes.push(Object.freeze({ path, state: 'queued', projection_id: projection.projection_id }));
+    } catch (error) {
+      outcomes.push(Object.freeze({ path, state: 'pending-local-replay', error_code: error.code || 'TRACKING_PROJECTION_FAILED', message: error.message }));
+    }
+  }
+  return Object.freeze(outcomes);
+}
+
+/** Hourly-safe local reconciliation entry point for the ClickUp outbox. */
+export function reconcileProjectClickUpTracking({ projectDir, handoff_id, clock } = {}) {
+  const outcomes = replayPendingClickUpProjections({ projectDir, handoff_id, ...(clock === undefined ? {} : { clock }) });
+  return Object.freeze({
+    state: outcomes.some((item) => item.state === 'blocked' || item.state === 'pending-local-replay') ? 'pending' : 'synchronized',
+    outcomes,
+  });
+}
+
+function attemptIdsForHandoff(records, handoffId) {
+  return new Set(records.filter((record) => record.type === 'attempt_claimed' && record.payload?.attempt?.handoff_id === handoffId)
+    .map((record) => record.payload.attempt.attempt_id));
+}
+
+function taskStates(engine, handoffId) {
+  const attemptIds = attemptIdsForHandoff(engine.records, handoffId);
+  const states = new Map();
+  for (const record of engine.records) {
+    if (record.type === 'attempt_claimed' && record.payload?.attempt?.handoff_id === handoffId) {
+      states.set(record.payload.attempt.task_id, { task_id: record.payload.attempt.task_id, attempt_id: record.payload.attempt.attempt_id, state: 'active' });
+    }
+    if (record.type === 'attempt_completed' && attemptIds.has(record.payload?.completion?.attempt_id)) {
+      const completion = record.payload.completion;
+      states.set(completion.task_id, { task_id: completion.task_id, attempt_id: completion.attempt_id, state: completion.state });
+    }
+  }
+  return states;
+}
+
+/**
+ * Returns the dependency-ready tasks from the project-local sealed handoff.
+ * A task becomes unblocked only after every predecessor is canonically merged,
+ * never merely claimed or marked ready_to_merge.
+ */
+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)
+    && task.dependency_ids.every((dependency) => merged.has(dependency)));
+  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)),
+  });
+}
+
+/**
+ * Computes the only local condition that may hand a project from RAIL to the
+ * Release Lane. A `ready` result is evidence of merged task completions, not
+ * a release authorization and never invokes a deployment adapter.
+ */
+export function selectRailReleaseReadiness({ projectDir, handoff_id, clock } = {}) {
+  const { handoff, engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const merged = new Map();
+  const attemptIds = attemptIdsForHandoff(engine.records, handoff.handoff_id);
+  for (const record of engine.records) {
+    if (record.type !== 'attempt_completed' || record.payload?.completion?.state !== 'merged' || !attemptIds.has(record.payload.completion.attempt_id)) continue;
+    const completion = record.payload.completion;
+    merged.set(completion.task_id, completionReference(handoff.handoff_id, completion.attempt_id, completion.completion_id));
+  }
+  const missing_task_ids = handoff.tasks.filter((task) => !merged.has(task.task_id)).map((task) => task.task_id);
+  return Object.freeze({
+    handoff_id: handoff.handoff_id,
+    state: missing_task_ids.length === 0 ? 'ready' : 'not-ready',
+    missing_task_ids: Object.freeze(missing_task_ids),
+    source_completion_refs: Object.freeze(handoff.tasks.map((task) => merged.get(task.task_id)).filter(Boolean)),
+  });
+}
+
+/**
+ * Claims one dependency-ready RAIL task and invokes the explicitly injected
+ * 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 } = {}) {
+  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 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']
+      .some((field) => typeof task.execution_binding[field] !== 'string' || !task.execution_binding[field].trim())) {
+    fail('TASK_EXECUTION_BINDING_REQUIRED', 'v2 RAIL dispatch requires a complete explicit task execution binding');
+  }
+  if (task.requires_browser === true && (!browser_request || typeof browser_request !== 'object')) fail('BROWSER_PREFLIGHT_REQUIRED', 'browser task dispatch requires a complete browser preflight request');
+  const browser = task.requires_browser === true
+    ? 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({
+    artifact: installation,
+    agent: 'dev',
+    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({
+    ...invocationBase,
+    invocation_id: `rail-invocation-${attempt_id}`,
+    attempt_id,
+    tool_policy_ref: task.routing_constraints_ref,
+    input_ref: task.execution_scope_ref,
+    expected_output_schema: 'rail-task-execution/v1',
+  });
+  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 });
+}
+
+/**
+ * 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 } = {}) {
+  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);
+  const trackingRequired = internalTrackingInstallation(projectDir, clock);
+  const task = handoff.tasks.find((item) => item.task_id === task_id);
+  if (trackingRequired && !task?.clickup_ref) fail('MISSING_CLICKUP_REFERENCE', 'internal RAIL task requires clickup_ref before claim');
+  const intentPath = trackingRequired ? prepareTrackingIntent(projectDir, { handoff_id, task_id, attempt_id, event: 'claim' }) : null;
+  let claim;
+  try {
+    claim = engine.claimTask({
+      handoff, task_id, attempt_id, operator_id, harness_process_id,
+      completed_task_ids, git_dir, ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
+    });
+  } catch (error) {
+    discardTrackingIntentWhenMutationAbsent({
+      intentPath,
+      engine,
+      matchesMutation: (record) => record.type === 'attempt_claimed'
+        && record.payload?.attempt?.attempt_id === attempt_id
+        && record.payload.attempt.task_id === task_id,
+    });
+    throw error;
+  }
+  const tracking_projection = trackingRequired
+    ? replayPendingClickUpProjections({ projectDir, handoff_id, ...(clock === undefined ? {} : { clock }) }).find((item) => item.path === intentPath)
+    : undefined;
+  return Object.freeze({ ...claim, ...(tracking_projection ? { tracking_projection } : {}) });
+}
+
+/** 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 } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  return engine.heartbeat({
+    attempt_id, claim_id, operator_id,
+    ...(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 } = {}) {
+  const { engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  return engine.recoverAttempt({
+    attempt_id, operator_id, harness_process_id, reconciliation, git_dir,
+    ...(lease_ttl_ms === undefined ? {} : { lease_ttl_ms }),
+  });
+}
+
+/**
+ * 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 } = {}) {
+  const { handoff, engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  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;
+  const task = handoff.tasks.find((item) => item.task_id === taskId);
+  if (trackingRequired && !task?.clickup_ref) fail('MISSING_CLICKUP_REFERENCE', 'internal RAIL task requires clickup_ref before completion');
+  const intentPath = trackingRequired ? prepareTrackingIntent(projectDir, { handoff_id, task_id: taskId, attempt_id, completion_id, state, event: 'completion' }) : null;
+  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,
+      ...(completed_at === undefined ? {} : { completed_at }), ...(metrics === undefined ? {} : { metrics }), handoff,
+    });
+  } catch (error) {
+    discardTrackingIntentWhenMutationAbsent({
+      intentPath,
+      engine,
+      matchesMutation: (record) => record.type === 'attempt_completed'
+        && record.payload?.completion?.completion_id === completion_id
+        && record.payload.completion.attempt_id === attempt_id,
+    });
+    throw error;
+  }
+  const result = Object.freeze({ ...completion, immutable_ref: completionReference(handoff.handoff_id, completion.attempt_id, completion.completion_id) });
+  const tracking_projection = trackingRequired
+    ? replayPendingClickUpProjections({ projectDir, handoff_id, ...(clock === undefined ? {} : { clock }) }).find((item) => item.path === intentPath)
+    : undefined;
+  return Object.freeze({ ...result, ...(tracking_projection ? { tracking_projection } : {}) });
+}
+
+/** Resolves only a completion that exists in the immutable project-local journal. */
+export function resolveRailCompletionReference({ projectDir, handoff_id, immutable_ref, clock } = {}) {
+  const { handoff, engine } = loadProjectRail({ projectDir, handoff_id, clock });
+  const prefix = `rail-completion://${handoff.handoff_id}/`;
+  if (typeof immutable_ref !== 'string' || !immutable_ref.startsWith(prefix)) fail('INVALID_COMPLETION_REFERENCE', 'completion reference is not bound to the sealed handoff');
+  const pieces = immutable_ref.slice(prefix.length).split('/');
+  if (pieces.length !== 2) fail('INVALID_COMPLETION_REFERENCE', 'completion reference has an invalid shape');
+  const [attempt_id, completion_id] = pieces;
+  const record = engine.records.find((item) => item.type === 'attempt_completed'
+    && item.payload?.completion?.attempt_id === attempt_id
+    && item.payload.completion.completion_id === completion_id);
+  if (!record) fail('COMPLETION_NOT_FOUND', 'completion reference is absent from the project-local journal');
+  return Object.freeze({ ...record.payload.completion, immutable_ref });
+}

package/src/orchestrator/release-runtime.js

@@ -0,0 +1,14 @@
+import { ReleaseLane } from '@chati/release-lane';
+import { resolveRailCompletionReference } from './rail-runtime.js';
+
+/**
+ * G3 local release authority. The returned ReleaseLane accepts only its own
+ * FakeReleaseTransport capability and resolves completion evidence from the
+ * project-local RAIL journal. It has no external deployment adapter.
+ */
+export function createProjectReleaseLane({ projectDir, handoff_id, clock = () => new Date() } = {}) {
+  return new ReleaseLane({
+    clock,
+    verify_completion: (immutable_ref) => resolveRailCompletionReference({ projectDir, handoff_id, immutable_ref, clock }),
+  });
+}

package/src/orchestrator/review-runtime.js

@@ -0,0 +1,74 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { acceptReview, decideReviewProgress } from '@chati/review-council';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { createProjectRailEngine, loadRailHandoff } from './rail-runtime.js';
+
+function fail(code, message) { const error = new Error(message); error.code = code; throw error; }
+function safeId(value, label) {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9._-]+$/.test(value)) fail('INVALID_REVIEW_STORAGE_ID', `${label} must contain only letters, digits, dot, underscore or hyphen`);
+  return value;
+}
+function reviewDir(projectDir, attemptId) { return join(projectDir, '.chati/v2/rail/reviews', safeId(attemptId, 'attempt_id')); }
+function reviewPath(projectDir, attemptId, reviewId) { return join(reviewDir(projectDir, attemptId), `${safeId(reviewId, 'review_id')}.json`); }
+
+function readReviewEvidence(projectDir, attemptId) {
+  const directory = reviewDir(projectDir, attemptId);
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory).filter((name) => name.endsWith('.json')).sort().map((name) => {
+    try { return JSON.parse(readFileSync(join(directory, name), 'utf8')); }
+    catch { return fail('INVALID_STORED_REVIEW', `review evidence cannot be read: ${name}`); }
+  });
+}
+
+function resolveAttemptLineage(projectDir, attemptId, clock) {
+  const engine = createProjectRailEngine({ projectDir, clock });
+  const claimRecord = engine.records.find((record) => record.type === 'attempt_claimed' && record.payload?.attempt?.attempt_id === attemptId);
+  if (!claimRecord) fail('REVIEW_ATTEMPT_NOT_CLAIMED', `review attempt ${attemptId} has no project-local RAIL claim`);
+  const attempt = claimRecord.payload.attempt;
+  const { handoff } = loadRailHandoff({ projectDir, handoff_id: attempt.handoff_id });
+  if (!handoff.tasks.some((task) => task.task_id === attempt.task_id)) fail('REVIEW_ATTEMPT_TASK_NOT_IN_HANDOFF', `claimed task ${attempt.task_id} is absent from its sealed handoff`);
+  return Object.freeze({
+    handoff_id: handoff.handoff_id,
+    handoff_manifest_digest: handoff.seal.manifest_digest,
+    task_id: attempt.task_id,
+  });
+}
+
+/** Stores a selected-only review record and derives the next rework decision. */
+export function recordRailReview({ projectDir, review, invocation, clock = () => new Date() } = {}) {
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) fail('V2_INSTALLATION_REQUIRED', 'RAIL review requires a v2 installation');
+  const validated = acceptReview({ review, invocation, installation: artifact.installation, snapshot: artifact.capability_snapshot, clock });
+  const lineage = resolveAttemptLineage(projectDir, validated.attempt_id, clock);
+  const path = reviewPath(projectDir, validated.attempt_id, validated.review_id);
+  const content = `${JSON.stringify({ review: validated, invocation, lineage }, null, 2)}\n`;
+  const stored = readReviewEvidence(projectDir, validated.attempt_id);
+  const matching = stored.find((entry) => entry.review?.review_id === validated.review_id);
+  if (matching && readFileSync(path, 'utf8') !== content) fail('REVIEW_STORAGE_CONFLICT', `review ${validated.review_id} already exists with different material`);
+  const prior = stored.filter((entry) => entry.review?.review_id !== validated.review_id);
+  const decision = decideReviewProgress({
+    prior_review_evidence: prior, current_review: validated, reviewer_invocation: invocation,
+    installation: artifact.installation, snapshot: artifact.capability_snapshot, clock,
+  });
+  const review_ref = `rail-review://${lineage.handoff_id}/${validated.attempt_id}/${validated.review_id}`;
+  let written = false;
+  if (!matching) {
+    mkdirSync(reviewDir(projectDir, validated.attempt_id), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    try {
+      linkSync(temporary, path);
+      written = true;
+    } catch (error) {
+      if (error?.code !== 'EEXIST' || readFileSync(path, 'utf8') !== content) fail('REVIEW_STORAGE_CONFLICT', `review ${validated.review_id} raced with different material`);
+    } finally {
+      if (existsSync(temporary)) unlinkSync(temporary);
+    }
+  }
+  const journal = createProjectRailEngine({ projectDir, clock }).recordReviewDecision({
+    attempt_id: validated.attempt_id, review_ref, decision, review: validated, invocation,
+    prior_review_evidence: prior, installation: artifact.installation, snapshot: artifact.capability_snapshot,
+  });
+  return Object.freeze({ path, review_ref, lineage, review: validated, decision, journal, written });
+}

package/src/orchestrator/runtime-installation-v2.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { INSTALLATION_ARTIFACT_PATH, doctorV2 } from '../installer-v2/index.js';
+import { assertEligibleInvocation } from '@chati/provider-registry';
+
+const AGENT_ACTIONS = Object.freeze({
+  'greenfield-wu': 'discovery', 'brownfield-wu': 'discovery', brief: 'discovery',
+  detail: 'planning', architect: 'planning', ux: 'planning', phases: 'planning', tasks: 'planning',
+  'qa-planning': 'review', dev: 'build', 'qa-implementation': 'review', 'qa-visual': 'review',
+  devops: 'build',
+});
+
+export function loadRuntimeInstallationV2(projectDir, { clock = () => new Date() } = {}) {
+  const path = join(projectDir, INSTALLATION_ARTIFACT_PATH);
+  if (!existsSync(path)) return null;
+  let artifact;
+  try { artifact = JSON.parse(readFileSync(path, 'utf8')); } catch (error) {
+    throw Object.assign(new Error('Invalid v2 installation artifact'), { code: 'INVALID_INSTALLATION_ARTIFACT', cause: error });
+  }
+  const doctor = doctorV2(artifact, { clock });
+  if (!doctor.passed) throw Object.assign(new Error('V2 installation artifact failed doctor'), { code: doctor.checks[0]?.code || 'INVALID_INSTALLATION_ARTIFACT' });
+  return Object.freeze(artifact);
+}
+
+export function resolveRuntimeInvocationV2({ artifact, agent, binding, model_id, reasoning_configuration, clock = () => new Date() }) {
+  const action = AGENT_ACTIONS[agent];
+  if (!action) throw Object.assign(new Error(`No v2 action mapping for agent ${agent}`), { code: 'UNMAPPED_AGENT_ACTION' });
+  const candidates = artifact.installation.enabled_providers.flatMap((candidateBinding) => {
+    if (binding && (candidateBinding.provider_id !== binding.provider_id || candidateBinding.harness_id !== binding.harness_id)) return [];
+    return candidateBinding.allowed_models.flatMap((candidateModelId) => {
+      if (model_id && candidateModelId !== model_id) return [];
+      const catalogModel = artifact.capability_snapshot.models.find((candidate) =>
+        candidate.provider_id === candidateBinding.provider_id && candidate.model_id === candidateModelId
+      );
+      if (!catalogModel?.actions.includes(action)) return [];
+      return [{
+        binding: candidateBinding,
+        model: catalogModel,
+        priority: catalogModel.routing_priority?.[agent] ?? catalogModel.routing_priority?.[action] ?? 0,
+      }];
+    });
+  }).sort((left, right) =>
+    right.priority - left.priority
+    || (right.model.adjudication_priority ?? 0) - (left.model.adjudication_priority ?? 0)
+    || `${left.binding.harness_id}:${left.model.model_id}`.localeCompare(`${right.binding.harness_id}:${right.model.model_id}`)
+  );
+  const selectedCandidate = candidates[0];
+  if (!selectedCandidate) throw Object.assign(new Error(`No eligible installed model for ${agent}/${action}`), { code: 'NO_ELIGIBLE_MODEL' });
+  const selected = selectedCandidate.binding;
+  const model = selectedCandidate.model.model_id;
+  const invocation = {
+    provider_id: selected.provider_id, harness_id: selected.harness_id, action,
+    model_pin: { model_id: model, catalog_snapshot_ref: artifact.capability_snapshot.snapshot_id, reasoning_configuration },
+  };
+  assertEligibleInvocation({ installation: artifact.installation, snapshot: artifact.capability_snapshot, invocation, clock });
+  return Object.freeze(invocation);
+}

package/src/orchestrator/session-manager.js

@@ -5,7 +5,7 @@
  * agent completions, and session validation for the Chati.dev pipeline.
  */
 
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 

package/src/telemetry/config.js

@@ -9,7 +9,7 @@ import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { resolveFrameworkDir } from '../utils/framework-dir.js';
 import { randomUUID } from 'crypto';
-import yaml from 'js-yaml';
+import * as yaml from 'js-yaml';
 
 // ---------------------------------------------------------------------------
 // Config Management

package/src/terminal/adapters/grok-adapter.js

@@ -0,0 +1,16 @@
+/**
+ * Grok Build CLI adapter.
+ *
+ * Grok's supported headless form is `grok -p <prompt> -m <model>`. The prompt
+ * deliberately remains an argument here because `-p` is the documented
+ * non-interactive interface. This adapter does not silently select a model.
+ */
+export function buildCommand(config, provider) {
+  const args = [...provider.baseArgs];
+  if (config.model) {
+    const resolvedModel = provider.modelMap[config.model] || config.model;
+    args.push(provider.modelFlag, resolvedModel);
+  }
+  args.push('-p', config.prompt || '');
+  return { command: provider.command, args, stdinPrompt: null };
+}

package/src/terminal/adapters/index.js

@@ -5,3 +5,4 @@
 export * as claude from './claude-adapter.js';
 export * as gemini from './gemini-adapter.js';
 export * as codex from './codex-adapter.js';
+export * as grok from './grok-adapter.js';