@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -1,8 +1,10 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_stash } from '#scripts/git/stash/git-stash'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_read_cli, type BlockRead } from '#scripts/issue/issue-read-cli'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { session_cite } from '#scripts/issue/session-cite'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { error_text } from '#scripts/lib/error-message'
 import { run_ship_preflight } from '#scripts/run/ship/run-ship-preflight'
@@ -10,8 +12,8 @@ import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_locate } from './run-prep-locate'
 
-// `josh run:prep <N>` — one call for the reads a `fullrun` makes before its first edit
-// (joshuafolkken/kit#1978): the issue body and comments (`issue:read`), the state, labels and
+// `josh run:prep <N>` — one call for the reads a `fullrun` makes before its first edit:
+// the issue body and comments (`issue:read`), the state, labels and
 // `human_review` line (`issue:state`), the dependency-update scope (`latest:scope`), and where the
 // paths and identifiers the body names occur in code (`run-prep-locate.ts`). Each is
 // reused rather than reproduced, and the two body reads run concurrently, so three round trips become
@@ -25,7 +27,6 @@ import { run_prep_locate } from './run-prep-locate'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh run:prep <issue-number>'
 const LANE_SKIP_SCOPE = 'not asked'
 const LANE_SKIP_REASON =
@@ -50,7 +51,11 @@ interface PrepReads {
 function parse_number(argv: ReadonlyArray<string>): string | undefined {
 	const [first] = argv
 
-	if (first === undefined || argv.length !== 1 || !ISSUE_NUMBER_PATTERN.test(first)) {
+	if (
+		first === undefined ||
+		argv.length !== 1 ||
+		!issue_number_shape.ISSUE_NUMBER_PATTERN.test(first)
+	) {
 		return undefined
 	}
 
@@ -60,7 +65,7 @@ function parse_number(argv: ReadonlyArray<string>): string | undefined {
 // One note for a read that produced nothing, naming which of the two it was — the same distinction
 // `issue:read` and `issue:state` keep, so a bundled failure still tells a retry from an answer.
 function failure_note(issue_number: string, kind: string): string {
-	return `(issue #${issue_number} not bundled: ${kind})`
+	return `(issue ${session_cite.issue(issue_number)} not bundled: ${kind})`
 }
 
 // A dispatched lane child never runs `josh latest` — the parent does it once per session
@@ -75,11 +80,10 @@ function latest_decision(): LatestDecision {
 	return latest_scope_cli.decide()
 }
 
-// Whether a dispatched lane child's tree holds uncommitted work (joshuafolkken/kit#2476). A lane child
-// that popped its parked work back and then found its issue closed is the one position that work is
-// lost from — the lane is removed by force — so only a lane is asked; a person's own checkout keeps its
-// unrelated edits out of the verdict. A status that cannot be read reports none, leaving the verdict
-// printed before this read existed.
+// Whether a dispatched lane child's tree holds uncommitted work. A lane child that popped
+// its parked work back and then found its issue closed is the one position that work is lost from —
+// the lane is removed by force — so only a lane is asked; a person's own checkout keeps its unrelated
+// edits out of the verdict. A status that cannot be read reports none, leaving the verdict unchanged.
 async function lane_has_changes(): Promise<boolean> {
 	if (!lane_child_marker.is_child_of(process.cwd())) return false
 
@@ -144,8 +148,9 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 
 	const reads = await gather(issue_number)
+	const report = run_prep.format_report(to_parts(issue_number, reads))
 
-	console.info(run_prep.format_report(to_parts(issue_number, reads)))
+	console.info(session_cite.text(report))
 
 	return exit_code(reads)
 }
@@ -155,8 +160,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 // `gather` and `to_parts` are exported so `run:next` reads the same state from the same three reads
-// rather than growing a second copy of the gather (joshuafolkken/kit#2188) — `run:next` is the
-// consumer of `run:prep` the epic #2166 wanted.
+// rather than growing a second copy of the gather.
 const run_prep_cli = { gather, parse_number, run, to_parts }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/run/run-prep-locate.ts

@@ -1,11 +1,10 @@
 import { get_exit_code } from '#scripts/git/git-execa-error'
 import { git_spawn } from '#scripts/git/git-spawn'
 
-// The code locations an issue names, bundled into `run:prep` (joshuafolkken/kit#2761). Across the 90
-// runs `.time-history.jsonl` split by contributor, 53% of round trips were investigation, and most of
-// it opened the files an issue names one read at a time. This finds each path, identifier and command
-// the body puts in backticks and hands back where it occurs in code — `file:line` and a short excerpt,
-// never a whole file — so the first read lands on the right place.
+// The code locations an issue names, bundled into `run:prep`. Investigation is most of a run's
+// round trips, and most of it opens the files an issue names one read at a time. This finds each
+// path, identifier and command the body puts in backticks and hands back where it occurs in code —
+// `file:line` and a short excerpt, never a whole file — so the first read lands on the right place.
 //
 // **Only a backticked span is a target.** A prose word is not a name, and a span holding a space is a
 // command line or a sentence rather than one thing to look up; the one exception is a `josh` command,

package/scripts/run/run-prep.ts

@@ -1,11 +1,9 @@
 import { issue_state, type IssueState } from '#scripts/issue/issue-state'
 
-// `josh run:prep <N>` — the reads a `fullrun` makes before its first edit, assembled into one report
-// (joshuafolkken/kit#1978). Two earlier passes at the setup phase were a documentation rule
-// (joshuafolkken/kit#1847) and a measurement (joshuafolkken/kit#1868); neither was an execution-side
-// change, and the `setup` median did not move. This joins the issue body and comments, the state and
-// `human_review` line, and the dependency-update scope that `issue:read`, `issue:state` and
-// `latest:scope` answered in three separate calls — reusing each rather than reproducing it.
+// `josh run:prep <N>` — the reads a `fullrun` makes before its first edit, assembled into one report.
+// This joins the issue body and comments, the state and `human_review` line, and the dependency-update
+// scope that `issue:read`, `issue:state` and `latest:scope` answer in three separate calls — reusing
+// each rather than reproducing it.
 //
 // The leading summary line carries the three facts a run branches on — the state, whether the issue
 // stops before its commit, and whether a dependency update is owed — so the decision is read off the
@@ -40,13 +38,12 @@ interface PrepParts {
 	state_failure: string
 	latest_scope: string
 	latest_reason: string
-	// Where the paths and identifiers the issue names occur in code (joshuafolkken/kit#2761).
+	// Where the paths and identifiers the issue names occur in code.
 	locations: string
 	// Whether a lane child's tree holds uncommitted work — read for the verdict, not printed in the
-	// report (joshuafolkken/kit#2476).
+	// report.
 	has_changes: boolean
-	// What `josh ship` would refuse on as the tree stands — `run_ship_preflight.ahead`
-	// (joshuafolkken/kit#3154).
+	// What `josh ship` would refuse on as the tree stands — `run_ship_preflight.ahead`.
 	ship_problems: ReadonlyArray<string>
 }
 

package/scripts/run/run-prrun-resume.ts

@@ -5,7 +5,7 @@ import { git_command } from '#scripts/git/git-command'
 import { run_hold, type HoldRead } from '#scripts/run/hold/run-hold'
 import { run_halfrun_resume, type StopMark } from './run-halfrun-resume'
 
-// joshuafolkken/kit#3023: a `prrun` stops at a green, mergeable pull request and **keeps** its hold, so
+// A `prrun` stops at a green, mergeable pull request and **keeps** its hold, so
 // a person can look before anything merges. What comes next is one of three, and `run:entry` answers
 // which as the resume token `fullrun #N` acts on — read, never inferred:
 //
@@ -74,7 +74,7 @@ async function read_facts(stop_head: string): Promise<ResumeFacts> {
 }
 
 // Read-only, so `run:entry` can ask the session budget before it takes anything over. `undefined` is
-// "no `prrun` stop for this issue here", and the ordinary claim decides the tree as before.
+// "no `prrun` stop for this issue here", and the ordinary claim decides the tree.
 async function resume_token(issue: string): Promise<PrrunToken | undefined> {
 	const target = await run_halfrun_resume.hold_target()
 

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

@@ -9,7 +9,7 @@ import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_report } from './run-report'
 
 // `josh run:report` — the session-facing report, generated from the run's event stream rather than
-// composed by hand (joshuafolkken/kit#2249). It reads the events the run appended, asks `release:scope`
+// composed by hand. It reads the events the run appended, asks `release:scope`
 // the same question `josh followup` already asks, and prints `run_report.build_report` of the two. The AI
 // writes only Step 0's three lines (Now / Change / Check), which `report-format.md` names as the half a
 // machine cannot answer; this owns the mechanical half — what merged, what parked and why, what was cut,
@@ -31,9 +31,9 @@ async function read_stream(): Promise<ReadonlyArray<RunEvent>> {
 	return run_event_stream.read_events(target)
 }
 
-// The invocation this report covers, taken from the run record that already holds the start time
-// (joshuafolkken/kit#2393). A checkout whose git directory cannot be resolved has no record to read, which is
-// the same undetermined answer an absent record gives — and neither one falls back to the whole stream.
+// The invocation this report covers, taken from the run record that already holds the start time.
+// A checkout whose git directory cannot be resolved has no record to read, which is the same
+// undetermined answer an absent record gives — and neither one falls back to the whole stream.
 async function read_scope(): Promise<EventScope> {
 	const directory = await run_carry.repository_directory()
 

package/scripts/run/run-report.ts

@@ -3,13 +3,10 @@ import { run_event_scope, type EventScope } from '#scripts/run/event/run-event-s
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 // The session-facing report generated *from* the run's event stream, rather than composed by hand each
-// time (joshuafolkken/kit#2249). #2205 gave the run a typed, ordered stream of what happened — a plan, a
-// launch, a merge, a park, a cut — and `format_event` already single-sources what one of those reads as.
-// What was never single-sourced is the report a person receives: `backlogrun-progress.md` defined the
-// epic completion summary in prose ("naming what was merged, what was parked and why, and what was
-// filed"), so the AI reassembled the wording every run and two runs' summaries never lined up.
+// time, so two runs' summaries line up. The run has a typed, ordered stream of what happened — a plan,
+// a launch, a merge, a park, a cut — and `format_event` single-sources what one of those reads as.
 //
-// **This is that generator, and it owns nothing `format_event` owns.** Each event line is `format_event`'s
+// **This generator owns nothing `format_event` owns.** Each event line is `format_event`'s
 // verbatim — the merges, the parks with their reason in the text, the cuts — so the enumeration is the
 // stream rendered, not a second rendering of it. The only thing this adds is the release tail, which is
 // not on the stream: whether a release is owed is `release:scope`'s answer, appended once at the end.
@@ -18,15 +15,13 @@ import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-st
 // exactly what was printed, so the body a person reads off-screen and the summary a session shows are one
 // text with one generator — the "no second format" the acceptance criteria pin.
 //
-// **And it covers one invocation, not the whole stream** (joshuafolkken/kit#2393, reported a second time
-// after #2308 was closed with no fix behind it). The stream outlives an invocation by design — it is the
-// repository's event log, not this run's — so a generator handed every event renders every run that ever
-// appended one. Two days of merges arrived in one completion summary, and the Telegram body built from that
-// output was rejected for length, which is the failure the generated report exists to prevent. The scope is
+// **And it covers one invocation, not the whole stream.** The stream outlives an invocation by design —
+// it is the repository's event log, not this run's — so a generator handed every event renders every
+// run that ever appended one, and a Telegram body built from that is rejected for length. The scope is
 // therefore an **input**: the caller answers which invocation this is, from the run record that already
 // holds the start time, and a scope nobody could determine prints a notice rather than everything. **The
-// scoping itself is `run-event-scope.ts`'s** (joshuafolkken/kit#2395), shared with every other stream
-// consumer rather than kept private here.
+// scoping itself is `run-event-scope.ts`'s**, shared with every other stream consumer rather than kept
+// private here.
 
 const LINE_SEPARATOR = '\n'
 
@@ -56,7 +51,7 @@ function release_tail(release: Decision): string | undefined {
 // The report: this invocation's events as `format_event`'s lines, then the release tail when there is one.
 // Handed the same events, scope and verdict it returns the same string, which is what the determinism test
 // pins — nothing here reads a clock or the environment. The scoping is `run-event-scope.ts`'s, shared with
-// every other stream consumer (joshuafolkken/kit#2395).
+// every other stream consumer.
 function build_report(input: ReportInput): string {
 	const scoped = run_event_scope.scoped_events(input.events, input.scope)
 	const lines =

package/scripts/run/run-retrospective.ts

@@ -1,10 +1,10 @@
 import { hook_decision } from '#scripts/josh/hook-decision'
 
 // Whether a run owes its end-of-run retrospective, single-sourced so `run:step` and `backlog:drive`
-// never disagree on it (joshuafolkken/kit#2750): a drive that read "owed" where `run:step` read "not
-// owed" handed back at every drain to a session that had nothing to run.
+// never disagree on it: a drive that read "owed" where `run:step` read "not owed" would hand back at
+// every drain to a session that had nothing to run.
 
-// The opt-in switch that gates the retrospective (joshuafolkken/kit#2370). It defaults off, so an unset
+// The opt-in switch that gates the retrospective. It defaults off, so an unset
 // variable owes no retrospective.
 const RETROSPECTIVE_ENV_KEY = 'JOSH_RETROSPECTIVE'
 

package/scripts/run/run-section.ts

@@ -0,0 +1,42 @@
+// The section report the composite commands share — `run:tail` and `ship` each run a fixed chain of
+// steps and print every step's output under its own header. The section shape, the join and the
+// clean/red verdict read off the collected codes are the same in both, so they live here once; what a
+// composite adds on top (ship's `stopped at:` line, tail's stderr fold) stays in its own module.
+
+const SECTION_SEPARATOR = '\n\n'
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface Section {
+	header: string
+	body: string
+	code: number
+}
+
+function section_report(section: Section): string {
+	return `${section.header}\n${section.body}`
+}
+
+function format_sections(sections: ReadonlyArray<Section>): string {
+	return sections.map((section) => section_report(section)).join(SECTION_SEPARATOR)
+}
+
+// Non-zero when any step failed, exactly as each step exits on its own — a bundle where one step
+// failed is never read as clean because the steps around it succeeded.
+function exit_code_of(sections: ReadonlyArray<Section>): number {
+	const is_clean = sections.every((section) => section.code === SUCCESS_EXIT_CODE)
+
+	return is_clean ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+const run_section = {
+	FAILURE_EXIT_CODE,
+	SECTION_SEPARATOR,
+	SUCCESS_EXIT_CODE,
+	exit_code_of,
+	format_sections,
+}
+
+export type { Section }
+export { run_section }

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

@@ -4,7 +4,7 @@ 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
+// The reading half of the stage ladder: 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`,
@@ -40,7 +40,7 @@ async function read_stop(
 }
 
 // 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.
+// again and answers `unknown` for it.
 async function read_stage(issue: string): Promise<StageRead> {
 	const [issue_read, stop] = await Promise.all([
 		issue_state_cli.read_issue(issue),

package/scripts/run/run-stage.ts

@@ -1,4 +1,6 @@
-// joshuafolkken/kit#3042: the workflow commands form a ladder — `kickoff` → `halfrun` → `prrun` →
+import { issue_cite } from '#scripts/issue/issue-cite'
+
+// 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.
@@ -19,7 +21,7 @@ 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.
+// What `run:entry` serves when no command is named.
 const DEFAULT_COMMAND: StageCommand = FULLRUN
 
 const FRESH = 'fresh'
@@ -105,7 +107,7 @@ function next_commands(command: StageCommand): ReadonlyArray<StageCommand> {
 
 // 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}`)
+	const commands = next_commands(command).map((next) => `${next} ${issue_cite.plain(issue)}`)
 
 	return `${NEXT_PREFIX}${commands.join(NEXT_SEPARATOR)}`
 }
@@ -113,7 +115,7 @@ function next_line(command: StageCommand, issue: string): string {
 function format_decision(issue: string, decision: StageDecision): string {
 	const fields = [`at: ${decision.state}`, `to: ${decision.command}`, `start: ${decision.start}`]
 
-	return `stage #${issue} — ${fields.join(' · ')}`
+	return `stage ${issue_cite.plain(issue)} — ${fields.join(' · ')}`
 }
 
 function cell(state: StageState, command: StageCommand): string {

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

@@ -1,12 +1,14 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
+import { session_cite } from '#scripts/issue/session-cite'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { run_status, type StatusParts } from './run-status'
 
-// `josh run:status <N>` — one call for the read-only status a run glances at (joshuafolkken/kit#2165):
+// `josh run:status <N>` — one call for the read-only status a run glances at:
 // the issue's state and labels (`issue:state`), the session's hand-off verdict (`cost --cut`), and the
 // invocation's carry counters (`run:carry`). Each is reused rather than reproduced, and the two async
 // reads run concurrently, so three round trips become one.
@@ -19,7 +21,6 @@ import { run_status, type StatusParts } from './run-status'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh run:status <issue-number> [--repo <owner/repo>]'
 const CARRY_NONE_NOTE = 'no run recorded here'
 const CARRY_UNREADABLE_NOTE = '(run record not bundled: unreadable)'
@@ -48,7 +49,7 @@ function valid_issue(positionals: ReadonlyArray<string>): string | undefined {
 
 	if (first === undefined || rest.length > 0) return undefined
 
-	return ISSUE_NUMBER_PATTERN.test(first) ? first : undefined
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(first) ? first : undefined
 }
 
 function parse(argv: ReadonlyArray<string>): StatusRequest | undefined {
@@ -88,7 +89,7 @@ async function gather(request: StatusRequest): Promise<StatusReads> {
 // One note for a read that produced nothing, naming which of the two it was — the same distinction
 // `issue:state` keeps, so a bundled failure still tells a retry from an answer.
 function failure_note(issue_number: string, kind: string): string {
-	return `(issue #${issue_number} not bundled: ${kind})`
+	return `(issue ${session_cite.issue(issue_number)} not bundled: ${kind})`
 }
 
 function carry_summary(carry: CarryRead): string {
@@ -145,8 +146,9 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 
 	const reads = await gather(request)
+	const report = run_status.format_report(to_parts(request.issue_number, reads))
 
-	console.info(run_status.format_report(to_parts(request.issue_number, reads)))
+	console.info(session_cite.text(report))
 
 	return exit_code(reads)
 }

package/scripts/run/run-status.ts

@@ -1,14 +1,13 @@
 import { issue_state, type IssueState } from '#scripts/issue/issue-state'
 
-// `josh run:status <N>` — the read-only status a run glances at, assembled into one report
-// (joshuafolkken/kit#2165). A run reads three independent facts to know where it stands — the issue's
-// own state, whether the session has crossed the hand-off budget, and its own carry counters — and
-// the procedure had it type `issue:state`, `cost --cut` and `run:carry` as three separate steps. This
-// joins the answers those three commands give, reusing each rather than reproducing it.
+// `josh run:status <N>` — the read-only status a run glances at, assembled into one report.
+// A run reads three independent facts to know where it stands — the issue's own state, whether the
+// session has crossed the hand-off budget, and its own carry counters. This joins the answers
+// `issue:state`, `cost --cut` and `run:carry` give, reusing each rather than reproducing it.
 //
 // **It is read-only, and that is the whole point** — the merge event has its own composite
-// (`run:merge`), and the pre-edit reads have theirs (`run:prep`); what was left was the passive glance
-// a resumed session or a non-merge decision takes, which must not write. `run:hold`'s claim and
+// (`run:merge`), and the pre-edit reads have theirs (`run:prep`); this is the passive glance a resumed
+// session or a non-merge decision takes, which must not write. `run:hold`'s claim and
 // `run:progress`'s clock mark are excluded for exactly that reason.
 //
 // The leading summary line carries the three facts on one line — the state, the cost verdict and the

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

@@ -13,10 +13,10 @@ import { run_headless } from './run-headless'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
 import { run_retrospective } from './run-retrospective'
-import { run_step, type StepInput } from './run-step'
+import { run_step, type ParentInput, type StepInput } from './run-step'
 
-// `josh run:step <N>` — print the run's next single action, computed from the event stream, the carry
-// record and the issue state (joshuafolkken/kit#2248). It reads exactly those three, never the
+// `josh run:step [<N>]` — print the run's next single action, computed from the event stream, the carry
+// record and the issue state. It reads exactly those three, never the
 // conversation: the issue facts through `run:prep`'s own gather (so this and `run:next` never answer
 // from different reads), the newest event off the stream, and the carry record's kind. The reader runs
 // the printed line, returns the result through `run:event`, and asks again — the loop `run:step`
@@ -25,17 +25,19 @@ import { run_step, type StepInput } from './run-step'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const USAGE = 'Usage: josh run:step <issue-number>'
+const USAGE =
+	'Usage: josh run:step [<issue-number>] — without a number it answers for the `backlogrun` carry record this session drives'
 
 interface RunReads {
 	carry_kind: CarryRead['kind']
 	is_retrospective_done: boolean
 	is_at_cut_cap: boolean
 	is_handed_off: boolean
+	is_merge_owed: boolean
 	last_event: string | undefined
 }
 
-// **A hand-off stops only the session that declared the record** (joshuafolkken/kit#2760). The record is
+// **A hand-off stops only the session that declared the record**. The record is
 // one per repository, so a `fullrun #M` a person starts in a fresh conversation beside a `backlogrun`
 // waiting for its successor reads the same handed-off mark — and would be told to stop on every step.
 // The owner is `--owner "$PPID"`, an ancestor of this process only in the session that took the cut.
@@ -50,6 +52,7 @@ const UNREADABLE_RUN: RunReads = {
 	is_retrospective_done: false,
 	is_at_cut_cap: false,
 	is_handed_off: false,
+	is_merge_owed: false,
 	last_event: undefined,
 }
 
@@ -65,23 +68,18 @@ function read_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))
 	// The last event *within this invocation's scope*, not the raw newest one: a stale event a previous
-	// 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), 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,
-	)
+	// invocation left on the stream — an old `child-launch`, say — must not be read as this run's
+	// position. Another issue's detached ship supervisor is left out the same way, and so — for a lane
+	// child — is every event that does not name its own issue.
+	const scope = run_event_scope.scope_of(carry)
+	const last = run_event_scope.last_issue_event(events, scope, issue_number, is_lane_child)
 
 	return {
 		carry_kind: carry.kind,
 		is_retrospective_done: run_carry.retrospective_done_of(carry),
-		is_at_cut_cap: carry.kind === 'carried' && run_carry.is_at_cut_cap(carry.carry),
+		is_at_cut_cap: carry.kind === 'carried' && run_headless.is_cut_capped(carry.carry),
 		is_handed_off: is_handed_off_here(carry),
+		is_merge_owed: run_event_scope.is_merge_owed(events, scope, issue_number),
 		last_event: last?.kind,
 	}
 }
@@ -102,6 +100,7 @@ function step_input(parts: PrepParts, run_reads: RunReads, is_lane_child: boolea
 		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_merge_owed: run_reads.is_merge_owed,
 		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.
@@ -120,7 +119,54 @@ async function gather(issue_number: string): Promise<Gathered> {
 	return { input: step_input(parts, run_reads, is_lane_child), ship_problems: parts.ship_problems }
 }
 
+const UNREADABLE_CARRY: CarryRead = { kind: 'unreadable' }
+
+// The parent's own position — a run asked about with no issue. The last event is the run's newest in
+// scope, whichever issue it names: a parent is positioned by the whole batch, never by one child.
+function parent_reads(directory: string): Pick<ParentInput, 'carry_kind' | 'last_event'> & {
+	carry: CarryRead
+} {
+	const carry = run_carry.read_carry(run_carry.carry_path(directory))
+	const events = run_event_stream.read_events(run_event_stream.target_of(directory))
+	const last = run_event_scope.last_scoped_event(events, run_event_scope.scope_of(carry))
+
+	return { carry, carry_kind: carry.kind, last_event: last?.kind }
+}
+
+function parent_input(directory: string | undefined): ParentInput {
+	const { carry, ...position } =
+		directory === undefined
+			? { carry: UNREADABLE_CARRY, carry_kind: UNREADABLE_CARRY.kind, last_event: undefined }
+			: parent_reads(directory)
+
+	return {
+		...position,
+		is_driving: run_headless.driven_here(carry, lane_reap.own_ancestry) !== undefined,
+		is_handed_off: is_handed_off_here(carry),
+		is_at_cut_cap: carry.kind === 'carried' && run_headless.is_cut_capped(carry.carry),
+		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		is_retrospective_done: run_carry.retrospective_done_of(carry),
+		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
+		is_retrospective_enabled: run_retrospective.is_enabled(),
+	}
+}
+
+// `unknown` is the one answer with nothing to run — no record this session drives — so it exits non-zero
+// with the usage, exactly as a position missing its issue state does.
+async function run_parent(): Promise<number> {
+	const { line } = run_step.parent_action(parent_input(await run_carry.repository_directory()))
+
+	console.info(line)
+	if (line !== run_step.UNKNOWN) return SUCCESS_EXIT_CODE
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length === 0) return await run_parent()
+
 	const issue_number = run_prep_cli.parse_number(argv)
 
 	if (issue_number === undefined) {
@@ -132,7 +178,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const { input, ship_problems } = await gather(issue_number)
 
 	console.info(run_step.next_action(input).line)
-	// On stderr, so stdout stays the one action line (joshuafolkken/kit#3154): what `josh ship` would
+	// On stderr, so stdout stays the one action line: what `josh ship` would
 	// refuse on is said at every step, while it is still cheap to meet.
 	if (ship_problems.length > 0) console.error(run_prep.ship_body(ship_problems))