agentxchain 2.32.0 → 2.34.2

package/bin/agentxchain.js

@@ -75,6 +75,8 @@ import { approveTransitionCommand } from '../src/commands/approve-transition.js'
 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,
@@ -139,6 +141,18 @@ program
   .option('--output <path>', 'Write the export artifact to a file instead of stdout')
   .action(exportCommand);
 
+program
+  .command('restore')
+  .description('Restore governed continuity roots from a run export artifact')
+  .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.32.0",
+  "version": "2.34.2",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

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/restore.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+
+import { loadExportArtifact, verifyExportArtifact } from '../lib/export-verifier.js';
+import { restoreRunExport } from '../lib/restore.js';
+
+export async function restoreCommand(opts) {
+  const input = opts?.input;
+  if (!input) {
+    console.error('Restore requires --input <path>.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const loaded = loadExportArtifact(input, process.cwd());
+  if (!loaded.ok) {
+    console.error(loaded.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const verification = verifyExportArtifact(loaded.artifact);
+  if (!verification.ok) {
+    console.error('Restore input failed export verification:');
+    for (const error of verification.errors.slice(0, 20)) {
+      console.error(`- ${error}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = restoreRunExport(process.cwd(), loaded.artifact);
+  if (!result.ok) {
+    console.error(result.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(chalk.green(`Restored governed continuity state from ${loaded.input}`));
+  console.log(`  ${chalk.dim('Run:')}      ${result.run_id || 'none'}`);
+  console.log(`  ${chalk.dim('Status:')}   ${result.status || 'unknown'}`);
+  console.log(`  ${chalk.dim('Files:')}    ${result.restored_files}`);
+  console.log(`  ${chalk.dim('Next:')}     agentxchain resume`);
+}
+

package/src/lib/export-verifier.js

@@ -3,7 +3,7 @@ import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 
-const SUPPORTED_EXPORT_SCHEMA_VERSION = '0.2';
+const SUPPORTED_EXPORT_SCHEMA_VERSIONS = new Set(['0.2', '0.3']);
 const VALID_FILE_FORMATS = new Set(['json', 'jsonl', 'text']);
 
 function sha256(buffer) {
@@ -51,8 +51,8 @@ function verifyFileEntry(relPath, entry, errors) {
     addError(errors, path, 'sha256 must be a 64-character lowercase hex digest');
   }
 
-  if (typeof entry.content_base64 !== 'string' || entry.content_base64.length === 0) {
-    addError(errors, path, 'content_base64 must be a non-empty string');
+  if (typeof entry.content_base64 !== 'string') {
+    addError(errors, path, 'content_base64 must be a string');
     return;
   }
 
@@ -161,6 +161,29 @@ function verifyRunExport(artifact, errors) {
     addError(errors, 'state', 'must match files..agentxchain/state.json.data');
   }
 
+  if ('workspace' in artifact) {
+    if (!artifact.workspace || typeof artifact.workspace !== 'object' || Array.isArray(artifact.workspace)) {
+      addError(errors, 'workspace', 'must be an object');
+    } else {
+      const git = artifact.workspace.git;
+      if (!git || typeof git !== 'object' || Array.isArray(git)) {
+        addError(errors, 'workspace.git', 'must be an object');
+      } else {
+        if (typeof git.is_repo !== 'boolean') addError(errors, 'workspace.git.is_repo', 'must be a boolean');
+        if (git.head_sha !== null && (typeof git.head_sha !== 'string' || git.head_sha.length === 0)) {
+          addError(errors, 'workspace.git.head_sha', 'must be a string or null');
+        }
+        if (!Array.isArray(git.dirty_paths) || git.dirty_paths.some((entry) => typeof entry !== 'string' || entry.length === 0)) {
+          addError(errors, 'workspace.git.dirty_paths', 'must be an array of non-empty strings');
+        }
+        if (typeof git.restore_supported !== 'boolean') addError(errors, 'workspace.git.restore_supported', 'must be a boolean');
+        if (!Array.isArray(git.restore_blockers) || git.restore_blockers.some((entry) => typeof entry !== 'string' || entry.length === 0)) {
+          addError(errors, 'workspace.git.restore_blockers', 'must be an array of non-empty strings');
+        }
+      }
+    }
+  }
+
   const activeTurnIds = Object.keys(artifact.state.active_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
   const retainedTurnIds = Object.keys(artifact.state.retained_turns || {}).sort((a, b) => a.localeCompare(b, 'en'));
 
@@ -340,8 +363,8 @@ export function verifyExportArtifact(artifact) {
     };
   }
 
-  if (artifact.schema_version !== SUPPORTED_EXPORT_SCHEMA_VERSION) {
-    addError(errors, 'schema_version', `must be "${SUPPORTED_EXPORT_SCHEMA_VERSION}"`);
+  if (!SUPPORTED_EXPORT_SCHEMA_VERSIONS.has(artifact.schema_version)) {
+    addError(errors, 'schema_version', `must be one of ${[...SUPPORTED_EXPORT_SCHEMA_VERSIONS].map((v) => `"${v}"`).join(', ')}`);
   }
 
   if (typeof artifact.export_kind !== 'string') {

package/src/lib/export.js

@@ -1,3 +1,4 @@
+import { execSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
@@ -6,7 +7,7 @@ import { loadProjectContext, loadProjectState } from './config.js';
 import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-config.js';
 import { loadCoordinatorState } from './coordinator-state.js';
 
-const EXPORT_SCHEMA_VERSION = '0.2';
+const EXPORT_SCHEMA_VERSION = '0.3';
 
 const COORDINATOR_INCLUDED_ROOTS = [
   'agentxchain-multi.json',
@@ -18,8 +19,9 @@ const COORDINATOR_INCLUDED_ROOTS = [
   '.agentxchain/multirepo/RECOVERY_REPORT.md',
 ];
 
-const INCLUDED_ROOTS = [
+export const RUN_EXPORT_INCLUDED_ROOTS = [
   'agentxchain.json',
+  'TALK.md',
   '.agentxchain/state.json',
   '.agentxchain/history.jsonl',
   '.agentxchain/decision-ledger.jsonl',
@@ -31,9 +33,41 @@ const INCLUDED_ROOTS = [
   '.agentxchain/transactions/accept',
   '.agentxchain/intake',
   '.agentxchain/multirepo',
+  '.agentxchain/reviews',
+  '.agentxchain/proposed',
+  '.agentxchain/reports',
   '.planning',
 ];
 
+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',
+  '.agentxchain/hook-annotations.jsonl',
+  '.agentxchain/notification-audit.jsonl',
+  '.agentxchain/dispatch',
+  '.agentxchain/staging',
+  '.agentxchain/transactions/accept',
+  '.agentxchain/intake',
+  '.agentxchain/multirepo',
+  '.agentxchain/reviews',
+  '.agentxchain/proposed',
+  '.agentxchain/reports',
+  '.planning',
+];
+
+function pathWithinRoots(relPath, roots) {
+  return roots.some((root) => relPath === root || relPath.startsWith(`${root}/`));
+}
+
+export function isRunRestorePath(relPath) {
+  return pathWithinRoots(relPath, RUN_RESTORE_ROOTS);
+}
+
 function sha256(buffer) {
   return createHash('sha256').update(buffer).digest('hex');
 }
@@ -122,6 +156,95 @@ function countDirectoryFiles(files, prefix) {
   return Object.keys(files).filter((path) => path.startsWith(`${prefix}/`)).length;
 }
 
+function isGitRepo(root) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getGitHeadSha(root) {
+  try {
+    return execSync('git rev-parse HEAD', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function getWorkingTreeChanges(root) {
+  try {
+    const tracked = execSync('git diff --name-only HEAD', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const staged = execSync('git diff --name-only --cached', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const untracked = execSync('git ls-files --others --exclude-standard', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+
+    return [...new Set([tracked, staged, untracked]
+      .flatMap((chunk) => chunk.split('\n').filter(Boolean)))]
+      .sort((a, b) => a.localeCompare(b, 'en'));
+  } catch {
+    return [];
+  }
+}
+
+export function buildRunWorkspaceMetadata(root) {
+  if (!isGitRepo(root)) {
+    return {
+      git: {
+        is_repo: false,
+        head_sha: null,
+        dirty_paths: [],
+        restore_supported: false,
+        restore_blockers: ['Export restore requires a git-backed checkout on the source machine.'],
+      },
+    };
+  }
+
+  const headSha = getGitHeadSha(root);
+  const dirtyPaths = getWorkingTreeChanges(root);
+  const restoreBlockers = [];
+
+  if (!headSha) {
+    restoreBlockers.push('Export restore requires a stable git HEAD in the source checkout.');
+  }
+
+  for (const dirtyPath of dirtyPaths) {
+    if (!isRunRestorePath(dirtyPath)) {
+      restoreBlockers.push(`Dirty path outside governed continuity roots: ${dirtyPath}`);
+    }
+  }
+
+  return {
+    git: {
+      is_repo: true,
+      head_sha: headSha,
+      dirty_paths: dirtyPaths,
+      restore_supported: restoreBlockers.length === 0,
+      restore_blockers: restoreBlockers,
+    },
+  };
+}
+
 export function buildRunExport(startDir = process.cwd()) {
   const context = loadProjectContext(startDir);
   if (!context) {
@@ -141,7 +264,7 @@ export function buildRunExport(startDir = process.cwd()) {
   const { root, rawConfig, config, version } = context;
   const state = loadProjectState(root, config);
 
-  const collectedPaths = [...new Set(INCLUDED_ROOTS.flatMap((relPath) => collectPaths(root, relPath)))]
+  const collectedPaths = [...new Set(RUN_EXPORT_INCLUDED_ROOTS.flatMap((relPath) => collectPaths(root, relPath)))]
     .sort((a, b) => a.localeCompare(b, 'en'));
 
   const files = {};
@@ -181,6 +304,7 @@ export function buildRunExport(startDir = process.cwd()) {
         intake_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/intake/')),
         coordinator_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/multirepo/')),
       },
+      workspace: buildRunWorkspaceMetadata(root),
       files,
       config: rawConfig,
       state,

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/restore.js

@@ -0,0 +1,153 @@
+import { execSync } from 'node:child_process';
+import { Buffer } from 'node:buffer';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import { loadProjectContext } from './config.js';
+import { RUN_RESTORE_ROOTS, isRunRestorePath } from './export.js';
+
+function isGitRepo(root) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getHeadSha(root) {
+  try {
+    return execSync('git rev-parse HEAD', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function getWorkingTreeChanges(root) {
+  try {
+    const tracked = execSync('git diff --name-only HEAD', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const staged = execSync('git diff --name-only --cached', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    const untracked = execSync('git ls-files --others --exclude-standard', {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+
+    return [...new Set([tracked, staged, untracked]
+      .flatMap((chunk) => chunk.split('\n').filter(Boolean)))];
+  } catch {
+    return [];
+  }
+}
+
+function clearRestoreRoots(root) {
+  for (const relPath of RUN_RESTORE_ROOTS) {
+    rmSync(join(root, relPath), { recursive: true, force: true });
+  }
+}
+
+function writeRestoredFiles(root, files) {
+  const relPaths = Object.keys(files).sort((a, b) => a.localeCompare(b, 'en'));
+
+  for (const relPath of relPaths) {
+    if (!isRunRestorePath(relPath)) {
+      throw new Error(`Export contains non-restorable file "${relPath}"`);
+    }
+    const entry = files[relPath];
+    if (!entry || typeof entry.content_base64 !== 'string') {
+      throw new Error(`Export file "${relPath}" is missing content_base64`);
+    }
+    const absPath = join(root, relPath);
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, Buffer.from(entry.content_base64, 'base64'));
+  }
+}
+
+export function restoreRunExport(targetDir, artifact) {
+  if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    return { ok: false, error: 'Restore input must be a JSON export artifact.' };
+  }
+
+  if (artifact.export_kind !== 'agentxchain_run_export') {
+    return { ok: false, error: `Restore only supports run exports in this slice. Got "${artifact.export_kind || 'unknown'}".` };
+  }
+
+  const workspaceGit = artifact.workspace?.git;
+  if (!workspaceGit || typeof workspaceGit !== 'object') {
+    return { ok: false, error: 'Export is missing workspace.git metadata required for restore.' };
+  }
+
+  if (workspaceGit.restore_supported !== true) {
+    const blockers = Array.isArray(workspaceGit.restore_blockers) ? workspaceGit.restore_blockers : [];
+    return {
+      ok: false,
+      error: blockers.length > 0
+        ? `Export cannot be restored safely:\n- ${blockers.join('\n- ')}`
+        : 'Export cannot be restored safely because restore_supported is false.',
+    };
+  }
+
+  const context = loadProjectContext(targetDir);
+  if (!context || context.config?.protocol_mode !== 'governed') {
+    return { ok: false, error: 'Restore target must be a governed project rooted by agentxchain.json.' };
+  }
+
+  if (context.config?.project?.id !== artifact.project?.id) {
+    return {
+      ok: false,
+      error: `Project mismatch: export is "${artifact.project?.id || 'unknown'}" but target is "${context.config?.project?.id || 'unknown'}".`,
+    };
+  }
+
+  if (!isGitRepo(context.root)) {
+    return { ok: false, error: 'Restore target must be a git-backed checkout.' };
+  }
+
+  const targetHead = getHeadSha(context.root);
+  if (!targetHead || targetHead !== workspaceGit.head_sha) {
+    return {
+      ok: false,
+      error: `Target HEAD mismatch: export expects "${workspaceGit.head_sha || 'unknown'}" but target is "${targetHead || 'unknown'}".`,
+    };
+  }
+
+  const dirtyPaths = getWorkingTreeChanges(context.root);
+  if (dirtyPaths.length > 0) {
+    return {
+      ok: false,
+      error: `Restore target must be clean before applying continuity state. Dirty paths: ${dirtyPaths.slice(0, 10).join(', ')}${dirtyPaths.length > 10 ? '...' : ''}`,
+    };
+  }
+
+  const files = artifact.files;
+  if (!files || typeof files !== 'object' || Array.isArray(files) || Object.keys(files).length === 0) {
+    return { ok: false, error: 'Export is missing restorable files.' };
+  }
+
+  clearRestoreRoots(context.root);
+  writeRestoredFiles(context.root, files);
+
+  return {
+    ok: true,
+    root: resolve(context.root),
+    run_id: artifact.summary?.run_id || null,
+    status: artifact.summary?.status || null,
+    restored_files: Object.keys(files).length,
+  };
+}

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