@joshuafolkken/kit 1.947.0 → 1.953.0

package/README.md

@@ -1,6 +1,6 @@
 # @joshuafolkken/kit
 
-A development toolkit that sets up a repository for AI-assisted work with one command. `josh init` gives an AI assistant (Claude Code, Codex, Gemini, Cursor) the project's rules, and the `josh` CLI runs the checks and the Git / GitHub Issue workflow the same way in every project. You stop copying config between repositories and re-explaining conventions to the assistant.
+A development toolkit that sets up a repository for AI-assisted work with one command. `josh init` gives an AI assistant (Claude Code, Codex, Gemini, Cursor) the project's rules, and the `josh` CLI runs the checks and the Git / GitHub Issue workflow the same way in every project. You stop copying config between repositories and re-explaining conventions to the assistant. For the problems kit exists to solve, see [why.md](./docs/why.md) (Japanese).
 
 ## What your project gets
 
@@ -34,11 +34,8 @@ It needs [Node.js](https://nodejs.org/) 22.19.0 or later with [pnpm](https://pnp
 
 - [getting-started.md](./docs/getting-started.md) — first install for an `index.html` site or a non-Node project (`static`)
 - [package.md](./docs/package.md) — add kit to a Node project (`node`)
+- [tutorial.md](./docs/tutorial.md) — your first change with an agent, from Issue to merge
 - [how-to.md](./docs/how-to.md) — step-by-step guides by task: update, release, run Issues, fix a failing gate
-
-**Understand kit**
-
-- [why.md](./docs/why.md) — the problems kit exists to solve
 - [overview.md](./docs/overview.md) — what kit sets up and how it works
 
 **Commands and configuration**

package/dist/hooks/{chunk-3FWV6CFC.js → chunk-452OKRQX.js}

@@ -1906,8 +1906,8 @@ function current_owner(repository_path = process.cwd()) {
 var repo_party = { FIRST_PARTY, THIRD_PARTY, UNKNOWN, classify: classify3, current_owner, target_owner };
 
 // scripts/lane/lane-registry.ts
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
-import path2 from "node:path";
+import { existsSync as existsSync2, readFileSync as readFileSync4 } from "node:fs";
+import path3 from "node:path";
 
 // scripts/git/git-ls-remote.ts
 var LS_REMOTE_COMMAND = "ls-remote";
@@ -1918,23 +1918,323 @@ function ls_remote_branch_arguments(branch_name) {
   return [LS_REMOTE_COMMAND, HEADS_FLAG, ORIGIN_REMOTE, `${HEADS_REF_PREFIX}${branch_name}`];
 }
 
+// scripts/git/repository-lock.ts
+import { randomUUID as randomUUID2 } from "node:crypto";
+import { linkSync, renameSync, rmSync as rmSync2 } from "node:fs";
+import { setTimeout as sleep } from "node:timers/promises";
+
+// scripts/josh/process-identity.ts
+import { execFileSync as execFileSync2, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFileSync as readFileSync3, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import path2 from "node:path";
+var PS_COMMAND = "/bin/ps";
+var FORMAT_FLAG = "-o";
+var START_TIME_FORMAT = "lstart=";
+var PID_FLAG = "-p";
+var PROBE_ENVIRONMENT = { TZ: "UTC", LC_ALL: "C" };
+var PROBE_TIMEOUT_MS = 2e3;
+var LIVENESS_SIGNAL = 0;
+var LOWEST_REAL_PID = 1;
+var PROC_START_FIELD_INDEX = 19;
+var BEACON_SCHEME = "socket:";
+var BEACON_SUFFIX = ".sock";
+var BEACON_PREFIX = `josh-process-identity-${String(process.getuid?.() ?? "")}-`;
+var BEACON_ID_LENGTH = 36;
+var BEACON_ID_PATTERN = /^[\da-f-]+$/u;
+var WINDOWS_PLATFORM = "win32";
+var SOCKET_PROBE_SOURCE = "const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(0));socket.once('error',()=>process.exit(1));socket.setTimeout(1000,()=>process.exit(1));";
+var beacons = /* @__PURE__ */ new Map();
+var exit_cleanup = { is_registered: false };
+function is_live_pid(pid) {
+  if (pid < LOWEST_REAL_PID) return false;
+  try {
+    process.kill(pid, LIVENESS_SIGNAL);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function read_proc_start(pid) {
+  try {
+    const stat = readFileSync3(`/proc/${String(pid)}/stat`, "utf8");
+    const fields = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/u);
+    const start = fields[PROC_START_FIELD_INDEX];
+    return start === void 0 ? void 0 : `proc:${start}`;
+  } catch {
+    return void 0;
+  }
+}
+function read_ps_start(pid) {
+  try {
+    const printed = execFileSync2(
+      PS_COMMAND,
+      [FORMAT_FLAG, START_TIME_FORMAT, PID_FLAG, String(pid)],
+      {
+        encoding: "utf8",
+        timeout: PROBE_TIMEOUT_MS,
+        stdio: ["ignore", "pipe", "ignore"],
+        env: PROBE_ENVIRONMENT
+      }
+    ).trim();
+    return printed.length > 0 ? printed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var START_PROBES = { read_proc_start, read_ps_start };
+function safe_probe(probe, pid) {
+  try {
+    return probe(pid);
+  } catch {
+    return void 0;
+  }
+}
+function read_start(pid, probes = START_PROBES) {
+  return safe_probe(probes.read_proc_start, pid) ?? safe_probe(probes.read_ps_start, pid);
+}
+function close_beacon(token) {
+  const server = beacons.get(token);
+  if (server === void 0) return;
+  beacons.delete(token);
+  server.close();
+  rmSync(token.slice(BEACON_SCHEME.length), { force: true });
+}
+function close_beacons() {
+  for (const token of beacons.keys()) close_beacon(token);
+}
+function ensure_exit_cleanup() {
+  if (exit_cleanup.is_registered) return;
+  exit_cleanup.is_registered = true;
+  process.once("exit", close_beacons);
+}
+function ignore_beacon_error() {
+}
+function bind_beacon(target) {
+  return createServer().on("error", ignore_beacon_error).listen(target);
+}
+function try_bind_beacon(bind, target) {
+  try {
+    const server = bind(target);
+    return server.listening ? server : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function open_beacon(bind = bind_beacon) {
+  const target = path2.join(PLATFORM_TEMP_ROOT, `${BEACON_PREFIX}${randomUUID()}${BEACON_SUFFIX}`);
+  const token = `${BEACON_SCHEME}${target}`;
+  const server = try_bind_beacon(bind, target);
+  if (server === void 0) return void 0;
+  server.unref();
+  beacons.set(token, server);
+  ensure_exit_cleanup();
+  return token;
+}
+function resolve_own_start(probes = START_PROBES, platform2 = process.platform) {
+  const start = read_start(process.pid, probes);
+  if (start !== void 0 || platform2 === WINDOWS_PLATFORM) return start;
+  return open_beacon();
+}
+function is_valid_beacon_name(name) {
+  if (!name.startsWith(BEACON_PREFIX) || !name.endsWith(BEACON_SUFFIX)) return false;
+  const id = name.slice(BEACON_PREFIX.length, -BEACON_SUFFIX.length);
+  return id.length === BEACON_ID_LENGTH && BEACON_ID_PATTERN.test(id);
+}
+function beacon_target(token) {
+  if (!token.startsWith(BEACON_SCHEME)) return void 0;
+  const target = token.slice(BEACON_SCHEME.length);
+  if (path2.dirname(target) !== PLATFORM_TEMP_ROOT) return void 0;
+  return is_valid_beacon_name(path2.basename(target)) ? target : void 0;
+}
+function is_live_beacon(target) {
+  return spawnSync(process.execPath, ["-e", SOCKET_PROBE_SOURCE, target], {
+    stdio: "ignore",
+    timeout: PROBE_TIMEOUT_MS
+  }).status === 0;
+}
+function has_matching_start(pid, recorded_start, read2) {
+  const observed = read2(pid);
+  return observed === void 0 ? void 0 : observed === recorded_start;
+}
+function matches_recorded_start(pid, recorded_start, read2) {
+  const target = beacon_target(recorded_start);
+  return target === void 0 ? has_matching_start(pid, recorded_start, read2) : is_live_beacon(target);
+}
+var own_probe = /* @__PURE__ */ new Map();
+function own_start() {
+  if (!own_probe.has(process.pid)) own_probe.set(process.pid, resolve_own_start());
+  return own_probe.get(process.pid);
+}
+function own_fields() {
+  const start = own_start();
+  return { pid: process.pid, ...start !== void 0 && { process_start: start } };
+}
+function is_same_process(pid, recorded_start, read2 = read_start) {
+  if (pid === void 0 || !is_live_pid(pid)) return false;
+  if (recorded_start === void 0) return void 0;
+  return matches_recorded_start(pid, recorded_start, read2);
+}
+function is_own_process(pid, recorded_start) {
+  return pid === process.pid && recorded_start === own_start();
+}
+var process_identity = {
+  close_beacon,
+  is_live_pid,
+  is_own_process,
+  is_same_process,
+  open_beacon,
+  own_fields,
+  own_start,
+  read_start,
+  resolve_own_start
+};
+
+// scripts/git/git-common-directory.ts
+import { execFileSync as execFileSync3 } from "node:child_process";
+var OWN_GIT_DIRECTORY = 0;
+var COMMON_GIT_DIRECTORY = 1;
+var PROBE_TIMEOUT_MS2 = 2e3;
+function read_directories(cwd) {
+  const git = git_utilities.get_git_command_for_spawn();
+  const output = execFileSync3(git, [...git_command.GIT_DIRECTORY_ARGUMENTS], {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    timeout: PROBE_TIMEOUT_MS2
+  });
+  return output.trim().split("\n");
+}
+function select_linked(directories) {
+  const own = directories[OWN_GIT_DIRECTORY];
+  const common = directories[COMMON_GIT_DIRECTORY];
+  return own !== void 0 && common !== void 0 && own !== common ? common : void 0;
+}
+function resolve2(cwd) {
+  try {
+    return select_linked(read_directories(cwd));
+  } catch {
+    return void 0;
+  }
+}
+function repository(cwd) {
+  try {
+    return read_directories(cwd)[COMMON_GIT_DIRECTORY];
+  } catch {
+    return void 0;
+  }
+}
+var git_common_directory = { repository, resolve: resolve2, select_linked };
+
+// scripts/git/repository-lock.ts
+var POLL_INTERVAL_MS = 200;
+function lock_path(prefix, cwd = process.cwd()) {
+  return stamp_file.stamp_path(prefix, git_common_directory.repository(cwd) ?? cwd);
+}
+function parse_owner(raw) {
+  if (raw === void 0) return void 0;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+function read_owner(target) {
+  return parse_owner(stamp_file.read_stamp_text(target));
+}
+function is_owner_gone(owner) {
+  return process_identity.is_same_process(owner.pid, owner.process_start) === false;
+}
+function restore(aside, target) {
+  try {
+    linkSync(aside, target);
+  } catch {
+  }
+}
+function stale_record(target, is_gone2) {
+  const raw = stamp_file.read_stamp_text(target);
+  const owner = parse_owner(raw);
+  return owner !== void 0 && is_gone2(owner) ? raw : void 0;
+}
+function move_aside(target) {
+  const aside = `${target}.${String(process.pid)}.${randomUUID2()}`;
+  try {
+    renameSync(target, aside);
+    return aside;
+  } catch {
+    return void 0;
+  }
+}
+function clear_stale(target, is_gone2 = is_owner_gone) {
+  const raw = stale_record(target, is_gone2);
+  if (raw === void 0) return;
+  const aside = move_aside(target);
+  if (aside === void 0) return;
+  if (stamp_file.read_stamp_text(aside) !== raw) restore(aside, target);
+  rmSync2(aside, { force: true });
+}
+function claim(target) {
+  clear_stale(target);
+  return stamp_file.create_stamp(target, process_identity.own_fields());
+}
+function release(target) {
+  const owner = read_owner(target);
+  if (owner !== void 0 && process_identity.is_own_process(owner.pid, owner.process_start)) {
+    stamp_file.remove_stamp(target);
+  }
+}
+async function acquire(target, max_wait_ms) {
+  const deadline = Date.now() + max_wait_ms;
+  while (!claim(target)) {
+    if (Date.now() >= deadline) return false;
+    await sleep(POLL_INTERVAL_MS);
+  }
+  return true;
+}
+async function with_lock(work, target, max_wait_ms) {
+  if (!await acquire(target, max_wait_ms)) return void 0;
+  try {
+    return await work();
+  } finally {
+    release(target);
+  }
+}
+var repository_lock = { clear_stale, lock_path, with_lock };
+
 // scripts/git/git-worktree.ts
 var WORKTREE = "worktree";
+var WORKTREE_LOCK_PREFIX = "josh-worktree-lock-";
+var WORKTREE_LOCK_MAX_WAIT_MS = 12e4;
+async function locked(arguments_) {
+  const target = repository_lock.lock_path(WORKTREE_LOCK_PREFIX);
+  const output = await repository_lock.with_lock(
+    async () => await git_spawn.read(arguments_),
+    target,
+    WORKTREE_LOCK_MAX_WAIT_MS
+  );
+  if (output === void 0) {
+    throw new Error(
+      `git ${arguments_.join(" ")}: timed out waiting for the work-tree lock ${target}`
+    );
+  }
+  return output;
+}
 async function worktree_list() {
   return await git_spawn.read([WORKTREE, "list", PORCELAIN_FLAG]);
 }
 async function worktree_add(directory, branch_name, start_point) {
   const flags = start_point === void 0 ? ["add"] : ["add", "--no-track", "-b", branch_name];
-  return await git_spawn.read([WORKTREE, ...flags, directory, start_point ?? branch_name]);
+  return await locked([WORKTREE, ...flags, directory, start_point ?? branch_name]);
 }
 async function worktree_add_detached(directory, commit2) {
-  return await git_spawn.read([WORKTREE, "add", "--detach", directory, commit2]);
+  return await locked([WORKTREE, "add", "--detach", directory, commit2]);
 }
 async function worktree_remove(directory) {
-  return await git_spawn.read([WORKTREE, "remove", "--force", directory]);
+  return await locked([WORKTREE, "remove", "--force", directory]);
 }
 async function worktree_prune() {
-  return await git_spawn.read([WORKTREE, "prune"]);
+  return await locked([WORKTREE, "prune"]);
 }
 async function ls_remote_branch(branch_name) {
   return await git_spawn.read(ls_remote_branch_arguments(branch_name));
@@ -2097,7 +2397,7 @@ function held_seat(content) {
 }
 function read_environment(directory) {
   try {
-    return readFileSync3(path2.join(directory, ENV_FILE_NAME), "utf8");
+    return readFileSync4(path3.join(directory, ENV_FILE_NAME), "utf8");
   } catch {
     return void 0;
   }
@@ -2463,174 +2763,6 @@ var run_invocation = {
   rebuild
 };
 
-// scripts/josh/process-identity.ts
-import { execFileSync as execFileSync2, spawnSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { readFileSync as readFileSync4, rmSync } from "node:fs";
-import { createServer } from "node:net";
-import path3 from "node:path";
-var PS_COMMAND = "/bin/ps";
-var FORMAT_FLAG = "-o";
-var START_TIME_FORMAT = "lstart=";
-var PID_FLAG = "-p";
-var PROBE_ENVIRONMENT = { TZ: "UTC", LC_ALL: "C" };
-var PROBE_TIMEOUT_MS = 2e3;
-var LIVENESS_SIGNAL = 0;
-var LOWEST_REAL_PID = 1;
-var PROC_START_FIELD_INDEX = 19;
-var BEACON_SCHEME = "socket:";
-var BEACON_SUFFIX = ".sock";
-var BEACON_PREFIX = `josh-process-identity-${String(process.getuid?.() ?? "")}-`;
-var BEACON_ID_LENGTH = 36;
-var BEACON_ID_PATTERN = /^[\da-f-]+$/u;
-var WINDOWS_PLATFORM = "win32";
-var SOCKET_PROBE_SOURCE = "const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(0));socket.once('error',()=>process.exit(1));socket.setTimeout(1000,()=>process.exit(1));";
-var beacons = /* @__PURE__ */ new Map();
-var exit_cleanup = { is_registered: false };
-function is_live_pid(pid) {
-  if (pid < LOWEST_REAL_PID) return false;
-  try {
-    process.kill(pid, LIVENESS_SIGNAL);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function read_proc_start(pid) {
-  try {
-    const stat = readFileSync4(`/proc/${String(pid)}/stat`, "utf8");
-    const fields = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/u);
-    const start = fields[PROC_START_FIELD_INDEX];
-    return start === void 0 ? void 0 : `proc:${start}`;
-  } catch {
-    return void 0;
-  }
-}
-function read_ps_start(pid) {
-  try {
-    const printed = execFileSync2(
-      PS_COMMAND,
-      [FORMAT_FLAG, START_TIME_FORMAT, PID_FLAG, String(pid)],
-      {
-        encoding: "utf8",
-        timeout: PROBE_TIMEOUT_MS,
-        stdio: ["ignore", "pipe", "ignore"],
-        env: PROBE_ENVIRONMENT
-      }
-    ).trim();
-    return printed.length > 0 ? printed : void 0;
-  } catch {
-    return void 0;
-  }
-}
-var START_PROBES = { read_proc_start, read_ps_start };
-function safe_probe(probe, pid) {
-  try {
-    return probe(pid);
-  } catch {
-    return void 0;
-  }
-}
-function read_start(pid, probes = START_PROBES) {
-  return safe_probe(probes.read_proc_start, pid) ?? safe_probe(probes.read_ps_start, pid);
-}
-function close_beacon(token) {
-  const server = beacons.get(token);
-  if (server === void 0) return;
-  beacons.delete(token);
-  server.close();
-  rmSync(token.slice(BEACON_SCHEME.length), { force: true });
-}
-function close_beacons() {
-  for (const token of beacons.keys()) close_beacon(token);
-}
-function ensure_exit_cleanup() {
-  if (exit_cleanup.is_registered) return;
-  exit_cleanup.is_registered = true;
-  process.once("exit", close_beacons);
-}
-function ignore_beacon_error() {
-}
-function bind_beacon(target) {
-  return createServer().on("error", ignore_beacon_error).listen(target);
-}
-function try_bind_beacon(bind, target) {
-  try {
-    const server = bind(target);
-    return server.listening ? server : void 0;
-  } catch {
-    return void 0;
-  }
-}
-function open_beacon(bind = bind_beacon) {
-  const target = path3.join(PLATFORM_TEMP_ROOT, `${BEACON_PREFIX}${randomUUID()}${BEACON_SUFFIX}`);
-  const token = `${BEACON_SCHEME}${target}`;
-  const server = try_bind_beacon(bind, target);
-  if (server === void 0) return void 0;
-  server.unref();
-  beacons.set(token, server);
-  ensure_exit_cleanup();
-  return token;
-}
-function resolve_own_start(probes = START_PROBES, platform2 = process.platform) {
-  const start = read_start(process.pid, probes);
-  if (start !== void 0 || platform2 === WINDOWS_PLATFORM) return start;
-  return open_beacon();
-}
-function is_valid_beacon_name(name) {
-  if (!name.startsWith(BEACON_PREFIX) || !name.endsWith(BEACON_SUFFIX)) return false;
-  const id = name.slice(BEACON_PREFIX.length, -BEACON_SUFFIX.length);
-  return id.length === BEACON_ID_LENGTH && BEACON_ID_PATTERN.test(id);
-}
-function beacon_target(token) {
-  if (!token.startsWith(BEACON_SCHEME)) return void 0;
-  const target = token.slice(BEACON_SCHEME.length);
-  if (path3.dirname(target) !== PLATFORM_TEMP_ROOT) return void 0;
-  return is_valid_beacon_name(path3.basename(target)) ? target : void 0;
-}
-function is_live_beacon(target) {
-  return spawnSync(process.execPath, ["-e", SOCKET_PROBE_SOURCE, target], {
-    stdio: "ignore",
-    timeout: PROBE_TIMEOUT_MS
-  }).status === 0;
-}
-function has_matching_start(pid, recorded_start, read2) {
-  const observed = read2(pid);
-  return observed === void 0 ? void 0 : observed === recorded_start;
-}
-function matches_recorded_start(pid, recorded_start, read2) {
-  const target = beacon_target(recorded_start);
-  return target === void 0 ? has_matching_start(pid, recorded_start, read2) : is_live_beacon(target);
-}
-var own_probe = /* @__PURE__ */ new Map();
-function own_start() {
-  if (!own_probe.has(process.pid)) own_probe.set(process.pid, resolve_own_start());
-  return own_probe.get(process.pid);
-}
-function own_fields() {
-  const start = own_start();
-  return { pid: process.pid, ...start !== void 0 && { process_start: start } };
-}
-function is_same_process(pid, recorded_start, read2 = read_start) {
-  if (pid === void 0 || !is_live_pid(pid)) return false;
-  if (recorded_start === void 0) return void 0;
-  return matches_recorded_start(pid, recorded_start, read2);
-}
-function is_own_process(pid, recorded_start) {
-  return pid === process.pid && recorded_start === own_start();
-}
-var process_identity = {
-  close_beacon,
-  is_live_pid,
-  is_own_process,
-  is_same_process,
-  open_beacon,
-  own_fields,
-  own_start,
-  read_start,
-  resolve_own_start
-};
-
 // scripts/run/run-carry.ts
 import { z as z5 } from "zod";
 
@@ -3404,8 +3536,8 @@ export {
   gh_failure,
   has_stderr_field,
   git_gh_exec,
-  lane_registry,
   process_identity,
+  lane_registry,
   run_invocation,
   run_carry,
   run_watcher_guard

package/dist/hooks/{chunk-GIX5SAAB.js → chunk-Z5TVZ4AP.js}

@@ -35,7 +35,7 @@ import {
   run_watcher_guard,
   shell_segments,
   tail_commands
-} from "./chunk-3FWV6CFC.js";
+} from "./chunk-452OKRQX.js";
 import {
   find_local_bin_upwards
 } from "./chunk-3V37IID6.js";

package/dist/hooks/codex-hook-adapter.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env tsx
 import {
   pretool_guard
-} from "./chunk-GIX5SAAB.js";
-import "./chunk-3FWV6CFC.js";
+} from "./chunk-Z5TVZ4AP.js";
+import "./chunk-452OKRQX.js";
 import {
   build_envelope,
   compose_context,

package/dist/hooks/pretool-guard.js

@@ -3,8 +3,8 @@ import {
   pretool_guard,
   pretool_outcome,
   pretool_outcome_async
-} from "./chunk-GIX5SAAB.js";
-import "./chunk-3FWV6CFC.js";
+} from "./chunk-Z5TVZ4AP.js";
+import "./chunk-452OKRQX.js";
 import "./chunk-3V37IID6.js";
 import "./chunk-V7RH56HU.js";
 import "./chunk-NKVLBB65.js";

package/dist/hooks/stop-guard.js

@@ -16,7 +16,7 @@ import {
   run_hold,
   run_invocation,
   run_watcher_guard
-} from "./chunk-3FWV6CFC.js";
+} from "./chunk-452OKRQX.js";
 import {
   session_language
 } from "./chunk-6V5OPIUU.js";

package/dist/version/index.js

@@ -163,9 +163,12 @@ var NO_QUARANTINE_MINUTES = 0;
 var NPMRC_PATH = ".npmrc";
 var release_times_schema = z2.record(z2.string(), z2.string());
 var MS_PER_MINUTE = 6e4;
-function parse_minimum_release_age(npmrc_content) {
+function parse_declared_minimum_release_age(npmrc_content) {
   const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1];
-  return raw === void 0 ? NO_QUARANTINE_MINUTES : Number(raw);
+  return raw === void 0 ? void 0 : Number(raw);
+}
+function parse_minimum_release_age(npmrc_content) {
+  return parse_declared_minimum_release_age(npmrc_content) ?? NO_QUARANTINE_MINUTES;
 }
 function is_on_major(version, major) {
   return major === void 0 || String(semver.major(version)) === major;
@@ -184,8 +187,7 @@ function select_aged_version(times, major, minimum_age_minutes, now_ms) {
 }
 function read_declared_minimum_release_age(npmrc_path) {
   try {
-    const raw = MINIMUM_RELEASE_AGE_RE.exec(readFileSync2(npmrc_path, "utf8"))?.[1];
-    return raw === void 0 ? void 0 : Number(raw);
+    return parse_declared_minimum_release_age(readFileSync2(npmrc_path, "utf8"));
   } catch {
     return void 0;
   }
@@ -206,6 +208,7 @@ function read_nearest_minimum_release_age(start, boundary) {
 var release_age = {
   release_times_schema,
   parse_minimum_release_age,
+  parse_declared_minimum_release_age,
   read_minimum_release_age,
   read_nearest_minimum_release_age,
   select_aged_version

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.947.0",
+  "version": "1.953.0",
   "name": "@joshuafolkken/kit",
   "description": "Development toolkit for AI-assisted projects: formatting, AI assistant rules and a Git/GitHub Issue workflow for any repository, plus lint, type check, tests and hooks for Node projects",
   "keywords": [

package/scripts/git/git-worktree.ts

@@ -1,6 +1,7 @@
 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
@@ -19,6 +20,36 @@ import { git_spawn } from './git-spawn'
 // (joshuafolkken/kit#1641; before it, `lane-start-point.ts` was the only reader and did both).
 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
+// 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
+// `lane-open.ts` does not serialize them. `remove` and `prune` edit the same directory, so they take
+// the same lock. The lock wraps the git call alone; the slow steps a caller runs afterwards — a lane's
+// dependency install — stay outside it.
+const WORKTREE_LOCK_PREFIX = 'josh-worktree-lock-'
+// A holder runs one local git command, so the wait only bounds a checkout that hung; it is generous
+// 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> {
+	const target = repository_lock.lock_path(WORKTREE_LOCK_PREFIX)
+	const output = await repository_lock.with_lock(
+		async () => await git_spawn.read(arguments_),
+		target,
+		WORKTREE_LOCK_MAX_WAIT_MS,
+	)
+
+	if (output === undefined) {
+		throw new Error(
+			`git ${arguments_.join(' ')}: timed out waiting for the work-tree lock ${target}`,
+		)
+	}
+
+	return output
+}
+
 // Every registered work tree of this repository, in git's own machine-readable form: one `worktree
 // <path>` / `HEAD <sha>` / `branch <ref>` block per tree, blocks separated by a blank line. Parsing
 // it is the caller's, so this module keeps one shape for every reader.
@@ -50,14 +81,14 @@ async function worktree_add(
 ): Promise<string> {
 	const flags = start_point === undefined ? ['add'] : ['add', '--no-track', '-b', branch_name]
 
-	return await git_spawn.read([WORKTREE, ...flags, directory, start_point ?? branch_name])
+	return await locked([WORKTREE, ...flags, directory, start_point ?? branch_name])
 }
 
 // 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).
 async function worktree_add_detached(directory: string, commit: string): Promise<string> {
-	return await git_spawn.read([WORKTREE, 'add', '--detach', directory, commit])
+	return await locked([WORKTREE, 'add', '--detach', directory, commit])
 }
 
 // **`--force` is the point, not a convenience.** A lane is closed after a park, a failure or an
@@ -65,13 +96,13 @@ async function worktree_add_detached(directory: string, commit: string): Promise
 // or untracked work. Refusing to remove it there would leave exactly the debris the close exists to
 // prevent.
 async function worktree_remove(directory: string): Promise<string> {
-	return await git_spawn.read([WORKTREE, 'remove', '--force', directory])
+	return await locked([WORKTREE, 'remove', '--force', directory])
 }
 
 // Drops the registrations whose directories are already gone — what makes a lane whose directory was
 // deleted by hand recoverable rather than a permanent `worktree add` refusal on that path.
 async function worktree_prune(): Promise<string> {
-	return await git_spawn.read([WORKTREE, 'prune'])
+	return await locked([WORKTREE, 'prune'])
 }
 
 // **Asked of the remote itself, because nothing prunes the remote-tracking refs**

package/scripts/git/repository-lock.ts

@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto'
+import { linkSync, renameSync, rmSync } from 'node:fs'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { git_common_directory } from './git-common-directory'
+
+// One holder at a time per repository, for work that every work tree of that repository shares
+// (joshuafolkken/kit#2701 for the stash sweep, joshuafolkken/kit#2736 for `git worktree add`). The
+// record is keyed on the git common directory, so every work tree of one repository contends for one
+// record per lock name, and it lives in the platform temp root beside the other stamps rather than
+// inside `.git`. Each caller names its own lock with a prefix, so two unrelated kinds of work never
+// wait on each other.
+
+const POLL_INTERVAL_MS = 200
+
+interface LockOwner {
+	pid: number
+	process_start?: string
+}
+
+type IsGone = (owner: LockOwner) => boolean
+
+function lock_path(prefix: string, cwd: string = process.cwd()): string {
+	return stamp_file.stamp_path(prefix, git_common_directory.repository(cwd) ?? cwd)
+}
+
+function parse_owner(raw: string | undefined): LockOwner | undefined {
+	if (raw === undefined) return undefined
+
+	try {
+		return JSON.parse(raw) as LockOwner
+	} catch {
+		return undefined
+	}
+}
+
+function read_owner(target: string): LockOwner | undefined {
+	return parse_owner(stamp_file.read_stamp_text(target))
+}
+
+function is_owner_gone(owner: LockOwner): boolean {
+	return process_identity.is_same_process(owner.pid, owner.process_start) === false
+}
+
+// Put back a record that turned out not to be the stale one. `linkSync` refuses an existing path, so
+// a lock someone claimed in the meantime is never overwritten.
+function restore(aside: string, target: string): void {
+	try {
+		linkSync(aside, target)
+	} catch {
+		// Another claim already holds the path; the record set aside is dropped below.
+	}
+}
+
+// The record's text when its owner is certainly gone, else `undefined`.
+function stale_record(target: string, is_gone: IsGone): string | undefined {
+	const raw = stamp_file.read_stamp_text(target)
+	const owner = parse_owner(raw)
+
+	return owner !== undefined && is_gone(owner) ? raw : undefined
+}
+
+// The path the record was moved to, or `undefined` when another claimant moved it first.
+function move_aside(target: string): string | undefined {
+	const aside = `${target}.${String(process.pid)}.${randomUUID()}`
+
+	try {
+		renameSync(target, aside)
+
+		return aside
+	} catch {
+		return undefined
+	}
+}
+
+// A record whose process is certainly gone is a crashed holder's, and is cleared before the claim; an
+// unreadable record or an uncertain answer is left in place, since clearing a live holder's lock is the
+// very race the lock exists to close. **The clear is a rename, then a compare**: two claimants can
+// both judge the same record stale, and the slower one's plain remove would delete the lock the faster
+// one had just claimed. Renaming moves exactly one file aside atomically, and only a record
+// byte-identical to the one judged stale is discarded — any other is a fresh claim and goes back.
+function clear_stale(target: string, is_gone: IsGone = is_owner_gone): void {
+	const raw = stale_record(target, is_gone)
+
+	if (raw === undefined) return
+
+	const aside = move_aside(target)
+
+	if (aside === undefined) return
+	if (stamp_file.read_stamp_text(aside) !== raw) restore(aside, target)
+	rmSync(aside, { force: true })
+}
+
+function claim(target: string): boolean {
+	clear_stale(target)
+
+	return stamp_file.create_stamp(target, process_identity.own_fields())
+}
+
+function release(target: string): void {
+	const owner = read_owner(target)
+
+	if (owner !== undefined && process_identity.is_own_process(owner.pid, owner.process_start)) {
+		stamp_file.remove_stamp(target)
+	}
+}
+
+async function acquire(target: string, max_wait_ms: number): Promise<boolean> {
+	const deadline = Date.now() + max_wait_ms
+
+	while (!claim(target)) {
+		if (Date.now() >= deadline) return false
+		await sleep(POLL_INTERVAL_MS)
+	}
+
+	return true
+}
+
+// Runs `work` holding the lock at `target` and answers its result, or `undefined` without running it
+// when another holder kept the lock for the whole wait.
+async function with_lock<T>(
+	work: () => Promise<T>,
+	target: string,
+	max_wait_ms: number,
+): Promise<T | undefined> {
+	if (!(await acquire(target, max_wait_ms))) return undefined
+
+	try {
+		return await work()
+	} finally {
+		release(target)
+	}
+}
+
+const repository_lock = { clear_stale, lock_path, with_lock }
+
+export { repository_lock }

package/scripts/git/stash-sweep-lock.ts

@@ -1,123 +1,18 @@
-import { randomUUID } from 'node:crypto'
-import { linkSync, renameSync, rmSync } from 'node:fs'
-import { setTimeout as sleep } from 'node:timers/promises'
-import { process_identity } from '#scripts/josh/process-identity'
-import { stamp_file } from '#scripts/josh/stamp-file'
-import { git_common_directory } from './git-common-directory'
+import { repository_lock } from './repository-lock'
 
 // One stash sweep at a time per repository (joshuafolkken/kit#2701). The stash is a single stack every
 // work tree shares, and a `backlogrun` runs one sweep per lane seat at once: two sweeps that each
 // resolve the same entry to `stash@{n}` and drop it would have the second drop land on whichever entry
-// moved into that position, and two that carry the same ledger lines would both append them. The lock
-// is keyed on the git common directory, so every work tree of one repository contends for one record.
+// moved into that position, and two that carry the same ledger lines would both append them. The
+// locking itself is `repository-lock.ts`, shared with the work-tree writes (joshuafolkken/kit#2736).
 
 const LOCK_PREFIX = 'josh-stash-sweep-lock-'
 // The locked phase is local git and one file append per entry, so a holder finishes in well under the
 // wait; the cap only bounds a holder that hung, and a sweep that gives up keeps its entries.
-const POLL_INTERVAL_MS = 200
 const MAX_WAIT_MS = 30_000
 
-interface LockOwner {
-	pid: number
-	process_start?: string
-}
-
 function lock_path(cwd: string = process.cwd()): string {
-	return stamp_file.stamp_path(LOCK_PREFIX, git_common_directory.repository(cwd) ?? cwd)
-}
-
-type IsGone = (owner: LockOwner) => boolean
-
-function parse_owner(raw: string | undefined): LockOwner | undefined {
-	if (raw === undefined) return undefined
-
-	try {
-		return JSON.parse(raw) as LockOwner
-	} catch {
-		return undefined
-	}
-}
-
-function read_owner(target: string): LockOwner | undefined {
-	return parse_owner(stamp_file.read_stamp_text(target))
-}
-
-function is_owner_gone(owner: LockOwner): boolean {
-	return process_identity.is_same_process(owner.pid, owner.process_start) === false
-}
-
-// Put back a record that turned out not to be the stale one. `linkSync` refuses an existing path, so
-// a lock someone claimed in the meantime is never overwritten.
-function restore(aside: string, target: string): void {
-	try {
-		linkSync(aside, target)
-	} catch {
-		// Another claim already holds the path; the record set aside is dropped below.
-	}
-}
-
-// The record's text when its owner is certainly gone, else `undefined`.
-function stale_record(target: string, is_gone: IsGone): string | undefined {
-	const raw = stamp_file.read_stamp_text(target)
-	const owner = parse_owner(raw)
-
-	return owner !== undefined && is_gone(owner) ? raw : undefined
-}
-
-// The path the record was moved to, or `undefined` when another sweep moved it first.
-function move_aside(target: string): string | undefined {
-	const aside = `${target}.${String(process.pid)}.${randomUUID()}`
-
-	try {
-		renameSync(target, aside)
-
-		return aside
-	} catch {
-		return undefined
-	}
-}
-
-// A record whose process is certainly gone is a crashed sweep's, and is cleared before the claim; an
-// unreadable record or an uncertain answer is left in place, since clearing a live holder's lock is the
-// very race the lock exists to close. **The clear is a rename, then a compare**: two sweeps can both
-// judge the same record stale, and the slower one's plain remove would delete the lock the faster one
-// had just claimed. Renaming moves exactly one file aside atomically, and only a record byte-identical
-// to the one judged stale is discarded — any other is a fresh claim and goes back.
-function clear_stale(target: string, is_gone: IsGone = is_owner_gone): void {
-	const raw = stale_record(target, is_gone)
-
-	if (raw === undefined) return
-
-	const aside = move_aside(target)
-
-	if (aside === undefined) return
-	if (stamp_file.read_stamp_text(aside) !== raw) restore(aside, target)
-	rmSync(aside, { force: true })
-}
-
-function claim(target: string): boolean {
-	clear_stale(target)
-
-	return stamp_file.create_stamp(target, process_identity.own_fields())
-}
-
-function release(target: string): void {
-	const owner = read_owner(target)
-
-	if (owner !== undefined && process_identity.is_own_process(owner.pid, owner.process_start)) {
-		stamp_file.remove_stamp(target)
-	}
-}
-
-async function acquire(target: string, max_wait_ms: number): Promise<boolean> {
-	const deadline = Date.now() + max_wait_ms
-
-	while (!claim(target)) {
-		if (Date.now() >= deadline) return false
-		await sleep(POLL_INTERVAL_MS)
-	}
-
-	return true
+	return repository_lock.lock_path(LOCK_PREFIX, cwd)
 }
 
 // Runs `work` holding the lock and answers its result, or `undefined` without running it when another
@@ -127,15 +22,9 @@ async function with_lock<T>(
 	target: string = lock_path(),
 	max_wait_ms: number = MAX_WAIT_MS,
 ): Promise<T | undefined> {
-	if (!(await acquire(target, max_wait_ms))) return undefined
-
-	try {
-		return await work()
-	} finally {
-		release(target)
-	}
+	return await repository_lock.with_lock(work, target, max_wait_ms)
 }
 
-const stash_sweep_lock = { clear_stale, lock_path, with_lock }
+const stash_sweep_lock = { clear_stale: repository_lock.clear_stale, lock_path, with_lock }
 
 export { stash_sweep_lock }

package/scripts/safe-chain/project-config.ts

@@ -1,12 +1,16 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
+import { release_age } from '#scripts/version/release-age'
 import { yaml_document } from '#scripts/yaml/yaml-document'
 import { dump } from 'js-yaml'
 import { z } from 'zod'
 
 const WORKSPACE_FILE = 'pnpm-workspace.yaml'
 const PROJECT_CONFIG_FILE = '.aikido'
+const NPMRC_FILE = '.npmrc'
 const EXCLUSIONS_FIELD = 'minimumPackageAgeExclusions'
+const AGE_FIELD = 'minimumPackageAgeHours'
+const MINUTES_PER_HOUR = 60
 const workspace_schema = z.object({ minimumReleaseAgeExclude: z.array(z.string()).optional() })
 
 function read_mapping(value: unknown, label: string): Record<string, unknown> {
@@ -72,27 +76,68 @@ function replace_safe_chain_block(existing: string, safe_chain: Record<string, u
 	return `${prefix}${prefix ? '\n' : ''}${replacement}${suffix}`
 }
 
-function merge_project_config(existing: string, workspace: string): string {
-	const source = workspace_schema.parse(yaml_document.parse_yaml(workspace))
-	const exclusions = source.minimumReleaseAgeExclude ?? []
-	const aikido = yaml_document.parse_yaml(existing)
-	const safe_chain = read_mapping(aikido['safe-chain'], 'safe-chain')
+// Safe Chain enforces its own minimum package age (48 hours by default), so CI refused lockfiles pnpm
+// had resolved under `.npmrc`'s shorter window (kit #2743). `.npmrc` is the source: its minutes are
+// floored to whole hours so Safe Chain is never stricter than pnpm, and an undeclared window writes
+// nothing; an explicit `0` opt-out is written as 0 so an earlier synchronized age cannot outlive it.
+function package_age_hours(npmrc: string): number | undefined {
+	const minutes = release_age.parse_declared_minimum_release_age(npmrc)
+	if (minutes === undefined) return undefined
+
+	return Math.floor(minutes / MINUTES_PER_HOUR)
+}
+
+function merge_age(safe_chain: Record<string, unknown>, npmrc: string): Record<string, unknown> {
+	const hours = package_age_hours(npmrc)
+	if (hours === undefined) return safe_chain
+
+	return { ...safe_chain, [AGE_FIELD]: hours }
+}
+
+function merge_exclusions(
+	safe_chain: Record<string, unknown>,
+	exclusions: ReadonlyArray<string>,
+): Record<string, unknown> {
 	const npm = read_mapping(safe_chain['npm'], 'safe-chain.npm')
-	if (JSON.stringify(npm[EXCLUSIONS_FIELD]) === JSON.stringify(exclusions)) return existing
-	if (exclusions.length === 0 && existing.length === 0) return existing
 
-	const merged = { ...safe_chain, npm: { ...npm, [EXCLUSIONS_FIELD]: exclusions } }
+	return { ...safe_chain, npm: { ...npm, [EXCLUSIONS_FIELD]: exclusions } }
+}
+
+function has_nothing_to_write(
+	existing: string,
+	exclusions: ReadonlyArray<string>,
+	npmrc: string,
+): boolean {
+	return existing.length === 0 && exclusions.length === 0 && package_age_hours(npmrc) === undefined
+}
+
+function read_exclusions(workspace: string): ReadonlyArray<string> {
+	return workspace_schema.parse(yaml_document.parse_yaml(workspace)).minimumReleaseAgeExclude ?? []
+}
+
+function merge_project_config(existing: string, workspace: string, npmrc = ''): string {
+	const exclusions = read_exclusions(workspace)
+	const aikido = yaml_document.parse_yaml(existing)
+	const safe_chain = read_mapping(aikido['safe-chain'], 'safe-chain')
+	const merged = merge_age(merge_exclusions(safe_chain, exclusions), npmrc)
+	if (JSON.stringify(merged) === JSON.stringify(safe_chain)) return existing
+	if (has_nothing_to_write(existing, exclusions, npmrc)) return existing
 
 	return replace_safe_chain_block(existing, merged)
 }
 
+function read_optional(file_path: string): string {
+	return existsSync(file_path) ? readFileSync(file_path, 'utf8') : ''
+}
+
 function sync_project_config(root: string): boolean {
 	const workspace_path = path.join(root, WORKSPACE_FILE)
 	if (!existsSync(workspace_path)) return false
 	const config_path = path.join(root, PROJECT_CONFIG_FILE)
-	const existing = existsSync(config_path) ? readFileSync(config_path, 'utf8') : ''
+	const existing = read_optional(config_path)
 	const workspace = readFileSync(workspace_path, 'utf8')
-	const merged = merge_project_config(existing, workspace)
+	const npmrc = read_optional(path.join(root, NPMRC_FILE))
+	const merged = merge_project_config(existing, workspace, npmrc)
 	if (merged === existing) return false
 	writeFileSync(config_path, merged)
 

package/scripts/sync/sync.ts

@@ -371,7 +371,6 @@ function report_repository_settings(name_with_owner: string | undefined): void {
 
 function sync_project_artifacts(is_force: boolean): void {
 	sync_ai_copy_all(is_force)
-	project_config.sync_project_config(PROJECT_ROOT)
 	sync_prettier_config(path.join(PROJECT_ROOT, 'prettier.config.js'))
 	sync_playwright_config(path.join(PROJECT_ROOT, 'playwright.config.ts'))
 	sync_deploy_vps(path.join(PROJECT_ROOT, '.github/workflows/deploy-vps.yml'))
@@ -382,6 +381,9 @@ function sync_project_artifacts(is_force: boolean): void {
 
 	sync_sonar_with_template(name_with_owner, is_force)
 	sync_config_files()
+	// After `sync_config_files`, which may add the `.npmrc` window `.aikido`'s age is derived from
+	// (joshuafolkken/kit#2743).
+	project_config.sync_project_config(PROJECT_ROOT)
 	sync_package_json_migrations(path.join(PROJECT_ROOT, PACKAGE_JSON))
 	report_repository_settings(name_with_owner)
 }

package/scripts/version/release-age.ts

@@ -19,12 +19,18 @@ const NPMRC_PATH = '.npmrc'
 const release_times_schema = z.record(z.string(), z.string())
 const MS_PER_MINUTE = 60_000
 
+// The window `.npmrc` content declares, or nothing when it does not declare one — an explicit
+// `minimum-release-age=0` stays 0 rather than collapsing into "not declared".
+function parse_declared_minimum_release_age(npmrc_content: string): number | undefined {
+	const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1]
+
+	return raw === undefined ? undefined : Number(raw)
+}
+
 // The quarantine window in minutes from `.npmrc`; a missing or malformed entry means no
 // quarantine, matching pnpm's own default for the setting.
 function parse_minimum_release_age(npmrc_content: string): number {
-	const raw = MINIMUM_RELEASE_AGE_RE.exec(npmrc_content)?.[1]
-
-	return raw === undefined ? NO_QUARANTINE_MINUTES : Number(raw)
+	return parse_declared_minimum_release_age(npmrc_content) ?? NO_QUARANTINE_MINUTES
 }
 
 // Stable releases only, on the requested major, published at or before the cutoff. The
@@ -82,9 +88,7 @@ function select_aged_version(
 // `minimum-release-age=0` opt-out stop the walk instead of falling through to an ancestor's policy.
 function read_declared_minimum_release_age(npmrc_path: string): number | undefined {
 	try {
-		const raw = MINIMUM_RELEASE_AGE_RE.exec(readFileSync(npmrc_path, 'utf8'))?.[1]
-
-		return raw === undefined ? undefined : Number(raw)
+		return parse_declared_minimum_release_age(readFileSync(npmrc_path, 'utf8'))
 	} catch {
 		return undefined
 	}
@@ -138,6 +142,7 @@ function read_nearest_minimum_release_age(start: string, boundary?: string): num
 const release_age = {
 	release_times_schema,
 	parse_minimum_release_age,
+	parse_declared_minimum_release_age,
 	read_minimum_release_age,
 	read_nearest_minimum_release_age,
 	select_aged_version,