@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/run/run-invocation.ts

@@ -1,46 +1,41 @@
 import { backlog_budget_cli } from '#scripts/backlog/backlog-budget-cli'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { run_issue_number } from './run-issue-number'
 
 // The grammar of an invocation that can be carried across a session cut, and the only place it is
-// written down (joshuafolkken/kit#1774, folded into `backlogrun` by joshuafolkken/kit#1984). It sat
-// inside `run-wake-session.ts` while that supervisor was its one reader; two now need the same answer
-// — the supervisor, to rebuild the text it wakes with, and `run-carry.ts`, to say which of a
-// `backlogrun`'s named issues are still outstanding. A grammar copied into two files is a grammar
-// kept correct in one, which is the clone `CLAUDE.md` prohibits.
+// written down. Two readers need the same answer — the supervisor, to rebuild the text it wakes with,
+// and `run-carry.ts`, to say which of a `backlogrun`'s named issues are still outstanding. A grammar
+// copied into two files is a grammar kept correct in one, which is the clone `CLAUDE.md` prohibits.
 //
 // **`backlogrun` is the one command that survives a cut, and its invocation is a named-issue list, a
 // budget, or both.** `backlogrun #N1 #N2 …` runs the named issues in the order they were typed and
 // then drains the opted-in backlog; `backlogrun --max 5 --idle 30` names only a budget; the two
-// combine as `backlogrun #N1 #N2 --max 5`. The named list is what `queue` used to be its own keyword
-// for (joshuafolkken/kit#1984 removed that keyword).
+// combine as `backlogrun #N1 #N2 --max 5`.
 //
 // **The invocation is taken apart and rebuilt, rather than inspected and handed on.** Everything that
 // may reach the operating system is enumerable: one command word, two flag names, and an integer for
 // each argument. Reading the record as tokens and composing a fresh string out of constants and
 // validated integers means the text the record held never reaches `spawn` at all.
 //
-// **A stricter check is not a break in the flow, and that is why three of them changed nothing.**
-// Validating the characters, fixing the binary as a constant and matching against a pattern all left
-// the recorded string flowing into the call; taint tracking follows where a value goes, not how hard
-// it was looked at on the way. Composing the argument from constants is what actually severs it
-// (joshuafolkken/kit#1719).
+// **A stricter check is not a break in the flow.** Validating the characters, fixing the binary as a
+// constant and matching against a pattern all leave the recorded string flowing into the call; taint
+// tracking follows where a value goes, not how hard it was looked at on the way. Composing the
+// argument from constants is what actually severs it.
 const BACKLOG_COMMAND = 'backlogrun'
 // **The named list is pinned to what was typed.** The record keeps the opening list unchanged across
-// every cut, so `classify_claim`'s character-for-character comparison is untouched and
-// joshuafolkken/kit#1722's single-writer guarantee is not weakened. What shrinks is the *outstanding*
-// set, and that lives in the record's `done` field rather than in the string — the alternative,
-// loosening the comparison to the keyword, is what joshuafolkken/kit#1774 rejected.
+// every cut, so `classify_claim`'s character-for-character comparison is untouched and the
+// single-writer guarantee is not weakened. What shrinks is the *outstanding* set, and that lives in
+// the record's `done` field rather than in the string.
 //
 // The flags this grammar knows how to carry across a session cut. A token is compared against these
 // and the **constant that matched** is what goes into the rebuilt invocation, never the token itself:
 // the two are equal as text and differ in where they came from, and here the origin is the whole point.
 const KNOWN_FLAGS: ReadonlyArray<string> = ['--max', '--idle']
 // `--only` is the one flag that takes no value — it says "run the named list and stop, do not drain the
-// pool" (joshuafolkken/kit#1984). It is carried across a cut like any other part of the invocation, so
+// pool". It is carried across a cut like any other part of the invocation, so
 // a resumed session that reads it back does not silently start draining the backlog the person excluded.
 const ONLY_FLAG = '--only'
-// The read itself is `cli_flags`'s (joshuafolkken/kit#3261): strict, so an unknown flag, a flag with
+// The read itself is `cli_flags`'s: strict, so an unknown flag, a flag with
 // no value, `--only=<x>` and a value that is itself a flag are all refused before this file looks.
 const OPTIONS = {
 	max: { type: 'string' },
@@ -71,7 +66,7 @@ interface Invocation {
 // A space is the only separator that can survive `detached-launch.ts`'s `is_safe_value`, which has
 // already refused every control character — so the split needs no pattern, and this file is left with
 // no regular expression of its own for a backtracking analysis to find. The one pattern it does use
-// is `run-issue-number.ts`'s, which is anchored and has no alternation.
+// is `issue-number-shape.ts`'s, which is anchored and has no alternation.
 function tokens_of(invocation: string): ReadonlyArray<string> {
 	return invocation.split(TOKEN_SEPARATOR).filter((token) => token.length > EMPTY_LENGTH)
 }
@@ -110,7 +105,7 @@ function rendered_options(tokens: ReadonlyArray<ArgumentToken>): ReadonlyArray<s
 	return rendered
 }
 
-// **The issue-number shape is `run-issue-number.ts`'s, for the reason the flag value's is
+// **The issue-number shape is `issue-number-shape.ts`'s, for the reason the flag value's is
 // `backlog:budget`'s.** It already refuses `0` and a leading zero, which is what keeps `#05` from
 // rebuilding as `#5` and being refused downstream as a rewritten record.
 // **The magnitude bound is here and not in the pattern**, which is anchored on digits and says nothing
@@ -122,7 +117,7 @@ function issue_of(token: string): number | undefined {
 
 	const digits = token.slice(ISSUE_PREFIX.length)
 
-	if (!run_issue_number.ISSUE_NUMBER_PATTERN.test(digits)) return undefined
+	if (!issue_number_shape.ISSUE_NUMBER_PATTERN.test(digits)) return undefined
 
 	const issue = Number(digits)
 

package/scripts/run/run-label.ts

@@ -1,11 +1,11 @@
 import { git_followup_label } from '#scripts/followup/git-followup-label'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
 
-// **The `in-progress` marker belongs to the commands that open and release a run**
-// (joshuafolkken/kit#3182). Every manifest used to spell the label's create, apply and removal as raw
-// `gh api` calls, so each copy was a place the marker could be forgotten; `run:entry` applies it the
-// moment the tree is held and the budget allows the run, and `run:release` takes it back off.
+// **The `in-progress` marker belongs to the commands that open and release a run**, so no manifest
+// spells the label's calls and none can forget it: `run:entry` applies it the moment the tree is held
+// and the budget allows the run, and `run:release` takes it back off.
 //
 // **Neither half ever fails the command it rides on.** The hold is the guard and the label only
 // reports it, so a refused write is warned about by name — with the call that finishes it by hand —
@@ -15,7 +15,9 @@ const MARK_RECOVERY = "gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[
 const UNMARK_RECOVERY = 'gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress'
 
 function warn(action: string, issue: string, recovery: string): void {
-	console.warn(`⚠ could not ${action} \`in-progress\` on #${issue} — run by hand: ${recovery}`)
+	console.warn(
+		`⚠ could not ${action} \`in-progress\` on ${session_cite.issue(issue)} — run by hand: ${recovery}`,
+	)
 }
 
 // `issue_add_label` creates the label when the repository lacks it (`lane-dispatch.ts`), so no

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

@@ -1,8 +1,9 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { lane_await } from '#scripts/lane/lane-await'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { error_text } from '#scripts/lib/error-message'
-import { run_issue_number } from './run-issue-number'
 import {
 	MS_PER_MINUTE,
 	MS_PER_SECOND,
@@ -16,8 +17,8 @@ import {
 	type ProcessTrace,
 } from './run-liveness'
 
-// `josh run:liveness <N> --output <path> --process <alive|none>` — one verdict about the delegated
-// unit running child `<N>` (joshuafolkken/kit#1485).
+// `josh run:liveness <N> --output <path> [--process <alive|none>]` — one verdict about the delegated
+// unit running child `<N>`.
 //
 // The stdout/stderr split is the contract, as it is for `run:hold`: exactly one
 // verdict token on stdout on every path, the reason and the advice on stderr. `undetermined` exits
@@ -92,7 +93,7 @@ interface ParsedArguments {
 function is_valid_target(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] ?? '')
 	)
 }
 
@@ -120,13 +121,25 @@ function to_optional_fields(values: ParsedValues): Partial<LivenessRequest> {
 	}
 }
 
+// Left out, the process trace is read here with the probe `lane:await` polls on — the child's
+// invocation or its detached ship — so no caller runs `pgrep` by hand; a
+// probe that could not look answers `unknown`, never `none`. A given `--process` still wins: it is
+// the answer for a unit this probe does not know, such as one whose checkout the caller scanned itself.
+function process_trace_of(values: ParsedValues, issue: string): ProcessTrace {
+	if (values.process !== undefined) return to_process_trace(values.process) ?? PROCESS_UNKNOWN
+
+	return lane_await.process_trace_default(issue)
+}
+
 // Reached only through `is_valid`, so the fallbacks below are unreachable defaults rather than
 // behavior: the alternative is a type assertion, which this codebase restricts.
 function to_request(parsed: ParsedArguments): LivenessRequest {
+	const issue = parsed.positionals[0] ?? ''
+
 	return {
-		issue: parsed.positionals[0] ?? '',
+		issue,
 		output_path: parsed.values.output ?? '',
-		process_trace: to_process_trace(parsed.values.process) ?? PROCESS_UNKNOWN,
+		process_trace: process_trace_of(parsed.values, issue),
 		...to_optional_fields(parsed.values),
 	}
 }

package/scripts/run/run-liveness.ts

@@ -5,28 +5,21 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_event, type AgentEventState } from '#scripts/agent/agent-event'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { ALREADY_DONE_LABEL, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_state } from '#scripts/issue/issue-state'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { run_hold } from '#scripts/run/hold/run-hold'
-import { run_issue_number } from './run-issue-number'
 
 // `josh run:liveness <N>` — whether the delegated unit running child `<N>` is still working, or
-// stopped without reporting (joshuafolkken/kit#1485).
-//
-// joshuafolkken/kit#1212 wrote the detection as a conjunction of four traces an agent read by hand,
-// and it could not fire for the stop that actually happened. Its second trace required a **dirty**
-// checkout, justified by "a unit that died mid-implementation leaves exactly this" — so a unit that
-// died *before* implementing, while it was still reading the skill and the issue, left a clean tree
-// and the conjunction stayed false forever. Measured on 2026-09-06: the unit for
-// joshuafolkken/kit#1169 stopped seven minutes in, three of the four traces held, and the parent
-// went on calling the child in progress for 42 minutes until a person asked.
+// stopped without reporting.
 //
 // **Two traces decide it, and neither depends on whether implementation started**: the unit's output
-// has stopped growing, and no process of the child's is alive in that checkout. The dirty tree is
-// demoted from the test to an input of the recovery — it says whether there is anything to stash,
-// which is a different question from whether the unit is alive. "Nothing was ever opened for the
-// child" is dropped outright: it is also the normal state of a unit that has not reached its commit
-// yet, and the branch-and-pull-request question already has an owner in `josh run:hold`'s preflight check.
+// has stopped growing, and no process of the child's is alive in that checkout. A unit can die before
+// implementing and leave a clean tree, so the dirty tree is an input of the recovery, not of the test
+// — it says whether there is anything to stash, which is a different question from whether the unit
+// is alive. "Nothing was ever opened for the child" is not a trace either: it is also the normal
+// state of a unit that has not reached its commit yet, and the branch-and-pull-request question
+// already has an owner in `josh run:hold`'s preflight check.
 //
 // **The binding constraint is the direction of the error.** A live unit booked as stopped has its
 // working work killed; a stopped unit booked as alive costs waiting. So the ladder reads the one
@@ -37,9 +30,8 @@ import { run_issue_number } from './run-issue-number'
 // **The output read follows the link.** The path a unit writes its transcript to is a symbolic link, and
 // the link's own modification time never changes after it is created — read with the shell's `stat`,
 // which does not follow by default on macOS, the file looks frozen whether the unit is alive or
-// dead. That is the second half of joshuafolkken/kit#1485: the same parent reported a dead unit as
-// alive twice on such a read. `statSync` follows the link, and the size is compared as well as the
-// modification time, because it is the two-sample size comparison that actually proved liveness.
+// dead. `statSync` follows the link, and the size is compared as well as the modification time,
+// because it is the two-sample size comparison that actually proves liveness.
 
 const ALIVE_VERDICT = 'alive'
 const SETTLED_VERDICT = 'settled'
@@ -52,11 +44,10 @@ type LivenessVerdict =
 	| typeof STOPPED_VERDICT
 	| typeof UNDETERMINED_VERDICT
 
-// The one trace this command cannot read for itself. A process scan that matched too little would
+// The one trace this module does not read for itself. A process scan that matched too little would
 // book a live unit as stopped, and one that matched too much would never detect anything — so the
-// caller runs the `pgrep` the skill specifies against the checkout it handed the unit, and passes
-// what it saw. `unknown` is the default, and a trace nobody gave is an unasked question rather than
-// an answer of "no process".
+// CLI reads it with `lane:await`'s probe, or takes what the caller passed. `unknown` is what a
+// request carries when nobody read it, an unasked question rather than an answer of "no process".
 const PROCESS_ALIVE = 'alive'
 const PROCESS_NONE = 'none'
 const PROCESS_UNKNOWN = 'unknown'
@@ -116,8 +107,8 @@ const ALIVE_ADVICE = 'Keep polling; do not touch the child.'
 const SETTLED_ADVICE =
 	'Read the child with `pnpm josh issue:state <N>` and take the branch its state says.'
 // The unit stopped, but *why* it stopped — abandoned mid-implementation, or dead because it could not
-// reach the API — is `run:ending`'s question, not this one's (joshuafolkken/kit#2277). Booking every
-// stop as a failure parked an API-outage child that should have been re-dispatched, so the recovery is
+// reach the API — is `run:ending`'s question, not this one's. Booking every stop as a failure would
+// park an API-outage child that should be re-dispatched, so the recovery is
 // routed through `run:merge --output`, the same composite a returned child takes: it reads the exit
 // record without waiting for the unit to return, re-dispatches an outage child (counting the outage,
 // and stopping the run on the environment guard once a run of them trips it), and parks an abandoned
@@ -127,7 +118,7 @@ const STOPPED_CLEAN_ADVICE =
 const STOPPED_DIRTY_ADVICE =
 	'Stash the half-finished work with `git stash push -u -m "backlogrun: stopped unit for #<N>"` and record it on the Issue, then classify how the unit ended with `pnpm josh run:merge <N> --output <path>` (add `--epic <E> --repo <owner/repo> --owner "$PPID"` for a named epic): it re-dispatches an API-outage child (counting the outage; a run of them trips the environment guard) and parks an abandoned child with `needs-decision` against the consecutive-failure guard, without waiting for the unit to return.'
 const UNDETERMINED_ADVICE =
-	'Read the trace that failed and ask again. Where the process trace was never given, run the `pgrep` against the checkout the unit was given and pass `--process alive` or `--process none`. Two of these in a row is a fault in the check itself rather than a slow unit: stop polling and report it.'
+	'Read the trace that failed and ask again. Where the process trace was given as `unknown`, leave `--process` out so the command reads it. Two of these in a row is a fault in the check itself rather than a slow unit: stop polling and report it.'
 
 // Output that moved is a unit that is writing, and it is asked before anything else — it is the one
 // reading that needs no other trace to mean what it says.
@@ -153,8 +144,8 @@ function definitive_verdict(traces: Traces): LivenessVerdict | undefined {
 
 // A live process is a unit inside a long check — a `pnpm josh followup` waiting on CI writes
 // nothing for up to 32 minutes, which is longer than the silent window and is exactly the false
-// positive this trace exists to stop. **It is asked after the unreadable check rather than before it**
-// (joshuafolkken/kit#1485, review round 2): a `pgrep` scoped a shade too wide answers `alive` on a
+// positive this trace exists to stop. **It is asked after the unreadable check rather than before it**:
+// a `pgrep` scoped a shade too wide answers `alive` on a
 // machine running several kit projects at once, and read ahead of an output path that resolves to
 // nothing it would answer `alive` on every poll forever — the unbounded stall this command exists to
 // remove, reappearing where nothing would ever count it.
@@ -220,9 +211,8 @@ function to_resolved_root(root: string): string {
 // **Every root is listed in both spellings, and that is load-bearing rather than defensive.** `/tmp`
 // is a symbolic link to `/private/tmp` on macOS and `/var` one to `/private/var`, so a containment
 // test against one spelling rejects a transcript whose path was written as the other — `path.relative`
-// resolves no link. Measured on 2026-09-07: a transcript at `/private/tmp/claude-501/…` was refused,
-// every poll answered `undetermined`, and the parent could not detect a stopped unit at all — the
-// unbounded stall this command exists to remove, reappearing inside its own path check. Resolving the
+// resolves no link — and a refused transcript makes every poll answer `undetermined`, the unbounded
+// stall this command exists to remove, reappearing inside its own path check. Resolving the
 // *candidate* would not do instead: it does not exist yet in the "resolves to nothing" case, which has
 // to stay unreadable rather than throw.
 const ALLOWED_ROOTS: ReadonlyArray<string> = [
@@ -251,9 +241,8 @@ function to_safe_path(output_path: string): string | undefined {
 }
 
 // `statSync` follows a symbolic link; `lstatSync` and the shell's bare `stat` do not. That difference is
-// the whole of joshuafolkken/kit#1485's second symptom, so it is stated here rather than left to a
-// reader to know. A path that resolves to nothing, or to something that is not a regular file, is
-// unreadable rather than frozen.
+// load-bearing, so it is stated here rather than left to a reader to know. A path that resolves to
+// nothing, or to something that is not a regular file, is unreadable rather than frozen.
 function sample_output(output_path: string): OutputSample | undefined {
 	const safe_path = to_safe_path(output_path)
 
@@ -324,7 +313,7 @@ function carries_label(labels: ReadonlyArray<string>, wanted: string): boolean {
 
 // The labels that say a unit stopped on purpose. `needs-decision` is the park branch; `already-done`
 // is the exit a child takes when it verifies its Issue's work is already merged
-// (joshuafolkken/kit#1679) — it comments the evidence, applies the label and stops with the checkout
+// — it comments the evidence, applies the label and stops with the checkout
 // clean, which is settled by the same reasoning. Left out, this command reports a child that
 // finished correctly as `stopped` and a supervisor restarts the investigation it just completed.
 const SETTLED_LABELS: ReadonlyArray<string> = [NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL]
@@ -336,8 +325,8 @@ function carries_settled_label(labels: ReadonlyArray<string>): boolean {
 // Settled needs positive evidence that the child is done with: it closed, or the unit parked it and
 // then stopped, which the loop's park branch already owns. **An open child that is not parked is not settled
 // even without `in-progress`** — that label is applied by the unit itself, after it reads the issue,
-// so a unit that died before applying it would otherwise be reported as a child needing nothing
-// (joshuafolkken/kit#1485, review round 1). Read that way, the stop this command exists for goes
+// so a unit that died before applying it would otherwise be reported as a child needing nothing.
+// Read that way, the stop this command exists for goes
 // undetected.
 async function read_child_settled(issue: string, repo?: string): Promise<boolean | undefined> {
 	const json = await git_gh_issue_read.issue_view_json(issue, STATE_FIELDS, repo)
@@ -386,7 +375,7 @@ async function read_traces(request: LivenessRequest): Promise<Traces> {
 }
 
 async function check(request: LivenessRequest): Promise<LivenessDecision> {
-	run_issue_number.require_issue_number(request.issue)
+	issue_number_shape.require_issue_number(request.issue)
 
 	return decide(await read_traces(request))
 }
@@ -394,7 +383,7 @@ async function check(request: LivenessRequest): Promise<LivenessDecision> {
 // The constants are exported by name rather than through the namespace: read back off a namespace
 // object their literal types widen to `string`, and `ProcessTrace` would then admit anything.
 // `to_safe_path` is on the namespace because `josh lane:output` refuses a path this command could
-// not read (joshuafolkken/kit#1713). Recorded, such a path makes every poll answer `undetermined`
+// not read. Recorded, such a path makes every poll answer `undetermined`
 // for ever — so the two have to agree, and agreeing means one function rather than two.
 const run_liveness = {
 	check,

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

@@ -3,15 +3,11 @@ import { fileURLToPath } from 'node:url'
 import { run_next } from './run-next'
 import { run_prep_cli } from './run-prep-cli'
 
-// `josh run:next <N>` — print the next step a `fullrun` takes, from the run's state
-// (joshuafolkken/kit#2188). It reads exactly what `run:prep` reads — the issue state, the
-// `human_review` line and the dependency scope — by calling `run:prep`'s own gather, so the two never
-// answer from different facts, and hands the assembled parts to the state → step mapping in
-// `run-next.ts`.
-//
-// **It is the consumer `run:prep` was built to have.** joshuafolkken/kit#1978 bundled the reads;
-// joshuafolkken/kit#2165 added the read-only glance; this one prints the decision those reads support,
-// which is the trim epic #2166 is after — prose a reader interprets replaced by a computed answer.
+// `josh run:next <N>` — print the next step a `fullrun` takes, from the run's state.
+// It reads exactly what `run:prep` reads — the issue state, the `human_review` line and the dependency
+// scope — by calling `run:prep`'s own gather, so the two never answer from different facts, and hands
+// the assembled parts to the state → step mapping in `run-next.ts`. It prints the decision those reads
+// support — prose a reader interprets replaced by a computed answer.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1

package/scripts/run/run-next.ts

@@ -1,12 +1,11 @@
 import type { PrepParts } from './run-prep'
 import { run_step, type PreVerdict } from './run-step'
 
-// `josh run:next <N>` — the next step a `fullrun` takes, printed from the run's state
-// (joshuafolkken/kit#2188). It is the foundation the epic #2166 rests on: the entry read is trimmed by
-// replacing prose that a reader has to interpret with a command that answers "what now" from the same
-// state `run:prep` already gathered, so the answer is computed rather than judged.
+// `josh run:next <N>` — the next step a `fullrun` takes, printed from the run's state.
+// It replaces prose that a reader has to interpret with a command that answers "what now" from the
+// same state `run:prep` already gathered, so the answer is computed rather than judged.
 //
-// **It is now the degenerate form of `run:step`** (joshuafolkken/kit#2248). `run:step` computes a run's
+// **It is the degenerate form of `run:step`.** `run:step` computes a run's
 // position from the event stream, the carry record and the issue state; a `fullrun` with nothing emitted
 // yet is at its pre-implementation position, which is exactly what this prints. The state → step mapping
 // lives once, in `run-step.ts`'s `pre_verdict`, and this maps each verdict to the prose sentence a

package/scripts/run/run-parent-cut-hook.ts

@@ -5,19 +5,18 @@ import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { error_text } from '#scripts/lib/error-message'
 import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
-import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import type { RunCarry } from '#scripts/run/carry/run-carry'
 import { run_headless } from './run-headless'
 import { run_watcher_hook } from './run-watcher-hook'
 
-// The `backlogrun` parent's hand-off, delivered at the call it binds on (joshuafolkken/kit#2947).
+// The `backlogrun` parent's hand-off, delivered at the call it binds on.
 //
-// **The parent's hand-off was asked only at a merge, and the context grew between merges.** The
-// orchestrator never implements, yet on 2026-10-02 parent 259fb6d5 sent 111 of its 170 requests past
-// the shared threshold, peaking at 207,081 tokens: `pnpm josh cost --cut` is read after each child's
-// merge (`backlogrun-progress.md` → "The hand-off"), and a long wait or a lane-failure investigation
-// between two merges is exactly where it went unread. This is the lesson `implementation-cut.ts` records
-// for a lane child, one session up — a check carried as a step is taken late, a `PreToolUse` refusal is
-// taken at the next call.
+// **A hand-off asked only at a merge goes unread while the context grows between merges.** The
+// orchestrator never implements, but `pnpm josh cost --cut` is read after each child's merge
+// (`backlogrun-progress.md` → "The hand-off"), and a long wait or a lane-failure investigation between
+// two merges is where the context grows past the shared threshold. This is the lesson
+// `implementation-cut.ts` records for a lane child, one session up — a check carried as a step is
+// taken late, a `PreToolUse` refusal is taken at the next call.
 //
 // **The same statistic and the same threshold, never a second measurement.** The verdict is
 // `cost_cli.session_verdict` — what `pnpm josh cost --cut` prints — read through the implementation cut's
@@ -33,8 +32,7 @@ const STAMP_PREFIX = 'josh-parent-cut-guard-'
 // **One refusal, then a quiet window long enough to finish the hand-off in.** The hand-off is several
 // calls — `lane:list`, `lane:output`, `run:carry --cut`, `run:wake`, the progress comment — and a guard
 // refusing each of them would wedge the very procedure it asks for. A parent that could not cut (a lane
-// nobody can poll) is asked again once the window has passed, which is the "next opportunity" the merge
-// seam used to be.
+// nobody can poll) is asked again once the window has passed.
 const QUIET_WINDOW_MS = 600_000
 
 // What the decision has to know about the world, passed in so it is testable without a carry record or
@@ -73,7 +71,7 @@ const PARENT_CUT_REASON =
 async function is_due(state: ParentCutState): Promise<boolean> {
 	const carry = await state.carry()
 
-	if (carry === undefined || run_carry.is_at_cut_cap(carry)) return false
+	if (carry === undefined || run_headless.is_cut_capped(carry)) return false
 
 	return state.verdict() === cost_verdict.OVER_VERDICT
 }

package/scripts/run/run-preflight.ts

@@ -1,30 +1,30 @@
 import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
 import { git_command } from '#scripts/git/git-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { json_value } from '#scripts/lib/json-value'
 import { run_hold } from '#scripts/run/hold/run-hold'
 import { z } from 'zod'
-import { run_issue_number } from './run-issue-number'
 
 // The preflight check — what an interrupted run left in this working tree, and what the rule says to
-// do about it before the next child starts (joshuafolkken/kit#926). It once had its own
-// `josh run:preflight` CLI; joshuafolkken/kit#1965 folded the check into `run:hold`, which now runs it
-// before it claims the tree, so this module is the shared logic behind that claim and behind
-// `run:progress`, and no longer a command of its own.
+// do about it before the next child starts. `run:hold` runs it before it claims the tree, so this
+// module is the shared logic behind that claim and behind `run:progress`, not a command of its own.
 //
-// joshuafolkken/kit#1091 gave a run a way to say "this tree is mine". This is the sibling question,
-// and it is about the run that never said anything again: an unattended run ends abnormally — a
-// crash, a Ctrl-C, a laptop asleep, an expired token — and leaves its feature branch, its open pull
-// request and its uncommitted changes behind. Every child of an `epicrun` starts with
-// `git switch main && git pull`, which refuses over a dirty tree, and an agent may not reach for
-// `git stash` on its own judgement, so the batch could not recover without a person.
+// It is about the run that never said anything again: an unattended run ends abnormally — a crash, a
+// Ctrl-C, a laptop asleep, an expired token — and leaves its feature branch, its open pull request and
+// its uncommitted changes behind. The next child's checkout refuses over a dirty tree, and an agent
+// may not reach for `git stash` on its own judgement, so without this check the batch cannot
+// recover unattended.
 //
 // **The rule answers, so the run does not judge.** "There is a branch already, I will carry on from
 // it" and "there is a branch already, I had better stop" are both defensible in the moment, which is
 // exactly why the choice is not left to the moment — the same reason `josh delegate` and
 // `josh review:level` refuse to leave their answers to an agent.
 //
-// **The check is re-askable, which the claim it now gates deliberately is not.** A claim asked twice
-// answers `busy`, because the second ask is a second run. This check reads state and writes nothing,
+// **The check is re-askable, and so is the claim it now gates — but only by the same run.** A claim
+// asked again for the issue the record names answers `hold`; for any other
+// issue it answers `busy`, because that ask is a second run. This check reads state and writes nothing,
 // so the reclaim recovery ends by asking `run:hold` again on the tree it just cleaned.
 
 const CLEAN_VERDICT = 'clean'
@@ -88,8 +88,8 @@ const STASH_LABEL_PREFIX = 'run:hold reclaimed before #'
 // The issue number reaches the advice inside a double-quoted shell command a caller is told to paste,
 // so the shape it may take is pinned beside the interpolation rather than only in the CLI that
 // happens to be today's single caller. `run:liveness` interpolates it the same way, so the pattern
-// and the refusal live in one module both read (joshuafolkken/kit#1485).
-const { require_issue_number } = run_issue_number
+// and the refusal live in one module both read.
+const { require_issue_number } = issue_number_shape
 const UNREADABLE_PR_MESSAGE = 'The pull request could not be read for branch '
 
 function needs_reclaim(tree: TreeState): boolean {
@@ -156,7 +156,7 @@ function to_reason(verdict: PreflightVerdict, tree: TreeState, child: ChildState
 }
 
 // **`-u` is not optional.** What an interrupted run leaves almost always includes a new `*.test.ts`,
-// which is untracked, and a stash without it leaves exactly those files for the `git switch` that
+// which is untracked, and a stash without it leaves exactly those files for the checkout that
 // follows to refuse over. **And the stash is recorded rather than popped**, which is what sets this
 // stash apart from every other sanctioned one: the work belongs to a run that is gone, so the Issue
 // comment is the only thing that can ever bring it back.
@@ -169,14 +169,14 @@ function reclaim_steps(tree: TreeState, issue: string): Array<string> {
 
 	return [
 		`git stash push -u -m "${STASH_LABEL_PREFIX}${issue}"`,
-		`Record the stash on #${issue} — the comment is what gets it popped; nothing pops it for you.`,
+		`Record the stash on ${session_cite.issue(issue)} — the comment is what gets it popped; nothing pops it for you.`,
 	]
 }
 
 function reclaim_advice(tree: TreeState, issue: string): string {
 	return [
 		...reclaim_steps(tree, issue),
-		`git switch ${tree.default_branch} && git pull`,
+		'pnpm josh ms',
 		'Then ask this command again: it is re-askable, and the clean tree gets its own answer.',
 	].join('\n')
 }
@@ -202,11 +202,7 @@ function decide(tree: TreeState, child: ChildState, issue: string): PreflightDec
 }
 
 function read_pr_field(raw: string): string | undefined {
-	try {
-		return pr_info_schema.parse(JSON.parse(raw)).state
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, pr_info_schema)?.state
 }
 
 function to_pr_state(raw: string): PrState {
@@ -227,11 +223,11 @@ async function read_tree_state(): Promise<TreeState> {
 
 // **An unreadable `gh` is not an absent pull request.** `pr_view` folds both into `''` and cannot tell
 // them apart, so the existence question is asked through `pr_exists`, which throws on a lookup it
-// could not complete (joshuafolkken/kit#1048). That throw reaches the CLI as `unknown`; without it a
+// could not complete. That throw reaches the CLI as `unknown`; without it a
 // rate-limited or logged-out `gh` turns a **merged** pull request into `resume`, and the run commits
 // on top of work somebody already landed — the exact hazard `park` exists for.
-// **The second half of the same guard.** `pr_view` throws on a read it could not complete
-// (joshuafolkken/kit#3263), but the two are separate round trips, so a lookup that answers empty
+// **The second half of the same guard.** `pr_view` throws on a read it could not complete,
+// but the two are separate round trips, so a lookup that answers empty
 // between them would still put a **merged** pull request back through `NO_PR` and out as `resume`.
 // An empty answer for a branch `pr_exists` has just confirmed is therefore a failed read by
 // construction, and it throws rather than answering.
@@ -335,9 +331,9 @@ interface CandidateContext {
 }
 
 // **A branch with no pull request, no commit beyond the default branch and no uncommitted change in
-// its lane holds no work** (joshuafolkken/kit#2855). A lane that ended before implementing — an
-// operational issue with no code change — leaves exactly that behind, and reading its mere existence
-// as a partial implementation sent the next `fullrun #N` to `resume` over nothing. A branch with a
+// its lane holds no work**. A lane that ended before implementing — an operational issue with no code
+// change — leaves exactly that behind, and reading its mere existence as a partial implementation
+// would send the next `fullrun #N` to `resume` over nothing. A branch with a
 // pull request is never counted: whatever its commits, the pull request is the state the verdict is
 // decided on.
 async function read_candidate(