@sema-agent/core 5.52.0 → 5.54.0

package/dist/core/mcp.js

@@ -1,5 +1,5 @@
 import { MCP_NAMESPACE } from "./protocol-table.js";
-import { mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
+import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -7,6 +7,7 @@ import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { CallToolResultSchema, ElicitRequestSchema, ErrorCode, ListResourcesResultSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { DEFAULT_REQUEST_TIMEOUT_MSEC } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { MCP_IMAGE_MAX_BASE64, sharpImageResizer } from "./image-downsample.js";
 import { sliceHeadSafe, sliceTailSafe } from "./surrogate-safe-slice.js";
 import { truncateError } from "./tool-errors.js";
@@ -663,6 +664,17 @@ export function mcpToolSchemaProblem(schema) {
     return undefined;
 }
 export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations) {
+    {
+        const collision = findNamespacePrefixCollision(MCP_NAMESPACE, specs.map((s) => s.name));
+        if (collision) {
+            const [a, b] = collision.peers;
+            const e = new Error(a === b
+                ? `MCP server "${inlineUntrusted(a, 120)}" is declared twice — each server needs its own name (both mount under "${collision.prefix}", so their tools would shadow each other and a refresh of one would unmount the other's).`
+                : `MCP server names "${inlineUntrusted(a, 120)}" and "${inlineUntrusted(b, 120)}" both mount under "${collision.prefix}" — the namespaced tool name keeps only [a-zA-Z0-9_-], so they are the same domain to this engine (their tools would shadow each other and a refresh of one would unmount the other's). Rename one.`);
+            e.code = "config.mcp_server_name_collision";
+            throw e;
+        }
+    }
     let revocationProbeFailed = false;
     const isServerRevoked = (serverName) => {
         if (mcpRevocations === undefined)
@@ -708,7 +720,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             if (r.status === "fulfilled") {
                 const s = r.value;
                 clients.push(s.client);
-                serverHandles.push({ name: spec.name, spec, client: s.client, health: s.health, toolNames: s.tools.map((t) => t.name) });
+                serverHandles.push({ name: spec.name, spec, client: s.client, health: s.health, tools: s.tools, listedRaw: s.listedTools });
                 tools.push(...s.tools);
                 toolAxes.push(...s.axes);
                 if (s.instructions) {
@@ -729,6 +741,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     resourceServers.push(s.resourceServer);
                 for (const d of s.dropped)
                     droppedTools.push({ server: inlineUntrusted(spec.name, 160), ...d });
+                if (s.listingIncomplete)
+                    warnings.push(listingIncompleteWarning(spec.name, s.listingIncomplete));
                 statuses.push(s.status);
             }
             else {
@@ -770,12 +784,17 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 }
                 try {
                     const listed = await listToolsLenient(h.client);
-                    cacheMcpToolMetadata(h.client, listed.tools);
-                    const { serverTools, serverAxes, dropped } = intakeListedTools(listed, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked);
+                    const advertised = new Set(listed.tools.map((t) => t.name));
+                    const retainedRaw = listed.incomplete !== undefined ? h.listedRaw.filter((t) => !advertised.has(t.name)) : [];
+                    const mergedRaw = retainedRaw.length > 0 ? [...listed.tools, ...retainedRaw] : listed.tools;
+                    cacheMcpToolMetadata(h.client, retainedRaw.length > 0 ? [...retainedRaw, ...listed.tools] : listed.tools);
+                    const { serverTools, serverAxes, dropped } = intakeListedTools({ tools: mergedRaw }, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked);
+                    const priorNames = h.tools.map((t) => t.name);
                     const newNames = serverTools.map((t) => t.name);
-                    const added = newNames.filter((n) => !h.toolNames.includes(n));
-                    const removed = h.toolNames.filter((n) => !newNames.includes(n));
-                    h.toolNames = newNames;
+                    const added = newNames.filter((n) => !priorNames.includes(n));
+                    const removed = priorNames.filter((n) => !newNames.includes(n));
+                    h.tools = serverTools;
+                    h.listedRaw = mergedRaw;
                     results.push({
                         server: h.name,
                         prefix: prefixOf(h.name),
@@ -786,6 +805,9 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                         tools: serverTools,
                         axes: serverAxes,
                         dropped: dropped.map((d) => ({ server: inlineUntrusted(h.name, 160), ...d })),
+                        ...(listed.incomplete !== undefined
+                            ? { listingIncomplete: listed.incomplete, error: `tool listing incomplete — ${listingIncompleteNote(listed.incomplete)}` }
+                            : {}),
                     });
                 }
                 catch (err) {
@@ -793,7 +815,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                         server: h.name,
                         prefix: prefixOf(h.name),
                         status: "failed",
-                        toolCount: h.toolNames.length,
+                        toolCount: h.tools.length,
                         added: [],
                         removed: [],
                         error: inlineUntrusted(namedMcpFailureText(err), 240),
@@ -864,6 +886,110 @@ function resourceLine(r) {
 function serverNames(servers) {
     return servers.map((r) => r.server).join(", ") || "(none)";
 }
+const MAX_MCP_LIST_PAGES = 20;
+const MIN_MCP_PAGE_BUDGET_MS = 250;
+function continuationPageFloorMs(budgetMs) {
+    return Math.max(1, Math.min(MIN_MCP_PAGE_BUDGET_MS, Math.floor(budgetMs / 10)));
+}
+export function listEntryFingerprint(entry) {
+    try {
+        const json = JSON.stringify(entry);
+        return typeof json === "string" ? json : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const LIST_ENTRY_FINGERPRINT_MAX_CHARS = 8 * 1024;
+const LOOP_REWIND_FINGERPRINT_MAX_CHARS = 1024 * 1024;
+export async function walkMcpListPages(fetchPage, opts) {
+    const items = [];
+    const used = new Set();
+    const deadline = Date.now() + opts.budgetMs;
+    let cursor;
+    let pages = 0;
+    for (;;) {
+        const remainingMs = pages === 0 ? opts.budgetMs : deadline - Date.now();
+        if (pages > 0 && remainingMs < continuationPageFloorMs(opts.budgetMs)) {
+            return { items, incomplete: { reason: "budget_exhausted", pages, budgetMs: opts.budgetMs } };
+        }
+        let page;
+        try {
+            page = await fetchPage(cursor, remainingMs);
+        }
+        catch (err) {
+            if (pages === 0 || opts.signal?.aborted)
+                throw err;
+            return { items, incomplete: { reason: "page_error", pages, error: err instanceof Error ? err.message : String(err) } };
+        }
+        opts.onPage?.();
+        const pageStart = items.length;
+        items.push(...page.items);
+        pages++;
+        if (page.cursorInvalid === true)
+            return { items, incomplete: { reason: "cursor_invalid", pages } };
+        const next = page.nextCursor;
+        if (next === undefined)
+            return { items };
+        if (used.has(next)) {
+            const fresh = [];
+            const fingerprintOf = opts.fingerprintOf;
+            if (fingerprintOf !== undefined) {
+                const before = new Set();
+                let keying = LOOP_REWIND_FINGERPRINT_MAX_CHARS;
+                const keyOf = (item) => {
+                    if (keying <= 0)
+                        return undefined;
+                    const fp = fingerprintOf(item);
+                    if (fp === undefined) {
+                        keying -= LIST_ENTRY_FINGERPRINT_MAX_CHARS;
+                        return undefined;
+                    }
+                    keying -= fp.length;
+                    return fp.length <= LIST_ENTRY_FINGERPRINT_MAX_CHARS ? fp : undefined;
+                };
+                for (let i = 0; i < pageStart; i++) {
+                    const fp = keyOf(items[i]);
+                    if (fp !== undefined)
+                        before.add(fp);
+                }
+                for (const item of page.items) {
+                    const fp = keyOf(item);
+                    if (fp !== undefined && before.has(fp))
+                        continue;
+                    fresh.push(item);
+                }
+            }
+            items.length = pageStart;
+            items.push(...fresh);
+            return { items, incomplete: { reason: "cursor_loop", pages } };
+        }
+        if (pages >= MAX_MCP_LIST_PAGES)
+            return { items, incomplete: { reason: "page_cap", pages } };
+        used.add(next);
+        cursor = next;
+    }
+}
+function idleWatchdogTripText(idleMs) {
+    return `received no response for ${idleMs}ms (idle watchdog; set MCP_IDLE_TIMEOUT_STDIO / MCP_IDLE_TIMEOUT_HTTP to change this bound)`;
+}
+function listingIncompleteNote(flag) {
+    const pages = `${flag.pages} page${flag.pages === 1 ? "" : "s"}`;
+    if (flag.reason === "page_cap") {
+        return `[listing truncated: the ${MAX_MCP_LIST_PAGES}-page pagination limit was reached — more entries may exist beyond this listing]`;
+    }
+    if (flag.reason === "cursor_loop") {
+        return `[listing truncated: after ${pages} the server handed back a pagination cursor it had already used, so the walk stopped — more entries may exist beyond this listing]`;
+    }
+    if (flag.reason === "cursor_invalid") {
+        return `[listing truncated: after ${pages} the server sent a pagination cursor that is not a string, so the walk could not continue — more entries may exist beyond this listing]`;
+    }
+    if (flag.reason === "budget_exhausted") {
+        const budget = flag.budgetMs !== undefined ? `${flag.budgetMs}ms ` : "";
+        return `[listing truncated: after ${pages} the ${budget}time budget for this listing was too low to give the next page a usable request, so the client stopped without sending one — this is a client-side bound, not a server failure; more entries may exist beyond this listing]`;
+    }
+    return `[listing incomplete: the server failed mid-pagination after ${pages} (${inlineUntrusted(flag.error ?? "unknown error", 240)}) — only the pages retrieved before the failure are shown]`;
+}
 async function readDirViaExtension(rs, uri, signal, timeoutMs, watchdog) {
     const resources = [];
     let cursor;
@@ -907,10 +1033,13 @@ function renderDirChildren(server, uri, children, flags) {
     if (flags?.cursorInvalid) {
         notes.push(`[listing incomplete: the server rejected the pagination cursor (invalid or expired) — only the pages retrieved before the rejection are shown; more entries may exist beyond this listing]`);
     }
+    if (flags?.listing)
+        notes.push(listingIncompleteNote(flags.listing));
     const detailFlags = {
         ...(flags?.truncated ? { truncated: true } : {}),
         ...(flags?.incomplete !== undefined ? { incomplete: true, error: flags.incomplete } : {}),
         ...(flags?.cursorInvalid ? { incomplete: true, cursorInvalid: true } : {}),
+        ...(flags?.listing ? { incomplete: true, listing: flags.listing } : {}),
     };
     const listing = children.length === 0
         ? `(Empty directory: ${inlineUntrusted(uri)})`
@@ -948,6 +1077,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 const sections = [];
                 const all = [];
                 const errors = [];
+                const incomplete = [];
                 for (const rs of targets) {
                     if (isServerRevoked(rs.server)) {
                         errors.push({ server: rs.server, error: "server revoked by the operator mid-session (request not sent)" });
@@ -962,16 +1092,30 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                     const idleMs = mcpIdleTimeoutMs(rs.transportKind);
                     const watchdog = armMcpIdleWatchdog(rs.health, idleMs, signal);
                     try {
-                        const res = await rs.client.listResources(undefined, { signal: watchdog.combinedSignal, timeout: mcpToolTimeoutMs() });
-                        all.push(...res.resources.map((r) => ({ server: rs.server, ...r })));
-                        const lines = res.resources.map((r) => resourceLine(r));
-                        sections.push(`[${rs.server}]\n${lines.length ? lines.join("\n") : "(no resources)"}`);
+                        const walk = await walkMcpListPages(async (cursor, remainingMs) => {
+                            const page = await rs.client
+                                .listResources(cursor === undefined ? undefined : { cursor }, { signal: watchdog.combinedSignal, timeout: remainingMs })
+                                .catch((err) => {
+                                throw watchdog.idleSignal.reason === IDLE_WATCHDOG_ABORT_REASON ? new Error(idleWatchdogTripText(idleMs)) : err;
+                            });
+                            return { items: page.resources, ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}) };
+                        }, { budgetMs: mcpToolTimeoutMs(), onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, ...(signal !== undefined ? { signal } : {}) });
+                        all.push(...walk.items.map((r) => ({ server: rs.server, ...r })));
+                        const lines = walk.items.map((r) => resourceLine(r));
+                        const body = lines.length ? lines.join("\n") : "(no resources)";
+                        if (walk.incomplete) {
+                            incomplete.push({ server: rs.server, ...walk.incomplete });
+                            sections.push(`[${rs.server}]\n${body}\n${listingIncompleteNote(walk.incomplete)}`);
+                        }
+                        else {
+                            sections.push(`[${rs.server}]\n${body}`);
+                        }
                     }
                     catch (err) {
                         if (signal?.aborted)
                             throw err;
                         const msg = watchdog.idleSignal.reason === IDLE_WATCHDOG_ABORT_REASON
-                            ? `received no response for ${idleMs}ms (idle watchdog; set MCP_IDLE_TIMEOUT_STDIO / MCP_IDLE_TIMEOUT_HTTP to change this bound)`
+                            ? idleWatchdogTripText(idleMs)
                             : err instanceof Error
                                 ? err.message
                                 : String(err);
@@ -985,7 +1129,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 const body = sections.join("\n\n");
                 return {
                     content: [{ type: "text", text: sections.length ? delimitUntrusted("mcp resources", body) : "(no MCP resources)" }],
-                    details: { resources: all, ...(errors.length ? { errors } : {}) },
+                    details: { resources: all, ...(errors.length ? { errors } : {}), ...(incomplete.length ? { incomplete } : {}) },
                     terminate: false,
                 };
             },
@@ -1114,12 +1258,15 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                             return renderDirChildren(server, uri, r.resources, { truncated: r.truncated, incomplete: r.incomplete, cursorInvalid: r.cursorInvalid });
                         watchdog.rearm();
                     }
-                    const res = await rs.client
-                        .listResources(undefined, { signal: watchdog.combinedSignal, timeout: timeoutMs })
-                        .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                    const walk = await walkMcpListPages(async (cursor, remainingMs) => {
+                        const page = await rs.client
+                            .listResources(cursor === undefined ? undefined : { cursor }, { signal: watchdog.combinedSignal, timeout: remainingMs })
+                            .catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs: remainingMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                        return { items: page.resources, ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}) };
+                    }, { budgetMs: timeoutMs, onPage: () => watchdog.rearm(), fingerprintOf: listEntryFingerprint, ...(signal !== undefined ? { signal } : {}) });
                     const dirPrefix = uri.endsWith("/") ? uri : `${uri}/`;
-                    const children = res.resources.filter((r) => typeof r.uri === "string" && r.uri !== uri && r.uri.startsWith(dirPrefix));
-                    return renderDirChildren(server, uri, children);
+                    const children = walk.items.filter((r) => typeof r.uri === "string" && r.uri !== uri && r.uri.startsWith(dirPrefix));
+                    return renderDirChildren(server, uri, children, walk.incomplete ? { listing: walk.incomplete } : undefined);
                 }
                 finally {
                     watchdog.dispose();
@@ -1166,7 +1313,8 @@ const LenientListToolsResultSchema = {
             });
         }
         const nextCursor = data.nextCursor;
-        return { success: true, data: { tools, ...(typeof nextCursor === "string" ? { nextCursor } : {}) } };
+        const cursorInvalid = nextCursor !== undefined && nextCursor !== null && typeof nextCursor !== "string";
+        return { success: true, data: { tools, ...(typeof nextCursor === "string" ? { nextCursor } : {}), ...(cursorInvalid ? { cursorInvalid: true } : {}) } };
     },
 };
 export function parseCallToolResultLenient(data) {
@@ -1181,7 +1329,19 @@ export function parseCallToolResultLenient(data) {
 }
 const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient };
 async function listToolsLenient(client, options) {
-    return client.request({ method: "tools/list", params: {} }, LenientListToolsResultSchema, options);
+    const walk = await walkMcpListPages(async (cursor, remainingMs) => {
+        const page = await client.request({ method: "tools/list", params: cursor === undefined ? {} : { cursor } }, LenientListToolsResultSchema, { ...options, timeout: remainingMs });
+        return {
+            items: page.tools,
+            ...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}),
+            ...(page.cursorInvalid === true ? { cursorInvalid: true } : {}),
+        };
+    }, {
+        budgetMs: options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC,
+        fingerprintOf: listEntryFingerprint,
+        ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+    });
+    return { tools: walk.items, ...(walk.incomplete !== undefined ? { incomplete: walk.incomplete } : {}) };
 }
 async function connectServer(spec, principal, onElicit, imageResizer, reminderDisclosure, isServerRevoked) {
     const elicitOn = spec.elicitation === true && onElicit !== undefined;
@@ -1243,7 +1403,9 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             tools: serverTools,
             axes: serverAxes,
             dropped,
+            listedTools: listed.tools,
             ...(instructions ? { instructions } : {}),
+            ...(listed.incomplete !== undefined ? { listingIncomplete: listed.incomplete } : {}),
             ...(resourceInfo && (resourceInfo.listAllowed || resourceInfo.readAllowed) ? { resourceServer: { server: spec.name, client, health, transportKind: idleKindOf(spec), ...resourceInfo } } : {}),
         };
     }
@@ -1256,6 +1418,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
+    const mintedNames = new Map();
     for (const t of listed.tools) {
         if (spec.allowTools && !spec.allowTools.includes(t.name)) {
             continue;
@@ -1278,6 +1441,17 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         }
         const remoteName = t.name;
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
+        const mintedBy = mintedNames.get(namespacedName);
+        if (mintedBy !== undefined) {
+            dropped.push({
+                tool: inlineUntrusted(t.name),
+                reason: mintedBy === t.name
+                    ? `this server listed this tool name more than once in one listing; the first entry is mounted as "${namespacedName}" and the repeat is dropped (one name cannot denote two tools)`
+                    : `name collides with an earlier tool of this server: both mount as "${namespacedName}" after namespacing (only [a-zA-Z0-9_-] survives), and one name cannot denote two tools`,
+            });
+            continue;
+        }
+        mintedNames.set(namespacedName, t.name);
         const hintAxis = mcpAxisFor(namespacedName, t.annotations);
         const axis = applyCallerAxisOverride(namespacedName, hintAxis, spec.toolAxes?.[remoteName]);
         if (axis)
@@ -1397,3 +1571,8 @@ function asServerWarning(spec, err) {
     warning.code = "mcp.server_unavailable";
     return warning;
 }
+function listingIncompleteWarning(server, flag) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" listed its tools INCOMPLETELY — ${listingIncompleteNote(flag)}. The tools beyond the ${flag.pages} page${flag.pages === 1 ? "" : "s"} retrieved are NOT mounted for this task.`);
+    warning.code = "mcp.listing_incomplete";
+    return warning;
+}

package/dist/core/permission-rule-model.d.ts

@@ -7,19 +7,36 @@
  * semantics; who may mint one, where it is stored, and where in the gate it is consumed live in
  * `permission-rule-store.ts`, `permission-rule-consent.ts` and `hooks.ts` respectively.
  *
- * ## The floor: only a single simple command can ever be matched
+ * ## The floor: what a rule may name, and what a rule may match
  *
- * Everything a shell can use to run a SECOND program behind an admitted first one — operators,
- * substitution, subshells, backgrounding, and **redirection** — puts the command outside this lane
- * entirely: it falls back to the pre-existing chain and asks. That includes redirection specifically,
- * which is a deliberate registered divergence from upstream (upstream strips redirections before
- * matching; with this repo's write gate not covering the shell tool, stripping would turn a rule as
- * innocuous as `Bash(ls)` into a licence for `ls > ~/.ssh/authorized_keys`).
+ * Everything a shell can use to run a program the text does not NAME — substitution, subshells,
+ * backgrounding, escapes, line breaks, and **redirection** — puts the command outside this lane
+ * entirely: it falls back to the pre-existing chain and asks. Redirection specifically is a deliberate
+ * registered divergence from upstream (upstream strips redirections before matching; with this repo's
+ * write gate not covering the shell tool, stripping would turn a rule as innocuous as `Bash(ls)` into a
+ * licence for `ls > ~/.ssh/authorized_keys`).
  *
- * The floor is `parseLeadingCommandName` — the one simple-command parser already shared by the
- * read-only classifier, the reversibility probe, the coarse command-name policy and the skill tool
- * specifier. A second tokenizer would drift, and drift on a loosening face shows up as a circumvention rather
- * than as a test failure.
+ * CONNECTORS are the one construct the lane does speak for, and only in the EXACT form. `./gradlew
+ * build && ./gradlew test` is one thing a person reads and approves in one glance, and the whole of it
+ * is written into the rule; nothing is admitted that the rule text does not spell out end to end. The
+ * PREFIX form stays single-command on both sides — as a rule BODY (`Bash(a && b:*)` is refused) and as
+ * a MATCH (`Bash(npm:*)` does not admit `npm test && curl evil.example`, which is the whole reason the
+ * two forms are separated here rather than sharing one matcher arm). Upstream reaches the same
+ * placement through a per-segment evaluation of its full decision chain, where a segment DENY is
+ * returned strictly before any whole-string allow; this lane's equivalent is that the deny/ask layer
+ * (`permission-rule-org.ts`) judges every segment and runs ahead of the allow lane at the gate.
+ *
+ * The floor is `parseLeadingCommandName` + `splitShellCompoundSegments` — the one simple-command parser
+ * and the one segmentation, both already shared with the read-only classifier, the reversibility probe,
+ * the coarse command-name policy and the skill tool specifier. A second tokenizer would drift, and drift
+ * on a loosening face shows up as a circumvention rather than as a test failure.
+ *
+ * argv[0] may carry a PATH prefix here (`./gradlew`, `/usr/bin/git`) — opt-in at the shared parser and
+ * used by this lane alone. The bare-name requirement belongs to the argv[0]-NAME filters, which compare
+ * one token against a name set; this lane compares the whole command line, so a path prefix is not a way
+ * past anything — it IS the text that was approved. No basename folding follows from it: `./gradlew`
+ * and `gradlew` stay two different commands to the matcher. The single place a basename is taken is the
+ * interpreter refusal below, which must read `/usr/bin/node` as `node`.
  *
  * ## Normalization order is load-bearing
  *
@@ -121,11 +138,64 @@ export declare const MAX_RULE_TEXT_CHARS = 512;
  * any program you like" — that is not a shape a single click can be understood to have authorized.
  *
  * The check is on argv[0] of the prefix, not on the prefix being exactly one word: `node -e:*` is the
- * same licence spelled longer. Deliberately strict-side — it costs the ability to persist a rule like
+ * same licence spelled longer. It is on argv[0]'s BASENAME, not its spelling: `/usr/bin/node:*` and
+ * `./node:*` grant precisely what `node:*` grants, and a table consulted with the full path would be a
+ * table any path prefix walks around (upstream takes the same basename before consulting its own
+ * interpreter set). Deliberately strict-side — it costs the ability to persist a rule like
  * `python manage.py migrate:*` (which an import reports as skipped rather than dropping silently), and
  * an EXACT rule naming a whole interpreter command line stays legal, since it authorizes one command.
+ *
+ * TWO groups, and the distinction matters when the table is next edited:
+ *  · LANGUAGE interpreters (`node`, `python`, `ruby`, …) — the argument IS a program. This half is
+ *    wider than upstream's own set, deliberately, and is the argument the paragraph above makes.
+ *  · LAUNCHERS — a program whose argument is another program to run: the shells, the environment and
+ *    privilege wrappers, the schedulers and resource wrappers, the tracers, and the shell BUILTINS
+ *    that dispatch (`command`, `builtin`). This half is upstream's set, adopted verbatim rather than
+ *    reasoned out row by row: it is the same question upstream answers with the same mechanism (its
+ *    set is consulted on argv[0]'s basename too), and every row passes this table's own first axis —
+ *    a body whose use is naming a program to execute is refused. They were missing, and each was one
+ *    token in front of the licence the language half already refuses: `command node:*`, `timeout 9
+ *    node:*` and `nice node:*` all grant exactly what `node:*` grants.
+ *
+ * KNOWN RESIDUAL, stated rather than hidden, and it is a property of the instrument rather than of this
+ * particular list: a positive list of NAMES cannot be made complete, and two independent review rounds
+ * enumerated escapes faster than rows could be added. Three shapes, none of which a longer list fixes:
+ *  · a version- or distribution-suffixed spelling of a listed interpreter (`python3.12`, `nodejs`);
+ *  · a launcher nobody listed — the set of programs that run another program has no boundary, and each
+ *    round produced more of them;
+ *  · a spelling that defeats the NAME question entirely: `/proc/self/exe` (basename `exe`, the running
+ *    shell), a symlink or a renamed binary, a BusyBox applet, a dynamic loader invoked directly.
+ * Matching a family would need a pattern rather than a set, with its own false-positive surface
+ * (`node-gyp`, `timeout-monitor`), and no pattern addresses the third shape at all. What carries the
+ * residue is therefore NOT this table: it is the three standing fences — the org deny/ask layer runs
+ * ahead of this lane and cannot be silenced by it, a mandated ask is not rule-clearable, and the
+ * narrower exact candidate (plus minting nothing) is always on the same card. This table's job is to
+ * keep the OBVIOUS one-token licence off a card a person clicks once, not to be a boundary.
  */
 export declare const BARE_INTERPRETER_NAMES: ReadonlySet<string>;
+/**
+ * Shell KEYWORDS, refused as a segment's `argv[0]` everywhere this lane reads a command.
+ *
+ * The floor this lane stands on extracts the first TOKEN of a segment and calls it the command name.
+ * That identification is what every comparison here rests on — the interpreter refusal, the deny/ask
+ * layer's per-segment judgement, and a person's reading of the rule text. For a control structure it is
+ * simply false. `for x in once; do curl evil.example; done` splits into three segments whose first
+ * tokens are `for`, `do` and `done`; all three are ordinary bare words, so the floor accepts each,
+ * `curl` is named by nothing, and a published `deny Bash(curl:*)` matches none of them while bash runs
+ * curl. A whole loop body — any number of programs — hides behind three tokens that name no program.
+ *
+ * Refusing the keyword puts the whole command outside the lane, which is the honest answer: no rule can
+ * be minted for it and no rule matches it, so it asks. Recovering these shapes properly needs a real
+ * shell grammar (upstream has one — it parses to a syntax tree and reads the commands out of the
+ * structure, so a keyword is never mistaken for a program); a token-level lane cannot, and pretending
+ * otherwise is the loosening direction.
+ *
+ * `!` is here for the same reason with a sharper edge: it is a keyword that PREFIXES a real command, so
+ * `! node -e …` is the `node` licence the interpreter table exists to refuse, wearing one extra token.
+ * `{`/`}`/`[[`/`]]` are already refused by the floor's argv[0] metacharacter rule; listed anyway,
+ * because that rule belongs to another module and is not this lane's to depend on.
+ */
+export declare const SHELL_RESERVED_WORDS: ReadonlySet<string>;
 /**
  * design/185 §1 — the reviewed command/subcommand grammar the PREFIX suggestion is generated from
  * (exactly the "reviewed command/subcommand grammar" the generator's history note names as the one
@@ -215,10 +285,46 @@ export declare function formatAllowRuleText(command: string, match: PersistedRul
  * Does this rule's command pattern admit `command`?
  *
  * `command` is the raw tool argument: the floor and the folding happen HERE, in that order, so no
- * caller can accidentally match a folded compound. Returns false for anything that is not a single
- * simple command — including every redirection form.
+ * caller can match a command this lane has not read. Returns false for every redirection, substitution,
+ * subshell, backgrounded or escaped form.
+ *
+ * **A PREFIX rule never admits a compound.** This is the single load-bearing line of the connector
+ * widening, and it is checked on the MATCH side rather than left to the mint side: `Bash(npm:*)` is an
+ * ordinary, legitimately mintable rule, and if the "does this command start with `npm `" arm were
+ * allowed to see a compound at all, that rule would admit `npm test && curl evil.example` — one stored
+ * yes to a build command turned into a standing yes to whatever is chained behind it. An EXACT rule has
+ * no such reach by construction: it admits one string, the one it spells.
  */
 export declare function ruleAdmitsCommand(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
+/**
+ * The same match, asked the DENY/ASK layer's question — "does this rule speak about this program run?".
+ *
+ * Split from {@link ruleAdmitsCommand} because the two differ on one axis that decides real cases: a
+ * quoted operator. `curl "https://x/?a=1&b=2"` is ONE command bash runs, and the `&` in a query string
+ * is not a connector; the matching side refuses it anyway (a rule text is a spelling with no operator
+ * characters in it at all — the historical rule-face contract), and the deny side inheriting that
+ * refusal made `deny Bash(curl:*)` silent on the commonest spelling of the very program it names
+ * (adversarial round 3).
+ *
+ * The asymmetry only ever runs one way: this predicate reads MORE commands than the matching one, never
+ * fewer. A shape only the ALLOW side could read would be a standing approval no published policy could
+ * see — the inversion this whole ticket exists to prevent.
+ */
+export declare function ruleAdmitsProgramRun(rule: Pick<PersistedAllowRule, "match" | "command">, command: string): boolean;
+/**
+ * The segments of `command` as the deny/ask layer must judge them, or `undefined` for a command this
+ * lane cannot read.
+ *
+ * A tightening rule speaks about a PROGRAM RUN, and a compound runs several. `Bash(curl:*)` published
+ * as a deny means "this machine does not make that call", and reading `npm test && curl evil.example`
+ * as one unmatched blob answered that with silence — the shape the widening above would otherwise make
+ * permanently approvable. Exported (rather than folded into a matcher here) because the layer that
+ * needs it holds the rules: this module owns what a command IS, `permission-rule-org.ts` owns what the
+ * organization says about each part of it.
+ *
+ * A single simple command yields a one-element list, so a deny that matched before matches identically.
+ */
+export declare function ruleLaneSegmentsOf(command: string): readonly string[] | undefined;
 /**
  * Is `path` inside (or equal to) `root`? Word-boundary containment on the path separator, so `/a` does
  * not contain `/ab`. Both sides are expected to be canonical already.
@@ -271,13 +377,26 @@ export interface RuleSuggestion {
  * shear a quoted segment — harmless in this direction, because the sheared pieces carry quote
  * characters and can never equal a bare lexicon word; every suspicious shape lands on "no prefix".
  *
- * Every produced candidate must survive the round trip — parse as a rule AND admit the very command
- * it was minted from. True by construction (a word-boundary lexicon prefix of a folded simple command
- * is exactly the matcher's two arms); enforced anyway, fail-closed: a candidate that would not
- * round-trip is silently not offered, since offering an option redemption would refuse is worse than
- * offering one fewer.
+ * Every produced candidate must survive the round trip — parse as a rule, come back as the match form
+ * this seat is offering, AND admit the very command it was minted from. Enforced on BOTH seats,
+ * fail-closed: a candidate that would not round-trip is silently not offered, since offering an option
+ * redemption would refuse is worse than offering one fewer.
+ *
+ * The FORM half of that check is not decoration. A command may end in the rule grammar's own prefix
+ * marker — `rm :*` is a legal thing to type — and wrapping it as an exact rule produces the text
+ * `Bash(rm :*)`, which the validator reads back as the PREFIX rule `Bash(rm:*)` over the command `rm`.
+ * Trusting the exact seat's own intent and labelling that result `match: "exact"` put a blanket
+ * every-`rm` rule on the card under the narrowest option's name, one click from being persisted (and,
+ * for a lexicon command like `git status :*`, emitted twice — once mislabelled, once as the real prefix
+ * candidate). The seat therefore believes the PARSER about what it got back, never its own request.
+ *
+ * A COMPOUND (`./gradlew build && ./gradlew test`) fills the exact seat and only that one: the offered
+ * rule spells the whole chain and admits exactly it. That is the shape this seat was missing — the
+ * ordinary build invocation is a connector chain, and a card that could offer nothing for it made every
+ * such command a fresh question forever, with no way for an answer to accumulate.
  *
- * Returns an empty array for anything the rule lane cannot speak for (compounds, redirections,
- * substitutions) — the card then simply carries no "don't ask again" option, which is the honest answer.
+ * Returns an empty array for anything the rule lane cannot speak for (redirections, substitutions,
+ * subshells, backgrounding) — the card then simply carries no "don't ask again" option, which is the
+ * honest answer.
  */
 export declare function suggestRulesForCommand(command: string): RuleSuggestion[];