@phnx-labs/agents-cli 1.22.114 → 1.22.115

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

@@ -0,0 +1,79 @@
+import type { SessionWatchRow, SessionWatchScopeStatus } from '../session/watch.js';
+import type { ToolSetupRow } from '../setup-tool-status.js';
+import type { AttentionItem } from './attention.js';
+import type { ActivityEvent } from './activity.js';
+import type { ToolRow } from './tools.js';
+type Base = {
+    v: 1;
+    type: string;
+    streamId: string;
+    sequence: number;
+    scope: string;
+};
+export type FeedWatchEnvelope = Base & {
+    type: 'reset';
+    capturedAt: number;
+    agents: SessionWatchRow[];
+    attention: AttentionItem[];
+    tools: ToolRow[];
+    /** This device's tool-setup rows; see `setup.snapshot` for why it is a set. */
+    setup: ToolSetupRow[];
+} | Base & {
+    type: 'agent.upsert';
+    rowKey: string;
+    agent: SessionWatchRow;
+} | Base & {
+    type: 'agent.remove';
+    rowKey: string;
+} | Base & {
+    type: 'attention.upsert';
+    rowKey: string;
+    attention: AttentionItem;
+} | Base & {
+    type: 'attention.remove';
+    rowKey: string;
+} | Base & {
+    type: 'activity.append';
+    event: ActivityEvent;
+}
+/** A browser task or computer run, projected by `feed/tools.ts`. */
+ | Base & {
+    type: 'tool.upsert';
+    rowKey: string;
+    tool: ToolRow;
+} | Base & {
+    type: 'tool.remove';
+    rowKey: string;
+}
+/**
+ * The whole tool-setup set for one device, replaced at once.
+ *
+ * Deliberately a SNAPSHOT and not per-row upserts: `getCachedToolSetup` always
+ * answers for every tool in `SETUP_TOOLS`, so "browser is ready" and "computer
+ * needs setup" are one coherent reading of the box taken at one moment. Sending
+ * three independent upserts would let a consumer render a mix of two different
+ * readings, and there is no row to *remove* — a tool that is not installed is a
+ * row saying so, which is exactly what a Setup pane must show.
+ */
+ | Base & {
+    type: 'setup.snapshot';
+    capturedAt: number;
+    setup: ToolSetupRow[];
+} | Base & {
+    type: 'scope';
+    capturedAt: number;
+    status: SessionWatchScopeStatus;
+    reason?: string;
+} | Base & {
+    type: 'heartbeat';
+    capturedAt: number;
+};
+export type FeedWatchPayload = FeedWatchEnvelope extends infer Envelope ? Envelope extends FeedWatchEnvelope ? Omit<Envelope, 'v' | 'streamId' | 'sequence'> : never : never;
+/** Per-subscriber stream identity and monotonic sequence. */
+export declare class FeedWatchState {
+    readonly streamId: string;
+    private sequence;
+    constructor(streamId?: `${string}-${string}-${string}-${string}-${string}`);
+    emit(event: FeedWatchPayload): FeedWatchEnvelope;
+}
+export {};

package/dist/lib/feed/envelope.js

@@ -0,0 +1,23 @@
+/**
+ * The feed stream's envelope contract and its sequencer.
+ *
+ * Extracted from `watch.ts` so the three modules that all speak this protocol —
+ * the producer (`watch.ts`), the shared collector (`hub.ts`), and the socket
+ * boundary (`hub-server.ts`) — can depend on the contract without depending on
+ * each other. `watch.ts` needs `FeedHub` to share its local collector and
+ * `hub.ts` needs the sequencer, so leaving both here is what keeps that from
+ * being an import cycle.
+ *
+ * `watch.ts` re-exports everything in this file, so every existing importer is
+ * unaffected.
+ */
+import { randomUUID } from 'node:crypto';
+/** Per-subscriber stream identity and monotonic sequence. */
+export class FeedWatchState {
+    streamId;
+    sequence = 0;
+    constructor(streamId = randomUUID()) { this.streamId = streamId; }
+    emit(event) {
+        return { v: 1, streamId: this.streamId, sequence: ++this.sequence, ...event };
+    }
+}

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

@@ -12,6 +12,12 @@
  * - Performance tracking: withTiming() wrapper for any async function
  */
 import type { ActorKind } from '../actor.js';
+/**
+ * The directory today's ledger is appended to. Exported for the tool-activity
+ * collector, which watches it instead of re-running `agents computer sessions`
+ * on a timer to notice a new `computer.action` (see `feed/tool-activity.ts`).
+ */
+export declare function getEventsDir(): string;
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
 export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'run.dispatched' | 'run.launch' | 'daemon.start' | 'daemon.stop' | 'daemon.error' | 'daemon.info' | 'routine.start' | 'routine.end' | 'watchdog.action' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'computer.action' | 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | 'secrets.lease-denied' | 'secrets.lease-expire' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'rotation.unresolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.failed' | 'webhook.handler.start' | 'webhook.handler.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 /** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */

package/dist/lib/feed/events.js

@@ -88,6 +88,14 @@ function eventsPath(date = new Date()) {
 function eventsDir(date = new Date()) {
     return path.dirname(eventsPath(date));
 }
+/**
+ * The directory today's ledger is appended to. Exported for the tool-activity
+ * collector, which watches it instead of re-running `agents computer sessions`
+ * on a timer to notice a new `computer.action` (see `feed/tool-activity.ts`).
+ */
+export function getEventsDir() {
+    return eventsDir();
+}
 /** Default retention period in days. */
 const DEFAULT_RETENTION_DAYS = 7;
 /** Default total footprint for the active log plus gzip archives (50 MiB). */

package/dist/lib/feed/hub-server.d.ts

@@ -0,0 +1,86 @@
+import { FeedHub } from './hub.js';
+import type { FeedWatchEnvelope } from './envelope.js';
+/**
+ * Outbound bytes a single reader may leave unflushed before it is dropped.
+ *
+ * `socket.write()` never blocks: when a reader stops draining — a stopped
+ * process, a suspended laptop, a debugger paused on a breakpoint — node buffers
+ * the backlog in the DAEMON's heap, without limit. A busy fleet stream is a few
+ * KB per second, so a reader wedged for an hour is tens of megabytes the daemon
+ * can never reclaim, and the daemon is the process every other surface depends
+ * on. A reader that cannot keep up is dropped loudly instead: it can reconnect
+ * and be caught up from held state, which is cheaper than the backlog.
+ */
+export declare const HUB_CLIENT_BACKLOG_LIMIT: number;
+/**
+ * How long a reader gets to send its scope line before it is REJECTED.
+ *
+ * The handshake is required, not defaulted. Silently treating a missing or
+ * unparseable scope as `fleet` meant a reader that sent nothing — or sent
+ * garbage, or sent its line after the grace elapsed — was quietly subscribed to
+ * the whole-fleet collector: it started ssh children to every peer on behalf of a
+ * client that never asked for them, and delivered peer data to a client that may
+ * have wanted only this box. A boundary that guesses is worse than one that
+ * refuses, so an unusable handshake is reported and the connection ends.
+ */
+export declare const HUB_HANDSHAKE_GRACE_MS = 2000;
+/** The canonical socket path (POSIX) / pipe-name key (Windows). */
+export declare function feedHubSocketPath(): string;
+/** The address a server listens on and a client connects to. */
+export declare function feedHubEndpoint(socketPath?: string): string;
+/**
+ * Serve one {@link FeedHub} to other processes. Each accepted connection is one
+ * subscriber; closing it detaches, and the last detach stops the fan-out.
+ */
+export declare class FeedHubServer {
+    private readonly hub;
+    private readonly socketPathOverride?;
+    private readonly localHub?;
+    private server;
+    private readonly detachers;
+    /** Which collector each reader is attached to, so a failure reaches only its own. */
+    private readonly attachedTo;
+    /** Readers dropped for exceeding {@link HUB_CLIENT_BACKLOG_LIMIT}. Observability. */
+    droppedForBacklog: number;
+    /** Readers refused for a missing, invalid, or late scope line. Observability. */
+    rejectedHandshakes: number;
+    /**
+     * @param hub      the FLEET collector (every reachable peer plus this box).
+     * @param localHub the LOCAL-only collector, served to a reader that asks for
+     *                 `scope: 'local'`. Optional: a server without one answers
+     *                 every reader from the fleet hub, which is what the fleet
+     *                 stream already contained.
+     */
+    constructor(hub: FeedHub, socketPathOverride?: string | undefined, localHub?: FeedHub | undefined);
+    /** Report a collector failure to its readers and end those connections. */
+    private failReaders;
+    /** Subscribers currently connected. Observability + tests. */
+    get clientCount(): number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Wait until the hub accepts a connection, or the deadline passes.
+ *
+ * `ensureDaemonStarted()` returns as soon as the daemon PROCESS is spawned, which
+ * is well before that process has loaded its services and bound this socket.
+ * Retrying immediately therefore raced the bind and failed on a daemon that was
+ * about to be perfectly healthy — reported to the operator as "the shared feed
+ * stream is unavailable". Resolves true once a connect succeeds.
+ */
+export declare function waitForHub(endpoint?: string, deadlineMs?: number, intervalMs?: number): Promise<boolean>;
+/**
+ * Read the shared stream from the hub until `signal` aborts.
+ *
+ * Rejects when the hub is not reachable. That is deliberate: a client that
+ * quietly ran its own `watchFleetFeed` instead would restore the per-caller
+ * ssh fan-out, so the caller starts the daemon and retries rather than
+ * degrading into the thing this replaced.
+ */
+export declare function streamFeedFromHub(options: {
+    signal: AbortSignal;
+    emit: (event: FeedWatchEnvelope) => void;
+    endpoint?: string;
+    /** Which collector to attach to. Defaults to the whole fleet. */
+    scope?: 'fleet' | 'local';
+}): Promise<void>;

package/dist/lib/feed/hub-server.js

@@ -0,0 +1,334 @@
+/**
+ * The shared feed collector, exposed to other processes.
+ *
+ * {@link FeedHub} already collapses N readers in ONE process to one fleet
+ * fan-out. The readers that matter are in DIFFERENT processes — the extension's
+ * leader child, the menu-bar helper, an operator's `agents feed watch --json` —
+ * so the hub has to be reachable across the process boundary or each of them
+ * opens its own ssh-per-peer fan-out anyway.
+ *
+ * This is that boundary, and it is deliberately the thinnest possible one: a
+ * UNIX socket (named pipe on Windows) that writes the SAME NDJSON envelopes
+ * `agents feed watch --json` has always written, one per line. A client is a
+ * `readline` over the socket; there is no request/response protocol, no framing
+ * of its own, and no second schema to keep in sync.
+ *
+ * The daemon owns the server (`FeedStreamService`), which is what makes it one
+ * scheduler and one executor: the hub dials peers, the clients only render. A
+ * client MUST NOT fall back to running its own fan-out when the socket is
+ * absent — that is the double-connection bug this module exists to remove — so
+ * {@link streamFeedFromHub} fails loud and the caller starts the daemon.
+ */
+import * as fs from 'node:fs';
+import * as net from 'node:net';
+import * as path from 'node:path';
+import { createInterface } from 'node:readline';
+import { getHelpersDir } from '../state.js';
+import { ipcEndpoint } from '../platform/ipc.js';
+const IS_WINDOWS = process.platform === 'win32';
+const SOCKET_NAME = 'feed-stream.sock';
+/**
+ * Outbound bytes a single reader may leave unflushed before it is dropped.
+ *
+ * `socket.write()` never blocks: when a reader stops draining — a stopped
+ * process, a suspended laptop, a debugger paused on a breakpoint — node buffers
+ * the backlog in the DAEMON's heap, without limit. A busy fleet stream is a few
+ * KB per second, so a reader wedged for an hour is tens of megabytes the daemon
+ * can never reclaim, and the daemon is the process every other surface depends
+ * on. A reader that cannot keep up is dropped loudly instead: it can reconnect
+ * and be caught up from held state, which is cheaper than the backlog.
+ */
+export const HUB_CLIENT_BACKLOG_LIMIT = 4 * 1024 * 1024;
+/**
+ * How long a reader gets to send its scope line before it is REJECTED.
+ *
+ * The handshake is required, not defaulted. Silently treating a missing or
+ * unparseable scope as `fleet` meant a reader that sent nothing — or sent
+ * garbage, or sent its line after the grace elapsed — was quietly subscribed to
+ * the whole-fleet collector: it started ssh children to every peer on behalf of a
+ * client that never asked for them, and delivered peer data to a client that may
+ * have wanted only this box. A boundary that guesses is worse than one that
+ * refuses, so an unusable handshake is reported and the connection ends.
+ */
+export const HUB_HANDSHAKE_GRACE_MS = 2_000;
+/** Bytes of handshake accepted before the reader is rejected outright. */
+const HUB_HANDSHAKE_MAX_BYTES = 1024;
+/** The scopes a reader may ask for. */
+const HUB_SCOPES = new Set(['fleet', 'local']);
+/** The canonical socket path (POSIX) / pipe-name key (Windows). */
+export function feedHubSocketPath() {
+    return path.join(getHelpersDir(), 'feed', SOCKET_NAME);
+}
+/** The address a server listens on and a client connects to. */
+export function feedHubEndpoint(socketPath = feedHubSocketPath()) {
+    return ipcEndpoint(socketPath);
+}
+/**
+ * Serve one {@link FeedHub} to other processes. Each accepted connection is one
+ * subscriber; closing it detaches, and the last detach stops the fan-out.
+ */
+export class FeedHubServer {
+    hub;
+    socketPathOverride;
+    localHub;
+    server = null;
+    detachers = new Map();
+    /** Which collector each reader is attached to, so a failure reaches only its own. */
+    attachedTo = new Map();
+    /** Readers dropped for exceeding {@link HUB_CLIENT_BACKLOG_LIMIT}. Observability. */
+    droppedForBacklog = 0;
+    /** Readers refused for a missing, invalid, or late scope line. Observability. */
+    rejectedHandshakes = 0;
+    /**
+     * @param hub      the FLEET collector (every reachable peer plus this box).
+     * @param localHub the LOCAL-only collector, served to a reader that asks for
+     *                 `scope: 'local'`. Optional: a server without one answers
+     *                 every reader from the fleet hub, which is what the fleet
+     *                 stream already contained.
+     */
+    constructor(hub, socketPathOverride, localHub) {
+        this.hub = hub;
+        this.socketPathOverride = socketPathOverride;
+        this.localHub = localHub;
+        // A collector that cannot start is reported to every reader attached to it
+        // and the connection is ended, so a consumer sees a failure instead of an
+        // indefinitely silent stream it cannot distinguish from an idle fleet.
+        for (const collector of [hub, localHub]) {
+            if (collector)
+                collector.onFailure = (error) => this.failReaders(collector, error);
+        }
+    }
+    /** Report a collector failure to its readers and end those connections. */
+    failReaders(collector, error) {
+        for (const [socket, attached] of this.attachedTo) {
+            if (attached !== collector || socket.destroyed)
+                continue;
+            socket.write(`${JSON.stringify({ v: 1, type: 'error', scope: '', error: error.message })}\n`);
+            socket.end();
+        }
+    }
+    /** Subscribers currently connected. Observability + tests. */
+    get clientCount() { return this.detachers.size; }
+    async start() {
+        const socketPath = this.socketPathOverride ?? feedHubSocketPath();
+        const endpoint = this.socketPathOverride ?? feedHubEndpoint();
+        const dir = path.dirname(socketPath);
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (!IS_WINDOWS) {
+            fs.chmodSync(dir, 0o700);
+            // A crashed daemon leaves the socket file behind; it accepts nothing, so
+            // removing it is the only way to bind. Named pipes vanish with their owner.
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { /* nothing stale to remove */ }
+        }
+        this.server = net.createServer((socket) => {
+            const end = () => {
+                this.detachers.get(socket)?.();
+                this.detachers.delete(socket);
+                this.attachedTo.delete(socket);
+            };
+            socket.on('close', end);
+            // A reader that dies mid-write surfaces as an error, not a close, and
+            // leaving it subscribed would hold every peer connection open forever.
+            socket.on('error', end);
+            /** Refuse this reader, telling it why rather than hanging up silently. */
+            const reject = (reason) => {
+                clearTimeout(grace);
+                if (socket.destroyed)
+                    return;
+                this.rejectedHandshakes += 1;
+                socket.write(`${JSON.stringify({ v: 1, type: 'error', scope: '', error: `feed handshake rejected: ${reason}` })}\n`);
+                socket.end();
+            };
+            const attach = (hub) => {
+                if (socket.destroyed || this.detachers.has(socket))
+                    return;
+                const detach = hub.subscribe((event) => {
+                    if (socket.destroyed)
+                        return;
+                    socket.write(`${JSON.stringify(event)}\n`);
+                    // Checked AFTER the write, so the reader is judged on a real backlog
+                    // rather than on one envelope's size.
+                    if (socket.writableLength > HUB_CLIENT_BACKLOG_LIMIT) {
+                        this.droppedForBacklog += 1;
+                        // `destroy` rather than `end`: a reader this far behind is not going
+                        // to drain a graceful FIN either, and the point is to release the
+                        // buffered bytes now. 'close' fires and detaches it.
+                        socket.destroy(new Error(`feed reader dropped: ${socket.writableLength} bytes unflushed exceeds the ${HUB_CLIENT_BACKLOG_LIMIT}-byte budget`));
+                    }
+                });
+                this.detachers.set(socket, detach);
+                this.attachedTo.set(socket, hub);
+                // A collector that ALREADY failed must not leave this reader waiting for
+                // a stream that is never coming.
+                if (hub.lastFailure)
+                    this.failReaders(hub, hub.lastFailure);
+            };
+            // The scope line is REQUIRED and must arrive within the grace window.
+            let handshake = '';
+            const grace = setTimeout(() => reject(`no scope line within ${HUB_HANDSHAKE_GRACE_MS}ms`), HUB_HANDSHAKE_GRACE_MS);
+            grace.unref();
+            socket.on('data', (chunk) => {
+                if (socket.destroyed)
+                    return;
+                // A line arriving AFTER this reader is attached is a protocol error: the
+                // scope is settled and a second one cannot retroactively change it.
+                if (this.detachers.has(socket)) {
+                    reject('scope sent after the stream was already open');
+                    return;
+                }
+                handshake += chunk.toString('utf-8');
+                const newline = handshake.indexOf('\n');
+                if (newline < 0) {
+                    if (handshake.length > HUB_HANDSHAKE_MAX_BYTES)
+                        reject('scope line exceeded the handshake budget');
+                    return;
+                }
+                clearTimeout(grace);
+                let scope;
+                try {
+                    scope = JSON.parse(handshake.slice(0, newline)).scope;
+                }
+                catch {
+                    reject('scope line is not valid JSON');
+                    return;
+                }
+                if (typeof scope !== 'string' || !HUB_SCOPES.has(scope)) {
+                    reject(`unknown scope ${JSON.stringify(scope)}; expected "fleet" or "local"`);
+                    return;
+                }
+                if (scope === 'local' && !this.localHub) {
+                    // Serving the fleet collector instead would start peer connections a
+                    // local-only reader never asked for.
+                    reject('this server has no local collector');
+                    return;
+                }
+                attach(scope === 'local' ? this.localHub : this.hub);
+            });
+            socket.once('end', () => clearTimeout(grace));
+        });
+        await new Promise((resolve, reject) => {
+            const listener = this.server;
+            listener.once('error', reject);
+            if (IS_WINDOWS) {
+                listener.listen(endpoint, () => resolve());
+                return;
+            }
+            // Restored on EVERY exit path. A listen error (the path is taken, the dir
+            // vanished) used to leave the process umask at 0o077 for good, so every
+            // later file this process created — a cache write, a journal — silently
+            // became owner-only. `once` guards the double-restore when both the
+            // success and error paths fire.
+            const previousUmask = process.umask(0o077);
+            let restored = false;
+            const restoreUmask = () => { if (!restored) {
+                restored = true;
+                process.umask(previousUmask);
+            } };
+            listener.once('error', restoreUmask);
+            listener.listen(socketPath, () => {
+                try {
+                    fs.chmodSync(socketPath, 0o600);
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+                finally {
+                    restoreUmask();
+                }
+            });
+        });
+    }
+    async stop() {
+        for (const [socket, detach] of this.detachers) {
+            detach();
+            socket.destroy();
+        }
+        this.detachers.clear();
+        this.attachedTo.clear();
+        const server = this.server;
+        this.server = null;
+        if (server)
+            await new Promise((resolve) => server.close(() => resolve()));
+        await this.hub.close();
+        await this.localHub?.close();
+    }
+}
+/**
+ * Wait until the hub accepts a connection, or the deadline passes.
+ *
+ * `ensureDaemonStarted()` returns as soon as the daemon PROCESS is spawned, which
+ * is well before that process has loaded its services and bound this socket.
+ * Retrying immediately therefore raced the bind and failed on a daemon that was
+ * about to be perfectly healthy — reported to the operator as "the shared feed
+ * stream is unavailable". Resolves true once a connect succeeds.
+ */
+export async function waitForHub(endpoint = feedHubEndpoint(), deadlineMs = 10_000, intervalMs = 100) {
+    const deadline = Date.now() + deadlineMs;
+    for (;;) {
+        const reachable = await new Promise((resolve) => {
+            const probe = net.createConnection(endpoint);
+            const settle = (ok) => { probe.destroy(); resolve(ok); };
+            probe.once('connect', () => settle(true));
+            probe.once('error', () => settle(false));
+        });
+        if (reachable)
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+}
+/**
+ * Read the shared stream from the hub until `signal` aborts.
+ *
+ * Rejects when the hub is not reachable. That is deliberate: a client that
+ * quietly ran its own `watchFleetFeed` instead would restore the per-caller
+ * ssh fan-out, so the caller starts the daemon and retries rather than
+ * degrading into the thing this replaced.
+ */
+export function streamFeedFromHub(options) {
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(options.endpoint ?? feedHubEndpoint());
+        let connected = false;
+        // Registered before anything else touches the socket: a connect failure on
+        // a missing socket path is emitted as an 'error' with no listener attached
+        // yet, which node raises as an uncaught exception rather than rejecting.
+        socket.on('error', (error) => finish(error));
+        const stop = () => { socket.destroy(); };
+        options.signal.addEventListener('abort', stop, { once: true });
+        const finish = (error) => {
+            options.signal.removeEventListener('abort', stop);
+            reader.close();
+            if (error && !connected)
+                reject(error);
+            else
+                resolve();
+        };
+        const reader = createInterface({ input: socket });
+        // `readline.Interface` re-emits its input stream's error on ITSELF, and an
+        // Interface with no 'error' listener raises it as an uncaught exception —
+        // so handling it on the socket alone is not enough. Routed to the same
+        // `finish` so a mid-stream input failure ends the read once.
+        reader.on('error', (error) => finish(error));
+        reader.on('line', (line) => {
+            if (!line)
+                return;
+            try {
+                const event = JSON.parse(line);
+                // Protocol only: an unversioned line is not a feed envelope.
+                if (event.v === 1)
+                    options.emit(event);
+            }
+            catch { /* a partial/foreign line is not state */ }
+        });
+        socket.on('connect', () => {
+            connected = true;
+            socket.write(`${JSON.stringify({ v: 1, scope: options.scope ?? 'fleet' })}\n`);
+        });
+        socket.on('close', () => finish());
+    });
+}

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

@@ -0,0 +1,95 @@
+import { FeedWatchState, type FeedWatchEnvelope } 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 declare const HUB_ACTIVITY_REPLAY = 50;
+/**
+ * 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 declare class FeedHubState {
+    private readonly scopes;
+    private readonly activity;
+    private scope;
+    apply(event: FeedWatchEnvelope): void;
+    /** The envelopes that bring a fresh subscriber to the current state. */
+    snapshot(state: FeedWatchState): FeedWatchEnvelope[];
+    /** Scopes the hub has seen. Observability + tests. */
+    get scopeNames(): string[];
+}
+/** The collector a hub owns: it runs until the signal aborts, emitting envelopes. */
+export type HubFanOut = (options: {
+    signal: AbortSignal;
+    emit: (event: FeedWatchEnvelope) => void;
+    reconnectMs?: number;
+}) => Promise<void>;
+/** Told to every attached reader when the shared fan-out cannot start. */
+export type HubFailureListener = (error: Error) => void;
+interface FeedHubOptions {
+    /**
+     * The collector to own — the fleet ssh fan-out, or the local watcher. Required
+     * rather than defaulted so this module depends on neither, which is what keeps
+     * `watch.ts` free to depend on THIS module for its shared local collector.
+     */
+    watch: HubFanOut;
+    /** Forwarded to the fan-out. */
+    reconnectMs?: number;
+}
+/**
+ * The shared collector. Construct one per process; call {@link subscribe} per
+ * reader.
+ */
+export declare class FeedHub {
+    private readonly options;
+    private readonly subscribers;
+    private readonly held;
+    private controller;
+    private running;
+    /**
+     * 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.
+     */
+    private generation;
+    /** The most recent fan-out failure, if the current generation hit one. */
+    lastFailure: Error | 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: HubFailureListener | null;
+    private readonly watch;
+    constructor(options: FeedHubOptions);
+    /** Readers currently attached. The fan-out runs iff this is > 0. */
+    get readerCount(): number;
+    /** Is the single shared fan-out running right now? */
+    get active(): boolean;
+    /** The held per-scope state, for observability and tests. */
+    get state(): FeedHubState;
+    /**
+     * 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: (event: FeedWatchEnvelope) => void): () => void;
+    /** Stop the fan-out and detach every reader. */
+    close(): Promise<void>;
+    /** Await the in-flight fan-out's teardown. Tests assert no overlap with it. */
+    settled(): Promise<void>;
+    /**
+     * 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.
+     */
+    private start;
+    private stop;
+    private broadcast;
+}
+export {};