@phnx-labs/agents-cli 1.22.83 → 1.22.85

package/dist/lib/harness/adapter.js

@@ -1,19 +1,23 @@
 /**
- * The four config-dir env keys a harness pins to its version home. Every
- * per-harness branch in the old buildExecEnv deleted the ones it does NOT set,
- * so its own config pointer never leaks into a foreign harness's invocation.
- * (XDG_CONFIG_HOME / XDG_DATA_HOME — Muse/Cursor — are deliberately absent: the
- * old code sets them but never strips them, and this preserves that exactly.)
+ * Config-dir env keys a harness pins to its slot / version home. Every
+ * per-harness branch in buildExecEnv deletes the ones it does NOT set, so a
+ * slot never inherits another account's dir (PHNX-3940 T5). GROK_HOME,
+ * OPENCODE_CONFIG_DIR, and the XDG pair were previously omitted, which let a
+ * parent agent's pin leak into a sibling slot.
  */
 export const CONFIG_DIR_ENV_KEYS = [
     'CLAUDE_CONFIG_DIR',
     'CODEX_HOME',
     'COPILOT_HOME',
     'KIMI_CODE_HOME',
+    'GROK_HOME',
+    'OPENCODE_CONFIG_DIR',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
 ];
 /**
  * Strip every config-dir env key except the one(s) this harness sets. `keep=[]`
- * (the default / no-config-dir harness) deletes all four — the old `else` arm.
+ * (the default / no-config-dir harness) deletes all of them — the old `else` arm.
  */
 export function stripForeignConfigDir(result, keep = []) {
     for (const key of CONFIG_DIR_ENV_KEYS) {

package/dist/lib/harness/adapters/grok.js

@@ -1,8 +1,13 @@
-// Grok has no exec-time config-dir env pin (buildExecEnv's `else` strips the
-// foreign keys — the registry fallback preserves that). It DOES relocate its
-// whole config tree via GROK_HOME in the generated shim.
+import * as path from 'path';
+import { stripForeignConfigDir } from '../adapter.js';
 export const grokAdapter = {
     id: 'grok',
+    applyExecConfigEnv(result, ctx) {
+        if (ctx.versionHome) {
+            result.GROK_HOME = path.join(ctx.versionHome, '.grok');
+        }
+        stripForeignConfigDir(result, ['GROK_HOME']);
+    },
     shimConfigEnvBash() {
         return `
 # Grok Build uses GROK_HOME to isolate its entire configuration tree

package/dist/lib/harness/adapters/muse.js

@@ -13,7 +13,7 @@ export const museAdapter = {
             result.XDG_CONFIG_HOME = path.join(ctx.versionHome, '.config');
             result.XDG_DATA_HOME = path.join(ctx.versionHome, '.local', 'share');
         }
-        stripForeignConfigDir(result);
+        stripForeignConfigDir(result, ['XDG_CONFIG_HOME', 'XDG_DATA_HOME']);
     },
     shimConfigEnvBash() {
         return `

package/dist/lib/harness/adapters/opencode.js

@@ -1,8 +1,17 @@
-// OpenCode has no exec-time config-dir env pin (buildExecEnv's `else` strips the
-// foreign keys — the registry fallback preserves that). It reads config-directory
-// resources from OPENCODE_CONFIG_DIR, pinned in the generated shim.
+import * as path from 'path';
+import { stripForeignConfigDir } from '../adapter.js';
+// OpenCode reads plugins/agents/commands from OPENCODE_CONFIG_DIR and auth from
+// $XDG_DATA_HOME/opencode (HARNESS_AUTH.slotEnv). Pin both at the slot / version
+// home so two accounts in one install never share a credential (PHNX-3940 T5).
 export const opencodeAdapter = {
     id: 'opencode',
+    applyExecConfigEnv(result, ctx) {
+        if (ctx.versionHome) {
+            result.OPENCODE_CONFIG_DIR = path.join(ctx.versionHome, '.config', 'opencode');
+            result.XDG_DATA_HOME = path.join(ctx.versionHome, '.local', 'share');
+        }
+        stripForeignConfigDir(result, ['OPENCODE_CONFIG_DIR', 'XDG_DATA_HOME']);
+    },
     shimConfigEnvBash() {
         return `
 # OpenCode reads plugins, agents, commands, and other config-directory

package/dist/lib/harness-auth-capabilities.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Per-harness auth capability table (PHNX-3940).
+ *
+ * One row per `ALL_AGENT_IDS` entry. Governs `accounts add` / connect login
+ * argv, identity strength, the durable worker credential (if any), and the
+ * config-dir env that pins a slot. Completeness is pinned by the test against
+ * `ALL_AGENT_IDS` — a new harness without a row is a type error and a failing
+ * test, never a silent skip.
+ *
+ * Values are taken from evidence-harness-auth.md (2026-09-06) and the adapters
+ * under `lib/harness/adapters/`. `LOGIN_INVOCATIONS` is the connect-era subset
+ * (claude, codex) derived from this table so existing connect callers keep
+ * working until T4 folds connect into `accounts add`.
+ */
+import type { AgentId } from './types.js';
+export type HarnessIdentityKind = 'strong' | 'email' | 'opaque';
+/**
+ * Durable worker credential, or `none` when the harness must log in per box.
+ * Codex is both: an API key (portable, bills the API) OR a per-device
+ * ChatGPT-plan device-auth login (the plan seat; never stored in the reserved
+ * store because it is a rotating session).
+ */
+export type HarnessWorkerKind = 'setup-token' | 'none' | `api-key:${string}` | `per-device${'' | `:${string}`}`;
+export type HarnessWorker = HarnessWorkerKind | HarnessWorkerKind[];
+export interface HarnessAuthCapability {
+    /** argv after the harness binary to start native login, or null when there is no finite login command. */
+    login: string[] | null;
+    /** argv to probe login status, or null when the CLI has no status command. */
+    status: string[] | null;
+    identity: HarnessIdentityKind;
+    worker: HarnessWorker;
+    /** Config-dir env that pins a slot, or null when isolation is HOME-swap only. */
+    slotEnv: string | null;
+}
+export declare const HARNESS_AUTH: Record<AgentId, HarnessAuthCapability>;
+export declare function harnessAuth(agent: AgentId): HarnessAuthCapability;
+/** Worker kinds as a flat list (codex's dual path is two entries). */
+export declare function harnessWorkerKinds(agent: AgentId): HarnessWorkerKind[];
+/**
+ * True when this harness has no portable worker credential and must log in
+ * per box. `worker: 'none'` (kimi, antigravity, …) and a sole `per-device…`
+ * kind both count; a dual path like Codex (API key OR device-auth) does not.
+ */
+export declare function harnessWorkerIsPerDevice(agent: AgentId): boolean;
+/**
+ * Native-login invocation per harness. Only harnesses with a REAL, finite login
+ * COMMAND that connect currently drives — connect fails clearly for anything
+ * else rather than faking a flow that never signs the user in. Verified against
+ * the installed CLIs (PHNX-3940): `claude auth login --help` → "Sign in to your
+ * Anthropic account" with `--email`; `codex login` drives the OAuth flow.
+ * Args are the `HARNESS_AUTH.login` values for the same ids.
+ */
+export interface LoginInvocation {
+    /** argv passed to the installed binary to start the native login. */
+    args: string[];
+    /** Flag that pre-fills the login email (appended as `[emailFlag, email]`), when supported. */
+    emailFlag?: string;
+    /** One-line hint shown before the login flow takes over. */
+    hint?: string;
+}
+export declare const LOGIN_INVOCATIONS: Partial<Record<AgentId, LoginInvocation>>;

package/dist/lib/harness-auth-capabilities.js

@@ -0,0 +1,52 @@
+export const HARNESS_AUTH = {
+    claude: { login: ['auth', 'login'], status: ['auth', 'status'], identity: 'strong', worker: 'setup-token', slotEnv: 'CLAUDE_CONFIG_DIR' },
+    codex: { login: ['login'], status: ['login', 'status'], identity: 'strong', worker: ['api-key:OPENAI_API_KEY', 'per-device:device-auth'], slotEnv: 'CODEX_HOME' },
+    grok: { login: ['login'], status: null, identity: 'strong', worker: 'api-key:XAI_API_KEY', slotEnv: 'GROK_HOME' },
+    // auth.json has no email claim; identity is the sorted provider-id join
+    // (`resolveOpenCodeAccountId`). NATIVE_ACCOUNT_CAPABILITIES.opencode.inspection
+    // is already 'opaque'.
+    opencode: { login: ['auth', 'login'], status: ['auth', 'list'], identity: 'opaque', worker: 'api-key:provider', slotEnv: 'XDG_DATA_HOME' },
+    cursor: { login: ['login'], status: ['status'], identity: 'strong', worker: 'api-key:CURSOR_API_KEY', slotEnv: null },
+    // No finite login argv — launch bare `kimi`, then `/login` in the TUI
+    // (`loginHint('kimi') === 'kimi'`, fleet/auth-sync `loginCommand: 'kimi'`).
+    kimi: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'KIMI_CODE_HOME' },
+    antigravity: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
+    droid: { login: null, status: null, identity: 'opaque', worker: 'api-key:FACTORY_API_KEY', slotEnv: null },
+    gemini: { login: null, status: null, identity: 'email', worker: 'none', slotEnv: null },
+    copilot: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'COPILOT_HOME' },
+    openclaw: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
+    amp: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
+    goose: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
+    hermes: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
+    // Auth lives under $XDG_CONFIG_HOME/muse (adapter pins XDG_CONFIG_HOME +
+    // XDG_DATA_HOME). slotEnv names the config pin; T5 must not HOME-swap.
+    muse: { login: null, status: null, identity: 'email', worker: 'none', slotEnv: 'XDG_CONFIG_HOME' },
+    warp: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
+};
+export function harnessAuth(agent) {
+    const cap = HARNESS_AUTH[agent];
+    if (!cap)
+        throw new Error(`No harness-auth capability for '${agent}'.`);
+    return cap;
+}
+/** Worker kinds as a flat list (codex's dual path is two entries). */
+export function harnessWorkerKinds(agent) {
+    const worker = harnessAuth(agent).worker;
+    return Array.isArray(worker) ? worker : [worker];
+}
+/**
+ * True when this harness has no portable worker credential and must log in
+ * per box. `worker: 'none'` (kimi, antigravity, …) and a sole `per-device…`
+ * kind both count; a dual path like Codex (API key OR device-auth) does not.
+ */
+export function harnessWorkerIsPerDevice(agent) {
+    return harnessWorkerKinds(agent).every((kind) => kind === 'none' || kind.startsWith('per-device'));
+}
+export const LOGIN_INVOCATIONS = {
+    claude: {
+        args: HARNESS_AUTH.claude.login,
+        emailFlag: '--email',
+        hint: 'Complete the Claude sign-in in your browser.',
+    },
+    codex: { args: HARNESS_AUTH.codex.login },
+};

package/dist/lib/helper-versions.d.ts

@@ -27,7 +27,7 @@
  * never be derived from `getCliVersion()`.
  */
 /** The helpers that have their own release train. */
-export type HelperName = 'menubar' | 'keychain' | 'computer-mac' | 'computer-win';
+export type HelperName = 'menubar' | 'computer-mac' | 'computer-win';
 /** One helper's release identity. */
 export interface HelperRelease {
     /** Tag prefix — the release is `<tagPrefix>/v<version>`. */
@@ -41,9 +41,11 @@ export interface HelperRelease {
 /**
  * Floors, by helper.
  *
- * `menubar` and `keychain` start at 1.0.0 — the first builds published under
- * their own tags rather than the CLI's. They are not "version 1 of the helper";
- * they are version 1 of its independent release train.
+ * `menubar` starts at 1.0.0 — the first build published under its own tag
+ * rather than the CLI's. It is not "version 1 of the helper"; it is version 1
+ * of its independent release train. The keychain helper moved with the
+ * standalone `secrets` engine (PHNX-3989) — it downloads and verifies its own
+ * helper release now, off this table entirely.
  */
 export declare const HELPER_RELEASES: Readonly<Record<HelperName, HelperRelease>>;
 /** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */

package/dist/lib/helper-versions.js

@@ -29,13 +29,14 @@
 /**
  * Floors, by helper.
  *
- * `menubar` and `keychain` start at 1.0.0 — the first builds published under
- * their own tags rather than the CLI's. They are not "version 1 of the helper";
- * they are version 1 of its independent release train.
+ * `menubar` starts at 1.0.0 — the first build published under its own tag
+ * rather than the CLI's. It is not "version 1 of the helper"; it is version 1
+ * of its independent release train. The keychain helper moved with the
+ * standalone `secrets` engine (PHNX-3989) — it downloads and verifies its own
+ * helper release now, off this table entirely.
  */
 export const HELPER_RELEASES = {
     menubar: { tagPrefix: 'menubar', floor: '1.0.0' },
-    keychain: { tagPrefix: 'keychain', floor: '1.0.0' },
     'computer-mac': { tagPrefix: 'computer-mac', floor: '1.0.0' },
     // The Windows helper is a bare .exe, not an .app bundle, so it does not share
     // helper-download.ts's zip/codesign/notarize machinery -- but it has the same

package/dist/lib/hosts/credential-transport.d.ts

@@ -0,0 +1,10 @@
+/** The host part of an ssh target (`user@host` -> `host`) for known_hosts matching. */
+export declare function hostKeyLookupName(target: string): string;
+/** Refuse durable credential transfer until the destination SSH key is pinned. */
+export declare function assertCredentialTransportHostPinned(target: string, pinned?: boolean): void;
+/**
+ * Resolve a `--device` value to an ssh target string for a credential-carrying
+ * remote operation. Delegates to the same resolver `run --device` uses; on a
+ * miss, treats the value as a raw ssh target and validates it.
+ */
+export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;

package/dist/lib/hosts/credential-transport.js

@@ -0,0 +1,37 @@
+/**
+ * Credential transport policy for a fleet host (agents-owned, PHNX-3989).
+ *
+ * Whether a durable credential may leave this device for a given host is
+ * agents fleet policy, not a secrets-engine concern: it hangs off the managed
+ * `known_hosts` pin and the hosts/devices registry. The standalone `secrets`
+ * CLI only carries the bundle once agents-cli has decided the destination is
+ * trustworthy, so these guards live here and are passed INTO the transport,
+ * never re-implemented on the engine side.
+ */
+import { assertValidSshTarget } from '../ssh-exec.js';
+import { resolveHost } from './registry.js';
+import { sshTargetFor } from './types.js';
+import { isHostPinned } from '../devices/known-hosts.js';
+/** The host part of an ssh target (`user@host` -> `host`) for known_hosts matching. */
+export function hostKeyLookupName(target) {
+    return target.split('@').pop() ?? target;
+}
+/** Refuse durable credential transfer until the destination SSH key is pinned. */
+export function assertCredentialTransportHostPinned(target, pinned = isHostPinned(hostKeyLookupName(target))) {
+    if (pinned)
+        return;
+    throw new Error(`Refusing to transfer provider credentials to '${target}' before its SSH host key is pinned. ` +
+        `Connect once with 'agents ssh ${target}' and verify the host, then retry.`);
+}
+/**
+ * Resolve a `--device` value to an ssh target string for a credential-carrying
+ * remote operation. Delegates to the same resolver `run --device` uses; on a
+ * miss, treats the value as a raw ssh target and validates it.
+ */
+export async function resolveHostSshTarget(nameOrAlias) {
+    const host = await resolveHost(nameOrAlias);
+    if (host)
+        return sshTargetFor(host);
+    assertValidSshTarget(nameOrAlias);
+    return nameOrAlias;
+}

package/dist/lib/hosts/dispatch.d.ts

@@ -170,6 +170,13 @@ export interface DispatchOptions {
  * (remote-cmd.ts) — keep the two in lockstep; run-forwarding.test.ts asserts
  * the table side.
  */
+/** Compose `agent[@version][#account]` so the peer resolves ITS slot (PHNX-3940 T5). */
+export declare function runAgentSpecArg(opts: {
+    agent: string;
+    version?: string;
+    account?: string;
+    accountPicker?: boolean;
+}): string;
 export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
 export interface InteractiveDispatchOptions {
     agent: string;

package/dist/lib/hosts/dispatch.js

@@ -359,8 +359,19 @@ async function launchDetached(host, target, opts) {
  * (remote-cmd.ts) — keep the two in lockstep; run-forwarding.test.ts asserts
  * the table side.
  */
+/** Compose `agent[@version][#account]` so the peer resolves ITS slot (PHNX-3940 T5). */
+export function runAgentSpecArg(opts) {
+    if (opts.accountPicker)
+        return `${opts.agent}@`;
+    let spec = opts.agent;
+    if (opts.version)
+        spec += `@${opts.version}`;
+    if (opts.account)
+        spec += `#${opts.account}`;
+    return spec;
+}
 export function buildRunForwardedArgs(opts) {
-    const agentArg = opts.version ? `${opts.agent}@${opts.version}` : opts.agent;
+    const agentArg = runAgentSpecArg(opts);
     const args = ['run', agentArg, opts.prompt, '--quiet'];
     if (opts.mode)
         args.push('--mode', opts.mode);
@@ -427,11 +438,7 @@ export function buildInteractiveRunForwardedArgs(opts) {
     if (opts.version && opts.accountPicker) {
         throw new Error('Interactive host dispatch cannot combine an account picker with a version pin');
     }
-    const agentArg = opts.accountPicker
-        ? `${opts.agent}@`
-        : opts.version
-            ? `${opts.agent}@${opts.version}`
-            : opts.agent;
+    const agentArg = runAgentSpecArg(opts);
     const args = ['run', agentArg];
     if (opts.prompt && opts.forceInteractive)
         args.push(opts.prompt);

package/dist/lib/identity/client.d.ts

@@ -10,9 +10,9 @@
  * here and nothing else.
  *
  * The shape mirrors the seams this repo already proved elsewhere —
- * `SyncBackend` (`lib/secrets/sync-backend.ts`) and `CloudProvider`
- * (`lib/cloud/types.ts`) — so a second identity backend, if one is ever
- * needed, is a swap here rather than a sweep across commands.
+ * the bounded secrets process client (`lib/secrets-client.ts`) and
+ * `CloudProvider` (`lib/cloud/types.ts`) — so a second identity backend, if
+ * one is ever needed, is a swap here rather than a sweep across commands.
  */
 /**
  * Where the account backend lives. Config, never a literal at a call site.

package/dist/lib/identity/client.js

@@ -10,9 +10,9 @@
  * here and nothing else.
  *
  * The shape mirrors the seams this repo already proved elsewhere —
- * `SyncBackend` (`lib/secrets/sync-backend.ts`) and `CloudProvider`
- * (`lib/cloud/types.ts`) — so a second identity backend, if one is ever
- * needed, is a swap here rather than a sweep across commands.
+ * the bounded secrets process client (`lib/secrets-client.ts`) and
+ * `CloudProvider` (`lib/cloud/types.ts`) — so a second identity backend, if
+ * one is ever needed, is a swap here rather than a sweep across commands.
  */
 import * as fs from 'fs';
 import * as path from 'path';

package/dist/lib/installations/index.d.ts

@@ -8,7 +8,7 @@
  * per-installation isolation track consumes exactly this).
  */
 export { type Installation, type InstallationRelease, type UpdateOutcome, type UpdateStrategyId, type UpdatePolicy, } from './types.js';
-export { createInstallation, listInstallations, recordRelease, } from './store.js';
+export { createInstallation, listInstallations, recordRelease, MANAGED_INSTALLATION_LABEL, resolveManagedInstallation, ensureHarnessInstallation, type EnsureHarnessInstallationResult, } from './store.js';
 export { describeInstallation, resolveInstallation, type ResolveInstallationOptions, } from './resolve.js';
 export { selectUpdateStrategy, supportsPinnedUpdate, type UpdateStrategy, } from './strategies.js';
 export { updateInstallation, type UpdateInstallationOptions } from './update.js';

package/dist/lib/installations/index.js

@@ -7,7 +7,7 @@
  * it, so the internal split can change without breaking callers (the Cursor
  * per-installation isolation track consumes exactly this).
  */
-export { createInstallation, listInstallations, recordRelease, } from './store.js';
+export { createInstallation, listInstallations, recordRelease, MANAGED_INSTALLATION_LABEL, resolveManagedInstallation, ensureHarnessInstallation, } from './store.js';
 export { describeInstallation, resolveInstallation, } from './resolve.js';
 export { selectUpdateStrategy, supportsPinnedUpdate, } from './strategies.js';
 export { updateInstallation } from './update.js';

package/dist/lib/installations/migrate.js

@@ -2366,4 +2366,13 @@ export async function runMigration() {
     catch {
         // best-effort — a migration must never fail because tmux wasn't reachable
     }
+    // PHNX-3940 T7: report leftover per-account installations. Dry-run only —
+    // moving homes requires an explicit `agents accounts migrate --apply`.
+    try {
+        const { reportAccountSlotMigrationOnUpgrade } = await import('../accounts/migrate.js');
+        await reportAccountSlotMigrationOnUpgrade();
+    }
+    catch {
+        // best-effort — a corrupt install must not block the rest of upgrade
+    }
 }

package/dist/lib/installations/resolve.js

@@ -21,7 +21,7 @@ export class InstallationNotFoundError extends Error {
         // Nothing installed is a different problem from "your selector missed", and
         // the remedy differs — say which one it is rather than printing an empty list.
         super(available.length === 0
-            ? `No ${AGENTS[agent].name} installations are managed by agents-cli. Install one with: agents add ${agent}@latest`
+            ? `No ${AGENTS[agent].name} installations are managed by agents-cli. Install one with: agents add ${agent}`
             : `No ${AGENTS[agent].name} installation matches '${selector}'. Installed: ${available.map((i) => describeInstallation(i)).join(', ')}`);
         this.agent = agent;
         this.selector = selector;

package/dist/lib/installations/shims.d.ts

@@ -201,6 +201,21 @@ export declare const CONFIG_ENV_ISOLATED_AGENTS: readonly AgentId[];
  * separate from the user's real `~/.<agent>`. See {@link CONFIG_ENV_ISOLATED_AGENTS}.
  */
 export declare function supportsIsolatedInstall(agent: AgentId): boolean;
+/**
+ * Harnesses that isolate by symlink-adopting `~/.<config>` rather than a
+ * config-dir env (PHNX-3940 T5). One active slot per device; `accounts default`
+ * repoints the adopted symlink under the auth-op lock.
+ */
+export declare function isSymlinkAdoptedHarness(agent: AgentId): boolean;
+/**
+ * Repoint this harness's adopted `~/.<config>` symlink at `home`'s config dir.
+ * No-op for env-isolated harnesses. Fails loud when the adopted path is a real
+ * directory rather than a symlink — adopting that is `agents use`, not default.
+ */
+export declare function repointAdoptedConfigToHome(agent: AgentId, home: string): {
+    success: boolean;
+    error?: string;
+};
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary

package/dist/lib/installations/shims.js

@@ -10,6 +10,7 @@ import { IS_WINDOWS, prependToWindowsUserPath } from '../platform/index.js';
 import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgentsDir } from '../state.js';
 export { getShimsDir };
 import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from '../agents.js';
+import { acquireAuthOperationLock } from '../accounts/auth-operation-lock.js';
 import { codexHomeShimBash } from '../codex-home.js';
 import { resolveHarnessAdapter } from '../harness/index.js';
 import { randomUUID } from 'node:crypto';
@@ -1130,6 +1131,74 @@ export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'cursor
 export function supportsIsolatedInstall(agent) {
     return CONFIG_ENV_ISOLATED_AGENTS.includes(agent);
 }
+/**
+ * Harnesses that isolate by symlink-adopting `~/.<config>` rather than a
+ * config-dir env (PHNX-3940 T5). One active slot per device; `accounts default`
+ * repoints the adopted symlink under the auth-op lock.
+ */
+export function isSymlinkAdoptedHarness(agent) {
+    return !CONFIG_ENV_ISOLATED_AGENTS.includes(agent);
+}
+/**
+ * Repoint this harness's adopted `~/.<config>` symlink at `home`'s config dir.
+ * No-op for env-isolated harnesses. Fails loud when the adopted path is a real
+ * directory rather than a symlink — adopting that is `agents use`, not default.
+ */
+export function repointAdoptedConfigToHome(agent, home) {
+    if (!isSymlinkAdoptedHarness(agent))
+        return { success: true };
+    const lock = acquireAuthOperationLock(agent);
+    try {
+        lock.assertHeld();
+        const configPath = getAgentConfigPath(agent);
+        const configDirName = path.relative(os.homedir(), AGENTS[agent].configDir);
+        const target = path.join(home, configDirName);
+        fs.mkdirSync(target, { recursive: true });
+        try {
+            const stat = fs.lstatSync(configPath);
+            if (stat.isSymbolicLink()) {
+                const current = path.resolve(path.dirname(configPath), fs.readlinkSync(configPath));
+                if (current === path.resolve(target))
+                    return { success: true };
+            }
+            else {
+                return {
+                    success: false,
+                    error: `${configPath} is not a symlink; refusing to replace a real config directory. `
+                        + `Run \`agents use ${agent}\` once to adopt it, then \`agents accounts default ${agent}\`.`,
+                };
+            }
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        // Atomic retarget: create temp symlink, rename over existing (same pattern
+        // as switchHomeFileSymlinks). A window of "path missing" would let a
+        // harness process observe neither the old nor the new target.
+        const tmpPath = `${configPath}.agents-tmp-${process.pid}`;
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch { /* leftover from a killed prior swap */ }
+        try {
+            fs.symlinkSync(target, tmpPath, process.platform === 'win32' ? 'junction' : undefined);
+            fs.renameSync(tmpPath, configPath);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch { /* rename may have already consumed it */ }
+            throw err;
+        }
+        return { success: true };
+    }
+    finally {
+        lock.release();
+    }
+}
 /**
  * Generate a versioned alias script that directly execs a specific version.
  * e.g., claude@2.0.65 -> directly runs that version's binary

package/dist/lib/installations/store.d.ts

@@ -60,6 +60,42 @@ export declare function listInstallationLabels(agent: AgentId): string[];
  * that disappears mid-scan is skipped rather than failing the whole listing.
  */
 export declare function listInstallations(agent: AgentId): Installation[];
+/**
+ * The label of the single managed installation every harness gets under the
+ * account model v2 (PHNX-3940). One managed install per harness per device;
+ * accounts live in credential slots beside it, and a second home is an expert
+ * `--isolated` copy, never another managed install.
+ */
+export declare const MANAGED_INSTALLATION_LABEL = "main";
+/**
+ * Resolve the ONE managed installation of a harness, or null when the harness
+ * has no managed install yet. The winner is deterministic: the `main` label
+ * first, then the recorded global default (the install the user actually
+ * launches), then the first remaining non-isolated installation by label.
+ * Isolated copies (`agents add --isolated`) never count — they are expert
+ * second homes, not the managed install.
+ */
+export declare function resolveManagedInstallation(agent: AgentId): Installation | null;
+export interface EnsureHarnessInstallationResult {
+    installation: Installation;
+    /** True when this call installed the harness just now; false when the managed installation already existed and was reused unchanged. */
+    installed: boolean;
+}
+/**
+ * The taught entry point for "make this harness runnable" (PHNX-3940): return
+ * the harness's single managed installation, installing the current release
+ * into the `main` label when the harness is not installed yet. `release` pins
+ * the fresh install to a concrete release (recorded as a pinned update policy
+ * by `installVersion`); it has no effect when an installation already exists —
+ * moving an existing install is `agents update <agent> --to <release>`'s job.
+ *
+ * Throws (fail loud) when the install fails; never returns a half-installed
+ * record.
+ */
+export declare function ensureHarnessInstallation(agent: AgentId, opts?: {
+    release?: string;
+    onProgress?: (message: string) => void;
+}): Promise<EnsureHarnessInstallationResult>;
 /**
  * Get the directory where a specific version is installed.
  */
@@ -154,6 +190,13 @@ export declare function pickCanonicalGlobalBinaryVersion(agent: AgentId, version
  * For a self-updating global-binary agent (droid) every version dir resolves to
  * the SAME binary, so this collapses them to a single canonical entry — one
  * install, one row in `agents view`, never the phantom set of semver dir names.
+ *
+ * A directory is an installation only when it has a working launch binary.
+ * Account credential slots (PHNX-3940, `~/.agents/.history/accounts/**`) are
+ * HOME-shaped dirs with no binary and no `installation.json`, so they can
+ * never appear here. Record-less pre-frozen installs are reported as-is; their
+ * migration belongs to the record-based paths (`listInstallations`), never to
+ * this read surface.
  */
 export declare function listInstalledVersions(agent: AgentId): string[];
 /**