@phnx-labs/agents-cli 1.22.116 → 1.22.118

package/dist/lib/browser/paths.js

@@ -0,0 +1,51 @@
+/**
+ * paths.ts — the on-disk browser layout the CONSUMER still reads.
+ *
+ * browser-cli owns the browser process, drivers and IPC, but it keeps every
+ * on-disk path the in-repo subsystem used (integration contract §4). So
+ * `agents browser sessions` (`sessions-list.ts`) and the feed's browser tool
+ * rows (`feed/tool-activity.ts`) read a profile's captures straight off disk —
+ * no daemon, no engine — and need just these path helpers. They were the pure
+ * path corner of the deleted `profiles.ts` / `runtime-state.ts` engine files.
+ *
+ * A profile's live tasks and captures may live under a COMPOSITE runtime dir
+ * (`<profile>@<endpoint>`, `<profile>@<endpoint>.<fork>`), not the bare
+ * `<profile>` dir, so `listProfileCacheDirs` matches every dir that belongs to a
+ * profile — the same last-`@` rule browser-cli names them with.
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot } from '../state.js';
+export { getBrowserDurableDir } from '../state.js';
+/** Root of the browser runtime cache — `~/.agents/.cache/browser/`. */
+export function getBrowserRuntimeDir() {
+    return getBrowserRuntimeDirRoot();
+}
+/** The runtime cache dir for one profile's bare name. */
+export function getProfileRuntimeDir(name) {
+    return path.join(getBrowserRuntimeDir(), name);
+}
+/**
+ * The profile a runtime-cache dir key belongs to. browser-cli keys a dir as
+ * `<profile>`, `<profile>@<endpoint>`, or `<profile>@<endpoint>.<fork>`. The
+ * profile name may itself contain `@` (`me@work`), so split on the LAST one.
+ */
+function profileOfCacheKey(key) {
+    const at = key.lastIndexOf('@');
+    return at === -1 ? key : key.slice(0, at);
+}
+/**
+ * Every runtime-cache dir that belongs to a profile, composite forms included.
+ * Empty when the root does not exist yet.
+ */
+export function listProfileCacheDirs(profileName) {
+    const root = getBrowserRuntimeDir();
+    if (!fs.existsSync(root))
+        return [];
+    const matches = [];
+    for (const entry of fs.readdirSync(root)) {
+        if (profileOfCacheKey(entry) === profileName)
+            matches.push(path.join(root, entry));
+    }
+    return matches;
+}

package/dist/lib/browser/record.d.ts

@@ -0,0 +1,38 @@
+/**
+ * record.ts — turn the engine's NDJSON action events (fd 4) into the durable
+ * `browser_sessions` row that `agents browser sessions` and `agents sessions
+ * --browser` read to link a browser task back to the agent session that drove it.
+ *
+ * WHY THIS STAYS HERE. `sessions.db` is agents-cli state. Handing the standalone
+ * engine a writer for it would have made it a second author of the session index
+ * — precisely the "one engine, one executor" rule the repo holds elsewhere.
+ * Instead the engine reports what it did on fd 4 and agents-cli, which owns the
+ * store, records it.
+ *
+ * Before PHNX-4101 this upsert ran INSIDE the browser daemon at task start
+ * (`BrowserService.start` → `recordBrowserSession`), with the identity resolved
+ * in the calling CLI and forwarded over IPC. The engine now streams that identity
+ * back on fd 4 instead, and this CLI process — the one the user actually ran, so
+ * the actor is right — performs the upsert. The behavior is unchanged; only the
+ * trigger moved from an IPC call to a line on a pipe.
+ *
+ * The feed's browser tool rows are projected from the on-disk captures and the
+ * live `tasks.json` (`lib/feed/tool-activity.ts`), not from a per-action event
+ * ledger, so — unlike `lib/computer/record.ts` — this emits no feed event: the
+ * durable row is the whole job, and every consumer already reads it.
+ */
+import type { BrowserActionEvent } from '../browser-client.js';
+/**
+ * Record one action the engine performed. Never throws: the action already
+ * happened and already reported its own success or failure on the engine's
+ * stderr, so a bookkeeping failure must not turn a successful navigate into a
+ * failed command.
+ *
+ * Only an event that names a `task` AND a `profile` can be recorded — the
+ * `browser_sessions` row is keyed on `(profile, task)`. A task-less verb
+ * (`profiles list`, `status`) carries neither and is skipped, exactly as the old
+ * inline recorder only ran for task-scoped verbs.
+ */
+export declare function recordBrowserAction(event: BrowserActionEvent, opts?: {
+    device?: string;
+}): void;

package/dist/lib/browser/record.js

@@ -0,0 +1,57 @@
+/**
+ * record.ts — turn the engine's NDJSON action events (fd 4) into the durable
+ * `browser_sessions` row that `agents browser sessions` and `agents sessions
+ * --browser` read to link a browser task back to the agent session that drove it.
+ *
+ * WHY THIS STAYS HERE. `sessions.db` is agents-cli state. Handing the standalone
+ * engine a writer for it would have made it a second author of the session index
+ * — precisely the "one engine, one executor" rule the repo holds elsewhere.
+ * Instead the engine reports what it did on fd 4 and agents-cli, which owns the
+ * store, records it.
+ *
+ * Before PHNX-4101 this upsert ran INSIDE the browser daemon at task start
+ * (`BrowserService.start` → `recordBrowserSession`), with the identity resolved
+ * in the calling CLI and forwarded over IPC. The engine now streams that identity
+ * back on fd 4 instead, and this CLI process — the one the user actually ran, so
+ * the actor is right — performs the upsert. The behavior is unchanged; only the
+ * trigger moved from an IPC call to a line on a pipe.
+ *
+ * The feed's browser tool rows are projected from the on-disk captures and the
+ * live `tasks.json` (`lib/feed/tool-activity.ts`), not from a per-action event
+ * ledger, so — unlike `lib/computer/record.ts` — this emits no feed event: the
+ * durable row is the whole job, and every consumer already reads it.
+ */
+import { recordBrowserSession } from '../session/db.js';
+import { resolveActor } from '../actor.js';
+/**
+ * Record one action the engine performed. Never throws: the action already
+ * happened and already reported its own success or failure on the engine's
+ * stderr, so a bookkeeping failure must not turn a successful navigate into a
+ * failed command.
+ *
+ * Only an event that names a `task` AND a `profile` can be recorded — the
+ * `browser_sessions` row is keyed on `(profile, task)`. A task-less verb
+ * (`profiles list`, `status`) carries neither and is skipped, exactly as the old
+ * inline recorder only ran for task-scoped verbs.
+ */
+export function recordBrowserAction(event, opts = {}) {
+    if (typeof event.task !== 'string' || typeof event.profile !== 'string')
+        return;
+    // The driven machine. `host` is what a `--device` invocation stamps; `opts.device`
+    // is the fallback for an engine that drove the device this CLI resolved but did
+    // not echo it back. Both absent → a local run, recorded under this machine.
+    const machine = event.host ?? opts.device;
+    try {
+        recordBrowserSession({
+            task: event.task,
+            profile: event.profile,
+            sessionId: event.sessionId ?? process.env.AGENT_SESSION_ID ?? process.env.AGENTS_SESSION_ID,
+            launchId: event.launchId ?? process.env.AGENT_LAUNCH_ID,
+            actor: event.actor ?? resolveActor().id,
+            ...(machine ? { machine } : {}),
+        });
+    }
+    catch {
+        // Recording is best-effort; the action is already done.
+    }
+}

package/dist/lib/browser/sessions-list.js

@@ -20,8 +20,7 @@ import { formatBytes } from '../format.js';
 // Re-exported for the picker, which lists artifacts from this module's rows.
 export { formatBytes };
 import * as path from 'path';
-import { getBrowserRuntimeDir, getProfileRuntimeDir } from './profiles.js';
-import { listProfileCacheDirs } from './runtime-state.js';
+import { getBrowserRuntimeDir, getProfileRuntimeDir, listProfileCacheDirs } from './paths.js';
 import { formatRelativeTime } from '../session/relative-time.js';
 import { getSessionById, listBrowserSessionRecords, pruneToolSessions } from '../session/db.js';
 import { listPidSessionEntries } from '../session/pid-registry.js';

package/dist/lib/browser-client.d.ts

@@ -0,0 +1,158 @@
+/**
+ * browser-client.ts — the ONE process client through which agents-cli talks to
+ * the standalone `browser` CLI (@phnx-labs/browser-cli, PHNX-4101).
+ *
+ * This is the agents-owned half of the browser extraction, and it is
+ * deliberately small. agents-cli no longer carries the CDP/BiDi/Arc drivers, a
+ * browser IPC service, a chrome-data/profile store, a network-capture pipeline,
+ * or the remote SSH driving loop — the standalone engine owns all of it, exactly
+ * as `secrets` took the keychain engine (PHNX-3989), `computer` took the
+ * accessibility engine (PHNX-4075) and `sessions` took the transcript engine
+ * (PHNX-4012). What stays here is what only the fleet CLI can know: which device
+ * a `--device` name resolves to, whether this machine consents to being driven,
+ * who the acting session is, and where an action must be recorded.
+ *
+ * THERE IS NO FALLBACK. A missing executable throws `BROWSER_BIN_MISSING` with
+ * install guidance (DIST-1) rather than silently driving a bundled engine —
+ * agents-cli has none to drive, and a fallback would re-couple the two release
+ * trains this extraction exists to separate.
+ *
+ * Transport — inherited-fd passthrough, not request/response (matches
+ * browser-cli's `bin/browser.cjs` launcher, which forwards fds 3-16):
+ *
+ *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
+ *     stdout is the command's stdout, its `--json` is the command's `--json`,
+ *     its prompts reach a real tty. agents-cli never re-formats engine output,
+ *     which is what keeps the surface honest as the engine evolves.
+ *   - fd 3 (`BROWSER_CONTEXT_FD`) carries ONE JSON object — the consumer context
+ *     built by `lib/browser/context.ts` — written and closed immediately, so the
+ *     engine reads to EOF and proceeds. The document is read once, before command
+ *     parsing; a malformed one is a hard error, an absent one the standalone case.
+ *   - fd 4 (`BROWSER_EVENTS_FD`) carries NDJSON action events back: one JSON
+ *     object per line, each an action the engine actually performed. agents-cli
+ *     turns those into feed events and `sessions --browser` history
+ *     (`lib/browser/record.ts`). The engine may emit none; it must never block
+ *     on this pipe.
+ *
+ * Both fds are anonymous pipes on the child's side, the same shape
+ * `computer-client.ts` and `secrets-client.ts` settled on after a named FIFO
+ * wedged macOS reads. The context is pushed rather than pulled so the engine
+ * needs no callback into agents-cli — one direction each way, no reentrancy.
+ */
+/** fd the engine reads its one-shot JSON context from. */
+export declare const BROWSER_CONTEXT_FD = 3;
+/** fd the engine writes NDJSON action events to. */
+export declare const BROWSER_EVENTS_FD = 4;
+export declare class BrowserClientError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function isBrowserClientError(err: unknown): err is BrowserClientError;
+/**
+ * Accept only the real standalone `browser` executable, never agents-cli's own
+ * `browser` command shim (`exec "$AGENTS_BIN" browser`, `installations/shims.ts`)
+ * — resolving that would recurse into this process. `findInPath` already skips
+ * `~/.agents/.cache/shims`; this guard is the second line, mirroring
+ * `isStandaloneComputer` (agents-cli never shipped a `dist/browser.js` bin, but
+ * the check stays symmetric and future-proof against one).
+ */
+export declare function isStandaloneBrowser(bin: string): boolean;
+/**
+ * Resolve the standalone executable. `BROWSER_BIN` wins so a dev build can be
+ * driven without touching PATH.
+ *
+ * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims` — see
+ * `isStandaloneBrowser` for why that skip is load-bearing.
+ */
+export declare function resolveBrowserBin(): string;
+/** True when the standalone `browser` CLI is resolvable — the readiness signal
+ * for `agents setup` without a spawn. Never throws. */
+export declare function browserInstalled(): boolean;
+/** A `.js`/`.cjs`/`.mjs` bin is run through this runtime; a real executable is exec'd directly. */
+export declare function invocation(bin: string): {
+    command: string;
+    prefix: string[];
+};
+/**
+ * One action the engine performed, as it appears on the NDJSON events fd.
+ *
+ * This is the engine's wire shape (browser-cli integration contract §2), not a
+ * translation of it: the engine emits `{event: "browser.action", ts, command,
+ * invocationId, pid, task, profile, url, host, sessionId, launchId, actor}`.
+ * `command` — not `verb` — is the field that names the action, and it is what
+ * marks a line as an action event.
+ */
+export interface BrowserActionEvent {
+    /** Always `browser.action` on this stream. */
+    event?: string;
+    /** ISO timestamp the engine stamped. */
+    ts?: string;
+    /** The verb the engine ran (`navigate`, `screenshot`, `click`, …). */
+    command: string;
+    /** The engine's own id for this run — the grouping key for a session row. */
+    invocationId?: string;
+    /** The engine process's pid. */
+    pid?: number;
+    /** The browser task the action targeted. */
+    task?: string;
+    /** The browser profile the task runs under. */
+    profile?: string;
+    /** The page URL at the time of the action, when the engine reported one. */
+    url?: string;
+    /** The driven device for a `--device` invocation; absent when local. */
+    host?: string;
+    /** Identity, echoed back from the context this CLI handed the engine. */
+    sessionId?: string;
+    launchId?: string;
+    actor?: string;
+    /** Free-form detail the engine attaches. */
+    [key: string]: unknown;
+}
+/**
+ * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
+ * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
+ * trailing partial line carried forward — are unit-testable without a spawn.
+ *
+ * A malformed line is dropped, not thrown: these events are telemetry riding
+ * alongside a user-visible action that already happened. Failing the command
+ * because its receipt was unreadable would be strictly worse than losing the
+ * receipt. The action itself already failed loud on its own channel if it failed.
+ */
+export declare function parseEventLines(buffer: string): {
+    events: BrowserActionEvent[];
+    rest: string;
+};
+interface RunBrowserOptions {
+    /** argv handed to the standalone, after the program name. */
+    argv: string[];
+    /** The consumer context serialized onto fd 3. */
+    context: unknown;
+    /** Called once per action event the engine reports on fd 4. */
+    onEvent?: (event: BrowserActionEvent) => void;
+    /**
+     * Capture the engine's stdout instead of inheriting the terminal.
+     *
+     * Used only where agents-cli must READ an answer rather than show it (the
+     * setup readiness probe polling `status --json`). Verbs never capture:
+     * re-printing engine output would make agents-cli a formatter for a surface
+     * it no longer owns.
+     */
+    capture?: boolean;
+}
+interface RunBrowserResult {
+    exitCode: number;
+    /** Engine stdout, only when `capture` was set. */
+    stdout: string;
+}
+/**
+ * Run the standalone engine with the consumer context on fd 3 and the action
+ * event stream on fd 4. Resolves with the engine's exit code; the caller
+ * propagates it so `agents browser` exits exactly as the engine did.
+ *
+ * Throws `BROWSER_BIN_MISSING` when the standalone is not installed. Every other
+ * failure is the engine's own, reported on the inherited stderr.
+ */
+export declare function runBrowser(opts: RunBrowserOptions): Promise<RunBrowserResult>;
+/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
+export declare function _resetBrowserClientForTest(): void;
+export {};

package/dist/lib/browser-client.js

@@ -0,0 +1,234 @@
+/**
+ * browser-client.ts — the ONE process client through which agents-cli talks to
+ * the standalone `browser` CLI (@phnx-labs/browser-cli, PHNX-4101).
+ *
+ * This is the agents-owned half of the browser extraction, and it is
+ * deliberately small. agents-cli no longer carries the CDP/BiDi/Arc drivers, a
+ * browser IPC service, a chrome-data/profile store, a network-capture pipeline,
+ * or the remote SSH driving loop — the standalone engine owns all of it, exactly
+ * as `secrets` took the keychain engine (PHNX-3989), `computer` took the
+ * accessibility engine (PHNX-4075) and `sessions` took the transcript engine
+ * (PHNX-4012). What stays here is what only the fleet CLI can know: which device
+ * a `--device` name resolves to, whether this machine consents to being driven,
+ * who the acting session is, and where an action must be recorded.
+ *
+ * THERE IS NO FALLBACK. A missing executable throws `BROWSER_BIN_MISSING` with
+ * install guidance (DIST-1) rather than silently driving a bundled engine —
+ * agents-cli has none to drive, and a fallback would re-couple the two release
+ * trains this extraction exists to separate.
+ *
+ * Transport — inherited-fd passthrough, not request/response (matches
+ * browser-cli's `bin/browser.cjs` launcher, which forwards fds 3-16):
+ *
+ *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
+ *     stdout is the command's stdout, its `--json` is the command's `--json`,
+ *     its prompts reach a real tty. agents-cli never re-formats engine output,
+ *     which is what keeps the surface honest as the engine evolves.
+ *   - fd 3 (`BROWSER_CONTEXT_FD`) carries ONE JSON object — the consumer context
+ *     built by `lib/browser/context.ts` — written and closed immediately, so the
+ *     engine reads to EOF and proceeds. The document is read once, before command
+ *     parsing; a malformed one is a hard error, an absent one the standalone case.
+ *   - fd 4 (`BROWSER_EVENTS_FD`) carries NDJSON action events back: one JSON
+ *     object per line, each an action the engine actually performed. agents-cli
+ *     turns those into feed events and `sessions --browser` history
+ *     (`lib/browser/record.ts`). The engine may emit none; it must never block
+ *     on this pipe.
+ *
+ * Both fds are anonymous pipes on the child's side, the same shape
+ * `computer-client.ts` and `secrets-client.ts` settled on after a named FIFO
+ * wedged macOS reads. The context is pushed rather than pulled so the engine
+ * needs no callback into agents-cli — one direction each way, no reentrancy.
+ */
+import { spawn } from 'node:child_process';
+import { realpathSync, existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { findInPath } from './agent-spec/agents.js';
+const INSTALL_HINT = 'npm i -g @phnx-labs/browser-cli';
+/** fd the engine reads its one-shot JSON context from. */
+export const BROWSER_CONTEXT_FD = 3;
+/** fd the engine writes NDJSON action events to. */
+export const BROWSER_EVENTS_FD = 4;
+export class BrowserClientError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BrowserClientError';
+    }
+}
+export function isBrowserClientError(err) {
+    return err instanceof BrowserClientError;
+}
+let cachedBin;
+function browserEntrypoint(bin) {
+    if (!/\.(cmd|ps1)$/i.test(bin))
+        return bin;
+    const launcher = path.join(path.dirname(bin), 'node_modules', '@phnx-labs', 'browser-cli', 'bin', 'browser.cjs');
+    return existsSync(launcher) ? launcher : bin;
+}
+/**
+ * Accept only the real standalone `browser` executable, never agents-cli's own
+ * `browser` command shim (`exec "$AGENTS_BIN" browser`, `installations/shims.ts`)
+ * — resolving that would recurse into this process. `findInPath` already skips
+ * `~/.agents/.cache/shims`; this guard is the second line, mirroring
+ * `isStandaloneComputer` (agents-cli never shipped a `dist/browser.js` bin, but
+ * the check stays symmetric and future-proof against one).
+ */
+export function isStandaloneBrowser(bin) {
+    let real = browserEntrypoint(bin);
+    try {
+        real = realpathSync(real);
+    }
+    catch { /* spawn reports missing explicit paths */ }
+    return !/\.(cmd|ps1)$/i.test(real) && !real.endsWith(path.join('dist', 'browser.js'));
+}
+/**
+ * Resolve the standalone executable. `BROWSER_BIN` wins so a dev build can be
+ * driven without touching PATH.
+ *
+ * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims` — see
+ * `isStandaloneBrowser` for why that skip is load-bearing.
+ */
+export function resolveBrowserBin() {
+    if (cachedBin)
+        return cachedBin;
+    const explicit = process.env.BROWSER_BIN?.trim();
+    const resolved = explicit && explicit.length > 0 ? (isStandaloneBrowser(explicit) ? explicit : null) : findInPath('browser', { accept: isStandaloneBrowser });
+    if (!resolved) {
+        throw new BrowserClientError('BROWSER_BIN_MISSING', 'The standalone `browser` CLI was not found. Install it with:\n' +
+            `  ${INSTALL_HINT}\n` +
+            'or run `agents setup browser` / `agents clis install browser`, or point $BROWSER_BIN at its executable.');
+    }
+    cachedBin = browserEntrypoint(resolved);
+    return cachedBin;
+}
+/** True when the standalone `browser` CLI is resolvable — the readiness signal
+ * for `agents setup` without a spawn. Never throws. */
+export function browserInstalled() {
+    try {
+        resolveBrowserBin();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A `.js`/`.cjs`/`.mjs` bin is run through this runtime; a real executable is exec'd directly. */
+export function invocation(bin) {
+    if (/\.[mc]?js$/.test(bin))
+        return { command: process.execPath, prefix: [bin] };
+    return { command: bin, prefix: [] };
+}
+/**
+ * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
+ * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
+ * trailing partial line carried forward — are unit-testable without a spawn.
+ *
+ * A malformed line is dropped, not thrown: these events are telemetry riding
+ * alongside a user-visible action that already happened. Failing the command
+ * because its receipt was unreadable would be strictly worse than losing the
+ * receipt. The action itself already failed loud on its own channel if it failed.
+ */
+export function parseEventLines(buffer) {
+    const events = [];
+    const parts = buffer.split('\n');
+    const rest = parts.pop() ?? '';
+    for (const line of parts) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && typeof parsed.command === 'string') {
+                events.push(parsed);
+            }
+        }
+        catch {
+            // Unreadable receipt — see above.
+        }
+    }
+    return { events, rest };
+}
+/**
+ * Run the standalone engine with the consumer context on fd 3 and the action
+ * event stream on fd 4. Resolves with the engine's exit code; the caller
+ * propagates it so `agents browser` exits exactly as the engine did.
+ *
+ * Throws `BROWSER_BIN_MISSING` when the standalone is not installed. Every other
+ * failure is the engine's own, reported on the inherited stderr.
+ */
+export async function runBrowser(opts) {
+    const bin = resolveBrowserBin();
+    const { command, prefix } = invocation(bin);
+    const child = spawn(command, [...prefix, ...opts.argv], {
+        stdio: ['inherit', opts.capture ? 'pipe' : 'inherit', 'inherit', 'pipe', 'pipe'],
+        env: {
+            ...process.env,
+            BROWSER_CONTEXT_FD: String(BROWSER_CONTEXT_FD),
+            BROWSER_EVENTS_FD: String(BROWSER_EVENTS_FD),
+        },
+    });
+    const contextPipe = child.stdio[BROWSER_CONTEXT_FD];
+    const eventsPipe = child.stdio[BROWSER_EVENTS_FD];
+    if (contextPipe) {
+        // An engine that exits before reading the context (bad argv, `--help`)
+        // closes fd 3 and we get EPIPE. That is a normal race, not a failure.
+        contextPipe.on('error', () => { });
+        contextPipe.end(JSON.stringify(opts.context) + '\n');
+    }
+    let stdout = '';
+    if (opts.capture && child.stdout) {
+        child.stdout.setEncoding('utf-8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+    }
+    let pending = '';
+    const drained = new Promise((resolve) => {
+        if (!eventsPipe)
+            return resolve();
+        eventsPipe.setEncoding('utf-8');
+        eventsPipe.on('data', (chunk) => {
+            const { events, rest } = parseEventLines(pending + chunk);
+            pending = rest;
+            for (const event of events)
+                opts.onEvent?.(event);
+        });
+        eventsPipe.on('error', () => resolve());
+        eventsPipe.on('end', () => {
+            // A final line with no trailing newline still counts.
+            const { events } = parseEventLines(pending.endsWith('\n') ? pending : pending + '\n');
+            pending = '';
+            for (const event of events)
+                opts.onEvent?.(event);
+            resolve();
+        });
+    });
+    const exitCode = await new Promise((resolve, reject) => {
+        child.on('error', (err) => {
+            reject(new BrowserClientError('BROWSER_SPAWN_FAILED', `Could not run \`${bin}\`: ${err.message}`));
+        });
+        child.on('close', (code, signal) => {
+            // A signalled child has no exit code; report the conventional 128+n so
+            // callers and shells see a non-zero status instead of a false success.
+            if (code == null)
+                return resolve(signal ? 128 + (osSignalNumber(signal) ?? 0) : 1);
+            resolve(code);
+        });
+    });
+    await drained;
+    return { exitCode, stdout };
+}
+/** Signal name → number for the 128+n exit convention. Only the ones a tunnelled
+ * or interrupted engine realistically dies on; anything else contributes 0 and
+ * still yields a non-zero status. */
+function osSignalNumber(signal) {
+    const table = {
+        SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGPIPE: 13, SIGTERM: 15,
+    };
+    return table[signal];
+}
+/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
+export function _resetBrowserClientForTest() {
+    cachedBin = undefined;
+}

package/dist/lib/channels/owner-sink.d.ts

@@ -1,27 +1,10 @@
 import type { Meta } from '../types.js';
-/** Why the owner sink cannot deliver from this box. */
-export type OwnerSinkReason = 'rush-not-on-path' | 'rush-signed-out';
+export type OwnerSinkReason = 'imessage-not-macos' | 'slack-no-token' | 'channel-unsupported';
 export interface OwnerSinkStatus {
-    /** Owner delivery is configured for this fleet (humans.yaml / notify.owner).
-     *  When false, no finding is emitted — an un-opted-in box is not "broken". */
     configured: boolean;
-    /** This box can actually deliver an owner notification right now. */
     reachable: boolean;
-    /** Resolved owner channel (e.g. `imessage`). */
     channel?: string;
-    /** Resolved transport after `notify.transports` mapping (usually === channel). */
     transport?: string;
-    /** Set only when `reachable` is false. */
     reason?: OwnerSinkReason;
 }
-/**
- * Probe whether THIS box can deliver an owner notification right now. Returns
- * `configured:false` (and the caller emits no finding) when the fleet has no
- * owner channel configured — an un-opted-in box is not broken. When configured,
- * reports whether the resolved transport can actually deliver from here.
- *
- * Only the concrete rush-backed failure the lane hits is reported as unreachable;
- * non-rush transports (desktop / mailbox / …) deliver locally and are treated as
- * reachable rather than probed, so this never invents a critical it cannot back.
- */
 export declare function probeOwnerSink(meta: Meta): Promise<OwnerSinkStatus>;