@phnx-labs/agents-cli 1.22.80 → 1.22.81

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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`).

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/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) {

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

@@ -4,7 +4,7 @@ import { type ResolvedDomainSkill } from './domain-skills.js';
 import { type Task, type TabInfo, type ProfileStatus, type BrowserType, type HistoricalTask, type ReapResult, type ProfileName, type ConnectionKey } from './types.js';
 import { type ReapOptions } from './hygiene.js';
 import { type RefOpts, type RefNode } from './refs.js';
-import type { TargetFilter } from './types.js';
+import type { TargetFilter, PageOpenResult } from './types.js';
 export type UploadMode = 'auto' | 'input' | 'drop' | 'chooser';
 export declare function resolveScreenshotOutputPath(outputPath: string | undefined, automaticPath: string): string;
 /**
@@ -135,6 +135,49 @@ export declare function resolveTaskIdentity(forwarded: {
     launchId?: string;
     sessionId?: string;
 };
+export interface StartOptions {
+    taskName?: string;
+    url?: string;
+    endpointName?: string;
+    skipDomainSkill?: boolean;
+    /** Always open a new tab, skipping the abandoned-task reclaim. */
+    fresh?: boolean;
+    /** Caller identity, forwarded from the CLI (see IPCRequest.actor/launchId). */
+    actor?: string;
+    launchId?: string;
+    /** Calling agent session, forwarded from the CLI (see IPCRequest.sessionId). */
+    sessionId?: string;
+    /** Whether the CALLER was dispatched here by a fleet `--device` hop. */
+    fleetRemote?: boolean;
+    /** Explicit human label (`--title`). */
+    title?: string;
+    /** Injected reachability probe — production uses ssh; tests pass a fake. */
+    probe?: DeviceProbe;
+}
+export interface StartResult {
+    task: string;
+    name: string;
+    tabId?: string;
+    windowId?: string;
+    /** BARE profile name — what the caller asked for, never the runtime key. */
+    profile: ProfileName;
+    /** Runtime key the task actually landed on (`<profile>@<device>`). */
+    key: ConnectionKey;
+    /** Device the daemon connected to. */
+    device: string;
+    /** Set when the daemon picked a remote declaring device. */
+    picked?: string;
+    skill?: ResolvedDomainSkill;
+    /** A same-name start that matched an existing task and reused it (PHNX-2399). */
+    reused?: boolean;
+    /**
+     * The actual page operation the URL open performed (PHNX-2399), or undefined
+     * when start opened no URL. Carries created/refreshed/message truthfully:
+     * a fresh tab is `created`, a same-URL owned-tab reopen is `refreshed`, an
+     * adopted abandoned tab or a no-op reuse is neither.
+     */
+    firstOpen?: PageOpenResult;
+}
 export declare class BrowserService {
     private static readonly SOURCE_PREFIX;
     /**
@@ -155,39 +198,56 @@ export declare class BrowserService {
     private lastTouchPersist;
     /** Coalescing window for the `touchTask` write. See {@link touchTask}. */
     private static readonly TOUCH_PERSIST_INTERVAL_MS;
-    start(profileName: string, opts?: {
-        taskName?: string;
-        url?: string;
-        endpointName?: string;
-        skipDomainSkill?: boolean;
-        /** Always open a new tab, skipping the abandoned-task reclaim. */
-        fresh?: boolean;
-        /** Caller identity, forwarded from the CLI (see IPCRequest.actor/launchId). */
-        actor?: string;
-        launchId?: string;
-        /** Calling agent session, forwarded from the CLI (see IPCRequest.sessionId). */
-        sessionId?: string;
-        /** Whether the CALLER was dispatched here by a fleet `--device` hop. */
-        fleetRemote?: boolean;
-        /** Explicit human label (`--title`). */
-        title?: string;
-        /** Injected reachability probe — production uses ssh; tests pass a fake. */
-        probe?: DeviceProbe;
-    }): Promise<{
-        task: string;
-        name: string;
-        tabId?: string;
-        windowId?: string;
-        /** BARE profile name — what the caller asked for, never the runtime key. */
-        profile: ProfileName;
-        /** Runtime key the task actually landed on (`<profile>@<device>`). */
-        key: ConnectionKey;
-        /** Device the daemon connected to. */
-        device: string;
-        /** Set when the daemon picked a remote declaring device. */
-        picked?: string;
-        skill?: ResolvedDomainSkill;
-    }>;
+    /**
+     * Serialization chains for the reopen/create critical section (PHNX-2399).
+     * Nothing else serializes IPC requests — `BrowserIPCServer` registers a
+     * per-connection `socket.on('data', async …)` that Node never awaits — so two
+     * concurrent `navigate`/`tab-add` requests, or two concurrent first-use
+     * creates for one caller, race the "is this URL already open?" lookup and each
+     * open a duplicate tab. Each key funnels its section through a promise chain so
+     * the second request sees the first's tab and refreshes it in place.
+     *
+     * Keys are DISJOINT by concern so a nested call can never wait on a lock its
+     * own outer frame holds: task-scoped work keys on `task:<key>:<name>`, first-
+     * use creation keys on `create:<callerId>`. `start()`'s Arc/Electron branch
+     * calls `navigate()` (a `task:` key) while the create path holds a `create:`
+     * key — different namespaces, so no re-entrant deadlock.
+     */
+    private critical;
+    /**
+     * Run `fn` mutually exclusive against every other call sharing `key`. The
+     * chain never rejects (each link swallows its own settlement) so one failed
+     * section cannot wedge the queue; `fn`'s own result/throw is returned to THIS
+     * caller unchanged. The map entry is dropped once its tail settles with no
+     * newer waiter, so idle tasks/callers don't accumulate.
+     */
+    private runExclusive;
+    /**
+     * The task's OWN tabs (excluding borrowed ones — a borrowed tab predates the
+     * task, see {@link Task.borrowedTabs}) that are still live in the browser AND
+     * whose current document canonically equals `url`. Deliberately scoped to THIS
+     * task: it is neither {@link adoptTabShowing} (reclaims OTHER abandoned tasks'
+     * tabs) nor {@link pickReusableTargetWithoutCreate} (borrows a USER tab on Arc)
+     * — the same-task reopen contract only ever touches a tab the task itself owns.
+     * A registered id with no live target (a tab closed out from under us) is
+     * skipped, so a stale mapping never masquerades as a reopenable tab.
+     */
+    private findOwnedTabShowing;
+    /**
+     * Same-task reopen (PHNX-2399): the requested URL is already live in a tab this
+     * task owns, so RELOAD that same tab and keep its ids rather than opening a
+     * duplicate. Returns the retained short id, or undefined when no owned tab
+     * shows the URL (the caller then falls through to its normal navigate/create
+     * semantics — that no-match split is intentional and preserved).
+     *
+     * A real `Page.reload` is issued; a failed reload THROWS rather than reporting
+     * a phantom refresh (a stale target was already excluded by
+     * {@link findOwnedTabShowing}). The tab is marked current WITHOUT
+     * `Target.activateTarget` — reopen must not steal window focus.
+     */
+    private reopenOwnedTab;
+    start(profileName: string, opts?: StartOptions): Promise<StartResult>;
+    private startBody;
     /**
      * Reclaim a live page already showing `url` from an ABANDONED task, instead
      * of opening a second copy of the same page (RUSH-2622). Returns its CDP
@@ -271,11 +331,18 @@ export declare class BrowserService {
         tabId: string;
         url: string;
         created: boolean;
+        refreshed: boolean;
+        message?: string;
     }>;
+    private navigateLocked;
     tabAdd(taskId: string, url: string, profileRef?: ProfileName | ConnectionKey): Promise<{
         tabId: string;
         url: string;
+        created: boolean;
+        refreshed: boolean;
+        message?: string;
     }>;
+    private tabAddLocked;
     tabFocus(taskId: string, tabHint: string): Promise<{
         tabId: string;
     }>;
@@ -471,6 +538,18 @@ export declare class BrowserService {
     private createPageTarget;
     private getOrCreateWindow;
     private hasTaskNamed;
+    /** The (connection, task) a handle names anywhere, or undefined. */
+    private findTaskByHandle;
+    /**
+     * Same-name `start --task <name>` retry (PHNX-2399). When a task by that name
+     * already exists this REUSES it — reopening the URL in the same tab (same id,
+     * a real reload, the `Tab already open—refreshed` note) — but only after
+     * proving it is genuinely the same task: same bare profile, same endpoint, and
+     * a matching caller identity. A mismatch on any of those is a real conflict and
+     * throws, so a different caller/profile/endpoint can never silently acquire
+     * another task. Serialized by the `namedstart:` lock in {@link start}.
+     */
+    private retryNamedStart;
     /** Map key for a task on a connection (tasks are keyed by `name`). */
     private taskMapKey;
     /** Find a task by map key, id, or name on one connection. */
@@ -503,7 +582,16 @@ export declare class BrowserService {
         created: boolean;
         picked?: string;
         device?: string;
+        /**
+         * When this call CREATED the task by starting a browser on `opts.url`, the
+         * page operation `start` already performed on that URL. The owning IPC
+         * handler reports it truthfully (adopt → created:false, Arc reuse →
+         * created:false, fresh tab → created:true) instead of re-running the
+         * navigate/tab-add (a duplicate execution) and assuming a create (PHNX-2399).
+         */
+        firstOpen?: PageOpenResult;
     } | null>;
+    private resolveOrCreateByIdentity;
     private listTasksForCaller;
     private currentUrlHint;
     /**

package/dist/lib/browser/service.js

@@ -318,7 +318,110 @@ export class BrowserService {
     lastTouchPersist = new Map();
     /** Coalescing window for the `touchTask` write. See {@link touchTask}. */
     static TOUCH_PERSIST_INTERVAL_MS = 60_000;
+    /**
+     * Serialization chains for the reopen/create critical section (PHNX-2399).
+     * Nothing else serializes IPC requests — `BrowserIPCServer` registers a
+     * per-connection `socket.on('data', async …)` that Node never awaits — so two
+     * concurrent `navigate`/`tab-add` requests, or two concurrent first-use
+     * creates for one caller, race the "is this URL already open?" lookup and each
+     * open a duplicate tab. Each key funnels its section through a promise chain so
+     * the second request sees the first's tab and refreshes it in place.
+     *
+     * Keys are DISJOINT by concern so a nested call can never wait on a lock its
+     * own outer frame holds: task-scoped work keys on `task:<key>:<name>`, first-
+     * use creation keys on `create:<callerId>`. `start()`'s Arc/Electron branch
+     * calls `navigate()` (a `task:` key) while the create path holds a `create:`
+     * key — different namespaces, so no re-entrant deadlock.
+     */
+    critical = new Map();
+    /**
+     * Run `fn` mutually exclusive against every other call sharing `key`. The
+     * chain never rejects (each link swallows its own settlement) so one failed
+     * section cannot wedge the queue; `fn`'s own result/throw is returned to THIS
+     * caller unchanged. The map entry is dropped once its tail settles with no
+     * newer waiter, so idle tasks/callers don't accumulate.
+     */
+    async runExclusive(key, fn) {
+        const prev = this.critical.get(key) ?? Promise.resolve();
+        const run = prev.then(fn, fn);
+        const tail = run.then(() => undefined, () => undefined);
+        this.critical.set(key, tail);
+        try {
+            return await run;
+        }
+        finally {
+            // Only the last link clears the entry; a newer waiter has replaced it.
+            if (this.critical.get(key) === tail)
+                this.critical.delete(key);
+        }
+    }
+    /**
+     * The task's OWN tabs (excluding borrowed ones — a borrowed tab predates the
+     * task, see {@link Task.borrowedTabs}) that are still live in the browser AND
+     * whose current document canonically equals `url`. Deliberately scoped to THIS
+     * task: it is neither {@link adoptTabShowing} (reclaims OTHER abandoned tasks'
+     * tabs) nor {@link pickReusableTargetWithoutCreate} (borrows a USER tab on Arc)
+     * — the same-task reopen contract only ever touches a tab the task itself owns.
+     * A registered id with no live target (a tab closed out from under us) is
+     * skipped, so a stale mapping never masquerades as a reopenable tab.
+     */
+    findOwnedTabShowing(task, url, liveTargets) {
+        const borrowed = new Set(task.borrowedTabs ?? []);
+        const wanted = canonicalTabUrl(url);
+        const liveById = new Map(liveTargets.filter((t) => t.type === 'page').map((t) => [t.targetId, t]));
+        for (const [shortId, cdpId] of Object.entries(task.tabs)) {
+            if (borrowed.has(shortId))
+                continue;
+            const live = liveById.get(cdpId);
+            if (!live)
+                continue; // registered but gone from the browser — not reopenable
+            if (canonicalTabUrl(live.url) === wanted)
+                return { shortId, targetId: cdpId };
+        }
+        return undefined;
+    }
+    /**
+     * Same-task reopen (PHNX-2399): the requested URL is already live in a tab this
+     * task owns, so RELOAD that same tab and keep its ids rather than opening a
+     * duplicate. Returns the retained short id, or undefined when no owned tab
+     * shows the URL (the caller then falls through to its normal navigate/create
+     * semantics — that no-match split is intentional and preserved).
+     *
+     * A real `Page.reload` is issued; a failed reload THROWS rather than reporting
+     * a phantom refresh (a stale target was already excluded by
+     * {@link findOwnedTabShowing}). The tab is marked current WITHOUT
+     * `Target.activateTarget` — reopen must not steal window focus.
+     */
+    async reopenOwnedTab(conn, task, url) {
+        const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+        const match = this.findOwnedTabShowing(task, url, targetInfos);
+        if (!match)
+            return undefined;
+        const sessionId = await this.getSessionId(conn, match.targetId);
+        // Real reload of the SAME document. If it throws, the ids are left exactly as
+        // they were and the error surfaces — never a success that didn't happen.
+        await conn.cdp.send('Page.reload', {}, sessionId);
+        // Mark current without foreground activation (no Target.activateTarget).
+        task.currentTabId = match.shortId;
+        await this.saveTaskState(task.profile, conn.tasks);
+        return { tabId: match.shortId };
+    }
     async start(profileName, opts = {}) {
+        // A NAMED start is serialized on the task NAME so two concurrent
+        // `start --task <name>` requests can't both pass the existence check and
+        // both create — the second observes the first's task and takes the retry (or
+        // conflict) path. The key is the bare name, NOT `profile:name`: the existence
+        // check (`findTaskByHandle`) is global by name, so two starts of the same
+        // name under DIFFERENT profiles must share one lock or they'd both pass.
+        // Disjoint `namedstart:` namespace, so the nested navigate()/create locks
+        // below never deadlock against it (PHNX-2399). An unnamed start needs no such
+        // guard: it always mints a fresh id.
+        if (opts.taskName) {
+            return this.runExclusive(`namedstart:${opts.taskName}`, () => this.startBody(profileName, opts));
+        }
+        return this.startBody(profileName, opts);
+    }
+    async startBody(profileName, opts) {
         // Consent gate, before anything is resolved or launched. This is the
         // authoritative one: gating only the `browser start` COMMAND left the ~18
         // page verbs that create a browser implicitly (navigate, click, screenshot,
@@ -337,8 +440,13 @@ export class BrowserService {
         const taskId = generateTaskId();
         let taskName;
         if (opts.taskName) {
-            if (this.hasTaskNamed(opts.taskName)) {
-                throw new Error(`Task "${opts.taskName}" already exists. Pick a different --task name or stop the existing one first.`);
+            const existing = this.findTaskByHandle(opts.taskName);
+            if (existing) {
+                // Same-name start RETRY (PHNX-2399): reuse the existing task rather than
+                // erroring — but only when it is genuinely the same task. A different
+                // profile, endpoint, or caller identity is a real conflict and must NOT
+                // silently acquire someone else's task.
+                return this.retryNamedStart(existing, profileName, routed, opts);
             }
             taskName = opts.taskName;
         }
@@ -482,8 +590,12 @@ export class BrowserService {
             });
         }).catch(() => { });
         // If URL provided, reclaim a tab an abandoned task is holding on it, else
-        // create one directly (no about:blank).
+        // create one directly (no about:blank). `firstOpen` records what actually
+        // happened so the owning IPC handler reports it truthfully rather than
+        // assuming a create (PHNX-2399): ADOPTING an abandoned tab is created:false,
+        // opening a fresh target is created:true.
         let tabId;
+        let firstOpen;
         if (opts.url && !conn.electron && conn.browserType !== 'arc') {
             const adopted = opts.fresh ? undefined : await this.adoptTabShowing(conn, opts.url);
             const targetId = adopted ?? (await this.createPageTarget(conn, { url: opts.url })).targetId;
@@ -493,6 +605,7 @@ export class BrowserService {
             this.invalidateTargetCache(conn);
             await this.saveTaskState(effectiveKey, conn.tasks);
             tabId = shortId;
+            firstOpen = { tabId: shortId, created: !adopted, refreshed: false };
         }
         else if (opts.url && (conn.electron || conn.browserType === 'arc')) {
             // Electron and Arc share the reuse-in-place path: neither may open a fresh
@@ -500,9 +613,11 @@ export class BrowserService {
             // so the implicit first navigate attaches to an existing tab — honoring the
             // profile's --target-filter — instead of throwing. This is what makes the
             // documented `navigate --profile arc --url …` first-use workflow attach rather
-            // than refuse on a task-less profile (PHNX-2399 review).
+            // than refuse on a task-less profile (PHNX-2399 review). Carry navigate's
+            // real result — Arc borrow is created:false, not a fabricated create.
             const result = await this.navigate(taskName, opts.url, effectiveKey);
             tabId = result.tabId;
+            firstOpen = { tabId: result.tabId, created: result.created, refreshed: result.refreshed, message: result.message };
         }
         // Domain-skill discovery: when a URL is supplied, look up site-specific
         // operating instructions and pass them back so the calling agent can pick
@@ -522,6 +637,7 @@ export class BrowserService {
             device: routed.device,
             picked: routed.picked,
             skill,
+            firstOpen,
         };
     }
     /**
@@ -812,7 +928,21 @@ export class BrowserService {
     }
     async navigate(taskId, url, profileRef) {
         const { conn, task } = await this.findTask(taskId, profileRef);
+        // Serialize the reopen/create section so two concurrent navigates for one
+        // task don't both miss the "already open?" check and open duplicates.
+        return this.runExclusive(`task:${task.profile}:${task.name}`, () => this.navigateLocked(conn, task, url));
+    }
+    async navigateLocked(conn, task, url) {
         this.maybeUpdateLabelFromUrl(conn, task, url);
+        // Same-task reopen (PHNX-2399): the URL is already live in a tab this task
+        // owns → reload THAT tab in place and keep its id, before the create/reuse
+        // paths below. Chrome and Arc alike; Electron drives one window and never
+        // has a second owned tab to match, so this is a no-op there.
+        const reopened = await this.reopenOwnedTab(conn, task, url);
+        if (reopened) {
+            emit('browser.navigate', { profile: parseConnectionKey(task.profile).profile, task: task.name, url, tabId: reopened.tabId, created: false });
+            return { tabId: reopened.tabId, url, created: false, refreshed: true, message: 'Tab already open—refreshed' };
+        }
         // If we have a current tab, navigate in it (reuse)
         const currentShortId = task.currentTabId;
         if (currentShortId && task.tabs[currentShortId]) {
@@ -821,7 +951,7 @@ export class BrowserService {
             await conn.cdp.send('Page.navigate', { url }, sessionId);
             await this.saveTaskState(task.profile, conn.tasks);
             emit('browser.navigate', { profile: parseConnectionKey(task.profile).profile, task: task.name, url, tabId: currentShortId, created: false });
-            return { tabId: currentShortId, url, created: false };
+            return { tabId: currentShortId, url, created: false, refreshed: false };
         }
         // No current tab - create one
         if (conn.electron) {
@@ -836,7 +966,7 @@ export class BrowserService {
             task.currentTabId = shortId;
             await this.saveTaskState(task.profile, conn.tasks);
             emit('browser.navigate', { profile: parseConnectionKey(task.profile).profile, task: task.name, url, tabId: shortId, created: true });
-            return { tabId: shortId, url, created: true };
+            return { tabId: shortId, url, created: true, refreshed: false };
         }
         // Arc exposes page targets and honors Page.navigate on them; what it cannot
         // survive is Target.createTarget (#2778). createPageTarget below therefore
@@ -885,7 +1015,7 @@ export class BrowserService {
                     tabId: shortId,
                     created: false,
                 });
-                return { tabId: shortId, url, created: false };
+                return { tabId: shortId, url, created: false, refreshed: false };
             }
             // Nothing safe to reuse -- fall through to the actionable refusal rather
             // than taking over a page the user is reading.
@@ -898,20 +1028,31 @@ export class BrowserService {
         this.invalidateTargetCache(conn);
         await this.saveTaskState(task.profile, conn.tasks);
         emit('browser.navigate', { profile: parseConnectionKey(task.profile).profile, task: task.name, url, tabId: shortId, created: true });
-        return { tabId: shortId, url, created: true };
+        return { tabId: shortId, url, created: true, refreshed: false };
     }
     async tabAdd(taskId, url, profileRef) {
         const { conn, task } = await this.findTask(taskId, profileRef);
+        return this.runExclusive(`task:${task.profile}:${task.name}`, () => this.tabAddLocked(conn, task, url));
+    }
+    async tabAddLocked(conn, task, url) {
         if (conn.electron) {
             throw new Error('Electron apps do not support opening additional tabs');
         }
+        // Same-task reopen (PHNX-2399): reopening a URL already live in one of this
+        // task's own tabs refreshes THAT tab rather than opening a duplicate. The
+        // no-match case below stays `tab add`'s intentional create-a-new-tab
+        // semantics — distinct from `navigate`, which reuses the current tab.
+        const reopened = await this.reopenOwnedTab(conn, task, url);
+        if (reopened) {
+            return { tabId: reopened.tabId, url, created: false, refreshed: true, message: 'Tab already open—refreshed' };
+        }
         const result = await this.createPageTarget(conn, { url });
         const shortId = generateShortId();
         task.tabs[shortId] = result.targetId;
         task.currentTabId = shortId; // new tab becomes current
         this.invalidateTargetCache(conn);
         await this.saveTaskState(task.profile, conn.tasks);
-        return { tabId: shortId, url };
+        return { tabId: shortId, url, created: true, refreshed: false };
     }
     async tabFocus(taskId, tabHint) {
         const { conn, task } = await this.findTask(taskId);
@@ -2377,6 +2518,75 @@ export class BrowserService {
         }
         return false;
     }
+    /** The (connection, task) a handle names anywhere, or undefined. */
+    findTaskByHandle(handle) {
+        for (const conn of this.connections.values()) {
+            const task = this.lookupTaskOnConn(conn, handle);
+            if (task)
+                return { conn, task };
+        }
+        return undefined;
+    }
+    /**
+     * Same-name `start --task <name>` retry (PHNX-2399). When a task by that name
+     * already exists this REUSES it — reopening the URL in the same tab (same id,
+     * a real reload, the `Tab already open—refreshed` note) — but only after
+     * proving it is genuinely the same task: same bare profile, same endpoint, and
+     * a matching caller identity. A mismatch on any of those is a real conflict and
+     * throws, so a different caller/profile/endpoint can never silently acquire
+     * another task. Serialized by the `namedstart:` lock in {@link start}.
+     */
+    async retryNamedStart(existing, profileName, routed, opts) {
+        const { conn, task } = existing;
+        const existingKey = conn.key ?? task.profile;
+        // Profile + endpoint must match what this retry asked for.
+        if (!keyBelongsToProfile(existingKey, profileName)) {
+            throw new Error(actionable(`Task "${opts.taskName}" already exists on profile "${parseConnectionKey(existingKey).profile}", not "${profileName}".`, `Next: stop it first (agents browser done --task ${task.name}) or pick a different --task name.`));
+        }
+        const wantEndpoint = parseConnectionKey(routed.key).endpoint;
+        const haveEndpoint = parseConnectionKey(existingKey).endpoint;
+        if (opts.endpointName && wantEndpoint !== haveEndpoint) {
+            throw new Error(actionable(`Task "${opts.taskName}" already exists on endpoint "${haveEndpoint}", not "${wantEndpoint}".`, `Next: stop it first (agents browser done --task ${task.name}) or pick a different --task name.`));
+        }
+        // Caller identity must match. Both identity-less (a human shell) is fine;
+        // otherwise the SAME session/launch must own it — never another caller's.
+        const caller = { sessionId: opts.sessionId, launchId: opts.launchId };
+        const bothAnon = !task.sessionId && !task.launchId && !caller.sessionId && !caller.launchId;
+        if (!bothAnon && !taskMatchesCaller(task, caller)) {
+            throw new Error(actionable(`Task "${opts.taskName}" already exists and belongs to a different caller.`, `Next: stop it first (agents browser done --task ${task.name}) or pick a different --task name.`));
+        }
+        // Genuine same-task retry. When a URL is given, run the real navigate — which
+        // reopens the same owned tab (refreshed) OR reuses the current tab for a
+        // different URL (created:false, refreshed:false) — and carry its ACTUAL
+        // result. With NO URL there is NO page operation: no reload, no counter
+        // change; it is a pure task reuse (created/refreshed both false).
+        let firstOpen;
+        if (opts.url) {
+            const nav = await this.navigate(task.name, opts.url, existingKey);
+            firstOpen = { tabId: nav.tabId, created: nav.created, refreshed: nav.refreshed, message: nav.message };
+        }
+        else {
+            firstOpen = { tabId: task.currentTabId, created: false, refreshed: false };
+        }
+        let skill;
+        if (opts.url && !opts.skipDomainSkill) {
+            const resolved = resolveDomainSkill(opts.url);
+            if (resolved)
+                skill = resolved;
+        }
+        return {
+            task: task.id,
+            name: task.name,
+            tabId: firstOpen.tabId,
+            profile: profileName,
+            key: existingKey,
+            device: routed.device,
+            picked: routed.picked,
+            skill,
+            reused: true,
+            firstOpen,
+        };
+    }
     /** Map key for a task on a connection (tasks are keyed by `name`). */
     taskMapKey(conn, task) {
         for (const [key, t] of conn.tasks) {
@@ -2428,6 +2638,17 @@ export class BrowserService {
             const found = await this.findTask(opts.task, opts.profile);
             return { ...found, created: false };
         }
+        // Serialize identity resolution + implicit creation per caller so two
+        // concurrent first-use requests (e.g. two `navigate <url>` with no --task)
+        // don't both see zero matches and both start a task. The `create:` namespace
+        // is disjoint from the `task:` locks `navigate`/`tabAdd` take, so the nested
+        // `start → navigate` (Arc/Electron) can never wait on a lock this frame holds
+        // (PHNX-2399). Distinct profiles create distinct tasks, so profile is in the
+        // key; identity-less human shells share one `anon` lane.
+        const createKey = `create:${opts.sessionId ?? opts.launchId ?? 'anon'}:${opts.profile ?? 'default'}`;
+        return this.runExclusive(createKey, () => this.resolveOrCreateByIdentity(opts));
+    }
+    async resolveOrCreateByIdentity(opts) {
         // After a daemon restart the connections map is empty while tasks.json still
         // holds live tasks. Rehydrate before identity matching so done/screenshot
         // without --task still find the caller's task.
@@ -2482,6 +2703,10 @@ export class BrowserService {
             created: true,
             picked: started.picked,
             device: started.device,
+            // `start` already opened opts.url on this tab; the handler must not open
+            // it a second time (a duplicate tab for tab-add; a redundant reload for
+            // navigate). Carry the ACTUAL page result so created/refreshed are truthful.
+            firstOpen: started.firstOpen,
         };
     }
     listTasksForCaller(caller) {
@@ -3003,10 +3228,23 @@ export class BrowserService {
         conn.targetCache = undefined;
     }
     async saveTaskState(key, tasks) {
-        const runtimeDir = getProfileRuntimeDir(key);
-        await fs.promises.mkdir(runtimeDir, { recursive: true });
-        const state = Object.fromEntries(tasks);
-        await fs.promises.writeFile(path.join(runtimeDir, 'tasks.json'), JSON.stringify(state, null, 2));
+        // tasks.json holds EVERY task on this connection, so two tasks persisting
+        // concurrently (the per-task locks are disjoint, and `touchTask`/label writes
+        // fire outside any task lock) would interleave writes of the same file and
+        // could truncate or corrupt it. Serialize the whole file write per runtime
+        // key — a `persist:` namespace disjoint from the `task:`/`create:` locks, so a
+        // save issued while holding a task lock never deadlocks (PHNX-2399).
+        await this.runExclusive(`persist:${key}`, async () => {
+            const runtimeDir = getProfileRuntimeDir(key);
+            await fs.promises.mkdir(runtimeDir, { recursive: true });
+            const state = Object.fromEntries(tasks);
+            // Write to a temp sibling then rename, so a reader never sees a half-written
+            // file even if the process dies mid-write (rename is atomic on one fs).
+            const target = path.join(runtimeDir, 'tasks.json');
+            const tmp = `${target}.${process.pid}.tmp`;
+            await fs.promises.writeFile(tmp, JSON.stringify(state, null, 2));
+            await fs.promises.rename(tmp, target);
+        });
     }
     loadTaskState(key) {
         const runtimeDir = getProfileRuntimeDir(key);

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

@@ -241,6 +241,8 @@ export interface TabInfo {
     url: string;
     title: string;
     task: string;
+    /** Whether this is the task's current tab (the one URL-less verbs act on). */
+    current?: boolean;
 }
 export interface ProfileStatus {
     /**
@@ -395,6 +397,31 @@ export interface IPCRequest {
      * not a truthful signal about the CURRENT caller; only the request is.
      */
     fleetRemote?: boolean;
+    /**
+     * SERVER-INTERNAL, never trusted off the wire (PHNX-2399). When a page verb's
+     * `bindTask` implicitly CREATED the task and `start` already opened the URL,
+     * the daemon stamps the resulting {@link PageOpenResult} here so the handler
+     * reports that first open truthfully (adopt → created:false, Arc/Electron
+     * reuse → created:false, fresh tab → created:true) WITHOUT re-executing the
+     * URL. `bindTask` clears any client-supplied value before binding.
+     */
+    firstOpen?: PageOpenResult;
+}
+/**
+ * The outcome of opening/showing a URL on a task tab (PHNX-2399): the ONE shared
+ * shape `navigate` / `tab add` / `start`'s first-open all report, so no surface
+ * has to re-derive created/refreshed from ad-hoc booleans.
+ *   - `created`   — a NEW page target was opened.
+ *   - `refreshed` — an existing OWNED tab showing this URL was reloaded in place.
+ *   - neither     — an existing tab was reused as-is (adopted abandoned tab, or
+ *                   navigated the current tab to a different URL).
+ * `created` and `refreshed` are mutually exclusive.
+ */
+export interface PageOpenResult {
+    tabId?: string;
+    created: boolean;
+    refreshed: boolean;
+    message?: string;
 }
 /** Subset of IPCResponse describing a recording start result. */
 export interface RecordStartFields {
@@ -412,6 +439,26 @@ export interface IPCResponse {
     error?: string;
     task?: string;
     tabId?: string;
+    /**
+     * navigate / tab-add: whether this action OPENED a new page target (true) or
+     * acted on an existing owned tab (false). A same-task reopen — the requested
+     * URL was already live in one of the task's own tabs — reports `created: false`
+     * with `refreshed: true`, so the caller can say "opened" vs "refreshed" honestly.
+     */
+    created?: boolean;
+    /**
+     * navigate / tab-add: the requested URL was already open in an owned tab, so
+     * that SAME tab was reloaded in place (same tabId) rather than a duplicate
+     * opened. Mutually exclusive with `created: true`.
+     */
+    refreshed?: boolean;
+    /**
+     * start: a same-name retry matched an existing task and REUSED it (task-level,
+     * distinct from the page-level `created`/`refreshed`). A no-URL retry is
+     * `reused: true` with `refreshed: undefined` — it did no page operation, so it
+     * must NOT read as a refresh (PHNX-2399).
+     */
+    reused?: boolean;
     windowTargetId?: string;
     tabs?: TabInfo[];
     profiles?: ProfileStatus[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.80",
+  "version": "1.22.81",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",