@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -1,14 +1,16 @@
-// `josh ship "<title> #<N>"` — the one call that ships a finished change (joshuafolkken/kit#2398). It
-// folds the fixed commit-to-report region a run spent a dozen round trips on — the gate, the
-// commit/push/PR (`git -y`), the CI-wait merge (`followup`) and the report bookkeeping (`run:tail`) —
-// into one composite, extending the post-merge fold of `run:tail` (joshuafolkken/kit#2372) into the
-// body of the region. The region is fixed procedure; the one decision it carried — disposing of a
-// review finding — stays in front of this command, so nothing a reader had to judge is folded away.
+// `josh ship "<title> #<N>"` — the one call that ships a finished change. It folds the fixed
+// commit-to-report region — the gate, the commit/push/PR (`git -y`), the CI-wait merge (`followup`)
+// and the report bookkeeping (`run:tail`) — into one composite, extending the post-merge fold of
+// `run:tail` into the body of the region. The region is fixed procedure; the one decision it
+// carried — disposing of a review finding — stays in front of this command, so nothing a reader had
+// to judge is folded away.
 //
 // **This module is the pure half**, kept apart from the chaining CLI the way `run-tail.ts` is. Unlike
 // `run:tail`, ship stops at the first failed step: a red gate must never reach the commit, so the
 // composite ends at the failure, and the report names the step that failed so the run reads only it.
 
+import { run_section, type Section } from '#scripts/run/run-section'
+
 const PREFLIGHT_HEADER = '=== preflight ==='
 const PRE_DETACH_HEADER = '=== pre-detach checks ==='
 const REVIEW_HEADER = '=== review ==='
@@ -18,52 +20,35 @@ const COMMIT_HEADER = '=== commit/push/PR ==='
 const ROUND_TWO_HEADER = '=== round-2 review ==='
 const FOLLOWUP_HEADER = '=== followup ==='
 const REPORT_HEADER = '=== report ==='
-const SECTION_SEPARATOR = '\n\n'
 const STOPPED_PREFIX = 'stopped at: '
-// The body of a stage a resumed ship passed over (joshuafolkken/kit#2426) — a success, so the report
+// The body of a stage a resumed ship passed over — a success, so the report
 // still shows every stage under its header and the reader sees which ones this call did not repeat.
 const SKIPPED_BODY = 'skipped — already done'
 
-const SUCCESS_EXIT_CODE = 0
-const FAILURE_EXIT_CODE = 1
-
-interface ShipSection {
-	header: string
-	body: string
-	code: number
-	// The paths a stopped merge left unmerged (joshuafolkken/kit#3221), handed to the stop prompt.
+type ShipSection = Section & {
+	// The paths a stopped merge left unmerged, handed to the stop prompt.
 	conflicts?: ReadonlyArray<string>
 }
 
-function section_report(section: ShipSection): string {
-	return `${section.header}\n${section.body}`
-}
-
 // The step that stopped the ship, or `undefined` when every executed step was green. Because the
 // composite breaks at the first failure, this is the last section whenever one exists.
 function failed_section(sections: ReadonlyArray<ShipSection>): ShipSection | undefined {
-	return sections.find((section) => section.code !== SUCCESS_EXIT_CODE)
+	return sections.find((section) => section.code !== run_section.SUCCESS_EXIT_CODE)
 }
 
 // The executed steps under their headers, closed with the name of the step that stopped the run so the
 // reader sees which one to fix without counting sections.
 function format_report(sections: ReadonlyArray<ShipSection>): string {
-	const body = sections.map((section) => section_report(section)).join(SECTION_SEPARATOR)
+	const body = run_section.format_sections(sections)
 	const failed = failed_section(sections)
 
 	if (failed === undefined) return body
 
-	return `${body}${SECTION_SEPARATOR}${STOPPED_PREFIX}${failed.header}`
-}
-
-// Non-zero when any executed step failed — the composite only ever collects a failed step as its last,
-// so this reads the same clean/red verdict as the loop that stopped there.
-function exit_code(sections: ReadonlyArray<ShipSection>): number {
-	const is_clean = sections.every((section) => section.code === SUCCESS_EXIT_CODE)
-
-	return is_clean ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	return `${body}${run_section.SECTION_SEPARATOR}${STOPPED_PREFIX}${failed.header}`
 }
 
+// The exit code is non-zero when any executed step failed — the composite only ever collects a failed
+// step as its last, so it reads the same clean/red verdict as the loop that stopped there.
 const run_ship = {
 	COMMIT_HEADER,
 	FOLLOWUP_HEADER,
@@ -76,7 +61,7 @@ const run_ship = {
 	SKIPPED_BODY,
 	SYNC_HEADER,
 	STOPPED_PREFIX,
-	exit_code,
+	exit_code: run_section.exit_code_of,
 	failed_section,
 	format_report,
 }

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

@@ -1,19 +1,20 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { backlog_drive_restore } from '#scripts/backlog/backlog-drive-restore'
 import { issue_merged } from '#scripts/issue/issue-merged'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_tidy } from './run-tidy'
 import { run_tidy_lanes, type IsMerged } from './run-tidy-lanes'
 import { run_tidy_stashes } from './run-tidy-stashes'
 
-// `josh run:tidy` — sweep what merged work left behind at a run's start (joshuafolkken/kit#2701): the
-// lanes still holding a seat after their issue merged, and the stashes whose issues are all merged.
-// Both used to wait for a person — `lane:list` flagged a merged lane, `run:carry --end` printed the
-// closed-issue stashes — and a batch ran with two of six seats held by finished work until someone did.
+// `josh run:tidy` — sweep what merged work left behind at a run's start: the lanes still holding a
+// seat after their issue merged, and the stashes whose issues are all merged.
 //
 // `run:hold` calls `sweep` once a claim succeeds, so every `fullrun` / `halfrun` start runs it; a
 // `backlogrun` runs the command itself in its once-per-repository preparation, beside `lane:prune`.
 // **The sweep never fails the run that called it**: the report goes to standard error, where
 // `run:hold`'s one-token standard output is not disturbed, and a failed read is a note, not an exit.
+// A lane the running `backlogrun` still has in flight is left to its `run:merge`.
 
 const FAILURE_NOTE = 'run:tidy could not finish; merged lanes and stashes may remain:'
 
@@ -33,7 +34,10 @@ function memoized(read: IsMerged): IsMerged {
 async function sweep(): Promise<void> {
 	try {
 		const read_merged = memoized(issue_merged.read_merged)
-		const lanes = await run_tidy_lanes.tidy_lanes(read_merged)
+		const in_flight = backlog_drive_restore.active_issues(
+			await run_event_stream_emit.current_events(),
+		)
+		const lanes = await run_tidy_lanes.tidy_lanes(read_merged, in_flight)
 		const stashes = await run_tidy_stashes.tidy_stashes(read_merged)
 		const report = run_tidy.format_report([...lanes, ...stashes])
 

package/scripts/run/tidy/run-tidy-lanes.ts

@@ -1,14 +1,17 @@
 import { git_spawn } from '#scripts/git/git-spawn'
 import { git_stash } from '#scripts/git/stash/git-stash'
+import { session_cite } from '#scripts/issue/session-cite'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { error_text } from '#scripts/lib/error-message'
 import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_tidy, type Outcome, type Verdict } from './run-tidy'
 
-// The lane half of `josh run:tidy` (joshuafolkken/kit#2701): each lane whose issue merged, read for
-// what would make closing it lose work, then closed with its run record released. A lane whose work
-// tree is already gone is `lane:prune`'s, so it is left to that command.
+// The lane half of `josh run:tidy`: each lane whose issue merged, read for what would make closing it
+// lose work, then closed with its run record released. A lane whose work tree is already gone is
+// `lane:prune`'s, so it is left to that command. A lane the running `backlogrun` still has in flight
+// is left to its `run:merge`: closed here, it would leave the run with no `merge` event, no ledger
+// line and no merged count.
 
 const CLOSED_KIND = 'closed'
 const INCOMPLETE_REASON = 'the close left files behind'
@@ -87,20 +90,28 @@ async function settle(lane: LaneInfo): Promise<Verdict> {
 	}
 }
 
-async function tidy_lane(lane: LaneInfo, is_merged: IsMerged): Promise<Outcome | undefined> {
+async function tidy_lane(
+	lane: LaneInfo,
+	is_merged: IsMerged,
+	in_flight: ReadonlySet<string>,
+): Promise<Outcome | undefined> {
+	if (in_flight.has(lane.issue)) return undefined
 	if (lane.is_stranded || !(await is_merged(lane.issue))) return undefined
 
-	return { target: `lane #${lane.issue}`, verdict: await settle(lane) }
+	return { target: `lane ${session_cite.issue(lane.issue)}`, verdict: await settle(lane) }
 }
 
 // One lane at a time: a close removes a work tree and prunes the worktree list the next read uses.
-async function tidy_lanes(is_merged: IsMerged): Promise<Array<Outcome>> {
+async function tidy_lanes(
+	is_merged: IsMerged,
+	in_flight: ReadonlySet<string> = new Set(),
+): Promise<Array<Outcome>> {
 	const outcomes: Array<Outcome> = []
 	const lanes = await lane_registry.list_lanes()
 
 	for (const lane of lanes) {
 		// eslint-disable-next-line no-await-in-loop -- a close prunes the worktree list the next one reads
-		const outcome = await tidy_lane(lane, is_merged)
+		const outcome = await tidy_lane(lane, is_merged, in_flight)
 
 		if (outcome !== undefined) outcomes.push(outcome)
 	}

package/scripts/run/tidy/run-tidy-stashes.ts

@@ -7,18 +7,18 @@ import { observation_ledger_home } from '#scripts/observations/observation-ledge
 import { run_tidy, type Outcome, type Verdict } from './run-tidy'
 import type { IsMerged } from './run-tidy-lanes'
 
-// The stash half of `josh run:tidy` (joshuafolkken/kit#2701): each entry whose named issues are all
-// merged is dropped, and one that touches the observation ledger has its lines carried into the ledger
-// first. The ledger is append-only and the digest counts repeats across it, so an entry's lines are
-// never discarded with the entry.
+// The stash half of `josh run:tidy`: each entry whose named issues are all merged is dropped, and one
+// that touches the observation ledger has its lines carried into the ledger first. The ledger is
+// append-only and the digest counts repeats across it, so an entry's lines are never discarded with
+// the entry.
 
 // The same width `run-carry-stash.ts` reads issue states at.
 const READ_CONCURRENCY = 8
 const GONE_REASON = 'already dropped by another run'
 const BUSY_REASON = 'another run held the stash sweep lock'
 
-// An entry cut before joshuafolkken/kit#2919 holds its lines at an old single-file path, so the lines
-// of every ledger path it touches are carried to the current ledger. The reads are independent, and the
+// An older entry may hold its lines at an old single-file path, so the lines of every ledger path it
+// touches are carried to the current ledger. The reads are independent, and the
 // lines come back in path order however the reads finish.
 async function added_ledger_lines(
 	hash: string,
@@ -34,8 +34,8 @@ async function added_ledger_lines(
 }
 
 // How many ledger lines went into the running work tree's ledger before the drop. The duplicate check
-// reads every issue's file, and the lines land in the file this tree writes (joshuafolkken/kit#2919),
-// so the run's own commit takes them to the default branch.
+// reads every issue's file, and the lines land in the file this tree writes, so
+// the run's own commit takes them to the default branch.
 async function carry_ledger(hash: string): Promise<number> {
 	const changed = await git_stash.changed_paths(hash)
 	const ledger_paths = changed.filter((file_path) => observation_ledger.is_ledger_path(file_path))

package/scripts/run/tidy/run-tidy.ts

@@ -1,7 +1,8 @@
+import { session_cite } from '#scripts/issue/session-cite'
 import { observation_ledger_line } from '#scripts/observations/observation-ledger-line'
 
-// The decisions behind `josh run:tidy` (joshuafolkken/kit#2701), kept apart from the git and GitHub
-// reads so each can be pinned without either. A run start sweeps what merged work left behind — the
+// The decisions behind `josh run:tidy`, kept apart from the git and GitHub reads so each
+// can be pinned without either. A run start sweeps what merged work left behind — the
 // lanes holding a seat after their branch merged, and the stashes of issues that are all merged — and
 // every rule here is written so that doubt keeps the thing: a lane with any uncommitted change or any
 // commit no remote has, and a stash naming any issue that is not merged or naming none at all, stay.
@@ -52,7 +53,7 @@ function lane_verdict(facts: LaneFacts): Verdict | undefined {
 }
 
 function unmerged_reason(unmerged: ReadonlyArray<string>): string {
-	const named = unmerged.map((issue) => `#${issue}`).join(', ')
+	const named = unmerged.map((issue) => session_cite.issue(issue)).join(', ')
 
 	return `${named} not merged`
 }

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

@@ -18,10 +18,9 @@ import { run_wake_restart, type RestartPorts } from './run-wake-restart'
 import { run_wake_session, type LaunchResult } from './run-wake-session'
 
 // `josh run:wake --start | --list | --stop | --loop` — the supervisor that continues a cut
-// `backlogrun` or `queue` without a person retyping the keyword (joshuafolkken/kit#1719,
-// joshuafolkken/kit#1774). **Which invocations it may continue is `run-invocation.ts`'s answer**, not
-// this file's: nothing here reads the recorded text, it is handed to `wake_argv` and either rebuilt
-// from that module's own constants or refused.
+// `backlogrun` or `queue` without a person retyping the keyword. **Which invocations it may continue
+// is `run-invocation.ts`'s answer**, not this file's: nothing here reads the recorded text, it is
+// handed to `wake_argv` and either rebuilt from that module's own constants or refused.
 //
 // The stdout/stderr split is the contract every `run:*` command shares: exactly one verdict token on
 // stdout on every path, the reason and the advice on stderr, so a loop branches on one token.
@@ -56,26 +55,24 @@ const UNKNOWN_VERDICT = 'unknown'
 const FAILED_VERDICT = 'failed'
 
 // **The note covers both ways `wake_argv` answers `undefined`**, because it cannot tell them apart and
-// a message that named only the first would accuse a legitimate invocation of carrying unsafe text
-// (joshuafolkken/kit#1774). The second is the one a person actually meets: a `queue` whose references
-// carry a `owner/repo#` prefix is a grammar this supervisor does not rebuild, and `queue.md` → "The
-// session boundary" is why such a queue begins no record in the first place.
+// a message that named only the first would accuse a legitimate invocation of carrying unsafe text.
+// The second is the one a person actually meets: a `queue` whose references carry a `owner/repo#`
+// prefix is a grammar this supervisor does not rebuild, and `queue.md` → "The session boundary" is why
+// such a queue begins no record in the first place.
 const UNSAFE_INVOCATION_NOTE =
 	'the carried invocation is not one this supervisor can continue — it is neither a backlogrun nor a queue it can rebuild, or it carries text that may not be passed to a command line'
-// The command rather than one entry point: since joshuafolkken/kit#1774 the supervisor continues a
-// `queue` as readily as a `backlogrun`, and a warning that named the wrong one would send the reader
-// looking at a run that is not the one that stopped.
+// The command rather than one entry point: the supervisor continues a `queue` as readily as a
+// `backlogrun`, and a warning that named the wrong one would send the reader looking at a run that is
+// not the one that stopped.
 const WARNING_TITLE = 'run:wake supervisor'
 const WARNING_RECOVERY = `Check the wake command, then restart with \`pnpm josh run:wake --start\`.`
-// **The stop reasons that reach a person, and what each one tells them** (joshuafolkken/kit#1746). A
-// reason absent from this map is one where nothing went wrong: `ended` is the run finishing through
-// `run:carry --end`, `stopped` is a person's own `--stop` or a supervisor being superseded, and a
-// warning channel that fired on those is one that stops being read.
+// **The stop reasons that reach a person, and what each one tells them.** A reason mapped to
+// `undefined` is one where nothing went wrong: `ended` is the run finishing through `run:carry --end`,
+// `stopped` is a person's own `--stop` or a supervisor being superseded, and a warning channel that
+// fired on those is one that stops being read.
 //
-// **`expired` and `unreadable` were silent until joshuafolkken/kit#1746, and that was the defect
-// rather than the design.** Both end the supervisor while a carry record is still sitting there handed
-// off, so the run is left asleep with nothing anywhere saying so — a silent overnight failure, while
-// only the `failed` reason was wired to the notification.
+// **`expired` and `unreadable` warn**, because both end the supervisor while a carry record is still
+// sitting there handed off, so the run would otherwise be left asleep with nothing anywhere saying so.
 // **Every reason is listed, and the silent two are listed as `undefined`.** A partial map would let a
 // sixth stop reason compile straight past this and reach nobody, which is the defect class this
 // section exists to close.
@@ -145,7 +142,7 @@ async function resolve_context(): Promise<WakeContext | undefined> {
 
 	// 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 (joshuafolkken/kit#1759).
+	// neither of which launches anything.
 	run_wake_session.ensure_log(log_target, note_to_stderr)
 
 	return {
@@ -178,7 +175,7 @@ function wake_session(
 	if (built.kind === 'rejected') return { kind: 'failed', note: built.note }
 
 	// The headless mark is what lets the stop hook hold this session's turn open while its lanes run —
-	// under `claude -p` a turn-end is the process's end (`run-headless.ts`, joshuafolkken/kit#2437).
+	// 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 }
 
@@ -224,10 +221,9 @@ async function warn_of_stop(stop: LoopStop, body: string, context: WakeContext):
 	})
 }
 
-// **Only a failed wake exits non-zero, and the two reasons that newly warn do not**
-// (joshuafolkken/kit#1746). The verdict-and-exit-code table in `docs/josh-commands-automation.md` is a contract
-// callers branch on; what `expired` and `unreadable` were missing is the notification, not a different
-// exit code, and changing both at once would break a caller to fix a silence.
+// **Only a failed wake exits non-zero; `expired` and `unreadable` warn but exit zero.** The
+// verdict-and-exit-code table in `docs/josh-commands-automation.md` is a contract callers branch on,
+// and what those two need is the notification, not a different exit code.
 function exit_code_of(reason: WakeStopReason): number {
 	return reason === run_wake_loop.FAILED_REASON ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
 }
@@ -235,7 +231,7 @@ function exit_code_of(reason: WakeStopReason): number {
 // A failure that reached nobody is the defect, so the Telegram goes out before the verdict is printed.
 // Which stops reach a person, and what each one says — `undefined` for the two where nothing went
 // wrong. It is a function rather than a bare lookup so the decision can be asserted for every reason
-// the loop can end on, which is the contract joshuafolkken/kit#1746 changed.
+// the loop can end on.
 function stop_body(reason: WakeStopReason): string | undefined {
 	return STOP_BODIES[reason]
 }
@@ -256,8 +252,8 @@ function spawn_supervisor(context: WakeContext, interval: string | undefined): n
 	if (profile === undefined) return report(FAILED_VERDICT, FAILURE_EXIT_CODE)
 	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 before joshuafolkken/kit#1746 its `console.error` — the launch note that
-	// says the agent CLI is not on `PATH`, and the stop note behind every warning — went nowhere at all.
+	// 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(
 		{
 			argv,
@@ -297,9 +293,8 @@ function start(context: WakeContext, interval: string | undefined): number {
 	return spawn_supervisor(context, interval)
 }
 
-// **The loop removes its record on the way out, and only its own** (joshuafolkken/kit#1727). A loop
-// that ended after its record was taken over used to delete the *successor's* record here, and the
-// run then went on with nobody watching it.
+// **The loop removes its record on the way out, and only its own.** A loop that ended after its record
+// was taken over must not delete the *successor's* record, or the run goes on with nobody watching it.
 //
 // **`superseded` is announced, because the two ways of ending look identical otherwise.** A `--stop`
 // and a take-over both leave this loop reporting `stopped` at exit 0, so a supervisor that was
@@ -322,7 +317,7 @@ function restart_ports(context: WakeContext, ports: LoopPorts, interval_ms: numb
 }
 
 // A failed pass is restarted while the carry record is still resumable (`run-wake-restart.ts`), so
-// only a failure past the restart bound reaches `finish` and its warning (joshuafolkken/kit#3332).
+// only a failure past the restart bound reaches `finish` and its warning.
 // **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.

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

@@ -6,9 +6,8 @@ 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'
 
-// The `--list` presentation of a wake record (joshuafolkken/kit#2407 split it out of `run-wake-cli.ts`,
-// which had reached its line limit). What the command *does* stays in the CLI; how a supervisor's
-// record reads back to a person lives here, one cohesive block.
+// 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
@@ -21,14 +20,13 @@ const UNREADABLE_TIME = 'an unreadable time'
 interface WakeContext {
 	carry_target: string
 	wake_target: string
-	// Where everything this supervisor starts writes its output (joshuafolkken/kit#1746). It is named
+	// 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.
 	log_target: string
 	// The run's event stream, keyed on the primary checkout's git directory — the one the resumed
 	// `backlogrun` parent runs in, so its own git directory is this common one, exactly the key the emit
 	// 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
-	// (joshuafolkken/kit#2207).
+	// `--list` is the degenerate last-event read of the same stream the attached session follows.
 	event_target: string
 	worktree: string
 }
@@ -39,10 +37,9 @@ function carry_cuts(read: CarryRead): string {
 	return UNKNOWN_CUTS
 }
 
-// **A wake that has gone out and has not been answered is said out loud** (joshuafolkken/kit#1746).
-// Read from `woke` and `cuts` alone, the forty minutes a supervisor spends retrying one lost cut look
-// exactly like the second before its first launch — so a person checking on a stalled backlog was
-// shown nothing to check. `attempts` is present only while a cut is unserved, which is why its
+// **A wake that has gone out and has not been answered is said out loud.** Read from `woke` and `cuts`
+// alone, the forty minutes a supervisor spends retrying one lost cut look exactly like the second
+// before its first launch. `attempts` is present only while a cut is unserved, which is why its
 // absence is what prints nothing.
 function outstanding_line(wake: RunWake): string | undefined {
 	if (wake.attempts === undefined) return undefined
@@ -50,10 +47,10 @@ function outstanding_line(wake: RunWake): string | undefined {
 	return `${String(wake.attempts)} launch(es) outstanding for the current cut, none claimed yet`
 }
 
-// **Why the supervisor is not launching, and until when** (joshuafolkken/kit#3363). A supervisor that
-// waits writes nothing to its log, so before this `--list` showed a stalled run and a waiting one
-// alike. The state is `run_wake.decide`'s own answer rather than a second reading of the record: an
-// `idle_since` mark is the last pass having found no work, so it is fed back in as `has_work: false`.
+// **Why the supervisor is not launching, and until when.** A supervisor that waits writes nothing to
+// its log, so without this `--list` would show a stalled run and a waiting one alike. The state is
+// `run_wake.decide`'s own answer rather than a second reading of the record: an `idle_since` mark is
+// the last pass having found no work, so it is fed back in as `has_work: false`.
 function wait_input(wake: RunWake, read: CarryRead, now: Date): WakeDecisionInput {
 	return {
 		read,
@@ -100,26 +97,25 @@ function wait_line(wake: RunWake, read: CarryRead, now: Date): string | undefine
 }
 
 // The run's stream, read here because a headless parent's progress reaches its own transcript alone —
-// after a cut, `--list` is the person's one window onto it (joshuafolkken/kit#1910). Two lines: the
-// newest event (the degenerate last-event read of the stream the watch pane follows, so `--list` and
-// the pane read one stream rather than two paths), and how to watch on from here in a pane of its own —
-// the same surface before and after the cut, with `tail -F` on the raw stream named as a recovery path
-// rather than the ambient one (joshuafolkken/kit#2207, joshuafolkken/kit#2492). The event line is
-// omitted before the first event, the way `outstanding_line` omits a count of zero; the watch line is
-// always shown.
+// after a cut, `--list` is the person's one window onto it. Two lines: the newest event (the
+// degenerate last-event read of the stream the board pane draws, so `--list` and the pane read one
+// stream rather than two paths), and how to watch on from here in a pane of its own — `run:board`, the
+// same surface before and after the cut, with `tail -F` on the raw stream named as a recovery path
+// rather than the ambient one. The event line is omitted before the first event, the way
+// `outstanding_line` omits a count of zero; the watch line is always shown.
 function stream_lines(context: WakeContext): Array<string> {
 	const event = run_event_stream.read_last(context.event_target)
 	const progress = event === undefined ? [] : [`progress: ${run_event_stream.format_event(event)}`]
-	const follow = `watch: \`pnpm josh run:event --watch ${String(event?.pos ?? 0)}\` in a pane of its own (recover with \`tail -F ${context.event_target}\`)`
+	const follow = `watch: \`pnpm josh run:board\` in a pane of its own (recover with \`tail -F ${context.event_target}\`)`
 
 	return [...progress, follow]
 }
 
 // The wake count is printed beside the carry record's `cuts` rather than alone, because their relation
 // is the property worth being able to check — one wake per cut, plus one per crashed session the
-// supervisor recovered (joshuafolkken/kit#2336), so `woke >= cuts` and the gap is the recoveries.
-// `woke < cuts` is the shortfall that says a cut went unserved, and since joshuafolkken/kit#1746 `woke`
-// counts records actually claimed rather than sessions started.
+// supervisor recovered, so `woke >= cuts` and the gap is the recoveries. `woke < cuts` is the
+// shortfall that says a cut went unserved; `woke` counts records actually claimed rather than sessions
+// started.
 // **The outstanding line beside it is what makes a shortfall readable**: the count is observed at a
 // poll, so it lags a claim by up to one interval, and launches still outstanding are what say whether
 // a missing wake is one not yet seen or one that never arrived.
@@ -136,8 +132,8 @@ function describe_wake(wake: RunWake, context: WakeContext, now: Date = new Date
 		wait_line(wake, read, now),
 		run_liveness.describe_agent_state(context.log_target),
 		`output: ${context.log_target}`,
-		// How progress is seen without asking after the cut: the run's stream, followed from here
-		// (joshuafolkken/kit#2207). `--list` is that reader's one-shot last-event form.
+		// How progress is seen without asking after the cut: the run's stream, followed from here.
+		// `--list` is that reader's one-shot last-event form.
 		...stream_lines(context),
 		`stop it with \`${STOP_COMMAND}\``,
 	]
@@ -145,7 +141,7 @@ function describe_wake(wake: RunWake, context: WakeContext, now: Date = new Date
 		.join('\n')
 }
 
-// The description as a person reads it, every issue on it a number-link (joshuafolkken/kit#2943). The
+// The description as a person reads it, every issue on it a number-link. The
 // invocation and the newest event both name issues (`backlogrun #1 #2`, `#1904 merged`), and a report
 // that copies them bare is what the Stop guard sends back. The repository is asked here, bounded, rather
 // than in the context every verb resolves: only the two describing verbs print it, and a lookup that

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

@@ -28,8 +28,8 @@ function is_final_stop(verdict: string | undefined, read: CarryRead): boolean {
 	return verdict?.startsWith('stop') === true && read.kind === 'none'
 }
 
-// **The details are the driver's whole stderr, so only their tail is handed on, and it goes last**
-// (joshuafolkken/kit#2931). The stderr carries every command the driver ran since it started, which
+// **The details are the driver's whole stderr, so only their tail is handed on, and it goes last.**
+// The stderr carries every command the driver ran since it started, which
 // after a long run is tens of kilobytes — far past what `is_safe_value` lets into an argv element. Its
 // tail is where the reason for stopping is; placing it last means the cap `wake_argv` applies to the
 // whole prompt can only ever cut into the details, never the verdict, the resume line or the epic note.
@@ -39,11 +39,11 @@ function details_tail(details: string): string {
 		: details
 }
 
-// **The hand-off names its next move, so the woken session never searches the procedure for it**
-// (joshuafolkken/kit#3156). Whatever the branch, the session acts on it and hands the loop back to the
-// supervisor with a cut; only a person's stop ends the run instead.
+// **The hand-off names its next move, so the woken session never searches the procedure for it.**
+// Whatever the branch, the session acts on it and hands the loop back to the supervisor with a cut;
+// only a person's stop ends the run instead.
 //
-// **The claim comes first** (joshuafolkken/kit#3238). The supervisor hands the record off before the
+// **The claim comes first.** The supervisor hands the record off before the
 // wake, so until the session adopts it with `--resume` every count it writes — `--merged`, `--done`,
 // the closing `--cut` — is refused as advancing a handed-off budget, and the supervisor, seeing no
 // claim, ends the run as a failed wake.
@@ -100,9 +100,9 @@ function driver_result(
 	return { kind: 'judgment', material: handoff_material(verdict, resume, invocation, details) }
 }
 
-// **The cause is the driver's stdout `error …` line, so it leads the note** (joshuafolkken/kit#3242).
-// `backlog:drive` prints an exception only to stdout, and its stderr is never empty — every command it
-// ran is there — so reading `err ?? out` dropped the one line that said why. The stderr follows as its
+// **The cause is the driver's stdout `error …` line, so it leads the note.** `backlog:drive` prints an
+// exception only to stdout, and its stderr is never empty — every command it ran is there — so reading
+// `err ?? out` would drop the one line that says why. The stderr follows as its
 // tail, for the same reason `details_tail` cuts a judgment's details.
 function cause_of(out: string): string {
 	const errors = out.split('\n').filter((line) => line.startsWith(ERROR_PREFIX))
@@ -133,11 +133,11 @@ function claim_record(target: string, invocation: string): boolean {
 	return run_carry.adopt_carry(target, current.carry, run_carry.owner_of(process.pid)) !== undefined
 }
 
-// **A verdict with nothing to judge is re-driven here, never handed to a session** (joshuafolkken/kit#3245).
-// A woken session met with `window`, `merge busy` or `merge retry` only cut and handed the loop back, and
-// the supervisor then ran the very same driver again — a model round trip, at a cache write each, that
-// decided nothing. The record is already this process's, so the rerun needs no fresh claim; the limit
-// keeps a driver that never settles from holding the supervisor past its own checks.
+// **A verdict with nothing to judge is re-driven here, never handed to a session.** A woken session
+// met with `window`, `merge busy` or `merge retry` could only cut and hand the loop back for the same
+// driver to run again — a model round trip, at a cache write each, that decides nothing. The record
+// is already this process's, so the rerun needs no fresh claim; the limit keeps a driver that never
+// settles from holding the supervisor past its own checks.
 const RERUN_VERDICTS: ReadonlyArray<string> = ['window', 'merge busy', 'merge retry']
 const RERUN_LIMIT = 10
 const RERUN_PAUSE_MS = 60_000

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

@@ -1,13 +1,13 @@
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { run_carry } from '#scripts/run/carry/run-carry'
 
-// The supervisor's recovery hand-off (joshuafolkken/kit#2437). A session that claimed the carry record
-// and then died without `run:carry --cut` leaves it `carried`, owned by a gone process, with no
-// hand-off. `run-wake.ts` → `decide_not_handed_off` already re-wakes on that record (#2336), but the
-// successor it woke then ran `--begin` over a record no cut handed off and was answered `standing` —
-// "stop for a person" — so the recovery ended the run it existed to continue.
+// The supervisor's recovery hand-off. A session that claimed the carry record and then died without
+// `run:carry --cut` leaves it `carried`, owned by a gone process, with no hand-off. `run-wake.ts` →
+// `decide_not_handed_off` re-wakes on that record, and a successor running `--begin` over a record no
+// cut handed off would be answered `standing` — "stop for a person" — ending the run the recovery
+// exists to continue.
 //
-// **The fix is to make the recovery a cut, not to teach the successor a second answer.** Before it
+// **The recovery is made a cut, rather than teaching the successor a second answer.** Before it
 // launches, the supervisor writes the same `is_handed_off` a `--cut` writes, so the successor's
 // `--begin` classifies `resume` through the one path a declared cut already takes, and `standing` is
 // left meaning what `backlogrun-steps.md` says it means: a record nobody is watching.