@joshuafolkken/kit 1.1229.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";
@@ -319,7 +325,7 @@ function resolve_package_bin(base_directory, package_name, bin_name) {
 // scripts/gate/core-budget.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { readdirSync as readdirSync2 } from "node:fs";
-import { availableParallelism as availableParallelism2 } from "node:os";
+import { availableParallelism as availableParallelism3 } from "node:os";
 import path8 from "node:path";
 
 // scripts/josh/platform-temporary.ts
@@ -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,
@@ -712,6 +738,242 @@ var unit_worker_share = {
 
 // scripts/gate/core-budget.ts
 import { z as z4 } from "zod";
+
+// scripts/gate/core-admission.ts
+var MS_PER_SECOND = 1e3;
+var RAMP_UP_MS = 3e4;
+function compare_claim(left, right) {
+  const by_time = left.reservation.claimed_at - right.reservation.claimed_at;
+  return by_time === 0 ? left.key.localeCompare(right.key) : by_time;
+}
+function add_load(totals, reservation) {
+  totals.cores += reservation.weight;
+  totals.memory_mb += reservation.memory_mb ?? 0;
+}
+function exceeds(totals, budget) {
+  return totals.cores > budget.cores || totals.memory_mb > budget.memory_mb;
+}
+function admitted_keys(reservations, budget, memory_budget = Infinity) {
+  const limit = { cores: budget, memory_mb: memory_budget };
+  const totals = { cores: 0, memory_mb: 0 };
+  const admitted = /* @__PURE__ */ new Set();
+  for (const [index, entry] of reservations.toSorted(compare_claim).entries()) {
+    add_load(totals, entry.reservation);
+    if (index !== 0 && exceeds(totals, limit)) break;
+    admitted.add(entry.key);
+  }
+  return admitted;
+}
+function is_admitted(key, reservations, budget) {
+  return admitted_keys(reservations, budget.cores, budget.memory_mb).has(key);
+}
+function sum_load(reservations) {
+  const load = { cores: 0, memory_mb: 0 };
+  for (const entry of reservations) add_load(load, entry.reservation);
+  return load;
+}
+function is_ramped(reservation, now) {
+  const { admitted_at } = reservation;
+  return admitted_at !== void 0 && now - admitted_at >= RAMP_UP_MS;
+}
+function ledger_load(reservations, now) {
+  const admitted = reservations.filter((entry) => entry.reservation.admitted_at !== void 0);
+  const ramped = admitted.filter((entry) => is_ramped(entry.reservation, now));
+  return { cores: sum_load(admitted).cores, memory_mb: sum_load(ramped).memory_mb };
+}
+function total_weight(reservations) {
+  return sum_load(reservations).cores;
+}
+function admitted_load(reservations, budget) {
+  const admitted = admitted_keys(reservations, budget);
+  return total_weight(reservations.filter((entry) => admitted.has(entry.key)));
+}
+function describe_memory(ledger, budget) {
+  if (!Number.isFinite(budget.memory_mb)) return "";
+  return ` and ${String(Math.round(ledger.memory_mb))} MB of memory against ${String(Math.round(budget.memory_mb))} MB`;
+}
+function describe_overflow(admission) {
+  const { overflow } = admission;
+  if (overflow === void 0) return void 0;
+  const { ledger, budget } = overflow;
+  const waited = String(Math.round(overflow.waited_ms / MS_PER_SECOND));
+  const cores = `the ledger held ${String(ledger.cores)} cores against a budget of ${String(budget.cores)}`;
+  return `started past the core budget after ${waited}s \u2014 ${cores}${describe_memory(ledger, budget)}`;
+}
+var core_admission = {
+  RAMP_UP_MS,
+  admitted_keys,
+  admitted_load,
+  describe_overflow,
+  is_admitted,
+  ledger_load,
+  sum_load
+};
+
+// scripts/gate/machine-capacity.ts
+import { readFile } from "node:fs/promises";
+import { availableParallelism as availableParallelism2, cpus, totalmem } from "node:os";
+import { execa } from "execa";
+var SAMPLE_WINDOW_MS = 250;
+var BASELINE_CORES = 2;
+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 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;
+  for (const { times } of cpus()) {
+    busy += times.user + times.nice + times.sys + times.irq;
+    idle += times.idle;
+  }
+  return { busy, total: busy + idle };
+}
+function busy_share_between(before, after) {
+  const total = after.total - before.total;
+  if (total <= 0) return void 0;
+  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 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;
+}
+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 {
+    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();
+}
+async function default_sleep(ms) {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function read_machine(sleep = default_sleep) {
+  const before = cpu_times();
+  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: 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;
+  return Math.floor(Math.max(0, busy_cores - ledger_cores - BASELINE_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
+  };
+}
+var machine_capacity = {
+  BASELINE_CORES,
+  busy_cores_between,
+  busy_share_between,
+  external_cores,
+  machine_budget,
+  parse_darwin_memory,
+  parse_linux_available,
+  parse_linux_swapped,
+  read_machine,
+  read_memory,
+  read_sample,
+  swapped_between
+};
+
+// scripts/gate/core-budget.ts
 var RESERVED_PREFIX = "josh-core-reserved-";
 var RESERVED_SUFFIX = ".json";
 var POLL_INTERVAL_MS = 50;
@@ -723,11 +985,20 @@ var CORE_WEIGHTS = {
   spell_check: 1,
   eslint_scan: 1
 };
+var MEMORY_MB = {
+  lint: 2400,
+  type_check: 1300,
+  spell_check: 350,
+  eslint_scan: 2400,
+  unit_worker: 350
+};
 var HELD_KEY = "JOSH_CORE_RESERVED";
 var HELD_VALUE = "1";
 var reservation_schema = process_owner_schema.extend({
   weight: z4.number(),
-  claimed_at: z4.number()
+  claimed_at: z4.number(),
+  memory_mb: z4.number().optional(),
+  admitted_at: z4.number().optional()
 });
 function marker_name(key) {
   return `${RESERVED_PREFIX}${key}${RESERVED_SUFFIX}`;
@@ -738,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 {
@@ -760,7 +1026,9 @@ function live_reservation(source) {
 }
 function marker_files2(directory) {
   try {
-    return readdirSync2(directory).filter((name) => name.startsWith(RESERVED_PREFIX));
+    return readdirSync2(directory).filter(
+      (name) => name.startsWith(RESERVED_PREFIX) && name.endsWith(RESERVED_SUFFIX)
+    );
   } catch {
     return [];
   }
@@ -771,67 +1039,79 @@ function live_reservations(directory = PLATFORM_TEMP_ROOT) {
     return reservation === void 0 ? [] : { key: name, reservation };
   });
 }
-function compare_claim(left, right) {
-  const by_time = left.reservation.claimed_at - right.reservation.claimed_at;
-  return by_time === 0 ? left.key.localeCompare(right.key) : by_time;
-}
-function admitted_keys(reservations, budget) {
-  const admitted = /* @__PURE__ */ new Set();
-  let cumulative = 0;
-  for (const [index, entry] of reservations.toSorted(compare_claim).entries()) {
-    cumulative += entry.reservation.weight;
-    if (index !== 0 && cumulative > budget) break;
-    admitted.add(entry.key);
-  }
-  return admitted;
-}
-function is_admitted(key, reservations, budget) {
-  return admitted_keys(reservations, budget).has(key);
-}
-function admitted_load(reservations, budget) {
-  const admitted = admitted_keys(reservations, budget);
-  return reservations.filter((entry) => admitted.has(entry.key)).reduce((total, entry) => total + entry.reservation.weight, 0);
-}
 function normalize_budget(budget) {
   return Number.isFinite(budget) ? Math.max(MIN_BUDGET, Math.floor(budget)) : MIN_BUDGET;
 }
-async function default_sleep(ms) {
+async function default_sleep2(ms) {
   await new Promise((resolve) => {
     setTimeout(resolve, ms);
   });
 }
-function write_reservation(target, weight, claimed_at) {
-  stamp_file.write_stamp(target, { ...process_identity.own_fields(), weight, claimed_at });
+function write_reservation(target, fields) {
+  stamp_file.replace_stamp(target, { ...process_identity.own_fields(), ...fields });
 }
 function resolve_timing(options) {
   return {
     now: options.now ?? Date.now,
-    sleep: options.sleep ?? default_sleep,
-    poll_interval_ms: options.poll_interval_ms ?? POLL_INTERVAL_MS
+    sleep: options.sleep ?? default_sleep2,
+    poll_interval_ms: options.poll_interval_ms ?? POLL_INTERVAL_MS,
+    wait_cap_ms: options.wait_cap_ms ?? WAIT_CAP_MS
+  };
+}
+async function current_budget(context, reservations) {
+  if (reservations.length <= 1) return { cores: context.budget, memory_mb: Infinity };
+  const reading = await context.read_machine();
+  const ledger = core_admission.ledger_load(reservations, context.now());
+  const budget = machine_capacity.machine_budget(context.budget, reading, ledger);
+  return { ...budget, cores: normalize_budget(budget.cores) };
+}
+function admit(context, overflow) {
+  write_reservation(context.target, { ...context.fields, admitted_at: context.now() });
+  return { overflow };
+}
+function overflow_of(context, reservations, budget) {
+  return {
+    waited_ms: context.now() - context.fields.claimed_at,
+    ledger: core_admission.sum_load(reservations),
+    budget
   };
 }
+async function poll_admission(context) {
+  const reservations = live_reservations(context.directory);
+  const budget = await current_budget(context, reservations);
+  if (core_admission.is_admitted(context.key, reservations, budget)) return admit(context);
+  if (context.now() >= context.deadline) {
+    return admit(context, overflow_of(context, reservations, budget));
+  }
+  return void 0;
+}
 async function await_admission(context) {
-  while (!is_admitted(context.key, live_reservations(context.directory), context.budget)) {
-    if (context.now() >= context.deadline) return;
+  let admission = await poll_admission(context);
+  while (admission === void 0) {
     await context.sleep(context.poll_interval_ms);
+    admission = await poll_admission(context);
   }
+  return admission;
 }
 async function reserve(weight, options = {}) {
   const timing = resolve_timing(options);
   const directory = options.directory ?? PLATFORM_TEMP_ROOT;
-  const budget = normalize_budget(options.budget ?? availableParallelism2());
   const claimed_at = timing.now();
   const name = marker_name(randomUUID3());
   const target = path8.join(directory, name);
-  write_reservation(target, weight, claimed_at);
-  await await_admission({
+  const fields = { weight, claimed_at, memory_mb: options.memory_mb };
+  write_reservation(target, fields);
+  const admission = await await_admission({
     ...timing,
     key: name,
+    target,
     directory,
-    budget,
-    deadline: claimed_at + (options.wait_cap_ms ?? WAIT_CAP_MS)
+    budget: normalize_budget(options.budget ?? availableParallelism3()),
+    deadline: claimed_at + timing.wait_cap_ms,
+    fields,
+    read_machine: options.read_machine ?? machine_capacity.read_machine
   });
-  return { target };
+  return { target, admission };
 }
 function release(handle) {
   sweep_marker2(handle.target);
@@ -839,7 +1119,7 @@ function release(handle) {
 async function with_core_reservation(weight, run2, options = {}) {
   const handle = await reserve(weight, options);
   try {
-    return await run2();
+    return await run2(handle.admission);
   } finally {
     release(handle);
   }
@@ -867,9 +1147,11 @@ var core_budget = {
   CORE_WEIGHTS,
   HELD_KEY,
   HELD_VALUE,
+  MEMORY_MB,
   RESERVED_PREFIX,
-  admitted_keys,
-  admitted_load,
+  admitted_keys: core_admission.admitted_keys,
+  admitted_load: core_admission.admitted_load,
+  describe_overflow: core_admission.describe_overflow,
   is_held,
   live_reservations,
   release,
@@ -958,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",
@@ -988,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",
@@ -1083,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"]]
   },
@@ -1113,13 +1406,19 @@ 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]",
+      "<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"]
     ]
+  },
+  "issue:release": {
+    script: "scripts/issue/issue-release-cli.ts",
+    description: "Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+    category: "AI tools",
+    reference: ["<issue>", "automation", ["network"]]
   }
 };
 
@@ -1155,7 +1454,7 @@ var LANE_COMMANDS = {
   },
   "lane:prune": {
     ...LANE_ARGUMENTS,
-    description: "Close every lane an interruption left without its work tree",
+    description: "Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root",
     category: "AI tools",
     reference: ["", "automation", ["files", "git"]],
     default_script_arguments: ["prune"]
@@ -1187,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"]
@@ -1230,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:
@@ -1274,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",
@@ -1388,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",
@@ -1409,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": {
@@ -1461,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": {
@@ -1470,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.
@@ -1530,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
   }
 };
@@ -1546,7 +1868,7 @@ var CLONE_COMMANDS = {
 };
 
 // scripts/gate/gate-plan.ts
-import { availableParallelism as availableParallelism3 } from "node:os";
+import { availableParallelism as availableParallelism4 } from "node:os";
 
 // scripts/lib/status-icons.ts
 var FAIL_ICON = "\u2717";
@@ -1594,28 +1916,53 @@ 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 = [
-  { label: LINT_LABEL, target: "lint", reserved_cores: core_budget.CORE_WEIGHTS.lint },
+  {
+    label: LINT_LABEL,
+    target: "lint",
+    reserved_cores: core_budget.CORE_WEIGHTS.lint,
+    memory_mb: core_budget.MEMORY_MB.lint
+  },
   {
     label: TYPE_CHECK_LABEL,
     target: "check",
-    reserved_cores: core_budget.CORE_WEIGHTS.type_check
+    reserved_cores: core_budget.CORE_WEIGHTS.type_check,
+    memory_mb: core_budget.MEMORY_MB.type_check
+  },
+  {
+    label: "cspell",
+    target: "cspell:dot",
+    reserved_cores: core_budget.CORE_WEIGHTS.spell_check,
+    memory_mb: core_budget.MEMORY_MB.spell_check
   },
-  { label: "cspell", target: "cspell:dot", reserved_cores: core_budget.CORE_WEIGHTS.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);
@@ -1655,19 +2002,33 @@ function check_weight(check, plan, available_cores) {
   if (check.label !== UNIT_LABEL) return check.reserved_cores;
   return plan.unit_worker_cap ?? solo_unit_weight(available_cores);
 }
-function direct_unit_weight(available_cores = availableParallelism3(), live_runs = unit_worker_share.live_run_count()) {
+function unit_memory(workers) {
+  return workers * core_budget.MEMORY_MB.unit_worker;
+}
+function check_memory(check, plan, available_cores) {
+  if (check.label !== UNIT_LABEL) return check.memory_mb ?? 0;
+  return unit_memory(check_weight(check, plan, available_cores));
+}
+function direct_unit_weight(available_cores = availableParallelism4(), live_runs = unit_worker_share.live_run_count()) {
   const weight = unit_worker_share.current_share(available_cores, live_runs) ?? solo_unit_weight(available_cores);
   return Math.max(unit_worker_share.MIN_WORKERS, weight);
 }
+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 = availableParallelism3(), 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) {
@@ -1680,7 +2041,7 @@ function format_unit_cap(plan) {
   if (plan.unit_worker_cap === void 0) return `${UNIT_LABEL} unrestricted`;
   return `${UNIT_LABEL} at ${String(plan.unit_worker_cap)} workers`;
 }
-function format_gate_plan(plan, available_cores = availableParallelism3(), concurrent_runs = unit_worker_share.SOLO_RUNS) {
+function format_gate_plan(plan, available_cores = availableParallelism4(), concurrent_runs = unit_worker_share.SOLO_RUNS) {
   const cap = format_unit_cap(plan);
   const count = `${String(plan.concurrency)} of ${String(plan.checks.length)}`;
   const width = `${count}${josh_verdict.GATE_OPENING_MARK}`;
@@ -1691,12 +2052,15 @@ var gate_plan = {
   GATE_CHECKS,
   LINT_LABEL,
   MEASURED_CORES,
+  METRICS_LABEL,
   RESERVED_CORES,
   STATIC_CHECKS,
   TYPE_CHECK_LABEL,
   UNIT_LABEL,
   WARNING_CHECKER_LABELS,
+  check_memory,
   check_weight,
+  direct_unit_memory,
   direct_unit_weight,
   format_gate_plan,
   format_machine,
@@ -1732,28 +2096,45 @@ var DEV_COMMANDS = {
     description: "Check code with prettier and eslint (skips a tool a basic project lacks)",
     category: "Development",
     reference: ["", "developer", ["processes"]],
-    core_weight: core_budget.CORE_WEIGHTS.lint
+    core_weight: core_budget.CORE_WEIGHTS.lint,
+    memory_mb: core_budget.MEMORY_MB.lint
   },
   "lint:related": {
     script: "scripts/lint/lint-related.ts",
     description: "Check only the changed files with prettier and eslint (whole tree on fallback)",
     category: "Development",
     reference: [FILE_ARGUMENTS, "developer", ["processes"]],
-    core_weight: core_budget.CORE_WEIGHTS.lint
+    core_weight: core_budget.CORE_WEIGHTS.lint,
+    memory_mb: core_budget.MEMORY_MB.lint
   },
   lines: {
     script: "scripts/lines/lines-command.ts",
     description: "Print a file's code lines against the max-lines limit and the headroom left",
     category: "Development",
     reference: [REQUIRED_FILE_ARGUMENTS, "developer", ["none"]],
-    core_weight: core_budget.CORE_WEIGHTS.eslint_scan
+    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",
     category: "Development",
     reference: ["", "automation", ["processes"]],
-    core_weight: core_budget.CORE_WEIGHTS.eslint_scan
+    core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+    memory_mb: core_budget.MEMORY_MB.eslint_scan
   },
   bytes: {
     script: "scripts/lines/bytes-command.ts",
@@ -1767,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)",
@@ -1787,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": {
@@ -1812,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
@@ -1825,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": {
@@ -1833,7 +2220,8 @@ var DEV_COMMANDS = {
     description: "Run spell check including dotfiles",
     category: "Development",
     reference: ["", "developer", ["processes"]],
-    core_weight: core_budget.CORE_WEIGHTS.spell_check
+    core_weight: core_budget.CORE_WEIGHTS.spell_check,
+    memory_mb: core_budget.MEMORY_MB.spell_check
   },
   behavior: {
     script: "scripts/behavior/behavior-cli.ts",
@@ -1852,14 +2240,16 @@ var DEV_COMMANDS = {
     description: "Run unit tests with Vitest (skips when Vitest is absent; fails when it has no tests)",
     category: "Development",
     reference: [FILTER_ARGUMENTS, "developer", ["processes"]],
-    core_weight: gate_plan.direct_unit_weight
+    core_weight: gate_plan.direct_unit_weight,
+    memory_mb: gate_plan.direct_unit_memory
   },
   "test:related": {
     script: "scripts/test/test-related.ts",
     description: "Run only the unit tests related to the changed files (full suite on fallback)",
     category: "Development",
     reference: [FILE_ARGUMENTS, "developer", ["processes"]],
-    core_weight: gate_plan.direct_unit_weight
+    core_weight: gate_plan.direct_unit_weight,
+    memory_mb: gate_plan.direct_unit_memory
   },
   "test:declared": {
     script: "scripts/test/test-declared.ts",
@@ -1903,7 +2293,8 @@ var DEV_COMMANDS = {
     description: "Type-check with tsc (skips a basic project with no TypeScript to check)",
     category: "Development",
     reference: ["[arguments...]", "developer", ["processes"]],
-    core_weight: core_budget.CORE_WEIGHTS.type_check
+    core_weight: core_budget.CORE_WEIGHTS.type_check,
+    memory_mb: core_budget.MEMORY_MB.type_check
   },
   port: {
     script: "scripts/ports/port-command.ts",
@@ -2024,9 +2415,9 @@ var MAINTENANCE_COMMANDS = {
     shell: [
       "sh",
       "-c",
-      "export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:corepack && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:scope --record"
+      "export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:corepack && pnpm josh latest:scope --record"
     ],
-    description: "Update pnpm, dependencies, and run security audit",
+    description: "Update dependencies, run security audit, then update pnpm",
     category: "Maintenance",
     reference: ["", "developer", ["files", "network", "processes"]],
     argument_targets: ["latest:corepack", "latest:update", "audit"]
@@ -2175,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": {
@@ -2193,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",
@@ -2222,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",
@@ -2251,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",
@@ -2263,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": {
@@ -2272,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",
@@ -2286,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",
@@ -2294,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)",
@@ -2302,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",
@@ -2340,6 +2739,7 @@ var ALIASES = {
   lr: "lint:related",
   ln: "lines",
   by: "bytes",
+  mt: "metrics",
   f: "format",
   sd: "cspell:dot",
   bh: "behavior",
@@ -2382,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
@@ -2745,15 +3147,16 @@ async function run_entry(entry, subcommand_arguments) {
   if (entry.shell) return run_shell_command(entry.shell, subcommand_arguments);
   return await run_script_entry(entry, subcommand_arguments);
 }
-function command_weight(entry) {
-  return typeof entry.core_weight === "function" ? entry.core_weight() : entry.core_weight;
+function declared(value) {
+  return typeof value === "function" ? value() : value;
 }
 async function dispatch_entry(entry, subcommand_arguments) {
-  const weight = command_weight(entry);
+  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)
+    async () => await run_entry(entry, subcommand_arguments),
+    { memory_mb: declared(entry.memory_mb) }
   );
 }
 async function run_command(cmd, subcommand_arguments, is_consumer = false) {