@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/run/run-watcher-hook.ts

@@ -1,14 +1,14 @@
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { json_value } from '#scripts/lib/json-value'
 import { run_progress_read } from '#scripts/run/progress/run-progress-read'
 import { z } from 'zod'
 import { run_watcher_guard } from './run-watcher-guard'
 
 // The `PreToolUse` adapter that turns `run_watcher_guard`'s verdict into a deny reason, so the guard
-// the CLI already carries is finally *called* on every tool call rather than left to prose asking the
-// run to call it (joshuafolkken/kit#2353). It is composed into `pretool-guard.ts` — the one PreToolUse
-// hook, kept one by joshuafolkken/kit#1930 — rather than added as a second `.claude/settings.json`
-// entry, so the consolidation invariant holds; the detection itself is unchanged.
+// the CLI already carries is *called* on every tool call rather than left to prose asking the run to
+// call it. It is composed into `pretool-guard.ts` — the one PreToolUse hook — rather than added as a
+// second `.claude/settings.json` entry, so the consolidation invariant holds.
 //
 // **It fires once per run, for the same reason every guard here stamps.** A stale watcher would other-
 // wise refuse *every* tool call, including the `pnpm josh run:progress --wait` that fixes it — a wedge.
@@ -24,13 +24,7 @@ const STAMP_PREFIX = 'josh-watcher-guard-'
 const payload_schema = z.object({ transcript_path: z.string().min(1) })
 
 function transcript_of(raw_payload: string): string | undefined {
-	try {
-		const parsed = payload_schema.safeParse(JSON.parse(raw_payload))
-
-		return parsed.success ? parsed.data.transcript_path : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw_payload, payload_schema)?.transcript_path
 }
 
 // The once-per-run arm: refuse only when nothing has been recorded yet, and record before returning so
@@ -56,7 +50,7 @@ function is_active(): boolean {
 
 // The guard's note when the watcher is stale and this call is the once-per-run one that refuses, or
 // `undefined` when the watcher is fresh (or the refusal was already spent this run). No session is asked
-// to relay the run's stream any more — the watch pane does (joshuafolkken/kit#2492).
+// to relay the run's stream — the watch pane does.
 async function stale_reason(transcript: string, now_ms: number): Promise<string | undefined> {
 	const result = await run_watcher_guard.check(await run_progress_read.live_target())
 

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

@@ -1,6 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
@@ -13,28 +15,27 @@ import { run_ship_return } from './run-ship-return'
 import { run_ship_stage, type Phase, type ShipState, type Stage } from './run-ship-stage'
 import { run_ship_steps, type ShipArguments, type Step } from './run-ship-steps'
 
-// `josh ship "<title> #<N>"` — one call for the fixed commit-to-report region a run ships a change on
-// (joshuafolkken/kit#2398). The loop used to spend a round trip each on `gate`, `git -y`, `followup`
-// and `run:tail`, re-billing a lane's full context every time; this runs the four internally and
-// prints one composite report, the same way `run:tail` folds the post-merge bookkeeping. Each step's
-// stderr is forwarded, so the reader still sees every explanation — a red check, a CI wait, a refusal —
-// the four would have printed on their own.
+// `josh ship "<title> #<N>"` — one call for the fixed commit-to-report region a run ships a change on.
+// It runs `gate`, `git -y`, `followup` and `run:tail` internally, so no round trip re-bills a lane's
+// full context, and prints one composite report, the same way `run:tail` folds the post-merge
+// bookkeeping. Each step's stderr is forwarded, so the reader still sees every explanation — a red
+// check, a CI wait, a refusal — the four would have printed on their own.
 //
 // It stops at the first failed step: the gate must be green before the commit, the commit before the
 // merge. The report ends at the failure and names the stopped step, so the run reads only that one.
 //
-// **Re-running it resumes rather than restarts** (joshuafolkken/kit#2426). Each stage's completion is
+// **Re-running it resumes rather than restarts**. Each stage's completion is
 // kept in a per-issue record, and the repository's actual state — committed, pushed, merged — is read
 // before the first stage, so a ship that died mid-way passes over what already happened and never
 // commits, pushes or merges twice. Each stage's start, success, failure or skip goes onto the run's
 // event stream. `run-ship-stage.ts` carries which stage may be passed over, and why the gate never is
 // on the record's word alone.
 //
-// **`--review` owns the round-1 review too** (joshuafolkken/kit#2427): a `review` stage in front of the
+// **`--review` owns the round-1 review too**: a `review` stage in front of the
 // gate launches the same-strength reviewer beside it and joins, attests and records the round without
 // an agent turn (`run-ship-review-steps.ts`); a High or Medium finding, or any failed join, stops there.
 //
-// **`--detach` hands the whole region to a supervisor that outlives the agent** (joshuafolkken/kit#2428):
+// **`--detach` hands the whole region to a supervisor that outlives the agent**:
 // the agent ends at the hand-off instead of relaunching itself for the gate, a supervised ship that stops
 // hands the stage back (`run-ship-return.ts`), and `--log <N>` prints the report it stopped on.
 //
@@ -54,13 +55,10 @@ const EXTRA_CITE_START = 1
 // The issue reference at the tail of the title — `git -y` and `followup` read the whole string, and
 // `run:tail` needs the number alone.
 const TRAILING_ISSUE_PATTERN = /#([1-9]\d*)\s*$/u
-// A follow-up citation passed as a trailing positional — a bare issue number, so a stray flag is
-// refused rather than forwarded to the wrong step.
-const CITE_PATTERN = /^[1-9]\d*$/u
 // Both body forms `followup` documents, forwarded verbatim: the inline `--notify-message` and the
 // shell-body-safe `--notify-message-file` a body naming a command or path must use (`followup.md`).
 const NOTIFY_OPTIONS = ['notify-message', 'notify-message-file'] as const
-// joshuafolkken/kit#2446: the PR body carrying the live-execution evidence `followup` gates the merge
+// The PR body carrying the live-execution evidence `followup` gates the merge
 // on, forwarded to `git -y` as a path because it holds commands and their output.
 const BODY_FILE_OPTION = 'body-file'
 const USAGE =
@@ -76,7 +74,7 @@ const OPTIONS = {
 	[NOTIFY_OPTIONS[1]]: { type: 'string' },
 	[BODY_FILE_OPTION]: { type: 'string' },
 	review: { type: 'boolean' },
-	// joshuafolkken/kit#2428: hand the region to a detached supervisor (`run-ship-detach.ts`), print the
+	// Hand the region to a detached supervisor (`run-ship-detach.ts`), print the
 	// report a stopped supervisor left, and carry follow-up citations as options so the supervisor's
 	// command line still ends with its title.
 	detach: { type: 'boolean' },
@@ -88,10 +86,13 @@ type ShipCommand = { kind: 'ship'; args: ShipArguments } | { kind: 'log'; number
 
 // What a resumed ship knows before its first stage: the record's path (absent outside a repository),
 // the stages it says completed, and the repository's actual state (`run-ship-stage.ts` decides from it).
+// `started` opens with the stages the record says this attempt started — a supervisor that ended
+// without a stop leaves them — and grows as each stage starts; every stage line carries it.
 interface ShipContext {
 	target: string | undefined
 	done: ReadonlySet<string>
 	state: ShipState
+	started: Array<string>
 }
 
 // The notify tail `followup` takes — whichever body form the caller composed, forwarded unchanged so a
@@ -122,6 +123,8 @@ interface ParsedValues extends NotifyValues {
 	cite?: Array<string>
 }
 
+// A follow-up citation passed as a trailing positional is a bare issue number, so a stray flag is
+// refused rather than forwarded to the wrong step.
 function ship_args(
 	title: string,
 	rest: ReadonlyArray<string>,
@@ -130,7 +133,9 @@ function ship_args(
 	const number = issue_number(title)
 	const cites = [...rest, ...(values.cite ?? [])]
 
-	if (number === undefined || cites.some((token) => !CITE_PATTERN.test(token))) return undefined
+	if (number === undefined || cites.some((token) => !issue_number_shape.is_issue_number(token))) {
+		return undefined
+	}
 
 	return {
 		title,
@@ -146,7 +151,9 @@ function ship_args(
 
 // `--log <N>` stands alone: a bare issue number and nothing to ship.
 function log_command(number: string, positionals: ReadonlyArray<string>): ShipCommand | undefined {
-	return CITE_PATTERN.test(number) && positionals.length === 0 ? { kind: 'log', number } : undefined
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(number) && positionals.length === 0
+		? { kind: 'log', number }
+		: undefined
 }
 
 function command_of(
@@ -170,15 +177,34 @@ function parse(argv: ReadonlyArray<string>): ShipCommand | undefined {
 	return parsed === undefined ? undefined : command_of(parsed.values, parsed.positionals)
 }
 
+// Every stage that ran is timed into the lane ledger, failed ones included — a stage that stopped the
+// ship cost the lane its time as well. The append is local and best-effort, so it adds no wait.
+//
+// **A stage that found nothing to do is not timed**: a round 2 that was not due, a round 1 already
+// recorded, or a gate that reused its tree's green record would otherwise read as a run that took a
+// second and pull the stage's median to zero.
+async function record_timed(step: Step, issue: string, elapsed_ms: number): Promise<void> {
+	await lane_ledger.record_stage({ stage: step.stage, elapsed_ms, issue: Number(issue) })
+}
+
 async function run_step(step: Step, args: ShipArguments, state: ShipState): Promise<ShipSection> {
+	const started_ms = performance.now()
 	const result = await step.run(args, state)
+	const elapsed_ms = performance.now() - started_ms
+
+	if (result.is_skipped !== true) await record_timed(step, args.number, elapsed_ms)
 	const section = { header: step.header, body: result.out, code: result.code }
 
 	return result.conflicts === undefined ? section : { ...section, conflicts: result.conflicts }
 }
 
-async function emit_phase(args: ShipArguments, stage: Stage, phase: Phase): Promise<void> {
-	const text = run_ship_stage.event_text(args.number, stage, phase)
+async function emit_phase(
+	args: ShipArguments,
+	context: ShipContext,
+	stage: Stage,
+	phase: Phase,
+): Promise<void> {
+	const text = run_ship_stage.event_text(args.number, stage, phase, context.started)
 
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.SHIP_STAGE, text)
 }
@@ -203,7 +229,7 @@ async function settle(
 ): Promise<void> {
 	const is_green = code === SUCCESS_EXIT_CODE
 
-	await emit_phase(args, step.stage, is_green ? PHASE.DONE : PHASE.FAILED)
+	await emit_phase(args, context, step.stage, is_green ? PHASE.DONE : PHASE.FAILED)
 
 	if (!is_green) return
 
@@ -219,12 +245,16 @@ async function run_stage(
 	context: ShipContext,
 ): Promise<ShipSection> {
 	if (run_ship_stage.is_done(step.stage, context.done, context.state, args.body.length > 0)) {
-		await emit_phase(args, step.stage, PHASE.SKIPPED)
+		await emit_phase(args, context, step.stage, PHASE.SKIPPED)
 
 		return { header: step.header, body: run_ship.SKIPPED_BODY, code: SUCCESS_EXIT_CODE }
 	}
 
-	await emit_phase(args, step.stage, PHASE.START)
+	context.started.push(step.stage)
+	record(context.target, (path) => {
+		run_ship_stage.mark_started(path, step.stage)
+	})
+	await emit_phase(args, context, step.stage, PHASE.START)
 	const section = await run_step(step, args, context.state)
 
 	await settle(step, args, context, section.code)
@@ -239,24 +269,28 @@ async function open_context(args: ShipArguments): Promise<ShipContext> {
 	])
 
 	const done = target === undefined ? new Set<string>() : run_ship_stage.read_done(target)
+	const started = target === undefined ? [] : [...run_ship_stage.read_started(target)]
 
-	return { target, done, state }
+	return { target, done, state, started }
 }
 
-// A detached supervisor hands the stopped stage back (`run-ship-return.ts`, joshuafolkken/kit#2428); a
-// ship in an agent's own turn has its report in front of that agent already.
+// A detached supervisor hands the stopped stage back (`run-ship-return.ts`); a
+// ship in an agent's own turn has its report in front of that agent already. The `ship-stop` ends the
+// attempt, so the record's started stages go with it.
 async function stopped(
 	sections: ReadonlyArray<ShipSection>,
 	args: ShipArguments,
-	stage: Stage,
+	step: Step,
+	context: ShipContext,
 ): Promise<ReadonlyArray<ShipSection>> {
 	if (run_ship_detach.is_supervised()) {
 		const conflicts = sections.at(-1)?.conflicts
 		const resume = run_ship_next.resume_of(args)
 
+		record(context.target, run_ship_stage.end_attempt)
 		await run_ship_return.return_control(
 			args.number,
-			stage,
+			step.stage,
 			conflicts === undefined ? resume : { ...resume, conflicts },
 		)
 	}
@@ -278,7 +312,7 @@ async function ship(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 		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)
+		if (section.code !== SUCCESS_EXIT_CODE) return await stopped(sections, args, step, context)
 	}
 
 	record(context.target, (path) => {
@@ -321,7 +355,7 @@ async function detach(args: ShipArguments): Promise<number> {
 	return result.verdict === run_ship_detach.LAUNCHED ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
-// joshuafolkken/kit#2457: a headless lane child's turn ending kills a ship it left in its own process,
+// A headless lane child's turn ending kills a ship it left in its own process,
 // so inside a lane child the region always goes to the supervisor, flag or not. The supervisor itself
 // inherits the lane mark, and is the one ship that must run the stages here.
 function should_detach(args: ShipArguments): boolean {
@@ -330,11 +364,11 @@ 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.
-// joshuafolkken/kit#3222: the type check and the document tests follow it here for the same reason; they
-// are not a stage, so the supervisor's gate runs them again rather than passing over them.
+// 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. The type
+// check and the document tests follow it here for the same reason; they are not a stage, so the
+// supervisor's gate runs them again rather than passing over them.
 async function pre_detach_sections(args: ShipArguments): Promise<ReadonlyArray<ShipSection>> {
 	const preflight = await run_stage(run_ship_steps.PREFLIGHT_STEP, args, await open_context(args))
 	if (preflight.code !== SUCCESS_EXIT_CODE) return [preflight]

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

@@ -1,18 +1,19 @@
 import { randomUUID } from 'node:crypto'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { session_cite } from '#scripts/issue/session-cite'
 import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { z } from 'zod'
 
-// `josh ship --detach` — hand the post-implementation region to a supervisor that outlives the agent
-// (joshuafolkken/kit#2428). A lane child used to take the pre-gate cut and relaunch a fresh agent session
-// to drive the gate, the review and the merge; that session re-read the issue to run fixed procedure,
-// and the wake role it billed was 59.8% of a run's wall time. This starts `josh ship` itself as a
-// detached process instead, so the agent ends at the hand-off and nothing but the mechanical region runs.
+// `josh ship --detach` — hand the post-implementation region to a supervisor that outlives the agent.
+// This starts `josh ship` itself as a detached process, so the agent ends at the hand-off and nothing
+// but the mechanical region runs.
 //
 // **The supervisor's command line ends with the `"<title> #<N>"` title**, which is what the parent's
 // liveness pattern (`lane-child-invocation.ts`) anchors on — so a lane whose agent has ended is still
@@ -24,7 +25,7 @@ import { z } from 'zod'
 // while that process is alive is refused `busy`: two supervisors would race each other's commit and
 // merge, which the resume record (`run-ship-stage.ts`) orders but cannot serialize.
 //
-// **The supervisor names itself once it starts** (joshuafolkken/kit#2642). The launcher reads the child's
+// **The supervisor names itself once it starts**. The launcher reads the child's
 // start time from outside, which a sandbox that refuses `ps` cannot answer; a pid with no start time
 // would then be believed for as long as any process holds that number. The supervisor therefore claims
 // the record with its own identity — whose socket beacon answers where `ps` cannot — and a record still
@@ -114,11 +115,8 @@ function result_path(repository: string, number: string): string {
 function read_record(repository: string, number: string): ShipRecord | undefined {
 	try {
 		const raw = stamp_file.read_stamp_text(result_path(repository, number))
-		if (raw === undefined) return undefined
-		const value: unknown = JSON.parse(raw)
-		const parsed = ship_record_schema.safeParse(value)
 
-		return parsed.success ? parsed.data : undefined
+		return raw === undefined ? undefined : json_value.parse_with(raw, ship_record_schema)
 	} catch {
 		return undefined
 	}
@@ -291,7 +289,7 @@ function launch(request: DetachRequest): DetachResult {
 			cwd: request.cwd,
 			log_path: log,
 			// The provider travels as a mark because the launch strips the session keys that name it, and
-			// `ship --review` resolves its reviewer from it (joshuafolkken/kit#2456).
+			// `ship --review` resolves its reviewer from it.
 			env: supervisor_environment(launch_id),
 		},
 		(note) => {
@@ -299,6 +297,7 @@ function launch(request: DetachRequest): DetachResult {
 		},
 	)
 
+	agent_role_profile.warn_of_default()
 	if (result.kind === 'failed') return failed_launch(request, result.note)
 
 	record_launch(request, result.pid, launch_id)
@@ -311,7 +310,10 @@ function launch(request: DetachRequest): DetachResult {
 
 async function detach(request: DetachRequest): Promise<DetachResult> {
 	if (read_result(request.repository, request.number)?.result === 'running') {
-		return { verdict: BUSY, note: `a ship supervisor for #${request.number} is already running` }
+		return {
+			verdict: BUSY,
+			note: `a ship supervisor for ${session_cite.issue(request.number)} is already running`,
+		}
 	}
 
 	const result = launch(request)
@@ -319,7 +321,7 @@ async function detach(request: DetachRequest): Promise<DetachResult> {
 	if (result.verdict === LAUNCHED) {
 		await run_event_stream_emit.emit(
 			run_event_stream.EVENT_KIND.SHIP_LAUNCH,
-			`#${request.number} ship supervisor launched`,
+			`${issue_cite.plain(request.number)} ship supervisor launched`,
 		)
 	}
 

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

@@ -4,7 +4,7 @@ import { stripVTControlCharacters } from 'node:util'
 import { buffered_process } from '#scripts/lib/buffered-process'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 
-// A lock file that no longer matches its inputs, asked before the gate (joshuafolkken/kit#3307).
+// A lock file that no longer matches its inputs, asked before the gate.
 //
 // The pre-push hook's setup runs `pnpm install`, which rewrites a lock that has drifted — a
 // `.pnpmfile.mjs` edit moves `pnpmfileChecksum` — and so leaves the working tree dirty under the push.

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

@@ -1,12 +1,11 @@
 import { run_ship_stage, type Stage } from './run-ship-stage'
 import type { ShipArguments } from './run-ship-steps'
 
-// The command a relaunched lane child runs once it has fixed what stopped its detached ship
-// (joshuafolkken/kit#2964). The ship-stop prompt used to say only "hand the region back per
-// chain-rule.md", so every relaunched session searched that document and re-derived the next command
-// — 179 reads of it in one run. The stopped stage decides the command mechanically, so it is decided
-// here, once, and the prompt carries it. `chain-rule.md` step 0 stays the single source of the
-// procedure; `ship-stop-prompt-document-rule.test.ts` holds every command below to it.
+// The command a relaunched lane child runs once it has fixed what stopped its detached ship.
+// The stopped stage decides the command mechanically, so it is decided here, once, and the prompt
+// carries it rather than each relaunched session re-deriving it. `chain-rule.md` step 0 stays the
+// single source of the procedure; `ship-stop-prompt-document-rule.test.ts` holds every command below
+// to it.
 //
 // The fix is left uncommitted on purpose: a dirty tree reads as not committed
 // (`run-ship-probe.ts`), so a re-detached ship runs the gate and the commit again on the fixed tree
@@ -42,7 +41,7 @@ interface ShipResume {
 	title: string
 	flags: ReadonlyArray<string>
 	is_review: boolean
-	// The paths a merge of the default branch left unmerged (joshuafolkken/kit#3221).
+	// The paths a merge of the default branch left unmerged.
 	conflicts?: ReadonlyArray<string>
 }
 
@@ -99,7 +98,7 @@ const AFTER_FIX: Record<Stage, (resume: ShipResume) => string> = {
 	[STAGE.REPORT]: detach_again,
 }
 
-// A conflict names its paths (joshuafolkken/kit#3221), so the resumed session resolves them without
+// A conflict names its paths, so the resumed session resolves them without
 // reading the report or asking git which files are unmerged.
 function conflict_step(conflicts: ReadonlyArray<string>): string {
 	return `Resolve the conflict with origin/main in ${conflicts.join(', ')} (the merge is left in progress: remove the conflict markers in those files), then`

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

@@ -1,24 +1,30 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
+import { project_checks } from '#scripts/gate/project-checks'
 import { type_check_step } from '#scripts/gate/type-check-step'
 import type { JoshResult } from '#scripts/josh/josh-run'
 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 and before
-// the hand-off (joshuafolkken/kit#3222). In one measured backlogrun about 7 of 31 lane resumes were a
-// gate failure first seen after the detach — a type error in a file the related-only checks never
-// touched, or a document test (a SKILL.md pointer, a byte budget, the command list) that only the full
-// suite runs — each paid for with a relaunched session. These two answer in seconds, so the same
-// session fixes what they find and ships again. **Nothing moves out of the gate**: the supervised gate
-// stage still runs every check, these included.
+// the hand-off: a type error in a file the related-only checks never touched, or a document test (a
+// SKILL.md pointer, a byte budget, the command list) that only the full suite runs, would otherwise
+// first surface after the detach and cost a relaunched session. These two answer in seconds, so the
+// same session fixes what they find and ships again. **Nothing moves out of the gate**: the
+// supervised gate stage still runs every check, these included.
 //
-// The test targets are the directories those resumes failed in. A consumer has none of them, so only
+// The test targets are the directories such failures land in. A consumer has none of them, so only
 // the ones present run, and a consumer meets the type check 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
+// durations are left out: they read the gate ledger, stale before the detach, so they stay with the
+// supervised gate.
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const SECTION_SEPARATOR = '\n\n'
-const PASSED = 'type check and document tests passed'
+const PASSED = 'pre-detach checks passed'
+const METRICS_TOTALS_COMMAND: ReadonlyArray<string> = ['josh', 'metrics', '--totals-only']
 const DOCUMENT_TEST_TARGETS: ReadonlyArray<string> = [
 	'scripts/document',
 	'scripts/claude',
@@ -33,11 +39,21 @@ function present_targets(directory: string): ReadonlyArray<string> {
 	return DOCUMENT_TEST_TARGETS.filter((target) => existsSync(path.join(directory, target)))
 }
 
+function document_tests(directory: string): Array<ReadonlyArray<string>> {
+	const targets = present_targets(directory)
+
+	return targets.length === 0 ? [] : [[...DOCUMENT_TEST_COMMAND, ...targets]]
+}
+
+// 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<ReadonlyArray<string>> {
+	return project_checks.is_kit_repository(directory) ? [METRICS_TOTALS_COMMAND] : []
+}
+
 async function command_lists(directory: string): Promise<Array<ReadonlyArray<string>>> {
 	const type_check = await type_check_step.resolve_type_check_args(directory)
-	const targets = present_targets(directory)
 
-	return targets.length === 0 ? [type_check] : [type_check, [...DOCUMENT_TEST_COMMAND, ...targets]]
+	return [type_check, ...document_tests(directory), ...kit_only(directory)]
 }
 
 async function run_in(
@@ -61,6 +77,6 @@ async function checks(directory: string = process.cwd()): Promise<JoshResult> {
 	}
 }
 
-const run_ship_pre_detach = { DOCUMENT_TEST_TARGETS, PASSED, checks }
+const run_ship_pre_detach = { DOCUMENT_TEST_TARGETS, METRICS_TOTALS_COMMAND, PASSED, checks }
 
 export { run_ship_pre_detach }

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

@@ -10,11 +10,10 @@ import { live_evidence } from '#scripts/review/live-evidence'
 import { run_ship_lock } from './run-ship-lock'
 import { run_ship_scoped } from './run-ship-scoped'
 
-// `josh ship`'s first stage (joshuafolkken/kit#2946). A detached ship used to meet the pull request's
-// preconditions only at the commit stage — `git -y`'s preflight — or at the merge — `followup`'s
-// live-evidence refusal — each after the review and the gate had already run, so every such stop
-// relaunched a session to repeat them. **Every precondition decidable before the review is asked here,
-// and all of them are reported at once.** No check is new: the classification, issue and branch answers
+// `josh ship`'s first stage. The commit stage (`git -y`'s preflight) and the merge (`followup`'s
+// live-evidence refusal) run after the review and the gate, so a stop there would repeat them.
+// **Every precondition decidable before the review is asked here, and all of them are reported at
+// once.** No check is new: the classification, issue and branch answers
 // are `git_preflight.problems_of`, and the evidence answer is `live_evidence.verdict_for` over the same
 // changed paths and the body this ship will deliver — `--body-file` when given, else the open PR's.
 //
@@ -23,8 +22,8 @@ import { run_ship_scoped } from './run-ship-scoped'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const EVIDENCE_PROBLEM = `This change touches runtime code, but the PR body has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and pass the body with --body-file <path>.`
-const EVIDENCE_PENDING = `This change touches runtime code and no PR is open yet: write the ${live_evidence.EVIDENCE_HEADING} section to a file and hand it to josh ship with --body-file <path>, or the ship refuses.`
+const EVIDENCE_PROBLEM = `This change touches runtime code, but the PR body has no ${live_evidence.EVIDENCE_HEADING} section: run the acceptance criteria for real and pass the body with --body-file <path>. Write it ${live_evidence.EVIDENCE_FORMAT}`
+const EVIDENCE_PENDING = `This change touches runtime code and no PR is open yet: write the ${live_evidence.EVIDENCE_HEADING} section to a file and hand it to josh ship with --body-file <path>, or the ship refuses. Write it ${live_evidence.EVIDENCE_FORMAT}`
 
 interface PreflightRequest {
 	title: string
@@ -72,7 +71,7 @@ async function caught(problems: Promise<Array<string>>): Promise<Array<string>>
 	}
 }
 
-// The lock file is asked here too (joshuafolkken/kit#3307), so a drift stops the ship before the gate
+// 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<string>> {
 	const [preflight, evidence, lock] = await Promise.all([
@@ -100,9 +99,9 @@ async function classification_problems(issue_number: string): Promise<Array<stri
 	return []
 }
 
-// **The same two refusals, asked before the ship rather than by it** (joshuafolkken/kit#3154). In one
-// measured backlogrun 20 of 41 lane `ship` refusals were a missing classification or missing evidence —
-// facts fixed long before the ship, refused at the run's largest context. `run:prep` (and so `run:entry`)
+// **The same two refusals, asked before the ship rather than by it**: a missing
+// classification or missing evidence is known long before the ship, yet refused there at the run's
+// largest context. `run:prep` (and so `run:entry`)
 // and `run:step` print this, so the Issue body and the evidence are met while they are cheap. Nothing
 // here replaces `stage`: the ship and `followup` still refuse on both. Before the PR exists the evidence
 // can only live in the file the ship will be handed, so it is asked for as that file, not reported as a

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

@@ -5,9 +5,9 @@ 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'
 
-// The read side of a resumed `josh ship` (joshuafolkken/kit#2426): the repository's actual state, asked
-// before any stage runs, and where the stage record lives. `run-ship-stage.ts` decides from what this
-// reads; this module only reads.
+// The read side of a resumed `josh ship`: the repository's actual state, asked before any stage runs,
+// and where the stage record lives. `run-ship-stage.ts` decides from what this reads; this module
+// only reads.
 //
 // **Every read that cannot complete answers `false`** — "not done yet" — so the stage runs and its own
 // guard answers instead: `git -y` refuses an empty commit, a push of a commit origin already holds
@@ -82,7 +82,7 @@ async function read_state(): Promise<ShipState> {
 }
 
 // The common git directory every lane of the repository shares — what the stage record, the detached
-// supervisor's log and its pid are keyed on (joshuafolkken/kit#2428) — or `undefined` outside one.
+// supervisor's log and its pid are keyed on — or `undefined` outside one.
 async function repository_directory(): Promise<string | undefined> {
 	try {
 		const directories = await git_command.git_directories()

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

@@ -9,7 +9,7 @@ import type { ShipResume } from './run-ship-next'
 import { run_ship_stage, type Stage } from './run-ship-stage'
 import { run_ship_stop_text } from './run-ship-stop-text'
 
-// How a detached `josh ship` supervisor hands a stopped stage back (joshuafolkken/kit#2428). The agent
+// How a detached `josh ship` supervisor hands a stopped stage back. The agent
 // ended when it handed the region over, so a red gate, a High/Medium review, a failed push or red CI has
 // nobody to read it — this is what gives it one, in two halves:
 //