agentxchain 2.46.2 → 2.48.0

package/bin/agentxchain.js

@@ -106,6 +106,7 @@ 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';
+import { eventsCommand } from '../src/commands/events.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -262,10 +263,22 @@ 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);
 
+program
+  .command('events')
+  .description('Show repo-local run lifecycle events')
+  .option('-f, --follow', 'Stream events as they occur')
+  .option('-t, --type <type>', 'Filter by event type (comma-separated)')
+  .option('--since <timestamp>', 'Show events after ISO-8601 timestamp')
+  .option('-j, --json', 'Output raw JSONL')
+  .option('-l, --limit <n>', 'Max events to show (default: 50, 0 = all)')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(eventsCommand);
+
 program
   .command('validate')
   .description('Validate project protocol artifacts')
@@ -355,6 +368,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.48.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/events.js

@@ -0,0 +1,150 @@
+/**
+ * agentxchain events — repo-local run event stream reader.
+ *
+ * Reads and optionally follows the `.agentxchain/events.jsonl` log,
+ * giving operators structured visibility into governed run lifecycle
+ * without requiring webhooks or a dashboard.
+ */
+
+import { resolve } from 'path';
+import { existsSync, watchFile, unwatchFile } from 'fs';
+import { readFileSync } from 'fs';
+import chalk from 'chalk';
+import { readRunEvents, RUN_EVENTS_PATH, VALID_RUN_EVENTS } from '../lib/run-events.js';
+
+/**
+ * @param {object} opts
+ * @param {boolean} [opts.follow]  - Stream events as they arrive
+ * @param {string}  [opts.type]    - Comma-separated event types
+ * @param {string}  [opts.since]   - ISO-8601 timestamp filter
+ * @param {boolean} [opts.json]    - Raw JSONL output
+ * @param {number}  [opts.limit]   - Max events to show (default 50)
+ * @param {string}  [opts.dir]     - Project directory
+ */
+export async function eventsCommand(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 != null ? parseInt(opts.limit, 10) : 50;
+  const events = readRunEvents(root, {
+    type: opts.type,
+    since: opts.since,
+    limit: limit === 0 ? undefined : limit,
+  });
+
+  if (opts.json) {
+    for (const evt of events) {
+      console.log(JSON.stringify(evt));
+    }
+  } else {
+    if (events.length === 0 && !opts.follow) {
+      console.log(chalk.dim('No events found.'));
+      if (opts.type) console.log(chalk.dim(`  (filtered by type: ${opts.type})`));
+      return;
+    }
+    for (const evt of events) {
+      printEvent(evt);
+    }
+  }
+
+  if (opts.follow) {
+    return followEvents(root, opts);
+  }
+}
+
+function printEvent(evt) {
+  const ts = evt.timestamp ? new Date(evt.timestamp).toLocaleTimeString() : '—';
+  const type = colorEventType(evt.event_type);
+  const runId = evt.run_id ? evt.run_id.slice(0, 12) : '—';
+  const phase = evt.phase || '—';
+  const turnInfo = evt.turn?.role_id ? ` [${evt.turn.role_id}]` : '';
+  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}`);
+}
+
+function colorEventType(type) {
+  const colors = {
+    run_started: chalk.green,
+    run_completed: chalk.green.bold,
+    run_blocked: chalk.red,
+    turn_dispatched: chalk.blue,
+    turn_accepted: chalk.green,
+    turn_rejected: chalk.yellow,
+    phase_entered: chalk.magenta,
+    escalation_raised: chalk.red.bold,
+    escalation_resolved: chalk.green,
+    gate_pending: chalk.yellow,
+    gate_approved: chalk.green,
+  };
+  const colorFn = colors[type] || chalk.white;
+  return colorFn(pad(type, 22));
+}
+
+function pad(str, len) {
+  return (str || '').padEnd(len);
+}
+
+function followEvents(root, opts) {
+  const filePath = resolve(root, RUN_EVENTS_PATH);
+  let lastSize = 0;
+
+  try {
+    if (existsSync(filePath)) {
+      lastSize = readFileSync(filePath).length;
+    }
+  } catch {}
+
+  console.log(chalk.dim('Watching for events... (Ctrl+C to stop)'));
+
+  return new Promise(() => {
+    const checkForNewEvents = () => {
+      try {
+        if (!existsSync(filePath)) return;
+        const content = readFileSync(filePath, 'utf8');
+        if (content.length <= lastSize) return;
+
+        const newContent = content.slice(lastSize);
+        lastSize = content.length;
+
+        const lines = newContent.split('\n').filter(Boolean);
+        for (const line of lines) {
+          try {
+            const evt = JSON.parse(line);
+            if (opts.type) {
+              const types = new Set(opts.type.split(',').map(t => t.trim()));
+              if (!types.has(evt.event_type)) continue;
+            }
+            if (opts.json) {
+              console.log(JSON.stringify(evt));
+            } else {
+              printEvent(evt);
+            }
+          } catch {}
+        }
+      } catch {}
+    };
+
+    watchFile(filePath, { interval: 200 }, checkForNewEvents);
+
+    process.on('SIGINT', () => {
+      unwatchFile(filePath, checkForNewEvents);
+      process.exit(0);
+    });
+  });
+}
+
+/**
+ * Walk up to find the nearest directory containing agentxchain.json.
+ */
+function findProjectRoot(start) {
+  let dir = resolve(start);
+  while (true) {
+    if (existsSync(resolve(dir, 'agentxchain.json'))) return dir;
+    if (existsSync(resolve(dir, '.agentxchain', 'state.json'))) return dir;
+    const parent = resolve(dir, '..');
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}

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';
 
@@ -30,6 +31,7 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -52,6 +54,7 @@ export const RUN_RESTORE_ROOTS = [
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -296,6 +299,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

@@ -40,8 +40,10 @@ import { getMaxConcurrentTurns } from './normalized-config.js';
 import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir, getReviewArtifactPath } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
 import { emitNotifications } from './notification-runner.js';
+import { emitRunEvent } from './run-events.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
 import { recordRunHistory } from './run-history.js';
+import { buildDefaultRunProvenance } from './run-provenance.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -61,6 +63,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;
@@ -1708,6 +1752,12 @@ export function raiseOperatorEscalation(root, config, details) {
     detail,
     recovery_action: recoveryAction,
   }, targetTurn);
+  emitRunEvent(root, 'escalation_raised', {
+    run_id: blocked.state.run_id,
+    phase: blocked.state.phase,
+    status: 'blocked',
+    payload: { source: 'operator', reason },
+  });
 
   return {
     ok: true,
@@ -1751,6 +1801,12 @@ export function reactivateGovernedRun(root, state, details = {}) {
       resolved_via: details.via || 'unknown',
       previous_escalation: state.escalation || null,
     }, state.escalation?.from_turn_id ? getActiveTurns(state)[state.escalation.from_turn_id] || getActiveTurn(state) : getActiveTurn(state));
+    emitRunEvent(details.root || root, 'escalation_resolved', {
+      run_id: nextState.run_id,
+      phase: nextState.phase,
+      status: nextState.status,
+      payload: { resolved_via: details.via || 'unknown' },
+    });
   }
 
   return { ok: true, state: attachLegacyCurrentTurnAlias(nextState) };
@@ -1766,21 +1822,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,10 +1854,17 @@ export function initializeGovernedRun(root, config) {
     budget_status: {
       spent_usd: 0,
       remaining_usd: config.budget?.per_run_max_usd ?? null
-    }
+    },
+    provenance,
   };
 
   writeState(root, updatedState);
+  emitRunEvent(root, 'run_started', {
+    run_id: runId,
+    phase: updatedState.phase,
+    status: 'active',
+    payload: { provenance: provenance || {} },
+  });
   return { ok: true, state: attachLegacyCurrentTurnAlias(updatedState) };
 }
 
@@ -2001,6 +2070,13 @@ export function assignGovernedTurn(root, config, roleId) {
 
   writeState(root, updatedState);
 
+  emitRunEvent(root, 'turn_dispatched', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: updatedState.status,
+    turn: { turn_id: turnId, role_id: roleId },
+  });
+
   // Session checkpoint — non-fatal, written after every successful turn assignment
   writeSessionCheckpoint(root, updatedState, 'turn_assigned', {
     role: roleId,
@@ -2977,6 +3053,14 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }
   }
 
+  // Emit turn_accepted event to local log.
+  emitRunEvent(root, 'turn_accepted', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: updatedState.status,
+    turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+  });
+
   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
@@ -2987,6 +3071,13 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       blockedOn: updatedState.blocked_on,
       recovery: updatedState.blocked_reason?.recovery || null,
     }, currentTurn);
+    emitRunEvent(root, 'run_blocked', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: 'blocked',
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      payload: { category: updatedState.blocked_reason?.category || 'needs_human' },
+    });
   }
 
   if (updatedState.pending_phase_transition) {
@@ -2996,6 +3087,16 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       gate: updatedState.pending_phase_transition.gate,
       requested_by_turn: updatedState.pending_phase_transition.requested_by_turn,
     }, currentTurn);
+    emitRunEvent(root, 'gate_pending', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      payload: {
+        gate_type: 'phase_transition',
+        from: updatedState.pending_phase_transition.from,
+        to: updatedState.pending_phase_transition.to,
+      },
+    });
   }
 
   if (updatedState.pending_run_completion) {
@@ -3004,6 +3105,12 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       requested_by_turn: updatedState.pending_run_completion.requested_by_turn,
       requested_at: updatedState.pending_run_completion.requested_at,
     }, currentTurn);
+    emitRunEvent(root, 'gate_pending', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      payload: { gate_type: 'run_completion' },
+    });
   }
 
   if (updatedState.status === 'completed') {
@@ -3012,6 +3119,12 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       completed_via: completionResult?.action === 'complete' ? 'accept_turn' : 'accept_turn_direct',
       requested_by_turn: completionResult?.requested_by_turn || turnResult.turn_id,
     }, currentTurn);
+    emitRunEvent(root, 'run_completed', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: 'completed',
+      payload: { completed_at: updatedState.completed_at || now },
+    });
   }
 
   // Session checkpoint — non-fatal, written after every successful acceptance
@@ -3161,6 +3274,13 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
     };
 
     writeState(root, updatedState);
+    emitRunEvent(root, 'turn_rejected', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      payload: { attempt: currentAttempt, retrying: true },
+    });
     return {
       ok: true,
       state: attachLegacyCurrentTurnAlias(updatedState),
@@ -3221,6 +3341,19 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
     blockedOn: updatedState.blocked_on,
     recovery: updatedState.blocked_reason?.recovery || null,
   }, updatedState.active_turns[currentTurn.turn_id]);
+  emitRunEvent(root, 'turn_rejected', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'blocked',
+    turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+    payload: { attempt: currentAttempt, retrying: false, escalated: true },
+  });
+  emitRunEvent(root, 'run_blocked', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'blocked',
+    payload: { category: 'retries_exhausted' },
+  });
 
   // Fire on_escalation hooks (advisory-only) after blocked state is persisted.
   const hooksConfig = config?.hooks || {};
@@ -3332,6 +3465,18 @@ export function approvePhaseTransition(root, config) {
   };
 
   writeState(root, updatedState);
+  emitRunEvent(root, 'gate_approved', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'active',
+    payload: { gate_type: 'phase_transition', from: transition.from, to: transition.to },
+  });
+  emitRunEvent(root, 'phase_entered', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'active',
+    payload: { from: transition.from },
+  });
 
   // Session checkpoint — non-fatal
   writeSessionCheckpoint(root, updatedState, 'phase_approved');
@@ -3434,6 +3579,18 @@ export function approveRunCompletion(root, config) {
     gate: completion.gate,
     requested_by_turn: completion.requested_by_turn || null,
   }, completion.requested_by_turn ? getActiveTurns(state)[completion.requested_by_turn] || null : null);
+  emitRunEvent(root, 'gate_approved', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'completed',
+    payload: { gate_type: 'run_completion' },
+  });
+  emitRunEvent(root, 'run_completed', {
+    run_id: updatedState.run_id,
+    phase: updatedState.phase,
+    status: 'completed',
+    payload: { completed_at: updatedState.completed_at },
+  });
 
   // Session checkpoint — non-fatal
   writeSessionCheckpoint(root, updatedState, 'run_completed');

package/src/lib/repo-observer.js

@@ -41,6 +41,8 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/run-history.jsonl',
+  '.agentxchain/events.jsonl',
+  '.agentxchain/notification-audit.jsonl',
   'TALK.md',
 ];
 

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-events.js

@@ -0,0 +1,117 @@
+/**
+ * run-events.js — Repo-local structured event log for governed runs.
+ *
+ * Appends lifecycle events to `.agentxchain/events.jsonl` so operators
+ * can observe run progress without webhooks or dashboard.
+ */
+
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export const RUN_EVENTS_PATH = '.agentxchain/events.jsonl';
+
+export const VALID_RUN_EVENTS = [
+  'run_started',
+  'phase_entered',
+  'turn_dispatched',
+  'turn_accepted',
+  'turn_rejected',
+  'run_blocked',
+  'run_completed',
+  'escalation_raised',
+  'escalation_resolved',
+  'gate_pending',
+  'gate_approved',
+];
+
+/**
+ * Emit a structured lifecycle event to the local event log.
+ *
+ * @param {string} root        - Project root directory
+ * @param {string} eventType   - One of VALID_RUN_EVENTS
+ * @param {object} details     - Event details
+ * @param {string} [details.run_id]  - Current run ID
+ * @param {string} [details.phase]   - Current phase
+ * @param {string} [details.status]  - Current run status
+ * @param {object} [details.turn]    - Turn context (turn_id, role_id, etc.)
+ * @param {object} [details.payload] - Additional event-specific data
+ * @returns {{ ok: boolean, event_id: string }}
+ */
+export function emitRunEvent(root, eventType, details = {}) {
+  const event_id = `evt_${randomBytes(8).toString('hex')}`;
+  const entry = {
+    event_id,
+    event_type: eventType,
+    timestamp: new Date().toISOString(),
+    run_id: details.run_id || null,
+    phase: details.phase || null,
+    status: details.status || null,
+    turn: details.turn || null,
+    payload: details.payload || {},
+  };
+
+  try {
+    const filePath = join(root, RUN_EVENTS_PATH);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    appendFileSync(filePath, `${JSON.stringify(entry)}\n`);
+    return { ok: true, event_id };
+  } catch (err) {
+    // Best-effort — never interrupt governed operations for event logging.
+    if (process.env.AGENTXCHAIN_DEBUG) {
+      process.stderr.write(`[run-events] write failed: ${err.message}\n`);
+    }
+    return { ok: false, event_id };
+  }
+}
+
+/**
+ * Read events from the local event log.
+ *
+ * @param {string} root      - Project root directory
+ * @param {object} [opts]    - Filter options
+ * @param {string} [opts.type]   - Comma-separated event types to include
+ * @param {string} [opts.since]  - ISO-8601 timestamp; only events after this
+ * @param {number} [opts.limit]  - Max events to return (from end of file)
+ * @returns {object[]}
+ */
+export function readRunEvents(root, opts = {}) {
+  const filePath = join(root, RUN_EVENTS_PATH);
+  if (!existsSync(filePath)) return [];
+
+  const raw = readFileSync(filePath, 'utf8');
+  const lines = raw.split('\n').filter(Boolean);
+
+  let events = [];
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // Skip malformed lines.
+    }
+  }
+
+  // Apply type filter.
+  if (opts.type) {
+    const types = new Set(opts.type.split(',').map(t => t.trim()));
+    events = events.filter(e => types.has(e.event_type));
+  }
+
+  // Apply since filter.
+  if (opts.since) {
+    const sinceMs = new Date(opts.since).getTime();
+    if (!Number.isNaN(sinceMs)) {
+      events = events.filter(e => new Date(e.timestamp).getTime() > sinceMs);
+    }
+  }
+
+  // Apply limit (from end).
+  if (opts.limit && opts.limit > 0 && events.length > opts.limit) {
+    events = events.slice(-opts.limit);
+  }
+
+  return events;
+}

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}`;
+}