@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/README.md

@@ -54,9 +54,10 @@ agents setup status                    # readiness for browser, computer, fleet,
 agents run claude "explain this repo"  # run any agent on your existing subscription
 ```
 
-`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.
+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).
 
@@ -224,8 +225,8 @@ Supports plan (read-only), edit, auto, and skip modes, effort levels, JSON outpu
 Treat `skip` as a last-resort escape hatch. In direct-exec runs (without `--acp`),
 agi-cli forwards the harness's native no-prompt flag; it does not add another
 safety layer. Prefer `auto` where it adds a safer automatic policy (smart classifier
-on Claude/Copilot, native high-auto mode on Droid, or interactive Kimi), or `edit`
-everywhere else. For headless Kimi, `edit`, `auto`, and `skip` all use the same
+on Claude/Copilot, never-prompt over a sandbox on Codex, native high-auto mode on
+Droid, or interactive Kimi), or `edit` everywhere else. For headless Kimi, `edit`, `auto`, and `skip` all use the same
 already-auto-approved `-p` behavior, so prefer `edit` rather than signaling a blanket
 bypass. Harnesses without a native bypass flag reject direct-exec `skip`.
 
@@ -247,11 +248,13 @@ permission requests at the ACP protocol layer: it selects `allow_always` when of
 otherwise the first permission option offered by the server. The same last-resort
 warning applies.
 
-Codex has no native smart-classifier mode, so `agents run codex --mode auto` resolves
-to sandboxed `edit` and can still prompt. When `--mode` is omitted for Codex, the same
-safe writable mode is used: the workspace, `~/.agents`, and regenerable toolchain caches
-are writable; network access is enabled; and approvals are requested on demand. An
-explicit `--mode plan` keeps the filesystem read-only while leaving network access on.
+Codex has three managed permission profiles rather than a smart classifier. `edit`
+and `auto` share one sandbox — the workspace, `~/.agents`, and regenerable toolchain
+caches are writable, and network access is enabled — and differ only in approvals:
+`edit` requests them on demand, while `auto` never prompts, so a sandbox-denied
+command fails and the agent works around it instead of stopping on a dialog nobody
+is watching. When `--mode` is omitted for Codex, `edit` is used. An explicit
+`--mode plan` keeps the filesystem read-only while leaving network access on.
 `agents run codex --mode skip` is different:
 it bypasses approvals **and** removes the sandbox. `full` remains an alias for `skip`,
 but new scripts should use the explicit `skip` name.
@@ -295,6 +298,11 @@ agents sessions render a1b2c3d4 -o session.md
 # Or publish it as a link in one step (unlisted + redacted by default)
 agents sessions share a1b2c3d4
 
+# Visualize a session as a trajectory -- tool-call waterfall, timing, stalls, errors
+agents trace a1b2c3d4                    # opens the HTML (a person at a terminal)
+agents trace a1b2c3d4 --text --errors-only   # compact text an agent reads in-context
+agents sessions trace a1b2c3d4 --json    # the versioned sessions-trace envelope
+
 # Just the last 3 turns, user messages only
 agents sessions a1b2c3d4 --last 3 --include user
 
@@ -329,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
 
@@ -434,6 +442,8 @@ agents feed --flat                  # one row per agent (legacy)
 agents feed --device mac-mini         # scope the view to one or more hosts
 agents feed --local                 # skip the SSH fan-out
 agents feed --json                  # blocks stamped with their outcome key
+agents feed watch --json            # versioned agents + attention + activity NDJSON
+agents feed answer <key> --choice 0 # first answer wins; route over the recorded reply rail
 agents feed post --title "Halfway done" "CI green, watching merge"  # title + body
 ```
 
@@ -483,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.
 
 ---
 
@@ -600,7 +610,7 @@ agents hosts check gpu-box              # reachable? which agi-cli version?
 
 # Run there instead of locally
 agents run claude --device gpu-box "profile this build"   # headless: follows live by default
-agents run claude --device gpu-box                         # no prompt → interactive TTY over SSH (tmux-backed)
+agents run claude --device gpu-box                         # no prompt → direct interactive TTY over SSH
 agents accounts sync work --device gpu-box               # portable provider account only; native OAuth stays local
 agents run claude --device auto "…"                      # affinity-pick host from 14d usage (harness stays claude)
 agents run claude --device auto "…"                        # same — auto is a host value, not a harness name
@@ -638,10 +648,12 @@ agents devices sync                     # ingest `tailscale status`
 agents devices ignore ipad              # sync the dismissal via agents.yaml fleet.discovery
 agents repo push user                    # carry device decisions to the other machines
 agents repo pull user                    # pull and reconcile them into this machine's registry
-agents devices list                     # fleet + headroom: load, mem, idle/busy — which box has room (cache-first)
+agents devices list                     # spec (cores/RAM/disk) + load/mem/disk + headroom + role + description
 agents devices list --live              # force a live probe of every device (alias of --refresh)
-agents devices list --full              # add per-device cores and free/total RAM
+agents devices list --full              # add per-device free/total RAM detail
 agents devices list --no-stats          # instant: names/addresses only, skip the probe
+agents devices describe mac-mini "signing + notarize box"   # one-line purpose, synced + shown in the list
+agents devices ignored                  # dismissed nodes — when, and which machine dismissed them
 agents devices config zion interactive.host zion   # the device agents show YOU artifacts on (★ in the list)
 agents devices config mac-mini agents.max-concurrent 4   # per-device settings (tracked devices/<name>/agents.yaml)
 agents devices config mac-mini scheduler.enabled off     # bare `devices config <name>` opens a settings menu (TTY)
@@ -698,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).
 
 ---
 
@@ -725,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).
 
 ---
 
@@ -814,7 +828,7 @@ tools:
 ---
 ```
 
-Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit`, or `--mode auto` on Claude Code and GitHub Copilot. Reserve `--mode skip` (legacy alias: `full`) for last-resort bypasses. `agents run` defaults to `--mode plan` for other harnesses; Codex defaults to its safe writable profile. An explicit Codex `--mode plan` is read-only with network access.
+Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit`, or `--mode auto` on Claude Code, GitHub Copilot, and Codex. Reserve `--mode skip` (legacy alias: `full`) for last-resort bypasses. `agents run` defaults to `--mode plan` for other harnesses; Codex defaults to its safe writable profile. An explicit Codex `--mode plan` is read-only with network access.
 
 Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` overrides a same-named workflow in `~/.agents/workflows/`. Commit project workflows with your repo so teammates get the same pipeline.
 
@@ -896,9 +910,11 @@ 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).
 
-> Personal use is free and Apache-2.0. Redistributing a branded build commercially will require a license in a future release.
+> 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.
 
 ---
 
@@ -910,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.
@@ -982,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)
@@ -990,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"
@@ -1005,7 +1034,7 @@ agents browser profiles create cloud \
 
 ## Sign in
 
-`agents auth` signs this machine in to **Phoenix ID** — the Phoenix Labs account layer that spaces and plan tiers hang off. Sign-in is Google-only and runs a device-code flow: the CLI shows a code, your browser confirms it, and the CLI picks the session up.
+Signing in is **optional**. Every local feature — `agents run`, sessions, teams, fleet dispatch, secrets, browser, computer — works with no account. The one thing an account unlocks is **team spaces**, the hosted surface under `agents auth space`. `agents auth` signs this machine in to **Phoenix ID**, the Phoenix Labs account layer behind team spaces. Sign-in is Google-only and runs a device-code flow: the CLI shows a code, your browser confirms it, and the CLI picks the session up.
 
 ```bash
 agents auth login                        # shows a code, opens a Phoenix-branded page
@@ -1109,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
@@ -1141,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
@@ -1221,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
@@ -1233,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
@@ -1263,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).
 
 ---
 
@@ -1312,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 usage` shows available 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.
 
 ---
 
@@ -1437,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/).
 
@@ -1499,7 +1541,7 @@ Claude Code, Codex CLI, Antigravity, Grok Build, and others each have their own
 
 ### Is it free?
 
-Yes. This developer tool is entirely free because we believe developers should have the best tools — fast and robust — so they can create the best products for their users.
+Yes — every feature, with no account and no signup. `agents run`, sessions, teams, fleet dispatch, secrets, browser, and computer automation all work the moment you install. The optional `agents auth login` exists only to unlock hosted team spaces (`agents auth space`); there are no paid tiers. This developer tool is entirely free because we believe developers should have the best tools — fast and robust — so they can create the best products for their users.
 
 ### Is this like `nvm` / `mise` / `asdf` for AI agents?
 
@@ -1533,7 +1575,9 @@ 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.
 
-Interactive tmux-backed runs require tmux 3.2 or newer.
+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
+focus`; tmux-backed runs require tmux 3.2 or newer.
 
 ### Do I need Node.js?
 
@@ -1563,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?
 
@@ -1575,21 +1619,24 @@ 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
 
-Apache-2.0 -- see [LICENSE](./LICENSE).
+FSL-1.1-Apache-2.0 -- see [LICENSE](./LICENSE). Free for every user and company to use, modify, and redistribute; the only barred use is offering agents-cli itself as a competing commercial product or service. Each version automatically becomes Apache-2.0 two years after its release.

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

@@ -63,8 +63,8 @@ export declare const loadMenubar: ModuleLoader;
 export declare const loadSync: ModuleLoader;
 export declare const loadRefreshRules: ModuleLoader;
 export declare const loadFactory: ModuleLoader;
-export declare const loadUsage: ModuleLoader;
 export declare const loadInsights: ModuleLoader;
+export declare const loadTrace: ModuleLoader;
 export declare const loadPerf: ModuleLoader;
 export declare const loadPty: ModuleLoader;
 export declare const loadTmux: ModuleLoader;
@@ -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

@@ -65,8 +65,8 @@ export const loadMenubar = async () => (await import('../commands/menubar.js')).
 export const loadSync = async () => (await import('../commands/sync.js')).registerSyncCommand;
 export const loadRefreshRules = async () => (await import('../commands/refresh-rules.js')).registerRefreshRulesCommand;
 export const loadFactory = async () => (await import('../commands/factory.js')).registerFactoryCommands;
-export const loadUsage = async () => (await import('../commands/usage.js')).registerUsageCommand;
 export const loadInsights = async () => (await import('../commands/insights.js')).registerInsightsCommand;
+export const loadTrace = async () => (await import('../commands/sessions-trace.js')).registerTraceCommand;
 export const loadPerf = async () => (await import('../commands/perf.js')).registerPerfCommand;
 export const loadPty = async () => (await import('../commands/pty.js')).registerPtyCommands;
 export const loadTmux = async () => (await import('../commands/tmux.js')).registerTmuxCommands;
@@ -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
@@ -172,8 +173,10 @@ export const COMMAND_LOADERS = {
     sync: [loadSync],
     'refresh-rules': [loadRefreshRules],
     factory: [loadFactory],
-    usage: [loadUsage],
     insights: [loadInsights],
+    // `agents trace` is a top-level alias of `agents sessions trace` (precedent:
+    // `agents insights` aliases `agents sessions insights`). One implementation.
+    trace: [loadTrace],
     perf: [loadPerf],
     pty: [loadPty],
     tmux: [loadTmux],
@@ -209,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[]>;
 /**