@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/watchdog.d.ts

@@ -1,23 +1,4 @@
-/**
- * `agents watchdog` — the watchdog CONSUMER (RUSH-1415).
- *
- * Runs the tick loop that ties the merged pieces together: list active sessions,
- * classify stalls, read the tail, decide (deterministic promise-without-toolcall
- * by default), run the resolver safety gate, and inject "Continue." into the EXACT
- * split — all without the Swift menu-bar. See src/lib/watchdog/runner.ts.
- *
- *   agents watchdog                    one tick, dry — prints what it WOULD nudge/skip and why
- *   agents watchdog --nudge            one tick, actually injects (explicit opt-in)
- *   agents watchdog --watch            manual poll loop (dry unless --nudge)
- *   agents watchdog --json             machine-readable tick output (for the menu-bar)
- *   agents watchdog enable|disable             turn the device-local daemon pass on/off
- *   agents watchdog policy <id> <p>    per-session policy: off | keep | handsoff
- *
- * The agents daemon is the sole automatic watchdog scheduler. The menu bar reads
- * persisted state; it never runs a tick.
- */
 import type { Command } from 'commander';
 import { type WatchdogTickResult } from '../lib/watchdog/runner.js';
 export declare function formatWatchdogTickLines(result: WatchdogTickResult, willInject: boolean, verbose?: boolean): string[];
-/** Register the `agents watchdog` command tree. */
 export declare function registerWatchdogCommand(program: Command): void;

package/dist/commands/watchdog.js

@@ -1,21 +1,3 @@
-/**
- * `agents watchdog` — the watchdog CONSUMER (RUSH-1415).
- *
- * Runs the tick loop that ties the merged pieces together: list active sessions,
- * classify stalls, read the tail, decide (deterministic promise-without-toolcall
- * by default), run the resolver safety gate, and inject "Continue." into the EXACT
- * split — all without the Swift menu-bar. See src/lib/watchdog/runner.ts.
- *
- *   agents watchdog                    one tick, dry — prints what it WOULD nudge/skip and why
- *   agents watchdog --nudge            one tick, actually injects (explicit opt-in)
- *   agents watchdog --watch            manual poll loop (dry unless --nudge)
- *   agents watchdog --json             machine-readable tick output (for the menu-bar)
- *   agents watchdog enable|disable             turn the device-local daemon pass on/off
- *   agents watchdog policy <id> <p>    per-session policy: off | keep | handsoff
- *
- * The agents daemon is the sole automatic watchdog scheduler. The menu bar reads
- * persisted state; it never runs a tick.
- */
 import chalk from 'chalk';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
@@ -28,16 +10,11 @@ import { loadWatchdogSessions, runWatchdogPass } from '../lib/watchdog/service.j
 import { readWatchdogEvents, WATCHDOG_LOG_PATH } from '../lib/watchdog/log.js';
 import { selectWatchdogHistory } from '../lib/watchdog/history.js';
 import { sessionHeadline } from '../lib/session/title.js';
-/** Default state dir the runner and these subcommands share. */
 function stateDir() {
     return path.join(getRuntimeStateDir(), 'watchdog');
 }
-/**
- * (Re)load the daemon so a just-changed routine takes effect without a restart.
- * Best-effort: enabling starts the daemon if it is not running, then SIGHUPs it.
- * Dynamic import keeps daemon.ts's heavy deps off the watchdog command's load path.
- */
 async function reloadDaemonForRoutine(startIfStopped) {
+    // Keep daemon dependencies off startup. If running, reload it; enable additionally starts it when stopped.
     const { isDaemonRunning, ensureDaemonStarted, signalDaemonReload } = await import('../lib/daemon/daemon.js');
     if (isDaemonRunning()) {
         signalDaemonReload();
@@ -46,7 +23,6 @@ async function reloadDaemonForRoutine(startIfStopped) {
     if (startIfStopped)
         ensureDaemonStarted();
 }
-/** Parse a duration flag ("60s", "5m", "1h") to ms, or fall back to `fallbackMs`. */
 function durationMsOr(raw, fallbackMs) {
     if (raw === undefined)
         return fallbackMs;
@@ -60,7 +36,6 @@ function humanMs(ms) {
         return `${Math.round(ms / 60_000)}m`;
     return `${Math.round(ms / 1000)}s`;
 }
-/** Render one tick's outcomes as a human status block. */
 function elapsedLabel(atMs, eventMs) {
     const seconds = Math.max(0, Math.round((atMs - eventMs) / 1000));
     if (seconds < 60)
@@ -100,8 +75,6 @@ export function formatWatchdogTickLines(result, willInject, verbose = false) {
                     : o.decision === 'nudge' ? 'WOULD-NUDGE'
                         : 'skip';
         const id = o.sessionId?.slice(0, 8) ?? 'no-session-id';
-        // `name` is the `agents run --name` launch handle — a user-given name, so it
-        // ranks with the label; everything below it is the shared headline ladder.
         const title = o.label || o.name || sessionHeadline(o);
         lines.push(`  ${tag.padEnd(11)} ${id}${title ? ` · ${title}` : ''}`);
         const metadata = [
@@ -135,8 +108,8 @@ function printTick(result, willInject, verbose) {
 async function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-/** Register the `agents watchdog` command tree. */
 export function registerWatchdogCommand(program) {
+    // The daemon alone schedules automatic passes; manual runs inject only with explicit --nudge.
     const cmd = program
         .command('watchdog')
         .description('Auto-nudge stalled agent terminals: detect stalls, resolve the exact split, inject "Continue." — no menu-bar needed.')
@@ -157,10 +130,6 @@ export function registerWatchdogCommand(program) {
             cooldownMs: durationMsOr(opts.cooldown, DEFAULT_THRESHOLDS.cooldownMs),
             dormantMs: durationMsOr(opts.dormant, DEFAULT_THRESHOLDS.dormantMs),
         };
-        // Injection gate: --nudge is the explicit opt-in to actually inject. Bare
-        // `agents watchdog` (and `--watch` without `--nudge`) is dry. The always-on
-        // path is the daemon-owned pass. Device config is its on/off switch; this
-        // explicit command still requires --nudge before it can inject.
         const computeWillInject = () => opts.nudge === true;
         const tickOnce = async (willInject, sessions) => runWatchdogPass({
             nudge: willInject,
@@ -170,10 +139,9 @@ export function registerWatchdogCommand(program) {
             allowGhosttyFocus: opts.allowGhosttyFocus === true,
             sessions,
         });
-        // RUSH-2062: share the daemon-warmed local active-session snapshot with
-        // menubar/CLI/Factory instead of re-running a full gather every tick.
         if (!opts.watch) {
             const willInject = computeWillInject();
+            // Reuse the daemon-warmed active snapshot rather than gathering the fleet again.
             const sessions = await loadWatchdogSessions();
             const result = await tickOnce(willInject, sessions);
             if (opts.json)
@@ -182,7 +150,6 @@ export function registerWatchdogCommand(program) {
                 printTick(result, willInject, opts.verbose === true);
             return;
         }
-        // Manual poll loop for ad-hoc use; the daemon owns the automatic cadence.
         const intervalMs = durationMsOr(opts.interval, 30_000);
         if (!computeWillInject() && !opts.json) {
             console.log(chalk.yellow(`watchdog --watch is DETECT-ONLY. Pass --nudge to inject, ` +
@@ -190,7 +157,6 @@ export function registerWatchdogCommand(program) {
         }
         // eslint-disable-next-line no-constant-condition
         while (true) {
-            // Re-evaluated each tick: picks up enable/disable flips mid-run.
             const willInject = computeWillInject();
             const sessions = await loadWatchdogSessions();
             const result = await tickOnce(willInject, sessions);
@@ -272,7 +238,6 @@ export function registerWatchdogCommand(program) {
       State (tray-readable): ${path.join('~/.agents/.cache/state/watchdog', '{nudges,flags,last-tick}.json')}
     `,
     });
-    // --- always-on enable/disable/status (backed by the daemon routine) --------
     const turnOn = async () => {
         setConfigValue('watchdog.enabled', true);
         await reloadDaemonForRoutine(true);
@@ -313,10 +278,6 @@ export function registerWatchdogCommand(program) {
         .description('Show whether the daemon watchdog pass is enabled and where state is written.')
         .option('--json', 'Emit status as JSON (for the menu-bar / scripts)')
         .action((_opts, command) => {
-        // The parent `watchdog` command also declares --json and greedily parses it
-        // before dispatching here, so `watchdog status --json` lands the flag on the
-        // parent, not this subcommand. optsWithGlobals() merges both levels, so we
-        // read it correctly regardless of which command commander bound it to.
         const json = command.optsWithGlobals().json === true;
         const on = getConfigValue('watchdog.enabled').value === true;
         const rotate = isWatchdogRotateEnabled() ? 'on' : 'off';
@@ -386,7 +347,6 @@ export function registerWatchdogCommand(program) {
         }
         console.log(chalk.dim(`${entries.length} event${entries.length === 1 ? '' : 's'} · ${WATCHDOG_LOG_PATH}`));
     });
-    // --- per-session policy ----------------------------------------------------
     cmd.command('policy <sessionId> <policy>')
         .description('Set per-session policy: off (ignore) | keep (default) | handsoff (detect + flag, never inject).')
         .action((sessionId, policy) => {

package/dist/commands/webhook.d.ts

@@ -1,13 +1,5 @@
-/**
- * `agents webhooks` — localhost receiver for signed public webhook ingress.
- *
- * The receiver intentionally binds localhost by default. Public exposure is a
- * separate `agents funnel up <host>` step so the HTTP process can be tested and
- * rotated without changing the Tailscale Funnel config.
- */
 import type { Command } from 'commander';
 import type { Server } from 'http';
 import type { Socket } from 'net';
-/** Stop accepting requests and destroy persistent connections so shutdown is bounded. */
 export declare function closeWebhookServer(server: Server, sockets: Set<Socket>): Promise<void>;
 export declare function registerWebhooksCommand(program: Command): void;

package/dist/commands/webhook.js

@@ -13,12 +13,6 @@ function positiveInt(value, fallback) {
 async function readWebhookSecrets(bundleName) {
     const { env } = await readAndResolveBundleEnv(bundleName, {
         caller: 'webhooks serve',
-        // `webhooks serve` is a long-running background server started to receive
-        // signed webhooks, not a human at a Touch ID sheet — so the read is always
-        // `agentOnly` (SEC-13: never pop biometry on its own). A `never`/no-ACL or
-        // broker-held bundle resolves silently; a locked bundle THROWS the actionable
-        // "unlock <name>" message, which propagates and fails the start LOUD rather
-        // than popping an unanswerable prompt.
         agentOnly: true,
     });
     const secrets = {};
@@ -33,7 +27,6 @@ async function readWebhookSecrets(bundleName) {
     }
     return secrets;
 }
-/** Stop accepting requests and destroy persistent connections so shutdown is bounded. */
 export async function closeWebhookServer(server, sockets) {
     const closing = closeServerBounded(server);
     for (const socket of sockets)
@@ -68,12 +61,7 @@ export function registerWebhooksCommand(program) {
                 port,
                 secrets,
                 rateLimitPerMinute: rateLimit,
-                // Durable delivery dedup: replays survive a receiver restart (an
-                // in-memory store would forget every seen delivery on restart).
                 deliveryStore: createFileDeliveryStore(path.join(getRuntimeStateDir(), 'webhook', 'deliveries.json')),
-                // Logged at MATCH time, before dispatch — a `run.command` handler can
-                // block on a shelled-out agent run for minutes, and that must never
-                // delay the log that says a delivery fired (RUSH-2722).
                 onMatch: (webhook, matchedJobNames, matchedHandlerNames) => {
                     const parts = [];
                     if (matchedJobNames.length)
@@ -83,8 +71,6 @@ export function registerWebhooksCommand(program) {
                     console.log(`${new Date().toISOString()} ${webhook.source}:${webhook.event} ` +
                         (parts.length ? `fired ${parts.join('; ')}` : 'no match'));
                 },
-                // The delivery is acked 202 before dispatch (RUSH-2548), so a dispatch
-                // failure has no HTTP status left to ride — print it instead.
                 onDeliveryError: (webhook, err) => {
                     console.error(chalk.red(`${new Date().toISOString()} ${webhook.source}:${webhook.event} dispatch failed after ack: ${err.message}`));
                 },

package/dist/commands/workflows.d.ts

@@ -1,10 +1,2 @@
-/**
- * Workflow management commands.
- *
- * Implements `agents workflows` — list, view, add, remove pipeline workflows
- * (WORKFLOW.md bundles with optional subagents/, skills/, plugins/ subdirs).
- * Run a workflow with: agents run <workflow-name>
- */
 import type { Command } from 'commander';
-/** Register the `agents workflows` command tree (list, view, add, remove). */
 export declare function registerWorkflowsCommands(program: Command): void;

package/dist/commands/workflows.js

@@ -14,7 +14,6 @@ import { getVersionHomePath, getGlobalDefault, syncResourcesToVersion, promptAge
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-/** Register the `agents workflows` command tree (list, view, add, remove). */
 export function registerWorkflowsCommands(program) {
     const workflowsCmd = program
         .command('workflows')
@@ -120,7 +119,6 @@ Examples:
         try {
             let workflows;
             if (!source) {
-                // Interactive: pick from central storage
                 const installed = listInstalledWorkflows();
                 if (installed.size === 0) {
                     console.log(chalk.yellow('No workflows in ~/.agents/workflows/'));
@@ -147,7 +145,6 @@ Examples:
                 workflows = selected.map(name => ({ name, path: installed.get(name).path }));
             }
             else {
-                // Fetch from repo or local path
                 const spinner = ora('Fetching workflows...').start();
                 const isGitRepo = source.startsWith('gh:') || source.startsWith('git:') ||
                     source.startsWith('https://') || source.startsWith('http://');
@@ -172,7 +169,6 @@ Examples:
                     console.log(chalk.yellow('No workflows found (looking for WORKFLOW.md files)'));
                     return;
                 }
-                // --names filter: pluck specific workflows from a multi-workflow source.
                 const requestedNames = parseCommaSeparatedList(options.names);
                 if (requestedNames.length > 0) {
                     const discoveredNames = new Set(discovered.map((w) => w.name));
@@ -210,7 +206,6 @@ Examples:
                     path: path.join(getUserWorkflowsDir(), w.name),
                 }));
             }
-            // Agent/version selection
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
@@ -327,7 +322,6 @@ Examples:
         for (const workflowName of toRemove) {
             const info = workflowTargetMap.get(workflowName);
             if (!info || info.targets.length === 0) {
-                // Not synced to any version — try removing from central storage directly
                 const result = removeWorkflow(workflowName);
                 if (result.success) {
                     console.log(`  ${chalk.red('-')} ${workflowName}: removed from central storage`);

package/dist/index.d.ts

@@ -1,27 +1,2 @@
 #!/usr/bin/env -S node --no-warnings=ExperimentalWarning
-/**
- * CLI entry point for agents-cli.
- *
- * Slim shell (RUSH-2335): no static imports at all, so the argv fast paths
- * below can answer without evaluating the commander + self-update +
- * command-registry graph. The full CLI loads via `await import('./bootstrap.js')`
- * once none of the fast paths match.
- *
- * Fast paths (must stay above the bootstrap import — ESM does not hoist dynamic
- * `import()`, but any static import here would still evaluate first):
- *   - `__launch-lease`
- *   - `__shim`
- *   - `__gh`
- *   - `__claude-statusline`
- *   - `__usage-ingest` / `__usage-export`
- *   - `__harness-update-run`
- *   - `__daemon-run`
- *   - `sessions` (read queries only — PHNX-4012)
- *
- * The synchronous secrets-broker fast paths (`__secrets-get` / `__secrets-ping`
- * / `__secrets-lock`) and `__vault-age-helper` moved out of this CLI entirely
- * with the standalone `secrets` engine (PHNX-3989) — agents-cli now talks to
- * it only through the bounded process client (`lib/secrets-client.ts`), never
- * through a hidden subcommand of its own.
- */
 export {};

package/dist/index.js

@@ -1,60 +1,15 @@
 #!/usr/bin/env -S node --no-warnings=ExperimentalWarning
-/**
- * CLI entry point for agents-cli.
- *
- * Slim shell (RUSH-2335): no static imports at all, so the argv fast paths
- * below can answer without evaluating the commander + self-update +
- * command-registry graph. The full CLI loads via `await import('./bootstrap.js')`
- * once none of the fast paths match.
- *
- * Fast paths (must stay above the bootstrap import — ESM does not hoist dynamic
- * `import()`, but any static import here would still evaluate first):
- *   - `__launch-lease`
- *   - `__shim`
- *   - `__gh`
- *   - `__claude-statusline`
- *   - `__usage-ingest` / `__usage-export`
- *   - `__harness-update-run`
- *   - `__daemon-run`
- *   - `sessions` (read queries only — PHNX-4012)
- *
- * The synchronous secrets-broker fast paths (`__secrets-get` / `__secrets-ping`
- * / `__secrets-lock`) and `__vault-age-helper` moved out of this CLI entirely
- * with the standalone `secrets` engine (PHNX-3989) — agents-cli now talks to
- * it only through the bounded process client (`lib/secrets-client.ts`), never
- * through a hidden subcommand of its own.
- */
-// Force exit on Ctrl+C when no interactive prompt is handling it — UNLESS a
-// guarded harness auto-update pass is mutating this process transactionally
-// (PHNX-3940). A hard exit mid-swap can leave an installation whose directory
-// and metadata disagree, so defer ONLY while that guard is held; the pass sees
-// the same SIGINT cooperatively (lib/installations/update-cancellation.ts) and
-// stops at its next safe boundary. The depth is read through the shared
-// `Symbol.for` registry key so this slim entry shell needs no static import of
-// that module (agent.test.ts pins the single allowed import). Every other SIGINT
-// still force-exits 130, and no other listener is touched.
 process.on('SIGINT', () => {
     const depth = globalThis[Symbol.for('agents.guardedAutoUpdateDepth')] ?? 0;
     if (depth > 0)
         return;
     process.exit(130);
 });
-// Ignore SIGPIPE — prevents exit code 13 crashes in piped environments
-// (e.g. `agents sessions | head`, or when stdout is captured by another process).
 process.on('SIGPIPE', () => { });
-// Launch-lease delegate: every generated native shim/alias calls
-// `agents __launch-lease <agent> <label> <pid>` right before its final `exec`
-// (PHNX-3940) — on the hot launch path of every managed agent, so it must skip
-// the same update-check/bootstrap machinery `__shim` skips below. See
-// `lib/installations/launch-gate.ts` for what this call actually does.
 if (process.argv[2] === '__launch-lease') {
     const { runLaunchLeaseCli } = await import('./lib/installations/launch-gate.js');
     process.exit(await runLaunchLeaseCli(process.argv.slice(3)));
 }
-// Transparent shim delegate: the generated Windows `.cmd` shims invoke
-// `agents __shim <agent>[@version] <raw args>`. Intercept here, before bootstrap
-// parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
-// through completely untouched and we skip registering the full command tree.
 if (process.argv[2] === '__shim') {
     const spec = process.argv[3] || '';
     const rawArgs = process.argv.slice(4);
@@ -65,11 +20,6 @@ if (process.argv[2] === '__shim') {
     const code = await execShimPassthrough(agent, rawArgs, process.cwd(), pinned || undefined);
     process.exit(code);
 }
-// gh overload delegate: the `gh` PATH shim routes `gh pr checks` here as
-// `agents __gh --real-gh <path> -- pr checks …`, so the rate-limit-prone read
-// runs over REST instead of GraphQL (PHNX-3501). Above bootstrap for the same
-// reason as __shim: no update check, no command-tree load — this is on the hot
-// path of an agent's CI watch, and the gh argv must pass through untouched.
 if (process.argv[2] === '__gh') {
     const { runGhOverload } = await import('./lib/github/gh-overload.js');
     process.exit(await runGhOverload(process.argv.slice(3)));
@@ -78,12 +28,6 @@ if (process.argv[2] === '__claude-statusline') {
     const { runClaudeStatusLine } = await import('./lib/claude-statusline.js');
     process.exit(await runClaudeStatusLine());
 }
-// Fleet usage-sync receiver: a headed peer pipes its daemon-state envelope to
-// stdin; we store it as that peer's file, merge its usage rows newest-wins into
-// this box's cache, and with `--reply` print our own envelope back (PHNX-3392,
-// PHNX-4116). Above the bootstrap line for the same reason as
-// __claude-statusline — no update check, no detached sync fork, and without
-// `--reply` nothing writes to stdout to corrupt the ready probe's view.
 if (process.argv[2] === '__usage-ingest') {
     const { runUsageIngest } = await import('./lib/accounting/usage-ingest.js');
     process.exit(await runUsageIngest());
@@ -93,35 +37,22 @@ if (process.argv[2] === '__usage-export') {
     process.stdout.write(JSON.stringify({ v: 1, rows: exportClaudeUsageCacheRows() }));
     process.exit(0);
 }
-// Harness auto-update child (PHNX-3940): the daemon's harness-update tick spawns
-// `agents __harness-update-run` over a Node IPC channel and cancels it
-// cooperatively by MESSAGE, never a kill (see
-// lib/daemon/harness-update-service.ts + lib/installations/update-cancellation.ts).
-// Above bootstrap for the same reason as __daemon-run: this internal periodic
-// child must not itself fire a self-update check or fork a detached sync, and its
-// stdout carries a clean JSON summary the daemon logs.
 if (process.argv[2] === '__harness-update-run') {
     const { runHarnessUpdateChild } = await import('./lib/installations/update-runtime.js');
     process.exit(await runHarnessUpdateChild());
 }
+if (process.argv[2] === '__self-heal-run') {
+    const { runSelfHealChild } = await import('./lib/self-heal/child.js');
+    process.exit(await runSelfHealChild());
+}
 if (process.argv[2] === '__daemon-run') {
     const { runDaemon, log: daemonLog } = await import('./lib/daemon/daemon.js');
-    // RUSH-2418: the daemon is the one always-on process here, and it ran with no
-    // top-level handler of any kind — an uncaught throw or a rejected promise from
-    // any of its background ticks died on Node's default handler, printing a raw
-    // stack to whatever the service manager had wired to stdout and never reaching
-    // the daemon's own structured log. Route both into log() so the failure is in
-    // logs.jsonl where `agents daemon logs` reads it, then exit non-zero and
-    // DELIBERATELY let the supervisor restart us — paced by the plist's
-    // ThrottleInterval / the unit's RestartSec, and never abandoned
-    // (StartLimitIntervalSec=0, PHNX-4116). Swallowing here would be the worse
-    // failure: a daemon left alive with a dead subsystem.
     const crash = (kind) => (err) => {
         const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
         try {
             daemonLog('ERROR', `${kind}: ${detail}`);
         }
-        catch { /* log path unwritable — stderr below still carries it */ }
+        catch { }
         process.stderr.write(`[agents] daemon ${kind}: ${detail}\n`);
         process.exit(1);
     };
@@ -135,48 +66,19 @@ if (process.argv[2] === '__daemon-run') {
     }
     process.exit(process.exitCode ?? 0);
 }
-// PHNX-4012: search/list/id lookup of `agents sessions` execs the standalone
-// `sessions` binary without loading bootstrap or the 6K-line sessions module.
-// Lifecycle verbs (resume/stop/inject/watch/--active/--markdown) fall through.
 if (process.argv[2] === 'sessions') {
     const forwarded = process.argv.slice(3);
     const { isReadQuery, usesFilterFlags, usesHostFlag, sessionsBinSupportsFilters, sessionsBinSupportsHost, planDeviceHostRead, resolveSessionsBin, invocation, SessionsClientError, SESSIONS_INSTALL_HINT, } = await import('./lib/sessions-client.js');
-    // Resolve the bin up front (a cheap PATH lookup): its presence decides whether
-    // we can route at all, and its VERSION decides whether the 0.2.0 filter flags
-    // (`--project`/`--since`/`--until`/`--sort`, `@version`, the shorthands) and the
-    // 0.2.1 `--host <target>` point-to-one remote read flag are recognized — an
-    // older `sessions` would mis-read them as FTS tokens, so those queries stay on
-    // the in-repo engine (which implements the same filters and the `--device`
-    // fan-out). The two floors are checked independently: a 0.2.0 binary takes the
-    // filters but not `--host`.
     let bin = null;
     try {
         bin = resolveSessionsBin();
     }
     catch (err) {
-        // No standalone on this box: fall through to the in-repo engine below rather
-        // than refusing the query. The fast path is an optimization for a box that
-        // has `sessions` installed (skips bootstrap and the sessions module); a box
-        // without it must still answer `agents sessions --json` exactly as before.
         if (!(err instanceof SessionsClientError && err.code === 'SESSIONS_BIN_MISSING'))
             throw err;
     }
     const filters = bin !== null && usesFilterFlags(forwarded) ? sessionsBinSupportsFilters(bin) : false;
     const host = bin !== null && usesHostFlag(forwarded) ? sessionsBinSupportsHost(bin) : false;
-    // PHNX-4012 local-orchestration collapse: a read query carrying `--device
-    // <name>` (and no explicit `--host`) routes through the standalone's
-    // point-to-one remote read — `sessions <read args> --host ssh://<resolved>` —
-    // instead of the in-repo `--device` peer fan-out, WHEN this box's standalone
-    // supports `--host` (>=0.2.1). `planDeviceHostRead` is pure and probes nothing,
-    // so a non-device read never pays a `sessions --version` spawn (the probe fires
-    // only after a device read is detected). If the PEER lacks the standalone the
-    // ssh `bash -lc` command-not-found surfaces as exit 127 — a CAPABILITY gate
-    // (same spirit as #3687's version gate, keyed on a specific documented signal),
-    // on which we FALL THROUGH to the in-repo `--device` fan-out below so the read
-    // still succeeds. Everything else (e.g. 255 unreachable) propagates verbatim.
-    // The in-repo fan-out is deliberately KEPT here as the path for un-upgraded
-    // peers; its eventual removal is a follow-up gated on fleet-wide 0.2.1 (a
-    // separate PHNX-4012 follow-up, see the PR body), not this PR.
     if (bin !== null) {
         const deviceRead = planDeviceHostRead(forwarded, { filters });
         if (deviceRead && sessionsBinSupportsHost(bin)) {
@@ -186,20 +88,12 @@ if (process.argv[2] === 'sessions') {
                 target = (await resolveRemoteDevice(deviceRead.device, {})).target;
             }
             catch {
-                // Unknown/unresolvable device — fall through to the in-repo path, which
-                // resolves `--device` against the same fleet registry and emits the
-                // canonical error; do not duplicate that error here.
                 target = null;
             }
             if (target !== null) {
                 const { spawnSync } = await import('node:child_process');
                 const { command, prefix } = invocation(bin);
                 const hostArgs = [...deviceRead.readArgs, '--host', `ssh://${target}`];
-                // Capture (not `stdio: 'inherit'`) so a 127 capability miss can fall
-                // through silently instead of leaking the peer's command-not-found before
-                // the in-repo read re-answers. Reads are bounded, so buffering is fine;
-                // force color + geometry through the capture when the caller is at a real
-                // terminal and not asking for `--json`, matching the passthrough renderer.
                 const childEnv = { ...process.env };
                 if (process.stdout.isTTY && !hostArgs.includes('--json')) {
                     if (childEnv.FORCE_COLOR === undefined)
@@ -218,9 +112,6 @@ if (process.argv[2] === 'sessions') {
                     process.stderr.write(`Failed to run \`sessions\`: ${res.error.message}\n`);
                     process.exit(1);
                 }
-                // Exit 127 = the peer has no standalone `sessions` on PATH (ssh/`bash
-                // -lc` command-not-found). Fall through to the in-repo fan-out rather
-                // than surfacing a broken read.
                 if (res.status !== 127) {
                     if (res.stdout)
                         process.stdout.write(res.stdout);
@@ -228,8 +119,6 @@ if (process.argv[2] === 'sessions') {
                         process.stderr.write(res.stderr);
                     process.exit(res.status ?? 1);
                 }
-                // 127: fall through. `forwarded` still carries `--device`, so the
-                // `isReadQuery` check below is false and bootstrap's in-repo path answers.
             }
         }
     }
@@ -244,13 +133,10 @@ if (process.argv[2] === 'sessions') {
             }
             process.exit(res.status ?? 1);
         }
-        // A read query on a box with no standalone: hint once, then fall through.
         if (process.env.AGENTS_SESSIONS_FASTPATH_HINT !== '0') {
             process.stderr.write(`agents: standalone \`sessions\` not installed; using the in-process engine (${SESSIONS_INSTALL_HINT})\n`);
         }
     }
 }
-// Full CLI: commander tree, update checks, migrations, parse. Static imports
-// inside bootstrap.js evaluate only when we reach this line.
 await import('./bootstrap.js');
 export {};

package/dist/lib/account-capabilities.d.ts

@@ -1,51 +1,17 @@
 import type { AgentId } from './types.js';
-/**
- * How safely agents-cli can read a harness's native login identity, and at what
- * granularity that identity is scoped.
- *
- * - `inspection`: `strong` = a stable account key (Claude/Codex/Grok);
- *   `email` = only an email claim, so the name binds to an address not a token
- *   (Muse); `opaque` = a stable but non-human identifier from an OAuth/JWT blob
- *   with no email (the device-scoped harnesses); `none` = no inspectable identity.
- * - `scope`: `version` = auth lives per installed version home; `device` = one
- *   login per device shared by every install; `unsupported` = agents-cli must not
- *   name/attach this harness's native login.
- * - `status`: `supported` = name + attach safely; `conditional` = supported only
- *   when the weaker (email) identity is present; `discovery-only` = shown in the
- *   list but not nameable; `unsupported` = neither.
- */
 interface NativeAccountCapability {
     inspection: 'strong' | 'email' | 'opaque' | 'none';
     scope: 'version' | 'device' | 'unsupported';
     status: 'supported' | 'conditional' | 'discovery-only' | 'unsupported';
 }
-/** Native-login selector coverage required by RUSH-3053. */
 export declare const NATIVE_ACCOUNT_SELECTOR_AGENTS: readonly ["claude", "codex", "cursor", "grok", "kimi"];
-/** Explicit dispositions for config-isolated harnesses outside that selector. */
 export declare const NATIVE_ACCOUNT_SELECTOR_EXCLUSIONS: Partial<Record<AgentId, string>>;
-/** Canonical truth for native-account naming and attachment semantics. */
 export declare const NATIVE_ACCOUNT_CAPABILITIES: Record<AgentId, NativeAccountCapability>;
 export declare function nativeAccountCapability(agent: AgentId): NativeAccountCapability;
-/** Whether a harness's native login can be named/attached (supported or conditional). */
 export declare function nativeAccountNameable(agent: AgentId): boolean;
-/** Harnesses whose native login is fully nameable/attachable today. */
 export declare function supportedNativeHarnesses(): AgentId[];
-/**
- * Named reason to refuse native name/attach, or null when the harness is
- * nameable. Provider-credential `accounts add` is a different path and MUST
- * not consult this — that surface is supported for every registered provider.
- */
 export declare function nativeAccountNamingRefusal(agent: AgentId): string | null;
-/** Fail loud on the native name/attach path for an unsupported harness. */
 export declare function assertNativeAccountNameable(agent: AgentId): void;
-/**
- * The single identity key used at `accounts add`, exec validation,
- * view, and inventory. Prefer the harness's stable `accountKey`. For an
- * email-only (`conditional`) harness, email is a presence gate — the stored
- * key is still `accountKey` (e.g. `muse:email=user@x.com`), never the bare
- * address, so `run`/`view` compare against the same value `getAccountInfo`
- * returns.
- */
 export declare function nativeIdentityKey(info: {
     signedIn?: boolean;
     email?: string | null;