controlzero 1.9.1__tar.gz → 1.9.3__tar.gz

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

@@ -1,5 +1,82 @@
 # Changelog
 
+## 1.9.3 -- 2026-06-16 (posture release: empty-bundle OBSERVE + self-explaining no-rule-match deny, epic gh#1247)
+
+The consolidated **posture release** for epic gh#1247 (customer Bryan).
+Three customer-visible behaviors land together so the engine's "what
+happens when a tool isn't covered by a rule" story is coherent across
+both SDKs and the backend:
+
+1. **Empty bundle -> OBSERVE** (was the only content of the superseded
+   1.9.2-observe draft).
+2. **Non-empty no-rule-match deny is now self-explaining** (folds in the
+   Python-only fix from gh#1257, which is superseded by this release).
+3. The backend `default_on_empty` knob on the bundle handler.
+
+### Fixed
+
+- **Hosted no-rule-match deny is now self-explaining (folds gh#1257).** A
+  non-empty bundle with `default_action=deny` and zero rule matches (the
+  exact shape of Bryan's "Db read only" allow-list, which excludes
+  `bash`) used to deny with the bare, bug-looking message
+  `No matching policy rule (fail-closed default)` -- no path out. The
+  deny reason now NAMES the unmatched action (e.g. `bash:find`) and the
+  exact remediation (add a catch-all `allow: '*'`, allow the specific
+  action, or flip the project/org default to allow) and tells the user
+  to do it in the Control Zero dashboard. `reason_code` stays
+  `NO_RULE_MATCH`; the legacy `fail-closed default` substring is retained
+  for any downstream regex consumer. The empty-bundle OBSERVE catch-all
+  matches FIRST, so a genuinely-empty bundle still observes and never
+  reaches this deny -- the two behaviors compose cleanly. Regression
+  tests in `tests/test_default_action.py`
+  (`test_1247_no_rule_match_deny_*`).
+
+### Changed
+
+A genuinely-EMPTY hosted bundle -- one that resolved successfully but has
+zero attached/active policies -- now defaults to **OBSERVE** (allow +
+audit + a loud "monitoring, not enforcing" signal) instead of the old
+day-one deny-brick. A fresh hosted project no longer blocks every tool
+call before the operator has authored a single rule; instead Control
+Zero allows the call through and audits it, loudly flagged, so the
+operator can see the engine is wired up and watching, then attach a
+policy to start enforcing.
+
+This is a founder-approved posture refinement (validated by a 4-lens
+second-opinion). It is deliberately **narrow and gated**:
+
+- **Only the genuinely-empty, successfully-resolved case observes.** A
+  non-empty bundle whose rules evaluate but nothing matches still
+  **denies** (`NO_RULE_MATCH`, `default_action` canonical deny) --
+  authored allow-lists stay secure. A bundle RESOLUTION ERROR / failed
+  pull / RLS / auth / decrypt failure still **fails closed** (deny,
+  `BUNDLE_MISSING`, honoring `default_on_missing`). Observe mode can
+  never mask a resolution error as an allow.
+- **The empty-vs-error boundary is structural, not a runtime flag.** The
+  empty path (`translate_to_local_policy`, reached only on successful
+  resolution) and the error path (`make_bundle_missing_policy`, reached
+  only on resolution failure) are separate functions with separate
+  reason codes, so they cannot be confused.
+
+### Added
+
+- **New `reason_code=OBSERVE_MODE_NO_POLICY`** and synthetic policy_id
+  `synthetic:OBSERVE_MODE_NO_POLICY` for the empty-bundle observe allow,
+  distinct from `NO_ACTIVE_POLICIES` (the deny/warn/allow empty postures)
+  and `BUNDLE_MISSING` (the fail-closed resolution-error path).
+- **`PolicyDecision.observe: bool`** -- True only on an observe-mode
+  allow. The CLI `guard` output now prints a loud yellow "OBSERVE MODE:
+  monitoring, not enforcing" line so an observe allow can never be
+  mistaken for a normal rule-driven allow. Gated strictly on the
+  reason_code, so no user-authored rule can ever set it.
+- **New `default_on_empty` knob** (`observe`|`deny`|`warn`|`allow`,
+  canonical `observe`), separate from `default_action`. An operator can
+  declare allow-list-vs-deny-list intent for the empty case instead of
+  it being inferred. Plumbed end-to-end: backend bundle payload ->
+  bundle translator -> `PolicySettings`. Local YAML policies may set
+  `settings.default_on_empty`. The dashboard observe-mode indicator +
+  CLI `status` line remain a separate frontend/CLI follow-up.
+
 ## 1.9.1 -- 2026-06-16 (hosted-mode local audit log P0, epic gh#1247)
 
 ### Fixed
@@ -29,6 +106,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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.1
+Version: 1.9.3
 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.3}/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.3"
 
 __all__ = [
     "Client",

{controlzero-1.9.1 → controlzero-1.9.3}/controlzero/_internal/bundle.py

@@ -493,9 +493,11 @@ def translate_to_local_policy(payload: dict) -> dict:
     # the canonical-default fallback (one source of truth).
     from controlzero._internal.enforcer import (
         DEFAULT_BUNDLE_ACTION,
+        DEFAULT_BUNDLE_ON_EMPTY,
         DEFAULT_BUNDLE_ON_MISSING,
         DEFAULT_BUNDLE_ON_TAMPER,
         VALID_DEFAULT_ACTIONS,
+        VALID_DEFAULT_ON_EMPTY,
         VALID_DEFAULT_ON_MISSING,
         VALID_DEFAULT_ON_TAMPER,
     )
@@ -508,6 +510,19 @@ def translate_to_local_policy(payload: dict) -> dict:
     if default_on_missing not in VALID_DEFAULT_ON_MISSING:
         default_on_missing = DEFAULT_BUNDLE_ON_MISSING
 
+    # default_on_empty (#1247 item 3): empty-bundle posture, resolved
+    # server-side org->project->canonical("observe"). Separate from
+    # default_action so an authored allow-list (no-match -> deny) and an
+    # empty project (observe) do not have to share one knob. Unknown /
+    # absent values coerce to the canonical "observe" so a fresh hosted
+    # project is observe-by-default instead of bricked day-one. NOTE:
+    # this knob is read ONLY here, on the SUCCESSFUL-resolution empty
+    # branch below -- the resolution-ERROR path (make_bundle_missing_
+    # policy) does not consult it and still fails closed.
+    default_on_empty = payload.get("default_on_empty")
+    if default_on_empty not in VALID_DEFAULT_ON_EMPTY:
+        default_on_empty = DEFAULT_BUNDLE_ON_EMPTY
+
     default_on_tamper = payload.get("default_on_tamper")
     if default_on_tamper not in VALID_DEFAULT_ON_TAMPER:
         default_on_tamper = DEFAULT_BUNDLE_ON_TAMPER
@@ -536,39 +551,69 @@ def translate_to_local_policy(payload: dict) -> dict:
                 flat.append(translated)
 
     if not flat:
-        # Empty policy set: synthetic catchall rule. The effect
-        # mirrors the bundle-level default_action so "empty bundle"
-        # continues to deliver the operator's chosen posture. Prior
-        # to #228 Phase 2 this was hard-coded to deny; now an org
-        # that ships an empty-bundle-with-default=allow gets the
-        # expected allow (with the same NO_ACTIVE_POLICIES
-        # reason_code so dashboards still bucket it as "nothing
-        # attached").
+        # Empty policy set (RESOLVED SUCCESSFULLY, zero translatable
+        # rules): synthetic catch-all rule whose posture is driven by
+        # default_on_empty (#1247 item 3 / #1252), NOT default_action.
+        #
+        # Why a separate knob: default_action governs the NON-EMPTY
+        # no-match path -- an org that authored an allow-list wants that
+        # to stay deny. But an org that has attached NOTHING YET should
+        # not be bricked day-one. The founder-approved refinement makes
+        # the genuinely-empty case OBSERVE by default: the call is
+        # ALLOWED THROUGH (effect="allow") but loudly flagged as
+        # monitoring-only (reason_code=OBSERVE_MODE_NO_POLICY, which the
+        # evaluator turns into observe=True on the decision) and
+        # audited, so the operator KNOWS the engine is wired up and
+        # watching, not enforcing. An operator can override
+        # default_on_empty to deny (fail-closed empty), warn (shadow),
+        # or allow (silent allow).
+        #
+        # SAFETY INVARIANT (the empty-vs-error boundary): this branch is
+        # reached ONLY when bundle resolution SUCCEEDED and produced
+        # zero rules. A resolution FAILURE (pull error, RLS/auth denial,
+        # decrypt failure) never reaches here -- it is caught upstream
+        # and routed to make_bundle_missing_policy(), which honors
+        # default_on_missing and STILL FAILS CLOSED (deny). So observe
+        # mode can never mask a resolution error as an allow.
         #
-        # Copy-choice note (2026-04-19, the 2026-04-19 P0): the previous
-        # message -- "No active policies. Define one in the Control Zero
-        # dashboard." -- presumed the user had not defined any policies.
-        # That presumption was wrong in the common case: the user had
-        # defined several, but the library-attachments state on the
-        # backend did not include any active attachment row, so the
-        # bundle arrived with zero policies while the dashboard Library
-        # tab still showed them. The new wording removes the
-        # presumption and points at the actual recovery action.
-        flat.append({
-            "effect": default_action,
-            "action": "*",
-            # T79: stamp a synthetic policy_id so the audit dashboard
-            # can render a recognizable chip + tooltip linking to the
-            # right troubleshooting anchor. The reason_code stays the
-            # same; the synthetic id is purely an audit-presentation
-            # contract (audit ingest stores it verbatim).
-            "id": "synthetic:NO_ACTIVE_POLICIES",
-            "reason": (
-                "No policies are active on this project. If the dashboard "
-                "shows attached policies, regenerate the policy bundle."
-            ),
-            "reason_code": "NO_ACTIVE_POLICIES",
-        })
+        # Copy-choice note (2026-04-19, the 2026-04-19 P0): the original
+        # NO_ACTIVE_POLICIES message presumed the user had defined no
+        # policies; in the common case the library-attachments state was
+        # simply empty while the dashboard still showed them. The wording
+        # below removes that presumption and points at recovery.
+        if default_on_empty == "observe":
+            # OBSERVE: allow + loud monitoring signal + audit.
+            flat.append({
+                "effect": "allow",
+                "action": "*",
+                "id": "synthetic:OBSERVE_MODE_NO_POLICY",
+                "reason": (
+                    "OBSERVE MODE: no policies are active on this project, so "
+                    "Control Zero is monitoring and auditing tool calls but "
+                    "NOT enforcing -- every call is allowed and logged. Attach "
+                    "a policy (or set the empty-project default to deny) in the "
+                    "Control Zero dashboard to start enforcing."
+                ),
+                "reason_code": "OBSERVE_MODE_NO_POLICY",
+            })
+        else:
+            # Explicit non-observe empty posture (deny / warn / allow).
+            # Keeps the historical NO_ACTIVE_POLICIES reason_code so
+            # dashboards still bucket it as "nothing attached". The
+            # effect honors the operator's declared default_on_empty.
+            flat.append({
+                "effect": default_on_empty,
+                "action": "*",
+                # T79: stamp a synthetic policy_id so the audit dashboard
+                # can render a recognizable chip + tooltip linking to the
+                # right troubleshooting anchor.
+                "id": "synthetic:NO_ACTIVE_POLICIES",
+                "reason": (
+                    "No policies are active on this project. If the dashboard "
+                    "shows attached policies, regenerate the policy bundle."
+                ),
+                "reason_code": "NO_ACTIVE_POLICIES",
+            })
 
     out = {
         "version": "1",
@@ -576,6 +621,7 @@ def translate_to_local_policy(payload: dict) -> dict:
         "settings": {
             "default_action": default_action,
             "default_on_missing": default_on_missing,
+            "default_on_empty": default_on_empty,
             "default_on_tamper": default_on_tamper,
         },
     }

{controlzero-1.9.1 → controlzero-1.9.3}/controlzero/_internal/enforcer.py

@@ -62,6 +62,20 @@ POLICY_ENGINE_VERSION = "0.1.0"
 REASON_CODE_RULE_MATCH = "RULE_MATCH"
 REASON_CODE_NO_RULE_MATCH = "NO_RULE_MATCH"
 REASON_CODE_NO_ACTIVE_POLICIES = "NO_ACTIVE_POLICIES"
+# OBSERVE_MODE_NO_POLICY (#1247 item 3 / #1252): a genuinely-empty,
+# rule-less bundle that RESOLVED SUCCESSFULLY (zero attached/active
+# policies) and whose resolved empty-policy posture is "observe". The
+# call is ALLOWED THROUGH but the decision is loudly flagged as
+# monitoring-only (observe=True on the decision) and audited, so the
+# operator knows the engine is NOT enforcing. This is deliberately a
+# DISTINCT code from NO_ACTIVE_POLICIES (which remains for the
+# deny/warn empty-posture cases and pre-refinement consumers) and from
+# BUNDLE_MISSING (a resolution FAILURE, which still fails closed -- see
+# make_bundle_missing_policy). The empty-vs-error boundary is the
+# security-critical invariant here: OBSERVE_MODE_NO_POLICY is ONLY ever
+# emitted on the SUCCESSFUL-resolution empty path, never on a pull /
+# RLS / auth error.
+REASON_CODE_OBSERVE_MODE_NO_POLICY = "OBSERVE_MODE_NO_POLICY"
 REASON_CODE_BUNDLE_MISSING = "BUNDLE_MISSING"
 REASON_CODE_BUNDLE_TAMPERED = "BUNDLE_TAMPERED"
 REASON_CODE_MACHINE_QUARANTINED = "MACHINE_QUARANTINED"
@@ -93,6 +107,7 @@ VALID_REASON_CODES = frozenset({
     REASON_CODE_RULE_MATCH,
     REASON_CODE_NO_RULE_MATCH,
     REASON_CODE_NO_ACTIVE_POLICIES,
+    REASON_CODE_OBSERVE_MODE_NO_POLICY,
     REASON_CODE_BUNDLE_MISSING,
     REASON_CODE_BUNDLE_TAMPERED,
     REASON_CODE_MACHINE_QUARANTINED,
@@ -129,6 +144,7 @@ VALID_REASON_CODES = frozenset({
 SYNTHETIC_POLICY_ID_PREFIX = "synthetic:"
 SYNTHETIC_NO_RULE_MATCH = "synthetic:NO_RULE_MATCH"
 SYNTHETIC_NO_ACTIVE_POLICIES = "synthetic:NO_ACTIVE_POLICIES"
+SYNTHETIC_OBSERVE_MODE_NO_POLICY = "synthetic:OBSERVE_MODE_NO_POLICY"
 SYNTHETIC_BUNDLE_MISSING = "synthetic:BUNDLE_MISSING"
 SYNTHETIC_RESOURCE_GATE_SKIP = "synthetic:RESOURCE_GATE_SKIP"
 SYNTHETIC_QUARANTINE = "synthetic:QUARANTINE"
@@ -137,6 +153,7 @@ SYNTHETIC_ENGINE_UNAVAILABLE = "synthetic:ENGINE_UNAVAILABLE"
 VALID_SYNTHETIC_POLICY_IDS = frozenset({
     SYNTHETIC_NO_RULE_MATCH,
     SYNTHETIC_NO_ACTIVE_POLICIES,
+    SYNTHETIC_OBSERVE_MODE_NO_POLICY,
     SYNTHETIC_BUNDLE_MISSING,
     SYNTHETIC_RESOURCE_GATE_SKIP,
     SYNTHETIC_QUARANTINE,
@@ -155,8 +172,30 @@ DEFAULT_BUNDLE_ACTION = "deny"
 DEFAULT_BUNDLE_ON_MISSING = "deny"
 DEFAULT_BUNDLE_ON_TAMPER = "warn"
 
+# default_on_empty (#1247 item 3 / #1252, founder-approved posture
+# refinement): the effect for a genuinely-EMPTY bundle -- one that
+# RESOLVED SUCCESSFULLY but has zero attached/active rules. This is a
+# SEPARATE knob from default_action (which governs the non-empty
+# no-match path). The distinction is the whole point: an org that has
+# authored an allow-list deliberately wants no-match -> deny
+# (default_action), while an org that has attached NOTHING YET should
+# not be bricked day-one -- it observes (allow + audit + a loud
+# "monitoring, not enforcing" signal) instead.
+#
+# Canonical default is "observe": a fresh/empty hosted project allows
+# tool calls through but loudly flags + audits every one as
+# OBSERVE_MODE_NO_POLICY, so the operator sees the engine is wired up
+# and watching, then authors real rules. An operator can override to
+# "deny" (fail-closed empty), "warn" (shadow), or "allow" (silent
+# allow, discouraged). CRITICAL: this only ever applies on the
+# SUCCESSFUL-resolution empty path; a resolution ERROR routes through
+# make_bundle_missing_policy + default_on_missing and STILL FAILS
+# CLOSED -- default_on_empty never weakens the error path.
+DEFAULT_BUNDLE_ON_EMPTY = "observe"
+
 VALID_DEFAULT_ACTIONS = frozenset({"deny", "allow", "warn"})
 VALID_DEFAULT_ON_MISSING = frozenset({"deny", "allow"})
+VALID_DEFAULT_ON_EMPTY = frozenset({"observe", "deny", "allow", "warn"})
 VALID_DEFAULT_ON_TAMPER = frozenset({"warn", "deny", "deny-all", "quarantine"})
 
 
@@ -217,6 +256,19 @@ class PolicyDecision:
     # requires_approval is True. None falls back to policy_id at
     # request time so the approver always sees a label.
     approval_action: Optional[str] = None
+    # observe (#1247 item 3 / #1252): True when this decision is an
+    # OBSERVE-MODE allow -- the call is permitted (effect="allow") but
+    # the engine is NOT enforcing because the bundle is genuinely empty
+    # (zero attached/active policies) and the resolved empty-policy
+    # posture is "observe". This is the LOUD signal the security review
+    # mandated: an observe allow must never look like a normal,
+    # rule-driven allow. Consumers (CLI output, audit annotation, hook
+    # banners) branch on this to print "OBSERVE MODE: monitoring, not
+    # enforcing". It is set ONLY alongside
+    # reason_code=OBSERVE_MODE_NO_POLICY and is False on every other
+    # path (including a real rule that happens to allow, and the
+    # fail-closed BUNDLE_MISSING / NO_RULE_MATCH paths).
+    observe: bool = False
 
     @property
     def decision(self) -> str:
@@ -457,6 +509,25 @@ class PolicyEvaluator:
                 reason_code=decision_code,
                 evaluated_rules=evaluated,
                 gate_matched=gate_matched_value,
+                # #1247 item 3: the empty-bundle observe catch-all
+                # (synthetic OBSERVE_MODE_NO_POLICY rule) is an allow
+                # that must be loudly flagged as monitoring-only. Set
+                # the observe signal here so CLI / hook / audit
+                # consumers can distinguish it from a normal
+                # rule-driven allow.
+                #
+                # Hardening (security review L1): gate on BOTH the
+                # reason_code AND the synthetic policy_id, so that even a
+                # (backend-signed) bundle rule that carried a forged
+                # reason_code="OBSERVE_MODE_NO_POLICY" cannot mislabel a
+                # rule-driven allow as observe -- the synthetic id is
+                # only ever stamped by translate_to_local_policy's empty
+                # branch. observe is an audit/UX label, never an
+                # authorization input, so this is belt-and-suspenders.
+                observe=(
+                    decision_code == REASON_CODE_OBSERVE_MODE_NO_POLICY
+                    and (rule.id or "") == SYNTHETIC_OBSERVE_MODE_NO_POLICY
+                ),
             )
             # DLP scan: only when the policy decision is "allow" and args exist
             if decision.allowed and args and self._dlp_scanner is not None:
@@ -475,11 +546,32 @@ class PolicyEvaluator:
         # that regex-match the reason string (a pattern we actively
         # discourage -- use reason_code instead) keep working.
         if self._default_action == "deny":
-            reason = "No matching policy rule (fail-closed default)"
+            # #1247 (folded from #1257): a deny-by-default no-rule-match is
+            # the single most confusing block a customer hits -- a benign
+            # tool (e.g. `bash:find`) is denied not because a rule forbids
+            # it but because no rule mentions it and the bundle's
+            # default_on_missing is deny. The historical message ("fail-
+            # closed default") gave no path out and looked like a bug.
+            # Name the unmatched action and the exact remediation so the
+            # deny is self-explaining. The leading phrase keeps the legacy
+            # "fail-closed default" substring for any downstream regex
+            # consumer (reason_code=NO_RULE_MATCH is the supported signal;
+            # this is belt-and-suspenders). NOTE: this is the NON-EMPTY
+            # bundle path -- a genuinely empty bundle short-circuits to the
+            # synthetic OBSERVE catch-all above and never reaches here, so
+            # observe and self-explaining-deny compose cleanly.
+            reason = (
+                f"No matching policy rule for '{action}' (fail-closed default; "
+                "default_on_missing=deny). This tool is neither allowed nor "
+                "denied by any rule in your hosted policy, so it is blocked. "
+                "Add a rule that allows it (e.g. allow: '*' as a catch-all, or "
+                f"allow: '{action}'), or set the project/org default to allow, "
+                "in the Control Zero dashboard."
+            )
         elif self._default_action == "allow":
-            reason = "No matching policy rule (default_action=allow)"
+            reason = f"No matching policy rule for '{action}' (default_action=allow)"
         else:  # "warn"
-            reason = "No matching policy rule (default_action=warn)"
+            reason = f"No matching policy rule for '{action}' (default_action=warn)"
 
         # T79: distinguish the T83-class signature ("a rule's actions
         # matched but its resources gate excluded the call") from the

{controlzero-1.9.1 → controlzero-1.9.3}/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.3}/controlzero/cli/main.py

@@ -214,6 +214,18 @@ def test(tool: str, method: str, policy: str, args: str, hitl: Optional[str], hi
     click.echo(f"args:    {args_dict}")
     click.echo("")
     click.secho(f"DECISION: {decision.effect.upper()}", fg=color, bold=True)
+    # #1247 item 3: an observe-mode allow is NOT a normal allow -- the
+    # engine is monitoring, not enforcing, because the project has no
+    # active policies. Print a distinct, loud line so the operator can
+    # never mistake an empty-bundle observe for "my rules allowed this".
+    if getattr(decision, "observe", False):
+        click.secho(
+            "OBSERVE MODE: monitoring, not enforcing -- this project has "
+            "no active policies, so every tool call is allowed and logged. "
+            "Attach a policy to start enforcing.",
+            fg="yellow",
+            bold=True,
+        )
     if decision.policy_id:
         click.echo(f"matched: {decision.policy_id}")
     if decision.reason:

{controlzero-1.9.1 → controlzero-1.9.3}/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.1 → controlzero-1.9.3}/controlzero/policy_loader.py

@@ -33,9 +33,11 @@ from typing import Union
 from controlzero._internal.action_validator import validate_actions
 from controlzero._internal.enforcer import (
     DEFAULT_BUNDLE_ACTION,
+    DEFAULT_BUNDLE_ON_EMPTY,
     DEFAULT_BUNDLE_ON_MISSING,
     DEFAULT_BUNDLE_ON_TAMPER,
     VALID_DEFAULT_ACTIONS,
+    VALID_DEFAULT_ON_EMPTY,
     VALID_DEFAULT_ON_MISSING,
     VALID_DEFAULT_ON_TAMPER,
 )
@@ -134,6 +136,9 @@ class PolicySettings:
     tamper_behavior: str = "warn"
     default_action: str = DEFAULT_BUNDLE_ACTION
     default_on_missing: str = DEFAULT_BUNDLE_ON_MISSING
+    # default_on_empty (#1247 item 3): empty-bundle posture. Canonical
+    # "observe" so a rule-less project monitors+audits without bricking.
+    default_on_empty: str = DEFAULT_BUNDLE_ON_EMPTY
     default_on_tamper: str = DEFAULT_BUNDLE_ON_TAMPER
 
 
@@ -294,6 +299,16 @@ def _validate_and_translate(data: dict, source_label: str) -> ParsedPolicy:
                 else:
                     settings.default_on_missing = dom
 
+            doe = settings_raw.get("default_on_empty")
+            if doe is not None:
+                if doe not in VALID_DEFAULT_ON_EMPTY:
+                    errors.append(
+                        "settings.default_on_empty must be one of "
+                        f"{sorted(VALID_DEFAULT_ON_EMPTY)}, got {doe!r}"
+                    )
+                else:
+                    settings.default_on_empty = doe
+
             dot = settings_raw.get("default_on_tamper")
             if dot is not None:
                 if dot not in VALID_DEFAULT_ON_TAMPER: