@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/behavior/behavior-rules.ts

@@ -1,12 +1,12 @@
 import { json_value } from '#scripts/lib/json-value'
+import { direct_pr_create } from '#scripts/rules/direct-pr-create'
 import { time_shell } from '#scripts/time-runtime/time-shell'
 import type { Block, TranscriptLine } from '#scripts/time-runtime/time-transcript-line'
 import type { Assertion, Finding } from './behavior-assertion'
 
-// The behavior assertions checked against recorded transcripts. This is the
-// **seed set** — the issue's own plan is to land one rule that is green across the recorded corpus,
-// then add more one at a time, each verified green before it joins. Starting with many would land a
-// wall of red that says nothing about which behavior actually regressed.
+// The behavior assertions checked against recorded transcripts. Rules join one at a time, each
+// verified green across the recorded corpus first — starting with many would land a wall of red that
+// says nothing about which behavior actually regressed.
 
 const BASH_TOOL = 'Bash'
 const TOOL_USE = 'tool_use'
@@ -98,46 +98,69 @@ function denied_call_ids(lines: ReadonlyArray<TranscriptLine>): ReadonlySet<stri
 	)
 }
 
-// The direct index mutations one transcript line ran, each as a finding at that line's position. A
-// line is one assistant content block, so its position is a place a reader can open in the file.
-function line_mutations(
+// The Bash calls that ran on one transcript line and broke the rule, each as a finding at that line's
+// position. A line is one assistant content block, so its position is a place a reader can open.
+function line_findings(
 	line: TranscriptLine,
-	index: number,
+	position: number,
 	denied_ids: ReadonlySet<string>,
+	rule: BashRule,
 ): ReadonlyArray<Finding> {
 	return line.blocks
 		.filter((block) => !denied_ids.has(block.id))
 		.map((block) => command_of(block))
-		.filter((command): command is string => command !== undefined && is_index_mutation(command))
-		.map((command) => ({
-			assertion: INDEX_ASSERTION_NAME,
-			position: index + FIRST_POSITION_OFFSET,
-			detail: command,
-		}))
+		.filter((command): command is string => command !== undefined && rule.is_violation(command))
+		.map((command) => ({ assertion: rule.name, position, detail: command }))
 }
 
-function scan_index_mutation(lines: ReadonlyArray<TranscriptLine>): ReadonlyArray<Finding> {
-	const denied_ids = denied_call_ids(lines)
+interface BashRule {
+	name: string
+	describe: string
+	is_violation: (command: string) => boolean
+}
+
+// One assertion over the Bash calls a run actually executed: a call the permission layer or a
+// PreToolUse hook refused never ran, so it breaks nothing.
+function bash_assertion(rule: BashRule): Assertion {
+	function scan(lines: ReadonlyArray<TranscriptLine>): ReadonlyArray<Finding> {
+		const denied_ids = denied_call_ids(lines)
+
+		return lines.flatMap((line, index) =>
+			line_findings(line, index + FIRST_POSITION_OFFSET, denied_ids, rule),
+		)
+	}
 
-	return lines.flatMap((line, index) => line_mutations(line, index, denied_ids))
+	return { name: rule.name, describe: rule.describe, scan }
 }
 
-const index_mutation_assertion: Assertion = {
+const index_mutation_assertion = bash_assertion({
 	name: INDEX_ASSERTION_NAME,
 	describe: 'git staging or commit must go through `pnpm josh git`, never a direct git call',
-	scan: scan_index_mutation,
-}
-
-// The seed set: every rule green across the recorded corpus today. A new rule is appended here only
-// after it has been verified green against past real runs.
-const ALL_ASSERTIONS: ReadonlyArray<Assertion> = [index_mutation_assertion]
+	is_violation: is_index_mutation,
+})
+
+// The matcher is the `direct-pr-create` guard's own, so the assertion and the refusal cannot drift. The
+// guard refuses every match, so a finding means a direct PR call ran past it — every run since the
+// guard landed is green; the only hits in the corpus predate it.
+const PR_CREATE_ASSERTION_NAME = 'no-direct-pr-create'
+const pr_create_assertion = bash_assertion({
+	name: PR_CREATE_ASSERTION_NAME,
+	describe: 'a pull request must be opened with `pnpm josh pr`, never `gh pr create` or `gh api`',
+	is_violation: direct_pr_create.is_direct_pr_create,
+})
+
+// Every rule green across the recorded corpus. A new rule is appended here only after it has been
+// verified green against past real runs.
+const ALL_ASSERTIONS: ReadonlyArray<Assertion> = [index_mutation_assertion, pr_create_assertion]
 
 const behavior_rules = {
 	ALL_ASSERTIONS,
 	INDEX_ASSERTION_NAME,
+	PR_CREATE_ASSERTION_NAME,
 	command_of,
 	index_mutation_assertion,
 	is_index_mutation,
+	pr_create_assertion,
 }
 
 export { behavior_rules }

package/scripts/build/build-bin.ts

@@ -1,7 +1,5 @@
-#!/usr/bin/env tsx
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { error_text } from '#scripts/lib/error-message'
 import { build } from 'esbuild'
 
 const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
@@ -9,10 +7,10 @@ const ENTRY_POINT = path.join(PACKAGE_DIR, 'scripts', 'josh', 'josh.ts')
 const OUTFILE = path.join(PACKAGE_DIR, 'dist', 'josh.js')
 const NODE_BANNER = '#!/usr/bin/env node'
 
-async function build_bin(): Promise<void> {
+async function build_bin(outfile: string = OUTFILE): Promise<void> {
 	await build({
 		entryPoints: [ENTRY_POINT],
-		outfile: OUTFILE,
+		outfile,
 		bundle: true,
 		platform: 'node',
 		format: 'esm',
@@ -22,16 +20,4 @@ async function build_bin(): Promise<void> {
 	})
 }
 
-async function main(): Promise<void> {
-	try {
-		await build_bin()
-		console.info(`  ✔ ${OUTFILE} built`)
-	} catch (error) {
-		console.error(error_text.message_of(error))
-		process.exit(1)
-	}
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
 export { build_bin, NODE_BANNER, OUTFILE }

package/scripts/build/build-claude-md.ts

@@ -1,4 +1,3 @@
-#!/usr/bin/env tsx
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -40,12 +39,6 @@ function build_claude_md(): string {
 	return DIST_CLAUDE_MD
 }
 
-function main(): void {
-	console.info(`  ✔ ${build_claude_md()} built`)
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
-
 export {
 	build_claude_md,
 	DIST_BASIC_CLAUDE_MDS,

package/scripts/build/build-commands.ts

@@ -1,10 +1,8 @@
-#!/usr/bin/env tsx
 import { rmSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { COMMAND_MAP } from '#scripts/josh/josh-command-map'
 import { BUNDLED_COMMAND_DIRECTORY, josh_in_process } from '#scripts/josh/josh-in-process'
-import { error_text } from '#scripts/lib/error-message'
 import { build } from 'esbuild'
 
 const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
@@ -52,15 +50,4 @@ async function build_commands(out_directory: string = OUT_DIR): Promise<string>
 	return out_directory
 }
 
-async function main(): Promise<void> {
-	try {
-		console.info(`  ✔ ${await build_commands()} built`)
-	} catch (error) {
-		console.error(error_text.message_of(error))
-		process.exit(1)
-	}
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
 export { build_commands, bundled_scripts, OUT_DIR }

package/scripts/build/build-hooks.ts

@@ -1,20 +1,13 @@
-#!/usr/bin/env tsx
-import {
-	mkdirSync,
-	mkdtempSync,
-	readdirSync,
-	readFileSync,
-	renameSync,
-	rmSync,
-	writeFileSync,
-} from 'node:fs'
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { hook_bundle_stamp } from '#scripts/build/hook-bundle-stamp'
-import { error_text } from '#scripts/lib/error-message'
+import { toolchain_inputs } from '#scripts/gate/toolchain-inputs'
+import { atomic_write } from '#scripts/lib/atomic-write'
 import { build, type OnLoadArgs, type OutputFile, type Plugin, type PluginBuild } from 'esbuild'
 
-const PACKAGE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const BUILD_SCRIPT = fileURLToPath(import.meta.url)
+const PACKAGE_DIR = path.join(path.dirname(BUILD_SCRIPT), '..', '..')
 const OUT_DIR = path.join(PACKAGE_DIR, 'dist', 'hooks')
 const { STAMP_NAME } = hook_bundle_stamp
 const CHUNK_PREFIX = 'chunk-'
@@ -29,11 +22,11 @@ const ANY_PATH = /.*/
 //
 // **`splitting: true` is load-bearing, not an optimization.** Every hook module decides whether to
 // run its main from `process.argv[1] === fileURLToPath(import.meta.url)`. A single-file bundle would
-// collapse every imported module's `import.meta.url` to the one output path, so a call to
-// `node dist/hooks/pretool-guard.js` would fire the self-invoke of `batch-guard` and
-// `investigation-guard` too — each reads stdin, and the second read gets an empty payload. Code
-// splitting keeps every entry in its own file with its own `import.meta.url`, so an imported guard's
-// `import.meta.url` never equals `argv[1]` and only the file actually launched runs its main.
+// collapse every imported module's `import.meta.url` to the one output path, so a call to one hook
+// would fire the self-invoke of every other entry it carries — each reads stdin, and the second read
+// gets an empty payload. Code splitting keeps every entry in its own file with its own
+// `import.meta.url`, so only the file actually launched runs its main. The guards `pretool-guard`
+// composes carry no self-invoke: theirs live in `*-main.ts` entries no module imports.
 //
 // **The flip side: an entry another entry imports loses its main**. Splitting
 // moves a module two entries share into a chunk, so a launched hook whose own module is imported
@@ -49,20 +42,15 @@ interface HookBundle {
 	out: string
 }
 
-// The settings.json hooks (the session-start audit provisioner among them), the Codex input adapter, and the three guards `pretool-guard`
-// composes: `batch-guard`, `investigation-guard` and `duplicate-read-guard` each self-invoke, so they
-// must be their own entries to keep their `import.meta.url` out of `pretool-guard`'s file.
-// `delivered-rules` (the fourth guard) has no self-invoke, so it stays inlined.
+// The settings.json hooks (the session-start audit provisioner among them) and the Codex input
+// adapter — every hook a hook config launches, and nothing else.
 const HOOK_BUNDLES: ReadonlyArray<HookBundle> = [
 	{ source: 'scripts/hooks/codex-hook-adapter.ts', out: 'codex-hook-adapter' },
 	{ source: 'scripts/hooks/pretool-guard-cli.ts', out: 'pretool-guard' },
 	{ source: 'scripts/hooks/stop-guard.ts', out: 'stop-guard' },
 	{ source: 'scripts/hooks/format-edited-cli.ts', out: 'format-edited' },
-	{ source: 'scripts/josh/session-language-cli.ts', out: 'session-lang' },
-	{ source: 'scripts/security/security-audit-provision.ts', out: 'audit-provision' },
-	{ source: 'scripts/hooks/batch-guard.ts', out: 'batch-guard' },
-	{ source: 'scripts/delegation/investigation-guard.ts', out: 'investigation-guard' },
-	{ source: 'scripts/delegation/duplicate-read-guard.ts', out: 'duplicate-read-guard' },
+	{ source: 'scripts/josh/session-language-main.ts', out: 'session-lang' },
+	{ source: 'scripts/security/security-audit-provision-main.ts', out: 'audit-provision' },
 ]
 
 function entry_point(bundle: HookBundle): { in: string; out: string } {
@@ -83,9 +71,22 @@ function prune_stale_outputs(out_directory: string, outputs: ReadonlyArray<strin
 	}
 }
 
+// **A module inlined into an entry keeps no self-invoke.** Its `import.meta.url` collapses to the
+// entry's output path, so its guard would match `argv[1]` and its main would run beside the hook's:
+// `stop-guard` ran `josh run:hold`'s, `josh notify`'s and `josh run:tidy`'s on every stop, and their
+// stdout ahead of the envelope made the harness drop the refusal (joshuafolkken/kit#4123). Only the
+// launched entry runs a main, so every other module's guard is built as `false`.
+const SELF_INVOKE_GUARD = 'process.argv[1] === fileURLToPath(import.meta.url)'
+
+function loaded_contents(contents: Uint8Array, is_entry: boolean): string {
+	const source = Buffer.from(contents).toString('utf8')
+
+	return is_entry ? source : source.replaceAll(SELF_INVOKE_GUARD, 'false')
+}
+
 // Every file the build loads is read here, so the stamp digests the exact bytes that were bundled —
 // a source edited mid-build is recorded as what it was, and the next launch rebuilds it.
-function source_recorder(sources: Map<string, Uint8Array>): Plugin {
+function source_recorder(sources: Map<string, Uint8Array>, entries: ReadonlySet<string>): Plugin {
 	return {
 		name: 'hook-source-recorder',
 		setup(plugin_build: PluginBuild): void {
@@ -94,7 +95,7 @@ function source_recorder(sources: Map<string, Uint8Array>): Plugin {
 
 				sources.set(path.relative(PACKAGE_DIR, args.path), contents)
 
-				return { contents, loader: 'default' }
+				return { contents: loaded_contents(contents, entries.has(args.path)), loader: 'default' }
 			})
 		},
 	}
@@ -113,10 +114,7 @@ function is_chunk_first(left: OutputFile, right: OutputFile): number {
 // Each file is written into a private staging directory and renamed into place, so a hook never
 // reads a half-written bundle and two builds running side by side never write one file at once.
 function place(staging: string, target: string, contents: Uint8Array | string): void {
-	const temporary = path.join(staging, path.basename(target))
-
-	writeFileSync(temporary, contents)
-	renameSync(temporary, target)
+	atomic_write.replace_file(target, contents, { staging_directory: staging })
 }
 
 function place_build(out_directory: string, files: ReadonlyArray<OutputFile>, stamp: string): void {
@@ -142,11 +140,26 @@ function place_build(out_directory: string, files: ReadonlyArray<OutputFile>, st
 // every tool call, and an emptied directory would make a hook launched mid-build fail to load and its
 // guard fail open. The source digest is placed last (`hook-bundle-stamp.ts`), so a launch only reads
 // the bundles as fresh once every one of them is in place.
+//
+// This script is an input too: it rewrites what it loads, so an edit to it changes the bundles while
+// every bundled source stays byte-identical. So is the toolchain (`toolchain-inputs.ts`): the manifest
+// maps the `#scripts/*` imports esbuild resolves, and the lockfile pins esbuild itself.
+function build_inputs(): Map<string, Uint8Array> {
+	const toolchain = toolchain_inputs.paths(PACKAGE_DIR)
+
+	return new Map<string, Uint8Array>([
+		[path.relative(PACKAGE_DIR, BUILD_SCRIPT), readFileSync(BUILD_SCRIPT)],
+		...toolchain.map((input) => [input, readFileSync(path.join(PACKAGE_DIR, input))] as const),
+	])
+}
+
 async function build_hooks(out_directory: string = OUT_DIR): Promise<void> {
-	const sources = new Map<string, Uint8Array>()
+	const sources = build_inputs()
+	const entry_points = HOOK_BUNDLES.map((bundle) => entry_point(bundle))
+	const entries = new Set(entry_points.map((entry) => entry.in))
 	const { outputFiles: files } = await build({
 		absWorkingDir: PACKAGE_DIR,
-		entryPoints: HOOK_BUNDLES.map((bundle) => entry_point(bundle)),
+		entryPoints: entry_points,
 		outdir: out_directory,
 		bundle: true,
 		splitting: true,
@@ -155,7 +168,7 @@ async function build_hooks(out_directory: string = OUT_DIR): Promise<void> {
 		target: 'node22',
 		packages: 'external',
 		write: false,
-		plugins: [source_recorder(sources)],
+		plugins: [source_recorder(sources, entries)],
 	})
 	const stamp = hook_bundle_stamp.stamp_text(
 		sources,
@@ -165,17 +178,5 @@ async function build_hooks(out_directory: string = OUT_DIR): Promise<void> {
 	place_build(out_directory, files, stamp)
 }
 
-async function main(): Promise<void> {
-	try {
-		await build_hooks()
-		for (const bundle of HOOK_BUNDLES) console.info(`  ✔ ${outfile_for(bundle)} built`)
-	} catch (error) {
-		console.error(error_text.message_of(error))
-		process.exit(1)
-	}
-}
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
-
 export type { HookBundle }
-export { build_hooks, HOOK_BUNDLES, OUT_DIR, outfile_for }
+export { build_hooks, HOOK_BUNDLES, OUT_DIR, outfile_for, STAGING_PREFIX }

package/scripts/build/hook-bundle-stamp.ts

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto'
-import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
+import { toolchain_inputs } from '#scripts/gate/toolchain-inputs'
+import { atomic_write } from '#scripts/lib/atomic-write'
 import { json_value } from '#scripts/lib/json-value'
 
 // What a hook build was made from, so a later launch can tell whether `dist/hooks/` still matches the
@@ -31,7 +33,7 @@ import { json_value } from '#scripts/lib/json-value'
 // again. Once an mtime is older than the window any later write moves it, so only settled inputs are
 // remembered; a launch inside the window simply hashes.
 //
-// This module is loaded by plain `node` on every hook launch (`scripts/hooks/hook-bundle-ready.ts`),
+// This module is loaded by plain `node` on every hook launch (`tools/hooks/hook-bundle-ready.ts`),
 // so it imports `node:` built-ins and `#scripts/*` subpaths alone — nothing slow to load.
 
 const STAMP_NAME = 'inputs.json'
@@ -171,13 +173,10 @@ function is_remembered(
 // Written through a rename so a concurrent launch never reads half a record. Best-effort: a tree that
 // cannot be written is simply hashed again next time.
 function remember(out_directory: string, verified: VerifiedDigest): void {
-	const temporary_path = path.join(out_directory, `${VERIFIED_NAME}.${String(process.pid)}`)
-
 	try {
-		writeFileSync(temporary_path, JSON.stringify(verified))
-		renameSync(temporary_path, path.join(out_directory, VERIFIED_NAME))
+		atomic_write.replace_file(path.join(out_directory, VERIFIED_NAME), JSON.stringify(verified))
 	} catch {
-		rmSync(temporary_path, { force: true })
+		// A record that could not be written leaves the digest to be computed again.
 	}
 }
 
@@ -194,12 +193,31 @@ function is_digest_current(
 	return true
 }
 
-// Fresh only when the record exists, every output it lists is still there, and the listed inputs hash
-// to the recorded digest — a missing or deleted input counts as stale. The hash is skipped when the
-// inputs still carry the signatures of an earlier launch that verified this digest.
+// The build records the toolchain inputs among its sources (`build-hooks.ts`), so an edited one
+// changes the digest; one created since — a new `tsconfig.*.json` or rule module — is in no record.
+function lists_toolchain(stamp: HookBundleStamp, package_directory: string): boolean {
+	const recorded = new Set(stamp.inputs.map((input) => input.split(path.sep).join('/')))
+
+	return toolchain_inputs.paths(package_directory).every((input) => recorded.has(input))
+}
+
+function is_complete(
+	stamp: HookBundleStamp,
+	out_directory: string,
+	package_directory: string,
+): boolean {
+	if (stamp.outputs.some((output) => !existsSync(path.join(out_directory, output)))) return false
+
+	return lists_toolchain(stamp, package_directory)
+}
+
+// Fresh only when the record exists, every output it lists is still there, it lists every toolchain
+// input, and the listed inputs hash to the recorded digest — a missing or deleted input counts as
+// stale. The hash is skipped when the inputs still carry the signatures of an earlier launch that
+// verified this digest.
 function is_fresh(out_directory: string, package_directory: string): boolean {
 	const stamp = read_stamp(out_directory)
-	if (!stamp?.outputs.every((output) => existsSync(path.join(out_directory, output)))) return false
+	if (stamp === undefined || !is_complete(stamp, out_directory, package_directory)) return false
 	const snapshot = read_snapshot(package_directory, stamp.inputs)
 	if (snapshot === undefined) return false
 	if (is_remembered(out_directory, stamp.digest, snapshot.signatures)) return true

package/scripts/build/local-bin.ts

@@ -2,13 +2,13 @@ import { existsSync, readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { package_bin_schema } from '#scripts/lib/schemas'
 
 const NODE_MODULES = 'node_modules'
 const BIN_DIR = '.bin'
 const WINDOWS_PLATFORM = 'win32'
 const WINDOWS_SHIM_SUFFIX = '.cmd'
-const PACKAGE_JSON = 'package.json'
 
 // Every spawn site that reaches for a locally-installed CLI needs the same two details: pnpm
 // writes the shims under `node_modules/.bin`, and on Windows the executable one carries a

package/scripts/cases/cases-cli.ts

@@ -1,11 +1,13 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { cases_interaction_scan, type Findings } from './cases-interaction-scan'
 import { cases, type Boundary } from './cases-logic'
 
-// `josh cases <path...>` — print the I/O boundaries the changed paths cross and the abnormal cases
-// each owes. The boundary tokens go on stdout so `$(pnpm josh cases …)` reads
-// them; the required cases go on stderr so a person sees them without a shell parsing around them.
-// The logic and the vocabulary live in `cases-logic.ts`; everything here is the invocation.
+// `josh cases <path...>` — print the I/O boundaries the changed paths cross, the shared state and the
+// environment they depend on, and the abnormal cases each owes. The tokens go on stdout so
+// `$(pnpm josh cases …)` reads them; the required cases go on stderr so a person sees them without a
+// shell parsing around them. The logic and the vocabulary live in `cases-logic.ts` and
+// `cases-interaction.ts`; everything here is the invocation.
 
 const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh cases <path...>'
@@ -13,19 +15,27 @@ const FAILURE_EXIT_CODE = 1
 
 function report_none(): number {
 	console.info(cases.NONE)
-	console.error('no network, process, filesystem or time boundary crossed')
+	console.error(
+		'no network, process, filesystem, time, shared-state or environment boundary crossed',
+	)
 
 	return 0
 }
 
-function report_boundaries(boundaries: ReadonlyArray<Boundary>): number {
-	console.info(boundaries.join(' '))
-	console.error(`required abnormal cases: ${cases.cases_for(boundaries).join(' / ')}`)
+// The interaction lines come first, as `report:template` places them at the head of "if it breaks".
+function report_crossed(boundaries: ReadonlyArray<Boundary>, findings: Findings): number {
+	console.info([...boundaries, ...cases_interaction_scan.interactions_of(findings)].join(' '))
+
+	for (const line of cases_interaction_scan.lines_for(findings)) console.error(line)
+
+	if (boundaries.length > 0) {
+		console.error(`required abnormal cases: ${cases.cases_for(boundaries).join(' / ')}`)
+	}
 
 	return 0
 }
 
-function run(argv: ReadonlyArray<string>): number {
+async function run(argv: ReadonlyArray<string>): Promise<number> {
 	if (argv.length === 0) {
 		console.error(USAGE)
 
@@ -33,16 +43,18 @@ function run(argv: ReadonlyArray<string>): number {
 	}
 
 	const boundaries = cases.boundaries_in(argv)
+	const findings = await cases_interaction_scan.scan(argv)
+	const is_crossed = boundaries.length + cases_interaction_scan.interactions_of(findings).length > 0
 
-	return boundaries.length === 0 ? report_none() : report_boundaries(boundaries)
+	return is_crossed ? report_crossed(boundaries, findings) : report_none()
 }
 
-function main(argv: ReadonlyArray<string>): void {
-	process.exitCode = run(argv)
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
 }
 
 const cases_cli = { run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
 export { cases_cli }

package/scripts/cases/cases-interaction-scan.ts

@@ -0,0 +1,134 @@
+import path from 'node:path'
+import { git_grep_hits, type GrepResult } from '#scripts/git/git-grep-hits'
+import { file_reader } from '#scripts/lib/read-file'
+import {
+	cases_interaction,
+	type Interaction,
+	type StatePath,
+	type Wording,
+} from './cases-interaction'
+
+// The I/O half of `josh cases`' interaction boundaries (joshuafolkken/kit#4491): read the changed
+// sources, then search the rest of the repository for each state path they name — by its literal and
+// by every constant this source binds it to — so the summary lists the other readers and writers as
+// `file:line`. Tests are left out of the search: a fixture path is not a second writer at run time.
+
+const SOURCE_EXTENSIONS: ReadonlySet<string> = new Set(['.ts', '.js', '.mjs', '.cjs', '.svelte'])
+const SOURCE_PATHSPECS: ReadonlyArray<string> = [
+	'*.ts',
+	'*.js',
+	'*.mjs',
+	'*.cjs',
+	'*.svelte',
+	':(exclude)*.test.ts',
+]
+const WHOLE_WORD = ['-w']
+const MAX_OTHERS = 10
+
+interface SharedState {
+	path: string
+	others: ReadonlyArray<string>
+	has_failed: boolean
+}
+
+interface Findings {
+	states: ReadonlyArray<SharedState>
+	variables: ReadonlyArray<string>
+	residents: ReadonlyArray<string>
+}
+
+function is_source(file: string): boolean {
+	return SOURCE_EXTENSIONS.has(path.extname(file))
+}
+
+function repo_relative(file: string): string {
+	return path.relative(process.cwd(), path.resolve(file))
+}
+
+// A module that declares its own constant of the same name holds its own state, not this one.
+async function constant_hits(name: string): Promise<GrepResult> {
+	const result = await git_grep_hits.search(name, WHOLE_WORD, SOURCE_PATHSPECS)
+	const declaration = new RegExp(String.raw`\b(?:const|let|var)\s+${name}\b`, 'u')
+	const declaring = new Set(
+		result.hits.filter((hit) => declaration.test(hit.excerpt)).map((hit) => hit.path),
+	)
+
+	return { ...result, hits: result.hits.filter((hit) => !declaring.has(hit.path)) }
+}
+
+async function shared_state(state: StatePath, own: ReadonlySet<string>): Promise<SharedState> {
+	const results = await Promise.all([
+		git_grep_hits.search(state.path, [], SOURCE_PATHSPECS),
+		...state.constants.map(async (name) => await constant_hits(name)),
+	])
+	const sites = results
+		.flatMap((result) => result.hits)
+		.filter((hit) => !own.has(hit.path))
+		.map((hit) => `${hit.path}:${hit.line}`)
+
+	return {
+		path: state.path,
+		others: [...new Set(sites)],
+		has_failed: results.some((result) => result.has_failed),
+	}
+}
+
+async function scan(paths: ReadonlyArray<string>): Promise<Findings> {
+	const content = paths
+		.filter((file) => is_source(file))
+		.map((file) => file_reader.read_if_readable(file) ?? '')
+		.join('\n')
+	const own = new Set(paths.map((file) => repo_relative(file)))
+	const states = await Promise.all(
+		cases_interaction.state_paths_in(content).map(async (state) => await shared_state(state, own)),
+	)
+
+	return { states, ...cases_interaction.environment_in(content) }
+}
+
+function interactions_of(findings: Findings): ReadonlyArray<Interaction> {
+	const has_environment = findings.variables.length + findings.residents.length > 0
+	const crossed = { state: findings.states.length > 0, env: has_environment }
+
+	return cases_interaction.INTERACTIONS.filter((interaction) => crossed[interaction])
+}
+
+function others_text(state: SharedState, words: Wording): string {
+	if (state.has_failed) return words.search_failed
+	if (state.others.length === 0) return words.no_others
+
+	const shown = state.others.slice(0, MAX_OTHERS)
+	const rest = state.others.length - shown.length
+
+	return rest > 0 ? `${shown.join(', ')}, +${String(rest)}` : shown.join(', ')
+}
+
+function line(label: string, subject: string, owed: ReadonlyArray<string>): string {
+	return `${label} ${subject}: ${owed.join(' / ')}`
+}
+
+// One line per state, variable and resident process, in that order — each carries its own subject,
+// so the reader sees whose cases they are without a second table.
+function lines_for(findings: Findings, lang?: string): ReadonlyArray<string> {
+	const words = cases_interaction.wording(lang)
+	const state_lines = findings.states.map((state) =>
+		line(
+			words.state,
+			`\`${state.path}\` (${words.others}: ${others_text(state, words)})`,
+			words.state_cases,
+		),
+	)
+	const variable_lines = findings.variables.map((name) =>
+		line(words.variable, `\`${name}\``, words.variable_cases),
+	)
+	const resident_lines = findings.residents.map((name) =>
+		line(words.resident, `\`${name}\``, words.resident_cases),
+	)
+
+	return [...state_lines, ...variable_lines, ...resident_lines]
+}
+
+const cases_interaction_scan = { scan, interactions_of, lines_for }
+
+export type { Findings, SharedState }
+export { cases_interaction_scan }