agentxchain 2.33.1 → 2.35.0

package/bin/agentxchain.js

@@ -76,6 +76,7 @@ import { approveCompletionCommand } from '../src/commands/approve-completion.js'
 import { dashboardCommand } from '../src/commands/dashboard.js';
 import { exportCommand } from '../src/commands/export.js';
 import { restoreCommand } from '../src/commands/restore.js';
+import { restartCommand } from '../src/commands/restart.js';
 import { reportCommand } from '../src/commands/report.js';
 import {
   pluginInstallCommand,
@@ -146,6 +147,12 @@ program
   .requiredOption('--input <path>', 'Path to a prior run export artifact')
   .action(restoreCommand);
 
+program
+  .command('restart')
+  .description('Restart a governed run from the last checkpoint (cross-session recovery)')
+  .option('--role <role>', 'Override the next role assignment')
+  .action(restartCommand);
+
 program
   .command('report')
   .description('Render a human-readable governance summary from an export artifact')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.33.1",
+  "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/restart.js

@@ -0,0 +1,222 @@
+/**
+ * agentxchain restart — governed-only command.
+ *
+ * Reconstructs dispatch context from durable checkpoint state and assigns the
+ * next turn. Unlike `resume` (which assumes the caller has session context),
+ * `restart` assumes the caller has NO session context and rebuilds everything
+ * from .agentxchain/session.json + .agentxchain/state.json.
+ *
+ * Use case: terminal died mid-run, machine restarted, new agent session
+ * picking up a long-horizon governed run.
+ */
+
+import chalk from 'chalk';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import {
+  assignGovernedTurn,
+  getActiveTurns,
+  getActiveTurnCount,
+  reactivateGovernedRun,
+  STATE_PATH,
+  HISTORY_PATH,
+  LEDGER_PATH,
+} from '../lib/governed-state.js';
+import { readSessionCheckpoint, SESSION_PATH } from '../lib/session-checkpoint.js';
+
+/**
+ * Generate a session recovery report summarizing the run state
+ * so a new agent session can orient quickly.
+ */
+function generateRecoveryReport(root, state, checkpoint) {
+  const lines = [
+    '# Session Recovery Report',
+    '',
+    `> Auto-generated by \`agentxchain restart\` at ${new Date().toISOString()}`,
+    '',
+    '## Run Identity',
+    '',
+    `- **Run ID**: \`${state.run_id}\``,
+    `- **Project**: \`${state.project_id || 'unknown'}\``,
+    `- **Status**: ${state.status}`,
+    `- **Phase**: ${state.phase || state.current_phase || 'unknown'}`,
+    '',
+  ];
+
+  if (checkpoint) {
+    lines.push(
+      '## Last Checkpoint',
+      '',
+      `- **Session**: \`${checkpoint.session_id}\``,
+      `- **Last turn**: \`${checkpoint.last_turn_id || 'none'}\``,
+      `- **Last role**: ${checkpoint.last_role || 'unknown'}`,
+      `- **Reason**: ${checkpoint.checkpoint_reason}`,
+      `- **Time**: ${checkpoint.last_checkpoint_at}`,
+      '',
+    );
+  }
+
+  // Recent decisions from ledger
+  const ledgerPath = join(root, LEDGER_PATH);
+  if (existsSync(ledgerPath)) {
+    try {
+      const entries = readFileSync(ledgerPath, 'utf8')
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map(l => JSON.parse(l));
+      const recent = entries.slice(-5);
+      if (recent.length > 0) {
+        lines.push('## Recent Decisions', '');
+        for (const entry of recent) {
+          lines.push(`- \`${entry.decision_id || entry.id || 'unknown'}\`: ${entry.summary || entry.description || JSON.stringify(entry).slice(0, 100)}`);
+        }
+        lines.push('');
+      }
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  // Turn history summary
+  const historyPath = join(root, HISTORY_PATH);
+  if (existsSync(historyPath)) {
+    try {
+      const entries = readFileSync(historyPath, 'utf8')
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .map(l => JSON.parse(l));
+      lines.push(`## Turn History`, '', `Total turns completed: ${entries.length}`, '');
+      const recent = entries.slice(-3);
+      if (recent.length > 0) {
+        lines.push('### Last 3 Turns', '');
+        for (const entry of recent) {
+          lines.push(`- **${entry.turn_id}** (${entry.role}, phase: ${entry.phase}): ${entry.status}`);
+        }
+        lines.push('');
+      }
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  lines.push('## Next Steps', '', 'The next turn has been assigned. Check the dispatch bundle for context.', '');
+
+  return lines.join('\n');
+}
+
+export async function restartCommand(opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = context;
+
+  if (config.protocol_mode !== 'governed') {
+    console.log(chalk.red('The restart command is only available for governed projects.'));
+    process.exit(1);
+  }
+
+  // Load state
+  const statePath = join(root, STATE_PATH);
+  if (!existsSync(statePath)) {
+    console.log(chalk.red('No governed run found. Use `agentxchain resume` or `agentxchain run` to start.'));
+    process.exit(1);
+  }
+
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+
+  // Load checkpoint (optional — restart can work without it, just with less context)
+  const checkpoint = readSessionCheckpoint(root);
+
+  // Validate run_id agreement if checkpoint exists
+  if (checkpoint && checkpoint.run_id !== state.run_id) {
+    console.log(chalk.red(`Checkpoint run_id mismatch: session.json has ${checkpoint.run_id}, state.json has ${state.run_id}`));
+    console.log(chalk.dim('The checkpoint is stale. Proceeding with state.json as ground truth.'));
+  }
+
+  // Check terminal states
+  if (state.status === 'completed') {
+    console.log(chalk.red('Run is in terminal state: completed.'));
+    console.log(chalk.dim(`Run ${state.run_id} completed at ${state.completed_at || 'unknown'}.`));
+    process.exit(1);
+  }
+
+  if (state.status === 'failed') {
+    console.log(chalk.red('Run is in terminal state: failed.'));
+    process.exit(1);
+  }
+
+  if (state.status === 'blocked') {
+    console.log(chalk.red('Run is blocked. Resolve the blocker first.'));
+    if (state.blocked_reason) {
+      console.log(chalk.dim(`Reason: ${typeof state.blocked_reason === 'string' ? state.blocked_reason : JSON.stringify(state.blocked_reason)}`));
+    }
+    console.log(chalk.dim('Use `agentxchain step --resume` or resolve the blocker, then try again.'));
+    process.exit(1);
+  }
+
+  // Handle abandoned active turns (assigned but never completed)
+  const activeTurns = getActiveTurns(state);
+  const activeTurnCount = getActiveTurnCount(state);
+  if (activeTurnCount > 0 && state.status === 'active') {
+    const turnIds = Object.keys(activeTurns);
+    console.log(chalk.yellow(`Warning: ${activeTurnCount} turn(s) were assigned but never completed: ${turnIds.join(', ')}`));
+    console.log(chalk.dim('These turns will be available for the next agent to complete.'));
+  }
+
+  // If paused, reactivate
+  if (state.status === 'paused' || state.status === 'idle') {
+    const reactivated = reactivateGovernedRun(root, state, {
+      reason: 'session_restart',
+    });
+    if (!reactivated.ok) {
+      console.log(chalk.red(`Failed to reactivate run: ${reactivated.error}`));
+      process.exit(1);
+    }
+  }
+
+  // Determine role from option or routing
+  const phase = state.phase || state.current_phase;
+  const routing = config.routing?.[phase];
+  const roleId = opts.role || routing?.entry_role || Object.keys(config.roles || {})[0] || null;
+
+  if (!roleId) {
+    console.log(chalk.red('Cannot determine which role to assign. Use --role to specify.'));
+    process.exit(1);
+  }
+
+  // Assign next turn if no active turn exists
+  if (activeTurnCount === 0) {
+    const assignment = assignGovernedTurn(root, config, roleId);
+    if (!assignment.ok) {
+      console.log(chalk.red(`Failed to assign turn: ${assignment.error}`));
+      process.exit(1);
+    }
+
+    console.log(chalk.green(`✓ Restarted run ${state.run_id}`));
+    console.log(chalk.dim(`  Phase: ${phase}`));
+    console.log(chalk.dim(`  Turn: ${assignment.turn?.id || 'assigned'}`));
+    console.log(chalk.dim(`  Role: ${assignment.turn?.role || roleId || 'routing default'}`));
+    if (checkpoint) {
+      console.log(chalk.dim(`  Last checkpoint: ${checkpoint.checkpoint_reason} at ${checkpoint.last_checkpoint_at}`));
+    }
+  } else {
+    console.log(chalk.green(`✓ Reconnected to run ${state.run_id}`));
+    console.log(chalk.dim(`  Phase: ${phase}`));
+    console.log(chalk.dim(`  Active turns: ${Object.keys(activeTurns).join(', ')}`));
+    console.log(chalk.dim('  Complete the active turn(s) with `agentxchain accept-turn` or `agentxchain step`.'));
+  }
+
+  // Write session recovery report
+  const recoveryReport = generateRecoveryReport(root, state, checkpoint);
+  const recoveryPath = join(root, '.agentxchain/SESSION_RECOVERY.md');
+  const recoveryDir = dirname(recoveryPath);
+  if (!existsSync(recoveryDir)) mkdirSync(recoveryDir, { recursive: true });
+  writeFileSync(recoveryPath, recoveryReport);
+  console.log(chalk.dim(`  Recovery report: .agentxchain/SESSION_RECOVERY.md`));
+}

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',
@@ -43,6 +44,7 @@ export const RUN_RESTORE_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/governed-state.js

@@ -35,6 +35,7 @@ import { getMaxConcurrentTurns } from './normalized-config.js';
 import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir, getReviewArtifactPath } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
 import { emitNotifications } from './notification-runner.js';
+import { writeSessionCheckpoint } from './session-checkpoint.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -2483,6 +2484,11 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     }, currentTurn);
   }
 
+  // Session checkpoint — non-fatal, written after every successful acceptance
+  writeSessionCheckpoint(root, updatedState, 'turn_accepted', {
+    role: historyEntry?.role,
+  });
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
@@ -2791,6 +2797,9 @@ export function approvePhaseTransition(root, config) {
 
   writeState(root, updatedState);
 
+  // Session checkpoint — non-fatal
+  writeSessionCheckpoint(root, updatedState, 'phase_approved');
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
@@ -2889,6 +2898,9 @@ export function approveRunCompletion(root, config) {
     requested_by_turn: completion.requested_by_turn || null,
   }, completion.requested_by_turn ? getActiveTurns(state)[completion.requested_by_turn] || null : null);
 
+  // Session checkpoint — non-fatal
+  writeSessionCheckpoint(root, updatedState, 'run_completed');
+
   return {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),

package/src/lib/repo-observer.js

@@ -34,6 +34,7 @@ const OPERATIONAL_PATH_PREFIXES = [
 // These are written exclusively by the orchestrator (§4.1 State Ownership Rule).
 const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/state.json',
+  '.agentxchain/session.json',
   '.agentxchain/history.jsonl',
   '.agentxchain/decision-ledger.jsonl',
   '.agentxchain/lock.json',

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;
   }));

package/src/lib/session-checkpoint.js

@@ -0,0 +1,92 @@
+/**
+ * Session checkpoint — automatic state markers for cross-session restart.
+ *
+ * Writes .agentxchain/session.json at every governance boundary
+ * (turn acceptance, phase transition, gate approval, run completion)
+ * so that `agentxchain restart` can reconstruct dispatch context
+ * without any in-memory session state.
+ *
+ * Design rules:
+ *   - Checkpoint writes are non-fatal: failures log a warning and do not
+ *     block the governance operation.
+ *   - The file is always overwritten, not appended.
+ *   - run_id in session.json must agree with state.json; mismatch is a
+ *     corruption signal.
+ */
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { randomBytes } from 'crypto';
+
+const SESSION_PATH = '.agentxchain/session.json';
+
+/**
+ * Generate a new session ID.
+ */
+function generateSessionId() {
+  return `session_${randomBytes(8).toString('hex')}`;
+}
+
+/**
+ * Read the current session checkpoint, or null if none exists.
+ */
+export function readSessionCheckpoint(root) {
+  const filePath = join(root, SESSION_PATH);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write or update the session checkpoint.
+ *
+ * @param {string} root - project root
+ * @param {object} state - current governed state (from state.json)
+ * @param {string} reason - checkpoint reason (e.g. 'turn_accepted', 'phase_approved', 'run_completed')
+ * @param {object} [extra] - optional extra context fields
+ */
+export function writeSessionCheckpoint(root, state, reason, extra = {}) {
+  const filePath = join(root, SESSION_PATH);
+  try {
+    // Read existing session to preserve session_id across checkpoints in the same session
+    const existing = readSessionCheckpoint(root);
+    const sessionId = (existing && existing.run_id === state.run_id)
+      ? existing.session_id
+      : generateSessionId();
+
+    const currentTurn = state.current_turn || null;
+    const lastTurnId = currentTurn?.id || currentTurn?.turn_id || state.last_completed_turn_id || null;
+    const lastRole = currentTurn?.role || currentTurn?.assigned_role || extra.role || null;
+    const lastPhase = state.current_phase || state.phase || null;
+
+    const checkpoint = {
+      session_id: sessionId,
+      run_id: state.run_id,
+      started_at: existing?.started_at || new Date().toISOString(),
+      last_checkpoint_at: new Date().toISOString(),
+      last_turn_id: lastTurnId,
+      last_phase: lastPhase,
+      last_role: lastRole,
+      run_status: state.status || null,
+      checkpoint_reason: reason,
+      agent_context: {
+        adapter: extra.adapter || null,
+        dispatch_dir: extra.dispatch_dir || null,
+      },
+    };
+
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, JSON.stringify(checkpoint, null, 2) + '\n');
+  } catch (err) {
+    // Non-fatal — warn but do not block governance operations
+    if (process.env.AGENTXCHAIN_DEBUG) {
+      console.error(`[session-checkpoint] Warning: failed to write checkpoint: ${err.message}`);
+    }
+  }
+}
+
+export { SESSION_PATH };