@joshuafolkken/kit 1.1178.0 → 1.1229.0

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

@@ -7,6 +7,7 @@ import { git_preflight } from '#scripts/git/git-preflight'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
 import { live_evidence } from '#scripts/review/live-evidence'
+import { run_ship_lock } from './run-ship-lock'
 import { run_ship_scoped } from './run-ship-scoped'
 
 // `josh ship`'s first stage (joshuafolkken/kit#2946). A detached ship used to meet the pull request's
@@ -71,13 +72,16 @@ async function caught(problems: Promise<Array<string>>): Promise<Array<string>>
 	}
 }
 
+// The lock file is asked here too (joshuafolkken/kit#3307), so a drift stops the ship before the gate
+// rather than being rewritten by the pre-push hook's install under the push.
 async function asked_problems(request: PreflightRequest): Promise<Array<string>> {
-	const [preflight, evidence] = await Promise.all([
+	const [preflight, evidence, lock] = await Promise.all([
 		caught(git_preflight.problems_of({ cli_input: request.title, will_open_pr: true })),
 		caught(evidence_problems(request.body_path)),
+		caught(run_ship_lock.lock_problems()),
 	])
 
-	return [...preflight, ...evidence]
+	return [...preflight, ...evidence, ...lock]
 }
 
 async function stage(request: PreflightRequest): Promise<JoshResult> {

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

@@ -1,8 +1,8 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { error_text } from '#scripts/lib/error-message'
-import { run_hold } from './run-hold'
-import { run_preflight } from './run-preflight'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_preflight } from '#scripts/run/run-preflight'
 import { run_ship_stage, type ShipState } from './run-ship-stage'
 
 // The read side of a resumed `josh ship` (joshuafolkken/kit#2426): the repository's actual state, asked

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

@@ -3,10 +3,11 @@ import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
+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 type { ShipResume } from './run-ship-next'
 import { run_ship_stage, type Stage } from './run-ship-stage'
+import { run_ship_stop_text } from './run-ship-stop-text'
 
 // How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
 // ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
@@ -29,7 +30,7 @@ const OPENAI_PROVIDER = 'openai'
 type ReturnOutcome = 'relaunched' | 'recorded'
 
 function stop_text(issue: string, stage: Stage, resume: ShipResume): string {
-	return `#${issue} ${run_ship_stage.stop_reason(stage, resume.conflicts)} failed — pnpm josh ship --log ${issue}`
+	return run_ship_stop_text.format(issue, run_ship_stage.stop_reason(stage, resume.conflicts))
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {

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
@@ -309,6 +311,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 +339,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,9 +1,9 @@
 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_carry, type CarryRead } 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 } from './run-wake'
 
 // The `--list` presentation of a wake record (joshuafolkken/kit#2407 split it out of `run-wake-cli.ts`,

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,
@@ -56,8 +56,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 +94,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()
 

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 }

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

@@ -3,8 +3,8 @@ import { backlog_budget } from '#scripts/backlog/backlog-budget'
 import { process_identity } from '#scripts/josh/process-identity'
 import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import type { CarryRead } from '#scripts/run/carry/run-carry'
 import { z } from 'zod'
-import type { CarryRead } from './run-carry'
 
 // joshuafolkken/kit#1719. joshuafolkken/kit#1714 made a `backlogrun`'s budget survive the session cut
 // and left out the one thing that starts the next session, so the record was carried and the

package/scripts/safe-chain/preinstall-command.ts

@@ -1,38 +1,37 @@
-// `setup-ci` only writes shims and adds them to PATH on a CI runner, so a local `pnpm install` is
-// scanned only when the developer has enabled safe-chain's own shell integration. That integration
-// runs pnpm behind safe-chain's registry proxy and hands `GLOBAL_AGENT_HTTP_PROXY` to it, which a bare
-// pnpm never sets — the one signal a lifecycle script can read (joshuafolkken/kit#2707).
-const SETUP_CI_CMD = 'pnpm dlx @aikidosec/safe-chain setup-ci'
-const LEGACY_PREINSTALL_RE = /^pnpm dlx @aikidosec\/safe-chain(?:@\S+)? setup-ci$/u
+// The `preinstall` kit writes fetches nothing: it only checks that safe-chain is scanning the install
+// and warns when it is not (joshuafolkken/kit#3269). It used to run `pnpm dlx @aikidosec/safe-chain
+// setup-ci`, which downloaded an unverified package on every install and — `setup-ci` acting only on
+// a CI runner, where kit installs with `--ignore-scripts` — protected nothing. safe-chain's shell
+// integration runs pnpm behind its registry proxy and hands `GLOBAL_AGENT_HTTP_PROXY` to it, which a
+// bare pnpm never sets — the one signal a lifecycle script can read (joshuafolkken/kit#2707).
+const INSTALL_GUIDE_ANCHOR = 'installing-safe-chain'
+const INSTALL_GUIDE_URL = `https://github.com/joshuafolkken/kit/blob/main/SECURITY.md#${INSTALL_GUIDE_ANCHOR}`
+// `.pnpmfile.mjs` recognizes the command by the package name, so the hint names it.
 const INTEGRATION_HINT =
-	'Warning: safe-chain is not scanning this install because its shell integration is not active.' +
-	' Install safe-chain (https://github.com/AikidoSec/safe-chain#installation) or run: safe-chain setup' +
+	'Warning: safe-chain (@aikidosec/safe-chain) is not scanning this install because its shell' +
+	` integration is not active. Install it with the hash-verified steps at ${INSTALL_GUIDE_URL}` +
 	' - then restart your terminal.'
 // `preinstall` runs before any dependency is installed, kit included, so the check is plain Node with
 // no imports. It never fails the install and stays silent on CI, where the runner is set up instead.
 // The source avoids double quotes, `$` and backticks so the shell passes it to Node verbatim.
 const LOCAL_INTEGRATION_CHECK_SOURCE = `if(!process.env.CI&&!process.env.GLOBAL_AGENT_HTTP_PROXY)console.warn('${INTEGRATION_HINT}')`
-const LOCAL_INTEGRATION_CHECK_CMD = `node -e "${LOCAL_INTEGRATION_CHECK_SOURCE}"`
+const SAFE_CHAIN_CMD = `node -e "${LOCAL_INTEGRATION_CHECK_SOURCE}"`
+// Every `preinstall` an earlier kit wrote: `setup-ci` alone, pinned or not, or followed by the
+// `node -e` check of any earlier wording.
+const LEGACY_PREINSTALL_RE =
+	/^pnpm dlx @aikidosec\/safe-chain(?:@\S+)? setup-ci(?: && node -e "[^"]*")?$/u
 
-function with_local_check(setup_command: string): string {
-	return `${setup_command} && ${LOCAL_INTEGRATION_CHECK_CMD}`
-}
-
-// Upgrade a `preinstall` kit wrote before the check existed, pinned version included; any other
-// value is the consumer's own and is left exactly as it is.
+// Replace a `preinstall` kit wrote earlier; any other value is the consumer's own and is left exactly
+// as it is.
 function migrate_preinstall(value: string): string {
-	if (!LEGACY_PREINSTALL_RE.test(value)) return value
-
-	return with_local_check(value)
+	return LEGACY_PREINSTALL_RE.test(value) ? SAFE_CHAIN_CMD : value
 }
 
-const SAFE_CHAIN_CMD = with_local_check(SETUP_CI_CMD)
-
 const safe_chain_preinstall = {
 	SAFE_CHAIN_CMD,
-	LOCAL_INTEGRATION_CHECK_CMD,
 	LOCAL_INTEGRATION_CHECK_SOURCE,
 	INTEGRATION_HINT,
+	INSTALL_GUIDE_ANCHOR,
 	migrate_preinstall,
 }