@joshuafolkken/kit 1.883.0 → 1.921.0

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

@@ -11,6 +11,8 @@ import { run_event_stream_emit } from './run-event-stream-emit'
 import { run_issue_number } from './run-issue-number'
 import { run_merge, type ChildOutcome, type EndingSignals } from './run-merge'
 import { run_merge_steps, type MergeContext } from './run-merge-steps'
+import { run_ship_detach } from './run-ship-detach'
+import { run_ship_probe } from './run-ship-probe'
 
 // `josh run:merge <N>` — one composite command for a `backlogrun` merge event (joshuafolkken/kit#2024).
 // The parent's context is the largest and its per-turn cost the highest, and the event was two turns:
@@ -324,6 +326,10 @@ async function on_unresolved(): Promise<MergeVerdict> {
 	return emit(RETRY_TOKEN, FAILURE_EXIT_CODE)
 }
 
+async function on_shipping(): Promise<MergeVerdict> {
+	return emit(RESUMED_TOKEN, SUCCESS_EXIT_CODE)
+}
+
 const HANDLERS: Readonly<Record<ChildOutcome, (ctx: MergeContext) => Promise<MergeVerdict>>> = {
 	cut: on_cut,
 	failed: on_failed,
@@ -333,11 +339,24 @@ const HANDLERS: Readonly<Record<ChildOutcome, (ctx: MergeContext) => Promise<Mer
 	parked: on_parked,
 	split: on_skipped,
 	unresolved: on_unresolved,
+	shipping: on_shipping,
+}
+
+async function is_ship_running(child: string): Promise<boolean> {
+	const repository = await run_ship_probe.repository_directory()
+
+	return (
+		repository !== undefined && run_ship_detach.read_result(repository, child)?.result === 'running'
+	)
 }
 
 // The whole merge event for one returned child, in-process: read its state, classify it, and run the
 // handler. The CLI prints the token; `backlog:drive` branches on the outcome (joshuafolkken/kit#2508).
 async function merge_child(ctx: MergeContext): Promise<MergeResult> {
+	if (await is_ship_running(ctx.child)) {
+		return { outcome: 'shipping', ...(await on_shipping()) }
+	}
+
 	const read = await issue_state_cli.read_issue(ctx.child, ctx.repo)
 	const outcome = outcome_of(read, await read_signals(ctx))
 

package/scripts/run/run-merge.ts

@@ -45,7 +45,15 @@ const ONE = 1
 // - `failed`      — OPEN and carrying neither, and not an outage; the child did not finish.
 // - `unresolved`  — the state could not be read; re-read before deciding.
 type ChildOutcome =
-	'merged' | 'human-review' | 'parked' | 'split' | 'cut' | 'outage' | 'failed' | 'unresolved'
+	| 'merged'
+	| 'human-review'
+	| 'parked'
+	| 'split'
+	| 'cut'
+	| 'outage'
+	| 'failed'
+	| 'unresolved'
+	| 'shipping'
 
 // What the CLI read beside the GitHub state: whether the exit record is an API outage, and whether the
 // lane holds a cut its successor never adopted.

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

@@ -392,6 +392,24 @@ function should_detach(args: ShipArguments): boolean {
 	return !run_ship_detach.is_supervised() && lane_child_marker.is_child_of(process.cwd())
 }
 
+async function supervised_repository(): Promise<string | undefined> {
+	return run_ship_detach.is_supervised() ? await run_ship_probe.repository_directory() : undefined
+}
+
+async function claim_supervised_identity(args: ShipArguments): Promise<void> {
+	const repository = await supervised_repository()
+	if (repository !== undefined) await run_ship_detach.claim_identity(repository, args.number)
+}
+
+async function record_supervised_result(
+	args: ShipArguments,
+	sections: ReadonlyArray<ShipSection>,
+): Promise<void> {
+	const repository = await supervised_repository()
+	if (repository === undefined) return
+	await run_ship_detach.mark_result(repository, args.number, run_ship.exit_code(sections))
+}
+
 async function run_ship_command(args: ShipArguments): Promise<number> {
 	if (should_detach(args)) {
 		if (!args.is_detach) console.error(LANE_CHILD_DETACH_NOTE)
@@ -399,8 +417,10 @@ async function run_ship_command(args: ShipArguments): Promise<number> {
 		return await detach(args)
 	}
 
+	await claim_supervised_identity(args)
 	const sections = await ship(args)
 
+	await record_supervised_result(args, sections)
 	console.info(run_ship.format_report(sections))
 
 	return run_ship.exit_code(sections)

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

@@ -1,5 +1,9 @@
+import { randomUUID } from 'node:crypto'
+import { setTimeout as sleep } from 'node:timers/promises'
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { process_identity } from '#scripts/josh/process-identity'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
 import { detached_launch, type LaunchArgv } from './detached-launch'
 import { run_event_stream } from './run-event-stream'
 import { run_event_stream_emit } from './run-event-stream-emit'
@@ -19,6 +23,14 @@ import { run_event_stream_emit } from './run-event-stream-emit'
 // **One supervisor per issue.** The launched pid is kept beside the stage record, and a second detach
 // 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
+// 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
+// carrying a bare pid is believed only for the claim window after its launch. A recorded start time the
+// probe cannot momentarily read is the opposite case: the pid is alive and was verified once, so it is
+// kept running rather than read as a crash that would license a second supervisor.
 
 const LOG_PREFIX = 'josh-ship-log-'
 const PID_PREFIX = 'josh-ship-pid-'
@@ -33,11 +45,39 @@ const NOTIFY_VALUE_INDEX = 1
 // Set on the supervisor so it knows a failed stage is its to hand back (`run-ship-return.ts`); a ship run
 // in an agent's own turn reports its failure in that turn and hands nothing back.
 const SUPERVISED_KEY = 'JOSH_SHIP_SUPERVISED'
+const LAUNCH_ID_KEY = 'JOSH_SHIP_LAUNCH_ID'
 const SUPERVISED_VALUE = '1'
 const LAUNCHED = 'launched'
 const BUSY = 'busy'
 const FAILED = 'failed'
-const NO_SIGNAL = 0
+const RESULT_PREFIX = 'josh-ship-result-'
+const RECORD_POLL_MS = 25
+const RECORD_WAIT_ATTEMPTS = 200
+// How long a bare launched pid is believed before the supervisor must have claimed the record: far above
+// a `pnpm josh ship` start-up, far below the lifetime a reused pid could otherwise be believed for.
+const CLAIM_WINDOW_MS = 120_000
+type ShipResult = 'running' | 'success' | 'failed' | 'abnormal'
+
+interface ShipRecord {
+	pid?: number | undefined
+	process_start?: string | undefined
+	launched_at?: number | undefined
+	launcher_pid?: number | undefined
+	launcher_start?: string | undefined
+	launch_id: string
+	result?: 'success' | 'failed' | undefined
+}
+
+const ship_record_schema = z.object({
+	pid: z.number().int().positive().optional(),
+	process_start: z.string().optional(),
+	launched_at: z.number().optional(),
+	launcher_pid: z.number().int().positive().optional(),
+	launcher_start: z.string().optional(),
+	launch_id: z.string(),
+	result: z.enum(['success', 'failed']).optional(),
+})
+
 // `detached_launch.log_header`'s shape — `\n=== <time> · started by process <pid> · <command> ===` — read
 // back to find where the last launch into the log began.
 const LAUNCH_MARK = ' · started by process '
@@ -67,21 +107,129 @@ function log_path(repository: string, number: string): string {
 	return stamp_file.stamp_path(`${LOG_PREFIX}${number}${KEY_SEPARATOR}`, repository, LOG_SUFFIX)
 }
 
-function is_alive(pid: number): boolean {
+function result_path(repository: string, number: string): string {
+	return stamp_file.stamp_path(`${RESULT_PREFIX}${number}${KEY_SEPARATOR}`, repository)
+}
+
+function read_record(repository: string, number: string): ShipRecord | undefined {
 	try {
-		process.kill(pid, NO_SIGNAL)
+		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
+	} catch {
+		return undefined
+	}
+}
+
+function record_launch(request: DetachRequest, pid: number, launch_id: string): void {
+	stamp_file.write_text_stamp(key(PID_PREFIX, request), String(pid))
+	const process_start = process_identity.read_start(pid)
+
+	stamp_file.replace_stamp(result_path(request.repository, request.number), {
+		pid,
+		launch_id,
+		launched_at: Date.now(),
+		...(process_start !== undefined && { process_start }),
+	})
+}
+
+function supervisor_environment(launch_id: string): Record<string, string | undefined> {
+	return {
+		...agent_role_profile.handoff_environment(),
+		[SUPERVISED_KEY]: SUPERVISED_VALUE,
+		[LAUNCH_ID_KEY]: launch_id,
+	}
+}
+
+function is_within_claim_window(record: ShipRecord): boolean {
+	return record.launched_at !== undefined && Date.now() - record.launched_at < CLAIM_WINDOW_MS
+}
+
+function has_live_identity(pid: number, record: ShipRecord): boolean {
+	if (record.process_start === undefined) {
+		return is_within_claim_window(record) && process_identity.is_live_pid(pid)
+	}
+
+	return process_identity.is_same_process(pid, record.process_start) !== false
+}
+
+function result_of(record: ShipRecord): ShipResult {
+	if (record.pid === undefined) {
+		const is_launcher = process_identity.is_same_process(record.launcher_pid, record.launcher_start)
+
+		return is_launcher === false ? 'abnormal' : 'running'
+	}
+
+	if (has_live_identity(record.pid, record)) return 'running'
 
-		return true
-	} catch (error) {
-		return error instanceof Error && 'code' in error && error.code === 'EPERM'
+	return record.result ?? 'abnormal'
+}
+
+function read_result(
+	repository: string,
+	number: string,
+): { launch_id: string; result: ShipResult } | undefined {
+	const record = read_record(repository, number)
+
+	return record === undefined
+		? undefined
+		: { launch_id: record.launch_id, result: result_of(record) }
+}
+
+function current_record(repository: string, number: string): ShipRecord | undefined {
+	const record = read_record(repository, number)
+
+	return record?.launch_id === process.env[LAUNCH_ID_KEY] ? record : undefined
+}
+
+function is_pending(record: ShipRecord | undefined): boolean {
+	return record !== undefined && record.pid === undefined
+}
+
+async function ready_record(repository: string, number: string): Promise<ShipRecord | undefined> {
+	let record = current_record(repository, number)
+
+	for (let attempt = 0; attempt < RECORD_WAIT_ATTEMPTS; attempt += 1) {
+		if (!is_pending(record)) return record
+
+		await sleep(RECORD_POLL_MS)
+		record = current_record(repository, number)
 	}
+
+	return undefined
 }
 
-// The recorded supervisor, when it is still running. An absent, unreadable or dead pid is no supervisor.
-function is_supervisor_running(pid_target: string): boolean {
-	const pid = Number(stamp_file.read_stamp_text(pid_target)?.trim())
+async function update_record(
+	repository: string,
+	number: string,
+	fields: Partial<ShipRecord>,
+): Promise<void> {
+	const record = await ready_record(repository, number)
+	if (record === undefined) return
 
-	return Number.isSafeInteger(pid) && pid > 0 && is_alive(pid)
+	stamp_file.replace_stamp(result_path(repository, number), { ...record, ...fields })
+}
+
+async function mark_result(repository: string, number: string, code: number): Promise<void> {
+	await update_record(repository, number, { result: code === 0 ? 'success' : 'failed' })
+}
+
+// A supervisor that cannot name its own start either (no probe and no beacon) leaves the launcher's
+// identity in place rather than pairing its own pid with the launcher-read start of another process.
+async function claim_identity(repository: string, number: string): Promise<void> {
+	const own = process_identity.own_fields()
+	if (own.process_start === undefined) return
+
+	await update_record(repository, number, own)
+}
+
+function failed_launch(request: DetachRequest, note: string): DetachResult {
+	stamp_file.remove_stamp(result_path(request.repository, request.number))
+
+	return { verdict: FAILED, note }
 }
 
 // The notify tail the supervisor is given: an inline body moved into a file, a file body passed as is.
@@ -119,9 +267,23 @@ function supervisor_argv(request: DetachRequest): LaunchArgv {
 	}
 }
 
+function prepare_launch(request: DetachRequest): string {
+	const launch_id = randomUUID()
+	const launcher = process_identity.own_fields()
+
+	stamp_file.replace_stamp(result_path(request.repository, request.number), {
+		launch_id,
+		launcher_pid: launcher.pid,
+		...(launcher.process_start !== undefined && { launcher_start: launcher.process_start }),
+	})
+
+	return launch_id
+}
+
 function launch(request: DetachRequest): DetachResult {
 	const notes: Array<string> = []
 	const log = log_path(request.repository, request.number)
+	const launch_id = prepare_launch(request)
 	const result = detached_launch.launch(
 		{
 			argv: supervisor_argv(request),
@@ -129,16 +291,16 @@ function launch(request: DetachRequest): DetachResult {
 			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).
-			env: { ...agent_role_profile.handoff_environment(), [SUPERVISED_KEY]: SUPERVISED_VALUE },
+			env: supervisor_environment(launch_id),
 		},
 		(note) => {
 			notes.push(note)
 		},
 	)
 
-	if (result.kind === 'failed') return { verdict: FAILED, note: result.note }
+	if (result.kind === 'failed') return failed_launch(request, result.note)
 
-	stamp_file.write_text_stamp(key(PID_PREFIX, request), String(result.pid))
+	record_launch(request, result.pid, launch_id)
 
 	return {
 		verdict: LAUNCHED,
@@ -147,7 +309,7 @@ function launch(request: DetachRequest): DetachResult {
 }
 
 async function detach(request: DetachRequest): Promise<DetachResult> {
-	if (is_supervisor_running(key(PID_PREFIX, request))) {
+	if (read_result(request.repository, request.number)?.result === 'running') {
 		return { verdict: BUSY, note: `a ship supervisor for #${request.number} is already running` }
 	}
 
@@ -187,6 +349,10 @@ const run_ship_detach = {
 	BUSY,
 	FAILED,
 	LAUNCHED,
+	LAUNCH_ID_KEY,
+	claim_identity,
+	mark_result,
+	read_result,
 	SUPERVISED_KEY,
 	detach,
 	is_supervised,

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

@@ -1,10 +1,12 @@
-import { agent_argv } from '#scripts/agent/agent-argv'
-import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { agent_argv, type AgentArgv } from '#scripts/agent/agent-argv'
+import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { gate_tree } from '#scripts/gate/gate-tree'
 import { scoped_green } from '#scripts/gate/scoped-green'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { josh_command, type JoshResult } from '#scripts/josh/josh-run'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
+import { openai_review_broker } from '#scripts/lane/openai-review-broker'
 import { detached_launch } from './detached-launch'
 import { run_ship_review, type RoundOutcome, type ScoredVerdict } from './run-ship-review'
 
@@ -41,12 +43,6 @@ 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 BRIEF_PREFIX = 'josh-ship-review-brief-'
-const FINDINGS_PREFIX = 'josh-ship-review-findings-'
-const LOG_PREFIX = 'josh-ship-review-log-'
-const BRIEF_SUFFIX = '.md'
-const FINDINGS_SUFFIX = '.txt'
-const LOG_SUFFIX = '.log'
 const FIXED_JOIN_NOTE =
 	'the round-1 gate read the tree before the review fixes — drained, not judged; the gate stage re-runs it.'
 const ROUND_TWO_SKIPPED_NOTE = 'round 2 not due — nothing left to verify; shipping on.'
@@ -59,11 +55,7 @@ function failure(out: string): JoshResult {
 }
 
 function paths(root: string = PROJECT_ROOT): { brief: string; findings: string; log: string } {
-	return {
-		brief: stamp_file.stamp_path(BRIEF_PREFIX, root, BRIEF_SUFFIX),
-		findings: stamp_file.stamp_path(FINDINGS_PREFIX, root, FINDINGS_SUFFIX),
-		log: stamp_file.stamp_path(LOG_PREFIX, root, LOG_SUFFIX),
-	}
+	return openai_review_broker.review_paths(root)
 }
 
 async function josh(argv: ReadonlyArray<string>): Promise<JoshResult> {
@@ -77,12 +69,12 @@ function note(text: string): void {
 // Under the reviewer profile — the same model and effort (`JOSH_REVIEWER_*` included) the chain's
 // subagent is given — and waited on, so the join below runs only once the review has finished. Each
 // call is its own process, so round 2 is a fresh session by construction.
-async function run_session(prompt: string, log_path: string): 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}`)
-
-	const request = { argv: built.argv, cwd: PROJECT_ROOT, log_path, profile: built.profile }
+async function run_direct_session(
+	argv: AgentArgv,
+	profile: AgentProfile,
+	log_path: string,
+): Promise<JoshResult> {
+	const request = { argv, cwd: PROJECT_ROOT, log_path, profile }
 	const result = await detached_launch.launch_attached(request, note)
 
 	if (result.kind === 'failed') return failure(`reviewer could not start: ${result.note}`)
@@ -91,15 +83,38 @@ async function run_session(prompt: string, log_path: string): Promise<JoshResult
 	return { code: SUCCESS_EXIT_CODE, out: '' }
 }
 
+async function run_session(
+	prompt: string,
+	log_path: string,
+	issue: string,
+	round: '1' | '2',
+): 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}`)
+
+	if (built.profile.provider !== 'openai' || !lane_child_marker.is_child_of(PROJECT_ROOT)) {
+		return await run_direct_session(built.argv, built.profile, log_path)
+	}
+
+	const is_success = await openai_review_broker.request(PROJECT_ROOT, issue, round)
+
+	return is_success ? { code: SUCCESS_EXIT_CODE, out: '' } : failure('isolated reviewer failed')
+}
+
 // The brief goes to a file and the previous round's findings are removed, so a reviewer that writes
 // nothing reads as unfinished rather than as the last round's verdict.
-async function launch_reviewer(brief: string, prompt_of: PromptOf): Promise<JoshResult> {
+async function launch_reviewer(
+	brief: string,
+	prompt_of: PromptOf,
+	issue: string,
+	round: '1' | '2',
+): Promise<JoshResult> {
 	const target = paths()
 
 	stamp_file.write_text_stamp(target.brief, brief)
 	stamp_file.remove_stamp(target.findings)
 
-	return await run_session(prompt_of(target.brief, target.findings), target.log)
+	return await run_session(prompt_of(target.brief, target.findings), target.log, issue, round)
 }
 
 function current_verdict(): ReturnType<typeof run_ship_review.read_verdict> {
@@ -150,7 +165,12 @@ async function run_phases(phases: ReadonlyArray<Phase>): Promise<JoshResult> {
 }
 
 // A brief-minting command, then a reviewer handed what it printed.
-function reviewed(open: ReadonlyArray<string>, prompt_of: PromptOf): ReadonlyArray<Phase> {
+function reviewed(
+	open: ReadonlyArray<string>,
+	prompt_of: PromptOf,
+	issue: string,
+	round: '1' | '2',
+): ReadonlyArray<Phase> {
 	const opened = { brief: '' }
 
 	return [
@@ -161,7 +181,7 @@ function reviewed(open: ReadonlyArray<string>, prompt_of: PromptOf): ReadonlyArr
 
 			return result
 		},
-		async () => await launch_reviewer(opened.brief, prompt_of),
+		async () => await launch_reviewer(opened.brief, prompt_of, issue, round),
 	]
 }
 
@@ -195,7 +215,7 @@ async function round_one_record(issue: string): Promise<JoshResult> {
 async function review_stage(issue: string): Promise<JoshResult> {
 	return await run_phases([
 		scoped_pair,
-		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt),
+		...reviewed([RUN_REVIEW], run_ship_review.reviewer_prompt, issue, '1'),
 		join_gate,
 		async () => await josh(ATTEST_CHECK),
 		async () => await round_one_record(issue),
@@ -216,7 +236,7 @@ async function round_two_stage(issue: string): Promise<JoshResult> {
 
 	return await run_phases([
 		scoped_pair,
-		...reviewed(ROUND_TWO_BRIEF, run_ship_review.verification_prompt),
+		...reviewed(ROUND_TWO_BRIEF, run_ship_review.verification_prompt, issue, '2'),
 		async () => await josh(ATTEST_CHECK),
 		async () => await record_and_route(issue, run_ship_review.round_two_outcome),
 	])

package/scripts/run/run-wake-session.ts

@@ -105,7 +105,9 @@ function wake_argv(
 	const matched = safe_invocation(invocation)
 	if (matched === undefined) return undefined
 	const prompt =
-		typeof session === 'object' ? `${matched}\n\nDriver handoff:\n${session.material}` : matched
+		typeof session === 'object'
+			? `${matched} | Driver handoff: ${session.material.replaceAll('\n', ' | ')}`
+			: matched
 	const session_id = typeof session === 'object' ? session.id : session
 
 	return profile === undefined

package/scripts/test/pilot-files.ts

@@ -253,7 +253,6 @@ const PILOT_FILES: ReadonlyArray<string> = [
 	'scripts/josh/kit-only.test.ts',
 	'scripts/josh/platform-temporary.test.ts',
 	'scripts/josh/process-identity.test.ts',
-	'scripts/lane/lane-await.test.ts',
 	'scripts/lane/lane-capacity.test.ts',
 	'scripts/lane/lane-child-invocation.test.ts',
 	'scripts/lane/lane-child-marker.test.ts',
@@ -399,7 +398,6 @@ const PILOT_FILES: ReadonlyArray<string> = [
 	'scripts/test/http-fault-injection.test.ts',
 	'scripts/test/pilot-config.test.ts',
 	'scripts/test/pilot-files.test.ts',
-	'scripts/test/test-declared-changed.test.ts',
 	'scripts/test/test-declared-document-rule.test.ts',
 	'scripts/test/test-declared-logic.test.ts',
 	'scripts/test/test-declared-match.test.ts',

package/scripts/test/skip-marker.ts

@@ -0,0 +1,3 @@
+const SKIP_MARKER = '— skipping'
+
+export { SKIP_MARKER }

package/scripts/test/test-declared-changed.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process'
+import { project_checks } from '#scripts/gate/project-checks'
 import { test_declared_logic, type Verdict } from './test-declared-logic'
 
 // The working-tree change set and the verdict over it, read **synchronously** for the `PreToolUse`
@@ -61,7 +62,7 @@ function source_paths(): ReadonlyArray<string> {
 // The verdict over the current working tree. `paths` stays injectable for a direct caller; when it is
 // omitted the injected set is read if one is in force, else the real tree.
 function current_verdict(paths: ReadonlyArray<string> = source_paths()): Verdict {
-	return test_declared_logic.verdict_for(paths)
+	return test_declared_logic.verdict_for(paths, project_checks.is_static(process.cwd()))
 }
 
 // Put the injection back to what it was before a `with_paths` span — cleared to the live reader when

package/scripts/test/test-declared-logic.ts

@@ -27,6 +27,7 @@ const TEST_SUFFIXES: ReadonlyArray<string> = ['.e2e.ts', '.test.ts']
 const EXEMPT_PATHS: ReadonlyArray<string> = ['.editorconfig']
 const EXEMPT_PREFIXES: ReadonlyArray<string> = ['.idea/', '.vscode/', 'prompts/']
 const EXEMPT_SUFFIXES: ReadonlyArray<string> = ['.md']
+const STATIC_VISUAL_SUFFIXES: ReadonlyArray<string> = ['.html', '.css']
 
 function normalize(paths: ReadonlyArray<string>): Array<string> {
 	return paths.map((path) => path.trim()).filter((path) => path !== '')
@@ -36,8 +37,12 @@ function is_test_file(path: string): boolean {
 	return TEST_SUFFIXES.some((suffix) => path.endsWith(suffix))
 }
 
-function is_exempt(path: string): boolean {
-	if (EXEMPT_PATHS.includes(path)) return true
+function is_static_visual(path: string, is_static: boolean): boolean {
+	return is_static && STATIC_VISUAL_SUFFIXES.some((suffix) => path.endsWith(suffix))
+}
+
+function is_exempt(path: string, is_static = false): boolean {
+	if (EXEMPT_PATHS.includes(path) || is_static_visual(path, is_static)) return true
 
 	return (
 		EXEMPT_SUFFIXES.some((suffix) => path.endsWith(suffix)) ||
@@ -47,31 +52,31 @@ function is_exempt(path: string): boolean {
 
 // A runtime file is one that is neither a test nor exempt. Its presence with no test file beside it is
 // the whole of what `required` reports.
-function is_runtime(path: string): boolean {
-	return !is_test_file(path) && !is_exempt(path)
+function is_runtime(path: string, is_static = false): boolean {
+	return !is_test_file(path) && !is_exempt(path, is_static)
 }
 
 // **A test file changed → `satisfied`, whatever else did.** A runtime file with no test beside it →
 // `required`. Everything left — an all-exempt change, and the empty diff — is `exempt`, because there
 // is no runtime file the change failed to test.
-function verdict_for(paths: ReadonlyArray<string>): Verdict {
+function verdict_for(paths: ReadonlyArray<string>, is_static = false): Verdict {
 	const changed = normalize(paths)
 
 	if (changed.some((path) => is_test_file(path))) return 'satisfied'
-	if (changed.some((path) => is_runtime(path))) return 'required'
+	if (changed.some((path) => is_runtime(path, is_static))) return 'required'
 
 	return 'exempt'
 }
 
 // The runtime files with no test beside them — the `required` detail line, so the answer says which
 // files it is about rather than only that it refused.
-function runtime_files(paths: ReadonlyArray<string>): Array<string> {
-	return normalize(paths).filter((path) => is_runtime(path))
+function runtime_files(paths: ReadonlyArray<string>, is_static = false): Array<string> {
+	return normalize(paths).filter((path) => is_runtime(path, is_static))
 }
 
 // The paths that made the change exempt — the `exempt` detail line.
-function exempt_files(paths: ReadonlyArray<string>): Array<string> {
-	return normalize(paths).filter((path) => is_exempt(path))
+function exempt_files(paths: ReadonlyArray<string>, is_static = false): Array<string> {
+	return normalize(paths).filter((path) => is_exempt(path, is_static))
 }
 
 const test_declared_logic = {

package/scripts/test/test-declared.ts

@@ -2,6 +2,7 @@
 import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
+import { project_checks } from '#scripts/gate/project-checks'
 import { test_declared_changed } from './test-declared-changed'
 import { test_declared_logic, type Verdict } from './test-declared-logic'
 import { test_declared_match, type MatchResult } from './test-declared-match'
@@ -76,24 +77,35 @@ function typed_runtime_file(path: string): string {
 }
 
 // The word is stdout so a caller can read it alone; the reason — which files, and why — is stderr.
-function detail_for(verdict: Verdict, paths: ReadonlyArray<string>): string {
+function exempt_detail(paths: ReadonlyArray<string>, is_static: boolean): string {
+	const exempt = test_declared_logic.exempt_files(paths, is_static)
+	const has_visual = is_static && exempt.some((path) => /\.(?:html|css)$/u.test(path))
+	const instruction = has_visual ? ' — confirm the rendered page in a browser' : ''
+
+	return `exempt paths: ${exempt.join(', ')}${instruction}`
+}
+
+function detail_for(verdict: Verdict, paths: ReadonlyArray<string>, is_static = false): string {
 	if (verdict === 'required') {
-		const typed = test_declared_logic.runtime_files(paths).map((path) => typed_runtime_file(path))
+		const typed = test_declared_logic
+			.runtime_files(paths, is_static)
+			.map((path) => typed_runtime_file(path))
 
 		return `runtime files with no test: ${typed.join(', ')}`
 	}
 
-	if (verdict === 'exempt') {
-		return `exempt paths: ${test_declared_logic.exempt_files(paths).join(', ')}`
-	}
+	if (verdict === 'exempt') return exempt_detail(paths, is_static)
 
 	return 'a test file changed'
 }
 
-function report(paths: ReadonlyArray<string>): { detail: string; verdict: Verdict } {
-	const verdict = test_declared_logic.verdict_for(paths)
+function report(
+	paths: ReadonlyArray<string>,
+	is_static: boolean = project_checks.is_static(process.cwd()),
+): { detail: string; verdict: Verdict } {
+	const verdict = test_declared_logic.verdict_for(paths, is_static)
 
-	return { detail: detail_for(verdict, paths), verdict }
+	return { detail: detail_for(verdict, paths, is_static), verdict }
 }
 
 function run(): void {