@agentteams/cli 0.1.96 → 0.1.98

package/README.md

@@ -74,21 +74,63 @@ export AGENTTEAMS_DEVICE_AUTH=1
 authorization. To turn it back off, remove `"deviceAuth"` from
 `~/.agentteams/config.json` and unset `AGENTTEAMS_DEVICE_AUTH`.
 
-Before starting, the CLI checks that this machine has a usable OS credential store
-(macOS Keychain, Windows Credential Manager, or libsecret on Linux). On a minimal
-Linux server install `libsecret` and unlock a keyring, e.g.
-`sudo apt install libsecret-tools` — otherwise use `AGENTTEAMS_API_KEY` instead.
+#### Where the login is stored
+
+The personal login is a refresh token, and it has to survive the command that
+created it — otherwise the next command is signed out again.
+
+The CLI always prefers the OS credential store: macOS Keychain, Windows Credential
+Manager, or libsecret (Secret Service) on Linux. When that store cannot keep the
+token, the CLI falls back to a **permission-protected file** under
+`~/.agentteams/credentials`, one file per API server:
+
+- POSIX: directory `0700`, file `0600`, and the CLI refuses to read or write the
+  file if it is a symlink, is owned by another user, or is reachable by group or
+  other.
+- Windows: `icacls` removes inheritance and grants only the current account. If
+  that cannot be applied or verified, the file backend is **not** used at all.
+
+The fallback is triggered by the OS store failing, not by which platform you are
+on, because the three platforms fail at different moments. On Linux the failure is
+visible up front; on macOS and Windows the availability check passes and only the
+write fails, which is why an SSH login there used to be revoked _after_ you had
+already approved it on another device.
+
+A protected file is weaker than an OS keyring: it is not encrypted, so anyone who
+can read your files or gain root on that machine can read the token.
+`agentteams auth status` always names the backend that actually holds the token and
+repeats that warning. To forbid the fallback — the login then fails before asking
+you to approve anything, exactly as it did before:
+
+```bash
+export AGENTTEAMS_DISABLE_FILE_CREDENTIALS=1
+```
+
+This applies to `init --device-auth` and `auth login --device-auth` on Linux, macOS
+and Windows alike, including machines you only ever reach over SSH.
+
+The variable stops the CLI **writing** a credential file. A file written before you
+set it stays readable and removable, so `agentteams auth logout` can still revoke
+that token and delete it — otherwise setting the variable would strand a live login
+on disk with no command left that could reach it.
+
+`auth status` names the reason the OS store was skipped when this process is the one
+that discovered it — always on Linux, where the failure shows up before the login.
+On macOS and Windows the failure is only visible at the moment of a write, so a
+later `auth status` reports the backend without repeating why; re-run the login (or
+`auth logout` and back in) to see the OS store's own error again.
 
 #### Troubleshooting
 
-| Message                                                             | Cause                                                                  | What to do                                                        |
-| ------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| `OAuth callback timed out after 60 seconds.`                        | The default flow was used from a shell the browser cannot call back to | Re-run with `--device-auth`                                       |
-| `does not support device authorization`                             | The server is an older AgentTeams API                                  | Re-run **without** `--device-auth`, or upgrade the server         |
-| `device authorization turned off because the server has no APP_URL` | Server configuration                                                   | Ask the operator to set `APP_URL`; use the default flow meanwhile |
-| `The device code expired before it was approved`                    | The code is valid for 15 minutes                                       | Run the command again for a new code                              |
-| `The sign-in request was denied in the browser`                     | Deny was clicked                                                       | Run the command again if that was a mistake                       |
-| `Cannot start device authorization: ... credential store`           | No usable OS credential store                                          | Install/unlock libsecret, or use `AGENTTEAMS_API_KEY`             |
+| Message                                                              | Cause                                                                   | What to do                                                                                                                                                                                                                       |
+| -------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OAuth callback timed out after 60 seconds.`                         | The default flow was used from a shell the browser cannot call back to  | Re-run with `--device-auth`                                                                                                                                                                                                      |
+| `does not support device authorization`                              | The server is an older AgentTeams API                                   | Re-run **without** `--device-auth`, or upgrade the server                                                                                                                                                                        |
+| `device authorization turned off because the server has no APP_URL`  | Server configuration                                                    | Ask the operator to set `APP_URL`; use the default flow meanwhile                                                                                                                                                                |
+| `The device code expired before it was approved`                     | The code is valid for 15 minutes                                        | Run the command again for a new code                                                                                                                                                                                             |
+| `The sign-in request was denied in the browser`                      | Deny was clicked                                                        | Run the command again if that was a mistake                                                                                                                                                                                      |
+| `Cannot start device authorization: ... credential store`            | Neither the OS credential store nor the file fallback can keep a login  | Read the reason in brackets — it names both halves. Unset `AGENTTEAMS_DISABLE_FILE_CREDENTIALS` if you set it, or fix the OS store (install/unlock libsecret, unlock the macOS login keychain, sign in interactively on Windows) |
+| `Store: protected file (~/.agentteams/credentials)` in `auth status` | The OS credential store was unavailable, so the file fallback is in use | Nothing is broken. Fix the OS store if you want the stronger backend; on Linux the message after it names the reason, on macOS and Windows only the run that first fell back can show it                                         |
 
 ### Service URLs (Defaults and Overrides)
 
@@ -119,6 +161,24 @@ agentteams convention delete --file .agentteams/rules/context.md
 agentteams convention delete --file .agentteams/rules/context.md --apply
 ```
 
+## Breaking Changes
+
+Every resource command is now `<resource> <action>` with its own subcommand, so each action's `--help` lists only the
+options it actually reads. The following public arguments were removed in that move. Passing one fails at argument
+parsing with `unknown option` / `unknown command`, and the CLI prints a `hint:` line with the replacement.
+
+| Removed                                              | Replacement                                                                         |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `--format`                                           | Nothing — output is already JSON. Still available on `init`/`auth`/`sync`/`doctor`. |
+| `--api-key`                                          | `--api-key-file <path>` or `AGENTTEAMS_API_KEY`                                     |
+| `--team-id`                                          | `AGENTTEAMS_TEAM_ID` or the `teamId` config field                                   |
+| `--limit` (report/postmortem/coaction/document list) | `--page-size` (`search --limit` is unchanged)                                       |
+| `plan show`, `code-review show`, `task show`         | `get`                                                                               |
+| `plan issue`                                         | `plan link-issue` (`issue` stays as an alias for one release)                       |
+
+If an agent in your project still passes `--format json`, its convention copy is stale — run
+`agentteams convention download` to refresh it.
+
 ## Core Commands
 
 ### `init`
@@ -206,8 +266,7 @@ Note: Plans are always created as `BACKLOG`. Even if you pass `--status` to `pla
 ```bash
 agentteams plan list
 agentteams plan get --id <plan-id>
-agentteams plan get --id <plan-id> --include-deps --format text
-agentteams plan show --id <plan-id>  # alias of get
+agentteams plan get --id <plan-id> --include-deps
 agentteams plan status --id <plan-id>
 agentteams plan set-status --id <plan-id> --status <status>
 
@@ -377,8 +436,8 @@ agentteams search --query "auth" --types PLAN,CO_ACTION
 # Limit results and token budget (useful for agents)
 agentteams search --query "deployment" --limit 5 --max-tokens 4000
 
-# JSON output for automation
-agentteams search --query "refactor" --format json
+# Output is JSON by default, so it pipes straight into jq
+agentteams search --query "refactor"
 ```
 
 Searchable entity types: `PLAN`, `CO_ACTION`, `COMPLETION_REPORT`, `POST_MORTEM`, `CONVENTION`
@@ -423,7 +482,6 @@ Agents connected over MCP get the same dispatch as the `agentteams_resolve` tool
 
 ```bash
 agentteams config whoami
-agentteams config whoami --format text
 ```
 
 `config whoami` prints current environment variable values for `AGENTTEAMS_API_KEY` and `AGENTTEAMS_API_URL`.
@@ -469,9 +527,9 @@ export AGENTTEAMS_PROJECT_ID="proj_xxx"
 출력 계약은 다음과 같습니다.
 
 - 기본: 리소스·자동화 명령의 전체 JSON 결과를 stdout에 출력합니다.
-- 사람용 예외: `init`, `sync`, `doctor`는 사람이 읽기 쉬운 기본 출력을 유지합니다. 기계가 읽을 수 있는
-  결과가 필요하면 이 명령에 `--format json`을 전달합니다.
-- `--format json`: 기본 자동화 경로와 동일한 전체 JSON 결과를 명시적으로 선택합니다.
+- 사람용 예외: `init`, `auth`, `sync`, `doctor`는 사람이 읽기 쉬운 기본 출력을 유지합니다. 기계가 읽을 수
+  있는 결과가 필요하면 **이 네 명령에 한해** `--format json`을 전달합니다. 다른 명령에는 `--format`이
+  없습니다(기본 출력이 이미 JSON입니다).
 - `--output-file <path>`: 전체 결과를 파일에 저장한 뒤, 저장 경로와 간결한 요약을 stdout에 출력합니다.
 - `--verbose`: 전체 raw 결과를 stdout에 출력합니다. `--output-file`과 함께 사용하면 저장 경로 요약 뒤에
   전체 결과도 이어서 출력합니다.
@@ -500,11 +558,11 @@ agentteams plan upload-html \
 ```
 
 ```bash
-agentteams plan list --format json
-agentteams plan update --id <plan-id> --status IN_PROGRESS --format json
+agentteams plan list
+agentteams plan update --id <plan-id> --status IN_PROGRESS
 ```
 
-Note: `convention` does not support `--format`.
+Note: `--format` exists only on `init`, `auth`, `sync`, and `doctor`. Every other command already prints JSON.
 
 ## Error Guide
 

package/dist/auth/credentialStore.d.ts

@@ -1,5 +1,6 @@
 /**
- * OS-protected credential storage for the CLI.
+ * Credential storage for the CLI: the OS store when it works, a protected file
+ * when it does not.
  *
  * The CLI ships as a plain npm package, so a native addon (keytar and friends)
  * would add a build toolchain requirement to every install. Instead each
@@ -9,15 +10,28 @@
  *   Windows  `powershell`   (Windows.Security.Credentials.PasswordVault)
  *   Linux    `secret-tool`  (libsecret / Secret Service)
  *
- * When none of them is usable the store **refuses to persist**: nothing is
- * written to disk in plaintext, the secret is kept for this process only, and
- * the caller is told so it can point CI users at the long-lived `key_` path
- * instead. This mirrors `desktop/src/main/localAgent/credentialStore.ts`, which
- * declines to write when `safeStorage` is unavailable — the two must not drift.
+ * Any of them can be unusable in a remote session, and the three fail at
+ * different moments — Linux at the probe, macOS and Windows only once a write is
+ * attempted. That is why the fallback in {@link createFileCredentialStore} is
+ * triggered by **an OS backend failing**, never by the platform or by looking for
+ * SSH environment variables: the platform does not predict the failure, and the
+ * user-visible damage (a login approved on another device and then revoked) is
+ * identical in all three cases.
+ *
+ * The OS store always wins where it works, and a value that had to go to a file
+ * is promoted back into it only after a verified write. Setting
+ * `AGENTTEAMS_DISABLE_FILE_CREDENTIALS` restores the previous behaviour for new
+ * logins, in which an unusable OS store means the secret lives in this process
+ * only. That older behaviour still mirrors
+ * `desktop/src/main/localAgent/credentialStore.ts`, which declines to write when
+ * `safeStorage` is unavailable. The opt-out never hides a file this CLI already
+ * wrote — reading and removing one stay possible, so `logout` can still revoke it.
  */
 /** One keychain "service" groups every CLI credential under a single name. */
 export declare const CREDENTIAL_SERVICE = "agentteams-cli";
-export type CredentialBackendId = 'macos-keychain' | 'windows-credential-manager' | 'libsecret' | 'none';
+export type CredentialBackendId = 'macos-keychain' | 'windows-credential-manager' | 'libsecret'
+/** Permission-protected file under `~/.agentteams/credentials`. */
+ | 'protected-file' | 'none';
 /**
  * Why the store can (or cannot) persist.
  *
@@ -32,7 +46,16 @@ export interface CredentialStoreStatus {
     /** false → nothing is ever written to disk; the secret lives in this process only. */
     persisted: boolean;
     reason: CredentialStoreReason;
-    /** Masked backend error, present only once a write has actually failed. */
+    /**
+     * Why this backend, in the user's words. Masked before it is set, so it never
+     * carries a secret.
+     *
+     * Two things end up here: the error from a write the OS store rejected, and —
+     * when `backend` is `protected-file` — why the OS store was not used at all.
+     * The second is the only place a user can learn that their `secret-tool` is
+     * installed but cannot be started, which is otherwise indistinguishable from
+     * not having installed it.
+     */
     detail?: string;
 }
 export interface CredentialSaveOutcome {
@@ -85,7 +108,12 @@ export interface CredentialReadOptions {
     fresh?: boolean;
 }
 export interface CredentialStore {
-    status(): CredentialStoreStatus;
+    /**
+     * @param account - Report where *this* slot's credential actually lives.
+     *   Omitted, the answer is the store-wide "can anything be persisted here",
+     *   which is what a login preflight needs before there is a slot to ask about.
+     */
+    status(account?: string): CredentialStoreStatus;
     read(account: string, options?: CredentialReadOptions): string | null;
     save(account: string, secret: string): CredentialSaveOutcome;
     remove(account: string): void;
@@ -94,10 +122,24 @@ export interface CreateCredentialStoreOptions {
     runner?: CommandRunner;
     platform?: NodeJS.Platform;
     service?: string;
+    /** Home directory the file fallback lives under. Defaults to `os.homedir()`. */
+    homeDir?: string;
+    /** Consulted for `AGENTTEAMS_DISABLE_FILE_CREDENTIALS` and the Windows account name. */
+    env?: NodeJS.ProcessEnv;
 }
 export declare function isMissingItemStatus(backend: CredentialBackendId, status: number | null): boolean;
 export declare function resolveBackendId(platform: NodeJS.Platform): CredentialBackendId;
-/** Cheap "is this backend usable at all" call. Exit code 0 means yes. */
+/**
+ * Cheap "can this backend be driven at all" call. Exit code 0 means yes.
+ *
+ * Deliberately not a durability test. None of the three probes can prove a write
+ * would land: `security list-keychains` says nothing about whether the login
+ * keychain is unlocked, the PowerShell probe never touches the vault, and
+ * `secret-tool --version` says nothing about a Secret Service being on the bus.
+ * That is by design — the write itself, verified by reading the value back in
+ * {@link createCredentialStore}, is what decides persistence, and a probe that
+ * tried to be authoritative would have to write a secret to find out.
+ */
 export declare function buildProbeCommand(backend: CredentialBackendId): CredentialCommand | null;
 export declare function buildReadCommand(backend: CredentialBackendId, service: string, account: string): CredentialCommand | null;
 export declare function buildSaveCommand(backend: CredentialBackendId, service: string, account: string, secret: string): CredentialCommand | null;
@@ -110,6 +152,24 @@ export declare function buildRemoveCommand(backend: CredentialBackendId, service
  * before text reaches a log or an error message.
  */
 export declare function maskSecret(text: string, secret: string): string;
+/**
+ * Join the OS-side and file-side reasons a save had nowhere to go.
+ *
+ * Neither one alone is the answer once both backends are out: the OS reason is
+ * what the user already suspects, and the file reason is the one thing that
+ * explains why the fallback this CLI advertises did not stand in.
+ */
+export declare function combineDetails(osDetail?: string, fileDetail?: string): string | undefined;
+/**
+ * Turn a failed probe into advice.
+ *
+ * "No usable OS credential store" sent Linux users to `apt install
+ * libsecret-tools` even when it was already installed, because a tool that is
+ * present but exits non-zero looked exactly like a tool that is absent. The two
+ * need different next steps, and only the exit status tells them apart:
+ * `status: null` is "could not be spawned", anything else is "ran and refused".
+ */
+export declare function describeProbeFailure(command: CredentialCommand, result: CommandResult): string;
 export declare function createCredentialStore(options?: CreateCredentialStoreOptions): CredentialStore;
 /** Process-wide store. Tests build their own through {@link createCredentialStore}. */
 export declare function getCredentialStore(): CredentialStore;

package/dist/auth/credentialStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentialStore.d.ts","sourceRoot":"","sources":["../../src/auth/credentialStore.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"credentialStore.d.ts","sourceRoot":"","sources":["../../src/auth/credentialStore.ts"],"names":[],"mappings":"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"}

package/dist/auth/credentialStore.js

@@ -1,5 +1,6 @@
 /**
- * OS-protected credential storage for the CLI.
+ * Credential storage for the CLI: the OS store when it works, a protected file
+ * when it does not.
  *
  * The CLI ships as a plain npm package, so a native addon (keytar and friends)
  * would add a build toolchain requirement to every install. Instead each
@@ -9,13 +10,25 @@
  *   Windows  `powershell`   (Windows.Security.Credentials.PasswordVault)
  *   Linux    `secret-tool`  (libsecret / Secret Service)
  *
- * When none of them is usable the store **refuses to persist**: nothing is
- * written to disk in plaintext, the secret is kept for this process only, and
- * the caller is told so it can point CI users at the long-lived `key_` path
- * instead. This mirrors `desktop/src/main/localAgent/credentialStore.ts`, which
- * declines to write when `safeStorage` is unavailable — the two must not drift.
+ * Any of them can be unusable in a remote session, and the three fail at
+ * different moments — Linux at the probe, macOS and Windows only once a write is
+ * attempted. That is why the fallback in {@link createFileCredentialStore} is
+ * triggered by **an OS backend failing**, never by the platform or by looking for
+ * SSH environment variables: the platform does not predict the failure, and the
+ * user-visible damage (a login approved on another device and then revoked) is
+ * identical in all three cases.
+ *
+ * The OS store always wins where it works, and a value that had to go to a file
+ * is promoted back into it only after a verified write. Setting
+ * `AGENTTEAMS_DISABLE_FILE_CREDENTIALS` restores the previous behaviour for new
+ * logins, in which an unusable OS store means the secret lives in this process
+ * only. That older behaviour still mirrors
+ * `desktop/src/main/localAgent/credentialStore.ts`, which declines to write when
+ * `safeStorage` is unavailable. The opt-out never hides a file this CLI already
+ * wrote — reading and removing one stay possible, so `logout` can still revoke it.
  */
 import { spawnSync } from 'node:child_process';
+import { FILE_CREDENTIAL_BACKEND, createFileCredentialStore, isFileCredentialFallbackDisabled, } from './fileCredentialStore.js';
 /** One keychain "service" groups every CLI credential under a single name. */
 export const CREDENTIAL_SERVICE = 'agentteams-cli';
 const WINDOWS_SERVICE_ENV = 'AGENTTEAMS_CREDENTIAL_SERVICE';
@@ -74,7 +87,17 @@ export function resolveBackendId(platform) {
             return 'none';
     }
 }
-/** Cheap "is this backend usable at all" call. Exit code 0 means yes. */
+/**
+ * Cheap "can this backend be driven at all" call. Exit code 0 means yes.
+ *
+ * Deliberately not a durability test. None of the three probes can prove a write
+ * would land: `security list-keychains` says nothing about whether the login
+ * keychain is unlocked, the PowerShell probe never touches the vault, and
+ * `secret-tool --version` says nothing about a Secret Service being on the bus.
+ * That is by design — the write itself, verified by reading the value back in
+ * {@link createCredentialStore}, is what decides persistence, and a probe that
+ * tried to be authoritative would have to write a secret to find out.
+ */
 export function buildProbeCommand(backend) {
     switch (backend) {
         case 'macos-keychain':
@@ -166,11 +189,82 @@ export function maskSecret(text, secret) {
         return text;
     return text.split(secret).join('***');
 }
+/**
+ * Join the OS-side and file-side reasons a save had nowhere to go.
+ *
+ * Neither one alone is the answer once both backends are out: the OS reason is
+ * what the user already suspects, and the file reason is the one thing that
+ * explains why the fallback this CLI advertises did not stand in.
+ */
+export function combineDetails(osDetail, fileDetail) {
+    if (!osDetail)
+        return fileDetail;
+    if (!fileDetail)
+        return osDetail;
+    return `${osDetail}; the protected-file fallback also failed: ${fileDetail}`;
+}
+/**
+ * Turn a failed probe into advice.
+ *
+ * "No usable OS credential store" sent Linux users to `apt install
+ * libsecret-tools` even when it was already installed, because a tool that is
+ * present but exits non-zero looked exactly like a tool that is absent. The two
+ * need different next steps, and only the exit status tells them apart:
+ * `status: null` is "could not be spawned", anything else is "ran and refused".
+ */
+export function describeProbeFailure(command, result) {
+    if (result.status === null) {
+        return `${command.command} could not be started on this machine`;
+    }
+    const stderr = result.stderr.trim().split(/\r?\n/)[0] ?? '';
+    const suffix = stderr ? `: ${stderr}` : '';
+    return `${command.command} exited with status ${result.status} during the availability check${suffix}`;
+}
 export function createCredentialStore(options = {}) {
     const runner = options.runner ?? defaultRunner;
     const platform = options.platform ?? process.platform;
     const service = options.service ?? CREDENTIAL_SERVICE;
+    const env = options.env ?? process.env;
     const backend = resolveBackendId(platform);
+    /**
+     * The fallback.
+     *
+     * Always constructed, even under the opt-out: building it is free — nothing is
+     * created on disk until something asks whether it is usable, and nothing asks
+     * while the OS backend is working.
+     */
+    const fileStore = createFileCredentialStore({
+        platform,
+        runner,
+        env,
+        ...(options.homeDir === undefined ? {} : { homeDir: options.homeDir }),
+    });
+    /**
+     * Whether a *new* secret may go to a file.
+     *
+     * The opt-out stops here and goes no further. Making it hide the store
+     * outright would mean a machine that had already fallen back could no longer
+     * see its own credential file: `logout` would report nothing to revoke and
+     * delete nothing, leaving a live refresh token on disk that the CLI can never
+     * reach again — and reads would quietly fall through to whatever older value
+     * the OS store still had.
+     */
+    const fileWritesAllowed = !isFileCredentialFallbackDisabled(env);
+    /**
+     * Whether this slot's authoritative copy is the file one.
+     *
+     * Cheap on the healthy path (one `lstat` that finds nothing) and, critically,
+     * decided by what is actually on disk rather than by which backend answered
+     * first. A file copy only exists because an OS write failed, so it is by
+     * construction at least as new as anything the OS store still holds — and
+     * presenting the older one would be refresh-token reuse, which the server
+     * answers by revoking the whole family.
+     *
+     * The directory check is the non-creating one: the file's own protection is
+     * verified on every read anyway, and a directory question that answered "no"
+     * here would send the caller to the OS store's stale copy instead of failing.
+     */
+    const fileHolds = (account) => fileStore.has(account) && fileStore.check({ create: false }).ok;
     /**
      * Session-only fallback, and a read cache on top of a working backend.
      * A one-shot command barely benefits, but `agentteams mcp` runs for hours and
@@ -185,6 +279,8 @@ export function createCredentialStore(options = {}) {
      */
     const memoryOnlyAccounts = new Set();
     let availability = null;
+    /** Why the probe said no, kept so the fallback can explain itself. */
+    let probeFailureDetail = null;
     /**
      * Set once a write is rejected by a backend that passed the probe. From then
      * on `status()` tells the truth — "this store looks present but will not keep
@@ -201,10 +297,13 @@ export function createCredentialStore(options = {}) {
         }
         // A backend that cannot even be probed is treated as absent rather than as
         // an error: the caller's job is to fall back, not to fail the command.
-        availability = runner(probe).status === 0;
+        const result = runner(probe);
+        availability = result.status === 0;
+        probeFailureDetail = availability ? null : describeProbeFailure(probe, result);
         return availability;
     };
-    const status = () => {
+    /** What the OS backend alone would report — the contract before the fallback. */
+    const osStatus = () => {
         if (backend === 'none') {
             return { backend, persisted: false, reason: 'UNSUPPORTED_PLATFORM' };
         }
@@ -212,7 +311,49 @@ export function createCredentialStore(options = {}) {
             return { backend, persisted: false, reason: 'WRITE_FAILED', detail: writeFailureDetail };
         }
         const available = isAvailable();
-        return { backend, persisted: available, reason: available ? 'OK' : 'NO_BACKEND' };
+        if (available)
+            return { backend, persisted: true, reason: 'OK' };
+        return {
+            backend,
+            persisted: false,
+            reason: 'NO_BACKEND',
+            ...(probeFailureDetail === null ? {} : { detail: probeFailureDetail }),
+        };
+    };
+    const fileStatus = (osReason) => ({
+        backend: FILE_CREDENTIAL_BACKEND,
+        persisted: true,
+        reason: 'OK',
+        // Carrying the OS-side reason forward is what lets `auth status` say *why*
+        // the weaker backend is in play instead of leaving it looking like a choice —
+        // but only while this process holds that reason. It comes from the probe or
+        // from a rejected write, both process-local, so a later `auth status` on
+        // macOS or Windows (where the probe passes) reports the backend with no
+        // reason attached. Linux, whose probe fails outright, always has one.
+        ...(osReason.detail === undefined ? {} : { detail: osReason.detail }),
+    });
+    const status = (account) => {
+        const os = osStatus();
+        // A slot whose copy is in a file is in a file, even on a machine whose OS
+        // store works again — and even under the opt-out, which forbids new writes
+        // rather than disowning what is already there. Reporting the keychain here
+        // would describe a token that is not there.
+        if (account !== undefined && fileHolds(account))
+            return fileStatus(os);
+        if (os.reason === 'OK')
+            return os;
+        if (!fileWritesAllowed)
+            return os;
+        // Read-only: `status` is asked by `auth status` and by the login preflight,
+        // neither of which may leave a credential directory behind.
+        const fileReady = fileStore.check({ create: false });
+        if (fileReady.ok)
+            return fileStatus(os);
+        // Both backends are out, so both reasons matter: the caller is about to tell
+        // the user why a login cannot be saved, and the file-side half is the only
+        // half that is new.
+        const detail = combineDetails(os.detail, fileReady.detail);
+        return detail === undefined ? os : { ...os, detail };
     };
     /**
      * The backend's own answer, with no memory cache in front of it.
@@ -223,7 +364,7 @@ export function createCredentialStore(options = {}) {
      * claim there is nothing to revoke while a valid refresh token sits in the
      * store.
      */
-    const readFromBackend = (account) => {
+    const readFromOsBackend = (account) => {
         if (!isAvailable())
             return { kind: 'error', detail: 'the credential store is not available' };
         const command = buildReadCommand(backend, service, account);
@@ -240,6 +381,19 @@ export function createCredentialStore(options = {}) {
         const secret = result.stdout.replace(/\r?\n$/, '');
         return secret.length === 0 ? { kind: 'missing' } : { kind: 'found', secret };
     };
+    /**
+     * Whichever backend actually holds this slot.
+     *
+     * No fall-through from a file error to the OS store. A file that exists but
+     * cannot be trusted means the authoritative copy is unreadable, and answering
+     * with the OS store's older value would present a superseded refresh token —
+     * reuse, which the server punishes by revoking the whole family.
+     */
+    const readFromBackend = (account) => {
+        if (fileHolds(account))
+            return fileStore.read(account);
+        return readFromOsBackend(account);
+    };
     return {
         status,
         read(account, options) {
@@ -248,7 +402,7 @@ export function createCredentialStore(options = {}) {
             // authoritative copy for this account. Where a write could not be
             // persisted, memory is the only copy there is and consulting the backend
             // would throw the live credential away.
-            const reread = options?.fresh === true && isAvailable() && !memoryOnlyAccounts.has(account);
+            const reread = options?.fresh === true && (fileHolds(account) || isAvailable()) && !memoryOnlyAccounts.has(account);
             if (cached !== undefined && !reread)
                 return cached;
             const outcome = readFromBackend(account);
@@ -273,21 +427,45 @@ export function createCredentialStore(options = {}) {
                 memoryOnlyAccounts.add(account);
                 return detail === undefined ? { persisted: false, reason } : { persisted: false, reason, detail };
             };
+            /**
+             * Last resort before giving up on persistence.
+             *
+             * Only ever reached once the OS backend has already failed, so it can never
+             * demote a machine whose keychain works.
+             */
+            const saveToFile = (reason, detail) => {
+                if (!fileWritesAllowed)
+                    return markMemoryOnly(reason, detail);
+                // Both halves are carried, never one instead of the other: the OS-side
+                // reason alone reads as "your keychain is locked" on a machine where the
+                // real blocker is a read-only home directory the fallback could not use.
+                const ready = fileStore.check();
+                if (!ready.ok)
+                    return markMemoryOnly(reason, combineDetails(detail, ready.detail));
+                const written = fileStore.save(account, secret);
+                if (written.ok) {
+                    memoryOnlyAccounts.delete(account);
+                    return { persisted: true, reason: 'OK' };
+                }
+                return markMemoryOnly(reason, combineDetails(detail, written.detail));
+            };
             if (!isAvailable()) {
-                return markMemoryOnly(backend === 'none' ? 'UNSUPPORTED_PLATFORM' : 'NO_BACKEND');
+                return saveToFile(backend === 'none' ? 'UNSUPPORTED_PLATFORM' : 'NO_BACKEND', probeFailureDetail ?? undefined);
             }
             const command = buildSaveCommand(backend, service, account, secret);
             if (!command) {
-                return markMemoryOnly('NO_BACKEND');
+                return saveToFile('NO_BACKEND');
             }
             const result = runner(command);
             if (result.status !== 0) {
                 // Never thrown: the caller's contract is "you may not get persistence",
                 // and a rejected write is just another way of not getting it. Throwing
-                // here would kill the documented session-only fallback at the exact
-                // moment it is needed.
+                // here would kill the documented fallback at the exact moment it is
+                // needed — and on macOS and Windows this is the *only* point at which the
+                // failure is detectable, since both probes pass in a session that cannot
+                // write.
                 writeFailureDetail = maskSecret(`${result.stderr}`.trim(), secret) || 'the credential store rejected the write';
-                return markMemoryOnly('WRITE_FAILED', writeFailureDetail);
+                return saveToFile('WRITE_FAILED', writeFailureDetail);
             }
             // A zero exit is not proof the value landed. A backend tool that collects
             // the secret interactively can store something else entirely and still
@@ -299,21 +477,30 @@ export function createCredentialStore(options = {}) {
             // A read that fails is not evidence either way, so it is not treated as a
             // mismatch: doing so would revoke a token that did store, on nothing more
             // than a locked keychain.
-            const stored = readFromBackend(account);
+            const stored = readFromOsBackend(account);
             if (stored.kind === 'error') {
                 writeFailureDetail = `the write could not be verified: ${stored.detail}`;
-                return markMemoryOnly('WRITE_FAILED', writeFailureDetail);
+                return saveToFile('WRITE_FAILED', writeFailureDetail);
             }
             if (stored.kind === 'missing' || stored.secret !== secret) {
                 writeFailureDetail = 'the credential store did not keep the value that was written';
-                return markMemoryOnly('WRITE_FAILED', writeFailureDetail);
+                return saveToFile('WRITE_FAILED', writeFailureDetail);
             }
+            // The OS store has the value and has proved it by handing it back — and
+            // only now is the file copy redundant. Dropping it any earlier (on a zero
+            // exit, say) would delete the one usable copy of a token whose OS write
+            // silently stored nothing.
+            fileStore.remove(account);
             writeFailureDetail = null;
             memoryOnlyAccounts.delete(account);
             return { persisted: true, reason: 'OK' };
         },
         remove(account) {
             memory.delete(account);
+            // Both copies, unconditionally — including under the opt-out, which stops
+            // new writes and not this: a logout that cleared only the backend it
+            // happens to prefer today would leave a live refresh token behind.
+            fileStore.remove(account);
             if (!isAvailable())
                 return;
             const command = buildRemoveCommand(backend, service, account);