@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/devices/worker-pick.js

@@ -0,0 +1,113 @@
+/**
+ * Pick a worker device for offloaded machine work — the suite, a build, any job
+ * that pins a box for minutes and must never land on the machine someone is
+ * sitting at.
+ *
+ * This is deliberately NOT `resolveDeviceAuto`. That resolver answers "which box
+ * should run this AGENT", so it gates on harness installation and a launch-ready
+ * account (`smart-launch.ts:200-210`). A vitest run needs neither: it needs a
+ * reachable POSIX box with headroom. Gating a test offload on a signed-in Claude
+ * account would exclude a perfectly good worker for a reason that has nothing to
+ * do with running tests.
+ *
+ * What it DOES share, on purpose, is everything that decides *where agents may
+ * go*: the same {@link listOnlineDeviceNames} pool (so `role=worker` /
+ * `role=personal` marks move this surface too), the same
+ * {@link probePoolSignals} reachability+load probe (so one cached fleet probe
+ * serves both), and the same {@link pickBestDevice} least-loaded ranking. Before
+ * this module, `scripts/test.sh` hand-rolled its own resolver in inline Python
+ * and therefore could not offer `--device auto` at all.
+ */
+import { normalizeHost } from '../machine-id.js';
+import { localMachineId } from '../session/origin-machine.js';
+import { loadDevicesSync } from './registry.js';
+import { isAutoPoolMember } from './pool.js';
+import { formatEmptyAutoPoolError, listOnlineDeviceNames, } from '../smart-launch.js';
+import { pickBestDevice } from '../teams/scheduler.js';
+import { probePoolSignals } from '../teams/placement-probe.js';
+/**
+ * Platforms a bun/vitest offload can actually run on.
+ *
+ * Windows is excluded by policy, not by accident: `AGENTS.md` states Windows is
+ * not a required PR or ordinary-release platform and `tests.yml` runs it only as
+ * a `continue-on-error` post-merge smoke. Silently shipping the tree to
+ * `win-mini` would produce a confusing failure for a platform whose result
+ * nobody gates on.
+ */
+export const POSIX_PLATFORMS = ['linux', 'macos'];
+/**
+ * Resolve the least-loaded eligible worker.
+ *
+ * Throws — never returns a degraded answer. An offload helper that quietly
+ * decided "no worker, run here" would recreate exactly the failure the offload
+ * exists to prevent: the operator believes the work went to the fleet while
+ * their laptop is pinned. Callers surface the thrown message verbatim.
+ */
+export async function resolveWorkerDevice(opts = {}) {
+    const local = normalizeHost(opts.localMachine ?? localMachineId());
+    const pool = [...new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost))];
+    // The local box joins the pool only when a role does not exclude it — the same
+    // rule resolveDeviceAuto applies. A box marked `personal` is marked precisely
+    // so long jobs stay off it, and that mark must hold for the suite too.
+    if (!pool.includes(local) && isAutoPoolMember(local))
+        pool.push(local);
+    if (pool.length === 0)
+        throw new Error(formatEmptyAutoPoolError());
+    const excluded = [];
+    const wanted = new Set((opts.platforms ?? POSIX_PLATFORMS).map((p) => p.toLowerCase()));
+    const reg = loadDevicesSync();
+    const platformOf = (name) => {
+        const d = reg[name] ?? reg[normalizeHost(name)]
+            ?? Object.values(reg).find((p) => p && normalizeHost(p.name) === normalizeHost(name));
+        return d?.platform ? String(d.platform).toLowerCase() : undefined;
+    };
+    // Platform first: it is a static registry fact, so filtering here keeps the
+    // live probe off boxes that could never be picked anyway.
+    const onPlatform = pool.filter((device) => {
+        const platform = platformOf(device);
+        // Unknown platform stays a candidate — a registry-only box with no recorded
+        // platform is a gap in the registry, not positive evidence it is Windows.
+        if (platform && !wanted.has(platform)) {
+            excluded.push({ device, reason: 'wrong-platform' });
+            return false;
+        }
+        return true;
+    });
+    if (onPlatform.length === 0)
+        throw new Error(formatNoWorkerError(excluded, wanted));
+    const signals = await (opts.probe ?? ((p) => probePoolSignals(p)))(onPlatform);
+    const eligible = onPlatform.filter((device) => {
+        const signal = signals.get(device);
+        if (signal?.reachable !== true) {
+            excluded.push({ device, reason: 'unreachable' });
+            return false;
+        }
+        if (signal.headroom === 'loaded') {
+            excluded.push({ device, reason: 'overloaded' });
+            return false;
+        }
+        return true;
+    });
+    if (eligible.length === 0)
+        throw new Error(formatNoWorkerError(excluded, wanted));
+    const device = pickBestDevice(eligible, [], { signals });
+    return {
+        device,
+        isLocal: normalizeHost(device) === local,
+        candidates: onPlatform.map((key) => ({
+            device: key,
+            loadPercent: signals.get(key)?.loadPercent,
+            headroom: signals.get(key)?.headroom,
+        })),
+        excluded,
+    };
+}
+/** The one no-worker message, naming every candidate and why it was dropped. */
+export function formatNoWorkerError(excluded, platforms) {
+    const detail = excluded.length
+        ? excluded.map((e) => `${e.device} (${e.reason})`).join(', ')
+        : 'none';
+    return (`agents: no worker device is available for offloaded work `
+        + `[platforms: ${[...platforms].sort().join(', ')}] — excluded: ${detail}. `
+        + 'Mark a worker with `agents devices role <name> worker`, or name one explicitly.');
+}

package/dist/lib/exec.d.ts

@@ -94,6 +94,8 @@ export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 export interface ExecOptions {
     agent: AgentId;
     version?: string;
+    /** Version home whose native auth/config is overlaid onto this run's binary. */
+    configVersion?: string;
     /** Omit to launch the CLI interactively -- no prompt, no --print, stdio fully inherited. */
     prompt?: string;
     /** Force interactive mode even when a prompt is provided. Wins over `headless`. */
@@ -398,30 +400,67 @@ export interface TmuxWrapContext {
     raw: boolean;
     /** The AGENTS_NO_TMUX=1 escape hatch. */
     noTmuxEnv: boolean;
-    /** This device's `tmux.enabled` config — false turns the wrap off for every launch on this box. */
+    /** This device's `tmux.enabled` config — true opts every eligible launch on this box into the wrap. */
     configEnabled: boolean;
+    /**
+     * True when this run was dispatched onto this box over SSH by `--device`
+     * (the launcher exports {@link REMOTE_INTERACTIVE_ENV}).
+     *
+     * A remote interactive agent is a child of the sshd session and holds its
+     * controlling TTY, so without the wrap a dropped link SIGHUPs it and the work
+     * in flight is gone. Durability is therefore NOT a preference the way
+     * `configEnabled` is — `tmux.enabled` is about whether this box's operator
+     * likes tmux's mouse/clipboard/scrollback at their own keyboard, which says
+     * nothing about whether a run arriving over the network must outlive it.
+     * Conflating the two is what left every `--device` agent unsurvivable
+     * (RUSH-3125), while lib/hosts/reconnect.ts reconnected on the premise that
+     * they were detached.
+     */
+    remoteDispatch: boolean;
     /** Whether a tmux binary is on PATH. */
     tmuxAvailable: boolean;
 }
+/**
+ * What to do with an interactive spawn. Three outcomes, not two: a run that
+ * MUST be durable and cannot be is neither "wrap" nor "spawn bare" — it is a
+ * launch that should not happen, because a bare remote spawn looks fine right
+ * up until the link blinks and the agent dies with it.
+ */
+export type TmuxWrapDecision = 
+/** Run the agent in a detached tmux session and attach this TTY. */
+{
+    kind: 'wrap';
+}
+/** Spawn directly — nothing about this run needs a pane. */
+ | {
+    kind: 'bare';
+}
+/** Remote-dispatched and tmux is missing on this box: refuse, don't pretend. */
+ | {
+    kind: 'undurable';
+};
 /**
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
- * `agents sessions --active` can tell co-located agents apart, and lets `agents
- * focus` re-attach a live session without forking it. Pure so the gate is unit-
- * tested independently of the (side-effecting) spawn.
+ * Wrapping serves two independent purposes, and they are gated differently:
+ *
+ *  - **Addressability** (`configEnabled`): a unique `%pane` handle so
+ *    `agents sessions --active` can tell co-located agents apart and `agents
+ *    focus` re-attaches without forking. That is a local preference — the
+ *    operator turns it on once tmux's mouse/clipboard/scrollback suits them.
+ *  - **Durability** (`remoteDispatch`): a run that arrived over SSH must outlive
+ *    the SSH client, because a bare remote spawn dies of SIGHUP the moment the
+ *    link blinks. That is not a preference, so it does not consult
+ *    `configEnabled` (RUSH-3125 — see {@link TmuxWrapContext.remoteDispatch}).
  *
- * All seven guards must pass:
- *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
- *   - not Windows     — no tmux path on win32.
- *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
- *   - not --raw       — explicit opt-out.
- *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
- *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
- *   - tmux installed  — otherwise there is nothing to wrap with.
+ * The per-run opt-outs bind BOTH: `--raw` / `--no-tmux` / `AGENTS_NO_TMUX=1` are
+ * explicit "I want the bare process" requests, and honouring them over the
+ * durability rule keeps one escape hatch that always works.
+ *
+ * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
  */
-export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
+export declare function resolveTmuxWrap(ctx: TmuxWrapContext): TmuxWrapDecision;
 /**
  * Build the shell command that runs an agent inside a tmux pane with the exact
  * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
@@ -440,6 +479,23 @@ export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
  * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
  * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
+/**
+ * True when `options.sessionId` is an id the HARNESS actually received, and so a
+ * real, resumable handle — rather than one the launcher generated for its own
+ * bookkeeping and the agent never saw.
+ *
+ * Mirrors exactly the two branches in buildExecCommand that put the id on the
+ * command line: a native resume (any harness with a `resume` spec) and claude's
+ * create-with-`--session-id`. Everything else — `agents run codex --session-id X`
+ * without `--resume`, or a fresh non-claude launch whose real id only shows up
+ * later via the SessionStart hook — leaves the agent with an id of its own
+ * choosing, so `options.sessionId` must not be published as if it were that id.
+ *
+ * Keep in lockstep with buildExecCommand's resume/create branches: a harness
+ * that gains a forced-session-id flag must be reflected here in the SAME change,
+ * or this reports a genuine id as fabricated.
+ */
+export declare function isHarnessKnownSessionId(agent: AgentId, sessionId: string | undefined, resume: boolean | undefined): boolean;
 export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv, opts?: {
     redactEnvValues?: boolean;
     envFile?: string;

package/dist/lib/exec.js

@@ -8,7 +8,7 @@ import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { ALL_MODES } from './types.js';
+import { ALL_MODES, REMOTE_INTERACTIVE_ENV } from './types.js';
 import { AGENTS, findInPath } from './agents.js';
 import { parseTimeout } from './scheduling/routines.js';
 import { compareVersions, getBinaryPath, getVersionHomePath, isVersionInstalled, listInstalledVersions, resolveVersion } from './installations/versions.js';
@@ -28,7 +28,7 @@ import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
-import { isTmuxEnabled } from './device-config.js';
+import { isTmuxEnabled, selfConfiguredDeviceRole } from './device-config.js';
 import { machineId } from './machine-id.js';
 import { shellQuote } from './ssh-exec.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
@@ -293,17 +293,28 @@ export function buildExecEnv(options) {
         // Resolve version/versionHome here (this module already imports
         // installations/versions); the adapters must not import it themselves or they
         // close a versions -> shims -> harness -> adapter import cycle.
-        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.version);
+        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.configVersion ?? options.version);
         configAdapter.applyExecConfigEnv(result, {
             agent: options.agent,
             version,
             versionHome,
             interactive: resolveInteractive(options),
+            deviceRole: selfConfiguredDeviceRole(),
             resolveClaudeSetupToken,
         });
     }
     else {
         stripForeignConfigDir(result);
+        // Grok's adapter owns the same GROK_HOME export in generated shims, but a
+        // labeled account deliberately runs one version's binary with another
+        // version's config. Apply that overlay here because the shim's binary-slot
+        // export cannot express a distinct account slot.
+        if (options.agent === 'grok' && options.configVersion) {
+            const { versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.configVersion);
+            if (!versionHome)
+                throw new Error(`Cannot resolve Grok account config home for ${options.configVersion}.`);
+            result.GROK_HOME = path.join(versionHome, '.grok');
+        }
     }
     // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
     // knows which box to drain and inject mid-run. Keyed by the session id — the
@@ -322,6 +333,7 @@ export function buildExecEnv(options) {
     // every event the child emits. `options.sessionId` is the CHILD's id, so read the
     // spawner from the live env; guard a same-session resume from naming itself parent.
     // Local-spawn scope here; forwarding it across the `--device` SSH hop is Phase 4.
+    delete result.AGENTS_PARENT_SESSION_ID;
     const spawnerSessionId = process.env.AGENTS_SESSION_ID || process.env.AGENT_SESSION_ID;
     if (spawnerSessionId && spawnerSessionId !== options.sessionId) {
         result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
@@ -388,6 +400,7 @@ export const AGENT_COMMANDS = {
             // independent; legacy --sandbox flags cannot express that combination.
             plan: [],
             edit: [],
+            auto: [],
             // skip = codex --yolo: drops the sandbox entirely and approves anything.
             skip: ['--dangerously-bypass-approvals-and-sandbox'],
         },
@@ -1163,36 +1176,47 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
- * `agents sessions --active` can tell co-located agents apart, and lets `agents
- * focus` re-attach a live session without forking it. Pure so the gate is unit-
- * tested independently of the (side-effecting) spawn.
+ * Wrapping serves two independent purposes, and they are gated differently:
+ *
+ *  - **Addressability** (`configEnabled`): a unique `%pane` handle so
+ *    `agents sessions --active` can tell co-located agents apart and `agents
+ *    focus` re-attaches without forking. That is a local preference — the
+ *    operator turns it on once tmux's mouse/clipboard/scrollback suits them.
+ *  - **Durability** (`remoteDispatch`): a run that arrived over SSH must outlive
+ *    the SSH client, because a bare remote spawn dies of SIGHUP the moment the
+ *    link blinks. That is not a preference, so it does not consult
+ *    `configEnabled` (RUSH-3125 — see {@link TmuxWrapContext.remoteDispatch}).
+ *
+ * The per-run opt-outs bind BOTH: `--raw` / `--no-tmux` / `AGENTS_NO_TMUX=1` are
+ * explicit "I want the bare process" requests, and honouring them over the
+ * durability rule keeps one escape hatch that always works.
  *
- * All seven guards must pass:
- *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
- *   - not Windows     — no tmux path on win32.
- *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
- *   - not --raw       — explicit opt-out.
- *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
- *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
- *   - tmux installed  — otherwise there is nothing to wrap with.
+ * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
  */
-export function shouldWrapInTmux(ctx) {
+export function resolveTmuxWrap(ctx) {
+    // A headless `-p` run has no TTY to attach, Windows has no tmux path, and
+    // nesting tmux-in-tmux is pointless — none of these can wrap, and none of them
+    // is a remote interactive agent whose life depends on it.
     if (!ctx.interactive)
-        return false;
+        return { kind: 'bare' };
     if (ctx.platform === 'win32')
-        return false;
+        return { kind: 'bare' };
     if (ctx.inTmux)
-        return false;
+        return { kind: 'bare' };
+    // Explicit opt-outs win over the durability rule: `--raw` exists precisely to
+    // get the unwrapped process, and a flag that silently stopped working on a
+    // remote box would be worse than an undurable run the user asked for.
     if (ctx.raw)
-        return false;
+        return { kind: 'bare' };
     if (ctx.noTmuxEnv)
-        return false;
-    if (!ctx.configEnabled)
-        return false;
+        return { kind: 'bare' };
+    if (!ctx.configEnabled && !ctx.remoteDispatch)
+        return { kind: 'bare' };
+    // Fail loud rather than launch a remote agent that a blink would kill: the
+    // caller refuses the run instead of starting work that cannot be recovered.
     if (!ctx.tmuxAvailable)
-        return false;
-    return true;
+        return ctx.remoteDispatch ? { kind: 'undurable' } : { kind: 'bare' };
+    return { kind: 'wrap' };
 }
 /**
  * Build the shell command that runs an agent inside a tmux pane with the exact
@@ -1212,6 +1236,29 @@ export function shouldWrapInTmux(ctx) {
  * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
  * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
+/**
+ * True when `options.sessionId` is an id the HARNESS actually received, and so a
+ * real, resumable handle — rather than one the launcher generated for its own
+ * bookkeeping and the agent never saw.
+ *
+ * Mirrors exactly the two branches in buildExecCommand that put the id on the
+ * command line: a native resume (any harness with a `resume` spec) and claude's
+ * create-with-`--session-id`. Everything else — `agents run codex --session-id X`
+ * without `--resume`, or a fresh non-claude launch whose real id only shows up
+ * later via the SessionStart hook — leaves the agent with an id of its own
+ * choosing, so `options.sessionId` must not be published as if it were that id.
+ *
+ * Keep in lockstep with buildExecCommand's resume/create branches: a harness
+ * that gains a forced-session-id flag must be reflected here in the SAME change,
+ * or this reports a genuine id as fabricated.
+ */
+export function isHarnessKnownSessionId(agent, sessionId, resume) {
+    if (!sessionId)
+        return false;
+    if (resume && AGENT_COMMANDS[agent]?.resume)
+        return true;
+    return agent === 'claude';
+}
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     // envFile: source the values instead of inlining them, so no VALUE ever lands
@@ -1282,11 +1329,14 @@ export function formatPaneTail(raw, maxLines = 30) {
  * Lifecycle:
  *   1. createSession() launches `sh -c 'exec env … agent'` detached, remain-on-exit
  *      on (global), and returns the pane id.
- *   2. A per-session `pane-died` hook detaches the attach client the instant the
- *      AGENT pane exits, so attach returns instead of parking on a dead pane. The
- *      hook is guarded on `#{hook_pane}` so it fires ONLY for the agent pane —
- *      user-created splits (Ctrl-b " / %) that the user exits are closed in place
- *      (`kill-pane`) instead of tearing down the whole client, so exiting one
+ *   2. A per-session `pane-died` hook tears the session down the instant the AGENT
+ *      pane exits: with a client attached it `detach-client`s so attach returns
+ *      instead of parking on a dead pane (then resolveAfterAttach reads the status
+ *      and kills); with no client attached it `kill-session`s outright, so a
+ *      wrapped agent that exits unattended can't leave a dead husk lingering on the
+ *      socket. The hook is guarded on `#{hook_pane}` so it fires ONLY for the agent
+ *      pane — user-created splits (Ctrl-b " / %) that the user exits are closed in
+ *      place (`kill-pane`) instead of tearing down the whole client, so exiting one
  *      split leaves the agent running full-window rather than kicking you out.
  *   3. We record the agent pane's pid → session mapping (WITH the tmux pane) so the
  *      headless active-scan attributes it, then attach the TTY (blocking).
@@ -1303,7 +1353,7 @@ async function runInTmux(options, executable, args) {
     const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
     const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
-    const NO_TMUX_TIP = `${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.\n  If tmux is broken on this machine, turn the wrap off for good: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
+    const NO_TMUX_TIP = `${GRAY}  This run used the opt-in tmux wrap. Re-run with --no-tmux for a direct launch, or turn the wrap off: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
     // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
     // detaches the client the instant the agent exits, so a fast failure (a
     // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
@@ -1414,8 +1464,13 @@ async function runInTmux(options, executable, args) {
     const cmd = buildTmuxAgentCommand(executable, args, execEnv, { envFile });
     const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
-    if (options.sessionId)
+    // Only publish an id the harness actually received. createSession turns this
+    // label into the `@ag_session_id` tmux option that status bars read, and a
+    // launcher-internal id displayed there looks exactly like a resumable one
+    // while `ag focus <id>` rejects it.
+    if (isHarnessKnownSessionId(options.agent, options.sessionId, options.resume)) {
         labels.sessionId = options.sessionId;
+    }
     // Only a launched pane sources-and-unlinks the env file. If createSession
     // throws, the pane never runs, so the resolved secrets (incl. the master
     // passphrase) would linger on disk — remove it on that failure path
@@ -1600,19 +1655,36 @@ async function spawnAgent(options) {
         command: executable,
         args: redactArgs(args.slice(0, 10)),
     });
-    // Interactive spawn-wrap: on macOS/Linux, run the agent INSIDE a shared-socket
-    // tmux session (then attach this TTY) so it gets a unique, addressable %pane.
-    // Headless runs, Windows, already-in-tmux, --raw, and AGENTS_NO_TMUX=1 keep the
-    // bare spawn below. See shouldWrapInTmux / runInTmux.
-    if (shouldWrapInTmux({
+    // Interactive spawn-wrap: run the agent INSIDE a shared-socket tmux session
+    // (then attach this TTY) so it gets a unique, addressable %pane — and, when
+    // the run arrived over `--device`, so it survives the SSH link that carries
+    // it. Every failed guard keeps the bare spawn below.
+    const tmuxWrap = resolveTmuxWrap({
         interactive,
         platform: process.platform,
         inTmux: !!process.env.TMUX,
         raw: options.raw === true,
         noTmuxEnv: process.env.AGENTS_NO_TMUX === '1',
         configEnabled: isTmuxEnabled(),
+        remoteDispatch: process.env[REMOTE_INTERACTIVE_ENV] === '1',
         tmuxAvailable: isTmuxInstalled(),
-    })) {
+    });
+    if (tmuxWrap.kind === 'undurable') {
+        // Refuse rather than start work a blink would destroy. This is the ONLY
+        // check — `ensureHostReady` gates a `--device` dispatch on the peer being
+        // reachable and able to run the pinned agent, not on it having tmux, so
+        // there is no launcher-side probe ahead of this one. Failing here still
+        // fails before the agent starts, which is what matters; a pre-dispatch
+        // probe would only move the message earlier, at the cost of a round trip on
+        // every launch.
+        const msg = `agents: ${machineId()} has no tmux, so a --device run here could not survive a dropped connection.\n`
+            + `  install it:            (apt|dnf|brew) install tmux\n`
+            + `  or accept the risk:    agents run … --device ${machineId()} --raw\n`;
+        process.stderr.write(`\x1b[31m${msg}\x1b[0m`);
+        timer.end({ exitCode: 1, status: 'failed', error: 'remote interactive run has no tmux for durability' });
+        return { exitCode: 1, stdout: '', stderr: msg };
+    }
+    if (tmuxWrap.kind === 'wrap') {
         timer.mark('startup');
         try {
             const result = await runInTmux(options, executable, args);

package/dist/lib/feed/answer.d.ts

@@ -0,0 +1,29 @@
+import { type ActiveSession } from '../session/active.js';
+import { type MessageReceipt } from './feed.js';
+export interface VerifiedOperator {
+    id?: string;
+    verified: boolean;
+    label?: string;
+}
+export interface FeedAnswerResult {
+    status: 'delivered' | 'already_answered';
+    receipt: MessageReceipt;
+}
+/** Atomically claim the first answer, then route it over the session's recorded reply rail. */
+export declare function claimAndRouteAttentionAnswer(input: {
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operator: VerifiedOperator;
+    feedRoot?: string;
+    mailboxRoot?: string;
+    sessions?: ActiveSession[];
+}): Promise<FeedAnswerResult>;
+/** Forward a fleet attention answer to the device that owns its scope. */
+export declare function forwardFeedAnswer(input: {
+    host: string;
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operatorId?: string;
+}): Promise<FeedAnswerResult>;