@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -1,22 +1,19 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
-import { api_outage } from '#scripts/agent/api-outage'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
+import { RUN_STALLED_LABEL } from '#scripts/issue/issue-labels'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
 import { lane_ledger } from '#scripts/lane/lane-ledger'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_carry, type CarryOwner, type RunCarry } from '#scripts/run/carry/run-carry'
-import { run_event_scope } from '#scripts/run/event/run-event-scope'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
-import { run_ending } from '#scripts/run/run-ending'
-import { run_label } from '#scripts/run/run-label'
-import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
-import { run_merge_ship } from './run-merge-ship'
+import { run_stalled, type StallCause } from '#scripts/run/park/run-stalled'
+import { run_merge, type ChildOutcome } from './run-merge'
+import { run_merge_auth } from './run-merge-auth'
+import { run_merge_driver } from './run-merge-driver'
+import { run_merge_signals } from './run-merge-signals'
 import { run_merge_steps, type FailedResult, type MergeContext } from './run-merge-steps'
 import { run_merge_token, type MergeToken } from './run-merge-token'
 
@@ -30,15 +27,12 @@ import { run_merge_token, type MergeToken } from './run-merge-token'
 // (stop — the child's own ending), `stop` (the consecutive-failure guard tripped, or a failed child could not be parked) and `retry` (the
 // child's state could not be read; re-read before deciding).
 
-const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const FIRST = 0
 const MIN_PID = 1
 const { MERGE_TOKEN } = run_merge_token
-const PARK_FAILURE_NOTE = 'The failed child could not be parked with needs-decision; stopping.'
-// The same digit shape `run-carry-args.ts` reads an owner pid under; a count is a bare run of digits.
-const DIGITS = /^\d+$/u
+const PARK_FAILURE_NOTE = `The failed child could not be parked with ${RUN_STALLED_LABEL}; stopping.`
 // A GitHub `owner/repo` slug: an owner and a repository name around a single slash, each starting with
 // an alphanumeric so neither half can begin with `-`. `epic` and `repo` flow into `pnpm josh`
 // subprocess arguments, so a value shaped like an option (`--foo`, or `--evil/x`) would be read as a
@@ -47,9 +41,10 @@ const DIGITS = /^\d+$/u
 // itself forbids (names cannot start with a hyphen) and which the taint analyzer keeps flagging.
 const REPO_PATTERN = /^[A-Za-z0-9][\w.-]*\/[A-Za-z0-9][\w.-]*$/u
 const USAGE =
-	'Usage: josh run:merge <issue> [--over <deprecated>] [--epic <E> --repo <owner/repo>] [--owner <pid>] [--output <path>]'
+	'Usage: josh run:merge <issue> [--over <deprecated>] [--epic <E> --repo <owner/repo>] [--owner <pid>] [--output <path>] [--driver]'
 
 const OPTIONS = {
+	driver: { type: 'boolean' },
 	epic: { type: 'string' },
 	output: { type: 'string' },
 	over: { type: 'string' },
@@ -59,7 +54,9 @@ const OPTIONS = {
 
 interface ParsedArguments {
 	positionals: ReadonlyArray<string>
-	values: Partial<Record<'epic' | 'output' | 'over' | 'owner' | 'repo', string>>
+	values: Partial<Record<'epic' | 'output' | 'over' | 'owner' | 'repo', string>> & {
+		driver?: boolean
+	}
 }
 
 // Absent owner is "no owner declared", which the carry guard reads as not provably foreign; a present
@@ -67,11 +64,10 @@ interface ParsedArguments {
 function to_owner(raw: string | undefined): CarryOwner | undefined {
 	if (raw === undefined) return run_carry.NO_OWNER
 
-	if (!DIGITS.test(raw)) return undefined
-
-	const pid = Number(raw)
+	// The same count shape `run-carry-args.ts` reads an owner pid under.
+	const pid = cli_flags.to_count(raw)
 
-	return pid < MIN_PID ? undefined : run_carry.owner_of(pid)
+	return pid === undefined || pid < MIN_PID ? undefined : run_carry.owner_of(pid)
 }
 
 // The epic form needs a repository (`epic:next --lanes` refuses without one), so an epic named with
@@ -120,7 +116,7 @@ function has_invalid_offer(values: ParsedArguments['values']): boolean {
 function has_invalid_legacy_over(raw: string | undefined): boolean {
 	if (raw === undefined) return false
 
-	return !DIGITS.test(raw) || !Number.isSafeInteger(Number(raw))
+	return cli_flags.to_count(raw) === undefined
 }
 
 function valid_child(parsed: ParsedArguments): string | undefined {
@@ -131,6 +127,11 @@ function valid_child(parsed: ParsedArguments): string | undefined {
 	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(child) ? child : undefined
 }
 
+// `backlog:drive` has no context to cut, so its merge is never handed back `over`.
+function threshold_of(values: ParsedArguments['values']): number | undefined {
+	return values.driver === true ? undefined : CONTEXT_CUT_THRESHOLD
+}
+
 function to_context(parsed: ParsedArguments): MergeContext | undefined {
 	if (has_invalid_offer(parsed.values) || has_invalid_legacy_over(parsed.values.over)) {
 		return undefined
@@ -148,7 +149,7 @@ function to_context(parsed: ParsedArguments): MergeContext | undefined {
 		child,
 		epic: valid_epic(parsed.values.epic),
 		repo: valid_repo(parsed.values.repo),
-		over: CONTEXT_CUT_THRESHOLD,
+		over: threshold_of(parsed.values),
 		owner,
 		output: parsed.values.output,
 	}
@@ -160,8 +161,8 @@ function parse(argv: ReadonlyArray<string>): MergeContext | undefined {
 	return parsed === undefined ? undefined : to_context(parsed)
 }
 
-// One handled return: the stdout token and the exit code. Returned rather than printed, so the
-// in-process caller (`backlog:drive`) reads the same verdict the CLI prints.
+// One handled return: the stdout token and the exit code. Returned rather than printed, so
+// `merge_child` carries the verdict to `run_merge_driver.printed`, which prints it.
 interface ControlVerdict {
 	token: MergeToken
 	code: number
@@ -187,63 +188,13 @@ function emit(token: MergeToken, code: number): ControlVerdict {
 	return { token, code, is_offer: false }
 }
 
+// No threshold is `backlog:drive`, which asks `backlog:offer` itself in the pass that collected the
+// child: `backlog:next` here would only hold back its next launch (joshuafolkken/kit#4406).
 async function offered(ctx: MergeContext): Promise<OfferVerdict> {
-	return { token: await run_merge_steps.ask_next(ctx), code: SUCCESS_EXIT_CODE, is_offer: true }
-}
-
-// Whether the child's session ended through its environment — read only when `--output` named the
-// transcript, off otherwise: its exit record shows it could not reach the API, or the session was
-// killed inside a turn. The path is validated inside `run_ending`, so a missing output is "no".
-function read_is_outage(output: string | undefined): boolean {
-	if (output === undefined) return false
-
-	return api_outage.is_outage(run_ending.read_exit(output)) || run_ending.ended_mid_turn(output)
-}
-
-async function child_outages(child: string): Promise<number> {
-	const events = await run_event_stream_emit.current_events()
-
-	return events.filter(
-		(event) =>
-			event.kind === run_event_stream.EVENT_KIND.OUTAGE &&
-			run_event_scope.issue_named(event) === child,
-	).length
-}
-
-// An outage child is re-dispatched only so many times: one that ends the same way on every dispatch is
-// parked, since merges in other lanes reset the run-wide outage streak and would never stop it.
-async function read_is_retryable(child: string, output: string | undefined): Promise<boolean> {
-	const is_interrupted =
-		read_is_outage(output) || (await run_merge_ship.is_unanswered(child, output))
-
-	if (!is_interrupted) return false
-
-	return (await child_outages(child)) < run_merge.CONSECUTIVE_OUTAGE_LIMIT
-}
-
-type IssueRead = Awaited<ReturnType<typeof issue_state_cli.read_issue>>
-
-// The timeline is read only for an OPEN, unparked child — the one classification a merged closing pull
-// request changes. A CLOSED child was closed by GitHub, so it must carry no `merged_pr` for
-// `do_merged` to close again.
-async function read_merged_pr(child: string, read: IssueRead): Promise<string | undefined> {
-	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'failed') return undefined
+	const token =
+		ctx.over === undefined ? run_merge_driver.DEFERRED_OFFER : await run_merge_steps.ask_next(ctx)
 
-	return await issue_closing_pr.read_closing_pr(child)
-}
-
-async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingSignals> {
-	const [is_cut, merged_pr, is_outage] = await Promise.all([
-		run_merge_steps.has_resumable_cut(ctx.child),
-		read_merged_pr(ctx.child, read),
-		read_is_retryable(ctx.child, ctx.output),
-	])
-
-	return { is_outage, is_cut, merged_pr }
-}
-
-function outcome_of(read: IssueRead, signals: EndingSignals): ChildOutcome {
-	return read.kind === 'state' ? run_merge.classify_child(read.state, signals) : 'unresolved'
+	return { token, code: SUCCESS_EXIT_CODE, is_offer: true }
 }
 
 // A refused count means this session is not the carry record's owner, so the whole operation is
@@ -256,7 +207,8 @@ function report_count_refused(carry: RunCarry | undefined): MergeVerdict {
 
 // A merged child counted and its lane closed, the merge put on the stream and in the ledger. Returns the
 // carry when the ownership check refused it, `undefined` once recorded. `run:carry --end` records the
-// merges a run ended with through it too (`run-merge-collect.ts`).
+// merges a run ended with through it too (`run-merge-collect.ts`). The lane's `ended` record is
+// `lane:close`'s alone: an `incomplete` close leaves the lane open on it (joshuafolkken/kit#4300).
 async function record_merged(ctx: MergeContext): Promise<RunCarry | undefined> {
 	const refused = await run_merge_steps.do_merged(ctx)
 
@@ -285,16 +237,13 @@ async function on_merged(ctx: MergeContext): Promise<MergeVerdict> {
 	return await offered(ctx)
 }
 
-// A child released to wait on its open blockers: settled for this run like a parked one, so it goes on
-// the stream the same way, but nothing was counted — the failure guard is not read, and the next child
-// is offered.
-async function on_waiting(
-	ctx: MergeContext,
-	blockers: ReadonlyArray<string>,
-): Promise<MergeVerdict> {
+// A child released to wait on its open blockers or its start date: settled for this run like a parked
+// one, so it goes on the stream the same way, but nothing was counted — the failure guard is not read,
+// and the next child is offered.
+async function on_waiting(ctx: MergeContext, waits: ReadonlyArray<string>): Promise<MergeVerdict> {
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.PARK,
-		`${issue_cite.plain(ctx.child)} waiting on ${blockers.join(', ')}`,
+		`${issue_cite.plain(ctx.child)} waiting on ${waits.join(', ')}`,
 	)
 
 	return await offered(ctx)
@@ -307,9 +256,11 @@ async function on_parked_failure(ctx: MergeContext, result: FailedResult): Promi
 		return emit(MERGE_TOKEN.STOP, FAILURE_EXIT_CODE)
 	}
 
+	const cause = result.cause ?? run_stalled.SESSION_UNFINISHED.short
+
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.PARK,
-		`${issue_cite.plain(ctx.child)} parked (needs-decision)`,
+		run_stalled.park_event(ctx.child, cause),
 	)
 
 	if (result.carry !== undefined && run_merge.is_guard_tripped(result.carry.failures)) {
@@ -319,12 +270,12 @@ async function on_parked_failure(ctx: MergeContext, result: FailedResult): Promi
 	return await offered(ctx)
 }
 
-async function on_failed(ctx: MergeContext, cause?: string): Promise<MergeVerdict> {
+async function on_failed(ctx: MergeContext, cause?: StallCause): Promise<MergeVerdict> {
 	const result = await run_merge_steps.do_failed(ctx, cause)
 
 	if (result.is_refused) return report_count_refused(result.carry)
 
-	if (result.blockers.length > 0) return await on_waiting(ctx, result.blockers)
+	if (result.waits.length > 0) return await on_waiting(ctx, result.waits)
 
 	return await on_parked_failure(ctx, result)
 }
@@ -349,6 +300,14 @@ async function on_outage(ctx: MergeContext): Promise<MergeVerdict> {
 	return await offered(ctx)
 }
 
+// A child whose session could not authenticate: the run stops with nothing counted or parked
+// (`run-merge-auth.ts`).
+async function on_unauthenticated(ctx: MergeContext): Promise<MergeVerdict> {
+	await run_merge_auth.stop(ctx.child)
+
+	return emit(MERGE_TOKEN.ENVIRONMENT, SUCCESS_EXIT_CODE)
+}
+
 // A child that ended its session with a cut no successor adopted: its successor is relaunched,
 // nothing is counted and nothing is parked, and `resumed` tells the parent to await the same lane
 // again rather than dispatch into it. A successor that could not be started — or a cut the
@@ -360,7 +319,7 @@ 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, run_merge_steps.CUT_RELAUNCH_CAUSE)
+		return await on_failed(ctx, run_stalled.CUT_NOT_RELAUNCHED)
 	}
 
 	await run_event_stream_emit.emit(
@@ -373,10 +332,10 @@ async function on_cut(ctx: MergeContext): Promise<MergeVerdict> {
 
 // A child that parked itself: nothing is counted, but the park is written to the stream as a failed
 // child's is, so a reader restoring the run from its events sees the child settled. Its `in-progress`
-// is dropped as a failed child's is: left on, it would outlive the `needs-decision` a person later
-// lifts, and a `run:solo` child would then hold the whole backlog.
+// is dropped as a failed child's is: left on, it would outlive the park label a person later
+// lifts, and a `run:solo` child would then hold the whole backlog. A lane it left empty is closed.
 async function on_parked(ctx: MergeContext): Promise<MergeVerdict> {
-	await run_label.unmark(ctx.child)
+	await run_merge_steps.release_child(ctx.child)
 	await run_event_stream_emit.emit(
 		run_event_stream.EVENT_KIND.PARK,
 		`${issue_cite.plain(ctx.child)} parked`,
@@ -397,6 +356,13 @@ async function on_skipped(ctx: MergeContext): Promise<MergeVerdict> {
 	return await offered(ctx)
 }
 
+// A child a person withdrew with `lane:withdraw`: the withdrawal already stopped it, closed its lane
+// and put itself on the stream, leaving its issue open for the next run, so nothing is counted or
+// written here and its seat goes to the next child.
+async function on_withdrawn(ctx: MergeContext): Promise<MergeVerdict> {
+	return await offered(ctx)
+}
+
 // The child's own ending: it stopped before its commit for a person to look at, so nothing is counted
 // and no next child is offered.
 async function on_human_review(): Promise<MergeVerdict> {
@@ -418,24 +384,29 @@ const HANDLERS: Readonly<Record<ChildOutcome, (ctx: MergeContext) => Promise<Mer
 	'human-review': on_human_review,
 	merged: on_merged,
 	outage: on_outage,
+	unauthenticated: on_unauthenticated,
 	parked: on_parked,
 	split: on_skipped,
 	unresolved: on_unresolved,
 	shipping: on_shipping,
+	withdrawn: on_withdrawn,
 }
 
-// The whole merge event for one returned child, in-process: read its state, classify it, and run the
-// handler. The CLI prints the token; `backlog:drive` branches on the outcome.
+// The whole merge event for one returned child: read its state, classify it, and run the handler.
+// The CLI prints the token and the outcome; `backlog:drive` runs it as a child process
+// (`run-merge-driver.ts`) and branches on the printed outcome.
 async function merge_child(ctx: MergeContext): Promise<MergeResult> {
 	if (lane_handoff.is_ship_running(ctx.child, process.cwd())) {
 		return { outcome: 'shipping', ...(await on_shipping()) }
 	}
 
 	const read = await issue_state_cli.read_issue(ctx.child, ctx.repo)
-	const signals = await read_signals(ctx, read)
-	const outcome = outcome_of(read, signals)
+	const signals = await run_merge_signals.read_signals(ctx, read)
+	const outcome = run_merge_signals.outcome_of(read, signals)
 
-	return { outcome, ...(await HANDLERS[outcome]({ ...ctx, merged_pr: signals.merged_pr })) }
+	const { merged_pr, is_streak_exempt } = signals
+
+	return { outcome, ...(await HANDLERS[outcome]({ ...ctx, merged_pr, is_streak_exempt })) }
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
@@ -449,24 +420,18 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	const result = await merge_child(ctx)
 
-	console.info(result.token)
+	console.info(run_merge_driver.printed(argv, result))
 
 	return result.code
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const run_merge_cli = {
 	merge_child,
 	parse,
-	read_merged_pr,
+	read_merged_pr: run_merge_signals.read_merged_pr,
 	record_merged,
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { MergeResult }
 export { run_merge_cli }

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

@@ -0,0 +1,74 @@
+import { epic_close } from '#scripts/epic/epic-close'
+import { git_followup_issue_close } from '#scripts/followup/git-followup-issue-close'
+import { session_cite } from '#scripts/issue/session-cite'
+
+const MERGE_CLOSER = 'pnpm josh run:merge'
+const SINGLE_READ = { attempts: 1, interval_ms: 0 }
+
+interface MergedChild {
+	child: string
+	// The merged pull request that closes the child, when GitHub left the child OPEN after the merge.
+	merged_pr?: string | undefined
+}
+
+// A child merged while GitHub left it OPEN is closed here, through the one close `followup` uses.
+// 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. Answers
+// whether the child is closed now.
+async function close_merged_open(merged: MergedChild): Promise<boolean> {
+	if (merged.merged_pr === undefined) return true
+
+	try {
+		await git_followup_issue_close.ensure_issue_closed(
+			{ issue_number: merged.child, pr_url: merged.merged_pr, closer: MERGE_CLOSER },
+			SINGLE_READ,
+		)
+
+		return true
+	} catch {
+		console.error(
+			`${session_cite.issue(merged.child)}: could not be closed — ${git_followup_issue_close.CLOSE_RECOVERY}`,
+		)
+
+		return false
+	}
+}
+
+// `run:merge`'s stdout carries only the next child or a verdict, so the epic auto-close's notes go to
+// stderr for as long as it runs, beside this command's own notes.
+function divert_info_to_stderr(): () => void {
+	const { info } = console
+
+	console.info = console.error
+
+	return function restore(): void {
+		console.info = info
+	}
+}
+
+async function with_notes_on_stderr(step: () => Promise<void>): Promise<void> {
+	const restore = divert_info_to_stderr()
+
+	try {
+		await step()
+	} finally {
+		restore()
+	}
+}
+
+// Every other child `run:merge` counts as merged is already closed, whatever closed it — `followup`
+// or `josh issue:measured` — so its epics are evaluated here, through the one entry every child close
+// takes (`epic-close.ts`, #4560). A child still OPEN after a failed close is not: the auto-close
+// treats the child as closed without reading it. An `already-done` child reads OPEN here and is
+// parked; once a person closes it, the next child close sweeps its epic (`epic-close.ts`, #4564).
+async function close_merged(merged: MergedChild): Promise<void> {
+	if (!(await close_merged_open(merged))) return
+
+	await with_notes_on_stderr(async () => {
+		await epic_close.close_completed_epics({ issue_number: merged.child, is_merged: true })
+	})
+}
+
+const run_merge_close = { close_merged }
+
+export { run_merge_close }

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

@@ -1,19 +1,18 @@
-import { backlog_drive_restore } from '#scripts/backlog/backlog-drive-restore'
+import { backlog_drive_adopt } from '#scripts/backlog/backlog-drive-adopt'
 import { issue_merged } from '#scripts/issue/issue-merged'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 import { session_cite } from '#scripts/issue/session-cite'
 import { lane_handoff } from '#scripts/lane/lane-handoff'
-import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import type { LaneInfo } from '#scripts/lane/lane-registry'
 import { run_carry, type CarryOwner, type RunCarry } from '#scripts/run/carry/run-carry'
-import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_merge } from './run-merge'
 import { run_merge_cli } from './run-merge-cli'
 
 type IssueRead = Awaited<ReturnType<typeof issue_state_cli.read_issue>>
 
-// The merges a run ends with, recorded at `run:carry --end`. `backlog:drive` collects only the lanes
-// it holds in memory, and a restarted driver reseeds them from the open lanes, so a lane that merged
-// while no driver watched it never reached `run:merge`: no `merge` event, no ledger line, no merged
+// The merges a run ends with, recorded at `run:carry --end`. `backlog:drive` collects the lanes it
+// holds or adopts while it runs (`backlog-drive-adopt.ts`), so a lane that merged while no driver
+// watched it never reached `run:merge`: no `merge` event, no ledger line, no merged
 // count. Each lane still open on a child the run launched and never settled is read once more, and
 // **only a merged one is collected** — closed by a merged pull request, or left open behind one —
 // through the same `run:merge` recording a driver would have made.
@@ -79,13 +78,7 @@ function owner_of(carry: RunCarry): CarryOwner {
 }
 
 async function collect_carried(carry: RunCarry): Promise<void> {
-	const in_flight = backlog_drive_restore.active_issues(
-		await run_event_stream_emit.current_events(),
-	)
-	const lanes = await lane_registry.list_lanes()
-	const collectable = lanes.filter((lane) => !lane.is_stranded && in_flight.has(lane.issue))
-
-	await collect_all(collectable, owner_of(carry))
+	await collect_all(await backlog_drive_adopt.active_lanes(), owner_of(carry))
 }
 
 // Asked by `--end` before it closes the record under `directory`, the common git directory; a run with

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

@@ -0,0 +1,71 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import type { MergeResult } from './run-merge-cli'
+import { run_merge_outcome } from './run-merge-outcome'
+import { run_merge_token } from './run-merge-token'
+
+// `run:merge` as `backlog:drive` runs it: a child process per merge, never an import, so a fix merged
+// into `run:merge` after the driver started is the code its next merge runs (joshuafolkken/kit#4102).
+// Imported in process, the driver went on parking children with the code it was started with.
+//
+// `--driver` asks for what the driver alone needs: no hand-off threshold — a supervisor has no context
+// to cut — and the whole `MergeResult` as one JSON line on stdout's last line, since the outcome the
+// driver branches on is not in the token a person reads.
+
+const COMMAND = 'run:merge'
+const DRIVER_FLAG = '--driver'
+const JSON_KEY = 'merge'
+const LINE_BREAK = '\n'
+// The offer token `--driver` answers in place of `backlog:next`'s: the driver never reads an offer's
+// text, only that one was printed, and asks `backlog:offer` itself (joshuafolkken/kit#4406).
+const DEFERRED_OFFER = 'deferred'
+
+const control_schema = z.object({
+	token: z.enum(Object.values(run_merge_token.MERGE_TOKEN)),
+	code: z.number(),
+	is_offer: z.literal(false),
+	outcome: z.enum(run_merge_outcome.CHILD_OUTCOMES),
+})
+const offer_schema = z.object({
+	token: z.string(),
+	code: z.number(),
+	is_offer: z.literal(true),
+	outcome: z.enum(run_merge_outcome.CHILD_OUTCOMES),
+})
+const printed_schema = z.object({
+	[JSON_KEY]: z.discriminatedUnion('is_offer', [control_schema, offer_schema]),
+})
+
+interface DriverMerge {
+	child: string
+	owner: string
+	output: string | undefined
+}
+
+function argv_of(merge: DriverMerge): Array<string> {
+	const output = merge.output === undefined ? [] : ['--output', merge.output]
+
+	return [COMMAND, merge.child, '--owner', merge.owner, DRIVER_FLAG, ...output]
+}
+
+function print(result: MergeResult): string {
+	return JSON.stringify({ [JSON_KEY]: result })
+}
+
+// What `run:merge` prints: the whole result under `--driver`, else the token a person reads.
+function printed(argv: ReadonlyArray<string>, result: MergeResult): string {
+	return argv.includes(DRIVER_FLAG) ? print(result) : result.token
+}
+
+// The result on stdout's last line, or `undefined` where the child process printed none — a crash
+// before its verdict, which the driver reads as no token.
+function read(out: string): MergeResult | undefined {
+	const last = out.trimEnd().split(LINE_BREAK).at(-1) ?? ''
+
+	return json_value.parse_with(last, printed_schema)?.[JSON_KEY]
+}
+
+const run_merge_driver = { DEFERRED_OFFER, DRIVER_FLAG, argv_of, print, printed, read }
+
+export type { DriverMerge }
+export { run_merge_driver }

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_merge_cli } from './run-merge-cli'
+
+// The `josh run:merge` entry, kept apart from `run-merge-cli.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await run_merge_cli.run(process.argv.slice(ARGV_OFFSET))
+}

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

@@ -0,0 +1,23 @@
+// The outcomes `run:merge` classifies a returned child as — each one's meaning is `run-merge.ts`'s.
+// Listed as values so `run:merge --driver`'s JSON is read back against the same names
+// (`run-merge-driver.ts`) rather than a second list.
+const CHILD_OUTCOMES = [
+	'merged',
+	'withdrawn',
+	'human-review',
+	'parked',
+	'split',
+	'cut',
+	'outage',
+	'unauthenticated',
+	'failed',
+	'unresolved',
+	'shipping',
+] as const
+
+type ChildOutcome = (typeof CHILD_OUTCOMES)[number]
+
+const run_merge_outcome = { CHILD_OUTCOMES }
+
+export type { ChildOutcome }
+export { run_merge_outcome }

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

@@ -0,0 +1,39 @@
+import { uptime } from 'node:os'
+import { agent_exit_record } from '#scripts/agent/agent-exit-record'
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { run_ending } from '#scripts/run/run-ending'
+
+// Whether a returned child was killed by the host restarting rather than ending on its own
+// (joshuafolkken/kit#4540). A restart clears the temporary directory the child's transcript and the run's
+// event stream live in, so the exit record cannot tell it apart from a failure; the lane's dispatch time,
+// kept in its worktree, can: a child dispatched before the host booted, with no exit record of its own,
+// did not end itself.
+
+const MS_PER_SECOND = 1000
+
+// When the host last booted, in epoch milliseconds.
+function booted_ms(): number {
+	return Date.now() - uptime() * MS_PER_SECOND
+}
+
+// Whether the newest launch ended on its own exit record. The log is appended across launches, and where
+// the temporary root survives a reboot it still holds an earlier launch's record, so only a record that
+// is the log's last line belongs to the launch the restart may have killed.
+function has_exit_record(output: string | undefined): boolean {
+	const transcript = output === undefined ? undefined : run_ending.read_transcript(output)
+
+	return transcript !== undefined && agent_exit_record.ends_on_exit_record(transcript)
+}
+
+async function is_host_restart(child: string, output: string | undefined): Promise<boolean> {
+	if (has_exit_record(output)) return false
+
+	const lane = await lane_registry.find_open_lane(child)
+	const dispatched_ms = lane?.dispatched_ms
+
+	return dispatched_ms !== undefined && dispatched_ms < booted_ms()
+}
+
+const run_merge_restart = { is_host_restart }
+
+export { run_merge_restart }