@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/git/git-schemas.ts

@@ -42,17 +42,16 @@ const epic_issue_schema = z.object({
 })
 
 // One blocker as `gh` reports it inside the `blockedBy` connection. `state` comes back with the
-// number, so telling a resolved blocker from a standing one costs no extra request
-// (joshuafolkken/kit#996).
+// number, so telling a resolved blocker from a standing one costs no extra request.
 // `number` is **required**. Relaxing it looks harmless and is not: `epic_issue.blockers_of` maps the
 // nodes to their numbers, so an optional one turns a `blockedBy` shape change from a failed parse —
 // which marks the child unreadable — into an empty blocker list, and `epic:next` then hands a
 // dependent to an unattended run before its prerequisite. Fail-safe is the direction that matters
-// here (joshuafolkken/kit#1005).
+// here.
 //
 // `repository_url` is the repository the blocker lives in, as REST names it
-// (`https://api.github.com/repos/<owner>/<repo>`). Carried since joshuafolkken/kit#1126: a
-// `blocked-by` relation may cross a repository, and a reader that keeps only the number resolves it
+// (`https://api.github.com/repos/<owner>/<repo>`). Carried because a `blocked-by` relation may
+// cross a repository, and a reader that keeps only the number resolves it
 // against the blocked child's own repository — a different issue, or none. Optional because a
 // caller that only wants numbers must not be made to fail on a response shape it never reads.
 const blocking_issue_schema = z.object({
@@ -62,16 +61,11 @@ const blocking_issue_schema = z.object({
 })
 
 // The blocker relations arrive as a connection — `{ nodes, totalCount }` — not a bare array.
-// Measured against a real issue rather than assumed (joshuafolkken/kit#860). `gh issue view`
-// answered the connection itself; since joshuafolkken/kit#1024 REST serves a bare array from the
-// issue's own `dependencies/blocked_by` endpoint and `git-gh-issue-rest.ts` maps it back into this
-// shape, so every reader below is unchanged.
+// REST serves a bare array from the issue's own `dependencies/blocked_by` endpoint and
+// `git-gh-issue-rest.ts` maps it back into this shape.
 //
-// **One definition, every reader.** The same connection was written out three times — twice here and
-// once in `scripts/epic/epic-issue.ts` — each naming only the fields its own caller happened to want,
-// so a shape change had three places to reach and one of them would not be noticed. That is the
-// duplication joshuafolkken/kit#862 removed from the epic commands, reintroduced by the readers that
-// came after (joshuafolkken/kit#1005).
+// **One definition, every reader.** A copy per reader, each naming only the fields its own caller
+// wants, would give a shape change several places to reach, one of which would not be noticed.
 //
 // `nodes` is a page — `blockedBy(first:50)` under GraphQL, one unpaged `per_page=100` request under
 // REST — while `totalCount` is exact, read from the issue's own dependency summary. A reader that
@@ -80,8 +74,7 @@ const blocking_issue_schema = z.object({
 // reads as complete. Every issue the reads go through carries one, so that is a guard rather than
 // a case. **Only the `auto-ok` pickup compares them**; the epic readers judge from the page they
 // were given, so an epic child declaring more blockers than one page holds is read from the first
-// page. Carried here so the field is available, not because every reader consults it
-// (joshuafolkken/kit#1005).
+// page. Carried here so the field is available, not because every reader consults it.
 const blocked_by_schema = z
 	.object({
 		nodes: z.array(blocking_issue_schema).default([]),
@@ -99,7 +92,7 @@ const epic_child_schema = z.object({
 //
 // Carried here rather than beside either reader: the pull request's conversation comments and an
 // epic's are the *same endpoint* answering the same objects, so a second declaration of this shape
-// would be the clone `CLAUDE.md` prohibits (joshuafolkken/kit#1039). `ai_review_pull_comment_schema`
+// would be the clone `CLAUDE.md` prohibits. `ai_review_pull_comment_schema`
 // above is the `gh --json` spelling the scan reads after the mapping, not this one.
 const rest_comment_schema = z.looseObject({
 	body: z.string().nullish(),
@@ -112,7 +105,7 @@ const rest_comment_schema = z.looseObject({
 const issue_label_schema = z.object({ name: z.string() })
 
 // `state` is optional because most readers ignore it — only `epic-add.ts` consults it, to refuse
-// adding a child to a closed epic (joshuafolkken/kit#2337). A reader that never asks the state field
+// adding a child to a closed epic. A reader that never asks the state field
 // still parses cleanly.
 const epic_subject_schema = z.object({
 	number: z.number(),
@@ -123,11 +116,11 @@ const epic_subject_schema = z.object({
 
 // One row of an open-issue listing, under the field names `gh issue list --json` answered with.
 // Three readers parse a listing through this shape: the next-issues display printed when a workflow
-// completes (#821), the `auto-ok` pickup (joshuafolkken/kit#906), and the per-repository busy check
-// `epic:next` makes before it offers a child (joshuafolkken/kit#925).
+// completes, the `auto-ok` pickup, and the per-repository busy check
+// `epic:next` makes before it offers a child.
 //
-// The row is *assembled* under those names rather than returned under them. Since
-// joshuafolkken/kit#1025 the listing is REST, and `blockedBy` is not part of a listing response at
+// The row is *assembled* under those names rather than returned under them. The listing is REST,
+// and `blockedBy` is not part of a listing response at
 // all: `git-gh-issue-list.ts` reads the relations from each row's own dependencies endpoint, and
 // only for the pickup, which is the one caller whose field list names `blockedBy` at all.
 //
@@ -140,7 +133,7 @@ const open_issue_schema = z.object({
 	labels: z.array(issue_label_schema).optional(),
 	createdAt: z.string(),
 	blockedBy: blocked_by_schema,
-	// Present only on the pickup listing, which reads it for the restructures each issue declares.
+	// Present only on the pickup listing, which reads it for the paths each issue declares.
 	body: z.string().optional(),
 })
 

package/scripts/git/git-spawn-sync.ts

@@ -3,7 +3,7 @@ import { GIT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import { git_utilities } from './constants'
 
-// The one place a synchronous git command is spawned from (joshuafolkken/kit#3065) — the sync
+// The one place a synchronous git command is spawned from — the sync
 // counterpart of `git-spawn.ts`. Every caller here wants an answer rather than an exception, so a
 // non-zero exit is returned as a result, and every call is bounded: a git that never answers is an
 // unknown the caller already handles, never a hang.

package/scripts/git/git-spawn.ts

@@ -1,3 +1,4 @@
+import { GIT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { git_utilities } from './constants'
 import {
@@ -9,7 +10,7 @@ import {
 import { PUSH_TIMEOUT_MS } from './git-push-transport'
 import { git_ssh_keepalive } from './git-ssh-keepalive'
 
-// The one place the ordinary git commands are spawned from (joshuafolkken/kit#1640). It sits in a
+// The one place the ordinary git commands are spawned from. It sits in a
 // module of its own rather than inside `git-command.ts` so that a second command module —
 // `git-worktree.ts` — can read it without importing the first. `read` is what resolves the git binary
 // and turns a non-zero exit into an error, and a second spawn helper beside it would be the clone
@@ -19,26 +20,32 @@ import { git_ssh_keepalive } from './git-ssh-keepalive'
 // second helper of this kind: a push needs a transport-fault retry that no other command has, so it
 // spawns git itself. The timeout it carries is shared here by `read_remote` / `with_output_remote`. Those two files are the spawn sites of the ordinary command
 // modules — the claim stops there. A synchronous caller goes through `git-spawn-sync.ts`, the same
-// binary resolution with a result instead of an exception (joshuafolkken/kit#3065). Other parts of
+// binary resolution with a result instead of an exception. Other parts of
 // this package spawn git for their own purposes (`scripts/run/progress/run-progress-clock.ts`,
 // `scripts/git/git-fixture-workspace.ts`), and an audit of how the git binary is resolved has to read
 // those too.
 
-async function read(arguments_: Array<string>): Promise<string> {
+// Bounded by `GIT_TIMEOUT_MS` unless the caller says otherwise, as the synchronous `git_spawn_sync.run`
+// is: a local git that never answers ends the call instead of holding an unattended run open.
+async function read(
+	arguments_: Array<string>,
+	timeout_ms: number = GIT_TIMEOUT_MS,
+): Promise<string> {
 	const git_cmd = git_utilities.get_git_command_for_spawn()
 	// execa runs the binary directly with an argument array and no `shell` option, so CLI
 	// args cannot break out of a shell sandbox; the git command and args are internally
 	// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
-	const { stdout } = await execa(git_cmd, arguments_) // NOSONAR
+	const { stdout } = await execa(git_cmd, arguments_, { timeout: timeout_ms }) // NOSONAR
 
 	return stdout.trimEnd()
 }
 
-// The budget for a git call that talks to the remote — `fetch` and `pull` (joshuafolkken/kit#2942).
-// `read` and `with_output` wait without end, and a `git fetch --prune` under `josh main:sync` sat on
-// a dead ssh connection for 37 minutes, stalling the unattended backlog driver whose merge step runs
-// it. The push's budget is reused rather than a second number chosen: both transfer objects over the
-// same transport, and that one is already read off what a healthy transfer costs here.
+// The budget for a git call that talks to the remote — `fetch` and `pull`.
+// `read` and `with_output` once waited without end, and a `git fetch --prune` under `josh main:sync`
+// sat on a dead ssh connection for 37 minutes, stalling the unattended backlog driver whose merge step
+// runs it. Their default now is a local command's, far too short for a transfer, so a remote call
+// still takes this one. The push's budget is reused rather than a second number chosen: both transfer
+// objects over the same transport, and that one is already read off what a healthy transfer costs here.
 const REMOTE_TIMEOUT_MS = PUSH_TIMEOUT_MS
 const MS_PER_SECOND = 1000
 
@@ -46,7 +53,7 @@ const MS_PER_SECOND = 1000
 // `cause` carries the same `TIMEOUT_EXIT_CODE` a timed-out push does. Unlike the push it is not
 // retried here: what the issue needed is that the wait ends, and a failure then surfaces to the
 // caller — `run:merge` raises a failed `main:sync` — instead of a second budget doubling the wait.
-function to_remote_error(command: string, error: unknown, timeout_ms: number): Error {
+function to_budget_error(command: string, error: unknown, timeout_ms: number): Error {
 	if (!has_timed_out(error)) return create_spawn_error(command, get_exit_code(error))
 
 	const seconds = String(Math.round(timeout_ms / MS_PER_SECOND))
@@ -75,7 +82,7 @@ async function spawn_remote(arguments_: Array<string>, options: RemoteOptions):
 
 		return typeof stdout === 'string' ? stdout.trimEnd() : ''
 	} catch (error) {
-		throw to_remote_error(arguments_[0] ?? '', error, options.timeout)
+		throw to_budget_error(arguments_[0] ?? '', error, options.timeout)
 	}
 }
 
@@ -101,16 +108,32 @@ async function with_output_remote(command: string, arguments_list: Array<string>
 	})
 }
 
-async function with_output(command: string, arguments_list: Array<string>): Promise<void> {
+// `config_options` are `-c <key>=<value>` pairs, which git reads only ahead of the command name and
+// which last for this one call — nothing is written into anyone's git configuration.
+//
+// `timeout_ms` defaults to a local command's budget. A command that runs hooks — a commit, a merge,
+// `git hook run` — is not one, and names the longer budget itself.
+interface OutputOptions {
+	config_options?: ReadonlyArray<string>
+	timeout_ms?: number
+}
+
+async function with_output(
+	command: string,
+	arguments_list: Array<string>,
+	options: OutputOptions = {},
+): Promise<void> {
+	const { config_options = [], timeout_ms = GIT_TIMEOUT_MS } = options
 	const git_command_bin = git_utilities.get_git_command_for_spawn()
+	const spawn_arguments = [...config_options, command, ...arguments_list]
 
 	try {
 		// execa runs the binary directly with an argument array and no `shell` option, so CLI
 		// args cannot break out of a shell sandbox; the git command and args are internally
 		// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
-		await execa(git_command_bin, [command, ...arguments_list], { stdio: 'inherit' }) // NOSONAR
+		await execa(git_command_bin, spawn_arguments, { stdio: 'inherit', timeout: timeout_ms }) // NOSONAR
 	} catch (error) {
-		throw create_spawn_error(command, get_exit_code(error))
+		throw to_budget_error(command, error, timeout_ms)
 	}
 }
 

package/scripts/git/git-ssh-keepalive.ts

@@ -1,8 +1,10 @@
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { git_utilities } from './constants'
+import { has_timed_out } from './git-execa-error'
 
-// The ssh environment every git network call runs under (joshuafolkken/kit#2942). It began inside
-// `git-push-transport.ts` as the push's own (joshuafolkken/kit#1251), and moved here when the fetch
+// The ssh environment every git network call runs under. It began inside
+// `git-push-transport.ts` as the push's own, and moved here when the fetch
 // and pull of `josh main:sync` turned out to need the same thing: a dead connection under a `git
 // fetch` was waited on for 37 minutes, stalling the unattended backlog driver behind it.
 //
@@ -16,6 +18,8 @@ const SSH_COMMAND_VARIABLE = 'GIT_SSH_COMMAND'
 const SSH_LEGACY_VARIABLE = 'GIT_SSH'
 const KEEPALIVE_SSH_COMMAND = `ssh ${SSH_KEEPALIVE_OPTIONS}`
 const SSH_COMMAND_CONFIG_KEY = 'core.sshCommand'
+const CONFIG_PROBE_ARGUMENTS = ['config', '--get', SSH_COMMAND_CONFIG_KEY]
+const PROBE_OPTIONS = { timeout: PROBE_TIMEOUT_MS }
 
 // Whatever already decides how ssh is invoked, or an empty string when nothing does. git reads three
 // sources in this order — `GIT_SSH_COMMAND`, `core.sshCommand`, then the legacy `GIT_SSH` — and the
@@ -50,12 +54,15 @@ async function has_configured_ssh_command(): Promise<boolean> {
 		// execa runs the binary directly with an argument array and no `shell` option, so CLI
 		// args cannot break out of a shell sandbox; the git command and args are internally
 		// controlled, never untrusted input. tssecurity:S8705 is a false positive here.
-		const { stdout } = await execa(git_command_bin, ['config', '--get', SSH_COMMAND_CONFIG_KEY]) // NOSONAR
+		const { stdout } = await execa(git_command_bin, CONFIG_PROBE_ARGUMENTS, PROBE_OPTIONS) // NOSONAR
 
 		return stdout.trim() !== ''
-	} catch {
+	} catch (error) {
 		// `git config --get` exits 1 when the key is unset, which is the answer rather than a failure.
-		return false
+		// A probe that never answers lands here as well: the remote call awaits this before its own
+		// budget starts, so a wait here is one that budget cannot end. It did not say the key is unset,
+		// so it reads as configured — guessing "unset" would put a plain `ssh` over a per-repository key.
+		return has_timed_out(error)
 	}
 }
 

package/scripts/git/git-staging.ts

@@ -68,17 +68,16 @@ async function stage_untracked_files(files: ReadonlyArray<string>): Promise<void
 	for (const file of files) console.info(`   + ${file}`)
 }
 
-// **The observation ledger rides the run's own commit** (joshuafolkken/kit#2763). It used to be
-// excluded here (joshuafolkken/kit#1756) and committed afterwards by `pnpm josh observations:flush` as
-// a pull request of its own — a second branch, CI wait and merge behind every run that appended a
-// line, 144 of them in one month. Staged with the run instead, the lines are reviewed and merged with
-// the pull request whose run recorded them, while CI for that pull request is the only wait.
+// **The observation ledger rides the run's own commit**. Committing it separately would cost a
+// second branch, CI wait and merge behind every run that appended a line. Staged with the run, the
+// lines are reviewed and merged with the pull request whose run recorded them, while CI for that pull
+// request is the only wait.
 //
-// **A line that breaks the grammar keeps the old exclusion** (joshuafolkken/kit#2123): the commit
+// **A line that breaks the grammar keeps the old exclusion**: the commit
 // goes ahead without the ledger, and `pnpm josh observations:flush` — which refuses the same line and
 // names it — is where it is repaired. The migration is run first, as the flush runs it, so a line
-// still on an old path (joshuafolkken/kit#2724) is committed in the directory. **A lane carries its
-// own lines** (joshuafolkken/kit#2919): its writers append to its own tree's issue file, so this is
+// still on an old path is committed in the directory. **A lane carries its
+// own lines**: its writers append to its own tree's issue file, so this is
 // the step that takes them to the default branch.
 const LEDGER_PATHSPECS: ReadonlyArray<string> = [
 	...LEDGER_DIRECTORIES,

package/scripts/git/git-workflow.ts

@@ -189,7 +189,7 @@ function build_commit_message(
 }
 
 // The file form exists because the PR body now carries a live-execution evidence section of commands
-// and their output (joshuafolkken/kit#2446) — text an inline double-quoted `--body` would have the shell
+// and their output — text an inline double-quoted `--body` would have the shell
 // evaluate first. Resolved through `cli_body`, the shared reader every `*-file` flag uses.
 function resolve_pr_body(values: CliArguments['values']): string | undefined {
 	return cli_body.resolve({

package/scripts/git/git-worktree.ts

@@ -1,10 +1,11 @@
+import { INSTALL_TIMEOUT_MS, SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { PORCELAIN_FLAG } from './constants'
 import { ls_remote_branch_arguments } from './git-ls-remote'
 import { git_spawn } from './git-spawn'
 import { repository_lock } from './repository-lock'
 
-// The four worktree reads and writes a lane's lifecycle needs, plus the branch deletion that ends it
-// (joshuafolkken/kit#1490; split out of `git-command.ts` under joshuafolkken/kit#1640). They live
+// The four worktree reads and writes a lane's lifecycle needs, plus the branch deletion that ends it.
+// They live
 // beside the other git commands rather than in `scripts/lane/` because `git_spawn.read` is what
 // resolves the git binary and turns a non-zero exit into an error — a second spawn helper next to it
 // would be the clone `CLAUDE.md` prohibits, so this module imports the shared one.
@@ -13,15 +14,14 @@ import { repository_lock } from './repository-lock'
 // asynchronous `git ls-remote` spawn, and a second spawn helper beside it would be that same clone.
 // **It is not the only one in this package** — `propagate_git.has_remote_branch` runs the same query
 // synchronously against a consumer's path, and the two share their arguments through
-// `git-ls-remote.ts` rather than the spawn (joshuafolkken/kit#1732). Its sole
-// caller is now `git-remote-branch.ts`, which turns the raw output into the three-way answer
-// (`absent` / `present` / `unreachable`) that `lane-start-point.ts` and `release-publish.ts` both act
-// on — so this module stops at "what git printed" and the meaning of it is decided there
-// (joshuafolkken/kit#1641; before it, `lane-start-point.ts` was the only reader and did both).
+// `git-ls-remote.ts` rather than the spawn. Its sole caller is `git-remote-branch.ts`, which turns
+// the raw output into the three-way answer (`absent` / `present` / `unreachable`) that
+// `lane-start-point.ts` and `release-publish.ts` both act on — so this module stops at "what git
+// printed" and the meaning of it is decided there.
 const WORKTREE = 'worktree'
 
-// **Every call that writes `.git/worktrees/` runs under one repository-wide lock**
-// (joshuafolkken/kit#2736). `git worktree add` is not safe against itself: while one add is still
+// **Every call that writes `.git/worktrees/` runs under one repository-wide lock**.
+// `git worktree add` is not safe against itself: while one add is still
 // building `.git/worktrees/<id>/` — its `commondir` not yet written — a second add enumerates the
 // existing registrations, reads the half-built one and fails with `fatal: failed to read
 // .git/worktrees/<id>/commondir`. Two lanes opened at once do exactly that, and the per-seat lock in
@@ -33,10 +33,13 @@ const WORKTREE_LOCK_PREFIX = 'josh-worktree-lock-'
 // because a large repository's checkout is itself several seconds, and several lanes queue behind it.
 const WORKTREE_LOCK_MAX_WAIT_MS = 120_000
 
-async function locked(arguments_: Array<string>): Promise<string> {
+// `timeout_ms` is left out by every call that only edits git's own records. An add checks a tree out
+// and so runs the `post-checkout` hook — a `pnpm install` in some consumers — on a suite's budget
+// instead of a local git command's, and a removal names the budget of what it deletes.
+async function locked(arguments_: Array<string>, timeout_ms?: number): Promise<string> {
 	const target = repository_lock.lock_path(WORKTREE_LOCK_PREFIX)
 	const output = await repository_lock.with_lock(
-		async () => await git_spawn.read(arguments_),
+		async () => await git_spawn.read(arguments_, timeout_ms),
 		target,
 		WORKTREE_LOCK_MAX_WAIT_MS,
 	)
@@ -61,15 +64,15 @@ async function worktree_list(): Promise<string> {
 // a detached HEAD; `start_point` is passed explicitly rather than left to `HEAD`, because a lane is
 // branched from the default branch whatever the checkout that opened it happens to be sitting on.
 //
-// **`--no-track` is load-bearing now that the start point is a remote-tracking ref**
-// (joshuafolkken/kit#1535). Branching from `refs/remotes/origin/<default>` makes git's default
+// **`--no-track` is load-bearing now that the start point is a remote-tracking ref**.
+// Branching from `refs/remotes/origin/<default>` makes git's default
 // `branch.autoSetupMerge` set `branch.<lane>.merge=refs/heads/<default>`, and a bare `git push` from
 // the lane then fails with "the upstream branch of your current branch does not match the name of
 // your current branch" — which is *not* the missing-upstream error `push()` retries as
 // `--set-upstream`, so every lane's `pnpm josh git` would stop there. Measured against git 2.x.
 //
 // **An absent `start_point` attaches the tree to the branch that is already there, and neither flag
-// is passed then** (joshuafolkken/kit#1627). `-b` refuses a branch that exists, so a lane whose child
+// is passed then**. `-b` refuses a branch that exists, so a lane whose child
 // had already pushed could not be reopened at all; deleting the branch first to get `-b` back would
 // discard those commits and orphan the pull request. `--no-track` cannot ride along either — git
 // answers `--[no-]track can only be used if a new branch is created` — and it has nothing to do here:
@@ -81,22 +84,25 @@ async function worktree_add(
 ): Promise<string> {
 	const flags = start_point === undefined ? ['add'] : ['add', '--no-track', '-b', branch_name]
 
-	return await locked([WORKTREE, ...flags, directory, start_point ?? branch_name])
+	return await locked([WORKTREE, ...flags, directory, start_point ?? branch_name], SUITE_TIMEOUT_MS)
 }
 
 // A throwaway tree at one commit, on no branch — `josh test:red` checks the merge-base out here, so
-// the pre-fix tree is built without creating a branch or touching the caller's tree and index
-// (joshuafolkken/kit#2448).
+// the pre-fix tree is built without creating a branch or touching the caller's tree and index.
 async function worktree_add_detached(directory: string, commit: string): Promise<string> {
-	return await locked([WORKTREE, 'add', '--detach', directory, commit])
+	return await locked([WORKTREE, 'add', '--detach', directory, commit], SUITE_TIMEOUT_MS)
 }
 
 // **`--force` is the point, not a convenience.** A lane is closed after a park, a failure or an
 // interruption as readily as after a success, and in each of those the tree still holds uncommitted
 // or untracked work. Refusing to remove it there would leave exactly the debris the close exists to
 // prevent.
+//
+// **It takes an install's budget, not a local git command's.** The tree it deletes holds the
+// `node_modules` an install wrote, and a removal cut partway leaves a half-deleted tree git still
+// registers — which `release_worktree.remove` does not step over, so the release branch stays too.
 async function worktree_remove(directory: string): Promise<string> {
-	return await locked([WORKTREE, 'remove', '--force', directory])
+	return await locked([WORKTREE, 'remove', '--force', directory], INSTALL_TIMEOUT_MS)
 }
 
 // Drops the registrations whose directories are already gone — what makes a lane whose directory was
@@ -105,21 +111,23 @@ async function worktree_prune(): Promise<string> {
 	return await locked([WORKTREE, 'prune'])
 }
 
-// **Asked of the remote itself, because nothing prunes the remote-tracking refs**
-// (joshuafolkken/kit#1627). `lane:close` deletes the local branch, GitHub deletes the remote one at
+// **Asked of the remote itself, because nothing prunes the remote-tracking refs**.
+// `lane:close` deletes the local branch, GitHub deletes the remote one at
 // the merge, and `refs/remotes/origin/<N>-lane` outlives both: this repository carried sixteen of
 // them for branches the remote no longer had. Empty output on a zero exit is therefore "not on the
 // remote", which a stale ref cannot say, and a non-zero exit is "could not ask" — a different answer
 // again, and the reason the caller cannot use `fetch` for this: `fetch` fails identically for a
 // branch that is gone and for a network that is down, and prunes neither (measured on git 2.x).
 //
-// **The arguments come from `git-ls-remote.ts`, which is the single source of the full ref path**
-// (joshuafolkken/kit#1709 for the anchoring, joshuafolkken/kit#1732 for the sharing). What broke
-// here was the truthfulness of the message rather than the safety of the answer: `lane:open` was
-// told origin has the lane branch and then stopped naming a branch nobody could find there, and the
-// release guard refused a name that was free.
+// **The arguments come from `git-ls-remote.ts`, which is the single source of the full ref path.**
+// An unanchored ref would make the message untruthful rather than the answer unsafe: `lane:open`
+// would be told origin has the lane branch and then stop naming a branch nobody could find there,
+// and the release guard would refuse a name that was free.
+//
+// **It takes the remote budget, not `read`'s**: that default is a local command's, and an ssh that
+// is slow to connect or waiting at a passphrase prompt would be cut there and read as `unreachable`.
 async function ls_remote_branch(branch_name: string): Promise<string> {
-	return await git_spawn.read(ls_remote_branch_arguments(branch_name))
+	return await git_spawn.read_remote(ls_remote_branch_arguments(branch_name))
 }
 
 // `-D` rather than `-d`: a lane branch is deleted whatever state its work reached, and `-d` refuses

package/scripts/git/gone-branch.ts

@@ -1,6 +1,6 @@
 import { git_spawn } from './git-spawn'
 
-// The local branches `josh ms` removes after it syncs (joshuafolkken/kit#2504). The repository
+// The local branches `josh ms` removes after it syncs. The repository
 // deletes a pull request's remote branch at the merge, and nothing removed the local copy: measured on
 // 2026-09-24, 212 of the primary checkout's 244 local branches tracked an upstream that was `[gone]`.
 //
@@ -102,7 +102,7 @@ async function delete_each(names: ReadonlyArray<string>): Promise<PruneResult> {
 
 // `fetch --prune` first, because `[gone]` is read from the remote-tracking refs and those outlive the
 // remote branch until something prunes them. The fetch is the one call here that reaches the remote,
-// so it is the one bounded (joshuafolkken/kit#2942).
+// so it is the one bounded.
 async function prune(default_branch: string): Promise<PruneResult> {
 	await git_spawn.read_remote(['fetch', '--prune'])
 

package/scripts/git/listing-cutoff.ts

@@ -1,7 +1,6 @@
 import { MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
 
-// Why an open-issue listing stopped short of the end of the backlog, or that it did not
-// (joshuafolkken/kit#1067).
+// Why an open-issue listing stopped short of the end of the backlog, or that it did not.
 //
 // Every caller of `issue_list` asks this same question, and before this the answer was written
 // out again at each of them — `rows.length >= LIMIT` in `epic:bundle` and the `auto-ok` pickup, a

package/scripts/git/lockfile-sync.ts

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { lane_install } from '#scripts/lane/lane-install'
+
+// Keeping the primary checkout's `node_modules` in step with its lock. A
+// fast-forward that brought in a merge adding `cli-spinners` left the primary checkout without it, and
+// every `josh` typed there — the supervisor's driver included — failed with `ERR_MODULE_NOT_FOUND`
+// until someone ran the install by hand.
+//
+// **The trigger is the lock differing from the one last installed, not the sync itself.** Most syncs
+// pull no dependency change, and an install on every one would cost seconds per child for nothing. The
+// comparison is against a record written after a successful install rather than against the lock read
+// before the sync: a sync-relative trigger forgets a failed install, so the retry saw an unchanged lock
+// and left `node_modules` stale, where this one keeps asking until an install succeeds. The record lives
+// inside `node_modules`, so deleting the directory forgets it too. The install is `lane_install`'s, so
+// `--frozen-lockfile`, the buffered output and the timeout stay single-sourced with the lane's own fill.
+
+const LOCKFILE_NAME = 'pnpm-lock.yaml'
+const RECORD_PATH = path.join('node_modules', '.josh-installed-lock')
+
+const UP_TO_DATE = { is_installed: true, output: '' }
+
+interface LockfileSyncResult {
+	is_installed: boolean
+	output: string
+}
+
+function read_text(file_path: string): string | undefined {
+	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : undefined
+}
+
+function digest(content: string): string {
+	return createHash('sha256').update(content).digest('hex')
+}
+
+function record(directory: string, lock_digest: string): void {
+	const record_path = path.join(directory, RECORD_PATH)
+
+	mkdirSync(path.dirname(record_path), { recursive: true })
+	writeFileSync(record_path, lock_digest)
+}
+
+/**
+ * Reinstall when the lock in `directory` differs from the one the last successful install recorded.
+ * A checkout with no lock, or one already installed, spawns nothing and reports installed.
+ */
+async function reinstall_if_stale(directory: string): Promise<LockfileSyncResult> {
+	const lock = read_text(path.join(directory, LOCKFILE_NAME))
+
+	if (lock === undefined) return UP_TO_DATE
+	const lock_digest = digest(lock)
+
+	if (read_text(path.join(directory, RECORD_PATH)) === lock_digest) return UP_TO_DATE
+	const result = await lane_install.install_dependencies(directory)
+
+	if (result.is_installed) record(directory, lock_digest)
+
+	return result
+}
+
+const lockfile_sync = { reinstall_if_stale }
+
+export type { LockfileSyncResult }
+export { lockfile_sync, LOCKFILE_NAME, RECORD_PATH }

package/scripts/git/main-merge-guard.ts

@@ -1,7 +1,6 @@
 import { git_spawn } from './git-spawn'
 
-// What `josh main:merge` refuses before it merges, and what it tells the run to do instead
-// (joshuafolkken/kit#2445).
+// What `josh main:merge` refuses before it merges, and what it tells the run to do instead.
 //
 // **A dirty tree is not refused as such.** The chain runs `main:merge` before the commit, over the
 // uncommitted implementation, and git carries uncommitted changes through a merge that touches none of

package/scripts/git/main-merge.ts

@@ -1,13 +1,13 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { extract_issue_number } from '#scripts/hooks/check-commit-message'
+import { issue_cite } from '#scripts/issue/issue-cite'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { error_text } from '#scripts/lib/error-message'
 import { git_command } from './git-command'
 import { main_merge_guard } from './main-merge-guard'
 
-// `josh main:merge` (`josh mm`) — bring the default branch into the branch this checkout is on
-// (joshuafolkken/kit#1659).
+// `josh main:merge` (`josh mm`) — bring the default branch into the branch this checkout is on.
 //
 // **It stopped being a `git pull` because `git pull` cannot decide anything on a diverged branch.**
 // With neither `pull.rebase` nor `pull.ff` set — the state of a checkout nobody has configured — git
@@ -21,7 +21,7 @@ import { main_merge_guard } from './main-merge-guard'
 //
 // The strategy is therefore named by this file rather than read out of whoever's git configuration
 // happens to be in force: **fetch, then merge `origin/<default>` into the current branch.** Merging
-// rather than rebasing is joshuafolkken/kit#1446's decision and not a fresh one — a rebase rewrites
+// rather than rebasing because a rebase rewrites
 // commits that are already pushed, so it needs a force push, which `.claude/settings.json` denies.
 //
 // `git_command.merge_fast_forward` is deliberately not reused: it passes `--ff-only`, which fails
@@ -33,7 +33,7 @@ const ARGV_OFFSET = 2
 const COMMAND_NAME = 'main:merge'
 
 // git's default merge message carries no `#N`, so on an issue branch the `commit-msg` hook refuses
-// it and leaves the index mid-merge (joshuafolkken/kit#2439). The number is read with the hook's
+// it and leaves the index mid-merge. The number is read with the hook's
 // own parser, so the message this writes is exactly the one that hook accepts; a branch without a
 // number keeps git's default.
 function merge_message(default_branch: string, current_branch: string): string | undefined {
@@ -41,10 +41,10 @@ function merge_message(default_branch: string, current_branch: string): string |
 
 	if (issue_number === undefined) return undefined
 
-	return `Merge ${default_branch} into ${current_branch} #${issue_number}`
+	return `Merge ${default_branch} into ${current_branch} ${issue_cite.plain(issue_number)}`
 }
 
-// What one merge of the default branch came to (joshuafolkken/kit#3221). `josh ship` merges it again
+// What one merge of the default branch came to. `josh ship` merges it again
 // before the commit and on a conflicting pull request, and branches on the answer rather than on an
 // exit code: `current` brought nothing in, so the tree is unchanged; `merged` changed it; `refused`
 // is the guard's answer, nothing attempted; `conflict` names the paths git left unmerged, so a resumed
@@ -81,7 +81,7 @@ async function merge_into(target: MergeTarget): Promise<MergeOutcome> {
 
 // The fetch is what makes `origin/<default>` current before the merge reads it. `git pull` did the
 // two together, which is the only thing it was doing here that is worth keeping. The refusal is read
-// after the fetch, so the incoming paths are the ones the merge would bring in (joshuafolkken/kit#2445).
+// after the fetch, so the incoming paths are the ones the merge would bring in.
 async function merge(): Promise<MergeOutcome> {
 	const default_branch = await git_command.get_default_branch()
 	const current_branch = await git_command.branch()