@phnx-labs/agents-cli 1.22.32 → 1.22.34

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 1.22.34
+
+- **A failed `agents teams add` no longer strands an `agents/<name>` branch that breaks every retry (RUSH-2356).** The worktree was created before the teammate record was persisted and nothing removed it when the add failed, so the next `teams add` with the same `--worktree` name died on `fatal: a branch named 'agents/<name>' already exists` — observed 2026-08-07, forcing three renames before a teammate could be created. Two guarantees now hold. Name uniqueness and the `--after` dependency graph are validated **before** `createWorktree` runs (`AgentManager.validateAddPreconditions`), so a duplicate name, unknown dependency, or cycle never creates a branch at all. A failure **after** the worktree exists — a missing harness CLI, a launch error, a cloud dispatch failure — removes the worktree and its branch before the command exits non-zero, and prints the exact `git worktree remove` / `git branch -D` pair if that teardown itself fails. Teardown is scoped twice over, because deleting a live teammate's worktree would destroy real work: only a worktree that same add created is a candidate, and only when no live teammate claims it (`AgentManager.isWorktreeClaimed`, a raw meta.json scan across every team, counting only non-terminal records). That second check matters because the add can fail *after* the record is durably saved — `spawn()` saves a staged teammate and only then runs the retention pass, which refreshes every sibling and can throw on a distributed one — so a teammate already recorded and waiting on an `--after` dependency keeps its worktree. If we can't prove a worktree is an orphan, it is left in place with the manual removal printed — the claim check **fails closed**, so an unreadable or half-written record answers "claimed" rather than "free": only a genuinely absent record (ENOENT) proves nothing claims the worktree, because the alternative error deletes a running teammate's uncommitted work. The pr-watch fixer path (`reactWithTeammate`) and a partially-failed `createWorktree` (branch ref created, checkout not) run the same guarded teardown — the fixer path matters because it stages its teammate with `--after` when it follows a source teammate, so it can reach the failure branch with a live, durably-recorded, merely-pending teammate already owning the worktree.
+
+  One user-visible surface change: a duplicate name, unknown `--after` dependency, or dependency cycle is now rejected before the worktree step, so it surfaces as the raw validation message under the friction id `teams/add-precondition-failed` rather than wrapped in `Could not add <agent> to <team>:` under `teams/add-failed`. Source: `apps/cli/src/commands/teams.ts`, `apps/cli/src/lib/teams/agents.ts`.
+
+- **`teams add` no longer silently discards pending teammates past the retention cap (RUSH-2356).** `listCompleted()` classified every non-RUNNING status — including `pending` — as "completed", so `cleanupOldAgents()` reaped staged `--after` teammates once the team's history crossed the 50-record cap: `teams add --after` printed a full success block for a teammate whose record then vanished. Retention now filters on a real terminal-status set (`completed`/`failed`/`stopped`); a pending or running teammate is never a reap candidate. `spawn()` also asserts its record is durably on disk right after writing it, so a failed write can no longer report success for a teammate that doesn't exist. Source: `apps/cli/src/lib/teams/agents.ts`.
+
+- **A session recorded on Windows no longer has its `cwd` corrupted when read on macOS or Linux (RUSH-2358).** `normalizeCwd()` is the shared cwd-normalisation path for every harness's session filtering and display, and its fallback used `path.isAbsolute(cwd)` — which is platform-relative. A Windows-rooted path (`C:\Users\dev\repo\...`) is not absolute *on POSIX*, so it fell through to `path.resolve()`, which silently prefixed the reading process's own working directory onto it. Transcripts sync across the fleet, so any session captured on a Windows box and indexed on a POSIX box has carried a corrupted `cwd` since the fallback was introduced — visible as wrong directory attribution in `agents sessions` filtering and display, and as a lost `worktree_slug`. The normalisation now recognises a Windows-rooted path (drive letter or UNC) on POSIX and treats it as already absolute, mirroring the existing branch that recognises a POSIX-rooted path on Windows. Source: `apps/cli/src/lib/session/discover.ts`.
+
+- **A dead `--device` teammate no longer reports RUNNING forever, and `resume` relaunches it (RUSH-2366).** The remote liveness probe only distinguished "`.exit` sentinel present" from "absent" — a process killed before it could write its exit code (SIGKILL, OOM, box lost) fell into the same "absent" bucket as a still-running teammate and stayed RUNNING indefinitely, so `agents teams resume` kept routing it to steer/mailbox instead of relaunching. The probe now resolves three states (ALIVE / EXITED / GONE) in one round-trip; GONE (process confirmed dead, no sentinel) latches FAILED. A separate stale-manager race is also fixed: a long-lived `teams start --watch` supervisor's cached teammate could re-persist a stale in-memory RUNNING over a terminal status a different CLI invocation (`agents teams stop`) had just written to disk — `updateStatusFromProcess()` and `rescanFromDisk()` now adopt a newer on-disk terminal status instead of overwriting it. Source: `apps/cli/src/lib/teams/agents.ts`.
+- **`agents message` can now reach a detached `agents run --device <host> --no-follow` dispatch (RUSH-2366 follow-up).** `getActiveSessions()` has no visibility into a detached dispatch's live remote process — only `~/.agents/.cache/hosts/<id>.json` (the record `agents hosts ps` reads) does — so `agents message <name>` reported "No running agent... matches" for a dispatch `agents hosts ps` showed running with a live pid, and the only recovery was killing and re-dispatching it (losing all context). `agents message` now resolves the same host-task records and reroutes the message over the existing `--host` passthrough to the box that actually owns it, or fails with an actionable "already `<status>`" message when the dispatch has already finished. It heals the dispatch record with `reconcileRunningTasks` before deciding, the same step `agents hosts stop`/`ps` already take — a detached record never self-updates, so a finished run stays stamped `running` on disk and would otherwise be routed through an SSH reroute that could only fail instead of being reported finished locally. Source: `apps/cli/src/commands/message.ts`, `apps/cli/src/lib/mailbox-target.ts`, `apps/cli/src/lib/hosts/tasks.ts`.
+- **`teams add --worktree` no longer nests a new worktree inside another teammate's worktree (RUSH-2366 follow-up).** When the caller's ambient cwd was already inside a linked worktree (e.g. an orchestrator agent dispatching `teams add` from within its own worktree), `createWorktree` resolved the placement root via `git rev-parse --show-toplevel`, which returns that worktree's OWN root rather than the main checkout's — landing the new worktree at `.../worktrees/A/.agents/worktrees/B`. Cleaning up A then destroyed B along with it, even though B's commit history survived on its branch ref. `createWorktree`/`removeWorktree` now resolve via `getMainRepoRoot()` (the existing `git-common-dir`-based helper), which always points at the main checkout regardless of which worktree the caller is standing in. Source: `apps/cli/src/lib/teams/worktree.ts`.
+
+- **An interactive Claude run authenticates from your own login again, not the headless setup-token (RUSH-2395).** `buildExecEnv` injected the `auth` bundle's per-account setup-token into `CLAUDE_CODE_OAUTH_TOKEN` for *every* resolved Claude launch, so a hand-driven session on a personal machine reported `Auth token: CLAUDE_CODE_OAUTH_TOKEN` in `/status` and ran on the probe credential instead of the login the user had established. That token exists for runs with no human present (usage probes, routines, dispatched runs), and it is `user:inference`-scoped, so it also cannot read usage (RUSH-2392). Injection is now gated on the run resolving **headless**; an interactive run is left on its per-version login, and an inherited copy of that same token is dropped so a nested interactive launch from inside a headless agent's shell does not keep authenticating as it. A token the caller exported themselves is matched by value and left alone. Source: `apps/cli/src/lib/exec.ts`.
+
+- **Multiple Cursor accounts are now real — each run authenticates as the account you pick (RUSH-2400).** Previously `agents view cursor` showed several Cursor accounts and balanced rotation picked one, but every run silently authenticated as the single live `~/.cursor` login: `buildExecEnv` gave Cursor no per-account isolation, so the version/account you selected was discarded at exec. Cursor has no config-dir env var, but its OAuth token — the login gate — lives at `$XDG_CONFIG_HOME/cursor/auth.json` (verified empirically; `~/.cursor/cli-config.json` is only metadata). `buildExecEnv` and the versioned-alias shim now pin `XDG_CONFIG_HOME` at the version home for Cursor (the same XDG mechanism muse uses), so `agents run cursor@<account>`, the account picker, and balanced rotation each launch `cursor-agent` authenticated as that account's own token — isolated per child process, so two accounts run concurrently without clobbering one another. `agents view cursor` now verifies each account's signed-in state against its own token (`CREDENTIAL_FILE_SEGMENTS.cursor`), and a migration seeds the current global login into the active account's home so no one is logged out on upgrade. The routine overlay path is unchanged (seeds from the active login by design). Source: `apps/cli/src/lib/exec.ts`, `apps/cli/src/lib/shims.ts`, `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/migrate.ts`.
+
+- **`agents browser sessions` / `agents sessions --browser` is task-first, with agent outcome previews (RUSH-2407).** On a TTY, the picker now groups every screenshot, PDF, and recording by browser task instead of printing one row per file, newest task first. A task whose `launchId` still resolves to an indexed agent session shows the canonical session digest (prompt, changes, tests, last response) before its captures; a task whose owning run already stopped is labeled unlinked rather than silently dropped. Downloads get their own group. Search matches task name, profile, the linked session's agent/topic, or an artifact filename; `enter` opens the highlighted capture (or drills into a capture list first for a multi-capture task). New `--no-interactive` flag prints the previous flat table; `--json` output is unchanged. Source: `apps/cli/src/lib/browser/sessions-list.ts`, `apps/cli/src/commands/browser-sessions-picker.ts`.
+
+- **`agents sessions --routine` is outcome-aware: run history, then linked sessions (RUSH-2409).** Selecting a routine now renders its canonical run history first — every run's id, trigger, status (completed/failed/blocked/skipped/missed), start/duration, exit/error, execution type (agent/command/workflow), placement (local/host/cloud), and log/report paths — and links each run to the indexed agent session(s) it produced (agent/version/account/model/token/cost/duration/tool metadata). A command-only routine (e.g. `auto-dispatch`, which produces no transcript) no longer dead-ends into the generic "No sessions found" copy: it shows its runs and states plainly that no agent session is produced, and command/blocked/skipped/missed attempts appear with no fabricated session row. Counts distinguish run records from linked sessions, and routine selection stays global across every working directory. The drilldown is the default routine view; an explicit `--flat`/`--tree` or a session id/query keeps the scoped session listing/picker. The canonical source is the run history under `~/.agents/.history/runs/<routine>/` (`listRuns`), not the session index — no divergent state added. Source: `apps/cli/src/commands/sessions.ts`.
+
+- **Inspect Watchdog decisions and actions from the CLI (RUSH-2410).** `agents watchdog history [sessionId]` renders every session inspection plus persisted decisions, nudges, rotates, and errors newest-first, with duration/limit filters, optional heartbeat rows, and safe JSON that excludes transcript content. The audit retains 5,000 events, and persisted transcript context is capped at 4,096 characters per event. `agents watchdog status` points to the history command instead of leaving the audit log undiscoverable. Source: `apps/cli/src/commands/watchdog.ts`, `apps/cli/src/lib/watchdog/{runner,log,history}.ts`.
+
+- **`agents ssh <device>` mirrors your project directory on interactive login (RUSH-2412).**
+  An interactive `agents ssh <device>` with no command now starts the remote login
+  shell in the same home-relative directory you launched from — `agents ssh
+  yosemite-s0` from `~/src/app` lands in `~/src/app` on the target when it exists,
+  else the remote home — matching `agents run --host`. It reuses the one canonical
+  portable-cwd resolver (`deriveMirroredCwd` / `remoteCdPrefix`), is best-effort (a
+  missing checkout never fails the login), injection-safe for paths with spaces or
+  metacharacters, and covers POSIX and Windows PowerShell. An explicit `agents ssh
+  <device> <cmd…>` is unchanged. Source: `apps/cli/src/lib/devices/connect.ts`,
+  `apps/cli/src/lib/project-root.ts`, `apps/cli/src/commands/ssh.ts`.
+
+- **Make live Watchdog ticks explain each session (RUSH-2416).** `agents watchdog` now prints the tick date/time and attention-worthy sessions with their stable id, label/topic, agent, host app, machine, project, activity, start/activity ages, cwd, latest preview, and exact decision reason. Healthy/non-actionable inspections collapse into one count; `--verbose` restores every row and `--json` remains the complete machine-readable result. Source: `apps/cli/src/commands/watchdog.ts`, `apps/cli/src/lib/watchdog/runner.ts`.
+
+- **`agents daemon start` no longer defeats its own launchd/systemd launch (RUSH-2417).** `startDaemon()` and the daemon child's `claimDaemonInstance()` resolve the same `<daemonDir>/daemon.lock`, and the launchd/systemd branches busy-waited on `waitForPid(3000)` while still holding it — the release only happened in `startDaemon`'s outer `finally`. The freshly-launched daemon therefore hit `EEXIST` against a holder that was alive (the parent CLI process) and exited with the false "another daemon is mid-takeover" warning, so the service-manager fast-start path failed deterministically on every fresh install and fell back to a detached spawn. The start lock is now released the moment the launch has been issued — after `launchctl load` / `systemctl start` / the detached spawn — instead of after the pid wait. The concurrent-start guarantee is unchanged: two `startDaemon()` calls still cannot both launch, because launchd (one plist label) and systemd (one unit) no-op a second start and the detached path is covered by `claimDaemonInstance`'s last-wins takeover (SING-11). Source: `apps/cli/src/lib/daemon.ts`.
+
+- **Reap orphaned keychain `watch-lock` helpers after ungraceful daemon death (RUSH-2419); await secrets broker socket release on close (RUSH-2421).** The auto-lock-on-sleep watcher is still never killed while its owning daemon is alive, but a separate reaper path now cleans it up once the parent is provably gone (OOM, SIGKILL, killTree) — closing the leak that only `close()` used to handle. Hosted and standalone broker `close()` now wait for `net.Server`'s `close` event with a 2s bound so a successor cannot race a half-released socket. Source: `apps/cli/src/lib/secrets/reaper.ts`, `apps/cli/src/lib/secrets/agent.ts`.
+
+* **Searchable command API reference.** `apps/cli/docs/command-reference.html` is generated from the complete registered Commander tree and covers every visible command and nested subcommand, argument, flag form, choice, default, alias, example, and note. `npm run verify:index` now fails when the HTML or canonical JSON drifts from the CLI. Source: `apps/cli/scripts/gen-command-index.ts`.
+
+- **`agents inspect` drill-downs render readable previews and return the resources that actually exist.** The detail view wrapped a description at a hardcoded 100 characters regardless of terminal width, so a long plugin or skill description lost its sentence at 80 columns and wasted the space at 200; it now wraps to the real width, and detail rows are width-aware too. `--rules` listed the composed `AGENTS.md` output and its symlinks while hiding every fragment under `rules/subrules/`, so `agents inspect . --rule foundations` exited 1 — rules now resolve from `subrules/`. `--hooks` did a flat `readdir` and reported the event directories plus doc files, disagreeing with the count the summary view printed for the same repo (12 vs 39); both now read through `listHookEntriesFromDir`. Plugin detail gains the bundle's real recursive size instead of `(bundle)`, plus its `author`, `dependencies`, and which execution surfaces it ships (`hooks/`, `bin/`, `.mcp.json`, …) — `author` was present in every `plugin.json` on disk but missing from the `PluginManifest` type, so nothing read it. Source: `apps/cli/src/commands/inspect.ts`, `apps/cli/src/lib/types.ts`.
+
+- **`agents inspect` no longer crashes when a `plugin.json` or `agents.yaml` field's JSON/YAML type contradicts the interface it is cast to.** `loadPluginManifest` and the `agents.yaml` hook reader both cast parsed input straight to a typed shape and validate almost nothing, so any field can be a string where an array was declared, or a number where a string was. Four crashes came from that: `"dependencies": "some-plugin"` reached `.join()` (truthy `.length`, no `.join`) *while building the plugin list*, so one bad manifest took down `agents inspect .`, `--plugins`, `--json`, and even a query for a different, valid plugin; a numeric `"version"` and a non-string `"description"` threw later at render, breaking the detail view and (for `description`) the plugin list; and in `agents.yaml`, a scalar `events: PreToolUse` or a numeric `matches.prompt_contains` threw in `summarizeHook`, breaking bare `agents inspect <repo>` and — through the user-level manifest — `agents inspect <agent>` on every machine. Every uncontrolled field now routes through one of two coercion helpers, so a scalar renders where a list was expected and an object drops its row instead of printing `[object Object]`. Source: `apps/cli/src/commands/inspect.ts`.
+
+- **One malformed `mcp/*.yaml` no longer takes down `agents inspect <repo>` with an unhandled stack trace.** `validateMcpYamlConfig` returns `null` for some bad shapes but *throws* for others — `args` that is not a string array, a non-string `command`, a non-map `env` — and the three directory scans that call it (`discoverMcpConfigsFromRepo`, `listMcpServerConfigs`, and the layered project/user MCP resource scan in `versions.ts`) let that throw escape, so a single bad file in a cloned repo crashed the whole command and hid the valid configs beside it. Scans now skip the offending file and name it on stderr, exactly as they already skip a `null`; explicit single-file operations still throw loudly. Source: `apps/cli/src/lib/mcp.ts`, `apps/cli/src/lib/versions.ts`.
+
+## 1.22.33
+
+- **Release tags are annotated with the folded changelog notes.** `scripts/release.sh` now creates `v<version>` as an annotated tag whose message is `Release <version>` plus the body of `.changelog/<version>.md` (the same notes that already become the release PR body). Agents keep writing one fragment under `.changelog/next/`; there is no separate tag-description channel. The already-published missing-tag recovery path uses the same helper with `--force`. Source: `apps/cli/scripts/release.sh`.
+
+`agents sessions --routines` once again opens the routine picker across every working directory instead of an empty current-repository session browser.
+
 ## 1.22.32
 
 - **Routines validate execution context before activation and fire once per schedule slot (RUSH-2290).** A routine selects one execution `project` plus a portable `cwd`; add/edit save proven blockers paused, durable slot and active-run claims prevent duplicate or overlapping launches, and every blocked/skipped/pre-spawn attempt remains visible without requiring a session transcript. Source: `apps/cli/src/lib/routine-context.ts`, `apps/cli/src/lib/routine-readiness.ts`, `apps/cli/src/lib/runner.ts`.

package/README.md

@@ -428,11 +428,12 @@ Top-level questions and waiting notifications publish one atomic open-block reco
 
 ```bash
 agents watchdog            # one tick, dry run — reports what it WOULD nudge and why
+agents watchdog --verbose  # include healthy/non-actionable session inspections
 agents watchdog --nudge    # actually inject "Continue." into the stalled split
 agents watchdog --watch    # daemon loop: a tick every --interval
 ```
 
-`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. It's dry by default; `--nudge` acts on a single tick. `agents watchdog on|off` controls the device-local daemon pass, which runs once every three minutes. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
+`agents watchdog` detects a stalled session, resolves the *exact* terminal split it lives in (tmux, iTerm, VSCodium, or a raw pty), and injects a nudge -- `Continue.` by default, or set `--text`. Its timestamped default output shows attention-worthy sessions with their agent, host app, machine, project, activity, age, path, latest preview, and decision reason; `--verbose` restores healthy/non-actionable inspections. It's dry by default; `--nudge` acts on a single tick. `agents watchdog on|off` controls the device-local daemon pass, which runs once every three minutes. Steer a single run with `agents watchdog policy <id> off | keep | handsoff`.
 
 A stalled session whose tail shows a hard account limit ("You've hit your weekly limit · resets …") is **rotated in place** instead of nudged: the watchdog gates on the same healthy-account selection `agents run auto` makes (zero healthy → one skip event per cooldown window, terminal untouched), injects the harness's exit sequence, relaunches `agents run auto --interactive --session-id <uuid>` in the *same* tab, then replays the old session's resume once the new TUI is live. Default on; `agents watchdog rotate off` disables it (nudging stays on).
 

package/dist/commands/accounts.js

@@ -24,9 +24,9 @@ async function chooseAccount() { const accounts = await discoverAccounts(); if (
     throw new Error('No signed-in accounts found. Run an installed agent and complete its normal login first.'); return select({ message: 'Which signed-in account do you want to name?', choices: accounts.map(account => ({ name: `${account.agent}  ${account.display}  (${account.versions.length} version${account.versions.length === 1 ? '' : 's'})${account.label ? `  currently “${account.label}”` : ''}`, value: account })) }); }
 export function registerAccountsCommand(program) {
     const accounts = program.command('accounts').description('Browse and name signed-in harness accounts').option('--json', 'Machine-readable discovered accounts').action(async (o) => printAccounts(!!o.json));
-    accounts.command('list').description('Alias for accounts').option('--json').action((o) => printAccounts(!!o.json));
+    accounts.command('list').description('Alias for accounts').option('--json', 'Machine-readable discovered accounts').action((o) => printAccounts(!!o.json));
     accounts.command('name <label>').description('Name one signed-in account; matching installed versions are found automatically').option('--from <agent@version>', 'Non-interactive identity source').action(async (label, o) => { const picked = o.from ? await fingerprintFromSource(o.from) : await chooseAccount(); nameAccount(label, picked.agent, picked.fingerprint); console.log(chalk.green(`Named the ${picked.agent} account '${label}'.`)); console.log(chalk.gray(`Found it in ${picked.versions.length} installed version${picked.versions.length === 1 ? '' : 's'}: ${picked.versions.join(', ')}`)); });
-    accounts.command('rename <old> <new>').action((oldLabel, newLabel) => renameAccountLabel(oldLabel, newLabel));
-    accounts.command('remove <label>').action((label) => removeAccountLabel(label));
+    accounts.command('rename <old> <new>').description('Rename a saved account label').action((oldLabel, newLabel) => renameAccountLabel(oldLabel, newLabel));
+    accounts.command('remove <label>').description('Remove a saved account label').action((label) => removeAccountLabel(label));
     setHelpSections(accounts, { examples: `agents accounts\nagents accounts name work\nagents accounts name work --from claude@2.1.220\nagents run claude --account work`, notes: 'First run the harness and complete its normal login. A label names one provider account; every matching installed version is discovered automatically. OAuth credentials are never copied or shared.' });
 }

package/dist/commands/browser-sessions-picker.d.ts

@@ -0,0 +1,16 @@
+export interface BrowserSessionsCommandOpts {
+    profile?: string;
+    open?: string | boolean;
+    json?: boolean;
+    /** Commander's `--no-interactive` convention: `false` opts out. */
+    interactive?: boolean;
+}
+/** True when the interactive picker should open instead of the printed table:
+ *  a real TTY, no `--json`/`--open`, and `--no-interactive` not set. */
+export declare function shouldOpenInteractiveBrowserSessions(opts: BrowserSessionsCommandOpts, isTTY: boolean): boolean;
+/**
+ * Shared entry point for `agents browser sessions` and `agents sessions
+ * --browser`. Replaces direct calls to `runBrowserSessions` at both call
+ * sites so the interactive routing decision lives in one place.
+ */
+export declare function runBrowserSessionsCommand(opts: BrowserSessionsCommandOpts): Promise<void>;

package/dist/commands/browser-sessions-picker.js

@@ -0,0 +1,179 @@
+/**
+ * Interactive, task-first `agents browser sessions` / `agents sessions --browser`
+ * view (RUSH-2407). Backs the TTY path only — non-TTY, `--json`, `--open`, and
+ * `--no-interactive` all fall straight through to the existing flat printer in
+ * `lib/browser/sessions-list.ts` (unchanged, so `--json` stays a stable surface).
+ *
+ * Reuses the same `itemPicker` + `buildPreview` primitives as the ordinary
+ * session picker (`sessions-picker.ts`) — same search/filter/quit help, and the
+ * preview pane for a linked task IS the canonical session digest, not a
+ * second renderer.
+ */
+import chalk from 'chalk';
+import { itemPicker } from '../lib/picker.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { buildPreview } from './sessions-picker.js';
+import { runBrowserSessions, buildBrowserSessionRows, matchesBrowserSessionRow, openArtifact, formatBytes, } from '../lib/browser/sessions-list.js';
+import { formatRelativeTime } from '../lib/session/relative-time.js';
+/** True when the interactive picker should open instead of the printed table:
+ *  a real TTY, no `--json`/`--open`, and `--no-interactive` not set. */
+export function shouldOpenInteractiveBrowserSessions(opts, isTTY) {
+    return opts.interactive !== false && !opts.json && opts.open === undefined && isTTY;
+}
+/**
+ * Shared entry point for `agents browser sessions` and `agents sessions
+ * --browser`. Replaces direct calls to `runBrowserSessions` at both call
+ * sites so the interactive routing decision lives in one place.
+ */
+export async function runBrowserSessionsCommand(opts) {
+    if (!shouldOpenInteractiveBrowserSessions(opts, isInteractiveTerminal())) {
+        runBrowserSessions({ profile: opts.profile, open: opts.open, json: opts.json });
+        return;
+    }
+    const rows = buildBrowserSessionRows(opts.profile);
+    if (rows.length === 0) {
+        console.log(`No browser captures found${opts.profile ? ` for profile "${opts.profile}"` : ''}.`);
+        return;
+    }
+    await browseAndOpen(rows);
+}
+const KIND_LABEL = {
+    screenshot: 'shots',
+    pdf: 'pdf',
+    recording: 'rec',
+    download: 'dl',
+};
+function formatCounts(counts) {
+    const parts = [];
+    for (const kind of Object.keys(KIND_LABEL)) {
+        if (counts[kind] > 0)
+            parts.push(`${KIND_LABEL[kind]} ${counts[kind]}`);
+    }
+    return parts.join(' · ') || '-';
+}
+function rowLinkSummary(row) {
+    if (row.kind === 'downloads')
+        return '';
+    if (row.linkStatus === 'linked' && row.linkedSession) {
+        const s = row.linkedSession;
+        return chalk.cyan(s.agent) + ' — ' + (s.label || s.topic || s.shortId);
+    }
+    if (row.linkStatus === 'unresolved') {
+        return chalk.yellow(`owner ${row.owner ?? 'unknown'} (session not indexed here)`);
+    }
+    return chalk.gray('unlinked');
+}
+function formatRowLabel(row) {
+    // Pad the raw text first, THEN colorize — padEnd on an already-chalked
+    // string counts the ANSI escape bytes as width and misaligns the column.
+    const name = (row.kind === 'downloads' ? '[downloads]' : (row.task ?? '')).padEnd(30);
+    const coloredName = row.kind === 'downloads' ? chalk.gray(name) : name;
+    const age = formatRelativeTime(new Date(row.latestMtimeMs).toISOString());
+    const counts = formatCounts(row.counts);
+    return [
+        coloredName,
+        row.profile.padEnd(26),
+        age.padEnd(11),
+        counts.padEnd(18),
+        rowLinkSummary(row),
+    ].join(' ');
+}
+const PREVIEW_ARTIFACT_LIMIT = 12;
+function buildRowPreview(row) {
+    const parts = [];
+    if (row.kind === 'downloads') {
+        parts.push(chalk.bold(`${row.profile} — downloads`));
+    }
+    else if (row.linkStatus === 'linked' && row.linkedSession) {
+        parts.push(buildPreview(row.linkedSession));
+    }
+    else if (row.linkStatus === 'unresolved') {
+        parts.push(chalk.yellow(`owner ${row.owner ?? 'unknown'} — launch ${row.launchId} has no indexed session on this machine.`));
+    }
+    else {
+        parts.push(chalk.gray(`Unlinked — no owning agent session is known for this task`
+            + (row.owner ? ` (last known owner: ${row.owner}).` : '.')));
+    }
+    parts.push('');
+    parts.push(chalk.bold(`Captures (${row.artifacts.length})`));
+    for (const a of row.artifacts.slice(0, PREVIEW_ARTIFACT_LIMIT)) {
+        const age = formatRelativeTime(new Date(a.mtimeMs).toISOString());
+        parts.push(`  ${age.padEnd(11)}  ${a.name.padEnd(30)}  ${formatBytes(a.bytes).padStart(8)}`);
+    }
+    const more = row.artifacts.length - PREVIEW_ARTIFACT_LIMIT;
+    if (more > 0)
+        parts.push(chalk.gray(`  … (${more} more)`));
+    return parts.join('\n');
+}
+function formatArtifactLabel(a) {
+    const age = formatRelativeTime(new Date(a.mtimeMs).toISOString());
+    return `${age.padEnd(11)}  ${a.name.padEnd(34)}  ${formatBytes(a.bytes).padStart(8)}`;
+}
+/** Open one artifact in the OS default app, printing its path (matches the
+ *  non-interactive `--open` behavior) and any open failure. */
+function openAndReport(a) {
+    console.log(a.path);
+    if (!openArtifact(a.path))
+        console.error(`Could not open ${a.path}`);
+}
+/** Task-level picker with a captures preview, then an artifact drill-down when
+ *  a task holds more than one capture. Loops until the user quits (esc) so a
+ *  capture-heavy task can be browsed and opened repeatedly in one session. */
+async function browseAndOpen(rows) {
+    for (;;) {
+        let picked;
+        try {
+            picked = await itemPicker({
+                message: 'Browser sessions:',
+                items: rows,
+                filter: (query) => (query.trim() ? rows.filter((r) => matchesBrowserSessionRow(r, query)) : rows),
+                labelFor: (row) => formatRowLabel(row),
+                buildPreview: (row) => buildRowPreview(row),
+                emptyMessage: 'No browser sessions match.',
+                enterHint: 'open capture',
+            });
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            throw err;
+        }
+        if (!picked)
+            return;
+        const row = picked.item;
+        if (row.artifacts.length === 0) {
+            console.log('No captures in this task yet.');
+            continue;
+        }
+        if (row.artifacts.length === 1) {
+            openAndReport(row.artifacts[0]);
+            continue;
+        }
+        const artifact = await pickArtifact(row);
+        if (artifact)
+            openAndReport(artifact);
+    }
+}
+/** Second-level picker over one row's captures, newest first. Enter opens the
+ *  highlighted capture; esc returns to the task list. */
+async function pickArtifact(row) {
+    try {
+        const picked = await itemPicker({
+            message: `Captures — ${row.task ?? 'downloads'} (${row.profile}):`,
+            items: row.artifacts,
+            filter: (query) => {
+                const q = query.trim().toLowerCase();
+                return q ? row.artifacts.filter((a) => a.name.toLowerCase().includes(q)) : row.artifacts;
+            },
+            labelFor: (a) => formatArtifactLabel(a),
+            emptyMessage: 'No captures.',
+            enterHint: 'open',
+        });
+        return picked?.item ?? null;
+    }
+    catch (err) {
+        if (isPromptCancelled(err))
+            return null;
+        throw err;
+    }
+}

package/dist/commands/browser.js

@@ -9,7 +9,7 @@ import { readAndResolveBundleEnv, bundleExists, readBundle, describeBundle } fro
 import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
-import { runBrowserSessions } from '../lib/browser/sessions-list.js';
+import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
 import { parseTargetFilter } from '../lib/browser/service.js';
 import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendIPCRequest, } from '../lib/browser/ipc.js';
@@ -58,6 +58,7 @@ const BROWSER_HELP_GROUPS = [
         title: 'Capture evidence',
         names: ['console', 'errors', 'requests', 'responsebody', 'record', 'pdf', 'logs'],
     },
+    { title: 'History and discovery', names: ['sessions', 'history', 'refs'] },
 ];
 export function registerBrowserCommand(program) {
     const browser = program
@@ -87,6 +88,9 @@ export function registerBrowserCommand(program) {
       # Drive another machine's browser (needs its consent — see remote-control)
       agents browser start --host zion
 
+      # Browse a task-heavy profile's captures: one row per task, not per file
+      agents browser sessions
+
       # Allow / deny other fleet machines driving THIS machine's browser
       agents browser remote-control on
 
@@ -1967,12 +1971,13 @@ function registerTaskCommands(browser) {
     });
     browser
         .command('sessions')
-        .description('List a profile\'s captured screenshots, PDFs, recordings, and downloads')
+        .description('Browse a profile\'s captured screenshots, PDFs, recordings, and downloads, grouped by task')
         .option('--profile <name>', 'Only this profile (default: all profiles with captures)')
         .option('--open [selector]', "Open a capture in the OS default app: 'latest' or a filename")
         .option('--json', 'Emit machine-readable JSON')
-        .action((opts) => {
-        runBrowserSessions({ profile: opts.profile, open: opts.open, json: opts.json });
+        .option('--no-interactive', 'Print the flat listing instead of opening the interactive task browser')
+        .action(async (opts) => {
+        await runBrowserSessionsCommand({ profile: opts.profile, open: opts.open, json: opts.json, interactive: opts.interactive });
     });
     // ─── Recording ─────────────────────────────────────────────────────────────
     const record = browser.command('record').description('Record a video of the page');

package/dist/commands/hosts.js

@@ -17,7 +17,7 @@ import { hostIdentityArgs, 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, loadTask, findTaskByName, findTaskBySessionId } from '../lib/hosts/tasks.js';
+import { listTasks, loadTask, findTaskByName, findTaskBySessionId, resolveTaskRef } from '../lib/hosts/tasks.js';
 import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
 import { showHostTaskLog } from '../lib/hosts/logs.js';
 import { stopDispatchedTask } from '../lib/hosts/dispatch.js';
@@ -252,10 +252,6 @@ async function doLogs(ref, follow, full) {
     if (res.exitCode !== undefined)
         process.exitCode = res.exitCode;
 }
-/** Resolve a host-task ref (id, --name handle, or session id) or null. */
-function resolveTaskRef(ref) {
-    return loadTask(ref) ?? findTaskByName(ref) ?? findTaskBySessionId(ref);
-}
 async function doStop(ref) {
     // Heal first so we don't try to kill a process that already exited.
     const current = resolveTaskRef(ref);