@joshuafolkken/kit 1.872.0

package/scripts/josh/process-identity.ts

@@ -0,0 +1,335 @@
+import { execFileSync, spawnSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { readFileSync, rmSync } from 'node:fs'
+import { createServer, type Server } from 'node:net'
+import path from 'node:path'
+import { PLATFORM_TEMP_ROOT } from './platform-temporary'
+
+// Whether the process a record names is still the one that wrote it (joshuafolkken/kit#1245).
+//
+// **A pid is not a process identity, and every record here was treating it as one.** `process.kill(
+// pid, 0)` answers "alive" for whatever holds that number *now*, so a marker left behind by a gate
+// that was killed starts reading as live again the moment the operating system reissues its pid. For
+// the in-flight gate marker that means `josh review:brief` printing "a gate is running on this tree"
+// about a gate that no longer exists — a verification saying something that is not true, which is the
+// one thing these records exist to prevent.
+//
+// **The identity is the pair (pid, start time).** A reissued pid necessarily started *after* the
+// record was written, so its start time differs and the pair separates the two processes outright.
+// This is the fix rather than a narrowing of the window: a lifetime on the record, the other
+// candidate, only shortens how long a phantom can be believed.
+//
+// **The start time is an opaque token, never a date.** Both sides use the same ordered probes and
+// compare the resulting token for equality; readers never parse it. Linux reads `/proc` directly,
+// other platforms try `ps`, and a sandbox that permits neither uses a process-owned Unix socket.
+// That socket accepts connections only while its writer lives, so a reused pid cannot revive it.
+//
+// **The token is only opaque if it is also stable, which it is not by default.** `ps` renders the
+// start time through the caller's own time zone and locale, so the *same* process prints
+// `Tue Sep  8 09:15:33 2026` in one shell and `Tue Sep  8 02:15:33 2026` in another that exported
+// `TZ=UTC` — and a writer and reader disagreeing about `TZ` would read a live process as a stranger.
+// That failure is worse than the one this module fixes, because it fires on a gate that really is
+// running: `unit-worker-share` would sweep the marker of a live run and put every suite back on the
+// whole machine, and `bench-guard` would clear the caches out from under a running gate. The probe
+// therefore pins `TZ` and `LC_ALL` rather than inheriting them.
+
+// The `ps` fallback uses an absolute path rather than a name resolved through `PATH`, which removes
+// the lookup from the caller's environment and lets the probe run with no inherited environment.
+// Where neither `/proc` nor `ps` is available, the probe answers "cannot tell", a case every caller
+// already handles.
+const PS_COMMAND = '/bin/ps'
+const FORMAT_FLAG = '-o'
+// `lstart` is the process's start time, printed as `Tue Sep  8 08:39:04 2026`. Both implementations
+// these records are read on print it that way — BSD `ps` on macOS, procps-ng on Linux — which is why
+// one command covers both without a platform branch.
+const START_TIME_FORMAT = 'lstart='
+const PID_FLAG = '-p'
+// The two variables that decide how `ps` renders that field, and **the whole environment the probe
+// runs in** — nothing is inherited, so the token depends on the process being asked about and on
+// nothing whatever about who is asking.
+const PROBE_ENVIRONMENT = { TZ: 'UTC', LC_ALL: 'C' }
+// A probe that hung would hang `josh review:brief`, `josh bench` and the unit suite's worker share
+// alike. Failing is harmless here: it answers "cannot tell", which every caller already handles.
+const PROBE_TIMEOUT_MS = 2000
+// `process.kill(pid, 0)` runs every permission check and delivers nothing, so it is the standard
+// liveness probe: it throws `ESRCH` where the process is gone.
+const LIVENESS_SIGNAL = 0
+// Below this a pid is not a process: `0` addresses the caller's own process group and anything
+// negative addresses another group, so a truncated or hand-edited record carrying either would
+// otherwise answer "alive" forever.
+const LOWEST_REAL_PID = 1
+const PROC_START_FIELD_INDEX = 19
+const BEACON_SCHEME = 'socket:'
+const BEACON_SUFFIX = '.sock'
+const BEACON_PREFIX = `josh-process-identity-${String(process.getuid?.() ?? '')}-`
+const BEACON_ID_LENGTH = 36
+const BEACON_ID_PATTERN = /^[\da-f-]+$/u
+const WINDOWS_PLATFORM = 'win32'
+const SOCKET_PROBE_SOURCE =
+	"const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(0));socket.once('error',()=>process.exit(1));socket.setTimeout(1000,()=>process.exit(1));"
+const beacons = new Map<string, Server>()
+const exit_cleanup = { is_registered: false }
+
+interface StartProbes {
+	read_proc_start: (pid: number) => string | undefined
+	read_ps_start: (pid: number) => string | undefined
+}
+
+function is_live_pid(pid: number): boolean {
+	if (pid < LOWEST_REAL_PID) return false
+
+	try {
+		process.kill(pid, LIVENESS_SIGNAL)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+// Linux exposes field 22 as the process start time in clock ticks since boot. The command name in
+// field 2 may itself contain spaces or `)`, so parsing starts after its final closing parenthesis;
+// `state` is then index 0 and `starttime` index 19. A direct file read avoids process enumeration and
+// remains available to a workspace sandbox that refuses `ps`.
+function read_proc_start(pid: number): string | undefined {
+	try {
+		const stat = readFileSync(`/proc/${String(pid)}/stat`, 'utf8')
+		const fields = stat
+			.slice(stat.lastIndexOf(')') + 1)
+			.trim()
+			.split(/\s+/u)
+		const start = fields[PROC_START_FIELD_INDEX]
+
+		return start === undefined ? undefined : `proc:${start}`
+	} catch {
+		return undefined
+	}
+}
+
+function read_ps_start(pid: number): string | undefined {
+	try {
+		const printed = execFileSync(
+			PS_COMMAND,
+			[FORMAT_FLAG, START_TIME_FORMAT, PID_FLAG, String(pid)],
+			{
+				encoding: 'utf8',
+				timeout: PROBE_TIMEOUT_MS,
+				stdio: ['ignore', 'pipe', 'ignore'],
+				env: PROBE_ENVIRONMENT,
+			},
+		).trim()
+
+		return printed.length > 0 ? printed : undefined
+	} catch {
+		return undefined
+	}
+}
+
+const START_PROBES: StartProbes = { read_proc_start, read_ps_start }
+
+function safe_probe(probe: (pid: number) => string | undefined, pid: number): string | undefined {
+	try {
+		return probe(pid)
+	} catch {
+		return undefined
+	}
+}
+
+function read_start(pid: number, probes: StartProbes = START_PROBES): string | undefined {
+	return safe_probe(probes.read_proc_start, pid) ?? safe_probe(probes.read_ps_start, pid)
+}
+
+function close_beacon(token: string): void {
+	const server = beacons.get(token)
+	if (server === undefined) return
+
+	beacons.delete(token)
+	server.close()
+	rmSync(token.slice(BEACON_SCHEME.length), { force: true })
+}
+
+function close_beacons(): void {
+	for (const token of beacons.keys()) close_beacon(token)
+}
+
+function ensure_exit_cleanup(): void {
+	if (exit_cleanup.is_registered) return
+
+	exit_cleanup.is_registered = true
+	process.once('exit', close_beacons)
+}
+
+function ignore_beacon_error(): void {
+	/* an unavailable beacon makes the identity safely unverifiable */
+}
+
+function bind_beacon(target: string): Server {
+	return createServer().on('error', ignore_beacon_error).listen(target)
+}
+
+function try_bind_beacon(bind: (target: string) => Server, target: string): Server | undefined {
+	try {
+		const server = bind(target)
+
+		return server.listening ? server : undefined
+	} catch {
+		return undefined
+	}
+}
+
+function open_beacon(bind: (target: string) => Server = bind_beacon): string | undefined {
+	const target = path.join(PLATFORM_TEMP_ROOT, `${BEACON_PREFIX}${randomUUID()}${BEACON_SUFFIX}`)
+	const token = `${BEACON_SCHEME}${target}`
+	const server = try_bind_beacon(bind, target)
+	if (server === undefined) return undefined
+
+	server.unref()
+	beacons.set(token, server)
+	ensure_exit_cleanup()
+
+	return token
+}
+
+// A Unix-domain listener is the macOS sandbox fallback rather than a weaker pid-only answer. The
+// random path is the generation token and the kernel-held listener is its lifetime: SIGKILL closes
+// it even when no cleanup handler runs, while a stale filesystem entry accepts no connection. A
+// process that later receives the same pid therefore cannot make the old pair live again.
+function resolve_own_start(
+	probes: StartProbes = START_PROBES,
+	platform: NodeJS.Platform = process.platform,
+): string | undefined {
+	const start = read_start(process.pid, probes)
+	if (start !== undefined || platform === WINDOWS_PLATFORM) return start
+
+	return open_beacon()
+}
+
+function is_valid_beacon_name(name: string): boolean {
+	if (!name.startsWith(BEACON_PREFIX) || !name.endsWith(BEACON_SUFFIX)) return false
+
+	const id = name.slice(BEACON_PREFIX.length, -BEACON_SUFFIX.length)
+
+	return id.length === BEACON_ID_LENGTH && BEACON_ID_PATTERN.test(id)
+}
+
+function beacon_target(token: string): string | undefined {
+	if (!token.startsWith(BEACON_SCHEME)) return undefined
+
+	const target = token.slice(BEACON_SCHEME.length)
+	if (path.dirname(target) !== PLATFORM_TEMP_ROOT) return undefined
+
+	return is_valid_beacon_name(path.basename(target)) ? target : undefined
+}
+
+function is_live_beacon(target: string): boolean {
+	return (
+		spawnSync(process.execPath, ['-e', SOCKET_PROBE_SOURCE, target], {
+			stdio: 'ignore',
+			timeout: PROBE_TIMEOUT_MS,
+		}).status === 0
+	)
+}
+
+function has_matching_start(
+	pid: number,
+	recorded_start: string,
+	read: (pid: number) => string | undefined,
+): boolean | undefined {
+	const observed = read(pid)
+
+	return observed === undefined ? undefined : observed === recorded_start
+}
+
+function matches_recorded_start(
+	pid: number,
+	recorded_start: string,
+	read: (pid: number) => string | undefined,
+): boolean | undefined {
+	const target = beacon_target(recorded_start)
+
+	return target === undefined
+		? has_matching_start(pid, recorded_start, read)
+		: is_live_beacon(target)
+}
+
+// Read once and kept: a process's own start time cannot change, and the probe costs a subprocess that
+// every record write would otherwise pay again. A `Map` rather than a nullable variable because
+// `has` distinguishes "not asked yet" from "asked, and the platform could not answer" — the second is
+// a real result, and re-probing on every write would pay the subprocess exactly where it cannot help.
+const own_probe = new Map<number, string | undefined>()
+
+function own_start(): string | undefined {
+	if (!own_probe.has(process.pid)) own_probe.set(process.pid, resolve_own_start())
+
+	return own_probe.get(process.pid)
+}
+
+// The fields a record carries to name its writer, in one place so no caller assembles them itself.
+//
+// **Spread rather than assigned, because `exactOptionalPropertyTypes` makes an explicit `undefined` a
+// different thing from an absent key** — and a platform whose start time cannot be read must leave
+// the key absent, which is exactly what every reader below reads as "cannot tell".
+function own_fields(): { pid: number; process_start?: string } {
+	const start = own_start()
+
+	return { pid: process.pid, ...(start !== undefined && { process_start: start }) }
+}
+
+// **Three answers, because the third one is real and the two callers resolve it in opposite
+// directions.** `true` is "the writer is still running", `false` is "it is not", and `undefined` is
+// "this platform cannot tell" — a pid that is alive paired with a start time nobody could read, on
+// either side of the record.
+//
+// Collapsing `undefined` into either boolean here would be a decision taken in the wrong place. What
+// being wrong costs differs per caller: the in-flight gate marker's readers pay a redundant unit run
+// for a false negative, so they take `=== true`; the unit-suite worker share pays a wider share of
+// the machine for a false negative and an oversubscribed machine for a false positive, so it takes
+// `!== false`. Each one chooses the answer that costs wall time rather than correctness.
+//
+// **A record written before this field existed lands on `undefined` rather than `true`**, the same
+// direction `describes_base` takes for a missing base: a reader that knows less than the writer did
+// must never come out ahead of one that knows the same.
+function is_same_process(
+	pid: number | undefined,
+	recorded_start: string | undefined,
+	read: (pid: number) => string | undefined = read_start,
+): boolean | undefined {
+	if (pid === undefined || !is_live_pid(pid)) return false
+	if (recorded_start === undefined) return undefined
+
+	return matches_recorded_start(pid, recorded_start, read)
+}
+
+// **Whether a record is the caller's own, which is a different question from whether its writer is
+// alive** (joshuafolkken/kit#1727). `is_same_process` asks about the recorded process; this asks
+// whether that process *is this one*. A supervisor that has been replaced reads its successor's
+// record as perfectly live, so liveness alone can never tell a hand-over from an ordinary pass — and
+// a writer deciding by liveness overwrites whatever it finds.
+//
+// **Compared against `own_fields()`, so the two can never disagree about what identity means.** The
+// pair a record carries is written there and read here, which is why this lives beside it rather
+// than in each record's own module.
+//
+// **A start time neither side can read leaves the pid as the whole comparison, and that is the
+// correct fallback rather than a gap.** Where the platform answers for nobody, both sides are
+// `undefined` and equal; where it answers for one and not the other, they differ and the record is
+// treated as someone else's — the safe direction, since refusing to write a record that is in fact
+// this process's own costs one supervisor pass, and writing over another's costs the run.
+function is_own_process(pid: number | undefined, recorded_start: string | undefined): boolean {
+	return pid === process.pid && recorded_start === own_start()
+}
+
+const process_identity = {
+	close_beacon,
+	is_live_pid,
+	is_own_process,
+	is_same_process,
+	open_beacon,
+	own_fields,
+	own_start,
+	read_start,
+	resolve_own_start,
+}
+
+export { process_identity }
+export type { StartProbes }

package/scripts/josh/session-language-cli.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from './josh-environment-file'
+import { session_language, type Resolution } from './session-language'
+
+// `josh session:lang` — say, on stdout, which language this session writes in, so a
+// `SessionStart` / `UserPromptSubmit` hook injects the resolved value into context every turn
+// (joshuafolkken/kit#1903). Before this, `JOSH_SESSION_LANG` lived only in `.env` — a personal,
+// non-committed file the harness never loads into the process environment — so the value was
+// invisible unless the agent read the file itself, and a one-word prompt like `diag` had nothing to
+// infer a language from and drifted to the surrounding English.
+//
+// **The `.env` read reuses the one loader** (`josh_environment_file.load_environment_file`) rather
+// than a second parser, and keeps node's precedence: a value already in the process environment wins
+// over the file's. Unset, empty and no-`.env` all resolve to `ja`, because a worktree without a
+// `.env`, a cloud session and a consumer repository are exactly where the drift recurs.
+//
+// The line itself is a script-fixed string, so it stays English by the same rule that pins the
+// Telegram header labels and the `--notify-message` default (`CLAUDE.md` → "Output language").
+
+const { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang } = session_language
+const ENGLISH_OPT_IN_LANG = 'en'
+const SCOPE_NOTE =
+	'write session dialogue, AskUserQuestion labels/descriptions and artifact prose (Issue bodies, comments, Telegram) in this language. English stays only for Issue/PR titles, code comments/test titles/commit messages, and script-fixed strings.'
+
+// The file load happens in `main`, on the command path only; the resolver reads the environment.
+function format_line(resolution: Resolution): string {
+	const suffix = resolution.is_default
+		? ` (default; set ${ENV_KEY}=${ENGLISH_OPT_IN_LANG} for English)`
+		: ''
+
+	return `Session language (${ENV_KEY}): ${resolution.lang}${suffix} — ${SCOPE_NOTE}`
+}
+
+function main(): void {
+	josh_environment_file.load_environment_file()
+	console.info(format_line(resolve_session_lang()))
+}
+
+const session_language_cli = {
+	DEFAULT_SESSION_LANG,
+	ENV_KEY,
+	format_line,
+	main,
+	resolve_session_lang,
+	SCOPE_NOTE,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+
+export { session_language_cli }

package/scripts/josh/session-language.ts

@@ -0,0 +1,30 @@
+// The session language, resolved from the process environment alone — the one resolver both
+// `josh session:lang` and the Stop hook read. It lives apart from `session-language-cli.ts` because
+// that file is its own hook bundle entry: an entry imported by another entry is moved into a shared
+// esbuild chunk, so its `import.meta.url` stops matching `argv[1]` and `dist/hooks/session-lang.js`
+// prints nothing (`build-hooks.ts` → "`splitting: true` is load-bearing").
+//
+// Unset and empty resolve to `ja`, because a worktree without a `.env`, a cloud session and a
+// consumer repository are exactly where the drift recurs (joshuafolkken/kit#1903).
+
+const ENV_KEY = 'JOSH_SESSION_LANG'
+const DEFAULT_SESSION_LANG = 'ja'
+
+interface Resolution {
+	lang: string
+	is_default: boolean
+}
+
+// Reads the process environment alone, so a unit test sets `process.env[ENV_KEY]` and never touches a
+// real `.env`. Loading the file is the caller's job.
+function resolve_session_lang(): Resolution {
+	const value = process.env[ENV_KEY]?.trim()
+	if (value) return { lang: value, is_default: false }
+
+	return { lang: DEFAULT_SESSION_LANG, is_default: true }
+}
+
+const session_language = { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang }
+
+export type { Resolution }
+export { session_language }

package/scripts/josh/stamp-file.ts

@@ -0,0 +1,194 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { PACKAGE_DIR } from '#scripts/init/init-paths'
+import { PLATFORM_TEMP_ROOT } from './platform-temporary'
+
+// A small record one josh command writes and another reads, kept per checkout in the temp directory.
+//
+// Extracted from `scripts/eval/eval-stamp.ts` when `josh latest:scope` needed the same handoff
+// (joshuafolkken/kit#1215). The mechanics below are not boilerplate — the symlink defense on the
+// write, the ownership check on the read, and the deterministic per-checkout path are each load
+// bearing — so a second copy of them is the clone `CLAUDE.md` prohibits. What differs between the
+// two records is their *payload* and the question asked of it, and that is all either module keeps.
+
+const HASH_ALGORITHM = 'sha256'
+const STAMP_SUFFIX = '.json'
+// Enough of the package path's digest to keep one checkout's record apart from another's in a shared
+// temp directory, and short enough to read in a printed path.
+const STAMP_KEY_LENGTH = 16
+// The path is deterministic — both commands have to reach it without being told where it is — and it
+// sits in a directory every account on the host may write to. A mode alone does not make that safe:
+// it applies on creation, and a plain write follows a symlink someone else put there.
+const STAMP_FILE_MODE = 0o600
+// Create-exclusively. Refusing an existing path is what keeps a write from being redirected into a
+// file the running user owns; the unlink below is what keeps the normal rewrite working.
+const STAMP_WRITE_FLAG = 'wx'
+// The same flag under the name that says what `create_stamp` uses it for: there the exclusivity is
+// the contract rather than a defense, because no unlink precedes it.
+const STAMP_CREATE_FLAG = STAMP_WRITE_FLAG
+const EXISTS_ERROR_CODE = 'EEXIST'
+const ACCOUNT_KEY_SEPARATOR = ':'
+
+// Bytes rather than a decoded string. UTF-8 decoding is lossy — every invalid sequence collapses to
+// the same replacement character — so hashing the decoded form would let two different files agree,
+// and the checks built on this exist precisely to notice that they do not.
+function digest(content: Buffer | string): string {
+	return createHash(HASH_ALGORITHM).update(content).digest('hex')
+}
+
+// **The account is part of the key, because `/tmp` is shared between accounts where `TMPDIR` was not.**
+// A root such as a globally installed `PACKAGE_DIR` is the same path for every account on the host, so
+// without this two accounts would name one file — and the second one's unlink of a file the first owns
+// fails on the sticky directory, ending its command. Folding the account in keeps accidental
+// collisions apart; a hostile local account can still pre-create a predictable name, which fails the
+// write rather than redirecting it (joshuafolkken/kit#1909). Windows has no `getuid` and keeps the
+// per-user `os.tmpdir()`, so it contributes an empty account.
+function account_key(): string {
+	return String(process.getuid?.() ?? '')
+}
+
+// The temp directory rather than the repository: this is a handoff between two commands of one
+// loop, and a file in the tree would have to be gitignored in kit and in every consumer `josh sync`
+// reaches — a distributed ignore entry bought for something nobody is meant to keep.
+//
+// **`PLATFORM_TEMP_ROOT` rather than `os.tmpdir()`, because the two commands need not share a
+// `TMPDIR`.** A record this module keeps is read by a *different* process than wrote it — the second
+// half of a handoff — and `os.tmpdir()` honors each process's own `TMPDIR`, so a session a
+// `run:wake` or a `lane:dispatch` launched resolves a different directory than its launcher and the
+// handoff is lost (joshuafolkken/kit#1909). The keyed digest below already keeps one checkout apart
+// from another; the root is what has to stop moving per process, which `platform-temporary.ts` pins.
+//
+// **`root` is what the record is keyed to, and the right answer differs per caller.** `PACKAGE_DIR`
+// is the default because `josh eval` measures the kit package's own files. A record about the
+// *project* must key on `PROJECT_ROOT` instead: a globally installed `josh` has one `PACKAGE_DIR`
+// for every project on the machine, so keying on it would let a run in one project answer for
+// another (joshuafolkken/kit#1215).
+//
+// **`suffix` is what the file is, not decoration.** Every record here was JSON until `josh gate`
+// needed to keep another tool's output verbatim (joshuafolkken/kit#1227), and a log named `.json`
+// tells every reader — a person, an editor, a `less` — that it is something it is not.
+function stamp_path(
+	prefix: string,
+	root: string = PACKAGE_DIR,
+	suffix: string = STAMP_SUFFIX,
+): string {
+	const key = digest(`${account_key()}${ACCOUNT_KEY_SEPARATOR}${root}`).slice(0, STAMP_KEY_LENGTH)
+
+	return path.join(PLATFORM_TEMP_ROOT, `${prefix}${key}${suffix}`)
+}
+
+// **The write unlinks first, then creates exclusively.** `rmSync` removes a symlink rather than
+// following it, and `wx` refuses an existing path outright, so someone who re-creates the path in
+// the window between the two can make this write *fail* — never make it land somewhere else. A
+// failed write leaves no record, and no record is the safe answer for every reader here. On a sticky
+// temp directory a file another account owns cannot be unlinked at all, so that case fails here too
+// rather than being silently trusted later.
+function write_exclusively(target: string, content: string): string {
+	rmSync(target, { force: true })
+	writeFileSync(target, content, { flag: STAMP_WRITE_FLAG, mode: STAMP_FILE_MODE })
+
+	return target
+}
+
+function write_stamp(target: string, payload: unknown): string {
+	return write_exclusively(target, JSON.stringify(payload))
+}
+
+// Mutable coordination state cannot disappear between an unlink and its replacement: a reader that
+// mistakes that gap for "no child" can start the same generation twice. The temporary file lives
+// beside the target, uses the same exclusive/symlink-safe create, and rename publishes it atomically.
+function replace_stamp(target: string, payload: unknown): string {
+	const temporary = `${target}.${String(process.pid)}.${randomUUID()}`
+
+	try {
+		writeFileSync(temporary, JSON.stringify(payload), {
+			flag: STAMP_CREATE_FLAG,
+			mode: STAMP_FILE_MODE,
+		})
+		renameSync(temporary, target)
+
+		return target
+	} finally {
+		rmSync(temporary, { force: true })
+	}
+}
+
+// The same write for a payload that is already text. `josh gate`'s log is another tool's output read
+// by a person or by an agent's `tail` (joshuafolkken/kit#1227), and JSON-encoding it would put `\n`
+// escapes between the reader and the thing they came to read. **It shares the body above rather than
+// repeating it**: the unlink-then-create-exclusively pair is the symlink defense, and a second copy
+// of it is the clone `CLAUDE.md` prohibits.
+function write_text_stamp(target: string, text: string): string {
+	return write_exclusively(target, text)
+}
+
+// `write_stamp` for a record whose *absence* is what the caller checked, and which two processes may
+// therefore try to create at once (joshuafolkken/kit#1091). It does **not** unlink first, so `wx` is
+// doing the job it exists for: the second writer loses and is told so, rather than both being told
+// they won. `false` is that loss and never an error, because "someone else got here first" is an
+// answer; anything else still throws, since a record that could not be written for another reason
+// must not read as a record somebody else holds.
+function create_stamp(target: string, payload: unknown): boolean {
+	try {
+		writeFileSync(target, JSON.stringify(payload), {
+			flag: STAMP_CREATE_FLAG,
+			mode: STAMP_FILE_MODE,
+		})
+
+		return true
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === EXISTS_ERROR_CODE) return false
+
+		throw error
+	}
+}
+
+// The counterpart to `write_stamp`, for a record that means something only while it exists — the
+// in-flight gate marker `josh gate` clears when its checks finish (joshuafolkken/kit#1242). `force`
+// makes an absent path a success, because "there is no record" is the state the caller wanted; and
+// `rmSync` removes a symlink rather than following it, the same reason the write unlinks first.
+function remove_stamp(target: string): void {
+	rmSync(target, { force: true })
+}
+
+// The read side of the write's problem. A record is trusted to say something is still current, so a
+// planted one suppresses the work the check exists to force. `lstatSync` reports the link rather than
+// what it points at, and it throws where the path is simply absent — both of which are "no record".
+// `getuid` is missing on Windows, where a shared temp directory is not the same hazard; the check
+// reduces to "is it a regular file" there.
+function is_own_regular_file(source: string): boolean {
+	const stats = lstatSync(source)
+
+	if (!stats.isFile()) return false
+
+	const uid = process.getuid?.()
+
+	return uid === undefined || stats.uid === uid
+}
+
+// `undefined` rather than a throw or an empty string: "there is no record" and "the record says
+// nothing has to be done" are two different answers, and only the first of them is a reason to act.
+function read_stamp_text(source: string): string | undefined {
+	try {
+		if (!is_own_regular_file(source)) return undefined
+
+		return readFileSync(source, 'utf8')
+	} catch {
+		return undefined
+	}
+}
+
+const stamp_file = {
+	create_stamp,
+	digest,
+	is_own_regular_file,
+	read_stamp_text,
+	replace_stamp,
+	remove_stamp,
+	stamp_path,
+	write_stamp,
+	write_text_stamp,
+}
+
+export { stamp_file }