@phnx-labs/agents-cli 1.20.43 → 1.20.44

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

@@ -272,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

@@ -515,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)
@@ -814,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.
@@ -834,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();
@@ -855,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;
@@ -873,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: '' };
     }

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

@@ -2,9 +2,13 @@
  * Shared host-task log viewer — the show-or-follow core behind both
  * `agents hosts logs <id>` and the top-level `agents logs <id>`.
  *
- * A running task with follow re-enters the offset-tail (`followHostTask`);
- * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
- * place so the two commands can never drift.
+ * A running task with follow re-enters the offset-tail (`followHostTask`).
+ * Otherwise the view is **concise by default**: a bounded tail of the captured
+ * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
+ * log. `full` opts into the entire raw log. (A host run's real transcript lives
+ * on the remote, not the local index — surfacing its rich summary needs remote
+ * runs to be discoverable there first; until then the bounded tail is the safe
+ * concise default.) Kept in one place so the two commands can never drift.
  */
 export interface HostLogResult {
     /** False when no host task with this id exists (caller may fall through to sessions). */
@@ -12,5 +16,10 @@ export interface HostLogResult {
     /** Process exit code to adopt when the task was shown/followed. */
     exitCode?: number;
 }
-/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
-export declare function showHostTaskLog(id: string, follow: boolean): Promise<HostLogResult>;
+/**
+ * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
+ * default; `full` dumps the entire raw combined-stdout log.
+ */
+export declare function showHostTaskLog(id: string, follow: boolean, full?: boolean): Promise<HostLogResult>;
+/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
+export declare function tailLines(text: string, n: number): string;

package/dist/lib/hosts/logs.js

@@ -2,9 +2,13 @@
  * Shared host-task log viewer — the show-or-follow core behind both
  * `agents hosts logs <id>` and the top-level `agents logs <id>`.
  *
- * A running task with follow re-enters the offset-tail (`followHostTask`);
- * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
- * place so the two commands can never drift.
+ * A running task with follow re-enters the offset-tail (`followHostTask`).
+ * Otherwise the view is **concise by default**: a bounded tail of the captured
+ * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
+ * log. `full` opts into the entire raw log. (A host run's real transcript lives
+ * on the remote, not the local index — surfacing its rich summary needs remote
+ * runs to be discoverable there first; until then the bounded tail is the safe
+ * concise default.) Kept in one place so the two commands can never drift.
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -12,8 +16,13 @@ import { loadTask, localLogPath, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { reconcileTask } from './reconcile.js';
 import { sshExecRaw } from '../ssh-exec.js';
-/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
-export async function showHostTaskLog(id, follow) {
+/** Lines of raw combined-stdout to show in the concise (non-`full`) view. */
+const HOST_LOG_TAIL_LINES = 40;
+/**
+ * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
+ * default; `full` dumps the entire raw combined-stdout log.
+ */
+export async function showHostTaskLog(id, follow, full = false) {
     const task = loadTask(id);
     if (!task)
         return { found: false };
@@ -36,21 +45,38 @@ export async function showHostTaskLog(id, follow) {
     // plain `logs <id>` also unsticks a task whose follower was killed. No-op (no
     // ssh) once the record is already terminal.
     reconcileTask(task);
+    // Raw combined-stdout: the whole log with `full`, else a bounded tail.
+    const raw = readTaskLog(task);
+    if (raw === null) {
+        process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
+        return { found: true, exitCode: 0 };
+    }
+    process.stdout.write(full ? raw : tailLines(raw, HOST_LOG_TAIL_LINES));
+    return { found: true, exitCode: 0 };
+}
+/** Read the task's combined-stdout — local mirror first, else fetch+cache remote. */
+function readTaskLog(task) {
     try {
-        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
+        return fs.readFileSync(localLogPath(task.id), 'utf-8');
     }
     catch {
         // No local log — task was dispatched with --no-follow. Fetch from the remote
         // on demand and cache locally so subsequent calls are instant.
         const remote = fetchAndCacheRemoteLog(task);
-        if (remote !== null) {
-            process.stdout.write(remote);
-        }
-        else {
-            process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
-        }
+        return remote !== null ? remote.toString('utf-8') : null;
     }
-    return { found: true, exitCode: 0 };
+}
+/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
+export function tailLines(text, n) {
+    const lines = text.split('\n');
+    // A trailing newline yields a final empty element — drop it from the count.
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    if (lines.length <= n)
+        return lines.join('\n') + '\n';
+    const hidden = lines.length - n;
+    const note = chalk.gray(`… ${hidden} earlier line${hidden === 1 ? '' : 's'} hidden — pass --full for the whole log\n`);
+    return note + lines.slice(-n).join('\n') + '\n';
 }
 /**
  * Fetch a task's remote log over SSH, write it to the local mirror path (for

package/dist/lib/redact.js

@@ -7,6 +7,7 @@ const SECRET_PATTERNS = [
     [/\bsk-[A-Za-z0-9]{20,}\b/g, '[REDACTED_API_KEY]'],
     [/\bnpm_[A-Za-z0-9]{36}\b/g, '[REDACTED_NPM_TOKEN]'],
     [/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED_JWT]'],
+    [/Bearer\s+\S+/gi, 'Bearer [REDACTED]'],
     [/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi, '$1=[REDACTED]'],
 ];
 export function redactSecrets(text) {

package/dist/lib/session/active.d.ts

@@ -102,6 +102,12 @@ export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
 }
+/**
+ * Resolve an agent kind from a process's reported executable. `comm` may be an
+ * absolute path (shim-launched agents), and Windows image names carry an
+ * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
+ */
+export declare function agentKindFromComm(commRaw: string): string | undefined;
 /**
  * Pick a Claude transcript file within a project dir.
  *

package/dist/lib/session/active.js

@@ -64,7 +64,16 @@ const AGENT_CLI_NAMES = {
  * absolute path (shim-launched agents), and Windows image names carry an
  * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
  */
-function agentKindFromComm(commRaw) {
+export function agentKindFromComm(commRaw) {
+    // A GUI desktop app can bundle a binary with the SAME name as an agent CLI: the
+    // Codex desktop app ships `/Applications/Codex.app/Contents/Resources/codex` (its
+    // `app-server`), whose basename `codex` would otherwise match the codex CLI and
+    // surface the app's background server as a phantom agent session — running at cwd
+    // '/', so it shows up unattributed in the feed. A real agent CLI is never inside a
+    // `.app` bundle, so exclude those. (The Claude desktop app is a separate case,
+    // already excluded by name below: its process is 'Claude', not the CLI's 'claude'.)
+    if (commRaw.includes('.app/Contents/'))
+        return undefined;
     const base = path.basename(commRaw);
     const stripped = base.replace(/\.exe$/i, '');
     // Windows image names compare case-insensitively; POSIX comms stay exact —

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 24;
+export declare const SHIM_SCHEMA_VERSION = 25;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.

package/dist/lib/shims.js

@@ -211,7 +211,10 @@ async function promptConflictStrategy(conflictInfos) {
 // v22 — export DISABLE_AUTOUPDATER=1 for claude shims so a pinned per-version
 //        install can't self-mutate: Claude Code's background auto-updater would
 //        otherwise rewrite the pinned binary in place. Explicit user value wins.
-export const SHIM_SCHEMA_VERSION = 24;
+// v25 — dispatcher self-recovery: if the baked AGENTS_BIN is gone (a removed/moved
+//        dev build that generated the shim), resolve `agents` on PATH instead of
+//        exiting 127, so a stale/vanished dev build can't brick every launch.
+export const SHIM_SCHEMA_VERSION = 25;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -291,8 +294,19 @@ AGENT="${agent}"
 CLI_COMMAND="${cliCommand}"
 
 if [ -z "$AGENTS_BIN" ] || [ ! -x "$AGENTS_BIN" ]; then
-  echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2
-  exit 127
+  # The baked dispatcher is gone — e.g. the build that generated this shim (often
+  # a dev build under ~/.local/agents-cli-dev) was removed, moved, or its version
+  # dir rotated. Self-recover to whatever 'agents' now resolves to on PATH instead
+  # of bricking every managed launch. 'agents' is the CLI itself, never a per-agent
+  # shim, so this cannot re-enter this dispatcher.
+  RECOVERED_BIN="$(command -v agents 2>/dev/null || true)"
+  if [ -n "$RECOVERED_BIN" ] && [ -x "$RECOVERED_BIN" ]; then
+    AGENTS_BIN="$RECOVERED_BIN"
+  else
+    echo "agents: agents-cli entrypoint missing or not executable: $AGENTS_BIN" >&2
+    echo "agents: could not resolve 'agents' on PATH to recover. Reinstall: npm i -g @phnx-labs/agents-cli" >&2
+    exit 127
+  fi
 fi
 
 # When agents-cli "adopts" a harness's own launcher (symlinks the native binary

package/dist/lib/teams/agents.js

@@ -20,6 +20,7 @@ import { debug } from './debug.js';
 import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from '../gemini-settings.js';
 import { getAgentsDir as getSystemAgentsDir, getShimsDir } from '../state.js';
 import { AGENTS, getAccountInfo } from '../agents.js';
+import { resolveVersion, isVersionInstalled } from '../versions.js';
 import { sanitizeProcessEnv } from '../secrets/bundles.js';
 let lastMemoryWarnAt = 0;
 // On macOS, os.freemem() returns only the truly-free pool and ignores the
@@ -326,18 +327,26 @@ export async function ensureGeminiPlanMode() {
  * (for CLIs the user installed outside agents-cli).
  */
 export function checkCliAvailable(agentType) {
-    const executable = AGENTS[agentType]?.cliCommand;
+    const agent = agentType;
+    const executable = AGENTS[agent]?.cliCommand;
     if (!executable) {
         return [false, `Unknown agent type: ${agentType}`];
     }
     const shimPath = path.join(getShimsDir(), executable);
-    if (fsSync.existsSync(shimPath)) {
-        return [true, shimPath];
+    const dispatch = fsSync.existsSync(shimPath) ? shimPath : findExecutable(executable);
+    if (!dispatch) {
+        return [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
     }
-    const resolved = findExecutable(executable);
-    return resolved
-        ? [true, resolved]
-        : [false, `CLI tool '${executable}' not found in PATH. Install it first.`];
+    // A shim file (or a PATH entry) existing does NOT mean the agent is runnable:
+    // the managed default version's binary can be a stub or gutted (a partial/raced
+    // npm extract leaves the version dir + JS wrapper but no real binary). Verify
+    // the resolved default version is actually installed so `teams doctor` reports
+    // the truth instead of a false `installed: true` that ENOENTs at spawn.
+    const version = resolveVersion(agent);
+    if (version && !isVersionInstalled(agent, version)) {
+        return [false, `${executable}@${version} is not runnable — its binary is missing/incomplete. Repair: agents add ${agent}@${version}`];
+    }
+    return [true, dispatch];
 }
 /** Check availability of all known agent CLIs. Returns a map of agent type to install status. */
 export function checkAllClis() {

package/dist/lib/tmux/session.d.ts

@@ -126,6 +126,46 @@ export declare function paneExitStatus(pane: string, socket?: string): Promise<P
  * Best-effort — a failed hook just means the user Ctrl-b d's out manually.
  */
 export declare function setSessionHook(name: string, hook: string, command: string, socket?: string): Promise<void>;
+/**
+ * Schema version of the `pane-died` hook installed on managed `agents run`
+ * sessions. Bump whenever the hook's SHAPE changes so the daemon reconcile
+ * (reconcileSessionHooks) knows to re-stamp live sessions a prior binary left on
+ * an older shape.
+ *   v1 — the original unconditional `detach-client`: ANY pane death (including a
+ *        user exiting a split they opened) tore down the whole client.
+ *   v2 — `#{hook_pane}`-guarded: only the AGENT pane dying detaches; a user
+ *        split's death runs `kill-pane`, closing just that split.
+ */
+export declare const AGENT_HOOK_SCHEMA = 2;
+/**
+ * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
+ * (so the blocking attach in runInTmux returns and the exit status can be read);
+ * a user split's death falls through to `kill-pane`, which — because the hook
+ * runs in the dead pane's context — closes that split in place. Single source of
+ * truth: both the spawn-wrap (exec.ts) and the daemon reconcile build the hook
+ * here, so the two can never drift.
+ */
+export declare function agentPaneDiedHook(sessionName: string, agentPane: string): string;
+/** Stamp a session's hook-schema marker to the current version. */
+export declare function markSessionHookSchema(name: string, socket?: string): Promise<void>;
+/**
+ * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
+ * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:
+ * it only `set-hook`s (never kills a pane or detaches a client), so a long-lived
+ * shared server started by a pre-fix binary — whose still-running sessions carry
+ * the old unconditional hook that kicked the user out of the whole view when they
+ * exited a split — self-heals in place, without waiting for those agents to exit
+ * or for the server to be recycled.
+ *
+ * The daemon calls this on a light interval. The per-session `@ag_hook_schema`
+ * marker makes steady-state a cheap no-op: a session already at the current
+ * schema is skipped. Only run-wrapped sessions (`ag-` prefix) are touched — an
+ * externally-created session on the socket keeps whatever hook it set.
+ */
+export declare function reconcileSessionHooks(socket?: string): Promise<{
+    scanned: number;
+    reconciled: number;
+}>;
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)

package/dist/lib/tmux/session.js

@@ -269,6 +269,98 @@ export async function setSessionHook(name, hook, command, socket) {
     const sock = socket ?? getDefaultSocketPath();
     await runTmux({ socket: sock, args: ['set-hook', '-t', name, hook, command], throwOnError: false }).catch(() => { });
 }
+/**
+ * Schema version of the `pane-died` hook installed on managed `agents run`
+ * sessions. Bump whenever the hook's SHAPE changes so the daemon reconcile
+ * (reconcileSessionHooks) knows to re-stamp live sessions a prior binary left on
+ * an older shape.
+ *   v1 — the original unconditional `detach-client`: ANY pane death (including a
+ *        user exiting a split they opened) tore down the whole client.
+ *   v2 — `#{hook_pane}`-guarded: only the AGENT pane dying detaches; a user
+ *        split's death runs `kill-pane`, closing just that split.
+ */
+export const AGENT_HOOK_SCHEMA = 2;
+/** Per-session tmux user-option that records which AGENT_HOOK_SCHEMA a session's hook is at. */
+const HOOK_SCHEMA_OPTION = '@ag_hook_schema';
+/**
+ * The guarded `pane-died` hook. Detach the client ONLY when the agent pane dies
+ * (so the blocking attach in runInTmux returns and the exit status can be read);
+ * a user split's death falls through to `kill-pane`, which — because the hook
+ * runs in the dead pane's context — closes that split in place. Single source of
+ * truth: both the spawn-wrap (exec.ts) and the daemon reconcile build the hook
+ * here, so the two can never drift.
+ */
+export function agentPaneDiedHook(sessionName, agentPane) {
+    return `if -F '#{==:#{hook_pane},${agentPane}}' 'detach-client -s =${sessionName}' 'kill-pane'`;
+}
+/** Stamp a session's hook-schema marker to the current version. */
+export async function markSessionHookSchema(name, socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    await runTmux({ socket: sock, args: ['set-option', '-t', name, HOOK_SCHEMA_OPTION, String(AGENT_HOOK_SCHEMA)], throwOnError: false }).catch(() => { });
+}
+/** Read a session's hook-schema marker; undefined when unset (pre-marker sessions). */
+async function readHookSchema(name, socket) {
+    const res = await runTmux({ socket, args: ['show-options', '-v', '-t', name, HOOK_SCHEMA_OPTION], throwOnError: false }).catch(() => null);
+    if (!res || res.code !== 0)
+        return undefined;
+    const v = res.stdout.trim();
+    return v === '' ? undefined : v;
+}
+/**
+ * Lowest pane id (`%N`) in a session — the first pane created, i.e. the agent
+ * pane, since user splits are always created later and get higher ids. Fallback
+ * for sessions whose SessionMeta (which records the agent pane) predates meta
+ * persistence. Undefined when the session has no panes (already torn down).
+ */
+async function lowestPaneId(name, socket) {
+    const res = await runTmux({ socket, args: ['list-panes', '-t', name, '-F', '#{pane_id}'], throwOnError: false }).catch(() => null);
+    if (!res || res.code !== 0)
+        return undefined;
+    const ids = res.stdout.split('\n').map(l => l.trim()).filter(id => /^%\d+$/.test(id));
+    if (!ids.length)
+        return undefined;
+    return ids.reduce((lo, id) => (parseInt(id.slice(1), 10) < parseInt(lo.slice(1), 10) ? id : lo));
+}
+/**
+ * Retrofit the current guarded `pane-died` hook onto every managed `agents run`
+ * session whose hook predates AGENT_HOOK_SCHEMA. Idempotent and NON-DESTRUCTIVE:
+ * it only `set-hook`s (never kills a pane or detaches a client), so a long-lived
+ * shared server started by a pre-fix binary — whose still-running sessions carry
+ * the old unconditional hook that kicked the user out of the whole view when they
+ * exited a split — self-heals in place, without waiting for those agents to exit
+ * or for the server to be recycled.
+ *
+ * The daemon calls this on a light interval. The per-session `@ag_hook_schema`
+ * marker makes steady-state a cheap no-op: a session already at the current
+ * schema is skipped. Only run-wrapped sessions (`ag-` prefix) are touched — an
+ * externally-created session on the socket keeps whatever hook it set.
+ */
+export async function reconcileSessionHooks(socket) {
+    const sock = socket ?? getDefaultSocketPath();
+    if (!fs.existsSync(sock))
+        return { scanned: 0, reconciled: 0 };
+    let sessions;
+    try {
+        sessions = await listSessions({ socket: sock });
+    }
+    catch {
+        return { scanned: 0, reconciled: 0 };
+    }
+    let reconciled = 0;
+    for (const s of sessions) {
+        if (!s.name.startsWith('ag-'))
+            continue; // only run-wrapped sessions
+        if (await readHookSchema(s.name, sock) === String(AGENT_HOOK_SCHEMA))
+            continue;
+        const agentPane = s.meta?.pane ?? await lowestPaneId(s.name, sock);
+        if (!agentPane)
+            continue;
+        await setSessionHook(s.name, 'pane-died', agentPaneDiedHook(s.name, agentPane), sock);
+        await markSessionHookSchema(s.name, sock);
+        reconciled++;
+    }
+    return { scanned: sessions.length, reconciled };
+}
 /**
  * List live sessions on the socket. Reconciles meta JSONs against tmux's view:
  *  - tmux session with no meta → returned without `meta` (external session)