@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/commands/import.js

@@ -20,6 +20,9 @@
  * In all forms, the agent's config dir (e.g. ~/.openclaw) is also moved under
  * management — same behavior as the first-run `agents setup` import flow.
  */
+import { withIsolationBoundary } from '../lib/isolation-boundary-report.js';
+import { assertIsolationBoundary, createVersionedAlias } from '../lib/shims.js';
+import { markVersionIsolated } from '../lib/versions.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -29,7 +32,7 @@ import { confirm } from '@inquirer/prompts';
 import { ALL_AGENT_IDS } from '../lib/agents.js';
 import { AGENTS, getCliPath, getCliVersion, agentLabel, resolveAgentName } from '../lib/agents.js';
 import { getVersionDir } from '../lib/versions.js';
-import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
+import { finalizeImport, importAgentBinary, importAgentConfig, importInstallScriptBinary, seedIsolatedConfigFromLocal, isValidImportVersion, resolvePackageDirFromBinary, } from '../lib/import.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 async function runImport(agentArg, opts) {
     const agentId = resolveAgentName(agentArg);
@@ -39,6 +42,16 @@ async function runImport(agentArg, opts) {
         process.exit(1);
     }
     const agent = AGENTS[agentId];
+    // Import registers the adopted install as a NORMAL version and only then sets the
+    // default / creates the shim / repoints the config. By that point the agent has a
+    // non-isolated version, so it is no longer protected and the primitive gates —
+    // which read the state as it is at call time — would let the adoption through.
+    // The boundary has to be checked against the state BEFORE the import mutates it.
+    // --isolated adopts nothing, so the boundary does not apply to it — it is in fact
+    // the supported way to bring a local install in while protection is on.
+    if (!opts.isolated) {
+        assertIsolationBoundary(agentId, 'adopt your existing install');
+    }
     // installScript-based agents (Grok, Antigravity, Cursor, Kiro, Goose, Roo)
     // don't have an npm package; their binary lives wherever the curl/brew
     // installer dropped it. We adopt by symlinking that PATH binary directly
@@ -121,7 +134,7 @@ async function runImport(agentArg, opts) {
             }
         }
     }
-    let version = opts.version;
+    let version = opts.as;
     if (!version) {
         if (!useDirectBinaryImport && globalPath) {
             try {
@@ -144,7 +157,7 @@ async function runImport(agentArg, opts) {
     }
     if (!version) {
         console.error(chalk.red(`Could not determine version for ${agentLabel(agentId)}.`));
-        console.error(chalk.gray('Pass --version <version> explicitly.'));
+        console.error(chalk.gray('Pass --as <version> explicitly.'));
         process.exit(1);
     }
     if (!isValidImportVersion(version)) {
@@ -154,7 +167,7 @@ async function runImport(agentArg, opts) {
     }
     const versionDir = getVersionDir(agentId, version);
     const fromLabel = useDirectBinaryImport ? installScriptBinary : globalPath;
-    console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}`));
+    console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}${opts.isolated ? ' (isolated copy)' : ''}`));
     console.log(`  from: ${chalk.gray(fromLabel)}`);
     console.log(`  into: ${chalk.gray(versionDir)}`);
     const configDirExists = fs.existsSync(agent.configDir);
@@ -165,6 +178,16 @@ async function runImport(agentArg, opts) {
             configAlreadyManaged = true;
             console.log(`  config: ${chalk.gray(`${agent.configDir} (already managed — will skip)`)}`);
         }
+        else if (opts.isolated) {
+            // This summary is printed BEFORE the branch that does the work, so it has to
+            // describe the mode it is actually about to run. Saying "will be moved" under
+            // --isolated announced the exact adoption the flag exists to prevent — a
+            // confirmation prompt that misdescribes the operation is worse than none.
+            console.log(`  config: ${chalk.gray(`${agent.configDir} (will be COPIED — your original stays put)`)}`);
+            if (!opts.withAuth) {
+                console.log(`          ${chalk.gray('credentials are skipped; pass --with-auth to include them')}`);
+            }
+        }
         else {
             console.log(`  config: ${chalk.gray(`${agent.configDir} (will be moved into version home)`)}`);
         }
@@ -175,7 +198,9 @@ async function runImport(agentArg, opts) {
     if (!opts.yes && isInteractiveTerminal()) {
         console.log();
         const proceed = await confirm({
-            message: `Import ${agentLabel(agentId)} v${version} into agents-cli?`,
+            message: opts.isolated
+                ? `Import ${agentLabel(agentId)} v${version} as an isolated copy?`
+                : `Import ${agentLabel(agentId)} v${version} into agents-cli?`,
             default: true,
         }).catch((err) => {
             if (isPromptCancelled(err))
@@ -191,7 +216,33 @@ async function runImport(agentArg, opts) {
     // user-visible side effect (renaming ~/.<agent>/), so if it fails we don't
     // want a stranded symlink farm. Binary registration is cheap and reversible
     // — if it fails after config, the next `agents import` call retries cleanly.
-    const willImportConfig = configDirExists && !configAlreadyManaged;
+    const willImportConfig = configDirExists && !configAlreadyManaged && !opts.isolated;
+    if (opts.isolated && configDirExists && configAlreadyManaged) {
+        console.log(chalk.gray(`  Skipping config copy: ${agent.configDir} is a managed symlink, not your real settings.`));
+    }
+    else if (opts.isolated && configDirExists) {
+        // COPY the user's settings in; never move, never symlink. The original stays
+        // exactly where it is — that is what separates this from adoption.
+        const seedSpinner = ora(`Copying ${agent.configDir} into the isolated copy...`).start();
+        const seed = seedIsolatedConfigFromLocal(agentId, version, { withAuth: opts.withAuth, all: opts.all });
+        if (seed.error) {
+            seedSpinner.fail(`Config: ${seed.error}`);
+            process.exit(1);
+        }
+        else if (seed.seeded) {
+            seedSpinner.succeed(`Settings copied (${seed.from} -> ${seed.to}); your original is untouched`);
+            if (seed.skippedRuntime.length > 0) {
+                console.log(chalk.gray(`  Runtime state NOT copied: ${seed.skippedRuntime.join(', ')} (regenerated as you use it; --all to include)`));
+            }
+            if (seed.skippedAuth.length > 0) {
+                console.log(chalk.gray(`  Credentials NOT copied: ${seed.skippedAuth.join(', ')}`));
+                console.log(chalk.gray('  The copy signs in separately. Use --with-auth to copy them too.'));
+            }
+        }
+        else {
+            seedSpinner.info('No existing config to copy.');
+        }
+    }
     if (willImportConfig) {
         const cfgSpinner = ora(`Importing config dir for ${agentLabel(agentId)} v${version}...`).start();
         const cfgResult = await importAgentConfig(agentId, version);
@@ -224,6 +275,19 @@ async function runImport(agentArg, opts) {
     // Wire the imported version into the resolver: global default, main shim,
     // versioned alias, home-file symlinks. Idempotent — safe to call even if
     // importAgentConfig already set the global default.
+    if (opts.isolated) {
+        // The isolated finalizer: launchable alias + marker, and nothing else. No global
+        // default, no bare shim, no config symlink — the same shape as
+        // `agents add --isolated`.
+        createVersionedAlias(agentId, version);
+        markVersionIsolated(agentId, version);
+        console.log();
+        console.log(chalk.green(`${agentLabel(agentId)} v${version} imported as an isolated copy.`));
+        console.log(chalk.gray(`  Your ${agent.configDir} and ${agent.cliCommand} launcher are untouched.`));
+        console.log(chalk.gray(`  Run it:  agents run ${agentId}@${version}`));
+        console.log(chalk.gray(`  Or make it the default isolated copy:  agents use ${agentId}@${version}`));
+        return;
+    }
     const finalizeSpinner = ora(`Wiring ${agentLabel(agentId)} v${version} as the active version...`).start();
     try {
         finalizeImport(agentId, version);
@@ -242,13 +306,22 @@ export function registerImportCommand(program) {
         .command('import')
         .argument('<agent>', 'Agent id (e.g. openclaw, claude, codex)')
         .description('Import an existing unmanaged agent install into agents-cli')
-        .option('--version <version>', 'Pin a version label (otherwise read from package.json)')
+        // NOT `--version`. The program declares `.version(VERSION)` (src/index.ts), which
+        // claims `-V, --version` globally and wins over a subcommand option of the same
+        // name — so `agents import codex --version 1.2.3` printed the CLI's own version
+        // and exited without importing anything. The flag had been unreachable since it
+        // was introduced, and the "could not determine version" error even advised using
+        // it. Renamed so it actually reaches the command.
+        .option('--as <version>', 'Version label to import as (otherwise read from package.json)')
         .option('--from-path <path>', 'Path to the npm package dir (otherwise auto-detected from PATH)')
+        .option('--isolated', 'Copy the install into a self-contained isolated version instead of adopting it')
+        .option('--with-auth', 'With --isolated, also copy credentials into the sandbox (skipped by default)')
+        .option('--all', 'With --isolated, also copy session history, logs and caches (skipped by default)')
         .option('-y, --yes', 'Skip the confirmation prompt')
         .addHelpText('after', `
 Examples:
   $ agents import openclaw                          Auto-detect via PATH
-  $ agents import openclaw --version 2026.3.8       Pin a version label
+  $ agents import openclaw --as 2026.3.8            Pin a version label
   $ agents import openclaw --from-path /opt/homebrew/lib/node_modules/openclaw
 
   # installScript-based agents (curl/brew installers, no npm package):
@@ -257,6 +330,11 @@ Examples:
   $ agents import cursor                            Adopt ~/.local/bin/cursor-agent
   $ agents import antigravity --from-path ~/.local/bin/agy
 
+  # Copy your setup into a sandbox instead of adopting it:
+  $ agents import codex --isolated                  New isolated copy at the local version
+  $ agents import codex --isolated --as 0.146.0     Re-seed an EXISTING isolated copy
+  $ agents import codex --isolated --with-auth      ...and share credentials with it
+
 When to use:
   When an agent CLI is already installed globally and you want to bring it
   under agents-cli management without reinstalling. Creates a symlink farm
@@ -265,5 +343,5 @@ When to use:
   npm-style packages (claude, codex, gemini, opencode, openclaw) and
   installScript-based agents (grok, antigravity, cursor, kiro, goose).
 `)
-        .action(runImport);
+        .action((...args) => withIsolationBoundary(() => runImport(...args)));
 }

package/dist/commands/inspect.js

@@ -21,6 +21,7 @@ import { truncate, termLink } from '../lib/format.js';
 import * as yaml from 'yaml';
 import { AGENTS, getCliState, resolveAgentName } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
+import { resolveConfiguredModel } from '../lib/models.js';
 import { resolveSingleAgentTarget, AgentSpecError } from '../lib/agent-spec/index.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath } from '../lib/versions.js';
@@ -585,8 +586,10 @@ async function renderSummary(agent, version, versionHome, options) {
         console.log(JSON.stringify(json, null, 2));
         return;
     }
-    // Plain text
-    const head = `${chalk.bold(agent)} ${chalk.gray('@')} ${chalk.cyan(version)}${isDefault ? '  ' + chalk.green('[default]') : ''}`;
+    // Plain text — model sits right beside the version, same priority (no label).
+    const configuredModel = resolveConfiguredModel(agent, version)?.model;
+    const modelPart = configuredModel ? '  ' + chalk.yellow(configuredModel) : '';
+    const head = `${chalk.bold(agent)} ${chalk.gray('@')} ${chalk.cyan(version)}${modelPart}${isDefault ? '  ' + chalk.green('[default]') : ''}`;
     console.log('\n' + head + '\n');
     const rows = [
         ['install', versionHome],

package/dist/commands/profiles.d.ts

@@ -15,5 +15,25 @@ import { type Preset } from '../lib/profiles-presets.js';
  * without mocking @inquirer/prompts.
  */
 export declare function buildProfileFromCollection(name: string, preset: Preset, collected: Record<string, string>, version?: string): Profile;
+/** Options accepted by {@link addProfile} — shared by `agents profiles add` and `agents harness add`. */
+export interface AddProfileOptions {
+    preset?: string;
+    host?: string;
+    model?: string;
+    baseUrl?: string;
+    authProvider?: string;
+    version?: string;
+    keyStdin?: boolean;
+    force?: boolean;
+}
+/**
+ * Create a profile ("custom harness"). Two paths:
+ *  - `--host <agent> --model <id>`: one-shot custom harness from a host + model
+ *    (no preset needed). This is what makes a model like Muse Spark a named,
+ *    runnable harness.
+ *  - otherwise: apply a built-in preset (existing behavior).
+ * `label` only tunes the success wording (Profile vs Harness). Throws on error.
+ */
+export declare function addProfile(name: string, opts: AddProfileOptions, label?: 'Profile' | 'Harness'): Promise<void>;
 /** Register the `agents profiles` command tree. */
 export declare function registerProfilesCommands(program: Command): void;

package/dist/commands/profiles.js

@@ -9,13 +9,13 @@
 import chalk from 'chalk';
 import { readStdinSync } from '../lib/format.js';
 import { spawn } from 'child_process';
-import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, validateProfileName, getPresetForProfile, } from '../lib/profiles.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, profileFromHostModel, baseUrlEnvKeyForHost, authEnvKeyForHost, validateProfileName, getPresetForProfile, } from '../lib/profiles.js';
 import { getPreset, listPresets, expandPreset } from '../lib/profiles-presets.js';
 import { hasKeychainToken, keychainItemName, setKeychainToken, deleteKeychainToken, } from '../lib/secrets/profiles.js';
 import { isInteractiveTerminal } from './utils.js';
 import { getAgentsInvocation } from '../lib/daemon.js';
 import { getActiveResourceProfileName, getResourceProfilePreset, listResourceProfileNames, setActiveResourceProfile, upsertResourceProfilePreset, validateResourceProfileName, } from '../lib/resource-profiles.js';
-import { AGENTS } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
 import { listInstalledVersions, syncResourcesToVersion } from '../lib/versions.js';
 /**
  * Pure helper: builds a Profile from collected wizard inputs. Extracted so the
@@ -31,6 +31,7 @@ export function buildProfileFromCollection(name, preset, collected, version) {
             envVar: preset.authEnvVar,
             keychainItem: keychainItemName(preset.provider),
         },
+        authOptional: preset.authOptional,
         description: preset.description,
         preset: preset.name,
         provider: preset.provider,
@@ -65,6 +66,66 @@ async function ensureProviderToken(provider, signupUrl, fromStdin) {
     setKeychainToken(item, token);
     console.log(chalk.green(`Stored in keychain: ${item}`));
 }
+/**
+ * Create a profile ("custom harness"). Two paths:
+ *  - `--host <agent> --model <id>`: one-shot custom harness from a host + model
+ *    (no preset needed). This is what makes a model like Muse Spark a named,
+ *    runnable harness.
+ *  - otherwise: apply a built-in preset (existing behavior).
+ * `label` only tunes the success wording (Profile vs Harness). Throws on error.
+ */
+export async function addProfile(name, opts, label = 'Profile') {
+    validateProfileName(name);
+    if (profileExists(name) && !opts.force) {
+        throw new Error(`${label} '${name}' already exists. Use --force to overwrite.`);
+    }
+    // One-shot host + model → custom harness, no preset required.
+    if (opts.host || opts.model) {
+        if (!opts.host || !opts.model) {
+            throw new Error('Both --host <agent> and --model <id> are required to build a harness from a host + model.');
+        }
+        if (!ALL_AGENT_IDS.includes(opts.host)) {
+            throw new Error(`Unknown host '${opts.host}'. Valid hosts: ${ALL_AGENT_IDS.join(', ')}`);
+        }
+        const host = opts.host;
+        if (opts.baseUrl && !baseUrlEnvKeyForHost(host)) {
+            console.error(chalk.yellow(`Note: --base-url has no known env var for host '${host}'; ignoring it.`));
+        }
+        let authEnvVar;
+        if (opts.authProvider) {
+            const key = authEnvKeyForHost(host);
+            if (!key) {
+                throw new Error(`--auth-provider is set but host '${host}' has no known auth env var. Use a preset or a hand-written profile YAML.`);
+            }
+            authEnvVar = key;
+            await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
+        }
+        const profile = profileFromHostModel(name, host, opts.model, {
+            version: opts.version,
+            baseUrl: opts.baseUrl,
+            provider: opts.authProvider,
+            authEnvVar,
+        });
+        writeProfile(profile);
+        console.log(chalk.green(`${label} '${name}' added — ${host} + ${opts.model}.`));
+        console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+        return;
+    }
+    // Preset path.
+    const presetName = opts.preset || name;
+    const preset = getPreset(presetName);
+    if (!preset) {
+        throw new Error(`No preset '${presetName}'.\nAvailable presets: ${listPresets().map((p) => p.name).join(', ')}\n` +
+            'Or build a custom harness: --host <agent> --model <id>.');
+    }
+    if (!preset.authOptional) {
+        await ensureProviderToken(preset.provider, preset.signupUrl, opts.keyStdin);
+    }
+    const profile = profileFromPreset(name, preset, opts.version);
+    writeProfile(profile);
+    console.log(chalk.green(`${label} '${name}' added.`));
+    console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+}
 /** Format a single profile as a table row for the `profiles list` output. */
 function renderProfileRow(p) {
     const host = p.host.version ? `${p.host.agent}@${p.host.version}` : p.host.agent;
@@ -462,27 +523,13 @@ Examples:
         .option('--version <version>', 'Pin the host CLI version (e.g., 2.1.113)')
         .option('--key-stdin', 'Read API key from stdin instead of prompting (for scripts/CI)')
         .option('--force', 'Overwrite an existing profile with the same name')
+        .addHelpText('after', '\nTo build a custom harness from a host CLI + model in one shot, use `agents harness add`.\n')
         .action(async (name, opts) => {
+        // Preset-only surface here — `--host` on `profiles` is reserved for remote
+        // device routing (see lib/hosts/passthrough.ts). The host+model one-shot
+        // lives on `agents harness add`, which owns its own `--host`.
         try {
-            if (profileExists(name) && !opts.force) {
-                console.error(chalk.red(`Profile '${name}' already exists. Use --force to overwrite.`));
-                process.exit(1);
-            }
-            const presetName = opts.preset || name;
-            const preset = getPreset(presetName);
-            if (!preset) {
-                console.error(chalk.red(`No preset '${presetName}'.`));
-                console.error(chalk.gray('Available presets: ' + listPresets().map((p) => p.name).join(', ')));
-                console.error(chalk.gray('Or pass --preset <name> to pick explicitly.'));
-                process.exit(1);
-            }
-            if (!preset.authOptional) {
-                await ensureProviderToken(preset.provider, preset.signupUrl, opts.keyStdin);
-            }
-            const profile = profileFromPreset(name, preset, opts.version);
-            writeProfile(profile);
-            console.log(chalk.green(`Profile '${name}' added.`));
-            console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+            await addProfile(name, { preset: opts.preset, version: opts.version, keyStdin: opts.keyStdin, force: opts.force }, 'Profile');
         }
         catch (err) {
             console.error(chalk.red(err.message));

package/dist/commands/repo.js

@@ -812,6 +812,7 @@ export function registerRepoCommands(program) {
             console.log(chalk.gray('No repos to pull.'));
             return;
         }
+        let anyPulled = false;
         for (const t of targets) {
             if (!fs.existsSync(t.dir) || !isGitRepo(t.dir)) {
                 // A plain (never-cloned) user repo — setup makes ~/.agents a bare dir and
@@ -851,11 +852,24 @@ export function registerRepoCommands(program) {
             const result = await pullRepo(t.dir);
             if (result.success) {
                 spinner.succeed(`${formatRepoTarget(t.alias, t.dir, result.branch)}: ${result.commit}`);
+                anyPulled = true;
             }
             else {
                 spinner.fail(`${formatRepoTarget(t.alias, t.dir)}: ${result.error}`);
             }
         }
+        // RUSH-1980: a pull rewrites the routine YAML on disk, but the daemon's
+        // scheduler froze its JobConfigs (device pins included) at load. Without a
+        // reload it keeps firing the pre-pull pins — a routine re-pinned to another
+        // host still fires here, double-firing across the fleet. SIGHUP the daemon
+        // so scheduler.reloadAll() re-reads the synced YAML and device pins refresh.
+        // No-op when the daemon isn't running (or on Windows, which has no SIGHUP).
+        if (anyPulled) {
+            const { isDaemonRunning, signalDaemonReload } = await import('../lib/daemon.js');
+            if (isDaemonRunning() && signalDaemonReload()) {
+                console.log(chalk.gray('Reloaded the routines daemon (device pins refreshed).'));
+            }
+        }
     });
     repoCmd
         .command('push [alias]')

package/dist/commands/routines.js

@@ -783,18 +783,26 @@ export function registerRoutinesCommands(program) {
         try {
             const result = await executeJob(job);
             const logPath = `${getRunDir(name, result.meta.runId)}/stdout.log`;
+            const succeeded = result.meta.status === 'completed';
             if (options.json) {
                 writeJson({
-                    ok: true,
+                    ok: succeeded,
                     job: name,
                     logDir: getRunDir(name, result.meta.runId),
                     ...runMetaJson(result.meta),
                     logPath,
                     reportPath: result.reportPath ?? null,
                 });
+                // A failed run must exit non-zero so cron wrappers, `&&` chains, and
+                // `--json` consumers actually see the failure (a logged-out agent used
+                // to exit 0 with ok:true, hiding the whole auth-failure epidemic). Set
+                // exitCode rather than process.exit() so the JSON payload is fully
+                // flushed to a pipe before the process ends.
+                if (!succeeded)
+                    process.exitCode = 1;
                 return;
             }
-            if (result.meta.status === 'completed') {
+            if (succeeded) {
                 spinner.succeed(`Job completed (exit code: ${result.meta.exitCode})`);
             }
             else if (result.meta.status === 'timeout') {
@@ -805,10 +813,15 @@ export function registerRoutinesCommands(program) {
             }
             console.log(chalk.gray(`  Run: ${result.meta.runId}`));
             console.log(chalk.gray(`  Log: ${logPath}`));
+            if (result.meta.errorMessage) {
+                console.log(chalk.gray(`  Reason: ${result.meta.errorMessage}`));
+            }
             if (result.reportPath) {
                 console.log(chalk.bold('\nReport:\n'));
                 console.log(fs.readFileSync(result.reportPath, 'utf-8'));
             }
+            if (!succeeded)
+                process.exitCode = 1;
         }
         catch (err) {
             if (options.json) {

package/dist/commands/secrets.js

@@ -15,10 +15,10 @@ 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, resolveSshTarget, } from '../lib/secrets/remote.js';
+import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveHostSshTarget, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
+import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, isHeadlessSecretsContext, readBundle, readBundleIfDecryptable, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, writeBundleWithItems, } from '../lib/secrets/bundles.js';
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
@@ -225,17 +225,29 @@ async function importFromICloud(bundleName, opts) {
     }
 }
 /**
- * Printed under a "bundle not found" failure: if the name matches a bundle
- * stranded in the iCloud Keychain (pre-device-local-cutover era), point at the
- * recovery command instead of leaving a dead end.
+ * Printed under a read failure: if the name matches a bundle stranded in the
+ * iCloud Keychain (pre-device-local-cutover era), point at the recovery command
+ * instead of leaving a dead end.
+ *
+ * `stillPresent` distinguishes the two failures, because they need different
+ * commands. A MISSING bundle imports straight from iCloud. A bundle that is on
+ * disk but undecryptable does not: `import` reads the existing bundle before
+ * writing into it, so it fails the same way the read just did. That one has to
+ * be deleted first — which is why naming the wrong command here bricked the
+ * name entirely.
  */
-function maybePrintSyncedHint(name) {
+function maybePrintSyncedHint(name, stillPresent) {
     if (process.platform !== 'darwin')
         return;
     try {
-        if (discoverSyncedBundles().some((c) => c.name === name)) {
-            console.error(chalk.yellow(`A legacy iCloud Keychain copy of '${name}' exists. Recover it with: agents secrets import ${name} --from icloud`));
-        }
+        if (!discoverSyncedBundles().some((c) => c.name === name))
+            return;
+        console.error(chalk.yellow(stillPresent
+            ? `A legacy iCloud Keychain copy of '${name}' exists, but the local copy is unreadable and ` +
+                `import writes into it. Delete the local copy first, then recover:\n` +
+                `  agents secrets delete ${name}\n` +
+                `  agents secrets import ${name} --from icloud`
+            : `A legacy iCloud Keychain copy of '${name}' exists. Recover it with: agents secrets import ${name} --from icloud`));
     }
     catch {
         // Hint only — never mask the original error.
@@ -383,12 +395,12 @@ async function browseRemote(targets, args, tty) {
     };
     if (tty) {
         for (const t of targets) {
-            const target = await resolveSshTarget(t);
+            const target = await resolveHostSshTarget(t);
             render(t, remoteSecretsRaw(target, args, { tty: true, osLookupName: t }));
         }
     }
     else {
-        const resolved = await Promise.all(targets.map(async (t) => ({ name: t, target: await resolveSshTarget(t) })));
+        const resolved = await Promise.all(targets.map(async (t) => ({ name: t, target: await resolveHostSshTarget(t) })));
         const results = resolved.map(({ name, target }) => remoteSecretsRaw(target, args, { osLookupName: name }));
         targets.forEach((t, i) => render(t, results[i]));
     }
@@ -871,7 +883,7 @@ export function registerSecretsCommands(program) {
             }
             catch (err) {
                 console.error(chalk.red(err.message));
-                maybePrintSyncedHint(resolvedName);
+                maybePrintSyncedHint(resolvedName, bundleExists(resolvedName));
                 process.exit(1);
             }
             const entries = describeBundle(bundle);
@@ -1465,16 +1477,27 @@ Examples:
         .action(async (name, opts) => {
         try {
             const resolvedName = name ?? (await pickBundleName('delete'));
-            const bundle = readBundle(resolvedName);
+            // An undecryptable bundle (lost/rotated passphrase) must still be
+            // deletable: deletion is the ONLY way out of that state, and every other
+            // verb — view, add, import — refuses to touch the name until it's gone.
+            // Its key refs are unreadable, so its keychain items cannot be
+            // enumerated for purging; say so rather than claiming a clean purge.
+            const bundle = readBundleIfDecryptable(resolvedName);
             if (!opts.yes) {
                 if (!isInteractiveTerminal()) {
                     console.error(chalk.red(`Refusing to delete '${resolvedName}' without --yes in a non-interactive shell.`));
                     process.exit(1);
                 }
-                const keychainCount = describeBundle(bundle).filter((e) => e.kind === 'keychain').length;
-                const suffix = keychainCount && !opts.keepSecrets
-                    ? ` and purge ${keychainCount} keychain item${keychainCount === 1 ? '' : 's'}`
-                    : '';
+                let suffix;
+                if (!bundle) {
+                    suffix = ' (unreadable — its keychain items cannot be enumerated and will be left in place)';
+                }
+                else {
+                    const keychainCount = describeBundle(bundle).filter((e) => e.kind === 'keychain').length;
+                    suffix = keychainCount && !opts.keepSecrets
+                        ? ` and purge ${keychainCount} keychain item${keychainCount === 1 ? '' : 's'}`
+                        : '';
+                }
                 const { confirm } = await import('@inquirer/prompts');
                 const proceed = await confirm({
                     message: `Delete bundle '${resolvedName}'${suffix}?`,
@@ -1485,7 +1508,7 @@ Examples:
                     return;
                 }
             }
-            if (!opts.keepSecrets) {
+            if (bundle && !opts.keepSecrets) {
                 const store = bundleItemStore(bundle.backend);
                 for (const { item } of keychainItemsForBundle(bundle)) {
                     store.delete(item);
@@ -1583,7 +1606,7 @@ Examples:
                 }
                 assertValidSshTarget(opts.host);
                 const resolvedBundleName = bundleName ?? (await pickBundleName('import into'));
-                const target = await resolveSshTarget(opts.host);
+                const target = await resolveHostSshTarget(opts.host);
                 const env = await remoteResolveEnv(target, resolvedBundleName, { osLookupName: opts.host });
                 const bundle = resolveImportBundle(resolvedBundleName, opts.backend, opts.synced);
                 const { added, skipped } = applyEnvToBundle(bundle, env, opts);
@@ -1848,7 +1871,7 @@ Examples:
                 // locally instead.
                 const { assertRemoteBundleFlagsUnsupported } = await import('../lib/secrets/bundles.js');
                 assertRemoteBundleFlagsUnsupported(bundleName, execOpts.host, { keys: keysSubset, allowExpired: execOpts.allowExpired }, { keysFlag: '--keys', allowExpiredFlag: '--allow-expired' });
-                secretEnv = await remoteResolveEnv(await resolveSshTarget(execOpts.host), bundleName, { osLookupName: execOpts.host });
+                secretEnv = await remoteResolveEnv(await resolveHostSshTarget(execOpts.host), bundleName, { osLookupName: execOpts.host });
             }
             else {
                 const { readAndResolveBundleEnv } = await import('../lib/secrets/bundles.js');
@@ -2052,7 +2075,7 @@ Examples:
             const unlockArgs = buildRemoteUnlockArgs(names, opts);
             let failures = 0;
             for (const h of hosts) {
-                const target = await resolveSshTarget(h);
+                const target = await resolveHostSshTarget(h);
                 // FOREGROUND stream (stdio inherited), NOT the piped remoteSecretsRaw:
                 // the remote's passphrase prompt only surfaces if the remote process
                 // sees a real TTY, which requires our local terminal to pass straight

package/dist/commands/sessions-browser.js

@@ -214,7 +214,7 @@ function helpFor(_f, mode) {
     if (mode === 'search') {
         return 'type to filter · ↑↓ navigate · esc exit search · ⏎ resume';
     }
-    return 's search · r running · c teams · a agent · d device · p project · w window · y copy-cmd · ⏎ resume · esc quit';
+    return 's search · r running · c teams · a agent · d device · p project · w window · tab preview · y copy-cmd · ⏎ resume · esc quit';
 }
 /**
  * Launch the interactive session browser. `initial` seeds the filter (e.g.

package/dist/commands/sessions-export.js

@@ -20,7 +20,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
-import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+import { discoverSessions, resolveSessionById, isCompleteSessionId } from '../lib/session/discover.js';
+import { findSessionsById } from '../lib/session/db.js';
 import { filterSessionsByQuery, parseAgentFilter } from './sessions.js';
 import { listLocalTranscripts, SYNC_AGENTS } from '../lib/session/sync/agents.js';
 import { machineId } from '../lib/machine-id.js';
@@ -228,16 +229,29 @@ function selectSessions(metas, selectors) {
     const byId = [];
     const unmatched = [];
     for (const sel of selectors) {
-        const hits = resolveSessionById(metas, sel);
-        if (hits.length > 0)
-            byId.push(...hits);
+        const trimmed = sel.trim();
+        // Same reason as resolveSessionQuery: the discovered pool is a minority of
+        // the index, so a complete id absent from it may still be indexed here.
+        const hits = resolveSessionById(metas, trimmed);
+        const resolved = hits.length > 0 || !isCompleteSessionId(trimmed) ? hits : findSessionsById(trimmed);
+        if (resolved.length > 0)
+            byId.push(...resolved);
         else
-            unmatched.push(sel);
+            unmatched.push(trimmed);
     }
     if (byId.length > 0 && unmatched.length === 0) {
         const seen = new Set();
         return byId.filter(s => (seen.has(s.id) ? false : (seen.add(s.id), true)));
     }
+    // A selector that is a COMPLETE session id and still missed cannot be widened:
+    // the id is unique, so the text query below could only bundle sessions that
+    // merely mention it. Bundling those would ship unrelated transcripts to
+    // whoever receives the export, so select nothing and let the caller report it.
+    const missingIds = unmatched.filter(isCompleteSessionId);
+    if (missingIds.length > 0) {
+        process.stderr.write(chalk.red(`No session with id ${missingIds.join(', ')} on this machine.\n`));
+        return [];
+    }
     // Any selector that isn't an id → treat the whole thing as a text query.
     return filterSessionsByQuery(metas, selectors.join(' '));
 }