@zackbart/connecta 0.40.0 → 0.42.0

package/dist/routes/mcp.js

@@ -1,4 +1,5 @@
-import { routeNames } from "../agent-routes.js";
+import { startTimingTrace } from "../timing-trace.js";
+import { META_ROUTES, routeNames } from "../agent-routes.js";
 import { upwardStep } from "../upward.js";
 import { bindDiscoveryEndpoint } from "../discovery-health.js";
 import { authCall, authInvoke, authFlow, authMethod } from "../auth/native.js";
@@ -8,15 +9,15 @@ import { observeAgentAdmission } from "../agent-observation.js";
 import { bindActivityRequest } from "../activity-request.js";
 import { closeScope } from "../runtime/connector-scope.js";
 import { executeLimits } from "../config.js";
-import { oauthConnectUrl, oauthConnectLink, oauthConnectLinkProgress, closeOAuthConnectLinks, claimAuthRetry, oauthConnectUnavailable, } from "../oauth-handoff.js";
+import { oauthConnectUrl, oauthConnectLink, oauthConnectLinkStarted, claimAuthRetry, oauthConnectUnavailable, } from "../oauth-handoff.js";
 import { AuthElicitation } from "../auth-elicitation.js";
 import { classifyInboundRequest, createMcpHandler, isJSONRPCErrorResponse, isLegacyRequest, McpServer, WebStandardStreamableHTTPServerTransport, } from "@modelcontextprotocol/server";
 import { Duration, Effect, Exit, Option, Result, Scope } from "effect";
 import { registerExecuteTool } from "../execute.js";
 import { ExecutorAdmissionError } from "../executor-admission.js";
 import { registerMetaTools } from "../meta-tools.js";
-import { endpointInstructions } from "../skills.js";
-import { NATIVE_TOOLS_LIST_TTL_MS, NativeSurface, nativeRequestHint } from "../native-tools.js";
+import { ENDPOINT_EXTENSION, endpointExtension, endpointInstructions } from "../skills.js";
+import { NATIVE_DEGRADED_TOOLS_LIST_TTL_MS, NATIVE_TOOLS_LIST_TTL_MS, NativeSurface, nativeRequestHint, } from "../native-tools.js";
 import { registerSkills } from "./skills.js";
 import { failureRecord, logFailure } from "../operator-record.js";
 import { redactAgentOutput, sentSecretsForRequest } from "../sent-secrets.js";
@@ -128,7 +129,7 @@ function withMcpCors(response, request, allowedOrigin) {
         }
         headers.append("Vary", "Access-Control-Request-Headers");
     }
-    headers.set("Access-Control-Expose-Headers", "WWW-Authenticate, Retry-After, mcp-session-id, mcp-protocol-version, Connecta-Error-Code, Connecta-Recovery");
+    headers.set("Access-Control-Expose-Headers", "WWW-Authenticate, Retry-After, mcp-session-id, mcp-protocol-version, Connecta-Error-Code, Connecta-Recovery, Connecta-Next-Action");
     const wrapped = new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
@@ -321,7 +322,7 @@ function toolkitRetired(logger, sentSecrets) {
         },
     });
 }
-function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, registry, canManageAuth, principalKey, runtimeContext, readOnly = false, pool, principalActor) {
+function serveMcp(request, requestSignal, requestStartedAt, requestScope, opts, baseUrl, actor, registry, canManageAuth, principalKey, runtimeContext, readOnly = false, pool, principalActor, agentEndpoint = false) {
     const sentSecrets = sentSecretsForRequest(requestScope);
     // Every McpServer the request builds is fresh and closes with its scope.
     // The modern handler tears its own down after the exchange; the legacy
@@ -329,7 +330,14 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
     const servers = [];
     // A native pool lists its downstream tools directly (pools.<name>.surface).
     const native = pool !== undefined ? opts.pools.get(pool)?.native : undefined;
+    // Agent endpoints keep six tools until Eve is tested against the seventh. The
+    // eval arms that render other route names measure their own fixed surfaces.
+    const readRoute = opts.config.execute.readRoute && !native && !readOnly && !agentEndpoint && opts.routes === META_ROUTES;
     const createServer = authMethod((hint) => authFlow(function* () {
+        // A native pool's text uses the native contract's wording.
+        const routes = native ? routeNames(native.executeCode ? "native-code" : "native") : opts.routes;
+        // Direct-call and handoff text names the program route read follow-ups should take.
+        const directRoutes = readRoute ? routeNames("read-route") : routes;
         const authElicitation = new AuthElicitation({
             vault: opts.config.vault,
             publicUrl: opts.config.publicUrl,
@@ -337,40 +345,49 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             principal: principalKey,
             registry,
             canManage: canManageAuth,
-            connectLink: authMethod((id, force, after) => authCall(oauthConnectLink, [
+            connectLink: authMethod((id, force, flow) => authCall(oauthConnectLink, [
                 opts,
                 opts.config.publicUrl ?? baseUrl,
                 id,
                 principalKey,
                 force,
                 Boolean(opts.config.vault?.seal && opts.config.vault.open),
-                after,
+                flow,
             ])),
-            linkProgress: authMethod((id, nonce) => authCall(oauthConnectLinkProgress, [opts, baseUrl, id, nonce])),
-            closeLinks: authMethod((id, nonces) => authCall(closeOAuthConnectLinks, [opts, baseUrl, id, nonces])),
+            linkStarted: authMethod((id, nonce) => authCall(oauthConnectLinkStarted, [opts, baseUrl, id, nonce])),
             claimRetry: authMethod((id, nonce) => authCall(claimAuthRetry, [opts, baseUrl, id, nonce])),
             unavailable: oauthConnectUnavailable(opts),
             credentialUi: Boolean(opts.config.ui && opts.config.vault),
+            credentialHandoffUrl: opts.config.ui?.credentialHandoffUrl(baseUrl),
+            routes: directRoutes,
             requestSignal,
             requestScope,
             defer: runtimeContext?.waitUntil?.bind(runtimeContext),
         });
+        // Read as this request's response is built, so a degraded native listing can shorten it.
+        const toolsListHint = { ttlMs: native ? NATIVE_TOOLS_LIST_TTL_MS : 3_600_000, cacheScope: "private" };
+        const connectors = registry.listConnectors();
+        const effectiveReadOnly = readOnly || (connectors.length > 0 && connectors.every((connector) => connector.readOnly === true));
         const server = new McpServer(opts.config.serverInfo, {
             // A request-local server cannot publish catalog changes. Set this before
             // tool registration, whose SDK default otherwise advertises listChanged.
-            capabilities: { tools: { listChanged: false }, extensions: { "io.modelcontextprotocol/skills": {} } },
-            // Instructions differ per endpoint only by the admitted pool's
-            // description. Every cache hint below is private, so a client keeps
-            // what it learned per endpoint URL and never shares it across them.
-            instructions: endpointInstructions(pool !== undefined ? opts.pools.get(pool)?.description : undefined, native),
+            capabilities: {
+                tools: { listChanged: false },
+                extensions: {
+                    "io.modelcontextprotocol/skills": {},
+                    [ENDPOINT_EXTENSION]: endpointExtension(connectors, native !== undefined, native?.executeCode ?? true, effectiveReadOnly),
+                },
+            },
+            // Instructions reflect the admitted pool, its connector roster and the effective write
+            // policy. `registry` is this caller's admitted view, the one execute_code's inventory
+            // reads, so a person at plain /mcp never sees an id outside their pool. Every cache hint
+            // below is private, so a client keeps what it learned for this caller and endpoint URL.
+            instructions: endpointInstructions(pool !== undefined ? opts.pools.get(pool)?.description : undefined, native, effectiveReadOnly, connectors.map((connector) => connector.id), readRoute),
             inputRequired: { legacyShim: false },
             requestState: { verify: (state, context) => authElicitation.verify(state, context) },
             cacheHints: {
                 "server/discover": { ttlMs: 3_600_000, cacheScope: "private" },
-                "tools/list": {
-                    ttlMs: native ? NATIVE_TOOLS_LIST_TTL_MS : 3_600_000,
-                    cacheScope: "private",
-                },
+                "tools/list": toolsListHint,
             },
         });
         servers.push(server);
@@ -378,6 +395,7 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             ? {
                 sink: opts.config.activity?.store,
                 recordTool: opts.config.activity?.recordTool,
+                recordOperation: opts.config.activity?.recordOperation,
                 actor,
                 ...(principalActor ? { principalActor } : {}),
                 requestId: crypto.randomUUID(),
@@ -397,12 +415,15 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             probeTimeoutMs: opts.config.discovery.probeTimeoutMs,
             ...(runtimeContext?.waitUntil ? { defer: runtimeContext.waitUntil.bind(runtimeContext) } : {}),
         });
-        const diagnostics = native ? { ...native, catalogErrors: [] } : undefined;
-        // A native pool's text uses the native contract's wording.
-        const routes = native ? routeNames(native.executeCode ? "native-code" : "native") : opts.routes;
+        const diagnostics = native
+            ? { ...native, catalogErrors: [], staleCatalogs: [] }
+            : undefined;
+        // The program tool this request lists and its reads may offer: the read route, where listed.
+        const programTool = !native || native.executeCode ? directRoutes.program : undefined;
         const nativeRoute = registerMetaTools(server, registry, {
             native: diagnostics,
-            routes,
+            programTool,
+            routes: directRoutes,
             authElicitation,
             client,
             baseUrl,
@@ -414,19 +435,23 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
             credentialHandoffUrl: opts.config.ui?.credentialHandoffUrl(baseUrl),
             ...(activity ? { activity } : {}),
             defaultToolTimeoutMs: opts.config.calls.defaultTimeoutMs ?? opts.config.execute.hostCallTimeoutMs,
+            responseCeilingMs: opts.config.execute.watchdogMs,
+            requestStartedAt,
             maxProgramResultChars: opts.config.execute.maxResultChars,
+            maxProgramHostCalls: opts.config.execute.maxHostCalls,
             probeTimeoutMs: opts.config.discovery.probeTimeoutMs,
             discoveryConcurrency: opts.config.discovery.concurrency,
             requestSignal,
             ...(runtimeContext?.waitUntil ? { defer: runtimeContext.waitUntil.bind(runtimeContext) } : {}),
         });
-        if (!native || native.executeCode) {
+        if (programTool) {
             registerExecuteTool(server, registry, {
                 authElicitation,
                 client,
                 baseUrl,
                 requestScope,
                 executor: opts.executor,
+                requestStartedAt,
                 defaultToolTimeoutMs: opts.config.calls.defaultTimeoutMs ?? opts.config.execute.hostCallTimeoutMs,
                 logger: opts.config.logger,
                 ...(activity ? { activity } : {}),
@@ -436,6 +461,7 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
                 readOnly,
                 native: native !== undefined,
                 routes,
+                readRoute,
             });
         }
         if (native && nativeRoute && hint) {
@@ -445,6 +471,10 @@ function serveMcp(request, requestSignal, requestScope, opts, baseUrl, actor, re
                 route: nativeRoute,
                 bind: (context) => authElicitation.bind(context),
                 catalogErrors: diagnostics.catalogErrors,
+                staleCatalogs: diagnostics.staleCatalogs,
+                onDegradedListing: () => {
+                    toolsListHint.ttlMs = NATIVE_DEGRADED_TOOLS_LIST_TTL_MS;
+                },
                 logger: opts.config.logger,
                 requestScope,
                 requestSignal,
@@ -635,16 +665,22 @@ export function createMcpRoute(opts) {
         request.signal.addEventListener("abort", onCallerAbort, { once: true });
         if (request.signal.aborted)
             onCallerAbort();
+        const finishTiming = startTimingTrace(requestScope, opts.config.timingTraceSampleRate, opts.config.logger);
         let deadlineTimer;
         return scopedToBody(Effect.gen(function* () {
             yield* Effect.addFinalizer(() => Effect.sync(() => {
-                requestOwner(requestScope).close();
-                if (!localAbort.signal.aborted) {
-                    localAbort.abort(request.signal.reason ?? new Error("MCP request ended."));
+                try {
+                    requestOwner(requestScope).close();
+                }
+                finally {
+                    finishTiming?.();
+                    if (!localAbort.signal.aborted) {
+                        localAbort.abort(request.signal.reason ?? new Error("MCP request ended."));
+                    }
+                    request.signal.removeEventListener("abort", onCallerAbort);
+                    if (deadlineTimer !== undefined)
+                        clearTimeout(deadlineTimer);
                 }
-                request.signal.removeEventListener("abort", onCallerAbort);
-                if (deadlineTimer !== undefined)
-                    clearTimeout(deadlineTimer);
             }));
             // A request naming `subscriptions/listen` defers its permit: nothing of
             // its body is read until auth and endpoint admission pass, and then at
@@ -652,8 +688,12 @@ export function createMcpRoute(opts) {
             // modern listen goes without a permit; trusting the header alone would
             // let a legacy tools/call bypass the pool, so anything else takes one
             // after classification. Every other request takes its permit here,
-            // before auth, and no body is read before auth on any path.
+            // before auth, and this route reads no body before auth on any path.
+            // The Node adapter has already buffered up to its own pre-auth cap
+            // (`listen`'s `maxBodyBytes`) before a request reaches core.
             const startedAt = Date.now();
+            // The response ceiling counts from here; a future stamp could only extend it.
+            const arrivedAt = Math.min(context.runtimeContext?.requestArrivedAt ?? startedAt, startedAt);
             const maxDurationMs = opts.requestAdmission.maxDurationMs;
             const listenHeader = request.method === "POST" && request.headers.get("Mcp-Method") === "subscriptions/listen";
             const refuseAdmission = (error) => {
@@ -766,8 +806,12 @@ export function createMcpRoute(opts) {
                     const headers = new Headers(response.headers);
                     headers.set("Connecta-Error-Code", "host_auth_required");
                     headers.set("Connecta-Recovery", "host_connection");
-                    // Custom adapters may own a streaming or non-JSON response. Preserve
-                    // that body and its request lifetime, and carry recovery in headers.
+                    headers.set("Connecta-Next-Action", JSON.stringify({
+                        action: "reconnect_host",
+                        purpose: "Reconnect the host with valid inbound credentials and endpoint grants; downstream OAuth cannot repair this connection.",
+                    }));
+                    // Custom adapters own their response stream and request lifetime.
+                    // Their typed recovery is carried in headers instead of replacing it.
                     if (!response.headers.get("Content-Type")?.includes("application/json")) {
                         return cors(new Response(response.body, { status: response.status, headers }));
                     }
@@ -780,6 +824,10 @@ export function createMcpRoute(opts) {
                             message: "The host is not authorized to connect to this endpoint. Sign in or update the host's connecta access token and endpoint grants.",
                             retryable: false,
                             recovery: "host_connection",
+                            nextAction: {
+                                action: "reconnect_host",
+                                purpose: "Reconnect this host to Connecta with valid inbound credentials and endpoint grants. Downstream connector authorization cannot repair the host connection.",
+                            },
                         },
                     })), { status: response.status, headers }));
                 }
@@ -923,7 +971,7 @@ export function createMcpRoute(opts) {
                 if (new URL(request.url).searchParams.has("toolkit")) {
                     return cors(toolkitRetired(opts.config.logger, sentSecrets));
                 }
-                return cors(yield* serveMcp(localRequest, localAbort.signal, requestScope, opts, baseUrl, authz.actor, scopedRegistry, (id) => {
+                return cors(yield* serveMcp(localRequest, localAbort.signal, arrivedAt, requestScope, opts, baseUrl, authz.actor, scopedRegistry, (id) => {
                     const connector = scopedRegistry.getConnector(id);
                     return Boolean(connector && mayManageConnector(opts, authz, connector));
                 }, authz.principalKey, runtimeContext, readOnly, scope.pool, authz.identity.principal
@@ -932,7 +980,7 @@ export function createMcpRoute(opts) {
                         id: authz.identity.principal.id,
                         namespace: authz.identity.principal.namespace,
                     }
-                    : undefined));
+                    : undefined, agentEndpoint));
             });
             if (remainingMs === undefined)
                 return yield* handled;

package/dist/routes/shared.d.ts

@@ -34,6 +34,12 @@ export interface ServerOptions {
 }
 export interface RuntimeExecutionContext extends InboundAuthRuntimeContext {
     waitUntil(promise: Promise<unknown>): void;
+    /**
+     * When the Node adapter received this request's headers, before it buffered
+     * the body. It comes from the host, never from anything the request carries.
+     * Workers read the body lazily, so the route's own clock already counts upload.
+     */
+    readonly requestArrivedAt?: number;
 }
 export interface RouteContext {
     request: Request;

package/dist/routes/ui-config.js

@@ -171,7 +171,7 @@ export function scanOperatorActivity(context, authz, registry, rows, agents) {
                         continue;
                     // A last call is a call; any row recorded for an agent, a catalog
                     // refresh included, is a sign it was seen.
-                    const row = event.kind !== "catalog_drift" && OUTCOMES.has(event.outcome) ? byId.get(event.connectorId) : undefined;
+                    const row = event.kind === undefined && OUTCOMES.has(event.outcome) ? byId.get(event.connectorId) : undefined;
                     const agent = (event.actor.kind === "access_token" || event.actor.kind === "vercel_oidc") &&
                         event.actor.namespace === AGENT_NAMESPACE &&
                         event.actor.id

package/dist/routes/ui-data.js

@@ -249,6 +249,7 @@ export function uiData(registry, baseUrl, options) {
                     toolCount,
                     observedAt: Date.now(),
                 }));
+            const observedAgeMs = observation ? Math.max(0, Date.now() - observation.observedAt) : undefined;
             return {
                 id: c.id,
                 authScope: c.authScope ?? "shared",
@@ -271,9 +272,9 @@ export function uiData(registry, baseUrl, options) {
                     ...(status.registrationPath ? { auth: { registrationPath: status.registrationPath } } : {}),
                     catalogAgeMs: registry.catalogAgeMs(c.id),
                     lastCall: null,
-                    ...(observation ? { observedAgeMs: Math.max(0, Date.now() - observation.observedAt) } : {}),
+                    ...(observedAgeMs !== undefined ? { observedAgeMs } : {}),
                 },
-                ...(observation ? { observedAgeMs: Math.max(0, Date.now() - observation.observedAt) } : {}),
+                ...(observedAgeMs !== undefined ? { observedAgeMs } : {}),
                 // Counts only, and only when a refresh in this runtime produced them.
                 // `Registry.withCatalogObservations` rebuilt the report through
                 ...(status.catalogAccess ? { catalogAccess: status.catalogAccess } : {}),

package/dist/runtime/call.js

@@ -359,17 +359,22 @@ export function wrapViewCredentials(view) {
         return;
     entry.credentialWrapped = true;
     const access = view.credential;
+    // A read outlives a caller that stopped waiting and registers when it lands, so the
+    // request counts it until then: a sealing run must not publish ahead of that.
+    const read = async (value, values) => {
+        const done = requestOf(entry.request).credentialReads.begin();
+        try {
+            const result = await value();
+            registerCredentialValues(viewSecrets(view), values(result));
+            return result;
+        }
+        finally {
+            done();
+        }
+    };
     view.credential = {
-        get: (field) => settleOnClose(view, async () => {
-            const value = await access.get(field);
-            registerCredentialValues(viewSecrets(view), value === null ? null : { [field ?? "value"]: value });
-            return value;
-        }, true),
-        getAll: () => settleOnClose(view, async () => {
-            const values = await access.getAll();
-            registerCredentialValues(viewSecrets(view), values);
-            return values;
-        }, true),
+        get: (field) => settleOnClose(view, () => read(() => access.get(field), (value) => (value === null ? null : { [field ?? "value"]: value })), true),
+        getAll: () => settleOnClose(view, () => read(() => access.getAll(), (values) => values), true),
     };
 }
 /** Credentials for request-owned transports use the operation, never a closed call. */

package/dist/runtime/native-storage.js

@@ -25,6 +25,11 @@ export function registerNativeStorage(edge, native) {
     storageMethods.set(edge, own);
     const getMany = native.getMany;
     storage.set(edge, {
+        catalogSnapshot: native.catalogSnapshot
+            ? (keys, generationKey, prefix, suffixes) => typed(() => getNativeStorage(edge)
+                ? native.catalogSnapshot(keys, generationKey, prefix, suffixes)
+                : Effect.succeed(new Map()))
+            : undefined,
         accessToken: native.accessToken
             ? (hash) => typed(() => (getNativeStorage(edge) ? native.accessToken(hash) : Effect.succeed(undefined)))
             : undefined,
@@ -37,6 +42,13 @@ export function registerNativeStorage(edge, native) {
                     : Effect.forEach(keys, (key) => current(edge, "get", own.get, [key], () => native.get(key)))),
             }
             : {}),
+        ...(native.setMany
+            ? {
+                setMany: (entries, options) => typed(() => getNativeStorage(edge)
+                    ? native.setMany(entries, options)
+                    : Effect.asVoid(Effect.forEach(entries, ([key, value]) => current(edge, "set", own.set, [key, value, options], () => native.set(key, value, options))))),
+            }
+            : {}),
         set: (key, value, options) => current(edge, "set", own.set, [key, value, options], () => native.set(key, value, options)),
         delete: (key) => current(edge, "delete", own.delete, [key], () => native.delete(key)),
         list: (prefix) => current(edge, "list", own.list, [prefix], () => native.list(prefix)),

package/dist/runtime/request-reads.js

@@ -1,3 +1,4 @@
+import { utf8Length } from "../bytes.js";
 // Request-scoped memo of storage reads (INV-7).
 //
 // One request often reads the same key many times: a catalog listing reads its
@@ -36,6 +37,7 @@
 // `FinalizationRegistry` (workerd before compatibility date 2025-05-05 without
 // `enable_weak_ref`) memoizes nothing: every read goes to storage.
 import { Effect } from "effect";
+import { getNativeStorage } from "./native-storage.js";
 const roots = new WeakMap();
 const observed = new WeakMap();
 /**
@@ -88,7 +90,7 @@ export function observeStorageWrites(storage, layer) {
     return storage;
 }
 /** The underlying store and key a read of `key` reaches, when every layer is observed. */
-function physical(storage, key) {
+export function physicalStorageAddress(storage, key) {
     const entry = observed.get(storage);
     if (!entry)
         return undefined;
@@ -99,10 +101,17 @@ function physical(storage, key) {
         own.list !== storage.list ||
         own.compareAndSet !== storage.compareAndSet)
         return undefined;
-    return "root" in layer ? { store: layer.root, key } : physical(layer.storage, layer.prefix + key);
+    return "root" in layer ? { store: layer.root, key } : physicalStorageAddress(layer.storage, layer.prefix + key);
 }
 const weakReferences = () => typeof WeakRef === "function" && typeof FinalizationRegistry === "function";
 export class RequestReads {
+    trace;
+    constructor(trace) {
+        this.trace = trace;
+    }
+    note(fresh, hit, value, started) {
+        this.trace?.record(fresh ? "memo.fresh" : hit ? "memo.hit" : "memo.miss", performance.now() - started, value === null ? 0 : utf8Length(value), 0, value === null ? 1 : 0);
+    }
     closed = false;
     stores = new Map();
     ref = weakReferences() ? new WeakRef(this) : undefined;
@@ -129,7 +138,7 @@ export class RequestReads {
     }
     /** A memoized answer, or how to record the value a storage read returns. */
     lookup(storage, key, fresh) {
-        const address = this.closed || !this.ref ? undefined : physical(storage, key);
+        const address = this.closed || !this.ref ? undefined : physicalStorageAddress(storage, key);
         if (!address)
             return undefined;
         const entries = this.entriesFor(address.store);
@@ -155,31 +164,70 @@ export class RequestReads {
     read(storage, key, load, fresh = false) {
         return Effect.suspend(() => {
             const found = this.lookup(storage, key, fresh);
-            if (!found)
+            if (!found && !this.trace)
                 return load;
-            if (found.hit)
+            const started = this.trace ? performance.now() : 0;
+            if (found?.hit) {
+                if (this.trace)
+                    this.note(fresh, true, found.value, started);
                 return Effect.succeed(found.value);
-            return Effect.tap(load, (value) => Effect.sync(() => found.record(value)));
+            }
+            return Effect.tap(load, (value) => Effect.sync(() => {
+                found?.record(value);
+                if (this.trace)
+                    this.note(fresh, false, value, started);
+            }));
         });
     }
     /** Prefetch only keys whose callers already permit request-local staleness. */
-    prefetch(requests, load) {
+    prefetch(requests, load, linked) {
         return Effect.suspend(() => {
             const pending = requests.map(({ storage, key }) => ({
-                address: physical(storage, key),
+                address: physicalStorageAddress(storage, key),
                 found: this.lookup(storage, key, false),
             }));
+            if (this.trace)
+                for (const { found } of pending)
+                    if (found?.hit)
+                        this.note(false, true, found.value, performance.now());
+            const started = this.trace ? performance.now() : 0;
             const root = pending[0]?.address?.store;
             const storage = root && roots.get(root);
             if (!storage || pending.some(({ address, found }) => !found || address?.store !== root))
                 return Effect.void;
+            if (pending.every(({ found }) => found?.hit))
+                return Effect.void;
+            const generation = linked && physicalStorageAddress(linked.storage, linked.generationKey);
+            const prefix = linked && physicalStorageAddress(linked.storage, linked.prefix);
+            const snapshot = getNativeStorage(storage)?.catalogSnapshot;
+            if (linked && snapshot && generation?.store === root && prefix?.store === root) {
+                // Candidates only locate entries. An intervening external write can make
+                // these stale, so consumers retain the separate post-chunk primary fence.
+                return Effect.map(snapshot(pending.map(({ address }) => address.key), generation.key, prefix.key, linked.suffixes), (values) => {
+                    pending.forEach(({ address, found }) => {
+                        if (found && !found.hit)
+                            found.record(values.get(address.key) ?? null);
+                    });
+                    for (const [key, value] of values) {
+                        if (pending.some(({ address }) => address.key === key))
+                            continue;
+                        const found = this.lookup(storage, key, false);
+                        if (found && !found.hit)
+                            found.record(value);
+                    }
+                });
+            }
             const misses = pending.filter(({ found }) => found && !found.hit);
             if (!misses.length)
                 return Effect.void;
             return Effect.map(load(storage, misses.map(({ address }) => address.key)), (values) => {
                 misses.forEach(({ found }, i) => {
-                    if (found && !found.hit)
-                        found.record(values[i] ?? null);
+                    if (found && !found.hit) {
+                        const value = values[i] ?? null;
+                        found.record(value);
+                        if (this.trace)
+                            this.note(false, false, value, started);
+                    }
                 });
             });
         });
@@ -187,12 +235,16 @@ export class RequestReads {
     /** `read` for a Promise-shaped caller, without another Effect edge. */
     async readPromise(storage, key, load, fresh = false) {
         const found = this.lookup(storage, key, fresh);
-        if (!found)
-            return load();
-        if (found.hit)
+        const started = this.trace ? performance.now() : 0;
+        if (found?.hit) {
+            if (this.trace)
+                this.note(fresh, true, found.value, started);
             return found.value;
+        }
         const value = await load();
-        found.record(value);
+        found?.record(value);
+        if (this.trace)
+            this.note(fresh, false, value, started);
         return value;
     }
     close() {

package/dist/runtime/request-scope.js

@@ -1,8 +1,42 @@
+import { traceFor } from "../timing-trace.js";
 // One owner per existing upstream request identity. Facts survive revocation;
 // retaining them never reconstitutes a call capability or a live operation.
-import { Context, Exit, Scope } from "effect";
+import { Context, Effect, Exit, Scope } from "effect";
 import { RequestReads } from "./request-reads.js";
 import { detach } from "./run.js";
+/** Work that can still add to a secret set. A sealing run waits until none is left. */
+export class PendingWork {
+    active = 0;
+    waiting = new Set();
+    get pending() {
+        return this.active > 0;
+    }
+    /** Returns the function that ends this piece of work; calling it twice counts once. */
+    begin() {
+        this.active++;
+        let done = false;
+        return () => {
+            if (done)
+                return;
+            done = true;
+            if (--this.active > 0)
+                return;
+            for (const wake of this.waiting)
+                wake();
+            this.waiting.clear();
+        };
+    }
+    /** Succeeds when nothing is pending. Interrupting it drops the wait. */
+    idle = Effect.callback((resume) => {
+        if (this.active === 0)
+            return resume(Effect.void);
+        const wake = () => resume(Effect.void);
+        this.waiting.add(wake);
+        return Effect.sync(() => {
+            this.waiting.delete(wake);
+        });
+    });
+}
 export class RequestOwner {
     identity;
     open = true;
@@ -13,6 +47,8 @@ export class RequestOwner {
     calls = new Set();
     signals = new WeakMap();
     scope = Scope.makeUnsafe();
+    /** Credential reads whose values have yet to join this request's secret set. */
+    credentialReads = new PendingWork();
     // Initialize secrets only when data is sent. Metadata-only UI imports must
     // not retain the payload matcher merely to revoke a request.
     retained = {
@@ -71,7 +107,7 @@ export function requestReads(identity) {
 export function ownerReads(owner) {
     const retained = owner.retained;
     if (!retained.reads) {
-        retained.reads = new RequestReads();
+        retained.reads = new RequestReads(traceFor(owner.identity));
         if (!owner.open)
             retained.reads.close();
     }

package/dist/runtime/run.js

@@ -128,7 +128,10 @@ export function withDeadlineEffect(operation, options) {
             fromSignal(controller.signal),
         ];
         if (options.timeoutMs !== undefined) {
-            contenders.push(Effect.sleep(Duration.millis(options.timeoutMs)).pipe(Effect.andThen(Effect.sync(() => controller.abort(options.timeoutError))), Effect.andThen(Effect.never)));
+            contenders.push(Effect.sleep(Duration.millis(options.timeoutMs)).pipe(Effect.andThen(Effect.suspend(() => {
+                const more = options.extendMs?.() ?? 0;
+                return more > 0 ? Effect.sleep(Duration.millis(more)) : Effect.void;
+            })), Effect.andThen(Effect.sync(() => controller.abort(options.timeoutError))), Effect.andThen(Effect.never)));
         }
         return Effect.raceAllFirst(contenders).pipe(Effect.ensuring(Effect.sync(() => {
             controller.abort();