@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/ssh-exec.js

@@ -18,6 +18,14 @@ import { getCacheDir } from './state.js';
  * smuggled in as part of a remote command, and `sshExec` additionally rejects a
  * leading `-` so it can never be parsed as an ssh argv flag.
  */
+/**
+ * ssh's own connection-layer failure code — the transport dropped or never came
+ * up, as opposed to the remote command choosing an exit status. Defined here,
+ * in the layer that owns the ssh invocation, and re-exported by
+ * `lib/hosts/reconnect.ts` as `SSH_CONN_FAILURE` so there is one constant for
+ * the concept rather than two that can drift apart.
+ */
+export const SSH_CONN_FAILURE_CODE = 255;
 export const SSH_TARGET_RE = /^[a-zA-Z0-9._-]+(@[a-zA-Z0-9._-]+)?$/;
 export function assertValidSshTarget(host) {
     if (host.startsWith('-') || !SSH_TARGET_RE.test(host)) {
@@ -314,20 +322,128 @@ export function sshExecRawStream(target, remoteCmd, opts) {
 export function sshReachable(target, timeoutMs = 10000) {
     return sshExec(target, 'true', { timeoutMs, multiplex: true }).code === 0;
 }
+/**
+ * The DEC private modes a full-screen remote app turns ON and, when it exits
+ * cleanly, turns back off itself. A remote agent TUI killed by a dropped link
+ * never gets to, so they stay enabled on the LOCAL terminal after ssh is gone:
+ * focus reporting (1004) and the mode/colour-scheme reports (996/997) then make
+ * the terminal emit answerback sequences at a shell that is not expecting them,
+ * which is the `^[[?997;1n ^[[I ^[[O` litter seen after a drop (RUSH-3125). Also
+ * resets bracketed paste (2004), the alternate screen (1049), mouse tracking
+ * (1000/1002/1003/1006), and re-shows the cursor (25) — every one of which a TUI
+ * leaves armed the same way.
+ */
+export const TERMINAL_MODE_RESET = '\x1b[?1004l\x1b[?996l\x1b[?997l\x1b[?2004l\x1b[?1049l'
+    + '\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?25h';
+/**
+ * Put the local terminal back the way ssh found it.
+ *
+ * Two independent kinds of state survive a hard ssh death, and BOTH have to be
+ * undone or the next thing the user sees is corrupted:
+ *
+ *  - **termios** (kernel side): `-tt` puts the tty in raw mode, so a killed ssh
+ *    leaves it with echo and line-editing off. `saved` is the `stty -g` snapshot
+ *    taken before the spawn; restoring it is exact, unlike guessing at `sane`.
+ *  - **DEC private modes** (terminal side): see {@link TERMINAL_MODE_RESET}.
+ *
+ * Then drain whatever the terminal already answered back into the input buffer.
+ * Without the drain those bytes are not merely cosmetic — they are still queued
+ * on the tty, so the NEXT attach hands them straight to the agent as if the user
+ * had typed them.
+ *
+ * Best-effort by construction: this runs while recovering from a failure, so a
+ * missing `stty`, a non-TTY stdin, or a closed stream must never turn a
+ * recoverable drop into a thrown error.
+ */
+export function restoreLocalTerminal(saved, opts) {
+    try {
+        if (saved)
+            spawnSync('stty', [saved], { stdio: ['inherit', 'ignore', 'ignore'] });
+    }
+    catch { /* no stty, or stdin is not a tty — nothing to restore */ }
+    try {
+        if (process.stdout.isTTY)
+            process.stdout.write(TERMINAL_MODE_RESET);
+    }
+    catch { /* stream closed */ }
+    try {
+        if (process.stdin.isTTY)
+            process.stdin.setRawMode?.(false);
+    }
+    catch { /* stdin not controllable in this context */ }
+    // The DRAIN is the one destructive step here, so it is opt-in per exit. See
+    // {@link sshStream} for why it must not run on a clean exit.
+    if (!opts.drainStdin)
+        return;
+    try {
+        // read() on a paused non-flowing stdin returns the buffered bytes and
+        // discards them; the loop clears a burst rather than one chunk.
+        if (process.stdin.isTTY) {
+            while (process.stdin.read() !== null) { /* discard */ }
+        }
+    }
+    catch { /* stdin not readable in this context */ }
+}
+/** `stty -g` snapshot of the local tty, or undefined when there is nothing to snapshot. */
+export function saveLocalTerminal() {
+    if (!process.stdin.isTTY)
+        return undefined;
+    try {
+        const r = spawnSync('stty', ['-g'], { stdio: ['inherit', 'pipe', 'ignore'], encoding: 'utf-8' });
+        const out = r.status === 0 ? r.stdout?.trim() : '';
+        return out || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the
  * local stdio wired straight through (`stdio: 'inherit'`), so output streams as
  * it is produced and — with `tty` — keystrokes reach a remote picker. Blocks
  * until the remote command exits and returns its exit code (255 is ssh's own
  * connection-layer failure; any other non-zero is the remote command's code).
+ *
+ * On a `tty` stream the local terminal state is snapshotted before the spawn and
+ * restored after it. ssh restores termios itself when it exits cleanly, so this
+ * is for the case that matters here: the link dying under a full-screen agent
+ * TUI, which leaves the tty raw and the TUI's DEC modes armed. Doing it HERE
+ * rather than in the reconnect loop means every caller that opens an interactive
+ * remote stream is covered, not just the one that noticed (RUSH-3125).
+ *
+ * **The stdin drain is gated on an ABNORMAL exit, and the distinction is not
+ * cosmetic.** Resetting termios and the DEC modes is idempotent — on a clean
+ * exit ssh and the remote TUI have already done it, so re-doing it changes
+ * nothing. Draining stdin is destructive: it discards whatever the user has
+ * typed ahead. On a clean exit those bytes are legitimate type-ahead the
+ * resuming shell should receive, and eating them would be a new bug in every
+ * caller of this function (`runInteractiveOnHost`, the remote-tmux attach in
+ * commands/go.ts, the remote secrets browse) rather than a fix. Only an
+ * abnormal exit — ssh killed by a signal (`status === null`) or its own
+ * connection-layer failure (255) — produces the answerback storm the drain
+ * exists to clear, because only then did the TUI die without sending its own
+ * mode resets.
  */
 export function sshStream(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
     const mux = opts.multiplex === false ? [] : controlOpts();
     const tty = opts.tty ? ['-tt'] : [];
     const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), ...tty, target, remoteCmd];
-    const res = spawnSync('ssh', args, { stdio: 'inherit' });
-    if (typeof res.status === 'number')
-        return res.status;
-    return 255; // spawn error / signal — treat as a connection-layer failure
+    const saved = opts.tty ? saveLocalTerminal() : undefined;
+    let abnormal = true; // a throw before/inside the spawn is abnormal by definition
+    try {
+        const res = spawnSync('ssh', args, { stdio: 'inherit' });
+        const code = typeof res.status === 'number' ? res.status : 255;
+        // Killed by a signal (no numeric status) or ssh's own connection-layer
+        // failure — the two shapes in which the remote TUI never got to reset the
+        // terminal. Any other code is ssh exiting normally with the remote's status.
+        abnormal = res.status === null || code === SSH_CONN_FAILURE_CODE;
+        return code;
+    }
+    finally {
+        // `finally`, because the abnormal exits are precisely the ones that leave
+        // the terminal wrecked — but the drain within it is gated (see the doc).
+        if (opts.tty)
+            restoreLocalTerminal(saved, { drainStdin: abnormal });
+    }
 }

package/dist/lib/startup/command-registry.d.ts

@@ -32,7 +32,9 @@ export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
  * `agents fleet apply` / `agents devices apply`. `beta` nested under
  * `agents setup beta` (RUSH-2981). `org` (the Prix-coupled account layer) was
  * removed; `agents auth` returned against Phoenix ID with `auth space` as the
- * team surface (RUSH-2581).
+ * team surface (RUSH-2581). `usage` was removed as a duplicate surface of
+ * `agents view`, which renders per-account usage with account, version, and
+ * auth state beside it (RUSH-3079).
  */
 export declare const RETIRED_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
 export declare function isKnownTopLevelCommand(name: string): boolean;

package/dist/lib/startup/command-registry.js

@@ -5,12 +5,12 @@ const LOADED_COMMAND_NAMES = [
     'routines', 'monitors', 'projects', 'run', 'open', 'reconnect', 'fork', 'config',
     'models', 'modes', 'trash', 'restore', 'doctor',
     'route', 'harness', 'harnesses', 'secrets', 'menubar', 'sync',
-    'refresh-rules', 'factory', 'usage', 'insights', 'perf',
+    'refresh-rules', 'factory', 'insights', 'trace', 'perf',
     'pty', 'tmux', 'watchdog', 'browser', 'computer', 'logs', 'events',
     'ssh', 'devices', 'fleet', 'repos', 'repo', 'setup', 'uninstall', 'upgrade', 'sessions',
     'teams', 'cloud', 'message', 'send', 'notify', 'feed',
     'mailboxes', 'mailbox', 'artifacts', 'webhooks',
-    'humans', 'daemon',
+    'humans', 'daemon', 'traces',
 ];
 const INLINE_COMMAND_NAMES = [
     'perms', 'exec', 'jobs', 'cron', 'check', 'resources', 'hq', '_internal',
@@ -52,12 +52,15 @@ export const KNOWN_TOP_LEVEL_COMMANDS = new Set([
  * `agents fleet apply` / `agents devices apply`. `beta` nested under
  * `agents setup beta` (RUSH-2981). `org` (the Prix-coupled account layer) was
  * removed; `agents auth` returned against Phoenix ID with `auth space` as the
- * team surface (RUSH-2581).
+ * team surface (RUSH-2581). `usage` was removed as a duplicate surface of
+ * `agents view`, which renders per-account usage with account, version, and
+ * auth state beside it (RUSH-3079).
  */
 export const RETIRED_TOP_LEVEL_COMMANDS = new Set([
     'webhook',
     'org',
     'serve',
+    'usage',
     'login',
     'logout',
     'budget',

package/dist/lib/startup/dev-build.js

@@ -22,12 +22,12 @@ import * as path from 'path';
  * looking for `.git`.
  *
  * That package root does not always hold `.git` itself, though — this repo is a
- * monorepo where the package lives at `apps/cli` and `.git` sits one level
+ * monorepo where the package lives at `cli` and `.git` sits one level
  * higher, at the true repo root. `.git` is therefore searched for in a SMALL,
  * bounded set of ancestors above the package root (see
  * `DEV_BUILD_GIT_ANCESTOR_DEPTH`), not just the package root itself — a source
- * checkout run via tsx/ts-node from `apps/cli/src/` or built to
- * `apps/cli/dist/` must still be recognized. The bound keeps this well short of
+ * checkout run via tsx/ts-node from `cli/src/` or built to
+ * `cli/dist/` must still be recognized. The bound keeps this well short of
  * an unrelated ancestor repo: a real Homebrew npm-global install's package root
  * sits 3 directories below `/opt/homebrew` (`lib/node_modules/@phnx-labs/…`),
  * so a depth of 2 finds this repo's `.git` while staying short of Homebrew's.

package/dist/lib/state.d.ts

@@ -31,7 +31,7 @@ export declare function getHumansFilePath(): string;
  * file against `schema/agents-yaml.schema.json`. Exported so
  * `lib/devices/config-migration.ts` rewrites a device doc with the same header.
  */
-export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json\n\n";
+export declare const META_HEADER = "# agents-cli metadata\n# Auto-generated - do not edit manually\n# https://github.com/phnx-labs/agents-cli\n# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json\n\n";
 /** Root of the system data directory (~/.agents/.system/). */
 export declare function getAgentsDir(): string;
 /** Root of the system data directory (~/.agents/.system/). */
@@ -258,7 +258,7 @@ export declare function getTeamsAgentsDir(): string;
 export declare function getTeamsRegistryPath(): string;
 /** Path to the device registry — SSH device profiles with platform/auth metadata. Durable runtime, per-machine (host list + addresses are NOT pulled by `agents repo push`). */
 export declare function getDevicesRegistryPath(): string;
-/** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
+/** Path to the LEGACY per-machine device ignore-list — superseded by the tracked `fleet.ignored` list in central agents.yaml (RUSH-3062); only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export declare function getDevicesIgnoredPath(): string;
 /** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the per-device doc `config:` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export declare function getDevicesAutoLaunchPath(): string;

package/dist/lib/state.js

@@ -168,7 +168,7 @@ const USER_PROMPTCUTS_FILE = path.join(USER_AGENTS_DIR, 'hooks', 'promptcuts.yam
 export const META_HEADER = `# agents-cli metadata
 # Auto-generated - do not edit manually
 # https://github.com/phnx-labs/agents-cli
-# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/apps/cli/schema/agents-yaml.schema.json
+# yaml-language-server: $schema=https://raw.githubusercontent.com/phnx-labs/agents-cli/main/cli/schema/agents-yaml.schema.json
 
 `;
 // ─── Root getters ─────────────────────────────────────────────────────────────
@@ -563,7 +563,9 @@ export function getTeamsAgentsDir() { return TEAMS_AGENTS_DIR; }
 /** Path to the team registry — list of named teams with timestamps. Durable runtime, per-machine. */
 export function getTeamsRegistryPath() { return path.join(HISTORY_DIR, 'teams', 'registry.json'); }
 /**
- * The devices dir (registry + ignore-list live here). Read at CALL time so a
+ * The devices dir (the registry lives here; the ignore-list moved to the
+ * tracked central agents.yaml as `fleet.ignored` — RUSH-3062). Read at CALL
+ * time so a
  * test can redirect it to a temp dir via AGENTS_DEVICES_DIR without racing the
  * module-load capture of HISTORY_DIR — mirrors the AGENTS_EVENTS_PATH /
  * AGENTS_SECRETS_AGENT_DIR test-isolation escape hatches. Never set in
@@ -575,7 +577,7 @@ function getDevicesDir() {
 }
 /** Path to the device registry — SSH device profiles with platform/auth metadata. Durable runtime, per-machine (host list + addresses are NOT pulled by `agents repo push`). */
 export function getDevicesRegistryPath() { return path.join(getDevicesDir(), 'registry.json'); }
-/** Path to the device ignore-list — tailscale node names the user dismissed, so auto-discovery never re-suggests them. Per-machine, same dir as the registry. */
+/** Path to the LEGACY per-machine device ignore-list — superseded by the tracked `fleet.ignored` list in central agents.yaml (RUSH-3062); only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export function getDevicesIgnoredPath() { return path.join(getDevicesDir(), 'ignored.json'); }
 /** Path to the LEGACY device auto-launch preference file — which registered devices are eligible/preferred for the ext's auto-host selection. Superseded by the per-device doc `config:` block; only lib/devices/config-migration.ts still reads it (to fold + remove it). */
 export function getDevicesAutoLaunchPath() { return path.join(getDevicesDir(), 'auto-launch.json'); }
@@ -893,7 +895,6 @@ const META_KEY_SCOPE = {
     actors: 'central',
     seededPresets: 'central',
     hooks: 'central',
-    browser: 'central',
     config: 'central',
     hosts: 'central',
     fleet: 'central',
@@ -908,7 +909,12 @@ const META_KEY_SCOPE = {
  * in central is stale and must be migrated out). A key NOT listed here — e.g. one
  * a newer CLI version added — is preserved verbatim, never dropped + synced away.
  */
-const KNOWN_META_KEYS = new Set(Object.keys(META_KEY_SCOPE));
+const KNOWN_META_KEYS = new Set([
+    ...Object.keys(META_KEY_SCOPE),
+    // Removed browser-profile store. Kept only as a serializer tombstone so the
+    // first registry read can migrate it into this device's file and delete it.
+    'browser',
+]);
 /**
  * Serialize the central (synced) meta to `agents.yaml` WITHOUT destroying the
  * hand-written comments in the committed file.

package/dist/lib/subagents-registry.js

@@ -27,7 +27,7 @@
  *
  * The per-agent `transform`/metadata parsers are the escape hatch: they live in
  * `subagents.ts` and are referenced by the table, so the generic engine has zero
- * per-agent branches. See the integration tiers in `docs/subagents.md`.
+ * per-agent branches. See `docs/orchestration.md`.
  */
 import * as fs from 'fs';
 import * as path from 'path';

package/dist/lib/teams/agents.js

@@ -1451,6 +1451,15 @@ export class AgentManager {
         }
         this.defaultMode = resolvedDefaultMode;
         this.initPromise = this.doInitialize();
+        // Mark the deferred rejection as observed. Construction fires init
+        // fire-and-forget; every public method still surfaces a failed init at its
+        // own `await this.initialize()` (the same promise rejects for each new
+        // awaiter). Without this, an init that loses a race with its directory
+        // being removed — measured twice as an unhandled
+        // `ENOENT mkdir /tmp/agents-retention-*` that failed a fully-green suite
+        // (exit 1 with 12k tests passed) and blocked release attestation — crashes
+        // the process instead of failing the caller that actually cares.
+        this.initPromise.catch(() => { });
     }
     async initialize() {
         if (!this.initPromise) {

package/dist/lib/terminal/index.d.ts

@@ -4,7 +4,7 @@
  *
  * Public entry point. Callers typically use `openSurfaces` (a batch with a
  * layout policy) or `openSurface` (a single request), and `availableBackends` /
- * `detectCurrentBackend` to pick a target. See docs/terminal-engine.md.
+ * `detectCurrentBackend` to pick a target. See docs/interfaces.md.
  */
 export type { Backend, SplitDirection, Layout, EngineContext, LaunchSpec, LaunchRequest, LaunchResult, TerminalBackend, } from './types.js';
 export { currentContext } from './types.js';

package/dist/lib/terminal/inject.d.ts

@@ -98,12 +98,31 @@ export interface InjectOptions {
 export interface InjectResult {
     ok: boolean;
     backend: InjectBackend;
+    /**
+     * Delivery is CONFIRMED to have reached the running agent, not merely dispatched.
+     *
+     * For tmux / iterm / ghostty / pty, `ok` already means delivered: `tmux
+     * send-keys` errors on a missing pane, `osascript write text` errors on a bad
+     * session id, and a pty write errors if the sidecar can't reach the fd — so a
+     * successful transport IS the confirmation. For **vscodium**, `ok` only means the
+     * editor CLI accepted the `--open-url` hand-off; whether the swarm-ext extension
+     * actually parsed the verb and typed anything is unknown from the CLI side (the
+     * ext must ack — RUSH follow-up). So vscodium is delivered-but-UNCONFIRMED, and
+     * the watchdog must not book a nudge as landed on that alone.
+     */
+    confirmed: boolean;
     /** Discrete writes delivered: 2 for the Ink-safe text+Enter split, 1 when combined or enter=false. */
     writes: number;
     /** For the tmux / AppleScript backends (or any dryRun), the spec(s) that ran / would run. */
     specs?: LaunchSpec[];
     error?: string;
 }
+/**
+ * Whether a successful transport on this backend CONFIRMS delivery to the agent.
+ * Everything but vscodium self-confirms (see InjectResult.confirmed); vscodium's
+ * `--open-url` is fire-and-forget until the swarm-ext extension acks the verb.
+ */
+export declare function backendConfirmsDelivery(backend: InjectBackend): boolean;
 /**
  * argv for `tmux send-keys` targeting a pane by id. Starts with `tmux` (like the
  * engine's `tmuxTabArgv`) so the same transport runs it locally or over SSH. The

package/dist/lib/terminal/inject.js

@@ -46,6 +46,14 @@ import { appleScriptStr } from './quote.js';
 import { runSpec } from './transport.js';
 import { itermBackend, ghosttyBackend } from './backends/index.js';
 import { currentContext } from './types.js';
+/**
+ * Whether a successful transport on this backend CONFIRMS delivery to the agent.
+ * Everything but vscodium self-confirms (see InjectResult.confirmed); vscodium's
+ * `--open-url` is fire-and-forget until the swarm-ext extension acks the verb.
+ */
+export function backendConfirmsDelivery(backend) {
+    return backend !== 'vscodium';
+}
 /** Carriage return — what Enter delivers into a raw PTY/tmux byte stream. */
 const CR = '\r';
 // --- tmux -------------------------------------------------------------------
@@ -180,22 +188,23 @@ export function vscodiumInjectSpec(target, text, opts) {
 // --- pty --------------------------------------------------------------------
 async function injectPty(target, text, o) {
     if (o.host && o.host !== 'local') {
-        return { ok: false, backend: 'pty', writes: 0, error: 'pty injection is local-only (the sidecar is not a remote surface)' };
+        return { ok: false, confirmed: false, backend: 'pty', writes: 0, error: 'pty injection is local-only (the sidecar is not a remote surface)' };
     }
     // Same Ink-safe split as tmux: text write, then a separate CR write.
     const writes = o.enter && o.combined ? [text + CR] : o.enter ? [text, CR] : [text];
     if (o.dryRun)
-        return { ok: true, backend: 'pty', writes: writes.length };
+        return { ok: true, confirmed: true, backend: 'pty', writes: writes.length };
     try {
         for (const input of writes) {
             const res = await ptyRequest('write', target.id, { input });
             if (!res.ok)
-                return { ok: false, backend: 'pty', writes: 0, error: res.error ?? 'pty write failed' };
+                return { ok: false, confirmed: false, backend: 'pty', writes: 0, error: res.error ?? 'pty write failed' };
         }
-        return { ok: true, backend: 'pty', writes: writes.length };
+        // A successful sidecar write reached the fd — real delivery.
+        return { ok: true, confirmed: true, backend: 'pty', writes: writes.length };
     }
     catch (err) {
-        return { ok: false, backend: 'pty', writes: 0, error: err instanceof Error ? err.message : String(err) };
+        return { ok: false, confirmed: false, backend: 'pty', writes: 0, error: err instanceof Error ? err.message : String(err) };
     }
 }
 // --- public entry -----------------------------------------------------------
@@ -225,8 +234,9 @@ export async function injectIntoTerminal(target, text, opts = {}) {
         : target.backend === 'ghostty'
             ? enter ? 2 : 1
             : enter && !combined ? 2 : 1;
+    const confirmed = backendConfirmsDelivery(target.backend);
     if (opts.dryRun)
-        return { ok: true, backend: target.backend, writes, specs };
+        return { ok: true, confirmed, backend: target.backend, writes, specs };
     // AppleScript backends: guard on the backend's own availability, but only for a
     // LOCAL run (a remote host is assumed to have the app — its ssh leg reports failure).
     if (target.backend === 'iterm' || target.backend === 'ghostty') {
@@ -234,14 +244,14 @@ export async function injectIntoTerminal(target, text, opts = {}) {
             const backend = target.backend === 'iterm' ? itermBackend : ghosttyBackend;
             const ctx = opts.ctx ?? currentContext();
             if (!backend.isAvailable(ctx)) {
-                return { ok: false, backend: target.backend, writes: 0, specs, error: `${backend.label} is not available here (platform ${ctx.platform})` };
+                return { ok: false, confirmed: false, backend: target.backend, writes: 0, specs, error: `${backend.label} is not available here (platform ${ctx.platform})` };
             }
         }
     }
     for (const spec of specs) {
         const res = await runSpec(spec, opts.host, opts.resolveHost);
         if (!res.ok)
-            return { ok: false, backend: target.backend, writes: 0, specs, error: res.error };
+            return { ok: false, confirmed: false, backend: target.backend, writes: 0, specs, error: res.error };
     }
-    return { ok: true, backend: target.backend, writes, specs };
+    return { ok: true, confirmed, backend: target.backend, writes, specs };
 }

package/dist/lib/terminal/types.d.ts

@@ -5,7 +5,7 @@
  * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
  * machine or a remote host. This is distinct from cloud providers
  * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
- * is attended and live. See docs/terminal-engine.md.
+ * is attended and live. See docs/interfaces.md.
  */
 /** An interactive terminal backend the engine can drive. */
 export type Backend = 'iterm' | 'ghostty' | 'tmux' | 'vscodium-agent' | 'terminal';

package/dist/lib/terminal/types.js

@@ -5,7 +5,7 @@
  * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
  * machine or a remote host. This is distinct from cloud providers
  * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
- * is attended and live. See docs/terminal-engine.md.
+ * is attended and live. See docs/interfaces.md.
  */
 /** Snapshot the live process context. */
 export function currentContext() {

package/dist/lib/tmux/orphan-reap.js

@@ -172,7 +172,7 @@ export const DETACHED_HELPER_RULES = [CLAUDE_BG_DAEMON];
 export function isProtectedAgentsService(args) {
     return /\b__daemon-run\b/.test(args)
         || /\bsecrets\s+_agent-run\b/.test(args)
-        || /\bMenubarHelper\b/.test(args)
+        || /\bAGI Menu\b/.test(args)
         || /\bAgents CLI\.app\b/.test(args);
 }
 /** Is this pid currently running? Signal-0 probe, matching `platform/process.ts`. */

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

@@ -9,6 +9,22 @@
  * pure provenance — `listSessions()` always reconciles them against
  * `tmux list-sessions` and prunes stale entries on the fly.
  */
+/**
+ * Ten times tmux's 2,000-line default, while keeping per-pane memory bounded:
+ * history storage scales with pane width, so a 200-column pane retains at most
+ * four million grid cells rather than an unbounded agent transcript.
+ */
+export declare const AGENTS_TMUX_HISTORY_LIMIT = 20000;
+/**
+ * Bump when the generated startup config changes, so an ALREADY-RUNNING server
+ * picks the new settings up. tmux reads `-f` only when it actually starts a
+ * server: a second `new-session -f other.conf` against a live server exits 0
+ * and silently applies nothing (verified against tmux 3.4). Since agents-cli
+ * uses one long-lived shared socket, the normal state at upgrade is a running
+ * server — so without this reconcile every existing machine would get none of
+ * these defaults, silently. Same shape as AGENT_HOOK_SCHEMA below.
+ */
+export declare const AGENTS_TMUX_CONFIG_SCHEMA = 1;
 /** Provenance written alongside each live tmux session. */
 export interface SessionMeta {
     name: string;
@@ -62,6 +78,8 @@ export interface ListedSession {
     attached: boolean;
     meta?: SessionMeta;
 }
+/** Build the atomic server-configuration + session-creation command. */
+export declare function buildCreateSessionArgs(opts: CreateSessionOptions, startupConfig: string): string[];
 export declare class TmuxSessionError extends Error {
     readonly cause?: unknown | undefined;
     constructor(message: string, cause?: unknown | undefined);
@@ -213,21 +231,36 @@ export declare function setSessionHook(name: string, hook: string, command: stri
  *        variant could stall the hook on a loaded CI runner, letting the dead
  *        split survive until the test's wait timeout expired (flake in CI shard
  *        3: pane-guarded pane-died hook / user split exit).
+ *   v6 — the agent-pane branch is now `session_attached`-aware: with a client
+ *        attached it `detach-client`s (the interactive path, so runInTmux's
+ *        attach returns and reads the exit status, EXEC-23b unchanged); with NO
+ *        client it `kill-session`s outright. A `remain-on-exit` pane with no
+ *        attach client to reap it otherwise lingers as a dead husk until the
+ *        daemon's periodic `reapDeadTmuxPanes` sweep — so a run whose terminal
+ *        was closed, or a `/exit` after the user detached, left an idle-looking
+ *        dead session on the socket. Killing it the instant the agent exits is
+ *        the "one close tears down every layer" contract (#5a).
  */
-export declare const AGENT_HOOK_SCHEMA = 5;
+export declare const AGENT_HOOK_SCHEMA = 6;
 /**
- * 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 runs the else-branch, closing just that split. The
- * else-branch goes through `run-shell -b -C` with an explicit `-t #{hook_pane}`
- * target: tmux format-expands the command at fire time and executes it inside
- * the server command queue in the background, so the event pane is always the
- * one killed without launching a second tmux client against the same socket and
- * without stalling the hook on a loaded runner. A bare `kill-pane` relied on
- * the hook context supplying a "current pane", while an external self-client
- * could race the server under load. Single source of truth: both the
- * spawn-wrap (exec.ts) and the daemon reconcile build the hook here, so the
- * two can never drift.
+ * The guarded `pane-died` hook. When the AGENT pane dies, tear the whole session
+ * down — but HOW depends on whether a client is attached:
+ *   - attached (`#{session_attached}`): `detach-client` so the blocking attach in
+ *     runInTmux returns and `resolveAfterAttach` reads the exit status off the
+ *     still-`remain-on-exit` dead pane, then kills the session (EXEC-23b, unchanged);
+ *   - no client: `kill-session` outright. Without this the dead pane sits under
+ *     `remain-on-exit` as an idle-looking husk until the daemon's periodic
+ *     `reapDeadTmuxPanes` sweep — the "second exit" / orphaned-idle session bug
+ *     when a wrapped agent exits with nobody attached (a closed terminal, or a
+ *     `/exit` after the user detached). `detach-client` on an unattached session
+ *     is a no-op, so the old hook left the husk; `kill-session` ends it at once.
+ * A user split's death still runs the else-branch, closing just that split via
+ * `run-shell -b -C` with an explicit `-t #{hook_pane}` target: tmux format-expands
+ * the command at fire time and executes it inside the server command queue in the
+ * background, so the event pane is always the one killed without launching a second
+ * tmux client against the same socket and without stalling the hook on a loaded
+ * runner. 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. */