@joshuafolkken/kit 1.1178.0 → 1.1240.0

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
@@ -236,9 +236,12 @@ function event_action(event: string, issue_number: string, is_lane_child: boolea
 }
 
 // A run that has planned but emitted nothing else is still at its pre-implementation position, so a
-// `plan` reads the same as an empty stream.
+// `plan` reads the same as an empty stream. A resume from an implementation cut is back at the same
+// position (joshuafolkken/kit#3375): read as the `cut` it follows, it pointed at the spent resume again.
+const IMPLEMENTATION_POSITIONS: ReadonlySet<string> = new Set([KIND.PLAN, KIND.RESUME])
+
 function is_pre_implementation(last_event: string | undefined): boolean {
-	return last_event === undefined || last_event === run_event_stream.EVENT_KIND.PLAN
+	return last_event === undefined || IMPLEMENTATION_POSITIONS.has(last_event)
 }
 
 // **No cut at the setup→implementation boundary** (joshuafolkken/kit#2489). A lane child's context is

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

package/scripts/run/{run-ship-cli.ts → ship/run-ship-cli.ts}

@@ -2,8 +2,8 @@
 import { fileURLToPath } from 'node:url'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { cli_flags } from '#scripts/lib/cli-flags'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
+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_ship, type ShipSection } from './run-ship'
 import { run_ship_detach } from './run-ship-detach'
 import { run_ship_next } from './run-ship-next'

package/scripts/run/{run-ship-detach.ts → ship/run-ship-detach.ts}

@@ -3,10 +3,10 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
+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 { z } from 'zod'
-import { detached_launch, type LaunchArgv } from './detached-launch'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
 
 // `josh ship --detach` — hand the post-implementation region to a supervisor that outlives the agent
 // (joshuafolkken/kit#2428). A lane child used to take the pre-gate cut and relaunch a fresh agent session

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

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { stripVTControlCharacters } from 'node:util'
+import { buffered_process } from '#scripts/lib/buffered-process'
+import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
+
+// A lock file that no longer matches its inputs, asked before the gate (joshuafolkken/kit#3307).
+//
+// The pre-push hook's setup runs `pnpm install`, which rewrites a lock that has drifted — a
+// `.pnpmfile.mjs` edit moves `pnpmfileChecksum` — and so leaves the working tree dirty under the push.
+// The hook then refuses the gate's record and re-runs the whole unit suite, long enough under a crowded
+// machine to time the push out. The frozen, lock-only install answers the same question without
+// writing anything or touching `node_modules`, in about a third of a second.
+//
+// A project with no lock file has nothing to drift, so nothing is asked there.
+//
+// **pnpm's own error line rides along**: the install refuses for reasons other than drift too — an
+// engine mismatch, a timeout on a crowded machine — and there "run `pnpm install`" fixes nothing, so
+// the reader needs pnpm's error code to tell the two apart. The line naming an `ERR_PNPM_` code wins
+// over the first line, which in a workspace is pnpm's "Scope: all N workspace projects" banner.
+
+const LOCK_FILE = 'pnpm-lock.yaml'
+const PNPM_ERROR_CODE = 'ERR_PNPM_'
+const LOCK_CHECK_ARGUMENTS = ['install', '--frozen-lockfile', '--lockfile-only', '--ignore-scripts']
+const LOCK_DRIFT = `${LOCK_FILE} does not match its inputs (\`pnpm install --frozen-lockfile\` refuses it), so the pre-push hook's install would rewrite it under the push: run \`pnpm install\` and commit ${LOCK_FILE}.`
+
+function drift_problem(output: string): string {
+	const lines = stripVTControlCharacters(output)
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => line !== '')
+	const reason = lines.find((line) => line.includes(PNPM_ERROR_CODE)) ?? lines[0]
+
+	return reason === undefined ? LOCK_DRIFT : `${LOCK_DRIFT} pnpm said: ${reason}`
+}
+
+async function lock_problems(directory: string = process.cwd()): Promise<Array<string>> {
+	if (!existsSync(path.join(directory, LOCK_FILE))) return []
+
+	const result = await buffered_process.run_buffered_process(LOCK_CHECK_ARGUMENTS, {
+		cwd: directory,
+		timeout_ms: INSTALL_TIMEOUT_MS,
+	})
+
+	return buffered_process.is_process_failed(result) ? [drift_problem(result.output)] : []
+}
+
+const run_ship_lock = { LOCK_CHECK_ARGUMENTS, LOCK_DRIFT, lock_problems }
+
+export { run_ship_lock }

package/scripts/run/{run-ship-preflight.ts → ship/run-ship-preflight.ts}

@@ -7,6 +7,7 @@ import { git_preflight } from '#scripts/git/git-preflight'
 import type { JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
 import { live_evidence } from '#scripts/review/live-evidence'
+import { run_ship_lock } from './run-ship-lock'
 import { run_ship_scoped } from './run-ship-scoped'
 
 // `josh ship`'s first stage (joshuafolkken/kit#2946). A detached ship used to meet the pull request's
@@ -71,13 +72,16 @@ async function caught(problems: Promise<Array<string>>): Promise<Array<string>>
 	}
 }
 
+// The lock file is asked here too (joshuafolkken/kit#3307), so a drift stops the ship before the gate
+// rather than being rewritten by the pre-push hook's install under the push.
 async function asked_problems(request: PreflightRequest): Promise<Array<string>> {
-	const [preflight, evidence] = await Promise.all([
+	const [preflight, evidence, lock] = await Promise.all([
 		caught(git_preflight.problems_of({ cli_input: request.title, will_open_pr: true })),
 		caught(evidence_problems(request.body_path)),
+		caught(run_ship_lock.lock_problems()),
 	])
 
-	return [...preflight, ...evidence]
+	return [...preflight, ...evidence, ...lock]
 }
 
 async function stage(request: PreflightRequest): Promise<JoshResult> {

package/scripts/run/{run-ship-probe.ts → ship/run-ship-probe.ts}

@@ -1,8 +1,8 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { error_text } from '#scripts/lib/error-message'
-import { run_hold } from './run-hold'
-import { run_preflight } from './run-preflight'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_preflight } from '#scripts/run/run-preflight'
 import { run_ship_stage, type ShipState } from './run-ship-stage'
 
 // The read side of a resumed `josh ship` (joshuafolkken/kit#2426): the repository's actual state, asked

package/scripts/run/{run-ship-return.ts → ship/run-ship-return.ts}

@@ -3,10 +3,11 @@ import { lane_child_invocation } from '#scripts/lane/lane-child-invocation'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_relaunch } from '#scripts/lane/lane-relaunch'
-import { run_event_stream } from './run-event-stream'
-import { run_event_stream_emit } from './run-event-stream-emit'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import type { ShipResume } from './run-ship-next'
 import { run_ship_stage, type Stage } from './run-ship-stage'
+import { run_ship_stop_text } from './run-ship-stop-text'
 
 // How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
 // ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
@@ -29,7 +30,7 @@ const OPENAI_PROVIDER = 'openai'
 type ReturnOutcome = 'relaunched' | 'recorded'
 
 function stop_text(issue: string, stage: Stage, resume: ShipResume): string {
-	return `#${issue} ${run_ship_stage.stop_reason(stage, resume.conflicts)} failed — pnpm josh ship --log ${issue}`
+	return run_ship_stop_text.format(issue, run_ship_stage.stop_reason(stage, resume.conflicts))
 }
 
 function can_relaunch(lane: LaneInfo | undefined): lane is LaneInfo {