diff --git a/Cargo.lock b/Cargo.lock
index 4fc58110..8315bf9f 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -7,8 +7,10 @@ name = "actual-cli"
 version = "0.2.0"
 dependencies = [
  "anyhow",
+ "argon2",
  "assert_cmd",
  "base64",
+ "chacha20poly1305",
  "chrono",
  "clap",
  "console",
@@ -20,6 +22,7 @@ dependencies = [
  "glob",
  "ignore",
  "indicatif",
+ "keyring",
  "mockito",
  "open",
  "predicates",
@@ -66,6 +69,16 @@ version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
 
+[[package]]
+name = "aead"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
+dependencies = [
+ "crypto-common",
+ "generic-array",
+]
+
 [[package]]
 name = "aes"
 version = "0.8.4"
@@ -166,6 +179,18 @@ dependencies = [
  "derive_arbitrary",
 ]
 
+[[package]]
+name = "argon2"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
+dependencies = [
+ "base64ct",
+ "blake2",
+ "cpufeatures",
+ "password-hash",
+]
+
 [[package]]
 name = "arrayvec"
 version = "0.7.6"
@@ -224,6 +249,12 @@ version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
+[[package]]
+name = "base64ct"
+version = "1.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
+
 [[package]]
 name = "bit-set"
 version = "0.5.3"
@@ -251,6 +282,15 @@ version = "2.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
 
+[[package]]
+name = "blake2"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+dependencies = [
+ "digest",
+]
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -359,6 +399,30 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
 
+[[package]]
+name = "chacha20"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818"
+dependencies = [
+ "cfg-if",
+ "cipher",
+ "cpufeatures",
+]
+
+[[package]]
+name = "chacha20poly1305"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10cd79432192d1c0f4e1a0fef9527696cc039165d729fb41b3f4f4f354c2dc35"
+dependencies = [
+ "aead",
+ "chacha20",
+ "cipher",
+ "poly1305",
+ "zeroize",
+]
+
 [[package]]
 name = "chrono"
 version = "0.4.44"
@@ -403,6 +467,7 @@ checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
  "crypto-common",
  "inout",
+ "zeroize",
 ]
 
 [[package]]
@@ -521,6 +586,26 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "core-foundation"
+version = "0.9.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91e195e091a93c46f7102ec7818a2aa394e1e1771c3ab4825963fa03e45afb8f"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "core-foundation-sys"
 version = "0.8.7"
@@ -628,6 +713,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
 dependencies = [
  "generic-array",
+ "rand_core 0.6.4",
  "typenum",
 ]
 
@@ -1729,6 +1815,21 @@ dependencies = [
  "thiserror 2.0.18",
 ]
 
+[[package]]
+name = "keyring"
+version = "3.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eebcc3aff044e5944a8fbaf69eb277d11986064cba30c468730e8b9909fb551c"
+dependencies = [
+ "byteorder",
+ "linux-keyutils",
+ "log",
+ "security-framework 2.11.1",
+ "security-framework 3.7.0",
+ "windows-sys 0.60.2",
+ "zeroize",
+]
+
 [[package]]
 name = "lab"
 version = "0.11.0"
@@ -1788,6 +1889,16 @@ dependencies = [
  "bitflags 2.11.0",
 ]
 
+[[package]]
+name = "linux-keyutils"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83270a18e9f90d0707c41e9f35efada77b64c0e6f3f1810e71c8368a864d5590"
+dependencies = [
+ "bitflags 2.11.0",
+ "libc",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -2066,6 +2177,12 @@ version = "1.70.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 
+[[package]]
+name = "opaque-debug"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
+
 [[package]]
 name = "open"
 version = "5.3.5"
@@ -2134,6 +2251,17 @@ dependencies = [
  "regex",
 ]
 
+[[package]]
+name = "password-hash"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
+dependencies = [
+ "base64ct",
+ "rand_core 0.6.4",
+ "subtle",
+]
+
 [[package]]
 name = "pathdiff"
 version = "0.2.3"
@@ -2282,6 +2410,17 @@ dependencies = [
  "miniz_oxide",
 ]
 
+[[package]]
+name = "poly1305"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf"
+dependencies = [
+ "cpufeatures",
+ "opaque-debug",
+ "universal-hash",
+]
+
 [[package]]
 name = "portable-atomic"
 version = "1.13.1"
@@ -2819,6 +2958,42 @@ version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
+[[package]]
+name = "security-framework"
+version = "2.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "897b2245f0b511c87893af39b033e5ca9cce68824c4d7e7630b5a1d339658d02"
+dependencies = [
+ "bitflags 2.11.0",
+ "core-foundation 0.9.4",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags 2.11.0",
+ "core-foundation 0.10.1",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "semver"
 version = "1.0.27"
@@ -3900,6 +4075,16 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "81e544489bf3d8ef66c953931f56617f423cd4b5494be343d9b9d3dda037b9a3"
 
+[[package]]
+name = "universal-hash"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
+dependencies = [
+ "crypto-common",
+ "subtle",
+]
+
 [[package]]
 name = "unsafe-libyaml"
 version = "0.2.11"
diff --git a/Cargo.toml b/Cargo.toml
index f3f0e443..271c2083 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -58,6 +58,24 @@ glob = "0.3"
 # Crypto
 sha2 = "0.10"
 base64 = "0.22"
+# Scoped personal-access-token storage: OS keychain (primary) with an
+# AEAD-encrypted-file fallback for headless Linux/CI where no OS keychain is
+# available. `keyring` is the portable keychain abstraction; chacha20poly1305 +
+# argon2 protect the fallback file at rest.
+#
+# The Linux backend is `linux-native` (kernel keyutils), NOT `sync-secret-service`.
+# The Secret Service backend links the system `libdbus` at build time through
+# pkg-config, so it fails to *compile* on a headless / CI Linux host that lacks
+# `libdbus-1-dev` — a harder failure than a runtime missing-daemon error. keyutils
+# is pure syscalls: no build-time system dependency, no D-Bus daemon, so it builds
+# everywhere and works headless. See docs/AGENT_AUTH.md for the finding.
+keyring = { version = "3", default-features = false, features = [
+    "apple-native",
+    "windows-native",
+    "linux-native",
+] }
+chacha20poly1305 = "0.10"
+argon2 = "0.5"
 
 # Async utilities
 futures = "0.3"
diff --git a/README.md b/README.md
index 181586d6..1190ffd8 100644
--- a/README.md
+++ b/README.md
@@ -122,6 +122,7 @@ you've written yourself.
 actual adr-bot        # analyze repo & write AI context files
 actual status         # check output file state (managed markers, staleness)
 actual auth           # verify authentication
+actual auth create-token  # mint a scoped token for CI / agents (prototype)
 actual config show    # view current configuration
 actual config set     # set a config value
 actual config path    # print config file location
@@ -130,6 +131,10 @@ actual models         # list known model names grouped by runner
 actual cache clear    # clear local analysis and tailoring caches
 ```
 
+For non-interactive (CI / agent) authentication with scoped access tokens, see
+[Agent authentication](docs/AGENT_AUTH.md). It also covers the
+dedicated-token-per-agent and never-in-prompt rules agents must follow.
+
 ## Configuration
 
 Config lives at `~/.actualai/actual/config.yaml` and is created automatically
diff --git a/docs/AGENT_AUTH.md b/docs/AGENT_AUTH.md
new file mode 100644
index 00000000..6f3fd753
--- /dev/null
+++ b/docs/AGENT_AUTH.md
@@ -0,0 +1,181 @@
+# Scoped access tokens for non-interactive use
+
+`actual login` signs you in through the browser. That's fine for a person at a
+keyboard. A CI job or an autonomous agent has no browser to click through,
+though, and that's the gap `actual auth create-token` closes: it mints a
+**scoped personal access token** (PAT) from your existing login session, so
+headless callers authenticate without one.
+
+> **Status: prototype.** This command is a proof of concept. The issuance
+> endpoint it calls is being finalized on the server; the CLI is built against
+> the documented contract and is repointed with a single flag or environment
+> variable once the endpoint ships. See [Endpoint](#endpoint) below.
+
+## Mint a token
+
+```console
+$ actual login                       # once, interactively, in a browser
+$ actual auth create-token --name ci-deploy --scopes adr:query,adr:review
+✔ Created scoped access token "ci-deploy"
+  Token id:    tok_9f3c
+  Scopes:      adr:query adr:review
+  Stored in:   OS keychain
+
+Your token is shown once below. Copy it now:
+
+actl_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+Keep this secret safe:
+  • Use a DEDICATED token per agent so actions are attributable and
+    individually revocable; never reuse your interactive login session.
+  • NEVER paste it into a prompt, commit it, or echo it to logs/history.
+  • For CI / non-interactive use, pass it via the ACTUAL_TOKEN env var.
+```
+
+The raw `actl_pat_…` value is printed **once**, to stdout, on its own line, so
+`TOKEN=$(actual auth create-token …)` captures just the secret. After that it
+lives only behind the OS keychain, or the encrypted-file fallback described
+below. It never reaches a log. Copy it now, because there's no second chance to
+read it back out in the clear.
+
+`--name` is required and `--scopes` takes a comma- or space-separated list.
+
+## Two rules for agents
+
+These two rules aren't optional hardening. They're the difference between a
+credential you can reason about and one you can't.
+
+### 1. A dedicated token per agent
+
+Mint a **separate** token for each agent instance, named after that agent
+(`--name <agent>`). Never hand an agent the human's interactive login session.
+
+One token per agent buys two things. Every action an agent takes is attributable
+to that agent's token rather than to a shared identity. And when one agent
+misbehaves or its host is compromised, you revoke that single token without
+disturbing every other agent and every human session.
+
+### 2. The token never enters the model's context
+
+A PAT lives in exactly one of two places. Those are the OS keychain, or the
+`ACTUAL_TOKEN` environment variable for a non-interactive run. It must **never**
+appear in:
+
+- an agent's prompt or conversation context,
+- the shell history,
+- a command-line argument that other processes can read,
+- a log line or an error report.
+
+The failure mode this guards against is specific to agents. An agent reads
+untrusted input: a web page, a file, a tool result. A prompt-injection payload
+hidden in that input can instruct the agent to exfiltrate any secret currently
+in its context. A token that is never in the context cannot be exfiltrated that
+way. Keep the secret in the keychain, or in an environment variable the model
+does not read, and that attack has nothing to reach.
+
+## Non-interactive use
+
+A headless caller resolves its token in this order:
+
+1. the `ACTUAL_TOKEN` environment variable, which is the CI path and needs no
+   storage;
+2. the OS keychain;
+3. the encrypted-file fallback.
+
+```console
+# CI: inject the secret as a masked environment variable, never echoed.
+$ export ACTUAL_TOKEN="actl_pat_…"     # from your CI secret store
+$ actual advisor "why is the build failing?"
+```
+
+In CI, pass the token through the platform's secret store as `ACTUAL_TOKEN`. Do
+not re-mint a token on every run, and do not write it to a file the job logs.
+
+## Storage
+
+```mermaid
+flowchart TD
+    A[create-token mints actl_pat_] --> B{ACTUAL_TOKEN_STORE}
+    B -->|auto default| C[Try OS keychain]
+    B -->|keyring| C
+    B -->|file| F[Encrypted file]
+    C -->|available| D[Stored in keychain]
+    C -->|unavailable, e.g. headless Linux| E{ACTUAL_TOKEN_PASSPHRASE set?}
+    E -->|yes| F
+    E -->|no| G[Error: configure a fallback or use ACTUAL_TOKEN]
+    F --> H[Argon2id key + XChaCha20-Poly1305 AEAD, 0600 file]
+```
+
+The primary store is the OS keychain (macOS Keychain, Windows Credential
+Manager, or the Linux kernel keyutils keyring), reached through the portable
+[`keyring`](https://crates.io/crates/keyring) crate.
+
+Where no keychain is available, an **encrypted-file fallback** keeps the token at
+rest under the config directory. The file is sealed with XChaCha20-Poly1305,
+keyed by Argon2id over a passphrase read from `ACTUAL_TOKEN_PASSPHRASE`, and
+written `0600`. No passphrase, no fallback. The CLI refuses rather than write
+anything weaker, so a token is never stored in a form softer than the keychain.
+
+| Environment variable | Purpose |
+| --- | --- |
+| `ACTUAL_TOKEN` | A ready-to-use token for a non-interactive run; wins over stored credentials. |
+| `ACTUAL_TOKEN_STORE` | Backend select: `auto` (default), `keyring`, or `file`. |
+| `ACTUAL_TOKEN_PASSPHRASE` | Passphrase that seals the encrypted-file fallback. |
+
+## Headless-storage finding
+
+The question this prototype set out to answer: does the keychain library degrade
+gracefully on a headless Linux box or CI runner with no desktop keyring?
+
+The first cut used the `keyring` crate's **Secret Service** backend
+(`sync-secret-service`), and the finding was sharper than expected. Secret
+Service does not fail gracefully at runtime here; it fails at **build time**.
+That backend links the system `libdbus` through `pkg-config`, so a host without
+`libdbus-1-dev` cannot compile the CLI at all. On stock Linux CI runners every
+job went red on `The system library dbus-1 required by crate libdbus-sys was not
+found`, across build, lint, test, and coverage alike. A missing runtime daemon
+is recoverable. A binary that never builds is not.
+
+The fix is to pick a Linux backend with no build-time system dependency. This
+CLI now uses `linux-native`, the kernel **keyutils** keyring, reached through raw
+syscalls: no `libdbus`, no `pkg-config`, no D-Bus daemon. It compiles on any
+Linux, including a bare CI container, and it stores secrets headless without a
+desktop session. macOS and Windows keep their native keychains (`apple-native`,
+`windows-native`), which never had the problem.
+
+Runtime degradation is still handled explicitly. In the default `auto` mode a
+keychain error routes to the encrypted-file store **when a passphrase is
+configured**, and otherwise fails loudly with a message pointing at
+`ACTUAL_TOKEN` or `ACTUAL_TOKEN_PASSPHRASE`. The CLI never invents a weaker store
+behind your back. Silent degradation would leave a token written somewhere
+unprotected, and that is the outcome worth avoiding.
+
+One property of keyutils is worth knowing. Kernel keyrings are scoped to a
+session or the persistent per-user keyring, so a secret there is less durable
+across reboots than a Secret Service entry on a desktop. For durable
+non-interactive use that does not matter, because the recommended paths avoid the
+OS keychain entirely:
+
+- **CI**: pass `ACTUAL_TOKEN` from the platform's secret store. Nothing is
+  written to disk.
+- **Headless Linux that must persist a token**: set `ACTUAL_TOKEN_PASSPHRASE` to
+  enable the encrypted-file fallback, which survives reboots at `0600`.
+- **Interactive desktop** (macOS, Windows, Linux with keyutils): the OS keychain
+  is used with no extra configuration.
+
+### Prototype limitations
+
+- The endpoint contract is provisional; see below.
+- The encrypted-file fallback derives its key from a passphrase. Treat that
+  passphrase as a secret of the same weight as the token, and supply a
+  high-entropy value (the Argon2id work factor slows brute force but cannot
+  rescue a guessable passphrase).
+
+## Endpoint
+
+`create-token` calls `POST <base>/api/oauth/tokens` with the login session token
+as the bearer, and reads back the minted `actl_pat_…`. The base URL is resolved
+from `--api-url`, then the `ACTUAL_API_URL` environment variable, then the
+api-service default, so a local mock or a future production path needs no code
+change. It isn't final yet. Until the server endpoint ships, treat the exact
+path and payload as provisional.
diff --git a/src/auth/mod.rs b/src/auth/mod.rs
index afa2adfd..5a737178 100644
--- a/src/auth/mod.rs
+++ b/src/auth/mod.rs
@@ -11,7 +11,9 @@
 
 pub mod loopback;
 pub mod oauth;
+pub mod pat;
 pub mod pkce;
 pub mod store;
+pub mod token_store;
 
 pub use store::StoredCredentials;
diff --git a/src/auth/oauth.rs b/src/auth/oauth.rs
index 564518a6..34a5bcee 100644
--- a/src/auth/oauth.rs
+++ b/src/auth/oauth.rs
@@ -141,7 +141,10 @@ pub fn build_authorize_url(
 /// Build an HTTP client for the auth server. Enforces HTTPS for non-loopback
 /// URLs so tokens are never sent in clear text (loopback `http://` is allowed
 /// for the local mock).
-fn build_http_client(base_url: &str) -> Result<reqwest::Client, ActualError> {
+///
+/// Shared with [`crate::auth::pat`], whose token-issuance call carries the same
+/// "never send a bearer over clear-text http" requirement.
+pub(crate) fn build_http_client(base_url: &str) -> Result<reqwest::Client, ActualError> {
     let is_localhost = base_url.starts_with("http://localhost")
         || base_url.starts_with("http://127.0.0.1")
         || base_url.starts_with("http://[::1]");
diff --git a/src/auth/pat.rs b/src/auth/pat.rs
new file mode 100644
index 00000000..4cdfbfe0
--- /dev/null
+++ b/src/auth/pat.rs
@@ -0,0 +1,289 @@
+//! Scoped personal access token (PAT) issuance against the Actual AI platform.
+//!
+//! `actual auth create-token` mints a PAT by calling the authenticated
+//! issuance endpoint with the user's existing `actual login` session token as
+//! the bearer — no second browser dance, the established session *is* the
+//! authentication for issuance. The endpoint returns the raw `actl_pat_…`
+//! exactly once; the CLI prints it once and otherwise keeps it only behind the
+//! keychain / encrypted-file store (see [`crate::auth::token_store`]).
+//!
+//! ## Endpoint contract (developed against; confirm against the backend)
+//!
+//! The backend issuance endpoint is still landing, so this module is written
+//! against the documented contract and is trivially repointed once the server
+//! ships:
+//!
+//! - `POST <base>/api/oauth/tokens`
+//! - `Authorization: Bearer <session access token>`
+//! - request body: `{ "name": "<label>", "scopes": ["adr:query", …] }`
+//! - response body: `{ "token": "actl_pat_…", "id": …, "name": …, "scopes":
+//!   […], "created_at": …, "expires_at": … }` — the raw `token` is returned
+//!   exactly once.
+//!
+//! `<base>` is resolved by the command layer (the `--api-url` flag, the
+//! `ACTUAL_API_URL` env var, or the api-service default), so steering the call
+//! at a local mock or a future production path needs no code change here.
+
+use serde::{Deserialize, Serialize};
+
+use crate::auth::oauth::build_http_client;
+use crate::error::ActualError;
+
+/// Opaque-token prefix. Chosen so secret-scanning can spot a leaked PAT, and
+/// asserted on the issuance response so a malformed/foreign token is rejected.
+pub const PAT_PREFIX: &str = "actl_pat_";
+
+/// Path of the authenticated issuance endpoint, appended to the resolved base.
+pub const ISSUANCE_PATH: &str = "/api/oauth/tokens";
+
+/// Request body for token issuance.
+#[derive(Debug, Serialize)]
+struct IssueTokenRequest {
+    name: String,
+    scopes: Vec<String>,
+}
+
+/// Issuance response. Only `token` is required; the metadata fields are
+/// surfaced when the server provides them.
+#[derive(Deserialize)]
+struct IssueTokenResponse {
+    token: String,
+    #[serde(default)]
+    id: Option<String>,
+    #[serde(default)]
+    name: Option<String>,
+    #[serde(default)]
+    scopes: Option<Vec<String>>,
+    #[serde(default)]
+    created_at: Option<String>,
+    #[serde(default)]
+    expires_at: Option<String>,
+}
+
+/// A freshly minted PAT plus its non-secret metadata.
+///
+/// The [`std::fmt::Debug`] impl redacts the raw token so it never reaches a log
+/// line, a panic message, or `{:?}` formatting.
+#[derive(Clone)]
+pub struct IssuedToken {
+    /// The raw `actl_pat_…` secret. **Sensitive — shown once, never logged.**
+    pub token: String,
+    /// Server-assigned token id, when provided.
+    pub id: Option<String>,
+    /// The credential label echoed back by the server, when provided.
+    pub name: Option<String>,
+    /// Granted scopes echoed back by the server.
+    pub scopes: Vec<String>,
+    /// Creation timestamp, when provided.
+    pub created_at: Option<String>,
+    /// Expiry timestamp, when provided.
+    pub expires_at: Option<String>,
+}
+
+impl std::fmt::Debug for IssuedToken {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("IssuedToken")
+            .field("token", &"<redacted>")
+            .field("id", &self.id)
+            .field("name", &self.name)
+            .field("scopes", &self.scopes)
+            .field("created_at", &self.created_at)
+            .field("expires_at", &self.expires_at)
+            .finish()
+    }
+}
+
+/// Map an unsuccessful issuance response to an [`ActualError`]. The body is an
+/// error payload (not a secret); it is truncated and surfaced for diagnosis.
+async fn issuance_error(response: reqwest::Response) -> ActualError {
+    let status = response.status();
+    let body = response.text().await.unwrap_or_default();
+    let truncated: String = body.chars().take(2048).collect();
+    ActualError::ApiError(format!(
+        "Token issuance failed (HTTP {status}): {truncated}"
+    ))
+}
+
+/// Mint a PAT named `name` with `scopes`, authenticating with `access_token`
+/// (the user's `actual login` session bearer) against `base_url`.
+///
+/// On success the raw token is validated to carry the [`PAT_PREFIX`] and
+/// returned in [`IssuedToken`]. The access token and the minted token are never
+/// logged.
+pub async fn issue(
+    base_url: &str,
+    access_token: &str,
+    name: &str,
+    scopes: &[String],
+) -> Result<IssuedToken, ActualError> {
+    let base = base_url.trim_end_matches('/');
+    let http = build_http_client(base)?;
+    let url = format!("{base}{ISSUANCE_PATH}");
+
+    let request = IssueTokenRequest {
+        name: name.to_string(),
+        scopes: scopes.to_vec(),
+    };
+
+    let response = http
+        .post(&url)
+        .bearer_auth(access_token)
+        .json(&request)
+        .send()
+        .await
+        .map_err(|e| ActualError::ApiError(format!("Token issuance request failed: {e}")))?;
+
+    if !response.status().is_success() {
+        return Err(issuance_error(response).await);
+    }
+
+    let body: IssueTokenResponse = response
+        .json()
+        .await
+        .map_err(|e| ActualError::ApiError(format!("Failed to parse issuance response: {e}")))?;
+
+    if !body.token.starts_with(PAT_PREFIX) {
+        return Err(ActualError::ApiError(format!(
+            "Issuance endpoint returned a token without the expected `{PAT_PREFIX}` prefix"
+        )));
+    }
+
+    Ok(IssuedToken {
+        token: body.token,
+        id: body.id,
+        name: body.name,
+        scopes: body.scopes.unwrap_or_default(),
+        created_at: body.created_at,
+        expires_at: body.expires_at,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn scopes() -> Vec<String> {
+        vec!["adr:query".to_string(), "adr:review".to_string()]
+    }
+
+    #[tokio::test]
+    async fn test_issue_success() {
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", ISSUANCE_PATH)
+            .match_header("authorization", "Bearer session-token-abc")
+            .match_body(mockito::Matcher::PartialJsonString(
+                r#"{"name":"ci-agent","scopes":["adr:query","adr:review"]}"#.to_string(),
+            ))
+            .with_status(201)
+            .with_header("content-type", "application/json")
+            .with_body(
+                r#"{"token":"actl_pat_abc123","id":"tok_1","name":"ci-agent","scopes":["adr:query","adr:review"],"created_at":"2026-06-30T00:00:00Z"}"#,
+            )
+            .create_async()
+            .await;
+
+        let issued = issue(&server.url(), "session-token-abc", "ci-agent", &scopes())
+            .await
+            .unwrap();
+        assert_eq!(issued.token, "actl_pat_abc123");
+        assert_eq!(issued.id.as_deref(), Some("tok_1"));
+        assert_eq!(issued.name.as_deref(), Some("ci-agent"));
+        assert_eq!(issued.scopes, vec!["adr:query", "adr:review"]);
+        mock.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn test_issue_minimal_response() {
+        // Only `token` returned; metadata absent.
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", ISSUANCE_PATH)
+            .with_status(200)
+            .with_header("content-type", "application/json")
+            .with_body(r#"{"token":"actl_pat_minimal"}"#)
+            .create_async()
+            .await;
+
+        let issued = issue(&server.url(), "tok", "name", &scopes())
+            .await
+            .unwrap();
+        assert_eq!(issued.token, "actl_pat_minimal");
+        assert!(issued.id.is_none());
+        assert!(issued.scopes.is_empty());
+        mock.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn test_issue_rejects_token_without_prefix() {
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", ISSUANCE_PATH)
+            .with_status(200)
+            .with_header("content-type", "application/json")
+            .with_body(r#"{"token":"oops_wrong_prefix"}"#)
+            .create_async()
+            .await;
+
+        let err = issue(&server.url(), "tok", "name", &scopes())
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, ActualError::ApiError(ref m) if m.contains(PAT_PREFIX)),
+            "got: {err:?}"
+        );
+        mock.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn test_issue_error_status_surfaces_body() {
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", ISSUANCE_PATH)
+            .with_status(403)
+            .with_body(r#"{"error":"insufficient_scope"}"#)
+            .create_async()
+            .await;
+
+        let err = issue(&server.url(), "tok", "name", &scopes())
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, ActualError::ApiError(ref m) if m.contains("insufficient_scope") && m.contains("403")),
+            "got: {err:?}"
+        );
+        mock.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn test_issue_rejects_non_https_non_loopback() {
+        // The shared client builder refuses to send a bearer over clear-text
+        // http to a non-loopback host.
+        let err = issue("http://example.com", "tok", "name", &scopes())
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("HTTPS")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_issued_token_debug_redacts_secret() {
+        let issued = IssuedToken {
+            token: "actl_pat_supersecret".to_string(),
+            id: Some("tok_1".to_string()),
+            name: Some("agent".to_string()),
+            scopes: scopes(),
+            created_at: None,
+            expires_at: None,
+        };
+        let debug = format!("{issued:?}");
+        assert!(
+            !debug.contains("actl_pat_supersecret"),
+            "Debug must not leak the token: {debug}"
+        );
+        assert!(debug.contains("<redacted>"));
+        assert!(debug.contains("tok_1"), "non-secret id should show");
+    }
+}
diff --git a/src/auth/token_store.rs b/src/auth/token_store.rs
new file mode 100644
index 00000000..2861ae3d
--- /dev/null
+++ b/src/auth/token_store.rs
@@ -0,0 +1,1236 @@
+//! Secure storage for scoped personal access tokens (PATs).
+//!
+//! A PAT minted by `actual auth create-token` is a long-lived bearer secret.
+//! It must never sit in plaintext on disk, in shell history, in process
+//! arguments, or in an agent's prompt / log stream. This module gives the CLI
+//! two storage backends and one non-interactive read path, so the raw token is
+//! shown once at mint time and thereafter only ever lives behind the OS
+//! keychain, an encrypted file, or the process environment.
+//!
+//! ## Backends
+//!
+//! - **`Keyring`** — the OS keychain (macOS Keychain, Windows Credential
+//!   Manager, Linux kernel keyutils) via the portable [`keyring`] crate. This is
+//!   the primary store on a desktop / interactive box.
+//! - **`EncryptedFile`** — an XChaCha20-Poly1305 AEAD file under the config
+//!   directory, with the key derived by Argon2id from a passphrase read from
+//!   `ACTUAL_TOKEN_PASSPHRASE`. This is the fallback for headless Linux / CI
+//!   where the OS keychain is unavailable.
+//!
+//! ## Backend selection (`ACTUAL_TOKEN_STORE`)
+//!
+//! - `auto` (default / unset): try the keychain; if it is unavailable, fall
+//!   back to the encrypted file (when a passphrase is configured). This is the
+//!   graceful-degradation path the headless-storage POC question asks about.
+//! - `keyring`: force the OS keychain.
+//! - `file`: force the encrypted file.
+//!
+//! ## Non-interactive read precedence ([`resolve`])
+//!
+//! 1. The `ACTUAL_TOKEN` environment variable — the CI path, no storage needed.
+//! 2. The OS keychain.
+//! 3. The encrypted fallback file.
+//!
+//! Token material is never written to a log or a `Debug` impl in this module.
+
+use std::path::{Path, PathBuf};
+
+use argon2::Argon2;
+use base64::engine::general_purpose::STANDARD as B64;
+use base64::Engine as _;
+use chacha20poly1305::aead::rand_core::RngCore;
+use chacha20poly1305::aead::{Aead, KeyInit, OsRng, Payload};
+use chacha20poly1305::{XChaCha20Poly1305, XNonce};
+use serde::{Deserialize, Serialize};
+
+use crate::config::paths::config_dir;
+use crate::error::ActualError;
+
+/// Keychain service name under which all PATs are filed. The keychain entry's
+/// "account" is the per-credential `--name`.
+pub const KEYRING_SERVICE: &str = "actual-cli";
+
+/// Environment variable holding a ready-to-use PAT for non-interactive
+/// (CI / agent) use. When set, it wins over any stored credential.
+pub const ACTUAL_TOKEN_ENV: &str = "ACTUAL_TOKEN";
+
+/// Environment variable selecting the storage backend: `auto` (default),
+/// `keyring`, or `file`.
+pub const STORE_BACKEND_ENV: &str = "ACTUAL_TOKEN_STORE";
+
+/// Environment variable holding the passphrase that protects the encrypted-file
+/// fallback. Required to use (read or write) the `file` backend.
+pub const PASSPHRASE_ENV: &str = "ACTUAL_TOKEN_PASSPHRASE";
+
+/// Subdirectory of the config dir holding encrypted token files.
+const TOKEN_SUBDIR: &str = "tokens";
+
+const ARGON2_KEY_LEN: usize = 32;
+const SALT_LEN: usize = 16;
+const XNONCE_LEN: usize = 24;
+const MAX_NAME_LEN: usize = 200;
+const MAX_TOKEN_FILE_SIZE: u64 = 64 * 1024;
+
+fn token_error(msg: impl std::fmt::Display) -> ActualError {
+    ActualError::ConfigError(msg.to_string())
+}
+
+/// Which backend a store / retrieve operation actually used. Returned by
+/// [`store`] so the command can tell the user where the secret landed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Backend {
+    /// The OS keychain (macOS Keychain, Windows Credential Manager, Linux
+    /// kernel keyutils).
+    Keyring,
+    /// The Argon2id + XChaCha20-Poly1305 encrypted fallback file.
+    EncryptedFile,
+}
+
+impl Backend {
+    /// Human-readable label for user-facing messages. Carries no secret.
+    pub fn label(self) -> &'static str {
+        match self {
+            Backend::Keyring => "OS keychain",
+            Backend::EncryptedFile => "encrypted file",
+        }
+    }
+}
+
+/// Resolved backend-selection mode from `ACTUAL_TOKEN_STORE`.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Mode {
+    Auto,
+    Keyring,
+    File,
+}
+
+fn selected_mode() -> Result<Mode, ActualError> {
+    match std::env::var(STORE_BACKEND_ENV).ok().as_deref() {
+        None | Some("") | Some("auto") => Ok(Mode::Auto),
+        Some("keyring") => Ok(Mode::Keyring),
+        Some("file") => Ok(Mode::File),
+        Some(other) => Err(token_error(format!(
+            "invalid {STORE_BACKEND_ENV}={other:?} (expected one of: auto, keyring, file)"
+        ))),
+    }
+}
+
+/// The configured fallback passphrase, or `None` when unset / empty.
+fn passphrase() -> Option<String> {
+    std::env::var(PASSPHRASE_ENV).ok().filter(|s| !s.is_empty())
+}
+
+/// The `ACTUAL_TOKEN` env value, or `None` when unset / empty.
+fn env_token() -> Option<String> {
+    std::env::var(ACTUAL_TOKEN_ENV)
+        .ok()
+        .filter(|s| !s.is_empty())
+}
+
+/// Reject names that are empty, over-long, or contain control characters. The
+/// raw name is used as the keychain account; a sanitized form names the file.
+fn validate_name(name: &str) -> Result<(), ActualError> {
+    if name.is_empty() {
+        return Err(token_error("token name must not be empty"));
+    }
+    if name.len() > MAX_NAME_LEN {
+        return Err(token_error(format!(
+            "token name is too long ({} chars, max {MAX_NAME_LEN})",
+            name.len()
+        )));
+    }
+    if name.chars().any(|c| c.is_control()) {
+        return Err(token_error(
+            "token name must not contain control characters",
+        ));
+    }
+    Ok(())
+}
+
+/// Map a name to a safe filename stem: keep `[A-Za-z0-9._-]`, replace the rest
+/// with `_`. Deterministic, so the same name always maps to the same file.
+fn sanitize_name(name: &str) -> String {
+    name.chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect()
+}
+
+fn token_dir() -> Result<PathBuf, ActualError> {
+    Ok(config_dir()?.join(TOKEN_SUBDIR))
+}
+
+fn token_file(name: &str) -> Result<PathBuf, ActualError> {
+    Ok(token_dir()?.join(format!("{}.token.json", sanitize_name(name))))
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/// Store `token` under `name`, returning which backend held it.
+///
+/// In `auto` mode the OS keychain is tried first; if it is unavailable (the
+/// headless-Linux / no-OS-keychain case) the encrypted file is used instead,
+/// provided `ACTUAL_TOKEN_PASSPHRASE` is set. The raw token is never written in
+/// plaintext under any path.
+pub fn store(name: &str, token: &str) -> Result<Backend, ActualError> {
+    validate_name(name)?;
+    match selected_mode()? {
+        Mode::Keyring => {
+            keyring_set(name, token)?;
+            Ok(Backend::Keyring)
+        }
+        Mode::File => {
+            file_set(name, token)?;
+            Ok(Backend::EncryptedFile)
+        }
+        Mode::Auto => match keyring_set(name, token) {
+            Ok(()) => Ok(Backend::Keyring),
+            Err(keyring_err) => {
+                if passphrase().is_some() {
+                    file_set(name, token)?;
+                    Ok(Backend::EncryptedFile)
+                } else {
+                    Err(token_error(format!(
+                        "the OS keychain is unavailable ({keyring_err}), and no encrypted-file \
+                         fallback is configured. Set {PASSPHRASE_ENV} to enable the encrypted-file \
+                         fallback, or use the {ACTUAL_TOKEN_ENV} environment variable for \
+                         non-interactive use."
+                    )))
+                }
+            }
+        },
+    }
+}
+
+/// Verify — **without** minting or writing anything — that a storage backend is
+/// available to hold a freshly-minted PAT. Call this *before* the token is
+/// minted so the predictable headless-Linux / no-keychain / no-passphrase case
+/// fails cleanly instead of stranding an orphaned, unrevocable live token.
+///
+/// A pass here is necessary but not sufficient: a later [`store`] can still fail
+/// for reasons a non-writing probe cannot see (a full disk, a keychain lock
+/// race). Callers must therefore still handle a [`store`] error by surfacing the
+/// minted token for manual capture and revocation — this only removes the
+/// *predictable* orphan, not every possible one.
+pub fn precheck(name: &str) -> Result<(), ActualError> {
+    validate_name(name)?;
+    match selected_mode()? {
+        Mode::Keyring => {
+            if keyring_available(name) {
+                Ok(())
+            } else {
+                Err(token_error(format!(
+                    "the OS keychain is unavailable and {STORE_BACKEND_ENV}=keyring forces it. \
+                     Use {STORE_BACKEND_ENV}=file with {PASSPHRASE_ENV} set, or provide a token \
+                     via {ACTUAL_TOKEN_ENV}, for non-interactive use."
+                )))
+            }
+        }
+        Mode::File => {
+            if passphrase().is_some() {
+                Ok(())
+            } else {
+                Err(token_error(format!(
+                    "{PASSPHRASE_ENV} must be set to use the encrypted-file token store."
+                )))
+            }
+        }
+        Mode::Auto => {
+            if keyring_available(name) || passphrase().is_some() {
+                Ok(())
+            } else {
+                Err(token_error(format!(
+                    "the OS keychain is unavailable and no encrypted-file fallback is configured. \
+                     Set {PASSPHRASE_ENV} to enable the encrypted-file fallback, or provide a \
+                     token via {ACTUAL_TOKEN_ENV}, for non-interactive use."
+                )))
+            }
+        }
+    }
+}
+
+/// Read the token stored under `name` from the keychain / file (not the
+/// environment). Returns `None` when no credential is stored.
+pub fn retrieve(name: &str) -> Result<Option<String>, ActualError> {
+    validate_name(name)?;
+    match selected_mode()? {
+        Mode::Keyring => keyring_get(name),
+        Mode::File => file_get(name),
+        Mode::Auto => match keyring_get(name) {
+            Ok(Some(tok)) => Ok(Some(tok)),
+            Ok(None) => file_get(name),
+            Err(keyring_err) => {
+                // Keychain unavailable (headless) — fall through to the file.
+                tracing::debug!("keychain read failed, trying file fallback: {keyring_err}");
+                file_get(name)
+            }
+        },
+    }
+}
+
+/// Delete the token stored under `name`. Idempotent: a missing credential is
+/// success. In `auto` mode both backends are cleared.
+pub fn delete(name: &str) -> Result<(), ActualError> {
+    validate_name(name)?;
+    match selected_mode()? {
+        Mode::Keyring => keyring_delete(name),
+        Mode::File => file_delete(name),
+        Mode::Auto => {
+            // Best-effort on the keychain (may be unavailable headless); always
+            // clear the file so no fallback copy lingers.
+            if let Err(keyring_err) = keyring_delete(name) {
+                tracing::debug!("keychain delete failed, clearing file fallback: {keyring_err}");
+            }
+            file_delete(name)
+        }
+    }
+}
+
+/// Resolve a usable token for non-interactive use: the `ACTUAL_TOKEN`
+/// environment variable wins, then the stored credential under `name`.
+pub fn resolve(name: &str) -> Result<Option<String>, ActualError> {
+    if let Some(tok) = env_token() {
+        return Ok(Some(tok));
+    }
+    retrieve(name)
+}
+
+// ── Keyring backend ─────────────────────────────────────────────────────────
+
+fn keyring_entry(name: &str) -> Result<keyring::Entry, ActualError> {
+    keyring::Entry::new(KEYRING_SERVICE, name)
+        .map_err(|e| token_error(format!("keychain entry init failed: {e}")))
+}
+
+/// Best-effort, non-mutating probe: can the OS keychain be reached for this
+/// service right now? A missing entry (`NoEntry`) counts as *available* — the
+/// store is reachable, just empty. Any other error (no keychain backend at all,
+/// e.g. headless Linux) counts as unavailable. Writes nothing, so it is safe to
+/// call before minting.
+fn keyring_available(name: &str) -> bool {
+    let Ok(entry) = keyring::Entry::new(KEYRING_SERVICE, name) else {
+        return false;
+    };
+    matches!(entry.get_password(), Ok(_) | Err(keyring::Error::NoEntry))
+}
+
+fn keyring_set(name: &str, token: &str) -> Result<(), ActualError> {
+    keyring_entry(name)?
+        .set_password(token)
+        .map_err(|e| token_error(format!("keychain write failed: {e}")))
+}
+
+fn keyring_get(name: &str) -> Result<Option<String>, ActualError> {
+    match keyring_entry(name)?.get_password() {
+        Ok(tok) => Ok(Some(tok)),
+        Err(keyring::Error::NoEntry) => Ok(None),
+        Err(e) => Err(token_error(format!("keychain read failed: {e}"))),
+    }
+}
+
+fn keyring_delete(name: &str) -> Result<(), ActualError> {
+    match keyring_entry(name)?.delete_credential() {
+        Ok(()) | Err(keyring::Error::NoEntry) => Ok(()),
+        Err(e) => Err(token_error(format!("keychain delete failed: {e}"))),
+    }
+}
+
+// ── Encrypted-file backend ──────────────────────────────────────────────────
+
+/// On-disk shape of an encrypted token. Holds only the salt, nonce, and
+/// ciphertext (which includes the Poly1305 tag) — never the plaintext token.
+#[derive(Debug, Serialize, Deserialize)]
+struct EncryptedBlob {
+    /// Format version, for forward compatibility.
+    version: u8,
+    /// Key-derivation function identifier.
+    kdf: String,
+    /// Argon2id salt, base64.
+    salt: String,
+    /// XChaCha20-Poly1305 nonce (24 bytes), base64.
+    nonce: String,
+    /// Ciphertext + auth tag, base64.
+    ciphertext: String,
+}
+
+/// Gather `N` cryptographically-random bytes from the OS RNG and return them.
+///
+/// Returning the freshly filled array (rather than filling a caller-owned zero
+/// buffer in place) keeps the random value off any `[0u8; N]` binding, so the
+/// salt and nonce that flow into the KDF and cipher are never a constant.
+fn random_bytes<const N: usize>() -> Result<[u8; N], ActualError> {
+    let mut buf = [0u8; N];
+    OsRng
+        .try_fill_bytes(&mut buf)
+        .map_err(|e| token_error(format!("failed to gather randomness: {e}")))?;
+    Ok(buf)
+}
+
+fn derive_key(passphrase: &[u8], salt: &[u8]) -> Result<[u8; ARGON2_KEY_LEN], ActualError> {
+    let mut key = [0u8; ARGON2_KEY_LEN];
+    Argon2::default()
+        .hash_password_into(passphrase, salt, &mut key)
+        .map_err(|e| token_error(format!("key derivation failed: {e}")))?;
+    Ok(key)
+}
+
+fn encrypt_token(name: &str, token: &str, passphrase: &[u8]) -> Result<EncryptedBlob, ActualError> {
+    let salt: [u8; SALT_LEN] = random_bytes()?;
+    let key = derive_key(passphrase, &salt)?;
+    let cipher = XChaCha20Poly1305::new_from_slice(&key)
+        .map_err(|e| token_error(format!("cipher init failed: {e}")))?;
+
+    let nonce_bytes: [u8; XNONCE_LEN] = random_bytes()?;
+    let nonce = XNonce::from_slice(&nonce_bytes);
+
+    // Bind the credential name as associated data so a file cannot be silently
+    // swapped between names.
+    let ciphertext = cipher
+        .encrypt(
+            nonce,
+            Payload {
+                msg: token.as_bytes(),
+                aad: name.as_bytes(),
+            },
+        )
+        .map_err(|_| token_error("token encryption failed"))?;
+
+    Ok(EncryptedBlob {
+        version: 1,
+        kdf: "argon2id".to_string(),
+        salt: B64.encode(salt),
+        nonce: B64.encode(nonce_bytes),
+        ciphertext: B64.encode(ciphertext),
+    })
+}
+
+fn decrypt_token(
+    name: &str,
+    blob: &EncryptedBlob,
+    passphrase: &[u8],
+) -> Result<String, ActualError> {
+    let salt = B64
+        .decode(&blob.salt)
+        .map_err(|e| token_error(format!("token file salt is not valid base64: {e}")))?;
+    let nonce_bytes = B64
+        .decode(&blob.nonce)
+        .map_err(|e| token_error(format!("token file nonce is not valid base64: {e}")))?;
+    let ciphertext = B64
+        .decode(&blob.ciphertext)
+        .map_err(|e| token_error(format!("token file ciphertext is not valid base64: {e}")))?;
+
+    if nonce_bytes.len() != XNONCE_LEN {
+        return Err(token_error("token file nonce has the wrong length"));
+    }
+    if salt.len() < 8 {
+        return Err(token_error("token file salt is too short"));
+    }
+
+    let key = derive_key(passphrase, &salt)?;
+    let cipher = XChaCha20Poly1305::new_from_slice(&key)
+        .map_err(|e| token_error(format!("cipher init failed: {e}")))?;
+    let nonce = XNonce::from_slice(&nonce_bytes);
+
+    let plaintext = cipher
+        .decrypt(
+            nonce,
+            Payload {
+                msg: &ciphertext,
+                aad: name.as_bytes(),
+            },
+        )
+        .map_err(|_| {
+            token_error("token decryption failed (wrong passphrase or corrupted token file)")
+        })?;
+
+    String::from_utf8(plaintext).map_err(|_| token_error("decrypted token is not valid UTF-8"))
+}
+
+fn file_set(name: &str, token: &str) -> Result<(), ActualError> {
+    let pass = passphrase().ok_or_else(|| {
+        token_error(format!(
+            "{PASSPHRASE_ENV} must be set to use the encrypted-file token store"
+        ))
+    })?;
+    let blob = encrypt_token(name, token, pass.as_bytes())?;
+    let json = serde_json::to_string_pretty(&blob)
+        .map_err(|e| token_error(format!("failed to serialize encrypted token: {e}")))?;
+    let path = token_file(name)?;
+    write_secure(&path, &json)
+}
+
+fn file_get(name: &str) -> Result<Option<String>, ActualError> {
+    let path = token_file(name)?;
+    let bytes = match std::fs::read(&path) {
+        Ok(b) => b,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+        Err(e) => return Err(token_error(format!("failed to read token file: {e}"))),
+    };
+    if bytes.len() as u64 > MAX_TOKEN_FILE_SIZE {
+        return Err(token_error("token file is too large"));
+    }
+    let pass = passphrase().ok_or_else(|| {
+        token_error(format!(
+            "{PASSPHRASE_ENV} must be set to read the encrypted-file token store"
+        ))
+    })?;
+    let blob: EncryptedBlob = serde_json::from_slice(&bytes)
+        .map_err(|e| token_error(format!("token file is corrupted: {e}")))?;
+    let token = decrypt_token(name, &blob, pass.as_bytes())?;
+    Ok(Some(token))
+}
+
+fn file_delete(name: &str) -> Result<(), ActualError> {
+    let path = token_file(name)?;
+    match std::fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(token_error(format!("failed to remove token file: {e}"))),
+    }
+}
+
+/// Write `content` to `path`, creating parents and (on unix) forcing `0600` so
+/// the encrypted blob is never world-readable. Mirrors [`crate::auth::store`].
+#[cfg(unix)]
+fn write_secure(path: &Path, content: &str) -> Result<(), ActualError> {
+    use std::io::Write;
+    use std::os::unix::fs::OpenOptionsExt;
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)
+            .map_err(|e| token_error(format!("failed to create token directory: {e}")))?;
+    }
+    let mut file = std::fs::OpenOptions::new()
+        .write(true)
+        .create(true)
+        .truncate(true)
+        .mode(0o600)
+        .open(path)
+        .map_err(|e| token_error(format!("failed to open token file for writing: {e}")))?;
+    file.write_all(content.as_bytes())
+        .map_err(|e| token_error(format!("failed to write token file: {e}")))?;
+    Ok(())
+}
+
+#[cfg(not(unix))]
+fn write_secure(path: &Path, content: &str) -> Result<(), ActualError> {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)
+            .map_err(|e| token_error(format!("failed to create token directory: {e}")))?;
+    }
+    std::fs::write(path, content)
+        .map_err(|e| token_error(format!("failed to write token file: {e}")))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testutil::{EnvGuard, ENV_MUTEX};
+    use tempfile::tempdir;
+
+    /// Set up an isolated env for the file backend: a temp config dir, the
+    /// `file` backend forced, and a passphrase. Returns the guards (which must
+    /// be held for the duration of the test) and the temp dir.
+    fn file_backend_env(
+        passphrase: &str,
+    ) -> (tempfile::TempDir, EnvGuard, EnvGuard, EnvGuard, EnvGuard) {
+        let tmp = tempdir().unwrap();
+        let g_cfg_file = EnvGuard::remove("ACTUAL_CONFIG");
+        let g_cfg = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let g_store = EnvGuard::set(STORE_BACKEND_ENV, "file");
+        let g_pass = EnvGuard::set(PASSPHRASE_ENV, passphrase);
+        (tmp, g_cfg_file, g_cfg, g_store, g_pass)
+    }
+
+    #[test]
+    fn test_precheck_file_mode_refuses_without_passphrase() {
+        // The pre-mint gate for the target env: a headless / `file` backend with
+        // no passphrase configured must be refused BEFORE any token is minted,
+        // so no orphaned, unrevocable token is ever created.
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let tmp = tempdir().unwrap();
+        let _g_cfg_file = EnvGuard::remove("ACTUAL_CONFIG");
+        let _g_cfg = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "file");
+        let _g_pass = EnvGuard::remove(PASSPHRASE_ENV);
+
+        assert!(
+            precheck("agent").is_err(),
+            "file backend with no passphrase must fail the pre-mint precheck"
+        );
+    }
+
+    #[test]
+    fn test_precheck_file_mode_passes_with_passphrase() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (_tmp, _g0, _g1, _g2, _g3) = file_backend_env("a-strong-passphrase");
+        assert!(
+            precheck("agent").is_ok(),
+            "file backend with a passphrase should pass the pre-mint precheck"
+        );
+    }
+
+    #[test]
+    fn test_precheck_keyring_mode_passes_when_keychain_available() {
+        // `keyring` mode with a reachable keychain passes the non-writing probe.
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+        assert!(
+            precheck("kr-agent").is_ok(),
+            "keyring mode with an available keychain should pass the precheck"
+        );
+    }
+
+    #[test]
+    fn test_precheck_keyring_mode_refuses_when_keychain_unavailable() {
+        // `keyring` mode with no reachable keychain (the headless case) must be
+        // refused BEFORE minting: the forced backend cannot hold the token.
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        fail_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+        let err = precheck("kr-agent").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("keychain is unavailable")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_precheck_keyring_mode_refuses_when_entry_init_fails() {
+        // The entry-init-failure leg of `keyring_available`: when the keychain
+        // backend cannot even construct an entry, the probe reports unavailable
+        // and the forced-keyring precheck refuses.
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        fail_test_keyring_build();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+        let err = precheck("kr-agent").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("keychain is unavailable")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_precheck_auto_mode_passes_when_keychain_available() {
+        // `auto` with a reachable keychain passes on the keychain leg alone,
+        // with no passphrase configured.
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "auto");
+        let _g_pass = EnvGuard::remove(PASSPHRASE_ENV);
+        assert!(
+            precheck("auto-agent").is_ok(),
+            "auto mode should pass on the keychain leg when it is available"
+        );
+    }
+
+    #[test]
+    fn test_precheck_auto_mode_passes_on_passphrase_when_keychain_unavailable() {
+        // `auto` with no keychain but a configured passphrase passes on the
+        // encrypted-file fallback leg.
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        fail_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "auto");
+        let _g_pass = EnvGuard::set(PASSPHRASE_ENV, "pw");
+        assert!(
+            precheck("auto-agent").is_ok(),
+            "auto mode should pass on the encrypted-file fallback when a passphrase is set"
+        );
+    }
+
+    #[test]
+    fn test_precheck_auto_mode_refuses_without_keychain_or_passphrase() {
+        // `auto` with neither a keychain nor a passphrase is the predictable
+        // headless orphan case — refused before any token is minted.
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        fail_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "auto");
+        let _g_pass = EnvGuard::remove(PASSPHRASE_ENV);
+        let err = precheck("auto-agent").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("keychain is unavailable")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_file_roundtrip_store_retrieve_delete() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let (_tmp, _g0, _g1, _g2, _g3) = file_backend_env("a-strong-passphrase");
+
+        let backend = store("ci-agent", "actl_pat_secretvalue123").unwrap();
+        assert_eq!(backend, Backend::EncryptedFile);
+
+        let got = retrieve("ci-agent").unwrap();
+        assert_eq!(got.as_deref(), Some("actl_pat_secretvalue123"));
+
+        delete("ci-agent").unwrap();
+        assert_eq!(retrieve("ci-agent").unwrap(), None);
+        drop(g_env);
+    }
+
+    #[test]
+    fn test_file_never_contains_plaintext() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+
+        let secret = "actl_pat_do_not_leak_me";
+        store("agent-x", secret).unwrap();
+
+        let path = tmp.path().join(TOKEN_SUBDIR).join("agent-x.token.json");
+        let on_disk = std::fs::read_to_string(&path).unwrap();
+        assert!(
+            !on_disk.contains(secret),
+            "encrypted file must not contain the plaintext token"
+        );
+        assert!(on_disk.contains("argon2id"), "expected the KDF marker");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_file_is_0600() {
+        use std::os::unix::fs::PermissionsExt;
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        store("agent-x", "actl_pat_x").unwrap();
+        let path = tmp.path().join(TOKEN_SUBDIR).join("agent-x.token.json");
+        let mode = std::fs::metadata(&path).unwrap().permissions().mode() & 0o777;
+        assert_eq!(mode, 0o600, "token file must be 0600");
+    }
+
+    #[test]
+    fn test_file_wrong_passphrase_fails_to_decrypt() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let tmp = tempdir().unwrap();
+        let _g_cfg_file = EnvGuard::remove("ACTUAL_CONFIG");
+        let _g_cfg = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "file");
+
+        let _g_pass = EnvGuard::set(PASSPHRASE_ENV, "right-passphrase");
+        store("agent", "actl_pat_value").unwrap();
+        drop(_g_pass);
+
+        let _g_pass2 = EnvGuard::set(PASSPHRASE_ENV, "wrong-passphrase");
+        let err = retrieve("agent").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("decryption failed")),
+            "expected a decryption failure, got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_file_requires_passphrase() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let tmp = tempdir().unwrap();
+        let _g_cfg_file = EnvGuard::remove("ACTUAL_CONFIG");
+        let _g_cfg = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "file");
+        let _g_pass = EnvGuard::remove(PASSPHRASE_ENV);
+
+        let err = store("agent", "actl_pat_value").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains(PASSPHRASE_ENV)),
+            "expected a passphrase-required error, got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_resolve_prefers_env_token() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (_tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        // Store one value, then set ACTUAL_TOKEN to a different value: resolve
+        // must return the env value, not the stored one.
+        store("agent", "actl_pat_stored").unwrap();
+        let _g_env = EnvGuard::set(ACTUAL_TOKEN_ENV, "actl_pat_from_env");
+        assert_eq!(
+            resolve("agent").unwrap().as_deref(),
+            Some("actl_pat_from_env")
+        );
+    }
+
+    #[test]
+    fn test_resolve_falls_back_to_store_without_env() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let (_tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        store("agent", "actl_pat_stored").unwrap();
+        assert_eq!(
+            resolve("agent").unwrap().as_deref(),
+            Some("actl_pat_stored")
+        );
+        drop(g_env);
+    }
+
+    #[test]
+    fn test_retrieve_absent_is_none() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (_tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        assert_eq!(retrieve("never-stored").unwrap(), None);
+    }
+
+    #[test]
+    fn test_corrupted_file_errors() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        let dir = tmp.path().join(TOKEN_SUBDIR);
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(dir.join("agent.token.json"), "{not valid json").unwrap();
+        let err = retrieve("agent").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("corrupted")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_aad_binding_rejects_name_swap() {
+        // A blob encrypted under one name must not decrypt under another, even
+        // with the right passphrase (the name is bound as associated data).
+        let blob = encrypt_token("agent-a", "actl_pat_v", b"pw").unwrap();
+        let err = decrypt_token("agent-b", &blob, b"pw").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("decryption failed")),
+            "got: {err:?}"
+        );
+        // Sanity: the correct name decrypts.
+        assert_eq!(
+            decrypt_token("agent-a", &blob, b"pw").unwrap(),
+            "actl_pat_v"
+        );
+    }
+
+    #[test]
+    fn test_validate_name() {
+        assert!(validate_name("").is_err());
+        assert!(validate_name("ok-name_1.2").is_ok());
+        assert!(validate_name(&"x".repeat(MAX_NAME_LEN + 1)).is_err());
+        assert!(validate_name("bad\nname").is_err());
+    }
+
+    #[test]
+    fn test_sanitize_name() {
+        assert_eq!(sanitize_name("ci/agent:1"), "ci_agent_1");
+        assert_eq!(sanitize_name("keep.me-ok_9"), "keep.me-ok_9");
+    }
+
+    #[test]
+    fn test_selected_mode_parsing() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+        assert_eq!(selected_mode().unwrap(), Mode::Keyring);
+        drop(_g);
+        let _g = EnvGuard::set(STORE_BACKEND_ENV, "file");
+        assert_eq!(selected_mode().unwrap(), Mode::File);
+        drop(_g);
+        let _g = EnvGuard::set(STORE_BACKEND_ENV, "auto");
+        assert_eq!(selected_mode().unwrap(), Mode::Auto);
+        drop(_g);
+        let _g = EnvGuard::remove(STORE_BACKEND_ENV);
+        assert_eq!(selected_mode().unwrap(), Mode::Auto);
+        drop(_g);
+        let _g = EnvGuard::set(STORE_BACKEND_ENV, "bogus");
+        assert!(selected_mode().is_err());
+    }
+
+    #[test]
+    fn test_backend_label() {
+        assert_eq!(Backend::Keyring.label(), "OS keychain");
+        assert_eq!(Backend::EncryptedFile.label(), "encrypted file");
+    }
+
+    #[test]
+    fn test_encrypt_uses_fresh_salt_and_nonce() {
+        // Two encryptions of the same token differ (random salt + nonce).
+        let a = encrypt_token("n", "actl_pat_v", b"pw").unwrap();
+        let b = encrypt_token("n", "actl_pat_v", b"pw").unwrap();
+        assert_ne!(a.ciphertext, b.ciphertext);
+        assert_ne!(a.nonce, b.nonce);
+        assert_ne!(a.salt, b.salt);
+    }
+
+    // ── Injectable in-memory keychain ─────────────────────────────────────────
+    //
+    // The real OS keychain cannot run deterministically under CI, so these tests
+    // install a persistent in-memory credential store through keyring's public
+    // `set_default_credential_builder` seam. It is keyed by (service, user) so a
+    // store → retrieve → delete round-trips across the separate `keyring::Entry`
+    // instances the backend creates, and it can be flipped to fail on demand to
+    // drive the error and fallback arms. Every keyring-touching test below holds
+    // `ENV_MUTEX` and calls `install_test_keyring()` first, so the process-global
+    // builder and the shared maps never race with a sibling test.
+    use keyring::credential::{Credential, CredentialApi, CredentialBuilderApi};
+    use std::any::Any;
+    use std::collections::HashMap;
+    use std::sync::Mutex;
+
+    static TEST_KEYRING: Mutex<Option<HashMap<(String, String), Vec<u8>>>> = Mutex::new(None);
+    static TEST_KEYRING_FAIL: Mutex<bool> = Mutex::new(false);
+    static TEST_KEYRING_FAIL_BUILD: Mutex<bool> = Mutex::new(false);
+
+    fn install_test_keyring() {
+        *TEST_KEYRING.lock().unwrap() = Some(HashMap::new());
+        *TEST_KEYRING_FAIL.lock().unwrap() = false;
+        *TEST_KEYRING_FAIL_BUILD.lock().unwrap() = false;
+        keyring::set_default_credential_builder(Box::new(TestKeyringBuilder));
+    }
+
+    /// Make every subsequent keychain op fail, simulating an unavailable keychain.
+    fn fail_test_keyring() {
+        *TEST_KEYRING_FAIL.lock().unwrap() = true;
+    }
+
+    /// Make `keyring::Entry::new` itself fail, simulating a platform with no
+    /// credential-store backend at all (so `keyring_available`'s entry-init
+    /// failure leg is reachable without OS-level trickery).
+    fn fail_test_keyring_build() {
+        *TEST_KEYRING_FAIL_BUILD.lock().unwrap() = true;
+    }
+
+    struct TestKeyringBuilder;
+    impl CredentialBuilderApi for TestKeyringBuilder {
+        fn build(
+            &self,
+            _target: Option<&str>,
+            service: &str,
+            user: &str,
+        ) -> keyring::Result<Box<Credential>> {
+            if *TEST_KEYRING_FAIL_BUILD.lock().unwrap() {
+                return Err(keyring::Error::Invalid(
+                    "test".into(),
+                    "no credential backend".into(),
+                ));
+            }
+            Ok(Box::new(TestCredential {
+                service: service.to_string(),
+                user: user.to_string(),
+            }))
+        }
+        fn as_any(&self) -> &dyn Any {
+            self
+        }
+    }
+
+    struct TestCredential {
+        service: String,
+        user: String,
+    }
+    impl TestCredential {
+        fn key(&self) -> (String, String) {
+            (self.service.clone(), self.user.clone())
+        }
+    }
+    impl CredentialApi for TestCredential {
+        fn set_secret(&self, secret: &[u8]) -> keyring::Result<()> {
+            if *TEST_KEYRING_FAIL.lock().unwrap() {
+                return Err(keyring::Error::Invalid("test".into(), "unavailable".into()));
+            }
+            TEST_KEYRING
+                .lock()
+                .unwrap()
+                .as_mut()
+                .unwrap()
+                .insert(self.key(), secret.to_vec());
+            Ok(())
+        }
+        fn get_secret(&self) -> keyring::Result<Vec<u8>> {
+            if *TEST_KEYRING_FAIL.lock().unwrap() {
+                return Err(keyring::Error::Invalid("test".into(), "unavailable".into()));
+            }
+            match TEST_KEYRING
+                .lock()
+                .unwrap()
+                .as_ref()
+                .unwrap()
+                .get(&self.key())
+            {
+                Some(v) => Ok(v.clone()),
+                None => Err(keyring::Error::NoEntry),
+            }
+        }
+        fn delete_credential(&self) -> keyring::Result<()> {
+            if *TEST_KEYRING_FAIL.lock().unwrap() {
+                return Err(keyring::Error::Invalid("test".into(), "unavailable".into()));
+            }
+            match TEST_KEYRING
+                .lock()
+                .unwrap()
+                .as_mut()
+                .unwrap()
+                .remove(&self.key())
+            {
+                Some(_) => Ok(()),
+                None => Err(keyring::Error::NoEntry),
+            }
+        }
+        fn as_any(&self) -> &dyn Any {
+            self
+        }
+    }
+
+    #[test]
+    fn test_keyring_backend_roundtrip() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+
+        let backend = store("kr-agent", "actl_pat_kr").unwrap();
+        assert_eq!(backend, Backend::Keyring);
+        assert_eq!(
+            retrieve("kr-agent").unwrap().as_deref(),
+            Some("actl_pat_kr")
+        );
+        delete("kr-agent").unwrap();
+        assert_eq!(retrieve("kr-agent").unwrap(), None);
+    }
+
+    #[test]
+    fn test_keyring_read_error_surfaces() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+        fail_test_keyring();
+        let err = retrieve("kr-agent").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("keychain read failed")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_keyring_delete_error_surfaces() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+        fail_test_keyring();
+        let err = delete("kr-agent").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("keychain delete failed")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_auto_uses_keyring_when_available() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "auto");
+
+        // Keyring is available → the secret lands there, reads back, and a delete
+        // clears it (after which retrieve falls through to the empty file).
+        let backend = store("auto-ok", "actl_pat_auto").unwrap();
+        assert_eq!(backend, Backend::Keyring);
+        assert_eq!(
+            retrieve("auto-ok").unwrap().as_deref(),
+            Some("actl_pat_auto")
+        );
+        delete("auto-ok").unwrap();
+        assert_eq!(retrieve("auto-ok").unwrap(), None);
+    }
+
+    #[test]
+    fn test_auto_falls_back_to_file_when_keyring_unavailable() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let tmp = tempdir().unwrap();
+        let _g_cfg_file = EnvGuard::remove("ACTUAL_CONFIG");
+        let _g_cfg = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "auto");
+        let _g_pass = EnvGuard::set(PASSPHRASE_ENV, "pw");
+        fail_test_keyring();
+
+        // Keyring write fails → encrypted-file fallback (passphrase configured).
+        let backend = store("auto-fb", "actl_pat_fb").unwrap();
+        assert_eq!(backend, Backend::EncryptedFile);
+        // Read + delete also route past the failing keychain to the file.
+        assert_eq!(retrieve("auto-fb").unwrap().as_deref(), Some("actl_pat_fb"));
+        delete("auto-fb").unwrap();
+        assert_eq!(retrieve("auto-fb").unwrap(), None);
+    }
+
+    #[test]
+    fn test_auto_errors_when_keyring_unavailable_and_no_passphrase() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let tmp = tempdir().unwrap();
+        let _g_cfg_file = EnvGuard::remove("ACTUAL_CONFIG");
+        let _g_cfg = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "auto");
+        let _g_pass = EnvGuard::remove(PASSPHRASE_ENV);
+        fail_test_keyring();
+
+        let err = store("auto-none", "actl_pat_x").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("keychain is unavailable")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_decrypt_rejects_bad_nonce_length() {
+        // A blob whose nonce decodes to the wrong length is rejected pre-decrypt.
+        // "AAAA" is valid base64 for three zero bytes — a 3-byte nonce, not 24.
+        let mut blob = encrypt_token("n", "actl_pat_v", b"pw").unwrap();
+        blob.nonce = "AAAA".to_string();
+        let err = decrypt_token("n", &blob, b"pw").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("nonce")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_decrypt_rejects_short_salt() {
+        // A valid nonce but a too-short salt (three bytes) is rejected pre-decrypt.
+        let mut blob = encrypt_token("n", "actl_pat_v", b"pw").unwrap();
+        blob.salt = "AAAA".to_string();
+        let err = decrypt_token("n", &blob, b"pw").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("salt")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_file_get_read_error_when_path_is_dir() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        // Put a directory where the token file should be so read() fails with a
+        // non-NotFound error.
+        std::fs::create_dir_all(tmp.path().join(TOKEN_SUBDIR).join("dirtok.token.json")).unwrap();
+        let err = retrieve("dirtok").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("failed to read token file")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_file_get_rejects_oversize_file() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        let dir = tmp.path().join(TOKEN_SUBDIR);
+        std::fs::create_dir_all(&dir).unwrap();
+        std::fs::write(
+            dir.join("big.token.json"),
+            vec![b'x'; MAX_TOKEN_FILE_SIZE as usize + 1],
+        )
+        .unwrap();
+        let err = retrieve("big").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("too large")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_file_get_requires_passphrase_to_read() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let tmp = tempdir().unwrap();
+        let _g_cfg_file = EnvGuard::remove("ACTUAL_CONFIG");
+        let _g_cfg = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "file");
+        // Write the file with a passphrase, then read it back with none set.
+        let g_pass = EnvGuard::set(PASSPHRASE_ENV, "pw");
+        store("passless", "actl_pat_v").unwrap();
+        drop(g_pass);
+        let _g_nopass = EnvGuard::remove(PASSPHRASE_ENV);
+        let err = retrieve("passless").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains(PASSPHRASE_ENV)),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_file_delete_missing_is_ok() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (_tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        // Deleting a token that was never stored is a no-op success.
+        delete("never-stored").unwrap();
+    }
+
+    #[test]
+    fn test_file_delete_error_when_path_is_dir() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        // A directory at the token-file path makes remove_file fail non-NotFound.
+        std::fs::create_dir_all(tmp.path().join(TOKEN_SUBDIR).join("dirdel.token.json")).unwrap();
+        let err = delete("dirdel").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("failed to remove token file")),
+            "got: {err:?}"
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_file_store_error_when_dir_cannot_be_created() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let (tmp, _g0, _g1, _g2, _g3) = file_backend_env("pw");
+        // A plain file where the tokens directory belongs makes create_dir_all fail.
+        std::fs::write(tmp.path().join(TOKEN_SUBDIR), "x").unwrap();
+        let err = store("blocked", "actl_pat_v").unwrap_err();
+        assert!(
+            matches!(err, ActualError::ConfigError(ref m) if m.contains("failed to create token directory")),
+            "got: {err:?}"
+        );
+    }
+
+    #[test]
+    fn test_keyring_delete_missing_is_ok() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        install_test_keyring();
+        let _g_env = EnvGuard::remove(ACTUAL_TOKEN_ENV);
+        let _g_store = EnvGuard::set(STORE_BACKEND_ENV, "keyring");
+        // Deleting a credential that was never stored is a no-op success (the
+        // keychain reports NoEntry, which the backend maps to Ok).
+        delete("ghost").unwrap();
+    }
+
+    #[test]
+    fn test_injected_keychain_as_any_hooks() {
+        // The keyring credential traits require `as_any`; exercise both so the
+        // injectable in-memory keychain is itself fully covered.
+        assert!(TestKeyringBuilder
+            .as_any()
+            .downcast_ref::<TestKeyringBuilder>()
+            .is_some());
+        let cred = TestCredential {
+            service: "s".to_string(),
+            user: "u".to_string(),
+        };
+        assert!(cred.as_any().downcast_ref::<TestCredential>().is_some());
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn test_write_secure_parentless_path_errors() {
+        // A path whose parent is None (the filesystem root) skips the mkdir step;
+        // the open then fails, covering the no-parent branch of write_secure.
+        let err = write_secure(Path::new("/"), "x").unwrap_err();
+        assert!(matches!(err, ActualError::ConfigError(_)), "got: {err:?}");
+    }
+}
diff --git a/src/cli/args.rs b/src/cli/args.rs
index 78d3d34e..1b7135c1 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -323,8 +323,8 @@ pub enum Command {
     AdrBot(SyncArgs),
     /// Check output file state
     Status(StatusArgs),
-    /// Check Claude Code authentication status
-    Auth,
+    /// Check the coding-agent runner's auth, or mint a scoped access token
+    Auth(AuthArgs),
     /// Sign in to your Actual AI account via browser OAuth
     Login(LoginArgs),
     /// Sign out of your Actual AI account and clear local credentials
@@ -475,6 +475,45 @@ pub struct LoginArgs {
     pub no_browser: bool,
 }
 
+/// Arguments for the `auth` command group.
+///
+/// With no subcommand, `actual auth` keeps its original behavior — a check of
+/// the underlying coding-agent runner (e.g. `claude auth status`). The
+/// `create-token` subcommand mints a scoped Actual AI platform token.
+#[derive(Parser, Debug)]
+pub struct AuthArgs {
+    #[command(subcommand)]
+    pub command: Option<AuthCommand>,
+}
+
+#[derive(Subcommand, Debug)]
+pub enum AuthCommand {
+    /// Mint a scoped personal access token for non-interactive (CI / agent) use
+    CreateToken(CreateTokenArgs),
+}
+
+/// Arguments for `auth create-token`.
+#[derive(Parser, Debug)]
+pub struct CreateTokenArgs {
+    /// Label identifying this token and the agent that will use it.
+    ///
+    /// Mint a DEDICATED token per agent (do not share the human's interactive
+    /// login session) so every action is attributable and the credential can be
+    /// revoked on its own.
+    #[arg(long, value_name = "NAME")]
+    pub name: String,
+
+    /// Scopes to grant, comma- or space-separated
+    /// (e.g. `--scopes adr:query,adr:review`).
+    #[arg(long, value_name = "SCOPE", value_delimiter = ',', required = true, num_args = 1..)]
+    pub scopes: Vec<String>,
+
+    /// Issuance API base URL. Defaults to the api-service; falls back through
+    /// the `ACTUAL_API_URL` env var. Point at a local mock for testing.
+    #[arg(long, value_name = "URL")]
+    pub api_url: Option<String>,
+}
+
 /// Arguments for the `status` command
 #[derive(Parser, Debug)]
 pub struct StatusArgs {
diff --git a/src/cli/commands/auth.rs b/src/cli/commands/auth.rs
index 657d376c..bdaaa1dc 100644
--- a/src/cli/commands/auth.rs
+++ b/src/cli/commands/auth.rs
@@ -1,12 +1,21 @@
 use std::path::Path;
 
+use crate::cli::args::{AuthArgs, AuthCommand};
 use crate::cli::ui::theme;
 use crate::error::ActualError;
 use crate::runner::auth::ClaudeAuthStatus;
 use crate::runner::binary::find_claude_binary;
 
-pub fn exec() -> Result<(), ActualError> {
-    run_auth()
+/// Dispatch the `auth` command group. With no subcommand, `actual auth` checks
+/// the underlying coding-agent runner (the original behavior). `create-token`
+/// mints a scoped Actual AI platform token.
+pub fn exec(args: &AuthArgs) -> Result<(), ActualError> {
+    match &args.command {
+        None => run_auth(),
+        Some(AuthCommand::CreateToken(create_args)) => {
+            crate::cli::commands::create_token::exec(create_args)
+        }
+    }
 }
 
 fn run_auth() -> Result<(), ActualError> {
@@ -561,10 +570,32 @@ mod tests {
     fn test_exec_binary_not_found() {
         let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
         let _guard = EnvGuard::set("CLAUDE_BINARY", "/nonexistent/path/to/claude");
-        let code = handle_result(exec());
+        let code = handle_result(exec(&AuthArgs { command: None }));
         assert_eq!(code, 2);
     }
 
+    #[test]
+    fn test_exec_dispatches_create_token() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        // Route `auth create-token` through the dispatch arm. With no stored
+        // login session it reaches create_token::exec and returns NotLoggedIn,
+        // which is enough to exercise the CreateToken branch of `exec`.
+        let _g1 = EnvGuard::remove("ACTUAL_CONFIG");
+        let tmp = tempfile::tempdir().unwrap();
+        let _g2 = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let args = AuthArgs {
+            command: Some(AuthCommand::CreateToken(
+                crate::cli::args::CreateTokenArgs {
+                    name: "dispatch-agent".to_string(),
+                    scopes: vec!["adr:query".to_string()],
+                    api_url: Some("http://127.0.0.1:1".to_string()),
+                },
+            )),
+        };
+        let err = exec(&args).unwrap_err();
+        assert!(matches!(err, ActualError::NotLoggedIn), "got: {err:?}");
+    }
+
     #[cfg(unix)]
     #[test]
     fn test_exec_success() {
@@ -576,7 +607,7 @@ mod tests {
             0,
         );
         let _guard = EnvGuard::set("CLAUDE_BINARY", script.to_str().unwrap());
-        let code = handle_result(exec());
+        let code = handle_result(exec(&AuthArgs { command: None }));
         assert_eq!(code, 0);
     }
 
@@ -587,7 +618,7 @@ mod tests {
         let dir = tempfile::tempdir().unwrap();
         let script = create_fake_binary(dir.path(), r#"{"loggedIn": false}"#, 0);
         let _guard = EnvGuard::set("CLAUDE_BINARY", script.to_str().unwrap());
-        let code = handle_result(exec());
+        let code = handle_result(exec(&AuthArgs { command: None }));
         assert_eq!(code, 2);
     }
 
@@ -643,7 +674,7 @@ mod tests {
         // File exists but is NOT executable — find_claude_binary rejects it
         // with ClaudeNotFound (exit code 2) before reaching the subprocess.
         let _guard = EnvGuard::set("CLAUDE_BINARY", not_executable.to_str().unwrap());
-        let code = handle_result(exec());
+        let code = handle_result(exec(&AuthArgs { command: None }));
         assert_eq!(code, 2);
     }
 
diff --git a/src/cli/commands/create_token.rs b/src/cli/commands/create_token.rs
new file mode 100644
index 00000000..afe1e0ca
--- /dev/null
+++ b/src/cli/commands/create_token.rs
@@ -0,0 +1,685 @@
+//! `actual auth create-token` — mint a scoped personal access token (PAT).
+//!
+//! Builds on the existing `actual login` session: it loads the stored
+//! credentials, refreshes the access token if it is near expiry, and calls the
+//! authenticated issuance endpoint with that token as the bearer (no second
+//! browser dance). The raw `actl_pat_…` is printed exactly once and otherwise
+//! kept only behind the OS keychain (or the encrypted-file fallback). The token
+//! is never written to a log.
+//!
+//! ## Security model for agents
+//!
+//! - Mint a **dedicated** token per agent (`--name <agent>`); never hand an
+//!   agent the human's interactive login session. One PAT per agent makes
+//!   actions attributable and lets a single agent be revoked on its own.
+//! - The secret must live **only** in the keychain or the `ACTUAL_TOKEN`
+//!   environment variable — never in an agent's prompt/conversation context,
+//!   shell history, or logs.
+
+use std::io::{self, Write};
+
+use chrono::{Duration as ChronoDuration, Utc};
+
+use crate::api::DEFAULT_API_URL;
+use crate::auth::store::{self, StoredCredentials};
+use crate::auth::{oauth, pat, token_store};
+use crate::cli::args::CreateTokenArgs;
+use crate::cli::ui::theme;
+use crate::error::ActualError;
+
+pub fn exec(args: &CreateTokenArgs) -> Result<(), ActualError> {
+    build_runtime()?.block_on(run(args))
+}
+
+/// Single-threaded tokio runtime so the sync CLI dispatch path can drive the
+/// async issuance flow (mirrors `commands::login` / `commands::advisor`).
+fn build_runtime() -> Result<tokio::runtime::Runtime, ActualError> {
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .map_err(|e| ActualError::InternalError(format!("failed to build tokio runtime: {e}")))
+}
+
+/// Resolve the issuance API base URL: the `--api-url` flag wins, then
+/// `ACTUAL_API_URL`, else the api-service default. Mirrors how `advisor`
+/// resolves its endpoint, so one env export steers both halves.
+fn resolve_api_url(flag: Option<&str>) -> String {
+    flag.map(|s| s.to_string())
+        .or_else(|| {
+            std::env::var("ACTUAL_API_URL")
+                .ok()
+                .filter(|s| !s.is_empty())
+        })
+        .unwrap_or_else(|| DEFAULT_API_URL.to_string())
+}
+
+/// If the stored access token is expired (or about to be), refresh it with the
+/// rotation primitive and re-persist. Mirrors `commands::advisor::ensure_fresh`;
+/// a refresh failure surfaces as `NotLoggedIn` so the user re-runs
+/// `actual login`.
+async fn ensure_fresh(creds: StoredCredentials) -> Result<StoredCredentials, ActualError> {
+    if creds.refresh_token.is_empty() {
+        return Ok(creds);
+    }
+    if creds.expires_within(Utc::now(), ChronoDuration::seconds(60)) {
+        let refreshed = oauth::refresh(&creds)
+            .await
+            .map_err(|_| ActualError::NotLoggedIn)?;
+        store::save(&refreshed)?;
+        return Ok(refreshed);
+    }
+    Ok(creds)
+}
+
+async fn run(args: &CreateTokenArgs) -> Result<(), ActualError> {
+    let stdout = io::stdout();
+    let stderr = io::stderr();
+    run_inner(&mut stdout.lock(), &mut stderr.lock(), args).await
+}
+
+/// The mint-and-store flow, with the secret going to `out` and all chrome to
+/// `err`. Split out from [`run`] so tests can inject buffers and assert the
+/// exact bytes each stream carries — the stdout=secret / stderr=chrome split is
+/// a load-bearing security contract.
+async fn run_inner(
+    out: &mut dyn Write,
+    err: &mut dyn Write,
+    args: &CreateTokenArgs,
+) -> Result<(), ActualError> {
+    let creds = store::load()?.ok_or(ActualError::NotLoggedIn)?;
+
+    // Refuse BEFORE any network work or minting when there is provably no place
+    // to keep the result — the predictable headless-Linux / no-passphrase case,
+    // which is exactly the target env. Without this, every failed attempt would
+    // mint a live token the user can neither capture nor revoke.
+    token_store::precheck(&args.name)?;
+
+    let creds = ensure_fresh(creds).await?;
+
+    let base_url = resolve_api_url(args.api_url.as_deref());
+    let issued = pat::issue(&base_url, &creds.access_token, &args.name, &args.scopes).await?;
+
+    // The token is now live server-side. A store failure here is a *post-mint*
+    // failure the precheck could not foresee (a full disk, a keychain lock
+    // race). We MUST still surface the token + id so the user can capture and
+    // revoke it, then propagate the error — letting `?` swallow it would strand
+    // a live, unrevocable secret the user never saw.
+    let backend = match token_store::store(&args.name, &issued.token) {
+        Ok(backend) => backend,
+        Err(store_err) => {
+            // Best-effort surface; if even stdout is broken there is nothing
+            // more we can do, so ignore the write error and return the store
+            // failure that actually explains what went wrong.
+            let _ = print_unstored_token(out, err, args, &issued, &store_err);
+            return Err(store_err);
+        }
+    };
+
+    print_result(out, err, args, &issued, backend)
+        .map_err(|e| ActualError::InternalError(format!("failed to write token output: {e}")))
+}
+
+/// Print the mint result. The raw token goes to `out` on its own line (so
+/// `TOKEN=$(actual auth create-token …)` captures just the secret); all chrome
+/// and guidance go to `err`. The token is printed once here and never logged.
+/// In production `out` is stdout and `err` is stderr; tests pass buffers to
+/// assert the stdout=secret / stderr=chrome split.
+fn print_result(
+    out: &mut dyn Write,
+    err: &mut dyn Write,
+    args: &CreateTokenArgs,
+    issued: &pat::IssuedToken,
+    backend: token_store::Backend,
+) -> io::Result<()> {
+    writeln!(
+        err,
+        "{} Created scoped access token {}",
+        theme::success(&theme::SUCCESS),
+        theme::success(format!("\"{}\"", args.name))
+    )?;
+    if let Some(id) = &issued.id {
+        writeln!(err, "  {:<12} {}", "Token id:", id)?;
+    }
+    // Prefer the scopes the server granted; fall back to what was requested.
+    let scopes = if issued.scopes.is_empty() {
+        args.scopes.join(" ")
+    } else {
+        issued.scopes.join(" ")
+    };
+    writeln!(err, "  {:<12} {}", "Scopes:", scopes)?;
+    if let Some(exp) = &issued.expires_at {
+        writeln!(err, "  {:<12} {}", "Expires:", exp)?;
+    }
+    writeln!(err, "  {:<12} {}", "Stored in:", backend.label())?;
+    writeln!(err)?;
+    writeln!(err, "Your token is shown once below. Copy it now:")?;
+    writeln!(err)?;
+
+    // The single place the raw secret is emitted: stdout, alone, for capture.
+    writeln!(out, "{}", issued.token)?;
+
+    writeln!(err)?;
+    writeln!(err, "{}", theme::hint("Keep this secret safe:"))?;
+    writeln!(
+        err,
+        "  • Use a DEDICATED token per agent so actions are attributable and"
+    )?;
+    writeln!(
+        err,
+        "    individually revocable; never reuse your interactive login session."
+    )?;
+    writeln!(
+        err,
+        "  • NEVER paste it into a prompt, commit it, or echo it to logs/history."
+    )?;
+    writeln!(
+        err,
+        "  • For CI / non-interactive use, pass it via the ACTUAL_TOKEN env var."
+    )?;
+    Ok(())
+}
+
+/// Surface a token that was minted but could **not** be stored, so the user can
+/// still capture and revoke it. Preserves the same capture contract as the
+/// success path — the raw token on `out` (stdout) alone, everything else on
+/// `err` (stderr) — so a store failure after a successful server-side mint can
+/// never strand a live, unrevocable secret the user never saw.
+fn print_unstored_token(
+    out: &mut dyn Write,
+    err: &mut dyn Write,
+    args: &CreateTokenArgs,
+    issued: &pat::IssuedToken,
+    store_err: &ActualError,
+) -> io::Result<()> {
+    writeln!(
+        err,
+        "{} Minted token {} but could not store it: {}",
+        theme::error(&theme::ERROR),
+        theme::error(format!("\"{}\"", args.name)),
+        store_err
+    )?;
+    match &issued.id {
+        Some(id) => {
+            writeln!(err, "  {:<12} {}", "Token id:", id)?;
+            writeln!(err)?;
+            writeln!(
+                err,
+                "This token is LIVE on the server. Copy it below to use it now, or revoke it by the id above."
+            )?;
+        }
+        None => {
+            writeln!(err)?;
+            writeln!(
+                err,
+                "This token is LIVE on the server but no id was returned, so it cannot be revoked by id — capture it below, or rotate the credential if you cannot."
+            )?;
+        }
+    }
+    writeln!(err)?;
+    writeln!(err, "Your token is shown once below. Copy it now:")?;
+    writeln!(err)?;
+
+    // Same capture contract as the success path: the raw secret on stdout, alone.
+    writeln!(out, "{}", issued.token)?;
+
+    writeln!(err)?;
+    writeln!(
+        err,
+        "{}",
+        theme::warning("Storage failed — the token was NOT saved locally.")
+    )?;
+    writeln!(
+        err,
+        "  • Capture the token above now; it will not be shown again."
+    )?;
+    writeln!(
+        err,
+        "  • If you cannot capture it, revoke it by the id above so it is not left orphaned."
+    )?;
+    writeln!(
+        err,
+        "  • Fix the store ({}=file with {} set, or pass {} directly) and re-run.",
+        token_store::STORE_BACKEND_ENV,
+        token_store::PASSPHRASE_ENV,
+        token_store::ACTUAL_TOKEN_ENV
+    )?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::testutil::{EnvGuard, ENV_MUTEX};
+
+    #[test]
+    fn test_resolve_api_url_flag_wins() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g = EnvGuard::set("ACTUAL_API_URL", "http://env-url");
+        assert_eq!(resolve_api_url(Some("http://flag-url")), "http://flag-url");
+    }
+
+    #[test]
+    fn test_resolve_api_url_env_fallback() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g = EnvGuard::set("ACTUAL_API_URL", "http://env-url");
+        assert_eq!(resolve_api_url(None), "http://env-url");
+    }
+
+    #[test]
+    fn test_resolve_api_url_default() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g = EnvGuard::remove("ACTUAL_API_URL");
+        assert_eq!(resolve_api_url(None), DEFAULT_API_URL);
+    }
+
+    #[test]
+    fn test_resolve_api_url_empty_env_is_ignored() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g = EnvGuard::set("ACTUAL_API_URL", "");
+        assert_eq!(resolve_api_url(None), DEFAULT_API_URL);
+    }
+
+    #[tokio::test]
+    async fn test_ensure_fresh_no_refresh_token_unchanged() {
+        let mut creds = sample_creds();
+        creds.refresh_token = String::new();
+        let out = ensure_fresh(creds.clone()).await.unwrap();
+        assert_eq!(out.access_token, creds.access_token);
+    }
+
+    #[tokio::test]
+    async fn test_ensure_fresh_not_expired_unchanged() {
+        let mut creds = sample_creds();
+        creds.expires_at = Some(Utc::now() + ChronoDuration::hours(1));
+        let out = ensure_fresh(creds).await.unwrap();
+        assert_eq!(out.access_token, "session-token");
+    }
+
+    #[test]
+    fn test_run_not_logged_in() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g1 = EnvGuard::remove("ACTUAL_CONFIG");
+        let tmp = tempfile::tempdir().unwrap();
+        let _g2 = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+
+        let args = CreateTokenArgs {
+            name: "agent".to_string(),
+            scopes: vec!["adr:query".to_string()],
+            api_url: Some("http://127.0.0.1:1".to_string()),
+        };
+        // Not signed in → NotLoggedIn before any network work.
+        let err = exec(&args).unwrap_err();
+        assert!(matches!(err, ActualError::NotLoggedIn), "got: {err:?}");
+    }
+
+    #[tokio::test]
+    async fn test_run_happy_path_mints_and_stores() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g1 = EnvGuard::remove("ACTUAL_CONFIG");
+        let tmp = tempfile::tempdir().unwrap();
+        let _g2 = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        // Force the file backend so the test never touches the real keychain.
+        let _g3 = EnvGuard::set("ACTUAL_TOKEN_STORE", "file");
+        let _g4 = EnvGuard::set("ACTUAL_TOKEN_PASSPHRASE", "test-passphrase");
+        let _g5 = EnvGuard::remove("ACTUAL_TOKEN");
+
+        // Seed a logged-in session (no expiry → no refresh path).
+        store::save(&sample_creds()).unwrap();
+
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", pat::ISSUANCE_PATH)
+            .match_header("authorization", "Bearer session-token")
+            .with_status(201)
+            .with_header("content-type", "application/json")
+            .with_body(r#"{"token":"actl_pat_minted","id":"tok_9","scopes":["adr:query"]}"#)
+            .create_async()
+            .await;
+
+        let args = CreateTokenArgs {
+            name: "agent-z".to_string(),
+            scopes: vec!["adr:query".to_string()],
+            api_url: Some(server.url()),
+        };
+        run(&args).await.unwrap();
+        mock.assert_async().await;
+
+        // The minted token landed in the (encrypted-file) store, retrievable.
+        assert_eq!(
+            token_store::retrieve("agent-z").unwrap().as_deref(),
+            Some("actl_pat_minted")
+        );
+    }
+
+    #[tokio::test]
+    async fn test_ensure_fresh_refreshes_expired_token() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g1 = EnvGuard::remove("ACTUAL_CONFIG");
+        let tmp = tempfile::tempdir().unwrap();
+        let _g2 = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", "/api/oauth/token")
+            .with_status(200)
+            .with_header("content-type", "application/json")
+            .with_body(
+                r#"{"access_token":"refreshed","token_type":"Bearer","expires_in":3600,"refresh_token":"rotated"}"#,
+            )
+            .create_async()
+            .await;
+
+        // An expired access token plus a refresh token and a reachable auth server
+        // takes the refresh-and-re-persist branch.
+        let mut creds = sample_creds();
+        creds.auth_url = Some(server.url());
+        creds.expires_at = Some(Utc::now() - ChronoDuration::hours(1));
+        let out = ensure_fresh(creds).await.unwrap();
+        assert_eq!(out.access_token, "refreshed");
+        mock.assert_async().await;
+    }
+
+    #[tokio::test]
+    async fn test_run_prints_requested_scopes_and_expiry() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g1 = EnvGuard::remove("ACTUAL_CONFIG");
+        let tmp = tempfile::tempdir().unwrap();
+        let _g2 = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        let _g3 = EnvGuard::set("ACTUAL_TOKEN_STORE", "file");
+        let _g4 = EnvGuard::set("ACTUAL_TOKEN_PASSPHRASE", "test-passphrase");
+        let _g5 = EnvGuard::remove("ACTUAL_TOKEN");
+
+        store::save(&sample_creds()).unwrap();
+
+        // The server omits scopes (so the printed scopes fall back to the request)
+        // and includes an expiry (so the expiry line is printed).
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", pat::ISSUANCE_PATH)
+            .with_status(201)
+            .with_header("content-type", "application/json")
+            .with_body(r#"{"token":"actl_pat_exp","expires_at":"2030-01-01T00:00:00Z"}"#)
+            .create_async()
+            .await;
+
+        let args = CreateTokenArgs {
+            name: "exp-agent".to_string(),
+            scopes: vec!["adr:query".to_string()],
+            api_url: Some(server.url()),
+        };
+        run(&args).await.unwrap();
+        mock.assert_async().await;
+
+        assert_eq!(
+            token_store::retrieve("exp-agent").unwrap().as_deref(),
+            Some("actl_pat_exp")
+        );
+    }
+
+    #[test]
+    fn test_print_result_stdout_carries_only_the_token() {
+        // The stdout=secret / stderr=chrome split is a load-bearing security
+        // contract: `TOKEN=$(actual auth create-token …)` must capture ONLY the
+        // token. Assert stdout is exactly the token + newline, and the chrome
+        // went to stderr instead (never the secret).
+        let issued = sample_issued("actl_pat_only");
+        let args = sample_args("agent-x");
+        let mut out = Vec::new();
+        let mut err = Vec::new();
+        print_result(
+            &mut out,
+            &mut err,
+            &args,
+            &issued,
+            token_store::Backend::EncryptedFile,
+        )
+        .unwrap();
+
+        assert_eq!(String::from_utf8(out).unwrap(), "actl_pat_only\n");
+        let err_s = String::from_utf8(err).unwrap();
+        assert!(
+            err_s.contains("Created scoped access token"),
+            "chrome must go to stderr: {err_s}"
+        );
+        assert!(
+            !err_s.contains("actl_pat_only"),
+            "the secret must never leak to stderr: {err_s}"
+        );
+    }
+
+    #[test]
+    fn test_print_unstored_token_surfaces_token_and_id_on_failure() {
+        // On a post-mint store failure the token must STILL reach stdout (alone)
+        // and the id + a revoke hint must reach stderr, so the user can capture
+        // and revoke rather than be left with an orphaned, unrevocable token.
+        let issued = sample_issued("actl_pat_orphan");
+        let args = sample_args("agent-x");
+        let store_err = ActualError::ConfigError("keychain unavailable".to_string());
+        let mut out = Vec::new();
+        let mut err = Vec::new();
+        print_unstored_token(&mut out, &mut err, &args, &issued, &store_err).unwrap();
+
+        // Capture contract preserved even on failure: stdout carries ONLY the token.
+        assert_eq!(String::from_utf8(out).unwrap(), "actl_pat_orphan\n");
+        let err_s = String::from_utf8(err).unwrap();
+        assert!(
+            err_s.contains("could not store it"),
+            "stderr should explain the failure: {err_s}"
+        );
+        assert!(
+            err_s.contains("tok_42"),
+            "stderr should carry the token id for revocation: {err_s}"
+        );
+        assert!(
+            err_s.contains("LIVE on the server"),
+            "stderr should warn the token is live: {err_s}"
+        );
+        assert!(
+            !err_s.contains("actl_pat_orphan"),
+            "the secret must never leak to stderr: {err_s}"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_run_store_failure_after_mint_surfaces_token_and_errors() {
+        let _lock = ENV_MUTEX.lock().unwrap_or_else(|e| e.into_inner());
+        let _g1 = EnvGuard::remove("ACTUAL_CONFIG");
+        let tmp = tempfile::tempdir().unwrap();
+        let _g2 = EnvGuard::set("ACTUAL_CONFIG_DIR", tmp.path().to_str().unwrap());
+        // File backend + passphrase set → the precheck PASSES, so we exercise
+        // the *post-mint* failure path rather than the pre-mint refusal.
+        let _g3 = EnvGuard::set("ACTUAL_TOKEN_STORE", "file");
+        let _g4 = EnvGuard::set("ACTUAL_TOKEN_PASSPHRASE", "test-passphrase");
+        let _g5 = EnvGuard::remove("ACTUAL_TOKEN");
+
+        // Occupy the token subdirectory path with a regular FILE so the store's
+        // directory creation fails — a store failure that only surfaces AFTER
+        // the server-side mint has already succeeded.
+        std::fs::write(tmp.path().join("tokens"), b"not a directory").unwrap();
+
+        // Seed a logged-in session (writes credentials.json in tmp, unaffected
+        // by the tokens-file above).
+        store::save(&sample_creds()).unwrap();
+
+        let mut server = mockito::Server::new_async().await;
+        let mock = server
+            .mock("POST", pat::ISSUANCE_PATH)
+            .with_status(201)
+            .with_header("content-type", "application/json")
+            .with_body(r#"{"token":"actl_pat_stranded","id":"tok_77","scopes":["adr:query"]}"#)
+            .create_async()
+            .await;
+
+        let args = CreateTokenArgs {
+            name: "agent-fail".to_string(),
+            scopes: vec!["adr:query".to_string()],
+            api_url: Some(server.url()),
+        };
+
+        let mut out = Vec::new();
+        let mut err = Vec::new();
+        let result = run_inner(&mut out, &mut err, &args).await;
+        mock.assert_async().await;
+
+        // The store failed, so the command surfaces the error...
+        assert!(result.is_err(), "a post-mint store failure must propagate");
+        // ...but the minted token was STILL emitted to stdout, alone, so the
+        // user can capture and revoke it instead of orphaning a live token.
+        assert_eq!(String::from_utf8(out).unwrap(), "actl_pat_stranded\n");
+        let err_s = String::from_utf8(err).unwrap();
+        assert!(
+            err_s.contains("tok_77"),
+            "the id needed to revoke the stranded token must be surfaced: {err_s}"
+        );
+    }
+
+    #[test]
+    fn test_print_unstored_token_without_id_warns_no_revoke_by_id() {
+        // When the mint response carries no id, the store-failure surface must
+        // still emit the token (alone, on stdout) and warn that it cannot be
+        // revoked by id — the no-id arm of print_unstored_token.
+        let mut issued = sample_issued("actl_pat_noid");
+        issued.id = None;
+        let args = sample_args("agent-x");
+        let store_err = ActualError::ConfigError("keychain unavailable".to_string());
+        let mut out = Vec::new();
+        let mut err = Vec::new();
+        print_unstored_token(&mut out, &mut err, &args, &issued, &store_err).unwrap();
+
+        assert_eq!(String::from_utf8(out).unwrap(), "actl_pat_noid\n");
+        let err_s = String::from_utf8(err).unwrap();
+        assert!(
+            err_s.contains("no id was returned"),
+            "stderr should explain the token cannot be revoked by id: {err_s}"
+        );
+        assert!(
+            !err_s.contains("actl_pat_noid"),
+            "the secret must never leak to stderr: {err_s}"
+        );
+    }
+
+    /// A `Write` that succeeds `remaining` times and then fails. Sweeping
+    /// `remaining` drives the error-propagation (`?`) path of each `writeln!` at
+    /// every position, so a broken output stream is guaranteed to surface as an
+    /// error rather than a false success.
+    struct FailAfter {
+        remaining: usize,
+        tripped: bool,
+    }
+    impl std::io::Write for FailAfter {
+        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+            if self.remaining == 0 {
+                self.tripped = true;
+                return Err(std::io::Error::other("simulated write failure"));
+            }
+            self.remaining -= 1;
+            Ok(buf.len())
+        }
+        fn flush(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn test_print_result_propagates_stderr_write_failure() {
+        // print_result returns io::Result so a failed terminal write surfaces as
+        // an error instead of a false success. Sweep the failure point across
+        // the whole chrome sequence so every stderr writeln's `?` is exercised.
+        for n in 0..50 {
+            let issued = sample_issued("actl_pat_x");
+            let args = sample_args("agent-x");
+            let mut out: Vec<u8> = Vec::new();
+            let mut err = FailAfter {
+                remaining: n,
+                tripped: false,
+            };
+            let r = print_result(
+                &mut out,
+                &mut err,
+                &args,
+                &issued,
+                token_store::Backend::EncryptedFile,
+            );
+            if err.tripped {
+                assert!(
+                    r.is_err(),
+                    "a stderr write failure (after {n}) must propagate"
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn test_print_unstored_token_propagates_stderr_write_failure() {
+        // Same error-propagation contract for the store-failure surface, swept
+        // across both the has-id and no-id chrome so every writeln `?` (in both
+        // branches) is exercised.
+        for with_id in [true, false] {
+            for n in 0..50 {
+                let mut issued = sample_issued("actl_pat_x");
+                if !with_id {
+                    issued.id = None;
+                }
+                let args = sample_args("agent-x");
+                let store_err = ActualError::ConfigError("store down".to_string());
+                let mut out: Vec<u8> = Vec::new();
+                let mut err = FailAfter {
+                    remaining: n,
+                    tripped: false,
+                };
+                let r = print_unstored_token(&mut out, &mut err, &args, &issued, &store_err);
+                if err.tripped {
+                    assert!(
+                        r.is_err(),
+                        "a stderr write failure (id={with_id}, after {n}) must propagate"
+                    );
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn test_fail_after_flush_is_infallible() {
+        // FailAfter only fails writes, never flushes; exercise flush so the test
+        // writer is itself fully covered under the per-file 100% gate.
+        let mut w = FailAfter {
+            remaining: 3,
+            tripped: false,
+        };
+        assert!(std::io::Write::flush(&mut w).is_ok());
+    }
+
+    fn sample_issued(token: &str) -> pat::IssuedToken {
+        pat::IssuedToken {
+            token: token.to_string(),
+            id: Some("tok_42".to_string()),
+            name: Some("agent-x".to_string()),
+            scopes: vec!["adr:query".to_string()],
+            created_at: None,
+            expires_at: None,
+        }
+    }
+
+    fn sample_args(name: &str) -> CreateTokenArgs {
+        CreateTokenArgs {
+            name: name.to_string(),
+            scopes: vec!["adr:query".to_string()],
+            api_url: None,
+        }
+    }
+
+    fn sample_creds() -> StoredCredentials {
+        StoredCredentials {
+            access_token: "session-token".to_string(),
+            refresh_token: "refresh".to_string(),
+            token_type: "Bearer".to_string(),
+            expires_at: None,
+            scope: Some("adr:query".to_string()),
+            organization_id: "org-1".to_string(),
+            member_id: "member-1".to_string(),
+            email: None,
+            subject: None,
+            auth_url: Some("http://localhost:4000".to_string()),
+        }
+    }
+}
diff --git a/src/cli/commands/mod.rs b/src/cli/commands/mod.rs
index 4b7f41e0..e84006d7 100644
--- a/src/cli/commands/mod.rs
+++ b/src/cli/commands/mod.rs
@@ -11,6 +11,7 @@ pub mod advisor;
 pub mod auth;
 pub mod cache;
 pub mod config;
+pub mod create_token;
 pub mod login;
 pub mod logout;
 pub mod models;
diff --git a/src/lib.rs b/src/lib.rs
index 68bcb8ac..ef86b623 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -21,15 +21,16 @@ pub use error::ActualError;
 
 // Re-export CLI types for backward compatibility with tests
 pub use cli::args::{
-    AdvisorArgs, CacheAction, CacheArgs, Cli, Command, ConfigAction, ConfigArgs, ConfigSetArgs,
-    LoginArgs, ModelsArgs, RunnerChoice, StatusArgs, SyncArgs,
+    AdvisorArgs, AuthArgs, AuthCommand, CacheAction, CacheArgs, Cli, Command, ConfigAction,
+    ConfigArgs, ConfigSetArgs, CreateTokenArgs, LoginArgs, ModelsArgs, RunnerChoice, StatusArgs,
+    SyncArgs,
 };
 
 pub fn run(cli: Cli) -> Result<(), ActualError> {
     match &cli.command {
         Command::AdrBot(args) => cli::commands::sync::exec(args),
         Command::Status(args) => cli::commands::status::exec(args),
-        Command::Auth => cli::commands::auth::exec(),
+        Command::Auth(args) => cli::commands::auth::exec(args),
         Command::Login(args) => cli::commands::login::exec(args),
         Command::Logout => cli::commands::logout::exec(),
         Command::Whoami => cli::commands::whoami::exec(),
diff --git a/tests/lib_test.rs b/tests/lib_test.rs
index 86f662df..a2487f6d 100644
--- a/tests/lib_test.rs
+++ b/tests/lib_test.rs
@@ -146,7 +146,29 @@ fn test_cli_parse_status_defaults() {
 #[test]
 fn test_cli_parse_auth() {
     let cli = Cli::parse_from(["actual", "auth"]);
-    assert!(matches!(cli.command, Command::Auth));
+    assert!(matches!(cli.command, Command::Auth(_)));
+}
+
+#[test]
+fn test_cli_parse_auth_create_token() {
+    use actual_cli::AuthCommand;
+    let cli = Cli::parse_from([
+        "actual",
+        "auth",
+        "create-token",
+        "--name",
+        "ci-agent",
+        "--scopes",
+        "adr:query,adr:review",
+    ]);
+    let Command::Auth(auth) = cli.command else {
+        unreachable!()
+    };
+    let Some(AuthCommand::CreateToken(args)) = auth.command else {
+        unreachable!()
+    };
+    assert_eq!(args.name, "ci-agent");
+    assert_eq!(args.scopes, vec!["adr:query", "adr:review"]);
 }
 
 #[test]