agentxchain 2.43.0 → 2.45.0

package/README.md

@@ -24,7 +24,7 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 See governance before you scaffold a real repo:
 
 ```bash
-npx agentxchain demo
+npx --yes -p agentxchain@latest -c "agentxchain demo"
 ```
 
 Requires Node.js 18.17+ or 20.5+ and `git`. The demo creates a temporary governed repo, runs a full PM -> Dev -> QA lifecycle through the real runner interface, shows gates/decisions/objections, and removes the temp workspace when finished. No API keys, config edits, or manual turn authoring required.
@@ -33,12 +33,13 @@ Requires Node.js 18.17+ or 20.5+ and `git`. The demo creates a temporary governe
 
 ```bash
 npm install -g agentxchain
+agentxchain --version
 ```
 
-Or run without installing:
+For a zero-install one-off command, use the package-bound form:
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project -y
+npx --yes -p agentxchain@latest -c "agentxchain demo"
 ```
 
 ## Testing
@@ -62,7 +63,7 @@ Duplicate execution remains intentional for the current 36-file slice until a la
 ### Governed workflow
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project -y
+agentxchain init --governed --dir my-agentxchain-project -y
 cd my-agentxchain-project
 git init
 git add -A
@@ -74,13 +75,13 @@ agentxchain step --role pm
 The default governed dev runtime is `claude --print --dangerously-skip-permissions` with stdin prompt delivery. The non-interactive governed path needs write access, so do not pretend bare `claude --print` is sufficient for unattended implementation turns. If your local coding agent uses a different launch contract, set it during scaffold creation:
 
 ```bash
-npx agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
+agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
 ```
 
 If you want template-specific planning artifacts from day one:
 
 ```bash
-npx agentxchain init --governed --template api-service --dir my-agentxchain-project -y
+agentxchain init --governed --template api-service --dir my-agentxchain-project -y
 ```
 
 Built-in governed templates:
@@ -119,8 +120,8 @@ Default governed scaffolding configures QA as `api_proxy` with `ANTHROPIC_API_KE
 For initiatives spanning multiple governed repos, use the coordinator to add cross-repo sequencing and shared gates:
 
 ```bash
-npx agentxchain init --governed --template api-service --dir repos/backend -y
-npx agentxchain init --governed --template web-app --dir repos/frontend -y
+agentxchain init --governed --template api-service --dir repos/backend -y
+agentxchain init --governed --template web-app --dir repos/frontend -y
 agentxchain multi init
 agentxchain multi step --json
 ```

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.45.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/adapters/api-proxy-adapter.js

@@ -23,7 +23,7 @@
  *   All error returns include a `classified` ApiProxyError object with
  *   error_class, recovery instructions, and retryable flag.
  *
- * Supported providers: "anthropic", "openai", "google"
+ * Supported providers: "anthropic", "openai", "google", "ollama"
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from 'fs';
@@ -51,6 +51,7 @@ const PROVIDER_ENDPOINTS = {
   anthropic: 'https://api.anthropic.com/v1/messages',
   openai: 'https://api.openai.com/v1/chat/completions',
   google: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent',
+  ollama: 'http://localhost:11434/v1/chat/completions',
 };
 
 // Bundled cost rates per million tokens (USD).
@@ -161,6 +162,22 @@ const PROVIDER_ERROR_MAPS = {
       { provider_error_type: 'INTERNAL', http_status: 500, error_class: 'unknown_api_error', retryable: true },
     ],
   },
+  // Ollama uses OpenAI-compatible error structure
+  ollama: {
+    extractErrorType(body) {
+      return typeof body?.error?.type === 'string' ? body.error.type : null;
+    },
+    extractErrorCode(body) {
+      return typeof body?.error?.code === 'string' ? body.error.code : null;
+    },
+    mappings: [
+      { provider_error_code: 'invalid_api_key', http_status: 401, error_class: 'auth_failure', retryable: false },
+      { provider_error_code: 'model_not_found', http_status: 404, error_class: 'model_not_found', retryable: false },
+      { provider_error_type: 'invalid_request_error', http_status: 400, body_pattern: /context|token.*limit|too.many.tokens/i, error_class: 'context_overflow', retryable: false },
+      { provider_error_type: 'invalid_request_error', http_status: 400, error_class: 'invalid_request', retryable: false },
+      { provider_error_type: 'rate_limit_error', http_status: 429, error_class: 'rate_limited', retryable: true },
+    ],
+  },
 };
 
 // ── Error classification ──────────────────────────────────────────────────────
@@ -465,7 +482,7 @@ function usageFromTelemetry(provider, model, usage, config) {
   let inputTokens = 0;
   let outputTokens = 0;
 
-  if (provider === 'openai') {
+  if (provider === 'openai' || provider === 'ollama') {
     inputTokens = Number.isFinite(usage.prompt_tokens) ? usage.prompt_tokens : 0;
     outputTokens = Number.isFinite(usage.completion_tokens) ? usage.completion_tokens : 0;
   } else if (provider === 'google') {
@@ -811,9 +828,10 @@ export async function dispatchApiProxy(root, state, config, options = {}) {
   const provider = runtime.provider;
   const model = runtime.model;
   const authEnv = runtime.auth_env;
-  const apiKey = process.env[authEnv];
+  const apiKey = authEnv ? process.env[authEnv] : null;
 
-  if (!apiKey) {
+  // Auth is required for cloud providers, optional for local providers (ollama)
+  if (!apiKey && authEnv) {
     const classified = classifyError(
       'missing_credentials',
       `Environment variable "${authEnv}" is not set — required for api_proxy`,
@@ -1124,6 +1142,15 @@ function buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens) {
   };
 }
 
+function buildOllamaRequest(promptMd, contextMd, model, maxOutputTokens) {
+  const openAiCompatible = buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens);
+  return {
+    ...openAiCompatible,
+    max_tokens: maxOutputTokens,
+    max_completion_tokens: undefined,
+  };
+}
+
 function buildGoogleHeaders(_apiKey) {
   // Google Gemini uses API key as a query parameter, not a header
   return {
@@ -1203,6 +1230,14 @@ function extractGoogleTurnResult(responseData) {
   return extraction;
 }
 
+function buildOllamaHeaders(apiKey) {
+  const headers = { 'Content-Type': 'application/json' };
+  if (apiKey) {
+    headers['Authorization'] = `Bearer ${apiKey}`;
+  }
+  return headers;
+}
+
 function buildProviderHeaders(provider, apiKey) {
   if (provider === 'openai') {
     return buildOpenAiHeaders(apiKey);
@@ -1210,6 +1245,9 @@ function buildProviderHeaders(provider, apiKey) {
   if (provider === 'google') {
     return buildGoogleHeaders(apiKey);
   }
+  if (provider === 'ollama') {
+    return buildOllamaHeaders(apiKey);
+  }
   return buildAnthropicHeaders(apiKey);
 }
 
@@ -1217,6 +1255,9 @@ function buildProviderRequest(provider, promptMd, contextMd, model, maxOutputTok
   if (provider === 'openai') {
     return buildOpenAiRequest(promptMd, contextMd, model, maxOutputTokens);
   }
+  if (provider === 'ollama') {
+    return buildOllamaRequest(promptMd, contextMd, model, maxOutputTokens);
+  }
   if (provider === 'google') {
     return buildGoogleRequest(promptMd, contextMd, model, maxOutputTokens);
   }
@@ -1304,7 +1345,7 @@ function extractOpenAiTurnResult(responseData) {
 }
 
 function extractTurnResult(responseData, provider = 'anthropic') {
-  if (provider === 'openai') {
+  if (provider === 'openai' || provider === 'ollama') {
     return extractOpenAiTurnResult(responseData);
   }
   if (provider === 'google') {
@@ -1324,10 +1365,17 @@ export {
   extractTurnResult,
   buildAnthropicRequest,
   buildOpenAiRequest,
+  buildOllamaRequest,
   buildGoogleRequest,
+  buildOllamaHeaders,
+  buildProviderHeaders,
+  buildProviderRequest,
   classifyError,
   classifyHttpError,
+  DEFAULT_RETRY_POLICY,
   BUNDLED_COST_RATES,
   BUNDLED_COST_RATES as COST_RATES, // backward compat alias
   getCostRates,
+  PROVIDER_ENDPOINTS,
+  RETRYABLE_ERROR_CLASSES,
 };

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/normalized-config.js

@@ -24,7 +24,8 @@ import {
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
 const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp', 'remote_agent'];
-const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai', 'google'];
+export const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai', 'google', 'ollama'];
+const AUTH_OPTIONAL_PROVIDERS = ['ollama'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
 const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
@@ -388,7 +389,9 @@ export function validateV4Config(data, projectRoot) {
           errors.push(`Runtime "${id}": api_proxy requires "model" (e.g. "claude-sonnet-4-6")`);
         }
         if (typeof rt.auth_env !== 'string' || !rt.auth_env.trim()) {
-          errors.push(`Runtime "${id}": api_proxy requires "auth_env" (environment variable name for API key)`);
+          if (!AUTH_OPTIONAL_PROVIDERS.includes(rt.provider)) {
+            errors.push(`Runtime "${id}": api_proxy requires "auth_env" (environment variable name for API key)`);
+          }
         }
         if ('base_url' in rt) {
           if (typeof rt.base_url !== 'string' || !rt.base_url.trim()) {

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');