@phnx-labs/agents-cli 1.22.78 → 1.22.79

package/CHANGELOG.md

@@ -1,9 +1,20 @@
 # Changelog
 
+## 1.22.79
+
+- **Managed harnesses follow the latest release without replacing account homes (PHNX-3940).** Automatic updates are on by default and configurable with `updates.auto` and per-harness `updates.<harness>.auto`. Updates preserve existing home paths and identities, defer active installations, and stage and verify the executable before committing it. A concrete `--to` release pins an installation; `--to latest` resumes automatic updates. `agents update --check` previews without changing local state. Source: `cli/src/lib/installations/update.ts`, `cli/src/lib/daemon/harness-update-service.ts`, `cli/src/commands/update.ts`.
+- **`agents accounts connect <harness> [name]` — stable accounts independent of releases (PHNX-3940).** A new account gets a fresh opaque installation label with its own isolated home, installs the current release into it (even when that release is already installed under another label), and drives the harness's native OAuth login there — the credential is never copied or fleet-synced. Reconnecting an existing account by name reuses that account's home and refuses to bind a different identity after login. Supported for the version-scoped, isolable harnesses (claude, codex first); others refuse with a clear reason instead of faking a flow. Source: `cli/src/lib/accounts/connect.ts`, `cli/src/commands/accounts.ts`.
+- **`agents accounts logout` honors `@label` / `#account` selectors (PHNX-3940).** `agents accounts logout claude@<label>`, `claude#<account>`, or a bare native account name now signs out that exact home instead of always selecting the global default, and the sign-out runs under the harness's canonical config-dir env (CLAUDE_CONFIG_DIR / CODEX_HOME) rather than HOME alone. Source: `cli/src/commands/accounts.ts`.
+- **Account-first read model for `agents accounts` / `view` (PHNX-3940).** `loadAccountCatalog()` / `buildNativeCatalog()` group installed homes by identity and derive a live connection state — a registered account whose homes are all signed out reads `reconnect-needed`, never a bare `connected` on the registry label alone — with the release/home kept as secondary diagnostics. Source: `cli/src/lib/account-catalog.ts`.
+- **`installVersion` accepts an `installationLabel` independent of the release (PHNX-3940).** The npm install path can now stage the current release under an opaque label distinct from the version string, so many accounts can share one upstream `latest` under separate isolated homes; the frozen installation record keeps label and `releaseVersion` separate. Source: `cli/src/lib/installations/versions.ts`.
+- **`agents accounts connect` allocates account homes safely — no cross-account overwrite (PHNX-3940 security fix).** Connect slots are now RANDOM opaque labels allocated to be disjoint from every home already owned by an account or currently signed in, so `connect work` after `work` was renamed `personal` can never land on and overwrite `personal`'s login. Retry-idempotency is provided by a device-scoped pending-connect map (cleared on success), not a name-derived slot. Connection state is now strict — a live credential in the home, not a bare metadata identity, so a stale/expired login reads `reconnect-needed`. A first connect selects the harness default only when none is configured, and an unnamed connect forces no name (it returns a hint to name the login). Source: `cli/src/lib/accounts/connect.ts`, `cli/src/lib/account-registry.ts`, `cli/src/lib/account-catalog.ts`, `cli/src/lib/state.ts`.
+
 ## 1.22.78
 
 - **The launch env carries the human's Phoenix ID profile picture.** A resolved human actor now gets `AGENTS_ACTOR_AVATAR` (https URL) when the Phoenix ID session signed in on the device belongs to the same email, so tools an agent runs — `artifacts render`, shares — can show the person instead of initials. A shared box signed in as someone else lends nothing to whoever SSH-ed in, and a child spawn inherits the value like the rest of `AGENTS_ACTOR*`. `agents auth whoami` now also refreshes the persisted picture from `/api/v1/auth/me`, which Phoenix ID returns as of phnx-labs/phoenix-id#7. Source: `cli/src/lib/actor.ts`, `cli/src/commands/auth.ts`.
 
+## 1.22.77
+
 - **`agents repo pull` / `agents sync` no longer wedge on a CLI-regenerated `~/.agents/agents.yaml` (PHNX-3968).** The shared central config was rewritten by config commands without being committed, so between the daemon's publish ticks the tree sat dirty on `agents.yaml`; an incoming peer commit that also touched it made the pull refuse with *"incoming changes touch uncommitted paths: agents.yaml"*, forcing manual autostash gymnastics on the fleet. Central config edits are now committed synchronously by the command that makes them (after the meta lock releases, skipped for the daemon whose own publish tick owns its commits), so the tree is clean at rest and the trip cannot occur. A genuinely dirty-and-differing central file now *refuses* the pull (data-safe, self-heals on the next commit) rather than silently taking the remote copy. The user-repo `CHANGELOG.md` (a duplicate of the shipped one) is de-tracked via `.git/info/exclude` so it stops churning the tree. Source: `cli/src/lib/state.ts`, `cli/src/lib/git.ts`, `cli/src/lib/browser/registry.ts`, `cli/src/lib/project-resources.ts`.
 
 ## 1.22.76

package/README.md

@@ -1151,7 +1151,34 @@ Distinct from **Accounts** below: this is *your human identity*; those are the *
 
 ## Accounts
 
-Give a provider credential a durable name once, reuse it everywhere -- across harnesses, across machines.
+Choose an agent and an account, independently of its release number. Connect a
+native account once on this device; its home, login, settings, and sessions stay
+in place when the executable is updated.
+
+```bash
+agents accounts connect codex work
+agents accounts connect claude personal
+agents accounts switch codex work
+agents run codex#work
+agents view codex                 # accounts and usage, one row per identity
+agents view codex --versions      # every retained installation and actual release
+```
+
+Connecting another account creates its own isolated home, even when it uses the
+same release. Reconnecting a named account reuses its existing home. Old
+release-named homes are adopted in place: no credential copying, directory moves,
+or automatic duplicate deletion. Native login remains device-local; an account
+known on another device is not necessarily connected here.
+
+Agents checks for updates to safely managed harness installations automatically.
+Disable this globally or per harness with `agents config set updates.auto false`
+or `agents config set updates.codex.auto false`. Use `agents update codex --check`
+to inspect eligibility without installing, or `agents update codex` to update
+that harness's installations. Running sessions and deliberately pinned
+installations are protected. See [installation and update policy](cli/docs/version-management.md).
+
+For unattended workers, give a **provider credential** a durable name and reuse it
+across supported harnesses and machines:
 
 ```bash
 agents accounts mint claude                  # drive `claude setup-token`, seed a named account + reserved auth bundle

package/dist/bootstrap.js

@@ -108,6 +108,8 @@ const AUDIT_EXEMPT_COMMANDS = new Set([
     '_internal friction',
 ]);
 program.hook('preAction', (_thisCommand, actionCommand) => {
+    if (isReadOnlyUpdatePreview)
+        return;
     try {
         const parts = auditCommandPath(actionCommand);
         if (parts.length === 0)
@@ -130,6 +132,8 @@ program.hook('preAction', (_thisCommand, actionCommand) => {
     }
 });
 program.hook('postAction', (_thisCommand, actionCommand) => {
+    if (isReadOnlyUpdatePreview)
+        return;
     try {
         const parts = auditCommandPath(actionCommand);
         if (parts.length === 0)
@@ -1026,18 +1030,35 @@ if (helpAllRequested) {
     program.outputHelp();
     process.exit(0);
 }
+// `agents update --check` (with or without a <target>) is a pure read-only
+// preview of the automatic-update plan — it reports what `--auto` WOULD do and
+// changes nothing (`planAutoUpdates` reads installation SNAPSHOTS, never
+// mutating disk). So it MUST NOT fire the mutating startup steps every other
+// real command runs: the CLI self-update check + multi-install sentinel, the
+// detached background repo sync, the legacy-fold and migration passes, the
+// macOS menu-bar install, and the interactive shim self-heal — each writes to
+// ~/.agents or a helper dir the user did not ask to touch (PHNX-3940). It is
+// NOT a documentation request: it still parses, resolves installations, and
+// routes over `--device`, so it is gated separately from isDocumentationRequest
+// rather than folded into it (which would also skip the passthrough router).
+// Re-read the command after spell correction, allowing leading root flags.
+const isReadOnlyUpdatePreview = !isDocumentationRequest &&
+    passedArgs.find((arg) => !arg.startsWith('-')) === 'update' &&
+    passedArgs.includes('--check');
 // Pure documentation paths (--version / --help / -h / --help-all) return
 // immediately: skip the update check (PATH scan + cache read) and the detached
 // background sync (spawns a child process) that every other invocation runs.
 if (!isDocumentationRequest) {
     bootMark('bootstrap:evaluated');
-    // Run update check before parsing so the upgrade notice/prompt precedes output.
-    await checkForUpdates();
-    // Fire-and-forget the background sync. System repo gets a real fast-forward
-    // pull (read-only locally, safe). User repo and extras get fetch-only + a
-    // status marker that `agents doctor` surfaces as a repo-behind warning.
-    const { spawnDetachedSync } = await import('./lib/auto-pull.js');
-    spawnDetachedSync();
+    if (!isReadOnlyUpdatePreview) {
+        // Run update check before parsing so the upgrade notice/prompt precedes output.
+        await checkForUpdates();
+        // Fire-and-forget the background sync. System repo gets a real fast-forward
+        // pull (read-only locally, safe). User repo and extras get fetch-only + a
+        // status marker that `agents doctor` surfaces as a repo-behind warning.
+        const { spawnDetachedSync } = await import('./lib/auto-pull.js');
+        spawnDetachedSync();
+    }
 }
 // First-run experience: no args + no config yet + TTY -> launch interactive setup.
 // Skipped when stdin/stdout isn't a terminal (CI, pipes) or when user passes any args.
@@ -1074,7 +1095,7 @@ const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help', 'uninstall']);
 // must not load any migration graph. Loaded from migrate-fold.js (leaf: fs +
 // createLink), not migrate.js, so a real command pays only the fold hop unless
 // the v20 sentinel is missing and runMigration() is required below.
-if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !isDocumentationRequest) {
+if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !isDocumentationRequest && !isReadOnlyUpdatePreview) {
     try {
         const { foldLegacySystemRepo } = await import('./lib/migrate-fold.js');
         foldLegacySystemRepo();
@@ -1084,7 +1105,8 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !isDocumentationRequest) {
 if (!firstRun &&
     requestedCommand &&
     !SETUP_EXEMPT_COMMANDS.has(requestedCommand) &&
-    !isDocumentationRequest) {
+    !isDocumentationRequest &&
+    !isReadOnlyUpdatePreview) {
     const { ensureInitialized } = await import('./commands/setup.js');
     await ensureInitialized(program);
 }
@@ -1101,7 +1123,7 @@ if (!firstRun &&
 // — only a missing/stale sentinel pays for
 // `await import('./lib/installations/migrate.js')` (which pulls the
 // hosts/routine/teams/daemon/menubar graph).
-if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !isDocumentationRequest) {
+if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !isDocumentationRequest && !isReadOnlyUpdatePreview) {
     try {
         const sentinel = getMigratedSentinelPath();
         // Sentinel is keyed to the migration SCHEMA version, not the binary version.
@@ -1141,7 +1163,8 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1' && !isDocumentationRequest) {
 // gate the update check, background sync, and ensureInitialized above already use.
 if (process.platform === 'darwin' &&
     process.env.AGENTS_SKIP_MIGRATION !== '1' &&
-    !isDocumentationRequest) {
+    !isDocumentationRequest &&
+    !isReadOnlyUpdatePreview) {
     try {
         const { installMenubarLaunchAgentOnUpgrade } = await import('./lib/menubar/install-menubar.js');
         installMenubarLaunchAgentOnUpgrade();
@@ -1158,7 +1181,12 @@ if (passedArgs.length === 0) {
     process.exit(0);
 }
 try {
-    await maybeBootstrapShimIntegration(requestedCommand, isDocumentationRequest, verboseStartup);
+    // The shim self-heal regenerates shims / adopts launchers / edits PATH — all
+    // writes, so a read-only `agents update --check` skips it too (same gate as
+    // the migration/menu-bar steps above) while still parsing normally.
+    if (!isReadOnlyUpdatePreview) {
+        await maybeBootstrapShimIntegration(requestedCommand, isDocumentationRequest, verboseStartup);
+    }
     bootMark('bootstrap:pre-parse');
     await program.parseAsync();
 }

package/dist/commands/accounts.d.ts

@@ -53,6 +53,8 @@ export declare function renderAccountList(records: {
     name?: string;
     display: string;
     versions: string[];
+    isDefault?: boolean;
+    state?: 'connected' | 'reconnect-needed';
 }[]): string;
 /** One labelable signed-in identity, folded across every version it is signed into. */
 export interface LabelIdentity {
@@ -102,5 +104,25 @@ export declare function setDefaultAccount(agentRaw: string, name: string): {
 export declare function runAccountsSwitch(harness: string, accountName: string | undefined, opts: {
     json: boolean;
 }): Promise<void>;
+/**
+ * Parse a `logout` target into its parts (pure). Supports `<harness>`,
+ * `<harness>@<label>`, `<harness>#<account>`, and a bare account name (no
+ * harness). `#` binds tighter than `@` so a `<harness>#<label>` selector is
+ * never mis-split on a `@` inside the selector.
+ */
+export declare function parseLogoutTarget(target: string): {
+    agentRaw: string;
+    installationLabel?: string;
+    identitySelector?: string;
+};
+/**
+ * Resolve a `logout` target to the exact `(agent, installed label)` whose home
+ * should be signed out — honoring a passed `@label` or `#account` selector
+ * instead of always selecting the global default (PHNX-3940).
+ */
+export declare function resolveLogoutTarget(target: string): Promise<{
+    agent: AgentId;
+    version: string;
+}>;
 export declare function registerAccountsCommand(program: Command): void;
 export {};

package/dist/commands/accounts.js

@@ -16,11 +16,17 @@ import { pushBundleToHost } from '../lib/secrets/push.js';
 import { assertCredentialTransportHostPinned, resolveHostSshTarget } from '../lib/secrets/remote.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { runDevicesAccounts } from './ssh.js';
-import { discoverNativeAccounts } from '../lib/account-catalog.js';
+import { collectNativeHomeRows, loadAccountCatalog } from '../lib/account-catalog.js';
+import { connectRefusal, connectSupported, runConnect } from '../lib/accounts/connect.js';
+import { acquireAuthOperationLock } from '../lib/accounts/auth-operation-lock.js';
 import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
 import { getAccountProvider, listAccountProviders, providerAuthenticatesHarness } from '../lib/account-provider-registry.js';
-import { accountBindings, addAccount, addNativeAccount, bindAccount, findAccount, findUnifiedAccount, inspectAccount, labelNativeAccount, listNativeAccounts, readAccountRegistry, removeAccount, renameAccount, setAccountSecret, unbindAccount } from '../lib/account-registry.js';
+import { accountBindings, addAccount, addNativeAccount, bindAccount, findAccount, findUnifiedAccount, inspectAccount, labelNativeAccount, listNativeAccounts, nativeAccountHome, readAccountRegistry, removeAccount, renameAccount, setAccountSecret, unbindAccount } from '../lib/account-registry.js';
 import { registerMintCommand } from './auth-mint.js';
+/** Comma-joined list of harnesses `accounts connect` can drive today. */
+function connectSupportedList() {
+    return ALL_AGENT_IDS.filter(connectSupported).join(', ');
+}
 function cleanCommandError(command, err) {
     command.error(err instanceof Error ? err.message : String(err), { exitCode: 1, code: 'accounts.error' });
 }
@@ -142,12 +148,11 @@ async function printAccounts(json, fleet = false) {
     if (fleet)
         return runDevicesAccounts({ json });
     const records = Object.values(readAccountRegistry().accounts).sort((a, b) => a.name.localeCompare(b.name));
-    const discovered = await discoverNativeAccounts();
-    const savedNative = listNativeAccounts(readMeta());
-    const native = discovered.map(row => {
-        const saved = savedNative.find(account => account.agent === row.agent && account.identityKey === row.id);
-        return { ...row, name: saved?.name, id: saved?.id ?? row.id };
-    });
+    const catalog = await loadAccountCatalog();
+    const native = catalog.native.map(row => ({
+        ...row, name: row.name ?? undefined, id: row.id ?? row.identityKey,
+        versions: row.installations.map(home => home.label),
+    }));
     if (json) {
         console.log(JSON.stringify([...records.map(account => publicAccount(inspectAccount(account.name))), ...native], null, 2));
         return;
@@ -160,7 +165,7 @@ export function renderAccountList(records, native) {
     // Native logins, grouped by harness — the selection surface for `<harness>#<label>`.
     out.push(chalk.bold('Native logins') + chalk.gray('     ') + chalk.gray('run <harness>#<label>'));
     if (!native.length) {
-        out.push(chalk.gray('  No signed-in native accounts found.'));
+        out.push(chalk.gray('  No native accounts found. Connect one: agents accounts connect <harness> [name]'));
     }
     else {
         const byHarness = new Map();
@@ -179,11 +184,12 @@ export function renderAccountList(records, native) {
                 const harnessCell = chalk.gray((i === 0 ? harness : '').padEnd(harnessW));
                 const rawLabel = acct.name ?? '—';
                 const labelCell = acct.name ? chalk.cyan(rawLabel.padEnd(labelW)) : chalk.gray(rawLabel.padEnd(labelW));
-                const isDefault = defaultVersion ? acct.versions.includes(defaultVersion) : false;
+                const isDefault = acct.isDefault ?? (defaultVersion ? acct.versions.includes(defaultVersion) : false);
                 if (isDefault)
                     sawDefault = true;
                 const marker = isDefault ? chalk.green('*') : ' ';
-                out.push(`  ${harnessCell}  ${labelCell}${marker} ${acct.display.padEnd(idW)}  ${chalk.gray(acct.versions.join(', '))}`);
+                const state = acct.state === 'reconnect-needed' ? 'not connected here' : 'connected';
+                out.push(`  ${harnessCell}  ${labelCell}${marker} ${acct.display.padEnd(idW)}  ${chalk.gray(state)}`);
             });
         }
         if (sawDefault)
@@ -412,6 +418,85 @@ export async function runAccountsSwitch(harness, accountName, opts) {
     const { account } = setDefaultAccount(agent, selected);
     console.log(chalk.green(`${agent} now uses account '${account.name}' unless --account overrides it.`));
 }
+/**
+ * Parse a `logout` target into its parts (pure). Supports `<harness>`,
+ * `<harness>@<label>`, `<harness>#<account>`, and a bare account name (no
+ * harness). `#` binds tighter than `@` so a `<harness>#<label>` selector is
+ * never mis-split on a `@` inside the selector.
+ */
+export function parseLogoutTarget(target) {
+    const hash = target.indexOf('#');
+    if (hash > 0) {
+        if (!target.slice(hash + 1).trim())
+            throw new Error('Select an account after #.');
+        return { agentRaw: target.slice(0, hash), identitySelector: target.slice(hash + 1) };
+    }
+    const at = target.indexOf('@');
+    if (at > 0) {
+        if (!target.slice(at + 1).trim())
+            throw new Error('Select an installation after @.');
+        return { agentRaw: target.slice(0, at), installationLabel: target.slice(at + 1) };
+    }
+    return { agentRaw: target };
+}
+/** Explicit account logout must never fall back to another account's home. */
+async function resolveAccountHomeLabel(account) {
+    const rows = await collectNativeHomeRows();
+    const homes = rows
+        .filter(r => r.signedIn && (r.accountKey ?? r.email))
+        .map(r => ({ agent: r.agent, identityKey: (r.accountKey ?? r.email.toLowerCase()), label: r.label }));
+    const deviceHome = nativeAccountHome(account.id, readMeta());
+    const matching = homes.filter(home => home.agent === account.agent && home.identityKey === account.identityKey);
+    const label = matching.find(home => home.label === deviceHome)?.label ?? matching[0]?.label;
+    if (!label || !listInstalledVersions(account.agent).includes(label)) {
+        throw new Error(`Account '${account.name}' has no installed ${account.agent} home to sign out of.`);
+    }
+    return label;
+}
+/**
+ * Resolve a `logout` target to the exact `(agent, installed label)` whose home
+ * should be signed out — honoring a passed `@label` or `#account` selector
+ * instead of always selecting the global default (PHNX-3940).
+ */
+export async function resolveLogoutTarget(target) {
+    const parsed = parseLogoutTarget(target);
+    const meta = readMeta();
+    if (ALL_AGENT_IDS.includes(parsed.agentRaw)) {
+        const agent = parsed.agentRaw;
+        if (parsed.installationLabel) {
+            if (!listInstalledVersions(agent).includes(parsed.installationLabel)) {
+                throw new Error(`${agent}@${parsed.installationLabel} is not installed.`);
+            }
+            return { agent, version: parsed.installationLabel };
+        }
+        if (parsed.identitySelector) {
+            const account = findUnifiedAccount(parsed.identitySelector, meta, undefined, agent);
+            if (!account || account.kind !== 'native' || account.agent !== agent) {
+                throw new Error(`No ${agent} account '${parsed.identitySelector}'.`);
+            }
+            return { agent, version: await resolveAccountHomeLabel(account) };
+        }
+        const configuredDefault = meta.accounts?.defaults?.[agent];
+        if (configuredDefault) {
+            const account = findUnifiedAccount(configuredDefault, meta, undefined, agent);
+            if (!account || account.kind !== 'native') {
+                throw new Error(`${agent}'s default is not a locally connected native account. Select the native account to sign out explicitly.`);
+            }
+            return { agent, version: await resolveAccountHomeLabel(account) };
+        }
+        const installed = listInstalledVersions(agent);
+        const version = getGlobalDefault(agent) ?? installed[installed.length - 1];
+        if (!version)
+            throw new Error(`No installed version of ${agent}. Install one with: agents add ${agent}`);
+        return { agent, version };
+    }
+    // A bare, non-harness target may be a native account name.
+    const account = findUnifiedAccount(target, meta);
+    if (account?.kind === 'native') {
+        return { agent: account.agent, version: await resolveAccountHomeLabel(account) };
+    }
+    throw new Error(`Unknown target '${target}'. Pass a native harness (claude, codex, …), <harness>@<label>, <harness>#<account>, or a native account name. Provider API-key accounts use \`agents accounts remove\`.`);
+}
 export function registerAccountsCommand(program) {
     const accounts = program.command('accounts').description('Browse native logins and manage provider account bundles')
         .option('--json', 'Machine-readable account metadata')
@@ -423,6 +508,35 @@ export function registerAccountsCommand(program) {
         await runAccountsAction(command, () => printAccounts(!!(o.json || command.optsWithGlobals().json)));
     });
     registerMintCommand(accounts);
+    const connectCmd = accounts.command('connect <harness> [name]')
+        .description('Connect a stable account: install the current release into a fresh isolated home and drive the harness native login (reconnect an existing account by name to reuse its home)')
+        .option('--json', 'Machine-readable connect result')
+        .action(async (harness, name, o, command) => {
+        await runAccountsAction(command, async () => {
+            const agent = parseHarness(harness);
+            const reason = connectRefusal(agent);
+            if (reason)
+                throw new Error(reason);
+            const result = await runConnect(agent, name, {
+                meta: readMeta(),
+                onProgress: (m) => console.log(chalk.gray(`  ${m}`)),
+            });
+            if (o.json || command.optsWithGlobals().json)
+                return console.log(JSON.stringify(result, null, 2));
+            const who = result.email ?? result.identityKey;
+            const named = result.name ? `'${result.name}' ` : '';
+            const release = result.releaseVersion ? ` [${result.releaseVersion}]` : '';
+            console.log(chalk.green(`${result.mode === 'reconnect' ? 'Reconnected' : 'Connected'} ${agent} account ${named}(${who}) in ${agent}@${result.label}${release}.`));
+            console.log(chalk.gray('  The native OAuth login stays owned by the harness in that home; nothing was copied.'));
+        });
+    });
+    setHelpSections(connectCmd, {
+        examples: `agents accounts connect claude work
+agents accounts connect codex personal
+agents accounts connect claude work   # again → reuses work's home, fails closed on a different identity
+agents run claude --account work`,
+        notes: `Each NEW account gets a fresh opaque installation label and its own isolated home, so ten accounts can share the same upstream release while keeping separate logins. Connect installs the current release even when it is already installed under another label, then launches the harness's native login there — the OAuth credential is never copied or fleet-synced. Reconnecting an existing account by name reuses its home and refuses to overwrite a home now signed in as a different identity. Supported for version-scoped, isolable harnesses (${connectSupportedList()}); others fail with a clear reason. Provider API-key/token accounts use 'agents accounts add' instead.`,
+    });
     accounts.command('add <name>')
         .description('Add a durable API key, setup token, or bearer token')
         .requiredOption('--provider <provider>', `Credential provider (${listAccountProviders().join(', ')})`)
@@ -643,36 +757,43 @@ agents run codex#work`,
         });
     });
     accounts.command('logout <target>')
-        .description('Sign out a harness-native OAuth login. API-key / setup-token / bearer accounts use `accounts remove` instead.')
+        .description('Sign out a harness-native OAuth login by <harness>, <harness>@<label>, <harness>#<account>, or account name. API-key / setup-token / bearer accounts use `accounts remove` instead.')
         .action(async (target, _o, command) => {
         await runAccountsAction(command, async () => {
             const provider = findAccount(target);
             if (provider) {
                 throw new Error(`Account '${provider.name}' uses ${provider.auth}, not OAuth. Remove it with: agents accounts remove ${provider.name}`);
             }
-            const agentRaw = target.split('@')[0];
-            if (!ALL_AGENT_IDS.includes(agentRaw)) {
-                throw new Error(`Unknown target '${target}'. Pass a native harness (claude, codex, …) or a provider account name. Provider API-key accounts use \`agents accounts remove\`.`);
+            const { agent } = await resolveLogoutTarget(target);
+            // Acquire the per-harness auth-operation mutex before logout — a concurrent
+            // connect for the same harness could allocate and install into the same home
+            // while this logout is in-flight, leaving the home in an ambiguous state.
+            const lock = acquireAuthOperationLock(agent);
+            try {
+                const resolved = await resolveLogoutTarget(target);
+                if (resolved.agent !== agent)
+                    throw new Error('Account selection changed; retry sign-out.');
+                const { version } = resolved;
+                const { runNativeAccountCommand } = await import('../lib/installations/native-command.js');
+                const { getVersionHomePath } = await import('../lib/installations/versions.js');
+                const { buildExecEnv } = await import('../lib/exec.js');
+                // Pin the harness's own config-dir env (CLAUDE_CONFIG_DIR / CODEX_HOME) to
+                // the resolved home so `logout` signs out THAT account's home — not
+                // whichever the global default happens to be. HOME alone was insufficient
+                // for a config-dir-env harness, which is why a passed @label was ignored.
+                const env = buildExecEnv({ agent, version, configVersion: version, interactive: true, mode: 'auto', effort: 'auto', cwd: process.cwd() });
+                env.HOME = getVersionHomePath(agent, version);
+                lock.assertHeld();
+                const result = await runNativeAccountCommand(agent, version, agent === 'claude' ? ['auth', 'logout'] : ['logout'], env, lock.signal);
+                lock.assertHeld();
+                if ((result.code ?? 1) !== 0) {
+                    throw new Error(`${agent} logout exited ${result.code ?? 'null'}. If this harness has no logout verb, sign out from its own UI.`);
+                }
+                console.log(chalk.green(`Signed out native ${agent} login (${agent}@${version}).`));
             }
-            const agent = agentRaw;
-            const { spawnSync } = await import('child_process');
-            const { getBinaryPath, getGlobalDefault, getVersionHomePath, listInstalledVersions } = await import('../lib/installations/versions.js');
-            const installed = listInstalledVersions(agent);
-            const version = getGlobalDefault(agent) ?? installed[installed.length - 1];
-            if (!version)
-                throw new Error(`No installed version of ${agent}. Install one with: agents add ${agent}`);
-            const bin = getBinaryPath(agent, version);
-            const home = getVersionHomePath(agent, version);
-            const result = spawnSync(bin, ['logout'], {
-                env: { ...process.env, HOME: home },
-                stdio: 'inherit',
-            });
-            if (result.error)
-                throw result.error;
-            if ((result.status ?? 1) !== 0) {
-                throw new Error(`${agent} logout exited ${result.status ?? 'null'}. If this harness has no logout verb, sign out from its own UI.`);
+            finally {
+                lock.release();
             }
-            console.log(chalk.green(`Signed out native ${agent} login (${version}).`));
         });
     });
     accounts.command('sync <name> [device]')
@@ -717,7 +838,9 @@ agents run claude`,
         notes: 'Switch writes the existing per-harness default (same binding as set-default). Rotation already honors it. Pass an account name to skip the picker. Native name/attach is only for harnesses agents-cli can isolate (claude, codex, grok); provider add is unrestricted.',
     });
     setHelpSections(accounts, {
-        examples: `agents accounts mint claude
+        examples: `agents accounts connect claude work
+agents accounts connect codex personal
+agents accounts mint claude
 agents accounts mint claude --account work --email ada@example.com --fleet
 agents accounts add work --provider anthropic --auth setup-token
 agents accounts add openrouter-work --provider openrouter --auth api-key --from-secrets openrouter.ai:OPENROUTER_API_KEY
@@ -732,6 +855,6 @@ agents accounts set-default claude work
 agents accounts sync openrouter-work yosemite-s0
 agents run claude --account work
 agents accounts logout claude`,
-        notes: 'Native account records contain metadata only; harness-owned OAuth credentials are never copied. Provider accounts are explicit portable bundles with policy never. `accounts mint claude` drives `claude setup-token` and seeds both the named account and the reserved file-based auth bundle (same command as `agents auth mint`). `accounts switch` is the fast picker over the same default `set-default` writes. Harness-native OAuth sign-out is `agents accounts logout <harness>` (API-key accounts use `accounts remove`). Synced vault unlock is `agents secrets vault unlock`.',
+        notes: 'Accounts are stable independent of releases: `accounts connect <harness> [name]` gives each new account a fresh isolated home on the current release and drives its native login (reconnect by name to reuse the home). Native account records contain metadata only; harness-owned OAuth credentials are never copied. Provider accounts are explicit portable bundles with policy never. `accounts mint claude` drives `claude setup-token` and seeds both the named account and the reserved file-based auth bundle (same command as `agents auth mint`). `accounts switch` is the fast picker over the same default `set-default` writes. Harness-native OAuth sign-out is `agents accounts logout <harness>` (API-key accounts use `accounts remove`). Synced vault unlock is `agents secrets vault unlock`.',
     });
 }

package/dist/commands/config.js

@@ -13,6 +13,7 @@
  * grammar into reads/writes of the existing stores.
  */
 import chalk from 'chalk';
+import { AGENTS } from '../lib/agents.js';
 import { setHelpSections } from '../lib/help.js';
 import { parseConfigKey, formatAgentVersion, devicePropertyToConfigName, configKeyStorageHint, } from '../lib/config-keys.js';
 import { registerBudgetCommand } from './budget.js';
@@ -23,6 +24,7 @@ import { readMeta, updateMeta } from '../lib/state.js';
 import { MODEL_TIERS } from '../lib/model-tiers.js';
 import { machineId } from '../lib/machine-id.js';
 import { getProjectRoot, setProjectRoot } from '../lib/project-root.js';
+import { rawAgentAutoUpdateSetting, rawGlobalAutoUpdateSetting, setAgentAutoUpdateEnabled, setGlobalAutoUpdateEnabled, unsetAgentAutoUpdateEnabled, unsetGlobalAutoUpdateEnabled, } from '../lib/installations/update-policy.js';
 /** Parse a boolean value the same way `agents devices configure` does. */
 function parseBool(value, key) {
     const v = value.trim().toLowerCase();
@@ -47,6 +49,8 @@ function parseValue(key, parsed, raw) {
             return raw.trim();
         case 'summarizer':
             return parsed.property === 'enabled' ? parseBool(raw, key) : raw.trim();
+        case 'updates':
+            return parseBool(raw, key);
         case 'device': {
             const property = parsed.property;
             switch (property) {
@@ -132,6 +136,13 @@ function setConfig(parsed, value) {
             setConfigValue(`summarizer.${parsed.property}`, value);
             return;
         }
+        case 'updates': {
+            if (parsed.agent)
+                setAgentAutoUpdateEnabled(parsed.agent, value);
+            else
+                setGlobalAutoUpdateEnabled(value);
+            return;
+        }
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             if (parsed.property === 'notes') {
@@ -196,6 +207,16 @@ function unsetConfig(parsed) {
             unsetConfigValue(name);
             return had;
         }
+        case 'updates': {
+            if (parsed.agent) {
+                const had = rawAgentAutoUpdateSetting(parsed.agent) !== undefined;
+                unsetAgentAutoUpdateEnabled(parsed.agent);
+                return had;
+            }
+            const had = rawGlobalAutoUpdateSetting() !== undefined;
+            unsetGlobalAutoUpdateEnabled();
+            return had;
+        }
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             const had = getConfigValue(configName, { device: parsed.device }).value !== undefined;
@@ -228,6 +249,8 @@ function getConfig(parsed) {
             return getProjectRoot();
         case 'summarizer':
             return getConfigValue(`summarizer.${parsed.property}`).value;
+        case 'updates':
+            return parsed.agent ? rawAgentAutoUpdateSetting(parsed.agent) : rawGlobalAutoUpdateSetting();
         case 'device': {
             const configName = devicePropertyToConfigName(parsed.property);
             return getConfigValue(configName, { device: parsed.device }).value;
@@ -310,6 +333,18 @@ function* listCentralConfigEntries() {
             yield { key, value, hint: configKeyStorageHint(parseConfigKey(key)) };
         }
     }
+    // Managed-harness auto-update switches (PHNX-3940) — user scope, syncs fleet-wide.
+    const globalAutoUpdate = rawGlobalAutoUpdateSetting();
+    if (globalAutoUpdate !== undefined) {
+        yield { key: 'updates.auto', value: globalAutoUpdate, hint: configKeyStorageHint(parseConfigKey('updates.auto')) };
+    }
+    for (const agent of Object.keys(AGENTS)) {
+        const value = rawAgentAutoUpdateSetting(agent);
+        if (value !== undefined) {
+            const key = `updates.${agent}.auto`;
+            yield { key, value, hint: configKeyStorageHint(parseConfigKey(key)) };
+        }
+    }
 }
 /** Collect device-scope config entries. */
 function* listDeviceConfigEntries(device) {
@@ -382,6 +417,8 @@ export function registerConfigCommand(program) {
       agents config set browser.profile work
       agents config set project.root ~/src/github.com/<you>
       agents config set devices.mac-mini.max-agents 4
+      agents config set updates.auto off
+      agents config set updates.claude.auto off
       agents config get run.claude@*.model
       agents config unset run.claude@*.tier.best
       agents config list