@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/feed/hub.js

@@ -1,46 +1,9 @@
-/**
- * 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 = [];
@@ -57,7 +20,6 @@ export class FeedHubState {
         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]));
@@ -86,8 +48,6 @@ export class FeedHubState {
                 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':
@@ -98,7 +58,6 @@ export class FeedHubState {
             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) {
@@ -110,56 +69,30 @@ export class FeedHubState {
             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);
@@ -176,7 +109,6 @@ export class FeedHub {
                 this.stop();
         };
     }
-    /** Stop the fan-out and detach every reader. */
     async close() {
         this.subscribers.clear();
         this.stop();
@@ -185,20 +117,9 @@ export class FeedHub {
         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;
@@ -210,32 +131,22 @@ export class FeedHub {
         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;
         });

package/dist/lib/feed/pr-status.d.ts

@@ -1,19 +1,12 @@
 import type { ActiveSession } from '../session/active.js';
-import type { DetectedPr } from '../session/state.js';
+import type { DetectedPr } from '@phnx-labs/sessions-cli/reader';
 import type { GhExec } from '../github/pr-mergeable.js';
 import type { PullRequestAttentionSignal } from './attention.js';
 export declare const PR_STATUS_TTL_MS = 45000;
 export interface PullRequestStatus extends PullRequestAttentionSignal {
     statusCheckRollup?: unknown[];
 }
-/** CLI-owned bounded-TTL source shared by feed attention and PR-board consumers. */
 export declare const PR_STATUS_DEFAULT_TIMEOUT_MS = 15000;
-/**
- * @param options.timeoutMs bound for the underlying `gh` call. An operator-facing
- *   caller working against a deadline (the feed answer path) passes its remaining
- *   budget so one unreachable PR cannot consume the whole operation; a timed-out
- *   read is negative-cached for the TTL like any other failure.
- */
 export declare function readPullRequestStatus(session: ActiveSession, options?: {
     nowMs?: number;
     ttlMs?: number;
@@ -21,18 +14,7 @@ export declare function readPullRequestStatus(session: ActiveSession, options?:
     gh?: GhExec;
 }): Promise<PullRequestStatus | undefined>;
 export declare function resetPullRequestStatusCache(): void;
-/**
- * The check rollup folded to one verdict; undefined when the PR has no checks.
- * `statusCheckRollup` mixes Checks-API runs (`conclusion` + `status`) with
- * legacy Status-API contexts (`state` only), so both shapes are read.
- */
 export declare function checksVerdict(rollup?: unknown[]): DetectedPr['checks'];
-/**
- * The row with its `pr` carrying the fetched status, so a consumer that only
- * sees the agent row (the menu bar, the extension) can color the chip without
- * its own `gh` call. A row without a PR, or a status that never resolved, is
- * returned as is.
- */
 export declare function withPullRequestStatus<T extends {
     pr?: DetectedPr;
 }>(row: T, status?: PullRequestStatus): T;

package/dist/lib/feed/pr-status.js

@@ -14,14 +14,7 @@ function needsHuman(value) {
     });
     return value.reviewDecision !== 'APPROVED' || (value.mergeable === 'MERGEABLE' && checksSettled);
 }
-/** CLI-owned bounded-TTL source shared by feed attention and PR-board consumers. */
 export const PR_STATUS_DEFAULT_TIMEOUT_MS = 15_000;
-/**
- * @param options.timeoutMs bound for the underlying `gh` call. An operator-facing
- *   caller working against a deadline (the feed answer path) passes its remaining
- *   budget so one unreachable PR cannot consume the whole operation; a timed-out
- *   read is negative-cached for the TTL like any other failure.
- */
 export async function readPullRequestStatus(session, options = {}) {
     const ref = session.pr?.url ?? session.pr?.number;
     if (!ref || !session.cwd)
@@ -47,11 +40,6 @@ export async function readPullRequestStatus(session, options = {}) {
     }
 }
 export function resetPullRequestStatusCache() { cache.clear(); }
-/**
- * The check rollup folded to one verdict; undefined when the PR has no checks.
- * `statusCheckRollup` mixes Checks-API runs (`conclusion` + `status`) with
- * legacy Status-API contexts (`state` only), so both shapes are read.
- */
 export function checksVerdict(rollup) {
     if (!rollup || rollup.length === 0)
         return undefined;
@@ -66,12 +54,6 @@ export function checksVerdict(rollup) {
     }
     return pending ? 'pending' : 'passing';
 }
-/**
- * The row with its `pr` carrying the fetched status, so a consumer that only
- * sees the agent row (the menu bar, the extension) can color the chip without
- * its own `gh` call. A row without a PR, or a status that never resolved, is
- * returned as is.
- */
 export function withPullRequestStatus(row, status) {
     if (!row.pr || !status)
         return row;

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

@@ -2,9 +2,7 @@ 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[];
@@ -23,84 +21,27 @@ interface ToolSources {
     }>;
     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;

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

@@ -1,29 +1,3 @@
-/**
- * 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';
@@ -31,15 +5,8 @@ import { getEventsDir } from './events.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) => {
@@ -51,10 +18,6 @@ export function collectToolRows(scope, sources = {}) {
             return empty;
         }
     };
-    // Task→device binding is browser-cli's now (bound at `start`, PHNX-4101), so
-    // agents-cli keeps no separate binding index. Cross-device tasks are driven by
-    // browser-cli from THIS box, so their `tasks.json` is local and reached by
-    // `readLiveBrowserTasks` below. The `bindings` source stays a test seam.
     const bindings = new Map();
     for (const binding of read(sources.bindings ?? (() => []), []))
         bindings.set(binding.name, binding);
@@ -69,11 +32,6 @@ export function collectToolRows(scope, sources = {}) {
             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;
@@ -86,16 +44,8 @@ export function collectToolRows(scope, sources = {}) {
         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();
@@ -116,35 +66,15 @@ export class ToolRowSet {
         }
         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;
@@ -152,7 +82,6 @@ function readLiveTasksFor(profileDir) {
         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;
@@ -162,9 +91,6 @@ function readLiveTasksFor(profileDir) {
         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)) {
@@ -175,9 +101,6 @@ function readLiveTasksFor(profileDir) {
         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') {
@@ -190,15 +113,7 @@ function readLiveTasksFor(profileDir) {
             ...(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 } : {}),
@@ -208,14 +123,6 @@ function readLiveTasksFor(profileDir) {
     }
     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 {
@@ -234,17 +141,6 @@ export function readLiveBrowserTasks(root = getBrowserRuntimeDir()) {
     }
     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();
@@ -252,39 +148,28 @@ export function watchToolActivity(options) {
         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 */ }
+        catch { }
     };
     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;
@@ -296,9 +181,6 @@ export function watchToolActivity(options) {
     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;