@phnx-labs/agents-cli 1.22.79 → 1.22.81

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.22.81
+
+- **Same-task page reopen refreshes the SAME tab instead of duplicating it (PHNX-2399).** When an agent reopens a URL that is already live in one of its browser task's OWN tabs, `agents browser navigate` / `tab add` now issue a real `Page.reload` on that same tab — keeping its tab id and CDP target, marking it current without stealing window focus — and report `refreshed: true` with the note `Tab already open—refreshed`, rather than opening a second copy. Borrowed Arc/user tabs are excluded, a stale registered tab or a failed reload never reports a phantom refresh, and the lookup→reload/create→persist section is serialized per task (and first-use creation per caller) so concurrent requests converge on one tab and the same id. The implicit first-open at the create boundary is reported as a genuine open, not disguised as a refresh. `navigate` / `tab add` gain `--json` (`{ ok, task, tabId, url, created, refreshed, message }`), and `agents browser tabs` again marks the current tab. Source: `cli/src/lib/browser/service.ts`, `cli/src/lib/browser/ipc.ts`, `cli/src/lib/browser/types.ts`, `cli/src/commands/browser.ts`.
+
+## 1.22.80
+
+- **`agents prune cleanup` collapses duplicate account homes to one per account — and keeps the RIGHT one (PHNX-3940).** After the automatic-update pass moves every home to the latest release in place, an account can be left with two homes: the original identity-captured login and a freshly re-logged-in home that only carries an email ("usage unavailable"). Consolidation now groups those together and keeps the home that best represents the account — captured identity first, then a signed-in credential, then the newest running release — instead of the blind highest dir-name semver, which was the just-created duplicate and whose selection trashed the working login. When the retired duplicate held the global default, the default is repointed onto the keeper first, so the duplicate actually collapses instead of being skipped. Retirement stays a reversible soft-delete (`agents restore`). Source: `cli/src/commands/view.ts` (`planDuplicatePrune`).
+
 ## 1.22.79
 
 - **Managed harnesses follow the latest release without replacing account homes (PHNX-3940).** Automatic updates are on by default and configurable with `updates.auto` and per-harness `updates.<harness>.auto`. Updates preserve existing home paths and identities, defer active installations, and stage and verify the executable before committing it. A concrete `--to` release pins an installation; `--to latest` resumes automatic updates. `agents update --check` previews without changing local state. Source: `cli/src/lib/installations/update.ts`, `cli/src/lib/daemon/harness-update-service.ts`, `cli/src/commands/update.ts`.

package/dist/commands/browser.js

@@ -1507,6 +1507,7 @@ function registerTaskCommands(browser) {
         .option('--fps <n>', 'Recording frames per second (with --record; 1–30, default 5)', (v) => parseInt(v, 10))
         .option('--duration <sec>', 'Recording duration cap in seconds (with --record; default 60)', (v) => parseInt(v, 10))
         .option('--max-mb <mb>', 'Recording size cap in MB (with --record; default 25)', (v) => parseInt(v, 10))
+        .option('--json', 'Output machine-readable JSON (task handle + tabId + reused/message)')
         .action(async (opts) => {
         // Fast-fail copy of the consent gate, so a refused start never resolves or
         // auto-creates a profile. The AUTHORITATIVE gate is in the daemon
@@ -1736,12 +1737,33 @@ function registerTaskCommands(browser) {
                 createdAt: Date.now(),
             });
         }
+        // --json: machine-readable, still task-handle-first for callers that parse it.
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                task: response.task,
+                tabId: response.tabId,
+                device: boundDevice,
+                profile: profileName,
+                // `reused` is task-level; `created`/`refreshed` describe the page op.
+                reused: response.reused === true,
+                created: response.created,
+                refreshed: response.refreshed,
+                message: response.message,
+            }, null, 2));
+            return;
+        }
         // stdout: just the resolved name, one line, no decoration. Lets callers do:
         //   export AGENTS_BROWSER_TASK=$(agents browser start --profile work)
         console.log(response.task);
         // stderr: human-friendly commentary so a TTY user still sees what happened.
-        // Shell substitution captures stdout only, so $(...) stays clean.
-        console.error(`Task "${response.task}" started on ${boundDevice} (profile: ${profileName}).`);
+        // Shell substitution captures stdout only, so $(...) stays clean. A same-name
+        // retry reused the TASK — key on `reused`, not the page-level `refreshed`
+        // (a no-URL retry reuses the task without reloading anything).
+        const startVerb = response.reused ? 'reused' : 'started';
+        console.error(`Task "${response.task}" ${startVerb} on ${boundDevice} (profile: ${profileName}).`);
+        if (response.message)
+            console.error(response.message);
         if (opts.url && response.tabId) {
             console.error(`Tab ${response.tabId}`);
         }
@@ -1938,6 +1960,7 @@ function registerTaskCommands(browser) {
         .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-u, --url <url>', 'URL to navigate to (or pass it positionally)')
         .option('-p, --profile <name>', 'Browser profile (optional if task is unique)')
+        .option('--json', 'Output machine-readable JSON')
         .action(async (urlPos, opts) => {
         const url = urlPos || opts.url;
         if (!url) {
@@ -1952,13 +1975,34 @@ function registerTaskCommands(browser) {
             profile: opts.profile ? await resolveProfileRef(opts.profile) : undefined,
         });
         if (!response.ok) {
-            console.error(response.error);
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, error: response.error }));
+            else
+                console.error(response.error);
             process.exit(1);
         }
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                task: response.task,
+                tabId: response.tabId,
+                url,
+                created: response.created ?? false,
+                refreshed: response.refreshed ?? false,
+                message: response.message,
+            }, null, 2));
+            return;
+        }
         if (response.task) {
             console.error(`task ${response.task}`);
         }
-        console.log(`Navigated ${response.tabId} to ${url}`);
+        // Honest human output: a same-task reopen reloaded the SAME tab rather than
+        // navigating a fresh one (PHNX-2399). Any picked-device / reopen note rides
+        // stderr so stdout stays the one-line result.
+        if (response.message)
+            console.error(response.message);
+        const verb = response.refreshed ? 'Refreshed' : 'Navigated';
+        console.log(`${verb} ${response.tabId} to ${url}`);
     });
     // Tab subcommand group
     const tab = browser.command('tab').description('Manage tabs');
@@ -1969,6 +2013,7 @@ function registerTaskCommands(browser) {
         .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .requiredOption('--url <url>', 'URL to open in the new tab')
         .option('-p, --profile <name>', 'Browser profile')
+        .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
         const task = resolveTaskName(opts);
         const response = await sendIPCRequest({
@@ -1978,10 +2023,34 @@ function registerTaskCommands(browser) {
             profile: opts.profile ? await resolveProfileRef(opts.profile) : undefined,
         });
         if (!response.ok) {
-            console.error(response.error);
+            if (opts.json)
+                console.log(JSON.stringify({ ok: false, error: response.error }));
+            else
+                console.error(response.error);
             process.exit(1);
         }
-        console.log(`Opened tab ${response.tabId}: ${opts.url}`);
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                task: response.task,
+                tabId: response.tabId,
+                url: opts.url,
+                created: response.created ?? false,
+                refreshed: response.refreshed ?? false,
+                message: response.message,
+            }, null, 2));
+            return;
+        }
+        // A reopen of a URL already in an owned tab refreshes that tab in place
+        // rather than opening a duplicate (PHNX-2399).
+        if (response.refreshed) {
+            if (response.message)
+                console.error(response.message);
+            console.log(`Refreshed tab ${response.tabId}: ${opts.url}`);
+        }
+        else {
+            console.log(`Opened tab ${response.tabId}: ${opts.url}`);
+        }
     });
     tab
         .command('focus <tabId>')

package/dist/commands/view.d.ts

@@ -95,6 +95,23 @@ export declare function parseResourceSections(options: {
 export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSections?: Set<ResourceSection>, opts?: {
     forceRefresh?: boolean;
 }): Promise<ViewJsonAgent[]>;
+interface PrunePlanEntry {
+    agentId: AgentId;
+    version: string;
+    email: string;
+    keeper: string;
+    isDefault: boolean;
+    /**
+     * 'duplicate'    — older version sharing an email with a newer install.
+     * 'home-leftover' — home-only dir left over after a previous removeVersion;
+     *                   no binary, but transcripts may still live here.
+     */
+    reason: 'duplicate' | 'home-leftover';
+}
+interface AgentPrunePlan {
+    agentId: AgentId;
+    toPrune: PrunePlanEntry[];
+}
 /**
  * Identity key for duplicate-install detection. Prefers accountKey — which
  * encodes account AND org — over the bare email: two installs can share an
@@ -104,10 +121,55 @@ export declare function collectAgentsJson(filterAgentId?: AgentId, resourceSecti
  * identity key. Null when there is no usable identity.
  */
 export declare function pruneGroupKey(info: Pick<AccountInfo, 'accountKey' | 'email'>): string | null;
+/** One installed home, reduced to the fields duplicate detection needs. */
+export interface PruneCandidate {
+    /** The version-dir label (opaque slot id). */
+    version: string;
+    /** The RUNNING release inside the home (installation.releaseVersion), or the label. */
+    release: string;
+    email: string | null;
+    /** Present only once the home's native identity is captured (claude: account+org). */
+    accountKey: string | null;
+    signedIn: boolean;
+    hasBinary: boolean;
+}
+/** A duplicate home to retire, and the keeper it collapses into. */
+export interface DuplicatePruneEntry {
+    version: string;
+    email: string;
+    keeper: string;
+}
+/**
+ * PURE duplicate-home detection: given every installed home for one agent, decide
+ * which are redundant duplicates of the SAME logical account and which single home
+ * to keep per account. Extracted from buildAgentPrunePlan so the keeper/merge rules
+ * are unit-tested without touching disk.
+ *
+ * Two rules, both conservative:
+ *  - GROUPING. A home with a captured `accountKey` groups by it (account+org, so a
+ *    personal Max and a Team seat on the same email stay separate). A home with NO
+ *    accountKey folds into a same-email account ONLY when a sibling home for that
+ *    email IS identified — that email-only home is an incompletely-captured re-login
+ *    of the known account, not a distinct seat (PHNX-3887). Otherwise it groups by
+ *    its bare email and only ever collapses against another equally-bare home.
+ *  - KEEPER. Within a group the keeper is the home that best represents the account:
+ *    captured identity first, then a signed-in credential, then the newest RUNNING
+ *    release, then the highest dir label as a stable tiebreak. This is deliberately
+ *    NOT "highest dir-name semver" — in the wild that is the freshly re-logged-in
+ *    duplicate that never captured its identity or usage, and keeping it while
+ *    trashing the identified home is the exact bug this replaces.
+ */
+export declare function planDuplicatePrune(candidates: PruneCandidate[]): DuplicatePruneEntry[];
+export declare function executePrunePlan(plan: AgentPrunePlan): Promise<Array<{
+    agent: AgentId;
+    version: string;
+}>>;
 /**
- * Prune older installed versions that share an email with a newer installed
- * version. Keeps the highest semver per email, skips the global default (with
- * a warning so the user can switch first).
+ * Consolidate to one home per logical account: retire the redundant duplicate
+ * homes an account accumulated, keeping the single home that best represents it
+ * (see {@link planDuplicatePrune} for the keeper/merge rules). When the retired
+ * duplicate holds the global default, the default is first repointed onto the
+ * keeper, so consolidation collapses it instead of leaving it pinned.
  *
  * When filterAgentId is set, prunes that agent first, then cascades: after
  * each agent, offers the next agent with duplicates. User answering "no"

package/dist/commands/view.js

@@ -11,7 +11,7 @@ import { authCacheKey, readAuthHealthCache } from '../lib/auth-health.js';
 import { agentReportsUsage, classifyUsageErrorKind, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageBenignState, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, isUsageHeadlessScopeError, usageErrorForDisplay, } from '../lib/accounting/usage.js';
 import { isHeadedDeviceRole, selfConfiguredDeviceRole } from '../lib/device-config.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/installations/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/installations/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/installations/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { renderMergedResources } from '../lib/merged-resources.js';
@@ -1455,50 +1455,116 @@ export async function collectAgentsJson(filterAgentId, resourceSections, opts) {
 export function pruneGroupKey(info) {
     return info.accountKey ?? info.email?.toLowerCase() ?? null;
 }
+/**
+ * PURE duplicate-home detection: given every installed home for one agent, decide
+ * which are redundant duplicates of the SAME logical account and which single home
+ * to keep per account. Extracted from buildAgentPrunePlan so the keeper/merge rules
+ * are unit-tested without touching disk.
+ *
+ * Two rules, both conservative:
+ *  - GROUPING. A home with a captured `accountKey` groups by it (account+org, so a
+ *    personal Max and a Team seat on the same email stay separate). A home with NO
+ *    accountKey folds into a same-email account ONLY when a sibling home for that
+ *    email IS identified — that email-only home is an incompletely-captured re-login
+ *    of the known account, not a distinct seat (PHNX-3887). Otherwise it groups by
+ *    its bare email and only ever collapses against another equally-bare home.
+ *  - KEEPER. Within a group the keeper is the home that best represents the account:
+ *    captured identity first, then a signed-in credential, then the newest RUNNING
+ *    release, then the highest dir label as a stable tiebreak. This is deliberately
+ *    NOT "highest dir-name semver" — in the wild that is the freshly re-logged-in
+ *    duplicate that never captured its identity or usage, and keeping it while
+ *    trashing the identified home is the exact bug this replaces.
+ */
+export function planDuplicatePrune(candidates) {
+    // Only installs with a working binary compete for "the live install for this account".
+    const installed = candidates.filter((c) => c.hasBinary && c.email);
+    // email -> every DISTINCT captured accountKey seen for it. An email-only home
+    // folds into an identified account only when that email maps to EXACTLY ONE
+    // account; when two distinct orgs share the email (the Personal+Team case) the
+    // fold is ambiguous, so the identity-less home is left ungrouped rather than
+    // guessed into one — guessing could retire the actually-working re-login of the
+    // OTHER org (the exact bug this function exists to prevent, one level up).
+    const emailToAccountKeys = new Map();
+    for (const c of installed) {
+        if (!c.accountKey)
+            continue;
+        const email = c.email.toLowerCase();
+        (emailToAccountKeys.get(email) ?? emailToAccountKeys.set(email, new Set()).get(email)).add(c.accountKey);
+    }
+    const groupKeyFor = (c) => {
+        if (c.accountKey)
+            return c.accountKey;
+        const email = c.email?.toLowerCase();
+        const keys = email ? emailToAccountKeys.get(email) : undefined;
+        if (keys && keys.size === 1)
+            return [...keys][0];
+        // ≥2 identified orgs on this email: never merge the ambiguous home. A unique
+        // key makes it its own singleton group (length 1 → never pruned).
+        if (keys && keys.size >= 2)
+            return `ambiguous:${c.email.toLowerCase()}:${c.version}`;
+        // No identified sibling at all: group equally-bare homes by email as before.
+        return pruneGroupKey(c);
+    };
+    const byAccount = new Map();
+    for (const c of installed) {
+        const key = groupKeyFor(c);
+        if (!key)
+            continue;
+        (byAccount.get(key) ?? byAccount.set(key, []).get(key)).push(c);
+    }
+    const rank = (c) => [c.accountKey ? 1 : 0, c.signedIn ? 1 : 0];
+    const better = (a, b) => {
+        const [aa, ab] = rank(a);
+        const [ba, bb] = rank(b);
+        if (aa !== ba)
+            return ba - aa;
+        if (ab !== bb)
+            return bb - ab;
+        if (a.release !== b.release)
+            return compareVersions(b.release, a.release);
+        return compareVersions(b.version, a.version);
+    };
+    const out = [];
+    for (const group of byAccount.values()) {
+        if (group.length < 2)
+            continue;
+        const sorted = [...group].sort(better);
+        const keeper = sorted[0].version;
+        for (const dup of sorted.slice(1)) {
+            out.push({ version: dup.version, email: dup.email, keeper });
+        }
+    }
+    return out;
+}
 async function buildAgentPrunePlan(agentId) {
     const dirInfos = listInstalledVersionDirs(agentId);
     const entries = await Promise.all(dirInfos.map(async ({ version, hasBinary }) => {
         const home = getVersionHomePath(agentId, version);
         const info = await getAccountInfo(agentId, home);
-        return { version, info, hasBinary };
+        const release = readInstallation(agentId, version)?.releaseVersion ?? version;
+        return { version, info, hasBinary, release };
     }));
     const globalDefault = getGlobalDefault(agentId);
     const toPrune = [];
-    const skippedDefaults = [];
-    // Duplicate-account detection runs only over installs that actually have a
-    // working binary — those are the things that compete for "the live install
-    // for this account."
-    const installed = entries.filter((e) => e.hasBinary);
-    const byAccount = new Map();
-    for (const e of installed) {
-        if (!e.info.email)
-            continue;
-        const key = pruneGroupKey(e.info);
-        if (!key)
-            continue;
-        const list = byAccount.get(key) ?? [];
-        list.push(e);
-        byAccount.set(key, list);
-    }
-    for (const [, group] of byAccount) {
-        if (group.length < 2)
-            continue;
-        const sorted = [...group].sort((a, b) => compareVersions(b.version, a.version));
-        const keeper = sorted[0].version;
-        for (const older of sorted.slice(1)) {
-            const plan = {
-                agentId,
-                version: older.version,
-                email: older.info.email,
-                keeper,
-                isDefault: older.version === globalDefault,
-                reason: 'duplicate',
-            };
-            if (plan.isDefault)
-                skippedDefaults.push(plan);
-            else
-                toPrune.push(plan);
-        }
+    for (const d of planDuplicatePrune(entries.map((e) => ({
+        version: e.version,
+        release: e.release,
+        email: e.info.email,
+        accountKey: e.info.accountKey,
+        signedIn: e.info.signedIn,
+        hasBinary: e.hasBinary,
+    })))) {
+        toPrune.push({
+            agentId,
+            version: d.version,
+            email: d.email,
+            keeper: d.keeper,
+            // The default may itself be a to-be-retired duplicate (a freshly created
+            // home often becomes the global default). We do NOT skip it: executePrune
+            // repoints the default onto the keeper first, then retires the duplicate.
+            isDefault: d.version === globalDefault,
+            reason: 'duplicate',
+        });
     }
     // Home-only leftovers: dirs without a binary. These are residue from a
     // prior removeVersion before the soft-delete migration, plus any hand-edited
@@ -1517,10 +1583,20 @@ async function buildAgentPrunePlan(agentId) {
             reason: 'home-leftover',
         });
     }
-    return { agentId, toPrune, skippedDefaults };
+    return { agentId, toPrune };
 }
-async function executePrunePlan(plan) {
+export async function executePrunePlan(plan) {
     const moved = [];
+    // Repoint the global default onto the keeper BEFORE retiring a duplicate that
+    // currently holds it, so consolidation collapses the duplicate instead of
+    // leaving it pinned as the default (and so removeVersion's own fallback never
+    // has to guess a replacement).
+    for (const p of plan.toPrune) {
+        if (p.reason === 'duplicate' && p.isDefault && p.keeper && p.keeper !== p.version) {
+            setGlobalDefault(p.agentId, p.keeper);
+            console.log(chalk.gray(`Default ${agentLabel(p.agentId)} moved ${p.version} → ${p.keeper} (keeper) before pruning the duplicate.`));
+        }
+    }
     for (const p of plan.toPrune) {
         const ok = removeVersion(p.agentId, p.version);
         if (ok) {
@@ -1537,14 +1613,6 @@ async function executePrunePlan(plan) {
     return moved;
 }
 function printPrunePlan(plan, isFirst) {
-    if (plan.skippedDefaults.length > 0) {
-        console.log(chalk.yellow(`Skipping default versions for ${agentLabel(plan.agentId)} (switch default first):`));
-        for (const s of plan.skippedDefaults) {
-            console.log(`  ${agentLabel(s.agentId)}@${s.version}  ${chalk.cyan(s.email)}  ` +
-                chalk.gray(`— duplicate of ${s.agentId}@${s.keeper}. Run: agents use ${s.agentId}@${s.keeper}`));
-        }
-        console.log();
-    }
     if (plan.toPrune.length === 0)
         return;
     const heading = isFirst ? `Will move to trash for ${agentLabel(plan.agentId)}:` : `Also found candidates for ${agentLabel(plan.agentId)}:`;
@@ -1562,9 +1630,11 @@ function printPrunePlan(plan, isFirst) {
     console.log();
 }
 /**
- * Prune older installed versions that share an email with a newer installed
- * version. Keeps the highest semver per email, skips the global default (with
- * a warning so the user can switch first).
+ * Consolidate to one home per logical account: retire the redundant duplicate
+ * homes an account accumulated, keeping the single home that best represents it
+ * (see {@link planDuplicatePrune} for the keeper/merge rules). When the retired
+ * duplicate holds the global default, the default is first repointed onto the
+ * keeper, so consolidation collapses it instead of leaving it pinned.
  *
  * When filterAgentId is set, prunes that agent first, then cascades: after
  * each agent, offers the next agent with duplicates. User answering "no"
@@ -1577,7 +1647,7 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
     const spinner = ora({ text: 'Scanning installed versions...', isSilent: !process.stdout.isTTY }).start();
     const plans = await Promise.all(ordered.map((a) => buildAgentPrunePlan(a)));
     spinner.stop();
-    const actionable = plans.filter((p) => p.toPrune.length > 0 || p.skippedDefaults.length > 0);
+    const actionable = plans.filter((p) => p.toPrune.length > 0);
     if (actionable.length === 0) {
         console.log(chalk.gray('Nothing to prune — no duplicate-account installs and no home-only leftovers.'));
         return;
@@ -1588,11 +1658,6 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
     let processedAny = false;
     for (const plan of actionable) {
         printPrunePlan(plan, isFirst);
-        if (plan.toPrune.length === 0) {
-            // Only skippedDefaults for this agent; move on.
-            isFirst = false;
-            continue;
-        }
         if (dryRun) {
             processedAny = true;
             isFirst = false;

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

@@ -105,7 +105,14 @@ export declare class BrowserIPCServer {
     private connections;
     /** In-flight stop, so a second SIGTERM awaits the same close, never skips it. */
     private stopping;
-    constructor(service: BrowserService);
+    /**
+     * Optional explicit socket path for TEST ISOLATION only (POSIX). When set, the
+     * server binds (and unlinks a stale copy of) THIS path instead of the shared
+     * production `browser.sock`, so a test never unlinks the user's live daemon
+     * socket. Default (undefined) is unchanged. Not for production use.
+     */
+    private readonly socketPathOverride?;
+    constructor(service: BrowserService, socketPathOverride?: string);
     start(): Promise<void>;
     /**
      * Stop accepting, release the binding, and only then resolve.

package/dist/lib/browser/ipc.js

@@ -443,12 +443,23 @@ export class BrowserIPCServer {
     connections = new Set();
     /** In-flight stop, so a second SIGTERM awaits the same close, never skips it. */
     stopping = null;
-    constructor(service) {
+    /**
+     * Optional explicit socket path for TEST ISOLATION only (POSIX). When set, the
+     * server binds (and unlinks a stale copy of) THIS path instead of the shared
+     * production `browser.sock`, so a test never unlinks the user's live daemon
+     * socket. Default (undefined) is unchanged. Not for production use.
+     */
+    socketPathOverride;
+    constructor(service, socketPathOverride) {
         this.service = service;
+        this.socketPathOverride = socketPathOverride;
     }
     async start() {
-        const socketPath = getSocketPath();
-        const endpoint = getIpcEndpoint();
+        const socketPath = this.socketPathOverride ?? getSocketPath();
+        // On POSIX the endpoint IS the socket path; an override addresses the same
+        // isolated file. (Windows keeps its derived pipe name; the override is
+        // POSIX-only test machinery.)
+        const endpoint = this.socketPathOverride ?? getIpcEndpoint();
         const socketDir = path.dirname(socketPath);
         fs.mkdirSync(socketDir, { recursive: true, mode: 0o700 });
         if (!IS_WINDOWS) {
@@ -615,6 +626,13 @@ export class BrowserIPCServer {
     async bindTask(request) {
         const createIfMissing = PAGE_CREATE_VERBS.has(request.action);
         const isClose = CLOSE_VERBS.has(request.action);
+        // NEVER trust these off the wire — they are server-derived bind state written
+        // BELOW from the resolver's own result. A client that pre-set `firstOpen` in
+        // its request JSON could otherwise steer navigate/tab-add to short-circuit
+        // onto an arbitrary tab id / forged created flag (or forge a picked-device
+        // hint). Clear before binding so only this handler's values survive (PHNX-2399).
+        delete request.firstOpen;
+        delete request.picked;
         // stop with --profile only (no task) is handled by the stop case itself.
         if (request.action === 'stop' && request.profile && !request.task)
             return undefined;
@@ -643,6 +661,13 @@ export class BrowserIPCServer {
             if (resolved.created && resolved.picked) {
                 request.picked = resolved.picked;
             }
+            // The implicit create already opened request.url on this tab. Carry the
+            // ACTUAL page result so the navigate/tab-add handler reports that first
+            // open honestly (created/refreshed as it happened) instead of executing
+            // the URL a second time (PHNX-2399).
+            if (resolved.created && resolved.firstOpen) {
+                request.firstOpen = resolved.firstOpen;
+            }
             return undefined;
         }
         catch (err) {
@@ -738,13 +763,26 @@ export class BrowserIPCServer {
                     fleetRemote: request.fleetRemote,
                     title: request.title,
                 });
+                // `reused` is task-level (a same-name retry matched an existing task);
+                // `created`/`refreshed` describe the actual PAGE operation, carried from
+                // `firstOpen`. A no-URL retry is `reused: true` with created/refreshed
+                // both false — no reload happened, so it must NOT read as refreshed. A
+                // pure task reuse with no page refresh gets the "Reused existing task"
+                // note; a same-URL reopen gets its own "Tab already open—refreshed" note
+                // from `firstOpen.message` (PHNX-2399).
+                const startReuseNote = result.reused && !result.firstOpen?.refreshed && !result.firstOpen?.created
+                    ? 'Reused existing task'
+                    : undefined;
                 return {
                     ok: true,
                     task: result.name,
                     tabId: result.tabId,
                     windowTargetId: result.windowId,
                     skill: result.skill,
-                    message: result.picked,
+                    reused: result.reused,
+                    created: result.firstOpen?.created,
+                    refreshed: result.firstOpen?.refreshed,
+                    message: [result.picked, result.firstOpen?.message, startReuseNote].filter(Boolean).join(' · ') || undefined,
                 };
             }
             // The out-of-process seam onto the abandoned-task reaper: the daemon
@@ -824,16 +862,60 @@ export class BrowserIPCServer {
                         error: actionable('No browser task for this session.', 'Next: agents browser navigate <url>  |  agents browser start'),
                     };
                 }
-                const result = await this.service.navigate(request.task, request.url, request.profile);
+                // The implicit create already opened this URL on this tab. Report the
+                // ACTUAL first-open result (adopt → created:false, fresh → created:true)
+                // instead of re-navigating it or assuming a create (PHNX-2399).
+                const firstOpen = request.firstOpen;
                 const picked = request.picked;
-                return { ok: true, tabId: result.tabId, task: request.task, message: picked };
+                if (firstOpen) {
+                    return {
+                        ok: true,
+                        tabId: firstOpen.tabId,
+                        task: request.task,
+                        created: firstOpen.created,
+                        refreshed: firstOpen.refreshed,
+                        message: [picked, firstOpen.message].filter(Boolean).join(' · ') || undefined,
+                    };
+                }
+                const result = await this.service.navigate(request.task, request.url, request.profile);
+                return {
+                    ok: true,
+                    tabId: result.tabId,
+                    task: request.task,
+                    created: result.created,
+                    refreshed: result.refreshed,
+                    // A picked-device hint and a reopen note are distinct signals; combine
+                    // them so a first navigate on a remote-picked device still surfaces the
+                    // pick, and a plain reopen surfaces the refresh note.
+                    message: [picked, result.message].filter(Boolean).join(' · ') || undefined,
+                };
             }
             case 'tab-add': {
                 if (!request.task || !request.url) {
                     return { ok: false, error: 'Task and URL required' };
                 }
+                const tabAddPicked = request.picked;
+                const firstOpen = request.firstOpen;
+                if (firstOpen) {
+                    return {
+                        ok: true,
+                        tabId: firstOpen.tabId,
+                        task: request.task,
+                        created: firstOpen.created,
+                        refreshed: firstOpen.refreshed,
+                        message: [tabAddPicked, firstOpen.message].filter(Boolean).join(' · ') || undefined,
+                    };
+                }
                 const result = await this.service.tabAdd(request.task, request.url, request.profile);
-                return { ok: true, tabId: result.tabId };
+                return {
+                    ok: true,
+                    tabId: result.tabId,
+                    task: request.task,
+                    created: result.created,
+                    refreshed: result.refreshed,
+                    // Keep the picked-device hint AND any reopen note (same shape as navigate).
+                    message: [tabAddPicked, result.message].filter(Boolean).join(' · ') || undefined,
+                };
             }
             case 'tab-focus': {
                 if (!request.task || !request.tabId) {
@@ -854,7 +936,10 @@ export class BrowserIPCServer {
                     return { ok: false, error: 'Task required' };
                 }
                 const tabs = await this.service.tabList(request.task);
-                return { ok: true, tabs: tabs.map(t => ({ id: t.id, url: t.url, title: t.title, task: request.task })) };
+                // Carry `current` through — it is the one field a caller needs to show
+                // which tab URL-less verbs act on, and dropping it here left `agents
+                // browser tabs` unable to mark the selection (PHNX-2399).
+                return { ok: true, tabs: tabs.map(t => ({ id: t.id, url: t.url, title: t.title, current: t.current, task: request.task })) };
             }
             case 'evaluate': {
                 if (!request.task || !request.expr) {