toolroll 0.9.46 → 0.9.48

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/setup-guide.d.ts

@@ -15,10 +15,10 @@ export declare function detectPreparation(repo: string): {
 } | null;
 /** Browser installation may write only this known file inside its project. */
 export declare function previewProjectInstructions(repo: string): {
+    content?: never;
     ok: false;
     message: string;
     plan?: never;
-    content?: never;
     fingerprint?: never;
     installed?: never;
 } | {
@@ -30,10 +30,10 @@ export declare function previewProjectInstructions(repo: string): {
     installed: boolean;
 };
 export declare function addProjectInstructions(repo: string, fingerprint: string): {
+    content?: never;
     ok: false;
     message: string;
     plan?: never;
-    content?: never;
     fingerprint?: never;
     installed?: never;
 } | import("./skills.js").InstallResult;

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,7 +1,9 @@
+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";
 import { type Actor } from "./actor.js";
+import { type LiveActivityKind } from "./live.js";
 import { type TokenPurpose } from "./api-tokens.js";
 import { type CriterionMatrixRow, type CriterionJudgementWord } from "./proof.js";
 import { type ExecutionProfile, type ChainEntry, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
@@ -69,6 +71,10 @@ export declare const FLOW_SEND_SCHEMA = "\nCREATE TABLE IF NOT EXISTS flow_send
 /** An owner's lasting choice to approve plans and merges from their paired chat (chat-approval.ts), for all their
  * projects (scope '*') or one (its path), with the limits they agreed to. Off unless a row says on; a project's own row
  * outranks the all-projects one. `generation` is the account's at the change: a reset password ends it. */
+/** What a running agent did last (live tasks): one row per run, a fixed kind from live.ts's
+ * vocabulary and when — never text, tool names or arguments. Display state, not evidence;
+ * a finished run's row goes with the live log's own retention (sweepRunActivity). */
+export declare const RUN_ACTIVITY_SCHEMA = "\nCREATE TABLE IF NOT EXISTS run_activity (\n  run  INTEGER PRIMARY KEY REFERENCES run(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL CHECK (kind IN ('session','message','edit','command','read','search','lookup','plan','delegate','tool')),\n  at   TEXT NOT NULL\n);\n";
 export declare const CHAT_APPROVAL_SCHEMA = "\nCREATE TABLE IF NOT EXISTS chat_approval_setting (\n  approver             TEXT NOT NULL,\n  scope                TEXT NOT NULL,\n  enabled              INTEGER NOT NULL CHECK (enabled IN (0,1)),\n  full_access          INTEGER NOT NULL DEFAULT 0 CHECK (full_access IN (0,1)),\n  attempt_cap_microusd INTEGER CHECK (attempt_cap_microusd IS NULL OR attempt_cap_microusd >= 0),\n  generation           INTEGER NOT NULL,\n  digest               TEXT NOT NULL,\n  updated_by           TEXT NOT NULL,\n  updated_at           TEXT NOT NULL,\n  PRIMARY KEY (approver, scope)\n);\n";
 /** The second tap on a flow decision in Telegram (telegram-flow.ts): Approve arms Yes and Cancel, bound to the binding,
  * chat, message and exact visit of the card; Yes decides it once. */
@@ -1934,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
@@ -2134,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
@@ -5601,6 +5612,17 @@ export declare class Store {
      * page and focused chat render live, including once the run that wrote
      * it has ended. */
     latestCheckpointForTask(taskRef: number): RunCheckpoint | null;
+    /** What the agent did last on this run (live tasks): one fixed kind and when, replacing the last. */
+    recordRunActivity(run: number, kind: LiveActivityKind, now: Date): void;
+    /** A run's last recorded activity and its newest progress checkpoint's time, in one read. */
+    runActivity(run: number): {
+        kind: LiveActivityKind | null;
+        at: string | null;
+        progressAt: string | null;
+    };
+    /** The live log's own retention: a finished run's activity goes once older than `retainMs`, and beyond the newest
+     * `bound` finished runs; a live run's always stays. */
+    sweepRunActivity(now: Date, retainMs: number, bound: number): number;
     /** One run's full checkpoint history, oldest first. */
     checkpointHistory(run: number): RunCheckpoint[];
     /** The newest scout run's report for a task (v34), when one exists. */

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";
@@ -12,6 +14,7 @@ import { cardOutputsForStore, cardOutputsFromStore } from "./contracts/stage-out
 import { chatControlHref, chatResultHref } from "./chat-controls.js";
 import { actorLabel, currentActor, leadSecretMatches, mintLeadToken, parseLeadToken } from "./actor.js";
 import { scanForSecrets } from "./evidence.js";
+import { LIVE_ACTIVITY_KINDS } from "./live.js";
 import { tokenPurpose, tokenRotationProblem } from "./api-tokens.js";
 /**
  * The database: a small task store, and the operational overlay beside it.
@@ -359,6 +362,16 @@ CREATE INDEX IF NOT EXISTS telegram_flow_choice_visit ON telegram_flow_choice (c
 /** An owner's lasting choice to approve plans and merges from their paired chat (chat-approval.ts), for all their
  * projects (scope '*') or one (its path), with the limits they agreed to. Off unless a row says on; a project's own row
  * outranks the all-projects one. `generation` is the account's at the change: a reset password ends it. */
+/** What a running agent did last (live tasks): one row per run, a fixed kind from live.ts's
+ * vocabulary and when — never text, tool names or arguments. Display state, not evidence;
+ * a finished run's row goes with the live log's own retention (sweepRunActivity). */
+export const RUN_ACTIVITY_SCHEMA = `
+CREATE TABLE IF NOT EXISTS run_activity (
+  run  INTEGER PRIMARY KEY REFERENCES run(id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK (kind IN ('session','message','edit','command','read','search','lookup','plan','delegate','tool')),
+  at   TEXT NOT NULL
+);
+`;
 export const CHAT_APPROVAL_SCHEMA = `
 CREATE TABLE IF NOT EXISTS chat_approval_setting (
   approver             TEXT NOT NULL,
@@ -3838,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 {
@@ -4090,6 +4106,8 @@ function initializeStore(db, file) {
     db.exec(CHAT_DECIDE_SCHEMA);
     // An owner's lasting chat-approval setting (no version bump: additive only; absent means off).
     db.exec(CHAT_APPROVAL_SCHEMA);
+    // What a running agent did last (no version bump: additive only; absent means no word yet).
+    db.exec(RUN_ACTIVITY_SCHEMA);
     db.exec(TELEGRAM_FLOW_CONFIRM_SCHEMA);
     // A flow's "Send to me" and "Person chooses" zones (no version bump: additive only).
     db.exec(FLOW_SEND_SCHEMA);
@@ -7336,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. */
@@ -7954,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");
@@ -7966,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
@@ -17523,6 +17558,27 @@ export class Store {
         const row = this.db.prepare("SELECT * FROM run_checkpoint WHERE task_ref = ? ORDER BY id DESC LIMIT 1").get(taskRef);
         return row === undefined ? null : readRunCheckpoint(row);
     }
+    /** What the agent did last on this run (live tasks): one fixed kind and when, replacing the last. */
+    recordRunActivity(run, kind, now) {
+        this.db.prepare("INSERT INTO run_activity (run, kind, at) VALUES (?, ?, ?) ON CONFLICT (run) DO UPDATE SET kind = excluded.kind, at = excluded.at")
+            .run(run, kind, now.toISOString());
+    }
+    /** A run's last recorded activity and its newest progress checkpoint's time, in one read. */
+    runActivity(run) {
+        const row = this.db.prepare(`SELECT (SELECT kind FROM run_activity WHERE run = ?1) AS kind, (SELECT at FROM run_activity WHERE run = ?1) AS at,
+      (SELECT created_at FROM run_checkpoint WHERE run = ?1 ORDER BY id DESC LIMIT 1) AS progress_at`).get(run);
+        const kind = typeof row["kind"] === "string" && LIVE_ACTIVITY_KINDS.includes(row["kind"]) ? row["kind"] : null;
+        return { kind, at: kind === null ? null : String(row["at"]), progressAt: row["progress_at"] == null ? null : String(row["progress_at"]) };
+    }
+    /** The live log's own retention: a finished run's activity goes once older than `retainMs`, and beyond the newest
+     * `bound` finished runs; a live run's always stays. */
+    sweepRunActivity(now, retainMs, bound) {
+        const finished = "run IN (SELECT id FROM run WHERE outcome IS NOT NULL)";
+        const aged = this.db.prepare(`DELETE FROM run_activity WHERE at < ? AND ${finished}`).run(new Date(now.getTime() - retainMs).toISOString()).changes;
+        const over = this.db.prepare(`DELETE FROM run_activity WHERE ${finished} AND run NOT IN (SELECT run FROM run_activity WHERE ${finished} ORDER BY at DESC, run DESC LIMIT ?)`)
+            .run(Math.max(0, Math.floor(bound))).changes;
+        return Number(aged) + Number(over);
+    }
     /** One run's full checkpoint history, oldest first. */
     checkpointHistory(run) {
         return this.db.prepare("SELECT * FROM run_checkpoint WHERE run = ? ORDER BY id ASC").all(run).map(readRunCheckpoint);

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-activity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a running agent did last, recorded and read (live tasks).
+ *
+ * The recorder sits beside the live log on the agent's stream and keeps one
+ * row per run: a fixed kind from live.ts's vocabulary and when. No text, no
+ * tool names, no arguments are ever kept, so nothing here can leak a secret.
+ * The reader picks the newer of that row and the run's latest progress
+ * checkpoint, and asks the runner's heartbeat whether the worker still
+ * answers. Neither side reads or stats a live-log file.
+ */
+import { type RunActivity } from "./activity-line.js";
+import type { Store } from "./store.js";
+type Observer = {
+    observe(event: Record<string, unknown>): void;
+    close(): void;
+};
+/** Watch a run's stream for what the agent does, alongside its live log (which may be null). Fail-soft: a write
+ * that fails never touches the run. */
+export declare function withRunActivity(liveLog: Observer | null, store: Pick<Store, "recordRunActivity">, run: number, clock: () => Date): Observer;
+/** A live run's last activity: the newer of its recorded kind and its latest progress checkpoint, else when it
+ * started; and "offline" only when its registered worker's heartbeat has lapsed. */
+export declare function runActivityOf(store: Store, run: {
+    id: number;
+    runner: string;
+    startedAt: string;
+}, now: Date): RunActivity;
+export {};