@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/daemon-ticks.d.ts

@@ -67,8 +67,9 @@ export declare function runFleetCacheWarmTick(): Promise<void>;
 /**
  * Usage refresh: keep the usage cache the `agents run` router reads
  * (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
- * The configured primary host is the fleet's sole provider-facing writer;
- * subscribers import its token-free derived cache.
+ * Every host is its own provider-facing writer — it refreshes only the
+ * accounts it holds credentials for, straight from the provider APIs
+ * (RUSH-3193 #15; no cross-host broadcast).
  */
 export declare function runUsageRefreshTick(): Promise<void>;
 /**
@@ -79,9 +80,19 @@ export declare function runUsageRefreshTick(): Promise<void>;
  * Cadence matches {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS} so one-shot readers and
  * long-lived watchers share one writer. Without this tick the journal has no
  * continuous producer and Factory freezes after the initial cache snapshot.
+ *
+ * Gated on reader presence (RUSH-3193): when no `sessions watch` / `feed watch`
+ * consumer has checked in within {@link ACTIVE_SESSIONS_READER_IDLE_WINDOW_MS} the
+ * expensive `ps`+`lsof` gather is skipped entirely on this scheduled tick. A
+ * watcher connecting to a cold/idle daemon is NOT served by this tick alone —
+ * {@link noteActiveSessionsJournalReader} only writes a presence timestamp, with
+ * no path back to this timer — so the daemon separately runs
+ * {@link watchActiveSessionsReaderPresence} to detect that idle→recent edge and
+ * fire an out-of-band call into this same function immediately (RUSH-2484).
  */
 export declare function runActiveSessionsWarmTick(opts?: {
     gather?: () => Promise<import('./session/active.js').ActiveSession[]>;
+    nowMs?: number;
 }): Promise<{
     sessions: number;
 }>;

package/dist/lib/daemon-ticks.js

@@ -108,21 +108,11 @@ export async function runFleetCacheWarmTick() {
 /**
  * Usage refresh: keep the usage cache the `agents run` router reads
  * (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
- * The configured primary host is the fleet's sole provider-facing writer;
- * subscribers import its token-free derived cache.
+ * Every host is its own provider-facing writer — it refreshes only the
+ * accounts it holds credentials for, straight from the provider APIs
+ * (RUSH-3193 #15; no cross-host broadcast).
  */
 export async function runUsageRefreshTick() {
-    const { resolveUsagePrimaryHost } = await import('./device-config.js');
-    const { machineId } = await import('./machine-id.js');
-    // usage.primary-host, else interactive.host, else null (standalone local refresh)
-    const primaryHost = resolveUsagePrimaryHost() ?? undefined;
-    const self = machineId();
-    const { importUsageFleetFromHost, usageRefreshRole } = await import('./usage-fleet.js');
-    if (usageRefreshRole(primaryHost, self) === 'subscriber') {
-        const imported = await importUsageFleetFromHost(primaryHost);
-        console.log(`usage refresh: imported ${Object.keys(imported.usage).length} account(s) from primary host ${primaryHost}`);
-        return;
-    }
     const { runUsageRefresh, buildLocalUsageAccounts } = await import('./usage-refresh.js');
     const { writeClaudeUsageCache } = await import('./accounting/usage.js');
     const { usageRateLimitedUntil } = await import('./usage-backoff.js');
@@ -134,9 +124,7 @@ export async function runUsageRefreshTick() {
     const { listProfiles } = await import('./profiles.js');
     const { refreshDueByokUsage } = await import('./byok-usage.js');
     const byok = await refreshDueByokUsage(listProfiles());
-    const { exportUsageFleet } = await import('./usage-fleet.js');
-    const published = exportUsageFleet();
-    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due; published ${Object.keys(published.usage).length} account(s)`);
+    console.log(`usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped; BYOK ${byok.refreshed} refreshed, ${byok.skipped} not-due`);
 }
 /**
  * Active-sessions warm (RUSH-2062 / RUSH-2484): publish THIS host's live session
@@ -146,10 +134,24 @@ export async function runUsageRefreshTick() {
  * Cadence matches {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS} so one-shot readers and
  * long-lived watchers share one writer. Without this tick the journal has no
  * continuous producer and Factory freezes after the initial cache snapshot.
+ *
+ * Gated on reader presence (RUSH-3193): when no `sessions watch` / `feed watch`
+ * consumer has checked in within {@link ACTIVE_SESSIONS_READER_IDLE_WINDOW_MS} the
+ * expensive `ps`+`lsof` gather is skipped entirely on this scheduled tick. A
+ * watcher connecting to a cold/idle daemon is NOT served by this tick alone —
+ * {@link noteActiveSessionsJournalReader} only writes a presence timestamp, with
+ * no path back to this timer — so the daemon separately runs
+ * {@link watchActiveSessionsReaderPresence} to detect that idle→recent edge and
+ * fire an out-of-band call into this same function immediately (RUSH-2484).
  */
 export async function runActiveSessionsWarmTick(opts = {}) {
-    const { publishLocalActiveSessions } = await import('./session/session-cache.js');
-    const r = await publishLocalActiveSessions({ gather: opts.gather });
+    const { publishLocalActiveSessions, isActiveSessionsJournalReaderRecent } = await import('./session/session-cache.js');
+    const nowMs = opts.nowMs ?? Date.now();
+    if (!isActiveSessionsJournalReaderRecent(nowMs)) {
+        console.log('active-sessions warm: idle (no recent reader), skipping gather');
+        return { sessions: 0 };
+    }
+    const r = await publishLocalActiveSessions({ gather: opts.gather, nowMs });
     console.log(`active-sessions warm: ${r.sessions.length} session(s) published`);
     return { sessions: r.sessions.length };
 }

package/dist/lib/device-config.d.ts

@@ -124,8 +124,6 @@ export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
 /** List user-scope config keys with their values. Used to show inherited settings
  * in per-device views without implying those keys are device-local. */
 export declare function listUserConfig(): ConfigEntry[];
-/** Resolve the explicit usage host, falling back to the user's interactive host. */
-export declare function resolveUsagePrimaryHost(): string | null;
 /**
  * Set a config key (validated). Device-scope keys target this machine unless
  * `opts.device` names a peer; `opts.fleet` writes the fleet-wide defaults layer

package/dist/lib/device-config.js

@@ -61,22 +61,6 @@ export const CONFIG_KEYS = [
             }
         },
     },
-    {
-        name: 'usage.primary-host',
-        yamlKey: 'usagePrimaryHost',
-        scope: 'user',
-        type: 'string',
-        description: 'Device whose usage snapshots are authoritative for fleet-wide usage reporting.',
-        validate: (v) => {
-            try {
-                assertRegistrableDeviceName(v);
-                return null;
-            }
-            catch (err) {
-                return err?.message ?? String(err);
-            }
-        },
-    },
     {
         name: 'auto.pool',
         yamlKey: 'autoPool',
@@ -181,7 +165,7 @@ export const CONFIG_KEYS = [
         description: 'Minutes a browser task may sit with no IPC action (navigate, click, type, screenshot, …) before the daemon\'s ' +
             'abandoned-task reaper closes its tabs and marks it done (RUSH-2622). 0 disables idle reaping — the reaper still ' +
             "closes a task whose owning agent session has exited, whatever this is set to. Read only on THIS box's own " +
-            'reaper tick and `agents browser gc`, so it never applies to a peer.',
+            'reaper tick and `agents browser prune`, so it never applies to a peer.',
         validate: (v) => v >= 0 ? null : 'browser.task-idle-minutes must be >= 0 (0 disables idle reaping).',
     },
     {
@@ -486,12 +470,6 @@ export function listConfig(opts) {
 export function listUserConfig() {
     return CONFIG_KEYS.filter((spec) => spec.scope === 'user').map((spec) => getConfigValue(spec.name));
 }
-/** Resolve the explicit usage host, falling back to the user's interactive host. */
-export function resolveUsagePrimaryHost() {
-    return getConfigValue('usage.primary-host').value
-        ?? getConfigValue('interactive.host').value
-        ?? null;
-}
 // ─── Writes ───────────────────────────────────────────────────────────────────
 /** The fleet manifest for a defaults write: `devices` materializes as an
  * explicit empty map (NOT 'all') so `agents apply` targets nothing until the

package/dist/lib/devices/registry.d.ts

@@ -107,7 +107,7 @@ export declare function assertValidDeviceName(name: string): void;
  *
  * Deliberately separate from {@link assertValidDeviceName}, and called from
  * exactly two kinds of place: `agents devices add <name>`, and the config keys
- * that point AT a device (`interactive.host`, `usage.primary-host`).
+ * that point AT a device (`interactive.host`).
  *
  * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
  * receive tailnet node names the user never typed — `devices sync` upserts every

package/dist/lib/devices/registry.js

@@ -88,7 +88,7 @@ export function assertValidDeviceName(name) {
  *
  * Deliberately separate from {@link assertValidDeviceName}, and called from
  * exactly two kinds of place: `agents devices add <name>`, and the config keys
- * that point AT a device (`interactive.host`, `usage.primary-host`).
+ * that point AT a device (`interactive.host`).
  *
  * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
  * receive tailnet node names the user never typed — `devices sync` upserts every

package/dist/lib/devices/stats-cache.d.ts

@@ -14,6 +14,26 @@ export declare const SPECS_STALE_MS: number;
 export declare function isFreshDeviceStats(stats: DeviceStats, now?: number): boolean;
 /** True when cached core, RAM-total, and disk-total facts remain current. */
 export declare function isFreshDeviceSpecs(stats: DeviceStats, now?: number): boolean;
+/**
+ * Carry a device's last successfully-probed hardware facts onto a row whose
+ * probe just came back unreachable (RUSH-3096).
+ *
+ * A failed probe knows nothing about the box — `probeDeviceStats` resolves
+ * `{ host, reachable: false, fetchedAt }` — and that bare row then replaced the
+ * cached one, so `agents devices list` rendered an offline device with an empty
+ * `spec` cell and forgot its cores/RAM/disk until it came back up. Cores, total
+ * RAM, and root-disk capacity do not change while a machine is down, so they
+ * survive the failure; `loadPercent`, `memPercent`, and the free-byte counts are
+ * current-state readings and stay absent rather than render a stale number as
+ * live.
+ *
+ * `specsFetchedAt` keeps the moment the facts were actually observed while
+ * `fetchedAt` advances to this attempt, so the row reads "this hardware, seen
+ * then; unreachable, as of now" instead of backdating a reading that never
+ * happened. A reachable probe is returned untouched — its own reading is the
+ * truth, including a fact the box has stopped reporting.
+ */
+export declare function retainHardwareFacts(probed: DeviceStats, prior: DeviceStats | undefined): DeviceStats;
 /** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
 export declare function readStatsCache(): Record<string, DeviceStats>;
 /**

package/dist/lib/devices/stats-cache.js

@@ -48,6 +48,44 @@ export function isFreshDeviceSpecs(stats, now = Date.now()) {
     const fetchedAt = stats.specsFetchedAt ?? stats.fetchedAt;
     return now - fetchedAt <= SPECS_STALE_MS;
 }
+/**
+ * Carry a device's last successfully-probed hardware facts onto a row whose
+ * probe just came back unreachable (RUSH-3096).
+ *
+ * A failed probe knows nothing about the box — `probeDeviceStats` resolves
+ * `{ host, reachable: false, fetchedAt }` — and that bare row then replaced the
+ * cached one, so `agents devices list` rendered an offline device with an empty
+ * `spec` cell and forgot its cores/RAM/disk until it came back up. Cores, total
+ * RAM, and root-disk capacity do not change while a machine is down, so they
+ * survive the failure; `loadPercent`, `memPercent`, and the free-byte counts are
+ * current-state readings and stay absent rather than render a stale number as
+ * live.
+ *
+ * `specsFetchedAt` keeps the moment the facts were actually observed while
+ * `fetchedAt` advances to this attempt, so the row reads "this hardware, seen
+ * then; unreachable, as of now" instead of backdating a reading that never
+ * happened. A reachable probe is returned untouched — its own reading is the
+ * truth, including a fact the box has stopped reporting.
+ */
+export function retainHardwareFacts(probed, prior) {
+    if (probed.reachable || !prior)
+        return probed;
+    const ncpu = probed.ncpu ?? prior.ncpu;
+    const memTotalBytes = probed.memTotalBytes ?? prior.memTotalBytes;
+    const diskTotalBytes = probed.diskTotalBytes ?? prior.diskTotalBytes;
+    if (ncpu === probed.ncpu &&
+        memTotalBytes === probed.memTotalBytes &&
+        diskTotalBytes === probed.diskTotalBytes) {
+        return probed;
+    }
+    return {
+        ...probed,
+        ncpu,
+        memTotalBytes,
+        diskTotalBytes,
+        specsFetchedAt: prior.specsFetchedAt ?? prior.fetchedAt,
+    };
+}
 function cacheFilePath() {
     return path.join(getCacheDir(), CACHE_FILE);
 }
@@ -95,7 +133,10 @@ export async function loadFleetStats(devices, opts = {}) {
     const writeCache = opts.writeCache ?? writeStatsCache;
     const self = opts.selfName;
     const now = opts.now ?? Date.now();
-    const cache = opts.forceRefresh ? {} : readCache();
+    // Always read the cache, even under --refresh. It is not *served* then, but it
+    // is the only record of each box's hardware, and a failed probe must not erase
+    // it — see {@link retainHardwareFacts}.
+    const cache = readCache();
     const stats = new Map();
     const toProbe = [];
     let servedFromCache = false;
@@ -105,7 +146,7 @@ export async function loadFleetStats(devices, opts = {}) {
             toProbe.push(d);
             continue;
         }
-        const cached = cache[d.name];
+        const cached = opts.forceRefresh ? undefined : cache[d.name];
         const cacheFresh = cached && (opts.specsOnly ? isFreshDeviceSpecs(cached, now) : isFreshDeviceStats(cached, now));
         if (cached && cacheFresh) {
             stats.set(d.name, cached);
@@ -121,8 +162,11 @@ export async function loadFleetStats(devices, opts = {}) {
         const probed = await probeFleet(toProbe, { selfName: self });
         const fresh = {};
         for (const [name, s] of probed) {
-            stats.set(name, s);
-            fresh[name] = s;
+            // A box that just failed to answer keeps the hardware it was last seen
+            // with, so this call and the cache it writes both carry the spec.
+            const row = retainHardwareFacts(s, cache[name]);
+            stats.set(name, row);
+            fresh[name] = row;
         }
         if (Object.keys(fresh).length > 0)
             writeCache(fresh);
@@ -131,7 +175,7 @@ export async function loadFleetStats(devices, opts = {}) {
     // list (e.g. self not registered as an ssh target) — matches the old callers'
     // explicit local fallback.
     if (self && !stats.has(self)) {
-        stats.set(self, await probeLocal(self));
+        stats.set(self, retainHardwareFacts(await probeLocal(self), cache[self]));
     }
     let oldest = null;
     for (const s of stats.values()) {

package/dist/lib/devices/worker-pick.d.ts

@@ -0,0 +1,48 @@
+import { type DevicePlacementSignal } from '../teams/scheduler.js';
+/** Why a candidate was dropped, for the fail-loud error message. */
+export interface WorkerExclusion {
+    device: string;
+    reason: 'unreachable' | 'overloaded' | 'wrong-platform' | 'interactive';
+}
+export interface WorkerPickPlan {
+    /** The chosen device name. Never the local box unless it is an auto-pool member. */
+    device: string;
+    /** True when the pick IS this machine (the caller should run in place). */
+    isLocal: boolean;
+    candidates: Array<{
+        device: string;
+        loadPercent?: number;
+        headroom?: string;
+    }>;
+    excluded: WorkerExclusion[];
+}
+export interface WorkerPickOptions {
+    /** Restrict to these platforms. Defaults to POSIX (`linux`, `macos`). */
+    platforms?: string[];
+    /** Override the candidate pool (tests). */
+    eligibleHosts?: string[];
+    localMachine?: string;
+    /** Injected probe (tests). */
+    probe?: (pool: string[]) => Promise<Map<string, DevicePlacementSignal>>;
+}
+/**
+ * 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 declare const POSIX_PLATFORMS: readonly ["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 declare function resolveWorkerDevice(opts?: WorkerPickOptions): Promise<WorkerPickPlan>;
+/** The one no-worker message, naming every candidate and why it was dropped. */
+export declare function formatNoWorkerError(excluded: WorkerExclusion[], platforms: Set<string>): string;

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

@@ -402,28 +402,65 @@ export interface TmuxWrapContext {
     noTmuxEnv: boolean;
     /** 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.
  *
- * Opting into 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 explicitly opted into addressable tmux panes.
- *   - 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
@@ -442,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;