@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/josh/josh-verdict.ts

@@ -1,14 +1,13 @@
 import { status_icons } from '#scripts/lib/status-icons'
 
-// A josh command's own overall verdict, and the one place its line is written (joshuafolkken/kit#1374).
+// A josh command's own overall verdict, and the one place its line is written.
 //
-// `status-icons.ts` single-sourced the *character* a failure line opens with, which was enough while
-// the only thing reading it was `time-reported-failure.ts` asking "did this call print a failure?".
-// It is not enough for a command that **forwards another tool's output**. `josh gate` prints the body
-// of a step that passed with warnings or skipped (joshuafolkken/kit#1328), and that body is written by
+// `status-icons.ts` single-sources the *character* a failure line opens with, which is not enough for
+// a command that **forwards another tool's output**. `josh gate` prints the body
+// of a step that passed with warnings or skipped, and that body is written by
 // eslint, svelte-check, vitest or cspell — this repository owns none of those formats. One of them
 // opening a line with the failure icon makes a *green* gate read as a failed call, and the re-run that
-// follows it is then charged as rework: the very figure joshuafolkken/kit#1361 exists to make honest.
+// follows it is then charged as rework, which the rework figure exists to keep honest.
 //
 // **The anchor is the command's own verdict, not the shape of every line it prints.** A command that
 // forwards other tools' output states its own result in one line, and that line outranks the body it
@@ -17,21 +16,20 @@ import { status_icons } from '#scripts/lib/status-icons'
 // each consumer's gate with inherited stdio — so a `passed` verdict speaks for the lines in front of
 // it and the reading resumes after it (`time-reported-failure.ts` → `lines_after_last_pass`).
 //
-// **Why not enumerate every josh failure-line shape.** That is the candidate joshuafolkken/kit#1374
-// names as most likely, and rejects for the reason it names: the gate's step line is
+// **Why not enumerate every josh failure-line shape.** The gate's step line is
 // `✗ <label> (pnpm <cmd>) <n>s`, `josh health`'s is `  ✗ <label>` and `josh propagate`'s is
 // `  ✗ <repo>  <reason>`, so a pattern list tight enough to exclude a third-party warning is a list of
 // per-command patterns — and the next josh command to print a failure line is silently not counted,
 // which is the detector going quiet without failing. Reading the verdict instead leaves every other
 // josh command exactly as it was: no verdict line, so nothing changes for them.
 //
-// **What it degrades to is today's behavior, not silence.** A body the harness truncated past the
+// **What it degrades to is the bare-icon reading, not silence.** A body the harness truncated past the
 // verdict line falls back to the bare-icon reading, so the figure stays a floor. The gate's verdict is
 // its **last** line, which is what survives the `2>&1 | tail -40` agents actually type
 // (`prompts/collaboration-workflow/output-bounds.md`), so the fallback is the rare case rather than
 // the common one.
 //
-// **The opening line is here for the same reason the verdict is** (joshuafolkken/kit#1379). A verdict
+// **The opening line is here for the same reason the verdict is**. A verdict
 // says where the gate's output *ended*; nothing said where it began, so a green verdict silenced every
 // failure mark printed before it — including one written by a command that had already finished. The
 // gate's plan line is what says "the gate starts here", and it is single-sourced for the reason the
@@ -41,8 +39,7 @@ const { FAIL_ICON, PASS_ICON } = status_icons
 const GATE_SUBJECT = 'verification gate'
 
 // The prefixes are what the detector matches **and** what the printer builds its line from, so a
-// reworded verdict moves both ends at once — the property joshuafolkken/kit#1361 gave the icon,
-// applied to the line. Splitting them into a printed string and a matched string is exactly the drift
+// reworded verdict moves both ends at once — the property the icon has, applied to the line. Splitting them into a printed string and a matched string is exactly the drift
 // this module exists to prevent.
 const GATE_PASSED_PREFIX = `${PASS_ICON} ${GATE_SUBJECT} passed`
 const GATE_FAILED_PREFIX = `${FAIL_ICON} ${GATE_SUBJECT} failed`

package/scripts/josh/josh.ts

@@ -24,8 +24,8 @@ function handle_unknown(cmd: string): never {
 	process.exit(1)
 }
 
-// `process.exit` truncates a piped stdout at its buffer size, and since joshuafolkken/kit#1342 the
-// output at risk is the script's own — `scripts/gate/verification-gate.ts` writes its per-check blocks
+// `process.exit` truncates a piped stdout at its buffer size, and the output at risk is the script's
+// own — `scripts/gate/verification-gate.ts` writes its per-check blocks
 // and its failure summary through this process, and sets `process.exitCode` rather than exiting for
 // exactly that reason. Recording the code and letting node exit when the loop drains keeps every
 // byte, and it leaves the last word with a script that finishes work after module evaluation
@@ -36,7 +36,7 @@ function record_exit_code(exit_code: number): void {
 }
 
 // `run_command` answers with a number for a shell command and a promise for a script it runs in
-// this same process (joshuafolkken/kit#1342); `await` covers both, and the argv slice is taken
+// this same process; `await` covers both, and the argv slice is taken
 // before it because the in-process branch replaces `process.argv` with the script's own.
 async function main(): Promise<void> {
 	const cmd = process.argv[ARGV_OFFSET]

package/scripts/josh/kit-only.ts

@@ -2,8 +2,8 @@ import { COMMAND_MAP } from './josh-command-map'
 import type { CommandEntry } from './josh-command-types'
 
 // The commands marked `is_kit_only` in the map only make sense inside the kit repository itself, so a
-// consumer never sees them in `josh --help` and is refused with guidance when it runs one
-// (joshuafolkken/kit#1988). The flag lives on the entry; everything a reader needs to act on it is
+// consumer never sees them in `josh --help` and is refused with guidance when it runs one.
+// The flag lives on the entry; everything a reader needs to act on it is
 // here, so the help filter, the dispatch guard and the distributed-doc test read one definition.
 
 // Where a consumer is told to go. A script-emitted string, so it stays English (`CLAUDE.md` →

package/scripts/josh/path-decision.ts

@@ -1,6 +1,6 @@
 import { changed_paths } from '#scripts/git/changed-paths'
 
-// The shape both path-decided commands share (joshuafolkken/kit#907).
+// The shape both path-decided commands share.
 //
 // `josh review:level` and `josh review:round2` ask different questions of the same tree, and they answer
 // the same way: read the changed paths, decide from them alone, print the answer on stdout and the reason on
@@ -29,8 +29,8 @@ interface DecisionCommand<Answer extends string> {
 	explain: (paths: ReadonlyArray<string>, answer: Answer) => string
 }
 
-// The flag contract every mechanically-decided command shares — the two here and `josh review:round2`
-// (joshuafolkken/kit#1433). An argument that is not a known flag makes the whole invocation
+// The flag contract every mechanically-decided command shares — the two here and `josh review:round2`.
+// An argument that is not a known flag makes the whole invocation
 // unreadable, and an unreadable invocation is never answered with a default. Shared because the
 // *direction* is the load-bearing part rather than the `some` call: a command that guessed would
 // hand the caller the answer they were reaching for instead of the one their tree supports, and two

package/scripts/josh/platform-temporary.ts

@@ -5,9 +5,9 @@ import { tmpdir } from 'node:os'
 // "the temp directory"**: it honors `TMPDIR`, which on macOS names a per-user `/var/folders/…/T`, so
 // two processes with different `TMPDIR` values resolve two different places. A record one josh
 // command writes for another to read then lands where the reader never looks — the transcript a
-// harness wrote under `/tmp` that `os.tmpdir()` could not name (joshuafolkken/kit#1501), and the run
-// record a `backlogrun` handed off that the `run:wake`-launched session began again from nothing
-// (joshuafolkken/kit#1909). A cross-process handoff has to key on a root neither end's own `TMPDIR`
+// harness wrote under `/tmp` that `os.tmpdir()` could not name, and the run
+// record a `backlogrun` handed off that the `run:wake`-launched session began again from nothing.
+// A cross-process handoff has to key on a root neither end's own `TMPDIR`
 // can move, and that is what this pins.
 //
 // **It is decided by platform rather than written as a bare `/tmp`, because a POSIX literal is not
@@ -42,12 +42,14 @@ function resolve_temporary_root(
 	return can_write(POSIX_TEMP_ROOT) ? POSIX_TEMP_ROOT : tmpdir()
 }
 
-// **An explicit root wins, and the unit suite is who sets one** (joshuafolkken/kit#2494). Every
+// **An explicit root wins, and the unit suite is who sets one**. Every
 // record keyed here is shared by the whole host, so a unit test that drove a writer for real wrote
 // into the live run's records — progress lines for issues the run never touched, relayed to the
 // session watching it. The network guard's `arm` points this at a directory of its own before any
 // worker forks, so every process of one test run shares a root no real run reads, and `disarm`
-// removes it with the rest of the guard.
+// removes it with the rest of the guard. Live evidence of `run:carry` sets it for the same
+// reason: the run's state records are keyed here too, and evidence taken against the default root
+// once ended the record of the run that was actually going.
 const TEMP_ROOT_KEY = 'JOSH_TEMP_ROOT'
 
 function temporary_root(override: string | undefined, platform: string): string {

package/scripts/josh/process-identity.ts

@@ -6,7 +6,7 @@ import path from 'node:path'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 
-// Whether the process a record names is still the one that wrote it (joshuafolkken/kit#1245).
+// Whether the process a record names is still the one that wrote it.
 //
 // **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
@@ -63,8 +63,14 @@ 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));"
+// The probe's three exits. Only a refused connection or a missing socket
+// proves the listener gone; any other error, the probe's own socket timeout, and a probe killed by
+// `PROBE_TIMEOUT_MS` or a signal leave the answer unknown, since a loaded machine produces all three
+// for a holder that is still running.
+const BEACON_LIVE_STATUS = 0
+const BEACON_UNKNOWN_STATUS = 1
+const BEACON_GONE_STATUS = 2
+const SOCKET_PROBE_SOURCE = `const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(${String(BEACON_LIVE_STATUS)}));socket.once('error',(error)=>process.exit(['ECONNREFUSED','ENOENT'].includes(error.code)?${String(BEACON_GONE_STATUS)}:${String(BEACON_UNKNOWN_STATUS)}));socket.setTimeout(1000,()=>process.exit(${String(BEACON_UNKNOWN_STATUS)}));`
 const beacons = new Map<string, Server>()
 const exit_cleanup = { is_registered: false }
 
@@ -219,15 +225,26 @@ function beacon_target(token: string): string | undefined {
 	return is_valid_beacon_name(path.basename(target)) ? target : undefined
 }
 
-function is_live_beacon(target: string): boolean {
+// No status is a probe killed by its timeout or a signal — unknown, the same as its own timeout.
+function run_socket_probe(target: string): number | undefined {
 	return (
 		spawnSync(process.execPath, ['-e', SOCKET_PROBE_SOURCE, target], {
 			stdio: 'ignore',
 			timeout: PROBE_TIMEOUT_MS,
-		}).status === 0
+		}).status ?? undefined
 	)
 }
 
+function is_live_beacon(
+	target: string,
+	probe: (target: string) => number | undefined = run_socket_probe,
+): boolean | undefined {
+	const status = probe(target)
+	if (status === BEACON_LIVE_STATUS) return true
+
+	return status === BEACON_GONE_STATUS ? false : undefined
+}
+
 function has_matching_start(
 	pid: number,
 	recorded_start: string,
@@ -299,7 +316,7 @@ function is_same_process(
 }
 
 // **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
+// alive**. `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.
@@ -319,6 +336,7 @@ function is_own_process(pid: number | undefined, recorded_start: string | undefi
 
 const process_identity = {
 	close_beacon,
+	is_live_beacon,
 	is_live_pid,
 	is_own_process,
 	is_same_process,

package/scripts/josh/process-owner.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod'
 
-// The pair a record names its writing process by, as `process_identity` reads it back
-// (joshuafolkken/kit#1245): the pid, and the opaque start token `process_identity.own_fields` wrote
+// The pair a record names its writing process by, as `process_identity` reads it back:
+// the pid, and the opaque start token `process_identity.own_fields` wrote
 // beside it. Every lock, marker and ledger entry that later asks `is_same_process` carries this pair,
-// so its shape is declared once here and each record extends it (joshuafolkken/kit#2986).
+// so its shape is declared once here and each record extends it.
 //
-// `process_start` is optional because a record written before joshuafolkken/kit#1245, or on a platform
+// `process_start` is optional because an older record, or one written on a platform
 // whose start time cannot be read, carries only the pid — `is_same_process` has an answer of its own
 // for that case rather than the record being rejected.
 const process_owner_schema = z.object({ pid: z.number(), process_start: z.string().optional() })

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

@@ -1,11 +1,13 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { backlogrun_launch } from '#scripts/backlog/backlogrun-launch'
+import { run_carry } from '#scripts/run/carry/run-carry'
 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,
+// `SessionStart` / `UserPromptSubmit` hook injects the resolved value into context every turn.
+// 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.
@@ -18,32 +20,72 @@ import { session_language, type Resolution } from './session-language'
 // 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").
 
+//
+// **The same hook carries the board rule while a `backlogrun` is live.** The rule
+// that a progress question is answered with `run:board --chat` is read only by the session driving a
+// run, so a session asked from the side never met it. The prompt is the one moment every session
+// shares, and the line is gated on the run being live, so a repository with no run pays nothing for
+// it. Live is `backlogrun_launch.is_running`'s answer, not a second reading of the records.
+
 const { DEFAULT_SESSION_LANG, ENV_KEY, resolve_session_lang } = session_language
-const ENGLISH_OPT_IN_LANG = 'en'
+
+const BOARD_LINE =
+	'A backlogrun is live here: answer a progress question with `pnpm josh run:board --chat`, verbatim in one code block.'
+
+interface LivePorts {
+	// The common git directory the run's records are keyed on; `undefined` outside a repository.
+	repository_directory: () => Promise<string | undefined>
+	is_running: (git_directory: string) => boolean
+}
+
+const LIVE_PORTS: LivePorts = {
+	repository_directory: run_carry.repository_directory,
+	is_running: backlogrun_launch.is_running,
+}
 
 // The file load happens in `main`, on the command path only; the resolver reads the environment.
 // The line carries the value alone: what the language covers is `CLAUDE.md` → "Output language",
-// already in context every turn, so repeating it here only spent context on each prompt.
+// already in context every turn, so repeating it here only spent context on each prompt. The default
+// prints nothing — that resident line already names `ja`.
 function format_line(resolution: Resolution): string {
-	const suffix = resolution.is_default
-		? ` (default; set ${ENV_KEY}=${ENGLISH_OPT_IN_LANG} for English)`
-		: ''
+	if (resolution.is_default) return ''
 
-	return `Session language (${ENV_KEY}): ${resolution.lang}${suffix}`
+	return `Session language (${ENV_KEY}): ${resolution.lang}`
 }
 
-function main(): void {
+// A throw is answered `false`: a hook that failed here would cost the prompt its language line too.
+async function is_run_live(ports: LivePorts = LIVE_PORTS): Promise<boolean> {
+	try {
+		const git_directory = await ports.repository_directory()
+
+		return git_directory !== undefined && ports.is_running(git_directory)
+	} catch {
+		return false
+	}
+}
+
+function prompt_lines(resolution: Resolution, is_live: boolean): Array<string> {
+	return [format_line(resolution), is_live ? BOARD_LINE : ''].filter((line) => line !== '')
+}
+
+async function main(): Promise<void> {
 	josh_environment_file.load_environment_file()
-	console.info(format_line(resolve_session_lang()))
+	const lines = prompt_lines(resolve_session_lang(), await is_run_live())
+
+	for (const line of lines) console.info(line)
 }
 
 const session_language_cli = {
+	BOARD_LINE,
 	DEFAULT_SESSION_LANG,
 	ENV_KEY,
 	format_line,
+	is_run_live,
+	prompt_lines,
 	resolve_session_lang,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main()
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main()
 
+export type { LivePorts }
 export { session_language_cli }

package/scripts/josh/session-language.ts

@@ -5,7 +5,7 @@
 // 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).
+// consumer repository are exactly where the drift recurs.
 
 const ENV_KEY = 'JOSH_SESSION_LANG'
 const DEFAULT_SESSION_LANG = 'ja'

package/scripts/josh/stamp-file.ts

@@ -6,8 +6,8 @@ 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
+// Extracted from `scripts/eval/eval-stamp.ts` when `josh latest:scope` needed the same handoff.
+// 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.
@@ -42,7 +42,7 @@ function digest(content: Buffer | string): string {
 // 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
+// write rather than redirecting it. 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?.() ?? '')
@@ -56,17 +56,17 @@ function account_key(): string {
 // `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
+// handoff is lost. 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).
+// another.
 //
 // **`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`
+// needed to keep another tool's output verbatim, 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,
@@ -95,17 +95,46 @@ function write_stamp(target: string, payload: unknown): string {
 	return write_exclusively(target, JSON.stringify(payload))
 }
 
+// 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
+}
+
+// A regular file at `target` that another account owns. An absent path or a symlink is not one: the
+// replace below swaps either out without following it.
+function is_foreign_file(target: string): boolean {
+	try {
+		return lstatSync(target).isFile() && !is_own_regular_file(target)
+	} catch {
+		return false
+	}
+}
+
 // 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 {
+// `rename` replaces the path itself rather than following a symlink planted there, so the write still
+// never lands somewhere else; a regular file another account owns is refused before it is replaced,
+// the same answer the unlink gives on a sticky temp directory.
+function replace_text_stamp(target: string, text: string): string {
+	if (is_foreign_file(target)) {
+		throw new Error(`refusing to replace another account's file: ${target}`)
+	}
+
 	const temporary = `${target}.${String(process.pid)}.${randomUUID()}`
 
 	try {
-		writeFileSync(temporary, JSON.stringify(payload), {
-			flag: STAMP_CREATE_FLAG,
-			mode: STAMP_FILE_MODE,
-		})
+		writeFileSync(temporary, text, { flag: STAMP_CREATE_FLAG, mode: STAMP_FILE_MODE })
 		renameSync(temporary, target)
 
 		return target
@@ -114,8 +143,12 @@ function replace_stamp(target: string, payload: unknown): string {
 	}
 }
 
+function replace_stamp(target: string, payload: unknown): string {
+	return replace_text_stamp(target, JSON.stringify(payload))
+}
+
 // 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`
+// by a person or by an agent's `tail`, 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.
@@ -124,7 +157,7 @@ function write_text_stamp(target: string, text: string): string {
 }
 
 // `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
+// therefore try to create at once. 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
@@ -145,28 +178,13 @@ function create_stamp(target: string, payload: unknown): boolean {
 }
 
 // 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`
+// in-flight gate marker `josh gate` clears when its checks finish. `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 {
@@ -185,6 +203,7 @@ const stamp_file = {
 	is_own_regular_file,
 	read_stamp_text,
 	replace_stamp,
+	replace_text_stamp,
 	remove_stamp,
 	stamp_path,
 	write_stamp,

package/scripts/josh/stamp-record.ts

@@ -0,0 +1,57 @@
+// What every aged record `stamp-file.ts` keeps is asked on the read: is it there, can it be read, and
+// has its bound run out.
+//
+// `run-carry.ts`, `run-cut.ts` and `run-hold.ts` each carried the expiry below, and the first two the
+// classification as well. What an unparsable or a future time means is one decision, so it is made
+// here once; what differs between the records is their payload, their timestamp field and their bound,
+// and that is all a `StampRecordSpec` names.
+
+interface StampRecordSpec<T> {
+	parse: (raw: string) => T | undefined
+	timestamp_of: (record: T) => string
+	max_age_ms: number
+}
+
+type StampRecordRead<T> =
+	| { kind: 'none' }
+	| { kind: 'carried'; record: T }
+	| { kind: 'expired'; record: T }
+	| { kind: 'unreadable' }
+
+const NONE_READ = { kind: 'none' } as const
+const UNREADABLE_READ = { kind: 'unreadable' } as const
+
+// **A time that is not a date is older than any bound, not current.** It passes a schema — it is a
+// string — so reading it as current would leave a record nothing can ever expire, which is the one
+// state a bound exists to make impossible. A time ahead of `now` (a skewed clock) has a negative age
+// and is not older; the bound is exclusive, so a record exactly at it is still current.
+function is_older_than(iso: string, max_age_ms: number, now: Date): boolean {
+	const at = Date.parse(iso)
+
+	if (Number.isNaN(at)) return true
+
+	return now.getTime() - at > max_age_ms
+}
+
+// **A record that cannot be read is `unreadable`, never `none`.** Absent is none; present and
+// unparseable is the state a guard must not fall open on.
+function classify<T>(
+	raw: string | undefined,
+	spec: StampRecordSpec<T>,
+	now: Date,
+): StampRecordRead<T> {
+	if (raw === undefined) return NONE_READ
+
+	const record = spec.parse(raw)
+
+	if (record === undefined) return UNREADABLE_READ
+
+	const is_expired = is_older_than(spec.timestamp_of(record), spec.max_age_ms, now)
+
+	return { kind: is_expired ? 'expired' : 'carried', record }
+}
+
+const stamp_record = { classify, is_older_than }
+
+export { stamp_record }
+export type { StampRecordRead, StampRecordSpec }