@farmslot/protocol 0.74.10 → 0.75.0

package/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to `@farmslot/protocol` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.75.0 - 2026-11-03
+
+- `SlotReleaseParams.skipArtifacts` is removed: a slot release no longer copies artifacts, so there is nothing to skip (F313).
+- `SlotStatus.retained` (`{ items, bytes }`): the nested checkouts that slot releases moved aside on the slot host instead of deleting them, and their total size there (F310).
+- `ReadyGatePayload.mergeConflicts`/`behindMain` are probed against the publication base (a stacked run's upstream branch), and a conflict on a publication gate now blocks its advancing actions (doc only; no shape change).
+- A client-cache observer that throws no longer stops the other observers or the cache's reads; each failing observer is logged once with `console.error`. Before, an observer that threw as a read started, or on its first delivery from `observe`, left that query loading with no request sent until the next reconnect.
+- `DispatchPreview.inheritedAcceptance`: the parent run and its original criteria a pr-complete run is held to, or `unavailable` with the reason.
+- `Run.parkedCommits` (`ParkedRunCommits[]`): an artifact-only run's own branch commits, parked under `refs/farmslot/parked/<run>/<head>` when its slot returned to idle (append-only).
+- `Run.releasedCheckout`: the branch and head an artifact-only run left on its slot when COMPLETE released the slot's ownership; a later ownerless return to idle parks only that head.
+- `RunEngineState.publishGate.refusedEvidencePackageId`: the prepared package a human-gate replay found the worker's evidence refused against; while it is still `packageId`, the gate rebuilds rather than reuses it.
+- `RunPipelineReviewPolicy` (`'default' | 'none'`) on `Run`, `RunCreateParams` and `DispatchPreviewParams` (with `completionPolicy`), `DispatchPreview.pipelineReview`, and the shared `pipelineReviewOffReason` / `pipelineReviewPolicyError` rule. Only an artifact-only dev or fix-bug run may turn its pipeline review off, and not alongside `reviewSequence`, `reviewPolicy` or an eval experiment; an unknown value is refused.
+- `compareText` orders strings as `localeCompare` does, through one shared `Intl.Collator`. Run lists and family groups sort with it.
+- Content prefetch hashes files and artifacts in 16 KB slices, one per macrotask, so a large file no longer blocks a frame; content a person opens still verifies at once.
+- Change notifications match queries by dependency ids computed when the query is first observed.
+- `ContentPrefetchOptions.media` (`ContentPrefetchMedia`, `ContentPrefetchMediaEntry`): a pending gate's videos and images over the content row cap go to a client media holder by digest, with the gate's age, instead of loading only when opened. `base64Bytes` and `createSha256` (chunked SHA-256) are exported from the client cache.
+- A gate or run whose first `run.get` fails (a timeout on a busy gateway, not a refusal), or a gate whose package does not fully load, is prefetched again after 5 s, 30 s, then every 2 minutes until a read succeeds or the run leaves the targets. Before, nothing read it again until the gateway connection changed, so a pending gate's evidence, videos included, never reached the device. A gate whose review diff cannot be read still hands its videos and large images to the media holder.
+- `awaitsHumanDecision(run)` is exported: a run at its human gate (also while a review it requested is still running and its ready decision is already resolved) or blocked at an open one, the runs the review queues show as waiting on a decision. Prefetch treats such a run as a gate and keeps prefetching its current package after its ready decision is resolved.
+- `CommandMethod` is now the closed `GATEWAY_COMMAND_METHODS` list, and `GATEWAY_READ_EXCEPTIONS` names the only reads a client sends outside the shared cache (ADR-071 Amendment 2: offline-first reads).
+- New `AppBindingMismatchPayload` (`kind: 'app_binding_mismatch'`) in `RunDecisionPayload`: the slot, the run's app, the slot's app and its source, and the project's slots bound to the run's app when they could be listed, and `operatorPick` when the slot came from a slot picker (F306).
+- New `projectDefaultApp(project)`: `recipe.app`, else the project's only declared app.
+- `PoolConfig` slots may carry `app`.
+- Record the question-tool setting of native worker processes and terminal worker contexts so retained task handoffs can resume or relaunch when it changes.
+- `trimRunForList`, `trimDecisionForList` and `RUN_LIST_PAYLOAD_VALUE_LIMIT` move here from the gateway (`runs/list-trim`), beside the new `runHasTrimmedDetail(run)`, moved from Command Center: whether a run.list row left out its output manifest or any decision payload value, which a view shows as not loaded until `run.get` lands. One module now holds what run.list leaves out and how a client tells.
+- `readRefused(error)` (client-cache): whether a read error is a gateway refusal (`RUN_NOT_FOUND`, `NOT_FOUND`, `RESOURCE_NOT_FOUND`, `AUTH_REQUIRED`, `AUTH_FORBIDDEN`), the same codes on which the cache evicts saved data. A network failure or timeout is not one.
+- `currentReviewChainEntry` reports `unresolvedCount: null` when the review result's `lineComments` is missing, as on a run.list row that trimmed it, instead of throwing.
+- `slotRecoveryEligibility` treats a clean ownerless checkout with unpushed commits as safe for bulk release with no confirmation, because the release parks those commits. New `parksSlotCommits`, `SlotParkedCommits` and `slotParkedDetail`. `SlotRefreshResult` and `FleetRefreshSlotUpdateEvent` gain an optional `parked` report.
+- `FleetStatus.poolErrors` lists pool files the last fleet refresh could not parse, and `SlotStatus.configError` gives why a slot's config could not be loaded.
+- Recording timelines accept equal adjacent presentation timestamps without dropping decoded frames; backwards, invalid and out-of-duration timestamps remain invalid.
+- Template previews and options on Dispatch accept an execution template id of the form `<flow>/<name>` (for example `pr-complete/default`). Before, every preview failed with "Invalid configuration selector: executionTemplateId". Command Center checks the selector before sending, and the gateway checks it again on marked reads, so both must run this version. The id still refuses `\`, empty segments, and `.` or `..` segments, and other configuration selectors stay single segments (F319).
+- `isPickerCatalogModel` and `runnerModelProviderLabel` hold the one rule for which node catalog models a picker shows: LiteLLM ("Consensys LiteLLM"), xAI, Anthropic and local omlx/lmstudio models, without Claude 4.x or older or Grok before 4.7. `RunnerCatalogModel.nodes` names the execution nodes that list a model when some node does not. Pi and OpenCode have no `RUNNER_PICKER_MODELS` seed any more, `PI_ANTHROPIC_MODELS` is removed, and `DEFAULT_PI_MODEL` and `DEFAULT_GROK_MODEL` are `grok-4.7`. `NativeRunnerOption.nodeModels` holds each execution node's models for Pi and OpenCode, and `nativeRunnerModels(option, executionNodeId)` picks the list for a session's node. `DispatchCandidatesParams` takes the chosen `runner` and `model`.
+- Keep bounded Dispatch candidate and ticket-match snapshots in the shared client store, with candidate invalidation when fleet, run, configuration or model catalogs change.
+
 ## 0.74.10 - 2026-11-01
 
 - `runWorkerEffort` names a run's worker effort (the worker context, then its native session, the dispatch effort, then the execution-profile choice for its runner and model), and `runEngineLabel` formats `runner/model · effort` with the effort only when known.

package/dist/client-cache/artifact-response.d.ts

@@ -0,0 +1,15 @@
+import type { GatewayResourceCache } from './types.js';
+export interface StoredArtifactRead {
+    current(): GatewayResourceCache | undefined;
+    url: string;
+    online: boolean;
+    read(): Promise<Response>;
+    signal?: AbortSignal;
+    /** Explicit reloads wait for fresh bytes; ordinary display opens saved bytes immediately. */
+    refresh?: boolean;
+    onStored?(response: Response): unknown;
+    onRefreshError?(error: unknown | undefined): void;
+}
+/** Retained text uses the same verified, bounded content store as images and files. */
+export declare function readStoredArtifactResponse({ current, url, online, read, signal, refresh, onRefreshError, onStored, }: StoredArtifactRead): Promise<Response>;
+//# sourceMappingURL=artifact-response.d.ts.map

package/dist/client-cache/artifact-response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-response.d.ts","sourceRoot":"","sources":["../../src/client-cache/artifact-response.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,OAAO,IAAI,oBAAoB,GAAG,SAAS,CAAC;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC;IACvC,cAAc,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;CACnD;AAeD,uFAAuF;AACvF,wBAAsB,0BAA0B,CAAC,EAC/C,OAAO,EACP,GAAG,EACH,MAAM,EACN,IAAI,EACJ,MAAM,EACN,OAAe,EACf,cAAc,EACd,QAAQ,GACT,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsFxC"}

package/dist/client-cache/artifact-response.js

@@ -0,0 +1,103 @@
+import { createSha256, RESOURCE_CONTENT_LIMITS } from './content.js';
+function textResponse(data, init) {
+    const response = new Response(data.slice().buffer, init);
+    // React Native's Response polyfill decodes ArrayBuffers one byte per character.
+    Object.defineProperty(response, 'text', { value: async () => new TextDecoder().decode(data) });
+    return response;
+}
+function digest(data) {
+    const hash = createSha256();
+    hash.update(data);
+    return hash.hex();
+}
+/** Retained text uses the same verified, bounded content store as images and files. */
+export async function readStoredArtifactResponse({ current, url, online, read, signal, refresh = false, onRefreshError, onStored, }) {
+    const cache = current();
+    if (!cache)
+        throw new Error('The offline store is not open yet');
+    const source = new URL(url, 'https://artifact.invalid');
+    if (source.pathname !== '/api/run-artifact')
+        throw new Error('Expected a retained artifact URL');
+    refresh ||= source.searchParams.has('m');
+    // Mirror refresh is an explicit reread, not part of the retained file's identity.
+    for (const name of ['token', 'password', 'm'])
+        source.searchParams.delete(name);
+    source.hash = '';
+    source.searchParams.sort();
+    // No URL, query credential or document body is written into an alias.
+    const alias = `artifact-response:${digest(new TextEncoder().encode(source.href))}`;
+    const token = cache.contentWriteToken();
+    const assertCurrent = () => {
+        if (signal?.aborted)
+            throw Object.assign(new Error('Artifact read aborted'), { name: 'AbortError' });
+        if (cache !== current() || cache.contentWriteToken().ownerVersion !== token.ownerVersion)
+            throw new Error('The artifact source changed');
+    };
+    assertCurrent();
+    const held = await cache.openContentByAlias(alias);
+    assertCurrent();
+    if (held && !online)
+        return textResponse(held);
+    if (!online)
+        throw new Error('This artifact has not been stored on this device');
+    const fetchFresh = async () => {
+        const response = await read();
+        assertCurrent();
+        if (!response.ok) {
+            if (held && (response.status === 401 || response.status === 403))
+                await cache.forgetContent({ kind: 'artifact', id: digest(held) });
+            return response;
+        }
+        const data = new Uint8Array(await response.arrayBuffer());
+        assertCurrent();
+        // Over-cap files remain the named large-media exception and are fetched only on open.
+        if (data.byteLength <= RESOURCE_CONTENT_LIMITS.fileBytes)
+            await cache.storeContent({
+                key: { kind: 'artifact', id: digest(data) },
+                data,
+                alias,
+                origin: 'opened',
+                cohort: 'run',
+                token,
+            });
+        assertCurrent();
+        return textResponse(data, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        });
+    };
+    if (held && !refresh && onStored) {
+        await onStored(textResponse(held));
+        assertCurrent();
+        try {
+            const response = await fetchFresh();
+            if (response.status >= 500 && onRefreshError) {
+                onRefreshError(new Error(`HTTP ${response.status}`));
+                return textResponse(held);
+            }
+            onRefreshError?.(response.ok ? undefined : new Error(`HTTP ${response.status}`));
+            return response;
+        }
+        catch (error) {
+            assertCurrent();
+            if (!onRefreshError)
+                throw error;
+            onRefreshError(error);
+            return textResponse(held);
+        }
+    }
+    if (held && !refresh && onRefreshError) {
+        // The saved response is the display fallback. Report refresh failures separately so
+        // temporary network loss cannot hide it or leave a rejected background promise.
+        void fetchFresh().then((response) => onRefreshError(response.ok ? undefined : new Error(`HTTP ${response.status}`)), (error) => {
+            if (cache === current() &&
+                !signal?.aborted &&
+                cache.contentWriteToken().ownerVersion === token.ownerVersion)
+                onRefreshError(error);
+        });
+        return textResponse(held);
+    }
+    return fetchFresh();
+}
+//# sourceMappingURL=artifact-response.js.map

package/dist/client-cache/artifact-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-response.js","sourceRoot":"","sources":["../../src/client-cache/artifact-response.ts"],"names":[],"mappings":"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"}

package/dist/client-cache/cache.d.ts

@@ -1,3 +1,8 @@
-import type { GatewayResourceCache, GatewayResourceCacheOptions } from './types.js';
+import type { GatewayResourceCache, GatewayResourceCacheOptions, ResourceQueryError } from './types.js';
+/**
+ * The gateway refused the read: the resource is gone or not this principal's. The
+ * cache evicts saved data on these; a network failure or timeout is not one.
+ */
+export declare function readRefused(error: ResourceQueryError | undefined): boolean;
 export declare function createGatewayResourceCache(options: GatewayResourceCacheOptions): GatewayResourceCache;
 //# sourceMappingURL=cache.d.ts.map

package/dist/client-cache/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/client-cache/cache.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EACV,oBAAoB,EACpB,2BAA2B,EAS5B,MAAM,YAAY,CAAC;AAgGpB,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CA+qCtB"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/client-cache/cache.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EACV,oBAAoB,EACpB,2BAA2B,EAM3B,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAuDpB;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAE1E;AA8CD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAu2CtB"}

package/dist/client-cache/cache.js

@@ -1,11 +1,13 @@
 import { Methods } from '../rpc/registry.js';
+import { runListVersion } from '../runs/list-version.js';
 import { ResourceCollectorAdmission } from './collector-admission.js';
-import { resourceBudgetEvictions, resourceContentWithinLimits, verifyResourceContent, } from './content.js';
+import { resourceBudgetEvictions, resourceContentWithinLimits, verifyResourceContent, verifyResourceContentInSlices, } from './content.js';
 import { isKnownResourceFamily, RESOURCE_PUBLISH_INTERVAL_MS, RESOURCE_REREAD_INTERVAL_MS, RESOURCE_RETRY_MAX_WAIT_MS, resourceKeyId, } from './keys.js';
 import { nativeHistoryStorageId, readNativeHistory, storedNativeHistoryMatches, } from './native-history.js';
 import { resourceQuery } from './registry.js';
+import { createRunDetailSync, runDetailTarget } from './run-details.js';
 import { isRunListCollectionRead, RUN_LIST_COLLECTION_ID, RunListCollection, runListSummaryFlags, } from './run-list-versions.js';
-import { createMemoryResourceStore, normalizeResourceStoreScope, resourceStoreScopeId, sameResourceAuthority, } from './store.js';
+import { createMemoryResourceStore, normalizeResourceStoreScope, readStoredQueryBatch, resourceStoreScopeId, sameResourceAuthority, } from './store.js';
 import { isUpstreamStoredQuery, upstreamRetentionEvictions } from './upstream-retention.js';
 import { workspaceRetentionEvictions, workspaceRetentionMembership, } from './workspace-retention.js';
 const deletionReasons = new Set([
@@ -21,6 +23,13 @@ const evictionCodes = new Set([
     'RUN_NOT_FOUND',
     'RESOURCE_NOT_FOUND',
 ]);
+/**
+ * The gateway refused the read: the resource is gone or not this principal's. The
+ * cache evicts saved data on these; a network failure or timeout is not one.
+ */
+export function readRefused(error) {
+    return Boolean(error && evictionCodes.has(error.code));
+}
 function queryError(error) {
     const code = error && typeof error === 'object' ? Reflect.get(error, 'code') : undefined;
     return {
@@ -44,6 +53,7 @@ function normalizeConnection(connection) {
     };
 }
 const defaultContentBudgetBytes = 500 * 1024 * 1024;
+const startupQueryBytes = 8 * 1024 * 1024;
 // Only the identity crosses the store seam, never a caller's other fields.
 const contentKey = ({ kind, id }) => ({ kind, id });
 function profileId(connection) {
@@ -56,6 +66,9 @@ export function createGatewayResourceCache(options) {
     const transport = options.transport;
     let store = options.store ?? createMemoryResourceStore();
     let metadata;
+    let startupStore;
+    let startupOwnerVersion = -1;
+    const startupQueries = new Map();
     let connection = normalizeConnection(transport.getConnection());
     let usable = false;
     let disposed = false;
@@ -91,9 +104,33 @@ export function createGatewayResourceCache(options) {
         maxBodyBytes: resourceQuery(Methods.RUN_LIST).maxBytes,
     });
     let runListLoad;
+    const fallbackDetailTargets = new Map();
+    const detailSync = createRunDetailSync({
+        connection: () => connection,
+        list: async () => (await readStoredContent((target) => target.listQueries())) ?? [],
+        stored: (runId) => readStoredContent((target) => target.getQuery(resourceQuery(Methods.RUN_GET, { runId }).id)),
+        touch: async (runId) => {
+            const target = store;
+            const ownerVersion = hydrationOwnerVersion;
+            await updateStore(target, () => target === store && !target.deleted && ownerVersion === hydrationOwnerVersion, () => target.touchQuery?.(resourceQuery(Methods.RUN_GET, { runId }).id, Date.now()) ??
+                Promise.resolve());
+        },
+        fetch: (runId, maxStoredBytes, signal) => retryQuery(resourceQuery(Methods.RUN_GET, { runId }), { origin: 'prefetch', cohort: 'run', maxStoredBytes }, signal),
+        onError: (error) => options.onStorageNotice?.(`Background run details could not sync: ${queryError(error).message}`),
+    });
+    function refreshDetailTargets() {
+        const versioned = runList.detailTargets();
+        detailSync.setTargets(store.persistent && usable
+            ? runList.held
+                ? versioned
+                : [...fallbackDetailTargets.values()]
+            : []);
+    }
     function forgetRunList() {
         runList.clear();
         runListLoad = undefined;
+        fallbackDetailTargets.clear();
+        detailSync.reset();
     }
     function updateCollectors() {
         collectors.update({ ...connection, foreground: usable && connection.foreground !== false }, usable
@@ -116,12 +153,29 @@ export function createGatewayResourceCache(options) {
         unsubscribeStore();
         store = next;
         storeVersion++;
+        startupStore = undefined;
+        startupQueries.clear();
+        detailSync.reset();
         unsubscribeStore = store.onDeleted(storeDeleted);
     }
+    /** Observers whose failure was already logged, so a repeating one is reported once. */
+    const failedObservers = new WeakSet();
+    /** One observer's failure is its own: the other observers and the cache's reads go on. */
+    function deliver(entry, listener) {
+        try {
+            listener(entry.state);
+        }
+        catch (error) {
+            if (failedObservers.has(listener))
+                return;
+            failedObservers.add(listener);
+            console.error(`Resource cache observer of ${entry.query.id} failed:`, error);
+        }
+    }
     function notify(entry) {
         entry.state = { ...entry.state, storageNotice };
         for (const listener of entry.listeners)
-            listener(entry.state);
+            deliver(entry, listener);
     }
     function cancelScheduledRead(entry) {
         if (entry.readTimer !== undefined)
@@ -232,6 +286,46 @@ export function createGatewayResourceCache(options) {
             if (entry.state.status !== 'ready')
                 hydrateEntry(entry);
     }
+    async function warmStoredQueries() {
+        if (!store.persistent ||
+            (startupStore === store && startupOwnerVersion === hydrationOwnerVersion))
+            return;
+        const readingStore = store;
+        const incarnation = storeVersion;
+        const ownerVersion = hydrationOwnerVersion;
+        const current = () => !disposed &&
+            store === readingStore &&
+            !readingStore.deleted &&
+            incarnation === storeVersion &&
+            ownerVersion === hydrationOwnerVersion;
+        try {
+            const batch = await readStoredQueryBatch(readingStore, startupQueryBytes);
+            if (!current())
+                return;
+            const collection = batch.find((saved) => saved.id === RUN_LIST_COLLECTION_ID);
+            const rows = collection && readingStore.getRows
+                ? await readingStore.getRows(RUN_LIST_COLLECTION_ID)
+                : undefined;
+            if (!current())
+                return;
+            startupQueries.clear();
+            let remaining = startupQueryBytes;
+            for (const saved of batch) {
+                if (saved.bytes > remaining)
+                    continue;
+                remaining -= saved.bytes;
+                if (saved.id !== RUN_LIST_COLLECTION_ID)
+                    startupQueries.set(saved.id, saved);
+            }
+            if (rows)
+                runList.hydrate(rows);
+            startupStore = readingStore;
+            startupOwnerVersion = ownerVersion;
+        }
+        catch (error) {
+            await recoverStore(error, readingStore);
+        }
+    }
     function schedule(entry) {
         if (entry.queued || disposed)
             return;
@@ -261,8 +355,13 @@ export function createGatewayResourceCache(options) {
             connection.id === next.id &&
             !scopeChanged &&
             !authorityChanged &&
-            !revoke)
+            !revoke) {
+            if (connection.metered !== next.metered) {
+                connection = { ...connection, metered: next.metered };
+                refreshDetailTargets();
+            }
             return;
+        }
         const ticket = ++version;
         runList.abort();
         // Stored facts belong to an owner, not a socket attempt. Fence a revoked
@@ -273,6 +372,7 @@ export function createGatewayResourceCache(options) {
         }
         connection = next;
         usable = false;
+        refreshDetailTargets();
         updateCollectors();
         revisions.clear();
         for (const entry of entries.values()) {
@@ -361,9 +461,14 @@ export function createGatewayResourceCache(options) {
                     await recoverStore(error, target);
                 }
             }
+            if (disposed || ticket !== version)
+                return;
+            if (!revoke && canPersist(next))
+                await warmStoredQueries();
             if (disposed || ticket !== version)
                 return;
             usable = next.connected && next.foreground !== false && !revoke;
+            refreshDetailTargets();
             updateCollectors();
             if (usable)
                 for (const entry of entries.values())
@@ -409,7 +514,7 @@ export function createGatewayResourceCache(options) {
             if (change.revision <= (revisions.get(id) ?? -1))
                 continue;
             revisions.set(id, change.revision);
-            const affected = [...entries.values()].filter((entry) => entry.query.dependencies.some((key) => resourceKeyId(key) === id));
+            const affected = [...entries.values()].filter((entry) => entry.dependencyIds.has(id));
             // Coverage counts declared dependencies only, so a known key that no entry declares (another
             // slot, an unopened workspace) changes nothing held. Only a family this client cannot name might.
             if (!affected.length && isKnownResourceFamily(change.key?.family))
@@ -441,6 +546,7 @@ export function createGatewayResourceCache(options) {
         }
         const entry = {
             query,
+            dependencyIds: new Set(query.dependencies.map(resourceKeyId)),
             state: { status: 'loading' },
             listeners: new Set(),
             hydration: Promise.resolve(),
@@ -454,9 +560,40 @@ export function createGatewayResourceCache(options) {
             failures: 0,
         };
         entries.set(query.id, entry);
-        hydrateEntry(entry);
+        const saved = isRunListView(query) ? heldRunListView(query) : takeStartupQuery(query);
+        if (applyStoredQuery(entry, saved)) {
+            entry.hydrated = true;
+            queueMicrotask(prune);
+        }
+        else
+            hydrateEntry(entry);
         return entry;
     }
+    function takeStartupQuery(query) {
+        if (startupStore !== store || startupOwnerVersion !== hydrationOwnerVersion)
+            return undefined;
+        const id = nativeHistoryStorageId(query);
+        const saved = startupQueries.get(id);
+        startupQueries.delete(id);
+        return saved;
+    }
+    function applyStoredQuery(entry, saved) {
+        const query = entry.query;
+        if (!saved ||
+            !query.persisted ||
+            saved.bytes > query.maxBytes ||
+            (query.method === Methods.NATIVE_SESSION_READ &&
+                !storedNativeHistoryMatches(query.params, saved.data)))
+            return false;
+        const sourceObservation = query.sourceObservation?.(saved.data);
+        entry.state = {
+            status: 'stale',
+            data: saved.data,
+            observedAt: saved.observedAt,
+            ...(sourceObservation ? { sourceObservation, error: sourceObservation.error } : {}),
+        };
+        return true;
+    }
     function hydrateEntry(entry) {
         const query = entry.query;
         const hydrationSerial = ++entry.hydrationSerial;
@@ -470,7 +607,8 @@ export function createGatewayResourceCache(options) {
             const readingStore = store;
             try {
                 const saved = query.persisted
-                    ? ((isRunListView(query) ? await storedRunListView(query, readingStore) : undefined) ??
+                    ? (takeStartupQuery(query) ??
+                        (isRunListView(query) ? await storedRunListView(query, readingStore) : undefined) ??
                         (await readingStore.getQuery(nativeHistoryStorageId(query))))
                     : undefined;
                 if (!disposed &&
@@ -480,17 +618,7 @@ export function createGatewayResourceCache(options) {
                     ownerVersion === hydrationOwnerVersion &&
                     entry.hydrationSerial === hydrationSerial &&
                     entry.state.status !== 'ready' &&
-                    saved &&
-                    saved.bytes <= query.maxBytes &&
-                    (query.method !== Methods.NATIVE_SESSION_READ ||
-                        storedNativeHistoryMatches(query.params, saved.data))) {
-                    const sourceObservation = query.sourceObservation?.(saved.data);
-                    entry.state = {
-                        status: 'stale',
-                        data: saved.data,
-                        observedAt: saved.observedAt,
-                        ...(sourceObservation ? { sourceObservation, error: sourceObservation.error } : {}),
-                    };
+                    applyStoredQuery(entry, saved)) {
                     notify(entry);
                 }
             }
@@ -521,6 +649,9 @@ export function createGatewayResourceCache(options) {
                 };
             await runListLoad.promise;
         }
+        return heldRunListView(query);
+    }
+    function heldRunListView(query) {
         const data = runList.view(query.params);
         return data && runList.observedAt !== undefined
             ? { id: query.id, data, observedAt: runList.observedAt, bytes: 0 }
@@ -623,7 +754,11 @@ export function createGatewayResourceCache(options) {
             const shared = entry.pending.prefetch;
             entry.pending.prefetch =
                 shared && prefetch
-                    ? { origin: 'prefetch', cohort: shared.cohort === 'gate' ? 'gate' : prefetch.cohort }
+                    ? {
+                        origin: 'prefetch',
+                        cohort: shared.cohort === 'gate' ? 'gate' : prefetch.cohort,
+                        maxStoredBytes: Math.min(shared.maxStoredBytes ?? Infinity, prefetch.maxStoredBytes ?? Infinity),
+                    }
                     : undefined;
             return entry.pending.promise;
         }
@@ -744,6 +879,7 @@ export function createGatewayResourceCache(options) {
                 const retention = entry.query.retention;
                 const saved = serialized !== undefined &&
                     bytes <= entry.query.maxBytes &&
+                    (entry.listeners.size > 0 || bytes <= (pending.prefetch?.maxStoredBytes ?? Infinity)) &&
                     (!retention || bytes <= retention.maxBytes)
                     ? {
                         id: nativeHistoryStorageId(entry.query),
@@ -816,7 +952,9 @@ export function createGatewayResourceCache(options) {
                                 (retention.cohort === 'upstream'
                                     ? isUpstreamStoredQuery(value.id)
                                     : value.id.startsWith(`${entry.query.method}:`)))
-                                .sort((a, b) => a.observedAt - b.observedAt ||
+                                .sort((a, b) => (entry.query.method === Methods.RUN_GET
+                                ? (a.accessedAt ?? a.observedAt) - (b.accessedAt ?? b.observedAt)
+                                : a.observedAt - b.observedAt) ||
                                 (entries.get(a.id)?.lastUsed ?? 0) - (entries.get(b.id)?.lastUsed ?? 0));
                             if (!current())
                                 return;
@@ -836,6 +974,14 @@ export function createGatewayResourceCache(options) {
                             await writingStore.putQuery(row);
                     });
                 }
+                if (store.persistent && entry.query.method === Methods.RUN_LIST) {
+                    const listed = reply.data;
+                    if (Array.isArray(listed.runs)) {
+                        for (const run of listed.runs)
+                            fallbackDetailTargets.set(run.id, runDetailTarget(run, runListVersion(run)));
+                    }
+                    refreshDetailTargets();
+                }
             }
             catch (error) {
                 if (disposed ||
@@ -962,14 +1108,25 @@ export function createGatewayResourceCache(options) {
         });
         return written;
     }
+    function contentWriteToken() {
+        return { connectionId: connection.id, ownerVersion: hydrationOwnerVersion, storeVersion };
+    }
     /** Stores verified bytes within the caps and the shared budget. */
-    function storeContent(input) {
+    async function storeContent(input) {
         const key = contentKey(input.key);
         const { data, origin, cohort } = input;
-        if (!resourceContentWithinLimits(key, data) ||
-            !verifyResourceContent(key, data, input.untrackedFiles))
-            return Promise.resolve(false);
-        return writeContent(input.token, async (target, current) => {
+        // Prefetch verifies between frames, so the write still answers to the owner it was asked under.
+        const token = input.token ?? contentWriteToken();
+        if (!resourceContentWithinLimits(key, data))
+            return false;
+        // Prefetch is background work; content a person opened is on their critical path and
+        // verifies at once, as before.
+        const verified = origin === 'prefetch'
+            ? await verifyResourceContentInSlices(key, data, input.untrackedFiles)
+            : verifyResourceContent(key, data, input.untrackedFiles);
+        if (!verified)
+            return false;
+        return writeContent(token, async (target, current) => {
             const accessedAt = Date.now();
             const content = await target.listContent();
             if (content.some((row) => row.kind === key.kind && row.id === key.id)) {
@@ -1019,6 +1176,13 @@ export function createGatewayResourceCache(options) {
             return true;
         });
     }
+    async function retryQuery(query, placement, signal) {
+        if (disposed)
+            throw new Error('Resource cache is disposed');
+        const entry = entryFor(query);
+        await fetchEntry(entry, false, placement, signal);
+        return entry.state;
+    }
     return {
         observedKey(match) {
             for (const entry of entries.values())
@@ -1071,7 +1235,7 @@ export function createGatewayResourceCache(options) {
                     notify(entry);
                 });
             }
-            receive(entry.state);
+            deliver(entry, receive);
             if (entry.state.status !== 'ready' || entry.dirty)
                 schedule(entry);
             return () => {
@@ -1091,13 +1255,21 @@ export function createGatewayResourceCache(options) {
                 throw new Error('Resource cache is disposed');
             return entryFor(query).state;
         },
-        async retry(query, placement, signal) {
+        async readStored(query, refresh = true) {
             if (disposed)
                 throw new Error('Resource cache is disposed');
+            const ownerVersion = hydrationOwnerVersion;
+            await barrier;
             const entry = entryFor(query);
-            await fetchEntry(entry, false, placement, signal);
+            await entry.hydration;
+            if (disposed || ownerVersion !== hydrationOwnerVersion)
+                throw new Error('The offline store owner changed');
+            // fetchEntry records network refusals in the query state and notifies its readers.
+            if (refresh && entry.state.data !== undefined)
+                void fetchEntry(entry);
             return entry.state;
         },
+        retry: retryQuery,
         async retryAfterPending(query) {
             if (disposed)
                 throw new Error('Resource cache is disposed');
@@ -1112,20 +1284,22 @@ export function createGatewayResourceCache(options) {
         readContent: (key) => readContentBytes((target) => target.getContent(contentKey(key)), false),
         runListProjections: () => runList.projections(),
         openContent: (key) => readContentBytes((target) => target.getContent(contentKey(key)), true),
+        async forgetContent(key) {
+            const target = store;
+            const ownerVersion = hydrationOwnerVersion;
+            await updateStore(target, () => target === store && !target.deleted && ownerVersion === hydrationOwnerVersion, () => target.deleteContent(contentKey(key)));
+        },
         readContentByAlias: (alias) => readContentBytes((target) => target.getContentByAlias(alias), false),
         openContentByAlias: (alias) => readContentBytes((target) => target.getContentByAlias(alias), true),
         storeContent,
         retainContent,
-        contentWriteToken: () => ({
-            connectionId: connection.id,
-            ownerVersion: hydrationOwnerVersion,
-            storeVersion,
-        }),
+        contentWriteToken,
         async dispose(reason) {
             if (disposed)
                 return;
             const withdrawing = collectors.close();
             disposed = true;
+            detailSync.reset();
             version++;
             unsubscribeChanges();
             unsubscribeConnection();