@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/README.md

@@ -56,7 +56,8 @@ agents run claude "explain this repo"  # run any agent on your existing subscrip
 
 Everything here — and every other command in this README — is free and needs no account; the optional `agents auth login` exists only for [team spaces](#sign-in). `agents setup` is interactive and idempotent -- safe to re-run on any machine. Once core setup exists, it opens a status-aware menu for browser, computer, secrets, fleet, share, watchdog, and device preferences; each choice delegates to the same wizard available under `agents setup <capability>`. In CI or another non-TTY, bare setup prints the checklist without prompting. The `agi-cli.sh` one-liner installs this same canonical `@phnx-labs/agents-cli` package. Prefer bun? `bun install -g @phnx-labs/agents-cli` works too.
 
-Full path -- installing harnesses, logging in, smoke-testing `agents teams`, and setting up your own fleet: [`apps/cli/docs/QUICKSTART.md`](apps/cli/docs/QUICKSTART.md).
+The command surface teaches setup through `agents setup` and group-level `--help`.
+The durable system model starts at [`cli/docs/README.md`](cli/docs/README.md).
 
 **Learn (concepts):** [Loop + graph engineering](https://agi-cli.sh/learn/loop-and-graph-engineering) · [Teams as graph engineering](https://agi-cli.sh/learn/teams-graph-engineering) · [Sessions · index + cross-device](https://agi-cli.sh/learn/sessions-index) · [Distributed fleet execution](https://agi-cli.sh/learn/distributed-fleet). Also: [harness engineering](https://agi-cli.sh/learn/harness-engineering) · [visual longform](https://share.agents-cli.sh/muqsitnawaz/agents-loop-and-graph-engineering).
 
@@ -336,7 +337,7 @@ agents insights --since 7d
 
 Interactive picker when you're in a terminal. Structured output (`--json`, `--markdown`, filtered by role or turn count) when piped.
 
-Backed by a SQLite + FTS5 index at `~/.agents/.history/sessions/sessions.db` with incremental scanning -- warm reads in ~100ms. Tool-call evidence is redacted and bounded before it is cached; repeated `--query` clauses must match distinct calls in one session. Tool queries read SQLite only: `agents sessions backfill tools` performs the one-time historical parse, while normal incremental scans index new and changed sessions. The index stores ordered static Bash program sites, so `--count` reports occurrences, containing tool calls, and distinct sessions without reparsing. `--fleet` executes one origin partition per device, so synced mirrors cannot duplicate compact evidence or counts returned over SSH; transcript bodies stay on their origin machine. This uses relational SQLite rows and literal FTS5 only, with no embeddings, vector database, or model calls. External tools can consume `--json` output as a programmatic observability layer; see [docs/sessions.md](apps/cli/docs/sessions.md) for the schemas and [docs/observability.md](apps/cli/docs/observability.md) for the consumption patterns.
+Backed by a SQLite + FTS5 index at `~/.agents/.history/sessions/sessions.db` with incremental scanning -- warm reads in ~100ms. Tool-call evidence is redacted and bounded before it is cached; repeated `--query` clauses must match distinct calls in one session. Tool queries read SQLite only: `agents sessions backfill tools` performs the one-time historical parse, while normal incremental scans index new and changed sessions. The index stores ordered static Bash program sites, so `--count` reports occurrences, containing tool calls, and distinct sessions without reparsing. `--fleet` executes one origin partition per device, so synced mirrors cannot duplicate compact evidence or counts returned over SSH; transcript bodies stay on their origin machine. This uses relational SQLite rows and literal FTS5 only, with no embeddings, vector database, or model calls. External tools can consume `--json` output as a programmatic observability layer; see [docs/sessions.md](cli/docs/sessions.md) for the schemas and [docs/observability.md](cli/docs/observability.md) for the consumption patterns.
 
 ### Live state, and catching up fast
 
@@ -492,7 +493,7 @@ agents fleet apply --no-login             # skip login propagation
 
 `agents fleet apply` probes every target over the existing SSH transport, then reconciles it to the profile: installs missing agents, upgrades `agi-cli`, syncs the named config scopes, and **propagates logins** so a host signed in once seeds the fleet -- turning "6 hosts x 8 harnesses = 48 OAuth flows" into one. Portable credential files (claude, codex, grok, kimi, opencode, droid, antigravity) stream to each target over encrypted SSH stdin, never shell-interpolated, and land at `0600`. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity on a Mac target) can't be extracted -- those surface as a one-time manual login, never faked. `--plan` / `--dry-run` shows the full matrix without touching anything.
 
-See [docs/fleet.md](apps/cli/docs/fleet.md) for the manifest schema and reconcile semantics.
+See [docs/fleet.md](cli/docs/fleet.md) for the manifest schema and reconcile semantics.
 
 ---
 
@@ -709,9 +710,11 @@ email) and naming which harnesses use it — the fast way to see which accounts
 and healthy across every machine. Scope either with `--agents <csv>` / `--device <csv>`, and
 add `--json` for the machine-readable per-host rows.
 
-**Hosts** (`agents hosts`) are git-synced dispatch targets in `agents.yaml`; **devices** (`agents devices`) are your Tailscale machines in a local registry. Both ride SSH and feed one host pool: devices appear in `agents hosts list` and capability routing without a second enrollment. On `--device` runs every `agents run` option is either forwarded (`--effort --env --timeout --loop …`), rejected loud (`--secrets` never crosses SSH implicitly), or consumed locally — nothing silently drops. See [docs/concepts.md](apps/cli/docs/concepts.md#devices--hosts).
+**Hosts** (`agents hosts`) are git-synced dispatch targets in `agents.yaml`; **devices** (`agents devices`) are your Tailscale machines in a local registry. Both ride SSH and feed one host pool: devices appear in `agents hosts list` and capability routing without a second enrollment. On `--device` runs every `agents run` option is either forwarded (`--effort --env --timeout --loop …`), rejected loud (`--secrets` never crosses SSH implicitly), or consumed locally — nothing silently drops. See [docs/concepts.md](cli/docs/concepts.md#devices--hosts).
 
-Every `--device` command rides one multiplexed SSH engine, tuned for driving a fleet from a small laptop: the first call to a machine opens a control socket and every later call reuses it (no repeat TCP+auth handshake), connections carry keepalive so a dropped link dies in ~45 s instead of zombying, and following a remote run polls in a single round-trip per cycle. Measured against a Tailscale-relayed host: repeated calls **~6–7× faster**, dispatch readiness **~2×**, and the follow loop **~21× faster with 50% fewer local ssh spawns**. Design: [docs/ssh-transport.md](apps/cli/docs/ssh-transport.md) · reproduce: `node scripts/bench-ssh.mjs <host>`.
+Every `--device` command rides the shared SSH transport so host resolution,
+identity checks, environment forwarding, reconnect behavior, and multiplexing cannot
+drift between callers. See [fleet architecture](cli/docs/fleet.md).
 
 ---
 
@@ -736,7 +739,7 @@ agents teams status auth-feature    # Who's working, what they changed, what the
 
 Teammates run detached -- close your terminal, they keep working. Check in with `teams status`, glance at a teammate's summary with `teams logs <name>` (add `--full` for the raw output), clean up with `teams disband`.
 
-Team state is observable via `agents teams list --json` / `agents teams status --json` (compact by default; add `--verbose` for the full per-teammate shape). External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/observability.md](apps/cli/docs/observability.md).
+Team state is observable via `agents teams list --json` / `agents teams status --json` (compact by default; add `--verbose` for the full per-teammate shape). External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/observability.md](cli/docs/observability.md).
 
 ---
 
@@ -907,7 +910,9 @@ agents setup mine toggle jack --enable teams
 agents setup mine remove jack --purge
 ```
 
-Under the hood, `init` drops a pure pass-through shim in `~/.agents/.cache/shims/<name>` (already on `PATH`) that sets `AGENTS_BRAND` and forwards every argument to the same binary — nothing is copied or forked. The brand's config lives in `~/.agents/agents.yaml` (`brands.<name>`), so it rides `agents repo push/pull` across your fleet. Disabling a command hides it **only** under that brand; plain `agents` / `ag` keep every command. Curated skills/plugins/MCP ride a per-brand [resource profile](apps/cli/docs/profiles.md). Full reference: [Make it yours](apps/cli/docs/mine.md).
+Under the hood, `init` creates a pass-through shim that selects a brand configuration;
+it does not fork the execution engine. Curated resources still resolve through the
+ordinary [resource architecture](cli/docs/resources.md).
 
 > Branded builds are free for personal and commercial use alike. New versions ship under FSL-1.1-Apache-2.0: every user and company may use, modify, and redistribute; only offering agents-cli itself as a competing commercial product or service is barred, and each version automatically becomes Apache-2.0 two years after release.
 
@@ -921,15 +926,21 @@ Under the hood, `init` drops a pure pass-through shim in `~/.agents/.cache/shims
 
 Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.
 
+Each device declares its own browsers in its own `devices/<machine>/agents.yaml`.
+The fleet registry is the union of those files: a name declared by one device is
+identity-bearing (the daemon tunnels to that device); a name declared by several
+is fungible (use the local one). `--device` is only valid on `agents browser start`;
+later verbs resolve the device from the task.
+
 ```bash
 # First run: omit --profile and we auto-pick the first installed Chromium-family
 # browser. macOS prefers Chrome > Brave > Edge > Chromium > Comet; Linux prefers
 # Chrome > Chromium > Brave > Edge; Windows prefers Edge (always preinstalled) >
-# Chrome > Brave > Comet. The auto-picked profile is saved as "default" for later runs.
+# Chrome > Brave > Comet. The auto-picked profile is saved as "auto-chrome".
 export AGENTS_BROWSER_TASK=$(agents browser start --url https://app.example.com)
 
 # Or pin a named profile to a specific browser (chrome, comet, brave, chromium,
-# edge, or custom) when you want isolation from "default".
+# edge, or custom) when you want isolation from auto-detect.
 agents browser profiles create work --browser chrome
 # `start` writes the resolved name (e.g. `swift-crab-falcon-a3f92b1c`) to stdout
 # and human-friendly commentary to stderr, so $(...) capture stays clean.
@@ -993,7 +1004,10 @@ agents browser profiles create slack \
 
 ### Remote browsers
 
-Connect to browsers running anywhere — local, SSH tunnels, or cloud services:
+Identity-bearing names tunnel automatically: declare `comet-local` only on the
+machine that holds the logins, and every other box reaches it through the
+daemon. `--device` on `start` binds a task to a specific box (fungible names,
+or an explicit pick). Later verbs reject `--device`.
 
 ```bash
 # Local CDP (discovers WebSocket URL automatically)
@@ -1001,7 +1015,11 @@ agents browser profiles create local-debug \
   --browser chrome \
   --endpoint "http://localhost:9222"
 
-# SSH tunnel to a remote machine
+# Bind a task to a fleet device at start; later verbs resolve it from the task
+agents browser start --task post --device zion --url https://x.com/
+agents browser screenshot --task post
+
+# Explicit SSH endpoint, declared on the machine that owns the browser
 agents browser profiles create staging \
   --browser chrome \
   --endpoint "ssh://deploy@staging.example.com?port=9222"
@@ -1120,7 +1138,7 @@ agents routines add daily-digest \
   --schedule "0 9 * * 1-5" \
   --agent claude \
   --project-anchor agents-cli \
-  --cwd apps/cli \
+  --cwd cli \
   --prompt "Review yesterday's PRs and summarize key changes"
 
 agents routines list                   # All jobs + next run times
@@ -1152,7 +1170,7 @@ Jobs run sandboxed -- agents only see directories and tools you explicitly allow
 decides where the body runs. The reliability contract (execution anchor + `--cwd`,
 readiness that saves a blocked routine paused, and the `blocked`/`skipped` run
 statuses) is specified in
-[docs/specifications.md §Routine execution & readiness](apps/cli/docs/specifications.md#routine-execution--readiness);
+[docs/specifications.md §Routine execution & readiness](cli/docs/specifications.md#routine-execution--readiness);
 some of it is planned (RUSH-2290), and the section marks what is landed vs intended.
 
 ### Daemon
@@ -1232,8 +1250,13 @@ Sources: a command's stdout (`--watch` / `--poll`), an HTTP endpoint (`--poll-ht
 ## Share
 
 ```bash
-# Publish an HTML artifact to a public link on your own Cloudflare R2 (~$0).
+# Signed in? Just publish — no Cloudflare setup.
+agents auth login
+agents artifacts share plan.html --visibility unlisted      # → https://share.agents-cli.sh/<handle>/<slug>-<id>
+
+# Or provision your own Cloudflare R2 (~$0).
 agents artifacts setup                                      # once: provision bucket + Worker on your CF
+agents traces setup                                         # provision the private traces Worker + R2 bucket
 agents artifacts share plan.html --slug fleet --expire 30d  # → https://<base>/fleet
 agents artifacts share plan.html --label "Q3 fleet plan" --meta kind=plan   # human title + structured metadata
 agents artifacts share plan.html --json                     # URL object for plan-render hooks
@@ -1244,18 +1267,26 @@ agents artifacts unshare fleet                              # take a published l
 ```
 
 `agents artifacts share` closes the loop: an agent makes work (a plan, a viz, a report),
-publishes it, and you open the link to see it. `setup` reads a Cloudflare API token
-from your `cloudflare.com` secrets bundle (or `--token`), creates an R2 bucket, uploads
-a tiny Worker, and enables the free `*.workers.dev` subdomain (or maps `--domain
-share.example.com` when the token owns the zone). Writes are bearer-gated **through**
-the Worker (its R2 binding does the put, so the client needs no S3 keys); reads are
-**public**, so a link outlives the agent. R2 has zero egress + a 10 GB free tier, so
-this is effectively free.
+publishes it, and you open the link to see it. **Signed-in users** publish to the
+already-live managed endpoint (`share.agents-cli.sh/<handle>/…`) with the Phoenix session — no
+Cloudflare account, bucket, or write token — and `share status` / `list` / `revisions`
+/ `unshare` talk to that same endpoint. The handle is the local-part of the signed-in
+email (`muqsitnawaz@gmail.com` → `muqsitnawaz`); the page slug is readable plus a
+short view-id. HTML is stored as one object: local images are inlined, `file://` TOC
+links become in-page hashes, so the published page is actually viewable. `--visibility unlisted` (hidden aliases
+`--unlisted` / `--private`) is a capability URL: GET still works, the gallery hides it,
+and the Worker sends `X-Robots-Tag: noindex`. **BYO Cloudflare** remains: `setup` reads
+a Cloudflare API token from your `cloudflare.com` secrets bundle (or `--token`), creates
+an R2 bucket, uploads a tiny Worker, and enables the free `*.workers.dev` subdomain (or
+maps `--domain share.example.com` when the token owns the zone). Writes are bearer-gated
+**through** the Worker (Phoenix bearer or static `WRITE_TOKEN`); reads are **public**, so
+a link outlives the agent. R2 has zero egress + a 10 GB free tier, so BYO is still
+effectively free.
 
 **Fleet mode:** provision one endpoint, then every fleet / cloud / ephemeral agent
 publishes through it with a shared write token — `agents artifacts share join <baseUrl>` uses an
 existing endpoint with no provisioning. `--expire 30d|12h|<date>` auto-expires a link.
-`--json` emits `{ url, coverUrl, expiresAt, label, labelSource }` so plan-render automation can
+`--json` emits `{ url, coverUrl, expiresAt, visibility, unlisted?, label, labelSource }` so plan-render automation can
 publish the rendered HTML and post the returned link without scraping terminal text.
 
 **Every share carries provenance and a title.** Agent/session/host/repo/date are
@@ -1274,7 +1305,7 @@ full URL, `<user>/<slug>`, or a bare slug (resolved against your own namespace);
 targets at once are fine. It also deletes the sibling `<slug>.png` OG cover by default
 (`--keep-cover` opts out) and verifies the page actually 404s before reporting success —
 the Worker's delete is idempotent, so `{"ok":true}` alone is never proof.
-See [docs/share.md](apps/cli/docs/share.md).
+See the publication boundary in [observability](cli/docs/observability.md).
 
 ---
 
@@ -1323,9 +1354,9 @@ Two repos with the same shape, different roles:
 
 **Resource resolution:** When syncing resources (commands, skills, rules, hooks, MCP, permissions), the order is **project > user > system**. A `.agents/` directory at project root wins, then `~/.agents/`, then `~/.agents-system/`. Same-named resources higher in the chain override lower ones; everything else unions in. Run `agents view --merged` to see the effective skills, commands, MCP servers, hooks, rules, plugins, workflows, and subagents, with each row tagged by its winning layer.
 
-See [docs/concepts.md](apps/cli/docs/concepts.md) for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end.
+See [docs/concepts.md](cli/docs/concepts.md) for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end.
 
-Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents view` shows per-account quota/rate-limit data for installed agents, `agents config budget` shows cross-vendor spend caps and current spend-to-cap (and enforces pre-flight estimates + a hard-cap kill-switch on every run — see [docs/observability.md](apps/cli/docs/observability.md#budget-guardrails-agents-budget)), `agents import` adopts an existing unmanaged install, `agents trash` lists and restores soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows.
+Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents view` shows per-account quota/rate-limit data for installed agents, `agents config budget` shows cross-vendor spend caps and current spend-to-cap (and enforces pre-flight estimates + a hard-cap kill-switch on every run — see [docs/observability.md](cli/docs/observability.md#budget-guardrails-agents-budget)), `agents import` adopts an existing unmanaged install, `agents trash` lists and restores soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows.
 
 ---
 
@@ -1448,7 +1479,7 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 
 ## Compatibility
 
-Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](apps/cli/src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](apps/cli/src/lib/capabilities.ts). Full matrix also in [docs/concepts.md](apps/cli/docs/concepts.md).
+Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](cli/src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](cli/src/lib/capabilities.ts). Full matrix also in [docs/concepts.md](cli/docs/concepts.md).
 
 > **Gemini CLI is hard-deprecated.** Google retired it for free, Pro, and Ultra tiers on **June 18, 2026** (announced at Google I/O 2026); the `gemini` command no longer serves requests on those tiers. agi-cli keeps the legacy `gemini` id only so old sessions/config can still be read. `agents add gemini`, `agents import gemini`, and `agents sync gemini` fail and point to **Antigravity CLI** (`antigravity`), Google's official successor — see [the transition notice](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/).
 
@@ -1576,7 +1607,7 @@ Profiles (experimental — available by default). Works with LiteLLM Proxy, Olla
 
 ### Can I add support for a new agent?
 
-Agents are defined in [src/lib/agents.ts](apps/cli/src/lib/agents.ts) -- each is a config object declaring commands dir, rules file, and capabilities. PRs welcome.
+Agents are defined in [src/lib/agents.ts](cli/src/lib/agents.ts) -- each is a config object declaring commands dir, rules file, and capabilities. PRs welcome.
 
 ### What's the relationship to Phoenix Labs / Rush?
 
@@ -1588,20 +1619,23 @@ Agents are defined in [src/lib/agents.ts](apps/cli/src/lib/agents.ts) -- each is
 
 | Path | What |
 |---|---|
-| [`apps/cli`](apps/cli) | **The CLI** (this README) — version management, config sync, sessions, teams, cloud, browser, computer, secrets. |
-| [`apps/ext`](apps/ext) | **AGI EXT** — a VS Code extension that spawns agent terminals as tabs and adds the Fleet dashboard. A separate product with its own publish identity. |
+| [`cli`](cli) | **The CLI** (this README) — version management, config sync, sessions, teams, cloud, browser, computer, secrets. |
+| [phnx-labs/agi-ext](https://github.com/phnx-labs/agi-ext) | **AGI EXT** — the VS Code extension (agent terminals as tabs + the Fleet dashboard). Moved to its own repo (RUSH-3189); separate product, own publish identity. |
 | [`native/computer-mac`](native/computer-mac) · [`native/computer-win`](native/computer-win) | Native backends behind `agents computer` — Swift (macOS Accessibility + screen capture) and C#/.NET (Windows UI Automation). |
-| [`packages/session-tracker`](packages/session-tracker) | The `SessionStart` hook that writes live-session state **AGI EXT** reads back (`apps/ext/src/core/liveSession.ts`) — not the CLI, which reads transcripts. |
+| [`packages/session-tracker`](packages/session-tracker) | The `SessionStart` hook that writes live-session state **AGI EXT** reads back (agi-ext `src/core/liveSession.ts`) — not the CLI, which reads transcripts. |
 
 ## Contributing
 
 ```bash
 git clone https://github.com/phnx-labs/agi-cli
-cd agi-cli/apps/cli
+cd agi-cli/cli
 bun install && bun run build && bun test
 ```
 
-Commands in [`apps/cli/src/commands/`](apps/cli/src/commands/), libraries in [`apps/cli/src/lib/`](apps/cli/src/lib/), tests as `*.test.ts` under vitest. [CLAUDE.md](CLAUDE.md) has the full style guide. [docs/landscape.md](apps/cli/docs/landscape.md) covers the competitive landscape.
+Commands live in [`cli/src/commands/`](cli/src/commands/), libraries in
+[`cli/src/lib/`](cli/src/lib/), and tests sit beside their sources. [AGENTS.md](AGENTS.md)
+is the canonical engineering guide; [`cli/docs/README.md`](cli/docs/README.md) is the
+architecture index.
 
 ## License
 

package/dist/bootstrap.js

@@ -473,8 +473,10 @@ async function installResolvedPackage(metadata) {
     // getKeychainHelperPath() still repairs it on the next secret operation).
     if (process.platform === 'darwin') {
         try {
-            const { ensureKeychainHelperInstalled } = await import('./lib/secrets/install-helper.js');
-            ensureKeychainHelperInstalled({ forceReinstall: true });
+            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.

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

@@ -91,6 +91,7 @@ export declare const loadHumans: ModuleLoader;
 export declare const loadAccounts: ModuleLoader;
 export declare const loadDaemon: ModuleLoader;
 export declare const loadAuth: ModuleLoader;
+export declare const loadTraces: 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 loadHumans = async () => (await import('../commands/humans.js')).re
 export const loadAccounts = async () => (await import('../commands/accounts.js')).registerAccountsCommand;
 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;
 /**
  * Commands whose modules pull in the SQLite-backed session/cloud stack. They are
  * registered AFTER `applyGlobalHelpConventions` (mirroring main's order: help
@@ -211,6 +212,7 @@ export const COMMAND_LOADERS = {
     humans: [loadHumans],
     daemon: [loadDaemon],
     auth: [loadAuth],
+    traces: [loadTraces],
 };
 /**
  * Register every module in {@link COMMAND_LOADERS} onto one fresh program and

package/dist/commands/accounts.d.ts

@@ -1,5 +1,6 @@
 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 UnifiedAccount } from '../lib/account-registry.js';
 export declare function nativeIdentityFromSource(raw: string): Promise<{
@@ -26,10 +27,67 @@ type AttachTarget = {
  * `agent@version`, or a known harness id.
  */
 export declare function classifyAttachTarget(target: string): AttachTarget;
+/**
+ * Persist the attached setup-token to a per-version `.oauth_token` file so an
+ * INTERACTIVE Claude launch on a keychain-less Linux worker can authenticate from it.
+ * Headless runs inject the token via `buildExecEnv`, but an interactive launch defers to
+ * the per-version login (`claudeAdapter.applyExecConfigEnv`), and the shim's Linux fallback
+ * (`claudeAdapter.shimConfigEnvBash`) reads exactly this file. Without writing it, a
+ * freshly-attached setup-token was invisible to interactive runs on a worker. macOS keeps
+ * the credential in the keychain, so `resolveClaudeSetupToken` returns null there and this
+ * is a no-op off Linux.
+ */
+export declare function writeClaudeInteractiveOauthToken(target: AttachTarget, targetAgent: AgentId): void;
 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[];
+}[]): string;
+/** One labelable signed-in identity, folded across every version it is signed into. */
+export interface LabelIdentity {
+    identityKey: string;
+    email: string | null;
+    versions: string[];
+    isDefault: boolean;
+}
+/**
+ * Fold signed-in run candidates into distinct identities — the unit a label
+ * binds to. The same account signed into several versions is ONE row, so a
+ * multi-version single-account harness never demands a selector. Candidates
+ * with no stable identity (no accountKey, no email) are dropped: there is
+ * nothing durable for a label to bind to. Default-version identity first.
+ */
+export declare function groupLabelIdentities(candidates: Pick<RotateCandidate, 'version' | 'email' | 'accountKey'>[], defaultVersion: string | null): LabelIdentity[];
+export type LabelSelection = {
+    kind: 'selected';
+    identity: LabelIdentity;
+} | {
+    kind: 'ambiguous';
+    identities: LabelIdentity[];
+};
+/**
+ * Resolve which signed-in login a bare-harness `accounts label` call means.
+ * `collect` is injectable (the `resolveRunVersion` pattern) so tests drive the
+ * real selection path against fixture candidates.
+ */
+export declare function resolveLabelIdentity(agent: AgentId, accountSelector: string | undefined, collect?: typeof collectRunCandidates): Promise<LabelSelection>;
+/**
+ * Body of `accounts label`, exported with the injectable candidate collector
+ * so tests exercise everything but the TTY prompt itself.
+ */
+export declare function runAccountsLabel(source: string, label: string | undefined, opts: {
+    account?: string;
+}, collect?: typeof collectRunCandidates): Promise<void>;
 /** Named accounts that `set-default` / `switch` can pin for this harness. */
 export declare function listSwitchableAccounts(agent: AgentId): Promise<UnifiedAccount[]>;
 /**