@phnx-labs/agents-cli 1.20.4 → 1.20.6

package/dist/commands/teams.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import { AgentManager, checkAllClis, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
-import { handleSpawn, handleStatus, handleStop, handleTasks, } from '../lib/teams/api.js';
+import { handleSpawn, handleStatus, handleStop, handleTasks, toTaskStatusSummary, } from '../lib/teams/api.js';
 import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
 import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
@@ -24,6 +24,7 @@ const AGENT_NAMES = {
     opencode: 'OpenCode',
     grok: 'Grok',
     antigravity: 'Antigravity',
+    kimi: 'Kimi',
 };
 const VALID_AGENTS = Object.keys(AGENT_NAMES);
 // 'full' kept as historical alias for 'skip'; normalized to 'skip' downstream.
@@ -381,6 +382,55 @@ async function resolveTeammateSessions(agents) {
     }
     return map;
 }
+// Default compact renderer — one block per teammate, optimized for the
+// orchestrator scanning "what state, what did you touch, what did you say
+// last." Caller passes the projected AgentStatusSummary; for the full
+// verbose layout use printAgentDetail above.
+function printAgentSummary(s) {
+    const label = statusColor(s.status)(s.status.toUpperCase());
+    const handle = s.name ?? shortId(s.agent_id);
+    const ident = s.name ? chalk.gray(`(${shortId(s.agent_id)})`) : '';
+    const duration = s.duration ? `${chalk.gray(' · ')}${chalk.white(s.duration)}` : '';
+    const errBadge = s.has_errors ? chalk.red(' !') : '';
+    const tools = chalk.gray(` · ${s.tool_count} tools`);
+    console.log(`  ${chalk.cyan(handle.padEnd(14))} ${ident.padEnd(11)} ${label}${duration}${tools}${errBadge}`);
+    // Files: counts + basenames. Read is count only.
+    const fileLines = [];
+    const renderCat = (label, cat) => {
+        if (cat.count === 0)
+            return;
+        const more = cat.count > cat.names.length ? ` +${cat.count - cat.names.length}` : '';
+        const names = cat.names.length ? ` ${cat.names.join(', ')}${more}` : '';
+        fileLines.push(`${label} ${cat.count}${names}`);
+    };
+    renderCat('modified', s.files.modified);
+    renderCat('created', s.files.created);
+    renderCat('deleted', s.files.deleted);
+    if (s.files.read.count > 0)
+        fileLines.push(`read ${s.files.read.count}`);
+    if (fileLines.length) {
+        console.log(`    ${chalk.gray('files   ')} ${fileLines.join(chalk.gray(' · '))}`);
+    }
+    // Last 3 bash commands.
+    const recentBash = s.bash_commands.slice(-3);
+    if (recentBash.length) {
+        console.log(`    ${chalk.gray('bash    ')}`);
+        for (const cmd of recentBash) {
+            console.log(`      ${chalk.gray('$')} ${truncate(cmd, 96)}`);
+        }
+    }
+    // Last messages — first non-empty line of each, truncated.
+    if (s.last_messages.length) {
+        console.log(`    ${chalk.gray('messages')}`);
+        for (const msg of s.last_messages) {
+            const firstLine = msg.split(/\r?\n/).find((l) => l.trim()) || '';
+            if (firstLine)
+                console.log(`      ${chalk.gray('>')} ${truncate(firstLine, 96)}`);
+        }
+    }
+    if (s.pr_url)
+        console.log(`    ${chalk.gray('PR      ')} ${chalk.cyan(s.pr_url)}`);
+}
 // Render a team's status in the same format the `status` subcommand uses, so
 // the interactive picker's Enter action drops the user into a familiar view.
 async function printTeamStatus(team, result) {
@@ -408,6 +458,36 @@ async function printTeamStatus(team, result) {
     console.log();
     console.log(chalk.gray(`cursor: ${result.cursor}`));
 }
+// Compact default renderer — no session-file dive, no per-teammate
+// 15-line preview. One block per teammate, suitable for the orchestrator
+// scanning what each agent did. Use `printTeamStatus` (above) for the
+// verbose/legacy layout.
+function printTeamSummary(team, result) {
+    const { summary, agents } = result;
+    console.log(chalk.bold(`Team ${chalk.cyan(team)}  `) +
+        chalk.gray(summary.pending > 0
+            ? `(${summary.pending} pending, ${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`
+            : `(${summary.running} working, ${summary.completed} done, ${summary.failed} failed, ${summary.stopped} stopped)`));
+    if (agents.length === 0) {
+        console.log(chalk.gray('  (no teammates yet — add one with `agents teams add`)'));
+    }
+    else {
+        const width = Math.min(process.stdout.columns || 80, 80);
+        const divider = chalk.gray('┈'.repeat(width));
+        for (let i = 0; i < agents.length; i++) {
+            console.log();
+            if (i > 0) {
+                console.log(divider);
+                console.log();
+            }
+            printAgentSummary(agents[i]);
+        }
+    }
+    console.log();
+    console.log(chalk.gray(`cursor: ${result.cursor}`));
+    console.log(chalk.gray('Full detail: agents teams status ' + team + ' --verbose'));
+    console.log(chalk.gray('Raw log:     agents teams logs --team ' + team + ' --teammate <name>'));
+}
 // Classify a team into a single bucket for --status filtering.
 //  - empty:   no teammates (created but nobody added yet)
 //  - waiting: only staged teammates — call `teams start` to kick them off
@@ -963,10 +1043,11 @@ export function registerTeamsCommands(program) {
     teams
         .command('status [team]')
         .aliases(['s', 'st', 'check'])
-        .description("Check in on a team: who's working, what files they touched, recent commands, last output. Pass --since for efficient delta polling.")
+        .description("Check in on a team: status, files touched, recent commands, last messages. Pass --verbose for the full per-teammate dump; --since for delta polling.")
         .option('-f, --filter <state>', 'Show only teammates in this state: running, completed, failed, stopped, or all (default: all)', 'all')
         .option('-s, --since <iso>', 'Cursor from a previous status call; only show updates after this timestamp (enables efficient polling)')
         .option('--agent-id <id>', 'Show only this one teammate (by UUID or UUID prefix)')
+        .option('-v, --verbose', 'Emit the full per-teammate detail (prompt, all file paths, all messages). Default is a compact summary.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         const filter = opts.filter;
@@ -983,8 +1064,15 @@ export function registerTeamsCommands(program) {
             const agents = opts.agentId
                 ? result.agents.filter((a) => a.agent_id.startsWith(opts.agentId))
                 : result.agents;
+            const filtered = { ...result, agents };
             if (isJsonMode(opts)) {
-                console.log(JSON.stringify({ ...result, agents }, null, 2));
+                // JSON output also respects --verbose. Default = compact summary
+                // shape; --verbose = full AgentStatusDetail. Same toggle covers
+                // both text and JSON so MCP-style consumers can opt into detail.
+                const payload = opts.verbose
+                    ? filtered
+                    : toTaskStatusSummary(filtered);
+                console.log(JSON.stringify(payload, null, 2));
                 return;
             }
             const exists = await teamExists(team);
@@ -992,7 +1080,12 @@ export function registerTeamsCommands(program) {
                 console.log(chalk.yellow(`No team called '${team}'. Create it with: agents teams create ${team}`));
                 return;
             }
-            await printTeamStatus(team, { ...result, agents });
+            if (opts.verbose) {
+                await printTeamStatus(team, filtered);
+            }
+            else {
+                printTeamSummary(team, toTaskStatusSummary(filtered));
+            }
         }
         catch (err) {
             die(`Could not check on team ${team}: ${err.message}`);
@@ -1307,14 +1400,19 @@ export function registerTeamsCommands(program) {
     teams
         .command('logs [teammate]')
         .alias('log')
-        .description("Read a teammate's raw log output. Accepts name, UUID, or UUID prefix.")
+        .description("Read a teammate's raw log output. Accepts positional name, --teammate <name>, UUID, or UUID prefix.")
         .option('-n, --tail <n>', 'Show only the last N lines instead of the full log')
         .option('--team <team>', 'Disambiguate when the same name appears in multiple teams')
+        .option('--teammate <name>', 'Teammate name (alias for the positional arg; useful for scripts)')
         .action(async (ref, opts) => {
         const base = await getAgentsDir();
-        // No teammate → picker in TTY, hard fail outside.
+        // Resolve teammate identity. Precedence:
+        //   1. positional `[teammate]` arg (back-compat, most common)
+        //   2. --teammate <name> flag (script-friendly alias)
+        //   3. interactive picker (TTY only)
+        const teammateRef = ref ?? opts.teammate;
         let agentId;
-        if (!ref) {
+        if (!teammateRef) {
             const mgr = mkManager();
             const picked = await pickTeammateOr(mgr, 'agents teams logs');
             if (!picked)
@@ -1322,13 +1420,13 @@ export function registerTeamsCommands(program) {
             agentId = picked.agentId;
         }
         else {
-            const resolved = await resolveTeammateAcrossTeams(base, ref, opts.team);
+            const resolved = await resolveTeammateAcrossTeams(base, teammateRef, opts.team);
             if (resolved.kind === 'none') {
-                die(`No notes on record for teammate '${ref}'`, 2);
+                die(`No notes on record for teammate '${teammateRef}'`, 2);
             }
             if (resolved.kind === 'ambiguous') {
                 const hints = resolved.candidates.map((c) => `${c.team}/${c.display}`).join(', ');
-                die(`'${ref}' matches multiple teammates: ${hints}.\n` +
+                die(`'${teammateRef}' matches multiple teammates: ${hints}.\n` +
                     `  Narrow it with --team <team>, or pass a UUID prefix.`, 2);
             }
             agentId = resolved.agentId;
@@ -1345,7 +1443,7 @@ export function registerTeamsCommands(program) {
             process.stdout.write(lines.slice(-n).join('\n'));
         }
         catch {
-            die(`No notes on record for teammate '${ref ?? agentId}' (looked in ${logPath})`, 2);
+            die(`No notes on record for teammate '${teammateRef ?? agentId}' (looked in ${logPath})`, 2);
         }
     });
     // doctor

package/dist/commands/tmux.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `agents tmux` — terminal multiplexer integration.
+ *
+ * Why this exists: the swarmify VS Code extension was hand-rolling tmux
+ * commands with brittle shell escaping (`extension/src/vscode/tmux.ts`).
+ * Lifting the orchestration into the CLI gives one source of truth that the
+ * extension, raw shells, `agents teams`, routines, and the Swarm MCP can all
+ * call into.
+ *
+ * Surface mirrors `agents pty`:
+ *   agents tmux check
+ *   agents tmux new <name>     [--cmd ...] [--cwd DIR] [--replace] [--attach-existing] [--source S]
+ *   agents tmux attach <name>
+ *   agents tmux list [--json]
+ *   agents tmux has <name>
+ *   agents tmux split <name> <h|v> [--cmd ...] [--cwd DIR]
+ *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
+ *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
+ *   agents tmux info <name>    [--json]
+ *   agents tmux kill <name>
+ *   agents tmux kill-all       [--yes]
+ */
+import type { Command } from 'commander';
+/** Register the `agents tmux` command tree. */
+export declare function registerTmuxCommands(program: Command): void;

package/dist/commands/tmux.js

@@ -0,0 +1,415 @@
+/**
+ * `agents tmux` — terminal multiplexer integration.
+ *
+ * Why this exists: the swarmify VS Code extension was hand-rolling tmux
+ * commands with brittle shell escaping (`extension/src/vscode/tmux.ts`).
+ * Lifting the orchestration into the CLI gives one source of truth that the
+ * extension, raw shells, `agents teams`, routines, and the Swarm MCP can all
+ * call into.
+ *
+ * Surface mirrors `agents pty`:
+ *   agents tmux check
+ *   agents tmux new <name>     [--cmd ...] [--cwd DIR] [--replace] [--attach-existing] [--source S]
+ *   agents tmux attach <name>
+ *   agents tmux list [--json]
+ *   agents tmux has <name>
+ *   agents tmux split <name> <h|v> [--cmd ...] [--cwd DIR]
+ *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
+ *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
+ *   agents tmux info <name>    [--json]
+ *   agents tmux kill <name>
+ *   agents tmux kill-all       [--yes]
+ */
+import chalk from 'chalk';
+import * as path from 'path';
+import { setHelpSections } from '../lib/help.js';
+import { assertTmuxAvailable, attachTmux, capturePane, createSession, getDefaultSocketPath, getTmuxVersion, hasSession, isTmuxInstalled, killAll, killSession, listSessions, readSessionMeta, sendKeys, splitPane, TmuxCommandError, TmuxSessionError, TmuxUnavailableError, } from '../lib/tmux/index.js';
+/** Register the `agents tmux` command tree. */
+export function registerTmuxCommands(program) {
+    const tmux = program
+        .command('tmux')
+        .description('Persistent terminal-multiplexer sessions for agents. Survive editor restarts, share with other tools.');
+    setHelpSections(tmux, {
+        examples: `
+      # Verify tmux is installed
+      agents tmux check
+
+      # Start a detached agent session
+      agents tmux new claude-debug --cmd "agents run claude" --cwd ~/code/myrepo
+
+      # Attach (replaces this shell with the tmux client)
+      agents tmux attach claude-debug
+
+      # Inspect remotely without attaching
+      agents tmux capture claude-debug --lines 200
+
+      # Send a slash command from a script
+      agents tmux send claude-debug "/clear"
+
+      # Clean up
+      agents tmux kill claude-debug
+    `,
+        notes: `
+      Storage:
+        Shared server socket: ~/.agents/.cache/helpers/tmux/server.sock
+        Per-session meta:     ~/.agents/.cache/helpers/tmux/<name>.json
+
+      Session names accept [A-Za-z0-9_-] up to 64 characters. tmux disallows
+      '.' and ':' in names since those address windows and panes.
+
+      Existing tmux sessions you started outside of agents-cli are NOT
+      visible here unless you point them at the same socket via --socket.
+    `,
+    });
+    // ─── check ──────────────────────────────────────────────────────────────────
+    const checkCmd = tmux
+        .command('check')
+        .description('Check whether tmux is installed and report its version.')
+        .option('--json', 'Output as JSON');
+    checkCmd.action((opts) => {
+        const installed = isTmuxInstalled();
+        const version = installed ? getTmuxVersion() : null;
+        if (opts.json) {
+            console.log(JSON.stringify({ installed, version, socket: getDefaultSocketPath() }));
+            return;
+        }
+        if (installed) {
+            console.log(chalk.green('tmux:'), version ?? '(version unknown)');
+            console.log(chalk.gray(`socket: ${getDefaultSocketPath()}`));
+        }
+        else {
+            console.log(chalk.yellow('tmux is not installed.'));
+            console.log(chalk.gray(process.platform === 'darwin'
+                ? '  Install with: brew install tmux'
+                : '  Install with: apt install tmux (or your distro equivalent)'));
+            process.exit(1);
+        }
+    });
+    // ─── new ────────────────────────────────────────────────────────────────────
+    const newCmd = tmux
+        .command('new <name>')
+        .description('Start a detached tmux session running a command. The session persists until killed.')
+        .option('-c, --cmd <command>', 'Command to launch in the first pane (sh -c). Omit for an empty shell.')
+        .option('-d, --cwd <dir>', 'Working directory for the first pane')
+        .option('-w, --width <n>', 'Initial window width in columns (tmux clamps to client size on attach)')
+        .option('-h, --height <n>', 'Initial window height in rows')
+        .option('-s, --source <source>', 'Provenance label: cli|extension|teams|external', 'cli')
+        .option('--label <k=v...>', 'Free-form labels (repeatable)', collectLabel, {})
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .option('--replace', 'Kill any existing session with the same name first')
+        .option('--attach-existing', 'Return the existing session if one with this name already exists')
+        .option('--json', 'Output session meta as JSON');
+    setHelpSections(newCmd, {
+        examples: `
+      # Detached agent session
+      agents tmux new claude-debug --cmd "agents run claude"
+
+      # Reuse the session if it already exists (idempotent)
+      agents tmux new pair --cmd "agents run claude" --attach-existing
+
+      # Replace a stale session
+      agents tmux new pair --cmd "agents run claude" --replace
+    `,
+    });
+    newCmd.action(async (name, opts) => {
+        await guardTmux(async () => {
+            const meta = await createSession({
+                name,
+                cmd: opts.cmd,
+                cwd: opts.cwd ? path.resolve(opts.cwd) : undefined,
+                width: opts.width ? parseInt(opts.width, 10) : undefined,
+                height: opts.height ? parseInt(opts.height, 10) : undefined,
+                source: validateSource(opts.source),
+                labels: Object.keys(opts.label).length > 0 ? opts.label : undefined,
+                socket: opts.socket,
+                replace: !!opts.replace,
+                attachExisting: !!opts.attachExisting,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify(meta));
+            }
+            else {
+                console.log(meta.name);
+            }
+        });
+    });
+    // ─── attach ─────────────────────────────────────────────────────────────────
+    const attachCmd = tmux
+        .command('attach <name>')
+        .description('Attach to a running session. Replaces this shell with the tmux client until you detach (Ctrl-b d).')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    attachCmd.action(async (name, opts) => {
+        await guardTmux(async () => {
+            const socket = opts.socket ?? getDefaultSocketPath();
+            if (!(await hasSession(name, socket))) {
+                console.error(chalk.red(`No tmux session named "${name}".`));
+                process.exit(1);
+            }
+            if (!process.stdout.isTTY) {
+                console.error(chalk.red('attach requires a TTY. Run this from an interactive shell.'));
+                process.exit(1);
+            }
+            const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${name}`] });
+            process.exit(code);
+        });
+    });
+    // ─── list ───────────────────────────────────────────────────────────────────
+    const listCmd = tmux
+        .command('list')
+        .alias('ls')
+        .description('List live tmux sessions on the shared server. Prunes stale meta files as a side effect.')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .option('--json', 'Output as JSON');
+    listCmd.action(async (opts) => {
+        await guardTmux(async () => {
+            const sessions = await listSessions({ socket: opts.socket });
+            if (opts.json) {
+                console.log(JSON.stringify(sessions));
+                return;
+            }
+            if (sessions.length === 0) {
+                console.log(chalk.gray('No tmux sessions.'));
+                return;
+            }
+            for (const s of sessions) {
+                const age = formatAge(Date.now() / 1000 - s.createdAtTmux);
+                const cmd = s.meta?.cmd ? chalk.gray(`  ${truncate(s.meta.cmd, 60)}`) : '';
+                const attached = s.attached ? chalk.green(' [attached]') : '';
+                console.log(`  ${chalk.bold(s.name)}  ${s.windows}w  ${age}${attached}${cmd}`);
+            }
+        });
+    });
+    // ─── has ────────────────────────────────────────────────────────────────────
+    tmux
+        .command('has <name>')
+        .description('Exit 0 if a session with this name exists, 1 otherwise. Useful in shell scripts.')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .action(async (name, opts) => {
+        await guardTmux(async () => {
+            const exists = await hasSession(name, opts.socket);
+            process.exit(exists ? 0 : 1);
+        });
+    });
+    // ─── split ──────────────────────────────────────────────────────────────────
+    const splitCmd = tmux
+        .command('split <name> <direction>')
+        .description('Split the active pane of a session. Direction: h (left/right) or v (top/bottom).')
+        .option('-c, --cmd <command>', 'Command to launch in the new pane')
+        .option('-d, --cwd <dir>', 'Working directory for the new pane')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)')
+        .option('--json', 'Output as JSON (returns new pane id like %3)');
+    setHelpSections(splitCmd, {
+        examples: `
+      # Split horizontally (panes side-by-side) and start a second agent
+      agents tmux split team h --cmd "agents run codex"
+
+      # Split vertically (panes stacked) — empty shell
+      agents tmux split team v
+    `,
+    });
+    splitCmd.action(async (name, direction, opts) => {
+        await guardTmux(async () => {
+            if (direction !== 'h' && direction !== 'v') {
+                console.error(chalk.red(`Invalid direction "${direction}". Use h or v.`));
+                process.exit(1);
+            }
+            const paneId = await splitPane({
+                name,
+                direction,
+                cmd: opts.cmd,
+                cwd: opts.cwd ? path.resolve(opts.cwd) : undefined,
+                socket: opts.socket,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({ paneId }));
+            }
+            else {
+                console.log(paneId);
+            }
+        });
+    });
+    // ─── send ───────────────────────────────────────────────────────────────────
+    const sendCmd = tmux
+        .command('send <target> <keys>')
+        .description('Send keystrokes to a session. Target is "name" or "name:pane" (e.g. team:%2 or team:1).')
+        .option('--no-enter', 'Do not append Enter after the keys')
+        .option('--raw', 'Send literally (-l) without tmux key-name interpretation (C-c, Enter, etc.)')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    setHelpSections(sendCmd, {
+        examples: `
+      # Type a command into the session and press Enter
+      agents tmux send team "echo hello"
+
+      # Send Ctrl-C to interrupt
+      agents tmux send team "C-c"
+
+      # Send literal text (no key-name interpretation)
+      agents tmux send team "C-c" --raw
+
+      # Target a specific pane
+      agents tmux send team:%2 "ls -la"
+    `,
+    });
+    sendCmd.action(async (target, keys, opts) => {
+        await guardTmux(async () => {
+            const { name, pane } = splitTarget(target);
+            await sendKeys({
+                name,
+                pane,
+                keys,
+                noEnter: !opts.enter,
+                raw: !!opts.raw,
+                socket: opts.socket,
+            });
+        });
+    });
+    // ─── capture ────────────────────────────────────────────────────────────────
+    const captureCmd = tmux
+        .command('capture <target>')
+        .description('Print the contents of a pane. Target is "name" or "name:pane".')
+        .option('-l, --lines <n>', 'Include this many extra history lines above the visible screen')
+        .option('--ansi', 'Keep ANSI escape codes (default strips them)')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    setHelpSections(captureCmd, {
+        examples: `
+      # See current screen
+      agents tmux capture team
+
+      # Include the last 500 history lines
+      agents tmux capture team --lines 500
+
+      # Target a specific pane
+      agents tmux capture team:%3
+    `,
+    });
+    captureCmd.action(async (target, opts) => {
+        await guardTmux(async () => {
+            const { name, pane } = splitTarget(target);
+            const text = await capturePane({
+                name,
+                pane,
+                lines: opts.lines ? parseInt(opts.lines, 10) : undefined,
+                ansi: !!opts.ansi,
+                socket: opts.socket,
+            });
+            process.stdout.write(text);
+            if (!text.endsWith('\n'))
+                process.stdout.write('\n');
+        });
+    });
+    // ─── info ───────────────────────────────────────────────────────────────────
+    const infoCmd = tmux
+        .command('info <name>')
+        .description('Show provenance for a session (cmd, cwd, created_at, source, labels).')
+        .option('--json', 'Output as JSON');
+    infoCmd.action(async (name, opts) => {
+        const meta = readSessionMeta(name);
+        if (!meta) {
+            console.error(chalk.yellow(`No meta for "${name}" (session may exist but wasn't created via agents tmux).`));
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(meta, null, 2));
+            return;
+        }
+        printMeta(meta);
+    });
+    // ─── kill ───────────────────────────────────────────────────────────────────
+    const killCmd = tmux
+        .command('kill <name>')
+        .description('Kill one tmux session. Idempotent — exits 0 even if the session was already gone.')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    killCmd.action(async (name, opts) => {
+        await guardTmux(async () => {
+            const killed = await killSession(name, opts.socket);
+            if (!killed) {
+                console.log(chalk.gray(`No session "${name}" — nothing to do.`));
+            }
+        });
+    });
+    // ─── kill-all ───────────────────────────────────────────────────────────────
+    const killAllCmd = tmux
+        .command('kill-all')
+        .description('Kill every session on the shared server and remove the socket. Requires --yes.')
+        .option('--yes', 'Confirm — required, no interactive prompt')
+        .option('--socket <path>', 'Use a custom socket (default: shared server)');
+    killAllCmd.action(async (opts) => {
+        await guardTmux(async () => {
+            if (!opts.yes) {
+                console.error(chalk.red('Refusing to kill-all without --yes.'));
+                process.exit(1);
+            }
+            const n = await killAll(opts.socket);
+            console.log(chalk.gray(`Killed ${n} session${n === 1 ? '' : 's'}.`));
+        });
+    });
+}
+// ─── helpers ──────────────────────────────────────────────────────────────────
+/** Wrap a command action so tmux-specific errors render cleanly instead of throwing. */
+async function guardTmux(fn) {
+    try {
+        assertTmuxAvailable();
+        await fn();
+    }
+    catch (err) {
+        if (err instanceof TmuxUnavailableError) {
+            console.error(chalk.red(err.message));
+            process.exit(127);
+        }
+        if (err instanceof TmuxSessionError) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        if (err instanceof TmuxCommandError) {
+            console.error(chalk.red(err.message));
+            process.exit(err.code ?? 1);
+        }
+        throw err;
+    }
+}
+/** Parse `name` or `name:pane` (pane may be `%id` or a numeric index). */
+function splitTarget(target) {
+    const idx = target.indexOf(':');
+    if (idx === -1)
+        return { name: target };
+    return { name: target.slice(0, idx), pane: target.slice(idx + 1) || undefined };
+}
+function validateSource(s) {
+    if (s === 'cli' || s === 'extension' || s === 'teams' || s === 'external')
+        return s;
+    return 'cli';
+}
+function collectLabel(value, acc) {
+    const eq = value.indexOf('=');
+    if (eq === -1)
+        return acc;
+    acc[value.slice(0, eq)] = value.slice(eq + 1);
+    return acc;
+}
+function formatAge(secs) {
+    if (secs < 60)
+        return `${Math.max(0, Math.floor(secs))}s`;
+    const m = Math.floor(secs / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+function truncate(s, n) {
+    return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+function printMeta(m) {
+    console.log(`  ${chalk.bold('name')}       ${m.name}`);
+    console.log(`  ${chalk.bold('socket')}     ${m.socket}`);
+    console.log(`  ${chalk.bold('createdAt')}  ${new Date(m.createdAt).toISOString()}`);
+    console.log(`  ${chalk.bold('source')}     ${m.source}`);
+    if (m.cwd)
+        console.log(`  ${chalk.bold('cwd')}        ${m.cwd}`);
+    if (m.cmd)
+        console.log(`  ${chalk.bold('cmd')}        ${m.cmd}`);
+    if (m.labels) {
+        for (const [k, v] of Object.entries(m.labels)) {
+            console.log(`  ${chalk.bold('label')}      ${k}=${v}`);
+        }
+    }
+}

package/dist/commands/trash.d.ts

@@ -1,10 +1,10 @@
 /**
  * `agents trash` — list and restore soft-deleted version directories.
  *
- * `removeVersion` moves a version dir to ~/.agents-system/trash/versions/<agent>/<version>/<timestamp>/
+ * `removeVersion` moves a version dir to ~/.agents/.history/trash/versions/<agent>/<version>/<timestamp>/
  * instead of hard-deleting. These commands let the user inspect what's there
  * and put a soft-deleted version back. The trash never auto-expires; only
- * `rm -rf ~/.agents-system/trash/` removes bytes from disk.
+ * `rm -rf ~/.agents/.history/trash/` removes bytes from disk.
  */
 import type { Command } from 'commander';
 export declare function registerTrashCommands(program: Command): void;

package/dist/commands/trash.js

@@ -143,7 +143,7 @@ export function registerTrashCommands(program) {
     });
     trash
         .command('restore <target>')
-        .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents-system/versions/')
+        .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents/.history/versions/')
         .action((target) => {
         const parsed = parseAgentVersion(target);
         if (!parsed) {