getlogbook 0.0.1__tar.gz

getlogbook-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Veertej Sehdave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

getlogbook-0.0.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: getlogbook
+Version: 0.0.1
+Summary: Commit-anchored shared memory for AI-assisted repos (stdlib only).
+Author: Veertej Sehdave
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vssehdave/Logbook
+Project-URL: Issues, https://github.com/vssehdave/Logbook/issues
+Keywords: git,ai-agents,dbt,memory,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Logbook
+
+Commit-anchored shared memory for AI-assisted repos. It records **why** code and warehouse models changed
+(what was wrong, how wrong, the fix) next to the git history, so a teammate or an AI agent can pick up where the
+last person left off. Works for any repo; dbt-style repos get layer awareness (`stg_`, `int_`, `fct_`, `dim_`).
+
+- Python 3.10+, **standard library only**, git 2.31+. Windows, macOS, Linux. No server to host, no model calls (`backend none`).
+- Two logs: a **private** one under `.git/logbook/` (never tracked), and a **shared** one on git refs
+  (`refs/logbook/log/<user>/<device>`, one writer per ref, so no merge conflicts). Sharing is opt-in per entry.
+- A live local viewer (`logbook serve`) shows the shared tree with your private entries overlaid.
+
+**Status: alpha (0.0.1).** The engine, git-ref storage, sharing and the viewer work and are tested on Linux, macOS and Windows.
+Not built yet: nothing prompts an agent to write a note, so real reasons exist only when someone runs `logbook note`;
+notes written on a branch before its first commit are not followed through a merge; there are no summaries above commits;
+setup is three separate commands; Claude Code is the only host. Entries marked `inferred` are copied from the commit message
+or a truncated transcript. They carry no reason and are never injected into an agent's prompt.
+
+## Try it (no credentials, about 30 seconds)
+
+    pip install getlogbook   # from a clone: pip install .   (or: PYTHONPATH=src python -m getlogbook ...)
+                             # the command is `logbook`; the package name is getlogbook because `logbook` on PyPI is taken
+    logbook demo           # Alice, Bob and a hostile Mallory on a scratch repo; every claim is checked
+    logbook demo --serve   # same, then open the viewer on Bob's clone
+
+## Daily use
+
+    logbook init                              # once per clone (git config user.email must be set)
+    logbook install-hook                      # git floor: copies each of your commits into an `inferred` entry (no reason)
+    logbook install --agent claude-code --write   # merges hooks into .claude/settings.local.json (dry run without --write)
+    logbook note --kind finding --topic "late payments" --summary "revenue dip" --why "export stalled" --wrong "1 day under"
+    logbook note --kind change --before-commit --summary "..." --why "..." --wrong "..." --fix "..."   # then commit as usual
+    logbook publish <id>                      # preview + redaction, you confirm; evidence is opt-in
+    logbook sync                              # fetch teammates' entries, push yours
+    logbook query "refunds" | explain fct_revenue | path <rev> <rev>   # exit 0 found, 3 ambiguous, 4 no match
+    logbook serve --open
+    logbook doctor                            # setup + what is NOT captured
+
+New teammate: clone, then `logbook join`. A plain `git clone`/`git fetch` does not download logbook refs.
+CI: `git fetch --depth=1 origin '+refs/logbook/log/*:refs/logbook-remote/origin/log/*'` (opt in; off by default).
+
+## How an agent consults it first
+
+Hooks (Claude Code is the only adapter shipped): `SessionStart` and `UserPromptSubmit` inject a digest of at most ~1,500
+characters, only when the prompt names a known model or path, only from people who have commits on this history (or whom you
+ran `logbook trust` on), only entries that say *why* or
+*how wrong*, finding first, each labelled with author, provenance, age, commits behind HEAD and "verify first". Each note
+is shown once per session. Agents without hooks: `logbook snippet` prints text for CLAUDE.md / AGENTS.md. Injection
+guarantees the notes are in context, not that the model uses them.
+
+## Safety defaults
+
+- Entries from other writers are **untrusted data**: author comes from the ref path, never from the file; text is
+  sanitised (links, code fences, instruction-like lines, angle brackets removed) before it reaches an agent, in `inject`
+  and in CLI output; the viewer renders only with `textContent` under a strict CSP.
+- Every entry is recorded, searchable and visible in the viewer. Trust only decides what is *automatically injected into an
+  agent's prompt*: your own entries, entries from anyone with a commit on this history (no setup), and writers you ran
+  `logbook trust <user-id>` on. A writer with push access who never committed is searchable but not injected.
+  Strict mode: `"inject_from": "self"` in `.logbook/policy.json`, or `trust_committers: false` in your config.
+  Limit: the id in a ref path is self-asserted, so anyone who can push refs could write under a committer's id; only
+  host-side ref protection prevents that.
+- Publishing: allowlisted fields only, secrets/emails/connection strings masked, pasted table rows refused, exact-bytes preview
+  with hash check, a local audit log. Redaction is a lint, not a guarantee. Published text can persist in forks and mirrors.
+- `logbook purge <id> --push` rewrites your own ref without the entry and leaves an id-only tombstone. Rotate any leaked secret.
+- Optional `.logbook/policy.json` (tracked): `publish`, `inject_from` (`self`|`trusted`), `attribution` (`none`|`pseudonym`|`named`
+  ceiling), `max_entry_bytes`. The client only ever gets stricter from it. Default attribution is a pseudonymous id.
+
+See `docs/DESIGN.md` for decisions, the failure-mode table, and what is not built.

getlogbook-0.0.1/README.md

@@ -0,0 +1,67 @@
+# Logbook
+
+Commit-anchored shared memory for AI-assisted repos. It records **why** code and warehouse models changed
+(what was wrong, how wrong, the fix) next to the git history, so a teammate or an AI agent can pick up where the
+last person left off. Works for any repo; dbt-style repos get layer awareness (`stg_`, `int_`, `fct_`, `dim_`).
+
+- Python 3.10+, **standard library only**, git 2.31+. Windows, macOS, Linux. No server to host, no model calls (`backend none`).
+- Two logs: a **private** one under `.git/logbook/` (never tracked), and a **shared** one on git refs
+  (`refs/logbook/log/<user>/<device>`, one writer per ref, so no merge conflicts). Sharing is opt-in per entry.
+- A live local viewer (`logbook serve`) shows the shared tree with your private entries overlaid.
+
+**Status: alpha (0.0.1).** The engine, git-ref storage, sharing and the viewer work and are tested on Linux, macOS and Windows.
+Not built yet: nothing prompts an agent to write a note, so real reasons exist only when someone runs `logbook note`;
+notes written on a branch before its first commit are not followed through a merge; there are no summaries above commits;
+setup is three separate commands; Claude Code is the only host. Entries marked `inferred` are copied from the commit message
+or a truncated transcript. They carry no reason and are never injected into an agent's prompt.
+
+## Try it (no credentials, about 30 seconds)
+
+    pip install getlogbook   # from a clone: pip install .   (or: PYTHONPATH=src python -m getlogbook ...)
+                             # the command is `logbook`; the package name is getlogbook because `logbook` on PyPI is taken
+    logbook demo           # Alice, Bob and a hostile Mallory on a scratch repo; every claim is checked
+    logbook demo --serve   # same, then open the viewer on Bob's clone
+
+## Daily use
+
+    logbook init                              # once per clone (git config user.email must be set)
+    logbook install-hook                      # git floor: copies each of your commits into an `inferred` entry (no reason)
+    logbook install --agent claude-code --write   # merges hooks into .claude/settings.local.json (dry run without --write)
+    logbook note --kind finding --topic "late payments" --summary "revenue dip" --why "export stalled" --wrong "1 day under"
+    logbook note --kind change --before-commit --summary "..." --why "..." --wrong "..." --fix "..."   # then commit as usual
+    logbook publish <id>                      # preview + redaction, you confirm; evidence is opt-in
+    logbook sync                              # fetch teammates' entries, push yours
+    logbook query "refunds" | explain fct_revenue | path <rev> <rev>   # exit 0 found, 3 ambiguous, 4 no match
+    logbook serve --open
+    logbook doctor                            # setup + what is NOT captured
+
+New teammate: clone, then `logbook join`. A plain `git clone`/`git fetch` does not download logbook refs.
+CI: `git fetch --depth=1 origin '+refs/logbook/log/*:refs/logbook-remote/origin/log/*'` (opt in; off by default).
+
+## How an agent consults it first
+
+Hooks (Claude Code is the only adapter shipped): `SessionStart` and `UserPromptSubmit` inject a digest of at most ~1,500
+characters, only when the prompt names a known model or path, only from people who have commits on this history (or whom you
+ran `logbook trust` on), only entries that say *why* or
+*how wrong*, finding first, each labelled with author, provenance, age, commits behind HEAD and "verify first". Each note
+is shown once per session. Agents without hooks: `logbook snippet` prints text for CLAUDE.md / AGENTS.md. Injection
+guarantees the notes are in context, not that the model uses them.
+
+## Safety defaults
+
+- Entries from other writers are **untrusted data**: author comes from the ref path, never from the file; text is
+  sanitised (links, code fences, instruction-like lines, angle brackets removed) before it reaches an agent, in `inject`
+  and in CLI output; the viewer renders only with `textContent` under a strict CSP.
+- Every entry is recorded, searchable and visible in the viewer. Trust only decides what is *automatically injected into an
+  agent's prompt*: your own entries, entries from anyone with a commit on this history (no setup), and writers you ran
+  `logbook trust <user-id>` on. A writer with push access who never committed is searchable but not injected.
+  Strict mode: `"inject_from": "self"` in `.logbook/policy.json`, or `trust_committers: false` in your config.
+  Limit: the id in a ref path is self-asserted, so anyone who can push refs could write under a committer's id; only
+  host-side ref protection prevents that.
+- Publishing: allowlisted fields only, secrets/emails/connection strings masked, pasted table rows refused, exact-bytes preview
+  with hash check, a local audit log. Redaction is a lint, not a guarantee. Published text can persist in forks and mirrors.
+- `logbook purge <id> --push` rewrites your own ref without the entry and leaves an id-only tombstone. Rotate any leaked secret.
+- Optional `.logbook/policy.json` (tracked): `publish`, `inject_from` (`self`|`trusted`), `attribution` (`none`|`pseudonym`|`named`
+  ceiling), `max_entry_bytes`. The client only ever gets stricter from it. Default attribution is a pseudonymous id.
+
+See `docs/DESIGN.md` for decisions, the failure-mode table, and what is not built.

getlogbook-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "getlogbook"
+version = "0.0.1"
+description = "Commit-anchored shared memory for AI-assisted repos (stdlib only)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Veertej Sehdave" }]
+keywords = ["git", "ai-agents", "dbt", "memory", "developer-tools"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/vssehdave/Logbook"
+Issues = "https://github.com/vssehdave/Logbook/issues"
+
+[project.scripts]
+logbook = "getlogbook.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+getlogbook = ["viewer.html"]

getlogbook-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

getlogbook-0.0.1/src/getlogbook/__init__.py

@@ -0,0 +1,2 @@
+"""logbook: commit-anchored shared memory for AI-assisted repos."""
+__version__ = "0.0.1"

getlogbook-0.0.1/src/getlogbook/__main__.py

@@ -0,0 +1,11 @@
+import sys
+
+if len(sys.argv) > 1 and sys.argv[1] in ("capture", "post-commit"):
+    # hook fast path: no argparse, no CLI imports (saves ~100 ms per invocation)
+    from .hookmain import run
+
+    raise SystemExit(run(sys.argv[1:]))
+
+from .cli import main
+
+raise SystemExit(main())

getlogbook-0.0.1/src/getlogbook/capture.py

@@ -0,0 +1,372 @@
+"""Capture: hook entry point, spool, reconcile, git post-commit floor, hook installers.
+
+Design rules (from the review panels):
+  * A hook only writes a small spool file and (maybe) spawns a detached worker. No model, no network, < 100 ms.
+  * A hook never fails the agent: everything is caught, logged to errors.log, exit code 0.
+  * `reconcile()` is the one sweep: spool -> transcript slices -> drafts; crash recovery; commits with no entry.
+  * Drafts built without a model are provenance=inferred and are never injected (no 'why').
+"""
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from . import git as g
+from .entry import BODY_FIELDS, Entry, from_json, new_id
+from .store import Repo, atomic_write
+
+MARK_BEGIN, MARK_END = "# >>> logbook >>>", "# <<< logbook <<<"
+CLAUDE_EVENTS = ["SessionStart", "UserPromptSubmit", "Stop", "PreCompact", "SessionEnd"]
+
+
+def now():
+    return time.strftime("%Y-%m-%dT%H:%M:%S")
+
+
+# ---- entries made by people/agents ---------------------------------------------------------------------------
+def make_entry(repo, kind, topic, body, paths=None, provenance="agent-written", via="cli", pending=False, supersedes=()):
+    from . import tree
+    body = {k: str(v)[:2000] for k, v in body.items() if k in BODY_FIELDS and v}
+    e = Entry(id=new_id(), kind=kind, topic=topic[:200], body=body, provenance=provenance, captured_via=via,
+              supersedes=list(supersedes), created=now(),
+              display=repo.cfg().get("display", "") if repo.attribution() == "named" else "")
+    if pending:  # change entries are written before the commit exists; post-commit attaches the sha
+        e.anchor = {"paths": list(paths or [])}
+        atomic_write(repo.cdir / "pending" / f"{e.id}.json", e.to_json())
+    else:
+        e.anchor = tree.anchor_for(repo, paths=paths)
+        repo.add_private(e)
+    return e
+
+
+def post_commit(repo):
+    """Attach pending change entries to the commit that was just made. Infers nothing here (reconcile does)."""
+    from . import tree
+    n = 0
+    pdir = repo.cdir / "pending"
+    for p in sorted(pdir.glob("*.json")) if pdir.exists() else []:
+        try:
+            e = from_json(p.read_text(encoding="utf-8"))
+            e.anchor = tree.anchor_for(repo)  # paths come from the commit itself
+            repo.add_private(e)
+            p.unlink()
+            n += 1
+        except (OSError, ValueError) as ex:
+            repo.error(f"post-commit {p.name}: {ex}")
+    return n
+
+
+# ---- spool + detached worker ---------------------------------------------------------------------------------
+@contextlib.contextmanager
+def _lock(path, timeout=1.0):
+    """Tiny cross-platform lock (O_EXCL file, stale after 10 s). Yields False if it could not be taken."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    end, fd = time.time() + timeout, None
+    while time.time() < end:
+        try:
+            fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            break
+        except FileExistsError:
+            try:
+                if time.time() - path.stat().st_mtime > 10:
+                    path.unlink()
+            except OSError:
+                pass
+            time.sleep(0.02)
+    try:
+        yield fd is not None
+    finally:
+        if fd is not None:
+            os.close(fd)
+            try:
+                path.unlink()
+            except OSError:
+                pass
+
+
+def spawn_detached(args, cwd):
+    if os.environ.get("LOGBOOK_NO_SPAWN"):  # tests
+        return
+    kw = dict(stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, close_fds=True, cwd=str(cwd))
+    if os.name == "nt":
+        flags = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW
+        try:  # escape the agent's job object if allowed, otherwise fall back
+            subprocess.Popen(args, creationflags=flags | 0x01000000, **kw)  # CREATE_BREAKAWAY_FROM_JOB
+        except OSError:
+            subprocess.Popen(args, creationflags=flags, **kw)
+    else:
+        subprocess.Popen(args, start_new_session=True, **kw)
+
+
+def spool_event(repo, event, agent, payload):
+    head, branch, paths, _ = g.state(repo.root)  # one subprocess
+    item = {"event": event, "agent": agent, "t": time.time(), "head": head or "", "branch": branch,
+            "paths": paths[:40], "session": str(payload.get("session_id", ""))[:80], "transcript": str(payload.get("transcript_path", "")),
+            "prompt": str(payload.get("prompt", ""))[:2000], "last": str(payload.get("last_assistant_message", ""))[:4000]}
+    atomic_write(repo.cdir / "spool" / f"{int(time.time() * 1000):013d}-{os.urandom(3).hex()}.json", json.dumps(item))
+    if item["session"] and item["transcript"]:  # copy the new bytes now: agents prune old transcripts
+        checkpoint(repo, item["session"], item["transcript"])
+
+
+def handle_hook(event, agent, raw):
+    """Entry point for `logbook capture`. Returns text for stdout (may be ''). Never raises."""
+    repo = None
+    try:
+        payload = json.loads(raw) if raw and raw.strip() else {}
+        if not isinstance(payload, dict):
+            payload = {}
+        repo = Repo(payload.get("cwd") or ".")
+        cfg = repo.cfg()
+        if not cfg.get("user"):
+            return ""
+        out = ""
+        if event in ("SessionStart", "UserPromptSubmit", "PreToolUse"):
+            from . import recall  # only the prompt-time hooks need retrieval; Stop/SessionEnd stay lean
+            files = []
+            ti = payload.get("tool_input")
+            if event == "PreToolUse" and isinstance(ti, dict) and ti.get("file_path"):
+                try:
+                    files = [Path(ti["file_path"]).resolve().relative_to(repo.root.resolve()).as_posix()]
+                except (ValueError, OSError):
+                    files = []
+            out = recall.hook_json(event, recall.digest(repo, event, payload.get("prompt", ""), files, str(payload.get("session_id", ""))))
+        if event in ("Stop", "PreCompact", "SessionEnd"):  # prompt-time hooks stay read-only and fast
+            spool_event(repo, event, agent, payload)
+        if event in ("SessionStart", "PreCompact", "SessionEnd"):
+            spawn_detached([cfg.get("interpreter") or sys.executable, "-m", "getlogbook", "reconcile", "--quiet"], repo.root)
+        return out
+    except Exception as ex:  # a hook must never break the agent
+        try:
+            (repo.error if repo else (lambda m: None))(f"capture {event}: {ex!r}")
+        except Exception:
+            pass
+        return ""
+
+
+# ---- reconcile -----------------------------------------------------------------------------------------------
+def _msg(obj):
+    m = obj.get("message") if isinstance(obj.get("message"), dict) else obj
+    role = m.get("role") or obj.get("type") or ""
+    c = m.get("content")
+    if isinstance(c, list):
+        c = " ".join(p.get("text", "") for p in c if isinstance(p, dict) and p.get("type") == "text")
+    return role, c.strip() if isinstance(c, str) else ""
+
+
+def _sid(sid):
+    return "".join(c for c in sid if c.isalnum() or c in "-_")[:80] or "nosession"
+
+
+def _load(d):
+    try:
+        st = json.loads((d / "state.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        st = {}
+    st.setdefault("offset", 0)
+    st.setdefault("paths", [])
+    st.setdefault("summarized", 0)
+    return st
+
+
+def _copy_slice(d, st, transcript):
+    if transcript and Path(transcript).is_file():
+        size = Path(transcript).stat().st_size
+        if size < st["offset"]:
+            st["offset"] = 0
+        if size > st["offset"]:
+            with open(transcript, "rb") as f:
+                f.seek(st["offset"])
+                data = f.read()
+            d.mkdir(parents=True, exist_ok=True)
+            (d / f"slice-{st['offset']:012d}.jsonl").write_bytes(data)
+            st["offset"] = size
+
+
+def checkpoint(repo, sid, transcript, paths=(), meta=None):
+    """Copy the transcript bytes added since the last checkpoint. Cheap; safe to call from a hook."""
+    d = repo.cdir / "sessions" / _sid(sid)
+    with _lock(d / ".lock") as got:
+        if not got:
+            return None
+        st = _load(d)
+        _copy_slice(d, st, transcript)
+        st["paths"] = sorted(set(st["paths"]) | set(paths))[:200]
+        st["last"] = time.time()
+        st.update(meta or {})
+        atomic_write(d / "state.json", json.dumps(st))
+        return d, st
+
+
+def _finalize(repo, sid, d, st, agent, head, branch):
+    from . import tree
+    texts = []
+    for sl in sorted(d.glob("slice-*.jsonl")):
+        if int(sl.stem.split("-")[1]) < st["summarized"]:
+            continue
+        for line in sl.read_text(encoding="utf-8", errors="replace").splitlines():
+            try:
+                role, text = _msg(json.loads(line))
+            except ValueError:
+                continue
+            if text:
+                texts.append((role, text))
+    assistant = [t for r, t in texts if r == "assistant"]
+    user = [t for r, t in texts if r == "user"]
+    if not assistant:
+        return None
+    st["summarized"] = st["offset"]
+    first_line = lambda s, n: (s.splitlines() or [""])[0][:n]
+    e = Entry(id=new_id(), kind="finding", topic=(first_line(user[0], 80) if user else f"session {sid[:8]}"),
+              body={"summary": assistant[-1][:300], "what": "\n".join("- " + first_line(a, 120) for a in assistant[:5])},
+              provenance="inferred", captured_via=agent or "agent", created=now())
+    a = tree.anchor_for(repo, sha=head or None, paths=st["paths"][:40], dirty=bool(st["paths"]))
+    a["branch"] = branch or a["branch"]
+    e.anchor = a
+    repo.add_private(e)
+    return e
+
+
+def reconcile(repo, quiet=True):
+    """Process spooled hook events, recover crashed sessions, and record commits that have no entry."""
+    done = {"drafts": 0, "floor": 0, "pending": 0}
+    sessions = {}
+    spool = repo.cdir / "spool"
+    for p in sorted(spool.glob("*.json")) if spool.exists() else []:
+        try:
+            it = json.loads(p.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            p.unlink(missing_ok=True)
+            continue
+        sid = it.get("session") or "nosession"
+        s = sessions.setdefault(sid, {"agent": it.get("agent", ""), "transcript": "", "final": False, "head": "", "branch": "", "paths": set()})
+        s["transcript"] = it.get("transcript") or s["transcript"]
+        s["head"], s["branch"] = it.get("head") or s["head"], it.get("branch") or s["branch"]
+        s["paths"] |= set(it.get("paths", []))
+        s["final"] |= it.get("event") in ("PreCompact", "SessionEnd")
+        p.unlink(missing_ok=True)
+    for sid, s in sessions.items():
+        safe = _sid(sid)
+        got = checkpoint(repo, safe, s["transcript"], s["paths"], {"agent": s["agent"], "head": s["head"], "branch": s["branch"]})
+        if got and s["final"]:
+            d = got[0]
+            with _lock(d / ".lock") as ok:
+                st = _load(d)
+                if ok and _finalize(repo, safe, d, st, s["agent"], s["head"], s["branch"]):
+                    done["drafts"] += 1
+                    st["paths"] = []
+                if ok:
+                    atomic_write(d / "state.json", json.dumps(st))
+    # crash recovery: sessions with unsummarised bytes and no activity for 30 minutes
+    sdir = repo.cdir / "sessions"
+    for d in sdir.iterdir() if sdir.exists() else []:
+        if not d.is_dir():
+            continue
+        with _lock(d / ".lock") as ok:
+            st = _load(d)
+            if ok and st["offset"] > st["summarized"] and time.time() - st.get("last", 0) > 1800:
+                if _finalize(repo, d.name, d, st, st.get("agent", ""), st.get("head", ""), st.get("branch", "")):
+                    done["drafts"] += 1
+                atomic_write(d / "state.json", json.dumps(st))
+    done["pending"] = post_commit(repo) if (repo.cdir / "pending").exists() else 0
+    done["floor"] = _commit_floor(repo)
+    return done
+
+
+def _commit_floor(repo):
+    """Inferred entries for my own commits since init that have no entry yet (covers web-UI/hook-less commits)."""
+    from . import tree
+    base = repo.cfg().get("floor_base")
+    if not base or not g.commit_exists(repo.root, base):
+        return 0
+    email = g.config_get(repo.root, "user.email")
+    rc, out, _ = g.try_run(["log", "--first-parent", "-n50", f"--author={email}", "--format=%H", f"{base}..HEAD"], repo.root)
+    covered = {l.entry.anchor.get("sha") for l in repo.all_entries()}
+    n = 0
+    for sha in (out.split() if rc == 0 else []):
+        if sha in covered:
+            continue
+        info = g.commit_info(repo.root, sha) or {}
+        paths = g.changed_paths(repo.root, sha)
+        body = g.try_run(["show", "-s", "--format=%b", sha], repo.root)[1].strip()
+        layers = sorted({l for l in (tree.layer_of(p) for p in paths) if l})
+        e = Entry(id=new_id(), kind="change", topic=info.get("subject", "")[:200],
+                  body={"summary": info.get("subject", ""), "what": (body + f"\nfiles: {len(paths)}" +
+                                                                     (f" ({', '.join(layers)})" if layers else "")).strip()},
+                  provenance="inferred", captured_via="reconcile", created=now())
+        e.anchor = tree.anchor_for(repo, sha=sha, paths=paths)
+        repo.add_private(e)
+        n += 1
+    return n
+
+
+# ---- installers ---------------------------------------------------------------------------------------------
+def _py(repo):
+    return (repo.cfg().get("interpreter") or sys.executable).replace("\\", "/")
+
+
+def install_git_hook(repo):
+    hooks = Path(g.run(["rev-parse", "--path-format=absolute", "--git-path", "hooks"], repo.root).strip())
+    hooks.mkdir(parents=True, exist_ok=True)
+    f = hooks / "post-commit"
+    block = f'{MARK_BEGIN}\n"{_py(repo)}" -m getlogbook post-commit >/dev/null 2>&1 || true\n{MARK_END}\n'
+    text = f.read_text(encoding="utf-8") if f.exists() else "#!/bin/sh\n"
+    if MARK_BEGIN not in text:  # chain, never overwrite
+        f.write_text(text.rstrip("\n") + "\n" + block, encoding="utf-8", newline="\n")
+    try:
+        f.chmod(f.stat().st_mode | 0o111)
+    except OSError:
+        pass
+    c = repo.cfg()
+    c.setdefault("floor_base", g.head_sha(repo.root) or "")
+    repo.save_cfg(c)
+    return f
+
+
+def uninstall_git_hook(repo):
+    hooks = Path(g.run(["rev-parse", "--path-format=absolute", "--git-path", "hooks"], repo.root).strip())
+    f = hooks / "post-commit"
+    if f.exists() and MARK_BEGIN in f.read_text(encoding="utf-8"):
+        t = f.read_text(encoding="utf-8")
+        a, _, rest = t.partition(MARK_BEGIN)
+        _, _, b = rest.partition(MARK_END)
+        f.write_text((a + b.lstrip("\n")).rstrip("\n") + "\n", encoding="utf-8", newline="\n")
+    return f
+
+
+def claude_snippet(repo, pretool=False):
+    py = _py(repo)
+    mk = lambda ev: [{"hooks": [{"type": "command", "command": f'"{py}" -m getlogbook capture --event {ev} --agent claude-code'}]}]
+    hooks = {ev: mk(ev) for ev in CLAUDE_EVENTS}
+    if pretool:
+        hooks["PreToolUse"] = [{"matcher": "Edit|Write|MultiEdit", **mk("PreToolUse")[0]}]
+    return {"hooks": hooks}
+
+
+def install_claude(repo, path=None, pretool=False, write=False, remove=False):
+    path = Path(path or repo.root / ".claude" / "settings.local.json")  # local: it holds a machine-specific interpreter path
+    try:
+        cur = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+    except ValueError:
+        raise SystemExit(f"logbook: {path} is not valid JSON; refusing to touch it")
+    hooks = cur.setdefault("hooks", {})
+    snippet = claude_snippet(repo, pretool)["hooks"]
+    for ev, entries in list(hooks.items()):  # always drop our previous entries so install is idempotent
+        keep = [e for e in entries if "getlogbook capture" not in json.dumps(e)]
+        if keep:
+            hooks[ev] = keep
+        else:
+            del hooks[ev]
+    if not remove:
+        for ev, entries in snippet.items():
+            hooks.setdefault(ev, []).extend(entries)
+    if not hooks:
+        cur.pop("hooks")
+    if write:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write(path, json.dumps(cur, indent=2))
+    return path, cur