agentxchain 2.82.0 → 2.84.0

package/package.json

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

package/scripts/model-compatibility-probe.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * Model Compatibility Probe — api_proxy + proposed write authority
+ *
+ * Dispatches a lightweight governed turn to each target model and records
+ * whether the model can produce a well-formed turn result with proposed_changes.
+ *
+ * Usage:
+ *   node cli/scripts/model-compatibility-probe.mjs
+ *   node cli/scripts/model-compatibility-probe.mjs --json
+ *
+ * Requires ANTHROPIC_API_KEY in the environment.
+ */
+
+const ANTHROPIC_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+
+const SYSTEM_PROMPT = [
+  'You are acting as a governed agent in an AgentXchain protocol run.',
+  'Your task and rules are described in the user message.',
+  'You MUST respond with a valid JSON object matching the turn result schema provided in the prompt.',
+  'Do NOT wrap the JSON in markdown code fences. Respond with raw JSON only.',
+].join('\n');
+
+const PROBE_PROMPT = `You are a governed agent with write_authority: "proposed".
+
+Your task: create a single file called \`probe-result.txt\` containing the text "model compatibility probe passed".
+
+Respond with a single raw JSON object (no markdown fences) matching this exact schema:
+
+{
+  "schema_version": "1.0",
+  "run_id": "probe_run",
+  "turn_id": "probe_turn_001",
+  "role": "dev",
+  "runtime_id": "probe_runtime",
+  "status": "completed",
+  "summary": "Created probe-result.txt for model compatibility verification.",
+  "decisions": [],
+  "objections": [],
+  "files_changed": ["probe-result.txt"],
+  "verification": { "status": "pass", "evidence": "File created successfully." },
+  "artifact": { "type": "patch", "ref": null },
+  "proposed_next_role": "human",
+  "proposed_changes": [
+    {
+      "path": "probe-result.txt",
+      "action": "create",
+      "content": "model compatibility probe passed"
+    }
+  ]
+}
+
+Return ONLY the JSON object. No explanation, no markdown fences, no extra text.`;
+
+const MODELS = [
+  { id: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5', maxTokens: 2048, costInput: 1.00, costOutput: 5.00 },
+  { id: 'claude-sonnet-4-6', label: 'Sonnet 4.6', maxTokens: 2048, costInput: 3.00, costOutput: 15.00 },
+];
+
+function extractTurnResult(text) {
+  if (typeof text !== 'string' || !text.trim()) {
+    return { ok: false, error: 'Empty response text' };
+  }
+  const trimmed = text.trim();
+
+  // Direct JSON parse
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+      return { ok: true, turnResult: parsed, method: 'direct' };
+    }
+  } catch { /* not pure JSON */ }
+
+  // Markdown fence extraction
+  const fenceMatch = trimmed.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+  if (fenceMatch) {
+    try {
+      const parsed = JSON.parse(fenceMatch[1].trim());
+      if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+        return { ok: true, turnResult: parsed, method: 'fence' };
+      }
+    } catch { /* invalid JSON inside fence */ }
+  }
+
+  // Substring extraction
+  const jsonStart = trimmed.indexOf('{');
+  const jsonEnd = trimmed.lastIndexOf('}');
+  if (jsonStart >= 0 && jsonEnd > jsonStart) {
+    try {
+      const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd + 1));
+      if (parsed && typeof parsed === 'object' && parsed.schema_version) {
+        return { ok: true, turnResult: parsed, method: 'substring' };
+      }
+    } catch { /* not valid JSON */ }
+  }
+
+  return { ok: false, error: 'Could not extract structured turn result JSON' };
+}
+
+function validateProposedChanges(turnResult) {
+  const changes = turnResult?.proposed_changes;
+  if (!Array.isArray(changes) || changes.length === 0) {
+    return { present: false, wellFormed: false, reason: 'proposed_changes missing or empty' };
+  }
+  for (const c of changes) {
+    if (!c.path || typeof c.path !== 'string') {
+      return { present: true, wellFormed: false, reason: `entry missing path` };
+    }
+    if (!['create', 'modify', 'delete'].includes(c.action)) {
+      return { present: true, wellFormed: false, reason: `invalid action: ${c.action}` };
+    }
+    if ((c.action === 'create' || c.action === 'modify') && (!c.content || typeof c.content !== 'string')) {
+      return { present: true, wellFormed: false, reason: `${c.action} entry missing content for ${c.path}` };
+    }
+  }
+  return { present: true, wellFormed: true, count: changes.length };
+}
+
+async function probeModel(model, apiKey) {
+  const startMs = Date.now();
+  const body = {
+    model: model.id,
+    max_tokens: model.maxTokens,
+    system: SYSTEM_PROMPT,
+    messages: [{ role: 'user', content: PROBE_PROMPT }],
+  };
+
+  let responseData;
+  let rawError = null;
+
+  try {
+    const res = await fetch(ANTHROPIC_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const errorBody = await res.text().catch(() => '');
+      rawError = `HTTP ${res.status}: ${errorBody.slice(0, 500)}`;
+      return {
+        model: model.id,
+        label: model.label,
+        extraction_success: false,
+        schema_valid: false,
+        proposed_changes_present: false,
+        proposed_changes_well_formed: false,
+        latency_ms: Date.now() - startMs,
+        cost_usd: 0,
+        classification: 'unsupported',
+        raw_error: rawError,
+      };
+    }
+
+    responseData = await res.json();
+  } catch (err) {
+    return {
+      model: model.id,
+      label: model.label,
+      extraction_success: false,
+      schema_valid: false,
+      proposed_changes_present: false,
+      proposed_changes_well_formed: false,
+      latency_ms: Date.now() - startMs,
+      cost_usd: 0,
+      classification: 'unsupported',
+      raw_error: err.message,
+    };
+  }
+
+  const latencyMs = Date.now() - startMs;
+
+  // Extract text from Anthropic response
+  const textBlock = responseData?.content?.find(b => b.type === 'text');
+  const responseText = textBlock?.text || '';
+
+  // Extract turn result
+  const extraction = extractTurnResult(responseText);
+
+  // Calculate cost
+  const usage = responseData?.usage || {};
+  const inputTokens = usage.input_tokens || 0;
+  const outputTokens = usage.output_tokens || 0;
+  const costUsd = (inputTokens / 1_000_000) * model.costInput + (outputTokens / 1_000_000) * model.costOutput;
+
+  if (!extraction.ok) {
+    return {
+      model: model.id,
+      label: model.label,
+      extraction_success: false,
+      extraction_method: null,
+      schema_valid: false,
+      proposed_changes_present: false,
+      proposed_changes_well_formed: false,
+      latency_ms: latencyMs,
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      cost_usd: Math.round(costUsd * 1_000_000) / 1_000_000,
+      classification: 'unsupported',
+      raw_error: extraction.error,
+      response_preview: responseText.slice(0, 300),
+    };
+  }
+
+  const tr = extraction.turnResult;
+  const schemaValid = typeof tr.schema_version === 'string' && tr.schema_version === '1.0';
+  const pcValidation = validateProposedChanges(tr);
+
+  let classification;
+  if (schemaValid && pcValidation.present && pcValidation.wellFormed) {
+    classification = 'reliable';
+  } else if (extraction.ok && (!pcValidation.present || !pcValidation.wellFormed)) {
+    classification = 'inconsistent';
+  } else {
+    classification = 'unsupported';
+  }
+
+  return {
+    model: model.id,
+    label: model.label,
+    extraction_success: true,
+    extraction_method: extraction.method,
+    schema_valid: schemaValid,
+    proposed_changes_present: pcValidation.present,
+    proposed_changes_well_formed: pcValidation.wellFormed,
+    proposed_changes_count: pcValidation.count || 0,
+    latency_ms: latencyMs,
+    input_tokens: inputTokens,
+    output_tokens: outputTokens,
+    cost_usd: Math.round(costUsd * 1_000_000) / 1_000_000,
+    classification,
+    raw_error: pcValidation.reason || null,
+    status_returned: tr.status,
+    summary_returned: typeof tr.summary === 'string' ? tr.summary.slice(0, 100) : null,
+  };
+}
+
+async function main() {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    console.error('ANTHROPIC_API_KEY not set');
+    process.exit(1);
+  }
+
+  const jsonMode = process.argv.includes('--json');
+
+  if (!jsonMode) {
+    console.log('AgentXchain Model Compatibility Probe');
+    console.log('Provider: Anthropic | Write Authority: proposed');
+    console.log('─'.repeat(60));
+  }
+
+  const results = [];
+
+  for (const model of MODELS) {
+    if (!jsonMode) {
+      process.stdout.write(`Probing ${model.label} (${model.id})... `);
+    }
+
+    const result = await probeModel(model, apiKey);
+    results.push(result);
+
+    if (!jsonMode) {
+      const icon = result.classification === 'reliable' ? '✓' : result.classification === 'inconsistent' ? '~' : '✗';
+      console.log(`${icon} ${result.classification} (${result.latency_ms}ms, $${result.cost_usd})`);
+      if (result.raw_error) {
+        console.log(`  └─ ${result.raw_error}`);
+      }
+    }
+  }
+
+  const output = {
+    probe_version: '1.0',
+    timestamp: new Date().toISOString(),
+    provider: 'anthropic',
+    write_authority: 'proposed',
+    models: results,
+    total_cost_usd: results.reduce((s, r) => s + r.cost_usd, 0),
+  };
+
+  if (jsonMode) {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    console.log('─'.repeat(60));
+    console.log(`Total cost: $${output.total_cost_usd.toFixed(6)}`);
+    console.log();
+    console.log('Matrix:');
+    for (const r of results) {
+      console.log(`  ${r.label.padEnd(12)} ${r.classification.padEnd(14)} extraction=${r.extraction_success} schema=${r.schema_valid} proposed=${r.proposed_changes_well_formed}`);
+    }
+  }
+
+  // Write results to .planning/ for durable reference
+  const { writeFileSync, mkdirSync } = await import('node:fs');
+  const { dirname, join } = await import('node:path');
+  const { fileURLToPath } = await import('node:url');
+  const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+  const outPath = join(repoRoot, '.planning', 'MODEL_COMPATIBILITY_RESULTS.json');
+  writeFileSync(outPath, JSON.stringify(output, null, 2) + '\n');
+  if (!jsonMode) {
+    console.log(`\nResults written to: .planning/MODEL_COMPATIBILITY_RESULTS.json`);
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/release-bump.sh

@@ -62,7 +62,6 @@ ALLOWED_RELEASE_PATHS=(
   "website-v2/docs/protocol-implementor-guide.mdx"
   ".planning/LAUNCH_EVIDENCE_REPORT.md"
   "website-v2/static/llms.txt"
-  "website-v2/static/sitemap.xml"
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"
 )
@@ -148,9 +147,9 @@ if [[ ! -f "${REPO_ROOT}/${RELEASE_DOC_PATH}" ]]; then
   SURFACE_ERRORS+=("release notes page missing: ${RELEASE_DOC_PATH}")
 fi
 
-# 4c. Docs sidebar links the release page
-if ! grep -q "'releases/${RELEASE_DOC_ID}'" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
-  SURFACE_ERRORS+=("sidebars.ts does not link 'releases/${RELEASE_DOC_ID}'")
+# 4c. Docs sidebar auto-generates releases from dirName (release doc existence is sufficient)
+if ! grep -q "dirName.*releases" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
+  SURFACE_ERRORS+=("sidebars.ts does not auto-generate releases (missing dirName: 'releases')")
 fi
 
 # 4d. Homepage hero badge shows target version
@@ -181,10 +180,7 @@ if ! grep -q "${CURRENT_RELEASE_ROUTE}" "${REPO_ROOT}/website-v2/static/llms.txt
   SURFACE_ERRORS+=("website-v2/static/llms.txt does not list '${CURRENT_RELEASE_ROUTE}'")
 fi
 
-# 4i. sitemap.xml must list the current release notes route
-if ! grep -q "${CURRENT_RELEASE_ROUTE}" "${REPO_ROOT}/website-v2/static/sitemap.xml" 2>/dev/null; then
-  SURFACE_ERRORS+=("website-v2/static/sitemap.xml does not list '${CURRENT_RELEASE_ROUTE}'")
-fi
+# 4i. sitemap.xml is now auto-generated by Docusaurus at build time — no static file check needed
 
 if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "FAIL: ${#SURFACE_ERRORS[@]} version-surface(s) not aligned to ${TARGET_VERSION}:" >&2
@@ -194,7 +190,7 @@ if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
   echo "create release identity when governed surfaces are stale." >&2
   exit 1
 fi
-echo "  OK: all 9 governed version surfaces reference ${TARGET_VERSION}"
+echo "  OK: all 8 governed version surfaces reference ${TARGET_VERSION}"
 
 # 5. Auto-align Homebrew mirror to target version
 # The formula URL and README version/tarball are updated automatically.

package/src/commands/config.js

@@ -219,6 +219,12 @@ function setSetting(config, configPath, keyValPair, context) {
   console.log('');
   console.log(chalk.green(`  ✓ Set ${chalk.bold(key)} = ${val}`));
   if (oldVal !== undefined) console.log(chalk.dim(`    (was: ${oldVal})`));
+  if ((validation.warnings || []).length > 0) {
+    console.log(chalk.yellow('  Warnings:'));
+    for (const warning of validation.warnings) {
+      console.log(chalk.dim(`    - ${warning}`));
+    }
+  }
   console.log('');
 }
 

package/src/commands/doctor.js

@@ -51,8 +51,11 @@ function governedDoctor(root, rawConfig, opts) {
 
   // 1. Config validation
   const configResult = loadNormalizedConfig(rawConfig, root);
-  if (configResult.ok) {
+  if (configResult.ok && (configResult.warnings || []).length === 0) {
     checks.push({ id: 'config_valid', name: 'Config validation', level: 'pass', detail: 'Config loads and validates' });
+  } else if (configResult.ok) {
+    const warningSummary = configResult.warnings.slice(0, 2).join('; ');
+    checks.push({ id: 'config_valid', name: 'Config validation', level: 'warn', detail: warningSummary });
   } else {
     const errorSummary = configResult.errors.slice(0, 3).join('; ');
     checks.push({ id: 'config_valid', name: 'Config validation', level: 'fail', detail: errorSummary });

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),
       })),
   };
 

package/src/lib/normalized-config.js

@@ -330,9 +330,10 @@ export function detectConfigVersion(raw) {
  */
 export function validateV4Config(data, projectRoot) {
   const errors = [];
+  const warnings = [];
 
   if (!data || typeof data !== 'object') {
-    return { ok: false, errors: ['Config must be a JSON object'] };
+    return { ok: false, errors: ['Config must be a JSON object'], warnings };
   }
 
   // Top-level required sections
@@ -555,7 +556,80 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...timeoutValidation.errors);
   }
 
-  return { ok: errors.length === 0, errors };
+  warnings.push(...collectRemoteReviewOnlyGateWarnings(data));
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+export function collectRemoteReviewOnlyGateWarnings(data) {
+  const warnings = [];
+  const routing = data?.routing;
+  const gates = data?.gates;
+  const roles = data?.roles;
+  const runtimes = data?.runtimes;
+
+  if (!routing || !gates || !roles || !runtimes) {
+    return warnings;
+  }
+
+  for (const [phase, route] of Object.entries(routing)) {
+    const exitGateId = route?.exit_gate;
+    if (!exitGateId || !gates[exitGateId]) {
+      continue;
+    }
+
+    const requiredFiles = Array.isArray(gates[exitGateId]?.requires_files)
+      ? gates[exitGateId].requires_files.filter(filePath => typeof filePath === 'string' && filePath.trim())
+      : [];
+    if (requiredFiles.length === 0) {
+      continue;
+    }
+
+    const candidateRoleIds = [
+      route?.entry_role,
+      ...(Array.isArray(route?.allowed_next_roles) ? route.allowed_next_roles : []),
+    ].filter((roleId) => roleId && roleId !== 'human');
+
+    if (candidateRoleIds.length === 0) {
+      continue;
+    }
+
+    const candidateRoles = [...new Set(candidateRoleIds)]
+      .map((roleId) => {
+        const role = roles[roleId];
+        const runtime = role?.runtime ? runtimes[role.runtime] : null;
+        if (!role || !runtime) {
+          return null;
+        }
+        return { roleId, role, runtime };
+      })
+      .filter(Boolean);
+
+    if (candidateRoles.length === 0) {
+      continue;
+    }
+
+    const hasFileProducingRole = candidateRoles.some(({ role }) =>
+      role.write_authority === 'authoritative' || role.write_authority === 'proposed');
+    if (hasFileProducingRole) {
+      continue;
+    }
+
+    const allRemoteReviewOnly = candidateRoles.every(({ role, runtime }) =>
+      role.write_authority === 'review_only' && (runtime.type === 'api_proxy' || runtime.type === 'remote_agent'));
+    if (!allRemoteReviewOnly) {
+      continue;
+    }
+
+    const roleSummary = candidateRoles
+      .map(({ roleId, runtime }) => `${roleId}:${runtime.type}`)
+      .join(', ');
+    warnings.push(
+      `Routing "${phase}" exits through gate "${exitGateId}" with requires_files (${requiredFiles.join(', ')}) but all participating roles are review_only remote runtimes (${roleSummary}). Those files cannot be produced through governed turns; add a proposed/authoritative writer, remove the gate files, or expect operator-managed out-of-band artifacts.`,
+    );
+  }
+
+  return warnings;
 }
 
 export function validateBudgetConfig(budget) {
@@ -1133,6 +1207,7 @@ export function loadNormalizedConfig(raw, projectRoot) {
       ok: false,
       normalized: null,
       errors: ['Unrecognized config format. Expected version: 3 or schema_version: "1.0" / 4'],
+      warnings: [],
       version: null,
     };
   }
@@ -1152,17 +1227,17 @@ export function loadNormalizedConfig(raw, projectRoot) {
       }
     }
     if (errors.length > 0) {
-      return { ok: false, normalized: null, errors, version: 3 };
+      return { ok: false, normalized: null, errors, warnings: [], version: 3 };
     }
-    return { ok: true, normalized: normalizeV3(raw), errors: [], version: 3 };
+    return { ok: true, normalized: normalizeV3(raw), errors: [], warnings: [], version: 3 };
   }
 
   if (version === 4) {
     const validation = validateV4Config(raw, projectRoot || null);
     if (!validation.ok) {
-      return { ok: false, normalized: null, errors: validation.errors, version: 4 };
+      return { ok: false, normalized: null, errors: validation.errors, warnings: validation.warnings || [], version: 4 };
     }
-    return { ok: true, normalized: normalizeV4(raw), errors: [], version: 4 };
+    return { ok: true, normalized: normalizeV4(raw), errors: [], warnings: validation.warnings || [], version: 4 };
   }
 }
 

package/src/lib/validation.js

@@ -9,6 +9,7 @@ import {
   validateAcceptanceHintCompletion,
   validateGovernedWorkflowKit,
 } from './governed-templates.js';
+import { collectRemoteReviewOnlyGateWarnings } from './normalized-config.js';
 
 const DEFAULT_REQUIRED_FILES = [
   '.planning/PROJECT.md',
@@ -115,6 +116,9 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
   errors.push(...workflowKit.errors);
   warnings.push(...workflowKit.warnings);
 
+  // Config-shape warnings (dead-end gates, etc.) — mirrors doctor/config --set surfaces
+  warnings.push(...collectRemoteReviewOnlyGateWarnings(rawConfig));
+
   const mustExist = [
     config.files?.state || '.agentxchain/state.json',
     config.files?.history || '.agentxchain/history.jsonl',