mixdog 1.3.4 → 1.3.5

package/src/defaults/skills/setup/references/surfaces.md

@@ -8,7 +8,7 @@ or requests a setting with no mutation action.
 | Target | Destination |
 |---|---|
 | `settings` | Settings home |
-| `providers` | Provider authentication and local providers |
+| `providers` | Provider authentication |
 | `model` | Main model selection |
 | `websearch` | Web Search route |
 | `workflow` | Workflow packs |
@@ -17,51 +17,77 @@ or requests a setting with no mutation action.
 | `theme` | Theme surface where supported |
 | `profile` | User profile |
 | `autoclear` | Session lifecycle controls |
-| `memory` | Memory capability surface |
-| `mcp` | Extensions → Skill → MCP, including OAuth Connect/Reconnect/Disconnect |
-| `skills` | Extensions → Skill → Skills |
-| `plugins` | Extensions → Plugin |
+| `memory` | Memory capability surface (Built-in card on the Extensions tab) |
+| `mcp` | Extensions → Connectors tab, including OAuth Connect/Reconnect/Disconnect |
+| `skills` | Skills (activity rail destination) |
+| `plugins` | Extensions → Extensions tab (plugins that bring MCP servers: Connectors → Custom connectors) |
 | `update` | Update surface |
-| `usage` | Provider usage sign-in |
+| `usage` | The /usage surface (provider usage); no sign-in |
 | `doctor` | Runtime diagnostics |
 | `context` | Context and compaction |
 | `developer` | Developer options (TUI: Developer picker) |
-| `voice` | Voice built-in (TUI: Settings hub) |
+| `voice` | Voice Built-in card on the Extensions tab (TUI: Settings hub) |
 | `connection` | Web-app pairing; Desktop only, the TUI shows guidance |
 
 An attached Desktop or TUI may navigate and return `opened:true`.
 
 ## Desktop map
 
-- Settings → General: profile, Web Search exposure, display language,
-  side panels, and notifications.
-- Settings → Context: auto-compact and auto-clear.
+- Settings → General: profile; Features (Regular check-ins, Reactions, Web
+  search, import conversations from other apps (UI-only), Load instruction
+  files, Auto reasoning base, link preview); notifications; worktree
+  defaults; display language, time format, side panels and their position;
+  markdown default view.
+- Settings → Context: Let AI rename sessions, auto-compact (also on model
+  change, summary model) and auto-clear.
+- Settings → Model management: "Show in /model" and favorites per model.
 - Settings → Output style: output style selection, plus the desktop-only
   "Expand tool activity" choice (collapsed / commands and edits / everything),
   saved per device; Ctrl+O toggles everything open for the current window.
-- Settings → Theme (one page): System / Dark / Light or a skin picture
-  (plate, accent, transparency), imported JSON color themes (about 26 color
-  roles), installed fonts, font sizes and chat text size. Saved on this device
-  only. First-run setup has a Theme step with the same System / Dark /
-  Light / skin choice.
+- Settings → Theme (one page): System / Dark / Light (`theme: "white"`) or a
+  skin picture (plate, accent, photo, transparency), imported JSON color
+  themes (about 26 color roles; import/export/remove are UI-only), installed
+  fonts, font sizes and chat text size. Saved on this device only. First-run
+  setup has a Theme step with the same System / Dark / Light / skin choice.
 - Settings → Bots (desktop only): the representative bot overlay, a small
   window with the representative bot that opens a quick message to it. On
-  by default; options to pin it above the message box (default on), keep it
-  above other windows (default off: it follows the app window's layer),
-  collapse its bubble and reset its position. The overlay's right-click
-  menu has the same options. Saved on this PC.
-- Settings → Providers: API-key, OAuth, custom provider registration, local
-  providers, and usage sign-in. A custom provider's model list waits up to
-  60 s, can be skipped, and then takes model ids typed by hand.
-- Extensions → Plugin → Git & GitHub: Git/GitHub CLI installation and connection.
-- Settings → Connection: web-app pairing and linked devices.
+  by default; options: enable, Position (4-way: pinned above the message box
+  (default), pinned here, free in the app window, free on screen), keep above
+  other windows (default off), collapse bubble, auto-advance long replies,
+  close replies automatically, size, and reset position (UI-only). The
+  overlay's right-click menu has the same options. Saved on this PC.
+- Settings → Providers: API-key and OAuth authentication, custom provider
+  registration, and Usage limits (resume automatically). A custom provider's
+  model list waits up to 60 s, can be skipped, and then takes model ids typed
+  by hand. Local models are managed in the Local Provider Built-in detail.
+- Settings → Connection (desktop only): web-app pairing, this PC's name and
+  the remote-access switch, connected devices (rename, Disconnect all), "PCs
+  I opened", SSH servers (per-server settings, server logins, cleanup), and
+  "Reopen server windows". Only `revoke_linked_device` has a tool action.
+  SSH connect: the address dialog's collapsed "Advanced options" take a login
+  key file (typed or browsed) and a default server folder; the key file is
+  used for every later connection to that server (reconnects included), and a
+  server is saved only after a connection with those settings worked. A server
+  that is connected already refuses a changed key or folder: disconnect first.
+  Per-server "Model login" is "This PC's accounts" (the default; models run
+  through this PC, only while it is connected) or "Server accounts" (models run
+  with the logins signed in on the server). "Manage server logins" (Server
+  accounts, connected server) logs a provider in or out on the server; an API
+  key saved there is kept in a private file (owner-only) when the server has
+  no keychain, as on Linux. Changing the model login restarts the server's
+  Mixdog after one confirmation and stops its running sessions.
 - Settings → System: update, keep-awake, run in background after the window
   closes, and Doctor.
-- Settings → Developer options: risk-gated OAuth providers.
+- Settings → Developer options: data-driven sections (approvals, risk-gated
+  providers); read them with `status developer`.
 - Projects: Project registration, name, Project Memories, and Common Memory.
 - Workflows: workflow packs, Main and Web Search defaults, and agent editing.
-- Extensions → Plugin: Built-in cards and plugins.
-- Extensions → Skill: skills and MCP servers.
+- Extensions → Extensions tab: Built-in cards (including Git & GitHub, Media
+  generation and its Default generator) and plugins.
+- Extensions → Connectors tab: MCP servers and catalog connectors (Gmail
+  connects only with an app password; Calendar and Drive offer "Use my
+  Google key"), plus Custom connectors (including plugin MCP servers).
+- Skills (activity rail): skills.
 
 Provider authentication is intentionally hidden from the remote web app; guide
 the user to Desktop.
@@ -75,8 +101,8 @@ install or toggles run through the attached Desktop; the receipt identifies
 
 Computer observe-only and background Memory cycles (`set_recap_enabled`)
 have no settings control in either app; setup is their only supported route.
-Usage pin and the short + long rail bars live in the usage card's flyout menu
-on the activity rail.
+Usage pin, the short + long rail bars, expanded accounts and rail slots live
+in the usage card's flyout menu on the activity rail.
 
 Schedules/webhooks and workflow/agent/skill definitions use their runtime
 actions directly. These do not require clicking their Desktop rails.
@@ -85,16 +111,23 @@ actions directly. These do not require clicking their Desktop rails.
 
 The setup tool does not mutate:
 
-- API keys, OAuth, usage sign-in, and GitHub CLI connection;
+- API keys, OAuth, and GitHub CLI connection;
+- turning on the developer option "Allow all actions" (only the person turns
+  it on; `set_developer_option` can turn it off);
+- custom provider registration and edits (non-secret fields included), group
+  room options, bot persona and avatar, import conversations, reset overlay
+  position, SSH and remote-access settings, sidebar/list ordering and other
+  per-device view state;
 - MCP server OAuth sign-in and sign-out (Desktop MCP list/editor, TUI
   `/mcp login` and `/mcp logout`; remote windows paste the redirect address);
 - notification permission and subscription on the receiving device;
 - web-app pairing credentials and OS permission dialogs;
 - TUI-local theme palettes (use `/theme`; Desktop themes are separate);
-- importing or exporting a JSON color theme file, choosing a skin or custom
-  skin picture, and the Lead's pixel face (stored on the host as `leadAvatar`,
-  edited from the Desktop or a paired client, and shared by all of them; every
-  Lead-class row and agent wears it, and the agent edit dialog has no avatar);
+- importing, exporting or removing a JSON color theme file, choosing a skin or
+  custom skin picture (plate, accent, photo), and the Lead's pixel face
+  (stored on the host as `leadAvatar`, edited from the Desktop or a paired
+  client, and shared by all of them; bots and Mixy have per-bot avatars in
+  the bot profile editor; only the Workflows agent editor has none);
 - approval grants ("항상 허용" is per feature and per bot, never for payment,
   permanent delete, Lead, workflow, Mixy link, group rooms or schedules) and
   browser action confirmations (`MIXDOG_BROWSER_CONFIRM_ACTIONS`,

package/src/defaults/skills/setup-guide/SKILL.md

@@ -67,9 +67,9 @@ connector links an outside service so bots and agents can read and act in it,
 and anything that sends or posts asks first through an approval card. Then
 suggest by what the user does, only these: Gmail (with a Google app password;
 it needs 2-Step Verification on the Google account, and the connect window
-opens the app-password page in the browser), Notion, Linear or Jira. GitHub is
-not a connector; it is the signed-in GitHub CLI of Git & GitHub. Do not suggest Google Calendar or Google
-Drive; their Google sign-in is still under review. Connect one with
+opens the app-password page in the browser), Google Calendar, Google Drive
+(both with the Google sign-in), Notion, Linear or Jira. GitHub is
+not a connector; it is the signed-in GitHub CLI of Git & GitHub. Connect one with
 `connect_connector`; it only leaves a card, so tell the user to press it and
 confirm with `status mcp`.
 

package/src/lib/keychain-cjs.cjs

@@ -341,12 +341,81 @@ function keychainDebug(what, detail) {
   if (process.env.MIXDOG_KEYCHAIN_DEBUG) console.error(`[keychain:debug] ${what}: ${String(detail).slice(0, 500)}`);
 }
 
+// A keychain failure that POSITIVELY means "this host has no usable provider"
+// (secret-tool or libsecret missing, no Secret Service on the bus) as opposed to
+// a keyring that exists but is locked, or any failure nobody recognises. Only
+// the former is served by the private secrets file (see "Linux fallback file");
+// a locked keyring must be unlocked, and an unknown error fails closed.
+const KEYRING_UNAVAILABLE = 'KEYRING_UNAVAILABLE';
+
+function keyringUnavailable(message) {
+  return Object.assign(new Error(message), { code: KEYRING_UNAVAILABLE });
+}
+
+// What secret-tool/libsecret/D-Bus print when there is no provider at all:
+// libsecret missing from the loader, no D-Bus session bus to talk to, or no
+// service owning org.freedesktop.secrets. Anything else is NOT matched.
+const NO_PROVIDER_STDERR = new RegExp(
+  [
+    'error while loading shared libraries: libsecret',
+    'libsecret-1\\.so[^\\n]*cannot open shared object',
+    'org\\.freedesktop\\.DBus\\.Error\\.ServiceUnknown',
+    'org\\.freedesktop\\.DBus\\.Error\\.NameHasNoOwner',
+    'org\\.freedesktop\\.DBus\\.Error\\.NoServer',
+    'org\\.freedesktop\\.secrets was not provided by any \\.service files',
+    'name org\\.freedesktop\\.secrets (?:is not|has no owner)',
+    'Cannot autolaunch D-Bus without X11',
+    'Unable to autolaunch a dbus-daemon without a \\$DISPLAY',
+    'Failed to execute child process .{0,6}dbus-launch',
+    'Could not connect: (?:No such file or directory|Connection refused)',
+    'Failed to connect to (?:socket|bus)[^\\n]*(?:No such file or directory|Connection refused)',
+    'Error (?:connecting|spawning command line)[^\\n]*dbus',
+    'Cannot spawn a message bus',
+  ].join('|'),
+  'i'
+);
+
+const SECRET_TOOL_MISSING_MESSAGE =
+  '[keychain] secret-tool is not installed — install libsecret-tools (sudo apt install libsecret-tools), ' +
+  'or set the relevant MIXDOG_*/PROVIDER_API_KEY environment variable instead';
+
+// Bounded, non-prompting availability probe: `secret-tool --version` never
+// touches the keyring. Resolves true only when the spawn itself reports ENOENT;
+// an existing tool, a timeout or any other failure is "not confirmed missing".
+function secretToolMissing() {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('secret-tool', ['--version'], {
+        env: secretToolEnv(),
+        stdio: ['ignore', 'ignore', 'ignore'],
+        shell: false,
+        windowsHide: true,
+      });
+    } catch (error) {
+      resolve(error?.code === 'ENOENT');
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {}
+      resolve(false);
+    }, 2000);
+    child.once('error', (error) => {
+      clearTimeout(timer);
+      resolve(error?.code === 'ENOENT');
+    });
+    child.once('close', () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+  });
+}
+
 function secretToolCheck(r) {
   if (r.error?.code === 'ENOENT') {
-    throw new Error(
-      '[keychain] secret-tool is not installed — install libsecret-tools (sudo apt install libsecret-tools), ' +
-        'or set the relevant MIXDOG_*/PROVIDER_API_KEY environment variable instead'
-    );
+    throw keyringUnavailable(SECRET_TOOL_MISSING_MESSAGE);
   }
   if (r.error?.code === 'ETIMEDOUT') {
     throw new Error(
@@ -355,6 +424,8 @@ function secretToolCheck(r) {
     );
   }
   if (r.error) {
+    // Not ENOENT: an unknown start failure (EACCES, resource limits) is not
+    // proof that no provider exists, so it fails closed instead of falling back.
     keychainDebug('secret-tool failed to start', r.error.message);
     throw new Error(
       '[keychain] secret-tool could not be started — check that libsecret-tools is installed and a Secret Service is running'
@@ -439,13 +510,16 @@ function secretToolFailure(action, r) {
   const detail = (r.stderr || '').trim() || `exit ${r.status}`;
   // User-facing text is fixed; the raw tool output only goes to the debug log.
   keychainDebug(`secret-tool ${action} failed`, detail);
-  if (/locked|denied|dismissed|cancel|not authori[sz]ed|IsLocked/i.test(detail)) {
+  if (/locked|unlock|denied|dismissed|cancel|not authori[sz]ed|IsLocked/i.test(detail)) {
     return new Error(
       `[keychain] secret-tool ${action} failed: the keyring is locked or the unlock prompt was declined. ` +
         'Unlock your keyring and retry.'
     );
   }
-  return new Error(`[keychain] secret-tool ${action} failed — ${secretToolHint()}`);
+  const message = `[keychain] secret-tool ${action} failed — ${secretToolHint()}`;
+  // Only a recognised "no provider" report may fall back to the secrets file.
+  // Anything else (storage error, unknown output) fails closed with this error.
+  return NO_PROVIDER_STDERR.test(detail) ? keyringUnavailable(message) : new Error(message);
 }
 
 function linuxGetBlocking(account) {
@@ -604,12 +678,32 @@ function _noteKeychainFailure(error) {
   if (error?.code === 'KEYRING_UNREACHABLE') state = 'unreachable';
   else if (/not installed/.test(message)) state = 'missing';
   else if (/locked|timed out/.test(message)) state = 'locked';
-  _keychainStatus = { state, message };
+  // Only a confirmed missing provider counts. A failed passive probe
+  // (KEYRING_UNREACHABLE: gdbus missing, unparsable reply) proves nothing, so
+  // it keeps its warning and recovery action.
+  _keychainStatus = { state, message, unavailable: error?.code === KEYRING_UNAVAILABLE };
+}
+
+// Sync entry points feed the same health the async ones do (Linux only).
+function _noteSyncOutcome(error) {
+  if (platform() !== 'linux') return;
+  if (error) _noteKeychainFailure(error);
+  else _noteKeychainOk();
 }
 
-/** Linux keyring health for the UI: ok | locked | missing | error | unknown. */
+/** Linux keyring health for the UI: ok | locked | missing | unreachable | error |
+ *  unknown. `fallback` is true only when a keychain write/read confirmed that
+ *  this host has no provider, so secrets live in the private secrets file
+ *  instead: a working store, not a failure to report. A locked or unreachable
+ *  keyring is never a fallback. */
 function keychainStatus() {
-  return { ..._keychainStatus };
+  const { unavailable, ...status } = _keychainStatus;
+  const fallback = unavailable === true && platform() === 'linux';
+  // `unsafeStore` ({ path: the secrets directory, kind: type | owner |
+  // permissions }, never a value) says the private file store is being ignored
+  // because its layout is unsafe — see fallbackUnsafeStore.
+  const unsafe = fallback ? fallbackUnsafeStore() : null;
+  return { ...status, fallback, ...(unsafe ? { unsafeStore: { path: unsafe.dir, kind: unsafe.kind } } : {}) };
 }
 
 function _linuxLoaded() {
@@ -668,6 +762,10 @@ function parseSecretToolSearchAccounts(stdout, stderr) {
 async function _linuxAccountsToRead(interactive, remaining) {
   let found = await searchMixdogItems();
   if (found === null && !interactive) {
+    // An inconclusive passive probe is "unreachable" only while a provider may
+    // exist. If secret-tool itself is not installed (headless host without
+    // gdbus either) that is a confirmed missing provider, not a warning.
+    if (await secretToolMissing()) throw keyringUnavailable(SECRET_TOOL_MISSING_MESSAGE);
     const error = new Error(LINUX_UNREACHABLE_MESSAGE);
     error.code = 'KEYRING_UNREACHABLE';
     throw error;
@@ -996,6 +1094,196 @@ function win32Delete(account) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Linux fallback file — headless hosts without a usable keychain provider
+// ---------------------------------------------------------------------------
+// When secret-tool/libsecret is missing or no Secret Service is running (a
+// headless SSH server, WSL), a secret is kept in `<dataDir>/secrets/
+// <account>.secret`: one owner-only (0600) file per account in an owner-only
+// (0700) directory, written atomically. Never in mixdog-config.json. A read
+// re-verifies that layout (no symlink, regular file, this user's, no group/other
+// access) and treats a store that fails it as absent. A locked keyring is NOT
+// such a host — it fails with its unlock message instead.
+// Order: the keychain is always tried first and wins when it has the account;
+// the file is read only when the keychain has nothing (or cannot be read), so a
+// value saved here stays readable after a keychain becomes available, and a
+// later save into an available keychain supersedes (and removes) the file value.
+
+function usesFallback(error) {
+  return platform() === 'linux' && error?.code === KEYRING_UNAVAILABLE;
+}
+
+function fallbackFile(account) {
+  return path.join(secretsDir(), `${encodeURIComponent(account)}.secret`);
+}
+
+function unsafeFallback(message, kind) {
+  return Object.assign(new Error(message), { code: 'EUNSAFE', ...(kind ? { kind } : {}) });
+}
+
+// Owner and mode bits are POSIX: without getuid (Windows) there is nothing to compare.
+function ownedByUser(stat) {
+  return typeof process.getuid !== 'function' || stat.uid === process.getuid();
+}
+
+function groupOrOtherAccessible(stat) {
+  return typeof process.getuid === 'function' && (stat.mode & 0o077) !== 0;
+}
+
+// Why a stat (an lstat/fstat of the store directory, or of an account file)
+// disqualifies it, as the repair it needs: 'type' (a symlink or not a regular
+// file/directory: remove it), 'owner' (someone else's: chown it), 'permissions'
+// (group/other can reach it: chmod it); null when it is fine.
+function unsafeKind(stat, directory) {
+  if (directory ? !stat.isDirectory() : !stat.isFile()) return 'type';
+  if (!ownedByUser(stat)) return 'owner';
+  return groupOrOtherAccessible(stat) ? 'permissions' : null;
+}
+
+// The verified secrets directory, or null when absent and not `create`d. A
+// pre-existing symlink, a non-directory, or a directory owned by someone else is
+// refused: following it would chmod and write outside the data dir. lstat does
+// not follow links, so a symlink never passes isDirectory(). `create` repairs
+// the mode itself (chmod 0700); a reader passes `requirePrivate` and refuses a
+// directory that group/other can reach instead.
+function fallbackDir({ create = false, requirePrivate = false } = {}) {
+  const dir = secretsDir();
+  let before;
+  try {
+    before = fs.lstatSync(dir);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    if (!create) return null;
+    fs.mkdirSync(path.dirname(dir), { recursive: true, mode: 0o700 });
+    fs.mkdirSync(dir, { mode: 0o700 });
+    before = fs.lstatSync(dir);
+  }
+  const kind = unsafeKind(before, true);
+  if (kind && (kind !== 'permissions' || requirePrivate)) {
+    throw unsafeFallback('the secrets directory is not a private directory owned by this user', kind);
+  }
+  if (create) {
+    fs.chmodSync(dir, 0o700);
+    // The chmod must have hit the directory that was verified, not a swapped-in link.
+    const after = fs.lstatSync(dir);
+    if (!after.isDirectory() || after.ino !== before.ino || after.dev !== before.dev) {
+      throw unsafeFallback('the secrets directory changed while it was being secured');
+    }
+  }
+  return dir;
+}
+
+// A stored value is served only from a private regular file owned by this user.
+// The file is opened without following a symlink (O_NOFOLLOW; ELOOP means it is
+// one) and without blocking on a FIFO (O_NONBLOCK), then judged by fstat on the
+// descriptor that is actually read, so nothing can be swapped in between check
+// and read. Anything else reads as absent: the EUNSAFE reason is thrown like the
+// directory's, and callers that tolerate a failed read treat it as "no secret".
+function fallbackGet(account) {
+  if (platform() !== 'linux') return null;
+  if (fallbackDir({ requirePrivate: true }) === null) return null;
+  const { O_RDONLY, O_NOFOLLOW = 0, O_NONBLOCK = 0 } = fs.constants;
+  let descriptor;
+  try {
+    descriptor = fs.openSync(fallbackFile(account), O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    if (error?.code === 'ELOOP') {
+      throw unsafeFallback('the secret file is a symbolic link, not a private file', 'type');
+    }
+    throw error;
+  }
+  try {
+    const kind = unsafeKind(fs.fstatSync(descriptor), false);
+    if (kind) throw unsafeFallback('the secret file is not a private regular file owned by this user', kind);
+    return fs.readFileSync(descriptor, 'utf8') || null;
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+// Passive health check for the status path: `{ dir, kind }` when the store has a
+// layout fallbackGet refuses (so its keys read as absent), else null. The read
+// path swallows that refusal when the keychain also failed, so without this the
+// user would see a bare "No key". Every call scans the directory afresh, so an
+// external repair shows at once; callers that need it for many rows ask once
+// (provider setup passes the one answer down).
+function fallbackUnsafeStore() {
+  if (platform() !== 'linux') return null;
+  const dir = secretsDir();
+  let value = null;
+  try {
+    if (fallbackDir({ requirePrivate: true }) !== null) {
+      for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.secret')) continue;
+        const kind = unsafeKind(fs.lstatSync(path.join(dir, name)), false);
+        if (kind) {
+          value = { dir, kind };
+          break;
+        }
+      }
+    }
+  } catch (error) {
+    if (error?.code === 'EUNSAFE') value = { dir, kind: error.kind };
+  }
+  return value;
+}
+
+/** Whether a read of `account` would be served by the Linux fallback file: the
+ *  file exists and the keychain does not hold the account. */
+function hasFallbackSecret(account) {
+  // A read prefers the keychain: a value it holds (cached) wins over the file.
+  if (_cacheGet(account) != null) return false;
+  try {
+    return fallbackGet(account) != null;
+  } catch {
+    return false;
+  }
+}
+
+// For a keychain that threw: an unreadable fallback must not mask that error.
+function fallbackGetQuiet(account) {
+  try {
+    return fallbackGet(account);
+  } catch {
+    return null;
+  }
+}
+
+function fallbackSet(account, value, keychainError) {
+  try {
+    const dir = fallbackDir({ create: true });
+    writeOwnerOnlyAtomicSync(path.join(dir, path.basename(fallbackFile(account))), value);
+  } catch (error) {
+    // The message carries the filesystem error only, never the value.
+    const reason = error?.code || 'unknown error';
+    throw Object.assign(
+      new Error(`${keychainError.message}\n  The private secrets file could not be written either: ${reason}`),
+      { cause: error }
+    );
+  }
+}
+
+function fallbackRemove(account) {
+  if (platform() !== 'linux') return;
+  if (fallbackDir() === null) return;
+  try {
+    fs.unlinkSync(fallbackFile(account));
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+}
+
+// After a save into the keychain: the file value is now stale. Best effort —
+// the keychain write already succeeded.
+function fallbackSupersede(account) {
+  try {
+    fallbackRemove(account);
+  } catch (error) {
+    keychainDebug('could not remove superseded fallback secret', error?.message);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -1022,9 +1310,18 @@ function backend() {
 function getSecret(account) {
   const cached = _cacheGet(account);
   if (cached !== undefined) return cached;
-  const value = backend().get(account);
+  let value;
+  try {
+    value = backend().get(account);
+  } catch (error) {
+    // Unreadable keychain (no provider, locked, not read yet): a secret saved
+    // to the fallback file is still there; otherwise the keychain error stands.
+    const stored = fallbackGetQuiet(account);
+    if (stored == null) throw error;
+    return stored;
+  }
   _cacheSet(account, value);
-  return value;
+  return value ?? fallbackGet(account);
 }
 
 function hasSecret(account) {
@@ -1040,19 +1337,39 @@ function hasSecret(account) {
 
 function setSecret(account, value) {
   let stored = false;
+  let viaFile = false;
   try {
-    backend().set(account, value);
+    try {
+      backend().set(account, value);
+      _noteSyncOutcome(null);
+      fallbackSupersede(account);
+    } catch (error) {
+      _noteSyncOutcome(error);
+      if (!usesFallback(error)) throw error;
+      fallbackSet(account, value, error);
+      viaFile = true;
+    }
     stored = true;
   } finally {
     _cacheInvalidate(account);
-    // Linux reads are cache-only, so a fresh write must stay readable.
-    if (stored && platform() === 'linux') _cacheSet(account, value);
+    // Linux reads are cache-only, so a fresh keychain write must stay readable.
+    // A file-only value is not cached: reads reach it through the file, and the
+    // cache then means "the keychain holds this".
+    if (stored && !viaFile && platform() === 'linux') _cacheSet(account, value);
   }
 }
 
 function deleteSecret(account) {
   try {
-    backend().delete(account);
+    fallbackRemove(account);
+    try {
+      backend().delete(account);
+      _noteSyncOutcome(null);
+    } catch (error) {
+      _noteSyncOutcome(error);
+      // No keychain provider here: nothing can be stored in it to delete.
+      if (!usesFallback(error)) throw error;
+    }
   } finally {
     _cacheInvalidate(account);
   }
@@ -1065,34 +1382,42 @@ async function getSecretAsync(account) {
   if (cached !== undefined) return cached;
   const b = backend();
   if (!b.getAsync) return getSecret(account);
-  if (_linuxLoaded()) return null;
+  if (_linuxLoaded()) return fallbackGet(account);
   const generation = _cacheGenerations.get(account) || 0;
   let value;
   try {
     value = await b.getAsync(account);
   } catch (error) {
     _noteKeychainFailure(error);
-    throw error;
+    const stored = fallbackGetQuiet(account);
+    if (stored == null) throw error;
+    return stored;
   }
   _noteKeychainOk();
   if ((_cacheGenerations.get(account) || 0) === generation) _cacheSet(account, value);
-  return value;
+  return value ?? fallbackGet(account);
 }
 
 async function setSecretAsync(account, value) {
   const b = backend();
   if (!b.setAsync) return setSecret(account, value);
   let stored = false;
+  let viaFile = false;
   try {
-    await b.setAsync(account, value);
+    try {
+      await b.setAsync(account, value);
+      _noteKeychainOk();
+      fallbackSupersede(account);
+    } catch (error) {
+      _noteKeychainFailure(error);
+      if (!usesFallback(error)) throw error;
+      fallbackSet(account, value, error);
+      viaFile = true;
+    }
     stored = true;
-    _noteKeychainOk();
-  } catch (error) {
-    _noteKeychainFailure(error);
-    throw error;
   } finally {
     _cacheInvalidate(account);
-    if (stored) _cacheSet(account, value);
+    if (stored && !viaFile) _cacheSet(account, value);
   }
 }
 
@@ -1100,11 +1425,15 @@ async function deleteSecretAsync(account) {
   const b = backend();
   if (!b.deleteAsync) return deleteSecret(account);
   try {
-    await b.deleteAsync(account);
-    _noteKeychainOk();
-  } catch (error) {
-    _noteKeychainFailure(error);
-    throw error;
+    fallbackRemove(account);
+    try {
+      await b.deleteAsync(account);
+      _noteKeychainOk();
+    } catch (error) {
+      _noteKeychainFailure(error);
+      // No keychain provider here: nothing can be stored in it to delete.
+      if (!usesFallback(error)) throw error;
+    }
   } finally {
     _cacheInvalidate(account);
   }
@@ -1118,6 +1447,7 @@ module.exports = {
   setSecretAsync,
   deleteSecretAsync,
   hasSecret,
+  hasFallbackSecret,
   keychainStatus,
   invalidateSecretCache,
   prewarmSecrets,