controlzero 1.11.9__tar.gz → 1.12.0__tar.gz

{controlzero-1.11.9 → controlzero-1.12.0}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.12.0 -- 2026-06-25 (per-agent key authority + per-agent bundle cache + whoami)
+
+### Added
+
+- **`controlzero whoami`.** Prints which API key the SDK will actually use for a
+  surface (per-agent / env / global), its prefix only (never the full key), and
+  the project + org it resolves to. Diagnoses the most common "my audit logs are
+  missing" cause: a `CONTROLZERO_API_KEY` exported in the shell that maps to a
+  different project than the integration you installed, so events land in the
+  wrong tenant and the dashboard shows nothing.
+- **Per-agent bundle cache.** Each governed surface now caches its policy bundle
+  under `~/.controlzero/integrations/<agent>/cache/` (next to the per-agent
+  `config.yaml`), so two surfaces on one machine each bound to their own project
+  no longer share a bundle. A read fallback keeps existing installs working on
+  upgrade: an empty per-agent cache transparently reads the legacy shared cache
+  until the first fetch re-caches it (no fail-closed on upgrade).
+
+### Changed
+
+- **Per-agent key is now AUTHORITATIVE in the enforcement hook.** Hook-check
+  precedence becomes per-agent (for the active surface) > env > global. A key
+  installed via `install <agent> --api-key` / `kiro init --api-key` now wins over
+  a stale ambient `CONTROLZERO_API_KEY`, with a loud one-line warning when they
+  differ. This closes the silent wrong-tenant bug where a hook spooled + uploaded
+  + ingested correctly but attributed the events to whatever key was exported in
+  the shell, so the dashboard for the installed project showed "no audit entries".
+  Non-hook resolution (`status`, install-time display) is unchanged
+  (env > per-agent > global).
+- **Cache bundle extension is now `.czpolicy`** (was `.bin`), matching the UI
+  policy export (both are the same signed bundle format). Legacy `.bin` caches
+  are still read and garbage-collected, so nothing breaks on upgrade.
+
 ## 1.11.9 -- 2026-06-25 (policy-posture remediation: honest hosted/local CLI, per-agent keys, key-validity diagnostics)
 
 ### Added

{controlzero-1.11.9 → controlzero-1.12.0}/PKG-INFO

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

@@ -41,7 +41,7 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.11.9"
+__version__ = "1.12.0"
 
 __all__ = [
     "Client",

{controlzero-1.11.9 → controlzero-1.12.0}/controlzero/cli/agent_config.py

@@ -169,3 +169,53 @@ def resolve_api_key(
         return global_key, "global"
 
     return None, "none"
+
+
+def per_agent_api_key(
+    state_dir: Path, canonical_source: Optional[str]
+) -> Optional[str]:
+    """The api_key installed for THIS agent surface only -- no global fallback.
+
+    Unlike :func:`resolve_api_key` (env > per-agent > global), this returns
+    ONLY the per-agent ``integrations/<canonical_source>/config.yaml`` key, or
+    None. hook-check uses it to make a surface's installed key AUTHORITATIVE
+    over a stale ambient ``CONTROLZERO_API_KEY`` (#1011 follow-up): a surface
+    wired by ``install <agent> --api-key`` / ``kiro init --api-key`` must
+    attribute its audit to the project it was installed for, never to whatever
+    key happens to be exported in the shell. Never raises.
+    """
+    if not canonical_source:
+        return None
+    return _read_api_key_from_yaml(
+        per_agent_config_path(state_dir, canonical_source)
+    )
+
+
+def resolve_hook_api_key(
+    state_dir: Path,
+    canonical_source: Optional[str],
+    *,
+    env: Optional[dict] = None,
+) -> tuple[Optional[str], str, bool]:
+    """Resolve the hook-check api_key with PER-AGENT-AUTHORITATIVE precedence.
+
+    Unlike :func:`resolve_api_key` (env > per-agent > global), the enforcement
+    hook makes a surface's installed key win over a stale ambient env var
+    (#1011 follow-up): per-agent > env > global. This is what fixes the silent
+    wrong-tenant bug. Returns ``(api_key_or_None, source_label, overrode_env)``
+    where ``source_label`` is ``"per_agent"`` / ``"env"`` / ``"global"`` /
+    ``"none"`` and ``overrode_env`` is True when a per-agent key replaced a
+    DIFFERENT ambient ``CONTROLZERO_API_KEY`` (the case the hook warns about).
+    Never raises.
+    """
+    env = env if env is not None else os.environ
+    ambient = env.get("CONTROLZERO_API_KEY")
+    per_agent = per_agent_api_key(state_dir, canonical_source)
+    if per_agent:
+        return per_agent, "per_agent", bool(ambient and ambient != per_agent)
+    if ambient:
+        return ambient, "env", False
+    global_key = _read_api_key_from_yaml(state_dir / "config.yaml")
+    if global_key:
+        return global_key, "global", False
+    return None, "none", False

{controlzero-1.11.9 → controlzero-1.12.0}/controlzero/cli/debug_bundle.py

@@ -10,7 +10,8 @@ What it does
 
 1. Reads ``~/.controlzero/cache/bootstrap-<prefix>.json`` to get the
    project encryption key + signing public key.
-2. Reads ``~/.controlzero/cache/bundle-<prefix>.bin`` for the raw blob.
+2. Reads ``bundle-<prefix>.czpolicy`` (legacy ``.bin``) for the raw blob,
+   from the shared cache or a per-client ``integrations/<slug>/cache/`` dir.
 3. Calls :func:`controlzero._internal.bundle.parse_bundle` to verify
    the signature, decrypt the AES-GCM payload, and decode the JSON.
 4. Prints a human-readable summary (bundle id / created_at / expires_at,
@@ -133,30 +134,79 @@ def _api_key_prefix(api_key: str) -> str:
     return api_key[:_KEY_SCOPE_LEN].replace("/", "_").replace(".", "_")
 
 
+def _all_cache_dirs() -> list[Path]:
+    """Per-client integration cache dirs FIRST, then the shared cache dir.
+
+    #1011 follow-up: a surface's bundle now lives under
+    ~/.controlzero/integrations/<slug>/cache/. Integration dirs are listed
+    before the legacy shared ~/.controlzero/cache/ so the debug tool prefers
+    the bundle the hook actually enforces over a stale shared-cache entry.
+    """
+    dirs: list[Path] = []
+    integ = Path.home() / ".controlzero" / "integrations"
+    if integ.exists():
+        for sub in sorted(integ.iterdir()):
+            c = sub / "cache"
+            if c.is_dir():
+                dirs.append(c)
+    dirs.append(CACHE_DIR)
+    return dirs
+
+
 def _resolve_cache_for_prefix(prefix: str) -> CacheLocation:
+    # The bundle for a prefix may live in the shared cache or under a per-client
+    # integration cache. Prefer a dir that actually holds the BUNDLE (the policy
+    # the hook enforces), integration caches before the shared cache, and the
+    # current .czpolicy over a legacy .bin. A migrated install can have a stale
+    # bootstrap/old bundle in the shared cache plus the live bundle under
+    # integrations/<slug>/cache; preferring the bundle avoids inspecting the
+    # stale shared copy.
+    dirs = _all_cache_dirs()
+    for d in dirs:
+        czp = d / f"bundle-{prefix}.czpolicy"
+        legacy = d / f"bundle-{prefix}.bin"
+        if czp.exists() or legacy.exists():
+            bundle_path = czp if czp.exists() else legacy
+            return CacheLocation(
+                prefix=prefix,
+                bootstrap_path=d / f"bootstrap-{prefix}.json",
+                bundle_path=bundle_path,
+            )
+    # No bundle anywhere -- fall back to a dir that at least has the bootstrap
+    # (so the not-found message points at a real bootstrap), else the shared
+    # cache with the current extension.
+    for d in dirs:
+        boot = d / f"bootstrap-{prefix}.json"
+        if boot.exists():
+            return CacheLocation(
+                prefix=prefix,
+                bootstrap_path=boot,
+                bundle_path=d / f"bundle-{prefix}.czpolicy",
+            )
     return CacheLocation(
         prefix=prefix,
         bootstrap_path=CACHE_DIR / f"bootstrap-{prefix}.json",
-        bundle_path=CACHE_DIR / f"bundle-{prefix}.bin",
+        bundle_path=CACHE_DIR / f"bundle-{prefix}.czpolicy",
     )
 
 
 def _autodetect_cache() -> Optional[CacheLocation]:
-    """Pick a single bootstrap+bundle pair under ``CACHE_DIR``.
+    """Pick a single bootstrap+bundle pair across all cache dirs.
 
     Used when the operator did not specify ``--api-key-prefix`` and we
     cannot find an API key in env / config. Returns the unique pair
-    when there is exactly one; returns None when there are zero or
-    several (caller surfaces a helpful error in either case).
+    when there is exactly one (across the shared + per-client caches);
+    returns None when there are zero or several (caller surfaces a
+    helpful error in either case).
     """
-    if not CACHE_DIR.exists():
+    prefixes: list[str] = []
+    for d in _all_cache_dirs():
+        for b in sorted(d.glob("bootstrap-*.json")):
+            prefixes.append(b.name[len("bootstrap-") : -len(".json")])
+    prefixes = sorted(set(prefixes))
+    if len(prefixes) != 1:
         return None
-    bootstraps = sorted(CACHE_DIR.glob("bootstrap-*.json"))
-    if len(bootstraps) != 1:
-        return None
-    name = bootstraps[0].name  # bootstrap-<prefix>.json
-    prefix = name[len("bootstrap-") : -len(".json")]
-    return _resolve_cache_for_prefix(prefix)
+    return _resolve_cache_for_prefix(prefixes[0])
 
 
 # --- Bundle load ----------------------------------------------------------
@@ -478,7 +528,10 @@ def debug_bundle_cmd(api_key_prefix: Optional[str], simulate: Optional[str]):
             "  Set CONTROLZERO_API_KEY=cz_live_... or pass --api-key-prefix.",
             err=True,
         )
-        click.echo(f"  Looked under: {CACHE_DIR}", err=True)
+        click.echo(
+            f"  Looked under: {', '.join(str(d) for d in _all_cache_dirs())}",
+            err=True,
+        )
         sys.exit(1)
 
     # 2. Load bootstrap (keys + safe metadata).

{controlzero-1.11.9 → controlzero-1.12.0}/controlzero/cli/main.py

@@ -541,6 +541,94 @@ def heartbeat_cmd():
         click.echo("  tamper          : none (hooks intact)")
 
 
+@cli.command("whoami")
+@click.option(
+    "--client",
+    default=None,
+    help="Integration surface to inspect (e.g. kiro_cli, kiro_ide). "
+    "Defaults to CONTROLZERO_CLIENT.",
+)
+def whoami_cmd(client: Optional[str]) -> None:
+    """Show which API key the SDK will use and the project/org it maps to.
+
+    Diagnoses the most common "my audit logs are missing" cause: a
+    CONTROLZERO_API_KEY exported in the shell that maps to a DIFFERENT project
+    than the integration you installed, so events land in the wrong tenant and
+    the dashboard shows nothing. The key is never printed in full -- only its
+    prefix, its source, and the project/org it resolves to.
+    """
+    from controlzero._internal.source_labels import canonicalize_source
+
+    client = client or os.environ.get("CONTROLZERO_CLIENT")
+    canon = canonicalize_source(client) if client else None
+    canon = canon if canon and canon != "unknown" else None
+
+    # Use the SAME precedence the hook uses (per-agent authoritative > env >
+    # global) so whoami reports exactly what enforcement will do.
+    env_key = os.environ.get("CONTROLZERO_API_KEY")
+    effective, label, _overrode = agent_config.resolve_hook_api_key(
+        GLOBAL_POLICY_DIR, canon
+    )
+    if not effective:
+        click.echo(
+            "No Control Zero API key configured (no integration config, no "
+            "CONTROLZERO_API_KEY, no ~/.controlzero/config.yaml). Local-file "
+            "policy mode."
+        )
+        click.echo(
+            "Run `controlzero install <agent> --api-key cz_...` or "
+            "`controlzero kiro init --api-key cz_...` to enable hosted "
+            "policy + audit sync."
+        )
+        return
+    source = {
+        "per_agent": f"integration config (integrations/{canon}/config.yaml)",
+        "env": "CONTROLZERO_API_KEY environment variable",
+        "global": "~/.controlzero/config.yaml",
+    }.get(label, label)
+
+    click.echo(f"Client surface:    {canon or '(none)'}")
+    click.echo(f"Effective API key: {effective[:12]}... (source: {source})")
+    if env_key and effective != env_key:
+        click.echo(
+            "WARNING: a DIFFERENT CONTROLZERO_API_KEY is set in your shell. The "
+            "key above takes precedence for this surface; the shell key would "
+            "attribute audit to its own project. Unset it to avoid confusion."
+        )
+
+    # Resolve project/org via the per-surface cache, then a live call.
+    _prev = os.environ.get("CONTROLZERO_CLIENT")
+    if canon:
+        os.environ["CONTROLZERO_CLIENT"] = canon
+    try:
+        from controlzero.hosted_policy import (
+            get_or_fetch_bootstrap,
+            load_cached_bootstrap,
+        )
+        keys = load_cached_bootstrap(effective)
+        origin = "cache"
+        if keys is None:
+            keys = get_or_fetch_bootstrap(effective)
+            origin = "backend"
+        click.echo(f"Project:           {keys.project_id}")
+        click.echo(f"Org:               {keys.org_id or '(unknown)'} (from {origin})")
+        click.echo(
+            "Audit events from this surface are attributed to that project."
+        )
+    except Exception as exc:  # noqa: BLE001
+        click.echo(f"Could not resolve the project/org for this key: {exc}")
+        click.echo(
+            "Check the key validity and network reachability to "
+            "https://api.controlzero.ai."
+        )
+    finally:
+        if canon:
+            if _prev is None:
+                os.environ.pop("CONTROLZERO_CLIENT", None)
+            else:
+                os.environ["CONTROLZERO_CLIENT"] = _prev
+
+
 @cli.command("policy-pull")
 def policy_pull_cmd():
     """Pull the latest policy bundle from the backend.
@@ -930,10 +1018,27 @@ def status_cmd(check_key: bool):
     hosted = bool(resolved_key)
     unenrolled_first_run = not (api_key_env or api_key_config or enrolled)
 
+    # If the env/global default is local but individual agents are bound to
+    # their own hosted keys, the machine is in a MIXED posture. Report that
+    # instead of a flat LOCAL, which would understate that some agents are
+    # actually enforcing a hosted bundle (the bindings table below names them).
+    any_per_agent_key = any(
+        agent_config._read_api_key_from_yaml(
+            agent_config.per_agent_config_path(GLOBAL_POLICY_DIR, slug)
+        )
+        for slug in _KNOWN_AGENT_SLUGS
+    )
+    if hosted:
+        mode = "HOSTED"
+    elif any_per_agent_key:
+        mode = "MIXED (local default; some agents hosted -- see bindings)"
+    else:
+        mode = "LOCAL"
+
     cli_output.emit(Severity.INFO, "Control Zero status")
     facts = {
         "state dir": str(GLOBAL_POLICY_DIR),
-        "mode": "HOSTED" if hosted else "LOCAL",
+        "mode": mode,
         "config source": resolved_source,
         "key (masked, env/global default)": _status_mask_key(resolved_key),
         "enrolled": enrolled,
@@ -1567,18 +1672,35 @@ def hook_check(policy: Optional[str], strict_flag: Optional[bool]):
     # key in config.yaml but not in env fell through to the local-file
     # path on every hook-check.
     #
-    # PR4-F precedence (highest first): explicit env var > per-agent
-    # integrations/<canonical_source>/config.yaml > global config.yaml. The
-    # slug helper is SHARED with the install-write path (agent_config), so a
-    # key written by `install <agent> --api-key` is found here under the same
-    # adapter. A malformed per-agent file degrades to global (never crashes).
-    if not os.environ.get("CONTROLZERO_API_KEY"):
-        _resolved_key, _ = agent_config.resolve_api_key(
-            GLOBAL_POLICY_DIR,
-            getattr(_adapter, "canonical_source", None),
+    # Precedence (#1011 follow-up, per-client isolation): the key installed
+    # FOR THIS agent surface (integrations/<canonical_source>/config.yaml) is
+    # AUTHORITATIVE -- it wins over a stale ambient CONTROLZERO_API_KEY so the
+    # surface's audit lands in the project it was installed for, not whatever
+    # key happens to be exported in the shell. That stale-env-hijack was the
+    # silent wrong-tenant bug: a Kiro hook spooled + uploaded + ingested fine,
+    # but the events were attributed to the env key's org, so the dashboard for
+    # the installed project showed "no audit entries". Only when there is NO
+    # per-agent key do we keep the env > global precedence (the PR4-F default).
+    # The slug helper is SHARED with the install-write path (agent_config), so
+    # a key written by `install <agent> --api-key` is found here under the same
+    # adapter. A malformed per-agent file degrades to env/global (never crashes).
+    _canon_source = getattr(_adapter, "canonical_source", None)
+    _eff_key, _eff_src, _overrode_env = agent_config.resolve_hook_api_key(
+        GLOBAL_POLICY_DIR, _canon_source
+    )
+    if _overrode_env:
+        # Make the override LOUD (mirrors the hosted/local shadow warning): a
+        # stale shell key silently stealing a surface's audit is exactly what
+        # we are closing. Never print the key itself.
+        click.echo(
+            "[Control Zero] Using the API key installed for this integration; "
+            "ignoring a different CONTROLZERO_API_KEY found in the environment "
+            "(audit is attributed to the installed key's project). Run "
+            "`controlzero whoami` to confirm.",
+            err=True,
         )
-        if _resolved_key:
-            os.environ["CONTROLZERO_API_KEY"] = _resolved_key
+    if _eff_key:
+        os.environ["CONTROLZERO_API_KEY"] = _eff_key
 
     # T103 review (B1, B2): the CLI hook-check is a non-interactive
     # subprocess that Claude Code / Gemini CLI / Codex CLI spawn fresh
@@ -2836,17 +2958,14 @@ def _warn_no_deny_rules(agent_name: str, template_path: Path) -> None:
 
     Also shows what deny rules the template WOULD have added.
     """
-    click.secho(
-        f"WARNING: Your existing policy at {GLOBAL_POLICY_PATH} has NO deny rules.",
-        fg="yellow",
-        bold=True,
-        err=True,
+    cli_output.emit(
+        Severity.WARNING,
+        f"Your existing policy at {GLOBAL_POLICY_PATH} has NO deny rules.",
     )
-    click.secho(
+    cli_output.emit(
+        Severity.WARNING,
         f"The {agent_name} hook will ALLOW ALL tool calls. "
         "This may not be what you want.",
-        fg="yellow",
-        err=True,
     )
     click.echo("", err=True)
     click.echo(

{controlzero-1.11.9 → controlzero-1.12.0}/controlzero/hosted_policy.py

@@ -138,13 +138,71 @@ def get_api_url() -> str:
     return os.environ.get("CONTROLZERO_API_URL", DEFAULT_API_URL).rstrip("/")
 
 
-def _cache_dir() -> Path:
-    """Resolve the cache directory, creating it if missing."""
-    p = Path.home() / ".controlzero" / "cache"
+def _integration_slug(client: Optional[str] = None) -> Optional[str]:
+    """Canonical integration slug for per-client cache isolation, or None.
+
+    Per-client isolation (#1011 follow-up): when a hook-check runs for a
+    specific client surface, ``cli.main`` pins ``CONTROLZERO_CLIENT`` to the
+    adapter's canonical source BEFORE the policy load, so each surface's cache
+    lives under ``~/.controlzero/integrations/<slug>/cache/`` instead of one
+    shared directory. Two surfaces on one machine (each installed with its own
+    project's key) then never share a bundle cache. Returns ``None`` for a
+    library caller with no client -- the legacy shared ``~/.controlzero/cache/``
+    layout.
+    """
+    raw = client if client is not None else os.environ.get("CONTROLZERO_CLIENT")
+    if not raw:
+        return None
+    # Lazy import: source_labels is pure data, but importing it lazily keeps
+    # the hosted_policy import graph flat (same pattern as __version__ below).
+    from controlzero._internal.source_labels import canonicalize_source
+    slug = canonicalize_source(raw)
+    return slug if slug != "unknown" else None
+
+
+def _cache_dir(client: Optional[str] = None) -> Path:
+    """Resolve the cache directory, creating it if missing.
+
+    When a client integration is active (see :func:`_integration_slug`) the
+    cache is namespaced under ``~/.controlzero/integrations/<slug>/cache/`` so
+    each governed surface keeps its own bundle; otherwise the shared
+    ``~/.controlzero/cache/`` layout is used.
+    """
+    slug = _integration_slug(client)
+    if slug:
+        p = Path.home() / ".controlzero" / "integrations" / slug / "cache"
+    else:
+        p = Path.home() / ".controlzero" / "cache"
     p.mkdir(parents=True, exist_ok=True)
     return p
 
 
+def _cache_read_dirs(client: Optional[str] = None) -> list[Path]:
+    """Cache dirs to READ from, in priority order.
+
+    Writes always go to the active (per-client when set) dir via
+    :func:`_cache_dir`. Reads additionally fall back to the legacy shared
+    ~/.controlzero/cache/ so an EXISTING install keeps serving its
+    last-known-good bundle on first run after upgrading to per-client caches
+    (#1011 follow-up) -- it would otherwise see an empty per-client cache and,
+    if the backend were briefly unreachable, fail closed. The bundle is still
+    signature-verified on parse, so the fallback never weakens enforcement.
+
+    The legacy dir is derived from the active dir's <root>/integrations/<slug>/
+    cache shape, NOT from Path.home() independently, so a test that points
+    _cache_dir at an arbitrary throwaway dir does not leak onto the real home.
+    """
+    # Call _cache_dir() with no positional arg on the common (env-driven) path
+    # so a test that monkeypatches _cache_dir with a zero-arg stub still works.
+    primary = _cache_dir() if client is None else _cache_dir(client)
+    parts = primary.parts
+    if len(parts) >= 4 and parts[-1] == "cache" and parts[-3] == "integrations":
+        legacy = primary.parent.parent.parent / "cache"
+        if legacy != primary:
+            return [primary, legacy]
+    return [primary]
+
+
 def _key_scope(api_key: str) -> str:
     """Return a filename-safe scope identifier for the given API key."""
     if not api_key:
@@ -171,9 +229,29 @@ def _bootstrap_cache_path(api_key: str) -> Path:
 
 
 def load_cached_bootstrap(api_key: str) -> Optional[BootstrapKeys]:
-    path = _bootstrap_cache_path(api_key)
-    if not path.exists():
-        return None
+    # Read from the active (per-client) dir first, then the legacy shared dir
+    # as a migration fallback (#1011 follow-up). When served from the fallback,
+    # copy into the active dir so the per-agent cache stops depending on the
+    # shared one (see load_cached_bundle for the rationale).
+    scope = _key_scope(api_key)
+    read_dirs = _cache_read_dirs()
+    primary = read_dirs[0]
+    for d in read_dirs:
+        path = d / f"bootstrap-{scope}.json"
+        if not path.exists():
+            continue
+        keys = _read_bootstrap_file(path)
+        if keys is not None:
+            if d != primary:
+                try:
+                    save_cached_bootstrap(api_key, keys)
+                except OSError:
+                    pass
+            return keys
+    return None
+
+
+def _read_bootstrap_file(path: Path) -> Optional[BootstrapKeys]:
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
         return BootstrapKeys(
@@ -252,11 +330,14 @@ def _extract_scope_from_cache_filename(name: str) -> Optional[str]:
 
     Matches:
         bootstrap-<scope>.json
-        bundle-<scope>.bin
+        bundle-<scope>.czpolicy   (current)
+        bundle-<scope>.bin        (legacy -- still recognised so a key
+                                   rotation GCs pre-.czpolicy caches)
         bundle-<scope>.meta
     """
     for prefix, suffix in (
         ("bootstrap-", ".json"),
+        ("bundle-", ".czpolicy"),
         ("bundle-", ".bin"),
         ("bundle-", ".meta"),
     ):
@@ -363,20 +444,58 @@ class CachedBundle:
 
 def _bundle_cache_paths(api_key: str) -> tuple[Path, Path]:
     scope = _key_scope(api_key)
-    bin_path = _cache_dir() / f"bundle-{scope}.bin"
-    meta_path = _cache_dir() / f"bundle-{scope}.meta"
-    return bin_path, meta_path
+    d = _cache_dir()
+    # #1011 follow-up: the cached bundle uses the .czpolicy extension to match
+    # the UI policy export, so the auto-downloaded and hand-exported bundles
+    # share one recognizable suffix (both are the same signed CZ01 format).
+    bundle_path = d / f"bundle-{scope}.czpolicy"
+    meta_path = d / f"bundle-{scope}.meta"
+    return bundle_path, meta_path
 
 
 def load_cached_bundle(api_key: str) -> Optional[CachedBundle]:
-    bin_path, meta_path = _bundle_cache_paths(api_key)
-    if not bin_path.exists() or not meta_path.exists():
-        return None
+    # Read from the active (per-client) dir first, then the legacy shared dir
+    # (#1011 follow-up); within each dir prefer the current .czpolicy bundle and
+    # fall back to a legacy .bin so a pre-#1011 cache stays readable until the
+    # next successful fetch re-caches it under the new name/dir.
+    scope = _key_scope(api_key)
+    read_dirs = _cache_read_dirs()
+    primary = read_dirs[0]
+    for d in read_dirs:
+        meta_path = d / f"bundle-{scope}.meta"
+        if not meta_path.exists():
+            continue
+        bin_path = d / f"bundle-{scope}.czpolicy"
+        if not bin_path.exists():
+            bin_path = d / f"bundle-{scope}.bin"
+        if not bin_path.exists():
+            continue
+        loaded = _read_cached_bundle_pair(bin_path, meta_path)
+        if loaded is not None:
+            if d != primary:
+                # Migrate-on-read: copy the last-known-good bundle from the
+                # legacy shared cache into the active per-agent cache so the
+                # surface stops depending on the shared dir. Without this, the
+                # common upgrade path (next pull is a 304, so load_hosted_policy
+                # serves this cached bundle and never calls save_cached_bundle)
+                # would leave the per-agent cache empty indefinitely -- and if
+                # the shared cache were later GC'd, the surface would lose its
+                # last-known-good. Best-effort: a failed copy still serves the
+                # read. The bundle is re-written under the .czpolicy name.
+                try:
+                    save_cached_bundle(api_key, loaded.bytes_, loaded.etag)
+                except OSError:
+                    pass
+            return loaded
+    return None
+
+
+def _read_cached_bundle_pair(bin_path: Path, meta_path: Path) -> Optional[CachedBundle]:
     try:
         blob = bin_path.read_bytes()
         meta = json.loads(meta_path.read_text(encoding="utf-8"))
         stored_checksum = str(meta.get("checksum", ""))
-        # #1303 residual B (cache integrity): verify the .bin blob still
+        # #1303 residual B (cache integrity): verify the cached blob still
         # matches the sha256 checksum recorded in .meta. A mismatch means the
         # cached bundle on disk was tampered with, truncated, or corrupted
         # since it was written. We NEVER silently trust such a blob -- a

{controlzero-1.11.9 → controlzero-1.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.11.9"
+version = "1.12.0"
 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.11.9 → controlzero-1.12.0}/tests/test_cli_debug_bundle.py

@@ -345,7 +345,8 @@ def test_missing_bundle_file_emits_helpful_error(tmp_path, monkeypatch):
     )
     assert result.exit_code == 2, result.output
     assert "bundle file not found" in result.output
-    assert f"bundle-{prefix}.bin" in result.output
+    # #1011 follow-up: the default cache bundle extension is now .czpolicy.
+    assert f"bundle-{prefix}.czpolicy" in result.output
 
 
 def test_output_does_not_leak_encryption_key_or_signing_pubkey(cache_with_bundle):