@joshuafolkken/kit 1.953.0 → 1.972.0

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

@@ -0,0 +1,167 @@
+import { run_cut, type CutState, type RunCut } from './run-cut'
+
+// The verdict tokens `josh run:cut` answers with and the reports that print them, split out of
+// `run-cut-cli.ts` so the CLI keeps to acting on the record. The contract is unchanged: **standard
+// output carries exactly one token** and every explanation goes to standard error.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+const CUT_VERDICT = 'cut'
+const RESUME_VERDICT = 'resume'
+// An implementation-phase resume: the fresh process continues implementing rather than going to the
+// gate (joshuafolkken/kit#1933). It is a distinct token so the resuming child branches on it without
+// re-reading the record.
+const RESUME_IMPL_VERDICT = 'resume-impl'
+const FRESH_VERDICT = 'fresh'
+// The recent-window context is under the shared cut threshold, so the pre-gate cut was not worth its
+// resume and nothing was cut (joshuafolkken/kit#2312). A benign, non-failing answer: the run carries
+// on to the gate itself, exactly as `not-a-lane` does.
+const UNDER_THRESHOLD_VERDICT = 'under-threshold'
+const STALE_VERDICT = 'stale'
+// The record matched the tree but carried no instruction to resume on, so the run was refused rather
+// than continued blind to what it was told to do (joshuafolkken/kit#2354).
+const INCOMPLETE_VERDICT = 'incomplete'
+// The `--handoff` path was given but could not be read as a handoff, or was too large for the record;
+// the cut is refused rather than taken without the instruction it was meant to carry.
+const BAD_HANDOFF_VERDICT = 'bad-handoff'
+const HANDED_OFF_VERDICT = 'handed-off'
+const BUSY_VERDICT = 'busy'
+const NOT_A_LANE_VERDICT = 'not-a-lane'
+const UNREADY_VERDICT = 'unready'
+const FAILED_VERDICT = 'failed'
+const ENDED_VERDICT = 'ended'
+const UNREADABLE_VERDICT = 'unreadable'
+const UNKNOWN_VERDICT = 'unknown'
+// The asking session is over the shared context-cut threshold, so an implementation cut was not
+// resumed into it (joshuafolkken/kit#2760) — the same refusal `run:carry` answers `over` with.
+const OVER_VERDICT = 'over'
+
+function report(verdict: string, code: number): number {
+	console.info(verdict)
+
+	return code
+}
+
+function report_stale(cut_record: RunCut): number {
+	console.error(run_cut.stale_message(cut_record))
+
+	return report(STALE_VERDICT, FAILURE_EXIT_CODE)
+}
+
+function report_busy(cut_record: RunCut): number {
+	console.error(run_cut.busy_message(cut_record))
+
+	return report(BUSY_VERDICT, FAILURE_EXIT_CODE)
+}
+
+// The record matched the tree but carried no instruction; the run is refused rather than continued
+// without what it was told to do (joshuafolkken/kit#2354).
+function report_incomplete(cut_record: RunCut): number {
+	console.error(run_cut.incomplete_message(cut_record))
+
+	return report(INCOMPLETE_VERDICT, FAILURE_EXIT_CODE)
+}
+
+// The `--handoff` file parsed but the assembled record would not fit the byte bound — the scalar fields
+// carry a handoff that fit alone past the cap (joshuafolkken/kit#2354).
+const HANDOFF_OVERFLOW_NOTE = '--handoff <path> would grow the cut record past its byte bound'
+// An implementation cut resumes into implementation, and that resume refuses a record with no
+// instruction (`incomplete`) — so the cut is refused here instead of relaunching a successor that can
+// only stop (joshuafolkken/kit#2484).
+const HANDOFF_MISSING_NOTE = 'this cut resumes into implementation and needs --handoff <path>'
+
+function report_bad_handoff(note: string): number {
+	console.error(`${note}. Nothing was cut; write the handoff file and reissue.`)
+
+	return report(BAD_HANDOFF_VERDICT, FAILURE_EXIT_CODE)
+}
+
+// A successor already resumed this cut; a process woken after its own hand-off is told to stop rather
+// than to investigate (joshuafolkken/kit#1935). It is a benign, non-failing stop.
+function report_handed_off(cut_record: RunCut): number {
+	console.error(run_cut.handed_off_message(cut_record))
+
+	return report(HANDED_OFF_VERDICT, SUCCESS_EXIT_CODE)
+}
+
+function report_unreadable(): number {
+	console.error(run_cut.unreadable_message())
+
+	return report(UNREADABLE_VERDICT, FAILURE_EXIT_CODE)
+}
+
+function report_unknown(): number {
+	console.error(run_cut.unknown_message())
+
+	return report(UNKNOWN_VERDICT, FAILURE_EXIT_CODE)
+}
+
+// A cut is only meaningful on a lane branch whose implementation is uncommitted. On the default
+// branch, or with a clean tree, there is nothing to carry across the boundary.
+function refuse_unready(state: CutState): number {
+	console.error(
+		`Not ready to cut on ${state.branch} (dirty: ${String(state.is_dirty)}); a cut needs an uncommitted lane branch. Nothing was cut.`,
+	)
+
+	return report(UNREADY_VERDICT, FAILURE_EXIT_CODE)
+}
+
+// Below the shared context threshold there is no accumulation a cut would drop, so the resume it would
+// relaunch costs more than it saves; the current process carries the run on to the gate uncut.
+function report_under_threshold(): number {
+	console.error(
+		'The recent-window context is under the shared cut threshold, so nothing was cut; a resume would cost more than the accumulation it would drop. Continue to the gate.',
+	)
+
+	return report(UNDER_THRESHOLD_VERDICT, SUCCESS_EXIT_CODE)
+}
+
+// **An implementation cut is never resumed by a session over the threshold** (joshuafolkken/kit#2760).
+// The cut outside a lane leaves the session that took it open, so a person retyping `fullrun #N` there
+// would be answered `resume-impl`, keep implementing over the threshold, and be cut again on the next
+// edit — a loop that sheds no context. The record is left intact for a fresh session.
+function report_over(): number {
+	console.error(
+		'This session is over the shared context-cut threshold (`pnpm josh cost --cut` answers `over`), so the implementation cut was not resumed here and its record is kept. End this conversation and type the invocation again in a fresh session.',
+	)
+
+	return report(OVER_VERDICT, FAILURE_EXIT_CODE)
+}
+
+const run_cut_report = {
+	BAD_HANDOFF_VERDICT,
+	BUSY_VERDICT,
+	CUT_VERDICT,
+	ENDED_VERDICT,
+	FAILED_VERDICT,
+	FAILURE_EXIT_CODE,
+	FRESH_VERDICT,
+	HANDED_OFF_VERDICT,
+	HANDOFF_MISSING_NOTE,
+	HANDOFF_OVERFLOW_NOTE,
+	INCOMPLETE_VERDICT,
+	NOT_A_LANE_VERDICT,
+	OVER_VERDICT,
+	RESUME_IMPL_VERDICT,
+	RESUME_VERDICT,
+	STALE_VERDICT,
+	SUCCESS_EXIT_CODE,
+	UNDER_THRESHOLD_VERDICT,
+	UNKNOWN_VERDICT,
+	UNREADABLE_VERDICT,
+	UNREADY_VERDICT,
+	refuse_unready,
+	report,
+	report_bad_handoff,
+	report_busy,
+	report_handed_off,
+	report_incomplete,
+	report_over,
+	report_stale,
+	report_under_threshold,
+	report_unknown,
+	report_unreadable,
+}
+
+export { run_cut_report }

package/scripts/run/run-cut.ts

@@ -9,7 +9,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
 import { z } from 'zod'
 import { run_cut_handoff, type Handoff } from './run-cut-handoff'
-import { run_hold } from './run-hold'
+import { run_hold, type RunHold } from './run-hold'
 
 // joshuafolkken/kit#1839: a lane child is a detached `fullrun #<N>` process, and the thinking it
 // accumulates while implementing rides on every later API call in the same session — measured at 176K
@@ -118,6 +118,8 @@ interface CutState {
 	branch: string
 	is_dirty: boolean
 	is_held: boolean
+	// The issue a `fullrun` hold names, absent when the tree is not held by one (joshuafolkken/kit#2760).
+	held_issue?: string | undefined
 }
 
 // The fields a cut is written from, bundled so `begin_cut` stays within the parameter limit. `phase`
@@ -432,22 +434,34 @@ function end_cut(target: string): void {
 	stamp_file.remove_stamp(target)
 }
 
-// Whether a run hold still stands over this tree — present as `held` or as an aged-out `stale`, but
+// The run hold still standing over this tree — present as `held` or as an aged-out `stale`, but
 // present. A tree with no hold at all is not the one a cut was taken in, so the resume refuses it.
-function tree_is_held(directory: string | undefined): boolean {
-	if (directory === undefined) return false
+function hold_of(directory: string | undefined): RunHold | undefined {
+	if (directory === undefined) return undefined
 
 	const read = run_hold.read_hold(run_hold.hold_path(directory))
 
-	return read.kind === 'held' || read.kind === 'stale'
+	return read.kind === 'held' || read.kind === 'stale' ? read.hold : undefined
+}
+
+// The issue a `fullrun` holds this tree for — what tells a `fullrun` held in its own checkout apart from
+// a person's tree (joshuafolkken/kit#2760). A `halfrun` or an in-session `backlogrun` child holds it
+// too, but its cut would be resumed as `fullrun #N`, so only a hold `run:entry` marked names an issue.
+function fullrun_issue(hold: RunHold | undefined): string | undefined {
+	return hold?.is_fullrun === true ? hold.issue : undefined
+}
+
+// The same read taken synchronously, for the `PreToolUse` implementation-cut guard.
+function held_issue_sync(): string | undefined {
+	return fullrun_issue(hold_of(worktree_git_directory_sync()))
 }
 
 async function current_state(): Promise<CutState> {
 	const branch = await git_command.branch()
 	const is_dirty = await run_hold.is_tree_dirty()
-	const directory = await worktree_directory()
+	const hold = hold_of(await worktree_directory())
 
-	return { branch, is_dirty, is_held: tree_is_held(directory) }
+	return { branch, is_dirty, is_held: hold !== undefined, held_issue: fullrun_issue(hold) }
 }
 
 function describe_cut(cut: RunCut): string {
@@ -508,8 +522,10 @@ const run_cut = {
 	describe_cut,
 	end_cut,
 	fresh_cut,
+	fullrun_issue,
 	handed_off_message,
 	has_required_handoff,
+	held_issue_sync,
 	incomplete_message,
 	invocation_for,
 	is_expired,

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

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { run_cut_report } from './run-cut-report'
 import { run_entry, type EntryParts } from './run-entry'
 import { run_hold_cli } from './run-hold-cli'
 import { run_next } from './run-next'
@@ -50,9 +51,13 @@ function first_line(out: string): string {
 }
 
 // `run:hold <N>` prints one token — `hold`, `busy` or `unknown` — and forwards its explanation to
-// stderr, so the composite branches on the token and the reader still sees why.
+// stderr, so the composite branches on the token and the reader still sees why. `--fullrun` marks the
+// hold as this entry's, since `run:entry` is `fullrun #N`'s alone (joshuafolkken/kit#2760).
 async function claim_hold(issue_number: string): Promise<string> {
-	const held = await josh_command.josh_run(['run:hold', issue_number], should_forward_stderr)
+	const held = await josh_command.josh_run(
+		['run:hold', issue_number, '--fullrun'],
+		should_forward_stderr,
+	)
 
 	return first_line(held.out)
 }
@@ -96,7 +101,36 @@ function stop_report(issue_number: string, hold: string, cost: string, report: s
 	return emit({ issue_number, hold, cost, verdict: run_entry.NO_VERDICT, report })
 }
 
+interface Resume {
+	token: string
+	code: number
+}
+
+// **A resume is asked before the hold is claimed** (joshuafolkken/kit#2760). An implementation cut
+// outside a lane keeps its hold, so the fresh session's `fullrun #N` would be refused `busy` by its own
+// run's hold before it ever reached `run:cut --resume` — the hand-off the cut promised could not land.
+async function ask_resume(issue_number: string): Promise<Resume> {
+	const asked = await josh_command.josh_run(
+		['run:cut', '--resume', issue_number],
+		should_forward_stderr,
+	)
+
+	return { token: first_line(asked.out), code: asked.code }
+}
+
+// Anything but `fresh` is `run:cut --resume`'s answer to act on (`pre-gate-cut.md`), not a new run: the
+// token and its exit code are passed through, and nothing is claimed or read.
+function resume_report(issue_number: string, resume: Resume): number {
+	console.info(`entry #${issue_number} — resume: ${resume.token}`)
+
+	return resume.code
+}
+
 async function open_run(issue_number: string): Promise<number> {
+	const resume = await ask_resume(issue_number)
+
+	if (resume.token !== run_cut_report.FRESH_VERDICT) return resume_report(issue_number, resume)
+
 	const hold = await claim_hold(issue_number)
 
 	if (hold !== run_hold_cli.HOLD_VERDICT) {

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

@@ -43,8 +43,14 @@ 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'
+// The most a claim reads: the issue number and the `--fullrun` 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]] | josh run:release [<issue-number> | --force]'
 
 const HOLD_VERDICT = 'hold'
 const BUSY_VERDICT = 'busy'
@@ -57,10 +63,14 @@ const HELD_VERDICT = 'held'
 
 const FORCE_RELEASE_KIND = 'force-release'
 
+interface ClaimRequest {
+	kind: 'claim'
+	issue: string
+	is_fullrun?: boolean
+}
+
 type HoldRequest =
-	| { kind: 'release'; claimant: string }
-	| { kind: typeof FORCE_RELEASE_KIND }
-	| { kind: 'claim'; issue: string }
+	ClaimRequest | { kind: 'release'; claimant: string } | { kind: typeof FORCE_RELEASE_KIND }
 
 const FORCE_RELEASE_REQUEST: HoldRequest = { kind: FORCE_RELEASE_KIND }
 
@@ -68,14 +78,21 @@ function release_request(claimant: string): HoldRequest {
 	return { kind: 'release', claimant }
 }
 
+// The flag after a numbered claim: absent, or `--fullrun`. Anything else is a usage error.
+function numbered_claim(issue: string, flag: string | undefined): HoldRequest | undefined {
+	if (flag === undefined) return { kind: 'claim', 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 +152,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 +164,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 +195,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 +206,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()
 
@@ -262,7 +283,7 @@ async function read_worktree(): Promise<string | undefined> {
 }
 
 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 === FORCE_RELEASE_KIND) return force_release(target)
 

package/scripts/run/run-hold.ts

@@ -43,6 +43,11 @@ 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
 }
 
 type HoldRead =
@@ -81,6 +86,7 @@ const run_hold_schema = z.object({
 	issue: z.string(),
 	taken_at: z.string(),
 	pid: z.number(),
+	is_fullrun: z.boolean().optional(),
 })
 
 // `undefined` for anything that is not a well-formed record, so the caller decides what a broken one
@@ -125,8 +131,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 +147,13 @@ 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))
 }
 
 // **A tree with uncommitted work in it is never handed over, however old its record is.** No age can

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,