@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/account-registry.js

@@ -1,21 +1,3 @@
-/**
- * Credential accounts, stored as canonical `agents secrets` bundles (RUSH-2470).
- *
- * One account IS one bundle: the bundle label is the account name, its vars
- * carry the identity (ACCOUNT_ID / PROVIDER / AUTH_TYPE / optional BASE_URL)
- * and the secret (API_KEY or TOKEN), and it uses the `never` prompt policy so
- * it reads headlessly and syncs across the fleet with no Touch ID. The bundle
- * shape lives in [[account-schema]]; this module owns the CRUD, resolution,
- * and the one-time migration off the legacy `accounts.yaml`.
- *
- * `readAccountRegistry()` still returns the historical
- * `{ version: 2, accounts }` view so existing consumers (harness, profiles,
- * exec) keep working — it is now a projection over the account bundles, not a
- * file read. Native OAuth logins are NOT accounts here; they stay native and
- * surface through unified discovery in [[account-catalog]]. Labels bind to
- * `(agent, identityKey)` on the central `accounts.native` rows in agents.yaml,
- * which `agents repo push/pull` already syncs fleet-wide.
- */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
@@ -56,7 +38,6 @@ function toCredentialAccount(record) {
         baseUrl: record.baseUrl,
     };
 }
-/** Every account bundle currently on this device, keyed by stable id. */
 function readAccountBundles() {
     const out = [];
     for (const bundle of listBundlesSync()) {
@@ -66,22 +47,15 @@ function readAccountBundles() {
     }
     return out;
 }
-/**
- * Fold a legacy `accounts.yaml` into account bundles, then archive it.
- * Transactional: every bundle is written first, and the file is archived (and
- * the old per-account keychain items dropped) ONLY after all writes succeed —
- * so an interrupted migration leaves the file in place and the next read
- * retries, skipping accounts that already landed as a bundle.
- */
 function migrateLegacyRegistryFile(base) {
+    // Credential accounts live in policy-never bundles; AccountRegistryDocument is only a compatibility projection.
+    // Migration writes all bundles first, skips identical retry writes, and removes legacy data only after total success.
     const file = accountRegistryPath(base);
     if (!fs.existsSync(file))
         return;
     const raw = yaml.parse(fs.readFileSync(file, 'utf8'));
     if (!raw || Array.isArray(raw))
         throw new Error(`Account registry corrupted at ${file}: expected a YAML map.`);
-    // Legacy version-bound labels (pre-credential-accounts) are not credentials —
-    // archive them so they are never resurrected as fake accounts.
     if (raw.version === undefined && raw.labels !== undefined) {
         archiveLegacyFile(file, 'accounts.legacy-labels.yaml');
         return;
@@ -108,18 +82,16 @@ function migrateLegacyRegistryFile(base) {
             if (!existing || existing.id !== id) {
                 throw new Error(`Cannot migrate account '${name}': a different secrets bundle already uses that name.`);
             }
-            continue; // already migrated on an earlier, interrupted run
+            continue;
         }
         const baseUrl = item.baseUrl ? String(item.baseUrl) : undefined;
         const record = { id, name, provider, auth, baseUrl };
         const secret = hasKeychainTokenSync(legacySecretRef) ? getKeychainTokenSync(legacySecretRef) : '';
         const { bundle, items } = buildAccountBundle(record, secret || 'x');
         if (!secret)
-            items.clear(); // no device-local secret: write metadata only
+            items.clear();
         writeBundleWithItemsSync(bundle, items);
     }
-    // Success: the file's accounts all exist as bundles now. Archive it and drop
-    // the superseded per-account keychain items.
     archiveLegacyFile(file, 'accounts.migrated.yaml');
     for (const legacyItem of retiredSecretItems)
         deleteKeychainTokenSync(legacyItem);
@@ -140,55 +112,21 @@ export function readAccountRegistry(base = getUserAgentsDir()) {
 export function findAccount(name, doc = readAccountRegistry()) {
     return doc.accounts[name] ?? Object.values(doc.accounts).find(account => account.name === name) ?? null;
 }
-/**
- * Effective native accounts: the fleet-shared central store (version-scoped
- * identities) merged with THIS box's own device doc (device-scoped identities).
- * A native login is machine-local — its home follows its scope (PHNX-3315), so
- * a `scope:'device'` identity is read from this box's device doc and never the
- * shared central agents.yaml (which is where its email/identityKey PII used to
- * accumulate). On an id collision the device slice wins.
- */
 export function listNativeAccounts(meta) {
     const merged = { ...meta.accounts?.native, ...meta.deviceAccounts?.native };
     return Object.values(merged).map(account => ({ ...account, kind: 'native' }));
 }
-/**
- * The native account registered for one harness login, or null when that login
- * is unnamed. `info` is the login's identity as `getAccountInfo` /
- * `readClaudeHomeConfig` report it; the match key is the same value every
- * catalog and inventory groups a home on — the stable `accountKey`, else the
- * lowercased email. The one lookup behind `agents view`, the device
- * inventories, and the Claude status line.
- */
 export function findNativeAccountByIdentity(meta, agent, info) {
+    // Stable accountKey must win; normalized email is only the key-less fallback shared by view, inventory, and statusline.
     const identityKey = info?.accountKey ?? info?.email?.toLowerCase();
     if (!identityKey)
         return null;
     return listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey) ?? null;
 }
-/**
- * Resolve one account by name or id across both stores, native first.
- *
- * `doc` is optional and read LAZILY: a native match returns without ever reading
- * the provider bundle registry — so a native view/attach/run never triggers a
- * bundle read, legacy-`accounts.yaml` migration, or a keychain decrypt (which
- * would surface a Touch ID prompt or crash on an undecryptable legacy item). A
- * default-evaluated `doc = readAccountRegistry()` argument would defeat this by
- * running before the body, so callers that only need a native lookup must be
- * able to omit it.
- */
 export function findUnifiedAccount(nameOrId, meta, doc, preferAgent) {
+    // Native matches return before bundle/keychain reads; preferAgent resolves shared labels for the launched harness.
     const needle = nameOrId.toLowerCase();
     const matches = listNativeAccounts(meta).filter(account => account.id === nameOrId || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle);
-    // `identityLabel` defaults to the login's own identifier (the email), so ONE
-    // selector legitimately matches several harnesses: `muqsitnawaz@gmail.com` is a
-    // claude login AND a codex login. Un-scoped, `.find()` returned whichever row the
-    // merged store happened to order first, so `agents run claude#<email>` died with
-    // "Account 'personal' is a codex login and cannot authenticate the claude harness"
-    // while that identity's own claude login sat right there. Prefer the harness being
-    // launched; fall back to the first match when the caller has no harness in hand.
-    // rename/remove/view refuse an ambiguous *name* via assertUnambiguousNativeAccount
-    // before they get here — this fallback is for identityLabel collisions.
     const native = matches.find(account => account.agent === preferAgent) ?? matches[0];
     if (native)
         return native;
@@ -198,12 +136,6 @@ export function findUnifiedAccount(nameOrId, meta, doc, preferAgent) {
 function nativeIdentityRows(meta, agent, identityKey) {
     return listNativeAccounts(meta).filter(account => account.agent === agent && account.identityKey === identityKey);
 }
-/**
- * Split a management selector into its harness and name. `<harness>#<name>`
- * pins the harness; a bare name (or row id) carries none. Native names are
- * unique per harness (PHNX-3887), so a bare name alone can legitimately match a
- * claude row AND a codex row — the selector is how rename/remove say which.
- */
 export function parseAccountSelector(input) {
     const hash = input.indexOf('#');
     if (hash < 0)
@@ -216,12 +148,6 @@ export function parseAccountSelector(input) {
         throw new Error('Select an account after #.');
     return { agent: agentRaw, name };
 }
-/**
- * Refuse a bare name that native rows in several harnesses share. A
- * harness-qualified selector (`agent` set) never hits this — uniqueness is
- * per harness. Ids are unique so they never collide either. Shared by
- * rename/remove/view so the message stays one string.
- */
 export function assertUnambiguousNativeAccount(meta, name, agent) {
     const matches = listNativeAccounts(meta).filter(account => (agent === undefined || account.agent === agent) && (account.id === name || account.name === name));
     const harnesses = [...new Set(matches.map(account => account.agent))].sort();
@@ -230,10 +156,6 @@ export function assertUnambiguousNativeAccount(meta, name, agent) {
             + `Pick one with <harness>#${name}, e.g. ${harnesses[0]}#${name}.`);
     }
 }
-/** Every row (central + this box's device store) for the identity that `name`
- * (id or account name) resolves to. With `agent` set only that harness's rows
- * are considered; without it, a name owned by rows in several harnesses is
- * refused rather than resolved to whichever the store ordered first. */
 function nativeRowsForNameOrId(meta, name, agent) {
     assertUnambiguousNativeAccount(meta, name, agent);
     const matches = listNativeAccounts(meta).filter(account => (agent === undefined || account.agent === agent) && (account.id === name || account.name === name));
@@ -242,23 +164,6 @@ function nativeRowsForNameOrId(meta, name, agent) {
         return [];
     return nativeIdentityRows(meta, found.agent, found.identityKey);
 }
-/**
- * Native label names are unique per HARNESS, not globally (PHNX-3887).
- *
- * One human identity is commonly signed into several harnesses —
- * `muqsitnawaz@icloud.com` is a claude login AND a codex login AND a grok login.
- * A global namespace let whichever harness was labelled first squat the good
- * name, forcing prefixed junk (`cxicloud`, `gkicloud`) on the rest. Nothing is
- * actually ambiguous at the point of use: the selector is `<harness>#<label>`,
- * and `findUnifiedAccount` already disambiguates via `preferAgent`.
- *
- * Pass `agent` to scope the check to that harness. Every native path has one
- * in hand — connect/label from the caller, rename from the row being renamed —
- * so the un-scoped form is only for provider accounts.
- *
- * Provider (non-native) accounts stay globally unique — they are selected by
- * bare name via `--account`, with no harness to scope them by.
- */
 function assertUniqueUnifiedName(name, meta, doc, exceptIds, agent) {
     const needle = name.toLowerCase();
     const nativeHits = listNativeAccounts(meta).filter(account => (agent === undefined || account.agent === agent)
@@ -268,25 +173,18 @@ function assertUniqueUnifiedName(name, meta, doc, exceptIds, agent) {
             ? `Account '${name}' already exists.`
             : `Account '${name}' already exists for the ${agent} harness.`);
     }
-    // Same laziness as findUnifiedAccount: a native row that already owns this
-    // name (even one we are mutating) means we never open the provider store.
     if (nativeHits.length > 0)
         return;
     const provider = findAccount(name, doc ?? readAccountRegistry());
     if (provider && !exceptIds?.has(provider.id))
         throw new Error(`Account '${name}' already exists.`);
 }
-/**
- * Validate a native account NAME (charset + per-harness uniqueness) WITHOUT a
- * known identity — the pre-flight `agents accounts add` runs before it
- * installs a home and drives a login, so a bad/colliding name fails before any
- * side effect instead of orphaning a freshly-minted home (PHNX-3940).
- */
 export function assertNativeAccountNameAvailable(name, agent) {
     assertNativeLabel(name);
     assertUniqueUnifiedName(name, readMeta(), undefined, undefined, agent);
 }
 export function addNativeAccount(name, agent, identityKey, identityLabel, scope) {
+    // Device-scoped identity belongs in the device document and must not propagate through central metadata.
     assertNativeLabel(name);
     const meta = readMeta();
     assertUniqueUnifiedName(name, meta, undefined, undefined, agent);
@@ -295,9 +193,6 @@ export function addNativeAccount(name, agent, identityKey, identityLabel, scope)
         throw new Error(`This ${agent} login is already named '${duplicate.name}'.`);
     const account = { id: crypto.randomUUID(), name, kind: 'native', agent, identityKey, identityLabel, scope };
     const entry = { id: account.id, name, agent, identityKey, identityLabel, scope };
-    // A native login's home follows its scope (PHNX-3315): a device-scoped
-    // identity lands in THIS box's device doc (its PII never touches the shared
-    // central agents.yaml); a version-scoped one stays in the fleet-shared store.
     if (scope === 'device') {
         updateMeta(current => ({
             ...current,
@@ -318,7 +213,6 @@ export function addNativeAccount(name, agent, identityKey, identityLabel, scope)
     }
     return account;
 }
-/** Create or replace the version-independent label for one native identity. */
 export function labelNativeAccount(agent, identityKey, identityLabel, label, scope) {
     const resolvedLabel = label ?? identityLabel;
     if (!resolvedLabel)
@@ -329,10 +223,6 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
     assertUniqueUnifiedName(resolvedLabel, meta, undefined, new Set(matches.map(account => account.id)), agent);
     if (matches.length === 0)
         return addNativeAccount(resolvedLabel, agent, identityKey, identityLabel, scope);
-    // Sweep every row for this identity (PHNX-3206), routing the whole sweep to the
-    // store that owns them: all rows for one identityKey share a scope (same agent),
-    // so a device-scoped login lands in this box's device doc, a version-scoped one
-    // in central (PHNX-3315).
     const rowScope = matches[0].scope;
     updateMeta(current => {
         if (rowScope === 'device') {
@@ -348,32 +238,17 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
     });
     return { ...matches[0], name: resolvedLabel, identityLabel, scope: rowScope };
 }
-/**
- * This box's recorded home LABEL for an account, or null.
- * Reads the leftover device-scoped `homes` map so legacy `acct-*` installation
- * labels still resolve (T5/T7); spawn-time HOME is {@link readSlots}[id].slotDir.
- */
 export function nativeAccountHome(accountId, meta) {
     return meta.deviceAccounts?.homes?.[accountId] ?? null;
 }
-/**
- * Set the per-harness default account by NAME only when none is configured
- * (PHNX-3940). Never overrides an existing choice — a first connect selecting a
- * default is a convenience, not a takeover. Returns whether it set the default.
- *
- * The check-then-write is performed INSIDE the `updateMeta` callback so two
- * concurrent callers (concurrent Promises or back-to-back calls on an async
- * boundary) cannot both observe "no default" and then both set themselves. Only
- * the first write wins; the second callback sees the first's write and returns
- * the current state unchanged.
- */
 export function setDefaultAccountIfAbsent(agent, name) {
+    // Compare-and-set preserves concurrent and legacy defaults.
     let set = false;
     updateMeta(current => {
         if (current.accounts?.defaults?.[agent])
-            return current; // already set — no-op
+            return current;
         if (current.agents?.[agent] || current.isolatedAgents?.[agent])
-            return current; // preserve a legacy home default
+            return current;
         set = true;
         return {
             ...current,
@@ -384,16 +259,9 @@ export function setDefaultAccountIfAbsent(agent, name) {
 }
 export function bindAccount(nameOrId, target, preferAgent) {
     const meta = readMeta();
-    // Scope to the harness being bound to: a bare identity selector matches every
-    // harness it is signed into, so without this the binding could persist against
-    // a different harness's row than the caller validated (the attach command
-    // resolves `targetAgent` and passes it here).
     const account = findUnifiedAccount(nameOrId, meta, undefined, preferAgent);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
-    // A binding follows its account: one that targets a device-scoped native login
-    // is itself machine-local and lands in this box's device doc (PHNX-3315);
-    // every other binding stays fleet-shared in central.
     if (account.kind === 'native' && account.scope === 'device') {
         updateMeta(current => ({
             ...current,
@@ -410,8 +278,6 @@ export function bindAccount(nameOrId, target, preferAgent) {
 }
 export function unbindAccount(nameOrId, target, preferAgent) {
     const meta = readMeta();
-    // Same scoping as bindAccount: detach the row on the harness the caller means,
-    // not whichever the store happened to order first for a colliding identity.
     const account = findUnifiedAccount(nameOrId, meta, undefined, preferAgent);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
@@ -434,19 +300,14 @@ export function unbindAccount(nameOrId, target, preferAgent) {
         return next;
     });
 }
-/** Every target bound to `accountId`: this box's device-doc bindings merged over
- * the fleet-shared central bindings (PHNX-3315). */
 export function accountBindings(accountId, meta) {
     const merged = { ...meta.accounts?.bindings, ...meta.deviceAccounts?.bindings };
     return Object.entries(merged).filter(([, id]) => id === accountId).map(([target]) => target).sort();
 }
-/** Explicit selection wins over a configured per-harness default. */
 export function resolveAccountSelection(explicit, agent, meta, opts = {}) {
+    // Device bindings override central bindings; missing explicit/bound accounts fail loud, while a stale default returns to balanced rotation.
     if (explicit)
         return { id: explicit, source: 'explicit' };
-    // This box's device-doc bindings win over the fleet-shared central bindings
-    // (PHNX-3315), so a per-box account attachment resolves without touching the
-    // shared file. Defaults are genuinely fleet-shared and stay central.
     const bindings = { ...meta.accounts?.bindings, ...meta.deviceAccounts?.bindings };
     const bound = opts.target ? bindings[opts.target] : undefined;
     if (bound)
@@ -498,34 +359,23 @@ export function setAccountSecret(name, secret, base = getUserAgentsDir()) {
     getAccountProvider(account.provider).validate(account.auth, secret);
     const record = { id: account.id, name: account.name, provider: account.provider, auth: account.auth, baseUrl: account.baseUrl };
     const { bundle, items } = buildAccountBundle(record, secret);
-    bundle.created_at = readBundleSync(account.name).created_at; // rotate the secret, keep the bundle's birth time
+    bundle.created_at = readBundleSync(account.name).created_at;
     writeBundleWithItemsSync(bundle, items);
 }
-/**
- * `oldSelector` is a bare name, a row id, or `<harness>#<name>`. A native row
- * carries its harness, so the new name only has to be free within THAT harness
- * (PHNX-3887 / PHNX-3988): renaming codex's `cxicloud` to `icloud` is fine
- * while claude's `icloud` stays untouched. Provider accounts have no harness
- * and stay globally unique.
- */
 export function renameAccount(oldSelector, newName, base = getUserAgentsDir()) {
     assertName(newName);
     const meta = readMeta();
     const selector = parseAccountSelector(oldSelector);
     const rows = nativeRowsForNameOrId(meta, selector.name, selector.agent);
     if (rows.length) {
+        // Sweep every identity row in its owning store; bare-name defaults rewrite only within this harness, while ids are global.
         assertUniqueUnifiedName(newName, meta, undefined, new Set(rows.map(account => account.id)), rows[0].agent);
-        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315)
-        // and any per-harness default that points to the old name or row ids.
         const rowScope = rows[0].scope;
         const renamedAgent = rows[0].agent;
         const renamedIds = new Set(rows.map(row => row.id));
         updateMeta(current => {
             const defaults = { ...current.accounts?.defaults };
             for (const [agent, value] of Object.entries(defaults)) {
-                // Ids are unique so an id match may rewrite any harness's default. A
-                // bare-name match must only rewrite THIS harness — two harnesses may
-                // legitimately share the same native name (PHNX-3988).
                 if (renamedIds.has(value) || (agent === renamedAgent && value === selector.name))
                     defaults[agent] = newName;
             }
@@ -562,10 +412,9 @@ export function renameAccount(oldSelector, newName, base = getUserAgentsDir()) {
         }
         return { ...current, accounts: { ...current.accounts, defaults } };
     });
-    renameBundleSync(account.name, newName); // moves metadata + secret, preserves ACCOUNT_ID
+    renameBundleSync(account.name, newName);
     renameProfileConsumers(account.name, newName, base);
 }
-/** `selector` is a bare name, a row id, or `<harness>#<name>` (see {@link renameAccount}). */
 export function removeAccount(selector, base = getUserAgentsDir()) {
     const meta = readMeta();
     const parsed = parseAccountSelector(selector);
@@ -575,10 +424,8 @@ export function removeAccount(selector, base = getUserAgentsDir()) {
         if (bindings.length)
             throw new Error(`Account '${rows[0].name}' is attached to: ${bindings.join(', ')}. Detach it before removing it.`);
         const ids = new Set(rows.map(row => row.id));
-        // Sweep every row for the identity (PHNX-3206) from its owning store (PHNX-3315).
         const rowScope = rows[0].scope;
         updateMeta(current => {
-            // Drop this box's connect-home and slot records for the removed account (PHNX-3940).
             const homes = { ...current.deviceAccounts?.homes };
             const slots = { ...current.deviceAccounts?.slots };
             for (const id of ids) {
@@ -639,11 +486,6 @@ export function resolveCredentialAccount(name, host, expectedProvider, base = ge
     if (!hasKeychainTokenSync(account.secretRef))
         throw new Error(`Credential for account '${account.name}' is missing on this device. Add it with 'agents accounts set-key ${account.name}'.`);
     const secretVar = secretVarFor(account.auth);
-    // Account bundles are policy `never`, so their value items carry no biometry
-    // ACL. Resolve through the bundle path that verifies that policy and attests
-    // `silentNoAcl` to the headless keychain guard. Calling getKeychainTokenSync()
-    // directly makes a headless --account launch reject the prompt-free item as
-    // if it required Touch ID before the helper ever reads it (PHNX-2939).
     const secret = readAndResolveBundleEnvSync(account.name, {
         keys: [secretVar],
         keyMode: 'storage',
@@ -665,11 +507,6 @@ export function resolveCredentialAccount(name, host, expectedProvider, base = ge
         env: { ...connectionEnv, [envVar]: secret },
     };
 }
-/**
- * Sync fallback: scan installed version homes to discover a native identity
- * that matches the given email, for accounts that predate the registration
- * system (empty `accounts.native`). Returns a synthetic SpawnAccount or null.
- */
 function discoverUnregisteredNativeAccount(email, agent) {
     if (agent !== 'claude')
         return null;
@@ -710,24 +547,15 @@ function discoverUnregisteredNativeAccount(email, agent) {
  * fails loudly (EXEC-ACCOUNT-4). Returns null when nothing is selected.
  */
 export function resolveSpawnAccount(explicit, agent, version, meta, opts = {}) {
-    // The binding lookup key. A custom harness passes its own profile/harness name
-    // (a run of `deepseek` must find a binding on `deepseek`, not `claude@x`); a
-    // native/global run keys on the exact `agent@version` installation.
     const target = opts.target ?? (version ? `${agent}@${version}` : agent);
     const selection = resolveAccountSelection(explicit, agent, meta, { useDefault: opts.useDefault, target });
     if (!selection)
         return null;
-    // Scope the lookup to the harness being launched: a bare identity selector
-    // (`claude#muqsitnawaz@gmail.com`) matches every harness that identity is signed
-    // into, and only this one can authenticate the spawn.
     let unified = findUnifiedAccount(selection.id, meta, undefined, agent);
     if (!unified && selection.source === 'explicit' && selection.id.includes('@')) {
         unified = discoverUnregisteredNativeAccount(selection.id, agent);
     }
     if (!unified) {
-        // A stale per-harness default is a preference, not a hard requirement: the
-        // machine stays runnable by falling back to balanced rotation. Bindings and
-        // explicit --account are intentional, so they still fail loud.
         if (selection.source === 'default') {
             process.stderr.write(chalk.yellow(`[agents] default account '${selection.id}' for ${agent} no longer exists on this machine; falling back to balanced selection. Clear the stale default with: agents accounts clear-default ${agent}\n`));
             return null;
@@ -741,9 +569,6 @@ export function resolveSpawnAccount(explicit, agent, version, meta, opts = {}) {
         if (unified.agent !== agent) {
             throw new Error(`Account '${unified.name}' is a ${unified.agent} login and cannot authenticate the ${agent} harness.`);
         }
-        // A provider-backed custom harness still injects its provider auth env, so a
-        // native identity claim over it is incoherent — reject before spawn even when
-        // the account is chosen explicitly with --account (which bypasses `attach`).
         if (opts.provider) {
             throw new Error(`Account '${unified.name}' is a native ${unified.agent} login and cannot run under a provider-backed harness (${opts.provider}); the harness's ${opts.provider} credentials would still be injected. Use a matching provider account.`);
         }

package/dist/lib/account-schema.d.ts

@@ -1,6 +1,5 @@
 import type { SecretsBundle } from './secrets-types.js';
 import type { AccountAuthKind } from './account-provider-registry.js';
-/** Canonical bundle variable names for a provider-account bundle. */
 export declare const ACCOUNT_VARS: {
     readonly id: "ACCOUNT_ID";
     readonly provider: "PROVIDER";
@@ -9,12 +8,7 @@ export declare const ACCOUNT_VARS: {
     readonly apiKey: "API_KEY";
     readonly token: "TOKEN";
 };
-/**
- * Account bundles are stored with the `never` prompt policy: no biometry ACL,
- * so reads are silent and the bundle syncs across the fleet without Touch ID.
- */
 export declare const ACCOUNT_POLICY: "never";
-/** The parsed identity of an account, independent of where its bytes live. */
 export interface AccountSchemaRecord {
     id: string;
     name: string;
@@ -22,23 +16,10 @@ export interface AccountSchemaRecord {
     auth: AccountAuthKind;
     baseUrl?: string;
 }
-/** The single secret var name that carries the credential for an auth kind. */
 export declare function secretVarFor(auth: AccountAuthKind): 'API_KEY' | 'TOKEN';
-/** The keychain item that stores an account bundle's secret value. */
 export declare function accountSecretItem(name: string, auth: AccountAuthKind): string;
-/**
- * Build the canonical account bundle plus the keychain item map holding its
- * secret. The identity vars are literals; the secret var is a `keychain:` ref
- * whose value lives in the returned item map, ready for `writeBundleWithItems`.
- */
 export declare function buildAccountBundle(record: AccountSchemaRecord, secret: string): {
     bundle: SecretsBundle;
     items: Map<string, string>;
 };
-/**
- * Parse an account record from a bundle, or null when the bundle is not an
- * account bundle (missing ACCOUNT_ID / PROVIDER / a known AUTH_TYPE). The
- * catalog uses the null return to keep ordinary secrets bundles out of the
- * account list.
- */
 export declare function parseAccountBundle(bundle: SecretsBundle): AccountSchemaRecord | null;

package/dist/lib/account-schema.js

@@ -1,27 +1,4 @@
-/**
- * Canonical on-disk shape of a provider credential account.
- *
- * RUSH-2470 makes a `agents secrets` bundle the single source of truth for a
- * credential account: one account IS one bundle. The bundle's label is the
- * account name; its variables carry the account's identity plus its secret:
- *
- *   ACCOUNT_ID   the stable UUID (a literal, survives rename)
- *   PROVIDER     the provider id (a literal, e.g. 'openrouter')
- *   AUTH_TYPE    'api-key' | 'setup-token' | 'bearer-token' (a literal)
- *   BASE_URL     optional endpoint override (a literal)
- *   API_KEY      the secret, for AUTH_TYPE 'api-key'      (a keychain ref)
- *   TOKEN        the secret, for setup-token/bearer-token (a keychain ref)
- *
- * The identity vars are non-secret literals stored inline in the bundle
- * metadata; only API_KEY / TOKEN reference a keychain-backed value. Account
- * bundles use the `never` prompt policy so their values carry no biometry ACL
- * and sync (and read headlessly) with no Touch ID — the whole point of the
- * change. This module is pure: it builds a bundle from a record and parses a
- * record back out, with no I/O. The registry ([[account-registry]]) owns
- * reads and writes; the catalog ([[account-catalog]]) owns discovery.
- */
 import { parseBundleValue, secretsKeychainItem } from './secrets-client.js';
-/** Canonical bundle variable names for a provider-account bundle. */
 export const ACCOUNT_VARS = {
     id: 'ACCOUNT_ID',
     provider: 'PROVIDER',
@@ -30,20 +7,13 @@ export const ACCOUNT_VARS = {
     apiKey: 'API_KEY',
     token: 'TOKEN',
 };
-/**
- * Account bundles are stored with the `never` prompt policy: no biometry ACL,
- * so reads are silent and the bundle syncs across the fleet without Touch ID.
- */
 export const ACCOUNT_POLICY = 'never';
-/** The single secret var name that carries the credential for an auth kind. */
 export function secretVarFor(auth) {
     return auth === 'api-key' ? ACCOUNT_VARS.apiKey : ACCOUNT_VARS.token;
 }
-/** The keychain item that stores an account bundle's secret value. */
 export function accountSecretItem(name, auth) {
     return secretsKeychainItem(name, secretVarFor(auth));
 }
-/** Read a bundle var as a literal string, or undefined if it is a secret ref. */
 function literalOf(raw) {
     if (raw === undefined)
         return undefined;
@@ -53,11 +23,6 @@ function literalOf(raw) {
 function isAccountAuthKind(value) {
     return value === 'api-key' || value === 'setup-token' || value === 'bearer-token';
 }
-/**
- * Build the canonical account bundle plus the keychain item map holding its
- * secret. The identity vars are literals; the secret var is a `keychain:` ref
- * whose value lives in the returned item map, ready for `writeBundleWithItems`.
- */
 export function buildAccountBundle(record, secret) {
     const secretVar = secretVarFor(record.auth);
     const vars = {
@@ -66,20 +31,12 @@ export function buildAccountBundle(record, secret) {
         [ACCOUNT_VARS.authType]: record.auth,
         [secretVar]: `keychain:${secretVar}`,
     };
-    // Wrap BASE_URL as an escaped literal so a URL that happens to start with a
-    // ref prefix (e.g. 'env://…') is never misread as a secret reference.
     if (record.baseUrl)
         vars[ACCOUNT_VARS.baseUrl] = { value: record.baseUrl };
     const bundle = { name: record.name, policy: ACCOUNT_POLICY, vars };
     const items = new Map([[secretsKeychainItem(record.name, secretVar), secret]]);
     return { bundle, items };
 }
-/**
- * Parse an account record from a bundle, or null when the bundle is not an
- * account bundle (missing ACCOUNT_ID / PROVIDER / a known AUTH_TYPE). The
- * catalog uses the null return to keep ordinary secrets bundles out of the
- * account list.
- */
 export function parseAccountBundle(bundle) {
     const id = literalOf(bundle.vars[ACCOUNT_VARS.id]);
     const provider = literalOf(bundle.vars[ACCOUNT_VARS.provider]);

package/dist/lib/accounting/account-launch.d.ts

@@ -1,29 +1,18 @@
 import type { AgentId, Meta } from '../types.js';
 import { type RotateCandidate } from './rotate.js';
 type ResolvedLaunchAccountKind = 'native' | 'provider' | 'legacy-native';
-/** Safe account identity that may be passed between launch consumers. */
 interface ResolvedLaunchAccount {
     kind: ResolvedLaunchAccountKind;
-    /** Stable registry id, or the durable identity key for an unmigrated login. */
     id: string;
-    /** User-facing account name, falling back to the durable identity label. */
     name: string;
-    /** Selector another device may resolve against its own registry. */
     selector: string;
-    /** Stable anti-collision/failover key; never derived from the binary label. */
     key: string;
 }
-/**
- * One fully-resolved spawn attempt. `env` may contain credential material and
- * `execHome` is a device-local path, so this type is confined to the local exec
- * boundary. Events and remote callers use {@link ResolvedLaunchAccount} only.
- */
 export interface ResolvedLocalAccountLaunch {
     agent: AgentId;
     executableVersion: string;
     account: ResolvedLaunchAccount | null;
     execHome?: string;
-    /** Compatibility label for an explicitly recorded, unmigrated home. */
     configVersion?: string;
     env: Record<string, string>;
     signedIn: boolean | null;
@@ -31,13 +20,9 @@ export interface ResolvedLocalAccountLaunch {
 }
 interface ResolveLocalAccountLaunchOptions {
     agent: AgentId;
-    /** Selects the executable only. It never chooses account state. */
     executableVersion: string;
-    /** Exact account candidate selected by strategy/picker/readiness. */
     candidate?: RotateCandidate;
-    /** Explicit account name/id (`--account`, `#name`, or a consumer intent). */
     selector?: string;
-    /** Resolve the harness default when no explicit selector/candidate exists. */
     useDefault?: boolean;
     provider?: string;
     target?: string;

package/dist/lib/accounting/account-launch.js

@@ -48,10 +48,8 @@ export async function resolveLocalAccountLaunch(options) {
     const meta = options.meta ?? readMeta();
     const selected = options.candidate;
     const selector = options.selector ?? (selected ? candidateSelector(selected) : undefined);
-    // Compatibility for a candidate already discovered in an unmigrated home.
-    // The candidate is the identity decision; the label only locates that exact
-    // local config home and never participates in account comparison.
     if (selected && !selector) {
+        // Legacy labels locate an exact local home; they are not rediscovered identities.
         const execHome = getVersionHomePath(options.agent, selected.version);
         if (!fs.existsSync(execHome)) {
             throw new Error(`${selected.accountLabel || options.agent} has no local account home at ${execHome}.`);

package/dist/lib/accounting/account-pool-collect.d.ts

@@ -1,36 +1,10 @@
 import type { AgentId } from '../types.js';
 import { type RotateCandidate } from './rotate.js';
 import { type RegistryAccountRecord } from './account-pool.js';
-/** Inputs to {@link foldRegistryCandidates} — injectable so the fold is unit-tested. */
 export interface RunCandidateInputs {
     native: RotateCandidate[];
     records: RegistryAccountRecord[];
     runVersion: string | undefined;
 }
-/**
- * PURE: fold provider-account candidates into the native version-home list.
- *
- * A registry account runs in `runVersion` (the agent's default installed home);
- * the token/key overrides that home's own login at exec, so any home works. It
- * carries `providerAccount` so the run path routes it through the existing
- * `--account` injection (`resolveSpawnAccount` → `accountEnv`). An account already
- * covered by a native login is skipped by accountKey. With no installed version
- * there is nowhere to execute a registry account, so the native list passes
- * through unchanged.
- */
 export declare function foldRegistryCandidates(agent: AgentId, inputs: RunCandidateInputs): RotateCandidate[];
-/**
- * Candidate list for the `agents run` strategy pick, account-centric: the usual
- * native version-home candidates PLUS one candidate per provider account whose
- * provider can authenticate `agent` and whose credential is present locally
- * (RUSH-3182). This is what makes a setup-token / API-key account balance-eligible.
- *
- * Passed as the `collect` argument to {@link resolveRunVersion} on the RUN path,
- * and used by session recovery (`resolveSessionRecovery`, PHNX-3626) so an
- * origin-account limit can rotate to a healthy provider account and stay NATIVE.
- * The other consumers of {@link collectRunCandidates} (watchdog, teams
- * placement) keep calling it directly and are unaffected. The existing
- * {@link pickBalancedCandidate} selects over the combined list, so the
- * revoked / rate-limit / exhausted logic is unchanged.
- */
 export declare function collectRunCandidatesForRun(agent: AgentId): Promise<RotateCandidate[]>;