@phnx-labs/agents-cli 1.22.74 → 1.22.76

package/dist/commands/workflows.js

@@ -1,3 +1,4 @@
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -56,8 +57,8 @@ Examples:
   # Remove from version homes (and central storage on second run)
   agents workflows remove code-review
 `);
-    workflowsCmd
-        .command('list [agent]')
+    withAliases(workflowsCmd
+        .command('list [agent]'), 'list')
         .description('Show installed workflows and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent')
         .action(async (agentArg, options) => {
@@ -260,8 +261,8 @@ Examples:
             process.exit(1);
         }
     });
-    workflowsCmd
-        .command('remove [name]')
+    withAliases(workflowsCmd
+        .command('remove [name]'), 'remove')
         .description('Remove a workflow from version homes (interactive picker if no name given)')
         .addHelpText('after', `
 Examples:
@@ -365,8 +366,8 @@ Examples:
             console.log(chalk.gray('Central source unchanged. Use "agents workflows remove <name>" again to remove from ~/.agents/workflows/.'));
         }
     });
-    workflowsCmd
-        .command('view [name]')
+    withAliases(workflowsCmd
+        .command('view [name]'), 'view')
         .description('Read workflow details (description, subagents, model, MCP)')
         .addHelpText('after', `
 Examples:

package/dist/lib/account-registry.js

@@ -187,11 +187,32 @@ function nativeRowsForNameOrId(meta, name) {
         return [];
     return nativeIdentityRows(meta, found.agent, found.identityKey);
 }
-function assertUniqueUnifiedName(name, meta, doc, exceptIds) {
+/**
+ * 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. Omit it for management
+ * lookups with no harness in hand (rename/remove), which keep the old
+ * fleet-wide check so a rename cannot collide with an unrelated harness's row.
+ *
+ * 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 => 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.`);
+    const nativeHits = listNativeAccounts(meta).filter(account => (agent === undefined || account.agent === agent)
+        && (account.id === name || account.name.toLowerCase() === needle || account.identityLabel?.toLowerCase() === needle));
+    if (nativeHits.some(account => !exceptIds?.has(account.id))) {
+        throw new Error(agent === undefined
+            ? `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)
@@ -203,7 +224,7 @@ function assertUniqueUnifiedName(name, meta, doc, exceptIds) {
 export function addNativeAccount(name, agent, identityKey, identityLabel, scope) {
     assertNativeLabel(name);
     const meta = readMeta();
-    assertUniqueUnifiedName(name, meta);
+    assertUniqueUnifiedName(name, meta, undefined, undefined, agent);
     const duplicate = listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey);
     if (duplicate)
         throw new Error(`This ${agent} login is already named '${duplicate.name}'.`);
@@ -240,7 +261,7 @@ export function labelNativeAccount(agent, identityKey, identityLabel, label, sco
     assertNativeLabel(resolvedLabel);
     const meta = readMeta();
     const matches = nativeIdentityRows(meta, agent, identityKey);
-    assertUniqueUnifiedName(resolvedLabel, meta, undefined, new Set(matches.map(account => account.id)));
+    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

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

@@ -50,6 +50,8 @@ export interface RotateCandidate {
      * does not gate — a stale/absent probe never blocks a launch.
      */
     authVerdict: AuthVerdict | null;
+    /** Epoch milliseconds of the auth probe behind authVerdict, when present. */
+    authCheckedAt?: number | null;
     lastActive: Date | null;
     /**
      * Set only for a candidate that comes from a provider account bundle rather
@@ -243,7 +245,7 @@ export type AccountReadiness = {
  * status — matching the gate — so a stale `out_of_credits` cache is not
  * reported while the account is actually serving requests.
  */
-export declare function readinessFromCandidate(candidate: RotateCandidate): AccountReadiness;
+export declare function readinessFromCandidate(candidate: RotateCandidate, now?: number): AccountReadiness;
 /**
  * Whether a human sitting at a terminal can clear this exclusion by launching
  * the agent and signing in. The two unhealthy classes are opposites, and the

package/dist/lib/accounting/rotate.js

@@ -15,7 +15,7 @@ import { emit } from '../feed/events.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
 import { readAccountHeadroom } from '../fleet-cache.js';
 import { machineId } from '../machine-id.js';
-import { readAuthHealthCache, authCacheKey, isDeadVerdict } from '../auth-health.js';
+import { AUTH_PROBE_MAX_AGE_MS, readAuthHealthCache, authCacheKey, isDeadVerdict } from '../auth-health.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -229,7 +229,7 @@ function hasUsageAvailable(candidate) {
  * status — matching the gate — so a stale `out_of_credits` cache is not
  * reported while the account is actually serving requests.
  */
-export function readinessFromCandidate(candidate) {
+export function readinessFromCandidate(candidate, now = Date.now()) {
     if (!candidate.signedIn) {
         return { ready: false, reason: 'signed_out', email: candidate.email };
     }
@@ -237,7 +237,9 @@ export function readinessFromCandidate(candidate) {
     // auth at spawn no matter how much usage headroom it has. Exclude it BEFORE the
     // usage gate so rotation never routes into a doomed login. Fail-open: any other
     // (or null) verdict does not gate — see `RotateCandidate.authVerdict`.
-    if (candidate.authVerdict !== null && isDeadVerdict(candidate.authVerdict)) {
+    const authFresh = candidate.authCheckedAt == null
+        || now - candidate.authCheckedAt <= AUTH_PROBE_MAX_AGE_MS;
+    if (authFresh && candidate.authVerdict !== null && isDeadVerdict(candidate.authVerdict)) {
         return { ready: false, reason: 'revoked', email: candidate.email };
     }
     if (hasUsageAvailable(candidate)) {
@@ -697,7 +699,8 @@ export async function collectRunCandidates(agent) {
         // lives — see isLaunchableSignedIn. Do not reuse the active-home fallback
         // identity for routing, or empty version homes look healthy and die at spawn.
         const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
-        const authVerdict = authCache[authCacheKey(localHost, agent, version)]?.verdict ?? null;
+        const authHealth = authCache[authCacheKey(localHost, agent, version)];
+        const authVerdict = authHealth?.verdict ?? null;
         return {
             agent,
             version,
@@ -710,6 +713,7 @@ export async function collectRunCandidates(agent) {
             plan: launchable ? info.plan : null,
             signedIn: launchable,
             authVerdict,
+            authCheckedAt: authHealth?.checkedAt ?? null,
             lastActive: info.lastActive,
         };
     }));

package/dist/lib/auth-health.d.ts

@@ -25,6 +25,8 @@ export interface AuthHealth {
     /** account label for display (email / id), when known. Never part of the key. */
     account?: string;
 }
+/** Maximum age of an auth verdict used for automatic routing decisions. */
+export declare const AUTH_PROBE_MAX_AGE_MS: number;
 /** Agents with a live network probe wired up today. The rest are best-effort. */
 export declare const LIVE_PROBE_AGENTS: ReadonlySet<AgentId>;
 /** Map an HTTP status from a live probe to a verdict. */

package/dist/lib/auth-health.js

@@ -23,6 +23,8 @@ import { getCacheDir } from './state.js';
 import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, readClaudeUsageCache, } from './accounting/usage.js';
 import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
+/** Maximum age of an auth verdict used for automatic routing decisions. */
+export const AUTH_PROBE_MAX_AGE_MS = 20 * 60_000;
 /** Agents with a live network probe wired up today. The rest are best-effort. */
 export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);
 // ---------------------------------------------------------------------------

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

@@ -90,6 +90,27 @@ export declare function ensureProfilePreferences(userDataDir: string, profileNam
  */
 export declare function isPortInUse(port: number): boolean;
 export declare function allocatePort(): number;
+/**
+ * Read the `--user-data-dir` a running browser process was launched with, by
+ * inspecting its command line (PHNX-3967). This is the ownership signal the
+ * attach-only guard uses to tell the credentialed canonical browser apart from a
+ * foreign port-squatter serving CDP on the same port (e.g. a logged-out
+ * `/tmp/...` Comet). Returns null when the pid is gone, exposes no
+ * `--user-data-dir`, or the platform probe fails.
+ *
+ * POSIX: `ps -ww -o command=` (full, un-truncated argv). Windows: the
+ * `CommandLine` from `Win32_Process` via PowerShell. The value is captured up to
+ * the next ` --<flag>` (or end of line) so a data dir that itself contains a
+ * space is not truncated at the space.
+ */
+export declare function getProcessUserDataDir(pid: number): string | null;
+/**
+ * Extract the `--user-data-dir` value from a browser command line. Handles both
+ * `--user-data-dir=<path>` and `--user-data-dir <path>` and stops the value at
+ * the next ` --<flag>` so a path containing spaces survives. Exported for unit
+ * testing without a live process.
+ */
+export declare function parseUserDataDirFromCommandLine(cmdline: string): string | null;
 export interface PortOccupant {
     pid: number;
     command: string;

package/dist/lib/browser/chrome.js

@@ -277,9 +277,15 @@ isElectron = false) {
     // *inside* each user-data-dir. Direct binary spawn with a fresh
     // --user-data-dir creates a fully independent process — the user's
     // normal browser (running under their default user-data-dir) and our
-    // sandboxed one coexist as two real processes. The macOS Dock collapses
-    // them into one icon per .app bundle, which makes it look like a single
-    // instance, but `ps -ww` will show both.
+    // sandboxed one coexist as two real processes.
+    //
+    // These are TWO dock tiles, not one. Measured on macOS 26 (zion, 2026-09-04):
+    // a second Comet spawned this way registers its OWN LaunchServices ASN, so
+    // `lsappinfo list` reports two `ai.perplexity.comet` entries and the Dock shows
+    // two Comet icons — one of them the logged-out sandbox. The Dock does NOT
+    // collapse same-bundle processes into one tile. Spawning a rival window is
+    // exactly the failure PHNX-3967 set out to end, which is why an attach-only
+    // profile never reaches this launcher (see connectLocal / isAttachOnlyProfile).
     const viewport = options.viewport ?? { width: 1512, height: 982 };
     const args = [
         '--remote-debugging-pipe',
@@ -479,6 +485,57 @@ export function allocatePort() {
     }
     throw new Error('No available ports in range 9200-9300');
 }
+/**
+ * Read the `--user-data-dir` a running browser process was launched with, by
+ * inspecting its command line (PHNX-3967). This is the ownership signal the
+ * attach-only guard uses to tell the credentialed canonical browser apart from a
+ * foreign port-squatter serving CDP on the same port (e.g. a logged-out
+ * `/tmp/...` Comet). Returns null when the pid is gone, exposes no
+ * `--user-data-dir`, or the platform probe fails.
+ *
+ * POSIX: `ps -ww -o command=` (full, un-truncated argv). Windows: the
+ * `CommandLine` from `Win32_Process` via PowerShell. The value is captured up to
+ * the next ` --<flag>` (or end of line) so a data dir that itself contains a
+ * space is not truncated at the space.
+ */
+export function getProcessUserDataDir(pid) {
+    if (!pid || pid <= 0)
+        return null;
+    let cmdline = '';
+    try {
+        if (process.platform === 'win32') {
+            cmdline = execFileSync('powershell', [
+                '-NoProfile',
+                '-Command',
+                `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`,
+            ], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        }
+        else {
+            cmdline = execFileSync('ps', ['-ww', '-o', 'command=', '-p', String(pid)], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+        }
+    }
+    catch {
+        return null;
+    }
+    return parseUserDataDirFromCommandLine(cmdline);
+}
+/**
+ * Extract the `--user-data-dir` value from a browser command line. Handles both
+ * `--user-data-dir=<path>` and `--user-data-dir <path>` and stops the value at
+ * the next ` --<flag>` so a path containing spaces survives. Exported for unit
+ * testing without a live process.
+ */
+export function parseUserDataDirFromCommandLine(cmdline) {
+    const line = cmdline.replace(/\r?\n/g, ' ').trim();
+    const m = line.match(/--user-data-dir[=\s]+(.*?)(?=\s--[A-Za-z]|$)/);
+    if (!m)
+        return null;
+    const value = m[1].trim().replace(/^["']|["']$/g, '');
+    return value.length > 0 ? value : null;
+}
 /**
  * Identify the process listening on a TCP port. Returns null when nothing is bound.
  * Used for clearer error messages when a profile's configured port is taken by a

package/dist/lib/browser/drivers/local.d.ts

@@ -16,6 +16,27 @@ export interface LocalConnection {
  * duplicate. Exported so the contract is unit-testable without a real Arc.
  */
 export declare function arcAttachRequiredError(profileName: string, port: number): Error;
+/**
+ * The loud error an ATTACH-ONLY profile raises when nothing debuggable is on its
+ * port (PHNX-3967). Same contract as {@link arcAttachRequiredError}, generalized
+ * to any browser: agents attach to a browser the user already started and NEVER
+ * spawn a rival window, so instead of falling through to `launchBrowser` (which
+ * would produce the second, logged-out dock tile this ticket set out to end) we
+ * fail loud with the exact relaunch that makes the canonical instance
+ * attachable — pinned to the profile's DURABLE `--user-data-dir` so the one-time
+ * sign-in persists. Exported so the contract is unit-testable without a browser.
+ */
+export declare function attachOnlyRequiredError(profile: Pick<BrowserProfile, 'name' | 'browser' | 'userDataDir'>, port: number): Error;
+/**
+ * The loud error an attach-only profile raises when a browser IS serving CDP on
+ * its port but is a FOREIGN instance — its `--user-data-dir` is not the profile's
+ * durable dir (PHNX-3967). This closes the port-squat: a logged-out `/tmp/...`
+ * Comet answering CDP on the canonical port passes the browser-FAMILY identity
+ * check, so without an ownership check agents would drive it as if it were the
+ * credentialed browser. Rather than adopt the squatter we reject it and name the
+ * fix. Exported for unit testing.
+ */
+export declare function foreignInstanceError(profile: Pick<BrowserProfile, 'name' | 'browser' | 'userDataDir'>, port: number, runningDataDir: string, pid: number): Error;
 export declare function connectLocal(endpoint: string, profile: BrowserProfile, 
 /**
  * Runtime key (`<profile>@<endpoint>`) the launched browser's user-data-dir,

package/dist/lib/browser/drivers/local.js

@@ -1,7 +1,7 @@
 import * as net from 'net';
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
-import { launchBrowser, getPortOccupant } from '../chrome.js';
-import { parseEndpointUrl } from '../profiles.js';
+import { launchBrowser, getPortOccupant, getProcessUserDataDir } from '../chrome.js';
+import { parseEndpointUrl, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir } from '../profiles.js';
 /**
  * Cheap TCP-level "is something bound here?" probe. Used as a fallback when
  * `getPortOccupant()` (lsof-based) misses the process — Comet and other
@@ -49,6 +49,89 @@ export function arcAttachRequiredError(profileName, port) {
         `  open -a Arc --args --remote-debugging-port=${port}\n` +
         `and retry. The port must match the profile's endpoint (\`agents browser profiles list\`).`);
 }
+/**
+ * The loud error an ATTACH-ONLY profile raises when nothing debuggable is on its
+ * port (PHNX-3967). Same contract as {@link arcAttachRequiredError}, generalized
+ * to any browser: agents attach to a browser the user already started and NEVER
+ * spawn a rival window, so instead of falling through to `launchBrowser` (which
+ * would produce the second, logged-out dock tile this ticket set out to end) we
+ * fail loud with the exact relaunch that makes the canonical instance
+ * attachable — pinned to the profile's DURABLE `--user-data-dir` so the one-time
+ * sign-in persists. Exported so the contract is unit-testable without a browser.
+ */
+export function attachOnlyRequiredError(profile, port) {
+    if (profile.browser === 'arc')
+        return arcAttachRequiredError(profile.name, port);
+    const app = profile.browser === 'comet' ? 'Comet' : profile.browser;
+    const dataDir = resolveProfileDataDir(profile);
+    return new Error(`Profile "${profile.name}" is attach-only and nothing is serving the Chrome ` +
+        `DevTools Protocol on cdp://127.0.0.1:${port}. agents browser attaches to the ` +
+        `${app} you already started and never launches a second one, so it will not spawn ` +
+        `a rival window (that is the duplicate, logged-out tile this profile exists to ` +
+        `prevent). Launch the canonical ${app} with remote debugging on its durable data dir:\n` +
+        `  open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${dataDir}\n` +
+        `and retry. Keep signing in once in that window — the data dir is durable, so the ` +
+        `login survives quit+relaunch.`);
+}
+/**
+ * The loud error an attach-only profile raises when a browser IS serving CDP on
+ * its port but is a FOREIGN instance — its `--user-data-dir` is not the profile's
+ * durable dir (PHNX-3967). This closes the port-squat: a logged-out `/tmp/...`
+ * Comet answering CDP on the canonical port passes the browser-FAMILY identity
+ * check, so without an ownership check agents would drive it as if it were the
+ * credentialed browser. Rather than adopt the squatter we reject it and name the
+ * fix. Exported for unit testing.
+ */
+export function foreignInstanceError(profile, port, runningDataDir, pid) {
+    const expected = resolveProfileDataDir(profile);
+    const app = profile.browser === 'comet' ? 'Comet' : profile.browser;
+    return new Error(`Attach-only ownership check failed for profile "${profile.name}" on ` +
+        `cdp://127.0.0.1:${port}: a ${app} is serving CDP there (pid ${pid}) but it is ` +
+        `running a FOREIGN user-data-dir\n` +
+        `  running:  ${runningDataDir}\n` +
+        `  expected: ${expected}\n` +
+        `so it is not this profile's credentialed browser. agents will not drive it. Close ` +
+        `that instance (\`kill ${pid}\`), then relaunch the canonical ${app}:\n` +
+        `  open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${expected}`);
+}
+/**
+ * Prefix every ownership-rejection message carries, so `connectLocal`'s catch can
+ * re-throw it verbatim instead of misreading it as "attach failed, launch fresh".
+ */
+const OWNERSHIP_REJECTION_PREFIX = 'Attach-only ownership check failed';
+/**
+ * Verify the browser serving CDP on `port` belongs to this attach-only profile,
+ * by comparing its live `--user-data-dir` to the profile's durable dir
+ * (PHNX-3967). No-op for a `launch`-policy profile. When an occupant IS present
+ * but its data dir can't be read, fail LOUD rather than open: a canonical Comet
+ * this profile is meant to attach to was launched by the user with the durable
+ * `--user-data-dir` and is readable via `ps`, so an unreadable occupant is the
+ * suspicious case, not a legitimate one — driving it would be the exact
+ * port-squat this guard exists to stop.
+ */
+function verifyEndpointOwnership(profile, port) {
+    if (!isAttachOnlyProfile(profile))
+        return;
+    // Arc is the user's single running instance under its own default data dir; it
+    // has no managed durable dir to compare against and no /tmp-squat vector.
+    if (profile.browser === 'arc')
+        return;
+    const occupant = getPortOccupant(port);
+    if (!occupant)
+        return;
+    const expected = resolveProfileDataDir(profile);
+    const runningDataDir = getProcessUserDataDir(occupant.pid);
+    if (!runningDataDir) {
+        throw new Error(`${OWNERSHIP_REJECTION_PREFIX} for profile "${profile.name}" on cdp://127.0.0.1:${port}: ` +
+            `a process (pid ${occupant.pid}) is serving CDP there but its --user-data-dir could not be ` +
+            `read, so ownership can't be confirmed. Refusing to attach to an unverified instance. If ` +
+            `this is your canonical browser, relaunch it with --user-data-dir=${expected} so the ` +
+            `attach-only guard can verify it.`);
+    }
+    if (normalizeDataDir(runningDataDir) !== normalizeDataDir(expected)) {
+        throw foreignInstanceError(profile, port, runningDataDir, occupant.pid);
+    }
+}
 export async function connectLocal(endpoint, profile, 
 /**
  * Runtime key (`<profile>@<endpoint>`) the launched browser's user-data-dir,
@@ -81,6 +164,11 @@ key) {
     try {
         const { wsUrl, browser } = await discoverBrowserWsUrl(port, 'localhost', profile.name);
         verifyBrowserIdentity(browser, profile.browser, port);
+        // Ownership beyond browser FAMILY (PHNX-3967): a foreign /tmp Comet answers
+        // CDP on the canonical port and passes verifyBrowserIdentity, so before we
+        // adopt the endpoint confirm its --user-data-dir is this profile's durable
+        // dir. Rejects the port-squatter loudly instead of driving it.
+        verifyEndpointOwnership(profile, port);
         const cdp = new CDPClient();
         await cdp.connect(wsUrl);
         return { cdp, port, pid: 0 };
@@ -89,13 +177,18 @@ key) {
         if (err instanceof Error && err.message.startsWith('Browser identity mismatch')) {
             throw err;
         }
-        // Arc reached the catch, so the attach above failed: the running Arc is not
-        // serving CDP on this port. Never fall through to launchBrowser — that would
-        // spawn the duplicate/stray-window this ticket set out to end (#2779,
-        // PHNX-2399). Fail loud with the relaunch that makes the user's Arc
-        // attachable.
-        if (profile.browser === 'arc') {
-            throw arcAttachRequiredError(profile.name, port);
+        // An ownership rejection is a definitive answer — never fall through to a
+        // fresh launch or a generic port message. Re-throw it verbatim.
+        if (err instanceof Error && err.message.startsWith(OWNERSHIP_REJECTION_PREFIX)) {
+            throw err;
+        }
+        // An attach-only profile reached the catch, so the attach above failed:
+        // nothing debuggable is on this port. Never fall through to launchBrowser —
+        // that would spawn the duplicate/stray-window this ticket set out to end
+        // (Arc: #2779, PHNX-2399; Comet: PHNX-3967). Fail loud with the relaunch that
+        // makes the canonical instance attachable.
+        if (isAttachOnlyProfile(profile)) {
+            throw attachOnlyRequiredError(profile, port);
         }
         // Distinguish "nothing listening on this port" (fine to launch fresh) from
         // "something is listening but it's not a debuggable browser" (bail loudly —

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

@@ -44,6 +44,34 @@ export type BrowserProfileWithDeclarations = BrowserProfile & {
 export declare function getConfiguredDefaultProfileName(): string | undefined;
 export declare function getBrowserRuntimeDir(): string;
 export declare function getProfileRuntimeDir(name: string): string;
+/**
+ * True when a profile attaches to a browser the user already launched and MUST
+ * NOT spawn its own (PHNX-3967). Arc is inherently attach-only — it is
+ * single-instance and relaunching it just produces a stray window, never a
+ * second debuggable process (issue #2779) — regardless of an explicit policy.
+ * Any other browser is attach-only only when the profile says so.
+ */
+export declare function isAttachOnlyProfile(profile: Pick<BrowserProfile, 'browser' | 'launchPolicy'>): boolean;
+/**
+ * The DURABLE `--user-data-dir` for a profile (PHNX-3967). An explicit
+ * `profile.userDataDir` wins; otherwise a per-profile dir under
+ * `~/.agents/.history/browser-profiles/<name>/chrome-data`, which is outside
+ * `~/.agents/.cache` so a one-time sign-in survives quit+relaunch and the
+ * `profiles remove` cache sweep. This is the dir the canonical Comet is launched
+ * with and the value the ownership guard compares a running instance against.
+ *
+ * Note this is distinct from {@link getProfileRuntimeDir}'s cache `chrome-data`,
+ * which `launchBrowser` uses for a `launch`-policy profile it spawns itself.
+ */
+export declare function resolveProfileDataDir(profile: Pick<BrowserProfile, 'name' | 'userDataDir'>): string;
+/**
+ * Normalize a `--user-data-dir` path for the attach-only ownership comparison
+ * (PHNX-3967): the real path when it resolves on this box, else the literal with
+ * trailing slashes stripped. The single source both the runtime guard
+ * (`drivers/local.ts` `verifyEndpointOwnership`) and `browser profiles doctor`
+ * use, so they can never disagree about whether a running instance is foreign.
+ */
+export declare function normalizeDataDir(dir: string): string;
 /**
  * Default destination for browser downloads for a profile. Set browser-global at
  * connect time (see BrowserService), so downloads land here even when the agent
@@ -217,7 +245,7 @@ export declare function updateProfile(profile: BrowserProfile): Promise<void>;
  * ({@link getProfileRuntimeDir}) and any live `<name>@<endpoint>` connection, so
  * changing either orphans the cached browser data. Delete and recreate instead.
  */
-export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'chrome' | 'secrets' | 'viewport'>>;
+export type EditableProfileFields = Partial<Pick<BrowserProfile, 'description' | 'binary' | 'electron' | 'targetFilter' | 'endpoints' | 'launchPolicy' | 'userDataDir' | 'chrome' | 'secrets' | 'viewport'>>;
 export interface EditProfileResult {
     profile: BrowserProfile;
     devices: string[];

package/dist/lib/browser/profiles.js

@@ -1,6 +1,6 @@
 import * as path from 'path';
 import * as fs from 'fs';
-import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, readMeta, updateMeta, } from '../state.js';
+import { getBrowserRuntimeDir as getBrowserRuntimeDirRoot, getBrowserDurableDir, readMeta, updateMeta, } from '../state.js';
 import { getConfigValue } from '../device-config.js';
 import { machineId } from '../machine-id.js';
 import { declaringDevices, profileRegistry, } from './registry.js';
@@ -51,6 +51,49 @@ export function getBrowserRuntimeDir() {
 export function getProfileRuntimeDir(name) {
     return path.join(getBrowserRuntimeDir(), name);
 }
+/**
+ * True when a profile attaches to a browser the user already launched and MUST
+ * NOT spawn its own (PHNX-3967). Arc is inherently attach-only — it is
+ * single-instance and relaunching it just produces a stray window, never a
+ * second debuggable process (issue #2779) — regardless of an explicit policy.
+ * Any other browser is attach-only only when the profile says so.
+ */
+export function isAttachOnlyProfile(profile) {
+    return profile.browser === 'arc' || profile.launchPolicy === 'attach-only';
+}
+/**
+ * The DURABLE `--user-data-dir` for a profile (PHNX-3967). An explicit
+ * `profile.userDataDir` wins; otherwise a per-profile dir under
+ * `~/.agents/.history/browser-profiles/<name>/chrome-data`, which is outside
+ * `~/.agents/.cache` so a one-time sign-in survives quit+relaunch and the
+ * `profiles remove` cache sweep. This is the dir the canonical Comet is launched
+ * with and the value the ownership guard compares a running instance against.
+ *
+ * Note this is distinct from {@link getProfileRuntimeDir}'s cache `chrome-data`,
+ * which `launchBrowser` uses for a `launch`-policy profile it spawns itself.
+ */
+export function resolveProfileDataDir(profile) {
+    if (profile.userDataDir)
+        return profile.userDataDir;
+    return path.join(getBrowserDurableDir(), profile.name, 'chrome-data');
+}
+/**
+ * Normalize a `--user-data-dir` path for the attach-only ownership comparison
+ * (PHNX-3967): the real path when it resolves on this box, else the literal with
+ * trailing slashes stripped. The single source both the runtime guard
+ * (`drivers/local.ts` `verifyEndpointOwnership`) and `browser profiles doctor`
+ * use, so they can never disagree about whether a running instance is foreign.
+ */
+export function normalizeDataDir(dir) {
+    let out = dir;
+    try {
+        out = fs.realpathSync(dir);
+    }
+    catch {
+        /* dir may not exist on this box; compare the literal */
+    }
+    return out.replace(/\/+$/, '');
+}
 /**
  * Default destination for browser downloads for a profile. Set browser-global at
  * connect time (see BrowserService), so downloads land here even when the agent
@@ -79,6 +122,8 @@ function configToProfile(name, config, devices = []) {
         targetFilter: config.targetFilter,
         endpoints: config.endpoints,
         defaultEndpoint: config.defaultEndpoint,
+        launchPolicy: config.launchPolicy,
+        userDataDir: config.userDataDir,
         chrome: config.chrome,
         secrets: config.secrets,
         viewport: config.viewport,
@@ -103,6 +148,10 @@ function profileToConfig(profile) {
         config.targetFilter = profile.targetFilter;
     if (profile.defaultEndpoint)
         config.defaultEndpoint = profile.defaultEndpoint;
+    if (profile.launchPolicy)
+        config.launchPolicy = profile.launchPolicy;
+    if (profile.userDataDir)
+        config.userDataDir = profile.userDataDir;
     if (profile.chrome)
         config.chrome = profile.chrome;
     if (profile.secrets)

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

@@ -109,6 +109,24 @@ export interface BrowserProfile {
      */
     endpoints: string[] | Record<string, EndpointPreset>;
     defaultEndpoint?: string;
+    /**
+     * How agents obtain a live browser for this profile (PHNX-3967):
+     *   - `launch` (default when absent): spawn the browser under a managed
+     *     `--user-data-dir` when nothing is serving CDP on the port.
+     *   - `attach-only`: NEVER spawn a rival window — attach to a browser the user
+     *     already started with remote debugging, else fail loud with a relaunch
+     *     hint. Arc is inherently attach-only; a canonical signed-in Comet uses it.
+     * Pairs with a durable {@link userDataDir}.
+     */
+    launchPolicy?: 'attach-only' | 'launch';
+    /**
+     * Absolute durable `--user-data-dir` for this profile (PHNX-3967). When absent,
+     * an attach-only profile resolves a default durable dir outside `.cache` so a
+     * one-time sign-in survives relaunch. The value the ownership guard compares a
+     * running instance against to reject a port-squatter. Resolve via
+     * `resolveProfileDataDir(profile)` rather than reading directly.
+     */
+    userDataDir?: string;
     chrome?: ChromeOptions;
     secrets?: string;
     viewport?: {

package/dist/lib/computer/computer-rpc.d.ts

@@ -25,10 +25,15 @@ export declare function resolveTcpEndpoint(): {
     port: number;
     token: string | null;
 } | null;
+export declare function resolveVncEndpoint(): {
+    host: string;
+    port: number;
+    password: string;
+} | null;
 export declare function openComputerClient(): ComputerClient;
 export declare const RPC_TIMEOUT_MS = 30000;
 export declare function resolveRpcTimeoutMs(env: string | undefined): number;
 export declare function describeTransport(): {
-    kind: 'socket' | 'stdio' | 'tcp' | 'none';
+    kind: 'socket' | 'stdio' | 'tcp' | 'vnc' | 'none';
     path: string | null;
 };