@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/issue/size-estimate.ts

@@ -0,0 +1,90 @@
+import { split_assess, type SizeMeasurement } from '#scripts/split/split-assess'
+import { z } from 'zod'
+import { SPLIT_ROUTE_LABEL } from './issue-labels'
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#4675: a request clearly over the split guide reached a lane as one Issue because
+// nothing asked for its size when it was filed, and a split is cheapest at filing time. Every filing
+// declares its estimate under the background heading, so it stays on the Issue; one over the guide is
+// refused unless it is filed as a split or says why it stays one Issue.
+//
+// **The guide is `split_assess`'s, never a copy** — the measured diff and the declared estimate are
+// judged by one `verdict_for`. An epic (a body carrying `## Split rationale`) declares no estimate:
+// its children do.
+
+const BACKGROUND_HEADING = '## 背景'
+const EPIC_HEADING = '## Split rationale'
+const PREFIX = '- 規模見積もり:'
+const { REASON_PREFIX } = split_assess
+const DECLARATION = `${PREFIX} 約 <N> ファイル / <M> 行（テスト除く）`
+// Full- or half-width parentheses alike: the two read the same to the person typing the line.
+const VALUE_PATTERN =
+	/^約\s*(?<files>\d+)\s*ファイル\s*\/\s*(?<lines>\d+)\s*行\s*[（(]テスト除く[）)]$/u
+const MISSING = `missing size estimate: declare \`${DECLARATION}\` under ${BACKGROUND_HEADING}`
+// The refusal ends in a line ready to paste (joshuafolkken/kit#5225).
+const EXAMPLE = `${PREFIX} 約 3 ファイル / 60 行（テスト除く）`
+const MALFORMED = `\`${PREFIX}\` must be written ${DECLARATION}\n${EXAMPLE}`
+const estimate_schema = z.object({ files: z.coerce.number(), lines: z.coerce.number() })
+
+function declared(body: string, prefix: string): string | undefined {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+	const line = markdown_section
+		.unfenced_lines(background)
+		.map((text) => text.trim())
+		.find((text) => text.startsWith(prefix))
+
+	return line?.slice(prefix.length).trim()
+}
+
+function is_epic(body: string): boolean {
+	return markdown_section.has_line(body, EPIC_HEADING)
+}
+
+// The declared estimate judged against the guide, or `undefined` when there is none or it does not parse.
+function parse(body: string): SizeMeasurement | undefined {
+	const read = estimate_schema.safeParse(VALUE_PATTERN.exec(declared(body, PREFIX) ?? '')?.groups)
+
+	if (!read.success) return undefined
+	const { files, lines } = read.data
+
+	return { files, lines, verdict: split_assess.verdict_for(files, lines) }
+}
+
+// The shape check `issue:lint` makes: the declaration is there and parses. The guide needs the route,
+// which only `issue:file` knows, so it is `guide_problem`'s.
+function problems(body: string): ReadonlyArray<string> {
+	if (is_epic(body)) return []
+	if (declared(body, PREFIX) === undefined) return [MISSING]
+
+	return parse(body) === undefined ? [MALFORMED] : []
+}
+
+// A split filing, or one that declares why it stays one Issue, passes over the guide.
+function is_excused(body: string, route: string | undefined): boolean {
+	return route === SPLIT_ROUTE_LABEL || (declared(body, REASON_PREFIX) ?? '') !== ''
+}
+
+function refusal(estimate: SizeMeasurement): string {
+	const counted = `size estimate ${String(estimate.files)} file(s) / ${String(estimate.lines)} line(s) exceeds the guide (${String(split_assess.FILE_GUIDE)} files / ${String(split_assess.LINE_GUIDE)} lines)`
+
+	return `${counted} — file it split (\`--route split\`) or declare \`${REASON_PREFIX} <理由>\`; split-assessment.md → "${split_assess.QUESTION_SECTION}"`
+}
+
+// The filing refusal for an estimate over the guide; `undefined` under it, on a split filing, or with
+// the reason declared. A missing or malformed estimate is `problems`' refusal, not this one.
+function guide_problem(body: string, route: string | undefined): string | undefined {
+	const estimate = parse(body)
+
+	if (estimate?.verdict !== split_assess.SPLIT_VERDICT) return undefined
+
+	return is_excused(body, route) ? undefined : refusal(estimate)
+}
+
+// The declared file count, or `undefined` when there is no estimate or it does not parse.
+function declared_files(body: string): number | undefined {
+	return parse(body)?.files
+}
+
+const size_estimate = { declared_files, guide_problem, problems }
+
+export { size_estimate }

package/scripts/issue/trusted-measure.ts

@@ -0,0 +1,84 @@
+import { execSync } from 'node:child_process'
+import { gh_author_association } from '#scripts/gh/gh-author-association'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { error_text } from '#scripts/lib/error-message'
+import { z } from 'zod'
+import { session_cite } from './session-cite'
+
+// Running a command an Issue body names — `josh measure:rerun`'s baselines and the drive's measurement
+// declaration (`measure-declaration.ts`) alike.
+//
+// **The command is shell, and the body is written by whoever filed the Issue**.
+// A baseline needs pipes and loops (`git log … | wc -l`, `for d in $(ls …)`), so an allow-list of
+// commands cannot make it safe; what can is who wrote it. The input is therefore the Issue number, not
+// a file, so the author's `author_association` arrives with the body from the same REST read, and only
+// a body written by someone with write access to the repository is run.
+
+const ISSUE_FIELDS = `body,${gh_author_association.AUTHOR_FIELDS}`
+const UNKNOWN_ASSOCIATION = 'unknown'
+// One command's budget — the same minute `josh-harness.ts` gives one command it spawns. A measurement
+// is a count or a digest that answers in seconds, so a command still running after a minute is stuck,
+// and without a bound it would hold the whole re-measurement open with nothing printed.
+const MEASURE_TIMEOUT_MS = 60_000
+const issue_schema = z.object({
+	body: z.string().nullish(),
+	...gh_author_association.author_fields_schema,
+})
+
+type IssueFields = z.infer<typeof issue_schema>
+type BodyRead = { kind: 'trusted'; body: string } | { kind: 'refused'; reason: string }
+type CommandRun = { kind: 'ok'; output: string } | { kind: 'failed'; message: string }
+
+// The command's stdout, trimmed, or the message a failing or timed-out command threw.
+function run_command(command: string): CommandRun {
+	try {
+		return {
+			kind: 'ok',
+			output: execSync(command, { encoding: 'utf8', timeout: MEASURE_TIMEOUT_MS }).trim(),
+		}
+	} catch (error) {
+		return { kind: 'failed', message: error_text.message_of(error) }
+	}
+}
+
+// The run as one printable value: a failure is spelled in place of the output.
+function text_of(run: CommandRun): string {
+	return run.kind === 'ok' ? run.output : `(command failed: ${run.message})`
+}
+
+async function read_issue(issue_number: string): Promise<IssueFields | undefined> {
+	const json = await git_gh_issue_read.issue_view_json(issue_number, ISSUE_FIELDS)
+
+	return json === undefined ? undefined : parse_json_object_or_undefined(json, issue_schema)
+}
+
+function untrusted(issue_number: string, issue: IssueFields): BodyRead {
+	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
+
+	return {
+		kind: 'refused',
+		reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author (${association}) is not ${gh_author_association.TRUSTED_LIST}`,
+	}
+}
+
+// The body, only when its author can write to the repository. A read that fails is refused as well:
+// an unknown author is not a trusted one.
+async function read_trusted_body(issue_number: string): Promise<BodyRead> {
+	const issue = await read_issue(issue_number)
+
+	if (issue === undefined) {
+		return { kind: 'refused', reason: `could not read issue ${session_cite.issue(issue_number)}` }
+	}
+
+	if (!(await gh_author_association.is_trusted(gh_author_association.author_of(issue)))) {
+		return untrusted(issue_number, issue)
+	}
+
+	return { kind: 'trusted', body: issue.body ?? '' }
+}
+
+const trusted_measure = { read_trusted_body, run_command, text_of }
+
+export type { BodyRead, CommandRun }
+export { trusted_measure }

package/scripts/josh/agent-session-environment.ts

@@ -1,7 +1,7 @@
 // The environment variables that name the **parent** agent session, and which a child session must
 // not inherit.
 //
-// `scripts/eval/eval-session.ts` and `josh run:wake` both launch a headless session. Two copies of
+// `tools/eval/eval-session.ts` and `josh run:wake` both launch a headless session. Two copies of
 // this list is the clone `CLAUDE.md`
 // prohibits, and this is the shape of clone that fails silently: the copy that drifts does not throw
 // or lint — the child dials the parent's private socket, is refused, and the session dies as

package/scripts/josh/command-usage.ts

@@ -1,36 +1,18 @@
-import { canonical_command, COMMAND_MAP } from './josh-command-map'
+import { canonical_command } from './josh-aliases'
+import { COMMAND_MAP } from './josh-command-map'
 import type { CommandUsage } from './josh-command-types'
-import { AUTOMATION_USAGE } from './josh-usage-automation'
-import { BACKLOG_USAGE } from './josh-usage-backlog'
-import { DEVELOPER_USAGE } from './josh-usage-developer'
-import { HOOK_USAGE } from './josh-usage-hooks'
-import { ISSUE_USAGE } from './josh-usage-issue'
-import { REVIEW_USAGE } from './josh-usage-review'
-import { RUN_USAGE } from './josh-usage-run'
-import { SESSION_USAGE } from './josh-usage-session'
-import { WORKFLOW_USAGE } from './josh-usage-workflow'
 
 // The single renderer of a command's usage. `josh help <command>` prints it and
-// `scripts/document/generate-command-usage.ts` writes it between a reference page's usage markers,
-// so the terminal and the page are one text (#3932).
-
-type UsageTable = Readonly<Record<string, CommandUsage>>
-
-// Which reference page renders each usage table — the one place a table is tied to its page, so the
-// generator's coverage check and `josh help` read the same set (#3981).
-/* eslint-disable @typescript-eslint/naming-convention */
-const USAGE_PAGE_TABLES: Readonly<Record<string, ReadonlyArray<UsageTable>>> = {
-	'docs/josh-commands.md': [DEVELOPER_USAGE],
-	'docs/josh-commands-run.md': [RUN_USAGE, SESSION_USAGE],
-	'docs/josh-commands-backlog.md': [ISSUE_USAGE, BACKLOG_USAGE, REVIEW_USAGE],
-	'docs/josh-commands-automation.md': [AUTOMATION_USAGE, WORKFLOW_USAGE, HOOK_USAGE],
-}
-/* eslint-enable @typescript-eslint/naming-convention */
-const COMMAND_USAGE: UsageTable = Object.fromEntries(
-	Object.values(USAGE_PAGE_TABLES)
-		.flat()
-		.flatMap((table) => Object.entries(table)),
-)
+// `josh command:derive` writes it between a reference page's usage markers,
+// so the terminal and the page are one text (#3932). The usage itself sits on each command's entry
+// (#4185); which page renders it is the page's own `<!-- usage: <command> -->` span.
+
+const USAGE_PAGES: ReadonlyArray<string> = [
+	'docs/josh-commands.md',
+	'docs/josh-commands-run.md',
+	'docs/josh-commands-backlog.md',
+	'docs/josh-commands-automation.md',
+]
 const NOTE_GAP = 3
 
 interface ExampleLine {
@@ -39,7 +21,7 @@ interface ExampleLine {
 }
 
 function usage_for(name: string): CommandUsage | undefined {
-	return Object.hasOwn(COMMAND_USAGE, name) ? COMMAND_USAGE[name] : undefined
+	return Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name]?.usage : undefined
 }
 
 function example_line(name: string, example: CommandUsage['examples'][number]): ExampleLine {
@@ -80,31 +62,22 @@ function format_usage(name: string): string | undefined {
 	return [format_examples(name, usage), ...flags].join('\n\n')
 }
 
-// `josh help <command>`: the synopsis line, the description, then the usage block when the command
-// has one. An alias resolves to its command; a name that is neither answers `undefined`.
+// `josh help <command>`: the synopsis line, the description, then the usage block. An alias
+// resolves to its command; a name that is neither answers `undefined`.
 function format_command_help(input: string): string | undefined {
 	const name = canonical_command(input)
 	const entry = Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name] : undefined
 	if (entry === undefined) return undefined
 	const [synopsis] = entry.reference
 	const head = synopsis ? `josh ${name} ${synopsis}` : `josh ${name}`
-	const usage = format_usage(name)
-
-	return [head, '', entry.description, ...(usage === undefined ? [] : ['', usage])].join('\n')
-}
-
-// The commands whose usage blocks a reference page renders — the keys of the tables tied to it.
-function page_commands(page: string): Array<string> {
-	const tables = Object.hasOwn(USAGE_PAGE_TABLES, page) ? USAGE_PAGE_TABLES[page] : undefined
 
-	return (tables ?? []).flatMap((table) => Object.keys(table))
+	return [head, '', entry.description, '', format_usage(name)].join('\n')
 }
 
 const command_usage = {
-	USAGE_PAGES: Object.keys(USAGE_PAGE_TABLES),
+	USAGE_PAGES,
 	format_command_help,
 	format_usage,
-	page_commands,
 }
 
 export { command_usage }

package/scripts/josh/durable-state-migrate.ts

@@ -0,0 +1,105 @@
+import { constants, copyFileSync, lstatSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// The two upkeep jobs of the durable run-state directory (`durable-state.ts`), each run at most once
+// per process per directory rather than on every record lookup.
+//
+// **A legacy record is copied once per directory.** A run that is going when
+// this lands wrote its records to `/tmp`, and reading only the new place would end it as a reboot
+// did. Copying on every lookup instead brought back a record a run removed on purpose — an ended
+// carry, a stopped launch, a failed ship's result — from the `/tmp` original. The original is left
+// in place: a lane or parent still on the code before this change reads `/tmp` until it merges main.
+// A copy rather than a rename because `/tmp` is often another filesystem. A record an old-code
+// process writes to `/tmp` after the copy is not picked up.
+//
+// **A log not written for two weeks is removed.** `/tmp` used to clear them on every boot; the common
+// git directory never does, and a log is the only record here that grows without an owner ending it.
+
+const COPIED_MARKER = '.legacy-copied'
+const MARKER_MODE = 0o600
+const LOG_RETENTION_DAYS = 14
+const DAY_MS = 86_400_000
+const LOG_SUFFIX = '.log'
+// What a record is. A lock or a staged write beside a record carries its prefix but means nothing
+// past the process that made it.
+const RECORD_SUFFIXES = ['.json', '.jsonl', LOG_SUFFIX] as const
+
+function is_record_name(name: string, prefixes: ReadonlyArray<string>): boolean {
+	const has_prefix = prefixes.some((prefix) => name.startsWith(prefix))
+
+	return has_prefix && RECORD_SUFFIXES.some((suffix) => name.endsWith(suffix))
+}
+
+function list_names(directory: string): Array<string> {
+	try {
+		return readdirSync(directory)
+	} catch {
+		return []
+	}
+}
+
+function copy_record(from: string, to: string): void {
+	try {
+		if (!stamp_file.is_own_regular_file(from)) return
+
+		copyFileSync(from, to, constants.COPYFILE_EXCL)
+	} catch {
+		// Another process wrote it first, or the copy failed; either way nothing is overwritten.
+	}
+}
+
+function copy_legacy(from: string, to: string, prefixes: ReadonlyArray<string>): void {
+	if (from === to) return
+
+	for (const name of list_names(from)) {
+		if (is_record_name(name, prefixes)) copy_record(path.join(from, name), path.join(to, name))
+	}
+}
+
+// The marker is created exclusively, so one process wins the copy. A marker rather than whether
+// `mkdirSync` made the directory: a lane on this code can create the shared directory before the run
+// that owns the `/tmp` records switches over, and that run still needs its copy.
+function claim_copy(directory: string): boolean {
+	try {
+		writeFileSync(path.join(directory, COPIED_MARKER), '', { flag: 'wx', mode: MARKER_MODE })
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+function copy_once(from: string, to: string, prefixes: ReadonlyArray<string>): void {
+	if (claim_copy(to)) copy_legacy(from, to, prefixes)
+}
+
+function is_stale(target: string, now_ms: number): boolean {
+	const age_ms = now_ms - lstatSync(target).mtimeMs
+
+	return age_ms > LOG_RETENTION_DAYS * DAY_MS && stamp_file.is_own_regular_file(target)
+}
+
+function prune_log(target: string, now_ms: number): void {
+	try {
+		if (is_stale(target, now_ms)) rmSync(target, { force: true })
+	} catch {
+		// Gone already, or not ours to remove.
+	}
+}
+
+function prune_stale_logs(
+	directory: string,
+	prefixes: ReadonlyArray<string>,
+	now_ms: number,
+): void {
+	for (const name of list_names(directory)) {
+		if (name.endsWith(LOG_SUFFIX) && is_record_name(name, prefixes)) {
+			prune_log(path.join(directory, name), now_ms)
+		}
+	}
+}
+
+const durable_state_migrate = { LOG_RETENTION_DAYS, copy_once, is_record_name, prune_stale_logs }
+
+export { durable_state_migrate }

package/scripts/josh/durable-state.ts

@@ -0,0 +1,112 @@
+import { mkdirSync } from 'node:fs'
+import path from 'node:path'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { durable_state_migrate } from '#scripts/josh/durable-state-migrate'
+import { PLATFORM_TEMP_ROOT, platform_temporary } from '#scripts/josh/platform-temporary'
+import { stamp_file } from '#scripts/josh/stamp-file'
+
+// **Which record goes where — the one place this is decided.** A record a run has to read again after
+// the machine restarts lives here, in the common git directory: the carry and ended records, the event
+// stream, the lane state and ledger, the wake log, the backlogrun launch record and log, the detached
+// ship's log and result, and a lane child's dispatch log. macOS empties `/tmp` on every boot, and losing them
+// there left the open lanes stateless, the merge statistics empty and a parked ship's failure
+// unreadable. Everything that means nothing past the process that wrote it — a lock, a pid, a socket,
+// a per-process cache — stays in `PLATFORM_TEMP_ROOT`, where a reboot clearing it is the right answer.
+//
+// **The common git directory rather than the home directory**, because a Codex lane's sandbox reads
+// `$HOME` but may write the common git directory (`codex-agent-argv.ts`), and every lane of one
+// repository shares it. A repository's own clone is also where `review-stops.jsonl` already lives.
+// Outside a repository there is no such directory, and the record falls back to the temp root.
+//
+// **Records a run left in `/tmp` are copied in once per directory, and a log not written for two
+// weeks is removed** (`durable-state-migrate.ts`).
+//
+// **`JOSH_TEMP_ROOT` moves this root too**, into a directory of its own beneath the override, so the unit
+// suite's network guard keeps every record of a test run out of the live one exactly as before.
+const RUN_STATE_DIRECTORY = 'run-state'
+const OVERRIDE_STATE_DIRECTORY = 'josh-state'
+const STATE_DIRECTORY_MODE = 0o700
+
+function state_root(override: string | undefined, common: string | undefined): string {
+	if (override !== undefined && override !== '') {
+		return path.join(override, OVERRIDE_STATE_DIRECTORY)
+	}
+
+	if (common === undefined) return PLATFORM_TEMP_ROOT
+
+	return path.join(common, git_common_directory.STATE_DIRECTORY, RUN_STATE_DIRECTORY)
+}
+
+// Read once at import, as `PLATFORM_TEMP_ROOT` is, so both roots answer for the same override.
+const STATE_ROOT_OVERRIDE = process.env[platform_temporary.TEMP_ROOT_KEY]
+
+// The root for a named common git directory — what a launcher grants a sandboxed child before it runs.
+function root_for(common: string | undefined): string {
+	return state_root(STATE_ROOT_OVERRIDE, common)
+}
+
+function root(): string {
+	return root_for(git_common_directory.repository())
+}
+
+// Every record kept here, by the prefix of its file name — the list the one-time copy from `/tmp`
+// walks, so a record added here is carried over with the rest.
+const PREFIX = {
+	CARRY: 'josh-run-carry-',
+	ENDED: 'josh-run-ended-',
+	EVENTS: 'josh-run-events-',
+	LANE_STATE: 'josh-lane-state-',
+	LANE_LEDGER: 'josh-lane-ledger-',
+	WAKE_LOG: 'josh-run-wake-log-',
+	BACKLOGRUN_LAUNCH: 'josh-backlogrun-launch-',
+	BACKLOGRUN_LOG: 'josh-backlogrun-log-',
+	SHIP_LOG: 'josh-ship-log-',
+	SHIP_RESULT: 'josh-ship-result-',
+	LANE_DISPATCH: 'josh-lane-dispatch-',
+	LANE_PLAN: 'josh-lane-plan-',
+} as const
+
+const PREFIXES: ReadonlyArray<string> = Object.values(PREFIX)
+
+// Directories this process has already made ready, so the upkeep runs once rather than per lookup.
+const ensured = new Set<string>()
+
+function prepare(directory: string): void {
+	mkdirSync(directory, { recursive: true, mode: STATE_DIRECTORY_MODE })
+	durable_state_migrate.copy_once(PLATFORM_TEMP_ROOT, directory, PREFIXES)
+	durable_state_migrate.prune_stale_logs(directory, PREFIXES, Date.now())
+}
+
+// **A directory that cannot be created answers the temp root rather than throwing** — a sandbox that
+// may not write the common git directory still runs, with the records `/tmp` always held.
+function ensure(directory: string): string {
+	if (ensured.has(directory)) return directory
+
+	try {
+		prepare(directory)
+	} catch {
+		return PLATFORM_TEMP_ROOT
+	}
+
+	ensured.add(directory)
+
+	return directory
+}
+
+// The durable counterpart of `stamp_file.stamp_path`: the same per-account, per-key file name, in the
+// directory above. The directory is created on the way, private to the account.
+function durable_path(prefix: string, key_root: string, suffix?: string): string {
+	return path.join(ensure(root()), stamp_file.stamp_name(prefix, key_root, suffix))
+}
+
+const durable_state = {
+	PREFIX,
+	STATE_DIRECTORY_MODE,
+	ensure,
+	path: durable_path,
+	root,
+	root_for,
+	state_root,
+}
+
+export { durable_state }

package/scripts/josh/file-map-stamp.ts

@@ -3,7 +3,7 @@ import { stamp_file } from './stamp-file'
 
 // A stamp whose payload is "when this was taken, and the digest of every file it covers".
 //
-// `scripts/eval/eval-stamp.ts` was the only holder of this shape. `josh review:brief` needs two more
+// `tools/eval/eval-stamp.ts` was the only holder of this shape. `josh review:brief` needs two more
 // records of exactly the same kind — the gate's result, and the snapshot round 1 takes so round 2
 // can name the fix delta — and copying the payload type, its validation, the guarded read and the
 // comparison into a second module is the clone `CLAUDE.md` prohibits. What genuinely differs between
@@ -48,6 +48,14 @@ interface FileMapStamp {
 	// reads it and the two `josh review:brief` records, which assert a completed past fact by
 	// existing at all, neither write nor read it.
 	completed_at?: string
+	// The git blob of each mapped path as it was read — written only by the round-1 review snapshot
+	// (`review-round-one-blobs.ts`). When `base` moves, round 2 carries these onto the new base and
+	// measures the fix delta from there; a record without them falls back to the moved-base refusal.
+	blobs?: Record<string, string>
+	// The fingerprint of what the vouched check reads beside the files — its tools' versions and its
+	// environment (`verification-inputs.ts`, joshuafolkken/kit#4495). Written by a record created with an
+	// `inputs` source; a reader of such a record refuses one whose fingerprint is absent or differs.
+	inputs?: string
 }
 
 // Takes `unknown` rather than the declared field type, because the declared type is an assertion
@@ -64,28 +72,38 @@ function is_file_map(value: unknown): value is Record<string, string> {
 // reader treats an absent field as the safe answer — "not running" for a `pid`, "cannot be reused"
 // for a `base`. Spread rather than assigned, because `exactOptionalPropertyTypes` makes an explicit
 // `undefined` a different thing from an absent key.
-function optional_fields(
-	pid: unknown,
-	base: unknown,
-	completed_at: unknown,
-	process_start: unknown,
-): Partial<FileMapStamp> {
+function identity_fields({ pid, process_start }: Partial<FileMapStamp>): Partial<FileMapStamp> {
 	return {
 		...(typeof pid === 'number' && { pid }),
+		...(typeof process_start === 'string' && { process_start }),
+	}
+}
+
+function tree_fields({ base, completed_at, blobs }: Partial<FileMapStamp>): Partial<FileMapStamp> {
+	return {
 		...(typeof base === 'string' && { base }),
 		...(typeof completed_at === 'string' && { completed_at }),
-		...(typeof process_start === 'string' && { process_start }),
+		...(is_file_map(blobs) && { blobs }),
 	}
 }
 
+function input_fields({ inputs }: Partial<FileMapStamp>): Partial<FileMapStamp> {
+	return typeof inputs === 'string' ? { inputs } : {}
+}
+
 function parse_stamp(raw: string): FileMapStamp | undefined {
-	const { taken_at, files, pid, base, completed_at, process_start } = JSON.parse(
-		raw,
-	) as Partial<FileMapStamp>
+	const parsed = JSON.parse(raw) as Partial<FileMapStamp>
+	const { taken_at, files } = parsed
 
 	if (typeof taken_at !== 'string' || !is_file_map(files)) return undefined
 
-	return { taken_at, files, ...optional_fields(pid, base, completed_at, process_start) }
+	return {
+		taken_at,
+		files,
+		...identity_fields(parsed),
+		...tree_fields(parsed),
+		...input_fields(parsed),
+	}
 }
 
 // Whether the process that wrote this record is still running. It takes the
@@ -152,14 +170,22 @@ function changed_since(stamp: FileMapStamp, tree: Record<string, string>): Reado
 interface FileMapStampAccess {
 	stamp_path: () => string
 	// `base` is written by the one record that is acted on rather than merely reported — the
-	// green-gate reuse. The others omit it and are unaffected.
-	write: (files: Record<string, string>, target?: string, base?: string) => string
+	// green-gate reuse. The others omit it and are unaffected. `blobs` is the round-1 snapshot's alone.
+	write: (
+		files: Record<string, string>,
+		target?: string,
+		base?: string,
+		blobs?: Record<string, string>,
+	) => string
 	// Marks an existing record as belonging to a run that finished. It
 	// amends rather than rewrites, and answers `undefined` where there is no record to amend: a run
 	// whose record never got written has nothing to assert a completion about, and inventing one here
 	// would manufacture the very vouching the field exists to withhold.
 	complete: (target?: string) => string | undefined
 	read: (source?: string) => FileMapStamp | undefined
+	// Whether `stamp` was written under the inputs fingerprint read now; always `true` for a record
+	// created without an `inputs` source, which never vouches for a check.
+	describes_inputs: (stamp: FileMapStamp) => boolean
 	// For a record whose meaning is its existence rather than its contents — the in-flight gate marker.
 	// A record nobody removes would go on asserting a gate that ended.
 	remove: (target?: string) => void
@@ -219,7 +245,11 @@ function complete_at(target: string): string | undefined {
 // The destination is a parameter on both sides so a test can exercise the round trip without
 // overwriting the record a real run may be relying on — two commands share one path by design, and a
 // suite that wrote to it would be a second writer nobody declared.
-function create(prefix: string, root?: string): FileMapStampAccess {
+//
+// `inputs` answers the fingerprint of what the record vouches for beside its files
+// (`verification-inputs.ts`); it is read at each write and each comparison, so a tool reinstalled or an
+// environment variable changed between them leaves the record standing for nobody.
+function create(prefix: string, root?: string, inputs?: () => string): FileMapStampAccess {
 	function resolve(): string {
 		return stamp_file.stamp_path(prefix, root)
 	}
@@ -229,15 +259,18 @@ function create(prefix: string, root?: string): FileMapStampAccess {
 		// `base` goes into the payload undefined and all — `JSON.stringify` drops an undefined value,
 		// so a caller that has no base writes exactly the record it wrote before this field existed.
 		// `own_fields` is what writes the pid, and the writing process's start time beside it — assembled in one place so no record can carry half an identity.
-		write: (files, target = resolve(), base?: string) =>
+		write: (files, target = resolve(), base?: string, blobs?: Record<string, string>) =>
 			stamp_file.write_stamp(target, {
 				taken_at: new Date().toISOString(),
 				files,
 				...process_identity.own_fields(),
 				base,
+				blobs,
+				inputs: inputs?.(),
 			}),
 		complete: (target = resolve()) => complete_at(target),
 		read: (source = resolve()) => read_at(source),
+		describes_inputs: (stamp) => inputs === undefined || stamp.inputs === inputs(),
 		remove: (target = resolve()) => {
 			stamp_file.remove_stamp(target)
 		},