@phnx-labs/agents-cli 1.22.51 → 1.22.53

package/dist/commands/sessions.d.ts

@@ -826,27 +826,37 @@ export type MetadataResolveOutcome = {
 };
 /**
  * A match unique enough to resolve on the FIRST peer that returns it and cancel
- * the rest of the fleet sweep: a full session UUID, which is globally unique.
+ * the rest of the fleet sweep: a full session UUID (globally unique), a live
+ * tmux alias, or a bare 8-hex short id — all three name at most one session PER
+ * ANSWERING peer, so the first reachable hit is enough (PHNX-3292: the alias/
+ * short-id case is exactly what `agents tmux ls` prints, and it used to stay
+ * all-settle right alongside a genuine keyword search).
  *
- * Only a full UUID qualifies. A session **label** is deliberately NOT definitive
- * here even on an exact match: labels are free-form and can collide, so a
- * distinct session may carry the same label on a peer that has not answered yet
- * — early-exiting on the first would silently, and nondeterministically, resume
- * the wrong session (whichever peer replied first). Labels therefore stay
- * all-settle so a cross-machine label conflict surfaces as an ambiguity, and a
- * short-id PREFIX stays all-settle for the same reason (RUSH-2203).
+ * A session **label** is deliberately NOT definitive here even on an exact
+ * match: labels are free-form and can collide, so a distinct session may carry
+ * the same label on a peer that has not answered yet — early-exiting on the
+ * first would silently, and nondeterministically, resume the wrong session
+ * (whichever peer replied first). Labels therefore stay all-settle so a
+ * cross-machine label conflict surfaces as an ambiguity, and a short-id PREFIX
+ * *shorter* than the full 8-hex width stays all-settle for the same reason
+ * (RUSH-2203).
  *
  * This is about cancelling a sweep that is still IN FLIGHT, where a peer that
  * has not answered yet is still expected to. It is deliberately stricter than
  * `isUniqueEnoughSelector`, which decides what to do once the sweep is OVER and
- * a peer has definitively not answered — see SES-9a.
+ * a peer has definitively not answered — see SES-9a. A collision between two
+ * peers that BOTH answer before the abort lands is still caught by the ordinary
+ * uniqueness gate in `metadataResolveOutcome`/`fleetCandidatesByQuery`; only a
+ * peer that has not answered yet, at the moment of the FIRST hit, is the
+ * accepted risk (documented in the PHNX-3292 plan).
  */
 export declare function isDefinitiveMatch(session: SessionMeta, selector: string): boolean;
 /**
- * Whether a selector may enable early-exit on the cancellable fan-out — only a
- * full UUID, which is globally unique so the first hit is the only hit. Labels,
- * keywords, and short-id prefixes stay all-settle: their uniqueness (or
- * conflict) is only knowable once every peer has answered. See
+ * Whether a selector may enable early-exit on the cancellable fan-out: a full
+ * UUID, a tmux alias, or an exact 8-hex short id — every shape that is globally
+ * unique enough for the first hit to be the only hit worth waiting for. Labels,
+ * keywords, and short-id prefixes narrower than 8 hex stay all-settle: their
+ * uniqueness (or conflict) is only knowable once every peer has answered. See
  * {@link isDefinitiveMatch}.
  */
 export declare function selectorAllowsEarlyExit(selector: string): boolean;

package/dist/commands/sessions.js

@@ -18,10 +18,10 @@ import { sanitizeForTerminal, redactSecrets } from '../lib/redact.js';
 import { resolveProjectKey } from '../lib/project-key.js';
 import { listProjectDefs, resolveProjectNameForCwd } from '../lib/projects.js';
 import ora from 'ora';
-import { SESSION_AGENTS } from '../lib/session/types.js';
+import { SESSION_AGENTS, isAgentTmuxAlias, sessionDisplayAgent } from '../lib/session/types.js';
 import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session/artifacts.js';
 import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, composeWin32CommandLine } from '../lib/platform/index.js';
-import { getActiveSessions, describeActiveDiscoveryHealth, sessionProcessIsLocal, backfillActiveRowsFromIndex, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } from '../lib/session/active.js';
+import { getActiveSessions, describeActiveDiscoveryHealth, sessionProcessIsLocal, backfillActiveRowsFromIndex, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson, shortIdFromName } from '../lib/session/active.js';
 export { activeSessionProjectKey, backfillActiveRowsFromIndex, backfillActiveRowsFromMeta, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } from '../lib/session/active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
@@ -233,9 +233,10 @@ async function renderArtifactsForSession(session, listAll, name) {
         console.log(chalk.gray('No file-write artifacts found in this session.'));
         return;
     }
-    const agentColor = colorAgent(session.agent);
+    const shown = sessionDisplayAgent(session);
+    const agentColor = colorAgent(shown);
     console.log('');
-    console.log(agentColor(session.agent) +
+    console.log(agentColor(shown) +
         chalk.gray(` · ${session.shortId} · ${formatRelativeTime(session.timestamp)}`));
     console.log(chalk.gray('─'.repeat(72)));
     for (const a of artifacts) {
@@ -726,7 +727,8 @@ function fitCell(content, room) {
  */
 export function renderActiveRowLines(s, indent, termW) {
     const idCol = chalk.dim(padToWidth((s.sessionId?.slice(0, 8)) ?? '-', ROW_ID_W));
-    const kindCol = colorAgent(s.kind)(padToWidth(truncateToWidth(s.kind, ROW_AGENT_W), ROW_AGENT_W + 1));
+    const shownKind = sessionDisplayAgent({ agent: s.kind, harness: s.harness });
+    const kindCol = colorAgent(shownKind)(padToWidth(truncateToWidth(shownKind, ROW_AGENT_W), ROW_AGENT_W + 1));
     const versionCol = chalk.gray(padToWidth(truncateToWidth(s.version ?? '', ROW_VERSION_W), ROW_VERSION_W + 1));
     const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), ROW_STATUS_W - 1), ROW_STATUS_W));
     const ownerCol = chalk.cyan(padToWidth(truncateToWidth(ownerLabel(s), ROW_OWNER_W - 1), ROW_OWNER_W));
@@ -1010,6 +1012,7 @@ export function serializeResolvedSessionsJson(sessions) {
         id: session.id,
         shortId: session.shortId,
         agent: session.agent,
+        harness: session.harness,
         origin: session.origin,
         timestamp: session.timestamp,
         lastActivity: session.lastActivity,
@@ -1805,7 +1808,8 @@ function runOutcomeDetail(meta) {
 /** Compact per-session metadata line under a linked session row. */
 function linkedSessionMeta(session) {
     const parts = [];
-    parts.push(session.version ? `${session.agent} v${session.version}` : session.agent);
+    const shown = sessionDisplayAgent(session);
+    parts.push(session.version ? `${shown} v${session.version}` : shown);
     if (session.account)
         parts.push(session.account);
     if (session.model)
@@ -2996,7 +3000,8 @@ function timeCell(age, topicSlack) {
  * when `showTicket` — otherwise a listing with no refs would waste a column of
  * dashes and needlessly truncate the topic. Worktree stays a trailing badge. */
 export function flatSessionRow(session, live, showTicket = false, cols = {}, bookmarked = false) {
-    const agentColor = colorAgent(session.agent);
+    const shown = sessionDisplayAgent(session);
+    const agentColor = colorAgent(shown);
     const age = sessionAgeParts(session.timestamp, session.lastActivity);
     const project = session.project || '-';
     const tag = originTag(session) || teamTag(session);
@@ -3045,7 +3050,7 @@ export function flatSessionRow(session, live, showTicket = false, cols = {}, boo
     const topicW = Math.max(MIN_TOPIC_W, width - fixedW - modelW - when.extraW);
     return (bookmarkCell +
         chalk.white(padToWidth(truncateToWidth(session.shortId, 9), 10)) +
-        agentColor(padToWidth(truncateToWidth(session.agent, 8), 9)) +
+        agentColor(padToWidth(truncateToWidth(shown, 8), 9)) +
         chalk.yellow(padToWidth(truncateToWidth(session.version || '-', 7), 8)) +
         (modelW ? chalk.yellow(padToWidth(truncateToWidth(modelLabel(session.model), modelW - 1), modelW)) : '') +
         machineCell +
@@ -3060,7 +3065,8 @@ export function flatSessionRow(session, live, showTicket = false, cols = {}, boo
 }
 /** One tree-mode row (grouped under a dir header): id · agent · badges · topic · time. No version/project column. */
 function treeSessionRow(session, live) {
-    const agentColor = colorAgent(session.agent);
+    const shown = sessionDisplayAgent(session);
+    const agentColor = colorAgent(shown);
     const age = sessionAgeParts(session.timestamp, session.lastActivity);
     const tag = originTag(session) || teamTag(session);
     const label = session.label;
@@ -3082,7 +3088,7 @@ function treeSessionRow(session, live) {
     const topicW = Math.max(12, baseTopicW - when.extraW);
     return ('  ' +
         chalk.dim(padToWidth(session.shortId, 9)) +
-        agentColor(padToWidth(truncateToWidth(session.agent, 7), 8)) +
+        agentColor(padToWidth(truncateToWidth(shown, 7), 8)) +
         (badges ? badges + ' ' : '') +
         (glyph ? glyph + ' ' : '') +
         statusCell +
@@ -3246,7 +3252,8 @@ const TEAM_HANDLE_W = 16;
  * identity the `--teams` view exists to show (RUSH-1997).
  */
 function teamMemberRow(session, live) {
-    const agentColor = colorAgent(session.agent);
+    const shown = sessionDisplayAgent(session);
+    const agentColor = colorAgent(shown);
     const origin = session.teamOrigin;
     const age = sessionAgeParts(session.timestamp, session.lastActivity);
     const handle = safeTeamText(origin?.handle) ?? session.shortId;
@@ -3267,7 +3274,7 @@ function teamMemberRow(session, live) {
     const topicW = Math.max(12, baseTopicW - when.extraW);
     return ('  ' +
         chalk.dim(padToWidth(session.shortId, 9)) +
-        agentColor(padToWidth(truncateToWidth(session.agent, 7), 8)) +
+        agentColor(padToWidth(truncateToWidth(shown, 7), 8)) +
         chalk.yellow(padToWidth(truncateToWidth(mode || '-', TEAM_MODE_W), TEAM_MODE_W + 1)) +
         (badges ? badges + ' ' : '') +
         (glyph ? glyph + ' ' : '') +
@@ -3444,13 +3451,14 @@ function renderArchivedSession(session, mode, options = {}) {
         }, null, 2));
         return;
     }
-    const agentColor = colorAgent(session.agent);
+    const shown = sessionDisplayAgent(session);
+    const agentColor = colorAgent(shown);
     const absTime = formatAbsoluteTime(session.timestamp);
     const title = session.label || session.topic;
     console.log('');
     if (title)
         console.log(chalk.bold.white(title));
-    console.log(agentColor(session.agent) +
+    console.log(agentColor(shown) +
         (session.version ? chalk.yellow(` ${session.version}`) : '') +
         (session.project ? chalk.cyan(`  ${session.project}`) : '') +
         chalk.gray(`  ${absTime} (${formatRelativeTime(session.timestamp)})`) +
@@ -3481,7 +3489,7 @@ async function renderSession(session, mode, filters, options = {}) {
         console.log(chalk.yellow('Session transcript not available (file no longer exists).'));
         console.log(chalk.gray(`Path: ${session.filePath}`));
         if (session.version)
-            console.log(chalk.gray(`Version: ${session.agent} ${session.version}`));
+            console.log(chalk.gray(`Version: ${sessionDisplayAgent(session)} ${session.version}`));
         if (session.project)
             console.log(chalk.gray(`Project: ${session.project}`));
         if (session.account)
@@ -3489,11 +3497,12 @@ async function renderSession(session, mode, filters, options = {}) {
         console.log(chalk.gray(`Time: ${session.timestamp}`));
         return;
     }
-    const spinner = ora(`Parsing ${session.agent} session...`).start();
+    const spinner = ora(`Parsing ${sessionDisplayAgent(session)} session...`).start();
     const parsedEvents = parseSession(session.filePath, session.agent);
     spinner.stop();
     let events = filterEvents(parsedEvents, filters);
-    const agentColor = colorAgent(session.agent);
+    const shown = sessionDisplayAgent(session);
+    const agentColor = colorAgent(shown);
     console.log('');
     if (mode === 'summary') {
         const stats = computeSummaryStats(events);
@@ -3507,7 +3516,7 @@ async function renderSession(session, mode, filters, options = {}) {
             const badges = signalBadges(metaSignals(session));
             console.log(chalk.bold.white(title) + (badges ? '  ' + badges : ''));
         }
-        console.log(agentColor(session.agent) +
+        console.log(agentColor(shown) +
             (session.version ? chalk.yellow(` ${session.version}`) : '') +
             modelStr +
             (session.project ? chalk.cyan(`  ${session.project}`) + branchStr : branchStr) +
@@ -3521,7 +3530,7 @@ async function renderSession(session, mode, filters, options = {}) {
         return;
     }
     if (mode === 'markdown') {
-        console.log(agentColor(session.agent) +
+        console.log(agentColor(shown) +
             (session.version ? chalk.yellow(` ${session.version}`) : '') +
             (session.project ? chalk.cyan(` ${session.project}`) : '') +
             chalk.gray(` ${formatRelativeTime(session.timestamp)}`) +
@@ -3662,7 +3671,8 @@ export function liveHostLabel(a) {
     return viewer && viewer !== a.host ? `${a.host}→${viewer}` : a.host;
 }
 export function formatPickerLabel(s, query, cols = {}, ssh, host = '', bookmarked = false, live) {
-    const agentColor = colorAgent(s.agent);
+    const shown = sessionDisplayAgent(s);
+    const agentColor = colorAgent(shown);
     const age = sessionAgeParts(s.timestamp, s.lastActivity);
     const project = s.project || '-';
     // SSH-launch origin (live rows only): mirrors the flat listing's `ssh←<device>`
@@ -3727,7 +3737,7 @@ export function formatPickerLabel(s, query, cols = {}, ssh, host = '', bookmarke
         // live row with no session id is named by its pid or cloud task, which can
         // run past the column and shunt every later column out of alignment.
         chalk.white(padRight(truncate(s.shortId, 9), 10)) +
-        agentColor(padRight(truncate(s.agent, 8), 9)) +
+        agentColor(padRight(truncate(shown, 8), 9)) +
         chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
         machineCell +
         hostCell +
@@ -4579,35 +4589,53 @@ function modeFlag(mode) {
     return undefined; // summary — the peer's default render
 }
 const FULL_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Width of `SessionMeta.shortId` / the hex a tmux alias embeds (`deriveShortId`). */
+const SHORT_SESSION_ID_RE = /^[0-9a-f]{8}$/i;
 /**
  * A match unique enough to resolve on the FIRST peer that returns it and cancel
- * the rest of the fleet sweep: a full session UUID, which is globally unique.
+ * the rest of the fleet sweep: a full session UUID (globally unique), a live
+ * tmux alias, or a bare 8-hex short id — all three name at most one session PER
+ * ANSWERING peer, so the first reachable hit is enough (PHNX-3292: the alias/
+ * short-id case is exactly what `agents tmux ls` prints, and it used to stay
+ * all-settle right alongside a genuine keyword search).
  *
- * Only a full UUID qualifies. A session **label** is deliberately NOT definitive
- * here even on an exact match: labels are free-form and can collide, so a
- * distinct session may carry the same label on a peer that has not answered yet
- * — early-exiting on the first would silently, and nondeterministically, resume
- * the wrong session (whichever peer replied first). Labels therefore stay
- * all-settle so a cross-machine label conflict surfaces as an ambiguity, and a
- * short-id PREFIX stays all-settle for the same reason (RUSH-2203).
+ * A session **label** is deliberately NOT definitive here even on an exact
+ * match: labels are free-form and can collide, so a distinct session may carry
+ * the same label on a peer that has not answered yet — early-exiting on the
+ * first would silently, and nondeterministically, resume the wrong session
+ * (whichever peer replied first). Labels therefore stay all-settle so a
+ * cross-machine label conflict surfaces as an ambiguity, and a short-id PREFIX
+ * *shorter* than the full 8-hex width stays all-settle for the same reason
+ * (RUSH-2203).
  *
  * This is about cancelling a sweep that is still IN FLIGHT, where a peer that
  * has not answered yet is still expected to. It is deliberately stricter than
  * `isUniqueEnoughSelector`, which decides what to do once the sweep is OVER and
- * a peer has definitively not answered — see SES-9a.
+ * a peer has definitively not answered — see SES-9a. A collision between two
+ * peers that BOTH answer before the abort lands is still caught by the ordinary
+ * uniqueness gate in `metadataResolveOutcome`/`fleetCandidatesByQuery`; only a
+ * peer that has not answered yet, at the moment of the FIRST hit, is the
+ * accepted risk (documented in the PHNX-3292 plan).
  */
 export function isDefinitiveMatch(session, selector) {
-    return FULL_SESSION_ID_RE.test(selector) && session.id.toLowerCase() === selector.trim().toLowerCase();
+    const trimmed = selector.trim();
+    if (FULL_SESSION_ID_RE.test(trimmed)) {
+        return session.id.toLowerCase() === trimmed.toLowerCase();
+    }
+    const shortId = shortIdFromName(trimmed) ?? (SHORT_SESSION_ID_RE.test(trimmed) ? trimmed : undefined);
+    return !!shortId && session.shortId.toLowerCase() === shortId.toLowerCase();
 }
 /**
- * Whether a selector may enable early-exit on the cancellable fan-out — only a
- * full UUID, which is globally unique so the first hit is the only hit. Labels,
- * keywords, and short-id prefixes stay all-settle: their uniqueness (or
- * conflict) is only knowable once every peer has answered. See
+ * Whether a selector may enable early-exit on the cancellable fan-out: a full
+ * UUID, a tmux alias, or an exact 8-hex short id — every shape that is globally
+ * unique enough for the first hit to be the only hit worth waiting for. Labels,
+ * keywords, and short-id prefixes narrower than 8 hex stay all-settle: their
+ * uniqueness (or conflict) is only knowable once every peer has answered. See
  * {@link isDefinitiveMatch}.
  */
 export function selectorAllowsEarlyExit(selector) {
-    return FULL_SESSION_ID_RE.test(selector);
+    const trimmed = selector.trim();
+    return FULL_SESSION_ID_RE.test(trimmed) || isAgentTmuxAlias(trimmed) || SHORT_SESSION_ID_RE.test(trimmed);
 }
 /** Resolve a fleet sweep through the same canonical full-id / prefix resolver as
  * local lookups, then group copies by logical session id. Synced mirrors of one
@@ -4725,9 +4753,11 @@ export function metadataResolveOutcome(localMatches, remote, selector) {
     //     6-char word like `facade` or `decade` is not treated as an identifier.
     // A label stays fail-closed at any length: labels are free-form and collide by
     // design, so one hit there really is a guess.
-    // (RUSH-2203's early-exit stays UUID-only — see isDefinitiveMatch — because
-    // that cancels the sweep mid-flight, where a peer that has not answered YET is
-    // still expected to answer. Here the sweep is already over.)
+    // (RUSH-2203's early-exit — see isDefinitiveMatch — cancels the sweep
+    // mid-flight, where a peer that has not answered YET is still expected to
+    // answer, so it stays narrower than this post-sweep gate even though
+    // PHNX-3292 widened it past UUID to alias/8-hex too. Here the sweep is
+    // already over.)
     if (isUniqueEnoughSelector(selector) && candidates.length === 1) {
         return { kind: 'resolved', session: candidates[0].hits[0].session };
     }

package/dist/commands/setup-browser.d.ts

@@ -10,8 +10,11 @@
 import type { Command } from 'commander';
 /**
  * Interactive browser setup. Returns true if a usable default profile exists
- * afterwards, false if the machine has no supported browser or the user backed
- * out. Never throws on cancel — the `agents setup` hub relies on that.
+ * afterwards, false if none exists / the user backed out. Non-interactively it
+ * only RECOGNIZES an existing profile — it never creates one (PHNX-3296), since
+ * silently minting a logged-out `auto-chrome` on a headless box is the exact bug
+ * that removed; a headless box gets its browser from the fleet hub. Never throws
+ * on cancel — the `agents setup` hub relies on that.
  */
 export declare function runBrowserWizard(): Promise<boolean>;
 /** Register `agents setup browser` under the parent `setup` command. */

package/dist/commands/setup-browser.js

@@ -9,7 +9,7 @@
  */
 import chalk from 'chalk';
 import { setConfigValue } from '../lib/device-config.js';
-import { findFirstInstalledBrowser, listInstalledBrowsers } from '../lib/browser/chrome.js';
+import { listInstalledBrowsers } from '../lib/browser/chrome.js';
 import { DEFAULT_BROWSER_PROFILE_NAME, getAutoDetectedProfile, createProfile, findFreeProfilePort, getConfiguredDefaultProfileName, } from '../lib/browser/profiles.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -18,25 +18,27 @@ const INSTALL_HINT = 'Install one of: Google Chrome, Brave, Microsoft Edge, Chro
     '(Safari and Firefox are not supported — agents browser drives over the Chrome DevTools Protocol.)';
 /**
  * Interactive browser setup. Returns true if a usable default profile exists
- * afterwards, false if the machine has no supported browser or the user backed
- * out. Never throws on cancel — the `agents setup` hub relies on that.
+ * afterwards, false if none exists / the user backed out. Non-interactively it
+ * only RECOGNIZES an existing profile — it never creates one (PHNX-3296), since
+ * silently minting a logged-out `auto-chrome` on a headless box is the exact bug
+ * that removed; a headless box gets its browser from the fleet hub. Never throws
+ * on cancel — the `agents setup` hub relies on that.
  */
 export async function runBrowserWizard() {
     if (!isInteractiveTerminal()) {
-        // Non-interactive: do the safe, deterministic thing (auto-detect + pin a
-        // default) without prompting, or print the install hint and bail.
-        if (!findFirstInstalledBrowser()) {
-            console.error(chalk.red('No supported browser found.\n') + chalk.dim(INSTALL_HINT));
-            return false;
-        }
+        // Non-interactive / headless: recognize an existing default, but NEVER mint
+        // one. Silently auto-detecting an installed browser and creating an
+        // `auto-chrome` here is exactly the bug PHNX-3296 removed — a headless box
+        // gets its browser from the fleet hub (`browser.device`), or from an
+        // interactive pick later.
         const existing = await getAutoDetectedProfile();
         if (existing) {
             console.log(chalk.dim(`Browser profile "${existing.name}" already exists.`));
             return true;
         }
-        const created = await createAutoDefault();
-        console.log(chalk.green(`Created browser profile "${created.name}" → ${created.browser}.`));
-        return true;
+        console.log(chalk.dim('No default browser profile on this machine. Re-run `agents setup browser` in an ' +
+            'interactive terminal to pick one, or use the fleet hub: agents config set browser.device <host>.'));
+        return false;
     }
     const installed = listInstalledBrowsers();
     if (installed.length === 0) {
@@ -86,23 +88,6 @@ export async function runBrowserWizard() {
     printOnboardingNextStep(profile.name);
     return true;
 }
-/** Build + persist a `default` profile pinned to the first installed browser. */
-async function createAutoDefault() {
-    const detected = findFirstInstalledBrowser();
-    if (!detected)
-        throw new Error('No supported browser found.');
-    const freePort = await findFreeProfilePort();
-    const profile = {
-        name: DEFAULT_BROWSER_PROFILE_NAME,
-        description: `Auto-detected ${detected.browserType} profile`,
-        browser: detected.browserType,
-        binary: detected.binary,
-        endpoints: [`cdp://127.0.0.1:${freePort}`],
-        viewport: { width: DEFAULT_VIEWPORT.width, height: DEFAULT_VIEWPORT.height },
-    };
-    await createProfile(profile);
-    return profile;
-}
 /** Offer to make `name` this machine's default browser profile (device-local). */
 async function maybeSetDeviceDefault(name, confirm) {
     const current = getConfiguredDefaultProfileName();

package/dist/commands/setup-preferences.d.ts

@@ -40,10 +40,29 @@ export declare function maybePickInteractiveHost(): Promise<boolean>;
  * 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 declare function maybePickBrowserProfile(): Promise<boolean>;
+export declare function maybePickBrowserProfile(deps?: {
+    /** Force interactivity in a test; defaults to a real TTY probe. */
+    interactive?: boolean;
+    /** Inject the prompt so the pick is testable without a TTY. */
+    select?: (config: {
+        message: string;
+        default?: string;
+        choices: Array<{
+            name: string;
+            value: string;
+        }>;
+    }) => Promise<string>;
+}): Promise<boolean>;
 /**
  * The bare-`agents setup` preferences step: interactive host, then browser.
  * Runs AFTER the capability hub so it never delays the bootstrap. Never

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.