@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/fleet-shared-state.js

@@ -1,18 +1,3 @@
-/**
- * Non-secret daemon state exchanged over SSH between fleet devices (PHNX-4116).
- *
- * Each device owns exactly one file under `~/.agents/devices/<device>/`
- * (`daemon-state.json`, UNTRACKED in the user repo). A device writes its OWN
- * file locally; a PEER's file on this box is written only by the usage-sync
- * exchange — a headed daemon dials each peer with `agents __usage-ingest
- * --reply`, sending its own envelope on stdin and writing the peer's reply
- * envelope here stamped with `receivedAt`. The envelope used to ride the user
- * repo as a tracked file, which turned the shared store into 18k `chore(devices)`
- * commits and wedged every clone behind a `git fetch` that timed out; git now
- * carries only human-authored resources. OAuth/setup-token values never belong
- * here: auth publishes only a readiness verdict; the existing encrypted SSH
- * bundle push remains the one path that may carry secret material.
- */
 import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
@@ -21,7 +6,6 @@ import { atomicWriteFileSync, ensureLockTarget, withFileLock, withFileLockAsync
 import { getUserAgentsDir } from './state.js';
 export const FLEET_SHARED_STATE_VERSION = 1;
 export const FLEET_SHARED_STATE_FILE = 'daemon-state.json';
-/** Path owned by one device in the conflict-free tracked device-doc tree. */
 export function fleetSharedStatePath(device, userAgentsDir = getUserAgentsDir()) {
     assertValidDeviceName(device);
     return path.join(userAgentsDir, 'devices', device, FLEET_SHARED_STATE_FILE);
@@ -29,12 +13,6 @@ export function fleetSharedStatePath(device, userAgentsDir = getUserAgentsDir())
 function isRecord(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
-/**
- * Validate an already-parsed envelope. `owner` pins the `device` field when the
- * caller knows whose envelope this must be (a file under `devices/<owner>/`);
- * an envelope arriving over the exchange names its own owner, so the caller
- * passes none and checks `device` against the dialed peer afterwards.
- */
 export function parseFleetSharedDeviceStateEnvelope(parsed, owner) {
     if (!isRecord(parsed) || parsed.version !== FLEET_SHARED_STATE_VERSION || typeof parsed.device !== 'string' || !parsed.device) {
         throw new Error('unrecognized shared-state envelope');
@@ -67,12 +45,6 @@ export function parseFleetSharedDeviceStateEnvelope(parsed, owner) {
 function parseFleetSharedDeviceState(raw, owner) {
     return parseFleetSharedDeviceStateEnvelope(JSON.parse(raw), owner);
 }
-/**
- * Merge one daemon-owned field into this device's shared file under a real
- * inter-process lock. Stable serialization avoids dirtying the user repo when
- * neither usage nor auth state changed.
- */
-/** Merge `patch` onto the current on-disk state; returns the serialized next state, or null when unchanged. Shared by the sync and async writers. */
 function mergeFleetState(currentRaw, device, patch) {
     let current = { version: FLEET_SHARED_STATE_VERSION, device };
     const trimmed = currentRaw.trim();
@@ -80,8 +52,9 @@ function mergeFleetState(currentRaw, device, patch) {
         try {
             current = parseFleetSharedDeviceState(trimmed, device);
         }
-        catch { /* owning device repairs its own malformed file; peers are never repaired here */ }
+        catch { }
     }
+    // Patches merge fieldwise so a partial peer update cannot erase unrelated state.
     const next = {
         ...current,
         ...(patch.usage !== undefined ? { usage: patch.usage } : {}),
@@ -103,7 +76,7 @@ export function updateFleetSharedDeviceState(device, patch, userAgentsDir = getU
         try {
             raw = fs.readFileSync(file, 'utf-8');
         }
-        catch { /* missing → treat as empty */ }
+        catch { }
         const { serialized, changed } = mergeFleetState(raw, device, patch);
         if (!changed)
             return { changed: false, path: file };
@@ -127,7 +100,7 @@ export async function updateFleetSharedDeviceStateAsync(device, patch, userAgent
         try {
             raw = await fsp.readFile(file, 'utf-8');
         }
-        catch { /* missing → treat as empty */ }
+        catch { }
         const { serialized, changed } = mergeFleetState(raw, device, patch);
         if (!changed)
             return { changed: false, path: file };
@@ -135,7 +108,6 @@ export async function updateFleetSharedDeviceStateAsync(device, patch, userAgent
         return { changed: true, path: file };
     });
 }
-/** Read every valid peer-owned state file; malformed peers fail separately. */
 export function readFleetSharedDeviceStates(userAgentsDir = getUserAgentsDir()) {
     const devicesDir = path.join(userAgentsDir, 'devices');
     let entries;
@@ -164,37 +136,19 @@ export function readFleetSharedDeviceStates(userAgentsDir = getUserAgentsDir())
     }
     return { states, errors };
 }
-/**
- * This device's own envelope as it stands on disk — what the usage-sync exchange
- * sends to peers and what `__usage-ingest --reply` prints back. A device that has
- * never published anything yields the bare `{version, device}` envelope, so a
- * peer still learns the device exists and answered.
- */
 export function readOwnFleetSharedDeviceState(device, userAgentsDir = getUserAgentsDir()) {
     const file = fleetSharedStatePath(device, userAgentsDir);
     let raw = '';
     try {
         raw = fs.readFileSync(file, 'utf-8');
     }
-    catch { /* never published → bare envelope */ }
+    catch { }
     if (!raw.trim())
         return { version: FLEET_SHARED_STATE_VERSION, device };
     const state = parseFleetSharedDeviceState(raw, device);
-    // `receivedAt` is a receiver-side stamp; the owner never advertises one.
     const { receivedAt: _receivedAt, ...own } = state;
     return own;
 }
-/**
- * Store a PEER's envelope, received over the SSH exchange, in that peer's file on
- * this box, stamped with `receivedAt`. Merges field-by-field onto whatever the
- * file already holds, so a partial envelope (a placement probe sends usage only)
- * refreshes that field without erasing the peer's last auth verdict, session
- * digests, or account rows. The five readers of `devices/<peer>/daemon-state.json`
- * (usage merge, poller claims, auth verdicts, session mirror, account catalog)
- * are unchanged by the transport swap. Async because it runs on the daemon's
- * usage-sync tick once per peer reply: the sync lock would `sleepSync` the event
- * loop for up to 30 s under contention (see {@link updateFleetSharedDeviceStateAsync}).
- */
 export async function storePeerFleetSharedDeviceState(state, userAgentsDir = getUserAgentsDir(), receivedAt = Date.now()) {
     const patch = { receivedAt };
     if (state.usage !== undefined)

package/dist/lib/fleet-status.d.ts

@@ -1,53 +1,26 @@
 import { type DeviceStats } from './devices/health.js';
-/** Live agent workload on a host. */
 export interface FleetAgentCounts {
-    /** Sessions actively working (status === 'running'). */
     running: number;
-    /** Total live sessions regardless of status (running/idle/input-required/…). */
     live: number;
-    /** Running count broken down by context: terminal / teams / cloud / headless. */
     byContext: Record<string, number>;
-    /** Running count broken down by agent CLI: claude / codex / cursor / … */
     byAgent: Record<string, number>;
 }
-/** One host's published status row. */
 export interface FleetStatusRow {
     host: string;
     agents: FleetAgentCounts;
-    /** Resource stats from the local probe; null when the probe produced nothing. */
     stats: DeviceStats | null;
-    /** Epoch ms this row was computed. */
     capturedAt: number;
 }
-/** Minimal shape needed to count workload — a subset of ActiveSession. */
 type CountableSession = {
     status?: string;
     context?: string;
     kind?: string;
     pidAlive?: boolean;
 };
-/**
- * Tally running-agent workload from a host's live sessions. "running" is the
- * actively-working set (`status === 'running'`); `live` is every session the
- * host is tracking. Pure so the tally is unit-tested without a live scan.
- */
 export declare function computeAgentCounts(sessions: ReadonlyArray<CountableSession>): FleetAgentCounts;
-/**
- * Probe THIS host's status — resource stats locally (no SSH) and agent workload
- * from the local live-session set (`getActiveSessions({ localOnly: true })`,
- * which never dials a remote host). Never throws: a failed sub-probe degrades to
- * null stats / zero counts.
- */
 export declare function probeLocalFleetStatus(host: string, now?: number): Promise<FleetStatusRow>;
 export declare function setFleetStatusMirrorPathForTest(mirrorPath: string | null): string | null;
-/** Read the whole fleet-status mirror (best-effort; missing/corrupt → empty). */
 export declare function readFleetStatus(): Record<string, FleetStatusRow>;
-/** Merge rows into the mirror (best-effort; preserves other hosts' rows). */
 export declare function writeFleetStatusRows(entries: Record<string, FleetStatusRow>): void;
-/**
- * Publish THIS host's row into the mirror (probe self, no SSH). The daemon calls
- * this on its warm tick; it is the whole of the daemon's fleet-status duty now
- * that cross-host probing is gone.
- */
 export declare function publishLocalFleetStatus(host: string): Promise<FleetStatusRow>;
 export {};

package/dist/lib/fleet-status.js

@@ -1,41 +1,9 @@
-/**
- * Per-host fleet-status rows: this machine's resource stats PLUS its live agent
- * workload (running-agent count + per-context / per-agent breakdown), published
- * to a shared local mirror.
- *
- * ## Why this exists (RUSH-2061)
- *
- * The daemon's fleet-cache warm used to `loadFleetStats({ forceRefresh: true })`
- * every 3 minutes — an SSH resource probe of EVERY device. With N daemons each
- * probing N devices that is N² SSH round trips across the fleet every 3 minutes,
- * each a remote `uptime;vm_stat;nproc` compute with a timeout that (pre-RUSH-2114)
- * could orphan the remote child. This module replaces that with a
- * **publish-own / read-union** model:
- *
- *  - Each daemon probes ONLY ITSELF (`probeLocalFleetStatus`, no SSH) and writes
- *    its own row into the mirror. Zero cross-host SSH from the daemon → the N²
- *    probe is gone.
- *  - A READER (the `agents fleet status` command) unions the fleet's rows on
- *    demand — a bounded, kill-on-timeout SSH read of each peer's already-computed
- *    `--local` row (a cheap `cat`-equivalent, not a fresh remote probe) — and
- *    writes them into the same mirror. `readFleetStatus` then serves the union
- *    synchronously with no network at all.
- *
- * The mirror file matches the `stats-cache` / `auth-health` convention exactly:
- * `{ version: 1, entries: Record<host, FleetStatusRow> }` under `getCacheDir()`,
- * keyed by `machineId()`, best-effort read/write that never throws.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
 import { probeLocalStats } from './devices/health.js';
 import { getActiveSessions } from './session/active.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
-/**
- * Tally running-agent workload from a host's live sessions. "running" is the
- * actively-working set (`status === 'running'`); `live` is every session the
- * host is tracking. Pure so the tally is unit-tested without a live scan.
- */
 export function computeAgentCounts(sessions) {
     const byContext = {};
     const byAgent = {};
@@ -53,12 +21,6 @@ export function computeAgentCounts(sessions) {
     }
     return { running, live, byContext, byAgent };
 }
-/**
- * Probe THIS host's status — resource stats locally (no SSH) and agent workload
- * from the local live-session set (`getActiveSessions({ localOnly: true })`,
- * which never dials a remote host). Never throws: a failed sub-probe degrades to
- * null stats / zero counts.
- */
 export async function probeLocalFleetStatus(host, now = Date.now()) {
     const [stats, sessions] = await Promise.all([
         probeLocalStats(host).catch(() => null),
@@ -71,7 +33,6 @@ export async function probeLocalFleetStatus(host, now = Date.now()) {
         capturedAt: now,
     };
 }
-/** Test seam for the mirror path (see usage.ts `setClaudeUsageCachePathForTest`). */
 let mirrorPathOverride = null;
 export function setFleetStatusMirrorPathForTest(mirrorPath) {
     const prev = mirrorPathOverride;
@@ -81,7 +42,6 @@ export function setFleetStatusMirrorPathForTest(mirrorPath) {
 function mirrorPath() {
     return mirrorPathOverride ?? path.join(getCacheDir(), '.fleet-status.json');
 }
-/** Read the whole fleet-status mirror (best-effort; missing/corrupt → empty). */
 export function readFleetStatus() {
     try {
         const parsed = JSON.parse(fs.readFileSync(mirrorPath(), 'utf-8'));
@@ -89,11 +49,9 @@ export function readFleetStatus() {
             return parsed.entries;
     }
     catch {
-        // missing or corrupt — treat as empty
     }
     return {};
 }
-/** Merge rows into the mirror (best-effort; preserves other hosts' rows). */
 export function writeFleetStatusRows(entries) {
     try {
         const target = mirrorPath();
@@ -107,14 +65,8 @@ export function writeFleetStatusRows(entries) {
         });
     }
     catch {
-        // best-effort; a failed write just means the reader sees an older union
     }
 }
-/**
- * Publish THIS host's row into the mirror (probe self, no SSH). The daemon calls
- * this on its warm tick; it is the whole of the daemon's fleet-status duty now
- * that cross-host probing is gone.
- */
 export async function publishLocalFleetStatus(host) {
     const row = await probeLocalFleetStatus(host);
     writeFleetStatusRows({ [host]: row });

package/dist/lib/format.d.ts

@@ -1,101 +1,27 @@
-/** Options for {@link die} — opt into machine-readable failure output. */
 interface DieOptions {
-    /**
-     * Emit a machine-readable `{"error", "hint"?}` object to **stdout** instead of
-     * red text on stderr. Pass `isJsonMode(options)` from a `--json` command so an
-     * agent parsing stdout gets a structured reason instead of an empty stream and
-     * a bare nonzero exit (RUSH-1830).
-     */
     json?: boolean;
-    /** Optional recovery hint — the command to run instead. Included in both modes. */
     hint?: string;
 }
-/**
- * Render a fatal error to the right stream. Pure — no I/O, no `process.exit` — so
- * the human-vs-agent split is unit-testable. A `--json` caller gets
- * `{"error","hint"?}` on **stdout** (where a JSON consumer reads); a human gets
- * red text (plus a gray hint line) on **stderr**.
- */
 export declare function formatDie(msg: string, opts?: DieOptions): {
     stream: 'stdout' | 'stderr';
     text: string;
 };
-/**
- * Print `msg` and exit the process with `code`. Humans get red text on stderr;
- * a `--json` caller (pass `{ json: true }`) gets `{"error","hint"?}` on stdout so
- * an agent has a parseable reason. Backward-compatible: `die(msg)` / `die(msg, code)`
- * keep the original red-stderr behavior.
- */
 export declare function die(msg: string, code?: number, opts?: DieOptions): never;
-/**
- * Await a command action and turn a thrown Error into a clean `die(message)`
- * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
- * rethrows plain Errors as engineering bugs, so a command whose helpers throw
- * user-actionable errors (auth, org) wraps its `.action(...)` call site with
- * this. The helpers keep throwing so tests can assert on them. Pass `json`
- * so a `--json` caller still gets the structured `{"error"}` payload.
- */
 export declare function runOrDie(fn: () => void | Promise<void>, opts?: DieOptions): Promise<void>;
-/**
- * `die()` with a structured friction event attached. Use this at CLI error
- * chokepoints so the nightly routine can classify and rank recurring failures
- * without re-parsing transcripts. `surface` is the subsystem (teams, browser,
- * secrets, guard, …); `failureId` is a stable slug (e.g. 'remote-cwd-on-add').
- */
 export declare function dieFriction(surface: string, failureId: string, msg: string, code?: number, opts?: DieOptions): never;
-/**
- * Truncate `s` to at most `max` characters, appending a single-char ellipsis
- * (`…`) when shortened. Character-count based (not ANSI/width aware — use
- * `truncateToWidth` from `session/width.ts` for colored strings).
- */
 export declare function truncate(s: string, max: number): string;
-/**
- * Format an ISO timestamp as a compact relative age: "just now", "5m ago",
- * "3h ago", "2d ago". The canonical short form — the long "5 minutes ago"
- * variant that once lived in `cloud.ts` is deliberately dropped. (For the
- * session-list long form with calendar fallback, see
- * `formatRelativeTime` in `session/relative-time.ts`.)
- */
 export declare function relTime(iso: string): string;
-/** Format a millisecond duration as "45s", "3m", "2h 5m", "1d 3h". */
 export declare function humanDuration(ms: number): string;
-/**
- * Human-readable byte size. Previously copy-pasted into five files
- * (`commands/prune.ts`, `commands/inspect.ts`,
- * `commands/sessions.ts`, `lib/browser/sessions-list.ts`) — this is the
- * canonical home.
- */
 export declare function formatBytes(n: number): string;
-/**
- * True when an error came from the user cancelling a prompt (Ctrl+C).
- *
- * Lives here rather than in `commands/utils.ts` so `lib/` callers
- * (`drift-sync.ts`, `refresh.ts`) don't have to import upward out of `lib/`
- * into the command layer. `commands/utils.ts` re-exports it.
- */
 export declare function isPromptCancelled(err: unknown): boolean;
-/** True when stdin/stdout are attached to a real terminal. */
 export declare function isInteractiveTerminal(): boolean;
-/** Parse a comma-separated CLI list, trimming whitespace and dropping empties. */
 export declare function parseCommaSeparatedList(value: string | undefined): string[];
-/**
- * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
- * wrappers). Matches the full CSI sequence including the `\x1b` escape.
- */
 export declare function visibleWidth(s: string): number;
-/** Pad `s` with trailing spaces to a target character width. */
 export declare function padRight(s: string, width: number): string;
-/** Pad `s` with trailing spaces to a target *visible* width (ANSI-aware). */
 export declare function padVisible(s: string, width: number): string;
-/** True when `--json` was passed. Piped stdout stays human-readable unless requested. */
 export declare function isJsonMode(opts: {
     json?: boolean;
 }): boolean;
-/** Read all of stdin synchronously and return it UTF-8 decoded and trimmed. */
 export declare function readStdinSync(): string;
-/**
- * Wrap `text` in an OSC 8 hyperlink to `filePath` (as a `file://` URL) when
- * stdout is a TTY; otherwise return `text` unchanged.
- */
 export declare function termLink(text: string, filePath: string): string;
 export {};

package/dist/lib/format.js

@@ -1,22 +1,8 @@
-/**
- * Shared terminal-formatting helpers.
- *
- * These small utilities were previously copy-pasted across ~20 command and lib
- * files, and had drifted into behavior differences (truncation ellipsis `...`
- * vs `…` vs `.`; `relTime` long "5 minutes ago" vs short "5m ago"; a
- * `visibleWidth` regex missing its `\x1b` escape). This module is the single
- * canonical home — every consumer imports from here.
- */
 import chalk from 'chalk';
 import { readSync } from 'node:fs';
 import { emitFriction } from './feed/events.js';
-/**
- * Render a fatal error to the right stream. Pure — no I/O, no `process.exit` — so
- * the human-vs-agent split is unit-testable. A `--json` caller gets
- * `{"error","hint"?}` on **stdout** (where a JSON consumer reads); a human gets
- * red text (plus a gray hint line) on **stderr**.
- */
 export function formatDie(msg, opts = {}) {
+    // Machine-readable failures belong on stdout; human failures belong on stderr.
     if (opts.json) {
         const payload = { error: msg };
         if (opts.hint)
@@ -28,31 +14,16 @@ export function formatDie(msg, opts = {}) {
         lines.push(chalk.gray(opts.hint));
     return { stream: 'stderr', text: lines.join('\n') };
 }
-/**
- * Print `msg` and exit the process with `code`. Humans get red text on stderr;
- * a `--json` caller (pass `{ json: true }`) gets `{"error","hint"?}` on stdout so
- * an agent has a parseable reason. Backward-compatible: `die(msg)` / `die(msg, code)`
- * keep the original red-stderr behavior.
- */
 export function die(msg, code = 1, opts = {}) {
     const { stream, text } = formatDie(msg, opts);
-    // Keep console.* (not process.std*.write): the suite spies on console.error /
-    // console.log to capture command output, and fd-level writes bypass those spies.
     if (stream === 'stdout')
         console.log(text);
     else
         console.error(text);
     process.exit(code);
 }
-/**
- * Await a command action and turn a thrown Error into a clean `die(message)`
- * instead of Node's raw stack dump — bootstrap's parseAsync catch deliberately
- * rethrows plain Errors as engineering bugs, so a command whose helpers throw
- * user-actionable errors (auth, org) wraps its `.action(...)` call site with
- * this. The helpers keep throwing so tests can assert on them. Pass `json`
- * so a `--json` caller still gets the structured `{"error"}` payload.
- */
 export async function runOrDie(fn, opts = {}) {
+    // Use at user-actionable command boundaries, not as an internal error-swallowing wrapper.
     try {
         await fn();
     }
@@ -60,31 +31,13 @@ export async function runOrDie(fn, opts = {}) {
         die(err instanceof Error ? err.message : String(err), 1, opts);
     }
 }
-/**
- * `die()` with a structured friction event attached. Use this at CLI error
- * chokepoints so the nightly routine can classify and rank recurring failures
- * without re-parsing transcripts. `surface` is the subsystem (teams, browser,
- * secrets, guard, …); `failureId` is a stable slug (e.g. 'remote-cwd-on-add').
- */
 export function dieFriction(surface, failureId, msg, code = 1, opts = {}) {
     emitFriction(surface, failureId, { error: msg });
     die(msg, code, opts);
 }
-/**
- * Truncate `s` to at most `max` characters, appending a single-char ellipsis
- * (`…`) when shortened. Character-count based (not ANSI/width aware — use
- * `truncateToWidth` from `session/width.ts` for colored strings).
- */
 export function truncate(s, max) {
     return s.length <= max ? s : s.slice(0, max - 1) + '…';
 }
-/**
- * Format an ISO timestamp as a compact relative age: "just now", "5m ago",
- * "3h ago", "2d ago". The canonical short form — the long "5 minutes ago"
- * variant that once lived in `cloud.ts` is deliberately dropped. (For the
- * session-list long form with calendar fallback, see
- * `formatRelativeTime` in `session/relative-time.ts`.)
- */
 export function relTime(iso) {
     const secs = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
     if (secs < 10)
@@ -97,7 +50,6 @@ export function relTime(iso) {
         return `${Math.floor(secs / 3600)}h ago`;
     return `${Math.floor(secs / 86400)}d ago`;
 }
-/** Format a millisecond duration as "45s", "3m", "2h 5m", "1d 3h". */
 export function humanDuration(ms) {
     const s = Math.floor(ms / 1000);
     if (s < 60)
@@ -113,12 +65,6 @@ export function humanDuration(ms) {
     const hh = h % 24;
     return hh ? `${d}d ${hh}h` : `${d}d`;
 }
-/**
- * Human-readable byte size. Previously copy-pasted into five files
- * (`commands/prune.ts`, `commands/inspect.ts`,
- * `commands/sessions.ts`, `lib/browser/sessions-list.ts`) — this is the
- * canonical home.
- */
 export function formatBytes(n) {
     if (n < 1024)
         return `${n} B`;
@@ -131,23 +77,14 @@ export function formatBytes(n) {
     }
     return `${size < 10 ? size.toFixed(1) : Math.round(size)} ${units[unit]}`;
 }
-/**
- * True when an error came from the user cancelling a prompt (Ctrl+C).
- *
- * Lives here rather than in `commands/utils.ts` so `lib/` callers
- * (`drift-sync.ts`, `refresh.ts`) don't have to import upward out of `lib/`
- * into the command layer. `commands/utils.ts` re-exports it.
- */
 export function isPromptCancelled(err) {
     return err instanceof Error && (err.name === 'ExitPromptError' ||
         err.message.includes('force closed') ||
         err.message.includes('User force closed'));
 }
-/** True when stdin/stdout are attached to a real terminal. */
 export function isInteractiveTerminal() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
-/** Parse a comma-separated CLI list, trimming whitespace and dropping empties. */
 export function parseCommaSeparatedList(value) {
     if (!value)
         return [];
@@ -156,28 +93,21 @@ export function parseCommaSeparatedList(value) {
         .map((item) => item.trim())
         .filter(Boolean);
 }
-/**
- * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
- * wrappers). Matches the full CSI sequence including the `\x1b` escape.
- */
 export function visibleWidth(s) {
     // eslint-disable-next-line no-control-regex
     return s.replace(/\x1b\[[0-9;]*m/g, '').length;
 }
-/** Pad `s` with trailing spaces to a target character width. */
 export function padRight(s, width) {
     return s.length >= width ? s : s + ' '.repeat(width - s.length);
 }
-/** Pad `s` with trailing spaces to a target *visible* width (ANSI-aware). */
 export function padVisible(s, width) {
     const w = visibleWidth(s);
     return w >= width ? s : s + ' '.repeat(width - w);
 }
-/** True when `--json` was passed. Piped stdout stays human-readable unless requested. */
 export function isJsonMode(opts) {
+    // Piped output stays human-readable unless the caller explicitly requests JSON.
     return Boolean(opts.json);
 }
-/** Read all of stdin synchronously and return it UTF-8 decoded and trimmed. */
 export function readStdinSync() {
     const chunks = [];
     const buf = Buffer.alloc(65536);
@@ -195,10 +125,6 @@ export function readStdinSync() {
     }
     return Buffer.concat(chunks).toString('utf-8').trim();
 }
-/**
- * Wrap `text` in an OSC 8 hyperlink to `filePath` (as a `file://` URL) when
- * stdout is a TTY; otherwise return `text` unchanged.
- */
 export function termLink(text, filePath) {
     if (!filePath || !process.stdout.isTTY)
         return text;

package/dist/lib/friction-heuristics.d.ts

@@ -1,32 +1,12 @@
-/**
- * Cheap heuristic readers over the `friction` event sink (emitFriction in
- * events.ts). Guard hooks (git-guard, rm-guard, git-require-clean-tree) call
- * `agents _internal friction --surface guard --id <failureId>` when they block
- * a destructive command, so it exists in the log — but nothing reads it back
- * yet. This is a starting point: one detector for the most actionable pattern,
- * an agent stuck retrying the SAME denied action instead of adapting.
- */
 import type { EventRecord } from './feed/events.js';
 interface RepeatedGuardBlockFinding {
-    /** Session id the repeated blocks happened in, or 'unknown' when the
-     *  friction event carried no session (e.g. a guard fired outside any
-     *  tracked agent session). */
     session: string;
     surface: string;
     failureId: string;
-    /** Number of times this exact (session, surface, failureId) blocked. */
     count: number;
     firstTs: string;
     lastTs: string;
 }
-/**
- * Group `friction` events by (session, surface, failureId) and flag groups
- * that repeat at least `minRepeats` times — the signature of an agent hitting
- * the same guard over and over rather than changing approach after the first
- * block. `events` is expected to already be filtered/queried for
- * `eventTypes: ['friction']` (see events.ts `query()`); non-friction records
- * are ignored defensively rather than assumed absent.
- */
 export declare function detectRepeatedGuardBlocks(events: EventRecord[], opts?: {
     minRepeats?: number;
 }): RepeatedGuardBlockFinding[];

package/dist/lib/friction-heuristics.js

@@ -1,14 +1,6 @@
 function asNonEmptyString(v) {
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-/**
- * Group `friction` events by (session, surface, failureId) and flag groups
- * that repeat at least `minRepeats` times — the signature of an agent hitting
- * the same guard over and over rather than changing approach after the first
- * block. `events` is expected to already be filtered/queried for
- * `eventTypes: ['friction']` (see events.ts `query()`); non-friction records
- * are ignored defensively rather than assumed absent.
- */
 export function detectRepeatedGuardBlocks(events, opts = {}) {
     const minRepeats = opts.minRepeats ?? 3;
     const groups = new Map();

package/dist/lib/fs-atomic.d.ts

@@ -1,64 +1,13 @@
 import * as fs from 'fs';
 export declare function sleepSync(ms: number): void;
-/**
- * Ensures the target file (and its parent directory) exist so proper-lockfile
- * can create a sibling .lock directory. Created with flag 'wx' so concurrent
- * creation races are safe (EEXIST is swallowed).
- */
 export declare function ensureLockTarget(filePath: string, initialContent?: string, dirMode?: number): void;
-/**
- * Writes content to filePath via a temp file + rename so readers never see a
- * partial write. On POSIX, rename(2) is atomic.
- */
 export declare function atomicWriteFileSync(filePath: string, content: string, options?: fs.WriteFileOptions): void;
-/**
- * Convenience wrapper around {@link atomicWriteFileSync} for the common case of
- * writing pretty-printed JSON (RUSH-2840). Same tmp-then-rename mechanics, same
- * caller responsibility to ensure the parent directory exists first — this adds
- * only the `JSON.stringify`.
- */
 export declare function atomicWriteJsonSync(filePath: string, data: unknown): void;
-/**
- * Async counterpart of {@link atomicWriteFileSync} for callers on the daemon's
- * shared event loop (PHNX-3695): a `writeFileSync`/`renameSync` on a tick freezes
- * every service and the browser IPC server until the disk write returns. Same
- * tmp-then-rename atomicity, but every syscall is awaited via `fs/promises`.
- */
 export declare function atomicWriteFile(filePath: string, content: string, options?: fs.WriteFileOptions): Promise<void>;
-/**
- * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
- * releases the lock. Retries with capped linear back-off until either the lock
- * is acquired or LOCK_ACQUIRE_TIMEOUT_MS elapses. Breaks stale locks older than
- * LOCK_STALE_MS, so a crashed holder never blocks past the stale window.
- *
- * `fn` is handed a `heartbeat()` it can call during a long, fully SYNCHRONOUS
- * critical section. proper-lockfile keeps a held lock "alive" by refreshing its
- * lockfile mtime on a `setTimeout` every `stale/2` — but that timer only fires
- * when the event loop gets a turn. A synchronous hold that outruns `stale`
- * (e.g. the scrypt-bound rotation loop in filestore.ts, ~16s on a real store)
- * never yields, so the timer cannot run: the lock ages past `stale` mid-hold and a
- * peer contending for it treats the live holder as crashed, breaks the lock, and
- * interleaves — corrupting the invariant the lock exists to protect, with no crash
- * involved. `heartbeat()` drives the same refresh synchronously (bumps the lockfile
- * mtime), so a long sync holder stays fresh while the short `stale` window still
- * detects a genuinely crashed holder within LOCK_STALE_MS. Callers whose critical
- * section is short (a single read-modify-write) can ignore it.
- */
 export interface FileLockOptions {
     staleMs?: number;
     acquireTimeoutMs?: number;
-    /** Lock a canonical absolute path before its file exists (e.g. a new installation record). */
     realpath?: boolean;
 }
 export declare function withFileLock<T>(filePath: string, fn: (heartbeat: () => void) => T, opts?: FileLockOptions): T;
-/**
- * Async counterpart of {@link withFileLock} for callers on the daemon's shared
- * event loop (PHNX-3695). The sync version retries acquisition with
- * {@link sleepSync} (`Atomics.wait`), which HALTS the thread for up to
- * {@link LOCK_ACQUIRE_TIMEOUT_MS} on contention — on a daemon tick that freezes
- * every service and the browser IPC server. This variant awaits proper-lockfile's
- * async `lock()` and yields with a real timer between retries, so the loop keeps
- * turning while a peer holds the lock. Same stale-break, same acquire budget,
- * same compromised-lock surfacing.
- */
 export declare function withFileLockAsync<T>(filePath: string, fn: (heartbeat: () => void) => Promise<T> | T, opts?: FileLockOptions): Promise<T>;