@phnx-labs/agents-cli 1.20.70 → 1.20.72

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## 1.20.72
+
+- **Stop `agents doctor` from reporting phantom drift and `agents prune` from
+  deleting source-managed resources.** Three reconciler false positives are
+  fixed: the instruction file (`CLAUDE.md`/`AGENTS.md`) is now compared against
+  the composed active-preset output the rules writer actually emits — not the raw
+  whole-repo `rules/AGENTS.md` — so a correctly-synced home no longer shows as
+  permanent drift; plugin-bundled commands installed as `<plugin>-<command>`
+  command-skills (e.g. `swarm-plan`, `code-review`) are no longer flagged as
+  orphans/extras that `prune cleanup` would delete; and command-as-skill wrappers
+  (the `agents_command` marker) are no longer miscounted as skills and surfaced as
+  deletable skill orphans. Source: `apps/cli/src/lib/staleness/`,
+  `apps/cli/src/lib/commands.ts`, `apps/cli/src/lib/skills.ts`.
+
+- **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`.
+
+- **No more macOS keychain password prompt from an interactive command.** Writing a non-`agents-cli.` keychain item (e.g. a refreshed Claude OAuth token during `agents view`, or an `agents secrets add`) via `/usr/bin/security add-generic-password -w` piped the value over stdin — but `readpassphrase(3)` reads the *controlling terminal* when one exists, so in an interactive shell `security` prompted the user ("password data for new item:") and hung to the timeout, ignoring the piped value. The write now runs `detached` (a new session with no controlling terminal) so the piped stdin is always used. Verified under a pty. Source: `apps/cli/src/lib/secrets/index.ts`.
+
+- **`agents logs <id> --json` now reports the true final status of a host task.**
+  For a run that finished remotely between dispatch and the one-shot `--json`
+  read, the payload emitted a stale `status: "running"` with no `exitCode` — even
+  though the completed log was already present — because `hostTaskLogJson`
+  discarded the reconciled record `reconcileTask` returns (it heals a new object
+  rather than mutating in place). It now emits the reconciled task, so a polling
+  agent sees `completed`/`failed` + `exitCode` + `finishedAt`. Source:
+  `apps/cli/src/lib/hosts/logs.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`.
+
+- **New `agents uninstall` — cleanly reverse adoption and restore your original setup.** Installing agents-cli *adopts* your agent config: it moves `~/.<agent>` aside and replaces it with a symlink into the version homes, adopts the launcher on `PATH`, and adds the shim dir to your shell rc — but until now nothing put any of that back, so removing the CLI stranded your original config under `~/.agents/.history/backups/` and left `~/.claude` a dangling symlink. `agents uninstall` is the reverse of `agents setup`: it restores every adopted `~/.<agent>` (from the timestamped backup, or the version home for imported installs), restores owned home files, releases adopted launchers, strips the shim dir from every shell rc, then disposes of `~/.agents` — moved aside to `~/.agents.removed-<ts>` (recoverable) by default, or hard-deleted with `--purge`. A config agents-cli never adopted is never touched (ownership is decided structurally by `getConfigSymlinkVersion`, the same check `removeVersion` uses); `--dry-run` prints the full plan without changing anything; and if any restore step errors, `--purge` self-downgrades to the recoverable move-aside so a swallowed error can never take your only copy. Works on macOS, Linux, and Windows (junctions and cross-volume `~/.agents` handled). Source: `apps/cli/src/lib/uninstall.ts`, `apps/cli/src/commands/uninstall.ts`.
+
 ## 1.20.70
 
 - **Fix `agents setup computer` / `agents computer setup` refusing to install a

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/commands.js

@@ -43,6 +43,7 @@ When to use:
 `);
     commandsCmd
         .command('list [agent]')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .description('Show which slash commands are installed and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
         .action(async (agentArg, options) => {
@@ -73,6 +74,7 @@ When to use:
             centralPath: getCommandsDir(),
             filterAgent,
             filterVersion,
+            json: options.json,
         });
     });
     commandsCmd

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/logs.js

@@ -23,9 +23,9 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
-import { parseAgentFilter, renderSessionLog } from './sessions.js';
+import { parseAgentFilter, renderSessionLog, renderSessionLogJson } from './sessions.js';
 import { streamSessionTail, isTailable } from './sessions-tail.js';
-import { showHostTaskLog } from '../lib/hosts/logs.js';
+import { showHostTaskLog, hostTaskLogJson } from '../lib/hosts/logs.js';
 import { listTasks } from '../lib/hosts/tasks.js';
 import { itemPicker } from '../lib/picker.js';
 import { query, stats, getLogsPath, rotate, levelFor, } from '../lib/events.js';
@@ -43,8 +43,20 @@ function candidateLabel(c) {
     const title = s.label || s.topic || '';
     return `${chalk.gray('sess')} ${s.shortId.padEnd(9)} ${(s.agent + ver).padEnd(14)} ${chalk.gray(s.timestamp.slice(0, 16))}  ${title.slice(0, 40)}`;
 }
+/** Emit a host-dispatch task's log as JSON: `{ kind, task, log }`. */
+function emitHostTaskJson(id) {
+    const hj = hostTaskLogJson(id);
+    if (!hj.found)
+        return false;
+    process.stdout.write(JSON.stringify({ kind: 'task', task: hj.task, log: hj.log ?? null }, null, 2) + '\n');
+    return true;
+}
 /** Show a resolved session — follow (tail), concise summary, or (`full`) transcript. */
-async function showSession(session, follow, full) {
+async function showSession(session, follow, full, json = false) {
+    if (json) {
+        await renderSessionLogJson(session);
+        return;
+    }
     if (follow) {
         if (!isTailable(session.agent)) {
             console.error(chalk.red(`Tailing is supported for claude and codex sessions only (got ${session.agent}).`));
@@ -55,17 +67,33 @@ async function showSession(session, follow, full) {
     }
     await renderSessionLog(session, full ? 'markdown' : 'summary');
 }
-async function showCandidate(c, follow, full) {
+async function showCandidate(c, follow, full, json = false) {
     if (c.kind === 'task') {
+        if (json) {
+            emitHostTaskJson(c.task.id);
+            return;
+        }
         const res = await showHostTaskLog(c.task.id, follow, full);
         if (res.exitCode !== undefined)
             process.exitCode = res.exitCode;
         return;
     }
-    await showSession(c.session, follow, full);
+    await showSession(c.session, follow, full, json);
 }
 /** Resolve an explicit id/--session: host task first, then a session. */
-async function showById(id, follow, full) {
+async function showById(id, follow, full, json = false) {
+    if (json) {
+        if (emitHostTaskJson(id))
+            return;
+        const sessions = await discoverSessions({ all: true, limit: 5000 });
+        const matches = resolveSessionById(sessions, id);
+        if (matches.length === 0) {
+            console.error(chalk.red(`No run or session found matching "${id}".`));
+            process.exit(1);
+        }
+        await renderSessionLogJson(matches[0]);
+        return;
+    }
     const hostRes = await showHostTaskLog(id, follow, full);
     if (hostRes.found) {
         if (hostRes.exitCode !== undefined)
@@ -85,7 +113,7 @@ async function runLogs(id, opts) {
     const full = !!opts.full;
     const directId = opts.session ?? id;
     if (directId) {
-        await showById(directId, follow, full);
+        await showById(directId, follow, full, !!opts.json);
         return;
     }
     const { agent, version } = parseAgentFilter(opts.agent);
@@ -110,7 +138,7 @@ async function runLogs(id, opts) {
         process.exit(1);
     }
     if (candidates.length === 1) {
-        await showCandidate(candidates[0], follow, full);
+        await showCandidate(candidates[0], follow, full, !!opts.json);
         return;
     }
     // Multiple sessions matched → picker if interactive, else a list to pick from.
@@ -134,7 +162,7 @@ async function runLogs(id, opts) {
     });
     if (!picked)
         return;
-    await showCandidate(picked.item, follow, full);
+    await showCandidate(picked.item, follow, full, !!opts.json);
 }
 function parseSince(s) {
     const m = s.match(/^(\d+)([smhdw])$/);
@@ -343,6 +371,7 @@ export function registerLogsCommand(program) {
         .option('--session <id>', 'Select a session/run by id (same as the positional id)')
         .option('-f, --follow', 'Follow live output')
         .option('-m, --full', 'Show the full raw transcript / stdout instead of the concise summary')
+        .option('--json', 'Machine-readable JSON: a host task as { kind, task, log }, a session as the redacted { session, events } (same shape as `sessions <id> --json`)')
         .action((id, opts) => runLogs(id, opts));
     logsCmd
         .command('audit')

package/dist/commands/mcp.js

@@ -147,6 +147,7 @@ When to use:
         .command('list [agent]')
         .description('Show which MCP servers are registered and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
+        .option('--json', 'Emit machine-readable JSON instead of the table/picker')
         .action(async (agentArg, options) => {
         const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
         const agentInput = agentArg || options.agent;
@@ -176,6 +177,7 @@ When to use:
             centralPath: getMcpDir(),
             filterAgent,
             filterVersion,
+            json: options.json,
         });
     });
     mcpCmd

package/dist/commands/resource-view.d.ts

@@ -33,6 +33,8 @@ export interface ResourceViewOptions {
     /** When the user specified agent or agent@version, we scope per-agent. */
     filterAgent?: AgentId;
     filterVersion?: string;
+    /** Emit machine-readable JSON instead of the picker/table (for agents/scripts). */
+    json?: boolean;
 }
 /** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export declare function showResourceList(opts: ResourceViewOptions): Promise<void>;

package/dist/commands/resource-view.js

@@ -14,6 +14,14 @@ import { isInteractiveTerminal, isPromptCancelled, printWithPager } from './util
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
 /** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export async function showResourceList(opts) {
+    if (opts.json) {
+        // Strip the non-serializable buildDetail thunk; emit the row metadata plus
+        // each resource's per-agent-version sync targets. One shared JSON contract
+        // for every resource `list` built on this helper.
+        const rows = opts.rows.map(({ buildDetail, ...row }) => row);
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
     if (opts.rows.length === 0) {
         console.log(chalk.gray(opts.emptyMessage));
         return;

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 };
 /**