agentxchain 0.8.7 → 2.1.1

package/scripts/release-postflight.sh

@@ -0,0 +1,231 @@
+#!/usr/bin/env bash
+# Release postflight — run this after publish succeeds.
+# Verifies: release tag exists, npm registry serves the version, metadata is present,
+# and the published package can execute its CLI entrypoint.
+# Usage: bash scripts/release-postflight.sh --target-version <semver> [--tag vX.Y.Z]
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_DIR="${SCRIPT_DIR}/.."
+cd "$CLI_DIR"
+
+TARGET_VERSION=""
+TAG=""
+RETRY_ATTEMPTS="${RELEASE_POSTFLIGHT_RETRY_ATTEMPTS:-6}"
+RETRY_DELAY_SECONDS="${RELEASE_POSTFLIGHT_RETRY_DELAY_SECONDS:-10}"
+
+usage() {
+  echo "Usage: bash scripts/release-postflight.sh --target-version <semver> [--tag vX.Y.Z]" >&2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target-version)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --target-version requires a semver argument" >&2
+        usage
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+        echo "Invalid semver: $2" >&2
+        usage
+        exit 1
+      fi
+      TARGET_VERSION="$2"
+      shift 2
+      ;;
+    --tag)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --tag requires a git tag argument" >&2
+        usage
+        exit 1
+      fi
+      TAG="$2"
+      shift 2
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$TARGET_VERSION" ]]; then
+  echo "Error: --target-version is required" >&2
+  usage
+  exit 1
+fi
+
+if [[ -z "$TAG" ]]; then
+  TAG="v${TARGET_VERSION}"
+fi
+
+if ! [[ "$RETRY_ATTEMPTS" =~ ^[0-9]+$ ]] || [[ "$RETRY_ATTEMPTS" -lt 1 ]]; then
+  echo "Error: RELEASE_POSTFLIGHT_RETRY_ATTEMPTS must be a positive integer" >&2
+  exit 1
+fi
+
+if ! [[ "$RETRY_DELAY_SECONDS" =~ ^[0-9]+$ ]]; then
+  echo "Error: RELEASE_POSTFLIGHT_RETRY_DELAY_SECONDS must be a non-negative integer" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+TARBALL_URL=""
+REGISTRY_CHECKSUM=""
+PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
+
+pass() { PASS=$((PASS + 1)); echo "  PASS: $1"; }
+fail() { FAIL=$((FAIL + 1)); echo "  FAIL: $1"; }
+
+run_and_capture() {
+  local __var_name="$1"
+  shift
+
+  local captured_output
+  local status
+  captured_output="$("$@" 2>&1)"
+  status=$?
+
+  printf -v "$__var_name" '%s' "$captured_output"
+  return "$status"
+}
+
+trim_last_line() {
+  printf '%s\n' "$1" | awk 'NF { line=$0 } END { gsub(/^[[:space:]]+|[[:space:]]+$/, "", line); print line }'
+}
+
+run_with_retry() {
+  local __output_var="$1"
+  local description="$2"
+  local success_mode="$3"
+  local expected_value="$4"
+  shift 4
+
+  local output=""
+  local status=0
+  local value=""
+  local attempt=1
+
+  while [[ "$attempt" -le "$RETRY_ATTEMPTS" ]]; do
+    if run_and_capture output "$@"; then
+      status=0
+    else
+      status=$?
+    fi
+
+    value="$(trim_last_line "$output")"
+
+    case "$success_mode" in
+      equals)
+        if [[ "$status" -eq 0 && "$value" == "$expected_value" ]]; then
+          printf -v "$__output_var" '%s' "$output"
+          return 0
+        fi
+        ;;
+      nonempty)
+        if [[ "$status" -eq 0 && -n "$value" ]]; then
+          printf -v "$__output_var" '%s' "$output"
+          return 0
+        fi
+        ;;
+      *)
+        echo "Error: unsupported retry success mode '${success_mode}'" >&2
+        exit 1
+        ;;
+    esac
+
+    if [[ "$attempt" -lt "$RETRY_ATTEMPTS" ]]; then
+      echo "  INFO: ${description} not ready (attempt ${attempt}/${RETRY_ATTEMPTS}); retrying in ${RETRY_DELAY_SECONDS}s..."
+      sleep "$RETRY_DELAY_SECONDS"
+    fi
+    attempt=$((attempt + 1))
+  done
+
+  printf -v "$__output_var" '%s' "$output"
+  return 1
+}
+
+echo "AgentXchain v${TARGET_VERSION} Release Postflight"
+echo "====================================="
+echo "Checks release truth after publish: tag, registry visibility, metadata, and install smoke."
+echo ""
+
+echo "[1/5] Git tag"
+if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null 2>&1; then
+  pass "Git tag ${TAG} exists locally"
+else
+  fail "Git tag ${TAG} is missing locally"
+fi
+
+echo "[2/5] Registry version"
+if run_with_retry VERSION_OUTPUT "registry version" equals "${TARGET_VERSION}" npm view "${PACKAGE_NAME}@${TARGET_VERSION}" version; then
+  PUBLISHED_VERSION="$(trim_last_line "$VERSION_OUTPUT")"
+  if [[ "$PUBLISHED_VERSION" == "$TARGET_VERSION" ]]; then
+    pass "npm registry serves ${PACKAGE_NAME}@${TARGET_VERSION}"
+  else
+    fail "npm registry returned '${PUBLISHED_VERSION}', expected '${TARGET_VERSION}'"
+  fi
+else
+  fail "npm registry does not serve ${PACKAGE_NAME}@${TARGET_VERSION}"
+  printf '%s\n' "$VERSION_OUTPUT" | tail -20
+fi
+
+echo "[3/5] Registry tarball metadata"
+if run_with_retry TARBALL_OUTPUT "registry tarball metadata" nonempty "" npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.tarball; then
+  TARBALL_URL="$(trim_last_line "$TARBALL_OUTPUT")"
+  if [[ -n "$TARBALL_URL" ]]; then
+    pass "registry exposes dist.tarball metadata"
+  else
+    fail "registry returned empty dist.tarball metadata"
+  fi
+else
+  fail "registry did not return dist.tarball metadata"
+  printf '%s\n' "$TARBALL_OUTPUT" | tail -20
+fi
+
+echo "[4/5] Registry checksum metadata"
+if run_with_retry INTEGRITY_OUTPUT "registry checksum metadata" nonempty "" npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.integrity; then
+  REGISTRY_CHECKSUM="$(trim_last_line "$INTEGRITY_OUTPUT")"
+fi
+if [[ -z "$REGISTRY_CHECKSUM" ]]; then
+  if run_with_retry SHASUM_OUTPUT "registry shasum metadata" nonempty "" npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.shasum; then
+    REGISTRY_CHECKSUM="$(trim_last_line "$SHASUM_OUTPUT")"
+  fi
+fi
+if [[ -n "$REGISTRY_CHECKSUM" ]]; then
+  pass "registry exposes checksum metadata"
+else
+  fail "registry did not return checksum metadata"
+fi
+
+echo "[5/5] Install smoke"
+if run_with_retry EXEC_OUTPUT "install smoke" nonempty "" npm exec --yes --package "${PACKAGE_NAME}@${TARGET_VERSION}" -- agentxchain --version; then
+  EXEC_VERSION="$(trim_last_line "$EXEC_OUTPUT")"
+  if [[ "$EXEC_VERSION" == "$TARGET_VERSION" ]]; then
+    pass "published CLI executes and reports ${TARGET_VERSION}"
+  else
+    fail "published CLI reported '${EXEC_VERSION}', expected '${TARGET_VERSION}'"
+  fi
+else
+  fail "published CLI install smoke failed"
+  printf '%s\n' "$EXEC_OUTPUT" | tail -20
+fi
+
+echo ""
+echo "====================================="
+echo "Results: ${PASS} passed, ${FAIL} failed"
+if [[ -n "$TARBALL_URL" ]]; then
+  echo "Tarball: ${TARBALL_URL}"
+fi
+if [[ -n "$REGISTRY_CHECKSUM" ]]; then
+  echo "Checksum: ${REGISTRY_CHECKSUM}"
+fi
+if [ "$FAIL" -gt 0 ]; then
+  echo "POSTFLIGHT FAILED — do not mark the release complete."
+  exit 1
+fi
+
+echo "POSTFLIGHT PASSED — registry truth matches the release tag."
+exit 0

package/scripts/release-preflight.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# Release preflight — run this before cutting a release.
+# Verifies: clean tree, deps, tests, CHANGELOG entry, pack dry-run.
+# Usage: bash scripts/release-preflight.sh [--strict] [--target-version <semver>]
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_DIR="${SCRIPT_DIR}/.."
+cd "$CLI_DIR"
+
+STRICT_MODE=0
+TARGET_VERSION="2.0.0"
+
+usage() {
+  echo "Usage: bash scripts/release-preflight.sh [--strict] [--target-version <semver>]" >&2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --strict)
+      STRICT_MODE=1
+      shift
+      ;;
+    --target-version)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --target-version requires a semver argument" >&2
+        usage
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+        echo "Invalid semver: $2" >&2
+        usage
+        exit 1
+      fi
+      TARGET_VERSION="$2"
+      shift 2
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+PASS=0
+FAIL=0
+WARN=0
+
+pass() { PASS=$((PASS + 1)); echo "  PASS: $1"; }
+fail() { FAIL=$((FAIL + 1)); echo "  FAIL: $1"; }
+warn() { WARN=$((WARN + 1)); echo "  WARN: $1"; }
+
+run_and_capture() {
+  local __var_name="$1"
+  shift
+
+  local output
+  local status
+  output="$("$@" 2>&1)"
+  status=$?
+
+  printf -v "$__var_name" '%s' "$output"
+  return "$status"
+}
+
+echo "AgentXchain v${TARGET_VERSION} Release Preflight"
+echo "====================================="
+if [[ "$TARGET_VERSION" == "1.0.0" ]]; then
+  echo "Local checks only. Human-gated release items remain in .planning/V1_RELEASE_CHECKLIST.md."
+else
+  echo "Local checks only. Human-gated release items remain in .planning/V1_RELEASE_CHECKLIST.md (v1.0) or .planning/V1_1_RELEASE_CHECKLIST.md (v1.1+)."
+fi
+if [[ "$STRICT_MODE" -eq 1 ]]; then
+  echo "Mode: STRICT (dirty tree and non-${TARGET_VERSION} package version are hard failures)"
+else
+  echo "Mode: DEFAULT (dirty tree and pre-bump package version are warnings)"
+fi
+echo ""
+
+# 1. Clean working tree
+echo "[1/6] Git status"
+if git diff --quiet HEAD 2>/dev/null && [ -z "$(git ls-files --others --exclude-standard 2>/dev/null)" ]; then
+  pass "Working tree is clean"
+else
+  if [[ "$STRICT_MODE" -eq 1 ]]; then
+    fail "Working tree is not clean"
+  else
+    warn "Uncommitted or untracked files present"
+  fi
+fi
+
+# 2. Dependencies
+echo "[2/6] Dependencies"
+if run_and_capture NPM_CI_OUTPUT npm ci --ignore-scripts; then
+  pass "npm ci succeeded"
+else
+  fail "npm ci failed"
+  printf '%s\n' "$NPM_CI_OUTPUT" | tail -20
+fi
+
+# 3. Tests
+echo "[3/6] Test suite"
+if run_and_capture TEST_OUTPUT npm test; then
+  TEST_STATUS=0
+else
+  TEST_STATUS=$?
+fi
+TEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# pass / { print $3 }')"
+TEST_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# fail / { print $3 }')"
+if [ "$TEST_STATUS" -eq 0 ] && [ "${TEST_FAIL:-0}" = "0" ]; then
+  pass "${TEST_PASS} tests passed, 0 failures"
+else
+  fail "npm test failed"
+  printf '%s\n' "$TEST_OUTPUT" | tail -20
+fi
+
+# 4. CHANGELOG has target version
+echo "[4/6] CHANGELOG"
+if grep -Fxq "## ${TARGET_VERSION}" CHANGELOG.md 2>/dev/null; then
+  pass "CHANGELOG.md contains ${TARGET_VERSION} entry"
+else
+  fail "CHANGELOG.md missing ${TARGET_VERSION} entry"
+fi
+
+# 5. Package version
+echo "[5/6] Package version"
+PKG_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).version)")
+echo "  Current version: ${PKG_VERSION}"
+if [ "$PKG_VERSION" = "${TARGET_VERSION}" ]; then
+  pass "package.json is at ${TARGET_VERSION}"
+else
+  if [[ "$STRICT_MODE" -eq 1 ]]; then
+    fail "package.json is at ${PKG_VERSION}, expected ${TARGET_VERSION}"
+  else
+    warn "package.json is at ${PKG_VERSION}, not yet bumped to ${TARGET_VERSION}"
+  fi
+fi
+
+# 6. Pack dry-run
+echo "[6/6] npm pack --dry-run"
+if run_and_capture PACK_OUTPUT npm pack --dry-run; then
+  pass "npm pack --dry-run succeeded"
+  PACK_SIZE_LINE="$(printf '%s\n' "$PACK_OUTPUT" | awk '/total files:/ { print; found=1 } END { if (!found) exit 1 }')"
+  if [ -n "${PACK_SIZE_LINE:-}" ]; then
+    echo "  ${PACK_SIZE_LINE}"
+  else
+    printf '%s\n' "$PACK_OUTPUT" | tail -5
+  fi
+else
+  fail "npm pack --dry-run failed"
+  printf '%s\n' "$PACK_OUTPUT" | tail -20
+fi
+
+# Summary
+echo ""
+echo "====================================="
+echo "Results: ${PASS} passed, ${FAIL} failed, ${WARN} warnings"
+if [ "$FAIL" -gt 0 ]; then
+  echo "PREFLIGHT FAILED — fix failures before release."
+  exit 1
+elif [ "$WARN" -gt 0 ]; then
+  echo "PREFLIGHT PASSED WITH WARNINGS — resolve warnings before release day."
+  exit 0
+else
+  echo "PREFLIGHT PASSED — ready for release."
+  exit 0
+fi

package/scripts/run-autonudge.sh

@@ -104,7 +104,7 @@ echo "Mode:      $( [[ "${AUTO_SEND}" == "true" ]] && echo "auto-send" || echo "
 echo "Interval:  ${INTERVAL_SECONDS}s"
 echo ""
 echo "Requirements:"
-echo "- Keep 'agentxchain watch' running in another terminal."
+echo "- Watch must be running (e.g. 'agentxchain supervise --autonudge' starts it in the same supervisor, or run 'agentxchain watch' in another terminal)."
 echo "- Grant Accessibility permission to Terminal and Cursor."
 echo ""
 

package/src/adapters/claude-code.js

@@ -1,8 +1,9 @@
 import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
-import { writeFileSync } from 'fs';
 import { join } from 'path';
+import { safeWriteJson } from '../lib/safe-write.js';
+import { filterAgents } from '../lib/filter-agents.js';
 
 export async function launchClaudeCodeAgents(config, root, opts) {
   const agents = filterAgents(config, opts.agent);
@@ -28,22 +29,14 @@ export async function launchClaudeCodeAgents(config, root, opts) {
   }
 
   if (launched.length > 0) {
-    const sessionFile = JSON.stringify({ launched, started_at: new Date().toISOString(), ide: 'claude-code' }, null, 2);
-    writeFileSync(join(root, '.agentxchain-session.json'), sessionFile + '\n');
+    safeWriteJson(join(root, '.agentxchain-session.json'), {
+      launched,
+      started_at: new Date().toISOString(),
+      ide: 'claude-code'
+    });
     console.log('');
     console.log(chalk.dim(`  Session saved to .agentxchain-session.json`));
   }
 
   return launched;
 }
-
-function filterAgents(config, specificId) {
-  if (specificId) {
-    if (!config.agents[specificId]) {
-      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
-      process.exit(1);
-    }
-    return { [specificId]: config.agents[specificId] };
-  }
-  return config.agents;
-}

package/src/adapters/cursor-local.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { generatePollingPrompt } from '../lib/seed-prompt-polling.js';
+import { filterAgents } from '../lib/filter-agents.js';
 
 export async function launchCursorLocal(config, root, opts) {
   const agents = filterAgents(config, opts.agent);
@@ -50,13 +51,22 @@ export async function launchCursorLocal(config, root, opts) {
     console.log(chalk.cyan(`  ─── Agent ${i + 1}/${total}: ${chalk.bold(id)} — ${agent.name} ───`));
     console.log('');
 
-    copyToClipboard(prompt);
-    console.log(chalk.green(`  ✓ Prompt copied to clipboard.`));
+    const copied = copyToClipboard(prompt);
+    if (copied) {
+      console.log(chalk.green('  ✓ Prompt copied to clipboard.'));
+    } else {
+      console.log(chalk.yellow('  ! Clipboard copy failed. Use the saved prompt file manually.'));
+    }
     console.log(chalk.dim(`    Saved to: .agentxchain-prompts/${id}.prompt.md`));
 
     // Open a separate Cursor window using the symlinked path
-    openCursorWindow(agentWorkspace);
-    console.log(chalk.dim(`    Cursor window opened for ${id}.`));
+    const opened = openCursorWindow(agentWorkspace);
+    if (opened) {
+      console.log(chalk.dim(`    Cursor window opened for ${id}.`));
+    } else {
+      console.log(chalk.yellow(`    Could not open Cursor window automatically for ${id}.`));
+      console.log(chalk.dim(`    Open manually: cursor --new-window "${agentWorkspace}"`));
+    }
 
     console.log('');
     console.log(`  ${chalk.bold('In the new Cursor window:')}`);
@@ -108,17 +118,6 @@ export async function launchCursorLocal(config, root, opts) {
   console.log('');
 }
 
-function filterAgents(config, specificId) {
-  if (specificId) {
-    if (!config.agents[specificId]) {
-      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
-      process.exit(1);
-    }
-    return { [specificId]: config.agents[specificId] };
-  }
-  return config.agents;
-}
-
 function copyToClipboard(text) {
   try {
     if (process.platform === 'darwin') {
@@ -137,10 +136,12 @@ function openCursorWindow(folderPath) {
   try {
     if (process.platform === 'darwin') {
       execSync(`open -na "Cursor" --args "${folderPath}"`, { stdio: 'ignore' });
-      return;
+      return true;
     }
     execSync(`cursor --new-window "${folderPath}"`, { stdio: 'ignore' });
+    return true;
   } catch {}
+  return false;
 }
 
 function isPmLike(agentId, agentDef) {

package/src/commands/accept-turn.js

@@ -0,0 +1,160 @@
+import chalk from 'chalk';
+import { loadProjectContext } from '../lib/config.js';
+import { acceptGovernedTurn } from '../lib/governed-state.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+
+export async function acceptTurnCommand(opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+
+  if (config.protocol_mode !== 'governed') {
+    console.log(chalk.red('The accept-turn command is only available for governed projects.'));
+    console.log(chalk.dim('Legacy projects use: agentxchain release'));
+    process.exit(1);
+  }
+
+  const result = acceptGovernedTurn(root, config, {
+    turnId: opts.turn,
+    resolutionMode: opts.resolution || 'standard',
+  });
+  if (!result.ok) {
+    if (result.error_code?.startsWith('hook_') || result.error_code === 'hook_blocked') {
+      const recovery = deriveRecoveryDescriptor(result.state);
+      const activeTurn = result.state?.current_turn;
+      const hookName = result.hookResults?.blocker?.hook_name
+        || result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name
+        || '(unknown)';
+
+      console.log('');
+      console.log(chalk.yellow(`  ${result.accepted ? 'Turn Accepted, Hook Failure Detected' : 'Turn Acceptance Blocked By Hook'}`));
+      console.log(chalk.dim('  ' + '─'.repeat(44)));
+      console.log('');
+      console.log(`  ${chalk.dim('Turn:')}     ${result.accepted?.turn_id || activeTurn?.turn_id || opts.turn || '(unknown)'}`);
+      console.log(`  ${chalk.dim('Role:')}     ${result.accepted?.role || activeTurn?.assigned_role || '(unknown)'}`);
+      if (result.accepted?.status) {
+        console.log(`  ${chalk.dim('Status:')}   ${result.accepted.status}`);
+      }
+      console.log(`  ${chalk.dim('Hook:')}     ${hookName}`);
+      console.log(`  ${chalk.dim('Error:')}    ${result.error}`);
+      if (recovery) {
+        console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);
+        console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);
+        console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+        if (recovery.detail) {
+          console.log(`  ${chalk.dim('Detail:')}   ${recovery.detail}`);
+        }
+      }
+      console.log('');
+      process.exit(1);
+    }
+
+    if (result.error_code === 'conflict' && result.conflict) {
+      console.log('');
+      console.log(chalk.yellow('  Acceptance Conflict Detected'));
+      console.log(chalk.dim('  ' + '─'.repeat(44)));
+      console.log('');
+      console.log(`  ${chalk.dim('Turn:')}     ${result.conflict.conflicting_turn.turn_id}`);
+      console.log(`  ${chalk.dim('Role:')}     ${result.conflict.conflicting_turn.role}`);
+      console.log(`  ${chalk.dim('Files:')}    ${result.conflict.conflicting_files.join(', ') || '(none)'}`);
+      console.log(`  ${chalk.dim('Overlap:')}  ${(result.conflict.overlap_ratio * 100).toFixed(0)}%`);
+      console.log(`  ${chalk.dim('Suggest:')}  ${result.conflict.suggested_resolution}`);
+      if (result.state?.status === 'blocked') {
+        const recovery = deriveRecoveryDescriptor(result.state);
+        if (recovery) {
+          console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+        }
+      }
+      console.log('');
+      process.exit(1);
+    }
+
+    if (result.error_code === 'lock_timeout') {
+      console.log('');
+      console.log(chalk.yellow('  Acceptance Lock Held'));
+      console.log(chalk.dim('  ' + '─'.repeat(44)));
+      console.log('');
+      console.log(`  ${chalk.dim('Reason:')}   ${result.error}`);
+      console.log(`  ${chalk.dim('Action:')}   Wait for the other acceptance to complete, then retry.`);
+      console.log(`  ${chalk.dim('Note:')}     Stale locks are auto-reclaimed after 30 seconds.`);
+      console.log('');
+      process.exit(1);
+    }
+
+    if (result.error_code === 'protocol_error') {
+      console.log(chalk.red(result.error || 'Protocol error.'));
+      process.exit(1);
+    }
+
+    if (!result.validation) {
+      console.log(chalk.red(result.error || 'Failed to accept turn.'));
+      process.exit(1);
+    }
+
+    const errorClass = result.validation?.error_class || 'unknown';
+    const stage = result.validation?.stage || 'unknown';
+
+    console.log('');
+    console.log(chalk.red(`  Validation failed at stage ${stage}`));
+    console.log(chalk.dim('  ' + '─'.repeat(44)));
+    console.log('');
+    console.log(`  ${chalk.dim('Reason:')}   ${errorClass}`);
+    console.log(`  ${chalk.dim('Owner:')}    human`);
+    console.log(`  ${chalk.dim('Action:')}   Fix staged result and rerun agentxchain accept-turn, or reject with agentxchain reject-turn --reason "..."`);
+    console.log(`  ${chalk.dim('Turn:')}     retained`);
+    if (result.validation?.errors?.length) {
+      for (const err of result.validation.errors) {
+        console.log(`  ${chalk.dim('Detail:')}   ${err}`);
+      }
+    }
+    console.log('');
+    console.log(chalk.dim('Inspect the staged result with: agentxchain validate --mode turn'));
+    process.exit(1);
+  }
+
+  const accepted = result.accepted;
+  const turnId = accepted?.turn_id || result.state?.last_completed_turn_id || '(unknown)';
+
+  console.log('');
+  console.log(chalk.green('  Turn Accepted'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log('');
+  console.log(`  ${chalk.dim('Turn:')}     ${turnId}`);
+  console.log(`  ${chalk.dim('Role:')}     ${accepted?.role || '(unknown)'}`);
+  console.log(`  ${chalk.dim('Status:')}   ${accepted?.status || 'completed'}`);
+  console.log(`  ${chalk.dim('Summary:')}  ${accepted?.summary || '(none)'}`);
+  if (accepted?.proposed_next_role) {
+    console.log(`  ${chalk.dim('Proposed:')} ${accepted.proposed_next_role}`);
+  }
+  if (result.state?.accepted_integration_ref) {
+    console.log(`  ${chalk.dim('Accepted:')} ${result.state.accepted_integration_ref}`);
+  }
+  if (accepted?.cost?.usd != null) {
+    console.log(`  ${chalk.dim('Cost:')}     $${formatUsd(accepted.cost.usd)}`);
+  }
+  console.log('');
+
+  const recovery = deriveRecoveryDescriptor(result.state);
+  if (recovery) {
+    console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);
+    console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);
+    console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
+    console.log(`  ${chalk.dim('Turn:')}     ${recovery.turn_retained ? 'retained' : 'cleared'}`);
+    if (recovery.detail) {
+      console.log(`  ${chalk.dim('Detail:')}   ${recovery.detail}`);
+    }
+  } else if (accepted?.proposed_next_role && accepted.proposed_next_role !== 'human') {
+    console.log(chalk.dim(`  Next: agentxchain resume --role ${accepted.proposed_next_role}`));
+  } else {
+    console.log(chalk.dim('  Next: review state, then run agentxchain resume when ready.'));
+  }
+  console.log('');
+}
+
+function formatUsd(value) {
+  return typeof value === 'number' && !Number.isNaN(value) ? value.toFixed(2) : '0.00';
+}