@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/issue/issue-scout.ts

@@ -4,7 +4,7 @@
 // strong signals: the two issues citing each other in prose, or a `blocked-by` recorded between them.
 // Neither reaches a draft — it has no number, so nothing can cite it and nothing can be recorded
 // against it — and the question a filing entry actually asks first is a different one: has somebody
-// already filed this? (joshuafolkken/kit#1252)
+// already filed this?
 //
 // So this is a second signal rather than a change to that threshold. `epic:bundle` deliberately
 // refuses title resemblance as grounds for *bundling*, because "related" expands without limit; the
@@ -95,8 +95,8 @@ interface ScoutIssue {
 	// already filed as #<E>", and the caller is sent to run an epic that has no implementation of its
 	// own. `epic_bundle.is_strong_signal` excludes them from the other half for the same reason.
 	is_epic?: boolean
-	// A closed issue is a candidate, and the two are not interchangeable to whoever reads the list
-	// (joshuafolkken/kit#1679): an open one says "somebody is already tracking this", a closed one
+	// A closed issue is a candidate, and the two are not interchangeable to whoever reads the list:
+	// an open one says "somebody is already tracking this", a closed one
 	// says "this may already be done". So the state travels with the row rather than being inferred
 	// from which listing it came out of, which the ranking mixes together.
 	is_closed?: boolean
@@ -210,8 +210,7 @@ function compare_candidates(left: DuplicateCandidate, right: DuplicateCandidate)
 //
 // Every row is scored — no prefix, no early exit. The issue this search exists to catch is the one
 // another session filed minutes ago, and where that one sits in the listing is the single thing
-// nobody controls (joshuafolkken/kit#1252). Since joshuafolkken/kit#1679 the rows may be closed as
-// well as open, and the two rank together: a run about to file has to be shown the strongest match
+// nobody controls. The rows may be closed as well as open, and the two rank together: a run about to file has to be shown the strongest match
 // there is, and which listing it came out of says nothing about how well it matches.
 function find_duplicates(
 	title: string,

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

@@ -1,14 +1,14 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { cli_flags } from '#scripts/lib/cli-flags'
 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
-// documents compare against (joshuafolkken/kit#1054; several numbers in one call,
-// joshuafolkken/kit#1302).
+// documents compare against, several numbers in one call.
 //
 // The numbers are read concurrently and reported together because the callers that need more than
 // one need them all: `diag`'s ranking table reads a state per row, and one process start plus one
@@ -29,7 +29,6 @@ import { issue_state, type IssueState } from './issue-state'
 
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
 const USAGE = 'Usage: josh issue:state <issue-number> [<issue-number> ...] [--repo <owner/repo>]'
 // A blank line between the blocks of a multi-number report, so a person sees where one issue ends
 // while a reader matching `issue: ` still finds each block by its first line.
@@ -49,7 +48,7 @@ interface StateRequest {
 }
 
 // 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
+// the body and the dependency-update scope, reusing this read rather than a
 // second one that would drift from the `human_review` decision `parse_issue_state` owns.
 type StateRead = { kind: 'state'; state: IssueState } | { kind: ReadFailureKind }
 
@@ -59,10 +58,9 @@ interface IssueReport {
 }
 
 // The read goes through `cli_flags`, both spellings gh itself accepts included (`--repo owner/repo`,
-// `--repo=owner/repo`), and is strict (joshuafolkken/kit#3261). An unrecognized flag refuses the
-// call: `--rep=owner/repo` used to be discarded for starting with a dash, so the call fell back to
-// the session's repository and printed a confident state for a *different* repository's issue of
-// that number (joshuafolkken/kit#1355).
+// `--repo=owner/repo`), and is strict. An unrecognized flag refuses the
+// call: discarding `--rep=owner/repo` for starting with a dash would fall back to the session's
+// repository and print a confident state for a *different* repository's issue of that number.
 const OPTIONS = { repo: { type: 'string', multiple: true } } as const
 
 // `absent` and "given but with nothing usable" are different answers. Falling back to the session's
@@ -81,7 +79,8 @@ function read_repo(given: ReadonlyArray<string> | undefined): { repo?: string }
 // unanswered. `#1262` copied out of a `diag` table is exactly that token.
 function is_issue_numbers(positionals: ReadonlyArray<string>): boolean {
 	return (
-		positionals.length > 0 && positionals.every((argument) => ISSUE_NUMBER_PATTERN.test(argument))
+		positionals.length > 0 &&
+		positionals.every((argument) => issue_number_shape.is_issue_number(argument))
 	)
 }
 
@@ -167,7 +166,15 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const issue_state_cli = { STATE_FIELDS, USAGE, main, parse_request, read_issue, run }
+const issue_state_cli = {
+	READ_CONCURRENCY,
+	STATE_FIELDS,
+	USAGE,
+	main,
+	parse_request,
+	read_issue,
+	run,
+}
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 

package/scripts/issue/issue-state.ts

@@ -1,24 +1,23 @@
-import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined } 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).
+// the report is decided by one pure function.
 //
-// The command exists because the *instructions* needed one. `gh issue view <N> --json state` is what
-// an unattended epic run was told to type to confirm a delegated child, and gh answers that call
-// over GraphQL — which a cloud session is refused (403). The REST endpoint is served normally, but
-// it reports `open` / `closed` in lower case, so writing the REST call into the documents would have
-// copied the casing rule out of `git-gh-rest-state.ts` and into prose. Routing the instruction
-// through a command keeps that rule in the one place joshuafolkken/kit#1024 put it.
+// The command exists because the *instructions* need one. `gh issue view <N> --json state` goes over
+// GraphQL — which a cloud session is refused (403). The REST endpoint is served normally, but it
+// reports `open` / `closed` in lower case, so writing the REST call into the documents would copy the
+// casing rule out of `git-gh-rest-state.ts` and into prose. Routing the instruction through a command
+// keeps that rule in one place.
 
 const NO_LABELS = '(none)'
 const LABEL_SEPARATOR = ', '
 const STATE_LABEL = 'state: '
 const LABELS_LABEL = 'labels: '
 // Whether this issue is one a run must stop on before committing. Printed as its own line rather than
-// left to a reader matching `needs-human-review` against the `labels:` line above
-// (joshuafolkken/kit#1132): GitHub keeps the spelling a label was created with and treats
+// left to a reader matching `needs-human-review` against the `labels:` line above:
+// GitHub keeps the spelling a label was created with and treats
 // `Needs-Human-Review` as the same label, so an eye comparing against the lowercase string misses it —
 // and a missed one is a run that does not stop and an artifact that ships, which is the whole thing
 // the label exists to prevent. Every other workflow label already reaches its decision through
@@ -26,8 +25,8 @@ const LABELS_LABEL = 'labels: '
 const HUMAN_REVIEW_LABEL_LINE = 'human_review: '
 const YES = 'yes'
 const NO = 'no'
-// The number a block belongs to, printed above it when several were asked for
-// (joshuafolkken/kit#1302). A block carries its own number rather than being matched by position,
+// The number a block belongs to, printed above it when several were asked for.
+// A block carries its own number rather than being matched by position,
 // because a batch read drops the numbers that resolve to nothing — a `diag` table mixes closed
 // issues and numbers that never existed — and a positional reading then attributes every block
 // after the gap to the wrong issue.
@@ -58,7 +57,7 @@ interface IssueState {
 // the same answer, because printing either as a state is what this command exists to prevent.
 function parse_issue_state(json: string): IssueState | undefined {
 	try {
-		const parsed = parse_json_object_safe(json, issue_state_schema)
+		const parsed = parse_json_object_or_undefined(json, issue_state_schema)
 
 		if (parsed === undefined) return undefined
 

package/scripts/issue/issue-wip.ts

@@ -1,11 +1,11 @@
-import { delivered_rules } from '#scripts/rules/delivered-rules'
 import { INTERRUPT_ROUTE_LABEL, SPLIT_ROUTE_LABEL, TIER_A_ROUTE_LABEL } from './issue-labels'
 
-// The WIP cap at the call that files (joshuafolkken/kit#3181). The count used to be a hand-run
-// `gh api … | wc -l` the agent compared with the cap itself; `josh issue:file` now reads it and asks
-// the exemption question before anything is sent, the same hold `--distinct` places on a duplicate.
+// The WIP cap at the call that files. `josh issue:file` reads the count and asks the exemption
+// question before anything is sent, the same hold `--distinct` places on a duplicate.
 // What stays judgement — whether a filing is exempt — is declared by the route or by `--over-cap`.
 
+// `WIP_CAP` is the number's single source; `wip-cap.md` states it once and a test pins the two equal.
+const WIP_CAP = 30
 const WITHIN = 'within'
 const EXEMPT = 'exempt'
 const HELD = 'held' as const
@@ -43,13 +43,13 @@ function is_exempt(filing: WipFiling): boolean {
 
 // The cap is "more than `WIP_CAP` open", so exactly the cap is still within it.
 function verdict_of(count: number, filing: WipFiling): WipVerdict {
-	if (count <= delivered_rules.WIP_CAP) return WITHIN
+	if (count <= WIP_CAP) return WITHIN
 
 	return is_exempt(filing) ? EXEMPT : HELD
 }
 
 function count_line(count: number, repo: string, verdict: WipVerdict): string {
-	return `wip: ${String(count)} open in ${repo} · cap ${String(delivered_rules.WIP_CAP)} · ${verdict}`
+	return `wip: ${String(count)} open in ${repo} · cap ${String(WIP_CAP)} · ${verdict}`
 }
 
 // The listing's JSON is an array of rows; anything else is unreadable rather than zero, because zero
@@ -64,7 +64,7 @@ function count_of(json: string): number | undefined {
 	}
 }
 
-const issue_wip = { HELD, HELD_MESSAGE, UNREAD_MESSAGE, verdict_of, count_line, count_of }
+const issue_wip = { WIP_CAP, HELD, HELD_MESSAGE, UNREAD_MESSAGE, verdict_of, count_line, count_of }
 
 export type { WipVerdict }
 export { issue_wip }

package/scripts/issue/markdown-section.ts

@@ -1,5 +1,5 @@
-// The body lines that sit under one `## heading`, up to the next `## heading` or the end
-// (joshuafolkken/kit#2212). Both the firing-point check and the baseline parser read a section this
+// The body lines that sit under one `## heading`, up to the next `## heading` or the end.
+// Both the firing-point check and the baseline parser read a section this
 // way, so the slicing lives in one place rather than being written twice.
 
 const HEADING_PREFIX = '## '
@@ -54,7 +54,7 @@ function has_line(body: string, text: string): boolean {
 
 // 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).
+// code fence is example text, so it neither opens nor closes a section.
 function section_lines_matching(
 	body: string,
 	is_target: (line: string) => boolean,

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

@@ -2,18 +2,20 @@
 import { execSync } from 'node:child_process'
 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 { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 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'
+import { session_cite } from './session-cite'
 
 // `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
+// command, and print the before/after pair. 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).
+// **The baseline is shell, and the body is written by whoever filed the Issue**.
 // 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
@@ -21,7 +23,6 @@ import { baseline_measure, type Baseline } from './baseline-measure'
 
 const FAILURE_EXIT_CODE = 1
 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(' / ')
@@ -71,7 +72,7 @@ async function append_ledger(lines: ReadonlyArray<string>, now: Date): Promise<v
 	if (lines.length === 0) return
 
 	// The running work tree's file for the checked-out issue, a lane's inside a lane — the run's own
-	// commit carries it (joshuafolkken/kit#2919).
+	// commit carries it.
 	const ledger_path = await observation_ledger_home.writer_path(now)
 
 	await observation_ledger_home.append(ledger_path, lines)
@@ -85,7 +86,7 @@ function today(now: Date): string {
 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)
+	return json === undefined ? undefined : parse_json_object_or_undefined(json, issue_schema)
 }
 
 // The body, only when its author can write to the repository. A read that fails is refused as well:
@@ -94,7 +95,7 @@ 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}` }
+		return { kind: 'refused', reason: `could not read issue ${session_cite.issue(issue_number)}` }
 	}
 
 	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
@@ -102,7 +103,7 @@ async function read_trusted_body(issue_number: string): Promise<BodyRead> {
 	if (!TRUSTED_ASSOCIATIONS.has(association)) {
 		return {
 			kind: 'refused',
-			reason: `refusing to run the baseline of #${issue_number}: its author is ${association}, not ${TRUSTED_LIST}`,
+			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${TRUSTED_LIST}`,
 		}
 	}
 
@@ -130,7 +131,7 @@ async function rerun(body: string, now: Date): Promise<number> {
 }
 
 async function run(issue_number: string | undefined, now: Date): Promise<number> {
-	if (issue_number === undefined || !ISSUE_NUMBER_PATTERN.test(issue_number)) {
+	if (issue_number === undefined || !issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)) {
 		console.error(USAGE)
 
 		return FAILURE_EXIT_CODE

package/scripts/issue/reproduction-measure.ts

@@ -1,8 +1,8 @@
 import { markdown_section } from './markdown-section'
 
 // A defect-claiming (behavior-change) Issue's reproduction section is written as `command + actual
-// output`, never prose, so the claim rests on a run that can be repeated rather than on a reading
-// (joshuafolkken/kit#2353). This is the counterpart of `baseline-measure.ts`: the baseline is a
+// output`, never prose, so the claim rests on a run that can be repeated rather than on a reading.
+// This is the counterpart of `baseline-measure.ts`: the baseline is a
 // distilled `command -> value`, the reproduction is the raw command *and* the output block it printed
 // — a prose "I checked it" is refused for the same reason a prose baseline is, it cannot be re-run.
 
@@ -38,7 +38,7 @@ function has_output_block(lines: ReadonlyArray<string>): boolean {
 }
 
 // The heading is a parameter so every `command + actual output` section is read by this one parser —
-// a pull request's live-execution evidence section is the same shape (joshuafolkken/kit#2446).
+// a pull request's live-execution evidence section is the same shape.
 function parse_reproduction(body: string, heading: string = REPRODUCTION_HEADING): Reproduction {
 	const lines = markdown_section.section_lines(body, heading)
 

package/scripts/issue/session-cite.ts

@@ -0,0 +1,56 @@
+import { repo_discovery } from '#scripts/discovery/repo-discovery'
+import { repo_origin } from '#scripts/discovery/repo-origin'
+import { issue_citation } from '#scripts/rules/issue-citation'
+import { issue_cite } from './issue-cite'
+
+// How a josh command names an Issue in what it prints to the session.
+//
+// **A line a command prints is a line a session copies.** A run quotes a progress line, a warning or a
+// refusal into its reply verbatim, and a bare `#N` in that line reaches the reply as a bare `#N` — which
+// the Stop guard then sends back for a second turn spent re-citing it. Printing the citation form at the
+// source makes the cheap path and the correct path the same one, the reasoning `issue:cite` itself was
+// built on.
+//
+// **The repository is read from the work tree's own `origin`, not asked of `gh`.** Most printing sites
+// hold no `owner/repo`, and a network read per printed line would put a round trip — and a way to fail
+// — into every warning. The config is a local file (`repo_discovery.read_origin_url`), and it is the
+// same remote `gh` expands `{owner}/{repo}` from, so the link points at the repository the command acts
+// on. A work tree with no GitHub origin falls back to the plain `#N`, the same fallback `reference` has.
+//
+// **The title is used when the caller already holds it, and never fetched.** A link without a title
+// still resolves to the Issue in one click and passes the Stop guard as cited; fetching a title per line
+// would cost the `gh` call this module exists to avoid.
+//
+// **A line assembled elsewhere is linked where it is printed.** A summary, a report or a list built by
+// a helper that also feeds GitHub or a parser holds `issue_cite.plain`; `text` links every bare `#N` in
+// it at the print boundary, the same `issue_citation.linkify` pass the listings already print through.
+
+// `owner/repo` of the repository the command runs in, or `undefined` without a GitHub `origin`.
+function session_repo(): string | undefined {
+	const url = repo_discovery.read_origin_url(process.cwd())
+	const identity = url === undefined ? undefined : repo_origin.parse_origin_url(url)
+
+	return identity === undefined ? undefined : `${identity.owner}/${identity.repo}`
+}
+
+// One Issue as a session reads it: `[#N](url) — title` with a title, `[#N](url)` without one. `repo`
+// names another repository's Issue; it defaults to the one the command runs in.
+function issue(number: number | string, title?: string, repo = session_repo()): string {
+	return issue_cite.reference(repo, String(number), title)
+}
+
+// `message` as a session reads it: every bare `#N` linked to the repository the command runs in, left
+// as it is without a GitHub `origin`.
+function text(message: string): string {
+	const repo = session_repo()
+
+	return repo === undefined ? message : issue_citation.linkify(message, repo)
+}
+
+const session_cite = {
+	issue,
+	session_repo,
+	text,
+}
+
+export { session_cite }

package/scripts/josh/agent-session-environment.ts

@@ -1,24 +1,25 @@
 // The environment variables that name the **parent** agent session, and which a child session must
 // not inherit.
 //
-// It lived inside `scripts/eval/eval-session.ts` until `josh run:wake` became a second launcher of a
-// headless session (joshuafolkken/kit#1719). Two copies of this list is the clone `CLAUDE.md`
+// `scripts/eval/eval-session.ts` and `josh run:wake` both launch a headless session. Two copies of
+// this list is the clone `CLAUDE.md`
 // prohibits, and this is the shape of clone that fails silently: the copy that drifts does not throw
 // or lint — the child dials the parent's private socket, is refused, and the session dies as
 // `API Error: Unable to connect to API (ConnectionRefused)` with nothing anywhere naming the cause.
 //
 // `CLAUDE_CODE_MESSAGING_SOCKET` is a UNIX socket only the parent listens on,
 // `CLAUDE_CODE_MESSAGING_TOKEN` is that socket's credential, and the two session identifiers claim
-// the parent's session as the child's own. Measured under joshuafolkken/kit#1158: removing them
-// restored 5/5 held in 54 seconds, and lowering the concurrency — the suspected cause before this one
-// was found — made it worse.
+// the parent's session as the child's own.
 //
 // **`SESSION_ID_KEY` is the name Claude Code exports for the running session's own id** — the base
 // name of that session's transcript file. It is single-sourced here rather than spelled a second time
-// where the cost reader identifies its own transcript by it (joshuafolkken/kit#2403): one env var,
+// where the cost reader identifies its own transcript by it: one env var,
 // one literal, so the list a child must not inherit and the selection that reads it cannot drift.
 const SESSION_ID_KEY = 'CLAUDE_CODE_SESSION_ID'
 
+// The pid of the agent session's own process, which a run hold records as its owner.
+const AGENT_PID_KEY = 'CLAUDE_PID'
+
 const PARENT_SESSION_KEYS: ReadonlyArray<string> = [
 	'CLAUDE_CODE_MESSAGING_SOCKET',
 	'CLAUDE_CODE_MESSAGING_TOKEN',
@@ -27,7 +28,7 @@ const PARENT_SESSION_KEYS: ReadonlyArray<string> = [
 ]
 
 // **The second thing a child must not inherit is a proxy that belongs to the invocation which
-// launched it** (joshuafolkken/kit#1760). `pnpm josh run:wake --start` runs under whatever wraps this
+// launched it**. `pnpm josh run:wake --start` runs under whatever wraps this
 // machine's package manager — here a supply-chain scanner, which stands a proxy up on a loopback port
 // and writes `HTTPS_PROXY=http://localhost:<ephemeral>` plus its own CA into the environment of
 // everything that invocation spawns. The supervisor is **detached**, so it outlives that proxy and
@@ -158,7 +159,7 @@ function is_scanner_proxy(source: EnvironmentSource): (value: string | undefined
 	}
 }
 
-// **The proxy half alone, for a spawn that is not a session** (joshuafolkken/kit#2436). kit's `gh`
+// **The proxy half alone, for a spawn that is not a session**. kit's `gh`
 // requests inherited the same loopback proxy, and the scanner behind it tunnels api.github.com
 // without inspecting it — so routing GitHub through it protected nothing and added a failure point:
 // the scanner release installed here marked a host it had once timed out on as dead for the rest of
@@ -176,6 +177,7 @@ function removed_proxy_environment(source: EnvironmentSource = process.env): Rem
 }
 
 const agent_session_environment = {
+	AGENT_PID_KEY,
 	LOOPBACK_HOSTS,
 	PARENT_SESSION_KEYS,
 	PROXY_CERTIFICATE_KEY,

package/scripts/josh/cli-body.ts

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

package/scripts/josh/command-suggest.ts

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

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

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