@phnx-labs/agents-cli 1.22.50 → 1.22.52

package/dist/commands/browser.js

@@ -14,7 +14,7 @@ import { DEFAULT_VIEWPORT, parseWindowSize, parseWindowPosition } from '../lib/b
 import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
-import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest as sendRawIPCRequest, } from '../lib/browser/ipc.js';
+import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest as sendRawIPCRequest, resetBrowserDaemon, } from '../lib/browser/ipc.js';
 import { bindTask, getTaskBinding, honorScreenshotOutput, REJECT_DEVICE_MESSAGE, resolveTaskRoute, unbindTask, unbindTasksForProfile, updateTaskBinding, } from '../lib/browser/task-index.js';
 import { isSelfHost } from '../lib/devices/self-host.js';
 import { resolveHost } from '../lib/hosts/registry.js';
@@ -248,6 +248,23 @@ function assertDeviceDeclaresProfile(device, profileName) {
     throw new Error(`Device "${device}" does not declare browser profile "${profileName}". ${where}\n` +
         `Next: run \`agents browser profiles add ${profileName} --browser <b>\` on ${device}.`);
 }
+/**
+ * The fleet browser hub this box drives by default (`browser.device`), or
+ * undefined to drive locally. It is one fleet-synced value in the central
+ * agents.yaml, so every box reads the same hub name — but the hub itself resolves
+ * to a self-host, and a fleet-dispatched invocation is already ON its target, so
+ * both return undefined. That self short-circuit is what lets a single synced
+ * value be safe: only the boxes that are NOT the hub forward to it, and the hub
+ * never forwards to itself.
+ */
+export function defaultBrowserHub() {
+    if (isFleetRemoteInvocation())
+        return undefined;
+    const hub = getConfigValue('browser.device').value;
+    if (!hub || isSelfHost(hub))
+        return undefined;
+    return hub;
+}
 // Help groups — surfaces the actual mental model an agent follows
 // ("open a session / drive the page / capture evidence / rare extras")
 // instead of an alphabetical dump. Everything not listed falls into a
@@ -277,7 +294,7 @@ export function registerBrowserCommand(program) {
       # Create a Chrome profile pointed at a CDP endpoint
       agents browser profiles create work --browser chrome --endpoint http://localhost:9222
 
-      # Start a session — auto-picks the first installed Chromium-family browser
+      # Start a session on this machine's default browser (set it once with: agents browser use)
       agents browser start
 
       # Or pin to a specific profile
@@ -306,6 +323,11 @@ export function registerBrowserCommand(program) {
 
       # Close tabs the daemon's own reaper would have caught on its next 5-min tick
       agents browser prune --dry-run
+
+      # Recover a wedged daemon ("Timeout waiting for browser daemon socket"):
+      # stop it and clear a stale socket, then start clean
+      agents browser stop --daemon
+      agents browser start
     `,
         notes: `
       Most agent workflows should use the 'browser' skill instead of raw subcommands.
@@ -346,7 +368,7 @@ export function buildBrowserUseChoices(profiles, installed, current) {
 export async function runBrowserUse(name, opts, interactive = isInteractiveTerminal()) {
     if (opts.unset || name === 'auto') {
         unsetConfigValue('browser.profile');
-        console.log('Default browser profile cleared. `agents browser start` will auto-detect an installed Chromium-family browser.');
+        console.log('Default browser profile cleared. Pick one with `agents browser use <name>` (or `agents setup`); until then `agents browser start` has no default to launch here.');
         return true;
     }
     let selectedName = name;
@@ -355,8 +377,15 @@ export async function runBrowserUse(name, opts, interactive = isInteractiveTermi
         if (!interactive) {
             console.log(current
                 ? `Default browser profile (this machine): ${current}`
-                : 'Default browser profile (this machine): auto-detect');
+                : 'Default browser profile (this machine): none — pick one with `agents browser use <name>`');
+            const hub = getConfigValue('browser.device').value;
+            if (hub) {
+                console.log(isSelfHost(hub)
+                    ? `Browser hub (browser.device): ${hub} — this machine, so drives locally`
+                    : `Browser hub (browser.device): ${hub} — bare \`agents browser start\` drives ${hub}'s browser`);
+            }
             console.log('Usage: agents browser use <name>  (or --unset)');
+            console.log('Fleet hub: agents config set browser.device <device>  (drive that box\'s browser from every machine)');
             return true;
         }
         const choices = buildBrowserUseChoices(await listProfiles(), listInstalledBrowsers(), current);
@@ -397,7 +426,7 @@ export async function runBrowserUse(name, opts, interactive = isInteractiveTermi
 function configureBrowserUseCommand(command, deprecated = false) {
     command
         .description('Pick the profile `agents browser start` uses when no --profile is passed. No name opens a picker on a TTY or prints the current default headlessly.')
-        .option('--unset', 'Clear the configured default (revert to auto-detecting an installed browser)')
+        .option('--unset', 'Clear the configured default (leaves this machine with no default until you pick one)')
         .action(async (name, opts) => {
         if (deprecated) {
             console.warn(chalk.yellow('Deprecation: `agents browser profiles set-default` is replaced by `agents browser use`.'));
@@ -918,7 +947,7 @@ function registerProfilesCommands(browser) {
             (removed > 0 ? ` (and ${removed} cache dir${removed === 1 ? '' : 's'})` : ''));
         if (getConfiguredDefaultProfileName() === name) {
             console.error(`warning: "${name}" was this machine's default browser profile; ` +
-                `\`agents browser start\` will auto-detect until you run: agents browser use <name>`);
+                `\`agents browser start\` has no default here until you run: agents browser use <name>`);
         }
     });
     profiles
@@ -1001,13 +1030,13 @@ function registerProfilesCommands(browser) {
       with \`agents browser profiles claim\` on the machine that hosts the browser.
 
       In \`list\`, the \`*\` marker means "this machine's configured default"
-      (\`agents browser start\` with no --profile). The auto-detected profile is
-      named \`auto-chrome\`; \`default\` is only an ALIAS for whichever profile
+      (\`agents browser start\` with no --profile). A profile a setup wizard pins
+      is named \`auto-chrome\`; \`default\` is only an ALIAS for whichever profile
       this machine is configured to use, resolved the same way by every command.
 
       \`prune\` only considers profiles this device declares. It never removes a
-      profile that is in use, the configured default, or the auto-detected
-      \`auto-chrome\`.
+      profile that is in use, the configured default, or the \`auto-chrome\`
+      profile a setup wizard created.
     `,
     });
     profiles
@@ -1347,13 +1376,13 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('start')
-        .description('Start a browser task. Pass --profile <name>; omit to use your configured default (`agents browser use <name>`), else auto-pick an installed Chromium-family browser. Page verbs (navigate/screenshot/…) create a task implicitly when none exists — start is for --profile/--url/--record/--title.')
-        .option('-p, --profile <name>', 'Browser profile to use (omit to use the configured default, else auto-pick an installed Chromium-family browser)')
+        .description('Start a browser task. Pass --profile <name>; omit to use your configured default (set it with `agents browser use <name>` or `agents setup`). Page verbs (navigate/screenshot/…) create a task implicitly when none exists — start is for --profile/--url/--record/--title.')
+        .option('-p, --profile <name>', 'Browser profile to use (omit to use this machine\'s configured default; set it with `agents browser use <name>`)')
         .option(TASK_OPTION_FLAG, 'Task name (auto-generated short id if omitted)')
         .option('--title <label>', 'Human label shown in `browser status` (defaults to first navigated host)')
         .option('-e, --endpoint <name>', 'Endpoint preset (defaults to the profile\'s default)')
         .option('-u, --url <url>', 'Open URL in first tab')
-        .option('--device <name>', 'Device that hosts this task; later verbs resolve it from --task (not valid on page verbs)')
+        .option('--device <name>', 'Device that hosts this task (defaults to the browser.device hub when set; use `local` to force this machine). Later verbs resolve it from --task; not valid on page verbs')
         .option('--fresh', 'Always open a new tab, skipping the reclaim of a tab an abandoned task is holding on that URL')
         .option('--no-skills', 'Skip auto-discovery of site-specific SKILL.md from ~/.agents/skills/browser/domain-skills/')
         .option('--record', 'Start recording right after the tab opens (shorthand for `agents browser record start` as a follow-up)')
@@ -1373,13 +1402,133 @@ function registerTaskCommands(browser) {
             console.error(err instanceof Error ? err.message : String(err));
             process.exit(1);
         }
+        // Thin-client hub (PHNX-2010): when this box has a fleet browser hub
+        // (`browser.device`) and the caller gave no explicit --device, forward the
+        // WHOLE start there — bare OR --profile — and skip the local profile/browser
+        // resolution below. The hub owns its profiles, browser, and consent, so this
+        // box needs no local browser and need not carry the named profile; forwarding
+        // the local pre-checks here would reject a profile that lives only on the hub.
+        // Later page verbs follow the task to the hub via the task→device index bound
+        // here. `--device local`/`--device self` (below) force a local run instead;
+        // `defaultBrowserHub()` is undefined on the hub itself and on a fleet-remote
+        // re-exec, so neither forwards to itself.
+        if (!opts.device) {
+            const hub = defaultBrowserHub();
+            if (hub) {
+                // No local profile validation: the hub is the authority on its own
+                // profiles (including fleet-scoped ones this box can't see in
+                // `declaringDevices`), so a bad `--profile` is caught by the hub's own
+                // start and streamed back with its exit code, rather than second-guessed
+                // here against a registry that doesn't carry the hub's profiles.
+                try {
+                    const result = await dispatchBrowserToDevice(hub, browserForwardedArgv(), 'capture');
+                    process.stdout.write(result.stdout);
+                    process.stderr.write(result.stderr);
+                    if (result.code !== 0)
+                        process.exit(result.code);
+                    const taskName = opts.task || result.stdout.trim().split('\n').find((line) => line.length > 0);
+                    if (!taskName) {
+                        console.error(`Remote start on ${hub} produced no task name.`);
+                        process.exit(1);
+                    }
+                    bindTask(taskName, {
+                        device: hub,
+                        // Only what the caller named; the hub's own default (bare start) is
+                        // opaque here. Name-based `done`/`stop --task` and the post-stop
+                        // unbind GC these regardless.
+                        profile: opts.profile,
+                        url: opts.url,
+                        sessionId: callerSessionId(),
+                        launchId: callerLaunchId(),
+                        createdAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err));
+                    process.exit(1);
+                }
+                return;
+            }
+        }
+        // Resolve an EXPLICIT --device BEFORE any local profile/browser
+        // resolution (PHNX-3289). The task lives on the TARGET device, so its
+        // browser binary and profile must resolve THERE. Resolving locally first
+        // made a browserless box fail with a misleading "No supported browser
+        // found" (bare start) or "Profile <x> not found" (a profile that lives
+        // only on the target) before the start ever routed to --device. This
+        // mirrors the hub path above: the target is the authority on its own
+        // profiles, so forward the whole start and let it validate. `local`/`self`
+        // force a local run; a fleet-remote re-exec is already ON the target and
+        // falls through to the local launch below.
+        const deviceName = opts.device === 'local' || opts.device === 'self' ? undefined : opts.device;
+        if (deviceName) {
+            const lowered = deviceName.toLowerCase();
+            if (lowered === 'all' || lowered === 'auto') {
+                console.error(`--device ${deviceName} is not valid on \`agents browser start\`: a task lives on one device.\n` +
+                    `Next: agents browser start --task <name> --device <device>`);
+                process.exit(1);
+            }
+            if (!isSelfHost(deviceName) && !isFleetRemoteInvocation()) {
+                // Resolve the profile NAME (never a local browser auto-pick) so a
+                // named profile can still be validated against the target's
+                // declarations before we round-trip. A bare start carries no name to
+                // validate — the target picks its own default — so it forwards
+                // straight through, which is exactly what unblocks a browserless box.
+                // Only resolve when the caller actually named a profile: passing an
+                // undefined ref would let `resolveProfileRef` fall back to THIS box's
+                // configured/auto-detected default (matching the ~4 other call sites
+                // in this file), and validating that local name against the target
+                // re-introduces the exact false failure this reorder fixes.
+                const forwardProfile = opts.profile ? await resolveProfileRef(opts.profile) : undefined;
+                if (forwardProfile) {
+                    try {
+                        assertDeviceDeclaresProfile(deviceName, forwardProfile);
+                    }
+                    catch (err) {
+                        console.error(err instanceof Error ? err.message : String(err));
+                        process.exit(1);
+                    }
+                }
+                try {
+                    const result = await dispatchBrowserToDevice(deviceName, browserForwardedArgv(), 'capture');
+                    process.stdout.write(result.stdout);
+                    process.stderr.write(result.stderr);
+                    if (result.code !== 0)
+                        process.exit(result.code);
+                    const taskName = opts.task || result.stdout.trim().split('\n').find((line) => line.length > 0);
+                    if (!taskName) {
+                        console.error(`Remote start on ${deviceName} produced no task name.`);
+                        process.exit(1);
+                    }
+                    bindTask(taskName, {
+                        device: deviceName,
+                        // Only the caller-named profile; the target's own default (bare
+                        // start) is opaque here, exactly as in the hub path.
+                        profile: forwardProfile ?? opts.profile,
+                        url: opts.url,
+                        sessionId: callerSessionId(),
+                        launchId: callerLaunchId(),
+                        createdAt: Date.now(),
+                    });
+                    if (!result.stderr.includes(`started on ${deviceName}`)) {
+                        console.error(`Task "${taskName}" started on ${deviceName}.`);
+                    }
+                }
+                catch (err) {
+                    console.error(err instanceof Error ? err.message : String(err));
+                    process.exit(1);
+                }
+                return;
+            }
+        }
         // One resolution order for every command (RUSH-2709): `--profile default`
         // means the same profile here as it does in stop / status / navigate.
         // `start` is the one command that LAUNCHES, so its implicit path goes
         // through ensureDefaultBrowserProfile, which additionally verifies the
-        // resolved default can launch on THIS machine and regenerates it when it
-        // can't (the "Custom binary not found" repair) — a filter-only command
-        // must not warn or rewrite a profile, so that check lives only here.
+        // resolved default can launch on THIS machine and, when nothing launchable
+        // resolves, throws an actionable "pick a browser in `agents setup`" error
+        // (PHNX-3296 — it no longer silently mints an auto-chrome). A filter-only
+        // command must not warn about the config, so that check lives only here.
         let profileName;
         try {
             profileName = await resolveProfileRefForStart(opts.profile);
@@ -1409,14 +1558,12 @@ function registerTaskCommands(browser) {
                 process.exit(1);
             }
         }
-        const deviceName = opts.device;
+        // Only the LOCAL launch reaches here — an explicit remote --device already
+        // forwarded and returned above. A residual `deviceName` means an explicit
+        // self target (or a fleet-remote re-exec on the target); its profile
+        // resolved locally, so verify this box actually declares it (the
+        // `profiles claim` hint lives in `assertDeviceDeclaresProfile`).
         if (deviceName) {
-            const lowered = deviceName.toLowerCase();
-            if (lowered === 'all' || lowered === 'auto') {
-                console.error(`--device ${deviceName} is not valid on \`agents browser start\`: a task lives on one device.\n` +
-                    `Next: agents browser start --task <name> --device <device>`);
-                process.exit(1);
-            }
             try {
                 assertDeviceDeclaresProfile(deviceName, profileName);
             }
@@ -1424,36 +1571,6 @@ function registerTaskCommands(browser) {
                 console.error(err instanceof Error ? err.message : String(err));
                 process.exit(1);
             }
-            if (!isSelfHost(deviceName) && !isFleetRemoteInvocation()) {
-                try {
-                    const result = await dispatchBrowserToDevice(deviceName, browserForwardedArgv(), 'capture');
-                    process.stdout.write(result.stdout);
-                    process.stderr.write(result.stderr);
-                    if (result.code !== 0)
-                        process.exit(result.code);
-                    const taskName = opts.task || result.stdout.trim().split('\n').find((line) => line.length > 0);
-                    if (!taskName) {
-                        console.error(`Remote start on ${deviceName} produced no task name.`);
-                        process.exit(1);
-                    }
-                    bindTask(taskName, {
-                        device: deviceName,
-                        profile: profileName,
-                        url: opts.url,
-                        sessionId: callerSessionId(),
-                        launchId: callerLaunchId(),
-                        createdAt: Date.now(),
-                    });
-                    if (!result.stderr.includes(`started on ${deviceName}`)) {
-                        console.error(`Task "${taskName}" started on ${deviceName} (profile: ${profileName}).`);
-                    }
-                }
-                catch (err) {
-                    console.error(err instanceof Error ? err.message : String(err));
-                    process.exit(1);
-                }
-                return;
-            }
         }
         // Grounded login guardrail: if the opening URL is a known login-gated
         // service and the resolved profile has no session for it, say so on stderr
@@ -1566,11 +1683,31 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('stop')
-        .description('Stop a browser task and close its tabs; with --profile, detach the whole profile (close browser + drop cached connection)')
+        .description('Stop a browser task and close its tabs; with --profile, detach the whole profile (close browser + drop cached connection); with --daemon, stop the browser daemon and clear a wedged socket')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option(DEVICE_ON_PAGE_VERB_FLAG, DEVICE_ON_PAGE_VERB_DESC)
         .option('-p, --profile <name>', 'Detach the whole profile (incl. composite "name@endpoint") instead of stopping a single task')
+        .option('--daemon', 'Stop the browser daemon entirely and clear a stale/wedged socket so the next start comes up clean (recovery for "Timeout waiting for browser daemon socket")')
         .action(async (opts) => {
+        if (opts.daemon) {
+            if (opts.profile || opts.task) {
+                console.error('--daemon stops the whole browser daemon; do not combine it with --profile or --task.');
+                process.exit(1);
+            }
+            try {
+                const result = await resetBrowserDaemon();
+                const parts = [];
+                parts.push(result.wasRunning ? 'Stopped browser daemon' : 'Browser daemon was not running');
+                if (result.socketCleared)
+                    parts.push('cleared stale socket');
+                console.log(`${parts.join('; ')}. It restarts on the next browser command.`);
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                process.exit(1);
+            }
+            return;
+        }
         if (opts.profile) {
             const profile = (await resolveProfileRef(opts.profile)) ?? opts.profile;
             const response = await sendIPCRequest({

package/dist/commands/config.js

@@ -111,6 +111,11 @@ function setConfig(parsed, value) {
             return;
         }
         case 'browser': {
+            if (parsed.property === 'device') {
+                // Fleet hub: user scope, one central value, never peer-targeted.
+                setConfigValue('browser.device', value);
+                return;
+            }
             // Device-local default lives in the per-device doc's config: block
             // (same store `agents devices config` / getConfigValue use). Bare
             // browser.profile targets this machine; devices.<name>.browser.profile
@@ -155,6 +160,11 @@ function unsetConfig(parsed) {
             return had;
         }
         case 'browser': {
+            if (parsed.property === 'device') {
+                const had = getConfigValue('browser.device').value !== undefined;
+                unsetConfigValue('browser.device');
+                return had;
+            }
             const target = parsed.device ? { device: parsed.device } : undefined;
             // Must follow parsed.property. Hardcoding 'browser.profile' here meant
             // `config unset browser.viewer` deleted the user's browser.profile while
@@ -195,6 +205,9 @@ function getConfig(parsed) {
         case 'auto':
             return getConfigValue('auto.pool').value;
         case 'browser': {
+            if (parsed.property === 'device') {
+                return getConfigValue('browser.device').value;
+            }
             return getConfigValue(parsed.property === 'viewer' ? 'browser.viewer' : 'browser.profile', parsed.device ? { device: parsed.device } : undefined).value;
         }
         case 'project':
@@ -267,6 +280,13 @@ function* listCentralConfigEntries() {
         const key = 'browser.viewer';
         yield { key, value: browserViewer, hint: configKeyStorageHint(parseConfigKey(key)) };
     }
+    // Fleet browser hub — user scope, so it belongs in the central listing next to
+    // its siblings. Omitting it repeats the browser.viewer invisibility bug.
+    const browserDevice = getConfigValue('browser.device').value;
+    if (browserDevice !== undefined) {
+        const key = 'browser.device';
+        yield { key, value: browserDevice, hint: configKeyStorageHint(parseConfigKey(key)) };
+    }
 }
 /** Collect device-scope config entries. */
 function* listDeviceConfigEntries(device) {

package/dist/commands/daemon.d.ts

@@ -16,6 +16,8 @@
  */
 import type { Command } from 'commander';
 import { type DaemonServiceId } from '../lib/daemon-services.js';
+/** Elapsed wall-clock seconds since `pid` started, or null if unavailable (best-effort, POSIX only). */
+export declare function uptimeSeconds(pid: number): number | null;
 /** One row of the roster every registered daemon service — supervisor-managed or legacy — renders in `agents daemon services`. */
 export interface DaemonServiceRow {
     id: DaemonServiceId;

package/dist/commands/daemon.js

@@ -30,6 +30,7 @@ import { parseDuration } from '../lib/hooks/cache.js';
 import { registerFunnelCommand } from './funnel.js';
 import { DEFAULT_WEBHOOK_PORT, DEFAULT_WEBHOOK_RATE_LIMIT, addHostedReceiver, getDaemonWebhooksConfigPath, hostedReceiverPort, readDaemonWebhooksConfig, removeHostedReceiver, } from '../lib/daemon-webhooks.js';
 import { parseFunnelPort } from '../lib/funnel.js';
+import { parseEtimeToSeconds } from '../lib/secrets/reaper.js';
 /**
  * Provably absent, or null when unknowable.
  *
@@ -256,13 +257,16 @@ function registryScopedDuplicates(processes, ownerPid) {
     return processes.filter((p) => registered.has(p.pid));
 }
 /** Elapsed wall-clock seconds since `pid` started, or null if unavailable (best-effort, POSIX only). */
-function uptimeSeconds(pid) {
+export function uptimeSeconds(pid) {
     if (process.platform === 'win32')
         return null;
     try {
-        const out = execFileSync('ps', ['-o', 'etimes=', '-p', String(pid)], { encoding: 'utf-8' }).trim();
-        const n = parseInt(out, 10);
-        return isNaN(n) ? null : n;
+        // `-o etimes=` is a GNU/procps keyword macOS/BSD `ps` rejects with a
+        // non-zero exit (`ps: etimes: keyword not found`), so `agents daemon status`
+        // errored out entirely on macOS. `etime` (`[[dd-]hh:]mm:ss`) is the portable
+        // POSIX field; `parseEtimeToSeconds` (shared with the keychain reaper) parses it.
+        const out = execFileSync('ps', ['-o', 'etime=', '-p', String(pid)], { encoding: 'utf-8' }).trim();
+        return parseEtimeToSeconds(out);
     }
     catch {
         return null;

package/dist/commands/detach.js

@@ -123,7 +123,7 @@ function spawnHeadless(command, args, logFile) {
     });
 }
 export async function detachAction(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/feedback.js

@@ -7,7 +7,7 @@ import { arch, platform, release } from 'node:os';
 import { createRequire } from 'node:module';
 import chalk from 'chalk';
 import { showUrl } from '../lib/open-url.js';
-const REPO = 'phnx-labs/agents-cli';
+const REPO = 'phnx-labs/agi-cli';
 const DISCUSSION_BASE = `https://github.com/${REPO}/discussions/new`;
 const ISSUE_BASE = `https://github.com/${REPO}/issues/new`;
 function readCliVersion() {

package/dist/commands/focus.d.ts

@@ -16,6 +16,7 @@ import type { Command } from 'commander';
 import { probeAttachRail, type AttachRailLiveness, type UnreachableFallback } from './go.js';
 import { type ActiveSession } from '../lib/session/active.js';
 import { type SessionMeta } from '../lib/session/types.js';
+export { looksLikeTmuxAlias, resolveTmuxAliasState, shouldAttachLocalTmuxAliasBeforeFleet, type TmuxAliasState } from '../lib/session/local-tmux-attach.js';
 import { type LiveStatusFilter } from './sessions.js';
 import { openSurfaces, type Backend } from '../lib/terminal/index.js';
 /** Options for `sessions focus` — device scope + the `--active` live-state filters. */
@@ -99,16 +100,6 @@ export declare function isAttachableLiveSession(session: ActiveSession): boolean
  * ("Session transcript not available (file no longer exists). Path: ").
  */
 export declare function dedupeSessionsByLogicalId(rows: SessionMeta[], self?: string): SessionMeta[];
-export type TmuxAliasState = 'not-an-alias' | 'no-server' | 'absent' | 'dead' | 'live';
-/** Shape of the tmux alias the CLI mints for an agent session: `ag-<agent>-<shortid>`.
- * Delegates to the one canonical matcher beside the name parsers in active.ts. */
-export declare function looksLikeTmuxAlias(selector: string): boolean;
-/**
- * Classify a selector against the live tmux server. Split from the attach so the
- * decision is testable against a real tmux server without replacing the caller's
- * shell (attaching is not something a test can undo).
- */
-export declare function resolveTmuxAliasState(selector: string, socket?: string): Promise<TmuxAliasState>;
 /**
  * The session to focus once an id/identity selector has resolved across the
  * fleet. Prefer the already-gathered candidate-pool row (it carries the live

package/dist/commands/focus.js

@@ -17,8 +17,9 @@ import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
 import { gatherLiveTargets, pickLiveTarget, pickLiveTargets, jumpTo, probeAttachRail, refuseFallback } from './go.js';
 import { sessionProcessIsLocal, sessionProcessHost, shortIdFromName } from '../lib/session/active.js';
-import { attachTmux, ensureSessionHookRepaired, getDefaultSocketPath, hasSession, runTmux } from '../lib/tmux/index.js';
 import { isAgentTmuxAlias } from '../lib/session/types.js';
+import { attachLocalLiveSelector } from '../lib/session/local-tmux-attach.js';
+export { looksLikeTmuxAlias, resolveTmuxAliasState, shouldAttachLocalTmuxAliasBeforeFleet } from '../lib/session/local-tmux-attach.js';
 import { buildSessionRecoveryCommand, filterSessionsByQuery, formatLiveStatusHeadline, formatPickerLabel, isRunningLiveSession, pickerColumnsFor, resumeSessionInPlace, resolveSessionMetadataValue, resolveSessionAgentName, requestedLiveStatuses, } from './sessions.js';
 import { resolveBackend, CONFIRM_THRESHOLD } from './sessions-resume.js';
 import { runOnPeer } from '../lib/session/remote-list.js';
@@ -221,6 +222,18 @@ export async function focusAction(id, opts) {
             process.exitCode = 1;
             return;
         }
+        // A live local tmux alias — or a bare 8-hex short id naming exactly one
+        // live local pane — attaches immediately, before any fleet SSH.
+        // `collectSessionCandidates` fans out twice (transcript pool + live
+        // roster), so a selector that is already a pane on THIS box used to print
+        // two unreachable-device lists and stall on offline peers (~2 min measured
+        // on yosemite-s0 for `sessions resume ag-claude-0145ab8f --attach-only`)
+        // and only then attach. SES-41 / PHNX-3292: an alive `ag-<agent>-<8hex>`
+        // pane is attached by name; the pane is sufficient, no fleet SSH needed. A
+        // dead/absent pane falls through to id resolution.
+        if (await attachLocalLiveSelector(textSelector, hosts)) {
+            return;
+        }
         // RUSH-2477: an id selector for a LOCAL indexed session resolves against the
         // WAL index alone — a plain read, no write-heavy discovery scan (none of
         // `tryClaimScan`/`releaseScan`'s `BEGIN IMMEDIATE` writer lock) and no
@@ -268,12 +281,6 @@ export async function focusAction(id, opts) {
         let exact = idSelector
             ? dedupeSessionsByLogicalId(sessions.filter((session) => session.id.toLowerCase().startsWith(idSelector)), self)
             : [];
-        // A tmux alias naming a LIVE local session attaches directly. This must run
-        // before the metadata resolver: that resolver treats an unmatched alias as a
-        // keyword query, so `ag-kimi-632c1fbc` came back as 13 unrelated text hits
-        // while the pane was alive and attachable the whole time.
-        if (exact.length === 0 && textSelector && !hosts.length && await attachLiveTmuxAlias(textSelector))
-            return;
         // Not live (or remote-scoped): an alias still carries the session's shortid,
         // so resolve by THAT rather than handing the whole `ag-<agent>-<shortid>`
         // string to the resolver — which treats an unmatched alias as a keyword
@@ -396,25 +403,6 @@ function looksLikeIdentitySelector(selector) {
     return !!selector && (/^[0-9a-f][0-9a-f-]{5,}$/i.test(selector) ||
         isAgentTmuxAlias(selector));
 }
-/**
- * Attach a live tmux session named exactly as the selector, without needing the
- * session index to know anything about it.
- *
- * SES-41 requires a `ag-<agent>-<8hex>` tmux alias to resolve, but the alias's
- * hex is the LAUNCH id, not the harness session id, and for a harness that
- * writes no `state/sessions/<pid>.json` record there is no mapping back to a
- * SessionMeta at all. Measured on yosemite-s0: `--resolve ag-kimi-632c1fbc`
- * fell through to a keyword search and returned 13 unrelated rows, while the
- * pane itself was alive (`%124`, `kimi-code`). The pane is the thing the user
- * asked for, and its NAME is sufficient to attach it — so an unattributable
- * session is still reachable instead of being a dead end that forces raw
- * `tmux -S … attach`.
- *
- * Returns false when this is not an alias, the server/session is absent, or
- * every pane is dead — the caller then continues to normal id resolution.
- * SES-39's "re-read `pane_dead` immediately before attach" is honoured here:
- * liveness is queried at attach time, not read from the roster.
- */
 /**
  * Rank two rows that are the same logical session, best first.
  *
@@ -447,59 +435,6 @@ export function dedupeSessionsByLogicalId(rows, self) {
     }
     return [...byId.values()];
 }
-/** Shape of the tmux alias the CLI mints for an agent session: `ag-<agent>-<shortid>`.
- * Delegates to the one canonical matcher beside the name parsers in active.ts. */
-export function looksLikeTmuxAlias(selector) {
-    return isAgentTmuxAlias(selector);
-}
-/**
- * Classify a selector against the live tmux server. Split from the attach so the
- * decision is testable against a real tmux server without replacing the caller's
- * shell (attaching is not something a test can undo).
- */
-export async function resolveTmuxAliasState(selector, socket) {
-    if (!looksLikeTmuxAlias(selector))
-        return 'not-an-alias';
-    const sock = socket ?? getDefaultSocketPath();
-    if (!fs.existsSync(sock))
-        return 'no-server';
-    if (!(await hasSession(selector, sock).catch(() => false)))
-        return 'absent';
-    const panes = await runTmux({
-        socket: sock,
-        args: ['list-panes', '-t', `=${selector}`, '-F', '#{pane_dead}'],
-    }).catch(() => undefined);
-    const states = (panes?.stdout ?? '').split('\n').map(s => s.trim()).filter(Boolean);
-    return states.some(d => d === '0') ? 'live' : 'dead';
-}
-async function attachLiveTmuxAlias(selector) {
-    const socket = getDefaultSocketPath();
-    if (await resolveTmuxAliasState(selector, socket) !== 'live')
-        return false;
-    if (!process.stdout.isTTY) {
-        console.error(chalk.red(`"${selector}" is a live tmux session, but attaching needs a TTY.`));
-        console.error(chalk.gray(`  Run it from a terminal, or: agents tmux attach ${selector}`));
-        process.exitCode = 1;
-        return true;
-    }
-    // Already inside a tmux client on this socket — which is the normal state for
-    // an interactive agent session here — MOVE that client instead of nesting a
-    // second one. jumpTo (go.ts) does the same; attaching from inside tmux
-    // otherwise stacks clients rather than taking you to the session.
-    if (process.env.TMUX) {
-        await runTmux({ socket, args: ['switch-client', '-t', `=${selector}`], throwOnError: false }).catch(() => { });
-        console.log(chalk.gray(`Switched this tmux client to ${selector}.`));
-        return true;
-    }
-    console.log(chalk.gray(`Attaching ${selector} — Ctrl-b d to detach.`));
-    // Repair a legacy/stale pane-died hook before handing the session to an
-    // attach client — the 5-min daemon reconcile that used to cover this was
-    // deleted; attach-time repair is what closes the gap now (RUSH-2435).
-    await ensureSessionHookRepaired(selector, socket);
-    const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${selector}`] });
-    process.exitCode = code;
-    return true;
-}
 function hasFocusFilters(opts, statuses) {
     return statuses.length > 0 || !!(opts.active || opts.local || opts.device?.length || focusOptionAgent(opts) ||
         opts.all || opts.teams || opts.inTeam || opts.routine || opts.project || opts.skill || opts.plugin ||