@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/josh/cli-body.ts

@@ -2,8 +2,8 @@ import { readFileSync, statSync } from 'node:fs'
 import path from 'node:path'
 
 // A body — an Issue comment, a PR comment, a notification message — handed to a command as an inline
-// double-quoted shell argument is **evaluated by the shell before the command ever sees it**
-// (joshuafolkken/kit#1198). The observed damage is not a mangled string: a PR comment posted with
+// double-quoted shell argument is **evaluated by the shell before the command ever sees it**.
+// The observed damage is not a mangled string: a PR comment posted with
 // `gh api … -f body="… \`pnpm josh ms\` …"` had part of its own text run as git commands, which
 // switched a lane's work tree onto `main` and stopped the run.
 //

package/scripts/josh/command-suggest.ts

@@ -1,6 +1,6 @@
 // A single-token "did you mean" for `josh <typo>`. The command set is small and the input is one
 // word, so a character edit distance is the right measure here — unlike `issue-scout`'s token-set
-// Dice similarity, which compares multi-word issue titles (joshuafolkken/kit#1928).
+// Dice similarity, which compares multi-word issue titles.
 const MAX_SUGGESTION_DISTANCE = 3
 
 // A cell of the matrix, defaulting the out-of-range read to 0. Reading through it keeps the nullish

package/scripts/josh/file-map-stamp.ts

@@ -1,8 +1,7 @@
 import { process_identity } from './process-identity'
 import { stamp_file } from './stamp-file'
 
-// A stamp whose payload is "when this was taken, and the digest of every file it covers"
-// (joshuafolkken/kit#1241).
+// A stamp whose payload is "when this was taken, and the digest of every file it covers".
 //
 // `scripts/eval/eval-stamp.ts` was the only holder of this shape. `josh review:brief` needs two more
 // records of exactly the same kind — the gate's result, and the snapshot round 1 takes so round 2
@@ -18,10 +17,10 @@ interface FileMapStamp {
 	taken_at: string
 	files: Record<string, string>
 	// The process that wrote it. Only a record whose meaning is "this is happening **now**" needs it —
-	// the in-flight gate marker (joshuafolkken/kit#1242). The other two assert a completed past fact,
+	// the in-flight gate marker. The other two assert a completed past fact,
 	// which stays true however long the file sits there, so they carry it and never read it.
 	pid?: number
-	// The other half of that process's identity: when it started (joshuafolkken/kit#1245). **A pid
+	// The other half of that process's identity: when it started. **A pid
 	// alone names whatever holds that number now**, so a marker left behind by a killed gate began
 	// reading as live again the moment the operating system reissued its pid — the brief then reporting
 	// a gate running on this tree about a gate that no longer exists. The pair separates them, because
@@ -30,19 +29,19 @@ interface FileMapStamp {
 	// the field existed carries none, which `process_identity.is_same_process` answers as "cannot tell"
 	// rather than as a match.
 	process_start?: string
-	// The commit the file map is defined against (joshuafolkken/kit#1328). Every reader of these
+	// The commit the file map is defined against. Every reader of these
 	// records computes its map as a diff against that commit — the branch's merge base with the
-	// default branch since joshuafolkken/kit#1527 — so **the map alone does not describe a tree**:
+	// default branch — so **the map alone does not describe a tree**:
 	// fetch an advanced default branch and rebase onto it, and every digest can stay identical while
 	// the rest of the working tree is replaced by code no check has read. The rebase moves `HEAD` and
 	// so moves the merge base, which is what this field catches; another lane merging into the shared
 	// default branch moves neither, and correctly leaves the record standing. Every reader that acts on
 	// a record rather than merely reporting it needs the guarantee: `josh gate`, which reuses a green
-	// result instead of re-running it, and since joshuafolkken/kit#1537 the round-1 review snapshot,
+	// result instead of re-running it, and the round-1 review snapshot,
 	// whose whole use is to name what round 1's fixes changed. A record written without it is refused
 	// rather than trusted.
 	base?: string
-	// When the run that wrote this record reached its verdict (joshuafolkken/kit#1164). Written only
+	// When the run that wrote this record reached its verdict. Written only
 	// by `complete`, so it is absent on a record whose run was interrupted or threw — which is the
 	// whole difference between "a run measured this tree" and "a run measured this tree and
 	// finished". Only a reader that acts on the *verdict* needs the second, so `josh eval` writes and
@@ -61,7 +60,7 @@ function is_file_map(value: unknown): value is Record<string, string> {
 }
 
 // An optional field of the wrong type is dropped rather than rejected: the records that never read
-// one were written without it before joshuafolkken/kit#1242 and joshuafolkken/kit#1328, and every
+// one were written without it, and every
 // reader treats an absent field as the safe answer — "not running" for a `pid`, "cannot be reused"
 // for a `base`. Spread rather than assigned, because `exactOptionalPropertyTypes` makes an explicit
 // `undefined` a different thing from an absent key.
@@ -89,7 +88,7 @@ function parse_stamp(raw: string): FileMapStamp | undefined {
 	return { taken_at, files, ...optional_fields(pid, base, completed_at, process_start) }
 }
 
-// Whether the process that wrote this record is still running (joshuafolkken/kit#1245). It takes the
+// Whether the process that wrote this record is still running. It takes the
 // whole record rather than a pid, because a pid on its own is not a process: asked that way a caller
 // could not tell the writing process from whatever the operating system later reissued its number to,
 // which is exactly the state the in-flight marker must never describe.
@@ -112,14 +111,13 @@ function is_writer_running(stamp: FileMapStamp | undefined): boolean {
 
 // **For a guard: only when certain of the opposite.** `josh bench` deletes caches a running gate is
 // reading, so the question it must ask is not "is the writer running" but "am I sure it is gone" — an
-// uncertain answer there would clear the caches out from under a live gate, which is the very event
-// joshuafolkken/kit#1332 was filed for. The probe is a subprocess and can fail on a loaded machine,
+// uncertain answer there would clear the caches out from under a live gate. The probe is a subprocess and can fail on a loaded machine,
 // which is exactly the machine a gate makes, so this is not a theoretical branch.
 function is_writer_gone(stamp: FileMapStamp | undefined): boolean {
 	return writer_state(stamp) === false
 }
 
-// Whether a record may be compared against a map read now (joshuafolkken/kit#1537). Every map here is
+// Whether a record may be compared against a map read now. Every map here is
 // a diff against `change_base`, so two of them taken against **different** bases do not cover the same
 // set of paths — and `changed_since` below reports that set difference as though the files had been
 // edited. Measured on the resumed runs of #1080 / #1085 / #1147 / #1197: a merge of the default branch
@@ -142,7 +140,7 @@ function describes_base(stamp: FileMapStamp, base: string | undefined): boolean
 //
 // **It says nothing about two maps read against different bases.** It takes the union of the key
 // sets, so a path only one of them covers is reported as changed — a set difference, not an edit.
-// Callers guard that with `describes_base` above (joshuafolkken/kit#1537).
+// Callers guard that with `describes_base` above.
 function changed_since(stamp: FileMapStamp, tree: Record<string, string>): ReadonlyArray<string> {
 	const names = new Set([...Object.keys(stamp.files), ...Object.keys(tree)])
 
@@ -153,17 +151,17 @@ function changed_since(stamp: FileMapStamp, tree: Record<string, string>): Reado
 
 interface FileMapStampAccess {
 	stamp_path: () => string
-	// `base` is written by the one record that is acted on rather than merely reported —
-	// joshuafolkken/kit#1328's green-gate reuse. The others omit it and are unaffected.
+	// `base` is written by the one record that is acted on rather than merely reported — the
+	// green-gate reuse. The others omit it and are unaffected.
 	write: (files: Record<string, string>, target?: string, base?: string) => string
-	// Marks an existing record as belonging to a run that finished (joshuafolkken/kit#1164). It
+	// Marks an existing record as belonging to a run that finished. It
 	// amends rather than rewrites, and answers `undefined` where there is no record to amend: a run
 	// whose record never got written has nothing to assert a completion about, and inventing one here
 	// would manufacture the very vouching the field exists to withhold.
 	complete: (target?: string) => string | undefined
 	read: (source?: string) => FileMapStamp | undefined
-	// For a record whose meaning is its existence rather than its contents — the in-flight gate marker
-	// (joshuafolkken/kit#1242). A record nobody removes would go on asserting a gate that ended.
+	// For a record whose meaning is its existence rather than its contents — the in-flight gate marker.
+	// A record nobody removes would go on asserting a gate that ended.
 	remove: (target?: string) => void
 }
 
@@ -186,7 +184,7 @@ function read_at(source: string): FileMapStamp | undefined {
 // Amending is the whole point, and re-writing would defeat it: `write` stamps a fresh `taken_at` and
 // takes a fresh file map, so calling it again at the end of a run would claim the tree as the run
 // *left* it was the tree the run measured — the record would then vouch for a comparison of that
-// tree against itself, which is the one answer it exists to withhold (joshuafolkken/kit#1164).
+// tree against itself, which is the one answer it exists to withhold.
 //
 // **It completes only a record this process wrote**, which the `pid` already in the payload is what
 // says. The path is deterministic per checkout, so a second whole-suite run started beside the first
@@ -199,7 +197,7 @@ function read_at(source: string): FileMapStamp | undefined {
 // deliberate but total-by-assumption: a field added to `write` without a matching entry in
 // `parse_stamp` and `optional_fields` would be dropped by any `complete`, so the two are extended
 // together.
-// **The pid is not the whole of that check either** (joshuafolkken/kit#1245). A record left behind by
+// **The pid is not the whole of that check either**. A record left behind by
 // a run that was killed, whose pid this process was later handed, passes `pid === process.pid` — and
 // stamping it would describe that dead run as finished, which is the false `skip` the field exists to
 // prevent, reached from a third direction. `is_writer_gone` is the added half rather than
@@ -232,8 +230,7 @@ function create(prefix: string, root?: string): FileMapStampAccess {
 		stamp_path: resolve,
 		// `base` goes into the payload undefined and all — `JSON.stringify` drops an undefined value,
 		// so a caller that has no base writes exactly the record it wrote before this field existed.
-		// `own_fields` is what writes the pid, and since joshuafolkken/kit#1245 the writing process's
-		// start time beside it — assembled in one place so no record can carry half an identity.
+		// `own_fields` is what writes the pid, and the writing process's start time beside it — assembled in one place so no record can carry half an identity.
 		write: (files, target = resolve(), base?: string) =>
 			stamp_file.write_stamp(target, {
 				taken_at: new Date().toISOString(),

package/scripts/josh/hook-decision.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import type { GuardedCall } from '#scripts/time-runtime/time-batch-guard'
 import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
 import { time_hook_transcript } from '#scripts/time-runtime/time-hook-transcript'
@@ -5,10 +6,10 @@ import { z } from 'zod'
 import { josh_environment_file } from './josh-environment-file'
 import { stamp_file } from './stamp-file'
 
-// The parts every refusing `PreToolUse` hook needs, held once (joshuafolkken/kit#1460).
+// The parts every refusing `PreToolUse` hook needs, held once.
 //
 // **It exists because the second such hook arrived.** `batch-guard.ts` was the first
-// (joshuafolkken/kit#1390) and carried the whole shell itself: the payload schema, the envelope
+//  and carried the whole shell itself: the payload schema, the envelope
 // Claude Code understands, the environment switch, and the stamp that makes a refusal
 // unrepeatable. The investigation guard needs all four unchanged and only its *rule* differs, so
 // copying them across would be the clone `CLAUDE.md` prohibits — and a rule fixed in one copy and
@@ -20,7 +21,7 @@ import { stamp_file } from './stamp-file'
 // Only the four fields a `PreToolUse` hook is handed and reads. Claude Code names the tool it is
 // about to run beside a transcript path, so nothing is searched for.
 //
-// **`agent_id` is what makes a delegated unit answerable with its own file** (joshuafolkken/kit#1424).
+// **`agent_id` is what makes a delegated unit answerable with its own file**.
 // The path in the payload is the *parent* session's whichever agent issued the call, so without this
 // field a guard judges the parent's frozen timeline and refuses nothing at all inside a fork.
 const payload_schema = z.object({
@@ -58,7 +59,7 @@ function is_switch_enabled(key: string): boolean {
 // The opt-in counterpart of `DISABLED_VALUES`: an unset variable stays off, and only one of these
 // spellings turns the switch on. A switch that must default off cannot be read with `is_switch_enabled`
 // — that one defaults on — so the value list is spelled out here rather than inverted at the call site,
-// keeping a typo from silently enabling what was meant to stay disabled (joshuafolkken/kit#2370).
+// keeping a typo from silently enabling what was meant to stay disabled.
 const ENABLED_VALUES: ReadonlyArray<string> = ['on', '1', 'true', 'yes']
 
 // Read at call time for the same reason as `is_switch_enabled`, so a suite that switches the variable
@@ -85,7 +86,7 @@ function deny_envelope(reason: string): string {
 	})
 }
 
-// **A rewrite, not a refusal** (joshuafolkken/kit#3154): the call proceeds with `updated_input` merged
+// **A rewrite, not a refusal**: the call proceeds with `updated_input` merged
 // over its own. `allow` is the decision the harness applies an `updatedInput` under; a settings `deny`
 // rule still wins over it, so this never widens what the call may do.
 function rewrite_envelope(updated_input: Record<string, unknown>, context: string): string {
@@ -126,7 +127,7 @@ function stamp_fault(switch_key: string): string {
 // anything is written under it, so a fork's first guarded calls read a path with no file behind it —
 // `time-hook-transcript.ts` states that "no history" is the honest verdict there. Reported as a fault
 // it would print on every early call of every fork, which is the routine case drowning the signal this
-// exists to raise (joshuafolkken/kit#1509).
+// exists to raise.
 function is_missing_file(error: unknown): boolean {
 	if (!(error instanceof Error) || !('code' in error)) return false
 
@@ -168,11 +169,7 @@ function last_refusal_ms(target: string): number {
 
 	if (raw === undefined) return NEVER_MS
 
-	try {
-		return refusal_schema.parse(JSON.parse(raw)).refused_at_ms
-	} catch {
-		return NEVER_MS
-	}
+	return json_value.parse_with(raw, refusal_schema)?.refused_at_ms ?? NEVER_MS
 }
 
 function record_refusal(target: string, now_ms: number): boolean {
@@ -199,7 +196,7 @@ function create_refusal_stamp(prefix: string): RefusalStamp {
 // **`.env` is loaded here rather than through the dispatcher's `tsx_arguments`**, and the reason —
 // declaring any `tsx_arguments` disqualifies a command from in-process dispatch — is now shared with
 // every other command that has to stay in-process, so the loader lives in `josh-environment-file.ts` rather
-// than here (joshuafolkken/kit#1491). Re-exported under this namespace because that is where the
+// than here. Re-exported under this namespace because that is where the
 // hooks reach for it.
 //
 // **Call it only on the real hook path**, never inside the pure refusal function, so a developer's
@@ -217,7 +214,7 @@ interface GuardRun {
 }
 
 // The notice half of a guard's rule, kept optional so a guard that only refuses supplies nothing and is
-// untouched (joshuafolkken/kit#1848). The investigation guard omits it; the batching guard supplies one
+// untouched. The investigation guard omits it; the batching guard supplies one
 // for the whole-file write, which it cannot refuse but can advise.
 interface NotifySpec {
 	// This disposition's record prefix, distinct from the refusal's so the two dedupe independently and
@@ -226,8 +223,8 @@ interface NotifySpec {
 	// The same shape as `should_block`, asked of the tail for a notify-only call. `notified_at_ms` is
 	// this disposition's own last-fired instant, never the refusal's.
 	should_notify: (tail: string, call: GuardedCall, notified_at_ms: number, run: GuardRun) => boolean
-	// The non-blocking text handed to `notice_envelope`, chosen from the call and the tail
-	// (joshuafolkken/kit#2164, joshuafolkken/kit#2276). A guard now notifies about more than one kind of
+	// The non-blocking text handed to `notice_envelope`, chosen from the call and the tail.
+	// A guard now notifies about more than one kind of
 	// call — the whole-file write it cannot refuse, and, in a lane child, a refusable call whose refusal
 	// is downgraded to a notice — and the two want different wording, so the text is a function of the
 	// call. It is handed the tail as well so a notice can name the concrete calls the run just issued
@@ -252,18 +249,18 @@ interface TranscriptGuardSpec {
 	should_block: (tail: string, call: GuardedCall, refused_at_ms: number, run: GuardRun) => boolean
 	// What the model is told. The deny reason is the only text that reaches it.
 	reason: string
-	// **The optional notice disposition** (joshuafolkken/kit#1848). Supplied, it lets a guard emit a
+	// **The optional notice disposition**. Supplied, it lets a guard emit a
 	// non-blocking notice for a call it does not refuse. Its record lives under a prefix of its own.
 	notify?: NotifySpec
 }
 
-// What one hook invocation decided. **`fault` is the half that did not exist** (joshuafolkken/kit#1509):
+// What one hook invocation decided. **`fault` is the half that did not exist**:
 // every failure still allows the call, but a failure that nobody can see is indistinguishable from a
 // run that was batching properly — so the guard could be dead for two hours and read as satisfied.
 // `reason` refuses; `fault` allows and says so.
 interface GuardOutcome {
 	reason: string | undefined
-	// **A notice, not a refusal** (joshuafolkken/kit#1848). Set where a notify-only call — a whole-file
+	// **A notice, not a refusal**. Set where a notify-only call — a whole-file
 	// write — reached the limit; the call still proceeds, and `notice_envelope` carries this to the
 	// model and the person with no `permissionDecision`. Never set together with `reason`: the block
 	// path decides first and returns before the notice path is asked.
@@ -287,7 +284,7 @@ interface FireResult {
 
 // The three the guard closes over: the spec, and one record per disposition. Bundled so the functions
 // below stay within the parameter limit, and so a further disposition adds a field rather than a
-// parameter to every one of them (joshuafolkken/kit#1848).
+// parameter to every one of them.
 interface GuardParts {
 	spec: TranscriptGuardSpec
 	stamp: RefusalStamp
@@ -306,7 +303,7 @@ interface GuardContext extends GuardParts {
 // cannot repeat on the call in hand. **Recording before firing is what makes a refusal unrepeatable**,
 // so a disposition that cannot record does not fire — it reports the fault instead of risking the
 // wedge, which is the half `scripts/hooks/batch-guard.ts` names. Shared by the refusal and the notice so the
-// arm-then-fire order is written once (joshuafolkken/kit#1848).
+// arm-then-fire order is written once.
 function fire_once(
 	stamp: RefusalStamp,
 	run: GuardRun,
@@ -367,7 +364,7 @@ function guard_reason_for_payload(
 	if (!parts.spec.is_candidate(call)) return NO_OUTCOME
 
 	// A hook firing inside a delegated unit is handed the *parent's* path, so the fork's own file is
-	// derived here rather than judged from the parent's frozen timeline (joshuafolkken/kit#1424).
+	// derived here rather than judged from the parent's frozen timeline.
 	const transcript = time_hook_transcript.transcript_of(payload.transcript_path, payload.agent_id)
 	const tail = time_density_hook.read_tail(transcript)
 	const context = { ...parts, tail, call, run: { transcript, now_ms } }
@@ -393,7 +390,7 @@ function guard_outcome(parts: GuardParts, raw_payload: string, now_ms: number):
 function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 	const stamp = create_refusal_stamp(spec.prefix)
 	// A record of its own for the notice, only where a notify spec is supplied. Keyed on its own prefix
-	// so a notice never spends the refusal's stamp (joshuafolkken/kit#1848).
+	// so a notice never spends the refusal's stamp.
 	const notify_stamp = spec.notify ? create_refusal_stamp(spec.notify.prefix) : undefined
 	const parts = { spec, stamp, notify_stamp }
 
@@ -410,7 +407,7 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 	// same reason `format-edited-file.ts` swallows a formatter it could not start: a hook that failed
 	// closed would stop a run over its own plumbing.
 	//
-	// **What changed is that it no longer does so in silence** (joshuafolkken/kit#1509). The call still
+	// **What changed is that it no longer does so in silence**. The call still
 	// goes through — failing open is the right call and is not being revisited — but the fault comes
 	// back as text the run can see, so "the guard said nothing" and "the guard could not look" stop
 	// being the same observation.
@@ -430,8 +427,8 @@ function create_transcript_guard(spec: TranscriptGuardSpec): TranscriptGuard {
 }
 
 // Write one already-resolved outcome, so a caller that has to await its rule (the watcher guard reads
-// the lane registry and the life record) can compute the outcome first and hand it here
-// (joshuafolkken/kit#2353). Nothing reaches stdout on the ordinary call, so what the harness parses
+// the lane registry and the life record) can compute the outcome first and hand it here.
+// Nothing reaches stdout on the ordinary call, so what the harness parses
 // stays empty unless the call is being refused.
 function emit_outcome(outcome: GuardOutcome): void {
 	const { reason, notice, fault } = outcome
@@ -453,9 +450,8 @@ function write_outcome(raw_payload: string, outcome: (raw: string) => GuardOutco
 // wrapper rather than a second implementation, so both paths write the same envelopes.
 //
 // **A guard still calling this discards any fault it raised** — `investigation-guard.ts` is the one
-// that does, so a stamp it could not write there is still silent. That is the same gap
-// joshuafolkken/kit#1509 closed for the batching guard, left standing deliberately: this Issue's
-// subject is the batching guard, and moving another hook across belongs with its own test.
+// that does, so a stamp it could not write there is still silent — the gap the batching guard no
+// longer has. Moving another hook across belongs with its own test.
 function write_decision(raw_payload: string, refusal: (raw: string) => string | undefined): void {
 	write_outcome(raw_payload, (raw) => ({
 		reason: refusal(raw),

package/scripts/josh/josh-command-map.ts

@@ -37,6 +37,7 @@ const ALIASES: Record<string, string> = {
 	lr: 'lint:related',
 	ln: 'lines',
 	by: 'bytes',
+	mt: 'metrics',
 	f: 'format',
 	sd: 'cspell:dot',
 	bh: 'behavior',
@@ -80,10 +81,12 @@ const ALIASES: Record<string, string> = {
 	ev: 'eval',
 	lsm: 'lane:sample',
 	lst: 'lane:stats',
+	lli: 'lane:limit',
+	blr: 'backlogrun',
 }
 
 // The canonical name of a `josh` subcommand: an alias expands, and anything else passes through
-// unchanged (joshuafolkken/kit#1789).
+// unchanged.
 //
 // **The expansion is one rule, so it lives beside the table it reads.** Two readers had each written
 // their own `ALIASES[name] ?? name` — the layer report and the gate-run count — and a third, the run

package/scripts/josh/josh-command-types.ts

@@ -6,9 +6,9 @@ import { ENV_FILE_NAME } from '#ports'
 //
 // **There is no mandatory counterpart any more.** `--env-file=.env` aborts before the script's first
 // line when the file is missing, which is wrong for every command kit ships: `doctor` runs from
-// anywhere, including a directory with no project at all (joshuafolkken/kit#869), and `notify` /
+// anywhere, including a directory with no project at all, and `notify` /
 // `followup` run in cloud sessions that carry their credentials as environment variables and keep no
-// `.env` at all (joshuafolkken/kit#1564). A command that needs a value to be present says so itself,
+// `.env` at all. A command that needs a value to be present says so itself,
 // where it can name what is missing.
 const OPTIONAL_ENV_FILE_FLAGS: ReadonlyArray<string> = [`--env-file-if-exists=${ENV_FILE_NAME}`]
 
@@ -17,7 +17,7 @@ type CommandCategory =
 
 // The two vocabularies are runtime tuples the types are derived from, rather than bare unions. A
 // union exists only at compile time, so the completeness test and the generated reference
-// (joshuafolkken/kit#2064) would each have to restate the values to check or render them — two
+//  would each have to restate the values to check or render them — two
 // copies that drift apart silently. Deriving the type from the tuple keeps one definition.
 const COMMAND_AUDIENCES = ['developer', 'maintainer', 'automation'] as const
 const COMMAND_SIDE_EFFECTS = [
@@ -57,42 +57,43 @@ interface CommandEntry {
 	// A command that only makes sense inside the kit repository itself — the rule-compliance eval and
 	// the run measurements that analyze kit's own development. It is dropped from a consumer's
 	// `josh --help` and refused with guidance when run in a consumer project, so a distributed help
-	// listing carries only what a consumer can run (joshuafolkken/kit#1988). The audience in
+	// listing carries only what a consumer can run. The audience in
 	// `reference` separately decides whether the command appears in the default listing.
 	is_kit_only?: boolean
 	// Pre-built to `dist/commands/` so a consumer's `dist/josh.js` imports it in its own process
-	// instead of spawning tsx for it (joshuafolkken/kit#3328, `docs/maintainers/runtime-bundling.md`).
+	// instead of spawning tsx for it (`docs/maintainers/runtime-bundling.md`).
 	is_bundled?: boolean
-	// The cores the command reserves from the machine-wide budget before it starts its heavy tools
-	// (joshuafolkken/kit#3345). `josh-logic.ts` claims them at the one dispatch point every command
+	// The cores the command reserves from the machine-wide budget before it starts its heavy tools.
+	// `josh-logic.ts` claims them at the one dispatch point every command
 	// passes through, so the command only declares the number. A function means the weight is read
 	// when the command starts: the unit suite's share depends on what else is running at that moment.
 	// **The edit hook declares none, on purpose.** It formats one file per edit and finishes in well
 	// under a second, so a wait for room on the machine would stall every edit for the length of
 	// another lane's check.
 	core_weight?: number | (() => number)
+	// The memory the command's tools hold, claimed with its cores; read like
+	// `core_weight`, and none declared is none waited for.
+	memory_mb?: number | (() => number)
 }
 
 // The name `josh gate` registers under. It lives here rather than in `verification-gate.ts` so a
 // consumer of the name — the command map, `propagate` — does not import the script module: that
 // module carries a `process.argv[1] === import.meta.url` main guard, and esbuild bundles every
-// import into one `dist/josh.js` where that guard matches on *any* `josh` invocation
-// (joshuafolkken/kit#914).
+// import into one `dist/josh.js` where that guard matches on *any* `josh` invocation.
 const GATE_COMMAND = 'gate'
 
-// joshuafolkken/kit#1256: three of the gate's four checks keep a content-addressed cache, so a
-// second run reads only what changed. eslint had one from the start; the type check and the spell
-// check rescanned the whole tree every time, which cost 10.5s of CPU against 2.8s cached.
+// Three of the gate's four checks keep a content-addressed cache, so a second run reads only what
+// changed.
 //
-// Neither of those two needs an invalidation rule of its own. `tsc` records the compiler options
-// inside the build-info file and re-checks everything when they differ, and `cspell` records a
-// content hash of every config and dictionary file it loaded as that entry's dependency — so editing
+// Neither the type check nor the spell check needs an invalidation rule of its own. `tsc` records
+// the compiler options inside the build-info file and re-checks everything when they differ, and
+// `cspell` records a content hash of every config and dictionary file it loaded as that entry's dependency — so editing
 // `tsconfig.json` or `cspell.config.yaml` invalidates what it should. CI restores only the eslint
 // cache (`.github/workflows/ci.yml` → "Setup ESLint cache"); the other two start every run cold.
 //
-// **eslint's does need one, and it is not here** (joshuafolkken/kit#1347). ESLint hashes the
-// *serialized* config, which drops every rule's `create`, so editing `eslint/rules/*.js` left every
-// cached entry valid on every cache file below. The fix is a content fingerprint of the rule modules
+// **eslint's does need one, and it is not here**. ESLint hashes the
+// *serialized* config, which drops every rule's `create`, so editing `eslint/rules/*.js` would leave
+// every cached entry valid on every cache file below. The answer is a content fingerprint of the rule modules
 // carried in the shared config's `settings` — `eslint/config-fingerprint.js` — because one value
 // there invalidates the gate's cache, the scoped one and the edit hook's at once, while a rule
 // written per cache file would have to be repeated for each and would go stale one file at a time.
@@ -150,10 +151,9 @@ const SHARED_CACHE_SPECS: ReadonlyArray<GateCacheSpec> = [
 ]
 const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => spec.cache_file)
 
-// joshuafolkken/kit#1332: the `PostToolUse` edit hook runs eslint too, and ESLint *deletes* the file
-// at `--cache-location` whenever it is started without `--cache` — so every single edit wiped the
-// cache the gate had just filled, and both gates of run joshuafolkken/kit#1326 paid a cold lint
-// (59.4s and 54.5s, against 3.0s warm). The hook is given a location of its own rather than the
+// The `PostToolUse` edit hook runs eslint too, and ESLint *deletes* the file at `--cache-location`
+// whenever it is started without `--cache` — so a shared file would be wiped by every single edit,
+// leaving the gate a cold lint. The hook is given a location of its own rather than the
 // gate's because the two run at the same time: `josh gate` lints the whole tree beside the review
 // while this hook fires on every edit, and each eslint run rewrites its cache file whole from the
 // copy it loaded at start-up — so two writers silently discard each other's entries. A file of its
@@ -162,18 +162,16 @@ const GATE_CACHE_FILES: ReadonlyArray<string> = GATE_CACHE_SPECS.map((spec) => s
 // **Pruning is not the reason**, though it reads like one: `file-entry-cache` defaults `noPrune` to
 // true, and a single-file run against the gate's full cache was measured byte-identical, so a shared
 // file would keep the entries that run never visited.
-// joshuafolkken/kit#1347: the same reasoning, reached a second time. `josh lint:related` is what an
-// implementation loop calls between edits, and `josh gate` lints the whole tree beside the review —
-// so those two run at the same time as readily as the hook and the gate do, and they shared one file
-// until this constant existed. Whichever of the pair wrote last replaced the file with "the copy I
-// loaded at start-up plus what I visited", so a narrowed run finishing during a whole-tree run rolled
-// the cache back to its pre-gate state, and a whole-tree run finishing second discarded the narrowed
-// one's entries.
+// The same reasoning for the scoped lint. `josh lint:related` is what an implementation loop calls
+// between edits, and `josh gate` lints the whole tree beside the review — so those two run at the
+// same time as readily as the hook and the gate do. Whichever of a pair sharing one file wrote last
+// would replace it with "the copy I loaded at start-up plus what I visited", so a narrowed run
+// finishing during a whole-tree run would roll the cache back to its pre-gate state, and a
+// whole-tree run finishing second would discard the narrowed one's entries.
 //
-// **The warming this gives up is worth less than the entries it stops losing.** The comment this
-// replaced argued the shared file let a narrowed run warm the gate's cache, which is true only while
-// the two never overlap; a file of its own is warm from its own second call onwards, and the gate's
-// stays exactly as the gate left it.
+// **The warming this gives up is worth less than the entries it stops losing.** A shared file would
+// let a narrowed run warm the gate's cache only while the two never overlap; a file of its own is
+// warm from its own second call onwards, and the gate's stays exactly as the gate left it.
 //
 // **The lint's target scope is untouched.** This is where a cache is written, not what is read:
 // `josh lint:related` narrows in front of the gate and `josh gate` still runs `josh lint` over the
@@ -209,7 +207,7 @@ const CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE)
 
 export type { CommandCategory, CommandEntry, GateCacheSpec }
 // The three cache files are exported one by one as well as as a list, because `josh bench` clears
-// them per target (joshuafolkken/kit#1314): the lint step writes only the eslint one, so a target
+// them per target: the lint step writes only the eslint one, so a target
 // that cleared the list would report a cold type check as the lint's own cost. The edit hook's cache
 // stays private; the scoped lint cache is exported because #2060 shares its completed file between
 // worktrees, but it still never overlaps the gate's distinct cache location.

package/scripts/josh/josh-commands-ai.ts

@@ -77,12 +77,12 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['[options]', 'maintainer', ['none']],
 		// Kit-only: it measures kit's own development runs and its report modules live under the
 		// undistributed `scripts/time/`, so it means nothing in a consumer project and is dropped from a
-		// consumer's help (joshuafolkken/kit#1997). The runtime analysis hooks and guards rely on stays
+		// consumer's help. The runtime analysis hooks and guards rely on stays
 		// distributed under `scripts/time-runtime/`.
 		is_kit_only: true,
 	},
 	// The tool-calls-per-round-trip density the batching guard is measured on, aggregated across the
-	// recent lane sessions (joshuafolkken/kit#2405). Kit-only for the same reason `time` is: it reads
+	// recent lane sessions. Kit-only for the same reason `time` is: it reads
 	// kit's own lane transcripts and means nothing in a consumer project.
 	'time:density': {
 		script: 'scripts/time/time-density-cli.ts',
@@ -99,7 +99,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'maintainer', ['none']],
 		// Kit-only: it reads kit's own development run — the transcript store, the review ledger and the
 		// run event stream — so it means nothing in a consumer project and is dropped from a consumer's
-		// help (joshuafolkken/kit#2328), through the same declaration `josh time` uses for the same reason.
+		// help, through the same declaration `josh time` uses for the same reason.
 		is_kit_only: true,
 	},
 	'review:brief': {
@@ -156,7 +156,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[--join]', 'automation', ['processes', 'files']],
 	},
-	// The post-merge sequence a run closed on, folded into one call (joshuafolkken/kit#2372): commit the
+	// The post-merge sequence a run closed on, folded into one call: commit the
 	// observation ledger, read the completion citations and decide the release scope. `observations:flush`,
 	// `issue:cite` and `release:scope` were three round trips re-billing the run's full context each.
 	'run:tail': {
@@ -166,7 +166,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[<issue> ...]', 'automation', ['git', 'network']],
 	},
-	// The commit-to-report region a run ships a change on, folded into one call (joshuafolkken/kit#2398):
+	// The commit-to-report region a run ships a change on, folded into one call:
 	// the gate, the commit/push/PR (`git -y`), the CI-wait merge (`followup`) and the report bookkeeping
 	// (`run:tail`) were four round trips re-billing the run's full context each. It stops at the first
 	// failed step and names it, so the run reads only the step to fix.
@@ -231,7 +231,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['[scenario...]', 'maintainer', ['processes', 'network']],
 		// Kit-only: it replays kit's own distributed rules against real Claude sessions, so it means
-		// nothing in a consumer project and is dropped from a consumer's help (joshuafolkken/kit#1988).
+		// nothing in a consumer project and is dropped from a consumer's help.
 		is_kit_only: true,
 	},
 }

package/scripts/josh/josh-commands-backlog.ts

@@ -1,12 +1,24 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
 // The `backlog:*` command registry, split out of `josh-commands-ai.ts` so that file stays under its
-// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason
-// (joshuafolkken/kit#2162, joshuafolkken/kit#2218). It is spread into `AI_COMMANDS` so the commands
+// 300-code-line limit, exactly as `LANE_COMMANDS` and `SPLIT_COMMANDS` were for the same reason.
+// It is spread into `AI_COMMANDS` so the commands
 // stay grouped with the other AI tools under the 'AI tools' category.
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
+	// Started from a terminal: the `backlogrun` keyword's launcher, and the board.
+	backlogrun: {
+		script: 'scripts/backlog/backlogrun-cli.ts',
+		description:
+			'Start a backlogrun in the background and show its board; with one already running, only show the board',
+		category: 'AI tools',
+		reference: [
+			'[#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]',
+			'developer',
+			['files', 'network', 'processes'],
+		],
+	},
 	'backlog:next': {
 		script: 'scripts/backlog/backlog-next.ts',
 		description:
@@ -41,7 +53,7 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'backlog:stalled': {
 		script: 'scripts/backlog/backlog-stalled-cli.ts',
-		// A stall sends one Telegram warning (joshuafolkken/kit#3357). The `Stop` hook calls the detector
+		// A stall sends one Telegram warning. The `Stop` hook calls the detector
 		// directly, so this flag costs only the manual command its in-process dispatch.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:

package/scripts/josh/josh-commands-clone.ts

@@ -1,7 +1,7 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The clone-detection commands, kept in their own module so `josh-commands-ai.ts` stays under its
-// line ceiling as the AI-tools set grows (joshuafolkken/kit#2217). Spread into `COMMAND_MAP` in
+// line ceiling as the AI-tools set grows. Spread into `COMMAND_MAP` in
 // `josh-command-map.ts` alongside the other command groups.
 /* eslint-disable @typescript-eslint/naming-convention */
 const CLONE_COMMANDS: Record<string, CommandEntry> = {