@kontextmind/kxm 0.7.147 → 0.7.149

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.147",
+      "version": "0.7.149",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -142,6 +142,15 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Pull-request CI runs the unit suite on Linux Node 24, and `CI / required` is the aggregate check.**
+  Docs and plan markdown skip the code jobs. `engine.test.ts` is split by
+  test name. `permission.test.ts` and `runtime.test.ts` run one file at a
+  time, and every other unit file runs in one light lane. Pushes to `main`
+  still run `validate:pr` on Linux and Windows for Node 22.19.0 and Node 24.
+  A pull request that touches path, process, shell, spawn, package, lockfile,
+  or workflow files also runs the unit lanes on Windows. Playwright stays on
+  Obscura. See [CI and release](docs/contributing/ci-and-release.md).
+
 - **Docs match the 2026-09-27 Steel and machine-account infrastructure.**
   Steel (`steel.kontextmind.com`, alias `steel.theneuro.me`) is reached only
   through Caddy on `kxmd-proxy` (VM 230) and Authentik forward auth. Direct
@@ -180,6 +189,7 @@ All notable user-facing changes are documented here. The project follows [Semant
   `opus` because the justfile recipe review-arch hardcoded that model while
   `reviewer-arch` listed only `fable-claude`. That recipe is gone; a request
   for `opus` fails closed.
+
 - **Dispatch reads role and model files, and agents bind a role.**
   `scripts/roster-policy.mjs` builds the developer policy from
   `.kxm/models/*.yaml` and `.kxm/roles/*.yaml` at `refs/remotes/origin/main`.
@@ -518,6 +528,8 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **Dry-run ship status no longer rewrites `.git/index`.** `git status` refreshes the index under an optional lock. The ship-status read passes `--no-optional-locks`, so a dry run leaves the checkout untouched.
+
 - **A committed checkout counts as authored work, and a one-shot outcome must be a standalone JSON object.** The authoring witness includes `HEAD` with porcelain status and both diffs, so a write that commits its edits is `changed` and can stay `passed`. A `rev-parse` failure keeps that empty head term only when the repository has no commits; any other git failure is `unwitnessed`. A one-shot outcome is accepted when the whole reply is one JSON object, or when that object stands alone on the final line. A closing code fence around the final object is allowed. An object followed by prose, a truncated reply, and an ambiguous tail settle `failed`.
 
 - **The test suite no longer passes `--test-timeout`.** Under `node --test` that flag bounds each file, so coverage on CI timed out `test/core/engine.test.ts` at three minutes. The wall clock in `scripts/run-bounded.mjs` still bounds each script.

package/docs/contributing/ci-and-release.md

@@ -1,11 +1,12 @@
 # CI and release
 
-Every pull request and every push to `main` that changes code runs a
-three-minute merge-safety gate, the complete suite with coverage floors runs
-nightly, every merge to `main` cuts a patch release, and every release is
-verified before it reaches npm. This
-page explains which checks run where, how a merge becomes a published version,
-and which smoke tests stay manual. It is for contributors and maintainers.
+Pull requests run lint, typecheck, and the unit suite on Linux Node 24.
+Pushes to `main` also run that suite and the full OS × Node matrix.
+The complete suite with coverage floors runs nightly, every merge to `main`
+cuts a patch release, and every release is verified before it reaches npm.
+This page explains which checks run where, how a merge becomes a published
+version, and which smoke tests stay manual. It is for contributors and
+maintainers.
 
 ## The pipeline at a glance
 
@@ -14,9 +15,10 @@ release and an npm publish; the nightly job adds the slower suites.
 
 ```mermaid
 flowchart LR
-  PR[Pull request] -->|"validate:pr, docs lint, plugin validation"| MERGE{Merged?}
+  PR[Pull request] -->|"unit shards, docs lint, plugin validation"| REQ["CI / required"]
+  REQ --> MERGE{Merged?}
   MERGE -->|yes| MAIN[main]
-  MAIN -->|"same three-minute validate:pr"| PUSH[Push CI]
+  MAIN -->|"unit shards plus validate:pr matrix"| PUSH[Push CI]
   MAIN -->|"Auto-Release: next patch tag"| TAG[Tag vX.Y.Z]
   TAG -->|dispatch| REL[Release workflow]
   REL -->|"verify, stamp version, pack"| GH[GitHub release<br/>kxm-X.Y.Z.tgz]
@@ -35,46 +37,75 @@ together.
 | Trigger | Workflow (job) | What it runs |
 |---|---|---|
 | Before you push | Local | `npm run verify` |
-| Pull request and push to `main` | `ci.yml` (Validate, two Node legs) | `validate:pr`, the three-minute gate; skipped for documentation-only changes |
+| Pull request, push to `main`, or manual | `ci.yml` (`required`) | Aggregates the lanes below into one pass/fail check named `CI / required` |
 | Pull request and push | `ci.yml` (Docs lint) | `lint:docs` and `check:versions`, always |
-| Pull request and push | `ci.yml` (Plugin validation) | `claude plugin validate --strict` on the marketplace and the plugin; skipped for documentation-only changes |
+| Code pull request and code push | `ci.yml` (Unit engine and Unit, Linux Node 24) | `engine.test.ts` split by test name; `permission.test.ts` and `runtime.test.ts` one file at a time; every other unit file together. Typecheck and `check-generated` run on the light lane |
+| Platform-sensitive pull request | `ci.yml` (Unit, Windows Node 24) | The same four unit lanes on `windows-latest` |
+| Push to `main`, or manual | `ci.yml` (Validate matrix) | `validate:pr` on Linux and Windows for Node 22.19.0 and Node 24; not on a pull request |
+| Code pull request and code push | `ci.yml` (Plugin validation) | `claude plugin validate --strict` on the marketplace and the plugin |
 | Daily at 04:00 UTC, or manual | `nightly.yml` | `test:coverage:complete`, `check`, `check:generated`, `npm pack --dry-run` |
 | Merged pull request | `auto-release.yml` | Tags the merge commit and dispatches `release.yml` |
 | Tag push or dispatch | `release.yml` | Verifies, packs and publishes (see [Release flow](#release-flow)) |
 | Manual only | `smoke.yml` | Real Pi smoke, currently disabled (see [Smoke tests](#smoke-tests)) |
-| Pull request, or manual | `e2e.yml` | `npm run e2e` on `ubuntu-latest`: Obscura v0.2.3 plus the Playwright smoke test. This workflow does not enable CI, Nightly, or Real Pi smoke |
+| Pull request, or manual | `e2e.yml` | `npm run e2e` on `ubuntu-latest`: Obscura v0.2.3 plus the Playwright smoke test. Separate from `ci.yml` |
 
 The npm scripts behind those rows:
 
 | Script | Composition |
 |---|---|
 | `verify` | `npm test` (core and package unit tests), `check`, `check:generated` |
+| `test:ci-shard` | One unit lane: build, then `engine <index> <total>`, `serial`, or `light` over `test/core/*.test.ts` and `packages/core/*/tests/unit/*.test.ts` |
 | `validate:pr` | `build`, `typecheck`, a compact contract and smoke set of nine `test/core` files, `check:versions`, and the generated-`dist` check |
-| `validate:ci` | `test:coverage` (core and package tests, 91/80/92 floors), `check`, `npm pack --dry-run`; not run by CI today, available locally |
+| `validate:ci` | `test:coverage` (core and package tests, 91/80/92 floors), `check`, `npm pack --dry-run`; the Release workflow runs it, and it stays available locally |
 | `test:coverage:complete` | Core, simulation and package tests with 93/80/93 floors |
 | `check` | `typecheck`, `lint:docs`, `check:versions` |
 
-Three differences matter when a check fails on one side only:
-
-- CI runs a compact contract and smoke set, not the core suite. The full core
-  suite and the package unit tests under `packages/core/*/tests` run in your
-  local `npm run verify`; run it before every push.
-- Coverage and `test/simulations` run only in the nightly complete suite, never
-  on a pull request or a push to `main`.
-- A regression the compact set misses can reach `main` and show up in the
-  nightly run, so treat a nightly failure as a release blocker.
-
-### Validate matrix and required checks
-
-The Validate job runs on Node 22.19.0 and Node 24, on Linux and Windows. Linux
-uses the ARC scale set `kontextmind-doks` with a three-minute job timeout.
-Windows uses GitHub-hosted `windows-latest` with a fifteen-minute timeout so
-`npm ci` can finish. The branch ruleset requires the job names
-`Validate (linux, Node 22.19.0)` and `Validate (linux, Node 24)` only; the
-Windows names are reported but not required, so a Windows-only failure does not
-block merge. Renaming a required Linux job or the matrix means updating the
-ruleset in the same change. A newer push cancels an older pull request run;
-runs on `main` are never cancelled.
+What moved off the pull-request lane, and what did not:
+
+- The four `validate:pr` cells — Linux and Windows, Node 22.19.0 and Node 24 —
+  run on a push to `main` and on `workflow_dispatch`. They do not run on a
+  pull request. The nine files inside `validate:pr` still run on a code pull
+  request, because they are part of the Linux Node 24 unit suite.
+- Node 22.19.0 does not run the unit suite on a pull request. It runs
+  `validate:pr` on `main`.
+- Windows runs the unit suite on a pull request only when the classifier marks
+  the change platform-sensitive. Every push to `main` that changes code still
+  runs `validate:pr` on Windows.
+- Coverage, `test/simulations`, and `npm pack --dry-run` stay in the nightly
+  complete suite. They were not part of pull-request CI before this split.
+- Plugin validation still runs on code pull requests and code pushes.
+
+Run `npm run verify` locally before every push. A nightly failure is a release
+blocker: it is the only place the simulation suite and coverage floors run.
+
+### Lanes and the required check
+
+Code pull requests run Docs lint, two Linux Node 24 engine shards, a serial
+lane (`permission.test.ts` then `runtime.test.ts`), a light lane for every
+other unit file, and Plugin validation. The light lane typechecks and checks
+generated bundles. `engine.test.ts` is split by test name because that file
+alone was 174 seconds; the serial lane keeps the next two longest files off
+the light pool, which was 268 seconds when every non-engine file shared one
+job. Linux jobs use the npm cache from
+`actions/setup-node`. Restoring a `node_modules` tarball was slower than
+`npm ci` on the Linux runners (about 24s versus 17s on 2026-09-24), so that
+cache stays on the Windows jobs, where `npm ci` is the slow step.
+
+The job `required` always runs. Its check name is `CI / required`. It fails
+when a lane fails or is cancelled, and it passes when a lane was skipped
+because the change did not need it. Add `CI / required` as a required status
+check in the `protect-main` ruleset. Skipped matrix legs are not required
+names, so they do not block auto-merge. This repository change does not edit
+that ruleset.
+
+A newer push cancels an older pull request run. Runs on `main` are never
+cancelled. Unit and Validate matrices use `fail-fast`.
+
+The Validate matrix still runs on Node 22.19.0 and Node 24, on Linux and
+Windows, for pushes to `main` and for `workflow_dispatch`. Linux uses the ARC
+scale set `kontextmind-doks` with a three-minute job timeout. Windows uses
+GitHub-hosted `windows-latest` with a fifteen-minute timeout so `npm ci` can
+finish. Those four job names are not the required check anymore.
 
 ### CI jobs stay queued while a runner is online
 
@@ -111,20 +142,26 @@ autoscaler. Do not relabel `km-gh-rn01` or push an empty commit as a routing
 workaround.
 
 > [!NOTE]
-> Windows Validate uses GitHub-hosted `windows-latest`, not a self-hosted
-> homelab runner and not the ARC scale set. Do not add a `kontextmind-doks`
-> label to a Windows runner. Nightly complete coverage and release stay on
-> Linux. Windows-specific fixtures (for example the `pi.cmd` worker launch in
-> `test/core/worker.test.ts`) also run in the hosted Windows Validate legs.
+> Windows jobs use GitHub-hosted `windows-latest`, not a self-hosted homelab
+> runner and not the ARC scale set. Do not add a `kontextmind-doks` label to a
+> Windows runner. Nightly complete coverage and release stay on Linux.
+> Platform-sensitive pull requests run the unit suite on Windows, which
+> includes `test/core/worker.test.ts`. The main Validate legs run the compact
+> `validate:pr` gate.
 
 ### The docs-only classifier
 
 The first job, Classify changes, lists the changed paths and sets `code=false`
-when every path matches `*.md`, `docs/*`, `.kxm/assets/*`, `LICENSE`, the issue
-and PR templates, or `dependabot.yml`. Validate and Plugin validation read it:
-for a documentation-only change they report success without checking out the
-code, so the required job names still pass. Docs lint always runs.
-`ci-contract.test.ts` pins this behavior.
+when every path matches `*.md` (including `plans/**/*.md`), `docs/**`,
+`.kxm/assets/**`, `LICENSE`, the issue and PR templates, or `dependabot.yml`.
+A non-markdown file under `plans/` is code. Unit lanes, Plugin validation,
+and the Validate matrix are skipped. Docs lint runs, and `CI / required`
+passes. `scripts/ci-classify.mjs` and `ci-contract.test.ts` pin this behavior.
+
+`platform=true` when a path is a package manifest, the lockfile, a file under
+`scripts/` or `.github/workflows/`, or a filename that names path, process,
+shell, spawn, worker, supervisor, repo-root, or ssh-remote behavior. A
+platform-sensitive pull request also runs the Windows Node 24 unit lanes.
 
 > [!WARNING]
 > Several tests and code paths read documentation files by path. A pull request

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.147",
+  "version": "0.7.149",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",
@@ -38,6 +38,7 @@
     "test:simulations": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/simulations/*.test.ts",
     "test:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts test/simulations/*.test.ts",
     "test": "npm run build && node scripts/run-bounded.mjs 1200000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
+    "test:ci-shard": "node scripts/ci-unit-shard.mjs",
     "e2e": "node scripts/obscura.mjs --ensure && playwright test",
     "test:coverage:core": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=91 --test-coverage-branches=80 --test-coverage-functions=92 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts packages/core/*/tests/unit/*.test.ts",
     "test:coverage:complete": "npm run build && node scripts/run-bounded.mjs 2400000 node --disable-warning=ExperimentalWarning --experimental-strip-types --test --test-force-exit --test-concurrency=4 --experimental-test-coverage --test-coverage-lines=93 --test-coverage-branches=80 --test-coverage-functions=93 --test-coverage-include=plugins/kxm/src/**/*.ts --test-coverage-exclude=plugins/kxm/src/server.ts --test-coverage-exclude=plugins/kxm/src/mcp-server.ts --test-coverage-exclude=plugins/kxm/src/runtime-supervisor.ts --test-coverage-include=packages/core/*/src/**/*.ts test/core/*.test.ts test/simulations/*.test.ts packages/core/*/tests/unit/*.test.ts",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.147",
+  "version": "0.7.149",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/claude-hook.js

@@ -724,7 +724,7 @@ function formatShipLine(ship) {
 }
 function readGitShip(cwd) {
   try {
-    const dirty = spawnSync("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
+    const dirty = spawnSync("git", ["--no-optional-locks", "-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
     if (dirty.status !== 0) return void 0;
     const isDirty = dirty.stdout.trim().length > 0;
     const upstream = spawnSync("git", ["-C", cwd, "rev-list", "--count", "@{u}..HEAD"], { encoding: "utf8", windowsHide: true });

package/plugins/kxm/dist/cli.js

@@ -50095,7 +50095,7 @@ function formatShipLine(ship) {
 }
 function readGitShip(cwd) {
   try {
-    const dirty = spawnSync10("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
+    const dirty = spawnSync10("git", ["--no-optional-locks", "-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
     if (dirty.status !== 0) return void 0;
     const isDirty = dirty.stdout.trim().length > 0;
     const upstream = spawnSync10("git", ["-C", cwd, "rev-list", "--count", "@{u}..HEAD"], { encoding: "utf8", windowsHide: true });

package/plugins/kxm/dist/extension.js

@@ -37099,7 +37099,7 @@ function formatShipLine(ship) {
 }
 function readGitShip(cwd) {
   try {
-    const dirty = spawnSync("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
+    const dirty = spawnSync("git", ["--no-optional-locks", "-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
     if (dirty.status !== 0) return void 0;
     const isDirty2 = dirty.stdout.trim().length > 0;
     const upstream = spawnSync("git", ["-C", cwd, "rev-list", "--count", "@{u}..HEAD"], { encoding: "utf8", windowsHide: true });

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.147";
+var VERSION = "0.7.149";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.147",
+  "version": "0.7.149",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.147";
+const VERSION = "0.7.149";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/session-work.ts

@@ -127,7 +127,9 @@ export function formatShipLine(ship?: SessionShipStatus): string {
 
 export function readGitShip(cwd: string): SessionShipStatus | undefined {
   try {
-    const dirty = spawnSync("git", ["-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
+    // --no-optional-locks keeps a ship-status read from rewriting .git/index.
+    // git status refreshes the index under an optional lock; a dry run must not.
+    const dirty = spawnSync("git", ["--no-optional-locks", "-C", cwd, "status", "--porcelain"], { encoding: "utf8", windowsHide: true });
     if (dirty.status !== 0) return undefined;
     const isDirty = dirty.stdout.trim().length > 0;
 

package/scripts/ci-classify.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+// Classify a pull request or push into the CI lanes.
+//
+// Docs and plan markdown skip the code jobs. The aggregate `required` job
+// still runs, so a skipped matrix does not leave the status check blank.
+// Platform-sensitive paths add the Windows unit shards on pull requests.
+// Pushes to main and workflow_dispatch keep the full OS x Node validate matrix.
+
+import { readFileSync } from "node:fs";
+
+const DOCS_RULES = [
+  (file) => file.endsWith(".md"),
+  (file) => file.startsWith("docs/"),
+  (file) => file.startsWith(".kxm/assets/"),
+  (file) => file === "LICENSE",
+  (file) => file.startsWith(".github/ISSUE_TEMPLATE/"),
+  (file) => file === ".github/pull_request_template.md",
+  (file) => file === ".github/dependabot.yml",
+];
+
+// Filename tokens for path, process, shell, and spawn behavior, plus the
+// dependency and workflow files that change how those paths run.
+const PLATFORM_NAME = /(path|paths|process|shell|spawn|worker|supervisor|repo-root|ssh-remote)/i;
+
+export function isDocsPath(file) {
+  return DOCS_RULES.some((rule) => rule(file));
+}
+
+export function isPlatformPath(file) {
+  if (/(^|\/)package\.json$/.test(file)) return true;
+  if (/(^|\/)package-lock\.json$/.test(file)) return true;
+  if (file.startsWith(".github/workflows/")) return true;
+  if (file.startsWith("scripts/")) return true;
+  const base = file.split("/").pop() ?? file;
+  return PLATFORM_NAME.test(base);
+}
+
+export function unboundedClassification() {
+  return { code: true, platform: false, runValidate: true };
+}
+
+export function classifyPaths(paths, event) {
+  const files = paths.map((file) => file.trim()).filter(Boolean);
+  const code = files.some((file) => !isDocsPath(file));
+  const platform = files.some((file) => isPlatformPath(file));
+  const runValidate = event !== "pull_request" && code;
+  return { code, platform, runValidate };
+}
+
+function emit(result) {
+  process.stdout.write(`code=${result.code}\n`);
+  process.stdout.write(`platform=${result.platform}\n`);
+  process.stdout.write(`run_validate=${result.runValidate}\n`);
+}
+
+if (process.argv[1] && process.argv[1].endsWith("ci-classify.mjs")) {
+  const event = process.argv[2] ?? "";
+  if (event !== "pull_request" && event !== "push" && event !== "workflow_dispatch" && event !== "unbounded") {
+    process.stderr.write("usage: ci-classify.mjs <pull_request|push|workflow_dispatch|unbounded>\n");
+    process.exit(2);
+  }
+  if (event === "unbounded") {
+    emit(unboundedClassification());
+  } else {
+    const stdin = readFileSync(0, "utf8");
+    emit(classifyPaths(stdin.split(/\r?\n/), event));
+  }
+}

package/scripts/ci-unit-shard.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+// Unit lanes for CI.
+//
+// Measured on Node 24 (4 cores), one file at a time: engine.test.ts 174s,
+// permission.test.ts 74s, runtime.test.ts 53s. Those files run their tests
+// sequentially, and running them in one process pool stretched the rest of
+// the suite to 268s. engine.test.ts is split by test name across two jobs.
+// permission and runtime run one file at a time in a serial job so they do
+// not steal cores from each other. Every other unit file runs in a light
+// job at concurrency 4.
+//
+// Dynamic `test(\`...\${...}\`)` names stay together as one pattern so a
+// loop is not dropped. Run via `npm run test:ci-shard` so npm_execpath is
+// set for the packed-install test: `engine <index> <total>`, `serial`, or
+// `light`.
+
+import { spawn, spawnSync } from "node:child_process";
+import { globSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const SHARD_TOTAL = 2;
+export const ENGINE_FILE = "test/core/engine.test.ts";
+// Solo Node 24 timings: permission 74s, runtime 53s. One file at a time.
+export const SERIAL_FILES = [
+  "test/core/permission.test.ts",
+  "test/core/runtime.test.ts",
+];
+const LIGHT_CONCURRENCY = 4;
+
+function escapeRegExp(value) {
+  return value.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&");
+}
+
+export function listUnitFiles(root) {
+  return [
+    ...globSync("test/core/*.test.ts", { cwd: root }),
+    ...globSync("packages/core/*/tests/unit/*.test.ts", { cwd: root }),
+  ].sort();
+}
+
+export function extractTestPatterns(source) {
+  const patterns = [];
+  const seen = new Set();
+  const re = /^[ \t]*test\(\s*(["'`])([\s\S]*?)\1/gm;
+  for (const match of source.matchAll(re)) {
+    const raw = match[2];
+    let sourcePattern;
+    let dynamic = false;
+    let name;
+    if (raw.includes("${")) {
+      dynamic = true;
+      const marked = raw.replace(/\$\{[^}]*\}/g, "\0");
+      sourcePattern = `^${escapeRegExp(marked).replaceAll("\0", ".*?")}$`;
+    } else {
+      name = raw.replace(/\\(["'`\\])/g, "$1");
+      sourcePattern = `^${escapeRegExp(name)}$`;
+    }
+    if (seen.has(sourcePattern)) continue;
+    seen.add(sourcePattern);
+    patterns.push({ dynamic, name, source: sourcePattern });
+  }
+  return patterns;
+}
+
+function conflicts(patterns) {
+  const exact = patterns.filter((pattern) => !pattern.dynamic);
+  const dynamic = patterns.filter((pattern) => pattern.dynamic);
+  const hits = [];
+  for (const pattern of dynamic) {
+    const regex = new RegExp(pattern.source);
+    for (const item of exact) {
+      if (regex.test(item.name)) hits.push(`${item.name} matches ${pattern.source}`);
+    }
+  }
+  return hits;
+}
+
+function enginePatterns(root) {
+  const patterns = extractTestPatterns(readFileSync(join(root, ENGINE_FILE), "utf8"));
+  if (patterns.length === 0) throw new Error(`${ENGINE_FILE} has no recognizable test() names`);
+  const overlapped = conflicts(patterns);
+  if (overlapped.length > 0) {
+    throw new Error(`${ENGINE_FILE} dynamic test names also match exact tests:\n${overlapped.join("\n")}`);
+  }
+  return patterns;
+}
+
+export function planEngineShard(root, index, total = SHARD_TOTAL) {
+  if (!Number.isInteger(index) || !Number.isInteger(total) || index < 1 || index > total) {
+    throw new Error(`shard ${index}/${total} is outside 1..${total}`);
+  }
+  const patterns = enginePatterns(root).filter((_, patternIndex) => patternIndex % total === index - 1);
+  if (patterns.length === 0) throw new Error(`engine shard ${index}/${total} assigned no tests`);
+  return { file: ENGINE_FILE, patterns };
+}
+
+export function planSerial(root) {
+  const files = listUnitFiles(root);
+  if (!files.includes(ENGINE_FILE)) throw new Error(`${ENGINE_FILE} is missing`);
+  for (const file of SERIAL_FILES) {
+    if (!files.includes(file)) throw new Error(`${file} is missing`);
+  }
+  return [...SERIAL_FILES];
+}
+
+export function planLight(root) {
+  const serial = new Set(SERIAL_FILES);
+  const files = listUnitFiles(root).filter((file) => file !== ENGINE_FILE && !serial.has(file));
+  if (files.length === 0) throw new Error("light lane has no unit files");
+  return files;
+}
+
+export function coverageOfShards(root, total = SHARD_TOTAL) {
+  const heavy = new Map();
+  for (let index = 1; index <= total; index += 1) {
+    const plan = planEngineShard(root, index, total);
+    for (const pattern of plan.patterns) heavy.set(pattern.source, (heavy.get(pattern.source) ?? 0) + 1);
+  }
+  return { files: listUnitFiles(root), serial: planSerial(root), light: planLight(root), heavy };
+}
+
+function runNode(args, label, children) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { env: process.env });
+    children.add(child);
+    let stdout = "";
+    let stderr = "";
+    const flush = (buffer, stream, chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split("\n");
+      const rest = lines.pop() ?? "";
+      for (const line of lines) stream.write(`[${label}] ${line}\n`);
+      return rest;
+    };
+    child.stdout.on("data", (chunk) => { stdout = flush(stdout, process.stdout, chunk); });
+    child.stderr.on("data", (chunk) => { stderr = flush(stderr, process.stderr, chunk); });
+    child.on("close", (code) => {
+      children.delete(child);
+      if (stdout) process.stdout.write(`[${label}] ${stdout}\n`);
+      if (stderr) process.stderr.write(`[${label}] ${stderr}\n`);
+      resolve(code ?? 1);
+    });
+    child.on("error", (error) => {
+      children.delete(child);
+      process.stderr.write(`[${label}] ${error.message}\n`);
+      resolve(1);
+    });
+  });
+}
+
+function testArgs(concurrency, files, patterns) {
+  const args = [
+    "--disable-warning=ExperimentalWarning",
+    "--experimental-strip-types",
+    "--test",
+    "--test-force-exit",
+    `--test-concurrency=${concurrency}`,
+  ];
+  for (const pattern of patterns ?? []) args.push("--test-name-pattern", pattern.source);
+  args.push(...files);
+  return args;
+}
+
+async function runPool(tasks, limit) {
+  const pending = [...tasks];
+  const children = new Set();
+  let failed = false;
+  const workers = Array.from({ length: Math.min(limit, pending.length) }, async () => {
+    while (pending.length > 0 && !failed) {
+      const task = pending.shift();
+      const code = await task(children);
+      if (code !== 0) {
+        failed = true;
+        for (const child of children) child.kill("SIGTERM");
+      }
+    }
+  });
+  await Promise.all(workers);
+  return failed ? 1 : 0;
+}
+
+function npmBuild() {
+  const npmCli = process.env.npm_execpath;
+  if (!npmCli) {
+    process.stderr.write("npm_execpath is required; run via npm run test:ci-shard\n");
+    return 1;
+  }
+  const result = spawnSync(process.execPath, [npmCli, "run", "build"], {
+    stdio: "inherit",
+    env: process.env,
+  });
+  return result.status ?? 1;
+}
+
+async function main() {
+  const mode = process.argv[2];
+  const root = process.cwd();
+  const built = npmBuild();
+  if (built !== 0) process.exit(built);
+  if (mode === "serial") {
+    const files = planSerial(root);
+    process.exit(await runPool([
+      (children) => runNode(testArgs(1, files), "serial", children),
+    ], 1));
+  }
+  if (mode === "light") {
+    const files = planLight(root);
+    process.exit(await runPool([
+      (children) => runNode(testArgs(LIGHT_CONCURRENCY, files), "light", children),
+    ], 1));
+  }
+  if (mode === "engine") {
+    const index = Number(process.argv[3]);
+    const total = Number(process.argv[4] ?? SHARD_TOTAL);
+    const plan = planEngineShard(root, index, total);
+    process.exit(await runPool([
+      (children) => runNode(testArgs(1, [plan.file], plan.patterns), "engine", children),
+    ], 1));
+  }
+  process.stderr.write("usage: ci-unit-shard.mjs <serial|light|engine> [index total]\n");
+  process.exit(2);
+}
+
+if (process.argv[1] && process.argv[1].endsWith("ci-unit-shard.mjs")) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+  });
+}