agentxchain 2.82.0 → 2.83.0

package/package.json

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

package/src/commands/intake-status.js

@@ -19,7 +19,7 @@ export async function intakeStatusCommand(opts) {
 
   // Detail mode: single intent
   if (result.intent) {
-    printIntentDetail(result.intent, result.event);
+    printIntentDetail(result.intent, result.event, result.next_action);
     process.exit(0);
   }
 
@@ -46,14 +46,17 @@ function printSummary(summary) {
       const pri = i.priority ? i.priority.padEnd(3) : '---';
       const tpl = (i.template || '---').padEnd(12);
       const st = statusColor(i.status);
-      console.log(`  ${chalk.dim(i.intent_id)}  ${pri}  ${tpl}  ${st}  ${chalk.dim(i.updated_at)}`);
+      const actionHint = i.next_action?.action_required && i.next_action?.label !== 'none'
+        ? `  ${chalk.dim(`→ ${i.next_action.label}`)}`
+        : '';
+      console.log(`  ${chalk.dim(i.intent_id)}  ${pri}  ${tpl}  ${st}  ${chalk.dim(i.updated_at)}${actionHint}`);
     }
   }
 
   console.log('');
 }
 
-function printIntentDetail(intent, event) {
+function printIntentDetail(intent, event, nextAction) {
   console.log('');
   console.log(chalk.bold(`  Intent: ${intent.intent_id}`));
   console.log(chalk.dim('  ' + '─'.repeat(44)));
@@ -93,6 +96,21 @@ function printIntentDetail(intent, event) {
     console.log(`    ${chalk.dim('Signal:')}  ${JSON.stringify(event.signal)}`);
   }
 
+  if (nextAction) {
+    console.log('');
+    console.log(chalk.dim('  Next Action:'));
+    console.log(`    ${nextAction.summary}`);
+    if (nextAction.command) {
+      console.log(`    ${chalk.dim('Command:')}  ${nextAction.command}`);
+    }
+    for (const alternative of nextAction.alternatives || []) {
+      console.log(`    ${chalk.dim('Alternative:')} ${alternative}`);
+    }
+    if (nextAction.recovery) {
+      console.log(`    ${chalk.dim('Recovery:')} ${nextAction.recovery}`);
+    }
+  }
+
   console.log('');
 }
 

package/src/commands/restart.js

@@ -167,7 +167,7 @@ export async function restartCommand(opts) {
   // Load state
   const statePath = join(root, STATE_PATH);
   if (!existsSync(statePath)) {
-    console.log(chalk.red('No governed run found. Use `agentxchain resume` or `agentxchain run` to start.'));
+    console.log(chalk.red('No governed run found. Use `agentxchain run` to start a governed run.'));
     process.exit(1);
   }
 

package/src/commands/resume.js

@@ -38,6 +38,7 @@ import {
 } from '../lib/turn-paths.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { runHooks } from '../lib/hook-runner.js';
+import { summarizeRunProvenance } from '../lib/run-provenance.js';
 
 export async function resumeCommand(opts) {
   const context = loadProjectContext();
@@ -128,6 +129,7 @@ export async function resumeCommand(opts) {
 
     const turnStatus = retainedTurn.status;
     if (turnStatus === 'failed' || turnStatus === 'retrying') {
+      printResumeRunContext({ root, state, config });
       console.log(chalk.yellow(`Re-dispatching failed turn: ${retainedTurn.turn_id}`));
       console.log(`  Role:    ${retainedTurn.assigned_role}`);
       console.log(`  Attempt: ${retainedTurn.attempt}`);
@@ -187,6 +189,7 @@ export async function resumeCommand(opts) {
       process.exit(1);
     }
 
+    printResumeRunContext({ root, state, config });
     console.log(chalk.yellow(`Re-dispatching blocked turn: ${retainedTurn.turn_id}`));
     console.log(`  Role:    ${retainedTurn.assigned_role}`);
     console.log(`  Attempt: ${retainedTurn.attempt}`);
@@ -251,6 +254,9 @@ export async function resumeCommand(opts) {
     console.log(chalk.green(`Resumed governed run: ${state.run_id}`));
   }
 
+  // Print run-context header before dispatch
+  printResumeRunContext({ root, state, config });
+
   // Resolve target role
   const roleId = resolveTargetRole(opts, state, config);
   if (!roleId) {
@@ -302,6 +308,53 @@ export async function resumeCommand(opts) {
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
+function printResumeRunContext({ root, state, config }) {
+  console.log('');
+  console.log(chalk.cyan.bold('agentxchain resume'));
+  console.log(`  ${chalk.dim('Run:')}      ${state?.run_id || '(uninitialized)'}`);
+  console.log(`  ${chalk.dim('Phase:')}    ${state?.phase || '(unknown)'}`);
+
+  const provenanceSummary = summarizeRunProvenance(state?.provenance);
+  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'})`
+      )}`
+    );
+  }
+
+  const activeGate = config?.routing?.[state?.phase]?.exit_gate || null;
+  if (activeGate) {
+    const gateStatus = state?.phase_gate_status?.[activeGate] || 'pending';
+    console.log(`  ${chalk.dim('Gate:')}     ${activeGate} (${gateStatus})`);
+
+    if (gateStatus !== 'passed') {
+      const gateDef = config?.gates?.[activeGate];
+      if (Array.isArray(gateDef?.requires_files) && gateDef.requires_files.length > 0) {
+        const fileChecks = gateDef.requires_files.map((filePath) => {
+          const exists = existsSync(join(root, filePath));
+          const shortPath = filePath.replace(/^\.planning\//, '');
+          return exists ? chalk.green(shortPath) : chalk.red(shortPath);
+        });
+        console.log(`  ${chalk.dim('Files:')}    ${fileChecks.join(chalk.dim(', '))}`);
+      }
+
+      const requirements = [];
+      if (gateDef?.requires_human_approval) requirements.push('human approval');
+      if (gateDef?.requires_verification_pass) requirements.push('verification pass');
+      if (requirements.length > 0) {
+        console.log(`  ${chalk.dim('Needs:')}    ${requirements.join(', ')}`);
+      }
+    }
+  }
+
+  console.log('');
+}
+
 function resolveTargetRole(opts, state, config) {
   const phase = state.phase;
   const routing = config.routing?.[phase];

package/src/commands/run.js

@@ -32,6 +32,7 @@ import { dispatchRemoteAgent, describeRemoteAgentTarget } from '../lib/adapters/
 import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest } from '../lib/dispatch-manifest.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import { resolveGovernedRole } from '../lib/role-resolution.js';
 import { buildInheritedContext } from '../lib/run-context-inheritance.js';
 import {
@@ -179,6 +180,24 @@ export async function executeGovernedRun(context, opts = {}) {
   // ── Run header ──────────────────────────────────────────────────────────
   log(chalk.cyan.bold('agentxchain run'));
   log(chalk.dim(`  Max turns: ${maxTurns}  Gate mode: ${autoApprove ? 'auto-approve' : 'interactive'}`));
+  if (provenance) {
+    const provenanceSummary = summarizeRunProvenance(provenance);
+    if (provenanceSummary) {
+      log(`  ${chalk.dim('Origin:')}    ${chalk.magenta(provenanceSummary)}`);
+    }
+  }
+  if (inheritedContext) {
+    const ic = inheritedContext;
+    const phasesCount = ic.parent_phases_completed?.length || 0;
+    const decisionsCount = ic.recent_decisions?.length || 0;
+    const turnsCount = ic.recent_accepted_turns?.length || 0;
+    const parts = [];
+    if (phasesCount) parts.push(`${phasesCount} phase${phasesCount !== 1 ? 's' : ''}`);
+    if (decisionsCount) parts.push(`${decisionsCount} decision${decisionsCount !== 1 ? 's' : ''}`);
+    if (turnsCount) parts.push(`${turnsCount} turn${turnsCount !== 1 ? 's' : ''}`);
+    const detail = parts.length ? ` — ${parts.join(', ')}` : '';
+    log(`  ${chalk.dim('Inherits:')} ${chalk.magenta(`parent ${ic.parent_run_id} (${ic.parent_status || 'unknown'})${detail}`)}`);
+  }
   log('');
 
   // ── Track first-call for --role override ────────────────────────────────

package/src/commands/status.js

@@ -1,4 +1,6 @@
 import chalk from 'chalk';
+import { existsSync } from 'fs';
+import { join } from 'path';
 import { loadConfig, loadLock, loadProjectContext, loadProjectState, loadState } from '../lib/config.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { getActiveTurn, getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
@@ -267,9 +269,29 @@ function renderGovernedStatus(context, opts) {
   if (state?.phase_gate_status) {
     console.log('');
     console.log(`  ${chalk.dim('Gates:')}`);
+    const activePhase = state.phase;
+    const activeRouting = config.routing?.[activePhase];
+    const activeExitGate = activeRouting?.exit_gate || null;
     for (const [gate, status] of Object.entries(state.phase_gate_status)) {
       const icon = status === 'passed' ? chalk.green('✓') : chalk.dim('○');
       console.log(`    ${icon} ${gate}: ${status}`);
+      if (status !== 'passed' && gate === activeExitGate && config.gates?.[gate]) {
+        const gateDef = config.gates[gate];
+        if (Array.isArray(gateDef.requires_files) && gateDef.requires_files.length > 0) {
+          const fileChecks = gateDef.requires_files.map(f => {
+            const exists = existsSync(join(root, f));
+            const short = f.replace(/^\.planning\//, '');
+            return exists ? chalk.green(short) : chalk.red(short);
+          });
+          console.log(`      ${chalk.dim('Files:')} ${fileChecks.join(chalk.dim(', '))}`);
+        }
+        const reqs = [];
+        if (gateDef.requires_human_approval) reqs.push('human approval');
+        if (gateDef.requires_verification_pass) reqs.push('verification pass');
+        if (reqs.length > 0) {
+          console.log(`      ${chalk.dim('Needs:')} ${reqs.join(', ')}`);
+        }
+      }
     }
   }
 
@@ -425,7 +447,7 @@ function renderWorkflowKitArtifactsSection(wkData) {
 
 function renderLastGateFailure(failure, config) {
   const entryRole = config?.routing?.[failure.phase]?.entry_role || null;
-  const suggestedCommand = entryRole ? `agentxchain assign ${entryRole}` : 'agentxchain assign <role>';
+  const suggestedCommand = entryRole ? `agentxchain step --role ${entryRole}` : 'agentxchain step --role <role>';
   const requestLabel = failure.gate_type === 'run_completion'
     ? 'Run completion'
     : `${failure.from_phase || failure.phase} -> ${failure.to_phase || 'unknown'}`;

package/src/commands/step.js

@@ -51,6 +51,7 @@ import {
 } from '../lib/adapters/local-cli-adapter.js';
 import { describeMcpRuntimeTarget, dispatchMcp, resolveMcpTransport } from '../lib/adapters/mcp-adapter.js';
 import { dispatchRemoteAgent, describeRemoteAgentTarget } from '../lib/adapters/remote-agent-adapter.js';
+import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import {
   getDispatchAssignmentPath,
   getDispatchContextPath,
@@ -326,6 +327,8 @@ export async function stepCommand(opts) {
   const runtimeType = runtime?.type || role?.runtime_class || 'manual';
   const hooksConfig = config.hooks || {};
 
+  printStepRunContext({ root, state, config });
+
   if (bundleWritten && hooksConfig.after_dispatch?.length > 0) {
     const afterDispatchHooks = runHooks(root, hooksConfig, 'after_dispatch', {
       turn_id: turn.turn_id,
@@ -945,6 +948,53 @@ function printRecoverySummary(state, heading) {
   }
 }
 
+function printStepRunContext({ root, state, config }) {
+  console.log('');
+  console.log(chalk.cyan.bold('agentxchain step'));
+  console.log(`  ${chalk.dim('Run:')}      ${state?.run_id || '(uninitialized)'}`);
+  console.log(`  ${chalk.dim('Phase:')}    ${state?.phase || '(unknown)'}`);
+
+  const provenanceSummary = summarizeRunProvenance(state?.provenance);
+  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'})`
+      )}`
+    );
+  }
+
+  const activeGate = config?.routing?.[state?.phase]?.exit_gate || null;
+  if (activeGate) {
+    const gateStatus = state?.phase_gate_status?.[activeGate] || 'pending';
+    console.log(`  ${chalk.dim('Gate:')}     ${activeGate} (${gateStatus})`);
+
+    if (gateStatus !== 'passed') {
+      const gateDef = config?.gates?.[activeGate];
+      if (Array.isArray(gateDef?.requires_files) && gateDef.requires_files.length > 0) {
+        const fileChecks = gateDef.requires_files.map((filePath) => {
+          const exists = existsSync(join(root, filePath));
+          const shortPath = filePath.replace(/^\.planning\//, '');
+          return exists ? chalk.green(shortPath) : chalk.red(shortPath);
+        });
+        console.log(`  ${chalk.dim('Files:')}    ${fileChecks.join(chalk.dim(', '))}`);
+      }
+
+      const requirements = [];
+      if (gateDef?.requires_human_approval) requirements.push('human approval');
+      if (gateDef?.requires_verification_pass) requirements.push('verification pass');
+      if (requirements.length > 0) {
+        console.log(`  ${chalk.dim('Needs:')}    ${requirements.join(', ')}`);
+      }
+    }
+  }
+
+  console.log('');
+}
+
 function printDispatchBundleWarnings(bundleResult) {
   for (const warning of bundleResult.warnings || []) {
     console.log(chalk.yellow(`Dispatch bundle warning: ${warning}`));

package/src/lib/governed-state.js

@@ -1835,7 +1835,7 @@ export function reactivateGovernedRun(root, state, details = {}) {
 export function initializeGovernedRun(root, config, options = {}) {
   let state = readState(root);
   if (!state) {
-    return { ok: false, error: 'No governed state.json found' };
+    state = buildFreshIdleStateForNewRun(null, config);
   }
   const allowTerminalRestart = options.allow_terminal_restart === true
     && (state.status === 'completed' || state.status === 'blocked');

package/src/lib/intake.js

@@ -120,6 +120,122 @@ function readJsonDir(dirPath) {
     .filter(Boolean);
 }
 
+function buildIntakeNextAction(intent) {
+  const intentId = intent?.intent_id || '<intent_id>';
+  const status = intent?.status || 'unknown';
+  const resolveCommand = `agentxchain intake resolve --intent ${intentId}`;
+
+  switch (status) {
+    case 'detected':
+      return {
+        label: 'triage',
+        summary: 'Triage this detected intent so it can enter governed delivery.',
+        command: `agentxchain intake triage --intent ${intentId} --priority <p0-p3> --template <template_id> --charter "<charter>" --acceptance "<criterion>"`,
+        alternatives: [
+          `agentxchain intake triage --intent ${intentId} --suppress --reason "<reason>"`,
+        ],
+        recovery: null,
+        action_required: true,
+      };
+    case 'triaged':
+      return {
+        label: 'approve',
+        summary: 'Approve this triaged intent for planning or reject it explicitly.',
+        command: `agentxchain intake approve --intent ${intentId}`,
+        alternatives: [
+          `agentxchain intake triage --intent ${intentId} --reject --reason "<reason>"`,
+        ],
+        recovery: null,
+        action_required: true,
+      };
+    case 'approved':
+      return {
+        label: 'plan',
+        summary: 'Generate planning artifacts for this approved intent.',
+        command: `agentxchain intake plan --intent ${intentId}`,
+        alternatives: [],
+        recovery: null,
+        action_required: true,
+      };
+    case 'planned':
+      return {
+        label: 'start',
+        summary: 'Start repo-local execution or hand the intent off to a coordinator workstream.',
+        command: `agentxchain intake start --intent ${intentId}`,
+        alternatives: [
+          `agentxchain intake handoff --intent ${intentId} --coordinator-root <path> --workstream <id>`,
+        ],
+        recovery: null,
+        action_required: true,
+      };
+    case 'executing':
+      return {
+        label: 'resolve',
+        summary: intent?.target_workstream
+          ? 'Re-check the coordinator workstream outcome for this intent.'
+          : 'Re-check the governed run outcome for this intent.',
+        command: resolveCommand,
+        alternatives: [],
+        recovery: null,
+        action_required: true,
+      };
+    case 'blocked':
+      return {
+        label: 'recover',
+        summary: 'Resolve the linked run blockage, then re-check intake resolution.',
+        command: resolveCommand,
+        alternatives: [],
+        recovery: intent?.run_blocked_recovery || null,
+        action_required: true,
+      };
+    case 'completed':
+      return {
+        label: 'none',
+        summary: 'No action required. This intent completed successfully.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: false,
+      };
+    case 'suppressed':
+      return {
+        label: 'none',
+        summary: 'No action required. This intent was suppressed.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: false,
+      };
+    case 'rejected':
+      return {
+        label: 'none',
+        summary: 'No action required. This intent was rejected.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: false,
+      };
+    case 'failed':
+      return {
+        label: 'inspect',
+        summary: 'Manual inspection required. This intent is in a reserved failed state.',
+        command: null,
+        alternatives: [],
+        recovery: 'Inspect the linked intent and run artifacts manually before continuing.',
+        action_required: true,
+      };
+    default:
+      return {
+        label: 'inspect',
+        summary: 'Manual inspection required. The intent state is not recognized by the current intake surface.',
+        command: null,
+        alternatives: [],
+        recovery: null,
+        action_required: true,
+      };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------
@@ -329,7 +445,13 @@ export function intakeStatus(root, intentId) {
     const intent = JSON.parse(readFileSync(intentPath, 'utf8'));
     const eventPath = join(dirs.events, `${intent.event_id}.json`);
     const event = existsSync(eventPath) ? JSON.parse(readFileSync(eventPath, 'utf8')) : null;
-    return { ok: true, intent, event, exitCode: 0 };
+    return {
+      ok: true,
+      intent,
+      event,
+      next_action: buildIntakeNextAction(intent),
+      exitCode: 0,
+    };
   }
 
   const events = readJsonDir(dirs.events);
@@ -354,6 +476,7 @@ export function intakeStatus(root, intentId) {
         template: i.template,
         status: i.status,
         updated_at: i.updated_at,
+        next_action: buildIntakeNextAction(i),
       })),
   };