@sema-agent/core 5.53.0 → 5.54.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 5.54.0 — 2026-08-22
+
+### Fixed
+- **Compound commands are adjudicated segment-wise** (#353 hemostat): the rule lane's whole-string
+  floor made every compound spelling invisible to it — an org/user **deny** on `curl` never fired on
+  `git status && curl evil.example` (fail-open past the deny into the classifier lane), suggestions
+  came back empty, and an exact compound rule could not be minted or matched. Now: any-segment deny
+  refuses the whole string before any allow path; whole-string exact allow admits; all-segments-allow
+  admits; anything else asks with a per-segment suggestion batch (capped at 5). A path-prefixed
+  argv0 (`/usr/bin/curl`) joins the rule lane as text. A build-tool allowlist was considered and
+  rejected (not a CC form).
+- **MCP listings walk their pagination** (#381): tools/list and resources/list read only the FIRST
+  page — later tools silently never mounted and nothing disclosed it. All list sites now walk pages
+  through one bounded chokepoint (20-page cap; cursor-loop guard; a continuation needs a fundable
+  remainder — min(250ms, budget/10)); an unfinished walk is disclosed with a typed reason
+  (`cursor_invalid` | `page_error` | `cursor_loop` | `page_cap` | `budget_exhausted`) on the model
+  face, the operator warning lane (`mcp.listing_incomplete`), and `McpRefreshResult.listingIncomplete`;
+  a refresh that cannot prove an entry gone retains it. **Closed-set note**: `McpListingIncomplete.reason`
+  gains `budget_exhausted` (+ optional `budgetMs`) — a downstream exhaustive switch needs the case.
+- **Ledger stores enforce single-writer-per-directory at construction** (#382): checkpoint /
+  background-agent / workflow-run each documented a boot lock they did not hold — two OS processes
+  could each win the SAME once-only approval, and one process's compaction could erase another's
+  fsync'd rows. The fence now lives with the authority (`shared-ledger.ts` bootstrap takes
+  `<dir>/LOCK`; refcount-joined in-process; crashed-owner locks pruned through a named claim gate);
+  a second OS process is refused at construction. New exports: `FileStoreLockError`,
+  `FileStoreLockErrorCode` (`store.dir_in_use` | `store.dir_claiming` | `store.lock_unreadable`).
+- **The workflow budget gate re-judges after admission** (#383): the ceiling was checked only at
+  dispatch time against a pre-batch snapshot — a 40-item fan-out overshot 26x (serial dispatch
+  identically) and the refusal text blamed "a loop without a termination condition". The
+  authoritative check now runs after `sem.acquire()` against live spend; refused calls settle as
+  failed agent rows carrying `workflow.budget_exceeded`; a fully-cached resume is never gated;
+  bad budget values refuse loudly; budget and agent-cap refusals each name their own cause.
+- **The workflow steer marker is unpredictable** (test P0-KPI #9): the workflow lane's steer
+  correlation marker was a monotone counter (`steer-1`…) — untrusted content could pre-claim the
+  tag and self-declare correlation, the hole the subagent steer seat had already closed
+  (design/122 r1-m3). Both seats now single-source the same 12-hex fragment; markers are
+  per-delivery distinct, ephemeral, never journaled.
+- **Pre-release rescan dispositions (seven, fixed in-tree before publish)**: the compound-splitter
+  extraction was not byte-identical for the readonly classifier (`ls; 2>/dev/null` had flipped from
+  ask to auto-allow — restored); a near-exhausted MCP walk budget was spent as a real request and
+  its cut-off blamed on the server (now core-attributed, see #381 above); a stuck paginator's
+  re-served page was appended twice and the duplicate blamed on a namespacing collision (rewind of
+  provably byte-identical re-serves; drop reasons split); a failed `BootLock.release()` left a stale
+  holder able to delete its successor's live fence (release is one-shot again); a zero-ref fence
+  entry was joinable without consulting the disk (re-validated, foreign owners refused by name);
+  `FileWorkflowRunStore.close()`'s doc credited a backend factory that never constructs it;
+  `docs/ARCHITECTURE.md`'s lock coverage contradicted `docs/KNOWN-ISSUES.md`.
+- Behavior narrowings (named): org/user denies now reach compound spellings (previously fail-open);
+  a second OS process over a ledger directory refuses at construction instead of corrupting;
+  `compactNow()` on a closed store throws; workflow budget bad values refuse at construction;
+  budget-refused calls appear as failed agent rows; a second `dispose()` after a failed fence
+  release removes nothing; an in-process re-open over an unreadable stranded lock refuses
+  (`store.lock_unreadable`); a stranded fence taken by another process refuses (`store.dir_in_use`);
+  a failed fence release warns (was silent); `ls; 2>/dev/null` asks again (restores the 5.53
+  contract).
+
 ## 5.53.0 — 2026-08-21
 
 ### Fixed

package/dist/agents/subagent.d.ts

@@ -356,6 +356,10 @@ export interface SubagentSteerHandle {
      */
     resume?: (content: string) => Promise<string>;
 }
+/** design/122 r1-m3 — UNPREDICTABLE correlation-marker fragment (uuid random tail, 12 hex chars). A marker
+ *  must not be guessable by untrusted content — the old `steer-a<seq>` global counter let injected text
+ *  pre-claim "[steer-aN]" and self-declare correlation; the same fix applies to the new resume markers. */
+export declare function markerFragment(): string;
 /**
  * design/122 D2 — build the `resume` verb for one delegation (closure over the ledger + delegation runner —
  * NEVER the parent tool ctx / spec builder, r1-m5). Validation order: TTL sweep (MAJOR-1) → disposed?

package/dist/agents/subagent.js

@@ -436,7 +436,7 @@ function createBgActivityBeat(parentToolCallId, emitTick, noteActivity) {
             emitTick(starts);
     };
 }
-function markerFragment() {
+export function markerFragment() {
     return uuidv7().replace(/-/g, "").slice(-12);
 }
 function createSteerHandle(stream, parentToolCallId, agentName, settled, retain) {

package/dist/core/mcp.d.ts

@@ -85,6 +85,39 @@ export interface McpDroppedTool {
     tool: string;
     reason: string;
 }
+/**
+ * The completeness verdict of a walked STANDARD MCP list method (`tools/list`, `resources/list` — see
+ * {@link walkMcpListPages}). ABSENT means the walk reached the end of pagination and the aggregated
+ * listing IS the server's full list. PRESENT means it is not, and the listing must not be presented —
+ * or DIFFED — as if it were: an entry missing from a truncated listing is unproven-absent, not
+ * withdrawn (that inference is exactly what made a paginating server's second-page tools read as
+ * `removed`).
+ *  - `page_cap` — {@link MAX_MCP_LIST_PAGES} pages were walked with a cursor still pending;
+ *  - `cursor_loop` — the server handed back a cursor already used in this walk (a paginator that does
+ *    not advance); the walk stops rather than spinning to the cap re-appending the same page;
+ *  - `cursor_invalid` — the server sent a `nextCursor` that is not a string (`null` excepted: that is
+ *    JSON's absent optional). It cannot be followed and it is not proof of the end, so the walk stops
+ *    and says so instead of certifying a short listing as complete;
+ *  - `page_error` — a CONTINUATION page failed. The pages already retrieved are kept and the failure
+ *    text carried. A FIRST-page failure is never this: it still throws (a caller's "no listing at all"
+ *    must not degrade into "an empty listing");
+ *  - `budget_exhausted` — CORE stopped the walk: the time this listing is allowed to spend
+ *    ({@link walkMcpListPages}'s `budgetMs`) had too little left to fund another request
+ *    ({@link MIN_MCP_PAGE_BUDGET_MS}), so none was sent. Distinct from `page_error` on purpose — the
+ *    server neither failed nor was asked. Issuing that request anyway would hand the SDK a
+ *    near-zero timeout, and its -32001 would arrive here wearing the server's failure clothes.
+ * `error` is SERVER-authored text — neutralize it before it rides any model/operator face.
+ */
+export interface McpListingIncomplete {
+    reason: "page_cap" | "cursor_loop" | "cursor_invalid" | "page_error" | "budget_exhausted";
+    /** Pages actually retrieved before the walk stopped (≥ 1 — a zero-page walk throws instead). */
+    pages: number;
+    error?: string;
+    /** The walk's total time budget in ms. Present ONLY on `budget_exhausted`, where it is the whole
+     *  actionable content of the verdict (which bound to raise); every other reason leaves it absent
+     *  rather than reporting a budget that had nothing to do with the stop. */
+    budgetMs?: number;
+}
 /** Tools materialized from one or more MCP servers, plus a disposer to disconnect them. */
 export interface MaterializedMcp {
     tools: AgentTool[];
@@ -125,10 +158,17 @@ export interface MaterializedMcp {
         pendingRemovals: string[];
     };
     /**
-     * One entry per server that failed to connect / list its tools and was SKIPPED (fail-open,
-     * design/29). The task proceeds with the healthy servers' tools — a single bad server (missing
-     * stdio command, unreachable URL) must never brick every task in the scenario. The Runner forwards
-     * these to `onError(phase:"mcp")`. Empty when every server connected.
+     * The OPERATOR warning lane for this materialization (the Runner forwards each entry to
+     * `onError(phase:"mcp")`). Empty when every server connected and listed completely. Two populations,
+     * distinguishable by the `code` each Error carries — a consumer must NOT read mere presence as "this
+     * server was skipped":
+     *  - `mcp.server_unavailable` — a server that failed to connect / list its tools and was SKIPPED
+     *    (fail-open, design/29): the task proceeds with the healthy servers' tools, because a single bad
+     *    server (missing stdio command, unreachable URL) must never brick every task in the scenario;
+     *  - `mcp.listing_incomplete` — a server that DID connect but whose `tools/list` pagination walk did
+     *    not reach the end ({@link McpListingIncomplete}): its tools past the stopping point are not
+     *    mounted this task, which is a capability loss the operator must see rather than infer from a
+     *    short tool list.
      */
     warnings: Error[];
     /**
@@ -186,7 +226,13 @@ export interface MaterializedMcp {
     dispose: () => Promise<void>;
 }
 /** [1605] One per-server entry of {@link MaterializedMcp.refresh}. `added`/`removed` are namespaced
- *  (`mcp__<server>__<tool>`) names; `tools`/`axes`/`dropped` are present only on `"refreshed"`. */
+ *  (`mcp__<server>__<tool>`) names; `tools`/`axes`/`dropped` are present only on `"refreshed"`.
+ *  The model-facing refresh receipt renders each `dropped` entry with ITS OWN `reason` (schema
+ *  gate, same-listing name collision, …) — never a blanket label; a consumer matching that receipt
+ *  text should key on the tool name, not on any fixed reason wording. Note the startup-time
+ *  sibling: two DECLARED servers whose names normalize to one prefix refuse the whole mount at
+ *  connect (`config.mcp_server_name_collision`, both original spellings named) — a deployment
+ *  carrying such a pair learns at the first materialize, with the rename spelled out in the error. */
 export interface McpRefreshResult {
     server: string;
     /** The server's namespaced-name prefix (`mcp__<normalized-server>__`) — the consumer's SPLICE
@@ -199,11 +245,37 @@ export interface McpRefreshResult {
     status: "refreshed" | "not_connected" | "failed" | "revoked";
     toolCount: number;
     added: string[];
+    /**
+     * Names that were mounted before this refresh and are no longer in the roster it returns — i.e. an
+     * assertion that the server withdrew them. It is therefore EMPTY whenever {@link listingIncomplete}
+     * is present, and empty as a FACT rather than a policy: an incomplete walk cannot prove absence, so
+     * it retains what it could not prove gone (see `listingIncomplete`) and nothing leaves. `added` is
+     * unaffected — a name that IS in the partial listing was really listed, whether or not the walk
+     * finished (#381).
+     */
     removed: string[];
     tools?: AgentTool[];
     axes?: McpToolAxis[];
     dropped?: McpDroppedTool[];
+    /**
+     * Set on `not_connected` / `failed` / `revoked`; ALSO set on a `"refreshed"` entry whose listing walk
+     * did not finish (see {@link listingIncomplete}) — a refresh that produced usable tools is not a
+     * failure, so the status stays `refreshed` and the incompleteness rides here.
+     */
     error?: string;
+    /**
+     * #381 — present when this entry's `tools/list` walk did NOT reach the end of pagination. `tools` is
+     * then a MERGE: everything the partial listing did return, plus the previously-mounted entries whose
+     * absence it cannot prove (so the consumer's replace-the-whole-prefix swap withdraws nothing, and
+     * `removed: []` describes a roster that really lost nothing). Absent on a complete walk and on every
+     * non-`refreshed` status.
+     *
+     * RESIDUAL, honest: the model-facing `RefreshMcpTools` receipt renders a refreshed entry's line from
+     * added/removed/excluded/dropped only, so this fact reaches the STRUCTURED face (`details.results`)
+     * and the operator, not the receipt text — rendering it there is a prepare-task change, filed rather
+     * than smuggled in here.
+     */
+    listingIncomplete?: McpListingIncomplete;
 }
 /** design/99 §E9 — projected per-server MCP status (see {@link MaterializedMcp.statuses}). NOTE: `serverInfo`
  *  and `error` are SERVER-controlled strings (verbatim from the remote) — UNTRUSTED; a consumer rendering them
@@ -490,6 +562,97 @@ export declare function applyCallerAxisOverride(name: string, hint: McpToolAxis
  *  for the discrimination nails; the message is SERVER-authored and is only ever classified here, never
  *  trusted as instructions. */
 export declare function classifyDirReadInvalidParams(message: string): "not_found" | "not_directory";
+/**
+ * The content key {@link walkMcpListPages}'s cursor-loop arm uses to recognize an entry it already
+ * collected: the entry's own JSON, which is what the server sent and what a re-served page repeats
+ * verbatim. `undefined` for anything unserializable — an entry that cannot be keyed is never treated as
+ * a repeat, so the failure direction is "kept, and disclosed by the lane that judges it" rather than
+ * "silently gone".
+ *
+ * NOT a semantic identity: two spellings of the same entry (different key order, a description the
+ * server re-rendered) read as different entries here and both survive. That is the safe direction —
+ * this key only ever authorizes a DELETION, so it must be exact and never clever.
+ *
+ * Exported for the walker's own unit pins (same reason {@link walkMcpListPages} is): its bound is a
+ * behavior, and a pin that re-declared the bound locally would pass while the real one drifted.
+ */
+export declare function listEntryFingerprint(entry: unknown): string | undefined;
+/**
+ * #381 — walk a paginated MCP list method to the END (`{cursor?}` → `{items, nextCursor?}`), bounded.
+ *
+ * Every spec-standard MCP list method is paginated the same way: absence of `nextCursor` means "that
+ * was the last page". A single request therefore returns the WHOLE list only for servers that choose
+ * not to paginate — and a server may start paginating at any time, with no protocol change and no
+ * malice, the moment its list outgrows its own page size. Treating page one as the complete list is
+ * both a capability loss (the rest is never mounted) and, at any call site that DIFFS two listings, an
+ * active falsehood about the server's inventory.
+ *
+ * Contract:
+ *  - page ONE is fetched with the caller's own historic parameters (`cursor === undefined`), so a
+ *    non-paginating server's wire traffic is byte-identical to before;
+ *  - a FIRST-page failure propagates unchanged — every caller's failure shape (skipped server,
+ *    `failed` refresh, per-server attributed aggregate error) is built on that throw;
+ *  - a CONTINUATION failure keeps the pages already retrieved and reports {@link McpListingIncomplete}
+ *    (`page_error`) — fail-open WITH disclosure, the same law {@link readDirViaExtension} follows —
+ *    except an ABORT, which still propagates (a cancelled walk is not a short listing);
+ *  - a repeated cursor stops the walk (`cursor_loop`) instead of spinning to the cap, AND undoes the
+ *    entries that page re-served (a paginator that does not advance is typically one answering with a
+ *    page already collected, and keeping it is how one entry gets listed twice) — judged by
+ *    `identityOf` where the caller can key its entries, whole-page otherwise; an unreadable cursor
+ *    stops the walk as `cursor_invalid` rather than passing for the end of the listing;
+ *  - {@link MAX_MCP_LIST_PAGES} pages with a cursor still pending stops it too (`page_cap`);
+ *  - a remainder too short to fund a real request stops it as `budget_exhausted` — core's own doing,
+ *    named as such (see {@link MIN_MCP_PAGE_BUDGET_MS}).
+ * SIZE, stated rather than assumed: a single page has never been bounded here (a server could always
+ * answer with an arbitrarily long list), and walking multiplies that existing exposure by at most the
+ * page cap — a bounded multiplier, not a new unbounded surface. Per-entry admission stays where it
+ * already is (the intake schema gate, which also drops a name a later page repeats).
+ *
+ * TIME, the reason `budgetMs` exists (codex review, confirmed): the page cap bounds REQUESTS, not
+ * latency. Giving every page its own full request timeout would let a server that stalls each page hold
+ * a connect (or a refresh) for up to twenty timeouts — twenty minutes at the SDK's 60s default, where
+ * an unpaginated listing cost one. So the WALK gets the budget a single listing used to have: page one
+ * is issued with the full amount (byte-identical to the pre-walk request) and each continuation gets
+ * only what is left. ACCEPTED COST, stated: a genuinely slow server whose pages together outlast that
+ * bound is truncated where a single-request listing would not have been — but that truncation is
+ * DISCLOSED, while the alternative is an undisclosed twenty-fold latency ceiling on the task's startup
+ * path. The bound is the caller's own configured request timeout, not a new knob, so a deployment that
+ * needs more already has the dial. `fetchPage` receives the remaining budget and MUST spend it as that
+ * request's timeout — the deadline is cooperative, since only the caller can pass a timeout to its own
+ * transport — and must REPORT that same number if the request then times out: a page cut off at 3ms
+ * whose failure text names the whole listing budget describes a wait that never happened.
+ *
+ * NOT merged with {@link readDirViaExtension}, which walks the same way but owns CC-anchored
+ * first-page `InvalidParams` discrimination (not-a-directory vs not-found) and its own three-state
+ * flags; folding it in here would put that CC semantics into the standard-method path where it has no
+ * meaning.
+ *
+ * Exported for the walker's own unit pins — its arms are failure/deadline states that no fixture server
+ * can drive deterministically. Every production consumer goes through the three call sites in this file.
+ */
+export declare function walkMcpListPages<T>(fetchPage: (cursor: string | undefined, remainingMs: number) => Promise<{
+    items: T[];
+    nextCursor?: string;
+    cursorInvalid?: boolean;
+}>, opts: {
+    budgetMs: number;
+    onPage?: () => void;
+    signal?: AbortSignal;
+    /** A key for one entry's CONTENT — equal keys mean the same listing entry, served again.
+     *  `undefined` for an entry the caller cannot key. Used ONLY by the cursor-loop arm, to tell a
+     *  re-served page from a page that merely arrived with a broken cursor; absent ⇒ that arm cannot
+     *  tell them apart and falls back to dropping the whole page (see it for the trade).
+     *
+     *  CONTENT, not name: an entry's name is what the CALLERS' admission gates key on, and they judge
+     *  each entry on its own (a tool whose schema they refuse is dropped, and a later entry of the same
+     *  name is then free to mount). Keying this on the name would let this walk delete the second
+     *  entry before any of that ran — the only admissible definition of a tool, removed on the theory
+     *  that a name cannot appear twice, which is a rule the layer below owns and applies differently. */
+    fingerprintOf?: (item: T) => string | undefined;
+}): Promise<{
+    items: T[];
+    incomplete?: McpListingIncomplete;
+}>;
 /**
  * RB-408 G12 — `tools/call` result parse that accepts the MCP `2026-07-28` widening of
  * `structuredContent` from "a JSON object" to ANY JSON value (the same revision that relaxes

package/dist/core/mcp.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";
@@ -719,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) {
@@ -740,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 {
@@ -781,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),
@@ -797,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) {
@@ -804,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),
@@ -875,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;
@@ -918,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)})`
@@ -959,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)" });
@@ -973,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);
@@ -996,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,
                 };
             },
@@ -1125,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();
@@ -1177,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) {
@@ -1192,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;
@@ -1254,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 } } : {}),
         };
     }
@@ -1267,7 +1418,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
-    const mintedNames = new Set();
+    const mintedNames = new Map();
     for (const t of listed.tools) {
         if (spec.allowTools && !spec.allowTools.includes(t.name)) {
             continue;
@@ -1290,14 +1441,17 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         }
         const remoteName = t.name;
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
-        if (mintedNames.has(namespacedName)) {
+        const mintedBy = mintedNames.get(namespacedName);
+        if (mintedBy !== undefined) {
             dropped.push({
                 tool: inlineUntrusted(t.name),
-                reason: `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`,
+                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.add(namespacedName);
+        mintedNames.set(namespacedName, t.name);
         const hintAxis = mcpAxisFor(namespacedName, t.annotations);
         const axis = applyCallerAxisOverride(namespacedName, hintAxis, spec.toolAxes?.[remoteName]);
         if (axis)
@@ -1417,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;
+}