spexcode 0.6.1 → 0.6.2

package/README.md

@@ -18,211 +18,159 @@
 
 </div>
 
-Spec-driven development with AI agents in the loop. SpexCode keeps a versioned tree of specs inside
+Spec-driven orchestration for your coding agents. SpexCode keeps a versioned tree of specs inside
 your git repo, links every spec to the code it governs, and runs a session manager that dispatches
 coding agents into isolated worktrees. You review and merge; the tool keeps intent and
 implementation from drifting apart.
 
-[![Watch: this repo's spec tree grow from its git history](docs/spec-tree-poster.jpg)](https://spexcode.net/assets/spec-tree-growth.mp4)
-
-<sub>▶ This repo's own spec tree, replayed from its git history — 160 spec nodes growing over three weeks. Click for the [full video](https://spexcode.net/assets/spec-tree-growth.mp4).</sub>
-
 English | [中文](./docs/README.zh-CN.md) · Docs: [spexcode.net](https://spexcode.net) · License: MIT
 
-Quick links: [the model](#the-model) · [quick start](#quick-start) ·
-[agents](#working-with-agents) · [eval](#measuring-behavior-eval) · [config](#configuration)
+| Feature | Description |
+|---|---|
+| **Computable spec–code drift** | Every spec pins the file it governs, down to the function. Whether code moved without its spec is computed from commits and line ranges, the same way on every machine: advisory for the file, blocking when an anchored function changes. |
+| **Session & worktree management** | Each task runs in its own worktree and branch; independent tasks run in parallel. Sessions form a hierarchy: a session can dispatch and supervise workers of its own, so a worker can have a supervisor and that supervisor another. Workers propose; you review once, at merge time. |
+| **Shareable URLs** | Spec nodes, sessions, evals, live terminals: every dashboard view has a stable address you can send to a colleague. Two people can watch the same session board. |
+| **Modular layers** | Three separable layers: the spec↔code data asset (L0), the session substrate (L1), the dashboard (L2). Take what you need; L0 and L1 are building bricks for your own software factory. |
+| **Cross-harness support** | Claude Code, Codex, OpenCode, pi, each interactive or headless. One materialized workflow contract serves them all; adding a harness is a config entry. |
 
 ## The model
 
-<div align="center"><img src="docs/sdd-tuxedo-pooh.png" alt="spec-driven development meme" width="260"></div>
-
-A spec node is a directory under `.spec/` containing a `spec.md`: frontmatter (title, status, a
-`code:` pointer to the file it governs, a `related:` list for files it references) plus a prose
-body stating what that part of the system is supposed to do, right now. Nodes nest, so the tree
-mirrors how you think about the project rather than the file layout. The body can split into two
-labelled parts. The short **raw source** states the intent; changing it takes explicit
-human approval (an agent can draft it, a human signs off). The **expanded spec** is the agent's
-detailed reading of that intent; it iterates freely but must always match the raw source.
+A spec node is a directory under `.spec/` holding a `spec.md`: frontmatter naming the one file it
+governs (`code:` — optionally pinned to specific functions with `path#symbol`) and the files it
+references (`related:`), then a prose body stating what that part of the system is supposed to do,
+right now. Nodes nest, so the tree mirrors how you think about the project rather than the file
+layout. The body can split into two labelled parts: a short **raw source** a human signs off on, and
+an **expanded spec** the agent iterates freely — as long as it keeps matching the raw source.
 
-<img src="docs/readme-node.png" alt="spec node popup">
+<img src="docs/readme-model.svg" alt="a spec node governs one file, anchored at function level; related files are referenced; git is the only database">
 
-Two rules make this workable:
+Git is the only database: a node's versions are the commits that touched its
+`spec.md`. A change is one commit that updates both the spec and the code it justifies. When code
+moves alone, the linter notices:
 
-1. **Git is the database.** There is no separate store. A node's version count is the number of
-   commits that changed its `spec.md`, its history view is `git log` on that file, and each version
-   is attributed to an agent session through a `Session:` commit trailer. This is also why a spec
-   body always describes present intent and gets rewritten in place: changelog headings inside the
-   body are banned (the linter enforces it), because git already keeps the history.
-2. **Spec and code land together.** A change is one commit that updates both the `spec.md` and the
-   code it justifies. When code moves without its spec, the linter flags it,
+<img src="docs/readme-drift-flow.svg" alt="one real drift: spec and code land together, six days of code-only commits later a rename hits the anchored function — the commit is flagged and blocked">
 
-   ```
-   drift: spec-cli/src/graph.ts is 1 commit(s) ahead of spec 'graph-lean' (v12) — may be stale
-   ```
+The check compares plain git facts: which commits came after the spec's last version, and whether
+they intersect the anchored unit's lines. It cannot judge whether the new behavior is better, only
+that the spec stopped describing it. The commit in the diagram updated seven other specs in the
+same rename and missed this one; that kind of miss is normal work, and it is what a mechanical
+check catches.
 
-   and keeps flagging until the spec catches up.
+## Software as heuristic learning
 
-## The optimization loop
+Specs, commits, and evals compose into one optimization loop. The spec is the loss function: it
+states what you want, and it is the half a human signs off on. Commits are the optimizer. **eval**,
+the measurement subsystem, scores how far live behavior currently sits from the spec — an agent runs
+each scenario against the product's real surface, the way an end user would touch it, and files the
+result with evidence (a screenshot, a recording). The score's history lives in git like everything
+else, and a bug fix is expected to bracket: a failing eval that reproduces the bug, then a passing
+one on the same scenario.
 
-Specs, commits, and evals compose into one loop. The spec is the loss function: it states what you
-want, and it's the half a human signs off on. Commits are the optimizer. **eval**, the measurement
-subsystem, scores how far live behavior currently sits from the spec, and the
-score's history lives in git like everything else.
+<div align="center"><img src="docs/readme-loop.svg" alt="the spec/code optimization loop" width="560"></div>
 
-<img src="docs/readme-loop.png" alt="the spec/code optimization loop">
-
-It also settles where the human stands day to day: nobody reads a neural net by staring at its
-weights, and between merge gates you don't have to stare at agent diffs either. Attention goes to
-the spec and the evals; the diff gets read once, at merge time.
+Nobody reads a neural net by staring at its weights, and between merge gates you don't stare at
+agent diffs either. Attention goes to the two ends — the spec and the evals; the diff gets read
+once, at merge time.
 
 ## Quick start
 
-Requires Node ≥ 22 and git. This part is plain tooling — no AI involved yet.
+Requires Node ≥ 22 and git.
 
 ```sh
 npm i -g spexcode                              # installs the `spex` command
 cd your-repo
-spex init --harness claude,codex,opencode,pi,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/, installs hooks, materializes the agent contracts
+spex init --harness claude,codex,opencode,pi,zcode,claude-headless,opencode-headless,pi-headless,codex-headless   # seeds .spec/, installs hooks, materializes the agent contracts
 ```
 
-That's the whole adoption. The example lists all the built-in harnesses — remove the ones you don't
-use: `--harness` is required, has no default, and takes any one id or comma-separated subset.
-`spex init` is additive: it works on any existing git repo and never
-overwrites your files — it creates a root `.spec/project/spec.md` and a starter `spexcode.json`,
-installs the git hooks, and writes the selected harness's managed contract, so any agent working in
-the repo discovers the workflow on its own.
+That's the whole adoption. The example lists all the built-in harnesses; remove the ones you don't
+use (`--harness` is required and takes any one id or comma-separated subset).
+`spex init` is additive: it works on any existing git repo, never overwrites your files, and does
+three things. It seeds a root `.spec/project/spec.md` plus a starter `spexcode.json`, installs the
+git hooks, and **materializes** the workflow rules into the files your agent already reads
+(`CLAUDE.md`, `AGENTS.md`): read the governing spec before the code, land spec and code in one
+commit, propose merges instead of performing them. Any agent that opens the repo discovers the
+workflow on its own.
 
-When you want the live board — the graph, sessions, evals — start the runtime:
+When you want the live board (the graph, sessions, evals), start the runtime:
 
 ```sh
-spex serve       # this project's backend — prints its URL, registers itself for your user
-spex dashboard   # once per user, any directory: the one dashboard — open the URL it prints
+spex serve       # this project's backend — prints its URL
+spex dashboard   # the machine's one gateway — every project behind one URL
 ```
 
-Run `spex serve` from each project you want online. Every backend registers itself, and the single
-`spex dashboard` finds them all — backends already running and ones you start later, in any order.
-`/projects` switches and manages projects; each project's board lives under `/p/:id/`. There is no
-per-project dashboard process and no port pairing to remember: if a port is taken, give that
-backend its own with `spex serve --port <n>`, and trust the URL each command prints.
-
-Those are installed-user commands. Contributors working from this source checkout use `npm run api`
-for the reloadable backend and `npm run web` for the Vite/HMR frontend; see
-[Contributing](#contributing).
-
-Then grow the tree:
-
-1. Edit `.spec/project/spec.md` to describe the project.
-2. Add child nodes for the parts you want governed, each with a `code:` entry pointing at an
-   existing file (`related:` for the files it touches but doesn't own).
-3. Run `spex spec lint`. Coverage warnings list the source files no spec claims yet; that list is your
-   adoption TODO.
+One `spex dashboard` per machine is enough: every project you serve shows up behind it, and its
+`/projects` page manages them from the browser.
+[Getting started](https://spexcode.net/getting-started/) walks the rest of the setup.
 
-You are not expected to hand-author all of this. The intended workflow is to have an agent do most
-of the spec writing; `spex guide spec` prints the exact file format it needs.
-[Getting started](https://spexcode.net/getting-started/) on the docs site walks the setup end to
-end.
+## How does this system work
 
-<img src="docs/readme-graph.png" alt="dashboard screenshot">
+Three stacked layers, and each is worth having without the ones above it:
 
-*SpexCode's own repo on its own board; the sessions top-left are agents building the tool.*
+<img src="docs/readme-layers.svg" alt="L0 the spec-code data asset, L1 the agent session substrate, L2 the dashboard workspace — an adoption ladder">
 
-## Working with agents
+L0 is the asset an organisation adopts and keeps: plain files in plain git, useful offline.
+([Watch this repo's own L0 grow from its git
+history](https://spexcode.net/assets/spec-tree-growth.mp4), 160 spec nodes over three weeks.)
+L1 puts agents to work on that asset: the session state machine below. L2 is the workspace you
+watch it all from, and because it is only a consumer of L1, anything the dashboard does, your
+scripts and agents can do through the same CLI.
 
-This part needs tmux and a logged-in [Claude Code](https://www.anthropic.com/claude-code) or Codex
-on the machine.
+## Working with agents (L1)
 
-```sh
-spex session new "[[settings]] make the settings page remember the last tab"
-```
-
-launches a worker session in its own worktree on branch `node/settings-…`. The prompt's first
-`[[settings]]` mention sets the branch name and board attribution; the
-worker still finds and reads the governing spec itself before touching code. It makes the change,
-rewrites the spec body to match, commits
-both (a hook stamps the `Session:` trailer), then proposes a merge and stops. Workers never merge
-themselves. The merge stays with the manager: when you fire it, the session's own agent runs the
-actual `git merge`, so conflicts land on the one who knows the work. The same dispatch is a
-button on the dashboard (the new-session box on the board); the command form is what agents
-themselves use when they delegate.
-
-You supervise from outside — on the board, or with the same commands your agent uses:
+This part needs tmux on the machine (on Windows, run inside WSL2).
 
 ```sh
-spex session watch              # stream session transitions: launched / review / done / needs-input ...
-spex session review settings    # commits ahead of trunk, merge-base diff, merge-conflict/lint gates
-spex session merge settings     # gated merge into the trunk
-spex session close settings
+spex session new "[[uploader]] retry failed chunks with backoff"
 ```
 
-Independent tasks run in parallel. Each worker is isolated in its own worktree, git serializes the
-merges, and a pre-commit guard blocks direct commits on the trunk, so everything flows through
-reviewable node branches.
+launches a worker session in its own worktree on branch `node/uploader-…`. The prompt's first
+`[[uploader]]` mention sets the branch name and board attribution; the worker finds and reads
+the governing spec before it changes code. It makes the change, rewrites the spec body to
+match, puts both in one commit, then files a merge proposal and stops:
 
-The process is enforced by mechanism, not prompt engineering: the backend creates the branch and a
-hook stamps the attribution; the materialized contract block carries the rest, so your dispatch
-prompt stays task-only. More on this mode of working:
-[working with agents](https://spexcode.net/working-with-agents/).
-
-## Measuring behavior: eval
-
-eval is the measuring half of
-[the loop](#the-optimization-loop), built on the YATU discipline (**You As The User**): you measure
-behavior from the product's real surface, the way a real end user would touch it, not through an
-internal helper or shortcut that makes the
-proof easy. A spec says what a part should do; an
-`eval.md` beside it says how to check. Each scenario is a plain description plus an expected
-result. eval itself runs nothing (no DSL, no runner). An agent runs the scenario however it can:
-a test file, a real browser, or just clicking through by hand and screenshotting. It compares
-actual to expected and files the eval with evidence:
+<img src="docs/readme-worker-flow.svg" alt="the eight-step worker loop: dispatch, read the spec, do the work, run evals, clear drift, propose a merge, human review, close">
 
 ```sh
-spex eval add settings --scenario remembers-tab --pass --image evidence.png
+spex session ls                  # the living table below
+spex session watch stream        # follow transitions: working → review → done …
+spex session review uploader     # commits ahead of trunk, merge-base diff, merge/lint gates
+spex session merge uploader      # hands the gated merge to the session's own agent
+spex session close uploader      # retire the worktree, branch, and record
 ```
 
-Evals live in a git-tracked ndjson next to the spec, so measurements get the same attribution
-and history as spec versions. Bug fixes are expected to bracket: file a failing eval that
-reproduces the bug, fix, then file a passing eval on the same scenario.
+<img src="docs/readme-sessions.svg" alt="animated terminal: spex session ls listing five sessions across working, review, asking and done states">
 
-<img src="docs/readme-eval.png" alt="eval view screenshot">
+Each rule has a mechanism enforcing it: the backend creates the branch, a git hook attributes
+every commit to its session, a pre-commit guard rejects direct commits to the trunk, and the
+remaining conventions live in the materialized `CLAUDE.md`/`AGENTS.md`. Your dispatch prompt only
+has to state the task. More: [working with agents](https://spexcode.net/working-with-agents/).
 
-*The eval view: scenario evals on the left; the selected eval's expected result, staleness,
-and recorded video evidence in the middle.*
+## The dashboard (L2)
 
-## What's in the repo
-
-| Package | Role |
-|---|---|
-| `spec-cli` | The `spex` CLI and the HTTP backend (Hono, runs via tsx, no build step). Reads `.spec` and git live; owns the session state machine and the linter. |
-| `spec-dashboard` | React board: the node graph, per-node spec/history/issues panes, and a real terminal onto each live agent session. |
-| `spec-eval` | Scenario definitions, evals, evidence. |
-| `spec-forge` | Read-only tracer that resolves a forge's open issues and PRs to the spec nodes they serve (GitHub and GitLab drivers today). An issue links itself with a `Spec: <node-id>` line in its body; a PR from a `node/<id>` branch links for free. |
+The spec tree, the sessions, and the evals each have a live page on the dashboard. Start `spex serve` and `spex dashboard`, then:
 
-## The linter
+<img src="docs/readme-graph.png" alt="the spec map: SpexCode's own repo on its own board — per-node version and eval chips, an agent avatar hovering on the node it is editing">
 
-`spex spec lint` checks the spec↔code graph and is the real gate (the git hook is fast local feedback):
+*Your whole repo as one map — SpexCode's own board shown. Each node carries its version and eval
+state, an agent's avatar hovers on the node it is editing right now, and the rail top-left is the
+live session console.*
 
-- **integrity** (error): a `code:` or `related:` path that doesn't exist
-- **living** (error): a changelog heading in a spec body
-- **coverage** (warn): unclaimed source files
-- **drift** (warn): governed code changed after its spec's last version, derived live from git
+<img src="docs/readme-node.png" alt="a node opened on the board: the raw source callout, the expanded spec body, the governed file, a drift badge, and tabs for history, issues, eval">
 
-plus naming and ownership rules (`one-govern`, `id-format`, `mention` as errors;
-`related-drift`, `owners`, `confusable-id` as warns) — `spex guide spec` lists them all.
+*Click a node: the raw source on top, the expanded spec below it, the file it governs, its current
+drift state, and tabs for the version history git already kept, its issues, and its evals.*
 
-`spex doctor` is the opt-in, read-only health diagnosis. Its altitude and breadth checks report bodies that
-look like implementation dumps and nodes with wide child fan-out, with per-node evidence and repair, without
-putting heuristic judgment in the lint or commit gate.
+<img src="docs/readme-eval.png" alt="an eval reading under review: verdict banner, the scenario's expected result, the agent's note, recorded video evidence, and the review queue">
 
-## Configuration
+*An eval reading under review: the verdict, the scenario's expected result, the agent's note and
+recorded video evidence. You can draw a region on the video to annotate it; the annotation is
+matched to its step automatically, and the timestamp and step are sent to the agent with your
+comment. The queue on the right leads to the next reading.*
 
-`spexcode.json` (committed, portable: layout, lint policy, doctor health budgets, project dashboard identity, launcher names) and
-`spexcode.local.json` (gitignored, host-specific: absolute launcher paths, cert paths) cover every
-setting. There is no imperative settings verb: you edit the two files by hand (or ask your agent
-to), and `spex guide settings` documents every field. The Projects admin UI writes a project's icon back
-to that same `dashboard.icon` field; the global gateway icon is the one separate host fact at
-`$SPEXCODE_HOME/config.json` `gateway.icon`, never copied into a repo. The other
-manuals are `spex guide` (the workflow), `spex guide spec`, `spex guide eval`, and
-`spex guide footprint`; `spex help` maps the commands.
+The whole workspace is served over HTTP, so every view (a spec node, a session, an eval reading, a
+live terminal) is a stable URL you can hand to a colleague; you can sit on the same board together.
+The terminal pane is a real tmux session: copy the printed command and attach from your own
+terminal.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/hooks/harness.sh

@@ -1,15 +1,15 @@
 #!/usr/bin/env bash
 # @@@ harness.sh - the SHELL face of the [[harness-adapter]] (spec-cli/src/harness.ts). The hook scripts run
 # as pure shell, so they cannot import the TS adapter; this sourced library is its mirror. dispatch.sh sources
-# it and exports SPEXCODE_HARNESS (claude|codex|opencode) — baked into the shim by each adapter, so a hook learns its
+# it and exports SPEXCODE_HARNESS (claude|codex|opencode|zcode) — baked into the shim by each adapter, so a hook learns its
 # harness deterministically, never by sniffing the payload shape. EVERY harness-divergent payload-parse lives
 # HERE; the hook scripts stay harness-agnostic and just call hp_* (the one place Claude's tool names appear in
 # shell, plus codex's Bash-command mapping). The session-id + global-store resolution is harness-agnostic and
 # lives here too, so the six hooks no longer each repeat the git-common-dir → project-key dance.
-# SPEXCODE_HARNESS is claude|codex|opencode|pi|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its
-# host (z-code/Claude) shares Claude's payload shape; `opencode`'s generated plugin ([[opencode-harness]]) and
-# `pi`'s generated extension ([[pi-harness]]) SYNTHESIZE claude-shaped payloads by construction — so every
-# `case "$SPEXCODE_HARNESS"` below routes all three through the claude branch via the default case; only codex
+# SPEXCODE_HARNESS is claude|codex|opencode|pi|zcode|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its
+# host (adopter-a/Claude) shares Claude's payload shape; `opencode`'s generated plugin ([[opencode-harness]]),
+# `pi`'s generated extension ([[pi-harness]]), and z-code's native hook payload all share that Claude shape — so every
+# `case "$SPEXCODE_HARNESS"` below routes all four through the claude branch via the default case; only codex
 # keeps parse arms of its own.
 
 
@@ -68,11 +68,28 @@ hp_field() {
 # every child tool call fired mark-active against the PARENT's record — the parent read `working` forever and
 # every park/done declaration was clobbered within seconds (measured). Same staleness class the codex branch
 # already guards against (payload-first below); claude now follows the same rule.
+# The claude preference is RESOLUTION-AWARE, not blind. "Claude's payload id equals its governed record id"
+# holds only while the launched conversation lives: a compaction/continuation MINTS A NEW conversation id
+# while the record keeps the launched one, and a blindly-preferred payload id then resolves to no record at
+# all — hp_store_dir echoes a path nothing sits at, so every record-dependent hook (stop-gate, mark-active,
+# idle, session-fail) silently no-ops and the session reads `working` forever (measured: a live session froze
+# at `active` while its terminal still answered). So the payload wins only when a record actually answers to
+# it, and an unresolvable payload falls back to the launched SPEXCODE_SESSION_ID. This cannot reopen the
+# subagent bug above: a Task subagent's payload carries the PARENT's session_id, which DOES resolve, so the
+# preference is unchanged there — the divergent branch is reached only when the two ids differ AND the
+# payload names nothing. The common path costs one string compare (the ids are equal), never a store read.
 hp_session_id() {
   local pid
   case "$SPEXCODE_HARNESS" in
     codex) hp_field "$1" session_id ;;
-    *)     pid=$(hp_field "$1" session_id); printf '%s' "${pid:-$SPEXCODE_SESSION_ID}" ;;
+    *)     pid=$(hp_field "$1" session_id)
+           if [ -n "$pid" ] && [ -n "$SPEXCODE_SESSION_ID" ] && [ "$pid" != "$SPEXCODE_SESSION_ID" ] \
+              && [ ! -e "$(hp_store_dir "$pid")/session.json" ] \
+              && [ -e "$(hp_store_dir "$SPEXCODE_SESSION_ID")/session.json" ]; then
+             printf '%s' "$SPEXCODE_SESSION_ID"
+           else
+             printf '%s' "${pid:-$SPEXCODE_SESSION_ID}"
+           fi ;;
   esac
 }
 
@@ -129,6 +146,9 @@ hp_store_dir() {
   local rd; rd=$(hp_runtime_dir) || return 1
   local direct="$rd/sessions/$1"
   if [ -e "$direct/session.json" ]; then printf '%s' "$direct"; return 0; fi
+  # same two-halves-of-absence rule as layout.ts's readAliasedRecordEntry: an id owning a store dir is already
+  # one of ours, so its emptiness is settled and the alias grep is the wrong question (and a whole-store scan).
+  if [ -d "$direct" ]; then printf '%s' "$direct"; return 0; fi
   local hit
   hit=$(grep -lF "\"harness_session_id\": \"$1\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1)
   [ -n "$hit" ] && { printf '%s' "${hit%/session.json}"; return 0; }

package/spec-cli/src/anchors.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 import { createRequire } from 'node:module'
-import { git, gitRequiredA, gitObjectFormat, isGitObjectId, batchRevisionOids, batchBlobTexts, combinedDiffOwnedChanges, driftPathWindow, type DiffLineRange, type DriftIndex, type DriftPathEvent } from './git.js'
+import { git, gitRequiredA, gitObjectFormat, isGitObjectId, batchRevisionOids, batchBlobTexts, combinedDiffOwnedChanges, driftPathWindow, readImmutableHunkFacts, persistImmutableHunkFacts, withEventLedgerBuild, type DiffLineRange, type DriftIndex, type DriftPathEvent, type ImmutableHunkRanges } from './git.js'
 
 const RS = '\x1e'
 
@@ -484,7 +484,8 @@ const hunkMemo = new Map<string, HunkRanges>()
 // historical path. Keying on those makes the key move exactly when an input does, and the oids are already
 // resolved by this read's one `cat-file --batch-check`, so completeness costs no extra child and no new state.
 const ABSENT_IMAGE = '-'
-const hunkMemoKey = (images: string[]) => images.join('\0')
+const HUNK_FACT_SCHEMA = 'anchor-range-histogram-v1'
+const hunkMemoKey = (images: string[]) => `${HUNK_FACT_SCHEMA}\0${images.join('\0')}`
 function rememberHunks(key: string, ranges: HunkRanges): HunkRanges {
   if (hunkMemo.size >= MEMO_MAX) hunkMemo.clear()
   hunkMemo.set(key, ranges)
@@ -584,6 +585,10 @@ const anchorRevisionKey = ({ commit, path }: AnchorRevision) => `${commit}\0${pa
 // selector verdict.
 async function runAnchorQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[], stopAtFirstHit: boolean): Promise<AnchorHit[][]> {
   if (!queries.length) return []
+  return withEventLedgerBuild(root, () => runAnchorQueriesInLedger(root, queries, regs, stopAtFirstHit))
+}
+
+async function runAnchorQueriesInLedger(root: string, queries: AnchorHitQuery[], regs: Extractor[], stopAtFirstHit: boolean): Promise<AnchorHit[][]> {
   const objectFormat = gitObjectFormat(root)
   const revisions = new Map<string, AnchorRevision>()
   const ordinaryEvents: { path: string; commit: string; event: DriftPathEvent }[] = []
@@ -604,14 +609,28 @@ async function runAnchorQueries(root: string, queries: AnchorHitQuery[], regs: E
     imageOf(event.commit, event.historicalPath),
     ...event.parents.map(({ commit, historicalPath }) => imageOf(commit, historicalPath)),
   ])
+  const hunkKeys = new Set<string>()
   const ordinaryByPath = new Map<string, Map<string, string>>()
   for (const { path, commit, event } of ordinaryEvents) {
     const entries = ordinaryByPath.get(path) ?? new Map<string, string>()
-    entries.set(commit, imageIdentity(event))
+    const key = imageIdentity(event)
+    hunkKeys.add(key)
+    entries.set(commit, key)
     ordinaryByPath.set(path, entries)
   }
+  for (const { win } of queries) for (const event of win) hunkKeys.add(imageIdentity(event))
+  const durableHunks = readImmutableHunkFacts(root, hunkKeys)
+  for (const [key, ranges] of durableHunks) rememberHunks(key, ranges)
+  const newHunks = new Map<string, ImmutableHunkRanges>()
   const ordinaryHunks = new Map<string, Map<string, HunkRanges>>()
-  for (const [path, entries] of ordinaryByPath) ordinaryHunks.set(path, await hunksAtMany(root, path, entries))
+  for (const [path, entries] of ordinaryByPath) {
+    const rangesByCommit = await hunksAtMany(root, path, entries)
+    ordinaryHunks.set(path, rangesByCommit)
+    for (const [commit, key] of entries) {
+      const ranges = rangesByCommit.get(commit)
+      if (ranges && !durableHunks.has(key)) newHunks.set(key, ranges)
+    }
+  }
   // The image's own memo answers before any bytes move, so the read asks git only for the revisions this
   // process has not parsed yet — the retention half of the same rule the hunk demand set follows.
   const units = new Map<string, FileRevisionUnits>()
@@ -665,8 +684,10 @@ async function runAnchorQueries(root: string, queries: AnchorHitQuery[], regs: E
         run.cursor++
         const after = units.get(anchorRevisionKey({ commit: event.commit, path: event.historicalPath }))!
         const before = event.parents.map(({ commit, historicalPath }) => units.get(anchorRevisionKey({ commit, path: historicalPath }))!)
+        const key = imageIdentity(event)
         const ranges = ordinaryHunks.get(event.historicalPath)?.get(event.commit)
-          ?? await hunksAt(root, event, imageIdentity(event))
+          ?? await hunksAt(root, event, key)
+        if (!durableHunks.has(key)) newHunks.set(key, ranges)
         if (event.parents.length && ranges.before.length !== before.length)
           throw new Error(`anchor diff for ${event.commit}:${event.historicalPath} has ${ranges.before.length} parent ranges for ${before.length} parents`)
         const hit = run.hits.get(event.commit) ?? { selectors: new Set<string>() }
@@ -688,6 +709,7 @@ async function runAnchorQueries(root: string, queries: AnchorHitQuery[], regs: E
       }
     }
   }
+  await persistImmutableHunkFacts(root, newHunks)
   return runs.map((run) => [...run.hits].map(([commit, hit]) => ({ commit, selectors: [...hit.selectors], ...(hit.unparseable ? { unparseable: hit.unparseable } : {}) })))
 }