agentxchain 2.33.1 → 2.34.2

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.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/lib/export.js

@@ -43,6 +43,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/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 };