@phnx-labs/agents-cli 1.22.104 → 1.22.106

package/dist/commands/resume.d.ts

@@ -1,28 +1,20 @@
 import type { SessionMeta } from '../lib/session/types.js';
 export declare const RESUME_SOURCE_ENV = "AGENTS_RESUME_SOURCE_JSON";
-/**
- * The source a dead-remote local fallback resumes from: the same session, but
- * with `machine` rewritten to THIS box so the delegated `agents run --resume`
- * resolves recovery locally (`sessionRecoveryPeer` returns undefined) instead of
- * bouncing back to the unreachable owner. Because no local version home owns the
- * peer's transcript, that local recovery lands on a labelled `/continue` replay
- * from the synced mirror — the only way to continue a session whose owning device
- * is gone. Owner-approved prefer-device, fall-back-local (PHNX-3626).
- *
- * Safe against the RUSH-2022 "silent local resume forks live state" hazard by
- * PRECONDITION: this is reached only after `runOnPeer` proved the owner
- * unreachable, so there is no live process on the peer to fork, and the fallback
- * is announced with a log line — never silent.
- */
+/** Inspect local archived context after the owner hop fails. Recovery still
+ * requires readable content and explicit replay consent before starting a run. */
 export declare function resumeLocalFallbackSource(session: SessionMeta, self?: string): SessionMeta;
 export interface StrictResumeOptions {
+    agent?: string;
     mode?: string;
+    account?: string;
+    model?: string;
     interactive?: boolean;
     headless?: boolean;
     cwd?: string;
     quiet?: boolean;
     /** Run on THIS machine even when the session belongs to a peer (escape hatch). */
     here?: boolean;
+    local?: boolean;
 }
 /**
  * The argv to re-run this resume on the machine that owns the session.
@@ -40,13 +32,6 @@ export declare function buildResumeRunArgs(session: {
     agent: string;
     version?: string;
 }, prompt: string | undefined, options: StrictResumeOptions): string[];
-/** Recreate a remote Claude launch whose forced id never materialized a transcript. */
-export declare function buildProvisionalRunArgs(session: {
-    id: string;
-    agent: string;
-    version?: string;
-    cwd?: string;
-}, prompt: string | undefined, options: StrictResumeOptions): string[];
 /** True when the caller asked for the strict resume path (prompt and/or flags). */
 export declare function wantsStrictResume(prompt: string | undefined, options: StrictResumeOptions): boolean;
 /**

package/dist/commands/resume.js

@@ -9,20 +9,8 @@ import { resolveSessionMetadataValue } from './sessions.js';
 import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../lib/session/resume-owner.js';
 import { machineId } from '../lib/machine-id.js';
 export const RESUME_SOURCE_ENV = 'AGENTS_RESUME_SOURCE_JSON';
-/**
- * The source a dead-remote local fallback resumes from: the same session, but
- * with `machine` rewritten to THIS box so the delegated `agents run --resume`
- * resolves recovery locally (`sessionRecoveryPeer` returns undefined) instead of
- * bouncing back to the unreachable owner. Because no local version home owns the
- * peer's transcript, that local recovery lands on a labelled `/continue` replay
- * from the synced mirror — the only way to continue a session whose owning device
- * is gone. Owner-approved prefer-device, fall-back-local (PHNX-3626).
- *
- * Safe against the RUSH-2022 "silent local resume forks live state" hazard by
- * PRECONDITION: this is reached only after `runOnPeer` proved the owner
- * unreachable, so there is no live process on the peer to fork, and the fallback
- * is announced with a log line — never silent.
- */
+/** Inspect local archived context after the owner hop fails. Recovery still
+ * requires readable content and explicit replay consent before starting a run. */
 export function resumeLocalFallbackSource(session, self = machineId()) {
     return { ...session, machine: self };
 }
@@ -36,6 +24,12 @@ export function resumeLocalFallbackSource(session, self = machineId()) {
  */
 export function buildResumeRemoteArgs(sessionId, prompt, options) {
     const args = ['sessions', 'resume', sessionId, ...(prompt === undefined ? [] : [prompt])];
+    if (options.agent)
+        args.push('--agent', options.agent);
+    if (options.account)
+        args.push('--account', options.account);
+    if (options.model)
+        args.push('--model', options.model);
     if (options.mode)
         args.push('--mode', options.mode);
     if (options.interactive)
@@ -51,8 +45,12 @@ export function buildResumeRemoteArgs(sessionId, prompt, options) {
 /** Translate `agents sessions resume <id>` to the canonical `agents run` surface after
  * resolving the source identity. The run command remains the only executor. */
 export function buildResumeRunArgs(session, prompt, options) {
-    const spec = session.version ? `${session.agent}@${session.version}` : session.agent;
+    const spec = session.agent;
     const args = ['run', spec, ...(prompt === undefined ? [] : [prompt]), '--resume', session.id];
+    if (options.account)
+        args.push('--account', options.account);
+    if (options.model)
+        args.push('--model', options.model);
     if (options.mode)
         args.push('--mode', options.mode);
     if (options.interactive)
@@ -65,23 +63,6 @@ export function buildResumeRunArgs(session, prompt, options) {
         args.push('--quiet');
     return args;
 }
-/** Recreate a remote Claude launch whose forced id never materialized a transcript. */
-export function buildProvisionalRunArgs(session, prompt, options) {
-    const spec = session.version ? `${session.agent}@${session.version}` : session.agent;
-    const args = ['run', spec, ...(prompt === undefined ? [] : [prompt]), '--session-id', session.id];
-    if (options.mode)
-        args.push('--mode', options.mode);
-    if (options.interactive)
-        args.push('--interactive');
-    if (options.headless)
-        args.push('--headless');
-    const cwd = options.cwd ?? session.cwd;
-    if (cwd)
-        args.push('--cwd', cwd);
-    if (options.quiet)
-        args.push('--quiet');
-    return args;
-}
 function consumeResumeSource() {
     const raw = process.env[RESUME_SOURCE_ENV];
     delete process.env[RESUME_SOURCE_ENV];
@@ -124,7 +105,7 @@ export async function runStrictResume(sessionId, prompt, options) {
     }
     // An owner hop must inspect only the owner's index. Fleet fan-out here can
     // rediscover the dispatcher's synthetic row and bounce the same id forever.
-    const outcome = await resolveSessionMetadataValue(sessionId.trim(), pinnedHere ? { local: true } : {});
+    const outcome = await resolveSessionMetadataValue(sessionId.trim(), { agent: options.agent, local: pinnedHere || options.local });
     if (outcome.kind === 'partial') {
         // RUSH-2492: an unreachable peer is a warning, not a hard failure. The
         // resolver already resolves an id found on the reachable fleet (SES-9a),
@@ -138,19 +119,6 @@ export async function runStrictResume(sessionId, prompt, options) {
         return;
     }
     if (outcome.kind === 'not-found') {
-        if (routedHop && routedSource?.filePath === '' && routedSource.agent === 'claude') {
-            const args = buildProvisionalRunArgs(routedSource, prompt, options);
-            const child = spawn(process.execPath, [process.argv[1], ...args], {
-                stdio: 'inherit',
-                env: process.env,
-            });
-            const exitCode = await new Promise((resolve) => {
-                child.once('error', () => resolve(127));
-                child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
-            });
-            process.exitCode = exitCode;
-            return;
-        }
         console.error(chalk.red(`No session matching "${sessionId}".`));
         process.exitCode = 1;
         return;
@@ -184,21 +152,16 @@ export async function runStrictResume(sessionId, prompt, options) {
             sessionId: outcome.session.id,
         });
         if (rc === 'no-target' || rc === 'unreachable') {
-            // Prefer-device, fall back to local (PHNX-3626): the owning device is
-            // unreachable — either not a dialable registered device ('no-target') or
-            // registered but offline/asleep so the SSH connection itself failed
-            // ('unreachable'). Either way there is no live harness to reach OR to fork,
-            // so continue the session HERE from its synced mirror rather than
-            // dead-ending. The local recovery resolves this to a labelled `/continue`
-            // replay (no local home owns the peer's transcript), the honest degradation.
+            // The owner may still be running. Only verified local content can be
+            // offered as a separate conversation after explicit replay consent.
             if (!options.quiet) {
-                process.stderr.write(chalk.yellow(`[agents] session ${outcome.session.shortId} belongs to ${owner}, which is unreachable → resuming locally (/continue replay from the synced transcript)\n`));
+                process.stderr.write(chalk.yellow(`[agents] session ${outcome.session.shortId} belongs to ${owner}, which is unreachable; checking for local transcript content before offering replay\n`));
             }
             process.exitCode = await delegateLocalResume(resumeLocalFallbackSource(outcome.session), prompt, options);
         }
         return;
     }
-    process.exitCode = await delegateLocalResume(outcome.session, prompt, options);
+    process.exitCode = await delegateLocalResume(pinnedHere ? resumeLocalFallbackSource(outcome.session) : outcome.session, prompt, options);
 }
 /**
  * Spawn the delegated local `agents run --resume` for a session this box owns

package/dist/commands/run-device-picker.d.ts

@@ -0,0 +1,58 @@
+import type { AgentId } from '../lib/types.js';
+import { type Headroom } from '../lib/devices/health.js';
+/** One row of the menu, already resolved from disk. Pure data so ordering is testable. */
+export interface RunDeviceRow {
+    name: string;
+    platform?: string;
+    isLocal: boolean;
+    online: 'online' | 'offline' | 'unknown';
+    role?: string;
+    description?: string;
+    loadPercent?: number;
+    memPercent?: number;
+    headroom: Headroom;
+    statsFetchedAt?: number;
+    lastSeenAt?: string;
+    hasAccount?: boolean;
+}
+export interface RunDeviceChoice {
+    name: string;
+    value: string;
+    disabled?: boolean | string;
+}
+/**
+ * Pure. Ordering: this machine first; then online rows by headroom (idle,
+ * light, busy, loaded, unknown) then loadPercent ascending then name; then
+ * unknown-state rows; then offline rows, disabled with the last-seen time.
+ *
+ * `accountLabel` renders the ✓/– account mark on rows whose `hasAccount` the
+ * catalog answered; without it the mark is omitted (hasAccount stays on the
+ * row for the caller either way).
+ */
+export declare function buildRunDeviceChoices(rows: RunDeviceRow[], accountLabel?: string): RunDeviceChoice[];
+/**
+ * Reads devices.yaml + the cached fleet stats + configured roles + (optionally)
+ * whether `accountLabel` exists on each box. ZERO SSH, zero network, never
+ * re-probes. Returns the rows and the age of the newest stats row (undefined
+ * when no cache).
+ */
+export declare function readRunDeviceRows(opts: {
+    agent: AgentId;
+    accountLabel?: string;
+}): {
+    rows: RunDeviceRow[];
+    snapshotAgeMs?: number;
+};
+/**
+ * Interactive menu. Off a TTY: fail loud with the non-interactive forms,
+ * exactly like the account picker. Prompt message: `Select a device for this
+ * run (fleet state as of <age>):` where <age> is e.g. '2 min ago', or
+ * `Select a device for this run (no cached fleet state):`. Returns the device
+ * name, or null when the user cancels (Esc/Ctrl-C) — a cancel launches
+ * nothing. Throws when the registry has no devices at all (the message names
+ * `agents devices add`).
+ */
+export declare function pickRunDevice(opts: {
+    agent: AgentId;
+    accountLabel?: string;
+}): Promise<string | null>;

package/dist/commands/run-device-picker.js

@@ -0,0 +1,222 @@
+/**
+ * Device picker for `agents run <agent>@` (PHNX-4083).
+ *
+ * The menu behind the trailing-`@` form: every registered fleet device,
+ * rendered from files the daemon already keeps on disk — the SSH device
+ * registry, the cached fleet stats (`.fleet-stats.json`), the fleet-synced
+ * device docs (roles + descriptions), and the fleet-synced account catalog.
+ *
+ * This module NEVER probes: no SSH, no network, no re-fetch of stale rows.
+ * `loadFleetStats` re-probes rows older than 3 minutes over SSH, which is the
+ * multi-second hang a mid-run menu cannot afford; the whole point here is that
+ * the picker renders the last cached fleet state, honestly aged ("fleet state
+ * as of 2 min ago"), instead of re-deriving it live.
+ *
+ * PR 2 wires this into `agents run`; this module ships the data + menu only.
+ */
+import { select } from '@inquirer/prompts';
+import { headroom } from '../lib/devices/health.js';
+import { loadDevicesSync } from '../lib/devices/registry.js';
+import { readStatsCache } from '../lib/devices/stats-cache.js';
+import { deviceOnlineState } from '../lib/devices/reachability.js';
+import { isSelfHost } from '../lib/devices/self-host.js';
+import { normalizeHost } from '../lib/machine-id.js';
+import { localMachineId } from '../lib/origin-machine.js';
+import { listConfiguredDeviceRoles, readDeviceConfigValues } from '../lib/device-config.js';
+import { listNativeAccounts } from '../lib/account-registry.js';
+import { readSharedAccountVerdicts } from '../lib/account-catalog.js';
+import { readMeta } from '../lib/state.js';
+import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
+const HEADROOM_ORDER = {
+    idle: 0,
+    light: 1,
+    busy: 2,
+    loaded: 3,
+    unknown: 4,
+};
+function formatPercentCell(value, suffix) {
+    return value === undefined ? '—' : `${Math.round(value)}% ${suffix}`;
+}
+/** 'HH:MM' (local) from an ISO timestamp; the raw string when it does not parse. */
+function formatHourMinute(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    const hh = String(d.getHours()).padStart(2, '0');
+    const mm = String(d.getMinutes()).padStart(2, '0');
+    return `${hh}:${mm}`;
+}
+/**
+ * Pure. Ordering: this machine first; then online rows by headroom (idle,
+ * light, busy, loaded, unknown) then loadPercent ascending then name; then
+ * unknown-state rows; then offline rows, disabled with the last-seen time.
+ *
+ * `accountLabel` renders the ✓/– account mark on rows whose `hasAccount` the
+ * catalog answered; without it the mark is omitted (hasAccount stays on the
+ * row for the caller either way).
+ */
+export function buildRunDeviceChoices(rows, accountLabel) {
+    const byHeadroomLoadName = (a, b) => HEADROOM_ORDER[a.headroom] - HEADROOM_ORDER[b.headroom]
+        || (a.loadPercent ?? Number.POSITIVE_INFINITY) - (b.loadPercent ?? Number.POSITIVE_INFINITY)
+        || a.name.localeCompare(b.name);
+    const local = rows.filter((row) => row.isLocal);
+    const online = rows.filter((row) => !row.isLocal && row.online === 'online').sort(byHeadroomLoadName);
+    const unknownState = rows.filter((row) => !row.isLocal && row.online === 'unknown').sort(byHeadroomLoadName);
+    const offline = rows
+        .filter((row) => !row.isLocal && row.online === 'offline')
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const ordered = [...local, ...online, ...unknownState, ...offline];
+    const nameWidth = Math.max(0, ...ordered.map((row) => row.name.length));
+    const platformWidth = Math.max(0, ...ordered.map((row) => row.platform?.length ?? 0));
+    const statusWidth = Math.max(0, ...ordered.map((row) => (row.isLocal ? 'this machine' : row.online).length));
+    const headroomWidth = Math.max(0, ...ordered.map((row) => row.headroom.length));
+    const loadWidth = Math.max(0, ...ordered.map((row) => formatPercentCell(row.loadPercent, 'load').length));
+    const memWidth = Math.max(0, ...ordered.map((row) => formatPercentCell(row.memPercent, 'mem').length));
+    return ordered.map((row) => {
+        const account = accountLabel !== undefined && row.hasAccount !== undefined
+            ? `${row.hasAccount ? '✓' : '–'} ${accountLabel}`
+            : undefined;
+        const name = [
+            row.name.padEnd(nameWidth),
+            (row.platform ?? '').padEnd(platformWidth),
+            (row.isLocal ? 'this machine' : row.online).padEnd(statusWidth),
+            row.headroom.padEnd(headroomWidth),
+            formatPercentCell(row.loadPercent, 'load').padEnd(loadWidth),
+            formatPercentCell(row.memPercent, 'mem').padEnd(memWidth),
+            row.role,
+            account,
+        ].filter((segment) => segment !== undefined && segment !== '').join(' · ');
+        return {
+            name: name.trimEnd(),
+            value: row.name,
+            ...(row.online === 'offline'
+                ? { disabled: row.lastSeenAt ? `offline since ${formatHourMinute(row.lastSeenAt)}` : 'offline' }
+                : {}),
+        };
+    });
+}
+/**
+ * The catalog's per-device answer for one account label, straight off the
+ * fleet-synced shared state (the same rows `agents view` renders): the daemon
+ * on each box publishes an auth verdict per registered account, and absence of
+ * a verdict row on a publishing box means the account is not provisioned
+ * there. A box that publishes no account rows at all (an older release) cannot
+ * be answered for — its devices stay `undefined`, never guessed.
+ */
+function resolveAccountDevices(agent, accountLabel) {
+    const account = listNativeAccounts(readMeta()).find((row) => row.agent === agent && (row.name === accountLabel || row.id === accountLabel));
+    if (!account)
+        return undefined; // the catalog has no such account — it cannot answer for any device
+    const shared = readSharedAccountVerdicts();
+    const publishing = new Set();
+    for (const rows of shared.values()) {
+        for (const row of rows)
+            publishing.add(normalizeHost(row.device));
+    }
+    const byDevice = new Map();
+    for (const row of shared.get(`${agent}:${account.id}`) ?? []) {
+        byDevice.set(normalizeHost(row.device), row.verdict !== 'missing');
+    }
+    return { byDevice, publishing };
+}
+/**
+ * Reads devices.yaml + the cached fleet stats + configured roles + (optionally)
+ * whether `accountLabel` exists on each box. ZERO SSH, zero network, never
+ * re-probes. Returns the rows and the age of the newest stats row (undefined
+ * when no cache).
+ */
+export function readRunDeviceRows(opts) {
+    const registry = loadDevicesSync();
+    const statsCache = readStatsCache();
+    const names = Object.keys(registry);
+    const roles = listConfiguredDeviceRoles(names);
+    const local = normalizeHost(localMachineId());
+    const accountDevices = opts.accountLabel
+        ? resolveAccountDevices(opts.agent, opts.accountLabel)
+        : undefined;
+    let newestFetchedAt;
+    for (const stats of Object.values(statsCache)) {
+        if (newestFetchedAt === undefined || stats.fetchedAt > newestFetchedAt)
+            newestFetchedAt = stats.fetchedAt;
+    }
+    const snapshotAgeMs = newestFetchedAt === undefined ? undefined : Math.max(0, Date.now() - newestFetchedAt);
+    const rows = names.map((name) => {
+        const profile = registry[name];
+        const stats = statsCache[name];
+        const online = deviceOnlineState(profile, stats);
+        const config = readDeviceConfigValues(name);
+        const description = typeof config.description === 'string' ? config.description : undefined;
+        const host = normalizeHost(name);
+        return {
+            name,
+            platform: profile.platform === 'unknown' ? undefined : profile.platform,
+            isLocal: isSelfHost(name) || host === local,
+            online,
+            role: roles[name],
+            description,
+            loadPercent: stats?.loadPercent,
+            memPercent: stats?.memPercent,
+            headroom: headroom(stats),
+            statsFetchedAt: stats?.fetchedAt,
+            lastSeenAt: online === 'offline'
+                ? profile.reachability?.checkedAt ?? profile.tailscale?.lastSeen
+                : undefined,
+            hasAccount: accountDevices
+                ? accountDevices.publishing.has(host)
+                    ? accountDevices.byDevice.get(host) ?? false
+                    : undefined
+                : undefined,
+        };
+    });
+    return { rows, snapshotAgeMs };
+}
+/** Human age for the prompt's "fleet state as of …" note: 'just now', '2 min ago', '3 h ago', … */
+function formatSnapshotAge(ageMs) {
+    if (ageMs < 45_000)
+        return 'just now';
+    if (ageMs < 90_000)
+        return '1 min ago';
+    if (ageMs < 3_600_000)
+        return `${Math.round(ageMs / 60_000)} min ago`;
+    if (ageMs < 86_400_000)
+        return `${Math.round(ageMs / 3_600_000)} h ago`;
+    return `${Math.round(ageMs / 86_400_000)} d ago`;
+}
+/**
+ * Interactive menu. Off a TTY: fail loud with the non-interactive forms,
+ * exactly like the account picker. Prompt message: `Select a device for this
+ * run (fleet state as of <age>):` where <age> is e.g. '2 min ago', or
+ * `Select a device for this run (no cached fleet state):`. Returns the device
+ * name, or null when the user cancels (Esc/Ctrl-C) — a cancel launches
+ * nothing. Throws when the registry has no devices at all (the message names
+ * `agents devices add`).
+ */
+export async function pickRunDevice(opts) {
+    // An empty registry is wrong on every terminal, so it is judged before the
+    // TTY gate: "register a device" is the useful answer, not "need a TTY".
+    const { rows, snapshotAgeMs } = readRunDeviceRows(opts);
+    if (rows.length === 0) {
+        throw new Error('No devices are registered. Add one with: agents devices add <name>');
+    }
+    if (!isInteractiveTerminal()) {
+        requireInteractiveSelection('Selecting a device', [
+            `agents run ${opts.agent} --device <name>`,
+            'agents devices',
+        ]);
+    }
+    const choices = buildRunDeviceChoices(rows, opts.accountLabel);
+    try {
+        return await select({
+            message: snapshotAgeMs !== undefined
+                ? `Select a device for this run (fleet state as of ${formatSnapshotAge(snapshotAgeMs)}):`
+                : 'Select a device for this run (no cached fleet state):',
+            choices,
+            loop: false,
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return null;
+        throw err;
+    }
+}

package/dist/commands/sessions-resume.d.ts

@@ -20,9 +20,13 @@ export interface ResumeOptions extends StrictResumeOptions {
     splits?: boolean;
     attachOnly?: boolean;
     local?: boolean;
+    /** Original run argv; only the bare resume selector changes after picking. */
+    runArgs?: string[];
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
 export declare function sessionsResumeAction(query: string | undefined, prompt: string | undefined, options: ResumeOptions): Promise<void>;
+/** Preserve run options and lifecycle intent when the picker opens its selected rows. */
+export declare function buildSelectedResumeArgs(id: string, prompt: string | undefined, options: ResumeOptions): string[];
 /** IDs and tmux aliases are actions, not picker search text. Human phrases keep
  * the existing pre-filtered picker, while an explicit identity resumes directly. */
 export declare function isDirectResumeSelector(query: string): boolean;