toolroll 0.9.47 → 0.9.48

package/dist/live-bus.js

@@ -0,0 +1,321 @@
+/**
+ * Live views push on write. Nothing here polls once a second.
+ *
+ * - The bus. The database's own revision triggers (workspace-revision.ts)
+ *   move one counter on every meaningful write. After each in-process
+ *   transact() COMMIT, and whenever another process (the worker, the CLI)
+ *   writes the database's write-ahead log, the revision is read once; when
+ *   it moved, every subscriber hears `{ revision }`. A rolled-back or quiet
+ *   write moves nothing and says nothing. A page left open with nothing
+ *   being written costs no database work at all.
+ * - The rooms. Each open task or flow is a room keyed by what it shows.
+ *   When the bus speaks, a room rechecks every viewer's access (a signed-out
+ *   or narrowed account is dropped), takes its fingerprint once, and only if
+ *   that moved tells its pages `change` with the fingerprint and revision —
+ *   an invalidation, never content. The page reads itself again under its
+ *   own checks, so redaction stays the page's.
+ * - The safety net. Every room also checks itself about every 30 s, so a
+ *   missed signal heals, and sends a keep-alive between.
+ * - Back-pressure. Each page's stream is bounded: a page that falls behind
+ *   gets one `reload` and ends so its EventSource can reconnect.
+ *
+ * Transport seam: a future WebSocket (live cursors) subscribes to the same
+ * LiveBus beside these SSE rooms; nothing in the Store or the triggers changes.
+ */
+import { watch } from "node:fs";
+import { WORKSPACE_REVISION_KEY } from "./workspace-revision.js";
+export function createLiveBus() {
+    const listeners = new Set();
+    let last = null;
+    return {
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        publish(change) {
+            last = change.revision;
+            for (const listener of [...listeners]) {
+                try {
+                    listener(change);
+                }
+                catch { /* one room never stops another */ }
+            }
+        },
+        revision: () => last,
+        listeners: () => listeners.size,
+    };
+}
+const SIGNAL = "toolroll_live_written";
+/**
+ * Publish the workspace revision when it moves: after this process commits,
+ * and when the database's write-ahead log changes under another process.
+ * Signals in one turn of the event loop coalesce into one read.
+ */
+export function followWorkspace(store, current, bus, options = {}) {
+    let last = null;
+    try {
+        last = current();
+    }
+    catch { /* the first signal reads it */ }
+    let scheduled = false, closed = false;
+    let timer = null;
+    const check = () => {
+        scheduled = false;
+        timer = null;
+        if (closed)
+            return;
+        // Never read inside an open transaction: what it wrote isn't committed yet.
+        if (store.handle.isTransaction === true) {
+            schedule(10);
+            return;
+        }
+        let now;
+        try {
+            now = current();
+        }
+        catch {
+            schedule(250);
+            return; /* busy: read again shortly */
+        }
+        if (now === last)
+            return;
+        last = now;
+        bus.publish({ revision: now });
+    };
+    const schedule = (delay = 0) => {
+        // With no page open, nobody needs the read.
+        if (scheduled || closed || bus.listeners() === 0)
+            return;
+        scheduled = true;
+        timer = setTimeout(check, delay);
+        timer.unref?.();
+    };
+    const unhook = store.onCommit(() => schedule());
+    // A write this process makes outside transact() (an autocommit statement)
+    // moves the revision too: a connection-local TEMP trigger on the revision
+    // row calls back here. Other processes never see it. The read waits for
+    // the statement's own commit, and a rollback leaves the revision unmoved.
+    let signalled = false;
+    const db = store.handle;
+    if (typeof db.function === "function") {
+        try {
+            db.function(SIGNAL, { deterministic: false }, () => { if (!closed)
+                schedule(); return null; });
+            db.exec(`CREATE TEMP TRIGGER IF NOT EXISTS ${SIGNAL}_update AFTER UPDATE ON main.service_cursor WHEN NEW.key = '${WORKSPACE_REVISION_KEY}' BEGIN SELECT ${SIGNAL}(); END;
+        CREATE TEMP TRIGGER IF NOT EXISTS ${SIGNAL}_insert AFTER INSERT ON main.service_cursor WHEN NEW.key = '${WORKSPACE_REVISION_KEY}' BEGIN SELECT ${SIGNAL}(); END;`);
+            signalled = true;
+        }
+        catch { /* commits and the safety net still reach the rooms */ }
+    }
+    const file = options.file ?? null;
+    let watcher = null;
+    if (file !== null) {
+        const start = options.watchFile ?? ((path, listener) => { try {
+            return watch(path, { persistent: false }, listener);
+        }
+        catch {
+            return null;
+        } });
+        // The worker and CLI write from their own processes; their commits land in the WAL.
+        watcher = start(`${file}-wal`, () => schedule());
+        watcher?.on?.("error", () => { watcher?.close(); watcher = null; });
+    }
+    return {
+        check,
+        close() {
+            closed = true;
+            if (timer !== null)
+                clearTimeout(timer);
+            unhook();
+            watcher?.close();
+            watcher = null;
+            if (signalled) {
+                try {
+                    db.exec(`DROP TRIGGER IF EXISTS temp.${SIGNAL}_update; DROP TRIGGER IF EXISTS temp.${SIGNAL}_insert;`);
+                }
+                catch { /* the database is closing */ }
+            }
+        },
+    };
+}
+/** About every 30 s a room checks itself; a keep-alive goes between. */
+export const SAFETY_NET_MS = 30_000;
+export const KEEP_ALIVE_MS = 15_000;
+/** What a page's stream may hold unsent before it is "behind". */
+export const STREAM_LIMIT_BYTES = 32 * 1024;
+/** One page's stream, bounded. Overflow is terminal, even below Node's drain threshold. */
+export class LiveStream {
+    response;
+    limit;
+    onOverflow;
+    ended = false;
+    constructor(response, limit = STREAM_LIMIT_BYTES, onOverflow = () => { }) {
+        this.response = response;
+        this.limit = limit;
+        this.onOverflow = onOverflow;
+    }
+    get open() { return !this.ended && !this.response.writableEnded && !this.response.destroyed; }
+    overflow() {
+        if (!this.open)
+            return;
+        this.ended = true;
+        // end(data) queues at most this final frame; it never waits for a drain
+        // that Node may not emit when our limit is below its high-water mark.
+        try {
+            this.response.end("event: reload\ndata: {}\n\n");
+        }
+        finally {
+            this.onOverflow();
+        }
+    }
+    write(frame) {
+        if (!this.open)
+            return;
+        if (this.response.writableLength > this.limit) {
+            this.overflow();
+            return;
+        }
+        this.response.write(frame);
+        if (this.response.writableLength > this.limit)
+            this.overflow();
+    }
+    send(event, data) {
+        this.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    }
+    keepAlive() {
+        this.write(": keep-alive\n\n");
+    }
+}
+const PRESENCE_SETTLE_MS = 150;
+/** Rooms of open pages that hear the bus. `presence` says who else is here, as each page should see it. */
+export function createLiveRooms(fingerprint, presence, options = {}) {
+    const bus = options.bus ?? null;
+    const keepAliveMs = options.keepAliveMs ?? KEEP_ALIVE_MS;
+    const checkEvery = Math.max(1, Math.round((options.safetyNetMs ?? SAFETY_NET_MS) / keepAliveMs));
+    const rooms = new Map();
+    let unsubscribe = null;
+    const here = (room, viewer) => presence([...room.viewers.keys()], viewer.name);
+    const announce = (room) => {
+        // A page that moves from one card to the next leaves and joins at once: say it once, after it settles.
+        if (room.settling !== null)
+            clearTimeout(room.settling);
+        room.settling = setTimeout(() => {
+            room.settling = null;
+            for (const [viewer, stream] of room.viewers)
+                stream.send("here", { people: here(room, viewer) });
+        }, PRESENCE_SETTLE_MS);
+        room.settling.unref();
+    };
+    const leave = (key, viewer) => {
+        const room = rooms.get(key);
+        if (room === undefined || !room.viewers.delete(viewer))
+            return;
+        if (!viewer.response.writableEnded)
+            viewer.response.end();
+        if (room.viewers.size > 0) {
+            announce(room);
+            return;
+        }
+        clearInterval(room.timer);
+        if (room.settling !== null)
+            clearTimeout(room.settling);
+        if (room.retry !== null)
+            clearTimeout(room.retry);
+        rooms.delete(key);
+        if (rooms.size === 0 && unsubscribe !== null) {
+            unsubscribe();
+            unsubscribe = null;
+        }
+    };
+    const drop = (key, viewer) => {
+        rooms.get(key)?.viewers.get(viewer)?.send("gone", {});
+        leave(key, viewer);
+    };
+    /** Recheck who may still see the room, then whether what it shows moved. */
+    const refresh = (key, room, revision) => {
+        // A signed-out or narrowed account stops hearing about it, at the first write after.
+        for (const viewer of [...room.viewers.keys()]) {
+            let ok = false;
+            try {
+                ok = viewer.valid();
+            }
+            catch {
+                ok = false;
+            }
+            if (!ok)
+                drop(key, viewer);
+        }
+        if (rooms.get(key) !== room)
+            return;
+        let now;
+        try {
+            now = fingerprint(key);
+        }
+        catch {
+            // A busy database: read again shortly rather than wait for the safety net.
+            if (room.retry === null) {
+                room.retry = setTimeout(() => { room.retry = null; if (rooms.get(key) === room)
+                    refresh(key, room, revision); }, 1_000);
+                room.retry.unref();
+            }
+            return;
+        }
+        if (now === null) {
+            for (const viewer of [...room.viewers.keys()])
+                drop(key, viewer);
+            return;
+        }
+        if (now === room.last)
+            return;
+        room.last = now;
+        for (const stream of room.viewers.values())
+            stream.send("change", { at: now, revision: revision ?? bus?.revision() ?? null });
+    };
+    const tick = (key, room) => {
+        room.ticks += 1;
+        if (room.ticks % checkEvery === 0) {
+            const before = room.last;
+            refresh(key, room, null);
+            if (rooms.get(key) === room && room.last !== before)
+                return;
+        }
+        for (const stream of room.viewers.values())
+            stream.keepAlive();
+    };
+    const heard = (change) => {
+        for (const [key, room] of [...rooms])
+            refresh(key, room, change.revision);
+    };
+    return {
+        join(key, viewer) {
+            let room = rooms.get(key);
+            if (room === undefined) {
+                let last = null;
+                try {
+                    last = fingerprint(key);
+                }
+                catch { /* the next signal or the safety net reads it */ }
+                const created = { viewers: new Map(), last, timer: setInterval(() => tick(key, created), keepAliveMs), ticks: 0, settling: null, retry: null };
+                created.timer.unref();
+                room = created;
+                rooms.set(key, room);
+                if (bus !== null && unsubscribe === null)
+                    unsubscribe = bus.subscribe(heard);
+            }
+            // Remove an overflowed page immediately, even while its final bytes
+            // wait for the client. Peers must not keep seeing stale presence.
+            const stream = new LiveStream(viewer.response, options.limitBytes, () => leave(key, viewer));
+            room.viewers.set(viewer, stream);
+            viewer.response.once("close", () => leave(key, viewer));
+            stream.send("change", { at: room.last, revision: bus?.revision() ?? null });
+            if (!stream.open)
+                return;
+            stream.send("here", { people: here(room, viewer) });
+            if (stream.open)
+                announce(room);
+        },
+        close() {
+            for (const [key, room] of [...rooms])
+                for (const viewer of [...room.viewers.keys()])
+                    leave(key, viewer);
+        },
+        size: () => [...rooms.values()].reduce((sum, room) => sum + room.viewers.size, 0),
+    };
+}

package/dist/metrics.d.ts

@@ -1,3 +1,6 @@
 import type { Store } from "./store.js";
+import { type ServerTelemetry } from "./server-telemetry.js";
 /** `repos`: the projects this console serves (null: all); task, run and worker figures count only theirs. */
 export declare function prometheusMetrics(store: Store, now: Date, repos?: readonly string[] | null, destinations?: ReadonlyMap<string, string>): string;
+/** Performance labels are fixed vocabularies only, independent of the store's project labels. */
+export declare function performanceMetrics(telemetry: ServerTelemetry): string;

package/dist/metrics.js

@@ -6,6 +6,7 @@
  */
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
+import { LATENCY_BUCKETS, QUEUE_BUCKETS, STREAM_FAMILIES } from "./server-telemetry.js";
 const label = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
 const line = (name, sample) => {
     const labels = Object.entries(sample.labels ?? {});
@@ -52,5 +53,56 @@ export function prometheusMetrics(store, now, repos = null, destinations) {
     add("toolroll_monitoring_last_ok_timestamp_seconds", "When a destination last took a delivery.", "gauge", status.filter(one => one.lastOkAt !== null).map(one => ({ labels: { destination: one.sink }, value: Math.floor(Date.parse(one.lastOkAt) / 1000) })));
     add("toolroll_worker_heartbeat_age_seconds", "Seconds since each project's worker last checked in.", "gauge", rows(`SELECT repo, MAX(heartbeat_at) AS at FROM watch_lease WHERE ${inProjects("repo")} GROUP BY repo`, ...scoped).map(row => ({ labels: { project: project(String(row["repo"])) }, value: Math.max(0, Math.round((now.getTime() - Date.parse(String(row["at"]))) / 1000)) })));
     add("toolroll_checkouts", "Build checkouts on disk, by state.", "gauge", rows(`SELECT CASE WHEN runner IS NOT NULL AND released_at IS NULL THEN 'leased' ELSE 'released' END AS state, COUNT(*) AS n FROM worktree WHERE ${inProjects("repo")} GROUP BY 1`, ...scoped).map(row => ({ labels: { state: String(row["state"]) }, value: Number(row["n"]) })));
-    return `${metrics.map(metric => [`# HELP ${metric.name} ${metric.help}`, `# TYPE ${metric.name} ${metric.type}`, ...metric.samples.map(sample => line(metric.name, sample))].join("\n")).join("\n")}\n`;
+    return `${metrics.map(metric => [`# HELP ${metric.name} ${metric.help}`, `# TYPE ${metric.name} ${metric.type}`, ...metric.samples.map(sample => line(metric.name, sample))].join("\n")).join("\n")}\n${performanceMetrics(store.telemetry)}`;
+}
+/** Performance labels are fixed vocabularies only, independent of the store's project labels. */
+export function performanceMetrics(telemetry) {
+    const out = [];
+    const header = (name, help, type) => out.push(`# HELP ${name} ${help}`, `# TYPE ${name} ${type}`);
+    const histogram = (name, value, labels = {}) => {
+        let cumulative = 0;
+        for (const [i, n] of value.total.bins.entries()) {
+            cumulative += n;
+            out.push(line(`${name}_bucket`, { labels: { ...labels, le: String(LATENCY_BUCKETS[i] ?? '+Inf') }, value: cumulative }));
+        }
+        out.push(line(`${name}_sum`, { labels, value: value.total.sum }), line(`${name}_count`, { labels, value: value.total.count }));
+    };
+    header('toolroll_http_request_duration_seconds', 'Request duration; SSE measures opening headers, not stream lifetime.', 'histogram');
+    for (const [route, value] of telemetry.routes)
+        histogram('toolroll_http_request_duration_seconds', value, { route });
+    for (const [name, help, value] of [
+        ['toolroll_sqlite_write_wait_seconds', 'Elapsed acquisition of an explicit write lock, including failed waits and all retry slices.', telemetry.writeWait],
+        ['toolroll_sqlite_write_hold_seconds', 'Time holding an explicit write transaction, through commit or rollback.', telemetry.writeHold],
+        ['toolroll_sqlite_write_statement_seconds', 'Standalone write duration, including native busy waits that SQLite cannot separate.', telemetry.writeStatement],
+    ]) {
+        header(name, help, 'histogram');
+        histogram(name, value);
+    }
+    const snapshot = telemetry.snapshot();
+    header('toolroll_event_loop_delay_seconds', 'Approximate event-loop delay over the last five minutes; 20 ms sampling interval.', 'gauge');
+    for (const [quantile, value] of [['0.5', snapshot.eventLoop.p50Ms], ['0.99', snapshot.eventLoop.p99Ms]]) {
+        if (value !== null)
+            out.push(line('toolroll_event_loop_delay_seconds', { labels: { quantile }, value: value / 1000 }));
+    }
+    header('toolroll_event_loop_delay_samples', 'Event-loop samples in the recent window; zero means no measurement yet.', 'gauge');
+    out.push(line('toolroll_event_loop_delay_samples', { value: snapshot.eventLoop.count }));
+    header('toolroll_sse_connections', 'Currently open live streams.', 'gauge');
+    for (const route of STREAM_FAMILIES)
+        out.push(line('toolroll_sse_connections', { labels: { route }, value: telemetry.streamQueues(route).length }));
+    header('toolroll_sse_queue_bytes', 'Bytes currently waiting to send across open streams.', 'gauge');
+    header('toolroll_sse_queue_max_bytes', 'Largest current per-stream send queue.', 'gauge');
+    header('toolroll_sse_queue_bytes_bucket', 'Current per-stream queue depth distribution, not a lifetime histogram; each stream contributes once.', 'gauge');
+    for (const route of STREAM_FAMILIES) {
+        const queues = telemetry.streamQueues(route);
+        out.push(line('toolroll_sse_queue_bytes', { labels: { route }, value: queues.reduce((sum, n) => sum + n, 0) }));
+        out.push(line('toolroll_sse_queue_max_bytes', { labels: { route }, value: queues.reduce((max, n) => Math.max(max, n), 0) }));
+        for (const bound of [...QUEUE_BUCKETS, Infinity])
+            out.push(line('toolroll_sse_queue_bytes_bucket', { labels: { route, le: Number.isFinite(bound) ? String(bound) : '+Inf' }, value: queues.filter(n => n <= bound).length }));
+    }
+    header('toolroll_request_budget_refusals_total', 'Requests refused by the shared CLI and MCP request budget, including unavailable budget checks.', 'counter');
+    for (const route of ['api', 'mcp'])
+        for (const reason of ['read-per-minute', 'act-per-minute', 'per-day', 'unavailable']) {
+            out.push(line('toolroll_request_budget_refusals_total', { labels: { route, reason }, value: telemetry.refusals.get(`${route}:${reason}`) ?? 0 }));
+        }
+    return `${out.join('\n')}\n`;
 }

package/dist/operate.js

@@ -181,6 +181,7 @@ import { WorktreePool } from "./worktree.js";
 import { requestTaskStop, resumeTaskStop, taskControlOf } from "./task-control.js";
 import { worktreeAdoptionNotice } from "./worktree-notices.js";
 import { workIndexPage, WorkIndexCursorError } from "./work-index.js";
+import { readExecutorOf } from "./read-executor.js";
 import { parseWorkView } from "./workspace-ui.js";
 import { taskWorkSummaryOf } from "./work-summary.js";
 import { assignmentOf, assignmentBrief, syncAssignmentHandoffs } from "./assignment.js";
@@ -10756,35 +10757,47 @@ function listTasks(flags, context) {
         !Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
         return fail(write, json, 'task list', 'usage', '--view takes all, needs-you, running or completed; --limit takes 1–100', EXIT.usage);
     }
-    let page;
-    try {
-        // A remote person limited to some projects (remoteLensOf) pages and counts only theirs.
-        const lens = context.principal?.lens ?? null;
-        page = workIndexPage(store, now, { principal: 'operator', repos: lens, includeUnplaced: lens === null }, {
-            view: parseWorkView(rawView ?? null), limit, cursor: text(flags, 'cursor') ?? null,
-            ...(wanted === undefined ? {} : { state: wanted }),
-            ...(text(flags, 'repo') === undefined ? {} : { project: text(flags, 'repo') }),
-        });
-    }
-    catch (error) {
+    // A remote person limited to some projects (remoteLensOf) pages and counts only theirs.
+    const lens = context.principal?.lens ?? null;
+    const access = { principal: 'operator', repos: lens, includeUnplaced: lens === null };
+    const options = {
+        view: parseWorkView(rawView ?? null), limit, cursor: text(flags, 'cursor') ?? null,
+        ...(wanted === undefined ? {} : { state: wanted }),
+        ...(text(flags, 'repo') === undefined ? {} : { project: text(flags, 'repo') }),
+    };
+    const refused = (error) => {
         if (!(error instanceof WorkIndexCursorError))
             throw error;
         return fail(write, json, 'task list', 'usage', 'Invalid page cursor. Start again without --cursor.', EXIT.usage);
-    }
-    const tasks = page.items.map(item => ({ ...item, id: item.rootId }));
-    if (json) {
-        write(envelopeJson({ ok: true, command: 'task list', count: tasks.length, tasks,
-            totals: page.totals, nextCursor: page.nextCursor, limit: page.limit, view: page.view, evidence: 'recorded' }));
+    };
+    const show = (page) => {
+        const tasks = page.items.map(item => ({ ...item, id: item.rootId }));
+        if (json) {
+            write(envelopeJson({ ok: true, command: 'task list', count: tasks.length, tasks,
+                totals: page.totals, nextCursor: page.nextCursor, limit: page.limit, view: page.view, evidence: 'recorded' }));
+            return EXIT.ok;
+        }
+        if (tasks.length === 0)
+            write(wanted === undefined ? 'The task list is empty.' : `Nothing is ${wanted}.`);
+        const width = Math.max(0, ...tasks.map(task => task.id.length));
+        for (const task of tasks)
+            write(`  ${task.id.padEnd(width)}  ${task.status.label.padEnd(16)}  ${task.title}`);
+        if (page.nextCursor !== null)
+            write(`Next page: --cursor ${page.nextCursor}`);
         return EXIT.ok;
+    };
+    // On the server, the same page is read on a worker's read-only connection so the request loop stays free.
+    const executor = readExecutorOf(store);
+    if (executor !== null)
+        return executor.workIndexPage(now, access, options).then(show, refused);
+    let page;
+    try {
+        page = workIndexPage(store, now, access, options);
     }
-    if (tasks.length === 0)
-        write(wanted === undefined ? 'The task list is empty.' : `Nothing is ${wanted}.`);
-    const width = Math.max(0, ...tasks.map(task => task.id.length));
-    for (const task of tasks)
-        write(`  ${task.id.padEnd(width)}  ${task.status.label.padEnd(16)}  ${task.title}`);
-    if (page.nextCursor !== null)
-        write(`Next page: --cursor ${page.nextCursor}`);
-    return EXIT.ok;
+    catch (error) {
+        return refused(error);
+    }
+    return show(page);
 }
 function showTask(positional, context) {
     const { store, write, json, now } = context;

package/dist/read-executor-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/read-executor-worker.js

@@ -0,0 +1,26 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { openStoreReadOnly } from './store.js';
+import { workIndexPage } from './work-index.js';
+/** One read-only, query-only connection per worker (read-executor.ts). Jobs arrive one at a time. */
+let store = null;
+function connection() {
+    if (store !== null)
+        return store;
+    const opened = openStoreReadOnly(String(workerData.file));
+    if (opened === null)
+        throw new Error('The read worker could not open the database read-only at the current schema.');
+    opened.handle.exec('PRAGMA query_only=1');
+    return store = opened;
+}
+parentPort.on('message', ({ id, job }) => {
+    let reply;
+    try {
+        if (job.kind !== 'work-index-page')
+            throw new Error('Unknown read.');
+        reply = { id, ok: true, value: workIndexPage(connection(), new Date(job.now), job.access, job.options) };
+    }
+    catch (error) {
+        reply = { id, ok: false, error: { name: error instanceof Error ? error.name : 'Error', message: error instanceof Error ? error.message : String(error) } };
+    }
+    parentPort.postMessage(reply);
+});

package/dist/read-executor.d.ts

@@ -0,0 +1,49 @@
+import type { Store } from './store.js';
+import { type WorkIndexOptions, type WorkIndexPage } from './work-index.js';
+import type { WorkSummaryAccess } from './work-summary.js';
+/**
+ * Heavy, read-only database work for the server, run on worker threads (docs/server-performance.md).
+ * Each worker owns one read-only, query-only connection to the server's own database file, so the
+ * measured hot read (the work index behind `task list`) never holds the HTTP event loop. Callers
+ * authorize first and send only the already-admitted access; a worker never widens it, writes, or
+ * retries. Without a file-backed database (tests, the demo) nothing is attached and callers keep
+ * running the same builder in-process.
+ */
+export type ReadJob = {
+    kind: 'work-index-page';
+    now: string;
+    access: WorkSummaryAccess;
+    options: WorkIndexOptions;
+};
+export type ReadReply = {
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: {
+        name: string;
+        message: string;
+    };
+};
+/** More queued reads than this fail at once instead of growing without bound. */
+export declare const READ_QUEUE_MAX = 1000;
+export declare class ReadExecutorError extends Error {
+    constructor(message: string);
+}
+export declare class ReadExecutor {
+    #private;
+    constructor(file: string, size?: number);
+    get size(): number;
+    /** workIndexPage(store, now, access, options) on a worker's read-only connection: same rows, same errors. */
+    workIndexPage(now: Date, access: WorkSummaryAccess, options: WorkIndexOptions): Promise<WorkIndexPage>;
+    /** Fails every queued and running read once, then stops the workers. */
+    close(): Promise<void>;
+}
+/** Half the cores, at most eight: the measured 20-engineer load needs over four (docs/server-performance.md),
+ * and the rest stay with the event loop and local agents. Workers start only when reads arrive. */
+export declare function defaultReadWorkers(): number;
+/** The server attaches its executor to its own Store; a command run on that Store reads through it. */
+export declare function attachReadExecutor(store: Store, executor: ReadExecutor): () => void;
+export declare function readExecutorOf(store: Store): ReadExecutor | null;