agentxchain 2.49.0 → 2.51.0

package/bin/agentxchain.js

@@ -107,7 +107,7 @@ import { intakeStatusCommand } from '../src/commands/intake-status.js';
 import { demoCommand } from '../src/commands/demo.js';
 import { historyCommand } from '../src/commands/history.js';
 import { eventsCommand } from '../src/commands/events.js';
-import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand } from '../src/commands/schedule.js';
+import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -288,6 +288,12 @@ scheduleCmd
   .option('-j, --json', 'Output as JSON')
   .action(scheduleDaemonCommand);
 
+scheduleCmd
+  .command('status')
+  .description('Show daemon health: running, stale, not_running, or never_started')
+  .option('-j, --json', 'Output as JSON')
+  .action(scheduleStatusCommand);
+
 program
   .command('history')
   .description('Show cross-run history of governed runs in this project')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.49.0",
+  "version": "2.51.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>
+# Usage: bash scripts/release-bump.sh --target-version <semver> [--skip-preflight]
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -10,9 +10,10 @@ REPO_ROOT="$(cd "${CLI_DIR}/.." && pwd)"
 cd "$CLI_DIR"
 
 TARGET_VERSION=""
+SKIP_PREFLIGHT=0
 
 usage() {
-  echo "Usage: bash scripts/release-bump.sh --target-version <semver>" >&2
+  echo "Usage: bash scripts/release-bump.sh --target-version <semver> [--skip-preflight]" >&2
 }
 
 while [[ $# -gt 0 ]]; do
@@ -31,6 +32,10 @@ while [[ $# -gt 0 ]]; do
       TARGET_VERSION="$2"
       shift 2
       ;;
+    --skip-preflight)
+      SKIP_PREFLIGHT=1
+      shift
+      ;;
     *)
       usage
       exit 1
@@ -250,8 +255,67 @@ if [[ "$COMMIT_MSG" != "$TARGET_VERSION" ]]; then
 fi
 echo "  OK: commit ${RELEASE_SHA:0:7} with message '${TARGET_VERSION}'"
 
+# 8.5. Inline preflight gate — tests, pack, and docs build must pass before tag
+if [[ "$SKIP_PREFLIGHT" -eq 1 ]]; then
+  echo ""
+  echo "[8.5/10] Inline preflight gate SKIPPED (--skip-preflight)"
+else
+  echo ""
+  echo "[8.5/10] Running inline preflight gate..."
+  echo "  Running test suite..."
+
+  # Install MCP example deps if needed (same as release-preflight.sh)
+  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
+
+  PREFLIGHT_FAILED=0
+
+  # 8.5a. Full test suite with release env vars
+  if env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 npm test >/dev/null 2>&1; then
+    echo "  OK: test suite passed"
+  else
+    echo "  FAIL: test suite failed" >&2
+    echo "  Re-running with output for diagnostics..." >&2
+    env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 npm test 2>&1 | tail -30 >&2
+    PREFLIGHT_FAILED=1
+  fi
+
+  # 8.5b. npm pack dry-run
+  if npm pack --dry-run >/dev/null 2>&1; then
+    echo "  OK: npm pack --dry-run passed"
+  else
+    echo "  FAIL: npm pack --dry-run failed" >&2
+    PREFLIGHT_FAILED=1
+  fi
+
+  # 8.5c. Docs build
+  if (cd "${REPO_ROOT}/website-v2" && npm run build >/dev/null 2>&1); then
+    echo "  OK: docs build passed"
+  else
+    echo "  FAIL: docs build failed" >&2
+    PREFLIGHT_FAILED=1
+  fi
+
+  if [[ "$PREFLIGHT_FAILED" -eq 1 ]]; then
+    echo "" >&2
+    echo "PREFLIGHT FAILED — release commit created but NOT tagged." >&2
+    echo "  Commit: ${RELEASE_SHA:0:7}" >&2
+    echo "  Fix the failures, amend the commit, and re-run:" >&2
+    echo "    bash scripts/release-bump.sh --target-version ${TARGET_VERSION}" >&2
+    echo "  Or skip preflight if already verified:" >&2
+    echo "    bash scripts/release-bump.sh --target-version ${TARGET_VERSION} --skip-preflight" >&2
+    exit 1
+  fi
+
+  echo "  Inline preflight gate passed — proceeding to tag"
+fi
+
 # 9. Create annotated tag
-echo "[9/9] Creating annotated tag..."
+echo "[9/10] Creating annotated tag..."
 git tag -a "v${TARGET_VERSION}" -m "v${TARGET_VERSION}"
 TAG_SHA=$(git rev-parse "v${TARGET_VERSION}")
 if [[ -z "$TAG_SHA" ]]; then
@@ -276,6 +340,10 @@ echo "Release identity created successfully."
 echo "  Version: ${TARGET_VERSION}"
 echo "  Commit:  ${RELEASE_SHA:0:7}"
 echo "  Tag:     v${TARGET_VERSION}"
+if [[ "$SKIP_PREFLIGHT" -eq 1 ]]; then
+  echo ""
+  echo "WARNING: Inline preflight was skipped. Verify before pushing:"
+  echo "  npm run preflight:release:strict -- --target-version ${TARGET_VERSION}"
+fi
 echo ""
-echo "Next: npm run preflight:release:strict -- --target-version ${TARGET_VERSION}"
-echo "Then: git push origin main --follow-tags"
+echo "Next: git push origin main --follow-tags"

package/scripts/sync-homebrew.sh

@@ -27,6 +27,18 @@ formula_sha() {
   grep -E '^\s*sha256\s+"' "$formula_path" | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/' || true
 }
 
+canonical_tap_matches_target() {
+  local formula_path="$1"
+  local expected_url="$2"
+  local expected_sha="$3"
+  [[ -f "$formula_path" ]] || return 1
+  local remote_url
+  local remote_sha
+  remote_url="$(formula_url "$formula_path")"
+  remote_sha="$(formula_sha "$formula_path")"
+  [[ "$remote_url" == "$expected_url" && "$remote_sha" == "$expected_sha" ]]
+}
+
 usage() {
   echo "Usage: bash scripts/sync-homebrew.sh --target-version <semver> [--push-tap] [--dry-run]" >&2
 }
@@ -207,10 +219,21 @@ if $PUSH_TAP; then
       git add Formula/agentxchain.rb
       git commit -m "agentxchain ${TARGET_VERSION}"
       if ! git push origin HEAD:main; then
-        echo "FAIL: could not push to ${CANONICAL_TAP_REPO}" >&2
-        exit 1
+        echo "  Push rejected by ${CANONICAL_TAP_REPO}; verifying remote state..."
+        git fetch origin main >/dev/null 2>&1 || true
+        REMOTE_FORMULA="$(mktemp "${TMPDIR:-/tmp}/homebrew-tap-remote-formula.XXXXXX")"
+        if git show origin/main:Formula/agentxchain.rb >"$REMOTE_FORMULA" 2>/dev/null \
+          && canonical_tap_matches_target "$REMOTE_FORMULA" "$TARBALL_URL" "$TARBALL_SHA"; then
+          rm -f "$REMOTE_FORMULA"
+          echo "  Canonical tap already matches target after push rejection — treating sync as complete."
+        else
+          rm -f "$REMOTE_FORMULA"
+          echo "FAIL: could not push to ${CANONICAL_TAP_REPO} and remote tap does not match target artifact" >&2
+          exit 1
+        fi
+      else
+        echo "  Pushed to ${CANONICAL_TAP_REPO}"
       fi
-      echo "  Pushed to ${CANONICAL_TAP_REPO}"
     fi
   )
 

package/src/commands/init.js

@@ -65,6 +65,20 @@ function appendAcceptanceHints(baseMatrix, acceptanceHints) {
   return `${baseMatrix}\n\n## Template Guidance\n${hintLines}\n`;
 }
 
+function findGitRoot(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    if (existsSync(join(current, '.git'))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
 // ── Governed init ───────────────────────────────────────────────────────────
 
 const GOVERNED_ROLES = {
@@ -950,6 +964,12 @@ async function initGoverned(opts) {
   if (dir !== process.cwd()) {
     console.log(`    ${chalk.bold(`cd ${targetLabel}`)}`);
   }
+  if (!findGitRoot(dir)) {
+    console.log(`    ${chalk.bold('git init')} ${chalk.dim('# initialize the governed repo')}`);
+  }
+  console.log(`    ${chalk.bold('agentxchain template validate')} ${chalk.dim('# prove the scaffold contract before the first turn')}`);
+  console.log(`    ${chalk.bold('git add -A')} ${chalk.dim('# stage the governed scaffold')}`);
+  console.log(`    ${chalk.bold('git commit -m "initial governed scaffold"')} ${chalk.dim('# checkpoint the starting state')}`);
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);
   console.log(`    ${chalk.bold('agentxchain status')} ${chalk.dim('# inspect phase, gate, and turn state')}`);
   console.log('');

package/src/commands/schedule.js

@@ -2,9 +2,15 @@ import chalk from 'chalk';
 import { loadProjectContext } from '../lib/config.js';
 import {
   SCHEDULE_STATE_PATH,
+  DAEMON_STATE_PATH,
   listSchedules,
   updateScheduleState,
   evaluateScheduleLaunchEligibility,
+  readDaemonState,
+  writeDaemonState,
+  updateDaemonHeartbeat,
+  createDaemonState,
+  evaluateDaemonStatus,
 } from '../lib/run-schedule.js';
 import { executeGovernedRun } from './run.js';
 
@@ -221,6 +227,78 @@ export async function scheduleRunDueCommand(opts) {
   process.exitCode = result.exitCode;
 }
 
+export async function scheduleStatusCommand(opts) {
+  const context = loadScheduleContext();
+  if (!context) return;
+
+  const raw = readDaemonState(context.root);
+  const evaluation = evaluateDaemonStatus(raw);
+
+  if (opts.json) {
+    const output = {
+      ok: evaluation.status === 'running' || evaluation.status === 'never_started',
+      state_file: DAEMON_STATE_PATH,
+      daemon: {
+        status: evaluation.status,
+        pid: raw?.pid ?? null,
+        started_at: raw?.started_at ?? null,
+        last_heartbeat_at: raw?.last_heartbeat_at ?? null,
+        last_cycle_result: raw?.last_cycle_result ?? null,
+        poll_seconds: raw?.poll_seconds ?? null,
+        stale_after_seconds: evaluation.stale_after_seconds ?? null,
+        last_error: raw?.last_error ?? null,
+      },
+    };
+    if (evaluation.warning) output.daemon.warning = evaluation.warning;
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  const statusColors = {
+    running: chalk.green,
+    stale: chalk.yellow,
+    not_running: chalk.red,
+    never_started: chalk.dim,
+  };
+  const colorFn = statusColors[evaluation.status] || chalk.white;
+
+  console.log(chalk.bold('Schedule Daemon Status'));
+  console.log(`  State:     ${colorFn(evaluation.status)}`);
+
+  if (evaluation.status === 'never_started') {
+    console.log(chalk.dim('  No daemon state file found. Run `agentxchain schedule daemon` to start.'));
+    return;
+  }
+
+  if (evaluation.warning) {
+    console.log(chalk.yellow(`  Warning:   ${evaluation.warning}`));
+  }
+
+  if (raw?.pid != null) {
+    console.log(`  PID:       ${raw.pid}`);
+  }
+  if (raw?.started_at) {
+    console.log(`  Started:   ${raw.started_at}`);
+  }
+  if (raw?.last_heartbeat_at) {
+    console.log(`  Heartbeat: ${raw.last_heartbeat_at}`);
+  }
+  if (raw?.last_cycle_result) {
+    const resultColor = raw.last_cycle_result === 'ok' ? chalk.green : chalk.red;
+    console.log(`  Last cycle: ${resultColor(raw.last_cycle_result)}`);
+  }
+  if (raw?.poll_seconds != null) {
+    console.log(`  Poll:      ${raw.poll_seconds}s`);
+  }
+  if (evaluation.status === 'stale') {
+    console.log(chalk.yellow(`  ⚠ Heartbeat is ${evaluation.heartbeat_age_seconds}s old (stale after ${evaluation.stale_after_seconds}s)`));
+  }
+  if (raw?.last_error) {
+    console.log(chalk.red(`  Last error: ${raw.last_error}`));
+  }
+}
+
 export async function scheduleDaemonCommand(opts) {
   const context = loadScheduleContext();
   if (!context) return;
@@ -239,16 +317,31 @@ export async function scheduleDaemonCommand(opts) {
   }
 
   let cycle = 0;
+  const daemonState = createDaemonState(process.pid, pollSeconds, opts.schedule || null, maxCycles);
+
+  try {
+    writeDaemonState(context.root, daemonState);
+  } catch (err) {
+    console.error(chalk.red(`Cannot write daemon state: ${err.message}`));
+    process.exitCode = 1;
+    return;
+  }
+
   if (!opts.json) {
     console.log(chalk.bold('AgentXchain Schedule Daemon'));
     console.log(chalk.dim(`  Poll: ${pollSeconds}s`));
     console.log(chalk.dim(`  State: ${SCHEDULE_STATE_PATH}`));
+    console.log(chalk.dim(`  Health: ${DAEMON_STATE_PATH}`));
     console.log('');
   }
 
   while (true) {
     cycle += 1;
+    daemonState.last_cycle_started_at = new Date().toISOString();
     const result = await runDueSchedules(context, opts);
+
+    updateDaemonHeartbeat(context.root, daemonState, result);
+
     if (opts.json) {
       console.log(JSON.stringify({ cycle, ...result }));
     }

package/src/lib/export.js

@@ -33,6 +33,7 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   '.agentxchain/run-history.jsonl',
   '.agentxchain/events.jsonl',
   '.agentxchain/schedule-state.json',
+  '.agentxchain/schedule-daemon.json',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',
@@ -57,6 +58,7 @@ export const RUN_RESTORE_ROOTS = [
   '.agentxchain/run-history.jsonl',
   '.agentxchain/events.jsonl',
   '.agentxchain/schedule-state.json',
+  '.agentxchain/schedule-daemon.json',
   '.agentxchain/dispatch',
   '.agentxchain/staging',
   '.agentxchain/transactions/accept',

package/src/lib/repo-observer.js

@@ -44,6 +44,7 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/events.jsonl',
   '.agentxchain/notification-audit.jsonl',
   '.agentxchain/schedule-state.json',
+  '.agentxchain/schedule-daemon.json',
   'TALK.md',
 ];
 

package/src/lib/run-schedule.js

@@ -4,7 +4,9 @@ import { safeWriteJson } from './safe-write.js';
 import { loadProjectState } from './config.js';
 
 export const SCHEDULE_STATE_PATH = '.agentxchain/schedule-state.json';
+export const DAEMON_STATE_PATH = '.agentxchain/schedule-daemon.json';
 const SCHEDULE_STATE_SCHEMA_VERSION = '0.1';
+const DAEMON_STATE_SCHEMA_VERSION = '0.1';
 
 function parseIsoTime(value) {
   if (typeof value !== 'string' || !value.trim()) return null;
@@ -158,3 +160,68 @@ export function evaluateScheduleLaunchEligibility(root, config) {
 
   return { ok: false, status, reason: `run_${status}` };
 }
+
+// ── Daemon Health State ─────────────────────────────────────────────────────
+
+export function readDaemonState(root) {
+  const absPath = join(root, DAEMON_STATE_PATH);
+  if (!existsSync(absPath)) return null;
+  try {
+    return JSON.parse(readFileSync(absPath, 'utf8'));
+  } catch {
+    return { _parse_error: true };
+  }
+}
+
+export function writeDaemonState(root, state) {
+  const absPath = join(root, DAEMON_STATE_PATH);
+  mkdirSync(dirname(absPath), { recursive: true });
+  safeWriteJson(absPath, { schema_version: DAEMON_STATE_SCHEMA_VERSION, ...state });
+}
+
+export function updateDaemonHeartbeat(root, daemonState, cycleResult) {
+  const now = new Date().toISOString();
+  const updated = {
+    ...daemonState,
+    last_heartbeat_at: now,
+    last_cycle_finished_at: now,
+    last_cycle_result: cycleResult.ok ? 'ok' : 'error',
+    last_error: cycleResult.ok ? null : (cycleResult.error || 'cycle failed'),
+  };
+  writeDaemonState(root, updated);
+  return updated;
+}
+
+export function createDaemonState(pid, pollSeconds, scheduleId, maxCycles) {
+  const now = new Date().toISOString();
+  return {
+    pid,
+    started_at: now,
+    last_heartbeat_at: now,
+    last_cycle_started_at: null,
+    last_cycle_finished_at: null,
+    last_cycle_result: null,
+    poll_seconds: pollSeconds,
+    schedule_id: scheduleId || null,
+    max_cycles: maxCycles,
+    last_error: null,
+  };
+}
+
+export function evaluateDaemonStatus(daemonState, now = Date.now()) {
+  if (!daemonState) return { status: 'never_started' };
+  if (daemonState._parse_error) return { status: 'not_running', warning: 'state file is malformed' };
+
+  const heartbeat = parseIsoTime(daemonState.last_heartbeat_at);
+  if (heartbeat === null) return { status: 'not_running', warning: 'no heartbeat recorded' };
+
+  const pollSeconds = typeof daemonState.poll_seconds === 'number' ? daemonState.poll_seconds : 60;
+  const staleAfterSeconds = Math.max(pollSeconds * 3, 30);
+  const ageSeconds = (now - heartbeat) / 1000;
+
+  if (ageSeconds > staleAfterSeconds) {
+    return { status: 'stale', stale_after_seconds: staleAfterSeconds, heartbeat_age_seconds: Math.round(ageSeconds) };
+  }
+
+  return { status: 'running', stale_after_seconds: staleAfterSeconds, heartbeat_age_seconds: Math.round(ageSeconds) };
+}