@phnx-labs/agents-cli 1.20.69 → 1.20.71

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## 1.20.71
+
+- **Capture your whole fleet into `agents.yaml`, then rebuild it anywhere with
+  `agents apply` (#1305).** New `agents fleet capture` (alias `agents devices
+  capture`) snapshots the live environment into the portable `fleet:` block — the
+  device roster (**names only**), the source's agents as `defaults`, secrets-bundle
+  **names**, and routine **names**. It commits **zero** Tailscale IPs or usernames:
+  `agents apply` reconstructs a fresh machine's roster by resolving each device
+  name **live from Tailscale** (`ensureDevicesRegistered`), so `git clone` +
+  `agents apply` replicates the fleet with nothing sensitive in the repo. `apply`
+  now also passes declared `sync:` scopes through to `agents sync <scope>`
+  (previously a bare `sync`) and surfaces declared secrets-bundle names to recreate
+  on each device (values stay keychain-local, never pushed). Browser profiles are
+  intentionally not duplicated into `fleet:` — they already sync via the central
+  `browser:` block. Source: `apps/cli/src/commands/fleet-capture.ts`,
+  `apps/cli/src/lib/fleet/capture.ts`, `apps/cli/src/lib/devices/sync.ts`,
+  `apps/cli/src/lib/fleet/{types,manifest,apply}.ts`.
+
+- **`agents fleet status` no longer hangs on a stale `~/.ssh/config`.** The fleet probes (version / doctor / `fleet ping`) now dial each device at its registry Tailscale address (`dnsName`/IP) instead of the bare host name — so a hand-written `Host <name>` block carrying a drifted LAN IP can no longer shadow the correct entry and make a reachable box look dead. It also fails fast: a device the stats probe already found unreachable is skipped straight to an unreachable row instead of eating a 15s+30s version+doctor timeout. Source: `apps/cli/src/commands/ssh.ts`.
+
+- **Fix the macOS menu-bar auto-heal so upgrades actually restart the helper.**
+  `agents` has an on-startup self-heal that re-copies `MenubarHelper.app` when
+  the CLI version changes, but on modern macOS `launchctl bootstrap` fails when
+  the job is already bootstrapped, and the deprecated `launchctl load -w`
+  fallback plus `kickstart -k` did not recover a job that launchd had stopped
+  respawning after a `WindowServer event port death`. The helper would stay
+  updated on disk but invisible in the menu bar. `enableMenubarService` now
+  boots the old job out, bootstraps the fresh plist, and kickstarts it — the
+  same sequence that reliably restores the icon by hand. Source:
+  `apps/cli/src/lib/menubar/install-menubar.ts`,
+  `apps/cli/src/lib/menubar/install-menubar.test.ts`.
+
+- **`agents repo pull` no longer wedges on per-machine pin drift.** The committed
+  `devices/<machineId>/agents.yaml` (each box's agent version pins) is rewritten
+  whenever a pin changes, leaving the working tree perpetually dirty — so
+  `agents repo pull`, which refuses a dirty tree, kept failing until the file was
+  hand-committed. `pullRepo` now durably commits **just that one path** (explicit
+  pathspec) before pulling, via `commitOwnDeviceMeta`. Genuine uncommitted edits to
+  any other file still (correctly) block the pull. No-op for the system/extra repos
+  that don't own the path. Source: `apps/cli/src/lib/git.ts`.
+
+- **`agents secrets unlock` now stays unlocked across an agents-cli upgrade (and,
+  with `--durable`, across sleep + reboot).** The macOS secrets broker held an
+  unlock only in RAM, so it evaporated every time the daemon restarted (upgrade)
+  or the machine slept — forcing a Touch ID re-tap and breaking headless reads
+  with "not unlocked in the secrets agent". An unlock now also persists a
+  device-local, non-biometry keychain session item that the broker **rehydrates on
+  start** and that reads **fall back to** silently. Split default: it survives
+  upgrade/restart automatically; pass `--durable` (or set `secrets.agent.durable:
+  true`) to also survive sleep/reboot — otherwise a bundle re-locks on sleep as
+  before. `lock` / rotate / delete clear it. On Linux and Windows `unlock` is now a
+  friendly no-op (secrets already resolve durably from the OS store with no
+  prompt), so the command behaves the same on all three platforms. Source:
+  `apps/cli/src/lib/secrets/session-store.ts` (new),
+  `apps/cli/src/lib/secrets/agent.ts`, `apps/cli/src/lib/secrets/bundles.ts`,
+  `apps/cli/src/lib/secrets/index.ts`, `apps/cli/src/commands/secrets.ts`,
+  `apps/cli/src/lib/types.ts`.
+
+- **`agents share` cover capture finds Playwright's `chrome-headless-shell` packages.** `scanCaches()` only knew the classic `chrome-mac/Chromium.app` and `Google Chrome for Testing` layouts, so on machines whose Playwright cache holds only the newer `chromium_headless_shell-*` packages (a raw `chrome-headless-shell` binary, not an `.app` bundle) — and no system Chrome/Brave/Edge — the OG cover capture silently returned null and shared plans published without a preview card. The scan now matches `chrome-headless-shell-mac-arm64`, `chrome-headless-shell-mac-x64`, and `chrome-headless-shell-linux64` layouts alongside the existing ones. Source: `apps/cli/src/lib/share/capture.ts`, `apps/cli/src/lib/share/capture.test.ts`.
+
+## 1.20.70
+
+- **Fix `agents setup computer` / `agents computer setup` refusing to install a
+  valid downloaded helper.** The signature check read `codesign -dv` from stdout,
+  but that command writes its details to **stderr** on success — so the Team-ID
+  check saw an empty string, found no `TeamIdentifier`, and rejected every
+  validly-signed, notarized helper with "signed by unexpected Team (none)". It now
+  reads both streams via `spawnSync`. Verified end-to-end against the real
+  published `v1.20.69` release asset (download → sha256 → extract → codesign +
+  Team `2HTP252L87` + `spctl` notarization → install). Source:
+  `apps/cli/src/lib/computer/download.ts`.
+
+- **The bundled macOS menu-bar helper is now a true universal binary on
+  Xcode-less release hosts.** `menubar/scripts/build.sh release` used
+  `swift build --arch arm64 --arch x86_64` (needs Xcode's xcbuild) and, on a
+  Command-Line-Tools-only host, silently fell back to a **single-arch** build —
+  shipping an arm64-only `MenubarHelper.app` in the tarball that could not run on
+  Intel Macs. It now builds each slice via `--triple` and `lipo`s them into one
+  universal binary, matching the computer helper. Source:
+  `apps/cli/menubar/scripts/build.sh`.
+
 ## 1.20.69
 
 - **Choose a safe account with `agents run <agent>@`.** A trailing `@` opens a

package/README.md

@@ -432,13 +432,15 @@ 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 matrix
+agents fleet status                     # warnings rollup + health/sync/version/Auth matrix (cache-first)
+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
 
 # Your Tailscale fleet, auto-discovered
 agents devices sync                     # ingest `tailscale status`
-agents devices list                     # fleet + live headroom: load, mem, idle/busy — which box has room
+agents devices list                     # fleet + headroom: load, mem, idle/busy — which box has room (cache-first)
+agents devices list --live              # force a live probe of every device (alias of --refresh)
 agents devices list --full              # add per-device cores and free/total RAM
 agents devices list --no-stats          # instant: names/addresses only, skip the probe
 agents ssh mac-mini                     # hardened SSH: fails fast if offline,
@@ -453,11 +455,22 @@ agents cloud run "nightly benchmark" --host gpu-box --agent claude   # task in c
 agents routines add nightly -s "0 2 * * *" -a claude -p "run the sweep" --run-on gpu-box
 ```
 
-`agents devices list` probes every reachable box in parallel (bounded timeout, so a
-slow node degrades to `—` instead of hanging) and shows normalized load, memory
-pressure, and an idle/light/busy/loaded headroom badge, plus a fleet-capacity summary
+`agents devices list` shows normalized load, memory pressure, and an
+idle/light/busy/loaded headroom badge, plus a fleet-capacity summary
 (`164 cores · 421G free / 518G RAM`). It answers "which machine has room right now?" —
-the utilization signal the teammate scheduler doesn't yet see.
+the utilization signal the teammate scheduler doesn't yet see. It's **cache-first**:
+reads serve instantly from a stats cache the daemon warms (~every 3 min), probing only
+this machine locally plus any device missing from the cache; pass `--refresh` (or the
+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.
 
 **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).
 

package/dist/commands/apply.js

@@ -15,6 +15,7 @@ import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { machineId } from '../lib/session/sync/config.js';
 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';
@@ -121,6 +122,15 @@ function renderPlan(plan) {
     if (noToken.length > 0) {
         console.log(chalk.yellow(`  manual login needed (no portable token on source): ${noToken.join(', ')}`));
     }
+    // Secrets bundles are declared once for the fleet; surface the distinct set to
+    // recreate on any device missing them (values are keychain-local, never pushed).
+    const bundles = [...new Set(rows.flatMap((r) => r.secretsNeeded))];
+    if (bundles.length > 0) {
+        const shown = bundles.slice(0, 12);
+        const more = bundles.length - shown.length;
+        const list = shown.join(', ') + (more > 0 ? `, +${more} more` : '');
+        console.log(chalk.yellow(`  ${bundles.length} secrets bundle(s) to recreate where missing (keychain-local, never pushed): ${list}`));
+    }
 }
 /** padEnd on the visible width, ignoring chalk color codes. Exported for tests. */
 export function stripPad(s, width) {
@@ -135,6 +145,24 @@ async function runApply(opts) {
     const file = opts.file ?? 'agents.yaml';
     const manifest = readFleetFile(path.resolve(file));
     const source = machineId();
+    // Fresh-machine bootstrap: an explicit `devices:` map may name boxes this
+    // machine has never registered (e.g. a freshly-cloned agents.yaml). Resolve
+    // those names live from Tailscale and register them BEFORE resolveDesired
+    // validates the roster — so replication needs only the repo, never committed
+    // IPs/usernames. `devices: all` needs no bootstrap (it targets what's already
+    // registered + online).
+    let unresolved = [];
+    if (manifest.devices !== 'all') {
+        const wanted = Object.keys(manifest.devices).filter((n) => n !== source);
+        const boot = await ensureDevicesRegistered(wanted);
+        unresolved = boot.unresolved;
+        if (boot.registered.length > 0) {
+            console.log(chalk.gray(`Registered ${boot.registered.length} device(s) from Tailscale: ${boot.registered.join(', ')}`));
+        }
+        if (boot.unresolved.length > 0) {
+            console.log(chalk.yellow(`Not resolvable on Tailscale — skipped, reconcile continues for the rest: ${boot.unresolved.join(', ')}`));
+        }
+    }
     const registry = await loadDevices();
     // Control devices (a cockpit) never run agents — exclude them from the
     // reconcile set entirely so `agents apply` doesn't try to install/sync/login
@@ -142,7 +170,9 @@ async function runApply(opts) {
     const all = Object.values(registry).filter((d) => !isControlDevice(d));
     const online = all.filter((d) => d.tailscale?.online === true).map((d) => d.name);
     const registered = all.map((d) => d.name);
-    let desired = resolveDesired(manifest, { onlineDevices: online, registeredDevices: registered, source });
+    // Unresolved names are skipped (surfaced above), never fatal — a manifest
+    // naming an asleep box must not abort the reconcile for every other device.
+    let desired = resolveDesired(manifest, { onlineDevices: online, registeredDevices: registered, source, unresolved });
     if (opts.device) {
         desired = desired.filter((d) => d.device === opts.device);
         if (desired.length === 0)
@@ -174,7 +204,7 @@ async function runApply(opts) {
     const probeList = await pool(desired, 6, async (d) => probeDevice(nameToProfile.get(d.device)));
     const probes = new Map(probeList.map((p) => [p.device, p]));
     const targetCliVersion = localCliVersion();
-    let plan = diffFleet(desired, probes, { targetCliVersion, sourceAuth });
+    let plan = diffFleet(desired, probes, { targetCliVersion, sourceAuth, secretsBundles: manifest.secrets?.bundles });
     // --only filter.
     if (opts.only) {
         const keep = new Set();
@@ -192,7 +222,10 @@ async function runApply(opts) {
     const isDry = opts.plan || opts.dryRun;
     if (isDry)
         return;
-    if (plan.actions.filter((a) => a.kind !== 'needs-login').length === 0) {
+    // `needs-login`/`needs-secret` are surfaced manual reminders, not executable
+    // mutations — exclude them so an otherwise-converged fleet still says "nothing
+    // to do" instead of looping forever on un-actionable surfacing.
+    if (plan.actions.filter((a) => a.kind !== 'needs-login' && a.kind !== 'needs-secret').length === 0) {
         console.log(chalk.green('\nNothing to do — fleet already matches the profile.'));
         return;
     }

package/dist/commands/check.js

@@ -4,6 +4,7 @@ import { setHelpSections } from '../lib/help.js';
 import { computeDrift } from '../lib/drift.js';
 import { loadDevices } from '../lib/devices/registry.js';
 import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
+import { fleetDialTarget } from '../lib/devices/connect.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { sshExecAsync } from '../lib/ssh-exec.js';
@@ -107,7 +108,7 @@ function checkPayload(device, drift) {
 async function probeDeviceCheck(target) {
     const isWin = /^win/i.test((target.platform ?? '').trim());
     const remoteCmd = buildRemoteAgentsInvocation(['check', '--json'], undefined, isWin ? 'windows' : undefined, isWin ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' });
-    const res = await sshExecAsync(target.name, remoteCmd, { timeoutMs: 30000, multiplex: true });
+    const res = await sshExecAsync(target.dialTarget, remoteCmd, { timeoutMs: 30000, multiplex: true });
     if (res.code !== 0 && !res.stdout.trim()) {
         throw new Error(res.timedOut ? 'timed out' : (res.stderr.trim() || `exit ${res.code ?? 'unknown'}`));
     }
@@ -135,6 +136,7 @@ async function runDevicesCheck(opts, cwd) {
         name: t.device.name,
         platform: t.device.platform,
         skip: t.skip,
+        dialTarget: fleetDialTarget(t.device),
     }));
     const remote = await fanOutDevices(remoteTargets, probeDeviceCheck);
     const devices = [local];

package/dist/commands/doctor.js

@@ -14,6 +14,7 @@ import { getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalled
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
 import { checkSyncStatus, countOrphans } from '../lib/drift.js';
+import { readAuthHealthCache, summarizeHostAuth } from '../lib/auth-health.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
@@ -741,6 +742,10 @@ export function registerDoctorCommand(program) {
                 console.log(JSON.stringify({
                     clis,
                     signIn,
+                    // Cached auth-health rollup for THIS host — lets `agents fleet status`
+                    // show a live-verified Auth column from the same fan-out it already
+                    // runs, without a separate fleet-wide `fleet ping`.
+                    auth: summarizeHostAuth(readAuthHealthCache(), machineId()),
                     sync: syncRows,
                     orphans: orphanRows,
                     hostClis: {

package/dist/commands/exec.js

@@ -8,6 +8,7 @@
 import { Option } from 'commander';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
+import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { parseLoopInterval } from '../lib/loop.js';
 import { AGENTS } from '../lib/agents.js';
 import { recordDispatchedRun } from '../lib/audit/log.js';
@@ -703,6 +704,17 @@ export function registerRunCommand(program) {
                                 `Make sure the host is reachable over SSH, then re-run with --copy-creds.`));
                         process.exit(1);
                     }
+                    // --copy-creds ships live credentials to a host, so it deliberately
+                    // requires an interactive terminal to pick which signed-in runtimes to
+                    // send and to confirm the transfer. Fail clean in a non-TTY/headless
+                    // shell instead of hanging on the picker/confirm below — auto-shipping
+                    // every signed-in token without consent would defeat the gate's purpose.
+                    if (!isInteractiveTerminal()) {
+                        // No non-interactive form: --copy-creds must pick which signed-in
+                        // runtimes to ship and confirm the transfer, so pass no alternatives
+                        // (an empty list prints just the "needs an interactive terminal" line).
+                        requireInteractiveSelection('--copy-creds (it selects which credentials to ship and confirms the transfer)', []);
+                    }
                     const { detectSignedInRuntimes, pickRuntimes, resolveClaudeCredentialsBlob } = await import('../lib/crabbox/runtimes.js');
                     const { confirm } = await import('@inquirer/prompts');
                     const detected = await detectSignedInRuntimes();

package/dist/commands/fleet-capture.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `agents fleet capture` (alias surface of `agents devices capture`) — snapshot
+ * the live environment into the `fleet:` block of `agents.yaml` so a fresh
+ * machine can reconstruct it with `agents apply`.
+ *
+ * Local-read + local-write, zero SSH. Records device NAMES only (never IPs or
+ * usernames — those are re-resolved live from Tailscale at apply-time), plus the
+ * source's own agents as defaults, browser profiles, secrets-bundle names, and
+ * routine names. The heavy lifting is the pure `captureFleet` builder; this
+ * command just gathers inputs and persists via `updateMeta`.
+ */
+import { Command } from 'commander';
+/** Attach `capture` to the `devices`/`fleet` command tree. */
+export declare function registerFleetCaptureCommand(devicesCmd: Command): void;

package/dist/commands/fleet-capture.js

@@ -0,0 +1,107 @@
+/**
+ * `agents fleet capture` (alias surface of `agents devices capture`) — snapshot
+ * the live environment into the `fleet:` block of `agents.yaml` so a fresh
+ * machine can reconstruct it with `agents apply`.
+ *
+ * Local-read + local-write, zero SSH. Records device NAMES only (never IPs or
+ * usernames — those are re-resolved live from Tailscale at apply-time), plus the
+ * source's own agents as defaults, browser profiles, secrets-bundle names, and
+ * routine names. The heavy lifting is the pure `captureFleet` builder; this
+ * command just gathers inputs and persists via `updateMeta`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import * as yaml from 'yaml';
+import { loadDevices, isControlDevice } from '../lib/devices/registry.js';
+import { readMeta, updateMeta, getDeviceMetaPath } from '../lib/state.js';
+import { listBundles } from '../lib/secrets/bundles.js';
+import { listJobs } from '../lib/routines.js';
+import { captureFleet } from '../lib/fleet/capture.js';
+/** The committed per-device pin dir: `~/.agents/devices/`. Derived from the
+ * device-meta path so it honors any AGENTS_HOME override the same way. */
+function devicesPinDir() {
+    return path.dirname(path.dirname(getDeviceMetaPath()));
+}
+/** Read `devices/<name>/agents.yaml` pin files into `name -> [id@latest]`. Only
+ * used with `--from-pins`; keeps capture zero-SSH by reading committed state. */
+function agentsFromPins(names) {
+    const dir = devicesPinDir();
+    const out = {};
+    for (const name of names) {
+        const p = path.join(dir, name, 'agents.yaml');
+        if (!fs.existsSync(p))
+            continue;
+        try {
+            const doc = yaml.parse(fs.readFileSync(p, 'utf-8'));
+            const ids = doc?.agents ? Object.keys(doc.agents) : [];
+            if (ids.length > 0)
+                out[name] = ids.map((id) => `${id}@latest`);
+        }
+        catch {
+            /* skip an unparsable pin file — capture is best-effort per device */
+        }
+    }
+    return out;
+}
+async function runCapture(opts) {
+    const meta = readMeta();
+    // Roster: registered, non-control device names only.
+    const registry = await loadDevices();
+    let names = Object.values(registry)
+        .filter((d) => !isControlDevice(d))
+        .map((d) => d.name)
+        .sort();
+    if (opts.device) {
+        names = names.filter((n) => n === opts.device);
+        if (names.length === 0)
+            throw new Error(`Device '${opts.device}' is not a registered device.`);
+    }
+    // Defaults seeded from the source machine's own installed agents.
+    const sourceAgents = Object.keys(meta.agents ?? {}).sort();
+    const defaults = {
+        agents: sourceAgents.map((id) => `${id}@latest`),
+        sync: ['user'],
+        login: 'sync',
+    };
+    const inputs = {
+        devices: names,
+        defaults,
+        agentsByDevice: opts.fromPins ? agentsFromPins(names) : undefined,
+        // Browser profiles are intentionally NOT captured — the central `browser:`
+        // block already syncs via the repo, and its ssh:// endpoints can carry
+        // `user@host`, which must never be copied into the fleet: block.
+        secretsBundles: listBundles().map((b) => b.name),
+        routines: listJobs().map((j) => j.name),
+    };
+    const next = captureFleet(meta.fleet, inputs);
+    if (opts.dryRun) {
+        console.log(chalk.gray('# agents.yaml fleet: block (dry run — not written)'));
+        console.log(yaml.stringify({ fleet: next }).trimEnd());
+        return;
+    }
+    updateMeta((m) => ({ ...m, fleet: next }));
+    const deviceCount = Object.keys(next.devices === 'all' ? {} : next.devices).length;
+    console.log(chalk.green('Captured fleet profile') +
+        chalk.gray(` — ${deviceCount} device(s), ${defaults.agents?.length ?? 0} agent(s), ` +
+            `${inputs.secretsBundles?.length ?? 0} secret bundle(s), ${inputs.routines?.length ?? 0} routine(s).`));
+    console.log(chalk.gray('  Wrote agents.yaml → fleet:. Push it (`agents repo push`) and run `agents apply` on any machine.'));
+}
+/** Attach `capture` to the `devices`/`fleet` command tree. */
+export function registerFleetCaptureCommand(devicesCmd) {
+    devicesCmd
+        .command('capture')
+        .description('Snapshot the live environment (roster names, agents, browser, secret-bundle names, routines) into agents.yaml fleet:.')
+        .option('--dry-run', 'print the fleet: block that would be written, and exit')
+        .option('--from-pins', 'record per-device agents from committed devices/<name>/agents.yaml')
+        .option('--device <name>', 'capture a single device')
+        .action(async (opts) => {
+        try {
+            await runCapture(opts);
+        }
+        catch (e) {
+            console.error(chalk.red(e.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/fork.js

@@ -34,21 +34,26 @@ export function registerForkCommand(program) {
             matches = findSessionsById(sessionArg, {});
         }
         if (matches.length === 0) {
-            console.log(chalk.red(`No session matching "${sessionArg}".`));
-            console.log(chalk.gray('List candidates with: agents sessions'));
+            // Errors go to stderr and set a non-zero exit code so a script chaining on
+            // `agents fork <id> && agents resume <new>` doesn't proceed on a failed fork.
+            console.error(chalk.red(`No session matching "${sessionArg}".`));
+            console.error(chalk.gray('List candidates with: agents sessions'));
+            process.exitCode = 1;
             return;
         }
         if (matches.length > 1) {
-            console.log(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
+            console.error(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
             for (const m of matches.slice(0, 8)) {
-                console.log(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
+                console.error(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
             }
+            process.exitCode = 1;
             return;
         }
         const source = matches[0];
         if (!isForkableAgent(source.agent)) {
-            console.log(chalk.yellow(`fork does not support ${source.agent} sessions yet.`));
-            console.log(chalk.gray(`  Supported: ${FORKABLE_AGENTS.join(', ')}.`));
+            console.error(chalk.yellow(`fork does not support ${source.agent} sessions yet.`));
+            console.error(chalk.gray(`  Supported: ${FORKABLE_AGENTS.join(', ')}.`));
+            process.exitCode = 1;
             return;
         }
         let result;
@@ -56,7 +61,8 @@ export function registerForkCommand(program) {
             result = forkSession(source, { name: options.name });
         }
         catch (err) {
-            console.log(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
+            console.error(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
+            process.exitCode = 1;
             return;
         }
         console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));

package/dist/commands/hosts.js

@@ -9,6 +9,7 @@
 import chalk from 'chalk';
 import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { checkbox, confirm } from '@inquirer/prompts';
+import { isInteractiveTerminal } from './utils.js';
 import { assertValidSshTarget } from '../lib/ssh-exec.js';
 import { getProvider, listAllHosts, resolveHost } from '../lib/hosts/registry.js';
 import { getDevice } from '../lib/devices/registry.js';
@@ -42,6 +43,12 @@ async function maybeBootstrap(target, hostName, probe = probeHost(target, resolv
     const remoteVer = remoteAgentsVersion(target, os);
     const localVer = localCliVersion();
     if (!remoteVer) {
+        // Non-TTY: this is a best-effort bootstrap prompt, so report and return
+        // instead of hanging on confirm() in a headless/piped shell.
+        if (!isInteractiveTerminal()) {
+            console.log(chalk.gray(`  agents-cli not found on ${hostName} — install it there, then: agents hosts check ${hostName}`));
+            return;
+        }
         const ok = await confirm({ message: `  agents-cli not found on ${hostName}. Install ${localVer ? `v${localVer}` : 'latest'} now?`, default: true });
         if (ok) {
             console.log(chalk.gray('  Installing agents-cli on the host…'));
@@ -52,6 +59,10 @@ async function maybeBootstrap(target, hostName, probe = probeHost(target, resolv
     }
     const remoteClean = remoteVer.replace(/^v/, '');
     if (localVer && remoteClean !== localVer) {
+        if (!isInteractiveTerminal()) {
+            console.log(chalk.gray(`  ${hostName} has agents-cli ${remoteClean}, you have ${localVer} — versions differ; upgrade the host to match when convenient.`));
+            return;
+        }
         const ok = await confirm({ message: `  ${hostName} has agents-cli ${remoteClean}, you have ${localVer}. Upgrade to match?`, default: false });
         if (ok) {
             const r = bootstrapAgentsCli(target, localVer, os);

package/dist/commands/secrets.d.ts

@@ -49,6 +49,7 @@ export declare function parseImportSource(opts: {
 export declare function buildRemoteUnlockArgs(names: string[], opts: {
     all?: boolean;
     ttl?: string;
+    durable?: boolean;
 }): string[];
 export { SSH_TARGET_RE, assertValidSshTarget };
 /**

package/dist/commands/secrets.js

@@ -20,7 +20,8 @@ import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBund
 import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
-import { secretsHoldMs, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { saveSession, deleteSession, deleteAllSessions } from '../lib/secrets/session-store.js';
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
@@ -249,6 +250,9 @@ export function buildRemoteUnlockArgs(names, opts) {
         'unlock',
         ...(opts.all ? ['--all'] : names),
         ...(opts.ttl ? ['--ttl', opts.ttl] : []),
+        // Forward --durable so a remote unlock honors it too; without this the remote
+        // silently falls back to its own secrets.agent.durable default (off).
+        ...(opts.durable ? ['--durable'] : []),
     ];
 }
 // SSH target validation is defined canonically in src/lib/ssh-exec.ts and
@@ -1840,6 +1844,7 @@ Examples:
         .command('unlock [names...]')
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --host, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')
         .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
+        .option('--durable', 'Keep the unlock across sleep + reboot too (default: survives upgrade/restart but re-locks on sleep). Set secrets.agent.durable in agents.yaml to make this the default.')
         .option('--all', 'Unlock every configured bundle')
         .option('--host <target>', 'Unlock the bundle(s) on this remote machine over SSH instead of locally (file-backed bundles only — the remote\'s passphrase prompt surfaces on your terminal over a -tt session). Single-valued (NOT variadic) so it never swallows the bundle name: `unlock <name> --host <machine>`.')
         .action(async (names, opts) => {
@@ -1880,8 +1885,12 @@ Examples:
             return;
         }
         if (process.platform !== 'darwin') {
-            console.error(chalk.red('secrets-agent is macOS-only (no biometry prompt to deduplicate elsewhere).'));
-            process.exit(1);
+            // No broker + no biometry prompt off darwin: secrets already resolve
+            // durably from the OS store (libsecret / Credential Manager) on every
+            // read with no prompt, so an unlock is a friendly no-op — not an error.
+            // Accept --durable as a documented no-op so the command is uniform.
+            console.log(chalk.gray('Nothing to unlock: secrets already persist on this OS — reads never re-prompt.'));
+            return;
         }
         let targets = opts.all ? listBundles().map((b) => b.name) : names;
         if (!targets || targets.length === 0) {
@@ -1915,6 +1924,14 @@ Examples:
                 const { bundle, env } = readAndResolveBundleEnv(name, { noAgent: true, caller: 'unlock' });
                 if (await agentLoad(name, bundle, env, ttlMs)) {
                     loaded++;
+                    // Persist a durable session snapshot so the unlock survives a daemon
+                    // restart / upgrade (and sleep too, with --durable). session-store.ts.
+                    saveSession(name, {
+                        bundle,
+                        env,
+                        expiresAt: Date.now() + ttlMs,
+                        sleepPersist: opts.durable ?? secretsAgentDurable(),
+                    });
                     console.log(`${chalk.green('unlocked')} ${chalk.cyan(name)} ${chalk.gray(`(${Object.keys(env).length} keys, ${humanRemaining(Date.now() + ttlMs)})`)}`);
                 }
                 else {
@@ -1941,12 +1958,15 @@ Examples:
             return; // nothing to lock off darwin
         if (names && names.length > 0 && !opts.all) {
             let total = 0;
-            for (const name of names)
+            for (const name of names) {
                 total += await agentLock(name);
+                deleteSession(name); // also drop the durable snapshot, or a restart re-warms it
+            }
             console.log(total > 0 ? chalk.green(`Locked ${total} bundle(s).`) : chalk.gray('Nothing to lock.'));
         }
         else {
             const wiped = await agentLock();
+            deleteAllSessions();
             console.log(wiped > 0 ? chalk.green(`Locked ${wiped} bundle(s).`) : chalk.gray('Nothing to lock.'));
         }
     });

package/dist/commands/sessions-tail.js

@@ -218,8 +218,7 @@ export function registerSessionsTailCommand(sessionsCmd) {
         .command('tail [sessionId]')
         .description('Stream JSONL events from a session file as they are written, one event per line. Long-running: Ctrl+C to stop. Claude and Codex only.')
         .option('--latest', 'Tail the most recent tailable session (claude or codex)')
-        .option('--from-start', 'Emit the full file first, then follow (default: start at EOF)')
-        .option('--json', 'Raw JSONL passthrough (default)');
+        .option('--from-start', 'Emit the full file first, then follow (default: start at EOF)');
     setHelpSections(tailCmd, {
         examples: `
       # Follow the most recent active Claude or Codex session