@geraldmaron/construct 1.4.0 → 1.4.2

package/lib/mcp/tool-rate-limit.mjs

@@ -0,0 +1,47 @@
+/**
+ * lib/mcp/tool-rate-limit.mjs — per-tool call-rate budget for the MCP CallTool path.
+ *
+ * Solo deployment mode never instantiates lib/mcp/broker.mjs's Broker (that class
+ * is role/policy-based and only wired in for team/enterprise), so the live MCP
+ * dispatch path has no bound on how often a single tool can be called — a stuck
+ * loop or an injected instruction can hammer a destructive tool until it exhausts
+ * its approval tokens, or burn cost/tokens spamming a read tool. checkToolRateLimit
+ * applies a sliding-window budget tiered by safety class, independent of role.
+ */
+
+const DEFAULT_WINDOW_MS = 60_000;
+const DEFAULT_BUDGET_BY_CLASS = Object.freeze({
+  destructive: 5,
+  write: 60,
+  read: 300,
+});
+
+export class ToolRateLimited extends Error {
+  constructor(tool, budget, windowMs) {
+    super(`rate-limited: ${tool} exceeded ${budget} calls per ${Math.round(windowMs / 1000)}s`);
+    this.name = 'ToolRateLimited';
+    this.tool = tool;
+  }
+}
+
+export class ToolRateLimiter {
+  constructor({ budgetByClass = DEFAULT_BUDGET_BY_CLASS, windowMs = DEFAULT_WINDOW_MS, now = () => Date.now() } = {}) {
+    this.budgetByClass = budgetByClass;
+    this.windowMs = windowMs;
+    this.now = now;
+    this.calls = new Map();
+  }
+
+  // Disabled when windowMs is falsy (0/NaN), mirroring the existing
+  // CONSTRUCT_MCP_TOOL_TIMEOUT_MS override convention in lib/mcp/server.mjs.
+
+  check(tool, safetyClass) {
+    if (!this.windowMs) return;
+    const budget = this.budgetByClass[safetyClass] ?? this.budgetByClass.read;
+    const ts = this.now();
+    const fresh = (this.calls.get(tool) || []).filter((t) => ts - t < this.windowMs);
+    if (fresh.length >= budget) throw new ToolRateLimited(tool, budget, this.windowMs);
+    fresh.push(ts);
+    this.calls.set(tool, fresh);
+  }
+}

package/lib/mcp/tool-safety.mjs

@@ -0,0 +1,94 @@
+/**
+ * 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' },
+  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-run.mjs

@@ -13,16 +13,20 @@
  */
 
 import { runOrchestration, startRun, getRun, getRuns } from '../../orchestration/runtime.mjs';
+import { governWebResults } from './web-search-governance.mjs';
 
 const TERMINAL = ['completed', 'completed-with-failures', 'cancelled', 'error'];
 
 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: run.status,
+    status: allPrepared ? 'completed-prepare-only' : run.status,
+    prepareOnly: allPrepared,
+    semantics: run.semantics ?? null,
     executionMode: run.execution?.executionMode,
-    degraded: run.execution?.degraded ?? false,
-    degradationReason: run.execution?.degradationReason ?? null,
+    degraded: run.degraded ?? run.execution?.degraded ?? false,
+    degradationReason: run.degradationReason ?? run.execution?.degradationReason ?? null,
     intent: run.plan?.intent ?? null,
     track: run.plan?.track ?? null,
     suggestedWorkflowType: run.plan?.suggestedWorkflowType ?? null,
@@ -31,10 +35,33 @@ 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,
     })),
   };
 }
 
+// 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,
@@ -108,13 +135,24 @@ 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 }) {
+// Per-request AbortSignal so a single hung fetch cannot stall runViaService
+// past a deterministic window even before the poll loop's overall deadline check.
+
+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 runViaService(remote, reqObj, { wait, timeout_ms, workerBackend, fetchImpl, perRequestTimeoutMs = 200 }) {
   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 };
     }
@@ -137,7 +175,7 @@ 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;
@@ -145,7 +183,7 @@ async function runViaService(remote, reqObj, { wait, timeout_ms, workerBackend,
       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 }) {

package/lib/mcp/tools/project.mjs

@@ -8,7 +8,8 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { loadRegistry } from '../../registry/loader.mjs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import { resolveWithinRoot } from '../../path-policy.mjs';
 import { loadConstructEnv } from '../../env-config.mjs';
 import { inspectContextState } from '../../context-state.mjs';
 import { loadWorkflow, summarizeWorkflow, inspectWorkflowHealth } from '../../workflow-state.mjs';
@@ -16,8 +17,11 @@ import { resolveExecutionContractModelMetadata, selectModelTierForWorkCategory }
 import { buildPublicHealthSurface } from '../../status.mjs';
 import { doctorRoot } from '../../config/xdg.mjs';
 
-export function exec(cmd, cwd) {
-  return execSync(cmd, { stdio: 'pipe', timeout: 10000, cwd }).toString().trim();
+// Model-controlled refs reach these git calls. Run git through argv with no shell so a
+// base_ref like `$(...)` is handed to git as one literal argument, never evaluated.
+
+function runGit(argv, cwd) {
+  return execFileSync('git', argv, { stdio: 'pipe', timeout: 10000, cwd }).toString().trim();
 }
 
 export function readJSON(filePath) {
@@ -140,10 +144,16 @@ export function summarizeDiff(args) {
   const baseRef = args.base_ref ?? 'HEAD~1';
   const cwd = args.cwd ? resolve(args.cwd) : process.cwd();
 
+  // A ref that starts with `-` would be read by git as an option, not a revision;
+  // control characters never belong in a ref. Reject both before argv handoff.
+  if (typeof baseRef !== 'string' || baseRef.startsWith('-') || /[\0\n\r]/.test(baseRef)) {
+    return { error: 'Invalid base_ref' };
+  }
+
   let stat, nameStatus;
   try {
-    stat = exec(`git diff --stat ${baseRef}`, cwd);
-    nameStatus = exec(`git diff --name-status ${baseRef}`, cwd);
+    stat = runGit(['diff', '--stat', baseRef], cwd);
+    nameStatus = runGit(['diff', '--name-status', baseRef], cwd);
   } catch {
     return { error: 'Not a git repository or git not available' };
   }
@@ -184,7 +194,14 @@ export function summarizeDiff(args) {
 }
 
 export function scanFile(args) {
-  const filePath = resolve(args.file_path);
+  const root = args.cwd ? resolve(args.cwd) : process.cwd();
+
+  let filePath;
+  try {
+    filePath = resolveWithinRoot(root, args.file_path);
+  } catch (err) {
+    return { error: err.message };
+  }
 
   let rawBuffer;
   try {
@@ -302,14 +319,14 @@ export function projectContext(args, { ROOT_DIR }) {
   let changed_files = [];
 
   try {
-    const log = exec('git log --oneline -10', cwd);
+    const log = runGit(['log', '--oneline', '-10'], cwd);
     recent_commits = log.split('\n').filter(Boolean);
   } catch {
     // not a git repo or no commits
   }
 
   try {
-    const status = exec('git status --short', cwd);
+    const status = runGit(['status', '--short'], cwd);
     const statusLines = status.split('\n').filter(Boolean);
     changed_files = statusLines.map((l) => l.trim());
     working_tree_status = statusLines.length > 0 ? 'dirty' : 'clean';

package/lib/mcp/tools/storage.mjs

@@ -2,11 +2,13 @@
  * lib/mcp/tools/storage.mjs — Storage MCP tools: status, sync, reset, and artifact deletion.
  *
  * All functions are async. Wraps lib/storage/admin.mjs and lib/storage/sync.mjs.
- * Requires confirm=true guards on destructive operations (reset, delete).
+ * Destructive operations (reset, delete) require confirm=true plus a one-time out-of-band
+ * approval token, since these tools are reachable only through the model's argument channel.
  */
 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();
@@ -34,6 +36,9 @@ 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,
@@ -48,6 +53,9 @@ 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))
     : [];

package/lib/mcp/tools/web-search-governance.mjs

@@ -0,0 +1,96 @@
+/**
+ * lib/mcp/tools/web-search-governance.mjs — the single F08 grader for web evidence.
+ *
+ * Every web result any specialist or tool ever sees passes through governWebResults here,
+ * so the F08 governance invariants (ADR-0017) are produced in exactly one place: a
+ * claim-relative class, an Admiralty grade defaulting to C3 with a derived confidence,
+ * a normalized date with a 12-month staleness flag, most-recent-first ordering, and the
+ * OWASP-LLM01 `trust: 'untrusted'` stamp on externally-sourced text. Results without a
+ * verifiable http(s) URL are dropped, never guessed. web-search.mjs (the governed
+ * provider tool), the orchestration worker's provider-native web path, and the remote
+ * orchestration ingress guard all re-use this grader so a citation can never reach a
+ * specialist ungoverned or mislabeled as trusted.
+ */
+
+const COMMUNITY_HOSTS = ['reddit.com', 'stackoverflow.com', 'news.ycombinator.com', 'discord.com', 'github.com'];
+const HIGH_CONFIDENCE_GRADES = new Set(['A1', 'A2', 'B1']);
+const STALE_AFTER_DAYS = 365;
+
+export function normalizeDate(it) {
+  const raw = it.date || it.publishedAt || it.published || it.published_at || it.datePublished || null;
+  if (!raw) return null;
+  const t = Date.parse(raw);
+  return Number.isNaN(t) ? null : new Date(t).toISOString().slice(0, 10);
+}
+
+// Claim-relative class (ADR-0017): community content is admissible primary evidence for
+// sentiment/demand claims under a checklist the tool cannot verify deterministically, so
+// community hosts default to `tertiary` (conservative for factual claims) and everything
+// else to `secondary`, leaving the researcher to promote a community source when the claim
+// is about experience.
+
+export function classifyResult(url) {
+  try {
+    const host = new URL(url).hostname.replace(/^www\./, '');
+    return COMMUNITY_HOSTS.some((h) => host === h || host.endsWith('.' + h)) ? 'tertiary' : 'secondary';
+  } catch {
+    return 'tertiary';
+  }
+}
+
+// Confidence maps from the Admiralty grade; `high` is reserved for A1/A2/B1 (ADR-0017). A
+// grade with reliability A/B or credibility 1/2 is `medium`; anything weaker is `low`.
+
+export function confidenceFromGrade(grade) {
+  if (HIGH_CONFIDENCE_GRADES.has(grade)) return 'high';
+  const reliability = grade?.[0];
+  const credibility = grade?.[1];
+  if (reliability === 'A' || reliability === 'B' || credibility === '1' || credibility === '2') return 'medium';
+  return 'low';
+}
+
+// Grade one raw item into a governed web result, or null when it carries no verifiable
+// http(s) URL. A raw item may come from a governed provider (may carry its own admiralty)
+// or a provider-native citation (never does — defaults to C3 + needsGrading).
+
+export function governWebResult(it, { now = Date.now() } = {}) {
+  if (!it || typeof it.url !== 'string' || !/^https?:\/\//.test(it.url)) return null;
+  const graded = typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty);
+  const admiralty = graded ? it.admiralty : 'C3';
+  const date = normalizeDate(it);
+  const stale = date != null && (now - Date.parse(date)) > STALE_AFTER_DAYS * 86_400_000;
+  return {
+    source: 'web',
+    url: it.url,
+    title: typeof it.title === 'string' && it.title ? it.title : it.url,
+    snippet: typeof it.snippet === 'string' ? it.snippet : '',
+    class: classifyResult(it.url),
+    admiralty,
+    confidence: confidenceFromGrade(admiralty),
+    date,
+    stale,
+    needsGrading: !graded,
+    // OWASP LLM01: web snippets are externally-sourced data — must not be treated as instructions
+    trust: 'untrusted',
+  };
+}
+
+// Order most-recent-first: fresh dated results, then undated (input order kept by the
+// stable sort), then stale ones; newest first within a tier.
+
+function recencyTier(r) {
+  return r.date && !r.stale ? 0 : r.date ? 2 : 1;
+}
+
+export function governWebResults(items, { now = Date.now() } = {}) {
+  const results = (Array.isArray(items) ? items : [])
+    .map((it) => governWebResult(it, { now }))
+    .filter(Boolean);
+  results.sort((a, b) => {
+    const t = recencyTier(a) - recencyTier(b);
+    if (t !== 0) return t;
+    if (a.date && b.date) return Date.parse(b.date) - Date.parse(a.date);
+    return 0;
+  });
+  return results;
+}

package/lib/mcp/tools/web-search.mjs

@@ -8,11 +8,12 @@
  * Admiralty grade with a derived confidence (ADR-0017) — results without a URL are dropped, not
  * guessed; (2) every result is labeled `source: 'web'` and the tool never falls back to repo/source
  * search; (3) when no governed provider is configured or the provider is unreachable, the tool
- * returns a typed degradation and zero results rather than claiming it searched the web.
+ * returns a typed degradation and zero results rather than claiming it searched the web. The grading
+ * itself lives in web-search-governance.mjs, the single chokepoint shared with the orchestration
+ * worker's provider-native web path (ADR-0050).
  */
 
-const COMMUNITY_HOSTS = ['reddit.com', 'stackoverflow.com', 'news.ycombinator.com', 'discord.com', 'github.com'];
-const HIGH_CONFIDENCE_GRADES = new Set(['A1', 'A2', 'B1']);
+import { governWebResults } from './web-search-governance.mjs';
 
 function providerConfig(env) {
   const url = env.WEB_SEARCH_URL;
@@ -20,36 +21,11 @@ function providerConfig(env) {
   return { url, key: env.WEB_SEARCH_KEY || null };
 }
 
-// Claim-relative class (ADR-0017): community content is admissible primary evidence for sentiment/
-// demand claims under a checklist the tool cannot verify deterministically, so it defaults community
-// hosts to `tertiary` (conservative for factual claims) and everything else to `secondary`, leaving
-// the researcher to promote a community source to primary when the claim is about experience.
-
-function classifyResult(url) {
-  try {
-    const host = new URL(url).hostname.replace(/^www\./, '');
-    return COMMUNITY_HOSTS.some((h) => host === h || host.endsWith('.' + h)) ? 'tertiary' : 'secondary';
-  } catch {
-    return 'tertiary';
-  }
-}
-
-// Confidence maps from the Admiralty grade; `high` is reserved for A1/A2/B1 (ADR-0017). A grade with
-// reliability A/B or credibility 1/2 is `medium`; anything weaker is `low`.
-
-function confidenceFromGrade(grade) {
-  if (HIGH_CONFIDENCE_GRADES.has(grade)) return 'high';
-  const reliability = grade?.[0];
-  const credibility = grade?.[1];
-  if (reliability === 'A' || reliability === 'B' || credibility === '1' || credibility === '2') return 'medium';
-  return 'low';
-}
-
 function degraded(reason, note) {
   return { source: 'web', degraded: true, degradationReason: reason, results: [], note };
 }
 
-export async function webSearch(args = {}, { env = process.env, fetchImpl = globalThis.fetch } = {}) {
+export async function webSearch(args = {}, { env = process.env, fetchImpl = globalThis.fetch, now = Date.now() } = {}) {
   const { query, claim, recency = null } = args;
   if (!query || typeof query !== 'string') {
     return { error: { code: 'INVALID_INPUT', message: 'query (string) is required' } };
@@ -74,21 +50,7 @@ export async function webSearch(args = {}, { env = process.env, fetchImpl = glob
   }
 
   const items = Array.isArray(payload?.results) ? payload.results : [];
-  const results = items
-    .filter((it) => it && typeof it.url === 'string' && /^https?:\/\//.test(it.url))
-    .map((it) => {
-      const admiralty = typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty) ? it.admiralty : 'C3';
-      return {
-        source: 'web',
-        url: it.url,
-        title: typeof it.title === 'string' && it.title ? it.title : it.url,
-        snippet: typeof it.snippet === 'string' ? it.snippet : '',
-        class: classifyResult(it.url),
-        admiralty,
-        confidence: confidenceFromGrade(admiralty),
-        needsGrading: !(typeof it.admiralty === 'string' && /^[A-F][1-6]$/.test(it.admiralty)),
-      };
-    });
+  const results = governWebResults(items, { now });
 
   return { source: 'web', degraded: false, query, claim, results, dropped: items.length - results.length };
 }