@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/dist/josh.js

@@ -82,10 +82,16 @@ function parse_or_undefined(text) {
     return void 0;
   }
 }
+function parse_with(text, schema) {
+  const value = parse_or_undefined(text);
+  if (value === void 0) return void 0;
+  const parsed = schema.safeParse(value);
+  return parsed.success ? parsed.data : void 0;
+}
 function is_record(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-var json_value = { parse_or_undefined, is_record };
+var json_value = { parse_or_undefined, parse_with, is_record };
 
 // scripts/lib/read-file.ts
 import { readFileSync } from "node:fs";
@@ -365,7 +371,10 @@ 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 SOCKET_PROBE_SOURCE = "const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(0));socket.once('error',()=>process.exit(1));socket.setTimeout(1000,()=>process.exit(1));";
+var BEACON_LIVE_STATUS = 0;
+var BEACON_UNKNOWN_STATUS = 1;
+var BEACON_GONE_STATUS = 2;
+var SOCKET_PROBE_SOURCE = `const net=require('node:net');const socket=net.createConnection(process.argv[1]);socket.once('connect',()=>process.exit(${String(BEACON_LIVE_STATUS)}));socket.once('error',(error)=>process.exit(['ECONNREFUSED','ENOENT'].includes(error.code)?${String(BEACON_GONE_STATUS)}:${String(BEACON_UNKNOWN_STATUS)}));socket.setTimeout(1000,()=>process.exit(${String(BEACON_UNKNOWN_STATUS)}));`;
 var beacons = /* @__PURE__ */ new Map();
 var exit_cleanup = { is_registered: false };
 function is_live_pid(pid) {
@@ -469,11 +478,16 @@ function beacon_target(token) {
   if (path4.dirname(target) !== PLATFORM_TEMP_ROOT) return void 0;
   return is_valid_beacon_name(path4.basename(target)) ? target : void 0;
 }
-function is_live_beacon(target) {
+function run_socket_probe(target) {
   return spawnSync(process.execPath, ["-e", SOCKET_PROBE_SOURCE, target], {
     stdio: "ignore",
     timeout: PROBE_TIMEOUT_MS
-  }).status === 0;
+  }).status ?? void 0;
+}
+function is_live_beacon(target, probe = run_socket_probe) {
+  const status = probe(target);
+  if (status === BEACON_LIVE_STATUS) return true;
+  return status === BEACON_GONE_STATUS ? false : void 0;
 }
 function has_matching_start(pid, recorded_start, read2) {
   const observed = read2(pid);
@@ -502,6 +516,7 @@ function is_own_process(pid, recorded_start) {
 }
 var process_identity = {
   close_beacon,
+  is_live_beacon,
   is_live_pid,
   is_own_process,
   is_same_process,
@@ -554,19 +569,35 @@ function write_exclusively(target, content) {
 function write_stamp(target, payload) {
   return write_exclusively(target, JSON.stringify(payload));
 }
-function replace_stamp(target, payload) {
+function is_own_regular_file(source) {
+  const stats = lstatSync(source);
+  if (!stats.isFile()) return false;
+  const uid = process.getuid?.();
+  return uid === void 0 || stats.uid === uid;
+}
+function is_foreign_file(target) {
+  try {
+    return lstatSync(target).isFile() && !is_own_regular_file(target);
+  } catch {
+    return false;
+  }
+}
+function replace_text_stamp(target, text) {
+  if (is_foreign_file(target)) {
+    throw new Error(`refusing to replace another account's file: ${target}`);
+  }
   const temporary = `${target}.${String(process.pid)}.${randomUUID2()}`;
   try {
-    writeFileSync(temporary, JSON.stringify(payload), {
-      flag: STAMP_CREATE_FLAG,
-      mode: STAMP_FILE_MODE
-    });
+    writeFileSync(temporary, text, { flag: STAMP_CREATE_FLAG, mode: STAMP_FILE_MODE });
     renameSync(temporary, target);
     return target;
   } finally {
     rmSync2(temporary, { force: true });
   }
 }
+function replace_stamp(target, payload) {
+  return replace_text_stamp(target, JSON.stringify(payload));
+}
 function write_text_stamp(target, text) {
   return write_exclusively(target, text);
 }
@@ -585,12 +616,6 @@ function create_stamp(target, payload) {
 function remove_stamp(target) {
   rmSync2(target, { force: true });
 }
-function is_own_regular_file(source) {
-  const stats = lstatSync(source);
-  if (!stats.isFile()) return false;
-  const uid = process.getuid?.();
-  return uid === void 0 || stats.uid === uid;
-}
 function read_stamp_text(source) {
   try {
     if (!is_own_regular_file(source)) return void 0;
@@ -605,6 +630,7 @@ var stamp_file = {
   is_own_regular_file,
   read_stamp_text,
   replace_stamp,
+  replace_text_stamp,
   remove_stamp,
   stamp_path,
   write_stamp,
@@ -794,9 +820,18 @@ var BYTES_PER_MB = 1048576;
 var KB_PER_MB = 1024;
 var PERCENT = 100;
 var MEMINFO_PATH = "/proc/meminfo";
+var VMSTAT_PATH = "/proc/vmstat";
 var LINUX_AVAILABLE = /^MemAvailable:\s+(?<kb>\d+) kB/mu;
-var PRESSURE_ARGUMENTS = ["-n", "kern.memorystatus_level"];
-var PRESSURE_LEVEL = /^\s*(?<level>\d+)\s*$/u;
+var LINUX_SWAP_IN = /^pswpin (?<pages>\d+)$/mu;
+var LINUX_SWAP_OUT = /^pswpout (?<pages>\d+)$/mu;
+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 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 SYSCTL_LINE = /^(?<name>[\w.]+): (?<value>\d+)$/gmu;
 function cpu_times() {
   let busy = 0;
   let idle = 0;
@@ -806,31 +841,96 @@ function cpu_times() {
   }
   return { busy, total: busy + idle };
 }
-function busy_cores_between(before, after, cores) {
+function busy_share_between(before, after) {
   const total = after.total - before.total;
   if (total <= 0) return void 0;
-  return (after.busy - before.busy) / total * cores;
+  return (after.busy - before.busy) / total;
+}
+function busy_cores_between(before, after, cores) {
+  const share = busy_share_between(before, after);
+  return share === void 0 ? void 0 : share * cores;
+}
+function sysctl_values(output) {
+  const values = [...output.matchAll(SYSCTL_LINE)].map(
+    (match) => [match.groups?.["name"] ?? "", Number(match.groups?.["value"])]
+  );
+  return new Map(values);
 }
-function parse_darwin_pressure(output, total_bytes) {
-  const level = PRESSURE_LEVEL.exec(output)?.groups?.["level"];
-  if (level === void 0) return void 0;
-  return Number(level) / PERCENT * (total_bytes / BYTES_PER_MB);
+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 swapped_between(from, to) {
+  if (from === void 0 || to === void 0) return void 0;
+  return Math.max(0, to - from);
+}
+function parse_darwin_memory(output, total_bytes) {
+  const values = sysctl_values(output);
+  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_pages(values.get(SWAP_IN_NAME), values.get(SWAP_OUT_NAME)),
+      values.get(PAGE_SIZE_NAME)
+    ),
+    pressure_level: values.get(PRESSURE_NAME)
+  };
 }
 function parse_linux_available(meminfo) {
   const kb = LINUX_AVAILABLE.exec(meminfo)?.groups?.["kb"];
   return kb === void 0 ? void 0 : Number(kb) / KB_PER_MB;
 }
-async function read_available_mb(platform2 = process.platform) {
+function pages_of(pattern, vmstat) {
+  const pages = pattern.exec(vmstat)?.groups?.["pages"];
+  return pages === void 0 ? void 0 : Number(pages);
+}
+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);
+}
+async function settled(read2) {
   try {
-    if (platform2 === "darwin") {
-      const { stdout } = await execa("sysctl", PRESSURE_ARGUMENTS);
-      return parse_darwin_pressure(stdout, totalmem());
-    }
-    return platform2 === "linux" ? parse_linux_available(await readFile(MEMINFO_PATH, "utf8")) : void 0;
+    return await read2();
   } catch {
     return void 0;
   }
 }
+async function read_darwin_memory() {
+  const { stdout } = await execa("sysctl", SYSCTL_ARGUMENTS, {
+    reject: false,
+    timeout: PROBE_TIMEOUT_MS
+  });
+  return parse_darwin_memory(stdout, totalmem());
+}
+async function read_page_size() {
+  const { stdout } = await execa("getconf", PAGE_SIZE_ARGUMENTS, { timeout: PROBE_TIMEOUT_MS });
+  return stdout;
+}
+async function read_linux_memory() {
+  const [meminfo, vmstat, page_size] = await Promise.all([
+    settled(async () => await readFile(MEMINFO_PATH, "utf8")),
+    settled(async () => await readFile(VMSTAT_PATH, "utf8")),
+    settled(read_page_size)
+  ]);
+  const page_bytes = page_size === void 0 ? void 0 : Number(page_size);
+  return {
+    available_mb: meminfo === void 0 ? void 0 : parse_linux_available(meminfo),
+    swapped_mb: vmstat === void 0 || page_bytes === void 0 ? void 0 : parse_linux_swapped(vmstat, page_bytes),
+    pressure_level: void 0
+  };
+}
+var UNREAD_MEMORY = {
+  available_mb: void 0,
+  swapped_mb: void 0,
+  pressure_level: void 0
+};
+async function read_memory() {
+  if (process.platform === "darwin") return await settled(read_darwin_memory) ?? UNREAD_MEMORY;
+  return process.platform === "linux" ? await read_linux_memory() : UNREAD_MEMORY;
+}
 function is_unquoted() {
   return cpus().length > 0 && cpus().length === availableParallelism2();
 }
@@ -841,9 +941,12 @@ async function default_sleep(ms) {
 }
 async function read_machine(sleep = default_sleep) {
   const before = cpu_times();
-  const [available_mb] = await Promise.all([read_available_mb(), sleep(SAMPLE_WINDOW_MS)]);
+  const [memory] = await Promise.all([read_memory(), sleep(SAMPLE_WINDOW_MS)]);
   const busy_cores = is_unquoted() ? busy_cores_between(before, cpu_times(), cpus().length) : void 0;
-  return { busy_cores, available_mb };
+  return { busy_cores, available_mb: memory.available_mb };
+}
+async function read_sample() {
+  return { cpu: cpu_times(), memory: await read_memory(), total_mb: totalmem() / BYTES_PER_MB };
 }
 function external_cores(busy_cores, ledger_cores) {
   if (busy_cores === void 0) return 0;
@@ -858,10 +961,16 @@ function machine_budget(cores, reading, ledger) {
 var machine_capacity = {
   BASELINE_CORES,
   busy_cores_between,
+  busy_share_between,
+  external_cores,
   machine_budget,
-  parse_darwin_pressure,
+  parse_darwin_memory,
   parse_linux_available,
-  read_machine
+  parse_linux_swapped,
+  read_machine,
+  read_memory,
+  read_sample,
+  swapped_between
 };
 
 // scripts/gate/core-budget.ts
@@ -900,12 +1009,7 @@ function is_running2(reservation) {
 function read_reservation(source) {
   const raw = stamp_file.read_stamp_text(source);
   if (raw === void 0) return void 0;
-  try {
-    const parsed = reservation_schema.safeParse(JSON.parse(raw));
-    return parsed.success ? parsed.data : void 0;
-  } catch {
-    return void 0;
-  }
+  return json_value.parse_with(raw, reservation_schema);
 }
 function sweep_marker2(source) {
   try {
@@ -1136,6 +1240,17 @@ var CSPELL_CACHE_FLAGS = content_cache_flags(CSPELL_CACHE_FILE);
 
 // scripts/josh/josh-commands-backlog.ts
 var BACKLOG_COMMANDS = {
+  // Started from a terminal: the `backlogrun` keyword's launcher, and the board.
+  backlogrun: {
+    script: "scripts/backlog/backlogrun-cli.ts",
+    description: "Start a backlogrun in the background and show its board; with one already running, only show the board",
+    category: "AI tools",
+    reference: [
+      "[#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]",
+      "developer",
+      ["files", "network", "processes"]
+    ]
+  },
   "backlog:next": {
     script: "scripts/backlog/backlog-next.ts",
     description: "Order the whole opted-in backlog: auto-ok issues and the descendants of auto-ok epics, transitively through nested epics",
@@ -1166,7 +1281,7 @@ var BACKLOG_COMMANDS = {
   },
   "backlog:stalled": {
     script: "scripts/backlog/backlog-stalled-cli.ts",
-    // A stall sends one Telegram warning (joshuafolkken/kit#3357). The `Stop` hook calls the detector
+    // A stall sends one Telegram warning. The `Stop` hook calls the detector
     // directly, so this flag costs only the manual command its in-process dispatch.
     tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
     description: "Report whether ready backlog work is sitting undispatched with a free lane and no recent dispatch",
@@ -1261,7 +1376,7 @@ var ISSUE_COMMANDS = {
   },
   "defect:rate": {
     script: "scripts/issue/defect-rate-cli.ts",
-    description: "Print the defect rate of merged work: defects filed per behavior change completed",
+    description: "Print the defect rate of merged work: defects filed per enhancement completed",
     category: "AI tools",
     reference: ["[--days <n>]", "automation", ["network"]]
   },
@@ -1291,10 +1406,10 @@ var ISSUE_COMMANDS = {
   },
   "issue:file": {
     script: "scripts/issue/issue-file-cli.ts",
-    description: "File an Issue with every filing step: lint, Origin, WIP cap, duplicate scout, labels, then epic:bundle",
+    description: "File an Issue with every filing step: lint, Origin, fold, WIP cap, duplicate scout, labels, then epic:bundle",
     category: "AI tools",
     reference: [
-      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>] [--over-cap] [--no-auto-ok] [--release]",
+      "<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,\u2026>] [--over-cap] [--no-auto-ok] [--requested] [--release]",
       "automation",
       ["network"]
     ]
@@ -1371,18 +1486,27 @@ var LANE_COMMANDS = {
     category: "AI tools",
     reference: ["<issue> [--stash <message>]", "automation", ["files", "git", "processes"]]
   },
-  // The lane-limit measurement (joshuafolkken/kit#3355): `.env` is read so `lane:stats` labels the row
+  // 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": {
+    script: "scripts/lane/lane-limit-cli.ts",
+    tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+    description: "Change a live backlogrun\u2019s lane limit without stopping it, or print the limit, lanes in use and free lanes",
+    category: "AI tools",
+    reference: ["[<limit>] [--reset]", "developer", ["files"]]
+  },
+  // The lane-limit measurement: `.env` is read so `lane:stats` labels the row
   // with the `JOSH_LANE_LIMIT` a person set there.
   "lane:sample": {
     ...MEASURE_ARGUMENTS,
-    description: "Record the machine load (load average, swap, free memory, working lanes) to the lane ledger",
+    description: "Record the machine load (load average, swap, free memory, working lanes) to the lane ledger \u2014 a backlogrun samples itself, this is for a reading outside one",
     category: "AI tools",
     reference: ["[--every <seconds>]", "maintainer", ["files"]],
     default_script_arguments: ["sample"]
   },
   "lane:stats": {
     ...MEASURE_ARGUMENTS,
-    description: "Print one table row of lane throughput, gate duration and machine load over a period",
+    description: "Print one table row of lane throughput, gate duration and machine load over a period, and the per-stage durations of a lane under it",
     category: "AI tools",
     reference: ["--period <days> [--limit <lane-limit>]", "maintainer", ["none"]],
     default_script_arguments: ["stats"]
@@ -1414,12 +1538,18 @@ var RUN_COMMANDS = {
   "run:carry": {
     script: "scripts/run/carry/run-carry-cli.ts",
     // `--stopped` sends the stop confirmation, so the Telegram credentials come from `.env` as for
-    // `run:wake` below (joshuafolkken/kit#3357).
+    // `run:wake` below.
     tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
     description: "Carry one invocation\u2019s budget across its own session cuts",
     category: "AI tools",
     reference: ["<operation> [arguments...]", "automation", ["files"]]
   },
+  "run:add": {
+    script: "scripts/run/add/run-add-cli.ts",
+    description: "Add issues to a live backlogrun, ahead of the queue unless --no-priority",
+    category: "AI tools",
+    reference: ["<issue...> [--no-priority]", "automation", ["network", "files"]]
+  },
   "run:wake": {
     script: "scripts/run/wake/run-wake-cli.ts",
     // `.env` rather than the ambient environment:
@@ -1458,18 +1588,26 @@ var RUN_COMMANDS = {
       ["files"]
     ]
   },
+  "run:board": {
+    script: "scripts/run/board/run-board-cli.ts",
+    // `--every` pushes its frame as a Telegram, so the credentials come from `.env` as for `run:carry`.
+    tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+    description: "Draw a live board of the running backlogrun, redrawn every second",
+    category: "AI tools",
+    reference: ["[--once | --chat | --every <minutes>]", "automation", ["files", "network"]]
+  },
   "run:prep": {
     script: "scripts/run/run-prep-cli.ts",
     description: "Bundle a run\u2019s pre-edit reads: body, comments, state, dependency scope",
     category: "AI tools",
     reference: ["<issue>", "automation", ["network"]]
   },
-  // The entry sequence a lane opened on, folded into one call (joshuafolkken/kit#2372): claim the tree,
+  // The entry sequence a lane opened on, folded into one call: claim the tree,
   // read the budget, gather the issue reads and decide the pre-implementation step. `run:hold`,
   // `cost --cut`, `run:prep` and `run:step` were four round trips re-billing a lane's full context each.
   "run:entry": {
     script: "scripts/run/entry/run-entry-cli.ts",
-    // A `busy` hold or an `over` budget sends the stop confirmation (joshuafolkken/kit#3357).
+    // A `busy` hold or an `over` budget sends the stop confirmation.
     tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
     description: "Open a run in one call: claim the tree, read the budget, bundle the reads, decide the pre-implementation step",
     category: "AI tools",
@@ -1572,12 +1710,12 @@ var AI_COMMANDS = {
     reference: ["[options]", "maintainer", ["none"]],
     // Kit-only: it measures kit's own development runs and its report modules live under the
     // undistributed `scripts/time/`, so it means nothing in a consumer project and is dropped from a
-    // consumer's help (joshuafolkken/kit#1997). The runtime analysis hooks and guards rely on stays
+    // consumer's help. The runtime analysis hooks and guards rely on stays
     // distributed under `scripts/time-runtime/`.
     is_kit_only: true
   },
   // The tool-calls-per-round-trip density the batching guard is measured on, aggregated across the
-  // recent lane sessions (joshuafolkken/kit#2405). Kit-only for the same reason `time` is: it reads
+  // recent lane sessions. Kit-only for the same reason `time` is: it reads
   // kit's own lane transcripts and means nothing in a consumer project.
   "time:density": {
     script: "scripts/time/time-density-cli.ts",
@@ -1593,7 +1731,7 @@ var AI_COMMANDS = {
     reference: ["", "maintainer", ["none"]],
     // 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 (joshuafolkken/kit#2328), through the same declaration `josh time` uses for the same reason.
+    // help, through the same declaration `josh time` uses for the same reason.
     is_kit_only: true
   },
   "review:brief": {
@@ -1645,7 +1783,7 @@ var AI_COMMANDS = {
     category: "AI tools",
     reference: ["[--join]", "automation", ["processes", "files"]]
   },
-  // The post-merge sequence a run closed on, folded into one call (joshuafolkken/kit#2372): commit the
+  // The post-merge sequence a run closed on, folded into one call: commit the
   // observation ledger, read the completion citations and decide the release scope. `observations:flush`,
   // `issue:cite` and `release:scope` were three round trips re-billing the run's full context each.
   "run:tail": {
@@ -1654,7 +1792,7 @@ var AI_COMMANDS = {
     category: "AI tools",
     reference: ["[<issue> ...]", "automation", ["git", "network"]]
   },
-  // The commit-to-report region a run ships a change on, folded into one call (joshuafolkken/kit#2398):
+  // The commit-to-report region a run ships a change on, folded into one call:
   // the gate, the commit/push/PR (`git -y`), the CI-wait merge (`followup`) and the report bookkeeping
   // (`run:tail`) were four round trips re-billing the run's full context each. It stops at the first
   // failed step and names it, so the run reads only the step to fix.
@@ -1714,7 +1852,7 @@ var AI_COMMANDS = {
     category: "AI tools",
     reference: ["[scenario...]", "maintainer", ["processes", "network"]],
     // Kit-only: it replays kit's own distributed rules against real Claude sessions, so it means
-    // nothing in a consumer project and is dropped from a consumer's help (joshuafolkken/kit#1988).
+    // nothing in a consumer project and is dropped from a consumer's help.
     is_kit_only: true
   }
 };
@@ -1778,6 +1916,7 @@ var LINT_LABEL = "lint";
 var TYPE_CHECK_LABEL = "check";
 var UNIT_LABEL = "test:unit";
 var BEHAVIOR_LABEL = "behavior";
+var METRICS_LABEL = "metrics";
 var WARNING_CHECKER_LABELS = [LINT_LABEL, TYPE_CHECK_LABEL];
 var STATIC_CHECKS = [
   {
@@ -1799,18 +1938,31 @@ var STATIC_CHECKS = [
     memory_mb: core_budget.MEMORY_MB.spell_check
   },
   { label: BEHAVIOR_LABEL, target: BEHAVIOR_LABEL, reserved_cores: 0 },
-  // **The unused-member check reserves no core** (joshuafolkken/kit#2987): it builds one TypeScript
+  // **The unused-member check reserves no core**: it builds one TypeScript
   // 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", 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.
+  // It times no startup here: beside the unit suite that reads the load, not josh.
+  {
+    label: METRICS_LABEL,
+    target: METRICS_LABEL,
+    args: ["--no-startup"],
+    reserved_cores: 0,
+    memory_mb: core_budget.MEMORY_MB.eslint_scan,
+    is_kit_only: true
+  }
 ];
 var GATE_CHECKS = [
   ...STATIC_CHECKS,
   { label: UNIT_LABEL, target: UNIT_LABEL, reserved_cores: 0 }
 ];
-function select_gate_checks(is_unit_included) {
-  return is_unit_included ? GATE_CHECKS : STATIC_CHECKS;
+function select_gate_checks(is_unit_included, is_kit_repository = true) {
+  const checks = is_unit_included ? GATE_CHECKS : STATIC_CHECKS;
+  return is_kit_repository ? checks : checks.filter((check) => check.is_kit_only !== true);
 }
 function has_unit_check(checks) {
   return checks.some((check) => check.label === UNIT_LABEL);
@@ -1864,15 +2016,19 @@ function direct_unit_weight(available_cores = availableParallelism4(), live_runs
 function direct_unit_memory() {
   return unit_memory(direct_unit_weight());
 }
+function unit_cap_for(checks, available_cores, concurrent_runs) {
+  if (!has_unit_check(checks)) return void 0;
+  return resolve_unit_worker_cap(available_cores, concurrent_runs);
+}
 function plan_of(concurrency, unit_worker_cap, checks = GATE_CHECKS) {
   return { checks, concurrency, unit_worker_cap };
 }
-function resolve_gate_plan(available_cores = availableParallelism4(), concurrent_runs = unit_worker_share.SOLO_RUNS, is_unit_included = true) {
-  const checks = select_gate_checks(is_unit_included);
+function resolve_gate_plan(available_cores = availableParallelism4(), concurrent_runs = unit_worker_share.SOLO_RUNS, is_unit_included = true, is_kit_repository = true) {
+  const checks = select_gate_checks(is_unit_included, is_kit_repository);
   return {
     checks,
     concurrency: resolve_concurrency(available_cores, concurrent_runs, checks),
-    unit_worker_cap: is_unit_included ? resolve_unit_worker_cap(available_cores, concurrent_runs) : void 0
+    unit_worker_cap: unit_cap_for(checks, available_cores, concurrent_runs)
   };
 }
 function format_machine(available_cores, concurrent_runs) {
@@ -1896,6 +2052,7 @@ var gate_plan = {
   GATE_CHECKS,
   LINT_LABEL,
   MEASURED_CORES,
+  METRICS_LABEL,
   RESERVED_CORES,
   STATIC_CHECKS,
   TYPE_CHECK_LABEL,
@@ -1958,6 +2115,19 @@ var DEV_COMMANDS = {
     core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
     memory_mb: core_budget.MEMORY_MB.eslint_scan
   },
+  metrics: {
+    script: "scripts/metrics/metrics-command.ts",
+    description: "Print repository-wide quality totals and durations, and fail when a total grew past the merge-base or a duration past its baseline",
+    category: "Development",
+    reference: [
+      '[--no-startup | --totals-only | --accept --reason "<why>"]',
+      "developer",
+      ["files"]
+    ],
+    core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+    memory_mb: core_budget.MEMORY_MB.eslint_scan,
+    is_kit_only: true
+  },
   "refactor:scan": {
     script: "scripts/refactor/refactor-scan-cli.ts",
     description: "List refactoring candidates in the changed scope by category and answer clear/candidates",
@@ -1978,6 +2148,12 @@ var DEV_COMMANDS = {
     category: "AI tools",
     reference: ["[--refresh]", "developer", ["files"]]
   },
+  "rule:list": {
+    script: "scripts/rules/rule-list.ts",
+    description: "Print the trigger-delivered rules \u2014 each one's source, firing call and silent turn \u2014 from the guard rows",
+    category: "AI tools",
+    reference: ["", "automation", ["none"]]
+  },
   format: {
     script: "scripts/lint/format.ts",
     description: "Format code with prettier and eslint (skips a tool a basic project lacks)",
@@ -1998,8 +2174,8 @@ var DEV_COMMANDS = {
     // **No `tsx_arguments`, deliberately.** `JOSH_BATCH_GUARD` is a per-machine preference kept in
     // `.env`, which every other command reads through `OPTIONAL_ENV_FILE_FLAGS` — but declaring any
     // `tsx_arguments` disqualifies a command from in-process dispatch (`josh-in-process.ts`), and
-    // this one runs before every `Bash` call. That is the hot path joshuafolkken/kit#1342 took a
-    // second ~0.16 s tsx start off. The script calls `process.loadEnvFile` itself instead, which is
+    // this one runs before every `Bash` call, where a second ~0.16 s tsx start is not affordable.
+    // The script calls `process.loadEnvFile` itself instead, which is
     // node's own `--env-file` parser with node's own precedence.
   },
   "pretool:guard": {
@@ -2023,7 +2199,7 @@ var DEV_COMMANDS = {
   },
   "session:lang": {
     script: "scripts/josh/session-language-cli.ts",
-    description: "Claude Code hook: print the resolved JOSH_SESSION_LANG (defaults to ja) for the session context",
+    description: "Claude Code hook: print a non-default JOSH_SESSION_LANG for the session context, and the run:board reply rule while a backlogrun is live (otherwise nothing)",
     category: "Development",
     reference: ["", "automation", ["none"]]
     // **No `tsx_arguments`, deliberately**, the same as `batch:guard` above: this runs on every
@@ -2036,7 +2212,7 @@ var DEV_COMMANDS = {
     category: "Development",
     reference: ["<pretool|posttool>", "automation", ["none"]]
     // The live-source fallback `scripts/hooks/run-hook.sh` derives from the `codex-hook-adapter`
-    // bundle name (joshuafolkken/kit#3184). **No `tsx_arguments`**, the same as `pretool:guard`
+    // bundle name. **No `tsx_arguments`**, the same as `pretool:guard`
     // above: it runs before every guarded Codex call.
   },
   "cspell:dot": {
@@ -2390,16 +2566,16 @@ var VERSIONING_COMMANDS = {
     category: "Versioning",
     reference: ["", "developer", ["network"]]
   },
-  // The one place that decides a version (joshuafolkken/kit#1169). A `script` entry for the same
+  // The one place that decides a version. A `script` entry for the same
   // reason `ranges` is one: script paths resolve against the kit package root, so it keeps working
   // from a consumer repository where the file lives under node_modules.
   release: {
     script: "scripts/release/release-cli.ts",
     description: "Release the merges main has taken since the version last changed",
     category: "Versioning",
-    reference: ["[version]", "maintainer", ["git", "network", "release"]]
+    reference: ["[--dry-run]", "maintainer", ["git", "network", "release"]]
   },
-  // The read-only half of the one above (joshuafolkken/kit#1582). `release --dry-run` cannot
+  // The read-only half of the one above. `release --dry-run` cannot
   // answer this question: it refuses off the default branch and on a dirty tree, which is every
   // position a run asks it from. A `script` entry for the same reason `release` is one.
   "release:scope": {
@@ -2408,8 +2584,8 @@ var VERSIONING_COMMANDS = {
     category: "Versioning",
     reference: ["[--json]", "automation", ["none"]]
   },
-  // Run by the release workflows, kit's and the one sync distributes, after a tag has published
-  // (joshuafolkken/kit#3007). Settings come from the environment, so the workflow decides them.
+  // Run by the release workflows, kit's and the one sync distributes, after a tag has published.
+  // Settings come from the environment, so the workflow decides them.
   "release:github": {
     script: "scripts/release/github-release-cli.ts",
     description: "Create the GitHub Release for a published tag, with generated notes",
@@ -2437,20 +2613,17 @@ var WORKFLOW_COMMANDS = {
     reference: ["<message>", "developer", ["network"]],
     default_script_arguments: ["-y", "--skip-commit", "--skip-push"]
   },
-  // **The optional form, on both** (joshuafolkken/kit#1564). These two were the last commands
-  // passing the mandatory `--env-file=.env`, which node resolves before the script's first line: on
-  // a machine with no `.env` they died as `.env: not found` with exit code 9, even where
-  // `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` existed as real environment variables — a cloud
-  // session, and `followup` with them the merge step of every `fullrun` there. `doctor` was moved to
-  // this form for the same reason in joshuafolkken/kit#869.
+  // **The optional form, on both**. The mandatory `--env-file=.env` is resolved by node before the
+  // script's first line: on a machine with no `.env` it dies as `.env: not found` with exit code 9,
+  // even where `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` exist as real environment variables — a
+  // cloud session, and `followup` with them the merge step of every `fullrun` there.
   //
   // Nothing is lost by relaxing it: both scripts already load `.env` through `josh_environment_file`
   // themselves, so the file is read either way and node's precedence — an existing environment
   // variable wins over the file — is node's own in both spellings.
   //
-  // **What the mandatory flag was accidentally providing was noise**, and that is replaced rather
-  // than dropped: `telegram_notify.send` now throws on missing credentials and on a failed send, so
-  // `josh notify` exits non-zero instead of warning and answering 0.
+  // **A missing credential still fails loudly**: `telegram_notify.send` throws on missing credentials
+  // and on a failed send, so `josh notify` exits non-zero instead of warning and answering 0.
   followup: {
     script: "scripts/followup/git-followup-workflow.ts",
     description: "Follow-up git workflow",
@@ -2466,11 +2639,23 @@ var WORKFLOW_COMMANDS = {
     script: "scripts/notify/telegram-test.ts",
     description: "Send Telegram notification",
     category: "Workflow",
-    reference: ["--task-type <type> --body <text>", "automation", ["notifications"]],
+    reference: [
+      "[--task-type <type>] [--body <text> | --body-file <path>] [--issue-url <url>] [--pr-url <url>] [--issue-title <text>] [--repo-name <name>]",
+      "automation",
+      ["notifications"]
+    ],
     tsx_arguments: OPTIONAL_ENV_FILE_FLAGS
   },
-  // The observation ledger's commit path for the lines no run's own commit carried
-  // (joshuafolkken/kit#1756, joshuafolkken/kit#2763): a lane's lines sit in the primary checkout, which
+  // One observation-ledger sighting: the key's count, the append and the second-sighting verdict,
+  // which a run used to type as a `cat | grep -c` and judge by hand.
+  "observation:record": {
+    script: "scripts/observations/observation-record-cli.ts",
+    description: "Record an observation sighting and answer whether it is now filed",
+    category: "Workflow",
+    reference: ["<key> <depth> <where> <what> [--checkout <path>]", "automation", ["files"]]
+  },
+  // The observation ledger's commit path for the lines no run's own commit carried:
+  // a lane's lines sit in the primary checkout, which
   // its commit cannot see, and the recurrence count the promotion rule reads is a count of main.
   "observations:flush": {
     script: "scripts/observations/observations-flush-cli.ts",
@@ -2478,8 +2663,8 @@ var WORKFLOW_COMMANDS = {
     category: "Workflow",
     reference: ["", "automation", ["git", "network"]]
   },
-  // The one write path for a `/code-review` round's findings (joshuafolkken/kit#2325), plus the
-  // `--check` gate `followup` runs before it merges (joshuafolkken/kit#2343). It appends a `- rf:`
+  // The one write path for a `/code-review` round's findings, plus the
+  // `--check` gate `followup` runs before it merges. It appends a `- rf:`
   // line per finding — or one zero-finding line for a clean round — to the observation ledger, so
   // `observations:flush` commits them and the recurrence count survives the run.
   "review:record": {
@@ -2487,12 +2672,12 @@ var WORKFLOW_COMMANDS = {
     description: "Record a review round\u2019s findings, or check a round was recorded",
     category: "Workflow",
     reference: [
-      "--issue <N> [<category>:<severity>:<file> ...] | --check --issue <N>",
+      "--issue <N> [--comment] [<category>:<severity>:<file> ...] | --check --issue <N>",
       "automation",
-      ["files"]
+      ["files", "network"]
     ]
   },
-  // The reader over what `review:record` wrote (joshuafolkken/kit#2325): each recurring category’s
+  // The reader over what `review:record` wrote: each recurring category’s
   // count, and the number of zero-finding rounds that distinguishes a quiet category from an unwatched one.
   "review:findings": {
     script: "scripts/review/review-findings-cli.ts",
@@ -2501,7 +2686,7 @@ var WORKFLOW_COMMANDS = {
     reference: ["", "developer", ["files"]]
   },
   // After a behavior-change Issue merges, re-run its declared baseline and print before/after; a value
-  // that did not move appends a refuted-premise line to the observation ledger (joshuafolkken/kit#2212).
+  // that did not move appends a refuted-premise line to the observation ledger.
   "measure:rerun": {
     script: "scripts/issue/measure-rerun-cli.ts",
     description: "Re-run a merged issue\u2019s baseline command and print the before/after pair",
@@ -2509,7 +2694,7 @@ var WORKFLOW_COMMANDS = {
     reference: ["<issue-number>", "automation", ["network", "processes", "files"]]
   },
   // A script rather than an `sh -c` chain, because it has a precondition to enforce: run inside a
-  // linked work tree it would hijack the default branch from every other one (joshuafolkken/kit#1535).
+  // linked work tree it would hijack the default branch from every other one.
   "main:sync": {
     script: "scripts/git/main-sync.ts",
     description: "Checkout default branch, pull latest, and prune merged remote-gone branches (refuses inside a lane)",
@@ -2517,9 +2702,8 @@ var WORKFLOW_COMMANDS = {
     reference: ["", "developer", ["git", "network"]]
   },
   // A script rather than an `sh -c` chain, because the strategy has to be named rather than left to
-  // the caller's git configuration: the `git pull` this replaced aborted with `Need to specify how
-  // to reconcile divergent branches` on exactly the diverged branch the command exists for
-  // (joshuafolkken/kit#1659).
+  // 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.
   "main:merge": {
     script: "scripts/git/main-merge.ts",
     description: "Merge origin default branch into the current branch",
@@ -2555,6 +2739,7 @@ var ALIASES = {
   lr: "lint:related",
   ln: "lines",
   by: "bytes",
+  mt: "metrics",
   f: "format",
   sd: "cspell:dot",
   bh: "behavior",
@@ -2597,7 +2782,9 @@ var ALIASES = {
   ruv: "rule:value",
   ev: "eval",
   lsm: "lane:sample",
-  lst: "lane:stats"
+  lst: "lane:stats",
+  lli: "lane:limit",
+  blr: "backlogrun"
 };
 
 // scripts/josh/josh-composite-arguments.ts