@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/CHANGELOG.md

@@ -1,5 +1,407 @@
 # 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,
+  Factory, watchdog, and CLI used to each re-run a full `sessions --active`
+  gather (~9s / ~170MB) with no sharing. The daemon now warms a local active-
+  session snapshot every 15s; those surfaces read the warm file when fresh.
+  `session/remote.ts` is cache-first too — a reachable host skips SSH while its
+  cache is within the freshness window (it used to replay only on
+  unreachable). Immutable per-session fields (topic, label, cwd, …) are memoized
+  by transcript mtime; live status never rides that memo. Source:
+  `apps/cli/src/lib/session/session-cache.ts`, `apps/cli/src/lib/session/remote.ts`,
+  `apps/cli/src/lib/daemon.ts`.
+
+- **`agents sessions <id>` / `agents resume <id>` resolve across the fleet fast, with
+  early-exit and SSH cancellation (RUSH-2203).** The cross-machine resolve fanned out
+  with `await Promise.all` and no cancellation, so one slow or unreachable peer stalled
+  the whole lookup to the 12s per-peer timeout even after a fast peer already returned
+  the exact match — a full-UUID resolve on a fleet with an offline box took ~16-40s. A
+  **full-UUID** resolve (globally unique) now opts into a cancellable, early-exit
+  fan-out: the first peer holding it resolves the sweep and SIGTERMs every
+  still-outstanding peer, and a local UUID hit resolves with **zero** SSH.
+  `agents resume <label>` auto-resumes the one exact-label match; labels are not globally
+  unique, so they stay all-settle (a same-label session may live on another peer) — a
+  unique label resumes, a cross-machine collision surfaces as an ambiguity. The not-found
+  message reports the actual sweep result (devices searched, which were unreachable)
+  instead of the misleading "search with `--device <host>`" — fleet search is already the
+  default. `--device all` / `--devices` are accepted and mean "the whole fleet". The
+  all-settle default is unchanged for the shared fan-out's other callers (tool-search,
+  program-count) and for labels / ambiguous short-id prefixes, which still wait for every
+  peer. Source:
+  `apps/cli/src/lib/remote-agents-json.ts`, `apps/cli/src/lib/session/remote-list.ts`,
+  `apps/cli/src/commands/sessions.ts`, `apps/cli/src/commands/resume.ts`.
+
+- **`agents sessions focus` gains device + live-state scoping and multi-select tabs
+  (RUSH-2206).** `focus` now honors `--device/--host <name>` (scope the picker to a
+  device's live sessions) and the same live-state filters `sessions --active` defines
+  (`--orphan`/`--crashed`/`--waiting`/`--idle`/`--working`/`--closed`/`--abandoned`/
+  `--queued`/`--unknown`) — they compose, so `agents sessions focus --orphan --device
+  yosemite-s0` lists only that host's orphans. The interactive picker is now
+  multi-select: check several sessions and each opens as a new tab in the terminal
+  you're in (Ghostty / iTerm / tmux, auto-detected), reusing `resume`'s batch open and
+  flood guard. Per tab, live semantics hold — a tmux session is joined (a second
+  client, no fork), local or remote over SSH; a session with no attach rail resumes a
+  copy in the tab, reported never silently dropped. `focus <id>` direct-jump and
+  `--attach-only` (old `go`) behavior are unchanged. Source:
+  `apps/cli/src/commands/focus.ts`, `apps/cli/src/commands/go.ts`.
+
+- **`agents harness edit` is now wizard-capable, on a shared step engine (RUSH-2219).**
+  Run `agents harness edit <name>` with no flags in a terminal and it walks each field
+  (model, endpoint, auth, version, fallback, description) pre-filled with the harness's
+  current values — where before it was flag-only and errored without one. Both `add`/`fork`
+  and `edit` now drive one shared step engine: every step is skippable by the matching flag,
+  so scripting stays non-interactive and a flagless non-interactive `edit` still errors as
+  before. Endpoint and version prompts are gated by the host's API format (a host with no
+  custom-endpoint slot, or one that self-updates, shows the field disabled with a reason
+  instead of silently accepting a value the run would drop). This is the foundation the
+  model catalog, connection test, edit matrix, and cross-host portability build on.
+  Source: `apps/cli/src/commands/harness-wizard.ts`, `apps/cli/src/commands/harness.ts`.
+
+- **Codex launches now default to safe writable access instead of an offline
+  read-only sandbox.** When no configured run default exists, omitting `--mode`
+  selects a managed workspace profile with network access, on-request approvals,
+  `~/.agents`, and regenerable build caches. Explicit `--mode plan` remains
+  filesystem-read-only but now retains network access. The same policy covers
+  `agents run`, fallback attempts, resumes, routines, direct `codex` shims,
+  versioned aliases, and Windows shim passthrough; only explicit `skip` disables
+  the sandbox and approvals. Source: `apps/cli/src/lib/codex-policy.ts`.
+
+- **Phone forwards are shaped to a text, not a wall.** `agents feed post`
+  (`--level important` / `--blocked`), `agents notify`, and `agents send --to owner`
+  all forward to the owner's phone through one seam, `composeBroadcastMessage`; it now
+  keeps the post **title** (the scannable headline) and truncates a long **body** to a
+  short excerpt marked `… (full in feed)` (caps: 500 chars / 8 lines). The full post is
+  untouched in the feed — only the outbound phone copy is shortened — so a requested
+  long write is not lost, and enforcing it at this seam covers every sink (owner alias,
+  in-process `channel:`, spawned `command:` via `{message}`), which a per-command shell
+  hook cannot. Source: `apps/cli/src/lib/feed-broadcast.ts` (`truncateBroadcastBody`).
+
+- **`agents run --lease` self-cleans its warm pool.** Each lease now auto-stops **expired, idle** boxes in the run's profile pool (an expired box can never be reused, so it was pure cost the 1h-idle `agents lease gc` window left running). Conservative: only a box that is running, in the same profile+netMode pool, past its lease expiry, and untouched for a grace window is stopped — a mid-boot or in-use box is never touched. Skipped when an explicit `--box <slug>` is named. Source: `apps/cli/src/lib/crabbox/lease.ts`.
+
+- **Muse Code (Meta) harness support.** `muse` is a first-class agent: install via
+  `curl -fsSL https://dev.meta.ai/install.sh | sh`, run with `agents run muse`,
+  and use in teams. Modes map to Muse safety flags (`--disable-write` /
+  `--disable-approval` / `--yolo`); `--model` and `--reasoning-effort` are
+  forwarded; headless is `muse exec` with `--json`; interactive resume is
+  `muse resume <id>` (id immediately after the verb), headless resume is
+  `--session-id`. Sessions under `~/.local/share/muse/sessions/` (plus version
+  homes) are discovered and parsed; usage shows Meta Model API rate limits when
+  a key is present, otherwise local 7-day token totals. MCP writes to
+  `~/.config/muse/settings.json` (`mcp_servers`, `schema_version: 1`). Model
+  catalog: `muse-spark-1.2` (default), `1.1`, `1.2-contributor` with offline
+  pricing. Aliases: `muse-code`, `meta-muse`. Hooks write Claude-shaped
+  matcher groups into `~/.config/muse/settings.json` (`schema_version: 1`);
+  plugins use the Claude marketplace layout under the XDG data plugin store
+  (`~/.local/share/muse/plugins`) with `.muse-plugin` manifests. Allowlist
+  stays false (Muse uses approval-mode + sandbox, not tool-name allow/deny).
+  Source: `apps/cli/src/lib/{agents,exec,models,usage,mcp,hooks,plugins,
+  plugin-marketplace,runner,shims}.ts`, `apps/cli/src/lib/session/*`.
+
+- **Release CI no longer re-runs the six-job cross-platform matrix on `v*` tags.**
+  The expensive `ci.yml` matrix (ubuntu + macOS + Windows × Node 22/24) still
+  runs on `release/**` branch pushes and manual `workflow_dispatch`, but not when
+  a version tag is pushed. `release.sh` tags the exact commit that already passed
+  the release-branch matrix, so the post-tag matrix was pure cost. Source:
+  `.github/workflows/ci.yml`.
+
+- **`claude-opus-5` and `claude-sonnet-5` were unpriced, so every session using them
+  cost $0.** The pricing table carried `claude-opus-4`, `claude-sonnet-4`,
+  `claude-fable-5` and `claude-mythos-5` but not the Opus/Sonnet 5 line. Matching is
+  dash-bounded (`getModelPricing`), so `claude-opus-5` cannot fall back to the
+  `claude-opus-4` entry — it resolved to null, and an unpriced model contributes
+  nothing rather than erroring. On one real index that silently zeroed **526 sessions**,
+  478 of them the current default model, understating `agents cost`, `agents output`
+  and `agents insights` alike. Rates from the published table: Opus 5 $5/$25 per MTok
+  (cache write $6.25, cache read $0.50); Sonnet 5 $2/$10 (cache write $2.50, cache read
+  $0.20). Source: `apps/cli/src/lib/pricing/prices.json`.
+
+- **Schema v34 reprices the sessions that were zeroed.** Adding prices alone fixes
+  nothing already indexed: `cost_usd` is computed at scan time and the scanner skips any
+  transcript whose `(file_mtime_ms, file_size)` is unchanged, so those rows would keep
+  their NULL forever. They cannot be repaired in place either — the row stores
+  `token_count` and `output_tokens` but not the uncached-input / cache-read / cache-write
+  split the price table needs. So v34 flushes `scan_ledger`, the same remedy v5 → v6 used
+  for this exact column when cost was introduced. One slower scan, then correct numbers.
+  Source: `apps/cli/src/lib/session/db.ts`.
+
+  **Sonnet 5's $2/$10 is introductory pricing that ends 2026-08-31.** From 2026-09-01 the
+  standard rate is $3/$15. The table holds one current rate per model with no notion of an
+  effective date, so that entry must be updated then or Sonnet 5 spend reads ~33% low.
+  Called out at the top of `table.ts`.
+
+- **`agents sessions --orphan`/`--active`: cross-harness live discovery + richer rows (RUSH-2205).**
+  Two fixes. (1) The headless `ps`-scan recognized only 6 agent executables, so a
+  bare-headless `grok`/`kimi`/`antigravity`/`openclaw`/`hermes`/`rush` run was
+  silently dropped from the live views; the comm→kind map is now derived from
+  `SESSION_AGENTS` × the AGENTS registry (`cliCommand`), so every discoverable
+  harness surfaces. (2) Each live row now shows the agent **version** and a human
+  **created · idle** time cell, and backfills the **ticket/PR/label** from the
+  indexed session history onto orphan rows that lack them, with the label/topic on
+  its own line — grouped-by-directory layout unchanged, rows stay width-safe.
+  Source: `apps/cli/src/lib/session/active.ts`, `apps/cli/src/commands/sessions.ts`.
+
+- **`agents doctor --check` verdict lines now carry a `check:` prefix and a total
+  version count**, so CI logs and log-scrapers get one consistent, grep-alike shape
+  whether the result is clean or drifted: `check: ok — 3 version(s) in sync` /
+  `check: drift — 2 stale, 1 never-synced across 3 version(s)`. The per-version
+  status badge for a never-synced version now reads `never-synced` (its real
+  status) instead of the unrelated `cold` label, and all three badges
+  (`stale`/`never-synced`/`unwired`) share one fixed-width column so the rows
+  align. Source: `apps/cli/src/commands/doctor.ts` (`runCheckGate`).
+
+- **`agents secrets export --host --remote-backend file` no longer requires
+  `AGENTS_SECRETS_PASSPHRASE`.** Since the file store became passphrase-free
+  (auto-provisioning a 0600 machine-local key under `~/.agents/.secrets-key/`), the
+  remote `import --backend file` reads headlessly under that key with no passphrase
+  and no Touch ID — but the export path still hard-failed unless a passphrase was
+  set, and forcing one made the remote bundle require that shared passphrase to
+  read, defeating the headless use it was for. The passphrase is now **optional**:
+  with none set, the remote command carries no `AGENTS_SECRETS_PASSPHRASE`
+  read/export prologue and the .env is the only stdin, so the remote keys the bundle
+  under its own machine-local key (headless reads); set `AGENTS_SECRETS_PASSPHRASE`
+  locally only to opt into a shared off-disk key, which is still forwarded over ssh
+  stdin (never argv). This unblocks hands-off Linux-driven releases that provision
+  `apple.com` on a headless macOS sign host. Windows targets are still refused
+  cleanly. Source: `apps/cli/src/lib/secrets/remote.ts`,
+  `apps/cli/src/commands/secrets.ts`.
+
+- **Docs: the per-command secrets Touch-ID contract is now written down and
+  accurate.** The `view --reveal` (1.22.14) and `exec` (1.22.21) interactive-unlock
+  changes shipped in code + CHANGELOG only; the reference docs still implied every
+  value command behaves the same. `docs/secrets.md` and the `secrets` skill now
+  carry an explicit Touch-ID matrix (deliberate `view --reveal`/`exec` at a real
+  terminal → one sheet on a locked bundle; `get`/`export` automation primitives →
+  never prompt, fail closed to `agents secrets unlock`; anything an agent launches →
+  broker-only), `specifications.md` adds **SEC-13b** + a `Prompts?` column on the
+  materialization table + `GWT-S2b`, and the skill's stale hold-window facts are
+  corrected (7-day default, screen-lock does not drop the hold). Docs-only; no
+  behavior change. Source: `apps/cli/docs/secrets.md`,
+  `apps/cli/docs/specifications.md`, `skills/secrets/SKILL.md`.
+
+- **Resume session identities through one live-first path across the fleet.**
+  `agents sessions resume <selector>` accepts a full UUID, unique UUID prefix,
+  durable tmux name (`ag-codex-c1f3d813`), or unique alias suffix (`c1f3d813`). It
+  resolves the owning device, rechecks whether the process and pane are alive,
+  attaches a live pane, and otherwise resumes the harness-native conversation with
+  its recorded version, cwd, and mode. Retained dead tmux panes no longer count as
+  attachable, and native resume no longer collides with an existing live wrapper.
+  Source: `apps/cli/src/commands/focus.ts`,
+  `apps/cli/src/commands/sessions-resume.ts`, `apps/cli/src/lib/exec.ts`.
+
+- **`agents fork` is now `agents sessions fork`.** Forking is a session operation, so
+  it lives under the `sessions` group next to `resume`/`focus` — `agents sessions fork
+  <id>` branches a conversation into a new, independent copy you can continue separately,
+  leaving the original untouched. The old top-level `agents fork` keeps working as a
+  hidden alias, so nothing that scripted it breaks. For a harness without a native copy
+  (anything but Claude today), the command now fails loud and names the manual branch —
+  start a fresh agent and seed it with `/continue <id>` — instead of only saying
+  "unsupported". Source: `apps/cli/src/commands/fork.ts`,
+  `apps/cli/src/commands/sessions.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`.
+
 ## 1.22.22
 
 - **New: `agents insights` — how you work, split by the Claude account that did the

package/README.md

@@ -32,6 +32,8 @@
       
   <a href="https://factory.ai" title="Factory AI Droid"><strong>Droid</strong></a>
   &nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://dev.meta.ai/docs/muse-code" title="Meta Muse Code"><strong>Muse</strong></a>
+  &nbsp;&nbsp;&nbsp;&nbsp;
   <a href="https://omp.sh" title="Oh My Pi"><strong>Pi</strong></a>
 </p>
 
@@ -218,7 +220,11 @@ otherwise the first permission option offered by the server. The same last-resor
 warning applies.
 
 Codex has no native smart-classifier mode, so `agents run codex --mode auto` resolves
-to sandboxed `edit` and can still prompt. `agents run codex --mode skip` is different:
+to sandboxed `edit` and can still prompt. When `--mode` is omitted for Codex, the same
+safe writable mode is used: the workspace, `~/.agents`, and regenerable toolchain caches
+are writable; network access is enabled; and approvals are requested on demand. An
+explicit `--mode plan` keeps the filesystem read-only while leaving network access on.
+`agents run codex --mode skip` is different:
 it bypasses approvals **and** removes the sandbox. `full` remains an alias for `skip`,
 but new scripts should use the explicit `skip` name.
 
@@ -297,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:
@@ -307,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` |
@@ -326,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.
 
@@ -345,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
@@ -684,7 +691,7 @@ tools:
 ---
 ```
 
-Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit`, or `--mode auto` on Claude Code and GitHub Copilot. Reserve `--mode skip` (legacy alias: `full`) for last-resort bypasses. `agents run` defaults to `--mode plan` (read-only), which deadlocks at `ExitPlanMode` in headless runs.
+Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit`, or `--mode auto` on Claude Code and GitHub Copilot. Reserve `--mode skip` (legacy alias: `full`) for last-resort bypasses. `agents run` defaults to `--mode plan` for other harnesses; Codex defaults to its safe writable profile. An explicit Codex `--mode plan` is read-only with network access.
 
 Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` overrides a same-named workflow in `~/.agents/workflows/`. Commit project workflows with your repo so teammates get the same pipeline.
 

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