agentxchain 2.31.0 → 2.33.1

package/bin/agentxchain.js

@@ -75,6 +75,7 @@ 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 { reportCommand } from '../src/commands/report.js';
 import {
   pluginInstallCommand,
@@ -139,6 +140,12 @@ 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('report')
   .description('Render a human-readable governance summary from an export artifact')

package/dashboard/app.js

@@ -13,6 +13,7 @@ import { render as renderGate } from './components/gate.js';
 import { render as renderInitiative } from './components/initiative.js';
 import { render as renderCrossRepo } from './components/cross-repo.js';
 import { render as renderBlockers } from './components/blockers.js';
+import { render as renderArtifacts } from './components/artifacts.js';
 
 const VIEWS = {
   timeline: { fetch: ['state', 'history', 'audit', 'annotations'], render: renderTimeline },
@@ -23,6 +24,7 @@ const VIEWS = {
   initiative: { fetch: ['coordinatorState', 'coordinatorBarriers', 'barrierLedger', 'coordinatorBlockers'], render: renderInitiative },
   'cross-repo': { fetch: ['coordinatorState', 'coordinatorHistory'], render: renderCrossRepo },
   blockers: { fetch: ['coordinatorBlockers'], render: renderBlockers },
+  artifacts: { fetch: ['workflowKitArtifacts'], render: renderArtifacts },
 };
 
 const API_MAP = {
@@ -37,6 +39,7 @@ const API_MAP = {
   barrierLedger: '/api/coordinator/barrier-ledger',
   coordinatorAudit: '/api/coordinator/hooks/audit',
   coordinatorBlockers: '/api/coordinator/blockers',
+  workflowKitArtifacts: '/api/workflow-kit-artifacts',
 };
 
 const viewState = {

package/dashboard/components/artifacts.js

@@ -0,0 +1,113 @@
+/**
+ * Workflow-Kit Artifacts view — renders live workflow-kit artifact status.
+ *
+ * Pure render function: takes data from /api/workflow-kit-artifacts, returns HTML.
+ * Ownership resolution and file-existence checks are server-side. This view
+ * renders the snapshot without reimplementing any logic.
+ *
+ * See: WORKFLOW_KIT_DASHBOARD_SPEC.md
+ */
+
+function esc(str) {
+  if (!str) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function badge(label, color = 'var(--text-dim)') {
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(label)}</span>`;
+}
+
+function statusIndicator(exists) {
+  if (exists) {
+    return `<span style="color:var(--green);font-weight:600" title="File exists">✓ exists</span>`;
+  }
+  return `<span style="color:var(--red);font-weight:600" title="File missing">✗ missing</span>`;
+}
+
+function renderArtifactRow(artifact) {
+  const isMissingRequired = !artifact.exists && artifact.required;
+  const rowStyle = isMissingRequired
+    ? ' style="border-left:3px solid var(--red)"'
+    : '';
+
+  return `<tr${rowStyle}>
+    <td class="mono">${esc(artifact.path)}</td>
+    <td>${artifact.required ? badge('required', 'var(--yellow)') : badge('optional', 'var(--text-dim)')}</td>
+    <td>${artifact.semantics ? `<span class="mono">${esc(artifact.semantics)}</span>` : '<span style="color:var(--text-dim)">—</span>'}</td>
+    <td>${artifact.owned_by ? esc(artifact.owned_by) : '<span style="color:var(--text-dim)">—</span>'}</td>
+    <td>${artifact.owner_resolution ? badge(artifact.owner_resolution, artifact.owner_resolution === 'explicit' ? 'var(--accent)' : 'var(--text-dim)') : '—'}</td>
+    <td>${statusIndicator(artifact.exists)}</td>
+  </tr>`;
+}
+
+export function render({ workflowKitArtifacts }) {
+  if (!workflowKitArtifacts) {
+    return `<div class="placeholder"><h2>Workflow Artifacts</h2><p>No workflow artifact data available. Ensure a governed run is active.</p></div>`;
+  }
+
+  if (workflowKitArtifacts.ok === false) {
+    const hint = workflowKitArtifacts.code === 'config_missing' || workflowKitArtifacts.code === 'state_missing'
+      ? ' Run <code>agentxchain init --governed</code> to get started.'
+      : '';
+    return `<div class="placeholder"><h2>Workflow Artifacts</h2><p>${esc(workflowKitArtifacts.error || 'Failed to load workflow artifact data.')}${hint}</p></div>`;
+  }
+
+  const data = workflowKitArtifacts;
+  const artifacts = data.artifacts;
+
+  // No workflow_kit configured
+  if (artifacts === null) {
+    return `<div class="placeholder"><h2>Workflow Artifacts</h2><p>No <code>workflow_kit</code> configured in <code>agentxchain.json</code>. Add a <code>workflow_kit</code> section to track phase artifacts.</p></div>`;
+  }
+
+  // Phase has no artifacts
+  if (!Array.isArray(artifacts) || artifacts.length === 0) {
+    return `<div class="placeholder"><h2>Workflow Artifacts</h2><p>Current phase <strong>${esc(data.phase || 'unknown')}</strong> has no workflow-kit artifacts defined.</p></div>`;
+  }
+
+  const missingRequired = artifacts.filter((a) => a.required && !a.exists).length;
+  const totalExists = artifacts.filter((a) => a.exists).length;
+
+  let html = `<div class="artifacts-view">`;
+
+  // Header
+  html += `<div class="run-header"><div class="run-meta">`;
+  if (data.phase) {
+    html += `<span class="phase-label">Phase: <strong>${esc(data.phase)}</strong></span>`;
+  }
+  html += `<span class="turn-count">${artifacts.length} artifact${artifacts.length !== 1 ? 's' : ''}</span>`;
+  html += `<span class="turn-count">${totalExists}/${artifacts.length} present</span>`;
+  if (missingRequired > 0) {
+    html += badge(`${missingRequired} missing required`, 'var(--red)');
+  }
+  html += `</div></div>`;
+
+  // Table
+  html += `<div class="section"><h3>Workflow-Kit Artifacts</h3>
+    <table class="data-table">
+      <thead>
+        <tr>
+          <th>Path</th>
+          <th>Required</th>
+          <th>Semantics</th>
+          <th>Owner</th>
+          <th>Resolution</th>
+          <th>Status</th>
+        </tr>
+      </thead>
+      <tbody>`;
+
+  for (const artifact of artifacts) {
+    html += renderArtifactRow(artifact);
+  }
+
+  html += `</tbody></table></div>`;
+
+  html += `</div>`;
+  return html;
+}

package/dashboard/index.html

@@ -382,6 +382,7 @@
     <a href="#blocked">Blocked</a>
     <a href="#gate">Gates</a>
     <a href="#blockers">Blockers</a>
+    <a href="#artifacts">Artifacts</a>
   </nav>
   <main id="view-container">
     <div class="placeholder">

package/package.json

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

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/dashboard/bridge-server.js

@@ -18,6 +18,7 @@ import { readResource } from './state-reader.js';
 import { FileWatcher } from './file-watcher.js';
 import { approvePendingDashboardGate } from './actions.js';
 import { readCoordinatorBlockerSnapshot } from './coordinator-blockers.js';
+import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -279,6 +280,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       return;
     }
 
+    if (pathname === '/api/workflow-kit-artifacts') {
+      const result = readWorkflowKitArtifacts(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);

package/src/lib/dashboard/workflow-kit-artifacts.js

@@ -0,0 +1,131 @@
+/**
+ * Workflow-kit artifact status — computed dashboard endpoint.
+ *
+ * Reads agentxchain.json config and .agentxchain/state.json to derive
+ * current-phase workflow-kit artifact status for live dashboard observation.
+ *
+ * Per DEC-WK-REPORT-002: ownership resolution uses explicit owned_by first,
+ * then falls back to routing[phase].entry_role.
+ *
+ * See: WORKFLOW_KIT_DASHBOARD_SPEC.md
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { loadConfig } from '../config.js';
+import { readJsonFile } from './state-reader.js';
+
+/**
+ * Read workflow-kit artifact status for the current phase.
+ *
+ * @param {string} workspacePath — project root (parent of .agentxchain/)
+ * @returns {{ ok: boolean, status: number, body: object }}
+ */
+export function readWorkflowKitArtifacts(workspacePath) {
+  const configResult = loadConfig(workspacePath);
+  if (!configResult) {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'config_missing',
+        error: 'Project config not found. Run `agentxchain init --governed` first.',
+      },
+    };
+  }
+
+  const agentxchainDir = join(workspacePath, '.agentxchain');
+  const state = readJsonFile(agentxchainDir, 'state.json');
+  if (!state) {
+    return {
+      ok: false,
+      status: 404,
+      body: {
+        ok: false,
+        code: 'state_missing',
+        error: 'Run state not found. Run `agentxchain init --governed` first.',
+      },
+    };
+  }
+
+  const config = configResult.config;
+  const phase = state.phase || null;
+
+  if (!config.workflow_kit) {
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        ok: true,
+        phase,
+        artifacts: null,
+      },
+    };
+  }
+
+  if (!phase) {
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        ok: true,
+        phase: null,
+        artifacts: [],
+      },
+    };
+  }
+
+  const phaseConfig = config.workflow_kit.phases?.[phase];
+  if (!phaseConfig) {
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        ok: true,
+        phase,
+        artifacts: [],
+      },
+    };
+  }
+
+  const artifacts = Array.isArray(phaseConfig.artifacts) ? phaseConfig.artifacts : [];
+  if (artifacts.length === 0) {
+    return {
+      ok: true,
+      status: 200,
+      body: {
+        ok: true,
+        phase,
+        artifacts: [],
+      },
+    };
+  }
+
+  const entryRole = config.routing?.[phase]?.entry_role || null;
+
+  const result = artifacts
+    .filter((a) => a && typeof a.path === 'string')
+    .map((a) => {
+      const hasExplicitOwner = typeof a.owned_by === 'string' && a.owned_by.length > 0;
+      return {
+        path: a.path,
+        required: a.required !== false,
+        semantics: a.semantics || null,
+        owned_by: hasExplicitOwner ? a.owned_by : entryRole,
+        owner_resolution: hasExplicitOwner ? 'explicit' : 'entry_role',
+        exists: existsSync(join(workspacePath, a.path)),
+      };
+    })
+    .sort((a, b) => a.path.localeCompare(b.path, 'en'));
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      ok: true,
+      phase,
+      artifacts: result,
+    },
+  };
+}

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,40 @@ 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/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 +155,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 +263,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 +303,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/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,
+  };
+}