@phnx-labs/agents-cli 1.22.59 → 1.22.61

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 1.22.61
+
+- **`agents harness` wizard: model catalog, connection test, and edit matrix (PHNX-2218/2220/2221/2222).** The create/edit wizard now picks the model from the host's own catalog (`getModelCatalog`) with a free-text escape hatch, gates the endpoint step to hosts that actually carry one, and runs a real pre-save connection test — `agents run <name> "say alive in one word" --headless --timeout 60s` classified into pass / auth / endpoint / model — behind a confirm with `--test`/`--no-test`, offering keep / edit / delete on failure rather than saving a broken harness silently. A resolver-sourced `harnessEditable` matrix disables (with a reason) any param the host's API format can't carry. Source: `apps/cli/src/commands/harness.ts`, `apps/cli/src/commands/harness-wizard.ts`, `apps/cli/src/commands/harness-hooks.ts`, `apps/cli/src/lib/harness-connection-test.ts`.
+
+- **Cap per-machine Linear API spend with a shared per-key request budget (PHNX-2310).** With ~13 concurrent drain agents on one Linear API key on a single box, nothing stopped them collectively exhausting Linear's 2,500 requests/hour limit and throttling ticket-status reads for every agent on that box. The `agents projects` card fetch now reserves against a proactive request budget keyed by the API key before each request; when the hourly pool is spent it serves the last cached snapshot (marked stale) instead of forcing a 429. The pool is lock-free on-disk state under the machine-local cache (one stamp file per request, a sliding one-hour window), so the many separate agent processes on a box coordinate without a shared mutable document to race on. Scope is per machine: the state is not fleet-synced, so two boxes sharing one key each budget independently — cross-device aggregation is a known limitation, not yet covered. This complements the existing read cache and reactive 429 backoff. Source: `cli/src/lib/linear-rate-limit.ts`, `cli/src/lib/linear-project-counts.ts`.
+
+- **`agents browser` drives your RUNNING Arc instead of spawning a second one (PHNX-2399).** Arc is single-instance: relaunching the Arc binary with a fresh `--user-data-dir` produced a stray window and no CDP endpoint rather than a debuggable instance. An Arc profile now attaches to the Arc you already have open (point its endpoint at the port you launched Arc's remote debugging on), and when that Arc exposes no CDP endpoint on the profile's port it **fails loud** with the one relaunch that fixes it (`open -a Arc --args --remote-debugging-port=<port>`) — it never silently launches a duplicate. Bind the profile to the tab/Space you want to drive with `--target-filter` (accepted for `--browser arc`, not just `--electron`): it is consulted when Arc picks which existing tab to drive, so `navigate` reuses your bound Space instead of an unrelated tab, and refuses rather than borrowing one when nothing matches. The documented first-use flow — `agents browser navigate --profile arc --url …` on a fresh profile — now attaches to an open tab instead of erroring. Opening a brand-new tab remains the one CDP-only op Arc can't survive (`Target.createTarget` crashes it), so tab-creating verbs fail clearly and steer you to reuse an existing tab or a Chromium-family browser. Source: `cli/src/lib/browser/drivers/local.ts`, `cli/src/lib/browser/service.ts`, `cli/src/commands/browser.ts`, `cli/src/lib/open-url.ts`.
+
+- **`agents sessions watch --json` rows now carry a canonical `phase` (PHNX-2484).** Each live/recoverable session row projects a coarse lifecycle bucket — `running | waiting | failed | done | idle` — derived once at the source from the finalized status (`derivePhase` in `cli/src/lib/session/active.ts`), so thin-client consumers (the AGI EXT Fleet panel) read `phase` off the row instead of re-deriving it from the status word. It also fixes a drift a status-only re-derivation had: `orphaned` and `crashed` now bucket to `failed` (dangling/dead — needs attention) rather than falling through to `idle` and hiding a dead agent.
+
+- **`balanced`/`available` routing never auto-picks an account from entirely stale usage (PHNX-2526).** When every signed-in account's usage snapshot is older than the 5-minute decision horizon and none can be verified, the initial route no longer guesses on a stale number (the yosemite-s1 incident, where a 26h–2.7d-old snapshot read 48% while the account was at its weekly cap). An interactive run now shows the account picker so a human chooses with the stale numbers in view; an unattended run (`--headless`/`--json`/no TTY, or a routine) fails loud with `NO_VERIFIED_USAGE`. The stale candidates are preserved only for bounded post-rejection failover, never the first pick. A pool that is merely *blind* (no snapshot at all — a worker box whose usage endpoint 403s) is unaffected and still draws a pick. Source: `apps/cli/src/lib/accounting/rotate.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/daemon/runner.ts`.
+
+- **Raise SSH `ControlPersist` to 10 minutes so repeated fleet touches reuse warm connections (PHNX-2582).** The OpenSSH multiplex master now lives for 10 minutes after its last use (`SSH_CONTROL_PERSIST_SECONDS`) instead of 60 seconds. The master only helps a repeated touch of the same host that arrives while it is still alive, and the ad-hoc `--device` / fan-out calls that touch a box repeatedly (`sessions --active`, `fleet ping`, `doctor`, `teams`, a `--device` command run a few times) arrive in bursts spread over minutes — so at the old 60 s window any two more than a minute apart both paid a fresh TCP+auth handshake (~100-300 ms direct, up to ~500 ms relayed). 10 minutes keeps a multi-minute burst warm (~3-5 ms per reuse) while staying bounded so an idle master to a slept host is reaped rather than lingering. Source: `cli/src/lib/ssh-exec.ts`.
+
+- **A running agent whose owning IDE window died is now surfaced as `orphaned` (PHNX-3183).** `foldHostLink` promoted only `idle`/`input_required` sessions to `orphaned`; a still-`running` agent was never flagged, so a genuinely-stranded remote agent — alive in tmux after its owning window crashed, rebooted, or dropped its SSH link — stayed hidden as a healthy "running" row. It now promotes a `running` session to `orphaned` when, and only when, its owning window was LOST: the window's registry slice went stale past `HOST_HEARTBEAT_STALE_MS` after having republished it (`hostWindowLost`). Client ABSENCE alone still never flags a running agent — a tmux attached-client count of zero is the normal steady state for a detached `agents run --device` pane (RUSH-3125), so promoting on it would relabel every unattended remote agent as orphaned (the over-report reverted in `6d973b823`). This narrows spec `SES-18a` to the window-loss case rather than the blanket precondition-drop that was reverted. Source: `cli/src/lib/session/host-link.ts`, `cli/src/lib/session/active.ts`, `cli/docs/specifications.md`, `cli/docs/sessions.md`.
+
+- **Teammates can no longer silently self-merge their own PRs (PHNX-3236).** A
+  write-capable `agents teams` teammate authenticates as the repo owner, so it
+  could merge its own PR straight past the required non-author-review gate (the
+  RUSH-2988 wave-1 dispatch self-merged PRs #1817/#1820 with zero reviews). Team
+  dispatch now appends a self-merge boundary (`TEAMMATE_PR_POLICY`, via one
+  `withTeammatePrPolicy` helper) to every write-capable (non-plan) teammate's
+  prompt, fresh or resumed, at **all three** dispatch surfaces — local, `--device`
+  remote (both via `buildRunArgv`), and `--cloud` (`cloudDispatchOptions`) — so
+  none can drift: open the PR and hand it off; do not merge your own PR without a
+  posted non-author verdict. The hard enforcement is `merge-guard.sh`, the PreToolUse
+  hook a teammate inherits, whose verdict check now excludes the PR author's own
+  reviews/comments (`phnx-labs/.agents` #395) — but it only reaches hook-capable
+  local/remote teammates; cloud teammates (provider sandbox, no inherited hook) and
+  hook-incapable harnesses (Warp) get the prompt as their only layer, a residual
+  documented in `cli/AGENTS.md` §6 that server-side branch protection closes. Source:
+  `cli/src/lib/teams/agents.ts`, `cli/src/commands/teams.ts`.
+
+- **Blanket `Bash` now auto-approves shell on Grok, so fleet agents stop punting on `ssh`/`scp`/`agents ssh` (PHNX-3294).** A blanket `Bash` grant was translated to a Grok rule with `pattern:"*"`, but Grok's `*` is a SINGLE-level wildcard, so it never auto-approved a multi-token command like `ssh host cmd` or `scp a b` — a Grok agent on a box without `permission_mode=always-approve` prompted and handed the command back to the user. Blanket `Bash` (and its `Bash(*)`/`Bash(**)` forms, allow and deny) now emit Grok's documented "bare prefix matches all invocations" rule — a bash rule with no `pattern` key — the true allow-all-shell form, matching how Kimi, Droid, and Claude already express it. This reads back as `Bash(*)`, so the round-trip is unchanged. Source: `cli/src/lib/permissions.ts`.
+
+- **`agents traces sync`: per-session roster in `index.json` (PHNX-3483).** The index shard now carries `sessions` — one flat scalar row per AGENT session (`id`, `title`, `harness`, `model`, `repo`, `mode`, `projectType`, `startedAt`, `durationMs`, `toolCount`, `errorCount`, `needsAttention`, best-effort `costUsd`) — so the Rush console can filter the session set and re-aggregate its headline metrics client-side instead of being stuck with the pre-rolled scalars. `durationMs` is the ACTIVE duration (`sessionActiveMs`, the value behind `stats.medianMs`; 0 when unmeasured) and `mode` encodes the AGENT-vs-INTERACTIVE segmentation (`headless`/`interactive`) so a mode-split median over the measured rows reproduces `stats.agentMedianMs`/`stats.interactiveMedianMs` (the segmented stats skip null-duration rows, which the roster still carries at `durationMs: 0`). Utility rows are excluded, so the roster length equals `stats.sessionsImported`. Source: `apps/cli/src/lib/traces/sync.ts`.
+
+- **`agents insights perf run` now actually records `agent.run` timings (PHNX-3497).** The `startup` sub-phase surface added in PHNX-3468 had no data on a foreground run: `recordPerfTiming` wrote the perf-spool row behind a fire-and-forget `import().then(...)`, and the `agents run` process exited before that deferred write landed — so every foreground run's `agent.run` sample was silently lost. The spool append is now synchronous (`recordSample` is an `appendFileSync` that never opens SQLite), so `agent.run` rows and their `startup` p50/p90 phase line persist and show up. Source: `cli/src/lib/feed/events.ts`.
+
+- **`gh pr checks` now escapes the shared GraphQL rate limit automatically — no new command to learn (PHNX-3501).** The whole fleet shares one GitHub token, and the merge loop's `gh pr checks/view/list` are all GraphQL-backed, so the fleet collectively drains GitHub's 5000-point/hr GraphQL budget while REST core sits ~95% idle — after which every agent's `gh pr checks --watch` dies with `GraphQL: API rate limit already exceeded`. A generated PATH shim (like the existing `browser` shim) now transparently intercepts the agent's trained `gh pr checks` and routes it to a hidden `agents __gh` verb backed by REST (`commits/{sha}/check-runs` + `/status`, anchored to the PR's live head SHA); every other `gh` verb execs the real binary byte-for-byte. `--watch` owns the REST poll loop (head-SHA-anchored, so a superseded run's red can never be reported — closes PHNX-3042); a one-shot runs real gh first and falls back to REST only on the exact rate-limit stderr. The shim self-heals — a leftover shim execs real gh whenever agents-cli is gone or uninstalled, so it can never break `gh`. Installed on `agents sync` (POSIX in v1). Source: `cli/src/lib/github/rest.ts`, `cli/src/lib/github/gh-overload.ts`, `cli/src/lib/installations/shims.ts`.
+
+- **`agents doctor` now detects content drift for mcp, permissions, subagents, workflows, and memory (PHNX-3504).** The resource-diff engine compared these kinds by NAME only (or, for workflows/memory, not at all), so an edited MCP command/args/env, a swapped permission rule, an edited subagent prompt, a changed workflow, or an edited knowledge-memory fact all read as a false `ok` under an unchanged name. Every kind `syncResourcesToVersion` writes is now content-aware: mcp structurally compares the home server def against the resolved source; subagents re-render the source through the registry transform and byte-compare; workflows compare layout-aware per harness (copied tree or transformed file); memory (`~/.agents/memory/*.md` facts, tracked via the `.agents-cli-memory.json` manifest) byte-compares each fact; permissions compare per-rule in the harness's native vocabulary for the representable harnesses (claude/opencode/cursor/droid/openclaw) and stay presence-only with an honest `detail: 'format cannot verify content'` for the lossy TOML/flag harnesses rather than faking `ok`. `workflows` and `memory` are now real `--kind` filters; `promptcuts` (not version-scoped) is dropped. A completeness test binds `DOCTOR_ALL_KINDS` to the writer set so a future synced kind cannot silently become a blind spot, and `agents doctor --fix` reaches the newly-covered kinds. Source: `cli/src/lib/doctor-diff.ts`, `cli/src/lib/resource-content-diff.ts`, `cli/src/lib/subagents-registry.ts`, `cli/src/lib/mcp.ts`, `cli/src/lib/permissions.ts`, `cli/src/lib/workflows.ts`, `cli/src/lib/heal.ts`, `cli/src/lib/devices/doctor-findings.ts`.
+
+- **A balanced/available route now records WHY it picked an account, so a bad pick is debuggable from `agents events` alone (PHNX-3564).** `rotation.resolved` / `rotation.unresolved` used to carry only `{ version, healthy: <n>, excluded: <n> }` — a device-local version number (meaningless across the fleet) and two counts. When a run landed on a weekly-maxed, logged-out, or absent account (PHNX-3505 / PHNX-3479), the event could not say which org, how fresh its usage was, or why it won the draw, so every occurrence was debugged blind. `buildRotationDecisionEvent` (`cli/src/lib/accounting/rotate.ts`) now emits a full decision record: `picked { usageKey (per-org quota key), email, tier }`; a `pickReason` read straight from the router's own result (`verified-weighted` for the healthy path, `unverified-<tier>-draw` for a blind/stale fallback, `refused-no-verified` for the fail-closed exit); a per-candidate map `{ usageKey, accountKey, providerAccount, tier (verified/stale/blind), source, capturedAt, ageMs, windows, eligible, excludedReason, credentialVerdict }` keyed by pool index (not version or usageKey, which a RUSH-3182 provider-account pool shares across rows); and a `freshness` tally `{ verified, stale, blind }` over the healthy pool. `usageKey` is the org uuid — the only identity that joins the same account across devices — and `ageMs` is measured by the routing host's clock, so a `last_seen` snapshot showing `tier: verified` beside a large `ageMs` is the cross-host clock-skew failure made visible. Two details are dictated by the event sink's generic sanitizer (`feed/events.ts`): candidates are a keyed object (not an array) because arrays are truncated to 10 entries, and the verdict field is named `credentialVerdict` (not `authVerdict`) because any key matching `/auth/i` is redacted — an end-to-end test drives a real `emit()` into a redirected sink and asserts the persisted line to lock both in. This event now also carries account **emails** to the local-only event log (`~/.agents/.history/events`, `0600`) — a new local PII surface for this event type. Pure observability: no routing-logic change, and every field is read from data the router already computed; the build+emit is wrapped so an observability bug can never abort a launch. Live-verified on zion (8 claude accounts: 1 verified, 7 stale — every synced row already past the 5-min decision window on arrival). Source: `cli/src/lib/accounting/rotate.ts`, `cli/src/lib/accounting/rotate.test.ts`.
+
+- **`agents reminders` + Claude statusline reminders.** Personal operating reminders kept in `~/.agents/reminders/reminders.yaml` (each a `short`/`full` pair) now surface succinctly in the Claude statusline — one per session, chosen deterministically from the session id so concurrent agents each show a different one and it stays stable within a session. Presence of the file with at least one entry is the opt-in; a malformed file is swallowed by the statusline (a broken prompt is worse than a missing line) but surfaced by `agents reminders`. The file syncs across the fleet via `agents repo push/pull`. Source: `cli/src/lib/reminders.ts`, `cli/src/commands/reminders.ts`, `cli/src/lib/claude-statusline.ts`.
+
+## 1.22.60
+
+- **Richer schema-2 trace shards (PHNX-3442).** The per-session trace shard the evals console reads is now a typed `ToolExecution` discriminated union instead of a thin `SessionStep` with one `output` blob. Bash steps carry per-action argv, effective program, build/test/git/network categories, and a conservative `danger`/`DESTRUCTIVE` classification (recursive-force-delete, `git reset --hard`, `git clean -f`, force push incl. the `+refspec` form, `git checkout -- .`, `DROP TABLE`/`TRUNCATE`/`DELETE`-without-`WHERE`, `kill -9`, `dd of=`, `mkfs`, redirects over block devices); edit/write steps carry file mutations, diff hunks, and a cross-step revert ledger (only an exact hash round-trip stamps `revertedByStep`, never a partial edit); read/grep steps carry counts; permission/hook events are first-class steps. It emits by default with no flag: the prix/web console already decodes both schema 1 and schema 2 and is the only shard consumer, so the change is backward-compatible by construction — a fleet-wide producer must not depend on an operator setting an env var. The bash unwrap/tokenize/classify, trajectory step-pairing (`pairSteps`), and shard meta helpers are reused, not reimplemented. `category`/`risk`/`categoryMetrics` are deliberately omitted — the consumer backfills neutral defaults. Source: `cli/src/lib/traces/schema2.ts`, `schema2-build.ts`, `schema2-danger.ts`, `cli/src/lib/traces/sync.ts`, `cli/src/lib/session/trajectory.ts`.
+
+- **Detect stranded uncommitted work in `agents teams status` (PHNX-2951).** A teammate that exits `COMPLETED` with no PR and uncommitted changes in its local worktree now reports `STRANDED` instead of `done`, and the status line names the worktree path so the work can be rescued before cleanup. The stranded count is computed over the full team even when `--filter` narrows the displayed agents, so `agents teams status <team> --filter running` still surfaces stranded completed teammates. Team rollups and `teams list --status` classify these teams as `stranded`, not `done`. Source: `cli/src/lib/teams/delivery.ts`, `cli/src/lib/teams/api.ts`, `cli/src/commands/teams.ts`.
+
+- **Track agent-launch boot cost: persist + surface the `startup` phase (PHNX-3468).** `agent.run` already timed a `startup` phase (entering `spawnAgent` → child spawn) but only the total run duration reached the perf warehouse, so boot cost was untrackable across the fleet. The timer now persists its sub-phase marks into each `perf.timing` sample's `meta_json`, `aggregateSamples` folds them into a per-label `phases` break-out (p50/p90 over the samples that carried each phase), and `agents insights perf run` renders a `└ startup: p50 …  p90 …  (n=…)` sub-line under `agent.run`. This is the measurement the boot-perf work is graded against. Source: `cli/src/lib/feed/events.ts`, `cli/src/lib/perf/db.ts`, `cli/src/lib/perf/types.ts`, `cli/src/commands/perf.ts`.
+
+- **`agents sessions preview <id>` now pulls the transcript digest from the
+  owning device for host-dispatched sessions (PHNX-3481).** A host dispatch
+  leaves a synthetic local index row with `machine = <peer>` and an empty
+  `filePath`, but that row does not carry the live fan-out's `_remote` marker.
+  Full-UUID preview resolved the local row and then treated it as a local live
+  session, rendering "full transcript not indexed here" without making any SSH
+  hop. Transcript reads now follow one file-aware predicate: an explicit remote
+  row still reads on its peer; a row naming another machine also reads there
+  when no transcript exists on this disk; and a synced mirror with a real local
+  file still renders locally. The direct preview, `sessions <id>`, picker view,
+  and picker/browser digest pane all share that rule. Live-registry metadata now
+  also stamps `_remote` when its execution machine differs from this box, and an
+  unreachable owner remains a loud error instead of a local placeholder.
+  Source: `cli/src/commands/sessions-picker.ts`, `cli/src/commands/sessions.ts`,
+  `cli/src/lib/session/live-metadata.ts`.
+
 ## 1.22.59
 
 - **`agents devices disable/prefer` now actually change `--device auto` placement (PHNX-2092).**

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

@@ -91,6 +91,7 @@ export declare const loadAccounts: ModuleLoader;
 export declare const loadDaemon: ModuleLoader;
 export declare const loadAuth: ModuleLoader;
 export declare const loadTraces: ModuleLoader;
+export declare const loadReminders: ModuleLoader;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help

package/dist/cli/command-registry.js

@@ -94,6 +94,7 @@ export const loadAccounts = async () => (await import('../commands/accounts.js')
 export const loadDaemon = async () => (await import('../commands/daemon.js')).registerDaemonCommand;
 export const loadAuth = async () => (await import('../commands/auth.js')).registerAuthCommand;
 export const loadTraces = async () => (await import('../commands/traces.js')).registerTracesCommands;
+export const loadReminders = async () => (await import('../commands/reminders.js')).registerRemindersCommand;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -128,6 +129,7 @@ export const COMMAND_LOADERS = {
     view: [loadView],
     inspect: [loadInspect],
     feedback: [loadFeedback],
+    reminders: [loadReminders],
     commands: [loadCommands],
     hooks: [loadHooks],
     skills: [loadSkills],

package/dist/commands/browser.js

@@ -602,7 +602,7 @@ function registerProfilesCommands(browser) {
         .option('--position <X,Y>', 'Window position on screen, e.g. 80,80')
         .option('--binary <path>', 'Absolute path to the browser/app binary (required with --browser custom)')
         .option('--electron', 'Treat this profile as an Electron desktop app: never call Target.createTarget; bind to the visible window using --target-filter or the skip-invisible heuristic')
-        .option('--target-filter <expr>', 'Pick the visible CDP page target when the app exposes more than one. Format: url:<substring> or title:<substring>')
+        .option('--target-filter <expr>', 'Pick the existing CDP page target to drive (Electron apps, and Arc — which reuses an open tab / Space rather than creating one). Format: url:<substring> or title:<substring>')
         .action(async (name, opts) => {
         try {
             assertRegistrableProfileName(name);
@@ -629,8 +629,13 @@ function registerProfilesCommands(browser) {
                 console.error('--target-filter must be url:<substring> or title:<substring> (non-empty value, no leading whitespace)');
                 process.exit(1);
             }
-            if (!opts.electron) {
-                console.error('--target-filter requires --electron (the filter is only consulted on Electron profiles)');
+            // The filter picks WHICH existing page target to drive without ever
+            // calling Target.createTarget — the two profiles that do that are
+            // Electron apps and Arc (which crashes on tab creation, so it drives an
+            // existing tab / Space, PHNX-2399). Any other browser opens its own tab
+            // and never consults the filter, so requiring it there would be a lie.
+            if (!opts.electron && opts.browser !== 'arc') {
+                console.error('--target-filter requires --electron or --browser arc (the filter is only consulted on profiles that reuse an existing tab)');
                 process.exit(1);
             }
         }
@@ -704,7 +709,7 @@ function registerProfilesCommands(browser) {
         .option('--binary <path>', 'Absolute path to the browser/app binary')
         .option('--electron', 'Treat this profile as an Electron desktop app')
         .option('--no-electron', 'Stop treating it as an Electron app')
-        .option('--target-filter <expr>', "url:<substring> or title:<substring>; requires --electron (pass '' to clear)")
+        .option('--target-filter <expr>', "url:<substring> or title:<substring>; consulted on Electron and Arc profiles (pass '' to clear)")
         .option('--json', 'Output machine-readable JSON')
         .action(async (name, opts) => {
         // The browser type and the name are identity, not settings: both key the

package/dist/commands/doctor.js

@@ -1458,7 +1458,7 @@ export function registerDoctorCommand(program) {
         .option('--json', 'Output machine-readable JSON')
         .option('--diff', 'In target mode, include unified diffs for divergent files')
         .option('--fix', 'Heal gaps: install missing resources, repair invalid plugin manifests, refresh stale plugins, reconcile drift, and purge stale/legacy agents-cli installs (npx-cache, pre-1.22.30, unsafe helper installer) when a fixed peer exists')
-        .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
+        .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,workflows,memory)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
         .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
         .option('--release <agent>', 'Undo --adopt: restore the native launcher agents-cli previously adopted')

package/dist/commands/exec.js

@@ -1773,7 +1773,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
             process.exit(resumeExit);
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, implicitModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, readProfile, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError, signInRecoverableCandidates }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports, capableAgents }, { shareRuntimeEnv },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, implicitModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive, inferredInteractiveWithoutTty }, { ALL_AGENT_IDS, ACCOUNT_INSPECTION_AGENT_IDS, agentLabel, supportsAccountInspection }, { profileExists, readProfile, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle, assertRemoteBundleFlagsUnsupported }, { splitBundleRef, resolveHostSshTarget, remoteResolveEnv }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, rotationFailoverChain, shouldArmRotationFailover, RUN_STRATEGIES, collectHarnessCandidates, pickHarnessWeighted, classifyHarnessCandidates, formatHarnessPickBanner, formatNoHealthyHarnessError, formatNoHealthyAccountError, formatNoVerifiedUsageError, signInRecoverableCandidates }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias, ensureAgentRunnable }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents, pruneStaleWorkflowSubagents, ensureSubagentDispatchTool }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports, capableAgents }, { shareRuntimeEnv },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -2439,6 +2439,40 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                             process.exit(1);
                         }
                     }
+                    else if (resolved.noVerifiedUsage) {
+                        // Entirely stale usage (PHNX-2526): every eligible account carries
+                        // a stale-but-present usage number and none is verified, so the
+                        // route would be a guess. NEVER auto-pick it. Interactive: show the
+                        // account picker so a human chooses with the (stale) numbers in
+                        // view. Unattended: fail loud with NO_VERIFIED_USAGE. The stale
+                        // pool survives ONLY as `resolved.rotation.healthy` for bounded
+                        // post-rejection failover, never as the initial pick.
+                        const { noVerifiedUsageDecision, pickRunAccountCandidate } = await import('./run-account-picker.js');
+                        const decision = noVerifiedUsageDecision({
+                            tty: isInteractiveTerminal(),
+                            json: options.json === true,
+                            headless: options.headless === true,
+                        });
+                        if (decision === 'picker') {
+                            const selected = await pickRunAccountCandidate(agent);
+                            // A cancelled picker launches nothing — same contract as the
+                            // trailing-@ account picker and the sign-in launch above.
+                            if (!selected)
+                                return;
+                            version = selected.version;
+                            // Keep the rotation so mid-run failover can still cascade across
+                            // the other (stale) healthy accounts after a real rejection.
+                            rotationResult = resolved.rotation;
+                            if (!options.quiet) {
+                                const identity = selected.accountLabel || 'signed-in account';
+                                process.stderr.write(chalk.gray(`[agents] no fresh usage for any ${agent} account — you picked ${identity} · ${agent}@${selected.version}\n`));
+                            }
+                        }
+                        else {
+                            console.error(chalk.red(formatNoVerifiedUsageError(agent, strategy, resolved.rotation?.healthy ?? [])));
+                            process.exit(1);
+                        }
+                    }
                     else if (resolved.version) {
                         version = resolved.version;
                         rotationResult = resolved.rotation;

package/dist/commands/harness-hooks.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Production {@link WizardHooks} for the harness create/edit wizard.
+ *
+ * The engine ({@link ./harness-wizard.js}) is pure and hook-driven; this module
+ * supplies the three real extension points the sibling subtasks fill:
+ *   - `pickModel`      — a catalog pick from the host's own model list
+ *                        (`getModelCatalog`), with a free-text escape hatch and a
+ *                        free-text FALLBACK when the host exposes no catalog
+ *                        (RUSH-2220).
+ *   - `connectionTest` — a real pre-save smoke test through `agents run`
+ *                        (RUSH-2221), delegated to {@link runHarnessConnectionTest}.
+ *   - `editable`       — the resolver-sourced per-host editability matrix
+ *                        (RUSH-2222), {@link defaultEditable}.
+ *
+ * Kept out of the engine so the engine stays testable with a scripted IO and no
+ * catalog probe, keychain read, or subprocess.
+ */
+import type { AgentId } from '../lib/types.js';
+import { type ModelInfo } from '../lib/models.js';
+import { type WizardHooks, type WizardIO, type WizardChoice } from './harness-wizard.js';
+/**
+ * The installed version whose model catalog to read for a host. The wizard has
+ * no version in hand for a fresh create, so it reads the host's default (or its
+ * sole installed) version — the same version a bare `agents run <host>` uses.
+ * Null when the host has no installed version to probe (→ free-text model).
+ */
+export declare function catalogVersionFor(host: AgentId): string | null;
+/**
+ * Build the model `select` choices from a catalog. Pure, so the labelling +
+ * escape-hatch rows are unit-tested with no catalog probe. Every list ends with
+ * a "type a custom id" row so a model the catalog doesn't list is always
+ * reachable; in edit mode a "keep current" row leads.
+ */
+export declare function buildModelChoices(models: ModelInfo[], current?: string): WizardChoice<string>[];
+/**
+ * Prompt over an already-resolved catalog: a `select` of the models plus the
+ * keep-current / custom-id rows, mapping the sentinel choices back to a concrete
+ * model id. Split from the catalog probe so the KEEP / CUSTOM / pick branches are
+ * unit-tested with a scripted IO and no installed agent.
+ */
+export declare function chooseModelFromCatalog(io: WizardIO, models: ModelInfo[], current: string | undefined): Promise<string>;
+/**
+ * The catalog-backed model pick (RUSH-2220). Returns the chosen model id, or
+ * `null` to fall through to the engine's free-text prompt when the host exposes
+ * no probeable catalog — so a host we can't enumerate degrades to today's
+ * free-text behaviour rather than blocking.
+ */
+export declare function pickModel(io: WizardIO, host: AgentId | undefined, version: string | undefined, current: string | undefined): Promise<string | null>;
+/**
+ * Assemble the production hook set the harness commands drive the wizard with.
+ * The connection-test hook reads the assembled draft's `name` — the caller writes
+ * the profile to disk first, then invokes the test through the real `agents run`
+ * path against that name.
+ */
+export declare function harnessHooks(): WizardHooks;

package/dist/commands/harness-hooks.js

@@ -0,0 +1,104 @@
+/**
+ * Production {@link WizardHooks} for the harness create/edit wizard.
+ *
+ * The engine ({@link ./harness-wizard.js}) is pure and hook-driven; this module
+ * supplies the three real extension points the sibling subtasks fill:
+ *   - `pickModel`      — a catalog pick from the host's own model list
+ *                        (`getModelCatalog`), with a free-text escape hatch and a
+ *                        free-text FALLBACK when the host exposes no catalog
+ *                        (RUSH-2220).
+ *   - `connectionTest` — a real pre-save smoke test through `agents run`
+ *                        (RUSH-2221), delegated to {@link runHarnessConnectionTest}.
+ *   - `editable`       — the resolver-sourced per-host editability matrix
+ *                        (RUSH-2222), {@link defaultEditable}.
+ *
+ * Kept out of the engine so the engine stays testable with a scripted IO and no
+ * catalog probe, keychain read, or subprocess.
+ */
+import chalk from 'chalk';
+import { getModelCatalog } from '../lib/models.js';
+import { getGlobalDefault, listInstalledVersions } from '../lib/installations/versions.js';
+import { runHarnessConnectionTest } from '../lib/harness-connection-test.js';
+import { defaultEditable, } from './harness-wizard.js';
+/** Sentinel select values for the two non-catalog rows in the model pick. */
+const CUSTOM_MODEL = '__custom_model__';
+const KEEP_MODEL = '__keep_model__';
+/**
+ * The installed version whose model catalog to read for a host. The wizard has
+ * no version in hand for a fresh create, so it reads the host's default (or its
+ * sole installed) version — the same version a bare `agents run <host>` uses.
+ * Null when the host has no installed version to probe (→ free-text model).
+ */
+export function catalogVersionFor(host) {
+    return getGlobalDefault(host) || listInstalledVersions(host)[0] || null;
+}
+/**
+ * Build the model `select` choices from a catalog. Pure, so the labelling +
+ * escape-hatch rows are unit-tested with no catalog probe. Every list ends with
+ * a "type a custom id" row so a model the catalog doesn't list is always
+ * reachable; in edit mode a "keep current" row leads.
+ */
+export function buildModelChoices(models, current) {
+    const choices = [];
+    if (current)
+        choices.push({ name: `Keep current (${current})`, value: KEEP_MODEL });
+    for (const m of models) {
+        const tags = [];
+        if (m.alias)
+            tags.push(m.alias);
+        if (m.isDefault)
+            tags.push('default');
+        const tail = tags.length ? chalk.gray(`  (${tags.join(', ')})`) : '';
+        const label = m.displayName && m.displayName !== m.id ? `${m.id}${chalk.gray('  ' + m.displayName)}` : m.id;
+        choices.push({ name: `${label}${tail}`, value: m.id });
+    }
+    choices.push({ name: 'Type a custom model id…', value: CUSTOM_MODEL });
+    return choices;
+}
+/**
+ * Prompt over an already-resolved catalog: a `select` of the models plus the
+ * keep-current / custom-id rows, mapping the sentinel choices back to a concrete
+ * model id. Split from the catalog probe so the KEEP / CUSTOM / pick branches are
+ * unit-tested with a scripted IO and no installed agent.
+ */
+export async function chooseModelFromCatalog(io, models, current) {
+    const choice = await io.select({
+        message: 'Model',
+        choices: buildModelChoices(models, current),
+    });
+    if (choice === KEEP_MODEL)
+        return current ?? '';
+    if (choice === CUSTOM_MODEL)
+        return io.input({ message: 'Model id', default: current });
+    return choice;
+}
+/**
+ * The catalog-backed model pick (RUSH-2220). Returns the chosen model id, or
+ * `null` to fall through to the engine's free-text prompt when the host exposes
+ * no probeable catalog — so a host we can't enumerate degrades to today's
+ * free-text behaviour rather than blocking.
+ */
+export async function pickModel(io, host, version, current) {
+    if (!host)
+        return null;
+    const resolvedVersion = version || catalogVersionFor(host);
+    if (!resolvedVersion)
+        return null;
+    const catalog = getModelCatalog(host, resolvedVersion);
+    if (!catalog || catalog.models.length === 0)
+        return null;
+    return chooseModelFromCatalog(io, catalog.models, current);
+}
+/**
+ * Assemble the production hook set the harness commands drive the wizard with.
+ * The connection-test hook reads the assembled draft's `name` — the caller writes
+ * the profile to disk first, then invokes the test through the real `agents run`
+ * path against that name.
+ */
+export function harnessHooks() {
+    return {
+        pickModel,
+        connectionTest: (draft) => runHarnessConnectionTest(draft.name),
+        editable: defaultEditable,
+    };
+}

package/dist/commands/harness-wizard.d.ts

@@ -28,6 +28,8 @@
  */
 import type { AgentId } from '../lib/types.js';
 import { type Profile } from '../lib/profiles.js';
+import type { ConnectionTestResult } from '../lib/harness-connection-test.js';
+export type { ConnectionTestResult } from '../lib/harness-connection-test.js';
 /** Whether the wizard is creating a new harness or editing an existing one. */
 export type WizardMode = 'create' | 'edit';
 /** A single `select` choice. `disabled` greys the row (used by the edit matrix). */
@@ -129,23 +131,40 @@ export interface HarnessEditable {
     version: boolean;
     fallback: boolean;
 }
+/** One field's editability plus, when disabled, the one-line reason to surface. */
+export interface EditableField {
+    enabled: boolean;
+    /** Set only when `enabled` is false — the greyed field's stated reason. */
+    reason?: string;
+}
+/** Per-host editability with a reason attached to every disabled field. */
+export interface HarnessEditability {
+    model: EditableField;
+    baseUrl: EditableField;
+    auth: EditableField;
+    version: EditableField;
+    fallback: EditableField;
+}
+/**
+ * The per-harness editability matrix (RUSH-2222). Which of a harness's params
+ * this host's API format actually lets you change, each disabled field carrying
+ * the reason the wizard greys it with.
+ *
+ * Sourced ENTIRELY from the same maps the run-time resolver reads —
+ * `baseUrlEnvKeyForHost` (endpoint slot), `authEnvKeyForHost` (auth env), and
+ * `isSelfUpdatingAgent` (pinnable version) — never a table hardcoded alongside
+ * them, so the wizard's enable/disable can never drift from what a run actually
+ * honors (repo rule: the capability table stays truthful, in lockstep with the
+ * code). A disabled param is never a silent no-op — the wizard shows its reason
+ * and the flag path fails loud (`forkProfile`'s base-URL throw is the precedent).
+ */
+export declare function harnessEditable(host: AgentId): HarnessEditability;
 /**
- * Resolver-sourced editability, the scaffold default behind the RUSH-2222 seam.
- * Every field is read from the same maps the run-time resolver uses
- * (`baseUrlEnvKeyForHost` / `authEnvKeyForHost` / `isSelfUpdatingAgent`), never a
- * table hardcoded alongside them — so the wizard's enable/disable can never drift
- * from what a run actually honors (repo rule: the capability table stays truthful,
- * in lockstep with the code). RUSH-2222 may replace this via {@link WizardHooks.editable}
- * to add per-param reasons; it must stay sourced from the resolver.
+ * The boolean projection of {@link harnessEditable} — the scaffold default behind
+ * the RUSH-2222 {@link WizardHooks.editable} seam. Derived from the reason-carrying
+ * matrix so the two can never disagree.
  */
 export declare function defaultEditable(host: AgentId): HarnessEditable;
-/** Outcome of a connection test (RUSH-2221 fills the real classifier). */
-export interface ConnectionTestResult {
-    ok: boolean;
-    /** Machine-readable class when it failed (auth / endpoint / model / unknown). */
-    reason?: 'auth' | 'endpoint' | 'model' | 'unknown';
-    message?: string;
-}
 /**
  * Extension points the sibling subtasks fill without touching the engine. Each is
  * a real no-op-by-default seam: absent, the scaffold uses today's behavior; none

package/dist/commands/harness-wizard.js

@@ -33,21 +33,49 @@ import { listBundles } from '../lib/secrets/bundles.js';
 import { AGENTS, ALL_AGENT_IDS, isSelfUpdatingAgent, resolveAgentName } from '../lib/agents.js';
 import { readAccountRegistry } from '../lib/account-registry.js';
 /**
- * Resolver-sourced editability, the scaffold default behind the RUSH-2222 seam.
- * Every field is read from the same maps the run-time resolver uses
- * (`baseUrlEnvKeyForHost` / `authEnvKeyForHost` / `isSelfUpdatingAgent`), never a
- * table hardcoded alongside them — so the wizard's enable/disable can never drift
- * from what a run actually honors (repo rule: the capability table stays truthful,
- * in lockstep with the code). RUSH-2222 may replace this via {@link WizardHooks.editable}
- * to add per-param reasons; it must stay sourced from the resolver.
+ * The per-harness editability matrix (RUSH-2222). Which of a harness's params
+ * this host's API format actually lets you change, each disabled field carrying
+ * the reason the wizard greys it with.
+ *
+ * Sourced ENTIRELY from the same maps the run-time resolver reads —
+ * `baseUrlEnvKeyForHost` (endpoint slot), `authEnvKeyForHost` (auth env), and
+ * `isSelfUpdatingAgent` (pinnable version) — never a table hardcoded alongside
+ * them, so the wizard's enable/disable can never drift from what a run actually
+ * honors (repo rule: the capability table stays truthful, in lockstep with the
+ * code). A disabled param is never a silent no-op — the wizard shows its reason
+ * and the flag path fails loud (`forkProfile`'s base-URL throw is the precedent).
+ */
+export function harnessEditable(host) {
+    const hasEndpoint = baseUrlEnvKeyForHost(host) !== null;
+    const hasAuth = authEnvKeyForHost(host) !== null;
+    const selfUpdating = isSelfUpdatingAgent(host);
+    return {
+        model: { enabled: true },
+        baseUrl: hasEndpoint
+            ? { enabled: true }
+            : { enabled: false, reason: `host '${host}' has no custom-endpoint slot — base URL not applicable` },
+        auth: hasAuth
+            ? { enabled: true }
+            : { enabled: false, reason: `host '${host}' manages its own login — no auth to edit` },
+        version: selfUpdating
+            ? { enabled: false, reason: `host '${host}' self-updates — its version can't be pinned` }
+            : { enabled: true },
+        fallback: { enabled: true },
+    };
+}
+/**
+ * The boolean projection of {@link harnessEditable} — the scaffold default behind
+ * the RUSH-2222 {@link WizardHooks.editable} seam. Derived from the reason-carrying
+ * matrix so the two can never disagree.
  */
 export function defaultEditable(host) {
+    const e = harnessEditable(host);
     return {
-        model: true,
-        baseUrl: baseUrlEnvKeyForHost(host) !== null,
-        auth: authEnvKeyForHost(host) !== null,
-        version: !isSelfUpdatingAgent(host),
-        fallback: true,
+        model: e.model.enabled,
+        baseUrl: e.baseUrl.enabled,
+        auth: e.auth.enabled,
+        version: e.version.enabled,
+        fallback: e.fallback.enabled,
     };
 }
 /** Resolve the host CLI a fork `source` runs under (the host `buildFork` will use). */
@@ -219,8 +247,10 @@ export function createSteps() {
                 // rest replaces the old silent-drop (`profileFromHostModel` discards a
                 // base URL the host can't honor) with an explicit reason.
                 const host = d.host ?? hostForSource(d.source);
-                if (host && baseUrlEnvKeyForHost(host) === null) {
-                    return { disabled: `host '${host}' has no custom-endpoint slot — base URL not applicable` };
+                if (host) {
+                    const cap = harnessEditable(host).baseUrl;
+                    if (!cap.enabled)
+                        return { disabled: cap.reason };
                 }
                 return 'run';
             },
@@ -285,14 +315,14 @@ function currentBaseUrl(p) {
 export function editSteps(original) {
     const host = original.host.agent;
     const editableFor = (hooks) => (hooks.editable ?? defaultEditable)(host);
-    // decide() has no access to hooks, so gate on the resolver default; a hook that
-    // narrows editability further is applied inside run(). The scaffold's default is
-    // the resolver truth, which is what the matrix subtask builds on.
-    const cap = defaultEditable(host);
+    // decide() has no access to hooks, so gate on the resolver-sourced matrix; a
+    // hook that narrows editability further is applied inside run(). The matrix is
+    // the resolver truth (RUSH-2222), reasons and all.
+    const cap = harnessEditable(host);
     return [
         {
             id: 'model',
-            decide: () => (cap.model ? 'run' : { disabled: `host '${host}' does not support a pinned model` }),
+            decide: () => (cap.model.enabled ? 'run' : { disabled: cap.model.reason }),
             async run(io, d, hooks) {
                 if (!editableFor(hooks).model)
                     return;
@@ -301,7 +331,7 @@ export function editSteps(original) {
         },
         {
             id: 'baseUrl',
-            decide: () => (cap.baseUrl ? 'run' : { disabled: `host '${host}' has no custom-endpoint slot` }),
+            decide: () => (cap.baseUrl.enabled ? 'run' : { disabled: cap.baseUrl.reason }),
             async run(io, d, hooks) {
                 if (!editableFor(hooks).baseUrl)
                     return;
@@ -311,7 +341,7 @@ export function editSteps(original) {
         },
         {
             id: 'account',
-            decide: () => (cap.auth ? 'run' : { disabled: `host '${host}' manages its own login — no auth to edit` }),
+            decide: () => (cap.auth.enabled ? 'run' : { disabled: cap.auth.reason }),
             async run(io, d, hooks) {
                 if (!editableFor(hooks).auth)
                     return;
@@ -327,7 +357,7 @@ export function editSteps(original) {
         },
         {
             id: 'version',
-            decide: () => cap.version ? 'run' : { disabled: `host '${host}' self-updates — its version can't be pinned` },
+            decide: () => (cap.version.enabled ? 'run' : { disabled: cap.version.reason }),
             async run(io, d, hooks) {
                 if (!editableFor(hooks).version)
                     return;
@@ -339,7 +369,7 @@ export function editSteps(original) {
         },
         {
             id: 'fallback',
-            decide: () => (cap.fallback ? 'run' : 'skip'),
+            decide: () => (cap.fallback.enabled ? 'run' : 'skip'),
             async run(io, d) {
                 d.fallbackModel = await io.input({
                     message: 'Fallback model (same-host rate-limit retry; blank for none)',

package/dist/commands/harness.d.ts

@@ -32,6 +32,8 @@ export interface ForkOptions {
     fromSecrets?: string;
     keyStdin?: boolean;
     force?: boolean;
+    /** Tri-state pre-save connection test: true = force, false = skip, undefined = ask on a TTY. */
+    test?: boolean;
 }
 /** Options accepted by `agents harness edit`. */
 export interface EditOptions {
@@ -47,6 +49,8 @@ export interface EditOptions {
     /** `<bundle>` or `<bundle>:<key>` — see {@link applyFromSecrets} in ./profiles.js. */
     fromSecrets?: string;
     keyStdin?: boolean;
+    /** Tri-state pre-save connection test: true = force, false = skip, undefined = ask on a TTY. */
+    test?: boolean;
 }
 /**
  * Build the new harness for `agents harness fork <source> <name>`.
@@ -79,6 +83,16 @@ export declare function forkNeedsWizard(source: string | undefined, name: string
  * `agents harness add <preset-name>` (no flags) still resolves via the preset
  * fallback instead of being routed into the wizard. */
 export declare function addNeedsWizard(name: string | undefined, opts: AddProfileOptions): boolean;
+/** Whether the pre-save connection test runs, or must be asked for on a TTY. */
+export type ConnectionTestGate = 'on' | 'off' | 'ask';
+/**
+ * Resolve the tri-state connection-test gate (RUSH-2221), pure so the branching
+ * is unit-tested with no prompt or spawn. `--test` forces it on, `--no-test`
+ * forces it off, and with neither flag a TTY is asked (default yes) while a
+ * non-interactive caller (`--key-stdin`, piped, CI) skips it — so scripting stays
+ * non-interactive unless it opts in with `--test`.
+ */
+export declare function connectionTestGate(testFlag: boolean | undefined, interactive: boolean): ConnectionTestGate;
 /**
  * Map a finished edit-wizard draft onto {@link EditOptions}, keeping only the
  * fields the user actually changed from the profile's current values. Unchanged