@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -0,0 +1,114 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// How a stopped detached ship goes back to the lane session that launched it, rather than to a fresh
+// one that re-reads the diff and the findings (joshuafolkken/kit#4711).
+//
+// **The session proves it is alive by waiting**: `josh ship:wait` refreshes a heartbeat on every poll,
+// and keeps it for one session gap after a chunk ends `pending`, so the session can re-issue the wait
+// without the supervisor reading it as gone. A wait that ends for good removes it.
+//
+// **One side decides who answers a stop, by an exclusive create**: the supervisor writes the stop note
+// and waits for the waiter to take it; past the gap it withdraws it and relaunches as before. Taking and
+// withdrawing are the same `create_stamp` on one decision record, so exactly one of them wins and a stop
+// is never answered twice nor dropped.
+
+const HEARTBEAT_PREFIX = 'josh-ship-waiter-'
+const HANDOFF_PREFIX = 'josh-ship-handoff-'
+const DECISION_PREFIX = 'josh-ship-handoff-taken-'
+const KEY_SEPARATOR = '-'
+const TAKEN = 'taken'
+const WITHDRAWN = 'withdrawn'
+// Long enough for a session to answer a `pending` chunk with the next wait, short enough that a session
+// which ended delays its fresh successor by no more than this.
+const SESSION_GAP_MS = 120_000
+const OFFER_POLL_MS = 1000
+
+const heartbeat_schema = z.object({ at: z.number() })
+const offer_schema = z.object({ at: z.number(), note: z.string() })
+
+function path_of(prefix: string, repository: string, issue: string): string {
+	return stamp_file.stamp_path(`${prefix}${issue}${KEY_SEPARATOR}`, repository)
+}
+
+function beat(repository: string, issue: string, at: number = Date.now()): void {
+	stamp_file.replace_stamp(path_of(HEARTBEAT_PREFIX, repository, issue), { at })
+}
+
+function leave(repository: string, issue: string): void {
+	stamp_file.remove_stamp(path_of(HEARTBEAT_PREFIX, repository, issue))
+}
+
+function is_waited(repository: string, issue: string, now: number = Date.now()): boolean {
+	const raw = stamp_file.read_stamp_text(path_of(HEARTBEAT_PREFIX, repository, issue))
+	const heartbeat = raw === undefined ? undefined : json_value.parse_with(raw, heartbeat_schema)
+
+	return heartbeat !== undefined && now - heartbeat.at < SESSION_GAP_MS
+}
+
+function decide(repository: string, issue: string, decision: string): boolean {
+	return stamp_file.create_stamp(path_of(DECISION_PREFIX, repository, issue), decision)
+}
+
+function clear_offer(repository: string, issue: string): void {
+	stamp_file.remove_stamp(path_of(HANDOFF_PREFIX, repository, issue))
+	stamp_file.remove_stamp(path_of(DECISION_PREFIX, repository, issue))
+}
+
+// An offer is never held past the session gap, so an older one was left by a supervisor that died
+// mid-offer and belongs to an earlier attempt, not to the ship this session waits on.
+function offered_note(repository: string, issue: string, now: number): string | undefined {
+	const raw = stamp_file.read_stamp_text(path_of(HANDOFF_PREFIX, repository, issue))
+	const offered = raw === undefined ? undefined : json_value.parse_with(raw, offer_schema)
+
+	return offered !== undefined && now - offered.at < SESSION_GAP_MS ? offered.note : undefined
+}
+
+// The waiter's side: the stop note, once this call won it; `undefined` where none is offered or the
+// supervisor already withdrew it.
+function take(repository: string, issue: string, now: number = Date.now()): string | undefined {
+	const note = offered_note(repository, issue, now)
+
+	if (note === undefined || !decide(repository, issue, TAKEN)) return undefined
+
+	stamp_file.remove_stamp(path_of(HANDOFF_PREFIX, repository, issue))
+
+	return note
+}
+
+async function await_taken(repository: string, issue: string): Promise<boolean> {
+	const decision = path_of(DECISION_PREFIX, repository, issue)
+
+	for (let waited = 0; waited < SESSION_GAP_MS; waited += OFFER_POLL_MS) {
+		if (stamp_file.read_stamp_text(decision) !== undefined) return true
+
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the waiter's next poll
+		await sleep(OFFER_POLL_MS)
+	}
+
+	return !decide(repository, issue, WITHDRAWN)
+}
+
+// The supervisor's side: whether a waiting session took `note`. A session that is not waiting is not
+// offered anything, so a lane whose child ended relaunches with no delay.
+async function offer(repository: string, issue: string, note: string): Promise<boolean> {
+	if (!is_waited(repository, issue)) return false
+
+	clear_offer(repository, issue)
+	// Renamed into place whole: a waiter polling between an exclusive create and its write would read an
+	// empty note, win the decision on it and drop the stop.
+	stamp_file.replace_stamp(path_of(HANDOFF_PREFIX, repository, issue), { at: Date.now(), note })
+	const is_taken = await await_taken(repository, issue)
+
+	// The decision stays until the next offer clears it: a waiter that read the note just before the
+	// withdrawal would otherwise win a fresh decision record and answer the stop a second time.
+	stamp_file.remove_stamp(path_of(HANDOFF_PREFIX, repository, issue))
+
+	return is_taken
+}
+
+const run_ship_waiter = { SESSION_GAP_MS, beat, is_waited, leave, offer, take }
+
+export { run_ship_waiter }

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

@@ -37,10 +37,23 @@ type ShipSection = Section & {
 	preconditions?: ReadonlyArray<string>
 	// The cause a stopped review round tagged its stop with, recorded with the stop.
 	cause?: Cause
+	// The stage found nothing to do, and why it ran or was skipped — both read onto its event line.
+	is_skipped?: boolean
+	reason?: string
 }
 
-// A stage's result under its header, carrying the conflicts, the preconditions and the cause only where
-// it has them.
+// The skip and the reason a stage's event line carries, only where the stage gave them.
+function mark_of(result: StepResult): Pick<ShipSection, 'is_skipped' | 'reason'> {
+	const { is_skipped, reason } = result
+
+	return {
+		...(is_skipped !== undefined && { is_skipped }),
+		...(reason !== undefined && { reason }),
+	}
+}
+
+// A stage's result under its header, carrying the conflicts, the preconditions, the cause and the mark
+// only where it has them.
 function section_of(header: string, result: StepResult): ShipSection {
 	const { conflicts, preconditions, cause } = result
 
@@ -52,6 +65,7 @@ function section_of(header: string, result: StepResult): ShipSection {
 		...(conflicts !== undefined && { conflicts }),
 		...(preconditions !== undefined && { preconditions }),
 		...(cause !== undefined && { cause }),
+		...mark_of(result),
 	}
 }
 

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

@@ -0,0 +1,48 @@
+import { spawn, type SpawnOptions } from 'node:child_process'
+import { existsSync } from 'node:fs'
+
+// **The host stays awake while a supervisor runs** (#5173). `lane-sleep.ts` takes host sleep out of a
+// lane's net time but cannot prevent it, and an idle sleep stops every lane, CI wait and relaunch at
+// once. `caffeinate -w <pid>` holds the assertion for exactly the supervisor's lifetime: a `--stop`, a
+// crash or a reload's exit ends it with no bookkeeping, and the successor of a reload starts its own
+// from this same call, so the hand-off needs no re-attach. `-i` blocks idle sleep, `-s` system sleep —
+// lid-close sleep included, but only on AC power (`docs/how-to/run-backlog.md`).
+const CAFFEINATE_PATH = '/usr/bin/caffeinate'
+const CAFFEINATE_FLAGS = ['-i', '-s', '-w']
+
+interface Started {
+	on: (event: 'error', listener: () => void) => unknown
+	unref: () => unknown
+}
+
+type Spawner = (command: string, args: Array<string>, options: SpawnOptions) => Started
+
+function argv(pid: number): Array<string> {
+	return [...CAFFEINATE_FLAGS, String(pid)]
+}
+
+// **A host without `caffeinate` (Linux, CI) runs the supervisor as before** — nothing is started and
+// nothing is printed; a spawn that fails late is swallowed for the same reason.
+function keep_awake(
+	pid: number,
+	is_present: (path: string) => boolean = existsSync,
+	spawner: Spawner = spawn,
+): void {
+	if (!is_present(CAFFEINATE_PATH)) return
+
+	const child = spawner(CAFFEINATE_PATH, argv(pid), { detached: true, stdio: 'ignore' })
+
+	child.on('error', () => {
+		// the supervisor runs without the assertion, as on a host without caffeinate
+	})
+	child.unref()
+}
+
+const run_wake_caffeinate = {
+	CAFFEINATE_PATH,
+	argv,
+	keep_awake,
+}
+
+export type { Spawner, Started }
+export { run_wake_caffeinate }

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

@@ -4,15 +4,14 @@ 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_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
-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_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'
@@ -54,29 +53,6 @@ const NONE_VERDICT = 'none'
 const UNKNOWN_VERDICT = 'unknown'
 const FAILED_VERDICT = 'failed'
 
-// 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,
-	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"
@@ -151,87 +127,6 @@ function refuse_without_carry(kind: CarryRead['kind']): number {
 	return report(NONE_VERDICT, FAILURE_EXIT_CODE)
 }
 
-// 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-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
-}
-
-// 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,
@@ -375,7 +270,7 @@ async function supervised(
 	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 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,
@@ -405,9 +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)
 
+	run_wake_session.keep_awake(process.pid)
+
 	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
@@ -467,16 +364,12 @@ const run_wake_cli = {
 	SUPERVISING_VERDICT,
 	UNKNOWN_VERDICT,
 	USAGE,
-	finish,
 	RELOAD_FAILED_NOTE,
-	record_failure,
 	reload,
 	restart_supervisor,
 	run,
 	start_for_launch,
-	stop_body,
 	supervised,
-	warning_body,
 }
 
 export { run_wake_cli }

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

@@ -23,31 +23,73 @@ interface CodeSource {
 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.
-function is_changed(loaded: string | undefined, current: string | undefined): boolean {
-	if (loaded === undefined || current === undefined) return false
+// 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
 }
 
-async function is_stale(state: CodeState, source: CodeSource): Promise<boolean> {
+// **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()
-	if (head === state.head) return false
+	const is_suspect = is_suspected() || state.is_suspect
+	if (!is_suspect && head === state.head) return false
+
+	const current = await source.closure()
 
-	state.head = head
+	consume(state, { head, is_suspect }, current)
 
-	return is_changed(state.loaded, await source.closure())
+	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.
-async function watch(source: CodeSource): Promise<() => Promise<boolean>> {
-	const state: CodeState = { head: await source.head(), loaded: await source.closure() }
+// 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)
+	return async () => await is_stale(state, source, is_suspected)
 }
 
 async function read_head(): Promise<string | undefined> {

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'
@@ -14,7 +15,8 @@ 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_MINUTES = 5
+const WINDOW_MS = WINDOW_MINUTES * MS_PER_MINUTE
 const WINDOW_VERDICT = 'window'
 
 function driver_args(invocation: string): ReadonlyArray<string> | undefined {
@@ -27,7 +29,7 @@ function driver_args(invocation: string): ReadonlyArray<string> | undefined {
 		'--owner',
 		String(process.pid),
 		'--window',
-		WINDOW_MINUTES,
+		String(WINDOW_MINUTES),
 		...rebuilt.split(' ').slice(1 + named_count),
 	]
 }
@@ -222,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 }

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

@@ -0,0 +1,137 @@
+import { telegram_notify } from '#scripts/notify/telegram-notify'
+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_stranded_detect, type WatchedRun } from '#scripts/run/run-stranded-detect'
+import type { WakeStopReason } from './run-wake'
+import type { WakeContext } from './run-wake-describe'
+import { run_wake_loop, type LoopStop } from './run-wake-loop'
+
+// How a `run:wake --loop` supervisor ends: which stops reach a person, what the warning says, the
+// `stranded` event it leaves, and the verdict and exit code it ends on. The CLI that runs the loop is
+// `run-wake-cli.ts`.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+// 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,
+	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.',
+}
+
+// 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-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
+}
+
+// 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 warn_and_record(
+	stop: LoopStop,
+	body: string,
+	context: WakeContext,
+	started_at: string,
+): Promise<void> {
+	console.error(stop.note ?? body)
+	const is_warned = await warn_of_stop(stop, body, context)
+
+	await record_failure(stop, { ...context, started_at }, is_warned)
+}
+
+// A failure that reached nobody is the defect, so the Telegram goes out before the verdict is printed.
+async function finish(stop: LoopStop, context: WakeContext, started_at: string): Promise<number> {
+	const body = stop_body(stop.reason)
+
+	if (body !== undefined) await warn_and_record(stop, body, context, started_at)
+
+	console.info(stop.reason)
+
+	return exit_code_of(stop.reason)
+}
+
+const run_wake_finish = {
+	finish,
+	record_failure,
+	stop_body,
+	warning_body,
+}
+
+export { run_wake_finish }

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

@@ -50,7 +50,8 @@ interface LoopPorts {
 	wake: (invocation: string, session_id: string, material: string) => LaunchResult
 	sleep: (milliseconds: number) => Promise<void>
 	now: () => Date
-	// Closes again a lane a process outlived, once the process is gone (`lane_close.retry_closes`).
+	// Closes again a lane a process outlived, once the process is gone (`lane_close.retry_closes`), and
+	// withdraws a lane whose issue was closed as not planned (`lane_withdraw_closed.withdraw_closed`).
 	retry_closes: () => Promise<void>
 	// Whether the code this process loaded differs from the code on disk now (`run-wake-code.ts`).
 	is_code_stale: () => Promise<boolean>
@@ -159,8 +160,9 @@ async function decide_pass(wake: RunWake, ports: LoopPorts): Promise<WakeDecisio
 	return run_wake.decide({ ...input, has_work: await ports.has_work(input.read) })
 }
 
-// A lane whose close a process outlived ends once the process is gone (joshuafolkken/kit#4300). A
-// failed retry is the next pass's to try again, never a reason to stop the run.
+// A lane whose close a process outlived ends once the process is gone (joshuafolkken/kit#4300), and
+// a lane whose issue was closed as not planned is withdrawn (joshuafolkken/kit#4915). A failed retry
+// is the next pass's to try again, never a reason to stop the run.
 async function retry_closes(ports: LoopPorts): Promise<void> {
 	try {
 		await ports.retry_closes()