@joshuafolkken/kit 1.1383.0 → 1.1435.0

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)
 }

package/scripts/backlog/backlogrun-launch.ts

@@ -11,6 +11,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { run_headless } from '#scripts/run/run-headless'
 import { z } from 'zod'
 
@@ -34,10 +35,20 @@ const launch_schema = z.object({
 	pid: z.number(),
 	start: z.string().optional(),
 	session: z.string().optional(),
+	// What the parent was started to run and when, so `run:board` has a run to draw and a clock to count
+	// before the parent claims the carry record. Absent on a record an earlier version wrote.
+	invocation: z.string().optional(),
+	started_at: z.string().optional(),
 })
 
 type LaunchRecord = z.infer<typeof launch_schema>
 
+// A launched run the parent has not claimed yet, as far as its record says.
+interface PendingLaunch {
+	invocation: string
+	started_at: string
+}
+
 interface LaunchTarget {
 	// The checkout the parent runs in, and its common git directory the records are keyed on.
 	worktree: string
@@ -117,10 +128,71 @@ function note_to_stderr(note: string): void {
 	console.error(`backlogrun: ${note}`)
 }
 
-function record_launch(git_directory: string, pid: number, session: string | undefined): void {
-	const started = process_identity.read_start(pid)
+// **The record and the run's first stage carry one moment**, so the `starting session` event is never
+// dated before the start the board measures from.
+function record_launch(
+	git_directory: string,
+	launch: Pick<LaunchRecord, 'pid' | 'session' | 'invocation'>,
+): void {
+	const now = new Date()
+	const identity = process_identity.read_start(launch.pid)
+	const record: LaunchRecord = { ...launch, start: identity, started_at: now.toISOString() }
+
+	stamp_file.replace_stamp(launch_path(git_directory), record)
+	run_event_setup.emit_in(git_directory, run_event_setup.STAGE.STARTING, now)
+}
+
+// The live launch record here, `undefined` once the parent it names is gone.
+function live_launch(git_directory: string): LaunchRecord | undefined {
+	const record = read_launch(launch_path(git_directory))
+
+	return is_launch_live(record) ? record : undefined
+}
+
+// The launch `run:board` draws while no carry record stands: one whose record says what it runs and
+// since when.
+function pending_launch(git_directory: string): PendingLaunch | undefined {
+	const { invocation, started_at } = live_launch(git_directory) ?? {}
+
+	if (invocation === undefined || started_at === undefined) return undefined
+
+	return { invocation, started_at }
+}
+
+// When the launch that started `owner_pid` began, for `run:carry --begin` to start the run's clock
+// from: **only the parent this launch started inherits it**, so a run typed inside a session — which has
+// no launch record, or another parent's — still starts at its own `--begin`.
+function started_for(git_directory: string, owner_pid: number | undefined): Date | undefined {
+	const record = live_launch(git_directory)
+
+	if (record?.started_at === undefined || record.pid !== owner_pid) return undefined
+
+	const started_ms = Date.parse(record.started_at)
+
+	return Number.isNaN(started_ms) ? undefined : new Date(started_ms)
+}
+
+function signal_parent(pid: number): void {
+	try {
+		process.kill(pid, 'SIGTERM')
+	} catch {
+		note_to_stderr(`process ${String(pid)} could not be signalled; its launch record is removed.`)
+	}
+}
+
+// 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.
+function stop_parent(git_directory: string): number | undefined {
+	const record = live_launch(git_directory)
+
+	stamp_file.remove_stamp(launch_path(git_directory))
+
+	if (record === undefined) return undefined
+
+	signal_parent(record.pid)
 
-	stamp_file.replace_stamp(launch_path(git_directory), { pid, start: started, session })
+	return record.pid
 }
 
 // The headless mark holds the parent's turn open while its lanes run, as `run:wake`'s does. The launch
@@ -160,7 +232,7 @@ function start(invocation: string, provider: AgentProvider, target: LaunchTarget
 
 	if (result.kind === 'failed') return result
 
-	record_launch(target.git_directory, result.pid, session)
+	record_launch(target.git_directory, { pid: result.pid, session, invocation })
 
 	const launched = { pid: result.pid, session, log_path: log_path(target.git_directory) }
 
@@ -171,8 +243,11 @@ const backlogrun_launch = {
 	argv_of,
 	chosen_environment,
 	is_running,
+	pending_launch,
 	start,
+	started_for,
+	stop_parent,
 }
 
-export type { Launched, LaunchTarget, StartResult }
+export type { Launched, LaunchTarget, PendingLaunch, StartResult }
 export { backlogrun_launch }

package/scripts/backlog/backlogrun-replace.ts

@@ -0,0 +1,166 @@
+import { lane_spent, type LaneUse } from '#scripts/lane/lane-spent'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+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 { backlog_drive_retrospective } from './backlog-drive-retrospective'
+import { backlogrun_launch } from './backlogrun-launch'
+
+// Whether `josh backlogrun` may replace the run already going with the one just typed. A run that
+// drained its backlog keeps watching for hours with nothing in flight, and starting another meant typing
+// `--stop` first; this is the test that lets the start do both.
+//
+// **A different invocation, a watching run, no lane in use — all three.** The same invocation is how a
+// person reopens the board, so it never rebuilds the run. A run still starting is opening a lane, and a
+// child killed mid-change leaves a tree nobody can resume, so only a run past its drain is replaced.
+//
+// **Only a lane a child is working in keeps the run.** A lane a past run left behind has nobody in it;
+// counted as open, it kept every later invocation from replacing the run (`lane-spent.ts`).
+//
+// **A drain that still owes the retrospective is not the watch.** The drain is marked before the
+// end-of-run retrospective runs, so a run owing one has a session at work on it; stopping that session
+// loses the retrospective with the record, and the run is kept until it has run.
+//
+// **An undetermined run is not replaced.** A record or a scope that cannot be read answers `keep`, the
+// side that keeps the run.
+//
+// **A launch its parent has not claimed yet is still starting, not unreadable.** No carry record stands
+// then, so the invocation is read from the launch record: the same one is the board reopened, and any
+// other is kept as a run that has not written its record yet.
+//
+// **A kept run says why.** Every `keep` carries the one condition that held it, because a board shown
+// with no word looked the same whichever of them it was.
+
+const KIND = run_event_stream.EVENT_KIND
+const NOT_FOUND = -1
+const ISSUE_PREFIX = '#'
+const UNREADABLE_REASON = "the run's record could not be read"
+const UNCLAIMED_REASON = 'the run is still starting: it has not written its record yet'
+const WORKING_LANE = 'a child is still working in the lane for'
+const UNREAD_LANE = 'whether a child is working could not be read in the lane for'
+const LANE_WAY_OUT = '(`pnpm josh lane:close <N>` discards a lane)'
+const RETROSPECTIVE_REASON = 'the run still owes its retrospective'
+const WORKING_REASON = 'the run is not watching: it is still starting or has a child at work'
+
+// `same` is the board reopened, which is kept without a word; `keep` is a refusal, and says why.
+type ReplaceVerdict = { kind: 'replace' } | { kind: 'same' } | { kind: 'keep'; reason: string }
+
+const REPLACE: ReplaceVerdict = { kind: 'replace' }
+const SAME: ReplaceVerdict = { kind: 'same' }
+
+interface ReplacePorts {
+	read_carry: (git_directory: string) => CarryRead
+	events: (git_directory: string) => ReadonlyArray<RunEvent>
+	is_retrospective_owed: (carry: RunCarry) => boolean
+	// The invocation of a launch whose parent has not claimed the record yet.
+	pending_invocation: (git_directory: string) => string | undefined
+	// The lanes in use: a child working in one, or a probe that did not answer.
+	lanes: () => Promise<LaneUse>
+}
+
+const LIVE_PORTS: ReplacePorts = {
+	read_carry: (git_directory) => run_carry.read_carry(run_carry.carry_path(git_directory)),
+	events: (git_directory) =>
+		run_event_stream.read_events(run_event_stream.target_of(git_directory)),
+	is_retrospective_owed: backlog_drive_retrospective.is_owed,
+	pending_invocation: (git_directory) =>
+		backlogrun_launch.pending_launch(git_directory)?.invocation,
+	lanes: async () => await lane_spent.lanes_in_use(),
+}
+
+function keep(reason: string): ReplaceVerdict {
+	return { kind: 'keep', reason }
+}
+
+// What the record alone settles, or `undefined` for a different invocation that owes nothing.
+function record_verdict(
+	invocation: string,
+	read: CarryRead,
+	ports: ReplacePorts,
+): ReplaceVerdict | undefined {
+	if (read.kind !== 'carried') return keep(UNREADABLE_REASON)
+	if (read.carry.invocation === invocation) return SAME
+
+	return ports.is_retrospective_owed(read.carry) ? keep(RETROSPECTIVE_REASON) : undefined
+}
+
+// A launch with no carry record yet, answered from the launch record.
+function unclaimed_verdict(pending: string | undefined, invocation: string): ReplaceVerdict {
+	return pending === invocation ? SAME : keep(UNCLAIMED_REASON)
+}
+
+// Watching is the run's newest drain with no launch after it: a child the watch woke for ends it.
+function is_watching(scoped: ReadonlyArray<RunEvent>): boolean {
+	const drained_at = scoped.findLastIndex((event) => event.kind === KIND.DRAIN)
+
+	if (drained_at === NOT_FOUND) return false
+
+	return scoped.slice(drained_at).every((event) => event.kind !== KIND.CHILD_LAUNCH)
+}
+
+function watch_verdict(
+	git_directory: string,
+	read: CarryRead,
+	ports: ReplacePorts,
+): ReplaceVerdict {
+	const events = ports.events(git_directory)
+	const scoped = run_event_scope.scoped_events(events, run_event_scope.scope_of(read))
+
+	if (scoped === undefined) return keep(UNREADABLE_REASON)
+
+	return is_watching(scoped) ? REPLACE : keep(WORKING_REASON)
+}
+
+function named(lead: string, issues: ReadonlyArray<string>): Array<string> {
+	if (issues.length === 0) return []
+
+	const cited = issues.map((issue) => `${ISSUE_PREFIX}${issue}`).join(' ')
+
+	return [`${lead} ${cited}`]
+}
+
+// The lanes are named with the command that discards one, the only way past a child that will not end —
+// and a probe that did not answer is said as that, because the close takes a lane's uncommitted work.
+function lane_reason(use: LaneUse): string {
+	const parts = [...named(WORKING_LANE, use.working), ...named(UNREAD_LANE, use.unread)]
+
+	return `${parts.join('; ')} ${LANE_WAY_OUT}`
+}
+
+function is_free(use: LaneUse): boolean {
+	return use.working.length === 0 && use.unread.length === 0
+}
+
+async function claimed_verdict(
+	invocation: string,
+	git_directory: string,
+	read: CarryRead,
+	ports: ReplacePorts,
+): Promise<ReplaceVerdict> {
+	const settled =
+		record_verdict(invocation, read, ports) ?? watch_verdict(git_directory, read, ports)
+
+	if (settled.kind !== 'replace') return settled
+
+	const use = await ports.lanes()
+
+	return is_free(use) ? REPLACE : keep(lane_reason(use))
+}
+
+async function decide(
+	invocation: string,
+	git_directory: string,
+	ports: ReplacePorts = LIVE_PORTS,
+): Promise<ReplaceVerdict> {
+	const read = ports.read_carry(git_directory)
+
+	if (read.kind === 'none') {
+		return unclaimed_verdict(ports.pending_invocation(git_directory), invocation)
+	}
+
+	return await claimed_verdict(invocation, git_directory, read, ports)
+}
+
+const backlogrun_replace = { decide }
+
+export type { ReplacePorts, ReplaceVerdict }
+export { backlogrun_replace }