@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -7,66 +7,20 @@ export declare function invocation(bin: string): {
     command: string;
     prefix: string[];
 };
-/** True if any 0.2.0-only filter flag is present — one case that needs the version probe. */
 export declare function usesFilterFlags(args: string[]): boolean;
-/**
- * True if the 0.2.1 point-to-one remote read flag `--host <value>` (or `--host=value`)
- * is present — the other case that needs the version probe, gated on its own floor.
- */
 export declare function usesHostFlag(args: string[]): boolean;
-/**
- * Whether the resolved `sessions` binary is at or above `minVersion`. A probe
- * failure or an unparseable version reads as unsupported — the safe direction
- * (in-repo engine handles it), never a mis-route to an old binary.
- */
 export declare function sessionsBinSupports(bin: string, minVersion: string): boolean;
-/** Whether the resolved `sessions` binary is new enough for the 0.2.0 filters. */
 export declare function sessionsBinSupportsFilters(bin: string): boolean;
-/** Whether the resolved `sessions` binary is new enough for the 0.2.1 `--host` flag. */
 export declare function sessionsBinSupportsHost(bin: string): boolean;
 export declare function isReadQuery(args: string[], opts?: {
     filters?: boolean;
     host?: boolean;
 }): boolean;
-/**
- * Plan the rewrite of a `sessions` READ query that names EXACTLY ONE device via
- * `--device <name>` (and no explicit `--host`) into the standalone's
- * point-to-one remote read: the caller resolves the device to an ssh target and
- * appends `--host ssh://<target>` to `readArgs`, forwarding it to the LOCAL
- * standalone (which owns the ssh hop). This is the local-orchestration collapse
- * (secrets-cli model): `sessions` owns the remote read, replacing the in-repo
- * `--device` peer fan-out — WHEN it is safe (the caller gates on the LOCAL
- * standalone supporting `--host`, >=0.2.1, and falls through to the in-repo
- * fan-out if the PEER lacks the standalone).
- *
- * `sessions --host` is point-to-one, so ONLY a single unambiguous device may
- * collapse; a multi-device query MUST stay on the in-repo fan-out, which parses
- * commander's variadic `--device` correctly. Returns null (→ in-repo path,
- * unchanged) when the query is not a single-device read:
- *   - no `--device`/`-D`, or a missing/flag-shaped value;
- *   - `--device`/`-D` appears more than once (`--device box --device mac-mini`);
- *   - the value is a fan-out sentinel `all`/`fleet` (case-insensitive);
- *   - a bare token immediately follows the value (`--device box mac-mini`) —
- *     commander's variadic would take it as a second device, so this is
- *     multi-device too;
- *   - an explicit `--host` is already on the argv — it wins, matching `secrets`'
- *     `rewriteDeviceToHost`, so we never add a second `--host`;
- *   - the remaining query (with `--device` stripped) is not a read — a lifecycle
- *     `--device` (resume/watch/inject/focus/…) keeps its in-repo/`runOnPeer`
- *     behavior exactly.
- *
- * Pure and argv-only: fleet resolution (device → ssh target, via
- * `resolveRemoteDevice`) and the version gate live in the caller so this is unit
- * testable with real inputs. `filters` mirrors the caller's version gate for the
- * 0.2.0 filter flags (the `--device` token is not a filter flag, so it is
- * computed identically on the original argv and on `readArgs`).
- */
 export declare function planDeviceHostRead(args: string[], opts?: {
     filters?: boolean;
 }): {
     device: string;
     readArgs: string[];
 } | null;
-/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
 export declare function _resetSessionsClientForTest(): void;
 export declare const SESSIONS_INSTALL_HINT = "npm i -g @phnx-labs/sessions-cli";

package/dist/lib/sessions-client.js

@@ -1,39 +1,12 @@
-/**
- * sessions-client.ts — agents-cli's process client for the standalone
- * `sessions` CLI (PHNX-4012). This client never falls back itself: a missing
- * binary throws `SESSIONS_BIN_MISSING` (loud, DIST-1). The caller decides what
- * that means — the read fast-path in `index.ts` falls through to the in-repo
- * `lib/session` engine when the standalone is not installed (every worker and
- * CI runner, until @phnx-labs/sessions-cli is published), and takes the fast
- * path when it is.
- *
- * Bin resolution uses `findInPath`, which skips `~/.agents/.cache/shims`.
- * That skip is load-bearing: the leftover `sessions` alias shim execs
- * `agents sessions`, and resolving it would recurse (the 1.22.85 secrets
- * fork bomb with the names swapped — agi-cli#3532).
- */
 import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
 import { findInPath } from './agent-spec/agents.js';
 import { compareVersions } from './agent-spec/primitives.js';
 import { stripRoutingFlags } from './hosts/remote-cmd.js';
 const INSTALL_HINT = 'npm i -g @phnx-labs/sessions-cli';
-/**
- * First `sessions` release that implements the metadata filters and sort
- * (`-p/--project`, `--since`, `--until`, `--sort`, the `@version` agent suffix,
- * and the harness shorthands). An older binary would treat these as FTS tokens,
- * so a box with `sessions` < this floor keeps them on the in-repo engine (which
- * implements the same filters) rather than mis-routing to a binary that can't.
- */
 const SESSIONS_FILTERS_MIN_VERSION = '0.2.0';
-/**
- * First `sessions` release that implements the point-to-one remote read flag
- * `--host <target>` (SSH to ONE box, run `sessions … --local`, stream JSON back).
- * An older binary would treat `--host` as an FTS token, so a box with `sessions`
- * below this floor keeps a `--host` query on the in-repo engine (which resolves
- * `--device` against the fleet) rather than mis-routing it. Kept separate from the
- * filter floor above even though 0.2.1 ≥ 0.2.0 — a 0.2.0 binary supports the
- * filters but NOT `--host`, so the two gates are checked independently.
- */
 const SESSIONS_HOST_MIN_VERSION = '0.2.1';
 export class SessionsClientError extends Error {
     code;
@@ -44,11 +17,40 @@ export class SessionsClientError extends Error {
     }
 }
 let cachedBin;
+function dependencySessionsBin() {
+    const dirs = createRequire(import.meta.url).resolve.paths('@phnx-labs/sessions-cli');
+    if (!dirs)
+        return null;
+    let pkgJsonPath;
+    for (const dir of dirs) {
+        const candidate = path.join(dir, '@phnx-labs', 'sessions-cli', 'package.json');
+        if (existsSync(candidate)) {
+            pkgJsonPath = candidate;
+            break;
+        }
+    }
+    if (!pkgJsonPath)
+        return null;
+    const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    const rel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.sessions;
+    const abs = rel ? path.resolve(path.dirname(pkgJsonPath), rel) : '';
+    if (!rel || !existsSync(abs)) {
+        throw new SessionsClientError('SESSIONS_BIN_MISSING', `@phnx-labs/sessions-cli is installed beside agents-cli but its sessions bin is missing` +
+            `${rel ? ` (${rel})` : ''}.`);
+    }
+    return realpathSync(abs);
+}
+// Skip the legacy agents shim to avoid recursive sessions passthrough.
 export function resolveSessionsBin() {
     if (cachedBin)
         return cachedBin;
-    const explicit = process.env.SESSIONS_BIN?.trim();
-    const resolved = explicit && explicit.length > 0 ? explicit : findInPath('sessions');
+    const raw = process.env.SESSIONS_BIN;
+    const explicit = raw?.trim();
+    if (explicit) {
+        cachedBin = explicit;
+        return cachedBin;
+    }
+    const resolved = (raw === undefined ? dependencySessionsBin() : null) ?? findInPath('sessions');
     if (!resolved) {
         throw new SessionsClientError('SESSIONS_BIN_MISSING', 'The standalone `sessions` CLI was not found. Install it with:\n' +
             `  ${INSTALL_HINT}\n` +
@@ -62,21 +64,11 @@ export function invocation(bin) {
         return { command: process.execPath, prefix: [bin] };
     return { command: bin, prefix: [] };
 }
-/**
- * Allowlist of what sessions-cli v1 actually implements. Anything else —
- * picker (no args), `--since`, `-D`, `--waiting`, `render`, `stats`,
- * lifecycle verbs — stays on the in-repo engine. A denylist leaked those
- * through `allowUnknownOption()` as FTS tokens (PR review on #3554).
- */
 const READ_FLAGS = new Set([
     '--json',
     '--local',
     '--no-interactive',
 ]);
-/**
- * Boolean harness-shorthand flags added in 0.2.0 (`--claude` = `--agent claude`).
- * Recognized as read flags only when the resolved binary supports filters.
- */
 const FILTER_BOOL_FLAGS = new Set([
     '--claude',
     '--codex',
@@ -85,18 +77,12 @@ const FILTER_BOOL_FLAGS = new Set([
     '--grok',
     '--opencode',
 ]);
-/**
- * Value-taking filter flags added in 0.2.0 (each consumes the next argv token,
- * or is written `--flag=value`). `--agent`/`--limit` are NOT here — they are the
- * 0.1.x base set handled unconditionally below.
- */
 const FILTER_VALUE_FLAGS = new Set([
     '--project',
     '--since',
     '--until',
     '--sort',
 ]);
-/** True if any 0.2.0-only filter flag is present — one case that needs the version probe. */
 export function usesFilterFlags(args) {
     return args.some((arg) => {
         if (arg === '-p' || arg === '-a')
@@ -110,20 +96,10 @@ export function usesFilterFlags(args) {
         return false;
     });
 }
-/**
- * True if the 0.2.1 point-to-one remote read flag `--host <value>` (or `--host=value`)
- * is present — the other case that needs the version probe, gated on its own floor.
- */
 export function usesHostFlag(args) {
     return args.some((arg) => arg === '--host' || arg.startsWith('--host='));
 }
 let cachedProbedVersion;
-/**
- * Probe `sessions --version` ONCE per process (cached), returning the parsed
- * version string, or `null` when the probe fails or the output is unparseable.
- * The single cache is what keeps the filter and host gates to one spawn between
- * them, however many `sessionsBinSupports*` calls a query makes.
- */
 function probeSessionsVersion(bin) {
     if (cachedProbedVersion !== undefined)
         return cachedProbedVersion;
@@ -133,20 +109,14 @@ function probeSessionsVersion(bin) {
     cachedProbedVersion = !res.error && /^\d+\.\d+\.\d+/.test(version) ? version : null;
     return cachedProbedVersion;
 }
-/**
- * Whether the resolved `sessions` binary is at or above `minVersion`. A probe
- * failure or an unparseable version reads as unsupported — the safe direction
- * (in-repo engine handles it), never a mis-route to an old binary.
- */
+// Failed or old version probes stay in the in-repo engine because an old CLI may treat unknown flags as FTS terms.
 export function sessionsBinSupports(bin, minVersion) {
     const version = probeSessionsVersion(bin);
     return version !== null && compareVersions(version, minVersion) >= 0;
 }
-/** Whether the resolved `sessions` binary is new enough for the 0.2.0 filters. */
 export function sessionsBinSupportsFilters(bin) {
     return sessionsBinSupports(bin, SESSIONS_FILTERS_MIN_VERSION);
 }
-/** Whether the resolved `sessions` binary is new enough for the 0.2.1 `--host` flag. */
 export function sessionsBinSupportsHost(bin) {
     return sessionsBinSupports(bin, SESSIONS_HOST_MIN_VERSION);
 }
@@ -177,9 +147,6 @@ const ENGINE_VERBS = new Set([
 export function isReadQuery(args, opts = {}) {
     if (args.length === 0)
         return false;
-    // Base (0.1.x) value flags, always recognized; the 0.2.0 filter value flags
-    // join them only when the binary supports filters, and the 0.2.1 `--host`
-    // value flag only when the binary supports it (its own, higher floor).
     const valueFlags = new Set(['--limit', '--agent']);
     const boolFlags = new Set(READ_FLAGS);
     if (opts.filters) {
@@ -192,7 +159,6 @@ export function isReadQuery(args, opts = {}) {
         valueFlags.add('--host');
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
-        // `-a` (agent) and `-p` (project) are 0.2.0 short flags that take a value.
         if (opts.filters && (arg === '-a' || arg === '-p')) {
             i += 1;
             continue;
@@ -221,14 +187,6 @@ export function isReadQuery(args, opts = {}) {
     }
     return true;
 }
-/**
- * Scan an argv for the `sessions` `--device`/`-D` flag, which commander defines
- * as VARIADIC (`-D, --device <target...>`) — so it can appear more than once and
- * a space-form value greedily consumes following bare tokens as extra devices.
- * Returns how many times it occurs, the FIRST value, and the index of the last
- * argv token that value occupies (the flag token itself for the `=`/glued forms,
- * the following value token for the space form). Pure; no imports.
- */
 function scanDeviceFlag(args) {
     let count = 0;
     let value;
@@ -265,42 +223,9 @@ function scanDeviceFlag(args) {
     }
     return { count, value, valueEndIndex };
 }
-/**
- * Plan the rewrite of a `sessions` READ query that names EXACTLY ONE device via
- * `--device <name>` (and no explicit `--host`) into the standalone's
- * point-to-one remote read: the caller resolves the device to an ssh target and
- * appends `--host ssh://<target>` to `readArgs`, forwarding it to the LOCAL
- * standalone (which owns the ssh hop). This is the local-orchestration collapse
- * (secrets-cli model): `sessions` owns the remote read, replacing the in-repo
- * `--device` peer fan-out — WHEN it is safe (the caller gates on the LOCAL
- * standalone supporting `--host`, >=0.2.1, and falls through to the in-repo
- * fan-out if the PEER lacks the standalone).
- *
- * `sessions --host` is point-to-one, so ONLY a single unambiguous device may
- * collapse; a multi-device query MUST stay on the in-repo fan-out, which parses
- * commander's variadic `--device` correctly. Returns null (→ in-repo path,
- * unchanged) when the query is not a single-device read:
- *   - no `--device`/`-D`, or a missing/flag-shaped value;
- *   - `--device`/`-D` appears more than once (`--device box --device mac-mini`);
- *   - the value is a fan-out sentinel `all`/`fleet` (case-insensitive);
- *   - a bare token immediately follows the value (`--device box mac-mini`) —
- *     commander's variadic would take it as a second device, so this is
- *     multi-device too;
- *   - an explicit `--host` is already on the argv — it wins, matching `secrets`'
- *     `rewriteDeviceToHost`, so we never add a second `--host`;
- *   - the remaining query (with `--device` stripped) is not a read — a lifecycle
- *     `--device` (resume/watch/inject/focus/…) keeps its in-repo/`runOnPeer`
- *     behavior exactly.
- *
- * Pure and argv-only: fleet resolution (device → ssh target, via
- * `resolveRemoteDevice`) and the version gate live in the caller so this is unit
- * testable with real inputs. `filters` mirrors the caller's version gate for the
- * 0.2.0 filter flags (the `--device` token is not a filter flag, so it is
- * computed identically on the original argv and on `readArgs`).
- */
+// Collapse --device to --host only for one unambiguous read; multi/fleet/lifecycle queries remain on in-repo fan-out.
 export function planDeviceHostRead(args, opts = {}) {
     const { count, value, valueEndIndex } = scanDeviceFlag(args);
-    // Exactly one occurrence, with a real (non-flag) value — else fall through.
     if (count !== 1)
         return null;
     if (value === undefined || value === '' || value.startsWith('-'))
@@ -310,7 +235,6 @@ export function planDeviceHostRead(args, opts = {}) {
     const lower = value.toLowerCase();
     if (lower === 'all' || lower === 'fleet')
         return null;
-    // A bare token after the value is a second variadic device (multi-device).
     const next = valueEndIndex !== undefined ? args[valueEndIndex + 1] : undefined;
     if (next !== undefined && !next.startsWith('-'))
         return null;
@@ -319,7 +243,6 @@ export function planDeviceHostRead(args, opts = {}) {
         return null;
     return { device: value, readArgs };
 }
-/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
 export function _resetSessionsClientForTest() {
     cachedBin = undefined;
     cachedProbedVersion = undefined;

package/dist/lib/settings-manifest.d.ts

@@ -11,32 +11,16 @@
  * The manifest below classifies the remaining per-agent files, and
  * carryForwardSettings() fills gaps in a target version home from a source
  * version home. It never overwrites a value the target already has: scalars
- * keep the target's value, objects merge recursively, arrays union. That makes
+ * keep the target's value, objects merge recursively, arrays keep the target value. That makes
  * the operation idempotent and safe to run on every `agents add` / `agents use`.
  * (One scoped exception: the 'claude-trust' strategy promotes a stamped-default
  * `hasTrustDialogAccepted: false` to `true` — see the note on that entry.)
  */
 import type { AgentId } from './types.js';
 interface CarryForwardResult {
-    /** Manifest rel paths that were created or updated in the target home. */
     applied: string[];
-    /** Backup directory holding pre-merge copies of modified target files, if any. */
     backupDir?: string;
 }
-/**
- * Fill gaps in `target` from `source` without overwriting target values:
- * missing keys are copied, plain objects recurse, and everything else —
- * scalars AND arrays — keeps the target's value. Arrays deliberately do not
- * union: other writers (factory sync, hooks registration) mutate array entries
- * in place, so a union would keep re-appending stale pre-mutation copies from
- * the source on every carry (e.g. a user hook duplicated after the system
- * hooks were merged into it). Returns a new object.
- */
 export declare function fillGaps(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
-/**
- * Carry user settings forward from one version home into another. Both paths
- * are version-home roots (the directory containing `.claude/` / `.codex/`).
- * Only fills gaps — never overwrites target values — so it is idempotent.
- */
 export declare function carryForwardSettings(agent: AgentId, fromHome: string, toHome: string): CarryForwardResult;
 export {};

package/dist/lib/settings-manifest.js

@@ -11,7 +11,7 @@
  * The manifest below classifies the remaining per-agent files, and
  * carryForwardSettings() fills gaps in a target version home from a source
  * version home. It never overwrites a value the target already has: scalars
- * keep the target's value, objects merge recursively, arrays union. That makes
+ * keep the target's value, objects merge recursively, arrays keep the target value. That makes
  * the operation idempotent and safe to run on every `agents add` / `agents use`.
  * (One scoped exception: the 'claude-trust' strategy promotes a stamped-default
  * `hasTrustDialogAccepted: false` to `true` — see the note on that entry.)
@@ -26,28 +26,15 @@ const SETTINGS_MANIFEST = {
         { rel: '.claude/settings.json', strategy: 'json-merge' },
         { rel: '.claude/settings.local.json', strategy: 'copy-if-absent' },
         { rel: '.claude/keybindings.json', strategy: 'copy-if-absent' },
-        // `.claude.json` holds the login (oauthAccount) and per-session stats, so it
-        // must never merge wholesale — but it is also where Claude records workspace
-        // trust (`projects[<path>].hasTrustDialogAccepted`). Without carrying that,
-        // every newly pinned version re-shows the trust dialog once per project
-        // (issue #2776). The 'claude-trust' strategy projects ONLY the trust flags
-        // out of the source file; credentials and stats stay per-version.
         { rel: '.claude.json', strategy: 'claude-trust' },
     ],
     codex: [
+        // auth.json is intentionally absent: each version home owns its login.
         {
             rel: '.codex/config.toml',
             strategy: 'toml-merge',
             stateKeys: ['notice', 'windows_wsl_setup_acknowledged'],
         },
-        // `.codex/auth.json` is deliberately NOT carried forward. Copying it seeded
-        // every new Codex version with the current default's ChatGPT token, so two
-        // installed versions always reported the same account and could never sign
-        // into separate accounts. Claude never merges `.claude.json` for the same
-        // reason (its 'claude-trust' entry extracts only the trust flags) — a
-        // version home holds its own login, keeping accounts per-version. A fresh
-        // Codex version installs signed-out; run `codex login`
-        // (or `agents run codex --version <v>`) inside it to authenticate.
         { rel: '.codex/instructions.md', strategy: 'copy-if-absent' },
         { rel: '.codex/hooks.json', strategy: 'copy-if-absent' },
         { rel: '.codex/prompts', strategy: 'dir-entries' },
@@ -57,16 +44,8 @@ const SETTINGS_MANIFEST = {
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-/**
- * Fill gaps in `target` from `source` without overwriting target values:
- * missing keys are copied, plain objects recurse, and everything else —
- * scalars AND arrays — keeps the target's value. Arrays deliberately do not
- * union: other writers (factory sync, hooks registration) mutate array entries
- * in place, so a union would keep re-appending stale pre-mutation copies from
- * the source on every carry (e.g. a user hook duplicated after the system
- * hooks were merged into it). Returns a new object.
- */
 export function fillGaps(target, source) {
+    // Recurse only through plain objects; target scalars and arrays win so stale source entries are never re-appended.
     const out = { ...target };
     for (const [key, sourceValue] of Object.entries(source)) {
         if (!(key in out)) {
@@ -77,20 +56,11 @@ export function fillGaps(target, source) {
         if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
             out[key] = fillGaps(targetValue, sourceValue);
         }
-        // scalar, array, or type mismatch: target wins
     }
     return out;
 }
-/**
- * Project paths the source `.claude.json` records an accepted trust dialog for.
- * Only an explicit `true` counts: Claude Code never persists a decline (the
- * dialog exits without writing), so `false` is only ever the stamped default —
- * not a user decision worth propagating. Verified against Claude Code
- * 2.1.219/2.1.220 (decline paths exit via code 1 / code 0 without a config
- * write); if a future Claude Code starts persisting declines, this premise —
- * and the false→true promotion in the 'claude-trust' case — must be revisited.
- */
 function trustedClaudeProjects(source) {
+    // Only true is portable trust; false is Claude's stamped default, not a persisted decline.
     const projects = isPlainObject(source.projects) ? source.projects : {};
     return Object.entries(projects)
         .filter(([, project]) => isPlainObject(project) && project.hasTrustDialogAccepted === true)
@@ -110,11 +80,6 @@ function backupFile(backupRoot, home, rel) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.copyFileSync(src, dest);
 }
-/**
- * Carry user settings forward from one version home into another. Both paths
- * are version-home roots (the directory containing `.claude/` / `.codex/`).
- * Only fills gaps — never overwrites target values — so it is idempotent.
- */
 export function carryForwardSettings(agent, fromHome, toHome) {
     const manifest = SETTINGS_MANIFEST[agent];
     const result = { applied: [] };
@@ -155,13 +120,6 @@ export function carryForwardSettings(agent, fromHome, toHome) {
                     break;
                 }
                 case 'claude-trust': {
-                    // Projection, not a merge: pull ONLY `projects[<path>].hasTrustDialogAccepted`
-                    // out of the source `.claude.json`. Everything else in that file
-                    // (oauthAccount, onboarding state, per-session stats) stays per-version.
-                    // Trust granted anywhere wins over the target's stamped-default `false`
-                    // (headless runs create project entries with the flag unset-as-false
-                    // without ever showing the dialog), but a target entry's other keys
-                    // are preserved untouched.
                     const source = JSON.parse(fs.readFileSync(sourcePath, 'utf-8'));
                     const trusted = trustedClaudeProjects(source);
                     if (trusted.length === 0)
@@ -170,8 +128,6 @@ export function carryForwardSettings(agent, fromHome, toHome) {
                     const parsedTarget = targetExists
                         ? JSON.parse(fs.readFileSync(targetPath, 'utf-8'))
                         : {};
-                    // A target that isn't an object (or whose `projects` isn't) is not
-                    // ours to repair — skip rather than clobber it with a rebuilt shape.
                     if (!isPlainObject(parsedTarget))
                         break;
                     const targetObj = parsedTarget;
@@ -197,11 +153,6 @@ export function carryForwardSettings(agent, fromHome, toHome) {
                     else {
                         fs.mkdirSync(path.dirname(targetPath), { recursive: true });
                     }
-                    // Atomic (tmp + rename): a running Claude session rewrites this exact
-                    // file (it holds the login and session stats), so a plain write risks
-                    // a reader seeing a partial file. The OUTSIDE `.claude.json` is the
-                    // real file (the INSIDE `.claude/.claude.json` symlink resolves to it
-                    // and survives the rename).
                     atomicWriteFileSync(targetPath, JSON.stringify({ ...targetObj, projects: targetProjects }, null, 2) + '\n');
                     result.applied.push(entry.rel);
                     break;
@@ -226,8 +177,6 @@ export function carryForwardSettings(agent, fromHome, toHome) {
                     const targetText = fs.readFileSync(targetPath, 'utf-8');
                     const targetObj = parse(targetText);
                     const merged = fillGaps(targetObj, source);
-                    // Compare parsed content, not text: other writers format differently,
-                    // and a semantic no-op must not trigger a rewrite/backup every switch.
                     if (JSON.stringify(merged) === JSON.stringify(targetObj))
                         break;
                     backupFile(backupRoot, toHome, entry.rel);
@@ -239,8 +188,6 @@ export function carryForwardSettings(agent, fromHome, toHome) {
             }
         }
         catch {
-            // A malformed source or target file must not break install/use.
-            // Leave the target untouched for this entry and move on.
         }
     }
     return result;

package/dist/lib/setup-tool-install.d.ts

@@ -1,3 +1,2 @@
 import { type SetupTool } from './setup-tool-status.js';
-/** Use the host installer; setup must not install or start a tool from a read. */
 export declare function installSetupTool(tool: Exclude<SetupTool, 'secrets'>): Promise<boolean>;

package/dist/lib/setup-tool-install.js

@@ -1,18 +1,13 @@
 import { installCli, resolveCliManifest } from './cli-resources.js';
 import { getCachedToolSetup, refreshToolSetup } from './setup-tool-status.js';
-const PACKAGES = {
-    browser: '@phnx-labs/browser-cli@0.1.5',
-    computer: '@phnx-labs/computer-cli@0.1.5',
-    term: '@phnx-labs/term-cli@0.1.0',
-};
-/** Use the host installer; setup must not install or start a tool from a read. */
+import { pinnedSpec } from './standalone-tools.js';
 export async function installSetupTool(tool) {
     if (getCachedToolSetup().find((row) => row.tool === tool)?.installed)
         return true;
     const manifest = resolveCliManifest(tool) ?? {
         name: tool,
         check: { kind: 'which', cmd: tool },
-        install: [{ npm: PACKAGES[tool] }],
+        install: [{ npm: pinnedSpec(tool) }],
         source: 'builtin',
         path: '',
     };

package/dist/lib/setup-tool-status.d.ts

@@ -13,10 +13,7 @@ export interface ToolSetupOptions {
     cacheDir?: string;
 }
 export declare function toolSetupCacheDir(options?: ToolSetupOptions): string;
-/** Presence is metadata; health is the last explicit check, never a timer probe. */
 export declare function getCachedToolSetup(options?: ToolSetupOptions): ToolSetupRow[];
 export declare function toolReadiness(tool: SetupTool, status: unknown): Pick<ToolSetupRow, 'readiness' | 'detail'>;
-/** A shared disk lock coalesces overlapping requests from separate CLI clients. */
 export declare function refreshToolSetup(tool?: SetupTool | 'all', options?: ToolSetupOptions): Promise<ToolSetupRow[]>;
-/** File notifications are shared by the daemon collector; no background probes. */
 export declare function subscribeToolSetup(listener: (rows: ToolSetupRow[]) => void, options?: ToolSetupOptions): () => void;

package/dist/lib/setup-tool-status.js

@@ -15,7 +15,6 @@ function cachePath(tool, options) {
 }
 function setupInputs(tool) {
     const inputs = [path.join(getUserAgentsDir(), 'agents.yaml'), getDeviceMetaPath()];
-    // browser-cli's IPC socket (integration contract §4). computer's is the helper socket.
     if (tool === 'browser')
         inputs.push(path.join(getHelpersDir(), 'browser', 'browser.sock'));
     if (tool === 'computer')
@@ -73,7 +72,7 @@ function binaryMetadata(tool) {
                     break;
                 }
             }
-            catch { /* Executables need not be npm packages. */ }
+            catch { }
             const parent = path.dirname(dir);
             if (parent === dir)
                 break;
@@ -94,10 +93,9 @@ function readCache(tool, options) {
         if (cached.v === 1 && cached.row?.tool === tool && typeof cached.fingerprint === 'string')
             return cached;
     }
-    catch { /* No health result yet. */ }
+    catch { }
     return null;
 }
-/** Presence is metadata; health is the last explicit check, never a timer probe. */
 export function getCachedToolSetup(options = {}) {
     return SETUP_TOOLS.map((tool) => {
         const { row, fingerprint } = binaryMetadata(tool);
@@ -130,14 +128,8 @@ export function toolReadiness(tool, status) {
 async function checkTool(row) {
     if (!row.installed || !row.executable)
         return { ...row, checkedAtMs: Date.now() };
-    // The standalone has no non-interactive health JSON. Do not list bundles or
-    // unlock the broker merely to paint a settings row.
     if (row.tool === 'secrets')
         return { ...row, checkedAtMs: Date.now(), detail: 'Installed. Secret access is checked when used; this check does not unlock secrets.' };
-    // term is a headless PTY engine with no `status --json` health surface; it is
-    // spawned on demand by the setup-token mint (`agents accounts add`/`login`,
-    // via auth-mint.ts → term-driver.ts, the sole term-client consumers).
-    // Presence on PATH is the whole readiness signal — do not probe it.
     if (row.tool === 'term')
         return { ...row, readiness: 'ready', detail: 'Installed. Spawned on demand by `agents accounts add`/`login`.', checkedAtMs: Date.now() };
     try {
@@ -149,7 +141,6 @@ async function checkTool(row) {
         return { ...row, readiness: 'unknown', detail: 'Health check failed or timed out. Check again to retry.', checkedAtMs: Date.now() };
     }
 }
-/** A shared disk lock coalesces overlapping requests from separate CLI clients. */
 export async function refreshToolSetup(tool = 'all', options = {}) {
     const requestedAt = Date.now();
     const dir = toolSetupCacheDir(options);
@@ -167,7 +158,6 @@ export async function refreshToolSetup(tool = 'all', options = {}) {
     }
     return getCachedToolSetup(options).filter((row) => tool === 'all' || row.tool === tool);
 }
-/** File notifications are shared by the daemon collector; no background probes. */
 export function subscribeToolSetup(listener, options = {}) {
     const dir = toolSetupCacheDir(options);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -181,7 +171,7 @@ export function subscribeToolSetup(listener, options = {}) {
             try {
                 paths.add(path.dirname(fs.realpathSync(row.executable)));
             }
-            catch { /* Removed since discovery. */ }
+            catch { }
         }
     }
     let previous = JSON.stringify(getCachedToolSetup(options));
@@ -207,7 +197,7 @@ export function subscribeToolSetup(listener, options = {}) {
             watcher.on('error', changed);
             watchers.push(watcher);
         }
-        catch { /* Absent PATH entries have no executable to report. */ }
+        catch { }
     }
     changed();
     return () => { if (debounce)

package/dist/lib/sha256-asset.d.ts

@@ -1,22 +1,2 @@
-/**
- * sha256 helpers for verifying downloaded release assets.
- *
- * These live in their own LEAF module — importing only `node:crypto` and
- * `node:fs` — on purpose. They used to sit in the computer subsystem's ssh-tunnel
- * module (since extracted, PHNX-4075), whose
- * own import graph reached `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
- * the in-repo secrets engine's own keychain-helper downloader, which imported
- * back into `helper-download.ts` while it was still evaluating — before
- * `EXPECTED_TEAM_ID` was bound, throwing `ReferenceError: Cannot access
- * 'EXPECTED_TEAM_ID' before initialization` for any entry point that reached
- * `helper-download.ts` first (RUSH-3113). The secrets engine that closed that
- * cycle is gone now (PHNX-3989 — the standalone `secrets` CLI downloads its own
- * helper), but the discipline that fixed it still holds: keep this module a
- * leaf, since `helper-download.ts` needs nothing beyond these two pure
- * functions and adding a local import here can reintroduce a cycle with
- * whatever imports it next.
- */
-/** Pull the digest out of a `<sha256>  <filename>` release asset. */
 export declare function parseSha256Asset(text: string): string;
-/** Stream a file through sha256 — the exe is ~157MB, never read it whole. */
 export declare function sha256File(file: string): Promise<string>;