@joshuafolkken/kit 1.1383.0 → 1.1435.0

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

@@ -25,7 +25,7 @@ import { run_merge_token, type MergeToken } from './run-merge-token'
 // The contract is `run:carry`'s: **standard output carries one token** (or the newline-separated
 // offer `epic:next --lanes` prints), and everything else is a captured subprocess or a quiet
 // in-process call. The verdicts this command adds to the offer are `over` (hand off), `human-review`
-// (stop — the child's own ending), `stop` (the consecutive-failure guard tripped) and `retry` (the
+// (stop — the child's own ending), `stop` (the consecutive-failure guard tripped, or a failed child could not be parked) and `retry` (the
 // child's state could not be read; re-read before deciding).
 
 const ARGV_OFFSET = 2
@@ -163,13 +163,16 @@ function parse(argv: ReadonlyArray<string>): MergeContext | undefined {
 interface ControlVerdict {
 	token: MergeToken
 	code: number
+	is_offer: false
 }
 
 // The next child offered in the collected one's place: the text `backlog:next` or `epic:next --lanes`
-// printed, passed through as it was read, so no narrower type holds it.
+// printed, passed through as it was read, so no narrower type holds it. `is_offer` keeps its `stop`
+// apart from the control one (`run_merge_token.is_control_stop`).
 interface OfferVerdict {
 	token: string
 	code: number
+	is_offer: true
 }
 
 type MergeVerdict = ControlVerdict | OfferVerdict
@@ -179,11 +182,11 @@ type MergeVerdict = ControlVerdict | OfferVerdict
 type MergeResult = MergeVerdict & { outcome: ChildOutcome }
 
 function emit(token: MergeToken, code: number): ControlVerdict {
-	return { token, code }
+	return { token, code, is_offer: false }
 }
 
 async function offered(ctx: MergeContext): Promise<OfferVerdict> {
-	return { token: await run_merge_steps.ask_next(ctx), code: SUCCESS_EXIT_CODE }
+	return { token: await run_merge_steps.ask_next(ctx), code: SUCCESS_EXIT_CODE, is_offer: true }
 }
 
 // Whether the child's exit record shows it could not reach the API — read only when `--output` named

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

@@ -0,0 +1,61 @@
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+
+// Why `run:merge` parks a child whose detached ship has already ended (joshuafolkken/kit#3808).
+//
+// **A child that handed its region to `josh ship --detach` is parked for what its ship did.** A running
+// ship is never parked (`merge_child` answers `shipping` first), so a park after a hand-off means the
+// ship ended unmerged — and the session the ship relaunched to fix it ended too. The generic "session
+// ended with its issue open" then hides the one fact a person needs: the stage the ship stopped at. The
+// cause is that stage's `ship-stop` line, written by the supervisor since its own launch; a ship that
+// ended without one (killed, or failed before any stage) is named by its result and its log instead.
+
+type ShipEnding = ReturnType<typeof run_ship_detach.read_result>
+
+const ENDED_RESULTS: ReadonlySet<string> = new Set(['failed', 'abnormal'])
+
+type Events = ReadonlyArray<RunEvent>
+
+// `child`'s events after its newest `ship-launch`, so an earlier launch's stop the relaunched session
+// already fixed is never blamed for this ending. The record and the stream outlive a dispatch, so only a
+// ship launched since the child's own newest dispatch is this attempt's: an earlier attempt's ended ship
+// answers `undefined`, never this park.
+function since_ship_launch(events: Events, child: string): Events | undefined {
+	const attempt = run_event_scope.since_own_launch(events, child)
+	const own = attempt.filter((event) => run_event_scope.issue_named(event) === child)
+	const launched_at = own.findLastIndex(
+		(event) => event.kind === run_event_stream.EVENT_KIND.SHIP_LAUNCH,
+	)
+
+	return launched_at === -1 ? undefined : own.slice(launched_at + 1)
+}
+
+function cause_of(ending: ShipEnding, events: Events, child: string): string | undefined {
+	if (ending === undefined || !ENDED_RESULTS.has(ending.result)) return undefined
+
+	const attempt = since_ship_launch(events, child)
+	if (attempt === undefined) return undefined
+
+	const stop = attempt.findLast((event) => event.kind === run_event_stream.EVENT_KIND.SHIP_STOP)
+
+	if (stop !== undefined) return `its detached ship stopped and was not fixed: ${stop.text}.`
+
+	return `its detached ship ended ${ending.result} before recording a stopped stage — pnpm josh ship --log ${child}.`
+}
+
+// The ship's cause for `child`'s park, read from the record and the stream this checkout's repository
+// keys on, or `undefined` when the child handed nothing to a ship or its ship succeeded.
+function cause(child: string, directory: string = process.cwd()): string | undefined {
+	const repository = git_common_directory.repository(directory)
+	if (repository === undefined) return undefined
+
+	const events = run_event_stream.read_events(run_event_stream.target_of(repository))
+
+	return cause_of(run_ship_detach.read_result(repository, child), events, child)
+}
+
+const run_merge_ship = { cause, cause_of }
+
+export { run_merge_ship }

package/scripts/run/merge/run-merge-steps.ts

@@ -9,6 +9,7 @@ import { NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { session_cite } from '#scripts/issue/session-cite'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_close } from '#scripts/lane/lane-close'
+import { lane_preserve } from '#scripts/lane/lane-preserve'
 import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
@@ -24,6 +25,7 @@ import { run_carry_conversation } from '#scripts/run/carry/run-carry-conversatio
 import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
 import { run_label } from '#scripts/run/run-label'
 import { run_merge } from './run-merge'
+import { run_merge_ship } from './run-merge-ship'
 
 // The result of attempting to apply a carry change. Distinguishing `refused` from `applied` lets
 // callers surface the refusal as a hard failure rather than silently continuing on a carry that was
@@ -167,18 +169,8 @@ async function close_lane(child: string): Promise<void> {
 	await josh(['lane:close', child])
 }
 
-function preserved_comment(message: string): string {
-	return [
-		'The lane held uncommitted work when `run:merge` closed it, so it was stashed before the close:',
-		`- recover with \`pnpm josh stash:pop "${message}"\``,
-	].join('\n')
-}
-
 async function stash_work(child: string, directory: string): Promise<void> {
-	const message = git_stash.work_message(child, LANE_CLOSE_OCCASION)
-
-	await git_stash.push(message, directory)
-	await git_gh_issue_write.issue_try_comment(child, preserved_comment(message))
+	await lane_preserve.stash_work(child, directory, LANE_CLOSE_OCCASION, '`run:merge` closed it')
 }
 
 // Stash whatever the lane still holds uncommitted before its tree is removed: `lane:close` deletes by
@@ -344,13 +336,14 @@ async function park_failed(ctx: MergeContext, cause: string): Promise<FailedResu
 }
 
 // A child that ended unfinished: waiting when it records an open blocker (`do_waiting`), parked
-// otherwise (`park_failed`) — an order already recorded is never a decision for a person.
-async function do_failed(ctx: MergeContext, cause: string = FAILED_CAUSE): Promise<FailedResult> {
+// otherwise (`park_failed`) — an order already recorded is never a decision for a person. Without a
+// cause of the caller's, a child whose detached ship ended is parked for the ship's stop.
+async function do_failed(ctx: MergeContext, cause?: string): Promise<FailedResult> {
 	const blockers = await open_blockers(ctx.child)
 
 	if (blockers.length > 0) return await do_waiting(ctx, blockers)
 
-	return await park_failed(ctx, cause)
+	return await park_failed(ctx, cause ?? run_merge_ship.cause(ctx.child) ?? FAILED_CAUSE)
 }
 
 // The outcome of counting an outage: the record to read the streak against, and whether the count was

package/scripts/run/merge/run-merge-token.ts

@@ -24,7 +24,21 @@ const MERGE_TOKEN = {
 
 type MergeToken = (typeof MERGE_TOKEN)[keyof typeof MERGE_TOKEN]
 
-const run_merge_token = { MERGE_TOKEN }
+// Where the token came from: `run:merge`'s own control verdict, or the next offer (`backlog:next` /
+// `epic:next`) passed through as it was read. The offer has a `stop` of its own — nothing ready to start
+// is left — spelled like the control `stop`, so the source travels beside the token.
+interface MergeTokenRead {
+	token: string
+	is_offer: boolean
+}
 
-export type { MergeToken }
+// The single reading of "this merge stopped the run": the control `stop` alone. An offer's `stop` is a
+// parked backlog, which `backlog:budget` decides — a watch while the idle budget lasts — never the merge.
+function is_control_stop(read: MergeTokenRead): boolean {
+	return !read.is_offer && read.token === MERGE_TOKEN.STOP
+}
+
+const run_merge_token = { MERGE_TOKEN, is_control_stop }
+
+export type { MergeToken, MergeTokenRead }
 export { run_merge_token }

package/scripts/run/run-headless.ts

@@ -129,6 +129,7 @@ const run_headless = {
 	is_backlog_parent,
 	is_cut_capped,
 	is_headless,
+	is_headless_parent,
 	is_owned_here,
 	must_keep_waiting,
 }

package/scripts/run/run-step.ts

@@ -222,6 +222,8 @@ const FULL_INPUT_ACTIONS: Record<string, (input: StepInput) => StepAction> = {
 	[KIND.STOP]: stop_action,
 	[KIND.DRAIN]: drain_action,
 	[KIND.CHILD_LAUNCH]: child_launch_action,
+	// A person's restart re-dispatched the child, so the parent's position is a launch's.
+	[KIND.RESTART]: child_launch_action,
 }
 
 // An event the table does not name leaves the position unknown rather than guessing a next step. A

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/ship/run-ship-cli.ts

@@ -274,6 +274,18 @@ async function open_context(args: ShipArguments): Promise<ShipContext> {
 	return { target, done, state, started }
 }
 
+// Every stop goes to the lane ledger — supervised, in an agent's own turn, or a lane child's preflight
+// before the hand-off — so `lane:stats` can say how long a ship stayed stopped for each reason.
+async function record_stop(
+	args: ShipArguments,
+	stage: Stage,
+	conflicts?: ReadonlyArray<string>,
+): Promise<void> {
+	const reason = run_ship_stage.stop_reason(stage, conflicts)
+
+	await lane_ledger.record_stop({ issue: Number(args.number), reason })
+}
+
 // A detached supervisor hands the stopped stage back (`run-ship-return.ts`); a
 // ship in an agent's own turn has its report in front of that agent already. The `ship-stop` ends the
 // attempt, so the record's started stages go with it.
@@ -283,8 +295,11 @@ async function stopped(
 	step: Step,
 	context: ShipContext,
 ): Promise<ReadonlyArray<ShipSection>> {
+	const conflicts = sections.at(-1)?.conflicts
+
+	await record_stop(args, step.stage, conflicts)
+
 	if (run_ship_detach.is_supervised()) {
-		const conflicts = sections.at(-1)?.conflicts
 		const resume = run_ship_next.resume_of(args)
 
 		record(context.target, run_ship_stage.end_attempt)
@@ -371,7 +386,12 @@ function should_detach(args: ShipArguments): boolean {
 // supervisor's gate runs them again rather than passing over them.
 async function pre_detach_sections(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const preflight = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
-	if (preflight.code !== SUCCESS_EXIT_CODE) return [preflight]
+
+	if (preflight.code !== SUCCESS_EXIT_CODE) {
+		await record_stop(args, run_ship_steps.PREFLIGHT_STEP.stage)
+
+		return [preflight]
+	}
 
 	const result = await run_ship_pre_detach.checks()
 

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

@@ -1,8 +1,9 @@
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
-import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
+import { lane_child_invocation, type ShipStop } 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 { lane_session_broker } from '#scripts/lane/lane-session-broker'
 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'
@@ -49,6 +50,31 @@ function note(text: string): void {
 	process.stderr.write(`${text}\n`)
 }
 
+function relaunched(lane: LaneInfo, stop: ShipStop): ReturnOutcome {
+	const invocation = lane_child_invocation.ship_stop_invocation(lane.issue, stop)
+	const phase = agent_role_profile.IMPLEMENTATION_PHASE
+	const result = lane_relaunch.relaunch(lane, invocation, phase, note)
+
+	if (result.kind === 'launched') return 'relaunched'
+
+	note(`the lane child could not be relaunched: ${result.note}`)
+
+	return 'recorded'
+}
+
+// **A served lane's child is relaunched by its broker, not from here**: this supervisor descends from the
+// child's Bash tool, which Claude Code starts without the token, so a child started here could not sign
+// in where the token is the only credential (joshuafolkken/kit#3817).
+async function brokered(lane: LaneInfo, stop: ShipStop): Promise<ReturnOutcome> {
+	if (await lane_session_broker.request(lane.directory, lane.issue, { kind: 'relaunch', stop })) {
+		return 'relaunched'
+	}
+
+	note('the lane child could not be relaunched: the lane broker did not start it')
+
+	return 'recorded'
+}
+
 async function return_control(
 	issue: string,
 	stage: Stage,
@@ -63,19 +89,11 @@ async function return_control(
 
 	if (lane === undefined) return 'recorded'
 
-	const invocation = lane_child_invocation.ship_stop_invocation(issue, { stage, ...resume })
-	const result = lane_relaunch.relaunch(
-		lane,
-		invocation,
-		agent_role_profile.IMPLEMENTATION_PHASE,
-		note,
-	)
+	const stop = { stage, ...resume }
 
-	if (result.kind === 'launched') return 'relaunched'
-
-	note(`the lane child could not be relaunched: ${result.note}`)
-
-	return 'recorded'
+	return lane_session_broker.is_serving(lane.directory, issue)
+		? await brokered(lane, stop)
+		: relaunched(lane, stop)
 }
 
 const run_ship_return = { return_control }

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

@@ -4,7 +4,7 @@ import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 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 { lane_session_broker } from '#scripts/lane/lane-session-broker'
 import { review_record } from '#scripts/review/review-record'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
@@ -66,7 +66,7 @@ function failure(out: string): JoshResult {
 }
 
 function paths(): { brief: string; findings: string; log: string } {
-	return openai_review_broker.review_paths(PROJECT_ROOT)
+	return lane_session_broker.review_paths(PROJECT_ROOT)
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
@@ -94,6 +94,16 @@ async function run_direct_session(
 	return { code: SUCCESS_EXIT_CODE, out: '' }
 }
 
+// A lane child's reviewer is started by the lane's broker: an OpenAI lane's always, since a nested Codex
+// cannot write outside its sandbox, and a Claude lane's whenever the `run:wake` supervisor serves it, since this
+// ship was started from the child's Bash tool and so never received a token-only credential
+// (joshuafolkken/kit#3817). A Claude lane nobody serves starts the reviewer itself, as before.
+function is_brokered(profile: AgentProfile, issue: string): boolean {
+	if (!lane_child_marker.is_child_of(PROJECT_ROOT)) return false
+
+	return profile.provider === 'openai' || lane_session_broker.is_serving(PROJECT_ROOT, issue)
+}
+
 async function run_session(
 	prompt: string,
 	log_path: string,
@@ -103,11 +113,14 @@ async function run_session(
 	const built = agent_argv.resolve_in(prompt, agent_role_profile.REVIEWER, PROJECT_ROOT)
 	if (built.kind === 'rejected') return failure(`reviewer profile rejected: ${built.note}`)
 
-	if (built.profile.provider !== 'openai' || !lane_child_marker.is_child_of(PROJECT_ROOT)) {
+	if (!is_brokered(built.profile, issue)) {
 		return await run_direct_session(built.argv, built.profile, log_path)
 	}
 
-	const is_success = await openai_review_broker.request(PROJECT_ROOT, issue, round)
+	const is_success = await lane_session_broker.request(PROJECT_ROOT, issue, {
+		kind: 'review',
+		round,
+	})
 
 	return is_success ? { code: SUCCESS_EXIT_CODE, out: '' } : failure('isolated reviewer failed')
 }

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

@@ -201,6 +201,7 @@ function stop_reason(stage: Stage, conflicts: ReadonlyArray<string> = []): strin
 }
 
 const run_ship_stage = {
+	CONFLICT,
 	PHASE,
 	STAGE,
 	clear,

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

@@ -0,0 +1,130 @@
+import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
+import { poll } from '#scripts/lib/poll'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_wake, type RunWake } from './run-wake'
+import type { WakeContext } from './run-wake-describe'
+
+// How a supervisor claims the run it watches — including the one `josh backlogrun` starts beside the
+// parent it launched, before that parent has claimed the carry record (joshuafolkken/kit#3804).
+//
+// **That supervisor is started by the command, not by the parent's own shell.** Claude Code removes its
+// token from every process its Bash tool starts, so a supervisor the parent started there could not
+// authenticate the sessions it wakes wherever the token is the only credential. Started by the command,
+// it inherits the token — but before the parent has run `run:carry --begin`, so it waits for that record
+// while the launch that will write it is alive, and gives up once that launch is gone.
+//
+// **While a launch is pending, only a live owner's record is its parent's**: a dead owner's record is one
+// an earlier run left, and supervising it would wake that run beside the parent just launched.
+
+interface AwaitPorts {
+	read_carry: () => CarryRead
+	// The invocation of the launched parent that has not claimed the carry record yet, `undefined` once
+	// no such launch is alive.
+	pending_invocation: () => string | undefined
+	is_owner_live: (carry: RunCarry) => boolean
+	sleep: (milliseconds: number) => Promise<void>
+}
+
+type ClaimResult =
+	| { kind: 'claimed'; wake: RunWake; carry: RunCarry }
+	| { kind: 'running' }
+	| { kind: 'refused'; carry_kind: CarryRead['kind'] }
+
+function is_live_carry(read: CarryRead, ports: AwaitPorts): boolean {
+	return read.kind === 'carried' && ports.is_owner_live(read.carry)
+}
+
+// What the supervisor claims its record for: the live carried run, else the launch about to carry one,
+// else the carried run a supervisor started with no launch pending wakes.
+function supervised_invocation(ports: AwaitPorts): string | undefined {
+	const read = ports.read_carry()
+
+	if (read.kind !== 'carried') return ports.pending_invocation()
+	if (ports.is_owner_live(read.carry)) return read.carry.invocation
+
+	return ports.pending_invocation() ?? read.carry.invocation
+}
+
+// **The carry record is read once more after the launch is gone**, because a parent that wrote the
+// record and ended between the two reads still left a run to supervise.
+async function await_carry(ports: AwaitPorts, interval_ms: number): Promise<CarryRead> {
+	const read = ports.read_carry()
+
+	if (is_live_carry(read, ports)) return read
+	if (ports.pending_invocation() === undefined) return ports.read_carry()
+
+	await ports.sleep(interval_ms)
+
+	return await await_carry(ports, interval_ms)
+}
+
+function ports_of(context: WakeContext): AwaitPorts {
+	return {
+		read_carry: () => run_carry.read_carry(context.carry_target),
+		pending_invocation: () => backlogrun_launch.pending_launch(context.git_directory)?.invocation,
+		is_owner_live: (carry) => run_carry.is_owner_live(carry),
+		sleep: poll.sleep,
+	}
+}
+
+// The run the claim is held for: the one claimed for, or **a live run carried under another
+// invocation** — a person's own `run:carry --begin` landing before the launched parent's. That run's
+// `run:wake --start` found this supervisor live and answered `running`, so letting the claim go here
+// would leave it with nobody watching it.
+function supervised_carry(
+	read: CarryRead,
+	invocation: string,
+	ports: AwaitPorts,
+): RunCarry | undefined {
+	if (read.kind !== 'carried') return undefined
+	if (read.carry.invocation === invocation || ports.is_owner_live(read.carry)) return read.carry
+
+	return undefined
+}
+
+// **The record is re-pointed at the run it now supervises**, because the loop wakes sessions for the
+// record's invocation. **It carries the state a claim for that run would**, not the state the claim
+// inherited for the pending launch's invocation — that run's wakes are not this one's. A refused write
+// means the record is no longer this process's, which the loop's first pass reads as the stop it is.
+function held_for(
+	target: string,
+	wake: RunWake,
+	carry: RunCarry,
+	profile: AgentProfile,
+): ClaimResult {
+	if (carry.invocation === wake.invocation) return { kind: 'claimed', wake, carry }
+
+	const supervised = run_wake.fresh_wake(carry.invocation, new Date(), profile)
+
+	run_wake.update_wake(target, supervised)
+
+	return { kind: 'claimed', wake: supervised, carry }
+}
+
+// **The record is claimed before the carry record is awaited**, so the parent's own `run:wake --start`
+// finds this supervisor live and answers `running` rather than starting a second one beside it.
+// A parent that ends without carrying a run leaves nothing to supervise, and the claim is let go.
+async function claim_run(
+	context: WakeContext,
+	profile: AgentProfile,
+	interval_ms: number,
+	ports: AwaitPorts = ports_of(context),
+): Promise<ClaimResult> {
+	const invocation = supervised_invocation(ports)
+	if (invocation === undefined) return { kind: 'refused', carry_kind: ports.read_carry().kind }
+	const wake = run_wake.claim(context.wake_target, invocation, new Date(), profile)
+	if (wake === undefined) return { kind: 'running' }
+	const read = await await_carry(ports, interval_ms)
+	const carry = supervised_carry(read, invocation, ports)
+	if (carry !== undefined) return held_for(context.wake_target, wake, carry, profile)
+
+	run_wake.tidy_own_wake(context.wake_target)
+
+	return { kind: 'refused', carry_kind: read.kind }
+}
+
+const run_wake_await = { await_carry, claim_run, supervised_invocation }
+
+export type { AwaitPorts, ClaimResult }
+export { run_wake_await }