@phnx-labs/agents-cli 1.20.88 → 1.20.90

package/CHANGELOG.md

@@ -1,5 +1,508 @@
 # Changelog
 
+## 1.20.90
+
+- **`agents sessions --active` now shows one row per agent, not one per directory.**
+  A live tmux agent pane whose durable identity records were missing (the common case
+  once meta/pid-registry entries age out) was dropped, then re-surfaced by the ps-scan
+  under the newest transcript in its cwd — so many distinct sessions collapsed onto one
+  stranger's id with an inflated `×N` badge, and `agents sessions focus <id>` could not
+  find them. The scanner now recovers the session id straight from the `ag-<agent>-<shortid>`
+  tmux pane name (resolved to the full UUID via the short-id index in one batched query),
+  and refuses to borrow a co-located sibling's transcript when no id is known — so every
+  live session surfaces as its own row and is focus-able again. Also adds a `runTmux`
+  timeout so a wedged tmux server can't hang the scan. Source: `apps/cli/src/lib/session/active.ts`.
+
+- **`agents view` now shows live usage bars for Antigravity.** The `agy` account
+  row renders one bar per model quota bucket (`3.1P: ███░░ 42% (1d)` style),
+  sourced from the same Google Code Assist `:retrieveUserQuota` endpoint `agy`
+  itself talks to. Auth reuses the stored `agy` OAuth credential (macOS Keychain
+  item `gemini`/`antigravity`, Linux Secret Service, or the
+  `~/.gemini/antigravity-cli/antigravity-oauth-token` file fallback), refreshing
+  the access token in memory when expired — safe from a read path because
+  Google's refresh tokens are non-rotating, and never written back to the
+  keychain. Each per-model bucket also flows into the throttle badge, run
+  rotation eligibility, and `agents view --json` (whose usage windows now carry
+  a `label` so same-keyed per-model bars are distinguishable). Source:
+  `apps/cli/src/lib/usage.ts`, `apps/cli/src/lib/agents.ts`,
+  `apps/cli/src/commands/view.ts`.
+
+- **A custom harness is now its own agent type in `agents view`.** A harness created
+  with `agents harness add` (or `agents profiles add`) used to render as an indented
+  `profile` row under whichever host CLI executes it. It now gets its own block beside
+  Claude and Codex — a bold name header, then one row carrying the pinned model, the
+  account/auth state, and `via <host> <version>` naming the native harness underneath.
+  That matches how it is already launched: `agents run <name>` treats a custom harness
+  exactly like a native agent id. A harness whose host CLI has no install is flagged
+  `(host <id> not installed)` rather than listed as runnable, and the separate
+  "Profile-only Agents" section is gone — those harnesses now render in the main list
+  like every other one. Source: `apps/cli/src/commands/view.ts`.
+- **`agents view <harness>` describes a custom harness** — host, model, provider, auth,
+  fork lineage, YAML path — instead of failing with "unknown agent";
+  `agents view <harness> --json` emits its summary. Source:
+  `apps/cli/src/commands/harness.ts` (`renderHarnessDetail`).
+- **New `agents harness fork <source> <name>`.** One verb over both starting points:
+  fork a native harness (`agents harness fork opencode deepseek --model
+  deepseek/deepseek-v4-flash-0731 --auth-provider openrouter`) or copy a custom one you
+  already tuned and change only what you name (`agents harness fork deepseek
+  deepseek-chat --model deepseek/deepseek-chat-v3`). Forking a custom harness is a full
+  copy — env, endpoint, auth binding, `fallback_model`, host version pin — so the two
+  diverge and deleting the source never affects the fork; forking a native harness
+  requires `--model` because there is no model to inherit. Flags: `--model`,
+  `--base-url`, `--auth-provider`, `--version`, `--label`, `--description`,
+  `--key-stdin`, `--force`. Source: `apps/cli/src/lib/profiles.ts` (`forkProfile`).
+- **Profile YAML gains optional `label:` and `forkedFrom:`.** `label` sets the name
+  `agents view` prints for the harness (defaults to the file name); `forkedFrom` records
+  the parent as display-only lineage. Existing profiles keep working untouched. Source:
+  `apps/cli/src/lib/profiles.ts`.
+- **Breaking (`--json`):** in `agents view <agent> --json`, the per-agent `profiles` key
+  is now `harnesses`, and each entry carries new `label`, `hostVersion`, `description`,
+  and `forkedFrom` fields alongside the existing ones. Source:
+  `apps/cli/src/commands/view.ts` (`ViewJsonAgent`).
+
+- **Menu bar ACTIVE: project accordion + session detail submenu.** Projects are
+  collapsed by default as a status strip (`▶ agents-cli  ●8 ◐1  zion`); click
+  `▶`/`▼` to fold agents open under the project (idle-row caps removed — collapse
+  is the wall protection). Focusing an agent opens a side submenu with linkable
+  detail (work title URL, cwd, Linear ticket, GitHub PR, duration, copy session
+  id) from the warm `sessions --active` cache. Accordion reopen rebuilds from
+  cache only (no teams walk / no CLI schedule). Local/remote uses the same host
+  normalize as CLI `machineId()` so local rows are not mislabeled remote. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`,
+  `LocalState.swift`, `Models.swift`.
+
+- **An offloaded editor tab no longer displays another session's id.** A Factory
+  tab launched with `agents run --host <device>` has no local agent process, but
+  the extension still resolved its "live" session id by reading the SessionStart
+  hook's `~/.agents/.cache/state/sessions/<pid>.json` for the local pid tree —
+  the pid of the ssh client. Those files are keyed by pid alone and are only
+  pruned when the pid is dead, so once the OS recycled a pid the tab adopted
+  whatever session had last held it: one remote tab showed the id and version of
+  an unrelated synthetic run from 20 days earlier while `/status` inside it
+  reported the truth. An offloaded tab now takes its identity from the device
+  instead of local disk, and a local tab rejects any state record whose
+  SessionStart timestamp predates the tab itself.
+- **`AGENT_TERMINAL_ID` now rides the SSH hop.** `agents run --host` forwarded
+  actor provenance but not the launching tab's terminal id, so the remote pid
+  registry recorded no terminal — leaving `agents sessions --active --host
+  <device>` unable to answer "which session is this tab running?" once the agent
+  moved on (a `/clear`, or an exit and rerun in the same tab).
+- **`agents sessions --active --json` now carries `terminalId`.** The pid registry
+  has always recorded it; the emitted row dropped it, so no consumer could join a
+  live session back to the editor tab that launched it.
+
+- **Balanced routing no longer launches into an account it only *thinks* has
+  headroom.** Account usage is cached per machine under stale-while-revalidate:
+  a snapshot up to 24h old was served instantly, and the background refresh that
+  should have corrected it lands after the pick is already made. On a box whose
+  refresh is failing that state is permanent — measured on `yosemite-s1`, every
+  Claude snapshot sat 26 hours to 2.7 days old, so balanced read
+  `muqsit@getrush.ai` as 48% used and launched into it while the account was at
+  its weekly cap; the session answered "You've hit your weekly limit" on its
+  first turn. Routing now caps how stale a snapshot may be when it is about to
+  decide (5 minutes), blocking on one bounded, parallel live read past that — and
+  no read at all inside the existing 2-minute fresh window, which back-to-back
+  launches hit. Display paths (`agents view`) keep the full 24h window and stay
+  off the network.
+- **A pick made on unconfirmed data says so.** When no account on the machine
+  could be refreshed, routing still launches — a broken refresh must not make a
+  box unusable — but the banner now reads `… (2 of 5 healthy, usage unverified —
+  no account could be refreshed)` instead of presenting a guess as a fact. An
+  account with a verified snapshot always wins over one with a stale snapshot,
+  even when the stale number looks emptier. This applies to `--strategy
+  available` as well as `balanced` — both route on the same cache, and
+  `available`'s headroom sort was inverted by a stale number in exactly the same
+  way. An explicit version preference is an instruction, not a ranking signal, so
+  it still wins.
+- **The mid-run failover chain is unchanged.** Declining to *pick* an account on
+  unconfirmed data and declining to *fail over to* it after the primary already
+  hit a 429 are different risks — by then the alternative is not launching at
+  all. Every eligible account stays in the failover chain; only the initial pick
+  prefers verified ones.
+
+- **`agents routines list` no longer reports another device's routine as failed.** Run
+  records are written into the runs dir of whichever machine fired the routine and carry
+  no device attribution, but the listing resolved Last Status from any local record and
+  rendered it even on rows for routines pinned elsewhere. A routine re-pinned to another
+  device therefore kept reporting the old machine's leftover records forever — on zion,
+  `security-sweep`, `review-open-prs` and `hetzner-lease-gc` all read `failed` from late
+  July while `yosemite-s0`/`s1`, the devices that actually fire them, had completed them
+  that morning. The macOS menu bar reads this JSON, so it painted a column of red `exit 1`
+  rows for routines that were green. Last Status is now scoped to the device that owns the
+  run: a routine this device does not fire shows `-`, and `--json` returns `null` for
+  `lastStatus`, `exitCode`, `failureReason`, `lastRunStartedAt` and `lastRunCompletedAt`
+  (`runsHere: false` already says why). A routine pinned to several devices renders one row
+  per device but carries a status only on its **This machine** row. Read a peer's status
+  with `agents routines list --device <name>`; the local history is untouched and still
+  readable via `agents routines runs <name>`. Source: `apps/cli/src/commands/routines.ts`
+  (`localLatestRun`, `groupRoutineJobsByDevice`), `apps/cli/docs/03-routines.md`.
+
+- **`agents watchdog` now tracks per-session presence (RUSH-2007 Layer C).** Each
+  tick reconciles a per-session presence record — `{location, device, transport,
+  lastSeen, status}` at `~/.agents/.cache/state/watchdog/presence.json` — from the
+  tick's active scan, deriving `connected` / `disconnected` by diffing consecutive
+  ticks. A session that was tracked but is now absent (its SSH link dropped or the
+  peer went unreachable) flips to `disconnected`, and the flip is surfaced in
+  `agents watchdog --json` under `presence.transitions` — an interactive drop as a
+  `reconnect-nudge` candidate, a headless remote as `keep-alive`. Folded into the
+  existing tick (no revived daemon, no extra SSH fan-out); additive and does not
+  change the tick's nudge decisions. Source:
+  `apps/cli/src/lib/session/presence.ts`, `apps/cli/src/lib/watchdog/runner.ts`.
+
+- **`agents setup secrets --policy hold` no longer fails, and `agents secrets
+  status` stops naming the retired `daily` policy.** The 1.20.79 `daily` → `hold`
+  rename swept the help, docs, and the `secrets list` POLICY column, but two
+  surfaces were never migrated. The worse one was functional: the onboarding
+  wizard carried its own copy of the policy vocabulary, so
+  `agents setup secrets --policy hold` — the canonical name every other secrets
+  command prints — exited with `Invalid --policy 'hold'. Use daily, always, or
+  never.`, and its interactive prompt still offered `daily` as the default
+  choice. It now shares `parsePolicyOpt` with `agents secrets policy`, so the two
+  commands can't disagree about what a policy is called; `daily`/`session` stay
+  accepted as aliases and the wizard's default is unchanged (the hold tier). The
+  second was cosmetic: `agents secrets status` printed "a daily bundle prompts
+  once…" and "the next read of each daily bundle…" — the one command a user runs
+  to answer *why did it prompt again*, naming a policy its sibling commands no
+  longer emit. Both lines now say `hold` and are pure values pinned by tests, so
+  the vocabulary can't drift again. Source:
+  `apps/cli/src/commands/setup-secrets.ts`, `apps/cli/src/commands/secrets.ts`.
+
+- **Favorite sessions from the browser.** `*` stars the highlighted session in
+  `agents sessions` and `f` filters the list to the starred ones; outside a TTY,
+  `agents sessions favorite <id>` (`--remove` / `--list` / `--json`) and
+  `agents sessions --favorites` do the same. Stars live in
+  `~/.agents/.history/favorites.json` keyed by session id, so they survive a reindex
+  of the session cache. They are per-machine — session sync carries transcripts, not
+  this file. Source:
+  `apps/cli/src/lib/session/favorites.ts`, `apps/cli/src/commands/sessions-favorite.ts`.
+- **Detect sessions that lost their host — two new statuses, `crashed` and `orphaned`.**
+  A session whose editor window or connection went down hard used to just VANISH from
+  `agents sessions --active` (its dead-pid registry entry was filtered out), and one
+  still running in tmux with nobody attached reported a plain `idle`. Both now say so:
+  `✗ crashed` when the host window stopped republishing and the agent died with it,
+  `◍ orphan` when the agent is alive with zero clients attached. Derived from tmux's
+  `#{session_attached}` and the IDE window's registry heartbeat — never from a
+  deliberate `agents sessions detach`, and never over a session that is still working.
+  Source: `apps/cli/src/lib/session/host-link.ts`, `apps/cli/src/lib/session/active.ts`.
+- **`agents sessions --active --favorites` now actually filters.** The flag was wired
+  into the interactive browser only, so every path that skips it — `--json`,
+  `--waiting`, a pipe, a multi-host scope, an SSH-fanout peer — silently returned the
+  whole fleet. Source: `apps/cli/src/commands/sessions.ts`.
+- **`agents sessions --active --waiting` no longer counts a dead session.** `activity`
+  is not rewritten when a session dies, so one that crashed mid-question reported "needs
+  your input" forever — what it needs is a relaunch. Source:
+  `apps/cli/src/commands/sessions.ts`.
+
+- **Resolve historical sessions safely across the fleet (#1757).** `agents sessions --resolve <full-id|prefix|keywords> --json` uses a versioned safe peer protocol, returns only resolver metadata, reports every full-ID candidate on ambiguity, treats synced copies as one match, and exits 2 without deciding when a peer fails, returns malformed output, or runs an older CLI. Source: `apps/cli/src/commands/sessions.ts`.
+
+- **A rate-limited usage endpoint is now backed off instead of hammered.** The
+  daemon warms auth-health every 3 minutes and probes *every installed version
+  home* in one parallel batch, so a machine with five Claude accounts sent five
+  concurrent requests to `api.anthropic.com/api/oauth/usage` every three minutes
+  — roughly 100/hour — before the usage refresh added its own. Nothing read
+  `Retry-After`. Measured on `yosemite-s1`: the endpoint answered
+  `429 rate_limit_error` with `retry-after: 2678` (about 45 minutes) for every
+  account while the credentials themselves read healthy, and the next tick fired
+  three minutes later, deep inside the penalty window, re-arming it. The box
+  never recovered, every usage read failed, and its cache froze — the
+  permanently-stale state balanced routing was already having to defend against.
+- **A 429 now records its deadline and every read honours it.** Usage fetches and
+  health probes for that provider short-circuit until the window passes — no
+  request, no renewed penalty — and report
+  `Claude rate-limited this machine — not retrying for 45 minutes.` The state is
+  on disk, because the callers are separate processes: the long-lived daemon and
+  every one-shot `agents view` / `agents run` — one empty file per penalty under
+  `~/.agents/.cache/usage-backoff/`, named `<agent>.<deadline>`, so two
+  processes recording the same provider at once cannot displace each other and a
+  read takes the furthest deadline. A server delay is capped at an hour, and a
+  missing or unparseable `Retry-After` still backs off.
+
+- **A usage read that fails now says so, instead of returning a silent null.**
+  Four branches in every networked usage fetch — Claude, Kimi, Droid and
+  Cursor — returned `{ snapshot: null, error: null }`: no readable credential, a
+  locally-expired one, a rejected request, and a request that threw (timeout,
+  DNS/TLS, an unparseable payload). The caller could not tell any of them apart
+  from a healthy read, so it fell
+  back to whatever the stale-while-revalidate cache held and drew those bars as
+  fact. Measured on `yosemite-s1`: every Claude account's stored access token had
+  expired (one of them eleven days earlier), so no read could succeed, and
+  `agents view claude --refresh` printed a full, healthy-looking table twice
+  while writing nothing to the cache. A usage read never refreshes a token
+  (RUSH-1822), so an expired credential does not heal on its own — the account
+  stays unreadable until that agent actually runs. A rate-limited endpoint (429)
+  now reads differently from a rejected credential (401), because re-authing
+  fixes one and not the other.
+- **`agents view` marks bars the live read could not confirm.** A row whose
+  snapshot came from the cache after a failed live read renders the reading plus
+  `unverified`, rather than looking identical to a confirmed one. The number
+  still shows — it is the last thing we saw — but it no longer reads as current.
+- **`agents view --refresh` reports what it could not refresh.** It now lists
+  each account it failed to reach and why, instead of rendering a table that
+  looks fully refreshed regardless.
+
+## 1.20.89
+
+- **Webhook handler layer for one-off agent/workflow/command/routine triggers.**
+  Routines still fire from signed webhooks, but a new `~/.agents/webhooks/*.yml`
+  layer can also run one-off actions: `run.agent`, `run.workflow`, `run.command`,
+  or delegate to an existing `routine`. Handlers support the same source/event/
+  action/label/repo/branch filters as routine triggers, plus Linear
+  `stateTo`/`stateFrom` state-change filters. Prompts and commands can use
+  `{{issue.identifier}}`, `{{updatedFrom.state.name}}`, etc. The receiver emits
+  `webhook.received`, `webhook.authorized`, `webhook.rejected`, `webhook.matched`,
+  `webhook.fired`, `webhook.handler.start`, and `webhook.handler.end` events.
+  Source: `apps/cli/src/lib/triggers/handlers.ts`,
+  `apps/cli/src/lib/triggers/webhook.ts`, `apps/cli/src/lib/routines.ts`,
+  `apps/cli/src/commands/routines.ts`, `apps/cli/docs/03-routines.md`.
+
+- **`agents routines add` gains `--state-to` and `--state-from` filters for Linear
+  triggers.** A Linear routine or handler can now fire only on a specific state
+  transition (for example `--state-to Plan`), instead of on every issue update.
+
+- **Values substituted into `run.command` are shell-quoted.** A webhook context is
+  built from an external payload, and fields like `issue.title` or a GitHub
+  `pull_request` title are free text any outside contributor can set — pasted raw
+  into a shell command they would be a command-injection sink. Substituted values
+  are now single-quoted (POSIX `sh`), so a payload stays one inert argument while
+  the operator's own template keeps its pipes, redirects, and `&&`. On Windows,
+  where `exec` runs through `cmd.exe` and these quoting rules do not hold, a
+  `run.command` containing `{{…}}` is refused with a clear error rather than run.
+  `run.prompt` is unaffected — it never reaches a shell.
+  Source: `apps/cli/src/lib/routines.ts` (`substituteWebhookCommand`,
+  `assertShellSubstitutionSupported`), `apps/cli/src/lib/triggers/handlers.ts`.
+
+- **The `Cmd-Shift-O` quick-dispatch bar now lists the repo's open Linear tickets,
+  and dispatches one on a click (RUSH-2098).** The panel only captured NEW work;
+  it now also shows what already exists. Switching the repo dropdown switches the
+  Linear project (the repo name is matched against `linear projects` reduced to
+  lowercase alphanumerics, so `agents-cli` finds "Agents CLI" with nothing to
+  configure; a worktree resolves to its parent repo, and a repo that matches no
+  project says so and lets you pick one, remembered per repo). Rows are ranked
+  urgent-first — Linear priority, then overdue, then in progress, then newest —
+  and typing filters them, so an existing ticket surfaces before Return files a
+  duplicate. Clicking a row (or `⌘1`–`⌘5`) dispatches that ticket to the selected
+  agents in the picked repo: **Run** claims it and implements it, **Plan** posts a
+  plan as a ticket comment. `⌘`-click opens it in Linear instead. The list renders
+  from a 90-second warm cache so the panel still appears instantly. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/LinearTickets.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/AgentsCLI.swift`.
+
+- **Fixed: a menu-bar dispatch whose child printed more than ~64 KiB hung forever
+  and never notified.** The helper read a monitored child's stdout only from the
+  process-termination handler, so a child that filled the pipe buffer blocked on
+  write, never exited, and the completion callback never fired — two `linear`
+  processes were left wedged by a single ticket fetch. Both monitored paths (the
+  ticket agent and `linear create`) now drain stdout, and feed stdin, on a
+  background queue while the child runs. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/AgentsCLI.swift`.
+
+- **The daemon warns when it was launched from an ephemeral root.** A daemon
+  started from a temp dir (`/tmp`, `/var/folders`, `/dev/shm`) or a git worktree
+  resolves its own job modules by dynamic `import()` rooted at the launch entry
+  (`getAgentsBinPath` → `process.argv[1]`). When that directory is later removed
+  — a `/tmp` cleanup, a review/verify checkout teardown, `git worktree remove` —
+  the long-lived daemon keeps ENOENT-ing on every routine's imports
+  (`auto-dispatch.ts`, `routines-placement.ts`, `devices/fleet.ts`), silently
+  wedging until restart. `anchorDaemonCwd` already rescues the cwd, but nothing
+  can re-root a deleted module tree. `runDaemon` now calls
+  `warnEphemeralDaemonRoot` at startup, so the risk is logged the moment the
+  daemon comes up — including a direct `agents __daemon-run` that never passes
+  through the launch-time `validateDaemonBinary` check. That launch-time check is
+  also broadened from git-worktree-only to any ephemeral root via the shared
+  `describeEphemeralDaemonRoot` predicate. The fix for a wedged daemon is
+  unchanged: run it from the globally installed binary
+  (`npm i -g @phnx-labs/agents-cli`) so its entry roots at a stable version home.
+  Source: `apps/cli/src/lib/daemon.ts`
+  (`describeEphemeralDaemonRoot`, `warnEphemeralDaemonRoot`, `validateDaemonBinary`).
+
+- **A `README.md` / `AGENTS.md` sitting in a resource directory is no longer
+  installed as a resource.** `listResources` skipped only dotfiles, so every `.md`
+  beside the actual resources was materialized as one: `commands/README.md` — which
+  the system repo has shipped for months — installed a bogus `/README` slash command
+  into every agent home, and adding per-directory `AGENTS.md` docs would have added
+  `/AGENTS`, `/CLAUDE`, and `/GEMINI` alongside it. `README`, `AGENTS`, `CLAUDE`, and
+  `GEMINI` are now filtered from both `listResources` and `resolveResource` for every
+  kind **except `rules`**, where `AGENTS.md` *is* the resource (the composed ruleset
+  that syncs as each agent's memory file). The check tests `!entry.isDirectory()`
+  rather than `isFile()`, because a `Dirent` for a symlink reports
+  `isFile() === false` and `CLAUDE.md`/`GEMINI.md` are symlinks to `AGENTS.md` by
+  convention — a resource *directory* named `agents/` is still a real resource.
+  Verified against the real installed layers: 30 commands with `README` leaking
+  before, 29 with none after.
+- **`agents commands list` and the command picker no longer offer a name that
+  cannot be opened.** `listCentralCommands` and `discoverCommands`
+  (`src/lib/commands.ts`) run their own `readdirSync` scans rather than going
+  through `listResources`, so they kept offering `README` while
+  `agents commands view README` answered "not found" — a listed-but-unopenable
+  name. Both now share the one exported `isDirectoryDoc` predicate, so every
+  enumerator agrees. Verified: 27 names with `README` before, 26 with none after.
+- **`agents commands add/remove/view` no longer suggest `README` as the example
+  command name.** With `README` reserved as a directory doc, the six hardcoded
+  examples in the help text and non-interactive hints named a command that can never
+  exist. They now use `plan`, which actually ships.
+
+- **File-backed secrets bundles no longer require `AGENTS_SECRETS_PASSPHRASE` on
+  macOS.** The encrypted file store now silently auto-provisions a stable
+  machine-local key (a 0600 file under `~/.agents/.secrets-key/`, kept outside the
+  encrypted store) on first use on **every** platform, macOS included — no prompt,
+  no Touch ID, nothing to set or remember. Previously a file-backed bundle on a Mac
+  hard-failed unless `AGENTS_SECRETS_PASSPHRASE` was exported, which blocked
+  headless reads (e.g. the `auth` bundle the usage/auth reader consults) and
+  frequently hung. Setting `AGENTS_SECRETS_PASSPHRASE` still works and takes
+  precedence — use it to hold the key off disk or to share one bundle's ciphertext
+  across boxes under a common key. Source: `apps/cli/src/lib/secrets/filestore.ts`,
+  `apps/cli/src/lib/secrets/bundles.ts`.
+
+- **Menu-bar & daemon notifications now use the current agents-cli mark, not the
+  legacy logo.** A desktop notification from the menu-bar helper or the routines
+  daemon showed the old `assets/logo.png` gradient "A" — outdated, and blank in the
+  notification's left-hand app-icon slot. `MenubarHelper.app`'s `AppIcon.icns` is
+  now generated from the current brand mark (`assets/app-icon.svg` → `app-icon.png`:
+  the lime-tile lowercase `a` shared with the agi-cli web favicon and the menu-bar
+  glyph), which drives both the notification's right-hand `contentImage` and its
+  left-hand app icon. The installer also registers the bundle with LaunchServices
+  (`lsregister -f`) at its `~/Library/Application Support` path so the OS can resolve
+  that app icon. Source: `apps/cli/menubar/scripts/build.sh`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`, `assets/app-icon.svg`.
+
+- **The menu bar is a single instance, always.** Two copies of the helper could
+  run at once — launchd's `KeepAlive` service plus a LaunchServices/`open` launch
+  of the same `.app` — putting two agents marks in the menu bar, and the second
+  copy could hold `Cmd-Shift-V`/`Cmd-Shift-O` (`RegisterEventHotKey` is
+  first-come). The helper now takes an `flock` on
+  `~/.agents/.cache/state/menubar.lock` at launch and holds it for its lifetime;
+  a helper that cannot take the lock pops the **running** helper's menu open and
+  exits 0, since re-launching a menu-bar app means "show me the one I already
+  have". An `flock` rather than a pid file: the kernel releases it when the
+  holder dies, so a `SIGKILL`ed helper cannot leave a stale "already running"
+  that blocks every later launch. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/SingleInstance.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/StatusItemController.swift`.
+
+- **`agents menubar setup` configures the menu bar end-to-end.** One idempotent
+  command for a machine that is wrong — never configured, helper down, or showing
+  a duplicate icon. It ends every running helper, installs/refreshes the bundle,
+  checks its code signature, writes the launchd login item (`RunAtLoad` +
+  `KeepAlive`), clears a previous `agents menubar disable`, and verifies exactly
+  one helper came back up — reporting each as its own step and exiting nonzero if
+  it cannot reach that state. `--check` reports without changing; `--json` emits
+  the step list. Source: `apps/cli/src/commands/menubar.ts`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`.
+
+- **`agents menubar status` now shows a duplicate.** Live helper processes were
+  collapsed to a boolean `running`, so two copies of the *installed* bundle — the
+  duplicate a user actually sees — reported as healthy. `--json` now carries an
+  `instances` array (copies of the installed bundle) beside the existing
+  `foreignInstances`, and the text readout names every extra pid and points at
+  `agents menubar setup`. Source:
+  `apps/cli/src/lib/menubar/install-menubar.ts` (`classifyMenubarProcesses`).
+
+- **Quick-dispatch ticket list: one-row filter + sort, and a scrollable list.**
+  The ticket controls sit on a single row of popups next to the Linear project
+  (project · filter · sort) — not a chip matrix or two-column block. Quick filter
+  options: All open, Todo, Doing, Backlog, P1 only, P2 only, Overdue. Quick sort
+  options: Urgent first, Newest, Oldest, Due date, Priority (flat list, no
+  status grouping). Filter and sort picks are remembered across summons. Ticket
+  rows scroll inside a fixed viewport so more than five matches stay reachable
+  without growing the panel. Source:
+  `apps/cli/menubar/Sources/MenubarHelper/LinearTickets.swift`,
+  `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`.
+
+- **`release.sh` now takes a release lease, and refuses to bump past an
+  unpublished tag.** Releases run from whichever fleet box an agent happens to be
+  on, so two agents could enter the pipeline at once; the collision only surfaced
+  at the publish gate (`merged tree != built tree -- refusing to publish`), after
+  one run had already merged and tagged, leaving the version merged but unshipped.
+  A new `scripts/release-lease.sh` holds mutual exclusion on `origin` as an orphan
+  commit at `refs/release-lock/held` — a second claimant's push can never be a
+  fast-forward, so git's rejection *is* the failed lock acquisition. The lease is
+  claimed before the first mutation and dropped by the existing cleanup trap on
+  every exit path. Because a healthy release routinely outlives any sane
+  expiry — the CI matrix alone has run 57 minutes and release 1.20.77 took 186
+  minutes — the lease is **renewed** by a background renewer for the whole run,
+  and the squash-merge, the tag, and the publish each **verify** ownership first,
+  failing closed if it can no longer be proven. A lease that stops being renewed
+  is reclaimable after 30 minutes, and reclaiming names the dead holder instead
+  of silently overwriting it. Separately,
+  `release.sh` now refuses to cut a new version while an older `v*` tag exists
+  that npm never received, and points at the re-run that finishes it — bumping
+  past an unpublished tag is what turned a one-version gap into npm 1.20.78 vs
+  main 1.20.81. Source: `apps/cli/scripts/release-lease.sh`,
+  `apps/cli/scripts/release.sh`.
+
+- **`agents funnel down` disables a public Funnel port from the same wrapper used
+  to enable ingress.** Webhook ingress now has a complete local receiver runbook:
+  keep GitHub/Linear signing keys in `agents secrets`, bind the receiver to
+  `127.0.0.1`, expose it with `agents funnel up`, rotate one source secret at a
+  time, and turn the public port off with `agents funnel down` before stopping or
+  moving the receiver. Source: `apps/cli/src/commands/funnel.ts`,
+  `apps/cli/src/lib/funnel.ts`, `apps/cli/docs/03-routines.md`.
+
+- **New `agents secrets rotate-passphrase` re-keys the encrypted file store under
+  a new master passphrase, atomically (RUSH-1975).** Until now there was no
+  supported way to rotate the file-store passphrase — `rekey` only renames macOS
+  keychain service names and `rotate <bundle> <key>` replaces a single secret
+  value, so a leaked passphrase (RUSH-1968) could only be remediated by a
+  hand-rolled non-atomic script or an export-to-plaintext round-trip (the exact
+  exposure being fixed). The new command decrypts every `<item>.enc` under the
+  current key, re-encrypts under a freshly generated one, and swaps both the
+  ciphertext and the 0600 key file by directory rename after verifying every item
+  round-trips. A crash at any point self-heals on the next *rotate* run to a single
+  readable store — content-aware recovery probes which key actually decrypts the
+  live store (not merely which files are present) and classifies the WHOLE store:
+  it completes the rotation forward or rolls back only when one key opens every
+  item, and if a later `secrets set` contaminated a crashed rotation into a MIXED
+  store (items under two keys at once, or a store dir recreated by an interstitial
+  write after the crash left it absent, so its backup holds items the live dir does
+  not) it refuses with an actionable error and preserves every recovery artifact
+  rather than sweeping the only copy of a key or the backed-up ciphertext — so a
+  crash anywhere in the swap can never orphan the store, even when a write landed in
+  between. The rotation and every store write run under
+  one cross-process lock, so a `secrets set` or a second rotation can never
+  interleave with a swap in the first place. No plaintext secret or passphrase is
+  ever written to disk, argv, or a log. Items
+  that don't decrypt under the current key (orphan caches, stale test artifacts)
+  are carried through verbatim, never re-keyed. Dry-run by default (`--commit` to
+  apply). A dry run never re-keys, but it *does* heal an interrupted rotation —
+  that is how a crashed store becomes readable again without re-keying it — and it
+  says so instead of claiming nothing was written. Refuses while the secrets-agent
+  holds live unlocks or while
+  `AGENTS_SECRETS_PASSPHRASE` is exported in the environment, unless `--force`.
+  Headless-safe and Linux-first. Source: `apps/cli/src/lib/secrets/filestore.ts`,
+  `apps/cli/src/commands/secrets-rotate-passphrase.ts`.
+
+- **`agents sessions --active --json` now reports who is watching each session.**
+  The `viewingIn` field carries the same string the table prints — `codium tab 3`,
+  `ghostty tab 2`, or `detached` for a live tmux pane with **no client attached**
+  (its terminal was closed or crashed). It is `null` both for a session that isn't
+  tmux-hosted and for one whose pane the locator could not resolve — `detached` is
+  claimed only when the pane was actually located, so absence of evidence is never
+  reported as evidence of absence. Previously the JSON path returned
+  before the locator pass ran, so the field never appeared and a machine consumer
+  could not tell a session someone is looking at from an orphaned one — which is
+  exactly what the Factory extension's `Agents: Resume` picker ranks by. The JSON
+  path resolves tmux clients only — no osascript — so scriptable output keeps the
+  cheapness the old ordering was protecting; a Ghostty-attached client resolves as
+  `ghostty` without its tab number. Peers running an older CLI that still emits the
+  `{app, tab}` object are normalized at the fan-out boundary, so a mixed-version
+  fleet sweep stays correct. Source: `apps/cli/src/lib/session/viewing-in.ts`
+  (`viewingInLabel`, `parseViewingIn`), `apps/cli/src/commands/sessions.ts`
+  (`serializeActiveSessionsForJson`, `enrichTmuxLocators`),
+  `apps/cli/src/lib/session/remote-active.ts`.
+
+- **Webhook handlers gain `run.env` and `host` placement.** A handler can now
+  inject environment variables into the process it spawns (`run.env`), and choose
+  where that run executes (`host`). `host` takes a device name (`yosemite-s0`), or
+  `fleet` to pick any eligible online worker, or `fleet/<platform>` /
+  `<platform>/fleet` (also a bare `linux` / `macos` / `windows`) to restrict that
+  pick to one platform. A fleet expression that matches no eligible device fails
+  loudly rather than silently falling back to the local machine, so `fleet/linux`
+  can never land on a macOS box. Omitting `host` runs locally, as before.
+  Source: `apps/cli/src/lib/triggers/handlers.ts` (`resolveHandlerHost`),
+  `apps/cli/src/lib/routines-placement.ts` (`pickFleetDevice` platform filter),
+  `apps/cli/src/lib/routines.ts` (`JobConfig.env`), `apps/cli/src/lib/runner.ts`.
+
 ## 1.20.88
 
 - **`agents doctor` redesigned into a prioritized, fleet-aware, per-version

package/README.md

@@ -265,6 +265,8 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 |---|---|---|
 | `s` | search text | `--query` / positional |
 | `r` | running only | `--active` |
+| `f` | favorites only | `--favorites` |
+| `*` | star / unstar the highlighted session | `agents sessions favorite <id>` |
 | `c` | team sessions | `--teams` |
 | `a` | agent (cycles) | `-a` |
 | `d` | device (cycles) | `--device` |
@@ -274,6 +276,10 @@ On a terminal, `agents sessions --active` (and a bare `agents sessions`) open th
 | `⏎` | resume / attach | `resume` / `focus` |
 | `y` | copy the equivalent command | `--print-cmd` |
 
+**Star the sessions you keep coming back to.** `*` marks the highlighted row (a `★` shows in the listing), `f` narrows to the starred ones, and `agents sessions favorite <id>` / `--favorites` do the same outside a TTY. Stars live in `~/.agents/.history/favorites.json` keyed by session id, so they survive a reindex of the session cache. They're per-machine — session sync carries transcripts, not this file.
+
+**A session that lost its host says so.** When an editor window or an SSH connection goes down hard, the agent it owned used to simply disappear from `--active`; when an agent outlived its window in tmux, it reported a plain `idle`. Both now carry their own status: `✗ crashed` (the host went down and took the agent with it) and `◍ orphan` (still alive, but no client is attached — nothing is showing it). Read from tmux's attached-client count and the editor window's registry heartbeat, so a deliberate `agents sessions detach` is never mistaken for one, and a session that is still *working* headlessly is left alone.
+
 Filters **stack** (they AND together), the active set shows in the header, and the highlighted row **previews below by default** (`tab` hides it) — prompt, activity, last response, plus a links line where the worked-on ticket and the PR the session opened are **clickable** (OSC 8 hyperlinks: the ticket jumps to Linear, the `PR#` to GitHub, in terminals that support them). The Linear workspace is resolved from `LINEAR_WORKSPACE` or the linear-cli config, so tickets stay plain text when it's unknown. Because every hotkey has a flag, the view you build by hand is a real command: press `y` (or run `--print-cmd`) to get the exact `ag sessions …` line — explore interactively, hand the line to an agent. Piped output, `--json`, or `--no-interactive` keep the plain listing for scripts. Peek without opening the pager with `agents sessions <id> --preview`.
 
 | before — preview hidden | after — preview open + clickable links |
@@ -1002,16 +1008,24 @@ Other useful commands: `agents doctor` checks CLI availability and resource sync
 On macOS, `agents-cli` puts a status item in your menu bar -- a live glance at what your agents are doing, plus a Spotlight-style bar for filing work without breaking focus.
 
 ```bash
-agents menubar enable      # install + launch at login
+agents menubar setup       # configure end-to-end: one instance, started at login
 agents menubar status      # is it installed and running?
 ```
 
+There is only ever **one** agents mark: the helper takes a lock at launch, so a
+second copy surfaces the running one's menu and exits instead of adding a
+duplicate icon. `agents menubar setup` is the recovery command when a machine is
+already wrong -- it ends any duplicate, installs the bundle, wires the login
+item, and verifies exactly one helper came back up.
+
 The dropdown surfaces a **NEEDS YOU** queue (agents waiting on a question, a plan review, or a permission prompt), the running roster, and a routines summary -- the same live state as `agents sessions --active`, one click away.
 
 ### Quick-issue bar (⌘⇧O)
 
 Press `Cmd-Shift-O` anywhere for a thin capture surface: type a one-line note, `Cmd-V` to paste, and attach one or more recent screenshots (double-click a thumbnail to preview it in full). Submit, and a headless agent picks the right project from your recent sessions, investigates, and files the Linear ticket itself -- you never leave what you were doing.
 
+The bar also lists the **open Linear tickets of the repo you picked**, urgent first. Switching the repo switches the Linear project; typing filters the list, so an existing ticket shows up before you file a duplicate; and clicking a row (or `⌘1`-`⌘5`) dispatches that ticket to the selected agents -- **Run** implements it, **Plan** posts a plan as a ticket comment.
+
 <p align="center">
   <img src="assets/menubar-quickissue.svg" alt="The Cmd-Shift-O quick-issue bar: a one-line note with attached screenshot thumbnails that a headless agent turns into a filed Linear ticket" width="100%" />
 </p>

package/dist/commands/commands.js

@@ -35,7 +35,7 @@ Examples:
   agents commands add
 
   # Install specific commands by name
-  agents commands add --names README,debug --agents codex@0.116.0
+  agents commands add --names plan,debug --agents codex@0.116.0
 
 When to use:
   - Project setup: 'agents commands add gh:team/commands' to sync everyone's workflow
@@ -90,7 +90,7 @@ Examples:
   agents commands add
 
   # Install specific commands to a single version
-  agents commands add --names README,debug --agents codex@0.116.0
+  agents commands add --names plan,debug --agents codex@0.116.0
 
   # Pull commands from GitHub and sync to all installed agents
   agents commands add gh:user/repo --agents claude,codex,cursor
@@ -125,7 +125,7 @@ Examples:
                 else {
                     if (!isInteractiveTerminal()) {
                         requireInteractiveSelection('Selecting commands from ~/.agents/commands/', [
-                            'agents commands add --names README,debug --agents codex',
+                            'agents commands add --names plan,debug --agents codex',
                             'agents commands add gh:user/repo --agents codex',
                         ]);
                     }
@@ -272,7 +272,7 @@ Examples:
         .addHelpText('after', `
 Examples:
   # Remove a command by name
-  agents commands remove README
+  agents commands remove plan
 
   # Interactive: pick commands to remove
   agents commands remove
@@ -305,7 +305,7 @@ Examples:
             }
             if (!isInteractiveTerminal()) {
                 requireInteractiveSelection('Selecting commands to remove', [
-                    'agents commands remove README',
+                    'agents commands remove plan',
                 ]);
             }
             try {
@@ -422,7 +422,7 @@ Examples:
         .addHelpText('after', `
 Examples:
   # View a specific command
-  agents commands view README
+  agents commands view plan
 
   # Interactive picker
   agents commands view
@@ -437,7 +437,7 @@ Examples:
             }
             if (!isInteractiveTerminal()) {
                 requireInteractiveSelection('Selecting a command to view', [
-                    'agents commands view README',
+                    'agents commands view plan',
                 ]);
             }
             try {

package/dist/commands/exec.js

@@ -59,7 +59,13 @@ function formatRotationBanner(result, verb = 'balanced') {
     const { picked, healthy, excluded } = result;
     const label = picked.email ? `${picked.email} · ${picked.agent}@${picked.version}` : `${picked.agent}@${picked.version}`;
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
-    return `[agents] ${verb} picked ${label} (${ratio})`;
+    // Say it when the pick was a guess. A machine whose usage refresh is failing
+    // reports old percentages with total confidence, so a silent banner reads
+    // identical whether the router knew the account had headroom or merely hoped
+    // so — and the operator only finds out when the agent answers "you've hit
+    // your weekly limit".
+    const caveat = result.usageUnverified ? ', usage unverified — no account could be refreshed' : '';
+    return `[agents] ${verb} picked ${label} (${ratio}${caveat})`;
 }
 /**
  * Whether `cwd` is inside a git work tree.