@phnx-labs/agents-cli 1.22.42 → 1.22.44

package/CHANGELOG.md

@@ -1,5 +1,154 @@
 # Changelog
 
+## 1.22.44
+
+- **Browser domain-skill discovery is layer-aware (RUSH-2497).** `agents browser start --url <url>` auto-loads a site-specific SKILL.md, but the lookup only ever searched the user layer (`~/.agents/skills/browser/domain-skills`), so a skill shipped in the system layer (`~/.agents/.system/skills/browser/domain-skills`) — or a project's `.agents/` — was silently invisible: the browser just opened without the guide. `resolveDomainSkill` now searches project > user > system > extra repos, first layer with a match wins, mirroring `resolveResource` precedence; `$AGENTS_BROWSER_DOMAIN_SKILLS_DIR` stays a single-root override for tests. The project layer resolves from the calling process's cwd — the shared browser daemon does not yet receive the CLI caller's cwd over IPC, so there the project layer follows the daemon's own cwd until RUSH-2996 threads it through. A miss still never breaks browser start, but now logs the roots searched at debug level (`AGENTS_DEBUG`/`DEBUG`) — the total silence is what hid this. Source: `apps/cli/src/lib/browser/domain-skills.ts`.
+
+- **`agents artifacts share list/update/delete` (and the `unshare` alias) had a silently-dropped `--json`/`--github-user` (RUSH-2687).** Commander resolves an option's long name against the WHOLE ancestor chain, not per-command — `share <file>` (the parent) already declares `--json`/`--github-user` for its own publish-time use, so the same-named flag on `list`/`update`/`delete` was swallowed at parse time even when passed alone (`--help` still showed it registered, which made it easy to miss). `agents artifacts share list --json | jq …`, the exact example in `docs/share.md`, never emitted JSON. Fixed by renaming the colliding options — `--list-json`/`--for-user` (list), `--update-json` (update), `--delete-json`/`--for-user` (delete/unshare) — matching the precedent `share revisions` already set (`--revisions-json`/`--for-user`, RUSH-2683). A CLI-wide `enablePositionalOptions()` fix was evaluated and reverted: commander copies that setting onto every command created via `.command()`, so enabling it on the root program broke `sessions backfill tools/resources --since … --json …`, which relies on a parent command's options staying visible to leaf subcommands via `optsWithGlobals()`. Source: `apps/cli/src/commands/share.ts`, `apps/cli/src/lib/startup/root-command.ts`.
+
+- **`agents artifacts share` publishes with a partial `share:` config (RUSH-2837).** `status` and publish both used to treat a missing/empty `accountId` as "not set up", even when `baseUrl` and `WRITE_TOKEN` were present — so a fleet rewrite that blanked `accountId` (or a partial `writeMeta` that dropped `share:`) silently killed PR evidence uploads. Publish now requires only `baseUrl` + the write token; `status` reports the endpoint and names an empty account id instead of pretending nothing is configured; `writeShareConfig` will not persist `accountId: ""` over a stored id; `serializeCentral` no longer deletes `share:` just because a write omitted the key. Source: `apps/cli/src/lib/share/config.ts`, `apps/cli/src/lib/state.ts`, `apps/cli/src/commands/share.ts`.
+
+- **Pick a device-local account after fleet placement (RUSH-2961).** `agents run <harness>@` now composes with `--device <name|auto>`: the device resolves first, then the interactive picker lists that peer's installed versions/accounts and pins the selection for this run. Automatic picker placement prefers a ready account, retains signed-out/revoked login targets, and excludes devices whose picker would contain only rate-limited or out-of-credit rows. `agents view --json` exposes each version's cached `authVerdict` so remote and local placement apply the same revoked-token gate. Source: `apps/cli/src/commands/{exec,view}.ts`, `apps/cli/src/lib/{smart-launch,hosts/dispatch,hosts/ready}.ts`.
+
+- **BREAKING: nest `agents beta` under `agents setup beta`; retire top-level `agents apply`; drop `harness login`/`logout` (RUSH-2981).** Enabling a preview feature is setup, not its own noun — `agents setup beta list/enable/disable` keep the same `~/.agents/agents.yaml` `beta.enabled` write path. Fleet reconcile is already `agents fleet apply` / `agents devices apply`; top-level `apply` is gone (unknown command, retired from distance-1 auto-correct). Harness credentials live on `agents accounts` — `harness login`/`logout` are removed. Does not touch org/auth/trends/audit/unshare (sibling session 01a02234). Source: `apps/cli/src/commands/{beta,setup,apply,harness}.ts`, `apps/cli/src/lib/startup/command-registry.ts`.
+
+- **Nest leftover top-level aliases; keep `agents org` as a deprecated spelling (RUSH-2989).**
+  `agents unshare` moves under `agents artifacts unshare` (same takedown as
+  `artifacts share delete`; the top-level name is retired). `agents audit` moves
+  under `agents events audit` (still `events --include runs`, plus `verify` for
+  the legacy hash-chain). Former top-level `agents trends` is `agents insights mix`
+  (also `agents insights trends`). `agents org` still works and prints a deprecation
+  line; the canonical tree is `agents auth space`. Prix login stays off
+  `agents accounts` (that noun is harness keys). Source:
+  `apps/cli/src/commands/{auth,org,artifacts,share,events,audit,insights}.ts`,
+  `apps/cli/src/lib/analytics/mix-commands.ts`.
+
+- **`agents view` shows Claude usage again — the daemon auth-health probe no longer hammers `/oauth/usage` into a permanent 429 (RUSH-2998).** The daemon's fleet auth-health probe (`probeLocalFleetAuth` → `probeClaudeStatus`) hit the rate-limited `/api/oauth/usage` endpoint every ~3 minutes on **every** device. Across the fleet that drove one per-account request quota to a persistent `429`; the shared `Retry-After` backoff then parked usage fleet-wide and the usage cache froze (windows stale-zeroed → `agents view` rendered `S: 0% (now) W: 0% (now)` for weeks). The periodic tick now re-probes the endpoint at most every 20 minutes (`AUTH_PROBE_MAX_AGE_MS`) and reuses the last real verdict in between — a ~5x cut in endpoint traffic. Fleet status still publishes every tick (it does not ride that endpoint), and every device keeps a **real** auth verdict, so `agents devices ping --strict` and the run auth-preflight keep detecting revocation on every host. `agents devices ping` forces a genuinely live probe (never the throttled cached verdict). Source: `apps/cli/src/lib/daemon-ticks.ts` (`AUTH_PROBE_MAX_AGE_MS`, `isCachedFleetAuthProbeFresh`, `refreshLocalFleetAuthState` `force`), `apps/cli/src/commands/ssh.ts` (`runFleetPing`).
+
+- **BREAKING: remove `agents serve`, its `--control` anchor, and `agents devices pair-ios` (RUSH-3001).**
+  The read-only local web companion (`agents serve`) duplicated what `agents sessions`,
+  `agents teams status`, and the AGI EXT Fleet panel already show, and its `--control`
+  mode existed only to anchor the unshipped iOS Fleet Cockpit prototype (`apps/ios`,
+  untouched since 2026-07-16, no Xcode project) — both are gone, and so is the prototype
+  itself. `agents devices pair-ios` (the only writer of the device registry's `control`
+  role) is removed with it; with no writer left, the `control`-only dial-exclusion
+  filters (`isControlDevice`) are removed too, across `doctor`, `apply`, `fleet status`,
+  `fleet-capture`, `smart-launch`, the devices host provider, session fan-out, and
+  remote login detection. `agents serve` now reports `unknown command` and is retired
+  from distance-1 auto-correct; `agents devices pair-ios` is rejected by `devices` as an
+  unexpected argument.
+  **Migration —** if you previously ran `agents devices pair-ios`, that phone or tablet is
+  still in your device registry with `role: control`, and the key is now ignored rather
+  than honoured: it becomes an ordinary fleet target. `agents fleet status`,
+  `agents fleet update/run`, `agents apply`, `agents doctor --check --devices`,
+  `agents insights output --all-hosts`, and any `--device all` passthrough will dial it and
+  wait out a ConnectTimeout; `agents hosts list` shows it as dispatchable; `--device auto`
+  can place an agent on it when no device is marked `worker`; and routine fleet placement
+  can schedule a recurring job onto it, since an `unknown`-platform device sorts ahead of a
+  real worker alphabetically. Failures are loud, not silent. Remove it with
+  `agents devices rm <name>`; the stale `role` key is dropped anyway on that device's next
+  `agents devices sync`. Session fan-out is unaffected — it still gates on a
+  `windows`/`linux`/`macos` platform.
+  Source: `apps/cli/src/commands/{serve,ssh}.ts`,
+  `apps/cli/src/lib/devices/{registry,fleet,pool,discovery-policy}.ts`,
+  `apps/cli/src/lib/{smart-launch,remote-agents-json,device-config}.ts`,
+  `apps/cli/src/lib/hosts/{registry,providers/devices}.ts`,
+  `apps/cli/src/lib/session/{watch,remote-list}.ts`, `apps/cli/src/lib/fleet/remote-login.ts`,
+  `apps/cli/src/cli/command-registry.ts`, `apps/cli/src/lib/startup/command-registry.ts`.
+
+- **Menu-bar helper restarts after a bundle swap; one-time TCC migration; `agents menubar doctor` (RUSH-3019).** `installMenubarLaunchAgentOnUpgrade()` swapped the installed bundle on an upgrade but never restarted the running helper — verified live: a helper pid started 21:44:16 kept running while the bundle under it was replaced at 21:53:46, so it kept requesting Accessibility under the OLD code identity and the grant never stuck. The heal now kickstarts the launchd job (`launchctl kickstart -k`) after a real content swap (a version bump or the ad-hoc -> Developer ID transition — a plist-only interpreter repoint, RUSH-3005's churn, does not trigger this) and falls back to ending the specific pid(s) still running the old binary when `kickstart -k` can't reach the GUI launchd domain from a non-Aqua shell context, so launchd's `KeepAlive` relaunches from the swapped binary. Separately, a machine that transitioned ad-hoc -> Developer ID (6fa36f73a) now gets a one-time `tccutil reset Accessibility com.phnx-labs.agents-menubar` to clear the dead grant recorded against the old identity, stamped so it never re-runs. The "Paste needs Accessibility" notification now opens System Settings' Accessibility pane on click and names the actual running bundle path. New read-only `agents menubar doctor` reports install path, installed vs CLI version, signing identity stability, and whether a live helper pid predates the on-disk bundle (the stale-process bug this fixes). Source: `apps/cli/src/lib/menubar/install-menubar.ts`, `apps/cli/src/commands/menubar.ts`, `apps/cli/menubar/Sources/MenubarHelper/Clip.swift`.
+
+- **Daemon autostart no longer fires under a redirected (sandbox/test) HOME (RUSH-3021).** #2860 gated service-manager registration on `isolatedHomeSuffix()` but left `ensureDaemonStarted()`'s detached spawn ungated, so a test-spawned CLI could fork a daemon into the test's temp HOME; the child outlived the test and raced its recursive teardown `rm` (the `ENOTEMPTY` flake that cost most full-suite attestation rolls on shared boxes). The launch path now refuses under a redirected HOME via the same `serviceManagerRegistrationAllowed()` signal and `AGENTS_SERVICE_MANAGER_ALLOW_REDIRECTED_HOME` test seam; reporting an already-running daemon is untouched, and `agents daemon start` remains the operator override. Source: `apps/cli/src/lib/daemon/daemon.ts` (`ensureDaemonStarted`), regression test in `apps/cli/src/lib/daemon/daemon.registry.test.ts`.
+
+- **The npm tarball no longer bundles the version-stamped signed CLI binary — releases publish from any OS (RUSH-3026).** `dist/bin/agents` (the Developer-ID-signed arm64 Mach-O, #315) embedded the release version, so every release forced a fresh Mac build + sign even when nothing native changed — chaining publishing to a single provisioned Mac (`mac-mini`), whose downtime stranded merged fixes unshippable. The binary is dropped from `package.json` `files` and the `prepack` gates; `postinstall`'s existing run-probe falls back to the JS entrypoint when the binary is absent, so macOS installs keep working (it returns as a per-release GitHub asset in a follow-up). `release.sh`'s home-base phase — already promote-only (download attested tarball, verify, install-smoke, `npm publish`) — drops its vestigial macOS gate, and a new `assert_promote_home_base` preflight (npm token + gh auth, via `scripts/promote-home-base-probe.sh`) runs BEFORE the release's first mutation, fixing the tagged-but-unpublished failure shape: the old signing preflight was defined but never invoked. The two `.app` helpers (keychain, menubar) remain bundled and manifest-reused — unchanged helpers are never rebuilt. Source: `apps/cli/package.json`, `apps/cli/scripts/release.sh`, `apps/cli/scripts/promote-home-base-probe.sh`.
+
+- **`agents sync` restores a resource deleted from a version home — no `--force` needed (#2398, #2397).** The staleness fast-guard decided sync-ness from source fingerprints alone, so a managed artifact deleted from the version home (a subagent, command, skill, hook, MCP config, or rules file) read as "Already in sync" and only `--force` restored it. The sync manifest now records the artifact paths the last full sync wrote (`writtenTargets`, reported by each resource writer), and `isStale` treats a missing path as stale — one `existsSync` per path, no content reads, so the fast-guard budget holds. A manifest written by an older agents-cli lacks the field and reads as stale once; that full sync establishes the baseline. Relatedly, four commands (`agents commands/skills/hooks/subagents remove`) claimed a removed resource "will re-sync on next agent launch" — the shim's launch hook (`agents sync --launch`) is project-scoped only and deliberately skips version-home reconciliation, so the messages now name the real recovery: `agents sync <agent>@<version> --yes`. `agents doctor --fix` was already immune (it heals from the live-home diff, not the manifest). Source: `apps/cli/src/lib/staleness/{index,types}.ts`, `apps/cli/src/lib/staleness/writers/{types,commands,skills,hooks,mcp,subagents,rules}.ts`, `apps/cli/src/lib/installations/versions.ts`, `apps/cli/src/commands/{commands,skills,hooks,subagents,prune}.ts`.
+
+- **`agents devices list` no longer serves fossilized load/mem numbers (#2666).** The
+  fleet stats cache (`.fleet-stats.json`) had no age bound and — since RUSH-2061
+  removed the daemon's N² fleet warm — no background writer, so the load/mem columns
+  froze at the last manual `--refresh` and re-rendered as current fleet state
+  indefinitely (observed: a 9-day-old row reporting an idle Mac at 1058% load). Cached
+  rows are now bounded by `STATS_STALE_MS` (3 minutes, the same window as the
+  agent-count mirror): a row past the bound is treated like a missing one — re-probed
+  live this call and rewritten — so the default `devices list` / `devices status` read
+  is itself the cache's writer and a stale value can never be presented as current.
+  This cache feeds the fleet scheduler, `--device auto` affinity, and the
+  session-start fleet banner. Source: `apps/cli/src/lib/devices/stats-cache.ts`,
+  `apps/cli/src/commands/ssh.ts`.
+
+## 1.22.43
+
+- **Rush Cloud no longer has a helper that reads the interactive Claude login (RUSH-2359 / incident #1767).** Dispatch already sends an email-only account manifest (SING-1b) and never uploaded a token; the leftover `readClaudeCredentialsBlob` still read Keychain / `.credentials.json` — the exact shape that captured a `claude setup-token` TTY banner as an Authorization header. That helper is deleted. `--lease` SING-1b detection now reads the wrapped rotating blob itself and ignores anything that is not `{ claudeAiOauth.accessToken }`. Source: `apps/cli/src/lib/cloud/rush.ts`, `apps/cli/src/lib/crabbox/runtimes.ts`.
+
+- **fix: `agents sync <agent>` self-heals version pointers left aimed at an uninstalled version (RUSH-2471).** `removeVersion` reassigns the default and clears the `~/.<agent>` config symlink only when it removes the pointed-at version, so a version-home whose launch binary vanished by any other route — grok self-updating its per-version binary out from under the old dir, a manual delete, a half-finished install that seeded the home but never landed the binary — left the global default and/or the symlink resolving to a dead version. Because `agents use <agent>@<v>` sets the default and the symlink together, both dangled in lockstep once `<v>`'s binary went away: `agents sync <agent>` would print `Repointed <agent> config symlink …` and then still fail `<agent>@<v> is not installed`, because the version to sync is resolved from the raw global default. `agents sync <agent>` now repoints the global default, the isolated default, and the config symlink off any not-installed version before resolving — the default to the newest non-isolated installed version (never auto-promoting an isolated install), the symlink to the resolved default else the newest non-isolated installed version (the user's real `~/.<agent>` is never repointed at an isolated install). A pointer already on an installed version (a deliberate `agents use` choice), a real config directory, and isolated-only agents are left untouched. Source: `apps/cli/src/lib/installations/versions.ts`, `apps/cli/src/commands/sync.ts`.
+
+- **Session preview groups metadata into verb-led rows (RUSH-2757, part 3).** `agents sessions preview` (and the picker pane) replaces the flat labeled block (`Prompt/Todos/Dirs/Repos/Changes/Artifacts/Skills/Plugins/Hooks/Links/Errors/Meta/Tools/Tests`) with five scannable verb rows in a fixed gutter — `Asked` (the originating prompt, quoted), `Doing` (checklist progress, team lineage, sub-agents), `Made` (file deltas, reads, artifacts, plan, PR), `Health` (errors + last test verdict, absent when clean), `Cost` (msgs, tokens, tool mix) — then `Latest` (the full wrapped last message, formerly `Last response:`) and one width-capped `Details ▸` fold (session id, skills, plugins, hooks, links, dirs, repos) that shows `… +N more` instead of wrapping and swamping the pane. Msgs/tokens/session-id move out of the header's third line into `Cost`/`Details`, so they render once. The metadata-only card (remote/unindexed sessions) uses the same rows. Source: `apps/cli/src/commands/sessions-picker.ts` (`formatCompactPreview`, `formatMetaOnlyBody`, `formatHeader`, `joinWidthCapped` — now ANSI-aware).
+
+- **`pr-merge-on-green` can actually select a PR (RUSH-2848).** The built-in's poll ran `gh pr list --author @me` with no `--repo`, so `gh` inferred the repository from cwd; the daemon's cwd is not a git repo and every poll returned empty. The poll now walks registered project slugs (`~/.agents/projects/*.yaml`), canonicalizes renamed repos (`phnx-labs/agents-cli` → `phnx-labs/agi-cli`), and lists with `--repo`. Verdict matches `merge-guard.sh`: a formal GitHub `APPROVED` review **or** an APPROVE comment on THIS PR (carried-from citations do not count). Hidden `agents _internal mergeable-prs` prints `owner/repo#n` (cwd-independent). Source: `apps/cli/src/lib/github/pr-verdict.ts`, `apps/cli/src/lib/github/pr-mergeable.ts`. Companion: phnx-labs/.agents-system#347.
+
+- **BREAKING: nest `agents status` under `agents sync status` (RUSH-2864).** `status` was the unified sync-drift report sitting as its own top-level command next to `sync`. It now lives as `agents sync status` (`--json` UnifiedSyncStatus contract and `--yes` reconcile unchanged). Top-level `agents status` is gone, not deprecated: it reports `unknown command`, and `status` is retired from distance-1 auto-correct. `agents sync <agent>` still treats the positional as an agent spec; `status` is reserved as the subcommand. `agents sync status --device` from a non-TTY does not inherit umbrella `--yes` (that flag is reconcile on this command, not "don't prompt"). Source: `apps/cli/src/commands/{status,sync}.ts`, `apps/cli/src/lib/hosts/passthrough.ts`, `apps/cli/src/lib/startup/command-registry.ts`.
+
+- **Custom harnesses (deepseek, kimi-chat, glm, …) now work in routines and monitors, and their profiles survive fleet sync (RUSH-2930).** `agents routines add --agent deepseek` and `agents monitors add --run deepseek` used to refuse any name outside the native registry; both now accept a custom harness (`agents harness list`), and the daemon delegates the job to `agents run <name>` — the same path workflow jobs take — so the profile's host binary, model env, and provider auth resolve exactly as an interactive run. The profile pins its own host version and auth, so `@version` pins, balanced rotation, and account-env injection don't apply to these jobs. Separately, `agents harness add/fork/edit` and the legacy-auth migration stored the account's per-device **id** in the profile, while profiles sync fleet-wide via `agents repo push` — every synced custom harness then died on other machines with `Unknown account '<uuid>'`. The portable account **name** is stored now, and a profile with a dangling ref reports which harness is broken and the exact `agents harness edit <name> --account <name>` repair instead of the bare registry error. Source: `apps/cli/src/lib/daemon/runner.ts`, `apps/cli/src/lib/scheduling/routines.ts`, `apps/cli/src/lib/monitors/config.ts`, `apps/cli/src/commands/{routines,harness,profiles}.ts`, `apps/cli/src/lib/profiles.ts`.
+
+- **BREAKING: remove the top-level `agents tickets` command (RUSH-2932).** Ticket reads go through `linear` (linear-cli) and `gh issue`. `agents tickets` reports `unknown command`, and `tickets` is retired from distance-1 auto-correct. AGI EXT now calls those CLIs directly. Source: `apps/cli/src/cli/command-registry.ts`, `apps/cli/src/lib/startup/command-registry.ts`, `apps/ext/src/vscode/tasks.vscode.ts`.
+
+- **Expired cached usage windows read as unknown, not 0% (RUSH-2936).** A cached Claude usage window whose reset time had passed was zeroed but kept, so a frozen cache (Anthropic has been 429-ing `/api/oauth/usage` per account since ~Aug 5) rendered every account as `S: 0% (now)  W: 0% (now)` with `usageStatus: "available"` — and balanced rotation kept dispatching into genuinely rate-limited accounts (RUSH-2858). `deserializeClaudeUsageSnapshot` now drops expired windows (the same rule the Grok collector already applied); an all-expired snapshot deserializes to null, the dead cache entry self-cleans, `agents view` renders `usage unavailable` plus the recorded throttle reason, and rotation falls back to the coarse cached status instead of trusting a fake 0%. Source: `apps/cli/src/lib/accounting/usage.ts`.
+
+- **`agents doctor <agent>@<version>` no longer marks every missing resource critical (RUSH-2947).** Target mode's `computeVerdict` hardcoded `severity: 'critical'` for any `status: 'missing'` resource of any kind, while fleet mode's `FINDING_SEVERITY` — whose own docblock calls it "the single source of truth" — rates the same fact `warning` for everything except `missing-hook`/`missing-plugin`. A missing command, skill, permission, subagent, rule, or MCP entry now reads `warning` in target mode too, matching fleet mode; a missing hook or plugin stays `critical` in both. `computeVerdict` reads severity from `FINDING_SEVERITY` via a new `missingResourceSeverity(kind)` helper instead of re-hardcoding it. Source: `apps/cli/src/commands/doctor.ts`.
+
+- **BREAKING: nest `agents alias` under `agents setup alias` (RUSH-2965).** Setting up a PATH shorthand is a setup action, not its own noun. `agents setup alias add/list/remove` keep the same shim behavior (`~/.agents/.cache/shims/` + `~/.agents/aliases.json`). Top-level `agents alias` is gone, not deprecated: it reports `unknown command`, and `alias` is retired from distance-1 auto-correct. Source: `apps/cli/src/commands/{alias,setup}.ts`, `apps/cli/src/lib/startup/command-registry.ts`.
+
+- **Block service-manager registration under a redirected HOME on macOS/Linux (RUSH-2968).**
+  `launchctl` and `systemctl --user` are per-user-session and ignore `$HOME`, so a CLI
+  running under a sandbox/redirected HOME (including every vitest fork) still talked to
+  the user's real service manager. `service-manifest.ts` already namespaces the job
+  label, but that only changes the identifier — the registration still lands in real
+  `launchd`/`systemd` (measured: 89 dead `…sandbox-<hash>` services accumulated in one
+  user's real launchd from test runs, KeepAlive-retrying torn-down executables). Every
+  registration path now consults `serviceManagerRegistrationAllowed()` (false when
+  `isolatedHomeSuffix()` is non-null) and skips with a stated reason rather than
+  touching the real service manager: daemon `startDaemon`/`stopDaemon`, menubar
+  `restartMenubarLaunchAgent`/`disableMenubarService`, secrets
+  `retireLegacySecretsAgentService`, and `agents computer start`. A test seam
+  `AGENTS_SERVICE_MANAGER_ALLOW_REDIRECTED_HOME=1` lets the existing shim-based tests
+  continue to exercise the registration code path. Source:
+  `apps/cli/src/lib/service-manifest.ts`, `apps/cli/src/lib/daemon/daemon.ts`,
+  `apps/cli/src/lib/menubar/install-menubar.ts`, `apps/cli/src/lib/secrets/agent.ts`,
+  `apps/cli/src/commands/computer.ts`.
+
+- **BREAKING: the top-level `agents inbox` command is removed — use `agents feed` (RUSH-2984).** `inbox` was a Phase-3 observe alias that re-parsed as `agents feed` (needs-you is already the feed default), the same leftover class as `timeline` (RUSH-2692). It is gone entirely, not deprecated: `agents inbox` now reports `unknown command`, and `inbox` is retired from distance-1 auto-correct. `agents feed` / `feed post` / `feed post --blocked` are unchanged. Source: `apps/cli/src/commands/feed.ts`, `apps/cli/src/lib/startup/command-registry.ts`, `apps/cli/src/bootstrap.ts`.
+
+- `agents auth` and `agents org` now print a clean one-line error (and a structured `{"error"}` payload under `--json`) for signed-out, expired-token, and bad-input states, instead of dumping a raw Node stack trace.
+
+- Fixed balanced Claude account rotation recording session-limit refusals until their stated reset, skipping those accounts, and surfacing `session-limited` in `agents view` instead of idle usage.
+
+- Sandboxed monitor `--run` and routine children now inherit this host's GitHub CLI auth (RUSH-2860). A monitor fire recorded `ok` while the spawned child had no `~/.config/gh`, so `gh auth status` reported "not logged into any GitHub hosts" and the PR it was meant to act on stayed open. The routine sandbox overlay replaces `HOME` with a disposable dir, and `gh` was never linked into it. `prepareJobHome` now links the host's `gh` config dir into the overlay (and only that — `~/.agents` is deliberately not linked, since it holds the secrets master key and the encrypted store), `buildSpawnEnv` pins `GH_CONFIG_DIR` and forwards `GH_TOKEN`/`GITHUB_TOKEN`, and the runner refuses to launch when a routine's own `env:` overrides `GH_CONFIG_DIR` such that this host's gh auth would still be hidden — a regression tripwire rather than a runtime guarantee. Not covered on Windows, where `gh` stores config under `%AppData%\GitHub CLI`.
+
+- **`agents webhooks` now advertises `/hooks/slack`.** The receiver has accepted signed
+  Slack deliveries since the Slack bridge landed, but `agents webhooks serve` and
+  `agents daemon webhooks list` still printed only `/hooks/github, /hooks/linear` — the
+  one URL you must paste into the Slack app was missing from the banner. The slash-command
+  ack now also says "replying in this channel", matching where the reply actually posts
+  (a slash command carries no thread). Source: `apps/cli/src/commands/webhook.ts`,
+  `apps/cli/src/commands/daemon.ts`, `apps/cli/src/lib/triggers/webhook.ts`.
+
+- **Slack/webhook handlers that run an agent actually dispatch now.** A `run.agent` or
+  `run.workflow` webhook handler was gated by the *routine* activation manifest
+  (`~/.agents/devices/<machine>/agents.yaml`). A handler is not a routine, so its name
+  could never be a member — on any box that had materialized that manifest, every
+  delivery was recorded `skipped` with an empty allowlist (`can only run on: `) while the
+  receiver logged it as `fired`, and `agents routines enable <handler>` refuses the name,
+  so there was no way out. Verified live: a real HMAC-signed `/agents` slash command
+  reached the public receiver, acked 200, and started no agent. The job now carries
+  `dispatchedBy: 'webhook'`, the same escape RUSH-2681 gave monitors; a handler's
+  `routine:` delegate still keeps its gate.
+- **`{{slack.response_url}}` is now available to handler prompts.** It was parsed off the
+  wire but never reached the `{{slack.*}}` namespace. Slack accepts a POST there for 30
+  minutes with no token and no channel membership, so it is the only reply that works
+  before the app has been invited to a channel — the shipped example handler now uses it.
+  Source: `apps/cli/src/lib/triggers/handlers.ts`, `apps/cli/src/lib/scheduling/routines.ts`.
+
 ## 1.22.42
 
 - **Plan-tier gates for `agents accounts` and `agents insights` (RUSH-2424).** A new `apps/cli/src/lib/entitlement.ts` reads the live subscription tier from `GET /api/v1/billing/subscription?agent=agi-cli` (the session token in `~/.rush/user.yaml`), caches it on disk for 15 minutes, and stays offline-tolerant: a stale cache is honored over a failed network call, and no session file at all resolves straight to the free tier. `agents accounts add` / `name` / `attach` now cap registered accounts at 3 per harness on free, 10 on paid/admin — a 4th add on free refuses before any write (`free plan is capped at 3 claude accounts (3/3). agents upgrade — up to 10 per harness.`) and the 3rd prints a one-line notice. Downgrading a plan never deletes a credential: over-cap accounts fall out of `accounts switch`/`set-default` (excluded from `listSwitchableAccounts`) and are listed `dormant (upgrade to reactivate)` in `agents accounts`. `agents insights` keeps top-line counts, harness mix, `insights mix`, and `agents perf` free on every tier; the Friction / Friction-thrash / Dissatisfaction-corrections sections, grouping `--by account` (the default), and `--narrative` are paid — a gated section is replaced by the in-voice notice `Friction and account-split analysis are on the paid plan.` in both the text report and `--json` (a new `plan: {tierName, isPaid}` field, `groups: null` when the account breakdown is gated, and the friction/correction facet keys stripped per group otherwise). Source: `apps/cli/src/lib/entitlement.ts`, `apps/cli/src/commands/accounts.ts`, `apps/cli/src/commands/insights.ts`.

package/README.md

@@ -188,9 +188,11 @@ agents run claude "summarize recent commits" --strategy balanced
 # Or choose one account/version interactively for only this run.
 agents run claude@
 agents run codex@ "review this branch"
+agents run claude@ --device auto        # pick the device, then choose there
+agents run claude@ --device yosemite-s0 # choose from one device's accounts
 ```
 
-`--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force the default) -- it never launches into an exhausted account.
+`--strategy balanced` spreads work across available versions of the same agent -- useful when you have multiple accounts and want to avoid burning through one. When a Claude run reports a session limit, agents-cli records the stated reset time, shows `session-limited` in `agents view`, and excludes that account until the reset. When every account is rate-limited, the run exits nonzero naming each excluded account and the earliest window reset (use `--strategy pinned` to force the default) -- it never launches into an exhausted account.
 
 ### Don't care which harness? `agents run auto`
 
@@ -205,7 +207,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the host layer
 
 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, Gemini, Cursor, Antigravity, Grok, Kimi, Droid, and OpenCode. It requires a terminal and cannot be combined with `--resume`, `--strategy`/`--balanced`, `--lease`, or `--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 a warm-box lease. Device routing is resolved first, then the picker is populated from the selected device. Profiles and workflows must use their concrete host agent instead.
 
 ### Chain agents
 
@@ -454,7 +456,7 @@ A stalled session whose tail shows a hard account limit ("You've hit your weekly
 ## Sync the fleet
 
 <p align="center">
-  <img src="assets/fleet-sync.svg" alt="agents apply: reconcile every device to one profile from agents.yaml — install missing agents and sync config. Native logins stay on the machine that minted them." width="100%" />
+  <img src="assets/fleet-sync.svg" alt="agents fleet apply: reconcile every device to one profile from agents.yaml — install missing agents and sync config. Native logins stay on the machine that minted them." width="100%" />
 </p>
 
 
@@ -471,14 +473,14 @@ fleet:
 ```
 
 ```bash
-agents apply --plan                 # device x dimension matrix; changes nothing
-agents apply                        # reconcile the fleet (confirms first; -y to skip)
-agents apply --device yosemite-s0   # scope to one device
-agents apply --only agents,config   # limit dimensions (agents, config, login)
-agents apply --no-login             # skip login propagation
+agents fleet apply --plan                 # device x dimension matrix; changes nothing
+agents fleet apply                        # reconcile the fleet (confirms first; -y to skip)
+agents fleet apply --device yosemite-s0   # scope to one device
+agents fleet apply --only agents,config   # limit dimensions (agents, config, login)
+agents fleet apply --no-login             # skip login propagation
 ```
 
-`agents apply` (`ag apply`) probes every target over the existing SSH transport, then reconciles it to the profile: installs missing agents, upgrades `agi-cli`, syncs the named config scopes, and **propagates logins** so a host signed in once seeds the fleet -- turning "6 hosts x 8 harnesses = 48 OAuth flows" into one. Portable credential files (claude, codex, grok, kimi, opencode, droid, antigravity) stream to each target over encrypted SSH stdin, never shell-interpolated, and land at `0600`. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity on a Mac target) can't be extracted -- those surface as a one-time manual login, never faked. `--plan` / `--dry-run` shows the full matrix without touching anything.
+`agents fleet apply` probes every target over the existing SSH transport, then reconciles it to the profile: installs missing agents, upgrades `agi-cli`, syncs the named config scopes, and **propagates logins** so a host signed in once seeds the fleet -- turning "6 hosts x 8 harnesses = 48 OAuth flows" into one. Portable credential files (claude, codex, grok, kimi, opencode, droid, antigravity) stream to each target over encrypted SSH stdin, never shell-interpolated, and land at `0600`. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity on a Mac target) can't be extracted -- those surface as a one-time manual login, never faked. `--plan` / `--dry-run` shows the full matrix without touching anything.
 
 See [docs/fleet.md](apps/cli/docs/fleet.md) for the manifest schema and reconcile semantics.
 
@@ -670,7 +672,7 @@ age (`updated 2m ago — pass --refresh (--live) for a live probe`).
 `agents fleet status` answers "is my fleet OK?" at a glance: a one-line rollup
 (`● N online · ○ M offline`), a short **NEEDS ATTENTION** list where every item names
 the command that fixes it (offline → `check the box`, config drift or a stark CLI gap →
-`agents apply <box>`, version skew → `agents upgrade --fleet`), then quiet per-device
+`agents fleet apply --device <box>`, version skew → `agents upgrade --fleet`), then quiet per-device
 rows grouped by OS (macOS / Linux / Windows) showing just `name · capacity · load/mem ·
 version`, with this machine flagged `▸ … ← this machine`. A healthy fleet reads in a few
 lines; orphaned versions are demoted to a one-line `agents prune` nudge in the footer.
@@ -1203,7 +1205,7 @@ agents artifacts share plan.html --json                     # URL object for pla
 agents artifacts share list --agent claude                  # everything published, filterable
 agents artifacts share revisions fleet                      # prior versions kept under a slug
 agents artifacts share status                               # show the endpoint
-agents unshare fleet                                        # take a published link (+ its OG cover) down
+agents artifacts unshare fleet                              # take a published link (+ its OG cover) down
 ```
 
 `agents artifacts share` closes the loop: an agent makes work (a plan, a viz, a report),
@@ -1232,7 +1234,7 @@ Republishing an existing slug keeps the prior version as a revision by default
 (`--no-revision` to skip); `agents artifacts share revisions <slug>` shows the retained
 history, newest first.
 
-`agents artifacts share delete <targets...>` (alias `agents unshare`) takes a page down — pass a
+`agents artifacts share delete <targets...>` (alias `agents artifacts unshare`) takes a page down — pass a
 full URL, `<user>/<slug>`, or a bare slug (resolved against your own namespace); several
 targets at once are fine. It also deletes the sibling `<slug>.png` OG cover by default
 (`--keep-cover` opts out) and verifies the page actually 404s before reporting success —
@@ -1505,7 +1507,7 @@ For full transparency: `agi-cli` keeps a local event log at `~/.agents/.cache/lo
 
 macOS and Linux. Windows via WSL works but isn't first-class yet.
 
-**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents harness login`) require macOS. Default iCloud sync for bundles requires macOS + iCloud Keychain enabled; use `--no-icloud-sync` for device-local bundles. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
+**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents accounts add`) require macOS. Default iCloud sync for bundles requires macOS + iCloud Keychain enabled; use `--no-icloud-sync` for device-local bundles. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
 
 Interactive tmux-backed runs require tmux 3.2 or newer.
 

package/dist/bootstrap.js

@@ -211,7 +211,7 @@ Install, configure, run, and dispatch AI coding agents from one place.
 Works with Claude, Codex, Antigravity, Cursor, OpenCode, OpenClaw, and Droid.
 
 Quick start:
-  agents setup                    First-time setup (interactive)
+  agents setup                    First-time setup (interactive); setup beta enables preview features
   agents view                     See what's installed
   agents run <agent> ["prompt"]   Run an agent (interactive without prompt, headless with)
   agents sessions                 Browse past sessions across all agents
@@ -256,15 +256,20 @@ Run and dispatch:
   pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
   artifacts                       Publish what an agent made (plans, reports, visuals) to a shareable link
 
-Observe (read the fleet — no store merge; aliases point at the real readers):
-  feed / inbox                    Needs-you inbox (open blocks waiting on you)
+Observe (read the fleet — no store merge):
+  feed                            Needs-you inbox (open blocks waiting on you); agent posts = feed --filter updates
   sessions --active               Live agents (who is running right now)
   events                          Unified ops + activity event trail
-  audit                           Tamper-evident run-dispatch log (not events)
-  status                          Sync/drift only (not the live fleet snapshot)
+  events audit                    Dispatched-run outcomes (alias of events --include runs)
+  sync status                     Sync/drift only (not the live fleet snapshot)
   devices snapshot                One-process inventory + active sessions poll
 
-Credentials:
+Identity (Prix account — shared with paid tiers):
+  auth login                      Sign in via the device-code flow
+  auth whoami                     Show the signed-in Prix user
+  auth space                      Create and manage a space (invite collaborators)
+
+Credentials (harness keys, not your Prix user):
   harness                         Custom (host CLI + model + auth) harnesses; replaces former profiles command
   secrets                         Keychain-backed env bundles; synced vault: secrets vault unlock|lock
   accounts                        Provider credentials + native OAuth logout
@@ -281,9 +286,6 @@ Config sync:
   repo init --path <dir>          Scaffold your own editable repo from a template
   repo add <path|gh:user/repo>    Merge an extra repo after the system repo
 
-Beta features:
-  beta                            Enable preview features (factory and more)
-
 Automation tips:
   Pass explicit names/IDs         Avoid pickers: agents sessions <id> --markdown
   Use --yes for defaults          Auto-accept sync/default prompts on add/use/pull
@@ -726,10 +728,13 @@ function registerHqTombstoneCommand(p) {
 }
 /**
  * Hidden `agents _internal <sub>` namespace for machine-to-machine calls that
- * are not user-facing. The first subcommand is `friction`, used by shell guard
- * hooks (git-guard, rm-guard, …) to self-report a block into the event log
- * before they exit 2 — they run before any `agents` process exists, so they
- * cannot emit in-process.
+ * are not user-facing. Subcommands:
+ *   - `friction` — shell guard hooks (git-guard, rm-guard, …) self-report a
+ *     block into the event log before they exit 2; they run before any
+ *     `agents` process exists, so they cannot emit in-process.
+ *   - `mergeable-prs` — the `pr-merge-on-green` built-in poll. Prints
+ *     `owner/repo#n` for this user's CI-green, non-author-approved open PRs
+ *     (cwd-independent `--repo`). Empty stdout is a silent observation.
  */
 function registerInternalCommand(p) {
     const internal = p.command('_internal', { hidden: true });
@@ -749,6 +754,21 @@ function registerInternalCommand(p) {
         });
         process.exit(0);
     });
+    internal
+        .command('mergeable-prs')
+        .description('Print owner/repo#n for CI-green, non-author-approved open PRs (pr-merge-on-green poll)')
+        .action(async () => {
+        try {
+            const { listMergeableRefs } = await import('./lib/github/pr-mergeable.js');
+            const refs = await listMergeableRefs();
+            if (refs)
+                process.stdout.write(`${refs}\n`);
+        }
+        catch {
+            // Empty observation — never write stderr (command.ts would treat it
+            // as the poll result and fire `mode: every` on the error text).
+        }
+    });
 }
 /** Runtime action for the shared `agents upgrade [version]` command definition. */
 async function runUpgrade(version, options) {

package/dist/cli/command-registry.d.ts

@@ -56,21 +56,16 @@ export declare const loadPrune: ModuleLoader;
 export declare const loadTrash: ModuleLoader;
 export declare const loadRestore: ModuleLoader;
 export declare const loadDoctor: ModuleLoader;
-export declare const loadApply: ModuleLoader;
-export declare const loadStatus: ModuleLoader;
 export declare const loadRoute: ModuleLoader;
 export declare const loadHarness: ModuleLoader;
 export declare const loadSecrets: ModuleLoader;
 export declare const loadMenubar: ModuleLoader;
-export declare const loadBeta: ModuleLoader;
 export declare const loadSync: ModuleLoader;
 export declare const loadRefreshRules: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
 export declare const loadUsage: ModuleLoader;
 export declare const loadInsights: ModuleLoader;
 export declare const loadPerf: ModuleLoader;
-export declare const loadTrends: ModuleLoader;
-export declare const loadAlias: ModuleLoader;
 export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
 export declare const loadWatchdog: ModuleLoader;
@@ -85,15 +80,12 @@ export declare const loadUninstall: ModuleLoader;
 export declare const loadUpgrade: ModuleLoader;
 export declare const loadSessions: ModuleLoader;
 export declare const loadTeams: ModuleLoader;
-export declare const loadTickets: ModuleLoader;
 export declare const loadCloud: ModuleLoader;
 export declare const loadMessage: ModuleLoader;
 export declare const loadSend: ModuleLoader;
 export declare const loadFeed: ModuleLoader;
 export declare const loadMailboxes: ModuleLoader;
-export declare const loadServe: ModuleLoader;
 export declare const loadArtifacts: ModuleLoader;
-export declare const loadAudit: ModuleLoader;
 export declare const loadWebhooks: ModuleLoader;
 export declare const loadHumans: ModuleLoader;
 export declare const loadAccounts: ModuleLoader;

package/dist/cli/command-registry.js

@@ -58,22 +58,16 @@ export const loadPrune = async () => (await import('../commands/prune.js')).regi
 export const loadTrash = async () => (await import('../commands/trash.js')).registerTrashCommands;
 export const loadRestore = async () => (await import('../commands/trash.js')).registerRestoreCommand;
 export const loadDoctor = async () => (await import('../commands/doctor.js')).registerDoctorCommand;
-export const loadApply = async () => (await import('../commands/apply.js')).registerApplyCommand;
-export const loadStatus = async () => (await import('../commands/status.js')).registerStatusCommand;
 export const loadRoute = async () => (await import('../commands/route.js')).registerRouteCommands;
 export const loadHarness = async () => (await import('../commands/harness.js')).registerHarnessCommands;
 export const loadSecrets = async () => (await import('../commands/secrets.js')).registerSecretsCommands;
 export const loadMenubar = async () => (await import('../commands/menubar.js')).registerMenubarCommands;
-export const loadBeta = async () => (await import('../commands/beta.js')).registerBetaCommands;
 export const loadSync = async () => (await import('../commands/sync.js')).registerSyncCommand;
 export const loadRefreshRules = async () => (await import('../commands/refresh-rules.js')).registerRefreshRulesCommand;
 export const loadFactory = async () => (await import('../commands/factory.js')).registerFactoryCommands;
 export const loadUsage = async () => (await import('../commands/usage.js')).registerUsageCommand;
 export const loadInsights = async () => (await import('../commands/insights.js')).registerInsightsCommand;
 export const loadPerf = async () => (await import('../commands/perf.js')).registerPerfCommand;
-// Thin deprecated alias of `agents insights mix` — no second mix implementation.
-export const loadTrends = async () => (await import('../commands/trends.js')).registerTrendsCommand;
-export const loadAlias = async () => (await import('../commands/alias.js')).registerAliasCommand;
 export const loadPty = async () => (await import('../commands/pty.js')).registerPtyCommands;
 export const loadTmux = async () => (await import('../commands/tmux.js')).registerTmuxCommands;
 export const loadWatchdog = async () => (await import('../commands/watchdog.js')).registerWatchdogCommand;
@@ -88,17 +82,13 @@ export const loadUninstall = async () => (await import('../commands/uninstall.js
 export const loadUpgrade = async () => (await import('../commands/upgrade.js')).registerUpgradeCommand;
 export const loadSessions = async () => (await import('../commands/sessions.js')).registerSessionsCommands;
 export const loadTeams = async () => (await import('../commands/teams.js')).registerTeamsCommands;
-export const loadTickets = async () => (await import('../commands/tickets.js')).registerTicketsCommand;
 export const loadCloud = async () => (await import('../commands/cloud.js')).registerCloudCommands;
 export const loadMessage = async () => (await import('../commands/message.js')).registerMessageCommand;
 export const loadSend = async () => (await import('../commands/send.js')).registerSendCommand;
 export const loadFeed = async () => (await import('../commands/feed.js')).registerFeedCommand;
 export const loadMailboxes = async () => (await import('../commands/mailboxes.js')).registerMailboxesCommand;
-export const loadServe = async () => (await import('../commands/serve.js')).registerServeCommand;
-// Registers the `artifacts` group (with `share` + `setup` under it) AND the
-// top-level `unshare` alias — see commands/artifacts.ts.
+// Registers the `artifacts` group (`share` + `setup` + nested `unshare`).
 export const loadArtifacts = async () => (await import('../commands/artifacts.js')).registerArtifactsCommands;
-export const loadAudit = async () => (await import('../commands/audit.js')).registerAuditCommands;
 export const loadWebhooks = async () => (await import('../commands/webhook.js')).registerWebhooksCommand;
 export const loadHumans = async () => (await import('../commands/humans.js')).registerHumansCommands;
 export const loadAccounts = async () => (await import('../commands/accounts.js')).registerAccountsCommand;
@@ -119,7 +109,6 @@ export const LAZY_COMMAND_NAMES = new Set([
     'teams',
     'cloud',
     'message',
-    'serve',
 ]);
 /**
  * User-typed top-level command name -> ordered list of module loaders to run.
@@ -178,22 +167,17 @@ export const COMMAND_LOADERS = {
     trash: [loadTrash],
     restore: [loadRestore],
     doctor: [loadDoctor],
-    apply: [loadApply],
-    status: [loadStatus],
     route: [loadRoute],
     harness: [loadHarness],
     harnesses: [loadHarness],
     secrets: [loadSecrets],
     menubar: [loadMenubar],
-    beta: [loadBeta],
     sync: [loadSync],
     'refresh-rules': [loadRefreshRules],
     factory: [loadFactory],
     usage: [loadUsage],
     insights: [loadInsights],
     perf: [loadPerf],
-    trends: [loadTrends],
-    alias: [loadAlias],
     pty: [loadPty],
     tmux: [loadTmux],
     watchdog: [loadWatchdog],
@@ -216,22 +200,14 @@ export const COMMAND_LOADERS = {
     upgrade: [loadUpgrade],
     sessions: [loadSessions],
     teams: [loadTeams],
-    tickets: [loadTickets],
     cloud: [loadCloud],
     message: [loadMessage],
     send: [loadSend],
     notify: [loadSend],
     feed: [loadFeed],
-    // Observe-umbrella alias of feed (the `timeline` alias was removed in RUSH-2692).
-    inbox: [loadFeed],
     mailboxes: [loadMailboxes],
     mailbox: [loadMailboxes],
-    serve: [loadServe],
     artifacts: [loadArtifacts],
-    // `unshare` is a top-level convenience alias of `artifacts share delete` (see
-    // commands/share.ts) — same module, registered as its own program.command().
-    unshare: [loadArtifacts],
-    audit: [loadAudit],
     webhooks: [loadWebhooks],
     humans: [loadHumans],
     daemon: [loadDaemon],

package/dist/commands/alias.d.ts

@@ -1,11 +1,14 @@
 /**
- * Alias command -- create top-level shim binaries that expand to `agents <subcommand>`.
+ * `agents setup alias` -- create top-level shim binaries that expand to
+ * `agents <subcommand>`. Nested under setup because the user is configuring
+ * this machine's PATH shortcuts, not operating a separate noun (RUSH-2965).
  *
- * Generates executable scripts in ~/.agents/shims/ (already on PATH from the
- * standard agents-cli install). Running `teams` becomes equivalent to
+ * Generates executable scripts in ~/.agents/.cache/shims/ (already on PATH from
+ * the standard agents-cli install). Running `teams` becomes equivalent to
  * `agents teams`. Aliases are tracked in ~/.agents/aliases.json so we can
  * list, regenerate, or remove them without scanning the shims directory
  * (which also holds agent CLI shims like claude/codex/gemini).
  */
 import type { Command } from 'commander';
-export declare function registerAliasCommand(program: Command): void;
+/** Register `agents setup alias` under the parent `setup` command. */
+export declare function registerAliasCommand(setupCmd: Command): void;

package/dist/commands/alias.js

@@ -4,7 +4,10 @@ import * as path from 'path';
 import { getUserAgentsDir } from '../lib/state.js';
 import { getShimsDir } from '../lib/installations/shims.js';
 import { ALL_AGENT_IDS, AGENTS } from '../lib/agents.js';
-const ALIASES_FILE = path.join(getUserAgentsDir(), 'aliases.json');
+import { setHelpSections } from '../lib/help.js';
+function aliasesFile() {
+    return path.join(getUserAgentsDir(), 'aliases.json');
+}
 /** Names that would clobber an agent CLI shim or the `agents` binary itself. */
 function reservedNames() {
     const reserved = new Set(['agents']);
@@ -13,10 +16,11 @@ function reservedNames() {
     return reserved;
 }
 function readAliases() {
-    if (!fs.existsSync(ALIASES_FILE))
+    const file = aliasesFile();
+    if (!fs.existsSync(file))
         return {};
     try {
-        const parsed = JSON.parse(fs.readFileSync(ALIASES_FILE, 'utf-8'));
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
         return parsed && typeof parsed === 'object' ? parsed : {};
     }
     catch {
@@ -24,8 +28,9 @@ function readAliases() {
     }
 }
 function writeAliases(map) {
-    fs.mkdirSync(path.dirname(ALIASES_FILE), { recursive: true });
-    fs.writeFileSync(ALIASES_FILE, JSON.stringify(map, null, 2) + '\n', 'utf-8');
+    const file = aliasesFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(map, null, 2) + '\n', 'utf-8');
 }
 function shimPath(name) {
     return path.join(getShimsDir(), name);
@@ -46,10 +51,30 @@ function isAliasShim(filePath) {
         return false;
     }
 }
-export function registerAliasCommand(program) {
-    const cmd = program
+/** Register `agents setup alias` under the parent `setup` command. */
+export function registerAliasCommand(setupCmd) {
+    const cmd = setupCmd
         .command('alias')
         .description('Create shorthand binaries that expand to `agents <subcommand>`');
+    setHelpSections(cmd, {
+        examples: `
+      # Make \`teams\` run \`agents teams\`
+      agents setup alias add teams
+
+      # Shorthand for a longer expansion
+      agents setup alias add sess sessions preview
+
+      agents setup alias list
+      agents setup alias remove teams
+    `,
+        notes: `
+      Writes an executable shim into ~/.agents/.cache/shims/ (already on PATH after
+      \`agents setup\`) and records it in ~/.agents/aliases.json.
+
+      Names that collide with the agents binary or an agent CLI (claude, codex,
+      grok, …) are refused. Top-level \`agents alias\` is gone — use this group.
+    `,
+    });
     cmd
         .command('add <name> [expansion...]')
         .description('Create an alias shim. If expansion is omitted, defaults to <name>.')
@@ -106,7 +131,7 @@ export function registerAliasCommand(program) {
         const map = readAliases();
         const entries = Object.entries(map);
         if (entries.length === 0) {
-            console.log(chalk.gray('No aliases. Try: agents alias add teams'));
+            console.log(chalk.gray('No aliases. Try: agents setup alias add teams'));
             return;
         }
         const width = entries.reduce((max, [n]) => Math.max(max, n.length), 0);