@phnx-labs/agents-cli 1.22.25 → 1.22.27

package/dist/commands/reconnect.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `agents reconnect [session-id]` — get me back into an agent terminal whose ssh
+ * link dropped.
+ *
+ * The auto-reconnect in lib/hosts/reconnect.ts already re-attaches a live remote
+ * pane over its own bounded backoff on a transient blink. This is the MANUAL
+ * recovery for after it gave up — a sustained outage, or a VS Code terminal tab
+ * that closed with the dead ssh client. One verb that always tries hardest to put
+ * you back into that agent: attach the live pane if it still exists, else resume
+ * the session; live pane > resumed copy > a clear message about what was lost.
+ *
+ * It delegates to `focus`, which already does exactly attach-else-resume for a
+ * resolved id ({@link focusAction} → `focusResolvedSession`), so there is no second
+ * recovery path to keep in sync. What `reconnect` adds is the recovery framing and,
+ * with no id, targeting the MOST RECENT session in this shell's directory — the one
+ * that most likely just dropped — instead of opening the full fleet picker.
+ */
+import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
+/**
+ * The recency signal a no-id reconnect targets: last activity if the scan
+ * computed one, else the creation time. A row with neither parseable sorts last.
+ * Pure so target selection is unit-tested without the scanner.
+ */
+export declare function sessionRecency(s: Pick<SessionMeta, 'lastActivity' | 'timestamp'>): number;
+/**
+ * Pick the session to reconnect when the user gave no id: the most recently
+ * active one in scope — the terminal that most likely just dropped. Pure; returns
+ * undefined for an empty scope so the caller can print guidance.
+ */
+export declare function pickMostRecentSession(sessions: SessionMeta[]): SessionMeta | undefined;
+/**
+ * Resolve the no-id target: prefer the most recent session started from THIS
+ * directory (the shell the user is reconnecting from), falling back to the most
+ * recent session anywhere when the current directory has none. Best-effort — a
+ * discovery failure yields undefined, never throws. Injectable `discover` keeps
+ * the two-step scope preference testable without touching the real scanner.
+ */
+export declare function resolveRecentTarget(cwd: string, discover?: (opts: {
+    cwd?: string;
+    all?: boolean;
+    since?: string;
+    limit?: number;
+}) => Promise<SessionMeta[]>): Promise<SessionMeta | undefined>;
+export declare function reconnectAction(id: string | undefined): Promise<void>;
+export declare function registerReconnectCommand(program: Command): void;

package/dist/commands/reconnect.js

@@ -0,0 +1,109 @@
+/**
+ * `agents reconnect [session-id]` — get me back into an agent terminal whose ssh
+ * link dropped.
+ *
+ * The auto-reconnect in lib/hosts/reconnect.ts already re-attaches a live remote
+ * pane over its own bounded backoff on a transient blink. This is the MANUAL
+ * recovery for after it gave up — a sustained outage, or a VS Code terminal tab
+ * that closed with the dead ssh client. One verb that always tries hardest to put
+ * you back into that agent: attach the live pane if it still exists, else resume
+ * the session; live pane > resumed copy > a clear message about what was lost.
+ *
+ * It delegates to `focus`, which already does exactly attach-else-resume for a
+ * resolved id ({@link focusAction} → `focusResolvedSession`), so there is no second
+ * recovery path to keep in sync. What `reconnect` adds is the recovery framing and,
+ * with no id, targeting the MOST RECENT session in this shell's directory — the one
+ * that most likely just dropped — instead of opening the full fleet picker.
+ */
+import chalk from 'chalk';
+import { focusAction } from './focus.js';
+import { discoverSessions } from '../lib/session/discover.js';
+import { setHelpSections } from '../lib/help.js';
+/**
+ * The recency signal a no-id reconnect targets: last activity if the scan
+ * computed one, else the creation time. A row with neither parseable sorts last.
+ * Pure so target selection is unit-tested without the scanner.
+ */
+export function sessionRecency(s) {
+    const t = Date.parse(s.lastActivity ?? s.timestamp ?? '');
+    return Number.isFinite(t) ? t : Number.NEGATIVE_INFINITY;
+}
+/**
+ * Pick the session to reconnect when the user gave no id: the most recently
+ * active one in scope — the terminal that most likely just dropped. Pure; returns
+ * undefined for an empty scope so the caller can print guidance.
+ */
+export function pickMostRecentSession(sessions) {
+    let best;
+    for (const s of sessions) {
+        if (!best || sessionRecency(s) > sessionRecency(best))
+            best = s;
+    }
+    return best;
+}
+/**
+ * Resolve the no-id target: prefer the most recent session started from THIS
+ * directory (the shell the user is reconnecting from), falling back to the most
+ * recent session anywhere when the current directory has none. Best-effort — a
+ * discovery failure yields undefined, never throws. Injectable `discover` keeps
+ * the two-step scope preference testable without touching the real scanner.
+ */
+export async function resolveRecentTarget(cwd, discover = discoverSessions) {
+    try {
+        const here = await discover({ cwd, since: '7d', limit: 200 });
+        const local = pickMostRecentSession(here);
+        if (local)
+            return local;
+        const any = await discover({ all: true, since: '7d', limit: 200 });
+        return pickMostRecentSession(any);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function reconnectAction(id) {
+    if (id) {
+        // focus already attaches a live pane or recovers a dropped one for a resolved
+        // id — on the origin device for a remote session. Reconnect is that path with
+        // a recovery-first name; no reason to duplicate the resolution/attach logic.
+        await focusAction(id, {});
+        return;
+    }
+    const recent = await resolveRecentTarget(process.cwd());
+    if (!recent) {
+        console.log(chalk.gray('No recent session to reconnect from here.'));
+        console.log(chalk.gray('  reconnect a specific one:  agents reconnect <session-id>'));
+        console.log(chalk.gray('  or pick from the fleet:    agents sessions'));
+        return;
+    }
+    const where = recent.machine ? ` on ${recent.machine}` : '';
+    console.log(chalk.gray(`Reconnecting ${recent.shortId}${where} (most recent here)…`));
+    await focusAction(recent.id, {});
+}
+export function registerReconnectCommand(program) {
+    const cmd = program
+        .command('reconnect')
+        .argument('[session-id]', 'Session id/prefix to reconnect (default: the most recent session started here)')
+        .description('Re-enter a dropped agent terminal: attach the live pane if it survived, else resume the session')
+        .action(async (id) => {
+        await reconnectAction(id);
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # Reconnect the session that just dropped in this shell (most recent here)
+      agents reconnect
+
+      # Reconnect one specific agent terminal by id/prefix
+      agents reconnect 74b13b0b
+
+      # Same, spelled under the sessions group
+      agents sessions reconnect 74b13b0b
+    `,
+        notes: `
+      - Best-effort recovery: a living remote tmux pane is JOINED (a second client, no fork); a dropped one is RESUMED on its origin device (a copy if it was mid-run, a /continue if idle).
+      - With no id, targets the most recent session started from this directory (the terminal that most likely just dropped), not the full fleet picker. Falls back to the most recent session anywhere when this directory has none.
+      - This is the manual companion to the automatic reconnect that runs during a live 'agents run --device <box>' when the network blinks; use it after that gave up or the terminal tab closed.
+      - Related: 'agents sessions focus' (attach/recover with a picker) and 'agents sessions resume' (multi-select history -> tabs).
+    `,
+    });
+}

package/dist/commands/resume.d.ts

@@ -5,7 +5,18 @@ interface ResumeOptions {
     headless?: boolean;
     cwd?: string;
     quiet?: boolean;
+    /** Run on THIS machine even when the session belongs to a peer (escape hatch). */
+    here?: boolean;
 }
+/**
+ * The argv to re-run this resume on the machine that owns the session.
+ *
+ * Deliberately carries no "don't route again" FLAG — that rides the
+ * {@link RESUME_PINNED_ENV} export instead, so the hop also works against a peer
+ * on an older CLI (see the constant's docs). Every argv token here exists in the
+ * released surface.
+ */
+export declare function buildResumeRemoteArgs(sessionId: string, prompt: string | undefined, options: ResumeOptions): string[];
 /** Translate `agents resume <id>` to the canonical `agents run` surface after
  * resolving the source identity. The run command remains the only executor. */
 export declare function buildResumeRunArgs(session: {

package/dist/commands/resume.js

@@ -3,6 +3,29 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { resolveSessionMetadataValue } from './sessions.js';
+import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../lib/session/resume-owner.js';
+/**
+ * The argv to re-run this resume on the machine that owns the session.
+ *
+ * Deliberately carries no "don't route again" FLAG — that rides the
+ * {@link RESUME_PINNED_ENV} export instead, so the hop also works against a peer
+ * on an older CLI (see the constant's docs). Every argv token here exists in the
+ * released surface.
+ */
+export function buildResumeRemoteArgs(sessionId, prompt, options) {
+    const args = ['resume', sessionId, ...(prompt === undefined ? [] : [prompt])];
+    if (options.mode)
+        args.push('--mode', options.mode);
+    if (options.interactive)
+        args.push('--interactive');
+    if (options.headless)
+        args.push('--headless');
+    if (options.cwd)
+        args.push('--cwd', options.cwd);
+    if (options.quiet)
+        args.push('--quiet');
+    return args;
+}
 /** Translate `agents 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) {
@@ -29,7 +52,11 @@ export function registerResumeCommand(program) {
         .option('--headless', 'Resume headlessly (a prompt is required)')
         .option('--cwd <path>', 'Override the recorded working directory')
         .option('-q, --quiet', 'Suppress routing banners')
+        .option('--here', 'Run on this machine even if the session belongs to another device')
         .action(async (sessionId, prompt, options) => {
+        // Read (and clear) the routing pin before anything else, so it can never
+        // reach the agent's own children.
+        const pinnedHere = consumeResumePinned() || !!options.here;
         const outcome = await resolveSessionMetadataValue(sessionId.trim());
         if (outcome.kind === 'partial') {
             console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
@@ -46,6 +73,29 @@ export function registerResumeCommand(program) {
             process.exitCode = 1;
             return;
         }
+        // The harness keeps its conversation state on the machine that produced
+        // the session, so a peer-owned session MUST resume there. Running it here
+        // starts the agent against state this box does not have — silently, since
+        // a synced mirror makes the transcript look local (RUSH-2022).
+        const owner = pinnedHere ? undefined : sessionOwnerDevice(outcome.session);
+        if (owner) {
+            if (!options.quiet) {
+                process.stderr.write(chalk.gray(`[agents] session ${outcome.session.shortId} belongs to ${owner} → resuming there\n`));
+            }
+            // `runOnPeer` is the existing transport for "this session's transcript
+            // and agent binary are on that box" (lib/session/remote-list.ts) — the
+            // same one the picker already uses. Not the `--host` passthrough: that
+            // one re-discovers locally and marks the run AGENTS_FLEET_REMOTE, which
+            // a long-lived resumed session must not inherit.
+            const { runOnPeer } = await import('../lib/session/remote-list.js');
+            const rc = await runOnPeer(buildResumeRemoteArgs(outcome.session.id, prompt, options), owner, { tty: !!process.stdout.isTTY, env: { [RESUME_PINNED_ENV]: '1' } });
+            if (rc === 'no-target') {
+                console.error(chalk.red(`Session ${outcome.session.shortId} lives on ${owner}, which isn't a reachable device right now.`));
+                console.error(chalk.gray(`Register/wake it (agents devices), or run there: agents ssh ${owner}`));
+                process.exitCode = 1;
+            }
+            return;
+        }
         const args = buildResumeRunArgs(outcome.session, prompt, options);
         const child = spawn(process.execPath, [process.argv[1], ...args], {
             stdio: 'inherit',
@@ -82,6 +132,7 @@ export function registerResumeCommand(program) {
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
         notes: `
       A full ID resolves from the local session database first (zero SSH) and, on a local miss, fans out with the first peer holding it cancelling the rest. An exact label always consults the fleet (labels are not globally unique) and auto-resumes the one match; a cross-machine label collision surfaces as an ambiguity.
+      A session that ran on another device resumes ON that device over SSH — the harness's conversation state lives there, so running it here would start against state this machine does not have. --here overrides that and runs locally.
       Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
     });
 }

package/dist/commands/routines.js

@@ -12,7 +12,7 @@ import * as path from 'path';
 import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonLog, getDaemonStatus, } from '../lib/daemon.js';
 import { assertSchedulerEnabled } from '../lib/device-config.js';
-import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
+import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError, ROUTINE_AGENT_IDS } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, computeProjectGroup, computeProjectGroupKind, projectGroupKey, projectGroupTitle, projectGroupOrder, normalizeProjects, } from '../lib/routines.js';
 import { listProjectDefs, isSafeProjectName } from '../lib/projects.js';
@@ -21,7 +21,7 @@ import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js'
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
-import { executeJob, monitorRunningJobs, ROUTINE_AGENT_IDS } from '../lib/runner.js';
+import { executeJob, monitorRunningJobs } from '../lib/runner.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { runCatchup } from '../lib/catchup.js';

package/dist/commands/secrets.d.ts

@@ -8,6 +8,8 @@
 import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg } from '../lib/platform/index.js';
+import { bundleEnvToDotenv } from '../lib/secrets/push.js';
+export { bundleEnvToDotenv };
 import { type SecretsBackend, type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 import { type SecretsListFilterOpts } from '../lib/secrets/list-filter.js';
 import { type BundleUsageSummary } from '../lib/secrets/usage-db.js';
@@ -78,14 +80,6 @@ export { SSH_TARGET_RE, assertValidSshTarget };
  * the executed command.
  */
 export declare function buildSecretsExecEnv(parentEnv: NodeJS.ProcessEnv, secretEnv: Record<string, string>): NodeJS.ProcessEnv;
-/**
- * Serialize a resolved env map to `.env` lines that round-trip losslessly through
- * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
- * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
- * value survives unchanged with no escaping. Newlines would break its line-based
- * parse, so multi-line values are rejected rather than silently corrupted.
- */
-export declare function bundleEnvToDotenv(env: Record<string, string>): string;
 /**
  * Encrypt a resolved env map to an offline bundle file using AES-256-GCM
  * (the same EncFile envelope as the per-item file store). Inner plaintext is

package/dist/commands/secrets.js

@@ -12,12 +12,12 @@ import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/widt
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
+import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
 import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
-import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, verifyRemoteKeychainPush, keychainWriteFailureMessage, buildRemoteFileImportCommand, } from '../lib/secrets/remote.js';
-import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
-import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
+import { resolveBundleForPush, pushResolvedBundleToHost, bundleEnvToDotenv } from '../lib/secrets/push.js';
+export { bundleEnvToDotenv };
 import { bundleBackend, bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, healKeychainBundleMetadataAclOnce, isHeadlessSecretsContext, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, readBundleIfDecryptable, reAclBundleItems, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, SECRET_TYPES, } from '../lib/secrets/bundles.js';
 import { parseListFilters, bundleMatchesFilter, bundleExpiry, filterIsActive, describeFilter, parseSortField, sortBundles, SORT_FIELDS, REF_KINDS, DEFAULT_EXPIRING_DAYS, } from '../lib/secrets/list-filter.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
@@ -354,24 +354,6 @@ function getCliVersion() {
         return '0.0.0';
     }
 }
-/**
- * Serialize a resolved env map to `.env` lines that round-trip losslessly through
- * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
- * quote pair and takes the inner bytes verbatim (no unescaping), so any single-line
- * value survives unchanged with no escaping. Newlines would break its line-based
- * parse, so multi-line values are rejected rather than silently corrupted.
- */
-export function bundleEnvToDotenv(env) {
-    const lines = [];
-    for (const [k, v] of Object.entries(env)) {
-        if (/[\r\n]/.test(v)) {
-            throw new Error(`Key '${k}' has a multi-line value; the SSH .env transport can't carry newlines. ` +
-                `Set it directly on the remote with 'agents secrets add ${k} --value-stdin'.`);
-        }
-        lines.push(`${k}="${v}"`);
-    }
-    return lines.join('\n') + '\n';
-}
 /**
  * Encrypt a resolved env map to an offline bundle file using AES-256-GCM
  * (the same EncFile envelope as the per-item file store). Inner plaintext is
@@ -2115,100 +2097,42 @@ Examples:
             if (hosts.length > 0) {
                 for (const h of hosts)
                     assertValidSshTarget(h);
-                const remoteBackend = parseBackendOpt(opts.remoteBackend);
+                const parsedBackend = parseBackendOpt(opts.remoteBackend);
+                // `--remote-backend` documents keychain|file only, and parseBackendOpt
+                // exits on anything else — but its return type still admits 'vault',
+                // which has no remote-push path. Refuse it here rather than let it fall
+                // through to the keychain branch and half-work.
+                if (parsedBackend === 'vault') {
+                    console.error(chalk.red("--remote-backend vault is not supported; use 'keychain' or 'file'."));
+                    process.exit(1);
+                }
+                const remoteBackend = parsedBackend;
                 // For a file-backed remote bundle a passphrase is OPTIONAL. The file
                 // store is passphrase-free by default: with AGENTS_SECRETS_PASSPHRASE
                 // unset the remote `import --backend file` auto-provisions the remote's
                 // own machine-local key (0600 under ~/.agents/.secrets-key/), so reads
                 // are HEADLESS. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE only when
-                // the operator opts in by setting it (e.g. to key the bundle off-disk
-                // under a shared secret) — shipped as the FIRST stdin line so it never
-                // lands in argv / `ps` / the remote shell history. Forcing a shared
-                // passphrase would defeat headless reads, so we no longer require one.
+                // the operator opts in by setting it. Forcing a shared passphrase would
+                // defeat headless reads, so we no longer require one.
                 const remotePassphrase = remoteBackend === 'file' ? (process.env.AGENTS_SECRETS_PASSPHRASE ?? '') : '';
-                const { env } = readAndResolveBundleEnv(resolvedBundleName, { caller: `ssh export`, keyMode: 'storage', agentOnly: true });
-                const dotenv = bundleEnvToDotenv(env);
-                const keyCount = Object.keys(env).length;
-                // Drive the remote's own `agents secrets import --from -` so the values
-                // land in its chosen backend, reading the .env off ssh stdin (never
-                // parsed by a remote shell — `--from -` replaces the POSIX-only
-                // `/dev/stdin`). The keychain path is built OS-aware via
-                // `remoteSecretsRaw` (bash -lc on POSIX, PowerShell on Windows), so it
-                // works on macOS, Linux AND Windows targets. `import` auto-creates the
-                // bundle, so no separate `create` (the old `|| true` was a POSIXism
-                // that broke on PowerShell: `'true' is not recognized`).
+                // Resolve ONCE for N hosts — reading a bundle can prompt, and doing it
+                // per host would prompt per host.
+                const resolvedForPush = resolveBundleForPush(resolvedBundleName, 'ssh export');
+                const keyCount = resolvedForPush.keyCount;
                 let failures = 0;
                 for (const host of hosts) {
-                    let res;
-                    if (remoteBackend === 'file') {
-                        // File backend: headless-readable via the remote's machine-local key
-                        // when no passphrase is set; otherwise forwards AGENTS_SECRETS_PASSPHRASE
-                        // as the FIRST stdin line (consumed by `read`, so it never lands in
-                        // argv / `ps` / remote history), then the .env. Both build a POSIX
-                        // `bash -lc` command — refuse a Windows target cleanly rather than
-                        // emit broken PowerShell.
-                        if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
-                            failures++;
-                            console.error(chalk.red(`${host}: file backend export to a Windows target is not yet supported.`));
-                            continue;
-                        }
-                        const { remoteCmd, input } = buildRemoteFileImportCommand(resolvedBundleName, dotenv, {
-                            passphrase: remotePassphrase,
-                            force: opts.force,
-                        });
-                        res = sshExec(host, remoteCmd, { input });
-                    }
-                    else if (remoteShellFor(resolveRemoteOsSync(host.split('@').pop() ?? host)) === 'powershell') {
-                        // Keychain on a Windows target: the `agents.ps1` shim doesn't
-                        // forward ssh-piped stdin to node, so `--from -` would hang.
-                        // Bridge the piped .env through PowerShell into a temp file and
-                        // import `--from <file>` (deleted afterwards). Same hardened ssh
-                        // engine, .env still only ever crosses the wire over ssh stdin.
-                        res = sshExec(host, buildWindowsStdinImportCommand(resolvedBundleName, { force: opts.force }), { input: dotenv });
-                    }
-                    else {
-                        // Keychain on a POSIX target: OS-aware wrapping + hardened ssh
-                        // engine (BatchMode, ConnectTimeout, keepalive, control-socket
-                        // reuse) via the same path the READ inverse (`remoteResolveEnv`)
-                        // uses. `--from -` reads the .env off ssh stdin.
-                        res = remoteSecretsRaw(host, ['import', resolvedBundleName, '--from', '-', ...(opts.force ? ['--force'] : [])], { input: dotenv, osLookupName: host });
-                    }
-                    if (res.code === null) {
-                        failures++;
-                        console.error(chalk.red(`${host}: ${res.stderr.trim() || (res.timedOut ? 'ssh timed out' : 'ssh failed')}`));
-                        continue;
-                    }
-                    if (res.code !== 0) {
+                    const out = pushResolvedBundleToHost(resolvedForPush, resolvedBundleName, host, {
+                        remoteBackend,
+                        force: opts.force,
+                        passphrase: remotePassphrase,
+                        operation: 'ssh export',
+                    });
+                    if (!out.ok) {
                         failures++;
-                        const msg = (res.stderr || res.stdout || '').trim();
-                        console.error(chalk.red(`${host}: remote import failed (exit ${res.code})${msg ? `: ${msg}` : ''}`));
+                        console.error(chalk.red(`${host}: ${out.message}`));
                         continue;
                     }
-                    // A keychain-backed push to a macOS remote over headless SSH can land
-                    // the bundle metadata but no READABLE value items: the remote login
-                    // keychain is locked in the non-interactive SSH context, so Security
-                    // accepts the write but the biometry-ACL'd item is unreadable, and the
-                    // remote `import` still exits 0. Read the bundle back the same way a
-                    // release will (drops the plaintext, keeps only key presence; the
-                    // remote's headless `agentOnly` guard fails fast, so no Touch ID) and
-                    // FAIL LOUDLY if the keys didn't materialize — rather than leave a
-                    // metadata-only bundle that breaks later with "stored item not found".
-                    // The file backend is headless-readable by construction, so skip it.
-                    if (remoteBackend === 'keychain') {
-                        const verdict = verifyRemoteKeychainPush(host, resolvedBundleName, Object.keys(env), { osLookupName: host });
-                        if (!verdict.ok) {
-                            failures++;
-                            if (verdict.kind === 'locked-keychain') {
-                                console.error(chalk.red(keychainWriteFailureMessage(host, resolvedBundleName, verdict.reason)));
-                            }
-                            else {
-                                console.error(chalk.red(`${host}: pushed '${resolvedBundleName}' but could not verify it on the remote: ${verdict.reason}`));
-                            }
-                            continue;
-                        }
-                    }
-                    const remoteMsg = (res.stdout || '').trim().split('\n').map((l) => l.trim()).filter(Boolean).pop();
-                    console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${remoteMsg || `${keyCount} key(s) exported`}`));
+                    console.log(chalk.green(`${host} -> '${resolvedBundleName}': ${out.message}`));
                 }
                 emitSecretAudit({ event: 'secrets.export', bundle: resolvedBundleName, operation: `export --host ${hosts.join(',')}`, source: 'ssh', host: hosts.join(','), status: failures > 0 ? 'error' : 'success', keyCount });
                 if (failures > 0)

package/dist/commands/sessions-picker.js

@@ -19,12 +19,17 @@ import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
-/** A session whose transcript lives on another machine (folded in over the live
- * cross-machine fan-out): its `filePath` is on that peer's disk, so the preview
- * can't parse it locally — it shows metadata + a "resume there" note instead.
- * Keys off `_remote`, not the machine tag, so locally-readable synced mirrors
- * still parse their file normally. */
-function remoteMachineOf(session) {
+/** A session whose transcript FILE is on another machine (folded in over the
+ * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
+ * preview can't parse it locally — it shows metadata + a "resume there" note
+ * instead. Keys off `_remote`, not the machine tag, so locally-readable synced
+ * mirrors still parse their file normally.
+ *
+ * This is the READ rule and only the read rule. Whether a session may be
+ * RESUMED here is a different question with a different answer — a mirror is
+ * readable but not resumable — and `sessionOwnerDevice`
+ * (lib/session/resume-owner.ts) is the single place that answers it (RUSH-2022). */
+function transcriptOnPeerOf(session) {
     return session._remote ? session.machine : undefined;
 }
 /**
@@ -98,7 +103,7 @@ function sanitizeMeta(s) {
 const previewCache = new Map();
 /** Build a cached multi-line preview string for display in the session picker. */
 export function buildPreview(session) {
-    const remote = remoteMachineOf(session);
+    const remote = transcriptOnPeerOf(session);
     const cacheKey = remote ? `${remote}:${session.id}` : session.id;
     const cached = previewCache.get(cacheKey);
     if (cached)

package/dist/commands/sessions.d.ts

@@ -11,7 +11,7 @@ interface SessionFilterOptions {
     all?: boolean;
     teams?: boolean;
     inTeam?: string;
-    routine?: boolean;
+    routine?: boolean | string;
     since?: string;
     until?: string;
 }
@@ -389,6 +389,22 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/** Resolve a typed routine selector by exact name, substring, or one unambiguous typo. */
+export declare function resolveRoutineName(query: string, names: readonly string[]): string | null;
+export interface RoutineRunGroup {
+    runId: string;
+    timestamp: string;
+    sessions: SessionMeta[];
+}
+export interface RoutineChoice {
+    name: string;
+    lastRunAt: string;
+    runCount: number;
+    latestRunSessionCount: number;
+}
+export declare function buildRoutineRunGroups(sessions: SessionMeta[]): RoutineRunGroup[];
+export declare function buildRoutineChoices(sessions: SessionMeta[]): RoutineChoice[];
+export declare function filterSessionsByRoutine(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<SessionMeta[] | null>;
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
 export declare function renderSessionPreview(query: string, scope: {
@@ -478,6 +494,10 @@ export declare function buildOverviewGroups(pool: SessionMeta[], perProjectCap:
     groups: OverviewGroup[];
     projectCount: number;
 };
+export declare function printRoutineRunOverview(sessions: SessionMeta[], liveIndex: Map<string, ActiveSession> | undefined, opts?: {
+    hiddenCount?: number;
+    hiddenUnmanaged?: number;
+}): void;
 /**
  * Render a resolved session to stdout — the non-follow view behind
  * `agents logs <sessionId>`. Defaults to the concise `summary` digest (same as
@@ -577,6 +597,16 @@ export declare function pickSessionInteractive(sessions: SessionMeta[], message?
 export declare const LIVE_ROW_PREFIX = "live:";
 export declare function isIdlessLiveRow(s: SessionMeta): boolean;
 export declare function handlePickedSession(picked: PickedSession): Promise<void>;
+/**
+ * Resume `session` on the machine that owns it, when that is not this one.
+ * Returns true when it handled the resume (hopped, or reported an unreachable
+ * owner), false when the session is local and the caller should take over here.
+ *
+ * The one hop for a foreground, one-session-at-a-time resume — shared by the
+ * `agents sessions` picker and by `sessions resume`'s no-tab-backend path, which
+ * would otherwise reach `resumeSessionInPlace` and be refused (RUSH-2022).
+ */
+export declare function resumeOnOwnerIfRemote(session: SessionMeta): Promise<boolean>;
 /**
  * Resume a session in the current terminal — a foreground takeover of this
  * process. Used by the single-select picker and by `sessions resume` when the
@@ -647,6 +677,22 @@ export declare function resolveSessionQuery(pool: SessionMeta[], query: string,
 export declare function fleetNotFoundMessage(query: string, deviceCount: number, unreachable: string[]): string[];
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
+/**
+ * Narrow a session list by --project and --agent before search resolution.
+ * Without this, a query like "scoped search" could match sessions in BOTH
+ * the project you specified AND elsewhere, producing an ambiguity error
+ * even though the user already pointed at the correct scope.
+ */
+export declare function applyScopeFilters(sessions: SessionMeta[], scope: {
+    agent?: string;
+    project?: string;
+    routine?: boolean | string;
+}): SessionMeta[];
+export declare function artifactLookupScope(agent?: string, project?: string, routine?: boolean | string): {
+    agent?: string;
+    project?: string;
+    routine?: boolean | string;
+};
 /**
  * Whether a missed local id lookup should widen to a cross-machine sweep.
  *