@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/detach-core.d.ts

@@ -1,23 +1,6 @@
-/**
- * Pure core of `agents sessions detach` — the nudge, the resumed-run argv, and the id
- * resolver. Kept import-light (only a type import) so it is unit-tested without
- * loading the live-session discovery graph.
- */
 import { type ActiveSession } from '../lib/session/active.js';
-/**
- * The prompt the backgrounded run resumes with. Its whole job is to stop a
- * now-unwatched agent from stalling on a confirmation nobody will answer: it
- * tells the agent it is headless and to drive to done, or to stop and state a
- * blocker (which surfaces as a waiting session the user can `attach`).
- */
 export declare const BACKGROUND_NUDGE: string;
-/**
- * Build the argv for the headless continuation `detach` spawns. Agent-agnostic
- * and version-pinned by construction — it goes through the same `agents run
- * --resume` path `attach` reverses.
- */
 export declare function buildBackgroundArgv(agent: string, sessionId: string, cwd?: string): string[];
-/** What to do with a resolved session, given which machine we're on. */
 type DetachTarget = {
     kind: 'local';
     sessionId: string;
@@ -29,18 +12,7 @@ type DetachTarget = {
     kind: 'refuse';
     reason: string;
 };
-/**
- * Decide how to detach a resolved session. Cloud and team sessions are refused
- * (they have their own lifecycles); a session on another machine is delegated to
- * that host over SSH — never stopped/resumed locally, since its pid and tmux
- * socket only mean something where it actually runs. Pure, so every branch is
- * unit-tested without a live pool. Mirrors `focus`/`jumpTo`'s remote branch.
- */
 export declare function resolveDetachTarget(s: ActiveSession, self: string): DetachTarget;
-/**
- * Resolve `<id>` to exactly one live session by prefix. Mirrors `focus`'s match
- * so the two verbs accept the same ids.
- */
 export declare function resolveOne(activeById: Map<string, ActiveSession>, id: string): ActiveSession | {
     error: string;
 };

package/dist/commands/detach-core.js

@@ -1,37 +1,14 @@
-/**
- * Pure core of `agents sessions detach` — the nudge, the resumed-run argv, and the id
- * resolver. Kept import-light (only a type import) so it is unit-tested without
- * loading the live-session discovery graph.
- */
 import { sessionProcessHost } from '../lib/session/active.js';
-/**
- * The prompt the backgrounded run resumes with. Its whole job is to stop a
- * now-unwatched agent from stalling on a confirmation nobody will answer: it
- * tells the agent it is headless and to drive to done, or to stop and state a
- * blocker (which surfaces as a waiting session the user can `attach`).
- */
 export const BACKGROUND_NUDGE = "You've been sent to the background — nobody is watching this session now. " +
     'Continue the current task and drive it to completion end-to-end. ' +
     "Don't ask for confirmation; make the reasonable call and keep going. " +
     'If you genuinely cannot proceed safely, stop and state the blocker plainly in one message.';
-/**
- * Build the argv for the headless continuation `detach` spawns. Agent-agnostic
- * and version-pinned by construction — it goes through the same `agents run
- * --resume` path `attach` reverses.
- */
 export function buildBackgroundArgv(agent, sessionId, cwd) {
     const argv = ['run', agent, BACKGROUND_NUDGE, '--resume', sessionId, '--headless'];
     if (cwd)
         argv.push('--cwd', cwd);
     return argv;
 }
-/**
- * Decide how to detach a resolved session. Cloud and team sessions are refused
- * (they have their own lifecycles); a session on another machine is delegated to
- * that host over SSH — never stopped/resumed locally, since its pid and tmux
- * socket only mean something where it actually runs. Pure, so every branch is
- * unit-tested without a live pool. Mirrors `focus`/`jumpTo`'s remote branch.
- */
 export function resolveDetachTarget(s, self) {
     if (s.context === 'cloud') {
         return { kind: 'refuse', reason: 'Cloud sessions run remotely and cannot be detached from here.' };
@@ -46,19 +23,12 @@ export function resolveDetachTarget(s, self) {
     if (!sessionId) {
         return { kind: 'refuse', reason: 'That session has no id to resume, so it cannot be detached.' };
     }
-    // The box to hop to is where the PROCESS is (a shim lives on its dispatcher),
-    // which is not always `machine`. `sessionProcessHost` returns undefined when
-    // the process is here, so a value means a genuine remote takeover.
     const processHost = sessionProcessHost(s, self);
     if (processHost) {
         return { kind: 'remote', machine: processHost, sessionId };
     }
     return { kind: 'local', sessionId };
 }
-/**
- * Resolve `<id>` to exactly one live session by prefix. Mirrors `focus`'s match
- * so the two verbs accept the same ids.
- */
 export function resolveOne(activeById, id) {
     const q = id.toLowerCase();
     const matches = [...activeById.values()].filter((s) => (s.sessionId ?? '').toLowerCase().startsWith(q));

package/dist/commands/detach.d.ts

@@ -1,15 +1,4 @@
 import type { Command } from 'commander';
 import type { ActiveSession } from '../lib/session/active.js';
-export declare function registerDetachCommand(program: Command): void;
-/**
- * Stop a live agent's interactive process and tear down its mux. tmux-hosted
- * sessions are killed by session (closes the pane, ends the agent, reaps its
- * helper processes); a plain process is SIGTERM'd (then SIGKILLed) by pid. Either
- * way we wait for the process to actually exit before returning.
- *
- * Shared by two callers: `detach` (stop the terminal so the headless resume it
- * spawns next doesn't fight the old process over the same transcript) and `stop`
- * (end the session outright — no resume). `socket` defaults to the shared agents
- * socket; it is a parameter only so a test can drive an isolated tmux server.
- */
+export declare function registerDetachCommand(program: Command, group?: 'sessions' | 'ps'): void;
 export declare function stopInteractive(s: ActiveSession, socket?: string): Promise<void>;

package/dist/commands/detach.js

@@ -1,15 +1,3 @@
-/**
- * `agents sessions detach <id>` — send a live agent session to the background:
- * stop its interactive process and continue it headless, unattended, so it drives
- * its task to completion without holding a terminal. Bring it back with
- * `agents sessions resume`. A sibling of `sessions focus` on the session
- * lifecycle axis.
- *
- * Agent-agnostic and version-pinned by construction: it re-invokes
- * `agents run <agent> "<nudge>" --resume <id> --headless`, which resolves the
- * session's originating version and uses the agent's native resume (claude/codex)
- * or a `/continue` replay (others) — the same path `attach` reverses.
- */
 import { spawn } from 'node:child_process';
 import { openSync, closeSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
@@ -23,8 +11,9 @@ import { writeDetachRecord } from '../lib/session/detached.js';
 import { getLogsDir } from '../lib/state.js';
 import { runOnPeer } from '../lib/session/remote-list.js';
 import { buildBackgroundArgv, resolveDetachTarget, resolveOne } from './detach-core.js';
-export function registerDetachCommand(program) {
-    program
+import { setHelpSections } from '../lib/help.js';
+export function registerDetachCommand(program, group = 'sessions') {
+    const cmd = program
         .command('detach')
         .argument('<id>', 'Short or full id of the live session to background')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
@@ -32,18 +21,16 @@ export function registerDetachCommand(program) {
         .action(async (id, opts) => {
         await detachAction(id, opts);
     });
+    setHelpSections(cmd, {
+        examples: `
+      # Background a live session: its terminal closes, the agent keeps working headless
+      agents ${group} detach 4b2f1a9c
+
+      # Bring it back into a terminal later
+      agents sessions resume 4b2f1a9c
+    `,
+    });
 }
-/**
- * Stop a live agent's interactive process and tear down its mux. tmux-hosted
- * sessions are killed by session (closes the pane, ends the agent, reaps its
- * helper processes); a plain process is SIGTERM'd (then SIGKILLed) by pid. Either
- * way we wait for the process to actually exit before returning.
- *
- * Shared by two callers: `detach` (stop the terminal so the headless resume it
- * spawns next doesn't fight the old process over the same transcript) and `stop`
- * (end the session outright — no resume). `socket` defaults to the shared agents
- * socket; it is a parameter only so a test can drive an isolated tmux server.
- */
 export async function stopInteractive(s, socket = getDefaultSocketPath()) {
     if (s.tmuxTarget) {
         const name = s.tmuxTarget.split(':')[0];
@@ -54,17 +41,12 @@ export async function stopInteractive(s, socket = getDefaultSocketPath()) {
             process.kill(s.pid, 'SIGTERM');
         }
         catch {
-            return; /* already gone — nothing to wait on */
+            return;
         }
     }
     if (s.pid && s.pid > 0)
         await waitForExit(s.pid);
 }
-/**
- * Poll until `pid` is gone (SIGTERM already sent), escalating to SIGKILL past the
- * deadline so a stuck process can't wedge the detach. Bounded so `detach` never
- * hangs waiting on a process that ignores signals.
- */
 async function waitForExit(pid, timeoutMs = 5000) {
     const deadline = Date.now() + timeoutMs;
     for (;;) {
@@ -72,33 +54,22 @@ async function waitForExit(pid, timeoutMs = 5000) {
             process.kill(pid, 0);
         }
         catch {
-            return; /* gone */
+            return;
         }
         if (Date.now() >= deadline) {
             try {
                 process.kill(pid, 'SIGKILL');
             }
             catch {
-                /* raced to exit */
             }
             return;
         }
         await new Promise((r) => setTimeout(r, 100));
     }
 }
-/**
- * Where a backgrounded continuation's stdout/stderr lands, by convention, so a
- * crash after detach is debuggable — there is no terminal watching it, and
- * presence only tells you the pid is gone, not whether the run finished or died.
- */
 function backgroundLogPath(sessionId) {
     return path.join(getLogsDir(), `detach-${sessionId.slice(0, 8)}.log`);
 }
-/**
- * Spawn the headless continuation detached, resolving to its pid for tracking.
- * Its output is redirected to `logFile` rather than discarded, so a fast-failing
- * background run leaves a trail.
- */
 function spawnHeadless(command, args, logFile) {
     return new Promise((resolve, reject) => {
         mkdirSync(path.dirname(logFile), { recursive: true });
@@ -110,14 +81,14 @@ function spawnHeadless(command, args, logFile) {
             try {
                 closeSync(fd);
             }
-            catch { /* fd handed to the child */ }
+            catch { }
             resolve(pid);
         });
         child.once('error', (err) => {
             try {
                 closeSync(fd);
             }
-            catch { /* never opened for the child */ }
+            catch { }
             reject(err instanceof Error ? err : new Error(String(err)));
         });
     });
@@ -132,16 +103,12 @@ async function detachAction(id, opts = {}) {
     }
     const s = resolved;
     const target = resolveDetachTarget(s, self);
-    // Cloud, team, and id-less sessions can't be backgrounded from here.
     if (target.kind === 'refuse') {
         console.error(chalk.red(target.reason));
         process.exitCode = 1;
         return;
     }
     const short = target.sessionId.slice(0, 8);
-    // A session on another host: its pid and tmux socket only mean something where
-    // it runs, so detach it *there* over SSH — never kill/resume locally. Mirrors
-    // focus/jumpTo's remote branch.
     if (target.kind === 'remote') {
         console.log(chalk.gray(`${short} lives on ${target.machine} — detaching it there over SSH…`));
         const rc = await runOnPeer(['sessions', 'detach', target.sessionId, '--local'], target.machine);
@@ -151,15 +118,12 @@ async function detachAction(id, opts = {}) {
         }
         return;
     }
-    // Local: stop the interactive process, then continue it headless, detached —
-    // version-pinned via the existing `agents run --resume` path.
     const sessionId = target.sessionId;
     const agent = s.kind;
     await stopInteractive(s);
     const logFile = backgroundLogPath(sessionId);
     const inv = getAgentsInvocation(buildBackgroundArgv(agent, sessionId, s.cwd));
     const pid = await spawnHeadless(inv.command, inv.args, logFile);
-    // Record it so `attach` and `agents ls --active` know it's backgrounded.
     writeDetachRecord({
         sessionId,
         agent,

package/dist/commands/device-config-test-harness.js

@@ -4,13 +4,6 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-// End-to-end tests for the unified `agents devices config` surface and the
-// retired-subcommand tombstones (configure / note / set / set-interactive /
-// enable / disable / prefer / unprefer). Spawns the REAL CLI against a
-// throwaway HOME (same pattern as ssh.test.ts) — no mocking; the assertions
-// read the actual files the commands wrote: per-device docs under
-// devices/<name>/agents.yaml (device layer) and central agents.yaml
-// fleet.defaults.config (fleet layer).
 export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const INDEX = path.join(REPO_ROOT, 'src', 'index.ts');
 let testHome = '';
@@ -31,14 +24,9 @@ export function run(args, extraEnv = {}) {
         env: {
             ...process.env,
             HOME: testHome,
-            // os.homedir() reads USERPROFILE on Windows, so HOME alone leaves the
-            // spawned CLI resolving the real profile ('agents-cli is not set up').
             USERPROFILE: testHome,
             AGENTS_NO_UPDATE_CHECK: '1',
             AGENTS_NO_USAGE_TRACK: '1',
-            // Default identity is mac-mini so machine-local keys (scheduler, tmux,
-            // browser consent) can be set in these tests. Override per-call to act
-            // as a different box.
             AGENTS_SYNC_MACHINE_ID: 'mac-mini',
             ...extraEnv,
         },

package/dist/commands/doctor.d.ts

@@ -1,26 +1,3 @@
-/**
- * `agents doctor` — diagnostic readout across the install.
- *
- * Two modes:
- *
- *   1. Overview (no target): three sections —
- *      - CLI availability (which agent binaries can be invoked).
- *      - Sync status per default version (fresh / stale / never-synced).
- *      - Orphans per default version per resource type.
- *
- *   2. Target mode: `agents doctor <agent>[@version]` — full per-resource
- *      diff for a single (agent, version) against the current cwd's resolved
- *      sources. Reports ok / DIFF / MISS / EXTRA per resource with the source
- *      layer (project, user, system, extra repo). With `--diff`, renders a
- *      unified diff body for each divergent file. Mirrors the resolution that
- *      the shim drives at runtime: project > user > system > extras.
- *
- * Read-only always: doctor diagnoses, it never mutates. To fix the gaps it
- * finds — install missing resources, repair Claude-invalid plugin manifests,
- * refresh stale plugins, reconcile drift, repair hook runtime shims — run
- * `agents sync <agent>@all` (the one fixer). Run `agents prune cleanup` to act
- * on orphan readouts.
- */
 import type { Command } from 'commander';
 import { type FleetInventory } from '../lib/devices/fleet-divergence.js';
 import { type DoctorFinding } from '../lib/devices/doctor-findings.js';
@@ -30,108 +7,28 @@ import { type SyncStatusRow, type OrphanRow } from '../lib/drift.js';
 import { type FetchStatusMarker } from '../lib/auto-pull.js';
 export declare function wrapLine(prefix: string, text: string, width?: number): string[];
 export declare function asRemoteSecretFindings(raw: unknown, device: string): DoctorFinding[];
-/**
- * Fetch a device's harness inventory by running its top-level `agents doctor
- * --json` (which carries the `fleet` field, RUSH-2027). Separate from
- * {@link probeFleetTarget} — that forwards `teams doctor --json` for per-agent
- * readiness, a different payload. Returns the parsed {@link FleetInventory} or
- * null (unreachable, non-zero exit, unparseable, or an older CLI with no
- * `fleet` field); a null is skipped by the comparator, never a false gap.
- */
-/**
- * How long one remote `doctor --json` probe may take.
- *
- * 180s, matching `ChildProcess.doctorTimeout`, which was set to 180 for this
- * same command for this same reason. The previous 30s sat BELOW the command's
- * real cost — 56s measured on `yosemite-m0`, 136s on an idle box — so every slow
- * device silently contributed nothing at all: no inventory, no sign-in, no
- * divergence, no secret findings. A ceiling under the true cost does not make a
- * probe cheap, it makes it always fail.
- *
- * This does not multiply by device count: `fanOutDevices` is `Promise.all`, so
- * whole-fleet wall time is bounded near the slowest box, not 180s x N.
- */
 export declare const FLEET_INVENTORY_TIMEOUT_MS = 180000;
-/**
- * Narrow a remote `doctor --json` `.fleet` payload to a usable inventory, or null.
- *
- * The remote runs ITS OWN agents-cli, whose version we do not control, so the
- * payload is untrusted input rather than a typed value — a cast alone let a
- * partial object (`{"fleet":{}}` from a skewed or truncated remote) reach
- * `compareFleetInventories`, which indexes `inv.resources[kind]` and
- * `Object.keys(inv.agentVersions)` unconditionally and throws. Returning null
- * routes that device into the existing "older agents-cli / no inventory" path,
- * which is honest and already rendered, instead of aborting the whole fan-out.
- *
- * This validates EVERY field of {@link FleetInventory} that anything downstream
- * reads — `resources`, `agentVersions`, `repos` and each optional `signIn` row.
- * It was tightened four times during review, each round finding the next
- * unvalidated layer, so treat partial validation here as a bug: a field added to
- * the inventory must be checked here in the same change.
- */
 export declare function asFleetInventory(value: unknown): FleetInventory | null;
 export type IssueSeverity = 'critical' | 'warning' | 'info';
-/**
- * One triaged health finding. `severity`/`category`/`subject`/`impact`/`fix` are
- * the triage backbone the human report renders and `--json` carries; `text`/`color`
- * stay the terse combined label older readers used, so the shape is additive.
- *
- * Severity model (agent-agnostic — applies to every agent doctor inspects):
- *   - critical (silent breakage): an unwired hook, a missing/unparseable
- *     settings.json, a MISSING hook or plugin.
- *   - warning (stale / drift): a source layer behind origin, a DIVERGENT resource,
- *     a stale / never-synced version, a MISSING resource of any other kind
- *     (see `missingResourceSeverity`, which reads this split from
- *     `FINDING_SEVERITY` — RUSH-2947).
- *   - info (orphan): an EXTRA resource → `agents prune cleanup`.
- */
 export interface VerdictIssue {
     severity: IssueSeverity;
-    /** machine-stable class: unwired-hook | settings-missing | settings-unparseable
-     *  | missing | source-behind | divergent | extra | stale | never-synced | orphan */
     category: string;
-    /** the hook / resource / layer / version the finding is about */
     subject: string;
-    /** one-line plain-English consequence */
     impact: string;
-    /** exact remediation command */
     fix: string;
-    /** terse combined label (legacy) */
     text: string;
     color: 'yellow' | 'red' | 'magenta';
 }
 export interface DoctorVerdict {
     healthy: boolean;
     issues: VerdictIssue[];
-    /** Resources (target) / versions (overview) reconciled clean — drives the
-     *  healthy line's count. */
     reconciled: number;
 }
 export declare function verdictIsAutoFixable(v: DoctorVerdict): boolean;
-/**
- * Fold a version report's divergences into a triaged verdict — one severity-tagged
- * finding per unwired hook, missing/divergent/extra resource, and behind-origin
- * source layer, each carrying its subject, plain-English impact, and exact fix. An
- * UNWIRED hook or a stale source is as unhealthy as a divergent file, not a
- * footnote. Pure so the health rollup is unit-testable without a version home.
- */
 export declare function computeVerdict(report: VersionResourceReport): DoctorVerdict;
-/**
- * Build the lines of a triaged health block: a single green ✓ line when healthy,
- * otherwise a severity-counted ✗ header followed by one row per finding (icon ·
- * severity · subject — impact, then the exact fix under it) and an optional heal
- * footer. Pure — returns the lines so the rendered output is unit-testable. Shared
- * by target mode and the bare overview so both read the same way.
- */
 export declare function healthBlockLines(verdict: DoctorVerdict, opts: {
     healthySummary: string;
     healFix?: string;
 }): string[];
-/**
- * Aggregate the bare `agents doctor` overview into the same triaged verdict target
- * mode uses — folding per-version wiring/sync drift, behind-origin source layers,
- * and orphan resources into severity-tagged findings. Agent-agnostic: every
- * installed version is classified the same way. Pure, so it is unit-testable.
- */
 export declare function computeOverviewHealth(syncRows: SyncStatusRow[], orphanRows: OrphanRow[], repoBehindMarkers: FetchStatusMarker[], duplicateHooks?: DuplicateVersionHook[]): DoctorVerdict;
 export declare function registerDoctorCommand(program: Command): void;