@geraldmaron/construct 1.0.21 → 1.0.23

package/lib/init-update.mjs

@@ -21,38 +21,6 @@ const dryRun = args.includes("--dry-run");
 const cwdArg = args.find((arg) => arg.startsWith("--cwd="));
 const cwd = cwdArg ? path.resolve(cwdArg.split("=")[1]) : process.cwd();
 
-const REQUIRED_AGENT_SECTIONS = [
-  "Operating hierarchy",
-  "Start-of-session rules",
-  "Maintenance rules",
-  "End-of-session rules",
-  "Verification rules",
-];
-
-async function loadAgentsTemplate(projectName) {
-  const modulePath = path.join(import.meta.dirname, "project-init-shared.mjs");
-  const module = await import(modulePath);
-  if (!module.buildAgentsGuide) {
-    throw new Error("buildAgentsGuide not available from project-init-shared.mjs");
-  }
-  return module.buildAgentsGuide(projectName);
-}
-
-function inferProjectName(targetDir) {
-  const packagePath = path.join(targetDir, "package.json");
-  if (fs.existsSync(packagePath)) {
-    try {
-      const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
-      if (pkg.name) return pkg.name;
-    } catch { /* fall through */ }
-  }
-  return path.basename(targetDir);
-}
-
-function findMissingAgentsSections(content) {
-  return REQUIRED_AGENT_SECTIONS.filter((section) => !content.toLowerCase().includes(section.toLowerCase()));
-}
-
 function ensureProposalDir(targetDir) {
   const dir = path.join(targetDir, ".cx", "proposals");
   fs.mkdirSync(dir, { recursive: true });
@@ -66,37 +34,6 @@ function writeProposal(targetDir, fileName, content) {
   return proposalPath;
 }
 
-function buildAgentsProposal(existingContent, template, missingSections) {
-  const missingList = missingSections.map((section) => `- ${section}`).join("\n");
-  return [
-    "<!--",
-    "Construct init:update proposal",
-    "Review this file and merge the needed sections into AGENTS.md manually.",
-    "The original AGENTS.md was not modified.",
-    "-->",
-    "",
-    "# Proposed AGENTS.md Update",
-    "",
-    "## Why this proposal exists",
-    "",
-    "Your current `AGENTS.md` is missing these required sections:",
-    missingList,
-    "",
-    "## Current AGENTS.md",
-    "",
-    "```md",
-    existingContent.trimEnd(),
-    "```",
-    "",
-    "## Current Construct template",
-    "",
-    "```md",
-    template.trimEnd(),
-    "```",
-    "",
-  ].join("\n");
-}
-
 function buildWorkflowProposal(existingContent) {
   const updatedContent = existingContent.replace(
     /(\s+- run: node bin\/construct doctor\s*\n)/,
@@ -207,29 +144,12 @@ export function resolveTemplateConflict(conflict, resolution, targetDir) {
 async function main() {
   console.log(`Preparing Construct standards update for ${cwd}`);
 
-  const agentsPath = path.join(cwd, "AGENTS.md");
-  if (!fs.existsSync(agentsPath)) {
-    console.error("AGENTS.md not found. Run `construct init` first.");
-    process.exit(1);
-  }
-
-  const projectName = inferProjectName(cwd);
-  const existingAgents = fs.readFileSync(agentsPath, "utf8");
-  const template = await loadAgentsTemplate(projectName);
-  const missingSections = findMissingAgentsSections(existingAgents);
-
   const planned = [];
 
-  if (missingSections.length > 0) {
-    const proposalPath = path.join(".cx", "proposals", "AGENTS.md.construct-update.md");
-    planned.push({
-      label: `AGENTS.md proposal (${missingSections.length} missing section${missingSections.length === 1 ? "" : "s"})`,
-      write() {
-        return writeProposal(cwd, "AGENTS.md.construct-update.md", buildAgentsProposal(existingAgents, template, missingSections));
-      },
-      relativePath: proposalPath,
-    });
-  }
+  // Construct's guidance in AGENTS.md/CLAUDE.md is owned by the versioned
+  // CONSTRUCT INTEGRATION marker block, kept current by `construct sync`
+  // (ADR-0027 §2/§4). init:update scope is opt-in standards a project owner
+  // merges by hand: CI checks and template conflicts.
 
   const workflowPath = path.join(cwd, ".github", "workflows", "ci.yml");
   if (fs.existsSync(workflowPath)) {

package/lib/init.mjs

@@ -15,7 +15,6 @@ import fs from "node:fs";
 import path from "node:path";
 
 import {
-  buildAgentsGuide,
   buildContextJson,
   buildContextMarkdown,
   buildPlanTemplate,
@@ -43,14 +42,9 @@ function inferProjectName(targetPath) {
 function main() {
   const projectName = inferProjectName(target);
 
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, "AGENTS.md"),
-    content: buildAgentsGuide(projectName),
-    generator: "construct/init",
-  });
+  // AGENTS.md is user-owned (ADR-0027 §2); Construct contributes only the fenced
+  // integration block via injectIntoAgentFile, never a doctrine body here.
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
@@ -75,22 +69,12 @@ function main() {
     content: buildContextMarkdown(),
     generator: "construct/init",
   });
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, ".cx", ".gitkeep"),
-    content: "",
-    generator: "construct/init",
-  });
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, ".cx", "inbox", ".gitkeep"),
-    content: "",
-    generator: "construct/init",
-  });
+  // `.cx/` already exists from the context writes above and is gitignored in full
+  // (ADR-0027), so a keep file there could never be tracked; `.cx/inbox/` is the local
+  // intake drop zone the watcher polls. Create the directories; write no dead keep file.
+
+  fs.mkdirSync(path.join(target, ".cx", "inbox"), { recursive: true });
+  created.push(".cx/inbox/");
 
   process.stdout.write(`\nConstruct init → ${target}\n\n`);
   if (created.length) {

package/lib/install/stage-project.mjs

@@ -14,7 +14,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, copyFileSync, writeFileSync, mkdirSync, chmodSync } from 'node:fs';
 import path from 'node:path';
 
-export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log }) {
+export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log, hosts = null }) {
   if (!projectRoot) throw new Error('stageProjectAdapters: projectRoot is required');
   if (!packageRoot) throw new Error('stageProjectAdapters: packageRoot is required');
   const emit = typeof log === 'function' ? log : () => {};
@@ -30,8 +30,14 @@ export function stageProjectAdapters({ projectRoot, packageRoot, pkgVersion, log
     return { staged: true, synced: false };
   }
 
+  // A `hosts` array restricts which adapter sets sync writes (construct-4xy6);
+  // null/empty leaves sync writing every host, preserving the postinstall path.
+
+  const syncArgs = [syncScript, '--project'];
+  if (Array.isArray(hosts) && hosts.length > 0) syncArgs.push(`--hosts=${hosts.join(',')}`);
+
   emit(`syncing project adapters into ${projectRoot}/.claude/`);
-  const result = spawnSync(process.execPath, [syncScript, '--project'], {
+  const result = spawnSync(process.execPath, syncArgs, {
     cwd: projectRoot,
     stdio: 'inherit',
     env: { ...process.env, CONSTRUCT_PROJECT_ROOT: projectRoot },

package/lib/intent-classifier.mjs

@@ -150,7 +150,7 @@ async function defaultModelCaller({ system, user }) {
       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: modelId.replace(/^openrouter\//, ''),

package/lib/knowledge/search.mjs

@@ -11,6 +11,9 @@
  *   3. docs/README.md        — docs index + contract
  *   4. .cx/knowledge/        — operator-written internal docs
  *   5. Any *.md in docs/cookbook/ — task-oriented recipes
+ *   6. <projectRoot>/.cx/knowledge/** — the cwd project's knowledge tree,
+ *      including `external/research/` written by `construct knowledge add`,
+ *      so foreign-project queries surface project content alongside bundled docs.
  *
  * Retrieval strategy:
  *   Token-based BM25-like scoring over 200-char chunks. Returns top-K chunks
@@ -30,8 +33,17 @@ const REPO_ROOT = join(MODULE_DIR, '..', '..');
 
 // ─── Source catalogue ────────────────────────────────────────────────────────
 
-/** Priority-ordered list of source files to search. */
-function buildSourceList(repoRoot = REPO_ROOT) {
+/**
+ * Priority-ordered list of source files to search.
+ *
+ * `projectRoot` covers the case where Construct is invoked from a foreign
+ * project (cwd != construct repo): the project's own `.cx/knowledge/**` —
+ * including the `external/research/` tree written by `construct knowledge add
+ * --source=research` — joins the source set, so freshly added project knowledge
+ * surfaces alongside (and ahead of) the bundled Construct docs. When
+ * projectRoot equals repoRoot or is absent, only the bundled set is searched.
+ */
+function buildSourceList(repoRoot = REPO_ROOT, projectRoot = null) {
   const sources = [];
 
   const priority = [
@@ -92,9 +104,45 @@ function buildSourceList(repoRoot = REPO_ROOT) {
     }
   }
 
+  // Project knowledge — the cwd project's `.cx/knowledge/**`. Searched only
+  // when the project is distinct from the construct repo (the latter's own
+  // .cx/knowledge is already covered above as repoRoot's internal knowledge).
+  // Priority 1 puts project content on the same scoring tier as core docs so a
+  // freshly added project finding outranks bundled framework material on tied
+  // matches; the `source: 'project'` tag lets consumers distinguish origin.
+
+  if (projectRoot && projectRoot !== repoRoot) {
+    const projectKnowledgeRoot = join(projectRoot, '.cx', 'knowledge');
+    if (existsSync(projectKnowledgeRoot)) {
+      for (const file of walkMarkdown(projectKnowledgeRoot)) {
+        sources.push({
+          path: file,
+          rel: relative(projectRoot, file),
+          priority: 1,
+          source: 'project',
+        });
+      }
+    }
+  }
+
   return sources;
 }
 
+// Recursive .md walk used for the project-knowledge tree, where `external/`
+// nests one subdirectory deeper than the flat internal/reference/how-tos layout.
+
+function walkMarkdown(root) {
+  const out = [];
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) out.push(...walkMarkdown(full));
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
 // ─── Chunking ────────────────────────────────────────────────────────────────
 
 const CHUNK_CHARS = 400;
@@ -272,7 +320,7 @@ export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, roo
 
   const root = repoRoot ?? REPO_ROOT;
   const dataDir = rootDir ?? (process.env.CX_DATA_DIR?.trim() || homedir());
-  const sources = buildSourceList(root);
+  const sources = buildSourceList(root, rootDir);
 
   // Build corpus from docs + operator knowledge
   const allChunks = [];
@@ -318,6 +366,7 @@ export function knowledgeSearch({ query, topK = 5, minScore = 0.1, repoRoot, roo
     text: chunk.text,
     heading: chunk.heading,
     file: chunk.source.rel,
+    origin: chunk.source.source || 'bundled',
     score: Math.round(score * 100) / 100,
     lineStart: chunk.lineStart,
   }));

package/lib/mcp/server.mjs

@@ -723,19 +723,6 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         required: ['query'],
       },
     },
-    {
-      name: 'rovo_search',
-      description: 'Cross-system semantic search via Atlassian Rovo. Searches Jira, Confluence, and other accessible sources. Returns excerpts with source attribution. Does NOT store results in the observation store. Use for broad queries across all sources, not just focal projects.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          query: { type: 'string', description: 'Search query (e.g., "Iverson reliability", "DR failover").' },
-          top_k: { type: 'number', description: 'Max results (default: 10, max: 50).' },
-          sources: { type: 'string', description: 'Comma-separated source filter (e.g., "jira,confluence").' },
-        },
-        required: ['query'],
-      },
-    },
     {
       name: 'efficiency_snapshot',
       description: 'Returns the read-efficiency snapshot for the current session — repeated reads, large reads, hot-spot files, and recommendations. Use this when investigating why a session feels slow or to surface optimization opportunities.',
@@ -939,6 +926,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: { cwd: { type: 'string', description: 'Project root (default: server cwd).' } },
       },
     },
+    {
+      name: 'document_export',
+      description: 'Convert a markdown file into a distributable PDF, DOCX, or HTML document via Pandoc (DOCX/HTML) and Typst (PDF engine), per ADR-0024. Both engines are optional system binaries discovered at runtime — the tool returns a structured "install <binary>" error when tooling is absent, never crashes. Use `detect_only=true` to check availability without running an export.',
+      inputSchema: {
+        type: 'object',
+        required: ['format'],
+        properties: {
+          input_path: { type: 'string', description: 'Absolute path to the markdown source file (required unless detect_only=true).' },
+          output_path: { type: 'string', description: 'Optional absolute output path; defaults to <input>.<format> next to the source.' },
+          format: { type: 'string', enum: ['pdf', 'docx', 'html'], description: 'Target format.' },
+          detect_only: { type: 'boolean', description: 'When true, report binary availability without exporting. Default false.' },
+        },
+      },
+    },
     {
       name: 'knowledge_search',
       description: 'Search Construct\'s own documentation, knowledge base, and distilled embed observations. Call this immediately — no approval needed — when the user asks what Construct is, how a feature works, what commands exist, or anything about Construct\'s architecture or configuration. Also searches embed observations from GitHub, Jira, and other configured sources. Returns relevant excerpts with source file and heading.',
@@ -1176,6 +1177,38 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
       },
     },
+    {
+      name: 'orchestration_run',
+      description: 'EXECUTE a real multi-specialist orchestration run via the local Construct daemon and return per-specialist output — the executing counterpart to workflow_invoke (which only plans). For MCP hosts with no subagent primitive (VS Code/Copilot, Cursor), this is how you actually run a specialist chain: the engine owns orchestration, this tool is the thin client (ADR-0022). Requires a running daemon (`construct dashboard`); if it is unreachable the tool fails fast with how to start it rather than silently degrading to a single-persona pass. Real specialist output requires the daemon to run the `provider` worker backend (a provider key configured); the default `inline` backend prepares tasks only.',
+      inputSchema: {
+        type: 'object',
+        required: ['request'],
+        properties: {
+          request: { type: 'string', description: 'Natural-language description of the work to orchestrate (e.g. "refactor the auth module and review it for security").' },
+          workflow_type: { type: 'string', description: 'Optional workflow type to shape the plan (e.g. architecture-review, risk-review).' },
+          requested_strategy: { type: 'string', enum: ['orchestrated', 'prompt-only', 'auto'], description: 'Execution strategy (default auto).' },
+          worker_backend: { type: 'string', enum: ['inline', 'provider'], description: 'provider executes specialists (needs a provider key); inline prepares only. Default: daemon config.' },
+          host: { type: 'string', description: 'Host/IDE identifier (advisory).' },
+          host_model: { type: 'string', description: 'Model the host uses, for model resolution.' },
+          host_provider: { type: 'string', description: 'Provider family the host uses, for model resolution.' },
+          file_count: { type: 'number', description: 'Optional planning hint: number of files in scope.' },
+          module_count: { type: 'number', description: 'Optional planning hint: number of modules in scope.' },
+          wait: { type: 'boolean', description: 'Wait for the run to reach a terminal state and return task output (default true). false returns the runId immediately to poll with orchestration_status.' },
+          timeout_ms: { type: 'number', description: 'Max time to wait when wait=true (default 120000). On timeout the runId is returned to poll.' },
+        },
+      },
+    },
+    {
+      name: 'orchestration_status',
+      description: 'Inspect orchestration runs on the local Construct daemon: pass run_id for the full record (status, per-task status/executor/output/error), or omit it for a list of recent runs. Fails fast if the daemon is unreachable.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          run_id: { type: 'string', description: 'Run id to fetch. Omit to list recent runs.' },
+          limit: { type: 'number', description: 'Max runs to list when run_id is omitted (default 20).' },
+        },
+      },
+    },
   ],
 }));
 
@@ -1227,7 +1260,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'session_search') result = sessionSearch(args);
     else if (name === 'session_save') result = sessionSave(args);
     else if (name === 'memory_search') result = await memorySearch(args);
-    else if (name === 'memory_add_observations') result = memoryAddObservations(args);
+    else if (name === 'memory_add_observations') result = await memoryAddObservations(args);
     else if (name === 'memory_create_entities') result = memoryCreateEntities(args);
     else if (name === 'memory_recent') result = memoryRecent(args);
     else if (name === 'rovo_search') result = await rovoSearch(args);
@@ -1241,6 +1274,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { knowledgeSearch } = await import('../knowledge/search.mjs');
       result = knowledgeSearch({ query: args.query, topK: args.top_k, repoRoot: args.repo_root, rootDir: args.root_dir });
     }
+    else if (name === 'document_export') {
+      const { detect, exportMarkdown } = await import('../document-export.mjs');
+      if (args.detect_only) {
+        result = detect(args.format);
+      } else {
+        result = exportMarkdown({ inputPath: args.input_path, outputPath: args.output_path, format: args.format });
+      }
+    }
     else if (name === 'profile_show') result = profileShow(args);
     else if (name === 'profile_list') result = profileList();
     else if (name === 'profile_drafts') result = profileDrafts(args);
@@ -1258,6 +1299,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     else if (name === 'workflow_invoke') result = await workflowInvoke(args);
     else if (name === 'capability_describe') result = capabilityDescribe(args);
     else if (name === 'construct_execution_resolve') result = executionResolve(args);
+    else if (name === 'orchestration_run') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationRun(args); }
+    else if (name === 'orchestration_status') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationStatus(args); }
     else result = { error: `Unknown tool: ${name}` };
   } catch (err) {
     result = { error: err.message ?? String(err) };

package/lib/mcp/tools/memory.mjs

@@ -56,13 +56,13 @@ export async function memorySearch(args) {
   };
 }
 
-export function memoryAddObservations(args) {
+export async function memoryAddObservations(args) {
   const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
   const project = args.project || cwd.split('/').pop() || 'unknown';
   const observations = (args.observations || []).slice(0, 10);
   const created = [];
   for (const obs of observations) {
-    const record = addObservation(cwd, {
+    const record = await addObservation(cwd, {
       role: obs.role || 'unknown',
       category: obs.category || 'insight',
       summary: obs.summary || '',

package/lib/mcp/tools/orchestration-run.mjs

@@ -0,0 +1,125 @@
+/**
+ * lib/mcp/tools/orchestration-run.mjs — MCP client for the local orchestration daemon.
+ *
+ * Executes a real multi-specialist run by driving the daemon's HTTP API
+ * (ADR-0022), so MCP hosts with no subagent primitive — VS Code/Copilot, Cursor —
+ * reach orchestrated outcomes through a tool they actually expose: the engine
+ * owns orchestration; this tool is the thin client. The daemon URL resolves from
+ * dashboard state (else the default loopback port) and the bearer token from
+ * ~/.construct/config.env. When the daemon is unreachable the tool fails fast
+ * with an actionable error rather than silently degrading to a single-persona
+ * pass — the absence of an executable path is made loud, not hidden.
+ */
+
+import { readDashboardState } from '../../service-manager.mjs';
+import { getDashboardToken } from '../../server/auth.mjs';
+
+const TERMINAL = ['completed', 'completed-with-failures', 'cancelled', 'error'];
+
+function resolveDaemon(env = process.env) {
+  const state = readDashboardState();
+  const base = (env.CONSTRUCT_ORCHESTRATION_URL || state?.url || `http://${env.BIND_HOST || '127.0.0.1'}:${env.PORT || '4242'}`).replace(/\/$/, '');
+  return { base, token: getDashboardToken(), daemonRunning: Boolean(state) };
+}
+
+// A reachability failure is the fail-fast signal MCP hosts need: report how to
+// start the engine instead of letting the host fall back to a manual pass.
+
+function unreachable(base, detail) {
+  return {
+    error: `Orchestration daemon not reachable at ${base}: ${detail}. Start it with \`construct dashboard\`, then retry. The engine runs orchestration; this host is a thin client (ADR-0022).`,
+    daemon: base,
+    failFast: true,
+  };
+}
+
+export async function orchestrationRun(args = {}, { fetchImpl = fetch, env = process.env } = {}) {
+  const {
+    request,
+    workflow_type,
+    requested_strategy = 'auto',
+    worker_backend,
+    host,
+    host_model,
+    host_provider,
+    file_count,
+    module_count,
+    wait = true,
+    timeout_ms = 120000,
+  } = args;
+
+  if (!request || typeof request !== 'string') return { error: 'Missing "request" string describing the work to orchestrate.' };
+
+  const { base, token } = resolveDaemon(env);
+  const headers = { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
+  const body = JSON.stringify({
+    request,
+    workflowType: workflow_type,
+    requestedStrategy: requested_strategy,
+    workerBackend: worker_backend,
+    host,
+    hostModel: host_model,
+    hostProvider: host_provider,
+    fileCount: file_count,
+    moduleCount: module_count,
+  });
+
+  let started;
+  try {
+    const res = await fetchImpl(`${base}/api/orchestration/runs`, { method: 'POST', headers, body });
+    if (res.status === 401 || res.status === 403) {
+      return { error: `Daemon rejected the request (HTTP ${res.status}). The dashboard token is missing or wrong — check CONSTRUCT_DASHBOARD_TOKEN in ~/.construct/config.env.`, daemon: base, failFast: true };
+    }
+    const envelope = await res.json();
+    if (!res.ok) return { error: `Daemon error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, daemon: base };
+    started = envelope.data;
+  } catch (err) {
+    return unreachable(base, err.message);
+  }
+
+  if (!wait) {
+    return { runId: started.runId, status: started.status, executionMode: started.execution?.executionMode, daemon: base, poll: 'orchestration_status with run_id' };
+  }
+
+  const deadline = Date.now() + timeout_ms;
+  let run = started;
+  while (!TERMINAL.includes(run.status)) {
+    if (Date.now() > deadline) {
+      return { runId: started.runId, status: run.status, timedOut: true, daemon: base, note: 'Run is still executing; poll it with orchestration_status.' };
+    }
+    await new Promise((r) => setTimeout(r, 250));
+    try {
+      const res = await fetchImpl(`${base}/api/orchestration/runs/${encodeURIComponent(started.runId)}`, { headers });
+      const envelope = await res.json();
+      if (!res.ok) return { error: `Daemon error while polling (HTTP ${res.status}): ${envelope.error || 'unknown'}`, runId: started.runId, daemon: base };
+      run = envelope.data;
+    } catch (err) {
+      return { error: `Lost connection to the daemon while polling run ${started.runId}: ${err.message}`, runId: started.runId, daemon: base, failFast: true };
+    }
+  }
+
+  return {
+    runId: run.runId,
+    status: run.status,
+    executionMode: run.execution?.executionMode,
+    degraded: run.execution?.degraded ?? false,
+    degradationReason: run.execution?.degradationReason ?? null,
+    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, output: t.output ?? null, reasoning: t.reasoning ?? null, error: t.error ?? null })),
+    daemon: base,
+  };
+}
+
+export async function orchestrationStatus(args = {}, { fetchImpl = fetch, env = process.env } = {}) {
+  const { run_id, limit = 20 } = args;
+  const { base, token } = resolveDaemon(env);
+  const headers = token ? { Authorization: `Bearer ${token}` } : {};
+  const path = run_id ? `/api/orchestration/runs/${encodeURIComponent(run_id)}` : `/api/orchestration/runs?limit=${encodeURIComponent(limit)}`;
+  try {
+    const res = await fetchImpl(`${base}${path}`, { headers });
+    const envelope = await res.json();
+    if (!res.ok) return { error: `Daemon error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, daemon: base };
+    return envelope.data;
+  } catch (err) {
+    return unreachable(base, err.message);
+  }
+}