docs(specs): byte-aware worktree retention (#842)

[sapersky]

Refs #842

Source doc: .ai/specs/2026-08-10-byte-aware-worktree-retention.md
Status: design only — no implementation in this PR

🎯 Goal

Count-based worktree retention (#483) works exactly as specified and still misses its own stated goal on build-heavy repositories. This spec proposes a strip rung between "keep" and "reclaim" so the policy can evict what costs disk without evicting what has value.

Why this is worth a design review before any code

Measured on one machine, four registered projects, retention healthy in every one of them (no orphans, worktreeReclaimedAt stamps present, all inside budget):

Project	Finished worktrees	Budget	On disk
cezar-app (Swift/Xcode)	10	keep=10 ✅	17 GB
tronbalance-web (JS)	10	keep=10 ✅	816 MB

One cezar-app worktree: 7 MB git-tracked, 2904 MB on disk — 99.8% regenerable build output. The same satisfied keep=10 costs 20× more on one toolchain than another, and the machine was at 8.8 GB free while the policy reported itself healthy.

Value (the checkout) and cost (the artifacts) live in disjoint file sets, so a count budget can only trade both away at once. A byte budget alone would not fix that — it would make the same all-or-nothing eviction happen sooner. The granularity is the defect, not the threshold.

📉 What the second review round changed: the byte dimension is deferred

The title still says byte-aware; the first release is not, and that is the substantive change in this revision. The whole measured win — 17 GB → ≈ 5.2 GB — is 3 × 1.7 GB + 7 × 7 MB, i.e. it comes entirely from stripping derived output outside a hot set of three, on recency alone. fs.statfs, DISK_FLOOR, pressureBytes, the escalation loop, persisted sizes with their lazy backfill and the node_modules tier would all serve a rung that frees nothing in the case this document was written about.

So they move to a conditional Phase 3, gated on re-measuring Phase 1 on the same four projects — recorded as Q5 in the Resolved assumptions table, an explicit and overridable decision rather than a silent omission. The constraints already learned (flat DISK_FLOOR, three escalation exits, backfill kept off the boot path, oldest-first ordering preserved) stay written down so Phase 3 does not rediscover them.

What this buys: one optional state field instead of two, no du in front of cezar serve, and roughly half the surface on a risk-high delete path — with the honest half of the promise shipping sooner.

⚠️ The assumption that needs a maintainer, not an agent

Q4 — is strip on by default in its first release? was defaulted to yes, and it is marked ⚠ NEEDS HUMAN CONFIRMATION. This PR is therefore a draft and should not merge until that call is made.

Two repository laws pull in opposite directions here. AGENTS.md → Zero config forbids hiding this behind an opt-in flag ("never trade a working default for a knob"). AGENTS.md → "Changing a mechanism that already works" warns that precisely this kind of change leaves the zero-config user quietly worse off, naming #810/#811 as the worked examples. What today's behavior is load-bearing for is warm build caches on recently finished tasks; HOT_KEEP = 3 is what preserves it. The surface is risk-high and every user is affected silently, so an autonomous default is the wrong instrument.

Q5 shrinks what is being signed off: with dependency trees deferred, default-on means "rebuild from CPU", never "re-download from a registry". The remaining assumptions (HOT_KEEP value, discovering the byte dimension rather than configuring it when it does land, a non-configurable artifact allowlist) are consequences of the Zero config law and are listed for override.

🔍 What most deserves adversarial review

The strip rung is a delete path over user data. A path is removed only when both hold: its basename is on an internal allowlist, and git check-ignore -q confirms it is genuinely ignored in that repository. The second condition is what protects a repo that tracks dist/, with nothing to configure. git clean -xdf/-Xdf is explicitly rejected in any form — it deletes ignored .env files, which is a data-loss incident rather than a cleanup. The dependency-tree names are absent from the Phase 1 allowlist rather than flagged off, so a tier that cannot fire is not one condition away from firing.

git check-ignore is already the canonical guard for this class of decision in this codebase (packages/cezar/src/agent-config/seed.ts:80, per catalog.ts:24), so this reuses an established mechanism rather than inventing one.

Candidate discovery is now a stated rule rather than a goal: prune on match, never descend into .git or a symlink, hard depth cap of 4. cezar's own checkout is the worked example — packages/cezar/dist at depth 2 and packages/cezar/web/dist at depth 3 — and a nested-workspace fixture makes a depth-1 implementation fail the suite instead of passing it green.

Compatibility

Additive only. One optional RunRecord field (worktreeStrippedAt) per BACKWARD_COMPATIBILITY.md §3 — a required field would silently drop every pre-existing run through the array safeParse — following the documented #737/#751 precedent. Since #695 that field is a lockstep edit across packages/cezar/src/runs/store.ts and packages/contract/src/runs.ts, behind the Exact<> parity assertions in contract-parity.runs.test.ts; the same applies to the GET /worktrees field and the new POST /worktrees/strip route, which also has to enter the §2 route inventory that bc-route-inventory.test.ts enforces. Those locksteps are now named in the plan steps rather than left to the implementer.

No configuration keys are added, renamed, or re-defaulted — the protected resources shape is untouched in every phase.

Breaking Changes

None — design only.

Notes

• Text-only spec: no UI mockups or current-app screenshots are attached because this repository has no om-prepare-test-env descriptor configured, so the browser-provider capture step was skipped rather than faked.
• Labels could not be applied by the author account (read access only — the same reason Implement: byte-aware worktree retention — a build-heavy repo holds 17 GB inside keep=10 #842 carries no labels). Intended set: documentation, skip-qa, review, priority-medium, risk-low for this design-only PR; the eventual implementation PR is risk-high.
• The earlier heads-up about feat: add resilient multi-model development workflows #747 is withdrawn — it is closed. Merge risk now sits with the contract/parity lockstep rather than with any single open PR.

How to pick this up

Implementation ships on its own PR referencing this one (Refs), via om-auto-implement-spec — this PR stays design-only.

🤖 Generated with Claude Code

[CLAassistant]

All committers have signed the CLA.

[sapersky]

🤖 om-auto-write-spec — Open Questions

The spec was written in autonomous mode, so the Open Questions gate was resolved with documented defaults instead of stopping. Every one of these is meant to be overridden here before merge — reply on this PR and the spec gets amended.

#	Question	Default chosen	Rationale
Q1	What is the "hot" set that keeps its build cache?	3 most recently finished, as an internal constant HOT_KEEP = 3, not a setting	AGENTS.md → Zero config: "When a feature seems to need configuration, the design is wrong. Discover it, or default it." Three covers the realistic resume window without holding a fleet of caches.
Q2	Is the byte budget a maxBytes setting, or discovered?	Discovered from free disk space; no new config key at all	"Never trade a working default for a knob." A byte ceiling is a number nobody can pick correctly — it depends on the machine, not the repo. Free space is the quantity the original goal is actually about, and it is already knowable. Side benefit: the protected resources shape is left completely untouched.
Q3	Is the artifact allowlist configurable per project?	No — internal constant, extended by PR when a new toolchain appears	Same law, plus a per-project allowlist is a footgun pointed at a delete path: a typo becomes data loss. The git check-ignore condition already adapts per repository without anyone authoring anything.
Q4	Is strip on by default in its first release?	Yes — ⚠ NEEDS HUMAN CONFIRMATION	Zero config forbids an opt-in flag, but "Changing a mechanism that already works" warns that exactly this kind of change leaves the zero-config user quietly worse off (#810/#811). HOT_KEEP preserves what the current behavior is load-bearing for — warm caches on recent tasks — but the surface is risk-high and every user is affected silently. This is a maintainer's call, not an agent's.

Merge is gated on Q4. That is why this PR is a draft: the design is coherent under the assumption, but shipping a silent default change on a risk-high surface should not rest on an autonomous default. Confirming or reversing Q4 is the one thing needed to move this out of draft — Q1–Q3 are ordinary review comments.

[wojciechszyjka]

🔍 Specification Review

🤖 om-auto-review-pr by @wojciechszyjka — spec-only PR (.ai/specs/**, one file), so this is a design review against the five lenses rather than a code checklist. The validation gate is not applicable and was not run; the diff adds no code.

🎯 Summary

The problem statement is the strongest part of this document, and it is a real one: a policy that reports itself healthy at keep=10 while holding 17 GB is not a threshold that needs tuning, it is a mechanism measuring the wrong thing. The framing — value and cost live in disjoint file sets, so a count budget can only trade both away at once — is the right diagnosis, and the conclusion that a byte budget alone would just make the same all-or-nothing eviction happen sooner is correct and worth keeping in the document.

I checked the spec against the code it proposes to change, and the grounding is good. selectReclaimableWorktrees really is reclaimable.slice(keep); GET /worktrees really does already compute per-row sizeBytes and a totalBytes: null degradation (server.ts:4309-4331); enforceRetention really is at run.ts:1502 behind the terminal-transition hook at run.ts:1170; and agent-config/seed.ts:80 really does re-check a by-convention ignore against git check-ignore -q -- before trusting it, so the safety rule reuses an established mechanism rather than inventing one.

I also tested the load-bearing half of that safety rule rather than taking it on trust. In a fixture repo with dist/ in .gitignore and dist/foo.js force-added, git check-ignore -q dist exits 1 — not ignored — because check-ignore consults the index unless --no-index is passed. So the spec's claim that "a repo that tracks dist/ fails condition 2 and is untouched" holds, including at directory granularity where I expected it to leak. That is the single most important assertion in the document and it survives. The implementation must not add --no-index, and the test matrix should say so explicitly, because that flag silently converts the guard into a data-loss path.

Verdict: request changes. Not on the direction — the strip rung is the right idea and the safety rule is sound. Three majors below are concrete holes in the design as written, each of which would ship a behavior the spec does not intend. There is also a merge blocker outside the author's design work.

🔴 Blocker (process, not design)

The CLA is unsigned and, as reported on this PR, cannot be signed by this account — sapersky seems not to be a GitHub user. license/cla is the only check on this PR and it is red. Whatever happens to the design, this branch cannot merge until that is resolved: either the commit's author email is added to a real GitHub account and the CLA signed, or the spec is carried forward on a PR from an account that can sign. Worth settling early rather than after a design round-trip.

Separately and already acknowledged by the author: Q4 needs a maintainer, and this PR is correctly a draft until it is answered. I agree with the author's reading that this is not an autonomous call — AGENTS.md Zero config and the "changing a mechanism that already works" warning genuinely point in opposite directions here, and the tie-breaker is a judgement about users, not about laws.

🟠 Major

1. DISK_FLOOR = max(10 GB, 10% of the volume) degenerates into "reclaim everything" on a large disk

Take a 4 TB volume with 300 GB free. That is a comfortable machine by any human reading, but max(10 GB, 10%) puts the floor at 400 GB, so the pass is permanently under pressure. The escalation the spec then specifies is "strip everything outside the hot set first, then reclaim oldest-first until free space recovers or nothing reclaimable is left" — and stripping a few worktrees will never move a 100 GB deficit, so the loop runs to the second exit condition and reclaims every reclaimable worktree, on every pass, regardless of keep.

max() is backwards for this quantity: the percentage term is meant to protect small volumes, but it is the term that dominates on large ones. Something shaped like min(50 GB, max(10 GB, 10%)) — or simply a flat constant, given the spec's own argument that once strip is doing the work the byte dimension is a backstop rather than the primary control — avoids it. Whatever the formula, the escalation loop needs a second exit condition so that "pressure cannot be relieved" degrades to today's count-only behavior instead of emptying the pool.

2. keep = 0 means "never auto-reclaim", and the strip rung silently overrides it

Today keep === 0 is documented as unlimited — never auto-reclaim and selectReclaimableWorktrees returns [] for it (retention.ts:37-42). That is a user who explicitly told cezar to keep their hands off. Under this spec, budgets "become placement" and "everything else that is finished gets stripped" — with no exception carved out for keep = 0, so that user's worktrees start losing their build trees anyway. The Data Model section states worktreeRetention and "the 0 = unlimited semantics are untouched", which is true of the config key and not true of what the user gets.

This needs an explicit decision in the spec — most likely keep = 0 disables both rungs, since the setting's meaning is "do not manage my worktrees" rather than "do not delete my directories" — and it belongs in the Edge Cases table beside the other degradations.

3. The persisted size is never measured for worktrees that already exist, so the byte dimension is permanently blind on exactly the machine in the problem statement

The spec moves sizing from "measured on demand" to "measured once at the terminal transition and persisted on the run record", and states that an absent size counts as 0. But a run that finished before this ships never transitions again, so worktreeSizeBytes is never written for it — not on the next pass, not ever. On the measured cezar-app project, all ten worktrees holding the 17 GB would report 0 to the planner forever, and pressureBytes would be computed against a total of zero on the one machine the spec opens with.

The count-driven half of the win still lands (strip applies outside the hot set regardless of size), so this is not fatal — but the byte dimension, which is the spec's title, is inert for the entire pre-existing population. The fix is small and the machinery already exists: worktreeSizeBytes() is already used per row by GET /worktrees, so the enforcer can lazily measure and persist any finished run whose size is absent, once. Please state that in the Architecture section rather than leaving it to the implementer.

Related, same section: plan step 5 wires enforceRetention (run.ts:1502) to the planner, but the boot path does not go through it — index.ts:238 calls reclaimWorktrees(repoRoot, store, keep) directly. As written, a cezar that is restarted rather than left running would keep applying the old count-only behavior at boot. Either the boot call site is listed in step 5 too, or both paths are funnelled through one entry point first.

🟡 Minor

• "Regenerable" is doing more work than it can carry for node_modules and .venv. The resume story is "none needed — the agent just rebuilds", which is true for .build, DerivedData, target and .next, and only conditionally true for a dependency tree: rebuilding it needs a reachable registry and, absent a warm package-manager cache, a non-trivial download. cezar's own worktrees are the worked example — the validation gate cannot run in one until node_modules is restored. Either say so in the rung table (strip trades disk for a rebuild that may need network), or consider whether dependency trees deserve their own rung ordering, stripped only under actual pressure.
• The hot set's scope is undefined. HOT_KEEP = 3 reads as "3 most recently finished", but retention itself is per project (keep is resolved per repo root). Three per project and three per workspace are very different policies for someone with four registered projects — the measured machine, in fact. Please pin it.
• fs.statfs is qualified by the wrong constraint. The spec cites Node ≥ 18.15; this repo already requires Node ≥ 20 (package.json:8), so availability is not the interesting risk. What is worth naming in the degradation row is the filesystem and platform cases where statfs returns something unusable — which the spec's count-only fallback already handles, but for a different stated reason than the one written down.
• The POST /worktrees/strip idempotency claim needs one sentence on concurrency. Retention already fires from a terminal transition (run.ts:1170) while the panel is open; a manual strip landing mid-pass should be specified as safe-by-overlap (both targets are regenerable) rather than left implied.

🔵 Nit

• Two grounding references drifted: selectReclaimableWorktrees is retention.ts:42, not :37, and index.ts:238 is reclaimWorktrees, not enforceRetention. Both matter only because the second one hides the missed call site in major 3.
• Worth adding to the Testability section, explicitly: git check-ignore must be called without --no-index, with the tracked-dist fixture as the regression that proves it. The whole safety argument rests on a default that a future refactor could plausibly "optimize" away.

✅ What I would not change

• Rejecting git clean -xdf/-Xdf outright, with .env named as the reason, is correct and belongs in the document permanently.
• Oldest-first over largest-first, with the reasoning given (recency is the property a user can reason about; the strip rung already removes the pressure that would justify a greedy heuristic), is the right call and well argued.
• Two independent conditions rather than one, and closed failure when check-ignore is unavailable, is the correct posture for a delete path.
• The additive-optional RunRecord fields with the safeParse rationale follow BACKWARD_COMPATIBILITY.md §3 exactly.

Labels

None applied — the author reports read-only access on this account, and the intended set (documentation, skip-qa, review, priority-medium, risk-low for the design PR; risk-high for the implementation) matches this repo's inference rules in SDLC.md:59, where worktree/branch handling and the .ai/cezar/ state file formats are both named risk-high surfaces. A maintainer can apply them as listed.

[sapersky]

🤖 om-auto-continue-pr — claim

Picking up @wojciechszyjka's review now: revising the spec for the three majors, the minors, and the valid nits, and fixing the CLA blocker at its root. This stays a spec-only, design-only PR — the only file that will change is the spec.

Read-only access again means no in-progress label and no self-assignment; this comment is the claim.

[sapersky]

🤖 om-auto-continue-pr — review addressed

Thank you for testing the load-bearing half of the safety rule instead of taking it on trust. That assertion — a repo that tracks dist/ is protected by condition 2 — is the one the whole document rests on, and an agent asserting it is worth much less than a reviewer who ran it. I reproduced your fixture independently before touching anything, and I got the same result, plus one extra data point worth recording:

.gitignore: dist/     dist/foo.js force-added
  git check-ignore -q dist              → exit 1   not ignored → PROTECTED
  git check-ignore -q --no-index dist   → exit 0   ignored     → WOULD DELETE
  .env (ignored, not on the allowlist)  → saved by condition 1, not condition 2
  directory patterns: `node_modules/` matches `node_modules`, `node_modules/`,
                      and nested `sub/node_modules`; bare `dist` matches too

The .env line is the one I had not spelled out: it demonstrates that neither condition implies the other, which is the actual argument for having two. Both are now in the spec, and the --no-index prohibition has its own named regression test rather than a sentence.

🟠 Majors — all three accepted, all three were real

1. DISK_FLOOR degenerating on a large disk. Confirmed; your arithmetic holds and the consequence is worse than a bad threshold — the loop reaches its "nothing reclaimable is left" exit and empties the pool on every pass, regardless of keep. Fixed by taking the spec's own argument seriously: if the byte dimension is a backstop rather than a tuning parameter, it does not need to scale with the volume. DISK_FLOOR is now a flat 10 GiB, and the reasoning about why the percentage term was wrong is kept in the document so nobody reintroduces it. I also added your suggested third exit condition: when reclaiming everything outside the hot set still would not clear the floor, the pass strips only, reports the condition, and reclaims nothing. Retention must never delete against a deficit it cannot fix.

2. keep = 0 silently overridden. Confirmed against retention.ts:38. Your reading of the setting's meaning is the right one and I have adopted it verbatim: keep = 0 now disables every rung. I also rewrote the Data Model sentence you flagged — "the 0 = unlimited semantics are untouched" was true of the config key and false of what the user gets, which is exactly the kind of true-but-misleading claim a spec should not contain.

3. Sizes never measured for the pre-existing population. Confirmed, and this was the most embarrassing one: the byte dimension would have been inert on precisely the machine the spec opens with. Lazy backfill is now stated in Architecture as required rather than left to the implementer — the enforcer measures and persists any finished run whose size is absent, once, reusing the worktreeSizeBytes() that GET /worktrees already calls per row.

3-related, the missed call site. This was the most valuable catch in the review. You are right that index.ts:238 calls reclaimWorktrees(...) directly and never goes through enforceRetention, and my spec asserted otherwise — so plan step 5 would have shipped a cezar that reverts to count-only behavior at boot, which is the common case on a laptop. The Architecture section now documents both call sites explicitly, and funnelling them through one entry point is its own plan step (5), ordered before the planner is wired in (6), so the omission cannot recur.

🟡 Minors — all accepted

• node_modules / .venv are not "regenerable" on the same terms. You are right, and this changed the design rather than the prose. The allowlist is now two-tiered: derived output (.build, DerivedData, target, dist, .next, .gradle, .turbo) is stripped whenever a worktree leaves the hot set, while dependency trees (node_modules, .venv) are stripped only under real disk pressure, because the trade there is disk now against a network dependency later. cezar's own worktree is cited as the worked example: the validation gate cannot run in one until node_modules is restored.
• HOT_KEEP scope. Pinned to per project, consistent with keep being resolved per repo root by resolveWorktreeRetention(repoRoot).
• fs.statfs. Corrected — package.json:8 requires Node >=20, so availability was never the interesting risk. The degradation row now names the real reason: filesystems and platforms where statfs fails or returns unusable numbers.
• POST /worktrees/strip concurrency. Stated: safe by overlap, since both actors target the same regenerable set, so a double removal is a no-op rather than a conflict.

🔵 Nits

• index.ts:238 — accepted, my error, corrected. As you say, it mattered because it was hiding major 3's missed call site.
• selectReclaimableWorktrees at :37 vs :42 — one polite pushback, because I think we are both right about different things. retention.ts:37 is the function declaration; :42 is the return reclaimable.slice(keep) expression. My sentence cited the symbol location while describing the expression, which is what made it read as wrong. Rather than move the reference, I have made it unambiguous: the spec now says the function at :37 reduces to reclaimable.slice(keep) at :42. If you would still prefer a single reference, say which and I will take it — this is not worth a round trip.

🔴 The CLA blocker — root-caused and fixed

You were right to flag it early, and the cause was mine rather than the user's. The CLA is signed for this account; the commit simply did not carry an email GitHub could link. The accepted #792 was authored as sapinskimarek@gmail.com (linked to sapersky), whereas the spec commit here went out under a different address that resolves to no GitHub user — hence the bot's "seems not to be a GitHub user". The repository's own git config had the correct address all along; it was overridden unnecessarily when committing.

Both commits have been re-authored to the linked address and force-pushed. license/cla is now green, and both commits resolve to sapersky. This is the one place I rewrote history on this branch, which the resume discipline otherwise forbids — it was unavoidable, because the CLA check reads every commit's author, and it is safe here since the branch is on a fork and your review is a top-level body rather than comments anchored to diff lines.

Still a draft, and still on Q4

Unchanged, and I agree with your agreement: Q4 needs a maintainer. The tie-breaker is a judgement about users, not about laws, and nothing in this revision touches it. Everything else in the review is now addressed, so Q4 is the sole remaining gate on moving this out of draft.

Notes

• This PR carries no .ai/runs/ execution plan, deliberately. The resume skill would normally commit one, but no spec PR in this repository does (docs(specs): design publishable Cezar React components #710, docs(specs): Linked-PR chips on the GitHub Issues list #816, docs(specs): a task remembers every PR it has been associated with #839 carry the spec and its assets only), and adding one would have broken the single-file property you validated. The reconstructed goal is this comment instead.
• Labels still could not be applied — read-only access, same as before. The intended set is unchanged from your reading of SDLC.md:59.
• Still worth rebasing around feat: add resilient multi-model development workflows #747 before implementation; it remains open on git-worktree.ts.

Diff of this revision: one file, +89 lines net. No code, no new files.

[sapersky]

🤖 om-auto-continue-pr — claim released

Review round complete: all three majors, all four minors and both nits addressed, CLA green. Nothing is being worked on for this PR right now.

Next step belongs to a maintainer, not to an agent: Q4 — whether the strip rung is on by default in its first release. That is the sole remaining gate on moving this out of draft. Implementation has deliberately not started and will ship on its own PR referencing this one.

[sapersky]

🤖 om-auto-fix-pr — ready for re-review; one label and one decision are all that is left

This PR has been sitting still for a day, and I think the cause is mechanical rather than substantive, so here is the state laid out end to end.

Why it stalled

Three things overlap, and none of them is a disagreement about the design:

1. The changes-requested label is stale. The review landed at 13:19, the revision addressing all of it was pushed at 13:35, and the label set was applied at 15:02 — 87 minutes after the fixes. It is not a race between two writers: the labels were applied from the list the review body recommended at review time (om-auto-review-pr had read-only access and could not apply them itself), so they froze the 13:19 state rather than the 15:02 one. SDLC.md:35 says the pipeline label returns to review once the fixes land, and the review's own Labels section names review as the intended pipeline label. Could a maintainer flip changes-requested → review? I have read-only access on this repo and cannot.
2. GitHub's review decision is still CHANGES_REQUESTED, because that only clears when the same reviewer submits a new review — pushing commits and replying does not clear it, and an outside contributor cannot press re-request review. So this comment is the re-request: @wojciechszyjka, this is ready for your second pass whenever you have a slot.
3. It is a draft, correctly, pending Q4 — which you agreed with. But a draft is invisible to the review sweeps, so nothing was ever going to surface it. That is the actual reason it hung in the void, and it is why Q4 is stated as a single yes/no at the bottom of this comment.

What is actually finished

Everything in the review, verified in the diff rather than asserted:

Finding	Where it landed
🟠 1 — DISK_FLOOR degenerating on a large disk	Flat 10 GiB, the max(10 GB, 10%) reasoning kept as a warning, plus your suggested third exit condition: an unrelievable deficit strips and reclaims nothing
🟠 2 — keep = 0 silently overridden	keep = 0 now disables every rung, stated in Architecture and in the Edge Cases table
🟠 3 — sizes never measured for the pre-existing population	Lazy backfill is required, not optional, reusing worktreeSizeBytes()
🟠 3-related — the missed index.ts:238 boot call site	Both call sites documented; funnelling them through one entry point is its own plan step, ordered before the planner is wired in
🟡 node_modules / .venv are not regenerable on the same terms	Allowlist split into two tiers — derived output always, dependency trees only under real pressure
🟡 HOT_KEEP scope	Pinned to per project
🟡 fs.statfs qualified by the wrong constraint	Corrected to the real risk: filesystems and platforms where it fails or returns unusable numbers
🟡 POST /worktrees/strip concurrency	Stated as safe by overlap
🔵 index.ts:238 reference	Corrected
🔵 --no-index prohibition	Its own named regression test with the tracked-dist fixture

The 🔴 CLA blocker is resolved at the root — both commits carry the linked address and license/cla is green.

What changed just now

main had advanced 14 commits since this branch was cut, so I merged it in (clean, still one file changed) and re-verified every grounding reference against the new head:

• server.ts:4313 → :4382 and server.ts:4328 → :4401 — the GET /worktrees handler moved.
• Everything else still lands exactly: retention.ts:37/:38/:42/:121, run.ts:1170/:1502/:2111, index.ts:238, seed.ts:80, catalog.ts:24, git-worktree.ts:238, package.json:8.

That is the whole delta — no design change, so the second pass should be short.

The one open decision: Q4

Is the strip rung on by default in its first release?

The spec's answer is yes, marked ⚠ NEEDS HUMAN CONFIRMATION, and we both agreed an agent should not settle it: AGENTS.md → Zero config forbids a knob, while "changing a mechanism that already works" warns the zero-config user gets quietly worse off. HOT_KEEP = 3 is what preserves today's warm-cache behavior for the runs anyone would actually resume.

A one-word reply unblocks it — yes (on by default, as written) or no (opt-in for the first release, and I will amend the spec and the plan accordingly). The moment it is answered I take this out of draft; implementation ships on its own PR referencing this one, and is still worth rebasing around #747.

_{Read-only access on this repo, so no labels and no self-assignment from this side — this comment is the claim, and it is released: nothing is being worked on here right now.}

[wojciechszyjka]

🤖 om-auto-review-pr started by @wojciechszyjka at 2026-08-11T20:08:34Z. Other auto-skills will skip this PR until the lock is released.

[wojciechszyjka]

🔍 Specification Review — Re-review

🤖 om-auto-review-pr by @wojciechszyjka — second pass. Spec-only PR (one file under .ai/specs/**), so this is a design review against the five lenses rather than a code checklist. Reviewed at 804b57a, which is level with origin/main — the merge is clean and the only file that differs from main is the spec. license/cla is green; there are no failing and no pending checks.

🎯 Summary

Everything I asked for in the first pass landed, and landed properly — not paraphrased into the document but actually resolved, with the reasoning kept where it earns its place. The DISK_FLOOR fix is the best example: rather than silently swapping max(10 GB, 10%) for a constant, the spec now records why the percentage term was wrong and keeps the worked 4 TB counter-example, so the next person cannot reintroduce it. The keep = 0 decision, the required (not optional) lazy backfill, both enforcement call sites, the two-tier allowlist and the --no-index regression test are all in. I re-verified each against the diff rather than against the author's summary.

One correction I owe from the first pass: my nit that selectReclaimableWorktrees is at retention.ts:42 rather than :37 was simply wrong. At the commit this PR was cut from, the function was already at :37 and reclaimable.slice(keep) at :42 — exactly what the spec says, then and now. The author was right to leave it. The index.ts:238 half of that nit was real and is fixed.

So the direction is settled and the safety rule still holds. What this pass finds is different in kind: the spec is written against a package layout this repository left behind on 2026-07-27, and one of the fixes I asked for has a cost on a path I did not think through when I asked for it. Neither is a disagreement about the design; both are things an implementer would hit on day one.

Verdict: request changes — four majors, none of them fatal to the shape.

💥 What can go wrong

🟠 Major 1 — "bounded candidate discovery" has no stated depth, and this monorepo puts every candidate below it

The strip primitive's discovery is specified as "bounded — it descends only far enough to find the allowlisted names, never a full walk of a 2.9 GB tree." That sentence names a goal, not a rule, and the difference decides whether the feature works at all here.

A checkout of this repository holds, right now:

node_modules                      depth 1
packages/cezar/node_modules       depth 2
packages/api-client/dist          depth 2
packages/cezar/dist               depth 2
packages/cezar/web/dist           depth 3

An implementer reading "bounded" conservatively ships a root-level or depth-1 scan; it finds the root node_modules and nothing else, and every dist/ — the derived-output tier, the tier that is supposed to be stripped unconditionally — survives. cezar's own worktrees are the spec's named worked example for rung 1b, so this is not a hypothetical layout. Every npm/yarn workspace, every Cargo workspace and every Gradle multi-project build has the same shape.

The Testability fixture matrix does not catch it either: every fixture listed (node_modules ignored, dist tracked, .env not allowlisted, check-ignore unavailable) is a single-package repo, so a depth-1 implementation passes the whole suite green.

Please state the actual rule — a concrete maximum depth, or "descend until an allowlisted name matches, never into one" — and add a nested-workspace fixture (packages/*/dist + packages/*/node_modules) to the matrix so the rule is enforced rather than described.

🟠 Major 2 — the mandatory lazy backfill lands a multi-gigabyte du on the one path that is awaited at boot

This one is a consequence of my own major 3 from the first pass, so it is fair for me to carry it: I asked for lazy backfill to be mandatory and for both call sites to be funnelled through one entry point, and the spec correctly does both. Together they put a new cost somewhere it was not before.

The terminal-transition path is fire-and-forget — void this.enforceRetention() at run.ts:1170, with the comment stating retention must never delay the lifecycle. Backfill there is free. The boot path is not: index.ts:238 is await reclaimWorktrees(repoRoot, store, keep), executed inside serveCommand before the server binds its port, under a comment that reads "Best-effort; never blocks boot." Today that await is cheap — reclaimWorktrees does no sizing at all.

Under this spec, the first cezar serve after upgrading walks du over every finished worktree that has no recorded size. On the machine in the Problem Statement that is ten worktrees totalling 17 GB, cold, in front of the port opening. GET /worktrees already pays this cost per row (server.ts:4382), but only when a user deliberately opens the Worktrees panel — moving it in front of every boot is a different bargain, and it is the boot of a tool whose whole value is being instantly there.

The fix is small and belongs in the Architecture section rather than in the implementer's judgement: bound the backfill (measure at most N per pass), or run it off the critical path (after listen, or on the first post-boot pass), or exempt the boot entry point from backfill entirely and let the terminal-transition path fill the table in. Any of the three works; leaving it unsaid means the obvious implementation is the slow one.

🟡 Minor — the delete path has no stated observability

Boot already prints reclaimed N old worktree(s) and the reclaim stamp is persisted. Strip gets a worktreeStrippedAt stamp and a panel summary, but the spec never says what the pass logs — which paths were removed, how many bytes were freed, or which of the three escalation exits it took. For a rung whose defining risk is "removing the wrong path destroys unrecoverable user data", a log line naming what was deleted is the cheapest possible trust mechanism and the first thing anyone will want when a report comes in. Please specify it beside the existing reclaim logging.

🔁 Backward compatibility

🟠 Major 3 — the Data Model and both API steps target a package layout this repo left on 2026-07-27

b47d507b (#695, "split into packages/*, add typed api-client, version the API") merged on 2026-07-27, two weeks before this spec was written — so this is not drift introduced by the recent merge of main, and I did not catch it in the first pass either. The consequence is that three of the plan's steps name one file where the repository now enforces two or three in lockstep, each behind a type-level Exact<> parity assertion that fails npm run typecheck, not a test you can defer.

Step 2 — the RunRecord fields. The spec says the optional worktreeSizeBytes / worktreeStrippedAt go on RunRecord in packages/cezar/src/runs/store.ts. That file is right for persistence (store.ts:105), and the BACKWARD_COMPATIBILITY.md §3 reasoning about safeParse is exactly correct. But the record also has a wire twin at packages/contract/src/runs.ts:133, and packages/cezar/src/server/contract-parity.runs.test.ts:77-82 asserts Exact<z.infer<typeof runRecordSchema>, RunPatch200> (and four siblings). Add the fields to the store alone and tsc goes red; add them to the contract alone and the persisted record never carries them. worktreeReclaimedAt — this feature's direct precedent — lives in both (contract/src/runs.ts:232), which is the pattern to follow.

Step 7 — GET /worktrees gains strippedAt and rung. The row shape is worktreeInfoSchema at packages/contract/src/repo.ts:168, the envelope is worktreesResponseSchema at :181, and contract-parity.github.test.ts:113 pins them to the route with Exact. The cockpit reads the result through the typed client at packages/web/src/api/client.ts:1763. So step 7 is at minimum: contract schema → server handler → api-client type → panel.

Step 8 — POST /worktrees/strip. Needs its own response schema beside reclaimWorktreesResponseSchema (repo.ts:189) and its parity assertion, a body validator matching the jsonZodValidator(() => reclaimBodySchema, …) pattern the reclaim route already uses (server.ts:4407), and an entry in the BACKWARD_COMPATIBILITY.md §2 route list — which is line 47, Worktrees: GET /api/v1/worktrees, POST /api/v1/worktrees/reclaim, and is machine-enforced by packages/cezar/src/server/bc-route-inventory.test.ts. A new route that is not added to that prose list fails the drift guard.

The good news is that route aliasing is free: worktreesRoutes is a chained sub-app, so projectRouteManifest (server.ts:408) picks a new registration up and the three-way alias-parity suite covers it without extra work. Worth saying so explicitly, because it is the one part of this that looks like it should need attention and does not.

I am calling this a major rather than a blocker because the spec does not mis-describe the codebase — store.ts and server.ts are both real and both must change. It under-describes it, and the missing half is the half that is type-enforced.

🟡 Minor — rung collides semantically with the reclaimable boolean already on the same row

The row already carries reclaimable: isReclaimable(r) (server.ts:4397, repo.ts:174), meaning finished, has a directory, not yet reclaimed. The spec adds rung: 'hot' | 'stripped' | 'reclaimable' to the same object. A hot worktree is then { reclaimable: true, rung: 'hot' } and a stripped one { reclaimable: true, rung: 'stripped' } — two adjacent fields where one word means "eligible under the old rule" and the same word means "the rung it is currently placed on". That is a bug waiting to happen in the panel and a confusing shape to freeze onto a protected surface.

Either rename the enum member ('evictable', or split it into strippedAt + a derived hot: boolean), or state in the API Contracts section how the two relate and which one a consumer should trust. A sentence is enough; the collision is not.

✅ Correct as written

• Both new RunRecord fields optional, with the safeParse rationale and the #737/#751 precedent — exactly BACKWARD_COMPATIBILITY.md §3.
• No configuration keys added, renamed or re-defaulted; the protected resources shape in GET/PUT /api/v1/workspace/config is untouched, and the spec correctly identifies that as a consequence of the Q2 decision rather than a coincidence.
• worktreeReclaimedAt and worktreeStrippedAt stated as independent stamps, with rematerializeReclaimedWorktree keying on the former alone.

🧩 What's missing

• 🟡 Two sources of truth for a worktree's size, never reconciled. The planner reads the persisted worktreeSizeBytes; GET /worktrees keeps calling worktreeSizeBytes() live per row and the spec explicitly leaves sizeBytes unchanged. That is a defensible split — live for display, persisted for planning — but after a strip the two disagree until the next re-stamp, and the panel is the surface where a user would notice. Say which is authoritative for which purpose, and whether the panel should prefer the persisted value now that one exists.
• 🟡 No acceptance criteria. The spec has a projection (5.2 GB instead of 17 GB) and a Testability section, but nothing stated as a pass/fail condition for the feature as a whole. Given the problem statement is a measurement, the acceptance criterion writes itself: re-run the same measurement on the same machine and state the number that counts as success.
• 🟡 Q4 remains open and is correctly still a maintainer call. I agree with the framing and with keeping the PR a draft until it is answered. Nothing for the author to do here; I am answering it separately.

📈 How this specification can be improved

• 🔵 #747 is closed, not open. The Merge risk bullet reads "#747 is open and edits packages/cezar/src/git-worktree.ts"; it is CLOSED. The advice to rebase around it is now moot, and the bullet should either be dropped or repointed at whatever is actually in flight when implementation starts.
• 🔵 server.ts is cited without its package path. Every other reference in the document carries one (packages/cezar/src/runs/retention.ts, packages/web/src/routes/settings/worktrees-panel.tsx), but server.ts:4382 / :4401 do not — and since #695 the file is packages/cezar/src/server/server.ts, one of four packages. Both line numbers are correct; only the path is missing. Same for index.ts:238 (packages/cezar/src/index.ts).
• Otherwise the structure is good and follows the repo's skeleton. The Edge Cases table in particular is doing real work — thirteen rows, each with a stated behavior rather than a shrug.

✂️ Is this the simplest possible solution?

🟠 Major 4 — the byte dimension is speculative by the spec's own evidence, and it is most of the machinery

I under-weighted this in the first pass, which is why it arrives late; the spec's own revisions are what made it visible.

Read the projection again: cezar-app goes from 17 GB to ≈ 5.2 GB as 3 × 1.7 GB + 7 × 7 MB. Every byte of that win comes from rung 1a — derived output, stripped outside the hot set, on recency alone. Swift .build and DerivedData are derived output; the motivating measurement contains no dependency tree at all. Rung 1b, pressureBytes, DISK_FLOOR, fs.statfs, the escalation loop with its three exit conditions, the persisted worktreeSizeBytes, and the mandatory lazy backfill exist to serve a rung that frees nothing in the case the document was written about.

And the spec argues this itself, twice: "once strip is doing the work, disk pressure stops binding in normal operation. The byte dimension becomes a backstop, not the primary control" and "a backstop does not need to scale with the volume." A backstop that has not yet been observed to fire is the definition of YAGNI.

The concrete alternative, since a claim of simplicity without a shape is worth nothing:

Phase 1 — strip derived output. stripWorktreeArtifacts() with the unchanged two-condition safety rule; HOT_KEEP = 3 per project; strip everything finished outside the hot set; keep = 0 disables everything; reclaim behaviour untouched. No statfs, no pressureBytes, no persisted sizes, no backfill, no escalation loop. The planner takes (runs, {hotKeep, keep}) and stays pure. The Data Model shrinks to one optional field — worktreeStrippedAt — or arguably zero, since "stripped" is observable from disk.

Phase 2 — panel surfacing and the manual action. Unchanged from what is written.

Phase 3 — the byte dimension, specified after Phase 1 has been measured on the same four projects. If pressure still binds, statfs, pressureBytes, rung 1b and the size persistence land then, against a real number instead of a projected one.

That cuts plan steps 4 and most of 6, removes a field from a protected surface (§3), removes the boot-path backfill cost in major 2 entirely, and drops the fs.statfs degradation row, the unrelievable-deficit exit and the pressure-ordering tests. It also keeps the honest part of the title's promise: the feature that fixes the measured problem ships sooner and with a smaller blast radius on a risk-high surface.

The counter-argument deserves stating rather than being brushed aside: on a JS repo the dependency trees are the bulk (tronbalance-web's 816 MB across ten worktrees is mostly node_modules), so rung 1b is not pointless — it is just unmeasured, and 816 MB is not what this document was written about. Deferring it costs nothing that a follow-up spec cannot recover, and buys a Phase 1 that is roughly half the surface.

If you disagree and want the byte dimension in the first release, that is a legitimate call — but then it belongs in the Resolved assumptions table as an explicit, overridable decision like Q1–Q4, not as an unexamined consequence of the title.

✅ What I would still not change

• Rejecting git clean -xdf/-Xdf outright with .env named as the reason. Permanent, load-bearing.
• Two independent conditions rather than one, and closed failure when check-ignore is unavailable.
• The --no-index prohibition promoted to its own named regression test with the tracked-dist fixture. This is the single most valuable paragraph in the document.
• Oldest-first over largest-first, with the reasoning intact.
• Reusing git check-ignore because agent-config/seed.ts:80 already establishes it as this codebase's guard for exactly this class of decision, rather than inventing a parallel mechanism. I re-verified that call site; it is ['check-ignore', '-q', '--', rel], index-consulting, as claimed.

✅ Validation gate

Not applicable and not run — the diff is a single markdown file under .ai/specs/ and adds no code. All five configured commands were skipped: npm run typecheck, npm test, npm run test:unit, npm run build, npm run test:package. This repository configures no markdown linter and no link checker, so there is no docs-applicable subset to run in their place.

Grounding was verified by hand against the checkout at this PR's head instead. Every reference in the document lands: retention.ts:37/:38/:42, run.ts:1170/:1502/:2111, index.ts:238, git-worktree.ts (worktreeSizeBytes at :225, removeWorktree at :239), seed.ts:80, catalog.ts:24, package.json:8 (node >=20), server.ts:4382 and :4401, SDLC.md:59 (worktree/branch handling and .ai/cezar/ state formats are both named risk-high), and worktrees-panel.tsx. The only reference that is stale is #747's open/closed state.

Labels

Unchanged, and correct for a design-only PR: documentation, skip-qa, priority-medium, risk-low. The pipeline label stays changes-requested to match this verdict — it was stale when the author flagged it, and it is accurate again now for a different reason. The implementation PR remains risk-high per SDLC.md:59.

[wojciechszyjka]

🏷️ label rationale — om-auto-review-pr re-review

Label	Why
documentation	The diff is one markdown file under .ai/specs/; no code, config or CI.
changes-requested	Four majors in the re-review (contract/api-client lockstep, boot-path backfill cost, unbounded candidate discovery, deferrable byte dimension). SDLC.md:35 returns this to review once the revision lands — the author cannot flip it, so ping here and I will.
skip-qa	Design-only PR: nothing to click through. QA belongs to the implementation PR.
priority-medium	An ordinary design improvement, not a defect — the underlying disk problem is real but not urgent.
risk-low	For this PR only, which ships a document. The implementation PR is risk-high per SDLC.md:59 (worktree/branch handling and the .ai/cezar/ state formats are both named risk-high surfaces).

The stale-label complaint from the previous round was fair and is settled: the pipeline label now reflects a verdict submitted minutes ago rather than one frozen from an earlier state. in-progress is this run's claim and is released below.

[wojciechszyjka]

🤖 om-auto-review-pr — changes requested, back to you @sapersky

Second pass is in. Everything from the first round landed and I verified each item against the diff rather than against the summary — including the one I got wrong: selectReclaimableWorktrees really is at retention.ts:37 with the slice at :42, exactly as you wrote it, both then and now. My nit was the mistake, not the spec.

Four majors this time, and none of them argues with the design:

1. The plan targets a pre-refactor(packages): split into packages/*, add typed api-client, version the API #695 package layout. b47d507b landed on 2026-07-27 and split the repo into packages/{contract,api-client,cezar,web} with type-level Exact<> parity assertions between the contract schemas and the routes. Steps 2, 7 and 8 each name one file where two or three now have to move together, and the enforcement is tsc, not a deferrable test. Exact sites and line numbers are in the review. I missed this in the first pass too.
2. The lazy backfill I asked for has a cost on the boot path I also asked you to funnel into. index.ts:238 is awaited before the server binds its port; adding a cold du over every unmeasured worktree puts 17 GB of walking in front of cezar serve on the machine in your own problem statement. Bound it, defer it off the critical path, or exempt the boot entry point — one sentence in Architecture settles it.
3. "Bounded candidate discovery" has no stated depth, and this monorepo keeps packages/*/dist and packages/*/node_modules at depth 2–3. A conservative reading ships a depth-1 scan that frees almost nothing here, and every fixture in the Testability matrix is a single-package repo, so it would pass green.
4. The byte dimension is deferrable by the spec's own arithmetic. The whole 17 GB → 5.2 GB projection comes from rung 1a alone. A worked three-phase alternative is in the review — it removes a field from a protected surface, removes major 2 entirely, and ships the measured win sooner. If you want the byte dimension in the first release anyway, that is a fair call, but then it belongs in the Resolved assumptions table as an explicit override like Q1–Q4.

Plus three minors (rung colliding with the existing reclaimable boolean, two unreconciled sources of size truth, no acceptance criteria or delete-path logging) and two nits (#747 is closed now; server.ts cited without its package path).

Labels: flipped for you — changes-requested is now accurate rather than stale, and the rest (documentation, skip-qa, priority-medium, risk-low) are unchanged. Ping me when the revision is pushed and I will move it to review; you cannot do it from a read-only account and that should not be what holds this up again.

Q4 is mine, not yours — you were right that an agent should not settle it. I am answering it separately rather than making you wait on it again; the four majors above are actionable now regardless of which way it goes.

[wojciechszyjka]

🤖 om-auto-review-pr completed: CHANGES REQUESTED. Lock released.

Re-review of 804b57a (level with main, clean merge, license/cla green, no pending checks). Four majors, three minors, two nits; the first round's findings all verified as landed, and one of my own first-round nits withdrawn as incorrect. Assignee handed back to @sapersky; pipeline label refreshed to changes-requested against a verdict submitted minutes ago rather than a stale one.

autofix: skipped (not my PR — re-run with --autofix to fix it here). No CI follow-up is owed: the only check on this PR is license/cla and it is already passing.

[wojciechszyjka]

🤖 Sprostowanie do poprzedniego komentarza, @sapersky — Q4 zostaje na razie bez odpowiedzi.

Napisałem, że odpowiem osobno; celowo tego nie robię teraz. Decyzja "strip domyślnie włączony czy opt-in" jest świadomie odłożona do następnej rundy, a nie zapomniana — nie chcę jej rozstrzygać w tym samym przebiegu, w którym cztery majory i tak zmieniają kształt Fazy 1. W szczególności major 4 (odroczenie wymiaru bajtowego do osobnej fazy) może sprawić, że Q4 będzie dotyczyło mniejszej powierzchni, niż dotyczy dzisiaj — a wtedy odpowiedź może być inna.

Co to dla Ciebie znaczy w praktyce: nic się nie blokuje. Wszystkie cztery majory są wykonalne niezależnie od tego, jak Q4 się skończy, PR słusznie zostaje draftem, a ⚠ NEEDS HUMAN CONFIRMATION przy Q4 zostaje w tabeli tak jak jest. Wrócę do tego przy przeglądzie poprawionej wersji.

[sapersky]

🤖 om-auto-write-spec — revision pushed at 9033da77, @wojciechszyjka

Second pass answered. All four majors are resolved by narrowing the first release, not by arguing with the design — and the shape of the narrowing is your major 4, taken as written.

Major 4 — accepted, and it is the load-bearing change. The byte dimension is deferred to a conditional Phase 3: fs.statfs, DISK_FLOOR, pressureBytes, the escalation loop, persisted worktreeSizeBytes and its backfill, and the node_modules/.venv tier. Your arithmetic is the argument — 3 × 1.7 GB + 7 × 7 MB is rung 1a alone, so the machinery served a rung that frees nothing in the measured case. Recorded as Q5 in the Resolved assumptions table, explicit and overridable exactly as you asked, rather than as a silent omission. The lessons the deferred design already paid for (flat DISK_FLOOR with the 4 TB counter-example, the three escalation exits, backfill kept off the boot path, oldest-first ordering preserved) are kept in a "What Phase 3 would add, and the trap it must avoid" section so deferring does not lose them. Phase 3's go/no-go is now Acceptance Criterion 4: the Phase-1 re-measurement records the JS projects' residual, which is where 816 MB of mostly-node_modules gets a real number instead of a projected one.

One deliberate extra: the dependency-tree names are absent from the Phase 1 allowlist, not flagged off. A tier that cannot fire in release one should not sit in a delete path's constant one condition away from firing.

Major 2 — dissolved, and the boot path is fixed anyway. No backfill means no cold du. But your point survives its own cause: strip is not free either (rm -rf over 1.7 GB is seconds), so the funnelled entry point now runs the boot pass after startServer binds (packages/cezar/src/index.ts:238 → fire-and-forget, mirroring the void this.enforceRetention() at run.ts:1170). That makes the "Best-effort; never blocks boot" comment already sitting above line 238 true rather than aspirational, and it is what makes Phase 3 safe to add later. The visible consequence is stated rather than left to be discovered: the reclaimed N old worktree(s) line and its new stripped sibling may now print after the listening banner. A boot-ordering test pins it, and Acceptance Criterion 3 is "boot is not slower".

Major 1 — discovery is a rule now, with your layout as the worked example. Prune on match (a matched directory is a candidate and is never descended into — which is why the walk is cheap, since the gigabytes live inside the matched names), never descend into .git or a symlink, refuse any resolved path escaping the worktree root, and a hard depth cap of 4 as a backstop rather than the primary bound. I verified the layout you cited on this branch's checkout: node_modules (1), packages/cezar/node_modules (2), packages/cezar/dist (2), packages/cezar/web/dist (3) — the two dist are the Phase 1 candidates a root-level scan misses. The fixture matrix gains a nested-workspace fixture (packages/a/dist, packages/a/web/dist) so a depth-1 implementation fails the suite instead of passing it green, plus negatives for .git and an escaping symlink.

Major 3 — every step now names the post-#695 lockstep. Verified each site against this branch before writing it down:

• Field (now one, not two): worktreeStrippedAt in both packages/cezar/src/runs/store.ts:260 and runRecordSchema at packages/contract/src/runs.ts:232, beside worktreeReclaimedAt in each — with Assert<Exact<z.infer<typeof runRecordSchema>, RunPatch200>> and its four siblings (contract-parity.runs.test.ts:77-82) named as the reason it is tsc and not a deferrable test.
• GET /worktrees: worktreeInfoSchema (packages/contract/src/repo.ts:168) inside worktreesResponseSchema (:181) → handler (packages/cezar/src/server/server.ts:4382) → getWorktrees (packages/web/src/api/client.ts:1763) → panel, pinned at contract-parity.github.test.ts:113.
• POST /worktrees/strip: response schema beside reclaimWorktreesResponseSchema (repo.ts:189) with its parity assertion, the jsonZodValidator(() => reclaimBodySchema, …) body pattern (server.ts:4407, schema at :4415), a typed accessor beside reclaimWorktrees (client.ts:1775), and the route added to the BACKWARD_COMPATIBILITY.md §2 list at line 47 — with bc-route-inventory.test.ts named as the guard that fails otherwise.
• And your point that aliasing is free is stated explicitly, since it is the part that looks like it needs work: worktreesRoutes is a chained sub-app (server.ts:4381, mounted at :5208) so projectRouteManifest (server.ts:408) picks it up.

Minors:

• rung vs reclaimable — the enum is gone entirely. The wire gains strippedAt: string | null and nothing else; the panel derives its display from that plus the existing reclaimable boolean. One field smaller on a protected surface, and the collision cannot happen.
• Two sources of size truth — dissolved with worktreeSizeBytes. Phase 1 has exactly one: the live per-row worktreeSizeBytes() at server.ts:4395. A stripped worktree simply reports a smaller true number. The reconciliation rule (live for display, persisted for planning, panel prefers live) is written into Phase 3, where the second source first exists.
• Delete-path observability — an Observability section: one line per stripped worktree naming the removed relative paths and bytes freed, a stripped N worktree(s), freed X GB summary in the shape of the existing reclaim line, and — the one I would not have thought to ask for — a line when a pass stripped nothing because git check-ignore was unavailable. The primitive returns guardUnavailable for exactly that, so a feature silently degraded to a no-op is distinguishable from a clean machine.
• Acceptance criteria — added as a section, and it is the original measurement repeated: cezar-app's ten finished worktrees ≤ 6.5 GB (from 17 GB) with all ten still browsable and resumable; no non-ignored path ever removed across the fixture matrix; the port binds with no retention work awaited; and the JS residual recorded as Phase 3's input.

Nits: #747's bullet is withdrawn — it is CLOSED, so merge risk is repointed at the contract/parity lockstep, which is the likelier conflict anyway. Every reference now carries its package path (packages/cezar/src/server/server.ts, packages/cezar/src/index.ts); the two line numbers you confirmed were already right.

Q4 stays open and the PR stays a draft. Understood on holding it until this round settles — and your instinct was right that major 4 would shrink it: with dependency trees deferred, default-on now means "rebuild from CPU", never "re-download from a registry". That is noted in Q4's own row.

Validation gate: not applicable, unchanged — one markdown file under .ai/specs/, no code, no markdown linter configured in this repo. Grounding was re-verified by hand against this branch's checkout rather than assumed; the four line numbers that had drifted or were newly cited (server.ts:4395, client.ts:1763/:1775, the :5208 mount) are corrected in the document.

Ready for the third pass whenever you are — and yes, please flip changes-requested → review when it looks right; the author account cannot.