@joshuafolkken/kit 1.872.0

package/scripts/run/run-step.ts

@@ -0,0 +1,292 @@
+import { git_stash } from '#scripts/git/git-stash'
+import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
+import type { CarryRead } from './run-carry'
+import { run_event_stream } from './run-event-stream'
+
+// `josh run:step <N>` — the run's next single action, computed from three mechanical inputs and nothing
+// else (joshuafolkken/kit#2248). It is the child of epic #2166 that lifts the fold from an *event* to a
+// whole *run*: `run:next` printed one prose line for a `fullrun`'s pre-implementation position, and the
+// backlogrun loop stayed a state machine written in English that the reader rebuilt every turn. This
+// computes the position from the event stream (`run-event-stream.ts`), the carry record
+// (`run-carry.ts`) and the issue state (`run-prep.ts`) — never the conversation — and prints one line.
+//
+// **The print is one of two shapes, never a procedure.** A runnable command the reader pastes, or a
+// single point a person has to judge (`decide: … — a | b`). The short verdict tokens below are the
+// non-command answers, exactly as `backlog:next` prints an issue command or one of its fixed verdicts;
+// an issue number is never a verdict token, only the named strings here are.
+//
+// **It does not re-decide what another command already answers.** A merged child's next step is
+// `run:merge`'s to classify, the next backlog issue is `backlog:next`'s, the merge chain is
+// `followup`'s — so this dispatches to them rather than cloning their logic. The one thing it owns is
+// *which* of them is next, read off the run's own position.
+
+const CLOSED = 'CLOSED'
+
+// The fixed verdict tokens — the non-command, non-decide answers. Kept as the oracle's declared
+// vocabulary (joshuafolkken/kit#2248), so `decision-oracle.test.ts` pins the list against these.
+const IMPLEMENT = 'implement'
+const HUMAN_REVIEW = 'human-review'
+const UPDATE_DEPS = 'update-deps'
+const ALREADY_DONE = 'already-done'
+// A closed issue whose lane tree still holds uncommitted work (joshuafolkken/kit#2476) — `run:step`
+// itself prints the `decide:` line naming the stash, and this is the token `run:entry` reports.
+const KEEP_WORK = 'keep-work'
+const WAIT = 'wait'
+const STOP = 'stop'
+const UNKNOWN = 'unknown'
+
+const VOCABULARY: ReadonlyArray<string> = [
+	IMPLEMENT,
+	HUMAN_REVIEW,
+	UPDATE_DEPS,
+	ALREADY_DONE,
+	KEEP_WORK,
+	WAIT,
+	STOP,
+	UNKNOWN,
+]
+
+// The whole-run bound is spent, and carrying the budget or discarding it is a person's call — the one
+// Tier-B point this machine surfaces rather than choosing.
+const EXPIRED_DECISION =
+	'decide: whole-run budget spent — resume with `pnpm josh run:carry --resume` | discard with `pnpm josh run:carry --end`'
+
+// The one step a stopped run still owes before it ends: the end-of-run retrospective
+// (joshuafolkken/kit#2328). It reads the run's own measurements and files the improvements worth
+// carrying into the next run; the command is kit-only, so it means nothing — and is never printed — in a
+// consumer project.
+const RETROSPECTIVE_COMMAND = 'pnpm josh retrospective'
+
+// The pre-implementation verdict `run:next` degenerates to: the position of a run that has emitted no
+// event yet. `run-next.ts` maps each of these to its prose sentence, so this is the single copy of the
+// state → step mapping and there is no second implementation (joshuafolkken/kit#2248).
+type PreVerdict =
+	| typeof IMPLEMENT
+	| typeof HUMAN_REVIEW
+	| typeof UPDATE_DEPS
+	| typeof ALREADY_DONE
+	| typeof KEEP_WORK
+	| typeof UNKNOWN
+
+interface PreInput {
+	state: string | undefined
+	is_human_review: boolean
+	latest_scope: string
+	// Whether a lane child's tree holds uncommitted work, read by `run:prep`'s gather
+	// (joshuafolkken/kit#2476). A closed issue over such a tree is not "nothing to do": the work was
+	// popped back from a park and is lost with the lane unless it is kept, so `already-done` gives way to
+	// `keep-work`.
+	has_changes: boolean
+}
+
+function closed_verdict(input: PreInput): typeof ALREADY_DONE | typeof KEEP_WORK {
+	return input.has_changes ? KEEP_WORK : ALREADY_DONE
+}
+
+// The three facts the run branches on before its first edit, ordered because they are not independent:
+// an unreadable state answers first, a closed issue is terminal, a required update is the earliest
+// action, and `needs-human-review` changes where the run ends so it precedes the ordinary implement.
+function pre_verdict(input: PreInput): PreVerdict {
+	if (input.state === undefined) return UNKNOWN
+	if (input.state === CLOSED) return closed_verdict(input)
+	if (input.latest_scope === latest_scope_cli.REQUIRED_SCOPE) return UPDATE_DEPS
+	if (input.is_human_review) return HUMAN_REVIEW
+
+	return IMPLEMENT
+}
+
+interface StepInput extends PreInput {
+	// The last event kind on the stream, or `undefined` for a stream with nothing on it. Only the newest
+	// event is read: the position is where the run *is*, not how it got there.
+	last_event: string | undefined
+	carry_kind: CarryRead['kind']
+	// Whether this invocation's end-of-run retrospective has already run, read off the carry record
+	// (joshuafolkken/kit#2328). At the stop position it is what tells a run that still owes a
+	// retrospective from one that has run it, so the step is printed exactly once.
+	is_retrospective_done: boolean
+	// Whether this checkout is a kit consumer rather than kit itself (joshuafolkken/kit#2328). The
+	// retrospective command is kit-only — refused in a consumer — so the step is never printed there; the
+	// consumer determination is the existing `doctor-consumer.ts` one, never a new judgement.
+	is_consumer: boolean
+	issue_number: string
+	// Whether this run is a dispatched lane child, read by the CLI from the dispatch mark
+	// (`lane-child-marker.ts`). A child must never be handed `run:merge` — that is the parent's own
+	// budget command and returns `busy` in a child (joshuafolkken/kit#2267, joshuafolkken/kit#2297).
+	is_lane_child: boolean
+	// Whether the end-of-run retrospective is switched on, read by the CLI from `JOSH_RETROSPECTIVE`
+	// (joshuafolkken/kit#2370). It defaults **off** — the auto-filed improvement issues the step drives
+	// are opt-in — so a run that leaves the variable unset never prints the retrospective step, while the
+	// retrospective's own logic is untouched and `pnpm josh retrospective` still runs by hand.
+	is_retrospective_enabled: boolean
+}
+
+interface StepAction {
+	kind: 'command' | 'verdict' | 'decide'
+	line: string
+}
+
+function verdict(token: string): StepAction {
+	return { kind: 'verdict', line: token }
+}
+
+function command(line: string): StepAction {
+	return { kind: 'command', line }
+}
+
+// The action for each event a run can be positioned at, keyed on the newest one. Each dispatches to the
+// command that owns that phase; `child-launch` is the one position with no command to run — the parent
+// waits for its child. `stop` and `drain` are handled apart in `stop_action` / `drain_action`, because
+// whether either still owes a retrospective needs more than the issue number. A merge and an outage share a next step: `run:merge`
+// classifies both, including the outage's stop condition.
+const KIND = run_event_stream.EVENT_KIND
+// A park and a stall share this next step: both mean runnable work is waiting to be offered
+// (joshuafolkken/kit#2359), so both are pointed at the backlog.
+const OFFER_BACKLOG = 'pnpm josh backlog:next'
+const EVENT_ACTIONS: Record<string, (issue_number: string) => StepAction> = {
+	[KIND.PR_OPENED]: () => command('pnpm josh followup'),
+	[KIND.REVIEW_ROUND]: () => command('pnpm josh review:round2'),
+	[KIND.MERGE]: (issue_number) => command(`pnpm josh run:merge ${issue_number}`),
+	[KIND.OUTAGE]: (issue_number) => command(`pnpm josh run:merge ${issue_number}`),
+	[KIND.PARK]: () => command(OFFER_BACKLOG),
+	[KIND.CUT]: (issue_number) => command(`pnpm josh run:cut --resume ${issue_number}`),
+	[KIND.CHILD_LAUNCH]: () => verdict(WAIT),
+	// A stall is undispatched ready work with a free lane, so its next step is exactly a park's: offer
+	// the backlog. The detector only reports the stall; reading it here as a dispatch is what turns the
+	// report into the action that resolves it.
+	[KIND.STALL]: () => command(OFFER_BACKLOG),
+	// The post-implementation region is with a detached ship supervisor (joshuafolkken/kit#2428): nothing
+	// is the agent's until the supervisor stops or the issue closes, which the terminal read answers.
+	[KIND.SHIP_LAUNCH]: () => verdict(WAIT),
+	// The supervisor stopped at a failed stage and handed control back — the next step is reading the
+	// report it stopped on, which names the stage and why.
+	[KIND.SHIP_STOP]: (issue_number) => command(`pnpm josh ship --log ${issue_number}`),
+}
+
+// The parent-only positions a dispatched lane child must never act on. `run:merge` is the parent's
+// budget command — a child that ran it read the `busy` it got back as a competing session and parked
+// its Issue unimplemented (joshuafolkken/kit#2267). A merge or an outage is the parent's to classify,
+// so a child at one has nothing to run and stops rather than being handed `run:merge`
+// (joshuafolkken/kit#2297).
+const PARENT_ONLY_EVENTS: ReadonlySet<string> = new Set([KIND.MERGE, KIND.OUTAGE])
+
+// Whether a run at a winding-down position still owes its end-of-run retrospective
+// (joshuafolkken/kit#2328) — false when the switch is off (the opt-in default, joshuafolkken/kit#2370),
+// for a dispatched lane child, where the batch runs one at its own end and never a child's (the
+// `release:scope` precedent), for a run whose retrospective has already run this invocation, and in a
+// consumer checkout, where the kit-only command is refused. The switch is read first, so a run that has
+// not opted in never consults the other three. The two positions that consult it are the drain and the
+// stop; both read exactly this, so the exclusion set is single-sourced.
+function is_retrospective_owed(input: StepInput): boolean {
+	if (!input.is_retrospective_enabled) return false
+
+	return !input.is_lane_child && !input.is_retrospective_done && !input.is_consumer
+}
+
+// A stopped run's last owed step is the end-of-run retrospective. When it is not owed the position stops
+// with no command to run, which is what the position meant before the retrospective existed.
+function stop_action(input: StepInput): StepAction {
+	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(STOP)
+}
+
+// The drain fires the retrospective *before* the idle watch, not after it (joshuafolkken/kit#2335): the
+// retrospective files the improvement issues the watch then picks up, so running it after the watch — as
+// the stop position alone did — spent the watch on an empty pool. When the retrospective is not owed the
+// run proceeds to that watch, which is a `WAIT` rather than a `STOP`: the backlog is empty but the run is
+// not ending, and the real `STOP` follows when the watch expires with the retrospective already done.
+function drain_action(input: StepInput): StepAction {
+	return is_retrospective_owed(input) ? command(RETROSPECTIVE_COMMAND) : verdict(WAIT)
+}
+
+// The two positions whose action needs the whole input rather than the issue number — a stop and a
+// drain both turn on whether the retrospective is still owed. Kept in a map so `next_action` dispatches
+// them in one branch rather than one `if` apiece (`is_retrospective_owed` is the shared gate).
+const FULL_INPUT_ACTIONS: Record<string, (input: StepInput) => StepAction> = {
+	[KIND.STOP]: stop_action,
+	[KIND.DRAIN]: drain_action,
+}
+
+// An event the table does not name leaves the position unknown rather than guessing a next step. A
+// lane child at a parent-only position stops instead — the runtime refusal `lane-carry-conflict.ts`
+// delivers is the same rule one call later, so this keeps a child from ever being pointed at it. The
+// stop position is dispatched by `next_action`, so it is not among the events this handles.
+function event_action(event: string, issue_number: string, is_lane_child: boolean): StepAction {
+	if (is_lane_child && PARENT_ONLY_EVENTS.has(event)) return verdict(STOP)
+
+	return EVENT_ACTIONS[event]?.(issue_number) ?? verdict(UNKNOWN)
+}
+
+// A run that has planned but emitted nothing else is still at its pre-implementation position, so a
+// `plan` reads the same as an empty stream.
+function is_pre_implementation(last_event: string | undefined): boolean {
+	return last_event === undefined || last_event === run_event_stream.EVENT_KIND.PLAN
+}
+
+// **No cut at the setup→implementation boundary** (joshuafolkken/kit#2489). A lane child's context is
+// bounded by the threshold-gated implementation cut alone (`implementation-cut.ts`): the first edit is
+// the moment both would have looked at, and below the threshold a cut there is one that does not pay
+// for itself (`context-cut-payback.ts`), so a planned lane child implements in the same session.
+function pre_implementation_action(input: StepInput): StepAction {
+	return verdict(pre_verdict(input))
+}
+
+// A closed issue ends the run, but a tree still holding uncommitted work is surfaced rather than
+// answered `already-done` — the answer a child read as "nothing to do" before its lane was removed
+// with the work in it (joshuafolkken/kit#2476).
+function closed_action(input: StepInput): StepAction {
+	if (closed_verdict(input) === ALREADY_DONE) return verdict(ALREADY_DONE)
+
+	const message = git_stash.work_message(input.issue_number, ALREADY_DONE)
+
+	return {
+		kind: 'decide',
+		line: `decide: #${input.issue_number} is closed but this tree holds uncommitted work — keep it with \`git stash push -u -m "${message}"\` | carry it into a new issue`,
+	}
+}
+
+// The terminal answers read before the run's position matters: an unreadable carry record leaves the
+// position unknowable, a spent budget is the person's call, and the issue's own state can end the run
+// whatever the events say. `undefined` when none applies and the position decides.
+function terminal_action(input: StepInput): StepAction | undefined {
+	if (input.carry_kind === 'unreadable') return verdict(UNKNOWN)
+	if (input.carry_kind === 'expired') return { kind: 'decide', line: EXPIRED_DECISION }
+	if (input.state === undefined) return verdict(UNKNOWN)
+	if (input.state === CLOSED) return closed_action(input)
+
+	return undefined
+}
+
+// The one entry point: the run's next action, from the three inputs and nothing else. A terminal answer
+// wins first; otherwise a run with nothing emitted yet is at its pre-implementation position, and a run
+// that has begun is placed by its newest event.
+function next_action(input: StepInput): StepAction {
+	const terminal = terminal_action(input)
+
+	if (terminal !== undefined) return terminal
+	if (is_pre_implementation(input.last_event)) return pre_implementation_action(input)
+
+	const event = input.last_event ?? ''
+	const full_input_action = FULL_INPUT_ACTIONS[event]
+
+	if (full_input_action !== undefined) return full_input_action(input)
+
+	return event_action(event, input.issue_number, input.is_lane_child)
+}
+
+const run_step = {
+	ALREADY_DONE,
+	EXPIRED_DECISION,
+	HUMAN_REVIEW,
+	IMPLEMENT,
+	KEEP_WORK,
+	RETROSPECTIVE_COMMAND,
+	STOP,
+	UNKNOWN,
+	UPDATE_DEPS,
+	VOCABULARY,
+	WAIT,
+	next_action,
+	pre_verdict,
+}
+
+export type { PreInput, PreVerdict, StepAction, StepInput }
+export { run_step }

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

@@ -0,0 +1,52 @@
+import { telegram_notify } from '#scripts/git/telegram-notify'
+import type { CarryRead } from './run-carry'
+
+// **A `backlogrun` that halts because a person is needed used to reach nobody once the session was
+// cut** (joshuafolkken/kit#2136). Every remaining child blocked behind a parked one, the backlog
+// drained of anything runnable, the failure streak tripped — each ends the run, and while the session
+// was the person's the stop was there in the conversation. After a cut the parent is a headless
+// `claude -p backlogrun`, so the stop reached its own transcript and nowhere else, and the run sat
+// stopped until someone thought to ask. The 15-minute heartbeat stays a pull; a *stop* is a state
+// change, and a state change is what `confirmation` exists to push.
+//
+// **This is the decision, kept apart from the send so the dedup can be pinned without a Telegram.**
+// `run:carry --end` calls `plan` on the record it is about to remove; `announce` only runs when a
+// notice comes back.
+
+interface StopNotice {
+	reason: string
+}
+
+const STOP_TITLE = 'backlogrun stopped'
+const STOP_RECOVERY =
+	'If this did not arrive, `pnpm josh run:wake --list` relays the last progress line.'
+
+// **Only a stop over a record that is still there is announced, and that is the whole of the dedup**
+// (joshuafolkken/kit#2136). `--end` removes the record, so a second `--end --stopped` — a retried
+// turn, a re-evaluation — reads `none` and plans nothing, which is why one event never sends twice. A
+// clean finish passes no reason and stays silent, because a completed run has its own notification and
+// this type is for the run that halted needing a person. An `unreadable` record is not announced: with
+// nothing readable there is no run this can honestly say stopped.
+function plan(read: CarryRead, reason: string | undefined): StopNotice | undefined {
+	if (reason === undefined || reason.length === 0) return undefined
+	if (read.kind !== 'carried' && read.kind !== 'expired') return undefined
+
+	return { reason }
+}
+
+async function announce(notice: StopNotice): Promise<boolean> {
+	return await telegram_notify.confirm({
+		issue_title: STOP_TITLE,
+		body: notice.reason,
+		recovery: STOP_RECOVERY,
+	})
+}
+
+const run_stop_notify = {
+	STOP_RECOVERY,
+	STOP_TITLE,
+	announce,
+	plan,
+}
+
+export { run_stop_notify }

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

@@ -0,0 +1,31 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_stranded } from './run-stranded'
+import { run_stranded_detect } from './run-stranded-detect'
+
+// `josh run:stranded` — read the three facts once and print the verdict (joshuafolkken/kit#2375). This
+// is the manual and testable face of the detector `stop-guard.ts` runs on every stop; both call the one
+// `detect_and_report`, so the command and the hook can never drift.
+//
+// **It reports, it never stops.** The exit code is always success — a strand is a state to surface, not
+// an error to fail on — so a caller (a person, a test, the wired hook) reads the verdict off stdout and
+// is never halted by it. Anything unreadable prints `ok` for the same reason: nothing carried to strand,
+// so the caller carries on.
+
+const SUCCESS_EXIT_CODE = 0
+
+async function main(): Promise<void> {
+	try {
+		console.info(await run_stranded_detect.detect_and_report())
+	} catch {
+		console.info(run_stranded.OK)
+	}
+
+	process.exitCode = SUCCESS_EXIT_CODE
+}
+
+const run_stranded_cli = { main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
+
+export { run_stranded_cli }

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

@@ -0,0 +1,134 @@
+import { telegram_notify } from '#scripts/git/telegram-notify'
+import { run_carry, type CarryRead, type RunCarry } from './run-carry'
+import { run_event_stream } from './run-event-stream'
+import { run_event_stream_emit } from './run-event-stream-emit'
+import {
+	run_stranded,
+	type StrandedInput,
+	type StrandedVerdict,
+	type SupervisorLiveness,
+} from './run-stranded'
+import { run_wake, type RunWake } from './run-wake'
+
+// The I/O half of the strand detector (joshuafolkken/kit#2375): it gathers the three facts the pure
+// judge in `run-stranded.ts` weighs, then — on a strand — leaves the marker and sends the one
+// notification. `stop-guard.ts` wires it into the Stop hook, so it runs at each loop boundary beside the
+// stall detector it mirrors (joshuafolkken/kit#2359); the CLI exposes the same call for a person to run
+// by hand.
+//
+// **Cheap and local.** Every read is a file on disk — the carry record, the wake record — and a process
+// liveness probe; there is no network call, so unlike the stall detector this makes every read every
+// time. The gate is the carry record itself: nothing carried, or a record that is expired or unreadable,
+// returns before the wake record is even read.
+
+// The recovery line names the command that hands the run to a fresh supervisor — the same one the pure
+// judge holds, so the notification and the recovery can never drift. It is deliberately not
+// `run:carry --resume`: the cutting session is refused `busy` and must stay refused
+// (joshuafolkken/kit#1935), 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 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
+	read_wake: (target: string) => RunWake | undefined
+	supervisor_liveness: (wake: RunWake | undefined) => SupervisorLiveness
+	emit_stranded: (text: string) => Promise<boolean>
+	notify_stranded: (body: string) => Promise<boolean>
+}
+
+interface RecordTargets {
+	carry: string
+	wake: string
+}
+
+// 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) }
+}
+
+async function real_emit_stranded(text: string): Promise<boolean> {
+	return await run_event_stream_emit.emit_once(run_event_stream.EVENT_KIND.STRANDED, text)
+}
+
+async function real_notify_stranded(body: string): Promise<boolean> {
+	return await telegram_notify.stranded({ body, recovery: STRAND_RECOVERY })
+}
+
+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,
+	read_wake: (target) => run_wake.read_wake(target),
+	supervisor_liveness: (wake) => run_stranded.supervisor_liveness(wake),
+	emit_stranded: real_emit_stranded,
+	notify_stranded: real_notify_stranded,
+}
+
+// The three facts, assembled behind the carry-record gate. A non-`carried` read — nothing carried, a
+// spent bound, 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
+
+	const read = ports.read_carry(targets.carry)
+
+	if (read.kind !== 'carried') return undefined
+
+	return {
+		read,
+		is_owner_live: ports.is_owner_live(read.carry),
+		supervisor: ports.supervisor_liveness(ports.read_wake(targets.wake)),
+	}
+}
+
+// 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.
+async function report(ports: DetectPorts, input: StrandedInput): Promise<void> {
+	if (input.read.kind !== 'carried') return
+
+	const text = run_stranded.describe(input.read.carry)
+
+	if (await ports.emit_stranded(text)) await ports.notify_stranded(text)
+}
+
+// Read the three facts, print nothing, and on a strand leave the marker and notify. The verdict is
+// returned for the CLI to print; the side effects are the report's.
+async function detect_and_report(ports: DetectPorts = DEFAULT_PORTS): Promise<StrandedVerdict> {
+	const input = await gather(ports)
+
+	if (input === undefined) return run_stranded.OK
+
+	const is_run_stranded = run_stranded.is_stranded(input)
+
+	if (is_run_stranded) await report(ports, input)
+
+	return run_stranded.verdict_of(is_run_stranded)
+}
+
+// Best-effort for the Stop hook: the detector is a report, so a failure to gather or notify is dropped
+// rather than raised into the stop decision it rides alongside.
+async function run_stranded_check(): Promise<void> {
+	try {
+		await detect_and_report()
+	} catch {
+		// Reporting is best-effort: a strand we could not read or send is dropped, never a blocked stop.
+	}
+}
+
+const run_stranded_detect = { DEFAULT_PORTS, detect_and_report, gather, report, run_stranded_check }
+
+export { run_stranded_detect }
+export type { DetectPorts, RecordTargets }

package/scripts/run/run-stranded.ts

@@ -0,0 +1,120 @@
+import { process_identity } from '#scripts/josh/process-identity'
+import { run_carry, type CarryRead, type RunCarry } from './run-carry'
+import type { RunWake } from './run-wake'
+
+// The mechanical judge of a *stranded* run (joshuafolkken/kit#2375). On 2026-09-22 a `backlogrun`'s
+// cost hand-off left the record carried and handed off, the session that cut it died, no successor ever
+// claimed the budget, and no supervisor was watching — so five lanes ran on with nobody driving, and the
+// only way forward was a person noticing and running the recovery by hand. Three facts, read and never
+// weighed, are what say that state has been reached: the budget was handed off, its owner is gone, and
+// no supervisor is alive to wake a successor.
+//
+// **Pure by design, exactly as `backlog-stalled.ts` is.** The carry read, the owner's liveness and the
+// supervisor's are handed in, so the four acceptance cases — all three holding, a live owner, a claimed
+// successor, and an unreadable record — and the supervisor's three-valued liveness are unit-tested
+// without a process table or a wall clock. The I/O that gathers the three facts is
+// `run-stranded-detect.ts`; this file only decides.
+//
+// **It is a report, never a stop.** A false positive costs one notification, never a halted run or a
+// torn-down lane — so every axis is read toward *not* stranded when it cannot be proven: an unreadable
+// carry record is not stranded, and a supervisor whose liveness cannot be established counts as watching.
+// **And recovery is another actor's, not the reader's** (joshuafolkken/kit#1935): the cutting session is
+// refused `busy` and must stay refused, so what the notification names is `run:wake --start`, which
+// starts a supervisor that wakes a *fresh* successor rather than driving the run itself.
+
+// **The recovery the notification names.** A supervisor started here reads the handed-off record and
+// wakes a successor that claims it with `--owner "$PPID"` — the reader never adopts the budget itself,
+// which is the `busy` refusal `run-carry.ts` → `is_count_refused` exists to keep.
+const RECOVERY_COMMAND = 'pnpm josh run:wake --start'
+
+// The three answers a supervisor's liveness probe gives, named (joshuafolkken/kit#2375). `live` is a
+// supervisor still watching, `gone` is one whose process has died or a record that was never there at
+// all, and `unknown` is the platform answering for nobody — a pid that is alive paired with a start
+// token this machine could not read. The three are kept apart because the strand judge resolves
+// `unknown` toward safety (it counts as watching) while `gone` is the one answer that contributes to a
+// strand.
+type SupervisorLiveness = 'live' | 'gone' | 'unknown'
+
+const LIVE: SupervisorLiveness = 'live'
+const GONE: SupervisorLiveness = 'gone'
+const UNKNOWN: SupervisorLiveness = 'unknown'
+
+type StrandedVerdict = 'stranded' | 'ok'
+
+const STRANDED: StrandedVerdict = 'stranded'
+const OK: StrandedVerdict = 'ok'
+
+// The three facts, assembled by the detect layer and consumed only here. `read` carries the carry
+// record's state, `is_owner_live` whether the process the record names still runs, and `supervisor` the
+// three-valued liveness of the wake record.
+interface StrandedInput {
+	read: CarryRead
+	is_owner_live: boolean
+	supervisor: SupervisorLiveness
+}
+
+// **The supervisor's liveness, three-valued** (joshuafolkken/kit#2375). An absent wake record is `gone`:
+// `run:wake --list` reported `none` in the run this fixes, and nothing watching is the very state a
+// strand needs. A present record is read through `process_identity.is_same_process`, whose own three
+// answers this passes straight through — `true` is `live`, `false` is `gone`, and the platform's "cannot
+// tell" is `unknown`. The prober is injected so the three cases are tested without a real process.
+function supervisor_liveness(
+	wake: RunWake | undefined,
+	same_process: (
+		pid: number | undefined,
+		start: string | undefined,
+	) => boolean | undefined = process_identity.is_same_process,
+): SupervisorLiveness {
+	if (wake === undefined) return GONE
+
+	const is_same = same_process(wake.pid, wake.process_start)
+
+	if (is_same === undefined) return UNKNOWN
+
+	return is_same ? LIVE : GONE
+}
+
+// **The whole of the judgement, in four reads.** The carry record must be `carried` — an `expired`,
+// `none` or `unreadable` read is never a strand, because there is either no budget to strand or no way
+// to trust what the record says. It must be handed off and *not* yet adopted — `adopt_carry` spends
+// `is_handed_off` the instant a successor claims it, so a claimed successor reads `false` here. The owner
+// must be gone — a live owner is a session still spending the budget, the ordinary in-flight state. And
+// the supervisor must be `gone` — `live` or `unknown` both count as something that could still wake a
+// successor, so only a proven-absent supervisor completes the strand.
+function is_stranded(input: StrandedInput): boolean {
+	if (
+		input.read.kind !== 'carried' ||
+		input.read.carry.is_handed_off !== true ||
+		input.is_owner_live
+	) {
+		return false
+	}
+
+	return input.supervisor === GONE
+}
+
+// The one line a person reads in the notification and on the stream: which run is stranded, and why. The
+// carry record's own summary carries the counts; this frames it as the strand it is.
+function describe(carry: RunCarry): string {
+	return `Run stranded — ${run_carry.describe_carry(carry)}. The owner is gone, no cut successor claimed the budget, and no supervisor is watching.`
+}
+
+function verdict_of(is_run_stranded: boolean): StrandedVerdict {
+	return is_run_stranded ? STRANDED : OK
+}
+
+const run_stranded = {
+	GONE,
+	LIVE,
+	OK,
+	RECOVERY_COMMAND,
+	STRANDED,
+	UNKNOWN,
+	describe,
+	is_stranded,
+	supervisor_liveness,
+	verdict_of,
+}
+
+export { run_stranded }
+export type { StrandedInput, StrandedVerdict, SupervisorLiveness }