@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/backlog/backlog-drive-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
+import { auto_ok_judge_read, type JudgedCache } from '#scripts/auto-ok/auto-ok-judge-read'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
@@ -166,6 +167,18 @@ function end_line(end: DriveEnd): string {
 	return end.detail === undefined ? base : `${base} ${end.detail}`
 }
 
+// The count of open issues owing an `auto-ok` judgement, over a cache kept for the process so a watch
+// minute reads the comments only of the issues that moved (`auto-ok-judge-read.ts`).
+function judgement_reader(): () => Promise<number> {
+	const cache: JudgedCache = new Map()
+
+	return async () => {
+		const owed = await auto_ok_judge_read.owed(cache)
+
+		return owed?.length ?? 0
+	}
+}
+
 function ports_of(
 	context: DriveContext,
 	seeded: ReadonlyArray<string>,
@@ -177,6 +190,7 @@ function ports_of(
 		offer: async (state) => await read_offer(state, context),
 		launch: async (issue) => await backlog_drive_launch.launch(issue, context.owner),
 		free_lanes: backlog_ready.drive_free_lane_count,
+		judgement_owed: judgement_reader(),
 		now: () => new Date(),
 		sleep: async (milliseconds) => {
 			await sleep(milliseconds)

package/scripts/backlog/backlog-drive-epic.ts

@@ -1,3 +1,4 @@
+import { epic_triage } from '#scripts/epic/epic-triage'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -12,7 +13,12 @@ import { backlog_offer } from './backlog-offer'
 // is runnable, without `run:add` and without waking a parent session.
 //
 // **Only what needs a person is handed back.** `stop` means every child left waits on a person, which a
-// judgment session reads. A failed `epic:next` is either a network blip or a broken graph (a cycle, an
+// judgment session reads. `triage` means a child carries neither `run:solo` nor `run:lane`, so
+// `epic:next --lanes` offers nothing until a session judges it — it exits 0 and repeats on every pass,
+// so waiting on it would never end. It is handed back under its own word, as the pool path's is, never
+// as `epic #N`: that verdict sends the session to run the epic's children, and the single-child
+// `epic:next` it asks there is not triage-gated, so it would launch the untriaged child instead of
+// labelling it. A failed `epic:next` is either a network blip or a broken graph (a cycle, an
 // undeclared order, an unreadable child), and its exit code does not tell them apart — so a failure is
 // a `wait` that retries on the next pass, and `backlog:offer`'s consecutive-retry limit of them hands the
 // epic back too, rather than waiting out the idle budget on an anomaly nobody is shown.
@@ -21,6 +27,7 @@ const NO_RETRIES = 0
 const SUCCESS_EXIT_CODE = 0
 const FIRST_LINE = 0
 const WAIT: OfferRead = { verdict: 'wait', issues: [], retries: NO_RETRIES }
+const TRIAGE: OfferRead = { ...WAIT, verdict: epic_triage.TRIAGE_VERDICT }
 
 // `--lanes` lists every child a free lane could take, so one the loop already knows about is passed
 // over rather than standing in front of the rest. `undefined` is an answer that could not be read.
@@ -53,22 +60,31 @@ function child_offer(children: ReadonlyArray<string>, state: DriveState): OfferR
 	return child === undefined ? WAIT : { verdict: 'run', issues: [child], retries: NO_RETRIES }
 }
 
+// The answers only a judgment session can move.
+function judgment_offer(epic: string, token: string): OfferRead | undefined {
+	if (token === 'stop') return handed_back(epic)
+
+	return token === epic_triage.TRIAGE_VERDICT ? TRIAGE : undefined
+}
+
 async function answered_offer(
 	epic: string,
 	answers: ReadonlyArray<string>,
 	state: DriveState,
 	owner: string,
 ): Promise<OfferRead> {
-	const token = answers[FIRST_LINE]
+	const token = answers[FIRST_LINE] ?? ''
 
-	if (token !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) {
-		return child_offer(answers, state)
-	}
-
-	if (token === 'stop') return handed_back(epic)
+	if (issue_number_shape.ISSUE_NUMBER_PATTERN.test(token)) return child_offer(answers, state)
+	const judgment = judgment_offer(epic, token)
+	if (judgment !== undefined) return judgment
 
 	if (token === 'complete') {
-		await backlog_drive_named.mark_done(epic, { outcome: 'merged', code: 0, token: 'none' }, owner)
+		await backlog_drive_named.mark_done(
+			epic,
+			{ outcome: 'merged', code: 0, token: 'none', is_offer: true },
+			owner,
+		)
 	}
 
 	return WAIT

package/scripts/backlog/backlog-drive-launch.ts

@@ -33,6 +33,9 @@ async function launch(issue: string, owner: string): Promise<LaunchOutcome['kind
 
 	const outcome = await lane_launch_cli.launch_lane({ issue, stash: await latest_stash() })
 
+	// A refusal the driver waits out writes nothing else, so the lane's stage is ended here.
+	if (outcome.kind !== 'launched') await run_event_setup.emit(run_event_setup.STAGE.NO_CHILD)
+
 	return outcome.kind
 }
 

package/scripts/backlog/backlog-drive-named-offer.ts

@@ -10,6 +10,7 @@ import { backlog_budget } from './backlog-budget'
 import type { DriveState, OfferRead } from './backlog-drive'
 import { backlog_drive_epic } from './backlog-drive-epic'
 import { backlog_drive_named } from './backlog-drive-named'
+import { backlog_drive_unread } from './backlog-drive-unread'
 
 interface NamedContext {
 	is_only: boolean
@@ -67,12 +68,16 @@ async function classify(
 ): Promise<OfferRead> {
 	const result = await issue_state_cli.read_issue(issue)
 
-	if (result.kind !== 'state') return { verdict: 'issue-state', issues: [], retries: NO_RETRIES }
+	if (result.kind !== 'state') return backlog_drive_unread.offer(issue, result, state.retries)
 
 	const outcome = settled_outcome(result.state)
 
 	if (outcome !== undefined) {
-		await backlog_drive_named.mark_done(issue, { outcome, code: 0, token: 'none' }, owner)
+		await backlog_drive_named.mark_done(
+			issue,
+			{ outcome, code: 0, token: 'none', is_offer: true },
+			owner,
+		)
 
 		return { verdict: 'wait', issues: [], retries: NO_RETRIES }
 	}

package/scripts/backlog/backlog-drive-named.ts

@@ -55,7 +55,9 @@ function is_done(result: MergeResult): boolean {
 		return result.code === 0 && result.token !== MERGE_TOKEN.BUSY
 	}
 
-	return result.outcome === 'failed' && result.code === 0 && result.token !== MERGE_TOKEN.STOP
+	return (
+		result.outcome === 'failed' && result.code === 0 && !run_merge_token.is_control_stop(result)
+	)
 }
 
 function can_mark(carry: RunCarry, issue: string, owner: string): boolean {
@@ -125,7 +127,7 @@ async function reconcile(
 		const outcome = parked.has(issue) ? 'parked' : 'merged'
 
 		// eslint-disable-next-line no-await-in-loop -- each mark rewrites the same carry file
-		await mark_done(String(issue), { outcome, code: 0, token: 'none' }, owner)
+		await mark_done(String(issue), { outcome, code: 0, token: 'none', is_offer: true }, owner)
 	}
 }
 

package/scripts/backlog/backlog-drive-unread.ts

@@ -0,0 +1,56 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import type { StateRead } from '#scripts/issue/issue-state-cli'
+import type { OfferRead } from './backlog-drive'
+import { backlog_offer } from './backlog-offer'
+
+// **A named issue whose state did not read is asked again before a session hears of it.** The read is
+// one `gh` request, and a dropped connection fails it for a moment and no longer: handing that to a
+// session costs a wake that can only cut and hand the loop back. So the failure is a `wait` that reads
+// again on the next pass — the driver keeps collecting children meanwhile — and `backlog:offer`'s
+// consecutive-retry limit bounds it, the count `backlog-drive-epic.ts` advances for a failed `epic:next`.
+//
+// **What is handed back is `offer`, with the issue and the reason on stderr.** That is the row a session
+// already reads for an offer that produced nothing to start: report what stderr printed, pick no issue
+// by hand. A number that resolves to nothing is an answer rather than a gap, so it is not asked again.
+
+type UnreadState = Exclude<StateRead, { kind: 'state' }>
+
+const NO_RETRIES = 0
+// The loop's own word for an offer it could not use (`backlog-drive.ts` → `ask_offer`).
+const HANDED_BACK = 'offer'
+const UNKNOWN_REASON = 'unknown reason'
+
+function cause_of(read: UnreadState): string {
+	if (read.kind === 'missing') return 'the number does not resolve'
+	const status = read.status === undefined ? [] : [`status ${String(read.status)}`]
+
+	return [read.reason ?? UNKNOWN_REASON, ...status].join(', ')
+}
+
+function note_of(issue: string, read: UnreadState): string {
+	return `The state of named issue ${issue_cite.plain(issue)} could not be read (${cause_of(read)})`
+}
+
+function handed_back(note: string): OfferRead {
+	console.error(note)
+
+	return { verdict: HANDED_BACK, issues: [], retries: NO_RETRIES }
+}
+
+// `retries` is the count of consecutive failed offers before this one. A named epic's failed
+// `epic:next` advances it too, so the note counts offers, never state reads.
+function offer(issue: string, read: UnreadState, retries: number): OfferRead {
+	const note = note_of(issue, read)
+	if (read.kind === 'missing') return handed_back(`${note}; check the number and the repository.`)
+	const failures = retries + 1
+
+	if (failures >= backlog_offer.RETRY_LIMIT) {
+		return handed_back(`${note}; the offer failed ${String(failures)} times in a row.`)
+	}
+
+	console.error(`${note}; reading it again.`)
+
+	return { verdict: 'wait', issues: [], retries: failures }
+}
+
+export const backlog_drive_unread = { HANDED_BACK, offer }

package/scripts/backlog/backlog-drive.ts

@@ -26,10 +26,14 @@ const RUN_VERDICT = 'run'
 const STOP_VERDICT = 'stop'
 // How the loop reads each `run:merge` token — keyed by the producer's own type, so a token added there
 // is a type error here until it is classified. `hand-back` ends the loop at once: a hand-off, a person's
-// stop, the environment down, a foreign owner, an unreadable state. `stop` — a parked backlog or the
-// failure guard — is the offer's `stop` reached through a merge: the child is collected, nothing more
-// starts, and the children still in flight are collected before the loop ends. `await` is a cut resumed
-// in place: the same lane is awaited again.
+// stop, the environment down, a foreign owner, an unreadable state. `stop` — the failure guard, or a
+// failed child left unparked — collects the child, starts nothing more, and collects the children still
+// in flight before the loop ends. `await` is a cut resumed in place: the same lane is awaited again.
+//
+// **The offer `run:merge` passes through is never read here** (joshuafolkken/kit#3781): its `stop` —
+// only person-waiting issues left — is spelled like the control one, and acting on it ended the run
+// without the idle watch. The loop asks `backlog:offer` on the next pass instead, so whether a parked
+// backlog waits or ends is `backlog:budget`'s alone, after a merge as after any other pass.
 type TokenHandling = 'hand-back' | 'stop' | 'await'
 const TOKEN_HANDLING: Readonly<Record<MergeToken, TokenHandling>> = {
 	[MERGE_TOKEN.OVER]: 'hand-back',
@@ -61,6 +65,8 @@ const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
 ])
 const NO_RETRIES = 0
 const NO_FREE_LANES = 0
+const EXHAUSTED_ANSWER = 'exhausted'
+const JUDGE_REASON = 'judge'
 const LAUNCHED = 'launched'
 const UNOPENED = 'unopened'
 
@@ -94,7 +100,8 @@ interface DriveState {
 }
 
 interface DriveEnd {
-	// Why the loop handed control back: `merge`, `launch`, `offer`, `watch`, `stop`, `window` or a verdict.
+	// Why the loop handed control back: `merge`, `launch`, `offer`, `judge`, `watch`, `stop`, `window`
+	// or a verdict.
 	reason: string
 	// The token the parent reads, where one command printed it.
 	token: string | undefined
@@ -103,7 +110,7 @@ interface DriveEnd {
 	is_finish?: boolean | undefined
 }
 
-type Collected = Pick<MergeResult, 'token' | 'outcome'>
+type Collected = Pick<MergeResult, 'token' | 'outcome' | 'is_offer'>
 
 interface DrivePorts {
 	// Whether a child's process has confirmed-ended — `lane:await`'s re-confirmed check in production.
@@ -117,6 +124,9 @@ interface DrivePorts {
 	// The lanes free right now — `backlog_ready.drive_free_lane_count` in production, the limit less the
 	// open lanes.
 	free_lanes: () => Promise<number>
+	// How many open issues lacking `auto-ok` still owe a judgement — `auto_ok_judge_read.owed` in
+	// production, `0` when the read failed.
+	judgement_owed: () => Promise<number>
 	now: () => Date
 }
 
@@ -145,7 +155,7 @@ function ended(reason: string, state: DriveState, token?: string, issue?: string
 function is_drain(read: OfferRead, state: DriveState): boolean {
 	return (
 		read.verdict === WATCH_VERDICT &&
-		read.answer === 'exhausted' &&
+		read.answer === EXHAUSTED_ANSWER &&
 		state.in_flight.length === 0 &&
 		read.is_retrospective_owed === true
 	)
@@ -154,7 +164,7 @@ function is_drain(read: OfferRead, state: DriveState): boolean {
 function needs_retrospective(read: OfferRead, state: DriveState): boolean {
 	return (
 		read.verdict === STOP_VERDICT &&
-		read.answer === 'exhausted' &&
+		read.answer === EXHAUSTED_ANSWER &&
 		state.in_flight.length === 0 &&
 		read.is_retrospective_owed === true
 	)
@@ -209,15 +219,19 @@ function collected_state(
 // One finished child: handed back on an immediate token, otherwise collected.
 async function collect(issue: string, state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const collected = await ports.merge(issue)
-	const { token } = collected
+	const { token, is_offer } = collected
 
 	// An empty first line is a `run:merge` that failed before printing one: never read as a collection.
+	// An offer's `retry` is `backlog:next`'s transport answer, left to the next `backlog:offer`.
 	if (token === '') return ended('merge', state, undefined, issue)
-	if (IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
+	if (!is_offer && IMMEDIATE_TOKENS.has(token)) return ended('merge', state, token, issue)
 
 	const next = collected_state(issue, collected, state, ports.now().toISOString())
 
-	return { kind: 'continue', state: token === MERGE_TOKEN.STOP ? merge_stopped(issue, next) : next }
+	return {
+		kind: 'continue',
+		state: run_merge_token.is_control_stop(collected) ? merge_stopped(issue, next) : next,
+	}
 }
 
 async function collect_finished(state: DriveState, ports: DrivePorts): Promise<PassResult> {
@@ -310,6 +324,18 @@ function on_verdict(read: OfferRead, state: DriveState): PassResult {
 	return { kind: 'continue', state }
 }
 
+// **A free lane with nothing opted in is the open backlog's turn to be judged**
+// (joshuafolkken/kit#3854): a watch over an exhausted pool hands back `judge` while an open issue
+// lacking `auto-ok` still owes a judgement, ahead of the drain it would otherwise be. Once every one
+// carries its judgement comment the count is zero and the watch is the driver's again.
+async function is_judgement_owed(read: OfferRead, ports: DrivePorts): Promise<boolean> {
+	const is_exhausted = read.verdict === WATCH_VERDICT && read.answer === EXHAUSTED_ANSWER
+
+	if (!is_exhausted || (await ports.free_lanes()) <= NO_FREE_LANES) return false
+
+	return (await ports.judgement_owed()) > 0
+}
+
 async function ask_offer(state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const read = await ports.offer(state)
 
@@ -318,6 +344,7 @@ async function ask_offer(state: DriveState, ports: DrivePorts): Promise<PassResu
 	const next = { ...state, retries: read.retries }
 
 	if (read.verdict === RUN_VERDICT) return await launch_all(read.issues, next, ports)
+	if (await is_judgement_owed(read, ports)) return ended(JUDGE_REASON, next, JUDGE_REASON)
 
 	return on_verdict(read, next)
 }

package/scripts/backlog/backlog-overlap.ts

@@ -78,9 +78,8 @@ interface SeparateContext {
 	repo: string
 }
 
-// The path each running lane declares, mapped to the issue that holds it.
-function running_claims(declared: Declared, read: BusyRead): Map<string, number> {
-	const holders = read.kind === 'busy' ? read.issues.map((issue) => issue.number) : []
+// The path each of `holders` declares, mapped to the issue that holds it.
+function claims_of(declared: Declared, holders: ReadonlyArray<number>): Map<string, number> {
 	const pairs = holders.flatMap((number) =>
 		[...(declared.get(number) ?? [])].map((path): [string, number] => [path, number]),
 	)
@@ -88,6 +87,10 @@ function running_claims(declared: Declared, read: BusyRead): Map<string, number>
 	return new Map(pairs)
 }
 
+function running_claims(declared: Declared, read: BusyRead): Map<string, number> {
+	return claims_of(declared, read.kind === 'busy' ? read.issues.map((issue) => issue.number) : [])
+}
+
 function paths_of(child: EpicChild, declared: Declared, repo: string): ReadonlySet<string> {
 	if (child.repo !== repo) return new Set()
 
@@ -113,6 +116,20 @@ function clash_of(
 	return clashes[0]
 }
 
+// The running issues a candidate is weighed against, and the repository they are in.
+interface Holding {
+	holders: ReadonlyArray<number>
+	repo: string
+}
+
+// The path `child` declares that one of the running `holders` already declares — the clash `separate`
+// withholds a candidate on, for a reader that names the running issues itself (`run:board`).
+function running_clash(child: EpicChild, declared: Declared, holding: Holding): Clash | undefined {
+	const claims = claims_of(declared, holding.holders)
+
+	return clash_of(claims, paths_of(child, declared, holding.repo))
+}
+
 function clash_note(child: EpicChild, clash: Clash): string {
 	const waiting = session_cite.issue(child.number, undefined, child.repo)
 	const holder = session_cite.issue(clash.holder, undefined, child.repo)
@@ -172,7 +189,7 @@ function separate(
 	return { offered: walk.offered, withheld, ...(notice !== undefined && { notice }) }
 }
 
-const backlog_overlap = { declared_of, declared_paths, separate }
+const backlog_overlap = { declared_of, declared_paths, running_clash, separate }
 
 export { backlog_overlap }
-export type { Declared }
+export type { Clash, Declared }

package/scripts/backlog/backlog-ready.ts

@@ -25,9 +25,7 @@ interface ReadyPorts {
 
 // The lanes in use: the open worktrees an interruption has not stranded. `josh lane:limit` prints it.
 async function live_lane_count(): Promise<number> {
-	const lanes = await lane_registry.list_lanes()
-
-	return lanes.filter((lane) => !lane.is_stranded).length
+	return lane_registry.live_count(await lane_registry.list_lanes())
 }
 
 async function free_under(limit: number): Promise<number> {

package/scripts/backlog/backlogrun-args.ts

@@ -9,8 +9,12 @@ 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.
 
 const AGENT_FLAG = '--agent'
+const STOP_FLAG = '--stop'
 const BACKLOG_COMMAND = 'backlogrun'
 const ISSUE_PREFIX = '#'
 const FLAG_PREFIX = '-'
@@ -26,7 +30,8 @@ interface BacklogrunArguments {
 	issues: ReadonlyArray<number>
 }
 
-type ArgumentsResult = { kind: 'args'; args: BacklogrunArguments } | { kind: 'refused' }
+type ArgumentsResult =
+	{ kind: 'args'; args: BacklogrunArguments } | { kind: 'stop' } | { kind: 'refused' }
 
 interface AgentSplit {
 	agent: string | undefined
@@ -56,7 +61,7 @@ function normalized(rest: ReadonlyArray<string>): Array<string> {
 	return [...rest.slice(0, split_at).map((token) => issue_token(token)), ...rest.slice(split_at)]
 }
 
-function parse(argv: ReadonlyArray<string>): ArgumentsResult {
+function parse_start(argv: ReadonlyArray<string>): ArgumentsResult {
 	const { agent, rest } = split_agent(argv)
 	const provider = agent === undefined ? undefined : AGENTS[agent]
 	const invocation = run_invocation.rebuild([BACKLOG_COMMAND, ...normalized(rest)].join(' '))
@@ -68,6 +73,12 @@ function parse(argv: ReadonlyArray<string>): ArgumentsResult {
 	return { kind: 'args', args: { provider, invocation, issues } }
 }
 
+function parse(argv: ReadonlyArray<string>): ArgumentsResult {
+	if (!argv.includes(STOP_FLAG)) return parse_start(argv)
+
+	return { kind: argv.length === 1 ? 'stop' : 'refused' }
+}
+
 const backlogrun_args = { parse }
 
 export type { BacklogrunArguments }

package/scripts/backlog/backlogrun-cli.ts

@@ -1,27 +1,41 @@
 #!/usr/bin/env tsx
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import type { AgentProvider } from '#scripts/agent/agent-role-profile'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 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_launch, type LaunchTarget, type StartResult } from './backlogrun-launch'
+import { backlogrun_replace, type ReplaceVerdict } from './backlogrun-replace'
+import { backlogrun_stop, type StopReport } from './backlogrun-stop'
 
-// `josh backlogrun` — start a `backlogrun` from the terminal and watch it. A
+// `josh backlogrun` — start a `backlogrun` from the terminal and watch it, or stop it with `--stop`. 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
 // board closes only the board.
+//
+// **An idle run gives way to a different invocation.** A run watching with no child at work in a lane
+// is stopped as `--stop` stops it and the typed one is started in its place (`backlogrun-replace.ts`);
+// a run that is kept says why in one line above the board. The same invocation only shows the board,
+// so looking at a run never rebuilds it.
 
 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]'
+	'Usage: josh backlogrun [<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop'
 
 interface BacklogrunPorts {
 	repository_directory: () => Promise<string | undefined>
 	is_running: (git_directory: string) => boolean
+	replacement: (invocation: string, git_directory: string) => Promise<ReplaceVerdict>
 	start: (args: BacklogrunArguments, target: LaunchTarget) => StartResult
+	start_supervisor: (git_directory: string, provider: AgentProvider) => LaunchResult
+	stop: (git_directory: string) => Promise<StopReport>
 	show_board: () => Promise<number>
 	write: (line: string) => void
 }
@@ -29,7 +43,11 @@ interface BacklogrunPorts {
 const LIVE_PORTS: BacklogrunPorts = {
 	repository_directory: run_carry.repository_directory,
 	is_running: backlogrun_launch.is_running,
+	replacement: async (invocation, git_directory) =>
+		await backlogrun_replace.decide(invocation, git_directory),
 	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),
 	show_board: async () => await run_board_cli.run([]),
 	write: (line) => process.stdout.write(`${line}\n`),
 }
@@ -41,6 +59,12 @@ function running_notes(issues: ReadonlyArray<number>): Array<string> {
 	return ['backlogrun: a run is already going; showing its board.', ...guidance]
 }
 
+// Why a different invocation did not replace the run, ahead of the board. The same invocation is the
+// board reopened, and adds nothing.
+function kept_notes(verdict: ReplaceVerdict): Array<string> {
+	return verdict.kind === 'keep' ? [`backlogrun: not replacing the run — ${verdict.reason}`] : []
+}
+
 function launched_note(result: Extract<StartResult, { kind: 'launched' }>): string {
 	const { pid, session, log_path } = result.launched
 	const session_part = session === undefined ? '' : `, session ${session}`
@@ -48,22 +72,26 @@ function launched_note(result: Extract<StartResult, { kind: 'launched' }>): stri
 	return `backlogrun: started (pid ${String(pid)}${session_part}); log ${log_path}`
 }
 
+// **The supervisor is started here, beside the parent, never from the parent's own shell**: Claude
+// Code removes its token from what its Bash tool starts, so only this process can hand a token-only
+// credential on to the sessions the supervisor wakes (joshuafolkken/kit#3804). A supervisor that does
+// not start leaves the parent's own `run:wake --start` to try, so the run is still shown.
+function supervisor_note(result: LaunchResult): string {
+	if (result.kind === 'failed') return `backlogrun: could not start the supervisor: ${result.note}`
+
+	return `backlogrun: supervisor started (pid ${String(result.pid)})`
+}
+
 // The agent starts in the main checkout, the parent of the common git directory every record is keyed on.
 function target_of(git_directory: string): LaunchTarget {
 	return { worktree: path.dirname(git_directory), git_directory }
 }
 
-async function begin(
+async function launch(
 	args: BacklogrunArguments,
 	git_directory: string,
 	ports: BacklogrunPorts,
 ): Promise<number> {
-	if (ports.is_running(git_directory)) {
-		for (const note of running_notes(args.issues)) ports.write(note)
-
-		return await ports.show_board()
-	}
-
 	const result = ports.start(args, target_of(git_directory))
 
 	if (result.kind === 'failed') {
@@ -73,29 +101,73 @@ async function begin(
 	}
 
 	ports.write(launched_note(result))
+	ports.write(supervisor_note(ports.start_supervisor(git_directory, args.provider)))
+
+	return await ports.show_board()
+}
+
+// The idle run is stopped as `--stop` stops it, and a run left with an owner this command may not
+// signal is not replaced: nothing is started beside it.
+async function replace(
+	args: BacklogrunArguments,
+	git_directory: string,
+	ports: BacklogrunPorts,
+): Promise<number> {
+	ports.write(`backlogrun: replacing the idle run with \`${args.invocation}\``)
+
+	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
+
+	return await launch(args, git_directory, ports)
+}
+
+async function begin(
+	args: BacklogrunArguments,
+	git_directory: string,
+	ports: BacklogrunPorts,
+): Promise<number> {
+	if (!ports.is_running(git_directory)) return await launch(args, git_directory, ports)
+
+	const verdict = await ports.replacement(args.invocation, git_directory)
+
+	if (verdict.kind === 'replace') return await replace(args, git_directory, ports)
+
+	for (const note of [...kept_notes(verdict), ...running_notes(args.issues)]) ports.write(note)
 
 	return await ports.show_board()
 }
 
+// Stopping starts nothing and draws no board: the lines say what was stopped, and a run left with an
+// owner this command may not signal is a failure the exit code carries.
+async function stop(git_directory: string, ports: BacklogrunPorts): Promise<number> {
+	const report = await ports.stop(git_directory)
+
+	for (const line of backlogrun_stop.lines_of(report)) ports.write(line)
+
+	return backlogrun_stop.is_stopped(report) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+function refuse(line: string, ports: BacklogrunPorts): number {
+	ports.write(line)
+
+	return FAILURE_EXIT_CODE
+}
+
 async function run(
 	argv: ReadonlyArray<string>,
 	ports: BacklogrunPorts = LIVE_PORTS,
 ): Promise<number> {
 	const parsed = backlogrun_args.parse(argv)
 
-	if (parsed.kind === 'refused') {
-		ports.write(USAGE)
-
-		return FAILURE_EXIT_CODE
-	}
+	if (parsed.kind === 'refused') return refuse(USAGE, ports)
 
 	const git_directory = await ports.repository_directory()
 
-	if (git_directory === undefined) {
-		ports.write('backlogrun: not inside a git repository')
-
-		return FAILURE_EXIT_CODE
-	}
+	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)
 }