@phnx-labs/agents-cli 1.20.33 → 1.20.35

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 1.20.35
+
+**CI: build node-pty's native binary on macOS/Windows so the release matrix is green cross-platform**
+
+- The cross-platform matrix (`ci.yml`, runs only on `release/**` + `v*`) installed deps with `bun install --ignore-scripts`, so `pty.node` from `@homebridge/node-pty-prebuilt-multiarch` was never fetched/built. That package ships prebuilt binaries only for Linux; macOS/Windows obtain `pty.node` via its own install script (prebuild-install download, else a node-gyp compile). With that script skipped the native module was absent, so the daemon-liveness integration test added in #568 — which spawns the real daemon (it loads node-pty) and asserts the browser IPC socket stays up — crashed on macOS/Windows while passing on Linux, and had been red on every release since. The matrix runs only on release branches, so it never surfaced on normal PRs (bun does not run that install script even without `--ignore-scripts` in bun 1.3.x). CI now runs a dedicated step that invokes the package's own install script (`npm run install`), which prefers a prebuilt download and falls back to a node-gyp compile, so it self-heals across platforms and node ABIs. Production (`npm install`) already built the native module, so end users were unaffected. A second macOS/Windows-only failure in the same #568 daemon-liveness test was also fixed: the test rooted its fake `HOME` under `os.tmpdir()`, which on macOS is the long `/var/folders/…/T/…`, pushing the daemon's AF_UNIX socket path to ~116 bytes — past macOS's 104-byte `sun_path` limit — so `bind()` failed with `EADDRINUSE`. The test now roots `HOME` at a short base on POSIX (Windows uses length-unlimited named pipes); real users with a normal `HOME` were never affected. Source: `.github/workflows/ci.yml`, `src/lib/daemon.test.ts`.
+
+**`agents logs`: a top-level, unified run-log viewer (#575)**
+
+- Viewing a dispatched run's output used to be nested and undiscoverable — only `agents hosts logs <id>` and `agents daemon logs` existed, and `agents hosts` wasn't even in `--help`. `agents logs [id]` is now a discoverable top-level command that resolves a run across **two substrates** — host-dispatch task stdout (`agents run --host`) and the local session index — and shows or (`-f`) follows it. `[id]`/`--session` load directly (host task tried first, then session); with no id, `--host`/`--agent`/`--version` filter a merged candidate list (one match shows, several open a fuzzy picker, non-TTY prints the list). Additive: `agents hosts logs` and `agents sessions tail` are unchanged and share the same helpers. Source: `src/commands/logs.ts`, `src/lib/hosts/logs.ts`.
+
+**Host-follow log tailer: no self-corruption on localhost, byte-accurate offsets (#586, #589)**
+
+- Following a run dispatched to **localhost** tripled the on-disk log and triple-printed the output, because the local mirror file and the remote log were the same file and the tailer appended its own reads back into it; it now detects that aliasing by file identity (`dev:ino`) and echoes only. Separately, the offset tracker advanced by a re-encoded string length, so a multibyte UTF-8 char split at a poll boundary drifted the offset and corrupted the stream on non-ASCII output; the tail is now byte-exact (raw `Buffer` via `sshExecRaw`). Source: `src/lib/hosts/progress.ts`, `src/lib/ssh-exec.ts`.
+
+**`agents upgrade`: the "What's new" changelog is now a compact heading list (#562)**
+
+- The post-upgrade changelog dumped every heading *and* every verbose sub-bullet for each version in the range — a screenful across a multi-version jump. It now prints one bullet per feature/fix heading and links to the full CHANGELOG for the details. The parser was extracted to a pure, unit-tested `renderWhatsNew` so it can be exercised without the CLI's import-time side effects. Source: `src/lib/whats-new.ts`, `src/index.ts`.
+
+**`agents sessions --active`: a per-pid registry de-collapses co-located agents (#546)**
+
+- On a host with no terminal extension (bare SSH/tmux — e.g. any Linux box), `--active` could only map a discovered agent process to a session by guessing the newest `.jsonl` in its cwd, so several agents in the same repo collapsed onto one session row (observed live: a single id listed 28 times), and `/restore` couldn't tell them apart. `agents run` now records each launch to `~/.agents/.cache/terminals/by-pid/<pid>.json` (`{agent, cwd, tmuxPane, sessionId, startedAtMs}`) — the headless equivalent of the terminal extension's `live-terminals.json` — so `--active` and `/restore` attribute each co-located agent correctly. Source: `src/lib/session/pid-registry.ts`, `src/lib/session/active.ts`, `src/lib/exec.ts`.
+
+## 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,34 @@ 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"   # follows live by default
+agents logs --host gpu-box              # pick a dispatched run and view its log
+agents logs <id> -f                     # re-attach to a running one and follow
+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).
+
+Every `--host` command rides one multiplexed SSH engine, tuned for driving a fleet from a small laptop: the first call to a machine opens a control socket and every later call reuses it (no repeat TCP+auth handshake), connections carry keepalive so a dropped link dies in ~45 s instead of zombying, and following a remote run polls in a single round-trip per cycle. Measured against a Tailscale-relayed host: repeated calls **~6–7× faster**, dispatch readiness **~2×**, and the follow loop **~21× faster with 50% fewer local ssh spawns**. Design: [docs/09-ssh-transport.md](docs/09-ssh-transport.md) · reproduce: `node scripts/bench-ssh.mjs <host>`.
+
+---
+
 ## Teams
 
 ```bash
@@ -646,11 +674,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 +702,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-actions.d.ts

@@ -55,4 +55,19 @@ export declare function buildWaitParams(opts: {
 };
 export declare function withClient<T>(fn: (client: ComputerClient) => Promise<T>): Promise<T>;
 export declare function unwrap(r: RPCResponse): Record<string, unknown>;
+export declare function resolveTargetPidDecision(client: ComputerClient, opts: {
+    pid?: number;
+    bundle?: string;
+}, gate?: {
+    verb?: string;
+    env?: NodeJS.ProcessEnv;
+    nowMs?: number;
+}): Promise<{
+    ok: true;
+    pid: number;
+    source: 'pid' | 'list_apps' | 'session_admission';
+} | {
+    ok: false;
+    error: string;
+}>;
 export declare function registerActionCommands(program: Command): void;

package/dist/commands/computer-actions.js

@@ -6,7 +6,88 @@
 // The daemon already implements every method; this file is the thin, typed
 // CLI skin over it plus a shared target resolver so callers stay in bundle-id
 // space and never hand-manage pids.
-import { openComputerClient, describeTransport, } from '../lib/computer-rpc.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { openComputerClient, describeTransport, resolvePolicyPath, } from '../lib/computer-rpc.js';
+import { COMPUTER_INPUT_GATED_VERBS, formatComputerPermissionGrantHint, } from '../lib/permissions.js';
+function isComputerInputVerb(verb) {
+    return typeof verb === 'string' && COMPUTER_INPUT_GATED_VERBS.includes(verb);
+}
+function computerSessionId(env = process.env) {
+    return env.CODEX_THREAD_ID
+        || env.CLAUDE_CODE_SESSION_ID
+        || env.CLAUDE_SESSION_ID
+        || env.AGENTS_SESSION_ID
+        || env.AGENTS_RUN_ID
+        || null;
+}
+function admissionCachePath(env = process.env) {
+    if (env.AGENTS_COMPUTER_ADMISSION_CACHE)
+        return env.AGENTS_COMPUTER_ADMISSION_CACHE;
+    return path.join(path.dirname(resolvePolicyPath()), 'computer-target-admissions.json');
+}
+function targetSelector(opts) {
+    return opts.bundle ? `bundle:${opts.bundle}` : 'frontmost';
+}
+function readAdmissionCache(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        return Array.isArray(parsed.admissions) ? parsed.admissions.filter(isAdmission) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function isAdmission(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const r = v;
+    return r.sessionId !== undefined
+        && typeof r.sessionId === 'string'
+        && typeof r.selector === 'string'
+        && r.gateClass === 'input'
+        && typeof r.pid === 'number'
+        && typeof r.bundle_id === 'string'
+        && typeof r.name === 'string'
+        && typeof r.admittedAtMs === 'number'
+        && isComputerInputVerb(r.admittedByVerb);
+}
+function rememberAdmission(app, opts) {
+    const sessionId = computerSessionId(opts.env);
+    if (!sessionId)
+        return;
+    const filePath = admissionCachePath(opts.env);
+    const admissions = readAdmissionCache(filePath);
+    const next = {
+        sessionId,
+        selector: opts.selector,
+        gateClass: 'input',
+        pid: app.pid,
+        bundle_id: app.bundle_id,
+        name: app.name,
+        admittedAtMs: opts.nowMs ?? Date.now(),
+        admittedByVerb: opts.verb,
+    };
+    const filtered = admissions.filter((a) => !(a.sessionId === sessionId && a.selector === opts.selector && a.gateClass === 'input'));
+    filtered.push(next);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify({ admissions: filtered }, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Cache persistence is best-effort; the daemon remains the final gate.
+    }
+}
+function findAdmission(opts) {
+    const sessionId = computerSessionId(opts.env);
+    if (!sessionId)
+        return null;
+    const admissions = readAdmissionCache(admissionCachePath(opts.env));
+    const matches = admissions
+        .filter((a) => a.sessionId === sessionId && a.selector === opts.selector && a.gateClass === 'input')
+        .sort((a, b) => b.admittedAtMs - a.admittedAtMs);
+    return matches[0] ?? null;
+}
 // Pure target picker — exercised by unit tests. Precedence: explicit --pid,
 // then --bundle, then the frontmost active allow-listed app (the same default
 // `screenshot` uses). Kept side-effect-free so the resolution rules are
@@ -24,7 +105,7 @@ export function pickTarget(list, opts) {
         if (!app) {
             return {
                 ok: false,
-                error: `bundle not in allow list (or not running): ${opts.bundle}\nadd Computer(${opts.bundle}) to a permissions group, then \`agents computer reload\``,
+                error: `bundle not in allow list (or not running): ${opts.bundle}\n${formatComputerPermissionGrantHint(opts.bundle)}`,
             };
         }
         return { ok: true, app };
@@ -33,7 +114,7 @@ export function pickTarget(list, opts) {
     if (!active) {
         return {
             ok: false,
-            error: 'no active app found in allow list\nadd Computer(<bundle-id>) to a permissions group, then `agents computer reload`',
+            error: `no active app found in allow list\n${formatComputerPermissionGrantHint()}`,
         };
     }
     return { ok: true, app: active };
@@ -141,20 +222,37 @@ export function unwrap(r) {
     }
     return r.result ?? {};
 }
-// Resolve the target pid via list_apps + pickTarget, printing a precise error
-// and exiting when no target matches.
-async function resolveTargetPid(client, opts) {
+export async function resolveTargetPidDecision(client, opts, gate) {
     // A directly-supplied pid skips the list_apps roundtrip — the daemon gates.
     if (opts.pid != null)
-        return opts.pid;
+        return { ok: true, pid: opts.pid, source: 'pid' };
     const apps = unwrap(await client.call('list_apps'));
     const list = apps.apps || [];
     const picked = pickTarget(list, opts);
+    const verb = gate?.verb;
+    const selector = targetSelector(opts);
+    if (picked.ok && isComputerInputVerb(verb)) {
+        rememberAdmission(picked.app, { selector, verb, env: gate?.env, nowMs: gate?.nowMs });
+    }
     if (!picked.ok) {
-        console.error(picked.error);
+        if (isComputerInputVerb(verb)) {
+            const admitted = findAdmission({ selector, env: gate?.env });
+            if (admitted)
+                return { ok: true, pid: admitted.pid, source: 'session_admission' };
+        }
+        return { ok: false, error: picked.error };
+    }
+    return { ok: true, pid: picked.app.pid, source: 'list_apps' };
+}
+// Resolve the target pid via list_apps + pickTarget, printing a precise error
+// and exiting when no target matches.
+async function resolveTargetPid(client, opts, gate) {
+    const resolved = await resolveTargetPidDecision(client, opts, gate);
+    if (!resolved.ok) {
+        console.error(resolved.error);
         process.exit(1);
     }
-    return picked.app.pid;
+    return resolved.pid;
 }
 // --raise flag: app-level focus_window before the main action so coordinate
 // clicks and keystrokes land on a visible, key window.
@@ -210,7 +308,7 @@ export function registerActionCommands(program) {
         .option('--depth <n>', 'Max tree depth', (v) => parseInt(v, 10))
         .option('--json', 'Emit compact JSON (default: pretty)')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'describe' });
             const params = { pid };
             if (opts.depth != null)
                 params.max_depth = opts.depth;
@@ -228,7 +326,7 @@ export function registerActionCommands(program) {
         .option('--raise', 'Bring the target app to the front first')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'click' });
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -250,7 +348,7 @@ export function registerActionCommands(program) {
         .description('Right-click (context menu) an element or coordinate')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'right-click' });
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -269,7 +367,7 @@ export function registerActionCommands(program) {
         .option('--allow-secure-field', 'Permit typing into a password field')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'type' });
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -295,7 +393,7 @@ export function registerActionCommands(program) {
         .option('--char-delay <ms>', 'Inter-character delay in ms (default 4; raise for lossy keyboard relays like VM guests, e.g. 25). Clamped to [1, 250].', (v) => parseInt(v, 10))
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'type-text' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = { pid, text: opts.text };
             if (opts.commit)
@@ -319,7 +417,7 @@ export function registerActionCommands(program) {
         .option('--require-frontmost', 'Fail (not warn) if the target is not the frontmost app')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'key' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = { pid, keys: opts.keys };
             if (opts.requireFrontmost)
@@ -350,7 +448,7 @@ export function registerActionCommands(program) {
             process.exit(1);
         }
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'drag' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = {
                 pid,
@@ -373,7 +471,7 @@ export function registerActionCommands(program) {
         .option('--raise', 'Bring the target app to the front first')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'scroll' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = { pid };
             if (opts.id)
@@ -398,7 +496,7 @@ export function registerActionCommands(program) {
         .requiredOption('--action <name>', 'AX action name')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'ax-action' });
             const res = unwrap(await client.call('ax_action', { pid, element_id: opts.id, action: opts.action }));
             emit(res, Boolean(opts.json), () => `performed ${opts.action}`);
         });
@@ -410,7 +508,7 @@ export function registerActionCommands(program) {
         .requiredOption('--id <@eN>', 'Element id from `describe`')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'focus' });
             const res = unwrap(await client.call('set_focus', { pid, element_id: opts.id }));
             emit(res, Boolean(opts.json), () => `focused ${opts.id}`);
         });
@@ -426,7 +524,7 @@ export function registerActionCommands(program) {
         .option('--title <s>', 'Raise the window whose title contains this string')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'raise' });
             const res = unwrap(await client.call('focus_window', { pid, ...buildRaiseParams(opts) }));
             emit(res, Boolean(opts.json), () => {
                 const scope = res.raised_window ? `window ${res.title ?? res.window_id ?? ''}`.trim() : 'app';
@@ -455,7 +553,7 @@ export function registerActionCommands(program) {
             const params = { ...spec.params };
             // duration-only waits don't need a target pid
             if (params.duration_ms == null)
-                params.pid = await resolveTargetPid(client, opts);
+                params.pid = await resolveTargetPid(client, opts, { verb: 'wait' });
             const res = unwrap(await client.call('wait', params));
             emit(res, Boolean(opts.json), () => res.satisfied ? `satisfied (${res.waited_ms}ms)` : `timed out (${res.waited_ms}ms)`);
         });
@@ -468,7 +566,7 @@ export function registerActionCommands(program) {
         .option('--max-chars <n>', 'Cap the extracted text length', (v) => parseInt(v, 10))
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'get-text' });
             const params = { pid };
             if (opts.id)
                 params.element_id = opts.id;

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

@@ -4,6 +4,7 @@ import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { queryUsageRollup, topSessionsByCost, } from '../lib/session/db.js';
 import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
+import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 export function registerCostCommand(program) {
     addHostOption(program.command('cost'))
         .description('Roll up $ cost and duration across local agent sessions')
@@ -84,27 +85,36 @@ async function costAction(options) {
     // Top sessions by cost.
     if (top.length > 0) {
         out.push(chalk.bold('Top sessions by cost'));
+        const cols = terminalWidth();
+        const showProject = cols >= 100;
         const costW = Math.max(...top.map(t => formatUsd(t.costUsd).length), 4);
         for (const t of top) {
             const cost = formatUsd(t.costUsd).padStart(costW);
             const dur = t.durationMs > 0 ? formatDuration(t.durationMs) : '—';
-            const label = t.meta.label || t.meta.topic || '(untitled)';
-            const proj = t.meta.project ? chalk.gray(` ${t.meta.project}`) : '';
-            out.push(`  ${chalk.green(cost)}  ${chalk.gray(t.meta.shortId)}  ${chalk.cyan(t.meta.agent.padEnd(7))} ${truncate(label, 48)}` +
-                proj +
-                chalk.gray(`  ${dur}`));
+            const label = (t.meta.label || t.meta.topic || '(untitled)').replace(/\s+/g, ' ').trim();
+            const proj = showProject && t.meta.project ? chalk.gray(` ${t.meta.project}`) : '';
+            const prefix = `  ${chalk.green(cost)}  ${chalk.gray(t.meta.shortId)}  ${chalk.cyan(t.meta.agent.padEnd(7))} `;
+            const suffix = proj + chalk.gray(`  ${dur}`);
+            const topicW = Math.max(12, cols - stringWidth(prefix) - stringWidth(suffix));
+            out.push(prefix + truncateToWidth(label, topicW) + suffix);
         }
         out.push('');
     }
     // Per-agent / per-project / per-day breakdown.
     const groupLabel = groupBy === 'agent' ? 'agent' : groupBy === 'project' ? 'project' : 'day';
     out.push(chalk.bold(`By ${groupLabel}`));
-    const keyW = Math.max(...breakdown.map(r => r.key.length), groupLabel.length);
+    const cols = terminalWidth();
     const costW2 = Math.max(...breakdown.map(r => formatUsd(r.costUsd).length), 4);
+    const countW = Math.max(...breakdown.map(r => String(r.sessionCount).length), 1);
+    const sessionW = Math.max(...breakdown.map(r => `${String(r.sessionCount).padStart(countW)} session${r.sessionCount !== 1 ? 's' : ''}`.length));
+    const durationW = Math.max(...breakdown.map(r => r.durationMs > 0 ? stringWidth(formatDuration(r.durationMs)) : 1), 1);
+    const fixedW = 2 + 2 + costW2 + 2 + sessionW + 2 + durationW;
+    const keyW = Math.max(8, Math.min(Math.max(...breakdown.map(r => stringWidth(r.key)), groupLabel.length), cols - fixedW));
     for (const r of breakdown) {
         const cost = formatUsd(r.costUsd).padStart(costW2);
         const dur = r.durationMs > 0 ? formatDuration(r.durationMs) : '—';
-        out.push(`  ${r.key.padEnd(keyW)}  ${chalk.green(cost)}  ${chalk.gray(`${r.sessionCount} session${r.sessionCount !== 1 ? 's' : ''}`)}  ${chalk.gray(dur)}`);
+        const sessions = `${String(r.sessionCount).padStart(countW)} session${r.sessionCount !== 1 ? 's' : ''}`;
+        out.push(`  ${padToWidth(truncateToWidth(r.key, keyW), keyW)}  ${chalk.green(cost)}  ${chalk.gray(padToWidth(sessions, sessionW))}  ${chalk.gray(padToWidth(dur, durationW))}`);
     }
     console.log(out.join('\n'));
 }
@@ -132,8 +142,3 @@ function renderDailyHistogram(daily) {
     }
     return lines.join('\n');
 }
-/** Truncate a string to n chars with an ellipsis. */
-function truncate(s, n) {
-    const oneLine = s.replace(/\s+/g, ' ').trim();
-    return oneLine.length > n ? oneLine.slice(0, n - 1) + '…' : oneLine;
-}

package/dist/commands/doctor.d.ts

@@ -22,4 +22,15 @@
  * apply pending sync.
  */
 import type { Command } from 'commander';
+export declare function wrapLine(prefix: string, text: string, width?: number): string[];
+/**
+ * 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;