@cosmicdrift/kumiko-guards 0.395.0 → 0.397.0

package/README.md

@@ -76,10 +76,15 @@ the pushing repo only; in a standalone clone it runs the repo's own
 workspace it runs a tracked `scripts/check-wt.sh` if present, otherwise the
 worktree's own `package.json` scripts `typecheck`, `lint`, `test`, and
 `test:dom` (whichever are declared), directly in the worktree — the parent's
-`bun check` would otherwise check the main checkout instead. There is no
-bypass switch. A `check-wt.sh` that wraps this hook (via `exec` or as a child
-process) is recognised by process ancestry, so the hook does not call it
-again; an exported variable cannot skip it.
+`bun check` would otherwise check the main checkout instead — followed by
+`kumiko-guards guards`, `ui` (only with non-empty `uiRoots` in `kumiko.json`,
+as in `kumiko check`), `checks`, `comment-lang` and `public-exports-changelog`.
+The repo that ships this package runs its checked-out `packages/guards/src/cli.ts`
+for these. There is no bypass switch. A `check-wt.sh` that wraps this hook (via
+`exec` or as a child process) is recognised by process ancestry, so the hook
+does not call it again and skips the pre-flight steps (`pre-push-extra.sh`,
+upgrade-state guard, gitleaks) the outer run already did; an exported variable
+cannot skip either.
 
 Extension point: a tracked, executable `scripts/pre-push-extra.sh` runs
 before the main check in every branch (worktree, parent-scoped, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.395.0",
+  "version": "0.397.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.395.0",
+    "@cosmicdrift/kumiko-types": "0.397.0",
     "ts-morph": "^28.0.0",
     "zod": "^4.6.7"
   },
@@ -52,7 +52,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.395.0"
+    "@cosmicdrift/kumiko-framework": "0.397.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-framework": {
@@ -60,6 +60,6 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-framework": "0.395.0"
+    "@cosmicdrift/kumiko-framework": "0.397.0"
   }
 }

package/src/_lib/test-es-raw-writes.ts

@@ -21,8 +21,13 @@ const LITERAL_WRITE_RE =
   /\b(?:DELETE\s+FROM\s+"?(?:read_\w+|kumiko_events)|UPDATE\s+"?read_\w+)\b/i;
 const TEMPLATE_WRITE_RE = /\b(?:DELETE\s+FROM|UPDATE)\s+"?\$\{\s*(\w+)(?:\.tableName)?\s*\}/gi;
 
+// Both write patterns start like this; a literal's text is part of the file's, so a
+// file without it has nothing to report.
+const SQL_WRITE_START_RE = /\b(?:DELETE\s+FROM|UPDATE)\s/i;
+
 function entityTableBindings(sourceFile: SourceFile): Set<string> {
   const names = new Set<string>();
+  if (!sourceFile.getFullText().includes("buildEntityTable")) return names;
   for (const decl of sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration)) {
     const init = decl.getInitializer();
     if (
@@ -51,8 +56,9 @@ function writesEventSourcedTable(node: Node, entityTables: ReadonlySet<string>):
 }
 
 export function findRawSqlWrites(sourceFile: SourceFile): RawWriteFinding[] {
-  const entityTables = entityTableBindings(sourceFile);
   const findings: RawWriteFinding[] = [];
+  if (!SQL_WRITE_START_RE.test(sourceFile.getFullText())) return findings;
+  const entityTables = entityTableBindings(sourceFile);
   for (const kind of [
     SyntaxKind.StringLiteral,
     SyntaxKind.NoSubstitutionTemplateLiteral,

package/src/changes.json

@@ -1,4 +1,22 @@
 [
+  {
+    "version": "0.396.0",
+    "type": "improvement",
+    "title": "Faster guard suite through text prefilters",
+    "detail": "RLS-Session-Settings, Internal-Subpath-Imports, Test-ES-Fixtures and Test-ES-Row-Writes walked every node of every scanned file. Each now first checks the file text for the tokens its rules need (for example kumiko. or set_config, createTenantDb, kumiko_events, DELETE FROM or UPDATE) and skips the walk when none appears; Internal-Subpath-Imports keeps walking any file with a unicode escape, which could spell a name without its plain text. Findings are unchanged: the suites report the same results on kumiko-framework, kumiko-enterprise and publicstatus before and after."
+  },
+  {
+    "version": "0.396.0",
+    "type": "improvement",
+    "title": "pre-push runs its worktree steps in parallel",
+    "detail": "The worktree branch without check-wt.sh now hands typecheck, lint, test, the guard suites, comment-lang and public-exports-changelog to the new run-steps-parallel.ts next to the hook. test:dom stays behind test in the same lane, every step still runs after a failure, and each step's output is printed as one block when it finishes. The failure line keeps its form (worktree check failed: <steps>). The pool follows the free CPU capacity with a floor of four lanes; KUMIKO_PRE_PUSH_POOL overrides it."
+  },
+  {
+    "version": "0.396.0",
+    "type": "fix",
+    "title": "pre-push runs its pre-flight steps once per push",
+    "detail": "When the hook delegated to a tracked scripts/check-wt.sh that wraps the hook again, the inner run repeated pre-push-extra.sh, the upgrade-state guard and the gitleaks scan, and that second scan only covered HEAD because git's stdin was already read. A re-entry recognised by process ancestry now skips these steps; a check-wt.sh run by hand still runs them once. The worktree branch without check-wt.sh adds kumiko-guards ui when kumiko.json declares non-empty uiRoots, and in the repo that ships kumiko-guards it runs the checked-out packages/guards/src/cli.ts instead of a node_modules bin."
+  },
   {
     "version": "0.394.0",
     "type": "fix",

package/src/guard-internal-subpath-imports.ts

@@ -72,6 +72,13 @@ const FORWARDED_TENANT_DB_REASON_ALLOWLIST = [
 
 type Finding = { line: number; message: string };
 
+// Skips a full-tree walk when no name it looks for appears in the file. A unicode
+// escape could spell a name without its plain text, so any `\u` keeps the walk.
+function mayMention(sf: SourceFile, names: readonly string[]): boolean {
+  const text = sf.getFullText();
+  return text.includes("\\u") || names.some((name) => text.includes(name));
+}
+
 function isTestFile(rel: string): boolean {
   return rel.split("/").includes("__tests__") || TEST_FILE_RE.test(rel);
 }
@@ -196,6 +203,7 @@ function reasonSymbolOf(callee: Node, locals: ReadonlyMap<string, string>): stri
 
 function findReasonViolations(sf: SourceFile): Finding[] {
   const findings: Finding[] = [];
+  if (!mayMention(sf, Object.keys(REASON_ARG_INDEX))) return findings;
   const locals = localNamesOf(sf, new Set(Object.keys(REASON_ARG_INDEX)));
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const callee = call.getExpression();
@@ -219,6 +227,7 @@ function isSystemModeProperty(prop: Node): boolean {
 
 function findTenantDbReasonViolations(sf: SourceFile): Finding[] {
   const findings: Finding[] = [];
+  if (!mayMention(sf, ["createTenantDb"])) return findings;
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const callee = call.getExpression();
     const calleeName =
@@ -241,6 +250,7 @@ function findTenantDbReasonViolations(sf: SourceFile): Finding[] {
 }
 
 function findFixedScopeUses(sf: SourceFile): Finding[] {
+  if (!sf.getFullText().includes(FIXED_SCOPE_SYMBOL)) return [];
   return sf
     .getDescendantsOfKind(SyntaxKind.Identifier)
     .filter((id) => id.getText() === FIXED_SCOPE_SYMBOL)

package/src/guard-rls-session-settings.ts

@@ -140,8 +140,12 @@ function isStringLike(node: Node): boolean {
   );
 }
 
+// Every rule needs "kumiko." or "set_config" in a literal, and a literal's text is part of the file's.
+const MENTIONS_RLS_SETTING_RE = /kumiko\.|set_config/i;
+
 function findSessionSettings(sf: SourceFile, rel: string) {
   const found: Array<{ line: number; message: string }> = [];
+  if (!MENTIONS_RLS_SETTING_RE.test(sf.getFullText())) return found;
   for (const node of sf.getDescendants()) {
     if (!isStringLike(node)) continue;
     // A template's own spans are visited as separate nodes; its full text is checked once here.

package/src/guard-test-es-fixtures.ts

@@ -59,6 +59,8 @@ function violationMessage(text: string): string | undefined {
 function collect(sourceFile: SourceFile, roots: readonly RepoRoot[]): GuardViolation[] {
   const file = relFromRepoRoot(sourceFile.getFilePath(), roots);
   if (ALLOWLIST.some((re) => re.test(file))) return [];
+  // Both rules need one of these table names in a literal, which is part of the file's text.
+  if (!/kumiko_events|read_tenant_memberships/i.test(sourceFile.getFullText())) return [];
   const violations: GuardViolation[] = [];
   for (const kind of LITERAL_KINDS) {
     for (const node of sourceFile.getDescendantsOfKind(kind)) {

package/src/guard-test-es-row-writes.ts

@@ -127,10 +127,13 @@ function collect(sourceFile: SourceFile, roots: readonly RepoRoot[]): GuardViola
   if (ALLOWLIST.some((re) => re.test(file))) return [];
   const bypass = helperBindings(sourceFile, BYPASS_NAMES);
   const seedRow = helperBindings(sourceFile, SEED_ROW_NAMES);
-  const bypassCalls = sourceFile
-    .getDescendantsOfKind(SyntaxKind.CallExpression)
-    .filter((call) => isHelperCallee(call.getExpression(), bypass))
-    .map((call) => ({ line: call.getStartLineNumber(), message: MESSAGE }));
+  const importsBypass = bypass.names.size > 0 || bypass.namespaces.size > 0;
+  const bypassCalls = importsBypass
+    ? sourceFile
+        .getDescendantsOfKind(SyntaxKind.CallExpression)
+        .filter((call) => isHelperCallee(call.getExpression(), bypass))
+        .map((call) => ({ line: call.getStartLineNumber(), message: MESSAGE }))
+    : [];
   return [
     ...bypassCalls,
     ...findSeedRowOnEntityTables(sourceFile, (callee) => isHelperCallee(callee, seedRow)),

package/src/pre-push.sh

@@ -7,7 +7,8 @@
 #   2. Else if running inside a worktree under the parent workspace (no
 #      check-wt.sh), run this worktree's own package.json scripts
 #      (typecheck, lint, test, test:dom) plus the consumer-CI guards
-#      (kumiko-guards guards/checks/comment-lang) directly —
+#      (kumiko-guards guards/ui/checks/comment-lang) directly, in parallel
+#      lanes via run-steps-parallel.ts —
 #      the parent's `bun check` would otherwise check the main checkout
 #      instead of the worktree.
 #   3. Else if running inside the cosmicdriftgamestudio Parent-Workspace,
@@ -24,6 +25,10 @@
 # Extension point: a tracked, executable scripts/pre-push-extra.sh runs
 # before the main check in every branch above, with KUMIKO_PUSH_REPO_ROOT
 # and KUMIKO_PUSH_PARENT_DIR available inline (never exported).
+#
+# The pre-flight steps (pre-push-extra.sh, upgrade-state guard, gitleaks) run
+# once per push: a re-entry from the wrapping check-wt.sh skips them, because
+# the outer run already did them before delegating.
 
 # Git exports GIT_DIR & co. to hooks; nothing this hook starts may inherit them,
 # or a test's fixture git calls write into this repo.
@@ -77,7 +82,36 @@ has_package_script() {
   ' "$REPO_ROOT/package.json" "$1") >/dev/null 2>&1
 }
 
-if git -C "$REPO_ROOT" ls-files --error-unmatch scripts/pre-push-extra.sh >/dev/null 2>&1 \
+# Same rule as `kumiko check`: the UI guards run only for declared, non-empty uiRoots.
+has_ui_roots() {
+  (cd / && bun -e '
+    const manifest = await Bun.file(process.argv[1]).json().catch(() => null);
+    process.exit(Array.isArray(manifest?.uiRoots) && manifest.uiRoots.length > 0 ? 0 : 1);
+  ' "$REPO_ROOT/kumiko.json") >/dev/null 2>&1
+}
+
+# Re-entry from the wrapping check-wt.sh is detected by process ancestry: the
+# hook records its own PID in KUMIKO_CHECK_WT_OWNER before delegating, so a
+# freely exported variable can neither skip the tracked check-wt.sh nor the
+# pre-flight steps below.
+is_reentry_from_check_wt() {
+  reentry_pid=$$
+  case "${KUMIKO_CHECK_WT_OWNER:-}" in '' | *[!0-9]*) return 1 ;; esac
+  while [ -n "$reentry_pid" ] && [ "$reentry_pid" -gt 1 ]; do
+    [ "$reentry_pid" = "$KUMIKO_CHECK_WT_OWNER" ] && return 0
+    reentry_pid=$(ps -o ppid= -p "$reentry_pid" 2>/dev/null | tr -d ' ')
+  done
+  return 1
+}
+
+CHECK_WT_REENTRY=0
+if is_reentry_from_check_wt; then
+  CHECK_WT_REENTRY=1
+  echo "[pre-push] re-entered from scripts/check-wt.sh — pre-push-extra.sh, upgrade-state guard and secret scan already ran in the outer hook"
+fi
+
+if [ "$CHECK_WT_REENTRY" = 0 ] \
+   && git -C "$REPO_ROOT" ls-files --error-unmatch scripts/pre-push-extra.sh >/dev/null 2>&1 \
    && [ -x "$REPO_ROOT/scripts/pre-push-extra.sh" ]; then
   echo "[pre-push] running scripts/pre-push-extra.sh…"
   (cd "$REPO_ROOT" && KUMIKO_PUSH_REPO_ROOT="$REPO_ROOT" KUMIKO_PUSH_PARENT_DIR="$PARENT_DIR" "$REPO_ROOT/scripts/pre-push-extra.sh" "$@") || exit 1
@@ -100,7 +134,7 @@ resolve_script_dir() {
   cd -P "$(dirname "$SOURCE")" >/dev/null 2>&1 && pwd
 }
 
-if [ -f "$REPO_ROOT/.kumiko/upgrade-state.json" ]; then
+if [ "$CHECK_WT_REENTRY" = 0 ] && [ -f "$REPO_ROOT/.kumiko/upgrade-state.json" ]; then
   SCRIPT_DIR="$(resolve_script_dir "$0")"
   GUARD_UPGRADE_STATE="$SCRIPT_DIR/guard-upgrade-state.ts"
   if [ ! -f "$GUARD_UPGRADE_STATE" ]; then
@@ -118,7 +152,9 @@ fi
 # caught in seconds, not after the long checks. A missing binary or a missing
 # origin/main only warns, so a machine without gitleaks is not locked out.
 # No --config: gitleaks reads a .gitleaks.toml in the repo root itself.
-if ! command -v gitleaks >/dev/null 2>&1; then
+if [ "$CHECK_WT_REENTRY" = 1 ]; then
+  : # the outer hook scanned the pushed refs from git's stdin
+elif ! command -v gitleaks >/dev/null 2>&1; then
   echo "[pre-push] gitleaks not installed — secret scan skipped. Install: brew install gitleaks" >&2
 elif ! git -C "$REPO_ROOT" rev-parse --verify --quiet origin/main >/dev/null 2>&1; then
   echo "[pre-push] origin/main not found — secret scan skipped" >&2
@@ -151,20 +187,7 @@ fi
 # canonical sibling path instead of this worktree — checking the wrong
 # code. Run the worktree-local check only when scripts/check-wt.sh is
 # tracked and executable (untracked/symlink stubs must not hijack push).
-# Re-entry from the wrapping check-wt.sh is detected by process ancestry: the
-# hook records its own PID in KUMIKO_CHECK_WT_OWNER before delegating, so a
-# freely exported variable cannot skip the tracked check-wt.sh.
-is_reentry_from_check_wt() {
-  reentry_pid=$$
-  case "${KUMIKO_CHECK_WT_OWNER:-}" in '' | *[!0-9]*) return 1 ;; esac
-  while [ -n "$reentry_pid" ] && [ "$reentry_pid" -gt 1 ]; do
-    [ "$reentry_pid" = "$KUMIKO_CHECK_WT_OWNER" ] && return 0
-    reentry_pid=$(ps -o ppid= -p "$reentry_pid" 2>/dev/null | tr -d ' ')
-  done
-  return 1
-}
-
-if ! is_reentry_from_check_wt \
+if [ "$CHECK_WT_REENTRY" = 0 ] \
    && [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
    && git -C "$REPO_ROOT" ls-files --error-unmatch scripts/check-wt.sh >/dev/null 2>&1 \
    && [ -x "$REPO_ROOT/scripts/check-wt.sh" ]; then
@@ -172,24 +195,44 @@ if ! is_reentry_from_check_wt \
   cd "$REPO_ROOT" && KUMIKO_CHECK_WT_OWNER=$$ exec "$REPO_ROOT/scripts/check-wt.sh"
 fi
 
+# The repo that ships kumiko-guards runs its checked-out cli.ts, so a push checks
+# the branch's own guards even when node_modules/.bin resolves to another checkout.
+is_kumiko_guards_repo() {
+  [ -f "$REPO_ROOT/packages/guards/src/cli.ts" ] \
+    && grep -q '"name": *"@cosmicdrift/kumiko-guards"' "$REPO_ROOT/packages/guards/package.json" 2>/dev/null
+}
+
 # Runs a guard bin from the worktree's or the parent's node_modules/.bin
 # (same guards consumer CI runs); an unresolvable bin is skipped, not fatal.
-run_guard_bin() {
+add_guard_step() {
   GUARD_LABEL="$1"
   GUARD_BIN="$2"
-  shift 2
+  GUARD_ARGS="$3"
+  if [ "$GUARD_BIN" = "kumiko-guards" ] && is_kumiko_guards_repo; then
+    add_step --step "$GUARD_LABEL" "bun $(shell_quote "$REPO_ROOT/packages/guards/src/cli.ts") $GUARD_ARGS"
+    return 0
+  fi
   for GUARD_CANDIDATE in "$REPO_ROOT/node_modules/.bin/$GUARD_BIN" "$PARENT_DIR/node_modules/.bin/$GUARD_BIN"; do
     if [ -x "$GUARD_CANDIDATE" ]; then
-      echo "[pre-push] $GUARD_BIN $*"
-      if ! "$GUARD_CANDIDATE" "$@"; then
-        FAILED="$FAILED $GUARD_LABEL"
-      fi
+      add_step --step "$GUARD_LABEL" "$(shell_quote "$GUARD_CANDIDATE") $GUARD_ARGS"
       return 0
     fi
   done
   echo "[pre-push] $GUARD_BIN: not resolvable in worktree/parent, skipped"
 }
 
+shell_quote() {
+  printf "'%s'" "$(printf '%s' "$1" | sed "s/'/'\\\\''/g")"
+}
+
+# POSIX sh has no arrays: the runner's argv is collected as one quoted string.
+STEP_ARGS=""
+add_step() {
+  for STEP_ARG in "$@"; do
+    STEP_ARGS="$STEP_ARGS $(shell_quote "$STEP_ARG")"
+  done
+}
+
 # infra#899: no tracked scripts/check-wt.sh — the parent-scoped `bun check`
 # branch below would check the main checkout, not this worktree. Run the
 # worktree's own package.json scripts directly instead (only when nested
@@ -198,32 +241,39 @@ run_guard_bin() {
 if [ "$(git rev-parse --path-format=absolute --git-dir)" != "$GIT_COMMON_DIR" ] \
    && [ -n "$PARENT_DIR" ]; then
   cd "$REPO_ROOT"
-  echo "[pre-push] worktree without scripts/check-wt.sh — running this worktree's package.json scripts (typecheck, lint, test, test:dom) and guards (guards, checks, comment-lang)…"
+  echo "[pre-push] worktree without scripts/check-wt.sh — running this worktree's package.json scripts (typecheck, lint, test, test:dom) and guards (guards, ui, checks, comment-lang, public-exports-changelog)…"
   if ! has_package_script test; then
     echo "[pre-push] FATAL: worktree without a package.json \"test\" script — nothing to run, refusing push." >&2
     echo "Add a \"test\" script to package.json." >&2
     exit 1
   fi
-  FAILED=""
+  RUNNER="$(resolve_script_dir "$0")/run-steps-parallel.ts"
+  if [ ! -f "$RUNNER" ]; then
+    echo "[pre-push] FATAL: run-steps-parallel.ts not found next to the resolved hook — refusing push" >&2
+    exit 1
+  fi
+  # test:dom stays behind test (always declared, see above) in one lane: both are
+  # bun test runs over the same repo and have always run one after the other.
   for SCRIPT_NAME in typecheck lint test test:dom; do
+    STEP_FLAG="--step"
+    [ "$SCRIPT_NAME" = "test:dom" ] && STEP_FLAG="--then"
     if has_package_script "$SCRIPT_NAME"; then
-      echo "[pre-push] bun run $SCRIPT_NAME"
-      if ! bun run "$SCRIPT_NAME"; then
-        FAILED="$FAILED $SCRIPT_NAME"
-      fi
+      add_step "$STEP_FLAG" "$SCRIPT_NAME" "bun run $SCRIPT_NAME"
     else
       echo "[pre-push] $SCRIPT_NAME: no script, skipped"
     fi
   done
-  run_guard_bin guards kumiko-guards guards
-  run_guard_bin checks kumiko-guards checks
-  run_guard_bin comment-lang kumiko-guards comment-lang --touched --base=origin/main
-  run_guard_bin public-exports-changelog kumiko-guards public-exports-changelog --base=origin/main
-  if [ -n "$FAILED" ]; then
-    echo "[pre-push] worktree check failed:$FAILED" >&2
-    exit 1
+  add_guard_step guards kumiko-guards "guards"
+  if has_ui_roots; then
+    add_guard_step ui kumiko-guards "ui"
+  else
+    echo "[pre-push] ui: no uiRoots in kumiko.json, skipped"
   fi
-  exit 0
+  add_guard_step checks kumiko-guards "checks"
+  add_guard_step comment-lang kumiko-guards "comment-lang --touched --base=origin/main"
+  add_guard_step public-exports-changelog kumiko-guards "public-exports-changelog --base=origin/main"
+  eval "set -- $STEP_ARGS"
+  exec bun "$RUNNER" --fail-prefix "[pre-push] worktree check failed:" "$@"
 fi
 
 if [ -n "$PARENT_DIR" ]; then

package/src/run-steps-parallel.ts

@@ -0,0 +1,105 @@
+#!/usr/bin/env bun
+// Runs the pre-push steps in parallel lanes. A lane runs its steps one after another
+// (`--then` appends to the previous lane), every step runs even after a failure,
+// and each step's output is printed as one block when it finishes, so nothing is
+// lost and nothing interleaves.
+//
+//   bun run-steps-parallel.ts --fail-prefix "<text>" --step <label> <cmd> [--then <label> <cmd>] ...
+import { availableParallelism, loadavg } from "node:os";
+
+export type Step = { readonly label: string; readonly cmd: string };
+export type Lane = readonly Step[];
+export type StepResult = Step & { readonly exitCode: number; readonly output: string };
+
+export type ParsedArgs = { readonly failPrefix: string; readonly lanes: readonly Lane[] };
+
+export function parseStepArgs(argv: readonly string[]): ParsedArgs {
+  let failPrefix = "steps failed:";
+  const lanes: Step[][] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === "--fail-prefix") {
+      const value = argv[++i];
+      if (value === undefined) throw new Error("--fail-prefix needs a value");
+      failPrefix = value;
+      continue;
+    }
+    if (flag !== "--step" && flag !== "--then") throw new Error(`unknown argument "${flag}"`);
+    const label = argv[++i];
+    const cmd = argv[++i];
+    if (label === undefined || cmd === undefined) throw new Error(`${flag} needs <label> <cmd>`);
+    const lastLane = lanes.at(-1);
+    if (flag === "--then" && lastLane !== undefined) lastLane.push({ label, cmd });
+    else lanes.push([{ label, cmd }]);
+  }
+  return { failPrefix, lanes };
+}
+
+// Most steps are single-threaded, so a few lanes still finish far sooner than one
+// even on a busy machine; beyond that floor the pool follows the free capacity
+// (cores minus 1-min load), so parallel pushes don't oversubscribe it further.
+const MIN_POOL = 4;
+
+export function resolvePoolSize(
+  override: string | undefined,
+  cores: number = availableParallelism(),
+  load1: number = loadavg()[0] ?? 0,
+): number {
+  const forced = Number(override);
+  if (Number.isInteger(forced) && forced > 0) return forced;
+  const ceiling = Math.max(1, cores - 1);
+  return Math.min(ceiling, Math.max(MIN_POOL, Math.round(cores - load1)));
+}
+
+async function runStep(step: Step, log: (text: string) => void): Promise<StepResult> {
+  const started = performance.now();
+  const proc = Bun.spawn(["sh", "-c", step.cmd], {
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  const output = stdout + stderr;
+  const seconds = ((performance.now() - started) / 1000).toFixed(1);
+  log(
+    `[pre-push] ${exitCode === 0 ? "✓" : "✗"} ${step.label} (${seconds}s)\n` +
+      (output.length > 0 ? `${output.endsWith("\n") ? output : `${output}\n`}` : ""),
+  );
+  return { ...step, exitCode, output };
+}
+
+export async function runLanes(
+  lanes: readonly Lane[],
+  poolSize: number,
+  log: (text: string) => void,
+): Promise<StepResult[]> {
+  const results: StepResult[][] = lanes.map(() => []);
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    for (let laneIndex = next++; laneIndex < lanes.length; laneIndex = next++) {
+      for (const step of lanes[laneIndex] ?? []) {
+        results[laneIndex]?.push(await runStep(step, log));
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(poolSize, lanes.length) }, worker));
+  return results.flat();
+}
+
+if (import.meta.main) {
+  const { failPrefix, lanes } = parseStepArgs(process.argv.slice(2));
+  const poolSize = resolvePoolSize(process.env["KUMIKO_PRE_PUSH_POOL"]);
+  const labels = lanes.map((lane) => lane.map((step) => step.label).join(" → ")).join(", ");
+  console.log(`[pre-push] ${lanes.length} lane(s), pool=${poolSize}: ${labels}`);
+  const results = await runLanes(lanes, poolSize, (text) => process.stdout.write(text));
+  const failed = results.filter((result) => result.exitCode !== 0).map((result) => result.label);
+  if (failed.length > 0) {
+    console.error(`${failPrefix} ${failed.join(" ")}`);
+    process.exit(1);
+  }
+}