toolroll 0.9.47 → 0.9.48

package/dist/sqlite-telemetry.js

@@ -0,0 +1,98 @@
+const states = new WeakMap();
+/** One observation for the entire bounded BEGIN retry, including a failed acquisition. */
+export function measureWriteWait(db, body) {
+    const state = states.get(db);
+    if (!state || state.measuringWait)
+        return body();
+    const started = state.telemetry.clock();
+    state.measuringWait = true;
+    try {
+        return body();
+    }
+    finally {
+        state.measuringWait = false;
+        state.telemetry.writeWait.observe((state.telemetry.clock() - started) / 1000);
+    }
+}
+/** Preserve SQLite calls, timeouts and transaction semantics. No SQL or parameters leave this wrapper.
+ * Native SQLite does not expose busy-handler time for autocommit writes: report their whole duration separately.
+ * Runtime explicit IMMEDIATE/EXCLUSIVE transactions report acquisition and hold; startup migrations are excluded.
+ */
+export function instrumentDatabase(db, telemetry) {
+    const state = { telemetry, measuringWait: false };
+    let heldAt = null;
+    const elapsed = (at) => (telemetry.clock() - at) / 1000;
+    const operation = (sql) => sql.replace(/^(?:\s|--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)+/, '').trim();
+    const writing = (sql) => /^(?:INSERT|UPDATE|DELETE|REPLACE|CREATE|DROP|ALTER)\b/i.test(sql) || /^WITH\b[\s\S]*\b(?:INSERT|UPDATE|DELETE|REPLACE)\b/i.test(sql);
+    const standalone = (write, body) => {
+        if (!write || heldAt !== null)
+            return body();
+        const at = telemetry.clock();
+        try {
+            return body();
+        }
+        finally {
+            telemetry.writeStatement.observe(elapsed(at));
+        }
+    };
+    const finish = () => { if (heldAt !== null) {
+        telemetry.writeHold.observe(elapsed(heldAt));
+        heldAt = null;
+    } };
+    const methods = {
+        exec(sql) {
+            const op = operation(sql);
+            if (/^BEGIN\s+(?:IMMEDIATE|EXCLUSIVE)\b/i.test(op)) {
+                const at = telemetry.clock();
+                try {
+                    db.exec(sql);
+                    heldAt = telemetry.clock();
+                }
+                finally {
+                    if (!state.measuringWait)
+                        telemetry.writeWait.observe(elapsed(at));
+                }
+            }
+            else if (/^(?:COMMIT|END|ROLLBACK(?!\s+TO))\b/i.test(op)) {
+                db.exec(sql);
+                finish();
+            }
+            else
+                standalone(writing(op), () => db.exec(sql));
+        },
+        prepare(sql) {
+            const statement = db.prepare(sql), write = writing(operation(sql));
+            const methods = {
+                run: (...params) => standalone(write, () => statement.run(...params)),
+                get: (...params) => standalone(write, () => statement.get(...params)),
+                all: (...params) => standalone(write, () => statement.all(...params)),
+            };
+            return preservingNative(statement, methods);
+        },
+        close() { try {
+            db.close();
+        }
+        finally {
+            finish();
+        } },
+    };
+    // Store.handle also exposes native extensions (for example scalar functions used by work summaries).
+    // Preserve their receivers and getters instead of narrowing the live connection to the minimal test interface.
+    const wrapped = preservingNative(db, methods);
+    states.set(wrapped, state);
+    return wrapped;
+}
+function preservingNative(native, methods) {
+    // Overrides belong to the facade, so a test spy or caller replacing prepare/run never mutates the
+    // native method that the timed implementation calls (and cannot recurse back into itself).
+    return new Proxy(methods, {
+        get(target, property) {
+            if (Object.hasOwn(target, property))
+                return Reflect.get(target, property);
+            const value = Reflect.get(native, property, native);
+            return typeof value === 'function' ? value.bind(native) : value;
+        },
+        has: (target, property) => Reflect.has(target, property) || Reflect.has(native, property),
+        getPrototypeOf: () => Object.getPrototypeOf(native),
+    });
+}

package/dist/store.d.ts

@@ -1,3 +1,4 @@
+import { ServerTelemetry } from "./server-telemetry.js";
 import type { DecisionOption } from "./contracts/decision.js";
 import { type SavedToolAction, type SavedToolRule } from "./contracts/store-json.js";
 import type { FlowCardChange, FlowCardFields } from "./contracts/flow-card.js";
@@ -1939,6 +1940,7 @@ export declare class ReviewBindingError extends Error {
 }
 export declare class Store {
     #private;
+    readonly telemetry: ServerTelemetry;
     private readonly db;
     constructor(db: Database);
     /** TESTS ONLY: raw database access for migration fixtures. Production
@@ -2139,6 +2141,10 @@ export declare class Store {
      * themselves when called alone.
      */
     transact<T>(body: () => T): T;
+    private readonly commitListeners;
+    /** Hear each outer transact() commit (live-bus.ts). Listeners run synchronously
+     * after COMMIT and must not write; the return value stops listening. */
+    onCommit(listener: () => void): () => void;
     /**
      * A named SAVEPOINT for a multi-statement primitive that must roll back
      * WHOLESALE on a mid-body error, EVEN when nested inside an outer

package/dist/store.js

@@ -1,4 +1,6 @@
 import { chatSchema, chatTables } from "./contracts/chat-tables.js";
+import { ServerTelemetry } from "./server-telemetry.js";
+import { instrumentDatabase, measureWriteWait } from "./sqlite-telemetry.js";
 import { parseStoreColumn, readStoreColumn, readStoreStringifiedList, readStoreTextList } from "./contracts/store-json.js";
 import { assessmentFromSavedEvidence, verificationEvidence } from "./verification-evidence.js";
 import { LEARNING_SCHEMA, queueLearning } from "./project-learning.js";
@@ -3849,6 +3851,9 @@ export function isDatabaseBusy(error) {
  * wait, which is still counted in nominal sleep.
  */
 function beginWriteWithin(db, budgetMs) {
+    measureWriteWait(db, () => beginWriteAttempt(db, budgetMs));
+}
+function beginWriteAttempt(db, budgetMs) {
     const deadline = performance.now() + budgetMs;
     db.exec(`PRAGMA busy_timeout = ${WRITE_WAIT_SLICE_MS}`);
     try {
@@ -7349,9 +7354,11 @@ export class ReviewBindingError extends Error {
     constructor(message) { super(message); this.name = "ReviewBindingError"; }
 }
 export class Store {
+    telemetry;
     db;
     constructor(db) {
-        this.db = db;
+        this.telemetry = new ServerTelemetry();
+        this.db = instrumentDatabase(db, this.telemetry);
     }
     /** TESTS ONLY: raw database access for migration fixtures. Production
      * code never calls this — the typed methods are the API. */
@@ -7967,10 +7974,10 @@ export class Store {
             return body();
         beginWriteWithin(this.db, CONCURRENT_WRITER_WAIT_MS);
         this.transacting = true;
+        let result;
         try {
-            const result = body();
+            result = body();
             this.db.exec("COMMIT");
-            return result;
         }
         catch (error) {
             this.db.exec("ROLLBACK");
@@ -7979,6 +7986,21 @@ export class Store {
         finally {
             this.transacting = false;
         }
+        // Only after the outer COMMIT: a rolled-back or nested body tells no one.
+        for (const listener of this.commitListeners) {
+            try {
+                listener();
+            }
+            catch { /* a listener never fails the write */ }
+        }
+        return result;
+    }
+    commitListeners = new Set();
+    /** Hear each outer transact() commit (live-bus.ts). Listeners run synchronously
+     * after COMMIT and must not write; the return value stops listening. */
+    onCommit(listener) {
+        this.commitListeners.add(listener);
+        return () => { this.commitListeners.delete(listener); };
     }
     /**
      * A named SAVEPOINT for a multi-statement primitive that must roll back

package/dist/surface.js

@@ -129,6 +129,7 @@ const GUIDE_ROWS = [
     ...MODELS_DESCRIPTORS.map(spec => ({ invocation: `models ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "target", required: true, meaning: "the CLI to update, or on/off" }] } : {}) })),
     // ---- the queue (agent surface) ----
     { invocation: "status", synopsis: "running work, queued reasons, results to review, the latest release check and plan windows", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: 'health', synopsis: 'recent server latency, event-loop delay, SQLite writes and live streams from the saved connection; instance operators only', audience: 'agent', agentMayInvoke: true, mutation: 'none', flags: [jsonFlag, { name: 'profile', takesValue: true, meaning: 'saved server connection' }] },
     { invocation: "integrations", synopsis: "every integration as Connected, Not set up or Broken, with its last success and error, what uses it and what to do; --saved skips new checks; never a secret", audience: "agent", agentMayInvoke: true, mutation: "none",
         flags: [jsonFlag, dbFlag, { name: "saved", takesValue: false, meaning: "show the last checks without checking again" }] },
     { invocation: "ready", synopsis: "what could be dispatched right now (rows carry reservedFor)", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
@@ -446,7 +447,7 @@ const REMOTE_NO = [
     "conversation read", "conversation follow", "conversation stop",
     "session capabilities", "session list", "session show", "session changes", "session start", "session send", "session stop", "session resume", "session recover",
     // This machine's checkout, saved profile, credentials and catch-up.
-    "project show", "project use", "brief", "lead token", "lead say",
+    "project show", "project use", "brief", "lead token", "lead say", "health",
     "assignment show", "assignment updates", "assignment claim", "assignment check", "assignment brief", "assignment inbox", "assignment ack",
     // Workers, the loop and the services that run here.
     "claim", "heartbeat", "release", "reap", "tick", "build", "reconcile",

package/dist/task-live.d.ts

@@ -1,17 +1,8 @@
-import type { ServerResponse } from "node:http";
+import { type LiveRoomOptions, type LiveRooms, type LiveViewer } from "./live-bus.js";
 import { type Store } from "./store.js";
-export type TaskViewer = {
-    name: string;
-    response: ServerResponse;
-    valid: () => boolean;
-};
+export type TaskViewer = LiveViewer;
 /** What changes when anything on the task page changes: one read over the family, kept short and opaque. */
 export declare function taskFingerprint(store: Store, root: string, now: Date, livenessMs?: number): string | null;
-export type TaskRooms = {
-    /** Keep this page's stream on the task family until it closes; the first events say where it stands and who's here. */
-    join: (root: string, viewer: TaskViewer) => void;
-    /** Every stream, ended (the server is closing). */
-    close: () => void;
-    size: () => number;
-};
-export declare function createTaskRooms(fingerprint: (root: string) => string | null, tickMs?: number): TaskRooms;
+export type TaskRooms = LiveRooms<string, TaskViewer>;
+/** Rooms keyed by the task family's root. With a bus, a write reaches every open page at once; without one, only the safety net. */
+export declare function createTaskRooms(fingerprint: (root: string) => string | null, options?: LiveRoomOptions): TaskRooms;

package/dist/task-live.js

@@ -3,12 +3,14 @@
  * same in all of them, and each shows who else has it open. The same design
  * as the live canvas (flow-live.ts):
  *
- * - A change nudge. While anyone has a task open, one indexed read a second,
- *   keyed by the task family's root, takes the family's fingerprint (its
- *   versions' states, runs, decisions, progress checkpoints, what the agent
- *   did last, and whether each live run's worker still answers); when it
- *   changes, every open page hears "change" and reads the task again the
- *   usual way. The nudge carries no task data.
+ * - A change nudge. When the live bus says the workspace was written
+ *   (live-bus.ts), one indexed read keyed by the task family's root takes
+ *   the family's fingerprint (its versions' states, runs, decisions,
+ *   progress checkpoints, what the agent did last, and whether each live
+ *   run's worker still answers); when it changed, every open page hears
+ *   "change" and reads the task again the usual way. The nudge carries no
+ *   task data. With nothing written, an open page costs no reads; a
+ *   30-second check heals a missed signal (and notices a lapsed worker).
  * - Who's here. Everyone else with the task open, by name, one line per
  *   person however many pages they have. Memory only; it goes when the page
  *   closes or hides.
@@ -17,12 +19,9 @@
  * keep one open reads itself on its usual beat.
  */
 import { createHash } from "node:crypto";
+import { createLiveRooms } from "./live-bus.js";
 import { DEFAULT_LIVENESS_MS } from "./runner.js";
 import { BUILT_IN } from "./store.js";
-const TICK_MS = 1_000;
-const CHECK_EVERY = 15;
-const HEARTBEAT_EVERY = 15;
-const PRESENCE_SETTLE_MS = 150;
 /** What changes when anything on the task page changes: one read over the family, kept short and opaque. */
 export function taskFingerprint(store, root, now, livenessMs = DEFAULT_LIVENESS_MS) {
     const row = store.handle.prepare(`WITH RECURSIVE family(ref, ext, depth) AS (
@@ -41,104 +40,8 @@ export function taskFingerprint(store, root, now, livenessMs = DEFAULT_LIVENESS_
     WHERE EXISTS (SELECT 1 FROM family)`).get(root, new Date(now.getTime() - livenessMs).toISOString(), BUILT_IN);
     return row === undefined ? null : createHash("sha256").update(Object.values(row).map(String).join("|")).digest("hex").slice(0, 16);
 }
-export function createTaskRooms(fingerprint, tickMs = TICK_MS) {
-    const rooms = new Map();
-    const write = (viewer, event, data) => {
-        if (viewer.response.writableEnded || viewer.response.destroyed)
-            return;
-        viewer.response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
-    };
-    /** Everyone on the task but you, once each, by name. */
-    const others = (room, me) => [...new Set([...room.viewers].map(one => one.name).filter(name => name !== me))].sort((a, b) => a.localeCompare(b));
-    const announce = (room) => {
-        if (room.settling !== null)
-            clearTimeout(room.settling);
-        room.settling = setTimeout(() => {
-            room.settling = null;
-            for (const viewer of room.viewers)
-                write(viewer, "here", { people: others(room, viewer.name) });
-        }, PRESENCE_SETTLE_MS);
-        room.settling.unref();
-    };
-    const leave = (root, viewer) => {
-        const room = rooms.get(root);
-        if (room === undefined || !room.viewers.delete(viewer))
-            return;
-        if (!viewer.response.writableEnded)
-            viewer.response.end();
-        if (room.viewers.size > 0) {
-            announce(room);
-            return;
-        }
-        if (room.timer !== null)
-            clearInterval(room.timer);
-        if (room.settling !== null)
-            clearTimeout(room.settling);
-        rooms.delete(root);
-    };
-    const tick = (root, room) => {
-        room.ticks += 1;
-        if (room.ticks % CHECK_EVERY === 0) {
-            // A signed-out or narrowed account stops hearing about the task.
-            for (const viewer of [...room.viewers])
-                if (!viewer.valid()) {
-                    write(viewer, "gone", {});
-                    leave(root, viewer);
-                }
-            if (!rooms.has(root))
-                return;
-        }
-        let now;
-        try {
-            now = fingerprint(root);
-        }
-        catch {
-            return; /* a busy database: the next tick reads again */
-        }
-        if (now === null) {
-            for (const viewer of [...room.viewers]) {
-                write(viewer, "gone", {});
-                leave(root, viewer);
-            }
-            return;
-        }
-        if (now !== room.last) {
-            room.last = now;
-            for (const viewer of room.viewers)
-                write(viewer, "change", { at: now });
-        }
-        else if (room.ticks % HEARTBEAT_EVERY === 0) {
-            for (const viewer of room.viewers)
-                if (!viewer.response.writableEnded)
-                    viewer.response.write(": keep-alive\n\n");
-        }
-    };
-    return {
-        join(root, viewer) {
-            let room = rooms.get(root);
-            if (room === undefined) {
-                let last = null;
-                try {
-                    last = fingerprint(root);
-                }
-                catch { /* the first tick reads it */ }
-                room = { viewers: new Set(), last, timer: null, ticks: 0, settling: null };
-                const created = room;
-                room.timer = setInterval(() => tick(root, created), tickMs);
-                room.timer.unref();
-                rooms.set(root, room);
-            }
-            room.viewers.add(viewer);
-            write(viewer, "change", { at: room.last });
-            write(viewer, "here", { people: others(room, viewer.name) });
-            announce(room);
-            viewer.response.once("close", () => leave(root, viewer));
-        },
-        close() {
-            for (const [root, room] of [...rooms])
-                for (const viewer of [...room.viewers])
-                    leave(root, viewer);
-        },
-        size: () => [...rooms.values()].reduce((sum, room) => sum + room.viewers.size, 0),
-    };
+/** Rooms keyed by the task family's root. With a bus, a write reaches every open page at once; without one, only the safety net. */
+export function createTaskRooms(fingerprint, options = {}) {
+    // Everyone on the task but you, once each, by name.
+    return createLiveRooms(fingerprint, (viewers, me) => [...new Set(viewers.map(one => one.name).filter(name => name !== me))].sort((a, b) => a.localeCompare(b)), options);
 }

package/dist/work-index.js

@@ -242,6 +242,17 @@ const PROJECTION = `WITH RECURSIVE admitted AS MATERIALIZED (
   FROM claimed c LEFT JOIN action_ledger completed ON completed.id=c.checked_id WHERE ($state IS NULL OR c.state=$state) AND ($leadId IS NULL OR EXISTS(SELECT 1 FROM team_task_owner own WHERE own.task_ref=c.root_ref AND own.lead=$leadId))
 )`;
 const registered = new WeakMap();
+const statements = new WeakMap();
+/** The page query is long and has one text per view filter: compile each once per connection. */
+function prepared(store, sql) {
+    let cache = statements.get(store.handle);
+    if (cache === undefined)
+        statements.set(store.handle, cache = new Map());
+    let statement = cache.get(sql);
+    if (statement === undefined)
+        cache.set(sql, statement = store.handle.prepare(sql));
+    return statement;
+}
 /** Connection-local pure parsing, with exactly the authoritative stored-scope
  * validator. The callback cannot query, inspect files or grant authority. */
 function registerValidators(store) {
@@ -358,7 +369,7 @@ export function workIndexPage(store, now, access, options = {}) {
     const limit = Number.isFinite(options.limit) ? Math.max(1, Math.min(WORK_INDEX_MAX_LIMIT, Math.floor(options.limit))) : WORK_INDEX_PAGE_LIMIT;
     const scope = cursorScope(access, options, view), cursor = readCursor(options.cursor, scope);
     const filter = view === 'needs-you' ? 'needs=1' : view === 'running' ? 'family_running=1' : view === 'completed' ? "code='complete'" : '1';
-    const rows = store.handle.prepare(`${projection}, selected_page AS MATERIALIZED (
+    const rows = prepared(store, `${projection}, selected_page AS MATERIALIZED (
     SELECT * FROM ranked WHERE ${filter} AND ($cursorRoot=0 OR
       ${ORDER}>$cursorRank OR (${ORDER}=$cursorRank AND (sort_at<$cursorAt OR (sort_at=$cursorAt AND root_ref<$cursorRoot))))
     ORDER BY ${ORDER},sort_at DESC,root_ref DESC LIMIT $limit

package/dist/workspace-revision.d.ts

@@ -1,4 +1,6 @@
 import type { Store } from './store.js';
+/** The service_cursor row the revision triggers move (live-bus.ts listens for it). */
+export declare const WORKSPACE_REVISION_KEY = "workspace-content:v1";
 export type WorkspaceRevision = {
     current(): string;
     expiresAt(now: Date): number;

package/dist/workspace-revision.js

@@ -2,7 +2,9 @@
  * metadata only: it never grants access or certifies task/process state. */
 import { createHash } from 'node:crypto';
 import { DEFAULT_LIVENESS_MS } from './runner.js';
-const KEY = 'workspace-content:v1';
+/** The service_cursor row the revision triggers move (live-bus.ts listens for it). */
+export const WORKSPACE_REVISION_KEY = 'workspace-content:v1';
+const KEY = WORKSPACE_REVISION_KEY;
 const PREFIX = 'workspace_revision_v1_';
 const MAX_AGE_MS = 60_000;
 const OMIT = new Set(['schema_version', 'service_cursor', 'wake', 'notification_delivery',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.47",
+  "version": "0.9.48",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"