agentxchain 2.46.0 → 2.47.0

package/bin/agentxchain.js

@@ -262,7 +262,8 @@ program
   .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('-s, --status <status>', 'Filter by status: completed or blocked')
+  .option('--lineage <run_id>', 'Show lineage chain for a specific run')
   .option('-d, --dir <path>', 'Project directory')
   .action(historyCommand);
 
@@ -355,6 +356,8 @@ program
   .option('--verbose', 'Stream adapter subprocess output')
   .option('--dry-run', 'Print what would be dispatched without executing')
   .option('--no-report', 'Suppress automatic governance report after run completes')
+  .option('--continue-from <run_id>', 'Continue from a prior terminal run (sets trigger=continuation)')
+  .option('--recover-from <run_id>', 'Recover from a prior blocked run (sets trigger=recovery)')
   .action(runCommand);
 
 program

package/dashboard/app.js

@@ -15,6 +15,8 @@ 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';
+import { render as renderTimeouts } from './components/timeouts.js';
+import { render as renderCoordinatorTimeouts } from './components/coordinator-timeouts.js';
 
 const VIEWS = {
   timeline: { fetch: ['state', 'continuity', 'history', 'audit', 'annotations', 'connectors'], render: renderTimeline },
@@ -27,6 +29,8 @@ const VIEWS = {
   blockers: { fetch: ['coordinatorBlockers'], render: renderBlockers },
   artifacts: { fetch: ['workflowKitArtifacts'], render: renderArtifacts },
   'run-history': { fetch: ['runHistory'], render: renderRunHistory },
+  timeouts: { fetch: ['timeouts'], render: renderTimeouts },
+  'coordinator-timeouts': { fetch: ['coordinatorTimeouts'], render: renderCoordinatorTimeouts },
 };
 
 const API_MAP = {
@@ -45,6 +49,8 @@ const API_MAP = {
   workflowKitArtifacts: '/api/workflow-kit-artifacts',
   connectors: '/api/connectors',
   runHistory: '/api/run-history',
+  timeouts: '/api/timeouts',
+  coordinatorTimeouts: '/api/coordinator/timeouts',
 };
 
 const viewState = {

package/dashboard/components/coordinator-timeouts.js

@@ -0,0 +1,220 @@
+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 scopeLabel(scope) {
+  if (scope === 'turn') return 'Per-Turn';
+  if (scope === 'phase') return 'Per-Phase';
+  if (scope === 'run') return 'Per-Run';
+  return esc(scope || '—');
+}
+
+function actionBadge(action) {
+  if (action === 'escalate') return badge('escalate', 'var(--red)');
+  if (action === 'warn') return badge('warn', 'var(--yellow)');
+  if (action === 'skip_phase') return badge('skip_phase', 'var(--accent)');
+  return badge(action || '—');
+}
+
+function typeLabel(type) {
+  if (type === 'timeout') return badge('exceeded', 'var(--red)');
+  if (type === 'timeout_warning') return badge('warning', 'var(--yellow)');
+  if (type === 'timeout_skip') return badge('skipped', 'var(--accent)');
+  if (type === 'timeout_skip_failed') return badge('skip failed', 'var(--red)');
+  return badge(type || '—');
+}
+
+function statusColor(status) {
+  const colors = {
+    active: 'var(--green)',
+    blocked: 'var(--red)',
+    paused: 'var(--yellow)',
+    completed: 'var(--accent)',
+    idle: 'var(--text-dim)',
+    initialized: 'var(--accent)',
+    linked: 'var(--green)',
+  };
+  return colors[status] || 'var(--text-dim)';
+}
+
+function renderSummary(summary) {
+  return `<div class="gate-card"><h3>Summary</h3>
+    <dl class="detail-list">
+      <dt>Repos</dt><dd>${summary.repo_count}</dd>
+      <dt>Timeout Configured</dt><dd>${summary.configured_repo_count}</dd>
+      <dt>Live Exceeded</dt><dd>${summary.repos_with_live_exceeded}</dd>
+      <dt>Live Warnings</dt><dd>${summary.repos_with_live_warnings}</dd>
+      <dt>Repo Events</dt><dd>${summary.repo_event_count}</dd>
+      <dt>Coordinator Events</dt><dd>${summary.coordinator_event_count}</dd>
+    </dl>
+  </div>`;
+}
+
+function renderConfigTable(config) {
+  if (!config) {
+    return `<p style="color:var(--text-dim)">No <code>timeouts</code> configured in this repo.</p>`;
+  }
+
+  let html = `<table class="data-table">
+    <thead><tr><th>Scope</th><th>Limit</th><th>Action</th></tr></thead>
+    <tbody>`;
+  if (config.per_turn_minutes) {
+    html += `<tr><td>Per-Turn</td><td>${config.per_turn_minutes}m</td><td>${actionBadge(config.action)}</td></tr>`;
+  }
+  if (config.per_phase_minutes) {
+    html += `<tr><td>Per-Phase</td><td>${config.per_phase_minutes}m</td><td>${actionBadge(config.action)}</td></tr>`;
+  }
+  if (config.per_run_minutes) {
+    html += `<tr><td>Per-Run</td><td>${config.per_run_minutes}m</td><td>${actionBadge(config.action)}</td></tr>`;
+  }
+  for (const override of (config.phase_overrides || [])) {
+    html += `<tr><td>Phase: <strong>${esc(override.phase)}</strong></td><td>${override.limit_minutes ? `${override.limit_minutes}m` : 'inherit'}</td><td>${override.action ? actionBadge(override.action) : 'inherit'}</td></tr>`;
+  }
+  html += `</tbody></table>`;
+  return html;
+}
+
+function renderLiveTable(live) {
+  const exceeded = live?.exceeded || [];
+  const warnings = live?.warnings || [];
+  if (exceeded.length === 0 && warnings.length === 0) {
+    return `<p style="color:var(--green)">No live timeout pressure.</p>`;
+  }
+
+  let html = `<table class="data-table">
+    <thead><tr><th>Status</th><th>Scope</th><th>Turn</th><th>Phase</th><th>Elapsed</th><th>Limit</th><th>Exceeded By</th><th>Action</th></tr></thead>
+    <tbody>`;
+  for (const item of exceeded) {
+    const turnLabel = item.turn_id
+      ? `<span class="mono">${esc(item.turn_id)}</span>${item.role_id ? ` <span style="color:var(--text-dim)">(${esc(item.role_id)})</span>` : ''}`
+      : '—';
+    html += `<tr style="border-left:3px solid var(--red)">
+      <td>${badge('EXCEEDED', 'var(--red)')}</td>
+      <td>${scopeLabel(item.scope)}</td>
+      <td>${turnLabel}</td>
+      <td>${item.phase ? esc(item.phase) : '—'}</td>
+      <td>${item.elapsed_minutes}m</td>
+      <td>${item.limit_minutes}m</td>
+      <td style="color:var(--red)">${item.exceeded_by_minutes}m</td>
+      <td>${actionBadge(item.action)}</td>
+    </tr>`;
+  }
+  for (const item of warnings) {
+    const turnLabel = item.turn_id
+      ? `<span class="mono">${esc(item.turn_id)}</span>${item.role_id ? ` <span style="color:var(--text-dim)">(${esc(item.role_id)})</span>` : ''}`
+      : '—';
+    html += `<tr style="border-left:3px solid var(--yellow)">
+      <td>${badge('WARNING', 'var(--yellow)')}</td>
+      <td>${scopeLabel(item.scope)}</td>
+      <td>${turnLabel}</td>
+      <td>${item.phase ? esc(item.phase) : '—'}</td>
+      <td>${item.elapsed_minutes}m</td>
+      <td>${item.limit_minutes}m</td>
+      <td>${item.exceeded_by_minutes}m</td>
+      <td>${actionBadge(item.action)}</td>
+    </tr>`;
+  }
+  html += `</tbody></table>`;
+  return html;
+}
+
+function renderEventTable(events, title) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return `<div class="section"><h3>${title}</h3><p style="color:var(--text-dim)">No timeout events recorded.</p></div>`;
+  }
+
+  let html = `<div class="section"><h3>${title}</h3>
+    <table class="data-table">
+      <thead><tr><th>Type</th><th>Scope</th><th>Phase</th><th>Turn</th><th>Elapsed</th><th>Limit</th><th>Action</th></tr></thead>
+      <tbody>`;
+  for (const event of events) {
+    html += `<tr>
+      <td>${typeLabel(event.type)}</td>
+      <td>${scopeLabel(event.scope)}</td>
+      <td>${event.phase ? esc(event.phase) : '—'}</td>
+      <td class="mono">${event.turn_id ? esc(event.turn_id) : '—'}</td>
+      <td>${event.elapsed_minutes != null ? `${event.elapsed_minutes}m` : '—'}</td>
+      <td>${event.limit_minutes != null ? `${event.limit_minutes}m` : '—'}</td>
+      <td>${actionBadge(event.action)}</td>
+    </tr>`;
+  }
+  html += `</tbody></table></div>`;
+  return html;
+}
+
+function renderRepoCard(repo) {
+  let html = `<div class="turn-card">
+    <div class="turn-header">
+      <span class="mono">${esc(repo.repo_id)}</span>
+      ${repo.status ? badge(repo.status, statusColor(repo.status)) : ''}
+      ${repo.configured ? badge('timeouts configured', 'var(--green)') : badge('no timeouts', 'var(--text-dim)')}
+    </div>`;
+
+  html += `<dl class="detail-list">
+    <dt>Path</dt><dd class="mono">${esc(repo.path)}</dd>`;
+  if (repo.run_id) {
+    html += `<dt>Run</dt><dd class="mono">${esc(repo.run_id)}</dd>`;
+  }
+  if (repo.phase) {
+    html += `<dt>Phase</dt><dd>${esc(repo.phase)}</dd>`;
+  }
+  html += `</dl>`;
+
+  if (repo.error) {
+    html += `<p style="color:var(--red)">${esc(repo.error.error)}</p></div>`;
+    return html;
+  }
+
+  html += `<div class="section"><h3>Configuration</h3>${renderConfigTable(repo.config)}</div>`;
+  if (repo.live) {
+    html += `<div class="section"><h3>Live Pressure</h3>${renderLiveTable(repo.live)}</div>`;
+  }
+  html += renderEventTable(repo.events, 'Repo Events');
+  html += `</div>`;
+  return html;
+}
+
+export function render({ coordinatorTimeouts }) {
+  if (!coordinatorTimeouts) {
+    return `<div class="placeholder"><h2>Coordinator Timeouts</h2><p>No coordinator timeout data available. Ensure a coordinator run is active.</p></div>`;
+  }
+
+  if (coordinatorTimeouts.ok === false) {
+    return `<div class="placeholder"><h2>Coordinator Timeouts</h2><p>${esc(coordinatorTimeouts.error || 'Failed to load coordinator timeout data.')}</p></div>`;
+  }
+
+  let html = `<div class="timeouts-view"><div class="run-header"><div class="run-meta">`;
+  if (coordinatorTimeouts.super_run_id) {
+    html += `<span class="mono run-id">${esc(coordinatorTimeouts.super_run_id)}</span>`;
+  }
+  if (coordinatorTimeouts.status) {
+    html += badge(coordinatorTimeouts.status, statusColor(coordinatorTimeouts.status));
+  }
+  if (coordinatorTimeouts.phase) {
+    html += `<span class="phase-label">Phase: <strong>${esc(coordinatorTimeouts.phase)}</strong></span>`;
+  }
+  html += `${badge('coordinator timeout view', 'var(--accent)')}</div></div>`;
+
+  if (coordinatorTimeouts.blocked_reason) {
+    html += `<div class="blocked-banner"><div class="blocked-icon">BLOCKED</div><div class="blocked-reason">${esc(typeof coordinatorTimeouts.blocked_reason === 'string' ? coordinatorTimeouts.blocked_reason : JSON.stringify(coordinatorTimeouts.blocked_reason))}</div></div>`;
+  }
+
+  html += renderSummary(coordinatorTimeouts.summary);
+  html += renderEventTable(coordinatorTimeouts.coordinator_events, 'Coordinator Events');
+  html += `<div class="section"><h3>Repo Timeout Status</h3><div class="turn-list">`;
+  for (const repo of (coordinatorTimeouts.repos || [])) {
+    html += renderRepoCard(repo);
+  }
+  html += `</div></div></div>`;
+  return html;
+}

package/dashboard/components/timeouts.js

@@ -0,0 +1,201 @@
+/**
+ * Timeouts view — renders live timeout pressure and persisted timeout events.
+ *
+ * Pure render function: takes data from /api/timeouts, returns HTML.
+ * All evaluation is server-side. This view renders the snapshot.
+ *
+ * See: TIMEOUT_DASHBOARD_SURFACE_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 scopeLabel(scope) {
+  if (scope === 'turn') return 'Per-Turn';
+  if (scope === 'phase') return 'Per-Phase';
+  if (scope === 'run') return 'Per-Run';
+  return esc(scope || '—');
+}
+
+function actionBadge(action) {
+  if (action === 'escalate') return badge('escalate', 'var(--red)');
+  if (action === 'warn') return badge('warn', 'var(--yellow)');
+  if (action === 'skip_phase') return badge('skip_phase', 'var(--accent)');
+  return badge(action || '—', 'var(--text-dim)');
+}
+
+function typeLabel(type) {
+  if (type === 'timeout') return badge('exceeded', 'var(--red)');
+  if (type === 'timeout_warning') return badge('warning', 'var(--yellow)');
+  if (type === 'timeout_skip') return badge('skipped', 'var(--accent)');
+  if (type === 'timeout_skip_failed') return badge('skip failed', 'var(--red)');
+  return badge(type || '—');
+}
+
+function formatTime(ts) {
+  if (!ts) return '—';
+  try {
+    const d = new Date(ts);
+    return d.toLocaleString();
+  } catch {
+    return esc(ts);
+  }
+}
+
+function renderConfigTable(config) {
+  let html = `<div class="section"><h3>Timeout Configuration</h3>
+    <table class="data-table">
+      <thead><tr><th>Scope</th><th>Limit</th><th>Action</th></tr></thead>
+      <tbody>`;
+
+  if (config.per_turn_minutes) {
+    html += `<tr><td>Per-Turn</td><td>${config.per_turn_minutes}m</td><td>${actionBadge(config.action)}</td></tr>`;
+  }
+  if (config.per_phase_minutes) {
+    html += `<tr><td>Per-Phase (global)</td><td>${config.per_phase_minutes}m</td><td>${actionBadge(config.action)}</td></tr>`;
+  }
+  if (config.per_run_minutes) {
+    html += `<tr><td>Per-Run</td><td>${config.per_run_minutes}m</td><td>${actionBadge(config.action)}</td></tr>`;
+  }
+
+  if (Array.isArray(config.phase_overrides)) {
+    for (const override of config.phase_overrides) {
+      const limitStr = override.limit_minutes ? `${override.limit_minutes}m` : '<span style="color:var(--text-dim)">inherit</span>';
+      const actionStr = override.action ? actionBadge(override.action) : '<span style="color:var(--text-dim)">inherit</span>';
+      html += `<tr><td>Phase: <strong>${esc(override.phase)}</strong></td><td>${limitStr}</td><td>${actionStr}</td></tr>`;
+    }
+  }
+
+  html += `</tbody></table></div>`;
+  return html;
+}
+
+function renderLivePressure(live) {
+  const hasExceeded = live.exceeded && live.exceeded.length > 0;
+  const hasWarnings = live.warnings && live.warnings.length > 0;
+
+  if (!hasExceeded && !hasWarnings) {
+    return `<div class="section"><h3>Live Pressure</h3><p style="color:var(--green)">No timeouts exceeded or approaching limits.</p></div>`;
+  }
+
+  let html = `<div class="section"><h3>Live Pressure</h3>
+    <table class="data-table">
+      <thead><tr><th>Status</th><th>Scope</th><th>Turn</th><th>Phase</th><th>Elapsed</th><th>Limit</th><th>Exceeded By</th><th>Action</th></tr></thead>
+      <tbody>`;
+
+  for (const item of (live.exceeded || [])) {
+    const turnLabel = item.turn_id
+      ? `<span class="mono">${esc(item.turn_id)}</span>${item.role_id ? ` <span style="color:var(--text-dim)">(${esc(item.role_id)})</span>` : ''}`
+      : '—';
+    html += `<tr style="border-left:3px solid var(--red)">
+      <td>${badge('EXCEEDED', 'var(--red)')}</td>
+      <td>${scopeLabel(item.scope)}</td>
+      <td>${turnLabel}</td>
+      <td>${item.phase ? esc(item.phase) : '—'}</td>
+      <td>${item.elapsed_minutes}m</td>
+      <td>${item.limit_minutes}m</td>
+      <td style="color:var(--red)">${item.exceeded_by_minutes}m</td>
+      <td>${actionBadge(item.action)}</td>
+    </tr>`;
+  }
+
+  for (const item of (live.warnings || [])) {
+    const turnLabel = item.turn_id
+      ? `<span class="mono">${esc(item.turn_id)}</span>${item.role_id ? ` <span style="color:var(--text-dim)">(${esc(item.role_id)})</span>` : ''}`
+      : '—';
+    html += `<tr style="border-left:3px solid var(--yellow)">
+      <td>${badge('WARNING', 'var(--yellow)')}</td>
+      <td>${scopeLabel(item.scope)}</td>
+      <td>${turnLabel}</td>
+      <td>${item.phase ? esc(item.phase) : '—'}</td>
+      <td>${item.elapsed_minutes}m</td>
+      <td>${item.limit_minutes}m</td>
+      <td>${item.exceeded_by_minutes}m</td>
+      <td>${actionBadge(item.action)}</td>
+    </tr>`;
+  }
+
+  html += `</tbody></table></div>`;
+  return html;
+}
+
+function renderEvents(events) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return `<div class="section"><h3>Timeout Events</h3><p style="color:var(--text-dim)">No timeout events recorded in the decision ledger.</p></div>`;
+  }
+
+  let html = `<div class="section"><h3>Timeout Events</h3>
+    <table class="data-table">
+      <thead><tr><th>Type</th><th>Scope</th><th>Phase</th><th>Turn</th><th>Elapsed</th><th>Limit</th><th>Action</th><th>Timestamp</th></tr></thead>
+      <tbody>`;
+
+  for (const event of events) {
+    html += `<tr>
+      <td>${typeLabel(event.type)}</td>
+      <td>${scopeLabel(event.scope)}</td>
+      <td>${event.phase ? esc(event.phase) : '—'}</td>
+      <td class="mono">${event.turn_id ? esc(event.turn_id) : '—'}</td>
+      <td>${event.elapsed_minutes != null ? `${event.elapsed_minutes}m` : '—'}</td>
+      <td>${event.limit_minutes != null ? `${event.limit_minutes}m` : '—'}</td>
+      <td>${actionBadge(event.action)}</td>
+      <td>${formatTime(event.timestamp)}</td>
+    </tr>`;
+  }
+
+  html += `</tbody></table></div>`;
+  return html;
+}
+
+export function render({ timeouts }) {
+  if (!timeouts) {
+    return `<div class="placeholder"><h2>Timeouts</h2><p>No timeout data available. Ensure a governed run is active.</p></div>`;
+  }
+
+  if (timeouts.ok === false) {
+    const hint = timeouts.code === 'config_missing' || timeouts.code === 'state_missing'
+      ? ' Run <code>agentxchain init --governed</code> to get started.'
+      : '';
+    return `<div class="placeholder"><h2>Timeouts</h2><p>${esc(timeouts.error || 'Failed to load timeout data.')}${hint}</p></div>`;
+  }
+
+  if (!timeouts.configured) {
+    return `<div class="placeholder"><h2>Timeouts</h2><p>No <code>timeouts</code> configured in <code>agentxchain.json</code>. Add a <code>timeouts</code> section to enable time-limit enforcement.</p></div>`;
+  }
+
+  let html = `<div class="timeouts-view">`;
+
+  // Header
+  html += `<div class="run-header"><div class="run-meta">`;
+  html += `<span class="phase-label"><strong>Timeouts</strong></span>`;
+  html += badge('configured', 'var(--green)');
+  const eventCount = Array.isArray(timeouts.events) ? timeouts.events.length : 0;
+  if (eventCount > 0) {
+    html += `<span class="turn-count">${eventCount} event${eventCount !== 1 ? 's' : ''} recorded</span>`;
+  }
+  html += `</div></div>`;
+
+  // Config summary
+  html += renderConfigTable(timeouts.config);
+
+  // Live pressure
+  if (timeouts.live) {
+    html += renderLivePressure(timeouts.live);
+  }
+
+  // Persisted events
+  html += renderEvents(timeouts.events);
+
+  html += `</div>`;
+  return html;
+}

package/dashboard/index.html

@@ -384,6 +384,8 @@
     <a href="#blockers">Blockers</a>
     <a href="#artifacts">Artifacts</a>
     <a href="#run-history">Run History</a>
+    <a href="#timeouts">Timeouts</a>
+    <a href="#coordinator-timeouts">Coordinator Timeouts</a>
   </nav>
   <main id="view-container">
     <div class="placeholder">

package/package.json

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

package/scripts/publish-from-tag.sh

@@ -16,10 +16,35 @@ cleanup() {
 trap cleanup EXIT
 
 usage() {
-  echo "Usage: bash scripts/publish-from-tag.sh <vX.Y.Z>" >&2
+  echo "Usage: bash scripts/publish-from-tag.sh [--skip-preflight] <vX.Y.Z>" >&2
 }
 
-TAG="${1:-}"
+SKIP_PREFLIGHT=0
+TAG=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --skip-preflight)
+      SKIP_PREFLIGHT=1
+      shift
+      ;;
+    -*)
+      echo "Error: unknown option '$1'" >&2
+      usage
+      exit 1
+      ;;
+    *)
+      if [[ -n "$TAG" ]]; then
+        echo "Error: release tag must be provided exactly once" >&2
+        usage
+        exit 1
+      fi
+      TAG="$1"
+      shift
+      ;;
+  esac
+done
+
 if [[ -z "$TAG" ]]; then
   echo "Error: release tag is required" >&2
   usage
@@ -55,8 +80,12 @@ if ! [[ "$RETRY_DELAY_SECONDS" =~ ^[0-9]+$ ]]; then
 fi
 
 echo "Publishing ${PACKAGE_NAME}@${RELEASE_VERSION} from ${TAG}"
-echo "Running strict release preflight..."
-bash scripts/release-preflight.sh --strict --target-version "${RELEASE_VERSION}"
+if [[ "$SKIP_PREFLIGHT" -eq 1 ]]; then
+  echo "Skipping strict release preflight because the caller already owns tagged-state verification."
+else
+  echo "Running strict release preflight..."
+  bash scripts/release-preflight.sh --strict --target-version "${RELEASE_VERSION}"
+fi
 
 EXISTING_VERSION="$(npm view "${PACKAGE_NAME}@${RELEASE_VERSION}" version 2>/dev/null || true)"
 if [[ "$EXISTING_VERSION" == "$RELEASE_VERSION" ]]; then

package/src/commands/history.js

@@ -7,7 +7,8 @@
 import { resolve } from 'path';
 import { existsSync, readFileSync } from 'fs';
 import chalk from 'chalk';
-import { queryRunHistory } from '../lib/run-history.js';
+import { queryRunHistory, queryRunLineage } from '../lib/run-history.js';
+import { getRunTriggerLabel, summarizeRunProvenance } from '../lib/run-provenance.js';
 
 /**
  * @param {object} opts - { json?: boolean, limit?: number, status?: string, dir?: string }
@@ -19,6 +20,42 @@ export async function historyCommand(opts) {
     process.exit(1);
   }
 
+  // ── Lineage mode ─────────────────────────────────────────────────────────
+  if (opts.lineage) {
+    const result = queryRunLineage(root, opts.lineage);
+    if (!result.ok) {
+      console.error(chalk.red(result.error));
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(result.chain, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold(`Run Lineage for ${opts.lineage}:`));
+    result.chain.forEach((entry, i) => {
+      if (entry.broken_link) {
+        const prefix = i === 0 ? '  ' : '  └─ ';
+        console.log(chalk.red(`${prefix}[broken link: ${entry.missing_run_id}]`));
+        return;
+      }
+      const runId = (entry.run_id || '—').slice(0, 12);
+      const status = formatStatus(entry.status);
+      const phases = (entry.phases_completed || []).join(',') || '—';
+      const turns = `${entry.total_turns || 0} turns`;
+      const cost = entry.total_cost_usd != null ? `$${entry.total_cost_usd.toFixed(2)}` : '';
+      const trigger = getRunTriggerLabel(entry.provenance);
+      const parentNote = entry.provenance?.parent_run_id
+        ? ` from ${entry.provenance.parent_run_id.slice(0, 12)}`
+        : '';
+      const prefix = i === 0 ? '  ' : '  └─ ';
+      console.log(`${prefix}${runId}  ${status}  ${pad(phases, 20)}  ${pad(turns, 10)}  ${pad(cost, 8)}  (${trigger}${parentNote})`);
+    });
+    return;
+  }
+
+  // ── Standard history view ────────────────────────────────────────────────
   const limit = opts.limit ? parseInt(opts.limit, 10) : 20;
   const entries = queryRunHistory(root, {
     limit,
@@ -43,6 +80,7 @@ export async function historyCommand(opts) {
     pad('#', 4),
     pad('Run ID', 14),
     pad('Status', 11),
+    pad('Trigger', 14),
     pad('Phases', 8),
     pad('Turns', 6),
     pad('Cost', 10),
@@ -57,6 +95,7 @@ export async function historyCommand(opts) {
     const idx = String(i + 1);
     const runId = (entry.run_id || '—').slice(0, 12);
     const status = formatStatus(entry.status);
+    const trigger = getRunTriggerLabel(entry.provenance);
     const phases = String(entry.phases_completed?.length || 0);
     const turns = String(entry.total_turns || 0);
     const cost = entry.total_cost_usd != null
@@ -73,6 +112,7 @@ export async function historyCommand(opts) {
       pad(idx, 4),
       pad(runId, 14),
       pad(status, 11),
+      pad(trigger, 14),
       pad(phases, 8),
       pad(turns, 6),
       pad(cost, 10),

package/src/commands/init.js

@@ -692,6 +692,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
     escalation: null,
     queued_phase_transition: null,
     queued_run_completion: null,
+    last_gate_failure: null,
     phase_gate_status: phaseGateStatus,
     budget_reservations: {},
     budget_status: {

package/src/commands/migrate.js

@@ -218,6 +218,7 @@ export async function migrateCommand(opts) {
     escalation: null,
     queued_phase_transition: null,
     queued_run_completion: null,
+    last_gate_failure: null,
     phase_gate_status: {
       planning_signoff: inferredPhase === 'planning' ? 'pending' : 'passed',
       implementation_complete: inferredPhase === 'qa' ? 'passed' : 'pending',