@joshuafolkken/kit 1.1240.0 → 1.1370.0

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

@@ -9,10 +9,11 @@ import { review_record } from '#scripts/review/review-record'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
 import { run_ship_scoped, type Phase } from './run-ship-scoped'
+import type { StepResult } from './run-ship-sync'
 
-// 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
-// gate. Each step is the existing command or mechanism, composed rather than cloned:
+// The side effects of `josh ship --review`: the round-1 review — open, launch, join, attest and
+// record — run by the supervisor beside the gate rather than across agent turns. Each step is the
+// existing command or mechanism, composed rather than cloned:
 //
 // 1. `run:review` starts the gate detached and mints the brief — the nonce `review:attest` checks.
 // 2. the reviewer is launched the way `run:wake` launches a session — `agent_argv` under the reviewer
@@ -20,14 +21,14 @@ import { run_ship_scoped, type Phase } from './run-ship-scoped'
 // 3. `run:review --join` blocks a verdict over a red gate; `review:attest --check` refuses a review
 //    that read another checkout; `review:record` writes the round the merge gate reads.
 //
-// **Round 1's local fixes and round 2 stay inside the supervisor** (joshuafolkken/kit#2489). A round-1
+// **Round 1's local fixes and round 2 stay inside the supervisor**. A round-1
 // reviewer that fixed its local Mediums in place changed the tree the background gate read, so that
 // join drains the gate rather than judging it — the ship's gate stage re-runs on the fixed tree. After
 // the commit, `round_two_stage` asks `review:round2 --round-1-closed` whether the fix delta owes a
 // second round, and on `required` runs it through the same commands the chain does: the scoped pair
 // `review:brief` requires, `review:brief --round 2`, a fresh reviewer session, attest and record.
 //
-// **A precondition the supervisor can meet itself is met, not stopped on** (joshuafolkken/kit#2500).
+// **A precondition the supervisor can meet itself is met, not stopped on**.
 // The scoped pair `run:review` and the local gate refuse without is run in place when this tree has no
 // green record, and a round-1 fix is counted only once that pair is green on the fixed tree.
 //
@@ -43,14 +44,19 @@ const ATTEST_CHECK = ['review:attest', '--check']
 const ROUND_TWO_DECISION = ['review:round2', '--round-1-closed']
 const ROUND_TWO_BRIEF = ['review:brief', '--round', '2']
 const ROUND_TWO_REQUIRED = 'required'
+const ROUND_ONE = '1'
+const ROUND_TWO = '2'
+const COMMENT_FLAG = '--comment'
+
+type Round = typeof ROUND_ONE | typeof ROUND_TWO
 const FIXED_JOIN_NOTE =
 	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate re-runs once the tree is fixed.'
 const ROUND_TWO_SKIPPED_NOTE = 'round 2 not due — nothing left to verify; shipping on.'
 const ROUND_ONE_RECORDED_NOTE =
 	'round 1 already recorded for this issue — not reviewed again; the gate reads the fixed tree and round 2 decides after the commit.'
 
-// 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).
+// The scoped pair's precondition, met by the supervisor itself rather than stopped on,
+// single-sourced with the preflight and gate stages.
 const { run_phases, scoped_pair } = run_ship_scoped
 
 type PromptOf = (brief_path: string, findings_path: string) => string
@@ -92,7 +98,7 @@ async function run_session(
 	prompt: string,
 	log_path: string,
 	issue: string,
-	round: '1' | '2',
+	round: Round,
 ): Promise<JoshResult> {
 	const built = agent_argv.resolve_in(prompt, agent_role_profile.REVIEWER, PROJECT_ROOT)
 	if (built.kind === 'rejected') return failure(`reviewer profile rejected: ${built.note}`)
@@ -112,7 +118,7 @@ async function launch_reviewer(
 	brief: string,
 	prompt_of: PromptOf,
 	issue: string,
-	round: '1' | '2',
+	round: Round,
 ): Promise<JoshResult> {
 	const target = paths()
 
@@ -130,7 +136,7 @@ function current_verdict(): ReturnType<typeof run_ship_review.read_verdict> {
 // tree before the fixes, so its verdict describes a tree that no longer exists. The join still ran to
 // its end, so the gate stage that follows never races it. Any fix drains it, not only a round whose
 // every finding was fixed — a partial fix moved the tree just the same, and the round then stops on its
-// unfixed finding at the record rather than on a `Gate RED` the gate never earned (joshuafolkken/kit#2961).
+// unfixed finding at the record rather than on a `Gate RED` the gate never earned.
 async function join_gate(): Promise<JoshResult> {
 	const joined = await josh([RUN_REVIEW, '--join'])
 
@@ -142,19 +148,29 @@ async function join_gate(): Promise<JoshResult> {
 	return { code: SUCCESS_EXIT_CODE, out: joined.out }
 }
 
+// **A passing round 2 is recorded on the issue, not in the tree**: it ran after the commit and reads
+// only, so no commit of the run's follows it, and a line appended now would be pushed onto the open
+// pull request by `pnpm josh followup` — restarting the CI the round ran beside. A blocking round 2
+// keeps the tree: the fix it stops for is pushed anyway, and carries the lines.
+function record_flags(round: Round, outcome: RoundOutcome): ReadonlyArray<string> {
+	return round === ROUND_TWO && outcome.is_passing ? [COMMENT_FLAG] : []
+}
+
 async function record_and_route(
 	issue: string,
+	round: Round,
 	outcome_of: (verdict: ScoredVerdict) => RoundOutcome,
 ): Promise<JoshResult> {
 	const verdict = current_verdict()
 
 	if (verdict.kind === run_ship_review.VERDICT.INVALID) return failure(verdict.note)
 
-	const recorded = await josh(['review:record', '--issue', issue, ...verdict.specs])
+	const outcome = outcome_of(verdict)
+	const flags = record_flags(round, outcome)
+	const recorded = await josh(['review:record', '--issue', issue, ...flags, ...verdict.specs])
 
 	if (recorded.code !== SUCCESS_EXIT_CODE) return recorded
 
-	const outcome = outcome_of(verdict)
 	const out = [...verdict.report, outcome.note].join('\n')
 
 	return outcome.is_passing ? { code: SUCCESS_EXIT_CODE, out } : failure(out)
@@ -165,7 +181,7 @@ function reviewed(
 	open: ReadonlyArray<string>,
 	prompt_of: PromptOf,
 	issue: string,
-	round: '1' | '2',
+	round: Round,
 ): ReadonlyArray<Phase> {
 	const opened = { brief: '' }
 
@@ -189,26 +205,31 @@ async function round_one_record(issue: string): Promise<JoshResult> {
 	const checked = is_fixed ? await scoped_pair() : undefined
 	const is_verified = checked === undefined || checked.code === SUCCESS_EXIT_CODE
 
-	return await record_and_route(issue, (verdict) =>
+	return await record_and_route(issue, ROUND_ONE, (verdict) =>
 		is_verified ? run_ship_review.round_one_outcome(verdict) : run_ship_review.UNVERIFIED_OUTCOME,
 	)
 }
 
+// A round that had nothing to review: it passes, and the ship does not time it as a review that ran.
+function skipped(out: string): StepResult {
+	return { code: SUCCESS_EXIT_CODE, out, is_skipped: true }
+}
+
 // The round-1 review, beside the gate: scoped pair → open → review → join → attest → record, stopping
 // at the first that did not pass.
 //
-// **A recorded round 1 is not run again** (joshuafolkken/kit#2964). A ship relaunched with `--review`
+// **A recorded round 1 is not run again**. A ship relaunched with `--review`
 // after a round-1 stop would otherwise review the whole change a second time as round 1 — a new Medium
 // there stops it again, and round 2 after the commit makes a third. The fix delta is round 2's to
 // verify, and `round_two_stage` asks whether it is due after the commit.
-async function review_stage(issue: string): Promise<JoshResult> {
+async function review_stage(issue: string): Promise<StepResult> {
 	const recorded = await review_record.check(Number(issue))
 
-	if (recorded.status === 'ok') return { code: SUCCESS_EXIT_CODE, out: ROUND_ONE_RECORDED_NOTE }
+	if (recorded.status === 'ok') return skipped(ROUND_ONE_RECORDED_NOTE)
 
 	return await run_phases([
 		scoped_pair,
-		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt, issue, '1'),
+		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt, issue, ROUND_ONE),
 		join_gate,
 		async () => await josh(ATTEST_CHECK),
 		async () => await round_one_record(issue),
@@ -217,21 +238,19 @@ async function review_stage(issue: string): Promise<JoshResult> {
 
 // The round-2 verification pass, after the commit so it runs beside CI: due only when the round-1 fix
 // delta says so, then scoped pair → brief → fresh reviewer → attest → record.
-async function round_two_stage(issue: string): Promise<JoshResult> {
+async function round_two_stage(issue: string): Promise<StepResult> {
 	const decision = await josh(ROUND_TWO_DECISION)
 	const answer = decision.out.trim()
 
 	if (decision.code !== SUCCESS_EXIT_CODE) return decision
 
-	if (answer !== ROUND_TWO_REQUIRED) {
-		return { code: SUCCESS_EXIT_CODE, out: `${answer}\n${ROUND_TWO_SKIPPED_NOTE}` }
-	}
+	if (answer !== ROUND_TWO_REQUIRED) return skipped(`${answer}\n${ROUND_TWO_SKIPPED_NOTE}`)
 
 	return await run_phases([
 		scoped_pair,
-		...reviewed(ROUND_TWO_BRIEF, run_ship_review.verification_prompt, issue, '2'),
+		...reviewed(ROUND_TWO_BRIEF, run_ship_review.verification_prompt, issue, ROUND_TWO),
 		async () => await josh(ATTEST_CHECK),
-		async () => await record_and_route(issue, run_ship_review.round_two_outcome),
+		async () => await record_and_route(issue, ROUND_TWO, run_ship_review.round_two_outcome),
 	])
 }
 

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

@@ -1,18 +1,17 @@
 import { review_finding_ledger } from '#scripts/review/review-finding-ledger'
 import { review_record_cli } from '#scripts/review/review-record-cli'
 
-// The pure half of `josh ship --review` (joshuafolkken/kit#2427): the one-line prompts the supervised
-// reviewers are launched with, the verdict read back off the findings file each writes, and where that
-// verdict routes the ship. Kept apart from the launch and the joins (`run-ship-review-steps.ts`) the way
-// `run-review.ts` is kept apart from `run-review-steps.ts`, so every branch is pinned without a session
-// ever starting.
+// The pure half of `josh ship --review`: the one-line prompts the supervised reviewers are launched
+// with, the verdict read back off the findings file each writes, and where that verdict routes the
+// ship. Kept apart from the launch and the joins (`run-ship-review-steps.ts`) the way `run-review.ts`
+// is kept apart from `run-review-steps.ts`, so every branch is pinned without a session ever starting.
 //
 // **The reviewer is the one the chain already runs.** Its prompt hands it the brief `run:review`
 // printed — the same level, rubric, checkout and `review:attest` nonce a `/code-review` subagent was
 // given — and asks only that the findings also be written in the `review:record` grammar, so the
 // supervisor records and routes them without an agent reading the prose.
 //
-// **Round 1 fixes what is local; round 2 only reads** (joshuafolkken/kit#2489). The round-1 reviewer
+// **Round 1 fixes what is local; round 2 only reads**. The round-1 reviewer
 // applies a Medium whose fix is small and local — the "small, local asks" `chain-rule.md` names — and
 // marks that finding `fixed`, so the supervisor carries the ship through the gate, the commit and a
 // round-2 verification pass instead of handing a lane child back for a fix it could not make. A High is
@@ -24,7 +23,7 @@ const HIGH = 'high'
 const MEDIUM = 'medium'
 const FIXED_PREFIX = 'fixed '
 // What a finding line carries after its spec: one sentence saying what is wrong, so a stopped ship's
-// log tells the resumed lane child the defect rather than only its location (joshuafolkken/kit#3159).
+// log tells the resumed lane child the defect rather than only its location.
 const DESCRIPTION_SEPARATOR = ' — '
 // Where the spec ends on read: a reviewer that types the dash as `-`, `--` or `–` still ends it there,
 // so its sentence never lands in the ledger's file field.
@@ -175,18 +174,17 @@ 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.
+// Whether a findings file records a clean round 1. 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
 }
 
 // Whether the reviewer edited the tree — any finding marked fixed, whether or not another one still
-// blocks (joshuafolkken/kit#2961). A partial fix moves the tree the background gate read as surely as a
-// full one, so the join reads it red either way; keyed off the verdict kind instead, a round that fixed
-// one Medium and left another stopped at a misleading `Gate RED` before its own blocking note.
+// blocks. A partial fix moves the tree the background gate read as surely as a full one, so the join
+// reads it red either way.
 function has_fixes(text: string | undefined): boolean {
 	if (text === undefined) return false
 

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

@@ -1,11 +1,12 @@
+import { gate_skip } from '#scripts/gate/gate-skip'
 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.
+// 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
+// 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
@@ -40,7 +41,7 @@ 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 (joshuafolkken/kit#3307), so both leave the record the pre-push hook reuses.
+// 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,
@@ -48,7 +49,15 @@ async function scoped_gate(): Promise<JoshResult> {
 	])
 }
 
-const run_ship_scoped = { run_phases, scoped_gate, scoped_pair }
+// Whether `josh gate` would only reuse this tree's green record: the gate's own reuse test rather than
+// a second copy of it, so the ship calls a gate stage a reuse on exactly the trees the gate skips.
+async function is_gate_green(): Promise<boolean> {
+	const tree = await gate_tree.read_gate_tree()
+
+	return gate_skip.reusable_green_gate(tree.files, tree.base) !== undefined
+}
+
+const run_ship_scoped = { is_gate_green, run_phases, scoped_gate, scoped_pair }
 
 export type { Phase }
 export { run_ship_scoped }

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

@@ -1,10 +1,11 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
-// `josh ship`'s durable stage record, and the decision of which stage a resumed ship may pass over
-// (joshuafolkken/kit#2426). The composite used to be a straight line with no memory: a ship that died
-// after its push re-ran the gate, and nothing checked whether the commit, the push or the merge had
-// already happened.
+// `josh ship`'s durable stage record, and the decision of which stage a resumed ship may pass over,
+// so a ship that died mid-way neither re-runs what already happened nor commits, pushes or merges
+// twice.
 //
 // **The record is a hint; the repository's actual state is the authority.** A record can be lost — a
 // temp directory wiped — or outlived by the tree it describes, when new work was committed after it
@@ -49,8 +50,21 @@ const RECORD_PREFIX = 'josh-ship-stages-'
 const RECORD_SEPARATOR = '-'
 const SKIP_COMMIT_FLAG = '--skip-commit'
 const SKIP_PUSH_FLAG = '--skip-push'
+const WORD_SEPARATOR = ' '
+const STARTED_SEPARATOR = ','
+const STARTED_INDEX = 3
+const WORD_COUNT = STARTED_INDEX + 1
 
-const record_schema = z.object({ done: z.array(z.string()) })
+// `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.
+const record_schema = z.object({
+	done: z.array(z.string()),
+	started: z.array(z.string()).default([]),
+})
+
+type ShipRecord = z.infer<typeof record_schema>
+
+const EMPTY_RECORD: ShipRecord = { done: [], started: [] }
 
 // Keyed on the repository and the issue: every lane of one repository shares the common git directory,
 // and two issues shipping from two lanes keep two records.
@@ -58,26 +72,44 @@ function record_path(repository: string, issue: string): string {
 	return stamp_file.stamp_path(`${RECORD_PREFIX}${issue}${RECORD_SEPARATOR}`, repository)
 }
 
-function parse_done(raw: string): ReadonlySet<string> {
-	try {
-		return new Set(record_schema.parse(JSON.parse(raw)).done)
-	} catch {
-		return new Set()
-	}
+function parse_record(raw: string): ShipRecord {
+	return json_value.parse_with(raw, record_schema) ?? EMPTY_RECORD
 }
 
-// The stages the record says completed. An absent, planted or malformed record reads as none — the
-// state decides from there, so "no record" is always the safe answer.
-function read_done(target: string): ReadonlySet<string> {
+// An absent, planted or malformed record reads as empty — the state decides from there, so "no
+// record" is always the safe answer.
+function read_record(target: string): ShipRecord {
 	const raw = stamp_file.read_stamp_text(target)
 
-	return raw === undefined ? new Set() : parse_done(raw)
+	return raw === undefined ? EMPTY_RECORD : parse_record(raw)
+}
+
+// The stages the record says completed.
+function read_done(target: string): ReadonlySet<string> {
+	return new Set(read_record(target).done)
 }
 
 function mark_done(target: string, stage: Stage): void {
-	const done = new Set([...read_done(target), stage])
+	const record = read_record(target)
+
+	stamp_file.replace_stamp(target, { ...record, done: [...new Set([...record.done, stage])] })
+}
+
+// The stages the current attempt has started, in the order it started them.
+function read_started(target: string): ReadonlyArray<string> {
+	return read_record(target).started
+}
+
+function mark_started(target: string, stage: Stage): void {
+	const record = read_record(target)
 
-	stamp_file.replace_stamp(target, { done: [...done] })
+	stamp_file.replace_stamp(target, { ...record, started: [...new Set([...record.started, stage])] })
+}
+
+// A `ship-stop` ends the attempt on the board (`run-board-phase.ts`), so the next attempt lists afresh
+// while the completed stages stay recorded.
+function end_attempt(target: string): void {
+	stamp_file.replace_stamp(target, { ...read_record(target), started: [] })
 }
 
 // Removed once the report stage completes, so a later ship of the same issue starts from the preflight.
@@ -92,19 +124,19 @@ 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
+	// 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 (joshuafolkken/kit#2427) precedes the commit, so a commit is its output as it
+	// 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.
 	[STAGE.REVIEW]: (_done, state) => state.is_merged || state.is_committed,
 	[STAGE.GATE]: (_done, state) => state.is_merged || state.is_committed,
-	// The merge of the default branch before the commit (joshuafolkken/kit#3221): once committed, a
+	// 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,
 	[STAGE.COMMIT]: (done, state) => state.is_merged || (done.has(STAGE.COMMIT) && is_shipped(state)),
-	// The round-2 pass (joshuafolkken/kit#2489) reads the pushed fix delta, so its record is honored only
+	// 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.
 	[STAGE.ROUND_TWO]: (done, state) =>
 		state.is_merged || (done.has(STAGE.ROUND_TWO) && is_shipped(state)),
@@ -115,7 +147,7 @@ const DONE_BY: Record<Stage, (done: ReadonlySet<string>, state: ShipState) => bo
 	[STAGE.REPORT]: (done) => done.has(STAGE.REPORT),
 }
 
-// A supplied PR body is work only the commit stage delivers (joshuafolkken/kit#2446): a rerun carrying
+// A supplied PR body is work only the commit stage delivers: a rerun carrying
 // the live-execution evidence a refused `followup` asked for reruns `git -y`, whose skip flags leave the
 // commit and push alone while the body reaches the already-open pull request.
 function is_done(
@@ -138,12 +170,30 @@ function commit_flags(state: ShipState): ReadonlyArray<string> {
 	return state.is_pushed ? [SKIP_COMMIT_FLAG, SKIP_PUSH_FLAG] : [SKIP_COMMIT_FLAG]
 }
 
-function event_text(issue: string, stage: Stage, phase: Phase): string {
-	return `#${issue} ${stage} ${phase}`
+// **The newest line carries the attempt's history**: a fourth word lists every
+// stage the attempt has started, so the one line per issue a stream full of positions keeps still
+// draws the whole track. A line with no started stage keeps the three-word form.
+function event_text(
+	issue: string,
+	stage: Stage,
+	phase: Phase,
+	started: ReadonlyArray<string> = [],
+): string {
+	const words = [issue_cite.plain(issue), stage, phase]
+	const listed = [...new Set(started)].join(STARTED_SEPARATOR)
+
+	const full = started.length > 0 ? [...words, listed] : words
+
+	return full.join(WORD_SEPARATOR)
+}
+
+// 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)
 }
 
-// A stop on a merge git could not finish is named `conflict` rather than by the stage it happened in
-// (joshuafolkken/kit#3221), so the event stream reads the cause without anyone opening the report.
+// A stop on a merge git could not finish is named `conflict` rather than by the stage it happened in,
+// so the event stream reads the cause without anyone opening the report.
 const CONFLICT = 'conflict'
 
 function stop_reason(stage: Stage, conflicts: ReadonlyArray<string> = []): string {
@@ -155,11 +205,15 @@ const run_ship_stage = {
 	STAGE,
 	clear,
 	commit_flags,
+	end_attempt,
 	event_text,
 	is_done,
 	mark_done,
+	mark_started,
 	read_done,
+	read_started,
 	record_path,
+	started_of,
 	stop_reason,
 }
 

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

@@ -6,8 +6,8 @@ import { run_ship_scoped } from './run-ship-scoped'
 import { run_ship_stage, type ShipState, type Stage } from './run-ship-stage'
 import { run_ship_sync, type StepResult } from './run-ship-sync'
 
-// The stages `josh ship` runs, in the order a change ships (joshuafolkken/kit#2398), kept apart from the
-// chaining CLI so the order is read in one place.
+// The stages `josh ship` runs, in the order a change ships, kept apart from the chaining
+// CLI so the order is read in one place.
 
 const should_forward_stderr = true
 
@@ -34,8 +34,8 @@ async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
 	return await josh_command.josh_run(argv, should_forward_stderr)
 }
 
-// joshuafolkken/kit#2946: the pull request's preconditions and the scoped pair are asked first, so a
-// stop they would cause lands before the review and the gate rather than after them.
+// The pull request's preconditions and the scoped pair are asked first, so a stop they would cause
+// lands before the review and the gate rather than after them.
 const PREFLIGHT_STEP: Step = {
 	stage: STAGE.PREFLIGHT,
 	header: run_ship.PREFLIGHT_HEADER,
@@ -43,15 +43,25 @@ const PREFLIGHT_STEP: Step = {
 		await run_ship_preflight.stage({ title: args.title, body_path: args.body_path }),
 }
 
+// The gate stage. **A gate that only reused the tree's green record is not timed**: after `--review`
+// launched the gate itself, this stage ends in seconds without running a check, and those seconds
+// would pull the `gate` row `lane:stats` reads for `JOSH_LANE_LIMIT` toward zero. The record is asked
+// for before the stage runs — afterwards every green gate has one.
+async function gate_stage(): Promise<StepResult> {
+	const is_skipped = await run_ship_scoped.is_gate_green()
+	const result = await run_ship_scoped.scoped_gate()
+
+	return { ...result, is_skipped }
+}
+
 // The gate before the commit, the commit/push/PR before the merge. The gate meets the scoped pair
 // first: a round-1 reviewer may have edited the tree since the preflight, and `josh gate` refuses a tree
-// with no green record (joshuafolkken/kit#2946). The commit step carries the `--skip-*` flags a resumed
-// ship needs, so an existing commit or push is never made twice.
+// with no green record. The commit step carries the `--skip-*` flags a resumed ship needs, so an
+// existing commit or push is never made twice.
 const COMMIT_STEPS: ReadonlyArray<Step> = [
-	// joshuafolkken/kit#3221: the default branch merged again before the commit, so the pull request
-	// opens on a branch that is current; a clean merge goes on without waking anyone. It runs before the
-	// gate (joshuafolkken/kit#3307): a merge after it moved the merge base the gate's record pins, so the
-	// pre-push hook could never reuse that record and re-ran the whole unit suite on every merged ship.
+	// The default branch is merged again before the commit, so the pull request opens on a branch that
+	// is current; a clean merge goes on without waking anyone. It runs before the gate: a merge after it
+	// would move the merge base the gate's record pins, so the pre-push hook could not reuse that record.
 	{
 		stage: STAGE.SYNC,
 		header: run_ship.SYNC_HEADER,
@@ -60,7 +70,7 @@ const COMMIT_STEPS: ReadonlyArray<Step> = [
 	{
 		stage: STAGE.GATE,
 		header: run_ship.GATE_HEADER,
-		run: async () => await run_ship_scoped.scoped_gate(),
+		run: async () => await gate_stage(),
 	},
 	{
 		stage: STAGE.COMMIT,
@@ -84,11 +94,11 @@ const MERGE_STEPS: ReadonlyArray<Step> = [
 	},
 ]
 
-// `--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 unless the
-// sync stage between them merged the default branch and changed the tree. 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.
+// `--review` 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 unless the sync stage between them
+// merged the default branch and changed the tree. It also puts the round-2 pass between the commit
+// and the followup, 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,

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

@@ -1,9 +1,11 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+
 // The text a `josh ship` supervisor records when a stage stops, written and read in one place so the
-// retrospective's per-stage count never drifts from the writer (joshuafolkken/kit#3245).
+// retrospective's per-stage count never drifts from the writer.
 const STOP_PATTERN = /^#\d+ (\S+) failed — /u
 
 function format(issue: string, reason: string): string {
-	return `#${issue} ${reason} failed — pnpm josh ship --log ${issue}`
+	return `${issue_cite.plain(issue)} ${reason} failed — pnpm josh ship --log ${issue}`
 }
 
 function reason_of(text: string): string | undefined {

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

@@ -6,13 +6,11 @@ import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { error_text } from '#scripts/lib/error-message'
 import { run_ship_scoped } from './run-ship-scoped'
 
-// `josh ship` keeps the branch current with the default branch itself (joshuafolkken/kit#3221). The
-// lane merged it once, before the hand-off, and nothing merged it again while the pull request opened
-// and CI ran — so a default branch that moved meanwhile stopped the followup as `interrupted`, and a
-// relaunched session spent its first turns finding out that the cause was a conflict. Most of those
-// conflicts were not conflicts at all to git: merging the default branch again resolved them.
+// `josh ship` keeps the branch current with the default branch itself: a default branch that moves
+// while the pull request opens and CI runs would otherwise stop the followup as `interrupted`, though
+// merging the default branch again usually resolves it.
 //
-// So the merge happens twice more, mechanically: once before the commit (`sync_stage`), and once when
+// So the merge happens mechanically: once before the commit (`sync_stage`), and once when
 // the followup fails on a pull request GitHub reports `DIRTY` (`followup_stage`). Only a merge git
 // itself cannot finish stops the ship, and it stops as `conflict`, naming the unmerged paths so the
 // resumed session goes straight to them.
@@ -29,7 +27,10 @@ const CURRENT_SUFFIX = ' brings nothing in'
 const MERGED_PREFIX = 'merged '
 
 // A stage's result, plus the paths a stopped merge left unmerged — carried to the stop prompt.
+// `is_skipped` marks a stage that found nothing to do — a review round with nothing to review, a gate
+// that reused a green record — so its few seconds are not timed as a run of it.
 interface StepResult extends JoshResult {
+	is_skipped?: boolean
 	conflicts?: ReadonlyArray<string>
 }
 
@@ -63,7 +64,7 @@ function sync_note(outcome: Exclude<MergeOutcome, { kind: 'conflict' }>): string
 
 // A refusal does not stop the commit: the guard refuses only uncommitted work the default branch also
 // touches, and once that work is committed the followup merges again on a clean tree. A merge that changed
-// the tree is checked by the gate stage that follows (joshuafolkken/kit#3307), so the commit never carries
+// the tree is checked by the gate stage that follows, so the commit never carries
 // an unchecked merge and the gate's record names the merge base the push carries.
 async function sync_stage(): Promise<StepResult> {
 	const outcome = await merge_outcome()
@@ -84,7 +85,7 @@ async function is_conflicting(): Promise<boolean> {
 	}
 }
 
-// The merged tree is gated before it is pushed (joshuafolkken/kit#3307): the push then carries the tree
+// The merged tree is gated before it is pushed: the push then carries the tree
 // the gate's record describes, so the pre-push hook reuses it rather than re-running the unit suite.
 async function push_merged(title: string): Promise<StepResult | undefined> {
 	const gate = await run_ship_scoped.scoped_gate()