@joshuafolkken/kit 1.1387.0 → 1.1453.0

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

@@ -201,6 +201,7 @@ function stop_reason(stage: Stage, conflicts: ReadonlyArray<string> = []): strin
 }
 
 const run_ship_stage = {
+	CONFLICT,
 	PHASE,
 	STAGE,
 	clear,

package/scripts/run/wake/run-wake-await.ts

@@ -0,0 +1,130 @@
+import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
+import { poll } from '#scripts/lib/poll'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_wake, type RunWake } from './run-wake'
+import type { WakeContext } from './run-wake-describe'
+
+// How a supervisor claims the run it watches — including the one `josh backlogrun` starts beside the
+// parent it launched, before that parent has claimed the carry record (joshuafolkken/kit#3804).
+//
+// **That supervisor is started by the command, not by the parent's own shell.** Claude Code removes its
+// token from every process its Bash tool starts, so a supervisor the parent started there could not
+// authenticate the sessions it wakes wherever the token is the only credential. Started by the command,
+// it inherits the token — but before the parent has run `run:carry --begin`, so it waits for that record
+// while the launch that will write it is alive, and gives up once that launch is gone.
+//
+// **While a launch is pending, only a live owner's record is its parent's**: a dead owner's record is one
+// an earlier run left, and supervising it would wake that run beside the parent just launched.
+
+interface AwaitPorts {
+	read_carry: () => CarryRead
+	// The invocation of the launched parent that has not claimed the carry record yet, `undefined` once
+	// no such launch is alive.
+	pending_invocation: () => string | undefined
+	is_owner_live: (carry: RunCarry) => boolean
+	sleep: (milliseconds: number) => Promise<void>
+}
+
+type ClaimResult =
+	| { kind: 'claimed'; wake: RunWake; carry: RunCarry }
+	| { kind: 'running' }
+	| { kind: 'refused'; carry_kind: CarryRead['kind'] }
+
+function is_live_carry(read: CarryRead, ports: AwaitPorts): boolean {
+	return read.kind === 'carried' && ports.is_owner_live(read.carry)
+}
+
+// What the supervisor claims its record for: the live carried run, else the launch about to carry one,
+// else the carried run a supervisor started with no launch pending wakes.
+function supervised_invocation(ports: AwaitPorts): string | undefined {
+	const read = ports.read_carry()
+
+	if (read.kind !== 'carried') return ports.pending_invocation()
+	if (ports.is_owner_live(read.carry)) return read.carry.invocation
+
+	return ports.pending_invocation() ?? read.carry.invocation
+}
+
+// **The carry record is read once more after the launch is gone**, because a parent that wrote the
+// record and ended between the two reads still left a run to supervise.
+async function await_carry(ports: AwaitPorts, interval_ms: number): Promise<CarryRead> {
+	const read = ports.read_carry()
+
+	if (is_live_carry(read, ports)) return read
+	if (ports.pending_invocation() === undefined) return ports.read_carry()
+
+	await ports.sleep(interval_ms)
+
+	return await await_carry(ports, interval_ms)
+}
+
+function ports_of(context: WakeContext): AwaitPorts {
+	return {
+		read_carry: () => run_carry.read_carry(context.carry_target),
+		pending_invocation: () => backlogrun_launch.pending_launch(context.git_directory)?.invocation,
+		is_owner_live: (carry) => run_carry.is_owner_live(carry),
+		sleep: poll.sleep,
+	}
+}
+
+// The run the claim is held for: the one claimed for, or **a live run carried under another
+// invocation** — a person's own `run:carry --begin` landing before the launched parent's. That run's
+// `run:wake --start` found this supervisor live and answered `running`, so letting the claim go here
+// would leave it with nobody watching it.
+function supervised_carry(
+	read: CarryRead,
+	invocation: string,
+	ports: AwaitPorts,
+): RunCarry | undefined {
+	if (read.kind !== 'carried') return undefined
+	if (read.carry.invocation === invocation || ports.is_owner_live(read.carry)) return read.carry
+
+	return undefined
+}
+
+// **The record is re-pointed at the run it now supervises**, because the loop wakes sessions for the
+// record's invocation. **It carries the state a claim for that run would**, not the state the claim
+// inherited for the pending launch's invocation — that run's wakes are not this one's. A refused write
+// means the record is no longer this process's, which the loop's first pass reads as the stop it is.
+function held_for(
+	target: string,
+	wake: RunWake,
+	carry: RunCarry,
+	profile: AgentProfile,
+): ClaimResult {
+	if (carry.invocation === wake.invocation) return { kind: 'claimed', wake, carry }
+
+	const supervised = run_wake.fresh_wake(carry.invocation, new Date(), profile)
+
+	run_wake.update_wake(target, supervised)
+
+	return { kind: 'claimed', wake: supervised, carry }
+}
+
+// **The record is claimed before the carry record is awaited**, so the parent's own `run:wake --start`
+// finds this supervisor live and answers `running` rather than starting a second one beside it.
+// A parent that ends without carrying a run leaves nothing to supervise, and the claim is let go.
+async function claim_run(
+	context: WakeContext,
+	profile: AgentProfile,
+	interval_ms: number,
+	ports: AwaitPorts = ports_of(context),
+): Promise<ClaimResult> {
+	const invocation = supervised_invocation(ports)
+	if (invocation === undefined) return { kind: 'refused', carry_kind: ports.read_carry().kind }
+	const wake = run_wake.claim(context.wake_target, invocation, new Date(), profile)
+	if (wake === undefined) return { kind: 'running' }
+	const read = await await_carry(ports, interval_ms)
+	const carry = supervised_carry(read, invocation, ports)
+	if (carry !== undefined) return held_for(context.wake_target, wake, carry, profile)
+
+	run_wake.tidy_own_wake(context.wake_target)
+
+	return { kind: 'refused', carry_kind: read.kind }
+}
+
+const run_wake_await = { await_carry, claim_run, supervised_invocation }
+
+export type { AwaitPorts, ClaimResult }
+export { run_wake_await }

package/scripts/run/wake/run-wake-cli.ts

@@ -1,25 +1,25 @@
 #!/usr/bin/env tsx
 import { randomUUID } from 'node:crypto'
-import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import type { AgentProfile, AgentProvider } from '#scripts/agent/agent-role-profile'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { poll } from '#scripts/lib/poll'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
-import { run_carry_ended } from '#scripts/run/carry/run-carry-ended'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_headless } from '#scripts/run/run-headless'
 import { run_stranded_detect, type WatchedRun } from '#scripts/run/run-stranded-detect'
-import { run_wake, type RunWake, type WakeStopReason, type WakeTidyResult } from './run-wake'
+import { run_wake, type WakeStopReason, type WakeTidyResult } from './run-wake'
+import { run_wake_await } from './run-wake-await'
 import { run_wake_describe, type WakeContext } from './run-wake-describe'
 import { run_wake_driver } from './run-wake-driver'
 import { run_wake_handoff } from './run-wake-handoff'
 import { run_wake_loop, type LoopPorts, type LoopStop } from './run-wake-loop'
-import { run_wake_restart, type RestartPorts } from './run-wake-restart'
 import { run_wake_session, type LaunchResult } from './run-wake-session'
+import { run_wake_stop } from './run-wake-stop'
+import { run_wake_supervise } from './run-wake-supervise'
 
 // `josh run:wake --start | --list | --stop | --loop` — the supervisor that continues a cut
 // `backlogrun` or `queue` without a person retyping the keyword. **Which invocations it may continue
@@ -86,6 +86,7 @@ const STOP_BODIES: Record<WakeStopReason, string | undefined> = {
 	unreadable:
 		'The carry record could not be read, so the supervisor stopped rather than guess at it.',
 }
+const NO_PROFILE_NOTE = 'the scheduler profile could not be resolved'
 const SUPERSEDED_RESULT: WakeTidyResult = 'superseded'
 const SUPERSEDED_NOTE =
 	'another supervisor now holds the record, so it was left alone; this loop is the superseded one'
@@ -134,26 +135,14 @@ function group_count(values: ParsedValues): number {
 	return verbs.filter((flag) => flag === true).length
 }
 
+function context_of(directory: string): WakeContext {
+	return run_wake_describe.context_of(directory, note_to_stderr)
+}
+
 async function resolve_context(): Promise<WakeContext | undefined> {
 	const directory = await run_carry.repository_directory()
 
-	if (directory === undefined) return undefined
-
-	const log_target = run_wake.wake_log_path(directory)
-
-	// Every verb reaches this one function, so creating the log here is what makes the path each of
-	// them prints a path that exists — including `--list` and the already-running branch of `--start`,
-	// neither of which launches anything.
-	run_wake_session.ensure_log(log_target, note_to_stderr)
-
-	return {
-		carry_target: run_carry.carry_path(directory),
-		ended_target: run_carry_ended.ended_path(directory),
-		wake_target: run_wake.wake_path(directory),
-		log_target,
-		event_target: run_event_stream.target_of(directory),
-		worktree: path.dirname(directory),
-	}
+	return directory === undefined ? undefined : context_of(directory)
 }
 
 // There is nothing to supervise unless a run is actually carrying a budget. Refusing here rather than
@@ -165,6 +154,12 @@ function refuse_without_carry(kind: CarryRead['kind']): number {
 	return report(NONE_VERDICT, FAILURE_EXIT_CODE)
 }
 
+// **A session that started is said on the stream.** The driver's `waiting on judgment` is the moment it
+// asked; from here a session is at work on the answer, until the supervisor's next hand-off.
+function say_session_running(context: WakeContext): void {
+	run_event_setup.emit_to(context.event_target, run_event_setup.STAGE.SESSION, new Date())
+}
+
 function wake_session(
 	context: WakeContext,
 	invocation: string,
@@ -180,8 +175,11 @@ function wake_session(
 	// under `claude -p` a turn-end is the process's end (`run-headless.ts`).
 	const environment = run_headless.environment()
 	const target = { cwd: context.worktree, env: environment, log_path: context.log_target }
+	const result = run_wake_session.launch({ argv: built.argv, ...target, profile }, note_to_stderr)
 
-	return run_wake_session.launch({ argv: built.argv, ...target, profile }, note_to_stderr)
+	if (result.kind === 'launched') say_session_running(context)
+
+	return result
 }
 
 // **A record this supervisor owns itself is not a session at work.** A failed driver leaves the record
@@ -287,14 +285,18 @@ async function finish(stop: LoopStop, context: WakeContext, started_at: string):
 	return report(stop.reason, exit_code_of(stop.reason))
 }
 
-function spawn_supervisor(context: WakeContext, interval: string | undefined): number {
-	const profile = run_wake_session.scheduler_profile()
-	if (profile === undefined) return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
+function launch_supervisor(
+	context: WakeContext,
+	interval: string | undefined,
+	profile: AgentProfile | undefined,
+): LaunchResult {
+	if (profile === undefined) return { kind: 'failed', note: NO_PROFILE_NOTE }
 	const argv = run_wake_session.supervisor_argv(SCRIPT_PATH, interval)
+
 	// **The supervisor's own output goes to the same file as the sessions it starts.** It is detached
 	// with the same call, so otherwise its `console.error` — the launch note that says the agent CLI is
 	// not on `PATH`, and the stop note behind every warning — would go nowhere at all.
-	const result = run_wake_session.launch(
+	return run_wake_session.launch(
 		{
 			argv,
 			cwd: context.worktree,
@@ -303,6 +305,20 @@ function spawn_supervisor(context: WakeContext, interval: string | undefined): n
 		},
 		note_to_stderr,
 	)
+}
+
+// The supervisor `josh backlogrun` starts beside its launched parent, on the parent's provider, from its
+// own process so it inherits the credential the parent's Bash tool does not pass on (kit#3804). No carry
+// record stands yet, so `start`'s check is skipped; its `--loop` waits for the parent to claim one.
+function start_for_launch(git_directory: string, provider: AgentProvider): LaunchResult {
+	const resolved = run_wake_session.chosen_profile(provider)
+	if (resolved.kind === 'rejected') return { kind: 'failed', note: resolved.note }
+
+	return launch_supervisor(context_of(git_directory), undefined, resolved.profile)
+}
+
+function spawn_supervisor(context: WakeContext, interval: string | undefined): number {
+	const result = launch_supervisor(context, interval, run_wake_session.scheduler_profile())
 
 	if (result.kind === 'failed') {
 		console.error(`Could not start the supervisor: ${result.note}`)
@@ -345,40 +361,32 @@ function tidy_up(target: string): void {
 	if (run_wake.tidy_own_wake(target) === SUPERSEDED_RESULT) note_to_stderr(SUPERSEDED_NOTE)
 }
 
-function restart_ports(context: WakeContext, ports: LoopPorts, interval_ms: number): RestartPorts {
-	return {
-		pass: async () => await run_wake_loop.run_loop(context.wake_target, ports, interval_ms),
-		is_resumable: () => run_carry.read_carry(context.carry_target).kind === 'carried',
-		pause: async () => {
-			await poll.sleep(interval_ms)
-		},
-		note: note_to_stderr,
-	}
-}
-
 // A failed pass is restarted while the carry record is still resumable (`run-wake-restart.ts`), so
-// only a failure past the restart bound reaches `finish` and its warning.
+// only a failure past the restart bound reaches `finish` and its warning; the Claude lanes are brokered
+// for as long as it supervises (`run-wake-supervise.ts`).
 // **The record is claimed once and held across every restart**, so a `--stop` landing in the pause
 // between two passes still finds it, signals this process, and the next pass reads the removal as the
 // person's stop rather than claiming a fresh record and resuming.
 async function loop(context: WakeContext, interval_ms: number): Promise<number> {
-	const read = run_carry.read_carry(context.carry_target)
-
-	if (read.kind !== 'carried') return refuse_without_carry(read.kind)
-
 	const profile = run_wake_session.scheduler_profile()
 	if (profile === undefined) return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
 
-	const claimed = run_wake.claim(context.wake_target, read.carry.invocation, new Date(), profile)
+	const claimed = await run_wake_await.claim_run(context, profile, interval_ms)
 
-	if (claimed === undefined) return report(RUNNING_VERDICT)
+	if (claimed.kind === 'running') return report(RUNNING_VERDICT)
+	if (claimed.kind === 'refused') return refuse_without_carry(claimed.carry_kind)
 
-	const ports = ports_for(context, claimed.profile ?? profile)
-	const stop = await run_wake_restart.supervise(restart_ports(context, ports, interval_ms))
+	const ports = ports_for(context, claimed.wake.profile ?? profile)
+	const stop = await run_wake_supervise.supervise({
+		context,
+		ports,
+		interval_ms,
+		note: note_to_stderr,
+	})
 
 	tidy_up(context.wake_target)
 
-	return await finish(stop, context, read.carry.started_at)
+	return await finish(stop, context, claimed.carry.started_at)
 }
 
 // **The verdict tracks whether the supervisor is actually running, not merely whether a record is
@@ -394,30 +402,10 @@ function list(context: WakeContext): number {
 	return report(run_wake.is_supervisor_live(wake) ? SUPERVISING_VERDICT : STALE_VERDICT)
 }
 
-// **Removing the record is the stop; the signal only shortens the wait.** A pid already gone, or one
-// this process may not signal, is not an error — the loop ends at its next pass either way, because it
-// re-reads the record it no longer finds and `run_wake.update_wake` refuses to write one back.
-function signal_supervisor(wake: RunWake): void {
-	if (!run_wake.is_supervisor_live(wake)) return
-
-	try {
-		process.kill(wake.pid, 'SIGTERM')
-	} catch {
-		console.error(
-			`Process ${String(wake.pid)} could not be signalled; the record is removed regardless.`,
-		)
-	}
-}
-
 function stop_supervisor(context: WakeContext): number {
-	const wake = run_wake.read_wake(context.wake_target)
-
-	if (wake === undefined) return report(NONE_VERDICT)
-
-	run_wake.remove_wake(context.wake_target)
-	signal_supervisor(wake)
+	const stopped = run_wake_stop.stop(context.wake_target)
 
-	return report(STOPPED_VERDICT)
+	return report(stopped === undefined ? NONE_VERDICT : STOPPED_VERDICT)
 }
 
 async function dispatch(
@@ -465,6 +453,7 @@ const run_wake_cli = {
 	ports_for,
 	record_failure,
 	run,
+	start_for_launch,
 	stop_body,
 	warning_body,
 }

package/scripts/run/wake/run-wake-describe.ts

@@ -1,17 +1,22 @@
+import path from 'node:path'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_ended } from '#scripts/run/carry/run-carry-ended'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_liveness } from '#scripts/run/run-liveness'
 import { run_wake, type RunWake, type WakeDecision, type WakeDecisionInput } from './run-wake'
+import { run_wake_session } from './run-wake-session'
 
 // The `--list` presentation of a wake record. What the command *does* stays in `run-wake-cli.ts`; how
 // a supervisor's record reads back to a person lives here, one cohesive block.
 
 const UNKNOWN_CUTS = 'an unreadable number of'
 const REPO_LOOKUP_TIMEOUT_MS = 10_000
-const STOP_COMMAND = 'pnpm josh run:wake --stop'
+// The whole run, not the supervisor alone: `run:wake --stop` leaves the run's record behind, and a
+// record with no owner is what the next `josh backlogrun` stands on without starting.
+const STOP_COMMAND = 'pnpm josh backlogrun --stop'
 const UNREADABLE_TIME = 'an unreadable time'
 
 // The three paths every verb needs: the carry record it reads, its own record, and the work tree a
@@ -30,6 +35,8 @@ interface WakeContext {
 	// side uses. `--list` relays the newest event from here: the report surface belongs to the run, and
 	// `--list` is the degenerate last-event read of the same stream the attached session follows.
 	event_target: string
+	// The common git directory every record is keyed on — what finds the launch `josh backlogrun` made.
+	git_directory: string
 	worktree: string
 }
 
@@ -156,7 +163,32 @@ function describe_wake_cited(wake: RunWake, context: WakeContext): string {
 	return cite_description(describe_wake(wake, context), repo)
 }
 
-const run_wake_describe = { STOP_COMMAND, cite_description, describe_wake, describe_wake_cited }
+function context_of(directory: string, note: (line: string) => void): WakeContext {
+	const log_target = run_wake.wake_log_path(directory)
+
+	// Every verb reaches this one function, so creating the log here is what makes the path each of
+	// them prints a path that exists — including `--list` and the already-running branch of `--start`,
+	// neither of which launches anything.
+	run_wake_session.ensure_log(log_target, note)
+
+	return {
+		carry_target: run_carry.carry_path(directory),
+		ended_target: run_carry_ended.ended_path(directory),
+		wake_target: run_wake.wake_path(directory),
+		log_target,
+		event_target: run_event_stream.target_of(directory),
+		git_directory: directory,
+		worktree: path.dirname(directory),
+	}
+}
+
+const run_wake_describe = {
+	STOP_COMMAND,
+	cite_description,
+	context_of,
+	describe_wake,
+	describe_wake_cited,
+}
 
 export type { WakeContext }
 export { run_wake_describe }

package/scripts/run/wake/run-wake-driver.ts

@@ -184,6 +184,15 @@ async function run_driver(
 	return await run_driver(target, args, wait, remaining - 1)
 }
 
+// **A result handed to a session is said on the stream first.** The driver has stopped asking, so
+// without it the board keeps the `handing off` this pass wrote and a run waiting on a session's
+// judgment reads as one still getting ready.
+async function announced(result: DriveResult): Promise<DriveResult> {
+	if (result.kind === 'judgment') await run_event_setup.emit(run_event_setup.STAGE.JUDGING)
+
+	return result
+}
+
 async function drive(target: string, wait: Pause = pause): Promise<DriveResult> {
 	const read = run_carry.read_carry(target)
 	if (read.kind !== 'carried') return { kind: 'failed', note: 'The carry record changed.' }
@@ -197,10 +206,8 @@ async function drive(target: string, wait: Pause = pause): Promise<DriveResult>
 
 	await run_event_setup.emit(run_event_setup.STAGE.HANDING_OFF)
 
-	return read_result(
-		await run_driver(target, args, wait, RERUN_LIMIT),
-		target,
-		read.carry.invocation,
+	return await announced(
+		read_result(await run_driver(target, args, wait, RERUN_LIMIT), target, read.carry.invocation),
 	)
 }
 

package/scripts/run/wake/run-wake-session.ts

@@ -1,6 +1,12 @@
 import { agent_argv, type AgentArgvResult } from '#scripts/agent/agent-argv'
-import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import {
+	agent_role_profile,
+	type AgentProfile,
+	type AgentProvider,
+	type ProfileResult,
+} from '#scripts/agent/agent-role-profile'
 import { claude_agent_argv } from '#scripts/agent/claude-agent-argv'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
 import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 import { run_invocation } from '#scripts/run/run-invocation'
 
@@ -46,10 +52,20 @@ function scheduler_profile(): AgentProfile | undefined {
 	return undefined
 }
 
-function supervisor_environment(profile: AgentProfile): Record<string, string> {
+// The scheduler profile of the provider a run was started on, whatever session the command was typed in
+// (joshuafolkken/kit#3804).
+function chosen_profile(provider: AgentProvider): ProfileResult {
+	const environment = backlogrun_launch.chosen_environment(provider)
+
+	return agent_role_profile.resolve(agent_role_profile.SCHEDULER, environment)
+}
+
+// **A Claude supervisor clears an inherited Codex session key**, so one started from a command typed in
+// a Codex session does not read itself as both.
+function supervisor_environment(profile: AgentProfile): Record<string, string | undefined> {
 	return profile.provider === 'openai'
 		? { CODEX_THREAD_ID: SUPERVISOR_SESSION }
-		: { CLAUDE_CODE_CHILD_SESSION: SUPERVISOR_SESSION }
+		: { CLAUDE_CODE_CHILD_SESSION: SUPERVISOR_SESSION, CODEX_THREAD_ID: undefined }
 }
 
 // **What comes back is always the rebuilt text, and it is refused unless it matches the record.** The
@@ -149,6 +165,7 @@ const run_wake_session = {
 	ensure_log: detached_launch.ensure_log,
 	is_safe_argv: detached_launch.is_safe_argv,
 	launch: detached_launch.launch,
+	chosen_profile,
 	scheduler_profile,
 	supervisor_argv,
 	supervisor_environment,

package/scripts/run/wake/run-wake-stop.ts

@@ -0,0 +1,37 @@
+import { run_wake, type RunWake } from './run-wake'
+
+// Stopping the supervisor, apart from the command that prints the verdict: `run:wake --stop` and
+// `josh backlogrun --stop` both stop it here, so the one stop is never written twice.
+
+// **Removing the record is the stop; the signal only shortens the wait.** A pid already gone, or one
+// this process may not signal, is not an error — the loop ends at its next pass either way, because it
+// re-reads the record it no longer finds and `run_wake.update_wake` refuses to write one back.
+function signal(pid: number): void {
+	try {
+		process.kill(pid, 'SIGTERM')
+	} catch {
+		console.error(
+			`Process ${String(pid)} could not be signalled; the record is removed regardless.`,
+		)
+	}
+}
+
+function signal_supervisor(wake: RunWake): void {
+	if (run_wake.is_supervisor_live(wake)) signal(wake.pid)
+}
+
+// The record that was stopped, `undefined` where there was none to stop.
+function stop(wake_target: string): RunWake | undefined {
+	const wake = run_wake.read_wake(wake_target)
+
+	if (wake === undefined) return undefined
+
+	run_wake.remove_wake(wake_target)
+	signal_supervisor(wake)
+
+	return wake
+}
+
+const run_wake_stop = { signal, stop }
+
+export { run_wake_stop }

package/scripts/run/wake/run-wake-supervise.ts

@@ -0,0 +1,44 @@
+import { claude_lane_broker } from '#scripts/lane/claude-lane-broker'
+import { poll } from '#scripts/lib/poll'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import type { WakeContext } from './run-wake-describe'
+import { run_wake_loop, type LoopPorts, type LoopStop } from './run-wake-loop'
+import { run_wake_restart, type RestartPorts } from './run-wake-restart'
+
+// The supervisor's whole life: the restarting loop (`run-wake-restart.ts`), with the Claude lanes
+// brokered beside it.
+//
+// **The lanes are brokered for the supervisor's life, not one drive's**: a lane's ship asks for its
+// reviewer or its relaunch whenever it gets there, a hand-back to a session included, and only this
+// process holds the token those sessions sign in with (joshuafolkken/kit#3817, `claude-lane-broker.ts`).
+
+interface SuperviseTarget {
+	context: WakeContext
+	ports: LoopPorts
+	interval_ms: number
+	note: (text: string) => void
+}
+
+function restart_ports(target: SuperviseTarget): RestartPorts {
+	const { context, ports, interval_ms } = target
+
+	return {
+		pass: async () => await run_wake_loop.run_loop(context.wake_target, ports, interval_ms),
+		is_resumable: () => run_carry.read_carry(context.carry_target).kind === 'carried',
+		pause: async () => {
+			await poll.sleep(interval_ms)
+		},
+		note: target.note,
+	}
+}
+
+async function supervise(target: SuperviseTarget): Promise<LoopStop> {
+	return await claude_lane_broker.serve_during(
+		async () => await run_wake_restart.supervise(restart_ports(target)),
+	)
+}
+
+const run_wake_supervise = { supervise }
+
+export { run_wake_supervise }
+export type { SuperviseTarget }