@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/helper-download.js

@@ -0,0 +1,194 @@
+/**
+ * Shared on-demand download + verification for the macOS native helper `.app`
+ * bundles that ship as signed + notarized GitHub release assets on each helper's
+ * OWN tag (`ComputerHelper.app`, `MenubarHelper.app`, `Agents CLI.app`) — see
+ * `helper-versions.ts` for why they are no longer keyed to the CLI's tag.
+ *
+ * A `.app` is a directory, so each asset is a zip (`ditto -c -k --keepParent`);
+ * a fresh `npm i -g` machine with no bundled copy fetches the asset for the
+ * pinned helper version, verifies its sha256 against the published `.sha256`,
+ * then verifies the code signature (Developer ID Team + notarization — and, for
+ * the menu-bar helper, its designated requirement) before it is ever installed.
+ *
+ * `computer/download.ts` (ComputerHelper) and `menubar/download-menubar.ts`
+ * (MenubarHelper) are thin per-helper wrappers over the primitives here — one
+ * download+verify machinery, two specs — so a fix to the verify/download logic
+ * lands for both helpers at once.
+ */
+import { execFileSync, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { getCacheDir } from './state.js';
+import { parseSha256Asset, sha256File } from './sha256-asset.js';
+import { helperTag } from './helper-versions.js';
+/** GitHub repo whose `v<version>` releases carry the helper assets. */
+export const HELPER_RELEASE_REPO = 'phnx-labs/agents-cli';
+/** Apple Developer ID Team every helper must be signed by ("Developer ID
+ *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
+export const EXPECTED_TEAM_ID = '2HTP252L87';
+/** Cache dir for a downloaded helper, one subdir per release tag. */
+export function helperCacheDir(spec, version) {
+    return path.join(getCacheDir(), ...spec.cacheSubdir, `v${version}`);
+}
+/**
+ * Release-asset URLs for one helper build, at that HELPER's own tag.
+ *
+ * The tag is `<helper>/v<version>` (e.g. `menubar/v1.0.0`), never the CLI's
+ * `v<cliVersion>`. Keying these to the CLI tag is what forced every CLI release
+ * to re-stage every helper asset, and simultaneously made a helper fix
+ * unreachable without a CLI release — see `helper-versions.ts` for the full why.
+ *
+ * `version` is a HELPER version. Passing a CLI version here yields a tag that
+ * does not exist; callers default it from {@link helperFloor}.
+ */
+export function helperAssetUrls(spec, version) {
+    const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/${helperTag(spec.helper, version)}`;
+    // Asset names must not contain spaces: GitHub rewrites a space to a dot on
+    // upload, so a spaced name is requested at a URL that 404s forever. Caught on
+    // `Agents CLI.app.zip`, which GitHub served as `Agents.CLI.app.zip`. Use an
+    // underscore -- GitHub preserves it verbatim.
+    if (spec.assetName.includes(' ')) {
+        throw new Error(`helper asset name ${JSON.stringify(spec.assetName)} contains a space; GitHub rewrites it to a dot on `
+            + 'upload, so this URL would always 404. Use an underscore instead.');
+    }
+    return { zip: `${base}/${spec.assetName}`, sha256: `${base}/${spec.assetName}.sha256` };
+}
+/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
+ *  emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
+export function parseTeamId(codesignInfo) {
+    return codesignInfo.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1] ?? null;
+}
+/** Read the bundle's designated requirement string (`codesign -d --requirements -`).
+ *  codesign writes it to stdout, but capture both streams so a diagnostic on
+ *  stderr can never make the pin-check read empty and falsely pass. */
+export function readDesignatedRequirement(appPath) {
+    const r = spawnSync('/usr/bin/codesign', ['-d', '--requirements', '-', appPath], { encoding: 'utf8' });
+    return `${r.stdout ?? ''}${r.stderr ?? ''}`;
+}
+/**
+ * Pure predicate (no I/O) behind the DR pin: does the requirement string pin
+ * BOTH the expected CFBundleIdentifier and the Developer ID Team? Returns null
+ * when it does, else an actionable error message naming the missing pin. Kept
+ * pure so the truth table is unit-testable without a signed bundle or codesign.
+ * Mirrors the release-time gate in `scripts/verify-menubar-helper.sh` (identifier
+ * + team substring check against the same requirement string).
+ */
+export function checkDesignatedRequirement(req, bundleId, teamId) {
+    const trimmed = req.trim();
+    const shown = trimmed ? JSON.stringify(trimmed.slice(0, 200)) : '<none>';
+    if (!trimmed.includes(`identifier "${bundleId}"`)) {
+        return (`helper designated requirement does not pin bundle id "${bundleId}" (read: ${shown}). ` +
+            `Installing it would revoke the Accessibility grant. Refusing to install.`);
+    }
+    if (!trimmed.includes(teamId)) {
+        return (`helper designated requirement does not pin Developer ID Team ${teamId} (read: ${shown}). ` +
+            `Installing it would revoke the Accessibility grant. Refusing to install.`);
+    }
+    return null;
+}
+/**
+ * Verify the bundle's designated requirement pins the expected CFBundleIdentifier
+ * AND Developer ID Team. macOS re-validates each new version against this stored
+ * requirement to keep an Accessibility grant alive across upgrades; a downloaded
+ * bundle whose DR drops either pin would silently revoke that grant on the next
+ * paste, so refuse it.
+ */
+export function verifyDesignatedRequirement(appPath, bundleId, teamId) {
+    const err = checkDesignatedRequirement(readDesignatedRequirement(appPath), bundleId, teamId);
+    if (err)
+        throw new Error(err);
+}
+/**
+ * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
+ * Team, (for the menu-bar helper) pinned by its designated requirement, and
+ * notarized (Gatekeeper-accepted). Throws with an actionable message on any
+ * failure — a downloaded bundle is never trusted without this.
+ */
+export function verifyHelperApp(appPath, spec) {
+    // 1. Structural + signature integrity.
+    try {
+        execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
+    }
+    // 2. Team identity — must be our Developer ID, not some other valid signer.
+    // `codesign -dv` writes its details to STDERR even on success (exit 0), so we
+    // must read stderr, not stdout. spawnSync captures both streams regardless of
+    // exit code; execFileSync would return only (empty) stdout and the Team check
+    // would falsely reject every validly-signed helper.
+    const dv = spawnSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { encoding: 'utf8' });
+    const info = `${dv.stdout ?? ''}${dv.stderr ?? ''}`;
+    const team = parseTeamId(info);
+    if (team !== spec.expectedTeamId) {
+        throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${spec.expectedTeamId}. Refusing to install.`);
+    }
+    // 3. Designated-requirement pin (menu-bar helper only) — before the Gatekeeper
+    //    assessment so a DR mismatch fails with its specific, actionable message
+    //    rather than a generic Gatekeeper rejection.
+    if (spec.expectedBundleId) {
+        verifyDesignatedRequirement(appPath, spec.expectedBundleId, spec.expectedTeamId);
+    }
+    // 4. Notarization / Gatekeeper — confirms Apple stapled a notarization ticket.
+    try {
+        execFileSync('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`helper is not notarized / rejected by Gatekeeper: ${e.message}. Refusing to install.`);
+    }
+}
+/**
+ * Download a helper release asset for `version`, verify sha256, extract the
+ * `.app`, and verify its signature (+ DR pin when the spec requires one).
+ * Returns the path to the extracted bundle. A missing asset is a hard error
+ * naming the exact tag — never a silent fallback to another release.
+ */
+export async function downloadHelperApp(spec, version) {
+    const dir = helperCacheDir(spec, version);
+    const cachedApp = path.join(dir, spec.appName);
+    if (fs.existsSync(cachedApp)) {
+        // Re-verify a cached bundle cheaply; a tampered cache must not be trusted.
+        verifyHelperApp(cachedApp, spec);
+        return cachedApp;
+    }
+    // Name the HELPER's tag, not `v${version}`: after the per-helper split that
+    // string was a tag that does not exist, so a 404 pointed the reader at the
+    // wrong place to look.
+    const tag = helperTag(spec.helper, version);
+    const { zip: zipUrl, sha256: shaUrl } = helperAssetUrls(spec, version);
+    const missing = (status, url) => new Error(`no ${spec.assetName} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
+        `The macOS helper ships as a GitHub release asset on its own helper tag; ` +
+        `from a repo checkout you can build it locally instead: ${spec.localBuildHint}`);
+    // Checksum first: it is tiny and 404s fast when the tag has no assets.
+    const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
+    if (!shaRes.ok)
+        throw missing(shaRes.status, shaUrl);
+    const expected = parseSha256Asset(await shaRes.text());
+    console.error(`Downloading ${spec.assetName} ${tag} from GitHub releases...`);
+    const zipRes = await fetch(zipUrl, { signal: AbortSignal.timeout(15 * 60_000) });
+    if (!zipRes.ok || !zipRes.body)
+        throw missing(zipRes.status, zipUrl);
+    fs.mkdirSync(dir, { recursive: true });
+    const partial = path.join(dir, `${spec.assetName}.download`);
+    try {
+        await pipeline(Readable.fromWeb(zipRes.body), fs.createWriteStream(partial));
+        const actual = await sha256File(partial);
+        if (actual !== expected) {
+            throw new Error(`sha256 mismatch for ${zipUrl}: expected ${expected}, got ${actual}`);
+        }
+        // Extract the zip (created with `ditto -c -k --keepParent`, so it contains
+        // <appName>/ at top level) into the version cache dir.
+        fs.rmSync(cachedApp, { recursive: true, force: true });
+        execFileSync('/usr/bin/ditto', ['-x', '-k', partial, dir], { stdio: 'pipe' });
+        if (!fs.existsSync(cachedApp)) {
+            throw new Error(`extracted asset did not contain ${spec.appName}`);
+        }
+        verifyHelperApp(cachedApp, spec);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
+    }
+    return cachedApp;
+}

package/dist/lib/helper-versions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which build of each native helper this CLI expects, and where its release
+ * lives — the module that decouples helper distribution from CLI releases.
+ *
+ * WHY THIS EXISTS. `helperAssetUrls` used to build
+ * `releases/download/v${cliVersion}/<asset>`, keying every helper to the CLI's
+ * own tag. That is coupled in BOTH directions and each one hurts:
+ *
+ *   - A CLI release had to re-stage every helper asset onto its new tag, or the
+ *     download 404'd. That is what chained an ordinary release to a Mac.
+ *   - A helper fix could not reach anyone without cutting a CLI release, because
+ *     no URL existed that a shipped CLI would look at.
+ *
+ * Helpers now publish to their OWN tags (`<helper>/v<x.y.z>`) and this table
+ * records the FLOOR — the build this CLI was tested against. A floor, not an
+ * exact pin: a pin would fix the first problem and leave the second, since an
+ * improved helper would still need a CLI release to be reachable. The floor is
+ * what a channel manifest can later resolve *upward* from (newest >= floor),
+ * without another rewrite of the download path.
+ *
+ * The floor is also the offline answer: it names an IMMUTABLE tag that always
+ * exists, so a machine that cannot reach a manifest still has exactly one
+ * correct URL rather than a guess.
+ *
+ * Bumping an entry here is a deliberate act — it says "this CLI has been tested
+ * against that helper build". It is not a mirror of the CLI version and must
+ * never be derived from `getCliVersion()`.
+ */
+/** The helpers that have their own release train. */
+export type HelperName = 'menubar' | 'keychain' | 'computer-mac' | 'computer-win';
+/** One helper's release identity. */
+export interface HelperRelease {
+    /** Tag prefix — the release is `<tagPrefix>/v<version>`. */
+    tagPrefix: string;
+    /**
+     * Lowest helper build this CLI is known to work with. Resolution may pick a
+     * NEWER build; it must never pick an older one.
+     */
+    floor: string;
+}
+/**
+ * Floors, by helper.
+ *
+ * `menubar` and `keychain` start at 1.0.0 — the first builds published under
+ * their own tags rather than the CLI's. They are not "version 1 of the helper";
+ * they are version 1 of its independent release train.
+ */
+export declare const HELPER_RELEASES: Readonly<Record<HelperName, HelperRelease>>;
+/** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
+export declare function helperTag(helper: HelperName, version: string): string;
+/** The floor build for one helper — the version used when nothing resolves higher. */
+export declare function helperFloor(helper: HelperName): string;

package/dist/lib/helper-versions.js

@@ -0,0 +1,58 @@
+/**
+ * Which build of each native helper this CLI expects, and where its release
+ * lives — the module that decouples helper distribution from CLI releases.
+ *
+ * WHY THIS EXISTS. `helperAssetUrls` used to build
+ * `releases/download/v${cliVersion}/<asset>`, keying every helper to the CLI's
+ * own tag. That is coupled in BOTH directions and each one hurts:
+ *
+ *   - A CLI release had to re-stage every helper asset onto its new tag, or the
+ *     download 404'd. That is what chained an ordinary release to a Mac.
+ *   - A helper fix could not reach anyone without cutting a CLI release, because
+ *     no URL existed that a shipped CLI would look at.
+ *
+ * Helpers now publish to their OWN tags (`<helper>/v<x.y.z>`) and this table
+ * records the FLOOR — the build this CLI was tested against. A floor, not an
+ * exact pin: a pin would fix the first problem and leave the second, since an
+ * improved helper would still need a CLI release to be reachable. The floor is
+ * what a channel manifest can later resolve *upward* from (newest >= floor),
+ * without another rewrite of the download path.
+ *
+ * The floor is also the offline answer: it names an IMMUTABLE tag that always
+ * exists, so a machine that cannot reach a manifest still has exactly one
+ * correct URL rather than a guess.
+ *
+ * Bumping an entry here is a deliberate act — it says "this CLI has been tested
+ * against that helper build". It is not a mirror of the CLI version and must
+ * never be derived from `getCliVersion()`.
+ */
+/**
+ * Floors, by helper.
+ *
+ * `menubar` and `keychain` start at 1.0.0 — the first builds published under
+ * their own tags rather than the CLI's. They are not "version 1 of the helper";
+ * they are version 1 of its independent release train.
+ */
+export const HELPER_RELEASES = {
+    menubar: { tagPrefix: 'menubar', floor: '1.0.0' },
+    keychain: { tagPrefix: 'keychain', floor: '1.0.0' },
+    'computer-mac': { tagPrefix: 'computer-mac', floor: '1.0.0' },
+    // The Windows helper is a bare .exe, not an .app bundle, so it does not share
+    // helper-download.ts's zip/codesign/notarize machinery -- but it has the same
+    // URL problem, so it shares the tag namespace and the floor.
+    'computer-win': { tagPrefix: 'computer-win', floor: '1.0.0' },
+};
+/** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
+export function helperTag(helper, version) {
+    const release = HELPER_RELEASES[helper];
+    if (!release)
+        throw new Error(`unknown helper '${helper}' (want: ${Object.keys(HELPER_RELEASES).join(', ')})`);
+    return `${release.tagPrefix}/v${version}`;
+}
+/** The floor build for one helper — the version used when nothing resolves higher. */
+export function helperFloor(helper) {
+    const release = HELPER_RELEASES[helper];
+    if (!release)
+        throw new Error(`unknown helper '${helper}' (want: ${Object.keys(HELPER_RELEASES).join(', ')})`);
+    return release.floor;
+}

package/dist/lib/hooks/cache.js

@@ -275,6 +275,25 @@ def should_fire():
             if not tn or tn not in allowed:
                 return False
 
+    v = m.get("permission_mode")
+    if v is not None:
+        allowed = arr(v)
+        if allowed:
+            pm = inp.get("permission_mode") or inp.get("permissionMode")
+            if pm and pm not in allowed:
+                return False
+
+    v = m.get("permission_mode_not")
+    if v is not None:
+        denied = arr(v)
+        if denied:
+            # Negative form: naming the mode to SKIP keeps every unknown mode
+            # firing, so the failure direction is "ran unnecessarily", never
+            # "did not run". Absence of a mode fires, same as permission_mode.
+            pm = inp.get("permission_mode") or inp.get("permissionMode")
+            if pm and pm in denied:
+                return False
+
     v = m.get("tool_args_match")
     if v is not None:
         ta = inp.get("tool_args")

package/dist/lib/hooks/install.js

@@ -3255,8 +3255,8 @@ function resolveSessionTrackerRoot() {
     if (fs.existsSync(path.join(built, 'dist', 'hook.sh'))) {
         return built;
     }
-    // Source layout: apps/cli/src/lib/hooks/ -> repo root -> packages/session-tracker
-    const source = path.resolve(here, '..', '..', '..', '..', '..', 'packages', 'session-tracker');
+    // Source layout: cli/src/lib/hooks/ -> repo root (4 up) -> packages/session-tracker
+    const source = path.resolve(here, '..', '..', '..', '..', 'packages', 'session-tracker');
     if (fs.existsSync(path.join(source, 'src', 'hook.sh'))) {
         return source;
     }

package/dist/lib/hooks/match.d.ts

@@ -20,6 +20,9 @@ export interface HookInput {
     tool_name?: string;
     tool_args?: unknown;
     cwd?: string;
+    permission_mode?: string;
+    /** Grok-style camelCase spelling of permission_mode. */
+    permissionMode?: string;
 }
 export declare function isSafeHookRegex(source: string): boolean;
 /**

package/dist/lib/hooks/match.js

@@ -131,6 +131,31 @@ export function shouldFire(matches, input) {
                 return false;
         }
     }
+    if (matches.permission_mode !== undefined) {
+        const allowed = arrayOf(matches.permission_mode);
+        if (allowed.length > 0) {
+            // Fail-open on absence: only some harnesses (Claude Code) report the
+            // live mode. An input with no mode field passes; an explicit value not
+            // in the allowed list skips.
+            const mode = input.permission_mode || input.permissionMode;
+            if (mode && !allowed.includes(mode))
+                return false;
+        }
+    }
+    if (matches.permission_mode_not !== undefined) {
+        const denied = arrayOf(matches.permission_mode_not);
+        if (denied.length > 0) {
+            // The negative form exists because the positive one cannot express
+            // "everywhere except plan" without enumerating every other mode — and an
+            // enumeration silently stops firing the moment a harness adds or renames
+            // one, which for a guard means it quietly stops guarding. Naming the mode
+            // to skip keeps every unknown mode firing, so the failure direction is
+            // "ran unnecessarily", never "did not run".
+            const mode = input.permission_mode || input.permissionMode;
+            if (mode && denied.includes(mode))
+                return false;
+        }
+    }
     if (matches.tool_args_match !== undefined) {
         const serialized = typeof input.tool_args === 'string'
             ? input.tool_args

package/dist/lib/hosts/credentials.d.ts

@@ -6,7 +6,7 @@
  * codex/grok/gemini `auth.json`-style files — so the box booted logged-in. Every
  * one of those is a **rotating, interactive OAuth / session credential**, and
  * copying it between devices is forbidden by the fleet-auth contract
- * (`docs/specifications.md` SING-1b, `docs/credential-management.md` invariant 2):
+ * (`docs/specifications.md` SING-1b, `docs/secrets.md`):
  * a shared refresh token rotates server-side on the next refresh and invalidates
  * every other copy — the "droid collapsed 10 boxes to 1 overnight" failure.
  *

package/dist/lib/hosts/credentials.js

@@ -6,7 +6,7 @@
  * codex/grok/gemini `auth.json`-style files — so the box booted logged-in. Every
  * one of those is a **rotating, interactive OAuth / session credential**, and
  * copying it between devices is forbidden by the fleet-auth contract
- * (`docs/specifications.md` SING-1b, `docs/credential-management.md` invariant 2):
+ * (`docs/specifications.md` SING-1b, `docs/secrets.md`):
  * a shared refresh token rotates server-side on the next refresh and invalidates
  * every other copy — the "droid collapsed 10 boxes to 1 overnight" failure.
  *

package/dist/lib/hosts/dispatch.d.ts

@@ -37,8 +37,14 @@ export declare function withActorEnv(env?: Record<string, string>): Record<strin
  * only reach the spawned agent's env and the remote `run auto` would re-pick.
  * Shared by the interactive (runInteractiveOnHost) and detached
  * (launchDetached) paths so both behave identically.
+ *
+ * `extra` carries the markers that are true of ONE path rather than both — the
+ * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
+ * to decide it must detach. It goes through this builder rather than being
+ * concatenated on at the call site so every remote env marker is exported the
+ * same way, in one place.
  */
-export declare function remoteRunShellPrelude(agent: string): string;
+export declare function remoteRunShellPrelude(agent: string, extra?: Record<string, string>): string;
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *

package/dist/lib/hosts/dispatch.js

@@ -20,7 +20,7 @@ import { followHostTask } from './progress.js';
 import { wrapHostCommandWithCredentials } from './credentials.js';
 import { hostKeyCheckingOpts } from '../devices/known-hosts.js';
 import { deriveMirroredCwd, homeRemainder, remoteCdPrefix } from '../project-root.js';
-import { RUN_AUTO_KEYWORD, RUN_AUTO_HOST_RESOLVED_ENV } from '../types.js';
+import { RUN_AUTO_KEYWORD, RUN_AUTO_HOST_RESOLVED_ENV, REMOTE_INTERACTIVE_ENV } from '../types.js';
 // The home-relative portability helpers live in project-root.js (the canonical
 // home-relative conversion home), reused by the interactive `agents ssh` login
 // shell builder (devices/connect.ts) as well as this dispatch layer. Re-exported
@@ -75,10 +75,16 @@ export function withActorEnv(env) {
  * only reach the spawned agent's env and the remote `run auto` would re-pick.
  * Shared by the interactive (runInteractiveOnHost) and detached
  * (launchDetached) paths so both behave identically.
+ *
+ * `extra` carries the markers that are true of ONE path rather than both — the
+ * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
+ * to decide it must detach. It goes through this builder rather than being
+ * concatenated on at the call site so every remote env marker is exported the
+ * same way, in one place.
  */
-export function remoteRunShellPrelude(agent) {
+export function remoteRunShellPrelude(agent, extra = {}) {
     const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
-    const exports = posixEnvExports(withActorEnv(guard));
+    const exports = posixEnvExports(withActorEnv({ ...guard, ...extra }));
     return exports ? `${exports}; ` : '';
 }
 /**
@@ -490,7 +496,13 @@ export async function runInteractiveOnHost(host, opts) {
     // Forward actor provenance so the interactive remote run inherits it rather
     // than re-resolving from this box's SSH_CONNECTION (RUSH-2028); a `run auto`
     // dispatch also gets the chain-hop guard (remoteRunShellPrelude).
-    const prelude = remoteRunShellPrelude(opts.agent);
+    //
+    // REMOTE_INTERACTIVE_ENV rides the same prelude and is what makes the remote
+    // agent DETACHED: its stdio is this ssh link, so without the tmux wrap a
+    // blink SIGHUPs it and the in-flight turn is gone — while reconnect.ts is
+    // built to re-attach a pane it assumes survived (RUSH-3125). Set here, on the
+    // interactive path only: `launchDetached` already setsids the headless one.
+    const prelude = remoteRunShellPrelude(opts.agent, { [REMOTE_INTERACTIVE_ENV]: '1' });
     let remoteCmd = `${prelude}${cwd}${invocation}`;
     if (opts.copyCreds) {
         remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);
@@ -501,7 +513,14 @@ export async function runInteractiveOnHost(host, opts) {
     const credHostKeyOpts = opts.copyCreds ? hostKeyCheckingOpts(true) : undefined;
     return sshStream(target, remoteCmd, {
         tty: process.stdin.isTTY,
-        multiplex: !opts.copyCreds,
+        // NOT multiplexed. `ControlPath=cm-%C` hashes only local host / remote host
+        // / port / user, so every agent tab pointed at a peer shares ONE master —
+        // and OpenSSH closes every channel on it the instant that master dies. One
+        // blink therefore ejected all six tabs on a box at once, which is what made
+        // a brief outage read as "all my agents exited" (RUSH-3125). The handshake
+        // this gives up is a one-time ~200ms on a session that runs for hours;
+        // probes and fan-outs keep the shared master, where it actually pays.
+        multiplex: false,
         hostKeyOpts: credHostKeyOpts,
         extraSshArgs: hostIdentityArgs(host),
     });

package/dist/lib/hosts/passthrough.d.ts

@@ -11,7 +11,7 @@
  * supervisor outlives a dropped connection.
  *
  * Commands with their own richer `--device` handling (`run`/`sessions`/`feed`/
- * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
+ * `computer`/`browser`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
  * fall through to their local actions. Everything else either routes via this
  * table or, when `--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
@@ -98,20 +98,13 @@ export declare function maybeRunOnHost(command: string, allArgs: string[], opts?
  * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
  * than being the first argv token.
  *
- * `agents browser … --device <box>` routes through {@link maybeRunOnHost} in
- * index.ts, but the standalone `browser` binary never enters index.ts — so without
- * this it dropped `--device` entirely (commander errored with `unknown option
- * '--device'`). This wires the identical routing: it synthesizes the implicit command
- * token (`browser`) at the front of the argv so the remote invocation builds as
- * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
- * it dispatched the run to a remote (the local program must then NOT parse).
- *
- * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
- * args minus the routing flags — never the synthetic command token — so the
- * standalone commander program parses cleanly and never sees an unknown `--device`.
- * When no routing flag is present it leaves `process.argv` untouched (the common
- * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
- * run.
+ * `agents computer … --device <box>` still routes through {@link maybeRunOnHost}
+ * in index.ts, but the standalone `browser` / `computer` binaries never enter
+ * index.ts. Browser now owns `--device` (start binds the task; later verbs
+ * reject it), so this function leaves argv intact for OWN_HOST commands and
+ * only strips routing flags on `--help`/`--version`. Other standalone commands
+ * still synthesize the implicit command token and delegate to
+ * {@link maybeRunOnHost}.
  *
  * @param command the fixed command name the binary stands for (`'browser'`).
  */

package/dist/lib/hosts/passthrough.js

@@ -11,7 +11,7 @@
  * supervisor outlives a dropped connection.
  *
  * Commands with their own richer `--device` handling (`run`/`sessions`/`feed`/
- * `computer`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
+ * `computer`/`browser`/`secrets`/`logs`/…) are listed in {@link OWN_HOST_COMMANDS} and
  * fall through to their local actions. Everything else either routes via this
  * table or, when `--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
@@ -28,6 +28,7 @@ import { resolveRemoteOsSync } from './remote-os.js';
 // 6–7× cheaper graph (RUSH-2374 proposal 2).
 import { machineId } from '../machine-id.js';
 import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, } from '../devices/interactive-host.js';
 import { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
@@ -100,7 +101,6 @@ export const REMOTE_PASSTHROUGH = {
     tmux: {},
     watchdog: {},
     factory: {},
-    browser: {},
 };
 /**
  * Commands that register and interpret `--device` themselves — must
@@ -115,6 +115,7 @@ export const OWN_HOST_COMMANDS = new Set([
     'sessions',
     'feed',
     'computer',
+    'browser', // `--device` on start binds the task; later verbs resolve it from the task
     'secrets',
     'accounts', // `accounts sync --device` names the destination, not remote routing
     'logs',
@@ -527,6 +528,21 @@ export async function maybeRunOnHost(command, allArgs, opts) {
         process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
         hostName = plan.host;
     }
+    // `interactive` is the second affinity sentinel: the box the human sits at
+    // (`interactive.host`). Resolved here, ahead of the isSelfHost check below, for
+    // the same reason `auto` is — a pin naming THIS machine must run locally rather
+    // than self-SSH. It never falls back to the local box when unset: rendering to
+    // a screen nobody is watching is the exact failure the sentinel prevents.
+    if (isDeviceInteractive(hostName)) {
+        const pinned = resolveInteractiveDevice();
+        if (!pinned) {
+            process.stderr.write(`${interactiveUnsetError()}\n`);
+            process.exitCode = 1;
+            return true;
+        }
+        process.stderr.write(chalk.gray(`[agents] device=interactive → ${pinned}\n`));
+        hostName = pinned;
+    }
     // Running against your own machine is just a local run — skip the SSH round-trip.
     // Match EVERY identity the box answers to (short id, loopback, tailscale
     // dnsName), not just machineId() — a `--device <self-dnsName>` used to slip past a
@@ -593,20 +609,13 @@ export async function maybeRunOnHost(command, allArgs, opts) {
  * the binary itself (the `browser`/`computer` bins, `dist/browser.js` etc.) rather
  * than being the first argv token.
  *
- * `agents browser … --device <box>` routes through {@link maybeRunOnHost} in
- * index.ts, but the standalone `browser` binary never enters index.ts — so without
- * this it dropped `--device` entirely (commander errored with `unknown option
- * '--device'`). This wires the identical routing: it synthesizes the implicit command
- * token (`browser`) at the front of the argv so the remote invocation builds as
- * `agents browser …`, delegates to {@link maybeRunOnHost}, and returns `true` when
- * it dispatched the run to a remote (the local program must then NOT parse).
- *
- * On a local / self-host fall-through it rewrites `process.argv` to the ORIGINAL
- * args minus the routing flags — never the synthetic command token — so the
- * standalone commander program parses cleanly and never sees an unknown `--device`.
- * When no routing flag is present it leaves `process.argv` untouched (the common
- * case), so an unrelated flag like `--no-tty` is never stripped from a purely local
- * run.
+ * `agents computer … --device <box>` still routes through {@link maybeRunOnHost}
+ * in index.ts, but the standalone `browser` / `computer` binaries never enter
+ * index.ts. Browser now owns `--device` (start binds the task; later verbs
+ * reject it), so this function leaves argv intact for OWN_HOST commands and
+ * only strips routing flags on `--help`/`--version`. Other standalone commands
+ * still synthesize the implicit command token and delegate to
+ * {@link maybeRunOnHost}.
  *
  * @param command the fixed command name the binary stands for (`'browser'`).
  */
@@ -616,6 +625,16 @@ export async function maybeRunStandaloneOnHost(command, opts) {
     // local run keeps every flag it passed.
     if (!hasHostRoutingFlag(rawArgs))
         return false;
+    // Commands that interpret `--device` themselves (browser start binds the
+    // task→device index; later browser verbs reject the flag) must see it.
+    // Help/version still strip so `browser --device x --help` parses.
+    if (OWN_HOST_COMMANDS.has(command)) {
+        const helpOrVersion = rawArgs.some((a) => a === '--help' || a === '-h' || a === '--version' || a === '-V');
+        if (helpOrVersion) {
+            process.argv = [process.argv[0], process.argv[1], ...stripRoutingFlags(rawArgs, STRIP_SPECS)];
+        }
+        return false;
+    }
     // Keep --help/--version local (docs must work without a reachable host), mirroring
     // index.ts's `helpOrVersionRequested` guard, but still strip the routing flags
     // below so commander doesn't choke on them.

package/dist/lib/hosts/providers/devices.d.ts

@@ -3,7 +3,7 @@
  *
  * Bridges the devices registry (`agents devices`, ~/.agents/.history/devices/
  * registry.json) into the host pool behind the same `HostProvider` seam as
- * `local` — the "tailscale provider" fast-follow named in docs/hosts.md. With
+ * `local` — the Tailscale-backed device provider described in docs/fleet.md. With
  * it, a machine registered once via `agents devices sync` becomes a resolvable
  * `--device`/`--device` dispatch target, participates in capability routing, and
  * is enumerable by target pickers — not just resolvable by exact name.

package/dist/lib/hosts/providers/devices.js

@@ -3,7 +3,7 @@
  *
  * Bridges the devices registry (`agents devices`, ~/.agents/.history/devices/
  * registry.json) into the host pool behind the same `HostProvider` seam as
- * `local` — the "tailscale provider" fast-follow named in docs/hosts.md. With
+ * `local` — the Tailscale-backed device provider described in docs/fleet.md. With
  * it, a machine registered once via `agents devices sync` becomes a resolvable
  * `--device`/`--device` dispatch target, participates in capability routing, and
  * is enumerable by target pickers — not just resolvable by exact name.