@phnx-labs/agents-cli 1.22.52 → 1.22.53

package/dist/lib/devices/discovery-policy.js

@@ -1,5 +1,6 @@
 /** Synced device approval/ignore policy and local registry reconciliation. */
 import { readMeta, updateMeta } from '../state.js';
+import { unionDeviceDiscovery } from './device-docs.js';
 import { addIgnored, assertValidDeviceName, loadDevices, removeDevice, removeIgnored, upsertDevice, } from './registry.js';
 import { localLoginUser, withDefaultUser } from './sync.js';
 import { nodeToDeviceInput, parseTailscaleStatus, tailscaleStatusJson } from './tailscale.js';
@@ -8,36 +9,46 @@ export function getDeviceDiscoveryStatus(name) {
     assertValidDeviceName(name);
     return loadDeviceDiscoveryPolicies().get(name);
 }
-/** Persist one portable decision in the central fleet manifest. */
+/**
+ * Persist ONE discovery decision in THIS box's device doc (PHNX-3315). Each box
+ * records only its own choices in `devices/<machine>/agents.yaml` `fleet.discovery`,
+ * so N boxes no longer rewrite one shared central map (the guaranteed pull
+ * conflict). The effective policy is the union across every box
+ * ({@link loadDeviceDiscoveryPolicies}).
+ */
 export function setDeviceDiscoveryStatus(name, status) {
     assertValidDeviceName(name);
     updateMeta((meta) => {
-        const discovery = { ...meta.fleet?.discovery };
+        const discovery = { ...meta.deviceFleet?.discovery };
         if (status)
             discovery[name] = status;
         else
             delete discovery[name];
-        const fleet = {
-            ...meta.fleet,
-            devices: meta.fleet?.devices ?? {},
-            // Keep an empty map as the synced tombstone: it distinguishes "policy is
-            // authoritative and every device is pending" from an older config that
-            // has never opted into portable discovery decisions.
-            discovery,
-        };
-        return { ...meta, fleet };
+        return { ...meta, deviceFleet: { ...meta.deviceFleet, discovery } };
     });
 }
-/** Load every explicit decision from the synced central fleet manifest. */
+/**
+ * The effective discovery policy: the UNION across every box's device doc, plus
+ * any lingering central-legacy map (drained by the fold-then-delete migration).
+ * Precedence for a name declared by more than one box is deterministic and
+ * order-independent — `ignored` beats `approved` — so every box computes the
+ * identical policy. Absence means pending.
+ */
 export function loadDeviceDiscoveryPolicies() {
     const policies = new Map();
-    for (const [name, status] of Object.entries(readMeta().fleet?.discovery ?? {})) {
-        assertValidDeviceName(name);
-        if (status !== 'approved' && status !== 'ignored') {
-            throw new Error(`Device discovery policy for '${name}' must be approved or ignored.`);
+    const apply = (rec) => {
+        for (const [name, status] of Object.entries(rec ?? {})) {
+            assertValidDeviceName(name);
+            if (status !== 'approved' && status !== 'ignored') {
+                throw new Error(`Device discovery policy for '${name}' must be approved or ignored.`);
+            }
+            if (policies.get(name) === 'ignored')
+                continue; // ignored is never downgraded
+            policies.set(name, status);
         }
-        policies.set(name, status);
-    }
+    };
+    apply(readMeta().fleet?.discovery); // central legacy, until the migration drains it
+    apply(unionDeviceDiscovery()); // per-box device docs (ignored still wins)
     return policies;
 }
 /**
@@ -55,11 +66,10 @@ export function loadDeviceDiscoveryPolicies() {
  * that never meant to touch them.
  */
 export async function reconcileDeviceDiscoveryPolicies() {
-    const configured = readMeta().fleet?.discovery;
-    if (configured === undefined) {
+    const policies = loadDeviceDiscoveryPolicies();
+    if (policies.size === 0) {
         return { approved: [], ignored: [], registered: [], unresolved: [] };
     }
-    const policies = loadDeviceDiscoveryPolicies();
     const approved = [...policies].filter(([, s]) => s === 'approved').map(([n]) => n).sort();
     const ignored = [...policies].filter(([, s]) => s === 'ignored').map(([n]) => n).sort();
     for (const name of ignored) {

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

@@ -93,6 +93,14 @@ 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 +185,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 +426,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 +446,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 +469,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 +477,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.
  */

package/dist/lib/exec.js

@@ -181,6 +181,26 @@ export function defaultModeFor(agent) {
 export function implicitModeFor(agent) {
     return agent === 'codex' ? 'edit' : 'plan';
 }
+/**
+ * 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 function stampedAgentName(options) {
+    const harness = options.harnessName?.trim();
+    return harness || options.agent;
+}
+/**
+ * Profile name when it differs from the host agent. Undefined for a native
+ * run, so pid-registry / sidecar records stay sparse.
+ */
+export function customHarnessName(options) {
+    const harness = options.harnessName?.trim();
+    if (!harness || harness === options.agent)
+        return undefined;
+    return harness;
+}
 /**
  * Resolve interactive vs headless. Explicit flags are definitive and win over
  * inference: `--interactive` forces interactive, `--headless` forces headless.
@@ -346,8 +366,11 @@ export function buildExecEnv(options) {
     result.AGENTS_RUN_MODE = resolveHeadlessMode(options.agent, normalizeMode(options.mode), resolveInteractive(options), options.modeWarningContext, options.modeWarningState);
     result.AGENTS_HISTORY_DIR = getHistoryDir();
     // So activity / feed posts stamp the right harness without re-detecting.
+    // A custom-harness run (`agents run deepseek`) must stamp the PROFILE name,
+    // not the host CLI (`claude`) — otherwise sessions and feed posts cannot
+    // tell the two apart (PHNX-2935).
     if (options.agent) {
-        result.AGENTS_AGENT_NAME = options.agent;
+        result.AGENTS_AGENT_NAME = stampedAgentName(options);
     }
     if (options.cwd) {
         result.AGENTS_CWD = options.cwd;
@@ -1176,36 +1199,38 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * Wrapping serves two independent purposes, and they are gated differently:
+ * 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.
  *
- *  - **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}).
+ * 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 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 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.
  */
 export function resolveTmuxWrap(ctx) {
     // A headless `-p` run has no TTY to attach, Windows has no tmux path, and
-    // nesting tmux-in-tmux is pointless — none of these can wrap, and none of them
-    // is a remote interactive agent whose life depends on it.
+    // nesting tmux-in-tmux is pointless.
     if (!ctx.interactive)
         return { kind: 'bare' };
     if (ctx.platform === 'win32')
         return { kind: 'bare' };
     if (ctx.inTmux)
         return { kind: 'bare' };
-    // Explicit opt-outs win over the durability rule: `--raw` exists precisely to
-    // get the unwrapped process, and a flag that silently stopped working on a
-    // remote box would be worse than an undurable run the user asked for.
+    // Explicit opt-outs win over every other rule: `--raw` exists precisely to
+    // get the unwrapped process.
     if (ctx.raw)
         return { kind: 'bare' };
     if (ctx.noTmuxEnv)
@@ -1213,10 +1238,13 @@ export function resolveTmuxWrap(ctx) {
     // Local interactive with no TTY cannot attach. Wrapping anyway creates a
     // detached pane, attach returns immediately, and resolveAfterAttach treats
     // the still-alive pane as Ctrl-b d — the session-tracker test leak.
-    // Remote dispatch is the exception: --no-follow *intends* a detached pane.
     if (!ctx.hasTty && !ctx.remoteDispatch)
         return { kind: 'bare' };
-    if (!ctx.configEnabled && !ctx.remoteDispatch)
+    // tmux.enabled gates the wrap for local AND followed remote runs. The one
+    // exception: a followed remote run whose launcher has no TTY (CI, scripts)
+    // gives the peer nothing to attach to — the detached pane is its only
+    // interface, infrastructure rather than ergonomics.
+    if (!ctx.configEnabled && !(ctx.remoteDispatch && !ctx.hasTty))
         return { kind: 'bare' };
     // Fail loud rather than launch a remote agent that a blink would kill: the
     // caller refuses the run instead of starting work that cannot be recovered.
@@ -1520,6 +1548,7 @@ async function runInTmux(options, executable, args) {
         writePidSessionEntry({
             pid: panePid,
             agent: options.agent,
+            harness: customHarnessName(options),
             sessionId: options.sessionId,
             cwd,
             actor: resolveActor().id,
@@ -1538,6 +1567,7 @@ async function runInTmux(options, executable, args) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });
         }
@@ -1662,9 +1692,10 @@ async function spawnAgent(options) {
         args: redactArgs(args.slice(0, 10)),
     });
     // Interactive spawn-wrap: run the agent INSIDE a shared-socket tmux session
-    // (then attach this TTY) so it gets a unique, addressable %pane — and, when
-    // the run arrived over `--device`, so it survives the SSH link that carries
-    // it. Every failed guard keeps the bare spawn below.
+    // (then attach this TTY) so it gets a unique, addressable %pane. Opt-in via
+    // this device's tmux.enabled, local and remote alike (PHNX-3316); a followed
+    // remote run left bare relies on reconnect-and-resume, not a pane. Every
+    // failed guard keeps the bare spawn below.
     const tmuxWrap = resolveTmuxWrap({
         interactive,
         platform: process.platform,
@@ -1683,10 +1714,15 @@ async function spawnAgent(options) {
         // there is no launcher-side probe ahead of this one. Failing here still
         // fails before the agent starts, which is what matters; a pre-dispatch
         // probe would only move the message earlier, at the cost of a round trip on
-        // every launch.
-        const msg = `agents: ${machineId()} has no tmux, so a --device run here could not survive a dropped connection.\n`
-            + `  install it:            (apt|dnf|brew) install tmux\n`
-            + `  or accept the risk:    agents run … --device ${machineId()} --raw\n`;
+        // every launch. Reached only when the wrap was wanted: the device opted in
+        // via tmux.enabled, or a followed run whose launcher had no TTY (CI,
+        // scripts) left the peer nothing to attach to, so the pane is its stdout.
+        // The config tip uses the ssh form because tmux.enabled is machine-local:
+        // setting it from the launcher throws (assertLocalTarget).
+        const msg = `agents: ${machineId()} has no tmux, so this --device run cannot get the pane it needs.\n`
+            + `  install it:              (apt|dnf|brew) install tmux\n`
+            + `  or turn the wrap off:    agents ssh ${machineId()} 'agents devices config ${machineId()} tmux.enabled off'\n`
+            + `  or accept a bare run:    agents run … --device ${machineId()} --raw\n`;
         process.stderr.write(`\x1b[31m${msg}\x1b[0m`);
         timer.end({ exitCode: 1, status: 'failed', error: 'remote interactive run has no tmux for durability' });
         return { exitCode: 1, stdout: '', stderr: msg };
@@ -1737,6 +1773,7 @@ async function spawnAgent(options) {
         writePidSessionEntry({
             pid: child.pid ?? 0,
             agent: options.agent,
+            harness: customHarnessName(options),
             sessionId: options.sessionId,
             cwd: options.cwd || process.cwd(),
             actor: resolveActor().id,
@@ -1751,6 +1788,7 @@ async function spawnAgent(options) {
                 sessionId: options.sessionId,
                 actor: resolveActor().id,
                 initiatedBy: resolveActor().kind,
+                harness: customHarnessName(options),
                 startedAtMs: Date.now(),
             });
         }