@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/backlog/backlogrun-launch.ts

@@ -172,6 +172,29 @@ function started_for(git_directory: string, owner_pid: number | undefined): Date
 	return Number.isNaN(started_ms) ? undefined : new Date(started_ms)
 }
 
+function signal_parent(pid: number): void {
+	try {
+		process.kill(pid, 'SIGTERM')
+	} catch {
+		note_to_stderr(`process ${String(pid)} could not be signalled; its launch record is removed.`)
+	}
+}
+
+// Stops the parent this launcher started and forgets its launch — the pid stopped, `undefined` where
+// no launched parent was live. **Only the process the record names, and only while it is still that
+// process**: a session a person typed `backlogrun` into has no launch record and is never signalled.
+function stop_parent(git_directory: string): number | undefined {
+	const record = live_launch(git_directory)
+
+	stamp_file.remove_stamp(launch_path(git_directory))
+
+	if (record === undefined) return undefined
+
+	signal_parent(record.pid)
+
+	return record.pid
+}
+
 // The headless mark holds the parent's turn open while its lanes run, as `run:wake`'s does. The launch
 // strips only Claude's session keys, so a Codex session this was typed in is cleared here too — inherited,
 // it would make the parent's own `josh` commands resolve the wrong provider.
@@ -223,6 +246,7 @@ const backlogrun_launch = {
 	pending_launch,
 	start,
 	started_for,
+	stop_parent,
 }
 
 export type { Launched, LaunchTarget, PendingLaunch, StartResult }

package/scripts/backlog/backlogrun-replace.ts

@@ -0,0 +1,166 @@
+import { lane_spent, type LaneUse } from '#scripts/lane/lane-spent'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { backlog_drive_retrospective } from './backlog-drive-retrospective'
+import { backlogrun_launch } from './backlogrun-launch'
+
+// Whether `josh backlogrun` may replace the run already going with the one just typed. A run that
+// drained its backlog keeps watching for hours with nothing in flight, and starting another meant typing
+// `--stop` first; this is the test that lets the start do both.
+//
+// **A different invocation, a watching run, no lane in use — all three.** The same invocation is how a
+// person reopens the board, so it never rebuilds the run. A run still starting is opening a lane, and a
+// child killed mid-change leaves a tree nobody can resume, so only a run past its drain is replaced.
+//
+// **Only a lane a child is working in keeps the run.** A lane a past run left behind has nobody in it;
+// counted as open, it kept every later invocation from replacing the run (`lane-spent.ts`).
+//
+// **A drain that still owes the retrospective is not the watch.** The drain is marked before the
+// end-of-run retrospective runs, so a run owing one has a session at work on it; stopping that session
+// loses the retrospective with the record, and the run is kept until it has run.
+//
+// **An undetermined run is not replaced.** A record or a scope that cannot be read answers `keep`, the
+// side that keeps the run.
+//
+// **A launch its parent has not claimed yet is still starting, not unreadable.** No carry record stands
+// then, so the invocation is read from the launch record: the same one is the board reopened, and any
+// other is kept as a run that has not written its record yet.
+//
+// **A kept run says why.** Every `keep` carries the one condition that held it, because a board shown
+// with no word looked the same whichever of them it was.
+
+const KIND = run_event_stream.EVENT_KIND
+const NOT_FOUND = -1
+const ISSUE_PREFIX = '#'
+const UNREADABLE_REASON = "the run's record could not be read"
+const UNCLAIMED_REASON = 'the run is still starting: it has not written its record yet'
+const WORKING_LANE = 'a child is still working in the lane for'
+const UNREAD_LANE = 'whether a child is working could not be read in the lane for'
+const LANE_WAY_OUT = '(`pnpm josh lane:close <N>` discards a lane)'
+const RETROSPECTIVE_REASON = 'the run still owes its retrospective'
+const WORKING_REASON = 'the run is not watching: it is still starting or has a child at work'
+
+// `same` is the board reopened, which is kept without a word; `keep` is a refusal, and says why.
+type ReplaceVerdict = { kind: 'replace' } | { kind: 'same' } | { kind: 'keep'; reason: string }
+
+const REPLACE: ReplaceVerdict = { kind: 'replace' }
+const SAME: ReplaceVerdict = { kind: 'same' }
+
+interface ReplacePorts {
+	read_carry: (git_directory: string) => CarryRead
+	events: (git_directory: string) => ReadonlyArray<RunEvent>
+	is_retrospective_owed: (carry: RunCarry) => boolean
+	// The invocation of a launch whose parent has not claimed the record yet.
+	pending_invocation: (git_directory: string) => string | undefined
+	// The lanes in use: a child working in one, or a probe that did not answer.
+	lanes: () => Promise<LaneUse>
+}
+
+const LIVE_PORTS: ReplacePorts = {
+	read_carry: (git_directory) => run_carry.read_carry(run_carry.carry_path(git_directory)),
+	events: (git_directory) =>
+		run_event_stream.read_events(run_event_stream.target_of(git_directory)),
+	is_retrospective_owed: backlog_drive_retrospective.is_owed,
+	pending_invocation: (git_directory) =>
+		backlogrun_launch.pending_launch(git_directory)?.invocation,
+	lanes: async () => await lane_spent.lanes_in_use(),
+}
+
+function keep(reason: string): ReplaceVerdict {
+	return { kind: 'keep', reason }
+}
+
+// What the record alone settles, or `undefined` for a different invocation that owes nothing.
+function record_verdict(
+	invocation: string,
+	read: CarryRead,
+	ports: ReplacePorts,
+): ReplaceVerdict | undefined {
+	if (read.kind !== 'carried') return keep(UNREADABLE_REASON)
+	if (read.carry.invocation === invocation) return SAME
+
+	return ports.is_retrospective_owed(read.carry) ? keep(RETROSPECTIVE_REASON) : undefined
+}
+
+// A launch with no carry record yet, answered from the launch record.
+function unclaimed_verdict(pending: string | undefined, invocation: string): ReplaceVerdict {
+	return pending === invocation ? SAME : keep(UNCLAIMED_REASON)
+}
+
+// Watching is the run's newest drain with no launch after it: a child the watch woke for ends it.
+function is_watching(scoped: ReadonlyArray<RunEvent>): boolean {
+	const drained_at = scoped.findLastIndex((event) => event.kind === KIND.DRAIN)
+
+	if (drained_at === NOT_FOUND) return false
+
+	return scoped.slice(drained_at).every((event) => event.kind !== KIND.CHILD_LAUNCH)
+}
+
+function watch_verdict(
+	git_directory: string,
+	read: CarryRead,
+	ports: ReplacePorts,
+): ReplaceVerdict {
+	const events = ports.events(git_directory)
+	const scoped = run_event_scope.scoped_events(events, run_event_scope.scope_of(read))
+
+	if (scoped === undefined) return keep(UNREADABLE_REASON)
+
+	return is_watching(scoped) ? REPLACE : keep(WORKING_REASON)
+}
+
+function named(lead: string, issues: ReadonlyArray<string>): Array<string> {
+	if (issues.length === 0) return []
+
+	const cited = issues.map((issue) => `${ISSUE_PREFIX}${issue}`).join(' ')
+
+	return [`${lead} ${cited}`]
+}
+
+// The lanes are named with the command that discards one, the only way past a child that will not end —
+// and a probe that did not answer is said as that, because the close takes a lane's uncommitted work.
+function lane_reason(use: LaneUse): string {
+	const parts = [...named(WORKING_LANE, use.working), ...named(UNREAD_LANE, use.unread)]
+
+	return `${parts.join('; ')} ${LANE_WAY_OUT}`
+}
+
+function is_free(use: LaneUse): boolean {
+	return use.working.length === 0 && use.unread.length === 0
+}
+
+async function claimed_verdict(
+	invocation: string,
+	git_directory: string,
+	read: CarryRead,
+	ports: ReplacePorts,
+): Promise<ReplaceVerdict> {
+	const settled =
+		record_verdict(invocation, read, ports) ?? watch_verdict(git_directory, read, ports)
+
+	if (settled.kind !== 'replace') return settled
+
+	const use = await ports.lanes()
+
+	return is_free(use) ? REPLACE : keep(lane_reason(use))
+}
+
+async function decide(
+	invocation: string,
+	git_directory: string,
+	ports: ReplacePorts = LIVE_PORTS,
+): Promise<ReplaceVerdict> {
+	const read = ports.read_carry(git_directory)
+
+	if (read.kind === 'none') {
+		return unclaimed_verdict(ports.pending_invocation(git_directory), invocation)
+	}
+
+	return await claimed_verdict(invocation, git_directory, read, ports)
+}
+
+const backlogrun_replace = { decide }
+
+export type { ReplacePorts, ReplaceVerdict }
+export { backlogrun_replace }

package/scripts/backlog/backlogrun-stop.ts

@@ -0,0 +1,178 @@
+import { process_identity } from '#scripts/josh/process-identity'
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { run_carry, type CarryRead, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_carry_end } from '#scripts/run/carry/run-carry-end'
+import { run_wake } from '#scripts/run/wake/run-wake'
+import { run_wake_stop } from '#scripts/run/wake/run-wake-stop'
+import { backlogrun_launch } from './backlogrun-launch'
+
+// `josh backlogrun --stop` — the order a `backlogrun` is stopped in, and what is said of it. Each stop
+// is the one its own command already makes (`run:wake --stop`, `run:carry --end --stopped`); only the
+// order is here.
+//
+// **Supervisor, then parent, then record.** A record ended first is one a supervisor or a parent still
+// alive can write back, and a supervisor still watching would wake a session over the run just ended.
+//
+// **Only what `josh backlogrun` started is stopped.** A run a person typed into a session of their own
+// is owned by that session; its record is kept and the owner is named, because ending a record under a
+// live owner leaves a session running lanes nothing counts.
+//
+// **A headless session is the run's own.** Nobody can end the run from it, so when it holds the record
+// it is stopped too. The record says so itself (`is_owner_headless`): the supervisor's record is gone
+// after a `run:wake --stop` or a supervisor that gave up, and the session it woke outlives both.
+//
+// **Lanes are counted, never stopped**: a child killed mid-change leaves a tree nobody can resume.
+
+const STOPPED_REASON = 'stopped by a person with `josh backlogrun --stop`'
+const PREFIX = 'backlogrun:'
+const ISSUE_PREFIX = '#'
+
+type RecordOutcome = { kind: 'none' } | { kind: 'ended' } | { kind: 'held'; owner: number }
+
+interface StopReport {
+	// The pids stopped, `undefined` where there was nothing to stop.
+	supervisor: number | undefined
+	parent: number | undefined
+	// The headless session that held the record.
+	session: number | undefined
+	record: RecordOutcome
+	// The issues whose lanes are still open, left running.
+	lanes: ReadonlyArray<string>
+}
+
+interface StopPorts {
+	stop_supervisor: (git_directory: string) => number | undefined
+	stop_parent: (git_directory: string) => number | undefined
+	stop_session: (pid: number) => void
+	read_carry: (git_directory: string) => CarryRead
+	is_live: (pid: number, start: string | undefined) => boolean
+	end_record: (git_directory: string) => Promise<CarryRead>
+	lanes: () => Promise<Array<string>>
+}
+
+// The issues whose lanes are open — every one a stop leaves on disk, a child in it or not.
+async function open_lanes(): Promise<Array<string>> {
+	const lanes = await lane_registry.list_lanes()
+
+	return lanes.filter((lane) => !lane.is_stranded).map((lane) => lane.issue)
+}
+
+// A person who typed the stop is at the terminal, so the ⏸️ confirmation a stop pushes is not sent.
+const LIVE_PORTS: StopPorts = {
+	stop_supervisor: (git_directory) => run_wake_stop.stop(run_wake.wake_path(git_directory))?.pid,
+	stop_parent: backlogrun_launch.stop_parent,
+	stop_session: run_wake_stop.signal,
+	read_carry: (git_directory) => run_carry.read_carry(run_carry.carry_path(git_directory)),
+	is_live: (pid, start) => process_identity.is_same_process(pid, start) !== false,
+	end_record: async (git_directory) =>
+		await run_carry_end.end_run(git_directory, { stopped: STOPPED_REASON, is_announced: false }),
+	lanes: open_lanes,
+}
+
+function live_owner(carry: RunCarry, ports: StopPorts): number | undefined {
+	const { owner_pid, owner_start } = carry
+
+	if (owner_pid === undefined) return undefined
+
+	return ports.is_live(owner_pid, owner_start) ? owner_pid : undefined
+}
+
+// The live owner this command did not just stop.
+function standing_owner(
+	read: CarryRead,
+	stopped: ReadonlyArray<number | undefined>,
+	ports: StopPorts,
+): number | undefined {
+	const owner = read.kind === 'carried' ? live_owner(read.carry, ports) : undefined
+
+	return stopped.includes(owner) ? undefined : owner
+}
+
+function is_headless_owner(read: CarryRead): boolean {
+	return read.kind === 'carried' && read.carry.is_owner_headless === true
+}
+
+// Stops the owner where the record marks it headless — the pid stopped, `undefined` where the owner
+// is any other process, which this command has no business signalling.
+function stop_headless(
+	owner: number | undefined,
+	read: CarryRead,
+	ports: StopPorts,
+): number | undefined {
+	if (owner === undefined || !is_headless_owner(read)) return undefined
+
+	ports.stop_session(owner)
+
+	return owner
+}
+
+async function close_record(
+	git_directory: string,
+	read: CarryRead,
+	holder: number | undefined,
+	ports: StopPorts,
+): Promise<RecordOutcome> {
+	if (read.kind === 'none') return { kind: 'none' }
+	if (holder !== undefined) return { kind: 'held', owner: holder }
+
+	await ports.end_record(git_directory)
+
+	return { kind: 'ended' }
+}
+
+async function stop(git_directory: string, ports: StopPorts = LIVE_PORTS): Promise<StopReport> {
+	const supervisor = ports.stop_supervisor(git_directory)
+	const parent = ports.stop_parent(git_directory)
+	const read = ports.read_carry(git_directory)
+	const owner = standing_owner(read, [supervisor, parent], ports)
+	const session = stop_headless(owner, read, ports)
+	const holder = session === undefined ? owner : undefined
+	const record = await close_record(git_directory, read, holder, ports)
+	const lanes = await ports.lanes()
+
+	return { supervisor, parent, session, record, lanes }
+}
+
+function process_line(what: string, pid: number | undefined): Array<string> {
+	return pid === undefined ? [] : [`${PREFIX} stopped the ${what} (process ${String(pid)})`]
+}
+
+function record_lines(outcome: RecordOutcome): Array<string> {
+	if (outcome.kind === 'none') return []
+	if (outcome.kind === 'ended') return [`${PREFIX} ended the run's record`]
+
+	return [
+		`${PREFIX} process ${String(outcome.owner)} owns the run and was not started by \`josh backlogrun\`; its record is kept — end the run from that session`,
+	]
+}
+
+function lane_lines(lanes: ReadonlyArray<string>): Array<string> {
+	if (lanes.length === 0) return []
+
+	const issues = lanes.map((issue) => `${ISSUE_PREFIX}${issue}`).join(' ')
+
+	return [`${PREFIX} ${String(lanes.length)} lane(s) still running, not stopped: ${issues}`]
+}
+
+// What a person reads back: one line per thing done, or the one line that says nothing was running.
+function lines_of(report: StopReport): Array<string> {
+	const done = [
+		...process_line('supervisor', report.supervisor),
+		...process_line('parent session', report.parent),
+		...process_line('headless session', report.session),
+		...record_lines(report.record),
+	]
+	const stopped = done.length === 0 ? [`${PREFIX} nothing is running`] : done
+
+	return [...stopped, ...lane_lines(report.lanes)]
+}
+
+// A record left with its owner is a run this command did not stop.
+function is_stopped(report: StopReport): boolean {
+	return report.record.kind !== 'held'
+}
+
+const backlogrun_stop = { is_stopped, lines_of, stop }
+
+export type { StopPorts, StopReport }
+export { backlogrun_stop }

package/scripts/behavior/behavior-cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { cost_transcript, type SessionFile } from '#scripts/cost-runtime/cost-transcript'
 import { status_icons } from '#scripts/lib/status-icons'
+import { NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
 import { behavior_assertion, type Violation } from './behavior-assertion'
 import { behavior_rules } from './behavior-rules'
 
@@ -32,8 +33,12 @@ function current_session(cwd: string = process.cwd()): SessionFile | undefined {
 // **A run with no transcript passes, and passes without the skip marker.** The gate reads `—
 // skipping` to withhold its green record; a behavior check that found no transcript — a CI runner has
 // none — has nothing to say about the tree and must not withhold the record the other checks earned.
+// It carries the nothing-to-check marker instead, so the gate's verdict does not count it as a check
+// that ran.
 function report_no_transcript(): number {
-	console.info(`${LABEL}: no recorded transcript to check ${status_icons.PASS_ICON}`)
+	console.info(
+		`${LABEL}: no recorded transcript — ${NOTHING_TO_CHECK_MARKER} ${status_icons.PASS_ICON}`,
+	)
 
 	return PASS_EXIT_CODE
 }

package/scripts/doctor/doctor-io.ts

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { pnpm_reach } from '#scripts/lib/pnpm-reach'
 import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
-import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { COMMAND_TIMEOUT_MS, PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import { doctor_logic } from './doctor-logic'
 
@@ -19,22 +20,45 @@ const AUTO_MERGE_WORKFLOW_PATH = '.github/workflows/dependabot-auto-merge.yml'
 // consumer's own auto-merge workflow which does creates the same one kit's does.
 const AUTO_MERGE_COMMAND = 'gh pr merge --auto'
 const YAML_COMMENT_PREFIX = '#'
+const UNKNOWN_PNPM: PnpmProbe = { state: 'unknown' }
 
-// Resolve the `josh` that the shell would run — the first match on PATH, via the platform's
-// lookup command (`where` on Windows, `which` elsewhere). Undefined when the lookup fails or
-// prints nothing (no `josh` on PATH, e.g. inside the kit repo where only `pnpm josh` runs).
-function resolve_path_josh(): string | undefined {
+// What the platform's lookup command said about a name: whether the command itself could be
+// started, and the first match it printed.
+interface PathLookup {
+	did_run: boolean
+	first_path: string | undefined
+}
+
+// Ask the platform's lookup command (`where` on Windows, `which` elsewhere) for `bin` on PATH.
+function look_up_on_path(bin: string): PathLookup {
 	const lookup = doctor_logic.path_lookup_command(process.platform)
-	const result = execaSync(lookup, [JOSH_BIN], { reject: false })
+	const result = execaSync(lookup, [bin], { reject: false })
+
+	return {
+		did_run: !pnpm_reach.is_not_found(result),
+		first_path: doctor_logic.first_path_line(read_spawn_stdout(result)),
+	}
+}
+
+// Resolve the `josh` that the shell would run — the first match on PATH. Undefined when the lookup
+// fails or prints nothing (no `josh` on PATH, e.g. inside the kit repo where only `pnpm josh` runs).
+function resolve_path_josh(): string | undefined {
+	return look_up_on_path(JOSH_BIN).first_path
+}
+
+// Whether the lookup command ran and found no `bin`. A lookup command that is itself absent proves
+// nothing about `bin`, so it is not an answer.
+function is_off_path(bin: string): boolean {
+	const { did_run, first_path } = look_up_on_path(bin)
 
-	return doctor_logic.first_path_line(read_spawn_stdout(result))
+	return did_run && first_path === undefined
 }
 
 // Resolve the pnpm-global `josh` bin path. Undefined when pnpm is missing or the global bin does
 // not contain a `josh` (kit not installed globally). `pnpm bin -g` prepends a `[WARN]` line to
 // stdout inside a project, so the bin directory is extracted via first_path_line.
 function resolve_pnpm_global_josh(): string | undefined {
-	const result = execaSync('pnpm', ['bin', '-g'], { reject: false })
+	const result = execaSync(pnpm_reach.PNPM, ['bin', '-g'], { reject: false })
 	const bin_directory = doctor_logic.first_path_line(read_spawn_stdout(result))
 	if (bin_directory === undefined) return undefined
 	const candidate = path.join(bin_directory, JOSH_BIN)
@@ -42,6 +66,29 @@ function resolve_pnpm_global_josh(): string | undefined {
 	return existsSync(candidate) ? candidate : undefined
 }
 
+// A spawn that found no executable proves pnpm is off PATH, but Windows never reports one: an
+// unresolved `pnpm` is handed to `cmd.exe`, which starts, prints "'pnpm' is not recognized" and exits
+// 1. So a pnpm that did not answer is also looked up by name, which says the same thing everywhere.
+function is_pnpm_missing(result: { code?: string | undefined }): boolean {
+	return pnpm_reach.is_not_found(result) || is_off_path(pnpm_reach.PNPM)
+}
+
+// Whether this process can start `pnpm`, and which one answers. `josh` runs its checks as
+// `pnpm josh <check>` children, so a `pnpm` this process cannot see fails every one of them before
+// it starts; asking here is what lets a user learn it before a gate does. `missing` is
+// kept apart from `unknown`: a pnpm that is on PATH and failed is a different fault with a
+// different fix.
+function probe_pnpm(): PnpmProbe {
+	const result = execaSync(pnpm_reach.PNPM, ['--version'], {
+		reject: false,
+		timeout: COMMAND_TIMEOUT_MS,
+	})
+	const version = read_spawn_stdout(result).trim()
+	if (version !== '' && result.exitCode === 0) return { state: 'found', version }
+
+	return is_pnpm_missing(result) ? { state: 'missing' } : UNKNOWN_PNPM
+}
+
 // Whether the working directory is provably *outside* a git work tree. Purely local — no network,
 // and it does not depend on `gh` being installed or authenticated, which is what makes it usable to
 // decide whether a repository-scoped check applies at all.
@@ -192,7 +239,11 @@ function has_auto_merge_workflow(start: string, boundary?: string): boolean {
 type GitTopLevel =
 	{ state: 'inside'; top_level: string } | { state: 'outside' } | { state: 'undetermined' }
 
+// What asking `pnpm --version` from this process established.
+type PnpmProbe = { state: 'found'; version: string } | { state: 'missing' } | { state: 'unknown' }
+
 const doctor_io = {
+	probe_pnpm,
 	resolve_path_josh,
 	resolve_pnpm_global_josh,
 	has_distributed_dependabot_config,
@@ -200,5 +251,5 @@ const doctor_io = {
 	resolve_git_top_level,
 }
 
-export type { GitTopLevel }
+export type { GitTopLevel, PnpmProbe }
 export { doctor_io }

package/scripts/doctor/doctor.ts

@@ -5,12 +5,13 @@ import { fileURLToPath } from 'node:url'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { pnpm_reach } from '#scripts/lib/pnpm-reach'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
 import { ruleset_check } from '#scripts/repo/ruleset-check'
 import { security_updates } from '#scripts/security/security-updates'
 import { running_binary } from '#scripts/version/running-binary'
 import { doctor_consumer } from './doctor-consumer'
-import { doctor_io, type GitTopLevel } from './doctor-io'
+import { doctor_io, type GitTopLevel, type PnpmProbe } from './doctor-io'
 import { doctor_logic } from './doctor-logic'
 import { doctor_ports } from './doctor-ports'
 
@@ -43,10 +44,12 @@ interface DoctorContext {
 	running_path: string
 	path_josh: string | undefined
 	global_josh: string | undefined
+	pnpm: PnpmProbe
 }
 
 function gather_context(): DoctorContext {
 	return {
+		pnpm: doctor_io.probe_pnpm(),
 		running_version: running_binary.read_running_version(SELF_DIR),
 		running_path: running_binary.running_package_directory(SELF_DIR),
 		path_josh: doctor_io.resolve_path_josh(),
@@ -54,13 +57,28 @@ function gather_context(): DoctorContext {
 	}
 }
 
+function describe_pnpm(probe: PnpmProbe): string {
+	if (probe.state === 'found') return probe.version
+
+	return probe.state === 'missing' ? NOT_ON_PATH : UNKNOWN
+}
+
 function print_report(ctx: DoctorContext): void {
 	console.info('josh doctor')
 	console.info(`  Running:     ${ctx.running_version ?? UNKNOWN}  (${ctx.running_path})`)
 	console.info(`  On PATH:     ${ctx.path_josh ?? NOT_ON_PATH}`)
+	console.info(`  pnpm:        ${describe_pnpm(ctx.pnpm)}`)
 	console.info(`  pnpm global: ${ctx.global_josh ?? UNKNOWN}`)
 }
 
+// Said here rather than left to the gate: every check `josh` runs is a `pnpm` child, so without
+// pnpm on this process's PATH each of them fails before it starts.
+function report_pnpm_reach(ctx: DoctorContext): void {
+	if (ctx.pnpm.state !== 'missing') return
+	console.info('')
+	console.info(`⚠ ${pnpm_reach.NOT_ON_PATH_NOTICE}`)
+}
+
 // Remove a confirmed stale kit shim so the pnpm-global josh reclaims PATH precedence. Any other
 // shadowing binary is left in place and reported for manual review.
 function reclaim_shim(path_josh: string, global_josh: string): void {
@@ -207,6 +225,7 @@ function consumer_root(git: GitTopLevel): string {
 function run_reports(ctx: DoctorContext, git: GitTopLevel, options: DoctorOptions): void {
 	print_report(ctx)
 	report_path_diagnosis(ctx, options.is_fix)
+	report_pnpm_reach(ctx)
 	doctor_consumer.report_consumer_setup(consumer_root(git))
 	report_repository_map(git)
 	if (options.show_ports) report_port_seeds(git)

package/scripts/document/document-byte-budget.ts

@@ -74,9 +74,9 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
 	{ path: 'docs/josh-commands-automation.md', bytes: 53_248 },
-	{ path: 'docs/josh-commands-run.md', bytes: 69_632 },
-	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
-	{ path: 'docs/josh-commands.md', bytes: 49_152 },
+	{ path: 'docs/josh-commands-run.md', bytes: 77_824 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 61_440 },
+	{ path: 'docs/josh-commands.md', bytes: 57_344 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },

package/scripts/epic/epic-bundle-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
 import { issue_cite } from '#scripts/issue/issue-cite'
@@ -14,6 +15,7 @@ import {
 	type BacklogIssue,
 	type BundleAction,
 	type BundleDecision,
+	type MembershipContext,
 } from './epic-bundle'
 import { epic_bundle_evidence } from './epic-bundle-evidence'
 import { epic_bundle_gaps } from './epic-bundle-gaps'
@@ -53,6 +55,7 @@ const UNKNOWN_REPO_MESSAGE =
 // describing one it does.
 const backlog_schema = epic_schema.extend({
 	title: z.string().nullable(),
+	labels: z.array(issue_label_schema).default([]),
 	blocked_by_count: z.number().nullish(),
 })
 
@@ -62,10 +65,6 @@ type BacklogRow = z.infer<typeof backlog_schema>
 // task-list read would answer differently the first time that shape moved.
 const { build_epic_index } = epic_index
 
-function to_epic_field(epic: number | undefined): { epic?: number } {
-	return epic === undefined ? {} : { epic }
-}
-
 // Undefined when the read failed, which the caller reports — as opposed to an issue that genuinely
 // declares no relations, which is an empty array.
 async function epic_issue_relations(
@@ -139,18 +138,19 @@ interface FetchedBacklog {
 // One listing row as the bundler reads it. Split from the fetch so that function stays a list of
 // requests rather than a request list plus a row mapping.
 function to_backlog_issue(
-	row: { number: number; title?: string | null; body?: string | null },
-	context: { repo: string; epics: Map<number, number>; epic_numbers: ReadonlySet<number> },
+	row: Pick<BacklogRow, 'number' | 'title' | 'body' | 'labels'>,
+	context: MembershipContext & { repo: string },
 	blocked_by: ReadonlyArray<IssueReference>,
 ): BacklogIssue {
+	const labels = row.labels.map((label) => label.name)
+
 	return {
 		number: row.number,
 		repo: context.repo,
 		title: row.title ?? '',
 		body: row.body ?? '',
 		blocked_by,
-		is_epic: context.epic_numbers.has(row.number),
-		...to_epic_field(context.epics.get(row.number)),
+		...epic_bundle.membership_of(row.number, labels, context),
 	}
 }