@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## 1.22.86
+
+- **Workers now materialize a slot for every registered Claude account, not only
+  the ones added through the v2 `accounts add` flow (PHNX-3940).** The daemon's
+  slot reconciliation skipped any account row without a `workerCredential` field —
+  every account registered before the v2 model — on the assumption that a legacy
+  row "resolves its token at spawn". That holds for `agents run claude#<name>` but
+  not for the interactive picker, so on a worker whose `auth` bundle already held
+  all eight setup-tokens `agents run claude --interactive --device auto` listed the
+  installed version labels, showed most of them `logged out`, and launching one put
+  a Claude login screen on a headless box. `reconcileLocalWorkerSlots` now resolves
+  each row through the same `reservedSyncTargets` the push plan uses (a v2 row's
+  reserved `__claude__` key, a legacy row's email-keyed `auth` token), so every
+  account whose token is on the box gets a `durable` slot with a 0600
+  `.oauth_token` and the seeded identity the adapter injects from. Two related
+  fixes ride along: the credential publisher is now a ready **headed** device
+  (`electPublisher`, headed-first then by name) instead of the alphabetically first
+  ready box, which had made a worker the fleet's source of truth; and slot
+  reconciliation runs first in the `auth-sync` tick, so a failed shared-state git
+  exchange no longer postpones local provisioning. Source:
+  `cli/src/lib/secrets/reserved-sync.ts`, `cli/src/lib/daemon/auth-sync-service.ts`.
+
+- **`agents secrets` no longer recurses into the legacy `secrets` shim after an
+  in-place upgrade (PHNX-3989).** Boxes that ran agents-cli before the standalone
+  `secrets` engine still carry `~/.agents/.cache/shims/secrets`, a command shim that
+  `exec`s `agents secrets`. It sits first on PATH and survives an upgrade because its
+  baked entrypoint still exists, and 1.22.85 resolved the standalone with a plain
+  `which secrets` — so on every such box `agents secrets …` (and the daemon's
+  reserved-store sync, which uses the same resolver) re-entered itself through the
+  shim without bound. The resolver now skips agents-cli's own shims dir when looking
+  for the standalone (`SECRETS_BIN` still wins; a miss still fails loud with the
+  install command), and the self-heal shim pass removes that legacy `secrets` shim
+  even though its target install is alive, since it can only recurse. The package's
+  postinstall — which used to write that very shim on every install, so an upgrade
+  kept bringing it back — no longer writes a `secrets` alias at all and removes one
+  a previous install left behind; the bare-command aliases are now `sessions`,
+  `browser`, `pty`, and `teams`. Install the standalone with
+  `npm i -g @phnx-labs/secrets-cli` if `agents secrets` reports it missing.
+
+## 1.22.85
+
+- **`agents run codex` marks an exhausted account so rotation stops re-picking it
+  (PHNX-3859).** When a headless codex run ended with `You've hit your usage limit
+  … try again at <date>` (or an out-of-credits refusal), that account's throttle
+  was never recorded, so the balanced picker kept selecting it from a stale usage
+  snapshot and every subsequent run died the same way instead of rotating to a
+  healthy sibling. Codex now persists a per-account refusal marker the same way
+  Claude already did — the usage cache is identity-keyed and shared across
+  harnesses — so `collectRunCandidates` excludes the dead account and picks a
+  healthy one. A usage limit is noted with its reset clock (it auto-clears when the
+  window resets), a genuine credit/quota exhaustion is noted clock-less (cleared by
+  a later successful run), and a limit with no parseable reset is left untouched
+  rather than persisted as an unexpirable marker. Source: `cli/src/lib/exec.ts`
+  (`classifyCodexRunRefusal`, `parseCodexUsageLimitReset`).
+
+- **Account list and view render seams (PHNX-3940).** `agents accounts list <harness>` emits only that harness's group — a provider credential appears under the harnesses it authenticates that match the filter, and empty groups are omitted. `agents view <harness>` prints the ACCOUNT / IDENTITY / STATE / WHERE / USAGE / FIX header once per harness block. USAGE is its own column (bar + percent) between WHERE and FIX; FIX holds only the repair command and stays empty when the verdict is unverified with nothing to run. WHERE reads `this box` when only this device reports, and `accounts list --fleet` names devices whose daemon-state carries no account verdicts (older release) instead of leaving a blank column. `accounts migrate --dry-run` still counts a busy canonical as the kept install and says so. Source: `cli/src/lib/account-catalog.ts`, `cli/src/commands/accounts.ts`, `cli/src/commands/view.ts`, `cli/src/lib/devices/harness-inventory.ts`, `cli/src/lib/accounts/migrate.ts`.
+
+- **Account slots and reserved credential stores (PHNX-3940).** Each account is a HOME-shaped slot at `~/.agents/.history/accounts/<harness>/<id>/` (device-doc `deviceAccounts.slots`, never central). A harness-auth capability table covers every installed agent; connect still drives claude/codex from that table. Secrets refuse user bundle names starting with `__`; reserved stores `__<harness>__` accept only a setup-token or API key. The legacy `auth` bundle stays a readable alias. Source: `cli/src/lib/accounts/slots.ts`, `cli/src/lib/harness-auth-capabilities.ts`, `cli/src/lib/secrets/reserved-stores.ts`.
+
+- **One managed installation per harness (PHNX-3940, track T2).** `agents add <harness>` now installs or reuses the harness's single managed installation (label `main`) via `ensureHarnessInstallation`; `agents add <harness>@<release>` pins that SAME installation — identical to `agents update <harness> --to <release>` — instead of creating a second home, which now requires `--isolated`. Bare `agents update <harness>` updates the single managed installation (the `@<label>` selector stays for legacy layouts but is hidden from help), `agents view --versions` is a hidden legacy diagnostic, and account credential-slot dirs never appear as installations. Source: `cli/src/lib/installations/store.ts`, `cli/src/commands/versions.ts`, `cli/src/commands/update.ts`, `cli/src/commands/view.ts`.
+
+- **Account lists now show live authentication verdicts, fleet coverage, and exact repair commands (PHNX-3940).** `agents accounts list [<harness>]` and `agents view <harness>` share one account-first renderer; `--json` emits the version 2 account schema, and `--fleet` renders accounts by device without exposing reserved credential stores. A provider credential that authenticates a harness appears in that harness's rows (`ready`/`missing`); one no harness uses is listed under Other accounts. Unfiltered `--json` emits one `kind: "provider"` entry per harness the credential authenticates (same `id`, each with its own `harness`), plus one `harness: null` entry for an orphan; a harness filter emits only that harness's entry. The daemon sends one important owner notification when an account changes from live to expired or revoked. Worker usage scope failures are shown as unverified, never as a credit claim.
+
+- **`agents accounts add <harness> [name]` is the account onboarding verb (PHNX-3940, track T4).** On a headed device it reuses the harness's one managed installation, creates a HOME-shaped credential slot per account (no second installation), drives the native login into that slot, registers the fleet-wide account row (`provisioning`, `createdOn`), and mints the durable worker credential into the reserved `__<harness>__` store keyed by account id — claude via a `setup-token` drive in the slot (plus the legacy `auth` bundle key this release), codex/grok/cursor/opencode via `--api-key` or an interactive prompt (never derived from OAuth), codex additionally via `--per-device` for a ChatGPT-plan seat; `--no-worker-token` skips the mint with a warning, and an ambient `CLAUDE_CODE_OAUTH_TOKEN` refuses it. Workers are refused before any side effect, with the laptop command and the automatic provisioning named. **`agents accounts login <harness>#<name>`** re-authenticates into the SAME slot (fail-closed on an identity mismatch) and re-mints/re-syncs; a per-device harness (kimi) may log in on any box. **`agents accounts default <harness> [name]`** is the one write path for the per-harness default (picker with no name). The legacy `connect`, `name`, `label`, `mint`, `attach`, `detach`, `switch`, and `set-default` verbs still execute for one release but are hidden from help and print a one-line pointer to their replacement. The provider form `accounts add <name> --provider <p> --auth <t>` is unchanged when the first arg is not a harness id; mixing the forms fails loud as ambiguous. Source: `cli/src/lib/accounts/add.ts` (renamed from `connect.ts`, `runConnect` kept as an alias), `cli/src/lib/auth-mint.ts` (api-key collection flows in `MINT_FLOWS`, `seedReservedStoreKey`, `workerCredentialStoreKey`), `cli/src/commands/accounts.ts`.
+
+- **Spawn and rotation read account slots, not extra installations (PHNX-3940, track T5).** `agents run <harness>#<name>` (and `--account`) now sets the spawn HOME to that account's slot on this device; the binary still comes from the one managed install unless `@<label>` pins it. A leftover `acct-*` home still resolves until migration; when no `homes` label was recorded, spawn matches the account's identity against each installed version home's own credential file (the pre-T5 fallback). A worker with the durable key present materializes the slot; a missing slot fails loud with the add/login hint rather than launching into a wrong home. Balanced/available rotation enumerates slots (plus leftover homes) and never launches a slot whose verdict is outside `{live, unverified}`. A routine pinned to a native account forwards `--account` so two slots sharing one managed binary still launch the selected login. The account picker shows account · verdict · usage. Symlink-adopted harnesses (droid, antigravity, gemini, …) hold one active slot per device — `accounts default` either repoints the adopted `~/.<config>` under the auth-op lock or fails loud without writing the default; a run whose adopted symlink does not point at the selected slot fails loud. Remote `--device` forwards `#name` unchanged so the peer resolves its own slot. Config-dir env pins (`GROK_HOME`, `OPENCODE_CONFIG_DIR`, XDG) are stripped so two slots in one install never inherit each other's dir. Source: `cli/src/commands/exec.ts`, `cli/src/lib/exec.ts`, `cli/src/lib/exec-account-home.ts`, `cli/src/lib/accounting/rotate.ts`, `cli/src/lib/daemon/runner.ts`, `cli/src/lib/harness/adapter.ts`.
+
+- **Worker provisioning generalized to every portable account, per key and per role (PHNX-3940).** The daemon's `auth-sync` tick no longer syncs only the single legacy `auth` bundle: it plans per ACCOUNT and per KEY (`<ENV>_<accountId>`) over every account's reserved `__<harness>__` store (falling back to the legacy `auth` bundle for a claude row predating the slot model), so a newly-added account propagates to workers within one tick instead of being hidden behind a bundle-coarse "already present" verdict. Pushes target `role=worker` devices only — a headed (`personal`/`desktop`) peer receives the account row but never a durable key (credential-management.md invariant 7). After a key lands on a worker, the daemon materializes a slot for it (`ensureSlot` + the durable write: for claude, `.oauth_token` 0600 + seeded identity; an API-key harness gets a durable slot with no file; a token-less harness gets a per-device slot). An email-only worker slot now resolves its account/org identity from the fleet-synced registry row, so it reads as connected instead of "not connected here". The durable credential moves only over the existing encrypted SSH bundle push and is retained nowhere else; native OAuth/session files are never transported. Source: `cli/src/lib/secrets/reserved-sync.ts`, `cli/src/lib/claude-account-token.ts`, `cli/src/lib/native-accounts.ts`, `cli/src/lib/daemon/auth-sync-service.ts`, `cli/src/lib/agent-spec/agents.ts`.
+
+- **Fold leftover per-account installations into one install plus credential slots (PHNX-3940, track T7).** `agents accounts migrate --dry-run` (default) inventories every installation dir per harness and prints the plan; `--apply` moves each credential-bearing unique identity's `home/` into `~/.agents/.history/accounts/<harness>/<id>/`, trashes empty logged-out homes and duplicate identities (reversible via `agents trash restore`), repoints the global default at the canonical install, and re-indexes `sessions.db` paths in the same transaction. The apply manifest is written with the plan before the first move and updated after each one so a crash lists exactly what moved; `agent@label` bindings are rewritten per-target (a duplicate home's binding follows the kept identity) rather than collapsed onto one bare-agent binding. A busy home is deferred, never moved. An ordinary upgrade only prints the dry-run report. `--device <name>` runs the same command on a fleet box. Routines without an explicit `account:` still resolve a provider binding or per-harness default into injected env. Source: `cli/src/lib/accounts/migrate.ts`, `cli/src/commands/accounts.ts`, `cli/src/lib/session/db.ts`, `cli/src/lib/daemon/runner.ts`.
+
+- **Account model v2 docs, fleet guidance, and seam cleanups (PHNX-3940).** The credential, version, README, and AGENTS reference now describe the shipped one-managed-installation-plus-account-slots model rather than the pre-v2 per-account installations: `agents accounts add <harness> [name]` is the taught onboarding verb, `accounts connect`/`--versions` read as hidden/legacy, and the "no reserved bundle name" claim in `docs/credential-management.md` is resolved in favor of the code — `auth` is the reserved legacy alias for the `__claude__` store, reserved per-harness stores (`__<harness>__`) hold durable worker credentials, and provider accounts stay their own named bundles. The provisioning model is rewritten around `accounts add` plus the daemon's per-key/per-role reserved-store push (headed devices keep native login; workers receive only the durable key). `cli/AGENTS.md` login remediations teach `accounts login <harness>#<name>` on a headed device. Live FIX hints (`signin-badge` / account catalog empty-state) teach the same verbs — never the hidden `connect` alias. Spawn-home resolution in `docs/execution.md` matches the shipped order including spawn-time worker-slot provisioning and adopted-symlink target verification. Bare `agents update <harness>` now names the isolated/legacy installations it left untouched instead of moving the one managed install silently; `reserved-sync.ts` uses a single `AUTH_STORE_ALIAS` symbol; and the "nothing installed" hint teaches bare `agents add <harness>`. Source: `cli/docs/credential-management.md`, `cli/docs/version-management.md`, `cli/AGENTS.md`, `README.md`, `cli/src/commands/update.ts`, `cli/src/lib/secrets/reserved-sync.ts`, `cli/src/lib/installations/resolve.ts`.
+
+- **Process client for the standalone `secrets` CLI (PHNX-3989).** New internal seam `cli/src/lib/secrets-client.ts` — the one bounded request/response client through which agents-cli will talk to the extracted standalone `secrets` executable, over its private fd-3/fd-4 pipe (`secrets __serve`). It resolves the executable (`$SECRETS_BIN`, else `secrets` on PATH; a miss fails loud with `npm i -g @phnx-labs/secrets-cli` and NO fallback to the embedded engine), caches one protocol-version handshake per process, and exposes async (`secretsRequest`) and bounded-sync (`secretsRequestSync`) primitives plus typed wrappers for the bundle/agent/keychain/store/remote/push operations agents-cli consumes. It defaults `SECRETS_HOME` to `~/.agents` so the standalone adopts existing stores in place, and bridges the caller's legacy `AGENTS_SECRETS_PASSPHRASE` onto the renamed `SECRETS_PASSPHRASE` the standalone reads so it can decrypt that same file store. No consumer is converted yet and the embedded engine is untouched — that is the next wave. Source: `cli/src/lib/secrets-client.ts`, `cli/docs/secrets-client.md`.
+
+- **`agents secrets` is now a thin passthrough to the standalone `secrets` CLI, and its browser/ssh/apply/sync/webhook/doctor consumers move onto the process client (PHNX-3989).** `agents secrets <anything>` execs the installed `@phnx-labs/secrets-cli` binary verbatim — forwarding argv and flags unmodified, defaulting `SECRETS_HOME` to `~/.agents` so it adopts the existing store in place — and fails loud with `npm i -g @phnx-labs/secrets-cli` install guidance when the executable isn't found; there is no fallback to the in-repo engine (DIST-1). The old `commands/secrets.ts` registrar (and its `secrets-import`/`secrets-migrate`/`secrets-rotate-passphrase`/`secrets-sync`/`secrets-vault` siblings) stays in the tree, unregistered, until every other track's consumers convert. `agents setup secrets` is now install guidance plus a hand-off to the standalone's own interactive `secrets migrate`, dropping the old backend/policy wizard. `browser`, `ssh`, `apply`/`fleet apply`, `sync`, `webhooks serve`, `fleet capture`, `doctor`, and their library dependencies (`lib/browser/chrome.ts`, `lib/share/config.ts`, `lib/daemon-webhooks.ts`, `lib/sync-umbrella.ts`, `lib/fleet/apply.ts`) now resolve bundles, keychain items, and remote-sync pulls through `secrets-client.ts` instead of importing `lib/secrets/*` directly; fleet policy (the reserved `auth` bundle name and backend check) moves to a new agents-owned `lib/secrets-policy.ts` that calls the client rather than the engine. `secrets-client.ts` gains `bundleBackend`, `listRemoteBundles`/`pullBundle`, `scanUserRcFiles`/`masterPassphraseInEnv`, and the pure `secretsKeychainItem`/`keychainRef` naming helpers to cover these call sites. Source: `cli/src/commands/secrets-passthrough.ts`, `cli/src/commands/setup-secrets.ts`, `cli/src/lib/secrets-client.ts`, `cli/src/lib/secrets-policy.ts`, `cli/src/lib/net-close.ts`.
+
+- **The run/exec hot path resolves secrets through the standalone `secrets` process client (PHNX-3989).** `agents run --secrets <bundle>` (incl. `--secrets-keys`, `--allow-expired`, and remote `bundle@host`), the crabbox `--lease` provider-token / tailscale reads, the Cursor and Antigravity cloud API-key reads, and the `--lease` Claude credential read now go through `cli/src/lib/secrets-client.ts` instead of the embedded `lib/secrets/*` engine — a missing `secrets` executable fails loud with install guidance, never a silent fallback (DIST-1). Bundle precedence (profile < account < auto-share < bundles < `--env`) and the agents-owned `bundle@host` policy (fleet-alias resolution, flag validation) stay in agents-cli and are passed into the client; behaviour is unchanged. Source: `cli/src/lib/exec.ts` context, `cli/src/commands/exec.ts`, `cli/src/lib/crabbox/{cli,runtimes}.ts`, `cli/src/lib/cloud/{cursor,antigravity}.ts`.
+
+- **Accounts, profiles, and the reserved `auth` bundle now go through the standalone `secrets` CLI (PHNX-3989).** `agents accounts` (add / set-key / rename / remove / view / sync / mint), the harness profile token store (`agents harness add --from-secrets`, provider keys, legacy profile-auth migration), `agents lease setup`, the harness wizard's bundle browse, Claude usage/probe setup-token reads, and the Claude OAuth keychain read/write no longer load the embedded secrets engine: every read and write is one call on `cli/src/lib/secrets-client.ts`, which spawns the installed `secrets` executable. The seam is strict — a missing `secrets` fails loud with `npm i -g @phnx-labs/secrets-cli` and there is no fallback to the old engine. Fleet policy stays in agents-cli and is passed in: the reserved `auth` bundle's file-backend rule now lives in `cli/src/lib/secrets/reserved-stores.ts` (a keychain- or vault-backed `auth` still fails loud on read, and the standalone refuses to write one), and the SSH host-pinning guard for credential transport moved to `cli/src/lib/hosts/credential-transport.ts`. The client grew the wrappers these paths need (`renameBundle`, `rotateBundleSecret`, `bundleBackend`, `keychainUsesFileFallback`, sync siblings for the bundle and item writers) plus the raw item-naming helpers (`secretsKeychainItem`, `profileKeychainItem`, `keychainRef`, `parseBundleValue`). Setup-token reads memoize per process for 10 s instead of fingerprinting the engine's on-disk credential file (an in-process mint or rotation clears the memo). The suite installs the pinned published standalone once per machine (`tests/secrets-standalone.ts`, wired through vitest's global setup) and drives it for real — no in-memory keychain. Source: `cli/src/lib/account-registry.ts`, `cli/src/lib/profiles.ts`, `cli/src/lib/auth-mint.ts`, `cli/src/lib/claude-account-token.ts`, `cli/src/commands/accounts.ts`, `cli/src/commands/profiles.ts`.
+- **Read-only status surfaces never hang or crash on a missing/broken `secrets` (PHNX-3989).** The synchronous client (`secretsRequestSync`) does its fd 3/4 wiring in a POSIX shell — request via a FIFO, response redirected onto stdout (`4>&1`) — so it works under the Bun runtime the suite spawns the CLI with (Bun's `spawnSync` drops numbered fds 3+, which had left the standalone deadlocked for 60 s and surfacing as `secrets returned a non-JSON response`). It is bounded to 3 s, and `agents view` / `agents accounts` / the `agents run` account-rotation pool now degrade to one clear line (`secretsUnavailable`) instead of hanging or aborting when the standalone can't answer. A non-JSON reply names the first 200 bytes it got on fd 4, and `SecretsClientError` serializes to a plain `{code, message}` so folding a failure into a `JSON.stringify`'d structure can't throw a circular-reference error. Source: `cli/src/lib/secrets-client.ts`, `cli/src/lib/account-catalog.ts`, `cli/src/lib/accounting/account-pool-collect.ts`, `cli/tests/secrets-standalone.ts`.
+
+- **The in-repo secrets engine is gone — the standalone `@phnx-labs/secrets-cli` is the only implementation (PHNX-3989 Track D).** `cli/src/lib/secrets/**` (bundle storage, the broker, the keychain/file/vault backends, the keychain-helper Swift source) and the old `commands/secrets.ts`/`secrets-vault.ts`/`secrets-sync.ts`/`secrets-migrate.ts`/`secrets-import.ts`/`secrets-rotate-passphrase.ts` command files are deleted; every consumer (`account-registry.ts`, `auth-mint.ts`, `claude-account-token.ts`, `exec.ts`, `sync-umbrella.ts`, `crabbox/cli.ts`, `fleet/apply.ts`, `teams/agents.ts`, `devices/doctor-findings.ts`, `session/sync/config.ts`, `commands/{daemon,lease,profiles,sync,exec,repo}.ts`, and more) now resolves through `secrets-client.ts` exclusively. Shared wire types moved to a new pure `secrets-types.ts`; agents-owned reserved-store constants moved to a new leaf `reserved-stores.ts` (kept deliberately dependency-free to avoid a circular import with `secrets-policy.ts`'s fleet-sync helpers, which absorbed `reserved-sync.ts` and gained resource-profile scoping — `resolveSecretsContextForRun`/`resolveAllowedBundlesForActiveProfile`, wired into `agents run --secrets` per CTX-1). **The daemon no longer hosts or takes over the secrets broker (OWN-1):** `secrets-broker-service.ts` and `keychain-reap-service.ts` are deleted, `secrets-broker`/`keychain-reap` are gone from `DaemonServiceId`, and `agents daemon status`/`services` now only probes the broker's reachability (`socketPath`/health always `null`). The `__vault-age-helper`/`__secrets-get`/`__secrets-ping`/`__secrets-lock` intercepts are gone from `index.ts` (now a zero-static-import slim shell), and `bootstrap.ts` no longer reinstalls a keychain helper on upgrade. Release tooling that built/signed/verified the keychain helper (`scripts/build-keychain-helper.sh`, `scripts/verify-keychain-helper.sh`, `scripts/keychain-entitlements.plist`) is deleted, and `release-attestation-produce.sh`/`release.sh`/`release-manifest.sh`/`remote-sign-mac.sh`/`signing-home-base-probe.sh` no longer reference it — a release now signs only the menu-bar helper and the standalone CLI binary. `age-encryption` and the keychain-helper build deps are dropped from `package.json`. A new `scripts/packed-tarball.test.ts` proves the packed tarball ships no `dist/lib/secrets/`, no keychain-helper artifact, and no bundled `.app` of any kind — DIST-1, executed against a real `npm pack` + `tar tzf`, not grepped. Source: `cli/src/lib/{secrets-client,secrets-types,secrets-policy,reserved-stores}.ts`, `cli/src/index.ts`, `cli/src/bootstrap.ts`, `cli/src/lib/daemon/daemon.ts`, `cli/scripts/packed-tarball.test.ts`.
+
+- **Workflows sync through one per-harness registry (PHNX-3993).** How each
+  workflows-capable harness stores a synced workflow (Claude bundle dir, Kimi flow
+  skill, Antigravity global_workflows file, Goose recipe, OpenClaw Lobster, Grok
+  Rhai) is declared once in `WORKFLOW_TARGETS`; sync, list, remove, the `agents
+  doctor` drift check, and the staleness detector are generic over it, where they
+  previously each branched on the harness id and the detector kept its own copy of
+  the ownership-marker parsers. Paths, markers, and error text are unchanged; a
+  foreign Kimi `<name>/` skill dir now blocks a sync the same way a foreign file
+  blocks the other harnesses instead of being written into. A completeness test
+  pins the table to `capableAgents('workflows')`. Source:
+  `cli/src/lib/workflows-registry.ts`.
+
 ## 1.22.84
 
 - **`agents feed watch` is cheap enough to leave running (PHNX-3939).** The watcher

package/README.md

@@ -577,12 +577,12 @@ agents:
 Think `requirements.txt` for CLI coding agents, on steroids. A shim reads `agents.yaml` from the project root and routes `claude` / `codex` / `antigravity` / `grok` (and others) to the right version automatically. Each version gets its own isolated home -- switching backs up config and re-syncs resources.
 
 ```bash
-agents add claude@2.0.65     # Install a specific version
-agents add codex@latest       # Install latest
-agents add codex@oldest       # Install the oldest published version
+agents add claude             # Install the one managed installation (taught form)
+agents add claude@2.0.65     # Pin that installation to a specific release (expert)
+agents add codex@latest       # Latest published release
 agents view                   # See everything installed
-agents accounts mint claude --account work   # mint a setup-token into a named account
-agents run claude --account work
+agents accounts add claude work   # headed: login + worker credential + sync
+agents run claude#work
 ```
 
 Multiple provider accounts to juggle? See [Accounts](#accounts) below.
@@ -1151,24 +1151,32 @@ Distinct from **Accounts** below: this is *your human identity*; those are the *
 
 ## Accounts
 
-Choose an agent and an account, independently of its release number. Connect a
-native account once on this device; its home, login, settings, and sessions stay
-in place when the executable is updated.
+Choose an agent and an account, independently of its release number. Install the
+harness once; each account is a credential slot of that one install -- login,
+settings, and sessions stay in place when the executable is updated. Add an
+account on a headed (personal/desktop) device; workers pick up the durable
+credential automatically.
 
 ```bash
-agents accounts connect codex work
-agents accounts connect claude personal
-agents accounts switch codex work
-agents run codex#work
-agents view codex                 # accounts and usage, one row per identity
-agents view codex --versions      # every retained installation and actual release
-```
-
-Connecting another account creates its own isolated home, even when it uses the
-same release. Reconnecting a named account reuses its existing home. Old
-release-named homes are adopted in place: no credential copying, directory moves,
-or automatic duplicate deletion. Native login remains device-local; an account
-known on another device is not necessarily connected here.
+agents add claude
+agents accounts add claude work          # headed: native login + worker credential + sync
+agents accounts add codex personal
+agents accounts login claude#work        # re-auth into the same slot
+agents accounts default claude work
+agents run claude#work
+agents accounts list
+agents view claude                       # accounts and usage, one row per identity
+agents view claude --versions            # legacy diagnostic: every retained installation and actual release
+```
+
+`accounts add <harness> [name]` reuses the managed install, creates a HOME-shaped
+slot (no binary), drives the native login there, registers the fleet-wide row, and
+mints the worker credential (claude: `setup-token`; codex/grok/cursor/opencode:
+`--api-key` or a prompt). On a worker it refuses before any slot, install, or
+browser. An already-registered name or identity points at `accounts login`.
+`accounts login <harness>#<name>` re-auths into the same slot, fails closed on a
+different identity, and re-mints. Native login stays device-local; an account
+known on another device is not necessarily logged in here.
 
 Agents checks for updates to safely managed harness installations automatically.
 Disable this globally or per harness with `agents config set updates.auto false`
@@ -1177,30 +1185,44 @@ to inspect eligibility without installing, or `agents update codex` to update
 that harness's installations. Running sessions and deliberately pinned
 installations are protected. See [installation and update policy](cli/docs/version-management.md).
 
-For unattended workers, give a **provider credential** a durable name and reuse it
-across supported harnesses and machines:
+For a portable **provider credential** (API key / setup-token / bearer), the first
+arg is the account name, not a harness id:
 
 ```bash
-agents accounts mint claude                  # drive `claude setup-token`, seed a named account + reserved auth bundle
-agents accounts mint claude --token-stdin    # already have a token
 agents accounts add work --provider anthropic --auth setup-token
 agents accounts add gateway --provider openrouter --auth api-key \
   --from-secrets openrouter.ai:OPENROUTER_API_KEY  # import from an existing secrets bundle
 agents accounts add deepinfra --provider deepinfra --auth api-key
 
-agents accounts switch claude             # picker: usage %, headroom, signed-out / rate-limited
-agents accounts switch claude work        # skip the picker; same write as set-default
-agents accounts set-default claude work   # claude uses `work` when --account is omitted
-agents accounts sync work --device yosemite-s0   # explicitly copy the bundle to a worker device
+agents accounts default claude work              # claude uses `work` when --account is omitted
+agents accounts sync work --device yosemite-s0   # copy the bundle to a worker
 agents run claude --account work
 agents harness add deepinfra --account deepinfra
 ```
 
-`agents accounts mint claude` (also `agents auth mint claude`) is the first-class replacement for the mint-auth recipe: it drives `claude setup-token` in a PTY, captures a well-formed `sk-ant-oat01-` token, and seeds both the named account and the reserved file-based `auth` bundle that usage/probe reads. Native rotating OAuth is never copied.
+Mixing `accounts add <harness>` with `--provider` fails loud as ambiguous. One
+provider account **is** one `agents secrets` bundle -- `accounts add` creates it
+with secrets policy `never`, so a background launch never raises Touch ID.
+Harness-native OAuth stays where the harness put it and is never copied.
 
-One provider account **is** one `agents secrets` bundle -- `agents accounts add` creates it with secrets policy `never`, so a background agent launch on that account never raises Touch ID. `agents accounts` (no subcommand) lists provider bundles next to harness-native signed-in identities so you see both kinds of credential together; `accounts list` / `inspect <name>` / `set-key <name>` (rotate) / `rename` / `remove` manage a bundle by its stable id, independent of its current label. `accounts switch <harness>` is the fast picker over that default -- it writes the same binding as `set-default`, and balanced rotation already honors it.
+```bash
+agents accounts list
+agents accounts rename claude#work cloud
+agents accounts logout claude#work
+agents accounts remove claude#cloud
+```
+
+`accounts list` shows native logins and provider credentials together. `rename` /
+`remove` / `view` take `<harness>#<name>` when the same name exists on several
+harnesses; an ambiguous bare name is refused. `logout` signs out a native OAuth
+login; API-key accounts use `remove`. `accounts sync <name> --device <device>`
+is the only way a provider credential crosses machines.
 
-Harness-native OAuth logins (Claude Code's own `/login`, `codex login`, and so on) stay exactly where the harness put them -- agi-cli discovers and displays them but never copies, renames, or converts them into a provider bundle. Native `accounts name` / `attach` is only for harnesses agents-cli can isolate today (claude, codex, grok; muse when an email is present). A device-scoped login (kimi, droid, …) is refused with a named reason; provider `accounts add --provider` is unrestricted. Native **labels** (`agents accounts label codex personal`) bind to a stable identityKey on the central account row in `agents.yaml`, which `agents repo push/pull` already syncs fleet-wide, so `codex#personal` selects the same login on every box. `accounts sync <name> --device <device>` is the only way a **provider** account credential crosses machines, and it's explicit: nothing copies OAuth automatically. Selection order for a run is explicit `--account`, then `accounts set-default` / `switch` for that harness, then the harness's native/balanced account behavior.
+Selection order for a run is explicit `--account` / `<harness>#<name>`, then
+`accounts default` for that harness, then the harness's native/balanced behavior.
+The hidden `connect` / `name` / `label` / `mint` / `attach` / `detach` /
+`switch` / `set-default` verbs are still accepted this release and print their
+replacement (`add` / `login` / `default` / `run <harness>#<name>`).
 
 ---
 
@@ -1225,23 +1247,25 @@ agents run claude "charge a test card" --secrets prod-stripe
 
 Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item aborts before the child starts.
 
-### Cross-machine sync via iCloud Keychain
+### Cross-machine sync
 
-Secret bundles sync through iCloud Keychain by default. Sign into the same iCloud account on another Mac (with iCloud Keychain enabled) and the bundle appears there within seconds — no copy-paste, no `.env` files emailed to yourself, no shared secret stores. Pass `--no-icloud-sync` when creating a bundle if it should stay device-local.
+Secrets are provided by the standalone [`@phnx-labs/secrets-cli`](https://github.com/phnx-labs/secrets-cli)
+engine (`agents setup secrets` checks whether it's installed). Its `push`/`pull`
+verbs move a bundle between machines by encrypting it and round-tripping it
+through `api.prix.dev` — no copy-paste, no `.env` files emailed to yourself:
 
 ```bash
 # On laptop:
 agents secrets create npm-tokens
-agents secrets add npm-tokens NPM_TOKEN          # value lives in iCloud Keychain
+agents secrets add npm-tokens NPM_TOKEN          # value lives in the local keychain/file store
+agents secrets push npm-tokens                   # encrypt + upload
 
-# On another Mac (same iCloud account):
-agents secrets list                              # npm-tokens is already there;
+# On another machine:
+agents secrets pull npm-tokens                   # decrypt + restore locally
 agents run claude "..." --secrets npm-tokens     # injects NPM_TOKEN automatically
 ```
 
-Under the hood, synced bundles route writes through a notarized helper app (`Agents CLI.app`) that holds the entitlement macOS requires for `kSecAttrSynchronizable`. Bundles created with `--no-icloud-sync` stay device-local.
-
-Bundle definitions sync via iCloud Keychain too — no `agents repo push` needed for secrets, no recreate step on each Mac. Nothing about secrets ever lives in plaintext on disk.
+Nothing about a secret's value ever lives in plaintext on disk, on either end.
 
 ### Per-secret metadata and rotation
 
@@ -1301,8 +1325,8 @@ some of it is planned (RUSH-2290), and the section marks what is landed vs inten
 
 ### Daemon
 
-Routines, the secrets broker, browser IPC, and the watchdog pass all run inside
-one always-on daemon per device. `agents daemon` is its runtime surface:
+Routines, browser IPC, and the watchdog pass all run inside one always-on
+daemon per device. `agents daemon` is its runtime surface:
 
 ```bash
 agents daemon                # identity + duplicates + per-service health (same as status)
@@ -1316,9 +1340,9 @@ agents daemon disable        # persist daemon.enabled: false -- nothing auto-sta
 agents daemon enable         # clear the kill switch
 
 agents daemon reload                        # SIGHUP -- reload jobs, re-evaluate scheduler.enabled, no restart
-agents daemon services                      # health of the two hosted services (secrets broker, browser IPC)
+agents daemon services                      # health of every hosted service (browser IPC, scheduler, ...)
 agents daemon services list                 # every toggleable service and its current on/off state
-agents daemon services enable secrets-broker
+agents daemon services enable scheduler
 agents daemon services disable browser-ipc  # stop hosting browser IPC without stopping the daemon
 agents browser stop --service               # browser-scoped alias; next browser action requiring IPC re-enables it
 agents routines stop                        # disable/reload only the scheduler service
@@ -1326,9 +1350,9 @@ agents daemon logs -f --level warn --since 1h
 agents daemon doctor                        # one-shot health check; non-zero exit on problems
 ```
 
-Each hosted responsibility (secrets broker, browser IPC, scheduler, monitors,
-watchdog, device probe, self-heal, self-update, keychain reap, account-state refresh,
-state-dir checks) is an independent toggle in `~/.agents/daemon/services.yaml`.
+Each hosted responsibility (browser IPC, scheduler, monitors, watchdog, device
+probe, self-heal, self-update, account-state refresh, state-dir checks) is an
+independent toggle in `~/.agents/daemon/services.yaml`.
 Self-update checks npm on its own schedule, installs + verifies a newer
 agents-cli with the same primitives `agents upgrade` uses, then exits so the OS
 supervisor relaunches the daemon onto the new code — the daemon used to run
@@ -1590,7 +1614,7 @@ Extras clone into `~/.agents-system/.repos/<alias>/` and ship the same layout as
 
 ## Security & Privacy
 
-**The CLI binary has no built-in telemetry or phone-home path.** Routine commands run locally; explicit features such as cloud dispatch and iCloud Keychain sync send only the data needed for the action you invoke. Here's exactly what `agi-cli` stores locally and why.
+**The CLI binary has no built-in telemetry or phone-home path.** Routine commands run locally; explicit features such as cloud dispatch and secrets push/pull send only the data needed for the action you invoke. Here's exactly what `agi-cli` stores locally and why.
 
 ### Event log
 
@@ -1635,14 +1659,17 @@ The index lives at `~/.agents/.history/sessions/sessions.db` (SQLite + FTS5). A
 
 ### Secrets
 
-API keys and credentials are stored in macOS Keychain, never in plaintext files. Bundle definitions also live in Keychain.
+Secrets are provided by the standalone `@phnx-labs/secrets-cli` engine, stored
+in the OS keychain or an encrypted file store — never in plaintext files.
+Bundle definitions live alongside their values.
 
 ```bash
 agents secrets create my-keys
-agents secrets add my-keys API_KEY    # Prompts for value, stores in Keychain
+agents secrets add my-keys API_KEY    # Prompts for value, stores in the keychain/file backend
 ```
 
-By default, secrets sync via iCloud Keychain to your other Macs. With `--no-icloud-sync`, they stay device-local. See [Secrets](#secrets) for full usage.
+Move a bundle to another machine with `secrets push`/`secrets pull` (encrypted
+round trip through `api.prix.dev`). See [Secrets](#secrets) for full usage.
 
 ### Summary
 
@@ -1650,7 +1677,7 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 |------|----------|--------------|---------|
 | Event log | `~/.agents/.cache/logs/` | You only (0600) | `AGENTS_DISABLE_EVENT_LOG=1` |
 | Session index | `~/.agents/.history/sessions/` | You only | Delete the directory |
-| Secrets | macOS Keychain | You + apps you authorize | Don't use `agents secrets` |
+| Secrets | OS keychain / encrypted file store | You + apps you authorize | Don't use `agents secrets` |
 | Config | `~/.agents/` | You only | N/A |
 
 ---
@@ -1747,7 +1774,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 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.
+**macOS-only features:** `agents accounts add` requires macOS. `agents secrets` itself is cross-platform — macOS Keychain, Linux libsecret, or the `file` backend everywhere, including Windows (non-WSL) via environment variables or a `.env` file as a fallback when neither native store applies.
 
 Interactive runs spawn directly by default. Enable `tmux.enabled` on a device to
 give each run an addressable pane for `agents message`, injection, and `agents

package/dist/bootstrap.d.ts

@@ -1,12 +1,13 @@
 /**
  * Full CLI bootstrap — loaded only after index.ts's argv fast paths miss.
  *
- * RUSH-2335: `src/index.ts` is a slim shell that statically imports only the
- * leaf `lib/secrets/sync-commands.js` so `__secrets-*` / `__vault-age-helper` /
- * `__shim` / `__daemon-run` can exit without evaluating the
- * commander + self-update + command-registry graph (~140ms saved per
- * synchronous broker read). Everything below that shell lands here via
- * `await import('./bootstrap.js')`.
+ * RUSH-2335: `src/index.ts` is a slim shell so `__shim` / `__daemon-run` and
+ * the other hidden fast paths can exit without evaluating the commander +
+ * self-update + command-registry graph. Everything below that shell lands
+ * here via `await import('./bootstrap.js')`. The `__secrets-*` / synchronous
+ * broker fast paths that used to justify this shell's one static import moved
+ * with the standalone `secrets` engine (PHNX-3989) — `index.ts` now has no
+ * static imports at all above this line.
  *
  * This module is the previous body of `index.ts` (command registration, update
  * checks, first-run setup, migrations, parse). Side-effecting top-level code

package/dist/bootstrap.js

@@ -1,12 +1,13 @@
 /**
  * Full CLI bootstrap — loaded only after index.ts's argv fast paths miss.
  *
- * RUSH-2335: `src/index.ts` is a slim shell that statically imports only the
- * leaf `lib/secrets/sync-commands.js` so `__secrets-*` / `__vault-age-helper` /
- * `__shim` / `__daemon-run` can exit without evaluating the
- * commander + self-update + command-registry graph (~140ms saved per
- * synchronous broker read). Everything below that shell lands here via
- * `await import('./bootstrap.js')`.
+ * RUSH-2335: `src/index.ts` is a slim shell so `__shim` / `__daemon-run` and
+ * the other hidden fast paths can exit without evaluating the commander +
+ * self-update + command-registry graph. Everything below that shell lands
+ * here via `await import('./bootstrap.js')`. The `__secrets-*` / synchronous
+ * broker fast paths that used to justify this shell's one static import moved
+ * with the standalone `secrets` engine (PHNX-3989) — `index.ts` now has no
+ * static imports at all above this line.
  *
  * This module is the previous body of `index.ts` (command registration, update
  * checks, first-run setup, migrations, parse). Side-effecting top-level code
@@ -381,27 +382,9 @@ async function installResolvedPackage(metadata) {
                 `The box has the new package but no working \`agents\` — relink manually: ${relink}`);
         }
     }
-    // The npm install above runs with --ignore-scripts, so the postinstall that
-    // installs the macOS Keychain helper never fires on upgrade. Force-refresh the
-    // helper here so a user upgrading FROM a broken build (e.g. the entitlement-less
-    // 1.20.4 helper that fails SecItemAdd with -34018) gets the fixed, signed bundle
-    // immediately — instead of waiting for the lazy staleness check in
-    // getKeychainHelperPath() to repair it on their next secret operation. The new
-    // package is already on disk, so the dynamic import resolves the freshly-installed
-    // helper module + bundle. Best-effort: an upgrade must never fail because the
-    // helper could not be reinstalled (the lazy staleness check in
-    // getKeychainHelperPath() still repairs it on the next secret operation).
-    if (process.platform === 'darwin') {
-        try {
-            const { ensureKeychainHelperInstalledAsync } = await import('./lib/secrets/install-helper.js');
-            // Async + download-capable: an upgrade to a tarball that dropped the
-            // bundle fetches the verified release asset instead of no-op'ing.
-            await ensureKeychainHelperInstalledAsync({ forceReinstall: true });
-        }
-        catch {
-            // Non-fatal.
-        }
-    }
+    // The macOS Keychain helper this used to force-refresh on upgrade moved with
+    // the standalone `secrets` engine (PHNX-3989) — it downloads and verifies its
+    // own helper release now, off this CLI's upgrade path entirely.
 }
 /** Present an interactive upgrade prompt (TTY) or a one-line hint (non-TTY). */
 async function promptUpgrade(latestVersion) {
@@ -1214,6 +1197,16 @@ catch (err) {
             console.error(err.message);
             process.exit(1);
         }
+        // The standalone `secrets` CLI is a required external dependency (DIST-1);
+        // when it is missing or a request to it fails, the sync/async client throws
+        // a typed SecretsClientError whose message is user-actionable install
+        // guidance (e.g. SECRETS_BIN_MISSING). Handling it at this choke point means
+        // every call site (doctor, browser, share, …) prints one clear line and
+        // exits 1 instead of dumping a Node stacktrace, without a per-call try/catch.
+        if (err.name === 'SecretsClientError') {
+            console.error(err.message);
+            process.exit(1);
+        }
     }
     throw err;
 }

package/dist/cli/command-registry.js

@@ -60,7 +60,11 @@ export const loadRestore = async () => (await import('../commands/trash.js')).re
 export const loadDoctor = async () => (await import('../commands/doctor.js')).registerDoctorCommand;
 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;
+// PHNX-3989: `agents secrets` is a thin passthrough to the standalone
+// `secrets` CLI (secrets-passthrough.ts). The legacy in-repo engine and its
+// own command registrar are gone (Track D, tasks.md item 7) — the standalone
+// `@phnx-labs/secrets-cli` package is the only implementation.
+export const loadSecrets = async () => (await import('../commands/secrets-passthrough.js')).registerSecretsCommands;
 export const loadMenubar = async () => (await import('../commands/menubar.js')).registerMenubarCommands;
 export const loadSync = async () => (await import('../commands/sync.js')).registerSyncCommand;
 export const loadRefreshRules = async () => (await import('../commands/refresh-rules.js')).registerRefreshRulesCommand;

package/dist/commands/accounts.d.ts

@@ -2,6 +2,7 @@ import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
 import { collectRunCandidates, type RotateCandidate } from '../lib/accounting/rotate.js';
 import { type Profile } from '../lib/profiles.js';
+import { type NativeAccountCatalogRow, type ProviderAccountCatalogRow } from '../lib/account-catalog.js';
 import { type UnifiedAccount } from '../lib/account-registry.js';
 export declare function nativeIdentityFromSource(raw: string): Promise<{
     agent: AgentId;
@@ -43,19 +44,11 @@ export declare function parseBundleKey(raw: string): {
     bundle: string;
     key: string;
 };
-/** Pure text renderer for `agents accounts list` — grouped, column-aligned, labels first-class. */
-export declare function renderAccountList(records: {
-    name: string;
-    provider: string;
-    auth: string;
-}[], native: {
-    agent: AgentId;
-    name?: string;
-    display: string;
-    versions: string[];
-    isDefault?: boolean;
-    state?: 'connected' | 'reconnect-needed';
-}[]): string;
+/** Compatibility export for tests/consumers; the canonical renderer is shared with view. */
+export declare function renderAccountList(native: NativeAccountCatalogRow[], providers?: ProviderAccountCatalogRow[], opts?: {
+    harness?: AgentId;
+    localDevice?: string;
+}): string;
 /** One labelable signed-in identity, folded across every version it is signed into. */
 export interface LabelIdentity {
     identityKey: string;