@phnx-labs/agents-cli 1.22.53 → 1.22.54

package/dist/lib/daemon/auth-sync-service.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reserved `auth` bundle fleet sync as a `PeriodicService` (PHNX-2371).
+ *
+ * Each daemon that has a local file-backed `auth` bundle pushes it to pinned
+ * fleet devices that do not yet have it. The destination auto-provisions its
+ * own machine-local key; no passphrase is forwarded. Single-executor per
+ * destination: this process only writes the remote's own store.
+ */
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class AuthSyncService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs: number;
+    readonly deadlineMs: number;
+    readonly startupDelayMs = 60000;
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+}

package/dist/lib/daemon/auth-sync-service.js

@@ -0,0 +1,34 @@
+/**
+ * Reserved `auth` bundle fleet sync as a `PeriodicService` (PHNX-2371).
+ *
+ * Each daemon that has a local file-backed `auth` bundle pushes it to pinned
+ * fleet devices that do not yet have it. The destination auto-provisions its
+ * own machine-local key; no passphrase is forwarded. Single-executor per
+ * destination: this process only writes the remote's own store.
+ */
+import { BasePeriodicService } from './service.js';
+const AUTH_SYNC_TICK_MS = 15 * 60_000;
+const AUTH_SYNC_DEADLINE_MS = 2 * 60_000;
+const AUTH_SYNC_KICKOFF_MS = 60_000;
+export class AuthSyncService extends BasePeriodicService {
+    id = 'auth-sync';
+    intervalMs = AUTH_SYNC_TICK_MS;
+    deadlineMs = AUTH_SYNC_DEADLINE_MS;
+    startupDelayMs = AUTH_SYNC_KICKOFF_MS;
+    async onStart(_ctx) {
+        // No connections to open — each tick re-reads the local bundle + registry.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup.
+    }
+    async onTick(ctx) {
+        const { syncReservedAuthBundle } = await import('../secrets/reserved-sync.js');
+        const result = syncReservedAuthBundle();
+        if (result.pushed.length > 0) {
+            ctx.log('INFO', `auth-sync: pushed auth to ${result.pushed.join(', ')}`);
+        }
+        for (const err of result.errors) {
+            ctx.log('WARN', `auth-sync: ${err.device}: ${err.message}`);
+        }
+    }
+}

package/dist/lib/daemon/daemon.js

@@ -28,6 +28,7 @@ import { startHostedWebhookReceivers } from '../daemon-webhooks.js';
 import { secretsBrokerSocketPath, brokerPidAlive } from '../secrets/agent.js';
 import { redactSecrets } from '../redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from '../cli-entry.js';
+import { localBinDir } from '../platform/posixpath.js';
 import { isSchedulerEnabled, assertSchedulerEnabled, isDaemonEnabled, resolveBrowserTaskIdleMs } from '../device-config.js';
 import { reapTerminalRoutineProcesses } from '../routine-process-cleanup.js';
 import { recordSubsystemOk, recordSubsystemError, recordSubsystemErrorReason, readSubsystemHealth, SUBSYSTEM_DAEMON_START } from '../daemon-health.js';
@@ -43,6 +44,7 @@ import { WatchdogService } from './watchdog-service.js';
 import { DeviceProbeService } from './device-probe-service.js';
 import { SelfHealService } from './self-heal-service.js';
 import { KeychainReapService } from './keychain-reap-service.js';
+import { AuthSyncService } from './auth-sync-service.js';
 import { StateDirCheckService } from './state-dir-check-service.js';
 import { emit, emitRoutineEnd } from '../feed/events.js';
 import { readDaemonServicesConfig, drainDaemonServiceRestartQueue } from '../daemon-services.js';
@@ -934,6 +936,10 @@ export async function runDaemon() {
         supervisor.register(new KeychainReapService());
     else
         log('INFO', 'Keychain-reap service disabled');
+    if (isEnabled('auth-sync'))
+        supervisor.register(new AuthSyncService());
+    else
+        log('INFO', 'Auth-sync service disabled');
     await supervisor.startAll({ log });
     activeServiceSupervisor = supervisor;
     // scheduler.enabled=false in this machine's device doc means NO routines fire
@@ -1800,10 +1806,23 @@ export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
 function daemonNodeBinDir() {
     return path.dirname(process.execPath);
 }
+/**
+ * Login-shell user-bin dirs a service-manager-started daemon would otherwise
+ * miss. systemd/launchd pin PATH and never source `~/.profile`, so they never
+ * see `~/.rush/bin` (where `rush` lands) or `~/.local/bin` (XDG user-bin).
+ * Monitor `notify` and dispatched `agents run` children inherit this PATH;
+ * without these dirs the rush-backed owner channel fails with
+ * `rush CLI not found on PATH` (PHNX-3075) while an interactive shell on the
+ * same box succeeds. Uses the same HOME the manifest bakes (RUSH-2639).
+ */
+function daemonUserBinDirs() {
+    const home = serviceManifestHomeEnv().HOME;
+    return [path.join(home, '.rush', 'bin'), localBinDir(home)];
+}
 /**
  * The full PATH value the daemon service manifest pins, in order: the directory
- * of the `agents` shim itself FIRST, then the Node runtime dir, then the
- * platform's system dirs.
+ * of the `agents` shim itself FIRST, then the Node runtime dir, then login-shell
+ * user-bin dirs (`~/.rush/bin`, `~/.local/bin`), then the platform's system dirs.
  *
  * The shim's own dir must lead so a scheduled `command` routine that shells out
  * to the bare name `agents` (`/bin/sh -c 'agents repo pull system'`) resolves the
@@ -1814,12 +1833,19 @@ function daemonNodeBinDir() {
  *
  * The Node runtime dir stays second so the shim's shebang (`#!/usr/bin/env node`)
  * still resolves the exact Node that installed the service — never an ancient
- * system node or a pruned nvm version. Deduped across the whole list, so a
+ * system node or a pruned nvm version. User-bin dirs sit after that pair so a
+ * `~/.local/bin/agents` cannot shadow the daemon binary, but `rush` (and other
+ * login-shell CLIs) still resolve. Deduped across the whole list, so a
  * Node/shim dir that already appears among the system dirs (e.g. a
  * `/usr/local/bin` install) never doubles.
  */
 function daemonPathValue(agentsBin, systemDirs) {
-    return [...new Set([path.dirname(agentsBin), daemonNodeBinDir(), ...systemDirs])].join(':');
+    return [...new Set([
+            path.dirname(agentsBin),
+            daemonNodeBinDir(),
+            ...daemonUserBinDirs(),
+            ...systemDirs,
+        ])].join(':');
 }
 /**
  * Build the argv to relaunch the `agents` CLI with the given subcommand args.

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

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index';
+export type DaemonServiceId = 'secrets-broker' | 'scheduler' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'keychain-reap' | 'account-state' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -72,6 +72,11 @@ export const DAEMON_SERVICES = [
         title: 'Session-index warm',
         description: 'Keeps this host\'s transcript index current so a locally-started session is discoverable within seconds.',
     },
+    {
+        id: 'auth-sync',
+        title: 'Auth bundle sync',
+        description: 'Pushes the reserved file-backed auth bundle (setup-tokens) to pinned fleet devices that do not yet have it.',
+    },
 ];
 /** Stable order of service IDs. */
 export const DAEMON_SERVICE_IDS = DAEMON_SERVICES.map((s) => s.id);

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

@@ -223,9 +223,9 @@ export declare function isDaemonEnabled(): boolean;
 /**
  * Throw when the daemon is disabled on this machine, naming the setting and
  * the fix. Every AUTO-start surface (routines add/start/catchup/webhook,
- * `ensureDaemonStarted`) refuses with this before calling `startDaemon()`.
- * `agents daemon start` is the deliberate override and does NOT call this —
- * disable only blocks auto-start, mirroring `systemctl disable`.
+ * monitors add, `ensureDaemonStarted`) refuses with this before calling
+ * `startDaemon()`. `agents daemon start` is the deliberate override and does
+ * NOT call this — disable only blocks auto-start, mirroring `systemctl disable`.
  */
 export declare function assertDaemonEnabled(): void;
 /**

package/dist/lib/device-config.js

@@ -145,7 +145,7 @@ export const CONFIG_KEYS = [
         defaultValue: true,
         description: 'Whether the daemon may run on this device at all (secrets broker, browser IPC, watchdog, and the ' +
             'routines scheduler). Disabling is the top-level kill switch: nothing auto-starts the daemon while it ' +
-            'is set, including `routines add`/`routines start`/`routines catchup`/webhook triggers. ' +
+            'is set, including `routines add`/`routines start`/`routines catchup`/`monitors add`/webhook triggers. ' +
             '`agents daemon start` still starts it explicitly.',
     },
     {
@@ -176,7 +176,7 @@ export const CONFIG_KEYS = [
         visibility: 'machine',
         type: 'bool',
         defaultValue: false,
-        description: "Whether other fleet machines may drive THIS device's browser over `browser --device <this-device>`. " +
+        description: "Whether other fleet machines may drive THIS device's browser over `browser --device <this-device>` or `agents ssh <this-device> …` (`agents browser` / `ag browser` / standalone `browser`). " +
             'Default off — a fleet-remote drive is refused until the owner runs `agents browser remote-control on`.',
     },
     {
@@ -813,9 +813,9 @@ export function isDaemonEnabled() {
 /**
  * Throw when the daemon is disabled on this machine, naming the setting and
  * the fix. Every AUTO-start surface (routines add/start/catchup/webhook,
- * `ensureDaemonStarted`) refuses with this before calling `startDaemon()`.
- * `agents daemon start` is the deliberate override and does NOT call this —
- * disable only blocks auto-start, mirroring `systemctl disable`.
+ * monitors add, `ensureDaemonStarted`) refuses with this before calling
+ * `startDaemon()`. `agents daemon start` is the deliberate override and does
+ * NOT call this — disable only blocks auto-start, mirroring `systemctl disable`.
  */
 export function assertDaemonEnabled() {
     if (isDaemonEnabled())

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

@@ -37,6 +37,26 @@ export declare function fleetDialTarget(device: DeviceProfile): string;
  * login).
  */
 export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
+/**
+ * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
+ * the standalone `browser` binary (`cli/package.json` `bin.browser` →
+ * `src/browser.ts`), including the quoted single-string form
+ * `agents ssh box 'browser …'`. The `--device` passthrough stamps
+ * {@link markFleetRemote} on this shape so the far-side consent gate can fire;
+ * `agents ssh` must too (PHNX-3065).
+ */
+export declare function isAgentsBrowserDrive(cmd: string[]): boolean;
+/**
+ * Prefix a remote command so the far side sees `AGENTS_FLEET_REMOTE=1` — the
+ * marker the browser consent gate reads. `wrapRemoteCommand` joins the argv
+ * with spaces (POSIX) or base64-encodes it for PowerShell, so a
+ * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
+ * `$env:VAR='1'; …` on PowerShell.
+ *
+ * Already-marked argv (the `--device` fan-out stamps this before
+ * {@link buildSshInvocation}) is left unchanged so the prefix is not doubled.
+ */
+export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfile, 'shell'>): string[];
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
  * mirrored project directory, falling back to the remote home when that
@@ -97,6 +117,12 @@ export declare function deviceIdentityArgs(device: DeviceProfile): string[];
  * to the remote home), matching `agents run --device`. It is ignored when a `cmd`
  * is given: an explicit command keeps its current cwd (the remote home) and its
  * behavior unchanged (RUSH-2412).
+ *
+ * An `agents browser …` / `ag browser …` / standalone `browser …` command is
+ * prefixed with {@link markFleetRemote} so the far-side consent gate sees
+ * `AGENTS_FLEET_REMOTE=1` the same way `browser --device` does. The local `env`
+ * overlay here is for the ssh *client* (askpass); it cannot carry the marker —
+ * OpenSSH does not forward arbitrary env (PHNX-3065).
  */
 export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions, opts?: {
     agentOnly?: boolean;

package/dist/lib/devices/connect.js

@@ -86,6 +86,43 @@ export function wrapRemoteCommand(device, cmd) {
     }
     return joined;
 }
+/**
+ * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
+ * the standalone `browser` binary (`cli/package.json` `bin.browser` →
+ * `src/browser.ts`), including the quoted single-string form
+ * `agents ssh box 'browser …'`. The `--device` passthrough stamps
+ * {@link markFleetRemote} on this shape so the far-side consent gate can fire;
+ * `agents ssh` must too (PHNX-3065).
+ */
+export function isAgentsBrowserDrive(cmd) {
+    if (cmd.length === 0)
+        return false;
+    const tokens = cmd.length === 1 && /\s/.test(cmd[0]) ? cmd[0].trim().split(/\s+/) : cmd;
+    const bin = tokens[0];
+    if (bin === 'browser')
+        return true;
+    return (bin === 'agents' || bin === 'ag') && tokens[1] === 'browser';
+}
+/**
+ * Prefix a remote command so the far side sees `AGENTS_FLEET_REMOTE=1` — the
+ * marker the browser consent gate reads. `wrapRemoteCommand` joins the argv
+ * with spaces (POSIX) or base64-encodes it for PowerShell, so a
+ * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
+ * `$env:VAR='1'; …` on PowerShell.
+ *
+ * Already-marked argv (the `--device` fan-out stamps this before
+ * {@link buildSshInvocation}) is left unchanged so the prefix is not doubled.
+ */
+export function markFleetRemote(cmd, device) {
+    if (device.shell === 'powershell') {
+        return cmd[0] === `$env:AGENTS_FLEET_REMOTE='1';`
+            ? cmd
+            : [`$env:AGENTS_FLEET_REMOTE='1';`, ...cmd];
+    }
+    return cmd[0] === 'env' && cmd[1] === 'AGENTS_FLEET_REMOTE=1'
+        ? cmd
+        : ['env', 'AGENTS_FLEET_REMOTE=1', ...cmd];
+}
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
  * mirrored project directory, falling back to the remote home when that
@@ -156,6 +193,12 @@ export function deviceIdentityArgs(device) {
  * to the remote home), matching `agents run --device`. It is ignored when a `cmd`
  * is given: an explicit command keeps its current cwd (the remote home) and its
  * behavior unchanged (RUSH-2412).
+ *
+ * An `agents browser …` / `ag browser …` / standalone `browser …` command is
+ * prefixed with {@link markFleetRemote} so the far-side consent gate sees
+ * `AGENTS_FLEET_REMOTE=1` the same way `browser --device` does. The local `env`
+ * overlay here is for the ssh *client* (askpass); it cannot carry the marker —
+ * OpenSSH does not forward arbitrary env (PHNX-3065).
  */
 export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}, opts = {}) {
     // The effective profile: central config (ssh.*/platform/user) overlaid on
@@ -166,9 +209,13 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}, o
     // wrapper (interactiveCwd), which is an interactive login too and still needs
     // a real tty below.
     const interactive = cmd.length === 0;
+    // Stamp the consent marker on the REMOTE command, not the local ssh env:
+    // SSH_ASKPASS lives on this side; AGENTS_FLEET_REMOTE must be visible to the
+    // process that runs on the peer.
+    const remoteCmd = !interactive && isAgentsBrowserDrive(cmd) ? markFleetRemote(cmd, device) : cmd;
     const remote = interactive
         ? buildInteractiveShellCommand(device, opts.interactiveCwd)
-        : wrapRemoteCommand(device, cmd);
+        : wrapRemoteCommand(device, remoteCmd);
     const env = {};
     const args = [
         ...hostKeyCheckingOpts(hostKey.pinned ?? false, hostKey.knownHostsFile),

package/dist/lib/devices/doctor-findings.d.ts

@@ -13,7 +13,7 @@ export type FindingSeverity = 'critical' | 'warning';
  *  the JSON consumer group by kind. */
 /** Every finding class. Severity is NOT annotated here — {@link FINDING_SEVERITY}
  *  below owns it, and a second copy in these comments is a fourth place to drift. */
-export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "hook-runtime-broken", "hook-runtime-visibility-unavailable", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "env-secret-export", "exec-policy", "ssh-key-enrollment", "stale-cli", "binary-shadow", "owner-sink-unreachable"];
+export declare const ALL_FINDING_KINDS: readonly ["logged-out", "logout-unprovable", "missing-hook", "missing-plugin", "unwired-hook", "hook-runtime-broken", "hook-runtime-visibility-unavailable", "cli-missing", "missing-resource", "content-drift", "never-synced", "stale", "repo-behind", "repo-drift", "fleet-resource-gap", "host-cli-missing", "host-cli-invalid", "version-skew", "orphan", "duplicate-hook", "duplicate-hook-drift", "rc-secret-export", "env-secret-export", "auth-bundle-wrong-backend", "exec-policy", "ssh-key-enrollment", "stale-cli", "binary-shadow", "owner-sink-unreachable"];
 /**
  * The severity each kind is emitted with - the SINGLE source of truth, read by
  * the builders below and asserted against both prose rubrics by
@@ -100,6 +100,10 @@ export interface LocalFindingInputs {
      *  scan reports clean while the leak is still in flight (RUSH-1968). Never the
      *  value — only whether it is set. */
     masterPassphraseInEnv?: boolean;
+    /** True when the reserved `auth` bundle exists on a non-file backend
+     *  (SEC-GAP-3): usage/probe ignores the setup-tokens and falls through to
+     *  Touch ID. Collected by `inspectReservedAuthBundle`. */
+    authBundleWrongBackend?: boolean;
     /** The effective PowerShell execution policy and the platform it was read on.
      *  Only `win32` yields a finding — the `agents.ps1` launcher is Windows-only. */
     execPolicy?: {

package/dist/lib/devices/doctor-findings.js

@@ -26,7 +26,7 @@
  *              never-synced · stale · repo-behind · repo-drift · version-skew ·
  *              fleet-resource-gap · hook-runtime-visibility-unavailable · orphan · duplicate-hook ·
  *              duplicate-hook-drift · host-cli-missing · host-cli-invalid ·
- *              rc-secret-export · env-secret-export · exec-policy · stale-cli ·
+ *              rc-secret-export · env-secret-export · auth-bundle-wrong-backend · exec-policy · stale-cli ·
  *              binary-shadow.
  *   (RUSH-2162 moved never-synced and duplicate-hook-drift to WARNING: both are
  *   stale-sync states one `agents sync` resolves, not "needs you now".)
@@ -102,6 +102,7 @@ export const ALL_FINDING_KINDS = [
     'duplicate-hook-drift', // …with differing content, so a stale copy can disagree
     'rc-secret-export', // credential-shaped export in a shell rc file
     'env-secret-export', // the file-store master key live in THIS process's env
+    'auth-bundle-wrong-backend', // reserved `auth` bundle exists but is not file-backed
     'exec-policy', // Windows execution policy blocks agents.ps1
     'ssh-key-enrollment', // Windows OpenSSH public-key path/content/ACL is invalid
     'stale-cli',
@@ -150,6 +151,7 @@ export const FINDING_SEVERITY = {
     'host-cli-invalid': 'warning',
     'rc-secret-export': 'warning',
     'env-secret-export': 'warning',
+    'auth-bundle-wrong-backend': 'warning',
     'exec-policy': 'warning',
     'ssh-key-enrollment': 'critical',
     'stale-cli': 'warning',
@@ -269,6 +271,8 @@ export function remediationFor(finding) {
             // that inherited it — an editor, a tmux server, the agents daemon — and
             // each keeps handing it to new children until IT restarts.
             return 'unset at the source, then restart every process that inherited it (shells, editor, tmux, agents daemon)';
+        case 'auth-bundle-wrong-backend':
+            return 'agents secrets delete auth --yes && agents secrets create auth --backend file';
         case 'exec-policy':
             return 'Set-ExecutionPolicy -Scope CurrentUser RemoteSigned';
         case 'ssh-key-enrollment':
@@ -519,6 +523,9 @@ export function buildLocalFindings(input) {
     const envFinding = envSecretFinding(device, input.masterPassphraseInEnv ?? false);
     if (envFinding)
         out.push(envFinding);
+    const authFinding = authBundleWrongBackendFinding(device, input.authBundleWrongBackend ?? false);
+    if (authFinding)
+        out.push(authFinding);
     // Windows execution policy blocking the generated agents.ps1 launcher.
     const policyFinding = execPolicyFinding(device, input.execPolicy);
     if (policyFinding)
@@ -688,6 +695,15 @@ function envSecretFinding(device, present) {
             + '(Expected inside a release sign context, which sets it deliberately.)',
     });
 }
+function authBundleWrongBackendFinding(device, present) {
+    if (!present)
+        return null;
+    return finding({
+        severity: FINDING_SEVERITY['auth-bundle-wrong-backend'], kind: 'auth-bundle-wrong-backend', device,
+        message: "reserved secrets bundle 'auth' exists but is not file-backed — "
+            + 'usage/probe ignores the setup-tokens and falls through to the interactive login',
+    });
+}
 function execPolicyFinding(device, execPolicy) {
     if (!execPolicy || execPolicy.platform !== 'win32')
         return null;
@@ -1038,6 +1054,8 @@ function warningSubject(f) {
         return 'shell rc';
     if (f.kind === 'env-secret-export')
         return 'environment';
+    if (f.kind === 'auth-bundle-wrong-backend')
+        return 'auth bundle';
     if (f.kind === 'exec-policy')
         return 'PowerShell';
     if (f.kind === 'fleet-resource-gap')

package/dist/lib/exec.d.ts

@@ -1,4 +1,5 @@
 import type { AgentId, Mode } from './types.js';
+import { type UsernsStatus } from './linux-userns.js';
 /**
  * Agent execution modes. Canonical name `skip` (dangerously skip permissions);
  * `full` is accepted as a permanent silent alias via normalizeMode().
@@ -88,6 +89,33 @@ export interface ModeWarningState {
 export declare function defaultModeFor(agent: AgentId): Mode;
 /** Safe mode used when the user did not provide --mode or a configured default. */
 export declare function implicitModeFor(agent: AgentId): ExecMode;
+/**
+ * Preflight for Codex's Linux sandbox. Codex ≥0.146 sandboxes `read-only` and
+ * `workspace-write` runs with a bundled bubblewrap that needs an unprivileged
+ * user namespace; on a box that restricts it (Ubuntu 24.04
+ * `apparmor_restrict_unprivileged_userns=1`) bwrap dies with "setting up uid map:
+ * Permission denied" and a HEADLESS codex run lands zero tools — no file writes,
+ * no shell — while still reporting a completed turn. That silent under-delivery
+ * is what breaks `agents teams` codex teammates (always headless + workspace-write)
+ * and headless `agents run codex` alike on the fleet. Returns a loud, actionable
+ * message to fail the launch with instead of spawning that doomed run; returns
+ * null when the run is fine to proceed.
+ *
+ * Deliberately scoped: only `codex`, only Linux, only a HEADLESS run (an
+ * interactive TUI surfaces the bwrap error to the operator itself), and only a
+ * SANDBOXED mode — `skip` is codex `--dangerously-bypass-approvals-and-sandbox`,
+ * which uses no bwrap and is unaffected. The intended auto=workspace-write config
+ * is never weakened here; the run fails loud rather than silently downgrading.
+ * PHNX-3285.
+ */
+export declare function codexSandboxPreflight(args: {
+    agent: AgentId;
+    platform: NodeJS.Platform;
+    interactive: boolean;
+    mode: Mode;
+    userns: UsernsStatus;
+    machine: string;
+}): string | null;
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */

package/dist/lib/exec.js

@@ -32,6 +32,7 @@ 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';
+import { probeUnprivilegedUserns } from './linux-userns.js';
 import { resolveClaudeSetupToken } from './claude-account-token.js';
 import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
@@ -181,6 +182,49 @@ export function defaultModeFor(agent) {
 export function implicitModeFor(agent) {
     return agent === 'codex' ? 'edit' : 'plan';
 }
+/**
+ * Preflight for Codex's Linux sandbox. Codex ≥0.146 sandboxes `read-only` and
+ * `workspace-write` runs with a bundled bubblewrap that needs an unprivileged
+ * user namespace; on a box that restricts it (Ubuntu 24.04
+ * `apparmor_restrict_unprivileged_userns=1`) bwrap dies with "setting up uid map:
+ * Permission denied" and a HEADLESS codex run lands zero tools — no file writes,
+ * no shell — while still reporting a completed turn. That silent under-delivery
+ * is what breaks `agents teams` codex teammates (always headless + workspace-write)
+ * and headless `agents run codex` alike on the fleet. Returns a loud, actionable
+ * message to fail the launch with instead of spawning that doomed run; returns
+ * null when the run is fine to proceed.
+ *
+ * Deliberately scoped: only `codex`, only Linux, only a HEADLESS run (an
+ * interactive TUI surfaces the bwrap error to the operator itself), and only a
+ * SANDBOXED mode — `skip` is codex `--dangerously-bypass-approvals-and-sandbox`,
+ * which uses no bwrap and is unaffected. The intended auto=workspace-write config
+ * is never weakened here; the run fails loud rather than silently downgrading.
+ * PHNX-3285.
+ */
+export function codexSandboxPreflight(args) {
+    if (args.agent !== 'codex')
+        return null;
+    if (args.platform !== 'linux')
+        return null;
+    if (args.interactive)
+        return null;
+    if (args.mode === 'skip')
+        return null;
+    if (args.userns.state !== 'blocked')
+        return null;
+    const reason = args.userns.reason ?? 'unprivileged user namespaces are restricted';
+    return (`codex's Linux sandbox can't start on ${args.machine}: ${reason}, so codex's ` +
+        `bundled bubblewrap fails with "bwrap: setting up uid map: Permission denied" ` +
+        `and a headless run lands zero tools. (PHNX-3285)\n` +
+        `\n` +
+        `Enable it once on this box — keeps codex's workspace-write sandbox intact:\n` +
+        `  echo 'kernel.apparmor_restrict_unprivileged_userns=0' | sudo tee /etc/sysctl.d/60-codex-userns.conf\n` +
+        `  sudo sysctl --system\n` +
+        `  # verify: unshare --user --map-root-user true   (exit 0 = fixed)\n` +
+        `(agents-cli ships cli/scripts/enable-codex-sandbox.sh to apply + verify this.)\n` +
+        `\n` +
+        `Or run codex WITHOUT a filesystem sandbox instead: add --mode skip.`);
+}
 /**
  * Identity a custom-harness run stamps on env / pid-registry / sidecars.
  * `agent` is the host CLI; `harnessName` is the profile the user launched.
@@ -797,8 +841,13 @@ export function buildExecCommand(options) {
     // that maps to reasoning effort on a single-model harness (e.g. Grok, where the
     // tier IS the effort dial). `modelVersion` is null when no version resolves;
     // `tierModel` is the concrete model a tier resolved to (null => drop the flag).
+    // Prefer the user's explicit --model. Codex falls back to ~/.codex/config.toml
+    // (per-version CODEX_HOME may not carry that setting). OpenCode has no model
+    // env var — a custom-harness pin lives in OPENCODE_MODEL and must become
+    // `--model` here, or the host silently uses its configured default (PHNX-2577).
     const effectiveModel = options.model
-        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined);
+        ?? (options.agent === 'codex' ? readCodexConfiguredModel() : undefined)
+        ?? (options.agent === 'opencode' ? options.env?.OPENCODE_MODEL : undefined);
     const modelVersion = effectiveModel && template.modelFlag
         ? (options.version || resolveVersion(options.agent, options.cwd || process.cwd()))
         : null;
@@ -906,12 +955,8 @@ export function buildExecCommand(options) {
     else if (options.sessionId && options.agent === 'claude') {
         cmd.push('--session-id', options.sessionId);
     }
-    // Add model. Prefer the user's explicit --model. Otherwise, for Codex, fall
-    // back to the model configured in the user's active ~/.codex/config.toml:
-    // Codex runs under a per-version CODEX_HOME (see buildExecEnv) that may not
-    // carry that setting, so without this it silently defaults to gpt-5.3-codex,
-    // which a ChatGPT-tier account can't use (HTTP 400). Forwarding keeps the
-    // user's default model setup for both `agents run` and `agents teams`.
+    // Add model. `effectiveModel` already preferred --model, then Codex's
+    // configured default, then an OpenCode custom-harness pin (OPENCODE_MODEL).
     if (effectiveModel && template.modelFlag) {
         if (tierResolved) {
             // Cost tier (cheap|default|best|ultra) -> a concrete model this harness+
@@ -1653,6 +1698,27 @@ async function spawnAgent(options) {
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
     const interactive = resolveInteractive(options);
+    // Fail loud before spawning a headless codex whose Linux sandbox can't start —
+    // otherwise it burns a turn and lands zero tools (PHNX-3285). Cheap gate first
+    // so the userns probe (one `unshare`) runs only for the exact case it applies to
+    // (codex + Linux + headless + a sandboxed mode), never for every spawn.
+    if (options.agent === 'codex' && process.platform === 'linux' && !interactive) {
+        const codexMode = options.mode ? normalizeMode(options.mode) : defaultModeFor(options.agent);
+        if (codexMode !== 'skip') {
+            const message = codexSandboxPreflight({
+                agent: options.agent,
+                platform: process.platform,
+                interactive,
+                mode: codexMode,
+                userns: probeUnprivilegedUserns(),
+                machine: machineId(),
+            });
+            if (message) {
+                process.stderr.write(`\x1b[31m${message}\x1b[0m\n`);
+                return { exitCode: 1, stdout: '', stderr: message };
+            }
+        }
+    }
     // Budget live kill-switch (issue #346). For headless runs we incrementally
     // parse stream-json usage off stdout, accumulate cost, and kill the child the
     // moment a configured cap is crossed — exactly like the --timeout path, but