@joshuafolkken/kit 1.872.0

package/scripts/lane/lane-occupancy.ts

@@ -0,0 +1,112 @@
+// The difference between the issues an `in-progress` label says are running and the lanes that are
+// actually open (joshuafolkken/kit#2235).
+//
+// `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 —
+// `ls` and a remote branch's existence — and reported two running issues as stranded. The two sets
+// disagree in two directions, and the harm is asymmetric: a label with no lane silently shrinks the
+// free-lane count, while a lane with no label lets another session claim the same issue and open a
+// second pull request on the same branch.
+//
+// **The judgement is read from the two sets, never invented.** The classification is three-valued so
+// an unreadable lane listing stays `unknown` rather than collapsing to `stopped` — reported as a dead
+// lane, a live one would have its stale label cleared and its issue handed out again.
+//
+// **Nothing here writes a label.** Removing `in-progress` from a live run is exactly the mistake that
+// opens a second pull request, so the repair is a person's — this module only names the difference.
+
+// How a lane listing arrived: the open lanes' issue numbers, or that the listing could not be read.
+type LaneRead = { kind: 'lanes'; issues: ReadonlyArray<number> } | { kind: 'unreadable' }
+
+// The three liveness verdicts, named so the `lane:list` oracle vocabulary reads them from here rather
+// than repeating the literals. `LIVE` is the silent norm; `STOPPED` and `UNKNOWN` lead the anomaly
+// lines below so the token a reader greps for is the one this module classifies with.
+const LIVE = 'live'
+const STOPPED = 'stopped'
+const UNKNOWN = 'unknown'
+
+// Whether an `in-progress` issue's lane is open, stopped, or could not be determined. `unknown` is
+// the answer when the lane listing itself could not be read — never `stopped`, which would report a
+// running lane as dead.
+type Liveness = typeof LIVE | typeof STOPPED | typeof UNKNOWN
+
+interface LabelledIssue {
+	issue: number
+	liveness: Liveness
+}
+
+interface OccupancyReport {
+	// Every `in-progress` issue with its lane liveness. A `live` one is the ordinary case; a `stopped`
+	// or `unknown` one is the anomaly `describe` names.
+	labelled: ReadonlyArray<LabelledIssue>
+	// Open lanes whose issue carries no `in-progress` label — the reverse difference. Empty when the
+	// lane listing could not be read, since there is nothing to compare against.
+	lanes_without_label: ReadonlyArray<number>
+}
+
+function to_liveness(issue: number, lanes: LaneRead): Liveness {
+	if (lanes.kind === 'unreadable') return UNKNOWN
+
+	return lanes.issues.includes(issue) ? LIVE : STOPPED
+}
+
+function to_lanes_without_label(
+	in_progress: ReadonlyArray<number>,
+	lanes: LaneRead,
+): Array<number> {
+	if (lanes.kind === 'unreadable') return []
+
+	return lanes.issues.filter((issue) => !in_progress.includes(issue))
+}
+
+// The two-directional difference between the `in-progress` issues and the open lanes. Pure: it reads
+// the two sets and writes nothing, which is what keeps the label untouched.
+function classify(in_progress: ReadonlyArray<number>, lanes: LaneRead): OccupancyReport {
+	return {
+		labelled: in_progress.map((issue) => ({ issue, liveness: to_liveness(issue, lanes) })),
+		lanes_without_label: to_lanes_without_label(in_progress, lanes),
+	}
+}
+
+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.`
+}
+
+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.`
+}
+
+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).`
+}
+
+function labelled_lines(labelled: ReadonlyArray<LabelledIssue>): Array<string> {
+	return labelled.flatMap((entry) => {
+		if (entry.liveness === 'stopped') return [stopped_line(entry.issue)]
+		if (entry.liveness === 'unknown') return [unknown_line(entry.issue)]
+
+		return []
+	})
+}
+
+// The anomalies as lines for standard error, or `undefined` when the two sets agree — the same shape
+// `lane:list` follows for every explanation, so its standard output stays a token per line.
+function describe(report: OccupancyReport): string | undefined {
+	const lines = [
+		...labelled_lines(report.labelled),
+		...report.lanes_without_label.map((issue) => without_label_line(issue)),
+	]
+
+	return lines.length === 0 ? undefined : lines.join('\n')
+}
+
+const lane_occupancy = {
+	LIVE,
+	STOPPED,
+	UNKNOWN,
+	classify,
+	describe,
+}
+
+export { lane_occupancy }
+export type { LabelledIssue, LaneRead, Liveness, OccupancyReport }

package/scripts/lane/lane-open.ts

@@ -0,0 +1,275 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, 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 { lane_cache } from './lane-cache'
+import { lane_environment } from './lane-environment'
+import { lane_install, type InstallResult } from './lane-install'
+import { lane_paths } from './lane-paths'
+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).
+//
+// **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
+// `repo-discovery.ts` follows a `.git` file pointer — so a lane opened here is guarded, discovered
+// and checked by the layers that are already there. Nothing below re-implements any of that.
+
+interface LanePlan {
+	lane: LaneInfo
+	environment_content: string
+	// The seat lock held across this lane's creation, released once its `.env` is on disk.
+	seat_lock: string
+}
+
+interface SeatReservation {
+	seat: number
+	lock: string
+}
+
+type OpenOutcome =
+	{ kind: 'already-open'; lane: LaneInfo } | { kind: 'full' } | { kind: 'opened'; lane: LaneInfo }
+
+const FULL_OUTCOME: OpenOutcome = { kind: 'full' }
+
+// The seat a lane will take is claimed by exclusively creating its lock directory here, under 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
+// 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_DIR = '.seat-locks'
+const SEAT_LOCK_PREFIX = 'seat-'
+
+// A root with no `.env` is the normal state of a fresh clone and of CI, and it means seed 0 — the
+// same reading `ports/index.js` gives a missing file. The lane still gets a file, because the seed
+// it is being given is the whole point.
+function read_root_environment(repository_root: string): string {
+	const file = path.join(repository_root, ENV_FILE_NAME)
+
+	return existsSync(file) ? readFileSync(file, 'utf8') : ''
+}
+
+function build_lane(
+	root: string,
+	issue: string,
+	seat: number,
+	environment_content: string,
+): LaneInfo {
+	// The ports are resolved from the exact `.env` the lane will carry, through the one formula in
+	// `ports/index.js`, so the opened-lane confirmation prints the numbers the lane will actually run.
+	const port_pair = lane_environment.read_lane_ports(environment_content)
+
+	return {
+		issue,
+		branch: lane_paths.lane_branch(issue),
+		directory: lane_paths.lane_directory(root, issue),
+		seat,
+		development_port: port_pair.development,
+		preview_port: port_pair.preview,
+		output: undefined,
+		is_stranded: false,
+	}
+}
+
+function seat_lock_path(root: string, seat: number): string {
+	return path.join(root, SEAT_LOCK_DIR, `${SEAT_LOCK_PREFIX}${String(seat)}`)
+}
+
+// Release the seat lock — idempotent (`force`), so calling it after the `.env` write and again in the
+// `finally` that covers an earlier failure both land safely.
+function release_seat_lock(lock: string): void {
+	rmSync(lock, { recursive: true, force: true })
+}
+
+// How many opens are in flight right now, read straight off disk: each holds one seat lock from its
+// seat claim until its `.env` is written, so the count of lock entries is the count of lanes still
+// being created. A missing directory is none held — the normal state when no open is running.
+function open_in_flight_count(root: string): number {
+	try {
+		return readdirSync(path.join(root, SEAT_LOCK_DIR)).filter((entry) =>
+			entry.startsWith(SEAT_LOCK_PREFIX),
+		).length
+	} catch {
+		return 0
+	}
+}
+
+// Claim `lock` by creating it exclusively — `false` when another open already holds it. The parent
+// is ensured first (idempotent); the lock itself is a non-recursive `mkdirSync`, so an existing one
+// throws rather than passing silently, which is what makes the claim atomic.
+function claim_seat(lock: string): boolean {
+	mkdirSync(path.dirname(lock), { recursive: true })
+
+	try {
+		mkdirSync(lock)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+function reserve_seat(root: string, free: ReadonlyArray<number>): SeatReservation | undefined {
+	for (const seat of free) {
+		const lock = seat_lock_path(root, seat)
+		if (claim_seat(lock)) return { seat, lock }
+	}
+
+	return undefined
+}
+
+/**
+ * Refuse to allocate while a live lane's seat cannot be read — but a lane still being opened is not
+ * one of those.
+ *
+ * Skipping a broken lane would read its seat as free and hand its ports to the new one, which is a
+ * 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
+ * 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
+ * genuinely broken and stop the allocation. A lock stranded by a hard crash masks a broken lane the
+ * same way; removing the `.seat-locks` directory clears it.
+ */
+function guard_unreadable(root: string, lanes: ReadonlyArray<LaneInfo>): void {
+	const unreadable = lane_registry.unreadable_lanes(lanes)
+
+	if (unreadable.length <= open_in_flight_count(root)) return
+
+	const named = unreadable.map((lane) => `#${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>\`.`,
+	)
+}
+
+/**
+ * Fail the open when the install failed, rather than handing back a lane nothing runs in.
+ *
+ * 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
+ * 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.
+ */
+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}`,
+	)
+}
+
+function build_plan(
+	repository_root: string,
+	root: string,
+	issue: string,
+	lanes: ReadonlyArray<LaneInfo>,
+): LanePlan | undefined {
+	const root_content = read_root_environment(repository_root)
+	const free = lane_seed_policy.free_seats(lane_registry.used_seats(lanes))
+	const reservation = reserve_seat(root, free)
+
+	if (reservation === undefined) return undefined
+
+	const environment_content = lane_environment.lane_file_content(root_content, reservation.seat)
+
+	return {
+		lane: build_lane(root, issue, reservation.seat, environment_content),
+		environment_content,
+		seat_lock: reservation.lock,
+	}
+}
+
+// The `.env` is written straight after the work tree exists, because the seed is the reason the
+// lane is being opened. Nothing else is recorded anywhere: that file *is* the record.
+//
+// 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
+// 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 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,
+// 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
+// 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
+// usable, cold first gate and fallback hooks and all.
+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`
+	// is written, where nothing was created that should hold it.
+	try {
+		mkdirSync(path.dirname(plan.lane.directory), { recursive: true })
+
+		const start_point = await lane_start_point.resolve_for_branch(plan.lane.branch)
+
+		await git_worktree.worktree_add(plan.lane.directory, plan.lane.branch, start_point)
+		writeFileSync(path.join(plan.lane.directory, ENV_FILE_NAME), plan.environment_content)
+		release_seat_lock(plan.seat_lock)
+		lane_cache.seed_caches(source_root, plan.lane.directory)
+		lane_cache.seed_hook_bundles(source_root, plan.lane.directory)
+		guard_install(plan.lane, await lane_install.install_dependencies(plan.lane.directory))
+	} finally {
+		release_seat_lock(plan.seat_lock)
+	}
+}
+
+/**
+ * Open the lane for `issue`, or say why it was not opened.
+ *
+ * A lane that is already open is never reopened — including a stranded one, whose registration git
+ * still holds and would refuse `worktree add` on. `lane:close` and `lane:prune` are the way out of
+ * both, and the refusal says so.
+ */
+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).
+	const repository_root = await lane_registry.main_repository_root()
+	const lanes = await lane_registry.list_lanes()
+	const existing = lane_registry.find_lane(lanes, issue)
+
+	if (existing !== undefined) return { kind: 'already-open', lane: existing }
+
+	const root = lane_paths.lane_root(repository_root)
+
+	guard_unreadable(root, lanes)
+
+	const plan = build_plan(repository_root, root, issue, lanes)
+
+	if (plan === undefined) return FULL_OUTCOME
+
+	await materialize(plan, repository_root)
+
+	return { kind: 'opened', lane: plan.lane }
+}
+
+const lane_open = {
+	build_plan,
+	guard_unreadable,
+	open_lane,
+	read_root_environment,
+}
+
+export type { OpenOutcome }
+export { lane_open }

package/scripts/lane/lane-output.ts

@@ -0,0 +1,124 @@
+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 { 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).
+//
+// **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
+// written anywhere on disk — so a session that did not open the lane could not poll its child, and
+// a hand-off had to drain the pool first: no new lane opened until every in-flight one had finished.
+// Recorded here,
+// `unit_output=$(pnpm josh lane:output <N>) && pnpm josh run:liveness <N> --output "$unit_output"`
+// works from a session that has never seen the child, and the drain goes away. **The `&&` is not
+// decoration**: a lane recording nothing prints `none` and exits non-zero, and a substitution written
+// inside the argument would discard that exit status and hand `run:liveness` a relative path.
+//
+// **Nothing here writes a `.env` that was not already there.** A lane whose file cannot be read is
+// refused rather than replaced: the same file carries the lane's port seat, and a fresh one holding
+// only this record would put the lane back on the main work tree's ports.
+
+type Refusal =
+	{ kind: 'no-lane' } | { kind: 'invalid'; reason: string } | { kind: 'unreadable'; lane: LaneInfo }
+
+type RecordOutcome = Refusal | { kind: 'recorded'; lane: LaneInfo; output: string }
+
+type ReadOutcome =
+	| { kind: 'no-lane' }
+	| { kind: 'none'; lane: LaneInfo }
+	| { kind: 'read'; lane: LaneInfo; output: string }
+
+const NO_OUTPUT = 'This lane records no output path yet.'
+// A quote would end the quoted assignment the record is written as, and a newline would split it
+// into two lines — either way the file would say something other than what was handed in.
+const FORBIDDEN_CHARACTERS = /["\n\r]/u
+
+/**
+ * Why this path cannot be recorded, or `undefined` when it can.
+ *
+ * **A path `run:liveness` could not read is refused here rather than there.** That command answers
+ * `undetermined` for one — an answer meaning "could not read" — so a lane recorded with it would
+ * poll as indeterminate for ever instead of the record being reported wrong. **The test is
+ * `run_liveness.to_safe_path` itself, never a second copy of its rules**: absolute, normalized, and
+ * confined to the home and temp directories, in both spellings of each. Restating half of that here
+ * is exactly how the two would come to disagree.
+ */
+function invalid_reason(output: string): string | undefined {
+	if (FORBIDDEN_CHARACTERS.test(output)) return 'the path cannot hold a quote or a line break'
+
+	return run_liveness.to_safe_path(output) === undefined
+		? 'the path has to be one `run:liveness` can read: absolute, and under the home or temp directory'
+		: undefined
+}
+
+/** Record where this lane's unit writes, leaving everything else in its `.env` untouched. */
+async function record_output(
+	issue: string,
+	output: string,
+	profile?: AgentProfile,
+): Promise<RecordOutcome> {
+	const reason = invalid_reason(output)
+
+	if (reason !== undefined) return { kind: 'invalid', reason }
+
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined) return { kind: 'no-lane' }
+
+	const content = lane_registry.read_environment(lane.directory)
+
+	if (content === undefined) return { kind: 'unreadable', lane }
+
+	writeFileSync(
+		path.join(lane.directory, ENV_FILE_NAME),
+		lane_environment.with_lane_output(content, output, profile),
+	)
+
+	return { kind: 'recorded', lane, output }
+}
+
+/**
+ * The path this lane records, read through the registry every other lane reading goes through.
+ *
+ * The session asking is never assumed to be the one that opened the lane — that is the whole point:
+ * the answer comes from the lane's own `.env`, so it is the same answer in every session.
+ */
+async function read_output(issue: string): Promise<ReadOutcome> {
+	const lane = await lane_registry.find_open_lane(issue)
+
+	if (lane === undefined) return { kind: 'no-lane' }
+
+	const { output } = lane
+
+	if (output === undefined) return { kind: 'none', lane }
+
+	return { kind: 'read', lane, output }
+}
+
+function describe_refusal(refusal: Refusal, issue: string): string {
+	if (refusal.kind === 'invalid') {
+		return `That output path cannot be recorded: ${refusal.reason}. \`pnpm josh run:liveness\` reads only an absolute path, so a record it cannot use would be worse than none.`
+	}
+
+	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 `No lane is open for #${issue}. Run \`pnpm josh lane:list\` to see what is open.`
+}
+
+const lane_output = {
+	NO_OUTPUT,
+	describe_refusal,
+	invalid_reason,
+	read_output,
+	record_output,
+}
+
+export type { ReadOutcome, RecordOutcome, Refusal }
+export { lane_output }

package/scripts/lane/lane-paths.ts

@@ -0,0 +1,96 @@
+import path from 'node:path'
+
+// Where a lane lives on disk, and what its branch is called (joshuafolkken/kit#1490).
+//
+// **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
+// duplicate of itself: the lint run, the unit suite, the spell check and `git status` would each
+// have to be taught to skip it, and one missed ignore rule turns a six-lane machine into six
+// copies of the tree being checked. A hidden sibling directory of the repository root is outside
+// every one of those walks by construction, and needs no ignore entry in kit or in any consumer
+// `josh sync` reaches.
+
+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
+// 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
+// re-issued to the next lane, and two live lanes share the dev and preview ports lanes exist to keep
+// apart. The name is therefore fixed at both ends at once rather than adapted at one of them.
+const LANE_BRANCH_SUFFIX = '-lane'
+
+type LaneEnvironment = Record<string, string | undefined>
+
+// `.kit-lanes` beside `kit`, `.app-kit-lanes` beside `app-kit`. Named after the repository rather
+// than shared between them, so two projects' lanes never contend for one directory.
+function default_lane_root(repository_root: string): string {
+	const name = path.basename(repository_root)
+
+	return path.join(path.dirname(repository_root), `.${name}${LANE_DIRECTORY_SUFFIX}`)
+}
+
+// A blank override is the shape of "I have not set this", exactly as `PORT_SEED`'s is: `.env.example`
+// ships keys with no value, so reading blank as a path would put every lane at the filesystem root.
+function lane_root(repository_root: string, environment: LaneEnvironment = process.env): string {
+	const configured = environment[LANE_ROOT_KEY]?.trim() ?? ''
+
+	return configured.length === 0 ? default_lane_root(repository_root) : path.resolve(configured)
+}
+
+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.
+const DEFAULT_LANE_ROOT_PATTERN = new RegExp(String.raw`^\..+${LANE_DIRECTORY_SUFFIX}$`, 'u')
+
+function is_lane_root(directory: string, environment: LaneEnvironment): boolean {
+	const configured = environment[LANE_ROOT_KEY]?.trim() ?? ''
+
+	if (configured.length > 0) return path.resolve(configured) === directory
+
+	return DEFAULT_LANE_ROOT_PATTERN.test(path.basename(directory))
+}
+
+// **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
+// where a lane sits*, never that a work tree is registered there, so a caller that needs the
+// registration still goes through `lane_registry`.
+function lane_issue_of(
+	directory: string,
+	environment: LaneEnvironment = process.env,
+): string | undefined {
+	const resolved = path.resolve(directory)
+	const issue = path.basename(resolved)
+
+	if (!LANE_ISSUE_PATTERN.test(issue)) return undefined
+
+	return is_lane_root(path.dirname(resolved), environment) ? issue : undefined
+}
+
+function lane_branch(issue: string): string {
+	return `${issue}${LANE_BRANCH_SUFFIX}`
+}
+
+const lane_paths = {
+	LANE_BRANCH_SUFFIX,
+	LANE_ROOT_KEY,
+	default_lane_root,
+	lane_branch,
+	lane_directory,
+	lane_issue_of,
+	lane_root,
+}
+
+export type { LaneEnvironment }
+export { lane_paths }