@phnx-labs/agents-cli 1.20.42 → 1.20.44

package/dist/commands/sessions.js

@@ -425,7 +425,14 @@ export function groupActiveSessions(sessions) {
  * to the same id form); else the local machine. Never keys off `ActiveSession.host`
  * — that is the terminal *app* (code/tmux), not the computer.
  */
+/** Synthetic top-level group key for provider-sandboxed cloud tasks. */
+const CLOUD_MACHINE_KEY = 'cloud';
 function machineKeyFor(s, localMachine) {
+    // Cloud tasks run in a provider sandbox, not on the machine they're attributed
+    // to for reply routing (s.machine = the querier). Surface them as their own
+    // top-level "cloud" group instead of nested under the local device.
+    if (s.context === 'cloud')
+        return CLOUD_MACHINE_KEY;
     if (s.machine)
         return s.machine;
     if (s.provenance?.host)
@@ -449,6 +456,11 @@ export function groupSessionsByMachine(sessions, localMachine) {
             return -1;
         if (b === localMachine)
             return 1;
+        // The synthetic "cloud" category sorts after all real machines.
+        if (a === CLOUD_MACHINE_KEY)
+            return 1;
+        if (b === CLOUD_MACHINE_KEY)
+            return -1;
         const ac = byMachine.get(a).length, bc = byMachine.get(b).length;
         if (ac !== bc)
             return bc - ac;
@@ -575,38 +587,48 @@ function groupTally(sessions) {
     return parts.join(' · ');
 }
 /** Print one machine's workspace tree, indented under its machine header. */
-function renderWorkspaceLayout(layout, base) {
+function renderWorkspaceLayout(layout, base, machineKey) {
     let first = true;
     for (const ws of layout.workspaces) {
         if (!first)
             console.log();
         first = false;
-        const header = ws.key === '__cloud__'
-            ? chalk.magenta.bold('cloud')
-            : ws.key === '__unknown__'
-                ? chalk.gray.bold('unknown')
-                : chalk.cyan.bold(shortCwd(ws.key));
-        const wsSessions = [...ws.windows.flatMap(w => w.sessions), ...ws.flat];
-        const tally = groupTally(wsSessions);
-        console.log(`${base}${header} ${chalk.gray(`(${ws.total})`)}${tally ? chalk.gray(`  ${tally}`) : ''}`);
+        // Under the top-level "cloud" machine group the __cloud__ workspace header is
+        // redundant ("▸ cloud" then "cloud") — render its rows flat under the machine
+        // header instead. Row indent collapses by one level to match.
+        const redundantCloud = ws.key === '__cloud__' && machineKey === CLOUD_MACHINE_KEY;
+        const rowBase = redundantCloud ? base : base + '  ';
+        if (!redundantCloud) {
+            const header = ws.key === '__cloud__'
+                ? chalk.magenta.bold('cloud')
+                : ws.key === '__unknown__'
+                    ? chalk.gray.bold('unknown')
+                    : chalk.cyan.bold(shortCwd(ws.key));
+            const wsSessions = [...ws.windows.flatMap(w => w.sessions), ...ws.flat];
+            const tally = groupTally(wsSessions);
+            console.log(`${base}${header} ${chalk.gray(`(${ws.total})`)}${tally ? chalk.gray(`  ${tally}`) : ''}`);
+        }
         for (const win of ws.windows) {
             // Host is per-process, but every terminal in the same IDE window shares
             // an ancestor — take the first non-empty host as the window's label.
             const host = win.sessions.find((s) => s.host)?.host ?? 'terminal';
             const winHeader = `${chalk.gray(host)} ${chalk.gray('·')} ${chalk.gray(shortWindowLabel(win.windowId))} ${chalk.gray(`(${win.sessions.length})`)}`;
-            console.log(base + '  ' + winHeader);
+            console.log(rowBase + winHeader);
             for (const s of win.sessions)
-                printActiveRow(s, base + '    ');
+                printActiveRow(s, rowBase + '  ');
         }
         for (const s of ws.flat)
-            printActiveRow(s, base + '  ');
+            printActiveRow(s, rowBase);
     }
 }
 /** Machine header: `▸ <name> ← this machine` for the local box (cyan), matching
  * the `ag devices list` treatment; a plain `▸ <name>` for remotes. */
 function printMachineHeader(mg) {
-    const marker = mg.isLocal ? chalk.cyan('▸ ') : chalk.gray('▸ ');
-    const name = mg.isLocal ? chalk.bold.cyan(mg.machine) : chalk.bold(mg.machine);
+    // The synthetic "cloud" group isn't a device — tint it magenta (matching the
+    // cloud row/label styling) so it reads as a category, not a machine.
+    const isCloud = mg.machine === CLOUD_MACHINE_KEY;
+    const marker = mg.isLocal ? chalk.cyan('▸ ') : isCloud ? chalk.magenta('▸ ') : chalk.gray('▸ ');
+    const name = mg.isLocal ? chalk.bold.cyan(mg.machine) : isCloud ? chalk.bold.magenta(mg.machine) : chalk.bold(mg.machine);
     const here = mg.isLocal ? chalk.cyan('  ← this machine') : '';
     console.log(`${marker}${name} ${chalk.gray(`(${mg.total})`)}${here}`);
 }
@@ -740,11 +762,16 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
             console.log();
         firstMachine = false;
         printMachineHeader(mg);
-        renderWorkspaceLayout(mg.layout, '  ');
+        renderWorkspaceLayout(mg.layout, '  ', mg.machine);
     }
     const parts = groupTally(sessions).split(' · ').filter(Boolean);
-    const machineWord = grouped.machines.length === 1 ? 'machine' : 'machines';
-    console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}) across ${grouped.machines.length} ${machineWord}.`));
+    // The synthetic "cloud" group is a category, not a machine — exclude it from the
+    // machine count and note it separately so the tally stays truthful.
+    const realMachines = grouped.machines.filter((m) => m.machine !== CLOUD_MACHINE_KEY).length;
+    const hasCloud = grouped.machines.some((m) => m.machine === CLOUD_MACHINE_KEY);
+    const machineWord = realMachines === 1 ? 'machine' : 'machines';
+    const cloudNote = hasCloud ? ' + cloud' : '';
+    console.log(chalk.gray(`\n${sessions.length} active (${parts.join(', ')}) across ${realMachines} ${machineWord}${cloudNote}.`));
     // Tip only when nothing else could be included and the user didn't opt out.
     if (!opts.local && !opts.hosts?.length && remoteDeviceCount === 0)
         printCrossMachineTip();
@@ -1258,12 +1285,13 @@ function resolveViewMode(options, filters) {
     return 'summary';
 }
 /**
- * Render a session's full transcript to stdout — the non-follow view behind
- * `agents logs <sessionId>`. Reuses the same markdown renderer as
- * `agents sessions <id> --markdown`.
+ * Render a resolved session to stdout — the non-follow view behind
+ * `agents logs <sessionId>`. Defaults to the concise `summary` digest (same as
+ * `agents sessions <id>`); pass `'markdown'` for the full transcript
+ * (`agents logs <id> --full`). Reuses the shared `renderSession` renderer.
  */
-export async function renderSessionLog(session) {
-    await renderSession(session, 'markdown', {});
+export async function renderSessionLog(session, mode = 'summary') {
+    await renderSession(session, mode, {});
 }
 async function renderSession(session, mode, filters, options = {}) {
     // OpenCode stores sessions in SQLite; filePath is "db_path#session_id"

package/dist/commands/teams.js

@@ -11,9 +11,10 @@ import { handleSpawn, handleStatus, handleStop, handleTasks, toTaskStatusSummary
 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';
-import { isVersionInstalled, resolveVersionAlias, resolveVersionAliasLoose } from '../lib/versions.js';
+import { isVersionInstalled, resolveVersion, resolveVersionAlias, resolveVersionAliasLoose, verifyInstalledBinaryLaunches } from '../lib/versions.js';
 import { AGENTS, warnAgentDeprecated } from '../lib/agents.js';
 import { discoverSessions, parseTimeFilter, resolveSessionById } from '../lib/session/discover.js';
+import { renderSessionLog } from './sessions.js';
 import { buildPreview as buildSessionPreview } from './sessions-picker.js';
 import { parseExecEnv } from '../lib/exec.js';
 import { teamPicker, printTeamTable } from './teams-picker.js';
@@ -1651,8 +1652,9 @@ export function registerTeamsCommands(program) {
     teams
         .command('logs [teammate]')
         .alias('log')
-        .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')
+        .description("Show a teammate's concise session summary. --full (or -n <lines>) for the raw stdout. Accepts positional name, --teammate <name>, UUID, or UUID prefix.")
+        .option('-n, --tail <n>', 'Show the last N lines of raw stdout instead of the concise summary')
+        .option('-m, --full', 'Show the full raw stdout log instead of the concise summary')
         .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) => {
@@ -1682,14 +1684,28 @@ export function registerTeamsCommands(program) {
             }
             agentId = resolved.agentId;
         }
+        // Concise by default: a teammate's agentId IS its agent session id (passed
+        // as --session-id at launch), so render the same summary digest as
+        // `agents sessions <id>`. --full / -n <lines> opt into the raw stdout.log.
+        if (!opts.full && !opts.tail) {
+            const all = await discoverSessions({ all: true, limit: 5000 });
+            const matches = resolveSessionById(all, agentId);
+            if (matches.length > 0) {
+                await renderSessionLog(matches[0], 'summary');
+                return;
+            }
+            // No resolvable session (e.g. a non-Claude teammate) — fall through to a
+            // bounded tail of raw stdout rather than dumping the whole file.
+        }
         const logPath = path.join(base, agentId, 'stdout.log');
         try {
             const content = await fs.readFile(logPath, 'utf-8');
-            if (!opts.tail) {
+            if (opts.full) {
                 process.stdout.write(content);
                 return;
             }
-            const n = Math.max(1, parseInt(opts.tail, 10) || 50);
+            // Default tail size keeps an un-resolvable teammate's glance bounded too.
+            const n = opts.tail ? Math.max(1, parseInt(opts.tail, 10) || 50) : 40;
             const lines = content.split('\n');
             process.stdout.write(lines.slice(-n).join('\n'));
         }
@@ -1705,6 +1721,28 @@ export function registerTeamsCommands(program) {
         .option('--json', 'Output machine-readable JSON')
         .action(async (opts) => {
         const info = checkAllClis();
+        // Deep integrity probe. `checkAllClis` reports presence (shim + stub guard),
+        // but a GUTTED native binary (JS wrapper present, platform binary missing —
+        // the codex/kimi optional-dep partial-extract failure) still passes that. So
+        // actually launch the resolved default version and, if it won't run, flip the
+        // agent to not-installed with a repair hint — otherwise doctor says "ready"
+        // and the teammate ENOENTs at spawn. Parallel; win32 is treated as healthy by
+        // verifyInstalledBinaryLaunches.
+        await Promise.all(Object.entries(info).map(async ([name, entry]) => {
+            if (!entry.installed)
+                return;
+            const agent = name;
+            const version = resolveVersion(agent);
+            if (!version)
+                return;
+            const health = await verifyInstalledBinaryLaunches(agent, version);
+            if (!health.ok) {
+                entry.installed = false;
+                entry.path = null;
+                entry.error = `${AGENTS[agent]?.cliCommand ?? name}@${version} is installed but its binary won't launch`
+                    + `${health.detail ? ` (${health.detail})` : ''}. Repair: agents add ${agent}@${version}`;
+            }
+        }));
         // Advisory enrichment only. Sign-in detection is UNRELIABLE, so it never
         // changes the authoritative installed/ready column — it annotates. And an
         // agent that is actually running in a team is treated as signed in

package/dist/lib/browser/chrome.d.ts

@@ -36,6 +36,28 @@ export declare function getRunningChromeInfo(profileName: string): {
     pid: number;
     port: number;
 } | null;
+/**
+ * Prepare `<userDataDir>/Default/Preferences` before launch.
+ *
+ * Two concerns, one write:
+ *  - First launch (file absent): stamp the agents-cli profile name so
+ *    Chromium's UI shows "<profile>" instead of its default "Person 1".
+ *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
+ *  - Every launch (when `persistSessionCookies`): pin
+ *    `session.restore_on_startup: 1` ("continue where you left off").
+ *    Chromium purges memory-only session cookies at startup UNLESS this
+ *    preference says the session will be restored — it keys the purge off
+ *    the pref, not off tabs actually reopening. Sites like idealista issue
+ *    login cookies with `expires=-1`, so without this every browser restart
+ *    silently logs the profile out. The visible tab-restore side effect is
+ *    suppressed separately via `--no-startup-window` (see launchBrowser).
+ *
+ * Runs only while the browser is down (called before spawn), so Chromium
+ * can't overwrite the patch on exit. Best-effort: a malformed existing file
+ * is left untouched (Chromium recovers its own state better than we can),
+ * and any I/O hiccup is silently ignored.
+ */
+export declare function ensureProfilePreferences(userDataDir: string, profileName: string, persistSessionCookies: boolean): void;
 /**
  * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
  * (lsof doesn't exist there). Returns false on any tooling error so port

package/dist/lib/browser/chrome.js

@@ -212,11 +212,11 @@ isElectron = false) {
     const runtimeDir = getProfileRuntimeDir(profileName);
     const userDataDir = path.join(runtimeDir, 'chrome-data');
     fs.mkdirSync(userDataDir, { recursive: true });
-    // First-launch seed: stamp the user-data-dir's Default/Preferences with
-    // the agents-cli profile name so Chromium's UI shows "<profile>" instead
-    // of its default "Person 1". Done only when the file doesn't exist —
-    // subsequent launches inherit whatever Chrome wrote in the meantime.
-    seedDefaultProfileName(userDataDir, profileName);
+    // Pre-launch Preferences pass: first-launch profile-name stamp, plus (for
+    // real browsers, not Electron apps) the session-cookie persistence pin.
+    // Electron apps manage their own storage and don't read Chromium's
+    // `session.*` prefs, so they get the name stamp only.
+    ensureProfilePreferences(userDataDir, profileName, !isElectron);
     // Chromium on macOS coordinates instances via the SingletonLock file
     // *inside* each user-data-dir. Direct binary spawn with a fresh
     // --user-data-dir creates a fully independent process — the user's
@@ -242,6 +242,14 @@ isElectron = false) {
         // remote-debugging transport is active. That property is the loudest
         // signal Cloudflare Turnstile, hCaptcha, and similar checks read.
         '--disable-blink-features=AutomationControlled',
+        // Companion to `session.restore_on_startup: 1` (see
+        // ensureProfilePreferences): the pref keeps session cookies alive across
+        // restarts, but on its own it would also reopen last session's tabs at
+        // startup. Suppressing the startup window leaves restore nothing to fill —
+        // cookies survive, no ghost tabs — and the task flow creates its own tab
+        // over CDP anyway. Electron apps need their window to appear (the CDP
+        // driver binds to it), so they skip the flag.
+        ...(isElectron ? [] : ['--no-startup-window']),
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -325,20 +333,52 @@ export function getRunningChromeInfo(profileName) {
     return { pid: rt.pid, port: rt.port };
 }
 /**
- * Stamp `<userDataDir>/Default/Preferences` with our profile name so
- * Chrome's UI labels the window with the agents-cli name rather than the
- * default "Person 1". Only writes when the file is absent (first launch).
- * Best-effort: any I/O hiccup is silently ignored; missing the rename is
- * cosmetic, not functional.
+ * Prepare `<userDataDir>/Default/Preferences` before launch.
+ *
+ * Two concerns, one write:
+ *  - First launch (file absent): stamp the agents-cli profile name so
+ *    Chromium's UI shows "<profile>" instead of its default "Person 1".
+ *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
+ *  - Every launch (when `persistSessionCookies`): pin
+ *    `session.restore_on_startup: 1` ("continue where you left off").
+ *    Chromium purges memory-only session cookies at startup UNLESS this
+ *    preference says the session will be restored — it keys the purge off
+ *    the pref, not off tabs actually reopening. Sites like idealista issue
+ *    login cookies with `expires=-1`, so without this every browser restart
+ *    silently logs the profile out. The visible tab-restore side effect is
+ *    suppressed separately via `--no-startup-window` (see launchBrowser).
+ *
+ * Runs only while the browser is down (called before spawn), so Chromium
+ * can't overwrite the patch on exit. Best-effort: a malformed existing file
+ * is left untouched (Chromium recovers its own state better than we can),
+ * and any I/O hiccup is silently ignored.
  */
-function seedDefaultProfileName(userDataDir, profileName) {
+export function ensureProfilePreferences(userDataDir, profileName, persistSessionCookies) {
     const defaultDir = path.join(userDataDir, 'Default');
     const prefsPath = path.join(defaultDir, 'Preferences');
-    if (fs.existsSync(prefsPath))
+    let prefs;
+    try {
+        prefs = JSON.parse(fs.readFileSync(prefsPath, 'utf8'));
+        if (typeof prefs !== 'object' || prefs === null)
+            return; // not ours to fix
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            return; // unreadable/malformed: leave alone
+    }
+    const firstLaunch = prefs === undefined;
+    if (firstLaunch)
+        prefs = { profile: { name: profileName } };
+    let dirty = firstLaunch;
+    if (persistSessionCookies && prefs.session?.restore_on_startup !== 1) {
+        prefs.session = { ...prefs.session, restore_on_startup: 1 };
+        dirty = true;
+    }
+    if (!dirty)
         return;
     try {
         fs.mkdirSync(defaultDir, { recursive: true });
-        fs.writeFileSync(prefsPath, JSON.stringify({ profile: { name: profileName } }));
+        fs.writeFileSync(prefsPath, JSON.stringify(prefs));
     }
     catch { /* not critical */ }
 }

package/dist/lib/browser/service.js

@@ -310,6 +310,19 @@ export class BrowserService {
             conn = await this.connectProfile(effectiveProfile, resolved.target);
             this.connections.set(composite, conn);
         }
+        // Browsers launch with --no-startup-window (session-cookie persistence,
+        // see launchBrowser), so a bare `start` with no --url would otherwise
+        // leave the user staring at a process with zero windows. Recreate the
+        // old startup-window affordance: if no page target exists, open a blank
+        // one. Deliberately NOT registered on the task — the startup window
+        // never was either, and tasks track only tabs they created.
+        if (!opts.url && !conn.electron) {
+            const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+            if (!targetInfos.some((t) => t.type === 'page')) {
+                await conn.cdp.send('Target.createTarget', { url: 'about:blank' });
+                this.invalidateTargetCache(conn);
+            }
+        }
         const task = {
             id: taskId,
             name: taskName,

package/dist/lib/daemon.js

@@ -19,6 +19,7 @@ import { detectOverdueJobs, notifyOverdue } from './overdue.js';
 import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
 import { readAndResolveBundleEnv } from './secrets/bundles.js';
+import { redactSecrets } from './redact.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -207,15 +208,6 @@ export function reapStrayDaemons(keepPid = process.pid) {
     }
     return { reaped, details };
 }
-/** Redact values that look like tokens or credentials in a log message. */
-function redactSecrets(message) {
-    let safe = message;
-    safe = safe.replace(/eyJ[A-Za-z0-9_-]{20,}/g, '[REDACTED_TOKEN]');
-    safe = safe.replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]');
-    safe = safe.replace(/(sk-[a-zA-Z0-9]{20,})/g, '[REDACTED_KEY]');
-    safe = safe.replace(/(ANTHROPIC_API_KEY|OPENAI_API_KEY|API_KEY|SECRET|TOKEN|PASSWORD)=\S+/gi, '$1=[REDACTED]');
-    return safe;
-}
 function rotateLogsIfNeeded(logPath) {
     try {
         const stat = fs.statSync(logPath);
@@ -428,6 +420,37 @@ export async function runDaemon() {
     };
     const deviceProbeInterval = setInterval(() => { void runDeviceProbe(); }, 3 * 60_000);
     const deviceProbeKickoff = setTimeout(() => { void runDeviceProbe(); }, 15_000);
+    // tmux hook reconcile: retrofit the guarded `pane-died` hook onto managed
+    // `agents run` sessions a pre-fix binary left with the old unconditional hook
+    // (which detached the whole client — kicking the user out of the view — when
+    // they exited a split they'd opened). Non-destructive: set-hook only, never a
+    // kill or detach. A per-session schema marker makes steady-state a no-op, so
+    // this stays cheap at ~every 5 min, plus once ~20s after startup so a
+    // just-upgraded daemon heals still-running sessions without waiting for them to
+    // cycle or the shared server to be recycled.
+    let reconcilingTmux = false;
+    const runTmuxReconcile = async () => {
+        if (reconcilingTmux)
+            return;
+        reconcilingTmux = true;
+        try {
+            const { isTmuxInstalled } = await import('./tmux/binary.js');
+            if (!isTmuxInstalled())
+                return;
+            const { reconcileSessionHooks } = await import('./tmux/session.js');
+            const r = await reconcileSessionHooks();
+            if (r.reconciled > 0)
+                log('INFO', `tmux: retrofitted pane-died hook on ${r.reconciled} session(s)`);
+        }
+        catch (err) {
+            log('ERROR', `tmux reconcile failed: ${err.message}`);
+        }
+        finally {
+            reconcilingTmux = false;
+        }
+    };
+    const tmuxReconcileInterval = setInterval(() => { void runTmuxReconcile(); }, 5 * 60_000);
+    const tmuxReconcileKickoff = setTimeout(() => { void runTmuxReconcile(); }, 20_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -447,6 +470,8 @@ export async function runDaemon() {
         clearTimeout(healKickoff);
         clearInterval(deviceProbeInterval);
         clearTimeout(deviceProbeKickoff);
+        clearInterval(tmuxReconcileInterval);
+        clearTimeout(tmuxReconcileKickoff);
         removeDaemonPid();
         process.exit(0);
     };

package/dist/lib/exec.d.ts

@@ -80,6 +80,13 @@ export interface ExecOptions {
     addDirs?: string[];
     timeout?: string;
     sessionId?: string;
+    /**
+     * Durable `agents run --name <slug>` handle. Exported to the agent's env as
+     * `AGENT_SESSION_NAME` (companion to `AGENT_SESSION_ID`) and, when a session
+     * id is known at launch, recorded in the run-name index so `agents sessions
+     * <name>` resolves the run. Absent for unnamed runs — no behavior change.
+     */
+    name?: string;
     /**
      * Resume the conversation named by `sessionId` using the agent's NATIVE resume
      * form (claude `--resume`, codex `resume`) instead of the default `--session-id`
@@ -265,6 +272,14 @@ export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
  * (`BASH_FUNC_*%%`) can't make `env` choke.
  */
 export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv): string;
+/**
+ * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
+ * (right-stripping each). Used by runInTmux to recap a fast-failed agent's
+ * output into the caller's shell so a launch crash (e.g. a gutted install that
+ * dies with ENOENT the instant it spawns) isn't swallowed by the bare
+ * `[detached]` the pane-died hook otherwise leaves behind.
+ */
+export declare function formatPaneTail(raw: string, maxLines?: number): string;
 /** Exit code spawnAgent resolves with when a run is killed for crossing a budget cap. */
 export declare const BUDGET_KILL_EXIT_CODE = 7;
 /**

package/dist/lib/exec.js

@@ -17,6 +17,7 @@ import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js'
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
@@ -257,6 +258,12 @@ export function buildExecEnv(options) {
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
     }
+    // Export the run's durable name (companion to AGENT_SESSION_ID) so a
+    // SessionStart hook / the agent can associate its transcript with the handle
+    // the user gave the run. Only set when --name was passed.
+    if (options.name) {
+        result.AGENT_SESSION_NAME = options.name;
+    }
     return {
         ...result,
         ...options.env,
@@ -508,7 +515,13 @@ export function buildExecCommand(options) {
             cmd[0] = absPath;
         }
         else {
-            cmd[0] = versionedName;
+            // No versioned shim on disk. Prefer the version's REAL launch binary
+            // (node_modules/.bin/<cli>) over the bare `<cli>@<version>` name — that
+            // literal is not on PATH and spawns as ENOENT (the `kimi@0.19.2` failure).
+            // Fall back to the literal only if the binary is absent (the run path's
+            // ensureAgentRunnable normally repairs/creates the alias before we reach here).
+            const realBinary = options.agent ? getBinaryPath(options.agent, options.version) : undefined;
+            cmd[0] = realBinary && fs.existsSync(realBinary) ? realBinary : versionedName;
         }
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
@@ -807,6 +820,21 @@ export function buildTmuxAgentCommand(executable, args, env) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     return `exec env ${envPrefix} ${agentCmd}`;
 }
+/**
+ * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
+ * (right-stripping each). Used by runInTmux to recap a fast-failed agent's
+ * output into the caller's shell so a launch crash (e.g. a gutted install that
+ * dies with ENOENT the instant it spawns) isn't swallowed by the bare
+ * `[detached]` the pane-died hook otherwise leaves behind.
+ */
+export function formatPaneTail(raw, maxLines = 30) {
+    return raw
+        .split('\n')
+        .map(l => l.replace(/\s+$/, ''))
+        .filter(l => l.length > 0)
+        .slice(-maxLines)
+        .join('\n');
+}
 /**
  * Run an interactive agent inside a detached tmux session on the shared socket,
  * attach the current TTY, and propagate the wrapped agent's exit code.
@@ -827,7 +855,7 @@ export function buildTmuxAgentCommand(executable, args, env) {
  *      (Ctrl-b d) — return 0 and LEAVE the session for `agents focus` to re-attach.
  */
 async function runInTmux(options, executable, args) {
-    const { createSession, killSession, paneExitStatus, setSessionHook, slugifyName } = await import('./tmux/session.js');
+    const { createSession, killSession, paneExitStatus, setSessionHook, slugifyName, agentPaneDiedHook, markSessionHookSchema } = await import('./tmux/session.js');
     const { getDefaultSocketPath } = await import('./tmux/paths.js');
     const { attachTmux, runTmux } = await import('./tmux/binary.js');
     const socket = getDefaultSocketPath();
@@ -848,7 +876,10 @@ async function runInTmux(options, executable, args) {
         // that split in place instead of detaching everyone (the pane-died hook runs
         // in the dead pane's context, so bare `kill-pane` targets it). Without the
         // guard, exiting any split kicked the user clean out of tmux.
-        await setSessionHook(name, 'pane-died', `if -F '#{==:#{hook_pane},${pane}}' 'detach-client -s =${name}' 'kill-pane'`, socket);
+        await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
+        // Stamp the schema marker so the daemon reconcile (which retrofits older
+        // sessions) recognizes this one as already current and skips it.
+        await markSessionHookSchema(name, socket);
         // Record the agent's OS pid (the pane leaf, thanks to `exec`) WITH its tmux
         // pane so the active-scan attributes it exactly and shows the %pane.
         let panePid = 0;
@@ -866,14 +897,54 @@ async function runInTmux(options, executable, args) {
             startedAtMs: Date.now(),
         });
     }
+    // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
+    // detaches the client the instant the agent exits, so a fast failure (a
+    // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
+    // otherwise leave only a bare `[detached]` with no clue why. Must run BEFORE
+    // killSession — capture-pane needs the session still alive (remain-on-exit
+    // keeps the dead pane readable until we tear it down). Best-effort throughout.
+    const surfacePaneFailure = async (status, headline) => {
+        if (!pane)
+            return;
+        let tail = '';
+        try {
+            const r = await runTmux({ socket, args: ['capture-pane', '-p', '-t', pane, '-S', '-200'], throwOnError: false });
+            if (r.code === 0)
+                tail = formatPaneTail(r.stdout);
+        }
+        catch { /* best-effort — a missing pane just means no recap */ }
+        const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
+        process.stderr.write(`\n${RED}agents: ${headline} (exit ${status ?? 1}).${OFF}\n`);
+        if (tail) {
+            process.stderr.write(`${GRAY}  ── last output from ${options.agent} ──${OFF}\n`);
+            process.stderr.write(tail.replace(/^/gm, '  ') + '\n');
+            process.stderr.write(`${GRAY}  ${'─'.repeat(30)}${OFF}\n`);
+        }
+        process.stderr.write(`${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.${OFF}\n\n`);
+    };
     // The agent could exit before we attach (fast failure). Don't attach to an
-    // already-dead pane — read its status directly and tear down.
+    // already-dead pane — surface its output + status directly and tear down.
     const before = pane ? await paneExitStatus(pane, socket) : { dead: false };
-    if (!before.dead) {
-        await attachTmux({ socket, args: ['attach-session', '-t', name] });
+    if (before.dead) {
+        // Only recap a FAILURE. A clean (0) exit before we attached is a successful
+        // quick run, not a crash — a red banner there would be spurious (mirrors the
+        // post-attach guard below).
+        if ((before.status ?? 0) !== 0) {
+            await surfacePaneFailure(before.status, `${options.agent} exited before it could start`);
+        }
+        await killSession(name, socket).catch(() => { });
+        return { exitCode: before.status ?? 0, stderr: '' };
     }
+    await attachTmux({ socket, args: ['attach-session', '-t', name] });
     const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
     if (after.dead) {
+        // Nonzero exit after attach → the agent crashed rather than the user
+        // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).
+        // The pane-died hook may have yanked the view before the error was readable,
+        // so recap it into the shell. A clean (0) exit stays quiet — nothing to say.
+        if ((after.status ?? 0) !== 0) {
+            await surfacePaneFailure(after.status, `${options.agent} exited`);
+        }
         await killSession(name, socket).catch(() => { });
         return { exitCode: after.status ?? 0, stderr: '' };
     }
@@ -900,6 +971,12 @@ async function spawnAgent(options) {
     if (options.agent === 'claude' && !options.resume && !options.sessionId) {
         options = { ...options, sessionId: randomUUID() };
     }
+    // Record the run's --name against its session id (when both are known at
+    // launch) so `agents sessions <name>` resolves it. Best-effort; unnamed runs
+    // and agents whose id isn't known up front simply skip this.
+    if (options.name && options.sessionId) {
+        recordRunName({ sessionId: options.sessionId, name: options.name, agent: options.agent, cwd: options.cwd });
+    }
     const cmd = buildExecCommand(options);
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;

package/dist/lib/hosts/dispatch.d.ts

@@ -27,6 +27,11 @@ export interface DispatchOptions {
      * resumable by id. Mutually exclusive with `resume`.
      */
     sessionId?: string;
+    /**
+     * Durable `--name <slug>` handle, forwarded to the remote `agents run` and
+     * recorded on the local task so `agents hosts logs/ps <name>` resolve it.
+     */
+    name?: string;
     /** Resume an existing session on the host by id (via `agents run --resume`). */
     resume?: string;
     /** Stream progress and block until completion (default true). */

package/dist/lib/hosts/dispatch.js

@@ -62,6 +62,7 @@ async function launchDetached(host, target, opts) {
         prompt: opts.promptLabel,
         pid: Number.isFinite(pid) ? pid : undefined,
         sessionId: opts.sessionId,
+        name: opts.name,
         remoteLog,
         remoteExit,
         status: 'running',
@@ -96,6 +97,8 @@ export function buildRunForwardedArgs(opts) {
         args.push('--mode', opts.mode);
     if (opts.model)
         args.push('--model', opts.model);
+    if (opts.name)
+        args.push('--name', opts.name);
     if (opts.resume)
         args.push('--resume', opts.resume);
     else if (opts.sessionId)
@@ -115,6 +118,7 @@ export async function dispatchToHost(host, opts) {
         timeoutMs: opts.timeoutMs,
         agentLabel: opts.agent,
         promptLabel: opts.prompt,
+        name: opts.name,
         // On resume the remote session keeps its existing id; record that id so the
         // task stays mapped to the same session.
         sessionId: opts.resume ?? opts.sessionId,