@joshuafolkken/kit 1.1240.0 → 1.1373.0

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

@@ -4,6 +4,9 @@ import { cost_cli } from '#scripts/cost-runtime/cost-cli'
 import { cost_verdict } from '#scripts/cost-runtime/cost-verdict'
 import { run_event_stream } from '#scripts/run/event/run-event-stream'
 import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { run_merge_collect } from '#scripts/run/merge/run-merge-collect'
+import { run_cli_fault } from '#scripts/run/run-cli-fault'
+import { run_headless } from '#scripts/run/run-headless'
 import { run_stop_notify } from '#scripts/run/run-stop-notify'
 import {
 	run_carry,
@@ -14,10 +17,11 @@ import {
 } from './run-carry'
 import { run_carry_args, type CountRequest, type Request } from './run-carry-args'
 import { run_carry_conversation } from './run-carry-conversation'
+import { run_carry_ended } from './run-carry-ended'
 import { run_carry_stash } from './run-carry-stash'
 
-// `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
+// `josh run:carry` — the record that carries one invocation's budget across its own session cuts.
+// 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.
@@ -42,12 +46,12 @@ 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:
+const COMMAND = 'run:carry'
+// The invocation has taken its maximum cuts. 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'
-// The asking session is over the shared context-cut threshold, so nothing was claimed
-// (joshuafolkken/kit#2760).
+// The asking session is over the shared context-cut threshold, so nothing was claimed.
 const OVER_VERDICT = 'over'
 const NO_CUTS = 0
 
@@ -67,9 +71,8 @@ function report(
 	// **`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.
+	// of the record it is already printing. 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) })
@@ -180,8 +183,7 @@ function start_fresh(
 
 // **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.
+// record. Only that run, or a person who knows it is over, ends it.
 function begin_over_expired(
 	target: string,
 	carry: RunCarry,
@@ -204,7 +206,7 @@ function begin_over_expired(
 
 // **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,
+// budget. 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 {
@@ -240,10 +242,9 @@ function adopt(target: string, request: CarryClaimRequest, is_json: boolean): nu
 	return report_claim(target, read.carry, request, is_json)
 }
 
-// **A session already over the shared cut threshold claims nothing** (joshuafolkken/kit#2760). A claim
-// assumed the asking session was fresh, so a `backlogrun` parent that had taken its cut at 233k could
-// retype the keyword in the same conversation and be answered `resumed` by its own hand-off — measured
-// twice, at 232k and 258k. The verdict is `pnpm josh cost --cut`'s, so no second threshold exists; only a
+// **A session already over the shared cut threshold claims nothing**: a `backlogrun` parent that has
+// taken its cut could otherwise retype the keyword in the same conversation and be answered `resumed`
+// by its own hand-off. The verdict is `pnpm josh cost --cut`'s, so no second threshold exists; only a
 // measured `over` refuses, because a provider with no transcript cannot be priced at all.
 function report_over(is_json: boolean): number {
 	console.error(
@@ -260,7 +261,7 @@ function claim_record(target: string, request: CarryClaimRequest, is_json: boole
 }
 
 // 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).
+// successor. It is a refusal exit, said without applying the change.
 function report_count_refused(carry: RunCarry, is_json: boolean): number {
 	console.error(run_carry.count_refused_message(carry))
 
@@ -268,9 +269,8 @@ function report_count_refused(carry: RunCarry, is_json: boolean): number {
 }
 
 // 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
+// apart from one whose retrospective never ran. 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
@@ -278,7 +278,7 @@ async function record_retrospective(request: CountRequest): Promise<void> {
 	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
+// A cut count is the one increment with a ceiling; 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
@@ -295,9 +295,8 @@ function report_cut_capped(carry: RunCarry, is_json: boolean): number {
 }
 
 // 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.
+// taken over) keeps a single writer across a cut, and a cut past the cap carries on uncut. `undefined`
+// when neither applies, so the count lands.
 function blocked_count(
 	carry: RunCarry,
 	request: CountRequest,
@@ -305,7 +304,7 @@ function blocked_count(
 ): 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)) {
+	if (is_cut_count(request) && run_headless.is_cut_capped(carry)) {
 		return report_cut_capped(carry, is_json)
 	}
 
@@ -315,7 +314,7 @@ function blocked_count(
 // 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).
+// uncut, both before the change is applied.
 async function count(
 	target: string,
 	read: CarryRead,
@@ -340,29 +339,47 @@ async function count(
 		: 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 closed-issue stash
-// report (joshuafolkken/kit#2505, `run-carry-stash.ts`) is once per invocation on the same read.
-//
-// **No ledger flush rides it any more** (joshuafolkken/kit#2919): each lane merges its own ledger
-// lines with its own pull request, so there is nothing left in the primary checkout to flush.
+// **A stop over a record that is still there pushes one ⏸️ confirmation before the record goes**.
+// `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 closed-issue stash report
+// (`run-carry-stash.ts`) is once per invocation on the same read.
 async function report_end(read: CarryRead): Promise<void> {
 	if (read.kind === 'none') return
 
 	await run_carry_stash.report_orphans()
 }
 
-async function finish(
-	target: string,
-	stopped: string | undefined,
-	is_json: boolean,
-): Promise<number> {
+// Best-effort: the board's record of the ended run never stands between `--end` and the carry record it
+// clears, so a failed write goes to stderr rather than leaving the run carried.
+function keep_ended(directory: string, read: CarryRead, stopped: string | undefined): void {
+	try {
+		run_carry_ended.record_ended(run_carry_ended.ended_path(directory), read, new Date(), stopped)
+	} catch (error) {
+		console.error(`run:carry: the ended run was not recorded for run:board: ${String(error)}`)
+	}
+}
+
+// The record goes, and the run it held stays readable as the last ended run, so `run:board` keeps the
+// finished run on screen until the next one begins — a stopped one with the session to resume it from.
+function close_record(directory: string, stopped: string | undefined): CarryRead {
+	const target = run_carry.carry_path(directory)
 	const read = run_carry.read_carry(target)
 
+	keep_ended(directory, read, stopped)
 	run_carry.end_carry(target)
 
+	return read
+}
+
+// The merges the run ended with are recorded while its record can still count them.
+async function finish(
+	directory: string,
+	stopped: string | undefined,
+	is_json: boolean,
+): Promise<number> {
+	await run_merge_collect.collect_merged(directory)
+	const read = close_record(directory, stopped)
 	const notice = run_stop_notify.plan(read, stopped)
 
 	if (notice !== undefined) await run_stop_notify.announce(notice)
@@ -378,11 +395,13 @@ async function finish(
 	return report_carry(ENDED_VERDICT, read.carry, is_json)
 }
 
-async function act(target: string, request: Request, is_json: boolean): Promise<number> {
+async function act(
+	target: string,
+	request: Exclude<Request, { kind: 'end' }>,
+	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)
@@ -390,16 +409,19 @@ async function act(target: string, request: Request, is_json: boolean): Promise<
 	return await count(target, read, request, is_json)
 }
 
-function report_unknown(is_json: boolean): number {
-	console.error(run_carry.unknown_message())
+// `unknown` with the reason it was answered: nothing was established, so nothing may be concluded.
+function report_unknown(message: string, is_json: boolean): number {
+	console.error(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()
+	const directory = await run_cli_fault.directory_of(COMMAND, run_carry.repository_directory)
+
+	if (directory === undefined) return report_unknown(run_carry.unknown_message(), is_json)
 
-	if (directory === undefined) return report_unknown(is_json)
+	if (request.kind === 'end') return await finish(directory, request.stopped, is_json)
 
 	return await act(run_carry.carry_path(directory), request, is_json)
 }
@@ -412,7 +434,8 @@ function refuse(): number {
 
 // 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.
+// starting a second budget over the first one's. The token stays `unknown`, and the failure says what
+// it was rather than borrowing the unreadable-git-directory message.
 async function run(argv: ReadonlyArray<string>): Promise<number> {
 	const values = run_carry_args.read_arguments(argv)
 
@@ -424,8 +447,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	try {
 		return await answer(request, values.json === true)
-	} catch {
-		return report_unknown(values.json === true)
+	} catch (error) {
+		return report_unknown(run_cli_fault.message(COMMAND, error), values.json === true)
 	}
 }
 

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

@@ -4,13 +4,12 @@ import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
 import { own_session } from '#scripts/cost-runtime/own-session'
 import type { CarryOwner, RunCarry } from './run-carry'
 
-// **A conversation outlives its process, so an owner named by a pid alone dies too early**
-// (joshuafolkken/kit#3137). The carry record names the agent process spending the budget, and that is
-// right while the process lives — but an interactive conversation is not its process. On 2026-10-04 a
-// VS Code extension-host restart ended the session's process at 15:17:34 UTC, and the same
-// conversation resumed eighteen seconds later in a new process (`--resume=<id>`), writing on into the
-// same transcript. `run:wake` read the old pid as dead, recovered the record as a crash, and dispatched
-// a second lane child for the issue the conversation was still running.
+// **A conversation outlives its process, so an owner named by a pid alone dies too early.** The carry
+// record names the agent process spending the budget, and that is right while the process lives — but
+// an interactive conversation is not its process. An extension-host restart ends the process and the
+// same conversation resumes seconds later in a new one (`--resume=<id>`), writing on into the same
+// transcript; read by pid alone, `run:wake` would recover the record as a crash and dispatch a second
+// lane child for the issue the conversation is still running.
 //
 // **The transcript is what persists across the restart, so it is the second half of the identity.**
 // Every resume path — the extension's `--resume=<id>`, a person's `claude -c` — appends to the one

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

@@ -0,0 +1,85 @@
+import path from 'node:path'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import type { CarryRead } from './run-carry'
+
+// The run `run:carry --end` last ended. `--end` removes the carry record, whose `started_at` is the only
+// mark of where an invocation began on the shared event stream, so without this `run:board` would lose
+// the finished run the moment it ended. This keeps the three facts the board needs to redraw that run —
+// what it was asked to do, when it began and when it ended — read from a record rather than guessed on
+// screen.
+//
+// **A stopped run also keeps why it stopped and the session that ran it**, so the board can offer the command that resumes that session to the person the stop waits on. The
+// session is the owner's transcript name, which is the Claude session id; a run with no transcript —
+// a Codex parent — keeps none.
+//
+// **One record, overwritten by the next `--end`**: the board keeps only the run before the next one, and
+// a run that begins replaces nothing here — its carry record is what the board reads while it runs.
+
+const ENDED_PREFIX = 'josh-run-ended-'
+const TRANSCRIPT_SUFFIX = '.jsonl'
+
+const ended_run_schema = z.object({
+	invocation: z.string(),
+	started_at: z.string(),
+	ended_at: z.string(),
+	stopped: z.string().optional(),
+	session: z.string().optional(),
+})
+
+type EndedRun = z.infer<typeof ended_run_schema>
+
+// Keyed on the common git directory, as the carry record is, so every lane reads the same one.
+function ended_path(git_directory: string): string {
+	return stamp_file.stamp_path(ENDED_PREFIX, git_directory)
+}
+
+function session_of(transcript: string | undefined): string | undefined {
+	return transcript === undefined ? undefined : path.basename(transcript, TRANSCRIPT_SUFFIX)
+}
+
+// The stop's reason and session, only for a run that stopped: a clean end has nobody to resume for.
+function stop_of(
+	transcript: string | undefined,
+	stopped: string | undefined,
+): Pick<EndedRun, 'stopped' | 'session'> {
+	return stopped === undefined ? {} : { stopped, session: session_of(transcript) }
+}
+
+// Records the run a `--end` is about to remove. A read with no record — `none` or `unreadable` — names
+// no run, so it leaves the previous record standing rather than erasing it.
+function record_ended(
+	target: string,
+	read: CarryRead,
+	now: Date = new Date(),
+	stopped?: string,
+): void {
+	if (read.kind !== 'carried' && read.kind !== 'expired') return
+
+	const { invocation, started_at, owner_transcript } = read.carry
+	const ended_at = now.toISOString()
+
+	stamp_file.replace_stamp(target, {
+		invocation,
+		started_at,
+		ended_at,
+		...stop_of(owner_transcript, stopped),
+	})
+}
+
+function parse_ended(raw: string): EndedRun | undefined {
+	return json_value.parse_with(raw, ended_run_schema)
+}
+
+// `undefined` when no run has ended here, or the record does not read.
+function read_ended(target: string): EndedRun | undefined {
+	const raw = stamp_file.read_stamp_text(target)
+
+	return raw === undefined ? undefined : parse_ended(raw)
+}
+
+const run_carry_ended = { ended_path, read_ended, record_ended }
+
+export { run_carry_ended }
+export type { EndedRun }

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

@@ -2,7 +2,7 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { run_carry, type CarryOwner } from './run-carry'
 import { run_carry_conversation } from './run-carry-conversation'
 
-// **A resumed conversation has to take its record back before it falls quiet** (joshuafolkken/kit#3137).
+// **A resumed conversation has to take its record back before it falls quiet**.
 // A count moves the owner to the conversation's new process, but a parent waiting on a lane child
 // counts nothing — `lane:await` blocks in the background and the transcript stays unwritten — so a
 // restart followed by a long wait outlasts the quiet window with the record still naming the dead

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

@@ -1,9 +1,10 @@
 import { git_stash } from '#scripts/git/stash/git-stash'
 import { stash_orphans } from '#scripts/git/stash/stash-orphans'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
+import { session_cite } from '#scripts/issue/session-cite'
 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
+// The stash check a `backlogrun` makes at its end: 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
@@ -47,7 +48,7 @@ async function read_closed(issues: ReadonlyArray<string>): Promise<ClosedRead> {
 // `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(', ')
+	const issues = unreadable.map((issue) => session_cite.issue(issue)).join(', ')
 
 	return `Could not read ${issues}, so a stash of theirs may be missing above; ${FAILURE_NOTE}`
 }

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

@@ -1,6 +1,5 @@
-// The pure streak arithmetic behind `run-carry.ts` → `apply_change`, relocated here so the record's
-// file stays under its line bound and the outage fold has a test of its own (joshuafolkken/kit#2317).
-// It owns the two consecutive-streak counters — the failure streak and the API-outage streak — and the
+// The pure streak arithmetic behind `run-carry.ts` → `apply_change`, kept apart so the record's file
+// stays under its line bound and the outage fold has a test of its own. It owns the two consecutive-streak counters — the failure streak and the API-outage streak — and the
 // one timestamp the outage fold reads. Nothing here touches disk: it is arithmetic over the values a
 // change carries and the counters already on the record.
 //
@@ -15,8 +14,8 @@ const NO_INCREMENT = 0
 // two minutes covers that burst with room to spare. **A genuinely dead API is different**: an outage
 // child is re-dispatched and spends its ten connection retries before the next child returns, so two
 // consecutive *real* outages land minutes apart — outside this window — and still accumulate toward the
-// environment guard. Measured on 2026-09-22 (joshuafolkken/kit#2317): one network event booked four
-// outages within seconds, tripping the limit of three in a single stroke though the API was alive.
+// environment guard, while one network event booking several outages within seconds cannot trip the
+// limit in a single stroke though the API is alive.
 const OUTAGE_FOLD_WINDOW_MS = 120_000
 
 interface StreakCarry {
@@ -48,7 +47,7 @@ function has_increment(value: number | undefined): boolean {
 
 // **A merge resets the streak; every other change adds to it.** The consecutive-failure guard trips on
 // children failing one after another, so a child that merged in between is what breaks the run — the
-// reset lives with the increment rather than in a caller that could forget it (joshuafolkken/kit#2024).
+// reset lives with the increment rather than in a caller that could forget it.
 function next_failures(carry: StreakCarry, change: StreakChange): number {
 	if (has_increment(change.merged)) return NO_INCREMENT
 
@@ -81,10 +80,9 @@ function counted_outage(carry: StreakCarry, change: StreakChange, now: Date): Ou
 	return { outages, last_outage_at: now.toISOString() }
 }
 
-// **An outage adds to the streak unless it folds; a merge or a genuine child failure resets it**
-// (joshuafolkken/kit#2240, fold added by joshuafolkken/kit#2317). Anything that proves the API *was*
-// reachable — a merge, or a child that failed on its own after reaching it — breaks the run and clears
-// the fold timestamp. A change that touches none of the three leaves the streak untouched.
+// **An outage adds to the streak unless it folds; a merge or a genuine child failure resets it**.
+// Anything that proves the API *was* reachable — a merge, or a child that failed on its own after
+// reaching it — breaks the run and clears the fold timestamp. A change that touches none of the three leaves the streak untouched.
 function next_outage(carry: StreakCarry, change: StreakChange, now: Date): OutageState {
 	if (has_increment(change.outages)) {
 		return is_within_fold_window(carry.last_outage_at, now)