agentxchain 2.13.0 → 2.15.0

package/README.md

@@ -14,6 +14,7 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 - [Adapter reference](https://agentxchain.dev/docs/adapters/)
 - [Protocol spec (v6)](https://agentxchain.dev/docs/protocol/)
 - [Protocol reference](https://agentxchain.dev/docs/protocol-reference/)
+- [Build your own runner](https://agentxchain.dev/docs/build-your-own-runner/)
 - [Why governed multi-agent delivery matters](https://agentxchain.dev/why/)
 
 ## Install
@@ -99,10 +100,10 @@ For initiatives spanning multiple governed repos, use the coordinator to add cro
 npx agentxchain init --governed --template api-service --dir repos/backend -y
 npx agentxchain init --governed --template web-app --dir repos/frontend -y
 agentxchain multi init
-agentxchain multi step --repo backend --role pm
+agentxchain multi step --json
 ```
 
-See the [multi-repo quickstart](https://agentxchain.dev/docs/quickstart#multi-repo-cold-start) for the full cold-start walkthrough.
+If the coordinator enters `blocked`, fix the cause and run `agentxchain multi resume` before continuing with `multi step` or `multi approve-gate`. See the [multi-repo quickstart](https://agentxchain.dev/docs/quickstart#multi-repo-cold-start) for the full cold-start walkthrough.
 
 ### Migrate a legacy project
 
@@ -131,7 +132,10 @@ agentxchain step
 | `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
 | `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
-| `plugin install|list|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
+| `multi init\|status\|step\|resume\|approve-gate\|resync` | Run the multi-repo coordinator lifecycle, including blocked-state recovery via `multi resume` |
+| `intake record\|triage\|approve\|plan\|start\|scan\|resolve` | Continuous-delivery intake: turn delivery signals into governed work items |
+| `intake handoff` | Bridge a planned intake intent to a coordinator workstream for multi-repo execution |
+| `plugin install\|list\|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
 
 ### Shared utilities
 
@@ -196,6 +200,7 @@ TALK.md
 
 - `manual`: implemented
 - `local_cli`: implemented
+- `mcp`: implemented for stdio and streamable HTTP tool-contract dispatch
 - `api_proxy`: implemented for synchronous review-only turns and stages a provider-backed result during `step`
 
 ## Legacy IDE Mode

package/bin/agentxchain.js

@@ -88,6 +88,7 @@ import {
   multiInitCommand,
   multiStatusCommand,
   multiStepCommand,
+  multiResumeCommand,
   multiApproveGateCommand,
   multiResyncCommand,
 } from '../src/commands/multi.js';
@@ -96,6 +97,7 @@ import { intakeTriageCommand } from '../src/commands/intake-triage.js';
 import { intakeApproveCommand } from '../src/commands/intake-approve.js';
 import { intakePlanCommand } from '../src/commands/intake-plan.js';
 import { intakeStartCommand } from '../src/commands/intake-start.js';
+import { intakeHandoffCommand } from '../src/commands/intake-handoff.js';
 import { intakeScanCommand } from '../src/commands/intake-scan.js';
 import { intakeResolveCommand } from '../src/commands/intake-resolve.js';
 import { intakeStatusCommand } from '../src/commands/intake-status.js';
@@ -415,6 +417,12 @@ multiCmd
   .option('-j, --json', 'Output as JSON')
   .action(multiStepCommand);
 
+multiCmd
+  .command('resume')
+  .description('Clear a blocked coordinator state after operator recovery')
+  .option('-j, --json', 'Output as JSON')
+  .action(multiResumeCommand);
+
 multiCmd
   .command('approve-gate')
   .description('Approve a pending phase transition or completion gate')
@@ -449,7 +457,7 @@ intakeCmd
 intakeCmd
   .command('triage')
   .description('Triage a detected intent — set priority, template, charter, and acceptance')
-  .requiredOption('--intent <id>', 'Intent ID to triage')
+  .option('--intent <id>', 'Intent ID to triage')
   .option('--priority <level>', 'Priority level (p0, p1, p2, p3)')
   .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app)')
   .option('--charter <text>', 'Delivery charter text')
@@ -486,10 +494,19 @@ intakeCmd
   .option('-j, --json', 'Output as JSON')
   .action(intakeStartCommand);
 
+intakeCmd
+  .command('handoff')
+  .description('Hand off a planned intent to a coordinator workstream')
+  .option('--intent <id>', 'Intent ID to hand off')
+  .option('--coordinator-root <path>', 'Path to the coordinator workspace root')
+  .option('--workstream <id>', 'Coordinator workstream ID')
+  .option('-j, --json', 'Output as JSON')
+  .action(intakeHandoffCommand);
+
 intakeCmd
   .command('scan')
   .description('Scan a structured source snapshot into intake events')
-  .requiredOption('--source <id>', 'Source type: ci_failure, git_ref_change, schedule')
+  .option('--source <id>', 'Source type: ci_failure, git_ref_change, schedule')
   .option('--file <path>', 'Path to snapshot JSON file')
   .option('--stdin', 'Read snapshot from stdin')
   .option('-j, --json', 'Output as JSON')

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "agentxchain",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
     "agentxchain": "./bin/agentxchain.js"
   },
+  "exports": {
+    ".": "./bin/agentxchain.js",
+    "./runner-interface": "./src/lib/runner-interface.js",
+    "./run-loop": "./src/lib/run-loop.js"
+  },
   "files": [
     "bin/",
     "src/",
@@ -21,6 +26,7 @@
     "preflight:release": "bash scripts/release-preflight.sh",
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
     "postflight:release": "bash scripts/release-postflight.sh",
+    "postflight:downstream": "bash scripts/release-downstream-truth.sh",
     "build:macos": "bun build bin/agentxchain.js --compile --target=bun-darwin-arm64 --outfile=dist/agentxchain-macos-arm64",
     "build:linux": "bun build bin/agentxchain.js --compile --target=bun-linux-x64 --outfile=dist/agentxchain-linux-x64",
     "publish:npm": "bash scripts/publish-npm.sh"

package/scripts/release-downstream-truth.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+# Release downstream truth — run after all downstream surfaces are updated.
+# Verifies: GitHub release exists, Homebrew tap SHA and URL match registry tarball.
+# Usage: bash scripts/release-downstream-truth.sh --target-version <semver>
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CLI_DIR="${SCRIPT_DIR}/.."
+REPO_ROOT="${CLI_DIR}/.."
+cd "$CLI_DIR"
+
+TARGET_VERSION=""
+RETRY_ATTEMPTS="${RELEASE_DOWNSTREAM_RETRY_ATTEMPTS:-3}"
+RETRY_DELAY_SECONDS="${RELEASE_DOWNSTREAM_RETRY_DELAY_SECONDS:-5}"
+
+usage() {
+  echo "Usage: bash scripts/release-downstream-truth.sh --target-version <semver>" >&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
+      ;;
+    *)
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$TARGET_VERSION" ]]; then
+  echo "Error: --target-version is required" >&2
+  usage
+  exit 1
+fi
+
+PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
+CANONICAL_HOMEBREW_FORMULA_URL="${AGENTXCHAIN_DOWNSTREAM_FORMULA_URL:-https://raw.githubusercontent.com/shivamtiwari93/homebrew-tap/main/Formula/agentxchain.rb}"
+
+PASS=0
+FAIL=0
+
+pass() { PASS=$((PASS + 1)); echo "  PASS: $1"; }
+fail() { FAIL=$((FAIL + 1)); echo "  FAIL: $1"; }
+
+echo "AgentXchain v${TARGET_VERSION} Downstream Release Truth"
+echo "====================================="
+echo "Checks downstream surfaces after publish: GitHub release, canonical Homebrew tap."
+echo ""
+
+# --- Check 1: GitHub Release ---
+echo "[1/3] GitHub release"
+if ! command -v gh >/dev/null 2>&1; then
+  fail "gh CLI not available — cannot verify GitHub release"
+else
+  GH_FOUND=false
+  for attempt in $(seq 1 "$RETRY_ATTEMPTS"); do
+    GH_TAG="$(gh release view "v${TARGET_VERSION}" --json tagName -q '.tagName' 2>/dev/null || true)"
+    if [[ "$GH_TAG" == "v${TARGET_VERSION}" ]]; then
+      GH_FOUND=true
+      break
+    fi
+    if [[ "$attempt" -lt "$RETRY_ATTEMPTS" ]]; then
+      echo "  INFO: GitHub release not found (attempt ${attempt}/${RETRY_ATTEMPTS}); retrying in ${RETRY_DELAY_SECONDS}s..."
+      sleep "$RETRY_DELAY_SECONDS"
+    fi
+  done
+  if $GH_FOUND; then
+    pass "GitHub release v${TARGET_VERSION} exists"
+  else
+    fail "GitHub release v${TARGET_VERSION} not found after ${RETRY_ATTEMPTS} attempts"
+  fi
+fi
+
+# --- Get registry tarball URL and compute SHA ---
+echo "[2/3] Canonical Homebrew tap SHA matches registry tarball"
+REGISTRY_TARBALL_URL="$(npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.tarball 2>/dev/null || true)"
+FORMULA_CONTENT="$(curl -fsSL "$CANONICAL_HOMEBREW_FORMULA_URL" 2>/dev/null || true)"
+if [[ -z "$REGISTRY_TARBALL_URL" ]]; then
+  fail "cannot fetch registry tarball URL for ${PACKAGE_NAME}@${TARGET_VERSION}"
+elif [[ -z "$FORMULA_CONTENT" ]]; then
+  fail "cannot fetch canonical Homebrew formula from ${CANONICAL_HOMEBREW_FORMULA_URL}"
+else
+  REGISTRY_SHA="$(curl -sL "$REGISTRY_TARBALL_URL" | shasum -a 256 | awk '{print $1}')"
+  if [[ -z "$REGISTRY_SHA" ]]; then
+    fail "cannot compute SHA256 of registry tarball"
+  else
+    FORMULA_SHA="$(printf '%s\n' "$FORMULA_CONTENT" | grep -E '^\s*sha256\s+"' | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/')"
+    if [[ "$REGISTRY_SHA" == "$FORMULA_SHA" ]]; then
+      pass "canonical Homebrew formula SHA256 matches registry tarball (${REGISTRY_SHA:0:16}...)"
+    else
+      fail "canonical Homebrew formula SHA256 mismatch: formula=${FORMULA_SHA:0:16}... registry=${REGISTRY_SHA:0:16}..."
+    fi
+  fi
+fi
+
+# --- Check 3: Homebrew tap URL matches registry tarball URL ---
+echo "[3/3] Canonical Homebrew tap URL matches registry tarball"
+if [[ -z "$REGISTRY_TARBALL_URL" ]]; then
+  fail "cannot verify URL — registry tarball URL unavailable"
+elif [[ -z "$FORMULA_CONTENT" ]]; then
+  fail "cannot verify URL — canonical Homebrew formula unavailable"
+else
+  FORMULA_URL="$(printf '%s\n' "$FORMULA_CONTENT" | grep -E '^\s*url\s+"' | sed 's/.*url *"\([^"]*\)".*/\1/')"
+  if [[ "$FORMULA_URL" == "$REGISTRY_TARBALL_URL" ]]; then
+    pass "canonical Homebrew formula URL matches registry tarball"
+  else
+    fail "canonical Homebrew formula URL mismatch: formula=${FORMULA_URL} registry=${REGISTRY_TARBALL_URL}"
+  fi
+fi
+
+echo ""
+echo "====================================="
+echo "Results: ${PASS} passed, ${FAIL} failed"
+if [ "$FAIL" -gt 0 ]; then
+  echo "DOWNSTREAM TRUTH FAILED — at least one downstream surface is inconsistent."
+  exit 1
+fi
+
+echo "DOWNSTREAM TRUTH PASSED — all downstream surfaces are consistent."
+exit 0

package/scripts/release-postflight.sh

@@ -1,7 +1,8 @@
 #!/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.
+# the published package can execute its CLI entrypoint, and runner package exports
+# are importable in a clean consumer project.
 # Usage: bash scripts/release-postflight.sh --target-version <semver> [--tag vX.Y.Z]
 set -uo pipefail
 
@@ -15,7 +16,7 @@ RETRY_ATTEMPTS="${RELEASE_POSTFLIGHT_RETRY_ATTEMPTS:-12}"
 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
+echo "Usage: bash scripts/release-postflight.sh --target-version <semver> [--tag vX.Y.Z]" >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -76,6 +77,7 @@ TARBALL_URL=""
 REGISTRY_CHECKSUM=""
 PACKAGE_NAME="$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf8')).name)")"
 PACKAGE_BIN_NAME="$(node -e "const pkg = JSON.parse(require('fs').readFileSync('package.json', 'utf8')); if (typeof pkg.bin === 'string') { console.log(pkg.name); process.exit(0); } const names = Object.keys(pkg.bin || {}); if (names.length !== 1) { console.error('package.json bin must declare exactly one entry'); process.exit(1); } console.log(names[0]);")"
+RUNNER_INTERFACE_VERSION_EXPECTED="$(node --input-type=module -e "import('./src/lib/runner-interface.js').then((mod) => { console.log(mod.RUNNER_INTERFACE_VERSION); }).catch((error) => { console.error(error.message); process.exit(1); });")"
 
 pass() { PASS=$((PASS + 1)); echo "  PASS: $1"; }
 fail() { FAIL=$((FAIL + 1)); echo "  FAIL: $1"; }
@@ -136,6 +138,67 @@ run_install_smoke() {
   return "$version_status"
 }
 
+run_runner_export_smoke() {
+  if [[ -z "$TARBALL_URL" ]]; then
+    echo "registry tarball metadata unavailable for runner export smoke" >&2
+    return 1
+  fi
+
+  local smoke_root
+  local consumer_root
+  local smoke_npmrc
+  local install_status
+  local node_status
+
+  smoke_root="$(mktemp -d "${TMPDIR:-/tmp}/agentxchain-runner-postflight.XXXXXX")"
+  consumer_root="${smoke_root}/consumer"
+  mkdir -p "$consumer_root"
+
+  smoke_npmrc="${smoke_root}/.npmrc"
+  echo "registry=https://registry.npmjs.org/" > "$smoke_npmrc"
+
+  cat > "${consumer_root}/package.json" <<'EOF'
+{
+  "name": "agentxchain-runner-postflight-smoke",
+  "private": true,
+  "type": "module"
+}
+EOF
+
+  (
+    cd "$consumer_root" || exit 1
+    env -u NODE_AUTH_TOKEN NPM_CONFIG_USERCONFIG="$smoke_npmrc" \
+      npm install "$TARBALL_URL" >/dev/null 2>&1
+  )
+  install_status=$?
+  if [[ "$install_status" -ne 0 ]]; then
+    rm -rf "$smoke_root"
+    return "$install_status"
+  fi
+
+  cat > "${consumer_root}/runner-export-smoke.mjs" <<'EOF'
+import { RUNNER_INTERFACE_VERSION, loadContext } from 'agentxchain/runner-interface';
+import { runLoop } from 'agentxchain/run-loop';
+
+if (typeof loadContext !== 'function') {
+  throw new Error('loadContext export missing');
+}
+
+if (typeof runLoop !== 'function') {
+  throw new Error('runLoop export missing');
+}
+
+console.log(RUNNER_INTERFACE_VERSION);
+EOF
+
+  local runner_output
+  runner_output="$(cd "$consumer_root" && node runner-export-smoke.mjs 2>&1)"
+  node_status=$?
+  printf '%s\n' "$runner_output"
+  rm -rf "$smoke_root"
+  return "$node_status"
+}
+
 run_with_retry() {
   local __output_var="$1"
   local description="$2"
@@ -189,17 +252,17 @@ run_with_retry() {
 
 echo "AgentXchain v${TARGET_VERSION} Release Postflight"
 echo "====================================="
-echo "Checks release truth after publish: tag, registry visibility, metadata, and install smoke."
+echo "Checks release truth after publish: tag, registry visibility, metadata, CLI install smoke, and runner export smoke."
 echo ""
 
-echo "[1/5] Git tag"
+echo "[1/6] 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"
+echo "[2/6] 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
@@ -212,7 +275,7 @@ else
   printf '%s\n' "$VERSION_OUTPUT" | tail -20
 fi
 
-echo "[3/5] Registry tarball metadata"
+echo "[3/6] 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
@@ -225,7 +288,7 @@ else
   printf '%s\n' "$TARBALL_OUTPUT" | tail -20
 fi
 
-echo "[4/5] Registry checksum metadata"
+echo "[4/6] 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
@@ -240,7 +303,7 @@ else
   fail "registry did not return checksum metadata"
 fi
 
-echo "[5/5] Install smoke"
+echo "[5/6] Install smoke"
 if run_with_retry EXEC_OUTPUT "install smoke" nonempty "" run_install_smoke; then
   EXEC_VERSION="$(trim_last_line "$EXEC_OUTPUT")"
   if [[ "$EXEC_VERSION" == "$TARGET_VERSION" ]]; then
@@ -253,6 +316,19 @@ else
   printf '%s\n' "$EXEC_OUTPUT" | tail -20
 fi
 
+echo "[6/6] Runner export smoke"
+if run_with_retry RUNNER_EXPORT_OUTPUT "runner export smoke" nonempty "" run_runner_export_smoke; then
+  RUNNER_EXPORT_VERSION="$(trim_last_line "$RUNNER_EXPORT_OUTPUT")"
+  if [[ "$RUNNER_EXPORT_VERSION" == "$RUNNER_INTERFACE_VERSION_EXPECTED" ]]; then
+    pass "published runner exports import with interface ${RUNNER_INTERFACE_VERSION_EXPECTED}"
+  else
+    fail "published runner exports reported interface '${RUNNER_EXPORT_VERSION}', expected '${RUNNER_INTERFACE_VERSION_EXPECTED}'"
+  fi
+else
+  fail "published runner exports install smoke failed"
+  printf '%s\n' "$RUNNER_EXPORT_OUTPUT" | tail -20
+fi
+
 echo ""
 echo "====================================="
 echo "Results: ${PASS} passed, ${FAIL} failed"

package/src/commands/intake-approve.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { approveIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeApproveCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-handoff.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { handoffIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
+
+export async function intakeHandoffCommand(opts) {
+  const root = requireIntakeWorkspaceOrExit(opts);
+
+  if (!opts.intent) {
+    const msg = '--intent <id> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  if (!opts.coordinatorRoot) {
+    const msg = '--coordinator-root <path> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  if (!opts.workstream) {
+    const msg = '--workstream <id> is required';
+    if (opts.json) {
+      console.log(JSON.stringify({ ok: false, error: msg }, null, 2));
+    } else {
+      console.log(chalk.red(msg));
+    }
+    process.exit(1);
+  }
+
+  const result = handoffIntent(root, opts.intent, {
+    coordinatorRoot: opts.coordinatorRoot,
+    workstreamId: opts.workstream,
+  });
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.ok) {
+    console.log('');
+    console.log(chalk.green(`  Handed off intent ${result.intent.intent_id}`));
+    console.log(`  Workstream: ${result.intent.target_workstream.workstream_id}`);
+    console.log(`  Super Run:  ${result.super_run_id}`);
+    console.log(`  Handoff:    ${result.handoff_path}`);
+    console.log(chalk.dim('  Status:     planned → executing (coordinator-managed)'));
+    console.log('');
+  } else {
+    console.log(chalk.red(`  ${result.error}`));
+  }
+
+  process.exit(result.exitCode);
+}

package/src/commands/intake-plan.js

@@ -1,18 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { planIntent } from '../lib/intake.js';
-import { basename } from 'node:path';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakePlanCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-record.js

@@ -1,19 +1,11 @@
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { findProjectRoot } from '../lib/config.js';
 import { recordEvent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeRecordCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   let payload;
   try {

package/src/commands/intake-resolve.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { resolveIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeResolveCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-scan.js

@@ -1,19 +1,11 @@
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { findProjectRoot } from '../lib/config.js';
 import { scanSource, SCAN_SOURCES } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeScanCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.source) {
     const msg = `--source is required. Supported scan sources: ${SCAN_SOURCES.join(', ')}`;

package/src/commands/intake-start.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { startIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeStartCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';

package/src/commands/intake-status.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { intakeStatus } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeStatusCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   const result = intakeStatus(root, opts.intent || null);
 
@@ -72,6 +64,10 @@ function printIntentDetail(intent, event) {
   console.log(`  ${chalk.dim('Charter:')}   ${intent.charter || '—'}`);
   console.log(`  ${chalk.dim('Created:')}   ${intent.created_at}`);
   console.log(`  ${chalk.dim('Updated:')}   ${intent.updated_at}`);
+  if (intent.target_workstream) {
+    console.log(`  ${chalk.dim('Workstream:')} ${intent.target_workstream.workstream_id}`);
+    console.log(`  ${chalk.dim('Super Run:')}  ${intent.target_workstream.super_run_id}`);
+  }
 
   if (intent.acceptance_contract && intent.acceptance_contract.length > 0) {
     console.log('');

package/src/commands/intake-triage.js

@@ -1,17 +1,9 @@
 import chalk from 'chalk';
-import { findProjectRoot } from '../lib/config.js';
 import { triageIntent } from '../lib/intake.js';
+import { requireIntakeWorkspaceOrExit } from './intake-workspace.js';
 
 export async function intakeTriageCommand(opts) {
-  const root = findProjectRoot(process.cwd());
-  if (!root) {
-    if (opts.json) {
-      console.log(JSON.stringify({ ok: false, error: 'agentxchain.json not found' }, null, 2));
-    } else {
-      console.log(chalk.red('agentxchain.json not found'));
-    }
-    process.exit(2);
-  }
+  const root = requireIntakeWorkspaceOrExit(opts);
 
   if (!opts.intent) {
     const msg = '--intent <id> is required';