@joshuafolkken/kit 1.957.0 → 1.978.0

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

@@ -0,0 +1,104 @@
+import { run_hold, type HoldRead, type RunHold } from './run-hold'
+
+// joshuafolkken/kit#2796: a `halfrun` stops before its commit and **keeps** its hold, because the
+// uncommitted, hand-verified work is exactly what a second run would trample. The person then types
+// `fullrun #N` to ship it — and `run:entry`'s claim answered `busy` against that very hold, or, once the
+// hold had been cleared, the preflight advised stashing the verified diff away. The hand-off the
+// `halfrun` stop promised could not land, and each run improvised its own way past the guard.
+//
+// **The stop is recorded, never inferred.** A hold naming #N over a dirty tree is also what a `halfrun`
+// still implementing and a `backlogrun` child leave, and adopting either hands a half-written diff to
+// the gate and the merge. So the `halfrun` stop re-writes its own record with a stop mark
+// (`run:hold <N> --halfrun-stop`) — re-keying a `halfrun new`'s unnumbered record to the issue it filed —
+// and only a marked record is adopted. An expired one qualifies too, since a person may verify the next
+// day. The adopted record carries the `fullrun` mark instead, so the implementation-cut guard and
+// `run:cut --resume` read the tree as this `fullrun`'s from here on.
+
+const MARKED = 'marked'
+const FOREIGN = 'foreign'
+const UNREADABLE = 'unreadable'
+
+type StopMark = typeof FOREIGN | typeof MARKED | typeof UNREADABLE
+
+function hold_of(read: HoldRead): RunHold | undefined {
+	return read.kind === 'held' || read.kind === 'stale' ? read.hold : undefined
+}
+
+function is_halfrun_stop(read: HoldRead, issue: string, is_dirty: boolean): boolean {
+	const hold = hold_of(read)
+
+	return is_dirty && hold?.issue === issue && hold.is_halfrun_stop === true
+}
+
+// The stopping run's own record names its issue, or `new` when it entered as `halfrun new`; a free tree
+// is marked as well, since the work to protect is sitting in it either way.
+function is_own_record(read: HoldRead, issue: string): boolean {
+	const hold = hold_of(read)
+
+	return hold === undefined || hold.issue === issue || hold.issue === run_hold.UNNUMBERED_ISSUE
+}
+
+function mark_stop_at(target: string, issue: string): StopMark {
+	const read = run_hold.read_hold(target)
+
+	if (read.kind === 'unreadable') return UNREADABLE
+
+	if (!is_own_record(read, issue)) return FOREIGN
+
+	run_hold.release_hold(target)
+
+	return run_hold.create_halfrun_stop_hold(target, issue) ? MARKED : FOREIGN
+}
+
+// `false` leaves the record untouched, so the ordinary claim that follows decides the tree exactly as
+// it did before this resume existed.
+function adopt_at(target: string, issue: string, is_dirty: boolean): boolean {
+	if (!is_halfrun_stop(run_hold.read_hold(target), issue, is_dirty)) return false
+
+	run_hold.release_hold(target)
+
+	return run_hold.create_hold(target, issue, new Date(), true)
+}
+
+// **An unreadable git directory is no resume**, never a crash: `run:entry` must still print its one
+// summary line, and the ordinary claim that follows answers `unknown` for the same tree.
+async function hold_target(): Promise<string | undefined> {
+	try {
+		const directory = await run_hold.worktree_directory()
+
+		return directory === undefined ? undefined : run_hold.hold_path(directory)
+	} catch {
+		return undefined
+	}
+}
+
+// Read-only, so `run:entry` can ask the session budget before it takes anything over.
+async function is_pending(issue: string): Promise<boolean> {
+	const target = await hold_target()
+
+	if (target === undefined) return false
+
+	return is_halfrun_stop(run_hold.read_hold(target), issue, await run_hold.is_tree_dirty())
+}
+
+async function adopt(issue: string): Promise<boolean> {
+	const target = await hold_target()
+
+	if (target === undefined) return false
+
+	return adopt_at(target, issue, await run_hold.is_tree_dirty())
+}
+
+const run_halfrun_resume = {
+	FOREIGN,
+	MARKED,
+	UNREADABLE,
+	adopt,
+	adopt_at,
+	is_halfrun_stop,
+	is_pending,
+	mark_stop_at,
+}
+
+export type { StopMark }
+export { run_halfrun_resume }

package/scripts/run/run-headless.ts

@@ -99,6 +99,7 @@ const run_headless = {
 	environment,
 	is_backlog_parent,
 	is_headless,
+	is_owned_here,
 	must_keep_waiting,
 }
 

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { run_halfrun_resume } from './run-halfrun-resume'
 import { run_hold, type HoldRead, type RunHold } from './run-hold'
 import { run_preflight, type PreflightDecision } from './run-preflight'
 import { run_tidy_cli } from './run-tidy-cli'
@@ -43,8 +44,15 @@ const RELEASE_FLAG = '--release'
 // cannot — clearing a record somebody else left behind — is spelled out rather than reached by
 // typing the ordinary command.
 const FORCE_FLAG = '--force'
+// What `fullrun #N`'s entry claims with, so the record says the run is a `fullrun` — the one run whose
+// implementation cut outside a lane resumes as `fullrun #N` (joshuafolkken/kit#2760).
+const FULLRUN_FLAG = '--fullrun'
+const HALFRUN_STOP_FLAG = '--halfrun-stop'
+// The most a claim reads: the issue number and the one flag after it.
+const MAX_CLAIM_ARGUMENTS = 2
 const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
-const USAGE = 'Usage: josh run:hold [<issue-number>] | josh run:release [<issue-number> | --force]'
+const USAGE =
+	'Usage: josh run:hold [<issue-number> [--fullrun | --halfrun-stop]] | josh run:release [<issue-number> | --force]'
 
 const HOLD_VERDICT = 'hold'
 const BUSY_VERDICT = 'busy'
@@ -56,11 +64,19 @@ const NONE_VERDICT = 'none'
 const HELD_VERDICT = 'held'
 
 const FORCE_RELEASE_KIND = 'force-release'
+const HALFRUN_STOP_KIND = 'halfrun-stop'
+
+interface ClaimRequest {
+	kind: 'claim'
+	issue: string
+	is_fullrun?: boolean
+}
 
 type HoldRequest =
+	| ClaimRequest
 	| { kind: 'release'; claimant: string }
 	| { kind: typeof FORCE_RELEASE_KIND }
-	| { kind: 'claim'; issue: string }
+	| { kind: typeof HALFRUN_STOP_KIND; issue: string }
 
 const FORCE_RELEASE_REQUEST: HoldRequest = { kind: FORCE_RELEASE_KIND }
 
@@ -68,14 +84,24 @@ function release_request(claimant: string): HoldRequest {
 	return { kind: 'release', claimant }
 }
 
+// The flag after a numbered claim: absent, `--fullrun` or `--halfrun-stop`. Anything else is a usage
+// error.
+function numbered_claim(issue: string, flag: string | undefined): HoldRequest | undefined {
+	if (flag === undefined) return { kind: 'claim', issue }
+
+	if (flag === HALFRUN_STOP_FLAG) return { kind: HALFRUN_STOP_KIND, issue }
+
+	return flag === FULLRUN_FLAG ? { kind: 'claim', issue, is_fullrun: true } : undefined
+}
+
 function parse_claim(argv: ReadonlyArray<string>): HoldRequest | undefined {
-	const [first] = argv
+	const [first, flag] = argv
 
 	if (first === undefined) return { kind: 'claim', issue: run_hold.UNNUMBERED_ISSUE }
 
-	if (argv.length > 1 || !ISSUE_NUMBER_PATTERN.test(first)) return undefined
+	if (argv.length > MAX_CLAIM_ARGUMENTS || !ISSUE_NUMBER_PATTERN.test(first)) return undefined
 
-	return { kind: 'claim', issue: first }
+	return numbered_claim(first, flag)
 }
 
 function parse_release_argument(first: string): HoldRequest | undefined {
@@ -135,8 +161,10 @@ async function blocking_message(read: HoldRead): Promise<string | undefined> {
 
 // A record already here is never overwritten by a claim: overwriting is what the guard exists to
 // prevent, and the person who knows the other run has ended clears it with `run:release --force`.
-function take_free_tree(target: string, issue: string): number {
-	if (run_hold.create_hold(target, issue)) return report_hold()
+function take_free_tree(target: string, request: ClaimRequest): number {
+	const is_taken = run_hold.create_hold(target, request.issue, new Date(), request.is_fullrun)
+
+	if (is_taken) return report_hold()
 
 	return report_busy(run_hold.race_message(run_hold.read_hold(target), target))
 }
@@ -145,11 +173,11 @@ function take_free_tree(target: string, issue: string): number {
 // record with a plain write would tell two sessions that both found it expired that they both won —
 // the race the free path was just fixed for, reintroduced one branch over. Removing it first is what
 // turns the expired record into a free tree; the create is what decides between the two claimants.
-function replace_stale(target: string, issue: string, hold: RunHold): number {
+function replace_stale(target: string, request: ClaimRequest, hold: RunHold): number {
 	console.error(run_hold.stale_message(hold))
 	run_hold.release_hold(target)
 
-	return take_free_tree(target, issue)
+	return take_free_tree(target, request)
 }
 
 // A non-clean preflight verdict is not an error: it is an answer a loop branches on, exactly as
@@ -176,8 +204,8 @@ async function preflight_gate(issue: string, is_linked: boolean): Promise<number
 	return report_preflight(decision)
 }
 
-async function claim(target: string, issue: string, is_linked: boolean): Promise<number> {
-	const gate = await preflight_gate(issue, is_linked)
+async function claim(target: string, request: ClaimRequest, is_linked: boolean): Promise<number> {
+	const gate = await preflight_gate(request.issue, is_linked)
 
 	if (gate !== undefined) return gate
 
@@ -187,7 +215,9 @@ async function claim(target: string, issue: string, is_linked: boolean): Promise
 	if (blocked !== undefined) return report_busy(blocked)
 
 	const code =
-		read.kind === 'stale' ? replace_stale(target, issue, read.hold) : take_free_tree(target, issue)
+		read.kind === 'stale'
+			? replace_stale(target, request, read.hold)
+			: take_free_tree(target, request)
 
 	if (code === SUCCESS_EXIT_CODE) await run_tidy_cli.sweep()
 
@@ -261,8 +291,22 @@ async function read_worktree(): Promise<string | undefined> {
 	}
 }
 
+// **A `halfrun` stop marks its own record** (joshuafolkken/kit#2796) — the positive "this run has ended
+// over its verified diff" that `run:entry` adopts on `fullrun #N`. Another run's record is left alone.
+function mark_halfrun_stop(target: string, issue: string): number {
+	const mark = run_halfrun_resume.mark_stop_at(target, issue)
+
+	if (mark === run_halfrun_resume.MARKED) return report_hold()
+
+	if (mark === run_halfrun_resume.UNREADABLE) return report_unknown()
+
+	return report_busy(run_hold.race_message(run_hold.read_hold(target), target))
+}
+
 async function dispatch(request: HoldRequest, target: string, is_linked: boolean): Promise<number> {
-	if (request.kind === 'claim') return await claim(target, request.issue, is_linked)
+	if (request.kind === 'claim') return await claim(target, request, is_linked)
+
+	if (request.kind === HALFRUN_STOP_KIND) return mark_halfrun_stop(target, request.issue)
 
 	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
 

package/scripts/run/run-hold.ts

@@ -43,6 +43,15 @@ interface RunHold {
 	issue: string
 	taken_at: string
 	pid: number
+	// Set only by `fullrun #N`'s entry (`run:entry` claims with `--fullrun`, joshuafolkken/kit#2760).
+	// The implementation cut outside a lane resumes as `fullrun #N`, so a `halfrun` or an in-session
+	// `backlogrun` child — which hold the tree just the same — must not be read as one. Optional and
+	// `| undefined` because a record written before this field existed is simply not a `fullrun`'s.
+	is_fullrun?: boolean | undefined
+	// Set only at a `halfrun`'s stop before commit (`run:hold <N> --halfrun-stop`, joshuafolkken/kit#2796):
+	// the positive record that the run has *ended* over its verified diff, which is what lets
+	// `fullrun #N` adopt the hold. A running `halfrun` or a `backlogrun` child never carries it.
+	is_halfrun_stop?: boolean | undefined
 }
 
 type HoldRead =
@@ -81,6 +90,8 @@ const run_hold_schema = z.object({
 	issue: z.string(),
 	taken_at: z.string(),
 	pid: z.number(),
+	is_fullrun: z.boolean().optional(),
+	is_halfrun_stop: z.boolean().optional(),
 })
 
 // `undefined` for anything that is not a well-formed record, so the caller decides what a broken one
@@ -125,8 +136,8 @@ function read_hold(target: string, now: Date = new Date()): HoldRead {
 	return classify(stamp_file.read_stamp_text(target), now)
 }
 
-function build_hold(issue: string, now: Date): RunHold {
-	return { issue, taken_at: now.toISOString(), pid: process.pid }
+function build_hold(issue: string, now: Date, is_fullrun?: boolean): RunHold {
+	return { issue, taken_at: now.toISOString(), pid: process.pid, is_fullrun }
 }
 
 function write_hold(target: string, issue: string, now: Date = new Date()): RunHold {
@@ -141,8 +152,18 @@ function write_hold(target: string, issue: string, now: Date = new Date()): RunH
 // an entry point in the same second both read `free`, and a write would tell both of them they won —
 // which is the incident this guard was written after, reproduced by the guard itself. `false` means
 // the other one got there first.
-function create_hold(target: string, issue: string, now: Date = new Date()): boolean {
-	return stamp_file.create_stamp(target, build_hold(issue, now))
+function create_hold(
+	target: string,
+	issue: string,
+	now: Date = new Date(),
+	is_fullrun?: boolean,
+): boolean {
+	return stamp_file.create_stamp(target, build_hold(issue, now, is_fullrun))
+}
+
+// The claim a `halfrun` stop leaves behind: the same exclusive create, carrying the stop mark.
+function create_halfrun_stop_hold(target: string, issue: string, now: Date = new Date()): boolean {
+	return stamp_file.create_stamp(target, { ...build_hold(issue, now), is_halfrun_stop: true })
 }
 
 // **A tree with uncommitted work in it is never handed over, however old its record is.** No age can
@@ -238,6 +259,7 @@ const run_hold = {
 	RELEASE_COMMAND,
 	UNNUMBERED_ISSUE,
 	classify,
+	create_halfrun_stop_hold,
 	create_hold,
 	describe_holder,
 	foreign_release_message,

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

@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { api_outage } from '#scripts/agent/api-outage'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
+import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { run_carry, type CarryOwner, type RunCarry } from './run-carry'
 import { run_ending } from './run-ending'
@@ -202,17 +203,27 @@ function read_is_outage(output: string | undefined): boolean {
 	return api_outage.is_outage(run_ending.read_exit(output))
 }
 
-async function read_signals(ctx: MergeContext): Promise<EndingSignals> {
-	return {
-		is_outage: read_is_outage(ctx.output),
-		is_cut: await run_merge_steps.has_resumable_cut(ctx.child),
-	}
+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 (joshuafolkken/kit#2769).
+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)
 }
 
-function outcome_of(
-	read: Awaited<ReturnType<typeof issue_state_cli.read_issue>>,
-	signals: EndingSignals,
-): ChildOutcome {
+async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingSignals> {
+	const [is_cut, merged_pr] = await Promise.all([
+		run_merge_steps.has_resumable_cut(ctx.child),
+		read_merged_pr(ctx.child, read),
+	])
+
+	return { is_outage: read_is_outage(ctx.output), is_cut, merged_pr }
+}
+
+function outcome_of(read: IssueRead, signals: EndingSignals): ChildOutcome {
 	return read.kind === 'state' ? run_merge.classify_child(read.state, signals) : 'unresolved'
 }
 
@@ -238,8 +249,8 @@ async function on_merged(ctx: MergeContext): Promise<MergeVerdict> {
 	return emit(await run_merge_steps.ask_next(ctx), SUCCESS_EXIT_CODE)
 }
 
-async function on_failed(ctx: MergeContext): Promise<MergeVerdict> {
-	const result = await run_merge_steps.do_failed(ctx)
+async function on_failed(ctx: MergeContext, cause?: string): Promise<MergeVerdict> {
+	const result = await run_merge_steps.do_failed(ctx, cause)
 
 	if (result.is_refused) return report_count_refused(result.carry)
 
@@ -291,7 +302,9 @@ async function on_cut(ctx: MergeContext): Promise<MergeVerdict> {
 
 	if (refused !== undefined) return report_count_refused(refused)
 
-	if (!(await run_merge_steps.resume_cut(ctx.child))) return await on_failed(ctx)
+	if (!(await run_merge_steps.resume_cut(ctx.child))) {
+		return await on_failed(ctx, run_merge_steps.CUT_RELAUNCH_CAUSE)
+	}
 
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.CHILD_LAUNCH,
@@ -358,9 +371,10 @@ async function merge_child(ctx: MergeContext): Promise<MergeResult> {
 	}
 
 	const read = await issue_state_cli.read_issue(ctx.child, ctx.repo)
-	const outcome = outcome_of(read, await read_signals(ctx))
+	const signals = await read_signals(ctx, read)
+	const outcome = outcome_of(read, signals)
 
-	return { outcome, ...(await HANDLERS[outcome](ctx)) }
+	return { outcome, ...(await HANDLERS[outcome]({ ...ctx, merged_pr: signals.merged_pr })) }
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

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

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { git_followup_issue_close } from '#scripts/git/git-followup-issue-close'
 import { git_gh_issue_write } from '#scripts/git/git-gh-issue-write'
 import { git_stash } from '#scripts/git/git-stash'
 import { IN_PROGRESS_LABEL, NEEDS_DECISION_LABEL } from '#scripts/git/issue-labels'
@@ -34,6 +35,12 @@ const LANES = '--lanes'
 const REPO_FLAG = '--repo'
 const LANE_CLOSE_OCCASION = 'lane close'
 const GIT_ENTRY = '.git'
+const MERGE_CLOSER = 'pnpm josh run:merge'
+const SINGLE_READ = { attempts: 1, interval_ms: 0 }
+// What the driver judged when it parks a child, stated on the issue (joshuafolkken/kit#2769).
+const FAILED_CAUSE = 'the child’s session ended with its issue still open and unfinished.'
+const CUT_RELAUNCH_CAUSE =
+	'its lane held a declared cut, but no successor could be relaunched from it (or it already was once).'
 
 // One returned child's context, gathered from the command line by the CLI.
 interface MergeContext {
@@ -46,6 +53,9 @@ interface MergeContext {
 	// ending apart from a genuine child failure (joshuafolkken/kit#2240); absent leaves outage detection
 	// off, so the child is classified from its GitHub state alone as before.
 	output?: string | undefined
+	// 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 (joshuafolkken/kit#2769).
+	merged_pr?: string | undefined
 }
 
 interface FailedResult {
@@ -164,6 +174,22 @@ async function post_counters(ctx: MergeContext, carry: RunCarry | undefined): Pr
 	await git_gh_issue_write.issue_try_comment(ctx.epic, run_merge.counters_comment(carry))
 }
 
+// A child merged while GitHub left it OPEN is closed here, through the one close `followup` uses
+// (joshuafolkken/kit#2769). The state was just read OPEN, so it is read once rather than waited on. A
+// close that fails is reported with its recovery and does not undo the merge being counted.
+async function close_merged_open(ctx: MergeContext): Promise<void> {
+	if (ctx.merged_pr === undefined) return
+
+	try {
+		await git_followup_issue_close.ensure_issue_closed(
+			{ issue_number: ctx.child, pr_url: ctx.merged_pr, closer: MERGE_CLOSER },
+			SINGLE_READ,
+		)
+	} catch {
+		console.error(`#${ctx.child}: could not be closed — ${git_followup_issue_close.CLOSE_RECOVERY}`)
+	}
+}
+
 // A merged child: count the merge (which resets the failure streak), return to the default branch,
 // stash any uncommitted work the lane still holds and close it, and mirror the counters onto the epic. Returns the carry when the ownership check
 // fails — the caller treats a non-undefined return as a hard refusal and must not offer a next child
@@ -173,6 +199,7 @@ async function do_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
 
 	if (refused !== undefined) return refused
 
+	await close_merged_open(ctx)
 	await sync_main()
 	const result = await apply_carry(ctx, {
 		...run_merge.change_of('merged'),
@@ -202,8 +229,10 @@ async function remove_in_progress(child: string): Promise<void> {
 // issue number forever, joshuafolkken/kit#2421), drop the stale `in-progress`, and park it with
 // `needs-decision` so the next offer does not hand the same child straight back. Returns the record
 // so the caller can read the streak against the guard. Returns `is_refused: true` without touching labels when the
-// carry record rejected the count (joshuafolkken/kit#2114).
-async function do_failed(ctx: MergeContext): Promise<FailedResult> {
+// carry record rejected the count (joshuafolkken/kit#2114). A park is always explained on the issue —
+// `cause` says what was judged, and the comment what was read and what a person does next
+// (joshuafolkken/kit#2769).
+async function do_failed(ctx: MergeContext, cause: string = FAILED_CAUSE): Promise<FailedResult> {
 	const result = await apply_carry(ctx, run_merge.change_of('failed'))
 
 	if (result.kind === 'refused') return { carry: result.carry, is_parked: false, is_refused: true }
@@ -214,6 +243,12 @@ async function do_failed(ctx: MergeContext): Promise<FailedResult> {
 	await remove_in_progress(ctx.child)
 	const is_parked = await git_gh_issue_write.issue_add_label(ctx.child, NEEDS_DECISION_LABEL)
 
+	if (is_parked) {
+		const reason = { child: ctx.child, cause, carry, output: ctx.output }
+
+		await git_gh_issue_write.issue_try_comment(ctx.child, run_merge.park_comment(reason))
+	}
+
 	return { carry, is_parked, is_refused: false }
 }
 
@@ -311,6 +346,7 @@ async function ask_next(ctx: MergeContext): Promise<string> {
 }
 
 const run_merge_steps = {
+	CUT_RELAUNCH_CAUSE,
 	apply_carry,
 	ask_next,
 	do_failed,

package/scripts/run/run-merge.ts

@@ -32,7 +32,9 @@ const ONE = 1
 
 // What a returned child turned out to be, decided from its GitHub state and — for the failed case
 // alone — the exit record.
-// - `merged`      — CLOSED; the child finished and its pull request merged.
+// - `merged`      — CLOSED; the child finished and its pull request merged. Also an OPEN, unparked
+//                   child a merged pull request's `closes #N` names — GitHub merged it without closing
+//                   the issue (joshuafolkken/kit#2769).
 // - `human-review` — OPEN and carrying `needs-human-review`; the run's own ending (SKILL.md → §2z).
 // - `parked`      — OPEN and carrying `needs-decision` or `already-done`; a person still owns it.
 // - `split`       — OPEN and carrying `epic`; its work was divided into new children.
@@ -60,6 +62,9 @@ type ChildOutcome =
 interface EndingSignals {
 	is_outage: boolean
 	is_cut: boolean
+	// The merged pull request whose `closes #N` names the child, when GitHub left the child OPEN after
+	// merging it (joshuafolkken/kit#2769).
+	merged_pr?: string | undefined
 }
 
 const NO_SIGNALS: EndingSignals = { is_outage: false, is_cut: false }
@@ -82,8 +87,12 @@ function is_parked(state: IssueState): boolean {
 // An OPEN, unparked child that is not waiting on a person: a declared cut is resumed
 // (joshuafolkken/kit#2484), and it is read before the outage so a cut whose process then lost the API is
 // still resumed from its record; an OPEN, unparked child that could not reach the API is an `outage`,
-// not a `failed` (joshuafolkken/kit#2240).
+// not a `failed` (joshuafolkken/kit#2240). **A merged pull request that closes it is read first**: the
+// work landed and only GitHub's close did not, so it is `merged` — never a failure counted against the
+// guard (joshuafolkken/kit#2769).
 function unfinished_outcome(signals: EndingSignals): ChildOutcome {
+	if (signals.merged_pr !== undefined) return 'merged'
+
 	if (signals.is_cut) return 'cut'
 
 	return signals.is_outage ? 'outage' : 'failed'
@@ -152,15 +161,44 @@ function counters_comment(carry: RunCarry): string {
 	].join('\n')
 }
 
+// Why the run parked a child it judged failed (joshuafolkken/kit#2769). A child that stops itself
+// leaves its own comment; one the driver stops left nothing, so a person opening the issue could not
+// tell why it carried `needs-decision`. Script-emitted, so English.
+interface ParkReason {
+	child: string
+	cause: string
+	carry: RunCarry | undefined
+	output: string | undefined
+}
+
+function streak_line(carry: RunCarry | undefined): string {
+	if (carry === undefined) return '- Consecutive failures: not recorded (no carry record).'
+
+	return `- Consecutive failures: ${String(carry.failures)} of ${String(CONSECUTIVE_FAILURE_LIMIT)} (the run stops at ${String(CONSECUTIVE_FAILURE_LIMIT)}).`
+}
+
+function park_comment(reason: ParkReason): string {
+	const transcript = reason.output === undefined ? '' : ` (\`${reason.output}\`)`
+
+	return [
+		'Parked with `needs-decision` by `pnpm josh run:merge`, the `backlogrun` driver — not by the child itself.',
+		`- Why: ${reason.cause}`,
+		'- Read: the issue is OPEN, carries none of `needs-decision`, `already-done`, `needs-human-review` or `epic`, and no merged pull request’s `closes #N` names it.',
+		streak_line(reason.carry),
+		`- Next: read the child’s transcript${transcript}, then either resume it with \`fullrun #${reason.child}\`, or record the decision here and remove \`needs-decision\`.`,
+	].join('\n')
+}
+
 const run_merge = {
 	CONSECUTIVE_FAILURE_LIMIT,
 	CONSECUTIVE_OUTAGE_LIMIT,
 	change_of,
 	classify_child,
 	counters_comment,
+	park_comment,
 	is_guard_tripped,
 	is_outage_guard_tripped,
 }
 
-export type { ChildOutcome, EndingSignals }
+export type { ChildOutcome, EndingSignals, ParkReason }
 export { run_merge }

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

@@ -6,10 +6,12 @@ import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 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
-// `human_review` line (`issue:state`), and the dependency-update scope (`latest:scope`). Each is
+// `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
 // one.
 //
@@ -37,6 +39,7 @@ interface PrepReads {
 	state: StateRead
 	latest: LatestDecision
 	has_changes: boolean
+	locations: string
 }
 
 // Exactly one issue number, or the call is refused: `run:prep` prepares one run, and a second number
@@ -90,8 +93,10 @@ async function gather(issue_number: string): Promise<PrepReads> {
 		issue_state_cli.read_issue(issue_number),
 		lane_has_changes(),
 	])
+	// Located from the body just read, so it waits for that read rather than joining the batch above.
+	const locations = await run_prep_locate.locate(content.kind === 'ok' ? content.block : '')
 
-	return { content, state, latest: latest_decision(), has_changes }
+	return { content, state, latest: latest_decision(), has_changes, locations }
 }
 
 function content_body(issue_number: string, content: BlockRead): string {
@@ -110,6 +115,7 @@ function to_parts(issue_number: string, reads: PrepReads): PrepParts {
 		latest_scope: reads.latest.scope,
 		latest_reason: reads.latest.reason,
 		has_changes: reads.has_changes,
+		locations: reads.locations,
 	}
 }