@sema-agent/core 5.52.0 → 5.54.0

package/CHANGELOG.md

@@ -1,5 +1,104 @@
 # 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
+- **An MCP refresh no longer rewrites the cacheable tool prefix** (#375 root fix): `RefreshMcpTools`
+  re-inserted the server's tool domain at the TAIL of the mount array — the wire order — so a
+  byte-identical listing still displaced the whole domain past every later tool, a full provider
+  prefix-cache re-bill the model itself was told to trigger ("refresh when a listing looks stale").
+  The domain now re-enters at its anchor (the lowest index it occupied): an unchanged listing
+  produces a byte-identical array. First-time mounts still append.
+- **Thinking replay survives strict gateways and non-streaming rewrites** (#374 adjacent):
+  the replay judge is shape-based (only a non-empty string counts as a signature — a JSON-roundtrip
+  `null`/number can no longer ride onto the wire), `signature_delta` refuses non-string coercion,
+  and an inlined `content_block_start` thinking block (the compat-gateway SSE-rewrite form) is now
+  fully captured — text and signature — instead of being dropped from every subsequent request.
+- **The cache-break detector tells the truth about reorders** (#376): an order-preserving hash
+  now attributes a pure reorder to `tool-set` with its own wording (previously it fell through to
+  "server-or-ttl … not a client-side prefix bug" — actively misleading, and the exact shape #375
+  just fixed); the low-hit-rate summary discriminates "prefix keeps changing" from "this route
+  reports no caching" using cacheWrite facts instead of guessing.
+- **The MCP refresh region is transactional and collision-gated** (#377): tool effect records are
+  reset before the fold (a refreshed read-only tool no longer silently degrades to write), a
+  rejected listing restores both non-monotone tables, two servers whose names normalize to the
+  same prefix refuse at connect (`config.mcp_server_name_collision`, both original spellings
+  named), and a single listing minting two identical tool names keeps the first with a disclosed
+  drop.
+- Behavior narrowings (named): colliding server configs from "silent shared domain" to a loud
+  connect refusal; same-listing name collisions from "both mounted under one name" to
+  "first kept, drop disclosed".
+
+- **Pre-release scan dispositions (three, fixed in-tree before publish)**: the protocol-name
+  reservation now covers ALIASES (a `__`-shaped caller alias refuses at prepare with the same loud
+  code — it was a dispatchable name sitting inside a server's prefix domain, which the refresh
+  region would classify and clear as remote); the refresh receipt states each drop's OWN reason
+  (a fixed "invalid schema" label lied about the collision lane); the A2A mount gains the same
+  normalized-prefix collision gate as MCP (`config.a2a_peer_name_collision`), making the
+  protocol-naming contract's engine-wide claim true.
+- Behavior narrowing (named): a caller tool alias containing `__` from "accepted" to a loud
+  prepare refusal; colliding A2A peer names from "silent shared domain" to a connect refusal.
+
+### Notes
+- Residuals ticketed: #379 (open-responses presence judge, inline text-block sibling, two-phase
+  refresh observation). #378 resolved by the alias-reservation fix above.
+
 ## 5.52.0 — 2026-08-21
 
 ### Added

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/brain/anthropic.js

@@ -66,7 +66,8 @@ function toAnthropicMessages(ctx, model) {
             for (const c of m.content) {
                 if (c.type === "thinking") {
                     const tc = c;
-                    const sig = tc.thinkingSignature;
+                    const sigRaw = tc.thinkingSignature;
+                    const sig = typeof sigRaw === "string" && sigRaw.length > 0 ? sigRaw : undefined;
                     if (tc.redacted) {
                         if (sig)
                             blocks.push({ type: "redacted_thinking", data: sig });
@@ -377,9 +378,19 @@ export function createAnthropicBrain(config = {}) {
                                     acc.redacted = true;
                                     acc.signature = cb.data ?? "";
                                 }
+                                else {
+                                    if (typeof cb.thinking === "string" && cb.thinking !== "")
+                                        acc.text = cb.thinking;
+                                    if (typeof cb.signature === "string" && cb.signature !== "")
+                                        acc.startSignature = cb.signature;
+                                }
                                 acc.pb = { type: "thinking", thinking: "" };
                                 partial.content = [acc.pb];
                                 out.push({ type: "thinking_start", contentIndex: idx, partial: { ...partial } });
+                                if (acc.text !== "") {
+                                    acc.pb.thinking = acc.text;
+                                    out.push({ type: "thinking_delta", contentIndex: idx, delta: acc.text, partial: { ...partial } });
+                                }
                             }
                             else if (cb.type === "tool_use") {
                                 acc.type = "tool_use";
@@ -418,6 +429,7 @@ export function createAnthropicBrain(config = {}) {
                                 }
                             }
                             else if (d.type === "thinking_delta" && d.thinking) {
+                                acc.startSignature = undefined;
                                 acc.text += d.thinking;
                                 if (acc.pb && acc.pb.type === "thinking")
                                     acc.pb.thinking = acc.text;
@@ -430,7 +442,7 @@ export function createAnthropicBrain(config = {}) {
                                     }
                                 }
                             }
-                            else if (d.type === "signature_delta" && d.signature) {
+                            else if (d.type === "signature_delta" && typeof d.signature === "string" && d.signature.length > 0) {
                                 acc.signature += d.signature;
                             }
                             else if (d.type === "input_json_delta" && d.partial_json) {
@@ -536,8 +548,9 @@ export function createAnthropicBrain(config = {}) {
                                 if (acc.text.length > 0 || acc.redacted === true)
                                     reasoningSeen = true;
                                 const block = { type: "thinking", thinking: acc.text };
-                                if (acc.signature)
-                                    block.thinkingSignature = acc.signature;
+                                const sig = acc.signature || acc.startSignature;
+                                if (sig)
+                                    block.thinkingSignature = sig;
                                 if (acc.redacted)
                                     block.redacted = true;
                                 finalContent.push(block);

package/dist/core/a2a.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import { A2A_TASK_STATES } from "./a2a-task-state.js";
 import { describeHttpTransportFailure, resolveProtocolHttpHeaders } from "./mcp.js";
-import { mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
+import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
 import { A2A_NAMESPACE } from "./protocol-table.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
 const A2A_REQUEST_TIMEOUT_MS = 30_000;
@@ -575,6 +575,17 @@ function asPeerWarning(spec, err) {
     return warning;
 }
 export async function materializeA2aTools(specs, principal, signal) {
+    if (specs.length > 0) {
+        const collision = findNamespacePrefixCollision(A2A_NAMESPACE, specs.map((s) => s.name));
+        if (collision) {
+            const [a, b] = collision.peers;
+            const e = new Error(a === b
+                ? `A2A peer "${a}" is declared twice — each peer needs its own name (both mount under "${collision.prefix}").`
+                : `A2A peer names "${a}" and "${b}" both mount under "${collision.prefix}" — the namespaced tool name keeps only [a-zA-Z0-9_-], so they are the same domain to this engine. Rename one.`);
+            e.code = "config.a2a_peer_name_collision";
+            throw e;
+        }
+    }
     const lifecycle = { disposed: false };
     const tools = [];
     const toolAxes = [];

package/dist/core/cache-break-detector.js

@@ -27,6 +27,7 @@ export class CacheBreakDetector {
             systemHash: fnv1a(input.systemPrompt),
             perToolHash: new Map(input.tools.map((t) => [t.name, fnv1a(`${t.name}\0${t.description}\0${stableStringify(t.parameters)}`)])),
             toolSetHash: fnv1a([...input.tools.map((t) => t.name)].sort().join(",")),
+            toolOrderHash: fnv1a(input.tools.map((t) => t.name).join(",")),
             modelKey: input.modelKey,
             cacheRead: input.cacheRead,
             at: Date.now(),
@@ -59,7 +60,11 @@ export class CacheBreakDetector {
             }
             else if (snap.toolSetHash !== prev.toolSetHash) {
                 cause = "tool-set";
-                detail = "the tool set changed (a tool was added/removed/reordered)";
+                detail = "the tool set changed (a tool was added or removed)";
+            }
+            else if (snap.toolOrderHash !== prev.toolOrderHash) {
+                cause = "tool-set";
+                detail = "the tool ORDER changed (same tools, different positions) — a reordered tool list is a byte-different prefix from the first moved tool onward, so the provider re-bills the whole tail";
             }
             else if (snap.systemHash !== prev.systemHash) {
                 cause = "system-prefix";
@@ -68,10 +73,11 @@ export class CacheBreakDetector {
             else {
                 const gapMs = snap.at - prev.at;
                 cause = "server-or-ttl";
+                const checked = "nothing this detector fingerprints (system prefix, tool set + order, model)";
                 detail =
                     gapMs < SERVER_GAP_MS
-                        ? `nothing in the prefix changed and the gap was ${Math.round(gapMs / 1000)}s — likely a server-side miss, not a client-side prefix bug`
-                        : `nothing changed but the gap was ${Math.round(gapMs / 60_000)}min — likely a normal TTL expiry (cold cache), not a bug`;
+                        ? `${checked} changed and the gap was ${Math.round(gapMs / 1000)}s — most likely a server-side miss; the message history is not fingerprinted, so volatile content early in the conversation would also land here`
+                        : `${checked} changed and the gap was ${Math.round(gapMs / 60_000)}min — most likely a normal TTL expiry (cold cache)`;
             }
         }
         return { turn: input.turn, cacheReadBefore: before, cacheReadAfter: after, cause, detail };

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