@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/time-runtime/time-batch-guard.ts

@@ -4,316 +4,111 @@ import { time_call_identity } from './time-call-identity'
 import { time_spans, type Span } from './time-spans'
 import { time_transcript_line } from './time-transcript-line'
 
-// Whether the call about to go out should be refused because the run has stopped batching
-// (joshuafolkken/kit#1390).
+// Whether the call about to go out should be refused because the run has stopped batching. What a
+// call is and what a single-call sequence is are `time-bundle-call.ts`'s and `time-bundles.ts`'s
+// answers — the same modules the end-of-run report uses — so the guard never disagrees with it.
 //
-// Two mechanisms already exist and neither moved the number. joshuafolkken/kit#1304 distributed the
-// norm as prose; joshuafolkken/kit#1329 and joshuafolkken/kit#1337 put the density in front of the run
-// while it was still going. Three consecutive runs measured 1.10–1.12 calls per round trip against a
-// 1.50 floor, with 14–27 of every hundred round trips recoverable (joshuafolkken/kit#1344). What is
-// left is not another way to *say* it: it is intervening in the decision itself.
+// A `PreToolUse` hook cannot see the size of the turn it interrupts (later `tool_use` lines arrive
+// seconds afterwards), so it decides on closed history alone; a refusal of a turn that was going to
+// batch is a false positive costing one round trip.
 //
-// **The judgement is `time-bundle-call.ts`'s and `time-bundles.ts`'s, not a second one.** Whether a
-// call is bundleable, what it names, and what counts as a run of single-call turns are already
-// decided — by the very modules the end-of-run report is computed from. A guard with an opinion of its
-// own would refuse calls the report then says were fine, and the Issue's own verification step reads
-// that report.
-//
-// ## What it cannot know: the size of the turn it is interrupting
-//
-// **A `PreToolUse` hook cannot tell a batched turn from a single-call one, and no field in the
-// transcript can be made to say.** Claude Code writes one line per content block and starts the first
-// tool as soon as that block parses — measured on a live session, the later `tool_use` lines of one
-// message arrive **1.4 to 15 seconds afterwards**. So at the instant the first call of a turn is
-// judged, the turn looks single-call whatever it will turn out to be. `stop_reason` is no help: every
-// line of a message carries the finished message's value, including the `thinking` line written before
-// any tool ran, so it says nothing about how much of the message exists yet.
-//
-// **The guard therefore decides on closed history alone** — the run of single-call turns already
-// behind it — and the refusal lands on the first call of the turn that follows. Where that turn was
-// going to batch, the refusal is a false positive costing one round trip, which is the price
-// joshuafolkken/kit#1390 named and accepted before this was built.
-//
-// **Reading the count anyway would have been worse than not reading it.** `time_density.last_turn_calls`
-// answers exactly this question after the fact, and calling it here returns `1` for every turn — so a
-// guard written against it would refuse the first call of every batched turn while reporting that it
-// had checked. That is the first call of the very behavior this exists to produce, punished with a
-// verdict nobody could see was empty.
-//
-// ## The refusal cannot repeat on the call in hand, but it does repeat as the run keeps single-calling
-//
-// A refusal repeating on the *same call* would wedge a run, and that is made structurally impossible in
-// two ways. The caller records when it last fired, and the immediate re-look never re-fires: a call the
-// run answered by re-issuing it unchanged is found on a refused span in the tail (`is_reissued_refusal`)
-// and let through, so a turn can have at most one of its calls refused.
-//
-// **What used to follow from the record was silence for the rest of the run, and kit#2164 is what ends
-// that.** The old rule fired only where the open sequence *began* after the last firing — and a run that
-// ignored the refusal and kept single-calling never started a new sequence, so it was never spoken to
-// again. Measured across every run, that came to one refusal per run against thousands of turns. The
-// rule now fires the first time a run of single-call turns reaches the limit, and then **again every
-// `REFIRE_EVERY` further single-call turns** it keeps issuing: `is_sequence_at_limit` counts the closed
-// single-call turns since the last firing and re-fires once that count reaches the interval. A new
-// sequence — the run batched, then lapsed again — is a first firing of its own, exactly as before.
-//
-// **The re-fire cannot wedge**, for the same reason the first firing cannot: each re-fire refuses a
-// *different* call than the one already on a refused span, and a call the run re-issues unchanged after a
-// re-fire is let through by `is_reissued_refusal` just as the first refusal's re-issue is.
-//
-// **And the caller must fail toward allowing.** With no instant on record every sequence looks new, so
-// a caller that cannot record the refusal must not make it. `scripts/hooks/batch-guard.ts` states that half.
-
-// How many consecutive single-call turns are allowed before one is refused. **Three, from the
-// measurement rather than from taste**: joshuafolkken/kit#1344 found the longest bundleable sequence
-// of each run at 3–5 turns, so refusing at the third catches most sequences while they still have
-// turns left to save. Four or more gives most of them back; two would refuse the ordinary pair a
-// person would never call a defect.
+// It fires when a sequence first reaches the limit, then every `REFIRE_EVERY` further single-call
+// turns, and never twice on the same call: an unchanged reissue is let through (`is_reissued_refusal`).
+// A caller that cannot record the refusal must not make it (`scripts/hooks/batch-guard.ts`).
+
+// The longest bundleable sequence measured at 3–5 turns, so refusing at the third still saves turns.
 const CONSECUTIVE_LIMIT = 3
 
-// **How many further single-call turns pass between one firing and the next, once a run keeps
-// single-calling after being spoken to** (joshuafolkken/kit#2164). This is the `N` the acceptance
-// criteria name, and it lives here as a single constant. Before this the guard fired once per unbroken
-// run of single-call turns and then went silent — a run that ignored the first refusal and kept issuing
-// single calls was never spoken to again, so over thousands of turns the guard delivered one notice. The
-// re-fire turns that back into steady pressure: the same `CONSECUTIVE_LIMIT` cadence the first firing
-// used, applied again from the last firing, so the reminder recurs every three continued single-call
-// turns rather than once. It is deliberately not more frequent than the initial limit — a shorter
-// interval would refuse a run that is only two single calls past a reminder it just answered.
+// Not tighter than the first limit, so a run just past an answered reminder is not refused again.
 const REFIRE_EVERY = CONSECUTIVE_LIMIT
 const ONE_TURN = 1
 const NONE = 0
 
-// **The notice's own re-fire interval, and the `N` joshuafolkken/kit#2276 measured as too long.** A
-// refusal that fired every single-call turn would refuse a run only one call past a reminder it just
-// answered, so `REFIRE_EVERY` holds the refusal at the initial limit. **A notice cannot wedge** — the
-// call proceeds either way — so nothing makes the notice pay that caution, and #2164 reusing the
-// refusal's three-turn cadence for it is why a lane child single-calling was nudged only once per three
-// mistakes. This is a single constant, the one the acceptance criteria name, kept apart from
-// `REFIRE_EVERY` so the refusal's cadence and the notice's cannot drift into one number that is wrong
-// for one of them.
+// A notice cannot wedge (the call proceeds), so it recurs every turn; kept apart from `REFIRE_EVERY`.
 const NOTICE_REFIRE_EVERY = ONE_TURN
 
-// **How many of the most recent single-call turns the notice names** (joshuafolkken/kit#2276). #2164's
-// notice ended at "batch what follows" and named no call, and the density did not move; naming the
-// concrete calls the run just issued one-per-turn is the untried half of "why it did not work" — a
-// reader shown *these three reads had no dependency* has something to act on that "batch more" never
-// gave. Three, so the notice carries the sequence that tripped the limit without growing the per-turn
-// context it rides on.
+// Naming the concrete calls gives the reader something to act on that "batch more" does not.
 const NAMED_CANDIDATE_COUNT = 3
 
-// **The turns already closed, so the one being interrupted is not among them.** A span exists only
-// once its result has come back, and the call being judged has not run yet — so a sequence of
-// `CONSECUTIVE_LIMIT - 1` closed turns is the state in which the next call would make the third.
+// The call being judged has not closed, so `CONSECUTIVE_LIMIT - 1` closed turns means it makes the limit.
 const SEQUENCE_BEFORE_LIMIT = CONSECUTIVE_LIMIT - ONE_TURN
 
-// The call about to go out, named the way the hook payload names it. A record rather than two
-// parameters so the tool and its input cannot be handed over in the wrong order — both are strings on
-// the caller's side often enough for that to compile.
+// A record so the tool and its input cannot be handed over in the wrong order.
 interface GuardedCall {
 	name: string
 	input: unknown
 }
 
-// What naming a call reads off it — a closed turn's span or the call in hand alike, so the live density
-// line can name the call that has just run beside the turns behind it (joshuafolkken/kit#3157).
+// A closed turn's span or the call in hand alike.
 type NamedCall = Pick<Span, 'is_bundleable' | 'is_writing' | 'label' | 'targets'>
 
-// **A write is refusable, and the exclusion that said otherwise is gone** (joshuafolkken/kit#1762).
-// Read over 19 recorded runs, 261 of 1,737 round trips (15.0%) were recoverable by batching and **184
-// of them (70.5%) were writes** — 158 `Edit` alone. The refusal's own text has always said the rule
-// covers them ("edits are covered exactly as reads are"); the implementation had not caught up, so the
-// largest single contributor to the waste was the one party the guard could never reach.
-//
-// **Two different things were rejected before this, and separating them is what unblocked it.** What
-// was rejected on measured cost is *widening the hook's matcher and nothing else*: a matcher naming
-// `Edit` in front of an `is_guarded_call` that answers `false` for every write starts a process that
-// can only ever answer "allow". That reasoning is sound and is untouched — the predicate is widened
-// first, so the matcher now reaches a question that has an answer. What was **not** rejected, because
-// nobody had proposed it, is making a write refusable at all; "buy nothing a refusal could use" was a
-// consequence of the exclusion below it rather than a ground of its own.
-//
-// **The safety objection was real, and it is narrowed rather than dismissed.** Claude Code denies one
-// call of a turn and runs the rest, so a refused edit leaves its siblings applied and itself not, and
-// the reissue can meet text that has moved under it. `depends_on_sequence` below closes the half that
-// is visible: it withholds the refusal whenever the call in hand shares a target with the sequence
-// behind it, writes included, so an edit to a file the run has already been rewriting is never
-// refused.
-//
-// **The half it cannot close is the turn it is interrupting** — for the reason stated above, no field
-// in the transcript says what else that turn issued. Three edits to one file batched into a single
-// turn can therefore have their first refused while the other two apply. **The bound is that this
-// surfaces rather than corrupts**: a refusable write is content-addressed — an `Edit` carries the
-// `old_string` it was written against, an in-place `sed` a pattern — so a reissue either applies where
-// it was meant to or fails to match and is reported. So the residual cost is one round trip in the
-// ordinary case and a failed edit the run must redo in this one — the same false-positive price
-// joshuafolkken/kit#1390 named and accepted for reads, now paid on the calls that carry most of the
-// waste instead of only on the calls that carry the rest.
-//
-// **The dispatch it adds is measured, and it is not the figure the deleted text quoted.** One hook run
-// is **0.53 s** in this checkout and about 0.4 s in a consumer, essentially all of it process startup —
-// measured under `docs/josh-commands-automation.md` → "`josh format:edited`", which is where that reading was
-// taken. The "about 2.4 s" above was a `pnpm josh` dispatch measured before joshuafolkken/kit#1342 made
-// this command eligible for the in-process path. Against that, one recovered round trip is a whole
-// model turn.
-//
-// **The matcher is settings a consumer can widen, so what a call is stays this module's answer.**
-// `is_guarded_call` is the guarantee and `.claude/settings.json` is the wiring; the two are kept apart
-// so a consumer editing the second cannot change the first.
-//
-// **What a call *is* lives in `time-bundle-call.ts`** since joshuafolkken/kit#1509, beside the rest of
-// it, because the sequence builder needs the same answer and a second copy here is what let the two
-// disagree — the builder had no way to ask at all, so it read a run of edits to one file as a chain of
-// dependent calls and no sequence ever formed.
-
-// One line, and it says four things: what happened, what to do instead, where the rule is written, and
-// what to do when the turn was already batching or the call really is alone. **The last of those is not
-// a loophole, it is the honest half** — the guard cannot see the turn it interrupted, so a reader told
-// only to batch would batch something that already was.
+// Writes are refusable — they were most of the recoverable round trips. A refused edit leaves its
+// siblings applied, but a refusable write is content-addressed, so a reissue either applies or fails
+// loudly; `depends_on_sequence` withholds the refusal where the call shares a target with the sequence.
+
+// The three texts carry the action and a pointer; the criterion's reasoning and measured cost stay
+// at the pointer, so a firing does not re-bill the rule body.
+const RULE_POINTER = '`prompts/collaboration-workflow/turn-batching.md`'
+const STREAK = `${String(CONSECUTIVE_LIMIT)} single-call turns in a row`
+
+// Includes what to do when the turn was already batching — the guard cannot see the turn it interrupted.
 const REASON =
-	`⛔ batching: the last ${String(SEQUENCE_BEFORE_LIMIT)} turns each issued a single tool call, so ` +
-	`this one would make ${String(CONSECUTIVE_LIMIT)} in a row. Reissue it in one turn together with ` +
-	`the calls meant to follow it that do not need its result. **The criterion is whether this call's ` +
-	`input needs another call's result, not what kind of call it is** — edits are covered exactly as ` +
-	`reads are, and it never authorizes weakening a verification gate or a review: fewer turns, never ` +
-	`less work. The rule, and where its measured cost and rejected mechanisms are, is in ` +
-	`\`prompts/collaboration-workflow/turn-batching.md\`. If this turn was already batching, or the call ` +
-	`genuinely has nothing to go beside it, reissue it as it was: this fires once per run of ` +
-	`single-call turns and cannot repeat on the call in hand.`
-
-// The notice a whole-file write earns instead of the refusal above (joshuafolkken/kit#1848). It says
-// the same thing REASON does — reissue the calls that do not need each other in one turn — but as a
-// **notice, not a refusal**: the write proceeds, because a `Write` cannot be refused safely (see
-// `WHOLE_FILE_WRITE_TOOL` below). The honest half is here for the same reason it is on REASON — the
-// guard cannot see the turn it is interrupting, so a reader told only to batch would batch a turn that
-// already was. It carries no ⛔, so a person watching reads it as advice rather than a stop.
+	`⛔ batching: ${STREAK}. Reissue this with the calls that do not need its result — the test is ` +
+	`whether a call's input needs another call's result, not what kind of call it is (edits are covered ` +
+	`exactly as reads), and it never authorizes weakening a verification gate or a review. Already ` +
+	`batching, or nothing to pair? Reissue it unchanged; this fires once per streak. ${RULE_POINTER}`
+
+// A whole-file write earns a notice, not a refusal: a `Write` cannot be refused safely.
 const NOTICE =
-	`💡 batching: the last ${String(SEQUENCE_BEFORE_LIMIT)} turns each issued a single tool call, so ` +
-	`this Write makes ${String(CONSECUTIVE_LIMIT)} in a row. This is a notice, not a refusal — the ` +
-	`write proceeds. Where the writes meant to follow it do not need its result, issue them in one turn ` +
-	`together. **The criterion is whether a call's input needs another call's result, not what kind of ` +
-	`call it is** — it never authorizes weakening a verification gate or a review: fewer turns, never ` +
-	`less work. The rule, and where its measured cost and rejected mechanisms are, is in ` +
-	`\`prompts/collaboration-workflow/turn-batching.md\`. If this run was already batching, or the write ` +
-	`genuinely has nothing to go beside it, carry on: this recurs every ` +
-	`${String(NOTICE_REFIRE_EVERY)} further single-call turn(s).`
-
-// The notice a *refusable* call earns instead of its refusal when the run is a dispatched lane child
-// (joshuafolkken/kit#2164). A headless `claude -p` child ends its turn on a denial, so the batching
-// guard cannot refuse there — but the guidance is exactly as useful, so it is delivered as a notice: the
-// call proceeds, and the model is told to batch what follows. It carries no ⛔, so a person watching
-// reads it as advice rather than a stop, and it says the reminder recurs so a child that keeps
-// single-calling knows the pressure is steady rather than spent.
-const LANE_NOTICE =
-	`💡 batching: the last ${String(SEQUENCE_BEFORE_LIMIT)} turns each issued a single tool call, so ` +
-	`this one makes ${String(CONSECUTIVE_LIMIT)} in a row. This is a notice, not a refusal — the call ` +
-	`proceeds, because a dispatched lane child ends its turn on a denial. Where the calls meant to follow ` +
-	`it do not need its result, issue them in one turn together. **The criterion is whether a call's ` +
-	`input needs another call's result, not what kind of call it is** — it never authorizes weakening a ` +
-	`verification gate or a review: fewer turns, never less work. The rule, and where its measured cost ` +
-	`and rejected mechanisms are, is in \`prompts/collaboration-workflow/turn-batching.md\`. If this run was already ` +
-	`batching, or the call genuinely has nothing to go beside it, carry on: this recurs every ` +
-	`${String(NOTICE_REFIRE_EVERY)} further single-call turn(s).`
-
-// The one write that is never refused, because it is the one whose reissue is **unconditional**. Every
-// other refusable write is content-addressed and so fails loudly when its turn's siblings moved the
-// text under it; a `Write` carries the whole file, so reissuing it re-applies content composed before
-// those siblings ran and overwrites an applied edit with no error anywhere. **A turn holding a `Write`
-// and an `Edit` of one file is a shape a run actually produces** — create it, then adjust it — which is
-// what separates this from a truncating shell redirect, where the colliding turn would have to hold two
-// writers of one path and is not a shape that occurs.
-//
-// **It is not the blanket exclusion joshuafolkken/kit#1762 removed.** That one turned away every write
-// for being a write; this turns away one tool because a false positive on it cannot surface. `Edit` —
-// 164 of the 251 recoverable round trips against `Write`'s 37, read over 20 runs — is untouched, and
-// the matcher leaves `Write` out for the cost reason above rather than relying on this line alone.
+	`💡 batching: ${STREAK}; the Write proceeds. Issue the writes that do not need its result in one ` +
+	`turn, never by weakening a gate or a review. ${RULE_POINTER}`
+
+// A headless lane child ends its turn on a denial, so a refusable call there earns a notice instead.
+// It recurs every single-call turn, so it is kept to one line.
+const LANE_NOTICE = `💡 batching: ${STREAK}; the call proceeds. Pair independent calls. ${RULE_POINTER}`
+
+// Never refused: its reissue overwrites an applied sibling edit with no error anywhere.
 const WHOLE_FILE_WRITE_TOOL = 'Write'
 
-// The one tool the write-side fold names (joshuafolkken/kit#2366). A span's label is its tool name for
-// everything but Bash (`time-spans.ts`), so this is how a recent single-call turn is read as an edit
-// that `edit:files` could fold — distinct from `Write`, which this command cannot content-address.
+// The one tool the write-side fold names; `Write` cannot be content-addressed by `edit:files`.
 const EDIT_TOOL = 'Edit'
 
-// Whether this call is one the guard could ever refuse, asked before any transcript is read. **The
-// caller uses it to skip that read**: a quarter-megabyte read inside a hook that holds every call is
-// not worth paying on a `pnpm josh` invocation the answer can never be about.
-//
-// **Bundleable is the whole test, because the criterion is dependency and not the kind of call.** The
-// `may_write` term that used to sit beside it excluded the 70.5% of recoverable round trips that are
-// writes (joshuafolkken/kit#1762). What keeps a write that genuinely cannot be refused safe is
-// `depends_on_sequence`, which reads the targets, rather than a blanket exclusion here.
+// Asked before the transcript is read, so the hook skips the read for calls it can never refuse.
+// Bundleable is the whole test — the criterion is dependency, not the kind of call.
 function is_guarded_call(call: GuardedCall): boolean {
 	if (call.name === WHOLE_FILE_WRITE_TOOL) return false
 
 	return time_bundle_call.call_facts(call.name, call.input).is_bundleable
 }
 
-// The counterpart to `is_guarded_call` for the one tool it turns away: the whole-file write is the
-// call the guard **notifies** about rather than refuses (joshuafolkken/kit#1848). It cannot be refused
-// safely — its reissue overwrites an applied sibling in silence — yet a run of single-call `Write`
-// turns was the largest recoverable contributor the refusal could never reach, so the notice carries
-// the rule to it without the false-positive cost. `.claude/settings.json` names `Write` in the matcher
-// so the hook is even reached, exactly as the predicate is what makes the matcher's answer non-empty.
 function is_notice_call(call: GuardedCall): boolean {
 	return call.name === WHOLE_FILE_WRITE_TOOL
 }
 
-// The same question narrowed to calls that write nothing — the test `is_guarded_call` used to be, kept
-// under a name that says what it asks rather than deleted. **`scripts/delegation/investigation-reads.ts`
-// is its caller**, and it needs this answer rather than the one above: it refuses a `Bash` line only
-// where that line is unambiguously a read, so an in-place `sed` stays outside its reach even now that
-// the batching guard can refuse one. Widening the single predicate in place would have loosened that
-// guard silently, which is the one way this change could have gone wrong without a test noticing.
-//
-// **`may_write`, not `is_writing`** — this is a refusal test, and it is the one that has to over-call.
-// The dependency test reads the other field, which may not (joshuafolkken/kit#1509).
+// For `investigation-reads.ts`, which refuses only unambiguous reads. `may_write` over-calls, as a
+// refusal test must.
 function is_read_only_call(call: GuardedCall): boolean {
 	const facts = time_bundle_call.call_facts(call.name, call.input)
 
 	return facts.is_bundleable && !facts.may_write
 }
 
-// **A shared target is a dependency, and it is what keeps the guard off the search-then-read pair.**
-// `time-bundles.ts` treats two calls naming the same path — or one naming a directory the other reads
-// inside of — as ordered, and reuses that test here so a call the report would never have counted as
-// recoverable is never refused either.
-//
-// **It asks for the shared target alone, where `time_bundles.is_dependent` exempts a write following a
-// write, because the two are answering different questions** (joshuafolkken/kit#1762). The builder asks
-// "could these two have gone out together", and for two edits to one file the answer is yes — that
-// exemption is what lets such a stretch form a sequence at all (joshuafolkken/kit#1509). This asks "is
-// refusing this one safe", and there the same pair is the one case where it is not: the siblings of a
-// refused edit still run, so an edit naming a file the run is already rewriting comes back to text that
-// has moved under it. Both sides read `shares_target`, so there is one definition of what sharing a
-// target means and two uses of it rather than a second copy.
+// A shared target is a dependency. Unlike `time_bundles.is_dependent`, a write after a write is not
+// exempt: refusing an edit to a file the run is rewriting would reissue against moved text.
 function depends_on_sequence(sequence: ReadonlyArray<Span>, facts: BundleFacts): boolean {
 	return sequence.some((span) => time_bundles.shares_target(span.targets, facts.targets))
 }
 
-// The instant the open sequence began, as far as the window shows. An empty sequence answers `NONE`,
-// and `NONE` is never greater than a recorded refusal — so the length test in `is_sequence_at_limit` is
-// what admits a run's first firing, and this decides only whether that firing is the sequence's first.
-//
-// **Both sides of that comparison are the same machine's wall clock**: the transcript's timestamps and
-// the instant the caller recorded. A clock that jumped backwards makes a record read as later than
-// every sequence, which withholds the firing — the safe direction, and the one every other failure here
-// takes too.
+// A clock that jumped backwards withholds the firing — the safe direction.
 function sequence_started_ms(sequence: ReadonlyArray<Span>): number {
 	return sequence[0]?.ended_ms ?? NONE
 }
 
-// How many of the open sequence's closed single-call turns ended after the last firing. For a run whose
-// last firing predates this sequence every turn counts; for one already spoken to inside this sequence
-// only the turns issued since count — which is what the re-fire interval is measured against.
 function turns_since(sequence: ReadonlyArray<Span>, last_fired_ms: number): number {
 	return sequence.filter((span) => span.ended_ms > last_fired_ms).length
 }
 
-// **The firing test, first-time and re-fire in one** (joshuafolkken/kit#2164). The length and dependency
-// gates are unchanged. What changed is the instant comparison: where a firing predates the open
-// sequence it is that sequence's first, so the length gate alone decides it; where the run has already
-// been spoken to inside this sequence, it re-fires only once `REFIRE_EVERY` further single-call turns
-// have closed since. The old rule kept only the first branch, which is why it fell silent for the rest
-// of a run that kept single-calling.
+// A firing before the open sequence makes this its first; inside it, re-fire every `refire_every` turns.
 function is_sequence_at_limit(
 	sequence: ReadonlyArray<Span>,
 	facts: BundleFacts,
@@ -327,14 +122,8 @@ function is_sequence_at_limit(
 	return turns_since(sequence, last_fired_ms) >= refire_every
 }
 
-// **Nothing here reads the turn the call belongs to**, because nothing can: see "What it cannot know"
-// above. The two call-shaped tests are asked of the call in hand, and everything else of the turns
-// behind it.
-// The sequence test both dispositions share, over spans the caller has already parsed: is the open run
-// of single-call turns at the limit, for a call that began after the last time this disposition fired.
-// Shared so the refusal and the notice cannot drift apart on what "three in a row" means
-// (joshuafolkken/kit#1848), and taking spans rather than the tail so a disposition that also asks
-// `is_reissued_refusal` parses the transcript once (joshuafolkken/kit#1979).
+// Shared by the refusal and the notice so they agree on "three in a row"; takes parsed spans so the
+// transcript is parsed once.
 function is_at_limit(
 	spans: ReadonlyArray<Span>,
 	call: GuardedCall,
@@ -349,25 +138,11 @@ function is_at_limit(
 	)
 }
 
-// This guard's own refusal label, as `time-transcript-line.ts` reads it back off a refused result: the
-// token after the ⛔ and before the first colon of REASON. Derived from REASON rather than written a
-// second time, so the two can never disagree about which refusals in the transcript are this guard's
-// (joshuafolkken/kit#1979).
+// Derived from REASON, so the two never disagree about which transcript refusals are this guard's.
 const GUARD_LABEL = time_transcript_line.guard_from_refusal(REASON)
 
-// **A call the guard has already refused, found in the tail by the same identity the report compares
-// re-issues on** (joshuafolkken/kit#1979). A refused call the run answered by re-issuing it unchanged
-// is one that had nothing to batch — refusing the re-issue again buys a round trip and no batching,
-// which is the waste `time-guard-refusals.ts`'s `same_args_reissue` counts. The identity is built
-// through the same `to_tool_call` the transcript parse uses, so a refused span and the live call about
-// to repeat it produce the identical string.
-//
-// **This is what the timestamp alone could not do.** `refused_at_ms` withholds the immediate
-// re-refusal, but an unbroken run of single-call turns longer than the read window presents a sequence
-// start that has moved forward and is refused again (see "What it cannot know" above). The refused span
-// is still in the tail even when that start has scrolled out of view, so its identity is what survives.
-// The first refusal of a novel call still fires — only a call already on a refused span of this guard's
-// is let through, so a genuinely bundleable single call is refused exactly as before.
+// An unchanged reissue of a refused call had nothing to batch, so it is let through. Matched by the
+// same identity the report uses, it survives a sequence start that scrolled out of the window.
 function is_reissued_refusal(spans: ReadonlyArray<Span>, call: GuardedCall): boolean {
 	const identity = time_call_identity.identity_of(
 		time_spans.to_tool_call(call.name, call.input, time_spans.NO_MESSAGE_ID),
@@ -379,9 +154,7 @@ function is_reissued_refusal(spans: ReadonlyArray<Span>, call: GuardedCall): boo
 	)
 }
 
-// `refire_every` defaults to the refusal's cadence so every existing caller reads unchanged; the
-// lane-child downgraded notice passes `NOTICE_REFIRE_EVERY` instead, so a refusable call turned into a
-// notice recurs on the notice's tighter cadence rather than the refusal's (joshuafolkken/kit#2276).
+// The lane-child notice passes `NOTICE_REFIRE_EVERY` to recur on the notice's cadence.
 function should_block(
 	text: string,
 	call: GuardedCall,
@@ -397,11 +170,7 @@ function should_block(
 	return is_at_limit(spans, call, refused_at_ms, refire_every)
 }
 
-// The notice's rule: the same sequence test, gated on the whole-file write rather than on a refusable
-// call. `notified_at_ms` is read from the notice's **own** record, so a notice never spends the
-// refusal's stamp and cannot silence a genuine refusal of a later read or edit on the same run. A
-// whole-file write is never refused, so it has no re-issue to detect — the reissue test is the
-// refusal's alone.
+// `notified_at_ms` is the notice's own record, so a notice never silences a later refusal.
 function should_notify(text: string, call: GuardedCall, notified_at_ms: number): boolean {
 	if (!is_notice_call(call)) return false
 
@@ -410,10 +179,7 @@ function should_notify(text: string, call: GuardedCall, notified_at_ms: number):
 	return is_at_limit(spans, call, notified_at_ms, NOTICE_REFIRE_EVERY)
 }
 
-// One recent single-call turn named the way a reader would recognize it: the tool, and the file it
-// touched where the label does not already carry it (joshuafolkken/kit#2276). `label` is the tool name
-// for a non-shell call and the command for a shell one, so the target is appended only where it adds
-// something the label has not already said.
+// The target is appended only where the label does not already carry it.
 function describe_span(span: NamedCall): string {
 	const target = span.targets[0] ?? ''
 	if (target === '' || span.label.includes(target)) return span.label
@@ -421,17 +187,9 @@ function describe_span(span: NamedCall): string {
 	return `${span.label} ${target}`
 }
 
-// **The fewest reads that a composite call can fold** (joshuafolkken/kit#2311). One path is a single
-// call already, so nothing folds below two — the directive is withheld and the run keeps the guidance
-// alone, exactly as it does when the recent turns were not reads at all.
 const FOLD_MINIMUM = 2
 
-// **The recent single-call turns that were file reads, each named by the one path it read.** A fold
-// needs a *file* path, so three targets are dropped: one that named none (a bare `pwd`), a write (a run
-// of edits has nothing for `read:files` to do), and a directory (`ls scripts/` names `scripts/`, which
-// `read:files` cannot read — it would emit `Cannot read scripts/` and exit 1, so the paste-ready
-// command must never carry it). The directory test is `has_extension` reused from the target scanner,
-// not a second copy. Deduped, so a run that read one file twice folds it once and names it once.
+// File paths only: no target, a write, or a directory (`read:files` cannot read one) is dropped.
 function read_targets(sequence: ReadonlyArray<NamedCall>): ReadonlyArray<string> {
 	const paths = sequence
 		.filter((span) => span.is_bundleable && !span.is_writing)
@@ -441,14 +199,7 @@ function read_targets(sequence: ReadonlyArray<NamedCall>): ReadonlyArray<string>
 	return [...new Set(paths)]
 }
 
-// **The composite-command half of the notice** (joshuafolkken/kit#2311): the single call that folds the
-// recent single-call reads, handed to the run ready to paste. Naming the concrete calls did not move the
-// density (#2276) — the notice still asked the model to *reissue them in one turn*, which is a request
-// for the parallel `tool_use` blocks the model structurally resists. The lever measured to move
-// round-trip density is a composite command that folds a routine section into one call (`read:files`,
-// kit#2202); so the guard now offers *that* command, the one the model can emit in a single turn,
-// rather than another way to say "batch". Below two reads there is nothing to fold, so it is empty and
-// the guidance stands alone.
+// A paste-ready composite command moves density where asking for parallel calls did not.
 function read_fold_directive(sequence: ReadonlyArray<NamedCall>): string {
 	const paths = read_targets(sequence)
 	if (paths.length < FOLD_MINIMUM) return ''
@@ -456,13 +207,7 @@ function read_fold_directive(sequence: ReadonlyArray<NamedCall>): string {
 	return ` Fold them into one call: \`pnpm josh read:files ${paths.join(' ')}\`.`
 }
 
-// **The write-side counterpart of the read fold** (joshuafolkken/kit#2366): the recent single-call
-// `Edit` turns, folded into one `edit:files` call. The read fold pastes a whole command because a read
-// is addressed by its path alone; an edit carries its own text, so the fold names the files and points
-// at the command that applies a plan of edits over them in one call — the composite command the model
-// can emit in a single turn where reissuing the edits as parallel `tool_use` blocks is the shape it
-// resists. Only `Edit` counts: a whole-file `Write` creates content this command cannot content-address,
-// and it earns its own notice already. Below two edits there is nothing to fold.
+// The write-side fold: an edit carries its own text, so it names the files for one `edit:files` plan.
 function write_targets(sequence: ReadonlyArray<NamedCall>): ReadonlyArray<string> {
 	const paths = sequence
 		.filter((span) => span.label === EDIT_TOOL)
@@ -479,8 +224,7 @@ function write_fold_directive(sequence: ReadonlyArray<NamedCall>): string {
 	return ` Fold them into one \`pnpm josh edit:files\` call with a plan over: ${paths.join(' ')}.`
 }
 
-// The calls named, and their folds offered — the text both the refusable-call notice and the live
-// density line carry, written once so the two cannot word the same calls differently.
+// Shared by the notice and the live density line, so both word the same calls alike.
 function name_candidates(calls: ReadonlyArray<NamedCall>): string {
 	if (calls.length === NONE) return ''
 
@@ -490,29 +234,15 @@ function name_candidates(calls: ReadonlyArray<NamedCall>): string {
 	return ` Just issued one per turn, so at least these could have shared a turn: ${named}.${folds}`
 }
 
-// **The concrete half of the notice** (joshuafolkken/kit#2276): the most recent single-call turns,
-// named, so the model is shown the calls it should have batched rather than only told to batch — and,
-// since kit#2311, the one `read:files` call that folds them where they were reads. Parsed from the tail
-// here rather than threaded from `should_notify` because it runs only when a notice actually fires,
-// which is rare enough that the second parse costs less than carrying the spans through the hook's
-// notice contract. An empty sequence names nothing and the notice falls back to its guidance alone.
+// Re-parsed here rather than threaded through: it runs only when a notice actually fires.
 function recent_candidates(tail: string): string {
 	return name_candidates(
 		time_bundles.open_sequence(time_spans.parse_timeline(tail).spans).slice(-NAMED_CANDIDATE_COUNT),
 	)
 }
 
-// **The candidates for a call that has already run** (joshuafolkken/kit#3157): what the `PostToolUse`
-// density line names. A lane child never sees the notice above — kit#2405 turned it `off` there — so
-// the density line is the one batching signal a lane receives, and until this it named nothing. The
-// call in hand is not in the open sequence (its turn has not closed), so it is named after the turns
-// behind it — and it is checked against them with the same shared-target test the refusal uses, so a
-// call that read what the turn before it wrote is never offered as one that could have gone beside
-// it. A call that is not bundleable names no targets, so the shared-target test cannot see what it
-// needs — `pnpm josh gate` after a run of edits reads every one of them — and it is never offered
-// either, exactly as `is_guarded_call` never refuses one. An empty answer means there is no concrete
-// pair to name, and the caller says nothing at all. A call the payload does not name is judged on the
-// closed turns alone.
+// For the `PostToolUse` density line, a lane's only batching signal. The call in hand is named after
+// the closed turns unless it depends on them or is not bundleable; empty means nothing to name.
 function pairing_candidates(tail: string, call: GuardedCall | undefined): string {
 	const sequence = time_bundles.open_sequence(time_spans.parse_timeline(tail).spans)
 
@@ -529,15 +259,10 @@ function pairing_candidates(tail: string, call: GuardedCall | undefined): string
 	return name_candidates([...sequence.slice(ONE_TURN - NAMED_CANDIDATE_COUNT), current])
 }
 
-// **This guard's own name for its once-per-run record.** It lives beside the rule rather than in
-// `batch-guard.ts` because a second module now has to read the same record: `delivered-rules.ts`
-// stands aside for this guard and has to ask whether it has *already* refused, and a second copy of
-// the string is the clone that would let the two disagree about which file they are reading.
+// Here rather than in `batch-guard.ts`: `delivered-rules.ts` reads the same record.
 const STAMP_PREFIX = 'josh-batch-guard-'
 
-// The notice's own record, distinct from `STAMP_PREFIX` so a notice fired on a Write cannot move the
-// instant the refusal reads — the two dispositions dedupe independently, once each per run of
-// single-call turns (joshuafolkken/kit#1848).
+// Separate, so the notice and the refusal dedupe independently.
 const NOTICE_STAMP_PREFIX = 'josh-batch-guard-notice-'
 
 const time_batch_guard = {