@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/run/progress/run-progress.ts

@@ -1,7 +1,7 @@
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 
 // `josh run:progress` — the one line an unattended run prints when it has gone quiet, and the clock
-// that decides when that is (joshuafolkken/kit#1520).
+// that decides when that is.
 //
 // **The trigger is silence, not a timer.** An `epicrun` reports when a child merges or is parked, and
 // a child is 20–46 minutes of wall clock; between those two events it says nothing at all, so the
@@ -10,11 +10,9 @@ import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 // from the last report of *any* kind, so a heartbeat never lands immediately behind a real one, where
 // it would be noise rather than news. `--mark` is how the run tells this clock a real report happened.
 //
-// **A line that could say "still running" is a line not worth printing.** Five minutes was measured in
-// live use on 2026-09-07 and 6 of 15 reports carried no changed number at all, which is the same
-// information as silence. Ten was measured next and was still short of a stage change, so the default
-// is twenty minutes (joshuafolkken/kit#1570): a child measures 20–46 minutes, and twenty gives one to
-// two reports per child rather than a run of lines saying what the last one said. Every field below is
+// **A line that could say "still running" is a line not worth printing.** The default is twenty
+// minutes: a child measures 20–46 minutes, and twenty gives one to two reports per child rather than a
+// run of lines saying what the last one said. Every field below is
 // re-read on each tick rather than remembered — a child's labels, whether a pull request exists yet,
 // which lanes are open, the load average, and how long the whole set has been identical.
 //
@@ -28,20 +26,17 @@ import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 // it prints about a pull request is that one exists and what state GitHub calls it — which is a read
 // it actually performs.
 //
-// **The line also says *when* it was observed, and not only how long the silence had run**
-// (joshuafolkken/kit#1560). A relative figure means something only while the reports keep coming: an
-// `epicrun` suspended overnight resumed and read its own `quiet 11m` as if no time had passed, and
-// concluded the machine's clock was broken when it matched GitHub's `Date` header to the second. Three
-// decisions follow from that, and each is a decision rather than a default:
+// **The line also says *when* it was observed, and not only how long the silence had run.** A
+// relative figure means something only while the reports keep coming: a run suspended overnight would
+// read its own `quiet 11m` as if no time had passed. Three decisions follow from that:
 //
-// - **The date is carried, not just the clock time.** The confusion above happened across a day
-//   boundary, so an `HH:MM` alone would have left the same hole open.
+// - **The date is carried, not just the clock time.** A suspension can cross a day boundary, so an
+//   `HH:MM` alone would leave the same hole open.
 // - **The local clock leads, and UTC is printed beside it.** The local half is the one a person can
-//   act on without converting anything, which is what UTC alone denied a reader seven hours from it
-//   (joshuafolkken/kit#1589). UTC is kept rather than replaced: the line is read from other machines
-//   and from cloud sessions, and joshuafolkken/kit#1245 already paid for a timestamp rendered in the
-//   reader's zone making one process look like a stranger. The printed offset ties the two halves
-//   together, so a reader on a third machine can place both.
+//   act on without converting anything. UTC is kept because the line is read from other machines and
+//   from cloud sessions, where a timestamp rendered in the reader's zone makes one process look like a
+//   stranger. The printed offset ties the two halves together, so a reader on a third machine can
+//   place both.
 // - **It is added beside the elapsed figures, never in place of them.** How long it has been quiet and
 //   when the observation was taken are two different facts, and neither can be reconstructed from the
 //   other without knowing the answer already.
@@ -53,13 +48,16 @@ const INTERVAL_KEY = 'JOSH_PROGRESS_INTERVAL_MINUTES'
 const MS_PER_MINUTE = 60_000
 const MS_PER_SECOND = 1000
 const DEFAULT_INTERVAL_MS = DEFAULT_INTERVAL_MINUTES * MS_PER_MINUTE
+// The switch that silences every progress report — the watcher's and `run:board --every`'s alike.
+const DISABLED_KEY = 'JOSH_PROGRESS'
+const DISABLED_VALUE = '0'
 
 // What one child looked like on this tick. `pr_state` is `run_preflight`'s own vocabulary rather than
 // a second spelling of it — `none` / `open` / `merged` / `closed`.
 interface ChildObservation {
 	issue: string
 	// Kept from the `in-progress` listing the child was read from, so the line cites it in full
-	// (joshuafolkken/kit#2943) without a read per child.
+	// without a read per child.
 	title: string
 	labels: ReadonlyArray<string>
 	pr_state: string
@@ -89,16 +87,15 @@ interface ProgressState {
 }
 
 const NO_LANES = 'none'
-// The children slot when the run has started but no child carries `in-progress` yet
-// (joshuafolkken/kit#1900). It is an observed fact — zero in-progress children — not a guess about
+// The children slot when the run has started but no child carries `in-progress` yet. It is an
+// observed fact — zero in-progress children — not a guess about
 // what will appear: `read_observations` returns an observation at all only because a mechanical record
 // (a lane, a hold, or a carried budget) says a run is underway, and the lanes field beside this one
 // carries whatever evidence exists.
 const NO_CHILD_YET = 'no in-progress child yet'
-// The fifth line's value when there is no scheduled next report. The command always supplies one, so
-// this is the migrated form of the rule `backlogrun.md` used to hold — a line with no `next` field says
-// the field was absent rather than inventing a time (joshuafolkken/kit#2026). `format_report` is a pure
-// renderer, so its contract states the absence rather than assuming a stamp is always there.
+// The fifth line's value when there is no scheduled next report. The command always supplies one, but
+// a line with no `next` field says the field was absent rather than inventing a time: `format_report`
+// is a pure renderer, so its contract states the absence rather than assuming a stamp is always there.
 const NO_NEXT = 'none'
 const QUIET_MARKER = '⏳'
 // `1970-01-01T00:00:00.000Z` cut after the minutes. Seconds are dropped because the interval this line
@@ -145,16 +142,14 @@ function format_offset(total_minutes: number): string {
 /**
  * The instant this observation was taken, on the local clock and in UTC, with its date on both.
  *
- * **The local half leads because it is the half a person can act on.** The line used to carry UTC
- * alone, and on a machine seven hours ahead every stamp in the report was a number the reader had to
- * convert before it meant anything — which is the same failure joshuafolkken/kit#1560 filed, arriving
- * from the other side: a stamp nobody can place is a stamp nobody reads.
+ * **The local half leads because it is the half a person can act on.** UTC alone is a number the
+ * reader has to convert before it means anything, and a stamp nobody can place is a stamp nobody reads.
  *
- * **UTC is kept beside it rather than replaced.** The reason it was pinned is real and unchanged: the
- * line is relayed to other machines and read in cloud sessions, and joshuafolkken/kit#1245 already
- * paid for a timestamp rendered in the reader's zone making one process look like a stranger. Printing
- * both costs twenty-five characters and leaves neither reader guessing — the offset is what ties the
- * two halves together, so a reader on a third machine can place the local half as well.
+ * **UTC is kept beside it rather than replaced.** The line is relayed to other machines and read in
+ * cloud sessions, where a timestamp rendered in the reader's zone makes one process look like a
+ * stranger. Printing both costs twenty-five characters and leaves neither reader guessing — the
+ * offset is what ties the two halves together, so a reader on a third machine can place the local
+ * half as well.
  *
  * **The local half is read off the instant shifted by that same rounded offset, never off `getHours`
  * and `getMinutes`.** Those truncate the seconds of a sub-minute offset while the offset beside them
@@ -202,8 +197,8 @@ function next_state(
 	return { key, unchanged_since_ms: now_ms }
 }
 
-// The issue leads as a citation rather than a bare `#N` (joshuafolkken/kit#2943): the parent relays these
-// lines verbatim, and a bare number copied into a reply is what the Stop guard sends back.
+// The issue leads as a citation rather than a bare `#N`: the parent relays these lines verbatim, and
+// a bare number copied into a reply is what the Stop guard sends back.
 function format_child(child: ChildObservation, cite: IssueCiter): string {
 	const labels = child.labels.length > 0 ? child.labels.join(',') : '(no labels)'
 
@@ -211,9 +206,8 @@ function format_child(child: ChildObservation, cite: IssueCiter): string {
 }
 
 // An empty set is the pre-label stage, said as such rather than left as a blank slot between the
-// separators (joshuafolkken/kit#1900). After that change a `read_observations` result carries no
-// children exactly when a run has started and none has reached `in-progress` yet, so this is the one
-// place the two cases are told apart on the line.
+// separators. A `read_observations` result carries no children exactly when a run has started and
+// none has reached `in-progress` yet, so this is the one place the two cases are told apart on the line.
 function format_children(children: ReadonlyArray<ChildObservation>, repo: string): string {
 	if (children.length === 0) return NO_CHILD_YET
 	const cite = issue_cite.citer(repo, new Map(children.map((child) => [child.issue, child.title])))
@@ -249,12 +243,9 @@ interface LineTiming {
 /**
  * When the next line is due if the silence holds — printed, never left for a reader to work out.
  *
- * **The two inputs were both here already and only one of them was printed** (joshuafolkken/kit#1726).
- * `backlogrun.md` asked the run to derive this from the `at` stamp plus the interval in force, and a run
- * that derives a time by hand eventually derives it wrong: one report reached a person as `20:1x`,
- * placeholder digits and all. Every comparable judgement in this repository has moved to the command
- * that already holds the inputs — `run:hold`, `delegate`, `review:level`, `latest:scope` — and
- * this is that same move for one value.
+ * **The command holds both inputs, so it prints the result.** A run that derives a time by hand from
+ * the `at` stamp plus the interval eventually derives it wrong; the judgement lives with the command
+ * that already holds the inputs, as for `run:hold`, `delegate`, `review:level` and `latest:scope`.
  *
  * **It is a schedule rather than an observation, and the two conditions on it are said in prose**
  * (`docs/josh-commands-run.md` → `josh run:progress`): it holds only while the silence continues, and a
@@ -267,7 +258,7 @@ function format_next_report(now_ms: number, interval_ms: number): string {
 
 // The already-formatted field strings the five labelled lines are built from. They are kept as strings
 // rather than the raw observation so that `format_report` stays a pure renderer the tests can drive with
-// an absent `next`, which is the migrated home of the doc's absent-field rule.
+// an absent `next`.
 interface ReportFields {
 	observed_at: string
 	quiet: string
@@ -287,14 +278,11 @@ function format_next_line(next: string | undefined): string {
 
 /**
  * The five labelled lines a quiet run prints — one field group per line, a label in front of every
- * field — so a person reads them without anything downstream re-labelling them (joshuafolkken/kit#2026).
- * The command used to emit one `·`-joined run of values that `backlogrun.md` asked the parent to rewrite
- * by hand every interval; the labels and the line breaks live here now, so the parent relays the output
- * verbatim and rounds, rephrases or re-labels nothing.
+ * field — so the parent relays the output verbatim and rounds, rephrases or re-labels nothing.
  *
- * The observation instant leads and the scheduled next closes it, for the reason the single line kept
- * them at its two ends: the first field says whether everything after it is still about now, and the
- * last is the one field about a moment that has not happened yet.
+ * The observation instant leads and the scheduled next closes it: the first field says whether
+ * everything after it is still about now, and the last is the one field about a moment that has not
+ * happened yet.
  */
 function format_report(fields: ReportFields): string {
 	return [
@@ -353,9 +341,15 @@ function minutes_from(raw: string | undefined): number | undefined {
 	return minutes
 }
 
+function is_disabled(): boolean {
+	return process.env[DISABLED_KEY] === DISABLED_VALUE
+}
+
 const run_progress = {
 	DEFAULT_INTERVAL_MINUTES,
 	DEFAULT_INTERVAL_MS,
+	DISABLED_KEY,
+	DISABLED_VALUE,
 	INTERVAL_KEY,
 	MS_PER_MINUTE,
 	MS_PER_SECOND,
@@ -368,6 +362,7 @@ const run_progress = {
 	format_next_line,
 	format_next_report,
 	format_report,
+	is_disabled,
 	is_due,
 	minutes_from,
 	next_state,

package/scripts/run/review/run-review-cli.ts

@@ -6,16 +6,16 @@ import { run_review, type GateState, type ReviewTiming } from './run-review'
 import { run_review_steps } from './run-review-steps'
 
 // `josh run:review` — one call that leaves `josh gate` running in the background and prints the whole
-// `/code-review` brief, so a lane child launches the two together and they overlap
-// (joshuafolkken/kit#2179). It composes `josh gate` and `josh review:brief` and changes neither: the
-// gate is the same command spawned detached, and the brief is `review:brief` run unchanged, so the
-// nonce/checkout contract `review:attest --check` enforces is minted exactly as before.
+// `/code-review` brief, so a lane child launches the two together and they overlap.
+// It composes `josh gate` and `josh review:brief` and changes neither: the gate is the same command
+// spawned detached, and the brief is `review:brief` run unchanged, so the nonce/checkout contract
+// `review:attest --check` enforces is minted exactly as a standalone brief mints it.
 //
 // **The default mode opens the pair; `--join` closes it.** The child runs the default, reads the brief
 // off stdout, launches the review subagent, and — once it returns — runs `--join`, which waits for the
 // gate to finish, records the overlap, and exits non-zero if the gate came back red. That exit code is
-// what makes "a red gate is not adopted over" a mechanical guarantee rather than an ordering the child
-// used to get for free (`run-review.ts` → `adopt_verdict`).
+// what makes "a red gate is not adopted over" a mechanical guarantee rather than an ordering
+// (`run-review.ts` → `adopt_verdict`).
 
 const ARGV_OFFSET = 2
 const JOIN_FLAG = '--join'

package/scripts/run/review/run-review-steps.ts

@@ -12,7 +12,7 @@ import { detached_launch, type LaunchArgv, type LaunchResult } from '#scripts/ru
 import { run_review, type GateState, type ReviewTiming, type TimingStart } from './run-review'
 
 // The side effects `josh run:review` performs, kept out of `run-review.ts` the way `run-merge-steps.ts`
-// is kept out of `run-merge.ts` (joshuafolkken/kit#2179). Three of them: launch the gate detached so
+// is kept out of `run-merge.ts`. Three of them: launch the gate detached so
 // one command leaves it running in the background, read back the state the join waits on from the
 // stamps a real `josh gate` writes, and keep the four timestamps the overlap is measured from.
 
@@ -65,10 +65,10 @@ function launch_gate(root: string = PROJECT_ROOT): LaunchResult {
 // in-flight marker reads. `reusable_green_gate` is the gate's own reuse test rather than a second copy
 // of it, so the join calls a gate green on exactly the trees the gate would skip.
 //
-// **The marker is read before the green record, never after** (joshuafolkken/kit#2434). The gate writes
-// its green record and only then clears the marker, so a marker read as gone means any green record is
-// already on disk for the read that follows. Read the other way round, a gate that recorded green and
-// cleared its marker between the two reads was seen as neither — and the join answered RED.
+// **The marker is read before the green record, never after**. The gate writes its green record
+// and only then clears the marker, so a marker read as gone means any green record is already on disk
+// for the read that follows. Read the other way round, a gate that recorded green and cleared its
+// marker between the two reads would be seen as neither — and the join would answer RED.
 async function read_gate_state(): Promise<GateState> {
 	const is_running = file_map_stamp.is_writer_running(review_stamps.in_flight_stamp.read())
 	const tree = await gate_tree.read_gate_tree()
@@ -78,7 +78,7 @@ async function read_gate_state(): Promise<GateState> {
 }
 
 // The brief has to report the gate as in-flight, or it says `Not verified` and sends the review agent
-// to re-run the suite the gate is already running (joshuafolkken/kit#1242). The detached gate writes
+// to re-run the suite the gate is already running. The detached gate writes
 // that marker itself, but its cold start can outrun the brief — so the composite writes the marker up
 // front, for the tree it is about to review. The gate overwrites it with its own identity the moment it
 // starts and clears it when it finishes, so this only closes the window between launch and that write;

package/scripts/run/review/run-review.ts

@@ -1,15 +1,13 @@
 // The pure decisions `josh run:review` makes, kept apart from the side effects the same way
-// `run-merge.ts` is kept apart from `run-merge-steps.ts` (joshuafolkken/kit#2179).
+// `run-merge.ts` is kept apart from `run-merge-steps.ts`.
 //
 // `run:review` starts the gate in the background and prints the `/code-review` brief in one call, so a
 // lane child launches both from a single command and the two overlap rather than running one after the
 // other. Two facts have to be decided from what the stamps say, and both are decided here so a test can
 // pin them without a gate ever running:
 //
-// - **whether the review verdict may be adopted** — only over a green gate. Before this command the
-//   ordering guaranteed it: the child read the gate, saw green, and only then launched the review, so
-//   there was no path to adopting a review over a red gate. Started together, that guarantee is no
-//   longer a side effect of the order and has to be a decision (`adopt_verdict`).
+// - **whether the review verdict may be adopted** — only over a green gate. Started together, the two
+//   no longer guarantee that by their order, so it has to be a decision (`adopt_verdict`).
 // - **how far the gate and the review overlapped** — the measurement the parallel start exists to
 //   produce, computed from the four timestamps `run-review-steps.ts` records.
 
@@ -18,10 +16,10 @@ const BLOCKED = 'blocked'
 
 type AdoptVerdict = typeof ADOPT | typeof BLOCKED
 
-// A red gate blocks the review verdict outright, whatever the review concluded — the same rule the
-// serial order used to enforce implicitly (joshuafolkken/kit#1242's gate-beside-review is only safe
-// while a red gate can still stop the commit). `--join` exits non-zero on `blocked`, so the guard is
-// the command's exit code rather than a sentence a child has to read and obey.
+// A red gate blocks the review verdict outright, whatever the review concluded: running the gate
+// beside the review is only safe while a red gate can still stop the commit. `--join` exits non-zero
+// on `blocked`, so the guard is the command's exit code rather than a sentence a child has to read
+// and obey.
 function adopt_verdict(is_gate_green: boolean): AdoptVerdict {
 	return is_gate_green ? ADOPT : BLOCKED
 }
@@ -85,8 +83,8 @@ function overlap_seconds(timing: ReviewTiming): number {
 	return Math.max(NO_OVERLAP, (end - start) / MS_PER_SECOND)
 }
 
-// The three lines a `--join` prints so a reader — issue #2179 and `chain-rule.md`'s overlap check —
-// can see the gate ran inside the review rather than in front of it.
+// The three lines a `--join` prints so a reader — `chain-rule.md`'s overlap check — can
+// see the gate ran inside the review rather than in front of it.
 function format_timing(timing: ReviewTiming): string {
 	const gate = span_seconds(timing.gate_started_at, timing.gate_ended_at)
 	const review = span_seconds(timing.review_started_at, timing.review_ended_at)

package/scripts/run/run-cli-fault.ts

@@ -0,0 +1,29 @@
+import { error_text } from '#scripts/lib/error-message'
+
+// What `run:cut`, `run:carry` and `run:hold` share about a failure nobody planned. Each of them answers
+// one token on every path out, and the token alone cannot say why — so the two failures are kept
+// apart here: a git directory that could not be resolved is the one case their "git directory could
+// not be read" message is true of, and anything else thrown is reported with its own message.
+
+// Only the resolution is folded into `undefined`, so the caller's unknown-git-directory message is
+// printed for that path alone. `JOSH_DEBUG` keeps the reason git gave.
+async function directory_of(
+	where: string,
+	read: () => Promise<string | undefined>,
+): Promise<string | undefined> {
+	try {
+		return await read()
+	} catch (error) {
+		error_text.trace_swallowed(where, error)
+
+		return undefined
+	}
+}
+
+function message(command: string, error: unknown): string {
+	return `${command} failed and established nothing: ${error_text.message_of(error)}`
+}
+
+const run_cli_fault = { directory_of, message }
+
+export { run_cli_fault }

package/scripts/run/run-ending-cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
 import {
@@ -8,10 +9,9 @@ import {
 	type EndingDecision,
 	type EndingRequest,
 } from './run-ending'
-import { run_issue_number } from './run-issue-number'
 
 // `josh run:ending <N> --output <path> [--repo <owner/repo>]` — one verdict about how the dispatched
-// lane child running `<N>` ended (joshuafolkken/kit#2139).
+// lane child running `<N>` ended.
 //
 // The stdout/stderr split is the contract `run:liveness` and `run:hold` keep: exactly one verdict
 // token on stdout on every path, the reason and the basis on stderr. `unreadable` exits non-zero,
@@ -59,7 +59,7 @@ interface ParsedArguments {
 function is_valid(parsed: ParsedArguments): boolean {
 	return (
 		parsed.positionals.length === 1 &&
-		run_issue_number.ISSUE_NUMBER_PATTERN.test(parsed.positionals[0] ?? '') &&
+		issue_number_shape.ISSUE_NUMBER_PATTERN.test(parsed.positionals[0] ?? '') &&
 		parsed.values.output !== undefined
 	)
 }

package/scripts/run/run-ending.ts

@@ -3,32 +3,28 @@ import { agent_exit_record } from '#scripts/agent/agent-exit-record'
 import { api_outage } from '#scripts/agent/api-outage'
 import type { ClaudeResultEvent } from '#scripts/agent/claude-result-event'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_state } from '#scripts/issue/issue-state'
 import { run_cut } from '#scripts/run/cut/run-cut'
 import { run_hold } from '#scripts/run/hold/run-hold'
-import { run_issue_number } from './run-issue-number'
 import { run_liveness } from './run-liveness'
 
-// `josh run:ending <N>` — how a dispatched lane child *ended*, not whether it is still moving
-// (joshuafolkken/kit#2139). `run:liveness` answers "still working, or stopped?"; a normally-exited
-// child that stopped mid-implementation is invisible to it — the output freezes exactly as a
-// completed child's does, and `is_error: false` looks like success. Measured on 2026-09-19: the child
-// for joshuafolkken/kit#2118 ended `subtype: success`, left three uncommitted files, opened no PR, and
-// `run:cut --resume` answered `fresh` — a mid-implementation exit that read as a clean finish, and the
-// cause took a person opening 875KB of JSONL to find.
+// `josh run:ending <N>` — how a dispatched lane child *ended*, not whether it is still moving.
+// `run:liveness` answers "still working, or stopped?"; a normally-exited child that stopped
+// mid-implementation is invisible to it — the output freezes exactly as a completed child's does, and
+// `is_error: false` looks like success.
 //
 // **The verdict is read from three traces the child leaves behind, never from `is_error`.** A cut
 // record for this issue means it handed off; a CLOSED Issue means it completed and merged; an OPEN
 // Issue with no cut means it ended in the middle. The exit record's own `is_error: false` is *not* a
-// completion — completion is the CLOSED Issue — which is the one distinction that was missing. The exit
-// record is read for the *basis* the park comment carries: which fields said so, and how many tool
-// calls the harness refused (`permission_denials`, the direct cause of the 2118 stop).
+// completion — completion is the CLOSED Issue. The exit record is read for the *basis* the park comment
+// carries: which fields said so, and how many tool calls the harness refused (`permission_denials`).
 //
 // **The words are a different question from `run:liveness`'s four**, deliberately non-overlapping:
 // `merged` / `cut` / `outage` / `abandoned` / `unreadable` answer "how did it end", where `alive` /
 // `stopped` / `settled` / `undetermined` answer "is it still going".
 //
-// **`outage` splits the mid-implementation ending in two** (joshuafolkken/kit#2240). A child that ended
+// **`outage` splits the mid-implementation ending in two**. A child that ended
 // mid-implementation because it could not reach the API is not a child that stalled on its own: the
 // exit record carries a transport-failure signature, read mechanically by `api-outage.ts`. The parent
 // reads it to leave the outage child re-dispatchable rather than parking it and counting it against
@@ -112,7 +108,7 @@ function describe_exit(record: ClaudeResultEvent): string {
 }
 
 // The refused interactive ask, as a clause the park comment can carry the question and options in — or
-// empty when the child asked nothing (joshuafolkken/kit#2201). This is the backstop for a child that
+// empty when the child asked nothing. This is the backstop for a child that
 // slipped past the `PreToolUse` refusal: the question is stranded in the exit record's
 // `permission_denials`, and lifting it here spares the parent opening the JSONL by hand.
 function refused_ask_clause(record: ClaudeResultEvent | undefined): string {
@@ -214,7 +210,7 @@ async function read_traces(request: EndingRequest): Promise<EndingTraces> {
 }
 
 async function check(request: EndingRequest): Promise<EndingDecision> {
-	run_issue_number.require_issue_number(request.issue)
+	issue_number_shape.require_issue_number(request.issue)
 
 	return decide(await read_traces(request))
 }

package/scripts/run/run-halfrun-resume.ts

@@ -5,11 +5,10 @@ import {
 	type StopMarkFields,
 } from '#scripts/run/hold/run-hold'
 
-// joshuafolkken/kit#2796: a `halfrun` stops before its commit and **keeps** its hold, because the
-// uncommitted, hand-verified work is exactly what a second run would trample. The person then types
-// `fullrun #N` to ship it — and `run:entry`'s claim answered `busy` against that very hold, or, once the
-// hold had been cleared, the preflight advised stashing the verified diff away. The hand-off the
-// `halfrun` stop promised could not land, and each run improvised its own way past the guard.
+// A `halfrun` stops before its commit and **keeps** its hold, because the uncommitted, hand-verified
+// work is exactly what a second run would trample. The person then types `fullrun #N` to ship it, and
+// that run adopts the hold here rather than meeting `busy` from `run:entry`'s claim or being advised
+// to stash the verified diff away.
 //
 // **The stop is recorded, never inferred.** A hold naming #N over a dirty tree is also what a `halfrun`
 // still implementing and a `backlogrun` child leave, and adopting either hands a half-written diff to
@@ -43,7 +42,7 @@ function is_own_record(read: HoldRead, issue: string): boolean {
 	return hold === undefined || hold.issue === issue || hold.issue === run_hold.UNNUMBERED_ISSUE
 }
 
-// `mark` is the `halfrun` stop's by default; a `prrun` stop passes its own (joshuafolkken/kit#3023), so
+// `mark` is the `halfrun` stop's by default; a `prrun` stop passes its own, so
 // the own-record check is one check whichever run is stopping.
 function mark_stop_at(
 	target: string,
@@ -68,8 +67,7 @@ function take_over(target: string, issue: string): boolean {
 	return run_hold.create_hold(target, issue, new Date(), true)
 }
 
-// `false` leaves the record untouched, so the ordinary claim that follows decides the tree exactly as
-// it did before this resume existed.
+// `false` leaves the record untouched, so the ordinary claim that follows decides the tree.
 function adopt_at(target: string, issue: string, is_dirty: boolean): boolean {
 	if (!is_halfrun_stop(run_hold.read_hold(target), issue, is_dirty)) return false
 

package/scripts/run/run-headless.ts

@@ -3,11 +3,11 @@ import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry } from '#scripts/lane/lane-registry'
 import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
 
-// The headless `backlogrun` parent (joshuafolkken/kit#2437). `run:wake` starts a cut's successor as
+// The headless `backlogrun` parent. `run:wake` starts a cut's successor as
 // `claude -p`, and there a turn that ends is the process that ends: its background `lane:await` and
 // `run:progress --wait` are killed with it, so "a background command's exit re-invokes the session"
-// (`backlogrun-progress.md` → "The parent keeps no clock of its own") does not hold. A successor that
-// ended its turn on a wait therefore ended the run's driver while its lanes were still working.
+// (`docs/maintainers/backlogrun-driver.md` → "Waiting while something is in flight") does not hold. A successor that
+// ends its turn on a wait therefore ends the run's driver while its lanes are still working.
 //
 // **The mark is what tells that session apart, and the supervisor is its only writer.** It rides the
 // launch's environment (`run-wake-cli.ts`), so an attached session never carries it, and a lane child
@@ -28,6 +28,21 @@ function is_headless(source: EnvironmentSource = process.env): boolean {
 	return source[HEADLESS_ENV_KEY] === HEADLESS_VALUE
 }
 
+// The session the supervisor launched itself — marked, and not a lane child that inherited the mark.
+function is_headless_parent(source: EnvironmentSource): boolean {
+	return is_headless(source) && lane_child_marker.marked_issue(source) === undefined
+}
+
+// **The cut cap binds a session cut, never the hand-back to the driver.** A headless parent is a
+// judgment session the `run:wake` driver woke for one branch, and its `--cut` is how it returns the
+// loop — the driver holds the run between wakes, so the session has no accumulated context for the
+// cap to weigh against a cold preamble. Capping it would leave the session unable to cut while the
+// headless stop rule refuses its turn-end until it does. Every reader of the cap asks here, so the
+// `--cut` refusal, `run:step` and the parent-cut hook never disagree about it.
+function is_cut_capped(carry: RunCarry, source: EnvironmentSource = process.env): boolean {
+	return !is_headless_parent(source) && run_carry.is_at_cut_cap(carry)
+}
+
 // Only a live, un-handed-off record binds the session to its lanes. After `run:carry --cut` the next
 // successor drives them, and after `--end` (`none`) or past the bound (`expired`) there is no run left
 // to drive — ending the turn is correct in all three. An unreadable record fails open, as every stop
@@ -49,9 +64,7 @@ async function read_carry_here(): Promise<CarryRead | undefined> {
  * lane child, with lanes still in flight and no cut handed the record off.
  */
 async function must_keep_waiting(source: EnvironmentSource = process.env): Promise<boolean> {
-	const is_candidate = is_headless(source) && lane_child_marker.marked_issue(source) === undefined
-
-	if (!is_candidate || !(await lane_registry.has_lanes_in_flight())) return false
+	if (!is_headless_parent(source) || !(await lane_registry.has_lanes_in_flight())) return false
 
 	return is_driving(await read_carry_here())
 }
@@ -64,9 +77,9 @@ async function current_carry(): Promise<RunCarry | undefined> {
 	return read?.kind === 'carried' ? read.carry : undefined
 }
 
-// **A live record binds only the session that declared it** (joshuafolkken/kit#2472). A cut's
-// successor adopts the record and rewrites its owner, and every session in this checkout reads that
-// same file — so without this test the session that cut, still attached, read as a second parent. The
+// **A live record binds only the session that declared it**. A cut's successor adopts the
+// record and rewrites its owner, and every session in this checkout reads that same file — so without
+// this test the session that cut, still attached, would read as a second parent. The
 // owner is `--owner "$PPID"`, the session process, which is an ancestor of every hook it runs; a
 // record that declared no owner proves no one is its parent.
 function is_owned_here(carry: RunCarry, ancestry: () => ReadonlySet<number>): boolean {
@@ -85,7 +98,7 @@ function driven_here(
 /**
  * The live, un-handed-off carry record this session drives as the `backlogrun` parent, or `undefined`
  * for a lane child or any session that does not own one. Returned rather than tested so a caller that
- * also needs the record's counters (the parent cut's cap, joshuafolkken/kit#2947) reads it once.
+ * also needs the record's counters (the parent cut's cap) reads it once.
  */
 async function driving_carry(
 	source: EnvironmentSource = process.env,
@@ -98,8 +111,7 @@ async function driving_carry(
 
 /**
  * Whether this session is the driving `backlogrun` parent, attached or headless: not a lane child, and
- * the declared owner of a live, un-handed-off carry record — the record only a `backlogrun` writes
- * (joshuafolkken/kit#2452, joshuafolkken/kit#2472).
+ * the declared owner of a live, un-handed-off carry record — the record only a `backlogrun` writes.
  */
 async function is_backlog_parent(
 	source: EnvironmentSource = process.env,
@@ -114,6 +126,7 @@ const run_headless = {
 	driving_carry,
 	environment,
 	is_backlog_parent,
+	is_cut_capped,
 	is_headless,
 	is_owned_here,
 	must_keep_waiting,