@phnx-labs/agents-cli 1.22.52 → 1.22.54

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/devices/registry.d.ts

@@ -176,10 +176,12 @@ export declare function removeDevice(name: string): Promise<boolean>;
  */
 export type { IgnoredDeviceEntry } from '../fleet/types.js';
 /**
- * The full ignore-list entries — who dismissed a node, when, and on which box —
- * the typed read side for `agents devices ignored`. Absent `fleet.ignored` =>
- * []. A malformed block is a hard error for the same reason the registry is:
- * silently returning [] would let the next write wipe the user's dismissals.
+ * The EFFECTIVE ignore-list: the union of every box's device doc
+ * `fleet.ignored` (deduped by node name, newest `ignoredAt` winning) plus any
+ * lingering central-legacy `fleet.ignored` block (drained by the migration).
+ * Deterministic and order-independent. A malformed block is a hard error for the
+ * same reason the registry is: silently returning [] would let the next write
+ * wipe the user's dismissals.
  */
 export declare function loadIgnoredEntries(meta?: Meta): IgnoredDeviceEntry[];
 /** Load the set of ignored node names. Same corruption contract as
@@ -195,7 +197,11 @@ export declare function isIgnored(name: string): Promise<boolean>;
  * lib/devices/config-migration.ts.
  */
 export declare function withIgnoredAdded(meta: Meta, names: string[], ignoredAt: string): Meta;
-/** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
+/** Add a node name to THIS box's ignore-list (device doc). Idempotent. Returns
+ * the resulting cross-box union of dismissed names. Reads only the device docs
+ * for the return value — a corrupt central-legacy block surfaces loudly on the
+ * effective read path ({@link loadIgnoredEntries}), never blocks a per-box
+ * write that does not touch central at all. */
 export declare function addIgnored(name: string): Promise<Set<string>>;
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was
  * not ignored. */

package/dist/lib/devices/registry.js

@@ -20,6 +20,7 @@ import lockfile from 'proper-lockfile';
 import { getDevicesRegistryPath, readMeta, updateMeta } from '../state.js';
 import { atomicWriteJsonSync } from '../fs-atomic.js';
 import { machineId } from '../machine-id.js';
+import { addIgnoredEntry, unionDeviceIgnored } from './device-docs.js';
 /**
  * Whether a fan-out should dial this device, honouring the preference stated on
  * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
@@ -287,19 +288,48 @@ export async function removeDevice(name) {
  * []. A malformed block is a hard error for the same reason the registry is:
  * silently returning [] would let the next write wipe the user's dismissals.
  */
-export function loadIgnoredEntries(meta = readMeta()) {
-    const raw = meta.fleet?.ignored;
-    if (raw === undefined)
-        return [];
+/** Validate a raw ignore-list block, or throw with `where` naming the file. */
+function assertIgnoredShape(raw, where) {
     if (!Array.isArray(raw) ||
         raw.some((e) => !e ||
             typeof e.name !== 'string' ||
             typeof e.ignoredAt !== 'string' ||
             typeof e.ignoredOn !== 'string')) {
-        throw new Error(`Device ignore-list corrupted in agents.yaml (fleet.ignored): expected a list of { name, ignoredAt, ignoredOn } entries. Inspect and repair ~/.agents/agents.yaml.`);
+        throw new Error(`Device ignore-list corrupted in ${where}: expected a list of { name, ignoredAt, ignoredOn } entries. Inspect and repair it.`);
     }
+}
+/**
+ * THIS box's OWN dismissals — the writable slice in `meta.deviceFleet.ignored`
+ * (the device doc). `withIgnoredAdded`/`removeIgnored` operate on this so a box
+ * only ever edits its own folder (PHNX-3315). Absent => [].
+ */
+function loadOwnIgnoredEntries(meta) {
+    const raw = meta.deviceFleet?.ignored;
+    if (raw === undefined)
+        return [];
+    assertIgnoredShape(raw, `devices/<machine>/agents.yaml (fleet.ignored)`);
     return raw;
 }
+/**
+ * The EFFECTIVE ignore-list: the union of every box's device doc
+ * `fleet.ignored` (deduped by node name, newest `ignoredAt` winning) plus any
+ * lingering central-legacy `fleet.ignored` block (drained by the migration).
+ * Deterministic and order-independent. A malformed block is a hard error for the
+ * same reason the registry is: silently returning [] would let the next write
+ * wipe the user's dismissals.
+ */
+export function loadIgnoredEntries(meta = readMeta()) {
+    const byName = new Map();
+    const central = meta.fleet?.ignored;
+    if (central !== undefined) {
+        assertIgnoredShape(central, `agents.yaml (fleet.ignored)`);
+        for (const e of central)
+            addIgnoredEntry(byName, e);
+    }
+    for (const e of unionDeviceIgnored())
+        addIgnoredEntry(byName, e);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
 /** Load the set of ignored node names. Same corruption contract as
  * {@link loadIgnoredEntries}. */
 export async function loadIgnored() {
@@ -317,40 +347,38 @@ export async function isIgnored(name) {
  * lib/devices/config-migration.ts.
  */
 export function withIgnoredAdded(meta, names, ignoredAt) {
-    const entries = loadIgnoredEntries(meta); // throws on a corrupted block — never wipe it
+    const entries = loadOwnIgnoredEntries(meta); // throws on a corrupted block — never wipe it
     const have = new Set(entries.map((e) => e.name));
     const fresh = names.filter((n) => !have.has(n));
     if (fresh.length === 0)
         return meta;
-    const fleet = (meta.fleet ?? { devices: {} });
     const ignored = [
         ...entries,
         ...fresh.map((name) => ({ name, ignoredAt, ignoredOn: machineId() })),
     ].sort((a, b) => a.name.localeCompare(b.name));
-    const nextFleet = { ...fleet, ignored };
-    return { ...meta, fleet: nextFleet };
+    return { ...meta, deviceFleet: { ...meta.deviceFleet, ignored } };
 }
-/** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
+/** Add a node name to THIS box's ignore-list (device doc). Idempotent. Returns
+ * the resulting cross-box union of dismissed names. Reads only the device docs
+ * for the return value — a corrupt central-legacy block surfaces loudly on the
+ * effective read path ({@link loadIgnoredEntries}), never blocks a per-box
+ * write that does not touch central at all. */
 export async function addIgnored(name) {
     assertValidDeviceName(name);
-    const meta = updateMeta((m) => withIgnoredAdded(m, [name], new Date().toISOString()));
-    return new Set(loadIgnoredEntries(meta).map((e) => e.name));
+    updateMeta((m) => withIgnoredAdded(m, [name], new Date().toISOString()));
+    return new Set(unionDeviceIgnored().map((e) => e.name));
 }
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was
  * not ignored. */
 export async function removeIgnored(name) {
     let removed = false;
     updateMeta((m) => {
-        const fleet = m.fleet;
-        if (!fleet?.ignored)
-            return m;
-        const entries = loadIgnoredEntries(m);
+        const entries = loadOwnIgnoredEntries(m); // only this box's own dismissals are ours to drop
         const next = entries.filter((e) => e.name !== name);
         if (next.length === entries.length)
             return m;
         removed = true;
-        const nextFleet = { ...fleet, ignored: next };
-        return { ...m, fleet: nextFleet };
+        return { ...m, deviceFleet: { ...m.deviceFleet, ignored: next } };
     });
     return removed;
 }

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,11 +89,46 @@ 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. */
 export interface ExecOptions {
     agent: AgentId;
+    /**
+     * Custom harness / profile name when this run was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `agent` stays the HOST CLI
+     * that actually executes. Stamped onto `AGENTS_AGENT_NAME`, the pid
+     * registry, and the session-actor sidecar so listings can tell the
+     * profile apart from a native host run (PHNX-2935).
+     */
+    harnessName?: string;
     version?: string;
     /** Version home whose native auth/config is overlaid onto this run's binary. */
     configVersion?: string;
@@ -177,6 +213,18 @@ export interface ExecOptions {
      */
     raw?: boolean;
 }
+/**
+ * Identity a custom-harness run stamps on env / pid-registry / sidecars.
+ * `agent` is the host CLI; `harnessName` is the profile the user launched.
+ * Empty/whitespace harness names fall back to the host so a blank stamp
+ * never hides a real agent.
+ */
+export declare function stampedAgentName(options: Pick<ExecOptions, 'agent' | 'harnessName'>): string;
+/**
+ * Profile name when it differs from the host agent. Undefined for a native
+ * run, so pid-registry / sidecar records stay sparse.
+ */
+export declare function customHarnessName(options: Pick<ExecOptions, 'agent' | 'harnessName'>): string | undefined;
 /**
  * Resolve interactive vs headless. Explicit flags are definitive and win over
  * inference: `--interactive` forces interactive, `--headless` forces headless.
@@ -406,15 +454,18 @@ export interface TmuxWrapContext {
      * 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.
+     * Since PHNX-3316 this flag no longer forces the wrap: `tmux.enabled` gates
+     * local and remote runs alike, because the operator reading "tmux disabled"
+     * expects NO tmux anywhere. A followed remote run left bare is protected by
+     * reconnect-and-resume (lib/hosts/reconnect.ts): a dropped link costs the
+     * in-flight turn, and the harness session resumes from disk.
+     *
+     * The flag still matters for one case: a followed remote run whose LAUNCHER
+     * has no TTY (CI, a script, another agent driving the CLI — `sshStream`
+     * allocates the peer's TTY from `process.stdin.isTTY`, dispatch.ts) gets no
+     * TTY on the peer either, so there is nothing to attach to and the detached
+     * pane is the run's only interface — it wraps regardless of `configEnabled`
+     * (and is refused as `undurable` when tmux is missing).
      */
     remoteDispatch: boolean;
     /** Whether a tmux binary is on PATH. */
@@ -423,16 +474,19 @@ export interface TmuxWrapContext {
      * True when this process has a real TTY to attach (`stdout.isTTY`).
      * A piped `agents run --interactive` (session-tracker tests, CI) has none:
      * wrapping then treating the failed attach as Ctrl-b d leaked live panes
-     * for a week on yosemite-s0 (PHNX-3293). Remote dispatch still wraps
-     * without a TTY — `--device --no-follow` *wants* a detached pane.
+     * for a week on yosemite-s0 (PHNX-3293). A remote dispatch still wraps
+     * without a TTY — a launcher that has none (CI, scripts, another agent)
+     * gives the peer nothing to attach to, so the detached pane is the run's
+     * only interface.
      */
     hasTty: 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.
+ * What to do with an interactive spawn. Three outcomes, not two: a remote run
+ * that WOULD wrap (the operator opted in, or a `--no-follow` run whose only
+ * interface is the detached pane) on a box with no tmux 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. */
@@ -443,7 +497,7 @@ export type TmuxWrapDecision =
  | {
     kind: 'bare';
 }
-/** Remote-dispatched and tmux is missing on this box: refuse, don't pretend. */
+/** Remote-dispatched, wants the wrap, and tmux is missing: refuse, don't pretend. */
  | {
     kind: 'undurable';
 };
@@ -451,20 +505,24 @@ export type TmuxWrapDecision =
  * 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.
  *
- * Wrapping serves two independent purposes, and they are gated differently:
- *
- *  - **Addressability** (`configEnabled`): a unique `%pane` handle so
- *    `agents sessions --active` can tell co-located agents apart and `agents
- *    focus` re-attaches without forking. That is a local preference — the
- *    operator turns it on once tmux's mouse/clipboard/scrollback suits them.
- *  - **Durability** (`remoteDispatch`): a run that arrived over SSH must outlive
- *    the SSH client, because a bare remote spawn dies of SIGHUP the moment the
- *    link blinks. That is not a preference, so it does not consult
- *    `configEnabled` (RUSH-3125 — see {@link TmuxWrapContext.remoteDispatch}).
- *
- * The per-run opt-outs bind BOTH: `--raw` / `--no-tmux` / `AGENTS_NO_TMUX=1` are
- * explicit "I want the bare process" requests, and honouring them over the
- * durability rule keeps one escape hatch that always works.
+ * The wrap is opt-in via this device's `tmux.enabled` (`configEnabled`): a
+ * unique `%pane` handle so `agents sessions --active` can tell co-located
+ * agents apart and `agents focus` re-attaches without forking, plus scrollback
+ * and mouse at the operator's keyboard. Off means OFF, for local and remote
+ * runs alike (PHNX-3316) — a followed `--device` run left bare is protected by
+ * reconnect-and-resume (lib/hosts/reconnect.ts), which rejoins the live pane
+ * when one exists and resumes the harness session from disk when it does not.
+ * The RUSH-3125 forced remote wrap conflated durability with that preference
+ * and surprised every operator who had explicitly left tmux off.
+ *
+ * One case still wraps regardless: a followed remote run whose launcher has
+ * no TTY (CI, scripts, another agent) gives the peer nothing to attach to —
+ * the detached pane is the run's only interface, not an ergonomics choice.
+ *
+ * The per-run opt-outs bind everything: `--raw` / `--no-tmux` /
+ * `AGENTS_NO_TMUX=1` are explicit "I want the bare process" requests, and an
+ * escape hatch that silently stopped applying over `--device` would be worse
+ * than the bare run the user asked for.
  *
  * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
  */