@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/backlog/backlogrun-cli.ts

@@ -1,27 +1,41 @@
 #!/usr/bin/env tsx
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import type { AgentProvider } from '#scripts/agent/agent-role-profile'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { run_board_cli } from '#scripts/run/board/run-board-cli'
 import { run_carry } from '#scripts/run/carry/run-carry'
+import type { LaunchResult } from '#scripts/run/detached-launch'
+import { run_wake_cli } from '#scripts/run/wake/run-wake-cli'
 import { backlogrun_args, type BacklogrunArguments } from './backlogrun-args'
 import { backlogrun_launch, type LaunchTarget, type StartResult } from './backlogrun-launch'
+import { backlogrun_replace, type ReplaceVerdict } from './backlogrun-replace'
+import { backlogrun_stop, type StopReport } from './backlogrun-stop'
 
-// `josh backlogrun` — start a `backlogrun` from the terminal and watch it. A
+// `josh backlogrun` — start a `backlogrun` from the terminal and watch it, or stop it with `--stop`. A
 // run already going is never joined by a second one: the board is shown, and any issue named is pointed
 // at `run:add` rather than added behind the person's back. Otherwise the agent is started in the
 // background, its output to a log file, and the board takes over the terminal at once. Closing the
 // board closes only the board.
+//
+// **An idle run gives way to a different invocation.** A run watching with no child at work in a lane
+// is stopped as `--stop` stops it and the typed one is started in its place (`backlogrun-replace.ts`);
+// a run that is kept says why in one line above the board. The same invocation only shows the board,
+// so looking at a run never rebuilds it.
 
 const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const USAGE =
-	'Usage: josh backlogrun [#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]'
+	'Usage: josh backlogrun [<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop'
 
 interface BacklogrunPorts {
 	repository_directory: () => Promise<string | undefined>
 	is_running: (git_directory: string) => boolean
+	replacement: (invocation: string, git_directory: string) => Promise<ReplaceVerdict>
 	start: (args: BacklogrunArguments, target: LaunchTarget) => StartResult
+	start_supervisor: (git_directory: string, provider: AgentProvider) => LaunchResult
+	stop: (git_directory: string) => Promise<StopReport>
 	show_board: () => Promise<number>
 	write: (line: string) => void
 }
@@ -29,7 +43,11 @@ interface BacklogrunPorts {
 const LIVE_PORTS: BacklogrunPorts = {
 	repository_directory: run_carry.repository_directory,
 	is_running: backlogrun_launch.is_running,
+	replacement: async (invocation, git_directory) =>
+		await backlogrun_replace.decide(invocation, git_directory),
 	start: (args, target) => backlogrun_launch.start(args.invocation, args.provider, target),
+	start_supervisor: run_wake_cli.start_for_launch,
+	stop: async (git_directory) => await backlogrun_stop.stop(git_directory),
 	show_board: async () => await run_board_cli.run([]),
 	write: (line) => process.stdout.write(`${line}\n`),
 }
@@ -41,6 +59,12 @@ function running_notes(issues: ReadonlyArray<number>): Array<string> {
 	return ['backlogrun: a run is already going; showing its board.', ...guidance]
 }
 
+// Why a different invocation did not replace the run, ahead of the board. The same invocation is the
+// board reopened, and adds nothing.
+function kept_notes(verdict: ReplaceVerdict): Array<string> {
+	return verdict.kind === 'keep' ? [`backlogrun: not replacing the run — ${verdict.reason}`] : []
+}
+
 function launched_note(result: Extract<StartResult, { kind: 'launched' }>): string {
 	const { pid, session, log_path } = result.launched
 	const session_part = session === undefined ? '' : `, session ${session}`
@@ -48,22 +72,26 @@ function launched_note(result: Extract<StartResult, { kind: 'launched' }>): stri
 	return `backlogrun: started (pid ${String(pid)}${session_part}); log ${log_path}`
 }
 
+// **The supervisor is started here, beside the parent, never from the parent's own shell**: Claude
+// Code removes its token from what its Bash tool starts, so only this process can hand a token-only
+// credential on to the sessions the supervisor wakes (joshuafolkken/kit#3804). A supervisor that does
+// not start leaves the parent's own `run:wake --start` to try, so the run is still shown.
+function supervisor_note(result: LaunchResult): string {
+	if (result.kind === 'failed') return `backlogrun: could not start the supervisor: ${result.note}`
+
+	return `backlogrun: supervisor started (pid ${String(result.pid)})`
+}
+
 // The agent starts in the main checkout, the parent of the common git directory every record is keyed on.
 function target_of(git_directory: string): LaunchTarget {
 	return { worktree: path.dirname(git_directory), git_directory }
 }
 
-async function begin(
+async function launch(
 	args: BacklogrunArguments,
 	git_directory: string,
 	ports: BacklogrunPorts,
 ): Promise<number> {
-	if (ports.is_running(git_directory)) {
-		for (const note of running_notes(args.issues)) ports.write(note)
-
-		return await ports.show_board()
-	}
-
 	const result = ports.start(args, target_of(git_directory))
 
 	if (result.kind === 'failed') {
@@ -73,29 +101,73 @@ async function begin(
 	}
 
 	ports.write(launched_note(result))
+	ports.write(supervisor_note(ports.start_supervisor(git_directory, args.provider)))
+
+	return await ports.show_board()
+}
+
+// The idle run is stopped as `--stop` stops it, and a run left with an owner this command may not
+// signal is not replaced: nothing is started beside it.
+async function replace(
+	args: BacklogrunArguments,
+	git_directory: string,
+	ports: BacklogrunPorts,
+): Promise<number> {
+	ports.write(`backlogrun: replacing the idle run with \`${args.invocation}\``)
+
+	const report = await ports.stop(git_directory)
+
+	for (const line of backlogrun_stop.lines_of(report)) ports.write(line)
+
+	if (!backlogrun_stop.is_stopped(report)) return FAILURE_EXIT_CODE
+
+	return await launch(args, git_directory, ports)
+}
+
+async function begin(
+	args: BacklogrunArguments,
+	git_directory: string,
+	ports: BacklogrunPorts,
+): Promise<number> {
+	if (!ports.is_running(git_directory)) return await launch(args, git_directory, ports)
+
+	const verdict = await ports.replacement(args.invocation, git_directory)
+
+	if (verdict.kind === 'replace') return await replace(args, git_directory, ports)
+
+	for (const note of [...kept_notes(verdict), ...running_notes(args.issues)]) ports.write(note)
 
 	return await ports.show_board()
 }
 
+// Stopping starts nothing and draws no board: the lines say what was stopped, and a run left with an
+// owner this command may not signal is a failure the exit code carries.
+async function stop(git_directory: string, ports: BacklogrunPorts): Promise<number> {
+	const report = await ports.stop(git_directory)
+
+	for (const line of backlogrun_stop.lines_of(report)) ports.write(line)
+
+	return backlogrun_stop.is_stopped(report) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+function refuse(line: string, ports: BacklogrunPorts): number {
+	ports.write(line)
+
+	return FAILURE_EXIT_CODE
+}
+
 async function run(
 	argv: ReadonlyArray<string>,
 	ports: BacklogrunPorts = LIVE_PORTS,
 ): Promise<number> {
 	const parsed = backlogrun_args.parse(argv)
 
-	if (parsed.kind === 'refused') {
-		ports.write(USAGE)
-
-		return FAILURE_EXIT_CODE
-	}
+	if (parsed.kind === 'refused') return refuse(USAGE, ports)
 
 	const git_directory = await ports.repository_directory()
 
-	if (git_directory === undefined) {
-		ports.write('backlogrun: not inside a git repository')
-
-		return FAILURE_EXIT_CODE
-	}
+	if (git_directory === undefined) return refuse('backlogrun: not inside a git repository', ports)
+	if (parsed.kind === 'stop') return await stop(git_directory, ports)
 
 	return await begin(parsed.args, git_directory, ports)
 }

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
 }