@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/dist/josh.js

@@ -131,20 +131,20 @@ var ABSENT_CODE = "ENOENT";
 function is_absent(error) {
   return error instanceof Error && "code" in error && error.code === ABSENT_CODE;
 }
-function read_optional(path12) {
+function read_optional(path16) {
   try {
-    return readFileSync(path12, "utf8");
+    return readFileSync(path16, "utf8");
   } catch (error) {
     if (is_absent(error)) return void 0;
     throw error;
   }
 }
-function read_file_or_empty(path12) {
-  return read_optional(path12) ?? "";
+function read_file_or_empty(path16) {
+  return read_optional(path16) ?? "";
 }
-function read_if_readable(path12) {
+function read_if_readable(path16) {
   try {
-    return readFileSync(path12, "utf8");
+    return readFileSync(path16, "utf8");
   } catch {
     return void 0;
   }
@@ -267,93 +267,6 @@ var doctor_consumer = {
   secretlint_line
 };
 
-// scripts/josh/josh-logic.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5 } from "node:fs";
-import path11 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-
-// scripts/build/local-bin.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { createRequire } from "node:module";
-import path3 from "node:path";
-
-// scripts/lib/ancestor-directories.ts
-import path2 from "node:path";
-var MAX_DEPTH = 64;
-function list(start_directory) {
-  const directories = [];
-  let current = path2.resolve(start_directory);
-  while (directories.length < MAX_DEPTH && !directories.includes(current)) {
-    directories.push(current);
-    current = path2.dirname(current);
-  }
-  return directories;
-}
-function nearest(start_directory, is_match) {
-  return list(start_directory).find((directory) => is_match(directory));
-}
-var ancestor_directories = { list, nearest };
-
-// scripts/lib/schemas.ts
-import { z as z2 } from "zod";
-var overrides_snapshot_schema = z2.record(z2.string(), z2.string());
-var package_version_schema = z2.object({ version: z2.string() });
-var package_named_version_schema = z2.looseObject({ name: z2.string(), version: z2.string() });
-var package_with_version_schema = z2.looseObject({ version: z2.string() });
-var ls_global_dependency_schema = z2.looseObject({ version: z2.string() });
-var ls_global_dependencies_schema = z2.record(z2.string(), ls_global_dependency_schema).optional();
-var pnpm_ls_global_schema = z2.array(
-  z2.looseObject({
-    dependencies: ls_global_dependencies_schema
-  })
-);
-var vscode_settings_schema = z2.record(z2.string(), z2.unknown());
-var with_scripts_schema = z2.looseObject({
-  scripts: z2.record(z2.string(), z2.string()).optional()
-});
-var with_development_deps_schema = z2.looseObject({
-  devDependencies: z2.record(z2.string(), z2.string()).optional()
-});
-var with_package_manager_schema = z2.looseObject({
-  packageManager: z2.string().optional()
-});
-var with_development_engine_schema = z2.looseObject({
-  devEngines: z2.record(z2.string(), z2.unknown()).optional()
-});
-var bin_entry_schema = z2.union([z2.string(), z2.record(z2.string(), z2.string())]).optional();
-var package_bin_schema = z2.looseObject({ bin: bin_entry_schema });
-var json_object_schema = z2.record(z2.string(), z2.unknown());
-var string_array_schema = z2.array(z2.string());
-var string_record_schema = z2.record(z2.string(), z2.string());
-
-// scripts/build/local-bin.ts
-var NODE_MODULES2 = "node_modules";
-var BIN_DIR = ".bin";
-var WINDOWS_PLATFORM = "win32";
-var WINDOWS_SHIM_SUFFIX = ".cmd";
-var PACKAGE_JSON = "package.json";
-function resolve_local_bin(project_root, bin_name) {
-  const shim = process.platform === WINDOWS_PLATFORM ? `${bin_name}${WINDOWS_SHIM_SUFFIX}` : bin_name;
-  return path3.join(project_root, NODE_MODULES2, BIN_DIR, shim);
-}
-function read_bin_entry(manifest_path, package_name, bin_name) {
-  const { bin } = package_bin_schema.parse(JSON.parse(readFileSync2(manifest_path, "utf8")));
-  if (typeof bin === "string") return bin_name === path3.basename(package_name) ? bin : void 0;
-  return bin?.[bin_name];
-}
-function resolve_package_bin(base_directory, package_name, bin_name) {
-  try {
-    const resolve_from = createRequire(path3.join(base_directory, PACKAGE_JSON));
-    const manifest_path = resolve_from.resolve(`${package_name}/${PACKAGE_JSON}`);
-    const bin_entry = read_bin_entry(manifest_path, package_name, bin_name);
-    if (bin_entry === void 0) return void 0;
-    const cli_entry = path3.join(path3.dirname(manifest_path), bin_entry);
-    return existsSync2(cli_entry) ? cli_entry : void 0;
-  } catch {
-    return void 0;
-  }
-}
-
 // scripts/gate/core-budget.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { readdirSync as readdirSync2 } from "node:fs";
@@ -364,7 +277,7 @@ import path8 from "node:path";
 import { accessSync, constants } from "node:fs";
 import { tmpdir } from "node:os";
 var POSIX_TEMP_ROOT = "/tmp";
-var WINDOWS_PLATFORM2 = "win32";
+var WINDOWS_PLATFORM = "win32";
 function is_writable_directory(directory) {
   try {
     accessSync(directory, constants.W_OK);
@@ -374,7 +287,7 @@ function is_writable_directory(directory) {
   }
 }
 function resolve_temporary_root(platform2, can_write = is_writable_directory) {
-  if (platform2 === WINDOWS_PLATFORM2) return tmpdir();
+  if (platform2 === WINDOWS_PLATFORM) return tmpdir();
   return can_write(POSIX_TEMP_ROOT) ? POSIX_TEMP_ROOT : tmpdir();
 }
 var TEMP_ROOT_KEY = "JOSH_TEMP_ROOT";
@@ -386,9 +299,9 @@ var PLATFORM_TEMP_ROOT = temporary_root(process.env[TEMP_ROOT_KEY], process.plat
 // scripts/josh/process-identity.ts
 import { execFileSync, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { readFileSync as readFileSync3, rmSync } from "node:fs";
+import { readFileSync as readFileSync2, rmSync } from "node:fs";
 import { createServer } from "node:net";
-import path4 from "node:path";
+import path2 from "node:path";
 var PS_COMMAND = "/bin/ps";
 var FORMAT_FLAG = "-o";
 var START_TIME_FORMAT = "lstart=";
@@ -403,7 +316,7 @@ 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_PLATFORM3 = "win32";
+var WINDOWS_PLATFORM2 = "win32";
 var BEACON_LIVE_STATUS = 0;
 var BEACON_UNKNOWN_STATUS = 1;
 var BEACON_GONE_STATUS = 2;
@@ -426,7 +339,7 @@ function is_present_pid(pid) {
 }
 function read_proc_start(pid) {
   try {
-    const stat = readFileSync3(`/proc/${String(pid)}/stat`, "utf8");
+    const stat = readFileSync2(`/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}`;
@@ -491,7 +404,7 @@ function try_bind_beacon(bind, target) {
   }
 }
 function open_beacon(bind = bind_beacon) {
-  const target = path4.join(PLATFORM_TEMP_ROOT, `${BEACON_PREFIX}${randomUUID()}${BEACON_SUFFIX}`);
+  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;
@@ -502,7 +415,7 @@ function open_beacon(bind = bind_beacon) {
 }
 function resolve_own_start(probes = START_PROBES, platform2 = process.platform) {
   const start = read_start(process.pid, probes);
-  if (start !== void 0 || platform2 === WINDOWS_PLATFORM3) return start;
+  if (start !== void 0 || platform2 === WINDOWS_PLATFORM2) return start;
   return open_beacon();
 }
 function is_valid_beacon_name(name) {
@@ -513,8 +426,8 @@ function is_valid_beacon_name(name) {
 function beacon_target(token) {
   if (!token.startsWith(BEACON_SCHEME)) return void 0;
   const target = token.slice(BEACON_SCHEME.length);
-  if (path4.dirname(target) !== PLATFORM_TEMP_ROOT) return void 0;
-  return is_valid_beacon_name(path4.basename(target)) ? target : void 0;
+  if (path2.dirname(target) !== PLATFORM_TEMP_ROOT) return void 0;
+  return is_valid_beacon_name(path2.basename(target)) ? target : void 0;
 }
 function run_socket_probe(target) {
   return spawnSync(process.execPath, ["-e", SOCKET_PROBE_SOURCE, target], {
@@ -573,18 +486,18 @@ var process_identity = {
 };
 
 // scripts/josh/process-owner.ts
-import { z as z3 } from "zod";
-var process_owner_schema = z3.object({ pid: z3.number(), process_start: z3.string().optional() });
+import { z as z2 } from "zod";
+var process_owner_schema = z2.object({ pid: z2.number(), process_start: z2.string().optional() });
 
 // scripts/josh/stamp-file.ts
 import { createHash, randomUUID as randomUUID2 } from "node:crypto";
-import { lstatSync, readFileSync as readFileSync4, renameSync, rmSync as rmSync2, writeFileSync } from "node:fs";
-import path6 from "node:path";
+import { lstatSync, readFileSync as readFileSync3, renameSync, rmSync as rmSync2, writeFileSync } from "node:fs";
+import path4 from "node:path";
 
 // scripts/init/init-paths.ts
-import path5 from "node:path";
+import path3 from "node:path";
 import { fileURLToPath } from "node:url";
-var PACKAGE_DIR = path5.join(path5.dirname(fileURLToPath(import.meta.url)), "..", "..");
+var PACKAGE_DIR = path3.join(path3.dirname(fileURLToPath(import.meta.url)), "..", "..");
 var PROJECT_ROOT = process.cwd();
 
 // scripts/josh/stamp-file.ts
@@ -604,7 +517,7 @@ function account_key() {
 }
 function stamp_path(prefix, root = PACKAGE_DIR, suffix = STAMP_SUFFIX) {
   const key = digest(`${account_key()}${ACCOUNT_KEY_SEPARATOR}${root}`).slice(0, STAMP_KEY_LENGTH);
-  return path6.join(PLATFORM_TEMP_ROOT, `${prefix}${key}${suffix}`);
+  return path4.join(PLATFORM_TEMP_ROOT, `${prefix}${key}${suffix}`);
 }
 function write_exclusively(target, content) {
   rmSync2(target, { force: true });
@@ -664,7 +577,7 @@ function remove_stamp(target) {
 function read_stamp_text(source) {
   try {
     if (!is_own_regular_file(source)) return void 0;
-    return readFileSync4(source, "utf8");
+    return readFileSync3(source, "utf8");
   } catch {
     return void 0;
   }
@@ -685,7 +598,7 @@ var stamp_file = {
 // scripts/test/unit-worker-share.ts
 import { readdirSync } from "node:fs";
 import { availableParallelism } from "node:os";
-import path7 from "node:path";
+import path5 from "node:path";
 var RUN_PREFIX = "josh-unit-running-";
 var WORKER_FLAG = "--maxWorkers";
 var WORKER_FLAGS = [WORKER_FLAG, "--max-workers"];
@@ -724,7 +637,7 @@ function is_marker_live(source) {
   return false;
 }
 function live_run_count(directory = PLATFORM_TEMP_ROOT) {
-  return marker_files(directory).filter((name) => is_marker_live(path7.join(directory, name))).length;
+  return marker_files(directory).filter((name) => is_marker_live(path5.join(directory, name))).length;
 }
 var NESTED_KEY = "JOSH_UNIT_RUN_MARKED";
 var NESTED_VALUE = "1";
@@ -735,17 +648,23 @@ function resolve_unit_workers(available_cores, runs) {
   if (runs <= SOLO_RUNS) return void 0;
   return Math.max(MIN_WORKERS, Math.floor(available_cores / runs));
 }
-function current_share(available_cores = availableParallelism(), live_runs = live_run_count()) {
+function cap_to_free(workers, free_cores, available_cores) {
+  if (free_cores === void 0 || free_cores >= (workers ?? available_cores)) return workers;
+  return Math.max(MIN_WORKERS, Math.floor(free_cores));
+}
+function current_share(available_cores = availableParallelism(), live_runs = live_run_count(), free_cores) {
   const own_run = is_nested_run() ? 0 : SOLO_RUNS;
-  return resolve_unit_workers(available_cores, live_runs + own_run);
+  const share = resolve_unit_workers(available_cores, live_runs + own_run);
+  return cap_to_free(share, free_cores, available_cores);
 }
 function is_worker_flag(argument) {
   return WORKER_FLAGS.some((flag) => argument === flag || argument.startsWith(`${flag}=`));
 }
+function has_worker_flag(vitest_arguments) {
+  return vitest_arguments.some((argument) => is_worker_flag(argument));
+}
 function worker_arguments(vitest_arguments, share) {
-  if (share === void 0 || vitest_arguments.some((argument) => is_worker_flag(argument))) {
-    return [];
-  }
+  if (share === void 0 || has_worker_flag(vitest_arguments)) return [];
   return [`${WORKER_FLAG}=${String(share)}`];
 }
 function mark_run_started(target) {
@@ -772,7 +691,9 @@ var unit_worker_share = {
   NESTED_VALUE,
   RUN_PREFIX,
   SOLO_RUNS,
+  cap_to_free,
   current_share,
+  has_worker_flag,
   is_nested_run,
   live_run_count,
   marker_path,
@@ -783,7 +704,7 @@ var unit_worker_share = {
 };
 
 // scripts/gate/core-budget.ts
-import { z as z4 } from "zod";
+import { z as z3 } from "zod";
 
 // scripts/gate/core-admission.ts
 var MS_PER_SECOND = 1e3;
@@ -856,6 +777,151 @@ var core_admission = {
   sum_load
 };
 
+// scripts/gate/core-wait.ts
+import path7 from "node:path";
+
+// scripts/lane/lane-paths.ts
+import path6 from "node:path";
+
+// scripts/issue/issue-number-shape.ts
+var ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u;
+var BAD_ISSUE_MESSAGE = "Not an issue number: ";
+function is_issue_number(value) {
+  return ISSUE_NUMBER_PATTERN.test(value);
+}
+function require_issue_number(issue) {
+  if (!is_issue_number(issue)) throw new Error(`${BAD_ISSUE_MESSAGE}${issue}`);
+}
+var issue_number_shape = { ISSUE_NUMBER_PATTERN, is_issue_number, require_issue_number };
+
+// scripts/lane/lane-paths.ts
+var LANE_ROOT_KEY = "JOSH_LANE_ROOT";
+var LANE_DIRECTORY_SUFFIX = "-lanes";
+var LANE_BRANCH_SUFFIX = "-lane";
+function default_lane_root(repository_root) {
+  const name = path6.basename(repository_root);
+  return path6.join(path6.dirname(repository_root), `.${name}${LANE_DIRECTORY_SUFFIX}`);
+}
+function lane_root(repository_root, environment = process.env) {
+  const configured = environment[LANE_ROOT_KEY]?.trim() ?? "";
+  return configured.length === 0 ? default_lane_root(repository_root) : path6.resolve(configured);
+}
+function lane_directory(root, issue) {
+  return path6.join(root, issue);
+}
+var DEFAULT_LANE_ROOT_PATTERN = new RegExp(String.raw`^\..+${LANE_DIRECTORY_SUFFIX}$`, "u");
+function is_lane_root(directory, environment) {
+  const configured = environment[LANE_ROOT_KEY]?.trim() ?? "";
+  if (configured.length > 0) return path6.resolve(configured) === directory;
+  return DEFAULT_LANE_ROOT_PATTERN.test(path6.basename(directory));
+}
+function lane_issue_of(directory, environment = process.env) {
+  const resolved = path6.resolve(directory);
+  const issue = path6.basename(resolved);
+  if (!issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) return void 0;
+  return is_lane_root(path6.dirname(resolved), environment) ? issue : void 0;
+}
+function lane_branch(issue) {
+  return `${issue}${LANE_BRANCH_SUFFIX}`;
+}
+var SEAT_LOCK_DIR = ".seat-locks";
+function is_lane_entry(name) {
+  return issue_number_shape.ISSUE_NUMBER_PATTERN.test(name) || DEFAULT_LANE_ROOT_PATTERN.test(name);
+}
+var lane_paths = {
+  LANE_BRANCH_SUFFIX,
+  LANE_ROOT_KEY,
+  SEAT_LOCK_DIR,
+  default_lane_root,
+  is_lane_entry,
+  lane_branch,
+  lane_directory,
+  lane_issue_of,
+  lane_root
+};
+
+// scripts/gate/core-wait.ts
+var WAIT_REASONS = ["cores", "memory", "pressure"];
+var REASON_TEXT = {
+  cores: "not enough free cores",
+  memory: "not enough free memory",
+  pressure: "memory under pressure"
+};
+function wait_reason(key, reservations, budget) {
+  const cores_only = { cores: budget.cores, memory_mb: Infinity };
+  if (!core_admission.is_admitted(key, reservations, cores_only)) return "cores";
+  return budget.memory_pressured === true ? "pressure" : "memory";
+}
+function wait_line(command, reason) {
+  return `\u23F3 ${command ?? "a step"} waits for the core budget \u2014 ${REASON_TEXT[reason]}`;
+}
+function lanes_root_of(checkout) {
+  if (lane_paths.lane_issue_of(checkout) === void 0) return lane_paths.lane_root(checkout);
+  return path7.dirname(path7.resolve(checkout));
+}
+function where_of(checkout) {
+  return { checkout, lane: lane_paths.lane_issue_of(checkout), lanes_root: lanes_root_of(checkout) };
+}
+function place_of(marker, home_root) {
+  const { checkout, lane, lanes_root } = marker;
+  if (checkout === void 0 || lanes_root === void 0 || lanes_root === home_root) {
+    return { lane, elsewhere: void 0 };
+  }
+  const name = lane === void 0 ? path7.basename(checkout) : `${path7.basename(lanes_root)}/${lane}`;
+  return { lane: void 0, elsewhere: name };
+}
+function wait_of(marker, now, home_root) {
+  const { command, wait_reason: reason } = marker;
+  if (reason === void 0 || marker.admitted_at !== void 0) return [];
+  return [{ command, ...place_of(marker, home_root), waited_ms: now - marker.claimed_at, reason }];
+}
+function waits_of(entries, now, home) {
+  const home_root = lanes_root_of(home);
+  return entries.flatMap((entry) => wait_of(entry.reservation, now, home_root)).toSorted((left, right) => right.waited_ms - left.waited_ms);
+}
+var core_wait = {
+  REASON_TEXT,
+  WAIT_REASONS,
+  wait_line,
+  wait_reason,
+  waits_of,
+  where_of
+};
+
+// scripts/gate/held-mark.ts
+var HELD_KEY = "JOSH_CORE_RESERVED";
+var HELD_VALUE = "1";
+var HELD_RESERVATION_KEY = "JOSH_CORE_RESERVATION";
+function is_held() {
+  return process.env[HELD_KEY] === HELD_VALUE;
+}
+function held_reservation() {
+  const key = process.env[HELD_RESERVATION_KEY] ?? "";
+  return key === "" ? void 0 : key;
+}
+function set_held_mark(value, reservation) {
+  process.env[HELD_KEY] = value;
+  process.env[HELD_RESERVATION_KEY] = reservation;
+}
+async function with_held_mark(run2, reservation = "") {
+  const previous = process.env[HELD_KEY] ?? "";
+  const previous_reservation = process.env[HELD_RESERVATION_KEY] ?? "";
+  set_held_mark(HELD_VALUE, reservation);
+  try {
+    return await run2();
+  } finally {
+    set_held_mark(previous, previous_reservation);
+  }
+}
+var held_mark = {
+  HELD_KEY,
+  HELD_RESERVATION_KEY,
+  HELD_VALUE,
+  held_reservation,
+  is_held,
+  with_held_mark
+};
+
 // scripts/gate/machine-capacity.ts
 import { readFile } from "node:fs/promises";
 import { availableParallelism as availableParallelism2, cpus, totalmem } from "node:os";
@@ -874,9 +940,20 @@ var PAGE_SIZE_ARGUMENTS = ["PAGESIZE"];
 var LEVEL_NAME = "kern.memorystatus_level";
 var SWAP_IN_NAME = "vm.compressor.swapper.swapins_total";
 var SWAP_OUT_NAME = "vm.compressor.swapper.swapouts_total";
+var COMPRESSED_NAME = "vm.compressor_input_bytes";
 var PAGE_SIZE_NAME = "hw.pagesize";
 var PRESSURE_NAME = "kern.memorystatus_vm_pressure_level";
-var SYSCTL_ARGUMENTS = [LEVEL_NAME, SWAP_IN_NAME, SWAP_OUT_NAME, PAGE_SIZE_NAME, PRESSURE_NAME];
+var PRESSURE_WARNING = 2;
+var SWAP_PRESSURE_MB = 16;
+var COMPRESSION_PRESSURE_MB = 64;
+var SYSCTL_ARGUMENTS = [
+  LEVEL_NAME,
+  SWAP_IN_NAME,
+  SWAP_OUT_NAME,
+  COMPRESSED_NAME,
+  PAGE_SIZE_NAME,
+  PRESSURE_NAME
+];
 var SYSCTL_LINE = /^(?<name>[\w.]+): (?<value>\d+)$/gmu;
 function cpu_times() {
   let busy = 0;
@@ -905,9 +982,9 @@ function sysctl_values(output) {
 function swapped_pages(pages_in, pages_out) {
   return pages_in === void 0 || pages_out === void 0 ? void 0 : pages_in + pages_out;
 }
-function swapped_mb(pages, page_bytes) {
-  if (pages === void 0 || page_bytes === void 0) return void 0;
-  return pages * page_bytes / BYTES_PER_MB;
+function mb_of(units, unit_bytes) {
+  if (units === void 0 || unit_bytes === void 0) return void 0;
+  return units * unit_bytes / BYTES_PER_MB;
 }
 function swapped_between(from, to) {
   if (from === void 0 || to === void 0) return void 0;
@@ -918,11 +995,12 @@ function parse_darwin_memory(output, total_bytes) {
   const level = values.get(LEVEL_NAME);
   return {
     available_mb: level === void 0 ? void 0 : level / PERCENT * (total_bytes / BYTES_PER_MB),
-    swapped_mb: swapped_mb(
+    swapped_mb: mb_of(
       swapped_pages(values.get(SWAP_IN_NAME), values.get(SWAP_OUT_NAME)),
       values.get(PAGE_SIZE_NAME)
     ),
-    pressure_level: values.get(PRESSURE_NAME)
+    pressure_level: values.get(PRESSURE_NAME),
+    compressed_mb: mb_of(values.get(COMPRESSED_NAME), 1)
   };
 }
 function parse_linux_available(meminfo) {
@@ -935,7 +1013,7 @@ function pages_of(pattern, vmstat) {
 }
 function parse_linux_swapped(vmstat, page_bytes) {
   const pages = swapped_pages(pages_of(LINUX_SWAP_IN, vmstat), pages_of(LINUX_SWAP_OUT, vmstat));
-  return swapped_mb(pages, page_bytes);
+  return mb_of(pages, page_bytes);
 }
 async function settled(read2) {
   try {
@@ -985,11 +1063,26 @@ async function default_sleep(ms) {
     setTimeout(resolve, ms);
   });
 }
+function moved_over(from, to, limit) {
+  return (swapped_between(from, to) ?? 0) > limit;
+}
+function is_pressured(before, after) {
+  return (after.pressure_level ?? 0) >= PRESSURE_WARNING || moved_over(before.swapped_mb, after.swapped_mb, SWAP_PRESSURE_MB) || moved_over(before.compressed_mb, after.compressed_mb, COMPRESSION_PRESSURE_MB);
+}
+function pressured_available(before, after) {
+  if (after.available_mb === void 0) return void 0;
+  return is_pressured(before, after) ? 0 : after.available_mb;
+}
 async function read_machine(sleep = default_sleep) {
   const before = cpu_times();
-  const [memory] = await Promise.all([read_memory(), sleep(SAMPLE_WINDOW_MS)]);
+  const [memory_before] = await Promise.all([read_memory(), sleep(SAMPLE_WINDOW_MS)]);
+  const memory_after = await read_memory();
   const busy_cores = is_unquoted() ? busy_cores_between(before, cpu_times(), cpus().length) : void 0;
-  return { busy_cores, available_mb: memory.available_mb };
+  return {
+    busy_cores,
+    available_mb: pressured_available(memory_before, memory_after),
+    memory_pressured: is_pressured(memory_before, memory_after)
+  };
 }
 async function read_sample() {
   return { cpu: cpu_times(), memory: await read_memory(), total_mb: totalmem() / BYTES_PER_MB };
@@ -1001,21 +1094,25 @@ function external_cores(busy_cores, ledger_cores) {
 function machine_budget(cores, reading, ledger) {
   return {
     cores: cores - external_cores(reading.busy_cores, ledger.cores),
-    memory_mb: reading.available_mb === void 0 ? Infinity : reading.available_mb + ledger.memory_mb
+    memory_mb: reading.available_mb === void 0 ? Infinity : reading.available_mb + ledger.memory_mb,
+    memory_pressured: reading.memory_pressured
   };
 }
 var machine_capacity = {
   BASELINE_CORES,
   busy_cores_between,
   busy_share_between,
+  COMPRESSION_PRESSURE_MB,
   external_cores,
   machine_budget,
   parse_darwin_memory,
   parse_linux_available,
   parse_linux_swapped,
+  pressured_available,
   read_machine,
   read_memory,
   read_sample,
+  SWAP_PRESSURE_MB,
   swapped_between
 };
 
@@ -1029,22 +1126,32 @@ var CORE_WEIGHTS = {
   lint: 2,
   type_check: 1,
   spell_check: 1,
-  eslint_scan: 1
+  eslint_scan: 1,
+  format: 1,
+  retrospective: 1,
+  install: 1,
+  e2e: 2
 };
 var MEMORY_MB = {
   lint: 2400,
   type_check: 1300,
   spell_check: 350,
   eslint_scan: 2400,
-  unit_worker: 350
+  unit_worker: 350,
+  format: 300,
+  retrospective: 900,
+  install: 100
 };
-var HELD_KEY = "JOSH_CORE_RESERVED";
-var HELD_VALUE = "1";
 var reservation_schema = process_owner_schema.extend({
-  weight: z4.number(),
-  claimed_at: z4.number(),
-  memory_mb: z4.number().optional(),
-  admitted_at: z4.number().optional()
+  weight: z3.number(),
+  claimed_at: z3.number(),
+  memory_mb: z3.number().optional(),
+  admitted_at: z3.number().optional(),
+  command: z3.string().optional(),
+  checkout: z3.string().optional(),
+  lane: z3.string().optional(),
+  lanes_root: z3.string().optional(),
+  wait_reason: z3.enum(core_wait.WAIT_REASONS).optional()
 });
 function marker_name(key) {
   return `${RESERVED_PREFIX}${key}${RESERVED_SUFFIX}`;
@@ -1096,6 +1203,10 @@ async function default_sleep2(ms) {
 function write_reservation(target, fields) {
   stamp_file.replace_stamp(target, { ...process_identity.own_fields(), ...fields });
 }
+function report_wait(line) {
+  process.stderr.write(`${line}
+`);
+}
 function resolve_timing(options) {
   return {
     now: options.now ?? Date.now,
@@ -1122,6 +1233,13 @@ function overflow_of(context, reservations, budget) {
     budget
   };
 }
+function mark_waiting(context, reason) {
+  const previous = context.fields.wait_reason;
+  if (previous === reason) return;
+  context.fields = { ...context.fields, wait_reason: reason };
+  write_reservation(context.target, context.fields);
+  if (previous === void 0) context.report(core_wait.wait_line(context.fields.command, reason));
+}
 async function poll_admission(context) {
   const reservations = live_reservations(context.directory);
   const budget = await current_budget(context, reservations);
@@ -1129,6 +1247,7 @@ async function poll_admission(context) {
   if (context.now() >= context.deadline) {
     return admit(context, overflow_of(context, reservations, budget));
   }
+  mark_waiting(context, core_wait.wait_reason(context.key, reservations, budget));
   return void 0;
 }
 async function await_admission(context) {
@@ -1139,13 +1258,23 @@ async function await_admission(context) {
   }
   return admission;
 }
+function resolve_ports(options) {
+  return {
+    read_machine: options.read_machine ?? machine_capacity.read_machine,
+    report: options.report ?? report_wait
+  };
+}
+function claim_fields(weight, claimed_at, options) {
+  const { memory_mb, command } = options;
+  return { weight, claimed_at, memory_mb, command, ...core_wait.where_of(process.cwd()) };
+}
 async function reserve(weight, options = {}) {
   const timing = resolve_timing(options);
   const directory = options.directory ?? PLATFORM_TEMP_ROOT;
   const claimed_at = timing.now();
   const name = marker_name(randomUUID3());
   const target = path8.join(directory, name);
-  const fields = { weight, claimed_at, memory_mb: options.memory_mb };
+  const fields = claim_fields(weight, claimed_at, options);
   write_reservation(target, fields);
   const admission = await await_admission({
     ...timing,
@@ -1155,92 +1284,134 @@ async function reserve(weight, options = {}) {
     budget: normalize_budget(options.budget ?? availableParallelism3()),
     deadline: claimed_at + timing.wait_cap_ms,
     fields,
-    read_machine: options.read_machine ?? machine_capacity.read_machine
+    ...resolve_ports(options)
   });
   return { target, admission };
 }
+function budget_waits(directory = PLATFORM_TEMP_ROOT, now = Date.now(), home = process.cwd()) {
+  return core_wait.waits_of(live_reservations(directory), now, home);
+}
 function release(handle) {
   sweep_marker2(handle.target);
 }
 async function with_core_reservation(weight, run2, options = {}) {
   const handle = await reserve(weight, options);
   try {
-    return await run2(handle.admission);
+    return await run2(handle.admission, path8.basename(handle.target));
   } finally {
     release(handle);
   }
 }
-function is_held() {
-  return process.env[HELD_KEY] === HELD_VALUE;
-}
-function set_held_mark(value) {
-  process.env[HELD_KEY] = value;
-}
-async function with_held_mark(run2) {
-  const previous = process.env[HELD_KEY] ?? "";
-  set_held_mark(HELD_VALUE);
-  try {
-    return await run2();
-  } finally {
-    set_held_mark(previous);
-  }
-}
 async function with_command_reservation(weight, run2, options = {}) {
-  if (is_held() || unit_worker_share.is_nested_run()) return await run2();
-  return await with_core_reservation(weight, async () => await with_held_mark(run2), options);
+  if (held_mark.is_held() || unit_worker_share.is_nested_run()) return await run2();
+  return await with_core_reservation(
+    weight,
+    async (_admission, key) => await held_mark.with_held_mark(run2, key),
+    options
+  );
 }
 var core_budget = {
   CORE_WEIGHTS,
-  HELD_KEY,
-  HELD_VALUE,
+  HELD_KEY: held_mark.HELD_KEY,
+  HELD_VALUE: held_mark.HELD_VALUE,
   MEMORY_MB,
   RESERVED_PREFIX,
   admitted_keys: core_admission.admitted_keys,
   admitted_load: core_admission.admitted_load,
+  budget_waits,
   describe_overflow: core_admission.describe_overflow,
-  is_held,
+  is_held: held_mark.is_held,
   live_reservations,
   release,
   reserve,
   with_command_reservation,
   with_core_reservation,
-  with_held_mark
+  with_held_mark: held_mark.with_held_mark
 };
 
-// scripts/josh/josh-logic.ts
-import { execaSync as execaSync2 } from "execa";
-
-// scripts/josh/command-suggest.ts
-var MAX_SUGGESTION_DISTANCE = 3;
-function at(values, index) {
-  return values[index] ?? 0;
+// ports/index.js
+import { existsSync as existsSync2 } from "node:fs";
+import path9 from "node:path";
+var PORT_SEED_KEY = "PORT_SEED";
+var LANE_SEAT_KEY = "JOSH_LANE_SEAT";
+var ENV_FILE_NAME = ".env";
+var PACKAGE_FILE_NAME = "package.json";
+var PROJECT_ENVIRONMENT_KEYS = /* @__PURE__ */ new Set([PORT_SEED_KEY, LANE_SEAT_KEY, "PLAYWRIGHT_REUSE_SERVER"]);
+var DEV_PORT_BASE = 5173;
+var PREVIEW_PORT_BASE = 4173;
+var MIN_SEED = 0;
+var SEED_LANE_MULTIPLIER = 10;
+var MAX_LANE = 9;
+var MAX_SEED = 99;
+var INTEGER_PATTERN = /^\d+$/u;
+function fail_invalid(key, raw, max) {
+  throw new Error(
+    `${key} must be an integer between ${MIN_SEED} and ${max}, got ${JSON.stringify(raw)}. Unset it to use the default ports (dev ${DEV_PORT_BASE}, preview ${PREVIEW_PORT_BASE}).`
+  );
 }
-function fill_distance_row(source, target, row, previous) {
-  const current = [row];
-  for (let col = 1; col <= target.length; col++) {
-    const cost = source[row - 1] === target[col - 1] ? 0 : 1;
-    const deletion = at(previous, col) + 1;
-    const insertion = at(current, col - 1) + 1;
-    const substitution = at(previous, col - 1) + cost;
-    current.push(Math.min(deletion, insertion, substitution));
+function read_trimmed(environment, key) {
+  const raw = environment[key];
+  return raw === void 0 ? "" : raw.trim();
+}
+function resolve_bounded(environment, key, max) {
+  const trimmed = read_trimmed(environment, key);
+  if (trimmed.length === 0) return MIN_SEED;
+  if (!INTEGER_PATTERN.test(trimmed)) fail_invalid(key, trimmed, max);
+  const value = Number(trimmed);
+  if (value > max) fail_invalid(key, trimmed, max);
+  return value;
+}
+function resolve_seed(environment = process.env) {
+  return resolve_bounded(environment, PORT_SEED_KEY, MAX_SEED);
+}
+function resolve_lane(environment = process.env) {
+  return resolve_bounded(environment, LANE_SEAT_KEY, MAX_LANE);
+}
+function resolve_offset(environment = process.env) {
+  return resolve_seed(environment) * SEED_LANE_MULTIPLIER + resolve_lane(environment);
+}
+function offset_from(base, environment) {
+  return base + resolve_offset(environment);
+}
+function resolve_development_port(environment = process.env) {
+  return offset_from(DEV_PORT_BASE, environment);
+}
+function resolve_preview_port(environment = process.env) {
+  return offset_from(PREVIEW_PORT_BASE, environment);
+}
+function resolve_project_directory(directory) {
+  const start = path9.resolve(directory);
+  let current = start;
+  while (!existsSync2(path9.join(current, PACKAGE_FILE_NAME))) {
+    const parent = path9.dirname(current);
+    if (parent === current) return start;
+    current = parent;
   }
   return current;
 }
-function edit_distance(source, target) {
-  let previous = Array.from({ length: target.length + 1 }, (_unused, index) => index);
-  for (let row = 1; row <= source.length; row++) {
-    previous = fill_distance_row(source, target, row, previous);
+function discard_loaded_keys(snapshot) {
+  for (const key of Object.keys(process.env)) {
+    if (!PROJECT_ENVIRONMENT_KEYS.has(key) && !Object.hasOwn(snapshot, key)) {
+      Reflect.deleteProperty(process.env, key);
+    }
   }
-  return at(previous, target.length);
 }
-function closest_command(input, commands) {
-  const within = commands.map((command) => ({ command, distance: edit_distance(input, command) })).filter((scored) => scored.distance <= MAX_SUGGESTION_DISTANCE).toSorted((left, right) => left.distance - right.distance);
-  return within[0]?.command;
-}
-var command_suggest = { closest_command, edit_distance };
-
-// ports/index.js
-var ENV_FILE_NAME = ".env";
+function load_environment_file(directory = process.cwd()) {
+  const file = path9.join(resolve_project_directory(directory), ENV_FILE_NAME);
+  if (!existsSync2(file)) return false;
+  const snapshot = { ...process.env };
+  process.loadEnvFile(file);
+  discard_loaded_keys(snapshot);
+  return true;
+}
+var ports = {
+  load_environment_file,
+  resolve_project_directory,
+  resolve_seed,
+  resolve_lane,
+  resolve_development_port,
+  resolve_preview_port
+};
 
 // scripts/josh/josh-command-types.ts
 var OPTIONAL_ENV_FILE_FLAGS = [`--env-file-if-exists=${ENV_FILE_NAME}`];
@@ -1250,6 +1421,10 @@ var TS_BUILD_INFO_FILE = ".tsbuildinfo";
 var CSPELL_CACHE_FILE = ".cspellcache";
 var ESLINT_EDIT_CACHE_FILE = ".eslintcache.edit";
 var ESLINT_RELATED_CACHE_FILE = ".eslintcache.related";
+var PRETTIER_CACHE_FILE = ".prettiercache";
+var PRETTIER_RELATED_CACHE_FILE = ".prettiercache.related";
+var CSPELL_COMMIT_CACHE_FILE = ".cspellcache.commit";
+var ESLINT_COMMIT_CACHE_FILE = ".eslintcache.commit";
 var ROOTED_JSON_PORTABILITY = "rooted-json";
 var ESLINT_CACHE_SPEC = {
   cache_file: ESLINT_CACHE_FILE,
@@ -1272,7 +1447,11 @@ var GATE_CACHE_FILES = GATE_CACHE_SPECS.map((spec) => spec.cache_file);
 var IGNORED_CACHE_FILES = [
   ...GATE_CACHE_FILES,
   ESLINT_EDIT_CACHE_FILE,
-  ESLINT_RELATED_CACHE_FILE
+  ESLINT_RELATED_CACHE_FILE,
+  PRETTIER_CACHE_FILE,
+  PRETTIER_RELATED_CACHE_FILE,
+  CSPELL_COMMIT_CACHE_FILE,
+  ESLINT_COMMIT_CACHE_FILE
 ];
 var CONTENT_CACHE_FLAGS = ["--cache", "--cache-strategy", "content"];
 var CACHE_LOCATION_FLAG = "--cache-location";
@@ -1283,6 +1462,10 @@ var ESLINT_CACHE_FLAGS = content_cache_flags(ESLINT_CACHE_FILE);
 var ESLINT_EDIT_CACHE_FLAGS = content_cache_flags(ESLINT_EDIT_CACHE_FILE);
 var ESLINT_RELATED_CACHE_FLAGS = content_cache_flags(ESLINT_RELATED_CACHE_FILE);
 var CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE);
+var PRETTIER_CACHE_FLAGS = content_cache_flags(PRETTIER_CACHE_FILE);
+var PRETTIER_RELATED_CACHE_FLAGS = content_cache_flags(PRETTIER_RELATED_CACHE_FILE);
+var CSPELL_COMMIT_CACHE_FLAGS = content_cache_flags(CSPELL_COMMIT_CACHE_FILE);
+var ESLINT_COMMIT_CACHE_FLAGS = content_cache_flags(ESLINT_COMMIT_CACHE_FILE);
 
 // scripts/josh/josh-commands-backlog.ts
 var BACKLOG_COMMANDS = {
@@ -1546,6 +1729,14 @@ var LANE_COMMANDS = {
     category: "AI tools",
     reference: ["<issue>", "developer", ["files", "git", "processes", "network"]]
   },
+  // `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+  "lane:withdraw": {
+    script: "scripts/lane/lane-withdraw-cli.ts",
+    tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+    description: "Stop a running lane child, stash its uncommitted work, close its issue as not planned and close the lane \u2014 booked withdrawn, not as an outage or a failure",
+    category: "AI tools",
+    reference: ["<issue> --reason <text>", "developer", ["files", "git", "processes", "network"]]
+  },
   // A live run's lane limit: `.env` is read so the bare form reports the
   // `JOSH_LANE_LIMIT` a person set there when no override stands.
   "lane:limit": {
@@ -1566,7 +1757,7 @@ var LANE_COMMANDS = {
   },
   "lane:stats": {
     ...MEASURE_ARGUMENTS,
-    description: "Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, and the wait after each ship stop reason under those",
+    description: "Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, the wait after each ship stop reason under those, and the duration and reuse count of each gate check last",
     category: "AI tools",
     reference: ["--period <days> [--limit <lane-limit>]", "maintainer", ["none"]],
     default_script_arguments: ["stats"]
@@ -1772,6 +1963,15 @@ var AI_COMMANDS = {
     category: "AI tools",
     reference: ["(--cut | --over <tokens-per-request>) [--path <dir>]", "automation", ["none"]]
   },
+  "cost:audit": {
+    script: "scripts/cost-audit/cost-audit-cli.ts",
+    description: "Report AI cost over a period by session kind, tool category and guard, with cost per merge and regressions against the period before",
+    category: "AI tools",
+    reference: ["[--period <days>]", "maintainer", ["none"]],
+    // Kit-only: it reads kit's own transcript store, like `josh retrospective`, which carries its
+    // summary line.
+    is_kit_only: true
+  },
   ...DOCUMENT_COMMANDS,
   time: {
     script: "scripts/time/time-cli.ts",
@@ -1799,6 +1999,8 @@ var AI_COMMANDS = {
     description: "Aggregate a finished run's cost, review findings, observation ledger and events into one digest",
     category: "AI tools",
     reference: ["", "maintainer", ["none"]],
+    core_weight: core_budget.CORE_WEIGHTS.retrospective,
+    memory_mb: core_budget.MEMORY_MB.retrospective,
     // Kit-only: it reads kit's own development run — the transcript store, the review ledger and the
     // run event stream — so it means nothing in a consumer project and is dropped from a consumer's
     // help, through the same declaration `josh time` uses for the same reason.
@@ -2000,6 +2202,7 @@ var TYPE_CHECK_LABEL = "check";
 var UNIT_LABEL = "test:unit";
 var BEHAVIOR_LABEL = "behavior";
 var METRICS_LABEL = "metrics";
+var EXPORTS_LABEL = "exports";
 var WARNING_CHECKER_LABELS = [LINT_LABEL, TYPE_CHECK_LABEL];
 var STATIC_CHECKS = [
   {
@@ -2025,7 +2228,7 @@ var STATIC_CHECKS = [
   // program and walks it for about 5s, and it is over well before lint and the type check. A
   // reservation would only take a place from the four-core CI runner's fan-out and a worker from the
   // unit suite for the whole gate.
-  { label: "exports", target: "exports:unused", reserved_cores: 0 },
+  { label: EXPORTS_LABEL, target: "exports:unused", reserved_cores: 0 },
   // **The metrics ratchet is kit's own**: it holds kit's repository-wide
   // totals to the merge-base's. It is one in-process eslint pass with only `max-lines` enabled, over
   // in a few seconds, so it reserves no core for the reason the unused-member check above does not.
@@ -2114,6 +2317,15 @@ function resolve_gate_plan(available_cores = availableParallelism4(), concurrent
     unit_worker_cap: unit_cap_for(checks, available_cores, concurrent_runs)
   };
 }
+function bound_by_free(plan, available_cores, free_cores) {
+  if (!has_unit_check(plan.checks)) return plan;
+  const unit_worker_cap = unit_worker_share.cap_to_free(
+    plan.unit_worker_cap,
+    free_cores,
+    available_cores
+  );
+  return { ...plan, unit_worker_cap };
+}
 function format_machine(available_cores, concurrent_runs) {
   const cores = `${String(available_cores)} cores`;
   if (concurrent_runs <= unit_worker_share.SOLO_RUNS) return cores;
@@ -2132,6 +2344,7 @@ function format_gate_plan(plan, available_cores = availableParallelism4(), concu
   return `${josh_verdict.GATE_OPENING_PREFIX}${width}, ${cap} (${machine})`;
 }
 var gate_plan = {
+  EXPORTS_LABEL,
   GATE_CHECKS,
   LINT_LABEL,
   MEASURED_CORES,
@@ -2141,6 +2354,7 @@ var gate_plan = {
   TYPE_CHECK_LABEL,
   UNIT_LABEL,
   WARNING_CHECKER_LABELS,
+  bound_by_free,
   check_memory,
   check_weight,
   direct_unit_memory,
@@ -2273,7 +2487,7 @@ var DEV_COMMANDS = {
   },
   "stop:guard": {
     script: "scripts/hooks/stop-guard.ts",
-    description: "Claude Code Stop hook: deliver the three stop-time rules \u2014 hold notify/release and issue citation (reads the Stop payload on stdin)",
+    description: "Claude Code Stop hook: send the hold notify, release the hold and print the issue citations itself; block on the rules that need the model (reads the Stop payload on stdin)",
     category: "Development",
     reference: ["", "automation", ["none"]]
     // **No `tsx_arguments`, deliberately**, the same as `pretool:guard` above: this runs at every
@@ -2407,6 +2621,12 @@ var HOOKS_COMMANDS = {
     category: "Git hooks",
     reference: ["[paths...]", "automation", ["none"]]
   },
+  "pre-commit-lint": {
+    script: "scripts/hooks/pre-commit-lint.ts",
+    description: "Git hook: run cspell, prettier or eslint over staged files from a content cache",
+    category: "Git hooks",
+    reference: ["<cspell|prettier|eslint> [paths...]", "automation", ["files"]]
+  },
   "pre-push-unit": {
     script: "scripts/hooks/pre-push-unit.ts",
     description: "Git hook: run unit tests, reusing a green gate recorded on the pushed tree",
@@ -2812,6 +3032,11 @@ var WORKFLOW_COMMANDS = {
   // A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
   // the caller's git configuration: a bare `git pull` aborts with `Need to specify how to reconcile
   // divergent branches` on exactly the diverged branch the command exists for.
+  //
+  // **It declares no core weight, by measurement** (joshuafolkken/kit#3944): its own work is git, and
+  // the catalog it may regenerate took 0.6s of CPU. The heavy processes seen beside it are commit
+  // hooks — its regenerated catalog's commit runs them — which reserve themselves, and a weight here
+  // would set the held mark they inherit, folding the parallel hook tools into this one place.
   "main:merge": {
     script: "scripts/git/main-merge.ts",
     description: "Merge origin default branch into the current branch",
@@ -2887,6 +3112,7 @@ var ALIASES = {
   tm: "time",
   tmd: "time:density",
   rtr: "retrospective",
+  ca: "cost:audit",
   rvf: "review:findings",
   ruv: "rule:value",
   ev: "eval",
@@ -2896,73 +3122,1685 @@ var ALIASES = {
   lst: "lane:stats",
   lli: "lane:limit",
   lrs: "lane:restart",
+  lwd: "lane:withdraw",
   blr: "backlogrun"
 };
-
-// scripts/josh/josh-composite-arguments.ts
-var SHELL_INTERPRETERS = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash"]);
-var SHELL_COMMAND_FLAG = "-c";
-var PATH_SEPARATOR = "/";
-var USAGE_ERROR_EXIT_CODE = 1;
-function is_shell_interpreter(executable) {
-  return SHELL_INTERPRETERS.has(executable.split(PATH_SEPARATOR).at(-1) ?? executable);
-}
-function is_composite_shell(shell) {
-  const [executable, flag] = shell ?? [];
-  if (executable === void 0) return false;
-  return is_shell_interpreter(executable) && flag === SHELL_COMMAND_FLAG;
-}
-function format_targets(targets) {
-  return targets.map((target) => `josh ${target}`).join(" or ");
-}
-function format_rejection(cmd, targets) {
-  const hint = targets.length > 0 ? `pass them to ${format_targets(targets)} instead` : "it runs a fixed sequence and forwards nothing";
-  return `josh ${cmd} takes no extra arguments \u2014 ${hint}`;
-}
-function reject_extra_arguments(cmd, entry, extra) {
-  if (extra.length === 0 || !is_composite_shell(entry.shell)) return void 0;
-  return format_rejection(cmd, entry.argument_targets ?? []);
+function canonical_command(name) {
+  if (!Object.hasOwn(ALIASES, name)) return name;
+  return ALIASES[name] ?? name;
 }
-var composite_arguments = { format_rejection, is_composite_shell, reject_extra_arguments };
 
-// scripts/josh/josh-in-process.ts
-import { realpathSync } from "node:fs";
-import path9 from "node:path";
-import { pathToFileURL } from "node:url";
-var TYPESCRIPT_EXTENSION = ".ts";
-var JAVASCRIPT_EXTENSION = ".js";
-var BUNDLED_COMMAND_DIRECTORY = path9.join("dist", "commands");
-var FAILURE_EXIT_CODE = 1;
-function is_typescript_dispatcher(dispatcher_url) {
-  return dispatcher_url.endsWith(TYPESCRIPT_EXTENSION);
-}
-function bundled_script_path(package_directory, script) {
-  const name = `${path9.basename(script, TYPESCRIPT_EXTENSION)}${JAVASCRIPT_EXTENSION}`;
-  return path9.join(package_directory, BUNDLED_COMMAND_DIRECTORY, name);
-}
-function in_process_target(entry, package_directory, dispatcher_url) {
-  if (entry.script === void 0 || entry.tsx_arguments !== void 0) return void 0;
-  if (is_typescript_dispatcher(dispatcher_url)) return path9.join(package_directory, entry.script);
-  return entry.is_bundled === true ? bundled_script_path(package_directory, entry.script) : void 0;
-}
-function read_exit_code() {
-  const code = process.exitCode;
-  return typeof code === "number" ? code : 0;
-}
-function resolve_real_path(script_path) {
-  try {
-    return realpathSync(script_path);
-  } catch {
-    return script_path;
-  }
-}
-async function run_in_process(script_path, script_arguments) {
-  const resolved_path = resolve_real_path(script_path);
-  process.argv = [process.execPath, resolved_path, ...script_arguments];
-  try {
-    await import(pathToFileURL(resolved_path).href);
-  } catch (error) {
-    console.error(error);
+// scripts/josh/josh-usage-automation.ts
+var STAGED = "--staged";
+var JSON_FLAG = "--json";
+var BRANCH_DIFF = "the branch diff";
+var STAGED_DIFF = "the staged diff instead";
+var PR_NUMBER = "42";
+var DRY_RUN = "--dry-run";
+var SKIP_PUBLISH_WAIT = "--skip-publish-wait";
+var AUTOMATION_USAGE = {
+  "refactor:scan": { examples: [{ arguments: "" }] },
+  "time:density": {
+    examples: [{ arguments: "" }, { arguments: "--lanes 5", note: "the five most recent lanes" }],
+    flags: [
+      {
+        names: ["--lanes <n>"],
+        description: "average over a different count of recent qualifying lanes (default 10)."
+      },
+      {
+        names: ["--path <dir>"],
+        description: "read another project's lane transcripts, as `josh time` does. Run it from the main checkout \u2014 a lane reads only its own transcript."
+      }
+    ]
+  },
+  "e2e:retry-check": { examples: [{ arguments: "" }] },
+  "sync:scope": {
+    examples: [
+      { arguments: "", note: BRANCH_DIFF },
+      { arguments: STAGED, note: STAGED_DIFF },
+      { arguments: JSON_FLAG, note: '{"scope":"managed","reason":"..."}' }
+    ],
+    flags: [
+      { names: [STAGED], description: "inspect the staged diff instead of the branch diff." },
+      { names: [JSON_FLAG], description: 'emit `{"scope","reason"}` as JSON.' }
+    ]
+  },
+  "dogfood:commit": { examples: [{ arguments: "~/Development/kit-test-html-start" }] },
+  "fresh:run": {
+    examples: [
+      { arguments: "--list", note: "kit's six patterns" },
+      { arguments: "kit-test-html-init", note: "one pattern, the packed checkout" },
+      {
+        arguments: "kit-test-html-start",
+        note: "a GitHub pattern, the latest published version"
+      },
+      { arguments: "--spec fresh/html-init.json", note: "a scenario another toolkit wrote" }
+    ],
+    flags: [
+      { names: ["--list"], description: "print the pattern names and run nothing." },
+      {
+        names: ["--spec <file.json>"],
+        description: "run the scenario in this file instead of a named pattern; the path is relative to the project root."
+      },
+      {
+        names: ["--package-version <version>"],
+        description: "the published version a `package_source: published` scenario installs. Default: the registry's latest version of the package the command is run from."
+      },
+      {
+        names: ["--log-dir <dir>"],
+        description: "where the log is written. Default: `.claude/tmp/fresh-machine`."
+      },
+      { names: ["--rebuild"], description: "build the machine image without the layer cache." }
+    ]
+  },
+  "auth:setup": {
+    examples: [
+      { arguments: "", note: "sign in and save the token" },
+      { arguments: "--check", note: "ok: \u2026 saved on <date>, or missing: \u2026 and exit 1" }
+    ]
+  },
+  "sonar:hotspots": { examples: [{ arguments: PR_NUMBER }] },
+  "sonar:new-code": { examples: [{ arguments: PR_NUMBER }] },
+  "ui:routes": {
+    examples: [
+      { arguments: "", note: BRANCH_DIFF },
+      { arguments: STAGED, note: STAGED_DIFF }
+    ]
+  },
+  propagate: {
+    examples: [
+      { arguments: "" },
+      { arguments: DRY_RUN, note: "report targets and steps, write nothing" },
+      { arguments: SKIP_PUBLISH_WAIT, note: "release already known to be published" },
+      { arguments: "--target app-kit", note: "carry the release into one consumer only" }
+    ],
+    flags: [
+      {
+        names: [DRY_RUN],
+        description: "report targets and steps without writing; skips the publish wait, opens no issues."
+      },
+      {
+        names: [SKIP_PUBLISH_WAIT],
+        description: "skip the registry poll for an already-published release."
+      },
+      {
+        names: ["--target <repo>"],
+        description: "process only that consumer (`app-kit` or `joshuafolkken/app-kit`); the rest are reported `skipped` and left untouched. An unknown, ambiguous or non-dependent name fails before the publish wait, writing nothing."
+      }
+    ]
+  },
+  "repo:party": {
+    examples: [
+      { arguments: "joshuafolkken/kit", note: "\u2192 first-party (in the kit session)" },
+      { arguments: "sveltejs/kit", note: "\u2192 third-party" },
+      { arguments: "", note: "no argument: the session's own repository" }
+    ]
+  }
+};
+
+// scripts/josh/josh-usage-backlog.ts
+var EXCLUDE = "--exclude <N>";
+var BUDGET = '--answer candidates --started "$started" --active "$active"';
+var REPO = "--repo <owner/repo>";
+var JUST_MERGED = "skip the issue just merged";
+var EXCLUDE_1630 = "--exclude 1630";
+var BACKLOG_USAGE = {
+  epic: {
+    examples: [
+      { arguments: '"Epic: split the parser work" 101 102 103' },
+      { arguments: '"Epic: staged rollout" 101 102 --ordered' },
+      { arguments: '"Epic: ..." 101 102 --rationale-file rationale.md' },
+      { arguments: "--promote 858 101 102 103", note: "turn an existing issue into an epic" },
+      { arguments: "--add 893 894", note: "track #894, declaring no order for it" },
+      { arguments: "--add 893 894 --before 891", note: "#894 must finish before #891" },
+      { arguments: "--add 893 894 --after 890", note: "#894 starts once #890 is done" },
+      { arguments: "--add 893 894 --decision-file why.md", note: "\u2026and record why, in one call" },
+      {
+        arguments: "--reconcile 2184",
+        note: "rewrite the body to match the recorded blocked-by, and record any order the body declared"
+      }
+    ],
+    flags: [
+      {
+        names: ["--ordered"],
+        description: "argument order is the dependency order; writes the arrow chain, records the matching `blocked-by` relations, and adds a `### Declared order` entry under `## Decisions`."
+      },
+      {
+        names: ["--rationale-file <path|->"],
+        description: "split rationale prose (`-` reads stdin)."
+      },
+      {
+        names: ["--origin <owner/repo#N>"],
+        description: "backlink when the split originated in another repository."
+      },
+      {
+        names: ["--before <M>"],
+        description: "with `--add`: insert before `#M`, re-pointing what `#M` was waiting on so the chain is never broken."
+      },
+      {
+        names: ["--after <M>"],
+        description: "with `--add`: start after `#M`; branches when `#M` already has a successor, extends when it is a tail."
+      },
+      {
+        names: ["--order-before <M>", "--order-after <M>"],
+        description: "with `--add`: move the task-list row only; write no `blocked-by` relation."
+      },
+      {
+        names: ["--decision-file <path|->"],
+        description: "with `--add`: record why the child was placed."
+      },
+      {
+        names: ["--remove <E> <M> <N> [<N2> \u2026]"],
+        description: "delete a declared order from the body and the relations; each consecutive pair is one link."
+      }
+    ]
+  },
+  "epic:next": {
+    examples: [
+      { arguments: "858" },
+      { arguments: "858 --repo joshuafolkken/kit", note: "just the next child for one repository" },
+      { arguments: "858 --repo joshuafolkken/kit --lanes", note: "one child per free lane there" }
+    ],
+    flags: [
+      {
+        names: [REPO],
+        description: "answer for one repository; stdout carries one token (an issue number, or `wait`/`stop`/`complete`), everything else on stderr."
+      },
+      {
+        names: ["--lanes"],
+        description: "print one issue number per free lane (requires `--repo`); `JOSH_LANE_LIMIT` sets the ceiling, default 4. Prints `triage` instead while any candidate carries neither `run:solo` nor `run:lane` (the triage gate in `josh backlog:next`)."
+      }
+    ]
+  },
+  "epic:bundle": { examples: [{ arguments: "874" }] },
+  "epic:audit": { examples: [{ arguments: "858" }] },
+  "epic:check": { examples: [{ arguments: "700" }] },
+  "auto-ok:next": {
+    examples: [{ arguments: "" }, { arguments: "--exclude 906", note: JUST_MERGED }],
+    flags: [
+      {
+        names: [EXCLUDE],
+        description: "drop issues from the answer; comma-separated, repeatable."
+      }
+    ]
+  },
+  "auto-ok:judge": {
+    examples: [
+      { arguments: "", note: "the issues that still owe a judgement" },
+      { arguments: "--apply 912 --lane", note: "opt it in, with its run label" },
+      { arguments: '--decline 913 --reason "<why>"', note: "record why it stays out" }
+    ],
+    flags: [
+      {
+        names: ["--apply <N> --lane|--solo"],
+        description: "checks the exclusions again against the labels as they stand, applies the run label and then `auto-ok`, and notes it on the progress board."
+      },
+      { names: ["--decline <N> --reason <text>"], description: "applies nothing." }
+    ]
+  },
+  "backlog:next": {
+    examples: [{ arguments: "" }, { arguments: EXCLUDE_1630, note: JUST_MERGED }],
+    flags: [
+      {
+        names: [EXCLUDE],
+        description: "drop issues from every bucket; comma-separated, repeatable."
+      }
+    ]
+  },
+  "backlog:plan": {
+    examples: [
+      { arguments: "" },
+      { arguments: EXCLUDE_1630, note: "after #1630 merged" },
+      { arguments: "--waves", note: "the run order, wave by wave" }
+    ],
+    flags: [
+      { names: [EXCLUDE], description: "same exclusion as `backlog:next`." },
+      {
+        names: ["--waves"],
+        description: "print the order the run takes, wave by wave, assuming each wave merges before the next. Read-only."
+      }
+    ]
+  },
+  "backlog:stalled": { examples: [{ arguments: "" }] },
+  "backlog:budget": {
+    examples: [
+      { arguments: BUDGET },
+      { arguments: '--answer exhausted --started "$started" --active "$active" --idle 60' },
+      { arguments: `${BUDGET} --merged 3 --running 2 --max 5` }
+    ],
+    flags: [
+      {
+        names: ["--answer <candidates|exhausted|blocked|parked|unreadable|untriaged>"],
+        description: "`backlog:next`'s answer, mapped."
+      },
+      {
+        names: ["--started", "--active"],
+        description: "when the invocation began / when it last had work (required unless the watch is off)."
+      },
+      {
+        names: ["--idle <minutes>"],
+        description: "once nothing can proceed, keep polling this long, counted from `--active` (default 480, 8 hours; `--idle 0` turns the watch off)."
+      },
+      {
+        names: ["--max <count>"],
+        description: "issues one invocation may take (default unlimited); `--merged` and `--running` count against it."
+      },
+      {
+        names: ["--json"],
+        description: 'collapse verdict and reason into `{"budget": "<verdict>", "reason": "\u2026"}`.'
+      }
+    ]
+  },
+  "backlog:offer": {
+    examples: [{ arguments: '--started "$started" --active "$active" --running 2 --retries 1' }]
+  },
+  "backlog:drive": {
+    examples: [{ arguments: '--owner "$PPID" [--max <n>] [--idle <minutes>] [--only]' }]
+  }
+};
+
+// scripts/josh/josh-usage-developer.ts
+var UNSEEDED = {};
+var NARROWED = { arguments: "scripts/thing.ts", note: "narrow by the given files instead" };
+var DEVELOPER_USAGE = {
+  gate: {
+    examples: [
+      { arguments: "" },
+      { arguments: "--verbose", note: "every check's output, passing ones included" },
+      { arguments: "--force", note: "re-run even on a tree already recorded green" },
+      { arguments: "--no-unit", note: "the static checks only (CI only)" }
+    ]
+  },
+  lint: { examples: [{ arguments: "" }] },
+  "lint:related": { examples: [{ arguments: "" }, NARROWED] },
+  lines: {
+    examples: [{ arguments: "scripts/hooks/format-edited-file.ts scripts/josh/josh-logic.ts" }]
+  },
+  bytes: {
+    examples: [
+      { arguments: "docs/josh-commands.md", note: "one document" },
+      { arguments: "", note: "scan: every budgeted document near its ceiling" }
+    ]
+  },
+  metrics: {
+    examples: [
+      { arguments: "", note: "print the totals and check them against the merge-base's" },
+      { arguments: '--accept --reason "<why>"', note: "record this branch's growth and why" }
+    ]
+  },
+  format: { examples: [{ arguments: "" }] },
+  "cspell:dot": { examples: [{ arguments: "", note: "includes dotfiles" }] },
+  behavior: { examples: [{ arguments: "" }] },
+  "exports:unused": { examples: [{ arguments: "" }] },
+  "test:unit": { examples: [{ arguments: "" }] },
+  "test:related": {
+    examples: [
+      { arguments: "" },
+      NARROWED,
+      { arguments: "--silent", note: "flags are forwarded to vitest" }
+    ]
+  },
+  "test:declared": {
+    examples: [
+      { arguments: "" },
+      { arguments: "--match", note: "check Step 0 declarations on stdin" },
+      { arguments: "--help", note: "print usage, including the --match stdin form" }
+    ]
+  },
+  "test:e2e": { examples: [{ arguments: "" }] },
+  test: { examples: [{ arguments: "" }] },
+  check: { examples: [{ arguments: "" }] },
+  port: {
+    examples: [
+      {
+        arguments: "dev",
+        note: `${String(ports.resolve_development_port(UNSEEDED))} with no seed set`
+      },
+      {
+        arguments: "preview",
+        note: `${String(ports.resolve_preview_port(UNSEEDED))} with no seed set`
+      }
+    ]
+  },
+  profile: { examples: [{ arguments: "" }] },
+  init: {
+    examples: [
+      {
+        arguments: "",
+        note: "create/merge config files, install and format (--no-install skips both, --dry-run only prints the plan)"
+      }
+    ]
+  },
+  "registry:migrate": { examples: [{ arguments: "" }] },
+  sync: { examples: [{ arguments: "", note: "overwrite managed files" }] },
+  uninstall: {
+    examples: [
+      { arguments: "", note: "show the plan, then ask" },
+      { arguments: "--yes", note: "remove without asking" }
+    ]
+  },
+  adopt: {
+    examples: [
+      { arguments: "" },
+      { arguments: "--dry-run", note: "report the steps without touching anything" }
+    ],
+    flags: [{ names: ["--dry-run"], description: "report the plan without writing." }]
+  },
+  git: {
+    examples: [
+      { arguments: "", note: "interactive" },
+      { arguments: "-y", note: "unattended (no TTY required)" },
+      { arguments: '-y "title"', note: "set commit message prefix" },
+      { arguments: '-y "<title> #<N>"', note: "follow-up commit on the same branch" },
+      {
+        arguments: "-y --skip-commit --skip-push",
+        note: "open the PR without committing/pushing"
+      }
+    ],
+    flags: [
+      {
+        names: ["-y", "--yes"],
+        description: "run non-interactively; works without a TTY (agent or CI shell)."
+      },
+      {
+        names: ["--skip-commit", "--skip-push"],
+        description: "recover/open a PR without a new commit or push."
+      }
+    ]
+  },
+  pr: { examples: [{ arguments: "", note: "open the PR for the current <N>-<slug> branch" }] },
+  "review:findings": { examples: [{ arguments: "" }] },
+  "main:sync": { examples: [{ arguments: "" }] },
+  "main:merge": { examples: [{ arguments: "" }] },
+  version: {
+    examples: [
+      { arguments: "" },
+      {
+        arguments: "--upgrade",
+        note: "upgrade global + project to latest, then re-run fix-gh-packages"
+      }
+    ],
+    flags: [
+      {
+        names: ["--upgrade"],
+        description: "upgrade both the global install (`pnpm add -g`) and the project devDependency (`pnpm add -D` + `fix-gh-packages`); already-current or not-installed targets are skipped."
+      }
+    ]
+  },
+  ranges: { examples: [{ arguments: "" }] },
+  doctor: {
+    examples: [
+      { arguments: "", note: "diagnose only" },
+      { arguments: "--fix", note: "reclaim the global josh by removing a stale kit shim" },
+      { arguments: "--ports", note: "also print the per-repository port-seed table" }
+    ],
+    flags: [
+      {
+        names: ["--fix"],
+        description: "remove a shadowing binary **only if it is a kit shim** (its body references `@joshuafolkken/kit` or the removed `install-bin` script); any other binary is left and reported for manual review. Also the one-shot recovery for an old project that re-created the global shim."
+      },
+      { names: ["--ports"], description: "additionally print the port-seed table (see below)." }
+    ]
+  },
+  audit: { examples: [{ arguments: "" }] },
+  overrides: {
+    examples: [
+      { arguments: "", note: "verify overrides unchanged" },
+      { arguments: "--save", note: "snapshot current merged overrides" }
+    ],
+    flags: [
+      {
+        names: ["--save"],
+        description: "write the current merged overrides to `.overrides-snapshot.json` (gitignored); later runs compare against it and exit non-zero on any add, removal, or change."
+      }
+    ]
+  },
+  backlogrun: {
+    examples: [
+      { arguments: "", note: "start in Claude, then show the board" },
+      { arguments: "3437 --only", note: "the arguments go to backlogrun as typed" },
+      { arguments: "--agent codex", note: "start in Codex" },
+      { arguments: "--stop", note: "stop the run in this repository" }
+    ]
+  },
+  "lane:limit": {
+    examples: [
+      { arguments: "8", note: "raise or lower the live run's limit to 8" },
+      { arguments: "", note: "print the limit, the lanes in use and the free lanes" },
+      { arguments: "--reset", note: "clear the override; JOSH_LANE_LIMIT applies again" }
+    ]
+  },
+  "lane:withdraw": {
+    examples: [{ arguments: '3769 --reason "folded into a broader issue"' }]
+  },
+  "test:red": { examples: [{ arguments: "", note: "red, green, no-test or test-only" }] },
+  start: {
+    examples: [
+      { arguments: "", note: "asks for the profile and the repository" },
+      {
+        arguments: "--yes --github --profile basic",
+        note: "unattended, including the GitHub repository"
+      }
+    ],
+    flags: [
+      { names: ["--profile basic|full"], description: "the profile, without asking." },
+      { names: ["--yes"], description: "take the defaults \u2014 not consent to write to GitHub." },
+      { names: ["--github"], description: "create the GitHub repository and push `main`." },
+      { names: ["--public"], description: "create the repository public instead of private." },
+      {
+        names: ['--init-command "<command>"'],
+        description: "run this setup command in place of `josh init`."
+      },
+      {
+        names: ['--push-preflight-command "<command>"'],
+        description: "a check run before the first step when the plan pushes; a failure stops the run before it writes anything."
+      },
+      { names: ["--dry-run"], description: "print the plan and change nothing." }
+    ]
+  },
+  latest: { examples: [{ arguments: "", note: "full update (update + audit + pnpm)" }] },
+  "latest:corepack": { examples: [{ arguments: "", note: "update pnpm only" }] },
+  "latest:update": { examples: [{ arguments: "", note: "update dependencies only" }] },
+  "lane:restart": {
+    examples: [{ arguments: "3769", note: "prints the fresh child's pid" }]
+  },
+  "rule:value": {
+    examples: [
+      { arguments: "" },
+      {
+        arguments: "--refresh",
+        note: "write the reading to the loop-head cache instead of stdout"
+      }
+    ]
+  }
+};
+
+// scripts/josh/josh-usage-hooks.ts
+var PRE_TOOL_USE = "run by the PreToolUse hook, the pending tool call as JSON on stdin";
+var IN_PRETOOL_GUARD = "run inside pretool:guard, not wired on its own";
+var HOOK_USAGE = {
+  "format:edited": {
+    examples: [
+      { arguments: "", note: "run by the PostToolUse hook, the tool call as JSON on stdin" }
+    ]
+  },
+  "batch:guard": { examples: [{ arguments: "", note: IN_PRETOOL_GUARD }] },
+  "investigation:guard": { examples: [{ arguments: "", note: PRE_TOOL_USE }] },
+  "duplicate-read:guard": { examples: [{ arguments: "", note: IN_PRETOOL_GUARD }] },
+  "rule:guard": { examples: [{ arguments: "", note: PRE_TOOL_USE }] },
+  "rule:list": { examples: [{ arguments: "", note: "print every trigger-delivered rule" }] },
+  "pretool:guard": { examples: [{ arguments: "", note: PRE_TOOL_USE }] },
+  "codex:hook-adapter": {
+    examples: [
+      { arguments: "pretool", note: "a Codex PreToolUse payload on stdin" },
+      { arguments: "posttool", note: "a Codex PostToolUse payload on stdin" }
+    ]
+  },
+  "stop:guard": {
+    examples: [{ arguments: "", note: "run by the Stop hook, the stop payload as JSON on stdin" }]
+  },
+  "session:lang": {
+    examples: [{ arguments: "", note: "run by the UserPromptSubmit hook; `ja` prints nothing" }]
+  }
+};
+
+// scripts/josh/josh-usage-issue.ts
+var REPO2 = "--repo <owner/repo>";
+var BODY_FILE = "--body-file <path>";
+var CONCURRENT = "several numbers, read concurrently";
+var REPO_FLAG = {
+  names: [REPO2],
+  description: "read a child in another repository; applies to every number."
+};
+var JSON_FLAG2 = { names: ["--json"], description: "print the verdict and reason as JSON." };
+var ISSUE_USAGE = {
+  "issue:read": {
+    examples: [{ arguments: "1715" }, { arguments: "1715 1567 1605", note: CONCURRENT }]
+  },
+  "issue:ack": { examples: [{ arguments: "3773" }] },
+  "issue:state": {
+    examples: [
+      { arguments: "42", note: "single-number shape" },
+      { arguments: "42 43 44", note: "each block headed by `issue:`" },
+      { arguments: "42 43 --repo joshuafolkken/app-kit", note: "a child in another repo" }
+    ],
+    flags: [REPO_FLAG]
+  },
+  "issue:release": {
+    examples: [
+      { arguments: "3360" },
+      { arguments: "3716 --wait", note: "blocked by the release issue instead" }
+    ],
+    flags: [
+      {
+        names: ["--wait"],
+        description: "the issue is blocked by the release issue instead, so `backlog:next` offers it again once the release ships (`.claude/skills/workflow-commands/prerequisite.md`)."
+      }
+    ]
+  },
+  "issue:scout": {
+    examples: [
+      { arguments: '"Stop the gate re-running after every edit"' },
+      { arguments: '"<title>" --body "parent: #1246"' },
+      { arguments: '"<title>" --body-file draft.md' }
+    ],
+    flags: [
+      {
+        names: ['--body "<text>"'],
+        description: "supply references (`#N`) in a `parent: #N` line or an acceptance-criteria section so the epic half has a number to work from; without one there (a background mention does not count) it prints `Epic: not asked`."
+      },
+      {
+        names: [BODY_FILE],
+        description: 'pass the whole draft, including its purpose, requirements and acceptance criteria. A file that cannot be read ends the command rather than being treated as "no candidates".'
+      }
+    ]
+  },
+  "issue:file": {
+    examples: [
+      { arguments: '"<title>" --body-file body.md --depth 1' },
+      {
+        arguments: '"<title>" --body-file body.md --depth 0 --route tier-a --repo joshuafolkken/kit'
+      },
+      { arguments: '"<title>" --body-file body.md --depth 1 --distinct 2801,2795' }
+    ],
+    flags: [
+      { names: [BODY_FILE], description: "the body. Required." },
+      {
+        names: ["--depth <0|1|2>"],
+        description: 'the depth label. Required. The criteria are `.claude/skills/workflow-commands/observation-filing.md` \u2192 "The depth test".'
+      },
+      {
+        names: ["--route <tier-a|split|interrupt|review-cap>"],
+        description: "the `route:` label naming the filing route. Omit it for a filing with no route."
+      },
+      {
+        names: ["--label <name>"],
+        description: "an extra label (for example `epic`). Repeatable."
+      },
+      {
+        names: [REPO2],
+        description: "the target repository. Defaults to this repository."
+      },
+      {
+        names: ["--distinct <N,\u2026>"],
+        description: "duplicate candidates you read and judged distinct."
+      },
+      {
+        names: ["--over-cap"],
+        description: "the run is blocked by this filing; the cap lets it through."
+      },
+      {
+        names: ["--no-auto-ok"],
+        description: "needs a person's judgement (Tier B / C); no `auto-ok`."
+      },
+      {
+        names: ["--release"],
+        description: "a consumer can use the change only once it is published. The filed issue becomes a blocker of the target's release issue (step 10)."
+      }
+    ]
+  },
+  "issue:fold-existing": { examples: [{ arguments: "assessment.json --json" }] },
+  "issue:fold": {
+    examples: [
+      {
+        arguments: '"First finding" "Second finding"',
+        note: "fold | separate | no-fold-needed | undetermined"
+      },
+      { arguments: '"a" "b" --not-separable', note: "the pair is really one deliverable \u2192 fold" },
+      { arguments: '"a" "b" --json', note: "the verdict and reason, machine-readable" }
+    ],
+    flags: [
+      {
+        names: ["--not-separable"],
+        description: "declare the judgement half: the findings are one deliverable, so they fold whatever their size."
+      },
+      JSON_FLAG2
+    ]
+  },
+  "issue:cite": {
+    examples: [
+      { arguments: "2220" },
+      { arguments: "2220 1758 1252", note: CONCURRENT },
+      { arguments: "45 --repo joshuafolkken/app-kit", note: "bare numbers in another repository" },
+      { arguments: "joshuafolkken/app-kit#45 2220", note: "per-token owner/repo#N notation" }
+    ],
+    flags: [
+      {
+        names: [REPO2],
+        description: "the repository for every bare number; a token written `owner/repo#N` overrides it for itself."
+      }
+    ]
+  },
+  "issue:comment": {
+    examples: [
+      {
+        arguments: "2304 --body-file .claude/tmp/park.md",
+        note: "the body from a file \u2014 no shell evaluates it"
+      },
+      {
+        arguments: '2304 --body "a short note"',
+        note: "inline, for a body with no backticks or $"
+      }
+    ],
+    flags: [
+      {
+        names: ["--body <text>"],
+        description: "the comment body, inline. Trimmed, with `\\n` expanded to a newline."
+      },
+      {
+        names: [BODY_FILE],
+        description: "read the body from a file, or from stdin with `-`. The safe form the rule steers every caller toward."
+      }
+    ]
+  },
+  "pkg:scout": {
+    examples: [{ arguments: '"date formatting" --size 5' }],
+    flags: [
+      { names: ["--size <n>"], description: "how many candidates to fetch and rank (default 10)." }
+    ]
+  },
+  "issue:lint": { examples: [{ arguments: ".claude/tmp/issue-body.md" }] },
+  "defect:rate": {
+    examples: [{ arguments: "", note: "the last 14 days" }, { arguments: "--days 30" }],
+    flags: [
+      {
+        names: ["--days <n>"],
+        description: "the window in whole days (default 14, at most 3650). Anything else prints the usage and exits 1."
+      }
+    ]
+  },
+  "issue:backlinks": { examples: [{ arguments: "2123" }] },
+  "report:lint": { examples: [{ arguments: "< summary.md" }] },
+  "stash:pop": {
+    examples: [
+      { arguments: '"backlogrun: parked #2028"' },
+      {
+        arguments: '"backlogrun: josh latest before lanes" --dir "$dir"',
+        note: "into a lane's work tree"
+      }
+    ],
+    flags: [
+      {
+        names: ["--dir <path>"],
+        description: "applies the pop in that work tree (`git -C <path>`); without it the pop lands in the current checkout. The stack is shared, so it reads the same either way."
+      }
+    ]
+  }
+};
+
+// scripts/josh/josh-usage-review.ts
+var MACHINE_READABLE = "the verdict and the reason, machine-readable";
+var LEVEL_ONLY = "--level-only";
+var JSON_FLAG3 = "--json";
+var CHECK = "--check";
+var ROUND_1_CLOSED = "--round-1-closed";
+var REVIEW_USAGE = {
+  "review:brief": {
+    examples: [
+      { arguments: "", note: "round 1" },
+      { arguments: "--round 2", note: "verification pass, scoped to the fix delta" },
+      { arguments: LEVEL_ONLY, note: "the level alone (pre-commit review)" },
+      { arguments: "--level-only --json", note: "level and reason, machine-readable" }
+    ],
+    flags: [
+      {
+        names: ["--round 2"],
+        description: "target is round 1's fixes and nothing else (widened back to the whole change when the record's change base no longer matches)."
+      },
+      {
+        names: [LEVEL_ONLY],
+        description: "print the level alone (level to stdout, reason to stderr); bypasses the scoped-green refusal."
+      },
+      {
+        names: ["--staged", "--json"],
+        description: "the staged diff; machine-readable level and reason."
+      }
+    ]
+  },
+  "review:round2": {
+    examples: [
+      { arguments: "", note: "\u2192 required" },
+      { arguments: ROUND_1_CLOSED, note: "\u2192 required | skip" },
+      { arguments: JSON_FLAG3, note: MACHINE_READABLE }
+    ],
+    flags: [
+      {
+        names: [ROUND_1_CLOSED],
+        description: "the caller states every round-1 High/Medium finding closed and none was filed or deferred; its absence answers `required`."
+      },
+      { names: [JSON_FLAG3], description: "machine-readable verdict and reason." }
+    ]
+  },
+  disposition: { examples: [{ arguments: "<path...>", note: "\u2192 runtime | non-runtime" }] },
+  "review:attest": {
+    examples: [
+      { arguments: "<nonce>", note: "run by the review, from the checkout it read" },
+      { arguments: CHECK, note: "run by the run, before it acts on the review" }
+    ],
+    flags: [
+      { names: ["<nonce>"], description: "attest the checkout the review read." },
+      {
+        names: [CHECK],
+        description: "verify before acting; `josh followup` asks again before merging."
+      }
+    ]
+  },
+  delegate: {
+    examples: [
+      { arguments: "gate-fix", note: "\u2192 delegate" },
+      { arguments: "review", note: "\u2192 keep" },
+      { arguments: "--list", note: "the enumeration, and what was rejected and why" }
+    ]
+  },
+  fanout: {
+    examples: [
+      { arguments: "scripts/a.ts,scripts/a.test.ts scripts/b.ts", note: "\u2192 parallel" },
+      {
+        arguments: "scripts/a.ts,shared.ts scripts/b.ts,shared.ts",
+        note: "\u2192 serial (units share shared.ts)"
+      },
+      { arguments: "scripts/a.ts", note: "\u2192 serial (fewer than two units)" }
+    ]
+  },
+  "split:assess": {
+    examples: [
+      { arguments: "", note: "\u2192 single" },
+      { arguments: JSON_FLAG3, note: MACHINE_READABLE }
+    ]
+  },
+  "oracle:list": { examples: [{ arguments: "" }] },
+  "clone:scan": { examples: [{ arguments: "" }] },
+  cases: {
+    examples: [
+      { arguments: "scripts/a.ts scripts/b.ts", note: "the boundaries these paths cross" }
+    ]
+  }
+};
+
+// scripts/josh/josh-usage-run.ts
+var ISSUE = { arguments: "<N>" };
+var OUTPUT = "--output <path>";
+var OWNER = "--owner <pid>";
+var REPO_FLAG2 = { names: ["--repo <owner/name>"], description: "a child in another repository." };
+var RUN_USAGE = {
+  "run:hold": {
+    examples: [
+      { arguments: "1091", note: "claim for issue 1091" },
+      { arguments: "1091 --fullrun", note: "claim as `fullrun #1091` (what `run:entry` runs)" }
+    ],
+    flags: [
+      { names: ["--fullrun"], description: "marks the record as `fullrun #N`'s." },
+      {
+        names: ["--halfrun-stop"],
+        description: "marks a `halfrun` stop for `run:entry` to adopt."
+      },
+      {
+        names: ["--prrun-stop"],
+        description: "marks a `prrun` stop with the commit its pull request is on."
+      }
+    ]
+  },
+  "run:release": {
+    examples: [
+      { arguments: "1091", note: "release this run's own record" },
+      { arguments: "--force", note: "clear a record left by a run that has ended" }
+    ],
+    flags: [
+      {
+        names: ["--force"],
+        description: "removes a record this run did not write, clearing another run's stale claim."
+      }
+    ]
+  },
+  "run:tidy": { examples: [{ arguments: "" }] },
+  "run:carry": {
+    examples: [
+      { arguments: '--begin "backlogrun --max 5" --owner "$PPID"' },
+      { arguments: "--json", note: "read the record back in a resumed session" },
+      { arguments: '--cut --owner "$PPID"', note: "hand the record off before a cut" },
+      {
+        arguments: '--retrospective --summary "0 filed; dropped #2240 already merged" --owner "$PPID"',
+        note: "close the end-of-run retrospective"
+      },
+      {
+        arguments: '--resume "backlogrun --max 5" --owner "$PPID"',
+        note: "adopt a record no cut handed off"
+      },
+      {
+        arguments: '--end --stopped "epic #2126: everything is blocked behind parked #2118"',
+        note: "end + push"
+      }
+    ],
+    flags: [
+      {
+        names: [OWNER],
+        description: "the long-lived process spending the budget (`$PPID` under a loop); required by counts and `--begin` / `--resume`. A live PID stays `busy` if probes fail."
+      },
+      { names: ["--done <issue>"], description: "shrinks a named-issue run's `remaining` list." },
+      {
+        names: ["--merged <issue>"],
+        description: "names the merged issue and counts it once against `merged_issues`, so a merge `run:merge` already recorded is not counted twice."
+      },
+      { names: ["--filed", "--cut"], description: "increments, never totals." },
+      {
+        names: ["--retrospective"],
+        description: "marks the end-of-run retrospective run, once per invocation, and requires `--summary <text>` \u2014 the same close writes that result as one `retrospective` event on the run's event stream (best-effort), so a run that filed zero improvements reads apart from one whose retrospective never ran. Either flag without the other is refused."
+      },
+      {
+        names: ["--stopped <reason>"],
+        description: "rides on `--end`: the run stopped rather than finished, so one \u23F8\uFE0F confirmation is pushed with the reason."
+      },
+      {
+        names: ["--end"],
+        description: "over a live record flushes pending ledger lines once (a failed flush goes to stderr and the record is still cleared); first collects each lane the run launched whose issue merged, exactly as `run:merge` would; keeps the run it removes as the last ended run \u2014 its invocation, start and end, one record overwritten by the next `--end` \u2014 so `run:board` can still draw a finished run."
+      }
+    ]
+  },
+  "run:add": {
+    examples: [
+      { arguments: "101 102", note: "ahead of the rest of the queue (`#N` works too)" },
+      { arguments: "101 --no-priority", note: "at the end of the queue" }
+    ]
+  },
+  "run:wake": {
+    examples: [
+      { arguments: "--start", note: "launch the detached supervisor" },
+      { arguments: "--list", note: "supervisor state, cut/wake counts, latest progress line" },
+      { arguments: "--stop", note: "stop the supervisor alone" },
+      { arguments: "--loop --interval 30", note: "run the loop body in the foreground" }
+    ]
+  },
+  "run:cut": {
+    examples: [
+      { arguments: "1839", note: "take the cut and hand it to a fresh process" },
+      {
+        arguments: "--impl 1839 --handoff .claude/tmp/handoff-1839.json",
+        note: "cut mid-implementation, carrying the instruction"
+      },
+      { arguments: "--resume 1839", note: "a fresh process's entry check" },
+      { arguments: "--end", note: "clear the record" }
+    ]
+  },
+  "run:liveness": {
+    examples: [
+      { arguments: "1169 --output <path>" },
+      { arguments: "1169 --output <path> --window 45 --gap 2 --repo joshuafolkken/app-kit" }
+    ],
+    flags: [
+      {
+        names: [OUTPUT],
+        description: "absolute, under the home or temp directory; a symlink is followed and size compared as well as mtime."
+      },
+      {
+        names: ["--process alive | none"],
+        description: "overrides the process trace, which the command otherwise reads itself: the child's own command line (`fullrun #<N>`) or its detached ship supervisor."
+      },
+      {
+        names: ["--window <min>"],
+        description: "silent window the file must be frozen for (default 30)."
+      },
+      { names: ["--gap <sec>"], description: "spacing between samples (default 5)." },
+      REPO_FLAG2
+    ]
+  },
+  "run:ending": {
+    examples: [
+      { arguments: "2118 --output <path>" },
+      { arguments: "2118 --output <path> --repo joshuafolkken/app-kit" }
+    ],
+    flags: [
+      {
+        names: [OUTPUT],
+        description: "the child's transcript, absolute and under the home or temp directory (validated the same way `run:liveness --output` is)."
+      },
+      REPO_FLAG2
+    ]
+  },
+  "run:prep": { examples: [ISSUE] },
+  "run:entry": {
+    examples: [
+      { arguments: "<N>", note: "a `fullrun`" },
+      { arguments: "<N> --to halfrun", note: "a run that goes as far as `halfrun`" }
+    ]
+  },
+  "run:status": {
+    examples: [ISSUE, { arguments: "<N> --repo <owner/repo>", note: "a cross-repo child" }]
+  },
+  "run:next": { examples: [ISSUE] },
+  "run:step": {
+    examples: [
+      { arguments: "<N>", note: "the run's next action for issue <N>" },
+      { arguments: "", note: "the `backlogrun` parent's next action" }
+    ]
+  },
+  "run:merge": {
+    examples: [
+      {
+        arguments: '<N> --epic <E> --repo <owner/repo> --owner "$PPID" --output <path>',
+        note: "prints the next child number, or a verdict"
+      },
+      { arguments: '<N> --owner "$PPID"', note: "backlog offer (no epic)" }
+    ],
+    flags: [
+      {
+        names: ["--epic <E>", "--repo <owner/repo>"],
+        description: "offer the epic's next children; omit both for the opted-in backlog."
+      },
+      {
+        names: [OWNER],
+        description: "the parent's process, so the carry count respects the ownership guard."
+      },
+      {
+        names: [OUTPUT],
+        description: "the transcript the outage split reads; absent, it is off."
+      }
+    ]
+  },
+  "run:review": {
+    examples: [
+      {
+        arguments: "",
+        note: "detach the gate, print the brief; then launch the /code-review subagent"
+      },
+      { arguments: "--join", note: "after the review returns: join the gate, check its verdict" }
+    ]
+  },
+  "run:tail": {
+    examples: [
+      { arguments: "<N>", note: "the closed issue" },
+      { arguments: "<N> <follow-up-N>", note: "and a follow-up filed this run" }
+    ]
+  },
+  ship: {
+    examples: [
+      { arguments: '"<title> #<N>" --body-file <evidence.md>' },
+      { arguments: '"<title> #<N>" --review', note: "both review rounds inside the ship" },
+      { arguments: '--detach "<title> #<N>"', note: "hand the ship to a supervisor" },
+      { arguments: "--log <N>", note: "a detached ship's log" }
+    ],
+    flags: [
+      {
+        names: ["--body-file <path>"],
+        description: "the PR body carrying the live-execution evidence `followup` gates on; forwarded to `git -y` alone."
+      },
+      { names: ["--notify-message <text>"], description: "forwarded to `followup` alone." },
+      {
+        names: ["--review"],
+        description: "runs review round 1 beside the gate, and round 2 after the commit when `review:round2` requires it; a High or an unfixed Medium stops the ship."
+      },
+      {
+        names: ["--detach"],
+        description: "hands the ship to a supervisor (implied in a lane child); a stop emits `ship-stop` (`--log <N>`). The preflight, type check, unused exports, cspell and guard tests run before the hand-off; a stop returns to the same session."
+      }
+    ]
+  },
+  "run:report": {
+    examples: [{ arguments: "", note: "print the report; the same text josh notify sends" }]
+  },
+  "run:event": {
+    examples: [
+      { arguments: "--append <kind> <text>", note: "append one event; prints its position" },
+      { arguments: "--from <position>", note: "every event after <position>, in order (JSON)" },
+      { arguments: "--follow <position>", note: "new events, waiting for one; position on stderr" },
+      { arguments: "--watch [<position>]", note: "every new event, rendered, until interrupted" },
+      { arguments: "--last", note: "the newest event alone" }
+    ]
+  }
+};
+
+// scripts/josh/josh-usage-session.ts
+var BARE = { arguments: "" };
+var PATH_DIR = "--path <dir>";
+var SESSION_USAGE = {
+  "run:progress": {
+    examples: [
+      { arguments: "--output <path>" },
+      { arguments: "--once", note: "five labelled lines now, whatever the clock says" },
+      { arguments: "--interval 20 --repo joshuafolkken/app-kit --hours 4" }
+    ],
+    flags: [
+      {
+        names: ["--mark"],
+        description: "record that a real report happened without printing a line (keeps the last line for `run:wake --list`)."
+      },
+      {
+        names: ["--path"],
+        description: 'print the ambient heartbeat log\'s path and exit. Every heartbeat line is mirrored there, so `tail -F "$(pnpm josh run:progress --path)"` follows the run across a `backlogrun` session cut. Reads no run state, so it answers in a lane child too.'
+      },
+      {
+        names: ["--interval <min>"],
+        description: "silence interval (default 20; also `JOSH_PROGRESS_INTERVAL_MINUTES`, then `josh.progress_interval_minutes`)."
+      },
+      {
+        names: ["--wait"],
+        description: "start once in the background: each report goes to the event stream and ambient log, never stdout; exits only on an arrival, `josh followup` ending the run, or `--hours`."
+      },
+      {
+        names: ["--hours <n>"],
+        description: "how long the watcher lives (default 8 with `--wait`, 1 otherwise)."
+      },
+      { names: ["--repo <owner/name>"], description: "scopes the read." }
+    ]
+  },
+  "run:board": {
+    examples: [
+      { arguments: "", note: "redraw until interrupted" },
+      { arguments: "--once", note: "one frame, then exit" },
+      { arguments: "--chat", note: "one frame for a chat, recorded as a progress report" },
+      {
+        arguments: "--every 5",
+        note: "the --chat frame as a \u{1F4CA} Progress Telegram every 5 minutes, until the run ends"
+      }
+    ],
+    flags: [
+      {
+        names: ["--chat"],
+        description: "answers a `backlogrun` progress question: the frame `--once` draws, with only `\u{1F9E0}` on the machine line and no escapes; it records the report as `run:progress --mark` does."
+      },
+      {
+        names: ["--every <minutes>"],
+        description: "sends the `--chat` frame as a `\u{1F4CA} Progress` Telegram now and every `<minutes>` until the run ends \u2014 only when a person asks for it."
+      }
+    ]
+  },
+  "run:watcher:guard": { examples: [BARE] },
+  "run:stranded": { examples: [BARE] },
+  "lane:open": { examples: [{ arguments: "1490", note: "prints the lane directory on stdout" }] },
+  "lane:close": {
+    examples: [{ arguments: "1490" }, { arguments: "--all" }],
+    flags: [{ names: ["--all"], description: "closes every lane." }]
+  },
+  "lane:list": { examples: [BARE] },
+  "lane:prune": { examples: [BARE] },
+  "lane:output": {
+    examples: [
+      { arguments: "1713 /abs/path/to/agent-7.jsonl", note: "record it; prints the path back" },
+      { arguments: "1713", note: "read it; prints the path, or `none`" }
+    ]
+  },
+  "lane:dispatch": {
+    examples: [
+      {
+        arguments: "1749",
+        note: "prints the child's pid; a refusal is an empty capture and exit 1"
+      }
+    ],
+    flags: [
+      {
+        names: ["JOSH_{SCHEDULER,WORKER,REVIEWER}_MODEL"],
+        description: "Claude Code role overrides; Anthropic defaults are respectively `claude-opus-5-5`, `claude-opus-5-5`, and `claude-opus-5-5`. Codex keeps its provider-specific model."
+      },
+      {
+        names: ["JOSH_{SCHEDULER,WORKER,REVIEWER}_EFFORT"],
+        description: "role effort overrides for either provider; defaults are `medium`, `medium`, and `high`."
+      },
+      {
+        names: ["JOSH_REVIEWER_VERIFICATION_{MODEL,EFFORT}"],
+        description: "review round 2 and later (the verification pass); Anthropic defaults are `claude-sonnet-5-5` / `high`, falling back to `JOSH_REVIEWER_*`."
+      }
+    ]
+  },
+  "lane:await": {
+    examples: [
+      { arguments: "1749 1750", note: "block until either lane completes" },
+      {
+        arguments: '1749 1750 --owner "$PPID"',
+        note: "reclaim the carry record for a resumed conversation first"
+      }
+    ]
+  },
+  "lane:launch": {
+    examples: [
+      { arguments: "1749", note: "every lane after the first" },
+      {
+        arguments: '1749 --stash "backlogrun: josh latest before lanes"',
+        note: "the first lane only"
+      }
+    ]
+  },
+  "lane:sample": { examples: [{ arguments: "", note: "one machine-load reading" }] },
+  "lane:stats": {
+    examples: [{ arguments: "--period 7", note: "a 7-day period's stage medians and maxima" }]
+  },
+  cost: {
+    examples: [
+      {
+        arguments: "--cut",
+        note: "compare billed input per request with the shared 135,000 context-cut threshold"
+      },
+      { arguments: "--over <tokens>", note: "compare with an explicit limit" },
+      { arguments: `--cut ${PATH_DIR}`, note: "Anthropic project or current OpenAI worktree" }
+    ],
+    flags: [
+      {
+        names: [PATH_DIR],
+        description: "selects another Anthropic project; OpenAI accepts only linked checkouts of the current project."
+      }
+    ]
+  },
+  "doc:section": {
+    examples: [
+      { arguments: '<file.md> "<heading>"' },
+      { arguments: 'backlogrun.md "The hand-off"' }
+    ]
+  },
+  "read:set": {
+    examples: [
+      { arguments: "", note: "every entry point" },
+      { arguments: "backlogrun", note: "one of them" },
+      { arguments: "backlogrun --json" }
+    ]
+  },
+  "doc:read": {
+    examples: [
+      { arguments: "CLAUDE.md", note: "under the cap: prints the document" },
+      { arguments: "backlogrun.md", note: "over the cap: prints a directive, no content" }
+    ]
+  },
+  "read:files": {
+    examples: [
+      { arguments: "a.ts b.ts c.ts", note: "under the cap: prints each file under its own header" },
+      {
+        arguments: "a.ts big.ts",
+        note: "over the cap: prints a directive to Read them in one turn, no content"
+      }
+    ]
+  },
+  "edit:files": {
+    examples: [
+      {
+        arguments: "plan.txt",
+        note: "applies every block in the plan, one line per edit reporting the outcome"
+      },
+      { arguments: "- <<'EDITS'", note: "plan from stdin, then EDITS" }
+    ]
+  },
+  time: {
+    examples: [
+      { arguments: "", note: "the last run tree, wall clock and cost by role" },
+      { arguments: "--run", note: "the same run-tree scope, named explicitly" },
+      { arguments: "--json", note: "the same figures, machine-readable" },
+      { arguments: PATH_DIR, note: "read another project's transcripts from this checkout" }
+    ],
+    flags: [
+      {
+        names: ["--run"],
+        description: '(default) the whole run tree, wall clock led beside dollars. It is the only scope; any other flag is a usage error (exit 1). History: `docs/maintainers/josh-commands-run-rationale.md` \u2192 "`josh cost` and `josh time` lost their report scopes".'
+      },
+      {
+        names: [PATH_DIR],
+        description: "aim the read at another project (absolute path); keeps the `cwd` behavior when absent."
+      },
+      { names: ["--json"], description: "the run tree, machine-readable." }
+    ]
+  },
+  "cost:audit": {
+    examples: [
+      { arguments: "", note: "the last 7 days against the 7 before" },
+      { arguments: "--period 30", note: "the last 30 days against the 30 before" }
+    ],
+    flags: [
+      {
+        names: ["--period <days>"],
+        description: "the length of each period, a positive whole number of days (default 7)."
+      }
+    ]
+  },
+  retrospective: {
+    examples: [{ arguments: "", note: "the digest for the run this checkout carries" }]
+  },
+  eval: {
+    examples: [
+      { arguments: "", note: "every scenario" },
+      { arguments: "consult-not-execute", note: "one scenario by name" }
+    ],
+    flags: [
+      { names: ["JOSH_EVAL_MODEL"], description: "the model to run against (default `sonnet`)." },
+      {
+        names: ["JOSH_EVAL_CONCURRENCY"],
+        description: "how many sessions run at once (default `5`); a non-positive-integer value is refused."
+      }
+    ]
+  }
+};
+
+// scripts/josh/josh-usage-workflow.ts
+var PR_TITLE = '"PR title #N"';
+var ISSUE_URL = '--issue-url "https://..."';
+var REVIEW_ISSUE = "--issue 2325";
+var CHECK2 = "--check";
+var JSON_FLAG4 = "--json";
+var BODY_FILE_NOTE = "(`-` reads stdin); use this whenever the body carries a backtick or `$`. Passing both forms is refused.";
+var WORKFLOW_USAGE = {
+  followup: {
+    examples: [
+      { arguments: PR_TITLE, note: "merges (default)" },
+      { arguments: String.raw`${PR_TITLE} --notify-message "Implemented X:\n- change 1"` },
+      { arguments: `${PR_TITLE} --notify-message-file completion.md` },
+      { arguments: `${PR_TITLE} --ai-review-ignore-reason "false positive"` },
+      { arguments: `${PR_TITLE} --no-merge`, note: "do the work, leave the PR open" }
+    ],
+    flags: [
+      {
+        names: ["--no-merge"],
+        description: "do the follow-up work but do not merge; leaves the PR open (the only flag that stops the merge). `--merge` is a deprecated no-op. A PR already merged by hand skips the CI wait, the AI-review scan and the merge and runs only the post-merge tail; a completion report already on the Issue is not posted again."
+      },
+      {
+        names: ["--notify-message"],
+        description: "inline completion body; `\\n` expands to newlines."
+      },
+      {
+        names: ["--notify-message-file"],
+        description: `read the completion body from a file ${BODY_FILE_NOTE}`
+      },
+      {
+        names: ["--ai-review-ignore-reason"],
+        description: "reason to dismiss an AI-review finding."
+      }
+    ]
+  },
+  notify: {
+    examples: [
+      { arguments: String.raw`--task-type planning ${ISSUE_URL} --body="- bullet 1\n- bullet 2"` },
+      {
+        arguments: `--task-type confirmation ${ISSUE_URL} --body-file r.md --recommended "Go" --alternative "Wait"`
+      }
+    ],
+    flags: [
+      {
+        names: ["--task-type"],
+        description: "one of `planning` \u{1F4CB}, `completion` \u2705, `failure` \u274C, `warning` \u26A0\uFE0F, `kickoff_retry` \u{1F504}, `confirmation` \u23F8\uFE0F. Do not send `completion` or `warning` by hand \u2014 `josh followup` sends them."
+      },
+      {
+        names: ["--body", "--body=$'\u2026'"],
+        description: "inline body; use `--body=$'\u2026'` when it starts with `-`."
+      },
+      { names: ["--body-file"], description: `read the body from a file ${BODY_FILE_NOTE}` },
+      {
+        names: ["--repo-name", "--issue-url", "--pr-url"],
+        description: "header repository, resolved in that order, then the working directory. The issue title is read from `--issue-url`."
+      },
+      {
+        names: ["--recommended", "--alternative"],
+        description: "the choices appended under `JOSH_SESSION_LANG` headings; `--recommended` is required for `confirmation`, `--alternative` is repeatable."
+      }
+    ]
+  },
+  "observations:flush": { examples: [{ arguments: "" }] },
+  "measure:rerun": { examples: [{ arguments: "2212" }] },
+  "review:record": {
+    examples: [
+      { arguments: `${REVIEW_ISSUE} bug-risks:medium:src/foo.ts:42 tests:low:a.test.ts` },
+      { arguments: REVIEW_ISSUE, note: "a zero-finding round \u2014 records one `none` line" },
+      {
+        arguments: `${REVIEW_ISSUE} --comment`,
+        note: "a round that passed after the PR opened \u2014 an Issue comment, no append"
+      },
+      { arguments: `${CHECK2} ${REVIEW_ISSUE}`, note: "the merge gate: was it recorded?" }
+    ]
+  },
+  bump: { examples: [{ arguments: "major" }, { arguments: "minor" }, { arguments: "patch" }] },
+  release: {
+    examples: [
+      { arguments: "" },
+      { arguments: "--dry-run", note: "count and report, write nothing" }
+    ],
+    flags: [
+      {
+        names: ["--dry-run"],
+        description: "count and report only; writes nothing, fetches nothing, and creates no work tree."
+      },
+      {
+        names: ["--help", "-h"],
+        description: "print the usage line and exit 0 without fetching or releasing. Any other argument is refused with the usage line and a non-zero exit, before anything is fetched."
+      }
+    ]
+  },
+  "release:scope": {
+    examples: [
+      { arguments: "", note: "\u2192 required | skip | unknown" },
+      { arguments: "--json", note: '{"scope":"\u2026","reason":"\u2026"} on one line' }
+    ]
+  },
+  "ruleset:check": {
+    examples: [
+      { arguments: "", note: "report only" },
+      { arguments: "--apply", note: "add the missing checks to the existing rule" }
+    ],
+    flags: [
+      {
+        names: ["--apply"],
+        description: "append the missing checks to the ruleset's required-checks rule (or to the branch protection's contexts). It never creates a ruleset: with none, create one under Settings \u2192 Rules \u2192 Rulesets, then rerun. Writing a repository setting needs admin access, so only this flag writes \u2014 `josh sync` and `josh doctor` never do."
+      }
+    ]
+  },
+  "audit:provision": {
+    examples: [
+      { arguments: "", note: "no-op if a scanner is already present" },
+      { arguments: "--force", note: "ignore backoff, allow a longer download" }
+    ],
+    flags: [
+      {
+        names: ["--force"],
+        description: "ignore the 6-hour failure backoff and allow a longer download window; the command to run after fixing a network problem."
+      }
+    ]
+  },
+  "reconcile-templates": {
+    examples: [
+      { arguments: "", note: "regenerate copy templates + record tripwire hashes" },
+      { arguments: CHECK2, note: "verify templates are in sync; non-zero on drift" }
+    ],
+    flags: [
+      {
+        names: [CHECK2],
+        description: "verify only; exits non-zero on drift. A pre-commit hook runs this when a tracked source or copy template is staged."
+      }
+    ]
+  },
+  "pre-push-unit": { examples: [{ arguments: "" }] },
+  "reserved-run": {
+    examples: [
+      { arguments: "2 -- pnpm install", note: "hold 2 cores while installing" },
+      { arguments: "1 -- pnpm josh audit", note: "hold 1 core while scanning" }
+    ]
+  },
+  "pre-commit-type-check": { examples: [{ arguments: "" }] },
+  "pr:classification": {
+    examples: [{ arguments: "", note: "run by CI on a pull request; fails without one label" }]
+  },
+  "observation:record": {
+    examples: [
+      { arguments: "flaky-e2e d1 'tests/e2e/login.test.ts' 'times out on CI only'" },
+      {
+        arguments: "flaky-e2e d1 'src/app.ts' 'fails there too' --checkout ~/Development/app",
+        note: "another repository's ledger"
+      }
+    ],
+    flags: [
+      {
+        names: ["--checkout <path>"],
+        description: "count and append in that repository's `.josh/observations/` instead."
+      }
+    ]
+  },
+  "release:github": {
+    examples: [
+      { arguments: "", note: "run by CI with GH_TOKEN, RELEASE_TAG and GITHUB_REPOSITORY set" }
+    ]
+  },
+  "latest:scope": {
+    examples: [
+      { arguments: "", note: "required or skip, the reason on stderr" },
+      { arguments: "--record", note: "note a finished josh latest run" },
+      { arguments: JSON_FLAG4, note: "the verdict and the reason as JSON" }
+    ],
+    flags: [
+      { names: ["--record"], description: "write the completion record `josh latest` ends with." },
+      { names: [JSON_FLAG4], description: "emit the verdict and its reason as JSON." }
+    ]
+  },
+  "latest:guard": { examples: [{ arguments: "", note: "refuses inside a lane" }] },
+  "prevent-main-commit": { examples: [{ arguments: "", note: "run by the pre-commit hook" }] },
+  "check-commit-message": {
+    examples: [{ arguments: ".git/COMMIT_EDITMSG", note: "run by the commit-msg hook" }]
+  },
+  "secretlint-scan": {
+    examples: [{ arguments: "src/app.ts .env.example", note: "the staged paths" }]
+  },
+  "pre-commit-lint": {
+    examples: [
+      { arguments: "cspell src/app.ts" },
+      { arguments: "prettier src/app.ts" },
+      { arguments: "eslint src/app.ts" }
+    ]
+  }
+};
+
+// scripts/josh/command-usage.ts
+var USAGE_PAGE_TABLES = {
+  "docs/josh-commands.md": [DEVELOPER_USAGE],
+  "docs/josh-commands-run.md": [RUN_USAGE, SESSION_USAGE],
+  "docs/josh-commands-backlog.md": [ISSUE_USAGE, BACKLOG_USAGE, REVIEW_USAGE],
+  "docs/josh-commands-automation.md": [AUTOMATION_USAGE, WORKFLOW_USAGE, HOOK_USAGE]
+};
+var COMMAND_USAGE = Object.fromEntries(
+  Object.values(USAGE_PAGE_TABLES).flat().flatMap((table) => Object.entries(table))
+);
+var NOTE_GAP = 3;
+function usage_for(name) {
+  return Object.hasOwn(COMMAND_USAGE, name) ? COMMAND_USAGE[name] : void 0;
+}
+function example_line(name, example) {
+  const command = example.arguments ? `pnpm josh ${name} ${example.arguments}` : `pnpm josh ${name}`;
+  return { command, note: example.note };
+}
+function format_examples(name, usage) {
+  const lines = usage.examples.map((example) => example_line(name, example));
+  const width = Math.max(...lines.map((line) => line.command.length)) + NOTE_GAP;
+  const rendered = lines.map(
+    (line) => line.note === void 0 ? line.command : `${line.command.padEnd(width)}# ${line.note}`
+  );
+  return ["```bash", ...rendered, "```"].join("\n");
+}
+function code_span(text) {
+  return `\`${text}\``;
+}
+function format_flags(flags) {
+  const items = flags.map(
+    (flag) => `- ${flag.names.map((spelling) => code_span(spelling)).join(" / ")} \u2014 ${flag.description}`
+  );
+  return ["**Options:**", "", ...items].join("\n");
+}
+function format_usage(name) {
+  const usage = usage_for(name);
+  if (usage === void 0) return void 0;
+  const flags = usage.flags === void 0 ? [] : [format_flags(usage.flags)];
+  return [format_examples(name, usage), ...flags].join("\n\n");
+}
+function format_command_help(input) {
+  const name = canonical_command(input);
+  const entry = Object.hasOwn(COMMAND_MAP, name) ? COMMAND_MAP[name] : void 0;
+  if (entry === void 0) return void 0;
+  const [synopsis] = entry.reference;
+  const head = synopsis ? `josh ${name} ${synopsis}` : `josh ${name}`;
+  const usage = format_usage(name);
+  return [head, "", entry.description, ...usage === void 0 ? [] : ["", usage]].join("\n");
+}
+function page_commands(page) {
+  const tables = Object.hasOwn(USAGE_PAGE_TABLES, page) ? USAGE_PAGE_TABLES[page] : void 0;
+  return (tables ?? []).flatMap((table) => Object.keys(table));
+}
+var command_usage = {
+  USAGE_PAGES: Object.keys(USAGE_PAGE_TABLES),
+  format_command_help,
+  format_usage,
+  page_commands
+};
+
+// scripts/josh/josh-logic.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "node:fs";
+import path15 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// scripts/build/local-bin.ts
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
+import { createRequire } from "node:module";
+import path11 from "node:path";
+
+// scripts/lib/ancestor-directories.ts
+import path10 from "node:path";
+var MAX_DEPTH = 64;
+function list(start_directory) {
+  const directories = [];
+  let current = path10.resolve(start_directory);
+  while (directories.length < MAX_DEPTH && !directories.includes(current)) {
+    directories.push(current);
+    current = path10.dirname(current);
+  }
+  return directories;
+}
+function nearest(start_directory, is_match) {
+  return list(start_directory).find((directory) => is_match(directory));
+}
+var ancestor_directories = { list, nearest };
+
+// scripts/lib/schemas.ts
+import { z as z4 } from "zod";
+var overrides_snapshot_schema = z4.record(z4.string(), z4.string());
+var package_version_schema = z4.object({ version: z4.string() });
+var package_named_version_schema = z4.looseObject({ name: z4.string(), version: z4.string() });
+var package_with_version_schema = z4.looseObject({ version: z4.string() });
+var ls_global_dependency_schema = z4.looseObject({ version: z4.string() });
+var ls_global_dependencies_schema = z4.record(z4.string(), ls_global_dependency_schema).optional();
+var pnpm_ls_global_schema = z4.array(
+  z4.looseObject({
+    dependencies: ls_global_dependencies_schema
+  })
+);
+var vscode_settings_schema = z4.record(z4.string(), z4.unknown());
+var with_scripts_schema = z4.looseObject({
+  scripts: z4.record(z4.string(), z4.string()).optional()
+});
+var with_development_deps_schema = z4.looseObject({
+  devDependencies: z4.record(z4.string(), z4.string()).optional()
+});
+var with_package_manager_schema = z4.looseObject({
+  packageManager: z4.string().optional()
+});
+var with_development_engine_schema = z4.looseObject({
+  devEngines: z4.record(z4.string(), z4.unknown()).optional()
+});
+var bin_entry_schema = z4.union([z4.string(), z4.record(z4.string(), z4.string())]).optional();
+var package_bin_schema = z4.looseObject({ bin: bin_entry_schema });
+var json_object_schema = z4.record(z4.string(), z4.unknown());
+var string_array_schema = z4.array(z4.string());
+var string_record_schema = z4.record(z4.string(), z4.string());
+
+// scripts/build/local-bin.ts
+var NODE_MODULES2 = "node_modules";
+var BIN_DIR = ".bin";
+var WINDOWS_PLATFORM3 = "win32";
+var WINDOWS_SHIM_SUFFIX = ".cmd";
+var PACKAGE_JSON = "package.json";
+function resolve_local_bin(project_root, bin_name) {
+  const shim = process.platform === WINDOWS_PLATFORM3 ? `${bin_name}${WINDOWS_SHIM_SUFFIX}` : bin_name;
+  return path11.join(project_root, NODE_MODULES2, BIN_DIR, shim);
+}
+function read_bin_entry(manifest_path, package_name, bin_name) {
+  const { bin } = package_bin_schema.parse(JSON.parse(readFileSync4(manifest_path, "utf8")));
+  if (typeof bin === "string") return bin_name === path11.basename(package_name) ? bin : void 0;
+  return bin?.[bin_name];
+}
+function resolve_package_bin(base_directory, package_name, bin_name) {
+  try {
+    const resolve_from = createRequire(path11.join(base_directory, PACKAGE_JSON));
+    const manifest_path = resolve_from.resolve(`${package_name}/${PACKAGE_JSON}`);
+    const bin_entry = read_bin_entry(manifest_path, package_name, bin_name);
+    if (bin_entry === void 0) return void 0;
+    const cli_entry = path11.join(path11.dirname(manifest_path), bin_entry);
+    return existsSync3(cli_entry) ? cli_entry : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// scripts/josh/josh-logic.ts
+import { execaSync as execaSync2 } from "execa";
+
+// scripts/josh/command-suggest.ts
+var MAX_SUGGESTION_DISTANCE = 3;
+function at(values, index) {
+  return values[index] ?? 0;
+}
+function fill_distance_row(source, target, row, previous) {
+  const current = [row];
+  for (let col = 1; col <= target.length; col++) {
+    const cost = source[row - 1] === target[col - 1] ? 0 : 1;
+    const deletion = at(previous, col) + 1;
+    const insertion = at(current, col - 1) + 1;
+    const substitution = at(previous, col - 1) + cost;
+    current.push(Math.min(deletion, insertion, substitution));
+  }
+  return current;
+}
+function edit_distance(source, target) {
+  let previous = Array.from({ length: target.length + 1 }, (_unused, index) => index);
+  for (let row = 1; row <= source.length; row++) {
+    previous = fill_distance_row(source, target, row, previous);
+  }
+  return at(previous, target.length);
+}
+function closest_command(input, commands) {
+  const within = commands.map((command) => ({ command, distance: edit_distance(input, command) })).filter((scored) => scored.distance <= MAX_SUGGESTION_DISTANCE).toSorted((left, right) => left.distance - right.distance);
+  return within[0]?.command;
+}
+var command_suggest = { closest_command, edit_distance };
+
+// scripts/josh/josh-composite-arguments.ts
+var SHELL_INTERPRETERS = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash"]);
+var SHELL_COMMAND_FLAG = "-c";
+var PATH_SEPARATOR = "/";
+var USAGE_ERROR_EXIT_CODE = 1;
+function is_shell_interpreter(executable) {
+  return SHELL_INTERPRETERS.has(executable.split(PATH_SEPARATOR).at(-1) ?? executable);
+}
+function is_composite_shell(shell) {
+  const [executable, flag] = shell ?? [];
+  if (executable === void 0) return false;
+  return is_shell_interpreter(executable) && flag === SHELL_COMMAND_FLAG;
+}
+function format_targets(targets) {
+  return targets.map((target) => `josh ${target}`).join(" or ");
+}
+function format_rejection(cmd, targets) {
+  const hint = targets.length > 0 ? `pass them to ${format_targets(targets)} instead` : "it runs a fixed sequence and forwards nothing";
+  return `josh ${cmd} takes no extra arguments \u2014 ${hint}`;
+}
+function reject_extra_arguments(cmd, entry, extra) {
+  if (extra.length === 0 || !is_composite_shell(entry.shell)) return void 0;
+  return format_rejection(cmd, entry.argument_targets ?? []);
+}
+var composite_arguments = { format_rejection, is_composite_shell, reject_extra_arguments };
+
+// scripts/josh/josh-in-process.ts
+import { realpathSync } from "node:fs";
+import path12 from "node:path";
+import { pathToFileURL } from "node:url";
+var TYPESCRIPT_EXTENSION = ".ts";
+var JAVASCRIPT_EXTENSION = ".js";
+var BUNDLED_COMMAND_DIRECTORY = path12.join("dist", "commands");
+var FAILURE_EXIT_CODE = 1;
+function is_typescript_dispatcher(dispatcher_url) {
+  return dispatcher_url.endsWith(TYPESCRIPT_EXTENSION);
+}
+function bundled_script_path(package_directory, script) {
+  const name = `${path12.basename(script, TYPESCRIPT_EXTENSION)}${JAVASCRIPT_EXTENSION}`;
+  return path12.join(package_directory, BUNDLED_COMMAND_DIRECTORY, name);
+}
+function in_process_target(entry, package_directory, dispatcher_url) {
+  if (entry.script === void 0 || entry.tsx_arguments !== void 0) return void 0;
+  if (is_typescript_dispatcher(dispatcher_url)) return path12.join(package_directory, entry.script);
+  return entry.is_bundled === true ? bundled_script_path(package_directory, entry.script) : void 0;
+}
+function read_exit_code() {
+  const code = process.exitCode;
+  return typeof code === "number" ? code : 0;
+}
+function resolve_real_path(script_path) {
+  try {
+    return realpathSync(script_path);
+  } catch {
+    return script_path;
+  }
+}
+async function run_in_process(script_path, script_arguments) {
+  const resolved_path = resolve_real_path(script_path);
+  process.argv = [process.execPath, resolved_path, ...script_arguments];
+  try {
+    await import(pathToFileURL(resolved_path).href);
+  } catch (error) {
+    console.error(error);
     return FAILURE_EXIT_CODE;
   }
   return read_exit_code();
@@ -2985,9 +4823,20 @@ var kit_only = {
   notice: kit_only_notice
 };
 
+// scripts/josh/package-directory.ts
+import { existsSync as existsSync4 } from "node:fs";
+import path13 from "node:path";
+var PACKAGE_JSON2 = "package.json";
+function find_package_directory(start_directory) {
+  return ancestor_directories.nearest(
+    start_directory,
+    (directory) => existsSync4(path13.join(directory, PACKAGE_JSON2))
+  ) ?? start_directory;
+}
+
 // scripts/josh/run-github-prerequisite.ts
-import { existsSync as existsSync3 } from "node:fs";
-import path10 from "node:path";
+import { existsSync as existsSync5 } from "node:fs";
+import path14 from "node:path";
 
 // scripts/discovery/repo-origin.ts
 var GITHUB_HOST = "github.com";
@@ -3096,7 +4945,7 @@ var GITHUB_RUN_COMMANDS = /* @__PURE__ */ new Set([
 ]);
 function explanation(root, command) {
   if (!GITHUB_RUN_COMMANDS.has(command)) return void 0;
-  if (!existsSync3(path10.join(root, ".git"))) {
+  if (!existsSync5(path14.join(root, ".git"))) {
     return `${command} requires Git and a GitHub origin. Run git init and add a GitHub origin first.`;
   }
   const url = git_spawn_sync.origin_url(root);
@@ -3110,21 +4959,15 @@ var COLUMN_WIDTH = 26;
 var ALIAS_PAD_WIDTH = 2;
 var TSX_BIN = "tsx";
 var TSX_PACKAGE = "tsx";
-var PACKAGE_JSON2 = "package.json";
+var PACKAGE_JSON3 = "package.json";
 var UNKNOWN_COMMAND_EXIT_CODE = -1;
-function find_package_directory(start_directory) {
-  return ancestor_directories.nearest(
-    start_directory,
-    (directory) => existsSync4(path11.join(directory, PACKAGE_JSON2))
-  ) ?? start_directory;
-}
-var PACKAGE_DIR2 = find_package_directory(path11.dirname(fileURLToPath2(import.meta.url)));
+var PACKAGE_DIR2 = find_package_directory(path15.dirname(fileURLToPath2(import.meta.url)));
 function resolve_tsx_executable() {
   const candidates = [
     resolve_local_bin(PACKAGE_DIR2, TSX_BIN),
     resolve_local_bin(process.cwd(), TSX_BIN)
   ];
-  return candidates.find(existsSync4) ?? TSX_BIN;
+  return candidates.find(existsSync6) ?? TSX_BIN;
 }
 function resolve_tsx_cli_entry() {
   for (const base_directory of [PACKAGE_DIR2, process.cwd()]) {
@@ -3141,7 +4984,7 @@ function resolve_tsx_runner() {
   return { executable: resolve_tsx_executable(), leading_arguments: [] };
 }
 function read_package_version() {
-  const raw = readFileSync5(path11.join(PACKAGE_DIR2, PACKAGE_JSON2), "utf8");
+  const raw = readFileSync5(path15.join(PACKAGE_DIR2, PACKAGE_JSON3), "utf8");
   return package_version_schema.parse(JSON.parse(raw)).version;
 }
 var HEADER = `josh v${read_package_version()} \u2014 Joshua Folkken's dev toolkit`;
@@ -3228,7 +5071,7 @@ async function run_script_entry(entry, subcommand_arguments) {
   const script_arguments = [...entry.default_script_arguments ?? [], ...subcommand_arguments];
   const target = josh_in_process.in_process_target(entry, PACKAGE_DIR2, import.meta.url);
   if (target !== void 0) return await josh_in_process.run_in_process(target, script_arguments);
-  return spawn_script_entry(entry, path11.join(PACKAGE_DIR2, entry.script ?? ""), script_arguments);
+  return spawn_script_entry(entry, path15.join(PACKAGE_DIR2, entry.script ?? ""), script_arguments);
 }
 function github_prerequisite_exit(resolved, is_consumer) {
   if (!is_consumer) return void 0;
@@ -3260,13 +5103,13 @@ async function run_entry(entry, subcommand_arguments) {
 function declared(value) {
   return typeof value === "function" ? value() : value;
 }
-async function dispatch_entry(entry, subcommand_arguments) {
+async function dispatch_entry(command, entry, subcommand_arguments) {
   const weight = declared(entry.core_weight);
   if (weight === void 0) return await run_entry(entry, subcommand_arguments);
   return await core_budget.with_command_reservation(
     weight,
     async () => await run_entry(entry, subcommand_arguments),
-    { memory_mb: declared(entry.memory_mb) }
+    { memory_mb: declared(entry.memory_mb), command }
   );
 }
 async function run_command(cmd, subcommand_arguments, is_consumer = false) {
@@ -3275,7 +5118,7 @@ async function run_command(cmd, subcommand_arguments, is_consumer = false) {
   if (!entry) return UNKNOWN_COMMAND_EXIT_CODE;
   const early_exit = pre_dispatch_exit(resolved, entry, subcommand_arguments, is_consumer);
   if (early_exit !== void 0) return early_exit;
-  return await dispatch_entry(entry, subcommand_arguments);
+  return await dispatch_entry(resolved, entry, subcommand_arguments);
 }
 var josh_logic = {
   format_help,
@@ -3289,13 +5132,17 @@ var josh_logic = {
 var ARGV_OFFSET = 2;
 var HELP_COMMANDS = /* @__PURE__ */ new Set(["help", "--help", "-h"]);
 var ALL_FLAG = "--all";
-function print_help(is_all, is_consumer) {
-  console.info(josh_logic.format_help(is_all, is_consumer));
-}
 function handle_unknown(cmd) {
   console.error(josh_logic.format_unknown_command(cmd));
   process.exit(1);
 }
+function print_help(is_all, is_consumer, topic) {
+  if (topic === void 0 || topic.startsWith("-")) {
+    console.info(josh_logic.format_help(is_all, is_consumer));
+    return;
+  }
+  console.info(command_usage.format_command_help(topic) ?? handle_unknown(topic));
+}
 function record_exit_code(exit_code) {
   if (exit_code !== 0) process.exitCode = exit_code;
 }
@@ -3304,7 +5151,7 @@ async function main() {
   const is_all = process.argv.includes(ALL_FLAG);
   const is_consumer = doctor_consumer.is_kit_consumer(find_package_directory(process.cwd()));
   if (!cmd || cmd === ALL_FLAG || HELP_COMMANDS.has(cmd)) {
-    print_help(is_all, is_consumer);
+    print_help(is_all, is_consumer, process.argv[ARGV_OFFSET + 1]);
     return;
   }
   const subcommand_arguments = process.argv.slice(ARGV_OFFSET + 1);