@phnx-labs/agents-cli 1.20.34 → 1.20.35

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## 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)**

package/README.md

@@ -240,7 +240,9 @@ 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 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
 
@@ -252,6 +254,8 @@ agents ssh mac-mini                     # hardened SSH: fails fast if offline,
 
 **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

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/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,6 +22,7 @@
  * 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

package/dist/commands/doctor.js

@@ -13,6 +13,7 @@ import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
 import { heal, healChangedAnything } from '../lib/heal.js';
 import { blocksLocalScripts, getEffectiveExecutionPolicy } from '../lib/platform/winpath.js';
+import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
@@ -29,7 +30,6 @@ function divergenceLines(report) {
         else if (p.status === 'diff')
             lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
     }
-    const counts = [];
     for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
         const rows = report.kinds[kind];
         const miss = rows.filter((r) => r.status === 'missing').length;
@@ -40,12 +40,44 @@ function divergenceLines(report) {
         if (dif)
             bits.push(`${dif} drifted`);
         if (bits.length)
-            counts.push(`${kind} ${bits.join('/')}`);
+            lines.push(`${kind.padEnd(11)} ${bits.join(' · ')}`);
     }
-    if (counts.length)
-        lines.push(counts.join(' · '));
     return lines;
 }
+function collapseWhitespace(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+export function wrapLine(prefix, text, width = terminalWidth()) {
+    const words = collapseWhitespace(text).split(' ').filter(Boolean);
+    if (words.length === 0)
+        return [prefix.trimEnd()];
+    const continuation = ' '.repeat(stringWidth(prefix));
+    const lines = [];
+    let linePrefix = prefix;
+    let line = prefix;
+    let hasWord = false;
+    for (const word of words) {
+        const room = Math.max(1, width - stringWidth(linePrefix));
+        const piece = stringWidth(word) > room ? truncateToWidth(word, room) : word;
+        const candidate = hasWord ? `${line} ${piece}` : `${line}${piece}`;
+        if (hasWord && stringWidth(candidate) > width) {
+            lines.push(line);
+            linePrefix = continuation;
+            line = continuation + piece;
+            hasWord = true;
+        }
+        else {
+            line = candidate;
+            hasWord = true;
+        }
+    }
+    lines.push(line);
+    return lines;
+}
+function printWrappedLine(prefix, text) {
+    for (const line of wrapLine(prefix, text))
+        console.log(chalk.gray(line));
+}
 function checkSyncStatus(cwd) {
     const rows = [];
     // Every installed version, not just the default — a stale NON-default version
@@ -130,7 +162,7 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         }
     }
     if (hidden.length > 0) {
-        console.log(chalk.gray(`  +${hidden.length} more supported (${hidden.join(', ')}) — \`agents add <name>\` to manage`));
+        printWrappedLine('  ', `+${hidden.length} more supported (${hidden.join(', ')}) — \`agents add <name>\` to manage`);
     }
     console.log();
     console.log(chalk.bold('Sync status (installed versions)'));
@@ -162,7 +194,7 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         // Version homes are reconciled only by management commands, so point at one
         // rather than promising an auto-sync that never happens.
         if (anyOutOfSync) {
-            console.log(chalk.gray('  Reconcile with `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>` (not applied on launch).'));
+            printWrappedLine('  ', 'Reconcile with `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>` (not applied on launch).');
         }
     }
     console.log();
@@ -199,10 +231,17 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
             const label = manifest.name.padEnd(nameWidth);
             const src = chalk.gray(`[${manifest.source}]`);
             if (installed) {
-                console.log(`  ${chalk.green('ready')}  ${label}  ${src}  ${chalk.gray(manifest.description || '')}`);
+                const prefix = `  ${chalk.green('ready')}  ${label}  ${src}`;
+                const desc = manifest.description
+                    ? `  ${truncateToWidth(collapseWhitespace(manifest.description), Math.max(1, terminalWidth() - stringWidth(prefix) - 2))}`
+                    : '';
+                console.log(prefix + chalk.gray(desc));
             }
             else {
-                console.log(`  ${chalk.red('miss ')}  ${label}  ${src}  ${chalk.gray(`not installed — run \`agents cli install ${manifest.name}\``)}`);
+                const prefix = `  ${chalk.red('miss ')}  ${label}  ${src}`;
+                const msg = `not installed — run \`agents cli install ${manifest.name}\``;
+                const budget = Math.max(1, terminalWidth() - stringWidth(prefix) - 2);
+                console.log(prefix + chalk.gray(`  ${truncateToWidth(msg, budget)}`));
             }
         }
     }
@@ -357,8 +396,12 @@ function renderKindSection(kind, rows, layers, options) {
     }
     for (const r of visible) {
         const src = sourceLabel(r, layers);
-        const detail = r.detail ? chalk.gray(`  ${r.detail}`) : '';
-        console.log(`    ${statusLabel(r.status)}  ${r.name.padEnd(28)} ${src}${detail}`);
+        const name = padToWidth(truncateToWidth(r.name, 28), 28);
+        const prefix = `    ${statusLabel(r.status)}  ${name} ${src}`;
+        const detail = r.detail
+            ? chalk.gray(`  ${truncateToWidth(collapseWhitespace(r.detail), Math.max(1, terminalWidth() - stringWidth(prefix) - 2))}`)
+            : '';
+        console.log(prefix + detail);
         if (options.showDiff && r.status === 'diff' && r.sourcePath && r.homePath) {
             const expected = readExpectedForDiff(kind, r);
             const actual = safeRead(r.homePath);
@@ -395,8 +438,10 @@ function readExpectedForDiff(kind, row) {
 function renderTargetText(report, options) {
     const label = `${AGENT_NAMES[report.agent] || report.agent}@${report.version}`;
     console.log(chalk.bold(label));
-    console.log(chalk.gray(`  home: ${report.home}`));
-    console.log(chalk.gray(`  cwd:  ${report.cwd}`));
+    const homePrefix = '  home: ';
+    const cwdPrefix = '  cwd:  ';
+    console.log(chalk.gray(homePrefix + truncateToWidth(report.home, Math.max(1, terminalWidth() - stringWidth(homePrefix)))));
+    console.log(chalk.gray(cwdPrefix + truncateToWidth(report.cwd, Math.max(1, terminalWidth() - stringWidth(cwdPrefix)))));
     const layerStr = [
         report.layers.project ? `project=${report.layers.project}` : null,
         `user=${report.layers.user}`,
@@ -405,7 +450,7 @@ function renderTargetText(report, options) {
             ? `extras=[${report.layers.extras.map((e) => e.alias).join(',')}]`
             : null,
     ].filter(Boolean).join(' ');
-    console.log(chalk.gray(`  layers: ${layerStr}`));
+    printWrappedLine('  layers: ', layerStr);
     // Staleness manifest verdict — single-line summary from the staleness
     // library, sitting alongside the detailed per-resource diff below.
     const manifest = loadManifest(report.agent, report.version);
@@ -446,7 +491,7 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents doctor ${report.agent}@${report.version} --fix\` to heal, or \`agents prune cleanup\` to drop extras.`));
+        printWrappedLine('  ', `Run \`agents doctor ${report.agent}@${report.version} --fix\` to heal, or \`agents prune cleanup\` to drop extras.`);
     }
 }
 // ─── fix / heal mode ───────────────────────────────────────────────────────────

package/dist/commands/events.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `agents events` — read the structured audit/event log.
+ *
+ * The event log (`~/.agents/.cache/logs/events-YYYY-MM-DD.jsonl`) records every
+ * `agents <module> <cmd>` invocation plus richer typed events (secrets access,
+ * version installs, ...), each stamped with who ran it and from where (OS user,
+ * local vs SSH, remote client IP). This command reads it back — the audit trail
+ * for "who accessed a secret / created a team / started an agent, and from which
+ * host?".
+ *
+ * Filter by `--module` (top-level group, e.g. teams), `--command` (path prefix,
+ * e.g. "teams create"), `--event` (typed event), `--agent`, and `--since`.
+ * `--follow` tails today's log live.
+ */
+import type { Command } from 'commander';
+export declare function registerEventsCommand(program: Command): void;