@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/run/{run-ship-review-steps.ts → ship/run-ship-review-steps.ts}

@@ -6,7 +6,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { openai_review_broker } from '#scripts/lane/openai-review-broker'
 import { review_record } from '#scripts/review/review-record'
-import { detached_launch } from './detached-launch'
+import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
 import { run_ship_scoped, type Phase } from './run-ship-scoped'
 
@@ -59,8 +59,8 @@ function failure(out: string): JoshResult {
 	return { code: FAILURE_EXIT_CODE, out }
 }
 
-function paths(root: string = PROJECT_ROOT): { brief: string; findings: string; log: string } {
-	return openai_review_broker.review_paths(root)
+function paths(): { brief: string; findings: string; log: string } {
+	return openai_review_broker.review_paths(PROJECT_ROOT)
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {

package/scripts/run/{run-ship-scoped.ts → ship/run-ship-scoped.ts}

@@ -39,7 +39,16 @@ async function scoped_pair(): Promise<JoshResult> {
 	)
 }
 
-const run_ship_scoped = { run_phases, scoped_pair }
+// The scoped pair and then `josh gate` — the gate stage, and the followup's gate over a merged tree
+// before its push (joshuafolkken/kit#3307), so both leave the record the pre-push hook reuses.
+async function scoped_gate(): Promise<JoshResult> {
+	return await run_phases([
+		scoped_pair,
+		async () => await josh_command.josh_run(['gate'], should_forward_stderr),
+	])
+}
+
+const run_ship_scoped = { run_phases, scoped_gate, scoped_pair }
 
 export type { Phase }
 export { run_ship_scoped }

package/scripts/run/{run-ship-steps.ts → ship/run-ship-steps.ts}

@@ -48,22 +48,20 @@ const PREFLIGHT_STEP: Step = {
 // with no green record (joshuafolkken/kit#2946). The commit step carries the `--skip-*` flags a resumed
 // ship needs, so an existing commit or push is never made twice.
 const COMMIT_STEPS: ReadonlyArray<Step> = [
-	{
-		stage: STAGE.GATE,
-		header: run_ship.GATE_HEADER,
-		run: async () =>
-			await run_ship_scoped.run_phases([
-				run_ship_scoped.scoped_pair,
-				async () => await josh(['gate']),
-			]),
-	},
-	// joshuafolkken/kit#3221: the default branch merged again right before the commit, so the pull
-	// request opens on a branch that is current; a clean merge goes on without waking anyone.
+	// joshuafolkken/kit#3221: the default branch merged again before the commit, so the pull request
+	// opens on a branch that is current; a clean merge goes on without waking anyone. It runs before the
+	// gate (joshuafolkken/kit#3307): a merge after it moved the merge base the gate's record pins, so the
+	// pre-push hook could never reuse that record and re-ran the whole unit suite on every merged ship.
 	{
 		stage: STAGE.SYNC,
 		header: run_ship.SYNC_HEADER,
 		run: async () => await run_ship_sync.sync_stage(),
 	},
+	{
+		stage: STAGE.GATE,
+		header: run_ship.GATE_HEADER,
+		run: async () => await run_ship_scoped.scoped_gate(),
+	},
 	{
 		stage: STAGE.COMMIT,
 		header: run_ship.COMMIT_HEADER,
@@ -87,7 +85,8 @@ const MERGE_STEPS: ReadonlyArray<Step> = [
 ]
 
 // `--review` (joshuafolkken/kit#2427) puts the supervised round-1 review in front of the gate: it
-// launches the gate itself, so the gate stage that follows reuses that tree's green record. It also
+// launches the gate itself, so the gate stage that follows reuses that tree's green record unless the
+// sync stage between them merged the default branch and changed the tree. It also
 // puts the round-2 pass between the commit and the followup (joshuafolkken/kit#2489), so the PR opens
 // between the rounds and round 2 runs beside CI — a no-op when round 1 left no fix delta.
 const REVIEW_STEP: Step = {

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

@@ -0,0 +1,13 @@
+// The text a `josh ship` supervisor records when a stage stops, written and read in one place so the
+// retrospective's per-stage count never drifts from the writer (joshuafolkken/kit#3245).
+const STOP_PATTERN = /^#\d+ (\S+) failed — /u
+
+function format(issue: string, reason: string): string {
+	return `#${issue} ${reason} failed — pnpm josh ship --log ${issue}`
+}
+
+function reason_of(text: string): string | undefined {
+	return STOP_PATTERN.exec(text)?.[1]
+}
+
+export const run_ship_stop_text = { format, reason_of }

package/scripts/run/{run-ship-sync.ts → ship/run-ship-sync.ts}

@@ -26,6 +26,7 @@ const MAX_MERGE_RETRIES = 2
 const CONFLICT_NOTE = 'merging the default branch left unmerged paths:'
 const DEFERRED_PREFIX = 'merge deferred to the followup: '
 const CURRENT_SUFFIX = ' brings nothing in'
+const MERGED_PREFIX = 'merged '
 
 // A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
 interface StepResult extends JoshResult {
@@ -52,21 +53,24 @@ function conflict_result(files: ReadonlyArray<string>, lead: string): StepResult
 	return { code: FAILURE_EXIT_CODE, out, conflicts: files }
 }
 
+function sync_note(outcome: Exclude<MergeOutcome, { kind: 'conflict' }>): string {
+	if (outcome.kind === 'refused') return `${DEFERRED_PREFIX}${outcome.message}`
+
+	return outcome.kind === 'current'
+		? `${outcome.branch}${CURRENT_SUFFIX}`
+		: `${MERGED_PREFIX}${outcome.branch}`
+}
+
 // A refusal does not stop the commit: the guard refuses only uncommitted work the default branch also
 // touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
-// the tree meets the scoped pair again, so the commit never carries an unchecked merge.
+// the tree is checked by the gate stage that follows (joshuafolkken/kit#3307), 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> {
 	const outcome = await merge_outcome()
 
 	if (outcome.kind === 'conflict') return conflict_result(outcome.files, '')
-	if (outcome.kind === 'merged') return await run_ship_scoped.scoped_pair()
-
-	const out =
-		outcome.kind === 'current'
-			? `${outcome.branch}${CURRENT_SUFFIX}`
-			: `${DEFERRED_PREFIX}${outcome.message}`
 
-	return { code: SUCCESS_EXIT_CODE, out }
+	return { code: SUCCESS_EXIT_CODE, out: sync_note(outcome) }
 }
 
 // Any read that fails answers "not conflicting": the followup failure then stands as it was.
@@ -80,6 +84,18 @@ async function is_conflicting(): Promise<boolean> {
 	}
 }
 
+// The merged tree is gated before it is pushed (joshuafolkken/kit#3307): the push then carries the tree
+// the gate's record describes, so the pre-push hook reuses it rather than re-running the unit suite.
+async function push_merged(title: string): Promise<StepResult | undefined> {
+	const gate = await run_ship_scoped.scoped_gate()
+
+	if (gate.code !== SUCCESS_EXIT_CODE) return gate
+
+	const push = await josh(['git', '-y', '--skip-commit', '--skip-pr', title])
+
+	return push.code === SUCCESS_EXIT_CODE ? undefined : push
+}
+
 // The result to stop on, or `undefined` once a clean merge is pushed and the followup can wait again.
 async function merge_again(title: string, failed: JoshResult): Promise<StepResult | undefined> {
 	if (!(await is_conflicting())) return failed
@@ -89,9 +105,7 @@ async function merge_again(title: string, failed: JoshResult): Promise<StepResul
 	if (outcome.kind === 'conflict') return conflict_result(outcome.files, failed.out)
 	if (outcome.kind !== 'merged') return failed
 
-	const push = await josh(['git', '-y', '--skip-commit', '--skip-pr', title])
-
-	return push.code === SUCCESS_EXIT_CODE ? undefined : push
+	return await push_merged(title)
 }
 
 async function followup_stage(

package/scripts/run/{run-tidy-lanes.ts → tidy/run-tidy-lanes.ts}

@@ -3,7 +3,7 @@ import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { error_text } from '#scripts/lib/error-message'
-import { run_hold } from './run-hold'
+import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_tidy, type Outcome, type Verdict } from './run-tidy'
 
 // The lane half of `josh run:tidy` (joshuafolkken/kit#2701): each lane whose issue merged, read for

package/scripts/run/{run-wake-cli.ts → wake/run-wake-cli.ts}

@@ -4,15 +4,17 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 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 './run-carry'
-import { run_event_stream } from './run-event-stream'
-import { run_headless } from './run-headless'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_headless } from '#scripts/run/run-headless'
 import { run_wake, type RunWake, type WakeStopReason, type WakeTidyResult } from './run-wake'
 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'
 
 // `josh run:wake --start | --list | --stop | --loop` — the supervisor that continues a cut
@@ -72,9 +74,8 @@ const WARNING_RECOVERY = `Check the wake command, then restart with \`pnpm josh
 //
 // **`expired` and `unreadable` were silent until joshuafolkken/kit#1746, and that was the defect
 // rather than the design.** Both end the supervisor while a carry record is still sitting there handed
-// off, so the run is left asleep with nothing anywhere saying so — `run-wake.ts` →
-// `is_predecessor_exiting` names the `expired` one as a silent overnight failure in as many words, and
-// then only the `failed` reason was wired to the notification.
+// off, so the run is left asleep with nothing anywhere saying so — a silent overnight failure, while
+// only the `failed` reason was wired to the notification.
 // **Every reason is listed, and the silent two are listed as `undefined`.** A partial map would let a
 // sixth stop reason compile straight past this and reach nobody, which is the defect class this
 // section exists to close.
@@ -309,6 +310,22 @@ 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 (joshuafolkken/kit#3332).
+// **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)
 
@@ -321,11 +338,8 @@ async function loop(context: WakeContext, interval_ms: number): Promise<number>
 
 	if (claimed === undefined) return report(RUNNING_VERDICT)
 
-	const stop = await run_wake_loop.run_loop(
-		context.wake_target,
-		ports_for(context, claimed.profile ?? profile),
-		interval_ms,
-	)
+	const ports = ports_for(context, claimed.profile ?? profile)
+	const stop = await run_wake_restart.supervise(restart_ports(context, ports, interval_ms))
 
 	tidy_up(context.wake_target)
 

package/scripts/run/{run-wake-describe.ts → wake/run-wake-describe.ts}

@@ -1,10 +1,10 @@
 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 } from './run-carry'
-import { run_event_stream } from './run-event-stream'
-import { run_liveness } from './run-liveness'
-import { run_wake, type RunWake } from './run-wake'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+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'
 
 // The `--list` presentation of a wake record (joshuafolkken/kit#2407 split it out of `run-wake-cli.ts`,
 // which had reached its line limit). What the command *does* stays in the CLI; how a supervisor's
@@ -13,6 +13,7 @@ import { run_wake, type RunWake } from './run-wake'
 const UNKNOWN_CUTS = 'an unreadable number of'
 const REPO_LOOKUP_TIMEOUT_MS = 10_000
 const STOP_COMMAND = 'pnpm josh run:wake --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
 // woken session runs in. The work tree is the common git directory's parent, which is the *primary*
@@ -49,6 +50,55 @@ function outstanding_line(wake: RunWake): string | undefined {
 	return `${String(wake.attempts)} launch(es) outstanding for the current cut, none claimed yet`
 }
 
+// **Why the supervisor is not launching, and until when** (joshuafolkken/kit#3363). A supervisor that
+// waits writes nothing to its log, so before this `--list` showed a stalled run and a waiting one
+// alike. The state is `run_wake.decide`'s own answer rather than a second reading of the record: an
+// `idle_since` mark is the last pass having found no work, so it is fed back in as `has_work: false`.
+function wait_input(wake: RunWake, read: CarryRead, now: Date): WakeDecisionInput {
+	return {
+		read,
+		woke_at: wake.woke_at,
+		attempts: wake.attempts ?? 0,
+		is_owner_live: read.kind === 'carried' && run_carry.is_owner_live(read.carry, now),
+		has_work: wake.idle_since === undefined ? undefined : false,
+		idle_since: wake.idle_since,
+		now,
+	}
+}
+
+function deadline(marked_at: string | undefined, limit_ms: number): string {
+	const marked = Date.parse(marked_at ?? '')
+
+	return Number.isNaN(marked) ? UNREADABLE_TIME : new Date(marked + limit_ms).toISOString()
+}
+
+// A live owner that is this supervisor is its own driver at work; any other is a session spending the
+// budget, which has no deadline of its own short of the carry record's whole-run expiry.
+function owner_wait(wake: RunWake, carry: RunCarry): string {
+	if (carry.owner_pid === wake.pid) {
+		return 'waiting: the driver holds the carry record and is running'
+	}
+
+	const expiry = deadline(carry.started_at, run_carry.CARRY_MAX_AGE_MS)
+
+	return `waiting: process ${String(carry.owner_pid)} holds the carry record; the driver starts at its next cut or once it exits, and the record expires at ${expiry}`
+}
+
+const WAIT_LINES: Partial<Record<WakeDecision['kind'], (wake: RunWake) => string>> = {
+	pending: (wake) =>
+		`waiting: the woken session has until ${deadline(wake.woke_at, run_wake.WAKE_GRACE_MS)} to claim the carry record`,
+	idle: (wake) =>
+		`waiting: no runnable work; the driver starts anyway at ${deadline(wake.idle_since, run_wake.IDLE_CEILING_MS)}`,
+}
+
+function wait_line(wake: RunWake, read: CarryRead, now: Date): string | undefined {
+	const { kind } = run_wake.decide(wait_input(wake, read, now))
+
+	if (kind === 'wait' && read.kind === 'carried') return owner_wait(wake, read.carry)
+
+	return WAIT_LINES[kind]?.(wake)
+}
+
 // The run's stream, read here because a headless parent's progress reaches its own transcript alone —
 // after a cut, `--list` is the person's one window onto it (joshuafolkken/kit#1910). Two lines: the
 // newest event (the degenerate last-event read of the stream the watch pane follows, so `--list` and
@@ -73,16 +123,17 @@ function stream_lines(context: WakeContext): Array<string> {
 // **The outstanding line beside it is what makes a shortfall readable**: the count is observed at a
 // poll, so it lags a claim by up to one interval, and launches still outstanding are what say whether
 // a missing wake is one not yet seen or one that never arrived.
-function describe_wake(wake: RunWake, context: WakeContext): string {
+function describe_wake(wake: RunWake, context: WakeContext, now: Date = new Date()): string {
 	const live = run_wake.is_supervisor_live(wake) ? 'running' : 'not running'
-	const cuts = carry_cuts(run_carry.read_carry(context.carry_target))
+	const read = run_carry.read_carry(context.carry_target)
 
 	return [
 		`invocation: ${wake.invocation}`,
 		`profile: ${wake.profile === undefined ? 'unrecorded' : agent_role_profile.describe(wake.profile)}`,
 		`supervisor: process ${String(wake.pid)} (${live}), watching since ${wake.started_at}`,
-		`woke ${String(wake.woke)} session(s) across ${cuts} cut(s)`,
+		`woke ${String(wake.woke)} session(s) across ${carry_cuts(read)} cut(s)`,
 		outstanding_line(wake),
+		wait_line(wake, read, now),
 		run_liveness.describe_agent_state(context.log_target),
 		`output: ${context.log_target}`,
 		// How progress is seen without asking after the cut: the run's stream, followed from here

package/scripts/run/{run-wake-driver.ts → wake/run-wake-driver.ts}

@@ -1,6 +1,6 @@
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
-import { run_carry, type CarryRead } from './run-carry'
-import { run_invocation } from './run-invocation'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
+import { run_invocation } from '#scripts/run/run-invocation'
 import type { DriveResult } from './run-wake-loop'
 
 const SUCCESS = 0
@@ -114,7 +114,12 @@ function failure_note(result: JoshResult): string {
 	return [cause_of(result.out), details_tail(result.err ?? '')].filter(Boolean).join('\n')
 }
 
-function read_result(result: JoshResult, target: string, invocation: string): DriveResult {
+function read_result(
+	result: JoshResult | undefined,
+	target: string,
+	invocation: string,
+): DriveResult {
+	if (result === undefined) return { kind: 'released' }
 	if (result.code !== SUCCESS) return { kind: 'failed', note: failure_note(result) }
 
 	return driver_result(result.out, run_carry.read_carry(target), invocation, result.err)
@@ -128,7 +133,51 @@ function claim_record(target: string, invocation: string): boolean {
 	return run_carry.adopt_carry(target, current.carry, run_carry.owner_of(process.pid)) !== undefined
 }
 
-async function drive(target: string): Promise<DriveResult> {
+// **A verdict with nothing to judge is re-driven here, never handed to a session** (joshuafolkken/kit#3245).
+// A woken session met with `window`, `merge busy` or `merge retry` only cut and handed the loop back, and
+// the supervisor then ran the very same driver again — a model round trip, at a cache write each, that
+// decided 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']
+const RERUN_LIMIT = 10
+const RERUN_PAUSE_MS = 60_000
+
+type Pause = (ms: number) => Promise<void>
+
+async function pause(ms: number): Promise<void> {
+	await new Promise((resolve) => {
+		setTimeout(resolve, ms)
+	})
+}
+
+function is_mechanical(result: JoshResult): boolean {
+	const verdict = result.out.split('\n', 1)[FIRST_LINE] ?? ''
+
+	return (
+		result.code === SUCCESS &&
+		RERUN_VERDICTS.some((entry) => verdict === entry || verdict.startsWith(`${entry} `))
+	)
+}
+
+// A record that expired or 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 `expired`
+// or `stopped`; a rerun would only fail on it and report the run as `failed`.
+async function run_driver(
+	target: string,
+	args: ReadonlyArray<string>,
+	wait: Pause,
+	remaining: number,
+): Promise<JoshResult | undefined> {
+	const result = await josh_command.josh_run(args, true)
+	if (remaining === 0 || !is_mechanical(result)) return result
+
+	await wait(RERUN_PAUSE_MS)
+	if (run_carry.read_carry(target).kind !== 'carried') return undefined
+
+	return await run_driver(target, args, wait, remaining - 1)
+}
+
+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.' }
 
@@ -139,9 +188,11 @@ async function drive(target: string): Promise<DriveResult> {
 		return { kind: 'failed', note: 'The driver could not claim the carry record.' }
 	}
 
-	const result = await josh_command.josh_run(args, true)
-
-	return read_result(result, target, read.carry.invocation)
+	return read_result(
+		await run_driver(target, args, wait, RERUN_LIMIT),
+		target,
+		read.carry.invocation,
+	)
 }
 
-export const run_wake_driver = { drive, driver_args, driver_result }
+export const run_wake_driver = { RERUN_LIMIT, drive, driver_args, driver_result }

package/scripts/run/{run-wake-handoff.ts → wake/run-wake-handoff.ts}

@@ -1,5 +1,5 @@
 import { stamp_file } from '#scripts/josh/stamp-file'
-import { run_carry } from './run-carry'
+import { run_carry } from '#scripts/run/carry/run-carry'
 
 // The supervisor's recovery hand-off (joshuafolkken/kit#2437). A session that claimed the carry record
 // and then died without `run:carry --cut` leaves it `carried`, owned by a gone process, with no

package/scripts/run/{run-wake-loop.ts → wake/run-wake-loop.ts}

@@ -1,4 +1,4 @@
-import type { CarryRead } from './run-carry'
+import type { CarryRead } from '#scripts/run/carry/run-carry'
 import {
 	run_wake,
 	type RunWake,
@@ -35,9 +35,8 @@ interface LoopPorts {
 	// The carry record, re-read every pass rather than cached: it is written by the parent loop of a
 	// different session, which is the whole point of reading it here.
 	read_carry: () => CarryRead
-	// Whether the process named on the carry record is still running. The cutting session writes
-	// `--cut` and then exits, so the two moments are not the same one and the supervisor has to wait
-	// out the second — `run-wake.ts` → `WakeDecisionInput.is_owner_live`.
+	// Whether the process named on the carry record is still running, which tells a session at work
+	// from a crashed one — `run-wake.ts` → `WakeDecisionInput.is_owner_live`.
 	is_owner_live: (read: CarryRead) => boolean
 	// A compatibility probe for the wake decision. Production lets the resident driver inspect work,
 	// including an empty idle watch, without starting an AI session.
@@ -56,8 +55,13 @@ interface LoopPorts {
 	now: () => Date
 }
 
+// `released`: the carry record ended while the driver paused, so there is nothing to hand on and the
+// next pass decides from the record how the run ends.
 type DriveResult =
-	{ kind: 'finished' } | { kind: 'judgment'; material: string } | { kind: 'failed'; note: string }
+	| { kind: 'finished' }
+	| { kind: 'released' }
+	| { kind: 'judgment'; material: string }
+	| { kind: 'failed'; note: string }
 
 interface LoopStop {
 	reason: WakeStopReason
@@ -89,6 +93,7 @@ async function wake_step(wake: RunWake, ports: LoopPorts): Promise<StepOutcome>
 	const driven = await ports.drive()
 	if (driven.kind === 'finished') return stopped('ended')
 	if (driven.kind === 'failed') return stopped(FAILED_REASON, driven.note)
+	if (driven.kind === 'released') return { kind: 'continue', wake }
 
 	const session_id = ports.new_session_id()
 
@@ -104,17 +109,11 @@ async function wake_step(wake: RunWake, ports: LoopPorts): Promise<StepOutcome>
 // A `wait` means the woken session has claimed the carry record, so the wake mark is cleared and the
 // next cut starts the grace window afresh — **and it is the only pass on which `woke` may grow**
 // (joshuafolkken/kit#1746), because arriving here is the supervisor observing that a record it was
-// waiting on has been taken over. A `hold` starts the ceiling on a wait without launching
-// anything — the bounded wait on a predecessor that has cut but not yet exited, which ends the moment
-// that predecessor does. A `pending` keeps what is there, because the window it is measured from is
-// still open.
+// waiting on has been taken over. A `pending` keeps what is there, because the window it is measured
+// from is still open.
 function continue_step(wake: RunWake, decision: WakeDecision, ports: LoopPorts): StepOutcome {
 	if (decision.kind === 'wait') return { kind: 'continue', wake: run_wake.count_claim(wake) }
 
-	if (decision.kind === 'hold') {
-		return { kind: 'continue', wake: run_wake.mark_wait(wake, ports.now()) }
-	}
-
 	if (decision.kind === 'idle') {
 		return { kind: 'continue', wake: run_wake.mark_idle(wake, ports.now()) }
 	}
@@ -140,7 +139,6 @@ function decision_input(wake: RunWake, ports: LoopPorts): WakeDecisionInput {
 		woke_at: wake.woke_at,
 		attempts: wake.attempts ?? NO_ATTEMPTS,
 		is_owner_live: ports.is_owner_live(read),
-		held_at: wake.held_at,
 		has_work: undefined,
 		idle_since: wake.idle_since,
 		now: ports.now(),
@@ -149,7 +147,7 @@ function decision_input(wake: RunWake, ports: LoopPorts): WakeDecisionInput {
 
 // **Work is asked about only where the answer could change the decision** (joshuafolkken/kit#2417):
 // on a pass the record alone would launch from. Every other pass — the in-flight wait, the pending
-// grace window, the hold — decides from the record as before and costs no backlog read.
+// grace window — decides from the record as before and costs no backlog read.
 async function decide_pass(wake: RunWake, ports: LoopPorts): Promise<WakeDecision> {
 	const input = decision_input(wake, ports)
 	const decision = run_wake.decide(input)

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

@@ -0,0 +1,58 @@
+import { run_wake_loop, type LoopStop } from './run-wake-loop'
+
+// **A supervisor that fails while the run is still resumable restarts itself** (joshuafolkken/kit#3332).
+// A `backlog:drive` that exited on a transient `main:sync` failure ended the supervisor as `failed`,
+// and the run then sat for forty minutes with a valid carry record, waiting for one `run:wake --start`
+// that only a person was left to type — joshuafolkken/kit#3297's "resume it yourself" rule binds an AI
+// session, and once the supervisor is gone there is none to read it.
+//
+// **Bounded, and only the bound reaches a person.** A failure that is not transient fails again on
+// every pass, so the restarts stop at `RESTART_LIMIT` and the last failure is handed back for the
+// ordinary warning, its note saying how many restarts went before it.
+
+const RESTART_LIMIT = 3
+
+interface RestartPorts {
+	// One run of the loop over the record the caller claimed once and holds across every restart, so a
+	// `--stop` landing in the pause is read by the next pass as the person's stop.
+	pass: () => Promise<LoopStop>
+	// Whether the carry record can still be continued — `carried`, neither `expired` nor gone.
+	is_resumable: () => boolean
+	pause: () => Promise<void>
+	note: (text: string) => void
+}
+
+function is_restartable(stop: LoopStop, restarts: number, ports: RestartPorts): boolean {
+	return (
+		stop.reason === run_wake_loop.FAILED_REASON && restarts < RESTART_LIMIT && ports.is_resumable()
+	)
+}
+
+function restart_note(stop: LoopStop, restarts: number): string {
+	return `the supervisor failed (${stop.note ?? 'no note'}); restarting it, ${String(restarts + 1)} of ${String(RESTART_LIMIT)}`
+}
+
+function with_restart_count(stop: LoopStop, restarts: number): LoopStop {
+	if (restarts === 0 || stop.reason !== run_wake_loop.FAILED_REASON) return stop
+
+	return {
+		...stop,
+		note: [stop.note, `after ${String(restarts)} automatic restarts`].filter(Boolean).join('\n'),
+	}
+}
+
+async function supervise(ports: RestartPorts, restarts = 0): Promise<LoopStop> {
+	const stop = await ports.pass()
+
+	if (!is_restartable(stop, restarts, ports)) return with_restart_count(stop, restarts)
+
+	ports.note(restart_note(stop, restarts))
+	await ports.pause()
+
+	return await supervise(ports, restarts + 1)
+}
+
+const run_wake_restart = { RESTART_LIMIT, supervise }
+
+export { run_wake_restart }
+export type { RestartPorts }

package/scripts/run/{run-wake-session.ts → wake/run-wake-session.ts}

@@ -1,8 +1,8 @@
 import { agent_argv, type AgentArgvResult } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { claude_agent_argv } from '#scripts/agent/claude-agent-argv'
-import { detached_launch, type LaunchArgv } from './detached-launch'
-import { run_invocation } from './run-invocation'
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
+import { run_invocation } from '#scripts/run/run-invocation'
 
 // How the supervisor starts things: the next agent session, and — at `--start` — its own detached
 // self. Both go through one `launch`, because the two differ only in what is being run
@@ -159,5 +159,5 @@ const run_wake_session = {
 	wake_argv,
 }
 
-export type { LaunchRequest, LaunchResult } from './detached-launch'
+export type { LaunchRequest, LaunchResult } from '#scripts/run/detached-launch'
 export { run_wake_session }