@phnx-labs/agents-cli 1.22.23 → 1.22.24

package/CHANGELOG.md

@@ -1,5 +1,198 @@
 # Changelog
 
+## 1.22.24
+
+- **`agents sessions focus` recovers dead panes and shares the sessions browser's selectors (GH-2108).** A retained tmux `remain-on-exit` pane is probed through `#{pane_dead}` immediately before attach, so dead or missing panes no longer open a `Pane is dead` screen. `focus` accepts session ids, topic/path searches, `agent@version` selectors (including per-device `latest`/`oldest`), device, project/time, team/routine, skill/plugin, favorites, and the complete live-state union. Focus, resume, attach, and `run --resume` now use one recovery decision on the origin device: a healthy exact origin performs native resume; otherwise balanced selection chooses a healthy version of the same harness and sends `/continue <id>` to read the indexed transcript, including transcripts retained under version trash. Host-dispatched rows persist the dispatch host as their origin, and `attach` routes its detach-record cleanup there before resuming. No usable same-harness version fails with the device, origin version, and account-health reason. Source: `apps/cli/src/commands/focus.ts`, `apps/cli/src/commands/sessions-browser.ts`, `apps/cli/src/lib/session/recovery.ts`.
+
+- **`agents secrets setup` no longer tells you to set `AGENTS_SECRETS_PASSPHRASE`, and
+  `docs/secrets.md` stops recommending the shell-rc export it flags as a leak
+  (RUSH-1968).** The file-backend note read `set AGENTS_SECRETS_PASSPHRASE for headless
+  encrypted-file reads`, implying a requirement; headless reads have worked with no
+  passphrase since the store began auto-provisioning a 0600 machine-local key, so it now
+  says so and names the real path. The docs were worse than merely stale: they called an
+  rc export *"Recommended for shared/CI machines"* and the 0600 key file *"identical to"*
+  it, which is how a master key ended up in `~/.zshenv` on seven worker boxes. That
+  equivalence is inverted — the key file is read by one process, an rc export is inherited
+  by every child and readable from `/proc/<pid>/environ` — and the section also named a
+  pre-#479 key path (`~/.agents/.cache/secrets/.passphrase`, now
+  `~/.agents/.secrets-key/passphrase`) and a TTY prompt step `getPassphrase` no longer
+  has. A new `docs-hygiene.test.ts` pins those claims against the shipped doc so the
+  advice cannot drift back. Source: `apps/cli/docs/secrets.md`,
+  `apps/cli/src/commands/setup-secrets.ts`, `apps/cli/src/lib/secrets/filestore.ts`.
+
+- **`agents secrets push`/`pull`, `agents sync --secrets`, and `agents secrets
+  export --to-file` / `import --from-file` read `AGENTS_SYNC_PASSPHRASE` now;
+  `AGENTS_SECRETS_PASSPHRASE` is the file store's master key and nothing else
+  (RUSH-1968).** One variable meant two different secrets: the local file store's master
+  key, and the passphrase that seals a bundle for transport. The store stopped needing a
+  passphrase once it auto-provisioned a machine-local key, but headless `push`/`pull`
+  still hard-failed without one — so the only way to get unattended sync on a worker box
+  was to export the **master key** fleet-wide, handing every same-user process the key to
+  the whole store. Splitting them means a box that only needs headless sync sets
+  `AGENTS_SYNC_PASSPHRASE` and never has the master key in its environment. The old name
+  still works for sync as a deprecated fallback — warned exactly once per process, so a
+  `push --all` over many bundles does not flood stderr — so scripted CI and release
+  automation keep working across the upgrade. The headless error now names the new
+  variable (`A sync passphrase is required. Run from a TTY, or set
+  AGENTS_SYNC_PASSPHRASE.`), and `agents sync`'s skip line with it — it previously read
+  `no passphrase available`, naming nothing an operator could act on. Note the legacy
+  fallback only works where that value is also the store's master key, since the old name
+  still keys the store; that coupling is the thing being retired. Resolution moved to
+  one chokepoint so the once-per-process promise holds rather than being per-call-site. Also
+  corrects `SEC-29a`, which claimed the variable applied "exclusively" to the file and
+  age-vault backends: the age-vault backend never reads it (it is gated by `agents
+  login`), and sync plus the portable `--to-file` envelope were two more consumers — the
+  new `SEC-29b` states the split as a normative invariant. Source:
+  `apps/cli/src/lib/secrets/sync-passphrase.ts`, `apps/cli/src/commands/secrets-sync.ts`,
+  `apps/cli/src/commands/sync.ts`, `apps/cli/src/lib/sync-umbrella.ts`.
+
+- Added `--team` as an alias for `agents sessions --teams`. (RUSH-1995)
+- Added absolute `agents secrets unlock --until <date>` expiry, mutually exclusive with relative `--ttl`. (RUSH-1960)
+- Added persisted per-agent-version reasoning effort defaults and surfaced them in `agents view`. (RUSH-2005)
+
+- **`agents feed` no longer crashes when the session index is locked (RUSH-2006).**
+  Outcome enrichment calls `discoverSessions` against `sessions.db`; under concurrent
+  scanner/daemon pressure that open can throw `SQLITE_BUSY` / "database is locked"
+  and take down the whole feed. A lock error now degrades to an empty meta set with a
+  stderr warning so blocks still render. Source: `apps/cli/src/commands/feed.ts`.
+
+- **`agents events --event` / filtered activity reads no longer miss matches under
+  `--limit` (RUSH-2093).** The unified reader capped activity records *before*
+  applying the event-type filter, so a rare match older than the newest-N routine
+  rows (e.g. one `pr.opened` under twenty `file.edited`) was silently dropped. Event
+  types are now passed into `readRecentActivity` so the cap counts matching rows; a
+  non-`activity` `--module` skips the activity half entirely. Source:
+  `apps/cli/src/lib/event-stream.ts`.
+
+- **`agents mcp add` no longer strips comments from `agents.yaml`.** The
+  write path (`writeManifest` / `serializeManifest` in `src/lib/manifest.ts`)
+  used plain `yaml.stringify`, which dropped every hand-written comment on
+  every add. It now round-trips via `yaml.parseDocument` and edits only the
+  keys that changed — the same approach `serializeCentral` already uses for
+  the central meta file (RUSH-2090).
+
+- **Hook cache refresh is now single-flight, backs off on failure, and logs its
+  real exit code (RUSH-2121).** The background refresh in the hook cache shim
+  acquires an atomic `mkdir` lock, so concurrent hook invocations no longer
+  stampede into N parallel refreshes; a persistently-failing refresh records a
+  failure timestamp and is skipped until a 60s backoff elapses instead of
+  re-firing on every invocation; and the refresh now emits a `hook.cache.refresh`
+  event carrying the subshell's real exit code instead of a hardcoded `0`.
+  Source: `apps/cli/src/lib/hooks/cache.ts`.
+
+- **`agents sync --host all` no longer fails every peer with `unknown option
+  '--json'`.** Fleet fan-out injects `--json` on each remote so the roster can
+  parse per-device results, but `sync` never registered the flag. Register
+  `--json` on `agents sync` and emit a machine-readable umbrella/agent/repo
+  payload so peers accept the flag and return parseable stdout (RUSH-2216).
+  Source: `apps/cli/src/commands/sync.ts`.
+
+- **A wedged keychain can no longer pile up `agents` processes (RUSH-2231, RUSH-2232).**
+  A stalled macOS `coreauthd` used to hang the signed keychain helper's XPC receive
+  forever, so every secrets-touching `agents` command blocked and dozens of helper
+  processes plus their `<defunct>` zombies accumulated and made the machine sluggish.
+  Two fixes: **(Layer 1)** every keychain-helper `spawnSync` is now bounded and
+  hard-killed (SIGKILL) on timeout — 8s for never-prompt verbs (`has`/`set`/`delete`/
+  `list*`), 60s for the may-prompt reads (`get`/`get-batch`/`migrate-*`) — surfacing a
+  typed timeout error and arming the read back-off instead of hanging.
+  **(Layer 3)** the daemon reaps the backlog: a 5-minute tick kills orphaned helpers
+  (reparented to PID 1, past a 30s grace) and, two-sweep-debounced, the helper child of
+  an `agents` proc stuck past 90s (child first, escalating to the parent only if it
+  stays wedged) — never touching a process whose start-time can't be captured or whose
+  path doesn't match the helper. Any keychain touch now also opportunistically starts
+  the daemon so the reaper runs even on a secrets-only box. Source:
+  `apps/cli/src/lib/secrets/index.ts`, `apps/cli/src/lib/secrets/reaper.ts`,
+  `apps/cli/src/lib/daemon.ts`.
+
+- **`agents inspect` and `agents doctor` now report harness-scoped hook inventory as capable, on-disk, wired, and unmanaged state.** Their JSON output carries the same state sets from `getResourceInventory`, so a harness with hook files or native wiring no longer collapses to a misleading `Hooks (0)` summary. Inventory is keyed by agent harness and installed version, not by configured model. Source: `apps/cli/src/lib/resource-inventory.ts`, `apps/cli/src/commands/inspect.ts`, `apps/cli/src/lib/doctor-diff.ts`.
+
+- **Fix: the keychain-helper reaper never reaped on macOS.** The daemon reaper shelled `ps -o etimes` — a GNU/Linux procps keyword that macOS `ps` rejects with a non-zero exit — so `execFileSync` threw on every tick and `reapOrphanedKeychainProcesses` returned `reaped: 0` on its only supported platform, leaving orphaned/wedged `Agents CLI` helper processes to pile up. Switched to the portable BSD `etime` keyword (`[[dd-]hh:]mm:ss`) with a parser to seconds. This also un-quarantines the darwin integration test that #2153 had to `it.skip` to unblock releases: that test's symlink fixture was correct all along — it read `reaped: 0` only because the reaper's own `ps etimes` call threw before parsing anything. Verified on macOS 15.4.1: 20/20 reaper tests pass, the integration test reaping a real orphaned sleeper. Source: `apps/cli/src/lib/secrets/reaper.ts`, `reaper.test.ts`.
+
+- **`agents modes [agent[@version]]` lists the permission modes a harness accepts.** The modes analog of `agents models`: for Claude / Codex / Cursor / …, shows which `--mode plan|edit|auto|skip` values work, the native CLI flags, the native default (`*`), any configured `run.defaults` mode, and degrade notes (e.g. plan→edit on Cursor). `agents inspect` also prints the mode list next to capabilities, and `agents run --help` / `agents models` point at the new command. Source: `apps/cli/src/commands/modes.ts`, `apps/cli/src/lib/agent-modes.ts`.
+
+- **`agents insights --all` now works as an alias for `--since all`.** It previously
+  exited with `unknown option '--all'` — a hard failure in the middle of a report the
+  user asked for, on the spelling most people reach for first. An explicit `--since`
+  still wins, so `--all --since 7d` resolves to 7d rather than silently contradicting
+  itself. Source: `apps/cli/src/commands/insights.ts`.
+
+- **Coexisting agents-cli installs no longer fight over the menu-bar helper.** The
+  helper lives at one path in Application Support, but every install on the box runs
+  the startup self-heal, and both the version stamp and the plist's baked
+  `AGENTS_ENTRY` record whichever copy acted last — so each copy read the others'
+  marks as drift and recopied the app bundle over them. Recopying replaces the
+  executable under the running helper and kills it, launchd `KeepAlive` restarts it,
+  and the next copy repeats it: a new pid every 5-15 seconds, 578 launches in one
+  observed helper log, and a status item that never stayed visible while
+  `agents menubar status` still reported `running: yes` (a pid always existed). The
+  plist's `AGENTS_ENTRY` is now treated as the owner and only the owner reinstalls
+  freely; a same-install upgrade keeps its entry path, so `npm update` still installs
+  the new helper normally. Another install still gets there — immediately if the
+  recorded owner is gone from disk, otherwise at most once an hour — so a stale copy
+  that merely still sits on disk can't freeze the menu bar for whichever install the
+  user actually upgrades. Repairs (a missing helper executable, a Developer-ID heal)
+  are never gated, and `agents menubar setup` bypasses the gate as the immediate
+  manual fix. An ad-hoc/dev-signed build never wins the timed takeover — recopying
+  an un-notarized bundle over a good one gets it rejected as "damaged" — though it
+  can still adopt a helper whose owner is gone. Two installs that are both invoked
+  regularly still trade ownership at the cooldown, so the helper restarts about once
+  an hour until one is removed; that is bounded rather than converged, and the real
+  fix remains a single install. `agents menubar status` no longer promises that a
+  stale helper "runs on next `agents` startup", which is not guaranteed on a
+  multi-install box. Fixes #2109. Source:
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **Muse Code global binary is visible to `agents view` / `isVersionInstalled`.**
+  Muse installs a single self-updating launcher at `~/.local/bin/muse` (same
+  shape as droid), but `getBinaryPath` still resolved a version-home
+  `node_modules/.bin/muse` that never exists. After `agents import muse` /
+  `agents add muse`, version dirs now resolve to that global path so managed
+  view, collapse, and live-version bookkeeping match what actually executes;
+  install no longer writes a self-referential shim symlink. Source:
+  `apps/cli/src/lib/versions.ts`.
+
+- **Muse multi-version isolation matches Claude/Codex (XDG pin, not bare symlink).**
+  Claude/Codex isolate per version with `CLAUDE_CONFIG_DIR` / `CODEX_HOME`.
+  Muse has no dedicated config env; it reads `$XDG_CONFIG_HOME/muse` and
+  `$XDG_DATA_HOME/muse`. After `agents import muse`, `~/.config/muse` is a
+  symlink into the version home — Muse refuses that path with
+  `Agent Definition filesystem source failed: SymlinkOrReparse` and exits 1
+  (the Zion `agents run muse@0.1.0` failure). Managed launches now pin
+  `XDG_CONFIG_HOME` + `XDG_DATA_HOME` into the version home from `buildExecEnv`,
+  the main shim, and versioned aliases (`muse@0.1.0`), the same way Claude pins
+  `CLAUDE_CONFIG_DIR`. Muse is also listed in `CONFIG_ENV_ISOLATED_AGENTS` so
+  `--isolated` installs are honest. Source: `apps/cli/src/lib/{exec,shims}.ts`.
+
+- **Scheduled routines now run on a per-account `claude setup-token` when one is
+  provisioned, instead of throwing it away.** `buildRoutineSpawnEnv` unconditionally
+  deleted `CLAUDE_CODE_OAUTH_TOKEN`, so even after `buildExecEnv` injected a long-lived,
+  non-rotating setup-token from the reserved file-backed `auth` bundle
+  (`resolveClaudeSetupToken`), a routine still fell back to the version home's rotating
+  `.credentials.json` login. With one Claude account signed into several version homes
+  (or several fleet boxes), that rotating login is the single-use-refresh-token
+  revocation storm — one home's refresh silently revokes every sibling copy, so an
+  unattended routine keeps landing on a just-revoked token and dies with `auth_failed:
+  OAuth access token has been revoked` / `Please run /login`, even though `agents view`
+  shows the account healthy. The delete now distinguishes the two flavours: a
+  per-account setup-token (keyed to this home's own account) is re-asserted and KEPT; an
+  inherited *ambient* token (a shared value the daemon env happened to carry — the
+  RUSH-1822 fleet-logout path) is still stripped so a routine never runs on it.
+  Provision the token with `/fleet:mint-auth`. Source:
+  `apps/cli/src/lib/runner.ts` (`buildRoutineSpawnEnv`).
+
+- **Resolved secrets no longer appear in `ps` for tmux-launched agents
+  (RUSH-2100).** An interactive `agents run` wraps the agent in tmux via
+  `exec env K=V … <agent>`, which put the entire exec env — every resolved
+  secrets-bundle value — into the pane's command line, readable by any process of
+  the same user. On one fleet box six live processes carried
+  `AGENTS_SECRETS_PASSPHRASE`, the key that decrypts every file-backed bundle on
+  that machine. The pane now sources a `0600` env file and unlinks it before
+  `exec`, so only the file path is argv-visible; a missing file aborts the pane
+  rather than launching half-configured. Every key routes through the file, not a
+  curated "secret-bearing" subset, so a newly added credential is covered without
+  anyone maintaining a list. Source: `apps/cli/src/lib/exec.ts`,
+  `apps/cli/docs/specifications.md` (SEC-8a).
+
 ## 1.22.23
 
 - **Daemon-warmed cross-surface session-status cache (RUSH-2062).** Menubar,

package/README.md

@@ -303,6 +303,7 @@ agents sessions --idle              # stopped between turns (fleet-wide)
 agents sessions --orphan            # agent outlived its terminal client
 agents sessions --crashed           # terminal and agent disappeared uncleanly
 agents sessions focus a1b2c3d4      # jump back into one — attach in place, or resume
+agents sessions focus claude@latest --device yosemite-s0  # pick latest there
 ```
 
 On a terminal, `agents sessions --active` (and a bare `agents sessions`) open the **interactive session browser** — one filter you drive with single keys, re-pulled live across the fleet:
@@ -313,7 +314,7 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 | `r` | running only | `--active` |
 | `f` | favorites only | `--favorites` |
 | `*` | star / unstar the highlighted session | `agents sessions favorite <id>` |
-| `c` | team sessions | `--teams` |
+| `c` | team sessions | `--team` (alias: `--teams`) |
 | `a` | agent (cycles) | `-a` |
 | `d` | device (cycles) | `--device` |
 | `p` | this repo ↔ all dirs | `--all` |
@@ -332,7 +333,7 @@ Filters **stack** (they AND together), the active set shows in the header, and t
 | --- | --- |
 | ![sessions browser, preview hidden](assets/demos/sessions-preview-before.png) | ![sessions browser, preview open with a links line](assets/demos/sessions-preview-after.png) |
 
-Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), `idle`, or a lifecycle state such as `orphaned`, `crashed`, `closed`, `abandoned`, `queued`, or `unknown`. Pass the matching flag (`--working`, `--idle`, `--waiting`, `--orphan`, `--crashed`, `--closed`, `--abandoned`, `--queued`, `--unknown`) directly; each implies `--active`, and several flags form a union. The fleet fan-out is already the default; `--local` opts out. `--all` instead widens historical directory and time scope. Rows also carry badges for the PR, worktree, and ticket. `agents sessions focus [id]` attaches the live pane in place -- the tmux split locally or over SSH, or its Ghostty tab -- and falls back to a fresh tab + resume when the terminal is gone.
+Each live session resolves to `working`, `waiting_input` (with why -- a question, a plan review, or a permission prompt), `idle`, or a lifecycle state such as `orphaned`, `crashed`, `closed`, `abandoned`, `queued`, or `unknown`. Pass the matching flag (`--working`, `--idle`, `--waiting`, `--orphan`, `--crashed`, `--closed`, `--abandoned`, `--queued`, `--unknown`) directly; each implies `--active`, and several flags form a union. The fleet fan-out is already the default; `--local` opts out. `--all` instead widens historical directory and time scope. Rows also carry badges for the PR, worktree, and ticket. `agents sessions focus [selector]` accepts the same agent/version, device, time, team, project, skill/plugin, favorite, and live-state filters as the session browser. A unique id focuses directly; an agent/version or text selector always opens the preview picker. Immediately before attach it checks the tmux pane process: a living pane is joined in place, while a dead/missing pane enters recovery instead of showing tmux's `Pane is dead` screen.
 
 Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an inferred title, files changed grouped by directory (created / modified / deleted), a histogram of which tools did the work (including parsed Bash commands -- `git`, `npm`, `ffmpeg`, `ssh`, and so on), and the last test verdict -- the signals to reload a task in seconds.
 
@@ -351,11 +352,11 @@ agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # original harness/version/d
 agents run auto --resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # adapt if its account is unavailable
 ```
 
-`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and restore the source harness, version, device, cwd, and recorded launch mode. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
+`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and recover on the source device. If the origin version is installed, signed in, and healthy, its isolated home performs native resume. Otherwise a healthy version of the **same harness** starts with `/continue <id>`, which reads the indexed transcript even when the old version home is retained under version trash. It never native-resumes from a different isolated home. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
 
 ### Send an agent to the background — and bring it back
 
-Running 30 agents and drowning in terminal tabs? `agents sessions detach <id>` stops a session's interactive process and keeps it working **headless** in the background -- it drives its task to done unattended, no tab, lower cost. `agents sessions attach <id>` brings it back: version-pinned resume into a live TUI, the same session and full history (including whatever it did while backgrounded).
+Running 30 agents and drowning in terminal tabs? `agents sessions detach <id>` stops a session's interactive process and keeps it working **headless** in the background -- it drives its task to done unattended, no tab, lower cost. `agents sessions attach <id>` brings it back through the same origin-device recovery decision: native resume in the exact healthy origin home, or same-harness `/continue` when that home is unavailable, with the full indexed history (including whatever it did while backgrounded).
 
 ```
 agents sessions detach a1b2c3d4     # go headless in the background, keep working

package/dist/commands/attach.d.ts

@@ -6,5 +6,7 @@
  * history, the exact inverse of `agents sessions detach`.
  */
 import type { Command } from 'commander';
+import type { SessionMeta } from '../lib/session/types.js';
 export declare function registerAttachCommand(program: Command): void;
 export declare function attachAction(id: string): Promise<void>;
+export declare function attachRecoveryArgs(session: Pick<SessionMeta, 'id'>): string[];

package/dist/commands/attach.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
-import { discoverSessions } from '../lib/session/discover.js';
-import { resumeSessionInPlace } from './sessions.js';
+import { runOnPeer } from '../lib/session/remote-list.js';
+import { sessionRecoveryPeer } from '../lib/session/recovery.js';
+import { resolveSessionMetadataValue, resumeSessionInPlace } from './sessions.js';
 import { readDetachRecord, clearDetachRecord, isHeadlessAlive } from '../lib/session/detached.js';
 export function registerAttachCommand(program) {
     program
@@ -12,16 +13,37 @@ export function registerAttachCommand(program) {
     });
 }
 export async function attachAction(id) {
-    const q = id.toLowerCase();
-    // Rich meta carries the pinned version + origin cwd the resume needs.
-    const metas = await discoverSessions({ all: true, since: '90d', limit: 2000 });
-    const meta = metas.find((m) => m.id === id) ?? metas.find((m) => m.id.toLowerCase().startsWith(q));
-    if (!meta) {
+    const outcome = await resolveSessionMetadataValue(id);
+    if (outcome.kind === 'partial') {
+        console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
+        process.exitCode = 2;
+        return;
+    }
+    if (outcome.kind === 'not-found') {
         console.error(chalk.red(`No session matching "${id}".`));
         console.error(chalk.gray('  See your sessions: agents sessions'));
         process.exitCode = 1;
         return;
     }
+    if (outcome.kind === 'ambiguous') {
+        console.error(chalk.red(`"${id}" matches ${outcome.candidates.length} sessions. Pass the full session id.`));
+        process.exitCode = 1;
+        return;
+    }
+    const meta = outcome.session;
+    // Route the WHOLE attach operation to the origin, not just its eventual
+    // resume. The detach record and headless PID are device-local; clearing them
+    // here would leave the real background continuation running beside a second
+    // process on the owning machine.
+    const peer = sessionRecoveryPeer(meta);
+    if (peer) {
+        const routed = await runOnPeer(attachRecoveryArgs(meta), peer, { tty: true });
+        if (routed === 'no-target') {
+            console.error(chalk.red(`Cannot attach ${meta.shortId}: origin device ${peer} is not a registered reachable peer.`));
+            process.exitCode = 1;
+        }
+        return;
+    }
     // If it's backgrounded, stop the headless continuation first so two processes
     // don't resume the same transcript at once.
     const rec = readDetachRecord(meta.id);
@@ -39,3 +61,6 @@ export async function attachAction(id) {
     console.log(chalk.gray(`Attaching ${meta.agent} ${meta.id.slice(0, 8)} — resuming interactively…`));
     await resumeSessionInPlace(meta);
 }
+export function attachRecoveryArgs(session) {
+    return ['sessions', 'attach', session.id];
+}

package/dist/commands/defaults.js

@@ -47,11 +47,13 @@ export function registerDefaultsCommands(program) {
         .description('Set defaults for an agent/version selector')
         .option('--mode <mode>', "Default mode: plan, edit, auto, skip. 'full' accepted as alias for skip.")
         .option('--model <model>', 'Default model or model alias, forwarded via --model')
+        .option('--effort <effort>', 'Default reasoning effort: low, medium, high, xhigh, max, or auto')
         .action((selector, options) => {
         try {
             const entry = setRunDefault(selector, {
                 ...(options.mode !== undefined ? { mode: options.mode } : {}),
                 ...(options.model !== undefined ? { model: options.model } : {}),
+                ...(options.effort !== undefined ? { effort: options.effort } : {}),
             });
             console.log(chalk.green('Set run default:'));
             console.log(`  ${formatRunDefaultEntry(entry)}`);

package/dist/commands/doctor.js

@@ -848,6 +848,11 @@ function renderTargetText(report, options) {
         // sees what was checked. options.requestedKinds drives this.
         if (options.requestedKinds && !options.requestedKinds.has(kind))
             continue;
+        if (kind === 'hooks' && report.hookInventory) {
+            const wired = report.hookInventory.wiringSupported ? String(report.hookInventory.wired.length) : 'unknown';
+            const unmanaged = report.hookInventory.unmanaged.length > 0 ? ` · unmanaged ${report.hookInventory.unmanaged.length}` : '';
+            console.log(chalk.gray(`  inventory: capable ${report.hookInventory.capable ? 'yes' : 'no'} · on-disk ${report.hookInventory.onDisk.length} · wired ${wired}${unmanaged}`));
+        }
         renderKindSection(kind, rows, report.layers, options);
         // A hook file can reconcile "ok" above yet be absent from settings.json — a
         // present-but-dead hook. Surface that right under the hooks section.

package/dist/commands/exec.js

@@ -532,7 +532,7 @@ export function registerRunCommand(program) {
         .option('--headless', 'Force headless mode. Auto-enabled when a prompt is provided; pass explicitly to stay headless with no prompt (reads the prompt from stdin).', false)
         .option('--no-auth-check', 'Skip the pre-launch "looks logged out" warning on an interactive run (advisory; never blocks anyway). Also silenced by AGENTS_NO_AUTH_CHECK=1.')
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
-        .option('--resume [id]', 'Resume a previous conversation. Full IDs resolve locally first, then fleet-wide. Claude, Codex, Grok, Kimi, Droid, and Cursor use version-gated native resume; other agents replay via /continue. Pair with a prompt to continue headlessly.')
+        .option('--resume [id]', 'Recover a previous conversation on its origin device. The exact healthy origin uses native resume; otherwise a healthy version of the same harness replays via /continue. 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>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --host runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
         .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
@@ -647,12 +647,14 @@ export function registerRunCommand(program) {
       agents run claude "fix the bug" -- --custom-flag
     `,
         notes: `
-      Modes (not every agent supports every mode — check agents.yaml capabilities):
+      Modes (not every agent supports every mode — run \`agents modes <agent>\`):
         plan  read-only investigation; no writes, no shell side-effects
         edit  may edit files; prompts for shell / risky operations
         auto  smart classifier auto-approves safe ops, prompts for risky (claude, copilot)
         skip  bypass every permission prompt (dangerously-skip-permissions)
         Legacy 'full' is silently rewritten to 'skip'.
+        List per-harness support + native flags: agents modes · agents modes claude
+        Models (cheap|default|best|ultra): agents models <agent[@version]>
 
       Headless plan support (a prompt makes the run headless):
         plan works headless on claude, codex, droid, opencode.
@@ -689,7 +691,7 @@ export function registerRunCommand(program) {
         given. --cloud is mutually exclusive with --host/--lease and with
         local-run flags (--loop, --resume, --secrets, --terminal, …).
 
-      Resume: --resume <id> resolves full IDs locally first, then fleet-wide, and restores the source version/device/mode. Claude, Codex, Grok, Kimi, Droid, and Cursor use version-gated native resume; others replay via /continue. agents resume <id> infers the harness too.
+      Resume: --resume <id> resolves full IDs locally first, then fleet-wide, and recovers on the source device with its cwd/mode. The exact healthy origin version uses native resume; otherwise a healthy version of the same harness replays via /continue. agents resume <id> infers the harness too.
 
       Passthrough: everything after -- is forwarded verbatim to the underlying agent CLI.
         agents run kimi -- --plan --some-native-flag value
@@ -835,6 +837,7 @@ export function registerRunCommand(program) {
         }
         let autoHarnessRequested = normalizedAgentSpec === RUN_AUTO_KEYWORD;
         let resolvedResumeSource;
+        let resolvedRecoveryTarget;
         // Concrete resume ids resolve BEFORE placement. Full UUIDs take the local
         // SQLite fast path; only a local miss fans out to the fleet. This lets a
         // command entered on zion discover that the owning version-home is on a
@@ -890,32 +893,40 @@ export function registerRunCommand(program) {
                     process.stderr.write(chalk.yellow(`[agents] session ${resolvedResumeSource.shortId} predates stored launch modes; using --mode ${options.mode}\n`));
             }
             const { machineId } = await import('../lib/machine-id.js');
+            const { sessionRecoveryDestinationMatches, sessionRecoveryPeer, } = await import('../lib/session/recovery.js');
             const sourceMachine = resolvedResumeSource.machine;
+            const sourcePeer = sessionRecoveryPeer(resolvedResumeSource);
             const explicitPlacement = hostTargetGiven(options).length > 0;
-            if (sourceMachine && sourceMachine !== machineId() && !explicitPlacement) {
-                options.host = sourceMachine;
+            if (sourcePeer && !explicitPlacement) {
+                options.host = sourcePeer;
             }
-            else if (!autoHarnessRequested && sourceMachine && sourceMachine !== machineId() && explicitPlacement && !hostTargetGiven(options).includes(sourceMachine)) {
-                console.error(chalk.red(`Strict resume must run on ${sourceMachine}, where session ${resolvedResumeSource.shortId} is owned. ` +
-                    `Use agents run auto --resume ${resolvedResumeSource.id} to hand off elsewhere.`));
+            else if (sourcePeer && explicitPlacement && !hostTargetGiven(options).some((host) => sessionRecoveryDestinationMatches(resolvedResumeSource, host))) {
+                console.error(chalk.red(`Session ${resolvedResumeSource.shortId} must recover on ${sourcePeer}, where its indexed transcript and version history are owned; ` +
+                    `the requested device was ${hostTargetGiven(options).join(', ')}.`));
                 process.exit(1);
             }
-            // On the owning machine, `auto` first asks the existing account router
-            // whether the exact source version is healthy. If it is, native resume
-            // wins. If not, keep `auto` so the normal harness/account router selects
-            // a healthy local target and the later resume block performs /continue.
-            if (autoHarnessRequested && (!sourceMachine || sourceMachine === machineId())) {
-                const sourceAgent = resolvedResumeSource.agent;
-                if (sourceAgent in AGENTS && resolvedResumeSource.version) {
-                    const { resolveRunVersion } = await import('../lib/rotate.js');
-                    const health = await resolveRunVersion(sourceAgent, 'available', resolvedResumeSource.cwd ?? process.cwd());
-                    if (!health.exhausted && health.version === resolvedResumeSource.version) {
-                        normalizedAgentSpec = `${sourceAgent}@${resolvedResumeSource.version}`;
-                        autoHarnessRequested = false;
-                        if (!options.quiet)
-                            process.stderr.write(chalk.gray(`[agents] auto resume → native ${normalizedAgentSpec} on ${sourceMachine ?? machineId()}\n`));
-                    }
+            // Recovery is resolved on the device that owns the transcript. A remote
+            // dispatch is pinned to the source HARNESS (not `run auto`'s cross-harness
+            // picker); the peer repeats this block with the injected SessionMeta and
+            // chooses its own healthy version. Locally, resolve it now.
+            const sourceAgent = resolvedResumeSource.agent;
+            if (!sourcePeer) {
+                try {
+                    const { resolveSessionRecovery } = await import('../lib/session/recovery.js');
+                    resolvedRecoveryTarget = await resolveSessionRecovery(resolvedResumeSource);
+                }
+                catch (err) {
+                    console.error(chalk.red(err.message));
+                    process.exit(1);
                 }
+                normalizedAgentSpec = `${resolvedRecoveryTarget.agent}@${resolvedRecoveryTarget.version}`;
+                autoHarnessRequested = false;
+                if (!options.quiet)
+                    process.stderr.write(chalk.gray(`[agents] session recovery → ${resolvedRecoveryTarget.mode} ${normalizedAgentSpec} on ${sourceMachine ?? machineId()} · ${resolvedRecoveryTarget.reason}\n`));
+            }
+            else if (autoHarnessRequested) {
+                normalizedAgentSpec = sourceAgent;
+                autoHarnessRequested = false;
             }
         }
         if (autoHarnessRequested) {
@@ -2217,10 +2228,44 @@ export function registerRunCommand(program) {
                 session = picked.session;
                 forceInteractive = true; // bare resume always lands in the agent's TUI
             }
-            // Native resume is valid only for the source harness + exact isolated
-            // version. `auto` may have selected another healthy harness/account; in
-            // that case keep the target version and hand off through /continue.
-            const canResumeNatively = session.agent === agent && nativeResume(agent, session.version);
+            // Bare `run <harness> --resume` learns the chosen SessionMeta only after
+            // the host-placement phase above. If the picker chose a synced session
+            // from another device, route the recovery command now; resolving local
+            // candidates would otherwise native-resume through this device's
+            // unrelated isolated home.
+            if (!resolvedResumeSource) {
+                const { sessionRecoveryPeer, sessionRecoveryRunArgs, } = await import('../lib/session/recovery.js');
+                const peer = sessionRecoveryPeer(session);
+                if (peer) {
+                    const { runOnPeer } = await import('../lib/session/remote-list.js');
+                    const routed = await runOnPeer(sessionRecoveryRunArgs(session), peer, { tty: true });
+                    if (routed === 'no-target') {
+                        console.error(chalk.red(`Cannot recover session ${session.shortId}: origin device ${peer} is not a registered reachable peer.`));
+                        process.exitCode = 1;
+                    }
+                    return;
+                }
+            }
+            // Bare interactive --resume selects the SessionMeta only down here, so
+            // it has not gone through the early concrete-id resolver. Resolve it now;
+            // concrete ids reuse the exact same target chosen above.
+            if (!resolvedRecoveryTarget) {
+                try {
+                    const { resolveSessionRecovery } = await import('../lib/session/recovery.js');
+                    resolvedRecoveryTarget = await resolveSessionRecovery(session);
+                }
+                catch (err) {
+                    console.error(chalk.red(err.message));
+                    process.exit(1);
+                }
+            }
+            if (resolvedRecoveryTarget.agent !== agent) {
+                console.error(chalk.red(`Session ${session.shortId} belongs to ${resolvedRecoveryTarget.agent}, not ${agent}. ` +
+                    `Use: agents run auto --resume ${session.id}`));
+                process.exit(1);
+            }
+            version = resolvedRecoveryTarget.version;
+            const canResumeNatively = resolvedRecoveryTarget.mode === 'native';
             if (canResumeNatively) {
                 version = session.version;
                 resumeNative = true;
@@ -2330,6 +2375,12 @@ export function registerRunCommand(program) {
                     console.error(chalk.red(`agents: ${agent}@${launchTarget} is not runnable and could not be repaired. Try: ${hint}`));
                     process.exit(1);
                 }
+                if (resolvedRecoveryTarget && healed !== launchTarget) {
+                    console.error(chalk.red(`agents: session recovery target ${agent}@${launchTarget} became unavailable on ` +
+                        `${resolvedResumeSource?.machine ?? 'this device'}; refusing to resume through another version home. ` +
+                        `Retry the command so recovery can select a healthy ${agent} version.`));
+                    process.exit(1);
+                }
                 // Always adopt the healed version explicitly. In the version-undefined
                 // path a fallback re-pins the GLOBAL default, but `resolveVersion`
                 // prefers a PROJECT pin — so leaving `version` undefined would let the
@@ -2447,7 +2498,8 @@ export function registerRunCommand(program) {
             console.error(chalk.gray(`Pass --mode plan explicitly if you really want a read-only run.`));
             process.exit(1);
         }
-        const effort = options.effort;
+        const effortSource = runCmd.getOptionValueSource('effort');
+        const effort = (effortSource === 'default' && runDefaults.effort ? runDefaults.effort : options.effort);
         if (!['low', 'medium', 'high', 'xhigh', 'max', 'auto'].includes(effort)) {
             console.error(chalk.red(`Invalid effort: ${effort}. Use 'low', 'medium', 'high', 'xhigh', 'max', or 'auto'`));
             process.exit(1);

package/dist/commands/feed.d.ts

@@ -60,6 +60,24 @@ export declare function sessionHintsFromActive(sessions: Array<{
         slug?: string;
     };
 }>): SessionOutcomeHint[];
+/**
+ * True when a SQLite open/query failed because another writer holds the lock.
+ * better-sqlite3 surfaces this as message "database is locked" and/or code
+ * SQLITE_BUSY (RUSH-2006).
+ */
+export declare function isSqliteBusyError(err: unknown): boolean;
+/**
+ * Load session metas for feed outcome enrichment. The sessions index can be
+ * locked by a concurrent scanner/daemon — enrichment is best-effort, so a lock
+ * degrades to an empty list instead of crashing `agents feed` (RUSH-2006).
+ *
+ * `load` is injected so tests can throw a real lock-shaped error without
+ * mocking the session module.
+ */
+export declare function loadSessionMetasForFeedEnrichment<T>(load: () => Promise<T[]>): Promise<{
+    metas: T[];
+    skippedLock: boolean;
+}>;
 export declare function registerFeedCommand(program: Command): void;
 /** Feed view selector (RUSH-2015): decisions, progress, or both. */
 export type FeedFilter = 'needs' | 'updates' | 'all';

package/dist/commands/feed.js

@@ -253,6 +253,39 @@ export function sessionHintsFromActive(sessions) {
         project: s.cwd ? projectKeyFromCwd(s.cwd) : undefined,
     }));
 }
+/**
+ * True when a SQLite open/query failed because another writer holds the lock.
+ * better-sqlite3 surfaces this as message "database is locked" and/or code
+ * SQLITE_BUSY (RUSH-2006).
+ */
+export function isSqliteBusyError(err) {
+    if (err == null)
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    const code = typeof err === 'object' && err !== null && 'code' in err
+        ? String(err.code ?? '')
+        : '';
+    return /SQLITE_BUSY|database is locked/i.test(msg) || /SQLITE_BUSY/i.test(code);
+}
+/**
+ * Load session metas for feed outcome enrichment. The sessions index can be
+ * locked by a concurrent scanner/daemon — enrichment is best-effort, so a lock
+ * degrades to an empty list instead of crashing `agents feed` (RUSH-2006).
+ *
+ * `load` is injected so tests can throw a real lock-shaped error without
+ * mocking the session module.
+ */
+export async function loadSessionMetasForFeedEnrichment(load) {
+    try {
+        return { metas: await load(), skippedLock: false };
+    }
+    catch (err) {
+        if (isSqliteBusyError(err)) {
+            return { metas: [], skippedLock: true };
+        }
+        throw err;
+    }
+}
 export function registerFeedCommand(program) {
     const feed = program
         .command('feed')
@@ -446,7 +479,17 @@ export function registerFeedCommand(program) {
         if (includeLocal) {
             sessions = await getActiveSessions();
         }
-        const sessionMetas = includeLocal && sessions.length > 0 ? await discoverSessions({ all: true, limit: 5000 }) : [];
+        // discoverSessions touches sessions.db; under concurrent scan pressure it
+        // can throw SQLITE_BUSY. Outcome enrichment is best-effort — degrade with
+        // a warning rather than crash the whole feed (RUSH-2006).
+        let sessionMetas = [];
+        if (includeLocal && sessions.length > 0) {
+            const loaded = await loadSessionMetasForFeedEnrichment(() => discoverSessions({ all: true, limit: 5000 }));
+            if (loaded.skippedLock) {
+                console.error(chalk.yellow('Feed: session index is locked; skipping local outcome enrichment'));
+            }
+            sessionMetas = loaded.metas;
+        }
         const localSignals = buildSessionSignals(sessions, sessionMetas);
         if (opts.pause || opts.kill) {
             if (!includeLocal) {