@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,25 +1,23 @@
-#!/usr/bin/env tsx
-import { randomUUID } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import type { AgentProfile, AgentProvider } from '#scripts/agent/agent-role-profile'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
+import { lane_session_broker } from '#scripts/lane/lane-session-broker'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { telegram_notify } from '#scripts/notify/telegram-notify'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
-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 WakeStopReason, type WakeTidyResult } from './run-wake'
+import { run_wake, type WakeTidyResult } from './run-wake'
 import { run_wake_await } from './run-wake-await'
+import { run_wake_code } from './run-wake-code'
 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_finish } from './run-wake-finish'
+import { run_wake_loop, type LoopStop } from './run-wake-loop'
+import { run_wake_ports } from './run-wake-ports'
 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'
+import { run_wake_takeover, type TakeoverResult } from './run-wake-takeover'
 
 // `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
@@ -29,24 +27,22 @@ import { run_wake_supervise } from './run-wake-supervise'
 // The stdout/stderr split is the contract every `run:*` command shares: exactly one verdict token on
 // stdout on every path, the reason and the advice on stderr, so a loop branches on one token.
 //
-// **`--start` and `--loop` are two halves of one thing.** `--start` spawns this same script detached
+// **`--start` and `--loop` are two halves of one thing.** `--start` spawns the command's entry detached
 // with `--loop` and returns immediately, which is what leaves the supervisor outside the conversation;
 // `--loop` is the body, and running it in the foreground is how a person watches what it does.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const ONE_GROUP = 1
-const MS_PER_SECOND = 1000
-// Whole and positive. A zero interval is a busy loop against the temp directory, not a faster
-// supervisor.
-const INTERVAL_PATTERN = /^[1-9]\d*$/u
+// The interval is whole and positive (`cli_flags.to_positive`): a zero interval is a busy loop against
+// the temp directory, not a faster supervisor.
 // **Bounded above as well as below, and for the same reason.** `setTimeout` clamps any delay past
 // 2^31−1 ms to *one millisecond*, so a number large enough to look like "poll rarely" produces exactly
 // the busy loop the lower bound exists to prevent. An hour is far past any useful polling interval and
 // nowhere near the clamp.
 const MAX_INTERVAL_SECONDS = 3600
-const SCRIPT_PATH = fileURLToPath(import.meta.url)
+// The command's entry, not this module: the guard that runs `main` lives in `run-wake-main.ts`.
+const SCRIPT_PATH = fileURLToPath(new URL('run-wake-main.ts', import.meta.url))
 
 const STARTED_VERDICT = 'started'
 const RUNNING_VERDICT = 'running'
@@ -57,37 +53,16 @@ const NONE_VERDICT = 'none'
 const UNKNOWN_VERDICT = 'unknown'
 const FAILED_VERDICT = 'failed'
 
-// **The note covers both ways `wake_argv` answers `undefined`**, because it cannot tell them apart and
-// a message that named only the first would accuse a legitimate invocation of carrying unsafe text.
-// The second is the one a person actually meets: a `queue` whose references carry a `owner/repo#`
-// prefix is a grammar this supervisor does not rebuild, and `queue.md` → "The session boundary" is why
-// such a queue begins no record in the first place.
-const UNSAFE_INVOCATION_NOTE =
-	'the carried invocation is not one this supervisor can continue — it is neither a backlogrun nor a queue it can rebuild, or it carries text that may not be passed to a command line'
-// The command rather than one entry point: the supervisor continues a `queue` as readily as a
-// `backlogrun`, and a warning that named the wrong one would send the reader looking at a run that is
-// not the one that stopped.
-const WARNING_TITLE = 'run:wake supervisor'
-const WARNING_RECOVERY = `Check the wake command, then restart with \`pnpm josh run:wake --start\`.`
-// **The stop reasons that reach a person, and what each one tells them.** A reason mapped to
-// `undefined` is one where nothing went wrong: `ended` is the run finishing through `run:carry --end`,
-// `stopped` is a person's own `--stop` or a supervisor being superseded, and a warning channel that
-// fired on those is one that stops being read.
-//
-// **`unreadable` warns**, because it ends the supervisor while a carry record is still sitting there
-// handed off, so the run would otherwise be left asleep with nothing anywhere saying so.
-// **Every reason is listed, and the silent two are listed as `undefined`.** A partial map would let a
-// fifth stop reason compile straight past this and reach nobody, which is the defect class this
-// section exists to close.
-const STOP_BODIES: Record<WakeStopReason, string | undefined> = {
-	ended: undefined,
-	stopped: undefined,
-	failed: 'The supervisor could not continue the run and has stopped.',
-	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 RELOAD_FAILED_NOTE =
+	"The supervisor's code changed, but the supervisor to replace it did not start"
+const TAKEOVER_NOTES: Record<Exclude<TakeoverResult, 'taken'>, string> = {
+	died: 'it exited before it claimed the run',
+	unclaimed: 'it did not claim the run in time, so it was stopped',
+}
 const SUPERSEDED_RESULT: WakeTidyResult = 'superseded'
+const REMOVED_RESULT: WakeTidyResult = 'removed'
+const STOPPED_STOP: LoopStop = { reason: 'stopped', note: undefined }
 const SUPERSEDED_NOTE =
 	'another supervisor now holds the record, so it was left alone; this loop is the superseded one'
 
@@ -115,17 +90,15 @@ function usage(): number {
 	return FAILURE_EXIT_CODE
 }
 
-function note_to_stderr(note: string): void {
-	console.error(`wake: ${note}`)
-}
+const { note_to_stderr } = run_wake_ports
 
 function to_interval_ms(value: string | boolean | undefined): number | undefined {
 	if (typeof value !== 'string') return backlog_budget.OFFER_INTERVAL_MS
-	if (!INTERVAL_PATTERN.test(value)) return undefined
-
-	const seconds = Number(value)
+	const seconds = cli_flags.to_positive(value)
 
-	return seconds > MAX_INTERVAL_SECONDS ? undefined : seconds * MS_PER_SECOND
+	return seconds === undefined || seconds > MAX_INTERVAL_SECONDS
+		? undefined
+		: seconds * MS_PER_SECOND
 }
 
 // Exactly one verb, never a guessed order between two.
@@ -154,137 +127,6 @@ 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,
-	profile: AgentProfile,
-	session: { id: string; material: string },
-): LaunchResult {
-	const built = run_wake_session.wake_argv(invocation, profile, context.worktree, session)
-
-	if (built === undefined) return { kind: 'failed', note: UNSAFE_INVOCATION_NOTE }
-	if (built.kind === 'rejected') return { kind: 'failed', note: built.note }
-
-	// The headless mark is what lets the stop hook hold this session's turn open while its lanes run —
-	// 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)
-
-	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
-// adopted for this process, so reading that owner as live would have every restarted pass wait on
-// itself and never drive again.
-function ports_for(context: WakeContext, profile: AgentProfile): LoopPorts {
-	return {
-		read_carry: () => run_carry.read_carry(context.carry_target),
-		is_owner_live: (read) => read.kind === 'carried' && run_carry.is_held_by_another(read.carry),
-		has_work: async () => true,
-		new_session_id: () => randomUUID(),
-		hand_off: () => {
-			run_wake_handoff.hand_off(context.carry_target)
-		},
-		drive: async () => await run_wake_driver.drive(context.carry_target),
-		wake: (invocation, session_id, material) =>
-			wake_session(context, invocation, profile, { id: session_id, material }),
-		sleep: async (milliseconds) => {
-			await new Promise((resolve) => setTimeout(resolve, milliseconds))
-		},
-		now: () => new Date(),
-	}
-}
-
-// The log is named in the warning rather than only in `--list`, because the person reading a warning
-// at three in the morning is the one who needs to know where to look next.
-function log_hint(context: WakeContext): string {
-	return `The output of every session this supervisor started is in ${context.log_target}.`
-}
-
-// The log hint goes ahead of the note: the Telegram length limit cuts the tail, and a long failure note
-// (stdout tail plus stderr tail) would otherwise take the one line that says where to look next.
-function warning_body(stop: LoopStop, body: string, context: WakeContext): string {
-	return [body, log_hint(context), stop.note].filter(Boolean).join('\n')
-}
-
-// Whether the warning reached a person — the answer `record_failure` leaves its marker on.
-async function warn_of_stop(stop: LoopStop, body: string, context: WakeContext): Promise<boolean> {
-	return await telegram_notify.warn({
-		issue_title: WARNING_TITLE,
-		body: warning_body(stop, body, context),
-		recovery: WARNING_RECOVERY,
-	})
-}
-
-// **A failed supervisor that leaves the run stranded says so on the stream, with its cause.** Nothing
-// else writes there when the supervisor gives up, so a reader of the events would see the last merge
-// and a run that looks as if it were still watching. The cause is the note's first line — the
-// driver's own `error …` — because the rest is a stderr tail the log already holds.
-//
-// **Only a strand, and only one a person was told of.** A `failed` stop is not always a strand: a
-// `run:carry --end` under a live driver fails it too, and that run ended cleanly. And the event is the
-// marker `run_stranded_detect` holds its own notification back on, so it is left only when the warning
-// was sent — after a failed send the stop-time detector still finds no marker, and notifies.
-function is_strand_told(stop: LoopStop, watched: WatchedRun, is_warned: boolean): boolean {
-	if (!is_warned || stop.reason !== run_wake_loop.FAILED_REASON) return false
-
-	return run_stranded_detect.is_left_stranded(watched)
-}
-
-async function record_failure(
-	stop: LoopStop,
-	watched: WatchedRun,
-	is_warned: boolean,
-): Promise<void> {
-	if (!is_strand_told(stop, watched, is_warned)) return
-
-	const [cause = ''] = (stop.note ?? '').split('\n', 1)
-
-	await run_event_stream_emit.emit(
-		run_event_stream.EVENT_KIND.STRANDED,
-		`The supervisor failed and stopped watching the run — ${cause}`,
-	)
-}
-
-// **Only a failed wake exits non-zero; `unreadable` warns but exits zero.** The
-// verdict-and-exit-code table in `docs/josh-commands-automation.md` is a contract callers branch on,
-// and what that one needs is the notification, not a different exit code.
-function exit_code_of(reason: WakeStopReason): number {
-	return reason === run_wake_loop.FAILED_REASON ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
-}
-
-// A failure that reached nobody is the defect, so the Telegram goes out before the verdict is printed.
-// Which stops reach a person, and what each one says — `undefined` for the two where nothing went
-// wrong. It is a function rather than a bare lookup so the decision can be asserted for every reason
-// the loop can end on.
-function stop_body(reason: WakeStopReason): string | undefined {
-	return STOP_BODIES[reason]
-}
-
-// `started_at` is the run this supervisor took on — what `record_failure` tells an ended run by once
-// the carry record that held it no longer reads.
-async function finish(stop: LoopStop, context: WakeContext, started_at: string): Promise<number> {
-	const body = stop_body(stop.reason)
-
-	if (body === undefined) return report(stop.reason)
-
-	console.error(stop.note ?? body)
-	const is_warned = await warn_of_stop(stop, body, context)
-
-	await record_failure(stop, { ...context, started_at }, is_warned)
-
-	return report(stop.reason, exit_code_of(stop.reason))
-}
-
 function launch_supervisor(
 	context: WakeContext,
 	interval: string | undefined,
@@ -317,8 +159,12 @@ function start_for_launch(git_directory: string, provider: AgentProvider): Launc
 	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())
+function spawn_supervisor(
+	context: WakeContext,
+	interval: string | undefined,
+	profile: AgentProfile | undefined,
+): number {
+	const result = launch_supervisor(context, interval, profile)
 
 	if (result.kind === 'failed') {
 		console.error(`Could not start the supervisor: ${result.note}`)
@@ -346,7 +192,15 @@ function start(context: WakeContext, interval: string | undefined): number {
 		return report(RUNNING_VERDICT)
 	}
 
-	return spawn_supervisor(context, interval)
+	return spawn_supervisor(context, interval, run_wake_session.scheduler_profile())
+}
+
+// The supervisor `josh backlogrun --restart` starts in place of the one it stopped, on that one's
+// profile, so the shell the restart was typed in does not choose it; the shell's where none was running.
+function restart_supervisor(git_directory: string, profile: AgentProfile | undefined): number {
+	const chosen = profile ?? run_wake_session.scheduler_profile()
+
+	return spawn_supervisor(context_of(git_directory), undefined, chosen)
 }
 
 // **The loop removes its record on the way out, and only its own.** A loop that ended after its record
@@ -357,8 +211,78 @@ function start(context: WakeContext, interval: string | undefined): number {
 // replaced would leave no trace of that anywhere. Which of the two happened is `tidy_own_wake`'s
 // answer rather than a second read taken here — the branch that decides it belongs beside the record,
 // where it is tested, not in a CLI that would have to re-derive it.
-function tidy_up(target: string): void {
-	if (run_wake.tidy_own_wake(target) === SUPERSEDED_RESULT) note_to_stderr(SUPERSEDED_NOTE)
+function tidy_up(target: string): WakeTidyResult {
+	const tidied = run_wake.tidy_own_wake(target)
+
+	if (tidied === SUPERSEDED_RESULT) note_to_stderr(SUPERSEDED_NOTE)
+
+	return tidied
+}
+
+// **No reload while a lane's request is being answered**: ending the broker closes every lane's server
+// but waits out the slowest request, a review up to its limit, leaving the run unwatched and the other
+// lanes unserved meanwhile. The check is skipped, not taken, so the moved commit is still read as
+// stale at the first idle pass.
+function code_check(is_stale: () => Promise<boolean>): () => Promise<boolean> {
+	return async () => !lane_session_broker.is_answering() && (await is_stale())
+}
+
+function reload_failed(note: string): LoopStop {
+	return { reason: run_wake_loop.FAILED_REASON, note: `${RELOAD_FAILED_NOTE}: ${note}` }
+}
+
+// A record removed by `--stop` or taken over while the loop ended is not this loop's to hand on.
+function as_not_handed_on(stop: LoopStop): LoopStop {
+	return stop.reason === run_wake_loop.RELOAD_REASON ? STOPPED_STOP : stop
+}
+
+// **The successor starts only once this supervisor's broker has closed and its record is gone**
+// (joshuafolkken/kit#4509): two brokers for one lane overwrite each other's response
+// (`claude-lane-broker.ts`), and a record still held by a live process refuses the successor's claim.
+// The lanes and the carry record are left as `backlogrun --restart` leaves them: untouched, for the
+// successor to adopt. A successor that did not start leaves the run unwatched, so it fails as a warning.
+async function reload(
+	context: WakeContext,
+	interval_ms: number,
+	profile: AgentProfile,
+): Promise<LoopStop> {
+	const interval = String(Math.round(interval_ms / MS_PER_SECOND))
+	const result = launch_supervisor(context, interval, profile)
+
+	if (result.kind === 'failed') return reload_failed(result.note)
+
+	const ports = run_wake_takeover.ports_of(context.wake_target)
+	const takeover = await run_wake_takeover.await_takeover(result.pid, ports)
+
+	if (takeover !== 'taken') return reload_failed(TAKEOVER_NOTES[takeover])
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.NOTE,
+		`The supervisor's code changed on main, so process ${String(process.pid)} handed the run to process ${String(result.pid)} on the new code.`,
+	)
+
+	return { reason: run_wake_loop.RELOAD_REASON, note: undefined }
+}
+
+async function supervised(
+	context: WakeContext,
+	interval_ms: number,
+	profile: AgentProfile,
+): Promise<LoopStop> {
+	const source = run_wake_code.source_of(context.worktree, SCRIPT_PATH)
+	const is_stale = code_check(await run_wake_code.watch(source, lane_session_broker.take_refusal))
+	const ports = run_wake_ports.ports_for(context, profile, is_stale)
+	const stop = await run_wake_supervise.supervise({
+		context,
+		ports,
+		interval_ms,
+		note: note_to_stderr,
+	})
+
+	if (tidy_up(context.wake_target) !== REMOVED_RESULT) return as_not_handed_on(stop)
+	if (stop.reason !== run_wake_loop.RELOAD_REASON) return stop
+
+	return await reload(context, interval_ms, profile)
 }
 
 // A failed pass is restarted while the carry record is still resumable (`run-wake-restart.ts`), so
@@ -376,17 +300,11 @@ async function loop(context: WakeContext, interval_ms: number): Promise<number>
 	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.wake.profile ?? profile)
-	const stop = await run_wake_supervise.supervise({
-		context,
-		ports,
-		interval_ms,
-		note: note_to_stderr,
-	})
+	run_wake_session.keep_awake(process.pid)
 
-	tidy_up(context.wake_target)
+	const stop = await supervised(context, interval_ms, claimed.wake.profile ?? profile)
 
-	return await finish(stop, context, claimed.carry.started_at)
+	return await run_wake_finish.finish(stop, context, claimed.carry.started_at)
 }
 
 // **The verdict tracks whether the supervisor is actually running, not merely whether a record is
@@ -436,28 +354,22 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await dispatch(values, context, interval_ms)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const run_wake_cli = {
 	FAILED_VERDICT,
 	NONE_VERDICT,
 	RUNNING_VERDICT,
+	SCRIPT_PATH,
 	STALE_VERDICT,
 	STOPPED_VERDICT,
 	SUPERVISING_VERDICT,
 	UNKNOWN_VERDICT,
 	USAGE,
-	finish,
-	ports_for,
-	record_failure,
+	RELOAD_FAILED_NOTE,
+	reload,
+	restart_supervisor,
 	run,
 	start_for_launch,
-	stop_body,
-	warning_body,
+	supervised,
 }
 
-if (process.argv[1] === SCRIPT_PATH) await main(process.argv.slice(ARGV_OFFSET))
-
 export { run_wake_cli }

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

@@ -0,0 +1,125 @@
+import { git_command } from '#scripts/git/git-command'
+import { error_text } from '#scripts/lib/error-message'
+import { import_graph } from '#scripts/lint/import-graph'
+
+// Whether the supervisor still runs the code on disk (joshuafolkken/kit#4509). A supervisor keeps the
+// code it started with for its whole life, while the lanes' ships run each new main — so a change to
+// what the supervisor serves them, the broker's request format above all, stops every lane that asks.
+//
+// **The code is the entry's import closure, not the tree**: a merge that touched only files the
+// supervisor never imports changes nothing it runs, and restarting on it would only cost a broker gap.
+// The closure is hashed as the lint cache hashes it (`import-graph.ts`).
+//
+// **The closure is re-hashed only once the commit has moved**: hashing it reads every file it reaches,
+// and on most passes nothing has merged since the last one.
+
+interface CodeSource {
+	// The commit the checkout sits on; `undefined` where it cannot be read.
+	head: () => Promise<string | undefined>
+	// The hash of the entry's import closure; `undefined` where it cannot be computed.
+	closure: () => Promise<string | undefined>
+}
+
+interface CodeState {
+	head: string | undefined
+	loaded: string | undefined
+	// A suspicion taken while the closure could not be hashed, kept for the next pass.
+	is_suspect: boolean
+}
+
+// **A hash that cannot be computed is never stale**: a supervisor that cannot tell keeps running, as
+// it did before this check existed, rather than restarting on every pass. **A suspected supervisor whose
+// start left no baseline is stale** (joshuafolkken/kit#4714): the broker refused a request, and without
+// a baseline nothing else could ever tell it differs, so the successor reads one afresh.
+function is_changed(
+	loaded: string | undefined,
+	current: string | undefined,
+	is_suspected: boolean,
+): boolean {
+	if (current === undefined) return false
+	if (loaded === undefined) return is_suspected
+
+	return loaded !== current
+}
+
+// **A move and a suspicion are consumed only once they were hashed**, so a closure that could not be
+// read at them is read again at the next pass (joshuafolkken/kit#4714).
+function consume(
+	state: CodeState,
+	read: { head: string | undefined; is_suspect: boolean },
+	current: string | undefined,
+): void {
+	if (current === undefined) {
+		state.is_suspect = read.is_suspect
+
+		return
+	}
+
+	state.head = read.head
+	state.is_suspect = false
+}
+
+// **A suspicion re-hashes an unmoved commit** (joshuafolkken/kit#4714).
+async function is_stale(
+	state: CodeState,
+	source: CodeSource,
+	is_suspected: () => boolean,
+): Promise<boolean> {
+	const head = await source.head()
+	const is_suspect = is_suspected() || state.is_suspect
+	if (!is_suspect && head === state.head) return false
+
+	const current = await source.closure()
+
+	consume(state, { head, is_suspect }, current)
+
+	return is_changed(state.loaded, current, is_suspect)
+}
+
+// The baseline is read when the watch starts — at the supervisor's start, as close to the moment its
+// modules were loaded as a reading can be. `is_suspected` answers, and clears, whether something has
+// seen this code differ from main's since it was last asked (`lane-session-broker.ts`).
+async function watch(
+	source: CodeSource,
+	is_suspected: () => boolean = () => false,
+): Promise<() => Promise<boolean>> {
+	const state: CodeState = {
+		head: await source.head(),
+		loaded: await source.closure(),
+		is_suspect: false,
+	}
+
+	return async () => await is_stale(state, source, is_suspected)
+}
+
+async function read_head(): Promise<string | undefined> {
+	try {
+		return await git_command.head_commit()
+	} catch (error) {
+		error_text.trace_swallowed('run_wake_code.read_head', error)
+
+		return undefined
+	}
+}
+
+// A fresh graph each time: one graph caches the content it read, so it would answer the old hash.
+async function read_closure(root: string, entry: string): Promise<string | undefined> {
+	try {
+		const graph = await import_graph.create(root)
+
+		return graph?.closure_hash(entry)
+	} catch (error) {
+		error_text.trace_swallowed('run_wake_code.read_closure', error)
+
+		return undefined
+	}
+}
+
+function source_of(root: string, entry: string): CodeSource {
+	return { head: read_head, closure: async () => await read_closure(root, entry) }
+}
+
+const run_wake_code = { source_of, watch }
+
+export type { CodeSource }
+export { run_wake_code }

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

@@ -1,4 +1,5 @@
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { MS_PER_MINUTE } from '#scripts/lib/timeouts'
 import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { run_invocation } from '#scripts/run/run-invocation'
@@ -11,6 +12,12 @@ const DETAILS_TAIL_LENGTH = 2048
 const TRUNCATION_MARK = '... '
 // The prefix `backlog-drive-cli.ts` gives the exception it catches.
 const ERROR_PREFIX = 'error '
+// **The driver is bounded so the supervisor reaches its pass boundary between dispatches**
+// (joshuafolkken/kit#4509): unbounded, `backlog:drive` dispatches, collects and merges lanes in its own
+// loop until a judgment hand-off, and the code check at the pass boundary would wait for that.
+const WINDOW_MINUTES = 5
+const WINDOW_MS = WINDOW_MINUTES * MS_PER_MINUTE
+const WINDOW_VERDICT = 'window'
 
 function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 	const rebuilt = run_invocation.rebuild(invocation)
@@ -21,6 +28,8 @@ function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 		'backlog:drive',
 		'--owner',
 		String(process.pid),
+		'--window',
+		String(WINDOW_MINUTES),
 		...rebuilt.split(' ').slice(1 + named_count),
 	]
 }
@@ -141,11 +150,11 @@ function claim_record(target: string, invocation: string): boolean {
 }
 
 // **A verdict with nothing to judge is re-driven here, never handed to a session.** A woken session
-// met with `window`, `merge busy` or `merge retry` could only cut and hand the loop back for the same
-// driver to run again — a model round trip, at a cache write each, that decides nothing. The record
-// is already this process's, so the rerun needs no fresh claim; the limit keeps a driver that never
-// settles from holding the supervisor past its own checks.
-const RERUN_VERDICTS: ReadonlyArray<string> = ['window', 'merge busy', 'merge retry']
+// met with `merge busy` or `merge retry` could only cut and hand the loop back for the same driver to
+// run again — a model round trip, at a cache write each, that decides nothing. The record is already
+// this process's, so the rerun needs no fresh claim; the limit keeps a driver that never settles from
+// holding the supervisor past its own checks.
+const RERUN_VERDICTS: ReadonlyArray<string> = ['merge busy', 'merge retry']
 const RERUN_LIMIT = 10
 const RERUN_PAUSE_MS = 60_000
 
@@ -157,18 +166,21 @@ async function pause(ms: number): Promise<void> {
 	})
 }
 
-function is_mechanical(result: JoshResult): boolean {
+function is_verdict(result: JoshResult, entries: ReadonlyArray<string>): boolean {
 	const verdict = result.out.split('\n', 1)[FIRST_LINE] ?? ''
 
 	return (
 		result.code === SUCCESS &&
-		RERUN_VERDICTS.some((entry) => verdict === entry || verdict.startsWith(`${entry} `))
+		entries.some((entry) => verdict === entry || verdict.startsWith(`${entry} `))
 	)
 }
 
 // A record that was removed during the pause answers `undefined`: its stale verdict must not reach a
 // session, so the supervisor's own next pass re-reads the record and ends the run as `ended` or
 // `stopped`; a rerun would only fail on it and report the run as `failed`.
+//
+// **A spent window answers `undefined` too**, so the supervisor's next pass checks its code before it
+// drives again; the restarted driver adopts the lanes still in flight.
 async function run_driver(
 	target: string,
 	args: ReadonlyArray<string>,
@@ -176,7 +188,8 @@ async function run_driver(
 	remaining: number,
 ): Promise<JoshResult | undefined> {
 	const result = await josh_command.josh_run(args, true)
-	if (remaining === 0 || !is_mechanical(result)) return result
+	if (is_verdict(result, [WINDOW_VERDICT])) return undefined
+	if (remaining === 0 || !is_verdict(result, RERUN_VERDICTS)) return result
 
 	await wait(RERUN_PAUSE_MS)
 	if (run_carry.read_carry(target).kind !== 'carried') return undefined
@@ -211,4 +224,4 @@ async function drive(target: string, wait: Pause = pause): Promise<DriveResult>
 	)
 }
 
-export const run_wake_driver = { RERUN_LIMIT, drive, driver_args, driver_result }
+export const run_wake_driver = { RERUN_LIMIT, WINDOW_MS, drive, driver_args, driver_result }