@joshuafolkken/kit 1.947.0 → 1.957.0

package/dist/hooks/{chunk-OM5VDM6F.js → chunk-XSL4SRMA.js}

@@ -1,13 +1,13 @@
 import {
   lane_child_marker
-} from "./chunk-O3PEDF3M.js";
+} from "./chunk-LDQDZYHX.js";
 import {
   time_bundle_call,
   time_format,
   time_round_trips,
   time_spans,
   time_transcript_line
-} from "./chunk-EYFJ74MJ.js";
+} from "./chunk-BELI5XSS.js";
 
 // scripts/lane/lane-guard-policy.ts
 var DEFAULT_MODE = "refuse";

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

@@ -1,25 +1,25 @@
 #!/usr/bin/env tsx
 import {
   pretool_guard
-} from "./chunk-GIX5SAAB.js";
-import "./chunk-3FWV6CFC.js";
+} from "./chunk-M6K7EQDO.js";
+import "./chunk-IJPBTDTB.js";
 import {
   build_envelope,
   compose_context,
   format_edited_payload
-} from "./chunk-IA7WC4NS.js";
+} from "./chunk-3ON7HOYB.js";
 import "./chunk-3V37IID6.js";
-import "./chunk-V7RH56HU.js";
-import "./chunk-NKVLBB65.js";
-import "./chunk-IBFC25IX.js";
-import "./chunk-M4U4YNRE.js";
-import "./chunk-OM5VDM6F.js";
+import "./chunk-244WYOEO.js";
+import "./chunk-KOCK5FXQ.js";
+import "./chunk-GNOITLRR.js";
+import "./chunk-HJXQZ7V4.js";
+import "./chunk-XSL4SRMA.js";
 import {
   hook_decision
-} from "./chunk-O3PEDF3M.js";
+} from "./chunk-LDQDZYHX.js";
 import {
   time_density_hook
-} from "./chunk-EYFJ74MJ.js";
+} from "./chunk-BELI5XSS.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 

package/dist/hooks/duplicate-read-guard.js

@@ -9,11 +9,11 @@ import {
   is_enabled,
   notice_refusal_path,
   refusal_path
-} from "./chunk-IBFC25IX.js";
-import "./chunk-M4U4YNRE.js";
-import "./chunk-OM5VDM6F.js";
-import "./chunk-O3PEDF3M.js";
-import "./chunk-EYFJ74MJ.js";
+} from "./chunk-GNOITLRR.js";
+import "./chunk-HJXQZ7V4.js";
+import "./chunk-XSL4SRMA.js";
+import "./chunk-LDQDZYHX.js";
+import "./chunk-BELI5XSS.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 export {

package/dist/hooks/format-edited.js

@@ -15,9 +15,9 @@ import {
   relative_to_root,
   resolve_invocations,
   select_invocation
-} from "./chunk-IA7WC4NS.js";
+} from "./chunk-3ON7HOYB.js";
 import "./chunk-3V37IID6.js";
-import "./chunk-EYFJ74MJ.js";
+import "./chunk-BELI5XSS.js";
 import "./chunk-RKUAD3I6.js";
 export {
   ESLINT_DAEMON,

package/dist/hooks/investigation-guard.js

@@ -10,11 +10,11 @@ import {
   is_enabled,
   load_environment_file,
   refusal_path
-} from "./chunk-NKVLBB65.js";
-import "./chunk-M4U4YNRE.js";
-import "./chunk-OM5VDM6F.js";
-import "./chunk-O3PEDF3M.js";
-import "./chunk-EYFJ74MJ.js";
+} from "./chunk-KOCK5FXQ.js";
+import "./chunk-HJXQZ7V4.js";
+import "./chunk-XSL4SRMA.js";
+import "./chunk-LDQDZYHX.js";
+import "./chunk-BELI5XSS.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 export {

package/dist/hooks/pretool-guard.js

@@ -3,16 +3,16 @@ import {
   pretool_guard,
   pretool_outcome,
   pretool_outcome_async
-} from "./chunk-GIX5SAAB.js";
-import "./chunk-3FWV6CFC.js";
+} from "./chunk-M6K7EQDO.js";
+import "./chunk-IJPBTDTB.js";
 import "./chunk-3V37IID6.js";
-import "./chunk-V7RH56HU.js";
-import "./chunk-NKVLBB65.js";
-import "./chunk-IBFC25IX.js";
-import "./chunk-M4U4YNRE.js";
-import "./chunk-OM5VDM6F.js";
-import "./chunk-O3PEDF3M.js";
-import "./chunk-EYFJ74MJ.js";
+import "./chunk-244WYOEO.js";
+import "./chunk-KOCK5FXQ.js";
+import "./chunk-GNOITLRR.js";
+import "./chunk-HJXQZ7V4.js";
+import "./chunk-XSL4SRMA.js";
+import "./chunk-LDQDZYHX.js";
+import "./chunk-BELI5XSS.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 export {

package/dist/hooks/stop-guard.js

@@ -16,20 +16,20 @@ import {
   run_hold,
   run_invocation,
   run_watcher_guard
-} from "./chunk-3FWV6CFC.js";
+} from "./chunk-IJPBTDTB.js";
 import {
   session_language
 } from "./chunk-6V5OPIUU.js";
 import {
   hook_decision,
   lane_child_marker
-} from "./chunk-O3PEDF3M.js";
+} from "./chunk-LDQDZYHX.js";
 import {
   PROJECT_ROOT,
   stamp_file,
   time_density_hook,
   time_hook_transcript
-} from "./chunk-EYFJ74MJ.js";
+} from "./chunk-BELI5XSS.js";
 import "./chunk-WPALEIRX.js";
 import "./chunk-RKUAD3I6.js";
 

package/dist/josh.js

@@ -1173,9 +1173,13 @@ var PROJECT_COMMANDS = {
   },
   start: {
     script: "scripts/init/start.ts",
-    description: "Initialize a project for the GitHub Issue workflow",
+    description: "Create a new project for the GitHub Issue workflow, from git init to labels",
     category: "Project",
-    reference: [PROFILE_ARGUMENTS, "developer", ["files", "git", "network"]]
+    reference: [
+      `${PROFILE_ARGUMENTS} [--yes] [--github] [--public]`,
+      "developer",
+      ["files", "git", "network", "processes"]
+    ]
   },
   init: {
     script: "scripts/init/init.ts",

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.957.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/backlog/backlog-drive-cli.ts

@@ -3,6 +3,7 @@ import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { CONTEXT_CUT_THRESHOLD } from '#scripts/cost-runtime/context-cut-threshold'
+import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_await, type AwaitState } from '#scripts/lane/lane-await'
 import { lane_launch_cli } from '#scripts/lane/lane-launch-cli'
@@ -24,6 +25,7 @@ import { backlog_drive_named_offer } from './backlog-drive-named-offer'
 import { backlog_drive_offer_argv } from './backlog-drive-offer-argv'
 import { backlog_drive_owner } from './backlog-drive-owner'
 import { backlog_drive_restore } from './backlog-drive-restore'
+import { backlog_drive_retrospective } from './backlog-drive-retrospective'
 import { backlog_offer_cli } from './backlog-offer-cli'
 
 // `josh backlog:drive` — the backlogrun parent's loop as one resident wait (joshuafolkken/kit#2499).
@@ -193,7 +195,7 @@ async function read_offer(
 
 	return offer === undefined
 		? undefined
-		: { ...offer, is_retrospective_done: carry.retrospective === true }
+		: { ...offer, is_retrospective_owed: backlog_drive_retrospective.is_owed(carry) }
 }
 
 // A non-zero `run:merge` prints its token first only for a hand-off (`busy`, `stop`, `retry`); any
@@ -357,6 +359,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {
+	// Load `.env` on the real command path only, so `JOSH_RETROSPECTIVE` set there reaches the offer read.
+	hook_decision.load_environment_file()
 	process.exitCode = await run(argv)
 }
 

package/scripts/backlog/backlog-drive-retrospective.ts

@@ -0,0 +1,20 @@
+import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { find_package_directory } from '#scripts/josh/josh-logic'
+import type { RunCarry } from '#scripts/run/run-carry'
+import { run_retrospective } from '#scripts/run/run-retrospective'
+
+// Whether a drain owes the retrospective, read through the owed rule `run:step` reads, so a drain it
+// owes nothing at keeps the idle watch rather than waking a session with nothing to run
+// (joshuafolkken/kit#2750). The drive is the parent's loop, never a lane child's.
+function is_owed(carry: RunCarry): boolean {
+	const root = find_package_directory(process.cwd())
+
+	return run_retrospective.is_owed({
+		is_retrospective_enabled: run_retrospective.is_enabled(),
+		is_lane_child: false,
+		is_retrospective_done: carry.retrospective === true,
+		is_consumer: doctor_consumer.is_kit_consumer(root),
+	})
+}
+
+export const backlog_drive_retrospective = { is_owed }

package/scripts/backlog/backlog-drive.ts

@@ -45,7 +45,9 @@ interface OfferRead {
 	retries: number
 	answer?: string | undefined
 	reason?: string | undefined
-	is_retrospective_done?: boolean
+	// Whether a drain here owes the retrospective: the opt-in switch is on and it has not run yet. Absent
+	// reads as not owed, so a drain with the switch off keeps the idle watch (joshuafolkken/kit#2750).
+	is_retrospective_owed?: boolean
 	is_finish?: boolean | undefined
 }
 
@@ -106,7 +108,9 @@ function ended(reason: string, state: DriveState, token?: string, issue?: string
 
 function is_drain(read: OfferRead, state: DriveState): boolean {
 	return (
-		read.verdict === WATCH_VERDICT && state.in_flight.length === 0 && !read.is_retrospective_done
+		read.verdict === WATCH_VERDICT &&
+		state.in_flight.length === 0 &&
+		read.is_retrospective_owed === true
 	)
 }
 
@@ -115,7 +119,7 @@ function needs_retrospective(read: OfferRead, state: DriveState): boolean {
 		read.verdict === STOP_VERDICT &&
 		read.answer === 'exhausted' &&
 		state.in_flight.length === 0 &&
-		!read.is_retrospective_done
+		read.is_retrospective_owed === true
 	)
 }
 

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/issue-labels.ts

@@ -177,6 +177,24 @@ const DEPTH_LABELS: ReadonlyArray<{
 	},
 ]
 
+// What `josh start` provisions on a new repository so the first `kickoff` finds every label a run
+// applies with its intended color (joshuafolkken/kit#2197). The `epic` and `in-progress` metadata is
+// the one the workflow documents create them with; the labels only a person applies are left out.
+const WORKFLOW_LABELS: ReadonlyArray<{
+	name: string
+	color: string
+	description: string
+}> = [
+	{
+		name: EPIC_LABEL,
+		color: '5319e7',
+		description: 'Tracks a batch of child issues from one split',
+	},
+	{ name: IN_PROGRESS_LABEL, color: '0075ca', description: 'Work is actively in progress' },
+	...FILING_ROUTE_LABELS,
+	...DEPTH_LABELS,
+]
+
 // The shape `gh issue list --json labels` returns; narrowed here so the predicate below takes any
 // listing row without importing a schema.
 interface LabelReference {
@@ -285,4 +303,5 @@ export {
 	REVIEW_ROUND2_SKIPPED_LABEL,
 	SPLIT_ROUTE_LABEL,
 	TIER_A_ROUTE_LABEL,
+	WORKFLOW_LABELS,
 }

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 }