@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/uninstall/uninstall-plan.ts

@@ -0,0 +1,119 @@
+import { json_format } from '#scripts/config-merge/json-format'
+import { json_value } from '#scripts/lib/json-value'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+
+// One file kit writes into a project, with the content it writes there. `distributed` is absent when
+// that content cannot be worked out here — a file whose text depends on the repository it lands in,
+// read where there is no such repository — and such a file is never one this command may delete.
+interface DistributedFile {
+	dest: string
+	distributed: string | undefined
+}
+
+interface FilePlan {
+	remove: Array<string>
+	keep: Array<string>
+}
+
+type ReadFile = (destination: string) => string | undefined
+
+// Never deleted, even while it is still what kit wrote: without it the `.env` and `node_modules` it
+// kept out of Git turn into untracked files, and the next `git add -A` stages them.
+const IGNORE_FILE = '.gitignore'
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies']
+const JOSH_FIELD = 'josh'
+const PROFILE_FIELD = 'profile'
+// `strip_kit` takes kit's own entry back out of this field, so it is not left for a person to review.
+const HANDLED_FIELDS: ReadonlySet<string> = new Set([JOSH_FIELD])
+
+// A file is deleted only while it is still, byte for byte, what kit writes: anything else holds the
+// project's own lines — an edit, or a file kit merged its entries into — and kit kept no record of
+// which lines those are.
+function classify_files(files: ReadonlyArray<DistributedFile>, read_file: ReadFile): FilePlan {
+	const present = files
+		.map((file) => ({ ...file, existing: read_file(file.dest) }))
+		.filter((file) => file.existing !== undefined)
+	const untouched = new Set(
+		present.filter((file) => file.existing === file.distributed).map((file) => file.dest),
+	)
+	const destinations = [...new Set(present.map((file) => file.dest))]
+
+	return {
+		remove: destinations.filter((destination) => untouched.has(destination)),
+		keep: destinations.filter((destination) => !untouched.has(destination)),
+	}
+}
+
+function parse_manifest(manifest_text: string): Record<string, unknown> {
+	const parsed: unknown = JSON.parse(manifest_text)
+
+	if (!json_value.is_record(parsed)) throw new Error('package.json must contain an object')
+
+	return parsed
+}
+
+function without_key(record: Record<string, unknown>, key: string): Record<string, unknown> {
+	return Object.fromEntries(Object.entries(record).filter(([name]) => name !== key))
+}
+
+// The field with one key taken out of the object it holds — and the field itself once that leaves
+// the object empty, so a manifest kit created is not left carrying `"devDependencies": {}`.
+function without_nested_key(
+	manifest: Record<string, unknown>,
+	field: string,
+	key: string,
+): Record<string, unknown> {
+	const value = manifest[field]
+	if (!json_value.is_record(value) || !Object.hasOwn(value, key)) return manifest
+	const rest = without_key(value, key)
+
+	return Object.keys(rest).length === 0
+		? without_key(manifest, field)
+		: { ...manifest, [field]: rest }
+}
+
+// The manifest without kit's dependency entry and its profile record — the two entries that are
+// kit's alone, so removing them cannot take anything of the project's.
+function strip_kit(manifest_text: string): string {
+	let manifest = without_nested_key(parse_manifest(manifest_text), JOSH_FIELD, PROFILE_FIELD)
+
+	for (const field of DEPENDENCY_FIELDS) {
+		manifest = without_nested_key(manifest, field, KIT_PACKAGE_NAME)
+	}
+
+	return json_format.format_package_json(manifest)
+}
+
+// Whether the manifest still holds an entry `strip_kit` takes out — asked of the parsed manifest, so
+// a file indented another way is not mistaken for one that has something to remove.
+function has_kit_entries(manifest_text: string): boolean {
+	const unchanged = json_format.format_package_json(parse_manifest(manifest_text))
+
+	return strip_kit(manifest_text) !== unchanged
+}
+
+function shared_entries(field: string, kit_value: unknown, project_value: unknown): Array<string> {
+	if (project_value === undefined) return []
+	if (!json_value.is_record(kit_value) || !json_value.is_record(project_value)) return [field]
+
+	return Object.keys(kit_value)
+		.filter((key) => key !== KIT_PACKAGE_NAME && Object.hasOwn(project_value, key))
+		.map((key) => `${field}.${key}`)
+}
+
+// The manifest entries kit merges in that the project still holds, named `scripts.preinstall` style.
+// `kit_manifest_text` is what kit's own merge writes into an empty manifest, so the names come from
+// the merge and not from a second list of them. They are reported, never removed: the merge kept no
+// record of the value it found, so a script named `josh` may be kit's or the project's own.
+function manifest_review(manifest_text: string, kit_manifest_text: string): Array<string> {
+	const manifest = parse_manifest(manifest_text)
+
+	return Object.entries(parse_manifest(kit_manifest_text))
+		.filter(([field]) => !HANDLED_FIELDS.has(field))
+		.flatMap(([field, kit_value]) => shared_entries(field, kit_value, manifest[field]))
+}
+
+const uninstall_plan = { classify_files, strip_kit, has_kit_entries, manifest_review }
+
+export { uninstall_plan, IGNORE_FILE }
+export type { DistributedFile, FilePlan }

package/scripts/uninstall/uninstall-report.ts

@@ -0,0 +1,61 @@
+import type { FilePlan } from './uninstall-plan'
+
+interface UninstallPlan {
+	files: FilePlan
+	// Whether kit's dependency entry or profile record is still in `package.json` to take out.
+	has_manifest_entries: boolean
+	// Whether lefthook is installed here with a config kit wrote or merged into.
+	has_git_hooks: boolean
+	review: Array<string>
+}
+
+const NOTHING = '  (nothing)'
+// The review comes first: the install runs whatever `scripts.prepare` is still in the manifest, and
+// the one kit merged in installs lefthook's hooks again.
+const NEXT_STEPS = [
+	'First clear "Review by hand" — a `scripts.prepare` left there reinstalls the git hooks.',
+	'Run `pnpm install` — it drops the package from node_modules and pnpm-lock.yaml.',
+	'Delete node_modules and pnpm-lock.yaml yourself if kit was the only dependency.',
+	'Labels, Issues and pull requests `josh start` created on GitHub are not touched.',
+]
+
+function section(title: string, lines: ReadonlyArray<string>): string {
+	const body = lines.length === 0 ? [NOTHING] : lines.map((line) => `  ${line}`)
+
+	return [`${title}:`, ...body].join('\n')
+}
+
+function removal_lines(plan: UninstallPlan): Array<string> {
+	const lines = [...plan.files.remove]
+
+	if (plan.has_manifest_entries) {
+		lines.push('package.json — the @joshuafolkken/kit dependency and the josh.profile record')
+	}
+
+	if (plan.has_git_hooks) lines.push('git hooks installed by lefthook (lefthook uninstall)')
+
+	return lines
+}
+
+// Printed before anything is deleted, so the three lists are the whole of what the command will do
+// and of what it leaves for a person: nothing outside the first one is ever written to.
+function describe(plan: UninstallPlan): string {
+	return [
+		section('Remove (still exactly what kit wrote)', removal_lines(plan)),
+		section('Keep (differs from what kit writes — remove kit lines by hand)', plan.files.keep),
+		section('Review by hand (kit cannot tell these from your own)', plan.review),
+	].join('\n\n')
+}
+
+function next_steps(): string {
+	return section('Next', NEXT_STEPS)
+}
+
+function is_empty(plan: UninstallPlan): boolean {
+	return removal_lines(plan).length === 0
+}
+
+const uninstall_report = { describe, next_steps, is_empty }
+
+export { uninstall_report }
+export type { UninstallPlan }

package/scripts/uninstall/uninstall.ts

@@ -0,0 +1,206 @@
+#!/usr/bin/env tsx
+import { existsSync, readdirSync, rmdirSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { stdin as input, stdout as output } from 'node:process'
+import { createInterface } from 'node:readline/promises'
+import { fileURLToPath } from 'node:url'
+import { resolve_local_bin } from '#scripts/build/local-bin'
+import { ask_yes_no_simple } from '#scripts/git/git-prompt'
+import { LEFTHOOK_PATH } from '#scripts/init/init-actions'
+import { init_logic_sonar } from '#scripts/init/init-logic-sonar'
+import { PACKAGE_DIR, PROJECT_ROOT } from '#scripts/init/init-paths'
+import { project_profile, type ProjectProfile } from '#scripts/init/project-profile'
+import { error_text } from '#scripts/lib/error-message'
+import { file_reader } from '#scripts/lib/read-file'
+import { PROJECT_CONFIG_FILE } from '#scripts/safe-chain/project-config'
+import { did_refuse_self_run } from '#scripts/self-sync-guard/self-sync-refusal'
+import { KIT_PACKAGE_NAME } from '#scripts/version/kit-descriptor'
+import { execaSync } from 'execa'
+import { distributed_files } from './distributed-files'
+import { IGNORE_FILE, uninstall_plan, type FilePlan } from './uninstall-plan'
+import { uninstall_report, type UninstallPlan } from './uninstall-report'
+
+const PACKAGE_JSON = 'package.json'
+const LEFTHOOK_BIN = 'lefthook'
+const ARGUMENT_START_INDEX = 2
+const YES_FLAG = '--yes'
+const UNINSTALL_USAGE = 'josh uninstall [--profile basic|full] [--yes]'
+const QUESTION = 'Remove the files and entries listed under "Remove"? (y/n): '
+const NOT_CONFIRMED = 'Nothing was removed.'
+const NO_TERMINAL = `${NOT_CONFIRMED} This is a preview: there is no terminal to confirm on, so pass --yes to remove what is listed.`
+// Written from the repository's own name and settings, so there is no distributed content to compare
+// them with: they are named for review and never deleted.
+const REVIEW_ONLY_FILES = [init_logic_sonar.get_sonar_template_destination(), PROJECT_CONFIG_FILE]
+const IGNORE_FILE_REVIEW = `${IGNORE_FILE} — delete it only once nothing it ignores (.env, node_modules) is left`
+
+interface Options {
+	is_yes: boolean
+	profile: ProjectProfile
+}
+
+function project_path(relative_path: string): string {
+	return path.join(PROJECT_ROOT, relative_path)
+}
+
+function read_project_file(relative_path: string): string | undefined {
+	return file_reader.read_if_readable(project_path(relative_path))
+}
+
+function parse_options(args: ReadonlyArray<string>): Options {
+	const rest = args.filter((argument) => argument !== YES_FLAG)
+	const requested = project_profile.requested_profile(rest, UNINSTALL_USAGE)
+
+	return {
+		is_yes: args.includes(YES_FLAG),
+		profile: project_profile.resolve_profile(PROJECT_ROOT, requested).profile,
+	}
+}
+
+// A lefthook config the profile distributes that still names the package — the one kit wrote, or the
+// project's own with kit's preset merged in. One that names it nowhere is the project's alone.
+function has_kit_lefthook_config(files: FilePlan): boolean {
+	if (![...files.remove, ...files.keep].includes(LEFTHOOK_PATH)) return false
+
+	return read_project_file(LEFTHOOK_PATH)?.includes(KIT_PACKAGE_NAME) === true
+}
+
+// Hooks are taken out only where the lefthook config is one kit wrote or merged into: once kit is
+// gone that config extends a preset that no longer exists, and a hook left in `.git/hooks` would
+// fail every commit on it.
+function has_git_hooks(files: FilePlan): boolean {
+	return (
+		has_kit_lefthook_config(files) &&
+		existsSync(project_path('.git')) &&
+		existsSync(resolve_local_bin(PROJECT_ROOT, LEFTHOOK_BIN))
+	)
+}
+
+function review_entries(manifest: string | undefined, profile: ProjectProfile): Array<string> {
+	const merged =
+		manifest === undefined
+			? []
+			: uninstall_plan.manifest_review(manifest, distributed_files.kit_manifest(profile))
+
+	return [
+		...merged.map((entry) => `${PACKAGE_JSON} ${entry}`),
+		...REVIEW_ONLY_FILES.filter((file) => existsSync(project_path(file))),
+		...(existsSync(project_path(IGNORE_FILE)) ? [IGNORE_FILE_REVIEW] : []),
+	]
+}
+
+function build_plan(profile: ProjectProfile): UninstallPlan {
+	const files = uninstall_plan.classify_files(distributed_files.list(profile), read_project_file)
+	const manifest = read_project_file(PACKAGE_JSON)
+
+	return {
+		files,
+		has_manifest_entries: manifest !== undefined && uninstall_plan.has_kit_entries(manifest),
+		has_git_hooks: has_git_hooks(files),
+		review: review_entries(manifest, profile),
+	}
+}
+
+async function is_confirmed(is_yes: boolean): Promise<boolean> {
+	if (is_yes) return true
+
+	if (!process.stdin.isTTY) {
+		console.info(`\n${NO_TERMINAL}`)
+
+		return false
+	}
+
+	const prompt = createInterface({ input, output })
+
+	try {
+		const is_accepted = await ask_yes_no_simple(prompt, `\n${QUESTION}`)
+		if (!is_accepted) console.info(NOT_CONFIRMED)
+
+		return is_accepted
+	} finally {
+		prompt.close()
+	}
+}
+
+// Run before the config is deleted, while lefthook can still read the project it is leaving.
+function remove_git_hooks(): void {
+	const bin = resolve_local_bin(PROJECT_ROOT, LEFTHOOK_BIN)
+	const result = execaSync(bin, ['uninstall'], {
+		cwd: PROJECT_ROOT,
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	if (result.exitCode === 0) console.info('  ✔ removed   git hooks')
+	else console.warn('  ⚠ lefthook uninstall failed — run it manually: lefthook uninstall')
+}
+
+function is_empty_directory(directory: string): boolean {
+	return existsSync(directory) && readdirSync(directory).length === 0
+}
+
+// A directory kit created for its own file — `.vscode`, `.github` — goes with the last file in it,
+// and one that still holds anything of the project's stays.
+function remove_empty_parents(relative_path: string): void {
+	let directory = path.dirname(relative_path)
+
+	while (directory !== '.' && is_empty_directory(project_path(directory))) {
+		rmdirSync(project_path(directory))
+		directory = path.dirname(directory)
+	}
+}
+
+function remove_file(relative_path: string): void {
+	rmSync(project_path(relative_path))
+	remove_empty_parents(relative_path)
+	console.info(`  ✔ removed   ${relative_path}`)
+}
+
+function strip_manifest(): void {
+	const manifest = read_project_file(PACKAGE_JSON)
+	if (manifest === undefined) return
+
+	writeFileSync(project_path(PACKAGE_JSON), uninstall_plan.strip_kit(manifest))
+	console.info(`  ✔ updated   ${PACKAGE_JSON}`)
+}
+
+function execute(plan: UninstallPlan): void {
+	console.info('\nRemoving:')
+	if (plan.has_git_hooks) remove_git_hooks()
+	for (const file of plan.files.remove) remove_file(file)
+	if (plan.has_manifest_entries) strip_manifest()
+	console.info(`\n${uninstall_report.next_steps()}\n\n✅ Done.\n`)
+}
+
+// The refusal `josh init` and `josh sync` make, for the opposite damage: in kit's own repository
+// every distributed file is the source, and each of them equals what kit distributes.
+async function main(args: ReadonlyArray<string> = []): Promise<void> {
+	if (did_refuse_self_run(PACKAGE_DIR, PROJECT_ROOT)) return
+	const options = parse_options(args)
+	const plan = build_plan(options.profile)
+
+	console.info(`\n🧹 Uninstalling @joshuafolkken/kit (profile: ${options.profile})\n`)
+	console.info(uninstall_report.describe(plan))
+
+	if (uninstall_report.is_empty(plan)) {
+		console.info('\nNothing of kit is left to remove.\n')
+
+		return
+	}
+
+	if (await is_confirmed(options.is_yes)) execute(plan)
+}
+
+async function run_cli(args: ReadonlyArray<string>): Promise<void> {
+	try {
+		await main(args)
+	} catch (error) {
+		console.error(`\n✖ ${error_text.message_of(error)}\n`)
+		process.exitCode = 1
+	}
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	await run_cli(process.argv.slice(ARGUMENT_START_INDEX))
+}
+
+export { main }

package/templates/AGENTS.basic.md

@@ -0,0 +1,4 @@
+# Agent Instructions
+
+> **All rules for this project live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
+> any work here, and follow every rule in it.** This file exists only to point at it.

package/templates/GEMINI.basic.md

@@ -0,0 +1,6 @@
+# Agent Instructions
+
+> **All rules for this project live in [`CLAUDE.md`](./CLAUDE.md). Read it in full before doing
+> any work here, and follow every rule in it.** This file exists only to point at it.
+
+@CLAUDE.md

package/dist/hooks/chunk-6V5OPIUU.js

@@ -1,13 +0,0 @@
-// scripts/josh/session-language.ts
-var ENV_KEY = "JOSH_SESSION_LANG";
-var DEFAULT_SESSION_LANG = "ja";
-function resolve_session_lang() {
-  const value = process.env[ENV_KEY]?.trim();
-  if (value) return { lang: value, is_default: false };
-  return { lang: DEFAULT_SESSION_LANG, is_default: true };
-}
-var session_language = { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang };
-
-export {
-  session_language
-};

package/scripts/lane/openai-review-broker.ts

@@ -1,262 +0,0 @@
-import { randomUUID } from 'node:crypto'
-import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
-import path from 'node:path'
-import { setTimeout as sleep } from 'node:timers/promises'
-import { agent_argv } from '#scripts/agent/agent-argv'
-import { agent_role_profile } from '#scripts/agent/agent-role-profile'
-import { git_common_directory } from '#scripts/git/git-common-directory'
-import { stamp_file } from '#scripts/josh/stamp-file'
-import { error_text } from '#scripts/lib/error-message'
-import { json_value } from '#scripts/lib/json-value'
-import { detached_launch } from '#scripts/run/detached-launch'
-import { run_ship_review } from '#scripts/run/ship/run-ship-review'
-import { z } from 'zod'
-import type { LaneInfo } from './lane-registry'
-
-const REQUEST_PREFIX = '.josh-review-request-'
-const RESPONSE_PREFIX = '.josh-review-response-'
-const BRIEF_PREFIX = 'josh-ship-review-brief-'
-const FINDINGS_PREFIX = 'josh-ship-review-findings-'
-const LOG_PREFIX = 'josh-ship-review-log-'
-const CACHE_DIRECTORY = ['node_modules', '.cache']
-const POLL_MS = 100
-const HEARTBEAT_MS = 500
-const HEARTBEAT_LIMIT_MS = 3000
-const MINUTE_MS = 60_000
-const REQUEST_LIMIT_MINUTES = 30
-const REQUEST_LIMIT_MS = REQUEST_LIMIT_MINUTES * MINUTE_MS
-const request_schema = z
-	.object({ session: z.uuid(), nonce: z.uuid(), round: z.enum(['1', '2']) })
-	.strict()
-const response_schema = z
-	.object({
-		session: z.uuid(),
-		nonce: z.string(),
-		is_success: z.boolean(),
-		heartbeat_at: z.number().int().positive(),
-	})
-	.strict()
-type ReviewRequest = z.infer<typeof request_schema>
-type ReviewResponse = z.infer<typeof response_schema>
-type ReviewRound = ReviewRequest['round']
-
-function review_paths(directory: string): { brief: string; findings: string; log: string } {
-	return {
-		brief: stamp_file.stamp_path(BRIEF_PREFIX, directory, '.md'),
-		findings: stamp_file.stamp_path(FINDINGS_PREFIX, directory, '.txt'),
-		log: stamp_file.stamp_path(LOG_PREFIX, directory, '.log'),
-	}
-}
-
-function request_path(directory: string, issue: string): string {
-	return path.join(directory, ...CACHE_DIRECTORY, `${REQUEST_PREFIX}${issue}.json`)
-}
-
-function response_path(directory: string, issue: string): string | undefined {
-	const common = git_common_directory.resolve(directory)
-	if (common === undefined || path.basename(common) !== '.git') return undefined
-
-	return path.join(path.dirname(common), ...CACHE_DIRECTORY, `${RESPONSE_PREFIX}${issue}.json`)
-}
-
-function read_record<T>(target: string, schema: z.ZodType<T>): T | undefined {
-	try {
-		return json_value.parse_with(readFileSync(target, 'utf8'), schema)
-	} catch {
-		return undefined
-	}
-}
-
-async function launch_review(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
-	const target = review_paths(lane.directory)
-	const prompt_of =
-		round === '1' ? run_ship_review.reviewer_prompt : run_ship_review.verification_prompt
-	const built = agent_argv.resolve_in(
-		prompt_of(target.brief, target.findings),
-		agent_role_profile.REVIEWER,
-		lane.directory,
-	)
-	if (built.kind === 'rejected' || built.profile.provider !== 'openai') return false
-
-	const result = await detached_launch.launch_attached(
-		{
-			argv: built.argv,
-			cwd: lane.directory,
-			log_path: target.log,
-			profile: built.profile,
-		},
-		console.error,
-	)
-
-	return result.kind === 'completed' && result.exit_code === 0
-}
-
-function write_response(target: string, body: z.infer<typeof response_schema>): void {
-	const temporary = `${target}.${String(process.pid)}.tmp`
-
-	writeFileSync(temporary, JSON.stringify(body))
-	renameSync(temporary, target)
-}
-
-async function launched(lane: LaneInfo, round: ReviewRound): Promise<boolean> {
-	try {
-		return await launch_review(lane, round)
-	} catch (error) {
-		error_text.trace_swallowed('openai_review_broker.launched', error)
-
-		return false
-	}
-}
-
-async function process_request(
-	lane: LaneInfo,
-	response: string,
-	received: ReviewRequest,
-	state: { current: ReviewResponse },
-): Promise<void> {
-	const is_success = await launched(lane, received.round)
-
-	state.current = {
-		session: received.session,
-		nonce: received.nonce,
-		is_success,
-		heartbeat_at: Date.now(),
-	}
-	write_response(response, state.current)
-}
-
-async function serve(
-	lane: LaneInfo,
-	session: string,
-	response: string,
-	state: { is_running: boolean; current: ReviewResponse },
-): Promise<void> {
-	let last_nonce = ''
-	const target = request_path(lane.directory, lane.issue)
-
-	while (state.is_running) {
-		const received = read_record(target, request_schema)
-
-		if (received?.session === session && received.nonce !== last_nonce) {
-			last_nonce = received.nonce
-			// eslint-disable-next-line no-await-in-loop -- requests are served one at a time, in arrival order
-			await process_request(lane, response, received, state)
-		}
-
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await sleep(POLL_MS)
-	}
-}
-
-function prepare(lane: LaneInfo): { response: string; current: ReviewResponse } {
-	const response = response_path(lane.directory, lane.issue)
-	if (response === undefined) throw new Error('review broker has no trusted response location')
-
-	const session = randomUUID()
-
-	mkdirSync(path.dirname(response), { recursive: true })
-	mkdirSync(path.dirname(request_path(lane.directory, lane.issue)), { recursive: true })
-	const current: ReviewResponse = {
-		session,
-		nonce: '',
-		is_success: false,
-		heartbeat_at: Date.now(),
-	}
-
-	write_response(response, current)
-
-	return { response, current }
-}
-
-function start_heartbeat(state: { current: ReviewResponse }, response: string): NodeJS.Timeout {
-	const heartbeat = setInterval(() => {
-		state.current = { ...state.current, heartbeat_at: Date.now() }
-		write_response(response, state.current)
-	}, HEARTBEAT_MS)
-
-	heartbeat.unref()
-
-	return heartbeat
-}
-
-async function stop_server(
-	state: { is_running: boolean },
-	heartbeat: NodeJS.Timeout,
-	serving: Promise<void>,
-	response: string,
-): Promise<void> {
-	clearInterval(heartbeat)
-	state.is_running = false
-	await serving
-	unlinkSync(response)
-}
-
-async function with_server<T>(lane: LaneInfo, run: () => Promise<T>): Promise<T> {
-	const { response, current } = prepare(lane)
-	const state = { is_running: true, current }
-	const heartbeat = start_heartbeat(state, response)
-	const serving = serve(lane, current.session, response, state)
-
-	try {
-		return await run()
-	} finally {
-		await stop_server(state, heartbeat, serving, response)
-	}
-}
-
-function is_live_response(
-	response: ReviewResponse | undefined,
-	session: string,
-): response is ReviewResponse {
-	const now = Date.now()
-
-	return (
-		response?.session === session &&
-		response.heartbeat_at <= now &&
-		response.heartbeat_at >= now - HEARTBEAT_LIMIT_MS
-	)
-}
-
-function response_verdict(
-	response: ReviewResponse | undefined,
-	session: string,
-	nonce: string,
-): 'wait' | 'success' | 'failure' {
-	if (!is_live_response(response, session)) return 'failure'
-	if (response.nonce !== nonce) return 'wait'
-
-	return response.is_success ? 'success' : 'failure'
-}
-
-async function wait_response(target: string, session: string, nonce: string): Promise<boolean> {
-	const deadline = Date.now() + REQUEST_LIMIT_MS
-
-	while (Date.now() < deadline) {
-		const verdict = response_verdict(read_record(target, response_schema), session, nonce)
-		if (verdict !== 'wait') return verdict === 'success'
-
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await sleep(POLL_MS)
-	}
-
-	return false
-}
-
-async function request(directory: string, issue: string, round: ReviewRound): Promise<boolean> {
-	const target = response_path(directory, issue)
-	if (target === undefined) return false
-	const response = read_record(target, response_schema)
-
-	if (response === undefined || !is_live_response(response, response.session)) return false
-
-	const nonce = randomUUID()
-	const body: ReviewRequest = { session: response.session, nonce, round }
-
-	stamp_file.replace_stamp(request_path(directory, issue), body)
-
-	return await wait_response(target, response.session, nonce)
-}
-
-const openai_review_broker = { request, request_path, response_path, review_paths, with_server }
-
-export { openai_review_broker }