@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/issue/issue-release.ts

@@ -0,0 +1,58 @@
+import { DEPTH_0_LABEL, RELEASE_LABEL } from './issue-labels'
+
+// The decisions behind `josh issue:release`, kept apart from the command
+// that reads the network so each is a pure answer a test can pin. An Issue whose change reaches a
+// consumer only once published is linked to the repository's release Issue, which it blocks until it
+// merges.
+
+interface ListingRow {
+	number: number
+}
+
+function is_listing_row(value: unknown): value is ListingRow {
+	if (typeof value !== 'object' || value === null) return false
+
+	return Number.isSafeInteger(Reflect.get(value, 'number'))
+}
+
+// The open release Issue a listing of `release`-labelled Issues names, or `undefined` when it names
+// none or is unreadable. One release publishes every merge since the last, so a repository holds one
+// release Issue at a time; were a person to open a second, the oldest is the one the next release
+// closes, so it is the one every new blocker joins.
+function open_release_of(json: string): number | undefined {
+	try {
+		const parsed: unknown = JSON.parse(json)
+		const rows = Array.isArray(parsed) ? parsed.filter((row) => is_listing_row(row)) : []
+
+		return rows.length === 0 ? undefined : Math.min(...rows.map((row) => row.number))
+	} catch {
+		return undefined
+	}
+}
+
+function title_of(repo: string): string {
+	return `Release ${repo} (next version)`
+}
+
+// Plain English with no classification declaration: the Issue is not filed through `issue:file`, and
+// its labels are `RELEASE_LABELS` rather than read off the body.
+function body_of(repo: string): string {
+	return [
+		`Tracks the next release of ${repo}.`,
+		'',
+		'Every Issue this one is blocked by changes something a consumer can use only once it is published. Once they have merged, a person runs `pnpm josh release` in the primary checkout.',
+		'',
+		'Close this Issue once that release is published: the next blocker files a new one, so an open release Issue names only unreleased work.',
+		'',
+		'`auto-ok` is never applied to this Issue by a run; a person may apply it.',
+		'',
+	].join('\n')
+}
+
+// The release label and a depth: the subject of a release is what a consumer touches.
+// Never `auto-ok`.
+const RELEASE_LABELS: ReadonlyArray<string> = [RELEASE_LABEL, DEPTH_0_LABEL]
+
+const issue_release = { RELEASE_LABELS, open_release_of, title_of, body_of }
+
+export { issue_release }

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

@@ -1,6 +1,7 @@
 import { capped_output } from '#scripts/document/capped-print'
+import { session_cite } from './session-cite'
 
-// The failure report `issue:read` and `issue:state` share (joshuafolkken/kit#3046). Both read a batch
+// The failure report `issue:read` and `issue:state` share. 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.
 
@@ -25,7 +26,7 @@ interface FailureTerms<K extends string> {
 }
 
 // Under the Bash output cap, or as part files past it — a batch of long threads is the shape that
-// overflowed (joshuafolkken/kit#3143).
+// overflowed.
 function print_blocks(blocks: ReadonlyArray<string>, separator: string, label: string): void {
 	if (blocks.length === 0) return
 
@@ -37,10 +38,12 @@ function print_blocks(blocks: ReadonlyArray<string>, separator: string, label: s
 // 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`)
+		console.error(
+			`✖ issue ${session_cite.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}"`,
+			`✖ could not read issue ${session_cite.issue(issue_number)} — a rate limit, expired auth, or a dropped connection. This is not "${misreading}"`,
 		)
 	}
 }

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

@@ -15,13 +15,14 @@ import {
 	type ScoutIssue,
 } from './issue-scout'
 import { issue_scout_closed, type ClosedScan } from './issue-scout-closed'
+import { session_cite } from './session-cite'
 
 const { CLOSED_CEILING_LINE, CLOSED_UNREADABLE_LINE, read_recently_closed, warn_about_closed } =
 	issue_scout_closed
 
 // `josh issue:scout "<title>" [--body "<summary>"]` — before an issue is filed, answer the two
 // questions every `new` entry point asks first: has this already been filed, and which epic does it
-// belong to (joshuafolkken/kit#1252).
+// belong to.
 //
 // Both were assembled by hand every time, differently every time: a measured `fullrun new` spent
 // 7 minutes 32 seconds — 22% of the run — listing epics, reading their children and searching for
@@ -104,13 +105,13 @@ function draft_of(args: ScoutArguments, repo: string): BacklogIssue {
 // below decides from prose references, and a title-only draft has none to give it.
 function format_duplicate(candidate: DuplicateCandidate): string {
 	const score = candidate.is_referenced === true ? 'ref' : candidate.score.toFixed(SCORE_DIGITS)
-	const epic = candidate.epic === undefined ? '' : ` (epic #${String(candidate.epic)})`
+	const epic = candidate.epic === undefined ? '' : ` (epic ${session_cite.issue(candidate.epic)})`
 	// The reader does two different things with the two states, so the row has to say which it is: an
 	// open candidate means somebody is already tracking this, a closed one means it may already be
 	// done — and the second is the exit `issue-comments.md` names, not a second filing.
 	const closed = candidate.is_closed === true ? ' (closed)' : ''
 
-	return `  #${String(candidate.number)}  ${score}  ${candidate.title}${closed}${epic}`
+	return `  ${session_cite.issue(candidate.number)}  ${score}  ${candidate.title}${closed}${epic}`
 }
 
 // Weak matches are not padding for an empty answer: a list nobody trusts is read once and skipped
@@ -147,7 +148,7 @@ const NO_EPIC_LINE = 'Epic: none — file it standalone; nothing open shares a r
 function format_epic(decision: BundleDecision): Array<string> {
 	const lines = [`Epic: ${epic_bundle_cli.ACTION_LINES[decision.action] ?? ''}`]
 
-	if (decision.epic !== undefined) lines.push(`  Target epic: #${String(decision.epic)}`)
+	if (decision.epic !== undefined) lines.push(`  Target epic: ${session_cite.issue(decision.epic)}`)
 
 	if (decision.candidates.length > 0) {
 		lines.push(`  Related: ${epic_bundle_cli.format_numbers(decision.candidates)}`)
@@ -168,9 +169,9 @@ const NO_REFERENCE_LINE =
 	'Epic: not asked — no issue number in the summary. Pass --body "…#<N>…", or take the epic printed beside a duplicate above.'
 
 // Every placing verdict above asserts that no epic already tracks the draft's relatives, and a cut
-// epic listing cannot support that: `epic:bundle` withholds them for it (joshuafolkken/kit#1697),
+// epic listing cannot support that: `epic:bundle` withholds them for it,
 // while this command drew the same lines out of `ACTION_LINES` and never passed through the gate that
-// does (joshuafolkken/kit#1703). The verdict is `epic:bundle`'s own, reused rather than restated, with
+// does. The verdict is `epic:bundle`'s own, reused rather than restated, with
 // only the `Epic:` label the rest of this report is read by put in front of it.
 function format_unconfirmed_epic(decision: BundleDecision): string {
 	const related = epic_bundle_cli.format_numbers(decision.candidates)
@@ -245,7 +246,7 @@ function format_epic_answer(
 // The closed rows reach the duplicate half only. `decide_bundle` places a draft among issues that
 // are still being worked on, and a closed one can neither gain a sibling nor be recommended as an
 // epic — so widening the placement pool with them would answer a different question from the one it
-// was asked (joshuafolkken/kit#1679).
+// was asked.
 function duplicates_of(
 	draft: BacklogIssue,
 	issues: ReadonlyArray<BacklogIssue>,
@@ -292,8 +293,7 @@ function qualify_duplicate_report(report_text: string, is_incomplete: boolean):
 }
 
 // The report a run copies into its reply, with every `#N` in the `Related:` / `Target epic:` /
-// duplicate listings linkified so the references it carries are clickable rather than bare
-// (joshuafolkken/kit#2329).
+// duplicate listings linkified so the references it carries are clickable rather than bare.
 function linkified_report(
 	draft: BacklogIssue,
 	widened: Widened,
@@ -315,7 +315,7 @@ function linkified_report(
 }
 
 // The scan's answer in both shapes it is read in: the report a person reads, and the candidate numbers
-// `issue:file` holds a filing to (joshuafolkken/kit#2808).
+// `issue:file` holds a filing to.
 interface ScoutOutcome {
 	report: string
 	candidates: ReadonlyArray<number>
@@ -335,7 +335,7 @@ async function scout(args: ScoutArguments, repo: string): Promise<ScoutOutcome |
 
 	const draft = draft_of(args, repo)
 	// A reference the open listing cannot show — the parent that merged minutes ago — is read directly,
-	// the same widening `epic:bundle` does and for the same reason (joshuafolkken/kit#947). The closed
+	// the same widening `epic:bundle` does and for the same reason. The closed
 	// listing needs nothing from it, so the two requests go out together.
 	const [widened, closed] = await Promise.all([
 		epic_bundle_cli.widen_with_referenced(draft, backlog),

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

@@ -6,11 +6,11 @@ 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
-// so the command that reports the scan and the one that files after it (`issue:file`,
-// joshuafolkken/kit#2808) read one listing rather than two.
+// The closed half of `issue:scout`'s duplicate scan, held apart from the CLI
+// so the command that reports the scan and the one that files after it (`issue:file`) read one
+// listing rather than two.
 
-// How far back the closed half of the scan reaches (joshuafolkken/kit#1679). One page: the duplicate
+// How far back the closed half of the scan reaches. One page: the duplicate
 // this half exists to catch closed hours ago, not months, and the listing is ordered by update so
 // the newest hundred already covers a run's own day several times over.
 //

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,