@joshuafolkken/kit 1.1050.0 → 1.1128.0

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

@@ -0,0 +1,106 @@
+import { run_ship_stage, type Stage } from './run-ship-stage'
+import type { ShipArguments } from './run-ship-steps'
+
+// The command a relaunched lane child runs once it has fixed what stopped its detached ship
+// (joshuafolkken/kit#2964). The ship-stop prompt used to say only "hand the region back per
+// chain-rule.md", so every relaunched session searched that document and re-derived the next command
+// — 179 reads of it in one run. The stopped stage decides the command mechanically, so it is decided
+// here, once, and the prompt carries it. `chain-rule.md` step 0 stays the single source of the
+// procedure; `ship-stop-prompt-document-rule.test.ts` holds every command below to it.
+//
+// The fix is left uncommitted on purpose: a dirty tree reads as not committed
+// (`run-ship-probe.ts`), so a re-detached ship runs the gate and the commit again on the fixed tree
+// instead of passing over them.
+//
+// **Every route is a re-detach.** The prompt only ever reaches a lane child, and a lane child's commit
+// and push belong to the detached ship (`scripts/rules/lane-background.ts`), so a `josh git -y` here could never
+// run. The rounds are the supervisor's too: under `--review` it skips a round 1 already recorded for the
+// issue and asks `review:round2` itself after the commit (`run-ship-review-steps.ts`), so the fix delta
+// is verified as round 2 rather than reviewed again as round 1.
+//
+// **The re-run carries the stopped ship's own options.** A preflight that stopped on missing live
+// evidence asks for `--body-file`, and `followup` delivers the body from it; a command naming only
+// the title would stop on the same evidence again, and drop the `--cite` follow-ups `run:tail` reads.
+
+const { STAGE } = run_ship_stage
+
+const COMMAND = {
+	LOG: 'pnpm josh ship --log',
+	DETACH: 'pnpm josh ship --detach',
+	DETACH_REVIEW: 'pnpm josh ship --detach --review',
+} as const
+
+// A single quote cannot appear inside single quotes, so it closes the quote, escapes one, and reopens.
+const ESCAPED_QUOTE = String.raw`'\''`
+
+// A token of only these characters means the same to the shell quoted or not, so it is left bare.
+const BARE_WORD = /^[\w%+,./:=@-]+$/u
+
+// What a stopped ship is re-run with: its title, every option it was started with, and whether it
+// carried `--review` — the one option a route decides rather than repeats.
+interface ShipResume {
+	title: string
+	flags: ReadonlyArray<string>
+	is_review: boolean
+}
+
+// Single quotes, so a `$` or a backtick in a title is never expanded by the shell that runs it.
+function quoted(title: string): string {
+	return `'${title.split("'").join(ESCAPED_QUOTE)}'`
+}
+
+function shell_word(token: string): string {
+	return BARE_WORD.test(token) ? token : quoted(token)
+}
+
+// A supervised ship's notify tail is already file-form (`run-ship-detach.ts`), so every flag is a path
+// or an issue number and fits the prompt.
+function resume_of(args: ShipArguments): ShipResume {
+	const cites = args.cites.flatMap((cite) => ['--cite', cite])
+
+	return {
+		title: args.title,
+		flags: [...args.notify, ...args.body, ...cites],
+		is_review: args.is_review,
+	}
+}
+
+// The command prefix stays as written; only the stopped ship's own tokens are quoted where needed.
+function ship_command(command: string, resume: ShipResume): string {
+	const words = [...resume.flags, resume.title].map((token) => shell_word(token))
+
+	return [command, ...words].join(' ')
+}
+
+// After the merge-side stages, or after round 2 — which is final — the re-detach reviews nothing.
+function detach_again(resume: ShipResume): string {
+	return `leave the fix uncommitted and run \`${ship_command(COMMAND.DETACH, resume)}\`.`
+}
+
+// Before round 2 the re-run takes the stopped ship's own shape: `--review` only when it carried it. A
+// reviewing ship skips its recorded round 1 and decides round 2 after the commit; a ship started
+// without `--review` was re-detached after round 2, which is final, so it reviews nothing.
+function detach_as_started(resume: ShipResume): string {
+	const command = resume.is_review ? COMMAND.DETACH_REVIEW : COMMAND.DETACH
+
+	return `leave the fix uncommitted and run \`${ship_command(command, resume)}\`.`
+}
+
+const AFTER_FIX: Record<Stage, (resume: ShipResume) => string> = {
+	[STAGE.PREFLIGHT]: detach_as_started,
+	[STAGE.REVIEW]: detach_as_started,
+	[STAGE.GATE]: detach_as_started,
+	[STAGE.COMMIT]: detach_as_started,
+	[STAGE.ROUND_TWO]: detach_again,
+	[STAGE.FOLLOWUP]: detach_again,
+	[STAGE.REPORT]: detach_again,
+}
+
+// Two lines' worth: read the stopped report, then the one command that resumes after the fix.
+function next_step(issue: string, stage: Stage, resume: ShipResume): string {
+	return `Read the stopped report with \`${COMMAND.LOG} ${issue}\`, fix the ${stage} failure, then ${AFTER_FIX[stage](resume)}`
+}
+
+const run_ship_next = { COMMAND, next_step, quoted, resume_of }
+
+export { run_ship_next, type ShipResume }

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

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { git_branch } from '#scripts/git/git-branch'
-import { git_gh_command } from '#scripts/git/git-gh-command'
 import { git_preflight } from '#scripts/git/git-preflight'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'

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

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { error_text } from '#scripts/lib/error-message'
 import { run_hold } from './run-hold'
 import { run_preflight } from './run-preflight'
 import { run_ship_stage, type ShipState } from './run-ship-stage'
@@ -20,7 +21,9 @@ const HEAD_REFERENCE = 'HEAD'
 async function or_false(is_true: () => Promise<boolean>): Promise<boolean> {
 	try {
 		return await is_true()
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_ship_probe.or_false', error)
+
 		return false
 	}
 }

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

@@ -5,6 +5,7 @@ import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
+import type { ShipResume } from './run-ship-next'
 import type { Stage } from './run-ship-stage'
 
 // How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
@@ -47,14 +48,18 @@ function note(text: string): void {
 	process.stderr.write(`${text}\n`)
 }
 
-async function return_control(issue: string, stage: Stage): Promise<ReturnOutcome> {
+async function return_control(
+	issue: string,
+	stage: Stage,
+	resume: ShipResume,
+): Promise<ReturnOutcome> {
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STOP, stop_text(issue, stage))
 
 	const lane = await lane_to_relaunch(issue)
 
 	if (lane === undefined) return 'recorded'
 
-	const invocation = lane_child_invocation.ship_stop_invocation(issue)
+	const invocation = lane_child_invocation.ship_stop_invocation(issue, { stage, ...resume })
 	const result = lane_relaunch.relaunch(
 		lane,
 		invocation,
@@ -69,7 +74,7 @@ async function return_control(issue: string, stage: Stage): Promise<ReturnOutcom
 	return 'recorded'
 }
 
-const run_ship_return = { return_control, stop_text }
+const run_ship_return = { return_control }
 
 export type { ReturnOutcome }
 export { run_ship_return }

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

@@ -5,6 +5,7 @@ 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'
@@ -43,8 +44,10 @@ 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).
@@ -125,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)
 
@@ -191,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'),
@@ -221,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

@@ -162,6 +162,16 @@ 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 {
@@ -174,6 +184,7 @@ const run_ship_review = {
 	FIXED_PREFIX,
 	UNVERIFIED_OUTCOME,
 	VERDICT,
+	has_fixes,
 	is_clean_round_one,
 	read_verdict,
 	reviewer_prompt,

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

@@ -16,6 +16,7 @@ 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
 	}

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

@@ -99,7 +99,7 @@ function steps(args: ShipArguments): ReadonlyArray<Step> {
 	return [PREFLIGHT_STEP, REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
 }
 
-const run_ship_steps = { steps }
+const run_ship_steps = { PREFLIGHT_STEP, steps }
 
 export type { ShipArguments, Step }
 export { run_ship_steps }

package/scripts/run/run-ship.ts

@@ -70,7 +70,6 @@ const run_ship = {
 	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

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryRead } from './run-carry'
 import { run_status, type StatusParts } from './run-status'
 
@@ -41,19 +41,6 @@ interface StatusReads {
 	cost: CostVerdict
 }
 
-interface ParsedArguments {
-	positionals: ReadonlyArray<string>
-	values: { repo?: string }
-}
-
-function read_args(argv: ReadonlyArray<string>): ParsedArguments | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true })
-	} catch {
-		return undefined
-	}
-}
-
 // Exactly one issue number, or the call is refused: `run:status` reports one run, and a second number
 // would print a second issue's state a caller reads as this run's own.
 function valid_issue(positionals: ReadonlyArray<string>): string | undefined {
@@ -65,7 +52,7 @@ function valid_issue(positionals: ReadonlyArray<string>): string | undefined {
 }
 
 function parse(argv: ReadonlyArray<string>): StatusRequest | undefined {
-	const parsed = read_args(argv)
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 
 	if (parsed === undefined) return undefined
 
@@ -168,7 +155,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,
 }

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

@@ -24,8 +24,4 @@ async function main(): Promise<void> {
 	process.exitCode = SUCCESS_EXIT_CODE
 }
 
-const run_stranded_cli = { main }
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
-export { run_stranded_cli }