@phnx-labs/agents-cli 1.20.41 → 1.20.43

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 1.20.43
+
+- **NEW: `agents run --name <slug>` — a durable, human/agent-friendly handle for any run.** An agent that dispatches another agent had no cheap status handle: the host-task id was never even printed (the `--no-follow` tip showed a literal `<id>` placeholder), and only Claude's session id is known up front (pre-minted `--session-id`) — every other agent's id is discovered later by scanning transcripts, so callers fell back to `agents logs`, which dumps the raw, token-heavy transcript. `--name` is chosen at launch, agent-agnostic, and stored on the structures that already back these views: a first-class `name` column on `sessions.db` (schema v9, additive, no rescan) parallel to `label` — `agents sessions <ref>` resolves against **both** name and label; the HostTask sidecar (forwarded to the remote run, so `agents hosts ps` gains a NAME column and `agents hosts logs <name>` resolves by name); and a run-name sidecar (`~/.agents/.cache/run-names/`) that joins a local run's name onto the index by id every scan via `syncNames` — the same idempotent pattern as `/rename` label sync. The `name` column is deliberately left out of the upsert `ON CONFLICT … SET` clause, so a discovery rescan can never null an existing name (regression-tested in `db.names.test.ts`). Omitting `--name` is a strict no-op: `name` stays unset and every id-based path is unchanged. The `--no-follow` dispatch tip now prints the real handle and steers to the compact `agents sessions` digest over the raw log. Source: `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/session/{db,run-names,discover}.ts`, `apps/cli/src/lib/hosts/{dispatch,tasks}.ts`.
+- **New terminals (and teammates) no longer launch into a rate-limited account; `balanced` is now the default run strategy.** Two coupled fixes. (1) A bare `agents run <agent>` — every new agent terminal the extension spawns, and every non-version-pinned `agents teams add`/`start` teammate, since both route through bare `agents run` — used to default to the `available` strategy, which *prefers the pinned default version when it looks healthy*. But "healthy" was judged by the router's `getRoutingUsedPercent`, which **excluded the 5-hour session window** and looked at weekly usage only. So a session-maxed account with weekly headroom (e.g. session 100% / week 60%) was deemed eligible and kept getting launched — while `agents view` showed it "rate-limited" (its badge, `deriveUsageStatusFromSnapshot`, *counts* the session window). The router and the badge disagreed. Now `hasUsageAvailable` shares the badge's exact signal: an account maxed on **any** blocking window (session or weekly) is ineligible and skipped by both `available` and `balanced` — you never spin up an agent on an account that can't serve the next request. Capacity *weighting* still ranks eligible accounts by weekly headroom, so a brief session spike doesn't distort long-run routing. (2) The default strategy is now `balanced` (was `available`): a bare run spreads load across all healthy accounts by remaining headroom instead of sticking to the pinned default. Override per-workspace with `run.<agent>.strategy` in `agents.yaml`, or per-invocation with `--strategy` / `-b`. Source: `apps/cli/src/lib/rotate.ts`, `apps/cli/src/lib/usage.ts`, `apps/cli/src/commands/exec.ts`.
+- **[browser] Logins survive browser restarts: sandboxed profiles keep memory-only session cookies, without restoring tabs.** Sites that issue login cookies with `expires=-1` (idealista, many banking/classifieds sites) logged the profile out on every browser restart, because Chromium purges memory-only session cookies at startup unless the session-restore preference is set — a constraint that had already leaked into agent designs as "sessions can't survive restarts". Every launch now pins `session.restore_on_startup: 1` ("continue where you left off") in the profile's `Default/Preferences`, which is the switch Chromium's cookie purge actually keys off — and pairs it with `--no-startup-window` so the *visible* side of restore never happens: no window exists at startup for restore to fill, no ghost tabs from the last task reopen, and the task flow creates its own tab over CDP exactly as before. Verified live on Windows/Comet: a memory-only cookie planted pre-restart was still present after a full stop/start, with OS-level window enumeration confirming a single window and zero restored tabs. The Preferences patch runs pre-spawn (browser down, so Chromium can't overwrite it on exit), stamps the profile name only on first launch, skips malformed files untouched, and is a no-op when already set. Electron profiles keep the old name-only seeding — they manage their own storage and need their startup window (the CDP driver binds to it). Bare `agents browser start` (no `--url`) recreates the old startup-window affordance by opening a blank page target when none exists, unregistered on the task like the startup window always was. Server-side session TTLs still apply — this removes the restart logout, not the site's own expiry. Source: `apps/cli/src/lib/browser/chrome.ts` (`ensureProfilePreferences`, launch args), `apps/cli/src/lib/browser/service.ts`.
+- **Security fix: `agents sessions --host <target>` no longer accepts a leading-dash target (SSH argv-flag smuggling).** `session/remote.ts` carried its own copy of `assertValidSshTarget` that omitted the `host.startsWith('-')` guard every other SSH path enforces, so a bare flag like `-l` or `-F/path` — which passes the character allowlist — was handed straight to `ssh` as an argument (`-oProxyCommand=…`-class injection) before any connection. The duplicate validator (and its `SSH_TARGET_RE`) is deleted; `runRemoteSessions` now routes through the canonical `assertValidSshTarget` in `ssh-exec.ts`, whose dash guard is already regression-tested (`ssh-exec.test.ts`). Source: `apps/cli/src/lib/session/remote.ts`.
+
+## 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

@@ -218,11 +218,13 @@ export function registerRunCommand(program) {
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
         .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('--name <slug>', 'Give the run a durable name — a stable handle you can check on later with `agents sessions <name>` (and `agents hosts logs <name>` for --host runs), instead of an opaque id. Optional; omitting it keeps today\'s id-only behavior.')
         .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.')
-        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then pinned. (Legacy `rotate` accepted as alias for `balanced`.)')
+        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then balanced (spreads load across healthy accounts and skips any that are rate-limited). (Legacy `rotate` accepted as alias for `balanced`.)')
         .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for gemini, claude (via @zed-industries/claude-code-acp adapter). Unified event stream; emits ndjson when --json.')
         .option('-y, --yes', 'Skip the interactive budget-confirm prompt (require_confirm_over). Never skips a hard budget block.', false)
         .option('--loop', 'Re-inject the prompt/entrypoint each iteration until a stop condition (issue #332). Guards (--max-iterations, --budget, --until) are enforced outside the agent. Writes a checkpoint after every iteration for --resume-checkpoint.')
@@ -274,9 +276,10 @@ export function registerRunCommand(program) {
         Legacy 'full' is silently rewritten to 'skip'.
 
       Run strategy (set via --strategy or run.<agent>.strategy in agents.yaml):
-        pinned     use the workspace/global pinned version (default)
-        available  use pinned if usage available; otherwise switch to another signed-in version
-        balanced   distribute load across healthy accounts by remaining capacity
+        pinned     use the workspace/global pinned version
+        available  use pinned if it can run right now; otherwise switch to another signed-in version
+        balanced   distribute load across healthy accounts by remaining capacity (default)
+        A version/account is skipped when it is rate-limited right now — any usage window (incl. the 5-hour session window) at 100%, matching the 'agents view' badge.
         --balanced is shorthand for --strategy balanced. Ignored when @version is pinned, when a profile is used, or with --fallback.
 
       Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
@@ -403,15 +406,22 @@ export function registerRunCommand(program) {
                     model: options.model,
                     remoteCwd: options.remoteCwd,
                     sessionId: hostSessionId,
+                    name: options.name,
                     resume: resumeId,
                     follow: options.follow !== false,
                 });
                 // Register the dispatched run in the LOCAL session index so it shows
-                // up in `agents sessions` and resolves by id, even though its
+                // up in `agents sessions` and resolves by id/name, even though its
                 // transcript lives on the host. No-op when no session id was captured.
                 registerHostSession(task, { cwd: process.cwd(), prompt });
                 if (options.follow === false) {
-                    console.log(chalk.green(`Dispatched to ${host.name}.`) + chalk.gray(' Track: agents hosts ps · Follow: agents hosts logs <id> -f'));
+                    // The handle the caller uses to check on the run: the name if given,
+                    // else the real host-task id (never the old literal `<id>`). Steer
+                    // to the compact `agents sessions` digest over the raw log first.
+                    const handle = task.name ?? task.id;
+                    console.log(chalk.green(`Dispatched to ${host.name}${task.name ? ` as "${task.name}"` : ''}.`) + '\n' +
+                        chalk.gray(`  Status:  agents sessions ${handle}`) + chalk.gray('   (compact digest — use this)') + '\n' +
+                        chalk.gray(`  Raw log: agents hosts logs ${handle} -f`) + chalk.gray('   (heavy, only if needed)'));
                     process.exit(0);
                 }
                 // -1 = the follow window closed but the run continues on the host (the
@@ -1061,8 +1071,10 @@ export function registerRunCommand(program) {
             json: options.json,
             headless: options.headless,
             sessionId: resumeSessionId ?? options.sessionId,
+            name: options.name,
             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/hosts.js

@@ -15,7 +15,7 @@ import { sshTargetFor } from '../lib/hosts/types.js';
 import { listSshConfigHosts, listKnownHosts, isSshConfigHost } from '../lib/hosts/ssh-config.js';
 import { probeHost, remoteAgentsVersion, bootstrapAgentsCli, localCliVersion, } from '../lib/hosts/ready.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
-import { listTasks } from '../lib/hosts/tasks.js';
+import { listTasks, loadTask, findTaskByName, findTaskBySessionId } from '../lib/hosts/tasks.js';
 import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
 import { showHostTaskLog } from '../lib/hosts/logs.js';
 /** Parse `user@host` or `host` into its pieces. */
@@ -179,18 +179,22 @@ async function doPs(json) {
         return;
     }
     const cols = terminalWidth();
-    console.log(chalk.bold('ID').padEnd(11) + chalk.bold('HOST').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
+    console.log(chalk.bold('ID').padEnd(11) + chalk.bold('NAME').padEnd(16) + chalk.bold('HOST').padEnd(16) + chalk.bold('AGENT').padEnd(10) + chalk.bold('STATUS').padEnd(11) + chalk.bold('PROMPT'));
     for (const t of tasks) {
         const status = t.status === 'completed' ? chalk.green(t.status) : t.status === 'failed' ? chalk.red(t.status) : chalk.yellow(t.status);
+        const nameCol = truncateToWidth(t.name ?? chalk.gray('-'), 15).padEnd(16);
         // Prompt fills the remaining width instead of a fixed 50-char byte slice (98-char rows).
-        const promptCol = truncateToWidth(t.prompt, Math.max(12, cols - (11 + 16 + 10 + 11)));
-        console.log(t.id.padEnd(11) + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
+        const promptCol = truncateToWidth(t.prompt, Math.max(12, cols - (11 + 16 + 16 + 10 + 11)));
+        console.log(t.id.padEnd(11) + nameCol + t.host.padEnd(16) + t.agent.padEnd(10) + status.padEnd(11) + promptCol);
     }
 }
-async function doLogs(id, follow) {
+async function doLogs(ref, follow) {
+    // Resolve the ref as a task id first, then fall back to a `--name` handle so
+    // `agents hosts logs <name>` works, not just the opaque id.
+    const id = loadTask(ref) ? ref : (findTaskByName(ref)?.id ?? findTaskBySessionId(ref)?.id ?? ref);
     const res = await showHostTaskLog(id, follow);
     if (!res.found) {
-        console.log(chalk.red(`Unknown task "${id}".`));
+        console.log(chalk.red(`Unknown task "${ref}".`));
         process.exitCode = 1;
         return;
     }

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

@@ -36,6 +36,28 @@ export declare function getRunningChromeInfo(profileName: string): {
     pid: number;
     port: number;
 } | null;
+/**
+ * Prepare `<userDataDir>/Default/Preferences` before launch.
+ *
+ * Two concerns, one write:
+ *  - First launch (file absent): stamp the agents-cli profile name so
+ *    Chromium's UI shows "<profile>" instead of its default "Person 1".
+ *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
+ *  - Every launch (when `persistSessionCookies`): pin
+ *    `session.restore_on_startup: 1` ("continue where you left off").
+ *    Chromium purges memory-only session cookies at startup UNLESS this
+ *    preference says the session will be restored — it keys the purge off
+ *    the pref, not off tabs actually reopening. Sites like idealista issue
+ *    login cookies with `expires=-1`, so without this every browser restart
+ *    silently logs the profile out. The visible tab-restore side effect is
+ *    suppressed separately via `--no-startup-window` (see launchBrowser).
+ *
+ * Runs only while the browser is down (called before spawn), so Chromium
+ * can't overwrite the patch on exit. Best-effort: a malformed existing file
+ * is left untouched (Chromium recovers its own state better than we can),
+ * and any I/O hiccup is silently ignored.
+ */
+export declare function ensureProfilePreferences(userDataDir: string, profileName: string, persistSessionCookies: boolean): void;
 /**
  * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
  * (lsof doesn't exist there). Returns false on any tooling error so port

package/dist/lib/browser/chrome.js

@@ -212,11 +212,11 @@ isElectron = false) {
     const runtimeDir = getProfileRuntimeDir(profileName);
     const userDataDir = path.join(runtimeDir, 'chrome-data');
     fs.mkdirSync(userDataDir, { recursive: true });
-    // First-launch seed: stamp the user-data-dir's Default/Preferences with
-    // the agents-cli profile name so Chromium's UI shows "<profile>" instead
-    // of its default "Person 1". Done only when the file doesn't exist —
-    // subsequent launches inherit whatever Chrome wrote in the meantime.
-    seedDefaultProfileName(userDataDir, profileName);
+    // Pre-launch Preferences pass: first-launch profile-name stamp, plus (for
+    // real browsers, not Electron apps) the session-cookie persistence pin.
+    // Electron apps manage their own storage and don't read Chromium's
+    // `session.*` prefs, so they get the name stamp only.
+    ensureProfilePreferences(userDataDir, profileName, !isElectron);
     // Chromium on macOS coordinates instances via the SingletonLock file
     // *inside* each user-data-dir. Direct binary spawn with a fresh
     // --user-data-dir creates a fully independent process — the user's
@@ -242,6 +242,14 @@ isElectron = false) {
         // remote-debugging transport is active. That property is the loudest
         // signal Cloudflare Turnstile, hCaptcha, and similar checks read.
         '--disable-blink-features=AutomationControlled',
+        // Companion to `session.restore_on_startup: 1` (see
+        // ensureProfilePreferences): the pref keeps session cookies alive across
+        // restarts, but on its own it would also reopen last session's tabs at
+        // startup. Suppressing the startup window leaves restore nothing to fill —
+        // cookies survive, no ghost tabs — and the task flow creates its own tab
+        // over CDP anyway. Electron apps need their window to appear (the CDP
+        // driver binds to it), so they skip the flag.
+        ...(isElectron ? [] : ['--no-startup-window']),
         ...(options.headless ? ['--headless=new'] : []),
         `--window-size=${viewport.width},${viewport.height}`,
         ...(viewport.x !== undefined && viewport.y !== undefined
@@ -325,20 +333,52 @@ export function getRunningChromeInfo(profileName) {
     return { pid: rt.pid, port: rt.port };
 }
 /**
- * Stamp `<userDataDir>/Default/Preferences` with our profile name so
- * Chrome's UI labels the window with the agents-cli name rather than the
- * default "Person 1". Only writes when the file is absent (first launch).
- * Best-effort: any I/O hiccup is silently ignored; missing the rename is
- * cosmetic, not functional.
+ * Prepare `<userDataDir>/Default/Preferences` before launch.
+ *
+ * Two concerns, one write:
+ *  - First launch (file absent): stamp the agents-cli profile name so
+ *    Chromium's UI shows "<profile>" instead of its default "Person 1".
+ *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
+ *  - Every launch (when `persistSessionCookies`): pin
+ *    `session.restore_on_startup: 1` ("continue where you left off").
+ *    Chromium purges memory-only session cookies at startup UNLESS this
+ *    preference says the session will be restored — it keys the purge off
+ *    the pref, not off tabs actually reopening. Sites like idealista issue
+ *    login cookies with `expires=-1`, so without this every browser restart
+ *    silently logs the profile out. The visible tab-restore side effect is
+ *    suppressed separately via `--no-startup-window` (see launchBrowser).
+ *
+ * Runs only while the browser is down (called before spawn), so Chromium
+ * can't overwrite the patch on exit. Best-effort: a malformed existing file
+ * is left untouched (Chromium recovers its own state better than we can),
+ * and any I/O hiccup is silently ignored.
  */
-function seedDefaultProfileName(userDataDir, profileName) {
+export function ensureProfilePreferences(userDataDir, profileName, persistSessionCookies) {
     const defaultDir = path.join(userDataDir, 'Default');
     const prefsPath = path.join(defaultDir, 'Preferences');
-    if (fs.existsSync(prefsPath))
+    let prefs;
+    try {
+        prefs = JSON.parse(fs.readFileSync(prefsPath, 'utf8'));
+        if (typeof prefs !== 'object' || prefs === null)
+            return; // not ours to fix
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            return; // unreadable/malformed: leave alone
+    }
+    const firstLaunch = prefs === undefined;
+    if (firstLaunch)
+        prefs = { profile: { name: profileName } };
+    let dirty = firstLaunch;
+    if (persistSessionCookies && prefs.session?.restore_on_startup !== 1) {
+        prefs.session = { ...prefs.session, restore_on_startup: 1 };
+        dirty = true;
+    }
+    if (!dirty)
         return;
     try {
         fs.mkdirSync(defaultDir, { recursive: true });
-        fs.writeFileSync(prefsPath, JSON.stringify({ profile: { name: profileName } }));
+        fs.writeFileSync(prefsPath, JSON.stringify(prefs));
     }
     catch { /* not critical */ }
 }

package/dist/lib/browser/service.js

@@ -310,6 +310,19 @@ export class BrowserService {
             conn = await this.connectProfile(effectiveProfile, resolved.target);
             this.connections.set(composite, conn);
         }
+        // Browsers launch with --no-startup-window (session-cookie persistence,
+        // see launchBrowser), so a bare `start` with no --url would otherwise
+        // leave the user staring at a process with zero windows. Recreate the
+        // old startup-window affordance: if no page target exists, open a blank
+        // one. Deliberately NOT registered on the task — the startup window
+        // never was either, and tasks track only tabs they created.
+        if (!opts.url && !conn.electron) {
+            const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+            if (!targetInfos.some((t) => t.type === 'page')) {
+                await conn.cdp.send('Target.createTarget', { url: 'about:blank' });
+                this.invalidateTargetCache(conn);
+            }
+        }
         const task = {
             id: taskId,
             name: taskName,

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

@@ -80,6 +80,13 @@ export interface ExecOptions {
     addDirs?: string[];
     timeout?: string;
     sessionId?: string;
+    /**
+     * Durable `agents run --name <slug>` handle. Exported to the agent's env as
+     * `AGENT_SESSION_NAME` (companion to `AGENT_SESSION_ID`) and, when a session
+     * id is known at launch, recorded in the run-name index so `agents sessions
+     * <name>` resolves the run. Absent for unnamed runs — no behavior change.
+     */
+    name?: string;
     /**
      * Resume the conversation named by `sessionId` using the agent's NATIVE resume
      * form (claude `--resume`, codex `resume`) instead of the default `--session-id`
@@ -109,6 +116,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 +226,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;
 /**