@joshuafolkken/kit 1.1514.0 → 1.1784.0

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'
 
@@ -32,7 +35,7 @@ const CLOSED = 'CLOSED'
 const EMPTY_SCOPE: GateScope = { standalone: new Set(), declared: new Map() }
 
 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 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 +48,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 +75,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(
@@ -107,15 +110,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 +143,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 +156,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
@@ -174,6 +199,7 @@ const backlog_waves = {
 	HEADING_ASSUMPTION,
 	NEEDS_DECISION_NOTE,
 	PARALLEL_NOTE,
+	run_stalled_note,
 	UNREACHED_HEADING,
 	build,
 	format_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

@@ -180,6 +180,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.
@@ -244,6 +249,7 @@ const backlogrun_launch = {
 	chosen_environment,
 	is_running,
 	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 }

package/scripts/backlog/backlogrun-stop.ts

@@ -22,12 +22,27 @@ import { backlogrun_launch } from './backlogrun-launch'
 // after a `run:wake --stop` or a supervisor that gave up, and the session it woke outlives both.
 //
 // **Lanes are counted, never stopped**: a child killed mid-change leaves a tree nobody can resume.
+// `josh lane:pause --all` is the way to suspend them without discarding anything.
+//
+// **`--restart` stops the same processes and keeps the record** (`stop_keeping_record`), so the run's
+// budget, counters and named list carry over to the supervisor started after it.
 
 const STOPPED_REASON = 'stopped by a person with `josh backlogrun --stop`'
 const PREFIX = 'backlogrun:'
 const ISSUE_PREFIX = '#'
 
-type RecordOutcome = { kind: 'none' } | { kind: 'ended' } | { kind: 'held'; owner: number }
+type RecordOutcome =
+	{ kind: 'none' } | { kind: 'ended' } | { kind: 'kept' } | { kind: 'held'; owner: number }
+
+// What stopping the processes left: the pids stopped, the record as it stood, and the live owner this
+// command may not signal.
+interface StoppedProcesses {
+	supervisor: number | undefined
+	parent: number | undefined
+	session: number | undefined
+	read: CarryRead
+	holder: number | undefined
+}
 
 interface StopReport {
 	// The pids stopped, `undefined` where there was nothing to stop.
@@ -41,6 +56,8 @@ interface StopReport {
 }
 
 interface StopPorts {
+	running_supervisor: (git_directory: string) => number | undefined
+	running_parent: (git_directory: string) => number | undefined
 	stop_supervisor: (git_directory: string) => number | undefined
 	stop_parent: (git_directory: string) => number | undefined
 	stop_session: (pid: number) => void
@@ -59,6 +76,8 @@ async function open_lanes(): Promise<Array<string>> {
 
 // A person who typed the stop is at the terminal, so the ⏸️ confirmation a stop pushes is not sent.
 const LIVE_PORTS: StopPorts = {
+	running_supervisor: (git_directory) => run_wake.read_wake(run_wake.wake_path(git_directory))?.pid,
+	running_parent: backlogrun_launch.running_parent,
 	stop_supervisor: (git_directory) => run_wake_stop.stop(run_wake.wake_path(git_directory))?.pid,
 	stop_parent: backlogrun_launch.stop_parent,
 	stop_session: run_wake_stop.signal,
@@ -120,17 +139,67 @@ async function close_record(
 	return { kind: 'ended' }
 }
 
-async function stop(git_directory: string, ports: StopPorts = LIVE_PORTS): Promise<StopReport> {
+function stop_processes(git_directory: string, ports: StopPorts): StoppedProcesses {
 	const supervisor = ports.stop_supervisor(git_directory)
 	const parent = ports.stop_parent(git_directory)
 	const read = ports.read_carry(git_directory)
 	const owner = standing_owner(read, [supervisor, parent], ports)
 	const session = stop_headless(owner, read, ports)
 	const holder = session === undefined ? owner : undefined
-	const record = await close_record(git_directory, read, holder, ports)
-	const lanes = await ports.lanes()
 
-	return { supervisor, parent, session, record, lanes }
+	return { supervisor, parent, session, read, holder }
+}
+
+function kept_record(read: CarryRead, holder: number | undefined): RecordOutcome {
+	if (read.kind === 'none') return { kind: 'none' }
+
+	return holder === undefined ? { kind: 'kept' } : { kind: 'held', owner: holder }
+}
+
+const NOTHING_STOPPED = { supervisor: undefined, parent: undefined, session: undefined }
+
+// The live owner `--restart` may not signal, read before anything is stopped: a refusal found after the
+// supervisor and the parent were stopped would leave the run with neither.
+function foreign_owner(git_directory: string, ports: StopPorts): number | undefined {
+	const read = ports.read_carry(git_directory)
+
+	if (is_headless_owner(read)) return undefined
+
+	const running = [ports.running_supervisor(git_directory), ports.running_parent(git_directory)]
+
+	return standing_owner(read, running, ports)
+}
+
+async function report_of(
+	stopped: Pick<StoppedProcesses, 'supervisor' | 'parent' | 'session'>,
+	record: RecordOutcome,
+	ports: StopPorts,
+): Promise<StopReport> {
+	const { supervisor, parent, session } = stopped
+
+	return { supervisor, parent, session, record, lanes: await ports.lanes() }
+}
+
+async function stop(git_directory: string, ports: StopPorts = LIVE_PORTS): Promise<StopReport> {
+	const stopped = stop_processes(git_directory, ports)
+	const record = await close_record(git_directory, stopped.read, stopped.holder, ports)
+
+	return await report_of(stopped, record, ports)
+}
+
+async function stop_keeping_record(
+	git_directory: string,
+	ports: StopPorts = LIVE_PORTS,
+): Promise<StopReport> {
+	const holder = foreign_owner(git_directory, ports)
+
+	if (holder !== undefined) {
+		return await report_of(NOTHING_STOPPED, { kind: 'held', owner: holder }, ports)
+	}
+
+	const stopped = stop_processes(git_directory, ports)
+
+	return await report_of(stopped, kept_record(stopped.read, stopped.holder), ports)
 }
 
 function process_line(what: string, pid: number | undefined): Array<string> {
@@ -140,6 +209,7 @@ function process_line(what: string, pid: number | undefined): Array<string> {
 function record_lines(outcome: RecordOutcome): Array<string> {
 	if (outcome.kind === 'none') return []
 	if (outcome.kind === 'ended') return [`${PREFIX} ended the run's record`]
+	if (outcome.kind === 'kept') return [`${PREFIX} kept the run's record`]
 
 	return [
 		`${PREFIX} process ${String(outcome.owner)} owns the run and was not started by \`josh backlogrun\`; its record is kept — end the run from that session`,
@@ -151,7 +221,9 @@ function lane_lines(lanes: ReadonlyArray<string>): Array<string> {
 
 	const issues = lanes.map((issue) => `${ISSUE_PREFIX}${issue}`).join(' ')
 
-	return [`${PREFIX} ${String(lanes.length)} lane(s) still running, not stopped: ${issues}`]
+	return [
+		`${PREFIX} ${String(lanes.length)} lane(s) still running, not stopped: ${issues} — suspend them in place with \`josh lane:pause --all\``,
+	]
 }
 
 // What a person reads back: one line per thing done, or the one line that says nothing was running.
@@ -172,7 +244,7 @@ function is_stopped(report: StopReport): boolean {
 	return report.record.kind !== 'held'
 }
 
-const backlogrun_stop = { is_stopped, lines_of, stop }
+const backlogrun_stop = { is_stopped, lines_of, stop, stop_keeping_record }
 
 export type { StopPorts, StopReport }
 export { backlogrun_stop }

package/scripts/behavior/behavior-cli.ts

@@ -13,8 +13,8 @@ import { behavior_rules } from './behavior-rules'
 // **The scope is the current run, not the whole corpus.** The store holds thousands of transcripts
 // and over a gigabyte; walking all of it every gate would cost minutes, not the seconds the other
 // checks take. Each gate checks its own run, so across runs the whole corpus is covered a run at a
-// time — and the engine stays general, so a broad scan of past runs (the greenness check this seed
-// assertion was verified with) is the same walk over a different set of files.
+// time — and the engine stays general, so a broad scan of past runs (the greenness check each
+// assertion is verified with) is the same walk over a different set of files.
 
 const PASS_EXIT_CODE = 0
 const FAIL_EXIT_CODE = 1