@joshuafolkken/kit 1.1383.0 → 1.1387.0

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

@@ -1,7 +1,9 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
 import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
+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_merge_collect } from '#scripts/run/merge/run-merge-collect'
@@ -151,25 +153,47 @@ function report_claim(
 	return report(CLAIM_VERDICTS[claim], carry, is_json, FAILURE_EXIT_CODE)
 }
 
-function start_fresh(target: string, request: CarryClaimRequest, is_json: boolean): number {
-	const carry = run_carry.begin_carry(target, request.invocation, request.owner)
+// When the run began: the moment `josh backlogrun` launched this owner, so the clock `run:board` was
+// already counting from does not restart at the claim; `undefined` — now — for every other run.
+async function launch_start(request: CarryClaimRequest): Promise<Date | undefined> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return undefined
+
+	return backlogrun_launch.started_for(directory, request.owner.pid)
+}
+
+// A run that began is planning, which is what its board says until the supervisor takes it over.
+async function start_fresh(
+	target: string,
+	request: CarryClaimRequest,
+	is_json: boolean,
+): Promise<number> {
+	const started = await launch_start(request)
+	const carry = run_carry.begin_carry(target, request.invocation, request.owner, started)
 
 	if (carry === undefined) return report_lost(is_json)
 
+	await run_event_setup.emit(run_event_setup.STAGE.PLANNING)
+
 	return report_carry(BEGAN_VERDICT, carry, is_json)
 }
 
 // **A standing record is never replaced, and never resumed into by something else.** Replacing one
 // would restart the budget the cut exists to carry, and resuming into one would put two parents on a
 // single budget. Its age changes none of that: a record is replaced by nothing but a person's `--end`.
-function begin(target: string, request: CarryClaimRequest, is_json: boolean): number {
+async function begin(
+	target: string,
+	request: CarryClaimRequest,
+	is_json: boolean,
+): Promise<number> {
 	const read = run_carry.read_carry(target)
 
 	if (read.kind === 'unreadable') return report_unreadable(is_json)
 
 	if (read.kind === 'carried') return report_claim(target, read.carry, request, is_json)
 
-	return start_fresh(target, request, is_json)
+	return await start_fresh(target, request, is_json)
 }
 
 function report_nothing_to_resume(is_json: boolean): number {
@@ -203,10 +227,16 @@ function report_over(is_json: boolean): number {
 	return report(OVER_VERDICT, undefined, is_json, FAILURE_EXIT_CODE)
 }
 
-function claim_record(target: string, request: CarryClaimRequest, is_json: boolean): number {
+async function claim_record(
+	target: string,
+	request: CarryClaimRequest,
+	is_json: boolean,
+): Promise<number> {
 	if (cost_cli.session_verdict() === cost_verdict.OVER_VERDICT) return report_over(is_json)
 
-	return request.is_adoption ? adopt(target, request, is_json) : begin(target, request, is_json)
+	if (request.is_adoption) return adopt(target, request, is_json)
+
+	return await begin(target, request, is_json)
 }
 
 // The record is no longer this session's to advance — handed off at a cut, or taken over by a live
@@ -347,7 +377,7 @@ async function act(
 	request: Exclude<Request, { kind: 'end' }>,
 	is_json: boolean,
 ): Promise<number> {
-	if (request.kind === 'claim') return claim_record(target, request.claim, is_json)
+	if (request.kind === 'claim') return await claim_record(target, request.claim, is_json)
 
 	const read = run_carry.read_carry(target)
 

package/scripts/run/carry/run-carry-ended.ts

@@ -79,7 +79,15 @@ function read_ended(target: string): EndedRun | undefined {
 	return raw === undefined ? undefined : parse_ended(raw)
 }
 
-const run_carry_ended = { ended_path, read_ended, record_ended }
+// Whether the run that began at `started_at` is the one `--end` last ended — what tells a record that is
+// gone because its run ended from one that only failed to read.
+function has_ended(target: string, started_at: string | undefined): boolean {
+	const ended = read_ended(target)
+
+	return ended !== undefined && ended.started_at === started_at
+}
+
+const run_carry_ended = { ended_path, has_ended, read_ended, record_ended }
 
 export { run_carry_ended }
 export type { EndedRun }

package/scripts/run/carry/run-carry.ts

@@ -336,6 +336,21 @@ function is_foreign_live_owner(carry: RunCarry, owner: CarryOwner): boolean {
 	return is_owner_live(carry) && !is_owned_by(carry, owner)
 }
 
+// Whether a process other than the caller still holds the record. **By process alone, never by
+// conversation**: the wake supervisor inherits the environment of the session that started it, so a
+// conversation match would read that live session's record as the supervisor's own. The driver adopts
+// the record for the supervisor's process (`run-wake-driver.ts` → `claim_record`), so without this a
+// supervisor reads itself as a session at work.
+function is_held_by_another(
+	carry: RunCarry,
+	is_live: (carry: RunCarry) => boolean = is_owner_live,
+): boolean {
+	const caller = owner_of(process.pid)
+	const is_own = carry.owner_pid === caller.pid && carry.owner_start === caller.start
+
+	return !is_own && is_live(carry)
+}
+
 function is_handed_off_to(carry: RunCarry, invocation: string): boolean {
 	return carry.is_handed_off === true && carry.invocation === invocation
 }
@@ -504,6 +519,7 @@ const run_carry = {
 	fresh_carry,
 	is_count_refused,
 	is_foreign_live_owner,
+	is_held_by_another,
 	is_owner_live,
 	lost_message,
 	nothing_to_resume_message,

package/scripts/run/event/run-event-render.ts

@@ -44,6 +44,7 @@ const KIND_LABELS: Readonly<Record<EventKind, KindLabel>> = {
 	'lane-phase': { ja: 'レーンの段階', en: 'lane phase' },
 	add: { ja: '割り込み', en: 'added' },
 	'lane-limit': { ja: 'レーン上限', en: 'lane limit' },
+	setup: { ja: '準備', en: 'setup' },
 }
 
 const LABELS_BY_KIND: ReadonlyMap<string, KindLabel> = new Map(Object.entries(KIND_LABELS))

package/scripts/run/event/run-event-setup.ts

@@ -0,0 +1,47 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_event_stream } from './run-event-stream'
+import { run_event_stream_emit } from './run-event-stream-emit'
+
+// The stages a run passes between `josh backlogrun` and its first child, each written to the stream as
+// one `setup` event by the step that enters it. **The text is the stage's own words**: `run:board` draws
+// it as written, so the message a person reads and the `💓` beside it come from one event and cannot
+// disagree. Only a lane opening names an issue, which is how a reader tells it from the stages before it.
+
+const STAGE = {
+	// `josh backlogrun` started the parent session, which is reading its procedure.
+	STARTING: 'starting session',
+	// `run:carry --begin` claimed the run, and the parent is planning it.
+	PLANNING: 'planning',
+	// The supervisor took the run over from the parent and is asking for the first offer.
+	HANDING_OFF: 'handing off',
+} as const
+
+const OPENING = 'opening lane'
+
+// The driver is about to open a lane for `issue` — for every child, not only the first.
+function opening_lane(issue: string): string {
+	return `${OPENING} ${issue_cite.plain(issue)}`
+}
+
+// Best-effort, as every append to this stream is: a stage that could not be written is a board that
+// says less, never a run that failed.
+async function emit(text: string): Promise<void> {
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SETUP, text)
+}
+
+// The same append for a caller that already holds the repository's common git directory and the moment
+// it wants the stage dated — the launcher, whose record and first stage carry one time.
+function emit_in(repository: string, text: string, at: Date): void {
+	try {
+		const target = run_event_stream.target_of(repository)
+
+		run_event_stream.append(target, run_event_stream.EVENT_KIND.SETUP, text, at.toISOString())
+	} catch (error) {
+		error_text.trace_swallowed('run_event_setup.emit_in', error)
+	}
+}
+
+const run_event_setup = { STAGE, emit, emit_in, opening_lane }
+
+export { run_event_setup }

package/scripts/run/event/run-event-stream.ts

@@ -83,7 +83,8 @@ const EVENT_KIND = {
 	// stalled is pointed straight at dispatching the work rather than left waiting.
 	STALL: 'stall',
 	// The run's own driver is gone: the cut handed the budget off, the owner has died, and no supervisor
-	// is watching. Emitted once per strand episode by the stop-time detector,
+	// is watching. Emitted once per strand episode by the stop-time detector — or by the `run:wake`
+	// supervisor as it fails, leaves that state behind and has warned of it —
 	// exactly as `STALL` is — the newest-event dedup keeps a run polled every stop from notifying more
 	// than once, and a terminal reader following the stream sees the line. The strand is the step before
 	// the stall: a stalled run still has a driver that could dispatch, a stranded one has none.
@@ -124,6 +125,11 @@ const EVENT_KIND = {
 	// arrival probe reads it as a wake: the lanes a raise frees are new room for a pool its baseline
 	// already holds. A trace: it says the run gained room, not where the run is.
 	LANE_LIMIT: 'lane-limit',
+	// One stage of the run's start — the session starting, the plan, the hand-off to the supervisor, a
+	// lane opening (`run-event-setup.ts`). `run:board` draws it until the first child launches, so the
+	// minutes before one read as work rather than as a run that has stopped. A trace: it says the run is
+	// getting ready, not where the run is.
+	SETUP: 'setup',
 } as const
 
 type EventKind = (typeof EVENT_KIND)[keyof typeof EVENT_KIND]
@@ -141,13 +147,19 @@ const TRACE_KINDS: ReadonlySet<string> = new Set([
 	EVENT_KIND.LANE_PHASE,
 	EVENT_KIND.ADD,
 	EVENT_KIND.LANE_LIMIT,
+	EVENT_KIND.SETUP,
 ])
 
 // The trace kinds that say only that the run was alive, so the bound rolls them off first. A `filed` or
 // `note` line is a trace to the position readers but is the board's record of what the run found, so
 // it rolls off only with the positions. A ship-stage `start` is disposable but goes last of them:
-// `run:board` draws from that line.
-const DISPOSABLE_KINDS: ReadonlySet<string> = new Set([EVENT_KIND.SHIP_STAGE, EVENT_KIND.HEARTBEAT])
+// `run:board` draws from that line. A `setup` line is read only until the child it prepares launches,
+// so every one but the newest goes.
+const DISPOSABLE_KINDS: ReadonlySet<string> = new Set([
+	EVENT_KIND.SHIP_STAGE,
+	EVENT_KIND.HEARTBEAT,
+	EVENT_KIND.SETUP,
+])
 
 const event_schema = z.object({
 	pos: z.number(),
@@ -241,10 +253,18 @@ function is_stage_start(event: RunEvent): boolean {
 	return event.text.split(WORD_SEPARATOR)[STAGE_PHASE_INDEX] === run_ship_stage.PHASE.START
 }
 
+// The disposable lines the bound never drops: each issue's newest ship-stage and the run's newest
+// `setup` stage, the ones `run:board` draws from now.
+function drawn_lines(events: ReadonlyArray<RunEvent>): ReadonlySet<RunEvent> {
+	const setup = events.findLast((event) => event.kind === EVENT_KIND.SETUP)
+
+	return new Set([...newest_stages(events), ...(setup === undefined ? [] : [setup])])
+}
+
 // The lines the bound may drop, in the order it drops them: the ones that draw nothing first, then the
 // ones `run:board` draws from, each group oldest first.
 function droppable(events: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> {
-	const kept = newest_stages(events)
+	const kept = drawn_lines(events)
 	const disposable = events.filter((event) => DISPOSABLE_KINDS.has(event.kind) && !kept.has(event))
 
 	return [
@@ -261,7 +281,8 @@ function droppable(events: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> {
 //
 // **Each issue's newest ship-stage is not disposable**: it is the only record `run:board` draws a lane's
 // review-and-later phase from, and on a stream full of positions it would otherwise roll off in its own
-// append.
+// append. **The newest `setup` stage is kept for the same reason**: it is the stage `run:board` draws
+// until the first child launches, and a run that starts on a full stream would otherwise show none.
 //
 // **A ship-stage `start` outlasts the other disposable lines**: each one is a phase on the lane's track,
 // so it is kept past the `done` lines and the heartbeats.

package/scripts/run/run-stranded-detect.ts

@@ -1,5 +1,6 @@
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 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_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_wake, type RunWake } from '#scripts/run/wake/run-wake'
@@ -27,13 +28,14 @@ import {
 // so recovery is another actor's.
 const STRAND_RECOVERY = `Restart supervision with \`${run_stranded.RECOVERY_COMMAND}\` — it wakes a fresh successor to claim the budget; the cutting session must not resume it itself.`
 
-// The seams a test replaces: the two record targets, the two record reads, the owner and supervisor
-// liveness probes, and the two side effects. The defaults are the real readers; a test hands fakes so
+// The seams a test replaces: the two record targets, the two record reads, the ended-run read, the owner
+// and supervisor liveness probes, and the two side effects. The defaults are the real readers; a test hands fakes so
 // the gather and report logic run without a git tree, a process table or a network.
 interface DetectPorts {
 	resolve_targets: () => Promise<RecordTargets | undefined>
 	read_carry: (target: string) => CarryRead
 	is_owner_live: (carry: RunCarry) => boolean
+	has_ended: (target: string, started_at: string) => boolean
 	read_wake: (target: string) => RunWake | undefined
 	supervisor_liveness: (wake: RunWake | undefined) => SupervisorLiveness
 	emit_stranded: (text: string) => Promise<boolean>
@@ -45,15 +47,25 @@ interface RecordTargets {
 	wake: string
 }
 
+// The run a supervisor was watching: its carry record, where `run:carry --end` records the run it
+// removes, and the `started_at` the supervisor read when it took the run on.
+interface WatchedRun {
+	carry_target: string
+	ended_target: string
+	started_at: string
+}
+
+function targets_of(directory: string): RecordTargets {
+	return { carry: run_carry.carry_path(directory), wake: run_wake.wake_path(directory) }
+}
+
 // Both records key on the common git directory, the same one `run-carry.ts` and `run-wake.ts` resolve,
 // so a strand read from any lane reads the one run's records. `undefined` outside a repository: no git
 // directory to key on, so no run to be stranded.
 async function real_resolve_targets(): Promise<RecordTargets | undefined> {
 	const directory = await run_carry.repository_directory()
 
-	if (directory === undefined) return undefined
-
-	return { carry: run_carry.carry_path(directory), wake: run_wake.wake_path(directory) }
+	return directory === undefined ? undefined : targets_of(directory)
 }
 
 async function real_emit_stranded(text: string): Promise<boolean> {
@@ -68,6 +80,7 @@ const DEFAULT_PORTS: DetectPorts = {
 	resolve_targets: real_resolve_targets,
 	read_carry: (target) => run_carry.read_carry(target),
 	is_owner_live: run_carry.is_owner_live,
+	has_ended: run_carry_ended.has_ended,
 	read_wake: (target) => run_wake.read_wake(target),
 	supervisor_liveness: (wake) => run_stranded.supervisor_liveness(wake),
 	emit_stranded: real_emit_stranded,
@@ -77,11 +90,7 @@ const DEFAULT_PORTS: DetectPorts = {
 // The three facts, assembled behind the carry-record gate. A non-`carried` read — nothing carried, or
 // an unreadable record — is `undefined`: there is no live budget to be stranded, so the
 // wake record is never read and the judge is never asked.
-async function gather(ports: DetectPorts): Promise<StrandedInput | undefined> {
-	const targets = await ports.resolve_targets()
-
-	if (targets === undefined) return undefined
-
+function input_at(ports: DetectPorts, targets: RecordTargets): StrandedInput | undefined {
 	const read = ports.read_carry(targets.carry)
 
 	if (read.kind !== 'carried') return undefined
@@ -93,6 +102,12 @@ async function gather(ports: DetectPorts): Promise<StrandedInput | undefined> {
 	}
 }
 
+async function gather(ports: DetectPorts): Promise<StrandedInput | undefined> {
+	const targets = await ports.resolve_targets()
+
+	return targets === undefined ? undefined : input_at(ports, targets)
+}
+
 // The marker and the notification, both once per strand episode. `emit_stranded` refuses a second while
 // the strand event is still the newest, and its `false` is what holds the notification back too — so a
 // strand polled every stop reaches the person once, not once a turn.
@@ -128,7 +143,38 @@ async function run_stranded_check(): Promise<void> {
 	}
 }
 
-const run_stranded_detect = { detect_and_report, run_stranded_check }
+// The same judgement for a reader that draws the run rather than reports on it: `run:board` asks it
+// every local read, so a run nobody is driving is not drawn as one still waiting for work.
+function is_stranded_at(directory: string, ports: DetectPorts = DEFAULT_PORTS): boolean {
+	const input = input_at(ports, targets_of(directory))
+
+	return input !== undefined && run_stranded.is_stranded(input)
+}
+
+// The judgement a supervisor asks of the run it is about to stop watching. The asker is that
+// supervisor on its way out, so it is taken as gone, and so is an owner that is the asker itself
+// (`run_carry.is_held_by_another`) — that owner is about to be gone. A
+// record another session holds is not left stranded. **A record that does not read is left stranded
+// unless `run:carry --end` ended this very run**: the read that failed the driver fails here too, and
+// that run still has its budget and nobody watching it.
+function is_left_stranded(run: WatchedRun, ports: DetectPorts = DEFAULT_PORTS): boolean {
+	const read = ports.read_carry(run.carry_target)
+
+	if (read.kind !== 'carried') return !ports.has_ended(run.ended_target, run.started_at)
+
+	return run_stranded.is_stranded({
+		read,
+		is_owner_live: run_carry.is_held_by_another(read.carry, ports.is_owner_live),
+		supervisor: run_stranded.GONE,
+	})
+}
+
+const run_stranded_detect = {
+	detect_and_report,
+	is_left_stranded,
+	is_stranded_at,
+	run_stranded_check,
+}
 
 export { run_stranded_detect }
-export type { DetectPorts, RecordTargets }
+export type { DetectPorts, RecordTargets, WatchedRun }

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

@@ -8,8 +8,11 @@ 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_carry_ended } from '#scripts/run/carry/run-carry-ended'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_headless } from '#scripts/run/run-headless'
+import { run_stranded_detect, type WatchedRun } from '#scripts/run/run-stranded-detect'
 import { run_wake, type 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'
@@ -145,6 +148,7 @@ async function resolve_context(): Promise<WakeContext | undefined> {
 
 	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),
@@ -180,10 +184,13 @@ function wake_session(
 	return run_wake_session.launch({ argv: built.argv, ...target, profile }, note_to_stderr)
 }
 
+// **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 +218,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,13 +272,17 @@ 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))
 }
@@ -336,7 +378,7 @@ async function loop(context: WakeContext, interval_ms: number): Promise<number>
 
 	tidy_up(context.wake_target)
 
-	return await finish(stop, context)
+	return await finish(stop, context, read.carry.started_at)
 }
 
 // **The verdict tracks whether the supervisor is actually running, not merely whether a record is
@@ -419,6 +461,9 @@ const run_wake_cli = {
 	SUPERVISING_VERDICT,
 	UNKNOWN_VERDICT,
 	USAGE,
+	finish,
+	ports_for,
+	record_failure,
 	run,
 	stop_body,
 	warning_body,

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

@@ -19,6 +19,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.

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
 }
@@ -188,6 +195,8 @@ async function drive(target: string, wait: Pause = pause): Promise<DriveResult>
 		return { kind: 'failed', note: 'The driver could not claim the carry record.' }
 	}
 
+	await run_event_setup.emit(run_event_setup.STAGE.HANDING_OFF)
+
 	return read_result(
 		await run_driver(target, args, wait, RERUN_LIMIT),
 		target,

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 }