@phnx-labs/agents-cli 1.20.41 → 1.20.43

package/dist/lib/exec.js

@@ -17,8 +17,11 @@ import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js'
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { getShimsDir } from './state.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
+import { isTmuxInstalled } from './tmux/binary.js';
+import { shellQuote } from './ssh-exec.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -255,6 +258,12 @@ export function buildExecEnv(options) {
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
     }
+    // Export the run's durable name (companion to AGENT_SESSION_ID) so a
+    // SessionStart hook / the agent can associate its transcript with the handle
+    // the user gave the run. Only set when --name was passed.
+    if (options.name) {
+        result.AGENT_SESSION_NAME = options.name;
+    }
     return {
         ...result,
         ...options.env,
@@ -753,6 +762,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.
  *
@@ -773,6 +907,12 @@ async function spawnAgent(options) {
     if (options.agent === 'claude' && !options.resume && !options.sessionId) {
         options = { ...options, sessionId: randomUUID() };
     }
+    // Record the run's --name against its session id (when both are known at
+    // launch) so `agents sessions <name>` resolves it. Best-effort; unnamed runs
+    // and agents whose id isn't known up front simply skip this.
+    if (options.name && options.sessionId) {
+        recordRunName({ sessionId: options.sessionId, name: options.name, agent: options.agent, cwd: options.cwd });
+    }
     const cmd = buildExecCommand(options);
     const [executable, ...args] = cmd;
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
@@ -800,6 +940,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/hosts/dispatch.d.ts

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

package/dist/lib/hosts/dispatch.js

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

package/dist/lib/hosts/session-index.js

@@ -36,6 +36,7 @@ export function hostSessionMeta(task, ctx) {
         filePath: '',
         topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
         label: `[host/${task.host}]`,
+        name: task.name,
     };
 }
 /**

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

@@ -15,6 +15,14 @@ export interface HostTask {
     agent: string;
     prompt: string;
     pid?: number;
+    /**
+     * The durable `agents run --name <slug>` handle for this dispatch, if given.
+     * Chosen at launch and agent-agnostic (unlike sessionId), so `agents hosts
+     * ps/logs <name>` and the dispatch tip can reference the run by a stable name
+     * even for agents that never expose a session id up front. Absent when the
+     * run was launched without `--name`.
+     */
+    name?: string;
     /**
      * The agent session id the remote run was launched with (Claude only — the
      * only agent that accepts `--session-id` to force a NEW session's id). Lets
@@ -52,3 +60,10 @@ export declare function listTasks(): HostTask[];
  * with the same forced id resolves to the most recent dispatch.
  */
 export declare function findTaskBySessionId(sessionId: string): HostTask | null;
+/**
+ * Find the newest host task launched with `--name <name>`, so `agents hosts
+ * logs/ps <name>` and resolve-by-handle can address a run by its durable name.
+ * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
+ * reused across dispatches.
+ */
+export declare function findTaskByName(name: string): HostTask | null;

package/dist/lib/hosts/tasks.js

@@ -85,3 +85,19 @@ export function findTaskBySessionId(sessionId) {
     }
     return null;
 }
+/**
+ * Find the newest host task launched with `--name <name>`, so `agents hosts
+ * logs/ps <name>` and resolve-by-handle can address a run by its durable name.
+ * Case-insensitive; newest wins (listTasks is createdAt-desc) when a name was
+ * reused across dispatches.
+ */
+export function findTaskByName(name) {
+    if (!name)
+        return null;
+    const wanted = name.toLowerCase();
+    for (const task of listTasks()) {
+        if (task.name && task.name.toLowerCase() === wanted)
+            return task;
+    }
+    return null;
+}

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/rotate.d.ts

@@ -47,9 +47,11 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
  * Resolve the configured strategy. Lookup order:
  *   1. project-local agents.yaml (nearest to `startPath`)
  *   2. ~/.agents/.system/agents.yaml
- *   3. default: `available` (use the pinned default version when healthy,
- *      otherwise fall through to a healthy account so a single rate-limited
- *      account doesn't block the run).
+ *   3. default: `balanced` (weighted-random across all healthy accounts by
+ *      remaining headroom, skipping any that are currently rate-limited). A
+ *      bare `agents run <agent>` — e.g. every new terminal the extension spawns
+ *      — should spread load and never launch into a throttled account, rather
+ *      than stick to the pinned default even when it's maxed.
  */
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
@@ -65,9 +67,12 @@ export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrate
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and usage available
- * (any non-session window strictly under 100%, or local flag not exhausted
- * when no live snapshot exists).
+ * Eligibility: signed in (email present), auth valid, and not currently
+ * rate-limited — no blocking window (session OR weekly) at 100%, matching the
+ * `agents view` badge; or the local cached status is usable when no live
+ * snapshot exists. Note the split: eligibility considers the session window
+ * (a session-maxed account can't run now), but the capacity *weight* above is
+ * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
  * Dedupe: when multiple versions share an email, collapse to one candidate
  * per email (the least-recently-active version). Prevents two parallel pods

package/dist/lib/rotate.js

@@ -10,7 +10,7 @@ import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
 import { getProjectRunConfigs } from './run-config.js';
-import { getUsageInfoByIdentity, getUsageLookupKey, } from './usage.js';
+import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -44,14 +44,16 @@ export function getProjectRunStrategy(agent, startPath) {
  * Resolve the configured strategy. Lookup order:
  *   1. project-local agents.yaml (nearest to `startPath`)
  *   2. ~/.agents/.system/agents.yaml
- *   3. default: `available` (use the pinned default version when healthy,
- *      otherwise fall through to a healthy account so a single rate-limited
- *      account doesn't block the run).
+ *   3. default: `balanced` (weighted-random across all healthy accounts by
+ *      remaining headroom, skipping any that are currently rate-limited). A
+ *      bare `agents run <agent>` — e.g. every new terminal the extension spawns
+ *      — should spread load and never launch into a throttled account, rather
+ *      than stick to the pinned default even when it's maxed.
  */
 export function getConfiguredRunStrategy(agent, startPath = process.cwd()) {
     return getProjectRunStrategy(agent, startPath)
         ?? normalizeRunStrategy(readMeta().run?.[agent]?.strategy)
-        ?? 'available';
+        ?? 'balanced';
 }
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export function setGlobalRunStrategy(agent, strategy) {
@@ -72,10 +74,19 @@ function isAvailableEligible(candidate) {
         && hasUsageAvailable(candidate);
 }
 function hasUsageAvailable(candidate) {
-    const usedPercent = getRoutingUsedPercent(candidate.usageSnapshot);
-    if (usedPercent !== null) {
-        return usedPercent < 100;
+    const snapshot = candidate.usageSnapshot;
+    if (snapshot && snapshot.windows.length > 0) {
+        // Eligibility mirrors the `agents view` throttle badge exactly
+        // (deriveUsageStatusFromSnapshot): an account maxed on ANY blocking window —
+        // including the 5-hour session window — cannot serve the next request, so it
+        // must not be picked. Previously this checked only non-session windows
+        // (getRoutingUsedPercent), so a session-maxed account with weekly headroom
+        // stayed "eligible" and the router kept launching into it while `ag view`
+        // showed it rate-limited. Capacity *weighting* still ranks eligible accounts
+        // by weekly headroom; this gate only decides can-it-run-right-now.
+        return deriveUsageStatusFromSnapshot(snapshot) !== 'rate_limited';
     }
+    // No live snapshot: fall back to the coarse cached status.
     if (candidate.usageStatus === 'out_of_credits' || candidate.usageStatus === 'rate_limited') {
         return false;
     }
@@ -140,9 +151,12 @@ function dedupeAndSortCandidates(candidates) {
  * headroom, with no stampede on the lowest-usage one. Stateless — parallel
  * callers naturally fan out via the random roll.
  *
- * Eligibility: signed in (email present), auth valid, and usage available
- * (any non-session window strictly under 100%, or local flag not exhausted
- * when no live snapshot exists).
+ * Eligibility: signed in (email present), auth valid, and not currently
+ * rate-limited — no blocking window (session OR weekly) at 100%, matching the
+ * `agents view` badge; or the local cached status is usable when no live
+ * snapshot exists. Note the split: eligibility considers the session window
+ * (a session-maxed account can't run now), but the capacity *weight* above is
+ * driven by weekly headroom so a brief session spike doesn't distort routing.
  *
  * Dedupe: when multiple versions share an email, collapse to one candidate
  * per email (the least-recently-active version). Prevents two parallel pods

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 };

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

@@ -20,6 +20,8 @@ export interface ActiveSession {
     cwd?: string;
     /** User-given name from /rename command. */
     label?: string;
+    /** Durable `agents run --name` launch handle, when the run was named. */
+    name?: string;
     /** First meaningful line of the initial prompt (extracted topic). */
     topic?: string;
     /** Live preview: the latest turn (agent message or tool action), from the state engine. */
@@ -84,11 +86,35 @@ export interface ActiveSession {
      * (after the --json/--waiting gates) — NOT emitted on the discovery path.
      */
     tmuxTarget?: string;
+    /**
+     * Which host app + tab a tmux-hosted session is currently being VIEWED in,
+     * resolved from the attached tmux client (its terminal PID -> app via
+     * HOST_MATCHERS, its tab via the per-app resolver). `undefined` means no
+     * client is attached — the session is running detached. Transient,
+     * renderer-set (see src/lib/session/viewing-in.ts) — NOT on the discovery path.
+     */
+    viewingIn?: {
+        app: string;
+        tab?: number;
+    };
 }
 export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
 }
+/**
+ * Pick a Claude transcript file within a project dir.
+ *
+ * With a CONCRETE session id: return that id's `<id>.jsonl` or undefined — NEVER a
+ * sibling's. Falling back to the newest file here is the bug that made N distinct
+ * co-located sessions (e.g. several editor tabs in one cwd, or two worktree siblings)
+ * all collapse onto ONE file and render identical preview + topic (they look like
+ * duplicate cards). The mtime fallback is only sound when NO id is known.
+ *
+ * With NO id: return the newest `.jsonl` by mtime (the legitimate single-session
+ * heuristic for a directly-launched agent with no registry entry).
+ */
+export declare function pickSessionFile(projectDir: string, sessionId?: string): string | undefined;
 /**
  * Locate the live transcript for an agent process. Claude files are keyed by
  * cwd (+ optional session uuid); Codex files are date-partitioned, so we resolve
@@ -117,6 +143,14 @@ export declare function parseWin32ProcessCsv(out: string): ProcRow[];
  * for testing the bound; production always uses the real `lsof`-backed probe.
  */
 export declare function resolveCwds(pids: number[], probe?: (pid: number) => Promise<string | undefined>): Promise<(string | undefined)[]>;
+/**
+ * Resolve the host app for a single pid by walking its process ancestry with the
+ * same HOST_MATCHERS logic `detectHost` uses. Reads the whole process table per
+ * call, so it's for the low-cardinality renderer path (one tmux client per
+ * session), not a hot loop. Returns undefined when nothing above the pid is a
+ * recognised UI. Exported for the "viewing in <app>" resolver.
+ */
+export declare function hostFromPid(pid: number): Promise<string | undefined>;
 export interface AgentCandidate {
     pid: number;
     kind: string;
@@ -155,9 +189,21 @@ export declare function foldSubordinateAgents(candidates: AgentCandidate[], ppid
  */
 export declare function listUnattributedActive(attributed: Set<number>): Promise<ActiveSession[]>;
 /**
- * Union of all four sources. Teams and terminals spawn actual CLI processes
- * that also show up in `ps`, so headless attribution runs last with the
- * already-attributed PIDs removed.
+ * Agents hosted in the shared-socket tmux server — the authoritative source for
+ * tmux-wrapped interactive spawns (see src/lib/exec.ts `runInTmux`). Enumerates
+ * every pane on the shared socket and keeps those whose session meta was stamped
+ * with `labels.agent` + `labels.sessionId` by the spawn-wrap. Because tmux (not a
+ * per-window `live-terminals.json`) is the source of truth, a tmux-hosted agent is
+ * ALWAYS captured with its exact `%pane` even when the extension registry is stale
+ * or absent. `source: 'teams'` is skipped — teammates are surfaced by listTeamsActive.
+ */
+export declare function listTmuxAgentSessions(): Promise<ActiveSession[]>;
+/**
+ * Union of all sources. Teams and terminals spawn actual CLI processes that
+ * also show up in `ps`, so headless attribution runs last with the already-
+ * attributed PIDs removed. The tmux source goes FIRST into the dedupe so a
+ * tmux-hosted agent's row (which carries the exact `%pane`) wins over a staler
+ * terminal/headless row for the same session id.
  */
 export declare function getActiveSessions(opts?: ActiveQueryOptions): Promise<ActiveSession[]>;
 export {};