@phnx-labs/agents-cli 1.20.41 → 1.20.42

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 1.20.42
+
+- **Fix: exiting a split pane inside an interactive `ag run` session kicked you out of tmux entirely.** When you split the window of an interactive agent session (`ag run claude`) with Ctrl-b `"`/`%` and then `exit`ed *your* split, the whole tmux client detached and dumped you back to the parent shell — even though the agent was still running in the other pane. Cause: `runInTmux` installed a session-wide `pane-died` hook (`detach-client`) meant to fire only when the AGENT pane exits (so the attach returns and the exit status is read), but with no `#{hook_pane}` guard it fired for *any* pane's death. The hook is now scoped to the agent pane; a user split that exits is closed in place (`kill-pane`, no lingering dead husk) and the agent keeps running full-window. Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/tmux/session.test.ts`.
+- **Every secret-value read is now audited, not just the ones that flowed through the resolver.** `agents events --module secrets` (or `--event secrets.get`) is meant to show "every secret accessed or revealed", but several paths read plaintext values without going through `readAndResolveBundleEnv` (the only place that emitted `secrets.get`), so they were invisible: `secrets push` (which reads the whole bundle to upload it — the most sensitive silent read), `secrets view --reveal`, the raw `secrets get <item>`, `secrets set <item>` (a raw write, no `secrets.set`), and the *initiating* side of `secrets exec --host` / `run --secrets bundle@host` (only the remote host logged it). Each now emits with a `source` telling you HOW it was read — `keychain`, `agent` (served from the unlocked broker), `reveal`, `raw-item`, `sync-push`, or `remote` (with the target `host`) — alongside the bundle, caller, keyCount, and OS-user/host/transport. The resolved **value is never written to the log**, only names and counts. All `secrets.*` events are now tagged `module: 'secrets'` so `--module secrets` actually surfaces the value reads (previously it matched only the coarse command events). Note: the event log has a 7-day retention, so export what you need for long-term records. Source: `src/lib/secrets/bundles.ts`, `src/lib/secrets/sync.ts`, `src/lib/secrets/remote.ts`, `src/commands/secrets.ts`, `docs/06-observability.md`.
+- **Fix: `sessions --active` showed the SAME preview + topic for every co-located session.** Multiple Claude sessions in one cwd (e.g. several editor tabs, or two worktree siblings) all rendered identical activity — they looked like duplicate cards. `findClaudeSessionFile` fell back to the newest `.jsonl` in the cwd whenever a session's `<id>.jsonl` wasn't found, so every distinct session collapsed onto ONE file's preview/topic. The stale-id trigger: an editor caches the launch uuid in `live-terminals.json`, but Claude rotates its transcript uuid on resume/compact, so the cached id no longer matches any file. Now the terminal path resolves each tab's EXACT id from the pid registry (mirroring the headless path), the newest-file fallback is gated to the no-id case (`pickSessionFile`), and an unresolvable file reads as `idle` rather than `running`. Source: `apps/cli/src/lib/session/active.ts`.
+- **Fix: one malformed Kimi session blanked the WHOLE `agents sessions` listing.** A Kimi `state.json` with neither `createdAt` nor `updatedAt` made `readKimiMeta` return an `undefined` timestamp, which binds `NULL` into the `timestamp TEXT NOT NULL` column and aborts the entire batch index — so a single bad session took down the listing for every session, not just itself. Two layers: `readKimiMeta` now coerces the timestamp to never-null, falling back to the `state.json` mtime (matching how the listing already ranks Kimi via `last_activity`, like every other parser); and `upsertSessionsBatch` wraps each row in a per-row guard so a future constraint-violating row skips itself (ledger deliberately not stamped, so the next scan re-tries it) instead of rolling back the whole batch. Source: `apps/cli/src/lib/session/discover.ts`, `apps/cli/src/lib/session/db.ts`.
+
 ## 1.20.41
 
 - **NEW: `agents sessions focus [id]`** — one command to get back to a session, however it's reachable. It **attaches** a live session in place (tmux `switch-client`/`attach-session`, a remote tmux over `ssh -tt`, or a Ghostty tab — joining the live process without forking); where there's **no live terminal to attach**, it **opens a new tab and resumes** the session — locally, or on the remote peer over SSH (`runOnPeer`, so the peer resolves the version-pinned binary). No id opens the rich live-session picker (this-machine first). Reuses the live-session detection and the terminal launch engine (`openSurfaces`), and folds `go`'s attach paths in. Source: `src/commands/focus.ts`, `src/commands/go.ts`.

package/dist/commands/computer-actions.js

@@ -200,7 +200,7 @@ function warnIfNotFrontmost(res) {
     }
 }
 function reportMissingHelper() {
-    console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
+    console.error('helper not built. Run: ./native/computer-mac/scripts/build.sh debug');
     process.exit(1);
 }
 // Open a client, run fn, always close. Fails fast if no helper is present.

package/dist/commands/computer.d.ts

@@ -22,9 +22,9 @@ export declare function detectImageFormat(buf: Buffer): '.png' | '.jpg' | null;
  * Make the screenshot filename honest about its bytes. The two helper backends
  * encode DIFFERENT formats and neither re-encodes to match the requested name:
  * the macOS helper (ScreenCaptureKit) returns JPEG
- * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * (native/computer-mac/Sources/ComputerHelper/Screenshot.swift:207,212),
  * the Windows helper returns PNG
- * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * (native/computer-win/Screenshot.cs:33). So a fixed default extension
  * cannot be correct for both — the only honest path is to sniff the real format
  * and swap the extension to match. Pure so it's unit-testable.
  *

package/dist/commands/computer.js

@@ -53,9 +53,9 @@ export function detectImageFormat(buf) {
  * Make the screenshot filename honest about its bytes. The two helper backends
  * encode DIFFERENT formats and neither re-encodes to match the requested name:
  * the macOS helper (ScreenCaptureKit) returns JPEG
- * (packages/computer-helper/Sources/ComputerHelper/Screenshot.swift:207,212),
+ * (native/computer-mac/Sources/ComputerHelper/Screenshot.swift:207,212),
  * the Windows helper returns PNG
- * (packages/computer-helper-win/Screenshot.cs:33). So a fixed default extension
+ * (native/computer-win/Screenshot.cs:33). So a fixed default extension
  * cannot be correct for both — the only honest path is to sniff the real format
  * and swap the extension to match. Pure so it's unit-testable.
  *
@@ -354,7 +354,7 @@ function registerSetupCommand(program) {
         }
         const srcApp = resolveHelperApp();
         if (!srcApp || !fs.existsSync(srcApp)) {
-            console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
+            console.error('helper not built. Run: ./native/computer-mac/scripts/build.sh debug');
             process.exit(1);
         }
         const home = os.homedir();
@@ -392,7 +392,7 @@ function registerSetupCommand(program) {
         }
         catch {
             console.error('codesign verify FAILED. The destination .app is unsigned or its signature was stripped.');
-            console.error('rebuild the helper with a Developer ID cert: ./packages/computer-helper/scripts/build.sh release');
+            console.error('rebuild the helper with a Developer ID cert: ./native/computer-mac/scripts/build.sh release');
             process.exit(1);
         }
         // 3. Ensure socket + log parent dirs exist.

package/dist/commands/exec.js

@@ -219,6 +219,7 @@ export function registerRunCommand(program) {
         .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. Pair with a prompt to continue headlessly.')
         .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
         .option('--verbose', 'Show detailed execution logs')
+        .option('--raw', 'Interactive runs on macOS/Linux launch inside a shared tmux session (for %pane addressing + re-attach). Pass --raw to spawn the agent directly instead. Also disabled by AGENTS_NO_TMUX=1.')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
@@ -1063,6 +1064,7 @@ export function registerRunCommand(program) {
             sessionId: resumeSessionId ?? options.sessionId,
             resume: resumeNative,
             verbose: options.verbose,
+            raw: options.raw,
             timeout: options.timeout,
             env,
             toolsRestrict: workflowToolsRestrict,

package/dist/commands/go.js

@@ -122,9 +122,14 @@ export function describeWhere(s, self) {
     const remote = s.machine && s.machine !== self ? s.machine : undefined;
     const mux = s.provenance?.mux;
     if (mux?.kind === 'tmux' && mux.pane) {
+        // When the renderer has resolved the current viewer, fold it into the label
+        // so `focus` reports "tmux %3 (viewing in codium tab 2)" / "(detached)".
+        const view = s.viewingIn
+            ? ` (viewing in ${s.viewingIn.app}${s.viewingIn.tab != null ? ` tab ${s.viewingIn.tab}` : ''})`
+            : '';
         return remote
             ? { label: `tmux ${mux.pane} on ${remote}`, action: `ssh + attach on ${remote}` }
-            : { label: `tmux ${mux.pane}`, action: 'attach its tmux' };
+            : { label: `tmux ${mux.pane}${view}`, action: 'attach its tmux' };
     }
     if (!remote && s.host === 'ghostty')
         return { label: 'Ghostty', action: 'focus its Ghostty tab' };

package/dist/commands/secrets.js

@@ -18,6 +18,7 @@ import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainI
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, installSecretsAgentService, runAgentLoadFromStdin, runSecretsAgent, secretsAgentServiceInstalled, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
 import { parseDuration } from '../lib/hooks/cache.js';
+import { emit } from '../lib/events.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
@@ -658,6 +659,26 @@ export function registerSecretsCommands(program) {
                 catch {
                     // Fall through to masked output on cancellation / batch failure.
                 }
+                // Revealing plaintext bypasses readAndResolveBundleEnv (the usual
+                // audit chokepoint), so emit here — a `--reveal` exposes real values
+                // and must show up in `agents events --module secrets`. Count both the
+                // keychain values actually decrypted AND the inline literals (which
+                // `--reveal` always prints, even for a literal-only bundle with no
+                // keychain refs — see the entries loop below). Values are never
+                // included, only how many keys were exposed. Emit only when something
+                // was actually shown (a cancelled Touch ID + no literals reveals none).
+                const literalCount = entries.filter((e) => e.kind === 'literal').length;
+                const exposedCount = revealedValues.size + literalCount;
+                if (exposedCount > 0) {
+                    emit('secrets.get', {
+                        module: 'secrets',
+                        bundle: bundle.name,
+                        caller: 'view --reveal',
+                        source: 'reveal',
+                        status: 'success',
+                        keyCount: exposedCount,
+                    });
+                }
             }
             for (const e of entries) {
                 if (e.kind === 'keychain') {
@@ -703,6 +724,9 @@ export function registerSecretsCommands(program) {
             // so `$(agents secrets get NAME)` captures it cleanly); diagnostics go
             // to stderr so they never pollute the captured value.
             const value = getKeychainToken(item);
+            // Raw item reads bypass readAndResolveBundleEnv, so audit here too.
+            // `item` is the keychain service name, never the value.
+            emit('secrets.get', { module: 'secrets', item, source: 'raw-item', status: 'success' });
             process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
         }
         catch {
@@ -734,6 +758,8 @@ export function registerSecretsCommands(program) {
             // so `agents secrets get` can read them back without a password sheet;
             // on Linux it goes through secret-tool / encrypted-file fallback.
             setKeychainToken(item, value);
+            // Raw item writes bypass writeBundle (the usual secrets.set chokepoint).
+            emit('secrets.set', { module: 'secrets', item, source: 'raw-item' });
             console.error(chalk.green(`Stored keychain item '${item}'.`));
         }
         catch (err) {

package/dist/commands/sessions.js

@@ -18,7 +18,8 @@ import { discoverArtifacts, readArtifact, resolveArtifact } from '../lib/session
 import { looksLikePath, toComparablePath, homeDir, needsWindowsShell, findExecutable } from '../lib/platform/index.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
-import { mapPanesToTargets } from '../lib/tmux/session.js';
+import { mapPanesToTargets, listClients } from '../lib/tmux/session.js';
+import { resolveViewingIn } from '../lib/session/viewing-in.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.js';
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
@@ -314,6 +315,16 @@ function locatorBadge(s) {
         parts.push(chalk.red('ssh'));
     if (p?.mux?.kind === 'tmux' && (s.tmuxTarget || p.mux.pane)) {
         parts.push(chalk.green(s.tmuxTarget ?? p.mux.pane));
+        // For a tmux-hosted session, say which app+tab is looking at it right now
+        // (or that it's running detached). Only meaningful for tmux (the pane is the
+        // durable handle; the viewer is transient).
+        if (s.viewingIn) {
+            const tab = s.viewingIn.tab != null ? ` tab ${s.viewingIn.tab}` : '';
+            parts.push(chalk.gray(`viewing in ${s.viewingIn.app}${tab}`));
+        }
+        else {
+            parts.push(chalk.gray('detached'));
+        }
     }
     else if (p?.mux?.kind === 'screen') {
         parts.push(chalk.green('screen'));
@@ -617,20 +628,27 @@ async function enrichLocalLocators(local) {
         }
     }
     catch { /* non-fatal */ }
-    // tmux attach targets, one batched query per distinct socket.
+    // tmux attach targets + "viewing in <app> tab N", one batched query per socket.
     try {
         const tmux = local.filter(s => s.provenance?.mux?.kind === 'tmux' && s.provenance.mux.pane);
-        const sockets = new Set(tmux.map(s => s.provenance.mux.socket));
-        for (const socket of sockets) {
-            const paneMap = await mapPanesToTargets(socket);
-            if (paneMap.size === 0)
-                continue;
-            for (const s of tmux) {
-                if (s.provenance.mux.socket !== socket)
+        if (tmux.length > 0) {
+            // One Ghostty enumeration shared across every socket's viewing-in resolve
+            // (a tmux client can be attached from a Ghostty tab).
+            const surfaces = await enumerateGhosttyTabs();
+            const sockets = new Set(tmux.map(s => s.provenance.mux.socket));
+            for (const socket of sockets) {
+                const paneMap = await mapPanesToTargets(socket);
+                if (paneMap.size === 0)
                     continue;
-                const target = paneMap.get(s.provenance.mux.pane);
-                if (target)
-                    s.tmuxTarget = target;
+                const clients = await listClients(socket);
+                for (const s of tmux) {
+                    if (s.provenance.mux.socket !== socket)
+                        continue;
+                    const target = paneMap.get(s.provenance.mux.pane);
+                    if (target)
+                        s.tmuxTarget = target;
+                    s.viewingIn = await resolveViewingIn(s, clients, { paneToTarget: paneMap, ghosttySurfaces: surfaces });
+                }
             }
         }
     }

package/dist/lib/computer-rpc.js

@@ -168,8 +168,8 @@ export function writeComputerPeers(allowedExecPaths) {
 export function resolveHelperExec() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        // Local build (running from the agents-cli checkout).
-        path.resolve(here, '..', '..', 'packages', 'computer-helper', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
+        // Local build (running from the agents-cli checkout). apps/cli/dist/lib -> repo root (4 up) -> native/computer-mac.
+        path.resolve(here, '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
         // Bundled with the npm package (later: CDN download lands here).
         path.resolve(here, '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
     ];
@@ -218,7 +218,7 @@ export function openComputerClient() {
     }
     const helperExec = resolveHelperExec();
     if (!helperExec) {
-        throw new Error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
+        throw new Error('helper not built. Run: ./native/computer-mac/scripts/build.sh debug');
     }
     return new StdioClient(helperExec);
 }

package/dist/lib/exec.d.ts

@@ -109,6 +109,12 @@ export interface ExecOptions {
     mcpConfigPath?: string;
     /** Raw args captured after `--` on the command line, forwarded verbatim to the underlying agent CLI. */
     passthroughArgs?: string[];
+    /**
+     * Escape hatch for the interactive tmux spawn-wrap (see shouldWrapInTmux):
+     * when true, spawn the agent directly instead of inside a shared-socket tmux
+     * session. Also forced off by AGENTS_NO_TMUX=1. No effect on headless runs.
+     */
+    raw?: boolean;
 }
 /**
  * Resolve interactive vs headless. Explicit flags are definitive and win over
@@ -213,6 +219,52 @@ export declare function resolveShimSpawn(platform: NodeJS.Platform, binary: stri
  * keeping version resolution in one place instead of reimplementing it in batch.
  */
 export declare function execShimPassthrough(agent: AgentId, rawArgs: string[], cwd: string, pinnedVersion?: string): Promise<number>;
+/** Inputs that decide whether an interactive spawn is wrapped in a shared-socket tmux session. */
+export interface TmuxWrapContext {
+    /** resolveInteractive() result — only interactive REPL launches are wrapped. */
+    interactive: boolean;
+    /** process.platform — Windows has no tmux path, always spawns bare. */
+    platform: NodeJS.Platform;
+    /** True when the launcher itself already runs inside tmux ($TMUX set) — never double-wrap. */
+    inTmux: boolean;
+    /** The `--raw` escape hatch. */
+    raw: boolean;
+    /** The AGENTS_NO_TMUX=1 escape hatch. */
+    noTmuxEnv: boolean;
+    /** Whether a tmux binary is on PATH. */
+    tmuxAvailable: boolean;
+}
+/**
+ * Decide whether to run an interactive agent INSIDE a detached tmux session on
+ * the shared socket (then attach the current TTY) instead of a bare spawn.
+ *
+ * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
+ * `agents sessions --active` can tell co-located agents apart, and lets `agents
+ * focus` re-attach a live session without forking it. Pure so the gate is unit-
+ * tested independently of the (side-effecting) spawn.
+ *
+ * All five guards must pass:
+ *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
+ *   - not Windows     — no tmux path on win32.
+ *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
+ *   - not --raw       — explicit opt-out.
+ *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
+ *   - tmux installed  — otherwise there is nothing to wrap with.
+ */
+export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;
+/**
+ * Build the shell command that runs an agent inside a tmux pane with the exact
+ * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
+ * K=V … <agent> <args…>` so:
+ *   - `env` materializes the full agent env INTO the pane, independent of the
+ *     (possibly stale, shared) tmux server environment — additive, so tmux's own
+ *     $TMUX / $TMUX_PANE still reach the agent for provenance detection;
+ *   - `exec` replaces the shell so the agent is the pane's leaf process (clean
+ *     `#{pane_pid}`, clean signal delivery on detach/kill).
+ * Keys are filtered to valid identifiers so exported shell functions
+ * (`BASH_FUNC_*%%`) can't make `env` choke.
+ */
+export declare function buildTmuxAgentCommand(executable: string, args: string[], env: NodeJS.ProcessEnv): 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

@@ -19,6 +19,8 @@ import { getShimsDir } from './state.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
+import { isTmuxInstalled } from './tmux/binary.js';
+import { shellQuote } from './ssh-exec.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -753,6 +755,131 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
         });
     });
 }
+/**
+ * Decide whether to run an interactive agent INSIDE a detached tmux session on
+ * the shared socket (then attach the current TTY) instead of a bare spawn.
+ *
+ * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
+ * `agents sessions --active` can tell co-located agents apart, and lets `agents
+ * focus` re-attach a live session without forking it. Pure so the gate is unit-
+ * tested independently of the (side-effecting) spawn.
+ *
+ * All five guards must pass:
+ *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
+ *   - not Windows     — no tmux path on win32.
+ *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
+ *   - not --raw       — explicit opt-out.
+ *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
+ *   - tmux installed  — otherwise there is nothing to wrap with.
+ */
+export function shouldWrapInTmux(ctx) {
+    if (!ctx.interactive)
+        return false;
+    if (ctx.platform === 'win32')
+        return false;
+    if (ctx.inTmux)
+        return false;
+    if (ctx.raw)
+        return false;
+    if (ctx.noTmuxEnv)
+        return false;
+    if (!ctx.tmuxAvailable)
+        return false;
+    return true;
+}
+/**
+ * Build the shell command that runs an agent inside a tmux pane with the exact
+ * env the bare spawn would use. tmux runs it via `sh -c <cmd>`; we `exec env
+ * K=V … <agent> <args…>` so:
+ *   - `env` materializes the full agent env INTO the pane, independent of the
+ *     (possibly stale, shared) tmux server environment — additive, so tmux's own
+ *     $TMUX / $TMUX_PANE still reach the agent for provenance detection;
+ *   - `exec` replaces the shell so the agent is the pane's leaf process (clean
+ *     `#{pane_pid}`, clean signal delivery on detach/kill).
+ * Keys are filtered to valid identifiers so exported shell functions
+ * (`BASH_FUNC_*%%`) can't make `env` choke.
+ */
+export function buildTmuxAgentCommand(executable, args, env) {
+    const envPrefix = Object.entries(env)
+        .filter(([k, v]) => v !== undefined && EXEC_ENV_KEY_PATTERN.test(k))
+        .map(([k, v]) => `${k}=${shellQuote(String(v))}`)
+        .join(' ');
+    const agentCmd = [executable, ...args].map(shellQuote).join(' ');
+    return `exec env ${envPrefix} ${agentCmd}`;
+}
+/**
+ * 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.
+ *
+ * Lifecycle:
+ *   1. createSession() launches `sh -c 'exec env … agent'` detached, remain-on-exit
+ *      on (global), and returns the pane id.
+ *   2. A per-session `pane-died` hook detaches the attach client the instant the
+ *      AGENT pane exits, so attach returns instead of parking on a dead pane. The
+ *      hook is guarded on `#{hook_pane}` so it fires ONLY for the agent pane —
+ *      user-created splits (Ctrl-b " / %) that the user exits are closed in place
+ *      (`kill-pane`) instead of tearing down the whole client, so exiting one
+ *      split leaves the agent running full-window rather than kicking you out.
+ *   3. We record the agent pane's pid → session mapping (WITH the tmux pane) so the
+ *      headless active-scan attributes it, then attach the TTY (blocking).
+ *   4. On return: if the pane is dead the agent exited — read its status, tear the
+ *      session down, return that code. If the pane is still alive the user detached
+ *      (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 { getDefaultSocketPath } = await import('./tmux/paths.js');
+    const { attachTmux, runTmux } = await import('./tmux/binary.js');
+    const socket = getDefaultSocketPath();
+    const cwd = options.cwd || process.cwd();
+    const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
+    const name = slugifyName(`ag-${options.agent}-${idSeed}`);
+    const cmd = buildTmuxAgentCommand(executable, args, buildExecEnv(options));
+    const labels = { agent: options.agent };
+    if (options.sessionId)
+        labels.sessionId = options.sessionId;
+    const meta = await createSession({ name, cmd, cwd, socket, source: 'cli', labels });
+    const pane = meta.pane;
+    if (pane) {
+        // When the AGENT pane dies, detach the client (don't kill) so the session
+        // survives just long enough to read the dead pane's exit status below. The
+        // `#{hook_pane}` guard scopes this to the agent pane only: if the user splits
+        // the window and exits one of THEIR panes, the else-branch `kill-pane` closes
+        // 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);
+        // 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;
+        try {
+            const r = await runTmux({ socket, args: ['display-message', '-pt', pane, '-p', '#{pane_pid}'], throwOnError: false });
+            panePid = parseInt(r.stdout.trim(), 10) || 0;
+        }
+        catch { /* best-effort */ }
+        writePidSessionEntry({
+            pid: panePid,
+            agent: options.agent,
+            sessionId: options.sessionId,
+            cwd,
+            tmuxPane: pane,
+            startedAtMs: Date.now(),
+        });
+    }
+    // The agent could exit before we attach (fast failure). Don't attach to an
+    // already-dead pane — read its 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] });
+    }
+    const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
+    if (after.dead) {
+        await killSession(name, socket).catch(() => { });
+        return { exitCode: after.status ?? 0, stderr: '' };
+    }
+    // Pane still alive → the user detached; keep the session for `agents focus`.
+    return { exitCode: 0, stderr: '' };
+}
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
@@ -800,6 +927,29 @@ async function spawnAgent(options) {
         command: executable,
         args: redactArgs(args.slice(0, 10)),
     });
+    // Interactive spawn-wrap: on macOS/Linux, run the agent INSIDE a shared-socket
+    // tmux session (then attach this TTY) so it gets a unique, addressable %pane.
+    // Headless runs, Windows, already-in-tmux, --raw, and AGENTS_NO_TMUX=1 keep the
+    // bare spawn below. See shouldWrapInTmux / runInTmux.
+    if (shouldWrapInTmux({
+        interactive,
+        platform: process.platform,
+        inTmux: !!process.env.TMUX,
+        raw: options.raw === true,
+        noTmuxEnv: process.env.AGENTS_NO_TMUX === '1',
+        tmuxAvailable: isTmuxInstalled(),
+    })) {
+        timer.mark('startup');
+        try {
+            const result = await runInTmux(options, executable, args);
+            timer.end({ exitCode: result.exitCode, status: result.exitCode === 0 ? 'success' : 'failed' });
+            return result;
+        }
+        catch (err) {
+            timer.end({ error: err.message, exitCode: -1, status: 'error' });
+            throw err;
+        }
+    }
     return new Promise((resolve, reject) => {
         // Interactive mode inherits all stdio so the CLI owns the TTY (TUI
         // rendering, raw-mode keystrokes, colored output). Headless mode pipes

package/dist/lib/menubar/install-menubar.js

@@ -77,7 +77,7 @@ export function menubarServiceInstalled() {
  * Locate the source `.app` shipped alongside the compiled JS.
  *   1. dist/lib/menubar/MenubarHelper.app — npm install layout (sibling of this file)
  *   2. <repo>/bin/MenubarHelper.app       — raw working tree (tsx/dev)
- *   3. <repo>/packages/menubar-helper/dist/MenubarHelper.app — fresh local build
+ *   3. apps/cli/menubar/dist/MenubarHelper.app — fresh local build
  */
 function sourceAppPath() {
     const candidates = [];
@@ -85,7 +85,7 @@ function sourceAppPath() {
         const here = path.dirname(fileURLToPath(import.meta.url));
         candidates.push(path.join(here, APP_BUNDLE_NAME));
         candidates.push(path.resolve(here, '..', '..', '..', 'bin', APP_BUNDLE_NAME));
-        candidates.push(path.resolve(here, '..', '..', '..', 'packages', 'menubar-helper', 'dist', APP_BUNDLE_NAME));
+        candidates.push(path.resolve(here, '..', '..', '..', 'menubar', 'dist', APP_BUNDLE_NAME));
     }
     catch {
         /* import.meta.url unavailable */

package/dist/lib/secrets/bundles.js

@@ -336,13 +336,13 @@ export function writeBundle(bundle) {
     // of the tier. On an un-updated pinned helper this write fails loudly (the
     // no-ACL command is missing) rather than silently landing an ACL'd item.
     itemStore(backend).set(bundleMetaItem(bundle.name), json, { noAcl: bundle.policy === 'never' });
-    emit('secrets.set', { bundle: bundle.name });
+    emit('secrets.set', { module: 'secrets', bundle: bundle.name });
 }
 export function deleteBundle(name) {
     validateBundleName(name);
     const deleted = itemStore(bundleBackend(name)).delete(bundleMetaItem(name));
     if (deleted) {
-        emit('secrets.delete', { bundle: name });
+        emit('secrets.delete', { module: 'secrets', bundle: name });
     }
     return deleted;
 }
@@ -692,6 +692,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             const filtered = filterAgentHitBySubsetAndExpiry(hit, opts);
             stampLastUsed(filtered.bundle);
             emit('secrets.get', {
+                module: 'secrets',
                 bundle: name,
                 caller: opts.caller,
                 status: 'success',
@@ -781,6 +782,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     keychainKeys.sort();
     const emitReadAudit = (status, err) => {
         emit('secrets.get', {
+            module: 'secrets',
             bundle: bundle.name,
             caller: opts.caller,
             status,
@@ -943,7 +945,7 @@ export function renameBundle(oldName, newName, opts = {}) {
         store.delete(oldItem);
     }
     deleteBundle(oldName);
-    emit('secrets.rename', { from: oldName, to: newName });
+    emit('secrets.rename', { module: 'secrets', from: oldName, to: newName });
 }
 /**
  * The store (keychain or encrypted file) that carries a bundle's items. The

package/dist/lib/secrets/remote.js

@@ -17,6 +17,7 @@
  */
 import { sshExec, assertValidSshTarget } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
+import { emit } from '../events.js';
 import { sshTargetFor } from '../hosts/types.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../hosts/remote-os.js';
@@ -136,5 +137,18 @@ export async function remoteResolveEnv(target, bundle) {
     for (const [k, v] of Object.entries(parsed)) {
         env[k] = typeof v === 'string' ? v : String(v);
     }
+    // The remote host audits its own `secrets export` read; this emit records the
+    // event on the INITIATING host too (values were pulled into this process and
+    // injected locally). Covers `secrets exec --host` and `run --secrets b@host`.
+    // Values never enter the payload — only the bundle, target host, and count.
+    emit('secrets.get', {
+        module: 'secrets',
+        bundle,
+        caller: 'remote resolve',
+        source: 'remote',
+        host: target,
+        status: 'success',
+        keyCount: Object.keys(env).length,
+    });
     return env;
 }

package/dist/lib/secrets/sync.js

@@ -14,6 +14,7 @@ import * as crypto from 'crypto';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { readBundle, writeBundle, keychainItemsForBundle, validateBundleName, } from './bundles.js';
 import { rushSyncBackend } from './drivers/rush.js';
+import { emit } from '../events.js';
 // PBKDF2 cost. 600k SHA-256 iters matches OWASP 2023+ guidance and keeps a
 // passphrase prompt under a second on the hardware the CLI targets.
 const PBKDF2_ITER = 600_000;
@@ -185,6 +186,18 @@ function rollbackFailureMessage(name, phase, err, dirty) {
 export async function pushBundle(name, opts) {
     validateBundleName(name);
     const snap = snapshotBundle(name);
+    // Push reads every plaintext value and uploads the (client-side-encrypted)
+    // bundle off-machine — the most sensitive read there is. It bypasses
+    // readAndResolveBundleEnv, so audit it explicitly. Values never enter the
+    // payload; only the bundle name and how many keys were read.
+    emit('secrets.get', {
+        module: 'secrets',
+        bundle: name,
+        caller: 'sync push',
+        source: 'sync-push',
+        status: 'success',
+        keyCount: Object.keys(snap.secrets).length,
+    });
     const envelope = encryptBlob(JSON.stringify(snap), opts.passphrase);
     const updated_at = new Date().toISOString();
     const payload = { envelope, updated_at };