@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -4,16 +4,18 @@ import { git_command } from '#scripts/git/git-command'
 import { main_merge, type MergeOutcome } from '#scripts/git/main-merge'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
+import { run_ship_overlap } from './run-ship-overlap'
 import { run_ship_scoped } from './run-ship-scoped'
+import type { Cause } from './run-ship-stop-cause'
 
 // `josh ship` keeps the branch current with the default branch itself: a default branch that moves
 // while the pull request opens and CI runs would otherwise stop the followup as `interrupted`, though
 // merging the default branch again usually resolves it.
 //
 // So the merge happens mechanically: once before the commit (`sync_stage`), and once when
-// the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). Only a merge git
-// itself cannot finish stops the ship, and it stops as `conflict`, naming the unmerged paths so the
-// resumed session goes straight to them.
+// the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). A conflict only on
+// generated files is regenerated by the merge itself (`main-merge-regenerate.ts`); any other conflict
+// stops the ship as `conflict`, naming the unmerged paths so the resumed session goes straight to them.
 
 const should_forward_stderr = true
 const SUCCESS_EXIT_CODE = 0
@@ -28,10 +30,14 @@ const MERGED_PREFIX = 'merged '
 
 // A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
 // `is_skipped` marks a stage that found nothing to do — a review round with nothing to review, a gate
-// that reused a green record — so its few seconds are not timed as a run of it.
+// that reused a green record — so its few seconds are not timed as a run of it. `preconditions` names
+// the kinds of the preconditions a stopped preflight found unmet (`run-ship-preflight.ts`). `cause` is the
+// one a stopped review round tagged its stop with (`run-ship-stop-cause.ts`).
 interface StepResult extends JoshResult {
 	is_skipped?: boolean
 	conflicts?: ReadonlyArray<string>
+	preconditions?: ReadonlyArray<string>
+	cause?: Cause
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
@@ -66,12 +72,19 @@ function sync_note(outcome: Exclude<MergeOutcome, { kind: 'conflict' }>): string
 // touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
 // the tree is checked by the gate stage that follows, so the commit never carries
 // an unchecked merge and the gate's record names the merge base the push carries.
-async function sync_stage(): Promise<StepResult> {
+//
+// The merge waits first for any lane whose open pull request changes the same paths
+// (`run-ship-overlap.ts`), so it brings that pull request in before the gate rather than meeting it
+// as `DIRTY` after CI.
+async function sync_stage(issue: string): Promise<StepResult> {
+	const waited = run_ship_overlap.note(await run_ship_overlap.await_overlap(issue))
 	const outcome = await merge_outcome()
 
-	if (outcome.kind === 'conflict') return conflict_result(outcome.files, '')
+	if (outcome.kind === 'conflict') return conflict_result(outcome.files, waited)
+
+	const out = [waited, sync_note(outcome)].filter((line) => line !== '').join('\n')
 
-	return { code: SUCCESS_EXIT_CODE, out: sync_note(outcome) }
+	return { code: SUCCESS_EXIT_CODE, out }
 }
 
 // Any read that fails answers "not conflicting": the followup failure then stands as it was.
@@ -109,21 +122,53 @@ async function merge_again(title: string, failed: JoshResult): Promise<StepResul
 	return await push_merged(title)
 }
 
-async function followup_stage(
+// Whether the ship waits on the merge alone, for its stage record (`run_ship_stage.mark_merge_waiting`).
+type WaitMark = (is_merge_waiting: boolean) => void
+
+function ignore_wait(): void {
+	// A ship with no stage record has no lane place to free.
+}
+
+// The wait is marked only while `josh followup` runs: the merge again and its gate run unmarked, so a
+// lane gating here still holds its place (joshuafolkken/kit#4466).
+async function marked_followup(
 	title: string,
 	notify: ReadonlyArray<string>,
-	retries = 0,
+	mark: WaitMark,
+): Promise<JoshResult> {
+	mark(true)
+
+	try {
+		return await josh(['followup', title, ...notify])
+	} finally {
+		mark(false)
+	}
+}
+
+async function followup_attempt(
+	title: string,
+	notify: ReadonlyArray<string>,
+	mark: WaitMark,
+	retries: number,
 ): Promise<StepResult> {
-	const result = await josh(['followup', title, ...notify])
+	const result = await marked_followup(title, notify, mark)
 
 	if (result.code === SUCCESS_EXIT_CODE || retries >= MAX_MERGE_RETRIES) return result
 
 	const stop = await merge_again(title, result)
 
-	return stop ?? (await followup_stage(title, notify, retries + 1))
+	return stop ?? (await followup_attempt(title, notify, mark, retries + 1))
+}
+
+async function followup_stage(
+	title: string,
+	notify: ReadonlyArray<string>,
+	mark: WaitMark = ignore_wait,
+): Promise<StepResult> {
+	return await followup_attempt(title, notify, mark, 0)
 }
 
 const run_ship_sync = { CONFLICT_NOTE, MAX_MERGE_RETRIES, followup_stage, sync_stage }
 
-export type { StepResult }
+export type { StepResult, WaitMark }
 export { run_ship_sync }

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

@@ -10,6 +10,9 @@
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
 import { run_section, type Section } from '#scripts/run/run-section'
+import { run_tail } from '#scripts/run/run-tail'
+import type { Cause } from './run-ship-stop-cause'
+import type { StepResult } from './run-ship-sync'
 
 const PREFLIGHT_HEADER = '=== preflight ==='
 const PRE_DETACH_HEADER = '=== pre-detach checks ==='
@@ -26,14 +29,38 @@ const STOPPED_PREFIX = 'stopped at: '
 const SKIPPED_BODY = 'skipped — already done'
 
 type ShipSection = Section & {
+	// The stage's standard output alone, the text an infrastructure stop is read on.
+	out?: string
 	// The paths a stopped merge left unmerged, handed to the stop prompt.
 	conflicts?: ReadonlyArray<string>
+	// The kinds of the preconditions a stopped preflight found unmet, recorded with the stop.
+	preconditions?: ReadonlyArray<string>
+	// The cause a stopped review round tagged its stop with, recorded with the stop.
+	cause?: Cause
+}
+
+// A stage's result under its header, carrying the conflicts, the preconditions and the cause only where
+// it has them.
+function section_of(header: string, result: StepResult): ShipSection {
+	const { conflicts, preconditions, cause } = result
+
+	return {
+		header,
+		body: run_tail.section_body(result.out, result.err, result.code),
+		code: result.code,
+		out: result.out,
+		...(conflicts !== undefined && { conflicts }),
+		...(preconditions !== undefined && { preconditions }),
+		...(cause !== undefined && { cause }),
+	}
 }
 
 // The step that stopped the ship, or `undefined` when every executed step was green. Because the
-// composite breaks at the first failure, this is the last section whenever one exists.
+// composite breaks at the first failure, this is the last section whenever one exists. The pre-detach
+// report runs on past a red check and prints the preflight refusal last (joshuafolkken/kit#4478), so
+// the last failed section is the one named.
 function failed_section(sections: ReadonlyArray<ShipSection>): ShipSection | undefined {
-	return sections.find((section) => section.code !== run_section.SUCCESS_EXIT_CODE)
+	return sections.findLast((section) => section.code !== run_section.SUCCESS_EXIT_CODE)
 }
 
 // The executed steps under their headers, closed with the name of the step that stopped the run so the
@@ -64,6 +91,7 @@ const run_ship = {
 	exit_code: run_section.exit_code_of,
 	failed_section,
 	format_report,
+	section_of,
 }
 
 export type { ShipSection }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { backlog_drive_restore } from '#scripts/backlog/backlog-drive-restore'
 import { issue_merged } from '#scripts/issue/issue-merged'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
@@ -49,6 +47,4 @@ async function sweep(): Promise<void> {
 
 const run_tidy_cli = { sweep }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await sweep()
-
 export { run_tidy_cli }

package/scripts/run/tidy/run-tidy-lanes.ts

@@ -3,6 +3,7 @@ import { git_stash } from '#scripts/git/stash/git-stash'
 import { session_cite } from '#scripts/issue/session-cite'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_residents } from '#scripts/lane/lane-residents'
 import { error_text } from '#scripts/lib/error-message'
 import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_tidy, type Outcome, type Verdict } from './run-tidy'
@@ -72,6 +73,8 @@ async function lane_verdict(lane: LaneInfo, hold_path: string): Promise<Verdict>
 async function close(issue: string, hold_path: string): Promise<Verdict> {
 	const outcome = await lane_close.close_lane(issue)
 
+	lane_residents.report(outcome.residents, session_cite.issue(issue))
+
 	if (outcome.kind !== CLOSED_KIND) return run_tidy.keep(INCOMPLETE_REASON)
 
 	run_hold.release_hold(hold_path)

package/scripts/run/tidy/run-tidy-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_tidy_cli } from './run-tidy-cli'
+
+// The `josh run:tidy` entry, kept apart from `run-tidy-cli.ts` because `run:hold` imports that one: a
+// bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186). The sweep takes no arguments and never sets an exit code.
+if (process.argv[1] === fileURLToPath(import.meta.url)) await run_tidy_cli.sweep()

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

@@ -1,25 +1,24 @@
-#!/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 { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 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_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_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 +28,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,13 +54,6 @@ 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.
@@ -82,12 +72,21 @@ const WARNING_RECOVERY = `Check the wake command, then restart with \`pnpm josh
 const STOP_BODIES: Record<WakeStopReason, string | undefined> = {
 	ended: undefined,
 	stopped: undefined,
+	reload: 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 +114,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,56 +151,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 {
@@ -256,7 +203,7 @@ async function record_failure(
 }
 
 // **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,
+// verdict-and-exit-code table in `docs/josh-commands-run.md` → `run:wake` 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
@@ -317,8 +264,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 +297,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 +316,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))
+	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,15 +405,7 @@ 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,
-	})
-
-	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)
 }
@@ -436,28 +457,26 @@ 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,
+	RELOAD_FAILED_NOTE,
 	record_failure,
+	reload,
+	restart_supervisor,
 	run,
 	start_for_launch,
 	stop_body,
+	supervised,
 	warning_body,
 }
 
-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,83 @@
+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 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.
+function is_changed(loaded: string | undefined, current: string | undefined): boolean {
+	if (loaded === undefined || current === undefined) return false
+
+	return loaded !== current
+}
+
+async function is_stale(state: CodeState, source: CodeSource): Promise<boolean> {
+	const head = await source.head()
+	if (head === state.head) return false
+
+	state.head = head
+
+	return is_changed(state.loaded, await source.closure())
+}
+
+// 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.
+async function watch(source: CodeSource): Promise<() => Promise<boolean>> {
+	const state: CodeState = { head: await source.head(), loaded: await source.closure() }
+
+	return async () => await is_stale(state, source)
+}
+
+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 }