@phnx-labs/agents-cli 1.22.114 → 1.22.115

package/dist/lib/feed/hub.js

@@ -0,0 +1,255 @@
+/**
+ * One fleet fan-out, many readers.
+ *
+ * THE COST THIS EXISTS TO AVOID. `watchFleetFeed` opens a persistent
+ * `ssh <peer> agents feed watch --json --local` per dialable device — that is
+ * correct, and it is also per CALLER. Every consumer that wanted the operator
+ * stream ran its own copy: the extension's leader child, a menu-bar helper, an
+ * operator's `agents feed watch --json`. Three readers on a thirteen-device
+ * fleet is thirty-nine long-lived ssh children carrying byte-identical NDJSON,
+ * three copies of the local activity cursor, and three independent backoff
+ * ladders that each re-dial the same offline box.
+ *
+ * WHAT REPLACES IT. The hub owns exactly ONE {@link watchFleetFeed} — so one ssh
+ * child per reachable peer, one collector, one backoff ladder — and broadcasts
+ * to every subscriber. The fan-out starts on the FIRST subscriber and stops on
+ * the LAST, so an idle box with no reader open holds no peer connections at all.
+ *
+ * A LATE SUBSCRIBER COSTS NOTHING. The hub keeps the per-scope row state the
+ * stream has delivered so far, so subscriber two is served a synthesized reset
+ * per scope out of that state — no second fan-out, no re-dial, no waiting for
+ * the peers to re-announce. Its `streamId`/`sequence` are its own and start at
+ * 1, which is exactly what the published contract ("order by streamId +
+ * sequence") lets a consumer rely on.
+ *
+ * RESET SEMANTICS ARE PRESERVED, NOT REINVENTED. A peer's reset replaces that
+ * ONE scope's rows in the held state and is forwarded verbatim; a peer going
+ * unavailable forwards the `scope` event and leaves its rows in place, so a
+ * reader that attaches while a box is offline still sees that box's last-known
+ * rows marked unavailable rather than an empty fleet.
+ */
+import { machineId, normalizeHost } from '../machine-id.js';
+import { FeedWatchState } from './envelope.js';
+/** Activity events replayed to a late subscriber. The lane is a rolling view,
+ *  so a bounded tail is the honest amount of history to hand over. */
+export const HUB_ACTIVITY_REPLAY = 50;
+function emptyScope() {
+    return { agents: new Map(), attention: new Map(), tools: new Map(), setup: [], capturedAt: 0 };
+}
+/**
+ * The per-scope row state the hub has observed. This is a projection of the
+ * events already delivered, never an independent gather: nothing here reads a
+ * file, runs a command, or dials a peer.
+ */
+export class FeedHubState {
+    scopes = new Map();
+    activity = [];
+    scope(name) {
+        const key = normalizeHost(name);
+        let scope = this.scopes.get(key);
+        if (!scope) {
+            scope = emptyScope();
+            this.scopes.set(key, scope);
+        }
+        return scope;
+    }
+    apply(event) {
+        const scope = this.scope(event.scope);
+        switch (event.type) {
+            case 'reset':
+                // One scope only. A peer reconnecting must not erase another's rows.
+                scope.agents = new Map(event.agents.map((agent) => [agent.rowKey, agent]));
+                scope.attention = new Map(event.attention.map((item) => [item.key, item]));
+                scope.tools = new Map(event.tools.map((tool) => [tool.rowKey, tool]));
+                scope.setup = event.setup;
+                scope.capturedAt = event.capturedAt;
+                break;
+            case 'agent.upsert':
+                scope.agents.set(event.rowKey, event.agent);
+                break;
+            case 'agent.remove':
+                scope.agents.delete(event.rowKey);
+                break;
+            case 'attention.upsert':
+                scope.attention.set(event.rowKey, event.attention);
+                break;
+            case 'attention.remove':
+                scope.attention.delete(event.rowKey);
+                break;
+            case 'tool.upsert':
+                scope.tools.set(event.rowKey, event.tool);
+                break;
+            case 'tool.remove':
+                scope.tools.delete(event.rowKey);
+                break;
+            case 'setup.snapshot':
+                scope.setup = event.setup;
+                break;
+            case 'scope':
+                // Rows are deliberately RETAINED: transient fleet loss is not session
+                // death, the same rule `watchLocalSessions` states for its own scope.
+                scope.status = { status: event.status, ...(event.reason ? { reason: event.reason } : {}) };
+                break;
+            case 'activity.append':
+                this.activity.push(event.event);
+                if (this.activity.length > HUB_ACTIVITY_REPLAY)
+                    this.activity.shift();
+                break;
+            case 'heartbeat': break;
+        }
+    }
+    /** The envelopes that bring a fresh subscriber to the current state. */
+    snapshot(state) {
+        const out = [];
+        for (const [name, scope] of this.scopes) {
+            out.push(state.emit({
+                type: 'reset', scope: name, capturedAt: scope.capturedAt || Date.now(),
+                agents: [...scope.agents.values()], attention: [...scope.attention.values()],
+                tools: [...scope.tools.values()], setup: scope.setup,
+            }));
+            if (scope.status)
+                out.push(state.emit({ type: 'scope', scope: name, capturedAt: Date.now(), ...scope.status }));
+        }
+        // Chronological, matching the order they were first delivered in.
+        for (const event of this.activity) {
+            out.push(state.emit({ type: 'activity.append', scope: normalizeHost(machineId()), event }));
+        }
+        return out;
+    }
+    /** Scopes the hub has seen. Observability + tests. */
+    get scopeNames() { return [...this.scopes.keys()]; }
+}
+/**
+ * The shared collector. Construct one per process; call {@link subscribe} per
+ * reader.
+ */
+export class FeedHub {
+    options;
+    subscribers = new Set();
+    held = new FeedHubState();
+    controller = null;
+    running = null;
+    /**
+     * Bumped on every start/stop. A fan-out's completion handler only clears state
+     * when its own generation is still current, so a run winding down cannot clear
+     * a newer one's controller.
+     */
+    generation = 0;
+    /** The most recent fan-out failure, if the current generation hit one. */
+    lastFailure = null;
+    /**
+     * Called when the fan-out rejects. Without this the failure lived only in a
+     * dropped promise, so readers sat attached to a collector that had already died
+     * and saw an idle stream instead of an error. Settable so the socket server can
+     * attach after construction.
+     */
+    onFailure = null;
+    watch;
+    constructor(options) {
+        this.options = options;
+        this.watch = options.watch;
+    }
+    /** Readers currently attached. The fan-out runs iff this is > 0. */
+    get readerCount() { return this.subscribers.size; }
+    /** Is the single shared fan-out running right now? */
+    get active() { return this.controller !== null; }
+    /** The held per-scope state, for observability and tests. */
+    get state() { return this.held; }
+    /**
+     * Attach a reader. It is immediately served a snapshot of the held state, then
+     * every later event. Returns the detach function; the fan-out stops when the
+     * last reader detaches.
+     */
+    subscribe(emit) {
+        const subscriber = { emit, state: new FeedWatchState() };
+        this.subscribers.add(subscriber);
+        for (const event of this.held.snapshot(subscriber.state))
+            emit(event);
+        this.start();
+        let detached = false;
+        return () => {
+            if (detached)
+                return;
+            detached = true;
+            this.subscribers.delete(subscriber);
+            if (this.subscribers.size === 0)
+                this.stop();
+        };
+    }
+    /** Stop the fan-out and detach every reader. */
+    async close() {
+        this.subscribers.clear();
+        this.stop();
+        const running = this.running;
+        this.running = null;
+        if (running)
+            await running.catch(() => { });
+    }
+    /** Await the in-flight fan-out's teardown. Tests assert no overlap with it. */
+    async settled() {
+        await this.running?.catch(() => { });
+    }
+    /**
+     * Start the single fan-out, waiting for any previous one to finish first.
+     *
+     * The wait is the whole point. `stop()` aborts and returns immediately, but the
+     * fan-out it aborted is still tearing down ssh children. A reader that detaches
+     * and immediately reattaches — a VS Code window reloading, a menu-bar popover
+     * closing and reopening — therefore used to start a SECOND fan-out alongside
+     * the dying one: two ssh children per peer, two collectors, for as long as the
+     * overlap lasted. Serializing on the previous run makes that impossible.
+     */
+    start() {
+        if (this.controller)
+            return;
+        const generation = ++this.generation;
+        this.lastFailure = null;
+        const controller = new AbortController();
+        this.controller = controller;
+        const previous = this.running ?? Promise.resolve();
+        this.running = previous
+            .catch(() => { })
+            .then(() => {
+            // The readers may all have left while we waited for the old run to
+            // drain; starting then would dial every peer for nobody.
+            if (generation !== this.generation || controller.signal.aborted)
+                return;
+            return this.watch({
+                signal: controller.signal,
+                ...(this.options.reconnectMs !== undefined ? { reconnectMs: this.options.reconnectMs } : {}),
+                // Generation-guarded: an aborted fan-out can still emit while it drains
+                // (a peer's last buffered line, a pending promise resolving). Those
+                // envelopes describe the OLD subscription and must not reach the new
+                // generation's readers or mutate its held state.
+                emit: (event) => { if (generation === this.generation)
+                    this.broadcast(event); },
+            });
+        })
+            .catch((error) => {
+            // Surfaced, never swallowed: a reader attached to a dead collector would
+            // otherwise be indistinguishable from a quiet fleet.
+            if (generation === this.generation) {
+                this.lastFailure = error instanceof Error ? error : new Error(String(error));
+                this.onFailure?.(this.lastFailure);
+            }
+        })
+            .finally(() => {
+            // Only clear if this is still the live run: a stop/start cycle may have
+            // replaced it, and clearing then would strand the newer controller.
+            if (generation === this.generation)
+                this.controller = null;
+        });
+    }
+    stop() {
+        this.generation += 1;
+        this.controller?.abort();
+        this.controller = null;
+    }
+    broadcast(event) {
+        this.held.apply(event);
+        const { v: _v, streamId: _streamId, sequence: _sequence, ...payload } = event;
+        for (const subscriber of this.subscribers) {
+            subscriber.emit(subscriber.state.emit(payload));
+        }
+    }
+}

package/dist/lib/feed/tool-activity.d.ts

@@ -0,0 +1,108 @@
+import { type BrowserSessionRow } from '../browser/sessions-list.js';
+import { type ComputerRunRow } from '../computer/sessions-list.js';
+import type { LiveBrowserTask } from './tools.js';
+import { type ToolRow } from './tools.js';
+/** Re-projection cadence used only while no directory watcher could arm. */
+export declare const TOOL_SWEEP_MS = 5000;
+/** What one re-projection changed. Empty on both sides means nothing moved. */
+export interface ToolDiff {
+    upserts: ToolRow[];
+    removes: string[];
+}
+interface ToolSources {
+    browserRows?: () => BrowserSessionRow[];
+    computerRows?: () => ComputerRunRow[];
+    bindings?: () => Array<{
+        name: string;
+        device?: string;
+        profile?: string;
+        url?: string;
+        createdAt?: number;
+        sessionId?: string;
+        launchId?: string;
+    }>;
+    liveTasks?: () => LiveBrowserTask[];
+}
+/**
+ * One projection attempt. `complete` is false when any source threw.
+ *
+ * The flag is load-bearing, not diagnostic. A transient read failure — the
+ * browser rewriting `tasks.json`, a rotating ledger, an EMFILE — used to yield an
+ * EMPTY row list, which the differ then read as "every task closed" and published
+ * as a remove for every row. The operator watched their live tasks vanish and
+ * come back. An incomplete projection is not evidence of absence, so the caller
+ * keeps the state it already had.
+ */
+export interface ToolSnapshot {
+    rows: ToolRow[];
+    complete: boolean;
+}
+/**
+ * Project every browser task and computer run this machine knows about into
+ * canonical tool rows, newest first. Impure by design — the three readers are
+ * injectable so a test drives real temp stores rather than a mocked service.
+ */
+export declare function collectToolRows(scope: string, sources?: ToolSources): ToolSnapshot;
+/**
+ * Holds the last projected row set and answers "what changed?".
+ *
+ * Row identity is the projection's own `rowKey`, so a browser task that gains a
+ * capture upserts under the same key, and a closed task — gone from both the
+ * index and the capture tree — comes back as a remove.
+ */
+export declare class ToolRowSet {
+    private readonly rows;
+    /** The diff from the current set to `next`, and adopt `next` as current. */
+    diff(next: ToolRow[]): ToolDiff;
+    /** Adopt `rows` as the current set without emitting a diff (a reset). */
+    reset(rows: ToolRow[]): void;
+}
+interface ToolWatchOptions {
+    scope: string;
+    signal: AbortSignal;
+    /** Called with every non-empty diff. */
+    onDiff: (diff: ToolDiff) => void;
+    /** Re-projection cadence while no watcher is armed. */
+    sweepMs?: number;
+    /** Roots to watch (tests pass temp dirs). */
+    roots?: string[];
+    /** Row sources, forwarded to {@link collectToolRows}. */
+    sources?: ToolSources;
+    /** Seed the set so the first diff reports only later changes. */
+    initial?: ToolRow[];
+}
+/**
+ * The directory roots whose contents back the tool rows.
+ *
+ * The standalone computer ledger is its OWN root: the engine writes there
+ * directly, without going through agents-cli, so nothing under the event-ledger
+ * or browser roots changes when an operator runs `computer` by hand. Omitting it
+ * meant those actions were only ever noticed on a sweep triggered by unrelated
+ * activity.
+ */
+export declare function toolWatchRoots(): string[];
+/**
+ * Every live browser task on this machine, across every profile runtime dir.
+ *
+ * THROWS for the same reason {@link readLiveTasksFor} does. A runtime dir that
+ * does not exist means no browser has ever run here — genuinely no tasks. A
+ * readdir that fails for any other reason (EACCES, EMFILE) is a failure, and
+ * returning `[]` for it would tell the differ every task had closed.
+ */
+export declare function readLiveBrowserTasks(root?: string): LiveBrowserTask[];
+/**
+ * Watch the tool roots and report diffs until `signal` aborts.
+ *
+ * `armed()` reports whether every root currently has a live watcher. It is a
+ * FUNCTION, not a flag captured at setup: a watcher can die later (its directory
+ * is removed and recreated, an inotify limit is hit), and a frozen `armed: true`
+ * meant the tick kept short-circuiting on `!dirty` from a watcher that would
+ * never report again — changes were then missed permanently, with the handle
+ * still claiming to be armed. Each tick re-arms whatever is missing and sweeps
+ * until everything is watched again.
+ */
+export declare function watchToolActivity(options: ToolWatchOptions): {
+    armed: () => boolean;
+    stop: () => void;
+};
+export {};

package/dist/lib/feed/tool-activity.js

@@ -0,0 +1,313 @@
+/**
+ * Event-driven tool-activity collector — the thing that makes the rows in
+ * `tools.ts` reach the feed stream without a poll.
+ *
+ * THE COST THIS EXISTS TO AVOID. A status surface that wants "which browser
+ * tasks and computer runs are there right now" has, until this module, one way
+ * to ask: run `agents browser sessions --json` and `agents computer sessions
+ * --json`, per device, on a timer. Two subprocesses per tool per device per
+ * tick, each paying a full CLI boot, to answer "nothing changed" almost every
+ * time. A menu bar at a one-minute cadence over a ten-device fleet is 1,200
+ * process spawns an hour for, typically, zero new rows.
+ *
+ * WHAT REPLACES IT. The two sources are files on the machine that owns them:
+ * the browser runtime tree (task index + capture dirs) and the event ledger
+ * that `computer.action` appends to. This collector watches those roots, and
+ * re-projects ONLY when one of them reports a change. A warm idle does no work
+ * at all: no directory read, no subprocess, no emission. When something does
+ * change it re-projects and emits the DIFF — the changed rows and the vanished
+ * row keys — never a full snapshot, so a single new screenshot costs one
+ * `tool.upsert`.
+ *
+ * WHEN THE WATCHERS CANNOT ARM (an unsupported filesystem, a root that does not
+ * exist yet) the collector says so on `armed` and re-projects on the bounded
+ * sweep cadence instead. That is a stated degradation, not a silent one: a
+ * caller can surface it, and the diff shape is identical either way.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getBrowserRuntimeDir } from '../state.js';
+import { getEventsDir } from './events.js';
+import { listTaskBindings } from '../browser/task-index.js';
+import { buildBrowserSessionRows } from '../browser/sessions-list.js';
+import { buildComputerSessionRows, standaloneComputerActionsDir } from '../computer/sessions-list.js';
+import { boundBrowserRow, projectBrowserToolRow, projectComputerToolRow, sortToolRows } from './tools.js';
+/** Re-projection cadence used only while no directory watcher could arm. */
+export const TOOL_SWEEP_MS = 5_000;
+/** Computer ledger rows read per projection. Bounds the newest-first window. */
+const TOOL_COMPUTER_LIMIT = 500;
+/**
+ * Project every browser task and computer run this machine knows about into
+ * canonical tool rows, newest first. Impure by design — the three readers are
+ * injectable so a test drives real temp stores rather than a mocked service.
+ */
+export function collectToolRows(scope, sources = {}) {
+    let complete = true;
+    const read = (source, empty) => {
+        try {
+            return source();
+        }
+        catch {
+            complete = false;
+            return empty;
+        }
+    };
+    const bindings = new Map();
+    for (const binding of read(sources.bindings ?? listTaskBindings, []))
+        bindings.set(binding.name, binding);
+    const liveTasks = new Map();
+    for (const task of read(sources.liveTasks ?? (() => readLiveBrowserTasks()), []))
+        liveTasks.set(task.task, task);
+    const rows = [];
+    const browserRows = read(sources.browserRows ?? (() => buildBrowserSessionRows()), []);
+    const captured = new Set();
+    for (const row of browserRows) {
+        if (row.task)
+            captured.add(row.task);
+        rows.push(projectBrowserToolRow(scope, row, row.task ? bindings.get(row.task) : undefined, row.task ? liveTasks.get(row.task) : undefined));
+    }
+    // Neither the capture tree nor the task index alone answers "which tasks exist".
+    // `tasks.json` is the live authority (and the only source of tabs); the task
+    // index additionally routes a task whose browser runs on ANOTHER device, which
+    // has no local live record. A task bound a second ago is live and closable with
+    // no capture to its name, and deriving rows from captures alone hid exactly that.
+    for (const task of new Set([...liveTasks.keys(), ...bindings.keys()])) {
+        if (captured.has(task))
+            continue;
+        const binding = bindings.get(task);
+        const live = liveTasks.get(task);
+        rows.push(projectBrowserToolRow(scope, boundBrowserRow(task, live ?? binding ?? {}), binding, live));
+    }
+    const computerRows = read(sources.computerRows ?? (() => buildComputerSessionRows({ limit: TOOL_COMPUTER_LIMIT, observer: scope })), []);
+    for (const row of computerRows)
+        rows.push(projectComputerToolRow(scope, row));
+    return { rows: sortToolRows(rows), complete };
+}
+/**
+ * Holds the last projected row set and answers "what changed?".
+ *
+ * Row identity is the projection's own `rowKey`, so a browser task that gains a
+ * capture upserts under the same key, and a closed task — gone from both the
+ * index and the capture tree — comes back as a remove.
+ */
+export class ToolRowSet {
+    rows = new Map();
+    /** The diff from the current set to `next`, and adopt `next` as current. */
+    diff(next) {
+        const upserts = [];
+        const seen = new Set();
+        for (const row of next) {
+            seen.add(row.rowKey);
+            const serialized = JSON.stringify(row);
+            if (this.rows.get(row.rowKey) === serialized)
+                continue;
+            this.rows.set(row.rowKey, serialized);
+            upserts.push(row);
+        }
+        const removes = [];
+        for (const key of [...this.rows.keys()]) {
+            if (seen.has(key))
+                continue;
+            this.rows.delete(key);
+            removes.push(key);
+        }
+        return { upserts, removes };
+    }
+    /** Adopt `rows` as the current set without emitting a diff (a reset). */
+    reset(rows) {
+        this.rows.clear();
+        for (const row of rows)
+            this.rows.set(row.rowKey, JSON.stringify(row));
+    }
+}
+/**
+ * The directory roots whose contents back the tool rows.
+ *
+ * The standalone computer ledger is its OWN root: the engine writes there
+ * directly, without going through agents-cli, so nothing under the event-ledger
+ * or browser roots changes when an operator runs `computer` by hand. Omitting it
+ * meant those actions were only ever noticed on a sweep triggered by unrelated
+ * activity.
+ */
+export function toolWatchRoots() {
+    return [getBrowserRuntimeDir(), getEventsDir(), standaloneComputerActionsDir()];
+}
+/**
+ * One profile's live task records, with the tabs each task addresses.
+ *
+ * THROWS on a read it cannot trust. An absent `tasks.json` is the ordinary "no
+ * live browser on this profile" case and returns nothing — but EACCES, EMFILE, a
+ * truncated file or malformed JSON are failures, and swallowing them returned an
+ * empty list that is indistinguishable from "every task closed". The caller then
+ * published a remove for every live row. Failing loud here is what lets
+ * `collectToolRows` mark the projection incomplete and PRESERVE the rows it has.
+ */
+function readLiveTasksFor(profileDir) {
+    const file = path.join(profileDir, 'tasks.json');
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        // Only "it isn't there" is benign. Anything else is a read we cannot trust.
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        // A JSON error is NOT benign: the browser rewrites this file in place, so a
+        // parse failure usually means we caught a write in progress — and the tasks
+        // are still very much alive.
+        throw new Error(`unreadable live task state at ${file}: ${error.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`unexpected live task state at ${file}: expected an object of tasks`);
+    }
+    const out = [];
+    for (const [name, value] of Object.entries(parsed)) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const record = value;
+        // `tabs` maps the task's SHORT id -> the engine's target id. The short id is
+        // what `browser tab focus` takes and what stays stable across a reconnect,
+        // so it is the id published; the target id is never surfaced.
+        const borrowed = new Set(Array.isArray(record.borrowedTabs) ? record.borrowedTabs.filter((id) => typeof id === 'string') : []);
+        const tabs = [];
+        if (record.tabs && typeof record.tabs === 'object') {
+            for (const id of Object.keys(record.tabs)) {
+                tabs.push({ id, ...(record.currentTabId === id ? { current: true } : {}), ...(borrowed.has(id) ? { borrowed: true } : {}) });
+            }
+        }
+        out.push({
+            task: typeof record.name === 'string' ? record.name : name,
+            ...(typeof record.profile === 'string' ? { profile: record.profile } : {}),
+            ...(typeof record.label === 'string' ? { label: record.label } : {}),
+            tabs,
+            // The real persisted schema is `createdAt` + `lastActionAt` (`browser/types.ts`
+            // `Task`). An earlier revision read `startedAt`, which the DTO at
+            // `service.ts` uses but `tasks.json` never carries — so every zero-capture
+            // task reported no start time at all and sorted to the bottom.
+            ...(typeof record.createdAt === 'number' ? { startedAtMs: record.createdAt } : {}),
+            // `lastActionAt` is refreshed by every task-scoped action, which makes it
+            // the honest freshness key for a task that has produced no capture yet.
+            // Tasks written before RUSH-2622 carry none; `createdAt` is the fallback the
+            // browser's own reader normalizes them to.
+            ...(typeof record.lastActionAt === 'number' ? { lastActionAtMs: record.lastActionAt }
+                : typeof record.createdAt === 'number' ? { lastActionAtMs: record.createdAt } : {}),
+            ...(typeof record.sessionId === 'string' ? { sessionId: record.sessionId } : {}),
+            ...(typeof record.launchId === 'string' ? { launchId: record.launchId } : {}),
+            ...(typeof record.actor === 'string' ? { actor: record.actor } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * Every live browser task on this machine, across every profile runtime dir.
+ *
+ * THROWS for the same reason {@link readLiveTasksFor} does. A runtime dir that
+ * does not exist means no browser has ever run here — genuinely no tasks. A
+ * readdir that fails for any other reason (EACCES, EMFILE) is a failure, and
+ * returning `[]` for it would tell the differ every task had closed.
+ */
+export function readLiveBrowserTasks(root = getBrowserRuntimeDir()) {
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === 'sessions')
+            continue;
+        out.push(...readLiveTasksFor(path.join(root, entry.name)));
+    }
+    return out;
+}
+/**
+ * Watch the tool roots and report diffs until `signal` aborts.
+ *
+ * `armed()` reports whether every root currently has a live watcher. It is a
+ * FUNCTION, not a flag captured at setup: a watcher can die later (its directory
+ * is removed and recreated, an inotify limit is hit), and a frozen `armed: true`
+ * meant the tick kept short-circuiting on `!dirty` from a watcher that would
+ * never report again — changes were then missed permanently, with the handle
+ * still claiming to be armed. Each tick re-arms whatever is missing and sweeps
+ * until everything is watched again.
+ */
+export function watchToolActivity(options) {
+    const roots = options.roots ?? toolWatchRoots();
+    const set = new ToolRowSet();
+    if (options.initial)
+        set.reset(options.initial);
+    let dirty = false;
+    let stopped = false;
+    /** One entry per root; `undefined` means that root needs re-arming. */
+    const watchers = new Map(roots.map((root) => [root, undefined]));
+    const armRoot = (root) => {
+        if (stopped || watchers.get(root))
+            return;
+        try {
+            // A root that does not exist yet (no browser has ever run here) cannot be
+            // watched, and would never be retried. Creating it arms the watcher now.
+            fs.mkdirSync(root, { recursive: true });
+            // Recursive: a capture lands in <root>/<profile>/sessions/<task>/, several
+            // levels below the root, and a non-recursive watch never sees it.
+            const watcher = fs.watch(root, { recursive: true }, () => { dirty = true; });
+            watcher.on('error', () => {
+                watcher.close();
+                // Release the slot AND mark dirty: the events this watcher dropped
+                // between failing and being replaced have to be picked up by a sweep,
+                // or a change that landed inside that gap is lost for good.
+                if (watchers.get(root) === watcher)
+                    watchers.set(root, undefined);
+                dirty = true;
+            });
+            watchers.set(root, watcher);
+        }
+        catch { /* reported by armed(); the sweep covers it until it arms */ }
+    };
+    for (const root of roots)
+        armRoot(root);
+    const armed = () => [...watchers.values()].every((watcher) => watcher !== undefined);
+    const reproject = () => {
+        const snapshot = collectToolRows(options.scope, options.sources);
+        // An incomplete read is not evidence a task closed. Keep the rows we have and
+        // stay dirty so the next tick retries — publishing removes here is what made
+        // live rows flicker out on a transient failure.
+        if (!snapshot.complete) {
+            dirty = true;
+            return;
+        }
+        const diff = set.diff(snapshot.rows);
+        if (diff.upserts.length > 0 || diff.removes.length > 0)
+            options.onDiff(diff);
+    };
+    const timer = setInterval(() => {
+        for (const root of roots)
+            armRoot(root);
+        // Fully-armed watchers mean a tick with nothing reported does NOTHING — no
+        // directory read, no projection. That is the warm-idle guarantee, and it is
+        // conditional on every root actually being watched right now.
+        if (armed() && !dirty)
+            return;
+        dirty = false;
+        reproject();
+    }, options.sweepMs ?? TOOL_SWEEP_MS);
+    const stop = () => {
+        stopped = true;
+        clearInterval(timer);
+        for (const watcher of watchers.values())
+            watcher?.close();
+        watchers.clear();
+    };
+    options.signal.addEventListener('abort', stop, { once: true });
+    return { armed, stop };
+}