@stigmer/runner 3.4.1 → 3.5.1

package/src/shared/__tests__/mcp-resolver.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { resolveMcpServers } from "../mcp-resolver.js";
+import { McpTransportError } from "../mcp-transport-guard.js";
+
+function makeUsage(slug: string, org = "test-org") {
+  return {
+    mcpServerRef: { slug, org, kind: 0 },
+    toolApprovalOverrides: [],
+  } as any;
+}
+
+function stdioMcpServer(slug: string) {
+  return {
+    metadata: { id: `id-${slug}`, slug },
+    spec: {
+      serverType: { case: "stdio", value: { command: "npx", args: [] } },
+      env: {},
+    },
+    status: undefined,
+  } as any;
+}
+
+function httpMcpServer(slug: string) {
+  return {
+    metadata: { id: `id-${slug}`, slug },
+    spec: {
+      serverType: { case: "http", value: { url: "https://mcp.example.com/mcp", headers: {} } },
+      env: {},
+    },
+    status: undefined,
+  } as any;
+}
+
+function clientReturning(serversBySlug: Record<string, unknown>) {
+  return {
+    getMcpServerByReference: vi.fn(async (ref: { slug: string }) => {
+      const server = serversBySlug[ref.slug];
+      if (!server) throw new Error(`not found: ${ref.slug}`);
+      return server;
+    }),
+  } as any;
+}
+
+describe("resolveMcpServers — transport guard integration", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  it("throws McpTransportError for stdio under a forbidding posture — never degraded to a skipped server", async () => {
+    // The per-server catch swallows resolution hiccups into console.warn;
+    // a policy rejection must escape it and fail the whole resolution.
+    const client = clientReturning({ filesystem: stdioMcpServer("filesystem") });
+
+    await expect(
+      resolveMcpServers(client, [makeUsage("filesystem")], {}, "stdio-forbidden"),
+    ).rejects.toThrow(McpTransportError);
+  });
+
+  it("fails the whole resolution even when other servers are resolvable", async () => {
+    const client = clientReturning({
+      github: httpMcpServer("github"),
+      filesystem: stdioMcpServer("filesystem"),
+    });
+
+    await expect(
+      resolveMcpServers(
+        client,
+        [makeUsage("github"), makeUsage("filesystem")],
+        {},
+        "stdio-forbidden",
+      ),
+    ).rejects.toThrow(McpTransportError);
+  });
+
+  it("resolves http servers under a forbidding posture", async () => {
+    const client = clientReturning({ github: httpMcpServer("github") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github")], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers).toHaveLength(1);
+    expect(result.resolvedServers[0].connectionType).toBe("http");
+  });
+
+  it("resolves stdio servers under an allowing posture", async () => {
+    const client = clientReturning({ filesystem: stdioMcpServer("filesystem") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("filesystem")], {}, "stdio-allowed",
+    );
+
+    expect(result.resolvedServers).toHaveLength(1);
+    expect(result.resolvedServers[0].connectionType).toBe("stdio");
+  });
+
+  it("still degrades gracefully for ordinary resolution failures", async () => {
+    const client = clientReturning({});
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("ghost")], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers).toHaveLength(0);
+  });
+});

package/src/shared/__tests__/mcp-transport-guard.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from "vitest";
+import {
+  assertTransportAllowed,
+  McpTransportError,
+  resolveMcpTransportPosture,
+} from "../mcp-transport-guard.js";
+
+describe("resolveMcpTransportPosture", () => {
+  it("forbids stdio on cloud runners", () => {
+    expect(resolveMcpTransportPosture("cloud", {})).toBe("stdio-forbidden");
+  });
+
+  it("allows stdio on local runners", () => {
+    expect(resolveMcpTransportPosture("local", {})).toBe("stdio-allowed");
+  });
+
+  it("honors the explicit allow override on a cloud runner (kill-switch)", () => {
+    expect(
+      resolveMcpTransportPosture("cloud", { STIGMER_MCP_ALLOW_STDIO: "true" }),
+    ).toBe("stdio-allowed");
+  });
+
+  it("honors the explicit forbid override on a local runner", () => {
+    expect(
+      resolveMcpTransportPosture("local", { STIGMER_MCP_ALLOW_STDIO: "false" }),
+    ).toBe("stdio-forbidden");
+  });
+
+  it("ignores malformed override values", () => {
+    expect(
+      resolveMcpTransportPosture("cloud", { STIGMER_MCP_ALLOW_STDIO: "yes" }),
+    ).toBe("stdio-forbidden");
+  });
+});
+
+describe("assertTransportAllowed", () => {
+  it("throws McpTransportError for stdio under a forbidding posture", () => {
+    expect(() =>
+      assertTransportAllowed("filesystem", "stdio", "stdio-forbidden"),
+    ).toThrow(McpTransportError);
+  });
+
+  it("names the server and both remediations in the error message", () => {
+    try {
+      assertTransportAllowed("filesystem", "stdio", "stdio-forbidden");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(McpTransportError);
+      const message = (err as Error).message;
+      expect(message).toContain("'filesystem'");
+      expect(message).toContain("local runner");
+      expect(message).toContain("execution_target: local");
+      expect(message).toContain("HTTP");
+    }
+  });
+
+  it("allows stdio under an allowing posture", () => {
+    expect(() =>
+      assertTransportAllowed("filesystem", "stdio", "stdio-allowed"),
+    ).not.toThrow();
+  });
+
+  it("allows http and sse regardless of posture", () => {
+    expect(() =>
+      assertTransportAllowed("github", "http", "stdio-forbidden"),
+    ).not.toThrow();
+    expect(() =>
+      assertTransportAllowed("sse-server", "sse", "stdio-forbidden"),
+    ).not.toThrow();
+  });
+});

package/src/shared/cold-start-timing.ts

@@ -0,0 +1,197 @@
+/**
+ * Cold-start timing instrumentation.
+ *
+ * Measures the two previously unmeasured segments of the user-perceived cold
+ * start (warm-agent-surfaces Phase 0): the runner PROCESS BOOT (Node start →
+ * worker polling its Temporal queue) and PER-EXECUTION SETUP (activity start →
+ * agent ready to stream), broken down by named phase.
+ *
+ * Emission is a single structured JSON log line per timeline (selector field
+ * `stigmer_timing`), joined to control-plane timestamps by `execution_id`.
+ * Deliberately logs, not proto/status payloads: the status-update path is
+ * size-guarded and UI-coupled, and Temporal history must never carry
+ * telemetry. Cluster logging picks these lines up as-is.
+ *
+ * Failure posture: instrumentation must never affect an execution. All
+ * emission is wrapped; recorders are plain arithmetic and cannot throw in
+ * practice, but callers still treat every function here as best-effort.
+ */
+
+// Static on purpose: the registry module is itself lazy (it dynamic-imports
+// @opentelemetry/api inside getInstruments), so this adds nothing to boot,
+// while per-call dynamic imports raced under concurrent emissions.
+import { getInstruments } from "../otel-metrics.js";
+
+/** One closed segment on a timeline: [startMs, startMs + durationMs). */
+export interface TimingSegment {
+  readonly name: string;
+  /** Offset from the recorder's origin when this segment began (ms). */
+  readonly startMs: number;
+  readonly durationMs: number;
+}
+
+/**
+ * Records a linear sequence of named segments.
+ *
+ * `mark(name)` closes the span from the previous mark (or the origin) and
+ * names it — so instrumentation reads as one line placed AFTER the work it
+ * measures, mirroring the existing `reportSetupProgress` phase idiom:
+ *
+ * ```ts
+ * const timing = new TimingRecorder();
+ * const execution = await client.getExecution(executionId);
+ * timing.mark("fetch_execution");
+ * ```
+ */
+export class TimingRecorder {
+  private readonly originMs: number;
+  private readonly segments: TimingSegment[] = [];
+  private lastMarkMs: number;
+
+  /**
+   * @param originMs absolute `performance.now()`-scale origin. Defaults to
+   *   "now" (per-execution timelines). Pass 0 for a process-lifetime timeline
+   *   whose offsets are milliseconds since Node start (`performance.now()`
+   *   is measured from `performance.timeOrigin`, i.e. process start).
+   */
+  constructor(originMs: number = performance.now()) {
+    this.originMs = originMs;
+    this.lastMarkMs = originMs;
+  }
+
+  /** Close the span since the previous mark (or origin) and name it. */
+  mark(name: string): void {
+    const now = performance.now();
+    this.segments.push({
+      name,
+      startMs: round1(this.lastMarkMs - this.originMs),
+      durationMs: round1(now - this.lastMarkMs),
+    });
+    this.lastMarkMs = now;
+  }
+
+  /** Total elapsed time from the origin to the latest mark (ms). */
+  totalMs(): number {
+    return round1(this.lastMarkMs - this.originMs);
+  }
+
+  snapshot(): readonly TimingSegment[] {
+    return this.segments;
+  }
+}
+
+/**
+ * Emit one timeline as a single structured log line.
+ *
+ * Shape (stable — the baseline report and log-based metrics query it):
+ * `{"stigmer_timing":"<event>", ...context, "total_ms":N, "segments":[{"name","start_ms","duration_ms"}]}`
+ *
+ * Each timeline's total is additionally mirrored onto its OTel histogram
+ * (see {@link recordTimingMetric}): the stdout line stays the source of
+ * truth for per-segment forensics (it is the only place segments exist —
+ * cluster workload logs are not ingested anywhere queryable), while the
+ * histogram gives dashboards the aggregate without scraping pods.
+ */
+export function emitTimingLog(
+  event: string,
+  context: Record<string, string | number | boolean | null | undefined>,
+  recorder: TimingRecorder,
+): void {
+  try {
+    console.log(JSON.stringify({
+      stigmer_timing: event,
+      ...context,
+      total_ms: recorder.totalMs(),
+      segments: recorder.snapshot().map((s) => ({
+        name: s.name,
+        start_ms: s.startMs,
+        duration_ms: s.durationMs,
+      })),
+    }));
+  } catch {
+    // Telemetry must never break the runner.
+  }
+  recordTimingMetric(event, context, recorder.totalMs());
+}
+
+/**
+ * Mirror a timeline's total onto its OTel histogram, fire-and-forget.
+ *
+ * Attributes are a per-event WHITELIST (`mode`, `harness`) — never ids or
+ * per-pod values. Unbounded attribute values multiply time series without
+ * limit (the JVM JFR thread_name incident, 2026-07-29: 5k+ series in
+ * 15 minutes), so new attributes here require the same closed-set argument
+ * these two carry. Events without a mapped instrument are control-plane
+ * timelines or future additions and are deliberately not recorded.
+ *
+ * Exported for tests; production callers go through {@link emitTimingLog}.
+ */
+export function recordTimingMetric(
+  event: string,
+  context: Record<string, string | number | boolean | null | undefined>,
+  totalMs: number,
+): void {
+  void (async () => {
+    const instruments = await getInstruments();
+    switch (event) {
+      case "runner_boot":
+        instruments.runnerBootDuration.record(totalMs, pickAttrs(context, "mode"));
+        break;
+      case "execution_setup":
+        instruments.executionSetupDuration.record(totalMs, pickAttrs(context, "harness"));
+        break;
+      case "pool_attach":
+        instruments.poolAttachDuration.record(totalMs);
+        break;
+      default:
+        break;
+    }
+  })().catch(() => {
+    // Telemetry must never break the runner.
+  });
+}
+
+/** Copy only the whitelisted string-valued keys into metric attributes. */
+function pickAttrs(
+  context: Record<string, string | number | boolean | null | undefined>,
+  ...keys: string[]
+): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const key of keys) {
+    const value = context[key];
+    if (typeof value === "string" && value.length > 0) {
+      attrs[key] = value;
+    }
+  }
+  return attrs;
+}
+
+// ─── Process boot timeline ───────────────────────────────────────────────────
+
+// Origin 0 = process start, so the implicit first segment (everything before
+// the first markBoot call) covers Node startup + entrypoint module loading.
+const bootRecorder = new TimingRecorder(0);
+let bootEmitted = false;
+
+/** Record a boot milestone (closes the span since the previous milestone). */
+export function markBoot(name: string): void {
+  if (bootEmitted) return;
+  bootRecorder.mark(name);
+}
+
+/**
+ * Emit the boot timeline once — called when the worker starts polling, the
+ * moment the sandbox can actually receive work. Later calls are no-ops so
+ * worker restarts within one process never emit a bogus second timeline.
+ */
+export function emitRunnerBootTiming(
+  context: Record<string, string | number | boolean | null | undefined>,
+): void {
+  if (bootEmitted) return;
+  bootEmitted = true;
+  emitTimingLog("runner_boot", context, bootRecorder);
+}
+
+function round1(ms: number): number {
+  return Math.round(ms * 10) / 10;
+}

package/src/shared/connect-backfill.ts

@@ -20,6 +20,7 @@
 
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
 import { resolveMcpServers } from "./mcp-resolver.js";
+import type { McpTransportPosture } from "./mcp-transport-guard.js";
 import type { StigmerClient } from "../client/stigmer-client.js";
 import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 
@@ -64,6 +65,7 @@ export async function backfillMcpServersIfNeeded(
   usages: McpServerUsage[],
   envVars: Record<string, string>,
   org: string,
+  transportPosture: McpTransportPosture,
   onHeartbeat?: () => void,
   secretKeys?: ReadonlySet<string>,
 ): Promise<ResolvedMcpServer[]> {
@@ -129,7 +131,9 @@ export async function backfillMcpServersIfNeeded(
     return currentServers;
   }
 
-  const refreshed = await resolveMcpServers(client, usages, envVars);
+  // Same posture as the initial resolution: every server here already
+  // passed the transport guard once, so re-resolving cannot newly reject.
+  const refreshed = await resolveMcpServers(client, usages, envVars, transportPosture);
   return refreshed.resolvedServers;
 }
 

package/src/shared/mcp-manager.ts

@@ -4,9 +4,12 @@
  * Wraps @langchain/mcp-adapters MultiServerMCPClient with:
  * - Conversion from ResolvedMcpServer[] to the SDK's Connection config
  * - Proper async cleanup via close()
- * - Cloud compatibility validation (warn on non-installable stdio commands)
  * - Tool filtering based on discovered capabilities
  *
+ * Transport policy (stdio is local-runner-only) is enforced upstream at
+ * resolution time by shared/mcp-transport-guard.ts — servers reaching
+ * this manager have already passed it.
+ *
  * The Cursor execution path does NOT use this manager — it passes MCP
  * configs directly to the Cursor SDK via toCursorMcpConfig(). This
  * manager is exclusively for LangGraph-based deep agent executions.
@@ -17,41 +20,6 @@ import type { Connection } from "@langchain/mcp-adapters";
 import type { DynamicStructuredTool } from "@langchain/core/tools";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
 
-const CLOUD_SAFE_COMMANDS = new Set(["npx", "node", "uvx", "python", "python3"]);
-
-/**
- * Classifies a stdio command's compatibility with cloud execution.
- * Returns true for commands that are installable/available in typical
- * cloud environments (npx, node, uvx, python).
- */
-export function isCloudCompatibleCommand(command: string): boolean {
-  const base = command.split("/").pop() ?? command;
-  return CLOUD_SAFE_COMMANDS.has(base);
-}
-
-/**
- * Log warnings for MCP servers that may not work in cloud mode.
- * Does not filter or reject — just provides operator visibility.
- */
-export function warnCloudIncompatibleServers(
-  servers: ResolvedMcpServer[],
-  isCloudMode: boolean,
-): void {
-  if (!isCloudMode) return;
-
-  for (const server of servers) {
-    if (server.connectionType === "stdio" && server.command) {
-      if (!isCloudCompatibleCommand(server.command)) {
-        console.warn(
-          `[MCP] Server '${server.slug}' uses stdio command '${server.command}' ` +
-          `which may not be available in cloud execution environments. ` +
-          `Consider using an HTTP MCP server or an npx-installable package.`,
-        );
-      }
-    }
-  }
-}
-
 /**
  * Convert harness-agnostic ResolvedMcpServer[] into the
  * MultiServerMCPClient connection config format.
@@ -98,12 +66,7 @@ export interface McpConnectionResult {
  */
 export async function connectMcpServers(
   servers: ResolvedMcpServer[],
-  options?: { isCloudMode?: boolean },
 ): Promise<McpConnectionResult> {
-  if (options?.isCloudMode) {
-    warnCloudIncompatibleServers(servers, true);
-  }
-
   const connectionConfig = toMcpClientConfig(servers);
 
   if (Object.keys(connectionConfig).length === 0) {

package/src/shared/mcp-resolver.ts

@@ -1,16 +1,25 @@
 /**
  * Resolves Stigmer McpServerUsage references into an intermediate
- * ResolvedMcpServer format that is harness-agnostic.
+ * ResolvedMcpServer format.
  *
- * Both ExecuteCursor and ExecuteDeepAgent need MCP server connection info
- * and tool approval policies. This module provides the common resolution
- * logic; each harness maps ResolvedMcpServer into its SDK-specific format.
+ * Consumers: the deep-agent harness (execute-deep-agent/setup.ts), the
+ * connect backfill (shared/connect-backfill.ts), and the discovery
+ * activity (activities/discover-mcp-server.ts, via mcpServerToResolved).
+ * NOTE: the Cursor harness does NOT use this module — it has its own
+ * near-duplicate resolver at activities/execute-cursor/mcp-resolver.ts.
+ * A behavioral change here (like the transport guard) must be mirrored
+ * there until the two are consolidated.
  */
 
 import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
+import {
+  assertTransportAllowed,
+  McpTransportError,
+  type McpTransportPosture,
+} from "./mcp-transport-guard.js";
 import {
   resolveHeaders,
   resolvePlaceholders,
@@ -44,11 +53,17 @@ export interface McpResolutionResult {
 
 /**
  * Fetch McpServer resources and resolve into intermediate format.
+ *
+ * @param transportPosture Whether stdio servers may run here (derive via
+ *        resolveMcpTransportPosture(config.mode)). A stdio server under a
+ *        forbidding posture throws {@link McpTransportError} and fails the
+ *        whole resolution — never degraded to a skipped server.
  */
 export async function resolveMcpServers(
   client: StigmerClient,
   usages: McpServerUsage[],
-  envVars: Record<string, string> = {},
+  envVars: Record<string, string>,
+  transportPosture: McpTransportPosture,
 ): Promise<McpResolutionResult> {
   const resolved: ResolvedMcpServer[] = [];
 
@@ -64,8 +79,16 @@ export async function resolveMcpServers(
         ref.slug,
       );
       const server = mcpServerToResolved(mcpServer, ref.slug, serverEnv);
-      if (server) resolved.push(server);
+      if (server) {
+        assertTransportAllowed(server.slug, server.connectionType, transportPosture);
+        resolved.push(server);
+      }
     } catch (err) {
+      if (err instanceof McpTransportError) {
+        // Policy rejection, not a resolution hiccup: swallowing it here
+        // would mean the agent silently loses tools. Fail the execution.
+        throw err;
+      }
       if (err instanceof PlaceholderResolutionError) {
         console.error(
           `MCP server ${ref.org}/${ref.slug}: ${err.message}`,

package/src/shared/mcp-transport-guard.ts

@@ -0,0 +1,81 @@
+/**
+ * Transport guard for MCP servers — stdio is local-runner-only.
+ *
+ * Why this is load-bearing: a stdio MCP server means "download a package
+ * from a public registry at session start and run it as a subprocess with
+ * the execution's secrets in its environment". On a local runner that
+ * machine belongs to the user — their trust decision. On a managed cloud
+ * runner it is a supply-chain exposure the platform owns, so hosted
+ * execution is HTTP-only. The control plane refuses such executions at
+ * create time (stigmer-cloud's McpTransportPolicy); this guard is the
+ * defense-in-depth backstop at the moment a subprocess would actually be
+ * spawned — it must hold even if a stdio usage reaches a cloud runner
+ * through a path the control plane did not see.
+ *
+ * The posture derives from Config.mode ("cloud" → forbid stdio), NOT from
+ * cloudModeEnabled — that is the Cursor cloud-agent feature flag and says
+ * nothing about where this process runs. STIGMER_MCP_ALLOW_STDIO exists as
+ * an explicit override so operators can roll the policy back without a
+ * redeploy (the runner-side counterpart of the control plane's
+ * stigmer.mcp.stdio-cloud-block kill-switch). Managed cloud deployments
+ * never set it.
+ *
+ * A rejection is thrown as {@link McpTransportError} and must FAIL the
+ * execution loudly: the resolvers' per-server catch blocks swallow
+ * resolution failures into console.warn and continue, which would turn a
+ * policy rejection into an agent silently losing tools. Both resolvers
+ * rethrow this error type for exactly that reason.
+ *
+ * Mirrors the posture/override/error shape of tools/url-guard.ts (the
+ * web_fetch SSRF boundary), the runner's established idiom for
+ * mode-keyed guards.
+ */
+
+export type McpTransportPosture = "stdio-allowed" | "stdio-forbidden";
+
+/** Thrown for every guard rejection; message is safe to surface to the user. */
+export class McpTransportError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "McpTransportError";
+  }
+}
+
+/**
+ * Derive the transport posture from runner mode plus the explicit override.
+ *
+ * @param mode Config.mode — "cloud" means a managed runner on shared infrastructure.
+ * @param env  Environment to read STIGMER_MCP_ALLOW_STDIO from.
+ */
+export function resolveMcpTransportPosture(
+  mode: "local" | "cloud",
+  env: NodeJS.ProcessEnv = process.env,
+): McpTransportPosture {
+  const override = env.STIGMER_MCP_ALLOW_STDIO;
+  if (override === "true") return "stdio-allowed";
+  if (override === "false") return "stdio-forbidden";
+  return mode === "cloud" ? "stdio-forbidden" : "stdio-allowed";
+}
+
+/**
+ * Assert that a resolved MCP server's transport is allowed under the given
+ * posture. Applies only to user-defined McpServer resources flowing through
+ * the resolvers — the internal datastore attachment is synthesized
+ * separately and is already HTTP in cloud mode.
+ *
+ * @throws McpTransportError when the posture forbids stdio and the server uses it
+ */
+export function assertTransportAllowed(
+  slug: string,
+  connectionType: "stdio" | "http" | "sse",
+  posture: McpTransportPosture,
+): void {
+  if (posture === "stdio-forbidden" && connectionType === "stdio") {
+    throw new McpTransportError(
+      `MCP server '${slug}' uses the stdio transport, which runs only on local ` +
+      `runners — this cloud runner refuses to spawn it. Run the session on a ` +
+      `local runner (session execution_target: local), or replace '${slug}' ` +
+      `with a remote (HTTP) MCP server.`,
+    );
+  }
+}

package/src/shared/tool-kind.ts

@@ -59,6 +59,7 @@ const TOOL_NAME_TO_KIND: ReadonlyMap<string, ToolKind> = new Map([
   ["ls", ToolKind.LIST],
   ["list_directory", ToolKind.LIST],
 
+  ["web_fetch", ToolKind.FETCH],
   ["WebFetch", ToolKind.FETCH],
   ["WebSearch", ToolKind.WEB_SEARCH],
 
@@ -118,6 +119,11 @@ export function toolApprovalCategory(name: string): ToolApprovalCategory | undef
       return "delete";
     case ToolKind.SHELL:
       return "shell";
+    // FETCH is deliberately uncategorized — i.e. auto-approved. This mirrors
+    // the Cursor harness (WebFetch is never gated) and is what makes the
+    // native web_fetch usable in unattended runs, where a gated tool is
+    // silently skipped. The safety boundary for web_fetch is its URL guard
+    // (tools/url-guard.ts), not the approval gate.
     default:
       return undefined;
   }