@joshuafolkken/kit 1.1035.0 → 1.1050.0

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

@@ -6,8 +6,13 @@ import { scoped_green } from '#scripts/gate/scoped-green'
 import { change_base } from '#scripts/git/change-base'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_command } from '#scripts/git/git-command'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { find_package_directory } from '#scripts/josh/josh-logic'
 import { path_decision } from '#scripts/josh/path-decision'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { openai_review_broker } from '#scripts/lane/openai-review-broker'
+import { run_ship_review } from '#scripts/run/run-ship-review'
 import { review_attest } from './review-attest'
 import { review_brief } from './review-brief'
 import { review_checkout, type ReviewCheckout } from './review-checkout'
@@ -134,13 +139,54 @@ function record_round_one(
 // failed to record would hand the review a command that cannot succeed and the run a check that
 // answers `not-required` — the guard gone, silently, which is the shape this whole record exists to
 // remove.
-async function open_contract(): Promise<{ checkout: ReviewCheckout; nonce: string }> {
+//
+// **Whether this is a resume is read first** (joshuafolkken/kit#2945): `record_target` drops the
+// previous nonce's records, so asked afterwards the finished review would always read as absent. The
+// findings file is the ship's, keyed on `PROJECT_ROOT` as the ship keys it; a review run outside the
+// ship writes none, so it never reads as a resume and keeps the whole change.
+//
+// **The narrowing is measured from the tree that review was briefed on**, and only when that record
+// was written by the brief the pointer names: one left by an earlier brief is not the tree the
+// finished review read, so the resume reads the whole change instead.
+function attested_tree(checkout: ReviewCheckout): FileMapStamp | undefined {
+	const { findings } = openai_review_broker.review_paths(PROJECT_ROOT)
+	const briefed = review_stamps.briefed_stamp.read()
+
+	if (briefed === undefined || !review_attest.is_briefed_since(briefed.taken_at, checkout.root)) {
+		return undefined
+	}
+
+	const is_clean =
+		review_attest.is_reviewed_on(checkout, findings, checkout.root) &&
+		run_ship_review.is_clean_round_one(stamp_file.read_stamp_text(findings))
+
+	return is_clean ? briefed : undefined
+}
+
+async function open_contract(): Promise<{
+	checkout: ReviewCheckout
+	nonce: string
+	resumed_from: FileMapStamp | undefined
+}> {
 	const checkout = await review_checkout.read_checkout()
+	const resumed_from = attested_tree(checkout)
 
 	// Keyed on the root git just answered with, never on `process.cwd()`: the check made before the
 	// merge asks git the same question, and the two hash different keys the moment one of them runs
 	// from a subdirectory — a mismatch that would drop the guard with nothing printed.
-	return { checkout, nonce: review_attest.record_target(checkout, checkout.root) }
+	return { checkout, nonce: review_attest.record_target(checkout, checkout.root), resumed_from }
+}
+
+// Retaken on every round-1 brief, after the pointer it pairs with (joshuafolkken/kit#2945). Swallowed:
+// a record that failed to write predates the next pointer, so the resume widens rather than narrows.
+function record_briefed(round: number, tree: Record<string, string>, base?: string): void {
+	if (round !== FIRST_ROUND) return
+
+	try {
+		review_stamps.briefed_stamp.write(tree, undefined, base)
+	} catch {
+		/* no record widens the resume rather than narrowing it */
+	}
 }
 
 interface ComposeRequest {
@@ -252,6 +298,7 @@ async function run_review(round: number, reading: ChangeReading): Promise<number
 	if (resolved.kind === 'rejected') return report_error(resolved.note)
 	console.info(await compose_brief({ round, paths, tree, base, profile: resolved.profile }))
 	record_round_one(round, tree, commit)
+	record_briefed(round, tree, commit)
 
 	return 0
 }

package/scripts/review/review-brief.ts

@@ -357,6 +357,39 @@ function round_two_block(
 	return narrow_block(scope.recorded_at, scope, root, base)
 }
 
+// **A resumed round 1 reads what changed since the attested review, reusing round 2's reconciliation**
+// (joshuafolkken/kit#2945). A ship that stopped and was re-issued briefed the whole change again, so
+// the reviewer re-read every file the attested review had just read. The scope is the comparison round
+// 2 makes, measured from the tree that review was briefed on. Every reading that cannot narrow falls back to the whole
+// change: no record, a moved base, or an empty target. An empty target is included because a resumed
+// review that read nothing would report a clean verdict over the one already recorded.
+const RESUMED_HEADING =
+	'Resumed round 1 — a review of this branch was already attested, so this pass reads only what changed since the tree it read.'
+
+const RESUMED_QUESTION =
+	'Review these files in full against the rubric — they are the only code this pass has not already read.'
+
+function resumed_target(
+	snapshot: FileMapStamp | undefined,
+	tree: Record<string, string>,
+	root: string,
+	base: string,
+): string {
+	const scope = round_two_scope(snapshot, tree, base)
+
+	if (scope.recorded_at === undefined || scope.target.length === 0) {
+		return whole_change_target(root, base)
+	}
+
+	return [
+		RESUMED_HEADING,
+		`The attested review read the tree recorded at ${scope.recorded_at}.`,
+		`Target: only these files, which changed since that tree:\n${format_paths(root, scope.target)}`,
+		...reconciliation(root, base, scope),
+		RESUMED_QUESTION,
+	].join('\n')
+}
+
 interface BriefStamps {
 	gate: FileMapStamp | undefined
 	in_flight: FileMapStamp | undefined
@@ -377,12 +410,23 @@ interface BriefInput {
 	// The rubric's absolute path, resolved by the caller against the kit package rather than the review
 	// checkout, so it resolves in a consumer that ships no `prompts/` of its own (joshuafolkken/kit#2402).
 	rubric_path: string
+	// The tree a finished, clean review of this branch was briefed on, so round 1 is a resume
+	// (joshuafolkken/kit#2945). Absent, round 1 reads the whole change.
+	resumed_from?: FileMapStamp | undefined
 }
 
 const SECOND_ROUND = 2
 
+function round_one_target(input: BriefInput): string {
+	const { root } = input.checkout
+
+	if (input.resumed_from === undefined) return whole_change_target(root, input.base)
+
+	return resumed_target(input.resumed_from, input.tree, root, input.base)
+}
+
 function target_block(input: BriefInput): string {
-	if (input.round < SECOND_ROUND) return whole_change_target(input.checkout.root, input.base)
+	if (input.round < SECOND_ROUND) return round_one_target(input)
 
 	return round_two_block(input.stamps.round_one, input.tree, input.checkout.root, input.base)
 }
@@ -422,6 +466,7 @@ const review_brief = {
 	green_stamp,
 	in_flight_line,
 	live_marker,
+	RESUMED_HEADING,
 	matching_stamp,
 	no_snapshot_line,
 	NOTHING_LEFT_LINE,

package/scripts/review/review-stamps.ts

@@ -59,10 +59,15 @@ const TEST_RELATED_PREFIX = 'josh-test-related-stamp-'
 const GATE_PREFIX = 'josh-gate-stamp-'
 const IN_FLIGHT_PREFIX = 'josh-gate-running-'
 const ROUND_ONE_PREFIX = 'josh-review-round1-'
+const BRIEFED_PREFIX = 'josh-review-briefed-'
 
 const gate_stamp: FileMapStampAccess = file_map_stamp.create(GATE_PREFIX, PROJECT_ROOT)
 const in_flight_stamp: FileMapStampAccess = file_map_stamp.create(IN_FLIGHT_PREFIX, PROJECT_ROOT)
 const round_one_stamp: FileMapStampAccess = file_map_stamp.create(ROUND_ONE_PREFIX, PROJECT_ROOT)
+// **The tree the latest round-1 brief handed out, retaken on every brief** (joshuafolkken/kit#2945).
+// The round-1 snapshot is kept from the first brief of a run, so it is not the tree a later review
+// read — a resume narrowed against it would skip a file put back to that older content.
+const briefed_stamp: FileMapStampAccess = file_map_stamp.create(BRIEFED_PREFIX, PROJECT_ROOT)
 const lint_related_stamp: FileMapStampAccess = file_map_stamp.create(
 	LINT_RELATED_PREFIX,
 	PROJECT_ROOT,
@@ -97,6 +102,8 @@ function clear_round_one(target?: string): void {
 }
 
 const review_stamps = {
+	BRIEFED_PREFIX,
+	briefed_stamp,
 	clear_round_one,
 	GATE_PREFIX,
 	gate_stamp,

package/scripts/rules/implementation-cut.ts

@@ -50,7 +50,7 @@ function is_impl_cut_segment(segment: string): boolean {
 }
 
 // Whether this command takes the implementation-phase cut, segment-wise so a spelling quoted inside a
-// body is not read as the call, and alias-expanded so `pnpm josh rct --impl` is the same call.
+// body is not read as the call.
 function takes_the_impl_cut(command: string): boolean {
 	return shell_segments.segments_of(command).some((segment) => is_impl_cut_segment(segment))
 }

package/scripts/rules/issue-fold.ts

@@ -21,8 +21,7 @@ import { tail_commands } from './tail-commands'
 // "fold first". **No new predicate**: the filing trigger is `bash_triggers.is_issue_filing`, and the
 // prior-filing count is `filing_cap.prior_filing_count`, both reused verbatim.
 
-// `pnpm josh issue:fold`, the one act the rule asks for. The alias `isf` is expanded where the command
-// is read, so the canonical name matches both spellings.
+// `pnpm josh issue:fold`, the one act the rule asks for.
 const FOLD_NAMES: ReadonlySet<string> = new Set(['issue:fold'])
 
 // Keeping the rule: a call that runs the fold. Segment-wise, so a spelling quoted inside a filing's

package/scripts/rules/lane-carry-conflict.ts

@@ -29,8 +29,7 @@ import { shell_segments } from './shell-segments'
 
 // The parent backlogrun budget/ownership commands. A child never runs either: `run:carry` begins and
 // advances the run budget the parent owns, and `run:merge` counts a returned child into it. Named in
-// canonical form only — `shell_segments.is_josh_command` canonicalizes an alias (`rc`, `rmg`) before
-// the match, so `pnpm josh rmg` arrives as `run:merge`.
+// canonical form only — `shell_segments.is_josh_command` canonicalizes an alias before the match.
 const RUN_BUDGET_COMMANDS: ReadonlySet<string> = new Set(['run:merge', 'run:carry'])
 
 // A segment that invokes one of the parent's budget commands. Segment-wise and alias-expanded for the

package/scripts/rules/lane-park.ts

@@ -30,8 +30,7 @@ import { shell_segments } from './shell-segments'
 // the stop, the reason is a checklist rather than an accusation, and a child that already parked simply
 // reissues. One wasted round trip on the compliant path is the safe direction; a missed park is not.
 
-// `josh notify`, in either spelling — the alias `nf` is expanded to `notify` before this sees it, the
-// same way `pre-gate-cut.ts` matches `gate` through `ga`.
+// `josh notify`, named canonically — `shell_segments.is_josh_command` expands an alias before the match.
 const NOTIFY_COMMANDS: ReadonlySet<string> = new Set(['notify'])
 // The task type that marks a stop waiting on a person, taken quoted or bare so `--task-type
 // confirmation` and `--task-type=confirmation` read alike. A `progress` or `pr` notification is not a

package/scripts/rules/pre-gate-cut.ts

@@ -44,8 +44,8 @@ const HOLD_COMMANDS: ReadonlySet<string> = new Set(['run:hold'])
 // predicate exists to keep it out of.
 const HOLD_MODE_FLAG = /(?:^|\s)--release(?:[=\s]|$)/u
 
-// **Alias-expanded rather than matched as text**, so `pnpm josh ga` and `pnpm josh rct` are the same
-// calls as their canonical spellings. Segment-wise for the reason every other row here is: one shell
+// **Alias-expanded rather than matched as text**, so `pnpm josh ga` is the same call as `pnpm josh
+// gate`. Segment-wise for the reason every other row here is: one shell
 // line carries several commands, and a name quoted inside a body is not the command being invoked.
 //
 // **One reading of that question rather than one per name set.** Four predicates here differ only in

package/scripts/run/run-headless.ts

@@ -73,10 +73,27 @@ function is_owned_here(carry: RunCarry, ancestry: () => ReadonlySet<number>): bo
 	return carry.owner_pid !== undefined && ancestry().has(carry.owner_pid)
 }
 
-function is_driven_here(read: CarryRead | undefined, ancestry: () => ReadonlySet<number>): boolean {
-	if (read?.kind !== 'carried' || !is_driving(read)) return false
+function driven_here(
+	read: CarryRead | undefined,
+	ancestry: () => ReadonlySet<number>,
+): RunCarry | undefined {
+	if (read?.kind !== 'carried' || !is_driving(read)) return undefined
 
-	return is_owned_here(read.carry, ancestry)
+	return is_owned_here(read.carry, ancestry) ? read.carry : undefined
+}
+
+/**
+ * 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.
+ */
+async function driving_carry(
+	source: EnvironmentSource = process.env,
+	ancestry: () => ReadonlySet<number> = lane_reap.own_ancestry,
+): Promise<RunCarry | undefined> {
+	if (lane_child_marker.marked_issue(source) !== undefined) return undefined
+
+	return driven_here(await read_carry_here(), ancestry)
 }
 
 /**
@@ -88,14 +105,13 @@ async function is_backlog_parent(
 	source: EnvironmentSource = process.env,
 	ancestry: () => ReadonlySet<number> = lane_reap.own_ancestry,
 ): Promise<boolean> {
-	if (lane_child_marker.marked_issue(source) !== undefined) return false
-
-	return is_driven_here(await read_carry_here(), ancestry)
+	return (await driving_carry(source, ancestry)) !== undefined
 }
 
 const run_headless = {
 	HEADLESS_ENV_KEY,
 	current_carry,
+	driving_carry,
 	environment,
 	is_backlog_parent,
 	is_headless,

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

@@ -0,0 +1,144 @@
+import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
+import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
+import { cost_format } from '#scripts/cost-runtime/cost-format'
+import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
+import { run_carry, type RunCarry } from './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 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.
+//
+// **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
+// short reuse window so a burst of calls is priced once.
+//
+// **It is async and composed after the synchronous guards, like the watcher guard.** Telling the parent
+// apart reads the carry record through `run_headless.driving_carry`, which is asynchronous; reusing it is
+// what keeps a second, synchronous spelling of the parent test from existing.
+
+const SWITCH_ENV_KEY = 'JOSH_PARENT_CUT_GUARD'
+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.
+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
+// a session transcript on disk.
+interface ParentCutState {
+	carry: () => Promise<RunCarry | undefined>
+	verdict: () => CostVerdict
+}
+
+function current_state(): ParentCutState {
+	return {
+		carry: async (): Promise<RunCarry | undefined> => await run_headless.driving_carry(),
+		verdict: (): CostVerdict =>
+			implementation_cut_verdict.reused_verdict(() => cost_cli.session_verdict()),
+	}
+}
+
+const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
+
+const PARENT_CUT_REASON =
+	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` (it owns the live carry record) and ' +
+	`its recent-context cost has crossed the shared ${THRESHOLD_TEXT} threshold between merges, so every ` +
+	'later request re-reads the accumulated context (joshuafolkken/kit#2947). Take the hand-off now rather ' +
+	'than at the next merge: follow `.claude/skills/workflow-commands/backlogrun-progress.md` → "The ' +
+	'hand-off" from its `over` branch — open no new lane and take no new child, read `pnpm josh lane:list`, ' +
+	'make sure every lane in flight records an output path, then run `pnpm josh run:carry --cut --owner ' +
+	'"$PPID"` and, unless it answers `capped`, `pnpm josh run:wake`, post the progress comment and end the ' +
+	'turn. A lane nobody can poll means the cut does not happen; carry on and this asks again later. ' +
+	'Reissue this call when the hand-off is done or cannot be taken — the guard stays quiet for a while ' +
+	'after it refuses, so the hand-off calls themselves are not refused.'
+
+// Neither an uncapped parent's own record nor a measured `over` is optional: a capped record has no cut
+// left to take (`run:carry --cut` answers `capped`), and an unmeasurable session is left alone here —
+// refusing every call of a session that cannot be priced would wedge it, while the merge-seam check
+// still takes `over`'s branch for it.
+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
+
+	return state.verdict() === cost_verdict.OVER_VERDICT
+}
+
+function is_quiet(target: string, now_ms: number): boolean {
+	const last_ms = hook_decision.create_refusal_stamp(STAMP_PREFIX).last_ms(target)
+
+	return last_ms !== hook_decision.NEVER_MS && now_ms - last_ms < QUIET_WINDOW_MS
+}
+
+// The quiet window is read before the carry record and the transcript price, so a refused parent's
+// following calls cost one small file read each.
+async function refusal_for(
+	transcript: string,
+	now_ms: number,
+	state: ParentCutState,
+): Promise<string | undefined> {
+	const stamp = hook_decision.create_refusal_stamp(STAMP_PREFIX)
+	const target = stamp.path(transcript)
+
+	if (is_quiet(target, now_ms) || !(await is_due(state))) return undefined
+
+	return stamp.record(target, now_ms) ? PARENT_CUT_REASON : undefined
+}
+
+// A delegated unit's call names the *parent's* transcript and runs under the parent's process, so the
+// carry record reads as owned here; only `agent_id` tells it apart (`hook-decision.ts`). Refusing it
+// would hand the unit a hand-off it cannot take and spend the parent's quiet window on it.
+function is_unit_call(raw_payload: string): boolean {
+	try {
+		return (hook_decision.parse_hook_payload(raw_payload)?.agent_id ?? '') !== ''
+	} catch {
+		return false
+	}
+}
+
+function is_exempt(raw_payload: string): boolean {
+	return !hook_decision.is_switch_enabled(SWITCH_ENV_KEY) || is_unit_call(raw_payload)
+}
+
+/**
+ * The deny reason for a call a `backlogrun` parent makes past the shared threshold, or `undefined` when
+ * the call proceeds — a lane child, a delegated unit, a person's session, a handed-off or capped
+ * record, an `under` or unmeasurable verdict, or a call inside the quiet window after a refusal.
+ */
+async function parent_cut_reason(
+	raw_payload: string,
+	now_ms: number = Date.now(),
+	state: ParentCutState = current_state(),
+): Promise<string | undefined> {
+	if (is_exempt(raw_payload)) return undefined
+
+	const transcript = run_watcher_hook.transcript_of(raw_payload)
+
+	if (transcript === undefined) return undefined
+
+	return await refusal_for(transcript, now_ms, state)
+}
+
+const run_parent_cut_hook = {
+	PARENT_CUT_REASON,
+	QUIET_WINDOW_MS,
+	STAMP_PREFIX,
+	SWITCH_ENV_KEY,
+	parent_cut_reason,
+}
+
+export type { ParentCutState }
+export { run_parent_cut_hook }

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

@@ -78,7 +78,7 @@ async function to_child(issue: OpenIssueData): Promise<ChildObservation> {
 	const number = String(issue.number)
 	const child = await run_preflight.read_child_state(number)
 
-	return { issue: number, labels: to_labels(issue), pr_state: child.pr_state }
+	return { issue: number, title: issue.title, labels: to_labels(issue), pr_state: child.pr_state }
 }
 
 async function read_children(repo: string): Promise<ReadonlyArray<ChildObservation> | undefined> {
@@ -171,6 +171,7 @@ async function read_observations(request: ObservationRequest): Promise<Observati
 	if (children.length === 0 && !(await has_run_started(lanes))) return IDLE_READ
 
 	const observations: Observations = {
+		repo: request.repo,
 		children,
 		lanes,
 		load_average: loadavg()[FIRST_LOAD_AVERAGE] ?? 0,

package/scripts/run/run-progress.ts

@@ -1,3 +1,5 @@
+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).
 //
@@ -56,6 +58,9 @@ const DEFAULT_INTERVAL_MS = DEFAULT_INTERVAL_MINUTES * MS_PER_MINUTE
 // 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.
+	title: string
 	labels: ReadonlyArray<string>
 	pr_state: string
 }
@@ -66,6 +71,8 @@ interface LaneObservation {
 }
 
 interface Observations {
+	// `owner/repo`, the repository the listing was read from — what every printed issue links into.
+	repo: string
 	children: ReadonlyArray<ChildObservation>
 	lanes: ReadonlyArray<LaneObservation>
 	load_average: number
@@ -195,26 +202,32 @@ function next_state(
 	return { key, unchanged_since_ms: now_ms }
 }
 
-function format_child(child: ChildObservation): string {
+// 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.
+function format_child(child: ChildObservation, cite: IssueCiter): string {
 	const labels = child.labels.length > 0 ? child.labels.join(',') : '(no labels)'
 
-	return `#${child.issue} ${labels} PR:${child.pr_state}`
+	return `${cite(child.issue)} ${labels} PR:${child.pr_state}`
 }
 
 // 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.
-function format_children(children: ReadonlyArray<ChildObservation>): string {
+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])))
 
-	return children.map((child) => format_child(child)).join(' · ')
+	return children.map((child) => format_child(child, cite)).join(' · ')
 }
 
-function format_lanes(lanes: ReadonlyArray<LaneObservation>): string {
+// A lane is linked without its title: a lane in flight is a child the line above already cited in full,
+// so repeating the title here would only lengthen the line.
+function format_lanes(lanes: ReadonlyArray<LaneObservation>, repo: string): string {
 	if (lanes.length === 0) return NO_LANES
+	const cite = issue_cite.citer(repo, new Map())
 
-	return lanes.map((lane) => `${lane.issue}:${lane.state}`).join(' ')
+	return lanes.map((lane) => `${cite(lane.issue)}:${lane.state}`).join(' ')
 }
 
 // Absent is said, never filled in. A run started without a transcript path prints `unread` here, which
@@ -303,8 +316,8 @@ function format_line(observations: Observations, timing: LineTiming): string {
 		observed_at: format_observed_at(timing.now_ms),
 		quiet: format_minutes(timing.now_ms - timing.quiet_since_ms),
 		unchanged: format_minutes(timing.now_ms - timing.unchanged_since_ms),
-		children: format_children(observations.children),
-		lanes: format_lanes(observations.lanes),
+		children: format_children(observations.children, observations.repo),
+		lanes: format_lanes(observations.lanes, observations.repo),
 		load: observations.load_average.toFixed(1),
 		record: format_record(observations.record_age_ms),
 		next: format_next_report(timing.now_ms, timing.interval_ms),

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

@@ -1,7 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
-import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
@@ -9,8 +8,8 @@ import { run_ship, type ShipSection } from './run-ship'
 import { run_ship_detach } from './run-ship-detach'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_return } from './run-ship-return'
-import { run_ship_review_steps } from './run-ship-review-steps'
 import { run_ship_stage, type Phase, type ShipState, type Stage } from './run-ship-stage'
+import { run_ship_steps, type ShipArguments, type Step } from './run-ship-steps'
 
 // `josh ship "<title> #<N>"` — one call for the fixed commit-to-report region a run ships a change on
 // (joshuafolkken/kit#2398). The loop used to spend a round trip each on `gate`, `git -y`, `followup`
@@ -67,7 +66,6 @@ const USAGE =
 const NO_LOG_NOTE = 'no detached ship supervisor log for this issue'
 const LANE_CHILD_DETACH_NOTE =
 	'lane child: shipping through the detached supervisor (--detach implied), so the end of this turn cannot kill it'
-const should_forward_stderr = true
 
 type NotifyValues = Partial<Record<(typeof NOTIFY_OPTIONS)[number], string>>
 
@@ -84,24 +82,8 @@ const OPTIONS = {
 	cite: { type: 'string', multiple: true },
 } as const
 
-interface ShipArguments {
-	title: string
-	number: string
-	notify: ReadonlyArray<string>
-	body: ReadonlyArray<string>
-	cites: ReadonlyArray<string>
-	is_review: boolean
-	is_detach: boolean
-}
-
 type ShipCommand = { kind: 'ship'; args: ShipArguments } | { kind: 'log'; number: string }
 
-interface Step {
-	stage: Stage
-	header: string
-	run: (args: ShipArguments, state: ShipState) => Promise<JoshResult>
-}
-
 // What a resumed ship knows before its first stage: the record's path (absent outside a repository),
 // the stages it says completed, and the repository's actual state (`run-ship-stage.ts` decides from it).
 interface ShipContext {
@@ -124,58 +106,7 @@ function body_arguments(path: string | undefined): ReadonlyArray<string> {
 	return path === undefined ? [] : [`--${BODY_FILE_OPTION}`, path]
 }
 
-const { STAGE, PHASE } = run_ship_stage
-
-// The four steps in the order a change ships: the gate before the commit, the commit/push/PR before
-// the merge, the merge before the report bookkeeping. The commit step carries the `--skip-*` flags a
-// resumed ship needs, so an existing commit or push is never made twice.
-async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
-	return await josh_command.josh_run(argv, should_forward_stderr)
-}
-
-const COMMIT_STEPS: ReadonlyArray<Step> = [
-	{ stage: STAGE.GATE, header: run_ship.GATE_HEADER, run: async () => await josh(['gate']) },
-	{
-		stage: STAGE.COMMIT,
-		header: run_ship.COMMIT_HEADER,
-		run: async (args, state) =>
-			await josh(['git', '-y', ...run_ship_stage.commit_flags(state), ...args.body, args.title]),
-	},
-]
-
-const MERGE_STEPS: ReadonlyArray<Step> = [
-	{
-		stage: STAGE.FOLLOWUP,
-		header: run_ship.FOLLOWUP_HEADER,
-		run: async (args) => await josh(['followup', args.title, ...args.notify]),
-	},
-	{
-		stage: STAGE.REPORT,
-		header: run_ship.REPORT_HEADER,
-		run: async (args) => await josh(['run:tail', args.number, ...args.cites]),
-	},
-]
-
-// `--review` (joshuafolkken/kit#2427) puts the supervised round-1 review in front of the gate: it
-// launches the gate itself, so the gate stage that follows reuses that tree's green record. It also
-// puts the round-2 pass between the commit and the followup (joshuafolkken/kit#2489), so the PR opens
-// between the rounds and round 2 runs beside CI — a no-op when round 1 left no fix delta.
-const REVIEW_STEP: Step = {
-	stage: STAGE.REVIEW,
-	header: run_ship.REVIEW_HEADER,
-	run: async (args) => await run_ship_review_steps.review_stage(args.number),
-}
-const ROUND_TWO_STEP: Step = {
-	stage: STAGE.ROUND_TWO,
-	header: run_ship.ROUND_TWO_HEADER,
-	run: async (args) => await run_ship_review_steps.round_two_stage(args.number),
-}
-
-function steps(args: ShipArguments): ReadonlyArray<Step> {
-	if (!args.is_review) return [...COMMIT_STEPS, ...MERGE_STEPS]
-
-	return [REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
-}
+const { PHASE } = run_ship_stage
 
 function issue_number(title: string): string | undefined {
 	return TRAILING_ISSUE_PATTERN.exec(title)?.[NUMBER_GROUP]
@@ -211,6 +142,7 @@ function ship_args(
 		number,
 		notify: notify_arguments(values),
 		body: body_arguments(values[BODY_FILE_OPTION]),
+		body_path: values[BODY_FILE_OPTION],
 		cites,
 		is_review: values.review === true,
 		is_detach: values.detach === true,
@@ -328,14 +260,14 @@ async function stopped(
 	return sections
 }
 
-// Run the four in order, stopping at the first that failed: a red gate never reaches the commit, so
+// Run the stages in order, stopping at the first that failed: a red gate never reaches the commit, so
 // the returned sections end at the failure the report names. A ship that reached the end clears its
-// record, so the next ship of the same issue starts from the gate.
+// record, so the next ship of the same issue starts from the preflight.
 async function ship(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const context = await open_context(args)
 	const sections: Array<ShipSection> = []
 
-	for (const step of steps(args)) {
+	for (const step of run_ship_steps.steps(args)) {
 		const section = await run_stage(step, args, context)
 
 		sections.push(section)