@joshuafolkken/kit 1.1383.0 → 1.1435.0

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

@@ -1,22 +1,25 @@
 #!/usr/bin/env tsx
 import { randomUUID } from 'node:crypto'
-import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import type { AgentProfile, AgentProvider } from '#scripts/agent/agent-role-profile'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
 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 '#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_wake, type RunWake, type WakeStopReason, type WakeTidyResult } from './run-wake'
+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_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'
+import { run_wake_stop } from './run-wake-stop'
+import { run_wake_supervise } from './run-wake-supervise'
 
 // `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
@@ -83,6 +86,7 @@ const STOP_BODIES: Record<WakeStopReason, string | undefined> = {
 	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 SUPERSEDED_RESULT: WakeTidyResult = 'superseded'
 const SUPERSEDED_NOTE =
 	'another supervisor now holds the record, so it was left alone; this loop is the superseded one'
@@ -131,25 +135,14 @@ function group_count(values: ParsedValues): number {
 	return verbs.filter((flag) => flag === true).length
 }
 
+function context_of(directory: string): WakeContext {
+	return run_wake_describe.context_of(directory, note_to_stderr)
+}
+
 async function resolve_context(): Promise<WakeContext | undefined> {
 	const directory = await run_carry.repository_directory()
 
-	if (directory === undefined) return undefined
-
-	const log_target = run_wake.wake_log_path(directory)
-
-	// Every verb reaches this one function, so creating the log here is what makes the path each of
-	// them prints a path that exists — including `--list` and the already-running branch of `--start`,
-	// neither of which launches anything.
-	run_wake_session.ensure_log(log_target, note_to_stderr)
-
-	return {
-		carry_target: run_carry.carry_path(directory),
-		wake_target: run_wake.wake_path(directory),
-		log_target,
-		event_target: run_event_stream.target_of(directory),
-		worktree: path.dirname(directory),
-	}
+	return directory === undefined ? undefined : context_of(directory)
 }
 
 // There is nothing to supervise unless a run is actually carrying a budget. Refusing here rather than
@@ -161,6 +154,12 @@ 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,
@@ -176,14 +175,20 @@ function wake_session(
 	// 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 run_wake_session.launch({ argv: built.argv, ...target, profile }, note_to_stderr)
+	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_owner_live(read.carry),
+		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: () => {
@@ -211,14 +216,45 @@ function warning_body(stop: LoopStop, body: string, context: WakeContext): strin
 	return [body, log_hint(context), stop.note].filter(Boolean).join('\n')
 }
 
-async function warn_of_stop(stop: LoopStop, body: string, context: WakeContext): Promise<void> {
-	await telegram_notify.warn({
+// Whether the warning reached a person — the answer `record_failure` leaves its marker on.
+async function warn_of_stop(stop: LoopStop, body: string, context: WakeContext): Promise<boolean> {
+	return await telegram_notify.warn({
 		issue_title: WARNING_TITLE,
 		body: warning_body(stop, body, context),
 		recovery: WARNING_RECOVERY,
 	})
 }
 
+// **A failed supervisor that leaves the run stranded says so on the stream, with its cause.** Nothing
+// else writes there when the supervisor gives up, so a reader of the events would see the last merge
+// and a run that looks as if it were still watching. The cause is the note's first line — the
+// driver's own `error …` — because the rest is a stderr tail the log already holds.
+//
+// **Only a strand, and only one a person was told of.** A `failed` stop is not always a strand: a
+// `run:carry --end` under a live driver fails it too, and that run ended cleanly. And the event is the
+// marker `run_stranded_detect` holds its own notification back on, so it is left only when the warning
+// was sent — after a failed send the stop-time detector still finds no marker, and notifies.
+function is_strand_told(stop: LoopStop, watched: WatchedRun, is_warned: boolean): boolean {
+	if (!is_warned || stop.reason !== run_wake_loop.FAILED_REASON) return false
+
+	return run_stranded_detect.is_left_stranded(watched)
+}
+
+async function record_failure(
+	stop: LoopStop,
+	watched: WatchedRun,
+	is_warned: boolean,
+): Promise<void> {
+	if (!is_strand_told(stop, watched, is_warned)) return
+
+	const [cause = ''] = (stop.note ?? '').split('\n', 1)
+
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.STRANDED,
+		`The supervisor failed and stopped watching the run — ${cause}`,
+	)
+}
+
 // **Only a failed wake exits non-zero; `unreadable` warns but exits zero.** The
 // verdict-and-exit-code table in `docs/josh-commands-automation.md` is a contract callers branch on,
 // and what that one needs is the notification, not a different exit code.
@@ -234,25 +270,33 @@ function stop_body(reason: WakeStopReason): string | undefined {
 	return STOP_BODIES[reason]
 }
 
-async function finish(stop: LoopStop, context: WakeContext): Promise<number> {
+// `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)
-	await warn_of_stop(stop, body, context)
+	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 spawn_supervisor(context: WakeContext, interval: string | undefined): number {
-	const profile = run_wake_session.scheduler_profile()
-	if (profile === undefined) return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
+function launch_supervisor(
+	context: WakeContext,
+	interval: string | undefined,
+	profile: AgentProfile | undefined,
+): LaunchResult {
+	if (profile === undefined) return { kind: 'failed', note: NO_PROFILE_NOTE }
 	const argv = run_wake_session.supervisor_argv(SCRIPT_PATH, interval)
+
 	// **The supervisor's own output goes to the same file as the sessions it starts.** It is detached
 	// with the same call, so otherwise its `console.error` — the launch note that says the agent CLI is
 	// not on `PATH`, and the stop note behind every warning — would go nowhere at all.
-	const result = run_wake_session.launch(
+	return run_wake_session.launch(
 		{
 			argv,
 			cwd: context.worktree,
@@ -261,6 +305,20 @@ function spawn_supervisor(context: WakeContext, interval: string | undefined): n
 		},
 		note_to_stderr,
 	)
+}
+
+// The supervisor `josh backlogrun` starts beside its launched parent, on the parent's provider, from its
+// own process so it inherits the credential the parent's Bash tool does not pass on (kit#3804). No carry
+// record stands yet, so `start`'s check is skipped; its `--loop` waits for the parent to claim one.
+function start_for_launch(git_directory: string, provider: AgentProvider): LaunchResult {
+	const resolved = run_wake_session.chosen_profile(provider)
+	if (resolved.kind === 'rejected') return { kind: 'failed', note: resolved.note }
+
+	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())
 
 	if (result.kind === 'failed') {
 		console.error(`Could not start the supervisor: ${result.note}`)
@@ -303,40 +361,32 @@ 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.
+// only a failure past the restart bound reaches `finish` and its warning; the Claude lanes are brokered
+// for as long as it supervises (`run-wake-supervise.ts`).
 // **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)
-
-	if (read.kind !== 'carried') return refuse_without_carry(read.kind)
-
 	const profile = run_wake_session.scheduler_profile()
 	if (profile === undefined) return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
 
-	const claimed = run_wake.claim(context.wake_target, read.carry.invocation, new Date(), profile)
+	const claimed = await run_wake_await.claim_run(context, profile, interval_ms)
 
-	if (claimed === undefined) return report(RUNNING_VERDICT)
+	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.profile ?? profile)
-	const stop = await run_wake_restart.supervise(restart_ports(context, ports, interval_ms))
+	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)
 
-	return await finish(stop, context)
+	return await finish(stop, context, claimed.carry.started_at)
 }
 
 // **The verdict tracks whether the supervisor is actually running, not merely whether a record is
@@ -352,30 +402,10 @@ function list(context: WakeContext): number {
 	return report(run_wake.is_supervisor_live(wake) ? SUPERVISING_VERDICT : STALE_VERDICT)
 }
 
-// **Removing the record is the stop; the signal only shortens the wait.** A pid already gone, or one
-// this process may not signal, is not an error — the loop ends at its next pass either way, because it
-// re-reads the record it no longer finds and `run_wake.update_wake` refuses to write one back.
-function signal_supervisor(wake: RunWake): void {
-	if (!run_wake.is_supervisor_live(wake)) return
-
-	try {
-		process.kill(wake.pid, 'SIGTERM')
-	} catch {
-		console.error(
-			`Process ${String(wake.pid)} could not be signalled; the record is removed regardless.`,
-		)
-	}
-}
-
 function stop_supervisor(context: WakeContext): number {
-	const wake = run_wake.read_wake(context.wake_target)
-
-	if (wake === undefined) return report(NONE_VERDICT)
-
-	run_wake.remove_wake(context.wake_target)
-	signal_supervisor(wake)
+	const stopped = run_wake_stop.stop(context.wake_target)
 
-	return report(STOPPED_VERDICT)
+	return report(stopped === undefined ? NONE_VERDICT : STOPPED_VERDICT)
 }
 
 async function dispatch(
@@ -419,7 +449,11 @@ const run_wake_cli = {
 	SUPERVISING_VERDICT,
 	UNKNOWN_VERDICT,
 	USAGE,
+	finish,
+	ports_for,
+	record_failure,
 	run,
+	start_for_launch,
 	stop_body,
 	warning_body,
 }

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

@@ -1,17 +1,22 @@
+import path from 'node:path'
 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, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_ended } from '#scripts/run/carry/run-carry-ended'
 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'
+import { run_wake_session } from './run-wake-session'
 
 // The `--list` presentation of a wake record. What the command *does* stays in `run-wake-cli.ts`; how
 // a supervisor's record reads back to a person lives here, one cohesive block.
 
 const UNKNOWN_CUTS = 'an unreadable number of'
 const REPO_LOOKUP_TIMEOUT_MS = 10_000
-const STOP_COMMAND = 'pnpm josh run:wake --stop'
+// The whole run, not the supervisor alone: `run:wake --stop` leaves the run's record behind, and a
+// record with no owner is what the next `josh backlogrun` stands on without starting.
+const STOP_COMMAND = 'pnpm josh backlogrun --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
@@ -19,6 +24,8 @@ const UNREADABLE_TIME = 'an unreadable time'
 // checkout — a lane must never be where the next session resumes, because a lane belongs to one child.
 interface WakeContext {
 	carry_target: string
+	// Where `run:carry --end` records the run it removes — what tells an ended run from an unread one.
+	ended_target: string
 	wake_target: string
 	// Where everything this supervisor starts writes its output. It is named
 	// in `--list` and in every warning, because a path nobody is told is a file nobody reads.
@@ -28,6 +35,8 @@ interface WakeContext {
 	// side uses. `--list` relays the newest event from here: the report surface belongs to the run, and
 	// `--list` is the degenerate last-event read of the same stream the attached session follows.
 	event_target: string
+	// The common git directory every record is keyed on — what finds the launch `josh backlogrun` made.
+	git_directory: string
 	worktree: string
 }
 
@@ -154,7 +163,32 @@ function describe_wake_cited(wake: RunWake, context: WakeContext): string {
 	return cite_description(describe_wake(wake, context), repo)
 }
 
-const run_wake_describe = { STOP_COMMAND, cite_description, describe_wake, describe_wake_cited }
+function context_of(directory: string, note: (line: string) => void): WakeContext {
+	const log_target = run_wake.wake_log_path(directory)
+
+	// Every verb reaches this one function, so creating the log here is what makes the path each of
+	// them prints a path that exists — including `--list` and the already-running branch of `--start`,
+	// neither of which launches anything.
+	run_wake_session.ensure_log(log_target, note)
+
+	return {
+		carry_target: run_carry.carry_path(directory),
+		ended_target: run_carry_ended.ended_path(directory),
+		wake_target: run_wake.wake_path(directory),
+		log_target,
+		event_target: run_event_stream.target_of(directory),
+		git_directory: directory,
+		worktree: path.dirname(directory),
+	}
+}
+
+const run_wake_describe = {
+	STOP_COMMAND,
+	cite_description,
+	context_of,
+	describe_wake,
+	describe_wake_cited,
+}
 
 export type { WakeContext }
 export { run_wake_describe }

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

@@ -1,5 +1,6 @@
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 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'
 import type { DriveResult } from './run-wake-loop'
 
@@ -125,10 +126,16 @@ function read_result(
 	return driver_result(result.out, run_carry.read_carry(target), invocation, result.err)
 }
 
+// **A record this process already owns is claimed again.** A driver that failed leaves the record
+// adopted for the supervisor and not handed off, and the restarted pass re-drives it from here; only a
+// record another live process holds is refused.
 function claim_record(target: string, invocation: string): boolean {
 	const current = run_carry.read_carry(target)
 	if (current.kind !== 'carried' || current.carry.invocation !== invocation) return false
-	if (current.carry.is_handed_off !== true && run_carry.is_owner_live(current.carry)) return false
+
+	if (current.carry.is_handed_off !== true && run_carry.is_held_by_another(current.carry)) {
+		return false
+	}
 
 	return run_carry.adopt_carry(target, current.carry, run_carry.owner_of(process.pid)) !== undefined
 }
@@ -177,6 +184,15 @@ async function run_driver(
 	return await run_driver(target, args, wait, remaining - 1)
 }
 
+// **A result handed to a session is said on the stream first.** The driver has stopped asking, so
+// without it the board keeps the `handing off` this pass wrote and a run waiting on a session's
+// judgment reads as one still getting ready.
+async function announced(result: DriveResult): Promise<DriveResult> {
+	if (result.kind === 'judgment') await run_event_setup.emit(run_event_setup.STAGE.JUDGING)
+
+	return result
+}
+
 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.' }
@@ -188,10 +204,10 @@ async function drive(target: string, wait: Pause = pause): Promise<DriveResult>
 		return { kind: 'failed', note: 'The driver could not claim the carry record.' }
 	}
 
-	return read_result(
-		await run_driver(target, args, wait, RERUN_LIMIT),
-		target,
-		read.carry.invocation,
+	await run_event_setup.emit(run_event_setup.STAGE.HANDING_OFF)
+
+	return await announced(
+		read_result(await run_driver(target, args, wait, RERUN_LIMIT), target, read.carry.invocation),
 	)
 }
 

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

@@ -21,7 +21,7 @@ function hand_off(target: string): void {
 
 	if (read.kind !== 'carried' || read.carry.is_handed_off === true) return
 
-	stamp_file.write_stamp(target, { ...read.carry, is_handed_off: true })
+	stamp_file.replace_stamp(target, { ...read.carry, is_handed_off: true })
 }
 
 const run_wake_handoff = { hand_off }

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

@@ -1,6 +1,12 @@
 import { agent_argv, type AgentArgvResult } from '#scripts/agent/agent-argv'
-import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+import {
+	agent_role_profile,
+	type AgentProfile,
+	type AgentProvider,
+	type ProfileResult,
+} from '#scripts/agent/agent-role-profile'
 import { claude_agent_argv } from '#scripts/agent/claude-agent-argv'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
 import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 import { run_invocation } from '#scripts/run/run-invocation'
 
@@ -46,10 +52,20 @@ function scheduler_profile(): AgentProfile | undefined {
 	return undefined
 }
 
-function supervisor_environment(profile: AgentProfile): Record<string, string> {
+// The scheduler profile of the provider a run was started on, whatever session the command was typed in
+// (joshuafolkken/kit#3804).
+function chosen_profile(provider: AgentProvider): ProfileResult {
+	const environment = backlogrun_launch.chosen_environment(provider)
+
+	return agent_role_profile.resolve(agent_role_profile.SCHEDULER, environment)
+}
+
+// **A Claude supervisor clears an inherited Codex session key**, so one started from a command typed in
+// a Codex session does not read itself as both.
+function supervisor_environment(profile: AgentProfile): Record<string, string | undefined> {
 	return profile.provider === 'openai'
 		? { CODEX_THREAD_ID: SUPERVISOR_SESSION }
-		: { CLAUDE_CODE_CHILD_SESSION: SUPERVISOR_SESSION }
+		: { CLAUDE_CODE_CHILD_SESSION: SUPERVISOR_SESSION, CODEX_THREAD_ID: undefined }
 }
 
 // **What comes back is always the rebuilt text, and it is refused unless it matches the record.** The
@@ -149,6 +165,7 @@ const run_wake_session = {
 	ensure_log: detached_launch.ensure_log,
 	is_safe_argv: detached_launch.is_safe_argv,
 	launch: detached_launch.launch,
+	chosen_profile,
 	scheduler_profile,
 	supervisor_argv,
 	supervisor_environment,

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

@@ -0,0 +1,37 @@
+import { run_wake, type RunWake } from './run-wake'
+
+// Stopping the supervisor, apart from the command that prints the verdict: `run:wake --stop` and
+// `josh backlogrun --stop` both stop it here, so the one stop is never written twice.
+
+// **Removing the record is the stop; the signal only shortens the wait.** A pid already gone, or one
+// this process may not signal, is not an error — the loop ends at its next pass either way, because it
+// re-reads the record it no longer finds and `run_wake.update_wake` refuses to write one back.
+function signal(pid: number): void {
+	try {
+		process.kill(pid, 'SIGTERM')
+	} catch {
+		console.error(
+			`Process ${String(pid)} could not be signalled; the record is removed regardless.`,
+		)
+	}
+}
+
+function signal_supervisor(wake: RunWake): void {
+	if (run_wake.is_supervisor_live(wake)) signal(wake.pid)
+}
+
+// The record that was stopped, `undefined` where there was none to stop.
+function stop(wake_target: string): RunWake | undefined {
+	const wake = run_wake.read_wake(wake_target)
+
+	if (wake === undefined) return undefined
+
+	run_wake.remove_wake(wake_target)
+	signal_supervisor(wake)
+
+	return wake
+}
+
+const run_wake_stop = { signal, stop }
+
+export { run_wake_stop }

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

@@ -0,0 +1,44 @@
+import { claude_lane_broker } from '#scripts/lane/claude-lane-broker'
+import { poll } from '#scripts/lib/poll'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import type { WakeContext } from './run-wake-describe'
+import { run_wake_loop, type LoopPorts, type LoopStop } from './run-wake-loop'
+import { run_wake_restart, type RestartPorts } from './run-wake-restart'
+
+// The supervisor's whole life: the restarting loop (`run-wake-restart.ts`), with the Claude lanes
+// brokered beside it.
+//
+// **The lanes are brokered for the supervisor's life, not one drive's**: a lane's ship asks for its
+// reviewer or its relaunch whenever it gets there, a hand-back to a session included, and only this
+// process holds the token those sessions sign in with (joshuafolkken/kit#3817, `claude-lane-broker.ts`).
+
+interface SuperviseTarget {
+	context: WakeContext
+	ports: LoopPorts
+	interval_ms: number
+	note: (text: string) => void
+}
+
+function restart_ports(target: SuperviseTarget): RestartPorts {
+	const { context, ports, interval_ms } = target
+
+	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: target.note,
+	}
+}
+
+async function supervise(target: SuperviseTarget): Promise<LoopStop> {
+	return await claude_lane_broker.serve_during(
+		async () => await run_wake_restart.supervise(restart_ports(target)),
+	)
+}
+
+const run_wake_supervise = { supervise }
+
+export { run_wake_supervise }
+export type { SuperviseTarget }