@joshuafolkken/kit 1.1514.0 → 1.2114.0

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,25 @@
+// 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',
+	'yielded',
+	'human-review',
+	'parked',
+	'split',
+	'cut',
+	'outage',
+	'unauthenticated',
+	'usage-limit',
+	'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 }

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

@@ -3,8 +3,10 @@ import { lane_registry } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
 import { run_event_scope } from '#scripts/run/event/run-event-scope'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import type { StallCause } from '#scripts/run/park/run-stalled'
 import { run_ending } from '#scripts/run/run-ending'
 import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import { run_ship_stop_text } from '#scripts/run/ship/run-ship-stop-text'
 
 // Why `run:merge` parks a child whose detached ship has already ended (joshuafolkken/kit#3808).
 //
@@ -35,7 +37,18 @@ function since_ship_launch(events: Events, child: string): Events | undefined {
 	return launched_at === -1 ? undefined : own.slice(launched_at + 1)
 }
 
-function cause_of(ending: ShipEnding, events: Events, child: string): string | undefined {
+// The stopped stage names the cause's short form (`review failed`); a stop text in no known shape is
+// still a ship stop.
+function stop_cause(stop: RunEvent): StallCause {
+	const stage = run_ship_stop_text.reason_of(stop.text)
+
+	return {
+		short: stage === undefined ? 'ship stopped' : `${stage} failed`,
+		why: `its detached ship stopped and was not fixed: ${stop.text}.`,
+	}
+}
+
+function cause_of(ending: ShipEnding, events: Events, child: string): StallCause | undefined {
 	if (ending === undefined || !ENDED_RESULTS.has(ending.result)) return undefined
 
 	const attempt = since_ship_launch(events, child)
@@ -43,14 +56,17 @@ function cause_of(ending: ShipEnding, events: Events, child: string): string | u
 
 	const stop = attempt.findLast((event) => event.kind === run_event_stream.EVENT_KIND.SHIP_STOP)
 
-	if (stop !== undefined) return `its detached ship stopped and was not fixed: ${stop.text}.`
+	if (stop !== undefined) return stop_cause(stop)
 
-	return `its detached ship ended ${ending.result} before recording a stopped stage — pnpm josh ship --log ${child}.`
+	return {
+		short: `ship ${ending.result}`,
+		why: `its detached ship ended ${ending.result} before recording a stopped stage — pnpm josh ship --log ${child}.`,
+	}
 }
 
 // The ship's cause for `child`'s park, read from the record and the stream this checkout's repository
 // keys on, or `undefined` when the child handed nothing to a ship or its ship succeeded.
-function cause(child: string, directory: string = process.cwd()): string | undefined {
+function cause(child: string, directory: string = process.cwd()): StallCause | undefined {
 	const repository = git_common_directory.repository(directory)
 	if (repository === undefined) return undefined
 
@@ -59,19 +75,29 @@ function cause(child: string, directory: string = process.cwd()): string | undef
 	return cause_of(run_ship_detach.read_result(repository, child), events, child)
 }
 
+function is_relaunch_failed(event: RunEvent): boolean {
+	return event.kind === run_event_stream.EVENT_KIND.RELAUNCH_FAILED
+}
+
 // Whether the ended ship was never answered: a session relaunched to fix a stop writes to the
 // transcript after it, so a transcript last written before the newest stop means no fix-up ran — its
-// broker or relaunch could not start. A ship with no stop at all ended abnormally only when its supervisor
-// died before reaching a stage.
+// broker or relaunch could not start. **A `relaunch-failed` after the stop reads it unanswered whatever the
+// mtime says** (joshuafolkken/kit#4765): the dispatch log's header is written before a spawn that may fail.
+// A ship with no stop at all ended abnormally only when its supervisor died before reaching a stage.
 function is_stop_unanswered(
 	ending: ShipEnding,
 	attempt: Events,
 	written_at: number | undefined,
 ): boolean {
-	const stop = attempt.findLast((event) => event.kind === run_event_stream.EVENT_KIND.SHIP_STOP)
+	const index = attempt.findLastIndex(
+		(event) => event.kind === run_event_stream.EVENT_KIND.SHIP_STOP,
+	)
+	const stop = attempt[index]
 
 	if (stop === undefined) return ending?.result === 'abnormal'
 
+	if (attempt.slice(index + 1).some((event) => is_relaunch_failed(event))) return true
+
 	return written_at !== undefined && written_at < Date.parse(stop.at)
 }
 

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

@@ -1,12 +1,16 @@
+import { api_auth } from '#scripts/agent/api-auth'
 import { api_outage } from '#scripts/agent/api-outage'
+import { api_usage_limit } from '#scripts/agent/api-usage-limit'
 import { issue_closing_pr } from '#scripts/issue/issue-closing-pr'
 import { issue_merged } from '#scripts/issue/issue-merged'
 import type { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { lane_yield } from '#scripts/lane/lane-yield'
 import { run_event_scope } from '#scripts/run/event/run-event-scope'
-import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_ending } from '#scripts/run/run-ending'
 import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
+import { run_merge_cap } from './run-merge-cap'
+import { run_merge_restart } from './run-merge-restart'
 import { run_merge_ship } from './run-merge-ship'
 import { run_merge_steps, type MergeContext } from './run-merge-steps'
 
@@ -25,32 +29,48 @@ function read_is_outage(output: string | undefined): boolean {
 	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()
+// Whether the child's session ended because it could not authenticate — off without `--output`, as the
+// outage read is. The lane's log is appended across launches, so it is read as the reviewer's is
+// (`api_auth.is_auth_failed_transcript`).
+function read_is_auth_failure(output: string | undefined): boolean {
+	if (output === undefined) return false
 
-	return events.filter(
-		(event) =>
-			event.kind === run_event_stream.EVENT_KIND.OUTAGE &&
-			run_event_scope.issue_named(event) === child,
-	).length
+	return api_auth.is_auth_failed_transcript(run_ending.read_transcript(output))
+}
+
+// Why an unfinished child is re-dispatchable, or `undefined` when it is not. **Only an API outage adds
+// to the run-wide streak**: a host restart is over by the time the child is read (joshuafolkken/kit#4540),
+// and an unanswered ship stop reached the API (joshuafolkken/kit#3974).
+async function retry_cause(
+	child: string,
+	output: string | undefined,
+): Promise<'api' | 'exempt' | undefined> {
+	if (await run_merge_restart.is_host_restart(child, output)) return 'exempt'
+
+	if (read_is_outage(output)) return 'api'
+
+	return (await run_merge_ship.is_unanswered(child, output)) ? 'exempt' : undefined
 }
 
 // An outage child is re-dispatched only so many times: one that ends the same way on every dispatch is
-// parked, since merges in other lanes reset the run-wide outage streak and would never stop it. **An
-// unanswered ship stop is told apart from an API outage**: the child reached the API, so it is
-// re-dispatched without adding to the run-wide streak (joshuafolkken/kit#3974).
+// parked, since merges in other lanes reset the run-wide outage streak and would never stop it. Its park
+// says so (`run-merge-cap.ts`).
 async function read_retryable(
 	child: string,
 	output: string | undefined,
-): Promise<{ is_outage: boolean; is_unanswered: boolean }> {
-	const is_api_outage = read_is_outage(output)
-	const is_unanswered = !is_api_outage && (await run_merge_ship.is_unanswered(child, output))
+): Promise<Pick<EndingSignals, 'is_outage' | 'is_streak_exempt' | 'capped_note'>> {
+	const cause = await retry_cause(child, output)
 
-	if (!is_api_outage && !is_unanswered) return { is_outage: false, is_unanswered: false }
+	if (cause === undefined) return { is_outage: false, is_streak_exempt: false }
 
-	const is_outage = (await child_outages(child)) < run_merge.CONSECUTIVE_OUTAGE_LIMIT
+	const events = await run_event_stream_emit.current_events()
+	const limit = run_merge.CONSECUTIVE_OUTAGE_LIMIT
 
-	return { is_outage, is_unanswered: is_outage && is_unanswered }
+	if (run_merge_cap.outages(events, child) >= limit) {
+		return { is_outage: false, capped_note: run_merge_cap.note_of(events, child, limit) }
+	}
+
+	return { is_outage: true, is_streak_exempt: cause === 'exempt' }
 }
 
 // The timeline is read only for an OPEN, unparked child — the one classification a merged closing pull
@@ -62,28 +82,49 @@ async function read_merged_pr(child: string, read: IssueRead): Promise<string |
 	return await issue_closing_pr.read_closing_pr(child)
 }
 
-// A child that merged before `lane:withdraw` stopped it is merged, not withdrawn: the withdrawal's
-// event is already written, so only the timeline tells its merged close from the not-planned one. An
-// unread timeline answers `undefined`, and `outcome_of` asks again rather than guessing.
+// **A CLOSED child is withdrawn unless a merge closed it**, whether or not `lane:withdraw` ran: an issue
+// closed as not planned, or closed with no merged pull request, never merged, so it must not be booked
+// as a merge (joshuafolkken/kit#4916). Only the timeline tells a merged close from the rest, so it
+// decides — and a child that merged before `lane:withdraw` stopped it is merged. Any other child is
+// withdrawn only by its event. An unread timeline answers `undefined`, and `outcome_of` asks again
+// rather than guessing.
 async function read_is_withdrawn(child: string, read: IssueRead): Promise<boolean | undefined> {
-	const events = await run_event_stream_emit.current_events()
+	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'merged') {
+		return run_event_scope.is_withdrawn(await run_event_stream_emit.current_events(), child)
+	}
 
-	if (!run_event_scope.is_withdrawn(events, child)) return false
-	if (read.kind !== 'state' || run_merge.classify_child(read.state) !== 'merged') return true
 	const is_merged = await issue_merged.read_merge_state(child)
 
 	return is_merged === undefined ? undefined : !is_merged
 }
 
+// The child's own yield is on the stream, read locally, as a person's withdrawal is.
+async function read_is_yielded(child: string): Promise<boolean> {
+	return lane_yield.is_yielded(await run_event_stream_emit.current_events(), child)
+}
+
+// When a usage limit that stopped the child resets — off without `--output`, as the outage read is. The
+// reset is read from the transcript's last write, not from this late collection of it.
+function read_resume_ms(output: string | undefined): number | undefined {
+	if (output === undefined) return undefined
+	const transcript = run_ending.read_transcript(output)
+
+	return api_usage_limit.transcript_resume_ms(transcript, Date.now(), run_ending.written_at(output))
+}
+
 async function read_signals(ctx: MergeContext, read: IssueRead): Promise<EndingSignals> {
-	const [is_cut, merged_pr, retryable, is_withdrawn] = await Promise.all([
+	const [is_cut, merged_pr, retryable, is_withdrawn, is_yielded] = await Promise.all([
 		run_merge_steps.has_resumable_cut(ctx.child),
 		read_merged_pr(ctx.child, read),
 		read_retryable(ctx.child, ctx.output),
 		read_is_withdrawn(ctx.child, read),
+		read_is_yielded(ctx.child),
 	])
 
-	return { ...retryable, is_cut, merged_pr, is_withdrawn }
+	const is_auth_failure = read_is_auth_failure(ctx.output)
+	const resume_ms = read_resume_ms(ctx.output)
+
+	return { ...retryable, is_cut, merged_pr, is_withdrawn, is_yielded, is_auth_failure, resume_ms }
 }
 
 // An unread state is `unresolved` unless a withdrawal already settled the child, which is read locally;