@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lint/lint-related.ts

@@ -1,8 +1,11 @@
 #!/usr/bin/env tsx
 import { existsSync } from 'node:fs'
+import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { document_byte_check } from '#scripts/document/document-byte-check'
+import { gate_plan } from '#scripts/gate/gate-plan'
 import { scoped_green } from '#scripts/gate/scoped-green'
+import { since_green } from '#scripts/gate/since-green'
 import { changed_file_scope, type ChangedFileScope } from '#scripts/git/changed-file-scope'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { lint_parallel } from './lint-parallel'
@@ -36,7 +39,8 @@ async function lint_exit_code(scope: ChangedFileScope): Promise<number> {
 	return await lint_parallel.run_lint_checks(
 		lint_related_scope.prettier_arguments(scope.files),
 		lint_related_scope.eslint_arguments(scope.files),
-		lint_related_scope.cross_file_recheck_options(scope.files),
+		lint_related_scope.RELATED_CACHES.eslint_file,
+		{ warm_daemon: true },
 	)
 }
 
@@ -63,6 +67,38 @@ async function scoped_exit_code(scope: ChangedFileScope, root: string): Promise<
 	return byte_check_exit_code(scope, root)
 }
 
+// **A bare run reads only what moved since its last green run** (`since-green.ts`), while a lintable file
+// is among it; otherwise the whole branch change, as before.
+async function since_green_scope(root: string): Promise<ChangedFileScope | undefined> {
+	const moved = await since_green.read_moved(review_stamps.lint_related_stamp, gate_plan.LINT_LABEL)
+
+	if (moved === undefined) return undefined
+
+	const inputs = lint_related_scope.scope_inputs(existsSync)
+	const files = moved.map((file) => path.join(root, file))
+
+	if (changed_file_scope.select_files(files, inputs).length === 0) return undefined
+
+	process.stdout.write(`${since_green.describe(lint_related_scope.COMMAND_LABEL, moved)}\n`)
+
+	return changed_file_scope.resolve_scope(files, inputs)
+}
+
+async function resolve_lint_scope(
+	command_arguments: ReadonlyArray<string>,
+	root: string,
+): Promise<ChangedFileScope> {
+	const since = command_arguments.length === 0 ? await since_green_scope(root) : undefined
+
+	if (since !== undefined) return since
+
+	return await changed_file_scope.resolve_command_scope({
+		command_arguments,
+		root,
+		inputs: lint_related_scope.scope_inputs(existsSync),
+	})
+}
+
 // The narrowing line is printed before either child starts, so a scoped run is never read as a
 // whole one, and a fallback says which of the two it was rather than looking like a narrow run
 // that found nothing.
@@ -72,11 +108,7 @@ async function scoped_exit_code(scope: ChangedFileScope, root: string): Promise<
 // and the three states in which it is withheld, are `scoped-green.ts`.
 async function run_related_lint(command_arguments: ReadonlyArray<string>): Promise<number> {
 	const root = await changed_file_scope.repository_root_or_cwd()
-	const scope = await changed_file_scope.resolve_command_scope({
-		command_arguments,
-		root,
-		inputs: lint_related_scope.scope_inputs(existsSync),
-	})
+	const scope = await resolve_lint_scope(command_arguments, root)
 
 	changed_file_scope.report_unusable_arguments(
 		command_arguments,

package/scripts/notify/confirmation-options.ts

@@ -15,7 +15,6 @@ interface Headings {
 	none: string
 }
 
-const JAPANESE_LANG_PREFIX = 'ja'
 const JAPANESE_HEADINGS: Headings = {
 	recommended: '推奨:',
 	alternatives: '他の選択肢:',
@@ -31,7 +30,7 @@ const ENGLISH_HEADINGS: Headings = {
 function headings(): Headings {
 	const { lang } = session_language.resolve_session_lang()
 
-	return lang.toLowerCase().startsWith(JAPANESE_LANG_PREFIX) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS
+	return session_language.is_japanese(lang) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS
 }
 
 // An empty list is stated as none, so a confirmation with no other option says so rather than

package/scripts/notify/telegram-notify.ts

@@ -20,14 +20,14 @@ const telegram_environment_schema = z.object({
 // Sending `failure` (❌) there would say the merge failed, which is false and is
 // the more expensive lie of the two; sending `completion` (✅) twice says nothing went wrong, which
 // is the silence this type exists to end.
-// **`stalled` is not `warning`**. `warning` names a run that *finished* and
-// merged alongside something that did not work; a stall is the opposite — the run is alive and has not
-// finished, it has simply stopped advancing while ready work waits for a free lane. The ⏳ icon says
-// exactly that: not done, not broken, just not moving.
-// **`stranded` is not `stalled`**. A stall is a *live* run that is not
-// dispatching; a strand is the step before it — the run's own driver is gone. The session that cut the
-// budget handed it off and died, no successor claimed it, and no supervisor is watching, so nothing can
-// take the next step at all. The 🚨 icon says a run needs a hand, not that ready work is merely waiting.
+// **`idle` is not `warning`**. `warning` names a run that *finished* and
+// merged alongside something that did not work; an idle run is alive and has not finished — it has
+// nothing left to dispatch and no child running, so what remains waits on a person. The 💤 icon says
+// exactly that: not done, not broken, just waiting for a hand.
+// **`stranded` is not `idle`**. An idle run still has a driver watching the
+// backlog; a stranded one has none. The session that cut the budget handed it off and died, no
+// successor claimed it, and no supervisor is watching, so nothing can take the next step at all. The
+// 🚨 icon says a run needs a hand to keep running at all.
 type TelegramTaskType =
 	| 'planning'
 	| 'completion'
@@ -35,7 +35,7 @@ type TelegramTaskType =
 	| 'warning'
 	| 'kickoff_retry'
 	| 'confirmation'
-	| 'stalled'
+	| 'idle'
 	| 'stranded'
 	| 'progress'
 
@@ -68,7 +68,7 @@ const TASK_DEFINITIONS: Record<TelegramTaskType, TaskDefinition> = {
 	warning: { icon: '⚠️', label: 'Completed with a warning' },
 	kickoff_retry: { icon: '🔄', label: 'Kickoff retry' },
 	confirmation: { icon: '⏸️', label: 'Confirmation required' },
-	stalled: { icon: '⏳', label: 'Ready work is sitting undispatched' },
+	idle: { icon: '💤', label: 'Backlog run idle — nothing left to dispatch' },
 	stranded: { icon: '🚨', label: 'Run stranded — nobody is driving it' },
 	progress: { icon: '📊', label: 'Progress' },
 }
@@ -389,25 +389,25 @@ async function confirm(input: ConfirmInput): Promise<boolean> {
 	)
 }
 
-interface StalledInput {
+interface IdleInput {
 	body: string
 	recovery: string
 }
 
 /**
- * Push the ⏳ stalled type — ready backlog work with a free lane that nothing has dispatched for a while.
- * Off-screen is the whole point: the state is invisible on the terminal until
- * a person asks, so it reaches them where they are not watching.
+ * Push the 💤 idle type — a backlog run with no child running and nothing left to dispatch.
+ * Off-screen is the whole point: what is left waits on a person, and the
+ * terminal shows that only to someone already watching.
  *
  * **`warn`'s shape exactly** — the repository looked up under the shared bound, the tolerant
- * `send_or_report` so a gateway timeout at Telegram never fails the detector that is only reporting, and
+ * `send_or_report` so a gateway timeout at Telegram never fails the loop that is only reporting, and
  * the caller's own `recovery` line. No `issue_title`: the header label already names what this is, and
  * the body carries what is waiting, so a title line would only repeat the header.
  */
-async function stalled(input: StalledInput): Promise<boolean> {
+async function idle(input: IdleInput): Promise<boolean> {
 	return await send_or_report(
 		{
-			task_type: 'stalled',
+			task_type: 'idle',
 			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
 			issue_title: undefined,
 			body: input.body,
@@ -425,11 +425,11 @@ interface StrandedInput {
 
 /**
  * Push the 🚨 stranded type — a run whose driver is gone and which nothing can advance.
- * Off-screen is the whole point, as it is for `stalled`: the state is
+ * Off-screen is the whole point, as it is for `idle`: the state is
  * invisible on the terminal because the session that would show it has died, so the person hears about
  * it where they are not watching, rather than by asking.
  *
- * **`stalled`'s shape exactly** — the repository looked up under the shared bound, the tolerant
+ * **`idle`'s shape exactly** — the repository looked up under the shared bound, the tolerant
  * `send_or_report` so a Telegram timeout never fails the detector that is only reporting, and the
  * caller's own `recovery` line naming the command that hands the run to a fresh supervisor. No
  * `issue_title`: the header label already names what this is.
@@ -471,10 +471,10 @@ async function progress(body: string): Promise<boolean> {
 
 const telegram_notify = {
 	confirm,
+	idle,
 	progress,
 	send,
 	send_or_report,
-	stalled,
 	stranded,
 	warn,
 }

package/scripts/notify/telegram-test-logic.ts

@@ -28,7 +28,6 @@ const VALID_TASK_TYPES: ReadonlyArray<TelegramTaskType> = [
 	'warning',
 	'kickoff_retry',
 	'confirmation',
-	'stalled',
 ]
 
 const DEFAULT_TASK_TYPE: TelegramTaskType = 'planning'

package/scripts/notify/telegram-test-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { telegram_test } from './telegram-test'
+
+// The `josh notify` entry, kept apart from `telegram-test.ts` because the stop hook and
+// `run-stop-notify.ts` import that one: a bundle is one file, so a main guard there would fire for
+// every command that carries it (joshuafolkken/kit#4186). The flags are read from `process.argv`.
+if (process.argv[1] === fileURLToPath(import.meta.url)) await telegram_test.run_cli()

package/scripts/notify/telegram-test.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { github_issue_url, type IssueUrlTarget } from '#scripts/gh/github-issue-url'
@@ -112,6 +110,14 @@ async function resolve_context(values: CliValues): Promise<ResolvedContext> {
 	return { repo_name, issue_title }
 }
 
+// The send behind the command line, for a caller that already holds the values — the `Stop` hook's
+// own confirmation (`stop-actions.ts`). It throws as `telegram_notify.send` does.
+async function send_values(values: CliValues): Promise<void> {
+	const context = await resolve_context(values)
+
+	await telegram_notify.send(telegram_test_logic.build_input({ values, context }))
+}
+
 async function main(): Promise<void> {
 	josh_environment_file.load_environment_file()
 	const values = parse_cli_arguments()
@@ -122,10 +128,7 @@ async function main(): Promise<void> {
 		return
 	}
 
-	const context = await resolve_context(values)
-	const input = telegram_test_logic.build_input({ values, context })
-
-	await telegram_notify.send(input)
+	await send_values(values)
 }
 
 // **A notification nobody received must not read as success**. This command
@@ -136,8 +139,8 @@ async function main(): Promise<void> {
 // and exits non-zero. Both the message and the `cause` whose text `handle` also prints reach it
 // already free of the bot token and the chat id — `telegram_notify` redacts each before throwing.
 //
-// Separated from the `import.meta.url` guard so the wiring is reachable from a unit test; the guard
-// itself stays the canonical one the in-process dispatcher matches on.
+// The `josh notify` entry is `telegram-test-main.ts`, kept apart because other modules import this one
+// (joshuafolkken/kit#4186).
 async function run_cli(): Promise<void> {
 	try {
 		await main()
@@ -146,8 +149,6 @@ async function run_cli(): Promise<void> {
 	}
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await run_cli()
-
-const telegram_test = { fetch_repo_name, fetch_issue_title, resolve_context, run_cli }
+const telegram_test = { fetch_repo_name, fetch_issue_title, resolve_context, run_cli, send_values }
 
 export { telegram_test }

package/scripts/observations/observation-ledger.ts

@@ -89,6 +89,18 @@ function is_ledger_path(file_path: string): boolean {
 	)
 }
 
+// The git pathspec of every path but the ledger — the same paths `is_ledger_path` answers, for a git
+// command to leave out. `:/` and `top` anchor it at the repository root, so a command run from a
+// subdirectory still covers the whole tree and still leaves the root's ledger alone.
+const LEDGER_EXCLUSION_PATHSPEC: ReadonlyArray<string> = [
+	':/',
+	...LEDGER_DIRECTORIES.map((directory) => `:(top,exclude)${directory}`),
+	...LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) => `:(top,exclude)${legacy}`),
+	...LEGACY_OBSERVATION_LEDGER_PATHS.map(
+		(legacy) => `:(top,exclude,glob)${legacy}.*${MIGRATION_CLAIM_SUFFIX}`,
+	),
+]
+
 function is_ledger_line(line: string): boolean {
 	return is_ledger_path(status_path(line))
 }
@@ -124,6 +136,7 @@ const observation_ledger = {
 
 export {
 	LEDGER_DIRECTORIES,
+	LEDGER_EXCLUSION_PATHSPEC,
 	LEDGER_FILE_EXTENSION,
 	LEGACY_LEDGER_FILE,
 	LEGACY_OBSERVATION_LEDGER_DIRECTORY,

package/scripts/observations/observations-flush-landing.ts

@@ -1,6 +1,8 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { OpenPull } from '#scripts/gh/git-gh-pr-auto-merge'
 import { git_pr_checks } from '#scripts/gh/git-pr-checks'
+import { git_pr_merge_checked } from '#scripts/gh/git-pr-merge-checked'
+import { git_command } from '#scripts/git/git-command'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { error_text } from '#scripts/lib/error-message'
 
@@ -21,9 +23,10 @@ const MERGE_FAILED_REASON =
 // **Best-effort, and the answer says which wait to use.** GraphQL — the only way to enable auto-merge
 // — can be refused in a cloud session, and that loses the safety net rather
 // than the flush: the in-process wait-and-merge still runs, exactly as before auto-merge existed.
+// The checkout's head is the commit this flush just pushed, so that is the one auto-merge may land.
 async function request_auto_merge(branch_name: string): Promise<boolean> {
 	try {
-		await git_gh_command.pr_enable_auto_merge(branch_name)
+		await git_gh_command.pr_enable_auto_merge(branch_name, await git_command.head_commit())
 
 		return true
 	} catch (error) {
@@ -37,8 +40,7 @@ async function request_auto_merge(branch_name: string): Promise<boolean> {
 // the merge gate's wait would run out its budget on a pull request that is already merged.
 async function wait_for_landing(branch_name: string, is_auto_merge: boolean): Promise<void> {
 	if (!is_auto_merge) {
-		await git_pr_checks.wait_for_pr_success(branch_name)
-		await git_gh_command.pr_merge(branch_name)
+		await git_pr_merge_checked.merge_when_green(branch_name)
 
 		return
 	}

package/scripts/observations/observations-flush.ts

@@ -1,6 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_command } from '#scripts/git/git-command'
 import { main_sync } from '#scripts/git/main-sync'
+import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/issue-labels'
 import { error_text } from '#scripts/lib/error-message'
 import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
 import type { BrokenLine } from './observation-ledger-line'
@@ -258,7 +259,11 @@ async function push_and_open(branch_name: string): Promise<string> {
 	try {
 		await git_command.push()
 
-		return await git_gh_command.pr_create(COMMIT_MESSAGE, pull_request_body(), 'ignore-for-release')
+		return await git_gh_command.pr_create(
+			COMMIT_MESSAGE,
+			pull_request_body(),
+			IGNORE_FOR_RELEASE_LABEL,
+		)
 	} catch (error) {
 		throw new Error(stranded_branch_message(branch_name, error_text.message_of(error)), {
 			cause: error,

package/scripts/overrides/overrides-check.ts

@@ -11,6 +11,7 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { file_reader } from '#scripts/lib/read-file'
 import { overrides_snapshot_schema } from '#scripts/lib/schemas'
 import { overrides_files } from './overrides-files'
 import { overrides_check, type OverridesDiff } from './overrides-logic'
@@ -19,17 +20,13 @@ const ARGV_OFFSET = 2
 const OPTIONS = { save: { type: 'boolean', default: false } } as const
 const USAGE = cli_flags.usage_line(['--save'], 'overrides')
 
-function is_file_not_found(error: unknown): boolean {
-	return error instanceof Error && 'code' in error && error.code === 'ENOENT'
-}
-
 function load_snapshot(): Record<string, string> {
 	try {
 		return overrides_snapshot_schema.parse(
 			JSON.parse(readFileSync(overrides_check.SNAPSHOT_PATH, 'utf8')),
 		)
 	} catch (error) {
-		if (is_file_not_found(error)) {
+		if (file_reader.is_absent(error)) {
 			console.error(`✖ Snapshot not found: ${overrides_check.SNAPSHOT_PATH}`)
 			console.error('  Run with --save first to create a snapshot.')
 		} else {

package/scripts/overrides/overrides-files.ts

@@ -1,3 +1,4 @@
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { file_reader } from '#scripts/lib/read-file'
 import { overrides_check, type OverridesSources } from './overrides-logic'
 
@@ -5,7 +6,7 @@ import { overrides_check, type OverridesSources } from './overrides-logic'
 // field at all — so a missing file reads as an empty document rather than aborting the check.
 function read_current_sources(): OverridesSources {
 	return {
-		package_json: file_reader.read_file_or_empty(overrides_check.PACKAGE_JSON_PATH),
+		package_json: file_reader.read_file_or_empty(PACKAGE_JSON),
 		workspace_yaml: file_reader.read_file_or_empty(overrides_check.WORKSPACE_YAML_PATH),
 	}
 }

package/scripts/overrides/overrides-logic.ts

@@ -1,3 +1,4 @@
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { yaml_document } from '#scripts/lib/yaml-document'
 import {
 	package_pnpm_schema,
@@ -68,7 +69,6 @@ function compare(snapshot: Record<string, string>, current: Record<string, strin
 }
 
 const SNAPSHOT_PATH = '.overrides-snapshot.json'
-const PACKAGE_JSON_PATH = 'package.json'
 const WORKSPACE_YAML_PATH = 'pnpm-workspace.yaml'
 
 // Both source files are optional and either may be absent from a project entirely, so an empty
@@ -109,14 +109,12 @@ function count_entry(path: string, overrides: Record<string, string>): Array<str
 function describe_sources(sources: OverridesSources): string {
 	const counts = [
 		...count_entry(WORKSPACE_YAML_PATH, read_overrides_from_workspace(sources.workspace_yaml)),
-		...count_entry(PACKAGE_JSON_PATH, read_overrides_from_package(sources.package_json)).map(
+		...count_entry(PACKAGE_JSON, read_overrides_from_package(sources.package_json)).map(
 			(entry) => `${entry} (ignored by pnpm)`,
 		),
 	]
 
-	if (counts.length === 0) {
-		return `no overrides found in ${WORKSPACE_YAML_PATH} or ${PACKAGE_JSON_PATH}`
-	}
+	if (counts.length === 0) return `no overrides found in ${WORKSPACE_YAML_PATH} or ${PACKAGE_JSON}`
 
 	return counts.join(', ')
 }
@@ -202,7 +200,6 @@ const overrides_check = {
 	list_excluded_package_names,
 	read_dependency_names,
 	build_update_command,
-	PACKAGE_JSON_PATH,
 	WORKSPACE_YAML_PATH,
 	SNAPSHOT_PATH,
 }

package/scripts/package/verify-optional-eslint-install.ts

@@ -1,16 +1,18 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { PACKAGE_JSON, package_manifest } from '#scripts/lib/package-manifest'
 import { execaSync } from 'execa'
+import { z } from 'zod'
 
 const root = process.cwd()
 const scratch = mkdtempSync(path.join(os.tmpdir(), 'kit-eslint-install-'))
-const PACKAGE_JSON = 'package.json'
 const IGNORE_SCRIPTS = '--ignore-scripts'
-const manifest = JSON.parse(readFileSync(path.join(root, PACKAGE_JSON), 'utf8')) as {
-	devDependencies: Record<string, string>
-	peerDependencies: Record<string, string>
-}
+const version_map_schema = z.record(z.string(), z.string())
+const manifest = package_manifest.read_manifest(
+	root,
+	z.object({ devDependencies: version_map_schema, peerDependencies: version_map_schema }),
+)
 const eslint_peers = Object.keys(manifest.peerDependencies).filter((name) =>
 	/^(?:@eslint\/|@stylistic\/|eslint|globals$|typescript)/u.test(name),
 )

package/scripts/propagate/propagate-publish.ts

@@ -1,4 +1,5 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { json_value } from '#scripts/lib/json-value'
 import { poll } from '#scripts/lib/poll'
 import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { with_page_size } from '#scripts/version/version-remote'
@@ -63,13 +64,7 @@ function fetch_published_versions(versions_endpoint: string): Array<string> | un
 	})
 	if (stdout === undefined) return undefined
 
-	try {
-		const parsed: unknown = JSON.parse(stdout)
-
-		return Array.isArray(parsed) ? parsed.filter((name) => typeof name === 'string') : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_array(stdout)?.filter((name) => typeof name === 'string')
 }
 
 // The knobs the wait exposes. Every one of them is injectable so the unit suite can drive the loop

package/scripts/propagate/propagate-targets.ts

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { RepoMap } from '#scripts/discovery/repo-map-logic'
-import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { z } from 'zod'
 
 // Deciding which repositories a published release should be carried into.
@@ -16,7 +16,6 @@ import { z } from 'zod'
 // us rather than a roster, so a new consumer needs no edit here — and it covers a consumer that is
 // not a published package at all, which a list of downstream package names cannot.
 
-const MANIFEST_NAME = 'package.json'
 const NODE_MODULES = 'node_modules'
 
 // Why a candidate is not going to be processed, or that it is. `not_selected` is the one state set
@@ -64,14 +63,7 @@ function has_checkout(repository_path: string): boolean {
 }
 
 function read_manifest(repository_path: string): Manifest | undefined {
-	const manifest_path = path.join(repository_path, MANIFEST_NAME)
-	if (!existsSync(manifest_path)) return undefined
-
-	try {
-		return json_value.parse_with(readFileSync(manifest_path, 'utf8'), manifest_schema)
-	} catch {
-		return undefined
-	}
+	return package_manifest.read_manifest_if_valid(repository_path, manifest_schema)
 }
 
 // The range a manifest declares for `package_name`, from either dependency field. Undefined when the
@@ -95,7 +87,7 @@ function installed_version(repository_path: string, package_name: string): strin
 // the parent directory), which is an ordinary "not downstream" rather than damage.
 function classify_manifest_absence(repository_path: string): TargetState | undefined {
 	if (!has_checkout(repository_path)) return 'missing_checkout'
-	if (!existsSync(path.join(repository_path, MANIFEST_NAME))) return 'not_downstream'
+	if (!existsSync(package_manifest.manifest_path(repository_path))) return 'not_downstream'
 
 	return undefined
 }

package/scripts/refactor/import-graph.ts

@@ -12,10 +12,12 @@ import { file_reader } from '#scripts/lib/read-file'
 const FROM_PATTERN = /\bfrom[ \t]*['"]([^'"\n]+)['"]/gu
 // A side-effect import carries no `from`: `import './register'`.
 const BARE_IMPORT_PATTERN = /^[ \t]*import[ \t]+['"]([^'"\n]+)['"]/gmu
-// The subpath import this package uses for cross-directory `scripts/` imports; `#scripts/x` resolves
-// to `scripts/x`. Relative specifiers resolve against the importer's directory.
-const SUBPATH_PREFIX = '#scripts/'
-const SCRIPTS_DIR = 'scripts'
+// The subpath imports this package uses for cross-directory imports; `#scripts/x` resolves to
+// `scripts/x` and `#tools/x` to `tools/x`. Relative specifiers resolve against the importer's directory.
+const SUBPATH_DIRECTORIES: ReadonlyArray<readonly [string, string]> = [
+	['#scripts/', 'scripts'],
+	['#tools/', 'tools'],
+]
 const RELATIVE_PREFIX = '.'
 // A specifier omits its extension, so a resolved base is tried against the real files these suffixes
 // would produce — a sibling module or a directory's index, in the order a resolver would.
@@ -38,9 +40,9 @@ function parse_imports(source: string): ReadonlyArray<string> {
 // Where a local specifier points before extension resolution, or `undefined` for a package import
 // this graph does not follow.
 function specifier_base(spec: string, importer: string, root: string): string | undefined {
-	if (spec.startsWith(SUBPATH_PREFIX)) {
-		return path.resolve(root, SCRIPTS_DIR, spec.slice(SUBPATH_PREFIX.length))
-	}
+	const subpath = SUBPATH_DIRECTORIES.find(([prefix]) => spec.startsWith(prefix))
+
+	if (subpath !== undefined) return path.resolve(root, subpath[1], spec.slice(subpath[0].length))
 
 	if (spec.startsWith(RELATIVE_PREFIX)) return path.resolve(path.dirname(importer), spec)
 

package/scripts/release/github-release-runs.ts

@@ -96,20 +96,31 @@ async function is_release_lost(source: RunSource, tag: string): Promise<boolean>
 	return run.status === 'completed' && (await is_release_over(source, tag))
 }
 
+async function publish_run(
+	source: RunSource,
+	workflow: string,
+	tag: string,
+): Promise<Run | undefined> {
+	return await find_run(source, workflow, `Publish ${tag}`)
+}
+
 // A run not listed yet is pending too: the announcement that starts this release also starts the
 // publication, so the release can ask before GitHub has queued that run.
+function run_state(run: Run | undefined): PollState {
+	if (run?.status !== 'completed') return 'pending'
+
+	return run.conclusion === 'success' ? 'ready' : 'failed'
+}
+
 async function publication_state(
 	source: RunSource,
 	workflow: string,
 	tag: string,
 ): Promise<PollState> {
-	const run = await find_run(source, workflow, `Publish ${tag}`)
-	if (run?.status !== 'completed') return 'pending'
-
-	return run.conclusion === 'success' ? 'ready' : 'failed'
+	return run_state(await publish_run(source, workflow, tag))
 }
 
-const github_release_runs = { is_release_lost, publication_state }
+const github_release_runs = { is_release_lost, publication_state, publish_run, run_state }
 
-export type { PollState, RunSource }
+export type { PollState, Run, RunSource }
 export { github_release_runs }

package/scripts/release/release-approval-prune.ts

@@ -0,0 +1,18 @@
+import { git_spawn } from '#scripts/git/git-spawn'
+
+// **A release drops every `josh metrics` approval the default branch holds** (joshuafolkken/kit#4187).
+// The release work tree is cut from `origin/<default>`, so every file it holds under the directory
+// belongs to an issue that already merged. Such a file is read only to tell it apart from a branch's
+// new one (`tools/metrics/metrics-ratchet.ts` → `fresh_approvals`): a branch's merge-base still holds
+// it unchanged, and a branch that merges the release in loses it on both sides, so removing it changes
+// no verdict. `--ignore-unmatch` makes a repository with no approvals a no-op.
+
+const APPROVAL_DIRECTORY = '.josh/metrics-accepted'
+
+async function prune(): Promise<void> {
+	await git_spawn.read(['rm', '-r', '-q', '--ignore-unmatch', '--', APPROVAL_DIRECTORY])
+}
+
+const release_approval_prune = { APPROVAL_DIRECTORY, prune }
+
+export { release_approval_prune }

package/scripts/release/release-history.ts

@@ -1,14 +1,12 @@
 import { git_command } from '#scripts/git/git-command'
 import { json_value } from '#scripts/lib/json-value'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { package_with_version_schema } from '#scripts/lib/schemas'
-import { version_targets } from '#scripts/version/version-targets'
 import { release_plan, type ReleasePlan, type VersionedCommit } from './release-plan'
 
 // Reading main's history for the two numbers a release is made of: where the version last changed,
 // and how many merges have landed since.
 
-const { PACKAGE_JSON } = version_targets
-
 // How far back the search for "the commit that last changed the version" goes, counted in commits
 // that touched `package.json`. Once children stop bumping that file still
 // changes for every dependency update, so the base can sit several entries down — but a repository