@joshuafolkken/kit 1.1050.0 → 1.1094.0

package/scripts/run/run-stage.ts

@@ -0,0 +1,160 @@
+// joshuafolkken/kit#3042: the workflow commands form a ladder — `kickoff` → `halfrun` → `prrun` →
+// `fullrun` — and **the command typed decides only how far a run goes; where it starts is read off the
+// issue**. A run that finds work already done resumes after it rather than redoing it, and a command
+// whose stopping point the issue has already reached reports that and stops.
+//
+// This module is the pure half of that rule: the five states an issue can be found in, the four
+// commands, and the one table that maps a (state, command) pair to a start and an end. `run:entry` reads
+// the state (`run-stage-read.ts`) and branches on the answer; the stage table in
+// `docs/how-to/run-issues.md` and each stop's `Next:` line are pinned to this module by
+// `run-stage-document.test.ts`, so the prose cannot drift from what the entry does.
+
+const KICKOFF = 'kickoff'
+const HALFRUN = 'halfrun'
+const PRRUN = 'prrun'
+const FULLRUN = 'fullrun'
+
+// In ladder order: a command's index plus one is the state rank it brings an issue to.
+const COMMANDS = [KICKOFF, HALFRUN, PRRUN, FULLRUN] as const
+
+type StageCommand = (typeof COMMANDS)[number]
+
+// What `run:entry` serves when no command is named — the one it served alone before the ladder existed.
+const DEFAULT_COMMAND: StageCommand = FULLRUN
+
+const FRESH = 'fresh'
+const PLANNED = 'planned'
+const HALFRUN_STOPPED = 'halfrun-stopped'
+const PRRUN_STOPPED = 'prrun-stopped'
+const MERGED = 'merged'
+
+// In ladder order: a state's index is how many rungs the issue has already climbed.
+const STATES = [FRESH, PLANNED, HALFRUN_STOPPED, PRRUN_STOPPED, MERGED] as const
+
+type StageState = (typeof STATES)[number]
+
+const REACHED = 'reached'
+
+// Where a run picks the issue up from each state — the first piece of work not yet done. A merged issue
+// has none: every command has reached it.
+const STARTS: Readonly<Record<StageState, string>> = {
+	[FRESH]: 'plan',
+	[PLANNED]: 'implement',
+	[HALFRUN_STOPPED]: 'gate',
+	[PRRUN_STOPPED]: 'followup',
+	[MERGED]: REACHED,
+}
+
+// Every start a decision can print, in ladder order — the `run:entry` oracle's vocabulary.
+const START_TOKENS: ReadonlyArray<string> = [...new Set(Object.values(STARTS))]
+
+// Where each command stops.
+const ENDS: Readonly<Record<StageCommand, string>> = {
+	[KICKOFF]: 'plan posted',
+	[HALFRUN]: 'gated, before the commit',
+	[PRRUN]: 'green, mergeable PR',
+	[FULLRUN]: 'merged',
+}
+
+const NEXT_PREFIX = 'Next: '
+const NEXT_SEPARATOR = ' | '
+const STATE_HEADER = 'Issue state'
+const CELL_ARROW = ' → '
+const REACHED_CELL = 'reached — report and stop'
+
+interface StageFacts {
+	is_closed: boolean
+	is_prrun_stopped: boolean
+	is_halfrun_stopped: boolean
+	is_planned: boolean
+}
+
+interface StageDecision {
+	state: StageState
+	command: StageCommand
+	// The first piece of work the run does, or `reached` when there is none left for this command.
+	start: string
+	end: string
+	is_reached: boolean
+}
+
+function to_command(value: string | undefined): StageCommand | undefined {
+	return COMMANDS.find((command) => command === value)
+}
+
+// The furthest rung the facts show, so a closed issue is merged whatever its hold still says.
+function state_of(facts: StageFacts): StageState {
+	if (facts.is_closed) return MERGED
+	if (facts.is_prrun_stopped) return PRRUN_STOPPED
+	if (facts.is_halfrun_stopped) return HALFRUN_STOPPED
+
+	return facts.is_planned ? PLANNED : FRESH
+}
+
+function decide(state: StageState, command: StageCommand): StageDecision {
+	const is_reached = STATES.indexOf(state) > COMMANDS.indexOf(command)
+	const start = is_reached ? REACHED : STARTS[state]
+
+	return { state, command, start, end: ENDS[command], is_reached }
+}
+
+// The commands that go further than `command`, nearest first — what a stop offers next.
+function next_commands(command: StageCommand): ReadonlyArray<StageCommand> {
+	return COMMANDS.slice(COMMANDS.indexOf(command) + 1)
+}
+
+// The `Next:` line a stop's Telegram and report carry, e.g. `Next: prrun #<N> | fullrun #<N>`.
+function next_line(command: StageCommand, issue: string): string {
+	const commands = next_commands(command).map((next) => `${next} #${issue}`)
+
+	return `${NEXT_PREFIX}${commands.join(NEXT_SEPARATOR)}`
+}
+
+function format_decision(issue: string, decision: StageDecision): string {
+	const fields = [`at: ${decision.state}`, `to: ${decision.command}`, `start: ${decision.start}`]
+
+	return `stage #${issue} — ${fields.join(' · ')}`
+}
+
+function cell(state: StageState, command: StageCommand): string {
+	const decision = decide(state, command)
+
+	return decision.is_reached ? REACHED_CELL : `${decision.start}${CELL_ARROW}${decision.end}`
+}
+
+// The stage table as rows of cells, header first — the shape both documents carry.
+function table_rows(): ReadonlyArray<ReadonlyArray<string>> {
+	const header = [STATE_HEADER, ...COMMANDS.map((command) => `\`${command}\``)]
+	const rows = STATES.map((state) => [
+		`\`${state}\``,
+		...COMMANDS.map((command) => cell(state, command)),
+	])
+
+	return [header, ...rows]
+}
+
+const run_stage = {
+	COMMANDS,
+	DEFAULT_COMMAND,
+	FRESH,
+	HALFRUN,
+	HALFRUN_STOPPED,
+	KICKOFF,
+	MERGED,
+	PLANNED,
+	PRRUN,
+	PRRUN_STOPPED,
+	REACHED,
+	START_TOKENS,
+	STATES,
+	decide,
+	format_decision,
+	next_commands,
+	next_line,
+	state_of,
+	table_rows,
+	to_command,
+} as const
+
+export type { StageCommand, StageDecision, StageFacts, StageState }
+export { run_stage }

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

@@ -168,7 +168,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_status_cli = { USAGE, parse, run }
+const run_status_cli = { parse, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

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

@@ -44,18 +44,22 @@ function is_handed_off_here(carry: CarryRead): boolean {
 	return run_headless.is_owned_here(carry.carry, lane_reap.own_ancestry)
 }
 
+const UNREADABLE_RUN: RunReads = {
+	carry_kind: 'unreadable',
+	is_retrospective_done: false,
+	is_at_cut_cap: false,
+	is_handed_off: false,
+	last_event: undefined,
+}
+
 // The run-level reads, keyed on the common git directory both the carry and the event stream share. A
 // directory that cannot be read leaves the position unknowable, which `next_action` answers `unknown`.
-function read_run(directory: string | undefined, issue_number: string): RunReads {
-	if (directory === undefined) {
-		return {
-			carry_kind: 'unreadable',
-			is_retrospective_done: false,
-			is_at_cut_cap: false,
-			is_handed_off: false,
-			last_event: undefined,
-		}
-	}
+function read_run(
+	directory: string | undefined,
+	issue_number: string,
+	is_lane_child: boolean,
+): RunReads {
+	if (directory === undefined) return UNREADABLE_RUN
 
 	const carry = run_carry.read_carry(run_carry.carry_path(directory))
 	const events = run_event_stream.read_events(run_event_stream.target_of(directory))
@@ -63,11 +67,13 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 	// invocation left on the stream must not be read as this run's position (joshuafolkken/kit#2395). The
 	// observed defect was a `run:step` that printed `wait` on a fresh run because an old `child-launch` was
 	// still the stream's tail. Another issue's detached ship supervisor is left out the same way
-	// (joshuafolkken/kit#2428).
+	// (joshuafolkken/kit#2428), and so — for a lane child — is every event that does not name its own issue
+	// (joshuafolkken/kit#3039).
 	const last = run_event_scope.last_issue_event(
 		events,
 		run_event_scope.scope_of(carry),
 		issue_number,
+		is_lane_child,
 	)
 
 	return {
@@ -82,7 +88,8 @@ function read_run(directory: string | undefined, issue_number: string): RunReads
 async function gather(issue_number: string): Promise<StepInput> {
 	const reads = await run_prep_cli.gather(issue_number)
 	const parts = run_prep_cli.to_parts(issue_number, reads)
-	const run_reads = read_run(await run_carry.repository_directory(), issue_number)
+	const is_lane_child = lane_child_marker.is_child_of(process.cwd())
+	const run_reads = read_run(await run_carry.repository_directory(), issue_number, is_lane_child)
 
 	return {
 		issue_number,
@@ -94,7 +101,7 @@ async function gather(issue_number: string): Promise<StepInput> {
 		is_retrospective_done: run_reads.is_retrospective_done,
 		is_at_cut_cap: run_reads.is_at_cut_cap,
 		is_handed_off: run_reads.is_handed_off,
-		is_lane_child: lane_child_marker.is_child_of(process.cwd()),
+		is_lane_child,
 		is_consumer: doctor_consumer.is_kit_consumer(find_package_directory(process.cwd())),
 		// Read here rather than in `run-step.ts` so the position logic stays a pure function of its input.
 		is_retrospective_enabled: run_retrospective.is_enabled(),
@@ -128,7 +135,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_step_cli = { USAGE, gather, main, run }
+const run_step_cli = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/run/run-step.ts

@@ -1,4 +1,4 @@
-import { git_stash } from '#scripts/git/git-stash'
+import { git_stash } from '#scripts/git/stash/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'

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

@@ -1,4 +1,4 @@
-import { telegram_notify } from '#scripts/git/telegram-notify'
+import { telegram_notify } from '#scripts/notify/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
@@ -43,8 +43,6 @@ async function announce(notice: StopNotice): Promise<boolean> {
 }
 
 const run_stop_notify = {
-	STOP_RECOVERY,
-	STOP_TITLE,
 	announce,
 	plan,
 }

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

@@ -24,8 +24,4 @@ async function main(): Promise<void> {
 	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

@@ -1,4 +1,4 @@
-import { telegram_notify } from '#scripts/git/telegram-notify'
+import { telegram_notify } from '#scripts/notify/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'
@@ -128,7 +128,7 @@ async function run_stranded_check(): Promise<void> {
 	}
 }
 
-const run_stranded_detect = { DEFAULT_PORTS, detect_and_report, gather, report, run_stranded_check }
+const run_stranded_detect = { detect_and_report, run_stranded_check }
 
 export { run_stranded_detect }
 export type { DetectPorts, RecordTargets }

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

@@ -22,7 +22,6 @@ import { run_tail, type TailSection } from './run-tail'
 // step for a line written on the default branch outside any issue's run.
 
 const ARGV_OFFSET = 2
-const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh run:tail [<issue-number> ...]'
@@ -33,21 +32,27 @@ interface Step {
 	argv: (issues: ReadonlyArray<string>) => ReadonlyArray<string>
 }
 
-// The steps in the order a run closes on: any ledger line the run's own commit did not carry
-// (joshuafolkken/kit#2763) is committed first so the recurrence count is on main — on most runs the
-// flush answers `clean` — the citations are read for the completion report, and the release scope is
-// decided last.
-const FLUSH_STEP: Step = {
-	header: run_tail.OBSERVATIONS_HEADER,
-	argv: () => ['observations:flush'],
-}
+// The steps in the order a run closes on: the checkout returns to the default branch, any ledger line
+// the run's own commit did not carry (joshuafolkken/kit#2763) is committed so the recurrence count is on
+// main — on most runs the flush answers `clean` — the citations are read for the completion report, and
+// the release scope is decided last.
+//
+// **The return comes first because the flush refuses anywhere else** (joshuafolkken/kit#2979). A run
+// closes right after its merge, still on the feature branch it shipped from, and `josh ship` reaches
+// this report with nothing in between — so the flush stopped a merged run as failed. `main:sync` is the
+// step a person used to type after the fact; it fast-forwards the local default branch before the
+// checkout, so a ledger line appended after the merge is carried along rather than refused.
+const LEDGER_STEPS: ReadonlyArray<Step> = [
+	{ header: run_tail.SYNC_HEADER, argv: () => ['main:sync'] },
+	{ header: run_tail.OBSERVATIONS_HEADER, argv: () => ['observations:flush'] },
+]
 const REPORT_STEPS: ReadonlyArray<Step> = [
 	{ header: run_tail.CITATIONS_HEADER, argv: (issues) => ['issue:cite', ...issues] },
 	{ header: run_tail.RELEASE_HEADER, argv: () => ['release:scope'] },
 ]
 
 function steps_for(is_lane_child: boolean): ReadonlyArray<Step> {
-	return is_lane_child ? REPORT_STEPS : [FLUSH_STEP, ...REPORT_STEPS]
+	return is_lane_child ? REPORT_STEPS : [...LEDGER_STEPS, ...REPORT_STEPS]
 }
 
 // Numbers only — a target `issue:cite` reads as an issue, so a stray flag is refused rather than
@@ -75,6 +80,7 @@ async function close_run(issues: ReadonlyArray<string>): Promise<ReadonlyArray<T
 
 	const is_lane_child = lane_child_marker.is_child_of(process.cwd())
 
+	// eslint-disable-next-line no-await-in-loop -- the tail steps run in their declared order
 	for (const step of steps_for(is_lane_child)) sections.push(await run_step(step, issues))
 
 	return sections
@@ -100,7 +106,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_tail_cli = { SUCCESS_EXIT_CODE, USAGE, close_run, main, parse_issues, run }
+const run_tail_cli = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/run/run-tail.ts

@@ -9,6 +9,7 @@
 // each step's output under a header and answers the exit code from the collected codes, so a test pins
 // the composite without a ledger ever being committed or a release ever read.
 
+const SYNC_HEADER = '=== sync ==='
 const OBSERVATIONS_HEADER = '=== observations ==='
 const CITATIONS_HEADER = '=== citations ==='
 const RELEASE_HEADER = '=== release ==='
@@ -52,6 +53,7 @@ const run_tail = {
 	CITATIONS_HEADER,
 	OBSERVATIONS_HEADER,
 	RELEASE_HEADER,
+	SYNC_HEADER,
 	exit_code,
 	format_report,
 	section_body,

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

@@ -1,5 +1,5 @@
 import { git_spawn } from '#scripts/git/git-spawn'
-import { git_stash } from '#scripts/git/git-stash'
+import { git_stash } from '#scripts/git/stash/git-stash'
 import { lane_close } from '#scripts/lane/lane-close'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { run_hold } from './run-hold'
@@ -96,6 +96,7 @@ async function tidy_lanes(is_merged: IsMerged): Promise<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)
 
 		if (outcome !== undefined) outcomes.push(outcome)

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

@@ -1,6 +1,6 @@
-import { git_stash, type StashEntry } from '#scripts/git/git-stash'
-import { stash_orphans } from '#scripts/git/stash-orphans'
-import { stash_sweep_lock } from '#scripts/git/stash-sweep-lock'
+import { git_stash, type StashEntry } from '#scripts/git/stash/git-stash'
+import { stash_orphans } from '#scripts/git/stash/stash-orphans'
+import { stash_sweep_lock } from '#scripts/git/stash/stash-sweep-lock'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
@@ -18,20 +18,19 @@ 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.
+// 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,
 	ledger_paths: ReadonlyArray<string>,
 ): Promise<Array<string>> {
-	const added: Array<string> = []
-
-	for (const ledger_path of ledger_paths) {
-		const lines = await git_stash.added_lines(hash, ledger_path)
-
-		added.push(...lines)
-	}
+	const added = await bounded_pool.bounded_map(
+		ledger_paths,
+		READ_CONCURRENCY,
+		async (ledger_path) => await git_stash.added_lines(hash, ledger_path),
+	)
 
-	return added
+	return added.flat()
 }
 
 // How many ledger lines went into the running work tree's ledger before the drop. The duplicate check
@@ -107,6 +106,7 @@ async function tidy_entries(
 	const outcomes: Array<Outcome> = []
 
 	for (const entry of entries) {
+		// eslint-disable-next-line no-await-in-loop -- drops shift the stash stack and append to the same ledger
 		const outcome = await tidy_entry(entry, merged)
 
 		if (outcome !== undefined) outcomes.push(outcome)

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

@@ -3,8 +3,8 @@ import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
-import { telegram_notify } from '#scripts/git/telegram-notify'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { run_carry, type CarryRead } from './run-carry'
 import { run_event_stream } from './run-event-stream'
 import { run_headless } from './run-headless'
@@ -226,7 +226,7 @@ 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.md` is a contract
+// (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.
 function exit_code_of(reason: WakeStopReason): number {
@@ -410,7 +410,6 @@ const run_wake_cli = {
 	NONE_VERDICT,
 	RUNNING_VERDICT,
 	STALE_VERDICT,
-	STARTED_VERDICT,
 	STOPPED_VERDICT,
 	SUPERVISING_VERDICT,
 	UNKNOWN_VERDICT,

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

@@ -199,10 +199,12 @@ async function run_loop(target: string, ports: LoopPorts, interval_ms: number):
 	let wake = run_wake.read_own_wake(target)
 
 	while (wake !== undefined) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		const stop = await run_pass(target, wake, ports)
 
 		if (stop !== undefined) return stop
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await ports.sleep(next_interval(run_wake.read_own_wake(target), interval_ms, ports.now()))
 		wake = run_wake.read_own_wake(target)
 	}
@@ -213,10 +215,8 @@ async function run_loop(target: string, ports: LoopPorts, interval_ms: number):
 const run_wake_loop = {
 	FAILED_REASON,
 	MAX_BACKOFF_FACTOR,
-	STOPPED_REASON,
 	next_interval,
 	run_loop,
-	step,
 }
 
 export type { DriveResult, LoopPorts, LoopStop }

package/scripts/run/run-wake.ts

@@ -1,6 +1,7 @@
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { backlog_budget } from '#scripts/backlog/backlog-budget'
 import { process_identity } from '#scripts/josh/process-identity'
+import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { z } from 'zod'
 import type { CarryRead } from './run-carry'
@@ -209,11 +210,9 @@ const STOP_REASONS: Record<'none' | 'expired' | 'unreadable', WakeStopReason> =
 	unreadable: 'unreadable',
 }
 
-const run_wake_schema = z.object({
+const run_wake_schema = process_owner_schema.extend({
 	invocation: z.string(),
 	started_at: z.string(),
-	pid: z.number(),
-	process_start: z.string().optional(),
 	woke: z.number(),
 	woke_at: z.string().optional(),
 	// **Every optional field of `RunWake` has to be listed here.** `z.object` strips what it does not
@@ -583,7 +582,6 @@ const run_wake = {
 	IDLE_CEILING_MS,
 	MAX_WAKE_ATTEMPTS,
 	WAKE_GRACE_MS,
-	WAKE_PREFIX,
 	claim,
 	count_claim,
 	count_wake,

package/scripts/run/run-watcher-guard-cli.ts

@@ -30,8 +30,4 @@ async function main(): Promise<void> {
 	process.exitCode = await run()
 }
 
-const run_watcher_guard_cli = { run }
-
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
-export { run_watcher_guard_cli }

package/scripts/run/run-watcher-guard.ts

@@ -1,4 +1,5 @@
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { run_headless } from './run-headless'
 import { run_progress_clock } from './run-progress-clock'
 
 // A watcher that stopped while children are still in-flight leaves the parent blind to completions
@@ -29,19 +30,21 @@ type GuardResult = { kind: 'ok' } | { kind: 'stale'; note: string }
 
 const OK_RESULT: GuardResult = { kind: 'ok' }
 
-// The lanes a parent is still waiting on. A stranded lane has no child working in it, so it is not
-// in-flight — the one definition both this guard and the headless stop rule read (`run-headless.ts`).
-async function has_lanes_in_flight(): Promise<boolean> {
-	const all_lanes = await lane_registry.list_lanes()
+// **Only the run that opened the lanes owes them a watcher** (joshuafolkken/kit#2965). The lane listing
+// is machine-wide, so a session with no run of its own — an investigation, a `fullrun` beside a batch —
+// used to be refused for another run's lanes. The session that drives the live `backlogrun` carry
+// record is the one that dispatched them; every other session passes.
+async function owes_watcher(): Promise<boolean> {
+	if (!(await run_headless.is_backlog_parent())) return false
 
-	return all_lanes.some((lane) => !lane.is_stranded)
+	return await lane_registry.has_lanes_in_flight()
 }
 
 // `life_target` is the path returned by `run_progress_read.stamp_target()` or
 // `run_progress_clock.life_target_of(git_directory)`. Passed in rather than resolved here so the
 // caller can use whichever resolution fits its sync/async context.
 async function check(life_target: string): Promise<GuardResult> {
-	if (!(await has_lanes_in_flight())) return OK_RESULT
+	if (!(await owes_watcher())) return OK_RESULT
 
 	if (run_progress_clock.is_life_fresh(life_target, STALE_THRESHOLD_MS)) return OK_RESULT
 
@@ -52,7 +55,6 @@ const run_watcher_guard = {
 	STALE_NOTE,
 	STALE_THRESHOLD_MS,
 	check,
-	has_lanes_in_flight,
 }
 
 export type { GuardResult }

package/scripts/run/run-watcher-hook.ts

@@ -81,6 +81,6 @@ async function watcher_hook_reason(
 	return await stale_reason(transcript, now_ms)
 }
 
-const run_watcher_hook = { SWITCH_ENV_KEY, STAMP_PREFIX, transcript_of, watcher_hook_reason }
+const run_watcher_hook = { transcript_of, watcher_hook_reason }
 
 export { run_watcher_hook }

package/scripts/safe-chain/ci-installer-pin.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { composite_actions } from '#scripts/ci/composite-actions'
 import { execaSync } from 'execa'
 
 // Where the workflows that install safe-chain on the runner live. Each carries the release and the
@@ -25,13 +26,18 @@ function installer_url(version: string): string {
 	return `https://github.com/AikidoSec/safe-chain/releases/download/${version}/install-safe-chain.sh`
 }
 
+// The local composite actions follow the workflows: kit's own pin lives in
+// `.github/actions/setup-pnpm`, which every kit workflow installs through (joshuafolkken/kit#2982).
 function list_workflows(): Array<string> {
-	return WORKFLOW_DIRECTORIES.filter((directory) => existsSync(directory)).flatMap((directory) =>
-		readdirSync(directory)
-			.filter((file_name) => WORKFLOW_FILE_RE.test(file_name))
-			.toSorted((left, right) => left.localeCompare(right))
-			.map((file_name) => `${directory}/${file_name}`),
+	const workflows = WORKFLOW_DIRECTORIES.filter((directory) => existsSync(directory)).flatMap(
+		(directory) =>
+			readdirSync(directory)
+				.filter((file_name) => WORKFLOW_FILE_RE.test(file_name))
+				.toSorted((left, right) => left.localeCompare(right))
+				.map((file_name) => `${directory}/${file_name}`),
 	)
+
+	return [...workflows, ...composite_actions.list()]
 }
 
 function extract_pinned_version(content: string): string | undefined {

package/scripts/safe-chain/project-config.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { file_reader } from '#scripts/lib/read-file'
+import { yaml_document } from '#scripts/lib/yaml-document'
 import { release_age } from '#scripts/version/release-age'
-import { yaml_document } from '#scripts/yaml/yaml-document'
 import { dump } from 'js-yaml'
 import { z } from 'zod'
 

package/scripts/security/security-audit-provision-logic.ts

@@ -191,7 +191,6 @@ function format_below_floor(version: string): string {
 }
 
 const security_audit_provision_logic = {
-	FORCED_DOWNLOAD_TIMEOUT_MS,
 	RETRY_INTERVAL_MS,
 	SESSION_DOWNLOAD_TIMEOUT_MS,
 	SCANNER_VERSION,

package/scripts/security/security-audit-provision.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
+import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { security_audit } from './security-audit'
 import { security_audit_logic } from './security-audit-logic'
 import { security_audit_provision_logic, type ScannerAsset } from './security-audit-provision-logic'
@@ -33,7 +34,7 @@ interface ProvisionOutcome {
 // catch-all would drop the release URL out of the message that names where the fetch went.
 async function download(url: string, timeout_ms: number): Promise<DownloadOutcome> {
 	try {
-		const response = await fetch(url, { signal: AbortSignal.timeout(timeout_ms) })
+		const response = await timed_fetch(url, {}, timeout_ms)
 		if (!response.ok) return { reason: `HTTP ${String(response.status)}` }
 
 		return { content: Buffer.from(await response.arrayBuffer()), reason: '' }
@@ -180,6 +181,6 @@ async function main(): Promise<void> {
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
 
-const security_audit_provision = { attempt, download, install, main, provision, report }
+const security_audit_provision = { attempt, provision, report }
 
 export { security_audit_provision }