collossal 0.1.0__py3-none-any.whl

collossal-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.3
+Name: collossal
+Version: 0.1.0
+Summary: Collossal CLI: connects your coding agent to your team's sessions, memory and rooms.
+Author: Vipul
+Author-email: Vipul <vilulgupta2802@gmail.com>
+Requires-Dist: mcp[cli]>=2.2.0
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: websockets>=13.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# Collossal MCP
+
+Shared memory for coding agents. Runs on a developer's machine and talks to the
+Collossal API over HTTPS — it holds an API key and never database credentials.
+
+## Setup
+
+One command per machine — the dashboard's Setup page shows it with your
+addresses filled in:
+
+```bash
+curl -fsSL https://<your-collossal>/install.sh | sh -s -- --api-url https://<your-collossal>/api/v1
+```
+
+That installs the `collossal` command (with uv, which brings its own Python) and
+runs `collossal install`, which:
+
+1. **Signs the machine in through the browser.** It shows a code and opens the
+   dashboard; you check the code and approve. The machine receives an API key
+   of your own — nothing to copy — saved to `~/.collossal/config.json` (0600).
+2. **Sets up Claude Code for every project:** the hooks below go into
+   `~/.claude/settings.json` (your other settings are kept, and the original is
+   backed up once), and the MCP server is registered with
+   `claude mcp add --scope user`.
+3. **Uploads your past sessions** from `~/.claude/projects` — every one,
+   whatever it ran in — with their real timestamps, titles and redaction, so
+   your history appears on the dashboard, not just what happens from now on.
+
+From then on every Claude Code session on the machine streams to your team's
+Sessions tab as it happens, and every teammate can open it. Nothing has to be
+connected first: a session is labelled by the repository it ran in (or, begun
+in a folder holding several, the one it works in most), or by its folder. A
+repository connected to a project additionally gets memory — decisions
+anchored to its files.
+
+Each person chooses which of their sessions the team sees, under **Sessions →
+Configure**: all of them (the default), or only those in the repositories and
+folders they pick. The choice applies at once to past sessions as well as new
+ones. A session outside it is still recorded, and its owner still sees it under
+My sessions — nobody else does: not teammates, not workspace admins, not an
+agent's `team_sessions` or a handoff. Setting it before running the installer
+keeps the upload of past sessions within it from the start.
+
+Until the CLI is published, install it from this checkout instead:
+
+```bash
+uv tool install --editable /path/to/main-mcp && collossal install --api-url http://localhost:3000/api/v1
+```
+
+| Command | Does |
+|---|---|
+| `collossal install` | All of the above; safe to run again |
+| `collossal import` | Upload past sessions again — e.g. after connecting another repo |
+| `collossal status` | Who this machine is signed in as, and what is set up |
+| `collossal doctor` | The same, plus what is wrong and how to fix it |
+| `collossal login` | Sign in again without changing anything else |
+| `collossal uninstall` | Remove the hooks, the MCP server and the sign-in |
+
+`COLLOSSAL_API_KEY` and `COLLOSSAL_API_URL` still work and take precedence over
+the saved sign-in — for CI, or to pin one project to a different workspace.
+
+## Tools
+
+**`memory_write`** — records a decision and anchors it to the files it governs.
+
+**`memory_search`** — natural-language search across the project. Results can
+come from a *different repository* than the one being edited; that is the point.
+
+**`memory_for_files`** — decisions attached to specific files. Needs no query,
+so it surfaces context an agent would not have known to search for. Anchors
+belong to a repo, so this looks within the current one; `memory_search` is the
+cross-repo path.
+
+**`team_sessions`** — teammates' recent agent sessions, to inherit from. Lists
+the whole workspace's, whatever repository or folder they ran in; excludes your
+own and any a teammate keeps private, and omits sessions that recorded nothing
+— an empty run is noise in a list an agent acts on.
+
+**`session_handoff`** — takes a teammate's session over: where the work is, the
+end of their conversation, and the decisions already anchored to the files
+involved, written for the receiving agent to read on its first turn. Accepts a
+session id or a pasted dashboard link. No agent will adopt a foreign session id,
+so what transfers is the context, not the process.
+
+The agent supplies the claim, rationale, and files. Everything identifying —
+repo, branch, commit, project — is read from the git checkout, because asking an
+agent for a project id invites it to guess.
+
+File paths are normalised to repo-relative before storage: an absolute path
+would anchor the memory to one machine's directory layout and never match for a
+teammate.
+
+A decision replaced by a newer one is still returned, labelled `[SUPERSEDED]`
+with the claim that replaced it, stated *before* its rationale — an agent must
+not be able to read stale reasoning without first seeing that it no longer
+holds.
+
+## Automatic capture
+
+Two hooks, because the transcript on disk already holds every tool call and
+message — there is nothing to gain from hooking each tool.
+
+| Hook | Does |
+|---|---|
+| `SessionStart` | Injects this project's decisions into the new session, and starts streaming it to the dashboard |
+| `Stop` | Captures what the turn taught, and delivers any instruction a teammate sent |
+| `SessionEnd` | Ships the rest of the transcript, and uploads the whole session if it was never streamed — one that began before Collossal was installed |
+
+`collossal install` puts them in `~/.claude/settings.json` for every project. To
+set them up by hand instead, merge `hooks.example.json` there, or into one
+project's `.claude/settings.json` to scope them to that repo — but not both, or
+that project's sessions are streamed twice.
+
+### How a session becomes memory
+
+The worker reads from the last cursor, then looks for four mechanically
+detectable moments — nothing here calls a model:
+
+- **`FAILURE_FIX`** — a command failed, edits followed, the same command passed.
+  Matched on command *shape* rather than exact text, because an agent re-runs
+  the same tool against a different file rather than retyping the failure.
+- **`REVERSAL`** — one file rewritten six or more times, with the reasoning
+  stated nearest the final edit. Fewer than six is ordinary iteration.
+- **`USER_CORRECTION`** — the user pushed back right after an assistant action.
+- **`STATED_CONSTRAINT`** — the user stated a rule.
+
+A session reaching none of these is dropped having cost one file read. Measured
+across 78 real transcripts (296 MB), that gate discards 39% for free and the
+rest yield about 6 windows each.
+
+Windows are stored separately from decisions, so the store of durable claims
+never fills with unprocessed transcript fragments. A stub promotes `FAILURE_FIX`
+windows to decisions at confidence 0.4; injection ignores anything below 0.5, so
+raw machine guesses never reach an agent's context before distillation exists.
+
+### Redaction
+
+Credentials are stripped in the worker, immediately before the push — not on
+the server, because scanning there would still mean the secret crossed the
+network and landed in a request log.
+
+Three layers: known vendor formats (Anthropic, OpenAI, GitHub, AWS, Slack,
+Google, Stripe, JWTs, private keys, connection strings), assignments whose
+*name* claims to hold a credential (`API_KEY=`, `SECRET=`), and a Shannon
+entropy fallback for credentials with no recognisable shape.
+
+The trade is deliberately asymmetric: a false positive costs a slightly less
+readable memory, a false negative puts a live credential in a database forever.
+
+Measured against 564 fields from real transcripts: **zero false positives**,
+and zero secrets missed across a suite of 15 credential formats. Absolute paths
+are rewritten repo-relative in the same pass, so memory does not carry one
+machine's directory layout to everyone else.
+
+### Safety properties
+
+The hook always exits 0 and swallows every error to `~/.collossal/hook.log`. It
+cannot fail a session, and with the API unreachable a session starts normally
+with no memory rather than an error.
+
+## Live sessions
+
+A workspace admin can watch a session as it happens and step into it.
+
+| Piece | Does |
+|---|---|
+| `tailer.py` | Spawned at SessionStart, detached. Follows the transcript, redacts, and pushes render-ready events plus snapshots of uncommitted work — `git diff`, and files not yet added — which a session's Changes tab and the workspace owner's Code diff view show. An empty snapshot means the tree is clean again. |
+| `Stop` hook | Collects instructions queued from the dashboard and hands them to the agent as its next input. |
+
+Two properties worth knowing.
+
+**It tails, it does not replay.** The tailer starts from the current end of the
+transcript. A hook firing on a resumed session would otherwise push its entire
+history — megabytes — as though it had all just happened.
+
+**Instructions arrive at a turn boundary, not instantly.** There is no way to
+interrupt a turn already running, so anything sent is queued and delivered the
+moment the agent would otherwise have stopped. Delivered exactly once: a
+repeated instruction would have the agent redo work.
+
+Everything streamed is redacted on the machine first, and absolute paths are
+rewritten repo-relative — a watcher sees the repository, not someone's home
+directory. Events are kept for `SESSION_RETENTION_DAYS` (90 days by default),
+so a session can be read back after it ends; the durable record of a session
+remains the decisions distilled from it.
+
+Sending an instruction also writes a `NOTICE` into the stream the watched
+person can see. Being observed and redirected with no indication of it is not
+something to ship.
+
+## Layout
+
+```
+config.py       env, validated once at startup
+git_context.py  repo/branch/commit discovery and path normalisation
+client.py       Collossal API client
+format.py       renders decisions for a context window
+server.py       MCPServer and the tools
+capture/
+  hook.py       lifecycle hook: injection, and spawning the worker
+  worker.py     detached — reads transcript, gates, ships
+  transcript.py streaming JSONL reader
+  windows.py    the four detectors
+  redact.py     strips credentials before anything leaves the machine
+  ship.py       API calls for capture and injection
+```

collossal-0.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+main_mcp/__init__.py,sha256=pOC5-Hzx2P87T0n2QIndADb99cir8yvZqRa-fcRZLks,339
+main_mcp/agents.py,sha256=7MLdCUNcLkYVSQ9OqiZZIFxQOB9LcyHnrDd8HVsQhmc,9602
+main_mcp/capture/__init__.py,sha256=G6vFZGqD2uV8Yn0G7wxQsf8n4d5OXYZbZfLknN0jTW4,78
+main_mcp/capture/checkouts.py,sha256=-no8vd-8FmPcuQRuo-sVREdZ_esbTfSBKeCfVqsVfGM,3134
+main_mcp/capture/history.py,sha256=99IYY7VjRT8D78L-sDb7TK8PeEwtDmkurp1TRfEdaQU,12146
+main_mcp/capture/hook.py,sha256=1Pn9x0TdTzdclnU6Tkg2iqiWFKxXrGB2eTV72TKw-Vk,13421
+main_mcp/capture/redact.py,sha256=XV3gdnj7ofdNaiNH8LZeRlJ7j-yO867O1U10J8zPsaM,7934
+main_mcp/capture/shell_edits.py,sha256=rMBJq9aKXa-8BUpwQ-YO4ik57kUTZF3PD3nkc9JqiPM,10407
+main_mcp/capture/ship.py,sha256=zzF8tNMlGy7EJ1G4P7T5klLre8L1Piu4z7xi3svabGo,4731
+main_mcp/capture/tailer.py,sha256=LknoK284x-yUdEu-aiHpqELpO4T-nTi3wCC9odrXvRI,16547
+main_mcp/capture/transcript.py,sha256=csDDO_DCLqbH5unpuHRDd375S0kjDlZ5jnhK78JZffQ,9528
+main_mcp/capture/turn_worker.py,sha256=jCIL-4byWqxft9EamPwg6llMMaNe3N0My0fDw_l51fI,4488
+main_mcp/capture/turns.py,sha256=tb3k-0T6-uxeAzg4rP8fhL2RUrcIToHOtW5KTnfJ5_g,4931
+main_mcp/capture/windows.py,sha256=mi30F6LeNyMM3LylPyKFz7Btu5hsG3sOv1enPO2NuH0,19666
+main_mcp/capture/worker.py,sha256=Tp6CZYT63HUuC3DKC9JwwtvPSe2MDr4hWMc_R98x51Q,3937
+main_mcp/cli.py,sha256=KorhhKiOJAGzwqgLVxBs8-RRMqxo3rSi99PdNJoQq5U,18603
+main_mcp/client.py,sha256=YNTZPqo5ChDX4_XEkRO8yYn1XjXQWNx5kr88FvmQtdI,9563
+main_mcp/config.py,sha256=p9QM9WuX9zfSo2hDhnMOkXWjqq6H7_DK2T6-RcdFV1c,3571
+main_mcp/format.py,sha256=CE2Lh5r_Lfae3Sd7_VAjCwa5Q2avJsJMg3yGeBj322s,2107
+main_mcp/git_context.py,sha256=Jd2Tz43DbXL5-a2bhva63ROxVOMKhviW2Me5LvLvhvE,3912
+main_mcp/room.py,sha256=as_uB6GvO83SeiwANRs24VqvriAM8bHiKneIhBG22DA,28443
+main_mcp/server.py,sha256=6ebPVcKcLq2MkEBiHWcS2J1IF6-Be--Z5w1TjMKxf9E,10522
+collossal-0.1.0.dist-info/WHEEL,sha256=WKk67IZPzp9uSkBO-iWoZzrqp9-AwH7FE9EB8EoJbf4,81
+collossal-0.1.0.dist-info/entry_points.txt,sha256=vRI9UufT43S63JrxaVDh0HequVRVgzWCyrs5W4A42yg,130
+collossal-0.1.0.dist-info/METADATA,sha256=1xkFgRT1yhb4L0lbf_o5sOamGEwfNqbuFi9N46BaHpo,10528
+collossal-0.1.0.dist-info/RECORD,,

collossal-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.12
+Root-Is-Purelib: true
+Tag: py3-none-any

collossal-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+collossal = main_mcp.cli:main
+collossal-hook = main_mcp.capture.hook:main
+collossal-mcp = main_mcp.server:main
+

main_mcp/__init__.py

@@ -0,0 +1,16 @@
+"""Collossal MCP server."""
+
+
+def main() -> None:
+    """Entry point.
+
+    The import is deferred so that `python -m main_mcp.server` does not load the
+    server module twice — which would run its startup config load and client
+    construction a second time.
+    """
+    from .server import main as run
+
+    run()
+
+
+__all__ = ["main"]

main_mcp/agents.py

@@ -0,0 +1,278 @@
+"""Wiring Collossal into the coding agents on this machine.
+
+For Claude Code that is two things, both at user scope so they apply to every
+project without anything being committed to one:
+
+* the lifecycle hooks, in ``~/.claude/settings.json`` — they put the project's
+  memory in front of each new session, stream it to the dashboard, deliver
+  teammates' instructions between turns, and complete its history at the end;
+* the MCP server, registered with ``claude mcp add --scope user``, so every
+  session has the memory and handoff tools.
+
+Both are recognised by the command they run, so installing again replaces them
+rather than stacking a second copy, and uninstalling removes exactly them and
+nothing the person put there themselves.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+HOOK_EVENTS = ("UserPromptSubmit", "SessionStart", "Stop", "SessionEnd")
+#: How long Claude Code may wait for each. `UserPromptSubmit` holds up the
+#: person's prompt until it returns, so it gets a far shorter leash than the
+#: rest — the hook's own budget is tighter still, and this is the backstop for
+#: the case where it hangs somewhere the budget does not cover.
+HOOK_TIMEOUTS = {"UserPromptSubmit": 5}
+DEFAULT_HOOK_TIMEOUT = 10
+#: How a hook is known to be Collossal's: it runs this command.
+HOOK_MARKER = "collossal-hook"
+MCP_NAME = "collossal"
+#: The same two, from when the product was spelled with one "l". Installing
+#: removes them, so a machine set up then does not run both.
+LEGACY_HOOK_MARKER = "colossal-hook"
+LEGACY_MCP_NAME = "colossal"
+
+
+class SettingsError(RuntimeError):
+    """A settings file that cannot be safely rewritten."""
+
+
+def claude_dir() -> Path:
+    """Claude Code's own directory, which ``CLAUDE_CONFIG_DIR`` moves."""
+    override = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+    return Path(override).expanduser() if override else Path.home() / ".claude"
+
+
+def settings_path() -> Path:
+    return claude_dir() / "settings.json"
+
+
+def claude_installed() -> bool:
+    return claude_dir().is_dir() or shutil.which("claude") is not None
+
+
+def executable(name: str) -> Path | None:
+    """One of this package's own commands, by absolute path.
+
+    Taken from beside the interpreter running this — where an installed tool
+    keeps its scripts — so a hook keeps working whatever PATH the agent happens
+    to be launched with.
+    """
+    beside = Path(sys.executable).parent / name
+    if beside.exists():
+        return beside
+    found = shutil.which(name)
+    return Path(found) if found else None
+
+
+# ---------------------------------------------------------------------------
+# Hooks
+# ---------------------------------------------------------------------------
+
+
+def _read(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8") or "{}")
+    except ValueError as exc:
+        # Never overwrite what could not be read: whatever else is in it is the
+        # person's, and a rewrite from nothing would silently drop it.
+        raise SettingsError(
+            f"{path} is not valid JSON ({exc}). Fix it, then run this again."
+        ) from exc
+    if not isinstance(data, dict):
+        raise SettingsError(f"{path} does not hold a JSON object.")
+    return data
+
+
+def _write(path: Path, data: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # The first time only: the file as it was before Collossal ever touched it.
+    backup = path.with_name(f"{path.name}.collossal-backup")
+    if path.exists() and not backup.exists():
+        shutil.copy2(path, backup)
+    tmp = path.with_name(f".{path.name}.tmp")
+    tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _ours(item: Any) -> bool:
+    if not isinstance(item, dict):
+        return False
+    command = str(item.get("command", ""))
+    return HOOK_MARKER in command or LEGACY_HOOK_MARKER in command
+
+
+def _without_ours(groups: Any) -> list[Any]:
+    """An event's hook groups, minus Collossal's — and minus any group that
+    held nothing else. Everything else is kept exactly as it was."""
+    if not isinstance(groups, list):
+        return []
+    kept: list[Any] = []
+    for group in groups:
+        items = group.get("hooks") if isinstance(group, dict) else None
+        if not isinstance(items, list):
+            kept.append(group)
+            continue
+        rest = [item for item in items if not _ours(item)]
+        if len(rest) == len(items):
+            kept.append(group)
+        elif rest:
+            kept.append({**group, "hooks": rest})
+    return kept
+
+
+def hook_command() -> str | None:
+    hook = executable("collossal-hook")
+    return shlex.quote(str(hook)) if hook else None
+
+
+def install_hooks(command: str) -> Path:
+    path = settings_path()
+    settings = _read(path)
+    hooks = settings.get("hooks") if isinstance(settings.get("hooks"), dict) else {}
+    for event in HOOK_EVENTS:
+        groups = _without_ours(hooks.get(event))
+        groups.append(
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": command,
+                        "timeout": HOOK_TIMEOUTS.get(event, DEFAULT_HOOK_TIMEOUT),
+                    }
+                ]
+            }
+        )
+        hooks[event] = groups
+    settings["hooks"] = hooks
+    _write(path, settings)
+    return path
+
+
+def remove_hooks() -> bool:
+    path = settings_path()
+    if not path.exists():
+        return False
+    settings = _read(path)
+    hooks = settings.get("hooks")
+    if not isinstance(hooks, dict):
+        return False
+
+    changed = False
+    for event in list(hooks):
+        rest = _without_ours(hooks[event])
+        if rest != hooks[event]:
+            changed = True
+            if rest:
+                hooks[event] = rest
+            else:
+                del hooks[event]
+    if not changed:
+        return False
+    if not hooks:
+        del settings["hooks"]
+    _write(path, settings)
+    return True
+
+
+def installed_hook() -> str | None:
+    """The command Collossal's hooks run, if all of them are in place."""
+    try:
+        hooks = _read(settings_path()).get("hooks")
+    except SettingsError:
+        return None
+    if not isinstance(hooks, dict):
+        return None
+    commands = []
+    for event in HOOK_EVENTS:
+        groups = hooks.get(event) if isinstance(hooks.get(event), list) else []
+        found = [
+            item["command"]
+            for group in groups
+            if isinstance(group, dict) and isinstance(group.get("hooks"), list)
+            for item in group["hooks"]
+            if _ours(item)
+        ]
+        if not found:
+            return None
+        commands.append(found[0])
+    return commands[0]
+
+
+def duplicate_hook_files(directories: list[str]) -> list[Path]:
+    """Project settings that also run Collossal's hooks.
+
+    Left over from setting a project up by hand. With the hooks installed for
+    every project, each of these would run a second time — two streams for one
+    session.
+    """
+    found: list[Path] = []
+    for directory in sorted(set(directories)):
+        for name in ("settings.json", "settings.local.json"):
+            path = Path(directory) / ".claude" / name
+            try:
+                text = path.read_text(encoding="utf-8")
+                if HOOK_MARKER in text or LEGACY_HOOK_MARKER in text:
+                    found.append(path)
+            except OSError:
+                continue
+    return found
+
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+
+
+def _claude(*args: str) -> subprocess.CompletedProcess[str] | None:
+    claude = shutil.which("claude")
+    if not claude:
+        return None
+    try:
+        return subprocess.run(
+            [claude, "mcp", *args], capture_output=True, text=True, timeout=60
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def register_mcp(server: Path) -> tuple[bool, str]:
+    # Replaced rather than added beside: `add` refuses a name already taken,
+    # and an older registration may point at a command that no longer exists.
+    _claude("remove", "--scope", "user", MCP_NAME)
+    _claude("remove", "--scope", "user", LEGACY_MCP_NAME)
+    result = _claude("add", "--scope", "user", MCP_NAME, "--", str(server))
+    if result is None:
+        return False, "the `claude` command is not on PATH"
+    return result.returncode == 0, (result.stderr or result.stdout).strip()
+
+
+def unregister_mcp() -> bool:
+    result = _claude("remove", "--scope", "user", MCP_NAME)
+    return bool(result and result.returncode == 0)
+
+
+def registered_mcp() -> str | None:
+    """The command the registered server runs.
+
+    Read from Claude Code's config rather than asked of `claude mcp get`, which
+    starts the server to health-check it — too slow for a status line.
+    """
+    override = os.environ.get("CLAUDE_CONFIG_DIR", "").strip()
+    path = Path(override).expanduser() / ".claude.json" if override else Path.home() / ".claude.json"
+    try:
+        servers = json.loads(path.read_text(encoding="utf-8")).get("mcpServers") or {}
+    except (OSError, ValueError, AttributeError):
+        return None
+    server = servers.get(MCP_NAME) if isinstance(servers, dict) else None
+    return server.get("command") if isinstance(server, dict) else None

main_mcp/capture/__init__.py

@@ -0,0 +1 @@
+"""Automatic capture: lifecycle hooks, transcript windowing, and shipping."""

main_mcp/capture/checkouts.py

@@ -0,0 +1,83 @@
+"""Which repository a session is working in, judged by what it touches.
+
+For a session begun in a folder that is not a checkout itself — a directory
+holding several repositories side by side, which is how many people open their
+agent. Such a session has no repository by where it began, but almost always
+one by what it does: the files it reads and edits, and where its commands run.
+
+Shared by the live stream, which keeps a running tally as events arrive, and
+the history import, which tallies a finished transcript in one go.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from .transcript import Event
+
+
+def checkout_of(path: Path, cache: dict[Path, Path | None]) -> Path | None:
+    """The git checkout a path lies in.
+
+    Found by looking for `.git` rather than by asking git: a session can touch
+    hundreds of paths, and a subprocess apiece would make that crawl. Every
+    directory passed on the way up is remembered, so most lookups are one
+    dictionary hit.
+    """
+    passed: list[Path] = []
+    found: Path | None = None
+    for directory in (path, *path.parents):
+        if directory in cache:
+            found = cache[directory]
+            break
+        passed.append(directory)
+        # A directory for a clone; a file for a worktree or a submodule.
+        if (directory / ".git").exists():
+            found = directory
+            break
+    for directory in passed:
+        cache[directory] = found
+    return found
+
+
+class Tally:
+    """A running count of where a session's tool calls have landed.
+
+    An edit says more about what a session is for than a read does, so it
+    counts three times over; ties go to whichever was touched first.
+    """
+
+    def __init__(self, base: Path | None) -> None:
+        #: Where relative paths are resolved from when an event has no cwd.
+        self._base = base
+        self._cache: dict[Path, Path | None] = {}
+        self._weight: dict[Path, int] = {}
+        self._first: dict[Path, int] = {}
+        self._seen = 0
+
+    def add(self, events: Iterable[Event]) -> None:
+        for e in events:
+            self._seen += 1
+            if e.kind != "tool_use":
+                continue
+            edited = set(e.edited_paths)
+            touched = [(p, 3 if p in edited else 1) for p in [e.file_path, *edited] if p]
+            if e.cwd:
+                touched.append((e.cwd, 1))
+            for raw, points in touched:
+                path = Path(raw)
+                if not path.is_absolute():
+                    where = Path(e.cwd) if e.cwd else self._base
+                    if where is None:
+                        continue
+                    path = where / path
+                root = checkout_of(path, self._cache)
+                if root is None:
+                    continue
+                self._weight[root] = self._weight.get(root, 0) + points
+                self._first.setdefault(root, self._seen)
+
+    def ranked(self) -> list[Path]:
+        """Checkouts touched so far, most-worked first."""
+        return sorted(self._weight, key=lambda root: (-self._weight[root], self._first[root]))