@joshuafolkken/kit 1.1010.0 → 1.1050.0

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

@@ -0,0 +1,144 @@
+import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
+import { cost_cli, type CostVerdict } from '#scripts/cost-runtime/cost-cli'
+import { cost_format } from '#scripts/cost-runtime/cost-format'
+import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
+import { hook_decision } from '#scripts/josh/hook-decision'
+import { implementation_cut_verdict } from '#scripts/rules/implementation-cut-verdict'
+import { run_carry, type RunCarry } from './run-carry'
+import { run_headless } from './run-headless'
+import { run_watcher_hook } from './run-watcher-hook'
+
+// The `backlogrun` parent's hand-off, delivered at the call it binds on (joshuafolkken/kit#2947).
+//
+// **The parent's hand-off was asked only at a merge, and the context grew between merges.** The
+// orchestrator never implements, yet on 2026-10-02 parent 259fb6d5 sent 111 of its 170 requests past
+// the shared threshold, peaking at 207,081 tokens: `pnpm josh cost --cut` is read after each child's
+// merge (`backlogrun-progress.md` → "The hand-off"), and a long wait or a lane-failure investigation
+// between two merges is exactly where it went unread. This is the lesson `implementation-cut.ts` records
+// for a lane child, one session up — a check carried as a step is taken late, a `PreToolUse` refusal is
+// taken at the next call.
+//
+// **The same statistic and the same threshold, never a second measurement.** The verdict is
+// `cost_cli.session_verdict` — what `pnpm josh cost --cut` prints — read through the implementation cut's
+// short reuse window so a burst of calls is priced once.
+//
+// **It is async and composed after the synchronous guards, like the watcher guard.** Telling the parent
+// apart reads the carry record through `run_headless.driving_carry`, which is asynchronous; reusing it is
+// what keeps a second, synchronous spelling of the parent test from existing.
+
+const SWITCH_ENV_KEY = 'JOSH_PARENT_CUT_GUARD'
+const STAMP_PREFIX = 'josh-parent-cut-guard-'
+
+// **One refusal, then a quiet window long enough to finish the hand-off in.** The hand-off is several
+// calls — `lane:list`, `lane:output`, `run:carry --cut`, `run:wake`, the progress comment — and a guard
+// refusing each of them would wedge the very procedure it asks for. A parent that could not cut (a lane
+// nobody can poll) is asked again once the window has passed, which is the "next opportunity" the merge
+// seam used to be.
+const QUIET_WINDOW_MS = 600_000
+
+// What the decision has to know about the world, passed in so it is testable without a carry record or
+// a session transcript on disk.
+interface ParentCutState {
+	carry: () => Promise<RunCarry | undefined>
+	verdict: () => CostVerdict
+}
+
+function current_state(): ParentCutState {
+	return {
+		carry: async (): Promise<RunCarry | undefined> => await run_headless.driving_carry(),
+		verdict: (): CostVerdict =>
+			implementation_cut_verdict.reused_verdict(() => cost_cli.session_verdict()),
+	}
+}
+
+const THRESHOLD_TEXT = `${cost_format.format_tokens(CONTEXT_CUT_THRESHOLD)}-token`
+
+const PARENT_CUT_REASON =
+	'⛔ backlogrun parent hand-off: this session drives a `backlogrun` (it owns the live carry record) and ' +
+	`its recent-context cost has crossed the shared ${THRESHOLD_TEXT} threshold between merges, so every ` +
+	'later request re-reads the accumulated context (joshuafolkken/kit#2947). Take the hand-off now rather ' +
+	'than at the next merge: follow `.claude/skills/workflow-commands/backlogrun-progress.md` → "The ' +
+	'hand-off" from its `over` branch — open no new lane and take no new child, read `pnpm josh lane:list`, ' +
+	'make sure every lane in flight records an output path, then run `pnpm josh run:carry --cut --owner ' +
+	'"$PPID"` and, unless it answers `capped`, `pnpm josh run:wake`, post the progress comment and end the ' +
+	'turn. A lane nobody can poll means the cut does not happen; carry on and this asks again later. ' +
+	'Reissue this call when the hand-off is done or cannot be taken — the guard stays quiet for a while ' +
+	'after it refuses, so the hand-off calls themselves are not refused.'
+
+// Neither an uncapped parent's own record nor a measured `over` is optional: a capped record has no cut
+// left to take (`run:carry --cut` answers `capped`), and an unmeasurable session is left alone here —
+// refusing every call of a session that cannot be priced would wedge it, while the merge-seam check
+// still takes `over`'s branch for it.
+async function is_due(state: ParentCutState): Promise<boolean> {
+	const carry = await state.carry()
+
+	if (carry === undefined || run_carry.is_at_cut_cap(carry)) return false
+
+	return state.verdict() === cost_verdict.OVER_VERDICT
+}
+
+function is_quiet(target: string, now_ms: number): boolean {
+	const last_ms = hook_decision.create_refusal_stamp(STAMP_PREFIX).last_ms(target)
+
+	return last_ms !== hook_decision.NEVER_MS && now_ms - last_ms < QUIET_WINDOW_MS
+}
+
+// The quiet window is read before the carry record and the transcript price, so a refused parent's
+// following calls cost one small file read each.
+async function refusal_for(
+	transcript: string,
+	now_ms: number,
+	state: ParentCutState,
+): Promise<string | undefined> {
+	const stamp = hook_decision.create_refusal_stamp(STAMP_PREFIX)
+	const target = stamp.path(transcript)
+
+	if (is_quiet(target, now_ms) || !(await is_due(state))) return undefined
+
+	return stamp.record(target, now_ms) ? PARENT_CUT_REASON : undefined
+}
+
+// A delegated unit's call names the *parent's* transcript and runs under the parent's process, so the
+// carry record reads as owned here; only `agent_id` tells it apart (`hook-decision.ts`). Refusing it
+// would hand the unit a hand-off it cannot take and spend the parent's quiet window on it.
+function is_unit_call(raw_payload: string): boolean {
+	try {
+		return (hook_decision.parse_hook_payload(raw_payload)?.agent_id ?? '') !== ''
+	} catch {
+		return false
+	}
+}
+
+function is_exempt(raw_payload: string): boolean {
+	return !hook_decision.is_switch_enabled(SWITCH_ENV_KEY) || is_unit_call(raw_payload)
+}
+
+/**
+ * The deny reason for a call a `backlogrun` parent makes past the shared threshold, or `undefined` when
+ * the call proceeds — a lane child, a delegated unit, a person's session, a handed-off or capped
+ * record, an `under` or unmeasurable verdict, or a call inside the quiet window after a refusal.
+ */
+async function parent_cut_reason(
+	raw_payload: string,
+	now_ms: number = Date.now(),
+	state: ParentCutState = current_state(),
+): Promise<string | undefined> {
+	if (is_exempt(raw_payload)) return undefined
+
+	const transcript = run_watcher_hook.transcript_of(raw_payload)
+
+	if (transcript === undefined) return undefined
+
+	return await refusal_for(transcript, now_ms, state)
+}
+
+const run_parent_cut_hook = {
+	PARENT_CUT_REASON,
+	QUIET_WINDOW_MS,
+	STAMP_PREFIX,
+	SWITCH_ENV_KEY,
+	parent_cut_reason,
+}
+
+export type { ParentCutState }
+export { run_parent_cut_hook }

package/scripts/run/run-progress-args.ts

@@ -1,4 +1,4 @@
-import { parseArgs } from 'node:util'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_progress_config } from './run-progress-config'
 
 // The argument half of `josh run:progress`, kept apart from the watcher so the CLI stays inside the file
@@ -37,11 +37,7 @@ interface ParsedValues {
 }
 
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
-	try {
-		return parseArgs({ args: [...argv], options: OPTIONS }).values
-	} catch {
-		return undefined
-	}
+	return cli_flags.parse_or_undefined({ args: [...argv], options: OPTIONS })?.values
 }
 
 // A hand-typed `--interval` outranks the environment, the environment outranks the interval the

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

@@ -5,6 +5,7 @@ import { backlog_arrival, type ArrivalProbe } from '#scripts/backlog/backlog-arr
 import { backlog_ready } from '#scripts/backlog/backlog-ready'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { error_text } from '#scripts/lib/error-message'
 import { run_event_stream_emit } from './run-event-stream-emit'
 import { run_progress, type ProgressState } from './run-progress'
 import { run_progress_args, type ParsedValues } from './run-progress-args'
@@ -229,7 +230,7 @@ function decline(loop: WatchLoop, now_ms: number, notice: string): WatchLoop {
 // under load — the very load this command exists to report — would otherwise take the reporting down
 // silently for the rest of an unattended run, with the parent not waiting on it and nothing saying why.
 function to_notice(error: unknown): string {
-	return `${FAILED_TICK_PREFIX} ${error instanceof Error ? error.message : String(error)}`
+	return `${FAILED_TICK_PREFIX} ${error_text.message_of(error)}`
 }
 
 async function attempt(

package/scripts/run/run-progress-read.ts

@@ -78,7 +78,7 @@ async function to_child(issue: OpenIssueData): Promise<ChildObservation> {
 	const number = String(issue.number)
 	const child = await run_preflight.read_child_state(number)
 
-	return { issue: number, labels: to_labels(issue), pr_state: child.pr_state }
+	return { issue: number, title: issue.title, labels: to_labels(issue), pr_state: child.pr_state }
 }
 
 async function read_children(repo: string): Promise<ReadonlyArray<ChildObservation> | undefined> {
@@ -171,6 +171,7 @@ async function read_observations(request: ObservationRequest): Promise<Observati
 	if (children.length === 0 && !(await has_run_started(lanes))) return IDLE_READ
 
 	const observations: Observations = {
+		repo: request.repo,
 		children,
 		lanes,
 		load_average: loadavg()[FIRST_LOAD_AVERAGE] ?? 0,

package/scripts/run/run-progress.ts

@@ -1,3 +1,5 @@
+import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
+
 // `josh run:progress` — the one line an unattended run prints when it has gone quiet, and the clock
 // that decides when that is (joshuafolkken/kit#1520).
 //
@@ -56,6 +58,9 @@ const DEFAULT_INTERVAL_MS = DEFAULT_INTERVAL_MINUTES * MS_PER_MINUTE
 // a second spelling of it — `none` / `open` / `merged` / `closed`.
 interface ChildObservation {
 	issue: string
+	// Kept from the `in-progress` listing the child was read from, so the line cites it in full
+	// (joshuafolkken/kit#2943) without a read per child.
+	title: string
 	labels: ReadonlyArray<string>
 	pr_state: string
 }
@@ -66,6 +71,8 @@ interface LaneObservation {
 }
 
 interface Observations {
+	// `owner/repo`, the repository the listing was read from — what every printed issue links into.
+	repo: string
 	children: ReadonlyArray<ChildObservation>
 	lanes: ReadonlyArray<LaneObservation>
 	load_average: number
@@ -195,26 +202,32 @@ function next_state(
 	return { key, unchanged_since_ms: now_ms }
 }
 
-function format_child(child: ChildObservation): string {
+// The issue leads as a citation rather than a bare `#N` (joshuafolkken/kit#2943): the parent relays these
+// lines verbatim, and a bare number copied into a reply is what the Stop guard sends back.
+function format_child(child: ChildObservation, cite: IssueCiter): string {
 	const labels = child.labels.length > 0 ? child.labels.join(',') : '(no labels)'
 
-	return `#${child.issue} ${labels} PR:${child.pr_state}`
+	return `${cite(child.issue)} ${labels} PR:${child.pr_state}`
 }
 
 // An empty set is the pre-label stage, said as such rather than left as a blank slot between the
 // separators (joshuafolkken/kit#1900). After that change a `read_observations` result carries no
 // children exactly when a run has started and none has reached `in-progress` yet, so this is the one
 // place the two cases are told apart on the line.
-function format_children(children: ReadonlyArray<ChildObservation>): string {
+function format_children(children: ReadonlyArray<ChildObservation>, repo: string): string {
 	if (children.length === 0) return NO_CHILD_YET
+	const cite = issue_cite.citer(repo, new Map(children.map((child) => [child.issue, child.title])))
 
-	return children.map((child) => format_child(child)).join(' · ')
+	return children.map((child) => format_child(child, cite)).join(' · ')
 }
 
-function format_lanes(lanes: ReadonlyArray<LaneObservation>): string {
+// A lane is linked without its title: a lane in flight is a child the line above already cited in full,
+// so repeating the title here would only lengthen the line.
+function format_lanes(lanes: ReadonlyArray<LaneObservation>, repo: string): string {
 	if (lanes.length === 0) return NO_LANES
+	const cite = issue_cite.citer(repo, new Map())
 
-	return lanes.map((lane) => `${lane.issue}:${lane.state}`).join(' ')
+	return lanes.map((lane) => `${cite(lane.issue)}:${lane.state}`).join(' ')
 }
 
 // Absent is said, never filled in. A run started without a transcript path prints `unread` here, which
@@ -303,8 +316,8 @@ function format_line(observations: Observations, timing: LineTiming): string {
 		observed_at: format_observed_at(timing.now_ms),
 		quiet: format_minutes(timing.now_ms - timing.quiet_since_ms),
 		unchanged: format_minutes(timing.now_ms - timing.unchanged_since_ms),
-		children: format_children(observations.children),
-		lanes: format_lanes(observations.lanes),
+		children: format_children(observations.children, observations.repo),
+		lanes: format_lanes(observations.lanes, observations.repo),
 		load: observations.load_average.toFixed(1),
 		record: format_record(observations.record_age_ms),
 		next: format_next_report(timing.now_ms, timing.interval_ms),

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

@@ -1,7 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
-import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
@@ -9,8 +8,8 @@ import { run_ship, type ShipSection } from './run-ship'
 import { run_ship_detach } from './run-ship-detach'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_return } from './run-ship-return'
-import { run_ship_review_steps } from './run-ship-review-steps'
 import { run_ship_stage, type Phase, type ShipState, type Stage } from './run-ship-stage'
+import { run_ship_steps, type ShipArguments, type Step } from './run-ship-steps'
 
 // `josh ship "<title> #<N>"` — one call for the fixed commit-to-report region a run ships a change on
 // (joshuafolkken/kit#2398). The loop used to spend a round trip each on `gate`, `git -y`, `followup`
@@ -67,7 +66,6 @@ const USAGE =
 const NO_LOG_NOTE = 'no detached ship supervisor log for this issue'
 const LANE_CHILD_DETACH_NOTE =
 	'lane child: shipping through the detached supervisor (--detach implied), so the end of this turn cannot kill it'
-const should_forward_stderr = true
 
 type NotifyValues = Partial<Record<(typeof NOTIFY_OPTIONS)[number], string>>
 
@@ -84,24 +82,8 @@ const OPTIONS = {
 	cite: { type: 'string', multiple: true },
 } as const
 
-interface ShipArguments {
-	title: string
-	number: string
-	notify: ReadonlyArray<string>
-	body: ReadonlyArray<string>
-	cites: ReadonlyArray<string>
-	is_review: boolean
-	is_detach: boolean
-}
-
 type ShipCommand = { kind: 'ship'; args: ShipArguments } | { kind: 'log'; number: string }
 
-interface Step {
-	stage: Stage
-	header: string
-	run: (args: ShipArguments, state: ShipState) => Promise<JoshResult>
-}
-
 // What a resumed ship knows before its first stage: the record's path (absent outside a repository),
 // the stages it says completed, and the repository's actual state (`run-ship-stage.ts` decides from it).
 interface ShipContext {
@@ -124,58 +106,7 @@ function body_arguments(path: string | undefined): ReadonlyArray<string> {
 	return path === undefined ? [] : [`--${BODY_FILE_OPTION}`, path]
 }
 
-const { STAGE, PHASE } = run_ship_stage
-
-// The four steps in the order a change ships: the gate before the commit, the commit/push/PR before
-// the merge, the merge before the report bookkeeping. The commit step carries the `--skip-*` flags a
-// resumed ship needs, so an existing commit or push is never made twice.
-async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
-	return await josh_command.josh_run(argv, should_forward_stderr)
-}
-
-const COMMIT_STEPS: ReadonlyArray<Step> = [
-	{ stage: STAGE.GATE, header: run_ship.GATE_HEADER, run: async () => await josh(['gate']) },
-	{
-		stage: STAGE.COMMIT,
-		header: run_ship.COMMIT_HEADER,
-		run: async (args, state) =>
-			await josh(['git', '-y', ...run_ship_stage.commit_flags(state), ...args.body, args.title]),
-	},
-]
-
-const MERGE_STEPS: ReadonlyArray<Step> = [
-	{
-		stage: STAGE.FOLLOWUP,
-		header: run_ship.FOLLOWUP_HEADER,
-		run: async (args) => await josh(['followup', args.title, ...args.notify]),
-	},
-	{
-		stage: STAGE.REPORT,
-		header: run_ship.REPORT_HEADER,
-		run: async (args) => await josh(['run:tail', args.number, ...args.cites]),
-	},
-]
-
-// `--review` (joshuafolkken/kit#2427) puts the supervised round-1 review in front of the gate: it
-// launches the gate itself, so the gate stage that follows reuses that tree's green record. It also
-// puts the round-2 pass between the commit and the followup (joshuafolkken/kit#2489), so the PR opens
-// between the rounds and round 2 runs beside CI — a no-op when round 1 left no fix delta.
-const REVIEW_STEP: Step = {
-	stage: STAGE.REVIEW,
-	header: run_ship.REVIEW_HEADER,
-	run: async (args) => await run_ship_review_steps.review_stage(args.number),
-}
-const ROUND_TWO_STEP: Step = {
-	stage: STAGE.ROUND_TWO,
-	header: run_ship.ROUND_TWO_HEADER,
-	run: async (args) => await run_ship_review_steps.round_two_stage(args.number),
-}
-
-function steps(args: ShipArguments): ReadonlyArray<Step> {
-	if (!args.is_review) return [...COMMIT_STEPS, ...MERGE_STEPS]
-
-	return [REVIEW_STEP, ...COMMIT_STEPS, ROUND_TWO_STEP, ...MERGE_STEPS]
-}
+const { PHASE } = run_ship_stage
 
 function issue_number(title: string): string | undefined {
 	return TRAILING_ISSUE_PATTERN.exec(title)?.[NUMBER_GROUP]
@@ -211,6 +142,7 @@ function ship_args(
 		number,
 		notify: notify_arguments(values),
 		body: body_arguments(values[BODY_FILE_OPTION]),
+		body_path: values[BODY_FILE_OPTION],
 		cites,
 		is_review: values.review === true,
 		is_detach: values.detach === true,
@@ -328,14 +260,14 @@ async function stopped(
 	return sections
 }
 
-// Run the four in order, stopping at the first that failed: a red gate never reaches the commit, so
+// Run the stages in order, stopping at the first that failed: a red gate never reaches the commit, so
 // the returned sections end at the failure the report names. A ship that reached the end clears its
-// record, so the next ship of the same issue starts from the gate.
+// record, so the next ship of the same issue starts from the preflight.
 async function ship(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const context = await open_context(args)
 	const sections: Array<ShipSection> = []
 
-	for (const step of steps(args)) {
+	for (const step of run_ship_steps.steps(args)) {
 		const section = await run_stage(step, args, context)
 
 		sections.push(section)

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

@@ -0,0 +1,87 @@
+import { readFile } from 'node:fs/promises'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_branch } from '#scripts/git/git-branch'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+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_scoped } from './run-ship-scoped'
+
+// `josh ship`'s first stage (joshuafolkken/kit#2946). A detached ship used to meet the pull request's
+// preconditions only at the commit stage — `git -y`'s preflight — or at the merge — `followup`'s
+// live-evidence refusal — each after the review and the gate had already run, so every such stop
+// relaunched a session to repeat them. **Every precondition decidable before the review is asked here,
+// and all of them are reported at once.** No check is new: the classification, issue and branch answers
+// are `git_preflight.problems_of`, and the evidence answer is `live_evidence.verdict_for` over the same
+// changed paths and the body this ship will deliver — `--body-file` when given, else the open PR's.
+//
+// The scoped pair runs last, met rather than stopped on (`run-ship-scoped.ts`), so the review and the
+// gate start on a tree both checks are green on.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const EVIDENCE_PROBLEM = `This change touches runtime code, but the PR body has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and pass the body with --body-file <path>.`
+
+interface PreflightRequest {
+	title: string
+	body_path: string | undefined
+}
+
+async function body_text(body_path: string | undefined): Promise<string | undefined> {
+	if (body_path !== undefined) return await readFile(body_path, 'utf8')
+
+	return await git_gh_command.pr_get_body(await git_branch.current())
+}
+
+async function evidence_problems(body_path: string | undefined): Promise<Array<string>> {
+	const [paths, body] = await Promise.all([
+		changed_paths.read_changed_paths(false),
+		body_text(body_path),
+	])
+
+	return live_evidence.verdict_for(paths, body) === 'required' ? [EVIDENCE_PROBLEM] : []
+}
+
+function refusal(problems: ReadonlyArray<string>): JoshResult {
+	const lines = problems.map((problem) => `  - ${problem}`)
+	const head = `${String(problems.length)} pull-request precondition(s) unmet before the review and the gate:`
+
+	return { code: FAILURE_EXIT_CODE, out: [head, ...lines].join('\n') }
+}
+
+// The reads here run in the ship's own process, where the commit stage's ran in a `git -y` child: a
+// throw — a `--body-file` path that does not exist, a git read that failed — would escape `ship()`
+// past the stop a supervised ship hands back on, so it is reported as one more unmet precondition.
+// Each side is caught on its own, so one side's failed read never hides what the other side found.
+async function caught(problems: Promise<Array<string>>): Promise<Array<string>> {
+	try {
+		return await problems
+	} catch (error) {
+		return [error_text.message_of(error)]
+	}
+}
+
+async function asked_problems(request: PreflightRequest): Promise<Array<string>> {
+	const [preflight, evidence] = await Promise.all([
+		caught(git_preflight.problems_of({ cli_input: request.title, will_open_pr: true })),
+		caught(evidence_problems(request.body_path)),
+	])
+
+	return [...preflight, ...evidence]
+}
+
+async function stage(request: PreflightRequest): Promise<JoshResult> {
+	const problems = await asked_problems(request)
+
+	if (problems.length > 0) return refusal(problems)
+
+	const scoped = await run_ship_scoped.scoped_pair()
+
+	return scoped.code === SUCCESS_EXIT_CODE ? { code: SUCCESS_EXIT_CODE, out: 'ready' } : scoped
+}
+
+const run_ship_preflight = { EVIDENCE_PROBLEM, stage }
+
+export type { PreflightRequest }
+export { run_ship_preflight }

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

@@ -1,7 +1,5 @@
 import { agent_argv, type AgentArgv } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
-import { gate_tree } from '#scripts/gate/gate-tree'
-import { scoped_green } from '#scripts/gate/scoped-green'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { stamp_file } from '#scripts/josh/stamp-file'
@@ -9,6 +7,7 @@ import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { openai_review_broker } from '#scripts/lane/openai-review-broker'
 import { detached_launch } from './detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
+import { run_ship_scoped, type Phase } from './run-ship-scoped'
 
 // The side effects of `josh ship --review` (joshuafolkken/kit#2427): the round-1 review the chain used
 // to open, launch, join, attest and record across five agent turns, run by the supervisor beside the
@@ -47,7 +46,10 @@ const FIXED_JOIN_NOTE =
 	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate stage re-runs it.'
 const ROUND_TWO_SKIPPED_NOTE = 'round 2 not due — nothing left to verify; shipping on.'
 
-type Phase = () => Promise<JoshResult>
+// The scoped pair's precondition, met by the supervisor itself rather than stopped on
+// (joshuafolkken/kit#2500), single-sourced with the preflight and gate stages (joshuafolkken/kit#2946).
+const { run_phases, scoped_pair } = run_ship_scoped
+
 type PromptOf = (brief_path: string, findings_path: string) => string
 
 function failure(out: string): JoshResult {
@@ -153,17 +155,6 @@ async function record_and_route(
 	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out)
 }
 
-async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
-	let last: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
-
-	for (const phase of phases) {
-		last = await phase()
-		if (last.code !== SUCCESS_EXIT_CODE) return last
-	}
-
-	return last
-}
-
 // A brief-minting command, then a reviewer handed what it printed.
 function reviewed(
 	open: ReadonlyArray<string>,
@@ -185,18 +176,6 @@ function reviewed(
 	]
 }
 
-// The scoped pair's precondition, met by the supervisor itself rather than stopped on
-// (joshuafolkken/kit#2500): only the checks with no green record for this tree run — the same
-// question `review:brief` and the local gate refuse on — so a fresh record costs nothing and a stale
-// or absent one costs a scoped run instead of a stop and a relaunched session. A check that genuinely
-// fails still stops the ship, its output forwarded to the ship log.
-async function scoped_pair(): Promise<JoshResult> {
-	const tree = await gate_tree.read_gate_tree()
-	const scripts = scoped_green.missing_scripts(tree.files, tree.base)
-
-	return await run_phases(scripts.map((script) => async () => await josh([script])))
-}
-
 // Fixes made in place are counted only once the scoped pair is green on the fixed tree. The reviewer is
 // asked to leave it green; this is the check that it did, and a fix it could not get green is routed as
 // the finding it still is — recorded, then stopped before the gate and the commit take it in.

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

@@ -154,6 +154,14 @@ function round_one_outcome(verdict: ScoredVerdict): RoundOutcome {
 	return { is_passing: true, note: verdict.kind === VERDICT.FIXED ? FIXED_NOTE : CLEAN_NOTE }
 }
 
+// Whether a findings file records a clean round 1 (joshuafolkken/kit#2945). A resumed round 1 narrows to
+// the delta only past a review that found nothing to fix. A blocking one has a finding in a file the
+// delta may not touch. A fixed one approved its own edits, not the briefed tree the delta is measured
+// from, so a file reverted to that tree would drop out of the delta with its finding back in it.
+function is_clean_round_one(text: string | undefined): boolean {
+	return read_verdict(text).kind === VERDICT.CLEAN
+}
+
 // Round 2 is final and reads only, so it passes clean or Low-only alone — a fix it made would itself be
 // unreviewed.
 function round_two_outcome(verdict: ScoredVerdict): RoundOutcome {
@@ -166,6 +174,7 @@ const run_ship_review = {
 	FIXED_PREFIX,
 	UNVERIFIED_OUTCOME,
 	VERDICT,
+	is_clean_round_one,
 	read_verdict,
 	reviewer_prompt,
 	round_one_outcome,

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

@@ -0,0 +1,44 @@
+import { gate_tree } from '#scripts/gate/gate-tree'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+
+// The scoped pair `josh ship` meets itself rather than stops on (joshuafolkken/kit#2500), shared by
+// every stage that needs a green record for this tree (joshuafolkken/kit#2946): the preflight stage at
+// the start, the review rounds, and the gate stage — a reviewer may have edited the tree after round
+// 1's pair ran, and `josh gate` refuses a tree with no green record.
+
+const SUCCESS_EXIT_CODE = 0
+const should_forward_stderr = true
+
+type Phase = () => Promise<JoshResult>
+
+async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
+	let last: JoshResult = { code: SUCCESS_EXIT_CODE, out: '' }
+
+	for (const phase of phases) {
+		last = await phase()
+		if (last.code !== SUCCESS_EXIT_CODE) return last
+	}
+
+	return last
+}
+
+// Only the checks with no green record for this tree run — the same question `review:brief` and the
+// local gate refuse on — so a fresh record costs nothing and a stale or absent one costs a scoped run
+// instead of a stop and a relaunched session. A check that genuinely fails still stops the ship, its
+// output forwarded to the ship log.
+async function scoped_pair(): Promise<JoshResult> {
+	const tree = await gate_tree.read_gate_tree()
+	const scripts = scoped_green.missing_scripts(tree.files, tree.base)
+
+	return await run_phases(
+		scripts.map(
+			(script) => async () => await josh_command.josh_run([script], should_forward_stderr),
+		),
+	)
+}
+
+const run_ship_scoped = { run_phases, scoped_pair }
+
+export type { Phase }
+export { run_ship_scoped }

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

@@ -17,6 +17,7 @@ import { z } from 'zod'
 // re-run on an unchanged tree a reuse rather than a second execution. No quality gate is folded away.
 
 const STAGE = {
+	PREFLIGHT: 'preflight',
 	REVIEW: 'review',
 	GATE: 'gate',
 	COMMIT: 'commit',
@@ -78,7 +79,7 @@ function mark_done(target: string, stage: Stage): void {
 	stamp_file.replace_stamp(target, { done: [...done] })
 }
 
-// Removed once the report stage completes, so a later ship of the same issue starts from the gate.
+// Removed once the report stage completes, so a later ship of the same issue starts from the preflight.
 function clear(target: string): void {
 	stamp_file.remove_stamp(target)
 }
@@ -90,6 +91,9 @@ function is_shipped(state: ShipState): boolean {
 }
 
 const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => boolean> = {
+	// The preflight (joshuafolkken/kit#2946) asks what the commit stage would refuse on, so a commit is
+	// its output as it is the gate's; a resumed commit stage still asks `git -y`'s own preflight.
+	[STAGE.PREFLIGHT]: (_done, state) => state.is_merged || state.is_committed,
 	// The `--review` round (joshuafolkken/kit#2427) precedes the commit, so a commit is its output as it
 	// is the gate's. A record alone is not honored: before a commit the tree may have been edited since
 	// the recorded round, and only a commit pins the tree that round read.