@phnx-labs/agents-cli 1.22.78 → 1.22.79

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>;