@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/devices/terminfo.js

@@ -1,37 +1,7 @@
-/**
- * Terminfo propagation for `agents ssh` interactive logins.
- *
- * Modern terminals (Ghostty, kitty, Alacritty, WezTerm, foot, rio) advertise a
- * custom `TERM` (e.g. `xterm-ghostty`) whose terminfo entry ships with the
- * terminal, not with the remote host's ncurses. SSH into a box that lacks the
- * entry and the session is subtly broken: wrong backspace, missing colors, a
- * garbled clear/alt-screen. Ghostty's own shell integration fixes this for the
- * bare `ssh` command, but `agents ssh` (Tailscale-relayed, spawned directly)
- * bypasses that wrapper — so we handle it here.
- *
- * Strategy: on an interactive POSIX login, if the local `$TERM` is one the
- * remote is unlikely to have, export it locally (`infocmp -x`) and compile it on
- * the remote (`tic -x -`, writes to the user's `~/.terminfo`, no sudo). This is
- * the canonical, terminal-agnostic technique.
- *
- * Two invariants keep it safe and cheap:
- *  - **Fail-safe.** Every failure is swallowed. A push that errors, times out,
- *    or hits a remote without `tic` leaves the user exactly where they are today
- *    — it never blocks or delays the actual login beyond the short push timeout.
- *  - **Cached.** A successful sync stamps a local marker keyed by host+TERM, so
- *    only the first login to each host pays the one extra round-trip; every
- *    repeat login is zero-cost.
- */
 import { spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from '../state.js';
-/**
- * Terminfo names that ncurses ships essentially everywhere, so pushing them is
- * wasted work. Anything NOT in this set (the exotic terminal entries) is a sync
- * candidate. Kept deliberately conservative: when unsure, we push — `tic` is
- * idempotent and the result is cached.
- */
 const UNIVERSAL_TERMS = new Set([
     'dumb',
     'ansi',
@@ -52,21 +22,13 @@ const UNIVERSAL_TERMS = new Set([
     'rxvt-unicode',
     'rxvt-unicode-256color',
 ]);
-/** How long a successful sync suppresses re-syncing the same host+TERM. */
-const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
-/** Cap on the push so a stalled remote can't delay the login indefinitely. */
+const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const PUSH_TIMEOUT_MS = 8000;
-/**
- * Decide whether an interactive login warrants a terminfo push. Pure so the
- * gating logic is unit-testable without touching ssh or the filesystem.
- *
- * @param interactive true only for a real login (no remote command) on a human tty.
- */
 export function shouldSyncTerminfo(params) {
     if (!params.interactive)
         return false;
     if (params.shell === 'powershell')
-        return false; // Windows console ignores terminfo
+        return false;
     const term = params.term?.trim();
     if (!term)
         return false;
@@ -74,28 +36,17 @@ export function shouldSyncTerminfo(params) {
         return false;
     return true;
 }
-/**
- * Cache key for a device: the remote **user@host**, not just the host. terminfo
- * is compiled into the *per-user* `~/.terminfo`, so `alice@box` and `bob@box`
- * are distinct sync targets — keying on host alone would let the first user's
- * stamp suppress the second user's (never-installed) sync. Mirrors
- * {@link sshTargetFor}'s user handling; falls back to the device name when the
- * address is unresolved.
- */
 export function terminfoHostKey(device, addr) {
     const host = addr ?? device.name;
     return device.user ? `${device.user}@${host}` : host;
 }
-/** Directory holding per-host+TERM sync stamps. `cacheRoot` override is for tests. */
 function stampDir(cacheRoot) {
     return path.join(cacheRoot ?? getCacheDir(), 'devices', 'terminfo');
 }
-/** Filesystem-safe stamp name for a host+TERM pair. */
 function stampFile(host, term, cacheRoot) {
     const safe = `${host}__${term}`.replace(/[^A-Za-z0-9._-]/g, '_');
     return path.join(stampDir(cacheRoot), safe);
 }
-/** True when a fresh successful-sync stamp exists for this host+TERM. */
 export function terminfoSynced(host, term, cacheRoot) {
     try {
         const st = fs.statSync(stampFile(host, term, cacheRoot));
@@ -105,17 +56,14 @@ export function terminfoSynced(host, term, cacheRoot) {
         return false;
     }
 }
-/** Record a successful sync so repeat logins skip the push. Best-effort. */
 export function markTerminfoSynced(host, term, cacheRoot) {
     try {
         fs.mkdirSync(stampDir(cacheRoot), { recursive: true });
         fs.writeFileSync(stampFile(host, term, cacheRoot), `${new Date().toISOString()}\n`);
     }
     catch {
-        /* a cache write failure just means we re-sync next time — never fatal */
     }
 }
-/** Export the local terminfo source for a TERM, or null if it can't be produced. */
 export function localTerminfoSource(term) {
     try {
         const res = spawnSync('infocmp', ['-x', term], {
@@ -127,18 +75,9 @@ export function localTerminfoSource(term) {
         }
     }
     catch {
-        /* infocmp missing or errored — nothing we can push */
     }
     return null;
 }
-/**
- * Best-effort: ensure `device` has the terminfo entry for the local `$TERM`
- * before an interactive login. Never throws; returns whether a push succeeded
- * (false when skipped, already-cached, or failed). `sshArgs`/`sshEnv` are the
- * SAME host-key + auth options the real login uses, minus the interactive tty —
- * so a password-auth device resolves through the askpass shim without a second
- * human prompt.
- */
 export function syncTerminfoToDevice(opts) {
     const term = opts.term?.trim();
     if (!term)
@@ -161,7 +100,6 @@ export function syncTerminfoToDevice(opts) {
         }
     }
     catch {
-        /* connection failed / timed out — fail-safe, login proceeds unaffected */
     }
     return false;
 }

package/dist/lib/devices/worker-pick.d.ts

@@ -1,13 +1,10 @@
 import { type DevicePlacementSignal } from '../teams/scheduler.js';
-/** Why a candidate was dropped, for the fail-loud error message. */
 export interface WorkerExclusion {
     device: string;
     reason: 'unreachable' | 'probe timed out' | 'overloaded' | 'wrong-platform' | 'interactive';
 }
 interface WorkerPickPlan {
-    /** The chosen device name. Never the local box unless it is an auto-pool member. */
     device: string;
-    /** True when the pick IS this machine (the caller should run in place). */
     isLocal: boolean;
     candidates: Array<{
         device: string;
@@ -17,23 +14,11 @@ interface WorkerPickPlan {
     excluded: WorkerExclusion[];
 }
 interface WorkerPickOptions {
-    /** Restrict to these platforms. Defaults to POSIX (`linux`, `macos`). */
     platforms?: string[];
-    /** Override the candidate pool (tests). */
     eligibleHosts?: string[];
     localMachine?: string;
-    /** Injected probe (tests). */
     probe?: (pool: string[]) => Promise<Map<string, DevicePlacementSignal>>;
 }
-/**
- * Resolve the least-loaded eligible worker.
- *
- * Throws — never returns a degraded answer. An offload helper that quietly
- * decided "no worker, run here" would recreate exactly the failure the offload
- * exists to prevent: the operator believes the work went to the fleet while
- * their laptop is pinned. Callers surface the thrown message verbatim.
- */
 export declare function resolveWorkerDevice(opts?: WorkerPickOptions): Promise<WorkerPickPlan>;
-/** The one no-worker message, naming every candidate and why it was dropped. */
 export declare function formatNoWorkerError(excluded: WorkerExclusion[], platforms: Set<string>): string;
 export {};

package/dist/lib/devices/worker-pick.js

@@ -1,23 +1,3 @@
-/**
- * Pick a worker device for offloaded machine work — the suite, a build, any job
- * that pins a box for minutes and must never land on the machine someone is
- * sitting at.
- *
- * This is deliberately NOT `resolveDeviceAuto`. That resolver answers "which box
- * should run this AGENT", so it gates on harness installation and a launch-ready
- * account (`smart-launch.ts:200-210`). A vitest run needs neither: it needs a
- * reachable POSIX box with headroom. Gating a test offload on a signed-in Claude
- * account would exclude a perfectly good worker for a reason that has nothing to
- * do with running tests.
- *
- * What it DOES share, on purpose, is everything that decides *where agents may
- * go*: the same {@link listOnlineDeviceNames} pool (so `role=worker` /
- * `role=personal` marks move this surface too), the same
- * {@link probePoolSignals} reachability+load probe (so one cached fleet probe
- * serves both), and the same {@link pickBestDevice} least-loaded ranking. Before
- * this module, `scripts/test.sh` hand-rolled its own resolver in inline Python
- * and therefore could not offer `--device auto` at all.
- */
 import { normalizeHost } from '../machine-id.js';
 import { localMachineId } from '../session/origin-machine.js';
 import { loadDevicesSync } from './registry.js';
@@ -25,30 +5,10 @@ import { isAutoPoolMember } from './pool.js';
 import { formatEmptyAutoPoolError, listOnlineDeviceNames, } from '../smart-launch.js';
 import { pickBestDevice } from '../teams/scheduler.js';
 import { probePoolSignals } from '../teams/placement-probe.js';
-/**
- * Platforms a bun/vitest offload can actually run on.
- *
- * Windows is excluded by policy, not by accident: `AGENTS.md` states Windows is
- * not a required PR or ordinary-release platform and `tests.yml` runs it only as
- * a `continue-on-error` post-merge smoke. Silently shipping the tree to
- * `win-mini` would produce a confusing failure for a platform whose result
- * nobody gates on.
- */
 const POSIX_PLATFORMS = ['linux', 'macos'];
-/**
- * Resolve the least-loaded eligible worker.
- *
- * Throws — never returns a degraded answer. An offload helper that quietly
- * decided "no worker, run here" would recreate exactly the failure the offload
- * exists to prevent: the operator believes the work went to the fleet while
- * their laptop is pinned. Callers surface the thrown message verbatim.
- */
 export async function resolveWorkerDevice(opts = {}) {
     const local = normalizeHost(opts.localMachine ?? localMachineId());
     const pool = [...new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost))];
-    // The local box joins the pool only when a role does not exclude it — the same
-    // rule resolveDeviceAuto applies. A box marked `personal` is marked precisely
-    // so long jobs stay off it, and that mark must hold for the suite too.
     if (!pool.includes(local) && isAutoPoolMember(local))
         pool.push(local);
     if (pool.length === 0)
@@ -61,12 +21,8 @@ export async function resolveWorkerDevice(opts = {}) {
             ?? Object.values(reg).find((p) => p && normalizeHost(p.name) === normalizeHost(name));
         return d?.platform ? String(d.platform).toLowerCase() : undefined;
     };
-    // Platform first: it is a static registry fact, so filtering here keeps the
-    // live probe off boxes that could never be picked anyway.
     const onPlatform = pool.filter((device) => {
         const platform = platformOf(device);
-        // Unknown platform stays a candidate — a registry-only box with no recorded
-        // platform is a gap in the registry, not positive evidence it is Windows.
         if (platform && !wanted.has(platform)) {
             excluded.push({ device, reason: 'wrong-platform' });
             return false;
@@ -79,9 +35,6 @@ export async function resolveWorkerDevice(opts = {}) {
     const eligible = onPlatform.filter((device) => {
         const signal = signals.get(device);
         if (signal?.reachable !== true) {
-            // A probe killed for exceeding its budget says nothing about whether the
-            // box is up — on a relayed fleet it usually is. Report the two apart so
-            // the message points at the link, not at a fleet outage (PHNX-3682).
             excluded.push({ device, reason: signal?.timedOut ? 'probe timed out' : 'unreachable' });
             return false;
         }
@@ -105,7 +58,6 @@ export async function resolveWorkerDevice(opts = {}) {
         excluded,
     };
 }
-/** The one no-worker message, naming every candidate and why it was dropped. */
 export function formatNoWorkerError(excluded, platforms) {
     const detail = excluded.length
         ? excluded.map((e) => `${e.device} (${e.reason})`).join(', ')

package/dist/lib/diff-text.d.ts

@@ -1,26 +1,8 @@
-/**
- * Tiny unified-diff helpers for human-readable doctor output.
- *
- * Wraps the `diff` package's createPatch into one call that returns a
- * pre-coloured unified diff (red = removed, green = added, dim = context).
- * Used by `agents doctor --diff`.
- */
 interface UnifiedDiffOptions {
-    /** Number of context lines around each change (default: 3). */
     context?: number;
-    /** Filename label shown in the patch header for the "expected" side. */
     fromLabel?: string;
-    /** Filename label shown in the patch header for the "actual" side. */
     toLabel?: string;
 }
-/**
- * Build a unified-diff text comparing two strings. Returns an empty string
- * when contents are identical.
- */
 export declare function unifiedDiff(expected: string, actual: string, options?: UnifiedDiffOptions): string;
-/**
- * Colour a unified-diff string for terminal output. Indents each line with
- * a constant prefix so it nests cleanly under a header.
- */
 export declare function colorizeUnifiedDiff(patch: string, indent?: string): string;
 export {};

package/dist/lib/diff-text.js

@@ -1,16 +1,5 @@
-/**
- * Tiny unified-diff helpers for human-readable doctor output.
- *
- * Wraps the `diff` package's createPatch into one call that returns a
- * pre-coloured unified diff (red = removed, green = added, dim = context).
- * Used by `agents doctor --diff`.
- */
 import chalk from 'chalk';
 import { createPatch } from 'diff';
-/**
- * Build a unified-diff text comparing two strings. Returns an empty string
- * when contents are identical.
- */
 export function unifiedDiff(expected, actual, options = {}) {
     if (expected === actual)
         return '';
@@ -19,10 +8,6 @@ export function unifiedDiff(expected, actual, options = {}) {
     const context = options.context ?? 3;
     return createPatch(fromLabel, expected, actual, '', '', { context });
 }
-/**
- * Colour a unified-diff string for terminal output. Indents each line with
- * a constant prefix so it nests cleanly under a header.
- */
 export function colorizeUnifiedDiff(patch, indent = '    ') {
     const lines = patch.split('\n');
     const out = [];

package/dist/lib/doctor-diff.d.ts

@@ -1,40 +1,3 @@
-/**
- * Per-version, per-cwd resource diff for `agents doctor <agent[@version]>`.
- *
- * Mirrors what `syncResourcesToVersion` writes into a version home, then
- * compares each kind back against its resolved source (project > user > system
- * > extra repos). Surfaces:
- *   - ok       — present in home, content matches resolved source
- *   - diff     — present in home, content differs from resolved source
- *   - missing  — resolved source exists, not present in home
- *   - extra    — present in home, no source in any layer
- *
- * Coverage — every kind `syncResourcesToVersion` writes is content-aware, so a
- * byte change under an unchanged name is `diff`, never a false `ok` (PHNX-3504):
- *   commands, skills, hooks, rules — full content compare with source layer.
- *   mcp        — structural compare of the home server def vs resolved source.
- *   subagents  — re-render source through the registry transform, byte-compare.
- *   workflows  — layout-aware per-harness content compare (dir tree or file).
- *   memory     — knowledge facts (~/.agents/memory/*.md), per-fact byte-compare.
- *   plugins    — per-item content compare of the marketplace mirror.
- *   permissions — per-rule compare in the harness's native vocabulary for the
- *     representable harnesses (claude/opencode/cursor/droid/openclaw); the lossy
- *     TOML/flag harnesses stay presence-only with an honest `detail`, never a
- *     faked `ok`.
- * A completeness test binds `DOCTOR_ALL_KINDS` to the writer set so a future
- * synced kind cannot silently become a blind spot. `promptcuts` is NOT a kind —
- * it is not version-scoped, so there is nothing per-home to diff.
- *
- * Intentional asymmetries (must mirror sync):
- *   - hooks ignore the project layer (`syncResourcesToVersion` skips
- *     project/.agents/hooks/ for safety).
- *   - rules/AGENTS.md is compared against the preset composition the rules writer
- *     emits (`composeRulesFromState`), re-rendered from the current `subrules/`
- *     fragments — so a fragment edit is caught even though `rules/AGENTS.md`
- *     never changed. A non-@-import home compiled by `agents refresh-rules`
- *     carries a leading `COMPILED_HEADER`, which is stripped before comparing so
- *     a header-compiled home still reconciles (the header is not source content).
- */
 import type { AgentId } from './types.js';
 import type { DiscoveredPlugin } from './types.js';
 import { type HookWiringReport } from './hooks/install.js';
@@ -47,25 +10,15 @@ export interface ResourceDiff {
     name: string;
     status: DiffStatus;
     source?: SourceLayer;
-    /** Absolute path to the resolved source file/dir (when source is known). */
     sourcePath?: string;
-    /** Absolute path to the file/dir inside the version home (when present). */
     homePath?: string;
-    /** Human-readable specifics for a divergent row — e.g. for a stale plugin:
-     *  "0.6.1→0.7.0, missing skills: ship, learn". Currently set for plugins. */
     detail?: string;
 }
-/** A source layer (user / system / an extra repo) that is behind its upstream —
- *  reconciled against stale truth. Attached to the report by the doctor command
- *  (needs a git probe, kept out of the pure per-version diff). */
 export interface SourceLayerBehind {
     layer: 'user' | 'system' | 'extra';
-    /** Human label for the layer's on-disk root (e.g. `~/.agents`). */
     label: string;
-    /** `agents repo pull` alias for the remediation hint. */
     alias: string;
     behind: number;
-    /** Upstream ref the layer trails (e.g. `origin/main`). */
     branch: string;
 }
 export interface VersionResourceReport {
@@ -89,47 +42,15 @@ export interface VersionResourceReport {
         missing: number;
         extra: number;
     };
-    /** Wiring inspection for the version's native settings.json (claude/droid).
-     *  Populated only when the `hooks` kind is in scope. */
     hookWiring?: HookWiringReport;
-    /** Harness-scoped hook state from the shared inventory engine. */
     hookInventory?: ResourceInventory;
-    /** Source layers behind their upstream. Filled by the doctor command (a git
-     *  probe), not the pure diff — undefined when uncomputed. */
     sourceBehind?: SourceLayerBehind[];
 }
-/**
- * True when `filePath` is a git symlink that was CHECKED OUT AS A PLAIN TEXT
- * FILE — the shape git produces on a client without symlink support (Windows
- * without Developer Mode, `core.symlinks=false`). Such a file holds exactly the
- * link target (a relative path, no trailing newline) instead of the pointed-to
- * content. `lstat().isSymbolicLink()` is FALSE for it, so callers that only
- * skip real symlinks (e.g. the rules/permissions alias files CLAUDE.md /
- * GEMINI.md, which are symlinks to AGENTS.md in the repo) wrongly treat it as
- * an independent resource that no sync can ever reconcile (PHNX-3187). The
- * signal is unambiguous: a whole file with no newline whose entire content
- * resolves to an existing sibling path. Real markdown rule files always contain
- * newlines, so this never false-positives on genuine content.
- */
 export declare function isCheckedOutSymlink(filePath: string): boolean;
-/**
- * Describe how a version's marketplace MIRROR of a plugin diverges from its
- * central source — the detail presence-only checks miss. Surfaces a stale mirror
- * version, a Claude-invalid manifest, and (the part users care about) the
- * plugin's own skills/commands that never made it into the mirror. Returns null
- * when the mirror faithfully matches source.
- */
 export declare function describePluginDrift(central: DiscoveredPlugin, mirrorDir: string): string | null;
 interface DiffOptions {
     cwd?: string;
-    /** Restrict to specific kinds; undefined = all. */
     kinds?: DoctorKind[];
-    /**
-     * Drop the project (`<cwd>/.agents/`) layer from resolution. Used by the heal
-     * path: the GLOBAL version home is only ever reconciled against user/system/
-     * extra sources — project resources are layered at launch, never synced into
-     * the global home, so counting them as "missing" there is a false gap.
-     */
     excludeProject?: boolean;
 }
 export declare function diffVersionResources(agent: AgentId, version: string, options?: DiffOptions): VersionResourceReport;