@phnx-labs/agents-cli 1.22.22 → 1.22.23

package/dist/commands/harness.js

@@ -13,10 +13,10 @@
 import chalk from 'chalk';
 import { addProfile, ensureProviderToken, applyFromSecrets } from './profiles.js';
 import { isInteractiveTerminal } from './utils.js';
-import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, editProfile, renameProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, editProfile, renameProfile, profileFromHostModel, authEnvKeyForHost, modelEnvKeyForHost, baseUrlEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
 import { listPresets, getPreset } from '../lib/profiles-presets.js';
-import { listBundles } from '../lib/secrets/bundles.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
+import { runWizardSteps, createSteps, editSteps, defaultWizardIO, } from './harness-wizard.js';
 /** Short capability summary for a native harness — its supported run modes. */
 function nativeModes(id) {
     const modes = AGENTS[id]?.capabilities?.modes ?? [];
@@ -193,108 +193,93 @@ async function runForkFlow(source, name, opts) {
     console.log(chalk.green(`Harness '${name}' forked from ${source}.`));
     console.log(chalk.gray(`Try: agents run ${name} "hello"`));
 }
-/** The first `_MODEL`-suffixed env var in a preset's static env block, if any. */
-function presetModel(preset) {
-    return Object.entries(preset.env).find(([k]) => k.endsWith('_MODEL'))?.[1];
-}
 /**
  * Interactive `agents harness add`/`fork` wizard — runs when required info is
- * missing and stdout is a TTY (see {@link forkNeedsWizard}, {@link addNeedsWizard}).
- * Always resolves to the same `(source, name, opts)` shape {@link buildFork}
- * accepts via {@link runForkFlow}, so a wizard run and a hand-written fork call
- * build an identical profile.
+ * missing and stdin+stdout are a TTY (see {@link forkNeedsWizard}, {@link addNeedsWizard}).
+ * Drives the shared step engine ({@link createSteps}) and maps its finished draft
+ * back to the same `(source, name, opts)` shape {@link buildFork} accepts via
+ * {@link runForkFlow}, so a wizard run and a hand-written fork call build an
+ * identical profile.
  */
-async function runHarnessWizard() {
-    const { select, input } = await import('@inquirer/prompts');
-    const customNames = listProfiles().map((p) => p.name);
-    const source = await select({
-        message: 'Fork from',
-        choices: [
-            ...ALL_AGENT_IDS.map((id) => ({ name: `${AGENTS[id].name}  ${chalk.gray('(native)')}`, value: id })),
-            ...customNames.map((n) => ({ name: `${n}  ${chalk.gray('(custom harness)')}`, value: n })),
-        ],
-    });
-    const presets = listPresets();
-    const CUSTOM = '__custom__';
-    const presetChoice = await select({
-        message: 'Preset',
-        choices: [
-            ...presets.map((p) => ({ name: `${p.name}  ${chalk.gray(p.description.slice(0, 60))}`, value: p.name })),
-            { name: 'Build custom (host + model + provider)', value: CUSTOM },
-        ],
-    });
-    let model;
-    let baseUrl;
-    let authProvider;
-    let defaultName = source;
-    if (presetChoice === CUSTOM) {
-        model = await input({ message: 'Model id' });
-        const NO_AUTH = '__none__';
-        const providers = [...new Set(presets.map((p) => p.provider))];
-        const providerChoice = await select({
-            message: 'Provider',
-            choices: [
-                ...providers.map((p) => ({ name: p, value: p })),
-                { name: 'no auth / host manages its own login', value: NO_AUTH },
-            ],
-        });
-        authProvider = providerChoice === NO_AUTH ? undefined : providerChoice;
-        const baseUrlInput = await input({ message: 'Base URL (optional)', default: '' });
-        baseUrl = baseUrlInput || undefined;
+async function runCreateWizard() {
+    const io = await defaultWizardIO();
+    const draft = await runWizardSteps(createSteps(), { mode: 'create' }, io);
+    return {
+        source: draft.source,
+        name: draft.name,
+        opts: {
+            model: draft.model,
+            baseUrl: draft.baseUrl,
+            authProvider: draft.authProvider,
+            fromSecrets: draft.fromSecrets,
+        },
+    };
+}
+/**
+ * Map a finished edit-wizard draft onto {@link EditOptions}, keeping only the
+ * fields the user actually changed from the profile's current values. Unchanged
+ * accepts (the wizard pre-fills each prompt with the current value) drop out, so
+ * the resulting {@link buildEdit} touches nothing the user left alone — and the
+ * "no changes" case is detectable via {@link hasEditFlags}. Base-URL clearing is
+ * intentionally not expressed here: the flag path can't clear it either (an empty
+ * `--base-url` is a no-op in `forkProfile`), so the wizard matches that until a
+ * later subtask adds explicit clearing.
+ */
+export function draftToEditOptions(draft, original) {
+    const host = original.host.agent;
+    const curModel = original.env[modelEnvKeyForHost(host)];
+    const baseKey = baseUrlEnvKeyForHost(host);
+    const curBaseUrl = baseKey ? original.env[baseKey] : undefined;
+    const curVersion = original.host.version ?? '';
+    const curFallback = original.fallback_model ?? '';
+    const curDescription = original.description ?? '';
+    const opts = {};
+    if (draft.model !== undefined && draft.model !== curModel)
+        opts.model = draft.model;
+    if (draft.baseUrl && draft.baseUrl !== curBaseUrl)
+        opts.baseUrl = draft.baseUrl;
+    if (draft.authProvider !== undefined)
+        opts.authProvider = draft.authProvider;
+    if (draft.fromSecrets !== undefined)
+        opts.fromSecrets = draft.fromSecrets;
+    if (draft.version !== undefined && draft.version !== curVersion)
+        opts.version = draft.version;
+    if (draft.fallbackModel !== undefined && draft.fallbackModel !== curFallback)
+        opts.fallbackModel = draft.fallbackModel;
+    if (draft.description !== undefined && draft.description !== curDescription)
+        opts.description = draft.description;
+    return opts;
+}
+/**
+ * Interactive `agents harness edit <name>` wizard — runs when no edit flags were
+ * given and stdin+stdout are a TTY. Loads the profile, drives the shared step
+ * engine ({@link editSteps}) pre-filled with current values, then persists via the
+ * same build+write path as the flag-driven edit. `--key-stdin` is honored for the
+ * auth step's key entry. When the user changes nothing, it says so and writes
+ * nothing.
+ */
+async function runEditWizard(name, cliOpts) {
+    if (!profileExists(name)) {
+        throw new Error(`Harness '${name}' not found. Create it first: agents harness add ${name} ...`);
     }
-    else {
-        const preset = getPreset(presetChoice);
-        model = presetModel(preset);
-        baseUrl = preset.env.ANTHROPIC_BASE_URL || preset.env.OPENAI_BASE_URL;
-        authProvider = preset.authOptional ? undefined : preset.provider;
-        // Pre-fill with the preset's own name (e.g. 'deepseek'), not a model
-        // detail, so users aren't nudged toward baking one into the identity name.
-        defaultName = preset.name;
+    const original = readProfile(name);
+    const io = await defaultWizardIO();
+    const draft = await runWizardSteps(editSteps(original), { mode: 'edit', original, host: original.host.agent, name }, io);
+    const opts = { ...draftToEditOptions(draft, original), keyStdin: cliOpts.keyStdin };
+    if (!hasEditFlags(opts)) {
+        console.log(chalk.gray(`No changes made to '${name}'.`));
+        return;
     }
-    const name = await input({
-        message: 'Harness name',
-        default: defaultName,
-        validate: (v) => {
-            try {
-                validateProfileName(v);
-                return true;
-            }
-            catch (err) {
-                return err.message;
-            }
-        },
-    });
-    const opts = { model, baseUrl, authProvider };
-    if (authProvider) {
-        const bundles = listBundles();
-        const TYPE_NOW = 'type';
-        const FROM_SECRETS = 'secrets';
-        const keySource = bundles.length > 0
-            ? await select({
-                message: `How should '${authProvider}' get its key?`,
-                choices: [
-                    { name: 'Type a key now', value: TYPE_NOW },
-                    { name: 'Use an existing agents secrets bundle', value: FROM_SECRETS },
-                ],
-            })
-            : TYPE_NOW;
-        if (keySource === FROM_SECRETS) {
-            const bundleName = await select({
-                message: 'Bundle',
-                choices: bundles.map((b) => ({
-                    name: b.description ? `${b.name}  ${chalk.gray(b.description)}` : b.name,
-                    value: b.name,
-                })),
-            });
-            const bundle = bundles.find((b) => b.name === bundleName);
-            const keys = Object.keys(bundle.vars);
-            const key = keys.length === 1
-                ? keys[0]
-                : await select({ message: 'Key', choices: keys.map((k) => ({ name: k, value: k })) });
-            opts.fromSecrets = `${bundleName}:${key}`;
-        }
+    const edited = buildEdit(name, opts);
+    if (opts.fromSecrets) {
+        await applyFromSecrets(edited, opts.fromSecrets, opts.authProvider);
+    }
+    else if (opts.authProvider) {
+        await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
     }
-    return { source, name, opts };
+    writeProfile(edited);
+    console.log(chalk.green(`Harness '${name}' updated.`));
+    console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
 }
 export function registerHarnessCommands(program) {
     const cmd = program
@@ -354,7 +339,7 @@ Examples:
                 if (!isInteractiveTerminal()) {
                     throw new Error("'agents harness add' needs --preset or --host + --model (or a name and an interactive terminal for the wizard).");
                 }
-                const wiz = await runHarnessWizard();
+                const wiz = await runCreateWizard();
                 await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
                 return;
             }
@@ -399,7 +384,7 @@ Examples:
                 if (!isInteractiveTerminal()) {
                     throw new Error("'agents harness fork' needs <source> and <name> (or an interactive terminal for the wizard).");
                 }
-                const wiz = await runHarnessWizard();
+                const wiz = await runCreateWizard();
                 await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
                 return;
             }
@@ -412,7 +397,7 @@ Examples:
     });
     cmd
         .command('edit <name>')
-        .description('Edit an existing custom harness in place — model, endpoint, auth, version, description, fallback.')
+        .description('Edit an existing custom harness in place — model, endpoint, auth, version, description, fallback. Omit flags in a terminal for the interactive wizard.')
         .option('--model <id>', 'Swap the pinned model')
         .option('--base-url <url>', 'Swap the custom endpoint base URL')
         .option('--auth-provider <provider>', 'Repoint auth at a different provider (keychain-backed)')
@@ -437,9 +422,20 @@ Examples:
 
   # Copy a key out of an existing secrets bundle instead of typing it
   agents harness edit corp --from-secrets prod:OPENROUTER_KEY
+
+  # No flags, in an interactive terminal: a wizard walks each field pre-filled
+  agents harness edit deepseek
 `)
         .action(async (name, opts) => {
         try {
+            // No edit flags + a real terminal → the interactive wizard, pre-filled
+            // with current values. Any flag (or a non-interactive caller) takes the
+            // flag path unchanged; a flagless non-interactive call still errors via
+            // buildEdit's EDIT_FLAGS_HELP.
+            if (!hasEditFlags(opts) && isInteractiveTerminal()) {
+                await runEditWizard(name, opts);
+                return;
+            }
             const edited = buildEdit(name, opts);
             if (opts.fromSecrets) {
                 await applyFromSecrets(edited, opts.fromSecrets, opts.authProvider);

package/dist/commands/resume.js

@@ -22,8 +22,8 @@ export function buildResumeRunArgs(session, prompt, options) {
 }
 export function registerResumeCommand(program) {
     const cmd = program
-        .command('resume <session-id> [prompt]')
-        .description('Resume a session with its original harness, version, device, account, cwd, and mode')
+        .command('resume <session> [prompt]')
+        .description('Resume a session by id, tmux alias, or exact label with its original harness, version, device, account, cwd, and mode. Searches the fleet automatically; a local full-id hit resumes with zero SSH.')
         .option('-m, --mode <mode>', 'Override the recorded launch mode')
         .option('-i, --interactive', 'Resume interactively even when a prompt is provided')
         .option('--headless', 'Resume headlessly (a prompt is required)')
@@ -71,10 +71,17 @@ export function registerResumeCommand(program) {
       # Resume and continue headlessly
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
 
+      # Resume by exact label (auto-resumes the one match)
+      agents resume "fix the flaky ssh test"
+
+      # Resume by durable tmux alias or its unique suffix
+      agents resume ag-codex-c1f3d813
+      agents resume c1f3d813
+
       # Deliberately change permissions
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
         notes: `
-      Full IDs resolve from the local session database first; an SSH fleet lookup runs only after a local miss.
+      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.
       Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
     });
 }

package/dist/commands/secrets.js

@@ -15,7 +15,7 @@ import * as path from 'path';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } 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, } from '../lib/secrets/remote.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 { 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';
@@ -333,10 +333,6 @@ function getCliVersion() {
         return '0.0.0';
     }
 }
-/** POSIX single-quote a string for safe interpolation into a remote shell command. */
-function shellQuote(s) {
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
  * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
@@ -1332,7 +1328,7 @@ export function registerSecretsCommands(program) {
             if (bundle.allow_exec)
                 console.log(chalk.yellow('allow_exec: true'));
             if (bundle.backend === 'file')
-                console.log(chalk.gray('backend: file (passphrase-encrypted; reads need AGENTS_SECRETS_PASSPHRASE, no Touch ID)'));
+                console.log(chalk.gray('backend: file (encrypted at rest; headless reads via a machine-local key, or AGENTS_SECRETS_PASSPHRASE if set — no Touch ID)'));
             if (bundle.backend === 'vault')
                 console.log(chalk.gray('storage: synced (age-encrypted ~/.agents/vault.age; needs agents login)'));
             if (bundlePolicy(bundle) === 'never') {
@@ -1588,7 +1584,7 @@ export function registerSecretsCommands(program) {
                 console.log(chalk.red('Stored without biometry protection — reads are silent. Automation-only; rotate anything sensitive out of it.'));
             }
             if (backend === 'file') {
-                console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted under AGENTS_SECRETS_PASSPHRASE (no Touch ID).'));
+                console.log(chalk.gray('File-backed: items are AES-256-GCM encrypted at rest under a machine-local key (or AGENTS_SECRETS_PASSPHRASE if set); headless reads, no Touch ID.'));
             }
             if (backend === 'vault') {
                 console.log(chalk.gray('Synced: items are encrypted in ~/.agents/vault.age. Copy that file with your sync tool of choice.'));
@@ -2064,7 +2060,7 @@ Examples:
         .option('--vault <name>', '1Password vault name (used with --to-1password)')
         .option('--host <target...>', 'Push the bundle over SSH to this target (host alias or user@host); repeatable for multiple machines')
         .option('--device <target...>', 'Alias for --host; repeatable')
-        .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file (passphrase-encrypted, headless-readable). file forwards AGENTS_SECRETS_PASSPHRASE over stdin.', 'keychain')
+        .option('--remote-backend <backend>', 'Backend for the bundle on the remote (with --host): keychain (default) or file. file is headless-readable via the remote\'s machine-local key; it forwards AGENTS_SECRETS_PASSPHRASE over stdin only if set (opt-in).', 'keychain')
         .option('--force', 'Overwrite existing keys/items on the target (used with --to-1password and --host)')
         .option('--format <shell|json>', 'Output for --plaintext export: shell (default) or json (lossless, machine-readable; used by remote resolve)', 'shell')
         .option('--to-file <path>', 'Write the bundle as an AES-256-GCM encrypted offline file (needs AGENTS_SECRETS_PASSPHRASE; symmetric counterpart of import --from-file)')
@@ -2097,20 +2093,16 @@ Examples:
                 for (const h of hosts)
                     assertValidSshTarget(h);
                 const remoteBackend = parseBackendOpt(opts.remoteBackend);
-                // For a file-backed remote bundle the remote must encrypt at rest with
-                // a passphrase. We forward the LOCAL AGENTS_SECRETS_PASSPHRASE — the
-                // operator unlocks it once on this (trusted, biometry-gated) machine —
-                // and ship it as the FIRST stdin line so it never lands in argv / `ps`
-                // / the remote shell history. The remote `read -r` consumes that line;
-                // `agents secrets import --from /dev/stdin` reads the .env remainder.
-                let remotePassphrase = '';
-                if (remoteBackend === 'file') {
-                    remotePassphrase = process.env.AGENTS_SECRETS_PASSPHRASE ?? '';
-                    if (!remotePassphrase) {
-                        throw new Error('--remote-backend file needs AGENTS_SECRETS_PASSPHRASE set locally to encrypt the ' +
-                            'bundle at rest on the remote. Set it for this command, then unlock it the same way per run.');
-                    }
-                }
+                // 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.
+                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;
@@ -2126,19 +2118,22 @@ Examples:
                 for (const host of hosts) {
                     let res;
                     if (remoteBackend === 'file') {
-                        // File backend forwards AGENTS_SECRETS_PASSPHRASE as the FIRST stdin
-                        // line (consumed by `read`, so it never lands in argv / `ps` /
-                        // remote history), then the .env. That `read`/`export` prologue is
-                        // POSIX shell — refuse a Windows target cleanly rather than emit
-                        // broken PowerShell.
+                        // 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 remoteAgents = `IFS= read -r AGENTS_SECRETS_PASSPHRASE; export AGENTS_SECRETS_PASSPHRASE; ` +
-                            `agents secrets import ${shellQuote(resolvedBundleName)} --from - --backend file${opts.force ? ' --force' : ''}`;
-                        res = sshExec(host, `bash -lc ${shellQuote(remoteAgents)}`, { input: `${remotePassphrase}\n${dotenv}` });
+                        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

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

@@ -1,6 +1,8 @@
 import type { Command } from 'commander';
-import { type Packing } from '../lib/terminal/index.js';
-interface ResumeOptions {
+import { type Backend, type EngineContext, type Packing } from '../lib/terminal/index.js';
+/** Opening more than this many live sessions at once asks for confirmation first. */
+export declare const CONFIRM_THRESHOLD = 5;
+export interface ResumeOptions {
     agent?: string;
     all?: boolean;
     teams?: boolean;
@@ -16,5 +18,21 @@ interface ResumeOptions {
     splits?: boolean;
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
+/** 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;
+/** Re-enter through the top-level command so fleet routing and harness policy
+ * stay centralized. The child inherits this terminal for a real interactive resume. */
+export declare function resumeSelectorInPlace(selector: string): Promise<void>;
+/** Direct identities use focus as the lifecycle dispatcher: it rechecks the
+ * live fleet, attaches a healthy pane, and falls through to `agents resume`
+ * only when the process is no longer attachable. */
+export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[]): Promise<void>;
+export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[]): string[];
 export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;
-export {};
+/**
+ * Decide which backend to launch into. Returns a concrete backend, `'inplace'`
+ * (resume in the current process — no GUI/tmux available), or `'cancel'` (the
+ * user dismissed the chooser).
+ */
+export declare function resolveBackend(options: ResumeOptions, ctx: EngineContext, count: number): Promise<Backend | 'inplace' | 'cancel'>;

package/dist/commands/sessions-resume.js

@@ -14,18 +14,21 @@ 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, buildResumeCommand, resumeSessionInPlace, parseAgentFilter, } from './sessions.js';
+import { filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, resumeSessionInPlace, parseAgentFilter, } from './sessions.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';
 /** Opening more than this many live sessions at once asks for confirmation first. */
-const CONFIRM_THRESHOLD = 5;
+export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
     const cmd = sessionsCmd
         .command('resume')
-        .argument('[query]', 'Filter sessions before selecting (topic, path, or id fragment)')
-        .description('Multi-select sessions and resume each in a terminal tab/split (this terminal, iTerm, Ghostty, tmux, VSCodium; local or --host).')
+        .argument('[query]', 'Session id/tmux alias to reopen directly, or text that filters the picker')
+        .description('Reopen one session by canonical identity, or multi-select history into terminal tabs/splits.')
         .option('-a, --agent <agent>', 'Filter by agent type and version (e.g., claude, codex@0.116.0)')
         .option('--all', 'Include sessions from every directory (not just current project)')
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
@@ -46,6 +49,10 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       # Pre-filter the pool before selecting (space in the filter → use [query])
       agents sessions resume "auth middleware"
 
+      # Reopen one session from any device by UUID prefix or tmux alias
+      agents sessions resume 019fd114
+      agents sessions resume ag-codex-c1f3d813
+
       # Force a backend / side-by-side splits / a remote host
       agents sessions resume --ghostty
       agents sessions resume --vscodium
@@ -53,7 +60,8 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       agents sessions resume --host zion --tmux
     `,
         notes: `
-      - space toggles a session, enter confirms; tab toggles the preview pane.
+      - A UUID/prefix or ag-<agent>-<suffix> alias bypasses the picker: a live pane is attached; an inactive session resumes on its owning device.
+      - With no identity selector, space toggles a session, enter confirms, and tab toggles the preview pane.
       - 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).
@@ -71,6 +79,10 @@ async function sessionsResumeAction(query, options) {
         process.exitCode = 1;
         return;
     }
+    if (query && isDirectResumeSelector(query)) {
+        await dispatchSessionLifecycleInPlace(query.trim(), options.host ? [options.host] : []);
+        return;
+    }
     const { agent, version } = parseAgentFilter(options.agent);
     const limit = parseInt(options.limit || '200', 10);
     const since = options.since ?? (options.all ? undefined : '30d');
@@ -118,11 +130,7 @@ async function sessionsResumeAction(query, options) {
     // 2. Split the selection into resumable surfaces and skipped agents (no silent drop).
     const items = [];
     for (const s of chosen) {
-        const command = buildResumeCommand(s);
-        if (!command) {
-            console.log(chalk.yellow(`  skip ${s.shortId} — resume is not supported for ${s.agent} sessions yet`));
-            continue;
-        }
+        const command = buildCanonicalResumeCommand(s.id);
         const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
         items.push({ session: s, cwd, command });
     }
@@ -179,6 +187,37 @@ async function sessionsResumeAction(query, options) {
     });
     console.log(chalk.gray(`\nOpened ${opened}/${items.length} in ${where}.`));
 }
+/** 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 function isDirectResumeSelector(query) {
+    const selector = query.trim();
+    return looksLikeSessionId(selector) || /^ag-[a-z][a-z0-9-]*-[0-9a-f]{8}$/i.test(selector);
+}
+/** Re-enter through the top-level command so fleet routing and harness policy
+ * stay centralized. The child inherits this terminal for a real interactive resume. */
+export async function resumeSelectorInPlace(selector) {
+    await spawnCliInPlace(['resume', selector]);
+}
+/** Direct identities use focus as the lifecycle dispatcher: it rechecks the
+ * live fleet, attaches a healthy pane, and falls through to `agents resume`
+ * only when the process is no longer attachable. */
+export async function dispatchSessionLifecycleInPlace(selector, hosts = []) {
+    await spawnCliInPlace(buildSessionLifecycleArgs(selector, hosts));
+}
+export function buildSessionLifecycleArgs(selector, hosts = []) {
+    return ['sessions', 'focus', selector, ...hosts.flatMap(host => ['--host', host])];
+}
+function asyncExitCode(child) {
+    return new Promise((resolve) => {
+        child.once('error', () => resolve(127));
+        child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
+    });
+}
+async function spawnCliInPlace(args) {
+    const child = spawn(process.execPath, [process.argv[1], ...args], { stdio: 'inherit' });
+    const exitCode = await asyncExitCode(child);
+    process.exitCode = exitCode;
+}
 export function resolveResumePacking(options) {
     return options.splits ? 'two-per-tab' : 'tabs';
 }
@@ -187,7 +226,7 @@ export function resolveResumePacking(options) {
  * (resume in the current process — no GUI/tmux available), or `'cancel'` (the
  * user dismissed the chooser).
  */
-async function resolveBackend(options, ctx, count) {
+export async function resolveBackend(options, ctx, count) {
     const forced = options.iterm ? 'iterm'
         : options.ghostty ? 'ghostty'
             : options.tmux ? 'tmux'