@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,20 +1,24 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { check_reuse, type CheckRecords } from '#scripts/gate/check-reuse'
-import { gate_plan } from '#scripts/gate/gate-plan'
+import { gate_labels } from '#scripts/gate/gate-labels'
 import type { GateStepResult } from '#scripts/gate/gate-report'
 import { gate_tree } from '#scripts/gate/gate-tree'
+import { metrics_totals } from '#scripts/gate/metrics-totals'
 import { project_checks } from '#scripts/gate/project-checks'
+import { structural_checks } from '#scripts/gate/structural-checks'
 import { type_check_step } from '#scripts/gate/type-check-step'
 import type { JoshResult } from '#scripts/josh/josh-run'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 
 // The fast checks a detached `josh ship` runs in the agent's own turn, after the preflight (whatever it
-// answered) and before the hand-off:a type error in a file the related-only checks never touched, an export nothing reads,
+// answered) and before the hand-off: a type error in a file the related-only checks never touched, an export nothing reads,
 // an unknown word, or a guard test (a SKILL.md pointer, a byte budget, the command list, a source with
 // no colocated test, a bare issue citation) that only the full suite runs, would otherwise first
 // surface after the detach and cost a relaunched session. They answer in seconds, so the same session
-// fixes what they find and ships again.
+// fixes what they find and ships again. A `--review` ship adds `test:pinned`, which probes the hunks
+// its verdict cache does not hold (`run-ship-pre-detach-pinned.ts`).
 //
 // **Nothing moves out of the gate, and the gate reuses what these already answered**: a check that is
 // the gate's own check passed silently here is recorded with the gate's per-check record
@@ -33,7 +37,10 @@ import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffe
 // present run, and a consumer meets the static checks alone.
 //
 // In kit the metrics ratchet's totals join them: a feature grows a total almost every time, and here
-// the session that grew the total writes the reason itself rather than a relaunched one. The
+// the session that grew the total writes the reason itself rather than a relaunched one —
+// `josh lint:related` has already reported the growth in the loop (`metrics-totals.ts`), so this is
+// the stop for a growth that notice did not settle. A total the branch's approval already names is
+// re-recorded at its growth here rather than stopped (`--rerecord`, joshuafolkken/kit#4716). The
 // durations are left out: they read the gate ledger, stale before the detach, so they stay with the
 // supervised gate.
 
@@ -53,9 +60,10 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const SECTION_SEPARATOR = '\n\n'
 const PASSED = 'pre-detach checks passed'
-const METRICS_TOTALS_COMMAND: ReadonlyArray<string> = ['josh', 'metrics', '--totals-only']
+const UNPINNED = 'unpinned'
+const { METRICS_RERECORD_COMMAND } = metrics_totals
 const STATIC_CHECKS: ReadonlyArray<PreDetachCheck> = [
-	{ list: ['josh', 'exports:unused'], label: gate_plan.EXPORTS_LABEL },
+	{ list: ['josh', 'exports:unused'], label: gate_labels.EXPORTS_LABEL },
 	{ list: ['josh', 'cspell:dot'] },
 ]
 const GUARD_TEST_TARGETS: ReadonlyArray<string> = [
@@ -63,13 +71,10 @@ const GUARD_TEST_TARGETS: ReadonlyArray<string> = [
 	'scripts/claude',
 	'scripts/rules',
 	'scripts/josh/josh-command-map.test.ts',
-	'scripts/issue/session-cite-scan.test.ts',
-	'tools/test/untested-sources.test.ts',
+	...structural_checks.STRUCTURAL_GUARD_TARGETS,
 	'tools/test/pure-files.test.ts',
 ]
-// A present directory need not hold a test the project's Vitest includes — a consumer's own
-// `scripts/claude` of shell helpers, say — and a filter that matches nothing would stop every ship.
-const GUARD_TEST_COMMAND: ReadonlyArray<string> = ['josh', 'test:unit', '--passWithNoTests']
+const { GUARD_TEST_COMMAND, failure_prefix, failure_section } = structural_checks
 
 function present_targets(directory: string): ReadonlyArray<string> {
 	return GUARD_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
@@ -83,17 +88,16 @@ function guard_tests(directory: string): Array<PreDetachCheck> {
 
 // The same kit-only rule as the gate's `is_kit_only` step: a consumer's kit has no `josh metrics`.
 function kit_only(directory: string): Array<PreDetachCheck> {
-	return project_checks.is_kit_repository(directory) ? [{ list: METRICS_TOTALS_COMMAND }] : []
+	return project_checks.is_kit_repository(directory) ? [{ list: METRICS_RERECORD_COMMAND }] : []
 }
 
 async function command_lists(directory: string): Promise<Array<PreDetachCheck>> {
 	const type_check = await type_check_step.resolve_type_check_args(directory)
 
 	return [
-		{ list: type_check, label: gate_plan.TYPE_CHECK_LABEL },
+		{ list: type_check, label: gate_labels.TYPE_CHECK_LABEL },
 		...STATIC_CHECKS,
 		...guard_tests(directory),
-		...kit_only(directory),
 	]
 }
 
@@ -120,38 +124,88 @@ function gate_results(runs: ReadonlyArray<PreDetachRun>): Array<GateStepResult>
 		})
 }
 
-function verdict(results: ReadonlyArray<BufferedProcessResult>): JoshResult {
-	const failed = results.filter((result) => buffered_process.is_process_failed(result))
+function verdict(runs: ReadonlyArray<PreDetachRun>): JoshResult {
+	const failed = runs.filter(({ result }) => buffered_process.is_process_failed(result))
 
 	if (failed.length === 0) return { code: SUCCESS_EXIT_CODE, out: PASSED }
 
 	return {
 		code: FAILURE_EXIT_CODE,
-		out: failed.map((result) => result.output.trim()).join(SECTION_SEPARATOR),
+		out: failed
+			.map(({ check, result }) => failure_section(check.list, result))
+			.join(SECTION_SEPARATOR),
 	}
 }
 
+// The `test:pinned` check a `--review` ship adds (`run-ship-pre-detach-pinned.ts`); none is asked by default.
+type PinnedCheck = () => Promise<JoshResult>
+
+async function not_asked(): Promise<JoshResult> {
+	return { code: SUCCESS_EXIT_CODE, out: PASSED }
+}
+
+// The checks' answer, with the kinds a `stop` record names its red by: `pre-detach` for the static
+// checks, `unpinned` for `test:pinned`, so `lane:stats` tells an unpinned stop apart
+// (joshuafolkken/kit#5228).
+interface PreDetachResult extends JoshResult {
+	preconditions?: ReadonlyArray<string>
+}
+
+function joined(result: JoshResult, pinned: JoshResult): JoshResult {
+	if (pinned.code === SUCCESS_EXIT_CODE) return result
+	if (result.code === SUCCESS_EXIT_CODE) return pinned
+
+	return { code: FAILURE_EXIT_CODE, out: [result.out, pinned.out].join(SECTION_SEPARATOR) }
+}
+
+function red_kinds(result: JoshResult, pinned: JoshResult): ReadonlyArray<string> {
+	return [
+		...(result.code === SUCCESS_EXIT_CODE ? [] : [lane_ledger_write.PRE_DETACH_STAGE]),
+		...(pinned.code === SUCCESS_EXIT_CODE ? [] : [UNPINNED]),
+	]
+}
+
+// The pinned check's stop joins the others' rather than hiding them.
+function with_pinned(result: JoshResult, pinned: JoshResult): PreDetachResult {
+	const preconditions = red_kinds(result, pinned)
+	const answer = joined(result, pinned)
+
+	return preconditions.length === 0 ? answer : { ...answer, preconditions }
+}
+
 // All run at once, buffered, and every failure is reported, so one ship shows all there is to fix.
-// The tree is read before they start, so a record is written only for the tree they read.
+// The tree is read before they start, so a record is written only for the tree they read. **The
+// metrics totals run first, alone**: they may re-record the branch's approval file
+// (`metrics-command.ts`), and a file written under the others would move the tree and leave the gate
+// nothing to reuse (joshuafolkken/kit#4716).
 async function checks(
 	directory: string = process.cwd(),
 	records: CheckRecords = check_reuse.DEFAULT_RECORDS,
-): Promise<JoshResult> {
+	pinned: PinnedCheck = not_asked,
+): Promise<PreDetachResult> {
+	const metrics = await Promise.all(
+		kit_only(directory).map(async (check) => await run_in(directory, check)),
+	)
 	const [lists, tree] = await Promise.all([command_lists(directory), gate_tree.read_gate_tree()])
-	const runs = await Promise.all(lists.map(async (check) => await run_in(directory, check)))
+	const [runs, pinned_result] = await Promise.all([
+		Promise.all(lists.map(async (check) => await run_in(directory, check))),
+		pinned(),
+	])
 
 	await check_reuse.record_green_checks(gate_results(runs), tree, records)
 
-	return verdict(runs.map(({ result }) => result))
+	return with_pinned(verdict([...runs, ...metrics]), pinned_result)
 }
 
 const run_ship_pre_detach = {
 	GUARD_TEST_TARGETS,
-	METRICS_TOTALS_COMMAND,
+	METRICS_RERECORD_COMMAND,
 	PASSED,
 	STATIC_CHECKS,
+	UNPINNED,
 	checks,
+	failure_prefix,
 }
 
-export type { PreDetachCheck }
+export type { PinnedCheck, PreDetachCheck, PreDetachResult }
 export { run_ship_pre_detach }

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

@@ -13,7 +13,9 @@ import { acceptance_map_check } from '#scripts/review/acceptance-map-check'
 import { live_evidence } from '#scripts/review/live-evidence'
 import { removed_tests_check } from '#scripts/review/removed-tests-check'
 import { run_ship_body_draft } from './run-ship-body-draft'
+import { run_ship_lap } from './run-ship-lap'
 import { run_ship_lock } from './run-ship-lock'
+import { run_ship_planned } from './run-ship-planned'
 import { run_ship_scoped } from './run-ship-scoped'
 
 // `josh ship`'s first stage. The commit stage (`git -y`'s preflight) and the merge (`followup`'s
@@ -22,7 +24,8 @@ import { run_ship_scoped } from './run-ship-scoped'
 // 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 ship body
-// draft, else the open PR's.
+// draft, else the open PR's. The `unplanned` answer is the branch's code files the lane's `lane:plan`
+// record never listed (`run-ship-planned.ts`).
 //
 // 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.
@@ -39,6 +42,7 @@ const PRECONDITION = {
 	REMOVED_TESTS: 'removed-tests',
 	LOCK: 'lock',
 	SCOPED: 'scoped',
+	UNPLANNED: run_ship_planned.PRECONDITION,
 	UNREADABLE: 'unreadable',
 } as const
 const EVIDENCE_PROBLEM = `This change touches runtime code, but the body this ship delivers has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and write it into the ship body draft run:prep wrote (josh ship reads it when --body-file is omitted), or pass the body with --body-file <path>. Write it ${live_evidence.EVIDENCE_FORMAT}`
@@ -149,22 +153,30 @@ async function lock_problems(): Promise<Array<Unmet>> {
 	return of_kind(PRECONDITION.LOCK, await run_ship_lock.lock_problems())
 }
 
+async function planned_problems(): Promise<Array<Unmet>> {
+	return of_kind(PRECONDITION.UNPLANNED, await run_ship_planned.problems())
+}
+
 // The lock file is asked here too, 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<Unmet>> {
-	const [preflight, evidence, acceptance, removed, lock] = await Promise.all([
+	const [preflight, evidence, acceptance, removed, lock, planned] = await Promise.all([
 		caught(git_preflight.problems_of({ cli_input: request.title, will_open_pr: true })),
 		caught(evidence_problems(request.body_path)),
 		caught(acceptance_problems(request.body_path)),
 		caught(removed_test_problems(request.body_path)),
 		caught(lock_problems()),
+		caught(planned_problems()),
 	])
 
-	return [...preflight, ...evidence, ...acceptance, ...removed, ...lock]
+	return [...preflight, ...evidence, ...acceptance, ...removed, ...lock, ...planned]
 }
 
 async function stage(request: PreflightRequest): Promise<PreflightResult> {
-	const problems = await asked_problems(request)
+	const problems = await run_ship_lap.timed(
+		run_ship_lap.STEP.PRECONDITIONS,
+		async () => await asked_problems(request),
+	)
 
 	if (problems.length > 0) return refusal(problems)
 

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

@@ -1,7 +1,7 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
-import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import { error_text } from '#scripts/lib/error-message'
+import { review_round_reuse } from '#scripts/review/review-round-reuse'
 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'
@@ -31,8 +31,8 @@ async function or_false(is_true: () => Promise<boolean>): Promise<boolean> {
 
 // A clean tree whose branch holds commits the default branch does not: the commit stage's output. A
 // dirty tree is uncommitted work, whatever is already committed beneath it.
-async function read_committed(): Promise<boolean> {
-	if (await run_hold.is_tree_dirty()) return false
+async function read_committed(is_dirty: boolean): Promise<boolean> {
+	if (is_dirty) return false
 
 	const base = await git_command.default_branch_reference()
 
@@ -61,23 +61,31 @@ async function read_merged(branch_name: string): Promise<boolean> {
 	return (await git_command.commit_count_beyond(base, HEAD_REFERENCE)) === 0
 }
 
-// The issue changed after the recorded review was briefed — the refusal `josh followup` would make
-// (joshuafolkken/kit#4221) — so the review stage re-runs instead of the followup failing again.
+// A stale review re-runs the review stage instead of the followup failing again.
 async function read_review_stale(): Promise<boolean> {
-	return await or_false(async () => (await issue_watch_gate.review_refusal_here()) !== undefined)
+	return await review_round_reuse.is_stale_here()
 }
 
 const NOTHING_DONE: ShipState = { is_committed: false, is_pushed: false, is_merged: false }
 
 async function read_branch_state(branch_name: string): Promise<ShipState> {
+	const is_dirty = await run_hold.is_tree_dirty()
 	const [is_committed, is_pushed, is_merged, is_review_stale] = await Promise.all([
-		or_false(read_committed),
+		or_false(async () => await read_committed(is_dirty)),
 		or_false(async () => await read_pushed(branch_name)),
 		or_false(async () => await read_merged(branch_name)),
 		read_review_stale(),
 	])
 
-	return { is_committed, is_pushed, is_merged, is_review_stale }
+	return { is_committed, is_pushed, is_merged, is_review_stale, is_dirty }
+}
+
+// Origin holds `HEAD` and nothing is left uncommitted: a line written to the tree now has no commit of
+// the run's own to ride, so pushing it would restart the pull request's CI (joshuafolkken/kit#4907).
+async function is_pushed_clean(): Promise<boolean> {
+	if (await run_hold.is_tree_dirty()) return false
+
+	return await or_false(async () => await read_pushed(await git_command.branch()))
 }
 
 // A branch that cannot be named leaves nothing to ask about, so it reads as nothing done.
@@ -109,6 +117,12 @@ async function record_target(issue: string): Promise<string | undefined> {
 	return repository === undefined ? undefined : run_ship_stage.record_path(repository, issue)
 }
 
-const run_ship_probe = { read_review_stale, read_state, record_target, repository_directory }
+const run_ship_probe = {
+	is_pushed_clean,
+	read_review_stale,
+	read_state,
+	record_target,
+	repository_directory,
+}
 
 export { run_ship_probe }

package/scripts/run/ship/run-ship-relaunch-cap.ts

@@ -6,6 +6,8 @@ import { run_event_scope } 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_stalled } from '#scripts/run/park/run-stalled'
+import { run_ship_stage } from './run-ship-stage'
+import { run_ship_stop_text } from './run-ship-stop-text'
 
 // How many times a stopped ship relaunches its lane child before the issue goes to a person. A child
 // that keeps stopping — the same red check, a finding it cannot close — would otherwise relaunch
@@ -18,29 +20,56 @@ import { run_stalled } from '#scripts/run/park/run-stalled'
 // The whole stream is read, not the run's carry scope: the count scopes itself by issue and dispatch,
 // and a lane child shipping with no carry record (`lane:dispatch` outside a run, or a run already
 // ended) would otherwise read no events and relaunch without a cap.
+//
+// **Each kind of stop has its own cap** (joshuafolkken/kit#4707): a review stop (round 1 or round 2)
+// and a mechanical one (gate, sync, commit, followup, conflict) are counted apart, so the review's
+// back-and-forth never spends the relaunches a red CI run needs. The kind is read off the stop's text
+// (`run-ship-stop-text.ts`); a text with no stage reads as mechanical.
 
 // One dispatch's own stops in the measured week reached five once and four or fewer otherwise, so four
 // relaunches leave a ship that converges alone and stop the one that does not.
 const MAX_SHIP_STOP_RELAUNCHES = 4
 const PARK_CAUSE = 'ship-stop cap'
 const { CHILD_LAUNCH, PARK, SHIP_STOP } = run_event_stream.EVENT_KIND
+const STOP_KIND = { REVIEW: 'review', MECHANICAL: 'mechanical' } as const
+const REVIEW_REASONS: ReadonlySet<string> = new Set([
+	run_ship_stage.STAGE.REVIEW,
+	run_ship_stage.STAGE.ROUND_TWO,
+])
+
+type StopKind = (typeof STOP_KIND)[keyof typeof STOP_KIND]
+
+function kind_of(reason: string | undefined): StopKind {
+	return reason !== undefined && REVIEW_REASONS.has(reason)
+		? STOP_KIND.REVIEW
+		: STOP_KIND.MECHANICAL
+}
 
-function stops_since_dispatch(events: ReadonlyArray<RunEvent>, issue: string): number {
+function is_stop_of(event: RunEvent, kind: StopKind): boolean {
+	return event.kind === SHIP_STOP && kind_of(run_ship_stop_text.reason_of(event.text)) === kind
+}
+
+function stops_since_dispatch(
+	events: ReadonlyArray<RunEvent>,
+	issue: string,
+	kind: StopKind,
+): number {
 	const own = events.filter((event) => run_event_scope.issue_named(event) === issue)
 	const dispatched = own.findLastIndex((event) => event.kind === CHILD_LAUNCH)
 
-	return own.slice(dispatched + 1).filter((event) => event.kind === SHIP_STOP).length
+	return own.slice(dispatched + 1).filter((event) => is_stop_of(event, kind)).length
 }
 
-async function is_over(issue: string): Promise<boolean> {
+// `reason` is the current stop's; only the stops of its kind are counted.
+async function is_over(issue: string, reason: string): Promise<boolean> {
 	const events = await run_event_stream_emit.all_events()
 
-	return stops_since_dispatch(events, issue) > MAX_SHIP_STOP_RELAUNCHES
+	return stops_since_dispatch(events, issue, kind_of(reason)) > MAX_SHIP_STOP_RELAUNCHES
 }
 
 function park_comment(issue: string, reason: string): string {
 	return [
-		`Parked by the \`josh ship\` supervisor: the ship stopped at \`${reason}\` after ${String(MAX_SHIP_STOP_RELAUNCHES)} relaunches of the lane child since its dispatch.`,
+		`Parked by the \`josh ship\` supervisor: the ship stopped at \`${reason}\` after ${String(MAX_SHIP_STOP_RELAUNCHES)} relaunches of the lane child for ${kind_of(reason)} stops since its dispatch — the ${kind_of(reason)} stop cap was exceeded.`,
 		'',
 		`Read the stop with \`pnpm josh ship --log ${issue}\`, then ${run_stalled.next_step(issue)}.`,
 	].join('\n')
@@ -58,13 +87,20 @@ async function park(issue: string, reason: string): Promise<boolean> {
 	await run_event_stream_emit.emit(PARK, run_stalled.park_event(issue, PARK_CAUSE))
 	await telegram_notify.warn({
 		issue_title: `Ship stop cap reached ${cite}`,
-		body: `The lane child stopped at ${reason} more than ${String(MAX_SHIP_STOP_RELAUNCHES)} times since its dispatch, so it was not relaunched and the issue is parked.`,
+		body: `The lane child's ${kind_of(reason)} stops passed their cap of ${String(MAX_SHIP_STOP_RELAUNCHES)} relaunches since its dispatch, the last at ${reason}, so it was not relaunched and the issue is parked.`,
 		recovery: `Read pnpm josh ship --log ${issue}, then fix the cause and remove ${RUN_STALLED_LABEL} to offer it again.`,
 	})
 
 	return true
 }
 
-const run_ship_relaunch_cap = { MAX_SHIP_STOP_RELAUNCHES, is_over, park, stops_since_dispatch }
+const run_ship_relaunch_cap = {
+	MAX_SHIP_STOP_RELAUNCHES,
+	STOP_KIND,
+	is_over,
+	kind_of,
+	park,
+	stops_since_dispatch,
+}
 
 export { run_ship_relaunch_cap }

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

@@ -0,0 +1,51 @@
+import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
+import { run_ship_detach } from './run-ship-detach'
+
+// A supervisor's successor on new code (`run-ship-handover.ts`) is the same launch: it keeps the launch
+// id, so every reader of the record — `ship:wait`, a lane's liveness, the overlap order by launch time —
+// sees one ship throughout, and the successor's claim and result land on that record.
+//
+// **The record keeps naming this supervisor until the successor claims it**
+// (`run_ship_detach.claim_identity`), so it is believed live throughout, and the successor's pid on it
+// is the take-over's proof.
+//
+// **The successor is this very process's command line, re-invoked under the same runner**, as the wake
+// supervisor re-invokes itself (`run-wake-session.ts`). Launched through `pnpm josh ship`, the spawned
+// pid would be pnpm's while the claim names the node process under it, so no claim would ever match.
+
+interface RelaunchRequest {
+	repository: string
+	number: string
+	cwd: string
+}
+
+// The pid the ship record names.
+function holder_pid(repository: string, number: string): number | undefined {
+	return run_ship_detach.read_record(repository, number)?.pid
+}
+
+// The supervisor's own argv ends with its `"<title> #<N>"` title, which a lane's liveness pattern needs.
+function successor_argv(): LaunchArgv {
+	return { command: process.execPath, args: [...process.execArgv, ...process.argv.slice(1)] }
+}
+
+// The successor's pid, `undefined` where this process is no supervisor or none started.
+function relaunch(request: RelaunchRequest): number | undefined {
+	const launch_id = process.env[run_ship_detach.LAUNCH_ID_KEY]
+	if (launch_id === undefined) return undefined
+	const result = detached_launch.launch(
+		{
+			argv: successor_argv(),
+			cwd: request.cwd,
+			log_path: run_ship_detach.log_path(request.repository, request.number),
+			env: run_ship_detach.supervisor_environment(launch_id),
+		},
+		console.error,
+	)
+
+	return result.kind === 'launched' ? result.pid : undefined
+}
+
+const run_ship_relaunch = { holder_pid, relaunch }
+
+export { run_ship_relaunch }