@phnx-labs/agents-cli 1.22.51 → 1.22.52

package/dist/commands/share.js

@@ -22,6 +22,8 @@ export function formatSharePublishResult(result, json = false) {
     if (json)
         return JSON.stringify(result, null, 2);
     const lines = [chalk.green(result.url)];
+    if (result.slug)
+        lines.push(chalk.dim(`  slug: ${result.slug}`));
     if (result.label) {
         const hint = result.labelSource === 'derived' ? chalk.dim(' (derived — pass --label to set one)') : '';
         lines.push(chalk.dim(`  "${result.label}"`) + hint);
@@ -436,7 +438,7 @@ export function registerShareCommands(artifactsCmd) {
         .command('share')
         .description('Publish an HTML file to a shareable link — managed if signed in, otherwise your Cloudflare R2.')
         .argument('[file]', 'file to publish (HTML or any static asset)')
-        .option('--slug <slug>', 'custom URL slug under your namespace (default: <feature>-<16hex>)')
+        .option('--slug <slug>', 'URL slug override (default: stable slug of the artifact title, then filename)')
         .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config; ignored on the managed endpoint)')
         .option('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
         .addOption(new Option('--visibility <level>', 'public | unlisted | me | org (default public). unlisted is a capability URL; me/org require a Phoenix session and are hidden from the gallery')
@@ -497,17 +499,17 @@ export function registerShareCommands(artifactsCmd) {
       # Hide from the public gallery (direct URL still works, noindex) and expire sooner
       agents artifacts share ./out/report.html --visibility unlisted --expire 12h
 
-      # Permanent public page (opt out of the default 30d expiry)
-      agents artifacts share ./out/landing.html --slug landing --expire never
+      # Permanent public page (the slug is derived from its title)
+      agents artifacts share ./out/landing.html --expire never
 
-      # Custom slug, expiring in 7 days
+      # Optional slug override
       agents artifacts share ./out/report.html --slug q3-report --expire 7d
 
       # Human title + structured metadata, shown in the gallery and share list
       agents artifacts share ./out/plan.html --label "Q3 fleet plan" --meta kind=plan --meta ticket=RUSH-2683
 
-      # Republish without keeping the previous version as a revision
-      agents artifacts share ./out/plan.html --slug q3-report --no-revision
+      # Republish the same title to the same URL without retaining a revision
+      agents artifacts share ./out/plan.html --no-revision
 ${SHARE_DELETE_EXAMPLES}
       # One-time setup (or join an existing endpoint)
       agents artifacts setup
@@ -519,8 +521,10 @@ ${SHARE_DELETE_EXAMPLES}
         notes: `
   Signed-in users publish to the managed endpoint (share.agents-cli.sh/<handle>/…)
   with the Phoenix session — no Cloudflare account, bucket, or write token. The
-  handle is the local-part of the signed-in email; the default slug is
-  <readable>-<16hex>. Without a session, the existing BYO Cloudflare path still
+  handle is the local-part of the signed-in email. The default slug is derived
+  deterministically from the HTML <title> or Markdown frontmatter title, then
+  the filename, so republishing the same title updates the same URL. --slug is
+  an optional override. Without a session, the existing BYO Cloudflare path still
   applies (setup / join). HTML is stored as one object: local images are inlined
   and Chrome-saved file:// TOC links become in-page hashes.
 

package/dist/commands/status.js

@@ -75,6 +75,11 @@ export function registerStatusCommand(syncCmd) {
         else {
             console.log(`  ${'.system repo'.padEnd(28)} ${chalk.green('up to date')}`);
         }
+        // A non-git / partial ~/.agents is its own drift state, not a per-agent
+        // "N missing" — surface it distinctly so the real problem isn't buried (PHNX-3301).
+        if (status.user.notGitRepo) {
+            console.log(`  ${'~/.agents (user repo)'.padEnd(28)} ${chalk.yellow('not a git repo — will adopt on next `agents repo sync user`')}`);
+        }
         if (status.agents.length === 0) {
             console.log(chalk.gray('  (no installed agent versions)'));
         }

package/dist/commands/sync.js

@@ -44,7 +44,7 @@ import { formatKeptProjectResources } from '../lib/project-resources.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 import { addHostOption } from '../lib/hosts/option.js';
-import { syncRepoGit } from '../lib/git.js';
+import { syncRepoGit, adoptUserRepoIfNeeded, recordUserRepoRemote, resolveUserRepoRemoteUrl } from '../lib/git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
 import { registerStatusCommand } from './status.js';
 /** Emit one JSON object to stdout for `--json` callers / fleet fan-out. */
@@ -206,6 +206,37 @@ async function runRepoGitSync(repo, quiet, outLog, errLog, json = false) {
     }
     if (!quiet && !json)
         outLog(chalk.bold(`Syncing ${repo} repo…`) + chalk.gray(` (${target.dir})`));
+    // Self-heal a non-git / partial user checkout in place before the git sync
+    // (PHNX-3301) — otherwise syncRepoGit hard-fails with "Not a git repo" and the
+    // only fix is a destructive re-clone. Only the user repo adopts: system is
+    // cloned by setup, extras by `repo add`.
+    if (repo === 'user') {
+        const adopted = await adoptUserRepoIfNeeded(target.dir);
+        if (adopted && !adopted.success) {
+            const hint = adopted.needsUrl
+                ? ' — git-back it: agents repo pull user <git-url>'
+                : '';
+            if (json) {
+                emitJson({ ok: false, mode: 'repo-git', repo, error: `${adopted.error}${hint}` });
+            }
+            else {
+                errLog(chalk.red(`sync ${repo} failed: ${adopted.error}`));
+                if (adopted.needsUrl)
+                    errLog(chalk.gray('  git-back it: agents repo pull user <git-url>'));
+            }
+            process.exitCode = 1;
+            return;
+        }
+        if (adopted?.success && !quiet && !json) {
+            outLog(chalk.green(`  adopted ${repo} in place → ${adopted.commit} (${adopted.materialized} file(s) materialized${adopted.reconciledAgentsYaml ? ', agents.yaml reconciled' : ''})`));
+            if (adopted.localEdits.length > 0) {
+                outLog(chalk.yellow(`  kept ${adopted.localEdits.length} local edit(s): ${adopted.localEdits.slice(0, 5).join(', ')}${adopted.localEdits.length > 5 ? ', …' : ''}`));
+            }
+            if (adopted.agentsYamlBackup) {
+                outLog(chalk.gray(`  saved the previous agents.yaml to ${adopted.agentsYamlBackup}`));
+            }
+        }
+    }
     const result = await syncRepoGit(target.dir, { push: target.push });
     if (!result.success) {
         if (json) {
@@ -217,6 +248,14 @@ async function runRepoGitSync(repo, quiet, outLog, errLog, json = false) {
         process.exitCode = 1;
         return;
     }
+    // Record the resolved remote so a future partial box (lost .git) can adopt in
+    // place without the operator re-typing the URL (PHNX-3301). Before the --json
+    // early-return so the record is refreshed on every healthy sync, JSON or not.
+    if (repo === 'user') {
+        const u = resolveUserRepoRemoteUrl(target.dir);
+        if (u)
+            recordUserRepoRemote(target.dir, u);
+    }
     if (json) {
         emitJson({
             ok: true,
@@ -290,9 +329,26 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         const target = resolveRepoGitTarget(repo);
         if (!target)
             continue;
+        // Adopt a non-git / partial user checkout in place before pulling (PHNX-3301).
+        if (repo === 'user') {
+            const adopted = await adoptUserRepoIfNeeded(target.dir);
+            if (adopted?.success) {
+                outLog(chalk.gray(`  adopted user in place → ${adopted.commit} (${adopted.materialized} file(s) materialized)`));
+            }
+            else if (adopted && !adopted.success) {
+                outLog(chalk.yellow(`  ! user: ${adopted.error}${adopted.needsUrl ? ' — agents repo pull user <git-url>' : ''}`));
+                continue;
+            }
+        }
         const res = await syncRepoGit(target.dir, { push: false });
-        if (res.success)
+        if (res.success) {
             outLog(chalk.gray(`  pulled ${repo} → ${res.commit}`));
+            if (repo === 'user') {
+                const u = resolveUserRepoRemoteUrl(target.dir);
+                if (u)
+                    recordUserRepoRemote(target.dir, u);
+            }
+        }
         else
             outLog(chalk.yellow(`  ! ${repo}: ${(res.error ?? 'pull failed').split('\n')[0]}`));
     }

package/dist/commands/tmux.d.ts

@@ -17,9 +17,16 @@
  *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
  *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
  *   agents tmux info <name>    [--json]
- *   agents tmux kill <name>
+ *   agents tmux kill [name]    no name → picker with live pane preview
  *   agents tmux kill-all       [--yes]
  */
 import type { Command } from 'commander';
+import { type ListedSession } from '../lib/tmux/index.js';
 /** Register the `agents tmux` command tree. */
 export declare function registerTmuxCommands(program: Command): void;
+/** Last useful line of a pane capture — what `tmux ls` shows so a name isn't a black box. */
+export declare function tmuxScreenSnippet(raw: string, max?: number): string;
+/** Last non-empty lines of a pane capture, for the kill-picker preview. */
+export declare function tmuxScreenPreview(raw: string, maxLines?: number): string;
+export declare function formatTmuxKillLabel(s: ListedSession, snippet: string, nowMs?: number): string;
+export declare function formatTmuxKillPreview(s: ListedSession, raw: string, nowMs?: number): string;

package/dist/commands/tmux.js

@@ -17,14 +17,15 @@
  *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
  *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
  *   agents tmux info <name>    [--json]
- *   agents tmux kill <name>
+ *   agents tmux kill [name]    no name → picker with live pane preview
  *   agents tmux kill-all       [--yes]
  */
 import chalk from 'chalk';
-import { truncate } from '../lib/format.js';
+import { truncate, isInteractiveTerminal, isPromptCancelled } from '../lib/format.js';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
-import { assertTmuxAvailable, attachTmux, capturePane, createSession, ensureSessionHookRepaired, getDefaultSocketPath, getTmuxVersion, hasSession, isTmuxInstalled, isTmuxVersionSupported, killAll, killSession, listSessions, MIN_TMUX_VERSION, readSessionMeta, sendKeys, splitPane, TmuxCommandError, TmuxSessionError, TmuxUnavailableError, } from '../lib/tmux/index.js';
+import { multiItemPicker } from '../lib/picker.js';
+import { assertTmuxAvailable, attachTmux, capturePane, createSession, ensureSessionHookRepaired, getDefaultSocketPath, getTmuxVersion, hasSession, isTmuxInstalled, isTmuxVersionSupported, killAll, killSession, teardownIfAgentExited, listSessions, MIN_TMUX_VERSION, readSessionMeta, sendKeys, splitPane, TmuxCommandError, TmuxSessionError, TmuxUnavailableError, } from '../lib/tmux/index.js';
 /** Register the `agents tmux` command tree. */
 export function registerTmuxCommands(program) {
     const tmux = program
@@ -47,8 +48,9 @@ export function registerTmuxCommands(program) {
       # Send a slash command from a script
       agents tmux send claude-debug "/clear"
 
-      # Clean up
+      # Clean up one by name, or pick from a list that shows each pane's last lines
       agents tmux kill claude-debug
+      agents tmux kill
     `,
         notes: `
       Storage:
@@ -145,7 +147,7 @@ export function registerTmuxCommands(program) {
     // ─── attach ─────────────────────────────────────────────────────────────────
     const attachCmd = tmux
         .command('attach <name>')
-        .description('Attach to a running session. Replaces this shell with the tmux client until you detach (Ctrl-b d).')
+        .description('Attach to a running session. Replaces this shell with the tmux client until you detach (Ctrl-b d) or the agent exits (session is then torn down).')
         .option('--socket <path>', 'Use a custom socket (default: shared server)');
     attachCmd.action(async (name, opts) => {
         await guardTmux(async () => {
@@ -163,6 +165,11 @@ export function registerTmuxCommands(program) {
             // deleted; attach-time repair is what closes the gap now (RUSH-2435).
             await ensureSessionHookRepaired(name, socket);
             const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${name}`] });
+            // The v6 pane-died hook only detach-clients when a client is attached
+            // (so runInTmux can read the exit status). Attach verbs must kill the
+            // husk themselves — otherwise `tmux ls` still lists the session after
+            // the agent exits (PHNX-3293).
+            await teardownIfAgentExited(name, socket);
             process.exit(code);
         });
     });
@@ -170,25 +177,34 @@ export function registerTmuxCommands(program) {
     const listCmd = tmux
         .command('list')
         .alias('ls')
-        .description('List live tmux sessions on the shared server. Prunes stale meta files as a side effect.')
+        .description('List live tmux sessions on the shared server (name, age, last screen line). Prunes stale meta files as a side effect.')
         .option('--socket <path>', 'Use a custom socket (default: shared server)')
         .option('--json', 'Output as JSON');
     listCmd.action(async (opts) => {
         await guardTmux(async () => {
             const sessions = await listSessions({ socket: opts.socket });
-            if (opts.json) {
-                console.log(JSON.stringify(sessions));
-                return;
-            }
             if (sessions.length === 0) {
+                if (opts.json) {
+                    console.log('[]');
+                    return;
+                }
                 console.log(chalk.gray('No tmux sessions.'));
                 return;
             }
+            const screens = await captureScreens(sessions, opts.socket);
+            if (opts.json) {
+                console.log(JSON.stringify(sessions.map((s) => ({
+                    ...s,
+                    preview: tmuxScreenSnippet(screens.get(s.name) ?? ''),
+                }))));
+                return;
+            }
             for (const s of sessions) {
                 const age = formatAge(Date.now() / 1000 - s.createdAtTmux);
-                const cmd = s.meta?.cmd ? chalk.gray(`  ${truncate(s.meta.cmd, 60)}`) : '';
                 const attached = s.attached ? chalk.green(' [attached]') : '';
-                console.log(`  ${chalk.bold(s.name)}  ${s.windows}w  ${age}${attached}${cmd}`);
+                const snippet = tmuxScreenSnippet(screens.get(s.name) ?? '');
+                const preview = snippet ? chalk.gray(`  ${snippet}`) : '';
+                console.log(`  ${chalk.bold(s.name)}  ${s.windows}w  ${age}${attached}${preview}`);
             }
         });
     });
@@ -329,15 +345,35 @@ export function registerTmuxCommands(program) {
     });
     // ─── kill ───────────────────────────────────────────────────────────────────
     const killCmd = tmux
-        .command('kill <name>')
-        .description('Kill one tmux session. Idempotent — exits 0 even if the session was already gone.')
+        .command('kill [name]')
+        .description('Kill one tmux session, or pick from a list that shows each pane\'s last screen. Idempotent.')
         .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    setHelpSections(killCmd, {
+        examples: `
+      # Kill by name
+      agents tmux kill ag-claude-04a1307c
+
+      # Pick from live panes — preview shows the last lines on screen
+      # (trust-folder stall, weekly-limit dialog, real work)
+      agents tmux kill
+    `,
+        notes: `
+      With no name, the picker captures each pane so you can tell a leaked
+      first-run dialog from an agent that is still working. Space multi-selects;
+      enter kills the checked rows (or the highlighted one if none are checked).
+      Ctrl-b d still keeps a live session; exiting the agent tears it down.
+    `,
+    });
     killCmd.action(async (name, opts) => {
         await guardTmux(async () => {
-            const killed = await killSession(name, opts.socket);
-            if (!killed) {
-                console.log(chalk.gray(`No session "${name}" — nothing to do.`));
+            if (name) {
+                const killed = await killSession(name, opts.socket);
+                if (!killed) {
+                    console.log(chalk.gray(`No session "${name}" — nothing to do.`));
+                }
+                return;
             }
+            await pickAndKillSessions(opts.socket);
         });
     });
     // ─── kill-all ───────────────────────────────────────────────────────────────
@@ -399,6 +435,120 @@ function collectLabel(value, acc) {
     acc[value.slice(0, eq)] = value.slice(eq + 1);
     return acc;
 }
+/** Last useful line of a pane capture — what `tmux ls` shows so a name isn't a black box. */
+export function tmuxScreenSnippet(raw, max = 72) {
+    const lines = raw
+        .split('\n')
+        .map((l) => l.replace(/\s+/g, ' ').trim())
+        .filter((l) => l.length > 0 && !/^[─═│┃┌┐└┘╰╯╭╮\s|-]+$/.test(l) && !/enter to confirm|esc to cancel|tab:next/i.test(l));
+    const tail = lines.slice(-8);
+    const preferred = [...tail].reverse().find((l) => /[?❯]|trust this folder|weekly limit|needs.you|waiting/i.test(l));
+    return truncate(preferred ?? tail[tail.length - 1] ?? '', max);
+}
+/** Last non-empty lines of a pane capture, for the kill-picker preview. */
+export function tmuxScreenPreview(raw, maxLines = 16) {
+    return raw
+        .split('\n')
+        .map((l) => l.replace(/\s+$/, ''))
+        .filter((l) => l.length > 0)
+        .slice(-maxLines)
+        .join('\n');
+}
+export function formatTmuxKillLabel(s, snippet, nowMs = Date.now()) {
+    const age = formatAge(nowMs / 1000 - s.createdAtTmux);
+    const agent = s.meta?.labels?.agent;
+    const bits = [s.name, age];
+    if (agent)
+        bits.push(agent);
+    if (snippet)
+        bits.push(snippet);
+    return bits.join('  ');
+}
+export function formatTmuxKillPreview(s, raw, nowMs = Date.now()) {
+    const age = formatAge(nowMs / 1000 - s.createdAtTmux);
+    const agent = s.meta?.labels?.agent;
+    const header = [
+        chalk.bold(s.name),
+        agent ? chalk.cyan(agent) : '',
+        chalk.gray(age),
+        s.attached ? chalk.green('attached') : chalk.gray('detached'),
+    ].filter(Boolean).join('  ');
+    const meta = [
+        s.meta?.cwd ? `cwd  ${s.meta.cwd}` : '',
+        s.meta?.cmd ? `cmd  ${truncate(s.meta.cmd, 80)}` : '',
+    ].filter(Boolean).join('\n');
+    const body = tmuxScreenPreview(raw) || chalk.gray('(empty pane)');
+    return [header, meta, '', chalk.gray('── last screen ──'), body].filter((line) => line !== '').join('\n');
+}
+async function captureScreens(sessions, socket) {
+    const rows = await Promise.all(sessions.map(async (s) => {
+        try {
+            const raw = await capturePane({ name: s.name, socket, lines: 40 });
+            return [s.name, raw];
+        }
+        catch {
+            return [s.name, ''];
+        }
+    }));
+    return new Map(rows);
+}
+async function pickAndKillSessions(socket) {
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('Pass a session name, or run from a TTY to pick from a list with pane previews.'));
+        console.error(chalk.gray('  agents tmux ls          # names + last screen line'));
+        console.error(chalk.gray('  agents tmux kill <name>'));
+        process.exitCode = 1;
+        return;
+    }
+    const sessions = await listSessions({ socket });
+    if (sessions.length === 0) {
+        console.log(chalk.gray('No tmux sessions.'));
+        return;
+    }
+    const screens = await captureScreens(sessions, socket);
+    let chosen;
+    try {
+        chosen = await multiItemPicker({
+            message: 'Kill which tmux sessions?',
+            items: sessions,
+            filter: (q) => {
+                const needle = q.trim().toLowerCase();
+                if (!needle)
+                    return sessions;
+                return sessions.filter((s) => {
+                    const hay = [
+                        s.name,
+                        s.meta?.labels?.agent,
+                        s.meta?.cwd,
+                        s.meta?.cmd,
+                        screens.get(s.name),
+                    ].join(' ').toLowerCase();
+                    return hay.includes(needle);
+                });
+            },
+            labelFor: (s) => formatTmuxKillLabel(s, tmuxScreenSnippet(screens.get(s.name) ?? '')),
+            keyFor: (s) => s.name,
+            buildPreview: (s) => formatTmuxKillPreview(s, screens.get(s.name) ?? ''),
+            pageSize: 12,
+            emptyMessage: 'No sessions match.',
+            enterHint: 'kill',
+        });
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return;
+        throw err;
+    }
+    if (!chosen || chosen.length === 0)
+        return;
+    for (const s of chosen) {
+        const killed = await killSession(s.name, socket);
+        if (killed)
+            console.log(chalk.gray(`Killed ${s.name}`));
+        else
+            console.log(chalk.gray(`No session "${s.name}" — already gone.`));
+    }
+}
 function formatAge(secs) {
     if (secs < 60)
         return `${Math.max(0, Math.floor(secs))}s`;

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

@@ -12,6 +12,50 @@ export declare function getSocketPath(): string;
 /** Is the daemon reachable? A real connect probe on every platform — a socket
  * file existing on disk is not proof a daemon is listening on it. */
 export declare function isDaemonReachable(): Promise<boolean>;
+/**
+ * Wait until the browser daemon is genuinely reachable, or throw.
+ *
+ * Re-probes across the whole window rather than latching on the first accept, so
+ * it survives an IPC-server restart that happens mid-wait (PHNX-3289): a restart
+ * just resets the consecutive-accept counter, and the loop keeps going until the
+ * daemon is *stably* up or the deadline passes. Bounded and fail-loud — a daemon
+ * that never comes up throws a message naming the endpoint and the budget, never
+ * a silent hang.
+ */
+export declare function waitForSocket(_socketPath: string, timeoutMs?: number): Promise<void>;
+/** Outcome of {@link resetBrowserDaemon} — what the wedge-recovery actually did. */
+export interface BrowserDaemonResetResult {
+    /** The daemon was reachable before the reset and a stop was issued. */
+    wasRunning: boolean;
+    /** A leftover `browser.sock` file was unlinked (POSIX only). */
+    socketCleared: boolean;
+}
+/**
+ * Clear a wedged browser daemon so a subsequent `start` comes up clean
+ * (PHNX-3289). Stops the shared daemon (the same `stopDaemon` path
+ * `reconcileDaemonVersion` uses for a stale-version restart), waits for the IPC
+ * endpoint to stop accepting, then unlinks any stale `browser.sock` a
+ * hard-crashed daemon left behind — the file a fresh `start` would otherwise
+ * `unlink` blindly, racing whatever still holds it.
+ *
+ * Fails loud: if the endpoint is *still* reachable after the quiesce window, a
+ * live server is holding it and clearing the socket under it would orphan two
+ * servers on one path, so we throw rather than pretend the reset worked. The
+ * daemon auto-restarts on the next browser command.
+ */
+export declare function resetBrowserDaemon(): Promise<BrowserDaemonResetResult>;
+/**
+ * Remove a leftover browser socket FILE, but only when nothing is listening on
+ * it — re-probing liveness IMMEDIATELY before the unlink to close the TOCTOU
+ * window (PHNX-3289 review). Between {@link resetBrowserDaemon}'s quiesce loop
+ * deciding the endpoint was unreachable and this unlink, a concurrent
+ * `browser start` could bind a NEW listener on the same path; an unconditional
+ * unlink would then delete a LIVE daemon's socket — the exact two-servers orphan
+ * this function exists to prevent. A listener seen here means the wedge is already
+ * resolved (a fresh daemon owns the path), so its socket is left intact. Returns
+ * true only when a genuinely dead file was removed.
+ */
+export declare function clearDeadSocketFile(endpoint: string, socketPath: string): Promise<boolean>;
 /**
  * One long-lived connection to the existing browser daemon. Requests are
  * serialized so the daemon's newline-delimited responses always map to the

package/dist/lib/browser/ipc.js

@@ -69,6 +69,29 @@ const SOCKET_NAME = 'browser.sock';
  * coming near the grace window.
  */
 const IPC_CLOSE_TIMEOUT_MS = 1_500;
+/**
+ * How long {@link waitForSocket} waits for the browser daemon to come up before
+ * failing loud (PHNX-3289).
+ *
+ * The old flat 6s ceiling was the wedge: the shared daemon's browser IPC server
+ * restarts (version reconcile, supervisor restart, a hard-crashed predecessor's
+ * successor claiming the socket), and a client that started its wait *during*
+ * one of those restart windows could burn the whole 6s and throw
+ * `Timeout waiting for browser daemon socket` on an otherwise-healthy daemon. A
+ * browser start/navigate then failed intermittently and self-healed on the next
+ * try. 15s comfortably spans a restart; the stable-probe requirement below is
+ * what keeps a socket that "appears and is immediately destroyed" (#556) from
+ * being mistaken for a ready daemon.
+ */
+const SOCKET_WAIT_TIMEOUT_MS = 15_000;
+/**
+ * Consecutive successful probes required before {@link waitForSocket} declares
+ * the daemon ready. A single accept can land in the sliver between a restarting
+ * server binding and tearing back down; requiring two accepts ~100ms apart means
+ * we only return once the daemon is *staying* up, so the caller's real request
+ * doesn't race a restart it happened to probe mid-flight.
+ */
+const SOCKET_WAIT_STABLE_PROBES = 2;
 export class BrowserDaemonNotRunningError extends Error {
     constructor() {
         super(formatBrowserDaemonNotRunningError());
@@ -78,8 +101,8 @@ export class BrowserDaemonNotRunningError extends Error {
 export function formatBrowserDaemonNotRunningError() {
     return [
         'Browser daemon not running.',
-        'Start it with: agents browser start (auto-picks an installed browser)',
-        'Or pin a profile: agents browser start --profile <name>',
+        'Start it with: agents browser start (uses this machine\'s configured default browser)',
+        'Pick / pin a profile: agents browser use <name>  (or: agents browser start --profile <name>)',
         'List profiles: agents browser profiles list',
     ].join('\n');
 }
@@ -117,15 +140,104 @@ function probeDaemon(endpoint, timeoutMs = 500) {
 export async function isDaemonReachable() {
     return probeDaemon(getIpcEndpoint());
 }
-async function waitForSocket(_socketPath, timeoutMs) {
+/**
+ * Wait until the browser daemon is genuinely reachable, or throw.
+ *
+ * Re-probes across the whole window rather than latching on the first accept, so
+ * it survives an IPC-server restart that happens mid-wait (PHNX-3289): a restart
+ * just resets the consecutive-accept counter, and the loop keeps going until the
+ * daemon is *stably* up or the deadline passes. Bounded and fail-loud — a daemon
+ * that never comes up throws a message naming the endpoint and the budget, never
+ * a silent hang.
+ */
+export async function waitForSocket(_socketPath, timeoutMs = SOCKET_WAIT_TIMEOUT_MS) {
     const endpoint = getIpcEndpoint();
     const deadline = Date.now() + timeoutMs;
+    let consecutive = 0;
     while (Date.now() < deadline) {
-        if (await probeDaemon(endpoint))
-            return;
+        if (await probeDaemon(endpoint)) {
+            consecutive += 1;
+            if (consecutive >= SOCKET_WAIT_STABLE_PROBES)
+                return;
+        }
+        else {
+            // A dropped probe means a restart (or the daemon isn't up yet) — start the
+            // stability count over rather than counting accepts from before the gap.
+            consecutive = 0;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`Timeout waiting for browser daemon socket after ${Math.round(timeoutMs / 1000)}s (${endpoint}).`);
+}
+/** How long {@link resetBrowserDaemon} waits for the endpoint to go quiet after
+ * signalling a stop before it clears the socket and re-checks. Bounded so the
+ * command fails loud instead of hanging on a daemon that will not die. */
+const DAEMON_RESET_QUIESCE_MS = 5_000;
+/**
+ * Clear a wedged browser daemon so a subsequent `start` comes up clean
+ * (PHNX-3289). Stops the shared daemon (the same `stopDaemon` path
+ * `reconcileDaemonVersion` uses for a stale-version restart), waits for the IPC
+ * endpoint to stop accepting, then unlinks any stale `browser.sock` a
+ * hard-crashed daemon left behind — the file a fresh `start` would otherwise
+ * `unlink` blindly, racing whatever still holds it.
+ *
+ * Fails loud: if the endpoint is *still* reachable after the quiesce window, a
+ * live server is holding it and clearing the socket under it would orphan two
+ * servers on one path, so we throw rather than pretend the reset worked. The
+ * daemon auto-restarts on the next browser command.
+ */
+export async function resetBrowserDaemon() {
+    const endpoint = getIpcEndpoint();
+    const wasRunning = await probeDaemon(endpoint);
+    stopDaemon();
+    // Wait for the listener to actually release the endpoint. We must decide
+    // reachability BEFORE touching the socket file: unlinking a path out from
+    // under a live server makes new connects ENOENT (so it would *look* cleared)
+    // while the server keeps running — the two-servers orphan the eviction
+    // protocol exists to prevent. So a still-reachable endpoint fails loud here,
+    // and only a genuinely dead one gets its stale file removed below.
+    const deadline = Date.now() + DAEMON_RESET_QUIESCE_MS;
+    let reachable = wasRunning;
+    while (reachable && Date.now() < deadline) {
         await new Promise((resolve) => setTimeout(resolve, 100));
+        reachable = await probeDaemon(endpoint);
+    }
+    if (reachable) {
+        throw new Error(actionable('Browser daemon is still reachable after stop — a live server is holding the socket.', `Endpoint: ${endpoint}`, 'Next: agents daemon status   (find and stop the process holding it)'));
+    }
+    // Nothing is listening now — clear the leftover socket file a hard-crashed
+    // daemon left behind, so the next `start` binds clean instead of unlinking it
+    // blindly. (Named pipes vanish with their owning process, so Windows has no
+    // stale file to clear.)
+    const socketCleared = IS_WINDOWS ? false : await clearDeadSocketFile(endpoint, getSocketPath());
+    return { wasRunning, socketCleared };
+}
+/**
+ * Remove a leftover browser socket FILE, but only when nothing is listening on
+ * it — re-probing liveness IMMEDIATELY before the unlink to close the TOCTOU
+ * window (PHNX-3289 review). Between {@link resetBrowserDaemon}'s quiesce loop
+ * deciding the endpoint was unreachable and this unlink, a concurrent
+ * `browser start` could bind a NEW listener on the same path; an unconditional
+ * unlink would then delete a LIVE daemon's socket — the exact two-servers orphan
+ * this function exists to prevent. A listener seen here means the wedge is already
+ * resolved (a fresh daemon owns the path), so its socket is left intact. Returns
+ * true only when a genuinely dead file was removed.
+ */
+export async function clearDeadSocketFile(endpoint, socketPath) {
+    if (!fs.existsSync(socketPath))
+        return false;
+    // A listener bound again since the quiesce loop → do not touch its socket.
+    if (await probeDaemon(endpoint))
+        return false;
+    try {
+        fs.unlinkSync(socketPath);
+        return true;
+    }
+    catch {
+        // Raced with a fresh start that already claimed it — the goal (no stale
+        // socket) still holds, so report cleared only when it is genuinely gone.
+        return !fs.existsSync(socketPath);
     }
-    throw new Error('Timeout waiting for browser daemon socket');
 }
 /**
  * One long-lived connection to the existing browser daemon. Requests are
@@ -865,7 +977,7 @@ async function reconcileDaemonVersion(socketPath) {
     stopDaemon();
     startDaemon();
     if (!(await isDaemonReachable())) {
-        await waitForSocket(socketPath, 6000);
+        await waitForSocket(socketPath);
     }
     await new Promise((r) => setTimeout(r, 300));
 }
@@ -968,7 +1080,7 @@ async function prepareIPC(action, opts) {
         }
         startDaemon();
         if (!(await isDaemonReachable())) {
-            await waitForSocket(socketPath, 6000);
+            await waitForSocket(socketPath);
         }
         if (!(await isDaemonReachable())) {
             throw new Error(actionable('Failed to start browser daemon.', `Log: ${getDaemonLogPath()}`, 'Next: agents doctor   (checks for a second agents-cli install)'));