agentxchain 2.43.0 → 2.44.0

package/bin/agentxchain.js

@@ -105,6 +105,7 @@ import { intakeScanCommand } from '../src/commands/intake-scan.js';
 import { intakeResolveCommand } from '../src/commands/intake-resolve.js';
 import { intakeStatusCommand } from '../src/commands/intake-status.js';
 import { demoCommand } from '../src/commands/demo.js';
+import { historyCommand } from '../src/commands/history.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -256,6 +257,15 @@ program
   .option('-v, --verbose', 'Show stack traces on failure')
   .action(demoCommand);
 
+program
+  .command('history')
+  .description('Show cross-run history of governed runs in this project')
+  .option('-j, --json', 'Output as JSON')
+  .option('-l, --limit <n>', 'Number of recent runs to show (default: 20)')
+  .option('-s, --status <status>', 'Filter by status: completed, blocked, failed')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(historyCommand);
+
 program
   .command('validate')
   .description('Validate project protocol artifacts')

package/dashboard/app.js

@@ -14,6 +14,7 @@ import { render as renderInitiative } from './components/initiative.js';
 import { render as renderCrossRepo } from './components/cross-repo.js';
 import { render as renderBlockers } from './components/blockers.js';
 import { render as renderArtifacts } from './components/artifacts.js';
+import { render as renderRunHistory } from './components/run-history.js';
 
 const VIEWS = {
   timeline: { fetch: ['state', 'continuity', 'history', 'audit', 'annotations', 'connectors'], render: renderTimeline },
@@ -25,6 +26,7 @@ const VIEWS = {
   'cross-repo': { fetch: ['coordinatorState', 'coordinatorHistory'], render: renderCrossRepo },
   blockers: { fetch: ['coordinatorBlockers'], render: renderBlockers },
   artifacts: { fetch: ['workflowKitArtifacts'], render: renderArtifacts },
+  'run-history': { fetch: ['runHistory'], render: renderRunHistory },
 };
 
 const API_MAP = {
@@ -42,6 +44,7 @@ const API_MAP = {
   coordinatorBlockers: '/api/coordinator/blockers',
   workflowKitArtifacts: '/api/workflow-kit-artifacts',
   connectors: '/api/connectors',
+  runHistory: '/api/run-history',
 };
 
 const viewState = {

package/dashboard/components/run-history.js

@@ -0,0 +1,144 @@
+/**
+ * Run History view — renders cross-run history from /api/run-history.
+ *
+ * Pure render function: takes data from the bridge server, returns HTML.
+ * No business logic — just table rendering with status-colored rows.
+ *
+ * See: RUN_HISTORY_TERMINAL_RECORDING_SPEC.md
+ */
+
+function esc(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function badge(label, color = 'var(--text-dim)') {
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(label)}</span>`;
+}
+
+function statusBadge(status) {
+  switch (status) {
+    case 'completed':
+      return badge('completed', 'var(--green)');
+    case 'blocked':
+      return badge('blocked', 'var(--yellow)');
+    case 'failed':
+      return badge('failed', 'var(--red)');
+    default:
+      return badge(status || 'unknown', 'var(--text-dim)');
+  }
+}
+
+function formatDuration(ms) {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${ms}ms`;
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  if (minutes < 60) return `${minutes}m ${remainingSeconds}s`;
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  return `${hours}h ${remainingMinutes}m`;
+}
+
+function formatCost(usd) {
+  if (usd == null) return '—';
+  return `$${Number(usd).toFixed(2)}`;
+}
+
+function formatDate(iso) {
+  if (!iso) return '—';
+  try {
+    const d = new Date(iso);
+    return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+      + ' ' + d.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+  } catch {
+    return esc(iso);
+  }
+}
+
+function truncateId(id, len = 12) {
+  if (!id) return '—';
+  return id.length > len ? id.slice(0, len) + '…' : id;
+}
+
+function renderRow(entry, index) {
+  const rowClass = entry.status === 'blocked'
+    ? ' style="border-left:3px solid var(--yellow)"'
+    : entry.status === 'failed'
+      ? ' style="border-left:3px solid var(--red)"'
+      : '';
+
+  const phases = Array.isArray(entry.phases_completed) && entry.phases_completed.length > 0
+    ? entry.phases_completed.map(p => esc(p)).join(' → ')
+    : '—';
+
+  const blockedInfo = entry.status === 'blocked' && entry.blocked_reason
+    ? `<div class="blocked-hint" style="font-size:0.85em;color:var(--yellow);margin-top:2px">${esc(typeof entry.blocked_reason === 'string' ? entry.blocked_reason : entry.blocked_reason?.detail || entry.blocked_reason?.category || '')}</div>`
+    : '';
+
+  return `<tr${rowClass}>
+    <td style="color:var(--text-dim)">${index + 1}</td>
+    <td class="mono" title="${esc(entry.run_id)}">${esc(truncateId(entry.run_id))}</td>
+    <td>${statusBadge(entry.status)}${blockedInfo}</td>
+    <td>${phases}</td>
+    <td>${entry.total_turns ?? '—'}</td>
+    <td>${formatCost(entry.total_cost_usd)}</td>
+    <td>${formatDuration(entry.duration_ms)}</td>
+    <td>${formatDate(entry.recorded_at || entry.completed_at)}</td>
+  </tr>`;
+}
+
+export function render({ runHistory }) {
+  if (!runHistory) {
+    return `<div class="placeholder"><h2>Run History</h2><p>No run history data available. Complete a governed run to see cross-run history.</p></div>`;
+  }
+
+  if (!Array.isArray(runHistory) || runHistory.length === 0) {
+    return `<div class="placeholder"><h2>Run History</h2><p>No runs recorded yet. Run history is populated when governed runs reach a terminal state (completed or blocked).</p></div>`;
+  }
+
+  const total = runHistory.length;
+  const completed = runHistory.filter(e => e.status === 'completed').length;
+  const blocked = runHistory.filter(e => e.status === 'blocked').length;
+
+  let html = `<div class="run-history-view">`;
+
+  // Header summary
+  html += `<div class="run-header"><div class="run-meta">`;
+  html += `<span class="turn-count">${total} run${total !== 1 ? 's' : ''} recorded</span>`;
+  if (completed > 0) html += badge(`${completed} completed`, 'var(--green)');
+  if (blocked > 0) html += badge(`${blocked} blocked`, 'var(--yellow)');
+  html += `</div></div>`;
+
+  // Table
+  html += `<div class="section"><h3>Cross-Run History</h3>
+    <table class="data-table">
+      <thead>
+        <tr>
+          <th>#</th>
+          <th>Run ID</th>
+          <th>Status</th>
+          <th>Phases</th>
+          <th>Turns</th>
+          <th>Cost</th>
+          <th>Duration</th>
+          <th>Date</th>
+        </tr>
+      </thead>
+      <tbody>`;
+
+  runHistory.forEach((entry, index) => {
+    html += renderRow(entry, index);
+  });
+
+  html += `</tbody></table></div>`;
+  html += `</div>`;
+  return html;
+}

package/dashboard/index.html

@@ -383,6 +383,7 @@
     <a href="#gate">Gates</a>
     <a href="#blockers">Blockers</a>
     <a href="#artifacts">Artifacts</a>
+    <a href="#run-history">Run History</a>
   </nav>
   <main id="view-container">
     <div class="placeholder">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/history.js

@@ -0,0 +1,120 @@
+/**
+ * agentxchain history — cross-run operator observability.
+ *
+ * Shows a persistent history of governed runs in the current project.
+ */
+
+import { resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import chalk from 'chalk';
+import { queryRunHistory } from '../lib/run-history.js';
+
+/**
+ * @param {object} opts - { json?: boolean, limit?: number, status?: string, dir?: string }
+ */
+export async function historyCommand(opts) {
+  const root = findProjectRoot(opts.dir || process.cwd());
+  if (!root) {
+    console.error(chalk.red('No AgentXchain project found. Run this inside a governed project.'));
+    process.exit(1);
+  }
+
+  const limit = opts.limit ? parseInt(opts.limit, 10) : 20;
+  const entries = queryRunHistory(root, {
+    limit,
+    status: opts.status || undefined,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+
+  if (entries.length === 0) {
+    console.log(chalk.dim('No run history found.'));
+    if (opts.status) {
+      console.log(chalk.dim(`  (filtered by status: ${opts.status})`));
+    }
+    return;
+  }
+
+  // Table header
+  const header = [
+    pad('#', 4),
+    pad('Run ID', 14),
+    pad('Status', 11),
+    pad('Phases', 8),
+    pad('Turns', 6),
+    pad('Cost', 10),
+    pad('Duration', 10),
+    pad('Date', 20),
+  ].join(' ');
+
+  console.log(chalk.bold(header));
+  console.log(chalk.dim('─'.repeat(header.length)));
+
+  entries.forEach((entry, i) => {
+    const idx = String(i + 1);
+    const runId = (entry.run_id || '—').slice(0, 12);
+    const status = formatStatus(entry.status);
+    const phases = String(entry.phases_completed?.length || 0);
+    const turns = String(entry.total_turns || 0);
+    const cost = entry.total_cost_usd != null
+      ? `$${entry.total_cost_usd.toFixed(4)}`
+      : '—';
+    const duration = entry.duration_ms != null
+      ? formatDuration(entry.duration_ms)
+      : '—';
+    const date = entry.recorded_at
+      ? new Date(entry.recorded_at).toLocaleString()
+      : '—';
+
+    console.log([
+      pad(idx, 4),
+      pad(runId, 14),
+      pad(status, 11),
+      pad(phases, 8),
+      pad(turns, 6),
+      pad(cost, 10),
+      pad(duration, 10),
+      pad(date, 20),
+    ].join(' '));
+  });
+
+  console.log(chalk.dim(`\n${entries.length} run(s) shown`));
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(resolve(dir, 'agentxchain.json'))) return dir;
+    const parent = resolve(dir, '..');
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function pad(str, width) {
+  return String(str).padEnd(width);
+}
+
+function formatStatus(status) {
+  if (status === 'completed') return chalk.green('completed');
+  if (status === 'blocked') return chalk.yellow('blocked');
+  if (status === 'failed') return chalk.red('failed');
+  return status || '—';
+}
+
+function formatDuration(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const secs = Math.floor(ms / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  const remainSecs = secs % 60;
+  if (mins < 60) return `${mins}m ${remainSecs}s`;
+  const hrs = Math.floor(mins / 60);
+  const remainMins = mins % 60;
+  return `${hrs}h ${remainMins}m`;
+}

package/src/commands/restart.js

@@ -190,7 +190,8 @@ export async function restartCommand(opts) {
   }
 
   if (state.status === 'failed') {
-    console.log(chalk.red('Run is in terminal state: failed.'));
+    console.log(chalk.red('Run uses reserved status: failed.'));
+    console.log(chalk.dim('Current governed writers do not emit run-level failed. Inspect state.json and recover manually.'));
     process.exit(1);
   }
 

package/src/lib/continuity-status.js

@@ -34,7 +34,16 @@ function deriveRecommendedContinuityAction(state) {
     };
   }
 
-  if (!['blocked', 'completed', 'failed'].includes(state.status)) {
+  if (state.status === 'failed') {
+    return {
+      recommended_command: null,
+      recommended_reason: 'reserved_terminal_state',
+      recommended_detail: 'run-level failed is reserved and not emitted by current governed writers',
+      restart_recommended: false,
+    };
+  }
+
+  if (!['blocked', 'completed'].includes(state.status)) {
     return {
       recommended_command: 'agentxchain restart',
       recommended_reason: 'restart_available',

package/src/lib/dashboard/bridge-server.js

@@ -20,6 +20,7 @@ import { approvePendingDashboardGate } from './actions.js';
 import { readCoordinatorBlockerSnapshot } from './coordinator-blockers.js';
 import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
 import { readConnectorHealthSnapshot } from './connectors.js';
+import { queryRunHistory } from '../run-history.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -293,6 +294,14 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/run-history') {
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      const limit = url.searchParams.get('limit') ? parseInt(url.searchParams.get('limit'), 10) : undefined;
+      const entries = queryRunHistory(workspacePath, { limit });
+      writeJson(res, 200, entries);
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);

package/src/lib/dashboard/state-reader.js

@@ -47,6 +47,7 @@ export const FILE_TO_RESOURCE = Object.fromEntries(
   Object.entries(RESOURCE_MAP).map(([resource, file]) => [normalizeRelativePath(file), resource])
 );
 FILE_TO_RESOURCE[normalizeRelativePath(SESSION_RECOVERY_FILE)] = '/api/continuity';
+FILE_TO_RESOURCE[normalizeRelativePath('run-history.jsonl')] = '/api/run-history';
 
 export const WATCH_DIRECTORIES = [
   '',

package/src/lib/export.js

@@ -29,6 +29,7 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
+  '.agentxchain/run-history.jsonl',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -50,6 +51,7 @@ export const RUN_RESTORE_ROOTS = [
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
+  '.agentxchain/run-history.jsonl',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',

package/src/lib/governed-state.js

@@ -36,6 +36,7 @@ import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir, getRev
 import { runHooks } from './hook-runner.js';
 import { emitNotifications } from './notification-runner.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
+import { recordRunHistory } from './run-history.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -1029,6 +1030,12 @@ function blockRunForHookIssue(root, state, { phase, turnId, hookName, detail, er
     }),
   };
   writeState(root, blockedState);
+
+  // DEC-RHTR-SPEC: Record blocked outcome in cross-run history (non-fatal)
+  if (notificationConfig) {
+    recordRunHistory(root, blockedState, notificationConfig, 'blocked');
+  }
+
   emitBlockedNotification(root, notificationConfig, blockedState, {
     category: typedReason,
     blockedOn: blockedState.blocked_on,
@@ -2094,6 +2101,12 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     });
 
     writeState(root, updatedState);
+
+    // DEC-RHTR-SPEC: Record conflict_loop blocked outcome in cross-run history (non-fatal)
+    if (updatedState.status === 'blocked') {
+      recordRunHistory(root, updatedState, config, 'blocked');
+    }
+
     return {
       ok: false,
       error: `Acceptance conflict detected for turn ${currentTurn.turn_id}`,
@@ -2464,6 +2477,10 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   }
 
   if (updatedState.status === 'blocked') {
+    // DEC-RHTR-SPEC: Record blocked outcome in cross-run history (non-fatal)
+    // Covers needs_human, budget:exhausted, and any other non-hook blocked states
+    recordRunHistory(root, updatedState, config, 'blocked');
+
     emitBlockedNotification(root, config, updatedState, {
       category: updatedState.blocked_reason?.category || 'needs_human',
       blockedOn: updatedState.blocked_on,
@@ -2694,6 +2711,9 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
 
   writeState(root, updatedState);
 
+  // DEC-RHTR-SPEC: Record retries-exhausted blocked outcome in cross-run history (non-fatal)
+  recordRunHistory(root, updatedState, config, 'blocked');
+
   emitBlockedNotification(root, config, updatedState, {
     category: 'retries_exhausted',
     blockedOn: updatedState.blocked_on,
@@ -2913,6 +2933,9 @@ export function approveRunCompletion(root, config) {
   // Session checkpoint — non-fatal
   writeSessionCheckpoint(root, updatedState, 'run_completed');
 
+  // Run history — non-fatal
+  recordRunHistory(root, updatedState, config, 'completed');
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),

package/src/lib/intake.js

@@ -23,7 +23,8 @@ const VALID_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
 const EVENT_ID_RE = /^evt_\d+_[0-9a-f]{4}$/;
 const INTENT_ID_RE = /^intent_\d+_[0-9a-f]{4}$/;
 
-// V3-S1 through S5 states
+// V3-S1 through S5 states. `failed` remains read-tolerant for historical/manual
+// intent files, but current first-party intake writers do not transition into it.
 const S1_STATES = new Set(['detected', 'triaged', 'approved', 'planned', 'executing', 'blocked', 'completed', 'failed', 'suppressed', 'rejected']);
 const TERMINAL_STATES = new Set(['suppressed', 'rejected', 'completed', 'failed']);
 
@@ -32,7 +33,7 @@ const VALID_TRANSITIONS = {
   triaged: ['approved', 'rejected'],
   approved: ['planned'],
   planned: ['executing'],
-  executing: ['blocked', 'completed', 'failed'],
+  executing: ['blocked', 'completed'],
   blocked: ['approved'],
 };
 
@@ -864,23 +865,29 @@ function resolveRepoBackedIntent(root, intentPath, dirs, intent) {
   const now = nowISO();
   const previousStatus = intent.status;
 
-  if (state.status === 'blocked' || state.status === 'failed') {
-    const newStatus = state.status === 'blocked' ? 'blocked' : 'failed';
-    intent.status = newStatus;
+  // Run-level 'failed' is reserved/unreached in current governed writers (DEC-RUN-STATUS-001).
+  // Fail closed if encountered — operator must investigate manually.
+  if (state.status === 'failed') {
+    return {
+      ok: false,
+      error: 'governed run has reserved status "failed" which is not emitted by current governed writers. Manual inspection required. See DEC-RUN-STATUS-001.',
+      exitCode: 1,
+    };
+  }
+
+  if (state.status === 'blocked') {
+    intent.status = 'blocked';
     intent.run_blocked_on = state.blocked_on || null;
     intent.run_blocked_reason = state.blocked_reason?.category || null;
     intent.run_blocked_recovery = state.blocked_reason?.recovery?.recovery_action || null;
-    if (newStatus === 'failed') {
-      intent.run_failed_at = now;
-    }
     intent.updated_at = now;
     intent.history.push({
       from: previousStatus,
-      to: newStatus,
+      to: 'blocked',
       at: now,
-      reason: `governed run ${intent.target_run} reached status ${state.status}`,
+      reason: `governed run ${intent.target_run} reached status blocked`,
       run_id: intent.target_run,
-      run_status: state.status,
+      run_status: 'blocked',
     });
 
     safeWriteJson(intentPath, intent);
@@ -888,8 +895,8 @@ function resolveRepoBackedIntent(root, intentPath, dirs, intent) {
       ok: true,
       intent,
       previous_status: previousStatus,
-      new_status: newStatus,
-      run_outcome: state.status,
+      new_status: 'blocked',
+      run_outcome: 'blocked',
       no_change: false,
       exitCode: 0,
     };
@@ -1025,15 +1032,26 @@ function resolveCoordinatorBackedIntent(root, intentPath, dirs, intent) {
     };
   }
 
-  if (coordinatorState.status === 'failed' || coordinatorState.status === 'completed') {
-    intent.status = 'failed';
-    intent.run_failed_at = now;
+  // Coordinator run-level 'failed' is reserved/unreached (DEC-RUN-STATUS-001). Fail closed.
+  if (coordinatorState.status === 'failed') {
+    return {
+      ok: false,
+      error: `coordinator run ${expectedSuperRunId} has reserved status "failed" which is not emitted by current governed writers. Manual inspection required. See DEC-RUN-STATUS-001.`,
+      exitCode: 1,
+    };
+  }
+
+  if (coordinatorState.status === 'completed') {
+    intent.status = 'blocked';
+    intent.run_blocked_on = `coordinator:completed_without_workstream:${workstreamId}`;
+    intent.run_blocked_reason = 'coordinator_completed_without_workstream';
+    intent.run_blocked_recovery = `Coordinator run ${expectedSuperRunId} completed without satisfying workstream ${workstreamId}. Re-approve the intent and start a new run.`;
     intent.updated_at = now;
     intent.history.push({
       from: previousStatus,
-      to: 'failed',
+      to: 'blocked',
       at: now,
-      reason: `coordinator run ${expectedSuperRunId} ended without satisfying workstream ${workstreamId}`,
+      reason: `coordinator run ${expectedSuperRunId} completed without satisfying workstream ${workstreamId}`,
       super_run_id: expectedSuperRunId,
       run_status: coordinatorState.status,
     });
@@ -1043,7 +1061,7 @@ function resolveCoordinatorBackedIntent(root, intentPath, dirs, intent) {
       ok: true,
       intent,
       previous_status: previousStatus,
-      new_status: 'failed',
+      new_status: 'blocked',
       run_outcome: coordinatorState.status,
       no_change: false,
       exitCode: 0,

package/src/lib/repo-observer.js

@@ -40,6 +40,7 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/lock.json',
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
+  '.agentxchain/run-history.jsonl',
   'TALK.md',
 ];
 

package/src/lib/run-history.js

@@ -0,0 +1,156 @@
+/**
+ * Run History — cross-run operator observability.
+ *
+ * Append-only JSONL ledger persisting summary metadata from each governed run.
+ * Survives across runs (not reset by initializeGovernedRun).
+ *
+ * DEC-RH-SPEC: .planning/RUN_HISTORY_SPEC.md
+ */
+
+import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+const RUN_HISTORY_PATH = '.agentxchain/run-history.jsonl';
+const HISTORY_PATH = '.agentxchain/history.jsonl';
+const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
+const SCHEMA_VERSION = '0.1';
+const WRITABLE_TERMINAL_STATUSES = new Set(['completed', 'blocked']);
+
+/**
+ * Record a run's summary into the persistent run-history ledger.
+ * Non-fatal: catches and returns { ok: false, error } on failure.
+ *
+ * @param {string} root - project root directory
+ * @param {object} state - final governed state
+ * @param {object} config - normalized config
+ * @param {'completed'|'blocked'} status - terminal status produced by current governed writers
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function recordRunHistory(root, state, config, status) {
+  try {
+    if (!WRITABLE_TERMINAL_STATUSES.has(status)) {
+      return {
+        ok: false,
+        error: `Unsupported run-history terminal status: ${status}. Current governed writers emit completed or blocked only.`,
+      };
+    }
+
+    const filePath = join(root, RUN_HISTORY_PATH);
+    mkdirSync(dirname(filePath), { recursive: true });
+
+    const historyEntries = readJsonlSafe(root, HISTORY_PATH);
+    const ledgerEntries = readJsonlSafe(root, LEDGER_PATH);
+
+    // Extract unique phases and roles from turn history
+    const phasesCompleted = [...new Set(historyEntries.map(e => e.phase).filter(Boolean))];
+    const rolesUsed = [...new Set(historyEntries.map(e => e.role).filter(Boolean))];
+
+    // Derive connector and model from config
+    const firstRole = Object.values(config.roles || {})[0];
+    const connectorUsed = firstRole?.runtime_id || firstRole?.runtime || null;
+    const modelUsed = firstRole?.model || config.adapter?.model || null;
+
+    // Derive run start time from first history entry or state
+    const startedAt = historyEntries[0]?.accepted_at
+      || state?.created_at
+      || null;
+    const completedAt = state?.completed_at || null;
+    const durationMs = (startedAt && completedAt)
+      ? new Date(completedAt).getTime() - new Date(startedAt).getTime()
+      : null;
+
+    const record = {
+      schema_version: SCHEMA_VERSION,
+      run_id: state?.run_id || null,
+      project_id: config.project?.id || null,
+      project_name: config.project?.name || null,
+      template: config.template || null,
+      status,
+      started_at: startedAt,
+      completed_at: completedAt,
+      duration_ms: durationMs,
+      phases_completed: phasesCompleted,
+      total_turns: historyEntries.length,
+      roles_used: rolesUsed,
+      decisions_count: ledgerEntries.length,
+      total_cost_usd: state?.budget_status?.spent_usd ?? null,
+      budget_limit_usd: config.budget?.per_run_max_usd ?? null,
+      blocked_reason: status === 'blocked' ? (state?.blocked_reason?.detail || state?.blocked_on || null) : null,
+      gate_results: state?.phase_gate_status || {},
+      connector_used: connectorUsed,
+      model_used: modelUsed,
+      recorded_at: new Date().toISOString(),
+    };
+
+    appendFileSync(filePath, JSON.stringify(record) + '\n');
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * Query the run-history ledger.
+ *
+ * @param {string} root - project root directory
+ * @param {object} [opts] - { limit?: number, status?: string }
+ * @returns {Array<object>} most-recent-first
+ */
+export function queryRunHistory(root, opts = {}) {
+  const filePath = join(root, RUN_HISTORY_PATH);
+  if (!existsSync(filePath)) return [];
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return [];
+  }
+  if (!content) return [];
+
+  let entries = content
+    .split('\n')
+    .filter(Boolean)
+    .map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    })
+    .filter(Boolean);
+
+  // Filter by status if requested
+  if (opts.status) {
+    entries = entries.filter(e => e.status === opts.status);
+  }
+
+  // Most recent first
+  entries.reverse();
+
+  // Limit
+  if (opts.limit && opts.limit > 0) {
+    entries = entries.slice(0, opts.limit);
+  }
+
+  return entries;
+}
+
+/**
+ * Get the path to the run-history file.
+ */
+export function getRunHistoryPath(root) {
+  return join(root, RUN_HISTORY_PATH);
+}
+
+// ── Internal ────────────────────────────────────────────────────────────────
+
+function readJsonlSafe(root, relPath) {
+  const filePath = join(root, relPath);
+  if (!existsSync(filePath)) return [];
+  try {
+    const content = readFileSync(filePath, 'utf8').trim();
+    if (!content) return [];
+    return content.split('\n').filter(Boolean).map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/lib/schema.js

@@ -31,6 +31,8 @@ export function validateStateSchema(data) {
 
 export function validateGovernedStateSchema(data) {
   const errors = [];
+  // Keep `failed` for compatibility. Current governed writers do not emit it,
+  // but validators and read-only surfaces still tolerate reserved/manual states.
   const VALID_RUN_STATUSES = ['idle', 'active', 'paused', 'blocked', 'completed', 'failed'];
   const isV1_1 = data?.schema_version === '1.1';
   const hasLegacyCurrentTurn = Object.prototype.hasOwnProperty.call(data || {}, 'current_turn');