@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/backlog/backlog-stalled.ts

@@ -1,11 +1,13 @@
 import { epic_triage } from '#scripts/epic/epic-triage'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 // When ready backlog work sits undispatched while lanes are free, nobody notices until a person asks.
 // This is the mechanical judge of that state: three facts read, never
 // weighed — is there runnable work, is there a free lane, and has nothing been dispatched for a while.
-// The verdict is a report, not a stop: a false positive costs one notification, never a halted run.
+// The verdict is a report, not a stop: a false positive costs one stream marker, never a halted run.
 //
 // **Pure by design.** The clock and the counts are handed in, so the four acceptance cases — work with
 // a free lane, work with no free lane, no work, and an unreadable record — and the elapsed-time
@@ -13,7 +15,6 @@ import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-st
 // counts is `backlog-stalled-detect.ts`; this file only decides.
 
 const STALL_THRESHOLD_MINUTES = 10
-const MS_PER_MINUTE = 60_000
 const STALL_THRESHOLD_MS = STALL_THRESHOLD_MINUTES * MS_PER_MINUTE
 const NONE = 0
 
@@ -28,11 +29,14 @@ const OK: StallVerdict = 'ok'
 const UNREADABLE: StallVerdict = 'unreadable'
 
 // The three facts, read and never judged: how many issues could start now, how many lanes are free, and
-// how long since the last dispatch. Assembled by the detect layer; consumed only here.
+// how long both have held together since the last dispatch — never the idle time before work arrived or
+// a long child ran (joshuafolkken/kit#4349). `hold` is the driver's open hold reason (`memory`, …), so a
+// deliberate hold reads apart from a slow dispatch. Assembled by the detect layer; consumed only here.
 interface StallReading {
 	ready_count: number
 	free_lanes: number
-	dispatch_age_ms: number
+	waiting_ms: number
+	hold?: string | undefined
 }
 
 // All three together, and only together. Separated from `assess` so the short-circuit gate in the
@@ -40,9 +44,7 @@ interface StallReading {
 // same condition rather than a second copy of it.
 function is_stalled(reading: StallReading, threshold_ms: number): boolean {
 	return (
-		reading.ready_count > NONE &&
-		reading.free_lanes > NONE &&
-		reading.dispatch_age_ms > threshold_ms
+		reading.ready_count > NONE && reading.free_lanes > NONE && reading.waiting_ms > threshold_ms
 	)
 }
 
@@ -68,23 +70,55 @@ function dispatch_reference_iso(events: ReadonlyArray<RunEvent>): string | undef
 	return last_launch?.at ?? events[0]?.at
 }
 
-// Milliseconds since that reference, or `undefined` when there is no reference or the stamp is
-// unparseable — the caller reads either as "nothing to age against" and returns no stall.
-function dispatch_age_ms(events: ReadonlyArray<RunEvent>, now_ms: number): number | undefined {
+// That reference as epoch milliseconds, or `undefined` when there is none or the stamp is unparseable.
+function dispatch_reference_ms(events: ReadonlyArray<RunEvent>): number | undefined {
 	const iso = dispatch_reference_iso(events)
+	const at = iso === undefined ? NaN : Date.parse(iso)
+
+	return Number.isNaN(at) ? undefined : at
+}
 
-	if (iso === undefined) return undefined
+// Milliseconds since that reference, or `undefined` when there is no reference — the caller reads it as
+// "nothing to age against" and returns no stall. A stall cannot be older than this, so it gates the
+// costly reads.
+function dispatch_age_ms(events: ReadonlyArray<RunEvent>, now_ms: number): number | undefined {
+	const at = dispatch_reference_ms(events)
+
+	return at === undefined ? undefined : now_ms - at
+}
+
+// When the current coexistence of offerable work and a free lane was first observed: the newest
+// observation since the reference, if it saw both. `undefined` when it did not or none was made — an
+// observation before the last dispatch belongs to an episode that dispatch ended.
+function open_offerable_ms(
+	entries: ReadonlyArray<LedgerEntry>,
+	reference_ms: number,
+): number | undefined {
+	const newest = entries.findLast(
+		(entry) => entry.kind === lane_ledger.KIND.OFFERABLE && Date.parse(entry.at) >= reference_ms,
+	)
+
+	if (newest?.kind !== lane_ledger.KIND.OFFERABLE || !newest.is_offerable) return undefined
+
+	return Date.parse(newest.at)
+}
 
-	const at = Date.parse(iso)
+// The driver's open hold reason: the newest of its hold, release and dispatch records, when a hold.
+function open_hold(entries: ReadonlyArray<LedgerEntry>): string | undefined {
+	const { HELD, RELEASED, DISPATCH } = lane_ledger.KIND
+	const hold_kinds: ReadonlySet<string> = new Set([HELD, RELEASED, DISPATCH])
+	const newest = entries.findLast((entry) => hold_kinds.has(entry.kind))
 
-	return Number.isNaN(at) ? undefined : now_ms - at
+	return newest?.kind === lane_ledger.KIND.HELD ? newest.reason : undefined
 }
 
-// The one line a person reads in the notification and on the stream: what is waiting and how long.
+// The one line a person reads in the notification and on the stream: what is waiting, how long, and the
+// driver's hold reason when it holds deliberately.
 function describe(reading: StallReading): string {
-	const minutes = Math.floor(reading.dispatch_age_ms / MS_PER_MINUTE)
+	const minutes = Math.floor(reading.waiting_ms / MS_PER_MINUTE)
+	const held = reading.hold === undefined ? '' : ` (held: ${reading.hold})`
 
-	return `${String(reading.ready_count)} ready, ${String(reading.free_lanes)} free lane(s), ${String(minutes)}m since the last dispatch`
+	return `${String(reading.ready_count)} ready, ${String(reading.free_lanes)} free lane(s), ${String(minutes)}m waiting with both${held}`
 }
 
 // The runnable issue numbers `backlog:next` printed: one token per line, a bare number per runnable
@@ -118,6 +152,8 @@ const backlog_stalled = {
 	describe,
 	dispatch_age_ms,
 	needs_triage,
+	open_hold,
+	open_offerable_ms,
 	ready_tokens,
 }
 

package/scripts/backlog/backlog-wait-cause.ts

@@ -0,0 +1,86 @@
+import type { EpicChild } from '#scripts/epic/epic-graph'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { has_label_name, IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_not_before } from '#scripts/issue/issue-not-before'
+
+// Why the backlog had nothing to offer while children ran (joshuafolkken/kit#4513): which waiting
+// issues wait on a dependency chain, and which on a declared start condition (a start date or a
+// sample condition, `issue-not-before.ts`), so `lane:stats` splits `offer:watch:blocked` by cause instead of reporting one row.
+//
+// `backlog:next` writes one line per cause on standard error and `backlog:offer` reads them back, the
+// way the `run:solo` notice travels; both sides go through this module so the spelling cannot drift.
+// A child carrying `in-progress` is the running work itself, not a wait it causes, so it is left out.
+
+type WaitCause = 'chain' | 'gate'
+
+type WaitCauses = Readonly<Record<WaitCause, ReadonlyArray<number>>>
+
+const CAUSES: ReadonlyArray<WaitCause> = ['chain', 'gate']
+const MARKS: Readonly<Record<WaitCause, string>> = {
+	chain: 'Waiting on a dependency chain:',
+	gate: 'Waiting on a start condition:',
+}
+const TAG_SEPARATOR = '+'
+const ISSUE_PATTERN = /#(\d+)/gu
+const CLOSED_STATE = 'CLOSED'
+
+// `blocked_by` keeps a relation after its blocker closes, so a candidate the overlap separation moved
+// to `waiting` would read as a chain on the closed relation alone.
+function has_open_blocker(child: EpicChild): boolean {
+	return child.blocked_by.some((blocker) => blocker.state !== CLOSED_STATE)
+}
+
+function cause_of(child: EpicChild): WaitCause | undefined {
+	if (has_label_name(child.labels, IN_PROGRESS_LABEL)) return undefined
+	if (!issue_not_before.is_due(child.body)) return 'gate'
+
+	return has_open_blocker(child) ? 'chain' : undefined
+}
+
+function numbers_with(children: ReadonlyArray<EpicChild>, cause: WaitCause): Array<number> {
+	return children.filter((child) => cause_of(child) === cause).map((child) => child.number)
+}
+
+// This repository's waiting children by cause; a child elsewhere is not work this checkout could start.
+function classify(children: ReadonlyArray<EpicChild>, repo: string): WaitCauses {
+	const here = children.filter((child) => child.repo === repo)
+
+	return { chain: numbers_with(here, 'chain'), gate: numbers_with(here, 'gate') }
+}
+
+function cited(numbers: ReadonlyArray<number>): string {
+	return numbers.map((number) => issue_cite.plain(number)).join(' ')
+}
+
+function lines_of(causes: WaitCauses): ReadonlyArray<string> {
+	return CAUSES.filter((cause) => causes[cause].length > 0).map(
+		(cause) => `${MARKS[cause]} ${cited(causes[cause])}`,
+	)
+}
+
+// The numbers on the cause's line; a linkified `[#N](…/issues/N)` still reads as one `#N`.
+function numbers_on(text: string, cause: WaitCause): ReadonlyArray<number> {
+	const line = text.split('\n').find((candidate) => candidate.startsWith(MARKS[cause]))
+
+	return [...(line ?? '').matchAll(ISSUE_PATTERN)].map((match) => Number(match[1]))
+}
+
+function parse(text: string): WaitCauses {
+	return { chain: numbers_on(text, 'chain'), gate: numbers_on(text, 'gate') }
+}
+
+// `chain`, `gate` or `chain+gate` — the held reason's last part — or `undefined` when neither applies.
+function tag_of(causes: WaitCauses): string | undefined {
+	const present = CAUSES.filter((cause) => causes[cause].length > 0)
+
+	return present.length > 0 ? present.join(TAG_SEPARATOR) : undefined
+}
+
+function numbers_of(causes: WaitCauses): ReadonlyArray<number> {
+	return [...causes.chain, ...causes.gate]
+}
+
+const backlog_wait_cause = { classify, lines_of, numbers_of, parse, tag_of }
+
+export type { WaitCauses }
+export { backlog_wait_cause }

package/scripts/backlog/backlog-waves.ts

@@ -6,9 +6,12 @@ import { epic_outside_blocker } from '#scripts/epic/epic-outside-blocker'
 import { epic_report, type EpicNextResult } from '#scripts/epic/epic-report'
 import {
 	has_label_name,
+	has_parked_label,
 	IN_PROGRESS_LABEL,
 	NEEDS_DECISION_LABEL,
+	RUN_STALLED_LABEL,
 } from '#scripts/issue/issue-labels'
+import { run_stalled } from '#scripts/run/park/run-stalled'
 import { backlog_plan, type PlanContext } from './backlog-plan'
 import { backlog_rank, type GateScope } from './backlog-rank'
 
@@ -21,7 +24,7 @@ import { backlog_rank, type GateScope } from './backlog-rank'
 // **No rule is written twice.** The first wave is `backlog_rank.select` — rank, `run:solo` gate,
 // overlap separation, cap —
 // over the very candidates `backlog:next` resolves, asked of an idle repository — so it is what
-// `backlog:next` prints when nothing is running. Each later wave marks the earlier waves closed and re-classifies the same pool
+// `backlog:next` prints when nothing is running, cut at the lane limit rather than the printed count. Each later wave marks the earlier waves closed and re-classifies the same pool
 // through `epic_classify.classify_children` with the resolver `epic:next` sorted it with the first
 // time — `epic_cross_repo.resolve_cross_repo`, so a blocker in another repository still waits for its
 // release rather than counting as done on close — then puts the runnable set through
@@ -30,9 +33,13 @@ import { backlog_rank, type GateScope } from './backlog-rank'
 const IDLE: BusyRead = { kind: 'idle' }
 const CLOSED = 'CLOSED'
 const EMPTY_SCOPE: GateScope = { standalone: new Set(), declared: new Map() }
+// A wave is as wide as the lanes that run it, not `backlog:next`'s `DISPLAY_LIMIT` — that printed
+// count pushed an issue whose blocker closed in wave k past wave k+1 (joshuafolkken/kit#5300).
+const UNCAPPED = Infinity
 
 const HEADING_ASSUMPTION =
-	'Assumes every issue in a wave merges before the next wave starts. Issues a run already has are left out, and only issues of this repository are planned.'
+	'Assumes every issue in a wave merges before the next wave starts. Issues a run already has are left out and count as merged first, and only issues of this repository are planned.'
+const UNCAPPED_WIDTH = 'A wave is not capped: the lane limit could not be read.'
 const UNREACHED_HEADING = 'Not reached — each names what it is waiting on:'
 const PARALLEL_NOTE = '(parallel)'
 const NEEDS_DECISION_NOTE = `waiting on a person (\`${NEEDS_DECISION_LABEL}\`)`
@@ -45,18 +52,23 @@ const PARALLEL_GAP = ' '.repeat(PARALLEL_GAP_WIDTH)
 interface WavePlan {
 	waves: ReadonlyArray<ReadonlyArray<EpicChild>>
 	unreached: ReadonlyArray<EpicChild>
+	// This repository's running issues, which count as merged before wave 1 and so sit in neither list
+	// above; still the run's own, so `run:board` holds their lanes (kit#3969).
+	running?: ReadonlyArray<EpicChild>
 }
 
+// A park leaves `in-progress` on (`epic-busy.ts`), and a parked issue waits on a person rather than
+// finishing first.
 function is_running(child: EpicChild): boolean {
-	return has_label_name(child.labels, IN_PROGRESS_LABEL)
+	return has_label_name(child.labels, IN_PROGRESS_LABEL) && !has_parked_label(child.labels)
 }
 
 function as_closed(child: EpicChild, done: ReadonlySet<string>): EpicChild {
 	return done.has(epic_graph.key_of(child)) ? { ...child, state: CLOSED } : child
 }
 
-// The pool a wave is chosen from. A running issue is left out of it but kept in `running`, so a child
-// behind it waits on it rather than being handed to a person.
+// The pool a wave is chosen from. `running` is every issue this run may finish, so a child behind one
+// waits on it rather than being handed to a person.
 interface WavePool {
 	children: ReadonlyArray<EpicChild>
 	running: ReadonlySet<string>
@@ -67,12 +79,7 @@ interface WavePool {
 function pool_of(result: EpicNextResult, repo: string, scope: GateScope): WavePool {
 	const all = backlog_rank.everything_in(result)
 
-	return {
-		children: all.filter((child) => !is_running(child)),
-		running: epic_outside_blocker.running_keys(all),
-		repo,
-		scope,
-	}
+	return { children: all, running: epic_outside_blocker.running_keys(all), repo, scope }
 }
 
 function offer(
@@ -81,8 +88,10 @@ function offer(
 	pool: WavePool,
 ): ReadonlyArray<EpicChild> {
 	const { repo, scope } = pool
+	const limit = scope.wave_limit ?? UNCAPPED
 
-	return backlog_rank.select({ candidates, pool: children, read: IDLE, repo, ...scope }).offered
+	return backlog_rank.select({ candidates, pool: children, read: IDLE, repo, ...scope, limit })
+		.offered
 }
 
 // Ranked against the whole result, exactly as `backlog:next` ranks it, so the two agree.
@@ -107,15 +116,31 @@ function next_wave(pool: WavePool, done: ReadonlySet<string>): ReadonlyArray<Epi
 	)
 }
 
+// `backlog:next` offers nothing behind a running issue, so an empty first wave still asks for the
+// issues the running ones release.
+function opening_wave(
+	result: EpicNextResult,
+	pool: WavePool,
+	done: ReadonlySet<string>,
+): ReadonlyArray<EpicChild> {
+	const wave = first_wave(result, pool)
+
+	return wave.length > 0 ? wave : next_wave(pool, done)
+}
+
 // Each wave is closed before the next is asked for; a wave that offers nothing ends the plan, which
 // the pool's size bounds because every wave closes at least one child. `scope` names the rows the
 // offer's cap bounds and the paths each issue declares; left empty, no wave is capped or separated.
 function build(result: EpicNextResult, repo: string, scope: GateScope = EMPTY_SCOPE): WavePlan {
 	const pool = pool_of(result, repo, scope)
-	const done = new Set<string>()
+	const running = pool.children.filter((child) => child.repo === repo && is_running(child))
+	// A running issue finishes first, before any wave: it starts closed, so it is never offered and the
+	// issues behind it reach a later wave instead of waiting past the plan. Another repository's is not
+	// this run's to finish, and closing it would answer its release from the version already out.
+	const done = new Set(running.map((child) => epic_graph.key_of(child)))
 	const waves: Array<ReadonlyArray<EpicChild>> = []
 
-	for (let wave = first_wave(result, pool); wave.length > 0; wave = next_wave(pool, done)) {
+	for (let wave = opening_wave(result, pool, done); wave.length > 0; wave = next_wave(pool, done)) {
 		waves.push(wave)
 		for (const child of wave) done.add(epic_graph.key_of(child))
 	}
@@ -124,7 +149,12 @@ function build(result: EpicNextResult, repo: string, scope: GateScope = EMPTY_SC
 		.everything_in(result)
 		.filter((child) => child.repo === repo && !done.has(epic_graph.key_of(child)))
 
-	return { waves, unreached }
+	return { waves, unreached, running }
+}
+
+// A stalled issue's note ends on the one next action its park comment names (`run-stalled.ts`).
+function run_stalled_note(child: number): string {
+	return `stalled mechanically — ${run_stalled.next_step(child)}`
 }
 
 // The plan's own "waiting on" wording is reused, so an unreached issue names its blocker the way the
@@ -132,6 +162,7 @@ function build(result: EpicNextResult, repo: string, scope: GateScope = EMPTY_SC
 // as not reached instead.
 function unreached_note(child: EpicChild, context: PlanContext): string {
 	if (has_label_name(child.labels, NEEDS_DECISION_LABEL)) return NEEDS_DECISION_NOTE
+	if (has_label_name(child.labels, RUN_STALLED_LABEL)) return run_stalled_note(child.number)
 	const note = backlog_plan.waiting_note(child, context)
 
 	return note === backlog_plan.PAST_OFFER_NOTE ? NOT_REACHED_NOTE : note
@@ -150,6 +181,12 @@ function unreached_lines(plan: WavePlan, context: PlanContext): Array<string> {
 	)
 }
 
+function width_line(wave_limit: number | undefined): string {
+	if (wave_limit === undefined) return UNCAPPED_WIDTH
+
+	return `A wave holds at most ${String(wave_limit)} standalone issues, the lane limit; an epic's children are not counted.`
+}
+
 function format_waves(
 	result: EpicNextResult,
 	context: PlanContext,
@@ -163,6 +200,7 @@ function format_waves(
 	return [
 		`Backlog waves — ${context.repo}`,
 		HEADING_ASSUMPTION,
+		width_line(scope.wave_limit),
 		'',
 		...(waves.length === 0 ? [backlog_plan.NOTHING] : waves),
 		'',
@@ -174,9 +212,12 @@ const backlog_waves = {
 	HEADING_ASSUMPTION,
 	NEEDS_DECISION_NOTE,
 	PARALLEL_NOTE,
+	run_stalled_note,
+	UNCAPPED_WIDTH,
 	UNREACHED_HEADING,
 	build,
 	format_waves,
+	width_line,
 }
 
 export { backlog_waves }

package/scripts/backlog/backlogrun-args.ts

@@ -10,11 +10,16 @@ import { run_invocation } from '#scripts/run/run-invocation'
 // **A bare number is an issue.** A shell reads an unquoted `#3437` as a comment, so `3437` in the named
 // list is taken as `#3437`; a number after the first flag is that flag's value and is left alone.
 //
-// **`--stop` stands alone.** It stops the run rather than starting one, so beside an issue or any other
-// flag it is refused before anything is stopped — a mistyped start must never end a run.
+// **`--stop` and `--restart` stand alone.** Each stops the run rather than starting one, so beside an
+// issue or any other flag it is refused before anything is stopped — a mistyped start must never end a
+// run.
 
 const AGENT_FLAG = '--agent'
-const STOP_FLAG = '--stop'
+// A map, not an object literal: a token such as `constructor` must not read an inherited property.
+const LONE_FLAGS: ReadonlyMap<string, LoneKind> = new Map([
+	['--stop', 'stop'],
+	['--restart', 'restart'],
+])
 const BACKLOG_COMMAND = 'backlogrun'
 const ISSUE_PREFIX = '#'
 const FLAG_PREFIX = '-'
@@ -30,8 +35,13 @@ interface BacklogrunArguments {
 	issues: ReadonlyArray<number>
 }
 
+type LoneKind = 'stop' | 'restart'
+
 type ArgumentsResult =
-	{ kind: 'args'; args: BacklogrunArguments } | { kind: 'stop' } | { kind: 'refused' }
+	| { kind: 'args'; args: BacklogrunArguments }
+	| { kind: 'stop' }
+	| { kind: 'restart' }
+	| { kind: 'refused' }
 
 interface AgentSplit {
 	agent: string | undefined
@@ -74,12 +84,14 @@ function parse_start(argv: ReadonlyArray<string>): ArgumentsResult {
 }
 
 function parse(argv: ReadonlyArray<string>): ArgumentsResult {
-	if (!argv.includes(STOP_FLAG)) return parse_start(argv)
+	const lone = argv.map((token) => LONE_FLAGS.get(token)).find((kind) => kind !== undefined)
+
+	if (lone === undefined) return parse_start(argv)
 
-	return { kind: argv.length === 1 ? 'stop' : 'refused' }
+	return { kind: argv.length === 1 ? lone : 'refused' }
 }
 
 const backlogrun_args = { parse }
 
-export type { BacklogrunArguments }
+export type { ArgumentsResult, BacklogrunArguments }
 export { backlogrun_args }

package/scripts/backlog/backlogrun-cli.ts

@@ -7,12 +7,14 @@ import { run_board_cli } from '#scripts/run/board/run-board-cli'
 import { run_carry } from '#scripts/run/carry/run-carry'
 import type { LaunchResult } from '#scripts/run/detached-launch'
 import { run_wake_cli } from '#scripts/run/wake/run-wake-cli'
-import { backlogrun_args, type BacklogrunArguments } from './backlogrun-args'
+import { backlogrun_args, type ArgumentsResult, type BacklogrunArguments } from './backlogrun-args'
 import { backlogrun_launch, type LaunchTarget, type StartResult } from './backlogrun-launch'
 import { backlogrun_replace, type ReplaceVerdict } from './backlogrun-replace'
+import { backlogrun_restart } from './backlogrun-restart'
 import { backlogrun_stop, type StopReport } from './backlogrun-stop'
 
-// `josh backlogrun` — start a `backlogrun` from the terminal and watch it, or stop it with `--stop`. A
+// `josh backlogrun` — start a `backlogrun` from the terminal and watch it, stop it with `--stop`, or
+// replace its processes with `--restart` while its record is kept (`backlogrun-restart.ts`). A
 // run already going is never joined by a second one: the board is shown, and any issue named is pointed
 // at `run:add` rather than added behind the person's back. Otherwise the agent is started in the
 // background, its output to a log file, and the board takes over the terminal at once. Closing the
@@ -27,7 +29,7 @@ const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const USAGE =
-	'Usage: josh backlogrun [<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop'
+	'Usage: josh backlogrun [<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop | --restart'
 
 interface BacklogrunPorts {
 	repository_directory: () => Promise<string | undefined>
@@ -36,6 +38,7 @@ interface BacklogrunPorts {
 	start: (args: BacklogrunArguments, target: LaunchTarget) => StartResult
 	start_supervisor: (git_directory: string, provider: AgentProvider) => LaunchResult
 	stop: (git_directory: string) => Promise<StopReport>
+	restart: (git_directory: string) => Promise<number>
 	show_board: () => Promise<number>
 	write: (line: string) => void
 }
@@ -48,6 +51,7 @@ const LIVE_PORTS: BacklogrunPorts = {
 	start: (args, target) => backlogrun_launch.start(args.invocation, args.provider, target),
 	start_supervisor: run_wake_cli.start_for_launch,
 	stop: async (git_directory) => await backlogrun_stop.stop(git_directory),
+	restart: async (git_directory) => await backlogrun_restart.restart(git_directory),
 	show_board: async () => await run_board_cli.run([]),
 	write: (line) => process.stdout.write(`${line}\n`),
 }
@@ -150,6 +154,17 @@ async function stop(git_directory: string, ports: BacklogrunPorts): Promise<numb
 	return backlogrun_stop.is_stopped(report) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
+async function dispatch(
+	parsed: Exclude<ArgumentsResult, { kind: 'refused' }>,
+	git_directory: string,
+	ports: BacklogrunPorts,
+): Promise<number> {
+	if (parsed.kind === 'stop') return await stop(git_directory, ports)
+	if (parsed.kind === 'restart') return await ports.restart(git_directory)
+
+	return await begin(parsed.args, git_directory, ports)
+}
+
 function refuse(line: string, ports: BacklogrunPorts): number {
 	ports.write(line)
 
@@ -167,9 +182,8 @@ async function run(
 	const git_directory = await ports.repository_directory()
 
 	if (git_directory === undefined) return refuse('backlogrun: not inside a git repository', ports)
-	if (parsed.kind === 'stop') return await stop(git_directory, ports)
 
-	return await begin(parsed.args, git_directory, ports)
+	return await dispatch(parsed, git_directory, ports)
 }
 
 const backlogrun_cli = { run }

package/scripts/backlog/backlogrun-launch.ts

@@ -6,6 +6,7 @@ import {
 	type AgentProvider,
 } from '#scripts/agent/agent-role-profile'
 import { agent_session_environment } from '#scripts/josh/agent-session-environment'
+import { durable_state } from '#scripts/josh/durable-state'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
@@ -27,8 +28,8 @@ import { z } from 'zod'
 // session can still start a Codex parent. The same choice is handed to the parent as
 // `JOSH_AGENT_PROVIDER`, the key a detached child with no session of its own resolves from.
 
-const LAUNCH_PREFIX = 'josh-backlogrun-launch-'
-const LOG_PREFIX = 'josh-backlogrun-log-'
+const LAUNCH_PREFIX = durable_state.PREFIX.BACKLOGRUN_LAUNCH
+const LOG_PREFIX = durable_state.PREFIX.BACKLOGRUN_LOG
 const LOG_SUFFIX = '.log'
 
 const launch_schema = z.object({
@@ -64,11 +65,11 @@ interface Launched {
 type StartResult = { kind: 'launched'; launched: Launched } | { kind: 'failed'; note: string }
 
 function launch_path(git_directory: string): string {
-	return stamp_file.stamp_path(LAUNCH_PREFIX, git_directory)
+	return durable_state.path(LAUNCH_PREFIX, git_directory)
 }
 
 function log_path(git_directory: string): string {
-	return stamp_file.stamp_path(LOG_PREFIX, git_directory, LOG_SUFFIX)
+	return durable_state.path(LOG_PREFIX, git_directory, LOG_SUFFIX)
 }
 
 function read_launch(target: string): LaunchRecord | undefined {
@@ -180,6 +181,11 @@ function signal_parent(pid: number): void {
 	}
 }
 
+// The pid `stop_parent` would stop, read without stopping it.
+function running_parent(git_directory: string): number | undefined {
+	return live_launch(git_directory)?.pid
+}
+
 // Stops the parent this launcher started and forgets its launch — the pid stopped, `undefined` where
 // no launched parent was live. **Only the process the record names, and only while it is still that
 // process**: a session a person typed `backlogrun` into has no launch record and is never signalled.
@@ -243,7 +249,10 @@ const backlogrun_launch = {
 	argv_of,
 	chosen_environment,
 	is_running,
+	launch_path,
+	log_path,
 	pending_launch,
+	running_parent,
 	start,
 	started_for,
 	stop_parent,

package/scripts/backlog/backlogrun-restart.ts

@@ -0,0 +1,97 @@
+import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import { run_board_cli } from '#scripts/run/board/run-board-cli'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
+import { run_carry_ended, type EndedRun } from '#scripts/run/carry/run-carry-ended'
+import { run_wake } from '#scripts/run/wake/run-wake'
+import { run_wake_cli } from '#scripts/run/wake/run-wake-cli'
+import { backlogrun_stop, type StopReport } from './backlogrun-stop'
+
+// `josh backlogrun --restart` — the run's processes replaced, its record kept. The supervisor, the
+// parent and a headless session are stopped as `--stop` stops them, the record is left standing, and a
+// supervisor started on the stopped one's profile adopts it: the budget, the counters and the named list
+// carry over, and the plan made at the start is not made again.
+//
+// **Only a run with a record is restarted.** No record is nothing to restart; a record `--end` closed
+// is a run that is over, and the line names the invocation that starts it again rather than reviving it.
+// A run owned by a session this command may not signal is refused as `--stop` refuses it.
+//
+// **No parent session is started.** The driver (`backlog:drive`) does the routine work, and the
+// supervisor wakes a session only where a decision is needed.
+
+const PREFIX = 'backlogrun:'
+const ISSUE_PREFIX_PATTERN = /^#/u
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+interface RestartPorts {
+	read_carry: (git_directory: string) => CarryRead
+	read_ended: (git_directory: string) => EndedRun | undefined
+	read_profile: (git_directory: string) => AgentProfile | undefined
+	stop: (git_directory: string) => Promise<StopReport>
+	start_supervisor: (git_directory: string, profile: AgentProfile | undefined) => number
+	show_board: () => Promise<number>
+	write: (line: string) => void
+}
+
+const LIVE_PORTS: RestartPorts = {
+	read_carry: (git_directory) => run_carry.read_carry(run_carry.carry_path(git_directory)),
+	read_ended: (git_directory) =>
+		run_carry_ended.read_ended(run_carry_ended.ended_path(git_directory)),
+	read_profile: (git_directory) => run_wake.read_wake(run_wake.wake_path(git_directory))?.profile,
+	stop: async (git_directory) => await backlogrun_stop.stop_keeping_record(git_directory),
+	start_supervisor: run_wake_cli.restart_supervisor,
+	show_board: async () => await run_board_cli.run([]),
+	write: (line) => process.stdout.write(`${line}\n`),
+}
+
+// The shell reads an unquoted `#N` as a comment, so the named list is written as bare numbers, which
+// `josh backlogrun` reads back as issues.
+function typed_invocation(invocation: string): string {
+	const tokens = invocation.split(' ').map((token) => token.replace(ISSUE_PREFIX_PATTERN, ''))
+
+	return `pnpm josh ${tokens.join(' ')}`
+}
+
+// Why nothing is restarted where the record is not carried.
+function refusal_of(read: CarryRead, ended: EndedRun | undefined): string {
+	if (read.kind === 'unreadable') return `${PREFIX} the run's record could not be read`
+	if (ended === undefined) return `${PREFIX} nothing to restart`
+
+	return `${PREFIX} the run has ended; start it again with \`${typed_invocation(ended.invocation)}\``
+}
+
+function refuse(line: string, ports: RestartPorts): number {
+	ports.write(line)
+
+	return FAILURE_EXIT_CODE
+}
+
+// The supervisor's profile is read before it is stopped, since stopping it removes the record that
+// holds it; the new one runs on the same provider whatever shell the restart was typed in.
+async function replace(git_directory: string, ports: RestartPorts): Promise<number> {
+	const profile = ports.read_profile(git_directory)
+	const report = await ports.stop(git_directory)
+
+	for (const line of backlogrun_stop.lines_of(report)) ports.write(line)
+
+	if (!backlogrun_stop.is_stopped(report)) return FAILURE_EXIT_CODE
+
+	if (ports.start_supervisor(git_directory, profile) !== SUCCESS_EXIT_CODE) {
+		return refuse(`${PREFIX} could not start the supervisor`, ports)
+	}
+
+	return await ports.show_board()
+}
+
+async function restart(git_directory: string, ports: RestartPorts = LIVE_PORTS): Promise<number> {
+	const read = ports.read_carry(git_directory)
+
+	if (read.kind === 'carried') return await replace(git_directory, ports)
+
+	return refuse(refusal_of(read, ports.read_ended(git_directory)), ports)
+}
+
+const backlogrun_restart = { restart }
+
+export type { RestartPorts }
+export { backlogrun_restart }