@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/commands/secrets-passthrough.js

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { buildServeEnv, invocation, resolveSecretsBin, SecretsClientError } from '../lib/secrets-client.js';
+const INSTALL_HINT = 'npm i -g @phnx-labs/secrets-cli';
+export function registerSecretsCommands(program) {
+    program
+        .command('secrets')
+        .description('Named bundles of env variables — passthrough to the standalone `secrets` CLI. Run `agents secrets --help` (or `agents setup secrets`) for the full subcommand list.')
+        .allowUnknownOption()
+        .allowExcessArguments()
+        // Hand `-h`/`--help` through too — the real subcommand help lives in the
+        // installed `secrets` binary, not in this passthrough.
+        .helpOption(false)
+        .action(() => {
+        let bin;
+        try {
+            bin = resolveSecretsBin();
+        }
+        catch (err) {
+            if (err instanceof SecretsClientError && err.code === 'SECRETS_BIN_MISSING') {
+                console.error(chalk.red('The standalone `secrets` CLI is not installed.'));
+                console.error(chalk.gray(`Install it, then re-run this command:`));
+                console.error(chalk.cyan(`  ${INSTALL_HINT}`));
+                process.exit(1);
+            }
+            throw err;
+        }
+        // Everything after the literal `secrets` token on the real argv — the
+        // subcommand + its own flags, verbatim, never re-parsed by commander.
+        const secretsIndex = process.argv.indexOf('secrets');
+        const forwarded = secretsIndex >= 0 ? process.argv.slice(secretsIndex + 1) : [];
+        const { command, prefix } = invocation(bin);
+        const res = spawnSync(command, [...prefix, ...forwarded], {
+            stdio: 'inherit',
+            env: buildServeEnv(),
+        });
+        if (res.error) {
+            console.error(chalk.red(`Failed to run \`secrets\`: ${res.error.message}`));
+            process.exit(1);
+        }
+        process.exit(res.status ?? 1);
+    });
+}

package/dist/commands/setup-accounts.d.ts

@@ -1,7 +1,8 @@
 /**
  * `agents setup accounts` — mint a Claude setup-token so unattended usage/probe
- * is not stuck on "usage pending". Delegates to the same mint engine as
- * `agents accounts mint` / `agents auth mint`.
+ * is not stuck on "usage pending". Delegates to the same mint engine as the
+ * mint step of `agents accounts add claude [name]` /
+ * `agents accounts login claude#<name>`.
  */
 import type { Command } from 'commander';
 export declare function runAccountsSetupWizard(): Promise<void>;

package/dist/commands/setup-accounts.js

@@ -6,13 +6,13 @@ export async function runAccountsSetupWizard() {
     const status = hasMintedSetupToken();
     if (status.ready) {
         console.log(chalk.green(`Setup-token already minted (${status.detail}).`));
-        console.log(chalk.gray('Re-mint with: agents accounts mint claude'));
+        console.log(chalk.gray('Re-mint with: agents accounts login claude#<name>'));
         return;
     }
     if (!isInteractiveTerminal()) {
         console.log(chalk.yellow('No Claude setup-token on this machine.'));
-        console.log(chalk.gray('Mint one with: agents accounts mint claude'));
-        console.log(chalk.gray('Already have a token: agents accounts mint claude --token-stdin'));
+        console.log(chalk.gray('Mint one with: agents accounts add claude [name]'));
+        console.log(chalk.gray('Already have a token: agents accounts add claude [name]'));
         process.exitCode = 1;
         return;
     }
@@ -21,7 +21,7 @@ export async function runAccountsSetupWizard() {
         default: true,
     });
     if (!proceed) {
-        console.log(chalk.gray('Skipped. Run `agents accounts mint claude` when ready.'));
+        console.log(chalk.gray('Skipped. Run `agents accounts add claude [name]` when ready.'));
         return;
     }
     const result = await mintAndSeed({ harness: 'claude' });

package/dist/commands/setup-secrets.d.ts

@@ -1,28 +1,23 @@
 /**
- * `agents setup secrets` — guided defaults for `agents secrets` onboarding.
+ * `agents setup secrets` — install guidance for the standalone `secrets` CLI,
+ * then a pass-through to its own `secrets migrate` onboarding (PHNX-3989).
  *
- * The wizard writes setup preferences and delegates imports to the existing
- * `agents secrets import` command, keeping bundle storage as the source of truth.
+ * The wizard that used to pick a default backend/policy and delegate imports
+ * lived entirely against the in-repo secrets engine. That engine is extracted
+ * to `@phnx-labs/secrets-cli`, which owns its own interactive onboarding
+ * (`secrets migrate`) — agents-cli never rebundles it (DIST-1), so there is no
+ * in-process fallback when it isn't installed: this command names the install
+ * command and stops.
  */
 import type { Command } from 'commander';
-import type { SecretsPolicy } from '../lib/secrets/bundles.js';
-interface SetupSecretsOptions {
-    backend?: string;
-    policy?: string;
-    importFrom?: string;
-    bundle?: string;
-    vault?: string;
-    iUnderstand?: boolean;
-    force?: boolean;
-}
 export declare function setupSecretsPrefsPath(): string;
-/** The wizard's `--policy` shares the canonical parser with `agents secrets
- * policy`, so it accepts `hold` (and the `daily`/`session` aliases) rather than
- * carrying its own copy that knows only the retired vocabulary. `parsePolicyOpt`
- * defaults an absent value to `always`; the wizard's own default is `hold`, so
- * it is supplied here rather than inherited. */
-export declare function parsePolicy(raw: string | undefined): SecretsPolicy;
-export declare function runSecretsSetupWizard(opts?: SetupSecretsOptions): Promise<boolean>;
+/** True when the standalone `secrets` executable resolves ($SECRETS_BIN or PATH). */
+export declare function isSecretsCliInstalled(): boolean;
+/**
+ * Print install guidance when the standalone is missing, else hand off to its
+ * own interactive `secrets migrate`. Returns whether setup is now complete
+ * (installed, and — when it ran — `migrate` exited 0).
+ */
+export declare function runSecretsSetupWizard(): Promise<boolean>;
 /** Register `agents setup secrets` under the parent `setup` command. */
 export declare function registerSetupSecretsCommand(setupCmd: Command): void;
-export {};

package/dist/commands/setup-secrets.js

@@ -1,249 +1,68 @@
 /**
- * `agents setup secrets` — guided defaults for `agents secrets` onboarding.
+ * `agents setup secrets` — install guidance for the standalone `secrets` CLI,
+ * then a pass-through to its own `secrets migrate` onboarding (PHNX-3989).
  *
- * The wizard writes setup preferences and delegates imports to the existing
- * `agents secrets import` command, keeping bundle storage as the source of truth.
+ * The wizard that used to pick a default backend/policy and delegate imports
+ * lived entirely against the in-repo secrets engine. That engine is extracted
+ * to `@phnx-labs/secrets-cli`, which owns its own interactive onboarding
+ * (`secrets migrate`) — agents-cli never rebundles it (DIST-1), so there is no
+ * in-process fallback when it isn't installed: this command names the install
+ * command and stops.
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'node:child_process';
-import { getCliLaunch } from '../lib/cli-entry.js';
-import { getHistoryDir, updateMeta } from '../lib/state.js';
-import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-import { parsePolicyOpt } from './secrets.js';
-function defaultBackendForPlatform(platform = process.platform) {
-    return platform === 'darwin' ? 'keychain' : 'file';
-}
+import { getHistoryDir } from '../lib/state.js';
+import { resolveSecretsBin, invocation, SecretsClientError } from '../lib/secrets-client.js';
+const INSTALL_HINT = 'npm i -g @phnx-labs/secrets-cli';
 export function setupSecretsPrefsPath() {
     return path.join(getHistoryDir(), 'setup', 'secrets.json');
 }
-function parseBackend(raw) {
-    const value = (raw ?? defaultBackendForPlatform()).toLowerCase();
-    if (value === 'keychain' || value === 'file' || value === 'vault')
-        return value;
-    throw new Error(`Invalid --backend '${raw}'. Use keychain, file, or vault.`);
-}
-/** The wizard's `--policy` shares the canonical parser with `agents secrets
- * policy`, so it accepts `hold` (and the `daily`/`session` aliases) rather than
- * carrying its own copy that knows only the retired vocabulary. `parsePolicyOpt`
- * defaults an absent value to `always`; the wizard's own default is `hold`, so
- * it is supplied here rather than inherited. */
-export function parsePolicy(raw) {
-    return parsePolicyOpt(raw ?? 'hold');
-}
-function parseImportSource(raw) {
-    const value = (raw ?? 'none').toLowerCase();
-    if (value === 'none' || value === 'env' || value === '1password' || value === 'icloud')
-        return value;
-    throw new Error(`Invalid --import-from '${raw}'. Use none, env, 1password, or icloud.`);
-}
-function hasCommand(command) {
-    const res = spawnSync(command, ['--version'], { stdio: 'ignore', windowsHide: true });
-    return !res.error;
-}
-function saveSetupSecretsPrefs(prefs) {
-    const file = setupSecretsPrefsPath();
-    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-    fs.writeFileSync(file, JSON.stringify(prefs, null, 2) + '\n', { mode: 0o600 });
-    return file;
-}
-function applySecretsDefaults(backend, policy) {
-    updateMeta((meta) => ({
-        ...meta,
-        secrets: {
-            ...meta.secrets,
-            backend,
-            ...(policy === 'never' ? {} : { policy }),
-        },
-    }));
-}
-function backendArgs(backend) {
-    return backend === 'vault' ? ['--synced'] : ['--backend', backend];
-}
-/**
- * Provision the signed macOS keychain broker on the explicit onboarding path.
- * This is the async, download-capable trigger the hot sync `getKeychainHelperPath()`
- * fails loud toward: with a bundled `.app` it is a local copy (no network); on a
- * tarball that lacks the bundle it fetches the verified release asset. Best-effort
- * — the wizard's saved prefs must survive an offline provision failure; the next
- * secret op re-points here.
- */
-async function maybeProvisionKeychainHelper(backend) {
-    if (backend !== 'keychain' || process.platform !== 'darwin')
-        return;
-    const { ensureKeychainHelperInstalledAsync } = await import('../lib/secrets/install-helper.js');
+/** True when the standalone `secrets` executable resolves ($SECRETS_BIN or PATH). */
+export function isSecretsCliInstalled() {
     try {
-        await ensureKeychainHelperInstalledAsync();
-        console.log(chalk.gray('keychain helper: installed the signed broker for this version.'));
+        resolveSecretsBin();
+        return true;
     }
     catch (err) {
-        console.error(chalk.yellow(`keychain helper not installed: ${err.message}\n` +
-            'Re-run `agents setup secrets` once online, or reinstall agents-cli.'));
-    }
-}
-function printBackendNotes(backend) {
-    if (backend === 'keychain') {
-        console.log(chalk.gray('backend: keychain — macOS reads may ask for Touch ID or the device password.'));
-    }
-    else if (backend === 'file') {
-        console.log(chalk.gray('backend: file — encrypted at rest; headless reads need no passphrase by default, via a machine-local key at ~/.agents/.secrets-key/passphrase.'));
-    }
-    else {
-        console.log(chalk.gray('backend: vault — synced ~/.agents/vault.age storage; unlock it with `agents secrets vault unlock`.'));
-    }
-}
-function runAgentsSubcommand(args) {
-    const launch = getCliLaunch(args);
-    const res = spawnSync(launch.command, launch.args, { stdio: 'inherit', env: process.env });
-    if ((res.status ?? 1) !== 0) {
-        throw new Error(`agents ${args.join(' ')} failed with exit ${res.status ?? 1}.`);
+        if (err instanceof SecretsClientError && err.code === 'SECRETS_BIN_MISSING')
+            return false;
+        throw err;
     }
 }
-async function maybeImportSecrets(source, opts) {
-    if (source === 'none')
-        return;
-    let bundle = opts.bundle;
-    if (!bundle) {
-        if (!isInteractiveTerminal()) {
-            throw new Error(`--bundle is required with --import-from ${source} in a non-interactive shell.`);
-        }
-        const { input } = await import('@inquirer/prompts');
-        bundle = await input({
-            message: 'Import into which bundle?',
-            default: 'default',
-            validate: (v) => (v.trim().length > 0 ? true : 'Enter a bundle name.'),
-        });
-    }
-    const args = ['secrets', 'import', bundle, ...backendArgs(opts.backend)];
-    if (opts.force)
-        args.push('--force');
-    if (source === 'env') {
-        let envPath = opts.vault;
-        if (!envPath) {
-            if (!isInteractiveTerminal()) {
-                throw new Error('--vault must name the .env path when --import-from env is used non-interactively.');
-            }
-            const { input } = await import('@inquirer/prompts');
-            envPath = await input({
-                message: '.env file path',
-                default: '.env',
-                validate: (v) => (v.trim().length > 0 ? true : 'Enter a .env path.'),
-            });
-        }
-        args.push('--from', envPath);
-    }
-    else if (source === '1password') {
-        const vault = opts.vault;
-        if (!vault)
-            throw new Error('--vault <name> is required with --import-from 1password.');
-        args.push('--from', `1password:${vault}`);
-    }
-    else {
-        args.push('--from', 'icloud');
-    }
-    runAgentsSubcommand(args);
-}
-async function resolveInteractiveChoices(opts) {
-    if (!isInteractiveTerminal()) {
-        return {
-            backend: parseBackend(opts.backend),
-            policy: parsePolicy(opts.policy),
-            importSource: parseImportSource(opts.importFrom),
-        };
-    }
-    const { select } = await import('@inquirer/prompts');
-    const backend = opts.backend ? parseBackend(opts.backend) : await select({
-        message: 'Default secrets backend',
-        default: defaultBackendForPlatform(),
-        choices: [
-            { name: 'keychain — local OS keychain; reads may ask for Touch ID/device password', value: 'keychain' },
-            { name: 'file — passphrase-encrypted file store for headless machines', value: 'file' },
-            { name: 'vault — synced ~/.agents/vault.age file; requires `agents secrets vault unlock`', value: 'vault' },
-        ],
-    });
-    const policy = opts.policy ? parsePolicy(opts.policy) : await select({
-        message: 'Default prompt policy',
-        default: 'hold',
-        choices: [
-            { name: 'hold — ask once, then hold for the configured window (7 days by default)', value: 'hold' },
-            { name: 'always — ask on every read', value: 'always' },
-            { name: 'never — no biometry ACL; use only for automation-only bundles', value: 'never' },
-        ],
-    });
-    const importChoices = [
-        { name: 'skip import', value: 'none' },
-        { name: 'import from .env file', value: 'env' },
-        ...(hasCommand('op') ? [{ name: 'import from 1Password vault', value: '1password' }] : []),
-        { name: 'import legacy iCloud Keychain bundles', value: 'icloud' },
-    ];
-    const importSource = opts.importFrom ? parseImportSource(opts.importFrom) : await select({
-        message: 'Import existing secrets now?',
-        default: 'none',
-        choices: importChoices,
-    });
-    return { backend, policy, importSource };
-}
-function printOnboardingSummary(backend, policy, prefsFile) {
-    console.log(chalk.bold('\nSecrets setup saved.'));
-    console.log(chalk.gray(`preferences: ${prefsFile}`));
-    printBackendNotes(backend);
-    if (policy === 'never') {
-        console.log(chalk.yellow('policy: never is saved as a setup preference; create automation-only bundles with --policy never --i-understand.'));
-    }
-    else {
-        console.log(chalk.gray(`policy: ${policy} — used by bundles that do not set their own policy.`));
-    }
-    console.log(chalk.bold('\nTry:'));
-    console.log(chalk.cyan(`  agents secrets create prod ${backendArgs(backend).join(' ')} --policy ${policy === 'never' ? 'hold' : policy}`));
-    console.log(chalk.cyan('  agents secrets add prod API_KEY'));
-    console.log(chalk.cyan('  agents run claude "deploy" --secrets prod'));
+function recordSetupComplete() {
+    const file = setupSecretsPrefsPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, JSON.stringify({ updatedAt: new Date().toISOString() }, null, 2) + '\n', { mode: 0o600 });
 }
-export async function runSecretsSetupWizard(opts = {}) {
-    const { backend, policy, importSource } = await resolveInteractiveChoices(opts);
-    if (policy === 'never' && !opts.iUnderstand && !isInteractiveTerminal()) {
-        throw new Error("Refusing to save policy 'never' non-interactively without --i-understand.");
+/**
+ * Print install guidance when the standalone is missing, else hand off to its
+ * own interactive `secrets migrate`. Returns whether setup is now complete
+ * (installed, and — when it ran — `migrate` exited 0).
+ */
+export async function runSecretsSetupWizard() {
+    if (!isSecretsCliInstalled()) {
+        console.log(chalk.yellow('The standalone `secrets` CLI is not installed.'));
+        console.log(chalk.gray('Install it, then re-run `agents setup secrets`:'));
+        console.log(chalk.cyan(`  ${INSTALL_HINT}`));
+        return false;
     }
-    applySecretsDefaults(backend, policy);
-    const prefsFile = saveSetupSecretsPrefs({
-        defaultBackend: backend,
-        defaultPolicy: policy,
-        updatedAt: new Date().toISOString(),
-    });
-    // Provision the signed keychain broker before any import subprocess reads it.
-    await maybeProvisionKeychainHelper(backend);
-    await maybeImportSecrets(importSource, {
-        bundle: opts.bundle,
-        vault: opts.vault,
-        backend,
-        force: opts.force,
-    });
-    printOnboardingSummary(backend, policy, prefsFile);
-    return true;
+    const bin = resolveSecretsBin();
+    const { command, prefix } = invocation(bin);
+    const res = spawnSync(command, [...prefix, 'migrate'], { stdio: 'inherit' });
+    const ok = (res.status ?? 1) === 0;
+    if (ok)
+        recordSetupComplete();
+    return ok;
 }
 /** Register `agents setup secrets` under the parent `setup` command. */
 export function registerSetupSecretsCommand(setupCmd) {
     setupCmd
         .command('secrets')
-        .description('Configure `agents secrets` defaults and optionally import existing secrets.')
-        .option('--backend <backend>', 'default backend: keychain, file, or vault')
-        .option('--policy <policy>', "default prompt policy: hold, always, or never ('daily'/'session' are accepted aliases for 'hold')")
-        .option('--import-from <source>', 'optional import source: none, env, 1password, or icloud')
-        .option('--bundle <name>', 'bundle name for optional imports')
-        .option('--vault <name-or-path>', '1Password vault name, or .env path with --import-from env')
-        .option('--i-understand', 'allow saving the "never" policy preference without an interactive prompt')
-        .option('--force', 'pass --force through to optional imports')
-        .action(async (options) => {
-        try {
-            await runSecretsSetupWizard(options);
-        }
-        catch (err) {
-            if (isPromptCancelled(err)) {
-                console.log(chalk.yellow('\nCancelled'));
-                return;
-            }
-            console.error(chalk.red(err.message));
+        .description('Install guidance for the standalone `secrets` CLI, then run its own `secrets migrate` onboarding.')
+        .action(async () => {
+        if (!(await runSecretsSetupWizard()))
             process.exitCode = 1;
-        }
     });
 }

package/dist/commands/ssh.js

@@ -16,7 +16,7 @@ import * as path from 'path';
 import chalk from 'chalk';
 import ora from 'ora';
 import { getCliVersion } from '../lib/version.js';
-import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
+import { readAndResolveBundleEnv } from '../lib/secrets-client.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { assertRegistrableDeviceName } from '../lib/devices/registry.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../lib/smart-launch.js';
@@ -2766,7 +2766,7 @@ async function runAskpass() {
     // render load/mem for an uncached password-auth device (RUSH-1970).
     const agentOnly = true;
     try {
-        const { env } = readAndResolveBundleEnv(bundle, { caller: 'agents ssh', keys: [key], keyMode: 'storage', agentOnly });
+        const { env } = await readAndResolveBundleEnv(bundle, { caller: 'agents ssh', keys: [key], keyMode: 'storage', agentOnly });
         const value = env[key];
         if (value === undefined) {
             console.error(`askpass: key '${key}' not found in bundle '${bundle}'`);

package/dist/commands/sync.js

@@ -33,7 +33,7 @@
 import * as path from 'path';
 import { Option } from 'commander';
 import chalk from 'chalk';
-import { resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
+import { resolveSyncPassphraseFromEnv } from '../lib/sync-passphrase.js';
 import { agentLabel, resolveAgentName, MANAGED_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { autoEvictCentralBrowserProfiles } from '../lib/browser/registry.js';
 import { shouldAutoClaimCentralProfile } from '../lib/browser/profiles.js';

package/dist/commands/update.d.ts

@@ -1,2 +1,12 @@
 import type { Command } from 'commander';
+import type { AgentId } from '../lib/types.js';
+/**
+ * One line naming the installations a bare `agents update <agent>` did NOT
+ * touch — isolated (`--isolated`) copies and legacy pre-v2 per-version homes —
+ * or `null` when the managed install is the only one. Bare `<agent>` moves only
+ * the single managed install, so leaving these silent would let a user believe
+ * every copy is current (PHNX-3940). Pure over the installation store so the
+ * naming logic is unit-testable without running a real update.
+ */
+export declare function describeSkippedInstallations(agent: AgentId, managedId: string): string | null;
 export declare function registerUpdateCommand(program: Command): void;

package/dist/commands/update.js

@@ -1,7 +1,8 @@
 import chalk from 'chalk';
 import { AGENTS, formatAgentError, resolveAgentName } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
-import { describeInstallation, effectiveUpdatePolicy, listInstallations, planAutoUpdates, resolveInstallation, runAutoUpdatePass, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
+import { describeInstallation, listInstallations, planAutoUpdates, resolveInstallation, runAutoUpdatePass, selectUpdateStrategy, supportsPinnedUpdate, updateInstallation, } from '../lib/installations/index.js';
+import { resolveManagedInstallation } from '../lib/installations/index.js';
 /**
  * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
  * label, or the release it currently carries — never a release to install; that
@@ -20,6 +21,22 @@ function parseTarget(raw) {
         throw new Error(formatAgentError(name));
     return { agent, selector };
 }
+/**
+ * One line naming the installations a bare `agents update <agent>` did NOT
+ * touch — isolated (`--isolated`) copies and legacy pre-v2 per-version homes —
+ * or `null` when the managed install is the only one. Bare `<agent>` moves only
+ * the single managed install, so leaving these silent would let a user believe
+ * every copy is current (PHNX-3940). Pure over the installation store so the
+ * naming logic is unit-testable without running a real update.
+ */
+export function describeSkippedInstallations(agent, managedId) {
+    const skipped = listInstallations(agent).filter((i) => i.id !== managedId);
+    if (skipped.length === 0)
+        return null;
+    const names = skipped.map((i) => `${agent}@${describeInstallation(i)}`).join(', ');
+    return `Left ${skipped.length} other ${AGENTS[agent].name} installation${skipped.length === 1 ? '' : 's'} unchanged `
+        + `(${names}). Update one with: agents update ${agent}@<label>.`;
+}
 function serialize(installation) {
     return {
         id: installation.id,
@@ -65,7 +82,7 @@ function printInstallations(agent, json) {
         return;
     }
     if (!installations.length) {
-        console.log(chalk.gray(`No managed ${agent} installations. Install one with: agents add ${agent}@latest`));
+        console.log(chalk.gray(`No managed ${agent} installations. Install one with: agents add ${agent}`));
         return;
     }
     console.log(chalk.bold(`${agent} installations\n`));
@@ -222,35 +239,21 @@ export function registerUpdateCommand(program) {
                 printOutcome(outcome, !!options.json);
                 return;
             }
-            // Bare `<agent>`, no `@label`: act on every installation of that agent
-            // that isn't explicitly pinned — the bulk case. A single installation
-            // keeps the old single-target behavior even if it happens to be pinned,
-            // since naming the agent with only one installed copy is unambiguous
-            // about which one is meant; `--to` still applies to it either way.
-            const installations = listInstallations(agent);
-            if (installations.length === 0) {
-                throw new Error(`No ${AGENTS[agent].name} installations are managed by agents-cli. Install one with: agents add ${agent}@latest`);
+            // Bare `<agent>`, no `@label`: update the harness's ONE managed
+            // installation (PHNX-3940). The `@<label>` selector above remains for
+            // legacy multi-install layouts and isolated copies; the automatic pass
+            // (`--auto`, the daemon) still sweeps every installation by policy.
+            const managed = resolveManagedInstallation(agent);
+            if (!managed) {
+                throw new Error(`No managed ${AGENTS[agent].name} installation. Install one with: agents add ${agent}`);
             }
-            const targets = installations.length === 1
-                ? installations
-                : installations.filter((i) => effectiveUpdatePolicy(i) !== 'pinned');
-            if (installations.length > 1 && targets.length === 0) {
-                throw new Error(`Every ${AGENTS[agent].name} installation is pinned to a concrete release. `
-                    + `Select one explicitly: agents update ${agent}@<label> --to latest`);
-            }
-            let anyError = false;
-            for (const installation of targets) {
-                try {
-                    const outcome = await updateOne(agent, installation, options);
-                    printOutcome(outcome, !!options.json);
-                }
-                catch (err) {
-                    anyError = true;
-                    fail(err);
-                }
+            const outcome = await updateOne(agent, managed, options);
+            printOutcome(outcome, !!options.json);
+            if (!options.json) {
+                const skippedLine = describeSkippedInstallations(agent, managed.id);
+                if (skippedLine)
+                    console.log(chalk.gray(skippedLine));
             }
-            if (anyError)
-                process.exitCode = 1;
         }
         catch (err) {
             fail(err);
@@ -275,21 +278,21 @@ export function registerUpdateCommand(program) {
         }
     });
     setHelpSections(update, {
-        examples: `agents update list claude
-agents update claude@2.0.65
-agents update claude@2.0.65 --to 2.1.220
-agents update claude@2.0.65 --to latest
-agents update claude
+        examples: `agents update claude
+agents update claude --to 2.1.220
+agents update claude --to latest
+agents update list claude
 agents update --check
 agents update claude --check --json
 agents update --auto`,
-        notes: 'An installation keeps its name for life; only the release inside it moves. That is why a default, a project pin, '
-            + 'a routine version, or a profile that names claude@2.0.65 keeps working after you update it. '
-            + 'The selector matches either the installation name or the release it currently carries — when two installations '
-            + 'share a release, select one by its installation name. '
+        notes: 'One managed installation per harness: a bare `<agent>` updates that installation, keeping its name and every '
+            + 'reference to it. That is why a default, a project pin, a routine version, or a profile that names claude@main '
+            + 'keeps working after you update it. '
+            + '`--to <release>` pins the installation to a concrete release (excluded from the automatic pass), `--to latest` '
+            + 'unpins it. The legacy `agents update <agent>@<label>` selector still addresses a specific installation by its '
+            + 'name or the release it currently carries, for pre-v2 layouts with several installations. '
             + 'The new release is fetched and launched before it replaces the working one, so a bad release leaves your agent running. '
-            + 'A bare `<agent>` (no @label) updates every one of its installations that is not pinned; `--to <release>` pins the '
-            + 'installations it touches, `--to latest` unpins them. Pinned and manual/vendor-managed installations are also skipped '
+            + 'Pinned and manual/vendor-managed installations are also skipped '
             + 'by the automatic background pass (agents config set updates.auto / updates.<agent>.auto). `--check` reports what '
             + '`--auto` would do without changing anything; `--auto` (no target) runs the exact pass the daemon runs, across every '
             + 'harness.',

package/dist/commands/versions.d.ts

@@ -7,16 +7,16 @@
  * switching, resource sync prompts, and project-level version pinning.
  */
 import type { Command } from 'commander';
-/** Bare installs reuse an account home; explicit labels keep their expert semantics. */
-export declare function planAccountFirstInstall(input: {
-    spec: string;
-    supported: boolean;
-    isolated: boolean;
-    labels: string[];
-    defaultLabel: string | null;
-}): {
-    existingLabel?: string;
-    installationLabel?: string;
-};
+/**
+ * What `agents add <spec>` does with the harness's ONE managed installation
+ * (PHNX-3940): with no managed install it installs one (label `main`); with
+ * one, a bare spec reuses it and an explicit `@<release>` pins that same
+ * install — exactly `agents update <agent> --to <release>`. A second home is
+ * only ever an `--isolated` copy, which bypasses this plan entirely.
+ */
+export declare function planManagedAdd(input: {
+    explicitPin: boolean;
+    managedInstalled: boolean;
+}): 'reuse' | 'pin' | 'install';
 /** Register `agents add`, `agents prune`, `agents remove`, and `agents use`. */
 export declare function registerVersionsCommands(program: Command): void;