@kontextmind/kxm 0.7.146 → 0.7.148

package/plugins/kxm/skills/kxm-browser-diagnostics/SKILL.md

@@ -15,16 +15,17 @@ Use this skill to investigate and resolve connectivity failures, CDP attachment
 - **Diagnosis**:
   - KontextMind Steel is behind Authentik forward auth. Unauthenticated requests redirect to `id.kxmd.dev`. Authentik accepts an app password only as `Authorization: Basic`. A Bearer token is refused.
   - Check that `STEEL_AUTH_BASIC` is set, or that both `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN` are set (`test -n "$STEEL_AUTH_TOKEN" && echo set`); never print the value.
-  - A legacy `STEEL_API_KEY` still uses `x-steel-api-key` and `?apiKey=` through the temporary proxy shim. Prefer the Authentik variables so the credential stays out of URLs.
-- **Remedy**: Re-export the Authentik app password into the session environment. Do not log it.
+  - `STEEL_API_KEY` is deprecated. Steel and Caddy do not enforce it. Do not put a credential in the URL. Direct LAN, tailnet, and host-forward connections are blocked.
+  - `websocketUrl` `ws://steel-browser/` means the client is older than `kxm` 0.7.135. The server returns `wss://steel.kontextmind.com/`.
+- **Remedy**: Re-read the `svc-steel` field `basic_auth` with `op read 'op://kontextmind/Steel (svc-steel)/basic_auth'` into `STEEL_AUTH_BASIC`. Do not log it or write it to disk. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`.
 
 ### 2. CDP WebSocket Attachment Failure
 
 - **Symptom**: `WebSocket connection to wss://... failed: 404/500`.
 - **Diagnosis**:
   - Check if the target session ID has already been released or timed out.
-  - Verify ingress WebSocket headers: ensure `nginx.ingress.kubernetes.io/websocket-services` is enabled.
-- **Remedy**: Query `GET /v1/sessions/<id>`. If status is `released`, launch a fresh session.
+  - The CDP path is `/v1/devtools` on `wss://steel.kontextmind.com/` with an `Authorization` header. Caddy must pass the WebSocket upgrade. A credential in the URL is not accepted.
+- **Remedy**: Query `GET /v1/sessions/<id>` with the same `Authorization` header. If status is `released`, launch a fresh session.
 
 ### 3. Session Timeout & Expiration
 

package/plugins/kxm/skills/kxm-browser-explore/SKILL.md

@@ -21,11 +21,12 @@ Use this skill for exploratory navigation, DOM inspection, scraping, and interac
 Ensure an active Steel session exists and obtain its CDP endpoint:
 
 ```bash
-# CDP URL only. The Authentik credential is an Authorization header, not a query parameter.
-CDP_URL="wss://<steel-host>/v1/devtools?sessionId=<sessionId>"
+# CDP path only. The session websocketUrl is wss://steel.kontextmind.com/.
+# The Authentik credential is an Authorization header, not a query parameter.
+CDP_URL="wss://steel.kontextmind.com/v1/devtools?sessionId=<sessionId>"
 ```
 
-Build that URL with `formatCDPConnect()` so the `Authorization: Basic` header is available for the handshake. `STEEL_AUTH_BASIC`, or `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`, supplies it. A Bearer token is not accepted.
+Build that URL with `formatCDPConnect()` so the `Authorization` header is available for the handshake. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`. Those override `STEEL_API_KEY`, which Steel and Caddy do not enforce. A Bearer token is not accepted. `kxm` 0.7.135 or newer is required. Read `basic_auth` with `op read` and do not write it to disk.
 
 ### 2. Connect a client that can send the header
 

package/plugins/kxm/skills/kxm-browser-session/SKILL.md

@@ -5,7 +5,7 @@ description: Start, attach to, inspect, and release self-hosted Steel browser se
 
 # KXM Browser Session Management
 
-Use this skill to create, inspect, attach automation tools to, and release isolated browser sessions running on your self-hosted Steel deployment. Set `STEEL_API_URL` (and optionally `STEEL_UI_URL`) to your deployment; KXM does not provide one.
+Use this skill to create, inspect, attach automation tools to, and release isolated browser sessions on the Steel server. `STEEL_API_URL` defaults to `https://steel.kontextmind.com`. `steel.theneuro.me` is an alias of that server. `kxm` 0.7.135 or newer is required.
 
 Playwright testing and verification use Obscura by default (`resolveBrowserCdpEndpoint()`, or `npm run e2e`). Use this skill's Steel session for human takeover, MFA, and the live session viewer. Attach Playwright to that session only when `KXM_BROWSER=steel`.
 
@@ -18,9 +18,9 @@ Playwright testing and verification use Obscura by default (`resolveBrowserCdpEn
 
 ## Prerequisites
 
-1. Your own Steel deployment, with `STEEL_API_URL` set to its base URL (for example `https://steel.example.com`) and `STEEL_UI_URL` set if the viewer lives elsewhere (default `$STEEL_API_URL/ui`).
-2. Authentik app-password auth in the environment. The KontextMind Steel hosts are behind Authentik forward auth, which accepts `Authorization: Basic` and refuses a Bearer token. Export `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN` (or the pre-encoded `STEEL_AUTH_BASIC`) from your password manager, for example `export STEEL_AUTH_TOKEN="$(pass-cli item view --vault-name '<vault>' --item-title '<item>' --field password)"`. Never paste the token into a prompt. `STEEL_API_KEY` is a deprecated shim (`x-steel-api-key` and `?apiKey=`); do not put credentials in URLs.
-3. Network access to remote CDP endpoints on port 443 / 9223.
+1. `kxm` 0.7.135 or newer. The server is `https://steel.kontextmind.com`. Caddy and Authentik forward auth are the only path. Direct LAN, tailnet, and host-forward access is blocked. Sessions return `websocketUrl` `wss://steel.kontextmind.com/` (previously `ws://steel-browser/`).
+2. The `svc-steel` Authentik credential in the environment. Allowed groups are `steel-users`, `kxmd-users`, `kxmd-admins`, and `kxmd-owners`. Read it at runtime and do not write it to disk: `export STEEL_AUTH_BASIC="$(op read 'op://kontextmind/Steel (svc-steel)/basic_auth')"`. Precedence is `STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`. Those override `STEEL_API_KEY`. `STEEL_API_KEY` is deprecated. Steel and Caddy do not enforce it. A Bearer token is refused. Never put the credential in a URL.
+3. HTTPS to `steel.kontextmind.com` for the CDP path `/v1/devtools`. Send `Authorization` on the handshake.
 
 ## Session Lifecycle States
 
@@ -48,7 +48,7 @@ Playwright testing and verification use Obscura by default (`resolveBrowserCdpEn
 - **Inputs**: Task ID, target URL, session timeout (default 300s, max 1800s), optional proxy or viewport dimensions.
 - **Outputs**:
   - `sessionId`: Unique session UUID.
-  - `cdpUrl`: Remote CDP WebSocket URL (`wss://<steel-host>/v1/devtools?sessionId=<id>`). Send `Authorization: Basic` on the handshake. The URL has no credential when Authentik auth is configured.
+  - `cdpUrl`: `wss://steel.kontextmind.com/v1/devtools?sessionId=<id>`. Send `Authorization` on the handshake. The URL has no credential. The session `websocketUrl` is `wss://steel.kontextmind.com/`.
   - `sessionViewerUrl`: Interactive web session viewer URL (`$STEEL_UI_URL?sessionId=<id>`).
   - `status`: `live` | `idle` | `released`.
 

package/plugins/kxm/skills/kxm-browser-verify/SKILL.md

@@ -77,7 +77,7 @@ Local pages require the launcher flag `--allow-private-network` (the launcher al
 
 ## Steel, only for takeover
 
-When the case is human takeover, MFA, or the live session viewer, set `KXM_BROWSER=steel` and a session id. `connectBrowserOverCdp()` passes `formatCDPConnect()` headers into `chromium.connectOverCDP`. Closing the Playwright browser disconnects the client and does not release the Steel session.
+When the case is human takeover, MFA, or the live session viewer, set `KXM_BROWSER=steel` and a session id. That path needs `kxm` 0.7.135 or newer. `connectBrowserOverCdp()` passes `formatCDPConnect()` headers into `chromium.connectOverCDP` for `/v1/devtools` on `wss://steel.kontextmind.com/`. The `Authorization` header is the `svc-steel` credential (`STEEL_AUTH_HEADER`, then `STEEL_AUTH_BASIC`, then `STEEL_AUTH_USER` and `STEEL_AUTH_TOKEN`). `STEEL_API_KEY` is deprecated and is not enforced. Closing the Playwright browser disconnects the client and does not release the Steel session.
 
 ```typescript
 import { chromium } from "playwright";

package/plugins/kxm/src/browser.ts

@@ -5,11 +5,12 @@
  * (`resolveBrowserCdpEndpoint()`). Steel remains the client for human
  * takeover, MFA, and the live session viewer (`KXM_BROWSER=steel`).
  * Manages remote Steel sessions, CDP endpoints, human takeover handoffs,
- * pass-cli credential references, and automated cleanup without leaking secrets.
+ * and automated cleanup without leaking secrets.
  *
- * Hosts behind Authentik forward auth (the KontextMind Steel proxies) accept
- * an app password only as `Authorization: Basic`. A Bearer token is refused.
- * `STEEL_API_KEY` remains a legacy shim: `x-steel-api-key` and `?apiKey=`.
+ * steel.kontextmind.com is reached only through Caddy and Authentik forward
+ * auth. Clients send `Authorization: Basic` for the svc-steel credential.
+ * A Bearer token is refused. `STEEL_API_KEY` is deprecated and is not
+ * enforced by Steel or Caddy. Do not put a credential in the URL.
  */
 
 import { execSync } from "node:child_process";
@@ -188,9 +189,9 @@ export class SteelAuthRedirectError extends Error {
 }
 
 const LEGACY_STEEL_AUTH_WARNING =
-  "kxm: STEEL_API_KEY is deprecated for Steel. Authentik forward auth accepts app passwords only as Authorization: Basic. " +
-  "Set STEEL_AUTH_BASIC, or STEEL_AUTH_USER and STEEL_AUTH_TOKEN. " +
-  "The legacy x-steel-api-key header and apiKey query parameter remain for the temporary proxy shim.\n";
+  "kxm: STEEL_API_KEY is deprecated for Steel. Steel and Caddy do not enforce it. " +
+  "Set STEEL_AUTH_HEADER, or STEEL_AUTH_BASIC, or STEEL_AUTH_USER and STEEL_AUTH_TOKEN. " +
+  "Those override STEEL_API_KEY. Send Authorization on the request, not in the URL.\n";
 
 let legacySteelAuthWarned = false;
 
@@ -310,6 +311,7 @@ export function resolvePassCliApiKey(
     }
   }
   try {
+    // Deprecated lookup. The hosted server does not enforce STEEL_API_KEY.
     const output = execFn(
       'pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --output json',
     );
@@ -325,8 +327,9 @@ export function resolvePassCliApiKey(
 }
 
 /**
- * Resolve Steel configuration from environment or pass-cli.
+ * Resolve Steel configuration from the environment.
  * Does not write secrets to disk or logs.
+ * Authentik Basic auth overrides `STEEL_API_KEY`. Steel and Caddy do not enforce that key.
  *
  * Authentik Basic auth (`STEEL_AUTH_HEADER`, `STEEL_AUTH_BASIC`, or
  * `STEEL_AUTH_USER` + `STEEL_AUTH_TOKEN`) wins over `STEEL_API_KEY`.
@@ -610,7 +613,7 @@ export class SteelClient {
   }
 
   /**
-   * Launch a new Steel browser session on DOKS.
+   * Launch a new Steel browser session.
    */
   async createSession(options?: CreateSessionOptions): Promise<SteelSession> {
     const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs ?? 300000;

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.146";
+const VERSION = "0.7.148";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/modes.ts

@@ -123,7 +123,7 @@ export const DEFAULT_MODES_CONFIG: ModesConfig = Object.freeze({
     browser: {
       description: "Remote Steel browser sessions and visual testing",
       tools: ["steel_session", "steel_scrape", "steel_screenshot"],
-      promptSnippet: "Use Steel on DOKS for browser automation; invoke takeover on MFA.",
+      promptSnippet: "Playwright tests use Obscura. Steel is remote browsing and takeover through Caddy and Authentik; send Authorization, never a credential in the URL.",
     },
   },
 });

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);
+  });
+}