@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,7 +1,10 @@
 import { gate_skip } from '#scripts/gate/gate-skip'
-import { gate_tree } from '#scripts/gate/gate-tree'
+import { gate_tree, type GateTree } from '#scripts/gate/gate-tree'
+import { metrics_totals } from '#scripts/gate/metrics-totals'
 import { scoped_green } from '#scripts/gate/scoped-green'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
+import { run_ship_lap } from './run-ship-lap'
+import { run_ship_synced_scope } from './run-ship-synced-scope'
 
 // The scoped pair `josh ship` meets itself rather than stops on, shared by every stage that needs a
 // green record for this tree: the preflight stage at the start, the review rounds, and the gate
@@ -25,13 +28,30 @@ async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
 	return last
 }
 
+// The tree after the branch's metrics approval is re-recorded (`metrics-totals.ts`): every review fix
+// and the gate stage meet the pair here, so a rewrite lands before any record is written for the tree.
+async function rerecorded_tree(): Promise<GateTree> {
+	const tree = await gate_tree.read_gate_tree()
+	const is_rerecorded = await metrics_totals.rerecord(process.cwd(), tree.files)
+
+	return is_rerecorded ? await gate_tree.read_gate_tree() : tree
+}
+
 // 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()
+// output forwarded to the ship log. A pair stale only because a merge with the default branch moved the
+// base runs nothing when the merge shares nothing with the branch (`run-ship-synced-scope.ts`).
+async function settled_pair(): Promise<JoshResult> {
+	const tree = await rerecorded_tree()
 	const scripts = scoped_green.missing_scripts(tree.files, tree.base)
+	const settled = await run_ship_synced_scope.settle(tree, scripts)
+
+	if (settled !== undefined) {
+		process.stdout.write(`${settled}\n`)
+
+		return { code: SUCCESS_EXIT_CODE, out: settled }
+	}
 
 	return await run_phases(
 		scripts.map(
@@ -40,13 +60,22 @@ async function scoped_pair(): Promise<JoshResult> {
 	)
 }
 
-// The scoped pair and then `josh gate` — the gate stage, and the followup's gate over a merged tree
-// before its push, so both leave the record the pre-push hook reuses.
-async function scoped_gate(): Promise<JoshResult> {
-	return await run_phases([
-		scoped_pair,
+// Timed as one lap in whichever ship stage asked for it (`run-ship-lap.ts`).
+async function scoped_pair(): Promise<JoshResult> {
+	return await run_ship_lap.timed(run_ship_lap.STEP.SCOPED_PAIR, settled_pair)
+}
+
+async function gate(): Promise<JoshResult> {
+	return await run_ship_lap.timed(
+		run_ship_lap.STEP.GATE,
 		async () => await josh_command.josh_run(['gate'], should_forward_stderr),
-	])
+	)
+}
+
+// The scoped pair and then `josh gate` — the gate stage, and the commit stage's and the followup's gate
+// over a merged tree before their push, so each leaves the record the pre-push hook reuses.
+async function scoped_gate(): Promise<JoshResult> {
+	return await run_phases([scoped_pair, gate])
 }
 
 // Whether `josh gate` would only reuse this tree's green record: the gate's own reuse test rather than

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

@@ -14,7 +14,7 @@ import { z } from 'zod'
 // the state, and a stale one is overruled by it. Neither can produce a second commit, push or merge.
 //
 // **The gate is never skipped on the record's word.** It is passed over only once its output — a
-// commit — exists; otherwise it runs, and `josh gate`'s own tree-keyed green record is what makes a
+// pushed commit — exists; otherwise it runs, and `josh gate`'s own tree-keyed green record is what makes a
 // re-run on an unchanged tree a reuse rather than a second execution. No quality gate is folded away.
 
 const STAGE = {
@@ -47,6 +47,8 @@ interface ShipState {
 	// The issue changed after the recorded review's brief (`issue-watch-gate.ts`), so the review re-runs
 	// even on a committed tree (joshuafolkken/kit#4221).
 	is_review_stale?: boolean
+	// The tree holds uncommitted work, which the sync stage commits locally before it merges.
+	is_dirty?: boolean
 }
 
 const RECORD_PREFIX = 'josh-ship-stages-'
@@ -57,6 +59,9 @@ const WORD_SEPARATOR = ' '
 const STARTED_SEPARATOR = ','
 const STARTED_INDEX = 3
 const WORD_COUNT = STARTED_INDEX + 1
+// The reason a stage ran or was skipped follows the words, behind a separator no word holds, so the
+// word readers below read the line as before.
+const REASON_SEPARATOR = ' | '
 
 // `started` lists the stages the current attempt started, kept across a supervisor that ended without a
 // stop so its successor's lines still carry them. `is_merge_waiting` is set only while `josh followup`
@@ -164,19 +169,23 @@ function is_shipped(state: ShipState): boolean {
 	return state.is_committed && state.is_pushed
 }
 
+// A lane child's `run:review` commits and pushes before the ship runs (joshuafolkken/kit#4907), so a
+// commit or a push is a stage's output only beside the ship's own record of that stage.
 const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => boolean> = {
 	// The preflight 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 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 — unless the issue changed since.
-	[STAGE.REVIEW]: (_done, state) =>
-		state.is_merged || (state.is_committed && state.is_review_stale !== true),
-	[STAGE.GATE]: (_done, state) => state.is_merged || state.is_committed,
-	// The merge of the default branch before the commit: once committed, a
-	// conflicting pull request is the followup's to merge again.
-	[STAGE.SYNC]: (_done, state) => state.is_merged || state.is_committed,
+	// its output; a resumed commit stage still asks `git -y`'s own preflight.
+	[STAGE.PREFLIGHT]: (done, state) =>
+		state.is_merged || (done.has(STAGE.PREFLIGHT) && state.is_committed),
+	// The sync stage commits locally before the review round and the gate, without pushing
+	// (`run-ship-sync.ts`), so a commit is neither's output: a pushed one on a clean tree is, as only the
+	// commit stage after the gate pushes — unless the issue changed since.
+	[STAGE.REVIEW]: (done, state) =>
+		state.is_merged ||
+		(done.has(STAGE.REVIEW) && is_shipped(state) && state.is_review_stale !== true),
+	[STAGE.GATE]: (done, state) => state.is_merged || (done.has(STAGE.GATE) && is_shipped(state)),
+	// The merge of the default branch before the gate: once pushed, a default branch that
+	// moved is the followup's to merge again.
+	[STAGE.SYNC]: (done, state) => state.is_merged || (done.has(STAGE.SYNC) && is_shipped(state)),
 	[STAGE.COMMIT]: (done, state) => state.is_merged || (done.has(STAGE.COMMIT) && is_shipped(state)),
 	// The round-2 pass reads the pushed fix delta, so its record is honored only
 	// while that push still stands — new work pushed on top reruns it.
@@ -231,9 +240,32 @@ function event_text(
 	return full.join(WORD_SEPARATOR)
 }
 
+// A line `event_text` wrote, with why its stage ran or was skipped after it (joshuafolkken/kit#5296).
+function with_reason(text: string, reason: string | undefined): string {
+	return reason === undefined ? text : `${text}${REASON_SEPARATOR}${reason}`
+}
+
+function words_part(text: string): string {
+	return text.split(REASON_SEPARATOR, 1)[0] ?? ''
+}
+
 // The stages a line says its attempt has started, `undefined` for a three-word line.
 function started_of(text: string): ReadonlyArray<string> | undefined {
-	return text.split(WORD_SEPARATOR, WORD_COUNT)[STARTED_INDEX]?.split(STARTED_SEPARATOR)
+	return words_part(text).split(WORD_SEPARATOR, WORD_COUNT)[STARTED_INDEX]?.split(STARTED_SEPARATOR)
+}
+
+// The stage word and the phase word of a line `event_text` wrote, `''` where the line has none.
+function words_of(text: string): { stage: string; phase: string } {
+	const [, stage = '', phase = ''] = words_part(text).split(WORD_SEPARATOR, WORD_COUNT)
+
+	return { stage, phase }
+}
+
+// Why the stage ran or was skipped, `undefined` for a line that carries no reason.
+function reason_of(text: string): string | undefined {
+	const at = text.indexOf(REASON_SEPARATOR)
+
+	return at === -1 ? undefined : text.slice(at + REASON_SEPARATOR.length)
 }
 
 // A stop on a merge git could not finish is named `conflict` rather than by the stage it happened in,
@@ -254,6 +286,7 @@ const run_ship_stage = {
 	end_attempt,
 	event_text,
 	is_done,
+	is_shipped,
 	mark_done,
 	mark_merge_waiting,
 	mark_place_waiting,
@@ -262,8 +295,11 @@ const run_ship_stage = {
 	read_merge_waiting,
 	read_place_waiting,
 	read_started,
+	reason_of,
 	record_path,
 	started_of,
+	with_reason,
+	words_of,
 	stop_reason,
 }
 

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

@@ -1,6 +1,7 @@
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { run_ship } from './run-ship'
 import { run_ship_body_draft } from './run-ship-body-draft'
+import { run_ship_lap } from './run-ship-lap'
 import { run_ship_preflight } from './run-ship-preflight'
 import { run_ship_probe } from './run-ship-probe'
 import { run_ship_review_steps } from './run-ship-review-steps'
@@ -23,6 +24,8 @@ interface ShipArguments {
 	cites: ReadonlyArray<string>
 	is_review: boolean
 	is_detach: boolean
+	// `--unpinned-ok "<reason>"` as given, forwarded to round 1's `run:review` alone; empty when absent.
+	unpinned_ok: ReadonlyArray<string>
 }
 
 interface Step {
@@ -65,7 +68,21 @@ async function gate_stage(): Promise<StepResult> {
 const SYNC_STEP: Step = {
 	stage: STAGE.SYNC,
 	header: run_ship.SYNC_HEADER,
-	run: async (args) => await run_ship_sync.sync_stage(args.number),
+	run: async (args, state) =>
+		await run_ship_sync.sync_stage(args.number, args.title, state.is_dirty === true),
+}
+
+// A default branch that moved since the sync stage is merged and gated again before the push
+// (`run_ship_sync.catch_up`, joshuafolkken/kit#4825). A resumed ship with nothing left to push leaves
+// that to the followup, which pushes what it merges; a pushed branch with new work still catches up.
+async function commit_stage(args: ShipArguments, state: ShipState): Promise<StepResult> {
+	const stop = run_ship_stage.is_shipped(state) ? undefined : await run_ship_sync.catch_up()
+
+	if (stop !== undefined) return stop
+
+	const argv = ['git', '-y', ...run_ship_stage.commit_flags(state), ...args.body, args.title]
+
+	return await run_ship_lap.timed(run_ship_lap.STEP.COMMIT, async () => await josh(argv))
 }
 
 // The gate before the commit, the commit/push/PR before the merge. The gate meets the scoped pair
@@ -81,8 +98,7 @@ const COMMIT_STEPS: ReadonlyArray<Step> = [
 	{
 		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]),
+		run: async (args, state) => await commit_stage(args, state),
 	},
 ]
 
@@ -133,7 +149,11 @@ const REVIEW_STEP: Step = {
 	stage: STAGE.REVIEW,
 	header: run_ship.REVIEW_HEADER,
 	run: async (args, state) =>
-		await run_ship_review_steps.review_stage(args.number, state.is_review_stale === true),
+		await run_ship_review_steps.review_stage(
+			args.number,
+			state.is_review_stale === true,
+			args.unpinned_ok,
+		),
 }
 const ROUND_TWO_STEP: Step = {
 	stage: STAGE.ROUND_TWO,

package/scripts/run/ship/run-ship-stop-cause.ts

@@ -1,6 +1,9 @@
 import { api_auth } from '#scripts/agent/api-auth'
+import { UNREADABLE_COMMENTS_STOP } from '#scripts/gh/git-gh-comments-unreadable'
+import { gh_retry } from '#scripts/gh/git-gh-retry'
 import { NO_CHECKS_MESSAGE } from '#scripts/gh/git-pr-checks-watch'
-import type { StopRecord } from '#scripts/lane/lane-ledger'
+import { git_error } from '#scripts/git/git-error'
+import type { StopRecord } from '#scripts/lane/lane-ledger-schema'
 import { run_ship_review, type StopFinding } from './run-ship-review'
 import { run_ship_stage, type Stage } from './run-ship-stage'
 
@@ -39,6 +42,7 @@ const INFRA_STAGES: ReadonlySet<Stage> = new Set([
 const INFRA_PATTERNS: ReadonlyArray<RegExp> = [
 	/rate limit/iu,
 	new RegExp(NO_CHECKS_MESSAGE, 'u'),
+	new RegExp(UNREADABLE_COMMENTS_STOP, 'u'),
 	/\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND)\b/u,
 	/socket hang up/iu,
 	/could not resolve host/iu,
@@ -84,6 +88,43 @@ function infra_text({ body, out = body }: StoppedOutput): string {
 	return out
 }
 
+const FAILURE_LINE = new RegExp(`^${git_error.FAILURE_PREFIX} `, 'gmu')
+const REPORTED_LINE = new RegExp(
+	`^(?:${git_error.FAILURE_PREFIX}|${git_error.DETAILS_PREFIX}) (?<message>.*)$`,
+	'gmu',
+)
+
+// The failure the stage ended on — the last `❌ Error:` line — and the cause logged under it: a caller
+// that wraps a spent request (a merge whose read-back failed too, a timed-out exec) ends on its own
+// message, with the request's beneath.
+function final_failures(body: string): ReadonlyArray<string> {
+	const last = [...body.matchAll(FAILURE_LINE)].at(-1)
+	if (last === undefined) return []
+
+	return [...body.slice(last.index).matchAll(REPORTED_LINE)].map(
+		({ groups }) => groups?.['message'] ?? '',
+	)
+}
+
+// A gh request transient to its last attempt notes so on stderr — gh's own transient verdict, never a
+// second list of its errors (joshuafolkken/kit#5052). A caller may catch it and stop later on a red
+// check, so the note counts only when it names the failure the stage ended on, or that failure's cause.
+function is_spent_stop(body: string): boolean {
+	return final_failures(body).some((message) => body.includes(gh_retry.spent_note(message)))
+}
+
+function is_infra_stop(failed: StoppedOutput): boolean {
+	return is_infra(infra_text(failed)) || is_spent_stop(failed.body)
+}
+
+// A gate an infrastructure stage ran itself tags its red as a check: its output is test output, where
+// a title naming a rate limit is no outage (joshuafolkken/kit#4825).
+function stage_cause(stage: Stage, failed: StoppedOutput): Cause {
+	if (failed.cause === CAUSE.CHECK || !INFRA_STAGES.has(stage)) return CAUSE.CHECK
+
+	return is_infra_stop(failed) ? CAUSE.INFRA : CAUSE.CHECK
+}
+
 function cause_of(stage: Stage, failed: StoppedOutput): Cause {
 	const { body, conflicts, cause } = failed
 	const reason = run_ship_stage.stop_reason(stage, conflicts)
@@ -91,7 +132,7 @@ function cause_of(stage: Stage, failed: StoppedOutput): Cause {
 	if (reason === run_ship_stage.CONFLICT) return CAUSE.CONFLICT
 	if (is_review(stage)) return review_cause(body, cause)
 
-	return INFRA_STAGES.has(stage) && is_infra(infra_text(failed)) ? CAUSE.INFRA : CAUSE.CHECK
+	return stage_cause(stage, failed)
 }
 
 // Whether a finding decided the stop — false on any other stop, and on a review stop no finding decided

package/scripts/run/ship/run-ship-stop-context.ts

@@ -2,9 +2,11 @@ import { stripVTControlCharacters } from 'node:util'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { changed_paths } from '#scripts/git/changed-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { review_prior_findings } from '#scripts/review/review-prior-findings'
 import { z } from 'zod'
 import { run_ship_next } from './run-ship-next'
 import { run_ship_probe } from './run-ship-probe'
+import type { StopFinding } from './run-ship-review'
 
 // What a relaunched lane child needs in front of it to fix a stopped ship: the tail of the failed
 // stage's output — a red check, or the High/Medium findings a review stage reports — and the branch's
@@ -14,6 +16,9 @@ import { run_ship_probe } from './run-ship-probe'
 // **Both are bounded**, so a long gate log never becomes the whole prompt. The tail is kept because a
 // check reports its verdict last; the lines left out go to a file whose path and line range the prompt
 // names, so nothing is lost and the session reads only the range it needs.
+//
+// **A review stop also carries the lane's earlier findings on the files it cites** (joshuafolkken/kit#4780),
+// so the fix meets the constraint an earlier round set on the same line rather than breaking it.
 
 const EXCERPT_LINE_LIMIT = 40
 const EXCERPT_LINE_WIDTH = 240
@@ -33,6 +38,7 @@ const stop_context_schema = z
 		omitted: omitted_schema.optional(),
 		changed: z.array(z.string()).readonly().optional(),
 		more_changed: z.number().int(),
+		prior: z.array(z.string()).readonly().optional(),
 	})
 	.strict()
 
@@ -121,8 +127,18 @@ async function changed_of(): Promise<Pick<StopContext, 'changed' | 'more_changed
 	}
 }
 
-async function build(issue: string, output: string): Promise<StopContext> {
-	return { ...(await excerpt_of(issue, output)), ...(await changed_of()) }
+async function build(
+	issue: string,
+	output: string,
+	findings: ReadonlyArray<StopFinding> = [],
+): Promise<StopContext> {
+	const prior = review_prior_findings.on_files(issue, findings)
+
+	return {
+		...(await excerpt_of(issue, output)),
+		...(await changed_of()),
+		...(prior.length > 0 && { prior }),
+	}
 }
 
 function has_excerpt(context: StopContext | undefined): boolean {
@@ -168,17 +184,12 @@ function changed_text(context: StopContext): string {
 	return `Changed files on the branch: ${context.changed.join(', ')}${more}.`
 }
 
-// The block the ship-stop prompt carries between the next command and the closing invocation.
-//
-// **It fits the `budget` the prompt leaves it** — the prompt is one argv element, refused past
-// `MAX_VALUE_LENGTH` (joshuafolkken/kit#3964) — by dropping the excerpt's head first, since a check
-// reports its verdict last; the tail line always stays.
-function describe(
-	issue: string,
-	context: StopContext,
-	budget: number = agent_role_profile.MAX_VALUE_LENGTH,
-): string {
-	const changed = changed_text(context)
+function trailer_text(context: StopContext): string {
+	return [changed_text(context), ...review_prior_findings.fix_lines(context.prior)].join(LINE_BREAK)
+}
+
+function fitted_block(issue: string, context: StopContext, budget: number): string {
+	const changed = trailer_text(context)
 
 	if (!has_excerpt(context)) return changed
 
@@ -193,6 +204,32 @@ function describe(
 	return block
 }
 
+function has_prior(context: StopContext): boolean {
+	return context.prior !== undefined && context.prior.length > 0
+}
+
+// The block the ship-stop prompt carries between the next command and the closing invocation.
+//
+// **It fits the `budget` the prompt leaves it** — the prompt is one argv element, kept within
+// `MAX_VALUE_LENGTH` (joshuafolkken/kit#3964), well under the launch gate's prompt cap — by dropping
+// the excerpt's head first, since a check
+// reports its verdict last; the tail line always stays. Past that, the earlier findings go oldest first.
+function describe(
+	issue: string,
+	context: StopContext,
+	budget: number = agent_role_profile.MAX_VALUE_LENGTH,
+): string {
+	let fitted = context
+	let block = fitted_block(issue, fitted, budget)
+
+	while (block.length > budget && has_prior(fitted)) {
+		fitted = { ...fitted, prior: fitted.prior?.slice(1) }
+		block = fitted_block(issue, fitted, budget)
+	}
+
+	return block
+}
+
 const run_ship_stop_context = {
 	CHANGED_PATH_LIMIT,
 	EXCERPT_LINE_LIMIT,