@sema-agent/core 5.21.0 → 5.22.0

package/dist/core/runner/runtask.js

@@ -32,13 +32,13 @@ import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { hasVerifiableStructureSignal } from "./grounding-signal.js";
 import { hasDestroy, isIsolated } from "../remote-env.js";
 import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
-import { formatHookFeedback } from "../hooks.js";
+import { cloneObserverInput, formatHookFeedback } from "../hooks.js";
 import { buildHumanInputEvent, projectHumanInput } from "../human-input-projection.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { RunnerSharedToolResultStore } from "../tool-result-store.js";
 import { formatDiagnosticsBlock } from "../lsp-diagnostics.js";
-import { isApprovalSettledBy, refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.js";
+import { checkToolPolicyProjection, constraintChainDigest, constraintChainEntryOf, isApprovalSettledBy, refuseOutOfContractDecision, toolPolicyNameSets } from "../tool-policy.js";
 import { defaultTaskRegistry } from "../task-registry.js";
 import { discloseDroppedPending, isDelegatedAgentTerminal, PendingSessionNotifications, renderTaskNotificationXml, SystemInjectionQueue, taskNotificationDedupKey } from "../task-notification.js";
 import { ToolDetachHub } from "../tool-detach.js";
@@ -2324,6 +2324,7 @@ export class Runner {
                 ...(s.retryInMs !== undefined ? { retryInMs: s.retryInMs } : {}),
                 ...(s.attempt !== undefined ? { attempt: s.attempt } : {}),
                 ...(s.maxRetries !== undefined ? { maxRetries: s.maxRetries } : {}),
+                ...(s.errClass !== undefined ? { errClass: s.errClass } : {}),
                 ...ident(),
             });
         };
@@ -2341,7 +2342,16 @@ export class Runner {
                 : t.kind === "breaker"
                     ? { kind: "breaker.transition", version: 1, taskId: rs.telemetry.taskId, key: t.key, phase: t.phase, failures: t.failures, ts: Date.now() }
                     : t.kind === "retry"
-                        ? { kind: "brain.retry", version: 1, taskId: rs.telemetry.taskId, attempt: t.attempt, phase: t.phase, ts: Date.now() }
+                        ? {
+                            kind: "brain.retry",
+                            version: 1,
+                            taskId: rs.telemetry.taskId,
+                            attempt: t.attempt,
+                            phase: t.phase,
+                            ...(t.errClass !== undefined ? { errClass: t.errClass } : {}),
+                            ...(t.nextDelayMs !== undefined ? { nextDelayMs: t.nextDelayMs } : {}),
+                            ts: Date.now(),
+                        }
                         : { kind: "vision.placeholder", version: 1, taskId: rs.telemetry.taskId, count: t.count, ts: Date.now() });
         };
         const withBrainSinks = (fn) => runWithStatusSink(statusEmit, () => runWithBrainTelemetry(telemetryEmit, fn));
@@ -3719,6 +3729,128 @@ export class Runner {
                     "re-supply would run the resumed leg under a different ancestor chain than it suspended with; " +
                     "rejected pre-CAS (the checkpoint stays pending) — re-resume with the full original chain");
             }
+            const expectedDigest = cp.state.inheritedGate.constraintDigest;
+            if (expectedDigest !== undefined) {
+                const persistedChain = cp.state.inheritedGate.constraintChain;
+                if (persistedChain === undefined || constraintChainDigest(persistedChain) !== expectedDigest) {
+                    throw new CheckpointError("resume.parent_constraint_mismatch", "the checkpoint's OWN recorded constraint chain does not match its recorded digest " +
+                        "(corrupt / inconsistently-minted row) — the frozen deny data the resume would execute is not the data the " +
+                        "digest authenticates; rejected pre-CAS (the checkpoint stays pending)");
+                }
+                const suppliedDigest = constraintChainDigest((internals?.inheritedGate?.parentConstraints ?? []).map((pc) => constraintChainEntryOf(pc.policy, { ...(pc.autoMode !== undefined ? { autoModeArmed: true } : {}), ...(pc.durableMandate === true ? { durableMandate: true } : {}), ...(pc.contentMandate === true ? { contentMandate: true } : {}) })));
+                if (suppliedDigest !== expectedDigest) {
+                    throw new CheckpointError("resume.parent_constraint_mismatch", "the re-supplied parent-constraint chain's projection content does not match what the checkpoint recorded " +
+                        `(recorded ${expectedDigest}, re-supplied ${suppliedDigest}) — a same-shape chain with different frozen ` +
+                        "deny data would run the resumed leg under a different ancestor gate than it suspended with; " +
+                        "rejected pre-CAS (the checkpoint stays pending) — re-resume with the original chain's policies");
+                }
+            }
+        }
+        const resumeInternals = internals?.inheritedGate?.parentConstraints !== undefined
+            ? {
+                ...internals,
+                inheritedGate: {
+                    ...internals.inheritedGate,
+                    parentConstraints: Object.freeze(internals.inheritedGate.parentConstraints.map((e) => ({ ...e }))),
+                },
+            }
+            : internals;
+        if (this.deps.lockedConfig?.keys?.includes("toolPolicy") === true && taskConfig.basePolicyForResumeEdit !== undefined) {
+            throw new CheckpointError("checkpoint.invalid_outcome", "TaskSpec.basePolicyForResumeEdit is administratively locked by this deployment (locked key \"toolPolicy\") — a task-supplied " +
+                "resume-edit policy is refused pre-CAS (the checkpoint stays pending); remove the field or change the deployment's lock configuration");
+        }
+        if (plainPolicyOutcome !== undefined &&
+            plainPolicyOutcome.decision === "allow" &&
+            plainPolicyOutcome.updatedInput !== undefined &&
+            cp.pendingAction.kind === "tool_approval" &&
+            cp.pendingAction.toolName !== ASK_USER_QUESTION_TOOL_NAME) {
+            const editedArgs = plainPolicyOutcome.updatedInput;
+            const editBudget = {
+                resourceRemainingMicroUsd: remainingBudgetMicroUsd(cp.resourceLedger),
+                resourceSpentMicroUsd: cp.resourceLedger?.spentMicroUsd ?? 0,
+                suspendCount: cp.suspendCount ?? 0,
+            };
+            const editedReq = {
+                toolName: cp.pendingAction.toolName,
+                args: editedArgs,
+                toolCallId: cp.pendingAction.toolCallId,
+                budget: editBudget,
+                ...(cp.state.handsCwd !== undefined ? { cwd: cp.state.handsCwd } : {}),
+            };
+            const editSignal = taskConfig.signal;
+            const raceEditAbort = async (p) => {
+                if (editSignal === undefined)
+                    return p;
+                if (editSignal.aborted) {
+                    throw new CheckpointError("checkpoint.resume_aborted", "the resume was aborted while re-adjudicating the approver's edit — the checkpoint stays pending and is resumable with a live signal");
+                }
+                return new Promise((resolve, reject) => {
+                    const onAbort = () => reject(new CheckpointError("checkpoint.resume_aborted", "the resume was aborted while re-adjudicating the approver's edit — the checkpoint stays pending and is resumable with a live signal"));
+                    editSignal.addEventListener("abort", onAbort, { once: true });
+                    p.then((v) => { editSignal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { editSignal.removeEventListener("abort", onAbort); reject(e); });
+                });
+            };
+            const ig = cp.state.inheritedGate;
+            if (ig?.requiresParentConstraint === true) {
+                const chain = ig.constraintChain;
+                const unprojectable = chain === undefined
+                    ? "the checkpoint predates the frozen projection chain (no constraintChain recorded)"
+                    : chain.some((e) => "opaque" in e)
+                        ? "the inherited chain carries an OPAQUE layer (no projection exported)"
+                        : chain.some((e) => !("opaque" in e) && e.requiresLiveRemainder)
+                            ? "an inherited chain layer declares a live remainder beyond its projection"
+                            : undefined;
+                if (unprojectable !== undefined) {
+                    throw new CheckpointError("resume.constraint_unprojectable", `the approver EDITED this call's input, but the inherited ancestor chain cannot re-adjudicate the edit statically: ${unprojectable}. ` +
+                        "Refusing the edited resume pre-CAS (the checkpoint stays pending and remains decidable) — approve the shown input as-is, deny it, " +
+                        "or re-issue the edited action as a fresh call so the full live chain adjudicates it");
+                }
+                for (const entry of chain) {
+                    const denied = checkToolPolicyProjection(entry, editedReq);
+                    if (denied !== undefined) {
+                        throw new CheckpointError("resume.constraint_rejected", `the approver EDITED this call's input and a FROZEN inherited ancestor constraint denies the edited args${denied.message ? `: ${denied.message}` : ""}. ` +
+                            "Refused pre-CAS (fresh-redecision semantics: the checkpoint stays pending and the same token remains decidable — approve as shown, deny, or edit differently)");
+                    }
+                }
+            }
+            const toolPolicyLocked = this.deps.lockedConfig?.keys?.includes("toolPolicy") === true;
+            const editBasePolicy = toolPolicyLocked
+                ? (this.deps.basePolicyForResumeEdit ?? this.deps.toolPolicy)
+                : (taskConfig.basePolicyForResumeEdit ?? this.deps.basePolicyForResumeEdit ?? taskConfig.toolPolicy ?? this.deps.toolPolicy);
+            if (editBasePolicy !== undefined) {
+                let rechecked;
+                try {
+                    rechecked = refuseOutOfContractDecision(await raceEditAbort(Promise.resolve(editBasePolicy.check(editedReq, editSignal))));
+                }
+                catch (err) {
+                    if (err instanceof CheckpointError)
+                        throw err;
+                    rechecked = { action: "deny", message: `the resume-edit policy re-check errored: ${err instanceof Error ? err.message : String(err)}` };
+                }
+                if (rechecked.action === "deny") {
+                    throw new CheckpointError("resume.constraint_rejected", `the approver EDITED this call's input and the deployment's resume-edit policy denies the edited args${rechecked.message ? `: ${rechecked.message}` : ""}. ` +
+                        "Refused pre-CAS (the checkpoint stays pending and remains decidable)");
+                }
+                if (rechecked.updatedInput !== undefined && !deepJsonEqual(rechecked.updatedInput, editedArgs)) {
+                    throw new CheckpointError("resume.constraint_rejected", `the deployment's resume-edit policy REWROTE the approver's edited args to a different value than was approved — the durable resume cannot execute either the un-adjudicated edit or an unapproved rewrite; ` +
+                        `refused pre-CAS (the checkpoint stays pending); re-submit the edited action so the rewrite is adjudicated and approved synchronously`);
+                }
+            }
+            const resumeHooks = taskConfig.hooks ?? this.deps.hooks;
+            if (resumeHooks?.preToolUse !== undefined && resumeHooks.preToolUseObservational === true) {
+                try {
+                    await raceEditAbort(Promise.resolve(resumeHooks.preToolUse(cp.pendingAction.toolName, cloneObserverInput(editedArgs), {
+                        toolCallId: cp.pendingAction.toolCallId,
+                        toolName: cp.pendingAction.toolName,
+                    })));
+                }
+                catch (err) {
+                    if (err instanceof CheckpointError)
+                        throw err;
+                    throw new CheckpointError("resume.constraint_rejected", `the declared-observational PreToolUse face threw while observing the approver's edited args (${err instanceof Error ? err.message : String(err)}) — ` +
+                        "refused fail-closed pre-CAS (the checkpoint stays pending and remains decidable)");
+                }
+            }
         }
         const outcomeForStore = plainPolicyOutcome ?? plainReviewOutcome ?? plainParkOutcome;
         if (outcomeForStore === undefined) {
@@ -3778,7 +3910,7 @@ export class Runner {
                     ? new CheckpointError("checkpoint.reopen_failed", "the resume was aborted before the approved action could run AND the store refused to reopen the checkpoint — the approval is terminally consumed and the suspended work was not executed; a retry needs a fresh approval")
                     : new CheckpointError("checkpoint.reopen_failed", "the resume was aborted before the approved action could run and the reopen attempt FAILED IN FLIGHT — the checkpoint's state is unprovable from here: it may already be pending again. Re-read it before deciding; do NOT issue a fresh approval on the assumption the old one is dead (the approved action did NOT run either way)");
         }
-        return this.runTaskStream(spec, { cp, outcome: outcomeForStore, onEnvRestoreFailed, ...(wakeMessage !== undefined ? { wakeMessage } : {}) }, internals);
+        return this.runTaskStream(spec, { cp, outcome: outcomeForStore, onEnvRestoreFailed, ...(wakeMessage !== undefined ? { wakeMessage } : {}) }, resumeInternals);
     }
     async applyResumeDecision(prepared, resume, emit, emitCommitted, onResolvedToolSuccess, onExecuteStart) {
         const { pendingAction } = resume.cp;
@@ -3853,15 +3985,23 @@ export class Runner {
         if (outcome.decision !== "allow") {
             throw new CheckpointError("checkpoint.invalid_outcome", `pending action reached the resolver with decision "${String(outcome.decision)}" — only "allow" executes and only "deny" injects a denial; refusing to execute`);
         }
+        const beltBudget = {
+            resourceRemainingMicroUsd: remainingBudgetMicroUsd(prepared.resourceLedger),
+            resourceSpentMicroUsd: prepared.resourceLedger?.spentMicroUsd ?? 0,
+            suspendCount: resume.cp.suspendCount ?? 0,
+        };
         if (outcome.decision === "allow" && outcome.updatedInput !== undefined && prepared.basePolicyForResumeEdit) {
             const rechecked = refuseOutOfContractDecision(await prepared.basePolicyForResumeEdit.check({
                 toolName: pendingAction.toolName,
                 args: resolvedArgs,
                 toolCallId: pendingAction.toolCallId,
+                budget: beltBudget,
                 ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
             }, prepared.abortController.signal));
-            if (rechecked.action === "deny") {
-                const editedDenial = formatHookFeedback(`The approver EDITED this call's input; the edited call is denied by the deployment's tool policy and was not executed${rechecked.message ? `: ${rechecked.message}` : ""}.`);
+            const beltUnsafe = rechecked.action === "deny" ||
+                (rechecked.updatedInput !== undefined && !deepJsonEqual(rechecked.updatedInput, resolvedArgs));
+            if (beltUnsafe) {
+                const editedDenial = formatHookFeedback(`The approver EDITED this call's input; the edited call is refused by the deployment's tool policy and was not executed${rechecked.action === "deny" && rechecked.message ? `: ${rechecked.message}` : " (the policy rewrote the edit to a value that was not approved)"}.`);
                 emitEnd(true, { content: editedDenial });
                 const eid = await prepared.session.appendMessage(toolResultMsg(pendingAction.toolCallId, pendingAction.toolName, editedDenial, true));
                 emitCommitted(eid, "toolResult", pendingAction.toolCallId);
@@ -3873,6 +4013,7 @@ export class Runner {
                 toolName: pendingAction.toolName,
                 args: resolvedArgs,
                 toolCallId: pendingAction.toolCallId,
+                budget: beltBudget,
                 ...(prepared.cwdRef !== undefined ? { cwd: prepared.cwdRef.current } : {}),
             }, prepared.abortController.signal));
             if (narrowed.action === "deny") {

package/dist/core/shared-memory/contract.js

@@ -31,6 +31,21 @@ async function connectedStores(provider) {
     }
     return [...snapshot.stores];
 }
+async function walkList(reader, prefix) {
+    const out = [];
+    let cursor;
+    for (let round = 0; round < 64; round++) {
+        const rows = await reader.list(prefix, { ...(cursor !== undefined ? { cursor } : {}), limit: 50 });
+        if (Array.isArray(rows))
+            return [...out, ...rows];
+        out.push(...rows.entries);
+        if (rows.nextCursor === undefined)
+            return out;
+        assert.ok(cursor === undefined || rows.nextCursor > cursor, `paged list nextCursor must strictly advance (got ${JSON.stringify(rows.nextCursor)} after ${JSON.stringify(cursor)})`);
+        cursor = rows.nextCursor;
+    }
+    return assert.fail("paged list did not terminate within 64 windows — nextCursor must eventually be absent");
+}
 function storeById(stores, id) {
     const found = stores.find((s) => s.info.id === id);
     if (!found)
@@ -93,7 +108,7 @@ export async function sharedMemoryStoreContract(hooks) {
         const stores = await connectedStores(await hooks.make(fixture));
         const alpha = storeById(stores, "alpha");
         const normalizedPrefix = "/a";
-        const rows = await alpha.reader.list(listPrefixArgument(normalizedPrefix), {});
+        const rows = await walkList(alpha.reader, listPrefixArgument(normalizedPrefix));
         const listed = new Set(rows.map((r) => r.path));
         const expected = fixture.stores[0].documents.filter((d) => matchesPathPrefix(d.path, normalizedPrefix));
         assert.ok(expected.length > 0, "the fixture must actually place documents under the probed prefix");
@@ -105,7 +120,7 @@ export async function sharedMemoryStoreContract(hooks) {
         const fixture = twoStoreFixture();
         const stores = await connectedStores(await hooks.make(fixture));
         const alpha = storeById(stores, "alpha");
-        const listed = new Set((await alpha.reader.list(undefined, {})).map((r) => r.path));
+        const listed = new Set((await walkList(alpha.reader, undefined)).map((r) => r.path));
         for (const doc of fixture.stores[0].documents) {
             assert.ok(listed.has(doc.path), `list(undefined) omitted "${doc.path}"`);
         }
@@ -122,10 +137,10 @@ export async function sharedMemoryStoreContract(hooks) {
         const stores = await connectedStores(await hooks.make(twoStoreFixture()));
         const alpha = storeById(stores, "alpha");
         const beta = storeById(stores, "beta");
-        const alphaPaths = new Set((await alpha.reader.list(undefined, {})).map((r) => r.path));
+        const alphaPaths = new Set((await walkList(alpha.reader, undefined)).map((r) => r.path));
         assert.ok(!alphaPaths.has("/b/only.md"), "store alpha listed a document that belongs to store beta");
         assert.strictEqual(await alpha.reader.read("/b/only.md", {}), null, "store alpha read a document that belongs to store beta");
-        const betaPaths = new Set((await beta.reader.list(undefined, {})).map((r) => r.path));
+        const betaPaths = new Set((await walkList(beta.reader, undefined)).map((r) => r.path));
         assert.ok(!betaPaths.has("/a/one.md"), "store beta listed a document that belongs to store alpha");
         assert.strictEqual(await beta.reader.read("/a/one.md", {}), null, "store beta read a document that belongs to store alpha");
     });

package/dist/core/shared-memory/normalize.d.ts

@@ -102,7 +102,9 @@ export interface NormalizedStore {
     info: SharedMemoryStoreInfo;
     list: (prefix: string | undefined, opts: {
         signal?: AbortSignal;
-    }) => Promise<SharedMemoryDocumentEntry[]>;
+        cursor?: string;
+        limit?: number;
+    }) => Promise<SharedMemoryDocumentEntry[] | import("./types.js").SharedMemoryPagedList>;
     read: (path: string, opts: {
         signal?: AbortSignal;
     }) => Promise<{

package/dist/core/shared-memory/tools.js

@@ -1,7 +1,7 @@
 import { Type } from "typebox";
 import { errorResult } from "../tools.js";
 import { CONNECTING_MESSAGE, GENERIC_FAILURE_MESSAGE, NO_STORES_MESSAGE, SHARED_STORE_FRAME, UNAVAILABLE_MESSAGE, datePrefixOf, echoUntrusted, foldReaderError, listPrefixArgument, normalizeEntries, normalizeMemoryPath, normalizeReadValue, normalizeSnapshot, pageDocuments, relativePathRefusal, sanitizeSharedContent, validateDocumentPath, validatePathPrefix, } from "./normalize.js";
-import { SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_READ_TOOL_NAME, } from "./types.js";
+import { SHARED_MEMORY_LIST_PAGE_SIZE, SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_CAP_BYTES, SHARED_MEMORY_READ_TOOL_NAME, } from "./types.js";
 const LIST_HINT = "List shared memory stores and their documents — check here before telling the user you do not have something.";
 const LIST_DESCRIPTION = [
     LIST_HINT,
@@ -58,12 +58,14 @@ function renderEntryLine(entry) {
     const path = JSON.stringify(entry.path);
     return meta === "" ? path : `${path}  (${meta})`;
 }
-function renderDocumentPage(page, remaining) {
+function renderDocumentPage(page, remaining, providerHasMore = false) {
     if (page.length === 0)
         return "(empty)";
     const footer = remaining > 0
         ? `\n… ${remaining} more — call again with cursor=${JSON.stringify(page.at(-1)?.path ?? "")} to continue.`
-        : "";
+        : providerHasMore
+            ? `\n… more — call again with cursor=${JSON.stringify(page.at(-1)?.path ?? "")} to continue.`
+            : "";
     return `${SHARED_STORE_FRAME}\n\n${page.map(renderEntryLine).join("\n")}${footer}`;
 }
 function renderDocument(content, updatedAt) {
@@ -173,31 +175,85 @@ export function createSharedMemoryTools(opts) {
                 if (refusal)
                     return refusedList(refusal, "refused", resolution.diagnostics, store);
             }
-            let raw;
-            try {
-                raw = await resolution.store.list(normalizedPrefix === undefined ? undefined : listPrefixArgument(normalizedPrefix), { signal });
-            }
-            catch (err) {
-                if (signal?.aborted === true)
-                    throw err;
-                return refusedList(foldReaderError(err), "failed", resolution.diagnostics, store);
+            const collected = [];
+            let droppedEntries = 0;
+            let providerHasMore = false;
+            let providerCursor;
+            let windowCursor = cursor;
+            const MAX_WINDOW_ROUNDS = 8;
+            for (let round = 0;; round++) {
+                let raw;
+                try {
+                    raw = await resolution.store.list(normalizedPrefix === undefined ? undefined : listPrefixArgument(normalizedPrefix), {
+                        signal,
+                        ...(windowCursor !== undefined ? { cursor: windowCursor } : {}),
+                        limit: SHARED_MEMORY_LIST_PAGE_SIZE + 1,
+                    });
+                }
+                catch (err) {
+                    if (signal?.aborted === true)
+                        throw err;
+                    return refusedList(foldReaderError(err), "failed", resolution.diagnostics, store);
+                }
+                let windowEntries = raw;
+                let nextCursor;
+                let isPaged = false;
+                try {
+                    if (raw !== null && typeof raw === "object" && !Array.isArray(raw) && Array.isArray(raw.entries)) {
+                        isPaged = true;
+                        windowEntries = raw.entries;
+                        const nc = raw.nextCursor;
+                        nextCursor = typeof nc === "string" ? nc : undefined;
+                    }
+                }
+                catch (err) {
+                    if (signal?.aborted === true)
+                        throw err;
+                    return refusedList(FAILED_ERROR, "failed", resolution.diagnostics, store);
+                }
+                const normalized = normalizeEntries(windowEntries);
+                if (normalized.kind === "malformed")
+                    return refusedList(FAILED_ERROR, "failed", resolution.diagnostics, store);
+                collected.push(...normalized.entries);
+                droppedEntries += normalized.droppedEntries;
+                const progressed = isPaged && nextCursor !== undefined && (windowCursor === undefined || nextCursor > windowCursor);
+                if (!progressed) {
+                    providerHasMore = false;
+                    break;
+                }
+                providerCursor = nextCursor;
+                providerHasMore = true;
+                const candidates = pageDocuments(collected, {
+                    ...(normalizedPrefix !== undefined ? { normalizedPrefix } : {}),
+                    ...(cursor !== undefined ? { cursor } : {}),
+                });
+                if (candidates.page.length >= SHARED_MEMORY_LIST_PAGE_SIZE || candidates.remaining > 0)
+                    break;
+                if (round + 1 >= MAX_WINDOW_ROUNDS)
+                    break;
+                windowCursor = nextCursor;
             }
-            const normalized = normalizeEntries(raw);
-            if (normalized.kind === "malformed")
-                return refusedList(FAILED_ERROR, "failed", resolution.diagnostics, store);
-            const { page, remaining } = pageDocuments(normalized.entries, {
+            const { page, remaining } = pageDocuments(collected, {
                 ...(normalizedPrefix !== undefined ? { normalizedPrefix } : {}),
                 ...(cursor !== undefined ? { cursor } : {}),
             });
+            const hasMoreBeyondWindow = providerHasMore;
             const details = {
-                ...diagnosticsOf(resolution.diagnostics.droppedStores ?? 0, normalized.droppedEntries),
+                ...diagnosticsOf(resolution.diagnostics.droppedStores ?? 0, droppedEntries),
                 outcome: "ok",
                 mode: "documents",
                 store,
                 entries: page,
                 remaining,
+                ...(hasMoreBeyondWindow ? { providerHasMore: true } : {}),
             };
-            return { content: renderDocumentPage(page, remaining), details };
+            if (page.length === 0 && hasMoreBeyondWindow && providerCursor !== undefined) {
+                return {
+                    content: `${SHARED_STORE_FRAME}\n\n(no matching documents in this range)\n… more — call again with cursor=${JSON.stringify(providerCursor)} to continue.`,
+                    details,
+                };
+            }
+            return { content: renderDocumentPage(page, remaining, hasMoreBeyondWindow), details };
         },
     };
     const readTool = {

package/dist/core/shared-memory/types.d.ts

@@ -69,15 +69,38 @@ export interface SharedMemoryDocumentEntry {
     /** ISO 8601. Rendering uses only a matching 10-character `YYYY-MM-DD` prefix; no match ⇒ treated as absent. */
     updatedAt?: string;
 }
+/**
+ * #77 / design/180 实施窗 — the PROVIDER-SIDE pagination window. A reader that pages returns this
+ * instead of the bare array: `entries` is the window it chose to serve; `nextCursor` present ⇔ the
+ * store holds MORE documents past the window. The cursor vocabulary is exactly the tool face's —
+ * an EXCLUSIVE lower bound over document paths in plain UTF-16 code-unit order — so the same value
+ * flows model → core → provider unchanged. `nextCursor` is consumed as a HAS-MORE declaration only
+ * (the continue cursor the model receives is always the last path of the rendered page), so a
+ * stale or fabricated value can cost at most one empty page, never an error and never a skip.
+ */
+export interface SharedMemoryPagedList {
+    entries: SharedMemoryDocumentEntry[];
+    nextCursor?: string;
+}
 /** The read face of ONE store. Both methods must honor `signal`. */
 export interface SharedMemoryStoreReader {
     /**
      * List the documents under `prefix` (`undefined` = the whole store). core sorts, re-filters and pages —
      * an implementation may pre-filter by prefix but is only required to return a superset.
+     *
+     * #77 pagination pushdown (additive, both sides optional): core passes `cursor` (the exclusive
+     * lower-bound path of the previous page — same ordering contract as `pageDocuments`) and `limit`
+     * (a window-size hint, one over the render page) on every call. A provider may IGNORE both and
+     * return the full superset array — the v1 shape, byte-compatible — or honor them and return a
+     * {@link SharedMemoryPagedList} window, which is what lets a large library serve bounded
+     * containers instead of materializing the whole set per call (the container itself has no core
+     * cap; the unpaged form remains provider self-discipline, stated rather than silently truncated).
      */
     list(prefix: string | undefined, opts: {
         signal?: AbortSignal;
-    }): Promise<SharedMemoryDocumentEntry[]>;
+        cursor?: string;
+        limit?: number;
+    }): Promise<SharedMemoryDocumentEntry[] | SharedMemoryPagedList>;
     /** Read one document. `null` = it does not exist (absence is a VALUE here, never an exception). */
     read(path: string, opts: {
         signal?: AbortSignal;
@@ -171,6 +194,9 @@ export type MemoryListDetails = SharedMemoryDiagnostics & ({
     store: string;
     entries: SharedMemoryDocumentEntry[];
     remaining: number;
+    /** #77 — the provider declared more documents past its served window (`remaining` counts only
+     *  the window's local tail, so 0 here does not mean the listing is complete). */
+    providerHasMore?: true;
 } | {
     outcome: "refused" | "failed";
     reason: string;

package/dist/core/store-contracts/permission-rule-sync-contract.d.ts

@@ -0,0 +1,33 @@
+/**
+ * design/182 §11 — the permission-rule sync JOIN contract: the cross-repo acceptance suite the
+ * server-side twin runs against its own merge implementation (design/182 §13 obligation ②: consume
+ * core's `joinRuleStates`, or pass THIS suite against your reimplementation — semantic identity is the
+ * contract, not code sharing).
+ *
+ * KIT form (design/159 S1): vitest-free (`node:assert`), runner seam via {@link ContractAssertionRunner},
+ * version lockstep via `CONTRACT_KIT_ENGINE_VERSION`. There is NO skip hook — every case is mandatory,
+ * so a passing run never means "most of it passed". Fixtures are built inline: the join is a pure
+ * function, so there is nothing to seed and no instance lifecycle.
+ *
+ * What is asserted: the semilattice laws (idempotent/commutative/associative — the convergence proof
+ * itself, not prose), the design's convergence-matrix grids (M1-M13), the tombstone-union rule, the
+ * metadata re-projection refusal, the state vector and the paired frontier collection. Content
+ * assertions are set-based, never order-based: a twin with a different canonical output order passes,
+ * a twin that loses or invents a dot does not.
+ */
+import type { RuleSyncFrontier, RuleSyncState } from "../permission-rule-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export interface PermissionRuleSyncContractHooks {
+    /** The merge under test. Default: core's own `joinRuleStates` (self-verification). */
+    join?: (a: RuleSyncState, b: RuleSyncState) => RuleSyncState;
+    /** The paired-collection arm under test. Default: core's `collectBelowFrontier`. */
+    collect?: (state: RuleSyncState, frontier: RuleSyncFrontier) => {
+        state: RuleSyncState;
+        collectedTombstones: number;
+    };
+    /** The state vector under test. Default: core's `ruleSyncVector`. */
+    vector?: (state: RuleSyncState) => RuleSyncFrontier;
+    runAssertion?: ContractAssertionRunner;
+}
+/** Run the full conformance suite. Throws (assert) on the first violated clause. */
+export declare function permissionRuleSyncContract(hooks?: PermissionRuleSyncContractHooks): Promise<void>;