@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/run/run-step.ts

@@ -1,14 +1,13 @@
 import { git_stash } from '#scripts/git/stash/git-stash'
+import { session_cite } from '#scripts/issue/session-cite'
 import type { CarryRead } from '#scripts/run/carry/run-carry'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import { run_retrospective } from './run-retrospective'
 
 // `josh run:step <N>` — the run's next single action, computed from three mechanical inputs and nothing
-// else (joshuafolkken/kit#2248). It is the child of epic #2166 that lifts the fold from an *event* to a
-// whole *run*: `run:next` printed one prose line for a `fullrun`'s pre-implementation position, and the
-// backlogrun loop stayed a state machine written in English that the reader rebuilt every turn. This
-// computes the position from the event stream (`run-event-stream.ts`), the carry record
+// else, so the run's loop is not a state machine written in English that the reader rebuilds every
+// turn. This computes the position from the event stream (`run-event-stream.ts`), the carry record
 // (`run-carry.ts`) and the issue state (`run-prep.ts`) — never the conversation — and prints one line.
 //
 // **The print is one of two shapes, never a procedure.** A runnable command the reader pastes, or a
@@ -24,12 +23,12 @@ import { run_retrospective } from './run-retrospective'
 const CLOSED = 'CLOSED'
 
 // The fixed verdict tokens — the non-command, non-decide answers. Kept as the oracle's declared
-// vocabulary (joshuafolkken/kit#2248), so `decision-oracle.test.ts` pins the list against these.
+// vocabulary, so `decision-oracle.test.ts` pins the list against these.
 const IMPLEMENT = 'implement'
 const HUMAN_REVIEW = 'human-review'
 const UPDATE_DEPS = 'update-deps'
 const ALREADY_DONE = 'already-done'
-// A closed issue whose lane tree still holds uncommitted work (joshuafolkken/kit#2476) — `run:step`
+// A closed issue whose lane tree still holds uncommitted work — `run:step`
 // itself prints the `decide:` line naming the stash, and this is the token `run:entry` reports.
 const KEEP_WORK = 'keep-work'
 const WAIT = 'wait'
@@ -52,15 +51,14 @@ const VOCABULARY: ReadonlyArray<string> = [
 const EXPIRED_DECISION =
 	'decide: whole-run budget spent — resume with `pnpm josh run:carry --resume` | discard with `pnpm josh run:carry --end`'
 
-// The one step a stopped run still owes before it ends: the end-of-run retrospective
-// (joshuafolkken/kit#2328). It reads the run's own measurements and files the improvements worth
-// carrying into the next run; the command is kit-only, so it means nothing — and is never printed — in a
-// consumer project.
+// The one step a stopped run still owes before it ends: the end-of-run retrospective.
+// It reads the run's own measurements and files the improvements worth carrying into the next run;
+// the command is kit-only, so it means nothing — and is never printed — in a consumer project.
 const RETROSPECTIVE_COMMAND = 'pnpm josh retrospective'
 
 // The pre-implementation verdict `run:next` degenerates to: the position of a run that has emitted no
 // event yet. `run-next.ts` maps each of these to its prose sentence, so this is the single copy of the
-// state → step mapping and there is no second implementation (joshuafolkken/kit#2248).
+// state → step mapping and there is no second implementation.
 type PreVerdict =
 	| typeof IMPLEMENT
 	| typeof HUMAN_REVIEW
@@ -73,10 +71,9 @@ interface PreInput {
 	state: string | undefined
 	is_human_review: boolean
 	latest_scope: string
-	// Whether a lane child's tree holds uncommitted work, read by `run:prep`'s gather
-	// (joshuafolkken/kit#2476). A closed issue over such a tree is not "nothing to do": the work was
-	// popped back from a park and is lost with the lane unless it is kept, so `already-done` gives way to
-	// `keep-work`.
+	// Whether a lane child's tree holds uncommitted work, read by `run:prep`'s gather.
+	// A closed issue over such a tree is not "nothing to do": the work was popped back from a park and
+	// is lost with the lane unless it is kept, so `already-done` gives way to `keep-work`.
 	has_changes: boolean
 }
 
@@ -101,36 +98,40 @@ interface StepInput extends PreInput {
 	// event is read: the position is where the run *is*, not how it got there.
 	last_event: string | undefined
 	carry_kind: CarryRead['kind']
-	// Whether this invocation's end-of-run retrospective has already run, read off the carry record
-	// (joshuafolkken/kit#2328). At the stop position it is what tells a run that still owes a
+	// Whether this invocation's end-of-run retrospective has already run, read off the carry record.
+	// At the stop position it is what tells a run that still owes a
 	// retrospective from one that has run it, so the step is printed exactly once.
 	is_retrospective_done: boolean
-	// Whether this checkout is a kit consumer rather than kit itself (joshuafolkken/kit#2328). The
+	// Whether this checkout is a kit consumer rather than kit itself. The
 	// retrospective command is kit-only — refused in a consumer — so the step is never printed there; the
 	// consumer determination is the existing `doctor-consumer.ts` one, never a new judgement.
 	is_consumer: boolean
 	issue_number: string
 	// Whether this run is a dispatched lane child, read by the CLI from the dispatch mark
 	// (`lane-child-marker.ts`). A child must never be handed `run:merge` — that is the parent's own
-	// budget command and returns `busy` in a child (joshuafolkken/kit#2267, joshuafolkken/kit#2297).
+	// budget command and returns `busy` in a child.
 	is_lane_child: boolean
-	// Whether the end-of-run retrospective is switched on, read by the CLI from `JOSH_RETROSPECTIVE`
-	// (joshuafolkken/kit#2370). It defaults **off** — the auto-filed improvement issues the step drives
+	// Whether the end-of-run retrospective is switched on, read by the CLI from `JOSH_RETROSPECTIVE`.
+	// It defaults **off** — the auto-filed improvement issues the step drives
 	// are opt-in — so a run that leaves the variable unset never prints the retrospective step, while the
 	// retrospective's own logic is untouched and `pnpm josh retrospective` still runs by hand.
 	is_retrospective_enabled: boolean
 	// Whether this session is woken when a background command it started completes, read by the CLI from
-	// the session's own environment (joshuafolkken/kit#2653). A parent without the callback cannot wait
+	// the session's own environment. A parent without the callback cannot wait
 	// on its lanes except by polling, so it hands the run to the supervisor instead of waiting.
 	has_completion_callback: boolean
 	// Whether the carried invocation has already taken its maximum cuts, read off the carry record by the
-	// CLI (joshuafolkken/kit#2346). At the cap `run:carry --cut` refuses, so the hand-off is not offered.
+	// CLI. At the cap `run:carry --cut` refuses, so the hand-off is not offered.
 	is_at_cut_cap: boolean
 	// Whether the carry record has been handed off by a cut and no successor has adopted it yet, read off
-	// the record by the CLI (joshuafolkken/kit#2760) and set only in the session that declared the record.
+	// the record by the CLI and set only in the session that declared the record.
 	// The session that took the cut is the only one that can read this — a successor spends the mark when
 	// it begins — so it is what tells that session to stop.
 	is_handed_off: boolean
+	// Whether this run launched the issue and its stream holds no `merge` for it yet, read by the CLI.
+	// A parent that reads a closed child as `already-done` never runs
+	// `run:merge`, so the merge is never written and `run:board` shows the child running forever.
+	is_merge_owed: boolean
 }
 
 interface StepAction {
@@ -146,26 +147,30 @@ function command(line: string): StepAction {
 	return { kind: 'command', line }
 }
 
+function merge_command(issue_number: string): StepAction {
+	return command(`pnpm josh run:merge ${issue_number}`)
+}
+
 // The action for each event a run can be positioned at, keyed on the newest one. Each dispatches to the
 // command that owns that phase. `stop`, `drain` and `child-launch` are handled apart in
 // `FULL_INPUT_ACTIONS`, because each needs more than the issue number. A merge and an outage share a
 // next step: `run:merge` classifies both, including the outage's stop condition.
 const KIND = run_event_stream.EVENT_KIND
-// A park and a stall share this next step: both mean runnable work is waiting to be offered
-// (joshuafolkken/kit#2359), so both are pointed at the backlog.
+// A park and a stall share this next step: both mean runnable work is waiting to be offered,
+// so both are pointed at the backlog.
 const OFFER_BACKLOG = 'pnpm josh backlog:next'
 const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 	[KIND.PR_OPENED]: () => command('pnpm josh followup'),
 	[KIND.REVIEW_ROUND]: () => command('pnpm josh review:round2'),
-	[KIND.MERGE]: (issue_number) => command(`pnpm josh run:merge ${issue_number}`),
-	[KIND.OUTAGE]: (issue_number) => command(`pnpm josh run:merge ${issue_number}`),
+	[KIND.MERGE]: merge_command,
+	[KIND.OUTAGE]: merge_command,
 	[KIND.PARK]: () => command(OFFER_BACKLOG),
 	[KIND.CUT]: (issue_number) => command(`pnpm josh run:cut --resume ${issue_number}`),
 	// A stall is undispatched ready work with a free lane, so its next step is exactly a park's: offer
 	// the backlog. The detector only reports the stall; reading it here as a dispatch is what turns the
 	// report into the action that resolves it.
 	[KIND.STALL]: () => command(OFFER_BACKLOG),
-	// The post-implementation region is with a detached ship supervisor (joshuafolkken/kit#2428): nothing
+	// The post-implementation region is with a detached ship supervisor: nothing
 	// is the agent's until the supervisor stops or the issue closes, which the terminal read answers.
 	[KIND.SHIP_LAUNCH]: () => verdict(WAIT),
 	// The supervisor stopped at a failed stage and handed control back — the next step is reading the
@@ -174,29 +179,28 @@ const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
 }
 
 // The parent-only positions a dispatched lane child must never act on. `run:merge` is the parent's
-// budget command — a child that ran it read the `busy` it got back as a competing session and parked
-// its Issue unimplemented (joshuafolkken/kit#2267). A merge or an outage is the parent's to classify,
-// so a child at one has nothing to run and stops rather than being handed `run:merge`
-// (joshuafolkken/kit#2297).
+// budget command — a child that ran it would read the `busy` it got back as a competing session and
+// park its Issue unimplemented. A merge or an outage is the parent's to classify, so a child at one
+// has nothing to run and stops rather than being handed `run:merge`.
 const PARENT_ONLY_EVENTS: ReadonlySet<string> = new Set([KIND.MERGE, KIND.OUTAGE])
 
 // A stopped run's last owed step is the end-of-run retrospective. When it is not owed the position stops
-// with no command to run, which is what the position meant before the retrospective existed.
+// with no command to run.
 function stop_action(input: StepInput): StepAction {
 	return run_retrospective.is_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(STOP)
 }
 
-// The drain fires the retrospective *before* the idle watch, not after it (joshuafolkken/kit#2335): the
-// retrospective files the improvement issues the watch then picks up, so running it after the watch — as
-// the stop position alone did — spent the watch on an empty pool. When the retrospective is not owed the
+// The drain fires the retrospective *before* the idle watch, not after it: the
+// retrospective files the improvement issues the watch then picks up, so running it after the watch
+// would spend the watch on an empty pool. When the retrospective is not owed the
 // run proceeds to that watch, which is a `WAIT` rather than a `STOP`: the backlog is empty but the run is
 // not ending, and the real `STOP` follows when the watch expires with the retrospective already done.
 function drain_action(input: StepInput): StepAction {
 	return run_retrospective.is_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
 }
 
-// The hand-off a `backlogrun` parent without a completion callback takes right after dispatching
-// (joshuafolkken/kit#2653). It is the existing merge-time cut, so the ownership check and the cut cap
+// The hand-off a `backlogrun` parent without a completion callback takes right after dispatching.
+// It is the existing merge-time cut, so the ownership check and the cut cap
 // apply unchanged, and the supervisor's driver adopts the in-flight lanes from their `child-launch`
 // events.
 const HAND_OFF_COMMAND = 'pnpm josh run:carry --cut --owner "$PPID"'
@@ -237,14 +241,14 @@ function event_action(event: string, issue_number: string, is_lane_child: boolea
 
 // A run that has planned but emitted nothing else is still at its pre-implementation position, so a
 // `plan` reads the same as an empty stream. A resume from an implementation cut is back at the same
-// position (joshuafolkken/kit#3375): read as the `cut` it follows, it pointed at the spent resume again.
+// position: read as the `cut` it follows, it would point at the spent resume again.
 const IMPLEMENTATION_POSITIONS: ReadonlySet<string> = new Set([KIND.PLAN, KIND.RESUME])
 
 function is_pre_implementation(last_event: string | undefined): boolean {
 	return last_event === undefined || IMPLEMENTATION_POSITIONS.has(last_event)
 }
 
-// **No cut at the setup→implementation boundary** (joshuafolkken/kit#2489). A lane child's context is
+// **No cut at the setup→implementation boundary**. A lane child's context is
 // bounded by the threshold-gated implementation cut alone (`implementation-cut.ts`): the first edit is
 // the moment both would have looked at, and below the threshold a cut there is one that does not pay
 // for itself (`context-cut-payback.ts`), so a planned lane child implements in the same session.
@@ -252,23 +256,30 @@ function pre_implementation_action(input: StepInput): StepAction {
 	return verdict(pre_verdict(input))
 }
 
+// A parent whose child closed before `run:merge` wrote the merge still owes it:
+// `run:merge` is the one writer of the `merge` event, so answering `already-done` here would leave the
+// child running on `run:board` forever. A lane child is never handed `run:merge`.
+function owes_merge(input: StepInput): boolean {
+	return input.is_merge_owed && input.carry_kind === 'carried' && !input.is_lane_child
+}
+
 // A closed issue ends the run, but a tree still holding uncommitted work is surfaced rather than
-// answered `already-done` — the answer a child read as "nothing to do" before its lane was removed
-// with the work in it (joshuafolkken/kit#2476).
+// answered `already-done` — the answer a child reads as "nothing to do" before its lane is removed
+// with the work in it.
 function closed_action(input: StepInput): StepAction {
+	if (owes_merge(input)) return merge_command(input.issue_number)
 	if (closed_verdict(input) === ALREADY_DONE) return verdict(ALREADY_DONE)
 
 	const message = git_stash.work_message(input.issue_number, ALREADY_DONE)
 
 	return {
 		kind: 'decide',
-		line: `decide: #${input.issue_number} is closed but this tree holds uncommitted work — keep it with \`git stash push -u -m "${message}"\` | carry it into a new issue`,
+		line: `decide: ${session_cite.issue(input.issue_number)} is closed but this tree holds uncommitted work — keep it with \`git stash push -u -m "${message}"\` | carry it into a new issue`,
 	}
 }
 
-// **A cut hands the run on, so the session that took it stops** (joshuafolkken/kit#2760). The driver had
-// no handed-off state, so after `run:carry --cut` it went on answering `wait` or the next offer — a
-// `backlogrun` parent measured at 233k kept launching children in the same conversation up to 294k. A
+// **A cut hands the run on, so the session that took it stops** — otherwise it would go on answering
+// `wait` or the next offer after `run:carry --cut`, launching children in the same conversation. A
 // lane child never holds the carry record, so its own position is not decided here.
 function is_handed_off_parent(input: StepInput): boolean {
 	return input.is_handed_off && input.carry_kind === 'carried' && !input.is_lane_child

package/scripts/run/run-stop-notify.ts

@@ -1,12 +1,11 @@
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 import type { CarryRead } from '#scripts/run/carry/run-carry'
 
-// **A `backlogrun` that halts because a person is needed used to reach nobody once the session was
-// cut** (joshuafolkken/kit#2136). Every remaining child blocked behind a parked one, the backlog
-// drained of anything runnable, the failure streak tripped — each ends the run, and while the session
-// was the person's the stop was there in the conversation. After a cut the parent is a headless
-// `claude -p backlogrun`, so the stop reached its own transcript and nowhere else, and the run sat
-// stopped until someone thought to ask. The 15-minute heartbeat stays a pull; a *stop* is a state
+// **A `backlogrun` that halts because a person is needed must reach them after a session cut.** Every
+// remaining child blocked behind a parked one, the backlog drained of anything runnable, the failure
+// streak tripped — each ends the run, and while the session is the person's the stop is there in the
+// conversation. After a cut the parent is a headless `claude -p backlogrun`, so the stop would reach
+// its own transcript and nowhere else. The 15-minute heartbeat stays a pull; a *stop* is a state
 // change, and a state change is what `confirmation` exists to push.
 //
 // **This is the decision, kept apart from the send so the dedup can be pinned without a Telegram.**
@@ -21,8 +20,8 @@ const STOP_TITLE = 'backlogrun stopped'
 const STOP_RECOVERY =
 	'If this did not arrive, `pnpm josh run:wake --list` relays the last progress line.'
 
-// **Only a stop over a record that is still there is announced, and that is the whole of the dedup**
-// (joshuafolkken/kit#2136). `--end` removes the record, so a second `--end --stopped` — a retried
+// **Only a stop over a record that is still there is announced, and that is the whole of the dedup**.
+// `--end` removes the record, so a second `--end --stopped` — a retried
 // turn, a re-evaluation — reads `none` and plans nothing, which is why one event never sends twice. A
 // clean finish passes no reason and stays silent, because a completed run has its own notification and
 // this type is for the run that halted needing a person. An `unreadable` record is not announced: with

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

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { run_stranded } from './run-stranded'
 import { run_stranded_detect } from './run-stranded-detect'
 
-// `josh run:stranded` — read the three facts once and print the verdict (joshuafolkken/kit#2375). This
+// `josh run:stranded` — read the three facts once and print the verdict. This
 // is the manual and testable face of the detector `stop-guard.ts` runs on every stop; both call the one
 // `detect_and_report`, so the command and the hook can never drift.
 //

package/scripts/run/run-stranded-detect.ts

@@ -10,10 +10,10 @@ import {
 	type SupervisorLiveness,
 } from './run-stranded'
 
-// The I/O half of the strand detector (joshuafolkken/kit#2375): it gathers the three facts the pure
+// The I/O half of the strand detector: it gathers the three facts the pure
 // judge in `run-stranded.ts` weighs, then — on a strand — leaves the marker and sends the one
 // notification. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary beside the
-// stall detector it mirrors (joshuafolkken/kit#2359); the CLI exposes the same call for a person to run
+// stall detector it mirrors; the CLI exposes the same call for a person to run
 // by hand.
 //
 // **Cheap and local.** Every read is a file on disk — the carry record, the wake record — and a process
@@ -23,8 +23,8 @@ import {
 
 // The recovery line names the command that hands the run to a fresh supervisor — the same one the pure
 // judge holds, so the notification and the recovery can never drift. It is deliberately not
-// `run:carry --resume`: the cutting session is refused `busy` and must stay refused
-// (joshuafolkken/kit#1935), so recovery is another actor's.
+// `run:carry --resume`: the cutting session is refused `busy` and must stay refused,
+// so recovery is another actor's.
 const STRAND_RECOVERY = `Restart supervision with \`${run_stranded.RECOVERY_COMMAND}\` — it wakes a fresh successor to claim the budget; the cutting session must not resume it itself.`
 
 // The seams a test replaces: the two record targets, the two record reads, the owner and supervisor

package/scripts/run/run-stranded.ts

@@ -2,12 +2,10 @@ import { process_identity } from '#scripts/josh/process-identity'
 import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
 import type { RunWake } from '#scripts/run/wake/run-wake'
 
-// The mechanical judge of a *stranded* run (joshuafolkken/kit#2375). On 2026-09-22 a `backlogrun`'s
-// cost hand-off left the record carried and handed off, the session that cut it died, no successor ever
-// claimed the budget, and no supervisor was watching — so five lanes ran on with nobody driving, and the
-// only way forward was a person noticing and running the recovery by hand. Three facts, read and never
-// weighed, are what say that state has been reached: the budget was handed off, its owner is gone, and
-// no supervisor is alive to wake a successor.
+// The mechanical judge of a *stranded* run: a handed-off budget whose cutting session died, with no
+// successor claiming it and no supervisor watching, so lanes run on with nobody driving. Three facts,
+// read and never weighed, are what say that state has been reached: the budget was handed off, its
+// owner is gone, and no supervisor is alive to wake a successor.
 //
 // **Pure by design, exactly as `backlog-stalled.ts` is.** The carry read, the owner's liveness and the
 // supervisor's are handed in, so the four acceptance cases — all three holding, a live owner, a claimed
@@ -18,7 +16,7 @@ import type { RunWake } from '#scripts/run/wake/run-wake'
 // **It is a report, never a stop.** A false positive costs one notification, never a halted run or a
 // torn-down lane — so every axis is read toward *not* stranded when it cannot be proven: an unreadable
 // carry record is not stranded, and a supervisor whose liveness cannot be established counts as watching.
-// **And recovery is another actor's, not the reader's** (joshuafolkken/kit#1935): the cutting session is
+// **And recovery is another actor's, not the reader's**: the cutting session is
 // refused `busy` and must stay refused, so what the notification names is `run:wake --start`, which
 // starts a supervisor that wakes a *fresh* successor rather than driving the run itself.
 
@@ -27,7 +25,7 @@ import type { RunWake } from '#scripts/run/wake/run-wake'
 // which is the `busy` refusal `run-carry.ts` → `is_count_refused` exists to keep.
 const RECOVERY_COMMAND = 'pnpm josh run:wake --start'
 
-// The three answers a supervisor's liveness probe gives, named (joshuafolkken/kit#2375). `live` is a
+// The three answers a supervisor's liveness probe gives, named. `live` is a
 // supervisor still watching, `gone` is one whose process has died or a record that was never there at
 // all, and `unknown` is the platform answering for nobody — a pid that is alive paired with a start
 // token this machine could not read. The three are kept apart because the strand judge resolves
@@ -53,11 +51,11 @@ interface StrandedInput {
 	supervisor: SupervisorLiveness
 }
 
-// **The supervisor's liveness, three-valued** (joshuafolkken/kit#2375). An absent wake record is `gone`:
-// `run:wake --list` reported `none` in the run this fixes, and nothing watching is the very state a
-// strand needs. A present record is read through `process_identity.is_same_process`, whose own three
-// answers this passes straight through — `true` is `live`, `false` is `gone`, and the platform's "cannot
-// tell" is `unknown`. The prober is injected so the three cases are tested without a real process.
+// **The supervisor's liveness, three-valued.** An absent wake record is `gone`: nothing watching is
+// the very state a strand needs. A present record is read through `process_identity.is_same_process`,
+// whose own three answers this passes straight through — `true` is `live`, `false` is `gone`, and the
+// platform's "cannot tell" is `unknown`. The prober is injected so the three cases are tested without
+// a real process.
 function supervisor_liveness(
 	wake: RunWake | undefined,
 	same_process: (

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

@@ -1,29 +1,29 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { run_tail, type TailSection } from './run-tail'
 
-// `josh run:tail [<N> ...]` — one call for the fixed post-merge sequence a run closes on
-// (joshuafolkken/kit#2372). The loop used to spend a round trip on `observations:flush`, one on
-// `issue:cite` and one on `release:scope`, re-billing a lane's full context each time; this runs the
-// three internally and prints one composite report, the same way `backlog:offer` chains its two calls
-// and `run:prep` bundles three reads. Each step's stderr is forwarded, so the reader still sees every
-// explanation the three would have printed on their own.
+// `josh run:tail [<N> ...]` — one call for the fixed post-merge sequence a run closes on.
+// It runs `observations:flush`, `issue:cite` and `release:scope` internally, so no round trip per step
+// re-bills a lane's full context, and prints one composite report, the same way
+// `backlog:offer` chains its two calls and `run:prep` bundles three reads. Each
+// step's stderr is forwarded, so the reader still sees every explanation the three would have
+// printed on their own.
 //
 // The issue numbers are the completion's citations — the closed issue and any follow-ups filed this run
 // — and go to `issue:cite`; the other two take none. A `run:tail` with no numbers still closes the run,
 // because `issue:cite` with no target exits zero.
 //
-// **A dispatched lane child skips the ledger step** (joshuafolkken/kit#2492). A flush opens a
+// **A dispatched lane child skips the ledger step**. A flush opens a
 // ledger-only pull request and waits out its whole CI before it merges — minutes per issue, spent on a
 // file only the retrospective and the measurements read — and a lane has nothing for it: its lines
-// merged with its own pull request (joshuafolkken/kit#2919). A single run outside a lane keeps the
+// merged with its own pull request. A single run outside a lane keeps the
 // step for a line written on the default branch outside any issue's run.
 
 const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh run:tail [<issue-number> ...]'
 const should_forward_stderr = true
 
@@ -33,14 +33,13 @@ interface Step {
 }
 
 // The steps in the order a run closes on: the checkout returns to the default branch, any ledger line
-// the run's own commit did not carry (joshuafolkken/kit#2763) is committed so the recurrence count is on
+// the run's own commit did not carry is committed so the recurrence count is on
 // main — on most runs the flush answers `clean` — the citations are read for the completion report, and
 // the release scope is decided last.
 //
-// **The return comes first because the flush refuses anywhere else** (joshuafolkken/kit#2979). A run
-// closes right after its merge, still on the feature branch it shipped from, and `josh ship` reaches
-// this report with nothing in between — so the flush stopped a merged run as failed. `main:sync` is the
-// step a person used to type after the fact; it fast-forwards the local default branch before the
+// **The return comes first because the flush refuses anywhere else**. A run closes right
+// after its merge, still on the feature branch it shipped from, and `josh ship` reaches this report
+// with nothing in between. `main:sync` fast-forwards the local default branch before the
 // checkout, so a ledger line appended after the merge is carried along rather than refused.
 const LEDGER_STEPS: ReadonlyArray<Step> = [
 	{ header: run_tail.SYNC_HEADER, argv: () => ['main:sync'] },
@@ -58,7 +57,7 @@ function steps_for(is_lane_child: boolean): ReadonlyArray<Step> {
 // Numbers only — a target `issue:cite` reads as an issue, so a stray flag is refused rather than
 // forwarded to the wrong step.
 function parse_issues(argv: ReadonlyArray<string>): ReadonlyArray<string> | undefined {
-	if (argv.every((token) => ISSUE_NUMBER_PATTERN.test(token))) return argv
+	if (argv.every((token) => issue_number_shape.is_issue_number(token))) return argv
 
 	return undefined
 }
@@ -74,7 +73,7 @@ async function run_step(step: Step, issues: ReadonlyArray<string>): Promise<Tail
 }
 
 // Run the steps in order, not concurrently: the ledger commit must land on main before the release scope
-// reads main's pending count, and the order is what a lane spent three turns on.
+// reads main's pending count.
 async function close_run(issues: ReadonlyArray<string>): Promise<ReadonlyArray<TailSection>> {
 	const sections: Array<TailSection> = []
 

package/scripts/run/run-tail.ts

@@ -1,5 +1,5 @@
-// `josh run:tail [<N> ...]` — the one call that closes a run (joshuafolkken/kit#2372). It folds the
-// fixed post-merge bookkeeping a lane spends three separate round trips on — commit the observation
+// `josh run:tail [<N> ...]` — the one call that closes a run. It folds the fixed
+// post-merge bookkeeping that would otherwise take three separate round trips — commit the observation
 // ledger (`observations:flush`), read the completion citations (`issue:cite`), and decide whether a
 // release is owed (`release:scope`) — into one composite, the same shape `run:prep` bundles three reads
 // on. None of the three needs a decision between it and the next, so nothing the reader had to judge is
@@ -9,53 +9,34 @@
 // each step's output under a header and answers the exit code from the collected codes, so a test pins
 // the composite without a ledger ever being committed or a release ever read.
 
+import { run_section, type Section } from './run-section'
+
 const SYNC_HEADER = '=== sync ==='
 const OBSERVATIONS_HEADER = '=== observations ==='
 const CITATIONS_HEADER = '=== citations ==='
 const RELEASE_HEADER = '=== release ==='
-const SECTION_SEPARATOR = '\n\n'
-
-const SUCCESS_EXIT_CODE = 0
-const FAILURE_EXIT_CODE = 1
-
-interface TailSection {
-	header: string
-	body: string
-	code: number
-}
-
-function section_report(section: TailSection): string {
-	return `${section.header}\n${section.body}`
-}
 
-function format_report(sections: ReadonlyArray<TailSection>): string {
-	return sections.map((section) => section_report(section)).join(SECTION_SEPARATOR)
-}
+type TailSection = Section
 
-// **A failed step's stderr joins its body** (joshuafolkken/kit#2462). A detached run's log keeps the
-// report, not the terminal, so a refusal printed only to stderr left the section reading
-// `ELIFECYCLE` alone. A passing step's stderr is commentary and stays out of the report.
+// **A failed step's stderr joins its body.** A detached run's log keeps the report, not the
+// terminal, so a refusal printed only to stderr would leave the section reading `ELIFECYCLE` alone. A
+// passing step's stderr is commentary and stays out of the report.
 function section_body(out: string, error_output: string | undefined, code: number): string {
-	if (code === SUCCESS_EXIT_CODE || error_output === undefined) return out
+	if (error_output === undefined || code === run_section.SUCCESS_EXIT_CODE) return out
 
 	return [out, error_output].filter((part) => part.length > 0).join('\n')
 }
 
-// Non-zero when any step failed, exactly as each of the three exits on its own — a bundle where the
-// ledger commit failed is never read as a clean close because the citations after it succeeded.
-function exit_code(sections: ReadonlyArray<TailSection>): number {
-	const is_clean = sections.every((section) => section.code === SUCCESS_EXIT_CODE)
-
-	return is_clean ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
-}
-
+// The exit code is non-zero when any step failed, exactly as each of the three exits on its own — a
+// bundle where the ledger commit failed is never read as a clean close because the citations after it
+// succeeded.
 const run_tail = {
 	CITATIONS_HEADER,
 	OBSERVATIONS_HEADER,
 	RELEASE_HEADER,
 	SYNC_HEADER,
-	exit_code,
-	format_report,
+	exit_code: run_section.exit_code_of,
+	format_report: run_section.format_sections,
 	section_body,
 }
 

package/scripts/run/run-watcher-guard-cli.ts

@@ -4,10 +4,9 @@ import { run_progress_read } from '#scripts/run/progress/run-progress-read'
 import { run_watcher_guard } from './run-watcher-guard'
 
 // `josh run:watcher:guard` — refuses when lane children are in-flight but the progress watcher has not
-// pinged its life record recently (joshuafolkken/kit#2113). This is the hand-run form, kept for a run
-// that calls it before a loop iteration; the *automatic* wiring is in `pretool-guard.ts`, which
-// composes the same guard through `run-watcher-hook.ts` so every tool call is checked
-// (joshuafolkken/kit#2353).
+// pinged its life record recently. This is the hand-run form, kept for a run that calls it before a
+// loop iteration; the *automatic* wiring is in `pretool-guard.ts`, which composes the same guard
+// through `run-watcher-hook.ts` so every tool call is checked.
 //
 // **Exits 0 (ok) or 1 (stale).** A non-zero exit is what the hook mechanism treats as a refusal —
 // the same contract `batch:guard` and `rule:guard` hold.

package/scripts/run/run-watcher-guard.ts

@@ -4,18 +4,17 @@ import { run_headless } from './run-headless'
 
 // A watcher that stopped while children are still in-flight leaves the run's event stream without a
 // heartbeat and the parent without the wake an arrival would deliver. This guard detects that state so
-// a hook can refuse the calls that follow a missed restart (joshuafolkken/kit#2113).
+// a hook can refuse the calls that follow a missed restart.
 //
 // **Staleness threshold is `TICK_MULTIPLIER` watcher ticks.** The watcher pings its life record on
 // every tick (every 30 s), so a gap wider than three ticks means the process has almost certainly
 // stopped: it exited on an arrival, its bound expired, or the session was cut without a restart. A
-// report is no longer one of those (joshuafolkken/kit#3102) — `--wait` streams its reports and keeps
-// running — so a restart is owed only after an exit the parent was woken for. Three gives one missed
-// tick of slack before the guard fires.
+// report is not one of those — `--wait` streams its reports and keeps running — so a restart is owed
+// only after an exit the parent was woken for. Three gives one missed tick of slack before the guard
+// fires.
 //
-// **It watches no relay** (joshuafolkken/kit#2492). A session following the run's event stream after a
-// cut used to be held to it here; that relay re-read the session's whole history per event, so the
-// stream is now watched from a pane of its own (`run:event --watch`) and no session owes it.
+// **It watches no relay.** A relay would re-read the session's whole history per event, so the stream
+// is watched from a pane of its own (`run:board`) and no session owes it.
 
 const WATCHER_TICK_MS = 30_000
 const TICK_MULTIPLIER = 3
@@ -34,11 +33,11 @@ type GuardResult = { kind: 'ok' } | { kind: 'stale'; note: string }
 
 const OK_RESULT: GuardResult = { kind: 'ok' }
 
-// **Only the run that opened the lanes owes them a watcher** (joshuafolkken/kit#2965). The lane listing
-// is machine-wide, so a session with no run of its own — an investigation, a `fullrun` beside a batch —
-// used to be refused for another run's lanes. The session that drives the live `backlogrun` carry
-// record is the one that dispatched them; every other session passes. A session `run:wake` woke owes
-// none either (joshuafolkken/kit#3245): the supervisor's driver watches the lanes, and the woken session
+// **Only the run that opened the lanes owes them a watcher**. The lane listing is
+// machine-wide, so without this a session with no run of its own — an investigation, a `fullrun`
+// beside a batch — would be refused for another run's lanes. The session that drives the live
+// `backlogrun` carry record is the one that dispatched them; every other session passes. A session
+// `run:wake` woke owes none either: the supervisor's driver watches the lanes, and the woken session
 // only acts on the branch it was handed and cuts.
 async function owes_watcher(): Promise<boolean> {
 	if (run_headless.is_headless() || !(await run_headless.is_backlog_parent())) return false