@letta-ai/dreams 0.0.1 → 0.0.4

package/README.md

@@ -15,50 +15,120 @@ npx @letta-ai/dreams@latest onboard --json
 
 1. verifies Node >= 22.13 through the bin preflight
 2. installs the exact CLI version under `~/.dreams/cli/<version>/`
-3. creates or preserves the stable launcher at `~/.dreams/bin/dreams`
+3. activates it through the stable launcher at `~/.dreams/bin/dreams`
 4. creates or preserves the installation id in `~/.dreams/installation.json`
-5. installs `~/.claude/skills/dreams-setup/SKILL.md`
+5. installs `~/.claude/skills/dreams-setup/` (skill + init snapshot template)
 6. initializes and migrates `~/.dreams/dreams.db`
-7. returns the next agent action based on authentication state
+7. returns a skill handoff (`status: "ready"`) with absolute `cli_path` and skill path
 
-It does not start login or `orient` itself. An unauthenticated response directs
-the agent to run `auth login` and then rerun `onboard`; an authenticated
-response directs the agent to run `orient`. Repeated calls are safe and return
-the same action until authentication state changes.
+It does **not** check authentication or choose login/orient next steps. The
+installed `dreams-setup` skill owns sequencing (authenticate → detect sources →
+init snapshot → approve directories + install consented hooks → optional
+background history import). SessionStart hooks call `dreams wake`; Stop hooks
+call `dreams sync`. Repeated `onboard` calls are safe and repair local setup
+only.
 
 ### Commands
 
-- `dreams onboard [--json]` — install or repair local setup and return the next
-  setup action.
-- `dreams status [--json]` — installation, durable CLI, SQLite, setup skill,
-  and authentication state.
+- `dreams onboard [--json]` — install or repair local setup and hand off to the
+  setup skill.
+- `dreams rollback [--json]` — reactivate the previous completed CLI version.
+- `dreams status [--json]` — installation, active and previous CLI versions,
+  SQLite, setup skill, and authentication state.
 - `dreams auth login [--json]` — OAuth device code sign-in (see Auth below).
-- `dreams auth status [--json]` — authentication state; tokens are masked
+- `dreams auth status [--json]` — authentication state; lists every discovered credential (`env` / `keychain` / `file`), which won and why, plus a hooks note that live sync inherits the harness process env; tokens are masked
   (`at-let-…abcd`), never printed.
 - `dreams auth logout [--json]` — best-effort revoke of Dreams' refresh token,
   then clear stored credentials.
+- `dreams dev reset local [--confirm] [--json]` — preview or remove only local
+  SQLite and blob state.
+- `dreams dev reset identity [--confirm] [--json]` — preview or remove local
+  state, stored Dreams credentials, and the installation identity.
 
 Local state lives in `~/.dreams/`. Requires Node >= 22.13, where built-in
 `node:sqlite` no longer requires the `--experimental-sqlite` flag.
 
-## Local sources (Claude Code)
+### CLI upgrades and rollback
+
+Installed CLI versions are immutable under `~/.dreams/cli/<version>/`. The
+atomic `~/.dreams/cli/activation.json` record selects the active version and
+retains one previous version. The stable launcher reads that record rather than
+pointing directly at a version.
+
+Run `dreams rollback` to reactivate the previous completed version. The launcher
+also rolls back automatically when an active CLI cannot reach its startup
+readiness marker, then retries the original command once. Normal command errors
+after readiness, including invalid arguments, authentication failures, and
+network failures, never trigger rollback.
+
+### Development reset
+
+Development resets are preview-only until `--confirm` is provided. `local`
+removes `dreams.db`, its SQLite sidecars, and `~/.dreams/blobs/`; it preserves
+credentials and the installation identity. `identity` removes those local files
+plus Dreams' stored credentials and `installation.json`, so the next `onboard`
+mints a new device identity. Both scopes preserve installed CLI versions, the
+stable launcher, the setup skill, and every Cloud resource. Confirmed resets
+hold the same local-state lock as onboarding, auth, source, and upload commands,
+so they fail instead of deleting files another process is using. If
+`DREAMS_CREDENTIALS_BACKEND=file` is forced, identity reset clears the file and
+explicitly reports that the OS keychain was not checked.
+
+Test-workspace cleanup is intentionally not available through this local CLI.
+It is a separate internal Cloud operation with different credentials and data
+cleanup semantics. `dreams dev reset test-workspace` fails without deleting
+anything.
+
+## Local sources (Claude Code and Codex)
 
 The CLI maintains a crash-safe local SQLite store (`~/.dreams/dreams.db`) that
-discovers Claude Code transcripts and prepares immutable upload segments before
-they are sent to Letta Cloud.
-
-- `dreams source approve-root <path> [--json]` — approve a work root. Sources
-  are **deny-by-default**: no transcript bytes are queued until their working
-  directory is under an approved root.
-- `dreams source scan [--json]` — discover top-level Claude Code sessions
-  (`~/.claude/projects/<project>/<sessionId>.jsonl`), read only complete new
-  lines after the durable cursor, and enqueue deterministic upload segments.
-  Repeated scans are idempotent; `.dreamignore` and unapproved roots are honored
-  before anything is enqueued.
-- `dreams source list [--json]` — show the DB path, approved roots, sources, and
-  the pending upload queue.
-- `dreams upload [--json]` — authenticate, register the source, and upload due
-  queue entries to Letta Cloud.
+discovers coding-agent transcripts and prepares immutable upload segments before
+they are sent to Letta Cloud. Harness behavior is selected with
+`--source <type>` (`claude-code` default; `codex`). One invocation always
+targets a single source — it never processes all sources at once.
+
+- `dreams source detect [--source <type>] [--json]` — detect a harness from
+  filesystem facts only (`~/.claude` or `~/.codex`; no transcript reads) and
+  register an installation-scoped Cloud source in status `detected`. Idempotent;
+  does not scan or upload.
+- `dreams source approve-dir <path> [--json]` (alias: `approve-root`) — approve a
+  work directory. Sources are **deny-by-default**: no transcript bytes are queued
+  until their working directory is under an approved folder (`.dreamignore`
+  still applies).
+- `dreams source scan [--source <type>] [--json]` — discover sessions for the
+  selected source (Claude: `~/.claude/projects/...`; Codex:
+  `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`), read only complete new lines
+  after the durable cursor, and enqueue deterministic upload segments. Repeated
+  scans are idempotent.
+- `dreams source list [--json]` — show the DB path, approved directories, sources,
+  and the pending upload queue.
+- `dreams snapshots create --type <type> --file <path> --client-request-id <id> [--workspace-id <id>] [--json]`
+  — submit a skill-authored JSON snapshot (256 KiB UTF-8 object cap) to
+  `POST /v1/dreams/workspaces/{workspaceId}/snapshots`. Workspace defaults to the
+  local binding from `source detect`.
+- `dreams hooks install [--source <type>] [--dry-run] [--json]` — install or
+  preview Claude Code / Codex live-sync hooks. SessionStart → `wake`, Stop →
+  `sync`. Prefer `--dry-run` for consent before writing.
+- `dreams wake [--source <type>] [--json]` — SessionStart entrypoint: quiet
+  managed CLI/skill repair, then force-kick the sync worker for pending
+  live/backfill drain (no stdin session hint). Always exits 0 for hook safety.
+- `dreams sync [--source <type>] [--force] [--json]` — Stop / live-turn
+  scheduler for one source: records a durable sync trigger (optional stdin
+  `session_id`) and runs a detached worker that live-scans tracked sessions and
+  uploads with a per-pass budget (~3h cadence unless `--force` or retry-due).
+- `dreams sync pause|resume [--json]` — global pause makes hook wakes no-ops;
+  resume clears pause and requests one immediate sync (not per-source).
+- `dreams sync status [--source <type>] [--json]` — per-source diagnostics
+  (`effective_state`, cadence/retry, worker). Codex status also reports
+  discovery health (`discovery.status` / reason codes) when rollout formats
+  drift.
+- `dreams backfill start --since <RFC3339> [--source <type>] [--json]` — approve
+  a frozen `[since, until=now]` historical window for one source and run one
+  bounded local scan/queue pass (session frontier, newest unfinished sessions
+  first; no upload). Policies are source-isolated. Re-running the same active
+  `--since` is idempotent; a different active policy fails closed. After
+  `backfill start`, kick with `dreams wake --source …` so draining does not wait
+  for the next session.
 
 Local cursors track a `queued_through_offset` (advanced as segments are queued)
 separately from an `acked_offset` (advanced only after durable Cloud
@@ -96,6 +166,12 @@ masks them. `DREAMS_CREDENTIALS_BACKEND=file|keychain` forces a backend
    when it is missing or expires within 5 minutes.
 3. Otherwise: a structured not-authenticated error (`dreams auth login`).
 
+`dreams auth status --json` reports that inventory explicitly: top-level
+`source` / `access_token` remain the winner for this process; `credentials[]`
+lists each backend with `present`, `selected`, and `reason`; `active` restates
+the winner; `hooks` notes that coding-agent hooks inherit the harness
+environment (a harness-set `LETTA_API_KEY` shadows stored OAuth).
+
 **Refresh rotation.** Refreshes use `refresh_token_mode: "new"`: the server
 always returns a *new* refresh token that revokes the old one for this
 (user, client, device). The CLI persists the rotated token immediately and
@@ -127,20 +203,20 @@ npm test                        # build + node:test suite (uses a temp HOME)
 ## Testing the npx bootstrap via tarball (no publish)
 
 ```sh
-npm pack                     # produces letta-ai-dreams-0.0.1.tgz
+npm pack                     # produces letta-ai-dreams-0.0.3.tgz
 cd "$(mktemp -d)"
-npx -y -p /absolute/path/to/dreams/letta-ai-dreams-0.0.1.tgz dreams onboard
+npx -y -p /absolute/path/to/dreams/letta-ai-dreams-0.0.3.tgz dreams onboard
 ```
 
 (The `-p <tarball> dreams` form is required: a bare `npx <tarball>` treats the
 path as a script to execute, not a package to install.)
 
 `onboard` writes to `~/.dreams/` and installs
-`~/.claude/skills/dreams-setup/SKILL.md`. Set `HOME` to a temporary directory
-for a sandboxed run.
+`~/.claude/skills/dreams-setup/` (including the init snapshot template). Set
+`HOME` to a temporary directory for a sandboxed run.
 
 ## Deferred
 
-- `orient` and its Cloud-backed setup actions
-- Shared-memory generation and review
-- Automated source configuration and historical backfill
+- Shared-memory repository generation and review
+- Hook installation and default Dream schedule creation
+- `dreams backfill start` (skill optional background history import)

package/bin/dreams-codex-hook.cjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Codex SessionStart/Stop hook launcher for Dreams.
+ *
+ * Codex Stop requires exactly one valid JSON object on stdout when exiting 0.
+ * Dreams CLI JSON must never leak into that stream. This wrapper:
+ *   1. Forwards hook stdin to `dreams <wake|sync> --source codex`
+ *   2. Suppresses all CLI stdout/stderr
+ *   3. Always prints `{}` and exits 0 (scheduling failures must not interrupt Codex)
+ *
+ * Usage:
+ *   node dreams-codex-hook.cjs <cli_path> [wake|sync]
+ * Default mode is `sync` (Stop / live turn). SessionStart should pass `wake`.
+ */
+"use strict";
+
+var spawnSync = require("node:child_process").spawnSync;
+var fs = require("node:fs");
+var path = require("node:path");
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0);
+  } catch {
+    return Buffer.alloc(0);
+  }
+}
+
+function quoteCmdArg(value) {
+  return '"' + String(value).replace(/"/g, '""') + '"';
+}
+
+function resolveMode(raw) {
+  if (raw === "wake" || raw === "sync") return raw;
+  return "sync";
+}
+
+/**
+ * Resolve how to invoke the durable Dreams CLI.
+ * On Windows the stable launcher is `dreams.cmd`, which cannot be spawnSync'd
+ * with shell:false. Prefer the sibling Node controller (`launcher.cjs`) when
+ * present (managed install layout); otherwise fall back to ComSpec with
+ * explicitly quoted paths so spaces work.
+ */
+function resolveInvocation(cliPath, mode) {
+  var args = [mode, "--source", "codex"];
+  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(cliPath)) {
+    var sibling = path.join(path.dirname(cliPath), "launcher.cjs");
+    try {
+      if (fs.statSync(sibling).isFile()) {
+        return { command: process.execPath, args: [sibling].concat(args), shell: false };
+      }
+    } catch {
+      // fall through to ComSpec
+    }
+    var cmdline = [quoteCmdArg(cliPath)].concat(args).join(" ");
+    return {
+      command: process.env.ComSpec || "cmd.exe",
+      args: ["/d", "/s", "/c", cmdline],
+      shell: false,
+    };
+  }
+  return { command: cliPath, args: args, shell: false };
+}
+
+function main() {
+  var cliPath = process.argv[2];
+  var mode = resolveMode(process.argv[3]);
+  var stdin = mode === "wake" ? Buffer.alloc(0) : readStdinSync();
+
+  if (typeof cliPath === "string" && cliPath.trim() !== "") {
+    try {
+      var invocation = resolveInvocation(cliPath, mode);
+      spawnSync(invocation.command, invocation.args, {
+        input: stdin,
+        encoding: "buffer",
+        stdio: ["pipe", "pipe", "pipe"],
+        windowsHide: true,
+        shell: invocation.shell,
+        env: process.env,
+      });
+    } catch {
+      // Tolerate missing launcher / spawn failures — hook must not interrupt Codex.
+    }
+  }
+
+  process.stdout.write("{}\n");
+  process.exit(0);
+}
+
+main();

package/bin/dreams.cjs

@@ -16,4 +16,25 @@ if (major < REQUIRED_MAJOR || (major === REQUIRED_MAJOR && minor < REQUIRED_MINO
   process.exit(1);
 }
 
+// node:sqlite still emits ExperimentalWarning on load; suppress only that noise
+// before requiring the CLI (which imports node:sqlite).
+(function suppressSqliteExperimentalWarning() {
+  var originalEmit = process.emit;
+  process.emit = function (event) {
+    if (event === 'warning' && arguments.length > 1) {
+      var warning = arguments[1];
+      if (
+        warning &&
+        typeof warning === 'object' &&
+        warning.name === 'ExperimentalWarning' &&
+        typeof warning.message === 'string' &&
+        /SQLite is an experimental feature|node:sqlite/i.test(warning.message)
+      ) {
+        return false;
+      }
+    }
+    return originalEmit.apply(process, arguments);
+  };
+})();
+
 require('../dist/cli.js').main();

package/dist/auth/commands.js

@@ -7,8 +7,8 @@
  * {"status":"authenticated",…} object once the user approves in the browser.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.commandAuthLogin = commandAuthLogin;
 exports.renderAuthStatus = renderAuthStatus;
+exports.commandAuthLogin = commandAuthLogin;
 exports.commandAuthStatus = commandAuthStatus;
 exports.commandAuthLogout = commandAuthLogout;
 const browser_1 = require("./browser");
@@ -17,12 +17,13 @@ const index_1 = require("./index");
 const credentials_1 = require("./credentials");
 const oauth_refresh_1 = require("./oauth-refresh");
 const oauth_1 = require("./oauth");
+const state_lock_1 = require("../local/state-lock");
 /** `auth login` short-circuits when the stored token is valid for >7 days. */
 const REAUTH_MARGIN_MS = 7 * 24 * 60 * 60 * 1000;
 function printJsonLine(value) {
     console.log(JSON.stringify(value));
 }
-async function commandAuthLogin(json) {
+async function commandAuthLoginUnlocked(json) {
     const stored = (0, credentials_1.loadCredentials)();
     if (stored && stored.credentials.access_token && !(0, credentials_1.expiresWithin)(stored.credentials, REAUTH_MARGIN_MS)) {
         if (json) {
@@ -96,22 +97,42 @@ async function commandAuthLogin(json) {
     }
 }
 function renderAuthStatus(info) {
+    const candidateLines = info.credentials.map((c) => {
+        const mark = c.selected ? "*" : " ";
+        const detail = c.present
+            ? `${c.access_token ?? "(no access token)"}` + (c.expires_at ? ` exp=${c.expires_at}` : "")
+            : "(absent)";
+        return `  ${mark} ${c.source.padEnd(9)} ${detail}\n      ${c.reason}`;
+    });
     if (!info.authenticated) {
         return [
             `Not authenticated — run \`dreams auth login\` to connect this device.`,
             ``,
             `  Device id: ${info.device_id}`,
+            ``,
+            `Credentials discovered:`,
+            ...candidateLines,
+            ``,
+            `Hooks: ${info.hooks.note}`,
         ].join("\n");
     }
     return [
         `Authenticated via ${info.source}`,
+        info.active ? `  Why: ${info.active.reason}` : ``,
         ``,
         `  Access token: ${info.access_token ?? "(none — will refresh on next use)"}`,
         `  Expires at:   ${info.expires_at ?? "(n/a — LETTA_API_KEY)"}`,
         `  Device id:    ${info.device_id}`,
-    ].join("\n");
+        ``,
+        `Credentials discovered (* = selected for this process):`,
+        ...candidateLines,
+        ``,
+        `Hooks: ${info.hooks.note}`,
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
 }
-function commandAuthStatus(json) {
+function commandAuthStatusUnlocked(json) {
     const info = (0, index_1.authStatusInfo)();
     if (json) {
         console.log(JSON.stringify(info, null, 2));
@@ -121,7 +142,7 @@ function commandAuthStatus(json) {
     }
     return 0;
 }
-async function commandAuthLogout(json) {
+async function commandAuthLogoutUnlocked(json) {
     const stored = (0, credentials_1.loadCredentials)();
     if (!stored) {
         if (json)
@@ -139,3 +160,44 @@ async function commandAuthLogout(json) {
         console.log("Logged out: refresh token revoked and local credentials cleared.");
     return 0;
 }
+function stateBusy(json) {
+    const message = "Another Dreams command is using local state. Try again after it finishes.";
+    if (json)
+        printJsonLine({ status: "error", code: "local_state_busy", message });
+    else
+        process.stderr.write(message + "\n");
+    return 1;
+}
+async function commandAuthLogin(json) {
+    const lock = (0, state_lock_1.acquireLocalStateLock)();
+    if (lock === null)
+        return stateBusy(json);
+    try {
+        return await commandAuthLoginUnlocked(json);
+    }
+    finally {
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+    }
+}
+function commandAuthStatus(json) {
+    const lock = (0, state_lock_1.acquireLocalStateLock)();
+    if (lock === null)
+        return stateBusy(json);
+    try {
+        return commandAuthStatusUnlocked(json);
+    }
+    finally {
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+    }
+}
+async function commandAuthLogout(json) {
+    const lock = (0, state_lock_1.acquireLocalStateLock)();
+    if (lock === null)
+        return stateBusy(json);
+    try {
+        return await commandAuthLogoutUnlocked(json);
+    }
+    finally {
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+    }
+}

package/dist/auth/credentials.js

@@ -47,6 +47,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EXPIRY_MARGIN_MS = exports.NotAuthenticatedError = void 0;
 exports.credentialsFilePath = credentialsFilePath;
 exports.loadCredentials = loadCredentials;
+exports.probeStoredCredentialBackends = probeStoredCredentialBackends;
 exports.saveCredentials = saveCredentials;
 exports.clearCredentials = clearCredentials;
 exports.expiresWithin = expiresWithin;
@@ -108,15 +109,26 @@ function keychainRead(account) {
         return null; // no entry, or keychain unusable — fall through to file
     }
 }
-function keychainDelete(account) {
+function keychainDelete(account, strict) {
     const ctor = keyringCtor();
-    if (!ctor)
-        return;
+    if (!ctor) {
+        if (backendOverride() === "file")
+            return "not_checked_file_backend";
+        if (strict) {
+            throw new Error("Could not verify OS keychain cleanup because @napi-rs/keyring is unavailable. " +
+                "Rerun where keychain support is available.");
+        }
+        return "unavailable";
+    }
     try {
         new ctor(KEYCHAIN_SERVICE, account).deleteCredential();
+        return "cleared";
     }
-    catch {
-        // already gone or keychain unusable
+    catch (error) {
+        if (strict) {
+            throw new Error(`Could not clear Dreams credentials from the OS keychain: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return "unavailable";
     }
 }
 // --- file backend ------------------------------------------------------------
@@ -155,6 +167,23 @@ function warnKeychainUnavailable() {
     process.stderr.write("Warning: OS keychain unavailable — storing credentials in ~/.dreams/credentials.json (mode 0600).\n");
 }
 // --- public API ---------------------------------------------------------------
+function credentialsFromKeychainRaw(refresh, accessRaw) {
+    let access_token = "";
+    let expires_at = EPOCH_ISO;
+    if (accessRaw) {
+        try {
+            const parsed = JSON.parse(accessRaw);
+            if (typeof parsed.access_token === "string")
+                access_token = parsed.access_token;
+            if (typeof parsed.expires_at === "string")
+                expires_at = parsed.expires_at;
+        }
+        catch {
+            // stale/foreign entry shape — treat access token as expired
+        }
+    }
+    return { access_token, refresh_token: refresh, expires_at };
+}
 /**
  * Load stored credentials: keychain first, then the file fallback (covers
  * installs where an earlier save fell back to the file).
@@ -162,25 +191,66 @@ function warnKeychainUnavailable() {
 function loadCredentials() {
     const refresh = keychainRead(REFRESH_ACCOUNT);
     if (refresh) {
-        let access_token = "";
-        let expires_at = EPOCH_ISO;
-        const accessRaw = keychainRead(ACCESS_ACCOUNT);
-        if (accessRaw) {
-            try {
-                const parsed = JSON.parse(accessRaw);
-                if (typeof parsed.access_token === "string")
-                    access_token = parsed.access_token;
-                if (typeof parsed.expires_at === "string")
-                    expires_at = parsed.expires_at;
+        return {
+            credentials: credentialsFromKeychainRaw(refresh, keychainRead(ACCESS_ACCOUNT)),
+            source: "keychain",
+        };
+    }
+    const fromFile = fileRead();
+    return fromFile ? { credentials: fromFile, source: "file" } : null;
+}
+/**
+ * Inspect each stored backend independently for `auth status` inventory.
+ * Unlike `loadCredentials()`, this does not stop after keychain wins — file is
+ * still reported when both exist. Never throws (forced-keychain misconfig →
+ * unavailable).
+ */
+function probeStoredCredentialBackends() {
+    let keychain;
+    if (backendOverride() === "file") {
+        keychain = { status: "not_checked", credentials: null };
+    }
+    else {
+        try {
+            const ctor = requireKeyring();
+            if (!ctor) {
+                keychain = { status: "unavailable", credentials: null };
             }
-            catch {
-                // stale/foreign entry shape — treat access token as expired
+            else {
+                let refresh = null;
+                let accessRaw = null;
+                try {
+                    refresh = new ctor(KEYCHAIN_SERVICE, REFRESH_ACCOUNT).getPassword() ?? null;
+                }
+                catch {
+                    refresh = null;
+                }
+                try {
+                    accessRaw = new ctor(KEYCHAIN_SERVICE, ACCESS_ACCOUNT).getPassword() ?? null;
+                }
+                catch {
+                    accessRaw = null;
+                }
+                if (refresh) {
+                    keychain = {
+                        status: "present",
+                        credentials: credentialsFromKeychainRaw(refresh, accessRaw),
+                    };
+                }
+                else {
+                    keychain = { status: "absent", credentials: null };
+                }
             }
         }
-        return { credentials: { access_token, refresh_token: refresh, expires_at }, source: "keychain" };
+        catch {
+            keychain = { status: "unavailable", credentials: null };
+        }
     }
     const fromFile = fileRead();
-    return fromFile ? { credentials: fromFile, source: "file" } : null;
+    const file = fromFile
+        ? { status: "present", credentials: fromFile }
+        : { status: "absent", credentials: null };
+    return { keychain, file };
 }
 /** Persist credentials: keychain if usable, else the 0600 file (with a warning). */
 function saveCredentials(credentials) {
@@ -202,10 +272,19 @@ function saveCredentials(credentials) {
     fileWrite(credentials);
 }
 /** Clear both backends (login/logout/invalid_grant paths). */
-function clearCredentials() {
-    keychainDelete(REFRESH_ACCOUNT);
-    keychainDelete(ACCESS_ACCOUNT);
+function clearCredentials(options = {}) {
+    const strict = options.strictKeychain === true;
+    const refresh = keychainDelete(REFRESH_ACCOUNT, strict);
+    const access = keychainDelete(ACCESS_ACCOUNT, strict);
     fs.rmSync(credentialsFilePath(), { force: true });
+    return {
+        file: "cleared",
+        keychain: refresh === "not_checked_file_backend" || access === "not_checked_file_backend"
+            ? "not_checked_file_backend"
+            : refresh === "cleared" && access === "cleared"
+                ? "cleared"
+                : "unavailable",
+    };
 }
 function expiresWithin(credentials, marginMs = exports.EXPIRY_MARGIN_MS) {
     const at = Date.parse(credentials.expires_at);