zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/_hooks/cc_bridge.py

@@ -0,0 +1,1016 @@
+#!/usr/bin/env python3
+"""Claude Code -> zeno SQLite bridge (v2: event-time cognition capture).
+
+Wires Claude Code hook events into the local zeno store. v1 captured
+sessions/agent_runs/supervision_events so RTLX-S behavioral anchors populate.
+v2 ADDS the multi-dimensional cognition signal at EVENT TIME: it records the real
+prompt at UserPromptSubmit and, at Stop, reads the turn's transcript (tool uses,
+tokens, timing) and writes one rich cognition_samples row (five drivers + a
+composite) via the shared zeno_cognition model. The HUD and dashboard read those
+same rows, so the terminal bar and the timeline agree by construction.
+
+This fixes the v1 "attention flat at 50" problem: effort is the REAL submitted
+prompt (not re-derived from a coarse transcript tail), and there are now five axes
+(effort / autonomy / verification / fatigue / flow), each scored against the
+user's own rolling baseline.
+
+Event mapping:
+  SessionStart       -> INSERT sessions
+  UserPromptSubmit   -> INSERT agent_runs (open) + record the turn's prompt state
+  Stop               -> close the open agent_run + WRITE the cognition_samples row
+  Notification       -> INSERT supervision_events type='intervene'
+  SessionEnd         -> close open runs + set sessions.end_at
+
+Hard constraints (unchanged):
+  - stdlib only for the capture path; the ONE optional import is zeno_cognition
+    (also stdlib, light - no SDK/pandas/sqlalchemy), guarded so a missing zeno
+    checkout degrades to v1 capture, never an error
+  - ALWAYS exit 0, never block Claude Code on a zeno write failure
+  - bounded transcript reads (tail only) to stay fast on every fire
+  - debug log via env: ZENO_CC_BRIDGE_DEBUG=1 -> ~/.zeno/cc-bridge.log
+  - cognition schema is owned by zeno_cognition.ensure_schema (single source of
+    truth); the drift test guards it against the alembic migration
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import socket
+import sqlite3
+import sys
+import urllib.error
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+# datetime.UTC is 3.11+; the Mac Mini's system python3 is 3.9 (CLT). Shim it via
+# timezone.utc so this hook imports on every machine's python3. (Do not let ruff's
+# UP017 "rewrite to datetime.UTC" autofix touch this - it breaks 3.9.)
+UTC = timezone.utc  # noqa: UP017
+
+DEFAULT_PROJECT_SLUG: str = "default-project"
+DEFAULT_HARNESS: str = "claude-code"
+DEFAULT_MODEL: str = "claude-opus-4-8"
+
+TRANSCRIPT_TAIL_BYTES = 512 * 1024
+RECENT_SCORES = 6
+RECENT_DURATIONS = 8
+
+# ---------------------------------------------------------------------------
+# real-time cross-device sync (feat/realtime-sync) - PUSH side.
+#
+# After the SACRED local capture (commit + close) succeeds, the hook best-effort
+# POSTs the just-written event to the shared API so the dashboard + both HUDs
+# update live. EVERYTHING here is swallowed: a dead target, DNS failure, a slow
+# network - none of it can change the hook's exit code (always 0) or block
+# Claude Code. Stdlib only (urllib).
+#
+# PRIVACY (PRIVACY.md): the payload carries ONLY derived numeric scores + token
+# counts + bounded label fields (model/harness/event_name) + opaque ids. It
+# NEVER carries the prompt text or any transcript content. The server's schema
+# is extra="forbid", so a stray field would 422; we additionally never put one
+# in. _build_ingest_payload below is the single chokepoint and is allowlist-only.
+# ---------------------------------------------------------------------------
+DEFAULT_API_BASE_URL = "https://zeno-api-364453955482.us-west1.run.app"
+SYNC_PATH = "/v1/capture/ingest"
+SYNC_TIMEOUT_S = 0.4  # explicit socket timeout; overridable for tests
+OUTBOX_MAX_LINES = 500  # bounded append-only spool (drop-oldest)
+OUTBOX_DRAIN_BUDGET_S = 0.5  # time-box a best-effort drain after a live push
+OUTBOX_DRAIN_MAX = 5  # at most a few spooled lines per successful push
+
+# Lifecycle hook events map to a bounded event_name label sent to the API; this
+# allowlist is also what gates which events push at all (Notification stays local).
+_PUSH_EVENT_NAMES = {
+    "SessionStart": "session_start",
+    "UserPromptSubmit": "user_prompt_submit",
+    "Stop": "stop",
+    "SessionEnd": "session_end",
+}
+
+# Cross-event scratch: a Stop that wrote a cognition row stashes the derived-only
+# sample here so main() can push it AFTER conn.commit()/close(). Reset per process.
+_PENDING_PUSH: dict[str, dict] = {}
+
+# Optional shared cognition model. Light + stdlib, but guarded: a missing zeno
+# checkout (or any import error) degrades this hook to v1 capture, never breaks it.
+_COG = None
+try:  # pragma: no cover - import shim
+    # Prefer the copy bundled with an installed zeno-cli wheel (v2 capture works
+    # out of the box); fall back to a repo checkout for dev / dotfiles installs.
+    try:
+        from zeno_cli.hud import zeno_cognition as _COG  # type: ignore
+    except Exception:
+        # Fall back to a bare repo checkout (dev / dotfiles installs without the wheel).
+        # The cognition logic now lives ONLY in the CLI source; zeno_cognition has no
+        # relative imports, so it imports cleanly as a top-level module from that dir.
+        _cog_dir = os.path.expanduser(
+            os.environ.get("ZENO_COG_DIR", "~/github/zeno/apps/cli/src/zeno_cli/hud")
+        )
+        if os.path.isdir(_cog_dir) and _cog_dir not in sys.path:
+            sys.path.insert(0, _cog_dir)
+        import zeno_cognition as _COG  # type: ignore  # noqa: E402
+except Exception:
+    _COG = None
+
+
+def _now() -> datetime:
+    return datetime.now(tz=UTC)
+
+
+def _now_iso() -> str:
+    return _now().isoformat()
+
+
+def _zeno_home() -> Path:
+    return Path(os.environ.get("ZENO_HOME", str(Path.home() / ".zeno"))).expanduser()
+
+
+def _zeno_db_path() -> Path:
+    return Path(os.environ.get("ZENO_DB_PATH", str(_zeno_home() / "zeno.db"))).expanduser()
+
+
+def _project_id(slug: str) -> str:
+    return str(uuid.uuid5(uuid.NAMESPACE_URL, slug))
+
+
+# ---------------------------------------------------------------------------
+# device + account identity for the dedup triple (device_id, session_id, sample_id)
+# ---------------------------------------------------------------------------
+def _device_id() -> str:
+    """Stable per-machine id (first leg of the dedup triple).
+
+    The zeno session id is uuid5(cc_session_id), so the SAME cc session run on two
+    machines collapses to one uuid - device_id is what keeps the two operators'
+    rows distinct. Read-or-create a persisted uuid4 at ~/.zeno/device-id (0600);
+    if the file can't be read/written for any reason, fall back to the hostname so
+    we still emit a non-empty, machine-stable id. Never raises."""
+    path = _zeno_home() / "device-id"
+    try:
+        existing = path.read_text(encoding="utf-8").strip()
+        if existing:
+            return existing
+    except OSError:
+        pass
+    new_id = str(uuid.uuid4())
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(new_id, encoding="utf-8")
+        try:
+            os.chmod(tmp, 0o600)
+        except OSError:
+            pass
+        tmp.replace(path)
+        return new_id
+    except OSError:
+        # last resort: a hostname is machine-stable enough to keep two machines'
+        # colliding session uuid apart even if we can't persist the device file.
+        try:
+            host = socket.gethostname().strip()
+        except OSError:
+            host = ""
+        return host or new_id
+
+
+def _account_id() -> str | None:
+    """Optional account label. ZENO_ACCOUNT_ID lets one operator tag which Claude
+    account a turn came from; absent, it's None (the server stamps the
+    authoritative identity as server_user_id from the tailnet login)."""
+    val = (os.environ.get("ZENO_ACCOUNT_ID") or "").strip()
+    return val or None
+
+
+# ---------------------------------------------------------------------------
+# real-time push: build payload (derived numerics only) -> POST -> spool on fail
+# ---------------------------------------------------------------------------
+def _sync_disabled() -> bool:
+    return bool(os.environ.get("ZENO_SYNC_DISABLE"))
+
+
+def _api_base_url() -> str:
+    return (os.environ.get("ZENO_API_BASE_URL") or DEFAULT_API_BASE_URL).rstrip("/")
+
+
+def _sync_timeout_s() -> float:
+    try:
+        return float(os.environ.get("ZENO_SYNC_TIMEOUT_S") or SYNC_TIMEOUT_S)
+    except (TypeError, ValueError):
+        return SYNC_TIMEOUT_S
+
+
+def _outbox_path() -> Path:
+    return _zeno_home() / "outbox.ndjson"
+
+
+def _build_ingest_payload(event: str, payload: dict) -> dict | None:
+    """Build the ingest body for a hook event - the SINGLE privacy chokepoint.
+
+    Allowlist-only: every value is a derived numeric, a token count, a bounded
+    label (event_name/model/harness), or an opaque id. There is NO path here for
+    prompt text or transcript content to enter the payload. Returns None when the
+    event should not push (no session id, or an event not in the push allowlist).
+    """
+    event_name = _PUSH_EVENT_NAMES.get(event)
+    if event_name is None:
+        return None
+    cc_session = payload.get("session_id")
+    if not cc_session:
+        return None
+
+    pending = _PENDING_PUSH.get("sample") or {}
+    has_sample = event == "Stop" and bool(pending)
+    # A Stop with a written cognition row pushes the per-turn sample; otherwise
+    # (incl. a Stop that wrote no row, e.g. _COG None) it's a bare lifecycle event.
+    zeno_session = (
+        pending.get("zeno_session") if has_sample else _cc_session_to_zeno_session(cc_session)
+    )
+    model = payload.get("model")
+    if has_sample and not model:
+        model = pending.get("model")
+
+    body: dict = {
+        "device_id": _device_id(),
+        "account_id": _account_id(),
+        "event_name": event_name,
+        "session_id": zeno_session,
+        "cc_session_id": str(cc_session),
+        "harness": DEFAULT_HARNESS,
+        "model": model,
+        "ts": (pending.get("ts") if has_sample else _now_iso()),
+    }
+    if has_sample:
+        body["sample"] = pending.get("sample")
+    return body
+
+
+def _idempotency_key(body: dict) -> str:
+    """Stable per-(device, session, entity) key so a replay is a true no-op -
+    mirrors the server's effective_key when no header is sent."""
+    sample = body.get("sample") or {}
+    entity = sample.get("sample_id") or f"{body['event_name']}:{body['ts']}"
+    return f"{body['device_id']}:{body['session_id']}:{entity}"
+
+
+def _post_ingest(body: dict, timeout_s: float) -> bool:
+    """POST one ingest body. Returns True on a 2xx, False on any failure. Never
+    raises (all exceptions -> False). urllib + an explicit socket timeout only."""
+    url = _api_base_url() + SYNC_PATH
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Idempotency-Key": _idempotency_key(body),
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:  # noqa: S310 (trusted tailnet)
+            return 200 <= getattr(resp, "status", 0) < 300
+    except urllib.error.HTTPError as exc:
+        # The server answered (4xx/5xx). 409 = idempotent replay conflict (already
+        # stored) - treat as delivered so we don't spool a no-op forever. Other
+        # statuses are genuine failures worth spooling.
+        return exc.code == 409
+    except Exception:
+        return False
+
+
+def _spool(body: dict) -> None:
+    """Append one event to the bounded append-only outbox; drop oldest over cap.
+    Best-effort: a spool failure must never surface to the caller."""
+    try:
+        path = _outbox_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(body, separators=(",", ":"))
+        with path.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+        _trim_outbox(path)
+    except OSError as exc:
+        _debug(f"spool failed: {exc}")
+
+
+def _trim_outbox(path: Path) -> None:
+    """Enforce the hard line cap, dropping the OLDEST lines. Rewritten atomically."""
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            lines = f.readlines()
+        if len(lines) <= OUTBOX_MAX_LINES:
+            return
+        kept = lines[-OUTBOX_MAX_LINES:]
+        tmp = path.with_suffix(".tmp")
+        with tmp.open("w", encoding="utf-8") as f:
+            f.writelines(kept)
+        tmp.replace(path)
+    except OSError as exc:
+        _debug(f"trim_outbox failed: {exc}")
+
+
+def _drain_outbox(timeout_s: float) -> None:
+    """After a live push, best-effort + time-boxed drain of a few spooled lines.
+    Pushes oldest-first; stops at the budget, the line cap, or the first failure
+    (so an offline window doesn't re-spin). Rewrites the outbox with the remainder."""
+    path = _outbox_path()
+    try:
+        if not path.exists():
+            return
+        with path.open("r", encoding="utf-8") as f:
+            lines = [ln for ln in f.read().splitlines() if ln.strip()]
+    except OSError as exc:
+        _debug(f"drain read failed: {exc}")
+        return
+    if not lines:
+        return
+    deadline = _monotonic() + OUTBOX_DRAIN_BUDGET_S
+    consumed = 0  # count of leading lines fully resolved (delivered or dropped)
+    for line in lines:
+        if consumed >= OUTBOX_DRAIN_MAX or _monotonic() >= deadline:
+            break
+        try:
+            body = json.loads(line)
+        except Exception:
+            consumed += 1  # unparseable - drop it, keep draining
+            continue
+        if not _post_ingest(body, timeout_s):
+            break  # stop on first failure; leave this line + the rest spooled
+        consumed += 1
+    if consumed == 0:
+        return
+    remainder = lines[consumed:]
+    try:
+        if remainder:
+            tmp = path.with_suffix(".tmp")
+            with tmp.open("w", encoding="utf-8") as f:
+                f.write("\n".join(remainder) + "\n")
+            tmp.replace(path)
+        else:
+            path.unlink(missing_ok=True)
+    except OSError as exc:
+        _debug(f"drain rewrite failed: {exc}")
+
+
+def _monotonic() -> float:
+    import time
+
+    return time.monotonic()
+
+
+def _maybe_push(event: str, payload: dict) -> None:
+    """Post-commit push entrypoint. Builds the derived-only payload, POSTs it, and
+    on failure spools it; on success best-effort drains the spool. Swallows
+    EVERYTHING - capture has already been committed and the hook must still exit 0
+    regardless of any network outcome."""
+    if _sync_disabled():
+        return
+    try:
+        body = _build_ingest_payload(event, payload)
+        if body is None:
+            return
+        timeout_s = _sync_timeout_s()
+        if _post_ingest(body, timeout_s):
+            _drain_outbox(timeout_s)
+        else:
+            _spool(body)
+    except Exception as exc:  # network/build path must never break the hook
+        _debug(f"maybe_push failed: {exc}")
+
+
+def _cc_session_to_zeno_session(cc_session_id: str) -> str:
+    """Stable cc session_id -> zeno session UUID (uuid5 over 'cc:<id>')."""
+    return str(uuid.uuid5(uuid.NAMESPACE_URL, f"cc:{cc_session_id}"))
+
+
+def _debug(message: str) -> None:
+    if not os.environ.get("ZENO_CC_BRIDGE_DEBUG"):
+        return
+    log_path = _zeno_home() / "cc-bridge.log"
+    try:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with log_path.open("a", encoding="utf-8") as f:
+            f.write(f"{_now_iso()} {message}\n")
+    except OSError:
+        pass
+
+
+def _parse_ts(s):
+    if not isinstance(s, str) or not s:
+        return None
+    try:
+        dt = datetime.fromisoformat(s.replace("Z", "+00:00"))
+    except Exception:
+        return None
+    # Normalize naive timestamps to UTC-aware. _now() is always aware, so a naive
+    # transcript ts (hand-edited / imported / a non-CC tool) would otherwise raise
+    # TypeError on the ts<since compare or the now-ts subtraction and silently drop
+    # the whole turn's cognition sample. Assume UTC for a naive value.
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt
+
+
+# ---------------------------------------------------------------------------
+# capture schema (v1 tables; cognition_samples is owned by zeno_cognition)
+# ---------------------------------------------------------------------------
+def _ensure_schema(conn: sqlite3.Connection) -> None:
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS sessions (
+            id TEXT PRIMARY KEY, start_at TEXT NOT NULL, end_at TEXT,
+            agent_count_max INTEGER NOT NULL, harness TEXT NOT NULL,
+            project_id TEXT NOT NULL, synced_at TEXT
+        );
+        CREATE TABLE IF NOT EXISTS agent_runs (
+            id TEXT PRIMARY KEY, session_id TEXT NOT NULL, harness TEXT NOT NULL,
+            model TEXT NOT NULL, started_at TEXT NOT NULL, ended_at TEXT,
+            outcome TEXT NOT NULL, synced_at TEXT
+        );
+        CREATE INDEX IF NOT EXISTS ix_agent_runs_session_id ON agent_runs (session_id);
+        CREATE TABLE IF NOT EXISTS supervision_events (
+            id TEXT PRIMARY KEY, session_id TEXT NOT NULL, agent_run_id TEXT,
+            type TEXT NOT NULL, timestamp TEXT NOT NULL, latency_ms_to_decide INTEGER,
+            metadata_json TEXT NOT NULL DEFAULT '{}', synced_at TEXT
+        );
+        CREATE INDEX IF NOT EXISTS ix_supervision_events_session_id
+            ON supervision_events (session_id);
+        CREATE INDEX IF NOT EXISTS ix_supervision_events_agent_run_id
+            ON supervision_events (agent_run_id);
+        CREATE TABLE IF NOT EXISTS load_probes (
+            id TEXT PRIMARY KEY, session_id TEXT NOT NULL, prompted_at TEXT NOT NULL,
+            responded_at TEXT, skipped INTEGER NOT NULL, subscales_json TEXT, synced_at TEXT
+        );
+        CREATE INDEX IF NOT EXISTS ix_load_probes_session_id ON load_probes (session_id);
+        CREATE TABLE IF NOT EXISTS babysitting_tax_points (
+            id TEXT PRIMARY KEY, session_id TEXT NOT NULL, n_agents_active INTEGER NOT NULL,
+            composite_load REAL NOT NULL, output_quality REAL, synced_at TEXT
+        );
+        CREATE INDEX IF NOT EXISTS ix_babysitting_tax_points_session_id
+            ON babysitting_tax_points (session_id);
+        """)
+    # cognition_samples schema is owned by the shared model (single source of truth).
+    if _COG is not None:
+        try:
+            _COG.ensure_schema(conn)
+        except Exception as exc:  # never let cognition schema break capture
+            _debug(f"cognition ensure_schema failed: {exc}")
+
+
+def _open_db() -> sqlite3.Connection:
+    db_path = _zeno_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(db_path, timeout=2.0)
+    conn.execute("PRAGMA journal_mode = WAL")
+    conn.execute("PRAGMA synchronous = NORMAL")
+    _ensure_schema(conn)
+    return conn
+
+
+# ---------------------------------------------------------------------------
+# per-session turn-state (cross-event scratch for the cognition signal)
+# ---------------------------------------------------------------------------
+def _turn_state_path(zeno_session: str) -> Path:
+    return _zeno_home() / "turn-state" / f"{zeno_session}.json"
+
+
+def _load_turn_state(zeno_session: str) -> dict:
+    try:
+        p = _turn_state_path(zeno_session)
+        if p.exists():
+            return json.loads(p.read_text()) or {}
+    except Exception:
+        pass
+    return {}
+
+
+def _save_turn_state(zeno_session: str, state: dict) -> None:
+    try:
+        p = _turn_state_path(zeno_session)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        tmp = p.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state))
+        tmp.replace(p)
+    except Exception:
+        pass
+
+
+def _baseline_path() -> str:
+    return str(_zeno_home() / "cognition-baseline.json")
+
+
+def _cv(values) -> float:
+    """Coefficient of variation of recent durations, mapped to 0..1 (irregularity)."""
+    vals = [float(v) for v in values if isinstance(v, (int, float)) and v >= 0]
+    if len(vals) < 3:
+        return 0.0
+    mean = sum(vals) / len(vals)
+    if mean <= 1e-6:
+        return 0.0
+    var = sum((v - mean) ** 2 for v in vals) / len(vals)
+    cv = math.sqrt(var) / mean
+    return max(0.0, min(1.0, cv))
+
+
+# ---------------------------------------------------------------------------
+# transcript stats for the current turn (tool uses, tokens) - bounded tail read
+# ---------------------------------------------------------------------------
+def _is_tool_result_only(obj) -> bool:
+    """True when a ``user`` transcript line is a tool-result echo, not a human turn.
+
+    Claude Code emits the result of every assistant ``tool_use`` as a ``user``-type
+    line whose ``message.content`` is a list of ``type=="tool_result"`` blocks. Those
+    are mid-turn, NOT human-prompt boundaries - the ``since is None`` fallback below
+    must not reset its per-turn counters on them, or a tool_use -> tool_result ->
+    tool_use interleave gets truncated to only the tail after the last tool result.
+    A human message's content is a string, or a list that includes text/image blocks.
+    """
+    msg = obj.get("message") or {}
+    content = msg.get("content")
+    if not isinstance(content, list) or not content:
+        return False
+    return all(isinstance(b, dict) and b.get("type") == "tool_result" for b in content)
+
+
+def _last_turn_stats(transcript_path, since_iso) -> dict:
+    out = {
+        "tool_uses": 0,
+        "edits": 0,
+        "input": None,
+        "output": None,
+        "cache_read": None,
+        "cache_creation": None,
+        "total": None,
+    }
+    if not transcript_path or not os.path.exists(transcript_path):
+        return out
+    try:
+        size = os.path.getsize(transcript_path)
+        with open(transcript_path, "rb") as f:
+            if size > TRANSCRIPT_TAIL_BYTES:
+                f.seek(size - TRANSCRIPT_TAIL_BYTES)
+                f.readline()  # discard partial line
+            data = f.read().decode("utf-8", "replace")
+    except Exception:
+        return out
+    since = _parse_ts(since_iso)
+    # Bounded guard: when `since` is None (turn-state lost, or a Stop fired without a
+    # recorded UserPromptSubmit), the `since and ts < since` filter below is a no-op,
+    # so WITHOUT this we would attribute the WHOLE ~512KB tail - many turns - to one
+    # sample and badly inflate tool_uses/tokens. Heuristic fallback: count only the
+    # final turn, i.e. reset the per-turn counters at each user-message boundary so we
+    # keep just the assistant messages after the last human turn in the tail.
+    use_boundary = since is None
+    last_usage = None
+    for line in data.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            o = json.loads(line)
+        except Exception:
+            continue
+        otype = o.get("type")
+        if use_boundary and otype == "user" and not _is_tool_result_only(o):
+            # new human turn: drop everything accumulated for the previous turn.
+            # A tool_result user-line (message.content all type=="tool_result") is the
+            # echo of the assistant's own tool call, NOT a turn boundary - skip the
+            # reset for those so a tool_use -> tool_result -> tool_use interleave keeps
+            # every tool_use of the final turn instead of truncating at the last result.
+            out["tool_uses"] = 0
+            out["edits"] = 0
+            last_usage = None
+            continue
+        if otype != "assistant":
+            continue
+        ts = _parse_ts(o.get("timestamp"))
+        if since and ts and ts < since:
+            continue  # only this turn's assistant messages
+        msg = o.get("message") or {}
+        content = msg.get("content")
+        if isinstance(content, list):
+            for b in content:
+                if isinstance(b, dict) and b.get("type") == "tool_use":
+                    out["tool_uses"] += 1
+                    if (b.get("name") or "").lower() in (
+                        "edit",
+                        "write",
+                        "multiedit",
+                        "notebookedit",
+                    ):
+                        out["edits"] += 1
+        u = msg.get("usage")
+        if isinstance(u, dict) and u:
+            last_usage = u
+    if last_usage:
+        out["input"] = last_usage.get("input_tokens")
+        out["output"] = last_usage.get("output_tokens")
+        out["cache_read"] = last_usage.get("cache_read_input_tokens")
+        cc = last_usage.get("cache_creation")
+        if isinstance(cc, dict):
+            out["cache_creation"] = (cc.get("ephemeral_5m_input_tokens") or 0) + (
+                cc.get("ephemeral_1h_input_tokens") or 0
+            )
+        else:
+            out["cache_creation"] = last_usage.get("cache_creation_input_tokens")
+        parts = [
+            p
+            for p in (out["input"], out["output"], out["cache_read"], out["cache_creation"])
+            if isinstance(p, (int, float))
+        ]
+        out["total"] = sum(parts) if parts else None
+    return out
+
+
+# ---------------------------------------------------------------------------
+# event handlers
+# ---------------------------------------------------------------------------
+def handle_session_start(conn: sqlite3.Connection, payload: dict) -> None:
+    cc_session = payload.get("session_id")
+    if not cc_session:
+        return
+    zeno_session = _cc_session_to_zeno_session(cc_session)
+    conn.execute(
+        """
+        INSERT OR IGNORE INTO sessions
+            (id, start_at, end_at, agent_count_max, harness, project_id, synced_at)
+        VALUES (?, ?, NULL, 1, ?, ?, NULL)
+        """,
+        (zeno_session, _now_iso(), DEFAULT_HARNESS, _project_id(DEFAULT_PROJECT_SLUG)),
+    )
+
+
+def handle_user_prompt_submit(conn: sqlite3.Connection, payload: dict) -> None:
+    cc_session = payload.get("session_id")
+    if not cc_session:
+        return
+    zeno_session = _cc_session_to_zeno_session(cc_session)
+    conn.execute(
+        """
+        INSERT OR IGNORE INTO sessions
+            (id, start_at, end_at, agent_count_max, harness, project_id, synced_at)
+        VALUES (?, ?, NULL, 1, ?, ?, NULL)
+        """,
+        (zeno_session, _now_iso(), DEFAULT_HARNESS, _project_id(DEFAULT_PROJECT_SLUG)),
+    )
+    model = payload.get("model") or os.environ.get("CLAUDE_MODEL", DEFAULT_MODEL)
+    conn.execute(
+        """
+        INSERT INTO agent_runs
+            (id, session_id, harness, model, started_at, ended_at, outcome, synced_at)
+        VALUES (?, ?, ?, ?, ?, NULL, 'unknown', NULL)
+        """,
+        (str(uuid.uuid4()), zeno_session, DEFAULT_HARNESS, model, _now_iso()),
+    )
+    _update_agent_count_max(conn, zeno_session)
+    _record_pending_prompt(zeno_session, payload)
+
+
+def _record_pending_prompt(zeno_session: str, payload: dict) -> None:
+    """Record the real submitted prompt for this turn (the effort signal) + the
+    review gap since the agent last stopped (the verification think-time). Stored
+    in turn-state and consumed at Stop. Best-effort; never raises."""
+    if _COG is None:
+        return
+    try:
+        text = (payload.get("prompt") or "").strip()
+        low = text.lower()
+        state = _load_turn_state(zeno_session)
+        now = _now()
+        last_stop = _parse_ts(state.get("last_stop_ts"))
+        review_gap = (now - last_stop).total_seconds() if last_stop else 0.0
+        lead = len(text) <= 6 and low in (
+            "y",
+            "yes",
+            "go",
+            "ok",
+            "continue",
+            "do it",
+            "ship it",
+            "next",
+        )
+        correction_markers = (
+            "fix",
+            "wrong",
+            "still",
+            "broken",
+            "redo",
+            "revert",
+            "undo",
+            "no,",
+            "not work",
+        )
+        error_markers = ("error", "broken", "failing", "traceback", "exception")
+        is_correction = any(m in low for m in correction_markers)
+        streak = int(state.get("correction_streak", 0))
+        streak = streak + 1 if is_correction else 0
+        state["correction_streak"] = streak
+        state["pending"] = {
+            "prompt_ts": now.isoformat(),
+            "review_gap_s": round(max(0.0, review_gap), 1),
+            "chars": len(text),
+            "has_code": "```" in text,
+            "multiline": text.count("\n") >= 2,
+            "lead_word": lead,
+            "reprompts": streak,
+            "errors": any(m in low for m in error_markers),
+        }
+        _save_turn_state(zeno_session, state)
+    except Exception as exc:
+        _debug(f"record_pending failed: {exc}")
+
+
+def _update_agent_count_max(conn: sqlite3.Connection, zeno_session: str) -> None:
+    open_count = conn.execute(
+        "SELECT COUNT(*) FROM agent_runs WHERE session_id = ? AND ended_at IS NULL",
+        (zeno_session,),
+    ).fetchone()[0]
+    conn.execute(
+        "UPDATE sessions SET agent_count_max = MAX(agent_count_max, ?) WHERE id = ?",
+        (open_count, zeno_session),
+    )
+
+
+def handle_stop(conn: sqlite3.Connection, payload: dict) -> None:
+    cc_session = payload.get("session_id")
+    if not cc_session:
+        return
+    zeno_session = _cc_session_to_zeno_session(cc_session)
+    row = conn.execute(
+        """
+        SELECT id, started_at FROM agent_runs
+        WHERE session_id = ? AND ended_at IS NULL
+        ORDER BY started_at DESC LIMIT 1
+        """,
+        (zeno_session,),
+    ).fetchone()
+    if row is not None:
+        run_id, started_at = row
+        conn.execute(
+            "UPDATE agent_runs SET ended_at = ?, outcome = ? WHERE id = ?",
+            (_now_iso(), _infer_outcome(conn, zeno_session, started_at), run_id),
+        )
+    _write_cognition(conn, payload, zeno_session)
+
+
+def _write_cognition(conn: sqlite3.Connection, payload: dict, zeno_session: str) -> None:
+    """Compose the five drivers for the just-finished turn and write one
+    cognition_samples row. Best-effort: any failure leaves capture intact."""
+    if _COG is None:
+        return
+    try:
+        state = _load_turn_state(zeno_session)
+        pending = state.get("pending") or {}
+        now = _now()
+
+        prompt_ts = _parse_ts(pending.get("prompt_ts"))
+        autonomous_s = (now - prompt_ts).total_seconds() if prompt_ts else 0.0
+        review_gap_s = float(pending.get("review_gap_s", 0.0) or 0.0)
+
+        start_row = conn.execute(
+            "SELECT start_at FROM sessions WHERE id = ?", (zeno_session,)
+        ).fetchone()
+        start_ts = _parse_ts(start_row[0]) if start_row else None
+        active_min = ((now - start_ts).total_seconds() / 60.0) if start_ts else 0.0
+
+        # Bound the transcript scan: prefer this turn's prompt_ts, but if it was lost
+        # (turn-state missing / Stop without a recorded UserPromptSubmit) fall back to
+        # the session start_at so we never pass since=None and over-count the tail.
+        since_iso = pending.get("prompt_ts") or (start_row[0] if start_row else None)
+        tstats = _last_turn_stats(payload.get("transcript_path"), since_iso)
+
+        durations = state.get("durations", [])
+        durations.append(round(max(0.0, autonomous_s), 1))
+        durations = durations[-RECENT_DURATIONS:]
+        inter_var = _cv(durations)
+        cadence_reg = max(0.0, 1.0 - inter_var)
+
+        reprompts = int(pending.get("reprompts", 0))
+        churn = min(1.0, reprompts / 3.0)
+        errors = bool(pending.get("errors"))
+        effort_level = None
+        eff = payload.get("effort")
+        if isinstance(eff, dict):
+            effort_level = eff.get("level")
+
+        raw = {
+            "effort": _COG.effort_raw(
+                pending.get("chars", 0),
+                pending.get("has_code", False),
+                pending.get("multiline", False),
+                effort_level,
+                pending.get("lead_word", False),
+            ),
+            "autonomy": _COG.autonomy_raw(
+                tstats["tool_uses"], pending.get("chars", 0), autonomous_s
+            ),
+            # accepts/rejects left 0: agent edit count is NOT a human accept/reject
+            # decision - feeding it would raise "review" exactly when autonomous
+            # editing is heaviest (backwards). gap + reprompts + churn carry
+            # verification until a real accept/reject signal exists.
+            "verification": _COG.verification_raw(review_gap_s, reprompts, churn),
+            "fatigue": _COG.fatigue_raw(active_min, inter_var, now.astimezone().hour),
+            "flow": _COG.flow_raw(cadence_reg, 0.5),
+        }
+
+        bl = _COG.Baselines.load(_baseline_path())
+        recent = [s for s in state.get("recent_scores", []) if isinstance(s, (int, float))]
+        context = {"long_session": active_min >= 120, "churn": churn, "errors": errors}
+        comp = _COG.compose(raw, bl, recent, context)
+
+        # always update baselines (even if compose declined) so they keep learning
+        for d, v in raw.items():
+            bl.update(d, v)
+        bl.save(_baseline_path())
+
+        if comp.get("ok"):
+            total = tstats["total"]
+            ctx_pct = None
+            ins = [tstats["input"], tstats["cache_read"], tstats["cache_creation"]]
+            if any(isinstance(x, (int, float)) for x in ins):
+                used = sum(x for x in ins if isinstance(x, (int, float)))
+                ctx_pct = round(min(100.0, used / 2000.0), 1)  # est. vs ~200k window
+            drv = comp["drivers"]
+            model = payload.get("model") or DEFAULT_MODEL
+            # The cognition row id IS the sample_id - the third leg of the dedup
+            # triple (device_id, session_id, sample_id). Pushing the same id keeps
+            # the local row and the synced row identified by construction.
+            sample_id = str(uuid.uuid4())
+            conn.execute(
+                """
+                INSERT INTO cognition_samples (
+                    id, session_id, ts, context_pct,
+                    input_tokens, output_tokens, cache_read_tokens,
+                    cache_creation_tokens, total_tokens,
+                    attention_score, attention_effort, attention_deliberation,
+                    attention_trend, model, harness,
+                    attention_autonomy, attention_verification,
+                    attention_fatigue, attention_flow
+                ) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+                """,
+                (
+                    sample_id,
+                    zeno_session,
+                    now.isoformat(),
+                    ctx_pct,
+                    tstats["input"],
+                    tstats["output"],
+                    tstats["cache_read"],
+                    tstats["cache_creation"],
+                    total,
+                    comp["score"],
+                    drv.get("effort"),
+                    None,  # attention_deliberation: v1 legacy column, unused in v2
+                    comp.get("trend"),
+                    model,
+                    DEFAULT_HARNESS,
+                    drv.get("autonomy"),
+                    drv.get("verification"),
+                    drv.get("fatigue"),
+                    drv.get("flow"),
+                ),
+            )
+            recent.append(comp["score"])
+            recent = recent[-RECENT_SCORES:]
+
+            # Stash the DERIVED-ONLY sample for the post-commit push. Numerics +
+            # bounded labels + ids ONLY - never any prompt/transcript text. main()
+            # consumes _PENDING_PUSH after conn.commit()/close() so capture stays
+            # decoupled from the network.
+            _PENDING_PUSH["sample"] = {
+                "zeno_session": zeno_session,
+                "ts": now.isoformat(),
+                "model": model,
+                "sample": {
+                    "sample_id": sample_id,
+                    "attention_score": comp["score"],
+                    "attention_effort": drv.get("effort"),
+                    "attention_autonomy": drv.get("autonomy"),
+                    "attention_verification": drv.get("verification"),
+                    "attention_fatigue": drv.get("fatigue"),
+                    "attention_flow": drv.get("flow"),
+                    "attention_trend": comp.get("trend"),
+                    "context_pct": ctx_pct,
+                    "input_tokens": tstats["input"],
+                    "output_tokens": tstats["output"],
+                    "cache_read_tokens": tstats["cache_read"],
+                    "cache_creation_tokens": tstats["cache_creation"],
+                    "total_tokens": total,
+                },
+            }
+
+        state["recent_scores"] = recent
+        state["durations"] = durations
+        state["last_stop_ts"] = now.isoformat()
+        state["pending"] = {}
+        _save_turn_state(zeno_session, state)
+    except Exception as exc:
+        _debug(f"write_cognition failed: {exc}")
+
+
+def _infer_outcome(conn: sqlite3.Connection, zeno_session: str, started_at: str) -> str:
+    intervened = conn.execute(
+        """
+        SELECT 1 FROM supervision_events
+        WHERE session_id = ? AND type = 'intervene' AND timestamp >= ? LIMIT 1
+        """,
+        (zeno_session, started_at),
+    ).fetchone()
+    return "unknown" if intervened else "completed"
+
+
+def handle_notification(conn: sqlite3.Connection, payload: dict) -> None:
+    cc_session = payload.get("session_id")
+    if not cc_session:
+        return
+    zeno_session = _cc_session_to_zeno_session(cc_session)
+    metadata = {"source": "cc:notification"}
+    message = payload.get("message")
+    if isinstance(message, str) and message:
+        metadata["message"] = message[:200]
+    conn.execute(
+        """
+        INSERT INTO supervision_events
+            (id, session_id, agent_run_id, type, timestamp,
+             latency_ms_to_decide, metadata_json, synced_at)
+        VALUES (?, ?, NULL, 'intervene', ?, NULL, ?, NULL)
+        """,
+        (str(uuid.uuid4()), zeno_session, _now_iso(), json.dumps(metadata)),
+    )
+
+
+def handle_session_end(conn: sqlite3.Connection, payload: dict) -> None:
+    cc_session = payload.get("session_id")
+    if not cc_session:
+        return
+    zeno_session = _cc_session_to_zeno_session(cc_session)
+    now = _now_iso()
+    open_runs = conn.execute(
+        "SELECT id, started_at FROM agent_runs WHERE session_id = ? AND ended_at IS NULL",
+        (zeno_session,),
+    ).fetchall()
+    for run_id, started_at in open_runs:
+        conn.execute(
+            "UPDATE agent_runs SET ended_at = ?, outcome = ? WHERE id = ?",
+            (now, _infer_outcome(conn, zeno_session, started_at), run_id),
+        )
+    conn.execute(
+        "UPDATE sessions SET end_at = ? WHERE id = ? AND end_at IS NULL",
+        (now, zeno_session),
+    )
+    # tidy the per-session turn-state scratch
+    try:
+        _turn_state_path(zeno_session).unlink(missing_ok=True)
+    except Exception:
+        pass
+
+
+_DISPATCH = {
+    "SessionStart": handle_session_start,
+    "UserPromptSubmit": handle_user_prompt_submit,
+    "Stop": handle_stop,
+    "Notification": handle_notification,
+    "SessionEnd": handle_session_end,
+}
+
+
+def main() -> int:
+    raw = sys.stdin.read()
+    try:
+        payload = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        _debug(f"bad json: {raw[:200]!r}")
+        return 0
+    event = payload.get("hook_event_name")
+    handler = _DISPATCH.get(event)
+    if handler is None:
+        _debug(f"no handler for event: {event!r}")
+        return 0
+    _PENDING_PUSH.clear()  # fresh per invocation; never inherit a prior stash
+    try:
+        conn = _open_db()
+    except sqlite3.Error as exc:
+        _debug(f"open_db failed: {exc}")
+        return 0
+    committed = False
+    try:
+        handler(conn, payload)
+        conn.commit()
+        committed = True
+        _debug(f"handled {event} for session {payload.get('session_id')!r}")
+    except sqlite3.Error as exc:
+        _debug(f"handler error on {event}: {exc}")
+    except Exception as exc:  # cognition path must never break capture
+        _debug(f"unexpected error on {event}: {exc}")
+    finally:
+        conn.close()
+    # LOCAL CAPTURE IS SACRED: the push runs STRICTLY AFTER the local commit/close
+    # above, only when that commit succeeded, and is fully swallowed inside
+    # _maybe_push. The hook ALWAYS returns 0 regardless of any network outcome.
+    if committed:
+        _maybe_push(event, payload)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())