@phnx-labs/agents-cli 1.22.50 → 1.22.52

package/dist/commands/go.d.ts

@@ -29,6 +29,28 @@ export declare function filterLivePool(sessions: ActiveSession[], opts?: {
     hosts?: string[];
     statuses?: LiveStatusFilter[];
 }): ActiveSession[];
+/**
+ * Live rows whose session id starts with `selector` (case-insensitive prefix).
+ * Same match `resolveOne` uses, so skip-fleet and resolve stay aligned.
+ */
+export declare function localLiveSelectorMatches(sessions: ActiveSession[], selector: string): ActiveSession[];
+/**
+ * Skip `gatherRemoteActive` when local already answered the selector:
+ * two local matches fail closed without waiting for a sleeping peer that
+ * might collide; a single local hit skips only when the selector is a full
+ * UUID or unique-enough 8-hex (`isUniqueEnoughSelector`). A shorter unique
+ * local prefix still races the fleet so a remote collision can fail closed.
+ * Zero matches still race the fleet.
+ */
+export declare function shouldSkipRemoteSweep(localMatches: ActiveSession[], selector: string): boolean;
+/**
+ * First-hit abort predicate for a live-id fleet race. A full UUID is globally
+ * unique so the first exact hit is the only hit. A unique-enough live prefix
+ * (8+ chars, the tmux `ag-<agent>-<8hex>` short id) aborts remaining SSH once
+ * a reachable peer answers — unanswered boxes must not delay (PHNX-3298).
+ * Shorter prefixes stay all-settle.
+ */
+export declare function isDefinitiveLiveMatch(session: ActiveSession, selector: string): boolean;
 /**
  * Live jump targets (local + remote), keyed by session id. Cloud is excluded by
  * default (it has no local pid to attach), but `detach` opts in with
@@ -38,11 +60,15 @@ export declare function filterLivePool(sessions: ActiveSession[], opts?: {
  * `hosts` scopes the sweep to named devices — the fan-out only dials them, and the
  * pool is then filtered to `s.machine ∈ hosts` so a stray local row can't leak in.
  * `statuses` narrows to the live-state words `--active` uses (orphan/crashed/…).
+ * `selector` (detach/stop) skips fleet SSH when local already has a unique live
+ * id or a local collision; omit it for browse (`focus` with no id) so the picker
+ * still all-settles.
  */
 export declare function gatherLiveTargets(local: boolean, opts?: {
     includeCloud?: boolean;
     hosts?: string[];
     statuses?: LiveStatusFilter[];
+    selector?: string;
 }): Promise<{
     self: string;
     activeById: Map<string, ActiveSession>;

package/dist/commands/go.js

@@ -18,17 +18,18 @@ import path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import { getActiveSessions, findSessionFileForKind, sessionProcessIsLocal, sessionProcessHost } from '../lib/session/active.js';
+import { isSessionIdShape } from '../lib/session/pid-registry.js';
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { deriveShortId } from '../lib/session/short-id.js';
-import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive, matchesLiveStatus, filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, } from './sessions.js';
+import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive, matchesLiveStatus, filterSessionsByQuery, formatPickerLabel, pickerColumnsFor, isUniqueEnoughSelector, } from './sessions.js';
 import { buildPreview } from './sessions-picker.js';
 import { multiItemPicker } from '../lib/picker.js';
 import { isPromptCancelled } from './utils.js';
 import { focusAction } from './focus.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { attachTmux, runTmux } from '../lib/tmux/binary.js';
-import { ensureSessionHookRepaired, paneExitStatus } from '../lib/tmux/session.js';
+import { ensureSessionHookRepaired, paneExitStatus, teardownIfAgentExited } from '../lib/tmux/session.js';
 import { getDefaultSocketPath } from '../lib/tmux/paths.js';
 import { sshExec, sshStream, assertValidSshTarget, shellQuote, SSH_CONN_FAILURE_CODE } from '../lib/ssh-exec.js';
 import { connectionEndedNotice } from '../lib/hosts/reconnect.js';
@@ -64,6 +65,50 @@ export function filterLivePool(sessions, opts = {}) {
     }
     return out;
 }
+/**
+ * Live rows whose session id starts with `selector` (case-insensitive prefix).
+ * Same match `resolveOne` uses, so skip-fleet and resolve stay aligned.
+ */
+export function localLiveSelectorMatches(sessions, selector) {
+    const q = selector.toLowerCase();
+    return sessions.filter((s) => (s.sessionId ?? '').toLowerCase().startsWith(q));
+}
+/**
+ * Skip `gatherRemoteActive` when local already answered the selector:
+ * two local matches fail closed without waiting for a sleeping peer that
+ * might collide; a single local hit skips only when the selector is a full
+ * UUID or unique-enough 8-hex (`isUniqueEnoughSelector`). A shorter unique
+ * local prefix still races the fleet so a remote collision can fail closed.
+ * Zero matches still race the fleet.
+ */
+export function shouldSkipRemoteSweep(localMatches, selector) {
+    if (localMatches.length >= 2)
+        return true;
+    if (localMatches.length === 1)
+        return isUniqueEnoughSelector(selector);
+    return false;
+}
+/**
+ * First-hit abort predicate for a live-id fleet race. A full UUID is globally
+ * unique so the first exact hit is the only hit. A unique-enough live prefix
+ * (8+ chars, the tmux `ag-<agent>-<8hex>` short id) aborts remaining SSH once
+ * a reachable peer answers — unanswered boxes must not delay (PHNX-3298).
+ * Shorter prefixes stay all-settle.
+ */
+export function isDefinitiveLiveMatch(session, selector) {
+    const id = (session.sessionId ?? '').toLowerCase();
+    const q = selector.trim().toLowerCase();
+    if (!id || !q)
+        return false;
+    if (isSessionIdShape(q))
+        return id === q;
+    return q.length >= 8 && id.startsWith(q);
+}
+function liveSelectorEarlyExit(selector) {
+    if (!selector || !isUniqueEnoughSelector(selector))
+        return undefined;
+    return { isDefinitive: (item) => isDefinitiveLiveMatch(item, selector) };
+}
 /**
  * Live jump targets (local + remote), keyed by session id. Cloud is excluded by
  * default (it has no local pid to attach), but `detach` opts in with
@@ -73,6 +118,9 @@ export function filterLivePool(sessions, opts = {}) {
  * `hosts` scopes the sweep to named devices — the fan-out only dials them, and the
  * pool is then filtered to `s.machine ∈ hosts` so a stray local row can't leak in.
  * `statuses` narrows to the live-state words `--active` uses (orphan/crashed/…).
+ * `selector` (detach/stop) skips fleet SSH when local already has a unique live
+ * id or a local collision; omit it for browse (`focus` with no id) so the picker
+ * still all-settles.
  */
 export async function gatherLiveTargets(local, opts = {}) {
     const self = machineId();
@@ -81,9 +129,16 @@ export async function gatherLiveTargets(local, opts = {}) {
         if (!s.machine)
             s.machine = self;
     let active = localActive;
-    if (!local) {
+    const skipRemote = local || (opts.selector
+        ? shouldSkipRemoteSweep(opts.hosts?.length
+            ? filterLivePool(localLiveSelectorMatches(localActive, opts.selector), { hosts: opts.hosts })
+            : localLiveSelectorMatches(localActive, opts.selector), opts.selector)
+        : false);
+    if (!skipRemote) {
         try {
-            const remote = await gatherRemoteActive(opts.hosts);
+            const remote = await gatherRemoteActive(opts.hosts, {
+                earlyExit: liveSelectorEarlyExit(opts.selector),
+            });
             active = dedupeByMachineSession([...localActive, ...remote.sessions]);
         }
         catch { /* remote sweep is best-effort */ }
@@ -320,7 +375,10 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
         // attach-time repair is what closes the gap now (RUSH-2435).
         if (session)
             await ensureSessionHookRepaired(session, socket);
-        process.exit(await attachTmux({ socket, args: ['attach-session', '-t', tgt] }));
+        const code = await attachTmux({ socket, args: ['attach-session', '-t', tgt] });
+        if (session)
+            await teardownIfAgentExited(session, socket);
+        process.exit(code);
     }
     // Path A: local Ghostty — focus its tab (Cmd+N via System Events).
     if (s.host === 'ghostty') {

package/dist/commands/menubar.js

@@ -27,8 +27,9 @@ function printStatus(s, opts = {}) {
         return;
     }
     console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
-    console.log(`  installed version  ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
-    console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
+    console.log(`  helper installed   ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
+    console.log(`  helper available   ${chalk.gray(s.currentVersion)}`);
+    console.log(`  CLI version        ${chalk.gray(s.cliVersion)}`);
     console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
     console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
     // Two copies of the INSTALLED bundle is the duplicate the user sees as two
@@ -80,8 +81,9 @@ function printSetupResult(r) {
 function printDoctorReport(r) {
     console.log(chalk.bold('AGI Menu doctor\n'));
     console.log(`  install path       ${r.installPath ? chalk.gray(r.installPath) : chalk.red('not installed')}`);
-    console.log(`  installed version  ${r.installedVersion ? chalk.gray(r.installedVersion) : chalk.gray('unknown')}`);
-    console.log(`  CLI version        ${chalk.gray(r.currentVersion)}${r.versionMatches ? '' : chalk.yellow('  (mismatch — `agents menubar setup` updates it)')}`);
+    console.log(`  helper installed   ${r.installedVersion ? chalk.gray(r.installedVersion) : chalk.gray('unknown')}`);
+    console.log(`  helper available   ${chalk.gray(r.currentVersion)}${r.versionMatches ? '' : chalk.yellow('  (newer helper available — `agents menubar setup` installs it)')}`);
+    console.log(`  CLI version        ${chalk.gray(r.cliVersion)}`);
     const identity = r.signingIdentity === 'developer-id'
         ? chalk.green('Developer ID (update-stable)')
         : r.signingIdentity === 'ad-hoc'

package/dist/commands/monitors.js

@@ -358,8 +358,8 @@ async function guardAgainstDuplicateMonitor(config, force) {
     // different arguments (another PR) are not a clash and still pass.
     if (process.env[NO_MONITOR_FANOUT_ENV])
         return;
-    const fleet = await gatherFleetMonitors();
     const mine = monitorFingerprint(config);
+    const fleet = await gatherFleetMonitors({ againstFingerprint: mine });
     const clash = fleet.monitors.find((r) => monitorFingerprint(r.monitor) === mine);
     if (clash) {
         stderrLine(chalk.red(`Monitor '${clash.monitor.name}' on ${chalk.bold(clash.machine)} already watches this exact source and fires the same action.`));

package/dist/commands/repo.js

@@ -29,7 +29,7 @@ function resolveRepoPath(target) {
     return path.join(HOME, `.agents-${trimmed}`);
 }
 import { applyExtraAliasToVersions, ensureAgentsDir, getExtraRepoDir, getSystemAgentsDir, getUserAgentsDir, readMeta, resolveExtraRepoDir, updateMeta, } from '../lib/state.js';
-import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin, adoptRepo, getRemoteUrl, sameGitRemote, displayHomePath, syncRepoGit, } from '../lib/git.js';
+import { parseSource, pullRepo, commitAndPush, isGitRepo, isSystemRepoOrigin, adoptRepo, adoptUserRepoIfNeeded, recordUserRepoRemote, resolveUserRepoRemoteUrl, getRemoteUrl, sameGitRemote, displayHomePath, syncRepoGit, } from '../lib/git.js';
 import { DEFAULT_SYSTEM_REPO } from '../lib/types.js';
 import { ALL_AGENT_IDS, isAgentName, resolveAgentName } from '../lib/agents.js';
 import { refresh } from '../lib/refresh.js';
@@ -1126,8 +1126,33 @@ Examples:
         }
         for (const t of targets) {
             if (!fs.existsSync(t.dir) || !isGitRepo(t.dir)) {
-                console.log(chalk.yellow(`  ${t.alias}: not a git repo, skipping`));
-                continue;
+                // The user repo self-heals in place instead of being skipped: adopt a
+                // non-git / partial checkout against its remote, preserving runtime
+                // state, then fall through to the normal sync (PHNX-3301). System is
+                // cloned by setup and extras by `repo add`, so those still skip.
+                if (t.alias === 'user' && fs.existsSync(t.dir)) {
+                    const spinner = ora(`Adopting ${formatRepoTarget(t.alias, t.dir)} in place...`).start();
+                    const adopted = await adoptUserRepoIfNeeded(t.dir);
+                    if (!adopted || !adopted.success) {
+                        spinner.fail(`${formatRepoTarget(t.alias, t.dir)}: ${adopted?.error ?? 'adopt failed'}`);
+                        if (adopted?.needsUrl)
+                            console.log(chalk.gray('  git-back it: agents repo pull user <git-url>'));
+                        process.exitCode = 1;
+                        continue;
+                    }
+                    spinner.succeed(`${formatRepoTarget(t.alias, t.dir)}: adopted in place → ${adopted.commit} (${adopted.materialized} file(s) materialized${adopted.reconciledAgentsYaml ? ', agents.yaml reconciled' : ''})`);
+                    if (adopted.localEdits.length > 0) {
+                        console.log(chalk.yellow(`  kept ${adopted.localEdits.length} local edit(s): ${adopted.localEdits.slice(0, 5).join(', ')}${adopted.localEdits.length > 5 ? ', …' : ''}`));
+                    }
+                    if (adopted.agentsYamlBackup) {
+                        console.log(chalk.gray(`  saved the previous agents.yaml to ${adopted.agentsYamlBackup}`));
+                    }
+                    // Now a git repo — fall through to the normal sync below.
+                }
+                else {
+                    console.log(chalk.yellow(`  ${t.alias}: not a git repo, skipping`));
+                    continue;
+                }
             }
             const push = t.alias !== 'system';
             const spinner = ora(`Syncing ${formatRepoTarget(t.alias, t.dir)}...`).start();
@@ -1136,6 +1161,9 @@ Examples:
                 const pushed = result.pushed ? ' (pushed)' : '';
                 spinner.succeed(`${formatRepoTarget(t.alias, t.dir)}: ${result.commit}${pushed}`);
                 if (t.alias === 'user') {
+                    const u = resolveUserRepoRemoteUrl(t.dir);
+                    if (u)
+                        recordUserRepoRemote(t.dir, u);
                     const { reconcileDeviceDiscoveryPolicies } = await import('../lib/devices/discovery-policy.js');
                     await reconcileDeviceDiscoveryPolicies();
                 }

package/dist/commands/sessions-resume.d.ts

@@ -22,6 +22,7 @@ export interface ResumeOptions extends StrictResumeOptions {
     local?: boolean;
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
+export declare function sessionsResumeAction(query: string | undefined, prompt: string | undefined, options: ResumeOptions): Promise<void>;
 /** IDs and tmux aliases are actions, not picker search text. Human phrases keep
  * the existing pre-filtered picker, while an explicit identity resumes directly. */
 export declare function isDirectResumeSelector(query: string): boolean;

package/dist/commands/sessions-resume.js

@@ -28,6 +28,7 @@ import { looksLikeSessionId } from '../lib/session/discover.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
 import { runStrictResume, wantsStrictResume } from './resume.js';
+import { attachLocalLiveSelector } from '../lib/session/local-tmux-attach.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
@@ -101,7 +102,7 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         await sessionsResumeAction(query, prompt, options);
     });
 }
-async function sessionsResumeAction(query, prompt, options) {
+export async function sessionsResumeAction(query, prompt, options) {
     const strictOpts = {
         mode: options.mode,
         interactive: options.interactive,
@@ -115,8 +116,18 @@ async function sessionsResumeAction(query, prompt, options) {
     // must go through sessions focus so they cannot silently fork a copy
     // (AGI EXT still shells `sessions resume <id> --local`).
     if (query && (isDirectResumeSelector(query) || wantsStrictResume(prompt, strictOpts))) {
+        const hosts = options.device ? [options.device] : [];
+        // PHNX-3292: a live LOCAL tmux pane (the exact alias, or a unique 8-hex
+        // short id) attaches immediately, before any fleet SSH — the product rule
+        // is "first unique match wins," and a pane already on this box is the
+        // fastest possible match. This applies to bare resume too, not just
+        // `--attach-only`: a prompt/mode/headless/cwd override still means the
+        // caller wants strict resume semantics (a scripted continue), so that
+        // case is excluded via wantsStrictResume.
+        if (!wantsStrictResume(prompt, strictOpts) && await attachLocalLiveSelector(query.trim(), hosts)) {
+            return;
+        }
         if (resumeUsesLifecycleDispatch(query, prompt, options)) {
-            const hosts = options.device ? [options.device] : [];
             await dispatchSessionLifecycleInPlace(query.trim(), hosts, !!options.attachOnly, !!options.local);
             return;
         }

package/dist/commands/sessions-stop.js

@@ -32,7 +32,7 @@ export function registerSessionsStopCommand(program) {
     });
 }
 export async function stopSessionAction(id, opts = {}) {
-    const { self, activeById } = await gatherLiveTargets(!!opts.local, { includeCloud: true });
+    const { self, activeById } = await gatherLiveTargets(!!opts.local, { includeCloud: true, selector: id });
     const resolved = resolveOne(activeById, id);
     if ('error' in resolved) {
         console.error(chalk.red(resolved.error));

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 } 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';
@@ -4579,35 +4579,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 +4743,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