@phnx-labs/agents-cli 1.22.50 → 1.22.52

package/dist/commands/setup-preferences.js

@@ -80,11 +80,19 @@ export async function maybePickInteractiveHost() {
  * Offer to pin this machine's default browser profile to a chosen browser.
  * Only asked when there is nothing to preserve: no configured device default
  * AND no existing `default` profile (an existing profile is the user's earlier
- * choice — never re-pinned behind their back). Returns true when a profile was
- * created and set as the device default. Silent no-op non-TTY.
+ * choice — never re-pinned behind their back). The list is the installed
+ * Chromium-family browsers plus a "None — this box uses the fleet hub" opt-out.
+ *
+ * This is the ONE place a default browser is chosen for a machine (PHNX-3296):
+ * a bare `agents browser start` no longer auto-detects and mints one, so picking
+ * here (or `agents browser use` / `agents setup browser` later) is how a box
+ * gets a local default at all. Picking "None" leaves it to the fleet hub
+ * (`browser.device`). Returns true when a profile was created and set as the
+ * device default. Silent no-op non-TTY — a headless box relies on the hub.
  */
-export async function maybePickBrowserProfile() {
-    if (!isInteractiveTerminal())
+export async function maybePickBrowserProfile(deps = {}) {
+    const interactive = deps.interactive ?? isInteractiveTerminal();
+    if (!interactive)
         return false;
     if (getConfiguredDefaultProfileName())
         return false;
@@ -93,15 +101,24 @@ export async function maybePickBrowserProfile() {
     const installed = listInstalledBrowsers();
     if (installed.length === 0)
         return false;
-    const { select } = await import('@inquirer/prompts');
-    const picked = await select({
+    const config = {
         message: 'Which browser should agents drive on THIS machine?',
         default: defaultBrowserChoice(installed) ?? SKIP,
         choices: [
             ...installed.map((b) => ({ name: `${b.browserType}  ${chalk.dim(b.binary)}`, value: b.browserType })),
-            { name: `Skip ${chalk.dim('— auto-detect on first use (priority order)')}`, value: SKIP },
+            { name: `None ${chalk.dim('— this box uses the fleet hub (agents config set browser.device <host>)')}`, value: SKIP },
         ],
-    });
+    };
+    // The prompt is the only non-testable boundary here, so it is injectable —
+    // everything after (createProfile, setConfigValue) runs for real.
+    let picked;
+    if (deps.select) {
+        picked = await deps.select(config);
+    }
+    else {
+        const { select } = await import('@inquirer/prompts');
+        picked = await select(config);
+    }
     if (picked === SKIP)
         return false;
     const chosen = installed.find((b) => b.browserType === picked) ?? installed[0];

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/commands/traces.js

@@ -1,7 +1,6 @@
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
-import { syncTraces } from '../lib/traces/sync.js';
-import { readSyncLedger } from '../lib/traces/sync.js';
+import { readSyncLedger, syncTraces } from '../lib/traces/sync.js';
 import { managedTracesBaseUrl, resolveTracesBackend } from '../lib/traces/backend.js';
 import { showUrl } from '../lib/open-url.js';
 import { DEFAULT_CF_BUNDLE, readCloudflareCreds } from '../lib/share/config.js';
@@ -93,7 +92,18 @@ async function handleSync(opts) {
         parts.push(chalk.dim(`${result.skipped} skipped`));
     }
     if (result.errors > 0) {
-        parts.push(chalk.yellow(`${result.errors} errors`));
+        // Distinguish expected history (transcripts cleaned off disk) from genuine
+        // failures that will be retried, so the operator knows which need attention.
+        const detail = [];
+        if (result.transcriptUnavailable > 0) {
+            detail.push(`${result.transcriptUnavailable} transcripts no longer on disk`);
+        }
+        const retryable = result.parseFailed + result.uploadFailed;
+        if (retryable > 0) {
+            detail.push(`${retryable} parse/upload failures — will retry`);
+        }
+        parts.push(chalk.yellow(`${result.errors} errors`) +
+            (detail.length ? chalk.dim(` (${detail.join(' · ')})`) : ''));
     }
     if (parts.length === 0) {
         parts.push(chalk.dim('nothing new'));
@@ -108,7 +118,25 @@ async function handleStatus() {
     }
     const when = new Date(ledger.lastSyncMtime).toLocaleString();
     console.log(`Last sync: ${chalk.bold(when)}`);
-    console.log(chalk.dim('Run `agents traces sync` to push new sessions.'));
+    const failures = ledger.failures ?? [];
+    if (failures.length > 0) {
+        const byKind = new Map();
+        for (const f of failures) {
+            const list = byKind.get(f.kind) ?? [];
+            list.push(f);
+            byKind.set(f.kind, list);
+        }
+        console.log(chalk.yellow(`\n${failures.length} unresolved failure${failures.length === 1 ? '' : 's'}:`));
+        for (const [kind, list] of byKind) {
+            const retry = kind === 'transcript-unavailable' ? chalk.dim(' (not retried)') : chalk.dim(' (retried each sync)');
+            console.log(`  ${chalk.bold(list.length)} ${kind}${retry}`);
+            const example = list[0];
+            if (example?.detail) {
+                console.log(chalk.dim(`    e.g. ${example.id.slice(0, 8)} · ${example.detail}`));
+            }
+        }
+    }
+    console.log(chalk.dim('\nRun `agents traces sync` to push new sessions.'));
 }
 async function handleOpen() {
     // M2 console — for now open the base URL which will route to the console once deployed.

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