@joshuafolkken/kit 1.1471.0 → 1.1514.0

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

@@ -1,22 +1,18 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { api_outage } from '#scripts/agent/api-outage'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
 import { lane_ledger } from '#scripts/lane/lane-ledger'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryOwner, type RunCarry } from '#scripts/run/carry/run-carry'
-import { run_event_scope } from '#scripts/run/event/run-event-scope'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
-import { run_ending } from '#scripts/run/run-ending'
 import { run_label } from '#scripts/run/run-label'
-import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
-import { run_merge_ship } from './run-merge-ship'
+import { run_merge, type ChildOutcome } from './run-merge'
+import { run_merge_signals } from './run-merge-signals'
 import { run_merge_steps, type FailedResult, type MergeContext } from './run-merge-steps'
 import { run_merge_token, type MergeToken } from './run-merge-token'
 
@@ -191,61 +187,6 @@ async function offered(ctx: MergeContext): Promise<OfferVerdict> {
 	return { token: await run_merge_steps.ask_next(ctx), code: SUCCESS_EXIT_CODE, is_offer: true }
 }
 
-// Whether the child's session ended through its environment — read only when `--output` named the
-// transcript, off otherwise: its exit record shows it could not reach the API, or the session was
-// killed inside a turn. The path is validated inside `run_ending`, so a missing output is "no".
-function read_is_outage(output: string | undefined): boolean {
-	if (output === undefined) return false
-
-	return api_outage.is_outage(run_ending.read_exit(output)) || run_ending.ended_mid_turn(output)
-}
-
-async function child_outages(child: string): Promise<number> {
-	const events = await run_event_stream_emit.current_events()
-
-	return events.filter(
-		(event) =>
-			event.kind === run_event_stream.EVENT_KIND.OUTAGE &&
-			run_event_scope.issue_named(event) === child,
-	).length
-}
-
-// An outage child is re-dispatched only so many times: one that ends the same way on every dispatch is
-// parked, since merges in other lanes reset the run-wide outage streak and would never stop it.
-async function read_is_retryable(child: string, output: string | undefined): Promise<boolean> {
-	const is_interrupted =
-		read_is_outage(output) || (await run_merge_ship.is_unanswered(child, output))
-
-	if (!is_interrupted) return false
-
-	return (await child_outages(child)) < run_merge.CONSECUTIVE_OUTAGE_LIMIT
-}
-
-type IssueRead = Awaited<ReturnType<typeof issue_state_cli.read_issue>>
-
-// The timeline is read only for an OPEN, unparked child — the one classification a merged closing pull
-// request changes. A CLOSED child was closed by GitHub, so it must carry no `merged_pr` for
-// `do_merged` to close again.
-async function read_merged_pr(child: string, read: IssueRead): Promise<string | undefined> {
-	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'failed') return undefined
-
-	return await issue_closing_pr.read_closing_pr(child)
-}
-
-async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingSignals> {
-	const [is_cut, merged_pr, is_outage] = await Promise.all([
-		run_merge_steps.has_resumable_cut(ctx.child),
-		read_merged_pr(ctx.child, read),
-		read_is_retryable(ctx.child, ctx.output),
-	])
-
-	return { is_outage, is_cut, merged_pr }
-}
-
-function outcome_of(read: IssueRead, signals: EndingSignals): ChildOutcome {
-	return read.kind === 'state' ? run_merge.classify_child(read.state, signals) : 'unresolved'
-}
-
 // A refused count means this session is not the carry record's owner, so the whole operation is
 // rejected — the lane is not closed and no next child is offered.
 function report_count_refused(carry: RunCarry | undefined): MergeVerdict {
@@ -397,6 +338,13 @@ async function on_skipped(ctx: MergeContext): Promise<MergeVerdict> {
 	return await offered(ctx)
 }
 
+// A child a person withdrew with `lane:withdraw`: the withdrawal already stopped it, closed its issue
+// and lane and put itself on the stream, so nothing is counted or written here and its seat goes to the
+// next child.
+async function on_withdrawn(ctx: MergeContext): Promise<MergeVerdict> {
+	return await offered(ctx)
+}
+
 // The child's own ending: it stopped before its commit for a person to look at, so nothing is counted
 // and no next child is offered.
 async function on_human_review(): Promise<MergeVerdict> {
@@ -422,6 +370,7 @@ const HANDLERS: Readonly<Record<ChildOutcome, (ctx: MergeContext) => Promise<Mer
 	split: on_skipped,
 	unresolved: on_unresolved,
 	shipping: on_shipping,
+	withdrawn: on_withdrawn,
 }
 
 // The whole merge event for one returned child, in-process: read its state, classify it, and run the
@@ -432,10 +381,12 @@ async function merge_child(ctx: MergeContext): Promise<MergeResult> {
 	}
 
 	const read = await issue_state_cli.read_issue(ctx.child, ctx.repo)
-	const signals = await read_signals(ctx, read)
-	const outcome = outcome_of(read, signals)
+	const signals = await run_merge_signals.read_signals(ctx, read)
+	const outcome = run_merge_signals.outcome_of(read, signals)
+
+	const { merged_pr, is_unanswered } = signals
 
-	return { outcome, ...(await HANDLERS[outcome]({ ...ctx, merged_pr: signals.merged_pr })) }
+	return { outcome, ...(await HANDLERS[outcome]({ ...ctx, merged_pr, is_unanswered })) }
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
@@ -461,7 +412,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 const run_merge_cli = {
 	merge_child,
 	parse,
-	read_merged_pr,
+	read_merged_pr: run_merge_signals.read_merged_pr,
 	record_merged,
 	run,
 }

package/scripts/run/merge/run-merge-signals.ts

@@ -0,0 +1,99 @@
+import { api_outage } from '#scripts/agent/api-outage'
+import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
+import { issue_merged } from '#scripts/issue/issue-merged'
+import type { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_ending } from '#scripts/run/run-ending'
+import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
+import { run_merge_ship } from './run-merge-ship'
+import { run_merge_steps, type MergeContext } from './run-merge-steps'
+
+// What `run:merge` reads beside a returned child's GitHub state before classifying it — the exit
+// record, the lane's cut, a merged closing pull request and a person's withdrawal — and the
+// classification those readings and the state decide (`run_merge.classify_child`).
+
+type IssueRead = Awaited<ReturnType<typeof issue_state_cli.read_issue>>
+
+// Whether the child's session ended through its environment — read only when `--output` named the
+// transcript, off otherwise: its exit record shows it could not reach the API, or the session was
+// killed inside a turn. The path is validated inside `run_ending`, so a missing output is "no".
+function read_is_outage(output: string | undefined): boolean {
+	if (output === undefined) return false
+
+	return api_outage.is_outage(run_ending.read_exit(output)) || run_ending.ended_mid_turn(output)
+}
+
+async function child_outages(child: string): Promise<number> {
+	const events = await run_event_stream_emit.current_events()
+
+	return events.filter(
+		(event) =>
+			event.kind === run_event_stream.EVENT_KIND.OUTAGE &&
+			run_event_scope.issue_named(event) === child,
+	).length
+}
+
+// An outage child is re-dispatched only so many times: one that ends the same way on every dispatch is
+// parked, since merges in other lanes reset the run-wide outage streak and would never stop it. **An
+// unanswered ship stop is told apart from an API outage**: the child reached the API, so it is
+// re-dispatched without adding to the run-wide streak (joshuafolkken/kit#3974).
+async function read_retryable(
+	child: string,
+	output: string | undefined,
+): Promise<{ is_outage: boolean; is_unanswered: boolean }> {
+	const is_api_outage = read_is_outage(output)
+	const is_unanswered = !is_api_outage && (await run_merge_ship.is_unanswered(child, output))
+
+	if (!is_api_outage && !is_unanswered) return { is_outage: false, is_unanswered: false }
+
+	const is_outage = (await child_outages(child)) < run_merge.CONSECUTIVE_OUTAGE_LIMIT
+
+	return { is_outage, is_unanswered: is_outage && is_unanswered }
+}
+
+// The timeline is read only for an OPEN, unparked child — the one classification a merged closing pull
+// request changes. A CLOSED child was closed by GitHub, so it must carry no `merged_pr` for
+// `do_merged` to close again.
+async function read_merged_pr(child: string, read: IssueRead): Promise<string | undefined> {
+	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'failed') return undefined
+
+	return await issue_closing_pr.read_closing_pr(child)
+}
+
+// A child that merged before `lane:withdraw` stopped it is merged, not withdrawn: the withdrawal's
+// event is already written, so only the timeline tells its merged close from the not-planned one. An
+// unread timeline answers `undefined`, and `outcome_of` asks again rather than guessing.
+async function read_is_withdrawn(child: string, read: IssueRead): Promise<boolean | undefined> {
+	const events = await run_event_stream_emit.current_events()
+
+	if (!run_event_scope.is_withdrawn(events, child)) return false
+	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'merged') return true
+	const is_merged = await issue_merged.read_merge_state(child)
+
+	return is_merged === undefined ? undefined : !is_merged
+}
+
+async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingSignals> {
+	const [is_cut, merged_pr, retryable, is_withdrawn] = await Promise.all([
+		run_merge_steps.has_resumable_cut(ctx.child),
+		read_merged_pr(ctx.child, read),
+		read_retryable(ctx.child, ctx.output),
+		read_is_withdrawn(ctx.child, read),
+	])
+
+	return { ...retryable, is_cut, merged_pr, is_withdrawn }
+}
+
+// An unread state is `unresolved` unless a withdrawal already settled the child, which is read locally;
+// a withdrawn child whose timeline could not tell its merge (`is_withdrawn` unset) is `unresolved` too.
+function outcome_of(read: IssueRead, signals: EndingSignals): ChildOutcome {
+	if (signals.is_withdrawn === undefined) return 'unresolved'
+
+	return run_merge.classify_child(read.kind === 'state' ? read.state : undefined, signals)
+}
+
+const run_merge_signals = { outcome_of, read_merged_pr, read_signals }
+
+export { run_merge_signals }

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

@@ -73,6 +73,8 @@ interface MergeContext {
 	// The merged pull request that closes the child, when GitHub left the child OPEN after the merge —
 	// the one `merged` child whose issue this command still has to close.
 	merged_pr?: string | undefined
+	// The outage is a ship stop no relaunch answered: re-dispatched, but not added to the streak.
+	is_unanswered?: boolean | undefined
 }
 
 interface FailedResult {
@@ -359,8 +361,16 @@ interface OutageResult {
 // the child, so it is re-dispatchable in the same run. Returns the record so the caller can read the
 // outage streak against its guard. Returns `is_refused: true` without touching labels when the carry
 // record rejected the count.
+async function count_outage(ctx: MergeContext): Promise<ApplyCarryResult> {
+	if (ctx.is_unanswered !== true) return await apply_carry(ctx, run_merge.change_of('outage'))
+
+	const refused = await refused_carry(ctx)
+
+	return refused === undefined ? { kind: 'none' } : { kind: 'refused', carry: refused }
+}
+
 async function do_outage(ctx: MergeContext): Promise<OutageResult> {
-	const result = await apply_carry(ctx, run_merge.change_of('outage'))
+	const result = await count_outage(ctx)
 
 	if (result.kind === 'refused') return { carry: result.carry, is_refused: true }
 

package/scripts/run/merge/run-merge.ts

@@ -24,10 +24,11 @@ const CLOSED_STATE = 'CLOSED'
 // failing every child it is handed rather than on failures scattered across a long run.
 const CONSECUTIVE_FAILURE_LIMIT = 3
 // Three outages in a row stop the run too — the same shape as the failure
-// guard, over its own streak. An outage is a child its environment ended — it could not reach the API,
-// its session was killed inside a turn, or its ship stopped with no relaunch — so a run of them is
-// the environment being down; stopping is what keeps the run from re-dispatching into a dead API
-// forever. A merge or a genuine child failure resets it (`run-carry.ts` → `next_outages`).
+// guard, over its own streak. An outage is a child its environment ended — it could not reach the API
+// or its session was killed inside a turn — so a run of them is the environment being down; stopping is
+// what keeps the run from re-dispatching into a dead API forever. A ship that stopped with no relaunch
+// is re-dispatched too but not counted: its child reached the API (joshuafolkken/kit#3974). A merge or
+// a genuine child failure resets it (`run-carry.ts` → `next_outages`).
 const CONSECUTIVE_OUTAGE_LIMIT = 3
 const ONE = 1
 
@@ -45,9 +46,12 @@ const ONE = 1
 //                   the child ended its session on purpose, so it is resumed rather than parked and
 //                   counts nothing.
 // - `failed`      — OPEN and carrying neither, and not an outage; the child did not finish.
+// - `withdrawn`   — a person withdrew it with `lane:withdraw`, read from the event stream before the
+//                   GitHub state: closed as not planned, or about to be, it is neither merged nor failed.
 // - `unresolved`  — the state could not be read; re-read before deciding.
 type ChildOutcome =
 	| 'merged'
+	| 'withdrawn'
 	| 'human-review'
 	| 'parked'
 	| 'split'
@@ -65,6 +69,10 @@ interface EndingSignals {
 	// The merged pull request whose `closes #N` names the child, when GitHub left the child OPEN after
 	// merging it.
 	merged_pr?: string | undefined
+	// The newest launch of the child was withdrawn by a person (`run_event_scope.is_withdrawn`).
+	is_withdrawn?: boolean | undefined
+	// The outage is a ship stop no relaunch answered, not an API the child could not reach.
+	is_unanswered?: boolean | undefined
 }
 
 const NO_SIGNALS: EndingSignals = { is_outage: false, is_cut: false }
@@ -107,12 +115,16 @@ function open_outcome(state: IssueState, signals: EndingSignals): ChildOutcome {
 	return unfinished_outcome(signals)
 }
 
-// The signals are read by the CLI and matter only for an OPEN child — a CLOSED child is merged
-// regardless of how the process exited.
+// The signals are read by the CLI and, but for a withdrawal, matter only for an OPEN child — a CLOSED
+// child is merged regardless of how the process exited. **A withdrawal is read first**: `lane:withdraw`
+// records it before stopping the child, so the parent may collect it while the issue is still OPEN, and
+// once it is CLOSED as not planned the closed state would otherwise read as a merge.
 function classify_child(
 	state: IssueState | undefined,
 	signals: EndingSignals = NO_SIGNALS,
 ): ChildOutcome {
+	if (signals.is_withdrawn === true) return 'withdrawn'
+
 	if (state === undefined) return 'unresolved'
 
 	if (is_closed(state)) return 'merged'
@@ -121,9 +133,9 @@ function classify_child(
 }
 
 // The counter change a child's outcome implies. A merge counts a merge (which resets the failure
-// streak); a failure counts a failure; a split, parked or human-review child counts nothing — a decision
-// waiting on a person is not the environment failing — and `undefined` says the carry record is left
-// untouched.
+// streak); a failure counts a failure; a split, parked, withdrawn or human-review child counts nothing —
+// a decision a person made or still owes is not the environment failing — and `undefined` says the
+// carry record is left untouched.
 function change_of(outcome: ChildOutcome): CarryChange | undefined {
 	if (outcome === 'merged') return { merged: ONE }
 

package/scripts/run/run-liveness.ts

@@ -103,7 +103,7 @@ const REASONS: Record<LivenessVerdict, string> = {
 		'A trace could not be read, so this says nothing about the unit. A trace that could not be read answers `undetermined`, never `stopped`.',
 }
 
-const ALIVE_ADVICE = 'Keep polling; do not touch the child.'
+const ALIVE_ADVICE = 'Keep waiting on `pnpm josh lane:await`; do not touch the child.'
 const SETTLED_ADVICE =
 	'Read the child with `pnpm josh issue:state <N>` and take the branch its state says.'
 // The unit stopped, but *why* it stopped — abandoned mid-implementation, or dead because it could not

package/scripts/run/run-poll-hook.ts

@@ -0,0 +1,157 @@
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { error_text } from '#scripts/lib/error-message'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { time_spans, type Span } from '#scripts/time-runtime/time-spans'
+import { run_headless } from './run-headless'
+import { run_watcher_hook } from './run-watcher-hook'
+
+// The `backlogrun` parent's and the wake session's poll, refused at its first repeat.
+//
+// **The parent waits on a blocking command, never on a re-read.** `backlog:drive` and `lane:await` hold
+// the turn until something the model has to read happens; a state read issued again with nothing
+// decided in between is a poll, and each one is a model turn spent on an answer that has not changed.
+//
+// **"Nothing decided in between" is read off the transcript**: the last completed call before this one
+// ran the same state read on the same operands, with no person's prompt after it. A different command, a person's prompt or
+// any other tool call in between breaks the streak, so a progress question answered twice is not one.
+//
+// **The parent test is `run_headless.driving_carry`'s**, the one the parent hand-off guard reads, so a
+// lane child, a person's session and a handed-off record are left alone. A wake session adopts the
+// record, so it reads as the parent here.
+
+const SWITCH_ENV_KEY = 'JOSH_POLL_GUARD'
+const BASH_TOOL = 'Bash'
+const STATE_READS: ReadonlySet<string> = new Set([
+	'josh lane:list',
+	'josh lane:output',
+	'josh run:board',
+	'josh run:carry',
+	'josh run:liveness',
+	'josh run:progress',
+	'josh run:wake',
+])
+
+const POLL_REASON =
+	'⛔ poll: this `backlogrun` session repeats a state read with nothing decided in between, on every ' +
+	'occurrence. Wait on `pnpm josh backlog:drive`, or `pnpm josh lane:await <N...> --owner "$PPID"` in ' +
+	'the background, and end the turn; its exit is the wake.'
+
+// The flags that make a state-read command write: `run:carry --filed` twice is two filings, and
+// `run:carry --cut` after `run:carry --json` is the hand-off, so neither is a re-read.
+const WRITING_FLAGS: ReadonlySet<string> = new Set([
+	'--begin',
+	'--cut',
+	'--done',
+	'--end',
+	'--every',
+	'--filed',
+	'--loop',
+	'--mark',
+	'--merged',
+	'--resume',
+	'--retrospective',
+	'--start',
+	'--stop',
+	'--wait',
+])
+
+const FLAG_PREFIX = '-'
+const NAME_WORDS = 2
+const SIGNATURE_SEPARATOR = ' '
+
+// A state read keyed by the command and its operands, or `undefined` for a call that is none.
+// **Operands, not flags**: `lane:output 1 <path>` then `lane:output 2 <path>` read two children, while
+// `run:board` and `run:board --chat` print one answer.
+function read_key(signature: string): string | undefined {
+	const words = signature.split(SIGNATURE_SEPARATOR)
+	const name = words.slice(0, NAME_WORDS).join(SIGNATURE_SEPARATOR)
+
+	if (!STATE_READS.has(name) || words.some((word) => WRITING_FLAGS.has(word))) return undefined
+
+	return words.filter((word) => !word.startsWith(FLAG_PREFIX)).join(SIGNATURE_SEPARATOR)
+}
+
+function read_keys(signatures: ReadonlyArray<string>): Array<string> {
+	return signatures.map((signature) => read_key(signature)).filter((key) => key !== undefined)
+}
+
+function state_reads_of(command: string): ReadonlyArray<string> {
+	return read_keys(time_shell.josh_signatures_of(command))
+}
+
+function command_of(input: unknown): string {
+	if (typeof input !== 'object' || input === null || !('command' in input)) return ''
+
+	return typeof input.command === 'string' ? input.command : ''
+}
+
+// The state reads the call runs, or none for a call this guard never judges: not a shell call, or a
+// delegated unit's (it names the parent's transcript, so only `agent_id` tells it apart).
+function candidate_reads(raw_payload: string): ReadonlyArray<string> {
+	const payload = hook_decision.parse_hook_payload(raw_payload)
+
+	if (payload?.tool_name !== BASH_TOOL || (payload.agent_id ?? '') !== '') return []
+
+	return state_reads_of(command_of(payload.tool_input))
+}
+
+// The last completed call or person's prompt; a model span is the turn itself, never a decision.
+function last_step(tail: string): Span | undefined {
+	return time_spans
+		.parse_timeline(tail)
+		.spans.findLast((span) => span.category !== time_spans.MODEL_CATEGORY)
+}
+
+function repeats_last_call(tail: string, reads: ReadonlyArray<string>): boolean {
+	const last = last_step(tail)
+
+	if (last?.category !== time_spans.TOOL_CATEGORY) return false
+
+	const last_reads = read_keys(last.josh_signatures)
+
+	return reads.some((key) => last_reads.includes(key))
+}
+
+// Every cheap test first: the carry record is read only for a call that already repeats a state read.
+function is_repeat(raw_payload: string): boolean {
+	const reads = hook_decision.is_switch_enabled(SWITCH_ENV_KEY) ? candidate_reads(raw_payload) : []
+	const transcript = reads.length === 0 ? undefined : run_watcher_hook.transcript_of(raw_payload)
+
+	if (transcript === undefined) return false
+
+	return repeats_last_call(time_density_hook.read_tail(transcript), reads)
+}
+
+/**
+ * The deny reason for a state read the driving `backlogrun` parent (or its wake session) issues again
+ * with nothing decided since the last one, or `undefined` when the call proceeds.
+ */
+async function poll_reason(
+	raw_payload: string,
+	is_parent: () => Promise<boolean> = run_headless.is_backlog_parent,
+): Promise<string | undefined> {
+	if (!is_repeat(raw_payload)) return undefined
+
+	return (await is_parent()) ? POLL_REASON : undefined
+}
+
+// It fails open: an unreadable transcript or carry record allows the call rather than wedging the run.
+async function safe_poll_reason(raw_payload: string): Promise<string | undefined> {
+	try {
+		return await poll_reason(raw_payload)
+	} catch (error) {
+		error_text.trace_swallowed('run_poll_hook.poll_reason', error)
+
+		return undefined
+	}
+}
+
+const run_poll_hook = {
+	POLL_REASON,
+	SWITCH_ENV_KEY,
+	poll_reason,
+	safe_poll_reason,
+}
+
+export { run_poll_hook }

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

@@ -14,15 +14,16 @@ 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 ParentInput, type StepInput } from './run-step'
+import { run_step_section } from './run-step-section'
 
-// `josh run:step [<N>]` — print the run's next single action, computed from the event stream, the carry
+// `josh run:step [<N>]` — print the run's next single action, followed by the section that governs it
+// (`run-step-section.ts`), 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`
 // exists to close.
 
-const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const USAGE =
@@ -154,16 +155,31 @@ function parent_input(directory: string | undefined): ParentInput {
 // `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()))
+	const action = run_step.parent_action(parent_input(await run_carry.repository_directory()))
 
-	console.info(line)
-	if (line !== run_step.UNKNOWN) return SUCCESS_EXIT_CODE
+	console.info(action.line)
+	if (action.line !== run_step.UNKNOWN) return run_step_section.print_for(action)
 
 	console.error(USAGE)
 
 	return FAILURE_EXIT_CODE
 }
 
+function report({ input, ship_problems }: Gathered): number {
+	const action = run_step.next_action(input)
+
+	console.info(action.line)
+	// On stderr, so stdout stays the action line and its rule: 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))
+
+	// A state that could not be read exits non-zero, exactly as `run:prep` and `run:next` exit on the
+	// same failure, so a position missing its issue state is never read as a confident next step.
+	if (input.state === undefined) return FAILURE_EXIT_CODE
+
+	return run_step_section.print_for(action)
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	if (argv.length === 0) return await run_parent()
 
@@ -175,16 +191,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 		return FAILURE_EXIT_CODE
 	}
 
-	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: 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))
-
-	// A state that could not be read exits non-zero, exactly as `run:prep` and `run:next` exit on the
-	// same failure, so a position missing its issue state is never read as a confident next step.
-	return input.state === undefined ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+	return report(await gather(issue_number))
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

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

@@ -0,0 +1,85 @@
+import { document_section_cli } from '#scripts/document/document-section-cli'
+import { run_step, type StepAction } from './run-step'
+
+// The section that governs each action `run:step` and `run:entry` print — the one table the action →
+// rule mapping lives in, so the manifests no longer carry a route table the reader walks to find it.
+// The command prints the section after its action line, which saves the `doc:section` turn the reader
+// would otherwise spend fetching a section the action already determined.
+//
+// **A heading that does not resolve fails the command**, exactly as `doc:section` refuses it: a pointer
+// renamed away would otherwise print the action without its rule, and the reader would act unread.
+
+const JOSH_PREFIX = 'pnpm josh '
+const COMMAND_SEPARATOR = ' '
+const SUCCESS_EXIT_CODE = 0
+
+// The key `run:entry` prints under — not a `run:step` action, but the entry's own read, kept in the
+// same table so every mechanically-chosen section has one home.
+const ENTRY = 'entry'
+
+interface SectionReference {
+	document: string
+	heading: string
+}
+
+function reference(document: string, heading: string): SectionReference {
+	return { document, heading }
+}
+
+// The gate's chain governs both the implementation it follows and a stopped ship's report.
+const CHAIN = reference('chain-rule.md', 'Run the review-to-merge chain')
+const PROGRESS = 'backlogrun-progress.md'
+
+// Keyed on a verdict token, or on the josh subcommand a command action runs. An action with no row —
+// `wait`, `stop`, a `decide:` line — has no rule to read beyond its own line.
+const GOVERNING_SECTIONS: ReadonlyMap<string, SectionReference> = new Map([
+	[ENTRY, reference('split-assessment.md', 'The question')],
+	[run_step.IMPLEMENT, CHAIN],
+	[run_step.HUMAN_REVIEW, reference('needs-human-review.md', '`needs-human-review`')],
+	[run_step.UPDATE_DEPS, reference('latest-gate.md', 'The dependency update')],
+	['followup', reference('followup.md', 'Run `pnpm josh followup`')],
+	['review:round2', reference('prompts/review.md', 'Review round cap')],
+	['run:merge', reference(PROGRESS, "Running a named epic's children")],
+	['backlog:next', reference('backlogrun-steps.md', 'The loop')],
+	['run:cut', reference('pre-gate-cut.md', 'Resuming')],
+	['ship', CHAIN],
+	['retrospective', reference('retrospective.md', 'The end-of-run retrospective')],
+	['run:carry', reference(PROGRESS, 'The hand-off')],
+])
+
+function key_of(action: StepAction): string {
+	if (action.kind !== 'command') return action.line
+
+	const [subcommand = ''] = action.line.slice(JOSH_PREFIX.length).split(COMMAND_SEPARATOR)
+
+	return subcommand
+}
+
+function section_for(key: string): SectionReference | undefined {
+	return GOVERNING_SECTIONS.get(key)
+}
+
+// Printed through `doc:section` itself, so the extent, the Bash-cap split and the refusal of an
+// unresolved heading are that command's, never a second copy of them.
+function print_section(key: string, root: string = process.cwd()): number {
+	const found = section_for(key)
+
+	if (found === undefined) return SUCCESS_EXIT_CODE
+
+	return document_section_cli.run([found.document, found.heading], root)
+}
+
+function print_for(action: StepAction, root: string = process.cwd()): number {
+	return print_section(key_of(action), root)
+}
+
+const run_step_section = {
+	ENTRY,
+	GOVERNING_SECTIONS,
+	key_of,
+	print_for,
+	print_section,
+}
+
+export type { SectionReference }
+export { run_step_section }