@phnx-labs/agents-cli 1.20.40 → 1.20.42

package/dist/commands/go.js

@@ -1,17 +1,17 @@
 /**
- * `agents sessions go [id]` — jump to a LIVE agent session's terminal.
+ * `agents sessions go [id]` — DEPRECATED alias for `agents sessions focus --attach-only`.
  *
- * No id  -> the SAME rich interactive picker as `agents sessions` (worktree, PR,
- *           changed files, tools, tests, last response — this-machine first),
- *           filtered to sessions that are running right now.
- * With id -> jump directly.
+ * `go` was "attach or refuse" (never fork/resume). `focus --attach-only` is exactly
+ * that behavior, so `go` now prints a deprecation notice and delegates to `focusAction`.
  *
- * "Jump" is not "resume" (which spawns a new process from the transcript). It walks
- * you to the already-running terminal:
- *   local tmux    -> attach (switch-client when already inside tmux)
- *   local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
- *   remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
- *   otherwise     -> refuse with a reason + resume hint (cloud / no attach rail)
+ * This file still owns the shared reach engine that `focus` imports:
+ *   - `gatherLiveTargets` / `pickLiveTarget` / `buildLivePool` — live-session discovery + picker
+ *   - `jumpTo` — the side-effecting jump: attach the already-running terminal
+ *       local tmux    -> attach (switch-client when already inside tmux)
+ *       local Ghostty -> focus its tab (Cmd+<n> via System Events; tab # from ghostty-tabs)
+ *       remote tmux   -> ssh -tt + tmux attach (pane->session resolved on the remote)
+ *       otherwise     -> hand off to the `UnreachableFallback` (attach-only refuses; focus resumes)
+ *   - `refuseFallback` — the attach-only fallback (remote -> login shell; local -> refuse)
  */
 import chalk from 'chalk';
 import path from 'path';
@@ -21,8 +21,8 @@ import { getActiveSessions, findSessionFileForKind } from '../lib/session/active
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { dedupeByMachineSession, mergeLocalFirst, pickSessionInteractive } from './sessions.js';
+import { focusAction } from './focus.js';
 import { machineId } from '../lib/session/sync/config.js';
-import { isInteractiveTerminal } from './utils.js';
 import { attachTmux, runTmux } from '../lib/tmux/binary.js';
 import { getDefaultSocketPath } from '../lib/tmux/paths.js';
 import { sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
@@ -33,20 +33,21 @@ export function registerGoCommand(program) {
         .command('go')
         .argument('[id]', 'Short/full session id to jump to; omit for an interactive picker')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
-        .description('Jump to a live agent session — attach its tmux, or focus its terminal tab')
+        .description('Deprecated alias for `sessions focus --attach-only`')
         .action(async (id, opts) => {
-        await goAction(id, opts);
+        console.error(chalk.yellow('`sessions go` is deprecated — use `sessions focus --attach-only`'));
+        await focusAction(id, { local: opts.local, attachOnly: true });
     });
 }
-async function goAction(id, opts) {
+/** Live jump targets (local + remote), keyed by session id. Cloud excluded (no pid). */
+export async function gatherLiveTargets(local) {
     const self = machineId();
-    // Live jump targets (local + remote), keyed by session id.
     const localActive = await getActiveSessions();
     for (const s of localActive)
         if (!s.machine)
             s.machine = self;
     let active = localActive;
-    if (!opts.local) {
+    if (!local) {
         try {
             const remote = await gatherRemoteActive();
             active = dedupeByMachineSession([...localActive, ...remote.sessions]);
@@ -57,54 +58,24 @@ async function goAction(id, opts) {
     for (const s of active)
         if (s.context !== 'cloud' && s.sessionId)
             activeById.set(s.sessionId, s);
-    if (activeById.size === 0) {
-        console.log(chalk.gray('No live agent sessions to jump to.'));
-        return;
-    }
-    // Direct jump by id — no picker.
-    if (id) {
-        const q = id.toLowerCase();
-        const matches = [...activeById.values()].filter((s) => s.sessionId.toLowerCase().startsWith(q));
-        if (matches.length === 0) {
-            console.error(chalk.red(`No live session matching "${id}".`));
-            process.exitCode = 1;
-            return;
-        }
-        if (matches.length > 1) {
-            console.error(chalk.red(`"${id}" is ambiguous (${matches.length} matches). Use more of the id.`));
-            process.exitCode = 1;
-            return;
-        }
-        await jumpTo(matches[0], self);
-        return;
-    }
-    if (!isInteractiveTerminal()) {
-        console.error(chalk.red('go needs an interactive terminal, or pass a session id.'));
-        process.exitCode = 1;
-        return;
-    }
-    // Reuse the rich `sessions` picker over the live sessions' full SessionMeta.
+    return { self, activeById };
+}
+/** Interactive pick over the live sessions' rich SessionMeta; returns the chosen live session. */
+export async function pickLiveTarget(activeById, self, message, enterHint) {
     const pool = await buildLivePool(activeById, self);
-    if (pool.length === 0) {
-        console.log(chalk.gray('No live sessions to jump to.'));
-        return;
-    }
-    const picked = await pickSessionInteractive(pool, 'Jump to a live session:', undefined, 0, 'jump');
+    if (pool.length === 0)
+        return null;
+    const picked = await pickSessionInteractive(pool, message, undefined, 0, enterHint);
     if (!picked)
-        return;
-    const target = activeById.get(picked.session.id);
-    if (!target) {
-        console.log(chalk.yellow(`${picked.session.shortId} is no longer live — try: `) + chalk.gray(`agents sessions resume ${picked.session.shortId}`));
-        return;
-    }
-    await jumpTo(target, self);
+        return null;
+    return activeById.get(picked.session.id) ?? null;
 }
 /**
  * Map each live session to its rich SessionMeta (worktree/PR/changes/tools/tests
  * via the shared picker), reusing `discoverSessions`. Remote or unindexed live
  * sessions get a minimal synthesized meta so they still appear and jump.
  */
-async function buildLivePool(activeById, self) {
+export async function buildLivePool(activeById, self) {
     let metas = [];
     try {
         metas = await discoverSessions({ all: true, since: '30d', limit: 1000 });
@@ -151,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' };
@@ -161,7 +137,17 @@ export function describeWhere(s, self) {
         return { label: `${s.host ?? 'shell'} on ${remote}`, action: `open a shell on ${remote}` };
     return { label: s.host ?? 'unknown terminal', action: 'resume it (no live attach rail)' };
 }
-async function jumpTo(s, self) {
+/** Default (attach-only): open a login shell on the remote, or refuse locally. */
+export async function refuseFallback(s, remote) {
+    if (remote) {
+        console.log(chalk.yellow(`${shortId(s)} on ${remote} isn't inside tmux — opening a shell on ${remote} instead.`));
+        assertValidSshTarget(remote);
+        process.exit(sshStream(remote, 'exec "${SHELL:-/bin/sh}" -l', { tty: true }));
+    }
+    console.log(chalk.yellow(`Can't jump to ${shortId(s)} — it's in ${s.host ?? 'an unknown terminal'} with no attach rail (not tmux/Ghostty).`) +
+        chalk.gray(`\nTry: agents sessions resume ${shortId(s)}`));
+}
+export async function jumpTo(s, self, fallback = refuseFallback) {
     const remote = s.machine && s.machine !== self ? s.machine : undefined;
     const mux = s.provenance?.mux;
     // Path C: remote tmux — ssh in and attach, resolving the pane's session on the remote.
@@ -177,9 +163,9 @@ async function jumpTo(s, self) {
             console.log(chalk.gray(`Attaching ${shortId(s)} on ${remote} over SSH — Ctrl-b d to detach.`));
             process.exit(sshStream(remote, remoteCmd, { tty: true }));
         }
-        console.log(chalk.yellow(`${shortId(s)} on ${remote} isn't inside tmux — opening a shell on ${remote} instead.`));
-        assertValidSshTarget(remote);
-        process.exit(sshStream(remote, 'exec "${SHELL:-/bin/sh}" -l', { tty: true }));
+        // Remote, not in tmux → hand off to the fallback (go: shell; focus: resume in a tab).
+        await fallback(s, remote);
+        return;
     }
     // Path B: local tmux — attach (or switch-client if we're already inside tmux).
     if (mux?.kind === 'tmux' && mux.pane) {
@@ -218,9 +204,8 @@ async function jumpTo(s, self) {
             chalk.gray(tab != null ? ` — switch to tab ${tab} (Cmd+${tab}).` : " — couldn't pinpoint its tab (same-repo forks are ambiguous); switch tabs manually."));
         return;
     }
-    // Path D: refuse with a reason.
-    console.log(chalk.yellow(`Can't jump to ${shortId(s)} — it's in ${s.host ?? 'an unknown terminal'} with no attach rail (not tmux/Ghostty).`) +
-        chalk.gray(`\nTry: agents sessions resume ${shortId(s)}`));
+    // Path D: no attach rail (headless / plain terminal) → hand off to the fallback.
+    await fallback(s, undefined);
 }
 /** Resolve a local tmux pane id to its session name + window index. */
 async function resolveLocalPane(socket, pane) {

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';
@@ -490,7 +491,7 @@ export function registerSecretsCommands(program) {
       # See what's in the bundle (values masked); shows its prompt policy
       agents secrets view prod
 
-      # Stop a noisy automation bundle from prompting every run: ask once a day
+      # Stop a noisy automation bundle from prompting every run: ask once a week
       agents secrets policy prod daily
 
       # Eval the bundle into your current shell
@@ -510,15 +511,16 @@ export function registerSecretsCommands(program) {
       Touch ID noise: macOS pops a prompt per bundle per process. Each bundle has
       a prompt policy, shown in the POLICY column of 'agents secrets list':
         daily (default)   ask once, then hold it silently in the local agent up
-                          to ~24h, until screen-lock / sleep / logout or 'lock'.
+                          to ~7 days, until sleep / logout or 'lock' (a bare
+                          screen-lock does NOT drop it). Name is historical.
         always            ask for Touch ID every time — never auto-held.
-      The default is 'daily' (one Touch ID per ~24h); change it globally with
+      The default is 'daily' (one Touch ID per ~7 days); change it globally with
       'secrets.policy' in agents.yaml, or per bundle with 'agents secrets policy
       <bundle> always'. 'agents secrets unlock <bundle>' holds any bundle after one
       prompt regardless of policy. Nothing on disk.
 
       See also:
-        agents secrets policy <bundle> daily           ask once a day, not every run
+        agents secrets policy <bundle> daily           ask once a week, not every run
         agents secrets unlock <bundle>                 hold a bundle after one Touch ID
         agents secrets lock                            wipe held bundles (re-prompt next read)
         agents secrets status                          show held bundles + when they lock
@@ -623,7 +625,7 @@ export function registerSecretsCommands(program) {
             }
             else {
                 console.log(bundlePolicy(bundle) === 'daily'
-                    ? chalk.gray('policy: daily (ask once, then held ~24h until screen-lock / sleep / logout)')
+                    ? chalk.gray('policy: daily (ask once, then held ~7 days until sleep / logout — screen-lock does not drop it)')
                     : chalk.gray('policy: always (asks for Touch ID every time — never auto-held)'));
             }
             if (bundle.created_at)
@@ -657,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') {
@@ -702,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 {
@@ -733,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) {
@@ -747,7 +774,7 @@ export function registerSecretsCommands(program) {
         .description('Create an empty bundle')
         .option('--description <text>', 'Free-form description')
         .option('--allow-exec', 'Allow exec: refs in this bundle (off by default)')
-        .option('--policy <policy>', 'prompt policy: daily (default, ask once a day), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand)')
+        .option('--policy <policy>', 'prompt policy: daily (default, ask once a week), always (ask every time), or never (silent, NO biometry ACL — needs --i-understand)')
         .addOption(new Option('--tier <policy>', 'deprecated alias for --policy').hideHelp())
         .option('--i-understand', 'Confirm creating a "never"-policy bundle (no biometry ACL) without an interactive prompt')
         .option('--backend <backend>', 'storage backend: keychain (default) or file (passphrase-encrypted, headless-readable)', 'keychain')
@@ -1528,7 +1555,7 @@ Examples:
     cmd
         .command('unlock [names...]')
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS).')
-        .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h). Default 24h.')
+        .option('--ttl <duration>', 'How long to hold it (e.g. 30m, 8h, 3d). Default 7d.')
         .option('--all', 'Unlock every configured bundle')
         .action(async (names, opts) => {
         if (process.platform !== 'darwin') {
@@ -1544,7 +1571,7 @@ Examples:
         if (opts.ttl) {
             const secs = parseDuration(opts.ttl);
             if (!secs) {
-                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h.`));
+                console.error(chalk.red(`Invalid --ttl '${opts.ttl}'. Use e.g. 30m, 2h, 8h, 3d.`));
                 process.exit(1);
             }
             ttlMs = secs * 1000;
@@ -1628,7 +1655,7 @@ Examples:
     cmd
         .command('policy <bundle> [policy]')
         .alias('tier')
-        .description("Show or set a bundle's prompt policy: daily (default, ask once a day), always (ask every time), or never (silent, NO biometry ACL).")
+        .description("Show or set a bundle's prompt policy: daily (default, ask once a week), always (ask every time), or never (silent, NO biometry ACL).")
         .option('--i-understand', 'Confirm switching to the "never" policy (no biometry ACL) without an interactive prompt')
         .action(async (bundleName, policyArg, opts) => {
         try {
@@ -1644,11 +1671,23 @@ Examples:
                 console.error(chalk.yellow('Aborted.'));
                 return;
             }
+            const wasDaily = bundlePolicy(bundle) === 'daily';
             bundle.policy = next;
             writeBundle(bundle);
+            // Tightening daily -> always/never must take effect NOW, not up to the
+            // ~7d hold later. If the broker is already serving this bundle silently
+            // (auto-cached under the old `daily` policy), evict it so the next read
+            // re-prompts (`always`) or reads its no-ACL item directly (`never`).
+            // macOS-only + best-effort; agentLock no-ops off darwin / with no broker.
+            if (wasDaily && next !== 'daily') {
+                try {
+                    await agentLock(bundle.name);
+                }
+                catch { /* broker down — nothing held */ }
+            }
             console.log(chalk.green(`${bundle.name} policy set to ${next}.`));
             if (next === 'daily') {
-                console.log(chalk.gray('Held by the secrets-agent for ~24h after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
+                console.log(chalk.gray('Held by the secrets-agent for ~7 days after one unlock (auto-cache is on by default; disable with `secrets.agent.auto: false` in agents.yaml).'));
             }
             else if (next === 'always') {
                 console.log(chalk.gray('Asks for Touch ID every time — never auto-held.'));

package/dist/commands/sessions.d.ts

@@ -98,6 +98,15 @@ export declare function dedupeByMachineSession(sessions: ActiveSession[]): Activ
  * `localMachine` is injected so the ordering is testable without os.hostname().
  */
 export declare function mergeLocalFirst(sessions: SessionMeta[], localMachine: string): SessionMeta[];
+/**
+ * Serialize a `SessionMeta[]` to the clean JSON shape the `--json` listing
+ * emits: strip the internal-only scoring/provenance fields (`_matchedTerms`,
+ * `_bm25Score`, `_remote`) that are search/fan-out bookkeeping, never part of
+ * the public record, then pretty-print as a 2-space array with a trailing
+ * newline. The single seam shared by the local `--json` path and the
+ * `--json --host` remote fan-out so both emit byte-identical row shapes.
+ */
+export declare function serializeSessionsJson(sessions: SessionMeta[]): string;
 /**
  * Whether the local machine's sessions belong in an `--active` view. Local is
  * included by default; an explicit `--host`/`--device` list scopes the view to

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';
@@ -40,6 +41,7 @@ import { registerSessionsTailCommand } from './sessions-tail.js';
 import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerGoCommand } from './go.js';
+import { registerFocusCommand } from './focus.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 /**
@@ -313,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'));
@@ -507,6 +519,40 @@ export function mergeLocalFirst(sessions, localMachine) {
     });
     return keys.flatMap((k) => byMachine.get(k));
 }
+/**
+ * Serialize a `SessionMeta[]` to the clean JSON shape the `--json` listing
+ * emits: strip the internal-only scoring/provenance fields (`_matchedTerms`,
+ * `_bm25Score`, `_remote`) that are search/fan-out bookkeeping, never part of
+ * the public record, then pretty-print as a 2-space array with a trailing
+ * newline. The single seam shared by the local `--json` path and the
+ * `--json --host` remote fan-out so both emit byte-identical row shapes.
+ */
+export function serializeSessionsJson(sessions) {
+    const serializable = sessions.map((s) => {
+        const { _matchedTerms, _bm25Score, _remote, ...rest } = s;
+        return rest;
+    });
+    return JSON.stringify(serializable, null, 2) + '\n';
+}
+/**
+ * `agents sessions --json --host <h>` — fan the RECENT (non-active) listing out
+ * to the named host(s) and emit ONE clean merged `SessionMeta[]` JSON array,
+ * the same shape the local `--json` path emits. Reuses `gatherRemoteList` (the
+ * exact SSH fan-out the interactive cross-machine listing already uses) and
+ * serializes the merged, machine-tagged rows — instead of `runRemoteSessions`,
+ * which streams each remote's raw stdout under a per-host banner and so can
+ * never be JSON.parsed. A dead host contributes `[]` (with a stderr note from
+ * the fan-out), so stdout is always a valid array and the exit stays 0.
+ */
+async function runRemoteSessionsJson(hosts) {
+    // Forward the caller's own filters (query, --limit, --since, …) minus --host,
+    // and guarantee --json so each peer answers with a parseable array.
+    const forwarded = buildForwardedArgs(process.argv, new Set(hosts));
+    if (!forwarded.includes('--json'))
+        forwarded.push('--json');
+    const { sessions } = await gatherRemoteList(forwarded, hosts);
+    process.stdout.write(serializeSessionsJson(sessions));
+}
 /**
  * `running N · idle N · waiting N · queued N` for a bucket of sessions (zero
  * buckets omitted). Same bucketing as the grand-total summary so per-group
@@ -582,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 });
+                }
             }
         }
     }
@@ -715,10 +768,17 @@ async function sessionsAction(query, options) {
     if (options.device && options.device.length > 0) {
         options.host = [...(options.host ?? []), ...options.device];
     }
-    // --host WITHOUT --active keeps the legacy per-host stream (each remote's raw
-    // stdout under a `── host ──` banner). With --active, the hosts are folded
-    // into the merged machine-grouped view instead (handled below).
+    // --host WITHOUT --active. `--json` fans the recent listing out and emits ONE
+    // clean merged SessionMeta[] array (same shape as the local --json path), for
+    // scripts/extensions that JSON.parse a remote's history. Without --json it
+    // keeps the legacy per-host stream (each remote's raw stdout under a
+    // `── host ──` banner). With --active, the hosts are folded into the merged
+    // machine-grouped view instead (handled below).
     if (options.host && options.host.length > 0 && !options.active) {
+        if (options.json) {
+            await runRemoteSessionsJson(options.host);
+            return;
+        }
         try {
             runRemoteSessions(options.host);
         }
@@ -858,11 +918,7 @@ async function sessionsAction(query, options) {
         }
         if (options.json) {
             const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
-            const serializable = filtered.map(s => {
-                const { _matchedTerms, _bm25Score, _remote, ...rest } = s;
-                return rest;
-            });
-            process.stdout.write(JSON.stringify(serializable, null, 2) + '\n');
+            process.stdout.write(serializeSessionsJson(filtered));
             return;
         }
         // Cross-machine fan-out: unless --local (or we ARE a peer answering a
@@ -2014,6 +2070,7 @@ export function registerSessionsCommands(program) {
     registerSessionsSyncCommand(sessionsCmd);
     registerSessionsResumeCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);
+    registerFocusCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {

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;
 /**