@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/feed/tools.d.ts

@@ -1,67 +1,29 @@
 import type { BrowserSessionRow, ArtifactKind } from '../browser/sessions-list.js';
 import type { ComputerRunRow } from '../computer/sessions-list.js';
-/** Newest captures retained per row. A task with hundreds of screenshots must
- *  not turn one stream envelope into a megabyte. */
 export declare const TOOL_CAPTURE_LIMIT = 20;
-/** Newest actions retained per computer row, for the same reason. */
 export declare const TOOL_ACTION_LIMIT = 50;
 export type ToolKind = 'browser' | 'computer';
-/** Why a row carries no owning session: `linked` resolved one, `unresolved` has
- *  an id that no indexed session matches, `unlinked` never had one. Mirrors the
- *  status both source modules already publish. */
 export type ToolLinkStatus = 'linked' | 'unresolved' | 'unlinked';
-/** One artifact a tool produced. Path only — never contents. */
 export interface ToolCapture {
     kind: ArtifactKind;
     name: string;
-    /**
-     * Absolute path ON {@link ToolCapture.host}. A capture lives on the machine
-     * whose browser produced it, so a fleet reader on another box must not treat
-     * this as a local path — it has to open it through that host. Carrying the host
-     * per capture is what makes the path meaningful off-box at all.
-     */
     path: string;
-    /** The device that holds this file. */
     host: string;
     bytes?: number;
     atMs: number;
 }
-/**
- * One tab a browser task has open, with the id the task itself addresses it by.
- *
- * `id` is the task's SHORT tab id (the key of `Task.tabs`), not the underlying
- * CDP target id: the short id is what `agents browser tab focus <id>` accepts
- * and what stays stable for the life of the tab, while the target id is an
- * engine-internal handle that a reconnect can change.
- */
 export interface ToolTab {
     id: string;
     url?: string;
     title?: string;
-    /** The tab URL-less verbs act on. */
     current?: boolean;
-    /**
-     * The task drives this tab but did not open it, so no close path touches it.
-     * Surfaced so a UI does not offer to close someone else's tab.
-     */
     borrowed?: boolean;
 }
-/**
- * An argv a consumer may run verbatim, plus the device it must run ON.
- *
- * `runOn` is load-bearing and is NOT a `--device` flag. A browser task is bound
- * to its device at `start`, and every later verb resolves that binding from the
- * local task index — `agents browser done --task x --device y` is explicitly
- * REJECTED (`browser/task-index.ts` `REJECT_DEVICE_MESSAGE`). So the way to act
- * on a task observed from another box is to run the plain argv on the host that
- * holds the binding, which is what this names.
- */
 export interface ToolCommand {
     command: 'agents';
     args: string[];
     runOn: string;
 }
-/** The agent session that drove the tool, as a click-through target. */
 export interface ToolOwner {
     sessionId: string;
     device: string;
@@ -70,13 +32,9 @@ export interface ToolOwner {
 }
 interface ToolRowBase {
     kind: ToolKind;
-    /** Opaque, stable identity for this row within one device scope. */
     rowKey: string;
-    /** The observing device that reported the row. */
     scope: string;
-    /** The DRIVEN machine — for `--device` runs this differs from `scope`. */
     device: string;
-    /** Is this a resource that still exists and can be acted on? */
     live: boolean;
     task?: string;
     sessionId?: string;
@@ -86,40 +44,21 @@ interface ToolRowBase {
     linkStatus: ToolLinkStatus;
     startedAtMs: number;
     updatedAtMs: number;
-    /** Newest first, bounded by {@link TOOL_CAPTURE_LIMIT}. */
     captures: ToolCapture[];
     captureCounts: Record<string, number>;
 }
 export interface BrowserToolRow extends ToolRowBase {
     kind: 'browser';
     profile: string;
-    /** Redacted by {@link redactToolUrl}; absent when the binding recorded none. */
     url?: string;
-    /**
-     * Tabs the task has open, newest-known first. Absent — not empty — when this
-     * host holds no live task record to read them from (a task bound to another
-     * device, or one whose run already ended leaving only captures). Absent means
-     * "unknown here", `[]` means "genuinely none".
-     */
     tabs?: ToolTab[];
-    /**
-     * Focus one of this task's tabs. Present only while `live` and only for a tab
-     * the task actually owns.
-     */
     showCommand?: ToolCommand;
-    /**
-     * The command that closes this task. Present ONLY while `live` — a task the
-     * index no longer binds has nothing left to close, and offering the command
-     * anyway would fail loud at the operator instead of at this boundary.
-     */
     closeCommand?: ToolCommand;
 }
 export interface ComputerToolRow extends ToolRowBase {
     kind: 'computer';
-    /** Always false: see the module docblock. A run is history, not a session. */
     live: false;
     bundle?: string;
-    /** Newest first, bounded by {@link TOOL_ACTION_LIMIT}. */
     actions: {
         verb: string;
         atMs: number;
@@ -127,59 +66,25 @@ export interface ComputerToolRow extends ToolRowBase {
         bundle?: string;
     }[];
     actionCounts: Record<string, number>;
-    /** Total actions for a row whose per-verb detail the ledger already pruned. */
     recoveredActionCount?: number;
 }
 export type ToolRow = BrowserToolRow | ComputerToolRow;
-/**
- * A task the local browser holds LIVE state for, read from its `tasks.json`.
- *
- * This is the only authority on a task's tabs: `tasks.json` is rewritten from
- * the live task map, so an entry here means the task exists right now, and its
- * `tabs` map is what `agents browser tab focus` addresses. A task whose run has
- * ended is absent even though its captures remain, which is exactly the
- * distinction `live` on a row reports.
- */
 export interface LiveBrowserTask {
     task: string;
     profile?: string;
     label?: string;
     tabs?: ToolTab[];
-    /** `Task.createdAt` — when the task was opened. */
     startedAtMs?: number;
-    /** `Task.lastActionAt` — refreshed by every task-scoped action. */
     lastActionAtMs?: number;
     sessionId?: string;
     launchId?: string;
-    /** `Task.actor` — who launched it, when the record carries one. */
     actor?: string;
 }
-/** Stable identity for one tool row within one device scope. */
 export declare function toolRowKey(scope: string, kind: ToolKind, identity: string): string;
-/**
- * A task URL safe to publish: userinfo removed and credential-shaped query
- * parameters replaced. A string that does not parse as a URL is dropped
- * entirely rather than published unexamined — it cannot be redacted safely.
- */
 export declare function redactToolUrl(raw: string | undefined): string | undefined;
-/**
- * A browser task the task index binds but that has produced no capture yet.
- *
- * `buildBrowserSessionRows` derives its rows from captures on disk, so a task
- * that was just opened — bound, live, drivable, closable — had no row at all
- * until its first screenshot landed. That is the window an operator most wants
- * to see, and it is exactly when a Sessions pane showed nothing. This
- * synthesizes the zero-capture row so it goes through the SAME projection rather
- * than a second parallel one.
- */
 export declare function boundBrowserRow(task: string, binding: {
     profile?: string;
 }): BrowserSessionRow;
-/**
- * One browser task (or a profile's downloads bucket) as a tool row. Pure: the
- * liveness verdict is passed in, because only the machine running the browser
- * daemon holds the task index that answers it.
- */
 export declare function projectBrowserToolRow(scope: string, row: BrowserSessionRow, binding?: {
     device?: string;
     profile?: string;
@@ -188,11 +93,6 @@ export declare function projectBrowserToolRow(scope: string, row: BrowserSession
     sessionId?: string;
     launchId?: string;
 }, live?: LiveBrowserTask): BrowserToolRow;
-/**
- * One computer run as a tool row. `live` is pinned false and no close/stop
- * command is produced: the emitting CLI process is already gone.
- */
 export declare function projectComputerToolRow(scope: string, row: ComputerRunRow): ComputerToolRow;
-/** Newest first across both kinds — the order a consumer renders. */
 export declare function sortToolRows(rows: ToolRow[]): ToolRow[];
 export {};

package/dist/lib/feed/tools.js

@@ -30,23 +30,13 @@
 import { createHash } from 'node:crypto';
 import { normalizeHost } from '../machine-id.js';
 import { sessionHeadline } from '../session/title.js';
-/** Newest captures retained per row. A task with hundreds of screenshots must
- *  not turn one stream envelope into a megabyte. */
 export const TOOL_CAPTURE_LIMIT = 20;
-/** Newest actions retained per computer row, for the same reason. */
 export const TOOL_ACTION_LIMIT = 50;
-/** Stable identity for one tool row within one device scope. */
 export function toolRowKey(scope, kind, identity) {
     return createHash('sha256').update(`${scope}\0${kind}\0${identity}`).digest('base64url').slice(0, 22);
 }
-/** Query parameters whose value is a credential, not a locator. */
 const CREDENTIAL_PARAM = /(token|secret|password|passwd|pwd|api[-_]?key|auth|session|signature|sig|code)/i;
 const REDACTED = '<redacted>';
-/**
- * A task URL safe to publish: userinfo removed and credential-shaped query
- * parameters replaced. A string that does not parse as a URL is dropped
- * entirely rather than published unexamined — it cannot be redacted safely.
- */
 export function redactToolUrl(raw) {
     if (!raw)
         return undefined;
@@ -63,34 +53,14 @@ export function redactToolUrl(raw) {
         if (CREDENTIAL_PARAM.test(key))
             url.searchParams.set(key, REDACTED);
     }
-    // A fragment is where OAuth implicit flows put the token, and nothing on a
-    // status row needs it.
     if (url.hash)
         url.hash = '';
     return url.toString();
 }
-/**
- * The owning agent session, or nothing.
- *
- * `sessionId` is passed in as the EFFECTIVE identity rather than read off the
- * capture row: a task's session is recorded in the live task record and in the
- * device binding as well as in the durable capture history, and a row assembled
- * from only one of those had an owner on some paths and not others. Resolving the
- * effective id first is what makes the owner link consistent for one task however
- * its row was assembled.
- *
- * Returns undefined when no id is known. `recordBrowserSession`/`emit` are
- * pre-existing no-ops for some paths, so closed history genuinely lacks an owner
- * sometimes — and an invented link would be worse than an absent one.
- */
 function ownerOf(sessionId, linkedSession, scope) {
     if (!sessionId)
         return undefined;
     const session = linkedSession ?? undefined;
-    // One headline ladder for the whole CLI (SES-14c): a row's own `label`, then the
-    // daemon-generated title, then the first-prompt topic. Re-deriving it here would
-    // silently drop the generated-title rung and show a different name for the same
-    // session than `agents sessions` does.
     const label = session ? sessionHeadline(session) : undefined;
     return {
         sessionId,
@@ -99,7 +69,6 @@ function ownerOf(sessionId, linkedSession, scope) {
         ...(session?.agent ? { agent: session.agent } : {}),
     };
 }
-/** A machine name, or undefined for the `unknown` not-identified sentinel. */
 function knownMachine(machine) {
     return machine && machine !== 'unknown' ? machine : undefined;
 }
@@ -109,16 +78,6 @@ function countBy(items, key) {
         counts[key(item)] = (counts[key(item)] ?? 0) + 1;
     return counts;
 }
-/**
- * A browser task the task index binds but that has produced no capture yet.
- *
- * `buildBrowserSessionRows` derives its rows from captures on disk, so a task
- * that was just opened — bound, live, drivable, closable — had no row at all
- * until its first screenshot landed. That is the window an operator most wants
- * to see, and it is exactly when a Sessions pane showed nothing. This
- * synthesizes the zero-capture row so it goes through the SAME projection rather
- * than a second parallel one.
- */
 export function boundBrowserRow(task, binding) {
     return {
         kind: 'task', task, profile: binding.profile ?? '',
@@ -127,49 +86,24 @@ export function boundBrowserRow(task, binding) {
         latestMtimeMs: 0,
     };
 }
-/**
- * One browser task (or a profile's downloads bucket) as a tool row. Pure: the
- * liveness verdict is passed in, because only the machine running the browser
- * daemon holds the task index that answers it.
- */
 export function projectBrowserToolRow(scope, row, binding, live) {
     const host = normalizeHost(scope);
-    // Live means the task still EXISTS: either this host's browser holds a live
-    // record for it, or the task index still routes it (which is the case for a
-    // task whose browser runs on another device).
     const isLive = Boolean(row.task) && (live !== undefined || binding !== undefined);
     const captures = row.artifacts.slice(0, TOOL_CAPTURE_LIMIT).map((artifact) => ({
         kind: artifact.kind, name: artifact.name, path: artifact.path, host, bytes: artifact.bytes, atMs: artifact.mtimeMs,
     }));
     const oldest = row.artifacts.length > 0 ? row.artifacts[row.artifacts.length - 1].mtimeMs : row.latestMtimeMs;
     const url = redactToolUrl(binding?.url);
-    // One effective identity for the row AND its owner link, resolved before either
-    // is built: durable capture history first (it survives the task), then the live
-    // record, then the device binding.
     const sessionId = row.sessionId ?? live?.sessionId ?? binding?.sessionId;
     const launchId = row.launchId ?? live?.launchId ?? binding?.launchId;
     const owner = ownerOf(sessionId, row.linkedSession, host);
-    // Tabs are only knowable from a LIVE task record on THIS host; a row projected
-    // from captures alone, or from a binding pointing at another device, genuinely
-    // does not know them and says so by omitting the field.
     const tabs = live?.tabs;
     const showTab = tabs?.find((tab) => tab.current && !tab.borrowed)?.id
         ?? tabs?.find((tab) => !tab.borrowed)?.id;
     const startedAtMs = live?.startedAtMs ?? binding?.createdAt ?? oldest;
-    // A task with no captures has no capture mtime to sort by. `lastActionAt` is
-    // refreshed by every task-scoped action, so it is the honest freshness key;
-    // its own start is the fallback. Reporting 0 would sort a brand-new live task
-    // to the very bottom of a newest-first list.
     const updatedAtMs = Math.max(row.latestMtimeMs, live?.lastActionAtMs ?? 0) || startedAtMs;
     return {
         kind: 'browser',
-        // Keyed on the TASK, never on the profile. A task with no captures yet is
-        // discovered from the task index, where the profile may not be recorded, so
-        // folding the profile into the identity would give the same task two
-        // different keys and render it twice the moment its first capture landed.
-        // Task names are unique within a machine's task index, which is the scope
-        // this key is already qualified by. The downloads bucket has no task, so it
-        // keys on its profile — one such row per profile, which is what it is.
         rowKey: toolRowKey(host, 'browser', row.task ? `task\0${row.task}` : `downloads\0${row.profile}`),
         scope: host,
         device: normalizeHost(binding?.device ?? host),
@@ -187,31 +121,14 @@ export function projectBrowserToolRow(scope, row, binding, live) {
         profile: row.profile || live?.profile || '',
         ...(url ? { url } : {}),
         ...(tabs ? { tabs } : {}),
-        // `runOn` is the OBSERVING host, not `device`: the binding that resolves the
-        // task's device lives here, and passing `--device` to a later verb is
-        // refused outright. See {@link ToolCommand}.
         ...(isLive && showTab ? { showCommand: { command: 'agents', args: ['browser', 'tab', 'focus', showTab, '--task', row.task], runOn: host } } : {}),
         ...(isLive ? { closeCommand: { command: 'agents', args: ['browser', 'done', '--task', row.task], runOn: host } } : {}),
     };
 }
-/**
- * One computer run as a tool row. `live` is pinned false and no close/stop
- * command is produced: the emitting CLI process is already gone.
- */
 export function projectComputerToolRow(scope, row) {
     const host = normalizeHost(scope);
     const owner = ownerOf(row.sessionId, row.linkedSession, host);
     const agent = row.agent ?? row.linkedSession?.agent;
-    // Captures come ONLY from a `capture` the producer recorded after the file was
-    // written. A screenshot action from before the producer carried that field has
-    // no path to report, and this deliberately reports none rather than guessing one
-    // from an output flag — a fabricated path is worse than an honest absence.
-    //
-    // `host` is the INVOKING machine, never `remoteHost`. The engine's helper RPC
-    // returns the image as base64 and the invoking process resolves `--out` and
-    // writes the file locally, so even a remote-desktop run leaves its screenshot
-    // on the box that ran the command. Naming the driven host would send a consumer
-    // looking for the file on a machine it was never written to.
     const captures = [];
     const captureCounts = {};
     for (const action of row.actions) {
@@ -236,11 +153,6 @@ export function projectComputerToolRow(scope, row) {
         kind: 'computer',
         rowKey: toolRowKey(host, 'computer', row.invocationId ?? `${row.machine}\0${row.pid ?? ''}\0${row.startMs}`),
         scope: host,
-        // `groupIntoComputerRuns` writes the literal 'unknown' when no record in the
-        // run identified a machine, which is a sentinel for "not identified" and not a
-        // device name. Publishing it made a locally-run action unaddressable and made
-        // it disappear under a device filter, so it resolves to the observing host —
-        // which is the machine whose ledger the run was read from.
         device: normalizeHost(row.remoteHost ?? knownMachine(row.machine) ?? host),
         live: false,
         ...(row.task ? { task: row.task } : {}),
@@ -259,7 +171,6 @@ export function projectComputerToolRow(scope, row) {
         ...(row.recoveredActionCount !== undefined ? { recoveredActionCount: row.recoveredActionCount } : {}),
     };
 }
-/** Newest first across both kinds — the order a consumer renders. */
 export function sortToolRows(rows) {
     return [...rows].sort((a, b) => b.updatedAtMs - a.updatedAtMs);
 }

package/dist/lib/feed/watch.d.ts

@@ -6,19 +6,12 @@ import { FeedHub } from './hub.js';
 import { getCachedToolSetup, subscribeToolSetup, type ToolSetupRow } from '../setup-tool-status.js';
 import type { GhExec } from '../github/pr-mergeable.js';
 export { FeedWatchState, type FeedWatchEnvelope, type FeedWatchPayload } from './envelope.js';
-/** Reuse session ownership reconciliation for the combined operator stream. */
 export declare class FeedSessionProjection {
     private readonly state;
     private readonly sessions;
     private readonly observations;
     private projectedAttention;
-    /**
-     * Tool rows per observing scope. A reset replaces one scope's rows and must
-     * not touch another's — the same per-scope rule the agent rows follow, and
-     * the reason a peer reconnecting cannot erase the local machine's tasks.
-     */
     private readonly toolsByScope;
-    /** Whole-set per scope; see the `setup.snapshot` docblock in `envelope.ts`. */
     private readonly setupByScope;
     constructor(state?: FeedWatchState);
     apply(event: FeedWatchEnvelope): FeedWatchEnvelope[];
@@ -28,46 +21,20 @@ interface WatchLocalFeedOptions {
     scope: string;
     signal: AbortSignal;
     emit: (event: FeedWatchEnvelope) => void;
-    /** Activity drain cadence. */
     activityPollMs?: number;
-    /** Attention reconcile cadence when nothing has announced a change. */
     reconcileMs?: number;
-    /** Session-watch inputs, forwarded verbatim to {@link watchLocalSessions}. */
     sessions?: Pick<WatchLocalOptions, 'readCache' | 'readPrevious' | 'journalPath' | 'journalPollMs' | 'heartbeatMs'>;
-    /** The `gh` runner behind PR status; a test passes a recorded table. */
     gh?: GhExec;
-    /** Tool-activity inputs, forwarded verbatim to {@link watchToolActivity}. */
     tools?: Pick<Parameters<typeof watchToolActivity>[0], 'sweepMs' | 'roots' | 'sources'>;
-    /**
-     * Tool-setup readers. The setup teammate owns DETECTION
-     * (`lib/setup-tool-status.ts`); this stream only publishes what its cache
-     * already holds, and never triggers a probe of its own.
-     */
     setup?: {
         read?: typeof getCachedToolSetup;
         subscribe?: typeof subscribeToolSetup;
     };
 }
 export declare function watchLocalFeed(options: WatchLocalFeedOptions): Promise<void>;
-/**
- * The one ingress for an envelope produced by ANOTHER agents-cli.
- *
- * `tools` was added to the `reset` payload within protocol v1, so a peer on an
- * older CLI is a correct v1 producer that simply reports no tool rows — which is
- * true of it, not a data defect to paper over. Normalizing HERE, at the single
- * place a foreign envelope enters, is what keeps every consumer downstream able
- * to treat the field as present instead of each re-checking it. A mixed-version
- * fleet is the normal state during a rollout, so an absent field must not take
- * the whole fan-out down.
- */
 export declare function normalizePeerEnvelope(event: FeedWatchEnvelope): FeedWatchEnvelope;
-/** The shared local collector, constructed on first use. Exposed for tests. */
 export declare function sharedLocalFeedHub(): FeedHub;
-/** Reset the shared collector. Tests only — it must not leak across cases. */
 export declare function resetSharedLocalFeedHub(): Promise<void>;
-/**
- * Subscribe to this machine's rows through the shared collector, until abort.
- */
 export declare function subscribeSharedLocalFeed(options: {
     signal: AbortSignal;
     emit: (event: FeedWatchEnvelope) => void;

package/dist/lib/feed/watch.js

@@ -17,19 +17,12 @@ import { FeedHub } from './hub.js';
 import { getCachedToolSetup, subscribeToolSetup } from '../setup-tool-status.js';
 import { PR_STATUS_TTL_MS, readPullRequestStatus, withPullRequestStatus } from './pr-status.js';
 export { FeedWatchState } from './envelope.js';
-/** Reuse session ownership reconciliation for the combined operator stream. */
 export class FeedSessionProjection {
     state;
     sessions = new SessionProjection();
     observations = new Map();
     projectedAttention = new Map();
-    /**
-     * Tool rows per observing scope. A reset replaces one scope's rows and must
-     * not touch another's — the same per-scope rule the agent rows follow, and
-     * the reason a peer reconnecting cannot erase the local machine's tasks.
-     */
     toolsByScope = new Map();
-    /** Whole-set per scope; see the `setup.snapshot` docblock in `envelope.ts`. */
     setupByScope = new Map();
     constructor(state = new FeedWatchState()) {
         this.state = state;
@@ -108,8 +101,6 @@ export class FeedSessionProjection {
                 result.push(this.state.emit({ type: 'agent.remove', scope: rowEvent.scope, rowKey: rowEvent.rowKey }));
             }
         }
-        // Attention has its own stable generation key, also used by feed answer.
-        // Never substitute the projected agent row key: reset consumers key by item.key.
         for (const [key, previous] of this.projectedAttention) {
             if (!next.has(key) && !resetScopes.has(previous.scope))
                 result.push(this.state.emit({ type: 'attention.remove', scope: previous.scope, rowKey: key }));
@@ -123,21 +114,12 @@ export class FeedSessionProjection {
         return result;
     }
 }
-/**
- * Live rows only: durable Previous rows share the operator stream for Sessions
- * history, but they are not live work and must never synthesize Needs-you
- * attention or a PR lookup.
- */
 function isLive(agent) {
     return Boolean(agent.sessionId) && !agent.previous && agent.context !== 'recent';
 }
-// ActiveSession.host names the terminal app; the feed contract's host is the
-// device scope. Normalize only the reconciler input so lifecycle/PR keys are
-// routable across the fleet while the projected agent row stays compatible.
 function reconcilerSession(agent) {
     return { ...agent, context: agent.context, host: agent.sourceDevice, viewingIn: undefined };
 }
-/** One `gh pr view` (cached 45 s) feeds both the attention verdict and the row's `pr` status. */
 async function pullRequestFor(agent, gh) {
     if (!isLive(agent) || !agent.pr)
         return undefined;
@@ -153,7 +135,6 @@ function attentionFor(agent, pullRequest) {
         pullRequest, nowMs: Date.now(),
     });
 }
-/** The row as the feed projects it: the session row with its PR status attached. */
 async function projectAgent(agent, gh) {
     const pullRequest = await pullRequestFor(agent, gh);
     return { agent: withPullRequestStatus(agent, pullRequest), attention: attentionFor(agent, pullRequest) };
@@ -182,52 +163,26 @@ export async function projectSessionEnvelope(event, state, gh, tools = [], setup
         return [state.emit({ type: 'scope', capturedAt: event.capturedAt, scope: event.scope, status: event.status, ...(event.reason ? { reason: event.reason } : {}) })];
     return [state.emit({ type: 'heartbeat', capturedAt: event.capturedAt, scope: event.scope })];
 }
-/**
- * Watch the feed dirs that can change attention without a session event: an
- * `agents feed post --blocked` writes a block, `feed answer` writes a
- * resolution. Both are external processes, so nothing on the session stream
- * announces them — this is what lets the reconcile pass be event-driven instead
- * of a poll over every row twice a second.
- */
 function watchAttentionStores(onChange) {
     const feedDir = getFeedDir();
     const watchers = [];
     for (const dir of [feedDir, path.join(feedDir, 'resolutions')]) {
         try {
-            // `resolutions` is created lazily by the first `recordResolution` call, so
-            // a fresh feed dir has no directory to watch yet. Create it up front —
-            // otherwise fs.watch throws ENOENT here, is swallowed, and never retried,
-            // silently downgrading every resolution to the 45 s PR-status fallback
-            // instead of the event-driven reconcile this function exists to provide.
             fs.mkdirSync(dir, { recursive: true });
             const watcher = fs.watch(dir, () => onChange());
-            // A directory that disappears must not take the watcher process down; the
-            // PR-status cadence below still reconciles on its own timer.
             watcher.on('error', () => watcher.close());
             watchers.push(watcher);
         }
-        catch { /* best-effort: the timed pass still reconciles on its own cadence */ }
+        catch { }
     }
     return () => { for (const watcher of watchers)
         watcher.close(); };
 }
 export async function watchLocalFeed(options) {
     const state = new FeedWatchState();
-    // The stream's opening scan registers every log past its own bytes, so the
-    // cursor has to be taken *after* it: a record appended while the scan was
-    // walking the directory is unreadable from the byte cursor, and only a
-    // timestamp taken after the scan classifies it as history rather than
-    // dropping it from a window the caller believes was covered.
     const activity = new ActivityStream();
     let activityCursor = Date.now();
-    // The tool rows as this machine last projected them. Held here rather than
-    // re-collected per reset: a session-watch reconnect emits a fresh reset, and
-    // re-reading the browser tree and the ledger for it would reintroduce exactly
-    // the per-render cost `tool-activity.ts` exists to remove.
     let toolRows = collectToolRows(options.scope, options.tools?.sources).rows;
-    // Setup rows come from the setup teammate's cache, never from a probe here:
-    // `getCachedToolSetup` reads metadata plus the last EXPLICIT health check, so
-    // publishing it costs no subprocess and cannot unlock a secret store.
     const readSetup = options.setup?.read ?? getCachedToolSetup;
     let setupRows = (() => {
         try {
@@ -239,8 +194,6 @@ export async function watchLocalFeed(options) {
     })();
     const agents = new Map();
     const attention = new Map();
-    // The PR status last projected onto each row, so a merge or a check verdict
-    // that lands between session events still reaches the row's consumers.
     const prStatus = new Map();
     let pending = Promise.resolve();
     const reconcileRows = async () => {
@@ -260,10 +213,6 @@ export async function watchLocalFeed(options) {
                 : state.emit({ type: 'attention.remove', scope: options.scope, rowKey }));
         }
     };
-    // Attention is reconciled when something can actually have changed it — a row
-    // moved, a block/resolution file was written — or when the PR-status TTL has
-    // expired and the cached verdicts are stale. Re-running it every 500 ms cost
-    // two file reads per row per tick and changed nothing.
     const reconcileMs = options.reconcileMs ?? PR_STATUS_TTL_MS;
     let attentionDirty = true;
     let lastReconcileMs = 0;
@@ -297,9 +246,6 @@ export async function watchLocalFeed(options) {
             }
         },
     });
-    // The setup cache is file-backed and notifies on change, so a Settings pane
-    // costs no polling: `subscribeToolSetup` is the invalidation the setup side
-    // publishes for exactly this consumer.
     const stopSetupWatch = (options.setup?.subscribe ?? subscribeToolSetup)((rows) => {
         const next = JSON.stringify(rows);
         if (next === JSON.stringify(setupRows))
@@ -363,17 +309,6 @@ function remoteFeedWatchCommand(os) {
         ? buildWindowsAgentsCommand({ args })
         : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
 }
-/**
- * The one ingress for an envelope produced by ANOTHER agents-cli.
- *
- * `tools` was added to the `reset` payload within protocol v1, so a peer on an
- * older CLI is a correct v1 producer that simply reports no tool rows — which is
- * true of it, not a data defect to paper over. Normalizing HERE, at the single
- * place a foreign envelope enters, is what keeps every consumer downstream able
- * to treat the field as present instead of each re-checking it. A mixed-version
- * fleet is the normal state during a rollout, so an absent field must not take
- * the whole fan-out down.
- */
 export function normalizePeerEnvelope(event) {
     if (event.type !== 'reset')
         return event;
@@ -381,30 +316,7 @@ export function normalizePeerEnvelope(event) {
         return event;
     return { ...event, tools: event.tools ?? [], setup: event.setup ?? [] };
 }
-/**
- * The process-wide local collector, shared by refcount.
- *
- * `watchLocalFeed` is cheap per tick but NOT free to duplicate: each call builds
- * its own `ActivityStream` cursor set over the activity directory, its own
- * recursive tool watchers, its own feed/resolution watchers and its own
- * setup subscription. Two callers in one process paid all of that twice and
- * produced identical envelopes — and there are genuinely two callers on a daemon
- * box: the fleet fan-out (which watches the local scope alongside every peer)
- * and anything else that wants this machine's rows.
- *
- * One {@link FeedHub} over `watchLocalFeed` collapses them: the watcher starts on
- * the first subscriber, stops on the last, and a late subscriber is caught up
- * from held state instead of constructing a second cursor set.
- *
- * This is deliberately PROCESS-wide and not machine-wide. Making `feed watch
- * --json --local` attach to the daemon instead would be the machine-wide
- * version, and it would put a daemon dependency on the one command the fleet
- * fan-out runs over ssh on every peer — a peer with a sick daemon would drop off
- * the fleet stream entirely rather than degrade. The cross-process sharing that
- * matters is the FLEET stream, which is what the daemon hub serves.
- */
 let sharedLocal = null;
-/** The shared local collector, constructed on first use. Exposed for tests. */
 export function sharedLocalFeedHub() {
     return sharedLocal ??= new FeedHub({
         watch: (hubOptions) => watchLocalFeed({
@@ -412,15 +324,11 @@ export function sharedLocalFeedHub() {
         }),
     });
 }
-/** Reset the shared collector. Tests only — it must not leak across cases. */
 export async function resetSharedLocalFeedHub() {
     const hub = sharedLocal;
     sharedLocal = null;
     await hub?.close();
 }
-/**
- * Subscribe to this machine's rows through the shared collector, until abort.
- */
 export function subscribeSharedLocalFeed(options) {
     const detach = sharedLocalFeedHub().subscribe(options.emit);
     return new Promise((resolve) => {
@@ -466,7 +374,7 @@ export async function watchFleetFeed(options) {
                     return true;
                 }
                 catch {
-                    return false; /* protocol only */
+                    return false;
                 }
             },
             onUnavailable: (reason) => options.emit(coordinator.emit({ type: 'scope', capturedAt: Date.now(), scope, status: 'unavailable', reason })),