@phnx-labs/agents-cli 1.22.23 → 1.22.25

package/dist/commands/sessions-resume.js

@@ -14,14 +14,16 @@ import { discoverSessions } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { multiItemPicker, itemPicker } from '../lib/picker.js';
 import { buildPreview } from './sessions-picker.js';
-import { filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, resumeSessionInPlace, parseAgentFilter, } from './sessions.js';
+import { formatPickerLabel, pickerColumnsFor, buildSessionRecoveryCommand, resumeSessionInPlace, parseAgentFilter, } from './sessions.js';
+import { sessionMatchesQuery } from './sessions-browser.js';
 import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, } from '../lib/terminal/index.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { confirm } from '@inquirer/prompts';
 import { spawn } from 'node:child_process';
-import { buildCanonicalResumeCommand } from '../lib/session/resume-command.js';
 import { looksLikeSessionId } from '../lib/session/discover.js';
+import { machineId } from '../lib/session/sync/config.js';
+import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
@@ -34,7 +36,7 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('-n, --limit <n>', 'Maximum number of sessions to load into the picker', '200')
-        .option('--host <alias>', 'Resume on a remote host over SSH (defaults to tmux there)')
+        .option('--host <alias>', 'Open on the session origin host over SSH; the host must match every selected session')
         .option('--iterm', 'Force the iTerm backend')
         .option('--ghostty', 'Force the Ghostty backend')
         .option('--tmux', 'Force the tmux backend')
@@ -65,8 +67,8 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       - Layout: one tab per session by default. --splits packs session pairs side by side in each tab.
       - Backend: auto-detected from the terminal you're in (iTerm / Ghostty / tmux); override with --iterm/--ghostty/--tmux/--vscodium.
       - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --host too).
-      - --host <alias> resumes on a remote machine over the same SSH transport as 'sessions --host' (defaults to tmux).
-      - Each session opens version-pinned, in its own cwd. Non-resumable agents are skipped with a note.
+      - --host <alias> opens the terminal surface on that host only when it is the selected sessions' origin; recovery never migrates a session to another device.
+      - Recovery runs on the session's origin device: exact healthy origin uses native resume; otherwise a healthy version of the same harness receives /continue <id>.
     `,
     });
     cmd.action(async (query, options) => {
@@ -110,7 +112,7 @@ async function sessionsResumeAction(query, options) {
         chosen = await multiItemPicker({
             message: 'Select sessions to resume:',
             items: sessions,
-            filter: (q) => (q.trim() ? filterSessionsByQuery(sessions, q) : sessions),
+            filter: (q) => (q.trim() ? sessions.filter((s) => sessionMatchesQuery(s, q)) : sessions),
             labelFor: (s, q) => formatPickerLabel(s, q, cols),
             keyFor: (s) => s.id,
             buildPreview,
@@ -127,17 +129,25 @@ async function sessionsResumeAction(query, options) {
     }
     if (!chosen || chosen.length === 0)
         return;
-    // 2. Split the selection into resumable surfaces and skipped agents (no silent drop).
+    if (options.host) {
+        const requestedHost = options.host;
+        const mismatches = chosen
+            .map((session) => resumeHostMismatch(session, requestedHost))
+            .filter((message) => message !== null);
+        if (mismatches.length > 0) {
+            for (const message of mismatches)
+                console.error(chalk.red(message));
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 2. Route every selection through the owning device's recovery resolver.
     const items = [];
     for (const s of chosen) {
-        const command = buildCanonicalResumeCommand(s.id);
+        const command = buildSessionRecoveryCommand(s, !!options.host);
         const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
         items.push({ session: s, cwd, command });
     }
-    if (items.length === 0) {
-        console.log(chalk.gray('Nothing resumable in the selection.'));
-        return;
-    }
     // 3. Resolve the backend (and host).
     const ctx = currentContext();
     const backend = await resolveBackend(options, ctx, items.length);
@@ -221,6 +231,12 @@ async function spawnCliInPlace(args) {
 export function resolveResumePacking(options) {
     return options.splits ? 'two-per-tab' : 'tabs';
 }
+export function resumeHostMismatch(session, requestedHost, self = machineId()) {
+    const origin = sessionOriginDevice(session, self);
+    return sessionRecoveryDestinationMatches(session, requestedHost, self)
+        ? null
+        : `Session ${session.shortId} originated on ${origin}; --host ${requestedHost} cannot move recovery to another device.`;
+}
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
  * (resume in the current process — no GUI/tmux available), or `'cancel'` (the

package/dist/commands/sessions.d.ts

@@ -131,7 +131,7 @@ export declare function formatActiveRowDescription(s: ActiveSession): string;
  */
 export declare function indexActiveBySessionId(active: ActiveSession[]): Map<string, ActiveSession>;
 /** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
-type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber'>;
+export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName'>;
 /**
  * Backfill display-only fields onto live rows from the indexed SessionMeta, by
  * full session id (RUSH-2205). A running process reports no agent version, and a
@@ -141,6 +141,8 @@ type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticke
  * the DB read that builds `metaById` is the caller's concern.
  */
 export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
+/** Add indexed display metadata to active rows for non-renderer consumers. */
+export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
 /**
  * The live decoration for a listing row: a status glyph and the latest-turn
  * preview, when the session is still running. `●` running / `◐` waiting on the
@@ -184,6 +186,16 @@ export declare function liveStatusWord(a: ActiveSession | undefined): string;
  * stays excluded rather than inventing a human who can answer.
  */
 export declare function isAwaitingUser(s: ActiveSession): boolean;
+/**
+ * Whether a row belongs in an unqualified `--active` view.
+ *
+ * The live registry deliberately retains terminally-dead rows long enough for
+ * `--closed` / `--crashed` and recovery to find them. Presence in that registry
+ * therefore is not, by itself, evidence that a session is still active.
+ * Explicit lifecycle filters bypass this predicate and select those retained
+ * rows through {@link matchesLiveStatus} instead.
+ */
+export declare function isRunningLiveSession(s: ActiveSession): boolean;
 /**
  * The tracker/PR ref for a session's dedicated column: the ticket id when known,
  * else `PR#<n>`, else empty. Pulled out of the trailing badge blob so refs align
@@ -573,6 +585,13 @@ export declare function handlePickedSession(picked: PickedSession): Promise<void
  * version-pinned launcher is genuinely missing.
  */
 export declare function resumeSessionInPlace(session: SessionMeta): Promise<void>;
+/**
+ * Relaunch this CLI's one recovery path. The owning device resolves account
+ * health and either performs exact-home native resume or same-harness
+ * `/continue`; callers never guess which version home can see the transcript.
+ * `portable` is for an SSH/terminal-engine command that executes on a peer.
+ */
+export declare function buildSessionRecoveryCommand(session: Pick<SessionMeta, 'id'>, portable?: boolean): string[];
 /**
  * Map a resume argv to the spawn(command, args, {shell}) triple.
  *
@@ -594,6 +613,9 @@ interface AgentFilter {
     agent?: SessionAgentId;
     version?: string;
 }
+/** Resolve the harness portion of a sessions selector with the CLI's canonical
+ * alias and single-typo rules. Kept pure so focus and the browser cannot drift. */
+export declare function resolveSessionAgentName(name: string): SessionAgentId | null;
 export declare function parseAgentFilter(agentName?: string): AgentFilter;
 /**
  * How a `sessions <query>` argument was resolved against the pool.

package/dist/commands/sessions.js

@@ -20,7 +20,7 @@ import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
 import ora from 'ora';
 import { SESSION_AGENTS } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
-import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, findExecutable, composeWin32CommandLine } from '../lib/platform/index.js';
+import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, composeWin32CommandLine } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
@@ -45,6 +45,8 @@ import { getShimsDir } from '../lib/state.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { resolveSessionAlias } from '../lib/session/actor-sidecar.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
+import { getAgentsInvocation } from '../lib/daemon.js';
+import { sessionRecoveryRunArgs } from '../lib/session/recovery.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker, buildPreview, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
@@ -409,6 +411,10 @@ export function backfillActiveRowsFromMeta(sessions, metaById) {
             if (!Number.isNaN(ts))
                 s.startedAtMs = ts;
         }
+        if (!s.origin && m.origin)
+            s.origin = m.origin;
+        if (!s.routineName && m.routineName)
+            s.routineName = m.routineName;
     }
 }
 /**
@@ -433,6 +439,10 @@ function loadBackfillMetaFor(sessions) {
     }
     return byId;
 }
+/** Add indexed display metadata to active rows for non-renderer consumers. */
+export function backfillActiveRowsFromIndex(sessions) {
+    backfillActiveRowsFromMeta(sessions, loadBackfillMetaFor(sessions));
+}
 /**
  * The live decoration for a listing row: a status glyph and the latest-turn
  * preview, when the session is still running. `●` running / `◐` waiting on the
@@ -525,6 +535,20 @@ export function isAwaitingUser(s) {
         return false;
     return s.status === 'input_required' || s.activity === 'waiting_input';
 }
+/**
+ * Whether a row belongs in an unqualified `--active` view.
+ *
+ * The live registry deliberately retains terminally-dead rows long enough for
+ * `--closed` / `--crashed` and recovery to find them. Presence in that registry
+ * therefore is not, by itself, evidence that a session is still active.
+ * Explicit lifecycle filters bypass this predicate and select those retained
+ * rows through {@link matchesLiveStatus} instead.
+ */
+export function isRunningLiveSession(s) {
+    if (s.status === 'closed' || s.status === 'crashed')
+        return false;
+    return s.pidAlive !== false;
+}
 /** Width of the live status column — `crashed` is the longest word it renders. */
 const LIVE_STATUS_W = 8;
 /** The colored, space-padded status cell for a listing row (empty when not live). */
@@ -1273,14 +1297,14 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     // gate: exit non-zero when the union contains a session awaiting the user.
     const statusFiltered = opts.statuses?.length
         ? merged.filter((session) => opts.statuses.some((status) => matchesLiveStatus(session, status)))
-        : merged;
+        : merged.filter(isRunningLiveSession);
     const sessions = statusFiltered;
     // Backfill agent version + ticket/PR/label/created onto the live rows from the
     // historical index (RUSH-2205) — a running process reports none of these, and
     // an orphan row usually lacks them. Done before both the JSON and human paths
     // so every consumer (incl. the SSH fan-out's remote --json) sees enriched rows;
     // transcripts sync across the fleet, so a remote row resolves from the local DB.
-    backfillActiveRowsFromMeta(sessions, loadBackfillMetaFor(sessions));
+    backfillActiveRowsFromIndex(sessions);
     if (asJson) {
         // Resolve who is watching each local tmux pane before serializing: `viewingIn`
         // is how a consumer distinguishes a session someone is looking at from one
@@ -3017,34 +3041,23 @@ export async function resumeSessionInPlace(session) {
     const cwd = session.cwd && fs.existsSync(session.cwd)
         ? session.cwd
         : process.cwd();
-    const resume = buildResumeCommand(session);
-    if (!resume) {
-        console.log(chalk.yellow(`Resume is not supported for ${session.agent} sessions yet. Showing summary instead.`));
-        await renderSession(session, 'summary', {});
-        return;
-    }
+    const resume = buildSessionRecoveryCommand(session);
     console.log(chalk.gray(`Resuming: ${resume.join(' ')} (cwd: ${cwd})`));
-    // Resolve the (possibly version-pinned) launcher up front. On Windows the
-    // agent shim is a `.cmd`/`.ps1` and, under the shell needed to run it (see
-    // spawnResumeCommand), a missing command exits non-zero rather than emitting
-    // an ENOENT `error` event — so detect a removed version here instead of
-    // relying on that event, keeping the fallback working on every OS.
-    // `resume[0]` is an absolute alias path when one exists on disk, so only a bare
-    // name still needs a PATH lookup. Checking existsSync first is what keeps an
-    // isolated install (shims deliberately off PATH) out of the fallback.
-    const launcherFound = path.isAbsolute(resume[0])
-        ? fs.existsSync(resume[0])
-        : !!findExecutable(resume[0]);
-    if (!launcherFound && session.version) {
-        const fallback = buildFallbackCommand(session);
-        if (fallback) {
-            console.log(chalk.gray(`Version ${session.version} is not installed. Resuming with the current version instead...`));
-            await spawnResumeCommand(fallback, cwd);
-            return;
-        }
-    }
     await spawnResumeCommand(resume, cwd);
 }
+/**
+ * Relaunch this CLI's one recovery path. The owning device resolves account
+ * health and either performs exact-home native resume or same-harness
+ * `/continue`; callers never guess which version home can see the transcript.
+ * `portable` is for an SSH/terminal-engine command that executes on a peer.
+ */
+export function buildSessionRecoveryCommand(session, portable = false) {
+    const args = sessionRecoveryRunArgs(session);
+    if (portable)
+        return ['agents', ...args];
+    const invocation = getAgentsInvocation(args);
+    return [invocation.command, ...invocation.args];
+}
 /**
  * Map a resume argv to the spawn(command, args, {shell}) triple.
  *
@@ -3112,8 +3125,6 @@ function spawnResumeCommand(cmd, cwd) {
  * isolated HOME where the JSONL was written — regardless of which version is
  * currently the default. Falls back to the bare shim when version is unknown.
  *
- * If the versioned binary is missing (version was removed), the ENOENT
- * handler in handlePickedSession retries via buildFallbackCommand.
  */
 /**
  * The agent's own resume invocation, given whichever launcher we resolved.
@@ -3180,19 +3191,6 @@ export function buildResumeCommand(session) {
             return null;
     }
 }
-/**
- * Fallback when the pinned version really is gone: the same resume invocation
- * against the current version.
- *
- * This used to spawn `<cli> "/continue <id>"`, feeding a slash command into the
- * TUI as a prompt. Neither CLI has `/continue` — codex documents `/resume` — so
- * the agent received an unrecognised command and the session was not resumed at
- * all. Reusing resumeArgv keeps the two paths from drifting apart again.
- */
-function buildFallbackCommand(session) {
-    const cli = AGENTS[session.agent]?.cliCommand ?? session.agent;
-    return resumeArgv(session.agent, session.id, cli);
-}
 // ---------------------------------------------------------------------------
 // Cloud session source (--cloud)
 // ---------------------------------------------------------------------------
@@ -3263,25 +3261,24 @@ async function runCloudSessions(query, options) {
     // Ensure the SessionMeta points at the local cache path for renderSession.
     await renderSession({ ...meta, filePath: cachedPath }, mode, filterOpts, options);
 }
+/** Resolve the harness portion of a sessions selector with the CLI's canonical
+ * alias and single-typo rules. Kept pure so focus and the browser cannot drift. */
+export function resolveSessionAgentName(name) {
+    const normalized = name.toLowerCase();
+    if (SESSION_AGENTS.includes(normalized)) {
+        return normalized;
+    }
+    const resolved = resolveAgentName(normalized);
+    if (resolved && SESSION_AGENTS.includes(resolved)) {
+        return resolved;
+    }
+    return fuzzyMatch(normalized, SESSION_AGENTS, FUZZY_PRESETS.agents);
+}
 export function parseAgentFilter(agentName) {
     if (!agentName)
         return {};
     const [name, version] = agentName.split('@', 2);
-    let agent = SESSION_AGENTS.includes(name)
-        ? name
-        : null;
-    if (!agent) {
-        // Aliases and single-typo corrections (cladue -> claude). SESSION_AGENTS
-        // includes ids (rush, hermes) that resolveAgentName doesn't know, so fall
-        // back to fuzzy-matching the session list directly.
-        const resolved = resolveAgentName(name);
-        if (resolved && SESSION_AGENTS.includes(resolved)) {
-            agent = resolved;
-        }
-        else {
-            agent = fuzzyMatch(name, SESSION_AGENTS, FUZZY_PRESETS.agents);
-        }
-    }
+    const agent = resolveSessionAgentName(name);
     if (!agent) {
         console.error(chalk.red(`Unknown agent: ${name}. Use: ${SESSION_AGENTS.join(', ')}`));
         process.exit(1);
@@ -3930,7 +3927,7 @@ export function registerSessionsCommands(program) {
         .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Widen every non-status filter to "all": every directory (not just this project) and all time (no window cap). Status filters like --active still compose; -a/--device/--since still narrow their axis.')
         .option('--unmanaged', "Also show sessions from your own ~/.<agent> installs (hidden once agents-cli manages that agent)")
-        .option('--teams', 'Include team-spawned sessions (hidden by default)')
+        .option('--team, --teams', 'Include team-spawned sessions (hidden by default)')
         .option('--in-team <name>', "Only this team: the session that spawned it plus (with --teams) its teammates. Spans every directory and all time, since a team's worktrees and history sit outside the default window.")
         .option('--routine', 'Show only sessions archived from routine runs')
         .option('-p, --project <name>', 'Filter by project name (searches across all directories)')
@@ -3997,7 +3994,7 @@ export function registerSessionsCommands(program) {
       agents sessions --crashed
 
       # --- Session lifecycle (one verb per intent) ---
-      # Jump to a live session (attach its terminal, or open a tab + resume)
+      # Focus a session (attach its living terminal, or recover an ended one)
       agents sessions focus a1b2c3d4
       # Attach only — never fork a copy (old: sessions go)
       agents sessions focus a1b2c3d4 --attach-only
@@ -4049,7 +4046,7 @@ export function registerSessionsCommands(program) {
     `,
         notes: `
       Session lifecycle (pick one verb — they are not synonyms):
-        focus [id]              jump to a live session (attach, or open tab + resume)
+        focus [selector]        attach a living pane, or recover on the origin device
         focus [id] --attach-only  attach only; never fork (replaces sessions go)
         detach <id>             interactive → headless continuation
         attach <id>             headless → interactive in this terminal

package/dist/commands/setup-secrets.js

@@ -66,7 +66,7 @@ function printBackendNotes(backend) {
         console.log(chalk.gray('backend: keychain — macOS reads may ask for Touch ID or the device password.'));
     }
     else if (backend === 'file') {
-        console.log(chalk.gray('backend: file — set AGENTS_SECRETS_PASSPHRASE for headless encrypted-file reads.'));
+        console.log(chalk.gray('backend: file — encrypted at rest; headless reads need no passphrase by default, via a machine-local key at ~/.agents/.secrets-key/passphrase.'));
     }
     else {
         console.log(chalk.gray('backend: vault — synced ~/.agents/vault.age storage; unlock it with agents login.'));

package/dist/commands/setup-watchdog.js

@@ -3,17 +3,12 @@ import { spawnSync } from 'node:child_process';
 import { getCliLaunch } from '../lib/cli-entry.js';
 import { loadDevices } from '../lib/devices/registry.js';
 import { machineId, normalizeHost } from '../lib/machine-id.js';
-import { devicesWithRoutineEnabled } from '../lib/routine-activation.js';
-import { readJob, setJobEnabled } from '../lib/routines.js';
+import { getConfigValue, setConfigValue } from '../lib/device-config.js';
 import { isPromptCancelled, requireInteractiveSelection } from './utils.js';
-const ROUTINE = 'watchdog';
 export async function runWatchdogSetupWizard() {
-    if (!readJob(ROUTINE)) {
-        throw new Error("Built-in routine 'watchdog' is missing. Run: agents repo pull system");
-    }
     const registry = await loadDevices();
     const devices = [...new Set([...Object.keys(registry), machineId()].map(normalizeHost))].sort();
-    const enabled = new Set(devicesWithRoutineEnabled(ROUTINE).map(normalizeHost));
+    const enabled = new Set(devices.filter((device) => getConfigValue('watchdog.enabled', { device }).value === true));
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         requireInteractiveSelection('watchdog devices', ['agents watchdog on', 'agents watchdog on --host <device>']);
     }
@@ -27,10 +22,10 @@ export async function runWatchdogSetupWizard() {
         for (const device of devices) {
             const on = selectedSet.has(device);
             if (device === normalizeHost(machineId())) {
-                setJobEnabled(ROUTINE, on);
+                setConfigValue('watchdog.enabled', on);
                 continue;
             }
-            const launch = getCliLaunch(['routines', on ? 'resume' : 'pause', ROUTINE, '--host', device]);
+            const launch = getCliLaunch(['watchdog', on ? 'on' : 'off', '--host', device]);
             const result = spawnSync(launch.command, launch.args, { stdio: 'inherit', env: process.env });
             if ((result.status ?? 1) !== 0)
                 throw new Error(`Could not configure watchdog on ${device}`);
@@ -49,6 +44,6 @@ export async function runWatchdogSetupWizard() {
 }
 export function registerSetupWatchdogCommand(setup) {
     setup.command('watchdog')
-        .description('Choose the devices where the built-in watchdog routine runs.')
+        .description('Choose the devices where the daemon watchdog pass runs.')
         .action(runWatchdogSetupWizard);
 }

package/dist/commands/setup.js

@@ -319,7 +319,7 @@ export function registerSetupCommand(program) {
         agents setup share       # provision or join a Cloudflare share endpoint
         agents setup secrets     # choose secrets backend/policy defaults + import
         agents setup fleet       # discover Tailscale devices + configure SSH access
-        agents setup watchdog    # choose which devices run the watchdog routine
+        agents setup watchdog    # choose which devices run the daemon watchdog pass
 
       To install CLIs from agents.yaml and sync resources into version homes:
         agents sync --local -y