@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,188 @@
+// The environment variables that name the **parent** agent session, and which a child session must
+// not inherit.
+//
+// It lived inside `scripts/eval/eval-session.ts` until `josh run:wake` became a second launcher of a
+// headless session (joshuafolkken/kit#1719). 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
+// `API Error: Unable to connect to API (ConnectionRefused)` with nothing anywhere naming the cause.
+//
+// `CLAUDE_CODE_MESSAGING_SOCKET` is a UNIX socket only the parent listens on,
+// `CLAUDE_CODE_MESSAGING_TOKEN` is that socket's credential, and the two session identifiers claim
+// the parent's session as the child's own. Measured under joshuafolkken/kit#1158: removing them
+// restored 5/5 held in 54 seconds, and lowering the concurrency — the suspected cause before this one
+// was found — made it worse.
+//
+// **`SESSION_ID_KEY` is the name Claude Code exports for the running session's own id** — the base
+// name of that session's transcript file. It is single-sourced here rather than spelled a second time
+// where the cost reader identifies its own transcript by it (joshuafolkken/kit#2403): one env var,
+// one literal, so the list a child must not inherit and the selection that reads it cannot drift.
+const SESSION_ID_KEY = 'CLAUDE_CODE_SESSION_ID'
+
+const PARENT_SESSION_KEYS: ReadonlyArray<string> = [
+	'CLAUDE_CODE_MESSAGING_SOCKET',
+	'CLAUDE_CODE_MESSAGING_TOKEN',
+	SESSION_ID_KEY,
+	'CLAUDE_CODE_CHILD_SESSION',
+]
+
+// **The second thing a child must not inherit is a proxy that belongs to the invocation which
+// launched it** (joshuafolkken/kit#1760). `pnpm josh run:wake --start` runs under whatever wraps this
+// machine's package manager — here a supply-chain scanner, which stands a proxy up on a loopback port
+// and writes `HTTPS_PROXY=http://localhost:<ephemeral>` plus its own CA into the environment of
+// everything that invocation spawns. The supervisor is **detached**, so it outlives that proxy and
+// hands the dead address to every session it wakes. The agent CLI obeys it, finds nothing listening,
+// and dies with the very same `ConnectionRefused` the paragraph above describes — measured at 2 m 57 s
+// per wake, three wakes per cut, and a backlog that stops at its first session cut.
+//
+// **`eval-session.ts` gets the same treatment, and that is deliberate rather than collateral.** Only a
+// detached launcher outlives the proxy, so that suite was never the one failing; but neither launcher
+// starts a package install, and a scanning proxy that exists to inspect package downloads has no
+// business carrying an agent session's API traffic. Making the removal conditional on the call site
+// would split one helper into two rules to keep in step, and leave the eval suite the one place a
+// dead address can still be inherited.
+//
+// **Every spelling goes, because the one left behind is the one obeyed.** Clients disagree about
+// which variable wins — `ALL_PROXY` is honoured by curl and by several Node agents, the lowercase
+// forms by most of the rest — so removing a subset leaves the failure exactly where it was.
+const PROXY_KEYS: ReadonlyArray<string> = [
+	'ALL_PROXY',
+	'HTTP_PROXY',
+	'HTTPS_PROXY',
+	'all_proxy',
+	'http_proxy',
+	'https_proxy',
+	'GLOBAL_AGENT_HTTP_PROXY',
+	'GLOBAL_AGENT_HTTPS_PROXY',
+]
+
+// The CA certificate exists to make that interception verifiable, so it goes only when **every** proxy
+// the environment declares is going with it. Left alone it may be a person's corporate trust store;
+// removed while one of their proxies survives, it takes that proxy's TLS down with it — which is the
+// worse of the two mistakes, since the session then reaches nothing at all.
+const PROXY_CERTIFICATE_KEY = 'NODE_EXTRA_CA_CERTS'
+
+// **Loopback is the test, and it is what keeps a real proxy untouched.** A proxy on this machine's own
+// interface was stood up by some process here, so a launcher that outlives its own parent cannot
+// assume the port is still that proxy's; one naming a real host is somebody's network and is left
+// exactly as it was. Deciding instead by "did a package manager set it" would need a wrapper
+// inventory nobody can keep current.
+//
+// **The spellings are what `URL` reports, not what a wrapper typed**: `::1` without its brackets is
+// not a URL host at all, and `http://[::1]:52554` parses with the brackets kept — so listing the bare
+// form beside it would be a row nothing can ever match. The whole of `127.0.0.0/8` is loopback, not
+// just `127.0.0.1`, so that half is a prefix rather than a literal.
+const LOOPBACK_HOSTS: ReadonlyArray<string> = ['localhost', 'ip6-localhost', '[::1]']
+const LOOPBACK_PREFIX = '127.'
+const NO_HOST = ''
+
+type EnvironmentSource = Readonly<Record<string, string | undefined>>
+type RemovedEnvironment = Record<string, undefined>
+
+function parsed_host(value: string): string {
+	try {
+		return new URL(value).hostname
+	} catch {
+		return NO_HOST
+	}
+}
+
+// **A value with no scheme is read again with one assumed.** `HTTPS_PROXY=localhost:52554` is what
+// curl and npm both accept, and `new URL` reads it as the `localhost:` scheme with no host at all —
+// so a single parse would hand exactly that dead address on as "not a loopback proxy".
+function proxy_host(value: string): string {
+	const direct = parsed_host(value)
+
+	return direct === NO_HOST ? parsed_host(`http://${value}`) : direct
+}
+
+function is_loopback_host(host: string): boolean {
+	return host.startsWith(LOOPBACK_PREFIX) || LOOPBACK_HOSTS.includes(host)
+}
+
+function is_loopback_proxy(value: string | undefined): boolean {
+	if (value === undefined || value === NO_HOST) return false
+
+	return is_loopback_host(proxy_host(value))
+}
+
+function is_declared(value: string | undefined): boolean {
+	return value !== undefined && value !== NO_HOST
+}
+
+// The certificate joins only when the environment declares no proxy this leaves standing. A machine
+// whose wrapper wrote one loopback proxy beside the person's own corporate one keeps both the
+// corporate proxy and the trust store that makes it usable.
+function loopback_proxy_keys(
+	source: EnvironmentSource,
+	is_removed: (value: string | undefined) => boolean = is_loopback_proxy,
+): ReadonlyArray<string> {
+	const declared = PROXY_KEYS.filter((key) => is_declared(source[key]))
+	const matched = declared.filter((key) => is_removed(source[key]))
+	const is_certificate_included = matched.length > 0 && matched.length === declared.length
+
+	return is_certificate_included ? [...matched, PROXY_CERTIFICATE_KEY] : matched
+}
+
+// **`undefined` rather than `''`**, because an empty socket path is still a socket path to whatever
+// reads it. Node's spawn omits an environment key whose value is `undefined`, which is the only way
+// to hand the child an environment that does not have the variable at all — and both callers spread
+// this over an inherited environment, so anything less than absent leaves the variable set.
+function to_removed(keys: ReadonlyArray<string>): RemovedEnvironment {
+	return Object.fromEntries(keys.map((key) => [key, undefined]))
+}
+
+function removed_environment(source: EnvironmentSource = process.env): RemovedEnvironment {
+	return to_removed([...PARENT_SESSION_KEYS, ...loopback_proxy_keys(source)])
+}
+
+// **The scanner is recognized by the CA it writes beside its proxy** — a file under its own
+// `.safe-chain` directory. Either separator is accepted so the test holds wherever the path came from.
+const SCANNER_DIRECTORY = '.safe-chain'
+const PATH_SEPARATOR = /[/\\]/u
+
+function is_scanner_certificate(value: string | undefined): boolean {
+	return value?.split(PATH_SEPARATOR).includes(SCANNER_DIRECTORY) ?? false
+}
+
+// **Only the scanner's own address goes.** It writes one address into `HTTPS_PROXY` and its
+// `global-agent` twin; a loopback proxy at any other address — a sandbox egress proxy in `ALL_PROXY`
+// or a lowercase spelling — is not its, may be the only route out, and stays.
+const SCANNER_PROXY_KEY = 'HTTPS_PROXY'
+
+function is_scanner_proxy(source: EnvironmentSource): (value: string | undefined) => boolean {
+	const scanner_proxy = source[SCANNER_PROXY_KEY]
+
+	return function is_match(value: string | undefined): boolean {
+		return value === scanner_proxy && is_loopback_proxy(value)
+	}
+}
+
+// **The proxy half alone, for a spawn that is not a session** (joshuafolkken/kit#2436). kit's `gh`
+// requests inherited the same loopback proxy, and the scanner behind it tunnels api.github.com
+// without inspecting it — so routing GitHub through it protected nothing and added a failure point:
+// the scanner release installed here marked a host it had once timed out on as dead for the rest of
+// the invocation, and every later `followup` read of that run failed at once with `Bad Gateway`.
+// The session keys stay out: a `gh` spawn has no parent session to be confused with.
+//
+// **Unlike a detached session, a `gh` spawn runs while its loopback proxy is alive** — and that
+// proxy may be the machine's only way out (a sandboxed agent's egress proxy, a corporate authenticating proxy on
+// `127.0.0.1:3128`). Loopback alone therefore cannot decide it: the removal happens only when the
+// declared CA is the scanner's own, and every other loopback proxy is left exactly as it was.
+function removed_proxy_environment(source: EnvironmentSource = process.env): RemovedEnvironment {
+	if (!is_scanner_certificate(source[PROXY_CERTIFICATE_KEY])) return {}
+
+	return to_removed(loopback_proxy_keys(source, is_scanner_proxy(source)))
+}
+
+const agent_session_environment = {
+	LOOPBACK_HOSTS,
+	PARENT_SESSION_KEYS,
+	PROXY_CERTIFICATE_KEY,
+	PROXY_KEYS,
+	SESSION_ID_KEY,
+	removed_environment,
+	removed_proxy_environment,
+}
+
+export { agent_session_environment }

package/scripts/josh/cli-body.ts

@@ -0,0 +1,96 @@
+import { readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+// A body — an Issue comment, a PR comment, a notification message — handed to a command as an inline
+// double-quoted shell argument is **evaluated by the shell before the command ever sees it**
+// (joshuafolkken/kit#1198). The observed damage is not a mangled string: a PR comment posted with
+// `gh api … -f body="… \`pnpm josh ms\` …"` had part of its own text run as git commands, which
+// switched a lane's work tree onto `main` and stopped the run.
+//
+// So every command that takes a body offers a path-shaped way in, and this module is the one that
+// reads it. It exists as a module rather than per entry point because `epic-cli.ts` already had the
+// reader for `--rationale-file` / `--decision-file`, and a second copy is the clone `CLAUDE.md`
+// prohibits — in the one place where two copies would disagree about what `-` means.
+
+// `-` reads stdin, matching `gh issue create --body-file -`. Shared by every `*-file` flag rather
+// than spelled out per flag, so the stdin form cannot come to mean one thing under one and something
+// else under another.
+const STDIN_PATH = '-'
+const STDIN_FD = 0
+
+// The escape a caller writes when the body has to stay one shell token. It is expanded for the
+// **inline** form only: a file already holds real newlines, and expanding there would rewrite a
+// literal backslash-n that the author put in the body on purpose.
+const ESCAPED_NEWLINE = String.raw`\n`
+
+// **The path is resolved and checked before it is opened**, rather than handed to `readFileSync` as
+// it arrived. The value comes from a command line an agent composed, so the failure worth guarding is
+// a wrong path reaching the file system unexamined — a missing path, or a directory. What comes back
+// instead is one sentence naming the resolved path, which is the difference between a completion
+// notification that fails legibly and one that dies on a raw `ENOENT` mid-merge.
+//
+// **The check refuses those two, not "everything that is not a regular file."** `epic --rationale-file`
+// accepted any readable path before this module existed, and the two spellings a run actually reaches
+// for are not regular files: `--rationale-file /dev/stdin` is a character device or a symlink to a
+// pipe, and a `<(…)` process substitution arrives as the FIFO `/dev/fd/63`. An `isFile()` test rejects
+// both with `Not a readable file`, which is a regression dressed as a guard — so the test is
+// `isDirectory()`, and anything else readable is opened exactly as it was before.
+function read_body_file(raw_path: string): string {
+	const resolved = path.resolve(raw_path)
+	const stats = statSync(resolved, { throwIfNoEntry: false })
+
+	if (stats === undefined || stats.isDirectory()) {
+		throw new Error(`Not a readable file: ${resolved}`)
+	}
+
+	return readFileSync(resolved, 'utf8')
+}
+
+function read_file_or_stdin(raw_path: string): string {
+	return raw_path === STDIN_PATH ? readFileSync(STDIN_FD, 'utf8') : read_body_file(raw_path)
+}
+
+function expand_escaped_newlines(raw: string): string {
+	return raw.replaceAll(ESCAPED_NEWLINE, '\n')
+}
+
+// A flag counts as given only when it carries text, so `--body ''` is not an answer.
+function has_value(raw: string | undefined): boolean {
+	return raw !== undefined && raw.length > 0
+}
+
+// The inline half, kept apart so `resolve` reads as the one decision it makes: file or not.
+//
+// **Trim first, expand second — the order the inline form has always had.** `git_notify` used to run
+// `raw.trim().replaceAll(…)` in one expression; moving only the expansion up here would leave a trim
+// downstream of it, and a body written `--notify-message "…\n"` would have its own trailing newline
+// eaten as surrounding whitespace. Trimming the raw argument removes quoting slack, which is the only
+// whitespace a shell token picks up by accident; the newlines the escape produces are the author's
+// text and survive it.
+function resolve_inline(inline: string | undefined): string | undefined {
+	return inline === undefined ? undefined : expand_escaped_newlines(inline.trim())
+}
+
+// **Both flags at once is refused rather than ranked.** A precedence rule would let a caller that
+// meant the file silently ship the inline string it was trying to get away from, which is the exact
+// failure this option exists to remove.
+function resolve(input: {
+	inline: string | undefined
+	file_path: string | undefined
+	inline_flag: string
+	file_flag: string
+}): string | undefined {
+	const { inline, file_path } = input
+
+	if (file_path === undefined || file_path.length === 0) return resolve_inline(inline)
+
+	if (has_value(inline)) {
+		throw new Error(`Pass ${input.inline_flag} or ${input.file_flag}, not both.`)
+	}
+
+	return read_file_or_stdin(file_path)
+}
+
+const cli_body = { read_file_or_stdin, expand_escaped_newlines, has_value, resolve }
+
+export { cli_body }

package/scripts/josh/command-suggest.ts

@@ -0,0 +1,57 @@
+// A single-token "did you mean" for `josh <typo>`. The command set is small and the input is one
+// word, so a character edit distance is the right measure here — unlike `issue-scout`'s token-set
+// Dice similarity, which compares multi-word issue titles (joshuafolkken/kit#1928).
+const MAX_SUGGESTION_DISTANCE = 3
+
+// A cell of the matrix, defaulting the out-of-range read to 0. Reading through it keeps the nullish
+// guards out of `fill_distance_row`, where they would each count against its complexity limit.
+function at(values: ReadonlyArray<number>, index: number): number {
+	return values[index] ?? 0
+}
+
+// One row of the Levenshtein matrix, built from the previous row. Kept a function of its own so the
+// distance itself stays a single loop rather than two nested ones.
+function fill_distance_row(
+	source: string,
+	target: string,
+	row: number,
+	previous: ReadonlyArray<number>,
+): Array<number> {
+	const current = [row]
+
+	for (let col = 1; col <= target.length; col++) {
+		const cost = source[row - 1] === target[col - 1] ? 0 : 1
+		const deletion = at(previous, col) + 1
+		const insertion = at(current, col - 1) + 1
+		const substitution = at(previous, col - 1) + cost
+
+		current.push(Math.min(deletion, insertion, substitution))
+	}
+
+	return current
+}
+
+function edit_distance(source: string, target: string): number {
+	let previous = Array.from({ length: target.length + 1 }, (_unused, index) => index)
+
+	for (let row = 1; row <= source.length; row++) {
+		previous = fill_distance_row(source, target, row, previous)
+	}
+
+	return at(previous, target.length)
+}
+
+// The closest command name to `input`, or undefined when nothing is within `MAX_SUGGESTION_DISTANCE`
+// — a wrong guess is worse than none, so a distant match is dropped rather than shown.
+function closest_command(input: string, commands: ReadonlyArray<string>): string | undefined {
+	const within = commands
+		.map((command) => ({ command, distance: edit_distance(input, command) }))
+		.filter((scored) => scored.distance <= MAX_SUGGESTION_DISTANCE)
+		.toSorted((left, right) => left.distance - right.distance)
+
+	return within[0]?.command
+}
+
+const command_suggest = { closest_command, edit_distance }
+
+export { command_suggest, MAX_SUGGESTION_DISTANCE }

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

@@ -0,0 +1,264 @@
+import { process_identity } from './process-identity'
+import { stamp_file } from './stamp-file'
+
+// A stamp whose payload is "when this was taken, and the digest of every file it covers"
+// (joshuafolkken/kit#1241).
+//
+// `scripts/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
+// the three is **which tree is read**, so that stays with each caller and everything else lives here.
+//
+// The record is deliberately not a `git diff`: the implementation and a review's fixes are
+// uncommitted in the same tree, so a diff cannot say which side of the review a change fell on —
+// which is the one question both readers ask.
+
+interface FileMapStamp {
+	taken_at: string
+	files: Record<string, string>
+	// The process that wrote it. Only a record whose meaning is "this is happening **now**" needs it —
+	// the in-flight gate marker (joshuafolkken/kit#1242). The other two assert a completed past fact,
+	// which stays true however long the file sits there, so they carry it and never read it.
+	pid?: number
+	// The other half of that process's identity: when it started (joshuafolkken/kit#1245). **A pid
+	// alone names whatever holds that number now**, so a marker left behind by a killed gate began
+	// reading as live again the moment the operating system reissued its pid — the brief then reporting
+	// a gate running on this tree about a gate that no longer exists. The pair separates them, because
+	// a reissued pid necessarily started after the record was written. Written by every record and read
+	// only by the one that asserts the present, exactly as `pid` already was; a record written before
+	// the field existed carries none, which `process_identity.is_same_process` answers as "cannot tell"
+	// rather than as a match.
+	process_start?: string
+	// The commit the file map is defined against (joshuafolkken/kit#1328). Every reader of these
+	// records computes its map as a diff against that commit — the branch's merge base with the
+	// default branch since joshuafolkken/kit#1527 — so **the map alone does not describe a tree**:
+	// fetch an advanced default branch and rebase onto it, and every digest can stay identical while
+	// the rest of the working tree is replaced by code no check has read. The rebase moves `HEAD` and
+	// so moves the merge base, which is what this field catches; another lane merging into the shared
+	// default branch moves neither, and correctly leaves the record standing. Every reader that acts on
+	// a record rather than merely reporting it needs the guarantee: `josh gate`, which reuses a green
+	// result instead of re-running it, and since joshuafolkken/kit#1537 the round-1 review snapshot,
+	// whose whole use is to name what round 1's fixes changed. A record written without it is refused
+	// rather than trusted.
+	base?: string
+	// When the run that wrote this record reached its verdict (joshuafolkken/kit#1164). Written only
+	// by `complete`, so it is absent on a record whose run was interrupted or threw — which is the
+	// whole difference between "a run measured this tree" and "a run measured this tree and
+	// finished". Only a reader that acts on the *verdict* needs the second, so `josh eval` writes and
+	// 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
+}
+
+// Takes `unknown` rather than the declared field type, because the declared type is an assertion
+// over whatever was on disk: the file is written by one command and read by another, and a truncated
+// or hand-edited one has to answer "no record" rather than reach the comparison as a lie.
+function is_file_map(value: unknown): value is Record<string, string> {
+	if (typeof value !== 'object' || value === null) return false
+
+	return Object.values(value).every((entry) => typeof entry === 'string')
+}
+
+// An optional field of the wrong type is dropped rather than rejected: the records that never read
+// one were written without it before joshuafolkken/kit#1242 and joshuafolkken/kit#1328, and every
+// 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> {
+	return {
+		...(typeof pid === 'number' && { pid }),
+		...(typeof base === 'string' && { base }),
+		...(typeof completed_at === 'string' && { completed_at }),
+		...(typeof process_start === 'string' && { process_start }),
+	}
+}
+
+function parse_stamp(raw: string): FileMapStamp | undefined {
+	const { taken_at, files, pid, base, completed_at, process_start } = JSON.parse(
+		raw,
+	) as Partial<FileMapStamp>
+
+	if (typeof taken_at !== 'string' || !is_file_map(files)) return undefined
+
+	return { taken_at, files, ...optional_fields(pid, base, completed_at, process_start) }
+}
+
+// Whether the process that wrote this record is still running (joshuafolkken/kit#1245). It takes the
+// whole record rather than a pid, because a pid on its own is not a process: asked that way a caller
+// could not tell the writing process from whatever the operating system later reissued its number to,
+// which is exactly the state the in-flight marker must never describe.
+//
+// **Three answers, and no record at all is the definite `false`.** `undefined` is "there is a live
+// process with that pid and this platform cannot say whether it is the writer" — a record from before
+// the field existed, a machine with no `ps`, or a probe that failed under load.
+function writer_state(stamp: FileMapStamp | undefined): boolean | undefined {
+	if (stamp === undefined) return false
+
+	return process_identity.is_same_process(stamp.pid, stamp.process_start)
+}
+
+// **For a claim: only when certain.** `josh review:brief` prints "a gate is running on this tree", so
+// an uncertain answer must not become that sentence; it becomes `Not verified`, and the run pays one
+// redundant reading of checks it was already running.
+function is_writer_running(stamp: FileMapStamp | undefined): boolean {
+	return writer_state(stamp) === true
+}
+
+// **For a guard: only when certain of the opposite.** `josh bench` deletes caches a running gate is
+// reading, so the question it must ask is not "is the writer running" but "am I sure it is gone" — an
+// uncertain answer there would clear the caches out from under a live gate, which is the very event
+// joshuafolkken/kit#1332 was filed for. The probe is a subprocess and can fail on a loaded machine,
+// which is exactly the machine a gate makes, so this is not a theoretical branch.
+function is_writer_gone(stamp: FileMapStamp | undefined): boolean {
+	return writer_state(stamp) === false
+}
+
+// Whether a record may be compared against a map read now (joshuafolkken/kit#1537). Every map here is
+// a diff against `change_base`, so two of them taken against **different** bases do not cover the same
+// set of paths — and `changed_since` below reports that set difference as though the files had been
+// edited. Measured on the resumed runs of #1080 / #1085 / #1147 / #1197: a merge of the default branch
+// between the two rounds moved the base, and the round-2 target then named files the branch had never
+// touched while omitting files it had.
+//
+// **A record written before the field existed carries no base, and that reads as "cannot be compared"
+// rather than "matches".** The caller's only safe response to an unusable record is to widen its
+// round, never to narrow it, so the absent case has to fall on the same side as a mismatch.
+//
+// **`undefined` on either side is a mismatch, never a match.** A caller that could not resolve the
+// base to a commit knows less than one that could, and two unknowns comparing equal is the same
+// fail-open the ref-name fallback produces.
+function describes_base(stamp: FileMapStamp, base: string | undefined): boolean {
+	return base !== undefined && stamp.base === base
+}
+
+// Every path in either map is one the caller's reader chose, so an empty result is the positive fact
+// "nothing this record covers has changed", never an unread diff.
+//
+// **It says nothing about two maps read against different bases.** It takes the union of the key
+// sets, so a path only one of them covers is reported as changed — a set difference, not an edit.
+// Callers guard that with `describes_base` above (joshuafolkken/kit#1537).
+function changed_since(stamp: FileMapStamp, tree: Record<string, string>): ReadonlyArray<string> {
+	const names = new Set([...Object.keys(stamp.files), ...Object.keys(tree)])
+
+	return [...names]
+		.filter((name) => stamp.files[name] !== tree[name])
+		.toSorted((left, right) => left.localeCompare(right))
+}
+
+interface FileMapStampAccess {
+	stamp_path: () => string
+	// `base` is written by the one record that is acted on rather than merely reported —
+	// joshuafolkken/kit#1328's green-gate reuse. The others omit it and are unaffected.
+	write: (files: Record<string, string>, target?: string, base?: string) => string
+	// Marks an existing record as belonging to a run that finished (joshuafolkken/kit#1164). 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
+	// For a record whose meaning is its existence rather than its contents — the in-flight gate marker
+	// (joshuafolkken/kit#1242). A record nobody removes would go on asserting a gate that ended.
+	remove: (target?: string) => void
+}
+
+// `undefined` rather than a throw or an empty record: "there is no record" and "the record says
+// nothing changed" are the two answers these stamps exist to keep apart, and only the first of them
+// is a reason to act. A planted record would answer the safe-looking way, which is why the read is
+// the guarded one in `stamp-file`.
+function read_at(source: string): FileMapStamp | undefined {
+	const raw = stamp_file.read_stamp_text(source)
+
+	if (raw === undefined) return undefined
+
+	try {
+		return parse_stamp(raw)
+	} catch {
+		return undefined
+	}
+}
+
+// Amending is the whole point, and re-writing would defeat it: `write` stamps a fresh `taken_at` and
+// takes a fresh file map, so calling it again at the end of a run would claim the tree as the run
+// *left* it was the tree the run measured — the record would then vouch for a comparison of that
+// tree against itself, which is the one answer it exists to withhold (joshuafolkken/kit#1164).
+//
+// **It completes only a record this process wrote**, which the `pid` already in the payload is what
+// says. The path is deterministic per checkout, so a second whole-suite run started beside the first
+// overwrites it with its own record — and a completion stamped onto that one would describe a run
+// that is still going, or was killed, as finished: the false `skip` this field exists to prevent,
+// reintroduced from the other side. A foreign record answers `undefined`, which every caller already
+// reads as "no completion", which is `required`.
+//
+// The write is of the *parsed* record, so it carries exactly the fields `parse_stamp` knows. That is
+// deliberate but total-by-assumption: a field added to `write` without a matching entry in
+// `parse_stamp` and `optional_fields` would be dropped by any `complete`, so the two are extended
+// together.
+// **The pid is not the whole of that check either** (joshuafolkken/kit#1245). A record left behind by
+// a run that was killed, whose pid this process was later handed, passes `pid === process.pid` — and
+// stamping it would describe that dead run as finished, which is the false `skip` the field exists to
+// prevent, reached from a third direction. `is_writer_gone` is the added half rather than
+// `is_writer_running`, so a record carrying no start time keeps the behavior it had: the run that
+// wrote it is the one completing it, and refusing there would answer `required` forever on any
+// platform that cannot report a start time.
+function is_own_record(stamp: FileMapStamp): boolean {
+	return stamp.pid === process.pid && !is_writer_gone(stamp)
+}
+
+function complete_at(target: string): string | undefined {
+	const stamp = read_at(target)
+
+	if (stamp === undefined) return undefined
+
+	if (!is_own_record(stamp)) return undefined
+
+	return stamp_file.write_stamp(target, { ...stamp, completed_at: new Date().toISOString() })
+}
+
+// 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 {
+	function resolve(): string {
+		return stamp_file.stamp_path(prefix, root)
+	}
+
+	return {
+		stamp_path: resolve,
+		// `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 since joshuafolkken/kit#1245 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) =>
+			stamp_file.write_stamp(target, {
+				taken_at: new Date().toISOString(),
+				files,
+				...process_identity.own_fields(),
+				base,
+			}),
+		complete: (target = resolve()) => complete_at(target),
+		read: (source = resolve()) => read_at(source),
+		remove: (target = resolve()) => {
+			stamp_file.remove_stamp(target)
+		},
+	}
+}
+
+const file_map_stamp = {
+	changed_since,
+	create,
+	describes_base,
+	is_file_map,
+	is_writer_gone,
+	is_writer_running,
+	parse_stamp,
+	read_at,
+}
+
+export type { FileMapStamp, FileMapStampAccess }
+export { file_map_stamp }