@phnx-labs/agents-cli 1.22.52 → 1.22.53

package/dist/commands/sync.js

@@ -35,6 +35,8 @@ import { Option } from 'commander';
 import chalk from 'chalk';
 import { resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
 import { agentLabel, resolveAgentName, MANAGED_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
+import { autoEvictCentralBrowserProfiles } from '../lib/browser/registry.js';
+import { shouldAutoClaimCentralProfile } from '../lib/browser/profiles.js';
 import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, healDanglingVersionPointers, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildSelection, mergeRepoScopedSelections, listRepoNames, getVersionHomePath, } from '../lib/installations/versions.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks/install.js';
@@ -352,6 +354,12 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         else
             outLog(chalk.yellow(`  ! ${repo}: ${(res.error ?? 'pull failed').split('\n')[0]}`));
     }
+    // Drain the legacy central `browser:` tombstone now that the repos are pulled.
+    // Running AFTER the pull is load-bearing: it acts on a view of central that
+    // already reflects peers' drains, so it never re-claims a profile another box
+    // already migrated (which would flip that profile's kind identity->fungible).
+    // The interactive path is always non-quiet, non-json.
+    evictCentralBrowserProfilesForSync(false, false, outLog, errLog);
     // 2. One selection spanning the chosen repos.
     const selection = mergeRepoScopedSelections(repos, cwd);
     const hasResources = selection.memory === 'all' || Object.entries(selection).some(([kind, v]) => kind !== 'memory' && Array.isArray(v) && v.length > 0);
@@ -374,6 +382,36 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         }
     }
 }
+/**
+ * Drain the legacy central `browser:` tombstone during `agents sync` (PHNX-3315).
+ * New profiles write the per-device doc, but profiles created before the
+ * device-scoped store lingered in the shared top-level `agents.yaml` and churned
+ * every fleet pull until someone ran `agents browser profiles claim` by hand.
+ * Fold the ones THIS box can host into its device doc — host-gated, and the
+ * selection is computed under the meta lock (see autoEvictCentralBrowserProfiles)
+ * so it never races itself. Callers MUST invoke this AFTER the repo pull: acting
+ * on a pre-pull view of central risks re-claiming a profile a peer already
+ * drained, which would flip its kind identity->fungible. Non-fatal so a hiccup
+ * can never wedge the sync.
+ */
+function evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog) {
+    try {
+        // Auto-claim ONLY remote (ssh://) tombstones — they are fungible by design,
+        // so a concurrent cross-machine double-claim is harmless. Local/cdp profiles
+        // have no per-machine ownership signal and are left central for an explicit
+        // `agents browser profiles claim` (PHNX-3315 review). See
+        // shouldAutoClaimCentralProfile.
+        const result = autoEvictCentralBrowserProfiles(shouldAutoClaimCentralProfile);
+        if (!quiet && !json && result.claimed.length > 0) {
+            outLog(chalk.gray(`  Claimed ${result.claimed.length} central browser profile(s) into this device: ${result.claimed.join(', ')}`));
+        }
+    }
+    catch (err) {
+        if (!quiet && !json) {
+            errLog(chalk.yellow(`  ! browser profile eviction skipped: ${err.message}`));
+        }
+    }
+}
 /**
  * The umbrella verb: bare `agents sync` (no agent) makes this machine current.
  * Resolves the flags + a secrets passphrase (env-only for now; tokenized auth
@@ -415,6 +453,12 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
             log: (msg) => { if (!quiet && !json)
                 outLog(chalk.gray(`  ${msg}`)); },
         });
+        // Drain the legacy central `browser:` tombstone AFTER the umbrella pull, so
+        // we act on central as converged by this sync rather than a stale pre-pull
+        // copy that could re-claim a profile a peer already migrated. Skipped under
+        // --cloud (fetch-only, no local reconcile).
+        if (!opts.cloud)
+            evictCentralBrowserProfilesForSync(quiet, json, outLog, errLog);
         if (json) {
             emitJson({
                 // A refused resource is not a clean sync (RUSH-2700).

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

@@ -34,7 +34,15 @@ export type UnifiedAccount = (CredentialAccount & {
 export declare function accountRegistryPath(base?: string): string;
 export declare function readAccountRegistry(base?: string): AccountRegistryDocument;
 export declare function findAccount(name: string, doc?: AccountRegistryDocument): CredentialAccount | null;
-export declare function listNativeAccounts(meta: Pick<Meta, 'accounts'>): NativeAccount[];
+/**
+ * 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 declare function listNativeAccounts(meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): NativeAccount[];
 /**
  * Resolve one account by name or id across both stores, native first.
  *
@@ -46,15 +54,17 @@ export declare function listNativeAccounts(meta: Pick<Meta, 'accounts'>): Native
  * running before the body, so callers that only need a native lookup must be
  * able to omit it.
  */
-export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts'>, doc?: AccountRegistryDocument): UnifiedAccount | null;
+export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, doc?: AccountRegistryDocument): UnifiedAccount | null;
 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;
 export declare function bindAccount(nameOrId: string, target: string): UnifiedAccount;
 export declare function unbindAccount(nameOrId: string, target: string): void;
-export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts'>): string[];
+/** Every target bound to `accountId`: this box's device-doc bindings merged over
+ * the fleet-shared central bindings (PHNX-3315). */
+export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): string[];
 /** Explicit selection wins over a configured per-harness default. */
-export declare function resolveAccountSelection(explicit: string | undefined, agent: AgentId, meta: Pick<Meta, 'accounts'>, opts?: {
+export declare function resolveAccountSelection(explicit: string | undefined, agent: AgentId, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, opts?: {
     useDefault?: boolean;
     target?: string;
 }): string | undefined;
@@ -100,7 +110,7 @@ export type SpawnAccount = {
  * A native account bound to a different harness than the one being launched
  * fails loudly (EXEC-ACCOUNT-4). Returns null when nothing is selected.
  */
-export declare function resolveSpawnAccount(explicit: string | undefined, agent: AgentId, version: string | undefined, meta: Pick<Meta, 'accounts'>, opts?: {
+export declare function resolveSpawnAccount(explicit: string | undefined, agent: AgentId, version: string | undefined, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>, opts?: {
     useDefault?: boolean;
     provider?: string;
     base?: string;

package/dist/lib/account-registry.js

@@ -12,7 +12,9 @@
  * `{ 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]].
+ * 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';
@@ -133,8 +135,17 @@ 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) {
-    return Object.values(meta.accounts?.native ?? {}).map(account => ({ ...account, kind: 'native' }));
+    const merged = { ...meta.accounts?.native, ...meta.deviceAccounts?.native };
+    return Object.values(merged).map(account => ({ ...account, kind: 'native' }));
 }
 /**
  * Resolve one account by name or id across both stores, native first.
@@ -155,8 +166,28 @@ export function findUnifiedAccount(nameOrId, meta, doc) {
     const provider = findAccount(nameOrId, doc ?? readAccountRegistry());
     return provider ? { ...provider, kind: 'provider' } : null;
 }
-function assertUniqueUnifiedName(name, meta, doc) {
-    if (findUnifiedAccount(name, meta, doc))
+function nativeIdentityRows(meta, agent, identityKey) {
+    return listNativeAccounts(meta).filter(account => account.agent === agent && account.identityKey === identityKey);
+}
+/** Every row (central + this box's device store) for the identity that `name`
+ * (id or account name) resolves to. */
+function nativeRowsForNameOrId(meta, name) {
+    const found = listNativeAccounts(meta).find(account => account.id === name || account.name === name);
+    if (!found)
+        return [];
+    return nativeIdentityRows(meta, found.agent, found.identityKey);
+}
+function assertUniqueUnifiedName(name, meta, doc, exceptIds) {
+    const needle = name.toLowerCase();
+    const nativeHits = listNativeAccounts(meta).filter(account => account.id === name || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle);
+    if (nativeHits.some(account => !exceptIds?.has(account.id)))
+        throw new Error(`Account '${name}' already exists.`);
+    // 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.`);
 }
 export function addNativeAccount(name, agent, identityKey, identityLabel, scope) {
@@ -167,13 +198,28 @@ export function addNativeAccount(name, agent, identityKey, identityLabel, scope)
     if (duplicate)
         throw new Error(`This ${agent} login is already named '${duplicate.name}'.`);
     const account = { id: crypto.randomUUID(), name, kind: 'native', agent, identityKey, identityLabel, scope };
-    updateMeta(current => ({
-        ...current,
-        accounts: {
-            ...current.accounts,
-            native: { ...current.accounts?.native, [account.id]: { id: account.id, name, 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,
+            deviceAccounts: {
+                ...current.deviceAccounts,
+                native: { ...current.deviceAccounts?.native, [account.id]: entry },
+            },
+        }));
+    }
+    else {
+        updateMeta(current => ({
+            ...current,
+            accounts: {
+                ...current.accounts,
+                native: { ...current.accounts?.native, [account.id]: entry },
+            },
+        }));
+    }
     return account;
 }
 /** Create or replace the version-independent label for one native identity. */
@@ -183,30 +229,49 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
         throw new Error(`${agent} does not expose an email; pass a manual label.`);
     assertNativeLabel(resolvedLabel);
     const meta = readMeta();
-    const existing = listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey);
-    const collision = findUnifiedAccount(resolvedLabel, meta);
-    if (collision && collision.id !== existing?.id)
-        throw new Error(`Account '${resolvedLabel}' already exists.`);
-    if (!existing)
+    const matches = nativeIdentityRows(meta, agent, identityKey);
+    assertUniqueUnifiedName(resolvedLabel, meta, undefined, new Set(matches.map(account => account.id)));
+    if (matches.length === 0)
         return addNativeAccount(resolvedLabel, agent, identityKey, identityLabel, scope);
-    updateMeta(current => ({
-        ...current,
-        accounts: {
-            ...current.accounts,
-            native: { ...current.accounts?.native, [existing.id]: { ...current.accounts?.native?.[existing.id], name: resolvedLabel, identityLabel } },
-        },
-    }));
-    return { ...existing, name: resolvedLabel, identityLabel };
+    // 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') {
+            const native = { ...current.deviceAccounts?.native };
+            for (const row of matches)
+                native[row.id] = { id: row.id, name: resolvedLabel, agent, identityKey, identityLabel, scope: rowScope };
+            return { ...current, deviceAccounts: { ...current.deviceAccounts, native } };
+        }
+        const native = { ...current.accounts?.native };
+        for (const row of matches)
+            native[row.id] = { id: row.id, name: resolvedLabel, agent, identityKey, identityLabel, scope: rowScope };
+        return { ...current, accounts: { ...current.accounts, native } };
+    });
+    return { ...matches[0], name: resolvedLabel, identityLabel, scope: rowScope };
 }
 export function bindAccount(nameOrId, target) {
     const meta = readMeta();
     const account = findUnifiedAccount(nameOrId, meta);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
-    updateMeta(current => ({
-        ...current,
-        accounts: { ...current.accounts, bindings: { ...current.accounts?.bindings, [target]: account.id } },
-    }));
+    // 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,
+            deviceAccounts: { ...current.deviceAccounts, bindings: { ...current.deviceAccounts?.bindings, [target]: account.id } },
+        }));
+    }
+    else {
+        updateMeta(current => ({
+            ...current,
+            accounts: { ...current.accounts, bindings: { ...current.accounts?.bindings, [target]: account.id } },
+        }));
+    }
     return account;
 }
 export function unbindAccount(nameOrId, target) {
@@ -214,25 +279,43 @@ export function unbindAccount(nameOrId, target) {
     const account = findUnifiedAccount(nameOrId, meta);
     if (!account)
         throw new Error(`Unknown account '${nameOrId}'.`);
-    if (meta.accounts?.bindings?.[target] !== account.id)
+    const inCentral = meta.accounts?.bindings?.[target] === account.id;
+    const inDevice = meta.deviceAccounts?.bindings?.[target] === account.id;
+    if (!inCentral && !inDevice)
         throw new Error(`Account '${account.name}' is not attached to '${target}'.`);
     updateMeta(current => {
-        const bindings = { ...current.accounts?.bindings };
-        delete bindings[target];
-        return { ...current, accounts: { ...current.accounts, bindings } };
+        let next = current;
+        if (current.accounts?.bindings?.[target] === account.id) {
+            const bindings = { ...current.accounts?.bindings };
+            delete bindings[target];
+            next = { ...next, accounts: { ...next.accounts, bindings } };
+        }
+        if (current.deviceAccounts?.bindings?.[target] === account.id) {
+            const bindings = { ...current.deviceAccounts?.bindings };
+            delete bindings[target];
+            next = { ...next, deviceAccounts: { ...next.deviceAccounts, bindings } };
+        }
+        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) {
-    return Object.entries(meta.accounts?.bindings ?? {}).filter(([, id]) => id === accountId).map(([target]) => target).sort();
+    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 = {}) {
     if (explicit)
         return explicit;
-    const bound = opts.target ? meta.accounts?.bindings?.[opts.target] : undefined;
+    // 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)
         return bound;
-    const deviceScoped = meta.accounts?.bindings?.[agent];
+    const deviceScoped = bindings[agent];
     if (deviceScoped)
         return deviceScoped;
     return opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
@@ -285,16 +368,23 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     assertName(newName);
     const doc = readAccountRegistry(base);
     const meta = readMeta();
-    const native = listNativeAccounts(meta).find(account => account.id === oldName || account.name === oldName);
-    if (native) {
-        assertUniqueUnifiedName(newName, meta, doc);
-        updateMeta(current => ({
-            ...current,
-            accounts: {
-                ...current.accounts,
-                native: { ...current.accounts?.native, [native.id]: { ...current.accounts?.native?.[native.id], name: newName } },
-            },
-        }));
+    const rows = nativeRowsForNameOrId(meta, oldName);
+    if (rows.length) {
+        assertUniqueUnifiedName(newName, meta, doc, new Set(rows.map(account => account.id)));
+        // Sweep every row for the identity (PHNX-3206) in its owning store (PHNX-3315).
+        const rowScope = rows[0].scope;
+        updateMeta(current => {
+            if (rowScope === 'device') {
+                const native = { ...current.deviceAccounts?.native };
+                for (const row of rows)
+                    native[row.id] = { ...native[row.id], name: newName };
+                return { ...current, deviceAccounts: { ...current.deviceAccounts, native } };
+            }
+            const native = { ...current.accounts?.native };
+            for (const row of rows)
+                native[row.id] = { ...native[row.id], name: newName };
+            return { ...current, accounts: { ...current.accounts, native } };
+        });
         return;
     }
     const account = findAccount(oldName, doc);
@@ -306,14 +396,24 @@ export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
 }
 export function removeAccount(name, base = getUserAgentsDir()) {
     const meta = readMeta();
-    const native = listNativeAccounts(meta).find(account => account.id === name || account.name === name);
-    if (native) {
-        const bindings = accountBindings(native.id, meta);
+    const rows = nativeRowsForNameOrId(meta, name);
+    if (rows.length) {
+        const bindings = [...new Set(rows.flatMap(row => accountBindings(row.id, meta)))].sort();
         if (bindings.length)
-            throw new Error(`Account '${native.name}' is attached to: ${bindings.join(', ')}. Detach it before removing it.`);
+            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 => {
+            if (rowScope === 'device') {
+                const accounts = { ...current.deviceAccounts?.native };
+                for (const id of ids)
+                    delete accounts[id];
+                return { ...current, deviceAccounts: { ...current.deviceAccounts, native: accounts } };
+            }
             const accounts = { ...current.accounts?.native };
-            delete accounts[native.id];
+            for (const id of ids)
+                delete accounts[id];
             return { ...current, accounts: { ...current.accounts, native: accounts } };
         });
         return;

package/dist/lib/answer-router.js

@@ -1,3 +1,4 @@
+import { addressabilityRecoveryHint } from './terminal/resolve.js';
 import { injectTargetFromReplyRail } from './session/inject.js';
 /**
  * Match free-text answer against question options.
@@ -123,7 +124,7 @@ export function resolveAnswerRoute(input) {
         return {
             kind: 'refuse',
             reason: 'Agent is parked on a question but has no addressable terminal (no tmux/iterm/pty rail). ' +
-                'Open its terminal and answer there, or run `agents sessions resume <id>` first.',
+                addressabilityRecoveryHint(session),
         };
     }
     // Open block but agent is still looping between tool calls — mailbox is correct.

package/dist/lib/browser/profiles.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserProfileConfig } from '../types.js';
 import type { BrowserProfile, ProfileName } from './types.js';
 export type { BrowserProfile } from './types.js';
 export { declaringDevices, profileKind, profileRegistry, type ProfileDeclaration, } from './registry.js';
@@ -175,6 +176,23 @@ export declare function effectiveLocalPort(profile: BrowserProfile): number | un
  * skip remote profiles in this scan.
  */
 export declare function findFreeProfilePort(): Promise<number>;
+export declare function hasSshEndpoint(endpoints: BrowserProfileConfig['endpoints']): boolean;
+/**
+ * Whether the automatic central-tombstone drain (PHNX-3315) may claim `config`
+ * into THIS device's doc during `agents sync`.
+ *
+ * Only REMOTE (`ssh://`) profiles qualify. An `ssh://` endpoint names a specific
+ * host, so the profile is fungible by design — any box resolves it to the same
+ * browser, and a concurrent double-claim across machines is harmless. A
+ * local/`cdp://` profile has NO per-machine ownership signal: "that browser is
+ * installed here" is not "I hold this profile's credentialed session", so two
+ * boxes with the same common browser installed would each auto-claim the same
+ * tombstone on their first post-merge sync and flip it identity->fungible
+ * fleet-wide (the exact logged-out-browser failure this module exists to prevent
+ * — PHNX-3315 review). Local/cdp tombstones stay central for the explicit
+ * `agents browser profiles claim`.
+ */
+export declare function shouldAutoClaimCentralProfile(config: BrowserProfileConfig): boolean;
 /**
  * Refuse a profile whose LOCAL port another profile already owns.
  *

package/dist/lib/browser/profiles.js

@@ -390,7 +390,7 @@ function validateRemoteBrowserBinary(binary) {
         throw new Error(`Remote browser binary contains shell metacharacters: ${binary}`);
     }
 }
-function hasSshEndpoint(endpoints) {
+export function hasSshEndpoint(endpoints) {
     const targets = Array.isArray(endpoints)
         ? endpoints
         : Object.values(endpoints).map((preset) => preset.target);
@@ -403,6 +403,31 @@ function hasSshEndpoint(endpoints) {
         }
     });
 }
+/**
+ * Whether the automatic central-tombstone drain (PHNX-3315) may claim `config`
+ * into THIS device's doc during `agents sync`.
+ *
+ * Only REMOTE (`ssh://`) profiles qualify. An `ssh://` endpoint names a specific
+ * host, so the profile is fungible by design — any box resolves it to the same
+ * browser, and a concurrent double-claim across machines is harmless. A
+ * local/`cdp://` profile has NO per-machine ownership signal: "that browser is
+ * installed here" is not "I hold this profile's credentialed session", so two
+ * boxes with the same common browser installed would each auto-claim the same
+ * tombstone on their first post-merge sync and flip it identity->fungible
+ * fleet-wide (the exact logged-out-browser failure this module exists to prevent
+ * — PHNX-3315 review). Local/cdp tombstones stay central for the explicit
+ * `agents browser profiles claim`.
+ */
+export function shouldAutoClaimCentralProfile(config) {
+    if (!hasSshEndpoint(config.endpoints))
+        return false;
+    return isProfileLaunchableHere({
+        name: '_',
+        browser: config.browser,
+        binary: config.binary,
+        endpoints: config.endpoints,
+    });
+}
 /**
  * Refuse a profile whose LOCAL port another profile already owns.
  *

package/dist/lib/browser/registry.d.ts

@@ -3,7 +3,15 @@ export interface ProfileDeclaration {
     device: string;
     config: BrowserProfileConfig;
 }
-/** Leftover central `browser:` map from before per-device declarations. Empty when none remain. */
+/**
+ * The leftover central `browser:` tombstone from before per-device declarations.
+ * Empty when none remain — and `agents sync` now drains it automatically via
+ * {@link autoEvictCentralBrowserProfiles}, so on a synced box this is empty and
+ * {@link profileRegistry} is the single source of truth. It survives only to
+ * fold in migration and to explain an as-yet-unclaimed profile in a resolve
+ * error (a profile hostable on a peer that has not synced yet), never as a
+ * parallel store callers read for resolution.
+ */
 export declare function centralBrowserProfiles(): Record<string, BrowserProfileConfig>;
 export interface CentralClaimResult {
     claimed: string[];
@@ -12,22 +20,44 @@ export interface CentralClaimResult {
 /**
  * Fold leftover central `browser:` entries into THIS device's declaration file.
  *
- * Never called implicitly, and that is the point. Every device can read the
- * central map, so an implicit claim races: whichever box happens to read first
- * claims the name, {@link profileKind} then reports it `identity`, and the
- * daemon tunnels to that box — which for a fleet-wide `cdp://localhost:*`
- * profile is a logged-out headless browser wearing a credentialed browser's
- * name. That is the exact bug this module exists to remove, and an implicit
- * migration would write it to disk as a stored fact.
+ * The EXPLICIT operator action (`agents browser profiles claim`), run on the
+ * machine that actually owns the browser. It is never called implicitly from a
+ * read, and that is the point: every device can read the central map, so an
+ * implicit claim races — whichever box reads first claims the name, {@link
+ * profileKind} then reports it `identity`, and the daemon tunnels to that box,
+ * which for a fleet-wide `cdp://localhost:*` profile is a logged-out headless
+ * browser wearing a credentialed browser's name. {@link autoEvictCentralBrowserProfiles}
+ * closes that race for the automatic path (host-gated + non-throwing on sync);
+ * this one is the manual, throw-on-conflict counterpart.
  *
- * The claim is an explicit operator action (`agents browser profiles claim`),
- * run on the machine that actually owns the browser. `canHostHere` is supplied
- * by the command layer so this module stays a leaf — it must not import
- * `isProfileLaunchableHere` (that would cycle through chrome.ts → profiles.ts).
- * Only profiles this machine can host are claimed; the rest stay central,
- * undeclared, and fail loudly on resolve.
+ * `canHostHere` is supplied by the command layer so this module stays a leaf —
+ * it must not import `isProfileLaunchableHere` (that would cycle through
+ * chrome.ts → profiles.ts). Only profiles this machine can host are claimed; the
+ * rest stay central, undeclared, and fail loudly on resolve.
  */
 export declare function migrateCentralBrowserProfiles(canHostHere: (config: BrowserProfileConfig) => boolean, name?: string): CentralClaimResult;
+/**
+ * Automatic, self-draining counterpart to {@link migrateCentralBrowserProfiles}:
+ * fold every lingering central `browser:` profile THIS machine can host into its
+ * device doc and clear it from central, so the tombstone drains itself on
+ * `agents sync` with no manual `agents browser profiles claim`.
+ *
+ * Safe to call implicitly, unlike a claim at registry-read time (which races —
+ * see the `profileRegistry does not claim central declarations` guard), but the
+ * CALLER owns one ordering invariant: invoke it AFTER the sync's repo pull. Two
+ * boxes can both host the same profile (`canHostHere` is launchability, not
+ * ownership), so a box acting on a PRE-pull view of central could re-claim a
+ * profile a peer already drained and pushed — both writes land in different
+ * device files with no git conflict, and the profile flips identity->fungible.
+ * Running post-pull means central already reflects peers' drains, so the tombstone
+ * is gone locally before this box looks. The selection is also computed INSIDE
+ * the meta lock, and the path never throws — an unhostable profile or one that
+ * conflicts with an existing local declaration is left central for an explicit
+ * claim rather than wedging the sync. After it runs, {@link profileRegistry} is
+ * the single source of truth: a claimed profile lives in the device doc alone,
+ * never double-counted across the two stores.
+ */
+export declare function autoEvictCentralBrowserProfiles(canHostHere: (config: BrowserProfileConfig) => boolean): CentralClaimResult;
 /**
  * Every profile any device declares, keyed by name to all declaring devices.
  * Reads every `devices/<name>/agents.yaml`; declarations never overwrite.