@geraldmaron/construct 1.4.2 → 1.5.0

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

@@ -13,19 +13,60 @@
  */
 
 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) {
-  const allPrepared = Array.isArray(run.tasks) && run.tasks.length > 0 && run.tasks.every((t) => t.status === 'prepared');
   return {
     runId: run.runId,
-    status: allPrepared ? 'completed-prepare-only' : run.status,
+    status: shapedStatus,
     prepareOnly: allPrepared,
+    runMode: run.runMode ?? null,
     semantics: run.semantics ?? null,
     executionMode: run.execution?.executionMode,
-    degraded: run.degraded ?? run.execution?.degraded ?? false,
+    degraded,
     degradationReason: run.degradationReason ?? run.execution?.degradationReason ?? null,
     intent: run.plan?.intent ?? null,
     track: run.plan?.track ?? null,
@@ -35,10 +76,15 @@ 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,
-      // ADR-0050: which web grant reached the web, the F08-governed evidence, and search count.
       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 } : {}),
     })),
   };
 }
@@ -75,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.
@@ -94,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') {
@@ -102,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 };
   }
@@ -119,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}` };
   }
@@ -135,18 +218,58 @@ 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).
 
-// Per-request AbortSignal so a single hung fetch cannot stall runViaService
-// past a deterministic window even before the poll loop's overall deadline check.
+// 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;
+  }
+}
 
-function timedRemoteFetch(fetchImpl, url, opts, perRequestMs) {
-  const signal = AbortSignal.timeout(perRequestMs);
-  return Promise.race([
-    fetchImpl(url, { ...opts, signal }),
-    new Promise((_, reject) => signal.addEventListener('abort', () => reject(signal.reason ?? new Error(`remote orchestration fetch timed out after ${perRequestMs}ms`)), { once: true })),
-  ]);
+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, perRequestTimeoutMs = 200 }) {
+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 });
@@ -160,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) {
@@ -180,22 +303,39 @@ async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend,
       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(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,
+};

package/lib/mcp/tools/provider-write.mjs

@@ -0,0 +1,187 @@
+/**
+ * lib/mcp/tools/provider-write.mjs — provider_write MCP tool (LMCP-I7).
+ *
+ * The only MCP-reachable path from a host agent (Claude Code, OpenCode) to an
+ * external write. Classified destructive in lib/mcp/tool-safety.mjs, so
+ * server.mjs's dispatch-time checkDestructiveGate() call already refuses the
+ * execute path without a valid out-of-band approval_token before this module
+ * ever runs — this file does not re-implement that check, it is downstream
+ * of it.
+ *
+ * Two modes, selected by `dry_run` (default true):
+ *   - dry_run=true: resolves the governed-write adapter for `provider` and
+ *     asks it to render the payload it would submit (adapter.renderDryRun),
+ *     which runs field/shape validation only. Never calls
+ *     lib/writes/envelope.mjs and never reaches adapter.write() — no network
+ *     call, no side effect, regardless of token presence.
+ *   - dry_run=false (execute): the destructive gate has already run in
+ *     server.mjs by the time dispatchToolByName reaches this module, so
+ *     arriving here at all means a token was consumed. Dispatches through
+ *     writeWithEnvelope() (LMCP-J2) — idempotency key, sent-log dedup,
+ *     policy/approval gate, retry, audit — which is the only caller of
+ *     adapter.write(). This module never calls adapter.write() directly.
+ *
+ * E4 respect: when args.specialist_id is present (an embedded-specialist
+ * caller), the proposed provider+writeKind is checked against that
+ * specialist's embedBindings grant via AuthorityGuard before either mode
+ * proceeds. A specialist outside its grant is denied here, before the
+ * adapter is even resolved — independent of and in addition to the
+ * destructive-gate token check server.mjs already performed.
+ */
+
+import { writeWithEnvelope } from '../../writes/envelope.mjs';
+import { WriteSentLog } from '../../writes/sent-log.mjs';
+import { AuthorityGuard } from '../../embed/authority-guard.mjs';
+import { mergedEmbedBindings } from '../../embed/capability-jobs.mjs';
+import { createGovernedJiraProvider } from '../../providers/contract/adapters/jira/governed-write.mjs';
+import { createJiraTransport } from '../../providers/contract/adapters/jira/transport.mjs';
+import { createGovernedConfluenceProvider } from '../../providers/contract/adapters/confluence/governed-write.mjs';
+import { createConfluenceTransport } from '../../providers/contract/adapters/confluence/transport.mjs';
+import { createGovernedGithubProvider } from '../../providers/contract/adapters/github/governed-write.mjs';
+import githubAdapter from '../../providers/contract/adapters/github/index.mjs';
+
+// Real transports read credentials from process.env at construction time
+// (JIRA_URL/JIRA_EMAIL/JIRA_TOKEN, CONFLUENCE_URL/CONFLUENCE_EMAIL/
+// CONFLUENCE_TOKEN); github's transport is the gh CLI, already
+// credential-free at construction. Building the transport lazily per call
+// (rather than once at module load) keeps a missing-credential AuthError
+// scoped to the one call that needed it.
+
+const ADAPTER_FACTORIES = {
+  jira: () => createGovernedJiraProvider({ jiraTransport: createJiraTransport() }),
+  confluence: () => createGovernedConfluenceProvider({ confluenceTransport: createConfluenceTransport() }),
+  github: () => createGovernedGithubProvider({ ghAdapter: githubAdapter }),
+};
+
+/**
+ * Resolve the governed-write adapter for a provider name. Isolated as its
+ * own function so tests can override resolution via the `deps.resolveAdapter`
+ * injection point without touching this module's real-transport wiring.
+ *
+ * @param {string} provider
+ * @returns {{ meta: object, write: Function, search?: Function, renderDryRun?: Function }}
+ */
+function resolveAdapter(provider) {
+  const factory = ADAPTER_FACTORIES[provider];
+  if (!factory) {
+    const known = Object.keys(ADAPTER_FACTORIES).join(', ');
+    throw new Error(`provider_write: unknown provider "${provider}" (known: ${known})`);
+  }
+  return factory();
+}
+
+/**
+ * Check an embedded-specialist caller's proposal against its embedBindings
+ * grant. Returns null (no opinion) when args carries no specialist_id, so
+ * non-embed callers are unaffected — additive enforcement layered in front
+ * of the destructive gate, mirroring lib/embed/capability-jobs.mjs's
+ * checkProposalAuthority for the daemon path.
+ *
+ * @param {object} args
+ * @param {{ rootDir?: string, env?: object, embedBindings?: object }} opts
+ * @returns {Promise<{ allowed: boolean, reason?: string }|null>}
+ */
+async function checkE4Binding(args, { rootDir, env = process.env, embedBindings } = {}) {
+  if (!args.specialist_id) return null;
+
+  const bindings = embedBindings ?? mergedEmbedBindings({ rootDir, env });
+  const guard = new AuthorityGuard({ authority: {} }, null, bindings);
+  const result = await guard.check('externalPost', {
+    proposal: {
+      specialistId: args.specialist_id,
+      providerId: args.provider,
+      writeKind: args.item?.type,
+    },
+  });
+
+  // Only a binding-scoped denial (mode: 'denied' with no queueId) short-circuits
+  // provider_write; a queued/autonomous authority-level outcome is not this
+  // tool's concern — the destructive gate + J2 envelope already own approval.
+  if (result.mode === 'denied' && !result.allowed) {
+    return { allowed: false, reason: result.reason };
+  }
+  return null;
+}
+
+/**
+ * provider_write tool implementation.
+ *
+ * @param {object} args
+ * @param {string} args.provider - 'jira' | 'confluence' | 'github'
+ * @param {object} args.item - write payload, shape depends on provider (see governed-write.mjs per adapter)
+ * @param {boolean} [args.dry_run=true] - render-only when true; never touches adapter.write()
+ * @param {string} [args.specialist_id] - embedded-specialist caller id (LMCP-E4 binding check)
+ * @param {string} [args.idempotency_key] - explicit idempotency key forwarded to the J2 envelope
+ * @param {object} [deps] - injection points for tests
+ * @param {Function} [deps.resolveAdapter] - override adapter resolution
+ * @param {WriteSentLog} [deps.sentLog] - override sent-log instance
+ * @param {object} [deps.embedBindings] - override merged embedBindings map
+ * @param {string} [deps.rootDir]
+ * @param {object} [deps.env]
+ * @returns {Promise<object>}
+ */
+export async function providerWrite(args = {}, deps = {}) {
+  const provider = args.provider;
+  const item = args.item;
+  const dryRun = args.dry_run !== false;
+
+  if (!provider) return { error: 'provider_write: args.provider is required' };
+  if (!item || typeof item !== 'object') return { error: 'provider_write: args.item is required' };
+
+  const bindingDenial = await checkE4Binding(args, {
+    rootDir: deps.rootDir,
+    env: deps.env,
+    embedBindings: deps.embedBindings,
+  });
+  if (bindingDenial) {
+    return { status: 'denied', provider, dryRun, reason: bindingDenial.reason };
+  }
+
+  const resolve = deps.resolveAdapter ?? resolveAdapter;
+  let adapter;
+  try {
+    adapter = resolve(provider);
+  } catch (err) {
+    return { error: err.message ?? String(err) };
+  }
+
+  if (dryRun) {
+    if (typeof adapter.renderDryRun !== 'function') {
+      return {
+        status: 'dry-run',
+        provider,
+        dryRun: true,
+        diff: null,
+        note: `provider "${provider}" adapter has no renderDryRun; payload echoed verbatim, no validation performed.`,
+        payload: item,
+      };
+    }
+    try {
+      const diff = adapter.renderDryRun(item);
+      return { status: 'dry-run', provider, dryRun: true, diff };
+    } catch (err) {
+      return { status: 'dry-run-invalid', provider, dryRun: true, error: err.message ?? String(err) };
+    }
+  }
+
+  const sentLog = deps.sentLog ?? new WriteSentLog({ persistPath: WriteSentLog.resolvePersistPath(deps.rootDir ?? process.cwd()) });
+
+  const envelopeResult = await writeWithEnvelope({
+    provider: adapter,
+    config: {},
+    payload: item,
+    dryRun: false,
+    sentLog,
+    idempotencyKey: args.idempotency_key,
+    requestedBy: args.specialist_id ? { role: `cx-${args.specialist_id}` } : {},
+  });
+
+  return {
+    status: envelopeResult.status,
+    provider,
+    dryRun: false,
+    envelope: envelopeResult.envelope,
+  };
+}
+
+export default providerWrite;

package/lib/mcp/tools/scope.mjs

@@ -201,9 +201,6 @@ export function scopeCreate(args = {}) {
 // Mutating, gated, destructive: archive a curated scope.
 
 export function scopeArchive(args = {}) {
-  if (args.confirm !== true) {
-    return { error: 'scope_archive requires confirm=true (destructive: moves files into archive/scopes/)' };
-  }
   if (!args.id || !args.reason || String(args.reason).trim().length < 8) {
     return { error: 'scope_archive requires id:string and reason:string (>=8 chars)' };
   }

package/lib/mcp/tools/skills.mjs

@@ -253,7 +253,7 @@ export async function orchestrationPolicy(args) {
       const { emitTraceEvent, newTraceId } = await import('../../worker/trace.mjs');
       const cwd = process.cwd();
       const queue = createIntakeQueue(cwd, process.env);
-      const intake = queue.read(intakeId);
+      const intake = await queue.read(intakeId);
       if (!intake) {
         intakeError = `intake packet not found: ${intakeId}`;
       } else if (!intake.triage) {

package/lib/mcp/tools/storage.mjs

@@ -8,8 +8,6 @@
 import { resolve } from 'node:path';
 import { deleteIngestedArtifacts, getStorageStatus, inferProjectName, purgeExpiredData, resetStorage } from '../../storage/admin.mjs';
 import { syncFileStateToSql } from '../../storage/sync.mjs';
-import { consumeApprovalToken } from '../destructive-approval.mjs';
-
 export async function storageStatus(args) {
   const cwd = args.cwd ? resolve(String(args.cwd)) : process.cwd();
   const project = args.project ? String(args.project) : inferProjectName(cwd);
@@ -36,9 +34,6 @@ export async function storageReset(args) {
   if (args.confirm !== true) {
     return { error: 'storage_reset requires confirm=true' };
   }
-  if (!consumeApprovalToken('storage_reset', args.approval_token)) {
-    return { error: 'storage_reset requires a valid out-of-band approval token; confirm=true alone is not authorization' };
-  }
   return resetStorage(cwd, {
     env: process.env,
     project,
@@ -53,9 +48,6 @@ export async function deleteIngestedArtifactsTool(args) {
   if (args.confirm !== true) {
     return { error: 'delete_ingested_artifacts requires confirm=true' };
   }
-  if (!consumeApprovalToken('delete_ingested_artifacts', args.approval_token)) {
-    return { error: 'delete_ingested_artifacts requires a valid out-of-band approval token; confirm=true alone is not authorization' };
-  }
   const files = Array.isArray(args.files)
     ? args.files.map((value) => String(value))
     : [];