@geraldmaron/construct 1.0.21 → 1.0.24

package/lib/reconcile/legacy-skills-cleanup.mjs

@@ -0,0 +1,200 @@
+/**
+ * lib/reconcile/legacy-skills-cleanup.mjs — clean up SKILL.md files at
+ * ~/.agents/skills/ whose frontmatter is missing the `name` and
+ * `description` fields required by the Anthropic Agent Skills loader.
+ *
+ * The cleanup is constrained to files whose frontmatter matches the
+ * Construct doc-stamp shape (cx_doc_id + generator: construct/sync-specialists
+ * + body_hash), so non-Construct skill authors in the same tree are
+ * untouched. Empty parent directories prune upward; ~/.agents itself is
+ * removed only if Construct emptied it.
+ *
+ * Safety: `auto`. detect() is pure-read; apply() never modifies files
+ * outside the matched-stamp set and never touches files whose mtime falls
+ * after the doc-stamp timestamp recorded in the frontmatter (a signal
+ * that something other than Construct's sync may have edited the file).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { homeDir } from '../paths.mjs';
+
+const LEGACY_REL = path.join('.agents', 'skills');
+
+function legacyRoot() {
+  return path.join(homeDir(), LEGACY_REL);
+}
+
+const STAMP_RE = /^cx_doc_id:\s*\S+/m;
+const GENERATOR_RE = /^generator:\s*construct\/sync-specialists/m;
+const BODY_HASH_RE = /^body_hash:\s*sha256:/m;
+const NAME_RE = /^name:\s*\S+/m;
+const DESCRIPTION_RE = /^description:\s*\S/m;
+const UPDATED_AT_RE = /^updated_at:\s*(\S+)/m;
+
+// Frontmatter shapes the Construct sync writer has emitted. The "stale"
+// shape is doc-stamp-only (cx_doc_id + generator + body_hash, no name, no
+// description) — the Anthropic Agent Skills loader rejects it. The current
+// shape carries name + description and parses cleanly.
+
+function classifyFrontmatter(content) {
+  if (!content || !content.startsWith('---\n')) return { kind: 'no-frontmatter' };
+  const closeIdx = content.indexOf('\n---', 4);
+  if (closeIdx === -1) return { kind: 'malformed' };
+  const fm = content.slice(4, closeIdx);
+  const isConstructStamp = STAMP_RE.test(fm) && GENERATOR_RE.test(fm) && BODY_HASH_RE.test(fm);
+  const hasName = NAME_RE.test(fm);
+  const hasDescription = DESCRIPTION_RE.test(fm);
+  const updatedMatch = fm.match(UPDATED_AT_RE);
+  const updatedAtMs = updatedMatch ? Date.parse(updatedMatch[1]) : NaN;
+  if (isConstructStamp && !hasName && !hasDescription) {
+    return { kind: 'construct-stale', updatedAtMs };
+  }
+  if (isConstructStamp && hasName && hasDescription) {
+    return { kind: 'construct-current', updatedAtMs };
+  }
+  return { kind: 'foreign' };
+}
+
+function walkSkillFiles(dir) {
+  const out = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return out; }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkSkillFiles(full));
+    else if (entry.isFile() && entry.name === 'SKILL.md') out.push(full);
+  }
+  return out;
+}
+
+function inspectFile(file) {
+  let content = '';
+  let stat;
+  try {
+    content = fs.readFileSync(file, 'utf8');
+    stat = fs.statSync(file);
+  } catch {
+    return { file, classification: { kind: 'unreadable' } };
+  }
+  const classification = classifyFrontmatter(content);
+  return { file, classification, mtimeMs: stat.mtimeMs };
+}
+
+// A file is safe to remove when (a) it matches the Construct stale shape,
+// (b) its mtime is within a small skew of its declared updated_at — if
+// the user edited it after Construct wrote it, mtime drifts ahead, and
+// the file is preserved.
+
+const USER_EDIT_SKEW_MS = 5 * 60 * 1000;
+
+function isSafeToRemove(inspection) {
+  const c = inspection.classification;
+  if (c.kind !== 'construct-stale') return false;
+  if (!Number.isFinite(c.updatedAtMs)) return true;
+  const drift = inspection.mtimeMs - c.updatedAtMs;
+  return drift <= USER_EDIT_SKEW_MS;
+}
+
+function pruneEmptyDirsUpward(startDir, stopDir) {
+  let cur = startDir;
+  while (cur && cur.startsWith(stopDir) && cur !== stopDir) {
+    let entries;
+    try { entries = fs.readdirSync(cur); } catch { return; }
+    if (entries.length > 0) return;
+    try { fs.rmdirSync(cur); } catch { return; }
+    cur = path.dirname(cur);
+  }
+}
+
+async function detect() {
+  const root = legacyRoot();
+  if (!fs.existsSync(root)) {
+    return { needsRepair: false, summary: 'No legacy ~/.agents/skills directory present.' };
+  }
+  const files = walkSkillFiles(root);
+  if (files.length === 0) {
+    return { needsRepair: false, summary: 'Legacy directory present but empty.' };
+  }
+  let stale = 0;
+  let staleUserEdited = 0;
+  let constructCurrent = 0;
+  let foreign = 0;
+  let unreadable = 0;
+  for (const file of files) {
+    const inspection = inspectFile(file);
+    const kind = inspection.classification.kind;
+    if (kind === 'construct-stale') {
+      if (isSafeToRemove(inspection)) stale += 1;
+      else staleUserEdited += 1;
+    } else if (kind === 'construct-current') {
+      constructCurrent += 1;
+    } else if (kind === 'foreign') {
+      foreign += 1;
+    } else {
+      unreadable += 1;
+    }
+  }
+  if (stale === 0) {
+    return {
+      needsRepair: false,
+      summary: `Legacy directory present, no Construct-shaped stale files to remove (current: ${constructCurrent}, foreign: ${foreign}, user-edited stale: ${staleUserEdited}).`,
+      details: { stale, staleUserEdited, constructCurrent, foreign, unreadable, total: files.length },
+    };
+  }
+  return {
+    needsRepair: true,
+    summary: `${stale} stale Construct SKILL.md files at ~/.agents/skills (current: ${constructCurrent}, foreign: ${foreign}, user-edited stale: ${staleUserEdited}, unreadable: ${unreadable}).`,
+    details: { stale, staleUserEdited, constructCurrent, foreign, unreadable, total: files.length },
+  };
+}
+
+async function apply() {
+  const root = legacyRoot();
+  if (!fs.existsSync(root)) return { summary: 'Already clean.' };
+  const files = walkSkillFiles(root);
+  let removed = 0;
+  let preserved = 0;
+  const dirsToCheck = new Set();
+  for (const file of files) {
+    const inspection = inspectFile(file);
+    if (!isSafeToRemove(inspection)) {
+      preserved += 1;
+      continue;
+    }
+    try {
+      fs.unlinkSync(file);
+      removed += 1;
+      dirsToCheck.add(path.dirname(file));
+    } catch {
+      preserved += 1;
+    }
+  }
+  for (const dir of [...dirsToCheck].sort((a, b) => b.length - a.length)) {
+    pruneEmptyDirsUpward(dir, root);
+  }
+  // If the root is now empty, prune it and the .agents parent if also empty.
+
+  try {
+    if (fs.readdirSync(root).length === 0) {
+      fs.rmdirSync(root);
+      const parent = path.dirname(root);
+      try {
+        if (fs.readdirSync(parent).length === 0) fs.rmdirSync(parent);
+      } catch { /* parent has unrelated content */ }
+    }
+  } catch { /* root has remaining entries */ }
+  return {
+    summary: `Removed ${removed} stale SKILL.md file${removed === 1 ? '' : 's'} from ~/.agents/skills${preserved > 0 ? ` (preserved ${preserved} with user-edit signal)` : ''}.`,
+  };
+}
+
+export default {
+  id: 'legacy-skills-cleanup',
+  description: 'Remove SKILL.md files at ~/.agents/skills whose frontmatter lacks the required name/description fields.',
+  safety: 'auto',
+  detect,
+  apply,
+};

package/lib/reconcile/mcp-entry-reconcile.mjs

@@ -0,0 +1,142 @@
+/**
+ * lib/reconcile/mcp-entry-reconcile.mjs — strip Codex `[mcp_servers.<id>]`
+ * tables whose `bearer_token_env_var` references an unset env var from configs
+ * written before the sync-time fix (ADR-0027 / construct-n6h7).
+ *
+ * Codex aborts at startup when an MCP server's bearer_token_env_var names an
+ * env var that is unset. The sync writer now omits such entries, but a config
+ * written by an earlier version still carries them. This repair removes exactly
+ * those construct-managed tables from the global `~/.codex/config.toml` and a
+ * project `.codex/config.toml` when present, preserving every other table.
+ *
+ * Detection mirrors the sync-time gate (codexMcpEnvResolves): an entry whose
+ * token env var resolves is kept; only unresolved-credential tables are pruned.
+ * Tables with no credential requirement are never touched. Removal is scoped to
+ * registry-managed MCP ids by exact table name, so user-authored mcp_servers
+ * tables are out of scope. Safety: `auto`. detect() reads only; apply() is
+ * idempotent because removeTomlTables drains the matched tables to none.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { homeDir } from '../paths.mjs';
+import {
+  getCodexConfigPath,
+  buildCodexMcpEntry,
+  removeTomlTables,
+  tomlString,
+} from '../codex-config.mjs';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function registryMcpServers() {
+  const installed = path.join(homeDir(), '.construct', 'specialists', 'registry.json');
+  const bundled = fileURLToPath(new URL('../../specialists/registry.json', import.meta.url));
+  for (const src of [installed, bundled]) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(src, 'utf8'));
+      if (parsed && parsed.mcpServers) return parsed.mcpServers;
+    } catch {
+      continue;
+    }
+  }
+  return {};
+}
+
+function hasMcpTable(text, id) {
+  return new RegExp(`^\\[mcp_servers\\.(?:${escapeRegExp(id)}|${escapeRegExp(tomlString(id))})\\]`, 'm').test(text);
+}
+
+// An entry with no bearer_token_env_var has no credential requirement and is
+// always valid. An entry whose token env var is set resolves; an unset value
+// (undefined or empty string) is the abort condition Codex hits at startup.
+
+function tokenResolves(id, def, env) {
+  const entry = buildCodexMcpEntry(id, def, env);
+  const tokenVar = entry?.bearer_token_env_var;
+  if (!tokenVar) return true;
+  const val = env[tokenVar];
+  return val !== undefined && val !== '';
+}
+
+function configTargets() {
+  const targets = [{ scope: 'global', file: getCodexConfigPath(homeDir()) }];
+  const projectConfig = path.join(process.cwd(), '.codex', 'config.toml');
+  if (fs.existsSync(projectConfig)) targets.push({ scope: 'project', file: projectConfig });
+  return targets;
+}
+
+function unresolvedTables(text, registryMcp, env) {
+  const ids = [];
+  for (const id of Object.keys(registryMcp)) {
+    if (!hasMcpTable(text, id)) continue;
+    if (tokenResolves(id, registryMcp[id], env)) continue;
+    ids.push(id);
+  }
+  return ids;
+}
+
+async function detect() {
+  const registryMcp = registryMcpServers();
+  if (Object.keys(registryMcp).length === 0) {
+    return { needsRepair: false, summary: 'No registry MCP servers to reconcile.' };
+  }
+  const env = process.env;
+  const offenders = [];
+  for (const target of configTargets()) {
+    let text = '';
+    try {
+      if (!fs.existsSync(target.file)) continue;
+      text = fs.readFileSync(target.file, 'utf8');
+    } catch {
+      continue;
+    }
+    const ids = unresolvedTables(text, registryMcp, env);
+    if (ids.length > 0) offenders.push({ ...target, ids });
+  }
+  if (offenders.length === 0) {
+    return { needsRepair: false, summary: 'No Codex MCP tables reference an unset token env var.' };
+  }
+  const total = offenders.reduce((acc, o) => acc + o.ids.length, 0);
+  return {
+    needsRepair: true,
+    summary: `${total} Codex MCP table${total === 1 ? '' : 's'} reference an unset token env var (${offenders.map((o) => `${o.scope}: ${o.ids.join(', ')}`).join('; ')}).`,
+    details: { offenders: offenders.map((o) => ({ scope: o.scope, ids: o.ids })) },
+  };
+}
+
+async function apply() {
+  const registryMcp = registryMcpServers();
+  const env = process.env;
+  let removed = 0;
+  const scopes = [];
+  for (const target of configTargets()) {
+    if (!fs.existsSync(target.file)) continue;
+    const text = fs.readFileSync(target.file, 'utf8');
+    const ids = unresolvedTables(text, registryMcp, env);
+    if (ids.length === 0) continue;
+
+    // Strip both the bare and quoted table forms per id, matching the names
+    // the sync writer emits, so a table written either way is removed.
+
+    const tableNames = ids.flatMap((id) => [`mcp_servers.${id}`, `mcp_servers.${tomlString(id)}`]);
+    const cleaned = removeTomlTables(text, tableNames);
+    fs.writeFileSync(target.file, `${cleaned.trimEnd()}\n`, 'utf8');
+    removed += ids.length;
+    scopes.push(`${target.scope}: ${ids.join(', ')}`);
+  }
+  if (removed === 0) return { summary: 'Already clean.' };
+  return { summary: `Removed ${removed} unresolved Codex MCP table${removed === 1 ? '' : 's'} (${scopes.join('; ')}).` };
+}
+
+export default {
+  id: 'mcp-entry-reconcile',
+  description: 'Strip Codex MCP tables whose bearer_token_env_var references an unset env var from existing configs.',
+  safety: 'auto',
+  detect,
+  apply,
+};

package/lib/runtime/uv-bootstrap.mjs

@@ -37,12 +37,32 @@ function which(bin) {
   return result.stdout.trim().split('\n')[0] || null;
 }
 
+// First-run docling provisioning blocks for minutes (uv install, venv, then a
+// large `uv pip install docling` that pulls ML deps). Without a heartbeat it
+// reads as a hang. Progress goes to stderr only, so JSON consumers on stdout are
+// unaffected; it is the long-operation's own channel, not a suppressible notice.
+
+function progress(message) {
+  try { process.stderr.write(`[docling setup] ${message}\n`); } catch { /* stderr closed */ }
+}
+
+// spawnSync sets status=null and error.code=ETIMEDOUT on timeout; distinguish a
+// timeout from a real non-zero exit so the message tells the user what to do.
+
+function describeStepFailure(label, result, timeoutMs) {
+  if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
+    return `${label} timed out after ${Math.round(timeoutMs / 1000)}s — docling's one-time download did not complete. Check network/proxy and re-run; or set ingest.fallback to "adapter" to skip docling.`;
+  }
+  return `${label} failed (${result.status}): ${result.stderr || result.stdout || result.error?.message || 'unknown error'}`;
+}
+
 function ensureUv(installDir) {
   const fromPath = which('uv');
   if (fromPath) return fromPath;
   const cachedUv = path.join(installDir, 'bin', 'uv');
   if (existsSync(cachedUv)) return cachedUv;
   mkdirSync(installDir, { recursive: true });
+  progress('Installing uv (Python toolchain) — first run only…');
   const env = { ...process.env, UV_INSTALL_DIR: path.join(installDir, 'bin'), UV_NO_MODIFY_PATH: '1' };
   const sh = spawnSync('sh', ['-c', `curl -LsSf ${UV_INSTALL_URL} | sh`], {
     env,
@@ -50,7 +70,7 @@ function ensureUv(installDir) {
     encoding: 'utf8',
   });
   if (sh.status !== 0) {
-    throw new Error(`uv install failed (${sh.status}): ${sh.stderr || sh.stdout}`);
+    throw new Error(describeStepFailure('uv install', sh, UV_TIMEOUT_MS));
   }
   if (!existsSync(cachedUv)) {
     throw new Error(`uv install reported success but binary not found at ${cachedUv}`);
@@ -86,23 +106,27 @@ export function ensureDoclingVenv({ runtimeDir = defaultRuntimeDir(), force = fa
     return { pythonBin: existingPython, venvDir, runtimeDir, fresh: false };
   }
 
+  progress('Provisioning the docling document extractor (first run). This downloads a Python runtime and ML dependencies and can take several minutes; later runs are instant.');
   const uv = ensureUv(runtimeDir);
 
+  progress('Creating Python 3.11 virtualenv…');
   const venvResult = spawnSync(uv, ['venv', venvDir, '--python', '3.11'], {
     timeout: VENV_TIMEOUT_MS,
     encoding: 'utf8',
   });
   if (venvResult.status !== 0) {
-    throw new Error(`uv venv failed (${venvResult.status}): ${venvResult.stderr}`);
+    throw new Error(describeStepFailure('uv venv', venvResult, VENV_TIMEOUT_MS));
   }
 
+  progress(`Installing docling ${DOCLING_PIN} and its dependencies — the slow step (large download)…`);
   const installResult = spawnSync(uv, ['pip', 'install', '--python', pythonBinFor(venvDir), `docling==${DOCLING_PIN}`], {
     timeout: INSTALL_TIMEOUT_MS,
     encoding: 'utf8',
   });
   if (installResult.status !== 0) {
-    throw new Error(`docling install failed (${installResult.status}): ${installResult.stderr}`);
+    throw new Error(describeStepFailure('docling install', installResult, INSTALL_TIMEOUT_MS));
   }
+  progress('docling extractor ready.');
 
   const pythonBin = pythonBinFor(venvDir);
   writeMarker(markerPath, {

package/lib/schema-infer.mjs

@@ -210,9 +210,23 @@ async function callModel(userContent, { traceId } = {}) {
   }
 
   // If only Anthropic key available, use configured fast tier directly.
+  // Construct ships with no implicit model defaults (ADR-0027,
+  // tests/model-router-no-defaults.test.mjs), so an unconfigured fast tier
+  // resolves to null. Surface a clear configuration error instead of letting
+  // null leak into the candidate loop where /^anthropic\//.test(null) throws.
+
   if (candidates.length === 0 && anthropicKey) {
     const envPath = getUserEnvPath();
-    candidates = [readCurrentModels(envPath, {}).fast];
+    const fast = readCurrentModels(envPath, {}).fast;
+    if (!fast) {
+      throw new Error(
+        "Schema inference requires a fast-tier model. " +
+        "Either set OPENROUTER_API_KEY (to use free model fallbacks) or " +
+        "configure a fast tier with 'construct models --apply' or " +
+        "'export CX_MODEL_FAST=<model-id>'."
+      );
+    }
+    candidates = [fast];
   }
 
   let lastError;
@@ -261,7 +275,7 @@ async function callModel(userContent, { traceId } = {}) {
           headers: {
             Authorization: `Bearer ${orKey}`,
             'content-type': 'application/json',
-            'HTTP-Referer': 'https://github.com/construct',
+            'HTTP-Referer': 'https://github.com/geraldmaron/construct',
           },
           body: JSON.stringify({
             model: openRouterModelId,

package/lib/server/csrf.mjs

@@ -66,6 +66,11 @@ export function ensureCsrfCookie(req, res) {
  */
 export function verifyCsrf(req, { skip } = {}) {
   if (SAFE_METHODS.has(req.method)) return true;
+  // A request authenticated by an Authorization header (bearer token) is not
+  // cookie-driven, so it cannot be forged cross-origin — CSRF defends ambient
+  // cookie auth, not header tokens. This is what lets programmatic API clients
+  // (editor adapters, CLI, CI) POST without the browser CSRF dance.
+  if (req.headers && req.headers.authorization) return true;
   if (typeof skip === 'function' && skip(req.url || '')) return true;
   const headerVal = req.headers[HEADER_NAME];
   const cookieVal = parseCookies(req)[COOKIE_NAME];
@@ -78,13 +83,20 @@ export function verifyCsrf(req, { skip } = {}) {
 }
 
 /**
- * Default skip predicate — webhooks and auth/login may legitimately accept
- * cross-origin POSTs without the CSRF dance.
+ * Default skip predicate — webhooks, auth/login, and the orchestration API
+ * legitimately accept POSTs without the CSRF dance. CSRF defends a browser
+ * cookie session; the `/api/orchestration/*` endpoints are consumed only by
+ * programmatic clients (the `--remote` CLI, the MCP tool, editor adapters) that
+ * carry a bearer token (or nothing in no-token mode), never the dashboard
+ * cookie — so CSRF is the wrong control there, and the auth gate still protects
+ * them in token mode. Without this, a no-token daemon rejects every orchestration
+ * run with a 403.
  */
 export function defaultSkip(url) {
   if (!url) return false;
   return (
     url.startsWith('/api/webhooks/') ||
+    url.startsWith('/api/orchestration/') ||
     url === '/api/auth/login' ||
     url === '/api/slack/commands'
   );

package/lib/server/index.mjs

@@ -32,6 +32,14 @@ import { onEmbedNotification } from '../embed/notifications.mjs';
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const ROOT_DIR = join(__dirname, '..', '..');
 const HOME = homedir();
+
+// The daemon is a long-lived, detached service not bound to one project, so its
+// orchestration runs persist under the user data root (HOME → ~/.cx/runtime/
+// orchestration via the run store's relative path) rather than the install
+// directory. A global install dir can be shared or read-only and would mix
+// every project's runs together; HOME is always writable and survives reinstalls.
+
+const ORCHESTRATION_RUN_ROOT = HOME;
 const PORT = parseInt(process.env.PORT ?? '4242', 10);
 
 // Default bind is loopback regardless of NODE_ENV. Exposing the dashboard to
@@ -464,6 +472,88 @@ async function handleApprovals(req, res) {
   res.end('Method Not Allowed');
 }
 
+// Orchestration daemon surface: start a run (background execution), inspect runs,
+// and stream a single run's lifecycle over SSE. Construct's runtime owns the
+// orchestration; this lets any thin client (editor, TUI, CI) reach the outcome.
+// Responses are wrapped in the versioned, secret-free embedded-contract envelope.
+
+async function handleOrchestration(req, res) {
+  const url = new URL(req.url, `http://${BIND_HOST}:${PORT}`);
+  const { startRun, getRun, getRuns } = await import('../orchestration/runtime.mjs');
+  const { onRunEvent, requestCancel } = await import('../orchestration/events.mjs');
+  const { wrapResponse } = await import('../embedded-contract/envelope.mjs');
+
+  const send = (code, data) => {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(wrapResponse({ data, surface: 'sdk' })));
+  };
+  const fail = (code, message) => {
+    res.writeHead(code, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: message }));
+  };
+
+  if (url.pathname === '/api/orchestration/runs' && req.method === 'POST') {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', async () => {
+      try {
+        const d = JSON.parse(body || '{}');
+        if (!d.request || typeof d.request !== 'string') throw new Error('Missing "request" string');
+        const run = await startRun(
+          { request: d.request, workflowType: d.workflowType, requestedStrategy: d.requestedStrategy, host: d.host, hostModel: d.hostModel, hostProvider: d.hostProvider, fileCount: d.fileCount, moduleCount: d.moduleCount },
+          { cwd: ORCHESTRATION_RUN_ROOT, workerBackend: d.workerBackend || null },
+        );
+        send(202, run);
+      } catch (err) {
+        fail(400, err.message);
+      }
+    });
+    return;
+  }
+
+  if (url.pathname === '/api/orchestration/runs' && req.method === 'GET') {
+    const limit = Number(url.searchParams.get('limit') || 20);
+    send(200, { runs: await getRuns(ORCHESTRATION_RUN_ROOT, { limit }) });
+    return;
+  }
+
+  const match = url.pathname.match(/^\/api\/orchestration\/runs\/([^/]+)(\/events|\/cancel)?$/);
+  if (match) {
+    const runId = decodeURIComponent(match[1]);
+    const sub = match[2];
+
+    if (!sub && req.method === 'GET') {
+      const run = await getRun(ORCHESTRATION_RUN_ROOT, runId);
+      if (!run) { fail(404, `Run not found: ${runId}`); return; }
+      send(200, run);
+      return;
+    }
+
+    if (sub === '/cancel' && req.method === 'POST') {
+      requestCancel(runId);
+      send(202, { runId, cancelRequested: true });
+      return;
+    }
+
+    if (sub === '/events' && req.method === 'GET') {
+      const run = await getRun(ORCHESTRATION_RUN_ROOT, runId);
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive', 'Access-Control-Allow-Origin': '*' });
+      res.write(': connected\n\n');
+      if (run) {
+        const snapshot = { type: 'snapshot', runId, status: run.status, chainOfThought: run.chainOfThought ?? null, tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, reasoning: t.reasoning ?? null })) };
+        res.write(`data: ${JSON.stringify(snapshot)}\n\n`);
+      }
+      const off = onRunEvent(runId, (event) => {
+        try { res.write(`data: ${JSON.stringify(event)}\n\n`); } catch { off(); }
+      });
+      req.on('close', off);
+      return;
+    }
+  }
+
+  fail(404, 'Not found');
+}
+
 // ── Config handler ────────────────────────────────────────────────────────
 
 function handleConfig(req, res) {
@@ -701,6 +791,11 @@ const server = createServer(async (req, res) => {
     return;
   }
 
+  if (url.pathname.startsWith('/api/orchestration/')) {
+    await handleOrchestration(req, res);
+    return;
+  }
+
   if (url.pathname === '/api/registry' && req.method === 'GET') {
     try {
       const registry = JSON.parse(readFileSync(REGISTRY_FILE, 'utf8'));