controlzero 1.9.1__tar.gz → 1.9.2__tar.gz

{controlzero-1.9.1 → controlzero-1.9.2}/CHANGELOG.md

@@ -29,6 +29,50 @@
   preserved so the local log still records THAT a rule fired, and the remote
   sink keeps full fidelity.
 
+## 1.9.2 -- 2026-06-16 (durable-by-default + keychain-DEK audit spool, epic gh#1247)
+
+### Changed
+
+- **Hosted-mode audit is now durable by default.** When a `Client` is
+  constructed with an API key (hosted mode) and `CONTROLZERO_SPOOL` is
+  unset, the audit sink now defaults to the **durable encrypted spool**:
+  every decision is serialized, encrypted, and fsynced to an append-only
+  on-disk WAL **before** any network send, then drained opportunistically
+  in a background thread. Audit is no longer lost on a backend outage. An
+  explicit `CONTROLZERO_SPOOL` value (including `off`) still wins, and the
+  enrolled-machine sink keeps its prior off-by-default. Sink init is
+  fail-soft: any open/IO error degrades to the prior in-memory path,
+  emits `spool_init_degraded_total`, and never crashes or blocks the
+  PreToolUse hook.
+
+### Security
+
+- **Spool encryption key (DEK) defaults to the OS keystore.** The DEK now
+  lives in the macOS Keychain (a `security` generic-password item) or the
+  Linux Secret Service (`secret-tool`/libsecret) by default when one is
+  available; the on-disk `spool.key` then holds only a sentinel, so a
+  file-read of the spool directory can neither **decrypt** nor **forge**
+  spooled audit records (the AES-GCM tag and hash chain are keyed on the
+  DEK). Keystore access is strictly **non-interactive** and
+  hard-timeout-bounded -- a prompt risk, locked keystore, or missing CLI
+  degrades to the legacy 0600 `spool.key` (key hardening never costs audit
+  durability and never blocks the hook). A pre-existing on-disk DEK is
+  migrated into the keystore on first keystore-enabled open. Force the
+  legacy file DEK with `CONTROLZERO_SPOOL_KEYCHAIN=0` or
+  `CONTROLZERO_SPOOL_KEYCHAIN_DISABLE=1`; require the keystore with
+  `CONTROLZERO_SPOOL_KEYCHAIN=1`.
+
+### Tests
+
+- New `tests/spool/test_spool_keychain_dek.py` (keystore round-trip,
+  sentinel-on-disk, prompt-risk fallback, file opt-out, file->keystore
+  migration) and `tests/spool/test_spool_durable_default_tamper.py`
+  (hosted durable default, encrypted-WAL-before-send, **tampered-frame
+  rejection surfaced via `spool_tamper_records_total{gcm_auth}`**,
+  graceful init-failure degrade, WAL append latency budget). Spool
+  isolation is enforced suite-wide so tests never touch the real home dir
+  or OS keychain.
+
 ## 1.9.0 -- 2026-06-15 (Antigravity install CLI, epic gh#925)
 
 ### Added

{controlzero-1.9.1 → controlzero-1.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.1
+Version: 1.9.2
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai

{controlzero-1.9.1 → controlzero-1.9.2}/controlzero/__init__.py

@@ -40,7 +40,7 @@ from controlzero.hitl.grant_protocol import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.9.1"
+__version__ = "1.9.2"
 
 __all__ = [
     "Client",

{controlzero-1.9.1 → controlzero-1.9.2}/controlzero/audit_remote.py

@@ -261,26 +261,74 @@ class _SpoolWiringMixin:
     _spool = None
     _spool_mode = "off"
 
-    def _init_spool(self, stream_key: str) -> None:
+    def _init_spool(self, stream_key: str, default_mode: str = "off") -> None:
+        """Open the offline audit spool for this sink.
+
+        ``default_mode`` is the mode used when ``CONTROLZERO_SPOOL`` is
+        UNSET. The hosted (API-key) sink passes ``"durable"`` so audit is
+        never lost on a backend outage even when the operator has not set
+        the env knob -- the founder requirement that hosted-mode audit
+        WALs to encrypted disk before send by default. The enrolled sink
+        keeps ``"off"`` (no behavior change). An explicit ``CONTROLZERO_SPOOL``
+        value ALWAYS wins (operators can force ``off``/``spool_only``).
+
+        Non-blocking guarantee (founder constraint): this runs inside the
+        PreToolUse hook hot path. Every failure mode -- spool import
+        error, keystore prompt risk, IO error, ENOSPC -- DEGRADES to the
+        prior in-memory behavior and emits ``spool_init_degraded_total``;
+        it never crashes or blocks the agent. Spool open itself is
+        bounded (one recovery scan + the 200 ms seq.lock budget); it does
+        no network IO.
+        """
         self._drain_state_lock = threading.Lock()
         self._drain_inflight = False
         self._drain_again = False
         self._drain_auth_blocked = False
         self._spool = None
         self._spool_mode = "off"
-        # Fast path: flag off AND no spool directory on disk -- skip the
-        # spool import entirely so the default path stays byte-identical.
-        mode_raw = (os.environ.get("CONTROLZERO_SPOOL") or "").strip().lower()
+        # Fast path: flag off/unset, NO hosted default, AND no spool
+        # directory on disk -- skip the spool import entirely so the
+        # legacy default path stays byte-identical. When default_mode is
+        # durable (hosted), we must NOT take this shortcut: the whole
+        # point is to open a durable spool with no env set.
+        env_present = os.environ.get("CONTROLZERO_SPOOL")
+        mode_raw = (env_present or "").strip().lower()
         spool_dir = os.path.expanduser(
             os.environ.get("CONTROLZERO_SPOOL_DIR") or _SPOOL_DEFAULT_DIR)
-        if mode_raw in ("", "off") and not os.path.isdir(spool_dir):
+        # "Unset" means the env var is absent or an empty/whitespace
+        # string. An EXPLICIT "off" is a deliberate operator choice and
+        # MUST win over the sink default -- it is NOT treated as unset.
+        env_unset = (env_present is None) or (mode_raw == "")
+        env_off = mode_raw == "off"
+        # Effective mode is "off" when: env explicitly off, OR env unset
+        # AND this sink's default is off. In that case, with no spool on
+        # disk, skip the spool import entirely (byte-identical legacy).
+        effective_off = env_off or (env_unset and default_mode in ("", "off"))
+        if effective_off and not os.path.isdir(spool_dir):
             return
         try:
-            from controlzero.spool import Spool, get_mode
-
-            self._spool_mode = get_mode()
-            self._spool = Spool.maybe_open(stream_key)
+            from controlzero.spool import Spool, SpoolConfig, get_mode
+
+            # Resolve the effective mode: an explicit env value (incl.
+            # "off") wins; only a truly UNSET/blank env falls back to
+            # this sink's default_mode.
+            resolved = get_mode()  # "off" when unset/blank or unknown
+            if env_unset and default_mode not in ("", "off"):
+                resolved = default_mode
+            cfg = SpoolConfig.from_env()
+            cfg.mode = resolved
+            self._spool_mode = resolved
+            self._spool = Spool.maybe_open(stream_key, config=cfg)
+            # If the spool opened but immediately degraded to memory-only
+            # (e.g. ENOSPC during the open-time recovery/cleanup), surface
+            # it as a metric. The sink still functions -- WAL just buffers
+            # in memory until disk frees up -- so this is a warning, not a
+            # crash (C15).
+            if (self._spool is not None
+                    and getattr(self._spool, "in_memory_mode", False)):
+                self._spool_init_degraded("memory_mode")
         except Exception as exc:  # noqa: BLE001
+            self._spool_init_degraded("exception")
             logger.warning(
                 "controlzero: audit spool unavailable (%s); "
                 "falling back to in-memory buffering",
@@ -289,6 +337,15 @@ class _SpoolWiringMixin:
             self._spool = None
             self._spool_mode = "off"
 
+    @staticmethod
+    def _spool_init_degraded(reason: str) -> None:
+        """Emit the spool-init degrade metric. Never raises."""
+        try:
+            from controlzero.spool import metrics as _m
+            _m.incr("spool_init_degraded_total", reason)
+        except Exception:  # noqa: BLE001
+            pass
+
     @property
     def _spool_wal(self) -> bool:
         """True when log() must take the spool-first WAL path."""
@@ -660,8 +717,11 @@ class BearerAuditSink(_SpoolWiringMixin):
         self._closed = False
 
         # Offline audit spool (Phase 2): the stream is keyed by the api
-        # key fingerprint, exactly the spec's stream identity.
-        self._init_spool(api_key)
+        # key fingerprint, exactly the spec's stream identity. HOSTED
+        # mode defaults to durable WAL-to-encrypted-disk so audit is
+        # never lost on a backend outage even with no env set (founder
+        # requirement). An explicit CONTROLZERO_SPOOL value still wins.
+        self._init_spool(api_key, default_mode=_SPOOL_MODE_DURABLE)
 
         self._start_flush_timer()
         # Drain-only rule (plan section 10): an existing non-empty spool

{controlzero-1.9.1 → controlzero-1.9.2}/controlzero/cli/spool_cmd.py

@@ -203,9 +203,22 @@ def spool_verify(as_json):
         click.echo("error: spool.key missing; cannot verify", err=True)
         sys.exit(2)
     from controlzero.spool import assess_segment, derive_key
-    from controlzero.spool._state import load_or_create_dek, secure_read
+    from controlzero.spool._state import (
+        SpoolKeyUnavailable,
+        load_or_create_dek,
+        secure_read,
+    )
 
-    dek = load_or_create_dek(root)
+    try:
+        dek = load_or_create_dek(root)
+    except SpoolKeyUnavailable:
+        click.echo(
+            "error: spool DEK lives in the OS keystore but the keystore is "
+            "not readable right now (locked, or run on a different machine). "
+            "Unlock the keystore (or run on the originating host) and retry.",
+            err=True,
+        )
+        sys.exit(2)
 
     def key_provider(header):
         return derive_key(dek, header.device_id, header.stream_fp,

controlzero-1.9.2/controlzero/spool/_keyring.py

@@ -0,0 +1,311 @@
+"""Non-interactive OS-keychain provider for the spool DEK (spec 7.1, 5).
+
+The 32-byte device encryption key (DEK) protects the encrypted spool at
+rest. By default the DEK lives in ``spool.key`` (base64, 0600) co-located
+with the ciphertext it protects -- so a single file-read of the spool
+directory recovers the key AND the records. This module moves the DEK
+into the OS keystore so a local file-read of the spool dir can neither
+decrypt nor (because the AEAD tag and hash chain are keyed on the DEK)
+forge spool records.
+
+HARD CONSTRAINT (spec section 5, the ``CONTROLZERO_SPOOL_KEYCHAIN`` row):
+the spool runs inside coding-agent hooks (Claude Code / Gemini / Codex
+PreToolUse). A blocking keychain GUI prompt inside a hook is a P0. Every
+keystore call here therefore:
+
+  - runs NON-INTERACTIVELY (the platform CLI flag that reads/writes a
+    stored item without ever raising a GUI unlock dialog), and
+  - is wrapped in a hard wall-clock timeout, and
+  - on ANY failure (tool missing, locked keystore, prompt risk, timeout,
+    non-zero exit) returns None so the caller falls back to the 0600
+    file path with a documented warning.
+
+The provider never raises into the caller; ``get``/``set`` return None on
+any problem. ``available()`` is a cheap, side-effect-free probe used to
+decide the default DEK source.
+
+Service/account identity (stable, per-OS-user, no secrets in the name):
+
+  macOS Keychain (generic password item):
+      service = "com.controlzero.spool.dek"
+      account = "<spool_root_realpath>"
+  Linux Secret Service (libsecret via secret-tool):
+      attributes: service=com.controlzero.spool.dek, path=<spool_root>
+
+Keying the item on the spool root path lets two distinct spool roots
+(e.g. a test root and the real ~/.controlzero/spool) hold independent
+DEKs without colliding.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import os
+import shutil
+import subprocess  # noqa: S404 -- fixed argv, no shell, hard timeout
+import sys
+
+logger = logging.getLogger("controlzero.spool.keyring")
+
+# Stable keystore identity. NOT a secret; safe to hardcode.
+_SERVICE = "com.controlzero.spool.dek"
+
+# Hard wall-clock ceiling for any SINGLE keystore subprocess. The hook
+# hot path budget is 2 s total (_SPOOL_HOOK_BUDGET_S); a keystore call
+# that takes longer is treated as unavailable so we fall back to the file
+# path rather than risk the hook. Kept well below the hook budget so that
+# even the worst case (a get that times out followed by no set -- see
+# get_dek/set_dek discipline) stays a fraction of the budget.
+_KEYCHAIN_TIMEOUT_S = 0.5
+
+# Opt-out kept narrow and explicit: a value of "0" or "file" forces the
+# legacy on-disk DEK even on a platform with a working keystore. Any
+# other value (or unset) keeps the keychain-default behavior. This is
+# the inverse-sense companion to CONTROLZERO_SPOOL_KEYCHAIN=1 which
+# remains supported as an explicit opt-IN (handled by the caller).
+ENV_KEYCHAIN_DISABLE = "CONTROLZERO_SPOOL_KEYCHAIN_DISABLE"
+
+
+def _account_for(root: str) -> str:
+    """Per-spool-root account id. Realpath so a symlinked vs canonical
+    root resolve to the same keystore item."""
+    try:
+        return os.path.realpath(os.path.expanduser(root))
+    except Exception:  # noqa: BLE001
+        return os.path.expanduser(root)
+
+
+# Sentinel returned by _run on a hard timeout (vs a clean non-zero exit).
+# A timeout means the keystore is likely prompting / wedged, so the caller
+# should STOP attempting further keystore calls this open (don't burn a
+# second timeout on a set after a get already timed out).
+_TIMEOUT = object()
+
+
+def _run(argv, input_bytes=None):
+    """Run a keystore CLI non-interactively with a hard timeout.
+
+    Returns (rc, stdout_bytes), ``_TIMEOUT`` (the call exceeded the hard
+    budget -- likely a prompt/wedge), or None on any other failure
+    (missing binary, OSError). NEVER raises. NEVER inherits a tty, and
+    runs in its OWN session/process group so a CLI that tries to open a
+    controlling-terminal/agent prompt cannot attach to ours; on timeout
+    the whole process group is killed so nothing lingers blocking."""
+    try:
+        proc = subprocess.Popen(  # noqa: S603 -- fixed argv list, shell=False
+            argv,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,  # detach from our session/tty + pgid
+        )
+    except (OSError, ValueError):
+        return None
+    try:
+        out, _err = proc.communicate(input=input_bytes,
+                                     timeout=_KEYCHAIN_TIMEOUT_S)
+    except subprocess.TimeoutExpired:
+        # Kill the whole process group so a prompting CLI cannot linger.
+        try:
+            os.killpg(proc.pid, 9)
+        except (OSError, AttributeError):
+            try:
+                proc.kill()
+            except OSError:
+                pass
+        try:
+            proc.communicate(timeout=0.2)
+        except Exception:  # noqa: BLE001
+            pass
+        logger.debug("keystore call timed out (killed pgroup): %s", argv[0])
+        return _TIMEOUT
+    except (OSError, ValueError):
+        return None
+    return proc.returncode, out or b""
+
+
+# Per-process latch: once a keystore call has timed out (prompt/wedge),
+# treat the keystore as unavailable for the rest of this process so we
+# never burn a second hard timeout on the hook hot path.
+_keystore_timed_out = False
+
+
+def _decode_get(res):
+    """Map a _run() result for a GET into a 32-byte DEK or None.
+
+    A timeout latches the keystore off for this process and returns None
+    (caller falls back to file). A non-zero exit (item absent) is None."""
+    global _keystore_timed_out
+    if res is _TIMEOUT:
+        _keystore_timed_out = True
+        return None
+    if res is None:
+        return None
+    rc, out = res
+    if rc != 0:
+        return None
+    text = out.decode("utf-8", "replace").strip()
+    if not text:
+        return None
+    try:
+        raw = base64.b64decode(text)
+    except Exception:  # noqa: BLE001
+        return None
+    return raw if len(raw) == 32 else None
+
+
+def _ok_set(res):
+    """Map a _run() result for a SET into True/False. Timeout latches the
+    keystore off and returns False (caller falls back to file)."""
+    global _keystore_timed_out
+    if res is _TIMEOUT:
+        _keystore_timed_out = True
+        return False
+    if res is None:
+        return False
+    rc, _out = res
+    return rc == 0
+
+
+# -- macOS Keychain (security(1) generic-password items) --------------------
+
+
+def _macos_security_bin():
+    return shutil.which("security")
+
+
+def _macos_get(account: str):
+    sec = _macos_security_bin()
+    if not sec:
+        return None
+    # -w prints ONLY the password to stdout. For a generic-password item
+    # that this same process created (ACL grants the caller access), the
+    # read is non-interactive: the keychain does not raise an unlock
+    # dialog for a previously-stored generic password owned by the same
+    # login keychain. If the keychain is locked and WOULD prompt, the
+    # call blocks -- the hard timeout in _run() bounds that to 1 s and we
+    # fall back to file. -g is intentionally NOT passed (it can route to
+    # an interactive dialog on some macOS versions).
+    res = _run([sec, "find-generic-password", "-s", _SERVICE,
+                "-a", account, "-w"])
+    return _decode_get(res)
+
+
+def _macos_set(account: str, dek: bytes) -> bool:
+    sec = _macos_security_bin()
+    if not sec:
+        return False
+    b64 = base64.b64encode(dek).decode("ascii")
+    # -U updates an existing item in place. We deliberately do NOT pass
+    # `-T ""`: an empty trusted-application list forces an access-control
+    # evaluation that can BLOCK the `security` process (verified on macOS:
+    # `-T ""` hangs add-generic-password). The default ACL trusts the
+    # creating process, which is exactly the non-interactive behavior we
+    # need -- the same login user's later `security find-generic-password
+    # -w` reads it back without a GUI prompt. The hard timeout in _run()
+    # still bounds any pathological case.
+    res = _run([sec, "add-generic-password", "-s", _SERVICE,
+                "-a", account, "-w", b64, "-U"])
+    return _ok_set(res)
+
+
+# -- Linux Secret Service (libsecret via secret-tool(1)) --------------------
+
+
+def _secret_tool_bin():
+    return shutil.which("secret-tool")
+
+
+def _linux_get(account: str):
+    st = _secret_tool_bin()
+    if not st:
+        return None
+    # secret-tool lookup is non-interactive when the collection is
+    # already unlocked (the common case: a logged-in desktop session).
+    # If the keyring is locked it MAY prompt; the timeout bounds it and
+    # we fall back to file. attributes pin the item.
+    res = _run([st, "lookup", "service", _SERVICE, "path", account])
+    return _decode_get(res)
+
+
+def _linux_set(account: str, dek: bytes) -> bool:
+    st = _secret_tool_bin()
+    if not st:
+        return False
+    b64 = base64.b64encode(dek).decode("ascii") + "\n"
+    # secret-tool store reads the secret from stdin.
+    res = _run([st, "store", "--label=ControlZero spool DEK",
+                "service", _SERVICE, "path", account],
+               input_bytes=b64.encode("ascii"))
+    return _ok_set(res)
+
+
+# -- public surface ---------------------------------------------------------
+
+
+def backend_name():
+    """The keystore backend that would be used on this platform, or None.
+
+    Side-effect-free: only checks the platform and that the CLI exists on
+    PATH. Does NOT touch the keystore (no prompt risk)."""
+    if os.environ.get(ENV_KEYCHAIN_DISABLE, "").strip().lower() in ("1", "file", "true", "yes"):
+        return None
+    if sys.platform == "darwin":
+        return "macos" if _macos_security_bin() else None
+    if sys.platform.startswith("linux"):
+        return "secret-service" if _secret_tool_bin() else None
+    # Windows DPAPI path is not implemented in v1; the file fallback is
+    # used (documented in the spec / spool docs).
+    return None
+
+
+def available():
+    """True iff a keystore backend CLI is present on this platform AND
+    not disabled by env. Side-effect-free (no keystore access)."""
+    return backend_name() is not None
+
+
+def get_dek(root: str):
+    """Return the 32-byte DEK from the OS keystore, or None.
+
+    None means: no keystore, item absent, locked, prompt-risk hit the
+    timeout, or a malformed stored value. The caller falls back to the
+    on-disk DEK. Never raises."""
+    if _keystore_timed_out:
+        return None
+    backend = backend_name()
+    if backend is None:
+        return None
+    account = _account_for(root)
+    try:
+        if backend == "macos":
+            return _macos_get(account)
+        if backend == "secret-service":
+            return _linux_get(account)
+    except Exception as exc:  # noqa: BLE001 -- defensive: never raise on hot path
+        logger.debug("keystore get failed: %s", exc)
+    return None
+
+
+def set_dek(root: str, dek: bytes):
+    """Store the 32-byte DEK in the OS keystore. Returns True on success.
+
+    On any failure returns False; the caller then persists the DEK to the
+    0600 file instead. Never raises."""
+    if len(dek) != 32:
+        return False
+    if _keystore_timed_out:
+        return False
+    backend = backend_name()
+    if backend is None:
+        return False
+    account = _account_for(root)
+    try:
+        if backend == "macos":
+            return _macos_set(account, dek)
+        if backend == "secret-service":
+            return _linux_set(account, dek)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("keystore set failed: %s", exc)
+    return False

{controlzero-1.9.1 → controlzero-1.9.2}/controlzero/spool/_spool.py

@@ -21,6 +21,7 @@ import socket
 import time
 import uuid
 
+from . import _keyring
 from . import _metrics as metrics
 from ._compress import compress, default_write_flg
 from ._constants import (
@@ -63,6 +64,7 @@ from ._frame import (
     walk_records,
 )
 from ._state import (
+    SpoolKeyUnavailable,
     atomic_write,
     ensure_dir,
     fsync_dir,
@@ -89,6 +91,24 @@ def get_mode():
     return MODE_OFF
 
 
+def _resolve_keychain_env():
+    """Resolve the DEK-source tri-state from the environment.
+
+    Returns:
+      True  if CONTROLZERO_SPOOL_KEYCHAIN is explicitly truthy (opt-in);
+      False if CONTROLZERO_SPOOL_KEYCHAIN is explicitly falsey OR
+            CONTROLZERO_SPOOL_KEYCHAIN_DISABLE is set (opt-out);
+      None  otherwise -> the default keystore-first-when-available path.
+    """
+    raw = os.environ.get(ENV_KEYCHAIN)
+    if raw is not None and raw.strip() != "":
+        return raw.strip().lower() in ("1", "true", "yes", "on")
+    if os.environ.get(_keyring.ENV_KEYCHAIN_DISABLE, "").strip().lower() in (
+            "1", "file", "true", "yes", "on"):
+        return False
+    return None
+
+
 def _env_int(name, default):
     raw = os.environ.get(name)
     if raw is None or raw == "":
@@ -115,13 +135,17 @@ class SpoolConfig:
                  segment_age_s=DEFAULT_SEGMENT_AGE_S,
                  retention_s=DEFAULT_RETENTION_S,
                  max_bytes=DEFAULT_MAX_BYTES,
-                 keychain=False):
+                 keychain=None):
         self.mode = mode
         self.root = root or os.path.expanduser(DEFAULT_DIR)
         self.segment_bytes = segment_bytes
         self.segment_age_s = segment_age_s
         self.retention_s = retention_s
         self.max_bytes = max_bytes
+        # Tri-state DEK source (spec 7.1, section 5):
+        #   None  -> keystore-first when available, else 0600 file (DEFAULT);
+        #   True  -> explicit keystore opt-in (CONTROLZERO_SPOOL_KEYCHAIN=1);
+        #   False -> 0600 file only (explicit opt-out / disable env).
         self.keychain = keychain
 
     @classmethod
@@ -133,7 +157,7 @@ class SpoolConfig:
             segment_age_s=_env_int(ENV_SEGMENT_AGE, DEFAULT_SEGMENT_AGE_S),
             retention_s=_env_int(ENV_RETENTION, DEFAULT_RETENTION_S),
             max_bytes=_env_int(ENV_MAX_BYTES, DEFAULT_MAX_BYTES),
-            keychain=os.environ.get(ENV_KEYCHAIN, "0") == "1",
+            keychain=_resolve_keychain_env(),
         )
 
 
@@ -188,6 +212,17 @@ class Spool:
             self._init_dirs(create)
             self.recover()
             self.cleanup()
+        except SpoolKeyUnavailable as exc:
+            # The DEK lives in a keystore we cannot read this open and
+            # spool.key holds only the sentinel. Minting a new key would
+            # orphan the existing keystore-encrypted records, so degrade
+            # to memory-only for this process and try again next open
+            # (the keystore may be reachable then). Never destructive.
+            metrics.incr("spool_key_unavailable_total", "keychain")
+            logger.warning(
+                "spool DEK unavailable (keystore unreadable, sentinel on "
+                "disk); degrading to memory-only this process: %s", exc)
+            self._memory_mode = True
         except OSError as exc:
             self._degrade(exc, during="init")
 
@@ -221,7 +256,7 @@ class Spool:
         now_iso = _iso_from_ms(self._now_ms())
         self._device_id, self._device_epoch = load_or_create_device(
             self._root, now_iso)
-        self._dek = load_or_create_dek(self._root)
+        self._dek = load_or_create_dek(self._root, keychain=self._cfg.keychain)
         if create:
             ensure_dir(self._stream_dir)