agentxchain 2.61.0 → 2.63.0

package/bin/agentxchain.js

@@ -86,6 +86,8 @@ import {
 } from '../src/commands/plugin.js';
 import { templateSetCommand } from '../src/commands/template-set.js';
 import { templateListCommand } from '../src/commands/template-list.js';
+import { roleCommand } from '../src/commands/role.js';
+import { turnShowCommand } from '../src/commands/turn.js';
 import { templateValidateCommand } from '../src/commands/template-validate.js';
 import {
   multiInitCommand,
@@ -192,6 +194,7 @@ program
   .description('View or edit project configuration')
   .option('--add-agent', 'Add a new agent interactively')
   .option('--remove-agent <id>', 'Remove an agent by ID')
+  .option('--get <path>', 'Read a config value (e.g. --get project.goal)')
   .option('--set <path_and_value...>', 'Set a config value (e.g. --set project.goal "Build a governed CLI")')
   .option('-j, --json', 'Output config as JSON')
   .action(configCommand);
@@ -484,6 +487,33 @@ templateCmd
   .option('-j, --json', 'Output as JSON')
   .action(templateValidateCommand);
 
+const roleCmd = program
+  .command('role')
+  .description('Inspect governed role definitions');
+
+roleCmd
+  .command('list')
+  .description('List all defined roles with title, authority, and runtime')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => roleCommand('list', null, opts));
+
+roleCmd
+  .command('show <role_id>')
+  .description('Show detailed information for a single role')
+  .option('-j, --json', 'Output as JSON')
+  .action((roleId, opts) => roleCommand('show', roleId, opts));
+
+const turnCmd = program
+  .command('turn')
+  .description('Inspect active governed turn dispatch bundles');
+
+turnCmd
+  .command('show [turn_id]')
+  .description('Show a selected active turn and its dispatch artifacts')
+  .option('--artifact <name>', 'Print one artifact: assignment, prompt, context, or manifest')
+  .option('-j, --json', 'Output as JSON')
+  .action(turnShowCommand);
+
 const multiCmd = program
   .command('multi')
   .description('Multi-repo coordinator orchestration');

package/package.json

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

package/scripts/release-bump.sh

@@ -198,21 +198,53 @@ echo "  OK: all 9 governed version surfaces reference ${TARGET_VERSION}"
 
 # 5. Auto-align Homebrew mirror to target version
 # The formula URL and README version/tarball are updated automatically.
-# The SHA256 is carried from the previous version — it is inherently a
+# The SHA256 is carried from the previous committed formula — it is inherently a
 # post-publish artifact (npm registry tarballs are not byte-identical to
-# local npm-pack output). sync-homebrew.sh corrects the SHA after publish.
+# local npm-pack output). Any working-tree SHA edit is overwritten here.
+# sync-homebrew.sh corrects the SHA after publish.
 echo "[5/9] Auto-aligning Homebrew mirror to ${TARGET_VERSION}..."
 HOMEBREW_MIRROR="${REPO_ROOT}/cli/homebrew/agentxchain.rb"
 HOMEBREW_MIRROR_README="${REPO_ROOT}/cli/homebrew/README.md"
 TARBALL_URL="https://registry.npmjs.org/agentxchain/-/agentxchain-${TARGET_VERSION}.tgz"
 HOMEBREW_ALIGNED=false
+COMMITTED_HOMEBREW_SHA=""
+
+extract_formula_sha() {
+  sed -nE 's|^[[:space:]]*sha256 "([a-f0-9]{64})".*|\1|p' "$1" | head -n 1
+}
 
 if [[ -f "$HOMEBREW_MIRROR" ]]; then
+  COMMITTED_FORMULA_TMP="$(mktemp "${TMPDIR:-/tmp}/agentxchain-homebrew-head.XXXXXX")"
+  if ! git -C "$REPO_ROOT" show "HEAD:cli/homebrew/agentxchain.rb" >"$COMMITTED_FORMULA_TMP" 2>/dev/null; then
+    rm -f "$COMMITTED_FORMULA_TMP"
+    echo "FAIL: could not load HEAD:cli/homebrew/agentxchain.rb to carry the pre-publish SHA" >&2
+    exit 1
+  fi
+  COMMITTED_HOMEBREW_SHA="$(extract_formula_sha "$COMMITTED_FORMULA_TMP")"
+  rm -f "$COMMITTED_FORMULA_TMP"
+  if [[ -z "$COMMITTED_HOMEBREW_SHA" ]]; then
+    echo "FAIL: HEAD:cli/homebrew/agentxchain.rb does not contain a parseable sha256" >&2
+    exit 1
+  fi
+
+  WORKTREE_HOMEBREW_SHA="$(extract_formula_sha "$HOMEBREW_MIRROR")"
+  if [[ -z "$WORKTREE_HOMEBREW_SHA" ]]; then
+    echo "FAIL: cli/homebrew/agentxchain.rb does not contain a parseable sha256" >&2
+    exit 1
+  fi
+
   ESCAPED_URL="$(printf '%s' "$TARBALL_URL" | sed 's/[&/\]/\\&/g')"
+  ESCAPED_SHA="$(printf '%s' "$COMMITTED_HOMEBREW_SHA" | sed 's/[&/\]/\\&/g')"
   sed -i.bak -E "s|^([[:space:]]*url \").*(\")|\1${ESCAPED_URL}\2|" "$HOMEBREW_MIRROR"
+  sed -i.bak -E "s|^([[:space:]]*sha256 \").*(\")|\1${ESCAPED_SHA}\2|" "$HOMEBREW_MIRROR"
   rm -f "${HOMEBREW_MIRROR}.bak"
   HOMEBREW_ALIGNED=true
   echo "  OK: formula URL -> ${TARBALL_URL}"
+  if [[ "$WORKTREE_HOMEBREW_SHA" != "$COMMITTED_HOMEBREW_SHA" ]]; then
+    echo "  OK: formula SHA normalized back to committed pre-publish SHA ${COMMITTED_HOMEBREW_SHA}"
+  else
+    echo "  OK: formula SHA carried from committed pre-publish SHA ${COMMITTED_HOMEBREW_SHA}"
+  fi
 fi
 
 if [[ -f "$HOMEBREW_MIRROR_README" ]]; then
@@ -223,7 +255,7 @@ if [[ -f "$HOMEBREW_MIRROR_README" ]]; then
 fi
 
 if $HOMEBREW_ALIGNED; then
-  echo "  Note: SHA carried from previous version; sync-homebrew.sh will set the real registry SHA post-publish"
+  echo "  Note: local npm pack output is not canonical release truth; sync-homebrew.sh will set the real registry SHA post-publish"
 else
   echo "  Skipped: no Homebrew mirror files found"
 fi
@@ -346,4 +378,7 @@ if [[ "$SKIP_PREFLIGHT" -eq 1 ]]; then
   echo "  npm run preflight:release:strict -- --target-version ${TARGET_VERSION}"
 fi
 echo ""
+echo "Homebrew mirror is in Phase 1 (stale SHA from previous version)."
+echo "After npm publish completes, run sync-homebrew.sh to reach Phase 3."
+echo ""
 echo "Next: git push origin main --follow-tags"

package/src/commands/accept-turn.js

@@ -166,6 +166,9 @@ export async function acceptTurnCommand(opts = {}) {
   if (accepted?.cost?.usd != null) {
     console.log(`  ${chalk.dim('Cost:')}     $${formatUsd(accepted.cost.usd)}`);
   }
+  if (result.budget_warning) {
+    console.log(`  ${chalk.yellow('Budget warning:')} ${result.budget_warning}`);
+  }
   console.log('');
 
   const recovery = deriveRecoveryDescriptor(result.state);

package/src/commands/config.js

@@ -17,6 +17,12 @@ export async function configCommand(opts) {
   const config = rawConfig;
   const configPath = join(root, CONFIG_FILE);
 
+  if (opts.get && opts.set) {
+    console.log(chalk.red('  --get and --set are mutually exclusive.'));
+    console.log(chalk.dim('  Inspect a value with `agentxchain config --get <path>` or change it with `agentxchain config --set <path> <value>`.'));
+    process.exit(1);
+  }
+
   if (version === 4 && opts.addAgent) {
     printLegacyOnlyMutationError('--add-agent');
     return;
@@ -37,6 +43,11 @@ export async function configCommand(opts) {
     return;
   }
 
+  if (opts.get) {
+    getSetting(config, opts.get, { json: opts.json });
+    return;
+  }
+
   if (opts.set) {
     setSetting(config, configPath, opts.set, { version, root });
     return;
@@ -81,6 +92,7 @@ function printLegacyConfig(config) {
   console.log(chalk.dim('  Commands:'));
   console.log(`    ${chalk.bold('agentxchain config --add-agent')}        Add a new agent`);
   console.log(`    ${chalk.bold('agentxchain config --remove-agent <id>')} Remove an agent`);
+  console.log(`    ${chalk.bold('agentxchain config --get <key>')}         Read one config value`);
   console.log(`    ${chalk.bold('agentxchain config --set <key> <val>')}   Update a setting`);
   console.log(`    ${chalk.bold('agentxchain config --json')}              Output as JSON`);
   console.log('');
@@ -99,6 +111,7 @@ function printGovernedConfig(config) {
   console.log(`  ${chalk.dim('Runtimes:')}  ${Object.keys(config.runtimes || {}).length}`);
   console.log('');
   console.log(chalk.dim('  Commands:'));
+  console.log(`    ${chalk.bold('agentxchain config --get project.goal')}              Read one config value without opening JSON`);
   console.log(`    ${chalk.bold('agentxchain config --set project.goal "Build a ..."')}  Set mission context without hand-editing JSON`);
   console.log(`    ${chalk.bold('agentxchain config --set roles.qa.runtime manual-qa')}  Switch a governed role runtime`);
   console.log(`    ${chalk.bold('agentxchain config --json')}                             Output raw config`);
@@ -169,10 +182,8 @@ function setSetting(config, configPath, keyValPair, context) {
   }
 
   const { key, rawVal } = parsed;
-  const segments = key.split('.');
-  const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
-
-  if (segments.some(segment => forbiddenKeys.has(segment))) {
+  const segments = parseKeyPath(key);
+  if (!segments) {
     console.log(chalk.red('  Refusing to write reserved object path.'));
     process.exit(1);
   }
@@ -211,6 +222,35 @@ function setSetting(config, configPath, keyValPair, context) {
   console.log('');
 }
 
+function getSetting(config, key, opts = {}) {
+  const segments = parseKeyPath(key);
+  if (!segments) {
+    console.log(chalk.red('  Refusing to read reserved object path.'));
+    process.exit(1);
+  }
+
+  let value = config;
+  for (const segment of segments) {
+    if (value === null || typeof value !== 'object' || !(segment in value)) {
+      console.log(chalk.red(`  Config path not found: ${key}`));
+      process.exit(1);
+    }
+    value = value[segment];
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  if (value !== null && typeof value === 'object') {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+
+  console.log(String(value));
+}
+
 function parseSetInput(input) {
   if (Array.isArray(input)) {
     if (input.length >= 2) {
@@ -235,6 +275,19 @@ function parseSetInput(input) {
   return null;
 }
 
+function parseKeyPath(input) {
+  if (typeof input !== 'string' || input.trim() === '') {
+    return null;
+  }
+
+  const segments = input.split('.');
+  const forbiddenKeys = new Set(['__proto__', 'prototype', 'constructor']);
+  if (segments.some(segment => segment === '' || forbiddenKeys.has(segment))) {
+    return null;
+  }
+  return segments;
+}
+
 function validateEditedConfig(config, context) {
   if (context.version === 4) {
     return validateV4Config(config, context.root);

package/src/commands/restart.js

@@ -297,6 +297,9 @@ export async function restartCommand(opts) {
       console.log(chalk.red(`Failed to assign turn: ${assignment.error}`));
       process.exit(1);
     }
+    for (const warning of assignment.warnings || []) {
+      console.log(chalk.yellow(`Warning: ${warning}`));
+    }
 
     // assignGovernedTurn already writes a checkpoint at turn_assigned
 

package/src/commands/resume.js

@@ -259,6 +259,7 @@ export async function resumeCommand(opts) {
     console.log(chalk.red(`Failed to assign turn: ${assignResult.error}`));
     process.exit(1);
   }
+  printAssignmentWarnings(assignResult);
   state = assignResult.state;
 
   // Write dispatch bundle
@@ -415,6 +416,12 @@ function printDispatchBundleWarnings(bundleResult) {
   }
 }
 
+function printAssignmentWarnings(assignResult) {
+  for (const warning of assignResult.warnings || []) {
+    console.log(chalk.yellow(`Warning: ${warning}`));
+  }
+}
+
 function printAssignmentHookFailure(result, roleId) {
   const recovery = deriveRecoveryDescriptor(result.state);
   const hookName = result.hookResults?.blocker?.hook_name

package/src/commands/role.js

@@ -0,0 +1,106 @@
+import chalk from 'chalk';
+import { loadProjectContext } from '../lib/config.js';
+
+export function roleCommand(subcommand, roleId, opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { rawConfig, version } = context;
+
+  if (version !== 4) {
+    console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
+    process.exit(1);
+  }
+
+  const roles = rawConfig.roles || {};
+  const roleIds = Object.keys(roles);
+
+  if (subcommand === 'show') {
+    return showRole(roleId, roles, roleIds, opts);
+  }
+
+  // Default: list
+  return listRoles(roles, roleIds, opts);
+}
+
+function listRoles(roles, roleIds, opts) {
+  if (roleIds.length === 0) {
+    if (opts.json) {
+      console.log('[]');
+    } else {
+      console.log('  No roles defined.');
+    }
+    return;
+  }
+
+  if (opts.json) {
+    const output = roleIds.map((id) => ({
+      id,
+      title: roles[id].title,
+      mandate: roles[id].mandate,
+      write_authority: roles[id].write_authority,
+      runtime: roles[id].runtime,
+    }));
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Roles (${roleIds.length}):\n`));
+  for (const id of roleIds) {
+    const r = roles[id];
+    const authority = r.write_authority === 'authoritative'
+      ? chalk.green(r.write_authority)
+      : r.write_authority === 'proposed'
+        ? chalk.yellow(r.write_authority)
+        : chalk.dim(r.write_authority);
+    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}] → ${chalk.dim(r.runtime)}`);
+  }
+  console.log('');
+  console.log(chalk.dim('  Usage: agentxchain role show <role_id>\n'));
+}
+
+function showRole(roleId, roles, roleIds, opts) {
+  if (!roleId) {
+    console.log(chalk.red('  Missing role ID.'));
+    console.log(chalk.dim(`  Usage: agentxchain role show <role_id>`));
+    if (roleIds.length > 0) {
+      console.log(chalk.dim(`  Available: ${roleIds.join(', ')}`));
+    }
+    process.exit(1);
+  }
+
+  if (!roles[roleId]) {
+    console.log(chalk.red(`  Unknown role: ${roleId}`));
+    console.log(chalk.dim(`  Available: ${roleIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  const r = roles[roleId];
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      id: roleId,
+      title: r.title,
+      mandate: r.mandate,
+      write_authority: r.write_authority,
+      runtime: r.runtime,
+    }, null, 2));
+    return;
+  }
+
+  const authority = r.write_authority === 'authoritative'
+    ? chalk.green(r.write_authority)
+    : r.write_authority === 'proposed'
+      ? chalk.yellow(r.write_authority)
+      : chalk.dim(r.write_authority);
+
+  console.log(chalk.bold(`\n  Role: ${chalk.cyan(roleId)}\n`));
+  console.log(`  Title:      ${r.title}`);
+  console.log(`  Mandate:    ${r.mandate}`);
+  console.log(`  Authority:  ${authority}`);
+  console.log(`  Runtime:    ${chalk.dim(r.runtime)}`);
+  console.log('');
+}

package/src/commands/status.js

@@ -277,7 +277,10 @@ function renderGovernedStatus(context, opts) {
 
   if (state?.budget_status) {
     console.log('');
-    console.log(`  ${chalk.dim('Budget:')}   spent $${formatUsd(state.budget_status.spent_usd)} / remaining $${formatUsd(state.budget_status.remaining_usd)}`);
+    const budgetLabel = state.budget_status.warn_mode
+      ? `spent $${formatUsd(state.budget_status.spent_usd)} / remaining $${formatUsd(state.budget_status.remaining_usd)} ${chalk.yellow('[OVER BUDGET]')}`
+      : `spent $${formatUsd(state.budget_status.spent_usd)} / remaining $${formatUsd(state.budget_status.remaining_usd)}`;
+    console.log(`  ${chalk.dim('Budget:')}   ${budgetLabel}`);
   }
 
   console.log('');

package/src/commands/step.js

@@ -293,6 +293,7 @@ export async function stepCommand(opts) {
         console.log(chalk.red(`Failed to assign turn: ${assignResult.error}`));
         process.exit(1);
       }
+      printAssignmentWarnings(assignResult);
       state = assignResult.state;
 
       const bundleResult = writeDispatchBundle(root, state, config);
@@ -948,6 +949,12 @@ function printDispatchBundleWarnings(bundleResult) {
   }
 }
 
+function printAssignmentWarnings(assignResult) {
+  for (const warning of assignResult.warnings || []) {
+    console.log(chalk.yellow(`Warning: ${warning}`));
+  }
+}
+
 function printAssignmentHookFailure(result, roleId) {
   const recovery = deriveRecoveryDescriptor(result.state);
   const hookName = result.hookResults?.blocker?.hook_name

package/src/commands/turn.js

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
+import {
+  getDispatchAssignmentPath,
+  getDispatchContextPath,
+  getDispatchManifestPath,
+  getDispatchPromptPath,
+  getDispatchTurnDir,
+} from '../lib/turn-paths.js';
+
+const ARTIFACTS = {
+  assignment: {
+    label: 'Assignment',
+    pathFor: getDispatchAssignmentPath,
+    parse: 'json',
+  },
+  prompt: {
+    label: 'Prompt',
+    pathFor: getDispatchPromptPath,
+    parse: 'text',
+  },
+  context: {
+    label: 'Context',
+    pathFor: getDispatchContextPath,
+    parse: 'text',
+  },
+  manifest: {
+    label: 'Manifest',
+    pathFor: getDispatchManifestPath,
+    parse: 'json',
+  },
+};
+
+export function turnShowCommand(turnId, opts) {
+  const context = requireGovernedContext();
+  const state = loadProjectState(context.root, context.config);
+
+  if (!state) {
+    console.log(chalk.red('  Governed state is missing or invalid.'));
+    process.exit(1);
+  }
+
+  const activeTurns = getActiveTurns(state);
+  const selectedTurnId = resolveTurnId(turnId, activeTurns);
+  const turn = activeTurns[selectedTurnId];
+  const artifacts = buildArtifactIndex(context.root, selectedTurnId);
+  const assignment = readJsonArtifact(artifacts.assignment.absPath);
+
+  if (opts.artifact) {
+    return printArtifact(selectedTurnId, turn, artifacts, opts.artifact, opts.json);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(buildTurnPayload(selectedTurnId, turn, state, artifacts, assignment), null, 2));
+    return;
+  }
+
+  printTurnSummary(selectedTurnId, turn, state, artifacts, assignment);
+}
+
+function requireGovernedContext() {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+  if (context.config.protocol_mode !== 'governed') {
+    console.log(chalk.red('  The turn command is only available for governed projects.'));
+    process.exit(1);
+  }
+  return context;
+}
+
+function resolveTurnId(requestedTurnId, activeTurns) {
+  const turnIds = Object.keys(activeTurns);
+  if (requestedTurnId) {
+    if (!activeTurns[requestedTurnId]) {
+      console.log(chalk.red(`  Unknown active turn: ${requestedTurnId}`));
+      if (turnIds.length > 0) {
+        console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+      }
+      process.exit(1);
+    }
+    return requestedTurnId;
+  }
+
+  if (turnIds.length === 0) {
+    console.log(chalk.red('  No active turn found.'));
+    process.exit(1);
+  }
+
+  if (turnIds.length > 1) {
+    console.log(chalk.red('  Multiple active turns are present. Re-run with `agentxchain turn show <turn_id>`.'));
+    console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  return turnIds[0];
+}
+
+function buildArtifactIndex(root, turnId) {
+  return Object.fromEntries(
+    Object.entries(ARTIFACTS).map(([id, artifact]) => {
+      const relPath = artifact.pathFor(turnId);
+      const absPath = join(root, relPath);
+      return [id, {
+        id,
+        label: artifact.label,
+        relPath,
+        absPath,
+        exists: existsSync(absPath),
+        parse: artifact.parse,
+      }];
+    }),
+  );
+}
+
+function buildTurnPayload(turnId, turn, state, artifacts, assignment) {
+  return {
+    turn_id: turnId,
+    run_id: state.run_id || assignment?.run_id || null,
+    phase: state.phase || assignment?.phase || null,
+    role: turn.assigned_role,
+    runtime: turn.runtime_id,
+    status: turn.status,
+    attempt: turn.attempt,
+    dispatch_dir: getDispatchTurnDir(turnId),
+    staging_result_path: assignment?.staging_result_path || null,
+    active_turn_count: getActiveTurnCount(state),
+    artifacts: Object.fromEntries(
+      Object.entries(artifacts).map(([id, artifact]) => [id, {
+        path: artifact.relPath,
+        exists: artifact.exists,
+      }]),
+    ),
+  };
+}
+
+function printTurnSummary(turnId, turn, state, artifacts, assignment) {
+  console.log('');
+  console.log(chalk.bold(`  Turn: ${chalk.cyan(turnId)}`));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Run:')}      ${state.run_id || assignment?.run_id || chalk.dim('unknown')}`);
+  console.log(`  ${chalk.dim('Phase:')}    ${state.phase || assignment?.phase || chalk.dim('unknown')}`);
+  console.log(`  ${chalk.dim('Role:')}     ${chalk.bold(turn.assigned_role)}`);
+  console.log(`  ${chalk.dim('Runtime:')}  ${turn.runtime_id}`);
+  console.log(`  ${chalk.dim('Status:')}   ${turn.status}`);
+  console.log(`  ${chalk.dim('Attempt:')}  ${turn.attempt}`);
+  console.log(`  ${chalk.dim('Dispatch:')} ${getDispatchTurnDir(turnId)}`);
+  if (assignment?.staging_result_path) {
+    console.log(`  ${chalk.dim('Staging:')}  ${assignment.staging_result_path}`);
+  }
+  console.log('');
+  console.log(`  ${chalk.dim('Artifacts:')}`);
+  for (const artifact of Object.values(artifacts)) {
+    const marker = artifact.exists ? chalk.green('exists') : chalk.red('missing');
+    console.log(`    ${artifact.label.padEnd(10)} ${marker}  ${artifact.relPath}`);
+  }
+  console.log('');
+  console.log(chalk.dim(`  View one: agentxchain turn show ${turnId} --artifact prompt`));
+  console.log('');
+}
+
+function printArtifact(turnId, turn, artifacts, artifactId, jsonMode) {
+  const artifact = artifacts[artifactId];
+  if (!artifact) {
+    console.log(chalk.red(`  Unknown artifact: ${artifactId}`));
+    console.log(chalk.dim(`  Allowed: ${Object.keys(ARTIFACTS).join(', ')}`));
+    process.exit(1);
+  }
+  if (!artifact.exists) {
+    console.log(chalk.red(`  Missing artifact: ${artifact.relPath}`));
+    process.exit(1);
+  }
+
+  const raw = readFileSync(artifact.absPath, 'utf8');
+  if (!jsonMode) {
+    process.stdout.write(raw.endsWith('\n') ? raw : `${raw}\n`);
+    return;
+  }
+
+  const content = artifact.parse === 'json'
+    ? JSON.parse(raw)
+    : raw;
+
+  console.log(JSON.stringify({
+    turn_id: turnId,
+    role: turn.assigned_role,
+    runtime: turn.runtime_id,
+    artifact: {
+      id: artifact.id,
+      path: artifact.relPath,
+      content,
+    },
+  }, null, 2));
+}
+
+function readJsonArtifact(absPath) {
+  if (!existsSync(absPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(absPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/src/lib/governed-state.js

@@ -1936,13 +1936,19 @@ export function assignGovernedTurn(root, config, roleId) {
     return { ok: false, error: `Cannot assign turn: ${activeCount} active turn(s) already at capacity (max_concurrent_turns = ${maxConcurrent})` };
   }
 
-  // DEC-BUDGET-ENFORCE-001: Pre-assignment budget exhaustion guard
-  if (state.budget_status?.remaining_usd != null && state.budget_status.remaining_usd <= 0) {
-    return { ok: false, error: `Cannot assign turn: run budget exhausted (spent $${(state.budget_status.spent_usd || 0).toFixed(2)} of $${((state.budget_status.spent_usd || 0) + state.budget_status.remaining_usd).toFixed(2)} limit). Increase budget with agentxchain config --set budget.per_run_max_usd <usd>, then run agentxchain resume` };
-  }
-
   // DEC-PARALLEL-011: Budget reservation
   const warnings = [];
+
+  // DEC-BUDGET-ENFORCE-001 + DEC-BUDGET-WARN-001: Pre-assignment budget exhaustion guard
+  if (state.budget_status?.remaining_usd != null && state.budget_status.remaining_usd <= 0) {
+    const onExceed = config.budget?.on_exceed || 'pause_and_escalate';
+    if (onExceed === 'warn') {
+      // Allow assignment but add a warning
+      warnings.push(`Budget exhausted (spent $${(state.budget_status.spent_usd || 0).toFixed(2)} of $${((state.budget_status.spent_usd || 0) + state.budget_status.remaining_usd).toFixed(2)} limit). Run continues in warn mode per on_exceed policy.`);
+    } else {
+      return { ok: false, error: `Cannot assign turn: run budget exhausted (spent $${(state.budget_status.spent_usd || 0).toFixed(2)} of $${((state.budget_status.spent_usd || 0) + state.budget_status.remaining_usd).toFixed(2)} limit). Increase budget with agentxchain config --set budget.per_run_max_usd <usd>, then run agentxchain resume` };
+    }
+  }
   const reservations = { ...(state.budget_reservations || {}) };
   const turnId = generateId('turn');
   const estimatedCost = estimateTurnBudget(config, roleId);
@@ -1950,7 +1956,8 @@ export function assignGovernedTurn(root, config, roleId) {
   if (estimatedCost > 0 && state.budget_status?.remaining_usd != null) {
     const alreadyReserved = Object.values(reservations).reduce((sum, r) => sum + (r.reserved_usd || 0), 0);
     const available = state.budget_status.remaining_usd - alreadyReserved;
-    if (estimatedCost > available) {
+    const onExceedReserve = config.budget?.on_exceed || 'pause_and_escalate';
+    if (estimatedCost > available && onExceedReserve !== 'warn') {
       return { ok: false, error: `Cannot assign turn: estimated cost $${estimatedCost.toFixed(2)} exceeds available budget $${available.toFixed(2)} (after reservations)` };
     }
     reservations[turnId] = {
@@ -2617,6 +2624,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     accepted_integration_ref: derivedRef,
     next_recommended_role: deriveNextRecommendedRole(turnResult, state, config),
     budget_status: {
+      ...(state.budget_status || {}),
       spent_usd: (state.budget_status?.spent_usd || 0) + costUsd,
       remaining_usd: state.budget_status?.remaining_usd != null
         ? state.budget_status.remaining_usd - costUsd
@@ -2657,7 +2665,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   if (turnReservation && costUsd > turnReservation.reserved_usd) {
     budgetWarning = `Actual cost $${costUsd.toFixed(2)} exceeded reservation $${turnReservation.reserved_usd.toFixed(2)} for this turn`;
   }
-  // Budget exhaustion enforcement
+  // Budget exhaustion enforcement (DEC-BUDGET-ENFORCE-001 + DEC-BUDGET-WARN-001)
   if (
     updatedState.budget_status.remaining_usd != null &&
     updatedState.budget_status.remaining_usd <= 0 &&
@@ -2665,9 +2673,9 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     updatedState.status !== 'completed'
   ) {
     const onExceed = config.budget?.on_exceed || 'pause_and_escalate';
+    const limit = (updatedState.budget_status.spent_usd + updatedState.budget_status.remaining_usd);
+    const overBy = Math.abs(updatedState.budget_status.remaining_usd);
     if (onExceed === 'pause_and_escalate') {
-      const limit = (updatedState.budget_status.spent_usd + updatedState.budget_status.remaining_usd);
-      const overBy = Math.abs(updatedState.budget_status.remaining_usd);
       updatedState.status = 'blocked';
       updatedState.blocked_on = 'budget:exhausted';
       updatedState.blocked_reason = buildBlockedReason({
@@ -2685,6 +2693,15 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       updatedState.budget_status.exhausted = true;
       updatedState.budget_status.exhausted_at = now;
       updatedState.budget_status.exhausted_after_turn = currentTurn.turn_id;
+    } else if (onExceed === 'warn') {
+      // DEC-BUDGET-WARN-001: Do not block — mark exhaustion and emit warning
+      if (!updatedState.budget_status.exhausted) {
+        updatedState.budget_status.exhausted = true;
+        updatedState.budget_status.exhausted_at = now;
+        updatedState.budget_status.exhausted_after_turn = currentTurn.turn_id;
+      }
+      updatedState.budget_status.warn_mode = true;
+      budgetWarning = `Budget exhausted: spent $${updatedState.budget_status.spent_usd.toFixed(2)} of $${limit.toFixed(2)} limit ($${overBy.toFixed(2)} over). Run continues in warn mode.`;
     }
   }
 
@@ -3081,6 +3098,22 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     });
   }
 
+  // DEC-BUDGET-WARN-001: Emit budget_exceeded_warn event when warn mode triggers
+  if (updatedState.budget_status?.warn_mode && budgetWarning) {
+    emitRunEvent(root, 'budget_exceeded_warn', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      payload: {
+        spent_usd: updatedState.budget_status.spent_usd,
+        limit_usd: updatedState.budget_status.spent_usd + updatedState.budget_status.remaining_usd,
+        remaining_usd: updatedState.budget_status.remaining_usd,
+        warning: budgetWarning,
+      },
+    });
+  }
+
   if (updatedState.pending_phase_transition) {
     emitPendingLifecycleNotification(root, config, updatedState, 'phase_transition_pending', {
       from: updatedState.pending_phase_transition.from,

package/src/lib/normalized-config.js

@@ -61,7 +61,7 @@ const VALID_API_PROXY_PREFLIGHT_FIELDS = [
   'tokenizer',
   'safety_margin_tokens',
 ];
-const VALID_BUDGET_ON_EXCEED = ['pause_and_escalate'];
+const VALID_BUDGET_ON_EXCEED = ['pause_and_escalate', 'warn'];
 
 function validateMcpRuntime(runtimeId, runtime, errors) {
   const transport = typeof runtime?.transport === 'string' && runtime.transport.trim()
@@ -583,7 +583,7 @@ export function validateBudgetConfig(budget) {
 
   if (budget.on_exceed !== undefined) {
     if (typeof budget.on_exceed !== 'string' || !VALID_BUDGET_ON_EXCEED.includes(budget.on_exceed)) {
-      errors.push(`budget.on_exceed must be one of: ${VALID_BUDGET_ON_EXCEED.join(', ')} (warn is not implemented)`);
+      errors.push(`budget.on_exceed must be one of: ${VALID_BUDGET_ON_EXCEED.join(', ')}`);
     }
   }
 

package/src/lib/report.js

@@ -45,6 +45,19 @@ function normalizeBudgetStatus(budgetStatus) {
   if (Number.isFinite(budgetStatus.remaining_usd)) {
     normalized.remaining_usd = budgetStatus.remaining_usd;
   }
+  // DEC-BUDGET-WARN-004: preserve warn-mode and exhaustion fields
+  if (budgetStatus.warn_mode === true) {
+    normalized.warn_mode = true;
+  }
+  if (budgetStatus.exhausted === true) {
+    normalized.exhausted = true;
+  }
+  if (budgetStatus.exhausted_at) {
+    normalized.exhausted_at = budgetStatus.exhausted_at;
+  }
+  if (budgetStatus.exhausted_after_turn) {
+    normalized.exhausted_after_turn = budgetStatus.exhausted_after_turn;
+  }
 
   return Object.keys(normalized).length > 0 ? normalized : null;
 }
@@ -890,8 +903,9 @@ export function formatGovernanceReportText(report) {
     ];
 
     if (run.budget_status) {
+      const warnTag = run.budget_status.warn_mode ? ' [OVER BUDGET]' : '';
       lines.push(
-        `Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}`,
+        `Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}${warnTag}`,
       );
     }
 
@@ -1300,7 +1314,8 @@ export function formatGovernanceReportMarkdown(report) {
     ];
 
     if (run.budget_status) {
-      lines.push(`- Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}`);
+      const warnTag = run.budget_status.warn_mode ? ' **[OVER BUDGET]**' : '';
+      lines.push(`- Budget: spent ${formatUsd(run.budget_status.spent_usd)}, remaining ${formatUsd(run.budget_status.remaining_usd)}${warnTag}`);
     }
 
     if (run.created_at) {

package/src/lib/run-events.js

@@ -23,6 +23,7 @@ export const VALID_RUN_EVENTS = [
   'escalation_resolved',
   'gate_pending',
   'gate_approved',
+  'budget_exceeded_warn',
 ];
 
 /**