toolroll 0.9.47 → 0.9.49

package/dist/cli.d.ts

@@ -40,7 +40,7 @@ export type ParseResult = {
     error: string;
 };
 type Write = (line: string) => void;
-export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)\n  toolroll repos remove <path>\n                                   take it out of the console; its tasks and results stay\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
+export declare const HELP = "toolroll \u2014 a control plane for unattended coding agents\n\nUsage\n  toolroll [path...]        report what is in flight\n  toolroll pulls            report what is waiting on a person\n  toolroll graph            report which work graph is already here\n  toolroll repos            list connected repositories, and how to adjust\n  toolroll repos add <path> add a project; it is in the console at once (no path: the repo you are in)\n  toolroll repos remove <path>\n                                   take it out of the console; its tasks and results stay\n  toolroll repos add-from-github <owner/name> --root <dir>\n                                   preview, then clone and connect (--yes)\n  toolroll link             put `toolroll` on your PATH\n  toolroll unlink           take it off again\n  toolroll update           update to the latest release: verified, drained, undoable\n                                   (preview first; --yes, --now, --at HH:MM, --rollback)\n  toolroll contract         the machine contract: envelope version + capabilities\n                                   (--commands dumps the declared command guide)\n  toolroll skills install --claude-code [--dir <path>]\n                                   install this binary's guides for Claude Code (preview first)\n  toolroll skills install   teach a repo's agents this queue exists (preview first)\n  toolroll skills list      the guides this exact binary serves\n  toolroll skills get <name>  print one guide (version-matched, never stale)\n  toolroll demo             a seeded throwaway sandbox \u2014 see it working in 90 seconds\n  toolroll up               app + builder for every saved project \u2014 the normal start\n  toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)\n  toolroll status           running, queued, ready results, release check and plan windows\n  toolroll health           recent server latency, write waits and live streams\n  toolroll integrations     which integrations work, and what to do about the ones that don't (--json)\n  toolroll session          native coding sessions through the running service\n  toolroll connect          save a private connection to your central service\n  toolroll lead             named leads on the connected service\n  toolroll lead token       mint your lead agent's credential: its own work pings nobody\n  toolroll lead say \"<text>\"  (the lead) one short message in its person's chat\n  toolroll conversation     shared and private conversations on that service\n  toolroll chat --lead <id> --conversation <id>  central chat (use --local for local chat)\n\nOperating the queue \u2014 `toolroll task` prints the whole surface,\nand any queue command + --help prints it too\n  toolroll approver add <name>\n                               mint the credential that lets a person say yes\n  toolroll ready            what could be dispatched right now\n  toolroll check-progress <run>  current or final approved check progress\n  toolroll task wait <id> [--timeout <seconds>]\n                               wait for this attempt to finish or need a person\n  toolroll task add <title> queue work\n  toolroll task scope <id> --goal <text>\n                               state what success is; approval binds to it\n  toolroll task approve <id>\n                               the yes \u2014 nothing builds without one\n  toolroll claim <id> --runner <name>\n  toolroll heartbeat <lease> / release <lease> / reap\n  toolroll tick --runner <name> --token <t> --repo <path>\n                               one unattended pass over the ready set\n  toolroll flows list | show <id> | create | edit | trigger | script | card | archive\n                               set up and inspect flows (writes preview until --yes)\n  toolroll chat --as <you> --token <t>\n                               talk to the mate: one conversation across every\n                               project; it proposes, you confirm (--say \"\u2026\" for one turn)\n  toolroll serve --repo <path>  advanced: run only the console\n                               (--editor vscode with --runner: file links\n                               open in VS Code on the device you browse from)\n  toolroll watch / daemon install   advanced: run only the builder\n  toolroll reconcile        recover what the last stretch left behind\n\nWith nothing connected it reports everything it can find below the working\ndirectory. Once you connect repositories it reports those instead.\n\nOptions\n  --all         report everything discoverable, ignoring connected repos\n  --depth <n>   directory levels to descend (default: 6)\n  --hidden      include dot-directories, which are skipped by default\n  --dirty       also read each working tree for uncommitted files\n  --local       branches only: no network, no pull requests, no issues\n  --json        emit a machine-readable envelope instead of a report\n  -o <file>     also write that envelope to a file (requires --json)\n  -h, --help    show this\n\nNothing is written, installed, or configured. Every repository is read\nthrough git with --no-optional-locks, so a scan never contends for the\nindex lock with an editor you have open.\n\n--dirty is off by default because reading a working tree is unbounded\nwork: on a large or cloud-synced repo `git status` can take minutes,\nwhere listing branches takes milliseconds.\n\nlink shows what it would do and changes nothing; add --yes to apply it,\nor --to <dir> to choose where. It never uses sudo, never leaves your\nhome directory, and never touches a file it did not create.";
 export declare function parseArgs(argv: readonly string[]): ParseResult;
 /** The commands that operate the queue rather than report on the world. */
 /** Every verb the CLI routes OUTSIDE runOperate. Exported (with

package/dist/cli.js

@@ -28,6 +28,7 @@ import { COMMAND_GUIDE, SURFACE_NOTES, SURFACE_SCHEMA_VERSION } from "./surface.
 import { runSessionCommand, SESSION_CLI_ACTIONS } from "./session-cli.js";
 import { maybeRunTeamCommand, TEAM_CLI_ACTIONS } from "./team-cli.js";
 import { maybeRunRemoteCommand } from "./remote-exec.js";
+import { runHealthCommand } from "./health-cli.js";
 import { discover, inspectAll } from "./discover.js";
 import { readPulls } from "./pulls.js";
 import { detectGraphs, chooseBackend, setupOptions, LABELS as GRAPH_LABELS, } from "./graph.js";
@@ -67,6 +68,7 @@ Usage
   toolroll up               app + builder for every saved project — the normal start
   toolroll onboard          make your agent Toolroll's lead: add this repo, install its skill (--yes), offer starter flows (--starter)
   toolroll status           running, queued, ready results, release check and plan windows
+  toolroll health           recent server latency, write waits and live streams
   toolroll integrations     which integrations work, and what to do about the ones that don't (--json)
   toolroll session          native coding sessions through the running service
   toolroll connect          save a private connection to your central service
@@ -383,6 +385,8 @@ export async function main(argv, write = line => console.log(line), mainOptions
 }
 async function dispatch(argv, write, mainOptions) {
     // A saved API token sends commands marked remote to the central server, before anything local opens.
+    if (argv[0] === 'health')
+        return runHealthCommand(argv.slice(1), write, mainOptions.team ?? mainOptions.remote);
     const central = await maybeRunRemoteCommand(argv, mainOptions.remote ?? mainOptions.team);
     if (typeof central === "number")
         return central;

package/dist/contracts/cli.d.ts

@@ -304,6 +304,93 @@ export declare const COMMAND_OUTPUTS: {
         reason: z.ZodString;
         message: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>], "ok">;
+    readonly health: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodLiteral<true>;
+        command: z.ZodLiteral<"health">;
+        health: z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            windowSeconds: z.ZodLiteral<300>;
+            uptimeSeconds: z.ZodNumber;
+            requests: z.ZodObject<{
+                count: z.ZodNumber;
+                p50Ms: z.ZodNullable<z.ZodNumber>;
+                p99Ms: z.ZodNullable<z.ZodNumber>;
+                maxMs: z.ZodNullable<z.ZodNumber>;
+                totalMs: z.ZodNumber;
+            }, z.core.$loose>;
+            routes: z.ZodRecord<z.ZodEnum<{
+                assets: "assets";
+                auth: "auth";
+                chat: "chat";
+                "chat-stream": "chat-stream";
+                cli: "cli";
+                console: "console";
+                decisions: "decisions";
+                "flow-stream": "flow-stream";
+                flows: "flows";
+                health: "health";
+                mcp: "mcp";
+                metrics: "metrics";
+                other: "other";
+                projects: "projects";
+                results: "results";
+                sessions: "sessions";
+                settings: "settings";
+                tasks: "tasks";
+                team: "team";
+                "team-stream": "team-stream";
+            }> & z.core.$partial, z.ZodObject<{
+                count: z.ZodNumber;
+                p50Ms: z.ZodNullable<z.ZodNumber>;
+                p99Ms: z.ZodNullable<z.ZodNumber>;
+                maxMs: z.ZodNullable<z.ZodNumber>;
+                totalMs: z.ZodNumber;
+            }, z.core.$loose>>;
+            eventLoop: z.ZodObject<{
+                count: z.ZodNumber;
+                p50Ms: z.ZodNullable<z.ZodNumber>;
+                p99Ms: z.ZodNullable<z.ZodNumber>;
+                maxMs: z.ZodNullable<z.ZodNumber>;
+                totalMs: z.ZodNumber;
+            }, z.core.$loose>;
+            writes: z.ZodObject<{
+                wait: z.ZodObject<{
+                    count: z.ZodNumber;
+                    p50Ms: z.ZodNullable<z.ZodNumber>;
+                    p99Ms: z.ZodNullable<z.ZodNumber>;
+                    maxMs: z.ZodNullable<z.ZodNumber>;
+                    totalMs: z.ZodNumber;
+                }, z.core.$loose>;
+                hold: z.ZodObject<{
+                    count: z.ZodNumber;
+                    p50Ms: z.ZodNullable<z.ZodNumber>;
+                    p99Ms: z.ZodNullable<z.ZodNumber>;
+                    maxMs: z.ZodNullable<z.ZodNumber>;
+                    totalMs: z.ZodNumber;
+                }, z.core.$loose>;
+                statement: z.ZodObject<{
+                    count: z.ZodNumber;
+                    p50Ms: z.ZodNullable<z.ZodNumber>;
+                    p99Ms: z.ZodNullable<z.ZodNumber>;
+                    maxMs: z.ZodNullable<z.ZodNumber>;
+                    totalMs: z.ZodNumber;
+                }, z.core.$loose>;
+            }, z.core.$loose>;
+            streams: z.ZodObject<{
+                open: z.ZodNumber;
+                queuedBytes: z.ZodNumber;
+                maxQueuedBytes: z.ZodNumber;
+            }, z.core.$loose>;
+            budgetRefusals: z.ZodNumber;
+        }, z.core.$loose>;
+    }, z.core.$loose>, z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodLiteral<false>;
+        command: z.ZodLiteral<"health">;
+        reason: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], "ok">;
     readonly integrations: z.ZodDiscriminatedUnion<[z.ZodObject<{
         envelopeVersion: z.ZodLiteral<1>;
         ok: z.ZodLiteral<true>;

package/dist/contracts/cli.js

@@ -12,6 +12,7 @@ import { z } from "zod";
 import { ENVELOPE_VERSION, envelopeJson } from "../envelope.js";
 import { parseContract } from "./contract.js";
 import { LISTED_TASK_STATES } from "./lead-tools.js";
+import { healthSnapshotSchema } from './health.js';
 const str = z.string();
 const int = z.number().int();
 const list = z.array(z.unknown());
@@ -167,6 +168,7 @@ export const COMMAND_OUTPUTS = {
     contract: contractOutput,
     scan: scanOutput,
     status: statusOutput,
+    health: answers('health', { health: healthSnapshotSchema }),
     integrations: integrationsOutput,
     ready: z.union([
         answers("ready", { count: int, tasks: rows({ id: str, title: str, state: str }) }),

package/dist/contracts/health.d.ts

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+export declare const latencySummarySchema: z.ZodObject<{
+    count: z.ZodNumber;
+    p50Ms: z.ZodNullable<z.ZodNumber>;
+    p99Ms: z.ZodNullable<z.ZodNumber>;
+    maxMs: z.ZodNullable<z.ZodNumber>;
+    totalMs: z.ZodNumber;
+}, z.core.$loose>;
+export declare const healthSnapshotSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    windowSeconds: z.ZodLiteral<300>;
+    uptimeSeconds: z.ZodNumber;
+    requests: z.ZodObject<{
+        count: z.ZodNumber;
+        p50Ms: z.ZodNullable<z.ZodNumber>;
+        p99Ms: z.ZodNullable<z.ZodNumber>;
+        maxMs: z.ZodNullable<z.ZodNumber>;
+        totalMs: z.ZodNumber;
+    }, z.core.$loose>;
+    routes: z.ZodRecord<z.ZodEnum<{
+        assets: "assets";
+        auth: "auth";
+        chat: "chat";
+        "chat-stream": "chat-stream";
+        cli: "cli";
+        console: "console";
+        decisions: "decisions";
+        "flow-stream": "flow-stream";
+        flows: "flows";
+        health: "health";
+        mcp: "mcp";
+        metrics: "metrics";
+        other: "other";
+        projects: "projects";
+        results: "results";
+        sessions: "sessions";
+        settings: "settings";
+        tasks: "tasks";
+        team: "team";
+        "team-stream": "team-stream";
+    }> & z.core.$partial, z.ZodObject<{
+        count: z.ZodNumber;
+        p50Ms: z.ZodNullable<z.ZodNumber>;
+        p99Ms: z.ZodNullable<z.ZodNumber>;
+        maxMs: z.ZodNullable<z.ZodNumber>;
+        totalMs: z.ZodNumber;
+    }, z.core.$loose>>;
+    eventLoop: z.ZodObject<{
+        count: z.ZodNumber;
+        p50Ms: z.ZodNullable<z.ZodNumber>;
+        p99Ms: z.ZodNullable<z.ZodNumber>;
+        maxMs: z.ZodNullable<z.ZodNumber>;
+        totalMs: z.ZodNumber;
+    }, z.core.$loose>;
+    writes: z.ZodObject<{
+        wait: z.ZodObject<{
+            count: z.ZodNumber;
+            p50Ms: z.ZodNullable<z.ZodNumber>;
+            p99Ms: z.ZodNullable<z.ZodNumber>;
+            maxMs: z.ZodNullable<z.ZodNumber>;
+            totalMs: z.ZodNumber;
+        }, z.core.$loose>;
+        hold: z.ZodObject<{
+            count: z.ZodNumber;
+            p50Ms: z.ZodNullable<z.ZodNumber>;
+            p99Ms: z.ZodNullable<z.ZodNumber>;
+            maxMs: z.ZodNullable<z.ZodNumber>;
+            totalMs: z.ZodNumber;
+        }, z.core.$loose>;
+        statement: z.ZodObject<{
+            count: z.ZodNumber;
+            p50Ms: z.ZodNullable<z.ZodNumber>;
+            p99Ms: z.ZodNullable<z.ZodNumber>;
+            maxMs: z.ZodNullable<z.ZodNumber>;
+            totalMs: z.ZodNumber;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+    streams: z.ZodObject<{
+        open: z.ZodNumber;
+        queuedBytes: z.ZodNumber;
+        maxQueuedBytes: z.ZodNumber;
+    }, z.core.$loose>;
+    budgetRefusals: z.ZodNumber;
+}, z.core.$loose>;

package/dist/contracts/health.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { ROUTE_FAMILIES } from '../server-telemetry.js';
+const count = z.number().int().nonnegative();
+const milliseconds = z.number().nonnegative();
+export const latencySummarySchema = z.looseObject({ count, p50Ms: milliseconds.nullable(), p99Ms: milliseconds.nullable(), maxMs: milliseconds.nullable(), totalMs: milliseconds });
+export const healthSnapshotSchema = z.looseObject({
+    version: z.literal(1), windowSeconds: z.literal(300), uptimeSeconds: z.number().nonnegative(),
+    requests: latencySummarySchema, routes: z.partialRecord(z.enum(ROUTE_FAMILIES), latencySummarySchema), eventLoop: latencySummarySchema,
+    writes: z.looseObject({ wait: latencySummarySchema, hold: latencySummarySchema, statement: latencySummarySchema }),
+    streams: z.looseObject({ open: count, queuedBytes: count, maxQueuedBytes: count }), budgetRefusals: count,
+});

package/dist/desktop-update.d.ts

@@ -94,13 +94,13 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    error?: never;
     active: boolean;
     phase: string;
     detail: string;
     running: boolean;
     canResume: boolean;
     canCancel: boolean;
-    error?: never;
     automaticRecovery?: never;
     recoveryAttempts?: never;
     recoveryRepairs?: never;

package/dist/flow-live.d.ts

@@ -1,24 +1,16 @@
-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 FlowPresence = {
     name: string;
     cards: number[];
     editing: boolean;
 };
-export type FlowViewer = {
-    name: string;
+export type FlowViewer = LiveViewer & {
     card: number | null;
     editing: boolean;
-    response: ServerResponse;
-    valid: () => boolean;
 };
 /** What changes when anything on the canvas changes: metadata only, kept short and opaque. */
 export declare function flowFingerprint(store: Store, flow: number, now?: Date): string | null;
-export type FlowRooms = {
-    /** Keep this page's stream on the flow until it closes; the first event says where the flow stands. */
-    join: (flow: number, viewer: FlowViewer) => void;
-    /** Every stream, ended (the server is closing). */
-    close: () => void;
-    size: () => number;
-};
-export declare function createFlowRooms(fingerprint: (flow: number) => string | null, tickMs?: number): FlowRooms;
+export type FlowRooms = LiveRooms<number, FlowViewer>;
+/** Rooms keyed by flow. With a bus, a write reaches every open page at once; without one, only the safety net. */
+export declare function createFlowRooms(fingerprint: (flow: number) => string | null, options?: LiveRoomOptions): FlowRooms;

package/dist/flow-live.js

@@ -2,9 +2,9 @@
  * The live canvas (v88): a flow open in several browsers stays the same in
  * all of them, and each shows who else has it open.
  *
- * - A change nudge. While anyone has a flow open, a small read each second
- *   checks the flow's fingerprint (its revision, cards, moves, comments,
- *   watchers, step runs, linked task progress and triggers); when it changes, every open page
+ * - A change nudge. When the live bus says the workspace was written
+ *   (live-bus.ts), one small read checks the flow's fingerprint (its revision, cards, moves, comments,
+ *   watchers, step runs, linked task progress and triggers); when it changed, every open page
  *   hears "change" and reads the flow again the usual way. The nudge
  *   carries no card data: what a page shows is always what its own read
  *   returned, under its own checks.
@@ -13,13 +13,11 @@
  *   name. It lives in memory only and goes when the page closes or hides.
  *
  * Streams are refresh hints only: nothing here writes, and a page that
- * can't keep one open falls back to reading every few seconds.
+ * can't keep one open falls back to reading every few seconds. With nothing
+ * written, an open flow costs no reads; a 30-second check heals a miss.
  */
 import { createHash } from "node:crypto";
-const TICK_MS = 1_000;
-const CHECK_EVERY = 15;
-const HEARTBEAT_EVERY = 15;
-const PRESENCE_SETTLE_MS = 150;
+import { createLiveRooms } from "./live-bus.js";
 // Statements belong to their database, without keeping closed Stores alive.
 const fingerprintStatements = new WeakMap();
 function fingerprintStatement(store) {
@@ -94,17 +92,12 @@ export function flowFingerprint(store, flow, now = new Date()) {
     const row = fingerprintStatement(store).get({ $flow: flow, $now: now.toISOString() });
     return row === undefined ? null : createHash("sha256").update(Object.values(row).map(String).join("|")).digest("hex").slice(0, 16);
 }
-export function createFlowRooms(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`);
-    };
+/** Rooms keyed by flow. With a bus, a write reaches every open page at once; without one, only the safety net. */
+export function createFlowRooms(fingerprint, options = {}) {
     /** Everyone on the flow but you, one line per person however many pages they have open. */
-    const others = (room, me) => {
+    const others = (viewers, me) => {
         const people = new Map();
-        for (const one of room.viewers) {
+        for (const one of viewers) {
             if (one.name === me)
                 continue;
             const seen = people.get(one.name) ?? { name: one.name, cards: [], editing: false };
@@ -115,97 +108,5 @@ export function createFlowRooms(fingerprint, tickMs = TICK_MS) {
         }
         return [...people.values()].sort((a, b) => a.name.localeCompare(b.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 of room.viewers)
-                write(viewer, "here", { people: others(room, viewer.name) });
-        }, PRESENCE_SETTLE_MS);
-        room.settling.unref();
-    };
-    const leave = (flow, viewer) => {
-        const room = rooms.get(flow);
-        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(flow);
-    };
-    const tick = (flow, room) => {
-        room.ticks += 1;
-        if (room.ticks % CHECK_EVERY === 0) {
-            // A signed-out or narrowed account stops hearing about the flow.
-            for (const viewer of [...room.viewers])
-                if (!viewer.valid()) {
-                    write(viewer, "gone", {});
-                    leave(flow, viewer);
-                }
-            if (!rooms.has(flow))
-                return;
-        }
-        let now;
-        try {
-            now = fingerprint(flow);
-        }
-        catch {
-            return; /* a busy database: the next tick reads again */
-        }
-        if (now === null) {
-            for (const viewer of [...room.viewers]) {
-                write(viewer, "gone", {});
-                leave(flow, 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(flow, viewer) {
-            let room = rooms.get(flow);
-            if (room === undefined) {
-                let last = null;
-                try {
-                    last = fingerprint(flow);
-                }
-                catch { /* the first tick reads it */ }
-                room = { viewers: new Set(), last, timer: null, ticks: 0, settling: null };
-                const created = room;
-                room.timer = setInterval(() => tick(flow, created), tickMs);
-                room.timer.unref();
-                rooms.set(flow, room);
-            }
-            room.viewers.add(viewer);
-            write(viewer, "change", { at: room.last });
-            write(viewer, "here", { people: others(room, viewer.name) });
-            announce(room);
-            const gone = () => leave(flow, viewer);
-            viewer.response.once("close", gone);
-        },
-        close() {
-            for (const [flow, room] of [...rooms])
-                for (const viewer of [...room.viewers])
-                    leave(flow, viewer);
-        },
-        size: () => [...rooms.values()].reduce((sum, room) => sum + room.viewers.size, 0),
-    };
+    return createLiveRooms(fingerprint, others, options);
 }

package/dist/health-cli.d.ts

@@ -0,0 +1,3 @@
+import { type TeamCliOptions } from './team-cli.js';
+/** Read the running server, never a fresh CLI process's empty counters or the local database. */
+export declare function runHealthCommand(argv: readonly string[], write: (line: string) => void, options?: TeamCliOptions): Promise<number>;

package/dist/health-cli.js

@@ -0,0 +1,79 @@
+import { bearerOf, centralProfile } from './team-cli.js';
+import { envelopeJson } from './envelope.js';
+import { healthSnapshotSchema } from './contracts/health.js';
+/** Read the running server, never a fresh CLI process's empty counters or the local database. */
+export async function runHealthCommand(argv, write, options = {}) {
+    const json = argv.includes('--json');
+    const fail = (message, reason = 'unavailable', code = 1) => {
+        write(json ? envelopeJson({ command: 'health', ok: false, reason, message }) : message);
+        return code;
+    };
+    if (argv.includes('--help')) {
+        write('toolroll health [--profile <name>] [--json]\nRecent latency, event-loop delay, write waits and live streams from the connected server. An instance operator must sign in with toolroll connect first.');
+        return 0;
+    }
+    let profileName;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--json')
+            continue;
+        if (argv[i] === '--profile' && profileName === undefined && argv[i + 1] && !argv[i + 1].startsWith('-')) {
+            profileName = argv[++i];
+            continue;
+        }
+        return fail('Use toolroll health [--profile <name>] [--json].', 'usage', 2);
+    }
+    try {
+        const profile = centralProfile(options, profileName);
+        if (!profile)
+            return fail('Connect to the server first with toolroll connect, then run toolroll health.', 'not-connected', 2);
+        const timeout = AbortSignal.timeout(30_000);
+        const response = await (options.fetch ?? fetch)(`${profile.origin}/health`, {
+            redirect: 'manual', credentials: 'omit', signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
+            headers: { authorization: bearerOf(profile), accept: json ? 'application/json' : 'text/plain' },
+        });
+        if (response.status !== 200) {
+            await response.body?.cancel();
+            return fail(response.status === 401 || response.status === 403 || response.status === 302
+                ? 'Sign in as an instance operator to read server health.'
+                : response.status === 404 ? 'This server does not provide performance health yet. Update the server.' : 'Server health is unavailable. Try again shortly.');
+        }
+        // A health response is bounded by the fixed route vocabulary. Refuse unrelated HTML and oversized replies.
+        const reader = response.body?.getReader();
+        if (!reader)
+            return fail('The server returned no health measurements.');
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                size += part.value.byteLength;
+                if (size > 128 * 1024) {
+                    await reader.cancel();
+                    return fail('The server returned an unexpected health response.');
+                }
+                chunks.push(part.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+        if (json) {
+            const parsed = healthSnapshotSchema.safeParse(JSON.parse(text));
+            if (!parsed.success)
+                return fail('The server returned an unexpected health response.');
+            write(envelopeJson({ command: 'health', ok: true, health: parsed.data }));
+        }
+        else {
+            if (!response.headers.get('content-type')?.startsWith('text/plain') || !text.startsWith('Server health'))
+                return fail('The server returned an unexpected health response.');
+            write(text.trimEnd());
+        }
+        return 0;
+    }
+    catch {
+        return fail('Could not read server health. Check the saved connection and server availability.');
+    }
+}

package/dist/live-bus.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 { type FSWatcher } from "node:fs";
+import type { ServerResponse } from "node:http";
+import type { Store } from "./store.js";
+export type LiveChange = {
+    revision: string;
+};
+export type LiveBus = {
+    subscribe: (listener: (change: LiveChange) => void) => () => void;
+    publish: (change: LiveChange) => void;
+    /** The last revision heard, if any. */
+    revision: () => string | null;
+    listeners: () => number;
+};
+export declare function createLiveBus(): LiveBus;
+export type WorkspaceFollower = {
+    close: () => void; /** Read the revision now (tests, and a commit signal). */
+    check: () => void;
+};
+/**
+ * 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 declare function followWorkspace(store: Store, current: () => string, bus: LiveBus, options?: {
+    file?: string | null;
+    watchFile?: (path: string, listener: () => void) => FSWatcher | null;
+}): WorkspaceFollower;
+/** About every 30 s a room checks itself; a keep-alive goes between. */
+export declare const SAFETY_NET_MS = 30000;
+export declare const KEEP_ALIVE_MS = 15000;
+/** What a page's stream may hold unsent before it is "behind". */
+export declare const STREAM_LIMIT_BYTES: number;
+/** One page's stream, bounded. Overflow is terminal, even below Node's drain threshold. */
+export declare class LiveStream {
+    readonly response: ServerResponse;
+    private readonly limit;
+    private readonly onOverflow;
+    private ended;
+    constructor(response: ServerResponse, limit?: number, onOverflow?: () => void);
+    get open(): boolean;
+    private overflow;
+    private write;
+    send(event: string, data: unknown): void;
+    keepAlive(): void;
+}
+export type LiveViewer = {
+    name: string;
+    response: ServerResponse;
+    valid: () => boolean;
+};
+export type LiveRooms<K, V extends LiveViewer> = {
+    /** Keep this page's stream on the room until it closes; the first events say where it stands and who's here. */
+    join: (key: K, viewer: V) => void;
+    /** Every stream, ended (the server is closing). */
+    close: () => void;
+    size: () => number;
+};
+export type LiveRoomOptions = {
+    bus?: LiveBus | null;
+    safetyNetMs?: number;
+    keepAliveMs?: number;
+    limitBytes?: number;
+};
+/** Rooms of open pages that hear the bus. `presence` says who else is here, as each page should see it. */
+export declare function createLiveRooms<K, V extends LiveViewer>(fingerprint: (key: K) => string | null, presence: (viewers: readonly V[], me: string) => unknown, options?: LiveRoomOptions): LiveRooms<K, V>;