agentxchain 2.12.0 → 2.14.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
@@ -91,6 +92,19 @@ agentxchain approve-completion
 
 Default governed scaffolding configures QA as `api_proxy` with `ANTHROPIC_API_KEY`. For a provider-free walkthrough, switch the QA runtime to `manual` before the QA step. If you override the dev runtime, either include `{prompt}` for argv delivery or set `--dev-prompt-transport` explicitly.
 
+### Multi-repo coordination
+
+For initiatives spanning multiple governed repos, use the coordinator to add cross-repo sequencing and shared gates:
+
+```bash
+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
+```
+
+See the [multi-repo quickstart](https://agentxchain.dev/docs/quickstart#multi-repo-cold-start) for the full cold-start walkthrough.
+
 ### Migrate a legacy project
 
 ```bash

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "agentxchain",
-  "version": "2.12.0",
+  "version": "2.14.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,132 @@
+#!/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)")"
+HOMEBREW_FORMULA="${REPO_ROOT}/cli/homebrew/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, 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] Homebrew tap SHA matches registry tarball"
+REGISTRY_TARBALL_URL="$(npm view "${PACKAGE_NAME}@${TARGET_VERSION}" dist.tarball 2>/dev/null || true)"
+if [[ -z "$REGISTRY_TARBALL_URL" ]]; then
+  fail "cannot fetch registry tarball URL for ${PACKAGE_NAME}@${TARGET_VERSION}"
+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"
+  elif [[ ! -f "$HOMEBREW_FORMULA" ]]; then
+    fail "Homebrew formula not found at ${HOMEBREW_FORMULA}"
+  else
+    FORMULA_SHA="$(grep -E '^\s*sha256\s+"' "$HOMEBREW_FORMULA" | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/')"
+    if [[ "$REGISTRY_SHA" == "$FORMULA_SHA" ]]; then
+      pass "Homebrew formula SHA256 matches registry tarball (${REGISTRY_SHA:0:16}...)"
+    else
+      fail "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] Homebrew tap URL matches registry tarball"
+if [[ -z "$REGISTRY_TARBALL_URL" ]]; then
+  fail "cannot verify URL — registry tarball URL unavailable"
+elif [[ ! -f "$HOMEBREW_FORMULA" ]]; then
+  fail "Homebrew formula not found at ${HOMEBREW_FORMULA}"
+else
+  FORMULA_URL="$(grep -E '^\s*url\s+"' "$HOMEBREW_FORMULA" | sed 's/.*url *"\([^"]*\)".*/\1/')"
+  if [[ "$FORMULA_URL" == "$REGISTRY_TARBALL_URL" ]]; then
+    pass "Homebrew formula URL matches registry tarball"
+  else
+    fail "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/lib/coordinator-recovery.js

@@ -66,6 +66,16 @@ function readRepoLocalHistory(repoPath) {
   }
 }
 
+function isAcceptedRepoHistoryEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return false;
+  }
+
+  // Real governed history records the turn outcome in `status` and acceptance
+  // via `accepted_at`. Older coordinator fixtures used `status: "accepted"`.
+  return Boolean(entry.accepted_at) || entry.status === 'accepted';
+}
+
 // ── Divergence Detection ────────────────────────────────────────────────────
 
 /**
@@ -166,7 +176,7 @@ export function detectDivergence(workspacePath, state, config) {
       // Read repo-local history to determine what happened
       const repoHistory = readRepoLocalHistory(repo.resolved_path);
       const turnAccepted = repoHistory.some(
-        e => e?.turn_id === dispatch.repo_turn_id && e?.status === 'accepted'
+        e => e?.turn_id === dispatch.repo_turn_id && isAcceptedRepoHistoryEntry(e)
       );
       const turnRejected = repoHistory.some(
         e => e?.turn_id === dispatch.repo_turn_id && e?.status === 'rejected'
@@ -279,7 +289,7 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
 
     const repoHistory = readRepoLocalHistory(repo.resolved_path);
     const acceptedEntry = repoHistory.find(
-      e => e?.turn_id === dispatch.repo_turn_id && e?.status === 'accepted'
+      e => e?.turn_id === dispatch.repo_turn_id && isAcceptedRepoHistoryEntry(e)
     );
 
     if (acceptedEntry) {

package/src/lib/reference-conformance-adapter.js

@@ -1,7 +1,7 @@
 import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { evaluatePhaseExit } from './gate-evaluator.js';
+import { evaluatePhaseExit, evaluateRunCompletion } from './gate-evaluator.js';
 import {
   approvePhaseTransition,
   approveRunCompletion,
@@ -708,6 +708,51 @@ function executeFixtureOperation(workspace, fixture) {
       };
     }
 
+    case 'evaluate_run_completion': {
+      const state = readJson(join(root, '.agentxchain', 'state.json'));
+      const acceptedTurn = {
+        run_completion_request: fixture.setup.turn_result?.run_completion_request ?? true,
+        verification: fixture.setup.turn_result?.verification || { status: 'pass' },
+      };
+      const result = evaluateRunCompletion({
+        state,
+        config: fixtureConfig,
+        acceptedTurn,
+        root,
+      });
+
+      if (result.action === 'awaiting_human_approval') {
+        return {
+          result: 'success',
+          action: result.action,
+          new_status: 'paused',
+          pending_run_completion: {
+            phase: state.phase,
+            gate: result.gate_id,
+          },
+        };
+      }
+
+      if (result.action === 'complete') {
+        return {
+          result: 'success',
+          action: result.action,
+          new_status: 'completed',
+        };
+      }
+
+      return {
+        result: 'success',
+        action: result.action,
+        state_unchanged: true,
+        reason: result.missing_files.length > 0
+          ? 'requires_files predicate failed'
+          : result.missing_verification
+            ? 'requires_verification_pass predicate failed'
+            : (result.reasons[0] || null),
+      };
+    }
+
     case 'append_decision': {
       const ledgerPath = join(root, '.agentxchain', 'decision-ledger.jsonl');
       const existingLedger = readJsonl(ledgerPath);