@joshuafolkken/kit 1.872.0

package/scripts/lane/lane-environment.ts

@@ -0,0 +1,253 @@
+import { LANE_SEAT_KEY, PORT_SEED_KEY, ports } from '#ports'
+import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
+
+// The lane's `.env`, built from the root's (joshuafolkken/kit#1490, joshuafolkken/kit#1494).
+//
+// **Port separation is required here, not optional.** `ports/index.js` resolves the project root as
+// the nearest ancestor holding a `package.json` — which, inside a linked work tree, is the lane's
+// own directory — so a lane with no `.env` runs on seed 0 and a lane handed a verbatim copy of the
+// root's runs on the root's exact offset; either way every lane lands on one pair of ports, and a
+// busy port fails without retrying on another. At the default six lanes that turns E2E from "fails
+// sometimes" into "fails nearly always". So the lane's `.env` keeps the project's `PORT_SEED`
+// unchanged and adds `JOSH_LANE_SEAT`, and `ports/index.js` combines them as `seed × 10 + seat`
+// (joshuafolkken/kit#1494): the file plainly shows which number is the project's and which is the
+// seat, and the multiplication that separates the bands lives in one place rather than here.
+//
+// **Everything else in the file is carried across verbatim**, comments and blank lines included:
+// `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `JOSH_SESSION_LANG` and whatever else the person has set
+// are as necessary inside a lane as outside one, and a lane that had to have them re-entered would
+// not be a place a run could start unattended.
+
+// Where the delegated unit running this lane's child writes (joshuafolkken/kit#1713). It goes in the
+// lane's own `.env` — the store `lane-registry.ts` already reads — rather than in a ledger beside the
+// trees, so `git worktree remove` erases the record along with the lane it described and there is
+// nothing left to go stale. `.env` is gitignored in kit and in every consumer `josh sync` reaches,
+// which is the objection that sent the run hold's stamp to the temp directory instead.
+const LANE_OUTPUT_KEY = 'JOSH_LANE_OUTPUT'
+const LANE_PROVIDER_KEY = 'JOSH_LANE_AGENT_PROVIDER'
+const LANE_ROLE_KEY = 'JOSH_LANE_AGENT_ROLE'
+const LANE_MODEL_KEY = 'JOSH_LANE_AGENT_MODEL'
+const LANE_EFFORT_KEY = 'JOSH_LANE_AGENT_EFFORT'
+const ASSIGNMENT_SEPARATOR = '='
+// `export PORT_SEED=3` is a form dotenv readers accept, so an assignment written that way has to be
+// read as the seed line rather than copied through beside the one appended below.
+const EXPORT_PREFIX = 'export '
+// `PORT_SEED="3"` and `PORT_SEED='3'` are both accepted by `process.loadEnvFile`, and the quotes are
+// not part of the value — passing them to the seed validator would fail a file that works.
+const QUOTE_CHARACTERS = new Set(['"', "'"])
+const MIN_QUOTED_LENGTH = 2
+const FIRST_CHARACTER_END = 1
+const LAST_CHARACTER_START = -1
+
+// Read character by character rather than by regular expression: the pattern this replaced —
+// optional leading blanks, an optional `export`, more blanks — backtracks super-linearly on a long
+// line of spaces, which `.env` files pick up from careless editors.
+function strip_export(line: string): string {
+	const trimmed = line.trimStart()
+
+	return trimmed.startsWith(EXPORT_PREFIX)
+		? trimmed.slice(EXPORT_PREFIX.length).trimStart()
+		: trimmed
+}
+
+function is_key_line(line: string, key: string): boolean {
+	const body = strip_export(line)
+
+	if (!body.startsWith(key)) return false
+
+	return body.slice(key.length).trimStart().startsWith(ASSIGNMENT_SEPARATOR)
+}
+
+function is_seed_line(line: string): boolean {
+	return is_key_line(line, PORT_SEED_KEY)
+}
+
+function is_seat_line(line: string): boolean {
+	return is_key_line(line, LANE_SEAT_KEY)
+}
+
+function is_output_line(line: string): boolean {
+	return is_key_line(line, LANE_OUTPUT_KEY)
+}
+
+// `trimEnd` rather than a trailing-newline pattern: the file is rejoined with one newline at the end
+// whatever it arrived with, so what is dropped here is only ever whitespace nothing reads.
+function split_lines(content: string): Array<string> {
+	const trimmed = content.trimEnd()
+
+	return trimmed.length === 0 ? [] : trimmed.split('\n')
+}
+
+function is_quoted(raw: string): boolean {
+	const first = raw.slice(0, FIRST_CHARACTER_END)
+
+	if (!QUOTE_CHARACTERS.has(first)) return false
+
+	return raw.length >= MIN_QUOTED_LENGTH && raw.endsWith(first)
+}
+
+function unquote(raw: string): string {
+	return is_quoted(raw) ? raw.slice(FIRST_CHARACTER_END, LAST_CHARACTER_START) : raw
+}
+
+function assignment_value(line: string): string {
+	return unquote(line.slice(line.indexOf(ASSIGNMENT_SEPARATOR) + FIRST_CHARACTER_END).trim())
+}
+
+/**
+ * The last value assigned to `key` in the file, or `undefined` when it is never assigned.
+ *
+ * **The last assignment wins, which is what `.env` itself means.** A file that kept the blank
+ * `PORT_SEED=` from `.env.example` and appended a real one later would otherwise read as unset here
+ * while reading as the real seed everywhere else.
+ */
+function read_assignment(content: string, key: string): string | undefined {
+	const line = split_lines(content).findLast((entry) => is_key_line(entry, key))
+
+	return line === undefined ? undefined : assignment_value(line)
+}
+
+/**
+ * The project's port seed a `.env` sets, validated by `ports.resolve_seed`.
+ *
+ * A missing or blank seed is 0, the documented default; a malformed one throws for the same reason
+ * and with the same message it does everywhere else. `josh doctor` reads it to report each
+ * repository's seed, and it is the base every lane's seat sits on top of.
+ */
+function read_root_seed(content: string): number {
+	return ports.resolve_seed({ [PORT_SEED_KEY]: read_assignment(content, PORT_SEED_KEY) })
+}
+
+/**
+ * The lane's seat, or `undefined` when the file assigns none.
+ *
+ * The validation is `ports.resolve_lane`'s rather than a second copy of it, so a malformed
+ * `JOSH_LANE_SEAT` fails when a lane is read for the same reason and with the same message it fails
+ * when `ports/index.js` reads it. A file that assigns no seat is `undefined` — a lane must carry one
+ * to be readable, and `undefined` is not seat 0, which is the main work tree's own.
+ */
+function read_lane_seat(content: string): number | undefined {
+	const raw = read_assignment(content, LANE_SEAT_KEY)
+
+	return raw === undefined ? undefined : ports.resolve_lane({ [LANE_SEAT_KEY]: raw })
+}
+
+/**
+ * The dev and preview ports a lane's `.env` resolves to, through the one formula in `ports`.
+ *
+ * The seed and the seat are read straight out of the file and handed to `ports`, so the
+ * `seed × 10 + seat` multiplication stays in `ports/index.js` and is never re-implemented here.
+ */
+function read_lane_ports(content: string): { development: number; preview: number } {
+	const environment = {
+		[PORT_SEED_KEY]: read_assignment(content, PORT_SEED_KEY),
+		[LANE_SEAT_KEY]: read_assignment(content, LANE_SEAT_KEY),
+	}
+
+	return {
+		development: ports.resolve_development_port(environment),
+		preview: ports.resolve_preview_port(environment),
+	}
+}
+
+/**
+ * The output path a lane's `.env` records, or `undefined` where it records none.
+ *
+ * **A blank assignment is `undefined` rather than an empty path** (joshuafolkken/kit#1713). A lane
+ * whose record was cleared has nothing to poll, and an empty string handed to
+ * `pnpm josh run:liveness --output` is a relative path — refused by its own root check, so the
+ * child would come back `undetermined` for ever rather than saying the record is missing.
+ */
+function read_lane_output(content: string): string | undefined {
+	const line = split_lines(content).findLast((entry) => is_output_line(entry))
+	const raw = line === undefined ? undefined : assignment_value(line)
+
+	return raw === undefined || raw.length === 0 ? undefined : raw
+}
+
+function read_lane_profile(content: string): AgentProfile | undefined {
+	return agent_role_profile.parse({
+		provider: read_assignment(content, LANE_PROVIDER_KEY),
+		role: read_assignment(content, LANE_ROLE_KEY),
+		model: read_assignment(content, LANE_MODEL_KEY),
+		effort: read_assignment(content, LANE_EFFORT_KEY),
+	})
+}
+
+/**
+ * The root file with its seed replaced, or with one appended where it had none.
+ *
+ * Replacing in place rather than appending is what keeps the file honest for a person reading it:
+ * two `PORT_SEED` lines would work — the last wins — and would say two different things.
+ */
+// Every other line for the same key is dropped rather than rewritten alongside: a file carrying two
+// of them works — the last wins — and says two different things to the person reading it.
+function replace_assignment(
+	lines: ReadonlyArray<string>,
+	keep: number,
+	assignment: string,
+	key: string,
+): Array<string> {
+	return lines.flatMap((entry, index) => {
+		if (index === keep) return [assignment]
+
+		return is_key_line(entry, key) ? [] : [entry]
+	})
+}
+
+function upsert_assignment(content: string, key: string, value: string): string {
+	const assignment = `${key}${ASSIGNMENT_SEPARATOR}${value}`
+	const lines = split_lines(content)
+	const last = lines.findLastIndex((entry) => is_key_line(entry, key))
+	const body =
+		last === -1 ? [...lines, assignment] : replace_assignment(lines, last, assignment, key)
+
+	return `${body.join('\n')}\n`
+}
+
+/**
+ * The root file with the lane's seat added, its `PORT_SEED` left exactly as it was.
+ *
+ * The project's seed is the lane's too — only the seat distinguishes them — so it is carried across
+ * verbatim and a `JOSH_LANE_SEAT` line is set beside it. `ports/index.js` then reads both and
+ * offsets the ports by `seed × 10 + seat`.
+ */
+function lane_file_content(root_content: string, seat: number): string {
+	return upsert_assignment(root_content, LANE_SEAT_KEY, String(seat))
+}
+
+/**
+ * The lane's `.env` with its recorded output path replaced, or with one appended where it had none.
+ *
+ * **The value is quoted, and the seed's is not.** A seed is digits; a path can hold a space or a
+ * `#`, and dotenv readers cut a value at an unquoted ` #` — so an unquoted record would come back
+ * truncated to something that still looks like a path. `read_lane_output` unquotes symmetrically.
+ */
+function with_lane_output(content: string, output: string, profile?: AgentProfile): string {
+	const recorded = upsert_assignment(content, LANE_OUTPUT_KEY, `"${output}"`)
+	if (profile === undefined) return recorded
+
+	const with_provider = upsert_assignment(recorded, LANE_PROVIDER_KEY, profile.provider)
+	const with_role = upsert_assignment(with_provider, LANE_ROLE_KEY, profile.role)
+	const with_model = upsert_assignment(with_role, LANE_MODEL_KEY, profile.model)
+
+	return upsert_assignment(with_model, LANE_EFFORT_KEY, profile.effort)
+}
+
+const lane_environment = {
+	LANE_OUTPUT_KEY,
+	LANE_PROVIDER_KEY,
+	LANE_ROLE_KEY,
+	is_output_line,
+	is_seat_line,
+	is_seed_line,
+	lane_file_content,
+	read_lane_output,
+	read_lane_profile,
+	read_lane_ports,
+	read_lane_seat,
+	read_root_seed,
+	with_lane_output,
+}
+
+export { lane_environment }

package/scripts/lane/lane-guard-policy.ts

@@ -0,0 +1,136 @@
+import { lane_child_marker, type MarkerSource } from './lane-child-marker'
+
+// How each `PreToolUse` guard behaves in a dispatched lane child, as an enumeration rather than a
+// judgement (joshuafolkken/kit#2138, joshuafolkken/kit#2164).
+//
+// **The three guards were built for the interactive main line, where a refusal is guidance.** A denial
+// rewrites the next move of a person's session. A dispatched lane child is a headless `claude -p`
+// process, so a *denial* ends the conversation with nothing committed — joshuafolkken/kit#2138 measured
+// a child killed before its commit by two investigation refusals and one batching refusal, every one of
+// them a read of a file the child was about to edit. So a guard whose correction is a denial cannot fire
+// as one in a child.
+//
+// **But a denial is not the only way a guard can speak, and that is what kit#2164 tried.** A guard can
+// also raise a *notice* — a non-blocking `additionalContext` that carries the same guidance without a
+// `permissionDecision`, so the turn is never ended. kit#2164 downgraded the batching guard to a notice
+// in the child for exactly that reason. So the choice is three-valued, not two:
+//
+//   - `refuse` — deny the call (the main-line default; the child keeps this for the safety rules).
+//   - `notice` — let the call through but attach the guidance, so a headless child is nudged, not killed.
+//   - `off`    — say nothing at all, for a guard whose remedy the child cannot carry out.
+//
+// **The notice did not move the number, kit#2178 took it off, and kit#2276 restores it changed.** The
+// lane child that ran right after kit#2164 merged came in at 1.00 calls per turn on both sides of the
+// first notice (transcript `f39efeb5`), so kit#2178 turned the batching notice `off` in the child rather
+// than pay the per-turn context cost of guidance measured not to work. But with it off, the notice fired
+// **zero** times across the 2026-09-21 backlogrun the density was next measured on, so the 1.147 read
+// there is the rate with no guidance at all — not a second measurement of the notice failing. kit#2276
+// therefore restores it as `notice`, with the two things #2164's lacked: it names the concrete recent
+// calls the run issued one-per-turn, and it recurs every single-call turn rather than every three. The
+// mode stays a genuine experiment — the density is re-measured on the next backlogrun, and a notice that
+// still does not move it is redesigned rather than kept.
+//
+// **It is an enumeration and not a judgement, for the reason `delegation-policy.ts` is one.** "This
+// guard's mode in a child" is a call made under the same pressure that produced the misfire. The list is
+// the whole of it, and a guard nobody classified refuses — the safe direction, since a wrongly-silenced
+// rule ships unnoticed while a wrongly-kept one costs at most the one round trip the child already
+// survived once. `lane-guard-policy.test.ts` pins that the enumeration and the guards' live behavior
+// cannot disagree.
+
+// The three ways a guard may behave in a lane child (joshuafolkken/kit#2164). Outside a lane child every
+// guard is `refuse`, which is why that is also the fail-safe default below.
+type LaneGuardMode = 'refuse' | 'notice' | 'off'
+type LaneGuardId = 'investigation' | 'batching' | 'rule' | 'duplicate-read'
+
+// The mode outside a lane child, and the fail-safe for a guard nobody enumerated: a denial, the same
+// direction `delegation-policy.ts` takes, because a silenced rule is the one mistake that ships unseen.
+const DEFAULT_MODE: LaneGuardMode = 'refuse'
+const OFF_MODE: LaneGuardMode = 'off'
+
+interface LaneGuardEntry {
+	id: LaneGuardId
+	// How this guard behaves when the session is a dispatched lane child.
+	mode_in_lane_child: LaneGuardMode
+	// Why. A mode with no reason is a choice nobody can check; the reason names what the child still needs
+	// the guard for, or why the guard cannot fire as a refusal there.
+	because: string
+}
+
+const LANE_GUARD_POLICY: ReadonlyArray<LaneGuardEntry> = [
+	{
+		id: 'investigation',
+		mode_in_lane_child: 'notice',
+		because:
+			'a refusal ends a child turn so it cannot fire as one (kit#2138), which is why it was `off` from #2138 to #2382. The exemption reason — "the child is itself the delegated unit, so it cannot dispatch a sub-unit to read its own edit targets" — did not hold in measurement: kit#2382 re-measured the six lane children after #2347 (#2366 #2370 #2371 #2372 #2374 #2375) and every one dispatched sub-agents (10 launches, 2 of them investigation fan-outs) and read 4–17 files it never edited, all six over the threshold of 3. So the reading the guard exists to send out was there to send. It takes `notice`, not `off`: the child is nudged to delegate rather than killed, on the `additionalContext` path batching and duplicate-read already use, and the notice names the concrete unedited files this run read (the #2276 precedent) rather than the generic "delegate" #2164 → #2178 measured not to move the number. The density is a genuine experiment — re-measured on the next backlogrun, and a notice that still does not move it is redesigned rather than kept',
+	},
+	{
+		id: 'batching',
+		mode_in_lane_child: 'off',
+		because:
+			'a refusal ends a child turn so it cannot fire as one (kit#2138); kit#2164 replaced it with a notice, kit#2178 took that notice off after it did not move the density, and kit#2276 restored it — naming the concrete recent calls and recurring every single-call turn — as a genuine experiment to be redesigned rather than kept if the next backlogrun still missed 1.40. kit#2405 is that re-measurement, and it cuts the notice off (`off`). `josh time:density` read 1.13 calls per round trip over the ten most recent lanes (1.04 in the Issue’s per-message frame), short of the 1.40 target as every advisory attempt before it was (kit#1304/#1329/#1337/#1390/#2164/#2276). The cause is structural rather than wording: a `PreToolUse` hook cannot see the turn it is in — a turn’s later `tool_use` lines arrive 1.4–15s after its first — so it judges only closed turns, and a notice at turn close still asks for the parallel `tool_use` blocks the model resists. The one lever measured to move the density is a composite command the model emits in a single call (`read:files`/`edit:files`, kit#2202/#2311), which needs no notice. So per the issue’s instruction to discontinue advisory means when the target is missed, the notice is cut off rather than rewritten a seventh time; the density stays readable through `josh time:density`',
+	},
+	{
+		id: 'duplicate-read',
+		mode_in_lane_child: 'notice',
+		because:
+			'a refusal ends a child turn so it cannot fire as one (kit#2138), and the unchanged re-reads the guard catches are measured in lane children above all (kit#2298 baseline: 8.0 per lane run) — so silencing it there (`off`) would neuter it exactly where the count lives. It takes `notice` instead: the child is nudged to scroll up to the earlier read rather than killed. The mode is a genuine experiment, as the batching notice is — a notice that does not reduce the duplicate reads on the next backlogrun is redesigned rather than kept',
+	},
+	{
+		id: 'rule',
+		mode_in_lane_child: 'refuse',
+		because:
+			"it carries the lane-only rules a child depends on (`pre-gate-cut`, `implementation-cut`, `lane-park`) and the safety rules a child must still obey (`shell-body`, `piped-verification`); a blanket suppression would disarm exactly the guards written for the child. `implementation-cut` (joshuafolkken/kit#2310) needs `refuse` for the same reason the pre-gate cut does — kit#1864 and kit#2310 both measured a cut carried as prose firing 0 times, so a notice, being prose in front of the run, would drop enforcement without a procedural replacement. The pre-gate-cut refusal does collateral a sibling call batched in the same turn — a `PreToolUse` deny cancels the turn's other parallel calls, which is the harness behavior kit#2177 measured on #2160 (gate refused, its batched `review:brief` cancelled) — and that collateral is not avoidable at the guard level. `notice` was considered for the pre-gate-cut point and rejected: kit#1864 measured the cut taken 0 times while it was carried as prose, and a notice is prose in front of the run (kit#2178 measured a lane-child notice not moving the number), so a notice would drop enforcement without a procedural replacement. kit#2177 supplies that replacement in the procedure instead — the chain orders the cut before the gate, so the cut is issued on its own (its `cut` verdict ends the turn, batching with nothing) and the gate runs in the fresh process where the carried cut keeps this guard silent; the refusal therefore stays `refuse` as insurance and the collateral is gone from the default path rather than from the guard",
+	},
+]
+
+const KNOWN_GUARD_IDS: ReadonlyArray<LaneGuardId> = LANE_GUARD_POLICY.map((entry) => entry.id)
+
+function entry_for(id: string): LaneGuardEntry | undefined {
+	return LANE_GUARD_POLICY.find((entry) => entry.id === id.trim())
+}
+
+// **An unenumerated guard refuses**, the same fail-safe direction `delegation-policy.ts` takes: a guard
+// nobody listed keeps the main-line default rather than being silently downgraded, because a downgrade
+// is what ships a missed rule.
+function mode_in_lane_child(id: string): LaneGuardMode {
+	return entry_for(id)?.mode_in_lane_child ?? DEFAULT_MODE
+}
+
+// The mode that applies to this guard right now. Outside a lane child every guard is `refuse`; inside
+// one it is the enumerated mode. A guard whose lane-child mode is already `refuse` reads the same either
+// way, so the marker — the dispatch mark against this checkout's own issue — is consulted only for a
+// guard the enumeration would actually change, never on every call.
+function mode_here(
+	id: string,
+	directory: string = process.cwd(),
+	source: MarkerSource = process.env,
+): LaneGuardMode {
+	const lane_mode = mode_in_lane_child(id)
+
+	if (lane_mode === DEFAULT_MODE) return DEFAULT_MODE
+
+	return lane_child_marker.is_child_of(directory, source) ? lane_mode : DEFAULT_MODE
+}
+
+// True when this guard must say nothing at all because the session is a dispatched lane child — the
+// `off` mode alone. A `notice`-mode guard is not suppressed: it still speaks, just without a
+// `permissionDecision`, so this must not answer `true` for it.
+function is_suppressed_here(
+	id: string,
+	directory: string = process.cwd(),
+	source: MarkerSource = process.env,
+): boolean {
+	return mode_here(id, directory, source) === OFF_MODE
+}
+
+const lane_guard_policy = {
+	LANE_GUARD_POLICY,
+	KNOWN_GUARD_IDS,
+	entry_for,
+	mode_in_lane_child,
+	mode_here,
+	is_suppressed_here,
+}
+
+export type { LaneGuardMode }
+export { lane_guard_policy }

package/scripts/lane/lane-install.ts

@@ -0,0 +1,94 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { buffered_process } from '#scripts/lib/buffered-process'
+
+// Filling the lane, which is the other half of opening one (joshuafolkken/kit#1554).
+//
+// **A work tree with no `node_modules` is not a lane yet.** A linked work tree starts as a checkout
+// and nothing else, and the lane root is a hidden *sibling* of the repository, so nothing above it
+// resolves either — every `pnpm josh …` typed inside a fresh lane failed with `tsx: command not
+// found`. The install itself is cheap, about 3.5 s from a warm store because pnpm hard-links out of
+// it; what it cost was one failed command and one diagnostic round trip, per lane, every time.
+//
+// **The seconds are not the reason this module exists.** `tsx: command not found` reads like a
+// broken toolchain to anyone who does not know the cause, and the way around a broken toolchain is
+// to verify by some other means — a verification nobody would report as non-standard, because
+// whoever ran it believed it was the only one available.
+//
+// The child is spawned through `buffered_process` rather than through `execa` here. What this needs
+// is exactly that module's contract — output buffered rather than inherited, a non-zero exit
+// reported rather than thrown, and a bound on how long the child may hang — and a second copy of it
+// is how a fix to one missed the other before (joshuafolkken/kit#914).
+
+// `--frozen-lockfile` because a lane is cut from `refs/remotes/origin/<default>` and has to build
+// exactly the lock committed there. A lock the install would rather rewrite is a finding, not
+// something to absorb silently into six parallel lanes.
+const INSTALL_ARGUMENTS = ['install', '--frozen-lockfile']
+// The manifest whose absence is the whole skip condition. A lane cut from a repository that has no
+// `package.json` has nothing to install, so running `pnpm install` there could only fail on a
+// manifest that was never there — which is exactly the fixture a cross-process lane test needs
+// (joshuafolkken/kit#2148). The condition is strictly "the file does not exist": a manifest that is
+// present but unreadable or broken still runs the install and still fails as before, so a genuinely
+// broken repository is never passed silently.
+const MANIFEST_FILE_NAME = 'package.json'
+// The lane opens with no dependencies installed, and that is the reported state rather than a
+// failure — there was nothing to install, so nothing failed.
+const NO_MANIFEST_OUTPUT = `No ${MANIFEST_FILE_NAME} in the lane, so the dependency install was skipped.`
+// The 3.5 s above is a warm store; a first run, or one after a dependency change, goes to the
+// network, so that figure is not the bound to write here. Ten minutes covers that fetch and still
+// ends `lane:open` when a registry never answers, rather than holding a parallel run open with
+// nothing printed. It is well under the fan-out's own half hour because this one blocks a command a
+// person is waiting on, not a check suite.
+const INSTALL_TIMEOUT_MS = 600_000
+
+interface InstallResult {
+	is_installed: boolean
+	// Captured rather than inherited, and reported only on a failure: `lane:open` prints the lane
+	// directory on standard output and nothing else, so an install writing there directly would
+	// break `dir=$(pnpm josh lane:open 1554)` for every caller.
+	output: string
+}
+
+// A lane with no manifest has nothing to install, so the install is skipped rather than run — the
+// seam a cross-process lane test needs, and a root-cause fix rather than a switch, because running
+// an install with no install target was the defect (joshuafolkken/kit#2148). The condition is
+// strictly the file's absence: `existsSync` answers only whether the path is there, never whether
+// its contents parse, so a present-but-broken manifest falls through to the real install and fails
+// exactly as before.
+function has_manifest(directory: string): boolean {
+	return existsSync(path.join(directory, MANIFEST_FILE_NAME))
+}
+
+/**
+ * Install the lane's dependencies, and report whether it worked rather than throwing.
+ *
+ * **A lane with no `package.json` skips the install** — there is nothing to install, so the reported
+ * state is installed rather than failed, and no child is spawned (joshuafolkken/kit#2148). This is
+ * the only seam: the production call path, its arguments and its environment are all unchanged.
+ *
+ * **The verdict is the exit code and only the exit code.** `pnpm install` runs `prepare`, which runs
+ * the lefthook installer, and in a linked work tree the hooks are shared with the primary repository
+ * — so a warning from it is expected and correct (joshuafolkken/kit#1503, #1507). Reading the child's
+ * text for a word like "failed" would turn that correct warning into a refusal to open a lane.
+ */
+async function install_dependencies(directory: string): Promise<InstallResult> {
+	if (!has_manifest(directory)) return { is_installed: true, output: NO_MANIFEST_OUTPUT }
+
+	const result = await buffered_process.run_buffered_process(INSTALL_ARGUMENTS, {
+		cwd: directory,
+		timeout_ms: INSTALL_TIMEOUT_MS,
+	})
+
+	return { is_installed: !buffered_process.is_process_failed(result), output: result.output }
+}
+
+const lane_install = { install_dependencies }
+
+export type { InstallResult }
+export {
+	lane_install,
+	INSTALL_ARGUMENTS,
+	INSTALL_TIMEOUT_MS,
+	MANIFEST_FILE_NAME,
+	NO_MANIFEST_OUTPUT,
+}

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

@@ -0,0 +1,133 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { josh_command } from '#scripts/josh/josh-run'
+import { execa } from 'execa'
+
+// `josh lane:launch <issue> [--stash <message>]` — one composite command for a `backlogrun` lane-start
+// event (joshuafolkken/kit#2162). Opening one lane was four to six turns of the parent: `lane:open`,
+// then — only the first lane, and only when `josh latest` had stashed — `stash:pop` and a re-install,
+// then `lane:dispatch`. This collapses them into one call that returns the child's pid, or a refusal,
+// the same shape `lane:dispatch` alone has.
+//
+// **It is a thin layer over the existing commands**, shelling out to each so their guards, refusals
+// and messages are reused rather than cloned — `lane:open`'s cut-session guard and its `full` /
+// `already-open` refusals, `stash:pop`'s message-matched pop, `lane:dispatch`'s in-progress claim and
+// warning. Their explanations stream through to stderr; the child's pid is the one thing on stdout.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const should_forward_stderr = true
+const PNPM = 'pnpm'
+const ISSUE_PATTERN = /^[1-9]\d*$/u
+
+const USAGE = 'Usage: josh lane:launch <issue-number> [--stash <message>]'
+
+const OPTIONS = { stash: { type: 'string' } } as const
+
+// The stash message is present only for the first lane — the caller passes `--stash` there and nowhere
+// else, so "only the first lane pops and re-installs" is preserved by which invocation carries it.
+interface LaunchContext {
+	issue: string
+	stash: string | undefined
+}
+
+function read_context(argv: ReadonlyArray<string>): LaunchContext | undefined {
+	try {
+		const parsed = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			strict: true,
+			allowPositionals: true,
+		})
+		const [issue, ...rest] = parsed.positionals
+
+		if (issue === undefined || rest.length > 0 || !ISSUE_PATTERN.test(issue)) return undefined
+
+		return { issue, stash: parsed.values.stash }
+	} catch {
+		return undefined
+	}
+}
+
+// The pop brought in the `pnpm-lock.yaml` `josh latest` rewrote, so this one lane installs a second
+// time against it. Output is captured and surfaced only on failure, so the composite's stdout stays
+// the child's pid alone.
+async function install(directory: string): Promise<boolean> {
+	const result = await execa(PNPM, ['--dir', directory, 'install', '--frozen-lockfile'], {
+		reject: false,
+	})
+
+	if ((result.exitCode ?? FAILURE_EXIT_CODE) === SUCCESS_EXIT_CODE) return true
+
+	console.error(result.stderr === '' ? result.stdout : result.stderr)
+
+	return false
+}
+
+// The first lane pops the shared stash and re-installs against the lock it brought in; a pop that
+// refused (`no-match` / `ambiguous`) stops the lane rather than dispatching onto an unprepared tree.
+// A caller without `--stash` skips both, which is every lane after the first.
+async function prepare(stash: string | undefined, directory: string): Promise<boolean> {
+	if (stash === undefined) return true
+
+	const popped = await josh_command.josh_run(
+		['stash:pop', stash, '--dir', directory],
+		should_forward_stderr,
+	)
+
+	if (popped.code !== SUCCESS_EXIT_CODE) return false
+
+	return await install(directory)
+}
+
+// The launch chain in-process: the dispatched child's pid, or `undefined` when a step refused. The CLI
+// prints the pid; `backlog:drive` launches through this same chain (joshuafolkken/kit#2508).
+async function launch_lane(context: LaunchContext): Promise<string | undefined> {
+	const opened = await josh_command.josh_run(['lane:open', context.issue], should_forward_stderr)
+
+	if (opened.code !== SUCCESS_EXIT_CODE) return undefined
+
+	if (!(await prepare(context.stash, opened.out))) return undefined
+
+	const dispatched = await josh_command.josh_run(
+		['lane:dispatch', context.issue],
+		should_forward_stderr,
+	)
+
+	return dispatched.code === SUCCESS_EXIT_CODE ? dispatched.out : undefined
+}
+
+async function launch(context: LaunchContext): Promise<number> {
+	const pid = await launch_lane(context)
+
+	if (pid === undefined) return FAILURE_EXIT_CODE
+
+	console.info(pid)
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const context = read_context(argv)
+
+	if (context === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await launch(context)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_launch_cli = { USAGE, install, launch, launch_lane, prepare, read_context, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export type { LaunchContext }
+export { lane_launch_cli }