@phnx-labs/agents-cli 1.22.119 → 1.22.121

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

@@ -1,141 +1,41 @@
 import { FeedHub } from './hub.js';
 import type { FeedWatchEnvelope } from './envelope.js';
-/**
- * Live bytes a reader may leave queued, sustained past {@link HUB_BACKLOG_GRACE_MS},
- * 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.
- *
- * The budget is a SUSTAINED condition on queued live events, never a verdict on
- * one envelope or one burst. A cold collector delivers every peer's reset as a
- * live event, thirteen of them inside one tick, and a healthy reader drains
- * that in milliseconds; judging the budget the instant an envelope was written
- * is how a 5 MB fleet reset was cut off after 8 KiB and delivered as one
- * unterminated line (the Menu activation failure this module's writer fixes).
- * The catch-up snapshot is never counted: it is bounded by the held state and is
- * exactly what a fresh reader is waiting for.
- */
 export declare const HUB_CLIENT_BACKLOG_LIMIT: number;
-/**
- * How long a reader may stay past {@link HUB_CLIENT_BACKLOG_LIMIT} before it is
- * dropped. A healthy reader on a unix socket clears the whole budget in well
- * under this; one still over it after this long is not keeping up. The live
- * bytes queued for a reader are therefore bounded by the budget plus what the
- * stream produces in this window; the snapshot and the frame in flight sit
- * outside that figure.
- */
 export declare const HUB_BACKLOG_GRACE_MS = 2000;
-/**
- * How long a reader may leave one chunk unaccepted before it is dropped.
- *
- * A write that returned `false` is a kernel buffer full of bytes the reader has
- * not read. A healthy reader — even one on a busy laptop — clears it in
- * milliseconds; one that has not in this long is not reading at all, and the
- * live-bytes budget alone would let a paused reader hold a large snapshot's
- * remainder in the daemon's heap forever.
- */
 export declare const HUB_DRAIN_STALL_MS = 30000;
-/**
- * Bytes handed to the socket per write. Small enough that a reader's own
- * backpressure (`write()` returning `false`, then `'drain'`) paces a multi-MB
- * snapshot instead of dumping it into the daemon's heap in one copy.
- */
 export declare const HUB_WRITE_CHUNK_BYTES: number;
-/** Optional overrides for the transport bounds. Tests exercise both bounds fast. */
 export type FeedHubLimits = {
     backlogBytes?: number;
     backlogGraceMs?: number;
     drainStallMs?: number;
     chunkBytes?: 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;
     private readonly writers;
     private readonly limits;
-    /** Readers dropped for queueing live bytes past the budget. Observability. */
     droppedForBacklog: number;
-    /** Readers dropped for not draining a chunk within the stall deadline. Observability. */
     droppedForStall: 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, limits?: FeedHubLimits);
-    /** Report a collector failure to its readers and end those connections. */
     private failReaders;
-    /** Subscribers currently connected. Observability + tests. */
     get clientCount(): number;
-    /** Bytes queued for every reader and not yet handed to a socket. Observability + tests. */
     get pendingBytes(): 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.
- *
- * Also rejects on any close the caller did not ask for. The stream has no end
- * of its own — the hub serves it until the reader leaves — so a FIN that
- * arrives before `signal` aborts is the hub refusing, failing, or dropping this
- * reader, and a FIN inside a line is a frame the hub never finished. Resolving
- * there let `agents feed watch --json` exit 0 after 8 KiB of a 5 MB reset,
- * which is indistinguishable from an empty fleet.
- */
 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

@@ -1,24 +1,3 @@
-/**
- * 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
- * line splitter 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';
@@ -26,124 +5,38 @@ import { getHelpersDir } from '../state.js';
 import { ipcEndpoint } from '../platform/ipc.js';
 const IS_WINDOWS = process.platform === 'win32';
 const SOCKET_NAME = 'feed-stream.sock';
-/**
- * Live bytes a reader may leave queued, sustained past {@link HUB_BACKLOG_GRACE_MS},
- * 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.
- *
- * The budget is a SUSTAINED condition on queued live events, never a verdict on
- * one envelope or one burst. A cold collector delivers every peer's reset as a
- * live event, thirteen of them inside one tick, and a healthy reader drains
- * that in milliseconds; judging the budget the instant an envelope was written
- * is how a 5 MB fleet reset was cut off after 8 KiB and delivered as one
- * unterminated line (the Menu activation failure this module's writer fixes).
- * The catch-up snapshot is never counted: it is bounded by the held state and is
- * exactly what a fresh reader is waiting for.
- */
 export const HUB_CLIENT_BACKLOG_LIMIT = 4 * 1024 * 1024;
-/**
- * How long a reader may stay past {@link HUB_CLIENT_BACKLOG_LIMIT} before it is
- * dropped. A healthy reader on a unix socket clears the whole budget in well
- * under this; one still over it after this long is not keeping up. The live
- * bytes queued for a reader are therefore bounded by the budget plus what the
- * stream produces in this window; the snapshot and the frame in flight sit
- * outside that figure.
- */
 export const HUB_BACKLOG_GRACE_MS = 2_000;
-/**
- * How long a reader may leave one chunk unaccepted before it is dropped.
- *
- * A write that returned `false` is a kernel buffer full of bytes the reader has
- * not read. A healthy reader — even one on a busy laptop — clears it in
- * milliseconds; one that has not in this long is not reading at all, and the
- * live-bytes budget alone would let a paused reader hold a large snapshot's
- * remainder in the daemon's heap forever.
- */
 export const HUB_DRAIN_STALL_MS = 30_000;
-/**
- * Bytes handed to the socket per write. Small enough that a reader's own
- * backpressure (`write()` returning `false`, then `'drain'`) paces a multi-MB
- * snapshot instead of dumping it into the daemon's heap in one copy.
- */
 export const HUB_WRITE_CHUNK_BYTES = 64 * 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);
 }
-/**
- * One reader's ordered outbound queue.
- *
- * Every line to one socket goes through this — snapshot, live events, and the
- * error envelope that precedes a refusal — so nothing can land inside another
- * line. Lines are written in {@link HUB_WRITE_CHUNK_BYTES} chunks and the pump
- * waits for `'drain'` after every write the socket did not accept, so the socket
- * never holds more than one chunk past its high-water mark. The frame's own
- * Buffer stays allocated until its last chunk is written (`subarray` is a view),
- * so `pendingBytes` is a gauge of UNFLUSHED bytes, not of retained heap. Two
- * bounds drop the reader: a chunk left unaccepted for `drainStallMs`, and live
- * bytes queued past `backlogBytes` for longer than `backlogGraceMs`. The bound
- * on what a reader can make the daemon hold is therefore time- and
- * rate-dependent — the budget, plus the stream's ingress during the grace,
- * plus the snapshot and the frame in flight — not a hard allocation cap.
- */
 class ReaderWriter {
     socket;
     limits;
     drop;
-    /** Lines not yet handed to the socket; `live` marks the ones the budget counts. */
     queue = [];
-    /** Bytes queued since the snapshot finished enqueuing; the budgeted part. */
     liveBytes = 0;
     live = false;
     running = false;
     closeAfterFlush = false;
-    /** Armed while the live queue is over budget; fires the drop if it still is. */
     overBudget = null;
-    /** Bytes of the line being pumped that have not yet been handed to the socket. */
     activeRemaining = 0;
     constructor(socket, limits, drop) {
         this.socket = socket;
         this.limits = limits;
         this.drop = drop;
     }
-    /**
-     * Unflushed bytes for this reader: queued lines, the unwritten rest of the
-     * line being pumped, and the socket's own buffer. A gauge of what is still
-     * owed to the socket, not of retained heap. A 5 MiB frame to a paused reader
-     * leaves the queue on its first chunk, so a queue-only gauge read 0 while
-     * almost all of it was still unflushed.
-     */
     get pendingBytes() {
         return this.queue.reduce((sum, line) => sum + line.bytes.length, 0) + this.activeRemaining + this.socket.writableLength;
     }
-    /** Everything enqueued from now on is a live event and counts against the budget. */
     startLive() { this.live = true; }
     write(line) {
         if (this.socket.destroyed)
@@ -156,12 +49,10 @@ class ReaderWriter {
         }
         void this.pump();
     }
-    /** FIN once everything queued has been handed to the socket. */
     end() {
         this.closeAfterFlush = true;
         void this.pump();
     }
-    /** Release the timers; the socket is gone. */
     dispose() {
         if (this.overBudget) {
             clearTimeout(this.overBudget);
@@ -216,7 +107,6 @@ class ReaderWriter {
             this.running = false;
         }
     }
-    /** Resolve true on `'drain'`; false when the socket closed or the stall deadline passed. */
     drained() {
         return new Promise((resolve) => {
             const settle = (ok) => {
@@ -237,33 +127,18 @@ class ReaderWriter {
         });
     }
 }
-/**
- * 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();
     writers = new Map();
     limits;
-    /** Readers dropped for queueing live bytes past the budget. Observability. */
     droppedForBacklog = 0;
-    /** Readers dropped for not draining a chunk within the stall deadline. Observability. */
     droppedForStall = 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, limits = {}) {
         this.hub = hub;
         this.socketPathOverride = socketPathOverride;
@@ -274,15 +149,11 @@ export class FeedHubServer {
             drainStallMs: limits.drainStallMs ?? HUB_DRAIN_STALL_MS,
             chunkBytes: limits.chunkBytes ?? HUB_WRITE_CHUNK_BYTES,
         };
-        // 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)
@@ -292,9 +163,7 @@ export class FeedHubServer {
             writer.end();
         }
     }
-    /** Subscribers currently connected. Observability + tests. */
     get clientCount() { return this.detachers.size; }
-    /** Bytes queued for every reader and not yet handed to a socket. Observability + tests. */
     get pendingBytes() {
         let total = 0;
         for (const writer of this.writers.values())
@@ -308,15 +177,12 @@ export class FeedHubServer {
         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 */ }
+            catch { }
         }
         this.server = net.createServer((socket) => {
-            // The scope line is REQUIRED and must arrive within the grace window.
             const grace = setTimeout(() => reject(`no scope line within ${HUB_HANDSHAKE_GRACE_MS}ms`), HUB_HANDSHAKE_GRACE_MS);
             grace.unref();
             const end = () => {
@@ -328,8 +194,6 @@ export class FeedHubServer {
                 this.writers.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);
             const writer = new ReaderWriter(socket, this.limits, (reason, message) => {
                 if (socket.destroyed)
@@ -338,13 +202,9 @@ export class FeedHubServer {
                     this.droppedForBacklog += 1;
                 else
                     this.droppedForStall += 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
-                // queued bytes now. 'close' fires and detaches it.
                 socket.destroy(new Error(message));
             });
             this.writers.set(socket, writer);
-            /** Refuse this reader, telling it why rather than hanging up silently. */
             const reject = (reason) => {
                 clearTimeout(grace);
                 if (socket.destroyed)
@@ -356,15 +216,10 @@ export class FeedHubServer {
             const attach = (hub) => {
                 if (socket.destroyed || this.detachers.has(socket))
                     return;
-                // `subscribe` emits the catch-up snapshot synchronously before it
-                // returns, so every line enqueued until then is snapshot and the first
-                // live event can only ever queue behind it.
                 const detach = hub.subscribe((event) => writer.write(JSON.stringify(event)));
                 writer.startLive();
                 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);
             };
@@ -372,8 +227,6 @@ export class FeedHubServer {
             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;
@@ -399,8 +252,6 @@ export class FeedHubServer {
                     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;
                 }
@@ -414,11 +265,6 @@ export class FeedHubServer {
                 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) {
@@ -443,9 +289,6 @@ export class FeedHubServer {
     async stop() {
         for (const detach of this.detachers.values())
             detach();
-        // Every connection, including one still in its handshake: `server.close`
-        // waits for open sockets, and a reader that never sent its scope line
-        // would otherwise hold the daemon's shutdown for the whole grace window.
         for (const [socket, writer] of this.writers) {
             writer.dispose();
             socket.destroy();
@@ -461,15 +304,6 @@ export class FeedHubServer {
         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 (;;) {
@@ -486,38 +320,17 @@ export async function waitForHub(endpoint = feedHubEndpoint(), deadlineMs = 10_0
         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.
- *
- * Also rejects on any close the caller did not ask for. The stream has no end
- * of its own — the hub serves it until the reader leaves — so a FIN that
- * arrives before `signal` aborts is the hub refusing, failing, or dropping this
- * reader, and a FIN inside a line is a frame the hub never finished. Resolving
- * there let `agents feed watch --json` exit 0 after 8 KiB of a 5 MB reset,
- * which is indistinguishable from an empty fleet.
- */
 export function streamFeedFromHub(options) {
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(options.endpoint ?? feedHubEndpoint());
         let aborted = false;
         let failure;
         const fail = (error) => { failure ??= error; socket.destroy(); };
-        // 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) => { failure ??= error; });
         const stop = () => { aborted = true; socket.destroy(); };
         options.signal.addEventListener('abort', stop, { once: true });
         if (options.signal.aborted)
             stop();
-        // Pieces of the line in progress; only the newest chunk is searched for a
-        // newline, so an 8 MB reset arriving in 64 KiB chunks is not rescanned from
-        // its start on every chunk.
         const partial = [];
         let partialBytes = 0;
         socket.setEncoding('utf-8');
@@ -549,11 +362,8 @@ export function streamFeedFromHub(options) {
                     fail(new Error(`feed hub sent a line that is not an envelope: ${line.slice(0, 80)}`));
                     return;
                 }
-                // Protocol only: an unversioned line is not a feed envelope.
                 if (event.v !== 1)
                     continue;
-                // A consumer that throws ends the read as a failure of THIS promise; left
-                // to escape the socket's 'data' handler it is an uncaught exception.
                 try {
                     options.emit(event);
                 }

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

@@ -1,93 +1,40 @@
 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;