@joshuafolkken/kit 1.872.0

package/scripts/run/run-hold-cli.ts

@@ -0,0 +1,310 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { run_hold, type HoldRead, type RunHold } from './run-hold'
+import { run_preflight, type PreflightDecision } from './run-preflight'
+
+// `josh run:hold [<N>]` and `josh run:release [<N> | --force]` — the working-tree guard the typed
+// entry points ask before they start (joshuafolkken/kit#1091).
+//
+// **A numbered claim asks the preflight question first** (joshuafolkken/kit#1965). `run:preflight`
+// was a separate command a run had to ask before this one; the two-step "preflight, then hold" was
+// one call too many, so the claim now runs the check itself and hands back a hold only on a `clean`
+// tree. A `reclaim` / `resume` / `park` tree is returned as that verdict without a record being
+// written, and the read-only check stays re-askable — clean up what it named, ask `run:hold` again.
+// The decision logic itself lives on in `run-preflight.ts` for `run:progress` to reuse; only its CLI
+// went away.
+//
+// **A release names the run it belongs to, exactly as the claim did** (joshuafolkken/kit#1799). The
+// record carries no owner until then, so `run:release` removed whatever was there — and the `busy`
+// stop message tells a person to type it when they judge a record stale, which is a judgement made
+// from outside the run that wrote it. That made the guard's own recovery instruction a way to free a
+// live run's tree: the incident of 2026-08-30, reached through the guard meant to prevent it.
+//
+// **It answers, so the entry point does not judge.** "This one is a small change, it will be fine" is
+// the judgement made under time pressure that produced the incident, and it is the same shape
+// `delegation-policy.ts` refuses to leave to an agent. A token on standard output is what the entry
+// point obeys.
+//
+// The contract is `epic:next`'s: **standard output carries exactly one token** — `hold`, `busy` or
+// `unknown` — and every explanation goes to standard error, so `answer=$(pnpm josh run:hold 1091)`
+// captures something a loop can branch on.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const RELEASE_FLAG = '--release'
+// What removes a record this run did not write. **The deliberate friction of the whole change**
+// (joshuafolkken/kit#1799): every release now names the run it belongs to, and the one act that
+// cannot — clearing a record somebody else left behind — is spelled out rather than reached by
+// typing the ordinary command.
+const FORCE_FLAG = '--force'
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const USAGE = 'Usage: josh run:hold [<issue-number>] | josh run:release [<issue-number> | --force]'
+
+const HOLD_VERDICT = 'hold'
+const BUSY_VERDICT = 'busy'
+const UNKNOWN_VERDICT = 'unknown'
+const RELEASED_VERDICT = 'released'
+const NONE_VERDICT = 'none'
+// The record is another run's, so nothing was removed. **It is not `none`**: a release that did not
+// happen must never read to a script as a tree it has just freed.
+const HELD_VERDICT = 'held'
+
+const FORCE_RELEASE_KIND = 'force-release'
+
+type HoldRequest =
+	| { kind: 'release'; claimant: string }
+	| { kind: typeof FORCE_RELEASE_KIND }
+	| { kind: 'claim'; issue: string }
+
+const FORCE_RELEASE_REQUEST: HoldRequest = { kind: FORCE_RELEASE_KIND }
+
+function release_request(claimant: string): HoldRequest {
+	return { kind: 'release', claimant }
+}
+
+function parse_claim(argv: ReadonlyArray<string>): HoldRequest | undefined {
+	const [first] = argv
+
+	if (first === undefined) return { kind: 'claim', issue: run_hold.UNNUMBERED_ISSUE }
+
+	if (argv.length > 1 || !ISSUE_NUMBER_PATTERN.test(first)) return undefined
+
+	return { kind: 'claim', issue: first }
+}
+
+function parse_release_argument(first: string): HoldRequest | undefined {
+	if (first === FORCE_FLAG) return FORCE_RELEASE_REQUEST
+
+	return ISSUE_NUMBER_PATTERN.test(first) ? release_request(first) : undefined
+}
+
+// **A bare `run:release` is the unnumbered run's release, not a release of whatever is there.** It
+// mirrors the bare claim, which records `new`, so the two spellings stay one pair.
+function parse_release(argv: ReadonlyArray<string>): HoldRequest | undefined {
+	const [first] = argv
+
+	if (first === undefined) return release_request(run_hold.UNNUMBERED_ISSUE)
+
+	return argv.length > 1 ? undefined : parse_release_argument(first)
+}
+
+function parse_request(argv: ReadonlyArray<string>): HoldRequest | undefined {
+	if (argv[0] === RELEASE_FLAG) return parse_release(argv.slice(1))
+
+	return parse_claim(argv)
+}
+
+// One shape for every answer that carries an explanation: the reason to standard error, the single
+// token to standard output, and the exit code that says whether anything was established.
+function report(message: string, verdict: string, code: number): number {
+	console.error(message)
+	console.info(verdict)
+
+	return code
+}
+
+function report_busy(message: string): number {
+	return report(message, BUSY_VERDICT, SUCCESS_EXIT_CODE)
+}
+
+function report_hold(): number {
+	console.info(HOLD_VERDICT)
+
+	return SUCCESS_EXIT_CODE
+}
+
+// What stops a claim, and `undefined` when nothing does. **An unreadable record stops it**: the run
+// that wrote it is the one whose uncommitted work would be trampled, so a record that cannot be
+// parsed is never read as an idle tree. **And an expired record still stops it while the tree is
+// dirty** — that is a run which stopped for a person, and the work is right there in the tree.
+async function blocking_message(read: HoldRead): Promise<string | undefined> {
+	if (read.kind === 'held') return run_hold.held_message(read.hold)
+
+	if (read.kind === 'unreadable') return run_hold.unreadable_message()
+
+	const is_expired_over_work = read.kind === 'stale' && (await run_hold.is_tree_dirty())
+
+	return is_expired_over_work ? run_hold.uncommitted_message(read.hold) : undefined
+}
+
+// A record already here is never overwritten by a claim: overwriting is what the guard exists to
+// prevent, and the person who knows the other run has ended clears it with `run:release --force`.
+function take_free_tree(target: string, issue: string): number {
+	if (run_hold.create_hold(target, issue)) return report_hold()
+
+	return report_busy(run_hold.race_message(run_hold.read_hold(target), target))
+}
+
+// **The stale path takes the tree the same exclusive way the free path does.** Replacing an expired
+// record with a plain write would tell two sessions that both found it expired that they both won —
+// the race the free path was just fixed for, reintroduced one branch over. Removing it first is what
+// turns the expired record into a free tree; the create is what decides between the two claimants.
+function replace_stale(target: string, issue: string, hold: RunHold): number {
+	console.error(run_hold.stale_message(hold))
+	run_hold.release_hold(target)
+
+	return take_free_tree(target, issue)
+}
+
+// A non-clean preflight verdict is not an error: it is an answer a loop branches on, exactly as
+// `busy` is, so it prints the reason and advice the check composed and exits zero. Only an unreadable
+// tree is `unknown`, and that reaches `report_unknown` through `run`'s catch, as it always did.
+function report_preflight(decision: PreflightDecision): number {
+	console.error(`${decision.reason}\n${decision.advice}`)
+	console.info(decision.verdict)
+
+	return SUCCESS_EXIT_CODE
+}
+
+// **The tree is checked before it is claimed.** A numbered claim carries a child whose branch and
+// pull request the check reads; a non-`clean` verdict stops the claim and is returned as-is, so no
+// record is written over work a run left behind. Two claims skip it: the unnumbered `new` claim has
+// no child to preflight, and a lane claim is covered by `lane:open` instead.
+async function preflight_gate(issue: string, is_linked: boolean): Promise<number | undefined> {
+	if (is_linked || issue === run_hold.UNNUMBERED_ISSUE) return undefined
+
+	const decision = await run_preflight.check(issue)
+
+	if (decision.verdict === run_preflight.CLEAN_VERDICT) return undefined
+
+	return report_preflight(decision)
+}
+
+async function claim(target: string, issue: string, is_linked: boolean): Promise<number> {
+	const gate = await preflight_gate(issue, is_linked)
+
+	if (gate !== undefined) return gate
+
+	const read = run_hold.read_hold(target)
+	const blocked = await blocking_message(read)
+
+	if (blocked !== undefined) return report_busy(blocked)
+
+	if (read.kind === 'stale') return replace_stale(target, issue, read.hold)
+
+	return take_free_tree(target, issue)
+}
+
+function remove_record(target: string, was_present: boolean): number {
+	run_hold.release_hold(target)
+	console.info(was_present ? RELEASED_VERDICT : NONE_VERDICT)
+
+	return SUCCESS_EXIT_CODE
+}
+
+function report_held(hold: RunHold): number {
+	return report(run_hold.foreign_release_message(hold), HELD_VERDICT, FAILURE_EXIT_CODE)
+}
+
+// A record nothing can parse names no run, so no claimant can match it — and removing it anyway is
+// the one thing this path exists to refuse. It answers `unknown` for the reason every other
+// unreadable state here does: nothing was established, so nothing may be concluded.
+function report_unreadable_release(): number {
+	return report(run_hold.unreadable_message(), UNKNOWN_VERDICT, FAILURE_EXIT_CODE)
+}
+
+// **A release removes the record only where the record names the run asking** (joshuafolkken/kit#1799).
+// Until then this removed whatever was there, and the `busy` stop message sent a person here to clear
+// a record they had judged stale from outside the run that wrote it — so the guard's own recovery
+// instruction was a way to free a live run's tree, which is the incident it was written after.
+function release(target: string, claimant: string): number {
+	const read = run_hold.read_hold(target)
+
+	if (read.kind === 'free') return remove_record(target, false)
+
+	if (read.kind === 'unreadable') return report_unreadable_release()
+
+	if (!run_hold.is_own_hold(read.hold, claimant)) return report_held(read.hold)
+
+	return remove_record(target, true)
+}
+
+// The one path that removes a record without matching it, which is why it says what it removed: a
+// record genuinely abandoned by a crashed session has no run left to release it, and the eight-hour
+// expiry alone leaves a dirty tree held until a person acts.
+function force_release(target: string): number {
+	const read = run_hold.read_hold(target)
+
+	if (read.kind === 'held' || read.kind === 'stale') {
+		console.error(run_hold.forced_release_message(read.hold))
+	}
+
+	return remove_record(target, read.kind !== 'free')
+}
+
+// A tree whose git directory cannot be read is `unknown` and exits non-zero, never `hold`: the guard
+// has established nothing there, and a run that proceeds on it is the run this command exists to stop.
+function report_unknown(): number {
+	return report(run_hold.unknown_message(), UNKNOWN_VERDICT, FAILURE_EXIT_CODE)
+}
+
+function report_usage(): number {
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function read_worktree(): Promise<string | undefined> {
+	try {
+		return await run_hold.worktree_directory()
+	} catch {
+		return undefined
+	}
+}
+
+async function dispatch(request: HoldRequest, target: string, is_linked: boolean): Promise<number> {
+	if (request.kind === 'claim') return await claim(target, request.issue, is_linked)
+
+	if (request.kind === FORCE_RELEASE_KIND) return force_release(target)
+
+	return release(target, request.claimant)
+}
+
+async function answer(request: HoldRequest): Promise<number> {
+	const directory = await read_worktree()
+
+	if (directory === undefined) return report_unknown()
+
+	const is_linked = await run_hold.is_linked_worktree()
+
+	return await dispatch(request, run_hold.hold_path(directory), is_linked)
+}
+
+// **Every path out of here prints exactly one token**, including the ones nobody planned: a permission
+// error on the record, or a git binary that is not there, used to leave standard output empty — and an
+// empty `$answer` matches none of the three tokens, which an entry point reads as "not busy" before
+// walking straight past the guard.
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request === undefined) return report_usage()
+
+	try {
+		return await answer(request)
+	} catch {
+		return report_unknown()
+	}
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_hold_cli = {
+	BUSY_VERDICT,
+	HELD_VERDICT,
+	HOLD_VERDICT,
+	NONE_VERDICT,
+	RELEASED_VERDICT,
+	UNKNOWN_VERDICT,
+	USAGE,
+	blocking_message,
+	main,
+	parse_request,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_hold_cli }

package/scripts/run/run-hold.ts

@@ -0,0 +1,264 @@
+import { git_command } from '#scripts/git/git-command'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+
+// joshuafolkken/kit#1091: `epicrun` asks `epic-busy.ts` whether a *repository* already has a child in
+// flight, and the entry points a person types — `fullrun`, `halfrun`, `kickoff` — never reach that
+// guard, because they do not go through `epic:next`. On 2026-08-30 two sessions therefore implemented
+// two issues in one checkout at once, and the second was one command away from committing nine files
+// onto the first one's branch.
+//
+// **The unit is the working tree, not the repository.** What these entries contend for is one branch,
+// one index and one uncommitted diff; a linked work tree has its own three, so a second run there is
+// legitimate and must not be stopped. Reusing `epic-busy.ts` here would stop it — that read answers
+// about a repository, which is a different resource and a different question.
+//
+// The key is the work tree's own git directory: `git rev-parse --absolute-git-dir` answers `.git` in
+// the main work tree and `.git/worktrees/<name>` in a linked one, so two work trees of one repository
+// key differently while two commands in the same work tree key alike.
+
+const HOLD_PREFIX = 'josh-run-hold-'
+// The label a `new` entry point writes: the guard has to run *before* the issue is filed, or the
+// stopped run leaves behind the very issue it should not have created.
+const UNNUMBERED_ISSUE = 'new'
+// Longer than any run — a measured `fullrun` is ten to fifty minutes — and short enough that a record
+// abandoned by a crashed session is gone by the next working day. It is what keeps an abnormally
+// ended run from holding the tree forever; a normally ended one is released by `josh followup`.
+const HOLD_MAX_AGE_HOURS = 8
+const MILLISECONDS_PER_HOUR = 3_600_000
+const HOLD_MAX_AGE_MS = HOLD_MAX_AGE_HOURS * MILLISECONDS_PER_HOUR
+
+const RELEASE_COMMAND = 'pnpm josh run:release'
+// The spelling that removes a record this run did not write (joshuafolkken/kit#1799). **It is a
+// separate spelling rather than the same one** because a stop message has to name something a person
+// can type when a record really has been abandoned — and the one it named until now removed a *live*
+// run's record just as readily, which is the incident this guard was written after, reached through
+// the guard's own recovery instruction.
+const FORCE_RELEASE_COMMAND = `${RELEASE_COMMAND} --force`
+// The sentence `epic-busy.ts` prints for the same reason: a guard that cannot read its record has not
+// established that the tree is free, and reporting it as free is the one failure that matters here.
+const NOT_IDLE = 'that is not "nothing is running here"'
+
+interface RunHold {
+	issue: string
+	taken_at: string
+	pid: number
+}
+
+type HoldRead =
+	| { kind: 'free' }
+	| { kind: 'held'; hold: RunHold }
+	| { kind: 'stale'; hold: RunHold }
+	| { kind: 'unreadable' }
+
+const FREE_READ: HoldRead = { kind: 'free' }
+const UNREADABLE_READ: HoldRead = { kind: 'unreadable' }
+
+function hold_path(git_directory: string): string {
+	return stamp_file.stamp_path(HOLD_PREFIX, git_directory)
+}
+
+// The first of the two paths git prints is this work tree's own; the second is the common directory
+// every work tree of the repository shares, which is exactly what must not be the key.
+async function worktree_directory(): Promise<string | undefined> {
+	const directories = await git_command.git_directories()
+
+	return directories[0]
+}
+
+// A linked work tree — a lane — reports its own git directory as the first path and the common
+// directory every work tree of the repository shares as the second; the primary checkout reports one
+// path for both. Comparing the two detects a lane without assuming the git directory is named `.git`:
+// a `--separate-git-dir` clone or a bare repository defeats any `.git`-segment match
+// (joshuafolkken/kit#1106).
+async function is_linked_worktree(): Promise<boolean> {
+	const directories = await git_command.git_directories()
+
+	return directories[0] !== undefined && directories[0] !== directories[1]
+}
+
+const run_hold_schema = z.object({
+	issue: z.string(),
+	taken_at: z.string(),
+	pid: z.number(),
+})
+
+// `undefined` for anything that is not a well-formed record, so the caller decides what a broken one
+// means. It means blocked, not free — see `classify`.
+function parse_hold(raw: string): RunHold | undefined {
+	try {
+		const parsed = run_hold_schema.safeParse(JSON.parse(raw))
+
+		return parsed.success ? parsed.data : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// **A `taken_at` that is not a date is stale, not current.** It passes the schema — it is a string —
+// so reading it as current would leave the tree held with nothing left to expire it, which is the one
+// state the expiry exists to make impossible. Fail-closed is still the answer for the *tree*: a stale
+// record only lets a claim through once `run-hold-cli.ts`'s `blocking_message` has also found the
+// tree clean.
+function is_stale(hold: RunHold, now: Date): boolean {
+	const taken = Date.parse(hold.taken_at)
+
+	if (Number.isNaN(taken)) return true
+
+	return now.getTime() - taken > HOLD_MAX_AGE_MS
+}
+
+// **A record that cannot be read is `unreadable`, never `free`.** Absent is free; present and
+// unparseable is the state a guard must not fall open on, because the run that wrote it is the one
+// whose uncommitted work would be trampled.
+function classify(raw: string | undefined, now: Date): HoldRead {
+	if (raw === undefined) return FREE_READ
+
+	const hold = parse_hold(raw)
+
+	if (hold === undefined) return UNREADABLE_READ
+
+	return { kind: is_stale(hold, now) ? 'stale' : 'held', hold }
+}
+
+function read_hold(target: string, now: Date = new Date()): HoldRead {
+	return classify(stamp_file.read_stamp_text(target), now)
+}
+
+function build_hold(issue: string, now: Date): RunHold {
+	return { issue, taken_at: now.toISOString(), pid: process.pid }
+}
+
+function write_hold(target: string, issue: string, now: Date = new Date()): RunHold {
+	const hold = build_hold(issue, now)
+
+	stamp_file.write_stamp(target, hold)
+
+	return hold
+}
+
+// The claim on a tree that read as free. **Exclusive rather than a plain write**: two sessions typing
+// an entry point in the same second both read `free`, and a write would tell both of them they won —
+// which is the incident this guard was written after, reproduced by the guard itself. `false` means
+// the other one got there first.
+function create_hold(target: string, issue: string, now: Date = new Date()): boolean {
+	return stamp_file.create_stamp(target, build_hold(issue, now))
+}
+
+// **A tree with uncommitted work in it is never handed over, however old its record is.** No age can
+// be chosen that covers a `halfrun` stop or a `needs-human-review` stop: those are held across a
+// person's latency rather than a run's, and the thing that must not be trampled is sitting in the
+// tree where anyone can see it. An unreadable status is dirty, for the reason every other unreadable
+// state here blocks.
+async function is_tree_dirty(): Promise<boolean> {
+	try {
+		const status = await git_command.status()
+
+		return status.trim() !== ''
+	} catch {
+		return true
+	}
+}
+
+function release_hold(target: string): void {
+	stamp_file.remove_stamp(target)
+}
+
+// The pid is recorded for the person reading the stop message, never as the liveness test: the process
+// that claims the tree is a short-lived `josh run:hold`, so it has exited by the time anything reads
+// the record back. Age is what expires a record; `pnpm josh run:release --force` is what clears
+// somebody else's early, and `pnpm josh run:release <N>` what the run that wrote it types.
+function describe_holder(hold: RunHold): string {
+	const holder = hold.issue === UNNUMBERED_ISSUE ? 'an unnumbered run' : `#${hold.issue}`
+
+	return `${holder}, recorded ${hold.taken_at} (pid ${String(hold.pid)})`
+}
+
+// The command the run that *wrote* a record types to remove it — the claim's own spelling, mirrored,
+// so that releasing names the run exactly as claiming did.
+function own_release_command(issue: string): string {
+	return issue === UNNUMBERED_ISSUE ? RELEASE_COMMAND : `${RELEASE_COMMAND} ${issue}`
+}
+
+// The whole of the ownership test, and it is the issue rather than the pid: the process that claims a
+// tree is a short-lived `josh run:hold` that has exited before anything reads the record back, while
+// the issue is what identifies a run across every command it issues. `run-carry.ts` compares a
+// recorded owner against a declared one for the same reason; what differs is only who the owner is.
+function is_own_hold(hold: RunHold, claimant: string): boolean {
+	return hold.issue === claimant
+}
+
+function held_message(hold: RunHold): string {
+	return `This working tree is already held by ${describe_holder(hold)}. One run at a time per working tree: a second run here commits its files onto the other run's branch. If that record is stale, run \`${FORCE_RELEASE_COMMAND}\` in this working tree — it removes a record this run did not write, so be sure the run that did has ended — and ask again.`
+}
+
+// **A release asked by anything but the record's own run removes nothing.** "Stale" is a judgement
+// made from outside the run that wrote the record, and the one place it is made is a person reading a
+// `busy` stop — so the refusal names both ways forward rather than only refusing.
+function foreign_release_message(hold: RunHold): string {
+	return `This working tree is held by ${describe_holder(hold)}, and this release did not claim it — nothing was removed. Release it as that run with \`${own_release_command(hold.issue)}\`, or, once you are sure it has ended, remove the record with \`${FORCE_RELEASE_COMMAND}\`.`
+}
+
+function forced_release_message(hold: RunHold): string {
+	return `Forced: removed the run record held by ${describe_holder(hold)}.`
+}
+
+function unreadable_message(): string {
+	return `This working tree's run record could not be read — ${NOT_IDLE}. Run \`${FORCE_RELEASE_COMMAND}\` in this working tree to clear it, then ask again.`
+}
+
+function stale_message(hold: RunHold): string {
+	return `Replaced a stale run record held by ${describe_holder(hold)}: older than ${String(HOLD_MAX_AGE_HOURS)} hours, so the run that wrote it has ended without releasing it.`
+}
+
+function uncommitted_message(hold: RunHold): string {
+	return `This working tree still has uncommitted changes, and its run record — held by ${describe_holder(hold)} — has expired. That is a run which stopped for a person rather than one that finished, so the tree is not free: commit or stash the work, or run \`${own_release_command(hold.issue)}\` once you are done with it, then ask again.`
+}
+
+// The exclusive claim lost: another process wrote the record between this one's read and its write.
+// Re-reading names the winner where it still holds; where it does not, the record is one this account
+// cannot read — a file another user owns on a shared temp directory — and the answer is still `busy`,
+// because this run did not get the tree. **The path is named** so the person is not sent round a loop
+// of "ask again" that can never come out differently: `run:release` cannot remove a file it does not
+// own either.
+function race_message(read: HoldRead, target: string): string {
+	if (read.kind === 'held') return held_message(read.hold)
+
+	return `A record already exists at ${target} and this run did not write it — ${NOT_IDLE}. Either another run claimed the tree at the same moment, or the record belongs to another account. Run \`${FORCE_RELEASE_COMMAND}\`, and remove that file by hand if it is still there.`
+}
+
+function unknown_message(): string {
+	return `Could not read this working tree's git directory — ${NOT_IDLE}. Run this from inside the checkout the run will edit.`
+}
+
+const run_hold = {
+	FORCE_RELEASE_COMMAND,
+	HOLD_MAX_AGE_HOURS,
+	HOLD_MAX_AGE_MS,
+	RELEASE_COMMAND,
+	UNNUMBERED_ISSUE,
+	classify,
+	create_hold,
+	describe_holder,
+	foreign_release_message,
+	forced_release_message,
+	held_message,
+	hold_path,
+	is_linked_worktree,
+	is_own_hold,
+	is_tree_dirty,
+	own_release_command,
+	parse_hold,
+	race_message,
+	read_hold,
+	release_hold,
+	stale_message,
+	uncommitted_message,
+	unknown_message,
+	unreadable_message,
+	worktree_directory,
+	write_hold,
+}
+
+export type { HoldRead, RunHold }
+export { run_hold }