@joshuafolkken/kit 1.872.0

package/scripts/run/run-carry-change.ts

@@ -0,0 +1,69 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import type { CarryChange, RunCarry } from './run-carry'
+import { run_carry_streak } from './run-carry-streak'
+
+const NO_INCREMENT = 0
+
+function next_done(carry: RunCarry, done: number | undefined): ReadonlyArray<number> | undefined {
+	if (done === undefined) return carry.done
+
+	const current = carry.done ?? []
+
+	return current.includes(done) ? current : [...current, done]
+}
+
+function next_merged_issues(
+	carry: RunCarry,
+	issue: number | undefined,
+): ReadonlyArray<number> | undefined {
+	if (issue === undefined) return carry.merged_issues
+
+	return [...(carry.merged_issues ?? []), issue]
+}
+
+function is_duplicate_merge(carry: RunCarry, change: CarryChange): boolean {
+	const issue = change.merged_issue
+
+	return issue !== undefined && carry.merged_issues?.includes(issue) === true
+}
+
+function next_counts(
+	carry: RunCarry,
+	change: CarryChange,
+): Pick<RunCarry, 'merged' | 'filed' | 'cuts' | 'is_handed_off'> {
+	const cuts = change.cuts ?? NO_INCREMENT
+
+	return {
+		merged: carry.merged + (change.merged ?? NO_INCREMENT),
+		filed: carry.filed + (change.filed ?? NO_INCREMENT),
+		cuts: carry.cuts + cuts,
+		is_handed_off: cuts > NO_INCREMENT,
+	}
+}
+
+function apply_change(
+	target: string,
+	carry: RunCarry,
+	change: CarryChange,
+	now: Date = new Date(),
+): RunCarry {
+	if (is_duplicate_merge(carry, change)) return carry
+
+	const streak = run_carry_streak.next_state(carry, change, now)
+	const next: RunCarry = {
+		...carry,
+		...next_counts(carry, change),
+		merged_issues: next_merged_issues(carry, change.merged_issue),
+		failures: streak.failures,
+		outages: streak.outages,
+		last_outage_at: streak.last_outage_at,
+		done: next_done(carry, change.done),
+		retrospective: change.retrospective === true || carry.retrospective,
+	}
+
+	stamp_file.write_stamp(target, next)
+
+	return next
+}
+
+export const run_carry_change = { apply_change }

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

@@ -0,0 +1,441 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import {
+	run_carry,
+	type CarryClaim,
+	type CarryClaimRequest,
+	type CarryRead,
+	type RunCarry,
+} from './run-carry'
+import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
+import { run_carry_flush } from './run-carry-flush'
+import { run_carry_stash } from './run-carry-stash'
+import { run_event_stream } from './run-event-stream'
+import { run_event_stream_emit } from './run-event-stream-emit'
+import { run_stop_notify } from './run-stop-notify'
+
+// `josh run:carry` — the record that carries one invocation's budget across its own session cuts
+// (joshuafolkken/kit#1714). A `backlogrun` begins it, counts a merge and a filing into it, marks each
+// cut, and ends it; a session that resumes after a cut reads the same budget back rather than
+// starting a new one. **Turning `argv` into a request is `run-carry-args.ts`'s**; what is here acts
+// on the record and prints.
+//
+// The contract is `run:hold`'s: **standard output carries exactly one token** and every explanation
+// goes to standard error, so `answer=$(pnpm josh run:carry --begin "backlogrun --max 5")` captures
+// something a loop can branch on. `--json` is the one exception, and it is still one line: the whole
+// record has to reach a resumed session, and prose on standard error cannot be read back.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const BEGAN_VERDICT = 'began'
+const RESUMED_VERDICT = 'resumed'
+const CARRIED_VERDICT = 'carried'
+const COUNTED_VERDICT = 'counted'
+const ENDED_VERDICT = 'ended'
+const EXPIRED_VERDICT = 'expired'
+const NONE_VERDICT = 'none'
+const UNREADABLE_VERDICT = 'unreadable'
+const MISMATCH_VERDICT = 'mismatch'
+const BUSY_VERDICT = 'busy'
+const STANDING_VERDICT = 'standing'
+const UNKNOWN_VERDICT = 'unknown'
+// The invocation has taken its maximum cuts (joshuafolkken/kit#2346). A benign, non-failing refusal:
+// the run carries on uncut rather than paying a cold preamble the accumulation it would shed no longer
+// covers, exactly as an under-threshold pre-gate cut carries on to the gate.
+const CAPPED_VERDICT = 'capped'
+const NO_CUTS = 0
+
+const CLAIM_VERDICTS: Record<CarryClaim, string> = {
+	busy: BUSY_VERDICT,
+	mismatch: MISMATCH_VERDICT,
+	resume: RESUMED_VERDICT,
+	standing: STANDING_VERDICT,
+}
+
+function report(
+	verdict: string,
+	carry: RunCarry | undefined,
+	is_json: boolean,
+	code: number,
+): number {
+	// **`remaining` rides along with the record rather than behind a flag of its own.** `--json` is
+	// already the one answer a resumed session reads back in full, and the question it has to answer
+	// there — which of a `backlogrun`'s named issues are still outstanding — is determined by two fields
+	// of the record it is already printing (joshuafolkken/kit#1774, folded in by joshuafolkken/kit#1984).
+	// A budget-only `backlogrun` names no issues, so the value is `undefined` and `JSON.stringify` drops
+	// the key entirely.
+	console.info(
+		is_json
+			? JSON.stringify({ verdict, carry, remaining: run_carry.remaining_of(carry) })
+			: verdict,
+	)
+
+	return code
+}
+
+function report_carry(verdict: string, carry: RunCarry, is_json: boolean): number {
+	if (!is_json) console.error(run_carry.describe_carry(carry))
+
+	return report(verdict, carry, is_json, SUCCESS_EXIT_CODE)
+}
+
+function report_unreadable(is_json: boolean): number {
+	console.error(run_carry.unreadable_message())
+
+	return report(UNREADABLE_VERDICT, undefined, is_json, FAILURE_EXIT_CODE)
+}
+
+function report_expired(carry: RunCarry, is_json: boolean): number {
+	console.error(run_carry.expired_message(carry))
+
+	return report_carry(EXPIRED_VERDICT, carry, is_json)
+}
+
+function report_read(read: CarryRead, is_json: boolean): number {
+	if (read.kind === 'none') return report(NONE_VERDICT, undefined, is_json, SUCCESS_EXIT_CODE)
+
+	if (read.kind === 'unreadable') return report_unreadable(is_json)
+
+	if (read.kind === 'expired') return report_expired(read.carry, is_json)
+
+	return report_carry(CARRIED_VERDICT, read.carry, is_json)
+}
+
+function report_busy(carry: RunCarry, is_json: boolean): number {
+	console.error(run_carry.busy_message(carry))
+
+	return report(BUSY_VERDICT, carry, is_json, FAILURE_EXIT_CODE)
+}
+
+function refusal_message(claim: CarryClaim, carry: RunCarry, invocation: string): string {
+	if (claim === 'busy') return run_carry.busy_message(carry)
+
+	if (claim === 'mismatch') return run_carry.mismatch_message(carry, invocation)
+
+	return run_carry.standing_message(carry)
+}
+
+// The exclusive create lost to another process, which is what `busy` says. It is said without
+// re-reading the record, because a record this caller does not own is not one to report the contents
+// of as though it had established them.
+function report_lost(is_json: boolean): number {
+	console.error(run_carry.lost_message())
+
+	return report(BUSY_VERDICT, undefined, is_json, FAILURE_EXIT_CODE)
+}
+
+// The take-over lost that same create, so another process claimed the record in between.
+function report_adoption(
+	target: string,
+	carry: RunCarry,
+	request: CarryClaimRequest,
+	is_json: boolean,
+): number {
+	const adopted = run_carry.adopt_carry(target, carry, request.owner)
+
+	if (adopted === undefined) return report_lost(is_json)
+
+	return report_carry(RESUMED_VERDICT, adopted, is_json)
+}
+
+// **Whose record it is, is the classifier's answer and not this command's guess.** `--end` is only
+// reached on the clean-finish path, so a run that crashed or stopped on a guard leaves its record
+// standing for up to the whole-run bound; `resumed` is reached only where the run itself declared the
+// cut, or where `--resume` says the reader has decided to carry it.
+function report_claim(
+	target: string,
+	carry: RunCarry,
+	request: CarryClaimRequest,
+	is_json: boolean,
+): number {
+	const claim = run_carry.classify_claim(carry, request)
+
+	if (claim === 'resume') return report_adoption(target, carry, request, is_json)
+
+	console.error(refusal_message(claim, carry, request.invocation))
+
+	return report(CLAIM_VERDICTS[claim], carry, is_json, FAILURE_EXIT_CODE)
+}
+
+function start_fresh(
+	target: string,
+	request: CarryClaimRequest,
+	is_replacement: boolean,
+	is_json: boolean,
+): number {
+	const carry = is_replacement
+		? run_carry.replace_carry(target, request.invocation, request.owner)
+		: run_carry.begin_carry(target, request.invocation, request.owner)
+
+	if (carry === undefined) return report_lost(is_json)
+
+	return report_carry(BEGAN_VERDICT, carry, is_json)
+}
+
+// **The bound ends *that* run, so a spent record whose owner is still running is not replaced
+// either.** Replacing it would delete a live parent's budget and answer `began` — two parents on one
+// record, which is the half of the defect the expiry path would otherwise have kept. Only that run,
+// or a person who knows it is over, ends it.
+function begin_over_expired(
+	target: string,
+	carry: RunCarry,
+	request: CarryClaimRequest,
+	is_json: boolean,
+): number {
+	if (run_carry.is_foreign_live_owner(carry, request.owner)) return report_busy(carry, is_json)
+
+	// **A hand-off says the resumption *is* that run, so the spent bound is this session's too.**
+	// Replaced here, the record would come back with `started_at` set to now — and `backlog:budget
+	// --started` reads that field, so the 8-hour bound would restart at every cut and never end the
+	// run. The answer is `expired`, and a person who really is starting a new run clears the record
+	// with `--end`, which is what the expiry message says.
+	if (carry.is_handed_off === true) return report_expired(carry, is_json)
+
+	console.error(run_carry.expired_message(carry))
+
+	return start_fresh(target, request, true, is_json)
+}
+
+// **A live record is never replaced, and never resumed into by something else.** Replacing one would
+// restart the budget the cut exists to carry, and resuming into one would put two parents on a single
+// budget — the two halves of the defect this command was written for. An expired one is replaced,
+// because its run has spent the whole-run bound and a person typing the keyword again is starting a
+// new run — unless its owner is still running, which is the case above.
+function begin(target: string, request: CarryClaimRequest, is_json: boolean): number {
+	const read = run_carry.read_carry(target)
+
+	if (read.kind === 'unreadable') return report_unreadable(is_json)
+
+	if (read.kind === 'carried') return report_claim(target, read.carry, request, is_json)
+
+	if (read.kind === 'expired') return begin_over_expired(target, read.carry, request, is_json)
+
+	return start_fresh(target, request, false, is_json)
+}
+
+function report_nothing_to_resume(is_json: boolean): number {
+	console.error(run_carry.nothing_to_resume_message())
+
+	return report(NONE_VERDICT, undefined, is_json, FAILURE_EXIT_CODE)
+}
+
+// `--resume` is the carry half of the answer `standing` asks for: the reader has decided the standing
+// record's run is over and its budget is this session's to continue. It still refuses a live foreign
+// owner, because deciding that is not the same as being allowed to.
+function adopt(target: string, request: CarryClaimRequest, is_json: boolean): number {
+	const read = run_carry.read_carry(target)
+
+	if (read.kind === 'none') return report_nothing_to_resume(is_json)
+
+	if (read.kind === 'unreadable') return report_unreadable(is_json)
+
+	if (read.kind === 'expired') return report_expired(read.carry, is_json)
+
+	return report_claim(target, read.carry, request, is_json)
+}
+
+function claim_record(target: string, request: CarryClaimRequest, is_json: boolean): number {
+	return request.is_adoption ? adopt(target, request, is_json) : begin(target, request, is_json)
+}
+
+// The record is no longer this session's to advance — handed off at a cut, or taken over by a live
+// successor. It is a refusal exit, said without applying the change (joshuafolkken/kit#1935).
+function report_count_refused(carry: RunCarry, is_json: boolean): number {
+	console.error(run_carry.count_refused_message(carry))
+
+	return report(BUSY_VERDICT, carry, is_json, FAILURE_EXIT_CODE)
+}
+
+// The retrospective's result on the run's event stream, so a run that filed zero improvements reads
+// apart from one whose retrospective never ran (joshuafolkken/kit#2342). It rides the `--retrospective`
+// mark rather than a call of its own, so closing the retrospective and recording what it found are one
+// action; the emit is best-effort, the same contract every other append on this stream keeps, and it
+// happens only after the mark applied — a refused count records nothing.
+async function record_retrospective(request: CountRequest): Promise<void> {
+	if (request.summary === undefined) return
+
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.RETROSPECTIVE, request.summary)
+}
+
+// A cut count is the one increment with a ceiling (joshuafolkken/kit#2346); a merge or a filing has
+// none. `--cut` sets `cuts` to one, so a positive count is what marks this count a cut.
+function is_cut_count(request: CountRequest): boolean {
+	return (request.change.cuts ?? NO_CUTS) > NO_CUTS
+}
+
+// The cut cap is reached, so the cut is refused without applying it — the run carries on uncut. Said as
+// a benign verdict rather than a failure, so a loop reads `capped` and continues rather than stopping.
+function report_cut_capped(carry: RunCarry, is_json: boolean): number {
+	console.error(
+		`Cut cap reached (${String(run_carry.MAX_CUTS)} cuts); nothing was counted and the run carries on uncut.`,
+	)
+
+	return report(CAPPED_VERDICT, carry, is_json, SUCCESS_EXIT_CODE)
+}
+
+// The refusals read before a count is applied: a record this session no longer owns (handed off or
+// taken over) keeps the single writer joshuafolkken/kit#1722 established across a cut, and a cut past
+// the cap carries on uncut (joshuafolkken/kit#2346). `undefined` when neither applies, so the count
+// lands.
+function blocked_count(
+	carry: RunCarry,
+	request: CountRequest,
+	is_json: boolean,
+): number | undefined {
+	if (run_carry.is_count_refused(carry, request.owner)) {
+		return report_count_refused(carry, is_json)
+	}
+
+	if (is_cut_count(request) && run_carry.is_at_cut_cap(carry)) {
+		return report_cut_capped(carry, is_json)
+	}
+
+	return undefined
+}
+
+// A count against a record that is not there is `none` and exits non-zero: the loop believed it was
+// carrying a budget and it was not, and a silent zero would let the run keep its own tally instead. A
+// count against a record this session no longer owns is refused, and a cut past the cap carries on
+// uncut, both before the change is applied (joshuafolkken/kit#1935, joshuafolkken/kit#2346).
+async function count(
+	target: string,
+	read: CarryRead,
+	request: CountRequest,
+	is_json: boolean,
+): Promise<number> {
+	if (read.kind === 'none') return report(NONE_VERDICT, undefined, is_json, FAILURE_EXIT_CODE)
+
+	if (read.kind === 'unreadable') return report_unreadable(is_json)
+
+	const blocked = blocked_count(read.carry, request, is_json)
+
+	if (blocked !== undefined) return blocked
+
+	const carry = run_carry.apply_change(target, read.carry, request.change)
+
+	await record_retrospective(request)
+
+	return read.kind === 'expired'
+		? report_expired(carry, is_json)
+		: report_carry(COUNTED_VERDICT, carry, is_json)
+}
+
+// **A stop over a record that is still there pushes one ⏸️ confirmation before the record goes**
+// (joshuafolkken/kit#2136). `plan` is read from the record `--end` is about to remove, so the second
+// `--end` reads `none` and plans nothing — one stop never notifies twice. A clean `--end` passes no
+// reason and stays silent, because a completed run has its own notification. The batch's one ledger
+// flush rides the same read for the same reason (joshuafolkken/kit#2492, `run-carry-flush.ts`), and
+// runs last: it waits out a pull request's CI, so a flush cut short must find the record already gone
+// and the stop already announced. The closed-issue stash report (joshuafolkken/kit#2505,
+// `run-carry-stash.ts`) is once per invocation on the same read, and goes first because it is quick.
+async function report_end(read: CarryRead): Promise<void> {
+	if (read.kind === 'none') return
+
+	await run_carry_stash.report_orphans()
+	await run_carry_flush.flush_ledger()
+}
+
+async function finish(
+	target: string,
+	stopped: string | undefined,
+	is_json: boolean,
+): Promise<number> {
+	const read = run_carry.read_carry(target)
+
+	run_carry.end_carry(target)
+
+	const notice = run_stop_notify.plan(read, stopped)
+
+	if (notice !== undefined) await run_stop_notify.announce(notice)
+
+	await report_end(read)
+
+	if (read.kind === 'none') return report(NONE_VERDICT, undefined, is_json, SUCCESS_EXIT_CODE)
+
+	if (read.kind === 'unreadable') {
+		return report(ENDED_VERDICT, undefined, is_json, SUCCESS_EXIT_CODE)
+	}
+
+	return report_carry(ENDED_VERDICT, read.carry, is_json)
+}
+
+async function act(target: string, request: Request, is_json: boolean): Promise<number> {
+	if (request.kind === 'claim') return claim_record(target, request.claim, is_json)
+
+	if (request.kind === 'end') return await finish(target, request.stopped, is_json)
+
+	const read = run_carry.read_carry(target)
+
+	if (request.kind === 'read') return report_read(read, is_json)
+
+	return await count(target, read, request, is_json)
+}
+
+function report_unknown(is_json: boolean): number {
+	console.error(run_carry.unknown_message())
+
+	return report(UNKNOWN_VERDICT, undefined, is_json, FAILURE_EXIT_CODE)
+}
+
+async function answer(request: Request, is_json: boolean): Promise<number> {
+	const directory = await run_carry.repository_directory()
+
+	if (directory === undefined) return report_unknown(is_json)
+
+	return await act(run_carry.carry_path(directory), request, is_json)
+}
+
+function refuse(): number {
+	console.error(run_carry_args.USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+// Every path out of here prints exactly one token, including the ones nobody planned: an empty
+// standard output matches none of the verdicts, which a loop reads as "nothing to carry" before
+// starting a second budget over the first one's.
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const values = run_carry_args.read_arguments(argv)
+
+	if (values === undefined) return refuse()
+
+	const request = run_carry_args.to_request(values)
+
+	if (request === undefined) return refuse()
+
+	try {
+		return await answer(request, values.json === true)
+	} catch {
+		return report_unknown(values.json === true)
+	}
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const run_carry_cli = {
+	BEGAN_VERDICT,
+	BUSY_VERDICT,
+	CAPPED_VERDICT,
+	CARRIED_VERDICT,
+	COUNTED_VERDICT,
+	ENDED_VERDICT,
+	EXPIRED_VERDICT,
+	MISMATCH_VERDICT,
+	NONE_VERDICT,
+	RESUMED_VERDICT,
+	STANDING_VERDICT,
+	UNKNOWN_VERDICT,
+	UNREADABLE_VERDICT,
+	// Re-exported rather than restated: the usage line belongs to the half that parses, and a second
+	// copy of it here would drift from the flags it describes.
+	USAGE: run_carry_args.USAGE,
+	main,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { run_carry_cli }

package/scripts/run/run-carry-flush.ts

@@ -0,0 +1,63 @@
+import { git_spawn } from '#scripts/git/git-spawn'
+import { josh_command } from '#scripts/josh/josh-run'
+import { observation_ledger } from '#scripts/observations/observation-ledger'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+
+// The one observation-ledger flush a `backlogrun` makes, at its end (joshuafolkken/kit#2492).
+//
+// A lane child used to flush after every merge (`run:tail`'s first step): a ledger-only branch, pull
+// request and full CI run per issue, minutes each, for a file only the retrospective and the
+// measurements read. The lanes now leave their lines appended in the primary checkout — the ledger's
+// only home (`observation-ledger-home.ts`) — and `run:carry --end` commits them all in one pull request
+// once the record is gone. `--end` is the batch's one end across every session cut, and the second
+// `--end` finds no record and flushes nothing, so the flush is once per invocation.
+//
+// **It runs after the retrospective, not before**, and loses nothing by it: the retrospective reads the
+// ledger file on disk (`retrospective-cli.ts` → `read_ledger`), not main, and the lines it stacks
+// itself land in the same pull request. **A line a cut or a crash left unflushed is not lost either**:
+// it is still a pending append in the primary checkout, and the next flush — this one, a later run's,
+// or a single run's `followup` — sees it from `git status`, whichever run wrote it.
+//
+// **A failed flush is reported, never allowed to keep the record standing.** The lines stay on disk for
+// the next flush, while a record that outlived its run would make the next `--begin` read `busy` — so
+// `--end` clears the record before it flushes. A flush killed before its commit leaves only the lines
+// in the working tree; one killed after it leaves them on its pull request's branch, which GitHub's
+// auto-merge lands once the checks pass (joshuafolkken/kit#2497).
+
+const FLUSH_ARGV: ReadonlyArray<string> = ['observations:flush']
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_NOTE =
+	'The observation ledger flush failed; its lines stay in the primary checkout for the next flush (`pnpm josh observations:flush`).'
+
+async function has_pending_append(): Promise<boolean> {
+	const root = observation_ledger_home.ledger_root()
+	const status = await git_spawn.read([
+		'-C',
+		root,
+		'status',
+		'--porcelain',
+		'--untracked-files=normal',
+	])
+
+	return observation_ledger.has_pending_append(status)
+}
+
+// Standard output is `run:carry`'s one-token contract, so every word of the flush goes to standard
+// error — the flush's own explanation is forwarded there, and its report is copied after it.
+async function flush_ledger(): Promise<void> {
+	try {
+		if (!(await has_pending_append())) return
+
+		const result = await josh_command.josh_run(FLUSH_ARGV, true)
+
+		if (result.out.length > 0) console.error(result.out)
+
+		if (result.code !== SUCCESS_EXIT_CODE) console.error(FAILURE_NOTE)
+	} catch {
+		console.error(FAILURE_NOTE)
+	}
+}
+
+const run_carry_flush = { FAILURE_NOTE, FLUSH_ARGV, flush_ledger }
+
+export { run_carry_flush }

package/scripts/run/run-carry-stash.ts

@@ -0,0 +1,71 @@
+import { git_stash } from '#scripts/git/git-stash'
+import { stash_orphans } from '#scripts/git/stash-orphans'
+import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+
+// The stash check a `backlogrun` makes at its end (joshuafolkken/kit#2505): the entries whose issue has
+// closed, and those with no readable owner, printed for a person to revive or discard. It rides
+// `run:carry --end` for the ledger flush's reason — `--end` is the invocation's one end across every
+// session cut, where `--begin` repeats on each resume. Standard output is `run:carry`'s one-token
+// contract, so the report goes to standard error, and a failed read is a note rather than a failed end.
+
+const READ_CONCURRENCY = 8
+const CLOSED_STATE = 'CLOSED'
+const FAILURE_NOTE =
+	'The closed-issue stash check failed; review the stack by hand with `git stash list`.'
+
+type Verdict = 'closed' | 'open' | 'unreadable'
+
+interface ClosedRead {
+	closed: Set<string>
+	unreadable: Array<string>
+}
+
+// Only a read that answers `CLOSED` counts as closed: a missing or unreadable issue is not evidence the
+// work is abandoned, and reporting it as closed would invite a person to drop live work.
+async function verdict_of(issue: string): Promise<Verdict> {
+	const read = await issue_state_cli.read_issue(issue)
+
+	if (read.kind !== 'state') return 'unreadable'
+
+	return read.state.state === CLOSED_STATE ? 'closed' : 'open'
+}
+
+async function read_closed(issues: ReadonlyArray<string>): Promise<ClosedRead> {
+	const verdicts = await bounded_pool.bounded_map(
+		issues,
+		READ_CONCURRENCY,
+		async (issue) => await verdict_of(issue),
+	)
+
+	return {
+		closed: new Set(issues.filter((_issue, index) => verdicts[index] === 'closed')),
+		unreadable: issues.filter((_issue, index) => verdicts[index] === 'unreadable'),
+	}
+}
+
+// `read_issue` answers a failed `gh` call as `unreadable` rather than throwing, so a missing `gh` or a
+// rate limit would otherwise empty the closed set and print a report that looks complete.
+function unreadable_note(unreadable: ReadonlyArray<string>): string {
+	const issues = unreadable.map((issue) => `#${issue}`).join(', ')
+
+	return `Could not read ${issues}, so a stash of theirs may be missing above; ${FAILURE_NOTE}`
+}
+
+async function report_orphans(): Promise<void> {
+	try {
+		const entries = await git_stash.list()
+		const read = await read_closed(stash_orphans.issues_of(entries))
+		const report = stash_orphans.format_report(stash_orphans.orphans(entries, read.closed))
+
+		if (report !== undefined) console.error(report)
+
+		if (read.unreadable.length > 0) console.error(unreadable_note(read.unreadable))
+	} catch {
+		console.error(FAILURE_NOTE)
+	}
+}
+
+const run_carry_stash = { FAILURE_NOTE, report_orphans }
+
+export { run_carry_stash }