@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/run/{run-progress-config.ts → progress/run-progress-config.ts}

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
+import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { z } from 'zod'
 import { run_progress } from './run-progress'
 
@@ -28,10 +29,6 @@ import { run_progress } from './run-progress'
 
 const PACKAGE_FILE = 'package.json'
 
-// Deep enough to cross a workspace package and its root, and bounded so a path that never reaches a
-// root — a broken mount, a mocked `dirname` — cannot spin.
-const MAX_DEPTH = 10
-
 // Unknown keys are stripped rather than rejected: this reads a whole `package.json`, and every other
 // field in it is none of this module's business. A present-but-unusable interval fails the parse and
 // falls through, which is the same answer an unusable environment variable already gets.
@@ -39,18 +36,6 @@ const package_schema = z.object({
 	josh: z.object({ progress_interval_minutes: z.number().positive() }).optional(),
 })
 
-function ancestors_of(start: string): ReadonlyArray<string> {
-	const directories: Array<string> = []
-	let current = path.resolve(start)
-
-	while (directories.length < MAX_DEPTH && !directories.includes(current)) {
-		directories.push(current)
-		current = path.dirname(current)
-	}
-
-	return directories
-}
-
 function read_declared_minutes(directory: string): number | undefined {
 	try {
 		const raw = readFileSync(path.join(directory, PACKAGE_FILE), 'utf8')
@@ -63,7 +48,7 @@ function read_declared_minutes(directory: string): number | undefined {
 }
 
 function read_package_minutes(start: string): number | undefined {
-	for (const directory of ancestors_of(start)) {
+	for (const directory of ancestor_directories.list(start)) {
 		const minutes = read_declared_minutes(directory)
 
 		if (minutes !== undefined) return minutes

package/scripts/run/{run-progress-read.ts → progress/run-progress-read.ts}

@@ -1,13 +1,13 @@
 import { loadavg } from 'node:os'
 import { epic_busy } from '#scripts/epic/epic-busy'
 import { git_command } from '#scripts/git/git-command'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { lane_registry } from '#scripts/lane/lane-registry'
 import { lane_report } from '#scripts/lane/lane-report'
-import { run_carry, type CarryRead } from './run-carry'
-import { run_hold, type HoldRead } from './run-hold'
-import { run_liveness } from './run-liveness'
-import { run_preflight } from './run-preflight'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
+import { run_hold, type HoldRead } from '#scripts/run/hold/run-hold'
+import { run_liveness } from '#scripts/run/run-liveness'
+import { run_preflight } from '#scripts/run/run-preflight'
 import type { ChildObservation, LaneObservation, Observations } from './run-progress'
 import { run_progress_clock } from './run-progress-clock'
 

package/scripts/run/{run-progress.ts → progress/run-progress.ts}

@@ -257,7 +257,7 @@ interface LineTiming {
  * this is that same move for one value.
  *
  * **It is a schedule rather than an observation, and the two conditions on it are said in prose**
- * (`docs/josh-commands-automation.md` → `josh run:progress`): it holds only while the silence continues, and a
+ * (`docs/josh-commands-run.md` → `josh run:progress`): it holds only while the silence continues, and a
  * real report arriving first restarts the clock through `--mark` and supersedes it. The line printing
  * it is itself a report, so the clock starts at this observation.
  */

package/scripts/run/{run-review-steps.ts → review/run-review-steps.ts}

@@ -8,7 +8,7 @@ import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
-import { detached_launch, type LaunchArgv, type LaunchResult } from './detached-launch'
+import { detached_launch, type LaunchArgv, type LaunchResult } from '#scripts/run/detached-launch'
 import { run_review, type GateState, type ReviewTiming, type TimingStart } from './run-review'
 
 // The side effects `josh run:review` performs, kept out of `run-review.ts` the way `run-merge-steps.ts`
@@ -114,8 +114,7 @@ function write_timing_start(start: TimingStart, target: string = PROJECT_ROOT):
 function to_timing(value: unknown): TimingStart | undefined {
 	if (typeof value !== 'object' || value === null) return undefined
 
-	const record = value as Record<string, unknown>
-	const { gate_started_at, review_started_at } = record
+	const { gate_started_at, review_started_at } = value as Record<string, unknown>
 
 	if (typeof gate_started_at !== 'string' || typeof review_started_at !== 'string') return undefined
 

package/scripts/run/run-ending.ts

@@ -4,8 +4,8 @@ import { api_outage } from '#scripts/agent/api-outage'
 import type { ClaudeResultEvent } from '#scripts/agent/claude-result-event'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { issue_state } from '#scripts/issue/issue-state'
-import { run_cut } from './run-cut'
-import { run_hold } from './run-hold'
+import { run_cut } from '#scripts/run/cut/run-cut'
+import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_issue_number } from './run-issue-number'
 import { run_liveness } from './run-liveness'
 

package/scripts/run/run-halfrun-resume.ts

@@ -1,4 +1,9 @@
-import { run_hold, type HoldRead, type RunHold, type StopMarkFields } from './run-hold'
+import {
+	run_hold,
+	type HoldRead,
+	type RunHold,
+	type StopMarkFields,
+} from '#scripts/run/hold/run-hold'
 
 // joshuafolkken/kit#2796: a `halfrun` stops before its commit and **keeps** its hold, because the
 // uncommitted, hand-verified work is exactly what a second run would trample. The person then types

package/scripts/run/run-headless.ts

@@ -1,7 +1,7 @@
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_reap } from '#scripts/lane/lane-reap'
 import { lane_registry } from '#scripts/lane/lane-registry'
-import { run_carry, type CarryRead, type RunCarry } from './run-carry'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
 
 // The headless `backlogrun` parent (joshuafolkken/kit#2437). `run:wake` starts a cut's successor as
 // `claude -p`, and there a turn that ends is the process that ends: its background `lane:await` and

package/scripts/run/run-invocation.ts

@@ -1,4 +1,5 @@
 import { backlog_budget_cli } from '#scripts/backlog/backlog-budget-cli'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_issue_number } from './run-issue-number'
 
 // The grammar of an invocation that can be carried across a session cut, and the only place it is
@@ -39,17 +40,34 @@ const KNOWN_FLAGS: ReadonlyArray<string> = ['--max', '--idle']
 // pool" (joshuafolkken/kit#1984). It is carried across a cut like any other part of the invocation, so
 // a resumed session that reads it back does not silently start draining the backlog the person excluded.
 const ONLY_FLAG = '--only'
+// The read itself is `cli_flags`'s (joshuafolkken/kit#3261): strict, so an unknown flag, a flag with
+// no value, `--only=<x>` and a value that is itself a flag are all refused before this file looks.
+const OPTIONS = {
+	max: { type: 'string' },
+	idle: { type: 'string' },
+	only: { type: 'boolean' },
+} as const
 const ISSUE_PREFIX = '#'
+const FLAG_PREFIX = '-'
 const TOKEN_SEPARATOR = ' '
 const FIRST_TOKEN = 0
 const FIRST_ARGUMENT_INDEX = 1
-const VALUE_OFFSET = 1
-const FLAG_PAIR_LENGTH = 2
-// `--only` advances the scan by one token, having no value where a `--max` / `--idle` pair advances two.
-const ONLY_STEP = 1
 const EMPTY_LENGTH = 0
 const NOT_FOUND = -1
 
+// One token of `parseArgs`'s `tokens` answer, as far as this file reads it: a positional's text, or an
+// option's name and the value it was given (`--max 5` and `--max=5` alike).
+interface ArgumentToken {
+	kind: string
+	name?: string
+	value?: string | undefined
+}
+
+interface Invocation {
+	issues: ReadonlyArray<number>
+	flags: ReadonlyArray<string>
+}
+
 // A space is the only separator that can survive `detached-launch.ts`'s `is_safe_value`, which has
 // already refused every control character — so the split needs no pattern, and this file is left with
 // no regular expression of its own for a backtracking analysis to find. The one pattern it does use
@@ -60,57 +78,33 @@ function tokens_of(invocation: string): ReadonlyArray<string> {
 
 // **The integer check is `backlog:budget`'s own, imported rather than restated.** It is the command
 // this invocation is going to be handed to, so a second copy of the rule here would be free to drift
-// from the one that actually reads the number.
-function flag_token(token: string, raw: string | undefined): string | undefined {
-	const flag = KNOWN_FLAGS.find((known) => known === token)
-	const value = backlog_budget_cli.to_count(raw)
+// from the one that actually reads the number. `--only` carries no value and renders to its own
+// constant for the same taint reason every other token does — the constant severs the record's string
+// from the rebuilt one.
+function render_option(token: ArgumentToken): string | undefined {
+	if (token.name === cli_flags.option_name(ONLY_FLAG)) return ONLY_FLAG
+	const flag = KNOWN_FLAGS.find((known) => cli_flags.option_name(known) === token.name)
+	const value = backlog_budget_cli.to_count(token.value)
 
 	if (flag === undefined || value === undefined) return undefined
 
 	return `${flag} ${String(value)}`
 }
 
-// One rendered flag and how far it advanced the scan: two tokens for a valued flag, one for `--only`.
-// The advance is returned rather than assumed, so `flag_tokens` handles a valueless flag mixed in with
-// the pairs without knowing which kind it read.
-interface FlagRead {
-	part: string
-	advance: number
-}
-
-// **`--only` is read before the valued flags**, because it is the one token that carries no value: read
-// as a valued flag it would swallow whatever follows it as its argument. It renders to its own constant
-// for the same taint reason every other token does — the constant severs the record's string from the
-// rebuilt one.
-function read_flag(tokens: ReadonlyArray<string>, index: number): FlagRead | undefined {
-	const token = tokens[index] ?? ''
-
-	if (token === ONLY_FLAG) return { part: ONLY_FLAG, advance: ONLY_STEP }
-
-	const part = flag_token(token, tokens[index + VALUE_OFFSET])
-
-	return part === undefined ? undefined : { part, advance: FLAG_PAIR_LENGTH }
-}
-
 // **An unknown flag is refused, never dropped.** Dropping one would wake a session running to a budget
 // the person did not declare the first time `backlogrun` grows a flag this list has not caught up with
 // — which is the failure that is hardest to notice, because the session runs and looks fine. A stray
-// `#N` after the flags lands here too, as a token that matches no known flag, and is refused: the
-// named list is the invocation's leading block, never interleaved with the budget.
-function flag_tokens(
-	tokens: ReadonlyArray<string>,
-	start: number,
-): ReadonlyArray<string> | undefined {
+// `#N` after the flags lands here too, as a token that is no option, and is refused: the named list is
+// the invocation's leading block, never interleaved with the budget. So is a `--` terminator.
+function rendered_options(tokens: ReadonlyArray<ArgumentToken>): ReadonlyArray<string> | undefined {
 	const rendered: Array<string> = []
-	let index = start
 
-	while (index < tokens.length) {
-		const read = read_flag(tokens, index)
+	for (const token of tokens) {
+		const part = render_option(token)
 
-		if (read === undefined) return undefined
+		if (part === undefined) return undefined
 
-		rendered.push(read.part)
-		index += read.advance
+		rendered.push(part)
 	}
 
 	return rendered
@@ -135,25 +129,15 @@ function issue_of(token: string): number | undefined {
 	return Number.isSafeInteger(issue) ? issue : undefined
 }
 
-// The named issues are the leading block of `#N` tokens, in the order they were typed. The scan stops
-// at the first token that is not an issue reference — that is where the budget flags begin — and a
-// `#`-prefixed token that does not validate refuses the whole invocation rather than being read as the
-// start of the flags. An empty block is a valid answer here (a bare `backlogrun` or a budget-only one);
-// `issue_numbers` is where "no named issues" becomes `undefined`.
-// The contiguous leading block of `#`-prefixed tokens — everything up to the first token that is not
-// an issue reference, which is where the budget flags begin.
-function take_leading_prefixed(args: ReadonlyArray<string>): ReadonlyArray<string> {
-	const stop = args.findIndex((token) => !token.startsWith(ISSUE_PREFIX))
-
-	return args.slice(FIRST_TOKEN, stop === NOT_FOUND ? args.length : stop)
-}
-
-function leading_issues(tokens: ReadonlyArray<string>): ReadonlyArray<number> | undefined {
+// The named issues are the leading block of positionals, in the order they were typed, and each must be
+// a `#N` that validates — anything else refuses the whole invocation rather than being dropped. An
+// empty block is a valid answer here (a bare `backlogrun` or a budget-only one); `issue_numbers` is
+// where "no named issues" becomes `undefined`.
+function issues_of(tokens: ReadonlyArray<ArgumentToken>): ReadonlyArray<number> | undefined {
 	const issues: Array<number> = []
-	const prefixed = take_leading_prefixed(tokens.slice(FIRST_ARGUMENT_INDEX))
 
-	for (const token of prefixed) {
-		const issue = issue_of(token)
+	for (const token of tokens) {
+		const issue = issue_of(token.value ?? '')
 
 		if (issue === undefined) return undefined
 
@@ -163,6 +147,35 @@ function leading_issues(tokens: ReadonlyArray<string>): ReadonlyArray<number> |
 	return issues
 }
 
+// The arguments after the command word, as `parseArgs` tokens, or `undefined` for another command or
+// an argument list the strict read refuses.
+function argument_tokens(invocation: string): ReadonlyArray<ArgumentToken> | undefined {
+	const tokens = tokens_of(invocation)
+
+	if (tokens[FIRST_TOKEN] !== BACKLOG_COMMAND) return undefined
+
+	return cli_flags.parse_or_undefined({
+		args: tokens.slice(FIRST_ARGUMENT_INDEX),
+		options: OPTIONS,
+		allowPositionals: true,
+		tokens: true,
+	})?.tokens
+}
+
+// The named list is everything before the first option, and the budget flags everything from it on.
+function parse(invocation: string): Invocation | undefined {
+	const tokens = argument_tokens(invocation)
+	if (tokens === undefined) return undefined
+	const stop = tokens.findIndex((token) => token.kind !== 'positional')
+	const split_at = stop === NOT_FOUND ? tokens.length : stop
+	const issues = issues_of(tokens.slice(FIRST_TOKEN, split_at))
+	const flags = rendered_options(tokens.slice(split_at))
+
+	if (issues === undefined || flags === undefined) return undefined
+
+	return { issues, flags }
+}
+
 function issue_token(issue: number): string {
 	return `${ISSUE_PREFIX}${String(issue)}`
 }
@@ -174,26 +187,17 @@ function joined(command: string, rendered: ReadonlyArray<string>): string {
 // The named list rebuilds first and the budget flags after it, so the canonical text is
 // `backlogrun #1 #2 --max 5` whatever spacing the record held. Both halves are composed from this
 // file's own constants and validated integers, so no token of the record survives into the result.
-function rebuilt_backlog(tokens: ReadonlyArray<string>): string | undefined {
-	const issues = leading_issues(tokens)
-
-	if (issues === undefined) return undefined
-
-	const flags = flag_tokens(tokens, FIRST_ARGUMENT_INDEX + issues.length)
-
-	if (flags === undefined) return undefined
-
-	return joined(BACKLOG_COMMAND, [...issues.map((issue) => issue_token(issue)), ...flags])
-}
-
 // The command word is compared against this file's own constant and the **constant** is what the
 // rebuilt text is composed from, so no token of the record survives into the result.
 function rebuild(invocation: string): string | undefined {
-	const tokens = tokens_of(invocation)
+	const parsed = parse(invocation)
 
-	if (tokens[FIRST_TOKEN] !== BACKLOG_COMMAND) return undefined
+	if (parsed === undefined) return undefined
 
-	return rebuilt_backlog(tokens)
+	return joined(BACKLOG_COMMAND, [
+		...parsed.issues.map((issue) => issue_token(issue)),
+		...parsed.flags,
+	])
 }
 
 // The issues a `backlogrun` invocation named, in the order it named them. An invocation with no named
@@ -201,12 +205,13 @@ function rebuild(invocation: string): string | undefined {
 // "this invocation named no issues" and "this run has no issues left" are different facts, and a
 // caller that could not tell them apart would report a finished sequential run as one that never had a
 // list. A malformed leading `#N` answers `undefined` too, because there is then no list to trust.
+// Only the leading block is read, so a flag this grammar does not carry — `backlog:plan`'s `--exclude`
+// — after it does not hide the named issues.
 function issue_numbers(invocation: string): ReadonlyArray<number> | undefined {
 	const tokens = tokens_of(invocation)
-
-	if (tokens[FIRST_TOKEN] !== BACKLOG_COMMAND) return undefined
-
-	const issues = leading_issues(tokens)
+	const stop = tokens.findIndex((token) => token.startsWith(FLAG_PREFIX))
+	const leading = stop === NOT_FOUND ? tokens : tokens.slice(FIRST_TOKEN, stop)
+	const issues = parse(leading.join(TOKEN_SEPARATOR))?.issues
 
 	if (issues === undefined || issues.length === EMPTY_LENGTH) return undefined
 
@@ -214,15 +219,11 @@ function issue_numbers(invocation: string): ReadonlyArray<number> | undefined {
 }
 
 // Whether the invocation carries `--only`, so a resumed session runs the named list and stops rather
-// than draining the pool. It reads the token from the same grammar `rebuild` composes from, so the two
+// than draining the pool. It reads the flag from the same parse `rebuild` composes from, so the two
 // cannot disagree on what `--only` looks like. A non-`backlogrun` invocation carries none, which is
 // `false`.
 function has_only(invocation: string): boolean {
-	const tokens = tokens_of(invocation)
-
-	if (tokens[FIRST_TOKEN] !== BACKLOG_COMMAND) return false
-
-	return tokens.slice(FIRST_ARGUMENT_INDEX).includes(ONLY_FLAG)
+	return parse(invocation)?.flags.includes(ONLY_FLAG) === true
 }
 
 // **Three entries, because three things call in.** The command word, the flag list and the token

package/scripts/run/run-liveness.ts

@@ -7,7 +7,7 @@ import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { ALREADY_DONE_LABEL, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
 import { issue_state } from '#scripts/issue/issue-state'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
-import { run_hold } from './run-hold'
+import { run_hold } from '#scripts/run/hold/run-hold'
 import { run_issue_number } from './run-issue-number'
 
 // `josh run:liveness <N>` — whether the delegated unit running child `<N>` is still working, or

package/scripts/run/run-parent-cut-hook.ts

@@ -5,7 +5,7 @@ import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { error_text } from '#scripts/lib/error-message'
 import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
-import { run_carry, type RunCarry } from './run-carry'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
 import { run_headless } from './run-headless'
 import { run_watcher_hook } from './run-watcher-hook'
 

package/scripts/run/run-preflight.ts

@@ -1,8 +1,8 @@
 import { git_gh_pr_read } from '#scripts/gh/git-gh-pr-read'
 import { git_command } from '#scripts/git/git-command'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { run_hold } from '#scripts/run/hold/run-hold'
 import { z } from 'zod'
-import { run_hold } from './run-hold'
 import { run_issue_number } from './run-issue-number'
 
 // The preflight check — what an interrupted run left in this working tree, and what the rule says to
@@ -230,11 +230,11 @@ async function read_tree_state(): Promise<TreeState> {
 // could not complete (joshuafolkken/kit#1048). That throw reaches the CLI as `unknown`; without it a
 // rate-limited or logged-out `gh` turns a **merged** pull request into `resume`, and the run commits
 // on top of work somebody already landed — the exact hazard `park` exists for.
-// **The second half of the same guard.** `pr_exists` refuses to read an unreadable lookup as an
-// absence, but `pr_view` still folds any failure of its own into `''` — and the two are separate
-// round trips, so a rate limit or a 5xx arriving between them would put a **merged** pull request
-// back through `NO_PR` and out as `resume`. An empty answer for a branch `pr_exists` has just
-// confirmed is therefore a failed read by construction, and it throws rather than answering.
+// **The second half of the same guard.** `pr_view` throws on a read it could not complete
+// (joshuafolkken/kit#3263), but the two are separate round trips, so a lookup that answers empty
+// between them would still put a **merged** pull request back through `NO_PR` and out as `resume`.
+// An empty answer for a branch `pr_exists` has just confirmed is therefore a failed read by
+// construction, and it throws rather than answering.
 async function read_pr_state(branch_name: string): Promise<PrState> {
 	if (!(await git_gh_pr_read.pr_exists(branch_name))) return NO_PR
 

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

@@ -5,10 +5,10 @@ import { issue_read_cli, type BlockRead } from '#scripts/issue/issue-read-cli'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { error_text } from '#scripts/lib/error-message'
+import { run_ship_preflight } from '#scripts/run/ship/run-ship-preflight'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_locate } from './run-prep-locate'
-import { run_ship_preflight } from './run-ship-preflight'
 
 // `josh run:prep <N>` — one call for the reads a `fullrun` makes before its first edit
 // (joshuafolkken/kit#1978): the issue body and comments (`issue:read`), the state, labels and

package/scripts/run/run-prrun-resume.ts

@@ -2,8 +2,8 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { PullMergeState } from '#scripts/gh/git-gh-pr-read'
 import { git_branch } from '#scripts/git/git-branch'
 import { git_command } from '#scripts/git/git-command'
+import { run_hold, type HoldRead } from '#scripts/run/hold/run-hold'
 import { run_halfrun_resume, type StopMark } from './run-halfrun-resume'
-import { run_hold, type HoldRead } from './run-hold'
 
 // joshuafolkken/kit#3023: a `prrun` stops at a green, mergeable pull request and **keeps** its hold, so
 // a person can look before anything merges. What comes next is one of three, and `run:entry` answers

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

@@ -2,10 +2,10 @@
 import { fileURLToPath } from 'node:url'
 import { git_followup_pending } from '#scripts/followup/git-followup-pending'
 import { release_scope_cli } from '#scripts/release/release-scope-cli'
-import { run_carry } from './run-carry'
-import { run_event_scope, type EventScope } from './run-event-scope'
-import { run_event_stream, type RunEvent } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { run_event_scope, type EventScope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_report } from './run-report'
 
 // `josh run:report` — the session-facing report, generated from the run's event stream rather than

package/scripts/run/run-report.ts

@@ -1,6 +1,6 @@
 import { release_scope_cli, type Decision } from '#scripts/release/release-scope-cli'
-import { run_event_scope, type EventScope } from './run-event-scope'
-import { run_event_stream, type RunEvent } from './run-event-stream'
+import { run_event_scope, type EventScope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
 
 // The session-facing report generated *from* the run's event stream, rather than composed by hand each
 // time (joshuafolkken/kit#2249). #2205 gave the run a typed, ordered stream of what happened — a plan, a

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

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url'
 import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
 import { issue_state_cli, type StateRead } from '#scripts/issue/issue-state-cli'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { run_carry, type CarryRead } from './run-carry'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
 import { run_status, type StatusParts } from './run-status'
 
 // `josh run:status <N>` — one call for the read-only status a run glances at (joshuafolkken/kit#2165):

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

@@ -6,9 +6,9 @@ import { hook_decision } from '#scripts/josh/hook-decision'
 import { find_package_directory } from '#scripts/josh/josh-logic'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_reap } from '#scripts/lane/lane-reap'
-import { run_carry, type CarryRead } from './run-carry'
-import { run_event_scope } from './run-event-scope'
-import { run_event_stream } from './run-event-stream'
+import { run_carry, type CarryRead } from '#scripts/run/carry/run-carry'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_headless } from './run-headless'
 import { run_prep, type PrepParts } from './run-prep'
 import { run_prep_cli } from './run-prep-cli'

package/scripts/run/run-step.ts

@@ -1,7 +1,7 @@
 import { git_stash } from '#scripts/git/stash/git-stash'
+import type { CarryRead } from '#scripts/run/carry/run-carry'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { latest_scope_cli } from '#scripts/version/latest-scope-cli'
-import type { CarryRead } from './run-carry'
-import { run_event_stream } from './run-event-stream'
 import { run_retrospective } from './run-retrospective'
 
 // `josh run:step <N>` — the run's next single action, computed from three mechanical inputs and nothing

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

@@ -1,5 +1,5 @@
 import { telegram_notify } from '#scripts/notify/telegram-notify'
-import type { CarryRead } from './run-carry'
+import type { CarryRead } from '#scripts/run/carry/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

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

@@ -1,14 +1,14 @@
 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'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_wake, type RunWake } from '#scripts/run/wake/run-wake'
 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

package/scripts/run/run-stranded.ts

@@ -1,6 +1,6 @@
 import { process_identity } from '#scripts/josh/process-identity'
-import { run_carry, type CarryRead, type RunCarry } from './run-carry'
-import type { RunWake } from './run-wake'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import type { RunWake } from '#scripts/run/wake/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

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { run_progress_read } from './run-progress-read'
+import { run_progress_read } from '#scripts/run/progress/run-progress-read'
 import { run_watcher_guard } from './run-watcher-guard'
 
 // `josh run:watcher:guard` — refuses when lane children are in-flight but the progress watcher has not

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

@@ -1,6 +1,6 @@
 import { lane_registry } from '#scripts/lane/lane-registry'
+import { run_progress_clock } from '#scripts/run/progress/run-progress-clock'
 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 run's event stream without a
 // heartbeat and the parent without the wake an arrival would deliver. This guard detects that state so
@@ -37,9 +37,11 @@ const OK_RESULT: GuardResult = { kind: 'ok' }
 // **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.
+// record is the one that dispatched them; every other session passes. A session `run:wake` woke owes
+// none either (joshuafolkken/kit#3245): the supervisor's driver watches the lanes, and the woken session
+// only acts on the branch it was handed and cuts.
 async function owes_watcher(): Promise<boolean> {
-	if (!(await run_headless.is_backlog_parent())) return false
+	if (run_headless.is_headless() || !(await run_headless.is_backlog_parent())) return false
 
 	return await lane_registry.has_lanes_in_flight()
 }

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

@@ -1,7 +1,7 @@
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { run_progress_read } from '#scripts/run/progress/run-progress-read'
 import { z } from 'zod'
-import { run_progress_read } from './run-progress-read'
 import { run_watcher_guard } from './run-watcher-guard'
 
 // The `PreToolUse` adapter that turns `run_watcher_guard`'s verdict into a deny reason, so the guard