@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/lane/lane-measure-cli.ts

@@ -4,16 +4,18 @@ import { fileURLToPath } from 'node:url'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { lane_capacity } from './lane-capacity'
 import { lane_ledger } from './lane-ledger'
-import { lane_load } from './lane-load'
+import { lane_sampler, type MeasureContext } from './lane-sampler'
+import { lane_stage_stats } from './lane-stage-stats'
 import { lane_stats } from './lane-stats'
 
-// `josh lane:sample` / `josh lane:stats` — the lane-limit measurement (joshuafolkken/kit#3355).
+// `josh lane:sample` / `josh lane:stats` — the lane-limit measurement.
 //
 // `lane:sample` appends one machine-load sample to the ledger, or one every `--every <seconds>` until it
 // is stopped; `lane:stats` reduces a period of the ledger to the one table row #3347 records per lane
-// limit. The merges and the gates write themselves (`run:merge`, `josh gate`), so a person runs only
-// the sampler beside a `backlogrun` and closes the period with `lane:stats`. The procedure is
-// `docs/maintainers/lane-limit-measurement.md`.
+// limit, and under it the per-stage durations of the period's lanes. Every entry writes itself during
+// a `backlogrun` — the merges, the gates, the stages, and the load `backlog:drive` samples while it
+// runs — so a person only closes the period with `lane:stats`; `lane:sample` is for a load reading
+// outside one. The procedure is `docs/maintainers/lane-limit-measurement.md`.
 
 const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
@@ -28,12 +30,6 @@ const USAGE = [
 const SAMPLE_OPTIONS = { every: { type: 'string' } } as const
 const STATS_OPTIONS = { period: { type: 'string' }, limit: { type: 'string' } } as const
 
-// Where the ledger is and what "now" is, overridable so a test reads a fixed ledger at a fixed instant.
-interface MeasureContext {
-	ledger_path?: string
-	now_ms?: number
-}
-
 function refuse(): number {
 	console.error(USAGE)
 
@@ -47,12 +43,6 @@ function positive(text: string | undefined): number | undefined {
 	return text !== undefined && Number.isFinite(value) && value > 0 ? value : undefined
 }
 
-async function take_sample(context: MeasureContext): Promise<void> {
-	const at = new Date(context.now_ms ?? Date.now()).toISOString()
-
-	await lane_ledger.record(await lane_load.sample(at), context.ledger_path)
-}
-
 // The `--every` interval: `{ seconds: undefined }` for a single sample, `undefined` for a refusal.
 function sample_interval(rest: ReadonlyArray<string>): { seconds: number | undefined } | undefined {
 	const values = cli_flags.values_of(rest, SAMPLE_OPTIONS)
@@ -71,7 +61,7 @@ function sample_interval(rest: ReadonlyArray<string>): { seconds: number | undef
 async function keep_sampling(context: MeasureContext, seconds: number): Promise<void> {
 	const ticks = every(seconds * MS_PER_SECOND, context)
 
-	for await (const tick_context of ticks) await take_sample(tick_context)
+	for await (const tick_context of ticks) await lane_sampler.take(tick_context)
 }
 
 // One sample now, then — with `--every` — one per interval.
@@ -83,7 +73,7 @@ async function sample_command(
 
 	if (interval === undefined) return refuse()
 
-	await take_sample(context)
+	await lane_sampler.take(context)
 
 	if (interval.seconds !== undefined) await keep_sampling(context, interval.seconds)
 
@@ -92,10 +82,10 @@ async function sample_command(
 
 // The label defaults to the limit this process reads, which is the period's limit only when nobody
 // changed it since — `--limit` names it outright.
-function limit_label(given: string | undefined): string {
+async function limit_label(given: string | undefined): Promise<string> {
 	if (given !== undefined) return given
 
-	const choice = lane_capacity.lane_limit()
+	const choice = await lane_capacity.lane_limit()
 
 	return choice.kind === 'limit' ? String(choice.limit) : lane_stats.MISSING
 }
@@ -118,10 +108,11 @@ async function stats_command(
 	if (values === undefined || period_days === undefined) return refuse()
 
 	const window = lane_stats.window_of(period_days, context.now_ms ?? Date.now())
-	const label = { limit: limit_label(values.limit), period_days }
-	const row = lane_stats.row(await read_ledger(context), window, label)
+	const label = { limit: await limit_label(values.limit), period_days }
+	const entries = await read_ledger(context)
+	const row = lane_stats.row(entries, window, label)
 
-	console.info(`${lane_stats.header()}\n${row}`)
+	console.info(`${lane_stats.header()}\n${row}\n\n${lane_stage_stats.table(entries, window)}`)
 
 	return 0
 }
@@ -145,5 +136,4 @@ const lane_measure_cli = {
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
-export type { MeasureContext }
 export { lane_measure_cli }

package/scripts/lane/lane-occupancy.ts

@@ -1,5 +1,7 @@
+import { session_cite } from '#scripts/issue/session-cite'
+
 // The difference between the issues an `in-progress` label says are running and the lanes that are
-// actually open (joshuafolkken/kit#2235).
+// actually open.
 //
 // `epic:next` counts lane occupancy from the `in-progress` label list; `lane:list` reads the work
 // trees that are actually open. Nothing named the difference, so a session read hand-made signals —
@@ -69,15 +71,15 @@ function classify(in_progress: ReadonlyArray<number>, lanes: LaneRead): Occupanc
 }
 
 function stopped_line(issue: number): string {
-	return `⚠ ${STOPPED} #${String(issue)} — carries \`in-progress\` but no lane is open — a stale label. Remove it if the run is done (labels are a person's to change), or reopen the lane.`
+	return `⚠ ${STOPPED} ${session_cite.issue(issue)} — carries \`in-progress\` but no lane is open — a stale label. Remove it if the run is done (labels are a person's to change), or reopen the lane.`
 }
 
 function unknown_line(issue: number): string {
-	return `⚠ ${UNKNOWN} #${String(issue)} — carries \`in-progress\` but the lane listing could not be read, so whether its lane is live is unknown — do not treat it as stopped.`
+	return `⚠ ${UNKNOWN} ${session_cite.issue(issue)} — carries \`in-progress\` but the lane listing could not be read, so whether its lane is live is unknown — do not treat it as stopped.`
 }
 
 function without_label_line(issue: number): string {
-	return `⚠ a lane is open for #${String(issue)} but it carries no \`in-progress\` label — another session could claim the same issue. Apply the label or close the lane (a person's, never this command's).`
+	return `⚠ a lane is open for ${session_cite.issue(issue)} but it carries no \`in-progress\` label — another session could claim the same issue. Apply the label or close the lane (a person's, never this command's).`
 }
 
 function labelled_lines(labelled: ReadonlyArray<LabelledIssue>): Array<string> {

package/scripts/lane/lane-open.ts

@@ -2,6 +2,7 @@ import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { session_cite } from '#scripts/issue/session-cite'
 import { file_reader } from '#scripts/lib/read-file'
 import { lane_cache } from './lane-cache'
 import { lane_environment } from './lane-environment'
@@ -12,8 +13,7 @@ import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_seed_policy } from './lane-seed'
 import { lane_start_point } from './lane-start-point'
 
-// Opening a lane: one linked work tree, one branch, one port seed, and the dependencies to run in it
-// (joshuafolkken/kit#1490, joshuafolkken/kit#1554).
+// Opening a lane: one linked work tree, one branch, one port seed, and the dependencies to run in it.
 //
 // **The reading side of a linked work tree already worked; only the creating side was missing.**
 // `git_directories()` resolves the tree's own git directory, `run-hold.ts` keys its record on it and
@@ -41,7 +41,7 @@ const FULL_OUTCOME: OpenOutcome = { kind: 'full' }
 // `lane_paths.SEAT_LOCK_DIR`, in the lanes root and clear of the lanes themselves (which are numbered, never dot-prefixed). The claim
 // is what closes the gap between reading the free seats and writing the lane's `.env`: two
 // `lane:open` runs that both saw seat 1 free cannot both create the same lock, so the loser steps to
-// the next free seat (joshuafolkken/kit#1494). The lock is released once the lane's `.env` is on
+// the next free seat. The lock is released once the lane's `.env` is on
 // disk and the seat is discoverable — or on any failure — so only a hard crash mid-open can strand
 // one, which removing the lanes-root `.seat-locks` directory clears.
 const SEAT_LOCK_PREFIX = 'seat-'
@@ -132,8 +132,8 @@ function reserve_seat(root: string, free: ReadonlyArray<number>): SeatReservatio
  * collision nothing reports until an E2E run fails somewhere else. Failing here names the lane and
  * what to do about it.
  *
- * **A lane git already lists but whose `.env` is not yet on disk is mid-open, not broken**
- * (joshuafolkken/kit#2147). It holds a seat lock from its seat claim until its `.env` write — the
+ * **A lane git already lists but whose `.env` is not yet on disk is mid-open, not broken**.
+ * It holds a seat lock from its seat claim until its `.env` write — the
  * whole window in which it reads as unreadable — and that lock keeps its seat off this open's table
  * (`reserve_seat` cannot claim a locked seat), so tolerating it here cannot cause a collision. The
  * count of held locks is the count of opens in flight, so only the unreadable lanes beyond it are
@@ -145,7 +145,9 @@ function guard_unreadable(root: string, lanes: ReadonlyArray<LaneInfo>): void {
 
 	if (unreadable.length <= open_in_flight_count(root)) return
 
-	const named = unreadable.map((lane) => `#${lane.issue} (${lane.directory})`).join(', ')
+	const named = unreadable
+		.map((lane) => `${session_cite.issue(lane.issue)} (${lane.directory})`)
+		.join(', ')
 
 	throw new Error(
 		`Cannot read the port seed of these open lanes, so a free seat cannot be chosen: ${named}. Restore each lane's ${ENV_FILE_NAME}, or close the lane with \`pnpm josh lane:close <issue-number>\`.`,
@@ -157,7 +159,7 @@ function guard_unreadable(root: string, lanes: ReadonlyArray<LaneInfo>): void {
  *
  * Reported as a success, the caller captures the directory and types the first `pnpm josh …` in it —
  * which fails with `tsx: command not found`, the exact failure the install exists to remove, now
- * with a success line printed above it (joshuafolkken/kit#1554). The work tree is left where it is
+ * with a success line printed above it. The work tree is left where it is
  * because both ways out need it there: the install can be run again against it, or `lane:close` can
  * take it away. The child's own output is carried along, since it is the only thing that says which
  * of the two applies.
@@ -166,7 +168,7 @@ function guard_install(lane: LaneInfo, result: InstallResult): void {
 	if (result.is_installed) return
 
 	throw new Error(
-		`Opened a lane for #${lane.issue} at ${lane.directory}, but installing its dependencies failed, so no \`pnpm josh …\` will run there. Finish it with \`pnpm --dir ${lane.directory} install --frozen-lockfile\`, or take it away with \`pnpm josh lane:close ${lane.issue}\`.\n${result.output}`,
+		`Opened a lane for ${session_cite.issue(lane.issue)} at ${lane.directory}, but installing its dependencies failed, so no \`pnpm josh …\` will run there. Finish it with \`pnpm --dir ${lane.directory} install --frozen-lockfile\`, or take it away with \`pnpm josh lane:close ${lane.issue}\`.\n${result.output}`,
 	)
 }
 
@@ -196,19 +198,19 @@ function build_plan(
 //
 // The start point comes from `lane_start_point` rather than from the default branch's bare name:
 // that name resolves to a local ref nothing advances, and the lane would start without the work
-// merged just before it (joshuafolkken/kit#1535). **It answers `undefined` when a branch of this
+// merged just before it. **It answers `undefined` when a branch of this
 // lane's name already exists**, which puts the work tree on that branch instead of creating one —
-// the only route back to a child that was parked after pushing (joshuafolkken/kit#1627).
+// the only route back to a child that was parked after pushing.
 //
-// **The install is the last step rather than a caller's, because a lane without it is unusable**
-// (joshuafolkken/kit#1554). Leaving it to whoever opened the lane made it a step nothing enforced,
+// **The install is the last step rather than a caller's, because a lane without it is unusable**.
+// Leaving it to whoever opened the lane made it a step nothing enforced,
 // and every lane opened without it failed on its first `pnpm josh …`. It runs after the `.env`
 // rather than before, so a lane that fails here still carries the seat it was allocated and the
 // failure is recoverable by re-running the install alone.
 //
-// **The gate's verification caches are seeded from the main checkout before the install**
-// (joshuafolkken/kit#1849), so the lane's first `josh gate` is warm rather than cold. The pre-built
-// hook bundles are seeded the same way (joshuafolkken/kit#2160): `dist/hooks/` is git-ignored, so a
+// **The gate's verification caches are seeded from the main checkout before the install**,
+// so the lane's first `josh gate` is warm rather than cold. The pre-built
+// hook bundles are seeded the same way: `dist/hooks/` is git-ignored, so a
 // lane's work tree never carries it and every Claude Code hook drops to the slow `pnpm josh …`
 // fallback without this copy. Both are best-effort and run after the `.env` write for the same reason
 // the install does: a lane whose warming found nothing still carries its seat and is perfectly
@@ -217,7 +219,7 @@ async function materialize(plan: LanePlan, source_root: string): Promise<void> {
 	// The seat lock is released the moment the `.env` is on disk — from then the lane is readable and
 	// its seat discoverable, so nothing more holds the seat. It must **not** ride the multi-minute
 	// install: a lock outlasting the unreadable window would inflate `open_in_flight_count` and mask a
-	// genuinely broken lane (joshuafolkken/kit#2147). The `finally` covers a failure before the `.env`
+	// genuinely broken lane. The `finally` covers a failure before the `.env`
 	// is written, where nothing was created that should hold it.
 	try {
 		mkdirSync(path.dirname(plan.lane.directory), { recursive: true })
@@ -236,8 +238,7 @@ async function materialize(plan: LanePlan, source_root: string): Promise<void> {
 }
 
 // Both refusals run before the seat is claimed, so neither leaves a lock behind. A directory at the
-// lane's path that git does not register is `lane_leftover`'s to remove or refuse
-// (joshuafolkken/kit#2857).
+// lane's path that git does not register is `lane_leftover`'s to remove or refuse.
 async function clear_the_way(
 	root: string,
 	issue: string,
@@ -257,7 +258,7 @@ async function clear_the_way(
 async function open_lane(issue: string): Promise<OpenOutcome> {
 	// The main work tree's, never this one's: run from inside a lane, the current root would put the
 	// new lane under `<lane>/.<lane>-lanes` and read the lane's own seed as the root's — a lane
-	// `list_lanes` cannot see, on ports it never recorded (joshuafolkken/kit#1497).
+	// `list_lanes` cannot see, on ports it never recorded.
 	const repository_root = await lane_registry.main_repository_root()
 	const lanes = await lane_registry.list_lanes()
 	const existing = lane_registry.find_lane(lanes, issue)

package/scripts/lane/lane-output.ts

@@ -2,12 +2,13 @@ import { writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { ENV_FILE_NAME } from '#ports'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
+import { session_cite } from '#scripts/issue/session-cite'
 import { run_liveness } from '#scripts/run/run-liveness'
 import { lane_environment } from './lane-environment'
 import { lane_registry, type LaneInfo } from './lane-registry'
 
 // Where the delegated unit running a lane's child writes, recorded in the lane and read back from
-// anywhere (joshuafolkken/kit#1713).
+// anywhere.
 //
 // **This is the one fact about an in-flight lane that only the dispatching session held.** The
 // harness names a unit's output file after that session's own id and the unit's, and neither is
@@ -106,10 +107,10 @@ function describe_refusal(refusal: Refusal, issue: string): string {
 	}
 
 	if (refusal.kind === 'unreadable') {
-		return `The lane for #${issue} has a ${ENV_FILE_NAME} that cannot be read at ${refusal.lane.directory}. Fix it and run this again — writing a new one would drop the lane's port seat with it.`
+		return `The lane for ${session_cite.issue(issue)} has a ${ENV_FILE_NAME} that cannot be read at ${refusal.lane.directory}. Fix it and run this again — writing a new one would drop the lane's port seat with it.`
 	}
 
-	return `No lane is open for #${issue}. Run \`pnpm josh lane:list\` to see what is open.`
+	return `No lane is open for ${session_cite.issue(issue)}. Run \`pnpm josh lane:list\` to see what is open.`
 }
 
 const lane_output = {

package/scripts/lane/lane-paths.ts

@@ -1,6 +1,7 @@
 import path from 'node:path'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 
-// Where a lane lives on disk, and what its branch is called (joshuafolkken/kit#1490).
+// Where a lane lives on disk, and what its branch is called.
 //
 // **A lane is deliberately not nested inside the repository.** A linked work tree is a second full
 // checkout, so putting it under the main one would hand every path-walking tool in the project a
@@ -13,7 +14,7 @@ import path from 'node:path'
 const LANE_ROOT_KEY = 'JOSH_LANE_ROOT'
 const LANE_DIRECTORY_SUFFIX = '-lanes'
 // **The issue number comes first because `pnpm josh git` will not commit from a branch that starts
-// any other way** (joshuafolkken/kit#1497). Its `has_same_issue_prefix` reads `/^\d+-/`, so the
+// any other way**. Its `has_same_issue_prefix` reads `/^\d+-/`, so the
 // original `lane/<N>` spelling made every lane a checkout nothing could be committed from — and
 // switching the branch inside the lane is not the way round it, because `lane_registry` identifies a
 // lane *by* this name: the moment it changes, the work tree drops out of `lane:list`, its seat is
@@ -43,9 +44,6 @@ function lane_directory(root: string, issue: string): string {
 	return path.join(root, issue)
 }
 
-// A lane directory's own name is the issue number, so the number a checkout belongs to is readable
-// from its path alone.
-const LANE_ISSUE_PATTERN = /^\d+$/u
 // Built from the suffix above rather than spelled again, so the two readings of a lane root cannot
 // drift apart. `.kit-lanes` and `.app-kit-lanes` both match; a plain `lanes` does not, because
 // `default_lane_root` always writes the leading dot.
@@ -62,10 +60,13 @@ function is_lane_root(directory: string, environment: LaneEnvironment): boolean
 // **The inverse of `lane_directory`, and the one lane test that needs no git.** `lane_registry`
 // answers the same question authoritatively by parsing `git worktree list`, but that read is
 // asynchronous and a `PreToolUse` guard is synchronous by contract — so a guard that has to know
-// whether the checkout it is running in is a lane reads it off the path instead
-// (joshuafolkken/kit#1864). It is deliberately the weaker of the two: it says the directory *sits
+// whether the checkout it is running in is a lane reads it off the path instead.
+// It is deliberately the weaker of the two: it says the directory *sits
 // where a lane sits*, never that a work tree is registered there, so a caller that needs the
 // registration still goes through `lane_registry`.
+//
+// A lane directory's own name is the issue number, so the number a checkout belongs to is readable
+// from its path alone.
 function lane_issue_of(
 	directory: string,
 	environment: LaneEnvironment = process.env,
@@ -73,7 +74,7 @@ function lane_issue_of(
 	const resolved = path.resolve(directory)
 	const issue = path.basename(resolved)
 
-	if (!LANE_ISSUE_PATTERN.test(issue)) return undefined
+	if (!issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) return undefined
 
 	return is_lane_root(path.dirname(resolved), environment) ? issue : undefined
 }
@@ -83,14 +84,14 @@ function lane_branch(issue: string): string {
 }
 
 // The lanes root's own bookkeeping, beside the lanes and never one of them: `lane:open` claims a seat
-// by creating a lock directory under it (joshuafolkken/kit#1494).
+// by creating a lock directory under it.
 const SEAT_LOCK_DIR = '.seat-locks'
 
 // A name the lane machinery writes into a lanes root: a lane's issue number, or a lanes root of its
 // own — the nested one a lane opened from inside a lane once put there. Anything else in the root
-// was put there by someone else (joshuafolkken/kit#3370).
+// was put there by someone else.
 function is_lane_entry(name: string): boolean {
-	return LANE_ISSUE_PATTERN.test(name) || DEFAULT_LANE_ROOT_PATTERN.test(name)
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(name) || DEFAULT_LANE_ROOT_PATTERN.test(name)
 }
 
 const lane_paths = {

package/scripts/lane/lane-phase.ts

@@ -0,0 +1,33 @@
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { run_event_plan } from '#scripts/run/event/run-event-plan'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_child_marker, type MarkerSource } from './lane-child-marker'
+
+// The `implement` phase a lane child reports to `run:board`. Every other phase
+// is read off an event the run already writes — the launch, the ship stages — but nothing marked the
+// moment the plan turned into code. The first runtime-file edit is that moment, and the Step 0 notice
+// already fires on it once per session, so the pretool hook calls this beside it. The Step 0 work summary
+// is where a plan settles, so the issue's `plan` event is written here first, unless `run:entry` already
+// wrote it for a planned issue.
+//
+// **A dispatched lane child only.** A person's own session, or one carrying a mark leaked from a parent,
+// is not a lane the board draws a row for, so it writes nothing.
+async function mark_implement(
+	directory: string = process.cwd(),
+	source: MarkerSource = process.env,
+): Promise<void> {
+	const issue = lane_child_marker.marked_issue(source)
+
+	if (issue === undefined || !lane_child_marker.is_child_of(directory, source)) return
+
+	await run_event_plan.emit_plan(issue)
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.LANE_PHASE,
+		`${issue_cite.plain(issue)} implement`,
+	)
+}
+
+const lane_phase = { mark_implement }
+
+export { lane_phase }

package/scripts/lane/lane-reap.ts

@@ -2,7 +2,7 @@ import { execFileSync } from 'node:child_process'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { lane_child_invocation } from './lane-child-invocation'
 
-// Ending a lane child that did not end itself (joshuafolkken/kit#2421).
+// Ending a lane child that did not end itself.
 //
 // **A detached child is kept alive on purpose and was never ended by anything.** `detached_launch`
 // lets a child outlive its parent's session, and every reader of it — `run:liveness`, the 30-minute
@@ -89,7 +89,7 @@ function ancestry_of(pid: number, probes: ReapProbes): Set<number> {
 }
 
 // This process and every process above it. The Stop hook reads it to tell whether the session that
-// declared a carry record's `--owner "$PPID"` is the one it runs under (joshuafolkken/kit#2472).
+// declared a carry record's `--owner "$PPID"` is the one it runs under.
 function own_ancestry(probes: ReapProbes = SYSTEM_PROBES): Set<number> {
 	return ancestry_of(process.pid, probes)
 }

package/scripts/lane/lane-registry.ts

@@ -5,11 +5,12 @@ import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { git_command } from '#scripts/git/git-command'
 import { git_worktree } from '#scripts/git/git-worktree'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { file_reader } from '#scripts/lib/read-file'
 import { lane_environment } from './lane-environment'
 import { lane_paths } from './lane-paths'
 
-// The open lanes, read from git and from each lane's own `.env` (joshuafolkken/kit#1490).
+// The open lanes, read from git and from each lane's own `.env`.
 //
 // **There is no ledger file, and that is the design rather than an omission.** A lane's seat has to
 // live in its `.env` anyway — that file is what `josh port` and `playwright.config.ts` read inside
@@ -25,11 +26,11 @@ interface LaneInfo {
 	directory: string
 	// The lane's seat (`JOSH_LANE_SEAT`, 1..9), and the dev/preview ports it resolves to through
 	// `ports/index.js` — all `undefined` when the lane's `.env` cannot be read. The seat is what a new
-	// lane's allocation has to avoid; the ports are what the report shows (joshuafolkken/kit#1494).
+	// lane's allocation has to avoid; the ports are what the report shows.
 	seat: number | undefined
 	development_port: number | undefined
 	preview_port: number | undefined
-	// Where the delegated unit running this lane's child writes (joshuafolkken/kit#1713), or
+	// Where the delegated unit running this lane's child writes, or
 	// `undefined` where the lane records none. It is the one thing about a lane that a session which
 	// did not open it cannot derive: the harness names a unit's file after the dispatching session
 	// and the unit's own id, neither of which is written anywhere else on disk. Recorded here, a
@@ -43,10 +44,6 @@ interface LaneInfo {
 const WORKTREE_PREFIX = 'worktree '
 const BRANCH_PREFIX = 'branch refs/heads/'
 const BLOCK_SEPARATOR = '\n\n'
-// The same shape `lane:open` accepts. Nothing reserves the `-lane` suffix, so a hand-made
-// `spike-lane` branch with a work tree would otherwise be read as a lane — and `lane:close --all`
-// would delete its directory and its branch on an issue number that never existed.
-const ISSUE_PATTERN = /^[1-9]\d*$/u
 
 function line_value(lines: ReadonlyArray<string>, prefix: string): string | undefined {
 	return lines.find((line) => line.startsWith(prefix))?.slice(prefix.length)
@@ -101,7 +98,7 @@ function held_seat(content: string | undefined): SeatPorts {
 /**
  * The lane's own `.env`, or `undefined` when it cannot be read.
  *
- * One read serves both the seat and the recorded output path (joshuafolkken/kit#1713). Reading the
+ * One read serves both the seat and the recorded output path. Reading the
  * file twice would let the two disagree about whether it could be read at all, and `unreadable` is
  * a state the report shows rather than a state anything falls back from.
  */
@@ -112,12 +109,16 @@ function read_environment(directory: string): string | undefined {
 // A lane is identified by its branch rather than by where it sits, so nothing here compares two
 // spellings of one path — git prints the resolved one, and a lane root reached through a symlink
 // would otherwise read as no lane at all.
+//
+// The issue is the same shape `lane:open` accepts. Nothing reserves the `-lane` suffix, so a hand-made
+// `spike-lane` branch with a work tree would otherwise be read as a lane — and `lane:close --all`
+// would delete its directory and its branch on an issue number that never existed.
 function branch_issue(branch: string | undefined): string | undefined {
 	if (!branch?.endsWith(lane_paths.LANE_BRANCH_SUFFIX)) return undefined
 
 	const issue = branch.slice(0, -lane_paths.LANE_BRANCH_SUFFIX.length)
 
-	return ISSUE_PATTERN.test(issue) ? issue : undefined
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue) ? issue : undefined
 }
 
 // **Stranded means the work tree is gone from disk, and nothing else.** git also marks a
@@ -154,8 +155,8 @@ function build_lane(
 	}
 }
 
-// **A lane is its branch *and* its place, and the place is what makes the identification safe**
-// (joshuafolkken/kit#1497). The branch alone is not a namespace anyone stays out of: `pnpm josh git`
+// **A lane is its branch *and* its place, and the place is what makes the identification safe**.
+// The branch alone is not a namespace anyone stays out of: `pnpm josh git`
 // builds an issue branch as `<N>-<slug of the title>`, so an issue titled "Lane" produces `<N>-lane`
 // — byte for byte the name `lane_paths.lane_branch` builds. Read as a lane, that work tree is
 // whichever checkout the person was working in, and `lane:close --all` would delete it, because
@@ -194,11 +195,11 @@ async function worktree_blocks(): Promise<Array<string>> {
 /**
  * The main work tree's root, whichever work tree this was run in.
  *
- * **Every lane path is derived from here, and `git rev-parse --show-toplevel` is not it**
- * (joshuafolkken/kit#1497). That answers the *current* work tree, which inside a lane is the lane
+ * **Every lane path is derived from here, and `git rev-parse --show-toplevel` is not it**.
+ * That answers the *current* work tree, which inside a lane is the lane
  * itself — so `lane:list` run there would look for lanes under `<lane>/.<lane>-lanes` and report that
  * none are open while six are running. The step from the current work tree to the main one is exactly
- * what `repo_discovery.main_worktree` resolves from the filesystem (joshuafolkken/kit#2233), so this
+ * what `repo_discovery.main_worktree` resolves from the filesystem, so this
  * is a thin async layer over it: `repository_root()` names the current work tree, and the shared
  * resolver walks its `.git`/`commondir` up to the main checkout. Keeping that walk in one place lets
  * the synchronous discovery callers — which cannot await this — share the same answer. For an ordinary
@@ -252,7 +253,7 @@ function find_lane(lanes: ReadonlyArray<LaneInfo>, issue: string): LaneInfo | un
 /**
  * The open lane for one issue, read from the listing every other lane reading goes through.
  *
- * **The listing and the find are one call because every caller needs both** (joshuafolkken/kit#1749).
+ * **The listing and the find are one call because every caller needs both**.
  * Each one that wrote the pair itself is a place the listing could be read differently — from a cache,
  * from a stale array — and the whole point of reading it live is that the answer is the same in every
  * session, including one that never opened the lane.

package/scripts/lane/lane-relaunch.ts

@@ -8,8 +8,8 @@ import type { LaneInfo } from './lane-registry'
 
 // Relaunching a lane child session into its own lane — a fresh agent process started detached, under
 // the lane's stored profile at the effort of the phase it resumes into, logging to the lane's dispatch
-// log and carrying the dispatch mark afresh. **It was `run:cut`'s alone until a second caller needed it**
-// (joshuafolkken/kit#2428): the detached `josh ship` supervisor hands a stopped stage back to an agent
+// log and carrying the dispatch mark afresh. **It was `run:cut`'s alone until a second caller needed it**:
+// the detached `josh ship` supervisor hands a stopped stage back to an agent
 // the same way the pre-gate cut hands the gate to one, so the launch is shared rather than copied — the
 // copy that drifts is the one that forgets the mark and is read as a person by every guard.
 //
@@ -38,9 +38,9 @@ function relaunch(
 			log_path: lane_dispatch_log.default_log_path(lane),
 			profile: built.profile,
 			// The relaunch keeps the mark, so the resumed child is still a dispatched child to every rule
-			// that reads it (joshuafolkken/kit#1904); the inherited environment cannot be relied on here,
-			// since the parent-session strip runs on the way in. **The ship supervisor's mark is dropped**
-			// (joshuafolkken/kit#2428): a detached supervisor is what relaunches after a stopped stage, and an
+			// that reads it; the inherited environment cannot be relied on here,
+			// since the parent-session strip runs on the way in. **The ship supervisor's mark is dropped**:
+			// a detached supervisor is what relaunches after a stopped stage, and an
 			// agent that inherited its mark would read its own in-turn `josh ship` failure as a supervisor's —
 			// relaunching a second child into the lane beside itself.
 			env: { ...lane_child_marker.env_for(lane.issue), [SUPERVISED_KEY]: undefined },
@@ -50,14 +50,14 @@ function relaunch(
 }
 
 // An OpenAI lane's process is started by its supervisor, never by a relaunch — both `run:cut` and the
-// `run:merge` cut fallback ask this one predicate (joshuafolkken/kit#2484).
+// `run:merge` cut fallback ask this one predicate.
 function is_openai_lane(lane: LaneInfo): boolean {
 	return lane.profile?.provider === OPENAI_PROVIDER
 }
 
-// The relaunch after a cut: the resume-specific prompt, not the record's bare `fullrun #<N>`
-// (joshuafolkken/kit#2022), so the successor goes straight to `run:cut --resume` without reading the
-// workflow-commands entry documents. Shared by `run:cut` and the `run:merge` fallback (joshuafolkken/kit#2484).
+// The relaunch after a cut: the resume-specific prompt, not the record's bare `fullrun #<N>`,
+// so the successor goes straight to `run:cut --resume` without reading the
+// workflow-commands entry documents. Shared by `run:cut` and the `run:merge` fallback.
 function resume(lane: LaneInfo, phase: string, on_note: (note: string) => void): RelaunchResult {
 	return relaunch(lane, lane_child_invocation.resume_invocation(lane.issue), phase, on_note)
 }

package/scripts/lane/lane-report.ts

@@ -1,9 +1,10 @@
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
+import { session_cite } from '#scripts/issue/session-cite'
 import { run_liveness } from '#scripts/run/run-liveness'
 import type { LaneInfo } from './lane-registry'
 
-// What a person reads when they ask what is open (joshuafolkken/kit#1490, joshuafolkken/kit#1494).
+// What a person reads when they ask what is open.
 //
 // The dev and preview ports are the ones the registry already resolved through `ports/index.js`
 // when it read each lane's `.env`, so the numbers printed here are the same ones `josh port` and
@@ -31,7 +32,7 @@ function value_or_unknown(value: number | undefined): string {
 }
 
 // The recorded output path goes last and is labelled, so it is told apart from the directory beside
-// it (joshuafolkken/kit#1713). A lane that records none prints `output -` rather than nothing at
+// it. A lane that records none prints `output -` rather than nothing at
 // all: a session that did not open the lane has to be able to see that the record is missing, not
 // read a shorter row as one field it failed to notice.
 function output_column(output: string | undefined): string {
@@ -52,7 +53,7 @@ function event_column(lane: LaneInfo): string {
 // The plain `#N`, for a caller that could not read the repository the issue would link into.
 const PLAIN_CITE: IssueCiter = issue_cite.citer(undefined, new Map())
 
-// The issue leads as a citation (joshuafolkken/kit#2943): a lane status report copies this row, and a
+// The issue leads as a citation: a lane status report copies this row, and a
 // bare `#N` copied into it is what the Stop guard sends back.
 function describe_lane(lane: LaneInfo, cite: IssueCiter = PLAIN_CITE): string {
 	return [
@@ -84,7 +85,7 @@ function describe_ports(lane: LaneInfo): string {
 // The one-line confirmation a person reads on standard error while standard output carries the
 // directory alone, so `dir=$(pnpm josh lane:open 1490)` stays usable.
 function describe_opened(lane: LaneInfo): string {
-	return `Opened a lane for #${lane.issue} on ${lane.branch}: ${describe_ports(lane)}.`
+	return `Opened a lane for ${session_cite.issue(lane.issue)} on ${lane.branch}: ${describe_ports(lane)}.`
 }
 
 const lane_report = {

package/scripts/lane/lane-resume.ts

@@ -3,8 +3,8 @@ import { api_outage } from '#scripts/agent/api-outage'
 import type { ClaudeResultEvent } from '#scripts/agent/claude-result-event'
 import { lane_child_invocation } from './lane-child-invocation'
 
-// How a lane re-dispatch chooses between resuming the disconnected child's session and starting fresh
-// (joshuafolkken/kit#2317). The premise the whole issue rests on: a child that could not reach the API
+// How a lane re-dispatch chooses between resuming the disconnected child's session and starting fresh.
+// The premise the whole issue rests on: a child that could not reach the API
 // left a `session_id` in its exit record, and re-dispatching it as a bare `fullrun #<N>` threw that
 // context away — a resumed child keeps it and loses only the last round-trip.
 //