@joshuafolkken/kit 1.1035.0 → 1.1094.0

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

@@ -1,14 +1,14 @@
 import { agent_argv, type AgentArgv } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
-import { gate_tree } from '#scripts/gate/gate-tree'
-import { scoped_green } from '#scripts/gate/scoped-green'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { openai_review_broker } from '#scripts/lane/openai-review-broker'
+import { review_record } from '#scripts/review/review-record'
 import { detached_launch } from './detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
+import { run_ship_scoped, type Phase } from './run-ship-scoped'
 
 // The side effects of `josh ship --review` (joshuafolkken/kit#2427): the round-1 review the chain used
 // to open, launch, join, attest and record across five agent turns, run by the supervisor beside the
@@ -44,10 +44,15 @@ const ROUND_TWO_DECISION = ['review:round2', '--round-1-closed']
 const ROUND_TWO_BRIEF = ['review:brief', '--round', '2']
 const ROUND_TWO_REQUIRED = 'required'
 const FIXED_JOIN_NOTE =
-	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate stage re-runs it.'
+	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate re-runs once the tree is fixed.'
 const ROUND_TWO_SKIPPED_NOTE = 'round 2 not due — nothing left to verify; shipping on.'
+const ROUND_ONE_RECORDED_NOTE =
+	'round 1 already recorded for this issue — not reviewed again; the gate reads the fixed tree and round 2 decides after the commit.'
+
+// The scoped pair's precondition, met by the supervisor itself rather than stopped on
+// (joshuafolkken/kit#2500), single-sourced with the preflight and gate stages (joshuafolkken/kit#2946).
+const { run_phases, scoped_pair } = run_ship_scoped
 
-type Phase = () => Promise<JoshResult>
 type PromptOf = (brief_path: string, findings_path: string) => string
 
 function failure(out: string): JoshResult {
@@ -123,12 +128,14 @@ function current_verdict(): ReturnType<typeof run_ship_review.read_verdict> {
 
 // A red join blocks unless the reviewer fixed findings in place: the background gate then read the
 // tree before the fixes, so its verdict describes a tree that no longer exists. The join still ran to
-// its end, so the gate stage that follows never races it.
+// its end, so the gate stage that follows never races it. Any fix drains it, not only a round whose
+// every finding was fixed — a partial fix moved the tree just the same, and the round then stops on its
+// unfixed finding at the record rather than on a `Gate RED` the gate never earned (joshuafolkken/kit#2961).
 async function join_gate(): Promise<JoshResult> {
 	const joined = await josh([RUN_REVIEW, '--join'])
 
 	if (joined.code === SUCCESS_EXIT_CODE) return joined
-	if (current_verdict().kind !== run_ship_review.VERDICT.FIXED) return joined
+	if (!run_ship_review.has_fixes(stamp_file.read_stamp_text(paths().findings))) return joined
 
 	note(FIXED_JOIN_NOTE)
 
@@ -153,17 +160,6 @@ async function record_and_route(
 	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out)
 }
 
-async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
-	let last: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
-
-	for (const phase of phases) {
-		last = await phase()
-		if (last.code !== SUCCESS_EXIT_CODE) return last
-	}
-
-	return last
-}
-
 // A brief-minting command, then a reviewer handed what it printed.
 function reviewed(
 	open: ReadonlyArray<string>,
@@ -185,18 +181,6 @@ function reviewed(
 	]
 }
 
-// The scoped pair's precondition, met by the supervisor itself rather than stopped on
-// (joshuafolkken/kit#2500): only the checks with no green record for this tree run — the same
-// question `review:brief` and the local gate refuse on — so a fresh record costs nothing and a stale
-// or absent one costs a scoped run instead of a stop and a relaunched session. A check that genuinely
-// fails still stops the ship, its output forwarded to the ship log.
-async function scoped_pair(): Promise<JoshResult> {
-	const tree = await gate_tree.read_gate_tree()
-	const scripts = scoped_green.missing_scripts(tree.files, tree.base)
-
-	return await run_phases(scripts.map((script) => async () => await josh([script])))
-}
-
 // Fixes made in place are counted only once the scoped pair is green on the fixed tree. The reviewer is
 // asked to leave it green; this is the check that it did, and a fix it could not get green is routed as
 // the finding it still is — recorded, then stopped before the gate and the commit take it in.
@@ -212,7 +196,16 @@ async function round_one_record(issue: string): Promise<JoshResult> {
 
 // The round-1 review, beside the gate: scoped pair → open → review → join → attest → record, stopping
 // at the first that did not pass.
+//
+// **A recorded round 1 is not run again** (joshuafolkken/kit#2964). A ship relaunched with `--review`
+// after a round-1 stop would otherwise review the whole change a second time as round 1 — a new Medium
+// there stops it again, and round 2 after the commit makes a third. The fix delta is round 2's to
+// verify, and `round_two_stage` asks whether it is due after the commit.
 async function review_stage(issue: string): Promise<JoshResult> {
+	const recorded = await review_record.check(Number(issue))
+
+	if (recorded.status === 'ok') return { code: SUCCESS_EXIT_CODE, out: ROUND_ONE_RECORDED_NOTE }
+
 	return await run_phases([
 		scoped_pair,
 		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt, issue, '1'),
@@ -242,6 +235,6 @@ async function round_two_stage(issue: string): Promise<JoshResult> {
 	])
 }
 
-const run_ship_review_steps = { paths, review_stage, round_two_stage }
+const run_ship_review_steps = { review_stage, round_two_stage }
 
 export { run_ship_review_steps }

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

@@ -154,6 +154,24 @@ function round_one_outcome(verdict: ScoredVerdict): RoundOutcome {
 	return { is_passing: true, note: verdict.kind === VERDICT.FIXED ? FIXED_NOTE : CLEAN_NOTE }
 }
 
+// Whether a findings file records a clean round 1 (joshuafolkken/kit#2945). A resumed round 1 narrows to
+// the delta only past a review that found nothing to fix. A blocking one has a finding in a file the
+// delta may not touch. A fixed one approved its own edits, not the briefed tree the delta is measured
+// from, so a file reverted to that tree would drop out of the delta with its finding back in it.
+function is_clean_round_one(text: string | undefined): boolean {
+	return read_verdict(text).kind === VERDICT.CLEAN
+}
+
+// Whether the reviewer edited the tree — any finding marked fixed, whether or not another one still
+// blocks (joshuafolkken/kit#2961). A partial fix moves the tree the background gate read as surely as a
+// full one, so the join reads it red either way; keyed off the verdict kind instead, a round that fixed
+// one Medium and left another stopped at a misleading `Gate RED` before its own blocking note.
+function has_fixes(text: string | undefined): boolean {
+	if (text === undefined) return false
+
+	return spec_findings(text).some((finding) => finding.is_fixed)
+}
+
 // Round 2 is final and reads only, so it passes clean or Low-only alone — a fix it made would itself be
 // unreviewed.
 function round_two_outcome(verdict: ScoredVerdict): RoundOutcome {
@@ -166,6 +184,8 @@ const run_ship_review = {
 	FIXED_PREFIX,
 	UNVERIFIED_OUTCOME,
 	VERDICT,
+	has_fixes,
+	is_clean_round_one,
 	read_verdict,
 	reviewer_prompt,
 	round_one_outcome,

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

@@ -0,0 +1,45 @@
+import { gate_tree } from '#scripts/gate/gate-tree'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+
+// The scoped pair `josh ship` meets itself rather than stops on (joshuafolkken/kit#2500), shared by
+// every stage that needs a green record for this tree (joshuafolkken/kit#2946): the preflight stage at
+// the start, the review rounds, and the gate stage — a reviewer may have edited the tree after round
+// 1's pair ran, and `josh gate` refuses a tree with no green record.
+
+const SUCCESS_EXIT_CODE = 0
+const should_forward_stderr = true
+
+type Phase = () => Promise<JoshResult>
+
+async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
+	let last: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
+
+	for (const phase of phases) {
+		// eslint-disable-next-line no-await-in-loop -- phases run in order and the first failure stops the rest
+		last = await phase()
+		if (last.code !== SUCCESS_EXIT_CODE) return last
+	}
+
+	return last
+}
+
+// Only the checks with no green record for this tree run — the same question `review:brief` and the
+// local gate refuse on — so a fresh record costs nothing and a stale or absent one costs a scoped run
+// instead of a stop and a relaunched session. A check that genuinely fails still stops the ship, its
+// output forwarded to the ship log.
+async function scoped_pair(): Promise<JoshResult> {
+	const tree = await gate_tree.read_gate_tree()
+	const scripts = scoped_green.missing_scripts(tree.files, tree.base)
+
+	return await run_phases(
+		scripts.map(
+			(script) => async () => await josh_command.josh_run([script], should_forward_stderr),
+		),
+	)
+}
+
+const run_ship_scoped = { run_phases, scoped_pair }
+
+export type { Phase }
+export { run_ship_scoped }

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

@@ -17,6 +17,7 @@ import { z } from 'zod'
 // re-run on an unchanged tree a reuse rather than a second execution. No quality gate is folded away.
 
 const STAGE = {
+	PREFLIGHT: 'preflight',
 	REVIEW: 'review',
 	GATE: 'gate',
 	COMMIT: 'commit',
@@ -78,7 +79,7 @@ function mark_done(target: string, stage: Stage): void {
 	stamp_file.replace_stamp(target, { done: [...done] })
 }
 
-// Removed once the report stage completes, so a later ship of the same issue starts from the gate.
+// Removed once the report stage completes, so a later ship of the same issue starts from the preflight.
 function clear(target: string): void {
 	stamp_file.remove_stamp(target)
 }
@@ -90,6 +91,9 @@ function is_shipped(state: ShipState): boolean {
 }
 
 const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => boolean> = {
+	// The preflight (joshuafolkken/kit#2946) asks what the commit stage would refuse on, so a commit is
+	// its output as it is the gate's; a resumed commit stage still asks `git -y`'s own preflight.
+	[STAGE.PREFLIGHT]: (_done, state) => state.is_merged || state.is_committed,
 	// The `--review` round (joshuafolkken/kit#2427) precedes the commit, so a commit is its output as it
 	// is the gate's. A record alone is not honored: before a commit the tree may have been edited since
 	// the recorded round, and only a commit pins the tree that round read.

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

@@ -0,0 +1,105 @@
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { run_ship } from './run-ship'
+import { run_ship_preflight } from './run-ship-preflight'
+import { run_ship_review_steps } from './run-ship-review-steps'
+import { run_ship_scoped } from './run-ship-scoped'
+import { run_ship_stage, type ShipState, type Stage } from './run-ship-stage'
+
+// The stages `josh ship` runs, in the order a change ships (joshuafolkken/kit#2398), kept apart from the
+// chaining CLI so the order is read in one place.
+
+const should_forward_stderr = true
+
+interface ShipArguments {
+	title: string
+	number: string
+	notify: ReadonlyArray<string>
+	body: ReadonlyArray<string>
+	body_path: string | undefined
+	cites: ReadonlyArray<string>
+	is_review: boolean
+	is_detach: boolean
+}
+
+interface Step {
+	stage: Stage
+	header: string
+	run: (args: ShipArguments, state: ShipState) => Promise<JoshResult>
+}
+
+const { STAGE } = run_ship_stage
+
+async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
+	return await josh_command.josh_run(argv, should_forward_stderr)
+}
+
+// joshuafolkken/kit#2946: the pull request's preconditions and the scoped pair are asked first, so a
+// stop they would cause lands before the review and the gate rather than after them.
+const PREFLIGHT_STEP: Step = {
+	stage: STAGE.PREFLIGHT,
+	header: run_ship.PREFLIGHT_HEADER,
+	run: async (args) =>
+		await run_ship_preflight.stage({ title: args.title, body_path: args.body_path }),
+}
+
+// The gate before the commit, the commit/push/PR before the merge. The gate meets the scoped pair
+// first: a round-1 reviewer may have edited the tree since the preflight, and `josh gate` refuses a tree
+// with no green record (joshuafolkken/kit#2946). The commit step carries the `--skip-*` flags a resumed
+// ship needs, so an existing commit or push is never made twice.
+const COMMIT_STEPS: ReadonlyArray<Step> = [
+	{
+		stage: STAGE.GATE,
+		header: run_ship.GATE_HEADER,
+		run: async () =>
+			await run_ship_scoped.run_phases([
+				run_ship_scoped.scoped_pair,
+				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]),
+	},
+]
+
+// The merge before the report bookkeeping.
+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 [PREFLIGHT_STEP, ...COMMIT_STEPS, ...MERGE_STEPS]
+
+	return [PREFLIGHT_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
+}
+
+const run_ship_steps = { PREFLIGHT_STEP, steps }
+
+export type { ShipArguments, Step }
+export { run_ship_steps }

package/scripts/run/run-ship.ts

@@ -9,6 +9,7 @@
 // `run:tail`, ship stops at the first failed step: a red gate must never reach the commit, so the
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
+const PREFLIGHT_HEADER = '=== preflight ==='
 const REVIEW_HEADER = '=== review ==='
 const GATE_HEADER = '=== gate ==='
 const COMMIT_HEADER = '=== commit/push/PR ==='
@@ -63,12 +64,12 @@ const run_ship = {
 	COMMIT_HEADER,
 	FOLLOWUP_HEADER,
 	GATE_HEADER,
+	PREFLIGHT_HEADER,
 	REPORT_HEADER,
 	REVIEW_HEADER,
 	ROUND_TWO_HEADER,
 	SKIPPED_BODY,
 	STOPPED_PREFIX,
-	SUCCESS_EXIT_CODE,
 	exit_code,
 	failed_section,
 	format_report,

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

@@ -0,0 +1,62 @@
+import { has_label_name, PLANNED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { run_halfrun_resume } from './run-halfrun-resume'
+import { run_prrun_resume, type PrrunToken } from './run-prrun-resume'
+import { run_stage, type StageState } from './run-stage'
+
+// The reading half of the stage ladder (joshuafolkken/kit#3042): the facts `run_stage.state_of` folds
+// into one state, each read from where the stage that produced it left it — never from the
+// conversation. A closed issue and the `run:planned` label come from GitHub; a `halfrun` stop and a `prrun`
+// stop come from the stop's own mark on the tree's hold (`run-halfrun-resume.ts`,
+// `run-prrun-resume.ts`).
+
+const CLOSED = 'CLOSED'
+
+interface StageRead {
+	state: StageState
+	// The `prrun` stop's resume token, kept so the entry acts on it without reading the pull request
+	// again; `undefined` when no `prrun` stop is recorded for the issue.
+	prrun_token: PrrunToken | undefined
+}
+
+function is_closed(read: StateRead): boolean {
+	return read.kind === 'state' && read.state.state === CLOSED
+}
+
+function is_planned(read: StateRead): boolean {
+	return read.kind === 'state' && has_label_name(read.state.labels, PLANNED_LABEL)
+}
+
+// The two stops are one hold record, so at most one is present; the `prrun` one is asked only when the
+// `halfrun` one is not, which spares its pull-request read.
+async function read_stop(
+	issue: string,
+): Promise<{ is_halfrun_stopped: boolean; prrun_token: PrrunToken | undefined }> {
+	if (await run_halfrun_resume.is_pending(issue)) {
+		return { is_halfrun_stopped: true, prrun_token: undefined }
+	}
+
+	return { is_halfrun_stopped: false, prrun_token: await run_prrun_resume.resume_token(issue) }
+}
+
+// An unreadable issue reads as neither closed nor planned: the ordinary entry that follows reads it
+// again and answers `unknown` for it, exactly as before the ladder existed.
+async function read_stage(issue: string): Promise<StageRead> {
+	const [issue_read, stop] = await Promise.all([
+		issue_state_cli.read_issue(issue),
+		read_stop(issue),
+	])
+	const state = run_stage.state_of({
+		is_closed: is_closed(issue_read),
+		is_prrun_stopped: stop.prrun_token !== undefined,
+		is_halfrun_stopped: stop.is_halfrun_stopped,
+		is_planned: is_planned(issue_read),
+	})
+
+	return { state, prrun_token: stop.prrun_token }
+}
+
+const run_stage_read = { read_stage }
+
+export type { StageRead }
+export { run_stage_read }

package/scripts/run/run-stage.ts

@@ -0,0 +1,160 @@
+// joshuafolkken/kit#3042: the workflow commands form a ladder — `kickoff` → `halfrun` → `prrun` →
+// `fullrun` — and **the command typed decides only how far a run goes; where it starts is read off the
+// issue**. A run that finds work already done resumes after it rather than redoing it, and a command
+// whose stopping point the issue has already reached reports that and stops.
+//
+// This module is the pure half of that rule: the five states an issue can be found in, the four
+// commands, and the one table that maps a (state, command) pair to a start and an end. `run:entry` reads
+// the state (`run-stage-read.ts`) and branches on the answer; the stage table in
+// `docs/how-to/run-issues.md` and each stop's `Next:` line are pinned to this module by
+// `run-stage-document.test.ts`, so the prose cannot drift from what the entry does.
+
+const KICKOFF = 'kickoff'
+const HALFRUN = 'halfrun'
+const PRRUN = 'prrun'
+const FULLRUN = 'fullrun'
+
+// In ladder order: a command's index plus one is the state rank it brings an issue to.
+const COMMANDS = [KICKOFF, HALFRUN, PRRUN, FULLRUN] as const
+
+type StageCommand = (typeof COMMANDS)[number]
+
+// What `run:entry` serves when no command is named — the one it served alone before the ladder existed.
+const DEFAULT_COMMAND: StageCommand = FULLRUN
+
+const FRESH = 'fresh'
+const PLANNED = 'planned'
+const HALFRUN_STOPPED = 'halfrun-stopped'
+const PRRUN_STOPPED = 'prrun-stopped'
+const MERGED = 'merged'
+
+// In ladder order: a state's index is how many rungs the issue has already climbed.
+const STATES = [FRESH, PLANNED, HALFRUN_STOPPED, PRRUN_STOPPED, MERGED] as const
+
+type StageState = (typeof STATES)[number]
+
+const REACHED = 'reached'
+
+// Where a run picks the issue up from each state — the first piece of work not yet done. A merged issue
+// has none: every command has reached it.
+const STARTS: Readonly<Record<StageState, string>> = {
+	[FRESH]: 'plan',
+	[PLANNED]: 'implement',
+	[HALFRUN_STOPPED]: 'gate',
+	[PRRUN_STOPPED]: 'followup',
+	[MERGED]: REACHED,
+}
+
+// Every start a decision can print, in ladder order — the `run:entry` oracle's vocabulary.
+const START_TOKENS: ReadonlyArray<string> = [...new Set(Object.values(STARTS))]
+
+// Where each command stops.
+const ENDS: Readonly<Record<StageCommand, string>> = {
+	[KICKOFF]: 'plan posted',
+	[HALFRUN]: 'gated, before the commit',
+	[PRRUN]: 'green, mergeable PR',
+	[FULLRUN]: 'merged',
+}
+
+const NEXT_PREFIX = 'Next: '
+const NEXT_SEPARATOR = ' | '
+const STATE_HEADER = 'Issue state'
+const CELL_ARROW = ' → '
+const REACHED_CELL = 'reached — report and stop'
+
+interface StageFacts {
+	is_closed: boolean
+	is_prrun_stopped: boolean
+	is_halfrun_stopped: boolean
+	is_planned: boolean
+}
+
+interface StageDecision {
+	state: StageState
+	command: StageCommand
+	// The first piece of work the run does, or `reached` when there is none left for this command.
+	start: string
+	end: string
+	is_reached: boolean
+}
+
+function to_command(value: string | undefined): StageCommand | undefined {
+	return COMMANDS.find((command) => command === value)
+}
+
+// The furthest rung the facts show, so a closed issue is merged whatever its hold still says.
+function state_of(facts: StageFacts): StageState {
+	if (facts.is_closed) return MERGED
+	if (facts.is_prrun_stopped) return PRRUN_STOPPED
+	if (facts.is_halfrun_stopped) return HALFRUN_STOPPED
+
+	return facts.is_planned ? PLANNED : FRESH
+}
+
+function decide(state: StageState, command: StageCommand): StageDecision {
+	const is_reached = STATES.indexOf(state) > COMMANDS.indexOf(command)
+	const start = is_reached ? REACHED : STARTS[state]
+
+	return { state, command, start, end: ENDS[command], is_reached }
+}
+
+// The commands that go further than `command`, nearest first — what a stop offers next.
+function next_commands(command: StageCommand): ReadonlyArray<StageCommand> {
+	return COMMANDS.slice(COMMANDS.indexOf(command) + 1)
+}
+
+// The `Next:` line a stop's Telegram and report carry, e.g. `Next: prrun #<N> | fullrun #<N>`.
+function next_line(command: StageCommand, issue: string): string {
+	const commands = next_commands(command).map((next) => `${next} #${issue}`)
+
+	return `${NEXT_PREFIX}${commands.join(NEXT_SEPARATOR)}`
+}
+
+function format_decision(issue: string, decision: StageDecision): string {
+	const fields = [`at: ${decision.state}`, `to: ${decision.command}`, `start: ${decision.start}`]
+
+	return `stage #${issue} — ${fields.join(' · ')}`
+}
+
+function cell(state: StageState, command: StageCommand): string {
+	const decision = decide(state, command)
+
+	return decision.is_reached ? REACHED_CELL : `${decision.start}${CELL_ARROW}${decision.end}`
+}
+
+// The stage table as rows of cells, header first — the shape both documents carry.
+function table_rows(): ReadonlyArray<ReadonlyArray<string>> {
+	const header = [STATE_HEADER, ...COMMANDS.map((command) => `\`${command}\``)]
+	const rows = STATES.map((state) => [
+		`\`${state}\``,
+		...COMMANDS.map((command) => cell(state, command)),
+	])
+
+	return [header, ...rows]
+}
+
+const run_stage = {
+	COMMANDS,
+	DEFAULT_COMMAND,
+	FRESH,
+	HALFRUN,
+	HALFRUN_STOPPED,
+	KICKOFF,
+	MERGED,
+	PLANNED,
+	PRRUN,
+	PRRUN_STOPPED,
+	REACHED,
+	START_TOKENS,
+	STATES,
+	decide,
+	format_decision,
+	next_commands,
+	next_line,
+	state_of,
+	table_rows,
+	to_command,
+} as const
+
+export type { StageCommand, StageDecision, StageFacts, StageState }
+export { run_stage }

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

@@ -168,7 +168,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_status_cli = { USAGE, parse, run }
+const run_status_cli = { parse, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

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

@@ -44,18 +44,22 @@ function is_handed_off_here(carry: CarryRead): boolean {
 	return run_headless.is_owned_here(carry.carry, lane_reap.own_ancestry)
 }
 
+const UNREADABLE_RUN: RunReads = {
+	carry_kind: 'unreadable',
+	is_retrospective_done: false,
+	is_at_cut_cap: false,
+	is_handed_off: false,
+	last_event: undefined,
+}
+
 // The run-level reads, keyed on the common git directory both the carry and the event stream share. A
 // directory that cannot be read leaves the position unknowable, which `next_action` answers `unknown`.
-function read_run(directory: string | undefined, issue_number: string): RunReads {
-	if (directory === undefined) {
-		return {
-			carry_kind: 'unreadable',
-			is_retrospective_done: false,
-			is_at_cut_cap: false,
-			is_handed_off: false,
-			last_event: undefined,
-		}
-	}
+function read_run(
+	directory: string | undefined,
+	issue_number: string,
+	is_lane_child: boolean,
+): RunReads {
+	if (directory === undefined) return UNREADABLE_RUN
 
 	const carry = run_carry.read_carry(run_carry.carry_path(directory))
 	const events = run_event_stream.read_events(run_event_stream.target_of(directory))
@@ -63,11 +67,13 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 	// invocation left on the stream must not be read as this run's position (joshuafolkken/kit#2395). The
 	// observed defect was a `run:step` that printed `wait` on a fresh run because an old `child-launch` was
 	// still the stream's tail. Another issue's detached ship supervisor is left out the same way
-	// (joshuafolkken/kit#2428).
+	// (joshuafolkken/kit#2428), and so — for a lane child — is every event that does not name its own issue
+	// (joshuafolkken/kit#3039).
 	const last = run_event_scope.last_issue_event(
 		events,
 		run_event_scope.scope_of(carry),
 		issue_number,
+		is_lane_child,
 	)
 
 	return {
@@ -82,7 +88,8 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 async function gather(issue_number: string): Promise<StepInput> {
 	const reads = await run_prep_cli.gather(issue_number)
 	const parts = run_prep_cli.to_parts(issue_number, reads)
-	const run_reads = read_run(await run_carry.repository_directory(), issue_number)
+	const is_lane_child = lane_child_marker.is_child_of(process.cwd())
+	const run_reads = read_run(await run_carry.repository_directory(), issue_number, is_lane_child)
 
 	return {
 		issue_number,
@@ -94,7 +101,7 @@ async function gather(issue_number: string): Promise<StepInput> {
 		is_retrospective_done: run_reads.is_retrospective_done,
 		is_at_cut_cap: run_reads.is_at_cut_cap,
 		is_handed_off: run_reads.is_handed_off,
-		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		is_lane_child,
 		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
 		// Read here rather than in `run-step.ts` so the position logic stays a pure function of its input.
 		is_retrospective_enabled: run_retrospective.is_enabled(),
@@ -128,7 +135,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_step_cli = { USAGE, gather, main, run }
+const run_step_cli = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/run/run-step.ts

@@ -1,4 +1,4 @@
-import { git_stash } from '#scripts/git/git-stash'
+import { git_stash } from '#scripts/git/stash/git-stash'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import type { CarryRead } from './run-carry'
 import { run_event_stream } from './run-event-stream'

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

@@ -1,4 +1,4 @@
-import { telegram_notify } from '#scripts/git/telegram-notify'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import type { CarryRead } from './run-carry'
 
 // **A `backlogrun` that halts because a person is needed used to reach nobody once the session was
@@ -43,8 +43,6 @@ async function announce(notice: StopNotice): Promise<boolean> {
 }
 
 const run_stop_notify = {
-	STOP_RECOVERY,
-	STOP_TITLE,
 	announce,
 	plan,
 }