agentxchain 0.8.8 → 2.2.0

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/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';
+}

package/src/commands/approve-completion.js

@@ -0,0 +1,80 @@
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { approveRunCompletion } from '../lib/governed-state.js';
+import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
+
+export async function approveCompletionCommand(opts) {
+  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('approve-completion is only available in governed mode.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+  const state = loadProjectState(root, config);
+
+  if (!state?.pending_run_completion) {
+    console.log(chalk.yellow('No pending run completion to approve.'));
+    if (state?.status === 'completed') {
+      console.log(chalk.dim('  This run is already completed.'));
+    } else if (state?.phase) {
+      console.log(chalk.dim(`  Current phase: ${state.phase}, status: ${state.status}`));
+    }
+    process.exit(1);
+  }
+
+  const pc = state.pending_run_completion;
+  console.log('');
+  console.log(chalk.bold('  Approving Run Completion'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Phase:')}  ${state.phase}`);
+  console.log(`  ${chalk.dim('Gate:')}   ${pc.gate}`);
+  console.log(`  ${chalk.dim('Turn:')}   ${pc.requested_by_turn}`);
+  console.log('');
+
+  const result = approveRunCompletion(root, config);
+
+  if (!result.ok) {
+    if (result.error_code?.startsWith('hook_') || result.error_code === 'hook_blocked') {
+      printGateHookFailure(result, 'run_completion', pc);
+    } else {
+      console.log(chalk.red(`  Failed: ${result.error}`));
+    }
+    process.exit(1);
+  }
+
+  console.log(chalk.green('  \u2713 Run completed'));
+  console.log(chalk.dim(`  Completed at: ${result.state.completed_at}`));
+  console.log('');
+}
+
+function printGateHookFailure(result, gateType, gateInfo) {
+  const recovery = deriveRecoveryDescriptor(result.state);
+  const hookName = result.hookResults?.blocker?.hook_name
+    || result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name
+    || '(unknown)';
+
+  console.log('');
+  console.log(chalk.yellow(`  ${gateType === 'phase_transition' ? 'Phase Transition' : 'Run Completion'} Blocked By Hook`));
+  console.log(chalk.dim('  ' + '-'.repeat(44)));
+  console.log('');
+  console.log(`  ${chalk.dim('Gate:')}     ${gateInfo.gate}`);
+  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}`);
+    }
+  } else {
+    console.log(`  ${chalk.dim('Action:')}   Fix or reconfigure hook "${hookName}", then rerun agentxchain approve-completion`);
+  }
+  console.log('');
+}