@phnx-labs/agents-cli 1.20.34 → 1.20.35

package/dist/commands/events.js

@@ -0,0 +1,173 @@
+/**
+ * `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 chalk from 'chalk';
+import * as fs from 'fs';
+import { query, LOGS_PATH } from '../lib/events.js';
+/** Parse `--since`: relative offsets (30s/5m/2h/7d/4w) or an ISO/absolute date. */
+function parseSince(s) {
+    const m = s.match(/^(\d+)([smhdw])$/);
+    if (m) {
+        const n = parseInt(m[1], 10);
+        const unitMs = {
+            s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000,
+        };
+        return new Date(Date.now() - n * unitMs[m[2]]);
+    }
+    const ms = Date.parse(s);
+    if (isNaN(ms))
+        throw new Error(`Invalid --since value: ${s} (use e.g. 2h, 7d, or an ISO date)`);
+    return new Date(ms);
+}
+/** How the run reached this host — 'local' or 'ssh 203.0.113.7'. */
+function originLabel(r) {
+    if (r.transport === 'ssh') {
+        return chalk.yellow(`ssh${r.sshClientIp ? ' ' + r.sshClientIp : ''}`);
+    }
+    return chalk.gray('local');
+}
+/** The most useful one-line detail for a record, by event family. */
+function detailFor(r) {
+    if (r.command)
+        return r.command;
+    const bits = [];
+    if (typeof r.team === 'string')
+        bits.push(`team=${r.team}`);
+    if (typeof r.bundle === 'string')
+        bits.push(`bundle=${r.bundle}`);
+    if (typeof r.skill === 'string')
+        bits.push(`skill=${r.skill}`);
+    if (typeof r.version === 'string')
+        bits.push(`v=${r.version}`);
+    if (typeof r.profile === 'string')
+        bits.push(`profile=${r.profile}`);
+    if (typeof r.error === 'string')
+        bits.push(chalk.red(r.error));
+    return bits.join(' ');
+}
+function renderRow(r) {
+    const time = chalk.gray(r.ts.slice(0, 19).replace('T', ' '));
+    const user = `${r.osUser ?? '?'}@${r.hostname}`;
+    const ev = r.event.startsWith('error') ? chalk.red(r.event) : chalk.cyan(r.event);
+    const agent = r.agent ? chalk.gray(` ${r.agent}`) : '';
+    return `${time}  ${originLabel(r).padEnd(24)} ${user.padEnd(22)} ${ev.padEnd(26)}${agent}  ${detailFor(r)}`;
+}
+export function registerEventsCommand(program) {
+    program
+        .command('events')
+        .description('Read the structured audit/event log (who ran what, from where)')
+        .option('--module <name>', 'Only events from this command group (e.g. teams, secrets)')
+        .option('--command <path>', 'Only this command path — prefix match (e.g. "teams create")')
+        .option('--event <type>', 'Only this typed event (repeatable, e.g. secrets.get)', collect, [])
+        .option('--agent <name>', 'Only events tagged with this agent')
+        .option('--since <time>', 'Only events newer than this (e.g. 2h, 7d, or ISO date)')
+        .option('--limit <n>', 'Max records to show (default 50)', '50')
+        .option('--json', 'Output raw records as JSON')
+        .option('-f, --follow', "Tail today's log live")
+        .addHelpText('after', `
+Examples:
+  agents events                          Recent activity across everything
+  agents events --module teams           Team lifecycle (create / add / disband)
+  agents events --module secrets         Every secret accessed or revealed
+  agents events --command "teams create" Just team creations
+  agents events --event secrets.get --since 7d --json
+  agents events -f                       Live tail`)
+        .action(async (options) => {
+        if (options.follow) {
+            await followLog();
+            return;
+        }
+        const limit = Math.max(1, parseInt(options.limit ?? '50', 10) || 50);
+        let startDate;
+        try {
+            startDate = options.since ? parseSince(options.since) : undefined;
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(2);
+        }
+        const records = query({
+            startDate,
+            eventTypes: options.event && options.event.length ? options.event : undefined,
+            agent: options.agent,
+            command: options.command,
+            module: options.module,
+            limit,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(records, null, 2));
+            return;
+        }
+        if (records.length === 0) {
+            console.log(chalk.gray('No matching events.'));
+            return;
+        }
+        // query() returns newest-first; print oldest-first so a tail reads naturally.
+        for (const r of records.slice().reverse())
+            console.log(renderRow(r));
+        console.log(chalk.gray(`\n${records.length} event(s). Log: ${LOGS_PATH}`));
+    });
+}
+/** commander repeatable-option collector. */
+function collect(value, previous) {
+    return previous.concat([value]);
+}
+/** Tail today's event file, printing new lines as they land. */
+async function followLog() {
+    const today = new Date();
+    const file = `${LOGS_PATH}/events-${today.getFullYear()}-${String(today.getMonth() + 1).padStart(2, '0')}-${String(today.getDate()).padStart(2, '0')}.jsonl`;
+    let offset = 0;
+    try {
+        offset = fs.statSync(file).size;
+    }
+    catch {
+        // File may not exist yet — start at 0 and pick it up on first write.
+    }
+    console.log(chalk.gray(`Tailing ${file} — Ctrl-C to stop`));
+    const drain = () => {
+        let size = 0;
+        try {
+            size = fs.statSync(file).size;
+        }
+        catch {
+            return;
+        }
+        if (size <= offset) {
+            if (size < offset)
+                offset = 0; // rotated/truncated
+            return;
+        }
+        const fd = fs.openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            offset = size;
+            for (const line of buf.toString('utf-8').split('\n').filter(Boolean)) {
+                try {
+                    console.log(renderRow(JSON.parse(line)));
+                }
+                catch {
+                    // Skip malformed lines.
+                }
+            }
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    };
+    // Poll — simpler and more portable than fs.watch across platforms/editors.
+    await new Promise(() => {
+        setInterval(drain, 500);
+    });
+}

package/dist/commands/exec.js

@@ -294,7 +294,12 @@ export function registerRunCommand(program) {
                     console.log(chalk.green(`Dispatched to ${host.name}.`) + chalk.gray(' Track: agents hosts ps · Follow: agents hosts logs <id> -f'));
                     process.exit(0);
                 }
-                process.exit(exitCode === undefined || exitCode === -1 ? 1 : exitCode);
+                // -1 = the follow window closed but the run continues on the host (the
+                // reattach hint is already printed). That's a detach, not a failure —
+                // exit 0. Any real remote code passes through.
+                if (exitCode === -1)
+                    process.exit(0);
+                process.exit(exitCode ?? 1);
             }
             catch (err) {
                 console.error(chalk.red(err.message));

package/dist/commands/hosts.js

@@ -7,15 +7,16 @@
  * hosts. Dispatch itself is `agents run --host <name>` (see commands/exec.ts).
  */
 import chalk from 'chalk';
+import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
 import { checkbox, confirm } from '@inquirer/prompts';
 import { assertValidSshTarget } from '../lib/ssh-exec.js';
 import { getProvider, listAllHosts, resolveHost } from '../lib/hosts/registry.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { listSshConfigHosts, listKnownHosts, isSshConfigHost } from '../lib/hosts/ssh-config.js';
 import { probeHost, remoteAgentsVersion, bootstrapAgentsCli, localCliVersion, } from '../lib/hosts/ready.js';
-import { listTasks, loadTask, localLogPath } from '../lib/hosts/tasks.js';
-import { followHostTask } from '../lib/hosts/progress.js';
-import * as fs from 'fs';
+import { listTasks } from '../lib/hosts/tasks.js';
+import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
+import { showHostTaskLog } from '../lib/hosts/logs.js';
 /** Parse `user@host` or `host` into its pieces. */
 function parseTarget(target) {
     const at = target.indexOf('@');
@@ -23,9 +24,12 @@ function parseTarget(target) {
         return { address: target };
     return { user: target.slice(0, at), address: target.slice(at + 1) };
 }
-/** Bootstrap/verify agents-cli on a freshly-enrolled host (best-effort, prompts). */
-async function maybeBootstrap(target, hostName) {
-    const probe = probeHost(target);
+/**
+ * Bootstrap/verify agents-cli on a freshly-enrolled host (best-effort, prompts).
+ * Callers that just probed the host pass the result through to avoid a second,
+ * redundant `uname` round-trip; otherwise we probe here.
+ */
+async function maybeBootstrap(target, hostName, probe = probeHost(target)) {
     if (!probe.reachable) {
         console.log(chalk.yellow(`  Not reachable over SSH yet — skipping bootstrap. Fix key auth, then: agents hosts check ${hostName}`));
         return;
@@ -75,7 +79,7 @@ async function doAdd(name, target, opts) {
             await registerHost({ name: c, provider: 'local', source, ...(source === 'inline' ? { address: c } : {}), os: probe.os, caps: opts.cap });
             console.log(chalk.green(`Enrolled ${c}`) + chalk.gray(` (${source}${probe.os ? `, ${probe.os}` : ''})`));
             if (opts.enroll !== false)
-                await maybeBootstrap(c, c);
+                await maybeBootstrap(c, c, probe);
         }
         return;
     }
@@ -107,7 +111,7 @@ async function doAdd(name, target, opts) {
     await registerHost(spec);
     console.log(chalk.green(`Enrolled ${name}`) + chalk.gray(` (${spec.source}${spec.os ? `, ${spec.os}` : ''}${spec.caps?.length ? `, caps: ${spec.caps.join(',')}` : ''})`));
     if (opts.enroll !== false)
-        await maybeBootstrap(sshTarget, name);
+        await maybeBootstrap(sshTarget, name, probe);
 }
 async function doList(json) {
     const hosts = await listAllHosts();
@@ -122,8 +126,11 @@ async function doList(json) {
     console.log(chalk.bold('NAME').padEnd(20) + chalk.bold('SOURCE').padEnd(13) + chalk.bold('TARGET').padEnd(28) + chalk.bold('CAPS'));
     for (const h of hosts) {
         const tgt = h.source === 'ssh-config' ? chalk.gray('(ssh-config)') : `${h.user ? h.user + '@' : ''}${h.address ?? ''}`;
+        // Cap TARGET at its column so a long user@host can't shove CAPS out of alignment.
+        const tgtW = stringWidth(tgt);
+        const tgtCol = tgtW > 28 ? truncateToWidth(tgt, 28) : tgt + ' '.repeat(28 - tgtW);
         const mark = h.enrolled ? '' : chalk.gray(' ·available');
-        console.log(h.name.padEnd(20) + h.source.padEnd(13) + tgt.padEnd(28) + (h.caps?.join(',') ?? '') + mark);
+        console.log(h.name.padEnd(20) + h.source.padEnd(13) + tgtCol + (h.caps?.join(',') ?? '') + mark);
     }
 }
 async function doCheck(name) {
@@ -155,7 +162,10 @@ async function doRemove(name) {
     console.log(chalk.green(`Removed ${name}`));
 }
 async function doPs(json) {
-    const tasks = listTasks();
+    // Heal any 'running' record whose local follower died (dropped connection,
+    // laptop sleep) against the remote `.exit` before listing, so `ps` never shows
+    // a finished run stuck at 'running'.
+    const tasks = reconcileRunningTasks(listTasks());
     if (json) {
         console.log(JSON.stringify(tasks, null, 2));
         return;
@@ -164,30 +174,24 @@ async function doPs(json) {
         console.log(chalk.gray('No host tasks yet. Dispatch one: agents run <agent> "<task>" --host <name>'));
         return;
     }
+    const cols = terminalWidth();
     console.log(chalk.bold('ID').padEnd(11) + chalk.bold('HOST').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
     for (const t of tasks) {
         const status = t.status === 'completed' ? chalk.green(t.status) : t.status === 'failed' ? chalk.red(t.status) : chalk.yellow(t.status);
-        console.log(t.id.padEnd(11) + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + t.prompt.slice(0, 50));
+        // Prompt fills the remaining width instead of a fixed 50-char byte slice (98-char rows).
+        const promptCol = truncateToWidth(t.prompt, Math.max(12, cols - (11 + 16 + 10 + 11)));
+        console.log(t.id.padEnd(11) + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
     }
 }
 async function doLogs(id, follow) {
-    const task = loadTask(id);
-    if (!task) {
+    const res = await showHostTaskLog(id, follow);
+    if (!res.found) {
         console.log(chalk.red(`Unknown task "${id}".`));
         process.exitCode = 1;
         return;
     }
-    if (follow && task.status === 'running') {
-        const code = await followHostTask(task.target, { remoteLog: task.remoteLog, remoteExit: task.remoteExit, taskId: id, echo: true });
-        process.exitCode = code === -1 ? 1 : code;
-        return;
-    }
-    try {
-        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
-    }
-    catch {
-        console.log(chalk.gray('(no local log captured for this task)'));
-    }
+    if (res.exitCode !== undefined)
+        process.exitCode = res.exitCode;
 }
 /** Register the `agents hosts` command tree. */
 export function registerHostsCommand(program) {

package/dist/commands/inspect.d.ts

@@ -18,6 +18,8 @@ import { type PluginResourceGroup } from '../lib/plugins.js';
 /** Resource kinds the inspect command can drill into. */
 declare const DRILLABLE_KINDS: readonly ["commands", "skills", "hooks", "mcp", "rules", "plugins", "workflows", "subagents"];
 type DrillableKind = typeof DRILLABLE_KINDS[number];
+/** Wrap a separator-joined value list under `prefix`, preserving a hanging indent. */
+export declare function wrapJoined(prefix: string, items: string[], sep: string, width: number): string[];
 interface ResourceItem {
     name: string;
     source: string;

package/dist/commands/inspect.js

@@ -31,6 +31,7 @@ import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
 import { countSessionsInScope } from '../lib/session/discover.js';
 import { damerauLevenshtein } from '../lib/fuzzy.js';
+import { terminalWidth, truncateToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
 /** Resource kinds the inspect command can drill into. */
 const DRILLABLE_KINDS = [
     'commands',
@@ -68,6 +69,44 @@ const SINGULAR_DRILL_ALIASES = {
 const CAPABILITY_NAMES = [
     'hooks', 'mcp', 'skills', 'commands', 'subagents', 'plugins', 'workflows', 'rules', 'allowlist',
 ];
+/** Wrap a separator-joined value list under `prefix`, preserving a hanging indent. */
+export function wrapJoined(prefix, items, sep, width) {
+    if (items.length === 0)
+        return [];
+    const continuation = ' '.repeat(stringWidth(prefix));
+    const fitItem = (item, linePrefix) => {
+        const room = Math.max(1, width - stringWidth(linePrefix));
+        return stringWidth(item) > room ? truncateToWidth(item, room) : item;
+    };
+    const lines = [];
+    let linePrefix = prefix;
+    let line = prefix;
+    let hasItem = false;
+    for (const raw of items) {
+        const item = fitItem(raw, linePrefix);
+        const candidate = hasItem ? `${line}${sep}${item}` : `${line}${item}`;
+        if (hasItem && stringWidth(candidate) > width) {
+            lines.push(line);
+            linePrefix = continuation;
+            line = continuation + fitItem(raw, linePrefix);
+            hasItem = true;
+        }
+        else {
+            line = candidate;
+            hasItem = true;
+        }
+    }
+    if (hasItem)
+        lines.push(line);
+    return lines;
+}
+function printWrappedJoined(prefix, items, sep) {
+    for (const line of wrapJoined(prefix, items, sep, terminalWidth()))
+        console.log(line);
+}
+function truncateValueForPrefix(prefix, value) {
+    return truncateToWidth(stripAnsi(value), Math.max(1, terminalWidth() - stringWidth(prefix)));
+}
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
     const cmd = addHostOption(program.command('inspect <target>'))
@@ -425,7 +464,10 @@ function renderRepoSummary(repo, options) {
         console.log(`  ${'git'.padEnd(10)} ${git.branch}${dirty}${url}`);
         if (git.lastCommit) {
             const rel = git.lastCommit.relative ? `  ${chalk.gray(`(${git.lastCommit.relative})`)}` : '';
-            sub('last', `${chalk.cyan(git.lastCommit.sha)}  ${truncate(git.lastCommit.subject, 60)}${rel}`);
+            const prefix = `  ${''.padEnd(10)} ${chalk.gray('last'.padEnd(8))} `;
+            const sha = chalk.cyan(git.lastCommit.sha);
+            const subjectWidth = Math.max(8, terminalWidth() - stringWidth(prefix) - stringWidth(sha) - 2 - stringWidth(rel));
+            console.log(`${prefix}${sha}  ${truncateToWidth(git.lastCommit.subject, subjectWidth)}${rel}`);
         }
         if (git.ahead !== null && git.behind !== null && (git.ahead > 0 || git.behind > 0)) {
             sub('sync', `ahead ${git.ahead} ${chalk.gray('·')} behind ${git.behind}`);
@@ -440,10 +482,12 @@ function renderRepoSummary(repo, options) {
         console.log(`  ${'manifests'.padEnd(10)} ${manifests.join(', ')}`);
         if (manifest) {
             if (manifest.versions.length > 0) {
-                sub('versions', manifest.versions.map(v => `${v.agent} ${chalk.cyan(v.version)}`).join(chalk.gray(' · ')));
+                const prefix = `  ${''.padEnd(10)} ${chalk.gray('versions'.padEnd(8))} `;
+                printWrappedJoined(prefix, manifest.versions.map(v => `${v.agent} ${chalk.cyan(v.version)}`), chalk.gray(' · '));
             }
             if (manifest.strategies.length > 0) {
-                sub('run', manifest.strategies.map(s => `${s.agent}:${s.strategy}`).join(chalk.gray(' · ')));
+                const prefix = `  ${''.padEnd(10)} ${chalk.gray('run'.padEnd(8))} `;
+                printWrappedJoined(prefix, manifest.strategies.map(s => `${s.agent}:${s.strategy}`), chalk.gray(' · '));
             }
         }
     }
@@ -551,8 +595,10 @@ async function renderSummary(agent, version, versionHome, options) {
         ['alias', aliasPath],
         ['strategy', strategy],
     ];
-    for (const [k, v] of rows)
-        console.log(`  ${k.padEnd(10)} ${v}`);
+    for (const [k, v] of rows) {
+        const prefix = `  ${k.padEnd(10)} `;
+        console.log(prefix + truncateValueForPrefix(prefix, v));
+    }
     console.log('\n' + chalk.bold('Capabilities'));
     for (const cap of CAPABILITY_NAMES) {
         const res = capabilities[cap];
@@ -603,7 +649,8 @@ function renderItemList(header, jsonHead, kind, items, options) {
         const tag = chalk.gray(`[${item.source}]`.padEnd(10));
         console.log(`  ${tag} ${termLink(chalk.cyan(item.name), item.linkTarget)}`);
         if (item.description) {
-            console.log(`             ${chalk.gray(truncate(item.description, 90))}`);
+            const prefix = '             ';
+            console.log(prefix + chalk.gray(truncateToWidth(item.description, Math.max(1, terminalWidth() - stringWidth(prefix)))));
         }
         if (item.groups)
             printGroupRows(item.groups);
@@ -1171,7 +1218,7 @@ function readFirstProseLine(p) {
 }
 // ─── OSC-8 + path helpers ────────────────────────────────────────────────────
 function termLink(text, filePath) {
-    if (!filePath)
+    if (!filePath || !process.stdout.isTTY)
         return text;
     const url = `file://${filePath}`;
     return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;

package/dist/commands/logs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `agents logs` — unified, discoverable run-log viewer.
+ *
+ * Resolves a run across two substrates and shows (or `-f` follows) its log:
+ *  - host-dispatch tasks (`agents run --host`) → combined-stdout log, offset-tailed
+ *  - sessions (the local index) → transcript, tailed via the sessions tailer
+ *
+ * `[id]`/`--session` load directly (host task tried first, then session). With no
+ * id, `--host`/`--agent`/`--version` filter a merged candidate list; one match is
+ * shown, several open the fuzzy picker (or, non-TTY, print the list).
+ *
+ * Additive: `agents hosts logs` and `agents sessions tail` are unchanged and share
+ * the same underlying helpers (showHostTaskLog / streamSessionTail).
+ */
+import type { Command } from 'commander';
+/** Register the top-level `agents logs` command. */
+export declare function registerLogsCommand(program: Command): void;

package/dist/commands/logs.js

@@ -0,0 +1,139 @@
+/**
+ * `agents logs` — unified, discoverable run-log viewer.
+ *
+ * Resolves a run across two substrates and shows (or `-f` follows) its log:
+ *  - host-dispatch tasks (`agents run --host`) → combined-stdout log, offset-tailed
+ *  - sessions (the local index) → transcript, tailed via the sessions tailer
+ *
+ * `[id]`/`--session` load directly (host task tried first, then session). With no
+ * id, `--host`/`--agent`/`--version` filter a merged candidate list; one match is
+ * shown, several open the fuzzy picker (or, non-TTY, print the list).
+ *
+ * Additive: `agents hosts logs` and `agents sessions tail` are unchanged and share
+ * the same underlying helpers (showHostTaskLog / streamSessionTail).
+ */
+import chalk from 'chalk';
+import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+import { parseAgentFilter, renderSessionLog } from './sessions.js';
+import { streamSessionTail, isTailable } from './sessions-tail.js';
+import { showHostTaskLog } from '../lib/hosts/logs.js';
+import { listTasks } from '../lib/hosts/tasks.js';
+import { itemPicker } from '../lib/picker.js';
+/** Compact one-line label used by both the picker and the non-TTY list. */
+function candidateLabel(c) {
+    if (c.kind === 'task') {
+        const t = c.task;
+        const status = t.status === 'completed' ? chalk.green(t.status)
+            : t.status === 'failed' ? chalk.red(t.status)
+                : chalk.yellow(t.status);
+        return `${chalk.gray('task')} ${t.id.slice(0, 8).padEnd(9)} ${t.host.padEnd(14)} ${t.agent.padEnd(8)} ${status}  ${t.prompt.slice(0, 40)}`;
+    }
+    const s = c.session;
+    const ver = s.version ? chalk.gray(`@${s.version}`) : '';
+    const title = s.label || s.topic || '';
+    return `${chalk.gray('sess')} ${s.shortId.padEnd(9)} ${(s.agent + ver).padEnd(14)} ${chalk.gray(s.timestamp.slice(0, 16))}  ${title.slice(0, 40)}`;
+}
+/** Show a resolved session — follow (tail) or render its transcript. */
+async function showSession(session, follow) {
+    if (follow) {
+        if (!isTailable(session.agent)) {
+            console.error(chalk.red(`Tailing is supported for claude and codex sessions only (got ${session.agent}).`));
+            process.exit(2);
+        }
+        await streamSessionTail(session, {});
+        return;
+    }
+    await renderSessionLog(session);
+}
+async function showCandidate(c, follow) {
+    if (c.kind === 'task') {
+        const res = await showHostTaskLog(c.task.id, follow);
+        if (res.exitCode !== undefined)
+            process.exitCode = res.exitCode;
+        return;
+    }
+    await showSession(c.session, follow);
+}
+/** Resolve an explicit id/--session: host task first, then a session. */
+async function showById(id, follow) {
+    const hostRes = await showHostTaskLog(id, follow);
+    if (hostRes.found) {
+        if (hostRes.exitCode !== undefined)
+            process.exitCode = hostRes.exitCode;
+        return;
+    }
+    const sessions = await discoverSessions({ all: true, limit: 5000 });
+    const matches = resolveSessionById(sessions, id);
+    if (matches.length === 0) {
+        console.error(chalk.red(`No run or session found matching "${id}".`));
+        process.exit(1);
+    }
+    await showSession(matches[0], follow);
+}
+async function runLogs(id, opts) {
+    const follow = !!opts.follow;
+    const directId = opts.session ?? id;
+    if (directId) {
+        await showById(directId, follow);
+        return;
+    }
+    const { agent, version } = parseAgentFilter(opts.agent);
+    const wantVersion = opts.version ?? version;
+    // Host tasks carry no session-index metadata; sessions carry no host tag.
+    // So --host scopes to dispatched tasks, and --version to sessions.
+    const candidates = [];
+    let tasks = listTasks();
+    if (opts.host)
+        tasks = tasks.filter((t) => t.host === opts.host);
+    if (agent)
+        tasks = tasks.filter((t) => t.agent === agent);
+    for (const t of tasks)
+        candidates.push({ kind: 'task', task: t });
+    if (!opts.host) {
+        const sessions = await discoverSessions({ agent, version: wantVersion, limit: 50 });
+        for (const s of sessions)
+            candidates.push({ kind: 'session', session: s });
+    }
+    if (candidates.length === 0) {
+        console.error(chalk.yellow('No matching runs. Dispatch one: agents run <agent> "<task>" [--host <name>]'));
+        process.exit(1);
+    }
+    if (candidates.length === 1) {
+        await showCandidate(candidates[0], follow);
+        return;
+    }
+    // Multiple sessions matched → picker if interactive, else a list to pick from.
+    if (!process.stdin.isTTY) {
+        console.error(chalk.yellow(`${candidates.length} runs match. Pass an id or --session <id>:`));
+        for (const c of candidates.slice(0, 30))
+            console.error('  ' + candidateLabel(c));
+        process.exit(1);
+    }
+    const picked = await itemPicker({
+        message: 'Select a run to view its log:',
+        items: candidates,
+        filter: (query) => {
+            const q = query.trim().toLowerCase();
+            if (!q)
+                return candidates;
+            return candidates.filter((c) => candidateLabel(c).toLowerCase().includes(q));
+        },
+        labelFor: (c) => candidateLabel(c),
+        shortIdFor: (c) => (c.kind === 'task' ? c.task.id : c.session.shortId),
+    });
+    if (!picked)
+        return;
+    await showCandidate(picked.item, follow);
+}
+/** Register the top-level `agents logs` command. */
+export function registerLogsCommand(program) {
+    program
+        .command('logs [id]')
+        .description('Show a run’s log — a host-dispatch task or a session. -f to follow a live one.')
+        .option('--host <name>', 'Scope to runs dispatched to a host')
+        .option('-a, --agent <agent>', 'Filter by agent (e.g. claude, codex@0.116.0)')
+        .option('--version <version>', 'Filter by agent version')
+        .option('--session <id>', 'Select a session/run by id (same as the positional id)')
+        .option('-f, --follow', 'Follow live output')
+        .action((id, opts) => runLogs(id, opts));
+}

package/dist/commands/models.d.ts

@@ -8,3 +8,6 @@
 import type { Command } from 'commander';
 /** Register the hidden `agents models` command. */
 export declare function registerModelsCommand(program: Command): void;
+export declare function formatModelSourceLine(kind: string, sourcePath: string, width?: number): string;
+export declare function formatModelAliasLines(parts: string[], width?: number): string[];
+export declare function formatModelSummaryLine(star: string, id: string, displayName?: string, alias?: string, width?: number): string;

package/dist/commands/models.js

@@ -11,6 +11,8 @@ import { homeDir } from '../lib/platform/index.js';
 import { resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
 import { getModelCatalog, locateModelSource } from '../lib/models.js';
+import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/width.js';
+import { wrapJoined } from './inspect.js';
 const MODEL_CAPABLE_AGENTS = ['claude', 'codex', 'gemini', 'opencode', 'cursor', 'openclaw', 'antigravity', 'kimi'];
 /**
  * Agents that don't necessarily install under ~/.agents/versions (cursor ships
@@ -131,21 +133,19 @@ function printCatalog(agent, version, isDefault, options) {
         console.log(chalk.yellow(`  No models extracted from ${src.kind} at ${src.path}.`));
         return;
     }
-    console.log(chalk.gray(`  source: ${src.kind} (${shortPath(src.path)})`));
+    console.log(chalk.gray(formatModelSourceLine(src.kind, shortPath(src.path))));
     if (Object.keys(catalog.aliases).length > 0) {
         const parts = Object.entries(catalog.aliases).map(([alias, id]) => `${chalk.cyan(alias)}=${id}`);
-        console.log(chalk.gray(`  aliases: `) + parts.join(', '));
+        for (const line of formatModelAliasLines(parts))
+            console.log(line);
     }
     console.log();
     for (const model of catalog.models) {
         const star = model.isDefault ? chalk.green('*') : ' ';
-        const display = model.displayName && model.displayName !== model.id
-            ? chalk.gray(` (${model.displayName})`)
-            : '';
-        const aliasTag = model.alias ? chalk.cyan(` [${model.alias}]`) : '';
-        console.log(`  ${star} ${chalk.bold(model.id)}${display}${aliasTag}`);
+        console.log(formatModelSummaryLine(star, model.id, model.displayName, model.alias));
         if (model.description) {
-            console.log(chalk.gray(`      ${model.description}`));
+            const descPrefix = '      ';
+            console.log(chalk.gray(descPrefix + truncateToWidth(model.description, Math.max(1, terminalWidth() - stringWidth(descPrefix)))));
         }
         if (options.cloud && model.perCloud) {
             const c = model.perCloud;
@@ -175,3 +175,22 @@ function printCatalog(agent, version, isDefault, options) {
 function shortPath(p) {
     return p.replace(homeDir(), '~');
 }
+export function formatModelSourceLine(kind, sourcePath, width = terminalWidth()) {
+    const prefix = `  source: ${kind} (`;
+    const suffix = ')';
+    const room = Math.max(1, width - stringWidth(prefix) - stringWidth(suffix));
+    return prefix + truncateToWidth(sourcePath, room) + suffix;
+}
+export function formatModelAliasLines(parts, width = terminalWidth()) {
+    return wrapJoined(chalk.gray('  aliases: '), parts, ', ', width);
+}
+export function formatModelSummaryLine(star, id, displayName, alias, width = terminalWidth()) {
+    const display = displayName && displayName !== id ? ` (${displayName})` : '';
+    const aliasTag = alias ? ` [${alias}]` : '';
+    const prefix = `  ${star} `;
+    const plain = `${id}${display}${aliasTag}`;
+    if (stringWidth(plain) > Math.max(1, width - stringWidth(prefix))) {
+        return prefix + truncateToWidth(plain, Math.max(1, width - stringWidth(prefix)));
+    }
+    return prefix + chalk.bold(id) + chalk.gray(display) + chalk.cyan(aliasTag);
+}