@joshuafolkken/kit 1.1455.0 → 1.1514.0

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

@@ -23,10 +23,12 @@ const CLOSED_STATE = 'CLOSED'
 // resets the streak (`run-carry.ts` → `next_failures`), so the guard trips only on an environment
 // failing every child it is handed rather than on failures scattered across a long run.
 const CONSECUTIVE_FAILURE_LIMIT = 3
-// Three API outages in a row stop the run too — the same shape as the failure
-// guard, over its own streak. An outage is a child that could not reach the API, 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`).
+// 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
+// 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
 
@@ -44,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'
@@ -64,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 }
@@ -106,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'
@@ -120,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-ending.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs'
+import { readFileSync, statSync } from 'node:fs'
 import { agent_exit_record } from '#scripts/agent/agent-exit-record'
 import { api_outage } from '#scripts/agent/api-outage'
 import type { ClaudeResultEvent } from '#scripts/agent/claude-result-event'
@@ -179,7 +179,7 @@ async function read_cut_taken(issue: string): Promise<boolean> {
 	return read.kind === 'carried' && read.cut.invocation === run_cut.invocation_for(issue)
 }
 
-function read_exit(output_path: string): ClaudeResultEvent | undefined {
+function read_transcript(output_path: string): string | undefined {
 	const safe_path = run_liveness.to_safe_path(output_path)
 
 	if (safe_path === undefined) return undefined
@@ -188,12 +188,38 @@ function read_exit(output_path: string): ClaudeResultEvent | undefined {
 		// Validated by `run_liveness.to_safe_path` — normalized, required absolute, confined to the
 		// allowed roots — the same check `josh lane:output` gates a transcript path with, reused rather
 		// than re-spelled so the two cannot disagree.
-		return agent_exit_record.read_exit_record(readFileSync(safe_path, 'utf8')) // NOSONAR
+		return readFileSync(safe_path, 'utf8') // NOSONAR
+	} catch {
+		return undefined
+	}
+}
+
+function read_exit(output_path: string): ClaudeResultEvent | undefined {
+	const transcript = read_transcript(output_path)
+
+	return transcript === undefined ? undefined : agent_exit_record.read_exit_record(transcript)
+}
+
+// When the child's transcript was last written, in epoch milliseconds — `undefined` when unreadable.
+function written_at(output_path: string): number | undefined {
+	const safe_path = run_liveness.to_safe_path(output_path)
+
+	if (safe_path === undefined) return undefined
+
+	try {
+		return statSync(safe_path).mtimeMs // NOSONAR — validated as `read_transcript` validates it
 	} catch {
 		return undefined
 	}
 }
 
+// The child's session was killed inside a turn rather than finishing it.
+function ended_mid_turn(output_path: string): boolean {
+	const transcript = read_transcript(output_path)
+
+	return transcript !== undefined && agent_exit_record.is_mid_turn(transcript)
+}
+
 async function read_traces(request: EndingRequest): Promise<EndingTraces> {
 	const [is_child_closed, is_cut_taken, is_tree_dirty] = await Promise.all([
 		read_child_closed(request.issue, request.repo),
@@ -218,7 +244,9 @@ async function check(request: EndingRequest): Promise<EndingDecision> {
 const run_ending = {
 	check,
 	decide,
+	ended_mid_turn,
 	read_exit,
+	written_at,
 }
 
 export type { EndingDecision, EndingRequest, EndingTraces, EndingVerdict }

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-parent-cut-hook.ts

@@ -53,16 +53,11 @@ function current_state(): ParentCutState {
 const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
 
 const PARENT_CUT_REASON =
-	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` (it owns the live carry record) and ' +
-	`its recent-context cost has crossed the shared ${THRESHOLD_TEXT} threshold between merges, so every ` +
-	'later request re-reads the accumulated context (joshuafolkken/kit#2947). Take the hand-off now rather ' +
-	'than at the next merge: follow `.claude/skills/workflow-commands/backlogrun-progress.md` → "The ' +
-	'hand-off" from its `over` branch — open no new lane and take no new child, read `pnpm josh lane:list`, ' +
-	'make sure every lane in flight records an output path, then run `pnpm josh run:carry --cut --owner ' +
-	'"$PPID"` and, unless it answers `capped`, `pnpm josh run:wake`, post the progress comment and end the ' +
-	'turn. A lane nobody can poll means the cut does not happen; carry on and this asks again later. ' +
-	'Reissue this call when the hand-off is done or cannot be taken — the guard stays quiet for a while ' +
-	'after it refuses, so the hand-off calls themselves are not refused.'
+	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` and its recent-context cost ' +
+	`crossed the ${THRESHOLD_TEXT} threshold between merges. Take the hand-off now: open no new lane, ` +
+	'follow `backlogrun-progress.md` → "The hand-off" (`pnpm josh run:carry --cut --owner "$PPID"`, then ' +
+	'`pnpm josh run:wake` unless `capped`) and end the turn. Reissue this call once done or if it ' +
+	'cannot be taken.'
 
 // Neither an uncapped parent's own record nor a measured `over` is optional: a capped record has no cut
 // left to take (`run:carry --cut` answers `capped`), and an unmeasurable session is left alone here —

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-preflight.ts

@@ -343,8 +343,7 @@ async function read_candidate(
 ): Promise<ChildState | undefined> {
 	const state = await read_pr_of_branch(name)
 
-	if (state.pr_state !== NO_PR) return state
-	if (await has_commits_beyond(context.base, references)) return state
+	if (state.pr_state !== NO_PR || (await has_commits_beyond(context.base, references))) return state
 
 	return (await is_held_dirty(name, context.lane)) ? state : undefined
 }

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 }

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

@@ -27,8 +27,7 @@ const STOP_RECOVERY =
 // this type is for the run that halted needing a person. An `unreadable` record is not announced: with
 // nothing readable there is no run this can honestly say stopped.
 function plan(read: CarryRead, reason: string | undefined): StopNotice | undefined {
-	if (reason === undefined || reason.length === 0) return undefined
-	if (read.kind !== 'carried') return undefined
+	if (reason === undefined || reason.length === 0 || read.kind !== 'carried') return undefined
 
 	return { reason }
 }

package/scripts/run/run-watcher-guard.ts

@@ -49,9 +49,12 @@ async function owes_watcher(): Promise<boolean> {
 // `run_progress_clock.life_target_of(git_directory)`. Passed in rather than resolved here so the
 // caller can use whichever resolution fits its sync/async context.
 async function check(life_target: string): Promise<GuardResult> {
-	if (!(await owes_watcher())) return OK_RESULT
-
-	if (run_progress_clock.is_life_fresh(life_target, STALE_THRESHOLD_MS)) return OK_RESULT
+	if (
+		!(await owes_watcher()) ||
+		run_progress_clock.is_life_fresh(life_target, STALE_THRESHOLD_MS)
+	) {
+		return OK_RESULT
+	}
 
 	return { kind: 'stale', note: STALE_NOTE }
 }