agentxchain 2.46.2 → 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/package.json

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

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/run.js

@@ -20,6 +20,7 @@ import { loadProjectContext, loadProjectState } from '../lib/config.js';
 import { runLoop } from '../lib/run-loop.js';
 import { buildRunExport } from '../lib/export.js';
 import { buildGovernanceReport, formatGovernanceReportMarkdown } from '../lib/report.js';
+import { validateParentRun } from '../lib/run-history.js';
 import { dispatchApiProxy } from '../lib/adapters/api-proxy-adapter.js';
 import {
   dispatchLocalCli,
@@ -56,6 +57,30 @@ export async function runCommand(opts) {
     process.exit(1);
   }
 
+  // ── Provenance flag validation ──────────────────────────────────────────
+  const continueFrom = opts.continueFrom;
+  const recoverFrom = opts.recoverFrom;
+
+  if (continueFrom && recoverFrom) {
+    console.log(chalk.red('Cannot specify both --continue-from and --recover-from'));
+    process.exit(1);
+  }
+
+  let provenance = undefined;
+  if (continueFrom || recoverFrom) {
+    const parentId = continueFrom || recoverFrom;
+    const validation = validateParentRun(root, parentId);
+    if (!validation.ok) {
+      console.log(chalk.red(validation.error));
+      process.exit(1);
+    }
+    provenance = {
+      trigger: continueFrom ? 'continuation' : 'recovery',
+      parent_run_id: parentId,
+      created_by: 'operator',
+    };
+  }
+
   const maxTurns = opts.maxTurns || 50;
   const autoApprove = !!opts.autoApprove;
   const verbose = !!opts.verbose;
@@ -319,7 +344,13 @@ export async function runCommand(opts) {
   };
 
   // ── Execute ─────────────────────────────────────────────────────────────
-  const result = await runLoop(root, config, callbacks, { maxTurns });
+  const runLoopOpts = {
+    maxTurns,
+    startNewRunFromCompleted: true,
+    startNewRunFromBlocked: Boolean(provenance),
+  };
+  if (provenance) runLoopOpts.provenance = provenance;
+  const result = await runLoop(root, config, callbacks, runLoopOpts);
 
   // ── Summary ─────────────────────────────────────────────────────────────
   console.log('');

package/src/commands/status.js

@@ -6,6 +6,7 @@ import { getContinuityStatus } from '../lib/continuity-status.js';
 import { getConnectorHealth } from '../lib/connector-health.js';
 import { deriveWorkflowKitArtifacts } from '../lib/workflow-kit-artifacts.js';
 import { evaluateTimeouts } from '../lib/timeout-evaluator.js';
+import { summarizeRunProvenance } from '../lib/run-provenance.js';
 
 export async function statusCommand(opts) {
   const context = loadProjectContext();
@@ -90,6 +91,7 @@ function renderGovernedStatus(context, opts) {
       template: config.template || 'generic',
       config,
       state,
+      provenance: state?.provenance || null,
       continuity,
       connector_health: connectorHealth,
       workflow_kit_artifacts: workflowKitArtifacts,
@@ -107,6 +109,10 @@ function renderGovernedStatus(context, opts) {
   console.log(`  ${chalk.dim('Template:')} ${config.template || 'generic'}`);
   console.log(`  ${chalk.dim('Phase:')}    ${state?.phase ? formatGovernedPhase(state.phase) : chalk.dim('unknown')}`);
   console.log(`  ${chalk.dim('Run:')}      ${formatRunStatus(state?.status)}`);
+  const provenanceSummary = summarizeRunProvenance(state?.provenance);
+  if (provenanceSummary) {
+    console.log(`  ${chalk.dim('Origin:')}   ${chalk.magenta(provenanceSummary)}`);
+  }
   if (state?.accepted_integration_ref) {
     console.log(`  ${chalk.dim('Accepted:')} ${state.accepted_integration_ref}`);
   }

package/src/lib/export.js

@@ -6,6 +6,7 @@ import { join, relative, resolve } from 'node:path';
 import { loadProjectContext, loadProjectState } from './config.js';
 import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-config.js';
 import { loadCoordinatorState } from './coordinator-state.js';
+import { normalizeRunProvenance } from './run-provenance.js';
 
 const EXPORT_SCHEMA_VERSION = '0.3';
 
@@ -296,6 +297,7 @@ export function buildRunExport(startDir = process.cwd()) {
         run_id: state?.run_id || null,
         status: state?.status || null,
         phase: state?.phase || null,
+        provenance: normalizeRunProvenance(state?.provenance),
         active_turn_ids: activeTurns,
         retained_turn_ids: retainedTurns,
         history_entries: countJsonl(files, '.agentxchain/history.jsonl'),

package/src/lib/governed-state.js

@@ -42,6 +42,7 @@ import { runHooks } from './hook-runner.js';
 import { emitNotifications } from './notification-runner.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
 import { recordRunHistory } from './run-history.js';
+import { buildDefaultRunProvenance } from './run-provenance.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -61,6 +62,48 @@ function generateId(prefix) {
   return `${prefix}_${randomBytes(8).toString('hex')}`;
 }
 
+function getInitialPhase(config) {
+  return Object.keys(config?.routing || {})[0] || 'planning';
+}
+
+function buildInitialPhaseGateStatus(config) {
+  return Object.fromEntries(
+    [...new Set(
+      Object.values(config?.routing || {})
+        .map((route) => route?.exit_gate)
+        .filter(Boolean)
+    )].map((gateId) => [gateId, 'pending'])
+  );
+}
+
+function buildFreshIdleStateForNewRun(state, config) {
+  return {
+    schema_version: state?.schema_version || GOVERNED_SCHEMA_VERSION,
+    run_id: null,
+    project_id: state?.project_id || config?.project?.id || null,
+    status: 'idle',
+    phase: getInitialPhase(config),
+    accepted_integration_ref: null,
+    active_turns: {},
+    turn_sequence: 0,
+    last_completed_turn_id: null,
+    blocked_on: null,
+    blocked_reason: null,
+    escalation: null,
+    pending_phase_transition: null,
+    pending_run_completion: null,
+    queued_phase_transition: null,
+    queued_run_completion: null,
+    last_gate_failure: null,
+    phase_gate_status: buildInitialPhaseGateStatus(config),
+    budget_reservations: {},
+    budget_status: {
+      spent_usd: 0,
+      remaining_usd: config?.budget?.per_run_max_usd ?? null,
+    },
+  };
+}
+
 function normalizeGateFailure(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     return null;
@@ -1766,21 +1809,27 @@ export function reactivateGovernedRun(root, state, details = {}) {
  * @param {object} config - normalized config
  * @returns {{ ok: boolean, error?: string, state?: object }}
  */
-export function initializeGovernedRun(root, config) {
-  const state = readState(root);
+export function initializeGovernedRun(root, config, options = {}) {
+  let state = readState(root);
   if (!state) {
     return { ok: false, error: 'No governed state.json found' };
   }
-  if (state.status === 'completed') {
+  const allowTerminalRestart = options.allow_terminal_restart === true
+    && (state.status === 'completed' || state.status === 'blocked');
+  if (state.status === 'completed' && !allowTerminalRestart) {
     return { ok: false, error: 'Cannot initialize run: this run is already completed. Start a new project or reset state.' };
   }
   const allowBlockedBootstrap = state.status === 'blocked' && state.run_id === null && getActiveTurnCount(state) === 0;
-  if (state.status !== 'idle' && state.status !== 'paused' && !allowBlockedBootstrap) {
+  if (state.status !== 'idle' && state.status !== 'paused' && !allowBlockedBootstrap && !allowTerminalRestart) {
     return { ok: false, error: `Cannot initialize run: status is "${state.status}", expected "idle", "paused", or pre-run "blocked"` };
   }
+  if (allowTerminalRestart) {
+    state = buildFreshIdleStateForNewRun(state, config);
+  }
 
   const runId = generateId('run');
   const now = new Date().toISOString();
+  const provenance = buildDefaultRunProvenance(options.provenance);
   const updatedState = {
     ...state,
     run_id: runId,
@@ -1792,7 +1841,8 @@ export function initializeGovernedRun(root, config) {
     budget_status: {
       spent_usd: 0,
       remaining_usd: config.budget?.per_run_max_usd ?? null
-    }
+    },
+    provenance,
   };
 
   writeState(root, updatedState);

package/src/lib/report.js

@@ -1,4 +1,5 @@
 import { verifyExportArtifact } from './export-verifier.js';
+import { normalizeRunProvenance, summarizeRunProvenance } from './run-provenance.js';
 
 export const GOVERNANCE_REPORT_VERSION = '0.1';
 
@@ -639,6 +640,7 @@ function buildRunSubject(artifact) {
       phase: artifact.summary?.phase || null,
       blocked_on: artifact.state?.blocked_on || null,
       blocked_reason: artifact.state?.blocked_reason || null,
+      provenance: normalizeRunProvenance(artifact.summary?.provenance || artifact.state?.provenance),
       active_turn_count: activeTurns.length,
       retained_turn_count: retainedTurns.length,
       active_turn_ids: activeTurns,
@@ -899,6 +901,9 @@ export function formatGovernanceReportText(report) {
     if (run.duration_seconds != null) {
       lines.push(`Duration: ${run.duration_seconds}s`);
     }
+    if (summarizeRunProvenance(run.provenance)) {
+      lines.push(`Provenance: ${summarizeRunProvenance(run.provenance)}`);
+    }
 
     lines.push(
       `History entries: ${artifacts.history_entries}`,
@@ -1300,6 +1305,9 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.duration_seconds != null) {
       lines.push(`- Duration: \`${run.duration_seconds}s\``);
     }
+    if (summarizeRunProvenance(run.provenance)) {
+      lines.push(`- Provenance: \`${summarizeRunProvenance(run.provenance)}\``);
+    }
 
     lines.push(
       `- History entries: ${artifacts.history_entries}`,

package/src/lib/run-history.js

@@ -9,6 +9,7 @@
 
 import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
+import { normalizeRunProvenance } from './run-provenance.js';
 
 const RUN_HISTORY_PATH = '.agentxchain/run-history.jsonl';
 const HISTORY_PATH = '.agentxchain/history.jsonl';
@@ -79,6 +80,7 @@ export function recordRunHistory(root, state, config, status) {
       gate_results: state?.phase_gate_status || {},
       connector_used: connectorUsed,
       model_used: modelUsed,
+      provenance: normalizeRunProvenance(state?.provenance),
       recorded_at: new Date().toISOString(),
     };
 
@@ -132,6 +134,115 @@ export function queryRunHistory(root, opts = {}) {
   return entries;
 }
 
+/**
+ * Walk run lineage backwards from a given run_id via parent_run_id links.
+ *
+ * Returns an ordered array (oldest ancestor first) of history entries
+ * forming the lineage chain. If a parent_run_id references a run not
+ * found in history, the chain terminates with a broken_link sentinel.
+ *
+ * @param {string} root - project root directory
+ * @param {string} runId - the run to trace lineage for
+ * @returns {{ ok: boolean, chain?: Array<object>, error?: string }}
+ */
+export function queryRunLineage(root, runId) {
+  const filePath = join(root, RUN_HISTORY_PATH);
+  if (!existsSync(filePath)) {
+    return { ok: false, error: 'No run history found. Run at least one governed run first.' };
+  }
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return { ok: false, error: 'Failed to read run history file.' };
+  }
+  if (!content) {
+    return { ok: false, error: 'No run history found. Run at least one governed run first.' };
+  }
+
+  const entries = content
+    .split('\n')
+    .filter(Boolean)
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+
+  // Build lookup by run_id
+  const byId = new Map();
+  for (const entry of entries) {
+    if (entry.run_id) byId.set(entry.run_id, entry);
+  }
+
+  // Find the target entry
+  const target = byId.get(runId);
+  if (!target) {
+    return { ok: false, error: `Run ${runId} not found in run history.` };
+  }
+
+  // Walk backwards collecting ancestors
+  const chain = [target];
+  let current = target;
+  const visited = new Set([runId]);
+
+  while (current.provenance?.parent_run_id) {
+    const parentId = current.provenance.parent_run_id;
+    if (visited.has(parentId)) break; // safety: prevent cycles
+    visited.add(parentId);
+
+    const parent = byId.get(parentId);
+    if (!parent) {
+      chain.unshift({ broken_link: true, missing_run_id: parentId });
+      break;
+    }
+    chain.unshift(parent);
+    current = parent;
+  }
+
+  return { ok: true, chain };
+}
+
+/**
+ * Validate that a run_id exists in history and is in a terminal state.
+ * Used by --continue-from and --recover-from flag validation.
+ *
+ * @param {string} root - project root directory
+ * @param {string} runId - the run_id to validate
+ * @returns {{ ok: boolean, entry?: object, error?: string }}
+ */
+export function validateParentRun(root, runId) {
+  const filePath = join(root, RUN_HISTORY_PATH);
+  if (!existsSync(filePath)) {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+
+  let content;
+  try {
+    content = readFileSync(filePath, 'utf8').trim();
+  } catch {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+  if (!content) {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+
+  const entries = content
+    .split('\n')
+    .filter(Boolean)
+    .map(line => { try { return JSON.parse(line); } catch { return null; } })
+    .filter(Boolean);
+
+  const entry = entries.find(e => e.run_id === runId);
+  if (!entry) {
+    return { ok: false, error: `Run ${runId} not found in run history` };
+  }
+
+  if (!WRITABLE_TERMINAL_STATUSES.has(entry.status)) {
+    return { ok: false, error: `Run ${runId} is still active (status: ${entry.status}). Cannot chain from a non-terminal run.` };
+  }
+
+  return { ok: true, entry };
+}
+
 /**
  * Get the path to the run-history file.
  */

package/src/lib/run-loop.js

@@ -38,7 +38,7 @@ const DEFAULT_MAX_TURNS = 50;
  * @param {string} root - project root directory
  * @param {object} config - normalized governed config
  * @param {object} callbacks - { selectRole, dispatch, approveGate, onEvent? }
- * @param {object} [options] - { maxTurns?: number }
+ * @param {object} [options] - { maxTurns?: number, provenance?: object, startNewRunFromCompleted?: boolean, startNewRunFromBlocked?: boolean }
  * @returns {Promise<RunLoopResult>}
  */
 export async function runLoop(root, config, callbacks, options = {}) {
@@ -58,8 +58,14 @@ export async function runLoop(root, config, callbacks, options = {}) {
 
   // ── Initialize if idle ──────────────────────────────────────────────────
   let state = loadState(root, config);
-  if (!state || state.status === 'idle') {
-    const initResult = initRun(root, config);
+  const shouldRestartCompleted = state?.status === 'completed' && options.startNewRunFromCompleted === true;
+  const shouldRestartBlocked = state?.status === 'blocked' && options.startNewRunFromBlocked === true;
+  if (!state || state.status === 'idle' || shouldRestartCompleted || shouldRestartBlocked) {
+    const initOpts = options.provenance ? { provenance: options.provenance } : {};
+    if (shouldRestartCompleted || shouldRestartBlocked) {
+      initOpts.allow_terminal_restart = true;
+    }
+    const initResult = initRun(root, config, initOpts);
     if (!initResult.ok) {
       return makeResult(false, 'init_failed', loadState(root, config), turnsExecuted, turnHistory, gatesApproved, [initResult.error]);
     }

package/src/lib/run-provenance.js

@@ -0,0 +1,90 @@
+const VALID_TRIGGERS = new Set([
+  'manual',
+  'continuation',
+  'recovery',
+  'intake',
+  'schedule',
+  'coordinator',
+]);
+
+const VALID_CREATORS = new Set([
+  'operator',
+  'coordinator',
+]);
+
+function normalizeString(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+export function normalizeRunProvenance(value, { fallbackManual = false } = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return fallbackManual ? buildDefaultRunProvenance() : null;
+  }
+
+  const trigger = normalizeString(value.trigger);
+  const createdBy = normalizeString(value.created_by);
+  const normalized = {
+    trigger: VALID_TRIGGERS.has(trigger) ? trigger : (fallbackManual ? 'manual' : null),
+    parent_run_id: normalizeString(value.parent_run_id),
+    trigger_reason: normalizeString(value.trigger_reason),
+    intake_intent_id: normalizeString(value.intake_intent_id),
+    created_by: VALID_CREATORS.has(createdBy) ? createdBy : 'operator',
+  };
+
+  if (!normalized.trigger) {
+    return fallbackManual ? buildDefaultRunProvenance() : null;
+  }
+
+  return normalized;
+}
+
+export function buildDefaultRunProvenance(overrides = {}) {
+  return normalizeRunProvenance({
+    trigger: 'manual',
+    parent_run_id: null,
+    trigger_reason: null,
+    intake_intent_id: null,
+    created_by: 'operator',
+    ...overrides,
+  }, { fallbackManual: true });
+}
+
+export function getRunTriggerLabel(provenance) {
+  const normalized = normalizeRunProvenance(provenance);
+  return normalized?.trigger || 'legacy';
+}
+
+export function summarizeRunProvenance(provenance) {
+  const normalized = normalizeRunProvenance(provenance);
+  if (!normalized) return null;
+
+  const details = [];
+  if (normalized.parent_run_id) {
+    details.push(`from ${normalized.parent_run_id}`);
+  }
+  if (normalized.intake_intent_id) {
+    details.push(`intent ${normalized.intake_intent_id}`);
+  }
+
+  const base = details.length > 0
+    ? `${normalized.trigger} ${details.join(' ')}`
+    : normalized.trigger;
+  const creatorSuffix = normalized.created_by === 'coordinator'
+    ? ' (created by coordinator)'
+    : '';
+  const reasonSuffix = normalized.trigger_reason
+    ? ` ("${normalized.trigger_reason}")`
+    : '';
+
+  if (
+    normalized.trigger === 'manual'
+    && !normalized.parent_run_id
+    && !normalized.intake_intent_id
+    && !normalized.trigger_reason
+    && normalized.created_by !== 'coordinator'
+  ) {
+    return null;
+  }
+
+  return `${base}${creatorSuffix}${reasonSuffix}`;
+}