@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/daemon/daemon.test-fixture.d.ts

@@ -1,22 +1,3 @@
-/**
- * Shared fixture for the daemon.*.test.ts suite slices (RUSH-2819).
- *
- * daemon.test.ts was a single 2201-line file (88 tests, ~112s in CI) — the
- * slowest file in the daemon test-ownership group, serializing an entire
- * vitest fork while every other selected file finished. The suite is split
- * into topical slices so per-file fork parallelism can spread the
- * process-spawning / real-daemon integration tests across workers; the
- * helpers shared by more than one slice live here.
- */
-/**
- * Isolates every slice against a fresh, empty standalone `secrets` store
- * (PHNX-3989) — an in-process fake keychain can no longer serve reads, since
- * the client always spawns the real standalone, and several slices here also
- * spawn a REAL `__daemon-run` subprocess that must see the SAME isolated
- * store (a fresh `SECRETS_HOME` covers both: `useFreshSecretsHome` sets it as
- * a `process.env` var, which every spawned child inherits by default). Call
- * once at the top level of each slice file.
- */
 export declare function installKeychainHermeticity(): void;
 export declare const REPO_ROOT: string;
 export declare const DIST_ENTRY: string;

package/dist/lib/daemon/daemon.test-fixture.js

@@ -4,25 +4,6 @@ import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { deleteBundleSync, _resetSecretsClientForTest } from '../secrets-client.js';
-/**
- * Shared fixture for the daemon.*.test.ts suite slices (RUSH-2819).
- *
- * daemon.test.ts was a single 2201-line file (88 tests, ~112s in CI) — the
- * slowest file in the daemon test-ownership group, serializing an entire
- * vitest fork while every other selected file finished. The suite is split
- * into topical slices so per-file fork parallelism can spread the
- * process-spawning / real-daemon integration tests across workers; the
- * helpers shared by more than one slice live here.
- */
-/**
- * Isolates every slice against a fresh, empty standalone `secrets` store
- * (PHNX-3989) — an in-process fake keychain can no longer serve reads, since
- * the client always spawns the real standalone, and several slices here also
- * spawn a REAL `__daemon-run` subprocess that must see the SAME isolated
- * store (a fresh `SECRETS_HOME` covers both: `useFreshSecretsHome` sets it as
- * a `process.env` var, which every spawned child inherits by default). Call
- * once at the top level of each slice file.
- */
 export function installKeychainHermeticity() {
     let home = '';
     let saved;
@@ -36,7 +17,7 @@ export function installKeychainHermeticity() {
         try {
             deleteBundleSync('claude');
         }
-        catch { /* not created */ }
+        catch { }
         if (saved === undefined)
             delete process.env.SECRETS_HOME;
         else
@@ -45,9 +26,5 @@ export function installKeychainHermeticity() {
         fs.rmSync(home, { recursive: true, force: true });
     });
 }
-// The real compiled CLI entry, shared by every slice that drives an actual
-// `__daemon-run` subprocess (lifecycle/registry/stop). Computed relative to
-// this file's own location, which stays in src/lib/daemon/ alongside every
-// slice, so the path math is unaffected by the split.
 export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
 export const DIST_ENTRY = path.join(REPO_ROOT, 'dist', 'index.js');

package/dist/lib/daemon/device-probe-service.d.ts

@@ -1,19 +1,3 @@
-/**
- * Device-probe tick as a `PeriodicService` (RUSH-3193 P3).
- *
- * Refreshes registered devices' reachability and detects newly appeared
- * tailnet nodes, dropping a sentinel per pending device so the menu-bar helper
- * can surface "NEW DEVICES -> Register / Ignore". Refresh mode never
- * auto-registers a newcomer; a machine without tailscale is a clean no-op.
- * `reconcilePendingSentinels` re-subtracts the ignore-list AND the registered
- * roster, so a dismissed or already-known device is never re-surfaced. On
- * soft-fail (no tailscale) sentinels are still pruned so a hermetic test leak
- * cannot leave fleet boxes in NEW DEVICES forever.
- *
- * The supervisor fires an immediate tick on start (see `service.ts`), which
- * replaces the previous inline `void runDeviceProbeTick()` kick-off that
- * cleared any leftover pollution set without waiting for the first interval.
- */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
 export declare class DeviceProbeService extends BasePeriodicService {

package/dist/lib/daemon/device-probe-service.js

@@ -1,33 +1,13 @@
-/**
- * Device-probe tick as a `PeriodicService` (RUSH-3193 P3).
- *
- * Refreshes registered devices' reachability and detects newly appeared
- * tailnet nodes, dropping a sentinel per pending device so the menu-bar helper
- * can surface "NEW DEVICES -> Register / Ignore". Refresh mode never
- * auto-registers a newcomer; a machine without tailscale is a clean no-op.
- * `reconcilePendingSentinels` re-subtracts the ignore-list AND the registered
- * roster, so a dismissed or already-known device is never re-surfaced. On
- * soft-fail (no tailscale) sentinels are still pruned so a hermetic test leak
- * cannot leave fleet boxes in NEW DEVICES forever.
- *
- * The supervisor fires an immediate tick on start (see `service.ts`), which
- * replaces the previous inline `void runDeviceProbeTick()` kick-off that
- * cleared any leftover pollution set without waiting for the first interval.
- */
 import { BasePeriodicService } from './service.js';
-/** Matches the historical inline interval (daemon.ts DEVICE_PROBE_TICK_MS). */
 const DEVICE_PROBE_TICK_MS = 3 * 60_000;
-/** Hard cap per tick — a tailnet + reachability sweep, short enough that a hang never freezes the service for long. */
 const DEVICE_PROBE_DEADLINE_MS = 90_000;
 export class DeviceProbeService extends BasePeriodicService {
     id = 'device-probe';
     intervalMs = DEVICE_PROBE_TICK_MS;
     deadlineMs = DEVICE_PROBE_DEADLINE_MS;
     async onStart(_ctx) {
-        // No connections/handles to open — each tick performs a fresh soft sync.
     }
     async onStop() {
-        // Nothing to release — the supervisor's timer teardown is the only cleanup needed.
     }
     async onTick(ctx) {
         const { runDeviceSync } = await import('../devices/sync.js');

package/dist/lib/daemon/feed-stream-service.d.ts

@@ -1,18 +1,3 @@
-/**
- * The shared feed collector's lifecycle as a `DaemonService`.
- *
- * WHY THE DAEMON OWNS IT. Dialing every peer over ssh and holding those
- * connections open is an ACTION on the fleet, so by the repo's one-scheduler /
- * one-executor rule it belongs to the daemon and not to a UI surface. Before
- * this service, every consumer of `agents feed watch --json` ran its own
- * `watchFleetFeed`, which is N ssh children per peer for N readers. The daemon
- * runs one, and the readers attach over a socket (`feed/hub-server.ts`).
- *
- * The server binds on start, but the fan-out itself is DEMAND-GATED by the hub:
- * with no client connected there is no `watchFleetFeed`, so an idle box holds no
- * peer connections — the same idle-cost rule `SessionStateService` follows for
- * its gather.
- */
 import { BaseDaemonService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
 export declare class FeedStreamService extends BaseDaemonService {

package/dist/lib/daemon/feed-stream-service.js

@@ -1,18 +1,3 @@
-/**
- * The shared feed collector's lifecycle as a `DaemonService`.
- *
- * WHY THE DAEMON OWNS IT. Dialing every peer over ssh and holding those
- * connections open is an ACTION on the fleet, so by the repo's one-scheduler /
- * one-executor rule it belongs to the daemon and not to a UI surface. Before
- * this service, every consumer of `agents feed watch --json` ran its own
- * `watchFleetFeed`, which is N ssh children per peer for N readers. The daemon
- * runs one, and the readers attach over a socket (`feed/hub-server.ts`).
- *
- * The server binds on start, but the fan-out itself is DEMAND-GATED by the hub:
- * with no client connected there is no `watchFleetFeed`, so an idle box holds no
- * peer connections — the same idle-cost rule `SessionStateService` follows for
- * its gather.
- */
 import { BaseDaemonService } from './service.js';
 import { FeedHub } from '../feed/hub.js';
 import { FeedHubServer } from '../feed/hub-server.js';
@@ -21,11 +6,6 @@ export class FeedStreamService extends BaseDaemonService {
     id = 'feed-stream';
     server = null;
     async onStart(ctx) {
-        // Two collectors, one socket. The fleet hub holds one ssh child per peer plus
-        // this box's rows; the local hub is this box ONLY and cannot fan out, so a
-        // reader that wants just this machine never causes a peer dial. They are
-        // separate hubs rather than one filtered stream because demand must be
-        // separate too: a local-only reader must not start the fleet fan-out.
         const fleet = new FeedHub({ watch: watchFleetFeed });
         this.server = new FeedHubServer(fleet, undefined, sharedLocalFeedHub());
         await this.server.start();

package/dist/lib/daemon/harness-update-service.d.ts

@@ -1,36 +1,3 @@
-/**
- * Daemon harness-update service (PHNX-3940).
- *
- * Runs the automatic-update pass (`installations/update-runtime.ts`) on a
- * schedule so a managed, transactional npm harness (Claude, Codex, …) stays
- * current with no operator action, subject to the `updates.auto` /
- * `updates.<agent>.auto` switches and each installation's own update policy.
- *
- * The pass itself does real, synchronous filesystem work per installation —
- * staging an npm install into a sibling directory, `fs.renameSync`/`fs.cpSync`
- * swaps, `fs.rmSync` cleanup — potentially across several installations in one
- * tick. Running that inline on the daemon's own event loop would stall every
- * other service (browser IPC, the scheduler, monitors) for the
- * duration, the same class of problem `self-update-service.ts` solves for the
- * CLI's OWN upgrade by installing into a fresh process it then exits into.
- * Here there is no "exit and let the supervisor restart" option (the daemon
- * itself isn't what's being updated), so instead this tick SPAWNS a bounded
- * child (`agents __harness-update-run`) over a Node IPC channel and only waits
- * on that child — every sync fs call happens in the child's own event loop /
- * thread pool, never this one.
- *
- * Cancellation is COOPERATIVE and cross-platform (PHNX-3940). On the tick's
- * deadline or daemon shutdown — both delivered as the supervisor aborting the
- * tick's `AbortSignal` — the daemon does NOT force-kill the child (execFile's
- * `timeout`/`signal` would, unconditionally on Windows, mid-swap). It SENDS the
- * child an IPC cancel message; the child stops at its next safe boundary (see
- * `installations/update-cancellation.ts` + `update.ts`'s `shouldCancel`) and
- * exits on its own, and the daemon waits for that TRUE exit. A wedged child that
- * ignores the request past a generous grace — never the normal path, since the
- * child's own npm/probe work is bounded — is force-reaped only as an
- * orphan-prevention backstop, and that abnormal case is reported as a failure,
- * never as a clean pass.
- */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
 interface HarnessUpdateOutcome {
@@ -38,48 +5,22 @@ interface HarnessUpdateOutcome {
     reason?: string;
     exitCode?: number | null;
     stdout?: string;
-    /** True when the pass was asked to stop (deadline/shutdown) and did so cooperatively. */
     cancelled?: boolean;
 }
 export interface CooperativeChildResult {
     exitCode: number | null;
     stdout: string;
-    /** True when a cancel was requested during this child's life (deadline/shutdown). */
     cancelled: boolean;
 }
-/**
- * Dependency seam so tests can assert the tick's decision/spawn logic without
- * actually installing anything. Production always uses
- * {@link defaultHarnessUpdateDeps}.
- */
 export interface HarnessUpdateDeps {
     runAutoUpdatePass(signal: AbortSignal): Promise<CooperativeChildResult>;
 }
-/**
- * Spawn `command args` as a child over a Node IPC channel and drive it to a TRUE
- * completion, requesting a cooperative stop (never a kill) when `signal` aborts —
- * the supervisor aborts it on the tick's deadline OR on daemon shutdown.
- *
- * Resolves with the child's real exit code and captured output. Rejects only on:
- *   - a spawn failure (missing binary) — a genuine service failure; and
- *   - the child having to be force-reaped past the grace window, or dying to an
- *     external signal — never a clean pass, so the tick logs it as ERROR instead
- *     of reading a killed process as a completed update.
- *
- * A non-zero exit with no kill is resolved (not rejected): the pass exits
- * non-zero for a per-installation vendor error, which is a normal tick outcome.
- *
- * Exported for the real-subprocess cancellation tests.
- */
 export declare function driveCooperativeChild(command: string, args: string[], signal: AbortSignal, graceMs: number, spawnOpts?: {
     env?: NodeJS.ProcessEnv;
     cwd?: string;
+    cancelMsg?: object;
+    label?: string;
 }): Promise<CooperativeChildResult>;
-/**
- * Core decision + spawn, shared so a future on-demand trigger (mirroring
- * `triggerSelfUpdateInBackground`) can reuse it. Returns rather than throws —
- * the periodic tick logs the outcome and moves on either way.
- */
 export declare function runHarnessUpdateTick(ctx: DaemonContext, signal: AbortSignal, deps?: HarnessUpdateDeps): Promise<HarnessUpdateOutcome>;
 export declare class HarnessUpdateService extends BasePeriodicService {
     readonly id: DaemonServiceId;

package/dist/lib/daemon/harness-update-service.js

@@ -1,60 +1,10 @@
-/**
- * Daemon harness-update service (PHNX-3940).
- *
- * Runs the automatic-update pass (`installations/update-runtime.ts`) on a
- * schedule so a managed, transactional npm harness (Claude, Codex, …) stays
- * current with no operator action, subject to the `updates.auto` /
- * `updates.<agent>.auto` switches and each installation's own update policy.
- *
- * The pass itself does real, synchronous filesystem work per installation —
- * staging an npm install into a sibling directory, `fs.renameSync`/`fs.cpSync`
- * swaps, `fs.rmSync` cleanup — potentially across several installations in one
- * tick. Running that inline on the daemon's own event loop would stall every
- * other service (browser IPC, the scheduler, monitors) for the
- * duration, the same class of problem `self-update-service.ts` solves for the
- * CLI's OWN upgrade by installing into a fresh process it then exits into.
- * Here there is no "exit and let the supervisor restart" option (the daemon
- * itself isn't what's being updated), so instead this tick SPAWNS a bounded
- * child (`agents __harness-update-run`) over a Node IPC channel and only waits
- * on that child — every sync fs call happens in the child's own event loop /
- * thread pool, never this one.
- *
- * Cancellation is COOPERATIVE and cross-platform (PHNX-3940). On the tick's
- * deadline or daemon shutdown — both delivered as the supervisor aborting the
- * tick's `AbortSignal` — the daemon does NOT force-kill the child (execFile's
- * `timeout`/`signal` would, unconditionally on Windows, mid-swap). It SENDS the
- * child an IPC cancel message; the child stops at its next safe boundary (see
- * `installations/update-cancellation.ts` + `update.ts`'s `shouldCancel`) and
- * exits on its own, and the daemon waits for that TRUE exit. A wedged child that
- * ignores the request past a generous grace — never the normal path, since the
- * child's own npm/probe work is bounded — is force-reaped only as an
- * orphan-prevention backstop, and that abnormal case is reported as a failure,
- * never as a clean pass.
- */
 import { spawn } from 'child_process';
 import { BasePeriodicService } from './service.js';
 import { getCliLaunch, getAgentsBinPath } from '../cli-entry.js';
 import { HARNESS_UPDATE_CHILD_CMD, cancelMessage } from '../installations/update-cancellation.js';
-/** Runs every 15 minutes — a design decision, not an externally-fixed cadence (PHNX-3940). */
 const HARNESS_UPDATE_TICK_MS = 15 * 60_000;
-/**
- * Cancellation deadline per tick. A real pass can touch several installations, each an npm
- * install (`INSTALL_TIMEOUT_MS` = 120s in strategies.ts) plus two launch
- * probes; 10 minutes leaves headroom for a handful of harnesses in one pass
- * while staying comfortably under the 15-minute cadence above.
- */
 const HARNESS_UPDATE_DEADLINE_MS = 10 * 60_000;
-/** First tick fires 60 seconds after daemon boot — long enough for shims/PATH to settle, short enough that a fresh box doesn't wait a full interval for its first check. */
 const HARNESS_UPDATE_STARTUP_DELAY_MS = 60_000;
-/**
- * How long to wait for the child to exit AFTER a cooperative cancel before
- * force-reaping it as an orphan backstop. The child's own work is bounded — one
- * npm install (`INSTALL_TIMEOUT_MS` = 120s in strategies.ts) plus two launch
- * probes, then a fast synchronous swap — so a healthy child stops well within
- * this window. A slow staging/postinstall can also exhaust it, but a delivered
- * cancel prevents that stage from committing. The backstop kills the process
- * group on POSIX and the worker on Windows; the tick reports a failure.
- */
 const HARNESS_UPDATE_CANCEL_GRACE_MS = 3 * 60_000;
 function defaultHarnessUpdateDeps() {
     return {
@@ -64,30 +14,13 @@ function defaultHarnessUpdateDeps() {
         },
     };
 }
-/**
- * Spawn `command args` as a child over a Node IPC channel and drive it to a TRUE
- * completion, requesting a cooperative stop (never a kill) when `signal` aborts —
- * the supervisor aborts it on the tick's deadline OR on daemon shutdown.
- *
- * Resolves with the child's real exit code and captured output. Rejects only on:
- *   - a spawn failure (missing binary) — a genuine service failure; and
- *   - the child having to be force-reaped past the grace window, or dying to an
- *     external signal — never a clean pass, so the tick logs it as ERROR instead
- *     of reading a killed process as a completed update.
- *
- * A non-zero exit with no kill is resolved (not rejected): the pass exits
- * non-zero for a per-installation vendor error, which is a normal tick outcome.
- *
- * Exported for the real-subprocess cancellation tests.
- */
 export function driveCooperativeChild(command, args, signal, graceMs, spawnOpts = {}) {
+    const cancelMsg = spawnOpts.cancelMsg ?? cancelMessage();
+    const label = spawnOpts.label ?? 'harness-update';
     return new Promise((resolve, reject) => {
         let child;
         try {
             child = spawn(command, args, {
-                // stdio[3] = 'ipc' is the cancel channel. Detached on POSIX so the child
-                // leads its own process group and the backstop below can reap its whole
-                // npm subtree; the parent still waits on it (never unref'd).
                 stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
                 detached: process.platform !== 'win32',
                 windowsHide: true,
@@ -115,14 +48,10 @@ export function driveCooperativeChild(command, args, signal, graceMs, spawnOpts
             if (cancelRequested || settled)
                 return;
             cancelRequested = true;
-            // Cooperative: a message the child reads at its next safe boundary. NEVER a
-            // signal — that would interrupt a swap (and is fatal on Windows, which has
-            // no cooperative SIGTERM). If the channel is already gone the child's own
-            // `disconnect` handler cancels it, so a failed send is not an error.
             try {
-                child.send(cancelMessage(), () => { });
+                child.send(cancelMsg, () => { });
             }
-            catch { /* channel closed; disconnect handles it */ }
+            catch { }
             graceTimer = setTimeout(() => {
                 if (settled)
                     return;
@@ -137,7 +66,7 @@ export function driveCooperativeChild(command, args, signal, graceMs, spawnOpts
                     try {
                         child.kill('SIGKILL');
                     }
-                    catch { /* already gone */ }
+                    catch { }
                 }
             }, graceMs);
             graceTimer.unref?.();
@@ -163,7 +92,7 @@ export function driveCooperativeChild(command, args, signal, graceMs, spawnOpts
             settled = true;
             cleanup();
             if (forceReaped || sigName) {
-                reject(new Error(`harness-update child did not exit cooperatively after cancel `
+                reject(new Error(`${label} child did not exit cooperatively after cancel `
                     + `(${forceReaped ? `force-reaped after ${graceMs}ms grace` : `died to ${sigName}`}). `
                     + (stderr.slice(0, 500) || stdout.slice(0, 500) || 'no output')));
                 return;
@@ -172,11 +101,6 @@ export function driveCooperativeChild(command, args, signal, graceMs, spawnOpts
         });
     });
 }
-/**
- * Core decision + spawn, shared so a future on-demand trigger (mirroring
- * `triggerSelfUpdateInBackground`) can reuse it. Returns rather than throws —
- * the periodic tick logs the outcome and moves on either way.
- */
 export async function runHarnessUpdateTick(ctx, signal, deps = defaultHarnessUpdateDeps()) {
     try {
         const { exitCode, stdout, cancelled } = await deps.runAutoUpdatePass(signal);
@@ -203,12 +127,8 @@ export class HarnessUpdateService extends BasePeriodicService {
     deadlineMs = HARNESS_UPDATE_DEADLINE_MS;
     startupDelayMs = HARNESS_UPDATE_STARTUP_DELAY_MS;
     async onStart(_ctx) {
-        // No connections/handles to open — each tick spawns its own bounded child.
     }
     async onStop() {
-        // The in-flight child (if any) is asked to stop COOPERATIVELY: the supervisor
-        // aborts `signal` on the current tick, which `driveCooperativeChild` turns
-        // into an IPC cancel message, never a kill. Nothing else to release here.
     }
     async onTick(ctx, signal) {
         await runHarnessUpdateTick(ctx, signal);

package/dist/lib/daemon/heartbeat-service.d.ts

@@ -1,4 +1,3 @@
-/** Daemon heartbeat and routine-process reconciliation under supervision. */
 import type { DaemonServiceId } from '../daemon-services.js';
 import { BasePeriodicService, type DaemonContext } from './service.js';
 export declare class HeartbeatService extends BasePeriodicService {

package/dist/lib/daemon/heartbeat-service.js

@@ -1,4 +1,3 @@
-/** Daemon heartbeat and routine-process reconciliation under supervision. */
 import { reapExitedRunningJobs } from './runner.js';
 import { reapTerminalRoutineProcesses } from '../routine-process-cleanup.js';
 import { BasePeriodicService } from './service.js';

package/dist/lib/daemon/leaked-daemons.d.ts

@@ -1,60 +1,14 @@
-/**
- * The daemon state dir for an ARBITRARY home — the same layout state.ts's
- * DAEMON_DIR chain produces (`<home>/.agents/.cache/helpers/daemon`). A caller
- * under a redirected HOME (a test/e2e harness) uses this to find the REAL
- * install's daemon records. Kept here rather than exported from state.ts: any
- * edit to state.ts selects its entire static-import closure into the required
- * impact gate (186 files, 295s against the 240s budget, measured on this
- * change's first CI run), so the helper cannot live there without a
- * budget-policy change. If state.ts's layout ever moves, this must move with
- * it — the two are the same address.
- */
 export declare function getDaemonDirForHome(home: string): string;
-/** One live `__daemon-run` process from the box-wide `ps` scan. */
 export interface DaemonRunProcess {
     pid: number;
-    /** Owning uid from `ps`, or null when unavailable. */
     uid: number | null;
-    /** Whitespace-tokenized argv (`ps` renders it unquoted). */
     tokens: string[];
 }
-/**
- * Every live `__daemon-run` process on this box, regardless of which install
- * launched it or which state dir it serves. POSIX-only (uses `ps`); a no-op on
- * Windows.
- *
- * `getDaemonLaunch` always spawns `<node> <entry> __daemon-run` with nothing
- * after it — the ONLY argv `__daemon-run` ever appears in for a real daemon.
- * A substring/regex test anywhere in the full command line is not enough: an
- * `agents run claude "<prompt>"` invocation whose prompt happens to quote the
- * literal text `__daemon-run` (this ticket's own brief does) matches that test
- * too, and was observed producing false "duplicate daemon" rows. Requiring it
- * to be the LAST whitespace-delimited token is the actual invariant.
- *
- * This raw box-wide scan is deliberately NOT the duplicate-detection scope
- * (RUSH-2368): a `__daemon-run` under a different HOME serves a different
- * `getDaemonDir()` and is not a duplicate of THIS device's daemon, however
- * `ps` sees it — a leaked vitest fixture under its own `/tmp` HOME matched
- * this scan and was reported as a stray to `kill`. Callers attach their own
- * scope: `agents daemon status` gates on the instance registry,
- * {@link findLeakedDaemons} on the owner records above.
- */
 export declare function listDaemonRunProcesses(): DaemonRunProcess[];
-/** A `__daemon-run` process no owner record names. */
 export interface LeakedDaemon {
     pid: number;
-    /** The HOME the process runs under, or null when it cannot be read. */
     home: string | null;
-    /** The process's start time as `ps lstart` renders it, or null when unavailable. */
     startedAt: string | null;
-    /** The launch entry (the argv token before `__daemon-run`), best-effort. */
     entry: string | null;
 }
-/**
- * Every `__daemon-run` process running as THIS uid that no owner record names:
- * neither the service manager's unit main PID nor the recorded
- * `<daemonDir>/daemon.pid`. Each result carries the process's HOME and start
- * time so the report can show them. An empty list means no leak — including
- * the common stopped-daemon case, where there is simply nothing running.
- */
 export declare function findLeakedDaemons(): LeakedDaemon[];

package/dist/lib/daemon/leaked-daemons.js

@@ -1,68 +1,13 @@
-/**
- * Leaked-daemon detection (W4, PHNX-3736).
- *
- * One daemon per device is the contract: the always-on process behind
- * `agents __daemon-run` is either the service manager's unit main PID or the
- * pid recorded in `<daemonDir>/daemon.pid`. Anything else running
- * `__daemon-run` as this uid is a LEAK — a daemon nothing owns.
- *
- * The motivating incident ran 4+ days on yosemite-s1: a headless e2e session
- * launched a daemon under `HOME=/tmp/pin-e2e-<pid>` and never stopped it. The
- * pid-file takeover in `daemon.ts` could not see it because it keeps its own
- * pid file under the temp home, and `agents daemon status`'s duplicate scope
- * (`findSurvivingStateDirDaemons`, RUSH-2368) deliberately covers only this
- * install's state dir — so the leak was invisible to every existing surface.
- *
- * Why flagging a different-HOME daemon here is not the RUSH-2368 harm: that
- * incident taught that a `__daemon-run` under another HOME is not a DUPLICATE
- * of this device's daemon and must never be told to `kill` from the duplicate
- * path. This module does not accuse it of being a duplicate — it reports that
- * NO owner record (unit main PID, recorded daemon.pid) names the pid at all,
- * and shows the process's own HOME and start time so the operator can judge
- * before acting. A different uid is never named: we cannot inspect its
- * environment or signal it.
- */
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { productionDaemonServiceNames, readDaemonPid, readServiceManagerPid } from './daemon.js';
 import { getDaemonDir } from '../state.js';
-/**
- * The daemon state dir for an ARBITRARY home — the same layout state.ts's
- * DAEMON_DIR chain produces (`<home>/.agents/.cache/helpers/daemon`). A caller
- * under a redirected HOME (a test/e2e harness) uses this to find the REAL
- * install's daemon records. Kept here rather than exported from state.ts: any
- * edit to state.ts selects its entire static-import closure into the required
- * impact gate (186 files, 295s against the 240s budget, measured on this
- * change's first CI run), so the helper cannot live there without a
- * budget-policy change. If state.ts's layout ever moves, this must move with
- * it — the two are the same address.
- */
 export function getDaemonDirForHome(home) {
     return path.join(home, '.agents', '.cache', 'helpers', 'daemon');
 }
-/**
- * Every live `__daemon-run` process on this box, regardless of which install
- * launched it or which state dir it serves. POSIX-only (uses `ps`); a no-op on
- * Windows.
- *
- * `getDaemonLaunch` always spawns `<node> <entry> __daemon-run` with nothing
- * after it — the ONLY argv `__daemon-run` ever appears in for a real daemon.
- * A substring/regex test anywhere in the full command line is not enough: an
- * `agents run claude "<prompt>"` invocation whose prompt happens to quote the
- * literal text `__daemon-run` (this ticket's own brief does) matches that test
- * too, and was observed producing false "duplicate daemon" rows. Requiring it
- * to be the LAST whitespace-delimited token is the actual invariant.
- *
- * This raw box-wide scan is deliberately NOT the duplicate-detection scope
- * (RUSH-2368): a `__daemon-run` under a different HOME serves a different
- * `getDaemonDir()` and is not a duplicate of THIS device's daemon, however
- * `ps` sees it — a leaked vitest fixture under its own `/tmp` HOME matched
- * this scan and was reported as a stray to `kill`. Callers attach their own
- * scope: `agents daemon status` gates on the instance registry,
- * {@link findLeakedDaemons} on the owner records above.
- */
+// A real daemon has __daemon-run as the final argv token; prompt text containing it is not identity.
 export function listDaemonRunProcesses() {
     if (process.platform === 'win32')
         return [];
@@ -89,13 +34,6 @@ export function listDaemonRunProcesses() {
     }
     return found;
 }
-/**
- * The HOME of a live process, or null when unreadable. Linux reads
- * `/proc/<pid>/environ`; macOS has no equivalent zero-dependency primitive, so
- * it falls back to `ps -E`, which appends the environment to the command
- * column. Both are best-effort: a null HOME must never turn into an accusation
- * beyond "unknown".
- */
 function processHome(pid) {
     if (process.platform === 'linux') {
         try {
@@ -119,7 +57,6 @@ function processHome(pid) {
         return null;
     }
 }
-/** The start time of a live process as `ps lstart` renders it, or null (best-effort, POSIX only). */
 function processStartTime(pid) {
     if (process.platform === 'win32')
         return null;
@@ -131,13 +68,7 @@ function processStartTime(pid) {
         return null;
     }
 }
-/**
- * Every `__daemon-run` process running as THIS uid that no owner record names:
- * neither the service manager's unit main PID nor the recorded
- * `<daemonDir>/daemon.pid`. Each result carries the process's HOME and start
- * time so the report can show them. An empty list means no leak — including
- * the common stopped-daemon case, where there is simply nothing running.
- */
+// Different-HOME processes are not duplicates; report only this uid's pid absent from manager and real-HOME owner records.
 export function findLeakedDaemons() {
     const owned = new Set();
     const recorded = readDaemonPid();
@@ -146,11 +77,6 @@ export function findLeakedDaemons() {
     const unitPid = readServiceManagerPid();
     if (unitPid)
         owned.add(unitPid);
-    // A caller under a redirected HOME (a test/e2e harness) must still recognize
-    // the REAL install's daemon as owned: its records live under the account
-    // home (`os.userInfo().homedir` reads the passwd record, ignoring $HOME),
-    // not under this process's HOME. Flagging the box's healthy production
-    // daemon as a leak would be the RUSH-2368 harm through a new door.
     const realDaemonDir = getDaemonDirForHome(os.userInfo().homedir);
     if (realDaemonDir !== getDaemonDir()) {
         const realRecorded = readDaemonPid(realDaemonDir);
@@ -165,8 +91,6 @@ export function findLeakedDaemons() {
     for (const p of listDaemonRunProcesses()) {
         if (owned.has(p.pid))
             continue;
-        // Another uid's daemon is never named: we cannot read its environment
-        // reliably and could not signal it if we tried.
         if (myUid !== null && p.uid !== null && p.uid !== myUid)
             continue;
         leaked.push({

package/dist/lib/daemon/monitor-engine-service.d.ts

@@ -1,15 +1,3 @@
-/**
- * MonitorEngine lifecycle as a `DaemonService` (RUSH-3193 P2).
- *
- * Wraps the `MonitorEngine` (event-triggered watchers) under the
- * `ServiceSupervisor` contract. The engine can own a timer when embedded by a
- * foreground caller, but the daemon starts it in external-scheduler mode so
- * every evaluation cycle receives the supervisor's deadline, health, and
- * circuit-breaker semantics.
- *
- * `getEngine()` exposes the underlying `MonitorEngine` so `daemon.ts`'s
- * SIGHUP handler can call `engine.reload()` when needed.
- */
 import { BasePeriodicService, type DaemonContext } from './service.js';
 import type { DaemonServiceId } from '../daemon-services.js';
 import { MonitorEngine } from '../monitors/engine.js';
@@ -18,7 +6,6 @@ export declare class MonitorEngineService extends BasePeriodicService {
     readonly intervalMs = 5000;
     readonly deadlineMs: number;
     private engine;
-    /** Returns the live engine after `start()`, or `null` before/after. */
     getEngine(): MonitorEngine | null;
     protected onStart(ctx: DaemonContext): Promise<void>;
     protected onStop(): Promise<void>;