controlzero 1.9.6__tar.gz → 1.9.7__tar.gz

{controlzero-1.9.6 → controlzero-1.9.7}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.9.7 -- 2026-06-16 (hosted audit delivery for short-lived processes, gh#1292)
+
+Fixes a P0 found via a customer report: hosted-mode audit rows were written to
+the local `~/.controlzero/audit.log` but never reached the dashboard for
+short-lived processes (PreToolUse hooks, CLI one-shots).
+
+### Fixed
+
+- **Remote audit never delivered for short-lived processes (gh#1292).** Since
+  1.9.2 the hosted (`BearerAuditSink`) and enrolled (`RemoteAuditSink`) sinks
+  default to the durable encrypted spool, where `log()` WALs the row and an
+  opportunistic `daemon=True` thread drains it. A short-lived process exits
+  before that thread can finish its HTTPS POST, and `close()` was a fsync-only
+  boundary, so the row stayed on local disk and never shipped. The hosted sink
+  now hands the drain to a **detached `controlzero spool flush` child** that
+  outlives the process (no latency on the agent hot path; the keystore and
+  network work happen in the child, never on the close path). The api key
+  travels via the child's environment, never on its argv. The enrolled sink
+  (opt-in, off the hosted hot path) does a bounded, fail-open in-process drain
+  on close instead. Both paths are fail-open: any error leaves the durable WAL
+  intact for a later drain. The durable WAL guarantee is unchanged.
+
 ## 1.9.6 -- 2026-06-16 (Antigravity GA-blocker hardening, gh#1248 / epic gh#925)
 
 Closes 3 of the prod-readiness GA blockers for the Antigravity (`agy`)

{controlzero-1.9.6 → controlzero-1.9.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.6
+Version: 1.9.7
 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.6 → controlzero-1.9.7}/controlzero/__init__.py

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

{controlzero-1.9.6 → controlzero-1.9.7}/controlzero/audit_remote.py

@@ -24,6 +24,7 @@ import json
 import logging
 import os
 import platform
+import sys
 import threading
 import uuid
 from datetime import datetime, timezone
@@ -110,6 +111,15 @@ _SPOOL_DEFAULT_DIR = "~/.controlzero/spool"
 # processes.
 _SPOOL_HOOK_BUDGET_S = 2.0
 _SPOOL_TIMER_BUDGET_S = 25.0
+# close() handoff budgets (#1292). A short-lived process (PreToolUse hook /
+# CLI one-shot) exits before the daemon drain ships its spooled rows, and
+# close() was a fsync-only boundary -- so the rows never reached the backend.
+# The hosted (Bearer) sink now hands the drain to a DETACHED uploader child
+# that outlives this process (no latency on the agent hot path, keystore +
+# network work happen off the close path). The enrolled sink -- opt-in, off
+# the hosted hot path -- does a bounded, fail-open in-process drain instead.
+_DETACHED_DRAIN_BUDGET_S = 30.0
+_CLOSE_DRAIN_BUDGET_S = 2.0
 
 
 def _build_wire_entry(
@@ -284,6 +294,11 @@ class _SpoolWiringMixin:
         self._drain_inflight = False
         self._drain_again = False
         self._drain_auth_blocked = False
+        # #1292: whether this process WAL-logged at least one entry (gates the
+        # close-time handoff so a pure-read process never spawns a drainer) and
+        # whether the detached drainer was already spawned (coalesce to one).
+        self._spool_logged = False
+        self._detached_drain_spawned = False
         self._spool = None
         self._spool_mode = "off"
         # Fast path: flag off/unset, NO hosted default, AND no spool
@@ -365,6 +380,10 @@ class _SpoolWiringMixin:
         except Exception as exc:  # noqa: BLE001
             logger.warning("controlzero: spool append failed (%s)", exc)
             return False
+        # This process has durably WAL-logged at least one entry; close() may
+        # need to hand its drain to a detached uploader so a short-lived
+        # process does not strand it (#1292).
+        self._spool_logged = True
         if self._spool_mode == _SPOOL_MODE_DURABLE:
             self._drain_async(budget_s=_SPOOL_HOOK_BUDGET_S)
         return True
@@ -377,6 +396,73 @@ class _SpoolWiringMixin:
     def _spool_drain_orphans(self) -> bool:
         return False
 
+    def _spawn_detached_drain(self) -> None:
+        """Hand the spool drain to a DETACHED child that outlives this
+        process, then return immediately (#1292).
+
+        A short-lived hosted process (PreToolUse hook / CLI one-shot) exits
+        before the in-process daemon drain can finish its HTTPS POST, so
+        durably-spooled rows never reach the backend -- close() was a
+        fsync-only boundary that stranded them. Spawning ``controlzero spool
+        flush`` in a new session lets the upload complete after this process
+        is gone: no latency on the agent hot path, and the keystore + network
+        work happen in the child, never on this close path (the founder
+        non-blocking-hook and no-keystore-on-close constraints).
+
+        Only the Bearer (hosted api-key) sink can be drained this way --
+        ``cz spool flush`` authenticates with the api key, which it reads from
+        the environment (never argv, so the key never lands in ``ps``). The
+        enrolled sink has no such entrypoint and uses an in-process close
+        drain instead.
+
+        Fail-open: any error leaves the durable WAL intact for a later drain
+        (next long-lived process, the timer, or an explicit ``cz spool
+        flush``)."""
+        if getattr(self, "_detached_drain_spawned", False):
+            return
+        if self._spool is None or not getattr(self, "_spool_logged", False):
+            return
+        api_key = getattr(self, "_api_key", None)
+        if not api_key:
+            return
+        try:
+            import subprocess
+
+            env = dict(os.environ)
+            env["CONTROLZERO_API_KEY"] = api_key
+            api_url = getattr(self, "_api_url", None)
+            if api_url:
+                env["CONTROLZERO_API_URL"] = api_url
+            popen_kwargs = dict(
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                env=env,
+                close_fds=True,
+            )
+            if os.name == "nt":  # detach on Windows
+                popen_kwargs["creationflags"] = (
+                    getattr(subprocess, "DETACHED_PROCESS", 0)
+                    | getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+                )
+            else:  # POSIX: escape the process group so it outlives the parent
+                popen_kwargs["start_new_session"] = True
+            subprocess.Popen(  # noqa: S603 -- fixed argv, no shell, no user input
+                [
+                    sys.executable, "-m", "controlzero.cli.main",
+                    "spool", "flush",
+                    "--timeout", str(_DETACHED_DRAIN_BUDGET_S),
+                ],
+                **popen_kwargs,
+            )
+            self._detached_drain_spawned = True
+        except Exception as exc:  # noqa: BLE001 -- never block/crash the host
+            logger.warning(
+                "controlzero: detached spool drain spawn failed (%s); audit "
+                "rows remain durable in the spool for a later drain",
+                exc,
+            )
+
     def _drain_async(self, budget_s: float = _SPOOL_HOOK_BUDGET_S) -> None:
         """One opportunistic non-blocking drain in a daemon thread.
         Coalesced: at most one drain in flight per sink instance; an
@@ -506,8 +592,17 @@ class RemoteAuditSink(_SpoolWiringMixin):
         self._closed = True
         self._cancel_flush_timer()
         if self._spool_wal:
-            # Spool mode: every entry is already durable on disk; close
-            # is a final fsync boundary, NEVER a blocking network flush.
+            # DURABLE mode (enrolled, opt-in, off the hosted hot path) ships
+            # synchronously with a bounded, fail-open budget before the final
+            # fsync so a short-lived process does not strand its rows (#1292).
+            # spool_only is replay-only and must NEVER live-send on close.
+            if (self._spool_mode == _SPOOL_MODE_DURABLE
+                    and getattr(self, "_spool_logged", False)):
+                try:
+                    self._drain_once(blocking=True,
+                                     budget_s=_CLOSE_DRAIN_BUDGET_S)
+                except Exception:  # noqa: BLE001 -- fail-open; WAL preserved
+                    pass
             self._spool_close()
             return
         # Synchronous flush -- we are shutting down
@@ -748,8 +843,13 @@ class BearerAuditSink(_SpoolWiringMixin):
         self._closed = True
         self._cancel_flush_timer()
         if self._spool_wal:
-            # Spool mode: entries are already durable; close is a final
-            # fsync boundary, NEVER a blocking network flush.
+            # DURABLE mode hands the drain to a DETACHED child that outlives
+            # this (possibly short-lived) process so its rows are delivered;
+            # close() makes NO in-process network call -- the child does the
+            # keystore + network work off this hot path (#1292). spool_only is
+            # replay-only and must NEVER live-send on close -- only fsync.
+            if self._spool_mode == _SPOOL_MODE_DURABLE:
+                self._spawn_detached_drain()
             self._spool_close()
             return
         self._flush_sync()

{controlzero-1.9.6 → controlzero-1.9.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.9.6"
+version = "1.9.7"
 description = "AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup."
 readme = "README.md"
 license = {text = "Apache-2.0"}

{controlzero-1.9.6 → controlzero-1.9.7}/tests/spool/test_spool_sink_wiring.py

@@ -17,6 +17,8 @@ from __future__ import annotations
 
 import collections
 import json
+import os
+import sys
 import threading
 import time
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -211,6 +213,44 @@ def test_enrolled_sink_still_off_by_default(server, spool_env, monkeypatch):
         sink.close()
 
 
+def test_enrolled_durable_close_drains_in_process(server, spool_env,
+                                                  monkeypatch):
+    # #1292: the enrolled sink (opt-in, off the hosted hook hot path) cannot
+    # use `cz spool flush` (no api key), so on close it does a bounded,
+    # fail-open IN-PROCESS drain (blocking=True) rather than stranding a
+    # short-lived process's rows. Reverting close() to a bare fsync makes this
+    # test fail (no blocking drain observed).
+    monkeypatch.setenv("CONTROLZERO_SPOOL", "durable")
+
+    class FakeState:
+        machine_id = "11111111-2222-4333-8444-555555555555"
+
+    import controlzero.enrollment as enrollment
+    monkeypatch.setattr(enrollment, "load_state", lambda: FakeState())
+    monkeypatch.setattr(
+        enrollment, "sign_request",
+        lambda *_a, **_k: {"X-CZ-Machine-ID": FakeState.machine_id,
+                           "X-CZ-Signature": "sig"})
+    sink = RemoteAuditSink(
+        api_url=server.url, machine_token="", org_id="org-1",
+        machine_id=FakeState.machine_id)
+    assert sink._spool is not None
+
+    blocking_calls = []
+    real_drain_once = sink._drain_once
+
+    def recording_drain_once(*a, **kw):
+        blocking_calls.append(bool(kw.get("blocking", False)))
+        return real_drain_once(*a, **kw)
+
+    monkeypatch.setattr(sink, "_drain_once", recording_drain_once)
+    sink.log(_entry(1))
+    sink.close()
+    # close() performed a blocking in-process drain (the daemon drain uses
+    # blocking=False, so a True here can only come from close()).
+    assert any(blocking_calls)
+
+
 def test_flag_off_401_still_clears_buffer_legacy(server, spool_env,
                                                  monkeypatch):
     """The legacy (non-spool) 401 contract is unchanged: sink disables
@@ -304,7 +344,12 @@ def test_durable_wal_survives_network_down(server, spool_env, monkeypatch):
         sink.close()
 
 
-def test_durable_close_is_not_a_network_flush(server, spool_env, monkeypatch):
+def test_durable_close_spawns_detached_drain(server, spool_env, monkeypatch):
+    # #1292: a short-lived hosted process must not strand its spooled rows.
+    # close() makes NO in-process network call (the agent hot path stays
+    # fast), but it MUST hand the drain to a DETACHED `controlzero spool
+    # flush` child that outlives this process so the rows are delivered.
+    # Reverting close() to a bare fsync makes this test fail (spawned == 0).
     monkeypatch.setenv("CONTROLZERO_SPOOL", "durable")
     sink = BearerAuditSink(api_url=server.url, api_key=API_KEY)
     import httpx
@@ -316,8 +361,18 @@ def test_durable_close_is_not_a_network_flush(server, spool_env, monkeypatch):
         raise httpx.ConnectError("down")
 
     monkeypatch.setattr(httpx, "post", counting_post)
+
+    spawned = []
+
+    class _FakePopen:
+        def __init__(self, argv, **kwargs):
+            spawned.append((argv, kwargs))
+
+    import subprocess
+    monkeypatch.setattr(subprocess, "Popen", _FakePopen)
+
     sink.log(_entry(1))
-    # let the opportunistic drain fail
+    # let the opportunistic daemon drain settle (it fails against the dead net)
     deadline = time.monotonic() + 5
     while time.monotonic() < deadline:
         with sink._drain_state_lock:
@@ -327,9 +382,78 @@ def test_durable_close_is_not_a_network_flush(server, spool_env, monkeypatch):
     n_before = len(posted)
     t0 = time.monotonic()
     sink.close()
-    # close() returned promptly and made NO network attempt of its own.
+    # close() returned promptly and made NO network attempt of its own ...
     assert time.monotonic() - t0 < 1.0
     assert len(posted) == n_before
+    # ... but it DID hand the drain to a detached `controlzero spool flush`.
+    assert len(spawned) == 1
+    argv, kwargs = spawned[0]
+    assert argv[0] == sys.executable
+    assert "spool" in argv and "flush" in argv
+    # the api key travels via env, NEVER on argv (no leak in `ps`).
+    assert API_KEY not in argv
+    assert kwargs["env"]["CONTROLZERO_API_KEY"] == API_KEY
+    # detached so it outlives this (possibly short-lived) process.
+    if os.name == "nt":
+        assert kwargs.get("creationflags", 0) != 0
+    else:
+        assert kwargs.get("start_new_session") is True
+
+
+def test_durable_close_spawn_failure_is_fail_open(server, spool_env,
+                                                  monkeypatch):
+    # If spawning the detached drainer fails, close() must NOT raise -- the
+    # rows stay durable in the WAL for a later drain.
+    monkeypatch.setenv("CONTROLZERO_SPOOL", "durable")
+    sink = BearerAuditSink(api_url=server.url, api_key=API_KEY)
+
+    import subprocess
+
+    def boom(*a, **kw):
+        raise OSError("cannot fork")
+
+    monkeypatch.setattr(subprocess, "Popen", boom)
+    sink.log(_entry(1))
+    sink.close()  # must not raise
+
+
+def test_durable_close_no_spawn_when_nothing_logged(server, spool_env,
+                                                    monkeypatch):
+    # A pure-read process that never WAL-logged must not spawn a drainer.
+    monkeypatch.setenv("CONTROLZERO_SPOOL", "durable")
+    sink = BearerAuditSink(api_url=server.url, api_key=API_KEY)
+
+    spawned = []
+
+    class _FakePopen:
+        def __init__(self, argv, **kwargs):
+            spawned.append(argv)
+
+    import subprocess
+    monkeypatch.setattr(subprocess, "Popen", _FakePopen)
+    sink.close()
+    assert spawned == []
+
+
+def test_spool_only_close_does_not_spawn_drain(server, spool_env, monkeypatch):
+    # spool_only is replay-only ("never live-send"): close() must NOT spawn a
+    # detached uploader even after logging -- only durable mode does (#1292).
+    # The close-drain is gated on _spool_mode == durable, NOT on _spool_wal
+    # (which is also true for spool_only); reverting that gate fails this test.
+    monkeypatch.setenv("CONTROLZERO_SPOOL", "spool_only")
+    sink = BearerAuditSink(api_url=server.url, api_key=API_KEY)
+
+    spawned = []
+
+    class _FakePopen:
+        def __init__(self, argv, **kwargs):
+            spawned.append(argv)
+
+    import subprocess
+    monkeypatch.setattr(subprocess, "Popen", _FakePopen)
+    sink.log(_entry(1))
+    sink.close()
+    assert spawned == []
 
 
 def test_durable_401_preserves_spool_and_keeps_logging(server, spool_env,

{controlzero-1.9.6 → controlzero-1.9.7}/tests/test_hosted_policy_e2e.py

@@ -184,11 +184,13 @@ def test_hosted_mode_audit_pushed(mock_backend):
     client = Client(api_key="cz_live_e2e_test")
     client.guard("web_search", args={})
     client.guard("send_email", args={})
-    # Hosted mode now defaults to the DURABLE encrypted spool (gh#1247):
-    # each decision is WAL'd to encrypted disk and delivered by the
-    # opportunistic async drain, so close() is a final fsync boundary,
-    # NOT a blocking network flush. Delivery is guaranteed (WAL) but
-    # asynchronous; poll for it instead of assuming a synchronous close.
+    # Hosted mode defaults to the DURABLE encrypted spool (gh#1247): each
+    # decision is WAL'd to encrypted disk and delivered by the opportunistic
+    # async drain. close() makes NO in-process network call; instead it hands
+    # the drain to a DETACHED `controlzero spool flush` child so a short-lived
+    # process does not strand its rows (gh#1292). Delivery is guaranteed (WAL)
+    # but asynchronous via the daemon drain and/or the detached child; poll for
+    # it instead of assuming a synchronous close.
     client.close()
 
     deadline = time.monotonic() + 8.0