agentxchain 2.34.2 → 2.35.0

package/package.json

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

package/scripts/release-bump.sh

@@ -81,7 +81,7 @@ stage_if_present() {
 }
 
 # 1. Assert only allowed release-surface dirt is present
-echo "[1/7] Checking release-prep tree state..."
+echo "[1/8] Checking release-prep tree state..."
 DISALLOWED_DIRTY=()
 while IFS= read -r status_line; do
   [[ -z "$status_line" ]] && continue
@@ -99,7 +99,7 @@ fi
 echo "  OK: tree contains only allowed release-prep changes"
 
 # 2. Assert not already at target version
-echo "[2/7] Checking current version..."
+echo "[2/8] Checking current version..."
 CURRENT_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json','utf8')).version)")
 if [[ "$CURRENT_VERSION" == "$TARGET_VERSION" ]]; then
   echo "FAIL: package.json is already at ${TARGET_VERSION}. Cannot double-bump." >&2
@@ -108,20 +108,77 @@ fi
 echo "  OK: current version is ${CURRENT_VERSION}, bumping to ${TARGET_VERSION}"
 
 # 3. Assert tag does not already exist
-echo "[3/7] Checking for existing tag..."
+echo "[3/8] Checking for existing tag..."
 if git rev-parse "v${TARGET_VERSION}" >/dev/null 2>&1; then
   echo "FAIL: tag v${TARGET_VERSION} already exists. Delete it first or choose a different version." >&2
   exit 1
 fi
 echo "  OK: tag v${TARGET_VERSION} does not exist"
 
-# 4. Update version files (no git operations)
-echo "[4/7] Updating version files..."
+# 4. Pre-bump version-surface alignment guard
+# Ensures all governed version surfaces already reference the target version
+# BEFORE the bump commit is created. This catches stale drift that would
+# otherwise only be discovered after minting local release identities.
+echo "[4/8] Verifying version-surface alignment for ${TARGET_VERSION}..."
+SURFACE_ERRORS=()
+
+# 4a. CHANGELOG top heading
+CHANGELOG_TOP=$(grep -m1 -E '^## [0-9]+\.[0-9]+\.[0-9]+$' "${REPO_ROOT}/cli/CHANGELOG.md" 2>/dev/null | sed 's/^## //' || true)
+if [[ "$CHANGELOG_TOP" != "$TARGET_VERSION" ]]; then
+  SURFACE_ERRORS+=("CHANGELOG.md top heading is '${CHANGELOG_TOP:-missing}', expected '${TARGET_VERSION}'")
+fi
+
+# 4b. Release notes page exists
+RELEASE_DOC_ID="v${TARGET_VERSION//./-}"
+RELEASE_DOC_PATH="website-v2/docs/releases/${RELEASE_DOC_ID}.mdx"
+if [[ ! -f "${REPO_ROOT}/${RELEASE_DOC_PATH}" ]]; then
+  SURFACE_ERRORS+=("release notes page missing: ${RELEASE_DOC_PATH}")
+fi
+
+# 4c. Docs sidebar links the release page
+if ! grep -q "'releases/${RELEASE_DOC_ID}'" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
+  SURFACE_ERRORS+=("sidebars.ts does not link 'releases/${RELEASE_DOC_ID}'")
+fi
+
+# 4d. Homepage hero badge shows target version
+if ! grep -q "v${TARGET_VERSION}" "${REPO_ROOT}/website-v2/src/pages/index.tsx" 2>/dev/null; then
+  SURFACE_ERRORS+=("homepage index.tsx does not contain 'v${TARGET_VERSION}'")
+fi
+
+# 4e. Conformance capabilities version
+CAPS_VERSION=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('${REPO_ROOT}/.agentxchain-conformance/capabilities.json','utf8')).version)}catch{console.log('missing')}" 2>/dev/null || echo "missing")
+if [[ "$CAPS_VERSION" != "$TARGET_VERSION" ]]; then
+  SURFACE_ERRORS+=("capabilities.json version is '${CAPS_VERSION}', expected '${TARGET_VERSION}'")
+fi
+
+# 4f. Protocol implementor guide example
+if ! grep -q "\"version\": \"${TARGET_VERSION}\"" "${REPO_ROOT}/website-v2/docs/protocol-implementor-guide.mdx" 2>/dev/null; then
+  SURFACE_ERRORS+=("protocol-implementor-guide.mdx does not contain '\"version\": \"${TARGET_VERSION}\"'")
+fi
+
+# 4g. Launch evidence report title
+ESCAPED_VERSION="${TARGET_VERSION//./\\.}"
+if ! grep -qE "^# Launch Evidence Report — AgentXchain v${ESCAPED_VERSION}" "${REPO_ROOT}/.planning/LAUNCH_EVIDENCE_REPORT.md" 2>/dev/null; then
+  SURFACE_ERRORS+=("LAUNCH_EVIDENCE_REPORT.md title does not carry v${TARGET_VERSION}")
+fi
+
+if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
+  echo "FAIL: ${#SURFACE_ERRORS[@]} version-surface(s) not aligned to ${TARGET_VERSION}:" >&2
+  printf '  - %s\n' "${SURFACE_ERRORS[@]}" >&2
+  echo "" >&2
+  echo "Fix these surfaces before running release-bump. The bump script refuses to" >&2
+  echo "create release identity when governed surfaces are stale." >&2
+  exit 1
+fi
+echo "  OK: all 7 governed version surfaces reference ${TARGET_VERSION}"
+
+# 5. Update version files (no git operations)
+echo "[5/8] Updating version files..."
 npm version "$TARGET_VERSION" --no-git-tag-version
 echo "  OK: package.json updated to ${TARGET_VERSION}"
 
-# 5. Stage version files
-echo "[5/7] Staging version files..."
+# 6. Stage version files
+echo "[6/8] Staging version files..."
 git add -- package.json
 if [[ -f package-lock.json ]]; then
   git add -- package-lock.json
@@ -131,8 +188,8 @@ for rel_path in "${ALLOWED_RELEASE_PATHS[@]}"; do
 done
 echo "  OK: version files and allowed release surfaces staged"
 
-# 6. Create release commit
-echo "[6/7] Creating release commit..."
+# 7. Create release commit
+echo "[7/8] Creating release commit..."
 git commit -m "${TARGET_VERSION}"
 RELEASE_SHA=$(git rev-parse HEAD)
 COMMIT_MSG=$(git log -1 --format=%s)
@@ -142,8 +199,8 @@ if [[ "$COMMIT_MSG" != "$TARGET_VERSION" ]]; then
 fi
 echo "  OK: commit ${RELEASE_SHA:0:7} with message '${TARGET_VERSION}'"
 
-# 7. Create annotated tag
-echo "[7/7] Creating annotated tag..."
+# 8. Create annotated tag
+echo "[8/8] 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

package/src/commands/status.js

@@ -1,7 +1,12 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
 import chalk from 'chalk';
 import { loadConfig, loadLock, loadProjectContext, loadProjectState, loadState } from '../lib/config.js';
 import { deriveRecoveryDescriptor } from '../lib/blocked-state.js';
 import { getActiveTurn, getActiveTurnCount, getActiveTurns } from '../lib/governed-state.js';
+import { readSessionCheckpoint } from '../lib/session-checkpoint.js';
+
+const SESSION_RECOVERY_PATH = '.agentxchain/SESSION_RECOVERY.md';
 
 export async function statusCommand(opts) {
   const context = loadProjectContext();
@@ -74,6 +79,7 @@ export async function statusCommand(opts) {
 function renderGovernedStatus(context, opts) {
   const { root, config, version } = context;
   const state = loadProjectState(root, config);
+  const continuity = getContinuityStatus(root, state);
 
   if (opts.json) {
     console.log(JSON.stringify({
@@ -82,6 +88,7 @@ function renderGovernedStatus(context, opts) {
       template: config.template || 'generic',
       config,
       state,
+      continuity,
     }, null, 2));
     return;
   }
@@ -101,6 +108,8 @@ function renderGovernedStatus(context, opts) {
   }
   console.log('');
 
+  renderContinuityStatus(continuity, state);
+
   const activeTurnCount = getActiveTurnCount(state);
   const activeTurns = getActiveTurns(state);
   const singleActiveTurn = getActiveTurn(state);
@@ -238,6 +247,64 @@ function renderGovernedStatus(context, opts) {
   console.log('');
 }
 
+function getContinuityStatus(root, state) {
+  const checkpoint = readSessionCheckpoint(root);
+  const recoveryReportPath = existsSync(join(root, SESSION_RECOVERY_PATH))
+    ? SESSION_RECOVERY_PATH
+    : null;
+
+  if (!checkpoint && !recoveryReportPath) return null;
+
+  const staleCheckpoint = !!(
+    checkpoint?.run_id
+    && state?.run_id
+    && checkpoint.run_id !== state.run_id
+  );
+
+  return {
+    checkpoint,
+    stale_checkpoint: staleCheckpoint,
+    recovery_report_path: recoveryReportPath,
+    restart_recommended: !!state && !['blocked', 'completed', 'failed'].includes(state.status),
+  };
+}
+
+function renderContinuityStatus(continuity, state) {
+  if (!continuity) return;
+
+  console.log(`  ${chalk.dim('Continuity:')}`);
+
+  if (continuity.checkpoint) {
+    const checkpoint = continuity.checkpoint;
+    const checkpointSummary = checkpoint.last_checkpoint_at
+      ? `${checkpoint.checkpoint_reason || 'unknown'} at ${checkpoint.last_checkpoint_at}`
+      : (checkpoint.checkpoint_reason || 'unknown');
+    console.log(`  ${chalk.dim('Session:')}  ${checkpoint.session_id || chalk.dim('unknown')}`);
+    console.log(`  ${chalk.dim('Checkpoint:')} ${checkpointSummary}`);
+    console.log(`  ${chalk.dim('Last turn:')} ${checkpoint.last_turn_id || chalk.dim('none')}`);
+    console.log(`  ${chalk.dim('Last role:')} ${checkpoint.last_role || chalk.dim('unknown')}`);
+    if (continuity.stale_checkpoint) {
+      console.log(
+        `  ${chalk.dim('Warning:')} ${chalk.yellow(
+          `session checkpoint tracks ${checkpoint.run_id}, but state.json tracks ${state?.run_id || 'unknown'}; state.json remains source of truth`
+        )}`
+      );
+    }
+  } else {
+    console.log(`  ${chalk.dim('Checkpoint:')} ${chalk.yellow('No session checkpoint recorded')}`);
+  }
+
+  if (continuity.restart_recommended) {
+    console.log(`  ${chalk.dim('Restart:')} ${chalk.cyan('agentxchain restart')} (rebuild session context from disk)`);
+  }
+
+  if (continuity.recovery_report_path) {
+    console.log(`  ${chalk.dim('Report:')}   ${continuity.recovery_report_path}`);
+  }
+
+  console.log('');
+}
+
 function formatPhase(phase) {
   const colors = { discovery: chalk.blue, build: chalk.green, qa: chalk.yellow, deploy: chalk.magenta, blocked: chalk.red };
   return (colors[phase] || chalk.white)(phase);

package/src/lib/dashboard/state-reader.js

@@ -10,6 +10,7 @@ import { readFileSync, existsSync } from 'fs';
 import { join, normalize } from 'path';
 
 const STATE_FILE = 'state.json';
+const SESSION_FILE = 'session.json';
 const HISTORY_FILE = 'history.jsonl';
 const LEDGER_FILE = 'decision-ledger.jsonl';
 const HOOK_AUDIT_FILE = 'hook-audit.jsonl';
@@ -23,6 +24,7 @@ const BARRIER_LEDGER_FILE = 'barrier-ledger.jsonl';
  */
 export const RESOURCE_MAP = {
   '/api/state': STATE_FILE,
+  '/api/continuity': SESSION_FILE,
   '/api/history': HISTORY_FILE,
   '/api/ledger': LEDGER_FILE,
   '/api/hooks/audit': HOOK_AUDIT_FILE,

package/src/lib/export.js

@@ -23,6 +23,7 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   'agentxchain.json',
   'TALK.md',
   '.agentxchain/state.json',
+  '.agentxchain/session.json',
   '.agentxchain/history.jsonl',
   '.agentxchain/decision-ledger.jsonl',
   '.agentxchain/hook-audit.jsonl',

package/src/lib/report.js

@@ -503,6 +503,30 @@ export function extractWorkflowKitArtifacts(artifact) {
     .sort((a, b) => a.path.localeCompare(b.path, 'en'));
 }
 
+function extractContinuityMetadata(artifact) {
+  const checkpoint = extractFileData(artifact, '.agentxchain/session.json');
+  if (!checkpoint || typeof checkpoint !== 'object') return null;
+
+  const runId = artifact.summary?.run_id || artifact.state?.run_id || null;
+  const staleCheckpoint = !!(
+    checkpoint.run_id
+    && runId
+    && checkpoint.run_id !== runId
+  );
+
+  return {
+    session_id: checkpoint.session_id || null,
+    run_id: checkpoint.run_id || null,
+    started_at: checkpoint.started_at || null,
+    last_checkpoint_at: checkpoint.last_checkpoint_at || null,
+    last_turn_id: checkpoint.last_turn_id || null,
+    last_phase: checkpoint.last_phase || null,
+    last_role: checkpoint.last_role || null,
+    checkpoint_reason: checkpoint.checkpoint_reason || null,
+    stale_checkpoint: staleCheckpoint,
+  };
+}
+
 function buildRunSubject(artifact) {
   const activeTurns = artifact.summary?.active_turn_ids || [];
   const retainedTurns = artifact.summary?.retained_turn_ids || [];
@@ -519,6 +543,7 @@ function buildRunSubject(artifact) {
   const gateSummary = extractGateSummary(artifact);
   const intakeLinks = extractIntakeLinks(artifact);
   const recoverySummary = extractRecoverySummary(artifact);
+  const continuity = extractContinuityMetadata(artifact);
 
   return {
     kind: 'governed_run',
@@ -550,6 +575,7 @@ function buildRunSubject(artifact) {
       gate_summary: gateSummary,
       intake_links: intakeLinks,
       recovery_summary: recoverySummary,
+      continuity,
       workflow_kit_artifacts: extractWorkflowKitArtifacts(artifact),
     },
     artifacts: {
@@ -620,6 +646,7 @@ function buildCoordinatorSubject(artifact) {
       base.hook_summary = extractHookSummary(childExport);
       base.gate_summary = extractGateSummary(childExport);
       base.recovery_summary = extractRecoverySummary(childExport);
+      base.continuity = extractContinuityMetadata(childExport);
       base.blocked_on = childExport.state?.blocked_on || null;
       return base;
     });
@@ -843,6 +870,18 @@ export function formatGovernanceReportText(report) {
       lines.push(`  Turn retained: ${run.recovery_summary.turn_retained == null ? 'n/a' : yesNo(run.recovery_summary.turn_retained)}`);
     }
 
+    if (run.continuity) {
+      lines.push('', 'Continuity:');
+      lines.push(`  Session: ${run.continuity.session_id || 'unknown'}`);
+      lines.push(`  Checkpoint: ${run.continuity.checkpoint_reason || 'unknown'} at ${run.continuity.last_checkpoint_at || 'n/a'}`);
+      lines.push(`  Last turn: ${run.continuity.last_turn_id || 'none'}`);
+      lines.push(`  Last role: ${run.continuity.last_role || 'unknown'}`);
+      lines.push(`  Last phase: ${run.continuity.last_phase || 'unknown'}`);
+      if (run.continuity.stale_checkpoint) {
+        lines.push(`  WARNING: checkpoint tracks run ${run.continuity.run_id}, but export tracks ${run.run_id}`);
+      }
+    }
+
     if (Array.isArray(run.workflow_kit_artifacts) && run.workflow_kit_artifacts.length > 0) {
       lines.push('', `Workflow Artifacts (${run.phase || 'unknown'} phase):`);
       for (const art of run.workflow_kit_artifacts) {
@@ -985,6 +1024,17 @@ export function formatGovernanceReportText(report) {
       if (repo.recovery_summary) {
         repoLines.push(`  Recovery: ${repo.recovery_summary.category || 'unknown'} — ${repo.recovery_summary.typed_reason || 'unknown'} (owner: ${repo.recovery_summary.owner || 'unknown'})`);
       }
+      if (repo.continuity) {
+        repoLines.push('  Continuity:');
+        repoLines.push(`    Session: ${repo.continuity.session_id || 'unknown'}`);
+        repoLines.push(`    Checkpoint: ${repo.continuity.checkpoint_reason || 'unknown'} at ${repo.continuity.last_checkpoint_at || 'n/a'}`);
+        repoLines.push(`    Last turn: ${repo.continuity.last_turn_id || 'none'}`);
+        repoLines.push(`    Last role: ${repo.continuity.last_role || 'unknown'}`);
+        repoLines.push(`    Last phase: ${repo.continuity.last_phase || 'unknown'}`);
+        if (repo.continuity.stale_checkpoint) {
+          repoLines.push(`    WARNING: checkpoint tracks run ${repo.continuity.run_id}, but repo export tracks ${repo.run_id}`);
+        }
+      }
       return repoLines;
     }));
   return lines.join('\n');
@@ -1110,6 +1160,18 @@ export function formatGovernanceReportMarkdown(report) {
       lines.push(`- Turn retained: \`${run.recovery_summary.turn_retained == null ? 'n/a' : yesNo(run.recovery_summary.turn_retained)}\``);
     }
 
+    if (run.continuity) {
+      lines.push('', '## Continuity', '');
+      lines.push(`- Session: \`${run.continuity.session_id || 'unknown'}\``);
+      lines.push(`- Checkpoint: \`${run.continuity.checkpoint_reason || 'unknown'}\` at \`${run.continuity.last_checkpoint_at || 'n/a'}\``);
+      lines.push(`- Last turn: \`${run.continuity.last_turn_id || 'none'}\``);
+      lines.push(`- Last role: \`${run.continuity.last_role || 'unknown'}\``);
+      lines.push(`- Last phase: \`${run.continuity.last_phase || 'unknown'}\``);
+      if (run.continuity.stale_checkpoint) {
+        lines.push(`- **Warning:** checkpoint tracks run \`${run.continuity.run_id}\`, but export tracks \`${run.run_id}\``);
+      }
+    }
+
     if (Array.isArray(run.workflow_kit_artifacts) && run.workflow_kit_artifacts.length > 0) {
       lines.push('', '## Workflow Artifacts', '');
       lines.push(`Phase: \`${run.phase || 'unknown'}\``, '');
@@ -1258,6 +1320,17 @@ export function formatGovernanceReportMarkdown(report) {
     if (repo.recovery_summary) {
       repoLines.push('', '#### Recovery', '', `- Category: \`${repo.recovery_summary.category || 'unknown'}\``, `- Typed reason: \`${repo.recovery_summary.typed_reason || 'unknown'}\``, `- Owner: \`${repo.recovery_summary.owner || 'unknown'}\``, `- Action: \`${repo.recovery_summary.recovery_action || 'n/a'}\``);
     }
+    if (repo.continuity) {
+      repoLines.push('', '#### Continuity', '');
+      repoLines.push(`- Session: \`${repo.continuity.session_id || 'unknown'}\``);
+      repoLines.push(`- Checkpoint: \`${repo.continuity.checkpoint_reason || 'unknown'}\` at \`${repo.continuity.last_checkpoint_at || 'n/a'}\``);
+      repoLines.push(`- Last turn: \`${repo.continuity.last_turn_id || 'none'}\``);
+      repoLines.push(`- Last role: \`${repo.continuity.last_role || 'unknown'}\``);
+      repoLines.push(`- Last phase: \`${repo.continuity.last_phase || 'unknown'}\``);
+      if (repo.continuity.stale_checkpoint) {
+        repoLines.push(`- **Warning:** checkpoint tracks run \`${repo.continuity.run_id}\`, but repo export tracks \`${repo.run_id}\``);
+      }
+    }
     repoLines.push('');
     return repoLines;
   }));