@farmslot/protocol 0.76.0 → 0.77.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ All notable changes to `@farmslot/protocol` are tracked here.
 
 - Active-development baseline; add user-facing changes here before release or package publication.
 
+## 0.77.0 - 2026-11-06
+
+- Add a family usage projection for shared session receipts, accounting contributions and review-round timing.
+- Measure shared RPC and offline cache performance, with authenticated diagnostics and action budgets.
+- Share context-configured display state across clients and expose bounded resident content previews for cached first paint.
+- Preserve structured missing-file errors through display reads.
+- Restore the Review History choice from shared links and retain it across native tab navigation.
+- Give current run reads a bounded two-minute window for publication-source and retained-evidence verification, so a slow read can refresh a ready gate.
+- Add shared pipeline session usage receipts with runner, model, effort, role, flow, identity, token splits, pricing status and duration, retained across relaunches and replays.
+- `run.extendReviewBudget` takes an optional `slotId`: the slot a failed run whose slot was released re-binds at the approved head.
+- Clarify that farm-wide worker discovery skips disconnected machines and pools with no enabled slots.
+- Retain watched check failure conclusions and CI fix scope refusals for operator decisions.
+- Allow the four scripted recovery behaviours in scenario configuration.
+- Declare bounded shared runtime claims and project recording capability metadata.
+- Record when a pending ticket refresh is superseded so its history survives a fresh admission.
+- Add opt-in ticket scope refresh and its person action history to publication package refresh.
+- Retain slotless review workspaces and exact reviewer conversations for a configurable project window, default seven days, so re-reviews resume the prior session on only the new diff. Expired storage is reclaimed safely and expiry is reported before a cold review.
+- Runs record `requestedSlotId`, the slot a caller or operator explicitly asked for, separately from the slot the engine placed them on.
+- Share bounded reconnect backoff, liveness probes and lifecycle/network recovery across Command Center and Companion.
+- Resume interrupted recovery without an identity from the client. Keep live owners and local work protected, and park unpublished commits retained by a terminal owner.
+- Open held review source without rereading it and batch missing source reads during prefetch.
+
 ## 0.76.0 - 2026-11-04
 
 - Define admin-person standalone session requester attribution, execution-target availability and real home metadata.

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":"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,CAu3CtB"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/client-cache/cache.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EACV,oBAAoB,EACpB,2BAA2B,EAM3B,kBAAkB,EAInB,MAAM,YAAY,CAAC;AAwDpB;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,SAAS,GAAG,OAAO,CAE1E;AA8CD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAoiDtB"}

package/dist/client-cache/cache.js

@@ -1,3 +1,4 @@
+import { afterForegroundPaint } from '../performance/paint.js';
 import { Methods } from '../rpc/registry.js';
 import { runListVersion } from '../runs/list-version.js';
 import { ResourceCollectorAdmission } from './collector-admission.js';
@@ -64,6 +65,36 @@ function profileId(connection) {
 }
 export function createGatewayResourceCache(options) {
     const transport = options.transport;
+    const metrics = options.performance ?? transport.performance;
+    const readContexts = new WeakMap();
+    const collectionIdentities = new Map();
+    function request(method, params, signal) {
+        const context = readContexts.get(signal);
+        let identity = context?.identity ?? collectionIdentities.get(method);
+        if (!identity) {
+            identity = {};
+            collectionIdentities.set(method, identity);
+        }
+        metrics?.reread(method, identity);
+        return transport.request(method, params, signal, context?.blocking ? 'interactive-read' : 'background-refresh');
+    }
+    function recordRead(entry, source, blocking) {
+        if (!metrics)
+            return;
+        const labels = { method: entry.query.method, cache_source: source };
+        metrics.increment('farmslot_client_cache_reads_total', labels);
+        if (entry.state.status === 'stale')
+            metrics.increment('farmslot_client_stale_reads_total', labels);
+        if (blocking)
+            metrics.increment('farmslot_client_blocking_reads_total', labels);
+        const age = entry.state.observedAt === undefined
+            ? undefined
+            : (Date.now() - entry.state.observedAt) / 1000;
+        if (age !== undefined && Number.isFinite(age) && age >= 0)
+            metrics.observe('farmslot_client_cache_age_seconds', labels, age);
+        else
+            metrics.increment('farmslot_client_unknown_age_total', labels);
+    }
     let store = options.store ?? createMemoryResourceStore();
     let metadata;
     let startupStore;
@@ -75,6 +106,35 @@ export function createGatewayResourceCache(options) {
     let version = 0;
     let storeVersion = 0;
     let hydrationOwnerVersion = 0;
+    // A bounded working set of the store's aliased bytes, for synchronous cached paint.
+    // Eviction and authority changes invalidate it with the durable rows.
+    const residentContent = new Map();
+    const residentLimit = Math.min(options.contentBudgetBytes ?? defaultContentBudgetBytes, 8 * 1024 * 1024);
+    let residentVersion = 0;
+    function forgetResident(key) {
+        residentVersion++;
+        for (const [alias, value] of residentContent)
+            if (value.key.kind === key.kind && value.key.id === key.id)
+                residentContent.delete(alias);
+    }
+    async function removeStoredContent(target, key) {
+        forgetResident(key);
+        await target.deleteContent(key);
+        forgetResident(key);
+    }
+    function rememberResident(alias, key, data) {
+        residentContent.delete(alias);
+        if (data.byteLength > residentLimit)
+            return;
+        residentContent.set(alias, { key, data: data.slice() });
+        let bytes = [...residentContent.values()].reduce((sum, value) => sum + value.data.byteLength, 0);
+        for (const [old, value] of residentContent) {
+            if (bytes <= residentLimit)
+                break;
+            residentContent.delete(old);
+            bytes -= value.data.byteLength;
+        }
+    }
     let lastUsed = 0;
     let storageNotice;
     let needsStore = options.store === undefined && options.openStore !== undefined;
@@ -89,7 +149,7 @@ export function createGatewayResourceCache(options) {
     let unsubscribeStore = store.onDeleted(storeDeleted);
     // Version lists: one shared run collection answers every run.list view.
     const runList = new RunListCollection({
-        request: (params, signal) => transport.request(Methods.RUN_LIST, params, signal),
+        request: (params, signal) => request(Methods.RUN_LIST, params, signal),
         persist: (merge) => {
             const writingStore = store;
             const incarnation = storeVersion;
@@ -142,6 +202,7 @@ export function createGatewayResourceCache(options) {
             return;
         usable = false;
         updateCollectors();
+        residentContent.clear();
         hydrationOwnerVersion++;
         version++;
         forgetRunList();
@@ -151,6 +212,7 @@ export function createGatewayResourceCache(options) {
     }
     function replaceStore(next) {
         unsubscribeStore();
+        residentContent.clear();
         store = next;
         storeVersion++;
         startupStore = undefined;
@@ -328,6 +390,27 @@ export function createGatewayResourceCache(options) {
                 if (saved.id !== RUN_LIST_COLLECTION_ID)
                     startupQueries.set(saved.id, saved);
             }
+            // Restore small aliased report bodies before exposing their cached run. Network
+            // prefetch can be queued behind other gates, even when these bytes are already held.
+            let contentRemaining = residentLimit;
+            const content = (await readingStore.listContent())
+                .filter((entry) => entry.kind === 'artifact' && entry.aliases?.length)
+                .sort((a, b) => b.accessedAt - a.accessedAt);
+            if (!current())
+                return;
+            for (const info of content) {
+                const aliasCount = info.aliases?.length ?? 0;
+                if (info.bytes * aliasCount > contentRemaining)
+                    continue;
+                const saved = await readingStore.getContent(info);
+                if (!current())
+                    return;
+                if (!saved || saved.data.byteLength * aliasCount > contentRemaining)
+                    continue;
+                contentRemaining -= saved.data.byteLength * aliasCount;
+                for (const name of info.aliases ?? [])
+                    rememberResident(name, saved, saved.data);
+            }
             if (rows)
                 runList.hydrate(rows);
             startupStore = readingStore;
@@ -378,6 +461,8 @@ export function createGatewayResourceCache(options) {
         // Stored facts belong to an owner, not a socket attempt. Fence a revoked
         // owner's pending I/O synchronously, before queued deletion can run.
         if (revoke || scopeChanged || authorityChanged) {
+            metrics?.resetScope();
+            residentContent.clear();
             hydrationOwnerVersion++;
             forgetRunList();
         }
@@ -421,6 +506,7 @@ export function createGatewayResourceCache(options) {
                 switchingProfile ||
                 ((next.connected || next.authority !== undefined) &&
                     (storedScopeChanged || storedAuthorityChanged))) {
+                residentContent.clear();
                 storeVersion++;
                 forgetRunList();
                 for (const entry of entries.values())
@@ -574,7 +660,7 @@ export function createGatewayResourceCache(options) {
         };
         entries.set(query.id, entry);
         const saved = isRunListView(query) ? heldRunListView(query) : takeStartupQuery(query);
-        if (applyStoredQuery(entry, saved)) {
+        if (applyStoredQuery(entry, saved, 'memory')) {
             entry.hydrated = true;
             queueMicrotask(prune);
         }
@@ -590,7 +676,7 @@ export function createGatewayResourceCache(options) {
         startupQueries.delete(id);
         return saved;
     }
-    function applyStoredQuery(entry, saved) {
+    function applyStoredQuery(entry, saved, origin = 'stored') {
         const query = entry.query;
         if (!saved ||
             !query.persisted ||
@@ -598,6 +684,7 @@ export function createGatewayResourceCache(options) {
             (query.method === Methods.NATIVE_SESSION_READ &&
                 !storedNativeHistoryMatches(query.params, saved.data)))
             return false;
+        entry.metricSource = origin;
         const sourceObservation = query.sourceObservation?.(saved.data);
         entry.state = {
             status: 'stale',
@@ -708,7 +795,7 @@ export function createGatewayResourceCache(options) {
                 observedAt: runList.observedAt,
             };
         // A view whose summaries the version reply cannot answer keeps its own full read.
-        return transport.request(Methods.RUN_LIST, params, signal);
+        return request(Methods.RUN_LIST, params, signal);
     }
     function stampCovers(entry, stamp) {
         if (!stamp ||
@@ -803,6 +890,10 @@ export function createGatewayResourceCache(options) {
             prefetch,
         };
         entry.pending = pending;
+        const refreshStarted = metrics?.clock();
+        const refreshEpoch = metrics?.epoch;
+        const blocking = entry.state.data === undefined;
+        readContexts.set(pending.controller.signal, { identity: entry, blocking });
         entry.dirty = false;
         entry.rereadFloor = undefined;
         const unknownGeneration = entry.unknownGeneration;
@@ -829,8 +920,8 @@ export function createGatewayResourceCache(options) {
                 const reply = fromRunList
                     ? await readRunListView(entry, pending.controller.signal)
                     : entry.query.method === Methods.NATIVE_SESSION_READ
-                        ? await readNativeHistory(entry.query.params, entry.state.data, (params, signal) => transport.request(Methods.NATIVE_SESSION_READ, params, signal), pending.controller.signal)
-                        : await transport.request(entry.query.method, entry.query.params, pending.controller.signal);
+                        ? await readNativeHistory(entry.query.params, entry.state.data, (params, signal) => request(Methods.NATIVE_SESSION_READ, params, signal), pending.controller.signal)
+                        : await request(entry.query.method, entry.query.params, pending.controller.signal);
                 if (disposed ||
                     store.deleted ||
                     pending.version !== version ||
@@ -859,6 +950,7 @@ export function createGatewayResourceCache(options) {
                     throw Object.assign(new Error(sourceObservation.error?.message ?? 'The gateway has not observed an upstream value.'), {
                         code: sourceObservation.error?.code ?? 'UPSTREAM_UNOBSERVED',
                     });
+                entry.metricSource = 'network';
                 entry.state = {
                     status: covered
                         ? sourceObservation && sourceObservation.status !== 'ready'
@@ -954,7 +1046,7 @@ export function createGatewayResourceCache(options) {
                                     return;
                             }
                             for (const key of victims.content) {
-                                await writingStore.deleteContent(key);
+                                await removeStoredContent(writingStore, key);
                                 if (!current())
                                     return;
                             }
@@ -1055,6 +1147,13 @@ export function createGatewayResourceCache(options) {
                 notify(entry);
             }
             finally {
+                if (metrics && refreshStarted !== undefined && metrics.epoch === refreshEpoch)
+                    metrics.observe(blocking
+                        ? 'farmslot_client_blocking_refresh_seconds'
+                        : 'farmslot_client_background_refresh_seconds', {
+                        method: entry.query.method,
+                        action_class: blocking ? 'interactive-read' : 'background-refresh',
+                    }, metrics.clock() - refreshStarted);
                 if (entry.pending === pending) {
                     entry.pending = undefined;
                     if (entry.dirty && entry.listeners.size && usable)
@@ -1103,6 +1202,25 @@ export function createGatewayResourceCache(options) {
             : undefined);
         return saved?.data;
     }
+    async function readAliasedContent(alias, open) {
+        const version = residentVersion;
+        const owner = hydrationOwnerVersion;
+        await barrier;
+        if (owner !== hydrationOwnerVersion || disposed)
+            return undefined;
+        const incarnation = storeVersion;
+        const saved = await readStoredContent((target) => target.getContentByAlias(alias), open
+            ? (target, { kind, id }) => target.touchContent({ kind, id }, Date.now(), 'opened')
+            : undefined);
+        if (version !== residentVersion ||
+            owner !== hydrationOwnerVersion ||
+            incarnation !== storeVersion ||
+            disposed)
+            return undefined;
+        if (saved)
+            rememberResident(alias, saved, saved.data);
+        return saved?.data;
+    }
     /** Content writes accept only the current connection's owner, from the token's fetch onward. */
     async function writeContent(token, write) {
         if (disposed || !connection.connected)
@@ -1162,7 +1280,7 @@ export function createGatewayResourceCache(options) {
                         return false;
                 }
                 for (const victim of victims.content) {
-                    await target.deleteContent(victim);
+                    await removeStoredContent(target, victim);
                     if (!current())
                         return false;
                 }
@@ -1175,8 +1293,11 @@ export function createGatewayResourceCache(options) {
                     accessedAt,
                 });
             }
-            if (input.alias !== undefined && current())
+            if (input.alias !== undefined && current()) {
                 await target.putContentAlias(input.alias, key);
+                if (current())
+                    rememberResident(input.alias, key, data);
+            }
             return true;
         });
     }
@@ -1210,8 +1331,38 @@ export function createGatewayResourceCache(options) {
         observe(query, listener) {
             if (disposed)
                 throw new Error('Resource cache is disposed');
+            const started = metrics?.clock();
+            const epoch = metrics?.epoch;
+            const alreadyHeld = entries.get(query.id)?.state.data !== undefined;
             const entry = entryFor(query);
-            const receive = (state) => listener(state);
+            const blocking = entry.state.data === undefined;
+            let first = true, active = true;
+            let cancelPaint;
+            const receive = (state) => {
+                listener(state);
+                if (state.data === undefined)
+                    return;
+                const source = alreadyHeld ? 'memory' : (entry.metricSource ?? 'unknown');
+                recordRead(entry, source, blocking && first);
+                if (!first || !metrics || started === undefined)
+                    return;
+                first = false;
+                if (connection.foreground === false)
+                    return;
+                cancelPaint = (options.afterPaint ?? afterForegroundPaint)(() => {
+                    if (!active || disposed || metrics.epoch !== epoch || connection.foreground === false)
+                        return;
+                    metrics.observe(source === 'network'
+                        ? 'farmslot_client_visible_read_seconds'
+                        : 'farmslot_client_cached_paint_seconds', {
+                        method: query.method,
+                        action_class: source === 'network' ? 'interactive-read' : 'cached-paint',
+                        cache_source: source,
+                    }, metrics.clock() - started);
+                });
+                if (!cancelPaint)
+                    metrics.increment('farmslot_client_unmeasured_paints_total', { method: query.method });
+            };
             entry.listeners.add(receive);
             updateCollectors();
             if (query.retention?.cohort === 'workspace') {
@@ -1256,6 +1407,8 @@ export function createGatewayResourceCache(options) {
             if (entry.state.status !== 'ready' || entry.dirty)
                 schedule(entry);
             return () => {
+                active = false;
+                cancelPaint?.();
                 entry.listeners.delete(receive);
                 updateCollectors();
                 if (!entry.listeners.size) {
@@ -1270,7 +1423,9 @@ export function createGatewayResourceCache(options) {
         read(query) {
             if (disposed)
                 throw new Error('Resource cache is disposed');
-            return entryFor(query).state;
+            const entry = entryFor(query);
+            recordRead(entry, 'memory', entry.state.data === undefined);
+            return entry.state;
         },
         async readStored(query, refresh = true) {
             if (disposed)
@@ -1302,20 +1457,25 @@ export function createGatewayResourceCache(options) {
         runListProjections: () => runList.projections(),
         openContent: (key) => readContentBytes((target) => target.getContent(contentKey(key)), true),
         async forgetContent(key) {
+            forgetResident(key);
             const target = store;
             const ownerVersion = hydrationOwnerVersion;
-            await updateStore(target, () => target === store && !target.deleted && ownerVersion === hydrationOwnerVersion, () => target.deleteContent(contentKey(key)));
+            await updateStore(target, () => target === store && !target.deleted && ownerVersion === hydrationOwnerVersion, () => removeStoredContent(target, contentKey(key)));
         },
-        readContentByAlias: (alias) => readContentBytes((target) => target.getContentByAlias(alias), false),
-        openContentByAlias: (alias) => readContentBytes((target) => target.getContentByAlias(alias), true),
+        peekContentByAlias: (alias) => residentContent.get(alias)?.data.slice(),
+        readContentByAlias: (alias) => readAliasedContent(alias, false),
+        openContentByAlias: (alias) => readAliasedContent(alias, true),
         storeContent,
         retainContent,
         contentWriteToken,
         async dispose(reason) {
+            if (reason && reason !== 'network' && reason !== 'background' && reason !== 'token-refresh')
+                metrics?.resetScope();
             if (disposed)
                 return;
             const withdrawing = collectors.close();
             disposed = true;
+            residentContent.clear();
             detailSync.reset();
             version++;
             unsubscribeChanges();