@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/README.md

@@ -270,10 +270,15 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 | `d` | device (cycles) | `--device` |
 | `p` | this repo ↔ all dirs | `--all` |
 | `w` | time window | `--since` |
+| `tab` | toggle the preview pane | — |
 | `⏎` | resume / attach | `resume` / `focus` |
 | `y` | copy the equivalent command | `--print-cmd` |
 
-Filters **stack** (they AND together), the active set shows in the header, and the highlighted row previews below. Because every hotkey has a flag, the view you build by hand is a real command: press `y` (or run `--print-cmd`) to get the exact `ag sessions …` line — explore interactively, hand the line to an agent. Piped output, `--json`, or `--no-interactive` keep the plain listing for scripts. Peek without opening the pager with `agents sessions <id> --preview`.
+Filters **stack** (they AND together), the active set shows in the header, and the highlighted row **previews below by default** (`tab` hides it) — prompt, activity, last response, plus a links line where the worked-on ticket and the PR the session opened are **clickable** (OSC 8 hyperlinks: the ticket jumps to Linear, the `PR#` to GitHub, in terminals that support them). The Linear workspace is resolved from `LINEAR_WORKSPACE` or the linear-cli config, so tickets stay plain text when it's unknown. Because every hotkey has a flag, the view you build by hand is a real command: press `y` (or run `--print-cmd`) to get the exact `ag sessions …` line — explore interactively, hand the line to an agent. Piped output, `--json`, or `--no-interactive` keep the plain listing for scripts. Peek without opening the pager with `agents sessions <id> --preview`.
+
+| before — preview hidden | after — preview open + clickable links |
+| --- | --- |
+| ![sessions browser, preview hidden](assets/demos/sessions-preview-before.png) | ![sessions browser, preview open with a links line](assets/demos/sessions-preview-after.png) |
 
 Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), or `idle`, alongside badges for the PR it opened, the worktree it sits in, and the ticket it's working. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
 
@@ -292,6 +297,17 @@ agents sessions resume --host zion --tmux  # resume on another machine over SSH
 
 `agents sessions resume` reopens sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
 
+### Send an agent to the background — and bring it back
+
+Running 30 agents and drowning in terminal tabs? `agents sessions detach <id>` stops a session's interactive process and keeps it working **headless** in the background -- it drives its task to done unattended, no tab, lower cost. `agents sessions attach <id>` brings it back: version-pinned resume into a live TUI, the same session and full history (including whatever it did while backgrounded).
+
+```
+agents sessions detach a1b2c3d4     # go headless in the background, keep working
+agents sessions attach a1b2c3d4     # resume it interactively, right here
+```
+
+Both are agent-agnostic -- they route through the same `agents run --resume` path (native resume for Claude/Codex, `/continue` replay for the rest). `agents sessions --active` marks each session's `presence` -- `attached` (you're watching it), `background` (running headless), or `parked` (its background run finished) -- so the menu bar and Factory show where every agent is. In the Factory extension, **Agents: Detach** (`Cmd/Ctrl+K B`) and **Agents: Attach** (`Cmd/Ctrl+K A`) do the same over the focused terminal.
+
 ---
 
 ## Control the fleet
@@ -319,6 +335,7 @@ agents feed --flat                  # one row per agent (legacy)
 agents feed --host mac-mini         # scope the view to one or more hosts
 agents feed --local                 # skip the SSH fan-out
 agents feed --json                  # blocks stamped with their outcome key
+agents feed post "halfway done"     # agent status post (auto session identity)
 ```
 
 Top-level questions and waiting notifications publish one atomic open-block record per session, including the mailbox id, host, runtime, and every answer option. The default view collapses agents under the **outcome** they serve (Linear ticket, PR, worktree slug, or Unassigned) so a 1,100-agent fleet reads as dozens of deliverables. Answered, resumed, and stopped blocks clear automatically; Task subagents are excluded. The rendered reply command uses the same mailbox id with `agents message`, so the decision routes back to the agent that asked it.
@@ -436,7 +453,8 @@ agents sync --host gpu-box              # make the remote machine current
 agents doctor --devices                 # readiness matrix for every registered device
 agents doctor --devices --json          # machine-readable fleet readiness
 agents doctor --device mac-mini         # same matrix, scoped to one device
-agents fleet status                     # warnings rollup + health/sync/version/Auth matrix (cache-first)
+agents fleet status                     # online/offline rollup + NEEDS ATTENTION + OS-grouped rows (cache-first)
+agents fleet status --verbose           # full per-device auth/CLI/sync/version grid
 agents fleet status --live              # force a live resource probe (alias of --refresh)
 agents fleet status --json --strict     # scriptable fleet health gate
 agents check --devices                  # CI drift gate across every registered device
@@ -468,13 +486,21 @@ this machine locally plus any device missing from the cache; pass `--refresh` (o
 shorter `--live`) to force a full live probe of every box. Cache-served output notes its
 age (`updated 2m ago — pass --refresh (--live) for a live probe`).
 
-`agents fleet status` adds an **Auth column** — which agent accounts are actually
-logged in, per device, read from the auth-health cache (no network). Four buckets keep
-it from crying wolf: `●live` (verified), `·present` (signed in but the agent has no
-live-probe endpoint — e.g. codex/grok — benign), `◐degraded` (soft/self-healing:
-expired-but-refreshing, rate-limited), and `○revoked` (server rejected — re-login now).
-Only `○` means a real re-login is needed. Run `agents fleet ping` to force a live
-re-verification across the fleet.
+`agents fleet status` answers "is my fleet OK?" at a glance: a one-line rollup
+(`● N online · ○ M offline`), a short **NEEDS ATTENTION** list where every item names
+the command that fixes it (offline → `check the box`, config drift or a stark CLI gap →
+`agents apply <box>`, version skew → `agents upgrade --fleet`), then quiet per-device
+rows grouped by OS (macOS / Linux / Windows) showing just `name · capacity · load/mem ·
+version`, with this machine flagged `▸ … ← this machine`. A healthy fleet reads in a few
+lines; orphaned versions are demoted to a one-line `agents prune` nudge in the footer.
+
+Pass `--verbose` for the full per-device grid — the **Auth column** (which agent accounts
+are actually logged in, per device, read from the auth-health cache — no network), plus
+the CLI-readiness and sync-drift columns. The Auth column has four buckets so it never
+cries wolf: `●live` (verified), `·present` (signed in but the agent has no live-probe
+endpoint — e.g. codex/grok — benign), `◐degraded` (soft/self-healing: expired-but-refreshing,
+rate-limited), and `○revoked` (server rejected — re-login now). Only `○` means a real
+re-login is needed. Run `agents fleet ping` to force a live re-verification across the fleet.
 
 **Hosts** (`agents hosts`) are git-synced dispatch targets in `agents.yaml`; **devices** (`agents devices`) are your Tailscale machines in a local registry. Both ride SSH and feed one host pool: devices appear in `agents hosts list` and capability routing without a second enrollment. On `--host` runs every `agents run` option is either forwarded (`--effort --env --timeout --loop …`), rejected loud (`--secrets` never crosses SSH implicitly), or consumed locally — nothing silently drops. See [docs/00-concepts.md](apps/cli/docs/00-concepts.md#devices--hosts).
 
@@ -1218,7 +1244,7 @@ Agents are defined in [src/lib/agents.ts](apps/cli/src/lib/agents.ts) -- each is
 | [`apps/cli`](apps/cli) | **The CLI** (this README) — version management, config sync, sessions, teams, cloud, browser, computer, secrets. |
 | [`apps/factory`](apps/factory) | **Factory** — a VS Code extension that spawns agent terminals as tabs and adds the Factory Floor dashboard. A separate product with its own publish identity. |
 | [`native/computer-mac`](native/computer-mac) · [`native/computer-win`](native/computer-win) | Native backends behind `agents computer` — Swift (macOS Accessibility + screen capture) and C#/.NET (Windows UI Automation). |
-| [`packages/session-tracker`](packages/session-tracker) | The `SessionStart` hook that writes live-session state the CLI reads back. |
+| [`packages/session-tracker`](packages/session-tracker) | The `SessionStart` hook that writes live-session state the **Factory extension** reads back (`apps/factory/src/core/liveSession.ts`) — not the CLI, which reads transcripts. |
 
 ## Contributing
 

package/dist/commands/apply.js

@@ -18,7 +18,8 @@ import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
 import { ensureDevicesRegistered } from '../lib/devices/sync.js';
 import { readFleetFile, resolveDesired } from '../lib/fleet/manifest.js';
 import { snapshotAuth, materializeAuth, parseAuthBundle, KEYCHAIN_BOUND_ON_MAC } from '../lib/fleet/auth-sync.js';
-import { agentIdOf, diffFleet, probeDevice, runFleetApply, pool, sourceHome, } from '../lib/fleet/apply.js';
+import { agentIdOf, diffFleet, probeDevice, runFleetApply, pool, sourceHome, expandAllSpecs, rosterNeedsVersions, } from '../lib/fleet/apply.js';
+import { listInstalledVersions } from '../lib/versions.js';
 /** Version of the running agents-cli — the fleet target version. */
 function localCliVersion() {
     try {
@@ -92,7 +93,7 @@ function renderPlan(plan) {
         const agentsCell = row.probe.reachable
             ? (() => {
                 const add = row.actions.filter((a) => a.kind === 'add-agent');
-                return add.length === 0 ? chalk.green(`ok ${row.desired.agents.length}/${row.desired.agents.length}`) : chalk.cyan('+ ' + add.map((a) => a.agent).join(','));
+                return add.length === 0 ? chalk.green(`ok ${row.desired.agents.length}/${row.desired.agents.length}`) : chalk.cyan('+ ' + add.map((a) => a.spec ?? a.agent).join(','));
             })()
             : chalk.gray('-');
         const configCell = row.probe.reachable
@@ -178,6 +179,15 @@ async function runApply(opts) {
         if (desired.length === 0)
             throw new Error(`Device '${opts.device}' is not a target in this manifest.`);
     }
+    // --agent overrides the roster for the targeted device(s): install exactly these
+    // specs instead of the manifest's. `claude@all` expands to every claude version
+    // installed on THIS machine, so a fresh box inherits the same version set. Pair
+    // with --device to seed one box; without it, every targeted device gets the set.
+    if (opts.agent && opts.agent.length > 0) {
+        const specs = expandAllSpecs(opts.agent, (id) => listInstalledVersions(id));
+        desired = desired.map((d) => ({ ...d, agents: specs }));
+        console.log(chalk.gray(`Roster override (--agent): ${specs.join(', ')}`));
+    }
     if (opts.login === false)
         desired = desired.map((d) => ({ ...d, login: 'skip' }));
     if (desired.length === 0) {
@@ -200,8 +210,9 @@ async function runApply(opts) {
     };
     // Probe every target device in parallel.
     const nameToProfile = new Map(desired.map((d) => [d.device, registry[d.device]]));
+    const withVersions = rosterNeedsVersions(desired);
     console.log(chalk.gray(`Probing ${desired.length} device(s)…`));
-    const probeList = await pool(desired, 6, async (d) => probeDevice(nameToProfile.get(d.device)));
+    const probeList = await pool(desired, 6, async (d) => probeDevice(nameToProfile.get(d.device), { withVersions }));
     const probes = new Map(probeList.map((p) => [p.device, p]));
     const targetCliVersion = localCliVersion();
     let plan = diffFleet(desired, probes, { targetCliVersion, sourceAuth, secretsBundles: manifest.secrets?.bundles });
@@ -280,6 +291,7 @@ export function configureApplyCommand(cmd) {
         .option('--dry-run', 'Alias for --plan')
         .option('-y, --yes', 'Skip the confirmation prompt')
         .option('--device <name>', 'Scope the apply to a single device')
+        .option('--agent <specs...>', 'Override the roster for targeted device(s): install these specs instead of the manifest\'s. Use `claude@all` to replicate every version installed on this machine.')
         .option('--only <dims>', 'Limit to dimensions: comma list of agents,config,login')
         .option('--no-login', 'Do not propagate logins')
         .addOption(new Option('--recv-auth', 'internal: receive an auth bundle on stdin').hideHelp())
@@ -309,6 +321,12 @@ export function registerApplyCommand(program) {
 
       # One device only
       agents apply --device yosemite-s1 -y
+
+      # Replicate every claude version on this machine onto a fresh box
+      agents apply --agent claude@all --device yosemite-s0 -y
+
+      # Install a specific pinned version on one device
+      agents apply --agent claude@2.1.207 --device yosemite-s0
     `,
     });
 }

package/dist/commands/attach.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agents sessions attach <id>` — bring a backgrounded (or parked) agent session
+ * back to the foreground: stop its headless continuation, then resume it
+ * interactively in this terminal. The resume is version-pinned native resume
+ * (claude/codex) or a `/continue` replay (others) — the same session, full
+ * history, the exact inverse of `agents sessions detach`.
+ */
+import type { Command } from 'commander';
+export declare function registerAttachCommand(program: Command): void;
+export declare function attachAction(id: string): Promise<void>;

package/dist/commands/attach.js

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+import { discoverSessions } from '../lib/session/discover.js';
+import { resumeSessionInPlace } from './sessions.js';
+import { readDetachRecord, clearDetachRecord, isHeadlessAlive } from '../lib/session/detached.js';
+export function registerAttachCommand(program) {
+    program
+        .command('attach')
+        .argument('<id>', 'Short or full id of the backgrounded/parked session to resume interactively')
+        .description('Bring a backgrounded agent to the foreground — resume it interactively here')
+        .action(async (id) => {
+        await attachAction(id);
+    });
+}
+export async function attachAction(id) {
+    const q = id.toLowerCase();
+    // Rich meta carries the pinned version + origin cwd the resume needs.
+    const metas = await discoverSessions({ all: true, since: '90d', limit: 2000 });
+    const meta = metas.find((m) => m.id === id) ?? metas.find((m) => m.id.toLowerCase().startsWith(q));
+    if (!meta) {
+        console.error(chalk.red(`No session matching "${id}".`));
+        console.error(chalk.gray('  See your sessions: agents sessions'));
+        process.exitCode = 1;
+        return;
+    }
+    // If it's backgrounded, stop the headless continuation first so two processes
+    // don't resume the same transcript at once.
+    const rec = readDetachRecord(meta.id);
+    if (rec) {
+        if (isHeadlessAlive(rec)) {
+            try {
+                process.kill(rec.headlessPid, 'SIGTERM');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        clearDetachRecord(meta.id);
+    }
+    console.log(chalk.gray(`Attaching ${meta.agent} ${meta.id.slice(0, 8)} — resuming interactively…`));
+    await resumeSessionInPlace(meta);
+}

package/dist/commands/computer.js

@@ -644,8 +644,8 @@ function registerSetupCommand(program) {
         console.log('');
         console.log('Next steps:');
         console.log('  1. Grant TCC permissions (one-time):');
-        console.log('     System Settings > Privacy & Security > Accessibility       — add Computer Helper.app');
-        console.log('     System Settings > Privacy & Security > Screen Recording    — add Computer Helper.app');
+        console.log('     System Settings > Privacy & Security > Accessibility       — add Agents Computer');
+        console.log('     System Settings > Privacy & Security > Screen Recording    — add Agents Computer');
         console.log('  2. Whitelist the apps the daemon may drive. Add a YAML under ~/.agents/permissions/groups/:');
         console.log('       name: computer');
         console.log('       allow:');
@@ -687,7 +687,7 @@ function registerStartCommand(program) {
         }
         if (!trusted) {
             console.log('');
-            console.log('Grant Accessibility + Screen Recording to Computer Helper.app, then run `agents computer start` again.');
+            console.log('Grant Accessibility + Screen Recording to Agents Computer, then run `agents computer start` again.');
         }
     });
 }

package/dist/commands/detach-core.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure core of `agents sessions detach` — the nudge, the resumed-run argv, and the id
+ * resolver. Kept import-light (only a type import) so it is unit-tested without
+ * loading the live-session discovery graph.
+ */
+import type { ActiveSession } from '../lib/session/active.js';
+/**
+ * The prompt the backgrounded run resumes with. Its whole job is to stop a
+ * now-unwatched agent from stalling on a confirmation nobody will answer: it
+ * tells the agent it is headless and to drive to done, or to stop and state a
+ * blocker (which surfaces as a waiting session the user can `attach`).
+ */
+export declare const BACKGROUND_NUDGE: string;
+/**
+ * Build the argv for the headless continuation `detach` spawns. Agent-agnostic
+ * and version-pinned by construction — it goes through the same `agents run
+ * --resume` path `attach` reverses.
+ */
+export declare function buildBackgroundArgv(agent: string, sessionId: string, cwd?: string): string[];
+/** What to do with a resolved session, given which machine we're on. */
+export type DetachTarget = {
+    kind: 'local';
+    sessionId: string;
+} | {
+    kind: 'remote';
+    machine: string;
+    sessionId: string;
+} | {
+    kind: 'refuse';
+    reason: string;
+};
+/**
+ * Decide how to detach a resolved session. Cloud and team sessions are refused
+ * (they have their own lifecycles); a session on another machine is delegated to
+ * that host over SSH — never stopped/resumed locally, since its pid and tmux
+ * socket only mean something where it actually runs. Pure, so every branch is
+ * unit-tested without a live pool. Mirrors `focus`/`jumpTo`'s remote branch.
+ */
+export declare function resolveDetachTarget(s: ActiveSession, self: string): DetachTarget;
+/**
+ * Resolve `<id>` to exactly one live session by prefix. Mirrors `focus`'s match
+ * so the two verbs accept the same ids.
+ */
+export declare function resolveOne(activeById: Map<string, ActiveSession>, id: string): ActiveSession | {
+    error: string;
+};

package/dist/commands/detach-core.js

@@ -0,0 +1,61 @@
+/**
+ * The prompt the backgrounded run resumes with. Its whole job is to stop a
+ * now-unwatched agent from stalling on a confirmation nobody will answer: it
+ * tells the agent it is headless and to drive to done, or to stop and state a
+ * blocker (which surfaces as a waiting session the user can `attach`).
+ */
+export const BACKGROUND_NUDGE = "You've been sent to the background — nobody is watching this session now. " +
+    'Continue the current task and drive it to completion end-to-end. ' +
+    "Don't ask for confirmation; make the reasonable call and keep going. " +
+    'If you genuinely cannot proceed safely, stop and state the blocker plainly in one message.';
+/**
+ * Build the argv for the headless continuation `detach` spawns. Agent-agnostic
+ * and version-pinned by construction — it goes through the same `agents run
+ * --resume` path `attach` reverses.
+ */
+export function buildBackgroundArgv(agent, sessionId, cwd) {
+    const argv = ['run', agent, BACKGROUND_NUDGE, '--resume', sessionId, '--headless'];
+    if (cwd)
+        argv.push('--cwd', cwd);
+    return argv;
+}
+/**
+ * Decide how to detach a resolved session. Cloud and team sessions are refused
+ * (they have their own lifecycles); a session on another machine is delegated to
+ * that host over SSH — never stopped/resumed locally, since its pid and tmux
+ * socket only mean something where it actually runs. Pure, so every branch is
+ * unit-tested without a live pool. Mirrors `focus`/`jumpTo`'s remote branch.
+ */
+export function resolveDetachTarget(s, self) {
+    if (s.context === 'cloud') {
+        return { kind: 'refuse', reason: 'Cloud sessions run remotely and cannot be detached from here.' };
+    }
+    if (s.context === 'teams') {
+        return {
+            kind: 'refuse',
+            reason: 'That session is managed by its team — stop it with `agents teams`, not `detach`.',
+        };
+    }
+    const sessionId = s.sessionId ?? '';
+    if (!sessionId) {
+        return { kind: 'refuse', reason: 'That session has no id to resume, so it cannot be detached.' };
+    }
+    if (s.machine && s.machine !== self) {
+        return { kind: 'remote', machine: s.machine, sessionId };
+    }
+    return { kind: 'local', sessionId };
+}
+/**
+ * Resolve `<id>` to exactly one live session by prefix. Mirrors `focus`'s match
+ * so the two verbs accept the same ids.
+ */
+export function resolveOne(activeById, id) {
+    const q = id.toLowerCase();
+    const matches = [...activeById.values()].filter((s) => (s.sessionId ?? '').toLowerCase().startsWith(q));
+    if (matches.length === 0)
+        return { error: `No live session matching "${id}".` };
+    if (matches.length > 1) {
+        return { error: `"${id}" is ambiguous (${matches.length} live matches). Use more of the id.` };
+    }
+    return matches[0];
+}

package/dist/commands/detach.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+export declare function registerDetachCommand(program: Command): void;
+export declare function detachAction(id: string, opts?: {
+    local?: boolean;
+}): Promise<void>;

package/dist/commands/detach.js

@@ -0,0 +1,171 @@
+/**
+ * `agents sessions detach <id>` — send a live agent session to the background:
+ * stop its interactive process and continue it headless, unattended, so it drives
+ * its task to completion without holding a terminal. Bring it back with
+ * `agents sessions attach`. A sibling of `sessions focus`/`resume` on the session
+ * lifecycle axis.
+ *
+ * Agent-agnostic and version-pinned by construction: it re-invokes
+ * `agents run <agent> "<nudge>" --resume <id> --headless`, which resolves the
+ * session's originating version and uses the agent's native resume (claude/codex)
+ * or a `/continue` replay (others) — the same path `attach` reverses.
+ */
+import { spawn } from 'node:child_process';
+import { openSync, closeSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import { gatherLiveTargets } from './go.js';
+import { killSession } from '../lib/tmux/index.js';
+import { getDefaultSocketPath } from '../lib/tmux/paths.js';
+import { getAgentsInvocation } from '../lib/daemon.js';
+import { captureProcessStartTime } from '../lib/pty-server.js';
+import { writeDetachRecord } from '../lib/session/detached.js';
+import { getLogsDir } from '../lib/state.js';
+import { runOnPeer } from '../lib/session/remote-list.js';
+import { buildBackgroundArgv, resolveDetachTarget, resolveOne } from './detach-core.js';
+export function registerDetachCommand(program) {
+    program
+        .command('detach')
+        .argument('<id>', 'Short or full id of the live session to background')
+        .option('--local', 'Only this machine (skip the cross-host sweep)')
+        .description('Send a live agent to the background — stop its terminal, keep it working headless')
+        .action(async (id, opts) => {
+        await detachAction(id, opts);
+    });
+}
+/**
+ * Stop the interactive process so it can't fight the headless resume over the
+ * same transcript. tmux-hosted sessions are killed by session (closes the pane
+ * and ends the agent); a plain process is SIGTERM'd by pid. Either way we then
+ * wait for the process to actually exit before returning, so the headless
+ * continuation never starts writing the transcript while the old process is
+ * still flushing it.
+ */
+async function stopInteractive(s) {
+    if (s.tmuxTarget) {
+        const name = s.tmuxTarget.split(':')[0];
+        await killSession(name, getDefaultSocketPath());
+    }
+    else if (s.pid && s.pid > 0) {
+        try {
+            process.kill(s.pid, 'SIGTERM');
+        }
+        catch {
+            return; /* already gone — nothing to wait on */
+        }
+    }
+    if (s.pid && s.pid > 0)
+        await waitForExit(s.pid);
+}
+/**
+ * Poll until `pid` is gone (SIGTERM already sent), escalating to SIGKILL past the
+ * deadline so a stuck process can't wedge the detach. Bounded so `detach` never
+ * hangs waiting on a process that ignores signals.
+ */
+async function waitForExit(pid, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            return; /* gone */
+        }
+        if (Date.now() >= deadline) {
+            try {
+                process.kill(pid, 'SIGKILL');
+            }
+            catch {
+                /* raced to exit */
+            }
+            return;
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+}
+/**
+ * Where a backgrounded continuation's stdout/stderr lands, by convention, so a
+ * crash after detach is debuggable — there is no terminal watching it, and
+ * presence only tells you the pid is gone, not whether the run finished or died.
+ */
+function backgroundLogPath(sessionId) {
+    return path.join(getLogsDir(), `detach-${sessionId.slice(0, 8)}.log`);
+}
+/**
+ * Spawn the headless continuation detached, resolving to its pid for tracking.
+ * Its output is redirected to `logFile` rather than discarded, so a fast-failing
+ * background run leaves a trail.
+ */
+function spawnHeadless(command, args, logFile) {
+    return new Promise((resolve, reject) => {
+        mkdirSync(path.dirname(logFile), { recursive: true });
+        const fd = openSync(logFile, 'a');
+        const child = spawn(command, args, { detached: true, stdio: ['ignore', fd, fd], env: process.env });
+        child.once('spawn', () => {
+            const pid = child.pid ?? 0;
+            child.unref();
+            try {
+                closeSync(fd);
+            }
+            catch { /* fd handed to the child */ }
+            resolve(pid);
+        });
+        child.once('error', (err) => {
+            try {
+                closeSync(fd);
+            }
+            catch { /* never opened for the child */ }
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}
+export async function detachAction(id, opts = {}) {
+    const { self, activeById } = await gatherLiveTargets(!!opts.local, { includeCloud: true });
+    const resolved = resolveOne(activeById, id);
+    if ('error' in resolved) {
+        console.error(chalk.red(resolved.error));
+        process.exitCode = 1;
+        return;
+    }
+    const s = resolved;
+    const target = resolveDetachTarget(s, self);
+    // Cloud, team, and id-less sessions can't be backgrounded from here.
+    if (target.kind === 'refuse') {
+        console.error(chalk.red(target.reason));
+        process.exitCode = 1;
+        return;
+    }
+    const short = target.sessionId.slice(0, 8);
+    // A session on another host: its pid and tmux socket only mean something where
+    // it runs, so detach it *there* over SSH — never kill/resume locally. Mirrors
+    // focus/jumpTo's remote branch.
+    if (target.kind === 'remote') {
+        console.log(chalk.gray(`${short} lives on ${target.machine} — detaching it there over SSH…`));
+        const rc = await runOnPeer(['sessions', 'detach', target.sessionId, '--local'], target.machine);
+        if (rc === 'no-target') {
+            console.error(chalk.red(`Can't reach ${target.machine} to detach ${short}.`));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Local: stop the interactive process, then continue it headless, detached —
+    // version-pinned via the existing `agents run --resume` path.
+    const sessionId = target.sessionId;
+    const agent = s.kind;
+    await stopInteractive(s);
+    const logFile = backgroundLogPath(sessionId);
+    const inv = getAgentsInvocation(buildBackgroundArgv(agent, sessionId, s.cwd));
+    const pid = await spawnHeadless(inv.command, inv.args, logFile);
+    // Record it so `attach` and `agents ls --active` know it's backgrounded.
+    writeDetachRecord({
+        sessionId,
+        agent,
+        cwd: s.cwd,
+        headlessPid: pid,
+        headlessStartTime: captureProcessStartTime(pid),
+        detachedAtMs: Date.now(),
+    });
+    console.log(chalk.green(`◒ Backgrounded ${agent} ${short}`) +
+        chalk.gray(` — running headless (pid ${pid}). Bring it back: agents sessions attach ${short}`));
+    console.log(chalk.gray(`  logs: ${logFile}`));
+}

package/dist/commands/doctor.js

@@ -22,6 +22,7 @@ import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
 import { heal, healChangedAnything } from '../lib/heal.js';
 import { blocksLocalScripts, getEffectiveExecutionPolicy } from '../lib/platform/winpath.js';
+import { scanUserRcFiles, rcSecretWarningLines } from '../lib/secrets/rc-hygiene.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
@@ -177,6 +178,10 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis, signIn) {
     // generated `agents.ps1` launcher — postinstall diagnoses it interactively,
     // but a non-interactive install never sees that. Surface it here too.
     renderExecPolicyAdvisory();
+    // Credentials exported from a shell rc file leak into every process's
+    // environment (readable via /proc/<pid>/environ) — the RUSH-1968 class. Flag
+    // them here so the master passphrase never silently lives in `~/.zshenv` again.
+    renderRcHygieneAdvisory();
 }
 // ─── windows execution-policy advisory ─────────────────────────────────────────
 /**
@@ -199,6 +204,19 @@ export function execPolicyWarningLines(platform, policy) {
         'The agents.cmd shim still works regardless of the policy.',
     ];
 }
+function renderRcHygieneAdvisory() {
+    const findings = scanUserRcFiles();
+    const lines = rcSecretWarningLines(findings);
+    if (lines.length === 0)
+        return;
+    console.log();
+    console.log(chalk.bold('Secrets in shell config'));
+    const [headline, ...rest] = lines;
+    console.log(`  ${chalk.yellow('warn ')}  ${headline}`);
+    for (const line of rest) {
+        console.log(chalk.gray(`           ${line}`));
+    }
+}
 function renderExecPolicyAdvisory() {
     // Only probe the policy on Windows — getEffectiveExecutionPolicy() spawns
     // powershell, which is a wasted (doomed) process on POSIX where the advisory