@phnx-labs/agents-cli 1.20.33 → 1.20.34

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 1.20.34
+
+**Test suite runs remotely on a crabbox VM (#525, #540)**
+
+- `scripts/release.sh`'s test gate now runs `bun install && bun run build && bun run test` on a leased crabbox VM via `scripts/sandbox.sh` instead of freezing the local machine, matching CI's Build→Test order (crabbox's sync honors `.gitignore`, so the gitignored `dist/` is built on the box). A new `bun run test:remote` offloads the suite the same way for local dev. Publishing still happens locally — only the signed macOS keychain helper can be produced and notarized here, and crabbox boxes are Linux. Source: `scripts/sandbox.sh`, `scripts/release.sh`, `package.json`.
+- `scripts/sandbox.sh` box acquisition is now robust: secrets load via `agents secrets export --plaintext` (the bare form now hard-errors), a missing `.crabbox.yaml` no longer aborts the script under `set -e`, and the agents-cli/claude install is gated to PR mode so test-mode runs match GitHub CI. Box selection gates on `crabbox status … ready=true` — skipping failed-bootstrap duds (which still report `status=running`) and warming a fresh box if none are ready — keyed on the stable `profile` label rather than an ephemeral slug. A dedicated `agents-cli` crabbox profile (`.crabbox.yaml`) isolates this repo's warm pool. Source: `scripts/sandbox.sh`, `.crabbox.yaml`.
+
 ## 1.20.31
 
 **`agents sessions <id>`: a catch-up digest for switching between many agents (#502)**

package/README.md

@@ -230,6 +230,30 @@ Profile YAML has no secrets -- safe to `agents repo push` to a shared repo. `age
 
 ---
 
+## Run on your own machines
+
+Dispatch any read-only or config command -- and `agents run` itself -- to another machine over SSH. No daemon.
+
+```bash
+# Enroll a machine (from ~/.ssh/config, or inline with user@address)
+agents hosts add gpu-box
+agents hosts check gpu-box              # reachable? which agents-cli version?
+
+# Run there instead of locally
+agents run claude --host gpu-box "profile this build"
+agents view claude --host gpu-box       # inspect the remote install
+agents sync --host gpu-box              # make the remote machine current
+
+# Your Tailscale fleet, auto-discovered
+agents devices sync                     # ingest `tailscale status`
+agents ssh mac-mini                     # hardened SSH: fails fast if offline,
+                                        # PowerShell on Windows, password-from-Keychain
+```
+
+**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. See [docs/00-concepts.md](docs/00-concepts.md#devices--hosts).
+
+---
+
 ## Teams
 
 ```bash
@@ -646,11 +670,13 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 
 Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](src/lib/capabilities.ts). Full matrix also in [docs/00-concepts.md](docs/00-concepts.md).
 
+> **† Gemini CLI is deprecated.** Google retired it for free, Pro, and Ultra tiers on **June 18, 2026** (announced at Google I/O 2026); the `gemini` command no longer serves requests on those tiers. agents-cli still manages existing installs, but warns on `agents add gemini` and `agents teams add … gemini`. New setups should use **Antigravity CLI** (`antigravity`), Google's official successor — see [the transition notice](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/).
+
 | Agent | Versions | Hooks | MCP | Permissions | Skills | Commands | Plugins | Subagents | Rules | Workflows |
 |-------|----------|-------|-----|-------------|--------|----------|---------|-----------|-------|-----------|
 | Claude Code | yes | yes | yes | yes | yes | yes | yes | yes | `CLAUDE.md` | yes |
 | Codex CLI | yes | >= 0.116.0 | yes | no | yes | < 0.117.0 · skills ($name, >= 0.117) | >= 0.128.0 | no | `AGENTS.md` | no |
-| Gemini CLI | yes | >= 0.26.0 | yes | no | yes | yes (.toml) | no | no | `GEMINI.md` | no |
+| Gemini CLI † | yes | >= 0.26.0 | yes | no | yes | yes (.toml) | no | no | `GEMINI.md` | no |
 | Antigravity | yes | yes | yes | yes | yes | yes | yes | no | `AGENTS.md` | no |
 | Grok Build | yes | yes | yes | yes | yes | skills ($name) | yes | no | `AGENTS.md` | no |
 | OpenClaw | yes | yes | yes | no | yes | gateway | yes | yes | `workspace/AGENTS.md` | no |
@@ -672,7 +698,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 |-------|----------|-------|---------------|
 | Claude Code | yes | yes | yes |
 | Codex CLI | yes | yes | yes |
-| Gemini CLI | yes | yes | yes |
+| Gemini CLI † | yes | yes | yes |
 | Cursor | -- | yes | -- |
 | OpenCode | -- | yes | -- |
 | Grok Build | -- | yes | yes |

package/dist/commands/computer.d.ts

@@ -12,6 +12,29 @@ export declare function shouldBlockOffPlatform(opts: {
     tcpConfigured: boolean;
     host?: string;
 }): boolean;
+/**
+ * Sniff the image format from the leading magic bytes: PNG starts with the
+ * 8-byte signature `89 50 4E 47` ("\x89PNG"), JPEG with `FF D8 FF`. Returns the
+ * canonical file extension, or null for anything else.
+ */
+export declare function detectImageFormat(buf: Buffer): '.png' | '.jpg' | null;
+/**
+ * Make the screenshot filename honest about its bytes. The two helper backends
+ * encode DIFFERENT formats and neither re-encodes to match the requested name:
+ * the macOS helper (ScreenCaptureKit) returns JPEG
+ * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * the Windows helper returns PNG
+ * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * cannot be correct for both — the only honest path is to sniff the real format
+ * and swap the extension to match. Pure so it's unit-testable.
+ *
+ * Returns the path to write to (caller's path with its extension corrected) and
+ * whether a correction was made. Unknown formats pass through unchanged.
+ */
+export declare function reconcileScreenshotExt(outPath: string, buf: Buffer): {
+    path: string;
+    corrected: boolean;
+};
 export declare function registerComputerCommand(program: Command): void;
 export declare function registerComputerSubcommands(program: Command): void;
 export { resolveHelperExec as resolveHelperPath };

package/dist/commands/computer.js

@@ -33,6 +33,42 @@ export function shouldBlockOffPlatform(opts) {
         return false; // remote path resolves its own endpoint
     return true;
 }
+/**
+ * Sniff the image format from the leading magic bytes: PNG starts with the
+ * 8-byte signature `89 50 4E 47` ("\x89PNG"), JPEG with `FF D8 FF`. Returns the
+ * canonical file extension, or null for anything else.
+ */
+export function detectImageFormat(buf) {
+    if (buf.length >= 4 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
+        return '.png';
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return '.jpg';
+    return null;
+}
+/**
+ * Make the screenshot filename honest about its bytes. The two helper backends
+ * encode DIFFERENT formats and neither re-encodes to match the requested name:
+ * the macOS helper (ScreenCaptureKit) returns JPEG
+ * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * the Windows helper returns PNG
+ * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * cannot be correct for both — the only honest path is to sniff the real format
+ * and swap the extension to match. Pure so it's unit-testable.
+ *
+ * Returns the path to write to (caller's path with its extension corrected) and
+ * whether a correction was made. Unknown formats pass through unchanged.
+ */
+export function reconcileScreenshotExt(outPath, buf) {
+    const actual = detectImageFormat(buf);
+    if (!actual)
+        return { path: outPath, corrected: false };
+    const cur = path.extname(outPath).toLowerCase();
+    const alreadyMatches = cur === actual || (actual === '.jpg' && (cur === '.jpg' || cur === '.jpeg'));
+    if (alreadyMatches)
+        return { path: outPath, corrected: false };
+    const base = outPath.slice(0, outPath.length - path.extname(outPath).length);
+    return { path: base + actual, corrected: true };
+}
 export function registerComputerCommand(program) {
     const computer = program
         .command('computer')
@@ -128,8 +164,8 @@ function registerScreenshotCommand(program) {
         .option('--list', 'List the app\'s windows (id/title/layer/bounds) instead of capturing — reveals modals/popups')
         .option('--window-id <n>', 'Capture a specific window by id (from --list)', (v) => parseInt(v, 10))
         .option('--display', 'Capture the whole display the app is on (composites stacked modals)')
-        .option('--out <path>', 'Output JPEG path', './computer-screenshot.jpg')
-        .option('--quality <n>', 'JPEG quality 1-100', (v) => parseInt(v, 10), 85)
+        .option('--out <path>', 'Output image path — extension auto-corrected to the encoded format (JPEG on macOS, PNG on a Windows --host)', './computer-screenshot.jpg')
+        .option('--quality <n>', 'JPEG quality 1-100 (macOS capture only; the Windows helper encodes lossless PNG and ignores this)', (v) => parseInt(v, 10), 85)
         .option('--json', 'Emit JSON (metadata for captures; window list for --list)')
         .action(async (opts) => {
         const quality = Math.max(1, Math.min(100, opts.quality || 85));
@@ -176,7 +212,10 @@ function registerScreenshotCommand(program) {
                 process.exit(1);
             }
             const buf = Buffer.from(b64, 'base64');
-            const outPath = path.resolve(opts.out);
+            // Sniff the real format and correct the extension so the filename never
+            // lies about its bytes (macOS -> JPEG, Windows helper -> PNG).
+            const requested = path.resolve(opts.out);
+            const { path: outPath, corrected } = reconcileScreenshotExt(requested, buf);
             fs.writeFileSync(outPath, buf);
             if (opts.json) {
                 // Drop the heavy base64 from the metadata echo; report where it went.
@@ -184,6 +223,9 @@ function registerScreenshotCommand(program) {
                 console.log(JSON.stringify(meta, null, 2));
             }
             else {
+                if (corrected) {
+                    console.log(`note: bytes are ${path.extname(outPath).slice(1).toUpperCase()}; corrected extension from ${path.basename(requested)}`);
+                }
                 const origin = res.origin || [];
                 const originStr = origin.length === 2 ? `, origin [${origin.join(',')}], scale ${res.scale ?? '?'}` : '';
                 console.log(`saved: ${outPath} (${res.width ?? '?'}x${res.height ?? '?'}, ${buf.byteLength} bytes${originStr})`);

package/dist/commands/doctor.d.ts

@@ -22,4 +22,14 @@
  * apply pending sync.
  */
 import type { Command } from 'commander';
+/**
+ * Windows-only advisory lines. When the effective PowerShell execution policy
+ * blocks unsigned local `.ps1` scripts (`Restricted`/`AllSigned`), the generated
+ * `agents.ps1` launcher fails in PowerShell even when it is on PATH. Surface the
+ * remediation; the `.cmd` companion still works, so this is a warning, not an
+ * error, and doctor never auto-changes the policy. Pure — returns `[]` on
+ * non-Windows or a permissive policy, so it is testable without invoking
+ * PowerShell.
+ */
+export declare function execPolicyWarningLines(platform: NodeJS.Platform, policy: string | null): string[];
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -12,6 +12,7 @@ import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 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 * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
@@ -208,6 +209,48 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
     for (const err of hostClis.errors) {
         console.log(`  ${chalk.red('err  ')}  ${chalk.gray(err.file)}: ${chalk.gray(err.reason)}`);
     }
+    // On Windows a Restricted/AllSigned execution policy silently breaks the
+    // generated `agents.ps1` launcher — postinstall diagnoses it interactively,
+    // but a non-interactive install never sees that. Surface it here too.
+    renderExecPolicyAdvisory();
+}
+// ─── windows execution-policy advisory ─────────────────────────────────────────
+/**
+ * Windows-only advisory lines. When the effective PowerShell execution policy
+ * blocks unsigned local `.ps1` scripts (`Restricted`/`AllSigned`), the generated
+ * `agents.ps1` launcher fails in PowerShell even when it is on PATH. Surface the
+ * remediation; the `.cmd` companion still works, so this is a warning, not an
+ * error, and doctor never auto-changes the policy. Pure — returns `[]` on
+ * non-Windows or a permissive policy, so it is testable without invoking
+ * PowerShell.
+ */
+export function execPolicyWarningLines(platform, policy) {
+    if (platform !== 'win32')
+        return [];
+    if (!blocksLocalScripts(policy))
+        return [];
+    return [
+        `PowerShell execution policy is ${policy} — it blocks the generated agents.ps1 launcher.`,
+        'Fix: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned',
+        'The agents.cmd shim still works regardless of the policy.',
+    ];
+}
+function renderExecPolicyAdvisory() {
+    // Only probe the policy on Windows — getEffectiveExecutionPolicy() spawns
+    // powershell, which is a wasted (doomed) process on POSIX where the advisory
+    // never applies.
+    if (process.platform !== 'win32')
+        return;
+    const lines = execPolicyWarningLines(process.platform, getEffectiveExecutionPolicy());
+    if (lines.length === 0)
+        return;
+    console.log();
+    console.log(chalk.bold('Execution policy (Windows)'));
+    const [headline, ...rest] = lines;
+    console.log(`  ${chalk.yellow('warn ')}  ${headline}`);
+    for (const line of rest) {
+        console.log(chalk.gray(`           ${line}`));
+    }
 }
 function parseTargetArg(arg) {
     const at = arg.indexOf('@');
@@ -547,6 +590,12 @@ export function registerDoctorCommand(program) {
                 return;
             }
             renderOverviewText(clis, syncRows, orphanRows, hostClis);
+            // Point at the interactive reconcile when anything is out of sync — the
+            // report shouldn't be a dead end. `agents status` runs the unified
+            // home-reading engine and offers to sync (opt-in, never auto-fires here).
+            if (syncRows.some((r) => r.status !== 'fresh')) {
+                console.log(chalk.gray('\nRun `agents status` to review and sync what has drifted.'));
+            }
             return;
         }
         const parsed = parseTargetArg(target);

package/dist/commands/import.js

@@ -263,7 +263,7 @@ When to use:
   pointing at the existing install — nothing is copied or moved (except the
   agent's config dir, which is moved into the version's home). Works for both
   npm-style packages (claude, codex, gemini, opencode, openclaw) and
-  installScript-based agents (grok, antigravity, cursor, kiro, goose, roo).
+  installScript-based agents (grok, antigravity, cursor, kiro, goose).
 `)
         .action(runImport);
 }

package/dist/commands/rules.js

@@ -51,7 +51,7 @@ Project rules & @-imports:
   @path imports inside AGENTS.md/CLAUDE.md are resolved at session start by the agent
   itself, not by agents-cli. Support is per-agent:
     Inlined natively:  claude, gemini
-    Literal text:      codex, cursor, opencode, copilot, amp, kiro, goose, roo
+    Literal text:      codex, cursor, opencode, copilot, amp, kiro, goose
 
   For rules that need to work across all agents, inline the content rather than using
   @-imports — the second group will load '@path/to/file.md' as a literal string.

package/dist/commands/secrets-migrate.js

@@ -23,7 +23,7 @@ import chalk from 'chalk';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { deleteKeychainToken, getKeychainToken, hasKeychainToken, listKeychainItems, setKeychainToken, } from '../lib/secrets/index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, listLegacyKeychainItems, setKeychainToken, } from '../lib/secrets/index.js';
 import { getBackupsDir } from '../lib/state.js';
 import { encryptBlob, MIN_PASSPHRASE_LEN } from '../lib/secrets/sync.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -104,6 +104,7 @@ export function registerSecretsMigrateAclCommand(secrets) {
         .description('Refresh existing keychain ACLs to use the signed Agents CLI helper. Dry-run by default.')
         .option('--commit', 'Perform writes (default is dry-run reporting only)')
         .option('--prefix <p>', `Restrict to items beginning with PREFIX (default ${ITEM_PREFIX})`, ITEM_PREFIX)
+        .option('--all', 'Rewrite EVERY matching item, not just legacy stragglers (slower; a Touch ID prompt per item)')
         .option('--passphrase-env <var>', 'Read the backup passphrase from this env var instead of prompting')
         .action(async (opts) => {
         try {
@@ -114,15 +115,24 @@ export function registerSecretsMigrateAclCommand(secrets) {
             if (!prefix.startsWith(ITEM_PREFIX)) {
                 throw new Error(`--prefix must start with '${ITEM_PREFIX}' to avoid touching unrelated Keychain items (got '${prefix}').`);
             }
-            const items = listKeychainItems(prefix).map((item) => {
+            // Default: migrate ONLY legacy stragglers (items still in the file-based
+            // keychain) — modern DP items need no rewrite and touching them is a
+            // Touch ID prompt per item for nothing. `--all` forces the old full
+            // rewrite. Either way this is one command over every matching item — no
+            // one-by-one invocation.
+            const names = opts.all ? listKeychainItems(prefix) : listLegacyKeychainItems(prefix);
+            const items = names.map((item) => {
                 const localExists = hasKeychainToken(item);
                 return { item, sync: !localExists };
             });
             if (items.length === 0) {
-                console.log(chalk.gray(`No keychain items with prefix '${prefix}'.`));
+                console.log(opts.all
+                    ? chalk.gray(`No keychain items with prefix '${prefix}'.`)
+                    : chalk.green(`Nothing to migrate — all items under '${prefix}' already use the modern ACL.`));
                 return;
             }
-            console.log(chalk.bold(`Found ${items.length} item(s) under '${prefix}'.`));
+            const label = opts.all ? 'item' : 'legacy item';
+            console.log(chalk.bold(`Found ${items.length} ${label}(s) under '${prefix}' to migrate.`));
             if (!opts.commit) {
                 for (const { item, sync } of items) {
                     console.log(`  ${chalk.cyan(item)} ${chalk.gray(sync ? '(synced)' : '(local)')}`);
@@ -131,16 +141,18 @@ export function registerSecretsMigrateAclCommand(secrets) {
                 console.log(chalk.gray('Dry-run — pass --commit to perform the migration.'));
                 return;
             }
-            // Commit phase. Snapshot every value first, encrypt, then mutate.
+            // Commit phase. Snapshot every value first (one batched read behind a
+            // single helper process, so DP items share one auth context), encrypt,
+            // then mutate.
+            const fetched = getKeychainTokens(items.map((i) => i.item));
             const records = [];
             for (const { item, sync } of items) {
-                try {
-                    const value = getKeychainToken(item);
-                    records.push({ item, sync, value });
-                }
-                catch (err) {
-                    console.error(chalk.red(`Skipping '${item}': read failed (${err.message}).`));
+                const value = fetched.get(item);
+                if (value === undefined) {
+                    console.error(chalk.red(`Skipping '${item}': read failed or item absent.`));
+                    continue;
                 }
+                records.push({ item, sync, value });
             }
             if (records.length === 0) {
                 console.error(chalk.red('No items could be read. Aborting before any writes.'));

package/dist/commands/secrets.d.ts

@@ -18,3 +18,23 @@ export { SSH_TARGET_RE, assertValidSshTarget };
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
+ * NO quoting of its own, so an unquoted arg with a space is split into several
+ * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
+ * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
+ * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
+ * rules, so the *child's* argv parse reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * `agents secrets exec` runs a caller-supplied command against a bundle the
+ * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
+ * ever changes (exec'ing an untrusted command line), route through a shell that
+ * disables expansion rather than relying on this quoter. An empty arg becomes
+ * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
+ * under `process.platform === 'win32'`).
+ */
+export declare function quoteWin32ExecArg(arg: string): string;

package/dist/commands/secrets.js

@@ -1325,8 +1325,18 @@ Examples:
                 secretEnv = readAndResolveBundleEnv(bundleName, { caller: `command ${cmd}` }).env;
             }
             const { spawn } = await import('child_process');
-            const proc = spawn(cmd, args, {
+            // On Windows, spawn without a shell ENOENTs for `.cmd`/`.bat` launchers
+            // (npm, yarn, most JS CLIs) and shell built-ins, so we set shell:true.
+            // With shell:true Node hands cmd.exe a single command line with NO quoting
+            // of its own, so args containing spaces or cmd metacharacters must be
+            // quoted here (quoteWin32ExecArg) or they'd be split. See that helper for
+            // the cmd.exe %VAR%/!VAR! expansion caveat.
+            const useShell = process.platform === 'win32';
+            const spawnCmd = useShell ? quoteWin32ExecArg(cmd) : cmd;
+            const spawnArgs = useShell ? args.map(quoteWin32ExecArg) : args;
+            const proc = spawn(spawnCmd, spawnArgs, {
                 stdio: 'inherit',
+                shell: useShell,
                 env: { ...process.env, ...secretEnv },
             });
             proc.on('close', (code) => process.exit(code ?? 0));
@@ -1619,6 +1629,48 @@ function humanRemaining(expiresAt) {
     const days = Math.round(hours / 24);
     return `locks in ${days} day${days === 1 ? '' : 's'}`;
 }
+/**
+ * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
+ * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
+ * NO quoting of its own, so an unquoted arg with a space is split into several
+ * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
+ * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
+ * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
+ * rules, so the *child's* argv parse reconstructs the original argument.
+ *
+ * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
+ * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
+ * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
+ * `agents secrets exec` runs a caller-supplied command against a bundle the
+ * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
+ * ever changes (exec'ing an untrusted command line), route through a shell that
+ * disables expansion rather than relying on this quoter. An empty arg becomes
+ * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
+ * under `process.platform === 'win32'`).
+ */
+export function quoteWin32ExecArg(arg) {
+    if (arg.length > 0 && !/[\s"&|<>()^]/.test(arg))
+        return arg;
+    let result = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if (ch === '\\') {
+            backslashes += 1;
+            continue;
+        }
+        if (ch === '"') {
+            // Double the run of backslashes, then escape this quote.
+            result += '\\'.repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+            continue;
+        }
+        result += '\\'.repeat(backslashes) + ch;
+        backslashes = 0;
+    }
+    // Trailing backslashes precede the closing quote → must be doubled.
+    result += '\\'.repeat(backslashes * 2) + '"';
+    return result;
+}
 /**
  * Copy text to the system clipboard, cross-platform.
  * macOS: `pbcopy`. Windows: `clip`. Linux: tries `wl-copy` (Wayland), then

package/dist/commands/status.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents status` — the unified sync-status surface.
+ *
+ * One command that answers "is my fleet in sync?" the same way every other
+ * surface does, because it reads the same engine (computeSyncStatus). Human mode
+ * renders the summary and, when a TTY finds drift, offers the interactive
+ * "sync now?" flow (promptDriftSync). `--json` emits the stable UnifiedSyncStatus
+ * contract the menu-bar and Agency consume. `--yes` reconciles everything with no
+ * prompts (the "kick it" path, safe in scripts).
+ */
+import { Command } from 'commander';
+export declare function registerStatusCommand(program: Command): void;

package/dist/commands/status.js

@@ -0,0 +1,81 @@
+/**
+ * `agents status` — the unified sync-status surface.
+ *
+ * One command that answers "is my fleet in sync?" the same way every other
+ * surface does, because it reads the same engine (computeSyncStatus). Human mode
+ * renders the summary and, when a TTY finds drift, offers the interactive
+ * "sync now?" flow (promptDriftSync). `--json` emits the stable UnifiedSyncStatus
+ * contract the menu-bar and Agency consume. `--yes` reconciles everything with no
+ * prompts (the "kick it" path, safe in scripts).
+ */
+import chalk from 'chalk';
+import { AGENTS } from '../lib/agents.js';
+import { setHelpSections } from '../lib/help.js';
+import { computeSyncStatus } from '../lib/sync-status.js';
+import { promptDriftSync } from '../lib/drift-sync.js';
+const agentName = (id) => AGENTS[id]?.name ?? id;
+function versionSummary(v) {
+    if (!v.everSynced)
+        return chalk.gray('never synced');
+    if (v.needsSync) {
+        const bits = [];
+        if (v.counts.drifted)
+            bits.push(`${v.counts.drifted} drifted`);
+        if (v.counts.missing)
+            bits.push(`${v.counts.missing} missing`);
+        return chalk.yellow(bits.join(' · '));
+    }
+    return chalk.green('in sync');
+}
+export function registerStatusCommand(program) {
+    const cmd = program
+        .command('status')
+        .description('Unified sync status across the fleet — what is drifted, missing, or behind, with an option to sync it.')
+        .option('--json', 'Output the machine-readable UnifiedSyncStatus contract')
+        .option('--yes', 'Reconcile everything detected (pull .system if behind + sync drifted/missing resources) without prompting')
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
+    setHelpSections(cmd, {
+        examples: `
+      # Show what's out of sync; offer to fix it (interactive)
+      agents status
+
+      # Machine-readable status for the menu-bar / Agency
+      agents status --json
+
+      # Reconcile everything with no prompts (CI / scripts / the "kick it" path)
+      agents status --yes
+    `,
+    });
+    cmd.action(async (opts) => {
+        const cwd = opts.cwd ?? process.cwd();
+        if (opts.json) {
+            const status = await computeSyncStatus({ cwd });
+            console.log(JSON.stringify(status, null, 2));
+            return;
+        }
+        const status = await computeSyncStatus({ cwd });
+        // Human summary header (always) — the per-version readout.
+        console.log(chalk.bold('Fleet sync status'));
+        if (status.system.unknown) {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.gray('freshness unknown (no upstream)')}`);
+        }
+        else if (status.system.behind > 0) {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.yellow(`${status.system.behind} behind`)}`);
+        }
+        else {
+            console.log(`  ${'.system repo'.padEnd(28)} ${chalk.green('up to date')}`);
+        }
+        if (status.agents.length === 0) {
+            console.log(chalk.gray('  (no installed agent versions)'));
+        }
+        for (const v of status.agents) {
+            const label = `${agentName(v.agent)}@${v.version}${v.isDefault ? chalk.gray(' (default)') : ''}`;
+            console.log(`  ${label.padEnd(28)} ${versionSummary(v)}`);
+        }
+        if (status.totals.orphan > 0) {
+            console.log(chalk.gray(`  (${status.totals.orphan} orphan${status.totals.orphan === 1 ? '' : 's'} — run \`agents prune cleanup\`)`));
+        }
+        // Hand off to the shared interactive/apply flow (summary already printed above).
+        await promptDriftSync({ cwd, yes: opts.yes, status, quiet: true });
+    });
+}