@phnx-labs/agents-cli 1.22.78 → 1.22.80

package/dist/lib/account-catalog.js

@@ -1,5 +1,21 @@
-import { ALL_AGENT_IDS, getAccountInfo, supportsAccountInspection } from './agents.js';
-import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
+import { ALL_AGENT_IDS, credentialPresence, getAccountInfo, supportsAccountInspection } from './agents.js';
+import { getGlobalDefault, getVersionHomePath, listInstalledVersions } from './installations/versions.js';
+import { readInstallation } from './installations/store.js';
+import { readMeta } from './state.js';
+import { listNativeAccounts, readAccountRegistry } from './account-registry.js';
+import { isLaunchableSignedIn as isCredentialLaunchable } from './accounting/rotate.js';
+/**
+ * Strict "is this home actually connected?" — a live CREDENTIAL in that exact
+ * version home, not just a metadata identity claim (PHNX-3940). A `.claude.json`
+ * carrying an `oauthAccount` block with no `.credentials.json`/`.oauth_token`
+ * beside it is stale/expired, and must read as `reconnect-needed`, never
+ * `connected`. Where agents-cli does not know the credential location
+ * (`knownLocation` false), it falls back to the metadata `signedIn` since there
+ * is nothing stricter to check.
+ */
+export function isLaunchableSignedIn(agent, versionHome, info) {
+    return isCredentialLaunchable(info.signedIn, credentialPresence(agent, versionHome));
+}
 export function groupNativeAccountRows(rows) {
     const grouped = new Map();
     for (const row of rows) {
@@ -27,12 +43,124 @@ export function groupNativeAccountRows(rows) {
 }
 /** Discover signed-in harness-native identities without copying their auth files. */
 export async function discoverNativeAccounts() {
+    const rows = await collectNativeHomeRows();
+    return groupNativeAccountRows(rows.map(r => ({ agent: r.agent, version: r.label, accountKey: r.accountKey, email: r.email, signedIn: r.signedIn })));
+}
+/** Probe every installed home of every inspectable harness for its native identity. */
+export async function collectNativeHomeRows() {
     const rows = [];
     for (const agent of ALL_AGENT_IDS.filter(supportsAccountInspection)) {
-        for (const version of listInstalledVersions(agent)) {
-            const info = await getAccountInfo(agent, getVersionHomePath(agent, version));
-            rows.push({ agent, version, accountKey: info.accountKey, email: info.email, signedIn: info.signedIn });
+        for (const label of listInstalledVersions(agent)) {
+            const home = getVersionHomePath(agent, label);
+            const info = await getAccountInfo(agent, home);
+            rows.push({
+                agent,
+                label,
+                releaseVersion: readInstallation(agent, label)?.releaseVersion ?? null,
+                accountKey: info.accountKey,
+                email: info.email,
+                // Strict: a live credential in THIS home, not a bare metadata identity.
+                signedIn: isLaunchableSignedIn(agent, home, info),
+            });
+        }
+    }
+    return rows;
+}
+/**
+ * Fold installed homes + the registry into account-first native rows (pure).
+ *
+ * Every home carrying an identity contributes an `AccountHome`; the identity is
+ * the group key. A registered account (name/id/connect home) is merged onto its
+ * identity, and — crucially — a registered account whose identity has NO live
+ * home still appears, as `reconnect-needed`, so a stale/expired login is never
+ * silently dropped from the list nor shown as connected.
+ */
+export function buildNativeCatalog(rows, meta, globalDefault = getGlobalDefault) {
+    const registered = listNativeAccounts(meta);
+    const defaults = meta.accounts?.defaults ?? {};
+    const groups = new Map();
+    const keyOf = (agent, identity) => `${agent}:${identity}`;
+    // Every installed home that carries a resolvable identity seeds a group.
+    for (const row of rows) {
+        const identity = row.accountKey ?? row.email?.toLowerCase();
+        if (!identity)
+            continue;
+        const key = keyOf(row.agent, identity);
+        const group = groups.get(key) ?? { agent: row.agent, identityKey: identity, email: null, homes: [] };
+        group.email ??= row.email;
+        group.homes.push({ label: row.label, releaseVersion: row.releaseVersion, signedIn: row.signedIn });
+        groups.set(key, group);
+    }
+    // A registered account whose identity has no discovered home still belongs in
+    // the catalog — it just has nothing live to connect through yet. Its
+    // `identityKey` is the same value a home row groups on (a raw accountKey, or
+    // an already-lowercased email), so an exact-key check finds the existing group.
+    for (const account of registered) {
+        const key = keyOf(account.agent, account.identityKey);
+        if (!groups.has(key)) {
+            groups.set(key, { agent: account.agent, identityKey: account.identityKey, email: account.identityLabel ?? null, homes: [] });
+        }
+    }
+    const out = [];
+    for (const group of groups.values()) {
+        const account = registered.find(a => a.agent === group.agent && a.identityKey === group.identityKey);
+        const email = group.email ?? account?.identityLabel ?? null;
+        const homes = [...group.homes].sort((a, b) => a.label.localeCompare(b.label));
+        const signedIn = homes.some(h => h.signedIn);
+        // The configured per-harness account default is AUTHORITATIVE: when present,
+        // only the matching native account is the default — an explicit default that
+        // names a provider (or a stale name) never invents a native default. Only
+        // when NO account default is configured does the global-default installation
+        // home decide (diagnostic fallback).
+        const defaultRef = defaults[group.agent];
+        let isDefault;
+        if (defaultRef !== undefined) {
+            isDefault = !!account && (account.name === defaultRef || account.id === defaultRef);
+        }
+        else {
+            const gd = globalDefault(group.agent);
+            isDefault = !!gd && homes.some(h => h.label === gd);
         }
+        // The home is a PER-HOST fact: this box's recorded connect home when it is
+        // actually installed here, else the local home carrying the identity. A home
+        // label recorded on another box is never assumed to exist locally.
+        const recordedHome = account ? (meta.deviceAccounts?.homes?.[account.id] ?? null) : null;
+        const home = (recordedHome && homes.some(h => h.label === recordedHome))
+            ? recordedHome
+            : (homes.find(h => h.signedIn)?.label ?? homes[0]?.label ?? null);
+        out.push({
+            kind: 'native',
+            agent: group.agent,
+            identityKey: group.identityKey,
+            name: account?.name ?? null,
+            id: account?.id ?? null,
+            email,
+            display: email ?? account?.name ?? group.identityKey,
+            home,
+            installations: homes,
+            isDefault,
+            state: signedIn ? 'connected' : 'reconnect-needed',
+        });
     }
-    return groupNativeAccountRows(rows);
+    // Named accounts first, then default, then a stable display order.
+    return out.sort((a, b) => a.agent.localeCompare(b.agent)
+        || Number(!!b.name) - Number(!!a.name)
+        || Number(b.isDefault) - Number(a.isDefault)
+        || a.display.localeCompare(b.display));
+}
+function toProviderRow(account) {
+    return { kind: 'provider', name: account.name, id: account.id, provider: account.provider, auth: account.auth, baseUrl: account.baseUrl };
+}
+/**
+ * Wire the real collectors to the pure builder. This is the canonical
+ * account-first read model `view.ts` renders: native identities (account +
+ * connection first, release/home secondary) plus the durable provider bundles.
+ */
+export async function loadAccountCatalog() {
+    const meta = readMeta();
+    const native = buildNativeCatalog(await collectNativeHomeRows(), meta);
+    const provider = Object.values(readAccountRegistry().accounts)
+        .map(toProviderRow)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { native, provider };
 }

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

@@ -55,9 +55,52 @@ export declare function listNativeAccounts(meta: Pick<Meta, 'accounts' | 'device
  * able to omit it.
  */
 export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, doc?: AccountRegistryDocument, preferAgent?: AgentId): UnifiedAccount | null;
+/**
+ * Validate a native account NAME (charset + per-harness uniqueness) WITHOUT a
+ * known identity — the pre-flight `agents accounts connect` 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 declare function assertNativeAccountNameAvailable(name: string, agent: AgentId): void;
 export declare function addNativeAccount(name: string, agent: AgentId, identityKey: string, identityLabel: string | undefined, scope: 'version' | 'device'): NativeAccount;
 /** Create or replace the version-independent label for one native identity. */
 export declare function labelNativeAccount(agent: AgentId, identityKey: string, identityLabel: string | undefined, label: string | undefined, scope: 'version' | 'device'): NativeAccount;
+/**
+ * Record THIS box's connect home for an account (PHNX-3940). Device-scoped: the
+ * home a box minted for an account is not assumed to exist on any other box, so
+ * it lives in the device doc keyed by the stable account id, never on the
+ * fleet-synced central identity row. Idempotent. A reconnect reads it back via
+ * {@link nativeAccountHome} to reuse the exact home even when the credential has
+ * expired and local signed-in discovery can no longer find it.
+ */
+export declare function setNativeAccountHome(accountId: string, installationLabel: string): void;
+/** This box's recorded connect home for an account, or null. */
+export declare function nativeAccountHome(accountId: string, meta: Pick<Meta, 'deviceAccounts'>): string | null;
+/**
+ * Every installation label THIS box has recorded as SOME account's connect home
+ * (PHNX-3940). These are identity-bearing and MUST NEVER be re-minted for a new
+ * account — the safe-allocation invariant that stops a new connect from
+ * overwriting another account's login.
+ */
+export declare function ownedConnectHomeLabels(meta: Pick<Meta, 'deviceAccounts'>): Set<string>;
+/** This box's in-flight connect slot for `(agent, name)`, or null. */
+export declare function pendingConnectSlot(agent: AgentId, name: string, meta: Pick<Meta, 'deviceAccounts'>): string | null;
+/** Record an in-flight connect slot for `(agent, name)` (device-scoped). */
+export declare function setPendingConnectSlot(agent: AgentId, name: string, slot: string): void;
+/** Clear the in-flight connect slot for `(agent, name)` once the account lands. */
+export declare function clearPendingConnectSlot(agent: AgentId, name: string): void;
+/**
+ * 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 declare function setDefaultAccountIfAbsent(agent: AgentId, name: string): boolean;
 export declare function bindAccount(nameOrId: string, target: string, preferAgent?: AgentId): UnifiedAccount;
 export declare function unbindAccount(nameOrId: string, target: string, preferAgent?: AgentId): void;
 /** Every target bound to `accountId`: this box's device-doc bindings merged over

package/dist/lib/account-registry.js

@@ -221,6 +221,16 @@ function assertUniqueUnifiedName(name, meta, doc, exceptIds, agent) {
     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 connect` 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) {
     assertNativeLabel(name);
     const meta = readMeta();
@@ -283,6 +293,87 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
     });
     return { ...matches[0], name: resolvedLabel, identityLabel, scope: rowScope };
 }
+/**
+ * Record THIS box's connect home for an account (PHNX-3940). Device-scoped: the
+ * home a box minted for an account is not assumed to exist on any other box, so
+ * it lives in the device doc keyed by the stable account id, never on the
+ * fleet-synced central identity row. Idempotent. A reconnect reads it back via
+ * {@link nativeAccountHome} to reuse the exact home even when the credential has
+ * expired and local signed-in discovery can no longer find it.
+ */
+export function setNativeAccountHome(accountId, installationLabel) {
+    updateMeta(current => ({
+        ...current,
+        deviceAccounts: {
+            ...current.deviceAccounts,
+            homes: { ...current.deviceAccounts?.homes, [accountId]: installationLabel },
+        },
+    }));
+}
+/** This box's recorded connect home for an account, or null. */
+export function nativeAccountHome(accountId, meta) {
+    return meta.deviceAccounts?.homes?.[accountId] ?? null;
+}
+/**
+ * Every installation label THIS box has recorded as SOME account's connect home
+ * (PHNX-3940). These are identity-bearing and MUST NEVER be re-minted for a new
+ * account — the safe-allocation invariant that stops a new connect from
+ * overwriting another account's login.
+ */
+export function ownedConnectHomeLabels(meta) {
+    return new Set(Object.values(meta.deviceAccounts?.homes ?? {}));
+}
+function pendingConnectKey(agent, name) {
+    return `${agent}:${name.toLowerCase()}`;
+}
+/** This box's in-flight connect slot for `(agent, name)`, or null. */
+export function pendingConnectSlot(agent, name, meta) {
+    return meta.deviceAccounts?.pendingConnects?.[pendingConnectKey(agent, name)] ?? null;
+}
+/** Record an in-flight connect slot for `(agent, name)` (device-scoped). */
+export function setPendingConnectSlot(agent, name, slot) {
+    updateMeta(current => ({
+        ...current,
+        deviceAccounts: {
+            ...current.deviceAccounts,
+            pendingConnects: { ...current.deviceAccounts?.pendingConnects, [pendingConnectKey(agent, name)]: slot },
+        },
+    }));
+}
+/** Clear the in-flight connect slot for `(agent, name)` once the account lands. */
+export function clearPendingConnectSlot(agent, name) {
+    updateMeta(current => {
+        const pendingConnects = { ...current.deviceAccounts?.pendingConnects };
+        delete pendingConnects[pendingConnectKey(agent, name)];
+        return { ...current, deviceAccounts: { ...current.deviceAccounts, pendingConnects } };
+    });
+}
+/**
+ * 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) {
+    let set = false;
+    updateMeta(current => {
+        if (current.accounts?.defaults?.[agent])
+            return current; // already set — no-op
+        if (current.agents?.[agent] || current.isolatedAgents?.[agent])
+            return current; // preserve a legacy home default
+        set = true;
+        return {
+            ...current,
+            accounts: { ...current.accounts, defaults: { ...current.accounts?.defaults, [agent]: name } },
+        };
+    });
+    return set;
+}
 export function bindAccount(nameOrId, target, preferAgent) {
     const meta = readMeta();
     // Scope to the harness being bound to: a bare identity selector matches every
@@ -463,16 +554,20 @@ export function removeAccount(name, base = getUserAgentsDir()) {
         // 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 record for the removed account (PHNX-3940).
+            const homes = { ...current.deviceAccounts?.homes };
+            for (const id of ids)
+                delete homes[id];
             if (rowScope === 'device') {
                 const accounts = { ...current.deviceAccounts?.native };
                 for (const id of ids)
                     delete accounts[id];
-                return { ...current, deviceAccounts: { ...current.deviceAccounts, native: accounts } };
+                return { ...current, deviceAccounts: { ...current.deviceAccounts, native: accounts, homes } };
             }
             const accounts = { ...current.accounts?.native };
             for (const id of ids)
                 delete accounts[id];
-            return { ...current, accounts: { ...current.accounts, native: accounts } };
+            return { ...current, accounts: { ...current.accounts, native: accounts }, deviceAccounts: { ...current.deviceAccounts, homes } };
         });
         return;
     }

package/dist/lib/accounting/rotate.d.ts

@@ -402,7 +402,7 @@ export declare function collectHarnessCandidates(agentIds?: AgentId[]): Promise<
  * (the usual form) or its `accountKey`, and only ever returns a signed-in slot.
  * Returns null when nothing matches, so the caller can fall back and warn.
  */
-export declare function matchAccountVersion(candidates: RotateCandidate[], account: string): string | null;
+export declare function matchAccountVersion(candidates: RotateCandidate[], account: string, preferredLabel?: string | null): string | null;
 /**
  * Resolve a routine's `account:` pin (login email or account key) to the
  * installed version currently holding that account. Thin I/O wrapper over
@@ -412,7 +412,7 @@ export declare function matchAccountVersion(candidates: RotateCandidate[], accou
  * (RUSH-1957): the pinned run never rotates and never lands on another
  * routine's credential.
  */
-export declare function resolveAccountVersion(agent: AgentId, account: string): Promise<string | null>;
+export declare function resolveAccountVersion(agent: AgentId, account: string, preferredLabel?: string | null): Promise<string | null>;
 /**
  * Pick a healthy version for `agent` using weighted random by remaining
  * capacity. See `pickBalancedCandidate` for algorithm details.

package/dist/lib/accounting/rotate.js

@@ -775,13 +775,13 @@ export async function collectHarnessCandidates(agentIds = ALL_AGENT_IDS) {
  * (the usual form) or its `accountKey`, and only ever returns a signed-in slot.
  * Returns null when nothing matches, so the caller can fall back and warn.
  */
-export function matchAccountVersion(candidates, account) {
+export function matchAccountVersion(candidates, account, preferredLabel) {
     const needle = account.trim().toLowerCase();
     if (!needle)
         return null;
-    const match = candidates.find((c) => c.signedIn &&
+    const matching = candidates.filter((c) => c.signedIn &&
         (c.email?.toLowerCase() === needle || c.accountKey?.toLowerCase() === needle));
-    return match?.version ?? null;
+    return matching.find(candidate => candidate.version === preferredLabel)?.version ?? matching[0]?.version ?? null;
 }
 /**
  * Resolve a routine's `account:` pin (login email or account key) to the
@@ -792,9 +792,9 @@ export function matchAccountVersion(candidates, account) {
  * (RUSH-1957): the pinned run never rotates and never lands on another
  * routine's credential.
  */
-export async function resolveAccountVersion(agent, account) {
+export async function resolveAccountVersion(agent, account, preferredLabel) {
     const candidates = await collectRunCandidates(agent);
-    return matchAccountVersion(candidates, account);
+    return matchAccountVersion(candidates, account, preferredLabel);
 }
 /**
  * Pick a healthy version for `agent` using weighted random by remaining

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

@@ -0,0 +1,9 @@
+import { type AgentId } from '../types.js';
+export declare function authLockFilePath(agent: AgentId, stateDir?: string): string;
+export interface AuthOperationLock {
+    readonly signal: AbortSignal;
+    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

@@ -0,0 +1,55 @@
+/** 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';
+import { getRuntimeStateDir } from '../state.js';
+import { isAgentId } from '../types.js';
+export function authLockFilePath(agent, stateDir) {
+    if (!isAgentId(agent))
+        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);
+    let compromised = null;
+    const controller = new AbortController();
+    let unlock;
+    try {
+        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);
+            },
+        });
+    }
+    catch (error) {
+        throw new Error(`Cannot safely start ${agent} authentication: another sign-in or sign-out may be in progress. ${error.message}`);
+    }
+    let released = false;
+    return {
+        signal: controller.signal,
+        assertHeld() {
+            controller.signal.throwIfAborted();
+            if (released)
+                throw new Error('Authentication lock was already released.');
+        },
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                unlock();
+            }
+            finally {
+                if (compromised)
+                    throw new Error(`Authentication lock was lost: ${compromised.message}`);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,170 @@
+import type { AgentId, Meta } from '../types.js';
+import { type NativeAccount } from '../account-registry.js';
+/** Which harnesses `connect` supports, and how their native login is launched. */
+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;
+}
+/** Whether `connect` can drive this harness (isolation + a real native login). */
+export declare function connectSupported(agent: AgentId): boolean;
+/**
+ * Named reason connect refuses a harness, or null when supported. Distinguishes
+ * "cannot isolate/name this login" (capability) from "no native login command
+ * wired yet" so the message is honest about which limit was hit.
+ */
+export declare function connectRefusal(agent: AgentId): string | null;
+export declare function assertConnectSupported(agent: AgentId): void;
+export declare function loginInvocation(agent: AgentId): LoginInvocation;
+/**
+ * Mint a fresh, opaque installation slot. `acct-<hex>` — alnum + hyphen only, so
+ * it satisfies VERSION_RE, and is visibly an account slot, not a release. It is
+ * RANDOM, never derived from the account name or identity: a name-derived slot
+ * recomputes an already-occupied home after a rename and lets a new connect
+ * overwrite another account's login (PHNX-3940 security fix). Retry-idempotency
+ * is instead provided by the device-scoped pending-connect map, and collision
+ * safety by allocating around occupied slots — see `allocateConnectSlot`.
+ */
+export declare function mintConnectLabel(): string;
+export type ConnectMode = 'new' | 'reconnect';
+export interface ConnectPlan {
+    mode: ConnectMode;
+    agent: AgentId;
+    /** The installation label whose isolated home hosts this account's login. */
+    label: string;
+    /** The human account name to register (new) or already registered (reconnect). */
+    name?: string;
+    /** For reconnect: the existing account being re-authenticated. */
+    existing?: NativeAccount;
+    /**
+     * For reconnect: the label was ADOPTED (freshly minted) because the existing
+     * account carried no recorded home and none was discoverable — so its identity
+     * must still be re-verified against the login, but there is no prior home to
+     * reuse. `false` when an existing home is being reused.
+     */
+    adoptedHome?: boolean;
+}
+/**
+ * Resolve the home to reuse for reconnecting an existing account: THIS box's
+ * recorded connect home first (device-scoped, survives an expired credential),
+ * else a currently-signed-in local home carrying its identity. Returns null when
+ * neither is known — a legacy account with no recorded or live home, for which
+ * connect adopts a fresh home.
+ */
+export declare function resolveExistingHomeLabel(existing: NativeAccount, deviceHome: string | null, signedInHomes: Array<{
+    agent: AgentId;
+    identityKey: string;
+    label: string;
+}>): string | null;
+/**
+ * Decide the release-independent connect plan (pure). `existing` is the native
+ * account the name resolves to for THIS harness (or null for a new connect);
+ * `existingHomeLabel` is its reusable home from {@link resolveExistingHomeLabel};
+ * `freshSlot` is a safely-allocated opaque slot (see `allocateConnectSlot`) used
+ * for a new connect or an adopted reconnect home — NEVER a name-derived label.
+ */
+export declare function planConnect(input: {
+    agent: AgentId;
+    name?: string;
+    existing: NativeAccount | null;
+    existingHomeLabel: string | null;
+    freshSlot: string;
+}): ConnectPlan;
+/**
+ * Safely allocate the opaque slot for a NEW connect or an ADOPTED reconnect home
+ * (PHNX-3940 security fix). Never reuses an identity-bearing slot:
+ *
+ * - `occupied` is every slot already owned by an account's home OR currently
+ *   signed in — an allocated slot is guaranteed disjoint from it, so a new
+ *   connect can never land on another account's home (the rename-collision flaw).
+ * - A named connect first reuses its device-scoped PENDING slot (a prior
+ *   failed/cancelled attempt) IF that slot is not occupied, so a retry lands in
+ *   the same fresh home instead of orphaning a new one.
+ * - Otherwise it mints random slots until one is neither occupied nor installed.
+ */
+export declare function allocateConnectSlot(input: {
+    agent: AgentId;
+    name?: string;
+    existing: NativeAccount | null;
+    occupied: ReadonlySet<string>;
+    installedLabels: ReadonlySet<string>;
+    pending: string | null;
+    mint?: () => string;
+}): string;
+/**
+ * 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.
+ * - Reconnect whose completed identity differs from the account's → REFUSE
+ *   registering the binding. The native credential in that home DID change (the
+ *   user signed in), so the message says the account BINDING is left unchanged —
+ *   it does not claim nothing happened.
+ * A new connect accepts whatever identity signed in (that is the account being
+ * created); the caller registers it.
+ */
+export declare function verifyConnectedIdentity(plan: ConnectPlan, observed: Pick<ObservedIdentity, 'identityKey' | 'signedIn'>): void;
+/** Resolve the existing native account a connect `name` refers to for a harness. */
+export declare function findConnectAccount(agent: AgentId, name: string | undefined, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): NativeAccount | null;
+/** 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;
+}
+/**
+ * Side-effecting operations connect needs, injected so the planning/verification
+ * path is unit-testable and the parent can own the real E2E login+verify.
+ */
+export interface ConnectRunners {
+    installedLabels(agent: AgentId): string[];
+    /** Install the CURRENT release into `label`'s isolated home (opaque label). */
+    install(agent: AgentId, label: string, onProgress?: (m: string) => void): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /** Launch the harness's native login under `label`'s home; resolves on exit. */
+    launchLogin(agent: AgentId, label: string, invocation: LoginInvocation, email?: string, signal?: AbortSignal): Promise<{
+        code: number | null;
+    }>;
+    observeIdentity(agent: AgentId, label: string): Promise<ObservedIdentity>;
+    signedInHomes(): Promise<Array<{
+        agent: AgentId;
+        identityKey: string;
+        label: string;
+    }>>;
+}
+export interface ConnectResult {
+    mode: ConnectMode;
+    agent: AgentId;
+    label: string;
+    name?: string;
+    identityKey: string;
+    email: string | null;
+    releaseVersion: string | null;
+    /** True when this connect became the harness's default (only set if none was configured). */
+    becameDefault: boolean;
+    /** For an UNNAMED connect: the command to name the login (no name was forced). */
+    nameHint?: string;
+}
+/**
+ * Drive one `agents accounts connect`. Pure decisions (plan, fail-closed verify)
+ * come from the helpers above; the install + login + identity read are injected.
+ *
+ * The default runners are loaded via dynamic import so this module — reachable
+ * from `account-registry` consumers — never statically pulls in the install
+ * engine or exec path and closes an import cycle (the intended pattern here).
+ *
+ * `stateDir` is only for tests: override the runtime-state dir used by the
+ * per-harness auth-operation mutex (defaults to the real runtime state dir).
+ */
+export declare function runConnect(agent: AgentId, name: string | undefined, opts: {
+    meta: Pick<Meta, 'accounts' | 'deviceAccounts'>;
+    onProgress?: (m: string) => void;
+    stateDir?: string;
+}, runners?: ConnectRunners): Promise<ConnectResult>;