@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/accounts/add.d.ts

@@ -3,69 +3,31 @@ import { type NativeAccount } from '../account-registry.js';
 import { LOGIN_INVOCATIONS, type LoginInvocation } from '../harness-auth-capabilities.js';
 export type { LoginInvocation };
 export { LOGIN_INVOCATIONS };
-/** The env var an api-key worker credential injects as, from HARNESS_AUTH. */
 export declare function workerApiKeyEnv(agent: AgentId): string | null;
-/** Whether `accounts add` can drive this harness (nameable, version-scoped, a real login command). */
 export declare function addSupported(agent: AgentId): boolean;
-/** One-line description of how a harness's workers get their credential. */
 export declare function workerProvisioningHint(agent: AgentId): string;
-/**
- * Named reason `accounts add` refuses a harness, or null when supported.
- * Distinguishes "cannot isolate/name this login" (capability) from "no finite
- * native login command" so the message is honest about which limit was hit.
- */
 export declare function addRefusal(agent: AgentId): string | null;
 export declare function supportedAddHarnesses(): AgentId[];
 export declare function assertAddSupported(agent: AgentId): void;
-/**
- * Named reason add/login refuses on a non-headed device, or null when this box
- * may run an interactive login. Workers never mint a native OAuth login
- * (credential-management.md invariant 7 + Provisioning model).
- */
 export declare function addWorkerRefusal(agent: AgentId, name?: string): string | null;
-/**
- * Refuse to mint a Claude setup-token while an ambient CLAUDE_CODE_OAUTH_TOKEN
- * is set in this shell — the ambient token is ONE account, so minting under it
- * would collapse every slot to that account (signin-badge.ts `ambientClaudeToken`).
- */
 export declare function ambientTokenRefusal(agent: AgentId, env?: NodeJS.ProcessEnv): string | null;
 export declare function loginInvocation(agent: AgentId): LoginInvocation;
-/** The observed identity of a completed login. */
 export interface ObservedIdentity {
     identityKey: string | null;
     email: string | null;
     releaseVersion: string | null;
-    /** Live credential presence — proof of sign-in, not just a metadata identity claim. */
     signedIn: boolean;
 }
-/**
- * Fail-closed identity check after the login completes (pure).
- *
- * - Not signed in (no live credential) → the login did not complete; a metadata
- *   identity key alone is NOT proof, so `signedIn` is required.
- * - A re-auth (`existing`) whose completed identity differs from the account's
- *   → REFUSE: the account keeps pointing at its original identity.
- * A new add accepts whatever identity signed in (that is the account being
- * created); the caller registers it.
- */
 export declare function verifyConnectedIdentity(ctx: {
     agent: AgentId;
     home: string;
     existing?: NativeAccount | null;
 }, observed: Pick<ObservedIdentity, 'identityKey' | 'signedIn'>): void;
-/** Resolve the existing native account a name refers to for a harness. */
 export declare function findAddAccount(agent: AgentId, name: string | undefined, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): NativeAccount | null;
-/**
- * Side-effecting operations add/login need, injected so the planning and
- * verification path is unit-testable with real meta on a real filesystem
- * without a network install, a browser, or a TTY.
- */
 export interface AddRunners {
-    /** Ensure the harness's ONE managed installation exists; resolves with its label. */
     ensureInstallation(agent: AgentId, onProgress?: (m: string) => void): Promise<{
         label: string;
     }>;
-    /** Launch the harness's native login with HOME = `home` (+ slotEnv); resolves on exit. */
     launchLogin(agent: AgentId, ctx: {
         home: string;
         args: string[];
@@ -75,27 +37,19 @@ export interface AddRunners {
         code: number | null;
     }>;
     observeIdentity(agent: AgentId, home: string): Promise<ObservedIdentity>;
-    /** Claude: drive `claude setup-token` in the slot and return the captured token. */
     mintSetupToken?(agent: AgentId, ctx: {
         home: string;
     }): Promise<string>;
-    /** Interactive api-key collection; null = user cancelled. Absent = non-interactive. */
     promptApiKey?(agent: AgentId, env: string): Promise<string | null>;
-    /** Ask the daemon for one auth-sync reconcile (the daemon owns the tick). */
     requestReconcile?(): void | Promise<void>;
 }
 export interface AddOptions {
     meta: Pick<Meta, 'accounts' | 'deviceAccounts'>;
     onProgress?: (m: string) => void;
-    /** Test-only: override the runtime-state dir for the auth-operation mutex. */
     stateDir?: string;
-    /** Worker credential for api-key harnesses; otherwise prompted interactively. */
     apiKey?: string;
-    /** Skip the worker-credential step (doctor-style warning is printed). */
     noWorkerToken?: boolean;
-    /** codex: a ChatGPT-plan account — no API key; workers log in per box. */
     perDevice?: boolean;
-    /** Overridable env for the ambient-token guard (tests). */
     env?: NodeJS.ProcessEnv;
 }
 export type WorkerCredentialOutcome = 'minted' | 'stored' | 'kept' | 'per-device' | 'skipped';
@@ -108,7 +62,6 @@ export interface AddResult {
     email: string | null;
     slotDir: string;
     releaseVersion: string | null;
-    /** True when this add became the harness's default (only set if none was configured). */
     becameDefault: boolean;
     provisioning: 'portable' | 'per-device';
     workerCredential: WorkerCredentialOutcome;
@@ -118,18 +71,5 @@ export interface AddResult {
     };
     warnings: string[];
 }
-/**
- * Drive one `agents accounts add <harness> [name]`: headed gate → one managed
- * installation → fresh slot → native login in the slot → register the row →
- * mint/collect the worker credential → request a daemon reconcile.
- */
 export declare function runAdd(agent: AgentId, name: string | undefined, opts: AddOptions, runners?: AddRunners): Promise<AddResult>;
-/**
- * Drive one `agents accounts login <harness>#<name>`: re-auth into the SAME
- * slot (re-running add's steps 4–8), re-minting the worker credential and
- * re-syncing. On a per-device harness (worker `none`) any box may run it —
- * that IS how such a box logs in. `--per-device` extends that to a dual-path
- * harness (codex, grok): this box signs the account's subscription seat in for
- * itself through the device-code flow instead of using a portable key.
- */
 export declare function runLogin(agent: AgentId, name: string, opts: AddOptions, runners?: AddRunners): Promise<AddResult>;

package/dist/lib/accounts/add.js

@@ -13,34 +13,6 @@ import { ambientClaudeToken, loginHint } from '../signin-badge.js';
 import { acquireAuthOperationLock } from './auth-operation-lock.js';
 import { ensureSlot, readSlots, recordSlot, slotDir } from './slots.js';
 export { LOGIN_INVOCATIONS };
-/**
- * `agents accounts add <harness> [name]` / `agents accounts login <harness>#<name>`
- * — the account onboarding front door (PHNX-3940, track T4).
- *
- * An account is a credential SLOT, not an installation: the harness has ONE
- * managed installation (`ensureHarnessInstallation`, label `main`); every
- * account gets a HOME-shaped slot under `~/.agents/.history/accounts/<harness>/<id>/`
- * with no binary in it. The native login runs with HOME = slot (plus the
- * harness's `slotEnv` pin), so the OAuth credential is minted directly into the
- * slot and never copied.
- *
- * Headed devices only for harnesses with a portable worker credential
- * (credential-management.md invariant 7): a worker is refused before any slot,
- * install, or browser login. Per-device harnesses (worker `none`, e.g. kimi)
- * may `accounts login` on any box — they are logged in per box by design.
- *
- * The worker credential is minted/collected per account id into the reserved
- * `__<harness>__` store (claude: `setup-token` drive; api-key harnesses:
- * `--api-key` or an interactive prompt — never derived from OAuth). The account
- * row carries only the `{bundle, key}` pointer, never the secret.
- */
-/**
- * Ambient provider-credential env vars stripped before a native login spawn, so
- * the OAuth flow authenticates as the human's identity rather than being
- * short-circuited by an injected API key / setup-token that would impersonate a
- * different account into the fresh slot. The target harness's own
- * `api-key:<ENV>` worker env (from HARNESS_AUTH) is stripped on top of this.
- */
 const PROVIDER_AUTH_ENV_KEYS = [
     'ANTHROPIC_API_KEY',
     'CLAUDE_CODE_OAUTH_TOKEN',
@@ -51,7 +23,6 @@ const PROVIDER_AUTH_ENV_KEYS = [
     'CURSOR_API_KEY',
     'FACTORY_API_KEY',
 ];
-/** The env var an api-key worker credential injects as, from HARNESS_AUTH. */
 export function workerApiKeyEnv(agent) {
     for (const kind of harnessWorkerKinds(agent)) {
         if (!kind.startsWith('api-key:'))
@@ -59,8 +30,6 @@ export function workerApiKeyEnv(agent) {
         const env = kind.slice('api-key:'.length);
         if (env !== 'provider')
             return env;
-        // opencode keys are provider-specific; the provider registry's own adapter
-        // names the harness's default env (opencode → OPENCODE_API_KEY).
         try {
             return getAccountProvider(agent).envFor(agent, 'api-key');
         }
@@ -79,12 +48,10 @@ function hasPerDeviceWorkerKind(agent) {
 function perDeviceRefusal(agent) {
     return `--per-device is only valid for a harness with a per-device worker path; ${agent} is provisioned from ${workerProvisioningHint(agent)}.`;
 }
-/** Whether `accounts add` can drive this harness (nameable, version-scoped, a real login command). */
 export function addSupported(agent) {
     const cap = nativeAccountCapability(agent);
     return cap.scope === 'version' && harnessAuth(agent).login !== null;
 }
-/** One-line description of how a harness's workers get their credential. */
 export function workerProvisioningHint(agent) {
     const parts = [];
     for (const kind of harnessWorkerKinds(agent)) {
@@ -102,11 +69,6 @@ export function workerProvisioningHint(agent) {
         return `${agent} has no portable credential — it logs in per box (run \`agents run ${agent} --device <box>\` on the worker and complete its native login)`;
     return parts.join(', or ');
 }
-/**
- * Named reason `accounts add` refuses a harness, or null when supported.
- * Distinguishes "cannot isolate/name this login" (capability) from "no finite
- * native login command" so the message is honest about which limit was hit.
- */
 export function addRefusal(agent) {
     const capabilityRefusal = nativeAccountNamingRefusal(agent);
     if (capabilityRefusal)
@@ -129,11 +91,6 @@ export function assertAddSupported(agent) {
     if (reason)
         throw new Error(reason);
 }
-/**
- * Named reason add/login refuses on a non-headed device, or null when this box
- * may run an interactive login. Workers never mint a native OAuth login
- * (credential-management.md invariant 7 + Provisioning model).
- */
 export function addWorkerRefusal(agent, name) {
     const role = selfConfiguredDeviceRole();
     if (isHeadedDeviceRole(role))
@@ -153,11 +110,6 @@ function assertAddAllowedOnThisDevice(agent, name) {
     if (reason)
         throw new Error(reason);
 }
-/**
- * Refuse to mint a Claude setup-token while an ambient CLAUDE_CODE_OAUTH_TOKEN
- * is set in this shell — the ambient token is ONE account, so minting under it
- * would collapse every slot to that account (signin-badge.ts `ambientClaudeToken`).
- */
 export function ambientTokenRefusal(agent, env = process.env) {
     if (!ambientClaudeToken(agent, env))
         return null;
@@ -173,16 +125,6 @@ export function loginInvocation(agent) {
         throw new Error(`No native login command is wired for ${agent}.`);
     return { args: login };
 }
-/**
- * Fail-closed identity check after the login completes (pure).
- *
- * - Not signed in (no live credential) → the login did not complete; a metadata
- *   identity key alone is NOT proof, so `signedIn` is required.
- * - A re-auth (`existing`) whose completed identity differs from the account's
- *   → REFUSE: the account keeps pointing at its original identity.
- * A new add accepts whatever identity signed in (that is the account being
- * created); the caller registers it.
- */
 export function verifyConnectedIdentity(ctx, observed) {
     if (!observed.signedIn || !observed.identityKey) {
         throw new Error(`No ${ctx.agent} login completed in the slot (no live credential). Nothing was registered.`);
@@ -193,14 +135,12 @@ export function verifyConnectedIdentity(ctx, observed) {
             + `Account '${ctx.existing.name}' still points at its original identity; nothing was changed. `);
     }
 }
-/** Resolve the existing native account a name refers to for a harness. */
 export function findAddAccount(agent, name, meta) {
     if (!name)
         return null;
     const needle = name.toLowerCase();
     return listNativeAccounts(meta).find(a => a.agent === agent && (a.id === name || a.name.toLowerCase() === needle || a.identityLabel?.toLowerCase() === needle)) ?? null;
 }
-/** Write account-model-v2 fields onto the just-registered row (central or device-scoped store). */
 function patchNativeAccountRow(accountId, patch) {
     updateMeta((current) => {
         if (current.accounts?.native?.[accountId]) {
@@ -214,7 +154,6 @@ function patchNativeAccountRow(accountId, patch) {
         throw new Error(`Account row '${accountId}' vanished before v2 fields could be recorded.`);
     });
 }
-/** Derive the account name for an unnamed add from the login's email local-part. */
 function deriveAccountName(email) {
     if (!email)
         return null;
@@ -224,12 +163,6 @@ function deriveAccountName(email) {
 function removeSlotDir(dir) {
     fs.rmSync(dir, { recursive: true, force: true });
 }
-/**
- * Mint or collect the worker credential for a freshly-registered account and
- * record the `{bundle, key}` pointer on its row. Claude drives `setup-token` in
- * the slot; api-key harnesses take `--api-key` or an interactive prompt (never
- * derived from OAuth). Returns the outcome + provisioning for the result.
- */
 async function mintWorkerCredential(agent, account, home, opts, runners, warnings) {
     const kinds = harnessWorkerKinds(agent);
     if (opts.noWorkerToken) {
@@ -244,8 +177,6 @@ async function mintWorkerCredential(agent, account, home, opts, runners, warning
     }
     const { seedReservedStoreKey, seedReservedAuthToken, workerCredentialStoreKey, } = await import('../auth-mint.js');
     if (kinds.includes('setup-token')) {
-        // Claude: a second browser grant, driven in the slot so the token is minted
-        // under the account's own identity.
         const refusal = ambientTokenRefusal(agent, opts.env ?? process.env);
         if (refusal)
             throw new Error(refusal);
@@ -254,8 +185,6 @@ async function mintWorkerCredential(agent, account, home, opts, runners, warning
         const token = await runners.mintSetupToken(agent, { home });
         const key = workerCredentialStoreKey(agent, account.id);
         const ref = seedReservedStoreKey(agent, 'setup-token', key, token);
-        // Legacy `auth` bundle key for this release, so the pre-v2 usage/probe and
-        // worker-inject readers keep resolving the account.
         if (account.identityLabel)
             seedReservedAuthToken(account.identityLabel, token);
         return { outcome: 'minted', ref, provisioning: 'portable' };
@@ -281,25 +210,15 @@ async function mintWorkerCredential(agent, account, home, opts, runners, warning
         const ref = seedReservedStoreKey(agent, 'api-key', key, value);
         return { outcome: 'stored', ref, provisioning: 'portable' };
     }
-    // worker: none (kimi/antigravity shape) — nothing portable exists.
     return { outcome: 'per-device', provisioning: 'per-device' };
 }
-/**
- * Drive one `agents accounts add <harness> [name]`: headed gate → one managed
- * installation → fresh slot → native login in the slot → register the row →
- * mint/collect the worker credential → request a daemon reconcile.
- */
 export async function runAdd(agent, name, opts, runners) {
     assertAddSupported(agent);
-    // Owner rule (invariant 7): a worker NEVER runs an interactive login. Refuse
-    // before the lock, slot, install, or browser — no side effects on a worker.
     assertAddAllowedOnThisDevice(agent, name);
     const kinds = harnessWorkerKinds(agent);
     if (opts.perDevice && !hasPerDeviceWorkerKind(agent)) {
         throw new Error(perDeviceRefusal(agent));
     }
-    // The ambient-token refusal is checked up front (not at the mint step) so the
-    // user doesn't complete a browser login only to be refused at the end.
     if (!opts.noWorkerToken && !opts.perDevice && kinds.includes('setup-token')) {
         const refusal = ambientTokenRefusal(agent, opts.env ?? process.env);
         if (refusal)
@@ -317,25 +236,16 @@ async function _runAddLocked(agent, name, opts, lock, runners) {
     const run = runners ?? await defaultAddRunners();
     const registry = await import('../account-registry.js');
     lock.assertHeld();
-    // Re-read meta AFTER acquiring the lock so a concurrent add committed before
-    // we were serialized past it is visible (`opts.meta` is a pre-lock snapshot).
     const meta = readMeta();
-    // Idempotency: a name that already resolves to an account of this harness is
-    // a re-auth, not an add.
     const existing = findAddAccount(agent, name, meta);
     if (existing) {
         throw new Error(`${agent}#${existing.name} is already added. Re-auth with: agents accounts login ${agent}#${existing.name}`);
     }
-    // Validate the requested NAME before any install, slot, or login — a bad or
-    // colliding name never mints an orphan slot and drives a login that can't be
-    // recorded.
     if (name)
         registry.assertNativeAccountNameAvailable(name, agent);
     opts.onProgress?.(`Ensuring the ${agent} installation…`);
     await run.ensureInstallation(agent, opts.onProgress);
     lock.assertHeld();
-    // The slot is keyed by the account id, which only exists after registration —
-    // mint a pending id, then rename the dir onto the real id once the row lands.
     const pendingId = crypto.randomUUID();
     const slot = ensureSlot(agent, pendingId);
     const fail = (err) => {
@@ -359,8 +269,6 @@ async function _runAddLocked(agent, name, opts, lock, runners) {
         fail(err);
     }
     const identityKey = observed.identityKey;
-    // The completed login may be an identity already registered under another
-    // name — adding it again would split one identity across two slots.
     const duplicate = listNativeAccounts(readMeta()).find(a => a.agent === agent && a.identityKey === identityKey);
     if (duplicate) {
         fail(new Error(`This ${agent} login is already added as '${duplicate.name}'. Re-auth with: agents accounts login ${agent}#${duplicate.name}`));
@@ -383,7 +291,6 @@ async function _runAddLocked(agent, name, opts, lock, runners) {
         checkedAt: new Date().toISOString(),
     };
     recordSlot(account.id, record);
-    // Select this account as the harness default ONLY if none is configured.
     const becameDefault = registry.setDefaultAccountIfAbsent(agent, account.name);
     const warnings = [];
     const minted = await mintWorkerCredential(agent, account, finalDir, opts, run, warnings);
@@ -411,19 +318,7 @@ async function _runAddLocked(agent, name, opts, lock, runners) {
         warnings,
     };
 }
-/**
- * Drive one `agents accounts login <harness>#<name>`: re-auth into the SAME
- * slot (re-running add's steps 4–8), re-minting the worker credential and
- * re-syncing. On a per-device harness (worker `none`) any box may run it —
- * that IS how such a box logs in. `--per-device` extends that to a dual-path
- * harness (codex, grok): this box signs the account's subscription seat in for
- * itself through the device-code flow instead of using a portable key.
- */
 export async function runLogin(agent, name, opts, runners) {
-    // A harness with a portable worker credential authenticates workers from that
-    // credential, so the interactive re-login stays headed-only. A per-device
-    // harness (kimi), or a per-device login of a dual-path harness, is logged in
-    // per box BY DESIGN — any role may run it.
     if (opts.perDevice && !hasPerDeviceWorkerKind(agent))
         throw new Error(perDeviceRefusal(agent));
     if (hasPortableWorkerKind(agent) && !opts.perDevice)
@@ -455,8 +350,6 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
     }
     await run.ensureInstallation(agent, opts.onProgress);
     lock.assertHeld();
-    // The SAME slot: the recorded one, adopted (legacy account with none yet) or
-    // re-materialized if the dir is gone from disk.
     const recorded = readSlots(meta)[account.id];
     const home = recorded?.slotDir ?? slotDir(agent, account.id);
     if (!recorded || !fs.existsSync(home)) {
@@ -466,8 +359,6 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
             authMode: perDevice ? 'per-device' : 'native',
         });
     }
-    // Pre-launch guard: refuse to launch a login into a slot signed in as a
-    // DIFFERENT identity — that would overwrite some other login's home.
     const current = fs.existsSync(home) ? await run.observeIdentity(agent, home) : null;
     lock.assertHeld();
     if (current?.signedIn && current.identityKey && current.identityKey !== account.identityKey) {
@@ -477,8 +368,6 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
     const cap = harnessAuth(agent);
     const args = cap.login ?? [];
     if (args.length === 0) {
-        // No finite login command (kimi): launch the bare harness in the slot; the
-        // human completes the in-TUI login (`kimi`, then /login).
         opts.onProgress?.(`Launching ${loginHint(agent)} — complete the login there.`);
     }
     const login = await run.launchLogin(agent, { home, args, email: account.identityLabel, signal: lock.signal });
@@ -495,16 +384,12 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
     let provisioning = perDevice ? 'per-device' : (account.provisioning ?? 'portable');
     if (!perDevice) {
         if (opts.apiKey && workerApiKeyEnv(agent)) {
-            // Explicit rotation of the stored API key.
             const minted = await mintWorkerCredential(agent, account, home, opts, run, warnings);
             outcome = minted.outcome;
             ref = minted.ref;
             provisioning = minted.provisioning;
         }
         else if (!account.workerCredential || harnessWorkerKinds(agent).includes('setup-token')) {
-            // Claude re-mints (the setup-token drive can always mint fresh from the
-            // live login); an api-key harness with a stored key keeps it unless
-            // --api-key rotates it.
             const minted = await mintWorkerCredential(agent, account, home, opts, run, warnings);
             outcome = minted.outcome;
             ref = minted.ref;
@@ -552,7 +437,6 @@ async function _runLoginLocked(agent, name, opts, lock, runners) {
         warnings,
     };
 }
-/** Real runners: the install engine, an inherited-stdio login spawn, identity read, and the mint drive. */
 async function defaultAddRunners() {
     const [store, agentsMod, execMod] = await Promise.all([
         import('../installations/store.js'),
@@ -563,19 +447,13 @@ async function defaultAddRunners() {
     const { agentConfigDirName, getAccountInfo } = agentsMod;
     const { buildExecEnv } = execMod;
     const { runNativeAccountCommand } = await import('../installations/native-command.js');
-    // A slot is HOME-shaped; the harness's config dir lives directly inside it.
     const slotConfigDir = (agent, home) => path.join(home, agentConfigDirName(agent));
     const loginEnv = (agent, installLabel, home) => {
         const env = buildExecEnv({ agent, version: installLabel, configVersion: installLabel, interactive: true, mode: 'auto', effort: 'auto', cwd: process.cwd() });
-        // HOME = slot; the harness's slotEnv (CLAUDE_CONFIG_DIR / CODEX_HOME / …)
-        // pins its config dir inside the slot so the login lands there.
         env.HOME = home;
         const pin = harnessAuth(agent).slotEnv;
         if (pin)
             env[pin] = slotConfigDir(agent, home);
-        // Strip any ambient provider API-key / setup-token env so the native login
-        // authenticates as the human's OAuth identity, not an injected credential
-        // that would impersonate a different account into this slot.
         for (const key of PROVIDER_AUTH_ENV_KEYS)
             delete env[key];
         const workerEnv = workerApiKeyEnv(agent);
@@ -601,7 +479,6 @@ async function defaultAddRunners() {
                 identityKey: nativeIdentityKey(info, nativeAccountCapability(agent)),
                 email: info.email,
                 releaseVersion: readInstallation(agent, (await ensureHarnessInstallation(agent, {})).installation.label)?.releaseVersion ?? null,
-                // Strict: a live credential in THIS slot, not a bare metadata identity.
                 signedIn: isLaunchableSignedIn(agent, home, info),
             };
         },
@@ -635,9 +512,6 @@ async function defaultAddRunners() {
             }
         },
         requestReconcile: async () => {
-            // The daemon owns the tick; this queues a one-shot auth-sync restart so
-            // the reconcile runs now instead of at the next 15-minute cadence. A
-            // stopped daemon is fine — its next boot reconciles.
             try {
                 const [{ isDaemonRunning, signalDaemonReload }, { queueDaemonServiceRestart }] = await Promise.all([
                     import('../daemon/daemon.js'),
@@ -649,7 +523,6 @@ async function defaultAddRunners() {
                 signalDaemonReload();
             }
             catch {
-                // Best-effort request: the reconcile also happens on the regular cadence.
             }
         },
     };

package/dist/lib/accounts/auth-operation-lock.d.ts

@@ -5,5 +5,4 @@ export interface AuthOperationLock {
     assertHeld(): void;
     release(): void;
 }
-/** Uses the same lock primitive as configuration writes; no fail-open fallback. */
 export declare function acquireAuthOperationLock(agent: AgentId, stateDir?: string): AuthOperationLock;

package/dist/lib/accounts/auth-operation-lock.js

@@ -1,4 +1,3 @@
-/** Cross-process exclusion for native connect/logout, including browser waits. */
 import * as path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { ensureLockTarget } from '../fs-atomic.js';
@@ -9,7 +8,6 @@ export function authLockFilePath(agent, stateDir) {
         throw new Error('Unknown authentication harness.');
     return path.join(stateDir ?? getRuntimeStateDir(), `auth-op-lock-${agent}.json`);
 }
-/** Uses the same lock primitive as configuration writes; no fail-open fallback. */
 export function acquireAuthOperationLock(agent, stateDir) {
     const target = authLockFilePath(agent, stateDir);
     ensureLockTarget(target, '{}', 0o700);
@@ -20,8 +18,6 @@ export function acquireAuthOperationLock(agent, stateDir) {
         unlock = lockfile.lockSync(target, {
             stale: 10 * 60_000,
             update: 1_000,
-            // The primitive refreshes the lock while a browser flow awaits input.
-            // Acquisition is immediate: never silently queue native logins.
             onCompromised: (error) => {
                 compromised = new Error(`Authentication lock was lost: ${error.message}`);
                 controller.abort(compromised);

package/dist/lib/accounts/migrate.d.ts

@@ -29,7 +29,6 @@ interface MigrationAction {
     identityKey?: string | null;
     email?: string | null;
     sessionCount: number;
-    /** Planned filesystem remap for sessions.db (from prefix → to prefix). */
     pathMoves: Array<{
         from: string;
         to: string;
@@ -67,9 +66,7 @@ interface AccountMigrationManifest {
     schema: number;
     at: string;
     dryRun: boolean;
-    /** `planned` until every irreversible step finishes; `complete` is last. */
     status: AccountMigrationManifestStatus;
-    /** Full plan, written before the first move so a crash still names the intent. */
     plan: AccountMigrationPlan;
     harnesses: Record<string, {
         canonical: string | null;
@@ -89,7 +86,6 @@ interface AccountMigrationManifest {
             reason: string;
         }>;
     }>;
-    /** old `agent@label` → new slot dir (or trash path). */
     map: Record<string, string>;
 }
 interface AccountMigrateDeps {
@@ -108,10 +104,5 @@ interface ApplyMigrationResult {
     sessionsReindexed: number;
 }
 export declare function applyAccountMigration(agents?: AgentId[], deps?: AccountMigrateDeps): Promise<ApplyMigrationResult>;
-/**
- * Upgrade hook: print a dry-run report when leftover per-account installations
- * exist. Never applies. `--apply` stays an explicit `agents accounts migrate`
- * flag this release.
- */
 export declare function reportAccountSlotMigrationOnUpgrade(): Promise<void>;
 export {};

package/dist/lib/accounts/migrate.js

@@ -1,15 +1,3 @@
-/**
- * Fold N per-account installations into 1 harness install + N credential slots
- * (PHNX-3940 T7).
- *
- * Homes are moved, never copied. Empty logged-out homes and duplicate identities
- * go to `agents trash` (restore reverses). Session transcript paths are re-indexed
- * in the same transaction as the moves. A running/leased home is deferred, never
- * moved. `--apply` is explicit; dry-run (and the upgrade hook) touch nothing.
- *
- * Native OAuth files stay inside the moved home on this device. Nothing here
- * reads or writes a reserved store, a setup-token, or a worker bundle.
- */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { ALL_AGENT_IDS, credentialPresence, getAccountInfo } from '../agents.js';
@@ -163,13 +151,6 @@ async function duplicateTrashLabels(items) {
 function plannedTrashPath(agent, label) {
     return path.join(getHistoryDir(), 'trash', 'versions', agent, label, '<stamp>');
 }
-/**
- * Where a canonical install's stale `home/` goes when its account already holds
- * a slot: the binary and the (recreated, empty) home stay under `versions/`, so
- * the old home cannot use the versions trash — `agents trash restore` would put a
- * whole install back over a live one. Restoring is a plain move back; the
- * migration manifest records the path under `<agent>@<label>#home`.
- */
 function homeTrashDir(agent, label) {
     return path.join(getHistoryDir(), 'trash', 'homes', agent, label);
 }
@@ -297,14 +278,6 @@ async function planHarness(agent, deps) {
             continue;
         }
         if (item.hasCredential && item.accountId && provisionedSlotExists(agent, item.accountId)) {
-            // The account already owns a populated slot on this device, so this
-            // per-version home is a stale copy of a credential the slot now carries.
-            // Routing it to `slot` would only trip `assertSlotAbsent` and abort the
-            // whole apply with nothing done — the state every auth-synced worker was
-            // in. Trash it instead (`agents trash restore` reverses). The canonical
-            // install keeps its binary and ends up with an empty home, exactly as it
-            // does when its home is the one that moves into the slot: two on-disk
-            // copies of one credential is not an end state the migration leaves.
             if (canonical && item.label === canonical.label) {
                 actions.push({
                     kind: 'canonical',
@@ -375,8 +348,6 @@ async function planHarness(agent, deps) {
     }
     const counts = {
         installations: inventory.length,
-        // A busy canonical is still the kept install — we did not move it, we
-        // deferred the fold. Counting it as 0 install is a lie.
         keep: actions.filter((a) => a.kind === 'canonical'
             || ((a.kind === 'slot' || a.kind === 'defer') && a.label === canonical?.label)).length,
         slots: actions.filter((a) => a.kind === 'slot').length,
@@ -387,6 +358,8 @@ async function planHarness(agent, deps) {
     return { agent, canonical: canonical?.label ?? null, defaultBefore, inventory, actions, counts };
 }
 export async function planAccountMigration(agents = [...ALL_AGENT_IDS], deps = {}) {
+    // Move rather than copy credential-bearing homes, defer running/leased homes,
+    // and keep planning/upgrade probes free of migration side effects.
     const harnesses = [];
     for (const agent of agents) {
         const plan = await planHarness(agent, deps);
@@ -453,8 +426,6 @@ function rewriteBindings(agent, labelToAccount, stillPresent) {
         if (!row) {
             throw new Error(`Cannot rewrite binding '${target}': account '${accountId}' is missing.`);
         }
-        // Keep the per-target key (`agent@label` → account id). Collapsing every
-        // label onto one bare-agent binding would drop every account after the first.
         bindAccount(row.id, target, agent);
     }
 }
@@ -503,6 +474,7 @@ function harnessManifest(manifest, agent, canonical) {
     return created;
 }
 export async function applyAccountMigration(agents = [...ALL_AGENT_IDS], deps = {}) {
+    // Apply only an explicit plan; transcript-bearing homes must retain one owner.
     const plan = await planAccountMigration(agents, deps);
     const now = deps.now ?? (() => new Date());
     const at = now();
@@ -572,9 +544,6 @@ export async function applyAccountMigration(agents = [...ALL_AGENT_IDS], deps =
                 labelToAccount.set(item.label, kept);
         }
         for (const action of h.actions.filter((a) => a.kind === 'canonical' && a.accountId)) {
-            // Canonical install whose account already holds a slot: hand the stale
-            // home off to the homes trash and leave an empty home behind, mirroring
-            // the slot branch's end state for a canonical home.
             const item = byLabel.get(action.label);
             if (!item)
                 throw new Error(`Plan named ${h.agent}@${action.label} but inventory has no such install.`);
@@ -597,9 +566,6 @@ export async function applyAccountMigration(agents = [...ALL_AGENT_IDS], deps =
             remaps.push({ from: item.dir, to: trashPath });
             stillPresent.delete(item.label);
             if (action.accountId) {
-                // A home trashed because its account already holds a slot: anything
-                // bound to this version label follows the account, and the stale
-                // home record clears so spawn resolves through the slot alone.
                 labelToAccount.set(item.label, action.accountId);
                 movedAccountIds.push(action.accountId);
             }
@@ -618,11 +584,6 @@ export async function applyAccountMigration(agents = [...ALL_AGENT_IDS], deps =
     persistManifest(manifestPath, manifest);
     return { plan, manifest, manifestPath, sessionsReindexed };
 }
-/**
- * Upgrade hook: print a dry-run report when leftover per-account installations
- * exist. Never applies. `--apply` stays an explicit `agents accounts migrate`
- * flag this release.
- */
 export async function reportAccountSlotMigrationOnUpgrade() {
     const plan = await planAccountMigration();
     const work = plan.totals.slots + plan.totals.trash + plan.totals.deferred;