@joshuafolkken/kit 1.1240.0 → 1.1370.0

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

@@ -1,9 +1,9 @@
 import { OPTIONAL_ENV_FILE_FLAGS, type CommandEntry } from './josh-command-types'
 
 // The run-lifecycle registry (`run:hold` through `run:step`), split out of `josh-commands-ai.ts` so
-// that file stays under its 300-code-line limit, as `BACKLOG_COMMANDS` and `LANE_COMMANDS` were
-// (joshuafolkken/kit#2992). It is spread into `AI_COMMANDS` at the place the entries used to sit, so
-// the generated catalog keeps their order.
+// that file stays under its 300-code-line limit, as `BACKLOG_COMMANDS` and `LANE_COMMANDS` are. It
+// is spread into `AI_COMMANDS` at the place the entries belong, so the generated catalog keeps their
+// order.
 
 // One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
 const RUN_HOLD_SCRIPT = 'scripts/run/hold/run-hold-cli.ts'
@@ -32,12 +32,18 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 	'run:carry': {
 		script: 'scripts/run/carry/run-carry-cli.ts',
 		// `--stopped` sends the stop confirmation, so the Telegram credentials come from `.env` as for
-		// `run:wake` below (joshuafolkken/kit#3357).
+		// `run:wake` below.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description: 'Carry one invocation’s budget across its own session cuts',
 		category: 'AI tools',
 		reference: ['<operation> [arguments...]', 'automation', ['files']],
 	},
+	'run:add': {
+		script: 'scripts/run/add/run-add-cli.ts',
+		description: 'Add issues to a live backlogrun, ahead of the queue unless --no-priority',
+		category: 'AI tools',
+		reference: ['<issue...> [--no-priority]', 'automation', ['network', 'files']],
+	},
 	'run:wake': {
 		script: 'scripts/run/wake/run-wake-cli.ts',
 		// `.env` rather than the ambient environment:
@@ -76,18 +82,26 @@ const RUN_COMMANDS: Record<string, CommandEntry> = {
 			['files'],
 		],
 	},
+	'run:board': {
+		script: 'scripts/run/board/run-board-cli.ts',
+		// `--every` pushes its frame as a Telegram, so the credentials come from `.env` as for `run:carry`.
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description: 'Draw a live board of the running backlogrun, redrawn every second',
+		category: 'AI tools',
+		reference: ['[--once | --chat | --every <minutes>]', 'automation', ['files', 'network']],
+	},
 	'run:prep': {
 		script: 'scripts/run/run-prep-cli.ts',
 		description: 'Bundle a run’s pre-edit reads: body, comments, state, dependency scope',
 		category: 'AI tools',
 		reference: ['<issue>', 'automation', ['network']],
 	},
-	// The entry sequence a lane opened on, folded into one call (joshuafolkken/kit#2372): claim the tree,
+	// The entry sequence a lane opened on, folded into one call: claim the tree,
 	// read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
 	// `cost --cut`, `run:prep` and `run:step` were four round trips re-billing a lane's full context each.
 	'run:entry': {
 		script: 'scripts/run/entry/run-entry-cli.ts',
-		// A `busy` hold or an `over` budget sends the stop confirmation (joshuafolkken/kit#3357).
+		// A `busy` hold or an `over` budget sends the stop confirmation.
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 		description:
 			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',

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

@@ -1,8 +1,7 @@
 import type { CommandEntry } from './josh-command-types'
 
 // The `split:assess` command registry, split out of `josh-commands-ai.ts` so that file stays under its
-// 300-code-line limit, exactly as `LANE_COMMANDS` was for the same reason (joshuafolkken/kit#2162,
-// joshuafolkken/kit#2218). It is spread into `AI_COMMANDS` so the command stays grouped with the other
+// 300-code-line limit, exactly as `LANE_COMMANDS` was for the same reason. It is spread into `AI_COMMANDS` so the command stays grouped with the other
 // decision oracles under the 'AI tools' category.
 
 /* eslint-disable @typescript-eslint/naming-convention */

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

@@ -24,16 +24,16 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Versioning',
 		reference: ['', 'developer', ['network']],
 	},
-	// The one place that decides a version (joshuafolkken/kit#1169). A `script` entry for the same
+	// The one place that decides a version. A `script` entry for the same
 	// reason `ranges` is one: script paths resolve against the kit package root, so it keeps working
 	// from a consumer repository where the file lives under node_modules.
 	release: {
 		script: 'scripts/release/release-cli.ts',
 		description: 'Release the merges main has taken since the version last changed',
 		category: 'Versioning',
-		reference: ['[version]', 'maintainer', ['git', 'network', 'release']],
+		reference: ['[--dry-run]', 'maintainer', ['git', 'network', 'release']],
 	},
-	// The read-only half of the one above (joshuafolkken/kit#1582). `release --dry-run` cannot
+	// The read-only half of the one above. `release --dry-run` cannot
 	// answer this question: it refuses off the default branch and on a dirty tree, which is every
 	// position a run asks it from. A `script` entry for the same reason `release` is one.
 	'release:scope': {
@@ -42,8 +42,8 @@ const VERSIONING_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Versioning',
 		reference: ['[--json]', 'automation', ['none']],
 	},
-	// Run by the release workflows, kit's and the one sync distributes, after a tag has published
-	// (joshuafolkken/kit#3007). Settings come from the environment, so the workflow decides them.
+	// Run by the release workflows, kit's and the one sync distributes, after a tag has published.
+	// Settings come from the environment, so the workflow decides them.
 	'release:github': {
 		script: 'scripts/release/github-release-cli.ts',
 		description: 'Create the GitHub Release for a published tag, with generated notes',

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

@@ -20,20 +20,17 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<message>', 'developer', ['network']],
 		default_script_arguments: ['-y', '--skip-commit', '--skip-push'],
 	},
-	// **The optional form, on both** (joshuafolkken/kit#1564). These two were the last commands
-	// passing the mandatory `--env-file=.env`, which node resolves before the script's first line: on
-	// a machine with no `.env` they died as `.env: not found` with exit code 9, even where
-	// `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` existed as real environment variables — a cloud
-	// session, and `followup` with them the merge step of every `fullrun` there. `doctor` was moved to
-	// this form for the same reason in joshuafolkken/kit#869.
+	// **The optional form, on both**. The mandatory `--env-file=.env` is resolved by node before the
+	// script's first line: on a machine with no `.env` it dies as `.env: not found` with exit code 9,
+	// even where `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` exist as real environment variables — a
+	// cloud session, and `followup` with them the merge step of every `fullrun` there.
 	//
 	// Nothing is lost by relaxing it: both scripts already load `.env` through `josh_environment_file`
 	// themselves, so the file is read either way and node's precedence — an existing environment
 	// variable wins over the file — is node's own in both spellings.
 	//
-	// **What the mandatory flag was accidentally providing was noise**, and that is replaced rather
-	// than dropped: `telegram_notify.send` now throws on missing credentials and on a failed send, so
-	// `josh notify` exits non-zero instead of warning and answering 0.
+	// **A missing credential still fails loudly**: `telegram_notify.send` throws on missing credentials
+	// and on a failed send, so `josh notify` exits non-zero instead of warning and answering 0.
 	followup: {
 		script: 'scripts/followup/git-followup-workflow.ts',
 		description: 'Follow-up git workflow',
@@ -49,11 +46,23 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/notify/telegram-test.ts',
 		description: 'Send Telegram notification',
 		category: 'Workflow',
-		reference: ['--task-type <type> --body <text>', 'automation', ['notifications']],
+		reference: [
+			'[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]',
+			'automation',
+			['notifications'],
+		],
 		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
 	},
-	// The observation ledger's commit path for the lines no run's own commit carried
-	// (joshuafolkken/kit#1756, joshuafolkken/kit#2763): a lane's lines sit in the primary checkout, which
+	// One observation-ledger sighting: the key's count, the append and the second-sighting verdict,
+	// which a run used to type as a `cat | grep -c` and judge by hand.
+	'observation:record': {
+		script: 'scripts/observations/observation-record-cli.ts',
+		description: 'Record an observation sighting and answer whether it is now filed',
+		category: 'Workflow',
+		reference: ['<key> <depth> <where> <what> [--checkout <path>]', 'automation', ['files']],
+	},
+	// The observation ledger's commit path for the lines no run's own commit carried:
+	// a lane's lines sit in the primary checkout, which
 	// its commit cannot see, and the recurrence count the promotion rule reads is a count of main.
 	'observations:flush': {
 		script: 'scripts/observations/observations-flush-cli.ts',
@@ -61,8 +70,8 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Workflow',
 		reference: ['', 'automation', ['git', 'network']],
 	},
-	// The one write path for a `/code-review` round's findings (joshuafolkken/kit#2325), plus the
-	// `--check` gate `followup` runs before it merges (joshuafolkken/kit#2343). It appends a `- rf:`
+	// The one write path for a `/code-review` round's findings, plus the
+	// `--check` gate `followup` runs before it merges. It appends a `- rf:`
 	// line per finding — or one zero-finding line for a clean round — to the observation ledger, so
 	// `observations:flush` commits them and the recurrence count survives the run.
 	'review:record': {
@@ -70,12 +79,12 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Record a review round’s findings, or check a round was recorded',
 		category: 'Workflow',
 		reference: [
-			'--issue <N> [<category>:<severity>:<file> ...] | --check --issue <N>',
+			'--issue <N> [--comment] [<category>:<severity>:<file> ...] | --check --issue <N>',
 			'automation',
-			['files'],
+			['files', 'network'],
 		],
 	},
-	// The reader over what `review:record` wrote (joshuafolkken/kit#2325): each recurring category’s
+	// The reader over what `review:record` wrote: each recurring category’s
 	// count, and the number of zero-finding rounds that distinguishes a quiet category from an unwatched one.
 	'review:findings': {
 		script: 'scripts/review/review-findings-cli.ts',
@@ -84,7 +93,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['files']],
 	},
 	// After a behavior-change Issue merges, re-run its declared baseline and print before/after; a value
-	// that did not move appends a refuted-premise line to the observation ledger (joshuafolkken/kit#2212).
+	// that did not move appends a refuted-premise line to the observation ledger.
 	'measure:rerun': {
 		script: 'scripts/issue/measure-rerun-cli.ts',
 		description: 'Re-run a merged issue’s baseline command and print the before/after pair',
@@ -92,7 +101,7 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<issue-number>', 'automation', ['network', 'processes', 'files']],
 	},
 	// A script rather than an `sh -c` chain, because it has a precondition to enforce: run inside a
-	// linked work tree it would hijack the default branch from every other one (joshuafolkken/kit#1535).
+	// linked work tree it would hijack the default branch from every other one.
 	'main:sync': {
 		script: 'scripts/git/main-sync.ts',
 		description:
@@ -101,9 +110,8 @@ const WORKFLOW_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['', 'developer', ['git', 'network']],
 	},
 	// A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
-	// the caller's git configuration: the `git pull` this replaced aborted with `Need to specify how
-	// to reconcile divergent branches` on exactly the diverged branch the command exists for
-	// (joshuafolkken/kit#1659).
+	// the caller's git configuration: a bare `git pull` aborts with `Need to specify how to reconcile
+	// divergent branches` on exactly the diverged branch the command exists for.
 	'main:merge': {
 		script: 'scripts/git/main-merge.ts',
 		description: 'Merge origin default branch into the current branch',

package/scripts/josh/josh-environment-file.ts

@@ -4,7 +4,7 @@ import { ENV_FILE_NAME } from '#ports'
 //
 // **The flag form is what most commands use, and it is not free.** Declaring any `tsx_arguments`
 // disqualifies a command from in-process dispatch (`josh-in-process.ts`), which puts a second
-// ~0.16 s tsx start in front of every call — the hot path joshuafolkken/kit#1342 took it off. A
+// ~0.16 s tsx start in front of every call. A
 // command a hook fires on every `Bash` call, or one an unattended `epicrun` polls every sixty
 // seconds, cannot pay that, so it reads the file itself instead.
 //

package/scripts/josh/josh-in-process.ts

@@ -5,8 +5,8 @@ import type { CommandEntry } from './josh-command-types'
 
 // `pnpm josh <script command>` started tsx twice — once for this dispatcher, once for the script it
 // spawned. Measured on 2026-09-04, the second start was about 0.16 s of the 0.55 s a
-// `pnpm josh format:edited` took, and the edit/Bash hook pays it 60–90 times in a single run
-// (joshuafolkken/kit#1342). The script is ordinary TypeScript and a TypeScript loader is already
+// `pnpm josh format:edited` took, and the edit/Bash hook pays it 60–90 times in a single run.
+// The script is ordinary TypeScript and a TypeScript loader is already
 // installed by the time this file runs, so the dispatcher evaluates the script itself instead.
 const TYPESCRIPT_EXTENSION = '.ts'
 const JAVASCRIPT_EXTENSION = '.js'
@@ -21,7 +21,7 @@ function is_typescript_dispatcher(dispatcher_url: string): boolean {
 }
 
 // A command marked `is_bundled` is pre-built to `dist/commands/<script basename>.js` by
-// `scripts/build/build-commands.ts` (joshuafolkken/kit#3328). The path is derived here, in a module
+// `scripts/build/build-commands.ts`. The path is derived here, in a module
 // the dispatcher bundle already carries, so the build and the dispatcher cannot name two locations.
 function bundled_script_path(package_directory: string, script: string): string {
 	const name = `${path.basename(script, TYPESCRIPT_EXTENSION)}${JAVASCRIPT_EXTENSION}`

package/scripts/josh/josh-logic.ts

@@ -59,7 +59,7 @@ function resolve_tsx_executable(): string {
 
 // Locating the CLI entry through tsx's own manifest never consults pnpm's generated shim, which
 // hardcodes a store path a later bump prunes. The resolution itself is `resolve_package_bin` —
-// shared with the format hook's eslint route rather than written twice (joshuafolkken/kit#1259).
+// shared with the format hook's eslint route rather than written twice.
 function resolve_tsx_cli_entry(): string | undefined {
 	for (const base_directory of [PACKAGE_DIR, process.cwd()]) {
 		const cli_entry = resolve_package_bin(base_directory, TSX_PACKAGE, TSX_BIN)
@@ -157,7 +157,7 @@ function format_help(is_all = false, is_consumer = false): string {
 }
 
 // Every name a user could type — the canonical commands and their aliases — ranked by edit distance
-// so `josh gat` points at `gate` (joshuafolkken/kit#1928).
+// so `josh gat` points at `gate`.
 function all_command_names(): Array<string> {
 	return [...Object.keys(COMMAND_MAP), ...Object.keys(ALIASES)]
 }
@@ -219,7 +219,7 @@ function spawn_script_entry(
 
 // Only the in-process branch is genuinely asynchronous; the spawning one answers the moment the
 // child exits. Both are reported as a promise so every caller has one shape to handle, and
-// `josh.ts` awaits it either way (joshuafolkken/kit#1342).
+// `josh.ts` awaits it either way.
 async function run_script_entry(
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
@@ -242,8 +242,7 @@ function github_prerequisite_exit(resolved: string, is_consumer: boolean): numbe
 }
 
 // The exit a command answers with before it runs, or `undefined` to go ahead: a consumer is refused a
-// kit-only command with guidance, and a composite command rejects extra arguments
-// (joshuafolkken/kit#1988).
+// kit-only command with guidance, and a composite command rejects extra arguments.
 function pre_dispatch_exit(
 	resolved: string,
 	entry: CommandEntry,
@@ -283,8 +282,8 @@ function declared(value: number | (() => number) | undefined): number | undefine
 	return typeof value === 'function' ? value() : value
 }
 
-// **Every command passes through here, so this is where a declared weight is reserved**
-// (joshuafolkken/kit#3345). A heavy command run directly, outside `josh gate`, used to start its tools
+// **Every command passes through here, so this is where a declared weight is reserved**.
+// A heavy command run directly, outside `josh gate`, used to start its tools
 // without claiming a place. A command under a parent that already holds its cores claims nothing:
 // `core_budget.with_command_reservation` reads the mark that parent set.
 async function dispatch_entry(

package/scripts/josh/josh-run.ts

@@ -1,6 +1,6 @@
 import { execa } from 'execa'
 
-// One captured `pnpm josh` subprocess (joshuafolkken/kit#2162). A composite command that collapses a
+// One captured `pnpm josh` subprocess. A composite command that collapses a
 // sequence of `pnpm josh` calls into one — `run:merge`, `backlog:offer`, `lane:launch` — reads each
 // step's output back rather than inheriting it, so the step's own report logic is reused rather than
 // cloned and only the composite's own token reaches the caller's stdout. This is that read, single-
@@ -11,11 +11,11 @@ import { execa } from 'execa'
 // a person sees it, so a composite streams it through; `run:merge` keeps it piped, because it composes
 // its own report from the captured values instead.
 //
-// **Forwarded stderr is captured as well** (joshuafolkken/kit#2462): a composite that writes a report
+// **Forwarded stderr is captured as well**: a composite that writes a report
 // of its own — `run:tail` — puts a failed step's reason in that report, where a detached run's log
 // otherwise showed only pnpm's `ELIFECYCLE` line.
 //
-// **`timeout_ms` bounds a read made from inside a loop** (joshuafolkken/kit#2503): the step is killed and
+// **`timeout_ms` bounds a read made from inside a loop**: the step is killed and
 // its exit reads as a failure, so a hung network call ends a pass instead of the loop around it.
 
 const PNPM = 'pnpm'

package/scripts/josh/josh-verdict.ts

@@ -1,14 +1,13 @@
 import { status_icons } from '#scripts/lib/status-icons'
 
-// A josh command's own overall verdict, and the one place its line is written (joshuafolkken/kit#1374).
+// A josh command's own overall verdict, and the one place its line is written.
 //
-// `status-icons.ts` single-sourced the *character* a failure line opens with, which was enough while
-// the only thing reading it was `time-reported-failure.ts` asking "did this call print a failure?".
-// It is not enough for a command that **forwards another tool's output**. `josh gate` prints the body
-// of a step that passed with warnings or skipped (joshuafolkken/kit#1328), and that body is written by
+// `status-icons.ts` single-sources the *character* a failure line opens with, which is not enough for
+// a command that **forwards another tool's output**. `josh gate` prints the body
+// of a step that passed with warnings or skipped, and that body is written by
 // eslint, svelte-check, vitest or cspell — this repository owns none of those formats. One of them
 // opening a line with the failure icon makes a *green* gate read as a failed call, and the re-run that
-// follows it is then charged as rework: the very figure joshuafolkken/kit#1361 exists to make honest.
+// follows it is then charged as rework, which the rework figure exists to keep honest.
 //
 // **The anchor is the command's own verdict, not the shape of every line it prints.** A command that
 // forwards other tools' output states its own result in one line, and that line outranks the body it
@@ -17,21 +16,20 @@ import { status_icons } from '#scripts/lib/status-icons'
 // each consumer's gate with inherited stdio — so a `passed` verdict speaks for the lines in front of
 // it and the reading resumes after it (`time-reported-failure.ts` → `lines_after_last_pass`).
 //
-// **Why not enumerate every josh failure-line shape.** That is the candidate joshuafolkken/kit#1374
-// names as most likely, and rejects for the reason it names: the gate's step line is
+// **Why not enumerate every josh failure-line shape.** The gate's step line is
 // `✗ <label> (pnpm <cmd>) <n>s`, `josh health`'s is `  ✗ <label>` and `josh propagate`'s is
 // `  ✗ <repo>  <reason>`, so a pattern list tight enough to exclude a third-party warning is a list of
 // per-command patterns — and the next josh command to print a failure line is silently not counted,
 // which is the detector going quiet without failing. Reading the verdict instead leaves every other
 // josh command exactly as it was: no verdict line, so nothing changes for them.
 //
-// **What it degrades to is today's behavior, not silence.** A body the harness truncated past the
+// **What it degrades to is the bare-icon reading, not silence.** A body the harness truncated past the
 // verdict line falls back to the bare-icon reading, so the figure stays a floor. The gate's verdict is
 // its **last** line, which is what survives the `2>&1 | tail -40` agents actually type
 // (`prompts/collaboration-workflow/output-bounds.md`), so the fallback is the rare case rather than
 // the common one.
 //
-// **The opening line is here for the same reason the verdict is** (joshuafolkken/kit#1379). A verdict
+// **The opening line is here for the same reason the verdict is**. A verdict
 // says where the gate's output *ended*; nothing said where it began, so a green verdict silenced every
 // failure mark printed before it — including one written by a command that had already finished. The
 // gate's plan line is what says "the gate starts here", and it is single-sourced for the reason the
@@ -41,8 +39,7 @@ const { FAIL_ICON, PASS_ICON } = status_icons
 const GATE_SUBJECT = 'verification gate'
 
 // The prefixes are what the detector matches **and** what the printer builds its line from, so a
-// reworded verdict moves both ends at once — the property joshuafolkken/kit#1361 gave the icon,
-// applied to the line. Splitting them into a printed string and a matched string is exactly the drift
+// reworded verdict moves both ends at once — the property the icon has, applied to the line. Splitting them into a printed string and a matched string is exactly the drift
 // this module exists to prevent.
 const GATE_PASSED_PREFIX = `${PASS_ICON} ${GATE_SUBJECT} passed`
 const GATE_FAILED_PREFIX = `${FAIL_ICON} ${GATE_SUBJECT} failed`

package/scripts/josh/josh.ts

@@ -24,8 +24,8 @@ function handle_unknown(cmd: string): never {
 	process.exit(1)
 }
 
-// `process.exit` truncates a piped stdout at its buffer size, and since joshuafolkken/kit#1342 the
-// output at risk is the script's own — `scripts/gate/verification-gate.ts` writes its per-check blocks
+// `process.exit` truncates a piped stdout at its buffer size, and the output at risk is the script's
+// own — `scripts/gate/verification-gate.ts` writes its per-check blocks
 // and its failure summary through this process, and sets `process.exitCode` rather than exiting for
 // exactly that reason. Recording the code and letting node exit when the loop drains keeps every
 // byte, and it leaves the last word with a script that finishes work after module evaluation
@@ -36,7 +36,7 @@ function record_exit_code(exit_code: number): void {
 }
 
 // `run_command` answers with a number for a shell command and a promise for a script it runs in
-// this same process (joshuafolkken/kit#1342); `await` covers both, and the argv slice is taken
+// this same process; `await` covers both, and the argv slice is taken
 // before it because the in-process branch replaces `process.argv` with the script's own.
 async function main(): Promise<void> {
 	const cmd = process.argv[ARGV_OFFSET]

package/scripts/josh/kit-only.ts

@@ -2,8 +2,8 @@ import { COMMAND_MAP } from './josh-command-map'
 import type { CommandEntry } from './josh-command-types'
 
 // The commands marked `is_kit_only` in the map only make sense inside the kit repository itself, so a
-// consumer never sees them in `josh --help` and is refused with guidance when it runs one
-// (joshuafolkken/kit#1988). The flag lives on the entry; everything a reader needs to act on it is
+// consumer never sees them in `josh --help` and is refused with guidance when it runs one.
+// The flag lives on the entry; everything a reader needs to act on it is
 // here, so the help filter, the dispatch guard and the distributed-doc test read one definition.
 
 // Where a consumer is told to go. A script-emitted string, so it stays English (`CLAUDE.md` →

package/scripts/josh/path-decision.ts

@@ -1,6 +1,6 @@
 import { changed_paths } from '#scripts/git/changed-paths'
 
-// The shape both path-decided commands share (joshuafolkken/kit#907).
+// The shape both path-decided commands share.
 //
 // `josh review:level` and `josh review:round2` ask different questions of the same tree, and they answer
 // the same way: read the changed paths, decide from them alone, print the answer on stdout and the reason on
@@ -29,8 +29,8 @@ interface DecisionCommand<Answer extends string> {
 	explain: (paths: ReadonlyArray<string>, answer: Answer) => string
 }
 
-// The flag contract every mechanically-decided command shares — the two here and `josh review:round2`
-// (joshuafolkken/kit#1433). An argument that is not a known flag makes the whole invocation
+// The flag contract every mechanically-decided command shares — the two here and `josh review:round2`.
+// An argument that is not a known flag makes the whole invocation
 // unreadable, and an unreadable invocation is never answered with a default. Shared because the
 // *direction* is the load-bearing part rather than the `some` call: a command that guessed would
 // hand the caller the answer they were reaching for instead of the one their tree supports, and two

package/scripts/josh/platform-temporary.ts

@@ -5,9 +5,9 @@ import { tmpdir } from 'node:os'
 // "the temp directory"**: it honors `TMPDIR`, which on macOS names a per-user `/var/folders/…/T`, so
 // two processes with different `TMPDIR` values resolve two different places. A record one josh
 // command writes for another to read then lands where the reader never looks — the transcript a
-// harness wrote under `/tmp` that `os.tmpdir()` could not name (joshuafolkken/kit#1501), and the run
-// record a `backlogrun` handed off that the `run:wake`-launched session began again from nothing
-// (joshuafolkken/kit#1909). A cross-process handoff has to key on a root neither end's own `TMPDIR`
+// harness wrote under `/tmp` that `os.tmpdir()` could not name, and the run
+// record a `backlogrun` handed off that the `run:wake`-launched session began again from nothing.
+// A cross-process handoff has to key on a root neither end's own `TMPDIR`
 // can move, and that is what this pins.
 //
 // **It is decided by platform rather than written as a bare `/tmp`, because a POSIX literal is not
@@ -42,12 +42,14 @@ function resolve_temporary_root(
 	return can_write(POSIX_TEMP_ROOT) ? POSIX_TEMP_ROOT : tmpdir()
 }
 
-// **An explicit root wins, and the unit suite is who sets one** (joshuafolkken/kit#2494). Every
+// **An explicit root wins, and the unit suite is who sets one**. Every
 // record keyed here is shared by the whole host, so a unit test that drove a writer for real wrote
 // into the live run's records — progress lines for issues the run never touched, relayed to the
 // session watching it. The network guard's `arm` points this at a directory of its own before any
 // worker forks, so every process of one test run shares a root no real run reads, and `disarm`
-// removes it with the rest of the guard.
+// removes it with the rest of the guard. Live evidence of `run:carry` sets it for the same
+// reason: the run's state records are keyed here too, and evidence taken against the default root
+// once ended the record of the run that was actually going.
 const TEMP_ROOT_KEY = 'JOSH_TEMP_ROOT'
 
 function temporary_root(override: string | undefined, platform: string): string {

package/scripts/josh/process-identity.ts

@@ -6,7 +6,7 @@ import path from 'node:path'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { PLATFORM_TEMP_ROOT } from './platform-temporary'
 
-// Whether the process a record names is still the one that wrote it (joshuafolkken/kit#1245).
+// Whether the process a record names is still the one that wrote it.
 //
 // **A pid is not a process identity, and every record here was treating it as one.** `process.kill(
 // pid, 0)` answers "alive" for whatever holds that number *now*, so a marker left behind by a gate
@@ -63,8 +63,14 @@ const BEACON_PREFIX = `josh-process-identity-${String(process.getuid?.() ?? '')}
 const BEACON_ID_LENGTH = 36
 const BEACON_ID_PATTERN = /^[\da-f-]+$/u
 const WINDOWS_PLATFORM = 'win32'
-const SOCKET_PROBE_SOURCE =
-	"const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(0));socket.once('error',()=>process.exit(1));socket.setTimeout(1000,()=>process.exit(1));"
+// The probe's three exits. Only a refused connection or a missing socket
+// proves the listener gone; any other error, the probe's own socket timeout, and a probe killed by
+// `PROBE_TIMEOUT_MS` or a signal leave the answer unknown, since a loaded machine produces all three
+// for a holder that is still running.
+const BEACON_LIVE_STATUS = 0
+const BEACON_UNKNOWN_STATUS = 1
+const BEACON_GONE_STATUS = 2
+const SOCKET_PROBE_SOURCE = `const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(${String(BEACON_LIVE_STATUS)}));socket.once('error',(error)=>process.exit(['ECONNREFUSED','ENOENT'].includes(error.code)?${String(BEACON_GONE_STATUS)}:${String(BEACON_UNKNOWN_STATUS)}));socket.setTimeout(1000,()=>process.exit(${String(BEACON_UNKNOWN_STATUS)}));`
 const beacons = new Map<string, Server>()
 const exit_cleanup = { is_registered: false }
 
@@ -219,15 +225,26 @@ function beacon_target(token: string): string | undefined {
 	return is_valid_beacon_name(path.basename(target)) ? target : undefined
 }
 
-function is_live_beacon(target: string): boolean {
+// No status is a probe killed by its timeout or a signal — unknown, the same as its own timeout.
+function run_socket_probe(target: string): number | undefined {
 	return (
 		spawnSync(process.execPath, ['-e', SOCKET_PROBE_SOURCE, target], {
 			stdio: 'ignore',
 			timeout: PROBE_TIMEOUT_MS,
-		}).status === 0
+		}).status ?? undefined
 	)
 }
 
+function is_live_beacon(
+	target: string,
+	probe: (target: string) => number | undefined = run_socket_probe,
+): boolean | undefined {
+	const status = probe(target)
+	if (status === BEACON_LIVE_STATUS) return true
+
+	return status === BEACON_GONE_STATUS ? false : undefined
+}
+
 function has_matching_start(
 	pid: number,
 	recorded_start: string,
@@ -299,7 +316,7 @@ function is_same_process(
 }
 
 // **Whether a record is the caller's own, which is a different question from whether its writer is
-// alive** (joshuafolkken/kit#1727). `is_same_process` asks about the recorded process; this asks
+// alive**. `is_same_process` asks about the recorded process; this asks
 // whether that process *is this one*. A supervisor that has been replaced reads its successor's
 // record as perfectly live, so liveness alone can never tell a hand-over from an ordinary pass — and
 // a writer deciding by liveness overwrites whatever it finds.
@@ -319,6 +336,7 @@ function is_own_process(pid: number | undefined, recorded_start: string | undefi
 
 const process_identity = {
 	close_beacon,
+	is_live_beacon,
 	is_live_pid,
 	is_own_process,
 	is_same_process,

package/scripts/josh/process-owner.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod'
 
-// The pair a record names its writing process by, as `process_identity` reads it back
-// (joshuafolkken/kit#1245): the pid, and the opaque start token `process_identity.own_fields` wrote
+// The pair a record names its writing process by, as `process_identity` reads it back:
+// the pid, and the opaque start token `process_identity.own_fields` wrote
 // beside it. Every lock, marker and ledger entry that later asks `is_same_process` carries this pair,
-// so its shape is declared once here and each record extends it (joshuafolkken/kit#2986).
+// so its shape is declared once here and each record extends it.
 //
-// `process_start` is optional because a record written before joshuafolkken/kit#1245, or on a platform
+// `process_start` is optional because an older record, or one written on a platform
 // whose start time cannot be read, carries only the pid — `is_same_process` has an answer of its own
 // for that case rather than the record being rejected.
 const process_owner_schema = z.object({ pid: z.number(), process_start: z.string().optional() })