@code-yeongyu/senpi 2026.11.10 → 2026.11.11

package/dist/core/extensions/types.d.ts

@@ -866,6 +866,8 @@ export interface ToolPermissionRequest {
     readonly patterns: readonly string[];
     /** Patterns an "always" approval of this call records. */
     readonly always: readonly string[];
+    /** An `ask` decision for this call is approved without a prompt; an `allow` or `deny` rule still decides first. */
+    readonly autoApproveAsk?: true;
 }
 /**
  * Hints about what a tool does, with the meaning of MCP tool annotations. They come from the tool's
@@ -1471,6 +1473,18 @@ export interface HandlerRegistrationOptions {
      */
     runs?: ExtensionSide;
 }
+/**
+ * Registration options for the provider request and stream hooks (`before_provider_request`, `provider_stream_event`,
+ * `after_provider_response`).
+ */
+export interface ProviderHookOptions extends HandlerRegistrationOptions {
+    /**
+     * The providers whose requests or streams this handler reads or changes; omitted, every provider. A hand advertises
+     * these to a hosted brain so it knows which calls need the device's hooks (hosted model-key custody CK21). The
+     * declaration never filters dispatch: the handler still receives every event wherever it runs.
+     */
+    providers?: readonly ProviderId[];
+}
 /** Registration options for `pi.on("before_agent_start", handler, options)`. */
 export interface BeforeAgentStartHandlerOptions extends HandlerRegistrationOptions {
     /**
@@ -2155,10 +2169,10 @@ export interface ExtensionAPI {
     on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>, options?: HandlerRegistrationOptions): () => void;
     on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>, options?: ContextHandlerOptions): () => void;
     on(event: "context_with_system", handler: ExtensionHandler<ContextWithSystemEvent, ContextEventResult>, options?: ContextHandlerOptions): () => void;
-    on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>, options?: HandlerRegistrationOptions): () => void;
+    on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>, options?: ProviderHookOptions): () => void;
     on(event: "before_provider_headers", handler: ExtensionHandler<BeforeProviderHeadersEvent>, options?: HandlerRegistrationOptions): () => void;
-    on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>, options?: HandlerRegistrationOptions): () => void;
-    on(event: "provider_stream_event", handler: ExtensionHandler<ProviderStreamEvent>, options?: HandlerRegistrationOptions): () => void;
+    on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>, options?: ProviderHookOptions): () => void;
+    on(event: "provider_stream_event", handler: ExtensionHandler<ProviderStreamEvent>, options?: ProviderHookOptions): () => void;
     on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>, options?: BeforeAgentStartHandlerOptions): () => void;
     on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>, options?: HandlerRegistrationOptions): () => void;
     on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>, options?: HandlerRegistrationOptions): () => void;
@@ -3055,6 +3069,8 @@ export interface Extension {
     nonMutatingContextHandlers?: WeakSet<HandlerFn>;
     /** The declared side of each handler registered with `{ runs }`; a handler that declared none has no entry. */
     handlerSides?: WeakMap<HandlerFn, ExtensionSide>;
+    /** The declared providers of each provider hook registered with `{ providers }`; undeclared hooks have no entry. */
+    handlerProviders?: WeakMap<HandlerFn, readonly ProviderId[]>;
     tools: Map<string, RegisteredTool>;
     /** Optional for compatibility with extension records created before child modules. */
     childModules?: Map<string, RegisteredChildModule>;

package/dist/core/hand/hook-advertise.d.ts

@@ -0,0 +1,41 @@
+import type { ProviderId } from "@earendil-works/pi-ai";
+import type { HandSessionAdvertisement, HookModelRequest, HookModelRequestReply } from "../egress/wire.ts";
+import type { Extension } from "../extensions/types.ts";
+export type HookProviders = readonly ProviderId[] | "*";
+export interface HandHookAccess {
+    readonly requestHooks: HookProviders;
+    readonly streamHooks: HookProviders;
+}
+/** The request and stream hooks of the extensions `only` accepts (the ones that run on this hand). */
+export declare function handHookAccess(extensions: readonly Extension[], only: (extensionPath: string) => boolean): HandHookAccess;
+export interface AdvertHashParts {
+    readonly extensionSetHash: string;
+    readonly cwd: string;
+    /** The project-local hook set, as hook identities; its order does not matter. */
+    readonly projectHooks: readonly string[];
+}
+/** `H(extension set hash, cwd, project-local hook set)` (4.9): `sha256:` + hex SHA-256 of their canonical JSON. */
+export declare function computeAdvertHash(parts: AdvertHashParts): string;
+/** A bound session's advertisement, before a connection stamps it. */
+export type HandHookSession = Omit<HandSessionAdvertisement, "t" | "connectionId">;
+/** A hook request for a session not advertised on the connection it names; nothing ran. */
+export declare class HookNotAdvertisedError extends Error {
+    readonly name = "HookNotAdvertisedError";
+}
+export interface HandHookLinkOptions {
+    send(message: HandSessionAdvertisement | HookModelRequestReply): Promise<void>;
+    serve(request: HookModelRequest): Promise<HookModelRequestReply>;
+}
+export interface HandHookLink {
+    /** A new connection: every bound session's advertisement goes out first, in order, under `connectionId`. */
+    connect(connectionId: string, sessions: readonly HandHookSession[]): Promise<void>;
+    /** A session bound (or re-hashed) mid-connection: its advertisement goes out before anything else for it. */
+    advertise(session: HandHookSession): Promise<void>;
+    /**
+     * One `hook.model_request` received on `connectionId`; its reply follows that session's advertisement. Its hooks run
+     * outside the outgoing order, so a slow hook holds back no other request's reply and no advertisement.
+     */
+    receive(connectionId: string, request: HookModelRequest): Promise<void>;
+}
+export declare function createHandHookLink(options: HandHookLinkOptions): HandHookLink;
+//# sourceMappingURL=hook-advertise.d.ts.map

package/dist/core/hand/hook-advertise.js

@@ -0,0 +1,98 @@
+/**
+ * The hand's hook advertisement of hosted model-key custody (row CK21; custody design 4.9, round-10 fold section 15).
+ *
+ * A hand tells a hosted brain, per bound session, which providers' calls need the device's hooks: the request hooks
+ * (`before_provider_request`) and the stream hooks (`provider_stream_event`, `after_provider_response`) of the user's
+ * extensions, each scoped by its `{ providers }` declaration or, undeclared, every provider (`"*"`). The advertisement
+ * carries the `connectionId`, the session's `cwd` and its `advertHash`, and it is the first message for its session on
+ * every (re)connect: the link serves no `hook.model_request` that its session's advertisement on that connection did
+ * not precede.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "@earendil-works/pi-agent-core";
+const REQUEST_HOOK_EVENTS = ["before_provider_request"];
+const STREAM_HOOK_EVENTS = ["provider_stream_event", "after_provider_response"];
+function hookProviders(extensions, events, only) {
+    const declared = new Set();
+    for (const extension of extensions) {
+        if (!only(extension.path))
+            continue;
+        for (const event of events)
+            for (const handler of extension.handlers.get(event) ?? []) {
+                const providers = extension.handlerProviders?.get(handler);
+                if (providers === undefined)
+                    return "*";
+                for (const provider of providers)
+                    declared.add(provider);
+            }
+    }
+    return [...declared].sort();
+}
+/** The request and stream hooks of the extensions `only` accepts (the ones that run on this hand). */
+export function handHookAccess(extensions, only) {
+    return {
+        requestHooks: hookProviders(extensions, REQUEST_HOOK_EVENTS, only),
+        streamHooks: hookProviders(extensions, STREAM_HOOK_EVENTS, only),
+    };
+}
+/** `H(extension set hash, cwd, project-local hook set)` (4.9): `sha256:` + hex SHA-256 of their canonical JSON. */
+export function computeAdvertHash(parts) {
+    const canonical = canonicalJson({
+        cwd: parts.cwd,
+        extensionSetHash: parts.extensionSetHash,
+        projectHooks: [...parts.projectHooks].sort(),
+    });
+    return `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+}
+/** A hook request for a session not advertised on the connection it names; nothing ran. */
+export class HookNotAdvertisedError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "HookNotAdvertisedError";
+    }
+}
+export function createHandHookLink(options) {
+    let connectionId;
+    let advertised = new Set();
+    // One outgoing order: an advertisement queued before a reply is sent before it.
+    let outgoing = Promise.resolve();
+    const enqueue = (work) => {
+        const run = outgoing.then(work);
+        outgoing = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const sendAdvert = (connection, session, into) => enqueue(async () => {
+        if (connectionId !== connection)
+            return;
+        await options.send({ t: "hand.session.advertise", connectionId: connection, ...session });
+        into.add(session.sessionId);
+    });
+    return {
+        async connect(next, sessions) {
+            connectionId = next;
+            const fresh = new Set();
+            advertised = fresh;
+            await Promise.all(sessions.map((session) => sendAdvert(next, session, fresh)));
+        },
+        async advertise(session) {
+            if (connectionId === undefined)
+                throw new HookNotAdvertisedError("no connection to advertise on");
+            await sendAdvert(connectionId, session, advertised);
+        },
+        async receive(connection, request) {
+            // Only the advertised check and the reply's send take a place in the outgoing order.
+            await enqueue(async () => {
+                if (connection !== connectionId || !advertised.has(request.sessionId))
+                    throw new HookNotAdvertisedError(`hook.model_request for session ${JSON.stringify(request.sessionId)} was not preceded by its advertisement on connection ${JSON.stringify(connection)}`);
+            });
+            const reply = await options.serve(request);
+            await enqueue(async () => {
+                // A reconnect since the request arrived: its connection is gone, so its reply is not sent.
+                if (connection !== connectionId)
+                    return;
+                await options.send(reply);
+            });
+        },
+    };
+}
+//# sourceMappingURL=hook-advertise.js.map

package/dist/core/hand/hook-contract.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The request-hook contract of hosted model-key custody (row CK21; custody design 4.9, round-10 fold section 15).
+ *
+ * `HookRequestInput` is the serializable projection of the fused `before_provider_request` input: the provider payload
+ * and the effective request model, without the request headers or the model's own headers, which can carry a
+ * credential and never leave the side that dials. A step call has this input; an aux call has none. A hand serves
+ * `hook.model_request` by running its user's request hooks on the input, only after the request's placement claim
+ * verified, and replies with the payload they produced, with their failures and the messages and notices they sent.
+ */
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExecutionScope } from "@earendil-works/pi-agent-core";
+import { type ClaimVerdict } from "../egress/placement-claim.ts";
+import type { HookModelRequest, HookModelRequestReply, ProviderCallErrorCode, ProviderCallKind, WireJson } from "../egress/wire.ts";
+import type { BeforeProviderRequestEvent } from "../extensions/types.ts";
+/** The pinned shape of `HookModelRequestInput` (and of the reply's `output`). */
+export type HookRequestInput = {
+    readonly payload: WireJson;
+    readonly model?: {
+        readonly [key: string]: WireJson;
+    };
+};
+/** The input or output cannot cross the wire: it is not JSON, or not the closed envelope. */
+export declare class HookContractError extends Error {
+    readonly name = "HookContractError";
+}
+/** The request's placement claim did not verify, so no hook ran; `code`/`retryable` are the claim's wire answer. */
+export declare class HookRequestRefusedError extends Error {
+    readonly name = "HookRequestRefusedError";
+    readonly verdict: Exclude<ClaimVerdict, "valid">;
+    readonly code: ProviderCallErrorCode;
+    readonly retryable: boolean;
+    constructor(verdict: Exclude<ClaimVerdict, "valid">);
+}
+/** The projection of a fused `before_provider_request` input. */
+export declare function hookRequestInputOf(event: Omit<BeforeProviderRequestEvent, "type"> & {
+    type?: string;
+}): HookRequestInput;
+/** A step call's hook input; an aux call runs no request hooks on the hand and has none. */
+export declare function hookRequestInputForCall(call: ProviderCallKind, event: Omit<BeforeProviderRequestEvent, "type"> & {
+    type?: string;
+}): HookRequestInput | undefined;
+/** The reply's `output`: the payload the hooks produced, with the model the request carried. */
+export declare function hookRequestOutputOf(input: HookRequestInput, payload: unknown): HookRequestInput;
+/** Reads a wire value back as the closed envelope `{ payload, model? }`; the model never carries headers. */
+export declare function parseHookRequestInput(value: unknown): HookRequestInput;
+/** The effective model a hand hands its hooks, as the loop sent it. */
+export declare function hookModelOf(input: HookRequestInput): Model<Api> | undefined;
+/** What the user's request hooks produced: the reply's `output`, their failures and what they sent. */
+export type HookRequestHooksResult = Omit<HookModelRequestReply, "t" | "sessionId" | "stepId" | "output"> & {
+    readonly output: HookRequestInput;
+};
+export interface HookServePorts {
+    /** The hand's placement-claim check (CK7's verifier with the hand's trust and clock). */
+    verifyClaim(claim: unknown): Promise<ClaimVerdict>;
+    /** Runs the user's request hooks of `sessionId` on `input` and returns what they produced. */
+    runRequestHooks(sessionId: string, input: HookRequestInput): Promise<HookRequestHooksResult>;
+}
+/** Serves one `hook.model_request`: claim first, then the closed input, then the hooks. */
+export declare function serveHookModelRequest(request: HookModelRequest, ports: HookServePorts): Promise<HookModelRequestReply>;
+/**
+ * `runRequestHooks` over a hand's loop-hook runner (`LooplessHand.loopHooks`): the session's hooks run on the runtime of
+ * `scope`, inside a loop-hook call bound to that session, with the loop busy (a model request is mid-turn). The hooks'
+ * failures and what they sent travel with the output, as they do on every loop-hook reply.
+ */
+export declare function loopHookRequestHooks(loopHooks: (event: string, payload: WireJson) => Promise<unknown>, scope: ExecutionScope): HookServePorts["runRequestHooks"];
+//# sourceMappingURL=hook-contract.d.ts.map

package/dist/core/hand/hook-contract.js

@@ -0,0 +1,138 @@
+import { CLAIM_VERDICT_ERRORS } from "../egress/placement-claim.js";
+/** The input or output cannot cross the wire: it is not JSON, or not the closed envelope. */
+export class HookContractError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "HookContractError";
+    }
+}
+/** The request's placement claim did not verify, so no hook ran; `code`/`retryable` are the claim's wire answer. */
+export class HookRequestRefusedError extends Error {
+    constructor(verdict) {
+        super(`hook.model_request refused: placement claim ${verdict}`);
+        this.name = "HookRequestRefusedError";
+        this.verdict = verdict;
+        this.code = CLAIM_VERDICT_ERRORS[verdict].code;
+        this.retryable = CLAIM_VERDICT_ERRORS[verdict].retryable;
+    }
+}
+const isPlainObject = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+/** `value` as JSON, exactly; anything JSON would drop, coerce or reject is refused (an `undefined` member is absent). */
+function wireJson(value, at) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (Number.isFinite(value))
+            return value;
+        throw new HookContractError(`${at} is not a finite number`);
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => wireJson(item, `${at}[${index}]`));
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, member] of Object.entries(value))
+            if (member !== undefined)
+                out[key] = wireJson(member, `${at}.${key}`);
+        return out;
+    }
+    throw new HookContractError(`${at} is not JSON`);
+}
+function wireModel(model) {
+    const { headers: _headers, ...rest } = model;
+    return wireJson(rest, "model");
+}
+/** The projection of a fused `before_provider_request` input. */
+export function hookRequestInputOf(event) {
+    const payload = wireJson(event.payload, "payload");
+    return event.model === undefined ? { payload } : { payload, model: wireModel(event.model) };
+}
+/** A step call's hook input; an aux call runs no request hooks on the hand and has none. */
+export function hookRequestInputForCall(call, event) {
+    return call.kind === "step" ? hookRequestInputOf(event) : undefined;
+}
+/** The reply's `output`: the payload the hooks produced, with the model the request carried. */
+export function hookRequestOutputOf(input, payload) {
+    const out = wireJson(payload, "payload");
+    return input.model === undefined ? { payload: out } : { payload: out, model: input.model };
+}
+const MODEL_STRING_FIELDS = ["id", "name", "api", "provider", "baseUrl"];
+/** Reads a wire value back as the closed envelope `{ payload, model? }`; the model never carries headers. */
+export function parseHookRequestInput(value) {
+    if (!isPlainObject(value) || !("payload" in value))
+        throw new HookContractError("hook input is not an object with a payload");
+    const extra = Object.keys(value).filter((key) => key !== "payload" && key !== "model");
+    if (extra.length > 0)
+        throw new HookContractError(`hook input has unknown members: ${extra.join(", ")}`);
+    const payload = wireJson(value.payload, "payload");
+    if (value.model === undefined)
+        return { payload };
+    const model = value.model;
+    if (!isPlainObject(model) || MODEL_STRING_FIELDS.some((field) => typeof model[field] !== "string"))
+        throw new HookContractError("hook input model is not a model");
+    if ("headers" in model)
+        throw new HookContractError("hook input model carries headers");
+    return { payload, model: wireJson(model, "model") };
+}
+/** The effective model a hand hands its hooks, as the loop sent it. */
+export function hookModelOf(input) {
+    return input.model;
+}
+/** Serves one `hook.model_request`: claim first, then the closed input, then the hooks. */
+export async function serveHookModelRequest(request, ports) {
+    const verdict = await ports.verifyClaim(request.claim);
+    if (verdict !== "valid")
+        throw new HookRequestRefusedError(verdict);
+    const input = parseHookRequestInput(request.input);
+    const produced = await ports.runRequestHooks(request.sessionId, input);
+    return { t: "hook.model_request.reply", sessionId: request.sessionId, stepId: request.stepId, ...produced };
+}
+const isHookFailure = (value) => isPlainObject(value) &&
+    typeof value.extensionPath === "string" &&
+    typeof value.event === "string" &&
+    typeof value.error === "string";
+function hookFailures(value) {
+    if (!Array.isArray(value) || !value.every(isHookFailure))
+        throw new HookContractError("the hand's request-hook reply has malformed errors");
+    return value.map(({ extensionPath, event, error }) => ({ extensionPath, event, error }));
+}
+function wireList(value, at) {
+    if (!Array.isArray(value))
+        throw new HookContractError(`the hand's request-hook reply has malformed ${at}`);
+    return value.map((item, index) => wireJson(item, `${at}[${index}]`));
+}
+function droppedCount(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+        return value;
+    throw new HookContractError("the hand's request-hook reply has a malformed droppedLate");
+}
+/**
+ * `runRequestHooks` over a hand's loop-hook runner (`LooplessHand.loopHooks`): the session's hooks run on the runtime of
+ * `scope`, inside a loop-hook call bound to that session, with the loop busy (a model request is mid-turn). The hooks'
+ * failures and what they sent travel with the output, as they do on every loop-hook reply.
+ */
+export function loopHookRequestHooks(loopHooks, scope) {
+    return async (sessionId, input) => {
+        const reply = await loopHooks("before_provider_request", {
+            scope: { id: scope.id, root: scope.root },
+            sessionId,
+            idle: false,
+            input,
+        });
+        if (!isPlainObject(reply))
+            throw new HookContractError("the hand's request-hook reply is not an object");
+        const { errors, sent, notices, droppedLate } = reply;
+        return {
+            output: parseHookRequestInput(reply.output),
+            ...(errors === undefined ? {} : { errors: hookFailures(errors) }),
+            ...(sent === undefined ? {} : { sent: wireList(sent, "sent") }),
+            ...(notices === undefined ? {} : { notices: wireList(notices, "notices") }),
+            ...(droppedLate === undefined ? {} : { droppedLate: droppedCount(droppedLate) }),
+        };
+    };
+}
+//# sourceMappingURL=hook-contract.js.map

package/dist/core/open-timing.d.ts

@@ -1,6 +1,8 @@
 export interface OpenTimer {
     mark(phase: string): void;
 }
+/** Speculative builds have no caller to charge; drop their timing rather than report a misleading open. */
+export declare function withoutOpenTiming<T>(build: () => T): T;
 export declare function openTimingEnabled(): boolean;
 export declare function startOpenTimer(scope: string): OpenTimer;
 //# sourceMappingURL=open-timing.d.ts.map

package/dist/core/open-timing.js

@@ -1,4 +1,5 @@
 import { envValue } from "./brand.js";
+import { AsyncLocalStorage } from "node:async_hooks";
 /**
  * Per-phase timing of a session open (senpi#5707), for naming the await that holds a slow open.
  * Enable with SENPI_OPEN_TIMING=1. Off, every call returns before reading a clock or touching
@@ -11,11 +12,16 @@ import { envValue } from "./brand.js";
  */
 const ENABLED = envValue("OPEN_TIMING") === "1";
 const DISABLED = { mark: () => { } };
+const speculative = new AsyncLocalStorage();
+/** Speculative builds have no caller to charge; drop their timing rather than report a misleading open. */
+export function withoutOpenTiming(build) {
+    return speculative.run(true, build);
+}
 export function openTimingEnabled() {
     return ENABLED;
 }
 export function startOpenTimer(scope) {
-    if (!ENABLED)
+    if (!ENABLED || speculative.getStore())
         return DISABLED;
     let last = performance.now();
     return {

package/dist/core/resource-loader.js

@@ -167,6 +167,21 @@ function getGlobalDefaultExtensionModulePath(extensionId) {
     }
     return canonicalizeGlobalDefaultExtensionModulePath(join(packageDir, sourceRoot, "core", "extensions", "builtin", extensionFile));
 }
+// A write-denied agent dir (a sandboxed review child, senpi#6287) is left as it is: a missing default
+// extension shim is not seeded, so that default does not load, and a stale shim keeps loading whatever it
+// points at. Startup survives either way; any other error is a real failure.
+function seedWritable(write) {
+    try {
+        write();
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "EROFS" || code === "EACCES" || code === "EPERM")
+            return false;
+        throw error;
+    }
+}
 function buildGlobalDefaultExtensionShim(modulePath) {
     return `${GENERATED_GLOBAL_EXTENSION_BANNER}export { default } from ${JSON.stringify(pathToFileURL(modulePath).href)};\n`;
 }
@@ -569,6 +584,8 @@ export class DefaultResourceLoader {
                     cwd: this.cwd,
                     agentDir: this.agentDir,
                     ...this.settingsManager.getSettings().contextFiles,
+                    // senpi#5567: user settings only; a project's settings never redirect the global file.
+                    globalPath: this.settingsManager.getGlobalContextFilePath(),
                 }),
         };
         const resolvedAgentsFiles = this.agentsFilesOverride ? this.agentsFilesOverride(agentsFiles) : agentsFiles;
@@ -595,7 +612,8 @@ export class DefaultResourceLoader {
             return;
         }
         const extensionsDir = join(this.agentDir, "extensions");
-        mkdirSync(extensionsDir, { recursive: true });
+        if (!seedWritable(() => mkdirSync(extensionsDir, { recursive: true })))
+            return;
         for (const extensionId of globalDefaultExtensionIds) {
             const modulePath = getGlobalDefaultExtensionModulePath(extensionId);
             const targetPath = getGlobalDefaultExtensionShimPath(this.agentDir, extensionId);
@@ -611,10 +629,10 @@ export class DefaultResourceLoader {
                 if (existing === shim || !isGeneratedGlobalDefaultExtensionShim(existing)) {
                     continue;
                 }
-                writeFileSync(targetPath, shim, "utf-8");
+                seedWritable(() => writeFileSync(targetPath, shim, "utf-8"));
                 continue;
             }
-            writeFileSync(targetPath, shim, "utf-8");
+            seedWritable(() => writeFileSync(targetPath, shim, "utf-8"));
         }
     }
     resolvePackagePaths(options = {}) {

package/dist/core/retry-fallback/controller-types.d.ts

@@ -16,6 +16,8 @@ export interface ActiveFallbackState {
     pinned: boolean;
     /** The original provider's login id when the episode began; a sign-in moves it and releases a billing pin (senpi#4099). */
     recoveryRevision?: string;
+    /** Wall-clock reset the usage limit behind a billing pin stated; the pin releases once it passes (senpi#4085). */
+    pinnedUntil?: number;
 }
 export type FallbackReason = "transient" | "refusal" | "hard-error" | "billing";
 /** Absent: the original recovered after its cooldown. `fallback-unusable`: the fallback itself could not serve. */

package/dist/core/retry-fallback/controller.js

@@ -4,7 +4,7 @@ import { firstUsableCandidate } from "./candidates.js";
 import { baseSelector, canonicalizeFallbackChains, formatSelector, parseFallbackSelector, resolveChainKey, rungSelector, } from "./chains.js";
 import { subscribeProviderAccountEvents } from "../extensions/builtin/anthropic-subscription/account-events.js";
 import { CircuitProbes } from "./circuit-probes.js";
-import { releaseOnCredentialChange } from "./credential-recovery.js";
+import { releaseOnCredentialChange, releaseOnLimitReset } from "./credential-recovery.js";
 import { pinAfterSwitch } from "./pin.js";
 import { isPureNetworkTransient } from "./transient-network.js";
 import { UnusableEntries } from "./unusable.js";
@@ -125,6 +125,7 @@ export class RetryFallbackController {
             return false;
         if (boundary === "turn")
             await releaseOnCredentialChange(state, model, this.deps, this.unusable);
+        releaseOnLimitReset(state, model, this.deps, this.unusable);
         if (state.pinned || !this.deps.isAuthAvailable(model.provider))
             return false;
         const stranded = this.unusable.isUnusable(current.model) && !this.unusable.isUnusable(model);
@@ -371,12 +372,18 @@ export class RetryFallbackController {
         const recoveryRevision = prior
             ? prior.recoveryRevision
             : await this.deps.recoveryRevision?.(current.model.provider);
+        const pin = pinAfterSwitch(prior, { from, fromProvider: current.model.provider, reason, limit });
+        // A new billing pin from a usage limit lasts until the reset the limit stated, when it named one (senpi#4085).
+        const pinnedUntil = pin.pinnedByBilling && prior?.pinnedByBilling !== true
+            ? (this.deps.cooldowns.statedResetAt(from) ?? this.unusable.accountResetAt(current.model.provider))
+            : prior?.pinnedUntil;
         this.state = {
             ...(recoveryRevision === undefined ? {} : { recoveryRevision }),
             chainKey: candidate.chainKey,
             originalThinkingLevel: prior?.originalThinkingLevel ?? current.thinkingLevel,
             lastAppliedThinkingLevel: thinking,
-            ...pinAfterSwitch(prior, { from, fromProvider: current.model.provider, reason, limit }),
+            ...pin,
+            ...(pinnedUntil === undefined ? {} : { pinnedUntil }),
         };
         const scope = limit === undefined ? {} : { limit };
         this.deps.logger.info("fallback_applied", { from, to, chainKey: candidate.chainKey, reason, ...scope });

package/dist/core/retry-fallback/cooldown.d.ts

@@ -6,6 +6,11 @@
  */
 export declare class SelectorCooldowns {
     private readonly expiresAtBySelector;
+    /**
+     * The same deadline on the wall clock. The monotonic clock stops while the machine sleeps, so a limit that
+     * reset during a sleep would stay held for its whole length again after waking (senpi#4085).
+     */
+    private readonly wallExpiresAtBySelector;
     /** Wall-clock end of a suppression whose length the provider stated (a reset or retry-after), not a default. */
     private readonly statedResetAtBySelector;
     private readonly now;
@@ -22,6 +27,8 @@ export declare class SelectorCooldowns {
     clear(baseSelector: string): void;
     /** Clears `baseSelector` and every rung of it (`baseSelector:<thinking level>`), never another model. */
     clearModel(baseSelector: string): void;
+    /** The wall clock the stated resets are read on. */
+    wallClock(): number;
     clearAll(): void;
     private durationFor;
     private statedDurationMs;

package/dist/core/retry-fallback/cooldown.js

@@ -12,6 +12,11 @@ import { isTransportFailureText } from "./transient-network.js";
 export class SelectorCooldowns {
     constructor(now, random = Math.random, wallNow = now) {
         this.expiresAtBySelector = new Map();
+        /**
+         * The same deadline on the wall clock. The monotonic clock stops while the machine sleeps, so a limit that
+         * reset during a sleep would stay held for its whole length again after waking (senpi#4085).
+         */
+        this.wallExpiresAtBySelector = new Map();
         /** Wall-clock end of a suppression whose length the provider stated (a reset or retry-after), not a default. */
         this.statedResetAtBySelector = new Map();
         this.now = now;
@@ -21,6 +26,7 @@ export class SelectorCooldowns {
     note(baseSelector, failure) {
         const { ms, stated } = this.durationFor(failure);
         this.expiresAtBySelector.set(baseSelector, this.now() + ms);
+        this.wallExpiresAtBySelector.set(baseSelector, this.wallNow() + ms);
         if (stated)
             this.statedResetAtBySelector.set(baseSelector, this.wallNow() + ms);
         else
@@ -30,7 +36,7 @@ export class SelectorCooldowns {
         const expiresAt = this.expiresAtBySelector.get(baseSelector);
         if (expiresAt === undefined)
             return false;
-        if (this.now() < expiresAt)
+        if (this.now() < expiresAt && this.wallNow() < (this.wallExpiresAtBySelector.get(baseSelector) ?? Infinity))
             return true;
         this.clear(baseSelector);
         return false;
@@ -41,6 +47,7 @@ export class SelectorCooldowns {
     }
     clear(baseSelector) {
         this.expiresAtBySelector.delete(baseSelector);
+        this.wallExpiresAtBySelector.delete(baseSelector);
         this.statedResetAtBySelector.delete(baseSelector);
     }
     /** Clears `baseSelector` and every rung of it (`baseSelector:<thinking level>`), never another model. */
@@ -52,8 +59,13 @@ export class SelectorCooldowns {
                 this.clear(key);
         }
     }
+    /** The wall clock the stated resets are read on. */
+    wallClock() {
+        return this.wallNow();
+    }
     clearAll() {
         this.expiresAtBySelector.clear();
+        this.wallExpiresAtBySelector.clear();
         this.statedResetAtBySelector.clear();
     }
     durationFor(failure) {

package/dist/core/retry-fallback/credential-recovery.d.ts

@@ -14,5 +14,12 @@ type RecoveryDeps = Pick<RetryFallbackControllerDeps, "recoveryRevision" | "cool
  * does not change the context that was refused (senpi#4099).
  */
 export declare function releaseOnCredentialChange(state: ActiveFallbackState, original: Model<Api>, deps: RecoveryDeps, unusable: UnusableEntries): Promise<void>;
+/**
+ * A billing pin a usage limit caused holds only until the reset that limit stated: the account serves again
+ * then, so the pin and the original's cooldown, unusable mark and circuit are released and the existing
+ * revert path tries it once, with no re-login (senpi#4085). A pin with no stated reset (an empty credit
+ * balance) still holds until a sign-in. A still-spent original falls back and pins again.
+ */
+export declare function releaseOnLimitReset(state: ActiveFallbackState, original: Model<Api>, deps: RecoveryDeps, unusable: UnusableEntries): void;
 export {};
 //# sourceMappingURL=credential-recovery.d.ts.map

package/dist/core/retry-fallback/credential-recovery.js

@@ -29,4 +29,28 @@ export async function releaseOnCredentialChange(state, original, deps, unusable)
         trigger: "sign-in",
     });
 }
+/**
+ * A billing pin a usage limit caused holds only until the reset that limit stated: the account serves again
+ * then, so the pin and the original's cooldown, unusable mark and circuit are released and the existing
+ * revert path tries it once, with no re-login (senpi#4085). A pin with no stated reset (an empty credit
+ * balance) still holds until a sign-in. A still-spent original falls back and pins again.
+ */
+export function releaseOnLimitReset(state, original, deps, unusable) {
+    if (!state.pinnedByBilling || state.pinnedUntil === undefined)
+        return;
+    if (deps.cooldowns.wallClock() < state.pinnedUntil)
+        return;
+    state.pinnedByBilling = false;
+    state.pinnedUntil = undefined;
+    state.pinned = state.pinnedByRefusal;
+    const selector = formatSelector(original);
+    deps.cooldowns.clearModel(selector);
+    unusable.clear(original);
+    deps.circuits?.close(selector);
+    deps.logger.info("credential_recovery_released", {
+        chainKey: state.chainKey,
+        originalSelector: state.originalSelector,
+        trigger: "limit-reset",
+    });
+}
 //# sourceMappingURL=credential-recovery.js.map