agentxchain 2.103.0 → 2.105.0

package/dashboard/live-observer.js

@@ -0,0 +1,91 @@
+export const LIVE_OBSERVER_STALE_MS = 15_000;
+
+function formatEventScope(scope) {
+  return scope === 'coordinator' ? 'coordinator' : 'run';
+}
+
+function resolveTimestamp(event) {
+  if (typeof event?.timestamp === 'string' && event.timestamp.trim()) {
+    return event.timestamp;
+  }
+  if (typeof event?.observedAt === 'string' && event.observedAt.trim()) {
+    return `${event.observedAt} (observed)`;
+  }
+  return 'unknown time';
+}
+
+export function buildLiveMeta({
+  connected,
+  lastRefreshAt,
+  lastEvent,
+  scope = 'run',
+  now = Date.now(),
+  staleAfterMs = LIVE_OBSERVER_STALE_MS,
+} = {}) {
+  const refreshMs = typeof lastRefreshAt === 'string' ? new Date(lastRefreshAt).getTime() : Number.NaN;
+  const hasRefresh = Number.isFinite(refreshMs);
+  const scopeLabel = formatEventScope(scope);
+
+  let freshnessState = 'connecting';
+  let freshnessLabel = 'Connecting';
+
+  if (!connected) {
+    freshnessState = 'disconnected';
+    freshnessLabel = 'Disconnected';
+  } else if (hasRefresh) {
+    freshnessState = (now - refreshMs) > staleAfterMs ? 'stale' : 'live';
+    freshnessLabel = freshnessState === 'live' ? 'Live' : 'Stale';
+  }
+
+  const refreshDetail = hasRefresh
+    ? `Updated ${lastRefreshAt}`
+    : connected
+      ? 'Waiting for first dashboard refresh'
+      : 'Waiting for dashboard reconnect';
+
+  const connectionDetail = connected ? 'WebSocket connected' : 'WebSocket disconnected';
+
+  let eventDetail = `No ${scopeLabel} events observed yet`;
+  if (lastEvent) {
+    const repoSuffix = scope === 'coordinator' && lastEvent.repoId ? ` from ${lastEvent.repoId}` : '';
+    eventDetail = `Last ${scopeLabel} event: ${lastEvent.type || 'unknown_event'}${repoSuffix} at ${resolveTimestamp(lastEvent)}`;
+  }
+
+  return {
+    title: scope === 'coordinator' ? 'Live Coordinator Feed' : 'Live Run Feed',
+    freshness_state: freshnessState,
+    freshness_label: freshnessLabel,
+    refresh_detail: refreshDetail,
+    connection_detail: connectionDetail,
+    event_detail: eventDetail,
+  };
+}
+
+export function createLiveEventFromMessage(message, observedAt = new Date().toISOString()) {
+  if (message?.type === 'event') {
+    return {
+      type: message.event?.event_type || 'unknown_event',
+      timestamp: message.event?.timestamp || null,
+      observedAt,
+    };
+  }
+
+  if (message?.type === 'coordinator_event') {
+    return {
+      type: message.event?.event_type || 'unknown_event',
+      timestamp: message.event?.timestamp || null,
+      observedAt,
+      repoId: message.repo_id || message.event?.repo_id || null,
+    };
+  }
+
+  return null;
+}
+
+export function shouldRefreshViewForLiveMessage(viewName, messageType) {
+  if (messageType === 'invalidate') return true;
+  if (messageType === 'coordinator_event') {
+    return viewName === 'cross-repo' || viewName === 'gate';
+  }
+  return false;
+}

package/package.json

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

package/scripts/release-bump.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Release identity creation — replaces raw `npm version <semver>`.
 # Creates version bump commit + annotated tag with fail-closed verification.
-# Usage: bash scripts/release-bump.sh --target-version <semver> [--skip-preflight]
+# Usage: bash scripts/release-bump.sh --target-version <semver> --coauthored-by "Name <email>" [--skip-preflight]
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -10,10 +10,11 @@ REPO_ROOT="$(cd "${CLI_DIR}/.." && pwd)"
 cd "$CLI_DIR"
 
 TARGET_VERSION=""
+COAUTHORED_BY=""
 SKIP_PREFLIGHT=0
 
 usage() {
-  echo "Usage: bash scripts/release-bump.sh --target-version <semver> [--skip-preflight]" >&2
+  echo "Usage: bash scripts/release-bump.sh --target-version <semver> --coauthored-by \"Name <email>\" [--skip-preflight]" >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -32,6 +33,15 @@ while [[ $# -gt 0 ]]; do
       TARGET_VERSION="$2"
       shift 2
       ;;
+    --coauthored-by)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --coauthored-by requires a trailer value like \"Name <email>\"" >&2
+        usage
+        exit 1
+      fi
+      COAUTHORED_BY="$2"
+      shift 2
+      ;;
     --skip-preflight)
       SKIP_PREFLIGHT=1
       shift
@@ -49,6 +59,12 @@ if [[ -z "$TARGET_VERSION" ]]; then
   exit 1
 fi
 
+if [[ -z "$COAUTHORED_BY" ]]; then
+  echo "Error: --coauthored-by is required so the release commit carries the mandated trailer" >&2
+  usage
+  exit 1
+fi
+
 echo "AgentXchain Release Identity: ${TARGET_VERSION}"
 echo "============================================="
 
@@ -280,13 +296,20 @@ echo "  OK: version files and allowed release surfaces staged"
 
 # 9. Create release commit
 echo "[9/10] Creating release commit..."
-git commit -m "${TARGET_VERSION}"
+git commit -m "${TARGET_VERSION}
+
+Co-Authored-By: ${COAUTHORED_BY}"
 RELEASE_SHA=$(git rev-parse HEAD)
 COMMIT_MSG=$(git log -1 --format=%s)
 if [[ "$COMMIT_MSG" != "$TARGET_VERSION" ]]; then
   echo "FAIL: commit message is '${COMMIT_MSG}', expected '${TARGET_VERSION}'" >&2
   exit 1
 fi
+COMMIT_BODY=$(git log -1 --format=%B)
+if [[ "$COMMIT_BODY" != *"Co-Authored-By: ${COAUTHORED_BY}"* ]]; then
+  echo "FAIL: release commit body is missing the required Co-Authored-By trailer" >&2
+  exit 1
+fi
 echo "  OK: commit ${RELEASE_SHA:0:7} with message '${TARGET_VERSION}'"
 
 # 9.5. Inline preflight gate — tests, pack, and docs build must pass before tag

package/scripts/release-preflight.sh

@@ -9,10 +9,12 @@ CLI_DIR="${SCRIPT_DIR}/.."
 cd "$CLI_DIR"
 
 STRICT_MODE=0
+PUBLISH_GATE=0
 TARGET_VERSION="2.0.0"
 
 usage() {
-  echo "Usage: bash scripts/release-preflight.sh [--strict] [--target-version <semver>]" >&2
+  echo "Usage: bash scripts/release-preflight.sh [--strict] [--publish-gate] [--target-version <semver>]" >&2
+  echo "  --publish-gate  Run only release-critical checks (no full test suite). Use in CI publish workflows." >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -21,6 +23,11 @@ while [[ $# -gt 0 ]]; do
       STRICT_MODE=1
       shift
       ;;
+    --publish-gate)
+      PUBLISH_GATE=1
+      STRICT_MODE=1
+      shift
+      ;;
     --target-version)
       if [[ -z "${2:-}" ]]; then
         echo "Error: --target-version requires a semver argument" >&2
@@ -99,49 +106,86 @@ else
 fi
 
 # 3. Tests
-echo "[3/6] Test suite"
-# Install MCP example deps — tests start example servers as subprocesses
-for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../examples/mcp-http-echo-agent"; do
-  if [[ -f "${example_dir}/package.json" && ! -d "${example_dir}/node_modules" ]]; then
-    echo "  Installing deps for $(basename "$example_dir")..."
-    (cd "$example_dir" && env -u NODE_AUTH_TOKEN -u NPM_CONFIG_USERCONFIG npm install --ignore-scripts --userconfig /dev/null 2>&1) || true
+if [[ "$PUBLISH_GATE" -eq 1 ]]; then
+  echo "[3/6] Release-gate tests (targeted subset)"
+  # In publish-gate mode, run only release-critical tests to avoid CI hangs.
+  # The full test suite is a pre-tag responsibility, not a publish-time gate.
+  GATE_TESTS=(
+    test/release-preflight.test.js
+    test/release-docs-content.test.js
+    test/release-notes-gate.test.js
+    test/release-identity-hardening.test.js
+    test/normalized-config.test.js
+    test/conformance.test.js
+  )
+  GATE_TEST_ARGS=()
+  for t in "${GATE_TESTS[@]}"; do
+    if [[ -f "$t" ]]; then
+      GATE_TEST_ARGS+=("$t")
+    fi
+  done
+  if [[ ${#GATE_TEST_ARGS[@]} -eq 0 ]]; then
+    fail "No release-gate test files found"
+  else
+    if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 node --test "${GATE_TEST_ARGS[@]}"; then
+      TEST_STATUS=0
+    else
+      TEST_STATUS=$?
+    fi
+    NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
+    NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
+    if [ "$TEST_STATUS" -eq 0 ] && [ "${NODE_FAIL:-0}" = "0" ]; then
+      pass "${NODE_PASS:-?} release-gate tests passed, 0 failures"
+    else
+      fail "Release-gate tests failed"
+      printf '%s\n' "$TEST_OUTPUT" | tail -20
+    fi
   fi
-done
-if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 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 [ -z "${TEST_PASS:-}" ]; then
-  VITEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed/ { for (i = 1; i <= NF; i++) if ($i ~ /^[0-9]+$/) { print $i; exit } }')"
-  NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
-  if [ -n "${VITEST_PASS:-}" ] && [ -n "${NODE_PASS:-}" ]; then
-    TEST_PASS="$((VITEST_PASS + NODE_PASS))"
-  elif [ -n "${NODE_PASS:-}" ]; then
-    TEST_PASS="${NODE_PASS}"
-  elif [ -n "${VITEST_PASS:-}" ]; then
-    TEST_PASS="${VITEST_PASS}"
+  echo "[3/6] Test suite"
+  # Install MCP example deps — tests start example servers as subprocesses
+  for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../examples/mcp-http-echo-agent"; do
+    if [[ -f "${example_dir}/package.json" && ! -d "${example_dir}/node_modules" ]]; then
+      echo "  Installing deps for $(basename "$example_dir")..."
+      (cd "$example_dir" && env -u NODE_AUTH_TOKEN -u NPM_CONFIG_USERCONFIG npm install --ignore-scripts --userconfig /dev/null 2>&1) || true
+    fi
+  done
+  if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 npm test; then
+    TEST_STATUS=0
+  else
+    TEST_STATUS=$?
   fi
-fi
-if [ -z "${TEST_FAIL:-}" ]; then
-  NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
-  if [ -n "${NODE_FAIL:-}" ]; then
-    TEST_FAIL="${NODE_FAIL}"
-  elif printf '%s\n' "$TEST_OUTPUT" | grep -Eq '^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed'; then
-    TEST_FAIL=0
+  TEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# pass / { print $3 }')"
+  TEST_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^# fail / { print $3 }')"
+  if [ -z "${TEST_PASS:-}" ]; then
+    VITEST_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed/ { for (i = 1; i <= NF; i++) if ($i ~ /^[0-9]+$/) { print $i; exit } }')"
+    NODE_PASS="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ tests / { print $3; exit }')"
+    if [ -n "${VITEST_PASS:-}" ] && [ -n "${NODE_PASS:-}" ]; then
+      TEST_PASS="$((VITEST_PASS + NODE_PASS))"
+    elif [ -n "${NODE_PASS:-}" ]; then
+      TEST_PASS="${NODE_PASS}"
+    elif [ -n "${VITEST_PASS:-}" ]; then
+      TEST_PASS="${VITEST_PASS}"
+    fi
   fi
-fi
-if [ "$TEST_STATUS" -eq 0 ] && [ "${TEST_FAIL:-0}" = "0" ]; then
-  if [ -n "${TEST_PASS:-}" ]; then
-    pass "${TEST_PASS} tests passed, 0 failures"
+  if [ -z "${TEST_FAIL:-}" ]; then
+    NODE_FAIL="$(printf '%s\n' "$TEST_OUTPUT" | awk '/^ℹ fail / { print $3; exit }')"
+    if [ -n "${NODE_FAIL:-}" ]; then
+      TEST_FAIL="${NODE_FAIL}"
+    elif printf '%s\n' "$TEST_OUTPUT" | grep -Eq '^[[:space:]]*Tests[[:space:]]+[0-9]+[[:space:]]+passed'; then
+      TEST_FAIL=0
+    fi
+  fi
+  if [ "$TEST_STATUS" -eq 0 ] && [ "${TEST_FAIL:-0}" = "0" ]; then
+    if [ -n "${TEST_PASS:-}" ]; then
+      pass "${TEST_PASS} tests passed, 0 failures"
+    else
+      pass "npm test passed, 0 failures"
+    fi
   else
-    pass "npm test passed, 0 failures"
+    fail "npm test failed"
+    printf '%s\n' "$TEST_OUTPUT" | tail -20
   fi
-else
-  fail "npm test failed"
-  printf '%s\n' "$TEST_OUTPUT" | tail -20
 fi
 
 # 4. CHANGELOG has target version

package/src/commands/accept-turn.js

@@ -54,7 +54,7 @@ export async function acceptTurnCommand(opts = {}) {
     }
 
     if (result.error_code?.startsWith('hook_') || result.error_code === 'hook_blocked') {
-      const recovery = deriveRecoveryDescriptor(result.state);
+      const recovery = deriveRecoveryDescriptor(result.state, config);
       const activeTurn = result.state?.current_turn;
       const hookName = result.hookResults?.blocker?.hook_name
         || result.hookResults?.results?.find((entry) => entry.hook_name)?.hook_name
@@ -94,7 +94,7 @@ export async function acceptTurnCommand(opts = {}) {
       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);
+        const recovery = deriveRecoveryDescriptor(result.state, config);
         if (recovery) {
           console.log(`  ${chalk.dim('Action:')}   ${recovery.recovery_action}`);
         }
@@ -177,7 +177,7 @@ export async function acceptTurnCommand(opts = {}) {
   }
   console.log('');
 
-  const recovery = deriveRecoveryDescriptor(result.state);
+  const recovery = deriveRecoveryDescriptor(result.state, config);
   if (recovery) {
     console.log(`  ${chalk.dim('Reason:')}   ${recovery.typed_reason}`);
     console.log(`  ${chalk.dim('Owner:')}    ${recovery.owner}`);

package/src/commands/decisions.js

@@ -7,7 +7,14 @@
 import { resolve } from 'path';
 import { existsSync, readFileSync } from 'fs';
 import chalk from 'chalk';
-import { readRepoDecisions, getActiveRepoDecisions, getRepoDecisionById, resolveDecisionAuthority } from '../lib/repo-decisions.js';
+import {
+  readRepoDecisions,
+  getActiveRepoDecisions,
+  getRepoDecisionById,
+  resolveDecisionAuthority,
+  getDecisionAuthorityMetadata,
+  summarizeRepoDecisions,
+} from '../lib/repo-decisions.js';
 
 /**
  * @param {object} opts - { json?: boolean, all?: boolean, show?: string, dir?: string }
@@ -18,6 +25,7 @@ export async function decisionsCommand(opts) {
     console.error(chalk.red('No AgentXchain project found. Run this inside a governed project.'));
     process.exit(1);
   }
+  const config = loadConfig(root);
 
   // ── Show single decision ───────────────────────────────────────────────
   if (opts.show) {
@@ -26,59 +34,68 @@ export async function decisionsCommand(opts) {
       console.error(chalk.red(`Decision ${opts.show} not found in repo decisions.`));
       process.exit(1);
     }
+    const enriched = enrichDecision(dec, config);
     if (opts.json) {
-      console.log(JSON.stringify(dec, null, 2));
+      console.log(JSON.stringify(enriched, null, 2));
       return;
     }
-    console.log(chalk.bold(`Decision ${dec.id}`));
-    console.log(`  Category:    ${dec.category}`);
-    console.log(`  Statement:   ${dec.statement}`);
-    console.log(`  Rationale:   ${dec.rationale}`);
-    console.log(`  Status:      ${formatStatus(dec.status)}`);
-    console.log(`  Role:        ${dec.role || '—'}`);
-    console.log(`  Phase:       ${dec.phase || '—'}`);
-    console.log(`  Run:         ${(dec.run_id || '—').slice(0, 16)}`);
-    console.log(`  Turn:        ${(dec.turn_id || '—').slice(0, 16)}`);
-    console.log(`  Durability:  ${dec.durability || 'repo'}`);
+    console.log(chalk.bold(`Decision ${enriched.id}`));
+    console.log(`  Category:    ${enriched.category || '—'}`);
+    console.log(`  Statement:   ${enriched.statement || '—'}`);
+    console.log(`  Rationale:   ${enriched.rationale || '—'}`);
+    console.log(`  Status:      ${formatStatus(enriched.status)}`);
+    console.log(`  Binding:     ${formatBindingState(enriched.binding_state)}`);
+    console.log(`  Role:        ${enriched.role || '—'}`);
+    console.log(`  Phase:       ${enriched.phase || '—'}`);
+    console.log(`  Run:         ${(enriched.run_id || '—').slice(0, 16)}`);
+    console.log(`  Turn:        ${(enriched.turn_id || '—').slice(0, 16)}`);
+    console.log(`  Durability:  ${enriched.durability || 'repo'}`);
     // Show decision authority if config has it
-    const config = loadConfig(root);
-    if (config && dec.role) {
-      const auth = resolveDecisionAuthority(dec.role, config);
+    if (config && enriched.role) {
+      const auth = resolveDecisionAuthority(enriched.role, config);
       if (auth !== null && !(typeof auth === 'object' && auth.unknown)) {
-        console.log(`  Authority:   ${auth} (${dec.role})`);
+        console.log(`  Authority:   ${auth} (${enriched.role})`);
       }
     }
-    if (dec.overrides) {
-      console.log(`  Supersedes:  ${chalk.yellow(dec.overrides)}`);
+    if (enriched.overrides) {
+      console.log(`  Supersedes:  ${chalk.yellow(enriched.overrides)}`);
     }
-    console.log(`  Created:     ${dec.created_at || '—'}`);
-    if (dec.overridden_by) {
-      console.log(`  Overridden:  ${chalk.yellow(dec.overridden_by)}`);
+    console.log(`  Created:     ${enriched.created_at || '—'}`);
+    if (enriched.overridden_by) {
+      console.log(`  Overridden:  ${chalk.yellow(enriched.overridden_by)}`);
     }
     return;
   }
 
   // ── List decisions ─────────────────────────────────────────────────────
-  const decisions = opts.all ? readRepoDecisions(root) : getActiveRepoDecisions(root);
+  const allDecisions = readRepoDecisions(root);
+  const decisions = opts.all ? allDecisions : getActiveRepoDecisions(root);
+  const enrichedDecisions = decisions.map((dec) => enrichDecision(dec, config));
 
   if (opts.json) {
-    console.log(JSON.stringify(decisions, null, 2));
+    console.log(JSON.stringify(enrichedDecisions, null, 2));
     return;
   }
 
-  if (decisions.length === 0) {
-    console.log(chalk.dim('No repo-level decisions found.'));
-    if (!opts.all) {
+  if (enrichedDecisions.length === 0) {
+    console.log(chalk.dim(opts.all ? 'No repo-level decisions found.' : 'No active repo decisions found.'));
+    if (!opts.all && allDecisions.length > 0) {
       console.log(chalk.dim('Use --all to include overridden decisions.'));
+      return;
     }
     return;
   }
 
   const label = opts.all ? 'Repo Decisions (all)' : 'Active Repo Decisions';
-  console.log(chalk.bold(`${label}: ${decisions.length}`));
+  const summary = buildDecisionListSummary(summarizeRepoDecisions(allDecisions, config), opts.all);
+  console.log(chalk.bold(`${label}: ${enrichedDecisions.length}`));
+  console.log(chalk.dim(summary.binding_line));
+  if (summary.category_line) console.log(chalk.dim(summary.category_line));
+  if (summary.history_line) console.log(chalk.dim(summary.history_line));
+  if (summary.authority_line) console.log(chalk.dim(summary.authority_line));
   console.log('');
 
-  for (const dec of decisions) {
+  for (const dec of enrichedDecisions) {
     const status = formatStatus(dec.status);
     const runShort = (dec.run_id || '').slice(0, 12);
     const override = dec.overridden_by
@@ -86,8 +103,9 @@ export async function decisionsCommand(opts) {
       : dec.overrides
         ? chalk.dim(` ← supersedes ${dec.overrides}`)
         : '';
+    const authority = formatAuthority(dec);
     console.log(`  ${chalk.cyan(dec.id)}  ${status}  ${chalk.dim(dec.category)}  ${dec.statement}${override}`);
-    console.log(`    ${chalk.dim(`by ${dec.role || '?'} in ${runShort || '?'}`)}`);
+    console.log(`    ${chalk.dim(`by ${dec.role || '?'} in ${runShort || '?'}${authority}`)}`);
   }
 }
 
@@ -97,6 +115,57 @@ function formatStatus(status) {
   return chalk.dim(status || '—');
 }
 
+function enrichDecision(decision, config) {
+  const authority = getDecisionAuthorityMetadata(decision.role, config);
+  return {
+    ...decision,
+    binding_state: decision.status === 'active'
+      ? 'binding'
+      : decision.overridden_by
+        ? 'replaced'
+        : 'historical',
+    authority_level: authority?.level ?? null,
+    authority_source: authority?.source ?? null,
+  };
+}
+
+function buildDecisionListSummary(summary, includeAll) {
+  const categories = summary?.operator_summary?.active_categories || [];
+  const highestAuthority = summary?.operator_summary?.highest_active_authority_level;
+  const highestAuthorityRole = summary?.operator_summary?.highest_active_authority_role;
+  const activeCount = summary?.active_count || 0;
+  const overriddenCount = summary?.overridden_count || 0;
+  return {
+    binding_line: `binding now: ${activeCount} active decision${activeCount === 1 ? '' : 's'}`,
+    category_line: categories.length > 0
+      ? `categories: ${categories.join(', ')}`
+      : null,
+    history_line: overriddenCount > 0
+      ? includeAll
+        ? `history: ${overriddenCount} overridden decision${overriddenCount === 1 ? '' : 's'} recorded`
+        : `history: ${overriddenCount} overridden decision${overriddenCount === 1 ? '' : 's'} hidden (use --all)`
+      : null,
+    authority_line: typeof highestAuthority === 'number'
+      ? `highest active authority: ${highestAuthority} (${highestAuthorityRole || 'unknown'})`
+      : null,
+  };
+}
+
+function formatAuthority(decision) {
+  if (typeof decision.authority_level === 'number') {
+    if (decision.authority_source === 'unknown_role') return ' • authority unknown';
+    return ` • authority ${decision.authority_level}`;
+  }
+  return '';
+}
+
+function formatBindingState(bindingState) {
+  if (bindingState === 'binding') return chalk.green('binding');
+  if (bindingState === 'replaced') return chalk.yellow('replaced');
+  if (bindingState === 'historical') return chalk.dim('historical');
+  return chalk.dim('—');
+}
+
 function findProjectRoot(dir) {
   let current = resolve(dir);
   while (current !== '/') {

package/src/commands/diff.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 
 import { findProjectRoot } from '../lib/config.js';
 import { buildExportDiff, resolveExportArtifact } from '../lib/export-diff.js';
+import { buildExportDiffSummary, buildRunDiffSummary } from '../lib/history-diff-summary.js';
 import { buildRunDiff, resolveRunHistoryReference } from '../lib/run-diff.js';
 
 export async function diffCommand(leftRef, rightRef, opts) {
@@ -28,7 +29,10 @@ export async function diffCommand(leftRef, rightRef, opts) {
     }
 
     if (opts.json) {
-      console.log(JSON.stringify(exportDiff.diff, null, 2));
+      console.log(JSON.stringify({
+        ...exportDiff.diff,
+        summary: buildExportDiffSummary(exportDiff.diff),
+      }, null, 2));
       return;
     }
 
@@ -56,7 +60,10 @@ export async function diffCommand(leftRef, rightRef, opts) {
 
   const diff = buildRunDiff(leftResult.entry, rightResult.entry);
   if (opts.json) {
-    console.log(JSON.stringify(diff, null, 2));
+    console.log(JSON.stringify({
+      ...diff,
+      summary: buildRunDiffSummary(diff),
+    }, null, 2));
     return;
   }
 
@@ -65,12 +72,13 @@ export async function diffCommand(leftRef, rightRef, opts) {
 
 function formatRunDiffText(diff) {
   const lines = [];
+  const summary = buildRunDiffSummary(diff);
   lines.push(chalk.bold('Run Diff'));
   lines.push(`${chalk.dim('Left:')}  ${formatRunHeader(diff.left)}`);
   lines.push(`${chalk.dim('Right:')} ${formatRunHeader(diff.right)}`);
+  appendComparisonSummary(lines, summary);
 
   if (!diff.changed) {
-    lines.push('');
     lines.push(chalk.green('No differences.'));
     return lines.join('\n');
   }
@@ -96,12 +104,13 @@ function formatRunDiffText(diff) {
 
 function formatExportDiffText(diff) {
   const lines = [];
+  const summary = buildExportDiffSummary(diff);
   lines.push(chalk.bold('Export Diff'));
   lines.push(`${chalk.dim('Left:')}  ${formatExportHeader(diff.left_ref, diff.left)}`);
   lines.push(`${chalk.dim('Right:')} ${formatExportHeader(diff.right_ref, diff.right)}`);
+  appendComparisonSummary(lines, summary);
 
   if (!diff.changed) {
-    lines.push('');
     lines.push(chalk.green('No differences.'));
     return lines.join('\n');
   }
@@ -158,6 +167,20 @@ function appendRegressionSection(lines, regressions) {
   }
 }
 
+function appendComparisonSummary(lines, summary) {
+  lines.push('');
+  lines.push(chalk.bold('Comparison Summary'));
+  lines.push(`- Outcome: ${summary.outcome}`);
+  lines.push(`- Risk: ${summary.risk_level}`);
+  if (Array.isArray(summary.highlights) && summary.highlights.length > 0) {
+    lines.push('- Highlights:');
+    for (const item of summary.highlights) {
+      lines.push(`  - ${item}`);
+    }
+  }
+  lines.push('');
+}
+
 function listChangeItems(entry) {
   const items = [];
   if (entry.added.length > 0) {