agentxchain 2.53.0 → 2.55.0

package/bin/agentxchain.js

@@ -407,6 +407,7 @@ program
   .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)')
+  .option('--inherit-context', 'Inherit read-only summary context from the parent run (requires --continue-from or --recover-from)')
   .action(runCommand);
 
 program

package/dashboard/components/run-history.js

@@ -68,6 +68,14 @@ function truncateId(id, len = 12) {
   return id.length > len ? id.slice(0, len) + '…' : id;
 }
 
+function isInheritable(entry) {
+  const snap = entry?.inheritance_snapshot;
+  if (!snap) return false;
+  const hasDecisions = Array.isArray(snap.recent_decisions) && snap.recent_decisions.length > 0;
+  const hasTurns = Array.isArray(snap.recent_accepted_turns) && snap.recent_accepted_turns.length > 0;
+  return hasDecisions || hasTurns;
+}
+
 function renderRow(entry, index) {
   const rowClass = entry.status === 'blocked'
     ? ' style="border-left:3px solid var(--yellow)"'
@@ -83,10 +91,15 @@ function renderRow(entry, index) {
     ? `<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>`
     : '';
 
+  const ctxIndicator = isInheritable(entry)
+    ? `<span title="Has inheritance snapshot — usable by child runs" style="color:var(--green)">✓</span>`
+    : `<span style="color:var(--text-dim)">—</span>`;
+
   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>${ctxIndicator}</td>
     <td>${phases}</td>
     <td>${entry.total_turns ?? '—'}</td>
     <td>${formatCost(entry.total_cost_usd)}</td>
@@ -125,6 +138,7 @@ export function render({ runHistory }) {
           <th>#</th>
           <th>Run ID</th>
           <th>Status</th>
+          <th>Ctx</th>
           <th>Phases</th>
           <th>Turns</th>
           <th>Cost</th>

package/package.json

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

package/src/commands/history.js

@@ -7,7 +7,7 @@
 import { resolve } from 'path';
 import { existsSync, readFileSync } from 'fs';
 import chalk from 'chalk';
-import { queryRunHistory, queryRunLineage } from '../lib/run-history.js';
+import { queryRunHistory, queryRunLineage, isInheritable } from '../lib/run-history.js';
 import { getRunTriggerLabel, summarizeRunProvenance } from '../lib/run-provenance.js';
 
 /**
@@ -46,11 +46,12 @@ export async function historyCommand(opts) {
       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 ctxMarker = isInheritable(entry) ? ' [ctx]' : '';
       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})`);
+      console.log(`${prefix}${runId}  ${status}  ${pad(phases, 20)}  ${pad(turns, 10)}  ${pad(cost, 8)}  (${trigger}${parentNote})${ctxMarker}`);
     });
     return;
   }
@@ -63,7 +64,8 @@ export async function historyCommand(opts) {
   });
 
   if (opts.json) {
-    console.log(JSON.stringify(entries, null, 2));
+    const enriched = entries.map(e => ({ ...e, inheritable: isInheritable(e) }));
+    console.log(JSON.stringify(enriched, null, 2));
     return;
   }
 
@@ -81,6 +83,7 @@ export async function historyCommand(opts) {
     pad('Run ID', 14),
     pad('Status', 11),
     pad('Trigger', 14),
+    pad('Ctx', 4),
     pad('Phases', 8),
     pad('Turns', 6),
     pad('Cost', 10),
@@ -96,6 +99,7 @@ export async function historyCommand(opts) {
     const runId = (entry.run_id || '—').slice(0, 12);
     const status = formatStatus(entry.status);
     const trigger = getRunTriggerLabel(entry.provenance);
+    const ctx = isInheritable(entry) ? '✓' : '—';
     const phases = String(entry.phases_completed?.length || 0);
     const turns = String(entry.total_turns || 0);
     const cost = entry.total_cost_usd != null
@@ -113,6 +117,7 @@ export async function historyCommand(opts) {
       pad(runId, 14),
       pad(status, 11),
       pad(trigger, 14),
+      pad(ctx, 4),
       pad(phases, 8),
       pad(turns, 6),
       pad(cost, 10),

package/src/commands/run.js

@@ -33,6 +33,7 @@ import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest } from '../lib/dispatch-manifest.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { resolveGovernedRole } from '../lib/role-resolution.js';
+import { buildInheritedContext } from '../lib/run-context-inheritance.js';
 import {
   getDispatchAssignmentPath,
   getDispatchContextPath,
@@ -91,6 +92,25 @@ export async function executeGovernedRun(context, opts = {}) {
     };
   }
 
+  // ── Inherit-context validation ─────────────────────────────────────────
+  const inheritContext = !!opts.inheritContext;
+  let inheritedContext = null;
+  if (inheritContext) {
+    if (!continueFrom && !recoverFrom) {
+      log(chalk.red('--inherit-context requires --continue-from or --recover-from'));
+      log(chalk.dim('Usage: agentxchain run --continue-from <run_id> --inherit-context'));
+      return { exitCode: 1, result: null };
+    }
+    const parentId = continueFrom || recoverFrom;
+    const inheritance = buildInheritedContext(root, parentId);
+    inheritedContext = inheritance.inherited_context;
+    if (inheritance.warnings?.length) {
+      for (const w of inheritance.warnings) {
+        log(chalk.yellow(`  ⚠ Inheritance: ${w}`));
+      }
+    }
+  }
+
   const maxTurns = opts.maxTurns || 50;
   const autoApprove = !!opts.autoApprove;
   const verbose = !!opts.verbose;
@@ -375,6 +395,7 @@ export async function executeGovernedRun(context, opts = {}) {
     startNewRunFromBlocked: opts.allowBlockedRestart ?? Boolean(provenance),
   };
   if (provenance) runLoopOpts.provenance = provenance;
+  if (inheritedContext) runLoopOpts.inheritedContext = inheritedContext;
   const result = await runLoop(root, config, callbacks, runLoopOpts);
 
   // ── Summary ─────────────────────────────────────────────────────────────

package/src/commands/status.js

@@ -92,6 +92,7 @@ function renderGovernedStatus(context, opts) {
       config,
       state,
       provenance: state?.provenance || null,
+      inherited_context: state?.inherited_context || null,
       continuity,
       connector_health: connectorHealth,
       workflow_kit_artifacts: workflowKitArtifacts,
@@ -113,6 +114,9 @@ function renderGovernedStatus(context, opts) {
   if (provenanceSummary) {
     console.log(`  ${chalk.dim('Origin:')}   ${chalk.magenta(provenanceSummary)}`);
   }
+  if (state?.inherited_context?.parent_run_id) {
+    console.log(`  ${chalk.dim('Inherits:')} ${chalk.magenta(`parent ${state.inherited_context.parent_run_id} (${state.inherited_context.parent_status || 'unknown'})`)}`);
+  }
   if (state?.accepted_integration_ref) {
     console.log(`  ${chalk.dim('Accepted:')} ${state.accepted_integration_ref}`);
   }

package/src/lib/dispatch-bundle.js

@@ -17,6 +17,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { getActiveTurn, getActiveTurns } from './governed-state.js';
+import { renderInheritedContextMarkdown } from './run-context-inheritance.js';
 import {
   DISPATCH_INDEX_PATH,
   getDispatchAssignmentPath,
@@ -511,6 +512,16 @@ function renderContext(state, config, root, turn, role) {
   }
   lines.push('');
 
+  // Inherited context from parent run (when --inherit-context was used)
+  if (state.inherited_context) {
+    // First turn gets the full rendering; subsequent turns get compact
+    const isFirstTurn = !state.last_completed_turn_id;
+    const inheritedMd = renderInheritedContextMarkdown(state.inherited_context, !isFirstTurn);
+    if (inheritedMd) {
+      lines.push(inheritedMd);
+    }
+  }
+
   // Last accepted turn summary
   if (state.last_completed_turn_id) {
     const lastTurn = readLastHistoryEntry(root, warnings);

package/src/lib/export.js

@@ -304,6 +304,7 @@ export function buildRunExport(startDir = process.cwd()) {
         status: state?.status || null,
         phase: state?.phase || null,
         provenance: normalizeRunProvenance(state?.provenance),
+        inherited_context: state?.inherited_context || null,
         active_turn_ids: activeTurns,
         retained_turn_ids: retainedTurns,
         history_entries: countJsonl(files, '.agentxchain/history.jsonl'),

package/src/lib/governed-state.js

@@ -1856,6 +1856,7 @@ export function initializeGovernedRun(root, config, options = {}) {
       remaining_usd: config.budget?.per_run_max_usd ?? null
     },
     provenance,
+    inherited_context: options.inherited_context || null,
   };
 
   writeState(root, updatedState);

package/src/lib/report.js

@@ -641,6 +641,7 @@ function buildRunSubject(artifact) {
       blocked_on: artifact.state?.blocked_on || null,
       blocked_reason: artifact.state?.blocked_reason || null,
       provenance: normalizeRunProvenance(artifact.summary?.provenance || artifact.state?.provenance),
+      inherited_context: artifact.summary?.inherited_context || artifact.state?.inherited_context || null,
       active_turn_count: activeTurns.length,
       retained_turn_count: retainedTurns.length,
       active_turn_ids: activeTurns,
@@ -904,6 +905,9 @@ export function formatGovernanceReportText(report) {
     if (summarizeRunProvenance(run.provenance)) {
       lines.push(`Provenance: ${summarizeRunProvenance(run.provenance)}`);
     }
+    if (run.inherited_context?.parent_run_id) {
+      lines.push(`Inherited from: ${run.inherited_context.parent_run_id} (${run.inherited_context.parent_status || 'unknown'})`);
+    }
 
     lines.push(
       `History entries: ${artifacts.history_entries}`,
@@ -1308,6 +1312,9 @@ export function formatGovernanceReportMarkdown(report) {
     if (summarizeRunProvenance(run.provenance)) {
       lines.push(`- Provenance: \`${summarizeRunProvenance(run.provenance)}\``);
     }
+    if (run.inherited_context?.parent_run_id) {
+      lines.push(`- Inherited from: \`${run.inherited_context.parent_run_id}\` (${run.inherited_context.parent_status || 'unknown'})`);
+    }
 
     lines.push(
       `- History entries: ${artifacts.history_entries}`,

package/src/lib/run-context-inheritance.js

@@ -0,0 +1,161 @@
+/**
+ * Run Context Inheritance — read-only summary bridge from parent to child run.
+ *
+ * When a child run uses `--inherit-context` with `--continue-from` or
+ * `--recover-from`, this module extracts a read-only summary from the
+ * selected parent run-history record and attaches it to the child's
+ * governed state.
+ *
+ * The inherited summary is:
+ *   - read-only (never mutated by the child run)
+ *   - a summary (not a full replay of the parent)
+ *   - observable in status --json, report, export, and CONTEXT.md
+ *
+ * DEC-RUN-CONTEXT-INHERIT-001
+ * Spec: .planning/RUN_CONTEXT_INHERITANCE_SPEC.md
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const RUN_HISTORY_PATH = '.agentxchain/run-history.jsonl';
+
+/**
+ * Build an inherited context summary from a parent run.
+ *
+ * @param {string} root - project root directory
+ * @param {string} parentRunId - the parent run_id
+ * @returns {{ ok: boolean, inherited_context?: object, warnings?: string[] }}
+ */
+export function buildInheritedContext(root, parentRunId) {
+  const warnings = [];
+
+  // 1. Read parent run-history entry
+  const parentEntry = findRunHistoryEntry(root, parentRunId);
+  if (!parentEntry) {
+    warnings.push(`Parent run ${parentRunId} not found in run-history.jsonl`);
+    return {
+      ok: true,
+      inherited_context: buildPartialContext(parentRunId, null, [], [], warnings),
+      warnings,
+    };
+  }
+
+  const snapshot = parentEntry.inheritance_snapshot;
+  const recentDecisions = Array.isArray(snapshot?.recent_decisions) ? snapshot.recent_decisions : [];
+  const acceptedTurns = Array.isArray(snapshot?.recent_accepted_turns) ? snapshot.recent_accepted_turns : [];
+
+  if (!snapshot) {
+    warnings.push('Parent run has no inheritance snapshot in run-history.jsonl — inherited context is metadata only');
+  }
+
+  const inherited_context = {
+    schema_version: '0.1',
+    parent_run_id: parentRunId,
+    parent_status: parentEntry.status,
+    parent_completed_at: parentEntry.completed_at || null,
+    parent_phases_completed: parentEntry.phases_completed || [],
+    parent_roles_used: parentEntry.roles_used || [],
+    parent_blocked_reason: parentEntry.blocked_reason || null,
+    recent_decisions: recentDecisions,
+    recent_accepted_turns: acceptedTurns,
+    inherited_at: new Date().toISOString(),
+    warnings: warnings.length > 0 ? warnings : undefined,
+  };
+
+  return { ok: true, inherited_context, warnings };
+}
+
+/**
+ * Render the inherited context as a markdown section for CONTEXT.md.
+ */
+export function renderInheritedContextMarkdown(inheritedContext, compact = false) {
+  if (!inheritedContext) return '';
+
+  const lines = [];
+  lines.push('## Inherited Run Context');
+  lines.push('');
+  lines.push('> **This is a fresh run, not a resumed parent.** The context below is a read-only summary from the parent run to provide continuity.');
+  lines.push('');
+  lines.push(`- **Parent run:** ${inheritedContext.parent_run_id}`);
+  lines.push(`- **Parent status:** ${inheritedContext.parent_status || 'unknown'}`);
+  if (inheritedContext.parent_completed_at) {
+    lines.push(`- **Completed at:** ${inheritedContext.parent_completed_at}`);
+  }
+  if (inheritedContext.parent_blocked_reason) {
+    lines.push(`- **Blocked reason:** ${inheritedContext.parent_blocked_reason}`);
+  }
+  if (inheritedContext.parent_phases_completed?.length) {
+    lines.push(`- **Phases completed:** ${inheritedContext.parent_phases_completed.join(', ')}`);
+  }
+  if (inheritedContext.parent_roles_used?.length) {
+    lines.push(`- **Roles used:** ${inheritedContext.parent_roles_used.join(', ')}`);
+  }
+  lines.push('');
+
+  if (!compact && inheritedContext.recent_decisions?.length) {
+    lines.push('### Recent Decisions');
+    lines.push('');
+    for (const d of inheritedContext.recent_decisions) {
+      const id = d.id || '(no id)';
+      const stmt = d.statement || '(no statement)';
+      lines.push(`- **${id}:** ${stmt}`);
+    }
+    lines.push('');
+  }
+
+  if (!compact && inheritedContext.recent_accepted_turns?.length) {
+    lines.push('### Recent Accepted Turns');
+    lines.push('');
+    for (const t of inheritedContext.recent_accepted_turns) {
+      const role = t.role || '(unknown)';
+      const summary = t.summary || '(no summary)';
+      lines.push(`- **${role}** (${t.turn_id || '?'}): ${summary}`);
+    }
+    lines.push('');
+  }
+
+  if (inheritedContext.warnings?.length) {
+    lines.push('### Inheritance Warnings');
+    lines.push('');
+    for (const w of inheritedContext.warnings) {
+      lines.push(`- ⚠ ${w}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ── Internal ────────────────────────────────────────────────────────────────
+
+function findRunHistoryEntry(root, runId) {
+  const filePath = join(root, RUN_HISTORY_PATH);
+  if (!existsSync(filePath)) return null;
+  try {
+    const content = readFileSync(filePath, 'utf8').trim();
+    if (!content) return null;
+    const entries = content.split('\n').filter(Boolean).map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+    return entries.find(e => e.run_id === runId) || null;
+  } catch {
+    return null;
+  }
+}
+
+function buildPartialContext(parentRunId, parentEntry, decisions, turns, warnings) {
+  return {
+    schema_version: '0.1',
+    parent_run_id: parentRunId,
+    parent_status: parentEntry?.status || null,
+    parent_completed_at: parentEntry?.completed_at || null,
+    parent_phases_completed: parentEntry?.phases_completed || [],
+    parent_roles_used: parentEntry?.roles_used || [],
+    parent_blocked_reason: parentEntry?.blocked_reason || null,
+    recent_decisions: decisions,
+    recent_accepted_turns: turns,
+    inherited_at: new Date().toISOString(),
+    warnings: warnings.length > 0 ? warnings : undefined,
+  };
+}

package/src/lib/run-history.js

@@ -16,6 +16,8 @@ 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']);
+const MAX_INHERITANCE_DECISIONS = 5;
+const MAX_INHERITANCE_TURNS = 3;
 
 /**
  * Record a run's summary into the persistent run-history ledger.
@@ -81,6 +83,10 @@ export function recordRunHistory(root, state, config, status) {
       connector_used: connectorUsed,
       model_used: modelUsed,
       provenance: normalizeRunProvenance(state?.provenance),
+      inheritance_snapshot: {
+        recent_decisions: buildRecentDecisionSnapshot(ledgerEntries),
+        recent_accepted_turns: buildRecentAcceptedTurnSnapshot(historyEntries),
+      },
       recorded_at: new Date().toISOString(),
     };
 
@@ -243,6 +249,21 @@ export function validateParentRun(root, runId) {
   return { ok: true, entry };
 }
 
+/**
+ * Check whether a run-history entry has a usable inheritance snapshot
+ * (at least one decision or one accepted turn available for child runs).
+ *
+ * @param {object} entry - a run-history record
+ * @returns {boolean}
+ */
+export function isInheritable(entry) {
+  const snap = entry?.inheritance_snapshot;
+  if (!snap) return false;
+  const hasDecisions = Array.isArray(snap.recent_decisions) && snap.recent_decisions.length > 0;
+  const hasTurns = Array.isArray(snap.recent_accepted_turns) && snap.recent_accepted_turns.length > 0;
+  return hasDecisions || hasTurns;
+}
+
 /**
  * Get the path to the run-history file.
  */
@@ -265,3 +286,26 @@ function readJsonlSafe(root, relPath) {
     return [];
   }
 }
+
+function buildRecentDecisionSnapshot(entries) {
+  return entries
+    .slice(-MAX_INHERITANCE_DECISIONS)
+    .map((entry) => ({
+      id: entry.id || entry.decision_id || null,
+      statement: entry.statement || entry.description || entry.text || null,
+      decided_by: entry.decided_by || entry.role || null,
+      phase: entry.phase || null,
+    }));
+}
+
+function buildRecentAcceptedTurnSnapshot(entries) {
+  return entries
+    .filter((entry) => entry.status === 'accepted')
+    .slice(-MAX_INHERITANCE_TURNS)
+    .map((entry) => ({
+      turn_id: entry.turn_id || null,
+      role: entry.role || null,
+      summary: entry.summary || null,
+      phase: entry.phase || null,
+    }));
+}

package/src/lib/run-loop.js

@@ -62,6 +62,9 @@ export async function runLoop(root, config, callbacks, options = {}) {
   const shouldRestartBlocked = state?.status === 'blocked' && options.startNewRunFromBlocked === true;
   if (!state || state.status === 'idle' || shouldRestartCompleted || shouldRestartBlocked) {
     const initOpts = options.provenance ? { provenance: options.provenance } : {};
+    if (options.inheritedContext) {
+      initOpts.inherited_context = options.inheritedContext;
+    }
     if (shouldRestartCompleted || shouldRestartBlocked) {
       initOpts.allow_terminal_restart = true;
     }