@joshuafolkken/kit 1.1050.0 → 1.1128.0

package/scripts/issue/issue-report-failures.ts

@@ -0,0 +1,80 @@
+// The failure report `issue:read` and `issue:state` share (joshuafolkken/kit#3046). Both read a batch
+// of numbers, print a block for each one that answered, and name every one that did not; only the
+// result kind that counts as an answer and what a gap must not be mistaken for differ between them.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+
+// The two failure kinds a read can end in, kept apart all the way to the report: `missing` is the
+// number resolving to nothing and `unreadable` is a read that failed, and the documents ask a
+// caller to report the two differently. Folding them together to simplify the batch would destroy
+// exactly that distinction.
+type ReadFailureKind = 'missing' | 'unreadable'
+
+interface NumberReport<K extends string> {
+	issue_number: string
+	result: { kind: K | ReadFailureKind }
+}
+
+interface FailureTerms<K extends string> {
+	success_kind: K
+	// What a failed read would be misread as if it were printed silently — "the issue is empty".
+	misreading: string
+}
+
+function print_blocks(blocks: ReadonlyArray<string>, separator: string): void {
+	if (blocks.length === 0) return
+
+	console.info(blocks.join(separator))
+}
+
+// A number that resolves to nothing is an answer — a typo, or another repository's number quoted in
+// prose — and it is reported as one. Everything else is a gap, and the message says so, because the
+// caller's next move differs: a gap is retried, an answer is not.
+function report_failure(kind: ReadFailureKind, issue_number: string, misreading: string): void {
+	if (kind === 'missing') {
+		console.error(`✖ issue #${issue_number} does not resolve — check the number and the repository`)
+	} else {
+		console.error(
+			`✖ could not read issue #${issue_number} — a rate limit, expired auth, or a dropped connection. This is not "${misreading}"`,
+		)
+	}
+}
+
+function is_failure_kind(kind: string): kind is ReadFailureKind {
+	return kind === 'missing' || kind === 'unreadable'
+}
+
+function report_one_failure<K extends string>(
+	report: NumberReport<K>,
+	terms: FailureTerms<K>,
+): boolean {
+	const { kind } = report.result
+
+	if (!is_failure_kind(kind)) return false
+
+	report_failure(kind, report.issue_number, terms.misreading)
+
+	return true
+}
+
+// Every number that produced no answer is named, so a caller is told which ones it has no answer for
+// rather than being left to subtract the printed blocks from what it asked. A single failure makes
+// the exit code non-zero.
+function report_failures<K extends string>(
+	reports: ReadonlyArray<NumberReport<K>>,
+	terms: FailureTerms<K>,
+): number {
+	let has_failure = false
+
+	for (const report of reports) {
+		has_failure = report_one_failure(report, terms) || has_failure
+	}
+
+	return has_failure ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+const issue_report_failures = { print_blocks, report_failures }
+
+export type { ReadFailureKind }
+export { issue_report_failures }

package/scripts/issue/issue-scout-cli.ts

@@ -5,7 +5,7 @@ import { epic_audit_logic } from '#scripts/epic/epic-audit'
 import { epic_bundle, type BacklogIssue, type BundleDecision } from '#scripts/epic/epic-bundle'
 import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
 import { epic_bundle_gaps } from '#scripts/epic/epic-bundle-gaps'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import {
@@ -403,16 +403,10 @@ const issue_scout_cli = {
 	NO_REFERENCE_LINE,
 	CLOSED_UNREADABLE_LINE,
 	CLOSED_CEILING_LINE,
-	DRAFT_NUMBER,
 	read_arguments,
 	with_draft_body,
-	draft_of,
-	format_duplicates,
-	format_epic_decision,
-	format_report,
 	scout,
 	run,
-	main,
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))

package/scripts/issue/issue-scout-closed.ts

@@ -1,9 +1,9 @@
-import { git_gh_command } from '#scripts/git/git-gh-command'
-import { EPIC_LABEL, has_any_label } from '#scripts/git/issue-labels'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PAGE_CEILING_CAUSE } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
 import { issue_label_schema } from '#scripts/git/schemas'
 import { z } from 'zod'
+import { EPIC_LABEL, has_any_label } from './issue-labels'
 import type { ScoutIssue } from './issue-scout'
 
 // The closed half of `issue:scout`'s duplicate scan (joshuafolkken/kit#1679), held apart from the CLI

package/scripts/issue/issue-scout.ts

@@ -232,10 +232,8 @@ function find_duplicates(
 
 const issue_scout = {
 	SIMILARITY_THRESHOLD,
-	MIN_SHARED_TOKENS,
 	MAX_CANDIDATES,
 	tokenize,
-	shared_tokens,
 	dice_similarity,
 	find_duplicates,
 }

package/scripts/issue/issue-state-cli.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { issue_report_failures, type ReadFailureKind } from './issue-report-failures'
 import { issue_state, type IssueState } from './issue-state'
 
 // `josh issue:state <N> [<N> ...]` — print each issue's state and labels, in the spelling the
@@ -25,7 +26,6 @@ import { issue_state, type IssueState } from './issue-state'
 // answer as "not CLOSED" would report a child as failed because nobody could reach GitHub. The two
 // are told apart here and neither is a state.
 
-const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const REPO_FLAG = '--repo'
@@ -43,18 +43,13 @@ const READ_CONCURRENCY = 8
 // The two fields, under the names `gh issue view --json` gave them. `git-gh-issue-rest.ts` maps them
 // back from REST, which is what keeps `OPEN` / `CLOSED` / `MERGED` out of this file.
 const STATE_FIELDS = 'state,labels'
+const FAILURE_TERMS = { success_kind: 'state', misreading: 'the issue is open' } as const
 
 interface StateRequest {
 	issue_numbers: ReadonlyArray<string>
 	repo?: string
 }
 
-// The two failure kinds a read can end in, kept apart all the way to the report: `missing` is the
-// number resolving to nothing and `unreadable` is a read that failed, and the documents ask a
-// caller to report the two differently. Folding them together to simplify the batch would destroy
-// exactly that distinction.
-type ReadFailureKind = 'missing' | 'unreadable'
-
 // One issue's state, or the failure kind. Named for export because `run:prep` reads the state beside
 // the body and the dependency-update scope (joshuafolkken/kit#1978), reusing this read rather than a
 // second one that would drift from the `human_review` decision `parse_issue_state` owns.
@@ -146,19 +141,6 @@ function parse_request(argv: ReadonlyArray<string>): StateRequest | undefined {
 	return repo_flag.kind === 'named' ? { issue_numbers, repo: repo_flag.repo } : { issue_numbers }
 }
 
-// A number that resolves to nothing is an answer — a typo, or another repository's number quoted in
-// prose — and it is reported as one. Everything else is a gap, and the message says so, because the
-// caller's next move differs: a gap is retried, an answer is not.
-function report_failure(kind: ReadFailureKind, issue_number: string): void {
-	if (kind === 'missing') {
-		console.error(`✖ issue #${issue_number} does not resolve — check the number and the repository`)
-	} else {
-		console.error(
-			`✖ could not read issue #${issue_number} — a rate limit, expired auth, or a dropped connection. This is not "the issue is open"`,
-		)
-	}
-}
-
 // One number's read, reduced to what the report needs and nothing printed yet. Separating the two
 // is what lets the whole batch be in flight at once: the numbers are independent, so reading them
 // one after the other spends a round trip per number for no reason.
@@ -206,30 +188,7 @@ function print_states(reports: ReadonlyArray<IssueReport>): void {
 	const should_attribute = reports.length > 1
 	const blocks = reports.flatMap((report) => state_blocks(report, should_attribute))
 
-	if (blocks.length === 0) return
-
-	console.info(blocks.join(BLOCK_SEPARATOR))
-}
-
-function report_one_failure(report: IssueReport): boolean {
-	if (report.result.kind === 'state') return false
-
-	report_failure(report.result.kind, report.issue_number)
-
-	return true
-}
-
-// Every number that produced no state is named, so a caller is told which ones it has no answer for
-// rather than being left to subtract the printed blocks from what it asked. A single failure still
-// makes the exit code non-zero, exactly as it did when only one number could be passed.
-function report_failures(reports: ReadonlyArray<IssueReport>): number {
-	let has_failure = false
-
-	for (const report of reports) {
-		has_failure = report_one_failure(report) || has_failure
-	}
-
-	return has_failure ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+	issue_report_failures.print_blocks(blocks, BLOCK_SEPARATOR)
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {
@@ -245,7 +204,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 
 	print_states(reports)
 
-	return report_failures(reports)
+	return issue_report_failures.report_failures(reports, FAILURE_TERMS)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

package/scripts/issue/issue-state.ts

@@ -1,6 +1,6 @@
-import { has_any_label, NEEDS_HUMAN_REVIEW_LABEL } from '#scripts/git/issue-labels'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
+import { has_any_label, NEEDS_HUMAN_REVIEW_LABEL } from './issue-labels'
 
 // The answer `josh issue:state` prints, kept apart from the reading and the printing so the shape of
 // the report is decided by one pure function (joshuafolkken/kit#1054).
@@ -96,10 +96,6 @@ function format_attributed_issue_state(issue_number: string, state: IssueState):
 
 const issue_state = {
 	NO_LABELS,
-	STATE_LABEL,
-	LABELS_LABEL,
-	HUMAN_REVIEW_LABEL_LINE,
-	ISSUE_LABEL,
 	parse_issue_state,
 	format_issue_state,
 	format_attributed_issue_state,

package/scripts/issue/markdown-section.ts

@@ -52,13 +52,16 @@ function has_line(body: string, text: string): boolean {
 	return has_unfenced_line(body, text)
 }
 
-// The lines between `heading` and the next `## ` heading, trimmed of the heading line itself; an empty
-// array when the heading is absent. A heading matched inside a sentence is not the section heading, so
-// only a line that is exactly the heading opens the section.
-function section_lines(body: string, heading: string): ReadonlyArray<string> {
+// The lines between the first unfenced line `is_target` accepts and the next unfenced `## ` heading,
+// trimmed of the heading line itself; an empty array when no line is accepted. A `## ` line inside a
+// code fence is example text, so it neither opens nor closes a section (joshuafolkken/kit#3066).
+function section_lines_matching(
+	body: string,
+	is_target: (line: string) => boolean,
+): ReadonlyArray<string> {
 	const lines = body.split('\n')
 	const visible = unfenced_lines(body)
-	const start = visible.findIndex((line) => is_the_heading(line, heading))
+	const start = visible.findIndex((line) => is_target(line))
 
 	if (start === -1) return []
 
@@ -68,6 +71,18 @@ function section_lines(body: string, heading: string): ReadonlyArray<string> {
 	return end === -1 ? rest : rest.slice(0, end)
 }
 
-const markdown_section = { section_lines, is_heading, has_line, has_unfenced_line }
+// A heading matched inside a sentence is not the section heading, so only a line that is exactly the
+// heading opens the section.
+function section_lines(body: string, heading: string): ReadonlyArray<string> {
+	return section_lines_matching(body, (line) => is_the_heading(line, heading))
+}
+
+const markdown_section = {
+	section_lines,
+	section_lines_matching,
+	unfenced_lines,
+	has_line,
+	has_unfenced_line,
+}
 
 export { markdown_section }

package/scripts/issue/measure-rerun-cli.ts

@@ -1,26 +1,52 @@
 #!/usr/bin/env tsx
 import { execSync } from 'node:child_process'
-import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
 import { error_text } from '#scripts/lib/error-message'
 import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { z } from 'zod'
 import { baseline_measure, type Baseline } from './baseline-measure'
 
-// `josh measure:rerun <path>` — read a behavior-change Issue body after merge, re-run each baseline
+// `josh measure:rerun <N>` — read a behavior-change Issue body after merge, re-run each baseline
 // command, and print the before/after pair (joshuafolkken/kit#2212). A value that did not move means
 // the premise the rule rested on is refuted, so a line is appended to the observation ledger — reusing
 // that append-only, same-key mechanism rather than a second one.
+//
+// **The baseline is shell, and the body is written by whoever filed the Issue** (joshuafolkken/kit#3064).
+// A baseline needs pipes and loops (`git log … | wc -l`, `for d in $(ls …)`), so an allow-list of
+// commands cannot make it safe; what can is who wrote it. The input is therefore the Issue number, not
+// a file, so the author's `author_association` arrives with the body from the same REST read, and only
+// a body written by someone with write access to the repository is run.
 
 const FAILURE_EXIT_CODE = 1
-const USAGE = 'Usage: josh measure:rerun <path-to-issue-body>'
+const ARGV_OFFSET = 2
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const ISSUE_FIELDS = 'body,author_association'
+const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
+const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
+const UNKNOWN_ASSOCIATION = 'unknown'
+const USAGE = 'Usage: josh measure:rerun <issue-number>'
 const NO_BASELINE = 'no `command → value` baseline found in ## ベースライン — nothing to re-run'
 const DATE_END = 10
-
-// The command's stdout, trimmed to one value. A failing command yields its message so the pair still
-// prints rather than aborting the whole re-measurement.
+// One baseline command's budget — the same minute `josh-harness.ts` gives one command it spawns. A
+// baseline is a count or a digest that answers in seconds, so a command still running after a minute
+// is stuck, and without a bound it would hold the whole re-measurement open with nothing printed.
+const MEASURE_TIMEOUT_MS = 60_000
+const issue_schema = z.object({
+	body: z.string().nullish(),
+	author_association: z.string().nullish(),
+})
+
+type IssueFields = z.infer<typeof issue_schema>
+type BodyRead = { kind: 'trusted'; body: string } | { kind: 'refused'; reason: string }
+
+// The command's stdout, trimmed to one value. A failing or timed-out command yields its message so the
+// pair still prints and the remaining baselines still run, rather than aborting the whole
+// re-measurement.
 function measure(command: string): string {
 	try {
-		return execSync(command, { encoding: 'utf8' }).trim()
+		return execSync(command, { encoding: 'utf8', timeout: MEASURE_TIMEOUT_MS }).trim()
 	} catch (error) {
 		return `(command failed: ${error_text.message_of(error)})`
 	}
@@ -56,8 +82,35 @@ function today(now: Date): string {
 	return now.toISOString().slice(0, DATE_END)
 }
 
-async function rerun(body_path: string, now: Date): Promise<number> {
-	const baselines = baseline_measure.parse_baselines(await readFile(body_path, 'utf8'))
+async function read_issue(issue_number: string): Promise<IssueFields | undefined> {
+	const json = await git_gh_issue_read.issue_view_json(issue_number, ISSUE_FIELDS)
+
+	return json === undefined ? undefined : parse_json_object_safe(json, issue_schema)
+}
+
+// The body, only when its author can write to the repository. A read that fails is refused as well:
+// an unknown author is not a trusted one.
+async function read_trusted_body(issue_number: string): Promise<BodyRead> {
+	const issue = await read_issue(issue_number)
+
+	if (issue === undefined) {
+		return { kind: 'refused', reason: `could not read issue #${issue_number}` }
+	}
+
+	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
+
+	if (!TRUSTED_ASSOCIATIONS.has(association)) {
+		return {
+			kind: 'refused',
+			reason: `refusing to run the baseline of #${issue_number}: its author is ${association}, not ${TRUSTED_LIST}`,
+		}
+	}
+
+	return { kind: 'trusted', body: issue.body ?? '' }
+}
+
+async function rerun(body: string, now: Date): Promise<number> {
+	const baselines = baseline_measure.parse_baselines(body)
 
 	if (baselines.length === 0) {
 		console.error(NO_BASELINE)
@@ -76,23 +129,29 @@ async function rerun(body_path: string, now: Date): Promise<number> {
 	return 0
 }
 
-async function run(body_path: string | undefined, now: Date): Promise<number> {
-	if (body_path === undefined) {
+async function run(issue_number: string | undefined, now: Date): Promise<number> {
+	if (issue_number === undefined || !ISSUE_NUMBER_PATTERN.test(issue_number)) {
 		console.error(USAGE)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	return await rerun(body_path, now)
+	const read = await read_trusted_body(issue_number)
+
+	if (read.kind === 'refused') {
+		console.error(read.reason)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await rerun(read.body, now)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv[0], new Date())
 }
 
-const measure_rerun_cli = { run, rerun_one, USAGE, NO_BASELINE }
-
-const ARGV_OFFSET = 2
+const measure_rerun_cli = { run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/issue/reproduction-measure.ts

@@ -53,7 +53,7 @@ function has_command_output(body: string, heading: string = REPRODUCTION_HEADING
 	return reproduction.has_command && reproduction.has_output
 }
 
-const reproduction_measure = { REPRODUCTION_HEADING, has_command_output, parse_reproduction }
+const reproduction_measure = { has_command_output }
 
 export type { Reproduction }
 export { reproduction_measure }

package/scripts/josh/cli-body.ts

@@ -91,6 +91,6 @@ function resolve(input: {
 	return read_file_or_stdin(file_path)
 }
 
-const cli_body = { read_file_or_stdin, expand_escaped_newlines, has_value, resolve }
+const cli_body = { read_file_or_stdin, has_value, resolve }
 
 export { cli_body }

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

@@ -253,11 +253,8 @@ const file_map_stamp = {
 	changed_since,
 	create,
 	describes_base,
-	is_file_map,
-	is_writer_gone,
 	is_writer_running,
 	parse_stamp,
-	read_at,
 }
 
 export type { FileMapStamp, FileMapStampAccess }

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

@@ -40,6 +40,7 @@ const ALIASES: Record<string, string> = {
 	f: 'format',
 	sd: 'cspell:dot',
 	bh: 'behavior',
+	eu: 'exports:unused',
 	t: 'test',
 	tu: 'test:unit',
 	tr: 'test:related',
@@ -62,6 +63,7 @@ const ALIASES: Record<string, string> = {
 	v: 'version',
 	r: 'ranges',
 	dr: 'doctor',
+	rc: 'ruleset:check',
 	pg: 'propagate',
 	ad: 'adopt',
 	ov: 'overrides',

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

@@ -4,10 +4,9 @@ import { DOCUMENT_COMMANDS } from './josh-commands-document'
 import { GUARD_COMMANDS } from './josh-commands-guard'
 import { ISSUE_COMMANDS } from './josh-commands-issue'
 import { LANE_COMMANDS } from './josh-commands-lane'
+import { RUN_COMMANDS } from './josh-commands-run'
 import { SPLIT_COMMANDS } from './josh-commands-split'
 
-// One script answers both `run:hold` and `run:release`; the flag below is what tells them apart.
-const RUN_HOLD_SCRIPT = 'scripts/run/run-hold-cli.ts'
 const ISSUE_WITH_OPTIONS = '<issue> [options]'
 
 /* eslint-disable @typescript-eslint/naming-convention */
@@ -21,7 +20,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<keywords> [--size <n>]', 'automation', ['network']],
 	},
 	'stash:pop': {
-		script: 'scripts/git/stash-pop-cli.ts',
+		script: 'scripts/git/stash/stash-pop-cli.ts',
 		description: 'Pop the stash matching this message, not whichever a shared stack has on top',
 		category: 'AI tools',
 		reference: ['<message>', 'automation', ['git']],
@@ -36,7 +35,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		script: 'scripts/epic/epic-next.ts',
 		description: "List an epic's runnable children, bundled per repository",
 		category: 'AI tools',
-		reference: ['<epic>', 'automation', ['network']],
+		reference: ['<epic>... [--repo <owner/repo>] [--lanes]', 'automation', ['network']],
 	},
 	'epic:bundle': {
 		script: 'scripts/epic/epic-bundle-cli.ts',
@@ -65,9 +64,10 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 	...BACKLOG_COMMANDS,
 	cost: {
 		script: 'scripts/cost-runtime/cost-cli.ts',
-		description: "Report a run's token and credit cost from Claude Code's session transcripts",
+		description:
+			'Say whether the next turn of a run crosses the context-cut threshold (--cut) or a given tokens-per-request figure (--over)',
 		category: 'AI tools',
-		reference: ['[--cut|--over]', 'automation', ['none']],
+		reference: ['(--cut | --over <tokens-per-request>) [--path <dir>]', 'automation', ['none']],
 	},
 	...DOCUMENT_COMMANDS,
 	time: {
@@ -134,100 +134,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<unit-files> <unit-files> [<unit-files> …]', 'automation', ['none']],
 	},
-	'run:hold': {
-		script: RUN_HOLD_SCRIPT,
-		description: 'Claim this working tree for a run, or say which run already holds it',
-		category: 'AI tools',
-		reference: ['[issue]', 'automation', ['files']],
-	},
-	'run:release': {
-		script: RUN_HOLD_SCRIPT,
-		description: "Release this working tree's run record",
-		category: 'AI tools',
-		reference: ['[issue|--force]', 'automation', ['files']],
-		default_script_arguments: ['--release'],
-	},
-	'run:tidy': {
-		script: 'scripts/run/run-tidy-cli.ts',
-		description: 'Close merged lanes and drop stashes whose issues are all merged',
-		category: 'AI tools',
-		reference: ['', 'automation', ['git', 'network', 'files']],
-	},
-	'run:carry': {
-		script: 'scripts/run/run-carry-cli.ts',
-		description: 'Carry one invocation’s budget across its own session cuts',
-		category: 'AI tools',
-		reference: ['<operation> [arguments...]', 'automation', ['files']],
-	},
-	'run:wake': {
-		script: 'scripts/run/run-wake-cli.ts',
-		// `.env` rather than the ambient environment:
-		// the failure warning needs the Telegram credentials, the same
-		// reasons `notify` and `followup` carry these flags.
-		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
-		description: 'Wake the next session of a cut backlogrun from outside the conversation',
-		category: 'AI tools',
-		reference: ['[options]', 'automation', ['processes', 'notifications']],
-	},
-	'run:cut': {
-		script: 'scripts/run/run-cut-cli.ts',
-		description: 'Cut a lane child before the gate and resume a fresh process',
-		category: 'AI tools',
-		reference: ['[--resume] <issue> [--impl] [--handoff <path>]', 'automation', ['files']],
-	},
-	'run:liveness': {
-		script: 'scripts/run/run-liveness-cli.ts',
-		description: 'Say whether a delegated unit is still working, or stopped without reporting',
-		category: 'AI tools',
-		reference: ['<issue> --output <path> [options]', 'automation', ['processes']],
-	},
-	'run:ending': {
-		script: 'scripts/run/run-ending-cli.ts',
-		description: 'Classify how a dispatched lane child ended (merged, cut, abandoned, unreadable)',
-		category: 'AI tools',
-		reference: ['<issue> --output <path> [--repo <owner/repo>]', 'automation', ['network']],
-	},
-	'run:progress': {
-		script: 'scripts/run/run-progress-cli.ts',
-		description: 'Report an unattended run’s progress once it has gone quiet for an interval',
-		category: 'AI tools',
-		reference: ['[--wait|--mark]', 'automation', ['files']],
-	},
-	'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,
-	// 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/run-entry-cli.ts',
-		description:
-			'Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['git', 'network', 'files']],
-	},
-	'run:status': {
-		script: 'scripts/run/run-status-cli.ts',
-		description: 'Bundle a run’s read-only status: issue state, cost verdict, carry counters',
-		category: 'AI tools',
-		reference: ['<issue> [--repo <owner/repo>]', 'automation', ['network']],
-	},
-	'run:next': {
-		script: 'scripts/run/run-next-cli.ts',
-		description: 'Print the next step a fullrun takes, computed from the run’s state',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network']],
-	},
-	'run:step': {
-		script: 'scripts/run/run-step-cli.ts',
-		description:
-			'Print the run’s next single action, computed from the event stream, carry record and issue state',
-		category: 'AI tools',
-		reference: ['<issue>', 'automation', ['network', 'files']],
-	},
+	...RUN_COMMANDS,
 	'repo:party': {
 		script: 'scripts/discovery/repo-party-cli.ts',
 		description:
@@ -255,7 +162,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 	'run:tail': {
 		script: 'scripts/run/run-tail-cli.ts',
 		description:
-			'Close a run in one call: commit the observation ledger, read the citations, decide the release scope',
+			'Close a run in one call: return to the default branch, commit the observation ledger, read the citations, decide the release scope',
 		category: 'AI tools',
 		reference: ['[<issue> ...]', 'automation', ['git', 'network']],
 	},
@@ -269,7 +176,7 @@ const AI_COMMANDS: Record<string, CommandEntry> = {
 			'Ship a change in one call: gate, commit/push/PR, the CI-wait merge and the report bookkeeping, stopping at the first failed step',
 		category: 'AI tools',
 		reference: [
-			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review] [--detach] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
+			'"<title> #<N>" [<follow-up-N> ...] [--cite <N>] [--review] [--detach] [--body-file <path>] [--notify-message <text> | --notify-message-file <path>] | --log <N>',
 			'automation',
 			['git', 'network'],
 		],

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

@@ -33,7 +33,11 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 		description:
 			'Print the whole backlog as a plan: ready now, waiting on what, waiting on a person, out of scope',
 		category: 'AI tools',
-		reference: ['[issue...] [--only]', 'automation', ['network']],
+		reference: [
+			'[issue...] [--only] [--waves] [--exclude <n>[,<n>...]]',
+			'automation',
+			['network'],
+		],
 	},
 	'backlog:stalled': {
 		script: 'scripts/backlog/backlog-stalled-cli.ts',