agentxchain 2.8.0 → 2.9.0

package/README.md

@@ -110,7 +110,7 @@ agentxchain step
 | `approve-completion` | Approve a pending human-gated run completion |
 | `validate` | Validate governed kickoff wiring, a staged turn, or both |
 | `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
-| `dashboard` | Open the read-only governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives |
+| `dashboard` | Open the local governance dashboard in your browser for repo-local runs or multi-repo coordinator initiatives, including pending gate approvals |
 | `plugin install|list|remove` | Install, inspect, or remove governed hook plugins backed by `agentxchain-plugin.json` manifests |
 
 ### Shared utilities

package/dashboard/app.js

@@ -53,6 +53,8 @@ const viewState = {
 
 let activeViewName = null;
 let activeViewData = null;
+let dashboardSession = null;
+let actionInFlight = false;
 
 function escapeHtml(str) {
   if (str == null) return '';
@@ -77,6 +79,15 @@ async function fetchData(keys) {
   return results;
 }
 
+async function loadSession() {
+  try {
+    const res = await fetch('/api/session');
+    dashboardSession = res.ok ? await res.json() : null;
+  } catch {
+    dashboardSession = null;
+  }
+}
+
 function currentView() {
   return (location.hash || '#timeline').slice(1);
 }
@@ -126,6 +137,20 @@ function renderView(viewName, data) {
   container.innerHTML = view.render(buildRenderData(viewName, data));
 }
 
+function setActionBanner(message, tone = 'info') {
+  const banner = document.getElementById('action-banner');
+  if (!banner) return;
+
+  if (!message) {
+    banner.textContent = '';
+    banner.className = 'action-banner';
+    return;
+  }
+
+  banner.textContent = message;
+  banner.className = `action-banner visible ${tone === 'error' ? 'error' : tone === 'success' ? 'success' : ''}`.trim();
+}
+
 async function loadView(viewName, { refresh = true } = {}) {
   const view = VIEWS[viewName];
   if (!view) {
@@ -264,6 +289,55 @@ document.addEventListener('click', (event) => {
   turnCard.toggleAttribute('data-expanded');
 });
 
+document.addEventListener('click', async (event) => {
+  const button = event.target.closest('[data-dashboard-action="approve-gate"]');
+  if (!button) return;
+
+  event.preventDefault();
+  if (actionInFlight) return;
+
+  if (!dashboardSession?.mutation_token) {
+    setActionBanner('Dashboard action token unavailable. Reload the page and try again.', 'error');
+    return;
+  }
+
+  const originalLabel = button.textContent;
+  const pendingLabel = button.dataset.actionLabel || 'Approve Gate';
+  actionInFlight = true;
+  button.disabled = true;
+  button.textContent = `${pendingLabel}...`;
+  setActionBanner('Submitting gate approval...', 'info');
+
+  try {
+    const res = await fetch('/api/actions/approve-gate', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-AgentXchain-Token': dashboardSession.mutation_token,
+      },
+      body: JSON.stringify({}),
+    });
+    const payload = await res.json().catch(() => ({
+      ok: false,
+      error: `Dashboard action failed with HTTP ${res.status}.`,
+    }));
+
+    if (!res.ok || payload.ok === false) {
+      setActionBanner(payload.error || `Dashboard action failed with HTTP ${res.status}.`, 'error');
+      return;
+    }
+
+    setActionBanner(payload.message || 'Gate approved.', 'success');
+    await loadView(currentView());
+  } catch (error) {
+    setActionBanner(error?.message || 'Dashboard action failed.', 'error');
+  } finally {
+    actionInFlight = false;
+    button.disabled = false;
+    button.textContent = originalLabel;
+  }
+});
+
 // ── Copy to clipboard ────────────────────────────────────────────────────
 
 document.addEventListener('click', (event) => {
@@ -299,7 +373,7 @@ function fallbackSelect(el) {
 
 // ── Init ───────────────────────────────────────────────────────────────────
 
-pickInitialView().finally(() => {
+Promise.all([pickInitialView(), loadSession()]).finally(() => {
   updateNav();
   connect();
 });

package/dashboard/components/gate.js

@@ -2,7 +2,7 @@
  * Gate Review view — renders pending phase transitions and run completion gates.
  *
  * Pure render function: takes data, returns HTML string. Testable in Node.js.
- * Per DEC-DASH-002: read-only. Shows the exact CLI command to approve, no buttons.
+ * Shows a narrow local approve action plus the exact CLI fallback command.
  */
 
 function esc(str) {
@@ -114,6 +114,17 @@ function renderList(title, items, formatter = (item) => item) {
   </div>`;
 }
 
+function renderApproveControls({ buttonLabel, cliCommand }) {
+  return `
+      <div class="gate-controls">
+        <button class="gate-button" type="button" data-dashboard-action="approve-gate" data-action-label="${esc(buttonLabel)}">${esc(buttonLabel)}</button>
+      </div>
+      <div class="gate-action">
+        <p>CLI fallback:</p>
+        <pre class="recovery-command mono" data-copy="${esc(cliCommand)}">${esc(cliCommand)}</pre>
+      </div>`;
+}
+
 export { findPostGateTurns, aggregateEvidence };
 
 function findCoordinatorGateRequest(history, pendingGate) {
@@ -254,12 +265,11 @@ export function render({
         )).join('')}</ul></div>`;
       }
     }
-    html += `
-      <div class="gate-action">
-        <p>Approve with:</p>
-        <pre class="recovery-command mono" data-copy="${isCoordinator ? 'agentxchain multi approve-gate' : 'agentxchain approve-transition'}">${isCoordinator ? 'agentxchain multi approve-gate' : 'agentxchain approve-transition'}</pre>
-      </div>
-    </div>`;
+    html += renderApproveControls({
+      buttonLabel: isCoordinator ? 'Approve Coordinator Gate' : 'Approve Transition',
+      cliCommand: isCoordinator ? 'agentxchain multi approve-gate' : 'agentxchain approve-transition',
+    });
+    html += `</div>`;
   }
 
   if (pendingCompletion) {
@@ -298,12 +308,11 @@ export function render({
     if (evidence.files.length > 0) {
       html += `<div class="gate-support"><p><strong>Files Changed:</strong></p><ul>${evidence.files.map(f => `<li class="mono">${esc(f)}</li>`).join('')}</ul></div>`;
     }
-    html += `
-      <div class="gate-action">
-        <p>Approve with:</p>
-        <pre class="recovery-command mono" data-copy="${isCoordinator ? 'agentxchain multi approve-gate' : 'agentxchain approve-completion'}">${isCoordinator ? 'agentxchain multi approve-gate' : 'agentxchain approve-completion'}</pre>
-      </div>
-    </div>`;
+    html += renderApproveControls({
+      buttonLabel: isCoordinator ? 'Approve Coordinator Gate' : 'Approve Completion',
+      cliCommand: isCoordinator ? 'agentxchain multi approve-gate' : 'agentxchain approve-completion',
+    });
+    html += `</div>`;
   }
 
   html += `</div>`;

package/dashboard/index.html

@@ -51,6 +51,23 @@
       background: var(--green);
     }
     .status-dot.disconnected { background: var(--red); }
+    .action-banner {
+      display: none;
+      padding: 10px 24px;
+      border-bottom: 1px solid var(--border);
+      font-size: 13px;
+      background: rgba(99, 102, 241, 0.08);
+      color: var(--text);
+    }
+    .action-banner.visible { display: block; }
+    .action-banner.success {
+      background: rgba(34, 197, 94, 0.08);
+      color: var(--green);
+    }
+    .action-banner.error {
+      background: rgba(239, 68, 68, 0.08);
+      color: var(--red);
+    }
     nav {
       display: flex;
       gap: 0;
@@ -251,6 +268,29 @@
       margin-bottom: 16px;
     }
     .gate-card h3 { font-size: 14px; margin-bottom: 12px; }
+    .gate-controls {
+      display: flex;
+      gap: 12px;
+      align-items: center;
+      flex-wrap: wrap;
+      margin-top: 12px;
+    }
+    .gate-button {
+      background: rgba(99, 102, 241, 0.14);
+      color: var(--text);
+      border: 1px solid rgba(99, 102, 241, 0.45);
+      border-radius: 4px;
+      padding: 8px 12px;
+      font: inherit;
+      font-size: 13px;
+      cursor: pointer;
+      transition: background 0.15s, border-color 0.15s, opacity 0.15s;
+    }
+    .gate-button:hover { background: rgba(99, 102, 241, 0.22); }
+    .gate-button:disabled {
+      cursor: wait;
+      opacity: 0.7;
+    }
     .gate-action { margin-top: 12px; }
     .gate-action p { font-size: 12px; color: var(--text-dim); margin-bottom: 6px; }
     .initiative-grid {
@@ -332,6 +372,7 @@
       <span id="ws-label">Connecting...</span>
     </div>
   </header>
+  <div class="action-banner" id="action-banner"></div>
   <nav>
     <a href="#initiative">Initiative</a>
     <a href="#cross-repo">Cross-Repo</a>

package/package.json

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

package/scripts/release-preflight.sh

@@ -100,6 +100,13 @@ fi
 
 # 3. Tests
 echo "[3/6] Test suite"
+# Install MCP example deps — tests start example servers as subprocesses
+for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../examples/mcp-http-echo-agent"; do
+  if [[ -f "${example_dir}/package.json" && ! -d "${example_dir}/node_modules" ]]; then
+    echo "  Installing deps for $(basename "$example_dir")..."
+    (cd "$example_dir" && env -u NODE_AUTH_TOKEN -u NPM_CONFIG_USERCONFIG npm install --ignore-scripts --userconfig /dev/null 2>&1) || true
+  fi
+done
 if run_and_capture TEST_OUTPUT npm test; then
   TEST_STATUS=0
 else

package/src/commands/dashboard.js

@@ -1,8 +1,8 @@
 /**
  * CLI command: agentxchain dashboard
  *
- * Starts the read-only dashboard bridge server and opens a browser.
- * See: V2_DASHBOARD_SPEC.md, DEC-DASH-002 (read-only in v2.0).
+ * Starts the local dashboard bridge server and opens a browser.
+ * The dashboard remains mostly observational, but can approve pending gates.
  */
 
 import { existsSync } from 'fs';

package/src/lib/coordinator-dispatch.js

@@ -238,7 +238,7 @@ export function dispatchCoordinatorTurn(workspacePath, state, config, assignment
     return { ok: false, error: bundleResult.error };
   }
 
-  const turn = assignResult.state.current_turn;
+  const turn = assignResult.turn;
   const contextResult = generateCrossRepoContext(
     workspacePath,
     state,

package/src/lib/dashboard/actions.js

@@ -0,0 +1,154 @@
+import { dirname } from 'path';
+import { loadProjectContext } from '../config.js';
+import { approvePhaseTransition, approveRunCompletion } from '../governed-state.js';
+import { deriveRecoveryDescriptor } from '../blocked-state.js';
+import { loadCoordinatorConfig } from '../coordinator-config.js';
+import { loadCoordinatorState } from '../coordinator-state.js';
+import { buildGatePayload, fireCoordinatorHook } from '../coordinator-hooks.js';
+import { approveCoordinatorCompletion, approveCoordinatorPhaseTransition } from '../coordinator-gates.js';
+import { readJsonFile } from './state-reader.js';
+
+function buildError(status, code, error, extra = {}) {
+  return {
+    status,
+    body: {
+      ok: false,
+      code,
+      error,
+      ...extra,
+    },
+  };
+}
+
+function normalizeRepoSuccess(result, gateType) {
+  if (gateType === 'phase_transition') {
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        scope: 'repo',
+        gate_type: 'phase_transition',
+        message: `Phase transition approved: ${result.transition.from} -> ${result.transition.to}`,
+        next_action: 'agentxchain step',
+      },
+    };
+  }
+
+  return {
+    status: 200,
+    body: {
+      ok: true,
+      scope: 'repo',
+      gate_type: 'run_completion',
+      message: 'Run completion approved. Run is now completed.',
+      next_action: null,
+    },
+  };
+}
+
+function normalizeRepoFailure(result) {
+  const recovery = result.state ? deriveRecoveryDescriptor(result.state) : null;
+  const code = result.error_code || 'approval_failed';
+  return buildError(409, code, result.error || 'Gate approval failed', {
+    next_action: recovery?.recovery_action || null,
+  });
+}
+
+function approveRepoGate(root, config, state) {
+  const gateType = state.pending_phase_transition ? 'phase_transition' : 'run_completion';
+  const result = gateType === 'phase_transition'
+    ? approvePhaseTransition(root, config)
+    : approveRunCompletion(root, config);
+
+  if (!result.ok) {
+    return normalizeRepoFailure(result);
+  }
+
+  return normalizeRepoSuccess(result, gateType);
+}
+
+function normalizeCoordinatorSuccess(result, gateType) {
+  if (gateType === 'phase_transition') {
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        scope: 'coordinator',
+        gate_type: 'phase_transition',
+        message: `Coordinator phase transition approved: ${result.transition.from} -> ${result.transition.to}`,
+        next_action: 'agentxchain multi step',
+      },
+    };
+  }
+
+  return {
+    status: 200,
+    body: {
+      ok: true,
+      scope: 'coordinator',
+      gate_type: 'run_completion',
+      message: 'Coordinator run completion approved. Run is now complete.',
+      next_action: null,
+    },
+  };
+}
+
+function approveCoordinatorGate(workspacePath, state, config) {
+  const gatePayload = buildGatePayload(state.pending_gate, state);
+  const gateHook = fireCoordinatorHook(workspacePath, config, 'before_gate', gatePayload, {
+    super_run_id: state.super_run_id,
+  });
+
+  if (gateHook.blocked) {
+    const blocker = gateHook.verdicts.find((entry) => entry.verdict === 'block');
+    const reason = blocker?.message || 'before_gate hook blocked approval';
+    return buildError(409, 'hook_blocked', reason);
+  }
+
+  if (!gateHook.ok) {
+    return buildError(409, 'hook_failed', gateHook.error || 'before_gate hook failed');
+  }
+
+  const gateType = state.pending_gate.gate_type;
+  let result;
+
+  if (gateType === 'phase_transition') {
+    result = approveCoordinatorPhaseTransition(workspacePath, state, config);
+  } else if (gateType === 'run_completion') {
+    result = approveCoordinatorCompletion(workspacePath, state, config);
+  } else {
+    return buildError(400, 'unknown_gate_type', `Unknown gate type: "${gateType}"`);
+  }
+
+  if (!result.ok) {
+    return buildError(409, 'approval_failed', result.error || 'Coordinator gate approval failed');
+  }
+
+  return normalizeCoordinatorSuccess(result, gateType);
+}
+
+export function approvePendingDashboardGate(agentxchainDir) {
+  const workspacePath = dirname(agentxchainDir);
+  const repoState = readJsonFile(agentxchainDir, 'state.json');
+
+  if (repoState?.pending_phase_transition || repoState?.pending_run_completion) {
+    const context = loadProjectContext(workspacePath);
+    return approveRepoGate(workspacePath, context?.config, repoState);
+  }
+
+  const coordinatorState = readJsonFile(agentxchainDir, 'multirepo/state.json');
+  if (coordinatorState?.pending_gate) {
+    const configResult = loadCoordinatorConfig(workspacePath);
+    if (!configResult.ok) {
+      const detail = (configResult.errors || [])
+        .map((entry) => typeof entry === 'string' ? entry : entry.message || JSON.stringify(entry))
+        .join('; ');
+      return buildError(400, 'coordinator_config_error', detail || 'Coordinator config error');
+    }
+
+    const loadedState = loadCoordinatorState(workspacePath) || coordinatorState;
+    return approveCoordinatorGate(workspacePath, loadedState, configResult.config);
+  }
+
+  return buildError(409, 'no_pending_gate', 'No pending repo or coordinator gate to approve.');
+}

package/src/lib/dashboard/bridge-server.js

@@ -1,20 +1,22 @@
 /**
- * Dashboard bridge server — read-only HTTP + WebSocket server.
+ * Dashboard bridge server — local HTTP + WebSocket server.
  *
- * Serves dashboard static assets, exposes read-only API endpoints for
- * .agentxchain/ state files, and pushes WebSocket invalidation events
- * when watched files change.
+ * Serves dashboard static assets, exposes state API endpoints for
+ * .agentxchain/ files, supports a narrow local gate-approval mutation,
+ * and pushes WebSocket invalidation events when watched files change.
  *
- * Security: binds to 127.0.0.1 only. No write RPC. No mutation endpoints.
+ * Security: binds to 127.0.0.1 only. WebSocket remains read-only.
+ * HTTP mutation is limited to authenticated approve-gate requests.
  * See: DEC-DASH-002, DEC-DASH-003, AT-DASH-007, AT-DASH-008.
  */
 
 import { createServer } from 'http';
-import { createHash } from 'crypto';
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
 import { readFileSync, existsSync } from 'fs';
 import { join, extname, resolve, sep } from 'path';
 import { readResource } from './state-reader.js';
 import { FileWatcher } from './file-watcher.js';
+import { approvePendingDashboardGate } from './actions.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -133,6 +135,55 @@ function sendWsError(socket, error) {
   }));
 }
 
+function writeJson(res, statusCode, payload, extraHeaders = {}) {
+  res.writeHead(statusCode, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Cache-Control': 'no-cache',
+    ...extraHeaders,
+  });
+  res.end(JSON.stringify(payload));
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (chunk) => {
+      body += chunk;
+      if (body.length > 32 * 1024) {
+        reject(new Error('Request body too large.'));
+        try { req.destroy(); } catch {}
+      }
+    });
+    req.on('end', () => {
+      if (!body.trim()) {
+        resolve({});
+        return;
+      }
+
+      try {
+        resolve(JSON.parse(body));
+      } catch {
+        reject(new Error('Request body must be valid JSON.'));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+function tokenMatches(expectedToken, receivedToken) {
+  if (typeof receivedToken !== 'string') {
+    return false;
+  }
+
+  const expected = Buffer.from(expectedToken, 'utf8');
+  const received = Buffer.from(receivedToken, 'utf8');
+  if (expected.length !== received.length) {
+    return false;
+  }
+
+  return timingSafeEqual(expected, received);
+}
+
 function resolveDashboardAssetPath(dashboardDir, pathname) {
   let decodedPath;
   try {
@@ -159,6 +210,7 @@ function resolveDashboardAssetPath(dashboardDir, pathname) {
 export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }) {
   const wsClients = new Set();
   const watcher = new FileWatcher(agentxchainDir);
+  const mutationToken = randomBytes(24).toString('hex');
 
   // Broadcast invalidation events to all connected WebSocket clients
   watcher.on('invalidate', ({ resource }) => {
@@ -168,30 +220,65 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
     }
   });
 
-  const server = createServer((req, res) => {
-    // Block all mutation methods (AT-DASH-008)
-    if (req.method !== 'GET' && req.method !== 'HEAD') {
-      res.writeHead(405, { 'Content-Type': 'application/json', 'Allow': 'GET, HEAD' });
-      res.end(JSON.stringify({ error: 'Method not allowed. Dashboard is read-only in v2.0.' }));
+  const server = createServer(async (req, res) => {
+    const method = req.method || 'GET';
+    const isApproveGateRequest = method === 'POST' && req.url && new URL(req.url, `http://${req.headers.host}`).pathname === '/api/actions/approve-gate';
+
+    if (method !== 'GET' && method !== 'HEAD' && !isApproveGateRequest) {
+      writeJson(
+        res,
+        405,
+        { error: 'Method not allowed. Dashboard mutations are limited to approve-gate.' },
+        { Allow: 'GET, HEAD, POST' }
+      );
       return;
     }
 
     const url = new URL(req.url, `http://${req.headers.host}`);
     const pathname = url.pathname;
 
+    if (pathname === '/api/session') {
+      writeJson(res, 200, {
+        session_version: '1',
+        mutation_token: mutationToken,
+        capabilities: {
+          approve_gate: true,
+        },
+      });
+      return;
+    }
+
+    if (pathname === '/api/actions/approve-gate') {
+      if (method !== 'POST') {
+        writeJson(res, 405, { ok: false, code: 'method_not_allowed', error: 'Use POST for dashboard actions.' }, { Allow: 'POST' });
+        return;
+      }
+
+      if (!tokenMatches(mutationToken, req.headers['x-agentxchain-token'])) {
+        writeJson(res, 403, { ok: false, code: 'invalid_token', error: 'Valid X-AgentXchain-Token is required.' });
+        return;
+      }
+
+      try {
+        await readJsonBody(req);
+      } catch (error) {
+        writeJson(res, 400, { ok: false, code: 'invalid_json', error: error.message });
+        return;
+      }
+
+      const result = approvePendingDashboardGate(agentxchainDir);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);
       if (!result) {
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'Resource not found' }));
+        writeJson(res, 404, { error: 'Resource not found' });
         return;
       }
-      res.writeHead(200, {
-        'Content-Type': 'application/json; charset=utf-8',
-        'Cache-Control': 'no-cache',
-      });
-      res.end(JSON.stringify(result.data));
+      writeJson(res, 200, result.data);
       return;
     }
 
@@ -253,7 +340,7 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847 }
       } else if (frame.opcode === 0x01) {
         sendWsError(
           ws,
-          'Dashboard is read-only in v2.0. WebSocket commands and mutations are not supported.'
+          'Dashboard WebSocket is read-only. Use the authenticated HTTP approve-gate action instead.'
         );
       }
     });

package/src/lib/governed-state.js

@@ -1257,7 +1257,8 @@ export function assignGovernedTurn(root, config, roleId) {
   };
 
   writeState(root, updatedState);
-  const result = { ok: true, state: attachLegacyCurrentTurnAlias(updatedState) };
+  const assignedTurn = updatedState.active_turns[turnId];
+  const result = { ok: true, state: attachLegacyCurrentTurnAlias(updatedState), turn: assignedTurn };
   if (warnings.length > 0) {
     result.warnings = warnings;
   }

package/src/lib/runner-interface.js

@@ -0,0 +1,60 @@
+/**
+ * Runner Interface — declared contract for governed execution consumers.
+ *
+ * This module re-exports the library functions that any runner (CLI, CI,
+ * hosted, programmatic) needs to orchestrate governed turns. It is the
+ * formal boundary described in RUNNER_INTERFACE_SPEC.md.
+ *
+ * Design rules:
+ *   - Only protocol-normative operations are exported here
+ *   - Adapter dispatch is NOT included (runner-specific)
+ *   - CLI output formatting is NOT included (runner-specific)
+ *   - Dashboard, export, report, intake are NOT included (runner features)
+ *
+ * Usage:
+ *   import { loadContext, loadState, initRun, assignTurn, acceptTurn } from './runner-interface.js';
+ *   const ctx = loadContext();
+ *   const state = loadState(ctx.root, ctx.config);
+ *   // ... orchestrate turns
+ */
+
+// ── Context ─────────────────────────────────────────────────────────────────
+
+export { loadProjectContext as loadContext, loadProjectState as loadState } from './config.js';
+
+// ── Governed Lifecycle ──────────────────────────────────────────────────────
+
+export {
+  initializeGovernedRun as initRun,
+  assignGovernedTurn as assignTurn,
+  acceptGovernedTurn as acceptTurn,
+  rejectGovernedTurn as rejectTurn,
+  approvePhaseTransition as approvePhaseGate,
+  approveRunCompletion as approveCompletionGate,
+  markRunBlocked,
+  raiseOperatorEscalation as escalate,
+  reactivateGovernedRun as reactivateRun,
+  getActiveTurns,
+  getActiveTurnCount,
+  getActiveTurn,
+  acquireAcceptanceLock as acquireLock,
+  releaseAcceptanceLock as releaseLock,
+} from './governed-state.js';
+
+// ── Dispatch ────────────────────────────────────────────────────────────────
+
+export { writeDispatchBundle } from './dispatch-bundle.js';
+export { getTurnStagingResultPath } from './turn-paths.js';
+
+// ── Hooks & Notifications ───────────────────────────────────────────────────
+
+export { runHooks } from './hook-runner.js';
+export { emitNotifications } from './notification-runner.js';
+
+// ── Config Utilities ────────────────────────────────────────────────────────
+
+export { getMaxConcurrentTurns } from './normalized-config.js';
+
+// ── Interface Version ───────────────────────────────────────────────────────
+
+export const RUNNER_INTERFACE_VERSION = '0.2';