@phnx-labs/agents-cli 1.22.114 → 1.22.116

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/feed.d.ts

@@ -23,7 +23,38 @@ export interface MessageReceipt {
     at: string;
     /** Optional sender label for the message. */
     from?: string;
+    /**
+     * The ask this receipt is ABOUT — the block generation live when the answer
+     * was sent. A block id is per SESSION, so it is reused by every generation of
+     * that session's questions; without this a late acknowledgement for question N
+     * is indistinguishable from one for question N+1 and would resolve the wrong
+     * ask (PHNX-3999). Carried durably on the queued message so it survives the
+     * process that sent it.
+     */
+    generation?: string;
+    /** The claim (attempt) this receipt is about — `AnswerRecord.answeredAt`. */
+    attempt?: string;
+}
+/** The ask a receipt or queued message belongs to, plus the attempt that sent it. */
+export interface ReceiptOrigin {
+    generation: string;
+    attempt: string;
 }
+/**
+ * Whether a receipt describes THIS ask.
+ *
+ * Identity is the GENERATION alone, never the attempt. The question is "does
+ * this receipt answer this ask?", and a second attempt on the same ask carries
+ * the same answer -- so a stranded claim that is adopted (which necessarily
+ * mints a new attempt) must still recognise the message its predecessor queued,
+ * or it enqueues a duplicate. `attempt` rides along as provenance for the
+ * delivery check, not as part of identity.
+ *
+ * An UNBOUND receipt (written before these fields existed) matches NOTHING: it
+ * cannot name an ask, so attributing it to one would let a message queued for an
+ * earlier question resolve whichever question is current (PHNX-3999).
+ */
+export declare function receiptMatchesOrigin(receipt: MessageReceipt, origin: ReceiptOrigin): boolean;
 export interface AnswerRecord {
     /** ISO-8601 timestamp of when the answer was recorded. */
     answeredAt: string;
@@ -267,7 +298,22 @@ export declare function recordAnswer(blockId: string, answer: {
     answeredFrom: string;
     operatorId?: string;
     verified?: boolean;
-}, root?: string): RecordAnswerResult;
+}, root?: string, options?: {
+    pending?: boolean;
+}): RecordAnswerResult;
+/**
+ * Promote a pending claim to a resolved answer — the second half of the
+ * two-phase answer protocol (see `recordAnswer`'s `pending` option).
+ *
+ * Called only once a rail has reported a real {@link MessageReceipt}: that is
+ * the point the item stops needing a human, so that is the point the tombstone
+ * is written and the card may leave the feed. An unconfirmed delivery never
+ * reaches here, so its card stays up.
+ */
+export declare function confirmAnswerResolution(blockId: string, root?: string, expected?: {
+    generation: string;
+    answeredAt: string;
+}): boolean;
 /** Read the answer record for a block, if one exists. */
 export declare function getAnswerRecord(blockId: string, root?: string): AnswerRecord | undefined;
 /**
@@ -277,6 +323,12 @@ export declare function getAnswerRecord(blockId: string, root?: string): AnswerR
  * restoring the attention lifecycle to the state another surface observed.
  */
 export declare function rollbackAnswerClaim(blockId: string, answeredAt: string, previousBlock: OpenBlock, previousResolution: AttentionResolution | undefined, root?: string): boolean;
+/**
+ * How long a release token may sit before it is treated as abandoned. A release
+ * is a handful of synchronous file operations, so anything this old belongs to a
+ * process that died holding it.
+ */
+export declare const RELEASE_TOKEN_STALE_MS = 60000;
 /** True when the block has already been answered. */
 export declare function isBlockAnswered(blockId: string, root?: string): boolean;
 /**
@@ -288,6 +340,14 @@ export declare function isBlockAnswered(blockId: string, root?: string): boolean
 export declare function recordMessageReceipt(blockId: string, receipt: MessageReceipt, root?: string): void;
 /** Read the receipt list for a block. */
 export declare function getBlockReceipts(blockId: string, root?: string): MessageReceipt[];
+/**
+ * The furthest-along receipt recorded for a block, or undefined when no rail
+ * ever reported one. This is the ONLY truthful evidence that an answer reached
+ * a delivery rail: an answer marker alone proves a claim was taken, not that
+ * anything was delivered, so a caller reporting on a block it did not deliver
+ * must read this rather than synthesize a receipt (PHNX-3999).
+ */
+export declare function latestMessageReceipt(blockId: string, root?: string, origin?: ReceiptOrigin): MessageReceipt | undefined;
 /** Mark a block as "continued" -- the agent consumed the answer and moved on. */
 export declare function recordContinued(blockId: string, root?: string): void;
 /** Mark a decision-class block as hard-parked (no safe default existed). */

package/dist/lib/feed/feed.js

@@ -23,12 +23,32 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as os from 'os';
 import * as yaml from 'yaml';
 import { stringifyDoc } from '../yaml-io.js';
 import { getFeedDir, getUserAgentsDir } from '../state.js';
 import { isAdmin, isHighConsequenceAllowed, isKnownOperator } from '../operator.js';
 import { projectKeyFromCwd } from '../project-key.js';
 import { atomicWriteJsonSync } from '../fs-atomic.js';
+/**
+ * Whether a receipt describes THIS ask.
+ *
+ * Identity is the GENERATION alone, never the attempt. The question is "does
+ * this receipt answer this ask?", and a second attempt on the same ask carries
+ * the same answer -- so a stranded claim that is adopted (which necessarily
+ * mints a new attempt) must still recognise the message its predecessor queued,
+ * or it enqueues a duplicate. `attempt` rides along as provenance for the
+ * delivery check, not as part of identity.
+ *
+ * An UNBOUND receipt (written before these fields existed) matches NOTHING: it
+ * cannot name an ask, so attributing it to one would let a message queued for an
+ * earlier question resolve whichever question is current (PHNX-3999).
+ */
+export function receiptMatchesOrigin(receipt, origin) {
+    if (receipt.generation === undefined)
+        return false;
+    return receipt.generation === origin.generation;
+}
 function resolutionDir(root) { return path.join(root, 'resolutions'); }
 /**
  * Canonical generation for a block. A writer that stamped `generation` wins;
@@ -129,7 +149,7 @@ export function readBlock(blockId, root) {
  * High-consequence blocks require a verified operator identity. Unverified
  * answers (no operatorId or not in the registry/allowed list) are refused.
  */
-export function recordAnswer(blockId, answer, root) {
+export function recordAnswer(blockId, answer, root, options = {}) {
     const dir = root ?? getFeedDir();
     const block = readBlock(blockId, dir);
     const operatorId = answer.operatorId;
@@ -187,24 +207,74 @@ export function recordAnswer(blockId, answer, root) {
         }
         throw err;
     }
-    // Marker created successfully -- mirror the answer into the block file and
-    // advance the lifecycle to `answered`. The resolution tombstone is written
-    // first, so if a stale lifecycle re-read races the block-file update the
-    // reconciler already refuses to resurrect this generation.
+    // Marker created successfully -- mirror the answer into the block file.
+    //
+    // A `pending` claim stops there: the claim is recorded so no second surface
+    // can take it, but the generation is NOT resolved and the lifecycle stays
+    // `open`, so the card remains in the operator's feed until a rail reports a
+    // real receipt (`confirmAnswerResolution`). A claim is not a delivery, and a
+    // claim whose delivery is never confirmed must not silently remove the item
+    // (PHNX-3999). `state` wins over `answer` in `deriveBlockState`, so the
+    // explicit `open` is what keeps the claimed block visible.
+    //
+    // The default one-phase path advances straight to `answered` for surfaces
+    // that resolve atomically (a policy default, a synchronous enqueue). The
+    // resolution tombstone is written first, so if a stale lifecycle re-read races
+    // the block-file update the reconciler already refuses to resurrect this
+    // generation.
     if (block) {
-        recordResolution({
-            blockId,
-            generation: blockGeneration(block),
-            resolvedAt: record.answeredAt,
-            sourceCursor: block.sourceCursor,
-            reason: 'answered',
-        }, dir);
+        if (!options.pending) {
+            recordResolution({
+                blockId,
+                generation: blockGeneration(block),
+                resolvedAt: record.answeredAt,
+                sourceCursor: block.sourceCursor,
+                reason: 'answered',
+            }, dir);
+        }
         block.answer = record;
-        block.state = 'answered';
+        block.state = options.pending ? 'open' : 'answered';
         publishBlock(block, dir);
     }
     return { ok: true };
 }
+/**
+ * Promote a pending claim to a resolved answer — the second half of the
+ * two-phase answer protocol (see `recordAnswer`'s `pending` option).
+ *
+ * Called only once a rail has reported a real {@link MessageReceipt}: that is
+ * the point the item stops needing a human, so that is the point the tombstone
+ * is written and the card may leave the feed. An unconfirmed delivery never
+ * reaches here, so its card stays up.
+ */
+export function confirmAnswerResolution(blockId, root, expected) {
+    const dir = root ?? getFeedDir();
+    const block = readBlock(blockId, dir);
+    const record = getAnswerRecord(blockId, dir);
+    if (!block || !record)
+        return false;
+    // One block id serves every generation of a session's asks, so a slow
+    // delivery for the PREVIOUS question must not resolve the one the agent has
+    // moved on to. A caller that knows which ask and which attempt it is
+    // confirming says so, and a mismatch is a no-op rather than a wrong tombstone.
+    // Bound to the ASK. The attempt is deliberately NOT compared: adopting a
+    // stranded claim mints a new attempt for the same question, and that adoption
+    // must still be able to resolve the ask it completed. The generation is what
+    // distinguishes one question from the next, which is the actual hazard.
+    if (expected && blockGeneration(block) !== expected.generation)
+        return false;
+    recordResolution({
+        blockId,
+        generation: blockGeneration(block),
+        resolvedAt: record.answeredAt,
+        sourceCursor: block.sourceCursor,
+        reason: 'answered',
+    }, dir);
+    block.answer = record;
+    block.state = 'answered';
+    publishBlock(block, dir);
+    return true;
+}
 /** Read the answer record for a block, if one exists. */
 export function getAnswerRecord(blockId, root) {
     return safeReadJson(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
@@ -221,6 +291,31 @@ export function rollbackAnswerClaim(blockId, answeredAt, previousBlock, previous
     const current = safeReadJson(marker);
     if (!current || current.answeredAt !== answeredAt)
         return false;
+    // Read-compare-then-unlink is NOT atomic, and two callers releasing the SAME
+    // claim is a real interleaving: both pass the compare, the first unlinks and
+    // re-claims, then the second unlinks the FIRST'S fresh marker and both end up
+    // holding a claim. The release is therefore gated on an O_EXCL token keyed by
+    // the exact claim being released -- the same primitive `recordAnswer` uses, so
+    // exactly one caller can ever release a given `answeredAt` (PHNX-3999).
+    const release = path.join(answeredDir(dir), `${blockId}.${answeredAt.replace(/[^0-9A-Za-z]/g, '')}.release`);
+    if (!acquireReleaseToken(release))
+        return false;
+    const dropToken = () => {
+        try {
+            fs.unlinkSync(release);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    };
+    // Re-read INSIDE the token: a racer that released-and-re-claimed between our
+    // first read and the token acquisition would otherwise be clobbered.
+    const held = safeReadJson(marker);
+    if (!held || held.answeredAt !== answeredAt) {
+        dropToken();
+        return false;
+    }
     // Restore while the O_EXCL marker still excludes every other claimant. The
     // marker is removed LAST; once another writer can win recordAnswer, this
     // rollback has no state left to overwrite.
@@ -237,9 +332,79 @@ export function rollbackAnswerClaim(blockId, answeredAt, previousBlock, previous
                 throw error;
         }
     }
-    fs.unlinkSync(marker);
+    try {
+        fs.unlinkSync(marker);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // The token has done its job: this exact claim can never be released again,
+    // because the claim it names no longer exists. Leaving it would accumulate one
+    // dead file per released claim forever.
+    dropToken();
     return true;
 }
+/**
+ * How long a release token may sit before it is treated as abandoned. A release
+ * is a handful of synchronous file operations, so anything this old belongs to a
+ * process that died holding it.
+ */
+export const RELEASE_TOKEN_STALE_MS = 60_000;
+/**
+ * Take the O_EXCL token that serialises releasing one specific claim.
+ *
+ * The token MUST be recoverable: a process killed between creating it and
+ * finishing would otherwise wedge that claim forever, and "the answer can never
+ * be released again" is a worse failure than the race the token prevents. So the
+ * token records its owner and its age, and a token whose owner is provably gone
+ * (same host, no such pid) or which is simply stale is reclaimed once.
+ */
+function acquireReleaseToken(release) {
+    const mine = { pid: process.pid, host: os.hostname(), at: Date.now() };
+    const create = () => {
+        try {
+            const fd = fs.openSync(release, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
+            try {
+                fs.writeSync(fd, Buffer.from(JSON.stringify(mine), 'utf-8'));
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    };
+    if (create())
+        return true;
+    const held = safeReadJson(release);
+    const ageMs = held?.at ? Date.now() - held.at : Number.POSITIVE_INFINITY;
+    let ownerGone = false;
+    if (held?.host === mine.host && typeof held.pid === 'number') {
+        // Signal 0 probes liveness without delivering anything.
+        try {
+            process.kill(held.pid, 0);
+        }
+        catch {
+            ownerGone = true;
+        }
+    }
+    if (!ownerGone && ageMs < RELEASE_TOKEN_STALE_MS)
+        return false; // a live peer owns it
+    try {
+        fs.unlinkSync(release);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // Exactly one reclaimer wins the re-create; the rest see EEXIST and back off.
+    return create();
+}
 /** True when the block has already been answered. */
 export function isBlockAnswered(blockId, root) {
     return fs.existsSync(path.join(answeredDir(root ?? getFeedDir()), `${blockId}.json`));
@@ -277,11 +442,58 @@ export function recordMessageReceipt(blockId, receipt, root) {
     }
     block.receipts = receipts;
     publishBlock(block, dir);
+    // The AGENT's own acknowledgement is what resolves a pending claim: `queued`
+    // only says a rail took the answer, so it must never remove the card
+    // (PHNX-3999).
+    //
+    // The promotion is bound to the RECEIPT's own origin, not to whatever the
+    // block happens to hold now. Checking `block.answer` alone was not enough: if
+    // the agent moved to question N+1 AND that ask was itself claimed, a late
+    // acknowledgement for question N found a live claim and resolved the wrong
+    // question. `confirmAnswerResolution`'s own compare is what rejects it.
+    //
+    // An UNBOUND receipt never resolves. It cannot say which ask it acknowledges,
+    // so promoting it against whatever claim happens to be live would resolve the
+    // wrong question -- the exact failure this binding exists to prevent. Its
+    // delivery evidence is still recorded above; the card then clears through the
+    // ordinary session-advance path instead.
+    if ((receipt.status === 'consumed' || receipt.status === 'continued')
+        && receipt.generation !== undefined && block.answer) {
+        confirmAnswerResolution(blockId, dir, {
+            generation: receipt.generation, answeredAt: block.answer.answeredAt,
+        });
+    }
 }
 /** Read the receipt list for a block. */
 export function getBlockReceipts(blockId, root) {
     return readBlock(blockId, root)?.receipts ?? [];
 }
+/**
+ * The furthest-along receipt recorded for a block, or undefined when no rail
+ * ever reported one. This is the ONLY truthful evidence that an answer reached
+ * a delivery rail: an answer marker alone proves a claim was taken, not that
+ * anything was delivered, so a caller reporting on a block it did not deliver
+ * must read this rather than synthesize a receipt (PHNX-3999).
+ */
+export function latestMessageReceipt(blockId, root, origin) {
+    const all = getBlockReceipts(blockId, root);
+    // A block id is per SESSION, so its receipt list accumulates across every
+    // generation of that session's asks. Reading it unfiltered lets question N's
+    // receipt answer for question N+1 -- so a caller that knows which ask it is
+    // asking about passes the origin and sees only that ask's evidence.
+    const receipts = origin ? all.filter((receipt) => receiptMatchesOrigin(receipt, origin)) : all;
+    let best;
+    for (const receipt of receipts) {
+        if (!best) {
+            best = receipt;
+            continue;
+        }
+        const rank = RECEIPT_STATUS_RANK[receipt.status] - RECEIPT_STATUS_RANK[best.status];
+        if (rank > 0 || (rank === 0 && receipt.at >= best.at))
+            best = receipt;
+    }
+    return best;
+}
 /** Mark a block as "continued" -- the agent consumed the answer and moved on. */
 export function recordContinued(blockId, root) {
     const dir = root ?? getFeedDir();

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

@@ -0,0 +1,141 @@
+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>;