@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/mcp/tool-safety.mjs

@@ -0,0 +1,95 @@
+/**
+ * lib/mcp/tool-safety.mjs — per-tool safety classification for the MCP catalog.
+ *
+ * One entry per tool name in lib/mcp/server.mjs's ALL_TOOL_DEFS (plus the `call`
+ * gateway). `class` is the host-facing risk tier; `filesystem`/`network`/`process`
+ * name which resource classes the tool can touch, derived from each tool's own
+ * description and input schema. withSafetyEnvelope (server.mjs) throws if a tool
+ * is missing here, so a newly added tool cannot ship without classification.
+ */
+
+const READ = 'read';
+const WRITE = 'write';
+const DESTRUCTIVE = 'destructive';
+
+export const DEFAULT_OUTPUT_SCHEMA = Object.freeze({ type: 'object' });
+
+export const TOOL_SAFETY = Object.freeze({
+  agent_health: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  summarize_diff: { class: READ, filesystem: 'read', network: 'none', process: 'spawn' },
+  scan_file: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  extract_document_text: { class: READ, filesystem: 'read', network: 'none', process: 'spawn' },
+  ingest_document: { class: WRITE, filesystem: 'write', network: 'none', process: 'spawn' },
+  infer_document_schema: { class: WRITE, filesystem: 'write', network: 'fetch', process: 'spawn' },
+  list_schema_artifacts: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  storage_status: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  storage_sync: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  storage_reset: { class: DESTRUCTIVE, filesystem: 'write', network: 'none', process: 'none' },
+  delete_ingested_artifacts: { class: DESTRUCTIVE, filesystem: 'write', network: 'none', process: 'none' },
+  project_context: { class: READ, filesystem: 'read', network: 'none', process: 'spawn' },
+  get_skill: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  orchestration_policy: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  list_skills: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  worker_run: { class: WRITE, filesystem: 'write', network: 'fetch', process: 'spawn' },
+  broker_check: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  agent_contract: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  find_tool: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  get_template: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  list_templates: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  search_skills: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  list_teams: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  suggest_skills: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  cx_trace: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  cx_score: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  cx_trace_update: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  session_list: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  session_load: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  session_search: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  session_save: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  memory_search: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  memory_add_observations: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  memory_create_entities: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  memory_recent: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  rovo_search: { class: READ, filesystem: 'none', network: 'fetch', process: 'none' },
+  efficiency_snapshot: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  session_usage: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  provider_fetch: { class: WRITE, filesystem: 'write', network: 'fetch', process: 'none' },
+  provider_write: { class: DESTRUCTIVE, filesystem: 'write', network: 'fetch', process: 'none' },
+  scope_show: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  scope_list: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  scope_drafts: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  scope_health: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  outcomes_summary: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  outcomes_record: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  knowledge_add: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  scope_create: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  scope_archive: { class: DESTRUCTIVE, filesystem: 'write', network: 'none', process: 'none' },
+  sandbox_list: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  knowledge_graph_ask: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  learning_status: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  document_export: { class: WRITE, filesystem: 'write', network: 'none', process: 'spawn' },
+  publish_detect: { class: READ, filesystem: 'read', network: 'none', process: 'spawn' },
+  publish_run: { class: WRITE, filesystem: 'write', network: 'none', process: 'spawn' },
+  knowledge_search: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  workflow_init: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  workflow_add_task: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  workflow_update_task: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  workflow_needs_main_input: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  workflow_validate: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  workflow_status: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  workflow_contract_validate: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  workflow_import_plan: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  cx_trace_telemetry: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  artifact_workflow: { class: WRITE, filesystem: 'write', network: 'none', process: 'spawn' },
+  author_artifact: { class: WRITE, filesystem: 'write', network: 'none', process: 'none' },
+  model_resolve: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  triage_recommend: { class: READ, filesystem: 'read', network: 'none', process: 'spawn' },
+  workflow_invoke: { class: WRITE, filesystem: 'write', network: 'none', process: 'spawn' },
+  capability_describe: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  construct_execution_resolve: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  orchestration_run: { class: WRITE, filesystem: 'write', network: 'fetch', process: 'none' },
+  web_search: { class: READ, filesystem: 'none', network: 'fetch', process: 'none' },
+  orchestration_status: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  orchestration_readiness: { class: READ, filesystem: 'read', network: 'none', process: 'none' },
+  call: { class: DESTRUCTIVE, filesystem: 'write', network: 'fetch', process: 'spawn' },
+});

package/lib/mcp/tool-surface-parity.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/mcp/tool-surface-parity.mjs — partition invariant for the MCP tool surface.
+ *
+ * The exposed surface is split into a flat core (CORE_TOOL_NAMES) and a long tail
+ * reached through the `call` gateway. Both are hand-maintained beside the catalog
+ * (ALL_TOOL_DEFS), so a typo in a core name silently drops a tool from BOTH the
+ * flat surface and the gateway enum, making it unreachable. These helpers enforce
+ * the partition from the catalog as the single source of truth: every declared
+ * core name must be a real catalog tool, and the flat core plus the gateway enum
+ * must together cover the catalog exactly once (no gap, no overlap, no phantom).
+ */
+
+// A core name that is not in the catalog is a typo or a stale entry; it must be
+// rejected loudly rather than silently dropping the tool from every surface.
+
+export function assertCoreSubsetOfCatalog(coreNames, catalog) {
+  const catalogSet = catalog instanceof Set ? catalog : new Set(catalog);
+  const phantom = [...coreNames].filter((name) => !catalogSet.has(name));
+  if (phantom.length > 0) {
+    throw new Error(
+      `tool-surface-parity: ${phantom.length} core tool name(s) absent from the catalog: ${phantom.join(', ')} — `
+      + 'a typo in CORE_TOOL_NAMES drops the tool from both the flat surface and the call enum.',
+    );
+  }
+  return true;
+}
+
+// The flat core and the gateway enum must partition the catalog exactly once.
+// Returns the partition diagnostics; assertToolSurfacePartition throws on any break.
+
+export function checkToolSurfacePartition({ catalog, flat, enumNames }) {
+  const catalogSet = catalog instanceof Set ? catalog : new Set(catalog);
+  const surfaced = [...flat, ...enumNames];
+
+  const overlap = flat.filter((name) => enumNames.includes(name));
+  const duplicates = [...new Set(surfaced.filter((name, idx) => surfaced.indexOf(name) !== idx))];
+  const missing = [...catalogSet].filter((name) => !flat.includes(name) && !enumNames.includes(name));
+  const phantom = [...new Set(surfaced.filter((name) => !catalogSet.has(name)))];
+
+  return {
+    ok: overlap.length === 0 && duplicates.length === 0 && missing.length === 0 && phantom.length === 0,
+    overlap: overlap.sort(),
+    duplicates: duplicates.sort(),
+    missing: missing.sort(),
+    phantom: phantom.sort(),
+  };
+}
+
+export function assertToolSurfacePartition({ catalog, flat, enumNames }) {
+  const result = checkToolSurfacePartition({ catalog, flat, enumNames });
+  if (!result.ok) {
+    const parts = [];
+    if (result.overlap.length) parts.push(`flat AND enum: ${result.overlap.join(', ')}`);
+    if (result.duplicates.length) parts.push(`surfaced twice: ${result.duplicates.join(', ')}`);
+    if (result.missing.length) parts.push(`unreachable: ${result.missing.join(', ')}`);
+    if (result.phantom.length) parts.push(`not in catalog: ${result.phantom.join(', ')}`);
+    throw new Error(`tool-surface-parity: partition broken — ${parts.join('; ')}`);
+  }
+  return true;
+}

package/lib/mcp/tools/orchestration-delegation-next.tool.mjs

@@ -0,0 +1,68 @@
+/**
+ * lib/mcp/tools/orchestration-delegation-next.tool.mjs — self-registered MCP
+ * tool (lib/mcp/tool-registry.mjs) that advances an orchestration-policy
+ * route's delegation chain by exactly one step (ADR-0067, construct-rf26.9).
+ *
+ * orchestration_policy classifies a request into intent/track/specialists/
+ * gates and — for a non-immediate track — the full contractChain, for a
+ * caller to read and self-sequence. This tool is the flow-engine-backed
+ * alternative for the SEQUENCING part specifically: it rebuilds the same
+ * deterministic route (routeRequest is a pure function of request/fileCount/
+ * moduleCount/introducesContract/explicitDrive) and drives its implied
+ * delegation flow (lib/orchestration/delegation-flow.mjs) one checkpointed
+ * step at a time, returning only the current specialist's delegation — never
+ * the rest of the chain. Call it once per specialist, with the same run_id,
+ * until `done` is true; state persists across calls (and across process
+ * restarts) via lib/flows/checkpoint.mjs under the machine-scoped state root.
+ */
+
+import { routeRequest } from '../../orchestration-policy.mjs';
+import { advanceDelegation } from '../../orchestration/delegation-flow.mjs';
+
+export const TOOL_DEFS = [
+  {
+    name: 'orchestration_delegation_next',
+    description:
+      'Advance a request\'s delegation chain by exactly one step. Pass the same classification inputs '
+      + 'you would give orchestration_policy (request/fileCount/moduleCount/introducesContract/explicitDrive) '
+      + 'plus a run_id you mint and keep for this dispatch (e.g. a session or task id). The first call starts '
+      + 'the chain and returns the first specialist\'s delegation; each subsequent call with the same run_id '
+      + 'returns the next one. Never returns more than the current step — act on currentDelegation only, then '
+      + 'call again. `done: true` with `currentDelegation: null` means the chain is exhausted (or the route\'s '
+      + 'track resolved to no specialists at all, e.g. immediate).',
+    inputSchema: {
+      type: 'object',
+      required: ['request', 'run_id'],
+      properties: {
+        request: { type: 'string', description: 'The same request text passed to orchestration_policy.' },
+        run_id: { type: 'string', description: 'Caller-chosen id for this dispatch. Reuse it across calls to advance the same chain.' },
+        fileCount: { type: 'number', description: 'Approximate number of files involved.' },
+        moduleCount: { type: 'number', description: 'Approximate number of modules involved.' },
+        introducesContract: { type: 'boolean', description: 'Whether the change introduces a new contract/dependency.' },
+        explicitDrive: { type: 'boolean', description: 'Whether drive/full-send mode is explicitly active.' },
+      },
+    },
+    outputSchema: { type: 'object' },
+    safety: { class: 'write', filesystem: 'write', network: 'none', process: 'none' },
+  },
+];
+
+export async function orchestrationDelegationNext(args = {}, { cwd = process.cwd() } = {}) {
+  const { request, run_id: runId } = args;
+  if (!request || typeof request !== 'string') return { error: 'Missing "request".' };
+  if (!runId || typeof runId !== 'string') return { error: 'Missing "run_id" — mint and reuse one id for this dispatch.' };
+
+  const route = routeRequest({
+    request,
+    fileCount: args.fileCount ?? 0,
+    moduleCount: args.moduleCount ?? 0,
+    introducesContract: args.introducesContract ?? false,
+    explicitDrive: args.explicitDrive ?? false,
+  });
+
+  return advanceDelegation(cwd, runId, route);
+}
+
+export const TOOL_HANDLERS = {
+  orchestration_delegation_next: orchestrationDelegationNext,
+};

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

@@ -13,16 +13,61 @@
  */
 
 import { runOrchestration, startRun, getRun, getRuns } from '../../orchestration/runtime.mjs';
+import { HOST } from '../../orchestration/worker.mjs';
+import { loadProjectConfig } from '../../config/project-config.mjs';
+import { governWebResults } from './web-search-governance.mjs';
+import { resolveNonNegativeSetting } from '../../env-config.mjs';
 
-const TERMINAL = ['completed', 'completed-with-failures', 'cancelled', 'error'];
+// Host loop instructions echoed on an awaiting-host run so the calling agent
+// never has to guess the protocol: execute each materialized prompt as that
+// specialist, submit the result, and follow next_task until it is null.
+// Worded to be un-misreadable as a failure: a VS Code host once read "did not
+// execute" as prepare-only-and-stuck, retried with worker_backend "provider",
+// and died on missing API credits — so the text must lead with success and
+// explicitly forbid that fallback.
+
+const HOST_INSTRUCTIONS =
+  'ACTION REQUIRED — this run succeeded and is now waiting on YOU, the calling agent. The host worker '
+  + 'backend means Construct materialized each specialist prompt and you execute them in your own '
+  + 'session (no API credits are spent). This is the normal path, not a failure: do NOT re-run with '
+  + 'worker_backend "provider" (real API spend, needs provider credits) and do not report the run as '
+  + 'incomplete. For each task in `tasks`, execute its `system`/`user` prompt yourself as that '
+  + 'specialist role, in order, then submit the result by calling orchestration_task_result with '
+  + '{ run_id, task_id, output }. Its response carries next_task (the next prompt to execute) or null '
+  + 'once the run is terminal — keep submitting until next_task is null, then re-read the run via '
+  + 'orchestration_status if you need the final consolidated output.';
+
+// Every state a run can rest in. `degraded` and `completed-prepare-only` are
+// terminal too — the poll loop must stop on them or a finished degraded/prepare-only
+// remote run reads as "still executing" until the overall deadline elapses.
+
+const TERMINAL = ['completed', 'completed-with-failures', 'completed-prepare-only', 'degraded', 'cancelled', 'error'];
+
+export function shapeRun(run) {
+  const hasTasks = Array.isArray(run.tasks) && run.tasks.length > 0;
+  const allPrepared = hasTasks && run.tasks.every((t) => t.status === 'prepared');
+  const degraded = run.degraded ?? run.execution?.degraded ?? false;
+
+  // Terminal-status taxonomy (construct-fbxv.1): a degraded run never surfaces as a
+  // bare 'completed'. All-prepared is the more specific "no specialist executed"
+  // signal, so it wins; otherwise any degraded run — whether it prepared zero tasks
+  // or executed with a capability gap — reports 'degraded'. Legacy runs persisted as
+  // bare 'completed' before this taxonomy are re-derived the same way.
+  const shapedStatus = allPrepared
+    ? 'completed-prepare-only'
+    : degraded && run.status === 'completed'
+      ? 'degraded'
+      : run.status;
 
-function shapeRun(run) {
   return {
     runId: run.runId,
-    status: run.status,
+    status: shapedStatus,
+    prepareOnly: allPrepared,
+    runMode: run.runMode ?? null,
+    semantics: run.semantics ?? null,
     executionMode: run.execution?.executionMode,
-    degraded: run.execution?.degraded ?? false,
-    degradationReason: run.execution?.degradationReason ?? null,
+    degraded,
+    degradationReason: run.degradationReason ?? run.execution?.degradationReason ?? null,
     intent: run.plan?.intent ?? null,
     track: run.plan?.track ?? null,
     suggestedWorkflowType: run.plan?.suggestedWorkflowType ?? null,
@@ -31,10 +76,38 @@ function shapeRun(run) {
     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,
+      webCapability: t.webCapability ?? null,
+      webEvidence: t.webEvidence ?? null,
+      webSearchRequests: t.webSearchRequests ?? 0,
+      // Host-backend fields only: the materialized prompt an awaiting-host task
+      // carries (nulled out once submitHostTaskResult records a real result),
+      // and provenanceSource — present only on a host-reported result, so it can
+      // never be confused with a construct-verified provider execution.
+      ...(t.hostPrompt ? { system: t.hostPrompt.system, user: t.hostPrompt.user } : {}),
+      ...(t.provenanceSource ? { provenanceSource: t.provenanceSource } : {}),
     })),
   };
 }
 
+// Fail-closed remote ingress guard (ADR-0050): the remote orchestration service is
+// out-of-repo and cannot be trusted to govern. Re-run every task's webEvidence through
+// the single F08 grader so a citation can never arrive trusted or ungoverned, and mark the
+// run degraded if any item was not already trust:'untrusted' with a valid Admiralty grade.
+
+export function governRemoteWebEvidence(run, now = Date.now()) {
+  let tampered = false;
+  for (const t of run.tasks || []) {
+    if (!Array.isArray(t.webEvidence) || t.webEvidence.length === 0) continue;
+    if (t.webEvidence.some((e) => e?.trust !== 'untrusted' || !/^[A-F][1-6]$/.test(e?.admiralty || ''))) tampered = true;
+    t.webEvidence = governWebResults(t.webEvidence, { now });
+  }
+  if (tampered) {
+    run.degraded = true;
+    run.degradationReason = run.degradationReason || 'remote-web-evidence-regoverned';
+  }
+  return run;
+}
+
 function toRequest(args) {
   return {
     request: args.request,
@@ -48,6 +121,27 @@ function toRequest(args) {
   };
 }
 
+// Only MCP dispatch reaches orchestrationRun() — an in-process CLI call goes
+// through runOrchestration/planRun directly (see bin/construct's `orchestrate
+// run`), never through this function — so the host-execution default belongs
+// exactly here: when the caller gave no explicit worker_backend AND the
+// project's own construct.config.json declares none, an MCP-originated run
+// defaults to the host executing specialists in its own session rather than
+// inline prepare-only or a provider API spend the caller may have no credits
+// for. The RAW (pre-default-merge) project config is the check that matters —
+// loadProjectConfig always merges DEFAULT_PROJECT_CONFIG in, so the merged
+// config's workerBackend is never actually absent; only the raw file reveals
+// whether the user configured one.
+
+function resolveMcpDefaultBackend(explicitBackend, { cwd, env }) {
+  if (explicitBackend) return explicitBackend;
+  try {
+    const { raw } = loadProjectConfig(cwd, env);
+    if (raw?.orchestration?.workerBackend) return undefined;
+  } catch { /* no resolvable config — fall through to the host default */ }
+  return HOST;
+}
+
 // A remote orchestration service is opt-in: only when CONSTRUCT_ORCHESTRATION_URL
 // is set (team / enterprise). The token comes from the Construct env, not from
 // the dashboard server, so the in-process default path carries no dashboard coupling.
@@ -67,6 +161,17 @@ function unreachable(base, detail) {
   };
 }
 
+// A bounded fetch timing out is not the same failure as a genuinely unreachable host
+// (ORCH-004 AC3): the error text must say timeout and name the bound so a healthy but
+// slow service is never misreported as network-down.
+
+function remoteFetchFailed(base, err) {
+  if (err?.name === 'RemoteFetchTimeoutError') {
+    return { error: `${err.message}. Raise CONSTRUCT_ORCHESTRATION_TIMEOUT_MS if the remote service is healthy but slow.`, service: base, failFast: true };
+  }
+  return unreachable(base, err.message);
+}
+
 export async function orchestrationRun(args = {}, { env = process.env, cwd = process.cwd(), fetchImpl = fetch } = {}) {
   const { request, worker_backend, wait = true, timeout_ms = 120000 } = args;
   if (!request || typeof request !== 'string') {
@@ -75,15 +180,17 @@ export async function orchestrationRun(args = {}, { env = process.env, cwd = pro
 
   const reqObj = toRequest(args);
   const remote = remoteService(env);
-  if (remote) return runViaService(remote, reqObj, { wait, timeout_ms, workerBackend: worker_backend, fetchImpl });
+  if (remote) return runViaService(remote, reqObj, { wait, timeout_ms, workerBackend: worker_backend, fetchImpl, env });
 
-  const opts = { env, cwd, workerBackend: worker_backend, fetchImpl };
+  const workerBackend = resolveMcpDefaultBackend(worker_backend, { cwd, env });
+  const opts = { env, cwd, workerBackend, fetchImpl };
   try {
     if (!wait) {
       const planned = await startRun(reqObj, opts);
       return { runId: planned.runId, status: planned.status, executionMode: planned.execution?.executionMode, poll: 'orchestration_status with run_id' };
     }
-    return shapeRun(await runOrchestration(reqObj, opts));
+    const shaped = shapeRun(await runOrchestration(reqObj, opts));
+    return shaped.status === 'awaiting-host' ? { ...shaped, hostInstructions: HOST_INSTRUCTIONS } : shaped;
   } catch (err) {
     return { error: `Orchestration failed: ${err.message}`, failFast: true };
   }
@@ -92,13 +199,16 @@ export async function orchestrationRun(args = {}, { env = process.env, cwd = pro
 export async function orchestrationStatus(args = {}, { env = process.env, cwd = process.cwd(), fetchImpl = fetch } = {}) {
   const { run_id, limit = 20 } = args;
   const remote = remoteService(env);
-  if (remote) return statusViaService(remote, { run_id, limit }, { fetchImpl });
+  if (remote) return statusViaService(remote, { run_id, limit }, { fetchImpl, env });
   try {
     if (run_id) {
       const run = await getRun(cwd, run_id, { env });
-      return run || { error: `No run found with id ${run_id}.` };
+      if (!run) return { error: `No run found with id ${run_id}.` };
+      const shaped = shapeRun(run);
+      return shaped.status === 'awaiting-host' ? { ...shaped, hostInstructions: HOST_INSTRUCTIONS } : shaped;
     }
-    return await getRuns(cwd, { env, limit });
+    const runs = await getRuns(cwd, { env, limit });
+    return runs.map(shapeRun);
   } catch (err) {
     return { error: `Failed to read orchestration runs: ${err.message}` };
   }
@@ -108,13 +218,64 @@ export async function orchestrationStatus(args = {}, { env = process.env, cwd =
 // is set; the wire shape matches the standalone orchestration service's
 // /api/orchestration/runs contract (ADR-0022).
 
-async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend, fetchImpl }) {
+// Reachability fail-fast belongs to the deadline check in the poll loop, not the
+// per-request budget: a remote LLM-backed run needs a generous per-request window
+// (ORCH-004; construct-o6t8.2). Default is 30s, well above the industry reachability-probe
+// mistake this replaces, and short of the 600s ceiling the OpenAI/Anthropic SDKs use for
+// long completions — an orchestration run/status round trip is shorter-lived than that.
+// Env-overridable via the shared non-negative resolver so an explicit 0 is honored
+// (near-instant abort) rather than silently treated as unset, and garbage/negative
+// values fall back to the default instead of producing a NaN AbortSignal delay.
+
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+
+function requestTimeoutMs(env) {
+  return resolveNonNegativeSetting(env, 'CONSTRUCT_ORCHESTRATION_TIMEOUT_MS', DEFAULT_REQUEST_TIMEOUT_MS);
+}
+
+// Per-request bound on every remote fetch (ORCH-004; construct-o6t8.2 / construct-neq9.6):
+// a timer aborts the request at perRequestMs and races it against a timeout rejection, so
+// a hung request settles the call even when the underlying fetch ignores its own signal.
+// The timer is cleared the instant either side of the race wins, so a healthy fast response
+// leaves no scheduled timer alive to fire and resolve a promise outside its own async scope
+// — the leak that tripped node:test's "resolution still pending after the loop resolved". The
+// rejection carries the numbered RemoteFetchTimeoutError so a bounded timeout stays
+// distinguishable from a genuinely unreachable host, never the signal's own DOMException
+// message ("aborted due to timeout" with no number).
+
+class RemoteFetchTimeoutError extends Error {
+  constructor(perRequestMs) {
+    super(`Remote orchestration request timed out after ${perRequestMs}ms`);
+    this.name = 'RemoteFetchTimeoutError';
+    this.timeoutMs = perRequestMs;
+  }
+}
+
+async function timedRemoteFetch(fetchImpl, url, opts, perRequestMs) {
+  const controller = new AbortController();
+  let clearTimer;
+  const timeout = new Promise((_, reject) => {
+    const timer = setTimeout(() => {
+      const err = new RemoteFetchTimeoutError(perRequestMs);
+      controller.abort(err);
+      reject(err);
+    }, perRequestMs);
+    clearTimer = () => clearTimeout(timer);
+  });
+  try {
+    return await Promise.race([fetchImpl(url, { ...opts, signal: controller.signal }), timeout]);
+  } finally {
+    clearTimer();
+  }
+}
+
+async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend, fetchImpl, env = process.env, perRequestTimeoutMs = requestTimeoutMs(env) } = {}) {
   const { base, token } = remote;
   const headers = { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) };
   const body = JSON.stringify({ ...reqObj, workerBackend });
   let started;
   try {
-    const res = await fetchImpl(`${base}/api/orchestration/runs`, { method: 'POST', headers, body });
+    const res = await timedRemoteFetch(fetchImpl, `${base}/api/orchestration/runs`, { method: 'POST', headers, body }, perRequestTimeoutMs);
     if (res.status === 401 || res.status === 403) {
       return { error: `Remote service rejected the request (HTTP ${res.status}). Set CONSTRUCT_ORCHESTRATION_TOKEN (or CONSTRUCT_DASHBOARD_TOKEN).`, service: base, failFast: true };
     }
@@ -122,7 +283,7 @@ async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend,
     if (!res.ok) return { error: `Remote service error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, service: base };
     started = envelope.data;
   } catch (err) {
-    return unreachable(base, err.message);
+    return remoteFetchFailed(base, err);
   }
 
   if (!wait) {
@@ -137,27 +298,44 @@ async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend,
     }
     await new Promise((r) => setTimeout(r, 250));
     try {
-      const res = await fetchImpl(`${base}/api/orchestration/runs/${encodeURIComponent(started.runId)}`, { headers });
+      const res = await timedRemoteFetch(fetchImpl, `${base}/api/orchestration/runs/${encodeURIComponent(started.runId)}`, { headers }, perRequestTimeoutMs);
       const envelope = await res.json();
       if (!res.ok) return { error: `Remote service error while polling (HTTP ${res.status}): ${envelope.error || 'unknown'}`, runId: started.runId, service: base };
       run = envelope.data;
     } catch (err) {
+      if (err?.name === 'RemoteFetchTimeoutError') {
+        return { error: `${err.message} while polling run ${started.runId}. Raise CONSTRUCT_ORCHESTRATION_TIMEOUT_MS if the remote service is healthy but slow.`, runId: started.runId, service: base, failFast: true };
+      }
       return { error: `Lost connection to the remote service while polling run ${started.runId}: ${err.message}`, runId: started.runId, service: base, failFast: true };
     }
   }
-  return { ...shapeRun(run), service: base };
+  return { ...shapeRun(governRemoteWebEvidence(run)), service: base };
 }
 
-async function statusViaService(remote, { run_id, limit }, { fetchImpl }) {
+// The status poll GET carries the same AbortSignal bound as the run POST (ORCH-004),
+// so a service that accepts the connection but never replies cannot hang this call
+// indefinitely. `timeoutMs` is overridable directly for tests; production callers
+// resolve it from env the same way runViaService does.
+
+export async function statusViaService(remote, { run_id, limit } = {}, { fetchImpl, env = process.env, timeoutMs = requestTimeoutMs(env) } = {}) {
   const { base, token } = remote;
   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 res = await timedRemoteFetch(fetchImpl, `${base}${path}`, { headers }, timeoutMs);
     const envelope = await res.json();
     if (!res.ok) return { error: `Remote service error (HTTP ${res.status}): ${envelope.error || 'unknown'}`, service: base };
+    // The remote service is out-of-repo and cannot be trusted to have governed its
+    // own web evidence (ADR-0050); re-run every run through the F08 grader on the
+    // status path exactly as runViaService does, so a citation can never arrive
+    // pre-marked trusted. shapeRun then applies the honest terminal-status taxonomy.
+    if (Array.isArray(envelope.data)) {
+      return envelope.data.map((r) => shapeRun(governRemoteWebEvidence(r)));
+    } else if (envelope.data) {
+      return shapeRun(governRemoteWebEvidence(envelope.data));
+    }
     return envelope.data;
   } catch (err) {
-    return unreachable(base, err.message);
+    return remoteFetchFailed(base, err);
   }
 }

package/lib/mcp/tools/orchestration-task-result.tool.mjs

@@ -0,0 +1,77 @@
+/**
+ * lib/mcp/tools/orchestration-task-result.tool.mjs — self-registered MCP tool
+ * (LMCP-B5, lib/mcp/tool-registry.mjs) that ingests one host-executed
+ * specialist task result for a run planned with worker_backend=host.
+ *
+ * orchestration_run materializes each specialist's prompt (system + user turn)
+ * and stands the run at 'awaiting-host' without ever calling a model itself —
+ * the calling host executes each prompt in its own session (the model/
+ * subscription it is already running under) and reports the result back here.
+ * submitHostTaskResult (lib/orchestration/runtime.mjs) is the single place that
+ * validates and records the result and finalizes the run once every task is
+ * terminal; this file only shapes that call as an MCP tool and echoes back the
+ * next materialized prompt so a host can drive the whole run in a simple loop:
+ * call orchestration_run once, then call this tool per task until next_task
+ * is null.
+ */
+
+import { submitHostTaskResult } from '../../orchestration/runtime.mjs';
+import { shapeRun } from './orchestration-run.mjs';
+
+export const TOOL_DEFS = [
+  {
+    name: 'orchestration_task_result',
+    description:
+      'Submit one host-executed specialist task result for an orchestration run planned with '
+      + 'worker_backend=host (the MCP default). orchestration_run returns each task\'s materialized '
+      + 'prompt (system/user) without executing it; execute that prompt yourself as the named '
+      + 'specialist role, then call this tool with the run_id, task_id, and your output. The '
+      + 'response carries next_task (the next awaiting prompt) or null once the run is terminal — '
+      + 'loop until null. model/provider/reasoning are optional, self-reported fields (never '
+      + 'independently verified), recorded with provenanceSource "host-reported".',
+    inputSchema: {
+      type: 'object',
+      required: ['run_id', 'task_id', 'output'],
+      properties: {
+        run_id: { type: 'string', description: 'The run id returned by orchestration_run.' },
+        task_id: { type: 'string', description: 'The task id this result answers (e.g. "t1"), from orchestration_run\'s task list or a prior call\'s next_task.' },
+        output: { type: 'string', description: 'The specialist output you produced for this task. Must be non-empty.' },
+        model: { type: 'string', description: 'Optional: the model you used to execute this task (self-reported).' },
+        provider: { type: 'string', description: 'Optional: the provider/vendor family you used (self-reported).' },
+        reasoning: { type: 'string', description: 'Optional: your reasoning/thinking for this task, if you want it disclosed.' },
+      },
+    },
+    outputSchema: { type: 'object' },
+    safety: { class: 'write', filesystem: 'write', network: 'none', process: 'none' },
+  },
+];
+
+/**
+ * @param {object} args   { run_id, task_id, output, model?, provider?, reasoning? }
+ * @param {object} [opts]  { env, cwd } — defaulted so this behaves identically whether called
+ *   directly (tests, CLI) or dispatched by the MCP server (which does not inject opts today,
+ *   matching orchestration_run/orchestration_status's own convention).
+ */
+export async function orchestrationTaskResult(args = {}, { env = process.env, cwd = process.cwd() } = {}) {
+  const { run_id, task_id, output, model, provider, reasoning } = args;
+  if (!run_id || typeof run_id !== 'string') return { error: 'Missing "run_id" — the run id from orchestration_run.' };
+  if (!task_id || typeof task_id !== 'string') return { error: 'Missing "task_id".' };
+
+  try {
+    const { run, nextTask } = await submitHostTaskResult(cwd, run_id, task_id, { output, model, provider, reasoning }, { env });
+    const shaped = shapeRun(run);
+    return {
+      accepted: true,
+      run_status: shaped.status,
+      next_task: nextTask
+        ? { task_id: nextTask.id, role: nextTask.role, system: nextTask.hostPrompt?.system ?? null, user: nextTask.hostPrompt?.user ?? null }
+        : null,
+    };
+  } catch (err) {
+    return { accepted: false, error: err.message, code: err.code || 'HOST_RESULT_REJECTED' };
+  }
+}
+
+export const TOOL_HANDLERS = {
+  orchestration_task_result: orchestrationTaskResult,
+};