toolroll 0.9.47 → 0.9.49

package/dist/server-telemetry.d.ts

@@ -0,0 +1,86 @@
+import type { BudgetLimit } from './request-budget.js';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const TELEMETRY_WINDOW_MS = 300000;
+export declare const LATENCY_BUCKETS: number[];
+export declare const ROUTE_FAMILIES: readonly ['cli', 'mcp', 'team', 'team-stream', 'chat', 'chat-stream', 'flows', 'flow-stream', 'tasks', 'results', 'decisions', 'sessions', 'settings', 'projects', 'assets', 'auth', 'metrics', 'health', 'console', 'other'];
+export type RouteFamily = typeof ROUTE_FAMILIES[number];
+export type StreamFamily = 'team-stream' | 'chat-stream' | 'flow-stream' | 'other';
+export declare const STREAM_FAMILIES: readonly StreamFamily[];
+export declare const QUEUE_BUCKETS: number[];
+/** Only literals from the allowlist can become labels, including for unknown or malformed paths. */
+export declare function routeFamily(raw: string): RouteFamily;
+type Counts = {
+    bins: number[];
+    count: number;
+    sum: number;
+    max: number;
+};
+export type LatencySummary = {
+    count: number;
+    p50Ms: number | null;
+    p99Ms: number | null;
+    maxMs: number | null;
+    totalMs: number;
+};
+/** Lifetime histogram plus a ring of ten-second slices. Cost and memory do not grow with traffic. */
+export declare class TimingHistogram {
+    private readonly clock;
+    readonly total: Counts;
+    private readonly slices;
+    constructor(clock: () => number);
+    observe(seconds: number, weight?: number): void;
+    private prune;
+    recent(): LatencySummary;
+}
+export type HealthSnapshot = {
+    version: 1;
+    windowSeconds: number;
+    uptimeSeconds: number;
+    requests: LatencySummary;
+    routes: Partial<Record<RouteFamily, LatencySummary>>;
+    eventLoop: LatencySummary;
+    writes: {
+        wait: LatencySummary;
+        hold: LatencySummary;
+        statement: LatencySummary;
+    };
+    streams: {
+        open: number;
+        queuedBytes: number;
+        maxQueuedBytes: number;
+    };
+    budgetRefusals: number;
+};
+export declare class ServerTelemetry {
+    readonly clock: () => number;
+    readonly requests: TimingHistogram;
+    readonly routes: Map<"assets" | "auth" | "chat" | "chat-stream" | "cli" | "console" | "decisions" | "flow-stream" | "flows" | "health" | "mcp" | "metrics" | "other" | "projects" | "results" | "sessions" | "settings" | "tasks" | "team" | "team-stream", TimingHistogram>;
+    readonly eventLoop: TimingHistogram;
+    readonly writeWait: TimingHistogram;
+    readonly writeHold: TimingHistogram;
+    readonly writeStatement: TimingHistogram;
+    readonly refusals: Map<string, number>;
+    private readonly recentRefusals;
+    private readonly streams;
+    private monitor;
+    private timer;
+    private readonly started;
+    constructor(clock?: () => number);
+    start(): void;
+    stop(): void;
+    /**
+     * Native nanosecond samples, folded into bounded buckets once a second, never one retained object per tick.
+     * Each raw sample includes the sampling timer's own interval, so it is subtracted: an idle loop reads near zero.
+     */
+    sampleEventLoop(): void;
+    budgetRefused(route: 'api' | 'mcp', reason: BudgetLimit | 'unavailable'): void;
+    private pruneRefusals;
+    observeRequest(family: RouteFamily, milliseconds: number): void;
+    openStream(response: ServerResponse, family: StreamFamily): void;
+    streamQueues(family?: StreamFamily): number[];
+    snapshot(): HealthSnapshot;
+}
+/** SSE latency is time to opening headers; a live view's lifetime is not request work. */
+export declare function instrumentRequest(telemetry: ServerTelemetry, request: IncomingMessage, response: ServerResponse): void;
+export declare function healthWords(health: HealthSnapshot): string;
+export {};

package/dist/server-telemetry.js

@@ -0,0 +1,263 @@
+/** Bounded, in-memory performance measurements. Never retain URLs, SQL, or identities. */
+import { monitorEventLoopDelay } from 'node:perf_hooks';
+export const TELEMETRY_WINDOW_MS = 300_000;
+const SLICE_MS = 10_000;
+/** monitorEventLoopDelay samples by sleeping this long, so every raw sample includes it. */
+const EVENT_LOOP_RESOLUTION_MS = 20;
+export const LATENCY_BUCKETS = [0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01, 0.015, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 15, 30, 60];
+export const ROUTE_FAMILIES = ['cli', 'mcp', 'team', 'team-stream', 'chat', 'chat-stream', 'flows', 'flow-stream', 'tasks', 'results', 'decisions', 'sessions', 'settings', 'projects', 'assets', 'auth', 'metrics', 'health', 'console', 'other'];
+export const STREAM_FAMILIES = ['team-stream', 'chat-stream', 'flow-stream', 'other'];
+export const QUEUE_BUCKETS = [0, 1024, 4096, 16384, 65536, 262144, 1048576];
+/** Only literals from the allowlist can become labels, including for unknown or malformed paths. */
+export function routeFamily(raw) {
+    let path;
+    try {
+        path = new URL(raw, 'http://localhost').pathname;
+    }
+    catch {
+        return 'other';
+    }
+    if (path === '/api/cli')
+        return 'cli';
+    if (path === '/mcp' || path.startsWith('/mcp/'))
+        return 'mcp';
+    if (path === '/api/team/events')
+        return 'team-stream';
+    if (path === '/api/team')
+        return 'team';
+    if (path === '/chat/stream')
+        return 'chat-stream';
+    if (/^\/flows\/[^/]+\/live$/.test(path))
+        return 'flow-stream';
+    if (path === '/metrics')
+        return 'metrics';
+    if (path === '/health')
+        return 'health';
+    const first = path.split('/')[1];
+    switch (first) {
+        case 'chat':
+        case 'lead': return 'chat';
+        case 'flows':
+        case 'recipes': return 'flows';
+        case 't':
+        case 'tasks':
+        case 'queue': return 'tasks';
+        case 'r':
+        case 'runs':
+        case 'review': return 'results';
+        case 'd':
+        case 'i': return 'decisions';
+        case 'code':
+        case 'session': return 'sessions';
+        case 'settings':
+        case 'people':
+        case 'spend': return 'settings';
+        case 'projects': return 'projects';
+        case 'assets': return 'assets';
+        case 'login':
+        case 'logout':
+        case 'auth': return 'auth';
+        case '':
+        case 'work':
+        case 'inbox':
+        case 'board':
+        case 'fleet':
+        case 'menu':
+        case 'done': return 'console';
+        default: return 'other';
+    }
+}
+const counts = () => ({ bins: Array.from({ length: LATENCY_BUCKETS.length + 1 }, () => 0), count: 0, sum: 0, max: 0 });
+const summary = (value) => {
+    const percentile = (fraction) => {
+        if (value.count === 0)
+            return null;
+        const rank = Math.ceil(value.count * fraction);
+        let n = 0;
+        for (const [i, count] of value.bins.entries()) {
+            n += count;
+            if (n >= rank)
+                return Math.min(LATENCY_BUCKETS[i] ?? value.max, value.max) * 1000;
+        }
+        return value.max * 1000;
+    };
+    return { count: value.count, p50Ms: percentile(0.5), p99Ms: percentile(0.99), maxMs: value.count ? value.max * 1000 : null, totalMs: value.sum * 1000 };
+};
+/** Lifetime histogram plus a ring of ten-second slices. Cost and memory do not grow with traffic. */
+export class TimingHistogram {
+    clock;
+    total = counts();
+    slices = new Map();
+    constructor(clock) {
+        this.clock = clock;
+    }
+    observe(seconds, weight = 1) {
+        if (!Number.isFinite(seconds) || seconds < 0 || weight <= 0)
+            return;
+        const at = Math.floor(this.clock() / SLICE_MS);
+        this.prune(at);
+        let slice = this.slices.get(at);
+        if (!slice) {
+            slice = counts();
+            this.slices.set(at, slice);
+        }
+        let bin = LATENCY_BUCKETS.findIndex(bound => seconds <= bound);
+        if (bin < 0)
+            bin = LATENCY_BUCKETS.length;
+        for (const value of [this.total, slice]) {
+            value.bins[bin] += weight;
+            value.count += weight;
+            value.sum += seconds * weight;
+            value.max = Math.max(value.max, seconds);
+        }
+    }
+    prune(at) {
+        for (const key of this.slices.keys())
+            if (key <= at - TELEMETRY_WINDOW_MS / SLICE_MS)
+                this.slices.delete(key);
+    }
+    recent() {
+        this.prune(Math.floor(this.clock() / SLICE_MS));
+        const merged = counts();
+        for (const value of this.slices.values()) {
+            value.bins.forEach((n, i) => { merged.bins[i] += n; });
+            merged.count += value.count;
+            merged.sum += value.sum;
+            merged.max = Math.max(merged.max, value.max);
+        }
+        return summary(merged);
+    }
+}
+export class ServerTelemetry {
+    clock;
+    requests;
+    routes = new Map();
+    eventLoop;
+    writeWait;
+    writeHold;
+    writeStatement;
+    refusals = new Map();
+    recentRefusals = new Map();
+    streams = new Map();
+    monitor;
+    timer;
+    started;
+    constructor(clock = () => performance.now()) {
+        this.clock = clock;
+        this.started = clock();
+        this.requests = new TimingHistogram(clock);
+        this.eventLoop = new TimingHistogram(clock);
+        this.writeWait = new TimingHistogram(clock);
+        this.writeHold = new TimingHistogram(clock);
+        this.writeStatement = new TimingHistogram(clock);
+        for (const family of ROUTE_FAMILIES)
+            this.routes.set(family, new TimingHistogram(clock));
+    }
+    start() {
+        if (this.monitor)
+            return;
+        this.monitor = monitorEventLoopDelay({ resolution: EVENT_LOOP_RESOLUTION_MS });
+        this.monitor.enable();
+        this.timer = setInterval(() => this.sampleEventLoop(), 1000);
+        this.timer.unref();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.sampleEventLoop();
+        this.monitor?.disable();
+        this.monitor = undefined;
+        this.timer = undefined;
+    }
+    /**
+     * Native nanosecond samples, folded into bounded buckets once a second, never one retained object per tick.
+     * Each raw sample includes the sampling timer's own interval, so it is subtracted: an idle loop reads near zero.
+     */
+    sampleEventLoop() {
+        const h = this.monitor;
+        if (!h || !h.count)
+            return;
+        const count = h.count, steps = Math.min(count, 1000);
+        let previous = 0;
+        for (let i = 1; i <= steps; i++) {
+            const rank = Math.floor(i * count / steps);
+            this.eventLoop.observe(Math.max(0, h.percentile(100 * rank / count) / 1e6 - EVENT_LOOP_RESOLUTION_MS) / 1000, rank - previous);
+            previous = rank;
+        }
+        h.reset();
+    }
+    budgetRefused(route, reason) {
+        const key = `${route}:${reason}`;
+        this.refusals.set(key, (this.refusals.get(key) ?? 0) + 1);
+        const at = Math.floor(this.clock() / SLICE_MS);
+        this.pruneRefusals(at);
+        this.recentRefusals.set(at, (this.recentRefusals.get(at) ?? 0) + 1);
+    }
+    pruneRefusals(at) {
+        for (const key of this.recentRefusals.keys())
+            if (key <= at - TELEMETRY_WINDOW_MS / SLICE_MS)
+                this.recentRefusals.delete(key);
+    }
+    observeRequest(family, milliseconds) {
+        this.requests.observe(milliseconds / 1000);
+        this.routes.get(family).observe(milliseconds / 1000);
+    }
+    openStream(response, family) {
+        this.streams.set(response, family);
+        const closed = () => this.streams.delete(response);
+        response.once('close', closed);
+        response.once('finish', closed);
+    }
+    streamQueues(family) {
+        return [...this.streams].filter(([response, kind]) => !response.destroyed && !response.writableEnded && (family === undefined || family === kind)).map(([response]) => response.writableLength);
+    }
+    snapshot() {
+        this.sampleEventLoop();
+        this.pruneRefusals(Math.floor(this.clock() / SLICE_MS));
+        const queues = this.streamQueues();
+        return {
+            version: 1, windowSeconds: TELEMETRY_WINDOW_MS / 1000, uptimeSeconds: (this.clock() - this.started) / 1000,
+            requests: this.requests.recent(), routes: Object.fromEntries([...this.routes].map(([route, histogram]) => [route, histogram.recent()]).filter(([, value]) => value.count > 0)),
+            eventLoop: this.eventLoop.recent(), writes: { wait: this.writeWait.recent(), hold: this.writeHold.recent(), statement: this.writeStatement.recent() },
+            streams: { open: queues.length, queuedBytes: queues.reduce((sum, bytes) => sum + bytes, 0), maxQueuedBytes: queues.reduce((max, bytes) => Math.max(max, bytes), 0) },
+            budgetRefusals: [...this.recentRefusals.values()].reduce((sum, n) => sum + n, 0),
+        };
+    }
+}
+/** SSE latency is time to opening headers; a live view's lifetime is not request work. */
+export function instrumentRequest(telemetry, request, response) {
+    const family = routeFamily(request.url ?? '/'), started = telemetry.clock();
+    let recorded = false;
+    const record = () => { if (!recorded) {
+        recorded = true;
+        telemetry.observeRequest(family, telemetry.clock() - started);
+    } };
+    const writeHead = response.writeHead;
+    response.writeHead = function (...args) {
+        const result = Reflect.apply(writeHead, this, args);
+        const headers = typeof args[1] === 'object' ? args[1] : args[2];
+        const contentType = this.getHeader('content-type') ?? (headers && !Array.isArray(headers) ? Object.entries(headers).find(([name]) => name.toLowerCase() === 'content-type')?.[1] : undefined);
+        if (String(contentType).startsWith('text/event-stream') && !recorded) {
+            record();
+            telemetry.openStream(this, STREAM_FAMILIES.includes(family) ? family : 'other');
+        }
+        return result;
+    };
+    response.once('finish', record);
+    response.once('close', record);
+}
+export function healthWords(health) {
+    const ms = (n) => n === null ? 'no samples' : `${n.toFixed(2)} ms`;
+    const timing = (value) => value.count ? `p50 ${ms(value.p50Ms)}, p99 ${ms(value.p99Ms)} (${value.count} samples)` : 'no samples yet';
+    return [
+        `Server health — last 5 minutes (up ${Math.floor(health.uptimeSeconds)} seconds; approximate percentiles)`,
+        `Requests: ${timing(health.requests)}.`,
+        ...Object.entries(health.routes).map(([route, value]) => `  ${route}: ${timing(value)}.`),
+        `Event-loop delay: ${timing(health.eventLoop)}; 20 ms sampling interval.`,
+        `SQLite write-lock waits: ${timing(health.writes.wait)}.`,
+        `SQLite time holding a write transaction: ${timing(health.writes.hold)}.`,
+        `SQLite standalone writes, including lock waits: ${timing(health.writes.statement)}.`,
+        `Live streams: ${health.streams.open} open; ${health.streams.queuedBytes} bytes waiting to send, largest queue ${health.streams.maxQueuedBytes} bytes.`,
+        `Request-budget refusals: ${health.budgetRefusals}.`,
+    ].join('\n');
+}

package/dist/session-http.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type SessionOperation, type SessionRequests, type SessionResponse } from './session-contract.js';
+import { type Admission } from './request-budget.js';
 export type SessionHttpActor = {
     name: string;
     generation: number;
@@ -13,6 +14,10 @@ export type SessionHttpOptions = {
     /** The existing live owner's operation. Null means no owner is ready.
      * The service rechecks actor generation and project access at execution. */
     execute: SessionHttpExecute | null;
+    /** The bearer request's budget by source (request-budget.ts): charged once, before the credential is checked or a body read. */
+    admit?: (request: IncomingMessage) => Admission;
+    /** Account admission after successful authentication, before any body read or owner call. */
+    admitAuthenticated?: (request: IncomingMessage, actor: SessionHttpActor) => Admission;
 };
 /** Handle this API family before the browser's form parser or login redirects.
  * This adapter dispatches at most once. It owns no catalog, database or provider. */

package/dist/session-http.js

@@ -1,4 +1,5 @@
 import { SESSION_REQUEST_BYTES, SESSION_RESPONSE_BYTES, isSessionResponse, sessionDescriptor, validateSessionRequest, } from './session-contract.js';
+import { limitWords } from './request-budget.js';
 function readBody(request) {
     return new Promise(resolve => {
         let size = 0;
@@ -99,6 +100,16 @@ export async function handleSessionHttp(request, response, options) {
     if (authorizationCount !== 1 || !/^Bearer (.+):(.+)$/.test(request.headers.authorization ?? '')) {
         return reject(401, 'unauthenticated', 'Current operator bearer credentials are required.');
     }
+    const refuseAdmission = (admitted) => {
+        if (admitted.ok)
+            return false;
+        if (admitted.status === 503)
+            return reject(503, 'limits-unavailable', 'Request limits could not be checked; nothing ran. Try again shortly.');
+        response.setHeader('retry-after', String(admitted.retryAfter));
+        return reject(429, 'rate-limited', limitWords(admitted.limit, admitted.retryAfter));
+    };
+    if (options.admit && refuseAdmission(options.admit(request)))
+        return true;
     let actor;
     try {
         actor = await options.authenticate(request);
@@ -109,6 +120,8 @@ export async function handleSessionHttp(request, response, options) {
     if (actor === null || typeof actor.name !== 'string' || !actor.name.trim() || !Number.isSafeInteger(actor.generation) || actor.generation < 1) {
         return reject(401, 'unauthenticated', 'Current operator bearer credentials are required.');
     }
+    if (options.admitAuthenticated && refuseAdmission(options.admitAuthenticated(request, actor)))
+        return true;
     const media = request.headers['content-type']?.split(';')[0]?.trim().toLowerCase();
     if (media !== 'application/json')
         return reject(415, 'unsupported-media-type', 'Send the session request as application/json.');

package/dist/session-server.d.ts

@@ -1,6 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Store } from './store.js';
 import type { CodingWorkspace } from './coding-workspace.js';
+import { type SessionHttpActor } from './session-http.js';
+import type { Admission } from './request-budget.js';
 /** Bind the transport to createDecisionServer's existing catalog owner and
  * live project admission. No cookie, coordinator token or caller-supplied actor
  * can acquire installation-wide native coding authority through this adapter. */
@@ -9,4 +11,7 @@ export declare function createSessionEndpoint(options: {
     workspace: CodingWorkspace | null;
     projects: () => readonly string[];
     projectAllowed: (repo: string) => boolean;
+    /** The request's source budget (request-budget.ts), charged once before the password is checked. */
+    admit?: (request: IncomingMessage) => Admission;
+    admitAuthenticated?: (request: IncomingMessage, actor: SessionHttpActor) => Admission;
 }): (request: IncomingMessage, response: ServerResponse) => Promise<boolean>;

package/dist/session-server.js

@@ -21,6 +21,8 @@ export function createSessionEndpoint(options) {
         },
     });
     return (request, response) => handleSessionHttp(request, response, {
+        ...(options.admit === undefined ? {} : { admit: options.admit }),
+        ...(options.admitAuthenticated === undefined ? {} : { admitAuthenticated: options.admitAuthenticated }),
         authenticate: request => {
             const bearer = /^Bearer (.+):(.+)$/.exec(request.headers.authorization ?? '');
             if (!bearer)

package/dist/sqlite-telemetry.d.ts

@@ -0,0 +1,9 @@
+import type { Database } from './store.js';
+import type { ServerTelemetry } from './server-telemetry.js';
+/** One observation for the entire bounded BEGIN retry, including a failed acquisition. */
+export declare function measureWriteWait<T>(db: Database, body: () => T): T;
+/** 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 declare function instrumentDatabase(db: Database, telemetry: ServerTelemetry): Database;

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",