@phnx-labs/agents-cli 1.20.87 → 1.20.89

package/CHANGELOG.md

@@ -1,5 +1,328 @@
 # Changelog
 
+## 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
+  readout (RUSH-2069).** Comprehensive by default (no `--verbose`): a top
+  `✗ CRITICAL — needs you now (N)` section lists every critical across the whole
+  fleet worst-first (`device · harness@version · account · message → remediation`),
+  then a `─── by computer ───` section gives each device its warnings plus a
+  compact accounts/versions line showing every installed version and its account
+  (provable ✓ / ✗). A single-machine `agents doctor` collapses to the CRITICAL
+  section plus one `▸ <machine>` block. Severity: provable logged-out, a missing
+  hook/plugin, a broken CLI, and a never-synced version whose declared resources
+  are therefore absent are CRITICAL; drift, version-skew, repo-behind/-drift,
+  orphans, and an unprovable logout are WARNINGS. Sign-in is
+  now probed **per installed version** (each version's own home + the global
+  credential via the new `credentialPresence`), so a per-version logged-out claim
+  is made only when both are absent, agents with no inspectable identity never
+  report logged-out, and the login remediation is
+  version-targeted (`agents run <agent>@<version>` for the isolated set;
+  gemini/antigravity/droid/cursor say the login is shared). Older fleet boxes that
+  can't report per-version sign-in surface an "older agents-cli — upgrade"
+  warning. The readout is de-duplicated so one root cause is one line: a version's
+  missing hooks/plugins and drifted resources collapse to a count plus two
+  examples (`32 hooks missing (incl. 'a', 'b')`), the same problem on several
+  versions of one agent reads as `claude (5 versions)` with an agent-wide fix
+  (isolated copies stay on their own line, since the sweep skips them), every
+  orphan row on a machine folds into one cleanup-only line, and a version that
+  already listed its drifted resources no longer also says "sources changed since
+  last sync". The two advisories that predate the redesign are findings now, not
+  separate blocks: credential-shaped exports in shell rc files (RUSH-1968) and the
+  Windows execution policy that blocks `agents.ps1`. The duplicate-version-home
+  hook check keeps its text output too — differing copies are critical, identical
+  ones a warning, one row per agent rather than one per hook — and so does the
+  Host CLIs check, as a `host CLIs` warning naming `agents cli install <name>`.
+  Remediations reach every version in their row: a row collapsed across versions
+  uses `agents sync <agent>@all --yes` (a bare `agents sync <agent>` would fix only
+  the default version), a cross-device resource gap says `agents repo pull` rather
+  than the central-to-home `agents doctor --fix`, and a diverged config repo names
+  its own alias instead of always saying `user`.
+  `agents doctor --json` adds a `findings` array and a per-version
+  `fleet.signIn` map; the existing `clis`/`sync`/`orphans`/`fleet`/`signIn`/`repos`
+  fields are unchanged. Source: `apps/cli/src/lib/devices/doctor-findings.ts`,
+  `apps/cli/src/lib/devices/fleet-inventory.ts`, `apps/cli/src/lib/agents.ts`,
+  `apps/cli/src/commands/doctor.ts`.
+
+- **Run Cursor routines safely (RUSH-2080).** Routines configured with `agent: cursor` now reuse the same-device login under the default sandbox, trust the configured workspace without `--yolo`, warn when a requested read-only plan is elevated to writable edit mode (including `loop:` jobs), and record successful runs correctly. Source: `apps/cli/src/lib/runner.ts`.
+
+- **`agents sessions` now discovers, indexes, and renders Cursor agent transcripts (RUSH-2081).**
+  Cursor writes its conversation to `projects/<encoded-cwd>/agent-transcripts/<uuid>/<uuid>.jsonl`
+  and metadata to `chats/<workspace-hash>/<uuid>/meta.json`. Discovery starts from the transcript
+  and joins metadata by UUID, so abandoned chats with no transcript never become empty rows.
+  Cursor is installed outside agents-cli's managed version homes, so users with any managed
+  agent version must pass `--unmanaged` to include Cursor rows.
+  Source: `apps/cli/src/lib/session/discover.ts`, `apps/cli/src/lib/session/parse.ts`.
+
+- **Fix Cursor usage and account inspection (RUSH-2082).** `agents usage` now derives support from the usage library so Cursor, Grok, and future usage sources cannot drift from the command, and `agents run cursor@` can inspect Cursor's active account. Source: `apps/cli/src/commands/usage.ts`, `apps/cli/src/lib/agents.ts`.
+
+- **Sync Cursor commands to the IDE and cursor-agent CLI (RUSH-2083).** Shared commands now remain available as typed IDE slash commands and are also generated as Agent Skills for cursor-agent, while preserving user-authored files in `.cursor/commands/`. Source: `apps/cli/src/lib/command-skills.ts`.
+
+- **Daemon routines resolve `agents` on `~/.local/bin` installs.** The generated daemon service (systemd + launchd) now puts the `agents` shim's own directory on `PATH`, not only the Node runtime dir. On a box where the shim lives outside the Node bin dir (a `~/.local/bin` global install, a separate npm prefix), the daemon's `PATH` previously carried only the Node dir, so every scheduled `command` routine — the always-on watchdog included — shelled out to a bare `agents` that resolved to nothing and died with `exit 127`. Source: `apps/cli/src/lib/daemon.ts`.
+
 ## 1.20.87
 
 - **`agents devices enable|disable|prefer|unprefer <name>` control which machines

package/README.md

@@ -165,7 +165,7 @@ agents run codex@ "review this branch"
 
 A trailing `@` opens an account picker before either an interactive or prompt-based run. Each installed version shows its account identity, exact version, login state, plan, and every available session, weekly, or monthly limit. Logged-out, rate-limited, and out-of-credit accounts remain visible with the reason they cannot be selected; signed-in accounts whose provider does not expose quota data stay selectable and say `limits unavailable`. The choice pins only that run and does not change your default version.
 
-Account selection is available for Claude, Codex, Antigravity, Grok, Kimi, Droid, and OpenCode. It requires a terminal and cannot be combined with `--resume`, `--strategy`/`--balanced`, `--lease`, or `--host`/`--device`; profiles and workflows must use their concrete host agent instead.
+Account selection is available for Claude, Codex, Gemini, Cursor, Antigravity, Grok, Kimi, Droid, and OpenCode. It requires a terminal and cannot be combined with `--resume`, `--strategy`/`--balanced`, `--lease`, or `--host`/`--device`; profiles and workflows must use their concrete host agent instead.
 
 ### Chain agents
 
@@ -1002,16 +1002,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>
@@ -1116,7 +1124,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 | Antigravity | yes | yes | yes | yes | yes | yes | yes | no | `AGENTS.md` | no |
 | Grok Build | yes | yes | yes | yes | yes | skills ($name) | yes | no | `AGENTS.md` | no |
 | OpenClaw | yes | yes | yes | no | yes | gateway | yes | yes | `workspace/AGENTS.md` | no |
-| Cursor | yes | no | yes | no | yes | yes | no | no | `.cursorrules` | no |
+| Cursor | yes | yes | yes | yes | yes | IDE + skills ($name) | yes | >= 2026.1.22 | `.cursorrules` | no |
 | OpenCode | yes | no | yes | >= 1.1.1 | yes | yes | no | no | `AGENTS.md` | no |
 | Copilot | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
 | Amp | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
@@ -1125,7 +1133,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 | Roo Code | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
 | Droid | yes | yes | yes | >= 0.57.5 | >= 0.26.0 | yes | yes | yes | `AGENTS.md` | no |
 
-**Legend:** `yes` / `no` = synced or skipped at install time. `skills ($name)` = no file-based slash-command dir; behavior ships as a generated skill invoked with `$command`. `gateway` = OpenClaw resolves slash commands at runtime, not from synced files. Version suffixes are enforced at sync time — out-of-range versions are skipped with a clear message.
+**Legend:** `yes` / `no` = synced or skipped at install time. `skills ($name)` = no file-based slash-command dir; behavior ships as a generated skill invoked with `$command`. `IDE + skills ($name)` = an IDE command file plus a generated skill for the CLI. `gateway` = OpenClaw resolves slash commands at runtime, not from synced files. Version suffixes are enforced at sync time — out-of-range versions are skipped with a clear message.
 
 **Host CLIs** (`agents cli`) are separate: YAML manifests under `~/.agents/cli/` install binaries onto your PATH (`gh`, `higgsfield`, etc.). They are not copied into per-agent version homes.
 

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

@@ -22,30 +22,11 @@
  * apply pending sync.
  */
 import type { Command } from 'commander';
-import { type FleetDivergenceReport } from '../lib/devices/fleet-divergence.js';
 import { type VersionResourceReport } from '../lib/doctor-diff.js';
 import { type DuplicateVersionHook } from '../lib/hooks.js';
 import { type SyncStatusRow, type OrphanRow } from '../lib/drift.js';
 import { type FetchStatusMarker } from '../lib/auto-pull.js';
 export declare function wrapLine(prefix: string, text: string, width?: number): string[];
-/**
- * Windows-only advisory lines. When the effective PowerShell execution policy
- * blocks unsigned local `.ps1` scripts (`Restricted`/`AllSigned`), the generated
- * `agents.ps1` launcher fails in PowerShell even when it is on PATH. Surface the
- * remediation; the `.cmd` companion still works, so this is a warning, not an
- * error, and doctor never auto-changes the policy. Pure — returns `[]` on
- * non-Windows or a permissive policy, so it is testable without invoking
- * PowerShell.
- */
-export declare function execPolicyWarningLines(platform: NodeJS.Platform, policy: string | null): string[];
-/**
- * Render the cross-device divergence section for `agents doctor --devices`
- * (RUSH-2027): a clean all-clear when the fleet agrees, otherwise the specific
- * gaps — a resource/version present here but missing on a box, or a diverged
- * config repo — grouped by device, each a plain-language line. Devices that
- * couldn't be compared (offline / older CLI) are named so the readout is honest.
- */
-export declare function renderFleetDivergence(report: FleetDivergenceReport): string[];
 export type IssueSeverity = 'critical' | 'warning' | 'info';
 /**
  * One triaged health finding. `severity`/`category`/`subject`/`impact`/`fix` are