@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/commands/config.d.ts

@@ -5,7 +5,6 @@
  *   - run defaults (model, mode, effort)
  *   - tier overrides (folded into the run namespace)
  *   - interactive host
- *   - usage primary host
  *   - browser profile
  *   - local projects root
  *   - per-device config keys

package/dist/commands/config.js

@@ -5,7 +5,6 @@
  *   - run defaults (model, mode, effort)
  *   - tier overrides (folded into the run namespace)
  *   - interactive host
- *   - usage primary host
  *   - browser profile
  *   - local projects root
  *   - per-device config keys
@@ -40,8 +39,6 @@ function parseValue(key, parsed, raw) {
             return raw.trim();
         case 'interactive':
             return raw.trim();
-        case 'usage':
-            return raw.trim();
         case 'auto':
             return raw.trim();
         case 'browser':
@@ -109,10 +106,6 @@ function setConfig(parsed, value) {
             setConfigValue('interactive.host', value);
             return;
         }
-        case 'usage': {
-            setConfigValue('usage.primary-host', value);
-            return;
-        }
         case 'auto': {
             setConfigValue('auto.pool', value);
             return;
@@ -156,11 +149,6 @@ function unsetConfig(parsed) {
             unsetConfigValue('interactive.host');
             return had;
         }
-        case 'usage': {
-            const had = getConfigValue('usage.primary-host').value !== undefined;
-            unsetConfigValue('usage.primary-host');
-            return had;
-        }
         case 'auto': {
             const had = getConfigValue('auto.pool').value !== undefined;
             unsetConfigValue('auto.pool');
@@ -204,8 +192,6 @@ function getConfig(parsed) {
         }
         case 'interactive':
             return getConfigValue('interactive.host').value;
-        case 'usage':
-            return getConfigValue('usage.primary-host').value;
         case 'auto':
             return getConfigValue('auto.pool').value;
         case 'browser': {
@@ -263,9 +249,6 @@ function* listCentralConfigEntries() {
     if (meta.config?.interactiveHost !== undefined) {
         yield { key: 'interactive.host', value: meta.config.interactiveHost, hint: 'config.interactiveHost' };
     }
-    if (meta.config?.usagePrimaryHost !== undefined) {
-        yield { key: 'usage.primary-host', value: meta.config.usagePrimaryHost, hint: 'config.usagePrimaryHost' };
-    }
     if (meta.config?.autoPool !== undefined) {
         yield { key: 'auto.pool', value: meta.config.autoPool, hint: 'config.autoPool' };
     }
@@ -353,14 +336,11 @@ export function registerConfigCommand(program) {
       agents config set run.claude@2.1.45.model claude-opus-4-8
       agents config set run.claude@*.mode auto
       agents config set interactive.host zion
-      agents config set usage.primary-host zion
       agents config set browser.profile work
       agents config set project.root ~/src/github.com/<you>
       agents config set devices.mac-mini.max-agents 4
       agents config get run.claude@*.model
-      agents config get usage.primary-host
       agents config unset run.claude@*.tier.best
-      agents config unset usage.primary-host
       agents config list
       agents config budget
       agents config budget set per_day 50

package/dist/commands/daemon.d.ts

@@ -15,4 +15,25 @@
  * duplicating it.
  */
 import type { Command } from 'commander';
+import { type DaemonServiceId } from '../lib/daemon-services.js';
+/** One row of the roster every registered daemon service — supervisor-managed or legacy — renders in `agents daemon services`. */
+export interface DaemonServiceRow {
+    id: DaemonServiceId;
+    title: string;
+    description: string;
+    enabled: boolean;
+    /**
+     * `ServiceSupervisor`'s real lifecycle state when `supervised` is true
+     * (`idle`/`running`/`parked`/`stopped`, written cross-process via
+     * `recordSubsystemState`). A legacy `setInterval`-driven service has no such
+     * record, so its state is inferred from `enabled` + whether the daemon
+     * process is up — labelled distinctly so a reader can't mistake it for a
+     * measured value.
+     */
+    state: string;
+    supervised: boolean;
+    lastRunMs: number | null;
+    lastError: string | null;
+    consecutiveFailures: number;
+}
 export declare function registerDaemonCommand(program: Command): void;

package/dist/commands/daemon.js

@@ -21,8 +21,8 @@ import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
 import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, getDaemonLogPath, isDaemonAutostartCircuitOpen, } from '../lib/daemon/daemon.js';
 import { getConfigValue, setConfigValue, isDaemonEnabled } from '../lib/device-config.js';
-import { readSubsystemHealth, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC, SUBSYSTEM_DAEMON_START, } from '../lib/daemon-health.js';
-import { DAEMON_SERVICE_IDS, listDaemonServiceStates, setDaemonServiceEnabled, getDaemonServicesConfigPath, } from '../lib/daemon-services.js';
+import { readSubsystemHealth, readAllSubsystemHealth, SUBSYSTEM_SECRETS_BROKER, SUBSYSTEM_BROWSER_IPC, SUBSYSTEM_DAEMON_START, } from '../lib/daemon-health.js';
+import { DAEMON_SERVICE_IDS, listDaemonServiceStates, setDaemonServiceEnabled, getDaemonServicesConfigPath, queueDaemonServiceRestart, } from '../lib/daemon-services.js';
 import { listJobs, getLatestRun } from '../lib/scheduling/routines.js';
 import { JobScheduler } from '../lib/scheduler.js';
 import { followFile } from '../lib/log-follow.js';
@@ -474,19 +474,76 @@ async function runStatus(opts) {
         console.log(chalk.red('\nThe daemon is wedged (heartbeat stale). Restart: agents daemon restart'));
     }
 }
+/**
+ * Combine the persisted enable/disable toggles with whatever health the
+ * `ServiceSupervisor` (or a legacy subsystem) has reported. Pure — reads two
+ * on-disk files, makes no probes — so it's cheap to call from both the
+ * non-interactive renderer and the interactive picker's refresh tick.
+ */
+function buildServiceRows(daemonRunning) {
+    const states = listDaemonServiceStates();
+    const healthById = new Map(readAllSubsystemHealth().map((h) => [h.subsystem, h]));
+    return states.map((s) => {
+        const h = healthById.get(s.id);
+        const supervised = h?.state !== undefined;
+        // A persisted supervisor state (health.json) is only trustworthy while the
+        // daemon is actually up. If it is not running (crash / kill -9 / never
+        // started), every service is stopped no matter what the last-written record
+        // says — trusting a stale 'running'/'parked'/'idle' here would print a
+        // report that contradicts the live-probed socket rows below (RUSH-2368).
+        const state = daemonRunning
+            ? (h?.state ?? (s.enabled ? 'running (unsupervised)' : 'stopped'))
+            : 'stopped';
+        return {
+            id: s.id,
+            title: s.title,
+            description: s.description,
+            enabled: s.enabled,
+            state,
+            supervised,
+            lastRunMs: h?.lastOkAt ? Date.parse(h.lastOkAt) : null,
+            lastError: h?.lastError ?? null,
+            consecutiveFailures: h?.consecutiveFailures ?? 0,
+        };
+    });
+}
+function serviceStateLabel(state) {
+    if (state === 'running')
+        return chalk.green('running');
+    if (state === 'parked')
+        return chalk.red('parked');
+    if (state === 'stopped')
+        return chalk.gray('stopped');
+    if (state === 'idle')
+        return chalk.gray('idle');
+    return chalk.yellow(state); // 'running (unsupervised)' or any future label
+}
 async function runServices(opts) {
     const [secrets, browserIpc] = await Promise.all([probeSecretsBroker(), probeBrowserIPC()]);
+    const rows = buildServiceRows(isDaemonRunning());
     if (opts.json) {
         console.log(JSON.stringify({
+            // Existing fields — unchanged shape, agents/CI consume these directly.
             secretsBroker: { reachable: secrets.reachable, socketPath: secrets.socketPath, heldBundles: secrets.heldBundles, health: secrets.record },
             browserIpc: { bound: browserIpc.bound, socketPath: browserIpc.socketPath, sessionCount: browserIpc.sessionCount, health: browserIpc.record },
+            // Additive: every registered service, supervised or legacy.
+            services: rows,
         }, null, 2));
         return;
     }
-    console.log(chalk.bold('Hosted services\n'));
+    console.log(chalk.bold('Daemon services\n'));
+    for (const row of rows) {
+        const lastRun = row.lastRunMs ? new Date(row.lastRunMs).toLocaleString() : '-';
+        console.log(`  ${row.id.padEnd(16)} ${serviceStateLabel(row.state).padEnd(20)} `
+            + `enabled=${row.enabled ? 'yes' : 'no '}  fails=${row.consecutiveFailures}  last-run=${lastRun}`);
+        if (row.lastError)
+            console.log(chalk.gray(`    last-error: ${row.lastError}`));
+    }
+    console.log(chalk.bold('\nHosted sockets\n'));
     console.log(healthLine(`secrets broker  ${secrets.reachable ? `(${secrets.socketPath}, ${secrets.heldBundles} bundle(s) held)` : '(unreachable)'}`, secrets.reachable, secrets.record));
     console.log(healthLine(`browser IPC     ${browserIpc.bound ? `(${browserIpc.socketPath}, ${browserIpc.sessionCount} session(s))` : '(unbound)'}`, browserIpc.bound, browserIpc.record));
     console.log(chalk.gray('\nScheduled routines run through `agents routines` — see: agents routines stats'));
+    console.log(chalk.gray('agents daemon services enable|disable|restart <id> apply live for supervised services.'));
 }
 function parseLogLines(raw) {
     const out = [];
@@ -795,9 +852,17 @@ export function registerDaemonCommand(program) {
       # Reload config (SIGHUP) without restarting — picks up routine/scheduler-gate changes
       agents daemon reload
 
-      # Every hosted service (secrets broker, browser IPC, webhook receiver, ...)
+      # Every registered service — state, enabled, failures, last error
       agents daemon services
 
+      # Toggle or restart a service live — applies without a daemon restart
+      # for supervisor-managed services (secrets-broker, browser-ipc,
+      # account-state, session-index, monitors' off-transition, watchdog,
+      # device-probe, self-heal, keychain-reap, state-dir-check)
+      agents daemon services disable secrets-broker
+      agents daemon services enable secrets-broker
+      agents daemon services restart secrets-broker
+
       # Host a signed webhook receiver here, supervised and restarted on crash
       agents daemon webhooks add --secrets-bundle linear-webhook
       agents daemon webhooks list
@@ -821,6 +886,16 @@ export function registerDaemonCommand(program) {
       the daemon (daemon.enabled: false in ~/.agents/devices/<host>/agents.yaml).
       'agents daemon start' still starts it explicitly, same as
       'systemctl start' on a disabled unit.
+
+      'agents daemon services enable|disable|restart <id>' applies live (no
+      daemon restart) for the 10 supervisor-managed services: secrets-broker,
+      browser-ipc, account-state, session-index, monitors (off only — turning
+      monitors back on still needs a restart), watchdog, device-probe,
+      self-heal, keychain-reap, and state-dir-check. The other 2 services
+      (scheduler, webhook-receiver) are still bare interval/socket setups with
+      no live start/stop hook, so a toggle there — and 'enable' on any service
+      that was disabled at daemon boot — still needs 'agents daemon restart'.
+      'agents daemon services' names which case you're in per row.
     `,
     });
     cmd.command('status')
@@ -917,11 +992,38 @@ export function registerDaemonCommand(program) {
     });
     const servicesCmd = cmd
         .command('services')
-        .description('The hosted services: health, bound state, socket path, and per-service toggles.')
+        .description('Every registered daemon service: live health, enabled state, and live enable/disable/restart.')
         .option('--json', 'Emit as JSON')
         .action(async (opts, command) => {
         await runServices({ json: command.optsWithGlobals().json === true });
     });
+    setHelpSections(servicesCmd, {
+        examples: `
+      # State, enabled, consecutive failures, last error for every service
+      agents daemon services
+
+      # Machine-readable — additive: also carries the pre-existing
+      # secretsBroker/browserIpc hosted-socket fields
+      agents daemon services --json
+
+      # Just the enable/disable metadata, no health probe
+      agents daemon services list
+
+      # Toggle or restart live — no daemon restart for a supervisor-managed
+      # service (secrets-broker, browser-ipc, account-state, session-index)
+      agents daemon services disable secrets-broker
+      agents daemon services enable secrets-broker
+      agents daemon services restart secrets-broker
+    `,
+        notes: `
+      A service disabled at daemon boot was never registered on the
+      supervisor, so 'enable' on it — and any toggle/restart on the 2
+      services the supervisor doesn't manage yet (scheduler,
+      webhook-receiver) — falls back to 'restart the daemon to apply'. Each
+      row in the plain-text view names which case it is; 'supervised:
+      true/false' does the same in --json.
+    `,
+    });
     servicesCmd
         .command('list')
         .description('List every daemon service and whether it is enabled.')
@@ -947,9 +1049,28 @@ export function registerDaemonCommand(program) {
         console.log(chalk.gray(`\nConfig: ${getDaemonServicesConfigPath()}`));
         console.log(chalk.gray('Changes take effect on the next daemon reload or restart.'));
     });
+    /**
+     * Apply an enable/disable toggle live (RUSH-3193 P4): persist it, then signal
+     * the running daemon to reload — its handler diffs the toggle and drives
+     * `supervisor.start/stop(id)` for a supervised service, so no restart is
+     * needed for the 10 supervisor-managed services (secrets-broker,
+     * browser-ipc, account-state, session-index, monitors' off-transition,
+     * watchdog, device-probe, self-heal, keychain-reap, state-dir-check). The 2
+     * remaining `setInterval`/socket-driven services (scheduler,
+     * webhook-receiver) and monitors' on-transition still need a restart — the
+     * daemon's own reload log says so.
+     */
+    function applyServiceToggleLive(service) {
+        if (!isDaemonRunning())
+            return;
+        const ok = signalDaemonReload();
+        console.log(ok
+            ? chalk.gray('Signalled the daemon to apply live. Confirm: agents daemon services')
+            : chalk.yellow('Reload signal not delivered — restart the daemon to apply: agents daemon restart'));
+    }
     servicesCmd
         .command('enable <service>')
-        .description('Enable a daemon service.')
+        .description('Enable a daemon service. Applies live for supervised services; a legacy service needs a restart.')
         .action((service) => {
         if (!DAEMON_SERVICE_IDS.includes(service)) {
             console.error(chalk.red(`Unknown service '${service}'. Run 'agents daemon services list' for valid services.`));
@@ -957,13 +1078,11 @@ export function registerDaemonCommand(program) {
         }
         setDaemonServiceEnabled(service, true);
         console.log(chalk.green(`Enabled '${service}'.`));
-        if (isDaemonRunning()) {
-            console.log(chalk.gray('Run `agents daemon reload` (or restart) to apply.'));
-        }
+        applyServiceToggleLive(service);
     });
     servicesCmd
         .command('disable <service>')
-        .description('Disable a daemon service.')
+        .description('Disable a daemon service. Applies live for supervised services; a legacy service needs a restart.')
         .action((service) => {
         if (!DAEMON_SERVICE_IDS.includes(service)) {
             console.error(chalk.red(`Unknown service '${service}'. Run 'agents daemon services list' for valid services.`));
@@ -971,9 +1090,25 @@ export function registerDaemonCommand(program) {
         }
         setDaemonServiceEnabled(service, false);
         console.log(chalk.green(`Disabled '${service}'.`));
-        if (isDaemonRunning()) {
-            console.log(chalk.gray('Run `agents daemon reload` (or restart) to apply.'));
+        applyServiceToggleLive(service);
+    });
+    servicesCmd
+        .command('restart <service>')
+        .description('Restart a supervised daemon service live, right now, outside its normal backoff schedule.')
+        .action((service) => {
+        if (!DAEMON_SERVICE_IDS.includes(service)) {
+            console.error(chalk.red(`Unknown service '${service}'. Run 'agents daemon services list' for valid services.`));
+            process.exit(1);
         }
+        if (!isDaemonRunning()) {
+            console.log(chalk.yellow('Daemon is not running — nothing to restart. Start it: agents daemon start'));
+            process.exit(1);
+        }
+        queueDaemonServiceRestart(service);
+        const ok = signalDaemonReload();
+        console.log(ok
+            ? chalk.green(`Restart requested for '${service}'.`) + chalk.gray(' Confirm: agents daemon services')
+            : chalk.yellow('Reload signal not delivered (unsupported on this platform, or the daemon just exited).'));
     });
     registerWebhooksSubcommand(cmd);
     registerFunnelCommand(cmd);

package/dist/commands/exec.js

@@ -508,7 +508,7 @@ export function registerRunCommand(program) {
         .option('--no-auth-check', 'Skip the pre-launch "looks logged out" warning on an interactive run (advisory; never blocks anyway). Also silenced by AGENTS_NO_AUTH_CHECK=1.')
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
         .option('--broadcast', 'Run the same prompt or --task across multiple agents (comma-separated [agent]) × --model cells. Replaces the former `agents bench` group.')
-        .option('--task <id>', 'With --broadcast: house benchmark task id under apps/cli/bench/tasks/')
+        .option('--task <id>', 'With --broadcast: house benchmark task id under cli/bench/tasks/')
         .option('--list-tasks', 'With --broadcast: list available broadcast task ids')
         .option('--results [run-id]', 'With --broadcast: show one saved matrix run, or list saved runs newest first')
         .option('--concurrency <n>', 'With --broadcast: maximum cells running at once', '3')
@@ -1501,6 +1501,19 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     if (process.env.AGENTS_DISPATCH_DEBUG || options.verbose) {
                         process.stderr.write(chalk.gray(`[hosts] dispatch interactive ${runAgent}${runVersion ? `@${runVersion}` : ''} -> ${host.name}\n`));
                     }
+                    {
+                        const { connectionStartedNotice, startConnectionTarget } = await import('../lib/hosts/reconnect.js');
+                        const startTarget = startConnectionTarget({
+                            agent: runAgent,
+                            hostSessionId,
+                            resumeId,
+                        });
+                        if (startTarget) {
+                            const started = connectionStartedNotice(startTarget, host.name);
+                            if (started)
+                                process.stderr.write(chalk.gray(started));
+                        }
+                    }
                     const exitCode = await runInteractiveOnHost(host, {
                         agent: runAgent,
                         version: resumeId ? undefined : runVersion,
@@ -1565,19 +1578,32 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     // `raw` runs aren't tmux wrapped, so there is nothing to reconnect to.
                     // For `run auto` prefer the join-resolved id (the harness the remote
                     // ACTUALLY picked) over the explicit --session-id only claude adopts.
-                    const reconnectId = (runAgent === RUN_AUTO_KEYWORD
-                        ? resolvedRemoteId ?? hostSessionId
-                        : hostSessionId ?? resolvedRemoteId) ?? resumeId;
-                    if (reconnectId && !isRaw) {
-                        const { reconnectInteractiveSession, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
-                        if (exitCode === SSH_CONN_FAILURE) {
-                            process.exit(await reconnectInteractiveSession({
-                                host,
-                                sessionId: reconnectId,
-                                initialExit: exitCode,
-                            }));
-                        }
+                    const { pickReconnectTarget, reconnectInteractiveSession, afterInteractiveRemoteExit, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
+                    const reconnectTarget = pickReconnectTarget({
+                        agent: runAgent,
+                        sessionId: hostSessionId,
+                        resolvedId: resolvedRemoteId,
+                        resumeId,
+                        launchId: correlationLaunchId,
+                    });
+                    // Raw is not tmux-wrapped, so it never auto-reconnects — but it
+                    // still prints the session id (EXEC-55). Bundling the notice
+                    // behind `!isRaw` left a dropped `--raw` tab as a bare shell.
+                    const next = afterInteractiveRemoteExit({
+                        target: reconnectTarget,
+                        host: host.name,
+                        exitCode,
+                        willReconnect: exitCode === SSH_CONN_FAILURE && !isRaw,
+                    });
+                    if (next.reconnect && reconnectTarget) {
+                        process.exit(await reconnectInteractiveSession({
+                            host,
+                            target: reconnectTarget,
+                            initialExit: exitCode,
+                        }));
                     }
+                    if (next.notice)
+                        process.stderr.write(next.notice);
                     process.exit(exitCode);
                 }
                 // Headless host run: launch detached, tail the remote log, and follow
@@ -2268,7 +2294,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 const peer = sessionRecoveryPeer(session);
                 if (peer) {
                     const { runOnPeer } = await import('../lib/session/remote-list.js');
-                    const routed = await runOnPeer(sessionRecoveryRunArgs(session), peer, { tty: true });
+                    const routed = await runOnPeer(sessionRecoveryRunArgs(session), peer, { tty: true, sessionId: session.id });
                     if (routed === 'no-target') {
                         console.error(chalk.red(`Cannot recover session ${session.shortId}: origin device ${peer} is not a registered reachable peer.`));
                         process.exitCode = 1;
@@ -2523,7 +2549,18 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 try {
                     const { getAccountInfo } = await import('../lib/agents.js');
                     const info = await getAccountInfo(agent);
-                    if (!info.signedIn) {
+                    // Claude authenticates interactively from a per-version setup-token on a
+                    // keychain-less worker (the shim's .oauth_token fallback), which the
+                    // native-credential probe above can't see — so don't warn "logged out" when
+                    // a setup-token resolves for this version. No-op on macOS, where the
+                    // credential lives in the keychain and resolveClaudeSetupToken returns null.
+                    let authedViaSetupToken = false;
+                    if (!info.signedIn && agent === 'claude' && version) {
+                        const { resolveClaudeSetupToken } = await import('../lib/claude-account-token.js');
+                        const { getVersionHomePath } = await import('../lib/installations/versions.js');
+                        authedViaSetupToken = resolveClaudeSetupToken(getVersionHomePath('claude', version)) !== null;
+                    }
+                    if (!info.signedIn && !authedViaSetupToken) {
                         process.stderr.write(chalk.yellow(`⚠  ${agent} looks logged out — log in with: ${loginHint(agent)}. Launching anyway...\n`));
                     }
                 }

package/dist/commands/focus.d.ts

@@ -20,6 +20,19 @@ 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. */
 export interface FocusOptions {
+    /**
+     * Resolve the target from the launcher's AGENT_LAUNCH_ID instead of a session
+     * id (RUSH-3125).
+     *
+     * A `--device` launcher mints this id BEFORE it opens the connection and
+     * forwards it, so it is the one handle that is still known after the link
+     * dies. A session id is not: only Claude is handed one up front, and every
+     * other harness's real id had to be read back off the peer — over the very
+     * link that just dropped — which is why a blink left a Grok or Codex tab with
+     * nothing to reconnect to. The lookup runs HERE, on the box that owns the hook
+     * records, so it needs no network at the moment it is needed most.
+     */
+    launchId?: string;
     local?: boolean;
     attachOnly?: boolean;
     device?: string[];
@@ -54,6 +67,7 @@ export interface FocusOptions {
     abandoned?: boolean;
     queued?: boolean;
     unknown?: boolean;
+    reconnectReattach?: boolean;
 }
 /** Commander gives overlapping `sessions` flags to the parent command, even
  * when they appear after `focus`. Fold only values explicitly provided there

package/dist/commands/focus.js

@@ -80,8 +80,10 @@ export function registerFocusCommand(program) {
         // console.warn here without first removing that delegation.
         .command('focus', { hidden: true })
         .argument('[selector]', 'Session id/prefix, agent@version, or topic/path search')
+        .option('--launch-id <id>', 'Target the run by its launcher AGENT_LAUNCH_ID instead of a session id (resolved from this machine\'s hook records)')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
         .option('--attach-only', 'Attach only — never open a new tab / resume a copy (the old `go` behavior)')
+        .option('--reconnect-reattach', '(internal) Set by the reconnect loop — warns when the expected pane is dead and a fresh copy starts instead', false)
         .option('-D, --device <target...>', 'Scope the picker to live sessions on these devices (device alias from `agents devices`, user@host; repeatable)')
         .option('--active', 'Only sessions present in the live roster')
         .option('-a, --agent <agent>', 'Filter by harness and recorded version (for example claude@latest)')
@@ -162,6 +164,38 @@ export function selectFallback(attachOnly) {
     return attachOnly ? refuseFallback : resumeInNewTab;
 }
 export async function focusAction(id, opts) {
+    // RUSH-3125: `--launch-id` names the run by the handle its launcher minted,
+    // and this box holds the hook record that maps it to the real session id — a
+    // local read, so it still works when the network that started the run is gone.
+    // Resolved up front into the ordinary id path: everything below, including the
+    // attach-else-resume recovery, is identical once we know which session it is.
+    if (opts.launchId) {
+        if (id) {
+            console.error(chalk.red('Pass a session id or --launch-id, not both — they name the same thing two ways.'));
+            process.exitCode = 1;
+            return;
+        }
+        // Read the launch-id index directly rather than through
+        // `resolveHookSessionRecord`: that helper kind-guards every hit, which exists
+        // to stop a REUSED PID crossing harnesses. A launch id is a per-launch uuid
+        // and cannot collide, and the caller here is a reattach that deliberately
+        // does not assume which harness the peer picked (`run auto` chooses it
+        // remotely), so demanding a kind would reject the exact case this serves.
+        const { loadHookSessionIndex } = await import('../lib/session/hook-sessions.js');
+        const resolved = loadHookSessionIndex().byLaunchId.get(opts.launchId)?.session_id;
+        if (!resolved) {
+            // Fail loud: a launch id with no record means the harness never got far
+            // enough to write one (it died at startup, or it has no SessionStart
+            // hook). Silently opening the picker here would strand an automated
+            // reattach in an interactive prompt nobody is watching.
+            console.error(chalk.red(`No session recorded for launch id ${opts.launchId} on ${machineId()}.`));
+            console.error(chalk.gray('  The run may have failed before its SessionStart hook fired.'));
+            console.error(chalk.gray('  Look for it:  agents sessions --active'));
+            process.exitCode = 1;
+            return;
+        }
+        id = resolved;
+    }
     const hosts = mergeFocusHosts(opts);
     const statuses = requestedLiveStatuses(opts);
     // A device scope needs the cross-host sweep; --local only wins when no host is named.
@@ -204,7 +238,7 @@ export async function focusAction(id, opts) {
                 // still joined instead of resumed as a copy; a crashed session has no live
                 // row and recovers in place.
                 const { activeById } = await gatherLiveTargets(true, { statuses: [] });
-                await focusResolvedSession(localMatch[0], activeById, self, fallback, opts.attachOnly === true);
+                await focusResolvedSession(localMatch[0], activeById, self, fallback, opts.attachOnly === true, opts.reconnectReattach === true);
                 return;
             }
         }
@@ -290,7 +324,7 @@ export async function focusAction(id, opts) {
             exact = [focusTargetForResolved(filteredMatch, outcome.session)];
         }
         if (exact.length === 1) {
-            await focusResolvedSession(exact[0], liveById, self, fallback, opts.attachOnly === true);
+            await focusResolvedSession(exact[0], liveById, self, fallback, opts.attachOnly === true, opts.reconnectReattach === true);
             return;
         }
         if (exact.length > 1) {
@@ -524,7 +558,7 @@ async function pickFocusCandidates(sessions, liveById, initialSearch) {
 export function focusTargetForResolved(poolMatch, resolved) {
     return poolMatch ?? resolved;
 }
-async function focusResolvedSession(meta, liveById, self, fallback, attachOnly) {
+async function focusResolvedSession(meta, liveById, self, fallback, attachOnly, reconnectReattach = false) {
     const active = liveById.get(meta.id);
     if (active && isAttachableLiveSession(active)) {
         await jumpTo(active, self, fallback);
@@ -535,10 +569,19 @@ async function focusResolvedSession(meta, liveById, self, fallback, attachOnly)
         process.exitCode = 1;
         return;
     }
+    if (reconnectReattach) {
+        // The reconnect loop expected this pane to be alive. It isn't — the peer
+        // rebooted, tmux crashed, or the agent exited while the link was down.
+        // Warn before any recovery attempt (local resume OR remote hop) so the
+        // user always knows their original context was not directly recovered.
+        console.error(chalk.yellow(`\nWarning: ${meta.shortId}'s pane is gone (reboot, tmux crash, or agent exited).`));
+        console.error(chalk.gray(`  Prior context is in the transcript — starting recovery.\n` +
+            `  To see what happened: agents sessions preview ${meta.shortId}`));
+    }
     const remote = sessionProcessHost(meta, self);
     if (remote) {
         console.log(chalk.gray(`Recovering ${meta.shortId} on ${remote}…`));
-        const rc = await runOnPeer(sessionRecoveryRunArgs(meta), remote, { tty: true });
+        const rc = await runOnPeer(sessionRecoveryRunArgs(meta), remote, { tty: true, sessionId: meta.id });
         if (rc === 'no-target') {
             console.error(chalk.red(`Cannot recover ${meta.shortId}: ${remote} is unreachable.`));
             process.exitCode = 1;
@@ -765,7 +808,7 @@ const resumeInNewTab = async (s, remote) => {
     // it actually delivers you to the session (the peer picks the right version + HOME).
     if (remote) {
         console.log(chalk.gray(`${shortId(s)} has no live terminal on ${remote} — resuming it there over SSH…`));
-        const rc = await runOnPeer(sessionRecoveryRunArgs({ id }), remote, { tty: true });
+        const rc = await runOnPeer(sessionRecoveryRunArgs({ id }), remote, { tty: true, sessionId: id });
         if (rc === 'no-target') {
             console.log(chalk.red(`${remote} isn't reachable as a device. Try: agents devices sync`));
             console.log(chalk.gray(`  recovery must run on ${remote}, where the indexed session originated`));

package/dist/commands/go.d.ts

@@ -66,6 +66,9 @@ export interface Where {
     label: string;
     action: string;
 }
+/** What `jumpTo` writes after a remote tmux attach's SSH stream returns. Pure so
+ *  the ControlMaster close path is unit-tested without SSH (RUSH-3227). */
+export declare function remoteAttachEndedNotice(sessionId: string | undefined, host: string, code: number): string | undefined;
 /**
  * Pure, testable mirror of `jumpTo`'s path selection (jumpTo itself has side
  * effects — process.exit / ssh / osascript). Keep the branch ORDER in sync with

package/dist/commands/go.js

@@ -30,7 +30,8 @@ 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 { getDefaultSocketPath } from '../lib/tmux/paths.js';
-import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget, shellQuote, SSH_CONN_FAILURE_CODE } from '../lib/ssh-exec.js';
+import { connectionEndedNotice } from '../lib/hosts/reconnect.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 const execFileAsync = promisify(execFile);
 export function registerGoCommand(program) {
@@ -191,6 +192,13 @@ function synthMeta(s, self) {
 function shortId(s) {
     return (s.sessionId ?? '').slice(0, 8) || '-';
 }
+/** What `jumpTo` writes after a remote tmux attach's SSH stream returns. Pure so
+ *  the ControlMaster close path is unit-tested without SSH (RUSH-3227). */
+export function remoteAttachEndedNotice(sessionId, host, code) {
+    if (!sessionId)
+        return undefined;
+    return connectionEndedNotice({ kind: 'session', id: sessionId }, host, { dropped: code === SSH_CONN_FAILURE_CODE });
+}
 /**
  * Pure, testable mirror of `jumpTo`'s path selection (jumpTo itself has side
  * effects — process.exit / ssh / osascript). Keep the branch ORDER in sync with
@@ -276,8 +284,13 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
                 `sess=$(tmux ${sock}display-message -pt ${p} '#{session_name}' 2>/dev/null); ` +
                 `[ -n "$w" ] && tmux ${sock}select-window -t "$w" 2>/dev/null; ` +
                 `exec tmux ${sock}attach-session -t "\${sess:-${p}}"`;
-            console.log(chalk.gray(`Attaching ${shortId(s)} on ${remote} over SSH — Ctrl-b d to detach.`));
-            process.exit(sshStream(remote, remoteCmd, { tty: true }));
+            const attachId = s.sessionId || shortId(s);
+            console.log(chalk.gray(`Attaching ${attachId} on ${remote} over SSH — Ctrl-b d to detach.`));
+            const code = sshStream(remote, remoteCmd, { tty: true });
+            const notice = remoteAttachEndedNotice(s.sessionId, remote, code);
+            if (notice)
+                process.stderr.write(notice);
+            process.exit(code);
         }
         // Remote, not in tmux → hand off to the fallback (go: shell; focus: resume in a tab).
         await fallback(s, remote);

package/dist/commands/inspect.js

@@ -274,8 +274,8 @@ function isDotAgentsRoot(dir) {
     for (const kind of DRILLABLE_KINDS) {
         // `routines/` alone is NOT a marker. Shipping example routine YAML for
         // `agents routines add` is a documented pattern (this repo's own
-        // apps/cli/routines/), and that directory is the ONLY kind dir there — so
-        // counting it would make `agents inspect apps/cli` resolve a source tree as
+        // cli/routines/), and that directory is the ONLY kind dir there — so
+        // counting it would make `agents inspect cli` resolve a source tree as
         // a DotAgents repo. Same reasoning as the nested-`.agents/` case above.
         if (kind === 'routines')
             continue;