@joshuafolkken/kit 1.1035.0 → 1.1094.0

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

@@ -9,6 +9,9 @@ import { run_hold_cli } from './run-hold-cli'
 import { run_next } from './run-next'
 import { run_prep } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'
+import { run_prrun_resume } from './run-prrun-resume'
+import { run_stage, type StageCommand, type StageDecision } from './run-stage'
+import { run_stage_read, type StageRead } from './run-stage-read'
 import { run_step } from './run-step'
 
 // `josh run:entry <N>` — one call for the fixed entry sequence a lane opens on (joshuafolkken/kit#2372).
@@ -27,7 +30,10 @@ const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
-const USAGE = 'Usage: josh run:entry <issue-number>'
+const USAGE = 'Usage: josh run:entry <issue-number> [--to kickoff|halfrun|prrun|fullrun]'
+const TO_FLAG = '--to'
+// The flag and its command.
+const TO_ARGUMENT_COUNT = 2
 const should_forward_stderr = true
 const NEWLINE = '\n'
 
@@ -48,16 +54,42 @@ function parse_number(argv: ReadonlyArray<string>): string | undefined {
 	return first
 }
 
+interface EntryRequest {
+	issue_number: string
+	command: StageCommand
+}
+
+// `--to <command>` names how far the run goes (joshuafolkken/kit#3042); absent, it is `fullrun`.
+// Anything else is refused.
+function parse_command(rest: ReadonlyArray<string>): StageCommand | undefined {
+	if (rest.length === 0) return run_stage.DEFAULT_COMMAND
+
+	const [flag, value] = rest
+
+	if (flag !== TO_FLAG || rest.length !== TO_ARGUMENT_COUNT) return undefined
+
+	return run_stage.to_command(value)
+}
+
+function parse_request(argv: ReadonlyArray<string>): EntryRequest | undefined {
+	const issue_number = parse_number(argv.slice(0, 1))
+	const command = parse_command(argv.slice(1))
+
+	return issue_number === undefined || command === undefined ? undefined : { issue_number, command }
+}
+
 function first_line(out: string): string {
 	return out.split(NEWLINE)[0] ?? ''
 }
 
 // `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. `--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> {
+// hold as a run whose implementation cut resumes as `fullrun #N` (joshuafolkken/kit#2760) — a
+// `fullrun`'s, and a `prrun`'s, which runs `fullrun`'s steps; a `halfrun`'s hold is never marked.
+async function claim_hold(issue_number: string, command: StageCommand): Promise<string> {
+	const mark = command === run_stage.HALFRUN ? [] : ['--fullrun']
 	const held = await josh_command.josh_run(
-		['run:hold', issue_number, '--fullrun'],
+		['run:hold', issue_number, ...mark],
 		should_forward_stderr,
 	)
 
@@ -131,31 +163,51 @@ function resume_report(issue_number: string, resume: Resume): number {
 // **A `halfrun` stopped before its commit is resumed, not claimed** (joshuafolkken/kit#2796): its hold
 // is kept over the verified diff, so the claim below would answer `busy` against it. The budget is asked
 // first, as for any run; then the hold is adopted and the run goes to the gate, skipping everything up
-// to and including implementation.
-async function resume_halfrun(issue_number: string): Promise<number> {
+// to and including implementation. **A `prrun` stopped before its merge is resumed the same way**
+// (joshuafolkken/kit#3023), under the token that says what is left of it.
+async function resume_stopped(
+	issue_number: string,
+	token: string,
+	stopped_run: { adopt: (issue: string) => Promise<boolean> },
+): Promise<number> {
 	const cost = await check_cost()
 
-	if (cost === run_entry.COST_OVER) {
-		return stop_report(issue_number, HALFRUN_RESUME_TOKEN, cost, COST_STOP_NOTE)
-	}
+	if (cost === run_entry.COST_OVER) return stop_report(issue_number, token, cost, COST_STOP_NOTE)
 
-	if (!(await run_halfrun_resume.adopt(issue_number))) {
+	if (!(await stopped_run.adopt(issue_number))) {
 		return stop_report(issue_number, run_hold_cli.BUSY_VERDICT, cost, HOLD_STOP_NOTE)
 	}
 
-	console.info(`entry #${issue_number} — resume: ${HALFRUN_RESUME_TOKEN}`)
+	console.info(`entry #${issue_number} — resume: ${token}`)
 
 	return SUCCESS_EXIT_CODE
 }
 
-async function open_run(issue_number: string): Promise<number> {
-	const resume = await ask_resume(issue_number)
+// The stopped run a decision picks up: a `halfrun` stop resumes at the gate, a `prrun` stop at
+// `followup` under its own token. `undefined` for any other start, so the ordinary claim decides.
+async function resume_any(
+	issue_number: string,
+	decision: StageDecision,
+	stage: StageRead,
+): Promise<number | undefined> {
+	if (decision.state === run_stage.HALFRUN_STOPPED) {
+		return await resume_stopped(issue_number, HALFRUN_RESUME_TOKEN, run_halfrun_resume)
+	}
 
-	if (resume.token !== run_cut_report.FRESH_VERDICT) return resume_report(issue_number, resume)
+	return stage.prrun_token === undefined
+		? undefined
+		: await resume_stopped(issue_number, stage.prrun_token, run_prrun_resume)
+}
 
-	if (await run_halfrun_resume.is_pending(issue_number)) return await resume_halfrun(issue_number)
+// **A command whose stopping point the issue has already reached redoes nothing** (joshuafolkken/kit#3042)
+// — the stage line is the whole report. A merged issue is the exception: the ordinary entry already
+// answers it (`already-done`, or `keep-work` over a lane's uncommitted work), so it is left to that.
+function is_settled(decision: StageDecision): boolean {
+	return decision.is_reached && decision.state !== run_stage.MERGED
+}
 
-	const hold = await claim_hold(issue_number)
+async function claim_run({ issue_number, command }: EntryRequest): Promise<number> {
+	const hold = await claim_hold(issue_number, command)
 
 	if (hold !== run_hold_cli.HOLD_VERDICT) {
 		return stop_report(issue_number, hold, run_entry.COST_SKIPPED, HOLD_STOP_NOTE)
@@ -170,16 +222,45 @@ async function open_run(issue_number: string): Promise<number> {
 	return emit({ issue_number, hold, cost, verdict: reads.verdict, report: reads.report })
 }
 
+// A carried cut is asked first, before anything is read (`run:cut --resume`); `kickoff` claims and cuts
+// nothing, so it never asks. `undefined` when no cut is waiting.
+async function resume_cut(request: EntryRequest): Promise<number | undefined> {
+	if (request.command === run_stage.KICKOFF) return undefined
+
+	const resume = await ask_resume(request.issue_number)
+
+	return resume.token === run_cut_report.FRESH_VERDICT
+		? undefined
+		: resume_report(request.issue_number, resume)
+}
+
+// `kickoff` stops at the stage line whatever it says — it plans, and claims nothing.
+async function open_run(request: EntryRequest): Promise<number> {
+	const { issue_number, command } = request
+	const cut = await resume_cut(request)
+
+	if (cut !== undefined) return cut
+
+	const stage = await run_stage_read.read_stage(issue_number)
+	const decision = run_stage.decide(stage.state, command)
+
+	console.info(run_stage.format_decision(issue_number, decision))
+
+	if (command === run_stage.KICKOFF || is_settled(decision)) return SUCCESS_EXIT_CODE
+
+	return (await resume_any(issue_number, decision, stage)) ?? (await claim_run(request))
+}
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	const issue_number = parse_number(argv)
+	const request = parse_request(argv)
 
-	if (issue_number === undefined) {
+	if (request === undefined) {
 		console.error(USAGE)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	return await open_run(issue_number)
+	return await open_run(request)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {
@@ -188,12 +269,8 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 
 const run_entry_cli = {
 	HALFRUN_RESUME_TOKEN,
-	SUCCESS_EXIT_CODE,
-	USAGE,
-	check_cost,
-	claim_hold,
-	main,
 	parse_number,
+	parse_request,
 	run,
 }
 

package/scripts/run/run-entry.ts

@@ -84,7 +84,6 @@ const run_entry = {
 	COST_SKIPPED,
 	COST_UNDER,
 	NO_VERDICT,
-	SUMMARY_PREFIX,
 	exit_code,
 	format_report,
 	can_proceed,

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

@@ -193,8 +193,6 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const run_event_cli = {
-	USAGE,
-	main,
 	run,
 	watch_start,
 }

package/scripts/run/run-event-follow.ts

@@ -52,6 +52,7 @@ async function follow(
 	let read = ports.read(position)
 
 	while (read.events.length === 0 && ports.now() < deadline) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await ports.sleep(options.tick_ms)
 		read = ports.read(position)
 	}

package/scripts/run/run-event-render.ts

@@ -69,7 +69,7 @@ function render(event: RunEvent, lang: string): string {
 	return [clock_of(event.at), label_of(event.kind, lang), event.text].join(FIELD_SEPARATOR)
 }
 
-const run_event_render = { KIND_LABELS, clock_of, label_of, render }
+const run_event_render = { clock_of, label_of, render }
 
 export type { KindLabel }
 export { run_event_render }

package/scripts/run/run-event-scope.ts

@@ -91,6 +91,22 @@ const SHIP_POSITION_KINDS: ReadonlySet<string> = new Set([
 	run_event_stream.EVENT_KIND.SHIP_STOP,
 ])
 
+const KIND = run_event_stream.EVENT_KIND
+
+// The parent's record of the batch around a child — its dispatch, park and split, the retrospective
+// whose summary may name an issue it filed, and the strand whose text carries the whole invocation
+// (`backlogrun #<N1> #<N2> …`). Each can name the child, yet none is a position the child itself is at,
+// so a lane child never reads one as its own.
+const BATCH_RECORD_KINDS: ReadonlySet<string> = new Set([
+	KIND.CHILD_LAUNCH,
+	KIND.PARK,
+	KIND.SPLIT,
+	KIND.RETROSPECTIVE,
+	KIND.STRANDED,
+])
+
+const ISSUE_REFERENCE = /#(\d+)/u
+
 function is_foreign_ship_event(event: RunEvent, issue: string): boolean {
 	return SHIP_POSITION_KINDS.has(event.kind) && !event.text.startsWith(`#${issue} `)
 }
@@ -99,16 +115,49 @@ function is_own_ship_event(event: RunEvent, issue: string): boolean {
 	return SHIP_POSITION_KINDS.has(event.kind) && !is_foreign_ship_event(event, issue)
 }
 
+// **A lane child's position is read only from events that name its own issue** (joshuafolkken/kit#3039).
+// The parent and every lane append to one stream under one carry scope, so anything else on it is another
+// run's: another lane's merge told a planned child to stop, the parent's stall (which names no issue)
+// pointed it at `backlog:next`, and another lane's cut at `run:cut --resume`. The child's own merge and
+// outage stay, so the parent-only stop in `run-step.ts` still holds; the parent keeps reading everything.
+function names_issue(event: RunEvent, issue: string): boolean {
+	return ISSUE_REFERENCE.exec(event.text)?.[1] === issue
+}
+
+function is_lane_position(event: RunEvent, issue: string): boolean {
+	return !BATCH_RECORD_KINDS.has(event.kind) && names_issue(event, issue)
+}
+
+// A lane child's attempt begins at its own newest launch. A child re-dispatched after an outage — or
+// relaunched after a cut, whose resume `run:cut --resume` answers at the entry — shares the scope with
+// its previous attempt, and that attempt's outage would otherwise stop the new one at its entry `run:step`.
+function since_own_launch(events: ReadonlyArray<RunEvent>, issue: string): ReadonlyArray<RunEvent> {
+	const launch = events.findLastIndex(
+		(event) => event.kind === KIND.CHILD_LAUNCH && names_issue(event, issue),
+	)
+
+	return events.slice(launch + 1)
+}
+
+function is_foreign_event(event: RunEvent, issue: string, is_lane_child: boolean): boolean {
+	if (is_lane_child) return !is_lane_position(event, issue)
+
+	return is_foreign_ship_event(event, issue)
+}
+
 // The newest position for one issue's run: the scoped last event with other issues' ship positions left
-// out, and — where no scope applies, as in an interactive `fullrun` with no carry record — the issue's own
-// newest ship position, which its issue number already scopes. A determined scope with nothing in it yet
-// reads nothing: an earlier invocation's stop for the same issue is not this invocation's position.
+// out — and, for a lane child, every event not naming its issue — and, where no scope applies, as in
+// an interactive `fullrun` with no carry record, the issue's own newest ship position, which its issue
+// number already scopes. A determined scope with nothing in it yet reads nothing: an earlier invocation's
+// stop for the same issue is not this invocation's position.
 function last_issue_event(
 	events: ReadonlyArray<RunEvent>,
 	scope: EventScope,
 	issue: string,
+	is_lane_child: boolean,
 ): RunEvent | undefined {
-	const own = events.filter((event) => !is_foreign_ship_event(event, issue))
+	const attempt = is_lane_child ? since_own_launch(events, issue) : events
+	const own = attempt.filter((event) => !is_foreign_event(event, issue, is_lane_child))
 
 	if (scope.kind === SINCE_SCOPE) return last_scoped_event(own, scope)
 

package/scripts/run/run-event-stream.ts

@@ -238,13 +238,10 @@ const run_event_stream = {
 	EVENT_CAP,
 	EVENT_KIND,
 	EVENT_KINDS,
-	EVENT_PREFIX,
-	EVENT_SUFFIX,
 	TRACE_KINDS,
 	append,
 	format_event,
 	has_since,
-	is_event_kind,
 	read_events,
 	read_from,
 	read_last,

package/scripts/run/run-event-watch.ts

@@ -22,6 +22,7 @@ async function watch(ports: WatchPorts, position: number): Promise<number> {
 	let next = position
 
 	while (ports.should_continue()) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		const read = await ports.pass(next)
 
 		for (const event of read.events) ports.write(ports.render(event))

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

@@ -1,4 +1,4 @@
-import { run_hold, type HoldRead, type RunHold } from './run-hold'
+import { run_hold, type HoldRead, type RunHold, type StopMarkFields } 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
@@ -38,7 +38,13 @@ function is_own_record(read: HoldRead, issue: string): boolean {
 	return hold === undefined || hold.issue === issue || hold.issue === run_hold.UNNUMBERED_ISSUE
 }
 
-function mark_stop_at(target: string, issue: string): StopMark {
+// `mark` is the `halfrun` stop's by default; a `prrun` stop passes its own (joshuafolkken/kit#3023), so
+// the own-record check is one check whichever run is stopping.
+function mark_stop_at(
+	target: string,
+	issue: string,
+	mark: StopMarkFields = run_hold.HALFRUN_STOP_FIELDS,
+): StopMark {
 	const read = run_hold.read_hold(target)
 
 	if (read.kind === 'unreadable') return UNREADABLE
@@ -47,7 +53,14 @@ function mark_stop_at(target: string, issue: string): StopMark {
 
 	run_hold.release_hold(target)
 
-	return run_hold.create_halfrun_stop_hold(target, issue) ? MARKED : FOREIGN
+	return run_hold.create_stop_hold(target, issue, mark) ? MARKED : FOREIGN
+}
+
+// The stopped run's record is replaced by this `fullrun`'s, shared with the `prrun` resume.
+function take_over(target: string, issue: string): boolean {
+	run_hold.release_hold(target)
+
+	return run_hold.create_hold(target, issue, new Date(), true)
 }
 
 // `false` leaves the record untouched, so the ordinary claim that follows decides the tree exactly as
@@ -55,9 +68,7 @@ function mark_stop_at(target: string, issue: string): StopMark {
 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)
+	return take_over(target, issue)
 }
 
 // **An unreadable git directory is no resume**, never a crash: `run:entry` must still print its one
@@ -95,9 +106,11 @@ const run_halfrun_resume = {
 	UNREADABLE,
 	adopt,
 	adopt_at,
-	is_halfrun_stop,
+	hold_of,
+	hold_target,
 	is_pending,
 	mark_stop_at,
+	take_over,
 }
 
 export type { StopMark }

package/scripts/run/run-headless.ts

@@ -1,7 +1,7 @@
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_reap } from '#scripts/lane/lane-reap'
+import { lane_registry } from '#scripts/lane/lane-registry'
 import { run_carry, type CarryRead, type RunCarry } from './run-carry'
-import { run_watcher_guard } from './run-watcher-guard'
 
 // The headless `backlogrun` parent (joshuafolkken/kit#2437). `run:wake` starts a cut's successor as
 // `claude -p`, and there a turn that ends is the process that ends: its background `lane:await` and
@@ -51,7 +51,7 @@ async function read_carry_here(): Promise<CarryRead | undefined> {
 async function must_keep_waiting(source: EnvironmentSource = process.env): Promise<boolean> {
 	const is_candidate = is_headless(source) && lane_child_marker.marked_issue(source) === undefined
 
-	if (!is_candidate || !(await run_watcher_guard.has_lanes_in_flight())) return false
+	if (!is_candidate || !(await lane_registry.has_lanes_in_flight())) return false
 
 	return is_driving(await read_carry_here())
 }
@@ -73,10 +73,27 @@ function is_owned_here(carry: RunCarry, ancestry: () => ReadonlySet<number>): bo
 	return carry.owner_pid !== undefined && ancestry().has(carry.owner_pid)
 }
 
-function is_driven_here(read: CarryRead | undefined, ancestry: () => ReadonlySet<number>): boolean {
-	if (read?.kind !== 'carried' || !is_driving(read)) return false
+function driven_here(
+	read: CarryRead | undefined,
+	ancestry: () => ReadonlySet<number>,
+): RunCarry | undefined {
+	if (read?.kind !== 'carried' || !is_driving(read)) return undefined
 
-	return is_owned_here(read.carry, ancestry)
+	return is_owned_here(read.carry, ancestry) ? read.carry : undefined
+}
+
+/**
+ * The live, un-handed-off carry record this session drives as the `backlogrun` parent, or `undefined`
+ * for a lane child or any session that does not own one. Returned rather than tested so a caller that
+ * also needs the record's counters (the parent cut's cap, joshuafolkken/kit#2947) reads it once.
+ */
+async function driving_carry(
+	source: EnvironmentSource = process.env,
+	ancestry: () => ReadonlySet<number> = lane_reap.own_ancestry,
+): Promise<RunCarry | undefined> {
+	if (lane_child_marker.marked_issue(source) !== undefined) return undefined
+
+	return driven_here(await read_carry_here(), ancestry)
 }
 
 /**
@@ -88,14 +105,13 @@ async function is_backlog_parent(
 	source: EnvironmentSource = process.env,
 	ancestry: () => ReadonlySet<number> = lane_reap.own_ancestry,
 ): Promise<boolean> {
-	if (lane_child_marker.marked_issue(source) !== undefined) return false
-
-	return is_driven_here(await read_carry_here(), ancestry)
+	return (await driving_carry(source, ancestry)) !== undefined
 }
 
 const run_headless = {
 	HEADLESS_ENV_KEY,
 	current_carry,
+	driving_carry,
 	environment,
 	is_backlog_parent,
 	is_headless,

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

@@ -3,6 +3,7 @@ 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_prrun_resume } from './run-prrun-resume'
 import { run_tidy_cli } from './run-tidy-cli'
 
 // `josh run:hold [<N>]` and `josh run:release [<N> | --force]` — the working-tree guard the typed
@@ -48,11 +49,13 @@ const FORCE_FLAG = '--force'
 // implementation cut outside a lane resumes as `fullrun #N` (joshuafolkken/kit#2760).
 const FULLRUN_FLAG = '--fullrun'
 const HALFRUN_STOP_FLAG = '--halfrun-stop'
+// A `prrun`'s stop before merge (joshuafolkken/kit#3023): its record keeps the commit it stopped on.
+const PRRUN_STOP_FLAG = '--prrun-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> [--fullrun | --halfrun-stop]] | josh run:release [<issue-number> | --force]'
+	'Usage: josh run:hold [<issue-number> [--fullrun | --halfrun-stop | --prrun-stop]] | josh run:release [<issue-number> | --force]'
 
 const HOLD_VERDICT = 'hold'
 const BUSY_VERDICT = 'busy'
@@ -65,6 +68,7 @@ const HELD_VERDICT = 'held'
 
 const FORCE_RELEASE_KIND = 'force-release'
 const HALFRUN_STOP_KIND = 'halfrun-stop'
+const PRRUN_STOP_KIND = 'prrun-stop'
 
 interface ClaimRequest {
 	kind: 'claim'
@@ -72,11 +76,20 @@ interface ClaimRequest {
 	is_fullrun?: boolean
 }
 
+interface StopRequest {
+	kind: typeof HALFRUN_STOP_KIND | typeof PRRUN_STOP_KIND
+	issue: string
+}
+
 type HoldRequest =
 	| ClaimRequest
+	| StopRequest
 	| { kind: 'release'; claimant: string }
 	| { kind: typeof FORCE_RELEASE_KIND }
-	| { kind: typeof HALFRUN_STOP_KIND; issue: string }
+
+function is_stop_request(request: HoldRequest): request is StopRequest {
+	return request.kind === HALFRUN_STOP_KIND || request.kind === PRRUN_STOP_KIND
+}
 
 const FORCE_RELEASE_REQUEST: HoldRequest = { kind: FORCE_RELEASE_KIND }
 
@@ -84,12 +97,20 @@ 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.
+const STOP_KIND_BY_FLAG: ReadonlyMap<string, typeof HALFRUN_STOP_KIND | typeof PRRUN_STOP_KIND> =
+	new Map([
+		[HALFRUN_STOP_FLAG, HALFRUN_STOP_KIND],
+		[PRRUN_STOP_FLAG, PRRUN_STOP_KIND],
+	])
+
+// The flag after a numbered claim: absent, `--fullrun`, `--halfrun-stop` or `--prrun-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 }
+	const stop_kind = STOP_KIND_BY_FLAG.get(flag)
+
+	if (stop_kind !== undefined) return { kind: stop_kind, issue }
 
 	return flag === FULLRUN_FLAG ? { kind: 'claim', issue, is_fullrun: true } : undefined
 }
@@ -293,8 +314,12 @@ 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)
+// A `prrun` stop marks its record the same way, with the commit it stopped on (joshuafolkken/kit#3023).
+async function mark_stop(target: string, request: StopRequest): Promise<number> {
+	const mark =
+		request.kind === PRRUN_STOP_KIND
+			? await run_prrun_resume.mark_stop_at(target, request.issue)
+			: run_halfrun_resume.mark_stop_at(target, request.issue)
 
 	if (mark === run_halfrun_resume.MARKED) return report_hold()
 
@@ -306,7 +331,7 @@ function mark_halfrun_stop(target: string, issue: string): number {
 async function dispatch(request: HoldRequest, target: string, is_linked: boolean): Promise<number> {
 	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 (is_stop_request(request)) return await mark_stop(target, request)
 
 	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
 
@@ -351,8 +376,6 @@ const run_hold_cli = {
 	RELEASED_VERDICT,
 	UNKNOWN_VERDICT,
 	USAGE,
-	blocking_message,
-	main,
 	parse_request,
 	run,
 }

package/scripts/run/run-hold.ts

@@ -52,6 +52,10 @@ interface RunHold {
 	// 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
+	// Set only at a `prrun`'s stop before merge (`run:hold <N> --prrun-stop`, joshuafolkken/kit#3023): the
+	// commit the green pull request stood on, so `fullrun #N` can tell an untouched branch — merge it —
+	// from one that moved since and has to pass the gate and the review again.
+	prrun_stop_head?: string | undefined
 }
 
 type HoldRead =
@@ -92,6 +96,7 @@ const run_hold_schema = z.object({
 	pid: z.number(),
 	is_fullrun: z.boolean().optional(),
 	is_halfrun_stop: z.boolean().optional(),
+	prrun_stop_head: z.string().optional(),
 })
 
 // `undefined` for anything that is not a well-formed record, so the caller decides what a broken one
@@ -161,9 +166,24 @@ function create_hold(
 	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.
+// What a stopped run's record carries on top of the claim: the `halfrun` stop's flag, or the commit a
+// `prrun` stop stood on (joshuafolkken/kit#3023).
+type StopMarkFields = Pick<RunHold, 'is_halfrun_stop' | 'prrun_stop_head'>
+
+const HALFRUN_STOP_FIELDS: StopMarkFields = { is_halfrun_stop: true }
+
+// The claim a stop leaves behind: the same exclusive create, carrying the stop mark.
+function create_stop_hold(
+	target: string,
+	issue: string,
+	mark: StopMarkFields,
+	now: Date = new Date(),
+): boolean {
+	return stamp_file.create_stamp(target, { ...build_hold(issue, now), ...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 })
+	return create_stop_hold(target, issue, HALFRUN_STOP_FIELDS, now)
 }
 
 // **A tree with uncommitted work in it is never handed over, however old its record is.** No age can
@@ -260,8 +280,9 @@ const run_hold = {
 	UNNUMBERED_ISSUE,
 	classify,
 	create_halfrun_stop_hold,
+	create_stop_hold,
+	HALFRUN_STOP_FIELDS,
 	create_hold,
-	describe_holder,
 	foreign_release_message,
 	forced_release_message,
 	held_message,
@@ -270,7 +291,6 @@ const run_hold = {
 	is_own_hold,
 	is_tree_dirty,
 	own_release_command,
-	parse_hold,
 	race_message,
 	read_hold,
 	release_hold,
@@ -282,5 +302,5 @@ const run_hold = {
 	write_hold,
 }
 
-export type { HoldRead, RunHold }
+export type { HoldRead, RunHold, StopMarkFields }
 export { run_hold }

package/scripts/run/run-issue-number.ts

@@ -14,6 +14,6 @@ function require_issue_number(issue: string): void {
 	if (!ISSUE_NUMBER_PATTERN.test(issue)) throw new Error(`${BAD_ISSUE_MESSAGE}${issue}`)
 }
 
-const run_issue_number = { BAD_ISSUE_MESSAGE, ISSUE_NUMBER_PATTERN, require_issue_number }
+const run_issue_number = { ISSUE_NUMBER_PATTERN, require_issue_number }
 
 export { run_issue_number }

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

@@ -159,7 +159,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_liveness_cli = { USAGE, main, parse_request, run }
+const run_liveness_cli = { USAGE, parse_request, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))