@joshuafolkken/kit 1.1050.0 → 1.1128.0

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

@@ -28,7 +28,7 @@ import { run_progress_read, type ObservationRead } from './run-progress-read'
 // `backlogrun` parent — `ready #N · free lanes N` — which is itself something the parent acts on.
 //
 // **It cannot send a Telegram.** That is structural rather than a promise — nothing here imports
-// `scripts/git/telegram-notify`, which is the only egress there is. A heartbeat every twenty minutes on
+// `scripts/notify/telegram-notify`, which is the only egress there is. A heartbeat every twenty minutes on
 // a phone is notification fatigue, and it would cheapen the `confirmation` and `completion` messages
 // that do need to interrupt someone.
 
@@ -51,7 +51,7 @@ const TICK_SECONDS = 30
 const DECLINE_RETRY_SECONDS = 120
 // The clock a fresh loop starts with: nothing has declined yet, so nothing is being waited out.
 const NO_RETRY = 0
-const { DEFAULT_MAX_HOURS } = run_progress_args
+const { DEFAULT_WAIT_MAX_HOURS } = run_progress_args
 const ENVIRONMENT_KEY = 'JOSH_PROGRESS'
 const DISABLED_VALUE = '0'
 
@@ -74,7 +74,7 @@ const UNREADABLE_NOTICE =
 	'The `in-progress` listing could not be read, so nothing is reported. That is not "nothing is running" — check `gh auth status` and ask again.'
 const FAILED_TICK_PREFIX =
 	'A progress reading failed, so nothing is reported for it. The watcher is still running, and will read again after the cooldown:'
-const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_MAX_HOURS)} by default) ran out before the run had been quiet for a whole interval, so there is nothing to report. Starting another \`--wait\` resumes the same clock.`
+const WAIT_EXPIRED_NOTICE = `The watch bound (\`--hours\`, ${String(DEFAULT_WAIT_MAX_HOURS)} by default for \`--wait\`) ran out with no newly runnable work arriving. Every report it made is already on the run's event stream (\`pnpm josh run:event --watch\`), so there is nothing to relay. Starting another \`--wait\` resumes the same clock.`
 // The repository name is only ever printed, never written against, so the bounded lookup is the right
 // one: a `gh` call that hangs would otherwise block the synchronous read at startup and leave the
 // watcher neither running nor saying so.
@@ -104,6 +104,10 @@ interface WatchOptions {
 	output_paths: ReadonlyArray<string>
 	repo: string
 	tick_ms: number
+	// `--wait` alone: the line goes to the run's event stream and the ambient log, never to standard
+	// output, because a background command's output reaches the session only as a wake
+	// (joshuafolkken/kit#3102).
+	is_stream_only?: boolean
 }
 
 interface EmitContext {
@@ -202,7 +206,7 @@ async function emit(options: WatchOptions, context: EmitContext): Promise<EmitRe
 		unchanged_since_ms: state.unchanged_since_ms,
 	})
 
-	console.info(line)
+	if (options.is_stream_only !== true) console.info(line)
 
 	return { kind: 'observed', state, line }
 }
@@ -287,8 +291,8 @@ async function step(options: WatchOptions, target: string, loop: WatchLoop): Pro
 /**
  * The loop both reporting forms are, with one difference between them.
  *
- * `watch` runs until `--hours` expires; `--wait` stops at the first line it prints
- * (joshuafolkken/kit#1576). Everything else — where the clock is seeded from, the tick, the decline
+ * `watch` runs until `--hours` expires; `--wait` stops at the first arrival and keeps its lines off
+ * standard output (joshuafolkken/kit#3102). Everything else — where the clock is seeded from, the tick, the decline
  * cooldown `step` keeps — is one implementation on purpose: two copies would let a fix to the bound or
  * to the initial silence reach one form and not the other, and `--wait` is the form a run starts.
  */
@@ -301,17 +305,14 @@ function seed_loop(target: string, started_ms: number): WatchLoop {
 // Why the loop stopped, so `drive` prints the bound-expired notice only when the bound is what
 // expired — not when `josh followup` ended the watcher, which is a clean stop with nothing to report.
 // `arrived` is a `--wait` ended early by newly runnable work (joshuafolkken/kit#2503).
-type WatchExit = 'reported' | 'arrived' | 'ended' | 'bound'
+type WatchExit = 'arrived' | 'ended' | 'bound'
 
-// `wait` is present for `--wait` alone, which ends at the first line it prints or at the first arrival
-// its probe sees. `state` is set by the one branch of `step` that printed a line and by no other, so
-// this asks "was anything reported" without keeping a second copy of the loop's own bookkeeping.
-async function wait_exit(
-	loop: WatchLoop,
-	wait: ArrivalProbe | undefined,
-): Promise<WatchExit | undefined> {
+// `wait` is present for `--wait` alone, which ends at the first arrival its probe sees. **A report is
+// not an exit** (joshuafolkken/kit#3102): every exit wakes the session that started it, and a wake
+// spent relaying a line the event stream already carries is the most expensive turn a run takes, so
+// only what the parent has to act on ends the wait.
+async function wait_exit(wait: ArrivalProbe | undefined): Promise<WatchExit | undefined> {
 	if (wait === undefined) return undefined
-	if (loop.state !== undefined) return 'reported'
 
 	return (await wait.has_arrived(Date.now())) ? 'arrived' : undefined
 }
@@ -335,8 +336,8 @@ function final_exit(life: string): WatchExit {
 // The loop both reporting forms share, reading its own liveness record at the top of each pass — the
 // `run-wake-loop.ts` `run_loop` shape (joshuafolkken/kit#1727). A record gone means `josh followup`
 // removed it at the merge, so the watcher stops at once instead of waiting out its bound
-// (joshuafolkken/kit#1821); `--wait` also stops at the first line it prints, and otherwise the loop
-// runs until `--hours` expires.
+// (joshuafolkken/kit#1821); `--wait` also stops at the first arrival, and otherwise the loop runs
+// until `--hours` expires.
 async function run_ticks(
 	options: WatchOptions,
 	target: string,
@@ -347,11 +348,14 @@ async function run_ticks(
 	let loop = seed_loop(target, started_ms)
 
 	while (Date.now() - started_ms < options.max_ms && !run_progress_clock.is_life_ended(life)) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(options.tick_ms)
 		run_progress_clock.ping_life(life)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		loop = await step(options, target, loop)
 
-		const exit = await wait_exit(loop, wait)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
+		const exit = await wait_exit(wait)
 
 		if (exit !== undefined) return exit
 	}
@@ -394,14 +398,16 @@ async function once(options: WatchOptions): Promise<number> {
 }
 
 /**
- * One interval of silence, one line, and then exit — the form that reports where a long-running
- * command cannot (joshuafolkken/kit#1576).
+ * The form a run starts in the background: it reports on its own and wakes the caller only for work
+ * (joshuafolkken/kit#3102).
  *
- * **The exit is the whole point.** A harness that only delivers a background command's standard
- * output *when that command exits* — Claude Code is one — relays nothing at all from `watch`, which
- * by design never exits: `epicrun #1474` was measured at 2h36m without a single progress line while
- * children were in flight. This form waits the same clock out and then ends, so the line it printed
- * is delivered; the caller relays it and starts the next one.
+ * **A report is not a wake.** It once ended at its first line so a harness that delivers a background
+ * command's output only on exit would relay it (joshuafolkken/kit#1576) — which cost the orchestrating
+ * session one turn per heartbeat, re-reading a hundred thousand tokens of context to pass on a line it
+ * was forbidden to change. Every line already reaches the run's event stream as a `heartbeat` and the
+ * ambient log, which a person's `run:event --watch` pane reads with no model in between, so this form
+ * keeps its lines off standard output and exits only on an arrival, on `josh followup` ending its life
+ * record, or on its bound. The caller starts it once and restarts it only after one of those.
  *
  * **The clock is still this command's, not the caller's.** It is the watch loop itself, a tick at a
  * time, rather than a second reading of the same record — so a real report elsewhere pushes the next
@@ -416,10 +422,10 @@ async function once(options: WatchOptions): Promise<number> {
  * carried budget, no lane, and no `in-progress` child — so a genuinely idle repository keeps the loop
  * waiting instead of ending it; returning there would hand the caller an instant answer to restart,
  * and the documented restart makes that a poll rather than a heartbeat. Once a run has started the
- * loop reports and exits even before the first child carries `in-progress` (joshuafolkken/kit#1900).
+ * loop reports even before the first child carries `in-progress` (joshuafolkken/kit#1900).
  */
 async function wait_once(options: WatchOptions): Promise<number> {
-	return await drive(options, true)
+	return await drive({ ...options, is_stream_only: true }, true)
 }
 
 async function mark_now(): Promise<number> {
@@ -445,7 +451,7 @@ function to_options(values: ParsedValues): WatchOptions | undefined {
 
 	return {
 		interval_ms: run_progress_args.to_interval_ms(values.interval),
-		max_ms: run_progress_args.to_max_ms(values.hours),
+		max_ms: run_progress_args.to_max_ms(values.hours, values.wait === true),
 		output_paths: values.output ?? [],
 		repo,
 		tick_ms: TICK_SECONDS * run_progress.MS_PER_SECOND,
@@ -491,27 +497,20 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const run_progress_cli = {
-	DECLINE_RETRY_SECONDS,
-	DEFAULT_MAX_HOURS,
+	DEFAULT_WAIT_MAX_HOURS,
 	DISABLED_NOTICE,
 	FAILED_TICK_PREFIX,
 	FRESH_LOOP,
 	IDLE_NOTICE,
 	LANE_CHILD_NOTICE,
-	MARKED_NOTICE,
 	REPO_UNRESOLVED_NOTICE,
-	TICK_SECONDS,
 	UNREADABLE_NOTICE,
 	USAGE,
 	WAIT_EXPIRED_NOTICE,
-	main,
 	read_arguments: run_progress_args.read_arguments,
-	report_decline,
 	run,
 	step,
 	to_interval_ms: run_progress_args.to_interval_ms,
-	to_max_ms: run_progress_args.to_max_ms,
-	to_options,
 	wait_once,
 }
 

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

@@ -1,6 +1,6 @@
-import { git_utilities } from '#scripts/git/constants'
+import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
-import { execaSync } from 'execa'
+import { error_text } from '#scripts/lib/error-message'
 import { z } from 'zod'
 
 // The report clock `josh run:progress` keeps, in the one form both of its readers can use
@@ -16,9 +16,10 @@ import { z } from 'zod'
 //
 // **The key is the work tree's own git directory**, the way `run_hold` keys its record: two lanes of
 // one repository are two runs, and one lane's report must not silence the other's clock. The
-// synchronous twin asks `git rev-parse --absolute-git-dir`, which is the first of the two lines
-// `git_command.git_directories` reads and the one the asynchronous path already takes — so the two
-// spellings cannot name different files.
+// synchronous twin is `git_common_directory.own()`, which asks the same two lines
+// `git_command.git_directories` reads and takes the first — so the two spellings cannot name different
+// files. A git read that fails or times out answers `undefined`, which reads as "no clock here" and
+// lets the call through.
 
 const PROGRESS_PREFIX = 'josh-run-progress-'
 // The watcher's own liveness record, kept apart from the report clock above: that one says *when* the
@@ -55,14 +56,6 @@ const MS_PER_MINUTE = 60_000
 const LOG_STALE_MINUTES = 90
 const LOG_STALE_MS = LOG_STALE_MINUTES * MS_PER_MINUTE
 const BLOCK_SEPARATOR = '\n\n'
-// The lookup only ever decides whether a rule speaks, so a git call that hangs must not hold the hook
-// that is holding the user's call. A timeout answers `undefined`, which reads as "no clock here" and
-// lets the call through — the direction every other failure in this path already takes.
-const GIT_TIMEOUT_MS = 5000
-// The first of the two lines `git_command.git_directories` reads, asked on its own because that is the
-// one the record is keyed on. Asking git rather than assuming a directory named `.git` is what makes a
-// linked work tree, a bare repository and a `--separate-git-dir` clone all answer correctly.
-const GIT_DIRECTORY_ARGUMENTS: ReadonlyArray<string> = ['rev-parse', '--absolute-git-dir']
 
 // `line` is the last heartbeat the watcher printed, kept verbatim beside the clock so a reader that
 // cannot see the watcher's transcript — a person checking a woken headless `backlogrun` through
@@ -240,7 +233,9 @@ function is_life_fresh(target: string, threshold_ms: number): boolean {
 		const pinged_ms = parse_pinged_at(raw)
 
 		return pinged_ms !== undefined && Date.now() - pinged_ms < threshold_ms
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('run_progress_clock.is_life_fresh', error)
+
 		return false
 	}
 }
@@ -259,25 +254,8 @@ function end_life(target: string): void {
 	stamp_file.remove_stamp(target)
 }
 
-// execa runs the binary directly with an argument array and no `shell` option, so CLI args cannot
-// break out of a shell sandbox; the git command and args are internally controlled, never untrusted
-// input. tssecurity:S8705 is a false positive here.
-function git_directory_sync(): string | undefined {
-	const git_binary = git_utilities.get_git_command_for_spawn()
-	const result = execaSync(git_binary, GIT_DIRECTORY_ARGUMENTS, {
-		reject: false,
-		timeout: GIT_TIMEOUT_MS,
-	}) // NOSONAR
-
-	if (result.exitCode !== 0) return undefined
-
-	const output = result.stdout.trim()
-
-	return output === '' ? undefined : output
-}
-
 function stamp_target_sync(): string | undefined {
-	const directory = git_directory_sync()
+	const directory = git_common_directory.own()
 
 	return directory === undefined ? undefined : stamp_target_of(directory)
 }
@@ -299,8 +277,6 @@ const run_progress_clock = {
 	LIFE_PREFIX,
 	LOG_KEEP,
 	LOG_STALE_MS,
-	PROGRESS_PREFIX,
-	append_line,
 	begin_life,
 	end_life,
 	is_life_ended,
@@ -314,7 +290,6 @@ const run_progress_clock = {
 	read_last_report,
 	read_last_report_sync,
 	stamp_target_of,
-	stamp_target_sync,
 }
 
 export { run_progress_clock }

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

@@ -27,8 +27,6 @@ import { run_progress } from './run-progress'
 // watcher it guards kept the default, which is the one state this module exists to prevent.
 
 const PACKAGE_FILE = 'package.json'
-const CONFIG_FIELD = 'josh'
-const INTERVAL_FIELD = 'progress_interval_minutes'
 
 // 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.
@@ -108,8 +106,6 @@ function configured_interval_ms(directory: string = process.cwd()): number {
 }
 
 const run_progress_config = {
-	CONFIG_FIELD,
-	INTERVAL_FIELD,
 	PACKAGE_FILE,
 	configured_interval_ms,
 	read_package_minutes,

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

@@ -28,7 +28,7 @@ import { run_progress_clock } from './run-progress-clock'
 // `run-progress-clock.ts`, because the trigger-delivered rule that refuses an early heartbeat reads
 // the same record from inside a `PreToolUse` hook and cannot await the git call this file makes
 // (joshuafolkken/kit#1570). What stays here is the asynchronous way of naming the work tree.
-const { PROGRESS_PREFIX, mark, parse_stamp, read_last_report } = run_progress_clock
+const { mark, parse_stamp, read_last_report } = run_progress_clock
 
 const FIRST_LOAD_AVERAGE = 0
 
@@ -182,7 +182,6 @@ async function read_observations(request: ObservationRequest): Promise<Observati
 }
 
 const run_progress_read = {
-	PROGRESS_PREFIX,
 	has_run_started,
 	live_target,
 	log_target,

package/scripts/run/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.md` → `josh run:progress`): it holds only while the silence continues, and a
+ * (`docs/josh-commands-automation.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.
  */
@@ -367,7 +367,6 @@ const run_progress = {
 	format_line,
 	format_next_line,
 	format_next_report,
-	format_record,
 	format_report,
 	is_due,
 	minutes_from,

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

@@ -0,0 +1,117 @@
+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_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
+// which as the resume token `fullrun #N` acts on — read, never inferred:
+//
+// - `prrun-merged` — the person merged it by hand. Only `followup`'s tail is left.
+// - `prrun-merge` — the branch is where the stop left it, both here and on the pull request, and the
+//   tree is clean. What was verified is what would merge, so `followup` merges without the gate and
+//   the review again.
+// - `prrun-gate` — the branch moved since the stop, or the tree is dirty: a person changed something,
+//   so the gate and the review run again before `followup`. **The pull request's own head is asked
+//   too**: a commit pushed on GitHub (a suggestion applied, "Update branch") moves only the remote,
+//   and `followup` merges the remote — an unread or moved one is never taken as untouched.
+//
+// **Only a marked record is adopted**, as for the `halfrun` stop (`run-halfrun-resume.ts`): the stop
+// writes the commit it stopped on (`run:hold <N> --prrun-stop`), and a hold without it is a run still
+// working, never one waiting for a person.
+
+const PRRUN_MERGED = 'prrun-merged'
+const PRRUN_MERGE = 'prrun-merge'
+const PRRUN_GATE = 'prrun-gate'
+
+type PrrunToken = typeof PRRUN_GATE | typeof PRRUN_MERGE | typeof PRRUN_MERGED
+
+interface ResumeFacts {
+	is_merged: boolean
+	stop_head: string
+	head: string
+	// The commit the pull request's head is on, or `undefined` when it could not be read.
+	pr_head: string | undefined
+	is_dirty: boolean
+}
+
+function is_untouched(facts: ResumeFacts): boolean {
+	return facts.head === facts.stop_head && facts.pr_head === facts.stop_head && !facts.is_dirty
+}
+
+function decide(facts: ResumeFacts): PrrunToken {
+	if (facts.is_merged) return PRRUN_MERGED
+
+	return is_untouched(facts) ? PRRUN_MERGE : PRRUN_GATE
+}
+
+function stop_head_of(read: HoldRead, issue: string): string | undefined {
+	const hold = run_halfrun_resume.hold_of(read)
+
+	return hold?.issue === issue ? hold.prrun_stop_head : undefined
+}
+
+async function read_merge_state(): Promise<PullMergeState | undefined> {
+	return await git_gh_command.pr_get_merge_state(await git_branch.current())
+}
+
+async function read_facts(stop_head: string): Promise<ResumeFacts> {
+	const [state, head, is_dirty] = await Promise.all([
+		read_merge_state(),
+		git_command.head_commit(),
+		run_hold.is_tree_dirty(),
+	])
+
+	return {
+		is_merged: state?.is_merged === true,
+		stop_head,
+		head,
+		pr_head: state?.head_sha,
+		is_dirty,
+	}
+}
+
+// Read-only, so `run:entry` can ask the session budget before it takes anything over. `undefined` is
+// "no `prrun` stop for this issue here", and the ordinary claim decides the tree as before.
+async function resume_token(issue: string): Promise<PrrunToken | undefined> {
+	const target = await run_halfrun_resume.hold_target()
+
+	if (target === undefined) return undefined
+
+	const stop_head = stop_head_of(run_hold.read_hold(target), issue)
+
+	return stop_head === undefined ? undefined : decide(await read_facts(stop_head))
+}
+
+async function adopt(issue: string): Promise<boolean> {
+	const target = await run_halfrun_resume.hold_target()
+
+	if (target === undefined || stop_head_of(run_hold.read_hold(target), issue) === undefined) {
+		return false
+	}
+
+	return run_halfrun_resume.take_over(target, issue)
+}
+
+// The `--prrun-stop` mark: the run's own record re-written with the commit the pull request is on.
+async function mark_stop_at(target: string, issue: string): Promise<StopMark> {
+	const head = await git_command.head_commit()
+
+	return run_halfrun_resume.mark_stop_at(target, issue, { prrun_stop_head: head })
+}
+
+const run_prrun_resume = {
+	PRRUN_GATE,
+	PRRUN_MERGE,
+	PRRUN_MERGED,
+	adopt,
+	decide,
+	mark_stop_at,
+	resume_token,
+	stop_head_of,
+}
+
+export type { PrrunToken, ResumeFacts }
+export { run_prrun_resume }

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { git_followup_pending } from '#scripts/git/git-followup-pending'
+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'
@@ -62,7 +62,6 @@ async function main(): Promise<void> {
 }
 
 const run_report_cli = {
-	main,
 	run,
 }
 

package/scripts/run/run-report.ts

@@ -71,7 +71,6 @@ function build_report(input: ReportInput): string {
 const run_report = {
 	UNKNOWN_SCOPE_NOTICE,
 	build_report,
-	release_tail,
 }
 
 export type { ReportInput }

package/scripts/run/run-retrospective.ts

@@ -28,7 +28,7 @@ function is_owed(facts: RetrospectiveFacts): boolean {
 	return !facts.is_lane_child && !facts.is_retrospective_done && !facts.is_consumer
 }
 
-const run_retrospective = { RETROSPECTIVE_ENV_KEY, is_enabled, is_owed }
+const run_retrospective = { is_enabled, is_owed }
 
 export type { RetrospectiveFacts }
 export { run_retrospective }

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

@@ -118,10 +118,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 }
 
 const run_review_cli = {
-	JOIN_FLAG,
-	USAGE,
 	join_exit_code,
-	main,
 	run,
 }
 

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

@@ -94,7 +94,9 @@ async function wait_for_gate_finish(now: Clock = () => Date.now()): Promise<Gate
 	let state = await read_gate_state()
 
 	while (!run_review.is_gate_settled(state) && now() - started < MAX_JOIN_WAIT_MS) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(POLL_INTERVAL_MS)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		state = await read_gate_state()
 	}
 

package/scripts/run/run-review.ts

@@ -105,12 +105,10 @@ const run_review = {
 	GATE_RED,
 	GATE_RUNNING,
 	adopt_verdict,
-	format_seconds,
 	format_timing,
 	gate_state,
 	is_gate_settled,
 	overlap_seconds,
-	span_seconds,
 }
 
 export type { AdoptVerdict, GateState, ReviewTiming, TimingStart }

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

@@ -1,11 +1,12 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { parseArgs } from 'node:util'
 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_ship, type ShipSection } from './run-ship'
 import { run_ship_detach } from './run-ship-detach'
+import { run_ship_next } from './run-ship-next'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_return } from './run-ship-return'
 import { run_ship_stage, type Phase, type ShipState, type Stage } from './run-ship-stage'
@@ -120,13 +121,6 @@ interface ParsedValues extends NotifyValues {
 	cite?: Array<string>
 }
 
-function parse_values(argv: ReadonlyArray<string>): {
-	values: ParsedValues
-	positionals: Array<string>
-} {
-	return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true, strict: true })
-}
-
 function ship_args(
 	title: string,
 	rest: ReadonlyArray<string>,
@@ -154,9 +148,10 @@ function log_command(number: string, positionals: ReadonlyArray<string>): ShipCo
 	return CITE_PATTERN.test(number) && positionals.length === 0 ? { kind: 'log', number } : undefined
 }
 
-function read_args(argv: ReadonlyArray<string>): ShipCommand | undefined {
-	const { values, positionals } = parse_values(argv)
-
+function command_of(
+	values: ParsedValues,
+	positionals: ReadonlyArray<string>,
+): ShipCommand | undefined {
 	if (values.log !== undefined) return log_command(values.log, positionals)
 
 	const title = positionals[FIRST]
@@ -169,11 +164,9 @@ function read_args(argv: ReadonlyArray<string>): ShipCommand | undefined {
 // Numbers-only tail and a strict parse, so a title with no `#<N>` or a stray flag is refused rather
 // than shipped past the wrong step.
 function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
-	try {
-		return read_args(argv)
-	} catch {
-		return undefined
-	}
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	return parsed === undefined ? undefined : command_of(parsed.values, parsed.positionals)
 }
 
 async function run_step(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {
@@ -255,7 +248,9 @@ async function stopped(
 	args: ShipArguments,
 	stage: Stage,
 ): Promise<ReadonlyArray<ShipSection>> {
-	if (run_ship_detach.is_supervised()) await run_ship_return.return_control(args.number, stage)
+	if (run_ship_detach.is_supervised()) {
+		await run_ship_return.return_control(args.number, stage, run_ship_next.resume_of(args))
+	}
 
 	return sections
 }
@@ -268,10 +263,12 @@ async function ship(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const sections: Array<ShipSection> = []
 
 	for (const step of run_ship_steps.steps(args)) {
+		// eslint-disable-next-line no-await-in-loop -- stages run in order and the first failure stops the ship
 		const section = await run_stage(step, args, context)
 
 		sections.push(section)
 
+		// eslint-disable-next-line no-await-in-loop -- stages run in order and the first failure stops the ship
 		if (section.code !== SUCCESS_EXIT_CODE) return await stopped(sections, args, step.stage)
 	}
 
@@ -324,6 +321,19 @@ function should_detach(args: ShipArguments): boolean {
 	return !run_ship_detach.is_supervised() && lane_child_marker.is_child_of(process.cwd())
 }
 
+// joshuafolkken/kit#2966: the preflight is deterministic and fast, so it runs here, in the agent's own
+// turn, before the hand-off — a stop it finds is fixed by the same session instead of relaunching one
+// from the supervisor. Only the slow stages go to the supervisor, which re-asks the preflight itself.
+async function detach_after_preflight(args: ShipArguments): Promise<number> {
+	const section = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
+
+	if (section.code === SUCCESS_EXIT_CODE) return await detach(args)
+
+	console.info(run_ship.format_report([section]))
+
+	return run_ship.exit_code([section])
+}
+
 async function supervised_repository(): Promise<string | undefined> {
 	return run_ship_detach.is_supervised() ? await run_ship_probe.repository_directory() : undefined
 }
@@ -346,7 +356,7 @@ async function run_ship_command(args: ShipArguments): Promise<number> {
 	if (should_detach(args)) {
 		if (!args.is_detach) console.error(LANE_CHILD_DETACH_NOTE)
 
-		return await detach(args)
+		return await detach_after_preflight(args)
 	}
 
 	await claim_supervised_identity(args)
@@ -376,7 +386,7 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const run_ship_cli = { SUCCESS_EXIT_CODE, USAGE, main, parse, run, ship }
+const run_ship_cli = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

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

@@ -195,6 +195,7 @@ async function ready_record(repository: string, number: string): Promise<ShipRec
 	for (let attempt = 0; attempt < RECORD_WAIT_ATTEMPTS; attempt += 1) {
 		if (!is_pending(record)) return record
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(RECORD_POLL_MS)
 		record = current_record(repository, number)
 	}