Add files using upload-large-folder tool

scripts/README.md

@@ -0,0 +1,75 @@
+---
+summary: "Repository script entry points and compatibility notes"
+read_when:
+  - Looking for an existing script before adding a new one
+  - Running repository checks, tests, docs, Docker, release, or GitHub helper scripts
+  - Updating package scripts or CI workflow script references
+title: "Scripts Directory"
+---
+
+# Scripts Directory
+
+The `scripts/` directory contains repository tooling used by local development,
+CI, docs publishing, releases, Docker proof, and maintainer operations. Prefer
+the package-script entry points in `package.json` when one exists, then read the
+underlying script before running it directly.
+
+## Compatibility
+
+Many scripts are stable paths referenced by `package.json`, GitHub Actions,
+docs, and maintainer runbooks. Do not move, rename, or regroup scripts only to
+improve taxonomy. A directory migration needs an explicit maintainer-approved
+compatibility plan for package scripts, workflows, docs snippets, and any raw
+script paths users may have copied.
+
+This index is a discovery aid for the current flat layout. It does not define a
+new directory taxonomy.
+
+## Common Entry Points
+
+| Area            | Prefer                                                                         | Notes                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| Build           | `pnpm build`                                                                   | Runs `scripts/build-all.mts`; use specific build scripts only when debugging a build stage.                         |
+| Changed checks  | `pnpm changed:lanes --json`, `pnpm check:changed`                              | Lane classification lives in `scripts/changed-lanes.mjs`; changed-file checks live in `scripts/check-changed.mjs`.  |
+| Docs            | `pnpm docs:list`, `pnpm docs:check-mdx`, `pnpm docs:check-links`               | Backed by `scripts/docs-list.js`, `scripts/check-docs-mdx.mjs`, and `scripts/docs-link-audit.mjs`.                  |
+| Formatting docs | `pnpm format:docs:check`                                                       | Uses `scripts/format-docs.mts`; use write mode only when intentionally formatting docs.                             |
+| Lint            | `pnpm lint`, `pnpm lint:core`, `pnpm lint:all`                                 | Wrapper scripts keep oxlint behavior aligned with repo config.                                                      |
+| Targeted tests  | `pnpm test <path-or-filter>` or `node scripts/run-vitest.mjs <path-or-filter>` | Avoid bare `vitest`; it can start watch mode.                                                                       |
+| Changed tests   | `pnpm test:changed`                                                            | Uses the repo's changed-test resolver instead of a broad Vitest run.                                                |
+| Docker proof    | `pnpm test:docker:all`, `pnpm test:docker:rerun`, `pnpm test:docker:timings`   | Use the planner/rerun helpers before launching broad Docker work.                                                   |
+| Live proof      | `pnpm test:live`                                                               | Live checks require the matching environment and credentials.                                                       |
+| Release checks  | `pnpm release:check`, `pnpm release:beta`, `pnpm release:candidate`            | Release scripts are maintainer workflows; read release docs before use.                                             |
+| GitHub reads    | `scripts/gh-read`                                                              | Uses a GitHub App read token when configured, leaving normal `gh` login for writes.                                 |
+| Commits         | `git add <files...>` then `git commit -m "<message>"`                          | Stage only the intended files for each commit.                                                                      |
+| Remote proof    | `node scripts/crabbox-wrapper.mjs ...`                                         | Use when the current host lacks the required isolation, OS, device, or capacity; sync each run and reuse the lease. |
+
+## Script Families
+
+- `check-*.mts` / `check-*.ts` / retained `check-*.mjs`: guardrails for architecture, docs, package
+  contents, boundaries, workflows, and generated artifacts.
+- `run-*.mjs` / `run-*.mts`: stable wrappers and typed implementations for Node, Vitest,
+  oxlint, tsgo, and environment setup.
+- `test-*.mts` / retained `test-*.mjs` / `test-*.sh` / `test-*.ts`: test planners, Docker lanes, live
+  checks, and focused validation helpers.
+- `docs-*` and `check-docs-*`: docs listing, link auditing, MDX checks,
+  spellcheck, sync, and i18n glossary checks.
+- `release-*`, `openclaw-npm-*`, and `plugin-*-release-*`: release preparation,
+  package verification, and publishing helpers.
+- `docker-*`, `test-docker-*`, and `test-live-*-docker.sh`: Docker E2E planning,
+  rerun, timing, and live/package lane helpers.
+- `gh-read*`, `label-*`, `sync-labels.ts`, and PR helpers: GitHub read,
+  labeling, and maintainer workflow support.
+- `generate-*`, `write-*`, `copy-*`, and `sync-*`: generated docs, metadata,
+  package surfaces, and build artifact support.
+- `lib/`: shared helpers imported by script entry points.
+
+## Maintenance Rules
+
+- Read `scripts/AGENTS.md` before changing scripts.
+- Keep package scripts, generators, generated-artifact checks, docs references,
+  and workflow references aligned when touching a script path.
+- Prefer existing wrappers instead of introducing a raw tool invocation.
+- Add or update focused tests under `test/scripts/` when changing script
+  behavior.
+
+See also [Scripts](https://docs.openclaw.ai/help/scripts) for public-facing script guidance.

scripts/analyze-plugin-sdk-usage.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Analyze Plugin Sdk Usage script supports OpenClaw repository automation.
+import { main } from "./ts-topology.ts";
+
+const forwardedArgs = process.argv.slice(2);
+const normalizedArgs = forwardedArgs[0] === "--" ? forwardedArgs.slice(1) : forwardedArgs;
+const exitCode = await main(["--scope=plugin-sdk", ...normalizedArgs]);
+if (exitCode !== 0) {
+  process.exit(exitCode);
+}

scripts/android-app-i18n.ts

@@ -0,0 +1,1594 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { expectDefined } from "../packages/normalization-core/src/expect.js";
+import { isDirectRunUrl } from "./lib/direct-run.mjs";
+import { NATIVE_I18N_LOCALES } from "./native-i18n-locales.ts";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, "..");
+const ANDROID_MAIN_ROOT = path.join(ROOT, "apps", "android", "app", "src", "main");
+const RESOURCE_ROOT = path.join(ANDROID_MAIN_ROOT, "res");
+const SOURCE_ROOT = path.join(ANDROID_MAIN_ROOT, "java");
+const ANDROID_PLAY_SOURCE_ROOT = path.join(ROOT, "apps", "android", "app", "src", "play", "java");
+const ANDROID_THIRD_PARTY_ROOT = path.join(ROOT, "apps", "android", "app", "src", "thirdParty");
+const ANDROID_THIRD_PARTY_RESOURCE_ROOT = path.join(ANDROID_THIRD_PARTY_ROOT, "res");
+const ANDROID_THIRD_PARTY_SOURCE_ROOT = path.join(ANDROID_THIRD_PARTY_ROOT, "java");
+const ANDROID_WEAR_MAIN_ROOT = path.join(ROOT, "apps", "android", "wear", "src", "main");
+const WEAR_RESOURCE_ROOT = path.join(ANDROID_WEAR_MAIN_ROOT, "res");
+const WEAR_SOURCE_ROOT = path.join(ANDROID_WEAR_MAIN_ROOT, "java");
+const ANDROID_SOURCE_ROOTS = [
+  SOURCE_ROOT,
+  ANDROID_PLAY_SOURCE_ROOT,
+  ANDROID_THIRD_PARTY_SOURCE_ROOT,
+  WEAR_SOURCE_ROOT,
+] as const;
+const INVENTORY_PATH = path.join(ROOT, "apps", ".i18n", "native-source.json");
+const ARTIFACT_ROOT = path.join(ROOT, "apps", ".i18n", "native");
+const TOOL_DISPLAY_PATH = path.join(
+  ROOT,
+  "apps",
+  "shared",
+  "OpenClawKit",
+  "Sources",
+  "OpenClawKit",
+  "Resources",
+  "tool-display.json",
+);
+const GENERATED_KOTLIN_PATH = path.join(
+  SOURCE_ROOT,
+  "ai",
+  "openclaw",
+  "app",
+  "i18n",
+  "NativeStringResources.kt",
+);
+const MANAGED_PREFIX = "native_";
+const ANDROID_QUALIFIERS: Record<string, string> = {
+  id: "in",
+  "zh-CN": "zh-rCN",
+  "zh-TW": "zh-rTW",
+  "pt-BR": "pt-rBR",
+  "ja-JP": "ja",
+};
+const localeDirectory = (locale: string) => `values-${ANDROID_QUALIFIERS[locale] ?? locale}`;
+const LOCALES = ["values", ...NATIVE_I18N_LOCALES.map(localeDirectory)] as const;
+const STRING_RE = /<string\s+name="([A-Za-z0-9_]+)"([^>]*)>([\s\S]*?)<\/string>/gu;
+const ARRAY_RE = /<string-array\s+name="([A-Za-z0-9_]+)"[^>]*>([\s\S]*?)<\/string-array>/gu;
+const ARRAY_ITEM_RE = /<item>([\s\S]*?)<\/item>/gu;
+const ANDROID_REFERENCE_COMMENT_RE =
+  /("""[\s\S]*?"""|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*')|<!--[\s\S]*?-->|\/\*[\s\S]*?\*\/|\/\/[^\r\n]*/gu;
+const XML_COMMENT_RE = /<!--[\s\S]*?-->/gu;
+const FORMAT_RE = /%\d+\$[a-z]/giu;
+const INVALID_APOSTROPHE_RE = /(?:&apos;|(?<!\\)')/u;
+const GENERATED_HEADER = "    <!-- Generated by scripts/android-app-i18n.ts. -->";
+const GENERATED_KOTLIN_HEADER = "// Generated by scripts/android-app-i18n.ts. Do not edit.";
+const THIRD_PARTY_STRINGS_FILE = "accessibility_strings.xml";
+const THIRD_PARTY_STRINGS_REPO_PATH =
+  "apps/android/app/src/thirdParty/res/values/accessibility_strings.xml";
+const THIRD_PARTY_GENERATED_RESOURCE_RE =
+  /^apps\/android\/app\/src\/thirdParty\/res\/values-[^/]+\/accessibility_strings\.xml$/;
+const WEAR_STRINGS_REPO_PATH = "apps/android/wear/src/main/res/values/strings.xml";
+const WEAR_GENERATED_RESOURCE_RE =
+  /^apps\/android\/wear\/src\/main\/res\/values-[^/]+\/strings\.xml$/;
+
+type NativeInventoryEntry = {
+  id: string;
+  source: string;
+  sites: Array<{ kind: string; path: string }>;
+  surface: "android" | "apple";
+};
+
+type NativeTranslations = Record<string, string>;
+
+type ResourceString = {
+  attrs: string;
+  key: string;
+  rawValue: string;
+  value: string;
+};
+
+const GENERATED_TRANSLATION_LINT_IGNORES = [
+  "Typos",
+  "TypographyDashes",
+  "TypographyEllipsis",
+] as const;
+
+type TranslationContradiction = {
+  locale: string;
+  selected: string;
+  source: string;
+  translations: string[];
+};
+
+export type GeneratedCatalog = {
+  contradictions: TranslationContradiction[];
+  kotlin: string;
+  resources: Map<string, string>;
+  sources: Set<string>;
+};
+
+export type AndroidUiLiteralFinding = {
+  line: number;
+  path: string;
+  source: string;
+};
+
+function compareText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function decodeXml(value: string): string {
+  return value
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&amp;", "&")
+    .replaceAll("\\n", "\n")
+    .replaceAll("\\'", "'")
+    .replaceAll('\\"', '"')
+    .replaceAll("\\\\", "\\");
+}
+
+export function decodeAndroidResourceValue(rawValue: string): string {
+  const trimmed = rawValue.trim();
+  const unquoted =
+    trimmed.startsWith('"') && trimmed.endsWith('"') ? trimmed.slice(1, -1) : trimmed;
+  return decodeXml(unquoted);
+}
+
+type KotlinInterpolation = {
+  end: number;
+  start: number;
+  value: string;
+};
+
+function readKotlinInterpolations(source: string): KotlinInterpolation[] | null {
+  const interpolations: KotlinInterpolation[] = [];
+  for (let index = 0; index < source.length; index += 1) {
+    if (source[index] !== "$") {
+      continue;
+    }
+    const next = source[index + 1];
+    if (next !== "{" && !/[A-Za-z_]/u.test(next ?? "")) {
+      continue;
+    }
+    const start = index;
+    if (next !== "{") {
+      index += 2;
+      while (/[A-Za-z0-9_]/u.test(source[index] ?? "")) {
+        index += 1;
+      }
+      interpolations.push({ start, end: index, value: source.slice(start, index) });
+      index -= 1;
+      continue;
+    }
+
+    let depth = 1;
+    let quote: '"' | "'" | null = null;
+    let escaped = false;
+    for (index += 2; index < source.length; index += 1) {
+      const character = source[index];
+      if (escaped) {
+        escaped = false;
+      } else if (quote !== null && character === "\\") {
+        escaped = true;
+      } else if (character === quote) {
+        quote = null;
+      } else if (quote === null && (character === '"' || character === "'")) {
+        quote = character;
+      } else if (quote === null && character === "{") {
+        depth += 1;
+      } else if (quote === null && character === "}") {
+        depth -= 1;
+        if (depth === 0) {
+          const end = index + 1;
+          interpolations.push({ start, end, value: source.slice(start, end) });
+          break;
+        }
+      }
+    }
+    if (depth !== 0) {
+      return null;
+    }
+  }
+  return interpolations;
+}
+
+export function renderAndroidResourceValue(source: string, translated: string): string {
+  let rendered = translated;
+  const sourceInterpolations = readKotlinInterpolations(source);
+  const translatedInterpolations = readKotlinInterpolations(translated);
+  if (sourceInterpolations === null || translatedInterpolations === null) {
+    throw new Error(
+      `Android translation has unbalanced interpolation placeholders: ${JSON.stringify(source)} -> ${JSON.stringify(translated)}`,
+    );
+  }
+  const sourceTokens = sourceInterpolations.map((interpolation) => interpolation.value);
+  const translatedTokens = translatedInterpolations.map((interpolation) => interpolation.value);
+  const tokenCounts = (tokens: readonly string[]) => {
+    const counts = new Map<string, number>();
+    for (const token of tokens) {
+      counts.set(token, (counts.get(token) ?? 0) + 1);
+    }
+    return [...counts].toSorted(([left], [right]) => compareText(left, right));
+  };
+  if (JSON.stringify(tokenCounts(sourceTokens)) !== JSON.stringify(tokenCounts(translatedTokens))) {
+    throw new Error(
+      `Android translation changed interpolation placeholders: ${JSON.stringify(source)} -> ${JSON.stringify(translated)}`,
+    );
+  }
+  if (sourceTokens.length > 0) {
+    const sourceIndices = new Map<string, number[]>();
+    for (const [index, token] of sourceTokens.entries()) {
+      const indices = sourceIndices.get(token) ?? [];
+      indices.push(index + 1);
+      sourceIndices.set(token, indices);
+    }
+    const translatedOccurrences = new Map<string, number>();
+    let cursor = 0;
+    rendered = "";
+    for (const interpolation of translatedInterpolations) {
+      rendered += translated.slice(cursor, interpolation.start).replaceAll("%", "%%");
+      const token = interpolation.value;
+      const occurrence = translatedOccurrences.get(token) ?? 0;
+      translatedOccurrences.set(token, occurrence + 1);
+      const index = sourceIndices.get(token)?.[occurrence];
+      rendered += index ? `%${index}$s` : token;
+      cursor = interpolation.end;
+    }
+    rendered += translated.slice(cursor).replaceAll("%", "%%");
+  }
+  return escapeAndroidResourceValue(rendered);
+}
+
+export function escapeAndroidResourceValue(value: string): string {
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll("\n", "\\n")
+    .replaceAll("'", "\\'")
+    .replaceAll('"', '\\"')
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function escapeKotlin(value: string): string {
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("$", "\\$")
+    .replaceAll("\n", "\\n");
+}
+
+function resourceKey(source: string): string {
+  return `${MANAGED_PREFIX}${createHash("sha256").update(source).digest("hex").slice(0, 16)}`;
+}
+
+function parseStrings(source: string): ResourceString[] {
+  return [...source.matchAll(STRING_RE)].map((match) => ({
+    key: match[1] ?? "",
+    attrs: match[2] ?? "",
+    rawValue: match[3] ?? "",
+    value: decodeXml(match[3] ?? ""),
+  }));
+}
+
+function withGeneratedTranslationLintIgnores(attrs: string): string {
+  const existing = attrs.match(/\btools:ignore\s*=\s*"([^"]*)"/u);
+  const ignores = [
+    ...(existing?.[1]
+      ?.split(",")
+      .map((value) => value.trim())
+      .filter(Boolean) ?? []),
+    ...GENERATED_TRANSLATION_LINT_IGNORES,
+  ];
+  const rendered = `tools:ignore="${[...new Set(ignores)].join(",")}"`;
+  return existing ? attrs.replace(existing[0], rendered) : `${attrs} ${rendered}`;
+}
+
+function parseArrays(source: string): Map<string, string[]> {
+  return new Map(
+    [...source.matchAll(ARRAY_RE)].map((match) => [
+      match[1] ?? "",
+      [...(match[2] ?? "").matchAll(ARRAY_ITEM_RE)].map((item) =>
+        decodeXml((item[1] ?? "").trim()),
+      ),
+    ]),
+  );
+}
+
+async function readStrings(
+  locale: string,
+  resourceRoot = RESOURCE_ROOT,
+  fileName = "strings.xml",
+): Promise<Map<string, ResourceString>> {
+  const source = await readFile(path.join(resourceRoot, locale, fileName), "utf8");
+  return new Map(parseStrings(source).map((entry) => [entry.key, entry]));
+}
+
+async function readAndroidSource(
+  root = SOURCE_ROOT,
+): Promise<Array<{ path: string; source: string }>> {
+  const entries = await readdir(root, { withFileTypes: true });
+  const sources: Array<{ path: string; source: string }> = [];
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      sources.push(...(await readAndroidSource(fullPath)));
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith(".kt")) {
+      sources.push({
+        path: path.relative(ROOT, fullPath).split(path.sep).join("/"),
+        source: await readFile(fullPath, "utf8"),
+      });
+    }
+  }
+  return sources;
+}
+
+async function readAllAndroidSource(): Promise<Array<{ path: string; source: string }>> {
+  return (await Promise.all(ANDROID_SOURCE_ROOTS.map((root) => readAndroidSource(root)))).flat();
+}
+
+type AndroidResourceReferenceSource = {
+  path: string;
+  source: string;
+};
+
+async function readAndroidResourceReferences(
+  root = ANDROID_MAIN_ROOT,
+): Promise<AndroidResourceReferenceSource[]> {
+  const entries = await readdir(root, { withFileTypes: true });
+  const sources: AndroidResourceReferenceSource[] = [];
+  for (const entry of entries) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      // This walk is confined to app/src/main, so Gradle build output is never eligible.
+      sources.push(...(await readAndroidResourceReferences(fullPath)));
+      continue;
+    }
+    if (entry.isFile() && /\.(?:kt|kts|xml)$/u.test(entry.name)) {
+      sources.push({
+        path: path.relative(ROOT, fullPath).split(path.sep).join("/"),
+        source: await readFile(fullPath, "utf8"),
+      });
+    }
+  }
+  return sources;
+}
+
+export function findUnusedAndroidResourceKeys(
+  keys: Iterable<string>,
+  referenceSources: readonly AndroidResourceReferenceSource[],
+): string[] {
+  const references = new Set<string>();
+  for (const reference of referenceSources) {
+    const isXml = reference.path.endsWith(".xml");
+    const source = reference.source.replace(
+      isXml ? XML_COMMENT_RE : ANDROID_REFERENCE_COMMENT_RE,
+      (match) => match.replace(/[^\r\n]/gu, " "),
+    );
+    const pattern = isXml ? /@string\/([A-Za-z0-9_]+)\b/gu : /\bR\.string\.([A-Za-z0-9_]+)\b/gu;
+    for (const match of source.matchAll(pattern)) {
+      if (match[1]) {
+        references.add(match[1]);
+      }
+    }
+  }
+  return [...keys].filter((key) => !references.has(key));
+}
+
+function lineNumber(source: string, offset: number): number {
+  return source.slice(0, offset).split("\n").length;
+}
+
+function decodeKotlinLiteral(value: string): string {
+  return value.replace(
+    /\\(?:u([0-9a-fA-F]{4})|[n"$\\])/gu,
+    (escape, codeUnit: string | undefined) => {
+      if (codeUnit) {
+        return String.fromCharCode(Number.parseInt(codeUnit, 16));
+      }
+      return escape === "\\n" ? "\n" : escape.slice(1);
+    },
+  );
+}
+
+function collectExplicitRuntimeSources(
+  sourceFiles: readonly { path: string; source: string }[],
+): Set<string> {
+  const sources = new Set<string>();
+  const callPattern = /\bnativeString(?:Resource)?\(\s*"((?:\\.|[^"\\])+)"/gu;
+  for (const file of sourceFiles) {
+    if (file.path.endsWith("/i18n/NativeStringResources.kt")) {
+      continue;
+    }
+    for (const match of file.source.matchAll(callPattern)) {
+      if (match[1]) {
+        sources.add(decodeKotlinLiteral(match[1]));
+      }
+    }
+  }
+  return sources;
+}
+
+function collectToolDisplaySources(value: unknown, sources = new Set<string>()): Set<string> {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectToolDisplaySources(item, sources);
+    }
+    return sources;
+  }
+  if (value === null || typeof value !== "object") {
+    return sources;
+  }
+  for (const [key, item] of Object.entries(value)) {
+    if ((key === "title" || key === "label") && typeof item === "string") {
+      sources.add(item);
+    } else {
+      collectToolDisplaySources(item, sources);
+    }
+  }
+  return sources;
+}
+
+async function readToolDisplaySources(): Promise<Set<string>> {
+  return collectToolDisplaySources(JSON.parse(await readFile(TOOL_DISPLAY_PATH, "utf8")));
+}
+
+const DIRECT_UI_LITERAL_PATTERNS = [
+  /\bText\s*\(\s*(?:text\s*=\s*)?"((?:\\.|[^"\\])+)"/gu,
+  /\b(?:ClawPrimaryButton|ClawSecondaryButton|ClawDangerButton|ClawLinkButton)\s*\([^)]*?\btext\s*=\s*"((?:\\.|[^"\\])+)"/gsu,
+  /\b(?:title|subtitle|body|text|label|statusText|confirmLabel|dismissLabel|contentDescription|placeholder|onClickLabel)\s*=\s*"((?:\\.|[^"\\])+)"/gu,
+  /\b(?:title|subtitle|body|text|label|statusText|confirmLabel|dismissLabel|contentDescription|placeholder|onClickLabel)\s*=\s*[^,\n]*\?:\s*"((?:\\.|[^"\\])+)"/gu,
+  /\b(?:_[A-Za-z0-9_]*(?:ErrorText|StatusText)|errorText|statusText)(?:\.value)?\s*=\s*"((?:\\.|[^"\\])+)"/gu,
+  /\bSettingsMetric\s*\(\s*"((?:\\.|[^"\\])+)"/gu,
+  /\bToast\.makeText\s*\([^,]+,\s*"((?:\\.|[^"\\])+)"/gu,
+  /\bset(?:Title|Message|PositiveButton|NegativeButton|NeutralButton)\s*\(\s*"((?:\\.|[^"\\])+)"/gu,
+  /\bnativeString(?:Resource)?\([^)]*\)\s*\+\s*"((?:\\.|[^"\\])+)"/gsu,
+] as const;
+const DIRECT_UI_RAW_LITERAL_PATTERNS = [
+  /\bText\s*\(\s*(?:text\s*=\s*)?"""([\s\S]*?)"""/gu,
+  /\b(?:ClawPrimaryButton|ClawSecondaryButton|ClawDangerButton|ClawLinkButton)\s*\([^)]*?\btext\s*=\s*"""([\s\S]*?)"""/gsu,
+  /\b(?:title|subtitle|body|text|label|statusText|confirmLabel|dismissLabel|contentDescription|placeholder|onClickLabel)\s*=\s*"""([\s\S]*?)"""/gu,
+  /\b(?:title|subtitle|body|text|label|statusText|confirmLabel|dismissLabel|contentDescription|placeholder|onClickLabel)\s*=\s*[^,\n]*\?:\s*"""([\s\S]*?)"""/gu,
+  /\b(?:_[A-Za-z0-9_]*(?:ErrorText|StatusText)|errorText|statusText)(?:\.value)?\s*=\s*"""([\s\S]*?)"""/gu,
+  /\bSettingsMetric\s*\(\s*"""([\s\S]*?)"""/gu,
+  /\bToast\.makeText\s*\([^,]+,\s*"""([\s\S]*?)"""/gu,
+  /\bset(?:Title|Message|PositiveButton|NegativeButton|NeutralButton)\s*\(\s*"""([\s\S]*?)"""/gu,
+  /\bnativeString(?:Resource)?\([^)]*\)\s*\+\s*"""([\s\S]*?)"""/gsu,
+] as const;
+const UI_STRING_HELPER_NAME_RE =
+  /(?:description|detail|error|label|message|nextRun|notice|report|status|subtitle|summary|text|title)$/iu;
+const UI_STRING_FUNCTION_RE = /\bfun\s+(?:<[^>{}]*>\s*)?([A-Za-z_][A-Za-z0-9_]*)\s*/gu;
+const UI_STRING_PROPERTY_RE =
+  /\bval\s+(?:[A-Za-z_][A-Za-z0-9_]*\.)?([A-Za-z_][A-Za-z0-9_]*)\s*:\s*String\s*(?:\n\s*)?get\(\)\s*=\s*/gu;
+const UI_BRANCH_LITERAL_RE = /(?:->|return|\?:)\s*"((?:\\.|[^"\\])+)"/gu;
+const UI_ELSE_BRANCH_LITERAL_RE = /\belse\s*\{?\s*"((?:\\.|[^"\\])+)"/gu;
+const UI_BRANCH_RAW_LITERAL_RE = /(?:->|return|\?:)\s*"""([\s\S]*?)"""/gu;
+const UI_ELSE_BRANCH_RAW_LITERAL_RE = /\belse\s*\{?\s*"""([\s\S]*?)"""/gu;
+const UI_MODEL_STRING_NAME_RE =
+  /^(?:contentDescription|errorText|helperText|onClickLabel|statusText)$/u;
+const UI_MODEL_CLASS_FIELDS = new Map<string, ReadonlySet<string>>([
+  ["CommandItem", new Set(["subtitle", "title"])],
+  ["HomeAttentionRow", new Set(["subtitle", "title"])],
+  ["OverviewMetricCardSpec", new Set(["subtitle", "title", "value"])],
+  ["SettingsToggleRow", new Set(["subtitle", "title"])],
+]);
+const KOTLIN_STRING_LITERAL_RE = /"""([\s\S]*?)"""|"((?:\\.|[^"\\])+?)"/gu;
+
+// These literals are either technical data or immutable source tokens localized at a typed render edge.
+const ALLOWED_UI_LITERALS = new Map<string, ReadonlySet<string>>([
+  [
+    "*",
+    new Set([
+      "0 = exact",
+      "Cron expression, e.g. 0 9 * * *",
+      "D",
+      "Google Chat",
+      "ID",
+      "ISO time, e.g. 2026-07-09T09:30:00Z",
+      "LOG",
+      "O",
+      "OC",
+      "OK",
+      "OPENCLAW",
+      "OpenClaw",
+      "U",
+      "e.g. America/New_York",
+      "current-step-alpha",
+      "gateway-progress",
+      "iMessage",
+      "main, isolated, current, or session:<id>",
+      "n/a",
+      "openclaw gateway",
+      "openclaw qr",
+      "PTT_BUSY: previous push-to-talk turn is still finishing",
+      "WhatsApp",
+    ]),
+  ],
+  ["apps/android/app/src/main/java/ai/openclaw/app/chat/ChatController.kt", new Set(["Off"])],
+  [
+    "apps/android/app/src/main/java/ai/openclaw/app/ui/SkillWorkshopSettingsScreen.kt",
+    new Set(["all", "applied", "held", "pending", "rejected"]),
+  ],
+  [
+    "apps/android/app/src/main/java/ai/openclaw/app/ui/GatewayDiagnostics.kt",
+    new Set(["$versionName-dev"]),
+  ],
+  [
+    "apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatScreen.kt",
+    // Plan checklist chrome: numeric done-counter and checkmark glyph.
+    new Set(["$completedCount/${steps.size}", "✓"]),
+  ],
+  [
+    "apps/android/app/src/main/java/ai/openclaw/app/ui/SettingsScreens.kt",
+    // Discovered-gateway subtitles are host:port endpoints, not translatable copy.
+    new Set(["${endpoint.host}:${endpoint.port}"]),
+  ],
+  [
+    "apps/android/app/src/main/java/ai/openclaw/app/ui/SidebarShell.kt",
+    // Compose animation labels are tooling identifiers, not rendered copy.
+    new Set(["sidebar-content-translation"]),
+  ],
+  [
+    "apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatCommandControls.kt",
+    new Set(["/$name", "help"]),
+  ],
+  [
+    "apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatMessageActions.kt",
+    new Set([">", "> $line"]),
+  ],
+  [
+    "apps/android/wear/src/main/java/ai/openclaw/wear/WearScreens.kt",
+    // Compose animation labels are tooling identifiers, not rendered copy.
+    new Set(["voice-swipe-hint", "voice-swipe-hint-offset"]),
+  ],
+]);
+
+function isAllowedUiLiteral(repoPath: string, source: string): boolean {
+  return (
+    source.trim().length === 0 ||
+    ALLOWED_UI_LITERALS.get("*")?.has(source) === true ||
+    ALLOWED_UI_LITERALS.get(repoPath)?.has(source) === true
+  );
+}
+
+function shouldScanUiLiterals(repoPath: string): boolean {
+  if (repoPath.endsWith("/i18n/NativeStringResources.kt")) {
+    return false;
+  }
+  if (
+    repoPath.endsWith("/AndroidScreenshotFixture.kt") ||
+    repoPath.endsWith("/WearScreenshotMode.kt")
+  ) {
+    return false;
+  }
+  if (repoPath.endsWith("/ui/design/ClawComponents.kt")) {
+    return false;
+  }
+  if (repoPath.endsWith("/ui/design/OpenClawMascot.kt")) {
+    return false;
+  }
+  return (
+    repoPath.includes("/ui/") ||
+    repoPath.endsWith("/accessibility/AccessibilityDevActivity.kt") ||
+    repoPath.includes("/wear/src/main/java/ai/openclaw/wear/") ||
+    repoPath.endsWith("/MainActivity.kt") ||
+    repoPath.endsWith("/NodeRuntime.kt") ||
+    repoPath.endsWith("/PermissionRequester.kt") ||
+    repoPath.endsWith("/NodeForegroundService.kt") ||
+    repoPath.endsWith("/chat/ChatController.kt") ||
+    repoPath.endsWith("/voice/MicCaptureManager.kt") ||
+    repoPath.endsWith("/voice/TalkModeManager.kt") ||
+    repoPath.endsWith("/node/SystemHandler.kt")
+  );
+}
+
+function findClosingDelimiter(
+  source: string,
+  openingOffset: number,
+  opening: string,
+  closing: string,
+): number | null {
+  let depth = 0;
+  let quoted = false;
+  let escaped = false;
+  for (let index = openingOffset; index < source.length; index += 1) {
+    const character = source[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quoted && character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === '"') {
+      quoted = !quoted;
+      continue;
+    }
+    if (quoted) {
+      continue;
+    }
+    if (character === opening) {
+      depth += 1;
+    } else if (character === closing) {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return null;
+}
+
+function expressionEnd(source: string, expressionStart: number): number {
+  const cursor = source.slice(expressionStart).search(/\S/u);
+  if (cursor < 0) {
+    return source.length;
+  }
+  const start = expressionStart + cursor;
+  let quoted = false;
+  let escaped = false;
+  let lineStart = start;
+  const depths = { "(": 0, "[": 0, "{": 0 };
+  const closingToOpening = { ")": "(", "]": "[", "}": "{" } as const;
+  for (let index = start; index < source.length; index += 1) {
+    const character = source[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quoted && character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === '"') {
+      quoted = !quoted;
+      continue;
+    }
+    if (quoted) {
+      continue;
+    }
+    if (character === "(" || character === "[" || character === "{") {
+      depths[character] += 1;
+      continue;
+    }
+    if (character === ")" || character === "]" || character === "}") {
+      depths[closingToOpening[character]] -= 1;
+      continue;
+    }
+    if (character !== "\n" || !Object.values(depths).every((depth) => depth === 0)) {
+      continue;
+    }
+    const line = source.slice(lineStart, index).trimEnd();
+    const nextLine =
+      source
+        .slice(index + 1)
+        .match(/^[^\S\n]*([^\n]*)/u)?.[1]
+        ?.trimStart() ?? "";
+    const continues =
+      line.length === 0 ||
+      /(?:\?:|[+*/%&|=.,([{])$/u.test(line) ||
+      /^(?:else\b|\?:|[+*/%&|.])/u.test(nextLine);
+    if (!continues) {
+      return index;
+    }
+    lineStart = index + 1;
+  }
+  return source.length;
+}
+
+function splitTopLevelSegments(
+  source: string,
+  start: number,
+  end: number,
+  options: { trackTypeArguments?: boolean } = {},
+): Array<{ end: number; start: number; value: string }> {
+  const segments: Array<{ end: number; start: number; value: string }> = [];
+  let segmentStart = start;
+  let quoted = false;
+  let escaped = false;
+  let typeArgumentDepth = 0;
+  let inDefaultValue = false;
+  const depths = { "(": 0, "[": 0, "{": 0 };
+  const closingToOpening = { ")": "(", "]": "[", "}": "{" } as const;
+  for (let index = start; index < end; index += 1) {
+    const character = source[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quoted && character === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (character === '"') {
+      quoted = !quoted;
+      continue;
+    }
+    if (quoted) {
+      continue;
+    }
+    if (options.trackTypeArguments && !inDefaultValue && character === "<") {
+      typeArgumentDepth += 1;
+      continue;
+    }
+    if (options.trackTypeArguments && character === ">" && typeArgumentDepth > 0) {
+      typeArgumentDepth -= 1;
+      continue;
+    }
+    if (character === "(" || character === "[" || character === "{") {
+      depths[character] += 1;
+      continue;
+    }
+    if (character === ")" || character === "]" || character === "}") {
+      depths[closingToOpening[character]] -= 1;
+      continue;
+    }
+    if (
+      options.trackTypeArguments &&
+      character === "=" &&
+      typeArgumentDepth === 0 &&
+      Object.values(depths).every((depth) => depth === 0)
+    ) {
+      inDefaultValue = true;
+      continue;
+    }
+    if (
+      character === "," &&
+      typeArgumentDepth === 0 &&
+      Object.values(depths).every((depth) => depth === 0)
+    ) {
+      segments.push({ end: index, start: segmentStart, value: source.slice(segmentStart, index) });
+      segmentStart = index + 1;
+      inDefaultValue = false;
+    }
+  }
+  segments.push({ end, start: segmentStart, value: source.slice(segmentStart, end) });
+  return segments;
+}
+
+function isLocalizedLiteral(expression: string, literalOffset: number): boolean {
+  return /\bnativeString(?:Resource)?\(\s*$/u.test(expression.slice(0, literalOffset));
+}
+
+function isComparisonLiteral(expression: string, literalOffset: number): boolean {
+  return /(?:==|!=)\s*$/u.test(expression.slice(0, literalOffset));
+}
+
+function collectHelperLiteralFindings(source: string, repoPath: string): AndroidUiLiteralFinding[] {
+  const findings: AndroidUiLiteralFinding[] = [];
+  const collectRange = (name: string, start: number, end: number) => {
+    if (!UI_STRING_HELPER_NAME_RE.test(name)) {
+      return;
+    }
+    const body = source.slice(start, end);
+    const direct = body.match(/^\s*"((?:\\.|[^"\\])+)"/u);
+    const directRaw = body.match(/^\s*"""([\s\S]*?)"""/u);
+    const matches = [
+      ...(direct ? [direct] : []),
+      ...(directRaw ? [directRaw] : []),
+      ...body.matchAll(UI_BRANCH_LITERAL_RE),
+      ...body.matchAll(UI_ELSE_BRANCH_LITERAL_RE),
+      ...body.matchAll(UI_BRANCH_RAW_LITERAL_RE),
+      ...body.matchAll(UI_ELSE_BRANCH_RAW_LITERAL_RE),
+    ];
+    const seenOffsets = new Set<number>();
+    const addLiteral = (literal: string, literalOffset: number) => {
+      if (seenOffsets.has(literalOffset)) {
+        return;
+      }
+      seenOffsets.add(literalOffset);
+      findings.push({
+        line: lineNumber(source, start + literalOffset),
+        path: repoPath,
+        source: decodeKotlinLiteral(literal),
+      });
+    };
+    for (const match of matches) {
+      const literal = match[1];
+      if (!literal) {
+        continue;
+      }
+      const delimiter = match[0]?.includes('"""') ? '"""' : '"';
+      const literalOffset = body.indexOf(`${delimiter}${literal}${delimiter}`, match.index ?? 0);
+      addLiteral(literal, Math.max(0, literalOffset));
+    }
+    for (const match of body.matchAll(/\bif\s*/gu)) {
+      let cursor = (match.index ?? 0) + match[0].length;
+      if (body[cursor] !== "(") {
+        continue;
+      }
+      const closingParen = findClosingDelimiter(body, cursor, "(", ")");
+      if (closingParen === null) {
+        continue;
+      }
+      cursor = closingParen + 1;
+      while (/\s/u.test(body[cursor] ?? "")) {
+        cursor += 1;
+      }
+      if (body[cursor] === "{") {
+        cursor += 1;
+        while (/\s/u.test(body[cursor] ?? "")) {
+          cursor += 1;
+        }
+      }
+      const expression = body.slice(cursor);
+      const literal =
+        expression.match(/^"""([\s\S]*?)"""/u)?.[1] ??
+        expression.match(/^"((?:\\.|[^"\\])+)"/u)?.[1];
+      if (literal) {
+        addLiteral(literal, cursor);
+      }
+    }
+  };
+  for (const match of source.matchAll(UI_STRING_FUNCTION_RE)) {
+    const name = match[1];
+    if (!name) {
+      continue;
+    }
+    let openingParen = (match.index ?? 0) + match[0].length;
+    while (/\s/u.test(source[openingParen] ?? "")) {
+      openingParen += 1;
+    }
+    if (source[openingParen] !== "(") {
+      continue;
+    }
+    const closingParen = findClosingDelimiter(source, openingParen, "(", ")");
+    if (closingParen === null) {
+      continue;
+    }
+    const returnType = source.slice(closingParen + 1).match(/^\s*:\s*String\s*(=|\{)/u);
+    const bodyKind = returnType?.[1];
+    if (!bodyKind || returnType?.index === undefined) {
+      continue;
+    }
+    const bodyStart = closingParen + 1 + returnType.index + returnType[0].length;
+    if (bodyKind === "{") {
+      const openingBrace = bodyStart - 1;
+      const closingBrace = findClosingDelimiter(source, openingBrace, "{", "}");
+      if (closingBrace !== null) {
+        collectRange(name, bodyStart, closingBrace);
+      }
+    } else {
+      collectRange(name, bodyStart, expressionEnd(source, bodyStart));
+    }
+  }
+  for (const match of source.matchAll(UI_STRING_PROPERTY_RE)) {
+    const name = match[1];
+    if (!name) {
+      continue;
+    }
+    const bodyStart = (match.index ?? 0) + match[0].length;
+    collectRange(name, bodyStart, expressionEnd(source, bodyStart));
+  }
+  return findings;
+}
+
+function collectTypedModelLiteralFindings(
+  source: string,
+  repoPath: string,
+): AndroidUiLiteralFinding[] {
+  const findings: AndroidUiLiteralFinding[] = [];
+  const classPattern = /\b(?:data\s+class|class)\s+([A-Za-z_][A-Za-z0-9_]*)\s*/gu;
+  for (const declaration of source.matchAll(classPattern)) {
+    const className = declaration[1];
+    if (!className) {
+      continue;
+    }
+    let openingParen = (declaration.index ?? 0) + declaration[0].length;
+    while (/\s/u.test(source[openingParen] ?? "")) {
+      openingParen += 1;
+    }
+    if (source[openingParen] === "<") {
+      const closingTypeArguments = findClosingDelimiter(source, openingParen, "<", ">");
+      if (closingTypeArguments === null) {
+        continue;
+      }
+      openingParen = closingTypeArguments + 1;
+      while (/\s/u.test(source[openingParen] ?? "")) {
+        openingParen += 1;
+      }
+    }
+    if (source[openingParen] !== "(") {
+      continue;
+    }
+    const closingParen = findClosingDelimiter(source, openingParen, "(", ")");
+    if (closingParen === null) {
+      continue;
+    }
+    const parameters = splitTopLevelSegments(source, openingParen + 1, closingParen, {
+      trackTypeArguments: true,
+    });
+    const userFacingParameters = new Map<string, number>();
+    const classFields = UI_MODEL_CLASS_FIELDS.get(className);
+    parameters.forEach((parameter, index) => {
+      const field = parameter.value.match(
+        /\bval\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*String\??(?=\s*(?:=|$))/u,
+      )?.[1];
+      if (field && (UI_MODEL_STRING_NAME_RE.test(field) || classFields?.has(field))) {
+        userFacingParameters.set(field, index);
+      }
+    });
+    if (userFacingParameters.size === 0) {
+      continue;
+    }
+    const callPattern = new RegExp(`\\b${className}\\b`, "gu");
+    for (const call of source.matchAll(callPattern)) {
+      let callOpening = (call.index ?? 0) + call[0].length;
+      while (/\s/u.test(source[callOpening] ?? "")) {
+        callOpening += 1;
+      }
+      if (source[callOpening] === "<") {
+        const closingTypeArguments = findClosingDelimiter(source, callOpening, "<", ">");
+        if (closingTypeArguments === null) {
+          continue;
+        }
+        callOpening = closingTypeArguments + 1;
+        while (/\s/u.test(source[callOpening] ?? "")) {
+          callOpening += 1;
+        }
+      }
+      if (source[callOpening] !== "(") {
+        continue;
+      }
+      if (callOpening === openingParen) {
+        continue;
+      }
+      const callClosing = findClosingDelimiter(source, callOpening, "(", ")");
+      if (callClosing === null) {
+        continue;
+      }
+      const argumentsList = splitTopLevelSegments(source, callOpening + 1, callClosing);
+      const namedArguments = new Map<string, (typeof argumentsList)[number]>();
+      let positionalArgumentCount = argumentsList.length;
+      argumentsList.forEach((argument, index) => {
+        const name = argument.value.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=(?!=)/u)?.[1];
+        if (!name) {
+          return;
+        }
+        namedArguments.set(name, argument);
+        positionalArgumentCount = Math.min(positionalArgumentCount, index);
+      });
+      for (const [field, parameterIndex] of userFacingParameters) {
+        const argument =
+          namedArguments.get(field) ??
+          (parameterIndex < positionalArgumentCount ? argumentsList[parameterIndex] : undefined);
+        if (!argument) {
+          continue;
+        }
+        for (const literal of argument.value.matchAll(KOTLIN_STRING_LITERAL_RE)) {
+          const literalValue = literal[1] ?? literal[2];
+          if (
+            !literalValue ||
+            isLocalizedLiteral(argument.value, literal.index ?? 0) ||
+            isComparisonLiteral(argument.value, literal.index ?? 0)
+          ) {
+            continue;
+          }
+          findings.push({
+            line: lineNumber(source, argument.start + (literal.index ?? 0)),
+            path: repoPath,
+            source: literal[1] === undefined ? decodeKotlinLiteral(literalValue) : literalValue,
+          });
+        }
+      }
+    }
+  }
+  return findings;
+}
+
+export function findUnlocalizedAndroidUiLiterals(
+  source: string,
+  repoPath: string,
+): AndroidUiLiteralFinding[] {
+  if (!shouldScanUiLiterals(repoPath)) {
+    return [];
+  }
+  const findings = new Map<string, AndroidUiLiteralFinding>();
+  for (const [patterns, delimiter] of [
+    [DIRECT_UI_LITERAL_PATTERNS, '"'],
+    [DIRECT_UI_RAW_LITERAL_PATTERNS, '"""'],
+  ] as const) {
+    for (const pattern of patterns) {
+      pattern.lastIndex = 0;
+      for (const match of source.matchAll(pattern)) {
+        const literal = match[1];
+        if (!literal) {
+          continue;
+        }
+        const findingSource = delimiter === '"' ? decodeKotlinLiteral(literal) : literal;
+        if (
+          isAllowedUiLiteral(repoPath, findingSource) ||
+          literal.startsWith("http") ||
+          literal.startsWith("content://")
+        ) {
+          continue;
+        }
+        const matchText = match[0] ?? "";
+        const offset =
+          (match.index ?? 0) + matchText.lastIndexOf(`${delimiter}${literal}${delimiter}`);
+        const finding = {
+          line: lineNumber(source, Math.max(0, offset)),
+          path: repoPath,
+          source: findingSource,
+        };
+        findings.set(`${finding.line}\u0000${finding.source}`, finding);
+      }
+    }
+  }
+  for (const finding of [
+    ...collectHelperLiteralFindings(source, repoPath),
+    ...collectTypedModelLiteralFindings(source, repoPath),
+  ]) {
+    if (!isAllowedUiLiteral(repoPath, finding.source)) {
+      findings.set(`${finding.line}\u0000${finding.source}`, finding);
+    }
+  }
+  return [...findings.values()].toSorted(
+    (left, right) => left.line - right.line || compareText(left.source, right.source),
+  );
+}
+
+function findInvalidResourceSyntax(strings: ReadonlyMap<string, ResourceString>): string[] {
+  return [...strings]
+    .filter(([, entry]) => {
+      const trimmed = entry.rawValue.trim();
+      const isQuoted = trimmed.startsWith('"') && trimmed.endsWith('"');
+      return !isQuoted && INVALID_APOSTROPHE_RE.test(trimmed);
+    })
+    .map(([key]) => key);
+}
+
+export function selectDeterministicTranslation(source: string, values: readonly string[]): string {
+  const translated = values.filter((value) => value !== source);
+  const candidates = translated.length > 0 ? translated : values;
+  const counts = new Map<string, number>();
+  for (const value of candidates) {
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  return (
+    [...counts]
+      .toSorted(
+        ([left, leftCount], [right, rightCount]) =>
+          rightCount - leftCount || compareText(left, right),
+      )
+      .at(0)?.[0] ?? ""
+  );
+}
+
+export function selectGeneratedTranslation(
+  source: string,
+  artifactTranslations: readonly string[],
+  existing?: { source: string; translation: string },
+): string {
+  // Tool-display sources can remain live after their matching UI inventory entries are retired.
+  // Preserve the checked-in locale value only while its English source is unchanged.
+  const candidates =
+    artifactTranslations.length > 0
+      ? artifactTranslations
+      : existing?.source === source && existing.translation !== source
+        ? [existing.translation]
+        : [];
+  return selectDeterministicTranslation(source, candidates);
+}
+
+async function readInventory(): Promise<NativeInventoryEntry[]> {
+  const parsed = JSON.parse(await readFile(INVENTORY_PATH, "utf8")) as {
+    entries?: NativeInventoryEntry[];
+  };
+  return (parsed.entries ?? []).filter((entry) => entry.surface === "android");
+}
+
+async function readArtifacts(): Promise<Map<string, NativeTranslations>> {
+  return new Map(
+    await Promise.all(
+      NATIVE_I18N_LOCALES.map(async (locale) => {
+        const parsed = JSON.parse(
+          await readFile(path.join(ARTIFACT_ROOT, `${locale}.json`), "utf8"),
+        ) as { translations?: NativeTranslations };
+        return [locale, parsed.translations ?? {}] as const;
+      }),
+    ),
+  );
+}
+
+function translationsBySource(
+  inventory: readonly NativeInventoryEntry[],
+  translationsById: Readonly<NativeTranslations>,
+): Map<string, string[]> {
+  const translations = new Map<string, string[]>();
+  for (const entry of inventory) {
+    const translated = translationsById[entry.id];
+    if (translated !== undefined) {
+      translations.set(entry.source, [translated]);
+    }
+  }
+  return translations;
+}
+
+function localizeManualStrings(
+  base: ReadonlyMap<string, ResourceString>,
+  inventoryBySource: ReadonlyMap<string, NativeInventoryEntry>,
+  translations: Readonly<NativeTranslations>,
+  surface: string,
+): ResourceString[] {
+  return [...base.values()].map((entry) => {
+    const source = decodeAndroidResourceValue(entry.rawValue);
+    const translatable = !/\btranslatable\s*=\s*"false"/u.test(entry.attrs);
+    const inventoryEntry = inventoryBySource.get(source);
+    if (translatable && !inventoryEntry) {
+      throw new Error(
+        `${surface} string is missing from native inventory: ${JSON.stringify(source)}`,
+      );
+    }
+    const value = (translatable && inventoryEntry && translations[inventoryEntry.id]) || source;
+    return {
+      attrs: translatable ? withGeneratedTranslationLintIgnores(entry.attrs) : entry.attrs,
+      key: entry.key,
+      rawValue: `"${escapeAndroidResourceValue(value)}"`,
+      value,
+    };
+  });
+}
+
+function renderStringsXml(
+  manual: readonly ResourceString[],
+  generated: ReadonlyMap<string, { source: string; value: string }>,
+): string {
+  const usesToolsNamespace =
+    generated.size > 0 || manual.some((entry) => entry.attrs.includes("tools:"));
+  const lines = [
+    usesToolsNamespace
+      ? '<resources xmlns:tools="http://schemas.android.com/tools">'
+      : "<resources>",
+  ];
+  for (const entry of manual) {
+    lines.push(`    <string name="${entry.key}"${entry.attrs}>${entry.rawValue}</string>`);
+  }
+  if (generated.size > 0) {
+    lines.push(GENERATED_HEADER);
+    for (const [key, entry] of [...generated].toSorted(([left], [right]) =>
+      compareText(left, right),
+    )) {
+      const formatted =
+        (readKotlinInterpolations(entry.source)?.length ?? 0) > 0 ? "" : ' formatted="false"';
+      // Translation-memory text intentionally preserves technical tokens and source punctuation,
+      // so Android's English dictionary and typography suggestions do not apply to managed keys.
+      lines.push(
+        `    <string name="${key}"${withGeneratedTranslationLintIgnores(formatted)}>"${renderAndroidResourceValue(entry.source, entry.value)}"</string>`,
+      );
+    }
+  }
+  lines.push("</resources>", "");
+  return lines.join("\n");
+}
+
+function renderAssistantXml(items: readonly string[]): string {
+  return [
+    "<resources>",
+    '    <string-array name="ask_openclaw_query_patterns">',
+    ...items.map((item) => `        <item>"${renderAndroidResourceValue(item, item)}"</item>`),
+    "    </string-array>",
+    "</resources>",
+    "",
+  ].join("\n");
+}
+
+function renderKotlin(sourceToKey: ReadonlyMap<string, string>): string {
+  const entries = [...sourceToKey].toSorted(([left], [right]) => compareText(left, right));
+  return [
+    GENERATED_KOTLIN_HEADER,
+    "package ai.openclaw.app.i18n",
+    "",
+    "import ai.openclaw.app.R",
+    "",
+    "internal val nativeStringResourceIds: Map<String, Int> =",
+    "  mapOf(",
+    ...entries.map(([source, key]) => `    "${escapeKotlin(source)}" to R.string.${key},`),
+    "  )",
+    "",
+  ].join("\n");
+}
+
+export async function buildAndroidAppI18nCatalog(): Promise<GeneratedCatalog> {
+  const inventory = await readInventory();
+  const [
+    artifacts,
+    localeStrings,
+    thirdPartyBaseStrings,
+    wearBaseStrings,
+    sourceFiles,
+    toolDisplaySources,
+  ] = await Promise.all([
+    readArtifacts(),
+    Promise.all(LOCALES.map((locale) => readStrings(locale))),
+    readStrings("values", ANDROID_THIRD_PARTY_RESOURCE_ROOT, THIRD_PARTY_STRINGS_FILE),
+    readStrings("values", WEAR_RESOURCE_ROOT),
+    readAllAndroidSource(),
+    readToolDisplaySources(),
+  ]);
+  const baseStrings = expectDefined(localeStrings[0], "English Android string resources");
+  const translatedStrings = localeStrings.slice(1);
+  const wearInventoryBySource = new Map(
+    inventory
+      .filter((entry) => entry.sites.some((site) => site.path === WEAR_STRINGS_REPO_PATH))
+      .map((entry) => [entry.source, entry]),
+  );
+  const thirdPartyInventoryBySource = new Map(
+    inventory
+      .filter((entry) => entry.sites.some((site) => site.path === THIRD_PARTY_STRINGS_REPO_PATH))
+      .map((entry) => [entry.source, entry]),
+  );
+  const manualBase = [...baseStrings.values()].filter(
+    (entry) => !entry.key.startsWith(MANAGED_PREFIX),
+  );
+  const manualSourceToKey = new Map(manualBase.map((entry) => [entry.value, entry.key]));
+  const entriesBySource = new Map<string, NativeInventoryEntry[]>();
+  for (const entry of inventory) {
+    if (
+      entry.surface !== "android" ||
+      entry.sites.every((site) => site.kind === "resource-string")
+    ) {
+      continue;
+    }
+    const group = entriesBySource.get(entry.source) ?? [];
+    group.push(entry);
+    entriesBySource.set(entry.source, group);
+  }
+  for (const source of collectExplicitRuntimeSources(sourceFiles)) {
+    if (!entriesBySource.has(source)) {
+      entriesBySource.set(source, []);
+    }
+  }
+  for (const source of toolDisplaySources) {
+    if (!entriesBySource.has(source)) {
+      entriesBySource.set(source, []);
+    }
+  }
+  const sourceToKey = new Map<string, string>();
+  for (const source of entriesBySource.keys()) {
+    sourceToKey.set(source, manualSourceToKey.get(source) ?? resourceKey(source));
+  }
+  const resources = new Map<string, string>();
+  const contradictions: TranslationContradiction[] = [];
+  for (const [localeIndex, locale] of NATIVE_I18N_LOCALES.entries()) {
+    const manualTranslations = translatedStrings[localeIndex] ?? new Map();
+    const localeTranslations = artifacts.get(locale) ?? {};
+    const artifactTranslationsBySource = translationsBySource(inventory, localeTranslations);
+    const generated = new Map<string, { source: string; value: string }>();
+    for (const source of entriesBySource.keys()) {
+      const key = sourceToKey.get(source);
+      if (!key || !key.startsWith(MANAGED_PREFIX)) {
+        continue;
+      }
+      const translations = artifactTranslationsBySource.get(source) ?? [];
+      const existingSource = decodeAndroidResourceValue(baseStrings.get(key)?.rawValue ?? "");
+      const existingTranslation = decodeAndroidResourceValue(
+        manualTranslations.get(key)?.rawValue ?? "",
+      );
+      const selected = selectGeneratedTranslation(
+        source,
+        translations,
+        existingSource && existingTranslation
+          ? { source: existingSource, translation: existingTranslation }
+          : undefined,
+      );
+      if (selected === source && translations.some((translation) => translation !== source)) {
+        throw new Error(
+          `Android translation selection kept the source despite a translated candidate: ${locale} ${JSON.stringify(source)}`,
+        );
+      }
+      const unique = [...new Set(translations)].toSorted(compareText);
+      if (unique.length > 1) {
+        contradictions.push({ locale, selected, source, translations: unique });
+      }
+      generated.set(key, {
+        source,
+        value: selected || source,
+      });
+    }
+    const manual = [...manualTranslations.values()].filter(
+      (entry) => !entry.key.startsWith(MANAGED_PREFIX),
+    );
+    resources.set(
+      path.join(RESOURCE_ROOT, localeDirectory(locale), "strings.xml"),
+      renderStringsXml(manual, generated),
+    );
+    const wearManual = localizeManualStrings(
+      wearBaseStrings,
+      wearInventoryBySource,
+      localeTranslations,
+      "Wear",
+    );
+    resources.set(
+      path.join(WEAR_RESOURCE_ROOT, localeDirectory(locale), "strings.xml"),
+      renderStringsXml(wearManual, new Map()),
+    );
+    const thirdPartyManual = localizeManualStrings(
+      thirdPartyBaseStrings,
+      thirdPartyInventoryBySource,
+      localeTranslations,
+      "Android third-party",
+    );
+    resources.set(
+      path.join(
+        ANDROID_THIRD_PARTY_RESOURCE_ROOT,
+        localeDirectory(locale),
+        THIRD_PARTY_STRINGS_FILE,
+      ),
+      renderStringsXml(thirdPartyManual, new Map()),
+    );
+  }
+  const generatedBase = new Map<string, { source: string; value: string }>();
+  for (const [source, key] of sourceToKey) {
+    if (!key.startsWith(MANAGED_PREFIX)) {
+      continue;
+    }
+    generatedBase.set(key, {
+      source,
+      value: source,
+    });
+  }
+  resources.set(
+    path.join(RESOURCE_ROOT, "values", "strings.xml"),
+    renderStringsXml(manualBase, generatedBase),
+  );
+
+  const assistantSource = await readFile(
+    path.join(RESOURCE_ROOT, "values", "assistant.xml"),
+    "utf8",
+  );
+  const assistantItems = parseArrays(assistantSource).get("ask_openclaw_query_patterns") ?? [];
+  for (const [locale, localeTranslations] of artifacts) {
+    const translatedBySource = translationsBySource(inventory, localeTranslations);
+    const translatedItems = assistantItems.map(
+      (source) =>
+        selectDeterministicTranslation(source, translatedBySource.get(source) ?? []) || source,
+    );
+    resources.set(
+      path.join(RESOURCE_ROOT, localeDirectory(locale), "assistant.xml"),
+      renderAssistantXml(translatedItems),
+    );
+  }
+
+  return {
+    contradictions,
+    kotlin: renderKotlin(sourceToKey),
+    resources,
+    sources: new Set(sourceToKey.keys()),
+  };
+}
+
+function formatProblems(problems: Array<readonly [string, string[]]>): string {
+  return [
+    "Android i18n resources are out of sync.",
+    ...problems.map(([label, keys]) => `${label}=${keys.join(",") || "none"}`),
+  ].join("\n");
+}
+
+/**
+ * Managed app rows (native_*) and localized Wear catalogs are owned end-to-end
+ * by the post-merge locale refresh workflow, so a source PR may legitimately
+ * carry stale generated output. Every other delta is real drift.
+ */
+function onlyManagedRowsPending(current: string, expected: string): boolean {
+  const currentRows = new Map(parseStrings(current).map((entry) => [entry.key, entry]));
+  const expectedRows = new Map(parseStrings(expected).map((entry) => [entry.key, entry]));
+  for (const [key, entry] of currentRows) {
+    const expectedEntry = expectedRows.get(key);
+    if (!expectedEntry) {
+      if (!key.startsWith(MANAGED_PREFIX)) {
+        return false;
+      }
+      continue;
+    }
+    if (expectedEntry.attrs !== entry.attrs || expectedEntry.rawValue !== entry.rawValue) {
+      return false;
+    }
+  }
+  for (const key of expectedRows.keys()) {
+    if (!currentRows.has(key) && !key.startsWith(MANAGED_PREFIX)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export async function syncAndroidAppI18n(
+  options: { check?: boolean; tolerateManagedPending?: boolean } = {},
+) {
+  const catalog = await buildAndroidAppI18nCatalog();
+  const drift: string[] = [];
+  let sawUnmanagedDrift = false;
+  for (const [filePath, expected] of catalog.resources) {
+    const current = await readFile(filePath, "utf8").catch(() => "");
+    if (current === expected) {
+      continue;
+    }
+    const relativeFilePath = path.relative(ROOT, filePath).split(path.sep).join("/");
+    if (
+      options.check &&
+      options.tolerateManagedPending &&
+      (WEAR_GENERATED_RESOURCE_RE.test(relativeFilePath) ||
+        THIRD_PARTY_GENERATED_RESOURCE_RE.test(relativeFilePath) ||
+        (filePath.endsWith("strings.xml") && onlyManagedRowsPending(current, expected)))
+    ) {
+      continue;
+    }
+    sawUnmanagedDrift = true;
+    drift.push(relativeFilePath);
+    if (!options.check) {
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await writeFile(filePath, expected);
+    }
+  }
+  const currentKotlin = await readFile(GENERATED_KOTLIN_PATH, "utf8").catch(() => "");
+  if (currentKotlin !== catalog.kotlin) {
+    // The Kotlin map derives 1:1 from the same managed catalog: tolerate it
+    // exactly when every resource delta above was managed-pending.
+    if (!(options.check && options.tolerateManagedPending && !sawUnmanagedDrift)) {
+      drift.push(path.relative(ROOT, GENERATED_KOTLIN_PATH).split(path.sep).join("/"));
+      if (!options.check) {
+        await writeFile(GENERATED_KOTLIN_PATH, catalog.kotlin);
+      }
+    }
+  }
+  if (options.check && drift.length > 0) {
+    throw new Error(`Android generated localization drift:\n${drift.join("\n")}`);
+  }
+  if (catalog.contradictions.length > 0) {
+    const limit = 20;
+    const visible = catalog.contradictions.slice(0, limit);
+    const remaining = catalog.contradictions.length - visible.length;
+    process.stderr.write(
+      [
+        `android-app-i18n: contradictions=${catalog.contradictions.length}`,
+        ...visible.map(
+          (finding) =>
+            `${finding.locale}: ${JSON.stringify(finding.source)} -> ${JSON.stringify(finding.selected)} (${finding.translations.map((translation) => JSON.stringify(translation)).join(", ")})`,
+        ),
+        ...(remaining > 0 ? [`android-app-i18n: ${remaining} more contradictions omitted`] : []),
+        "",
+      ].join("\n"),
+    );
+  }
+  return catalog;
+}
+
+export async function verifyAndroidAppI18n() {
+  const [
+    sourceFiles,
+    base,
+    referenceSource,
+    thirdPartyBase,
+    thirdPartyReferenceSource,
+    wearBase,
+    wearReferenceSource,
+  ] = await Promise.all([
+    readAllAndroidSource(),
+    readStrings("values"),
+    readAndroidResourceReferences(),
+    readStrings("values", ANDROID_THIRD_PARTY_RESOURCE_ROOT, THIRD_PARTY_STRINGS_FILE),
+    readAndroidResourceReferences(ANDROID_THIRD_PARTY_ROOT),
+    readStrings("values", WEAR_RESOURCE_ROOT),
+    readAndroidResourceReferences(ANDROID_WEAR_MAIN_ROOT),
+  ]);
+  const baseKeys = new Set(base.keys());
+  const thirdPartyBaseKeys = new Set(thirdPartyBase.keys());
+  const wearBaseKeys = new Set(wearBase.keys());
+  const problems: Array<readonly [string, string[]]> = [
+    ["App English syntax", findInvalidResourceSyntax(base)],
+    ["Third-party English syntax", findInvalidResourceSyntax(thirdPartyBase)],
+    ["Wear English syntax", findInvalidResourceSyntax(wearBase)],
+  ];
+  const manualBaseKeys = [...baseKeys].filter((key) => !key.startsWith(MANAGED_PREFIX));
+  problems.push([
+    "App English unused",
+    findUnusedAndroidResourceKeys(manualBaseKeys, referenceSource),
+  ]);
+  problems.push([
+    "Third-party English unused",
+    findUnusedAndroidResourceKeys(thirdPartyBaseKeys, thirdPartyReferenceSource),
+  ]);
+  problems.push([
+    "Wear English unused",
+    findUnusedAndroidResourceKeys(wearBaseKeys, wearReferenceSource),
+  ]);
+  const uiFindings = sourceFiles.flatMap((file) =>
+    findUnlocalizedAndroidUiLiterals(file.source, file.path),
+  );
+  problems.push([
+    "Unlocalized UI literals",
+    uiFindings.map((finding) => `${finding.path}:${finding.line}:${finding.source}`),
+  ]);
+  if (problems.some(([, keys]) => keys.length)) {
+    throw new Error(formatProblems(problems));
+  }
+  process.stdout.write(
+    `android-app-i18n: appSourceKeys=${baseKeys.size} thirdPartySourceKeys=${thirdPartyBaseKeys.size} wearSourceKeys=${wearBaseKeys.size}\n`,
+  );
+}
+
+export async function checkAndroidAppI18n(options: { tolerateManagedPending?: boolean } = {}) {
+  await verifyAndroidAppI18n();
+  await syncAndroidAppI18n({ check: true, ...options });
+  const localeStrings = await Promise.all(LOCALES.map((locale) => readStrings(locale)));
+  const wearLocaleStrings = options.tolerateManagedPending
+    ? []
+    : await Promise.all(LOCALES.map((locale) => readStrings(locale, WEAR_RESOURCE_ROOT)));
+  const thirdPartyLocaleStrings = options.tolerateManagedPending
+    ? []
+    : await Promise.all(
+        LOCALES.map((locale) =>
+          readStrings(locale, ANDROID_THIRD_PARTY_RESOURCE_ROOT, THIRD_PARTY_STRINGS_FILE),
+        ),
+      );
+  const base = expectDefined(localeStrings[0], "English Android string resources");
+  const localeProblems = (
+    surface: string,
+    surfaceBase: ReadonlyMap<string, ResourceString>,
+    translations: ReadonlyArray<ReadonlyMap<string, ResourceString>>,
+  ): Array<readonly [string, string[]]> => {
+    const surfaceBaseKeys = new Set(surfaceBase.keys());
+    return translations.flatMap((strings, index) => {
+      const locale = NATIVE_I18N_LOCALES[index];
+      const keys = new Set(strings.keys());
+      const placeholderMismatches = [...surfaceBase].flatMap(([key, sourceEntry]) => {
+        const translatedEntry = strings.get(key);
+        if (!translatedEntry) {
+          return [];
+        }
+        const expected = [...sourceEntry.rawValue.matchAll(FORMAT_RE)]
+          .map((match) => match[0])
+          .toSorted();
+        const actual = [...translatedEntry.rawValue.matchAll(FORMAT_RE)]
+          .map((match) => match[0])
+          .toSorted();
+        return expected.join("\u0000") === actual.join("\u0000") ? [] : [key];
+      });
+      return [
+        [`${surface} ${locale} missing`, [...surfaceBaseKeys].filter((key) => !keys.has(key))],
+        [`${surface} ${locale} extra`, [...keys].filter((key) => !surfaceBaseKeys.has(key))],
+        [`${surface} ${locale} placeholders`, placeholderMismatches],
+        [`${surface} ${locale} syntax`, findInvalidResourceSyntax(strings)],
+      ] as const;
+    });
+  };
+  const problems = localeProblems("App", base, localeStrings.slice(1));
+  if (thirdPartyLocaleStrings.length > 0) {
+    const thirdPartyBase = expectDefined(
+      thirdPartyLocaleStrings[0],
+      "English Android third-party string resources",
+    );
+    problems.push(
+      ...localeProblems("Third-party", thirdPartyBase, thirdPartyLocaleStrings.slice(1)),
+    );
+  }
+  if (wearLocaleStrings.length > 0) {
+    const wearBase = expectDefined(wearLocaleStrings[0], "English Wear string resources");
+    problems.push(...localeProblems("Wear", wearBase, wearLocaleStrings.slice(1)));
+  }
+  if (problems.some(([, keys]) => keys.length)) {
+    throw new Error(formatProblems(problems));
+  }
+  process.stdout.write(
+    `android-app-i18n: appKeys=${base.size} locales=${NATIVE_I18N_LOCALES.join(",")}\n`,
+  );
+}
+
+if (isDirectRunUrl(process.argv[1], import.meta.url)) {
+  const [command] = process.argv.slice(2);
+  if (command === "sync") {
+    await syncAndroidAppI18n();
+  } else if (command === "check") {
+    await checkAndroidAppI18n();
+  } else {
+    throw new Error("usage: node --import tsx scripts/android-app-i18n.ts <sync|check>");
+  }
+}

scripts/android-native-ci.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { readFileSync, realpathSync } from "node:fs";
+import { validateReleaseChildRunProvenance } from "./full-release-validation-policy.mjs";
+import { isDirectRunUrl } from "./lib/direct-run.mjs";
+import { isRecord } from "./lib/record-shared.mjs";
+import { runReleaseToolingGh } from "./release-tooling-identity.mjs";
+
+export function verifyAndroidNativeCi(approval, { runGh = runReleaseToolingGh } = {}) {
+  // Stable v2026.8.2's tag-owned publisher consumes v2 approvals from full FRV.
+  // The npm-only policy requires v3 so its separate native proof survives dispatch.
+  if (approval.version === 2 && approval.nativeCi === undefined) {
+    return;
+  }
+  const nativeCi = approval.nativeCi;
+  if (
+    approval.version !== 3 ||
+    !isRecord(nativeCi) ||
+    Object.keys(nativeCi).length !== 3 ||
+    typeof nativeCi.runId !== "string" ||
+    !/^[1-9][0-9]*$/u.test(nativeCi.runId) ||
+    nativeCi.runAttempt !== 1 ||
+    typeof nativeCi.workflowRef !== "string" ||
+    nativeCi.workflowRef.length === 0
+  ) {
+    throw new Error("Android approval requires an exact native CI qualification tuple.");
+  }
+  const run = JSON.parse(
+    runGh([
+      "api",
+      `repos/${approval.repository}/actions/runs/${nativeCi.runId}`,
+      "--method",
+      "GET",
+    ]),
+  );
+  const proof = validateReleaseChildRunProvenance(run, {
+    key: "nativeAndroid",
+    plannedRunAttempt: nativeCi.runAttempt,
+    repository: approval.repository,
+    runId: nativeCi.runId,
+    workflow: "ci.yml",
+    displayTitle: `CI release-native-android-${approval.parentRunId}-${approval.parentRunAttempt}-${approval.targetSha}`,
+    workflowRef: nativeCi.workflowRef,
+    workflowSha: approval.parentWorkflowSha,
+  });
+  if (
+    proof.effectiveRunAttempt !== nativeCi.runAttempt ||
+    run.status !== "completed" ||
+    run.conclusion !== "success"
+  ) {
+    throw new Error("Android approval requires the exact completed successful native CI attempt.");
+  }
+}
+
+// Isolated release harnesses can invoke the verifier through a scripts symlink.
+if (process.argv[1] && isDirectRunUrl(realpathSync(process.argv[1]), import.meta.url)) {
+  verifyAndroidNativeCi(JSON.parse(readFileSync(process.argv[2], "utf8")));
+}

scripts/android-pin-version.ts

@@ -0,0 +1,25 @@
+// Android pinning is retired; the shared mobile cutter owns release metadata.
+import { isDirectRunUrl } from "./lib/direct-run.mjs";
+
+const RETIRED_MESSAGE =
+  "Android version pinning is retired. Run the shared mobile cutter in scripts/mobile-release-version.ts.";
+
+function printUsage(): void {
+  process.stdout.write(`${RETIRED_MESSAGE}\n`);
+}
+
+export async function main(argv: string[]): Promise<number> {
+  if (argv.includes("-h") || argv.includes("--help")) {
+    printUsage();
+    return 0;
+  }
+  process.stderr.write(`${RETIRED_MESSAGE}\n`);
+  return 1;
+}
+
+if (isDirectRunUrl(process.argv[1], import.meta.url)) {
+  const exitCode = await main(process.argv.slice(2));
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}

scripts/android-screenshots.sh

@@ -0,0 +1,770 @@
+#!/usr/bin/env bash
+# Bash 5.3+ can deadlock writing heredoc pipes on macOS before the reader starts.
+if [[ ${OSTYPE:-} == darwin* && $BASH != /bin/bash ]] && ((BASH_VERSINFO[0] > 5 || (BASH_VERSINFO[0] == 5 && BASH_VERSINFO[1] >= 3))); then
+  exec /bin/bash "$0" "$@"
+fi
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  scripts/android-screenshots.sh [--form-factor all|phone|wear] [--device <adb-serial>] [--avd <name>] [--locale en-US] [--skip-build] [--skip-install] [--keep-emulator] [--dry-run]
+
+Builds and installs the phone and Wear OS debug apps on matching emulators,
+launches production screens with deterministic local fixture state, and writes
+Google Play screenshots under:
+  apps/android/fastlane/metadata/android/<locale>/images/phoneScreenshots/
+  apps/android/fastlane/metadata/android/<locale>/images/wearScreenshots/
+
+Capture evidence is saved under:
+  .artifacts/android-screenshots/latest/
+
+By default, the script captures both form factors using retained Pixel 2 and
+Wear OS Large Round AVDs. Use --form-factor with --avd or --device to capture
+one form factor on an explicitly selected emulator.
+EOF
+}
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ANDROID_DIR="${ROOT_DIR}/apps/android"
+DEFAULT_SCREENSHOT_AVD="OpenClaw_Screenshots_API36"
+DEFAULT_SCREENSHOT_DEVICE_PROFILE="pixel_2"
+DEFAULT_WEAR_SCREENSHOT_AVD="OpenClaw_Wear_Screenshots_API34"
+DEFAULT_WEAR_SCREENSHOT_DEVICE_PROFILE="wearos_large_round"
+case "$(uname -m)" in
+  arm64|aarch64) DEFAULT_SCREENSHOT_ABI="arm64-v8a" ;;
+  *) DEFAULT_SCREENSHOT_ABI="x86_64" ;;
+esac
+DEFAULT_SCREENSHOT_SYSTEM_IMAGE="system-images;android-36;google_apis;${DEFAULT_SCREENSHOT_ABI}"
+DEFAULT_WEAR_SCREENSHOT_SYSTEM_IMAGE="system-images;android-34;android-wear;${DEFAULT_SCREENSHOT_ABI}"
+FORM_FACTOR="${ANDROID_SCREENSHOT_FORM_FACTOR:-all}"
+LOCALE="en-US"
+DEVICE="${ANDROID_SCREENSHOT_DEVICE:-}"
+AVD="${ANDROID_SCREENSHOT_AVD:-$DEFAULT_SCREENSHOT_AVD}"
+SCREENSHOT_DEVICE_PROFILE="${ANDROID_SCREENSHOT_DEVICE_PROFILE:-$DEFAULT_SCREENSHOT_DEVICE_PROFILE}"
+SCREENSHOT_SYSTEM_IMAGE="${ANDROID_SCREENSHOT_SYSTEM_IMAGE:-$DEFAULT_SCREENSHOT_SYSTEM_IMAGE}"
+KEEP_EMULATOR="${ANDROID_SCREENSHOT_KEEP_EMULATOR:-0}"
+SKIP_BUILD=0
+SKIP_INSTALL=0
+DRY_RUN=0
+SCENES=(home chat settings gateway voice-wake)
+OUTPUT_TYPE="phoneScreenshots"
+GRADLE_ASSEMBLE_TASK=":app:assemblePlayDebug"
+APP_PACKAGE="ai.openclaw.app.debug"
+ACTIVITY_COMPONENT="$APP_PACKAGE/ai.openclaw.app.MainActivity"
+EMULATOR_PID=""
+EMULATOR_LOG=""
+STARTED_EMULATOR=0
+ARTIFACT_ROOT="${ROOT_DIR}/.artifacts/android-screenshots/latest"
+ARTIFACT_DIR="${ARTIFACT_ROOT}/phone"
+SCREENSHOT_SIZE="${ANDROID_SCREENSHOT_SIZE:-1440x2560}"
+DISPLAY_OVERRIDDEN=0
+ORIGINAL_WM_SIZE=""
+ORIGINAL_WM_DENSITY=""
+SCREENSHOT_DENSITY=""
+TIMEZONE_OVERRIDDEN=0
+ORIGINAL_AUTO_TIME_ZONE=""
+ORIGINAL_TIME_ZONE=""
+DEVICE_EXPLICIT=0
+AVD_EXPLICIT=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --)
+      shift
+      ;;
+    --form-factor)
+      FORM_FACTOR="${2:-}"
+      shift 2
+      ;;
+    --device)
+      DEVICE="${2:-}"
+      DEVICE_EXPLICIT=1
+      shift 2
+      ;;
+    --avd)
+      AVD="${2:-}"
+      AVD_EXPLICIT=1
+      shift 2
+      ;;
+    --locale)
+      LOCALE="${2:-}"
+      shift 2
+      ;;
+    --skip-build)
+      SKIP_BUILD=1
+      shift
+      ;;
+    --skip-install)
+      SKIP_INSTALL=1
+      shift
+      ;;
+    --keep-emulator)
+      KEEP_EMULATOR=1
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+case "$FORM_FACTOR" in
+  all)
+    if [[ "$DEVICE_EXPLICIT" == "1" || "$AVD_EXPLICIT" == "1" ]]; then
+      echo "--device and --avd require --form-factor phone or --form-factor wear." >&2
+      exit 1
+    fi
+    if [[ "$KEEP_EMULATOR" == "1" ]]; then
+      echo "--keep-emulator requires --form-factor phone or --form-factor wear." >&2
+      exit 1
+    fi
+    child_args=(--locale "$LOCALE")
+    [[ "$SKIP_BUILD" == "1" ]] && child_args+=(--skip-build)
+    [[ "$SKIP_INSTALL" == "1" ]] && child_args+=(--skip-install)
+    [[ "$DRY_RUN" == "1" ]] && child_args+=(--dry-run)
+    bash "$0" --form-factor phone "${child_args[@]}"
+    bash "$0" --form-factor wear "${child_args[@]}"
+    exit 0
+    ;;
+  phone)
+    ;;
+  wear)
+    if [[ "$DEVICE_EXPLICIT" != "1" ]]; then
+      DEVICE="${ANDROID_WEAR_SCREENSHOT_DEVICE:-}"
+    fi
+    if [[ "$AVD_EXPLICIT" != "1" ]]; then
+      AVD="${ANDROID_WEAR_SCREENSHOT_AVD:-$DEFAULT_WEAR_SCREENSHOT_AVD}"
+    fi
+    SCREENSHOT_DEVICE_PROFILE="${ANDROID_WEAR_SCREENSHOT_DEVICE_PROFILE:-$DEFAULT_WEAR_SCREENSHOT_DEVICE_PROFILE}"
+    SCREENSHOT_SYSTEM_IMAGE="${ANDROID_WEAR_SCREENSHOT_SYSTEM_IMAGE:-$DEFAULT_WEAR_SCREENSHOT_SYSTEM_IMAGE}"
+    SCREENSHOT_SIZE="${ANDROID_WEAR_SCREENSHOT_SIZE:-454x454}"
+    SCENES=(chat voice controls)
+    OUTPUT_TYPE="wearScreenshots"
+    GRADLE_ASSEMBLE_TASK=":wear:assembleDebug"
+    ACTIVITY_COMPONENT="$APP_PACKAGE/ai.openclaw.wear.MainActivity"
+    ARTIFACT_DIR="${ARTIFACT_ROOT}/wear"
+    ;;
+  *)
+    echo "Invalid Android screenshot form factor: ${FORM_FACTOR}" >&2
+    echo "Use all, phone, or wear." >&2
+    exit 1
+    ;;
+esac
+
+validate_locale() {
+  local locale="$1"
+  if [[ "$locale" =~ ^[A-Za-z0-9][A-Za-z0-9_-]*$ ]]; then
+    return
+  fi
+  echo "Invalid Android screenshot locale: ${locale}" >&2
+  echo "Use a locale tag like en-US or pt-BR; path separators and dot segments are not allowed." >&2
+  exit 1
+}
+
+validate_locale "$LOCALE"
+
+if [[ ! "$SCREENSHOT_SIZE" =~ ^[0-9]+x[0-9]+$ ]]; then
+  echo "Invalid Android screenshot size: ${SCREENSHOT_SIZE}" >&2
+  echo "Use a pixel size like 1080x1920." >&2
+  exit 1
+fi
+SCREENSHOT_WIDTH=$((10#${SCREENSHOT_SIZE%x*}))
+SCREENSHOT_HEIGHT=$((10#${SCREENSHOT_SIZE#*x}))
+SCREENSHOT_MIN_DIMENSION=$((SCREENSHOT_WIDTH < SCREENSHOT_HEIGHT ? SCREENSHOT_WIDTH : SCREENSHOT_HEIGHT))
+SCREENSHOT_MAX_DIMENSION=$((SCREENSHOT_WIDTH > SCREENSHOT_HEIGHT ? SCREENSHOT_WIDTH : SCREENSHOT_HEIGHT))
+if (( SCREENSHOT_MIN_DIMENSION < 320 || SCREENSHOT_MAX_DIMENSION > 3840 || SCREENSHOT_MAX_DIMENSION > SCREENSHOT_MIN_DIMENSION * 2 )); then
+  echo "Android screenshot size ${SCREENSHOT_SIZE} does not meet Google Play dimension and aspect-ratio limits." >&2
+  exit 1
+fi
+
+cleanup_started_emulator() {
+  local stopped=0
+
+  if [[ "$STARTED_EMULATOR" != "1" || "$KEEP_EMULATOR" == "1" ]]; then
+    return
+  fi
+  if [[ -n "${ADB_BIN:-}" && -n "${ADB_SERIAL:-}" ]]; then
+    if "$ADB_BIN" -s "$ADB_SERIAL" emu kill >/dev/null 2>&1; then
+      stopped=1
+      local deadline=$((SECONDS + 30))
+      while (( SECONDS < deadline )); do
+        if ! "$ADB_BIN" devices | awk 'NR > 1 && $2 == "device" { print $1 }' | grep -Fxq "$ADB_SERIAL"; then
+          break
+        fi
+        sleep 1
+      done
+    fi
+  fi
+  if [[ "$stopped" != "1" && -n "$EMULATOR_PID" ]]; then
+    kill "$EMULATOR_PID" >/dev/null 2>&1 || true
+  fi
+}
+
+restore_device_display() {
+  if [[ "$DISPLAY_OVERRIDDEN" != "1" || -z "${ADB_BIN:-}" || -z "${ADB_SERIAL:-}" ]]; then
+    return
+  fi
+  if [[ -n "$ORIGINAL_WM_SIZE" ]]; then
+    "$ADB_BIN" -s "$ADB_SERIAL" shell wm size "$ORIGINAL_WM_SIZE" >/dev/null 2>&1 || true
+  else
+    "$ADB_BIN" -s "$ADB_SERIAL" shell wm size reset >/dev/null 2>&1 || true
+  fi
+  if [[ -n "$ORIGINAL_WM_DENSITY" ]]; then
+    "$ADB_BIN" -s "$ADB_SERIAL" shell wm density "$ORIGINAL_WM_DENSITY" >/dev/null 2>&1 || true
+  else
+    "$ADB_BIN" -s "$ADB_SERIAL" shell wm density reset >/dev/null 2>&1 || true
+  fi
+}
+
+restore_device_timezone() {
+  if [[ "$TIMEZONE_OVERRIDDEN" != "1" || -z "${ADB_BIN:-}" || -z "${ADB_SERIAL:-}" ]]; then
+    return
+  fi
+  if [[ -n "$ORIGINAL_TIME_ZONE" ]]; then
+    "$ADB_BIN" -s "$ADB_SERIAL" shell cmd alarm set-timezone "$ORIGINAL_TIME_ZONE" >/dev/null 2>&1 || true
+  fi
+  if [[ "$ORIGINAL_AUTO_TIME_ZONE" == "true" || "$ORIGINAL_AUTO_TIME_ZONE" == "false" ]]; then
+    "$ADB_BIN" -s "$ADB_SERIAL" shell cmd time_zone_detector set_auto_detection_enabled "$ORIGINAL_AUTO_TIME_ZONE" >/dev/null 2>&1 || true
+  fi
+}
+
+cleanup_emulator_log() {
+  if [[ -n "$EMULATOR_LOG" && -f "$EMULATOR_LOG" ]]; then
+    rm -f "$EMULATOR_LOG"
+  fi
+}
+
+cleanup() {
+  restore_device_display
+  restore_device_timezone
+  cleanup_started_emulator
+  cleanup_emulator_log
+}
+
+trap cleanup EXIT
+
+adb_bin() {
+  if [[ -n "${ADB:-}" ]]; then
+    printf '%s\n' "$ADB"
+    return
+  fi
+  if command -v adb >/dev/null 2>&1; then
+    command -v adb
+    return
+  fi
+  for sdk_root in "${ANDROID_HOME:-}" "${ANDROID_SDK_ROOT:-}" "$HOME/Library/Android/sdk"; do
+    if [[ -n "$sdk_root" && -x "$sdk_root/platform-tools/adb" ]]; then
+      printf '%s\n' "$sdk_root/platform-tools/adb"
+      return
+    fi
+  done
+  echo "adb not found. Install Android platform-tools or set ADB." >&2
+  return 127
+}
+
+emulator_bin() {
+  if [[ -n "${ANDROID_EMULATOR:-}" ]]; then
+    printf '%s\n' "$ANDROID_EMULATOR"
+    return
+  fi
+  if command -v emulator >/dev/null 2>&1; then
+    command -v emulator
+    return
+  fi
+  for sdk_root in "${ANDROID_HOME:-}" "${ANDROID_SDK_ROOT:-}" "$HOME/Library/Android/sdk"; do
+    if [[ -n "$sdk_root" && -x "$sdk_root/emulator/emulator" ]]; then
+      printf '%s\n' "$sdk_root/emulator/emulator"
+      return
+    fi
+  done
+  echo "Android emulator binary not found. Install the Android emulator or set ANDROID_EMULATOR." >&2
+  return 127
+}
+
+avdmanager_bin() {
+  if [[ -n "${AVDMANAGER:-}" ]]; then
+    printf '%s\n' "$AVDMANAGER"
+    return
+  fi
+  for sdk_root in "${ANDROID_HOME:-}" "${ANDROID_SDK_ROOT:-}" "$HOME/Library/Android/sdk"; do
+    for relative_path in cmdline-tools/latest/bin/avdmanager cmdline-tools/bin/avdmanager tools/bin/avdmanager; do
+      if [[ -n "$sdk_root" && -x "$sdk_root/$relative_path" ]]; then
+        printf '%s\n' "$sdk_root/$relative_path"
+        return
+      fi
+    done
+  done
+  if command -v avdmanager >/dev/null 2>&1; then
+    command -v avdmanager
+    return
+  fi
+  echo "avdmanager not found. Install Android SDK command-line tools or set AVDMANAGER." >&2
+  return 127
+}
+
+ensure_screenshot_avd() {
+  local avd="$1"
+  local emulator
+  local avdmanager
+
+  emulator="$(emulator_bin)"
+  if "$emulator" -list-avds | grep -Fxq "$avd"; then
+    return
+  fi
+
+  avdmanager="$(avdmanager_bin)"
+  echo "Creating no-cutout screenshot AVD '${avd}' from device profile '${SCREENSHOT_DEVICE_PROFILE}'." >&2
+  if ! printf 'no\n' | "$avdmanager" create avd \
+    --force \
+    --name "$avd" \
+    --package "$SCREENSHOT_SYSTEM_IMAGE" \
+    --device "$SCREENSHOT_DEVICE_PROFILE"; then
+    echo "Could not create Android screenshot AVD '${avd}'." >&2
+    echo "Install SDK package '${SCREENSHOT_SYSTEM_IMAGE}' or set ANDROID_SCREENSHOT_SYSTEM_IMAGE." >&2
+    return 1
+  fi
+}
+
+connected_devices() {
+  local adb="$1"
+  "$adb" devices | awk 'NR > 1 && $2 == "device" { print $1 }'
+}
+
+device_count() {
+  local devices="$1"
+  printf '%s\n' "$devices" | sed '/^$/d' | wc -l | tr -d ' '
+}
+
+running_avd_name() {
+  local adb="$1"
+  local serial="$2"
+  "$adb" -s "$serial" emu avd name 2>/dev/null | tr -d '\r' | sed -n '1p'
+}
+
+wait_for_single_device() {
+  local adb="$1"
+  local timeout_seconds="${ANDROID_SCREENSHOT_EMULATOR_TIMEOUT_SECONDS:-180}"
+  local deadline=$((SECONDS + timeout_seconds))
+  local devices
+  local count
+
+  while (( SECONDS < deadline )); do
+    devices="$(connected_devices "$adb")"
+    count="$(device_count "$devices")"
+    if [[ "$count" == "1" ]]; then
+      printf '%s\n' "$devices"
+      return
+    fi
+    sleep 2
+  done
+
+  echo "Timed out waiting for exactly one Android emulator device." >&2
+  "$adb" devices -l >&2 || true
+  return 1
+}
+
+wait_for_boot_completed() {
+  local adb="$1"
+  local serial="$2"
+  local timeout_seconds="${ANDROID_SCREENSHOT_EMULATOR_TIMEOUT_SECONDS:-180}"
+  local deadline=$((SECONDS + timeout_seconds))
+  local boot_completed
+
+  "$adb" -s "$serial" wait-for-device
+  while (( SECONDS < deadline )); do
+    boot_completed="$("$adb" -s "$serial" shell getprop sys.boot_completed 2>/dev/null | tr -d '\r' || true)"
+    if [[ "$boot_completed" == "1" ]]; then
+      "$adb" -s "$serial" shell input keyevent 82 >/dev/null 2>&1 || true
+      return
+    fi
+    sleep 2
+  done
+
+  echo "Timed out waiting for Android emulator boot completion on ${serial}." >&2
+  return 1
+}
+
+wait_for_explicit_device() {
+  local adb="$1"
+  local serial="$2"
+  local timeout_seconds="${ANDROID_SCREENSHOT_DEVICE_TIMEOUT_SECONDS:-30}"
+  local deadline=$((SECONDS + timeout_seconds))
+  local state
+
+  while (( SECONDS < deadline )); do
+    state="$("$adb" devices | awk -v serial="$serial" '$1 == serial { print $2 }')"
+    if [[ "$state" == "device" ]]; then
+      return
+    fi
+    sleep 2
+  done
+
+  if [[ -n "$state" ]]; then
+    echo "Android device '${serial}' did not become usable within ${timeout_seconds}s; current adb state is '${state}'." >&2
+  else
+    echo "Android device '${serial}' was not found within ${timeout_seconds}s." >&2
+  fi
+  "$adb" devices -l >&2 || true
+  return 1
+}
+
+stabilize_device_for_screenshots() {
+  local adb="$1"
+  local serial="$2"
+  ORIGINAL_AUTO_TIME_ZONE="$("$adb" -s "$serial" shell cmd time_zone_detector is_auto_detection_enabled 2>/dev/null | tr -d '\r')"
+  ORIGINAL_TIME_ZONE="$("$adb" -s "$serial" shell getprop persist.sys.timezone 2>/dev/null | tr -d '\r')"
+  if [[ "$ORIGINAL_AUTO_TIME_ZONE" != "true" && "$ORIGINAL_AUTO_TIME_ZONE" != "false" ]]; then
+    echo "Could not determine emulator automatic timezone setting." >&2
+    return 1
+  fi
+  if [[ -z "$ORIGINAL_TIME_ZONE" ]]; then
+    echo "Could not determine emulator timezone." >&2
+    return 1
+  fi
+  # Arm cleanup before the first mutation; restoring an unchanged snapshot is safe.
+  TIMEZONE_OVERRIDDEN=1
+  # Seeded chat timestamps use the device timezone, so disable detection before
+  # pinning UTC to avoid inheriting the runner's locale.
+  "$adb" -s "$serial" shell cmd time_zone_detector set_auto_detection_enabled false >/dev/null
+  "$adb" -s "$serial" shell cmd alarm set-timezone UTC >/dev/null
+  "$adb" -s "$serial" shell settings put global window_animation_scale 0 >/dev/null 2>&1 || true
+  "$adb" -s "$serial" shell settings put global transition_animation_scale 0 >/dev/null 2>&1 || true
+  "$adb" -s "$serial" shell settings put global animator_duration_scale 0 >/dev/null 2>&1 || true
+  "$adb" -s "$serial" shell settings put global stay_on_while_plugged_in 3 >/dev/null 2>&1 || true
+  "$adb" -s "$serial" shell svc power stayon true >/dev/null 2>&1 || true
+  "$adb" -s "$serial" shell input keyevent 224 >/dev/null 2>&1 || true
+  "$adb" -s "$serial" shell wm dismiss-keyguard >/dev/null 2>&1 || true
+  "$adb" -s "$serial" shell settings put system font_scale 1.0 >/dev/null 2>&1 || true
+}
+
+require_emulator_device() {
+  local adb="$1"
+  local serial="$2"
+  local qemu
+
+  qemu="$("$adb" -s "$serial" shell getprop ro.kernel.qemu 2>/dev/null | tr -d '\r')"
+  if [[ "$qemu" == "1" ]]; then
+    return
+  fi
+  echo "Android screenshot capture requires an emulator; '${serial}' is not an emulator." >&2
+  echo "Pass --avd <name> or --device <emulator-serial>." >&2
+  return 1
+}
+
+configure_screenshot_display() {
+  local adb="$1"
+  local serial="$2"
+  local current_size
+  local current_density
+  local effective_size
+  local effective_density
+  local effective_width
+
+  current_size="$("$adb" -s "$serial" shell wm size 2>/dev/null | tr -d '\r')"
+  current_density="$("$adb" -s "$serial" shell wm density 2>/dev/null | tr -d '\r')"
+  ORIGINAL_WM_SIZE="$(printf '%s\n' "$current_size" | sed -n 's/^Override size: //p')"
+  ORIGINAL_WM_DENSITY="$(printf '%s\n' "$current_density" | sed -n 's/^Override density: //p')"
+  effective_size="${ORIGINAL_WM_SIZE:-$(printf '%s\n' "$current_size" | sed -n 's/^Physical size: //p')}"
+  effective_density="${ORIGINAL_WM_DENSITY:-$(printf '%s\n' "$current_density" | sed -n 's/^Physical density: //p')}"
+  if [[ ! "$effective_size" =~ ^[0-9]+x[0-9]+$ || ! "$effective_density" =~ ^[0-9]+$ ]]; then
+    echo "Could not determine emulator display size and density." >&2
+    return 1
+  fi
+
+  effective_width=$((10#${effective_size%x*}))
+  SCREENSHOT_DENSITY=$(((10#$effective_density * SCREENSHOT_WIDTH + effective_width / 2) / effective_width))
+  DISPLAY_OVERRIDDEN=1
+  "$adb" -s "$serial" shell wm size "$SCREENSHOT_SIZE" >/dev/null
+  "$adb" -s "$serial" shell wm density "$SCREENSHOT_DENSITY" >/dev/null
+  echo "Android screenshot density: ${SCREENSHOT_DENSITY} dpi"
+}
+
+boot_emulator() {
+  local adb="$1"
+  local avd="$2"
+  local emulator
+  local emulator_args
+  local extra_args
+  local serial
+
+  ensure_screenshot_avd "$avd"
+  emulator="$(emulator_bin)"
+  EMULATOR_LOG="$(mktemp "${TMPDIR:-/tmp}/openclaw-android-screenshot-emulator.XXXXXX.log")"
+  echo "No connected Android device found. Booting AVD '${avd}'." >&2
+  emulator_args=(-avd "$avd" -no-window -no-audio -no-boot-anim)
+  if [[ -n "${ANDROID_SCREENSHOT_EMULATOR_ARGS:-}" ]]; then
+    read -r -a extra_args <<<"$ANDROID_SCREENSHOT_EMULATOR_ARGS"
+    emulator_args+=(${extra_args[@]+"${extra_args[@]}"})
+  fi
+  "$emulator" "${emulator_args[@]}" >"$EMULATOR_LOG" 2>&1 &
+  EMULATOR_PID="$!"
+  STARTED_EMULATOR=1
+
+  serial="$(wait_for_single_device "$adb")"
+  wait_for_boot_completed "$adb" "$serial"
+  ADB_SERIAL="$serial"
+}
+
+resolve_device() {
+  local adb="$1"
+  local devices
+  local count
+  local connected_avd
+
+  if [[ -n "$DEVICE" ]]; then
+    wait_for_explicit_device "$adb" "$DEVICE"
+    ADB_SERIAL="$DEVICE"
+    return
+  fi
+  devices="$(connected_devices "$adb")"
+  count="$(device_count "$devices")"
+  if [[ "$count" == "1" ]]; then
+    if connected_avd="$(running_avd_name "$adb" "$devices")"; then
+      if [[ "$connected_avd" != "$AVD" ]]; then
+        echo "Connected emulator '${connected_avd:-unknown}' is not the screenshot AVD '${AVD}'." >&2
+        echo "Stop it so the script can boot '${AVD}', or pass --device '${devices}' to override the no-cutout profile." >&2
+        return 1
+      fi
+    fi
+    ADB_SERIAL="$devices"
+    return
+  fi
+  if [[ "$count" == "0" ]]; then
+    boot_emulator "$adb" "$AVD"
+    return
+  else
+    echo "Multiple Android devices are connected. Pass --device <adb-serial>." >&2
+  fi
+  return 1
+}
+
+latest_debug_apk() {
+  local output_dir
+  local pattern
+
+  if [[ "$FORM_FACTOR" == "wear" ]]; then
+    output_dir="${ANDROID_DIR}/wear/build/outputs/apk/debug"
+    pattern='*-debug.apk'
+  else
+    output_dir="${ANDROID_DIR}/app/build/outputs/apk/play/debug"
+    pattern='*-play-debug.apk'
+  fi
+  if [[ ! -d "$output_dir" ]]; then
+    return 0
+  fi
+  find "$output_dir" -maxdepth 1 -name "$pattern" -print 2>/dev/null | sort | tail -n 1
+}
+
+scene_ready_text() {
+  if [[ "$FORM_FACTOR" == "wear" ]]; then
+    case "$1" in
+      chat) printf '%s\n' "Release planning" ;;
+      voice) printf '%s\n' "Dictate" ;;
+      controls) printf '%s\n' "Gateway connected" ;;
+      *)
+        echo "Unknown Wear OS screenshot scene: $1" >&2
+        return 1
+        ;;
+    esac
+    return
+  fi
+  case "$1" in
+    home) printf '%s\n' "Overview" ;;
+    # The screenshot fixture seeds chat history and restores at the live edge,
+    # so wait for the latest reply instead of empty-chat copy.
+    chat) printf '%s\n' "The Android release is close." ;;
+    settings) printf '%s\n' "OpenClaw mobile" ;;
+    voice-wake) printf '%s\n' "Wake listener" ;;
+    # Connected fixtures can push Add Gateway below the composed viewport, so
+    # wait for the gateway detail's always-visible subtitle instead.
+    gateway) printf '%s\n' "Connection between this phone and OpenClaw." ;;
+    *)
+      echo "Unknown Android screenshot scene: $1" >&2
+      return 1
+      ;;
+  esac
+}
+
+wait_for_scene_ready() {
+  local adb="$1"
+  local serial="$2"
+  local scene="$3"
+  local dump_path="$4"
+  local marker
+  local timeout_seconds="${ANDROID_SCREENSHOT_SCENE_TIMEOUT_SECONDS:-45}"
+  local deadline=$((SECONDS + timeout_seconds))
+
+  marker="$(scene_ready_text "$scene")"
+  while (( SECONDS < deadline )); do
+    if "$adb" -s "$serial" exec-out uiautomator dump /dev/tty >"$dump_path" 2>/dev/null; then
+      # A newly created Wear AVD may cover the resumed app with its charging
+      # overlay after stay-awake is enabled. Dismiss it or first-run capture stalls.
+      if [[ "$FORM_FACTOR" == "wear" ]] && grep -Fq 'com.google.android.wearable.sysui:id/charging_container' "$dump_path"; then
+        "$adb" -s "$serial" shell input keyevent 4 >/dev/null 2>&1 || true
+        sleep 0.5
+        continue
+      fi
+      if grep -Fq "$marker" "$dump_path"; then
+        return
+      fi
+    fi
+    sleep 1
+  done
+
+  echo "Timed out waiting for scene '${scene}' to expose '${marker}' in the Android UI tree." >&2
+  return 1
+}
+
+sips_bin() {
+  if [[ -n "${SIPS:-}" ]]; then
+    printf '%s\n' "$SIPS"
+    return
+  fi
+  if command -v sips >/dev/null 2>&1; then
+    command -v sips
+    return
+  fi
+  echo "sips not found. Android release screenshots require macOS or an explicit SIPS executable." >&2
+  return 127
+}
+
+normalize_capture_for_play() {
+  local input_path="$1"
+  local output_path="$2"
+  local sips
+  local description
+
+  sips="$(sips_bin)"
+  "$sips" -s format jpeg -s formatOptions best "$input_path" --out "$output_path" >/dev/null
+  rm -f "$input_path"
+
+  description="$(file "$output_path")"
+  if [[ "$description" != *"${SCREENSHOT_SIZE/x/x}"* || "$description" != *"JPEG image data"* ]]; then
+    echo "Invalid Google Play screenshot output: ${description}" >&2
+    return 1
+  fi
+}
+
+write_artifact_manifest() {
+  local serial="$1"
+  local avd_name
+  local git_sha
+  local checksum_command
+
+  avd_name="$(running_avd_name "$ADB_BIN" "$serial")"
+  git_sha="$(git -C "$ROOT_DIR" rev-parse HEAD)"
+  if command -v shasum >/dev/null 2>&1; then
+    checksum_command=(shasum -a 256)
+  else
+    checksum_command=(sha256sum)
+  fi
+
+  {
+    printf 'git_sha=%s\n' "$git_sha"
+    printf 'form_factor=%s\n' "$FORM_FACTOR"
+    printf 'output_type=%s\n' "$OUTPUT_TYPE"
+    printf 'device=%s\n' "$serial"
+    printf 'avd=%s\n' "${avd_name:-unknown}"
+    printf 'locale=%s\n' "$LOCALE"
+    printf 'size=%s\n' "$SCREENSHOT_SIZE"
+    printf 'density=%s\n' "$SCREENSHOT_DENSITY"
+    printf 'format=high-quality JPEG\n'
+    printf 'scenes=%s\n' "${SCENES[*]}"
+    printf 'screenshots:\n'
+    "${checksum_command[@]}" "$ARTIFACT_DIR"/screenshots/*.jpg
+  } >"$ARTIFACT_DIR/manifest.txt"
+}
+
+OUTPUT_DIR="${ANDROID_DIR}/fastlane/metadata/android/${LOCALE}/images/${OUTPUT_TYPE}"
+ADB_SERIAL=""
+ADB_DISPLAY="${DEVICE:-<auto>}"
+
+echo "Android screenshot output: ${OUTPUT_DIR}"
+echo "Android screenshot artifacts: ${ARTIFACT_DIR}"
+echo "Android screenshot form factor: ${FORM_FACTOR}"
+echo "Android screenshot size: ${SCREENSHOT_SIZE}"
+echo "Scenes: ${SCENES[*]}"
+echo "ADB device: ${ADB_DISPLAY}"
+echo "Screenshot AVD: ${AVD}"
+echo "Screenshot device profile: ${SCREENSHOT_DEVICE_PROFILE}"
+echo "Screenshot system image: ${SCREENSHOT_SYSTEM_IMAGE}"
+
+if [[ "$DRY_RUN" == "1" ]]; then
+  echo "Dry run complete. No build, install, or capture commands were executed."
+  exit 0
+fi
+
+ADB_BIN="$(adb_bin)"
+resolve_device "$ADB_BIN"
+require_emulator_device "$ADB_BIN" "$ADB_SERIAL"
+stabilize_device_for_screenshots "$ADB_BIN" "$ADB_SERIAL"
+configure_screenshot_display "$ADB_BIN" "$ADB_SERIAL"
+mkdir -p "$OUTPUT_DIR"
+rm -f "$OUTPUT_DIR"/*.png "$OUTPUT_DIR"/*.jpg "$OUTPUT_DIR"/*.jpeg
+rm -rf "$ARTIFACT_DIR"
+mkdir -p "$ARTIFACT_DIR/screenshots" "$ARTIFACT_DIR/ui-dumps" "$ARTIFACT_DIR/activity-start"
+
+if [[ "$SKIP_INSTALL" != "1" ]]; then
+  if [[ "$SKIP_BUILD" != "1" ]]; then
+    (
+      cd "$ANDROID_DIR"
+      ./gradlew "$GRADLE_ASSEMBLE_TASK"
+    )
+  fi
+  APK_PATH="$(latest_debug_apk)"
+  if [[ -z "$APK_PATH" ]]; then
+    echo "No existing ${FORM_FACTOR} debug APK found. Run without --skip-build first." >&2
+    exit 1
+  fi
+  "$ADB_BIN" -s "$ADB_SERIAL" install -r "$APK_PATH" >/dev/null
+elif [[ "$SKIP_BUILD" != "1" ]]; then
+  (
+    cd "$ANDROID_DIR"
+    ./gradlew "$GRADLE_ASSEMBLE_TASK"
+  )
+fi
+
+"$ADB_BIN" -s "$ADB_SERIAL" shell pm clear "$APP_PACKAGE" >/dev/null
+"$ADB_BIN" -s "$ADB_SERIAL" shell pm grant "$APP_PACKAGE" android.permission.RECORD_AUDIO >/dev/null
+"$ADB_BIN" -s "$ADB_SERIAL" logcat -c >/dev/null 2>&1 || true
+
+for scene in "${SCENES[@]}"; do
+  output_path="${OUTPUT_DIR}/openclaw-${scene}.jpg"
+  raw_path="${OUTPUT_DIR}/openclaw-${scene}.raw.png"
+  artifact_path="${ARTIFACT_DIR}/screenshots/openclaw-${scene}.jpg"
+  ui_dump_path="${ARTIFACT_DIR}/ui-dumps/openclaw-${scene}.xml"
+  activity_start_path="${ARTIFACT_DIR}/activity-start/openclaw-${scene}.txt"
+  "$ADB_BIN" -s "$ADB_SERIAL" shell am force-stop "$APP_PACKAGE" >/dev/null
+  "$ADB_BIN" -s "$ADB_SERIAL" shell input keyevent 224 >/dev/null 2>&1 || true
+  "$ADB_BIN" -s "$ADB_SERIAL" shell wm dismiss-keyguard >/dev/null 2>&1 || true
+  "$ADB_BIN" -s "$ADB_SERIAL" shell am start -W \
+    -n "$ACTIVITY_COMPONENT" \
+    --ez openclaw.screenshotMode true \
+    --es openclaw.screenshotScene "$scene" >"$activity_start_path"
+  wait_for_scene_ready "$ADB_BIN" "$ADB_SERIAL" "$scene" "$ui_dump_path"
+  sleep "${ANDROID_SCREENSHOT_SETTLE_SECONDS:-0.5}"
+  "$ADB_BIN" -s "$ADB_SERIAL" exec-out screencap -p >"$raw_path"
+  normalize_capture_for_play "$raw_path" "$output_path"
+  cp "$output_path" "$artifact_path"
+  echo "Captured ${output_path}"
+done
+
+"$ADB_BIN" -s "$ADB_SERIAL" logcat -d >"$ARTIFACT_DIR/logcat.txt" 2>&1 || true
+if [[ -n "$EMULATOR_LOG" && -f "$EMULATOR_LOG" ]]; then
+  cp "$EMULATOR_LOG" "$ARTIFACT_DIR/emulator.log"
+fi
+write_artifact_manifest "$ADB_SERIAL"
+
+echo "Android screenshots written to ${OUTPUT_DIR}"
+echo "Android screenshot artifacts written to ${ARTIFACT_DIR}"

scripts/android-sips-linux.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+set -euo pipefail
+
+fail() {
+  printf 'android-sips-linux: %s\n' "$1" >&2
+  exit "${2:-1}"
+}
+
+if [[ $# -ne 9 ||
+  "$1" != "-s" || "$2" != "format" || "$3" != "jpeg" ||
+  "$4" != "-s" || "$5" != "formatOptions" || "$6" != "best" ||
+  "$8" != "--out" ]]; then
+  fail "unsupported arguments" 2
+fi
+
+input_path="$7"
+output_path="$9"
+convert_bin="/usr/bin/convert"
+identify_bin="/usr/bin/identify"
+
+[[ "$input_path" == /* && "$output_path" == /* ]] ||
+  fail "input and output paths must be absolute" 2
+[[ "$input_path" != "$output_path" ]] || fail "input and output paths must differ" 2
+[[ -f "$input_path" && ! -L "$input_path" ]] || fail "input is not a regular file"
+[[ ! -e "$output_path" && ! -L "$output_path" ]] || fail "output already exists"
+[[ -d "${output_path%/*}" ]] || fail "output directory does not exist"
+
+[[ -x "$convert_bin" && -x "$identify_bin" ]] ||
+  fail "fixed ImageMagick executables are unavailable" 2
+
+if ! input_dimensions="$("$identify_bin" -ping -format '%w %h' "$input_path" 2>/dev/null)"; then
+  fail "input is not a readable image"
+fi
+read -r input_width input_height extra <<<"$input_dimensions"
+[[ "$input_width" =~ ^[1-9][0-9]*$ && "$input_height" =~ ^[1-9][0-9]*$ && -z "${extra:-}" ]] ||
+  fail "input dimensions are invalid"
+
+umask 077
+temporary_dir="$(mktemp -d "${output_path}.tmp.XXXXXX")"
+temporary_output="$temporary_dir/output.jpg"
+cleanup() {
+  rm -rf "$temporary_dir"
+}
+trap cleanup EXIT
+
+if ! "$convert_bin" "$input_path" \
+  -colorspace sRGB \
+  -background white \
+  -alpha remove \
+  -alpha off \
+  -type TrueColor \
+  -quality 95 \
+  "jpeg:$temporary_output" >/dev/null 2>&1; then
+  fail "ImageMagick conversion failed"
+fi
+
+if ! output_description="$(
+  "$identify_bin" +ping -format '%m|%w|%h|%[colorspace]|%[type]|%[channels]|%Q' \
+    "$temporary_output" 2>/dev/null
+)"; then
+  fail "converted output is not a readable image"
+fi
+IFS='|' read -r output_format output_width output_height output_colorspace \
+  output_type output_channels output_quality <<<"$output_description"
+output_colorspace="$(printf '%s' "$output_colorspace" | tr '[:upper:]' '[:lower:]')"
+output_channels="$(printf '%s' "$output_channels" | tr '[:upper:]' '[:lower:]')"
+
+[[ "$output_format" == "JPEG" ]] || fail "converted output is not JPEG"
+[[ "$output_width" == "$input_width" && "$output_height" == "$input_height" ]] ||
+  fail "converted output dimensions changed"
+[[ "$output_colorspace" == "srgb" ]] || fail "converted output is not sRGB"
+[[ "$output_type" == "TrueColor" ]] || fail "converted output is not true color"
+[[ "$output_channels" != *a* ]] || fail "converted output retained an alpha channel"
+[[ "$output_quality" =~ ^[0-9]+$ && "$output_quality" -ge 90 ]] ||
+  fail "converted output quality is too low"
+
+mv "$temporary_output" "$output_path"

scripts/apple-app-i18n.ts

@@ -0,0 +1,984 @@
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { NATIVE_I18N_LOCALES } from "./native-i18n-locales.ts";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(HERE, "..");
+const REQUIRED_LOCALES = ["en", ...NATIVE_I18N_LOCALES];
+const FORMAT_RE = /%(?:%|(?:\d+\$)?(?:lld|ld|[@a-z]))/giu;
+const INFLECTED_COUNT_INTERPOLATION_RE = /\\\([A-Za-z_][A-Za-z0-9_]*\)/gu;
+const INFLECTED_COUNT_INTERPOLATION_EXACT_RE = /^\\\([A-Za-z_][A-Za-z0-9_]*\)$/u;
+const INFLECTED_COUNT_SEGMENT_RE =
+  /\^\[[^\]]*\\\([A-Za-z_][A-Za-z0-9_]*\)[^\]]*\]\(inflect: true\)/gu;
+const INFLECTED_COUNT_MARKER = "](inflect: true)";
+const IOS_CATALOG_PATH = "apps/ios/Resources/Localizable.xcstrings";
+const MACOS_CATALOG_PATH = "apps/macos/Sources/OpenClaw/Resources/Localizable.xcstrings";
+const MACOS_INFO_PLIST_PATH = "apps/macos/Sources/OpenClaw/Resources/Info.plist";
+const NATIVE_SOURCE_PATH = "apps/.i18n/native-source.json";
+const NATIVE_TRANSLATIONS_DIR = "apps/.i18n/native";
+const SHARED_CHAT_UI_SOURCE_PREFIX = "apps/shared/OpenClawKit/Sources/OpenClawChatUI/";
+const SHARED_GATEWAY_DISCOVERY_STATUS_SOURCE =
+  "apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayDiscoveryStatusText.swift";
+const IOS_SOURCE_PREFIXES = [
+  "apps/ios/",
+  SHARED_CHAT_UI_SOURCE_PREFIX,
+  "apps/shared/OpenClawKit/Sources/OpenClawKit/",
+] as const;
+const IOS_CATALOG_EXCLUSIONS = new Set([
+  // Product names and preview-only single-character fixtures are intentionally verbatim.
+  "OpenClaw",
+  "z",
+]);
+const MACOS_SOURCE_PREFIXES = [
+  "apps/macos/Sources/OpenClaw/",
+  SHARED_CHAT_UI_SOURCE_PREFIX,
+  SHARED_GATEWAY_DISCOVERY_STATUS_SOURCE,
+] as const;
+const MACOS_CATALOG_EXCLUSIONS = new Set([
+  // Product names are intentionally verbatim.
+  "OpenClaw",
+]);
+const IOS_INFO_PLIST_TARGETS = [
+  {
+    outputRoot: "apps/ios/Sources",
+    sourcePath: "apps/ios/Sources/Info.plist",
+  },
+  {
+    outputRoot: "apps/ios/WatchApp",
+    sourcePath: "apps/ios/WatchApp/Info.plist",
+  },
+  {
+    outputRoot: "apps/ios/ShareExtension",
+    sourcePath: "apps/ios/ShareExtension/Info.plist",
+  },
+  {
+    outputRoot: "apps/ios/ActivityWidget",
+    sourcePath: "apps/ios/ActivityWidget/Info.plist",
+  },
+] as const;
+const INFO_PLIST_LOCALIZABLE_KEYS = new Set(["NSScreenCaptureDescription"]);
+const AMBIGUOUS_RUNTIME_INTERPOLATIONS = [
+  {
+    label: "interpolated localized resource",
+    pattern:
+      /(?:\bString\s*\(\s*localized:|\bAttributedString\s*\(\s*localized:|\bLocalizedString(?:Key|Resource)\s*\(|(?:\b[A-Za-z_]\w*)?\.localized(?:Format)?\s*\()\s*"((?:\\.|[^"\\])*)"/gu,
+    allowsInflection: true,
+  },
+  {
+    label: "interpolated multiline localized resource",
+    pattern:
+      /\b(?:String\s*\(\s*localized:|AttributedString\s*\(\s*localized:|LocalizedString(?:Key|Resource)\s*\()\s*"""([\s\S]*?)"""/gu,
+    allowsInflection: true,
+  },
+  {
+    label: "interpolated SwiftUI text literal",
+    pattern:
+      /\b(?:Text|Label|Button|TextField|SecureField|Picker|Section|LabeledContent|Toggle|Menu|ShareLink|Link|TextEditor|ProgressView|Gauge|DisclosureGroup|ControlGroup|DatePicker|Stepper)\s*\(\s*"((?:\\.|[^"\\])*)"/gu,
+    allowsInflection: false,
+  },
+  {
+    label: "interpolated multiline SwiftUI text literal",
+    pattern:
+      /\b(?:Text|Label|Button|TextField|SecureField|Picker|Section|LabeledContent|Toggle|Menu|ShareLink|Link|TextEditor|ProgressView|Gauge|DisclosureGroup|ControlGroup|DatePicker|Stepper)\s*\(\s*"""([\s\S]*?)"""/gu,
+    allowsInflection: false,
+  },
+  {
+    label: "interpolated multiline SwiftUI modifier literal",
+    pattern:
+      /\.(?:accessibilityLabel|accessibilityHint|alert|confirmationDialog|help|navigationTitle)\s*\(\s*"""([\s\S]*?)"""/gu,
+    allowsInflection: false,
+  },
+  {
+    label: "interpolated SwiftUI modifier literal",
+    pattern:
+      /\.(?:accessibilityLabel|accessibilityHint|alert|confirmationDialog|help|navigationTitle)\s*\(\s*"((?:\\.|[^"\\])*)"/gu,
+    allowsInflection: false,
+  },
+  {
+    label: "interpolated accessibility model literal",
+    pattern: /\baccessibilityLabel\s*:\s*"((?:\\.|[^"\\])*)"/gu,
+    allowsInflection: false,
+  },
+] as const;
+
+export function findAmbiguousRuntimeInterpolations(source: string): string[] {
+  const violations: string[] = [];
+  for (const { label, pattern, allowsInflection } of AMBIGUOUS_RUNTIME_INTERPOLATIONS) {
+    pattern.lastIndex = 0;
+    for (const match of source.matchAll(pattern)) {
+      const literal = match[1] ?? "";
+      if (!literal.includes("\\(") || (allowsInflection && isInflectedCountSource(literal))) {
+        continue;
+      }
+      violations.push(label);
+      break;
+    }
+  }
+  return violations;
+}
+const APPLE_LOCALE_DIRECTORIES: Record<string, string> = {
+  "ja-JP": "ja",
+  "zh-CN": "zh-Hans",
+  "zh-TW": "zh-Hant",
+};
+const LOCALIZED_WRAPPER_CONTRACTS: Record<string, readonly string[]> = {
+  "apps/macos/Sources/OpenClaw/DeviceSettingsPanels.swift": [
+    'String(localized: "Quick Chat shortcut")',
+    'String(localized: "Microphone Test")',
+    'Button("Done")',
+  ],
+  "apps/macos/Sources/OpenClaw/DeviceMicrophonePanel.swift": [
+    'String(localized: "Stopped")',
+    'String(localized: "Timeout: no trigger heard")',
+    "Text(verbatim: meterError)",
+  ],
+  "apps/ios/Sources/Design/OpenClawProComponents.swift": [
+    "enum OpenClawTextValue: ExpressibleByStringLiteral",
+    "struct OpenClawNoticeBanner: View {\n    let icon: String\n    let title: OpenClawTextValue\n    let message: OpenClawTextValue",
+    "struct OpenClawAdaptiveHeaderRow<Leading: View, Accessory: View>: View {\n    let title: OpenClawTextValue\n    let subtitle: OpenClawTextValue?",
+    "struct OpenClawStatusBadge: View {\n    @Environment(\\.colorScheme) private var colorScheme\n    let label: OpenClawTextValue",
+    "struct ProStatusRow: View {\n    let icon: String\n    let title: OpenClawTextValue\n    let detail: OpenClawTextValue",
+  ],
+  "apps/ios/Sources/Design/SettingsProTabSupport.swift": [
+    "struct SettingsDetailRow: View {\n    let label: LocalizedStringKey\n    let value: OpenClawTextValue",
+    "init(_ label: LocalizedStringKey, value: OpenClawTextValue)",
+    "self.value.text",
+    "struct SettingsApprovalItem: Identifiable {\n    let id: String\n    let icon: String\n    let title: OpenClawTextValue\n    let detail: OpenClawTextValue\n    let priority: OpenClawTextValue",
+    "self.item.title.text",
+    "self.item.detail.text",
+    "self.item.priority.text",
+  ],
+  "apps/ios/Sources/Design/SettingsProTabActions.swift": [
+    "func detailStatusCard(\n        icon: String,\n        title: OpenClawTextValue,\n        detail: OpenClawTextValue,\n        value: OpenClawTextValue",
+    "func diagnosticCheckRow(\n        icon: String,\n        title: OpenClawTextValue,\n        detail: OpenClawTextValue,\n        value: OpenClawTextValue",
+    "pendingApproval.commandPreview.map(OpenClawTextValue.verbatim)",
+    'format: String(localized: "Agent: %@")',
+  ],
+  "apps/ios/Sources/Design/SettingsProTabSections.swift": [
+    "func settingsListRow(\n        icon: String,\n        iconColor: Color,\n        title: LocalizedStringKey",
+    "func aboutLinkRow(\n        title: LocalizedStringKey",
+    "func gatewaySecureField(\n        _ placeholder: LocalizedStringKey",
+    "func settingsToggle(\n        _ title: LocalizedStringKey",
+    ".accessibilityLabel(Text(placeholder))",
+    ".accessibilityLabel(Text(title))",
+  ],
+  "apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift": [
+    'String(localized: "Secure connection is required for this host.")',
+    'String(localized: "Use only on a trusted private network.")',
+  ],
+  "apps/ios/Sources/Gateway/ExecApprovalPromptDialog.swift": [
+    "private struct ExecApprovalPromptMetadataRow: View {\n    let label: LocalizedStringKey",
+    'localized: "about ^[\\(minutes) minute](inflect: true)"',
+    'localized: "about ^[\\(hours) hour](inflect: true)"',
+  ],
+  "apps/ios/Sources/Voice/TalkGatewayPermissionState.swift": [
+    'String(format: String(localized: "Missing %@"), scope)',
+    'String(localized: "Requesting approval")',
+  ],
+  "apps/ios/Sources/Voice/TalkModeManager.swift": [
+    'format: String(localized: "Speech error: %@")',
+    'format: String(localized: "Speak failed: %@")',
+    'self.setStatus(String(localized: "Listening (PTT)"), phase: .listening)',
+  ],
+  "apps/ios/Sources/Voice/VoiceWakeManager.swift": [
+    'format: String(localized: "Recognizer error: %@")',
+    'self.statusText = String(localized: "Triggered")',
+  ],
+  "apps/ios/Sources/Design/CommandCenterSupport.swift": [
+    "Text(verbatim: self.item.title)",
+    "Text(verbatim: self.item.trailing)",
+    "Text(verbatim: self.item.detail)",
+    "struct CommandEmptyStateRow: View {\n    let icon: String\n    let title: OpenClawTextValue\n    let detail: OpenClawTextValue",
+    "private func actionButton(\n        _ title: OpenClawTextValue",
+    "self.actionButton(.verbatim(category)",
+  ],
+  "apps/ios/Sources/Gateway/GatewayQuickSetupSheet.swift": [
+    "fullRowToggle(_ title: LocalizedStringKey",
+    "private struct GatewayQuickSetupStatusRow: View {\n    let title: LocalizedStringKey\n    let value: String",
+    "Text(LocalizedStringKey(availability.actionTitle))",
+    "Text(verbatim: self.message)",
+  ],
+  "apps/ios/Sources/Gateway/GatewayProblemView.swift": [
+    "title: .verbatim(self.problem.localizedTitle)",
+    "message: .verbatim(self.problem.localizedMessage)",
+    "Text(verbatim: primaryActionTitle)",
+  ],
+  "apps/ios/Sources/LiveActivity/LiveActivityManager.swift": [
+    'String(localized: "Connecting...")',
+    "status: .disconnected",
+  ],
+  "apps/ios/WatchApp/Sources/WatchInboxView.swift": [
+    "enum WatchTextValue {\n    case localized(LocalizedStringResource)",
+    "private struct WatchFaceHeader: View {\n    let section: WatchTextValue\n    let title: WatchTextValue\n    let subtitle: WatchTextValue",
+    "private struct WatchHeroCard: View {\n    let label: WatchTextValue\n    let title: WatchTextValue\n    let subtitle: WatchTextValue",
+    "private struct WatchStackCard: View {\n    let label: WatchTextValue\n    let title: WatchTextValue\n    let subtitle: WatchTextValue",
+    "private struct WatchDecisionButton: View {\n    let title: LocalizedStringKey",
+    'format: String(localized: "Expires in %@")',
+    'String(localized: "Pending review")',
+    'String(localized: "Review command below")',
+    "title: .verbatim(record.approval.commandPreview",
+  ],
+  "apps/ios/WatchApp/Sources/WatchDirectNode.swift": [
+    'private(set) var statusText = String(\n        localized: "Use iPhone Settings to enable direct connection.")',
+    'format: String(localized: "Direct connection failed: %@")',
+  ],
+  "apps/ios/WatchApp/Sources/WatchInboxStore.swift": [
+    "WatchAppCommandStatus(command: command, code: .sending)",
+    "WatchAppCommandStatus(command: command, code: .sent)",
+    "WatchAppCommandStatus(command: command, code: .queued)",
+  ],
+};
+const RAW_LOCALIZATION_BYPASSES: Record<string, readonly string[]> = {
+  "apps/ios/Sources/Design/SettingsProTabSections.swift": [
+    "func settingsListRow(\n        icon: String,\n        iconColor: Color,\n        title: String",
+    "func aboutLinkRow(title: String",
+    "func gatewayActionButton(\n        title: String",
+    "func gatewaySecureField(_ placeholder: String",
+    "func settingsToggle(\n        _ title: String",
+    ".accessibilityLabel(title)",
+  ],
+  "apps/ios/Sources/Gateway/GatewayConnectionController+Capabilities.swift": [
+    'helperText: "Secure connection is required for this host."',
+    'helperText: "Use only on a trusted private network."',
+  ],
+  "apps/ios/Sources/Gateway/ExecApprovalPromptDialog.swift": [
+    "private struct ExecApprovalPromptMetadataRow: View {\n    let label: String",
+    'return "under a minute"',
+    'return "about 1 minute"',
+  ],
+  "apps/ios/Sources/Voice/TalkModeManager.swift": [
+    'self.statusText = "',
+    'streamingOwner.terminalStatus = "',
+  ],
+  "apps/ios/Sources/Voice/VoiceWakeManager.swift": ['self.statusText = "'],
+  "apps/ios/Sources/Design/SettingsProTabSupport.swift": [
+    "struct SettingsDetailRow: View {\n    let label: LocalizedStringKey\n    let value: String",
+    "init(_ label: LocalizedStringKey, value: String)",
+    "Text(self.value)",
+    "Text(self.item.title)",
+    "Text(self.item.detail)",
+    "Text(self.item.priority)",
+  ],
+  "apps/ios/Sources/Design/CommandCenterSupport.swift": [
+    "Text(self.item.title)",
+    "Text(self.item.trailing)",
+    "Text(self.item.detail)",
+    "struct CommandEmptyStateRow: View {\n    let icon: String\n    let title: String",
+    "private func actionButton(\n        _ title: String",
+  ],
+  "apps/ios/Sources/Design/SettingsProTabActions.swift": [
+    "func detailStatusCard(\n        icon: String,\n        title: String",
+    "func diagnosticCheckRow(\n        icon: String,\n        title: String",
+  ],
+  "apps/ios/WatchApp/Sources/WatchInboxView.swift": [
+    'parts.append("Expires in \\(expiresText)")',
+    'return "Expires in <1m"',
+    'return "Expires in \\(deltaSeconds / 60)m"',
+    'return "Pending review"',
+    'return "Review command below"',
+    'return "Stop speaking"',
+    'return "Cancel voice turn"',
+    'return "Start voice turn"',
+  ],
+  "apps/ios/WatchApp/Sources/WatchDirectNode.swift": [
+    'private(set) var statusText = "',
+    'self.statusText = "',
+  ],
+  "apps/ios/WatchApp/Sources/WatchInboxStore.swift": [
+    'self.appSnapshotStatusText = "',
+    'self.appCommandStatusText = "',
+    'self.execApprovals[index].statusText = "',
+    'self.replyStatusText = "',
+  ],
+};
+
+type StringUnit = {
+  state?: string;
+  value?: string;
+};
+
+type CatalogLocalization = Record<string, unknown> & {
+  stringUnit?: StringUnit;
+};
+
+type CatalogEntry = Record<string, unknown> & {
+  localizations?: Record<string, CatalogLocalization>;
+};
+
+type Catalog = {
+  sourceLanguage?: string;
+  strings?: Record<string, CatalogEntry>;
+  version?: string;
+};
+
+type NativeSourceEntry = {
+  id: string;
+  source: string;
+  sites: Array<{ kind: string; path: string }>;
+  surface: string;
+};
+
+type NativeSourceArtifact = {
+  entries: NativeSourceEntry[];
+  version: number;
+};
+
+type NativeTranslationArtifact = {
+  locale: string;
+  translations: Record<string, string>;
+  version: number;
+};
+
+export type AppleTranslationContradiction = {
+  locale: string;
+  source: string;
+  translations: string[];
+};
+
+export type AppleCatalogBuild = {
+  catalog: Catalog;
+  contradictions: AppleTranslationContradiction[];
+};
+
+function formatTokens(value: string): string[] {
+  return [...value.matchAll(FORMAT_RE)].map((match) => match[0]).toSorted();
+}
+
+function stringsLiteral(value: string): string {
+  return JSON.stringify(value);
+}
+
+function compareCodeUnits(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+export function serializeAppleCatalog(catalog: Catalog): string {
+  const topLevelEntries = Object.entries(catalog);
+  const lines = ["{"];
+
+  for (const [topLevelIndex, [key, value]] of topLevelEntries.entries()) {
+    const comma = topLevelIndex === topLevelEntries.length - 1 ? "" : ",";
+    if (key !== "strings" || !value || typeof value !== "object" || Array.isArray(value)) {
+      lines.push(`  ${JSON.stringify(key)}: ${JSON.stringify(value)}${comma}`);
+      continue;
+    }
+
+    const entries = Object.entries(value);
+    lines.push(`  ${JSON.stringify(key)}: {`);
+    for (const [entryIndex, [entryKey, entry]] of entries.entries()) {
+      const entryComma = entryIndex === entries.length - 1 ? "" : ",";
+      lines.push(`    ${JSON.stringify(entryKey)}: ${JSON.stringify(entry)}${entryComma}`);
+    }
+    lines.push(`  }${comma}`);
+  }
+
+  lines.push("}", "");
+  return lines.join("\n");
+}
+
+function decodeXml(value: string): string {
+  return value
+    .replaceAll("&quot;", '"')
+    .replaceAll("&apos;", "'")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&amp;", "&");
+}
+
+function parseInfoPlistStrings(source: string): Array<{ key: string; source: string }> {
+  return [...source.matchAll(/<key>([^<]+)<\/key>\s*<string>([\s\S]*?)<\/string>/gu)]
+    .map((match) => ({
+      key: decodeXml(match[1] ?? ""),
+      source: decodeXml(match[2] ?? ""),
+    }))
+    .filter(
+      (entry) =>
+        entry.key.endsWith("UsageDescription") || INFO_PLIST_LOCALIZABLE_KEYS.has(entry.key),
+    );
+}
+
+type InfoPlistTranslation = {
+  source?: string;
+  value: string;
+};
+
+function parseStringsFile(source: string): Map<string, InfoPlistTranslation> {
+  const values = new Map<string, InfoPlistTranslation>();
+  for (const match of source.matchAll(
+    /(?:^\/\* OpenClaw source: ("(?:\\.|[^"\\])*") \*\/\n)?^\s*("(?:\\.|[^"\\])*")\s*=\s*("(?:\\.|[^"\\])*");/gmu,
+  )) {
+    values.set(JSON.parse(match[2] ?? '""') as string, {
+      source: match[1] ? (JSON.parse(match[1]) as string) : undefined,
+      value: JSON.parse(match[3] ?? '""') as string,
+    });
+  }
+  return values;
+}
+
+export function selectInfoPlistTranslation(
+  source: string,
+  candidates: readonly string[],
+  existing?: InfoPlistTranslation,
+): string {
+  const translatedCandidates = candidates.filter(
+    (candidate) => candidate.trim() && candidate.trim() !== source.trim(),
+  );
+  if (translatedCandidates.length > 0) {
+    return chooseTranslation(source, translatedCandidates);
+  }
+  return existing?.source === source && existing.value.trim() ? existing.value : source;
+}
+
+export function infoPlistTranslationCandidates(
+  artifact: NativeTranslationArtifact | undefined,
+  sourceId: string,
+  _source: string,
+): string[] {
+  const translated = artifact?.translations[sourceId];
+  return typeof translated === "string" ? [translated] : [];
+}
+
+function infoPlistSourceIds(nativeSource: NativeSourceArtifact): Map<string, string> {
+  return new Map(
+    nativeSource.entries.flatMap((entry) =>
+      entry.sites
+        .filter((site) => site.kind === "plist-string")
+        .map((site) => [[site.path, entry.source].join("\u0000"), entry.id] as const),
+    ),
+  );
+}
+
+function renderInfoPlistStrings(
+  sourcePath: string,
+  sourceEntries: ReadonlyArray<{ key: string; source: string }>,
+  sourceIds: ReadonlyMap<string, string>,
+  artifact: NativeTranslationArtifact | undefined,
+  existing: ReadonlyMap<string, InfoPlistTranslation> = new Map(),
+): string {
+  const lines = sourceEntries.map(({ key, source }) => {
+    const sourceId = sourceIds.get([sourcePath, source].join("\u0000"));
+    if (!sourceId) {
+      throw new Error(`missing native InfoPlist source id for ${sourcePath}:${key}`);
+    }
+    const candidates = infoPlistTranslationCandidates(artifact, sourceId, source);
+    const value = selectInfoPlistTranslation(source, candidates, existing.get(key));
+    return [
+      `/* OpenClaw source: ${stringsLiteral(source)} */`,
+      `${stringsLiteral(key)} = ${stringsLiteral(value)};`,
+    ].join("\n");
+  });
+  return `${lines.join("\n")}\n`;
+}
+
+async function readOptionalFile(filePath: string): Promise<string | null> {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function isAppleCatalogKind(kind: string): boolean {
+  return kind === "conditional-branch" || kind.startsWith("ui-");
+}
+
+function isAppleCatalogEntry(
+  entry: NativeSourceEntry,
+  sourcePrefixes: readonly string[],
+  exclusions: ReadonlySet<string>,
+): boolean {
+  return (
+    entry.surface === "apple" &&
+    entry.sites.some(
+      (site) =>
+        sourcePrefixes.some((prefix) => site.path.startsWith(prefix)) &&
+        isAppleCatalogKind(site.kind),
+    ) &&
+    (!entry.source.includes("\\(") || isInflectedCountSource(entry.source)) &&
+    !exclusions.has(entry.source)
+  );
+}
+
+function isInflectedCountSource(value: string): boolean {
+  if (!value.includes(INFLECTED_COUNT_MARKER)) {
+    return false;
+  }
+  const interpolations = value.match(/\\\([^)]*\)/gu) ?? [];
+  const segments = [...value.matchAll(INFLECTED_COUNT_SEGMENT_RE)];
+  return (
+    segments.length > 0 &&
+    interpolations.length === segments.length &&
+    interpolations.every((interpolation) =>
+      INFLECTED_COUNT_INTERPOLATION_EXACT_RE.test(interpolation),
+    ) &&
+    segments.every(
+      ([segment]) => (segment.match(INFLECTED_COUNT_INTERPOLATION_RE) ?? []).length === 1,
+    )
+  );
+}
+
+function appleCatalogValue(value: string): string {
+  if (!isInflectedCountSource(value)) {
+    return value;
+  }
+  return value.replace(INFLECTED_COUNT_SEGMENT_RE, (segment) =>
+    segment.replace(INFLECTED_COUNT_INTERPOLATION_RE, "%lld"),
+  );
+}
+
+function chooseTranslation(source: string, translations: readonly string[]): string {
+  // Apple catalogs key by source, so duplicate native contexts must converge.
+  // Preserve shipped values first; otherwise choose deterministically and report every conflict.
+  const counts = new Map<string, number>();
+  for (const translation of translations) {
+    counts.set(translation, (counts.get(translation) ?? 0) + 1);
+  }
+  return (
+    [...counts].toSorted(([leftValue, leftCount], [rightValue, rightCount]) => {
+      const sourcePenalty = Number(leftValue === source) - Number(rightValue === source);
+      return sourcePenalty || rightCount - leftCount || compareCodeUnits(leftValue, rightValue);
+    })[0]?.[0] ?? source
+  );
+}
+
+function buildAppleCatalog(
+  existingCatalog: Catalog,
+  nativeSource: NativeSourceArtifact,
+  translations: readonly NativeTranslationArtifact[],
+  includesEntry: (entry: NativeSourceEntry) => boolean,
+): AppleCatalogBuild {
+  const catalogEntries = nativeSource.entries
+    .filter(includesEntry)
+    .map((entry) => [entry, appleCatalogValue(entry.source)] as const);
+  const sources = [...new Set(catalogEntries.map(([, source]) => source))].toSorted(
+    compareCodeUnits,
+  );
+  const catalogIds = new Set(catalogEntries.map(([entry]) => entry.id));
+  const existingStrings = existingCatalog.strings ?? {};
+  const nativeEntryById = new Map(nativeSource.entries.map((entry) => [entry.id, entry]));
+  const translationsByLocale = new Map(
+    translations.map((artifact) => {
+      const bySource = new Map<string, string[]>();
+      for (const [id, translated] of Object.entries(artifact.translations)) {
+        const entry = nativeEntryById.get(id);
+        if (!entry || !catalogIds.has(id)) {
+          continue;
+        }
+        const source = appleCatalogValue(entry.source);
+        const values = bySource.get(source) ?? [];
+        values.push(appleCatalogValue(translated));
+        bySource.set(source, values);
+      }
+      return [artifact.locale, bySource] as const;
+    }),
+  );
+  const contradictions: AppleTranslationContradiction[] = [];
+  const strings: Record<string, CatalogEntry> = {};
+
+  for (const source of sources) {
+    const existing = existingStrings[source];
+    const localizations: NonNullable<CatalogEntry["localizations"]> = {};
+    for (const locale of REQUIRED_LOCALES) {
+      const candidates = translationsByLocale.get(locale)?.get(source) ?? [];
+      const distinct = [...new Set(candidates)].toSorted(compareCodeUnits);
+      if (distinct.length > 1) {
+        contradictions.push({ locale, source, translations: distinct });
+      }
+      const existingUnit = existing?.localizations?.[locale]?.stringUnit;
+      if (existingUnit?.value && existingUnit.state === "translated") {
+        localizations[locale] = { stringUnit: { ...existingUnit } };
+        continue;
+      }
+      if (locale === "en") {
+        localizations.en = {
+          stringUnit: {
+            state: "translated",
+            value: source,
+          },
+        };
+        continue;
+      }
+      const value = chooseTranslation(source, candidates);
+      localizations[locale] = {
+        stringUnit: {
+          state: value === source ? "new" : "translated",
+          value,
+        },
+      };
+    }
+    strings[source] = { localizations };
+  }
+
+  return {
+    catalog: {
+      sourceLanguage: "en",
+      strings,
+      version: "1.0",
+    },
+    contradictions: contradictions.toSorted(
+      (left, right) =>
+        compareCodeUnits(left.source, right.source) || compareCodeUnits(left.locale, right.locale),
+    ),
+  };
+}
+
+export function buildIosCatalog(
+  existingCatalog: Catalog,
+  nativeSource: NativeSourceArtifact,
+  translations: readonly NativeTranslationArtifact[],
+): AppleCatalogBuild {
+  return buildAppleCatalog(existingCatalog, nativeSource, translations, (entry) =>
+    isAppleCatalogEntry(entry, IOS_SOURCE_PREFIXES, IOS_CATALOG_EXCLUSIONS),
+  );
+}
+
+export function buildMacosCatalog(
+  existingCatalog: Catalog,
+  nativeSource: NativeSourceArtifact,
+  translations: readonly NativeTranslationArtifact[],
+): AppleCatalogBuild {
+  return buildAppleCatalog(existingCatalog, nativeSource, translations, (entry) =>
+    isAppleCatalogEntry(entry, MACOS_SOURCE_PREFIXES, MACOS_CATALOG_EXCLUSIONS),
+  );
+}
+
+async function listSwiftFiles(directory: string): Promise<string[]> {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      if (
+        entry.isDirectory() &&
+        /^(?:\.build|build|DerivedData|Previews?|Tests?|UITests?)$/u.test(entry.name)
+      ) {
+        return [];
+      }
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        return listSwiftFiles(entryPath);
+      }
+      return entry.isFile() && entry.name.endsWith(".swift") ? [entryPath] : [];
+    }),
+  );
+  return nested.flat();
+}
+
+async function validateRuntimeInterpolationPaths(): Promise<void> {
+  const roots = [...new Set([...IOS_SOURCE_PREFIXES, ...MACOS_SOURCE_PREFIXES])];
+  const files = new Set(
+    (
+      await Promise.all(
+        roots.map((prefix) => {
+          const sourcePath = path.join(ROOT, prefix);
+          return prefix.endsWith(".swift")
+            ? Promise.resolve([sourcePath])
+            : listSwiftFiles(sourcePath);
+        }),
+      )
+    ).flat(),
+  );
+  const violations: string[] = [];
+  for (const file of [...files].toSorted()) {
+    const source = await readFile(file, "utf8");
+    for (const label of findAmbiguousRuntimeInterpolations(source)) {
+      violations.push(`${path.relative(ROOT, file)}: ${label}`);
+    }
+  }
+  if (violations.length) {
+    throw new Error(
+      `Apple i18n runtime interpolation bypasses generated catalog coverage:\n${violations.join("\n")}`,
+    );
+  }
+}
+
+async function readNativeTranslations(): Promise<NativeTranslationArtifact[]> {
+  const expectedFiles = NATIVE_I18N_LOCALES.map((locale) => `${locale}.json`).toSorted();
+  const actualFiles = (
+    await readdir(path.join(ROOT, NATIVE_TRANSLATIONS_DIR), {
+      withFileTypes: true,
+    })
+  )
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => entry.name)
+    .toSorted();
+  if (JSON.stringify(actualFiles) !== JSON.stringify(expectedFiles)) {
+    throw new Error(
+      `Apple/native locale parity drift: expected ${JSON.stringify(expectedFiles)}, got ${JSON.stringify(actualFiles)}`,
+    );
+  }
+  return Promise.all(
+    NATIVE_I18N_LOCALES.map(async (locale) => {
+      const artifact = JSON.parse(
+        await readFile(path.join(ROOT, NATIVE_TRANSLATIONS_DIR, `${locale}.json`), "utf8"),
+      ) as NativeTranslationArtifact;
+      if (artifact.locale !== locale) {
+        throw new Error(
+          `native Apple translation artifact ${locale} declares locale ${artifact.locale}`,
+        );
+      }
+      return artifact;
+    }),
+  );
+}
+
+async function readAppleCatalogBuild(
+  catalogPath: string,
+  buildCatalog: typeof buildIosCatalog,
+): Promise<AppleCatalogBuild> {
+  const existingCatalog = JSON.parse(
+    await readFile(path.join(ROOT, catalogPath), "utf8"),
+  ) as Catalog;
+  const nativeSource = JSON.parse(
+    await readFile(path.join(ROOT, NATIVE_SOURCE_PATH), "utf8"),
+  ) as NativeSourceArtifact;
+  const translations = await readNativeTranslations();
+  return buildCatalog(existingCatalog, nativeSource, translations);
+}
+
+function validateCatalog(pathName: string, catalog: Catalog): number {
+  if (catalog.sourceLanguage !== "en" || catalog.version !== "1.0" || !catalog.strings) {
+    throw new Error(`invalid Apple string catalog: ${pathName}`);
+  }
+  let checked = 0;
+  for (const [key, entry] of Object.entries(catalog.strings)) {
+    const sourceTokens = formatTokens(key);
+    for (const locale of REQUIRED_LOCALES) {
+      const unit = entry.localizations?.[locale]?.stringUnit;
+      const value = unit?.value?.trim();
+      if (!value || (locale === "en" && unit?.state !== "translated")) {
+        throw new Error(
+          `Apple catalog ${pathName} is missing ${locale} for ${JSON.stringify(key)}`,
+        );
+      }
+      if (locale !== "en" && unit?.state !== "translated" && unit?.state !== "new") {
+        throw new Error(
+          `Apple catalog ${pathName} has untranslated ${locale} copy for ${JSON.stringify(key)}`,
+        );
+      }
+      if (formatTokens(value).join("\u0000") !== sourceTokens.join("\u0000")) {
+        throw new Error(
+          `Apple catalog ${pathName} has placeholder drift in ${locale} for ${JSON.stringify(key)}`,
+        );
+      }
+    }
+    checked += 1;
+  }
+  return checked;
+}
+
+async function syncIosInfoPlist(write: boolean): Promise<number> {
+  const translations = await readNativeTranslations();
+  const nativeSource = JSON.parse(
+    await readFile(path.join(ROOT, NATIVE_SOURCE_PATH), "utf8"),
+  ) as NativeSourceArtifact;
+  const sourceIds = infoPlistSourceIds(nativeSource);
+  let checked = 0;
+  for (const target of IOS_INFO_PLIST_TARGETS) {
+    const sourceEntries = parseInfoPlistStrings(
+      await readFile(path.join(ROOT, target.sourcePath), "utf8"),
+    );
+    for (const locale of NATIVE_I18N_LOCALES) {
+      const localeDir = APPLE_LOCALE_DIRECTORIES[locale] ?? locale;
+      const outputPath = path.join(
+        ROOT,
+        target.outputRoot,
+        `${localeDir}.lproj`,
+        "InfoPlist.strings",
+      );
+      const existingSource = await readOptionalFile(outputPath);
+      const existing = parseStringsFile(existingSource ?? "");
+      const artifact = translations.find((candidate) => candidate.locale === locale);
+      const expected = renderInfoPlistStrings(
+        target.sourcePath,
+        sourceEntries,
+        sourceIds,
+        artifact,
+        existing,
+      );
+      if (existingSource !== expected) {
+        if (!write) {
+          throw new Error(
+            `Apple InfoPlist localization ${path.relative(ROOT, outputPath)} is stale; run apple-app-i18n.ts sync-ios --write`,
+          );
+        }
+        await mkdir(path.dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, expected, "utf8");
+      }
+      checked += 1;
+    }
+  }
+  return checked;
+}
+
+export async function syncIosCatalog(write: boolean): Promise<AppleCatalogBuild> {
+  const build = await readAppleCatalogBuild(IOS_CATALOG_PATH, buildIosCatalog);
+  const catalogPath = path.join(ROOT, IOS_CATALOG_PATH);
+  const expected = serializeAppleCatalog(build.catalog);
+  const actual = await readFile(catalogPath, "utf8");
+  if (actual !== expected) {
+    if (!write) {
+      throw new Error(
+        `Apple catalog ${IOS_CATALOG_PATH} is stale; run apple-app-i18n.ts sync-ios --write`,
+      );
+    }
+    await writeFile(catalogPath, expected, "utf8");
+  }
+  return build;
+}
+
+export async function syncMacosCatalog(write: boolean): Promise<AppleCatalogBuild> {
+  const build = await readAppleCatalogBuild(MACOS_CATALOG_PATH, buildMacosCatalog);
+  const catalogPath = path.join(ROOT, MACOS_CATALOG_PATH);
+  const expected = serializeAppleCatalog(build.catalog);
+  const actual = await readFile(catalogPath, "utf8");
+  if (actual !== expected) {
+    if (!write) {
+      assertMacosCatalogCurrent(actual, build);
+      return build;
+    }
+    await writeFile(catalogPath, expected, "utf8");
+  }
+  return build;
+}
+
+export function assertMacosCatalogCurrent(actual: string, build: AppleCatalogBuild): void {
+  if (actual !== serializeAppleCatalog(build.catalog)) {
+    throw new Error(
+      `Apple catalog ${MACOS_CATALOG_PATH} is stale; run native-app-i18n.ts sync --write`,
+    );
+  }
+}
+
+/**
+ * Regenerates every Apple derived artifact (app catalogs and InfoPlist strings).
+ * Shared by this CLI and native-app-i18n's sync so the inventory can never be
+ * rewritten without its derived catalogs.
+ */
+export async function syncAppleAppI18n(): Promise<{
+  build: AppleCatalogBuild;
+  infoPlistFiles: number;
+  macosBuild: AppleCatalogBuild;
+}> {
+  const [build, macosBuild] = await Promise.all([syncIosCatalog(true), syncMacosCatalog(true)]);
+  const infoPlistFiles = await syncIosInfoPlist(true);
+  return { build, infoPlistFiles, macosBuild };
+}
+
+export async function verifyAppleAppI18n() {
+  await validateRuntimeInterpolationPaths();
+  for (const [sourcePath, contracts] of Object.entries(LOCALIZED_WRAPPER_CONTRACTS)) {
+    const source = await readFile(path.join(ROOT, sourcePath), "utf8");
+    const missing = contracts.filter((contract) => !source.includes(contract));
+    if (missing.length) {
+      throw new Error(
+        `Apple i18n wrapper ${sourcePath} bypasses localized string lookup: ${missing.join(", ")}`,
+      );
+    }
+  }
+  for (const [sourcePath, bypasses] of Object.entries(RAW_LOCALIZATION_BYPASSES)) {
+    const source = await readFile(path.join(ROOT, sourcePath), "utf8");
+    const present = bypasses.filter((bypass) => source.includes(bypass));
+    if (present.length) {
+      throw new Error(
+        `Apple i18n runtime path ${sourcePath} contains raw app-owned strings: ${present.join(", ")}`,
+      );
+    }
+  }
+
+  const macosBuild = await readAppleCatalogBuild(MACOS_CATALOG_PATH, buildMacosCatalog);
+  const macosKeys = validateCatalog(MACOS_CATALOG_PATH, macosBuild.catalog);
+
+  process.stdout.write(`apple-app-i18n: sourceMacosKeys=${macosKeys}\n`);
+}
+
+export async function checkAppleAppI18n() {
+  await verifyAppleAppI18n();
+  const [iosBuild, macosBuild] = await Promise.all([
+    syncIosCatalog(false),
+    syncMacosCatalog(false),
+  ]);
+  const iosKeys = validateCatalog(IOS_CATALOG_PATH, iosBuild.catalog);
+  const macosKeys = validateCatalog(MACOS_CATALOG_PATH, macosBuild.catalog);
+  const infoPlistFiles = await syncIosInfoPlist(false);
+
+  process.stdout.write(
+    [
+      `apple-app-i18n: iosKeys=${iosKeys}`,
+      `macosKeys=${macosKeys}`,
+      `infoPlistFiles=${infoPlistFiles}`,
+      `translationContradictions=${iosBuild.contradictions.length}`,
+      `macosTranslationContradictions=${macosBuild.contradictions.length}`,
+      `locales=${NATIVE_I18N_LOCALES.join(",")}`,
+      "\n",
+    ].join(" "),
+  );
+}
+
+export async function compileMacosLocalizations(outputDir: string) {
+  // Source PRs intentionally leave generated Apple catalogs for the serialized
+  // post-merge refresh. Package from the derived catalog so source changes
+  // cannot ship stale localization coverage before that refresh lands.
+  await verifyAppleAppI18n();
+  const catalog = (await readAppleCatalogBuild(MACOS_CATALOG_PATH, buildMacosCatalog)).catalog;
+  if (!catalog.strings) {
+    throw new Error(`invalid Apple string catalog: ${MACOS_CATALOG_PATH}`);
+  }
+  const [nativeSource, translations, infoPlistSource] = await Promise.all([
+    readFile(path.join(ROOT, NATIVE_SOURCE_PATH), "utf8").then(
+      (source) => JSON.parse(source) as NativeSourceArtifact,
+    ),
+    readNativeTranslations(),
+    readFile(path.join(ROOT, MACOS_INFO_PLIST_PATH), "utf8"),
+  ]);
+  const sourceIds = infoPlistSourceIds(nativeSource);
+  const infoPlistEntries = parseInfoPlistStrings(infoPlistSource);
+
+  for (const locale of REQUIRED_LOCALES) {
+    const localeDir = APPLE_LOCALE_DIRECTORIES[locale] ?? locale;
+    const lprojDir = path.join(outputDir, `${localeDir}.lproj`);
+    const lines = Object.entries(catalog.strings)
+      .toSorted(([left], [right]) => compareCodeUnits(left, right))
+      .map(([key, entry]) => {
+        const value = entry.localizations?.[locale]?.stringUnit?.value;
+        if (!value) {
+          throw new Error(
+            `Apple catalog ${MACOS_CATALOG_PATH} is missing ${locale} for ${JSON.stringify(key)}`,
+          );
+        }
+        return `${stringsLiteral(key)} = ${stringsLiteral(value)};`;
+      });
+    await mkdir(lprojDir, { recursive: true });
+    await writeFile(path.join(lprojDir, "Localizable.strings"), `${lines.join("\n")}\n`, "utf8");
+    if (locale !== "en") {
+      const artifact = translations.find((candidate) => candidate.locale === locale);
+      const infoPlistStrings = renderInfoPlistStrings(
+        MACOS_INFO_PLIST_PATH,
+        infoPlistEntries,
+        sourceIds,
+        artifact,
+      );
+      await writeFile(path.join(lprojDir, "InfoPlist.strings"), infoPlistStrings, "utf8");
+    }
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  const [command, flag, value] = process.argv.slice(2);
+  if (command === "check") {
+    await checkAppleAppI18n();
+  } else if (command === "sync-ios" && flag === "--write") {
+    const { build, infoPlistFiles, macosBuild } = await syncAppleAppI18n();
+    process.stdout.write(
+      `apple-app-i18n: synced Apple catalogs and ${infoPlistFiles} InfoPlist files; contradictions=${build.contradictions.length + macosBuild.contradictions.length}\n`,
+    );
+  } else if (command === "compile-macos" && flag === "--output" && value) {
+    await compileMacosLocalizations(path.resolve(value));
+  } else {
+    throw new Error(
+      "usage: node --import tsx scripts/apple-app-i18n.ts check|sync-ios --write|compile-macos --output <dir>",
+    );
+  }
+}

scripts/audit-seams.mts

@@ -0,0 +1,1049 @@
+#!/usr/bin/env node
+// Audits repo ownership seams, optional plugin leaks, and nearby test coverage signals.
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import {
+  BUNDLED_PLUGIN_PATH_PREFIX,
+  BUNDLED_PLUGIN_ROOT_DIR,
+} from "./lib/bundled-plugin-paths.mjs";
+import { visitModuleSpecifiers } from "./lib/guard-inventory-utils.mjs";
+import { optionalBundledClusterSet } from "./lib/optional-bundled-clusters.mjs";
+import { escapeRegExp } from "./lib/regexp.mjs";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+import { toLine } from "./lib/ts-guard-utils.mts";
+
+type ImportEntry = {
+  family: string;
+  file: string;
+  kind: string;
+  line: number;
+  resolvedPath: string;
+  specifier: string;
+};
+type OptionalClusterImportEntry = Omit<ImportEntry, "family"> & { cluster: string };
+type ModuleSpecifierVisit = {
+  kind: string;
+  specifierNode: ts.Node;
+  specifier: string;
+};
+const MATCH_QUALITY_RANK = {
+  "exact-stem": 0,
+  "path-nearby": 1,
+  "direct-import": 2,
+  "dir-token": 3,
+} as const satisfies Record<string, number>;
+type MatchQuality = keyof typeof MATCH_QUALITY_RANK;
+type RelatedTestMatch = { file: string; matchQuality: MatchQuality };
+type PackageJson = {
+  dependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  name?: string;
+  private?: boolean;
+  openclaw?: { install?: { npmSpec?: string } };
+};
+
+const repoRoot = resolveRepoRoot(import.meta.url);
+const srcRoot = path.join(repoRoot, "src");
+const extensionsRoot = path.join(repoRoot, BUNDLED_PLUGIN_ROOT_DIR);
+const testRoot = path.join(repoRoot, "test");
+const workspacePackagePaths = ["ui/package.json"];
+const MAX_SCAN_BYTES = 2 * 1024 * 1024;
+const compareStrings = (left: string, right: string) => left.localeCompare(right);
+const HELP_TEXT = `Usage: node --import tsx scripts/audit-seams.mts [--help]
+
+Audit repo seam inventory and emit JSON to stdout.
+
+Sections:
+  duplicatedSeamFamilies       Plugin SDK seam families imported from multiple production files
+  overlapFiles                 Production files that touch multiple seam families
+  optionalClusterStaticLeaks   Optional extension/plugin clusters referenced from the static graph
+  missingPackages              Workspace packages whose deps are not mirrored at the root
+  seamTestInventory            High-signal seam candidates with nearby-test gap signals,
+                               including cron orchestration seams for agent handoff,
+                               outbound/media delivery, heartbeat/followup handoff,
+                               and scheduler state crossings, plus subagent seams
+                               for spawn/session handoff, announce delivery,
+                               lifecycle registry, cleanup, and parent streaming
+
+Notes:
+  - Output is JSON only.
+  - For clean redirected JSON through package scripts, prefer:
+      pnpm --silent audit:seams > seam-inventory.json
+`;
+
+async function collectWorkspacePackagePaths() {
+  const entries = await fs.readdir(extensionsRoot, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      workspacePackagePaths.push(path.join("extensions", entry.name, "package.json"));
+    }
+  }
+}
+
+function normalizePath(filePath: string) {
+  return path.relative(repoRoot, filePath).split(path.sep).join("/");
+}
+
+async function readScannableText(filePath: string, maxBytes = MAX_SCAN_BYTES) {
+  const stat = await fs.stat(filePath);
+  if (stat.size <= maxBytes) {
+    return fs.readFile(filePath, "utf8");
+  }
+  const handle = await fs.open(filePath, "r");
+  try {
+    const buffer = Buffer.alloc(maxBytes);
+    const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+function redactNpmSpec(npmSpec: unknown) {
+  if (typeof npmSpec !== "string") {
+    return npmSpec ?? null;
+  }
+  return npmSpec
+    .replace(/(https?:\/\/)([^/\s:@]+):([^/\s@]+)@/gi, "$1***:***@")
+    .replace(/(https?:\/\/)([^/\s:@]+)@/gi, "$1***@");
+}
+
+function isCodeFile(fileName: string) {
+  return /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.test(fileName);
+}
+
+function isTestLikePath(relativePath: string) {
+  return (
+    /(^|\/)(__tests__|fixtures|test-utils|test-fixtures)\//.test(relativePath) ||
+    /(?:^|\/)[^/]*(?:[.-](?:test|spec))(?:[.-][^/]+)?\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.test(
+      relativePath,
+    )
+  );
+}
+
+function isProductionLikeFile(relativePath: string) {
+  return !isTestLikePath(relativePath);
+}
+
+async function walkCodeFiles(rootDir: string) {
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === "dist" || entry.name === "node_modules") {
+        continue;
+      }
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || !isCodeFile(entry.name)) {
+        continue;
+      }
+      const relativePath = normalizePath(fullPath);
+      if (!isProductionLikeFile(relativePath)) {
+        continue;
+      }
+      out.push(fullPath);
+    }
+  }
+  await walk(rootDir);
+  return out.toSorted((left, right) => normalizePath(left).localeCompare(normalizePath(right)));
+}
+
+async function walkAllCodeFiles(rootDir: string, options: { includeTests?: boolean } = {}) {
+  const out: string[] = [];
+  const includeTests = options.includeTests === true;
+
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === "dist" || entry.name === "node_modules") {
+        continue;
+      }
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+        continue;
+      }
+      if (!entry.isFile() || !isCodeFile(entry.name)) {
+        continue;
+      }
+      const relativePath = normalizePath(fullPath);
+      if (!includeTests && !isProductionLikeFile(relativePath)) {
+        continue;
+      }
+      out.push(fullPath);
+    }
+  }
+
+  await walk(rootDir);
+  return out.toSorted((left, right) => normalizePath(left).localeCompare(normalizePath(right)));
+}
+
+function resolveRelativeSpecifier(specifier: string, importerFile: string) {
+  if (!specifier.startsWith(".")) {
+    return null;
+  }
+  return normalizePath(path.resolve(path.dirname(importerFile), specifier));
+}
+
+function normalizePluginSdkFamily(resolvedPath: string) {
+  const relative = resolvedPath.replace(/^src\/plugin-sdk\//, "");
+  return relative.replace(/\.(m|c)?[jt]sx?$/, "");
+}
+
+function resolveOptionalClusterFromPath(resolvedPath: string) {
+  if (resolvedPath.startsWith(BUNDLED_PLUGIN_PATH_PREFIX)) {
+    const [, cluster] = resolvedPath.split("/");
+    return cluster && optionalBundledClusterSet.has(cluster) ? cluster : null;
+  }
+  if (resolvedPath.startsWith("src/plugin-sdk/")) {
+    const [cluster] = normalizePluginSdkFamily(resolvedPath).split("/");
+    return cluster && optionalBundledClusterSet.has(cluster) ? cluster : null;
+  }
+  return null;
+}
+
+function compareImports(left: ImportEntry, right: ImportEntry) {
+  return (
+    left.family.localeCompare(right.family) ||
+    left.file.localeCompare(right.file) ||
+    left.line - right.line ||
+    left.kind.localeCompare(right.kind) ||
+    left.specifier.localeCompare(right.specifier)
+  );
+}
+
+function collectPluginSdkImports(filePath: string, sourceFile: ts.SourceFile): ImportEntry[] {
+  const entries: ImportEntry[] = [];
+
+  function push(kind: string, specifierNode: ts.Node, specifier: string) {
+    const resolvedPath = resolveRelativeSpecifier(specifier, filePath);
+    if (!resolvedPath?.startsWith("src/plugin-sdk/")) {
+      return;
+    }
+    entries.push({
+      family: normalizePluginSdkFamily(resolvedPath),
+      file: normalizePath(filePath),
+      kind,
+      line: toLine(sourceFile, specifierNode),
+      resolvedPath,
+      specifier,
+    });
+  }
+
+  const visit = ({ kind, specifierNode, specifier }: ModuleSpecifierVisit) =>
+    push(kind, specifierNode, specifier);
+  visitModuleSpecifiers(ts, sourceFile, visit);
+  return entries;
+}
+
+async function collectCorePluginSdkImports() {
+  const files = await walkCodeFiles(srcRoot);
+  const inventory: ImportEntry[] = [];
+  for (const filePath of files) {
+    if (normalizePath(filePath).startsWith("src/plugin-sdk/")) {
+      continue;
+    }
+    const source = await fs.readFile(filePath, "utf8");
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true);
+    inventory.push(...collectPluginSdkImports(filePath, sourceFile));
+  }
+  return inventory.toSorted(compareImports);
+}
+
+function collectOptionalClusterStaticImports(
+  filePath: string,
+  sourceFile: ts.SourceFile,
+): OptionalClusterImportEntry[] {
+  const entries: OptionalClusterImportEntry[] = [];
+
+  function push(kind: string, specifierNode: ts.Node, specifier: string) {
+    if (!specifier.startsWith(".")) {
+      return;
+    }
+    const resolvedPath = resolveRelativeSpecifier(specifier, filePath);
+    if (!resolvedPath) {
+      return;
+    }
+    const cluster = resolveOptionalClusterFromPath(resolvedPath);
+    if (!cluster) {
+      return;
+    }
+    entries.push({
+      cluster,
+      file: normalizePath(filePath),
+      kind,
+      line: toLine(sourceFile, specifierNode),
+      resolvedPath,
+      specifier,
+    });
+  }
+
+  const visit = ({ kind, specifierNode, specifier }: ModuleSpecifierVisit) => {
+    if (kind !== "dynamic-import") {
+      push(kind, specifierNode, specifier);
+    }
+  };
+  visitModuleSpecifiers(ts, sourceFile, visit);
+  return entries;
+}
+
+async function collectOptionalClusterStaticLeaks() {
+  const files = await walkCodeFiles(srcRoot);
+  const inventory: OptionalClusterImportEntry[] = [];
+  for (const filePath of files) {
+    const relativePath = normalizePath(filePath);
+    if (relativePath.startsWith("src/plugin-sdk/")) {
+      continue;
+    }
+    const source = await fs.readFile(filePath, "utf8");
+    const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true);
+    inventory.push(...collectOptionalClusterStaticImports(filePath, sourceFile));
+  }
+  return inventory.toSorted((left, right) => {
+    return (
+      left.cluster.localeCompare(right.cluster) ||
+      left.file.localeCompare(right.file) ||
+      left.line - right.line ||
+      left.kind.localeCompare(right.kind) ||
+      left.specifier.localeCompare(right.specifier)
+    );
+  });
+}
+
+function buildDuplicatedSeamFamilies(inventory: ImportEntry[]) {
+  const grouped = new Map<string, ImportEntry[]>();
+  for (const entry of inventory) {
+    const bucket = grouped.get(entry.family) ?? [];
+    bucket.push(entry);
+    grouped.set(entry.family, bucket);
+  }
+
+  const duplicated = Object.fromEntries(
+    [...grouped.entries()]
+      .map(([family, entries]) => {
+        const files = [...new Set(entries.map((entry) => entry.file))].toSorted(compareStrings);
+        return [
+          family,
+          {
+            count: files.length,
+            importCount: entries.length,
+            files,
+            imports: entries,
+          },
+        ] as const;
+      })
+      .filter(([, value]) => value.files.length > 1)
+      .toSorted((left, right) => {
+        return (
+          right[1].count - left[1].count ||
+          right[1].importCount - left[1].importCount ||
+          left[0].localeCompare(right[0])
+        );
+      }),
+  );
+
+  return duplicated;
+}
+
+function buildOverlapFiles(inventory: ImportEntry[]) {
+  const byFile = new Map<string, ImportEntry[]>();
+  for (const entry of inventory) {
+    const bucket = byFile.get(entry.file) ?? [];
+    bucket.push(entry);
+    byFile.set(entry.file, bucket);
+  }
+
+  return [...byFile.entries()]
+    .map(([file, entries]) => {
+      const families = [...new Set(entries.map((entry) => entry.family))].toSorted(compareStrings);
+      return {
+        file,
+        families,
+        imports: entries,
+      };
+    })
+    .filter((entry) => entry.families.length > 1)
+    .toSorted((left, right) => {
+      return (
+        right.families.length - left.families.length ||
+        right.imports.length - left.imports.length ||
+        left.file.localeCompare(right.file)
+      );
+    });
+}
+
+function buildOptionalClusterStaticLeaks(inventory: OptionalClusterImportEntry[]) {
+  const grouped = new Map<string, OptionalClusterImportEntry[]>();
+  for (const entry of inventory) {
+    const bucket = grouped.get(entry.cluster) ?? [];
+    bucket.push(entry);
+    grouped.set(entry.cluster, bucket);
+  }
+
+  return Object.fromEntries(
+    [...grouped.entries()]
+      .map(
+        ([cluster, entries]) =>
+          [
+            cluster,
+            {
+              count: entries.length,
+              files: [...new Set(entries.map((entry) => entry.file))].toSorted(compareStrings),
+              imports: entries,
+            },
+          ] as const,
+      )
+      .toSorted((left, right) => {
+        return right[1].count - left[1].count || left[0].localeCompare(right[0]);
+      }),
+  );
+}
+
+function packageClusterMeta(relativePackagePath: string) {
+  if (relativePackagePath === "ui/package.json") {
+    return {
+      cluster: "ui",
+      packageName: "openclaw-control-ui",
+      packagePath: relativePackagePath,
+      reachability: "workspace-ui",
+    };
+  }
+  const cluster = path.basename(path.dirname(relativePackagePath));
+  return {
+    cluster,
+    packageName: null,
+    packagePath: relativePackagePath,
+    reachability: relativePackagePath.startsWith(BUNDLED_PLUGIN_PATH_PREFIX)
+      ? "extension-workspace"
+      : "workspace",
+  };
+}
+
+function classifyMissingPackageCluster(params: {
+  cluster: string;
+  pluginSdkEntries: string[];
+  hasStaticLeak: boolean;
+}) {
+  if (params.hasStaticLeak) {
+    return {
+      decision: "required",
+      reason:
+        "Cluster already appears in the static graph in this audit run, so treating it as optional would be misleading.",
+    };
+  }
+  if (optionalBundledClusterSet.has(params.cluster)) {
+    if (params.cluster === "ui") {
+      return {
+        decision: "optional",
+        reason:
+          "Private UI workspace. Repo-wide CLI/plugin CI should not require UI-only packages.",
+      };
+    }
+    if (params.pluginSdkEntries.length > 0) {
+      return {
+        decision: "optional",
+        reason:
+          "Public plugin-sdk entry exists, but repo-wide default check/build should isolate this optional cluster from the static graph.",
+      };
+    }
+    return {
+      decision: "optional",
+      reason:
+        "Workspace package is intentionally not mirrored into the root dependency set by default CI policy.",
+    };
+  }
+  return {
+    decision: "required",
+    reason:
+      "Cluster is statically visible to repo-wide check/build and has not been classified optional.",
+  };
+}
+
+async function buildMissingPackages(params: { staticLeakClusters?: Set<string> } = {}) {
+  const rootPackage: PackageJson = JSON.parse(
+    await fs.readFile(path.join(repoRoot, "package.json"), "utf8"),
+  );
+  const rootDeps = new Set([
+    ...Object.keys(rootPackage.dependencies ?? {}),
+    ...Object.keys(rootPackage.optionalDependencies ?? {}),
+    ...Object.keys(rootPackage.devDependencies ?? {}),
+  ]);
+
+  const pluginSdkEntrySources = await walkCodeFiles(path.join(repoRoot, "src", "plugin-sdk"));
+  const pluginSdkReachability = new Map<string, Set<string>>();
+  for (const filePath of pluginSdkEntrySources) {
+    const source = await fs.readFile(filePath, "utf8");
+    const matches = [...source.matchAll(/from\s+"(\.\.\/\.\.\/extensions\/([^/]+)\/[^"]+)"/g)];
+    for (const match of matches) {
+      const cluster = match[2];
+      if (!cluster) {
+        continue;
+      }
+      const bucket = pluginSdkReachability.get(cluster) ?? new Set();
+      bucket.add(normalizePath(filePath));
+      pluginSdkReachability.set(cluster, bucket);
+    }
+  }
+
+  const output = [];
+  for (const relativePackagePath of workspacePackagePaths.toSorted(compareStrings)) {
+    const packagePath = path.join(repoRoot, relativePackagePath);
+    let pkg: PackageJson;
+    try {
+      pkg = JSON.parse(await fs.readFile(packagePath, "utf8"));
+    } catch {
+      continue;
+    }
+    const missing = Object.keys(pkg.dependencies ?? {})
+      .filter((dep) => dep !== "openclaw" && !rootDeps.has(dep))
+      .toSorted(compareStrings);
+    if (missing.length === 0) {
+      continue;
+    }
+    const meta = packageClusterMeta(relativePackagePath);
+    const pluginSdkEntries = [...(pluginSdkReachability.get(meta.cluster) ?? new Set())].toSorted(
+      compareStrings,
+    );
+    const classification = classifyMissingPackageCluster({
+      cluster: meta.cluster,
+      pluginSdkEntries,
+      hasStaticLeak: params.staticLeakClusters?.has(meta.cluster) === true,
+    });
+    output.push({
+      cluster: meta.cluster,
+      decision: classification.decision,
+      decisionReason: classification.reason,
+      packageName: pkg.name ?? meta.packageName,
+      packagePath: relativePackagePath,
+      npmSpec: redactNpmSpec(pkg.openclaw?.install?.npmSpec),
+      private: pkg.private === true,
+      pluginSdkReachability:
+        pluginSdkEntries.length > 0 ? { staticEntryPoints: pluginSdkEntries } : undefined,
+      missing,
+    });
+  }
+
+  return output.toSorted((left, right) => {
+    return right.missing.length - left.missing.length || left.cluster.localeCompare(right.cluster);
+  });
+}
+
+function stemFromRelativePath(relativePath: string) {
+  return relativePath.replace(/\.(m|c)?[jt]sx?$/, "");
+}
+
+function splitNameTokens(name: string) {
+  return name
+    .split(/[^a-zA-Z0-9]+/)
+    .map((token) => token.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function hasImportSource(source: string, specifier: string, matchSuffix = false) {
+  const escaped = escapeRegExp(specifier);
+  const importSource = matchSuffix ? `(?:[^"']*/)?${escaped}` : escaped;
+  return new RegExp(
+    `from\\s+["']${importSource}["']|import\\s*\\(\\s*["']${importSource}["']\\s*\\)`,
+  ).test(source);
+}
+
+function hasAnyImportSource(source: string, specifiers: string[]) {
+  return specifiers.some((specifier) => hasImportSource(source, specifier));
+}
+
+function isCronProductionPath(relativePath: string) {
+  return relativePath.startsWith("src/cron/") && isProductionLikeFile(relativePath);
+}
+
+function isSubagentProductionPath(relativePath: string) {
+  return (
+    (relativePath.startsWith("src/agents/") || relativePath.startsWith("src/cron/")) &&
+    isProductionLikeFile(relativePath) &&
+    (/subagent|sessions-spawn|acp-spawn/.test(relativePath) ||
+      relativePath === "src/agents/tools/sessions-spawn-tool.ts" ||
+      relativePath === "src/agents/tools/subagents-tool.ts")
+  );
+}
+
+function describeCronSeamKinds(relativePath: string, source: string) {
+  if (!isCronProductionPath(relativePath)) {
+    return [];
+  }
+
+  const seamKinds = [];
+  const importsAgentRunner = hasAnyImportSource(source, [
+    "../../agents/cli-runner.js",
+    "../../agents/embedded-agent.js",
+    "../../agents/model-fallback.js",
+    "../../agents/subagent-registry.js",
+    "../../infra/agent-events.js",
+  ]);
+  const importsOutboundDelivery = hasAnyImportSource(source, [
+    "../infra/outbound/deliver.js",
+    "../../infra/outbound/deliver.js",
+    "../infra/outbound/session-context.js",
+    "../../infra/outbound/session-context.js",
+    "../infra/outbound/identity.js",
+    "../../infra/outbound/identity.js",
+    "../cli/outbound-send-deps.js",
+    "../../cli/outbound-send-deps.js",
+  ]);
+  const importsHeartbeat = hasAnyImportSource(source, [
+    "../auto-reply/heartbeat.js",
+    "../../auto-reply/heartbeat.js",
+    "../infra/heartbeat-wake.js",
+    "../../infra/heartbeat-wake.js",
+  ]);
+  const importsFollowup = hasAnyImportSource(source, [
+    "./subagent-followup.js",
+    "../../agents/subagent-registry.js",
+    "../../agents/tools/agent-step.js",
+    "../../gateway/call.js",
+  ]);
+  const importsSchedulerModules =
+    relativePath.startsWith("src/cron/service/") &&
+    hasAnyImportSource(source, [
+      "./jobs.js",
+      "./store.js",
+      "./timer.js",
+      "./state.js",
+      "../schedule.js",
+      "../store.js",
+    ]);
+
+  if (
+    importsAgentRunner &&
+    /\brunCliAgent\b|\brunEmbeddedAgent\b|\brunWithModelFallback\b|\bregisterAgentRunContext\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("cron-agent-handoff");
+  }
+
+  if (
+    importsOutboundDelivery &&
+    /\bdeliverOutboundPayloads\b|\bbuildOutboundSessionContext\b|\bresolveAgentOutboundIdentity\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("cron-outbound-delivery");
+  }
+
+  if (
+    importsHeartbeat &&
+    /\bstripHeartbeatToken\b|\bHeartbeat\b|\bheartbeat\b|\bnext-heartbeat\b/.test(source)
+  ) {
+    seamKinds.push("cron-heartbeat-handoff");
+  }
+
+  if (
+    importsSchedulerModules &&
+    /\bensureLoaded\b|\bpersist\b|\barmTimer\b|\brunMissedJobs\b|\bcomputeJobNextRunAtMs\b|\brecomputeNextRuns\b|\bnextWakeAtMs\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("cron-scheduler-state");
+  }
+
+  if (
+    importsOutboundDelivery &&
+    /\bmediaUrl\b|\bmediaUrls\b|\bfilename\b|\baudioAsVoice\b|\bdeliveryPayloads\b|\bdeliveryPayloadHasStructuredContent\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("cron-media-delivery");
+  }
+
+  if (
+    importsFollowup &&
+    /\bwaitForDescendantSubagentSummary\b|\breadDescendantSubagentFallbackReply\b|\bexpectsSubagentFollowup\b|\bcallGateway\b|\blistDescendantRunsForRequester\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("cron-followup-handoff");
+  }
+
+  return seamKinds;
+}
+
+function describeSubagentSeamKinds(relativePath: string, source: string) {
+  if (!isSubagentProductionPath(relativePath)) {
+    return [];
+  }
+
+  const seamKinds = [];
+  const isAnnounceDispatchPath =
+    relativePath === "src/agents/subagents/announce/subagent-announce.ts" ||
+    relativePath === "src/agents/subagents/announce/subagent-announce-dispatch.ts";
+  const importsSpawnRuntime = hasAnyImportSource(source, [
+    "./subagent-spawn.js",
+    "./acp-spawn.js",
+    "./subagents/spawn/subagent-spawn.js",
+    "../subagents/spawn/subagent-spawn.js",
+    "./subagents/spawn/acp-spawn.js",
+    "../subagents/spawn/acp-spawn.js",
+    "./subagent-registry.js",
+    "../subagent-registry.js",
+    "../../subagent-registry.js",
+    "../acp/control-plane/manager.js",
+    "../../../acp/control-plane/manager.js",
+  ]);
+  const importsLifecycleRegistry =
+    hasImportSource(source, "subagent-registry.js", true) ||
+    hasAnyImportSource(source, [
+      "./subagent-registry-completion.js",
+      "./subagent-registry-cleanup.js",
+      "./subagent-registry-state.js",
+      "./subagent-lifecycle-events.js",
+      "../context-engine/init.js",
+      "../context-engine/registry.js",
+      "../sessions/session-lifecycle-events.js",
+      "../../../context-engine/init.js",
+      "../../../context-engine/registry.js",
+      "../../../sessions/session-lifecycle-events.js",
+    ]);
+  const importsAnnounceDelivery = hasAnyImportSource(source, [
+    "./subagent-announce.js",
+    "./subagent-announce-dispatch.js",
+    "../announce/subagent-announce.js",
+    "../announce/subagent-announce-dispatch.js",
+    "./subagent-announce-queue.js",
+    "../infra/outbound/bound-delivery-router.js",
+    "../utils/delivery-context.shared.js",
+    "../gateway/call.js",
+    "../../../infra/outbound/bound-delivery-router.js",
+    "../../../utils/delivery-context.shared.js",
+    "../../../gateway/call.js",
+  ]);
+  const importsCleanup = hasAnyImportSource(source, [
+    "../gateway/call.js",
+    "./subagent-registry-cleanup.js",
+    "../acp/control-plane/spawn.js",
+    "../../../gateway/call.js",
+    "../../../acp/control-plane/spawn.js",
+  ]);
+  const importsParentStream = hasAnyImportSource(source, [
+    "./acp-spawn-parent-stream.js",
+    "../infra/heartbeat-wake.js",
+    "../infra/system-events.js",
+    "../infra/agent-events.js",
+    "../../../infra/heartbeat-wake.js",
+    "../../../infra/system-events.js",
+    "../../../infra/agent-events.js",
+  ]);
+
+  if (
+    importsSpawnRuntime &&
+    /\bspawnSubagentDirect\b|\bspawnAcpDirect\b|\bregisterSubagentRun\b|\bgetAcpSessionManager\b|\bspawnSubagent\b|\bspawnAcp\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("subagent-session-spawn");
+  }
+
+  if (
+    importsLifecycleRegistry &&
+    /\bemitSubagentEndedHookOnce\b|\bresolveDeferredCleanupDecision\b|\bpersistSubagentRunsToDisk\b|\brestoreSubagentRunsFromDisk\b|\bresolveContextEngine\b|\bemitSessionLifecycleEvent\b|\bcaptureSubagentCompletionReply\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("subagent-lifecycle-registry");
+  }
+
+  if (
+    (importsAnnounceDelivery || isAnnounceDispatchPath) &&
+    /\brunSubagentAnnounceFlow\b|\brunSubagentAnnounceDispatch\b|\benqueueAnnounce\b|\bcreateBoundDeliveryRouter\b|\bqueueEmbeddedAgentMessage\b|\bwaitForEmbeddedAgentRunEnd\b|\bqueue-fallback\b|\bdirect-primary\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("subagent-announce-delivery");
+  }
+
+  if (
+    importsCleanup &&
+    /\bsessions\.delete\b|\bdeleteTranscript\b|\bcleanupFailedAcpSpawn\b|\bcleanupProvisionalSession\b|\bcleanupFailedSpawnBeforeAgentStart\b|\bresolveDeferredCleanupDecision\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("subagent-session-cleanup");
+  }
+
+  if (
+    importsParentStream &&
+    /\bstartAcpSpawnParentStreamRelay\b|\brequestHeartbeatNow\b|\benqueueSystemEvent\b|\bonAgentEvent\b|\bstreamTo\b/.test(
+      source,
+    )
+  ) {
+    seamKinds.push("subagent-parent-stream");
+  }
+
+  return seamKinds;
+}
+
+export function describeSeamKinds(relativePath: string, source: string) {
+  const seamKinds = [];
+  const isReplyDeliveryPath =
+    /reply-delivery|reply-dispatcher|deliver-reply|reply\/.*delivery|monitor\/(?:replies|deliver|native-command)|outbound\/deliver|outbound\/message/.test(
+      relativePath,
+    );
+  const isChannelMediaAdapterPath =
+    (relativePath.startsWith(BUNDLED_PLUGIN_PATH_PREFIX) &&
+      /(outbound|outbound-adapter|reply-delivery|send|delivery|messenger|channel(?:\.runtime)?)\.ts$/.test(
+        relativePath,
+      )) ||
+    /^src\/channels\/plugins\/outbound\/[^/]+\.ts$/.test(relativePath);
+  if (
+    relativePath.startsWith("src/agents/tools/") &&
+    source.includes("details") &&
+    source.includes("media") &&
+    /details\s*:\s*{[\s\S]*\bmedia\b\s*:/.test(source)
+  ) {
+    seamKinds.push("tool-result-media");
+  }
+  if (
+    isReplyDeliveryPath &&
+    /\bmediaUrl\b|\bmediaUrls\b|resolveSendableOutboundReplyParts/.test(source)
+  ) {
+    seamKinds.push("reply-delivery-media");
+  }
+  if (
+    isChannelMediaAdapterPath &&
+    (/sendMedia\b/.test(source) || /\bmediaUrl\b|\bmediaUrls\b|filename|audioAsVoice/.test(source))
+  ) {
+    seamKinds.push("channel-media-adapter");
+  }
+  if (
+    isReplyDeliveryPath &&
+    /blockStreamingEnabled|directlySentBlockKeys|resolveSendableOutboundReplyParts/.test(source) &&
+    /\bmediaUrl\b|\bmediaUrls\b/.test(source)
+  ) {
+    seamKinds.push("streaming-media-handoff");
+  }
+  seamKinds.push(...describeCronSeamKinds(relativePath, source));
+  seamKinds.push(...describeSubagentSeamKinds(relativePath, source));
+  return [...new Set(seamKinds)].toSorted(compareStrings);
+}
+
+async function buildTestIndex(testFiles: string[]) {
+  return Promise.all(
+    testFiles.map(async (filePath) => {
+      const relativePath = normalizePath(filePath);
+      const stem = stemFromRelativePath(relativePath)
+        .replace(/\.test$/, "")
+        .replace(/\.spec$/, "");
+      const baseName = path.basename(stem);
+      const source = await readScannableText(filePath);
+      return {
+        filePath,
+        relativePath,
+        stem,
+        baseName,
+        source,
+      };
+    }),
+  );
+}
+
+type TestIndexEntry = Awaited<ReturnType<typeof buildTestIndex>>[number];
+
+function hasExecutableImportReference(source: string, importPath: string) {
+  const escapedImportPath = escapeRegExp(importPath);
+  const suffix = String.raw`(?:\.[^"'\\\`]+)?`;
+  const patterns = [
+    new RegExp(String.raw`\bfrom\s*["'\`]${escapedImportPath}${suffix}["'\`]`),
+    new RegExp(String.raw`\bimport\s*["'\`]${escapedImportPath}${suffix}["'\`]`),
+    new RegExp(String.raw`\brequire\s*\(\s*["'\`]${escapedImportPath}${suffix}["'\`]\s*\)`),
+    new RegExp(String.raw`\bimport\s*\(\s*["'\`]${escapedImportPath}${suffix}["'\`]\s*\)`),
+  ];
+  return patterns.some((pattern) => pattern.test(source));
+}
+
+function hasModuleMockReference(source: string, importPath: string) {
+  const escapedImportPath = escapeRegExp(importPath);
+  const suffix = String.raw`(?:\.[^"'\\\`]+)?`;
+  const patterns = [
+    new RegExp(String.raw`\bvi\.mock\s*\(\s*["'\`]${escapedImportPath}${suffix}["'\`]`),
+    new RegExp(String.raw`\bjest\.mock\s*\(\s*["'\`]${escapedImportPath}${suffix}["'\`]`),
+  ];
+  return patterns.some((pattern) => pattern.test(source));
+}
+
+const matchQualityRank = (quality: MatchQuality) => MATCH_QUALITY_RANK[quality] ?? 4;
+
+function findRelatedTests(relativePath: string, testIndex: TestIndexEntry[]): RelatedTestMatch[] {
+  const stem = stemFromRelativePath(relativePath);
+  const baseName = path.basename(stem);
+  const dirName = path.dirname(relativePath);
+  const normalizedDir = dirName.split(path.sep).join("/");
+  const baseTokens = new Set(splitNameTokens(baseName).filter((token) => token.length >= 7));
+
+  const matches: RelatedTestMatch[] = testIndex.flatMap((entry): RelatedTestMatch[] => {
+    if (entry.stem === stem) {
+      return [{ file: entry.relativePath, matchQuality: "exact-stem" }];
+    }
+    if (entry.stem.startsWith(`${stem}.`)) {
+      return [{ file: entry.relativePath, matchQuality: "path-nearby" }];
+    }
+    const entryDir = path.dirname(entry.relativePath).split(path.sep).join("/");
+    const importPath =
+      path.posix.relative(entryDir, stem) === path.basename(stem)
+        ? `./${path.basename(stem)}`
+        : path.posix.relative(entryDir, stem).startsWith(".")
+          ? path.posix.relative(entryDir, stem)
+          : `./${path.posix.relative(entryDir, stem)}`;
+    if (
+      hasExecutableImportReference(entry.source, importPath) &&
+      !hasModuleMockReference(entry.source, importPath)
+    ) {
+      return [{ file: entry.relativePath, matchQuality: "direct-import" }];
+    }
+    if (entryDir === normalizedDir && baseTokens.size > 0) {
+      const entryTokens = splitNameTokens(entry.baseName);
+      const sharedToken = entryTokens.find((token) => baseTokens.has(token));
+      if (sharedToken) {
+        return [{ file: entry.relativePath, matchQuality: "dir-token" }];
+      }
+    }
+    return [];
+  });
+
+  const byFile = new Map<string, RelatedTestMatch>();
+  for (const match of matches) {
+    const existing = byFile.get(match.file);
+    if (
+      !existing ||
+      matchQualityRank(match.matchQuality) < matchQualityRank(existing.matchQuality)
+    ) {
+      byFile.set(match.file, match);
+    }
+  }
+
+  return [...byFile.values()].toSorted((left, right) => {
+    return (
+      matchQualityRank(left.matchQuality) - matchQualityRank(right.matchQuality) ||
+      left.file.localeCompare(right.file)
+    );
+  });
+}
+
+export function determineSeamTestStatus(
+  seamKinds: string[],
+  relatedTestMatches: RelatedTestMatch[],
+) {
+  if (relatedTestMatches.length === 0) {
+    return {
+      status: "gap",
+      reason: "No nearby test file references this seam candidate.",
+    };
+  }
+
+  const bestMatch = relatedTestMatches[0]?.matchQuality ?? "unknown";
+  if (
+    seamKinds.includes("reply-delivery-media") ||
+    seamKinds.includes("streaming-media-handoff") ||
+    seamKinds.includes("tool-result-media") ||
+    seamKinds.includes("cron-agent-handoff") ||
+    seamKinds.includes("cron-outbound-delivery") ||
+    seamKinds.includes("cron-heartbeat-handoff") ||
+    seamKinds.includes("cron-scheduler-state") ||
+    seamKinds.includes("cron-media-delivery") ||
+    seamKinds.includes("cron-followup-handoff") ||
+    seamKinds.includes("subagent-session-spawn") ||
+    seamKinds.includes("subagent-lifecycle-registry") ||
+    seamKinds.includes("subagent-announce-delivery") ||
+    seamKinds.includes("subagent-session-cleanup") ||
+    seamKinds.includes("subagent-parent-stream")
+  ) {
+    return {
+      status: "partial",
+      reason: `Nearby tests exist (best match: ${bestMatch}), but this inventory does not prove cross-layer seam coverage end to end.`,
+    };
+  }
+  return {
+    status: "heuristic-nearby",
+    reason: `Nearby tests exist (best match: ${bestMatch}), but this remains a filename/path heuristic rather than proof of seam assertions.`,
+  };
+}
+
+async function buildSeamTestInventory() {
+  const productionFiles = [
+    ...(await walkCodeFiles(srcRoot)),
+    ...(await walkCodeFiles(extensionsRoot)),
+  ].toSorted((left, right) => normalizePath(left).localeCompare(normalizePath(right)));
+  const testFiles = [
+    ...(await walkAllCodeFiles(srcRoot, { includeTests: true })),
+    ...(await walkAllCodeFiles(extensionsRoot, { includeTests: true })),
+    ...(await walkAllCodeFiles(testRoot, { includeTests: true })),
+  ]
+    .filter((filePath) => /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.test(filePath))
+    .toSorted((left, right) => normalizePath(left).localeCompare(normalizePath(right)));
+  const testIndex = await buildTestIndex(testFiles);
+  const inventory = [];
+
+  for (const filePath of productionFiles) {
+    const relativePath = normalizePath(filePath);
+    const source = await readScannableText(filePath);
+    const seamKinds = describeSeamKinds(relativePath, source);
+    if (seamKinds.length === 0) {
+      continue;
+    }
+    const relatedTestMatches = findRelatedTests(relativePath, testIndex);
+    const status = determineSeamTestStatus(seamKinds, relatedTestMatches);
+    inventory.push({
+      file: relativePath,
+      seamKinds,
+      relatedTests: relatedTestMatches.map((entry) => entry.file),
+      relatedTestMatches,
+      status: status.status,
+      reason: status.reason,
+    });
+  }
+
+  return inventory.toSorted((left, right) => {
+    return (
+      left.status.localeCompare(right.status) ||
+      left.file.localeCompare(right.file) ||
+      left.seamKinds.join(",").localeCompare(right.seamKinds.join(","))
+    );
+  });
+}
+
+export async function main(argv: string[] = process.argv.slice(2)) {
+  const args = new Set(argv);
+  if (args.has("--help") || args.has("-h")) {
+    process.stdout.write(`${HELP_TEXT}\n`);
+    return;
+  }
+
+  await collectWorkspacePackagePaths();
+  const inventory = await collectCorePluginSdkImports();
+  const optionalClusterStaticLeaks = await collectOptionalClusterStaticLeaks();
+  const staticLeakClusters = new Set(optionalClusterStaticLeaks.map((entry) => entry.cluster));
+  const result = {
+    duplicatedSeamFamilies: buildDuplicatedSeamFamilies(inventory),
+    overlapFiles: buildOverlapFiles(inventory),
+    optionalClusterStaticLeaks: buildOptionalClusterStaticLeaks(optionalClusterStaticLeaks),
+    missingPackages: await buildMissingPackages({ staticLeakClusters }),
+    seamTestInventory: await buildSeamTestInventory(),
+  };
+
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+const entryFilePath = process.argv[1] ? path.resolve(process.argv[1]) : null;
+if (entryFilePath === fileURLToPath(import.meta.url)) {
+  await main();
+}

scripts/authorized-beta-focused-policy.json

@@ -0,0 +1,77 @@
+{
+  "schema": "openclaw.authorized-beta-focused-policy.v1",
+  "mode": "authorized-beta-focused-v1",
+  "releaseTag": "v2026.8.1-beta.3",
+  "releaseVersion": "2026.8.1-beta.3",
+  "baseCandidateSha": "3203a6f7f8d79644fde2b4f091a694f4c1698538",
+  "candidateSha": "3fbe94065c2b94f4c08acb6742a69938bf408d94",
+  "reviewedHeadSha": "e347223a5858bda5907acda858404e5f7a4c3720",
+  "candidateTreeSha": "71fb83bcab002be3da4057e7cffacf77d4cdbd2d",
+  "baseTreeSha": "10d1f3ab0ff52383c025c5846427e0dd5d14598a",
+  "packageProjectionSha256": "d1d8f60b8a14aeb567a0d5215a6b0265c74a07ebea04b288e43c31cba473bbca",
+  "eligibilityPlanDigest": "sha256:e05226cfd77716b262882b3e2525037a506cd8b6af2affa0a876499074b1671b",
+  "historicalToolingSha": "eed27fdb88c0c60cb79c5b159a0284bd519271c2",
+  "historicalToolingRef": "refs/tags/release-publish/eed27fdb88c0-1787493831",
+  "historicalFrv": {
+    "runId": "32644377679",
+    "runAttempt": 1,
+    "workflowPath": ".github/workflows/full-release-validation.yml",
+    "workflowRef": "release-ci/eed27fdb88c0-1787493942617",
+    "targetSha": "3203a6f7f8d79644fde2b4f091a694f4c1698538",
+    "ciRunId": "32644407381",
+    "ciFailedJobId": "97206458686",
+    "ciAggregateJobId": "97216945772",
+    "pluginRunId": "32645134710",
+    "pluginFailedJobId": "97208293666",
+    "pluginAggregateJobId": "97210400113",
+    "releaseChecksRunId": "32645133620",
+    "releaseChecksVerifierJobId": "97211299203",
+    "performanceRunId": "32644407718",
+    "performanceFailedJobId": "97206336416"
+  },
+  "focusedProof": {
+    "ciRunId": "32664685168",
+    "ciTargetLogJobId": "97256163016",
+    "ciSuccessJobId": "97256296219",
+    "pluginRunId": "32664686635",
+    "pluginTargetLogJobId": "97256164326",
+    "pluginSuccessJobId": "97256329353"
+  },
+  "changedPaths": [
+    {
+      "path": "extensions/slack/src/monitor.test-helpers.ts",
+      "status": "M",
+      "added": 12,
+      "deleted": 18
+    },
+    {
+      "path": "extensions/slack/src/monitor/provider.auth-test-token.test.ts",
+      "status": "M",
+      "added": 10,
+      "deleted": 569
+    },
+    {
+      "path": "extensions/slack/src/monitor/provider.event-identity-recovery.test.ts",
+      "status": "D",
+      "added": 0,
+      "deleted": 155
+    },
+    {
+      "path": "extensions/slack/src/monitor/provider.identity.test.ts",
+      "status": "A",
+      "added": 658,
+      "deleted": 0
+    }
+  ],
+  "inventory": {
+    "npmCount": 93,
+    "npmNamesSha256": "778eb6aeb324c02942e17755557ff9d5055376fb4d39096a60022f0ae75d67f3",
+    "clawHubCount": 89,
+    "clawHubNamesSha256": "1b161a4fde3c003e23db306d4a86908086caac1cd33e75feeaf27474366c1c2b",
+    "trustedPublisherCount": 75,
+    "trustedPublisherNamesSha256": "4266416f20fe5c8b7a4ce732121a2206fc8cfa6af25deae0aec70d552ceb5df8",
+    "bootstrapCount": 14,
+    "bootstrapNamesSha256": "83c79c6099d12dc2ebb58e2fc5ca8e078776dfa21b50dee741bac6aed5526eef",
+    "missingTrustedPublisherCount": 0
+  }
+}

scripts/bench-agent-concurrency-worker.ts

@@ -0,0 +1,836 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { pathToFileURL } from "node:url";
+import { toErrorObject } from "@openclaw/normalization-core/error-coercion";
+import type { SubagentRunRecord } from "../src/agents/subagents/registry/subagent-registry.types.js";
+import type { DB as OpenClawStateKyselyDatabase } from "../src/state/openclaw-state-db.generated.js";
+import {
+  WORKER_RESULT_SENTINEL,
+  type WorkerResult,
+  type WorkerScenario,
+} from "./bench-agent-concurrency.js";
+import { classifyBoundedUnsignedDecimal } from "./lib/arg-utils.mts";
+
+type WorkerOptions = {
+  scenario: WorkerScenario;
+  size: number;
+  runs: number;
+  warmup: number;
+};
+
+type Sample = {
+  durationMs: number;
+  invariant: Record<string, number | boolean>;
+};
+
+const SCENARIOS = new Set<WorkerScenario>([
+  "spawnPipelineInMemory",
+  "spawnPipelineDurable",
+  "admission",
+  "recoverySweep",
+  "duplicateSuppression",
+]);
+
+function parseInteger(raw: string | undefined, flag: string, min: number, max: number): number {
+  const result = classifyBoundedUnsignedDecimal(raw, min, max);
+  if (result.kind === "syntax") {
+    throw new Error(`${flag} must be an integer`);
+  }
+  if (result.kind !== "value") {
+    throw new Error(`${flag} must be between ${min} and ${max}`);
+  }
+  return result.value;
+}
+
+function parseOptions(argv: string[]): WorkerOptions {
+  const values = new Map<string, string>();
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (!flag?.startsWith("--") || !value || value.startsWith("--")) {
+      throw new Error(`invalid worker argument near ${flag ?? "end"}`);
+    }
+    if (values.has(flag)) {
+      throw new Error(`${flag} was provided more than once`);
+    }
+    values.set(flag, value);
+  }
+  const scenario = values.get("--scenario") as WorkerScenario | undefined;
+  if (!scenario || !SCENARIOS.has(scenario)) {
+    throw new Error(`unknown worker scenario: ${scenario ?? "missing"}`);
+  }
+  return {
+    scenario,
+    size: parseInteger(values.get("--size"), "--size", 1, 4096),
+    runs: parseInteger(values.get("--runs"), "--runs", 1, 100),
+    warmup: parseInteger(values.get("--warmup"), "--warmup", 0, 20),
+  };
+}
+
+function processMaxRssBytes(): number {
+  return Math.max(0, Math.round(process.resourceUsage().maxRSS * 1024));
+}
+
+async function waitForCondition(check: () => boolean): Promise<boolean> {
+  const deadline = Date.now() + 30_000;
+  while (Date.now() < deadline) {
+    if (check()) {
+      return true;
+    }
+    await new Promise<void>((resolve) => {
+      setImmediate(resolve);
+    });
+  }
+  return check();
+}
+
+async function drainSpawnSampleActiveWork(
+  waitForActiveWork?: (
+    timeoutMs: number,
+  ) => Promise<{ drained: boolean; snapshot: { counts: { totalActive: number } } }>,
+): Promise<void> {
+  const wait =
+    waitForActiveWork ??
+    (await import("../src/infra/gateway-active-work.js")).waitForGatewayActiveWork;
+  const result = await wait(30_000);
+  const active = result.snapshot.counts.totalActive;
+  if (!result.drained || active !== 0) {
+    throw new Error(`spawn sample left ${active} active gateway work items`);
+  }
+}
+
+async function resetRuntime(persist: boolean): Promise<void> {
+  const [subagents, tasks, stateDb, agentDb] = await Promise.all([
+    import("../src/agents/subagents/registry/subagent-registry.test-helpers.js"),
+    import("../src/tasks/task-runtime.test-helpers.js"),
+    import("../src/state/openclaw-state-db.js"),
+    import("../src/state/openclaw-agent-db.js"),
+  ]);
+  subagents.resetSubagentRegistryForTests({ persist });
+  subagents.testing.setDepsForTest();
+  tasks.resetTaskRegistryControlRuntimeForTests();
+  tasks.resetTaskRegistryDeliveryRuntimeForTests();
+  tasks.resetDetachedTaskLifecycleRuntimeForTests();
+  tasks.resetTaskRegistryForTests({ persist });
+  tasks.resetTaskFlowRegistryForTests({ persist });
+  stateDb.closeOpenClawStateDatabaseForTest();
+  agentDb.closeOpenClawAgentDatabasesForTest();
+}
+
+function createTerminalWaitBarrier() {
+  const waiters = new Map<string, (value: unknown) => void>();
+  let outstanding = 0;
+  let releasesStarted = false;
+  const callGateway = (async <T>(request: { method?: string; params?: unknown }) => {
+    if (request.method !== "agent.wait") {
+      return {} as T;
+    }
+    if (releasesStarted) {
+      throw new Error("agent.wait registered after the benchmark barrier released");
+    }
+    const runId =
+      request.params &&
+      typeof request.params === "object" &&
+      !Array.isArray(request.params) &&
+      typeof (request.params as { runId?: unknown }).runId === "string"
+        ? (request.params as { runId: string }).runId
+        : undefined;
+    if (!runId || waiters.has(runId)) {
+      throw new Error(`invalid or duplicate benchmark agent.wait run id: ${runId ?? "missing"}`);
+    }
+    outstanding += 1;
+    return await new Promise<T>((resolve) => {
+      waiters.set(runId, (value) => {
+        outstanding -= 1;
+        resolve(value as T);
+      });
+    });
+  }) as typeof import("../src/gateway/call.js").callGateway;
+  return {
+    callGateway,
+    get outstanding() {
+      return outstanding;
+    },
+    async waitUntilBlocked(expected: number) {
+      return await waitForCondition(() => outstanding === expected);
+    },
+    release(runId: string) {
+      releasesStarted = true;
+      const resolve = waiters.get(runId);
+      if (!resolve) {
+        throw new Error(`missing blocked benchmark agent.wait for ${runId}`);
+      }
+      waiters.delete(runId);
+      const endedAt = Date.now();
+      resolve({
+        status: "ok",
+        startedAt: endedAt - 1,
+        endedAt,
+        stopReason: "stop",
+      });
+    },
+    releaseAll() {
+      releasesStarted = true;
+      for (const runId of waiters.keys()) {
+        this.release(runId);
+      }
+    },
+  };
+}
+
+async function configureSpawnRuntime(
+  mode: "memory" | "durable",
+  callGateway: typeof import("../src/gateway/call.js").callGateway,
+): Promise<void> {
+  const [subagents, registry, taskStore, flowStore] = await Promise.all([
+    import("../src/agents/subagents/registry/subagent-registry.test-helpers.js"),
+    import("../src/agents/subagents/registry/subagent-registry-memory.js"),
+    import("../src/tasks/task-registry.store.js"),
+    import("../src/tasks/task-flow-registry.store.test-support.js"),
+  ]);
+  const sharedDeps = {
+    callGateway,
+    getRuntimeConfig: () => ({}),
+    onAgentEvent: () => () => {},
+    resolveAgentTimeoutMs: () => 1_000,
+    captureSubagentCompletionReply: async (childSessionKey: string) => {
+      const entry = [...registry.subagentRuns.values()].find(
+        (candidate) => candidate.childSessionKey === childSessionKey,
+      );
+      if (entry) {
+        // Completion already owns the row at this awaited seam. Suppress only
+        // its unrelated session projection, not the terminal registry/task transition.
+        entry.execution.suppressSessionEffects = true;
+      }
+      return undefined;
+    },
+    cleanupBrowserSessionsForLifecycleEnd: async () => {},
+    runSubagentAnnounceFlow: async () => "retryable" as const,
+    maybeWakeRequesterAfterAllChildrenSettled: async () => false,
+    ensureContextEnginesInitialized: () => {},
+    loadAgentRuntimePluginRegistryHandle: () => undefined,
+    resolveContextEngine: async () =>
+      ({
+        info: { id: "bench", name: "bench", version: "1" },
+        ingest: async () => ({ ok: true }),
+        assemble: async () => ({ messages: [] }),
+        onSubagentEnded: async () => {},
+      }) as unknown as import("../src/context-engine/types.js").ContextEngine,
+  };
+  if (mode === "memory") {
+    subagents.testing.setDepsForTest({
+      ...sharedDeps,
+      persistSubagentRunsToDisk: () => {},
+      persistSubagentRunsToDiskOrThrow: () => {},
+    });
+    taskStore.configureTaskRegistryRuntime({
+      store: {
+        loadSnapshot: () => ({ tasks: new Map(), deliveryStates: new Map() }),
+        upsertTaskWithDeliveryState: () => {},
+        deleteTaskWithDeliveryState: () => {},
+        upsertDeliveryState: () => {},
+        close: () => {},
+      },
+    });
+    const { createInMemoryTaskFlowRegistryStore } =
+      await import("../src/test-utils/task-registry-store.js");
+    flowStore.configureTaskFlowRegistryRuntime({
+      store: createInMemoryTaskFlowRegistryStore(),
+    });
+    return;
+  }
+  subagents.testing.setDepsForTest(sharedDeps);
+}
+
+type BenchmarkStateDatabase = Pick<OpenClawStateKyselyDatabase, "subagent_runs" | "task_runs">;
+
+async function readDurableRows() {
+  const [{ executeSqliteQuerySync, getNodeSqliteKysely }, stateDb] = await Promise.all([
+    import("../src/infra/kysely-sync.js"),
+    import("../src/state/openclaw-state-db.js"),
+  ]);
+  const database = stateDb.openOpenClawStateDatabase();
+  const db = getNodeSqliteKysely<BenchmarkStateDatabase>(database.db);
+  return {
+    path: database.path,
+    subagentRows: executeSqliteQuerySync(
+      database.db,
+      db
+        .selectFrom("subagent_runs")
+        .select((eb) => [
+          "run_id",
+          eb
+            .fn<number | null>("json_extract", ["payload_json", eb.val("$.execution.endedAt")])
+            .as("ended_at"),
+        ])
+        .orderBy("run_id"),
+    ).rows,
+    taskRows: executeSqliteQuerySync(
+      database.db,
+      db
+        .selectFrom("task_runs")
+        .select(["run_id", "status", "ended_at"])
+        .where("runtime", "=", "subagent")
+        .orderBy("run_id"),
+    ).rows,
+  };
+}
+
+function listSqliteFiles(root: string): string[] {
+  return fs
+    .readdirSync(root, { recursive: true })
+    .map(String)
+    .filter((entry) => entry.includes(".sqlite"))
+    .toSorted();
+}
+
+async function listBenchmarkTasks() {
+  const tasks = await import("../src/tasks/task-registry.js");
+  return tasks.listTaskRecords().filter((task) => task.runtime === "subagent");
+}
+
+async function listBenchmarkTaskMemory() {
+  const state = await import("../src/tasks/task-registry-state.js");
+  return [...state.tasks.values()].filter((task) => task.runtime === "subagent");
+}
+
+function assertExactRunIds(actual: Array<string | null>, expected: string[], label: string): void {
+  const normalized = actual
+    .filter((value): value is string => typeof value === "string")
+    .toSorted();
+  const wanted = expected.toSorted();
+  if (JSON.stringify(normalized) !== JSON.stringify(wanted)) {
+    throw new Error(
+      `${label} mismatch: ${JSON.stringify({ actual: normalized, expected: wanted })}`,
+    );
+  }
+}
+
+async function runSpawnSample(
+  fanout: number,
+  serial: number,
+  mode: "memory" | "durable",
+  stateDir: string,
+): Promise<Sample> {
+  const [pipeline, registry] = await Promise.all([
+    import("../src/agents/spawn-pipeline.js"),
+    import("../src/agents/subagents/registry/subagent-registry-memory.js"),
+  ]);
+  await resetRuntime(mode === "durable");
+  const barrier = createTerminalWaitBarrier();
+  await configureSpawnRuntime(mode, barrier.callGateway);
+  const taskRegistry = await import("../src/tasks/task-registry.js");
+  let releases = 0;
+  const runIds: string[] = [];
+  const params = Array.from({ length: fanout }, (_, index) => {
+    const runId = `bench-${mode}-${serial}-${index}`;
+    runIds.push(runId);
+    let released = false;
+    return {
+      adapter: {
+        initialize: async () => ({ index }),
+        dispatchTurn: async () => ({ runId }),
+        cleanupOnFailure: async () => {},
+      },
+      admissionReservation: {
+        release: () => {
+          if (!released) {
+            released = true;
+            releases += 1;
+          }
+        },
+      },
+      buildRegistration: () => ({
+        runId,
+        childSessionKey: `agent:bench:subagent:${mode}:${serial}:${index}`,
+        requesterSessionKey: "agent:bench:main",
+        requesterDisplayKey: "bench",
+        task: `benchmark child ${index}`,
+        cleanup: "keep" as const,
+        expectsCompletionMessage: false,
+      }),
+      progressSessionKey: "agent:bench:main",
+    };
+  });
+  let result: Sample | undefined;
+  let failure: unknown;
+  try {
+    const startedAt = performance.now();
+    const pipelineResults = await Promise.all(
+      params.map((entry) => pipeline.runSpawnPipeline(entry)),
+    );
+    const durationMs = performance.now() - startedAt;
+    const blocked = await barrier.waitUntilBlocked(fanout);
+    const successful = pipelineResults.filter((pipelineResult) => pipelineResult.ok);
+    const uniqueRuns = new Set(successful.map((pipelineResult) => pipelineResult.runId)).size;
+    const registeredRuns = registry.subagentRuns.size;
+    const tasksWhileBlocked = await listBenchmarkTasks();
+    assertExactRunIds(
+      tasksWhileBlocked.map((task) => task.runId ?? null),
+      runIds,
+      `${mode} in-memory task rows`,
+    );
+    if (!blocked || barrier.outstanding !== fanout) {
+      throw new Error(`spawn ${mode} did not block ${fanout} agent.wait calls`);
+    }
+    if (
+      successful.length !== fanout ||
+      uniqueRuns !== fanout ||
+      registeredRuns !== fanout ||
+      releases !== fanout
+    ) {
+      throw new Error(
+        `spawn ${mode} registration invariant failed: ${JSON.stringify({ fanout, uniqueRuns, registeredRuns, releases })}`,
+      );
+    }
+    let durableSubagentRows = 0;
+    let durableTaskRows = 0;
+    let durableStateFile = listSqliteFiles(stateDir).length > 0;
+    if (mode === "durable") {
+      const durable = await readDurableRows();
+      assertExactRunIds(
+        durable.subagentRows.map((row) => row.run_id),
+        runIds,
+        "durable subagent rows",
+      );
+      assertExactRunIds(
+        durable.taskRows.map((row) => row.run_id),
+        runIds,
+        "durable task rows",
+      );
+      if (
+        durable.subagentRows.some((row) => row.ended_at !== null) ||
+        durable.taskRows.some((row) => row.status !== "running" || row.ended_at !== null)
+      ) {
+        throw new Error("durable rows settled before the benchmark barrier released");
+      }
+      durableSubagentRows = durable.subagentRows.length;
+      durableTaskRows = durable.taskRows.length;
+      durableStateFile = fs.existsSync(durable.path);
+      if (!durableStateFile) {
+        throw new Error(`durable spawn pipeline database is missing at ${durable.path}`);
+      }
+    } else if (durableStateFile) {
+      throw new Error("in-memory spawn pipeline created durable SQLite state");
+    }
+    for (const runId of runIds) {
+      barrier.release(runId);
+      const runSettled = await waitForCondition(() => {
+        const run = registry.subagentRuns.get(runId);
+        const task = taskRegistry.findTaskByRunId(runId);
+        return (
+          run?.execution.status === "terminal" &&
+          typeof run.execution.endedAt === "number" &&
+          typeof run.cleanupCompletedAt === "number" &&
+          task?.status === "succeeded"
+        );
+      });
+      if (!runSettled) {
+        throw new Error(`spawn ${mode} did not settle released run ${runId}`);
+      }
+    }
+    const settledTasks = await listBenchmarkTasks();
+    const settledRuns = [...registry.subagentRuns.values()].filter(
+      (entry) =>
+        entry.execution.status === "terminal" &&
+        typeof entry.execution.endedAt === "number" &&
+        typeof entry.cleanupCompletedAt === "number",
+    ).length;
+    const succeededTasks = settledTasks.filter((task) => task.status === "succeeded").length;
+    if (settledRuns !== fanout || succeededTasks !== fanout || barrier.outstanding !== 0) {
+      throw new Error(
+        `spawn ${mode} settlement invariant failed: ${JSON.stringify({ fanout, settledRuns, succeededTasks, outstandingWaits: barrier.outstanding })}`,
+      );
+    }
+    // Terminal rows can settle before detached cleanup and requester-wake roots.
+    // Drain before reset so leaked work stays visible and cannot reach the next sample.
+    await drainSpawnSampleActiveWork();
+    result = {
+      durationMs,
+      invariant: {
+        ok: true,
+        registeredRuns,
+        reservationsReleased: releases,
+        blockedWaits: fanout,
+        settledRuns,
+        settledTasks: succeededTasks,
+        outstandingWaits: barrier.outstanding,
+        durableSubagentRows,
+        durableTaskRows,
+        durableStateFile,
+        postTeardownRegistryRows: -1,
+        postTeardownTaskRows: -1,
+        postTeardownDurableSubagentRows: -1,
+        postTeardownDurableTaskRows: -1,
+        postTeardownActiveRootWork: 0,
+      },
+    };
+  } catch (error) {
+    failure = error;
+  } finally {
+    try {
+      barrier.releaseAll();
+    } catch (error) {
+      failure ??= error;
+    }
+    try {
+      await resetRuntime(mode === "durable");
+    } catch (error) {
+      failure ??= error;
+    }
+  }
+  if (failure) {
+    throw toErrorObject(failure, "Agent concurrency benchmark failed");
+  }
+  const postTeardownTasks = await listBenchmarkTaskMemory();
+  const postTeardownRegistryRows = registry.subagentRuns.size;
+  const postTeardownTaskRows = postTeardownTasks.length;
+  let postTeardownDurableSubagentRows = 0;
+  let postTeardownDurableTaskRows = 0;
+  if (mode === "durable") {
+    const durable = await readDurableRows();
+    postTeardownDurableSubagentRows = durable.subagentRows.length;
+    postTeardownDurableTaskRows = durable.taskRows.length;
+    await resetRuntime(false);
+  }
+  if (
+    postTeardownRegistryRows !== 0 ||
+    postTeardownTaskRows !== 0 ||
+    postTeardownDurableSubagentRows !== 0 ||
+    postTeardownDurableTaskRows !== 0 ||
+    barrier.outstanding !== 0
+  ) {
+    throw new Error(
+      `spawn ${mode} teardown invariant failed: ${JSON.stringify({ postTeardownRegistryRows, postTeardownTaskRows, postTeardownDurableSubagentRows, postTeardownDurableTaskRows, outstandingWaits: barrier.outstanding })}`,
+    );
+  }
+  if (mode === "memory" && listSqliteFiles(stateDir).length > 0) {
+    throw new Error("in-memory spawn pipeline created SQLite state during teardown");
+  }
+  if (!result) {
+    throw new Error(`spawn ${mode} did not produce a benchmark result`);
+  }
+  result.invariant.postTeardownRegistryRows = postTeardownRegistryRows;
+  result.invariant.postTeardownTaskRows = postTeardownTaskRows;
+  result.invariant.postTeardownDurableSubagentRows = postTeardownDurableSubagentRows;
+  result.invariant.postTeardownDurableTaskRows = postTeardownDurableTaskRows;
+  return result;
+}
+
+async function runAdmissionSample(fanout: number, serial: number): Promise<Sample> {
+  const { reserveChildAdmissionSlot } = await import("../src/agents/child-admission.js");
+  const controllerSessionKey = `agent:bench:admission:${serial}`;
+  const reservations: Array<{ release: () => void }> = [];
+  const reserve = () =>
+    reserveChildAdmissionSlot({
+      controllerSessionKey,
+      resolveAdmission: (pendingChildren) =>
+        pendingChildren < fanout
+          ? { ok: true as const }
+          : { ok: false as const, governingCap: "benchmark" },
+    });
+  const startedAt = performance.now();
+  for (let index = 0; index < fanout; index += 1) {
+    const reservation = reserve();
+    if (!reservation.ok) {
+      throw new Error(`admission rejected slot ${index + 1}/${fanout}`);
+    }
+    reservations.push(reservation);
+  }
+  const overflow = reserve();
+  for (const reservation of reservations) {
+    reservation.release();
+    reservation.release();
+  }
+  const replacement = reserve();
+  if (replacement.ok) {
+    replacement.release();
+  }
+  const durationMs = performance.now() - startedAt;
+  const ok = !overflow.ok && replacement.ok;
+  if (!ok) {
+    throw new Error(`admission invariant failed at fanout ${fanout}`);
+  }
+  return {
+    durationMs,
+    invariant: { ok, admissionCap: reservations.length, overflowRejected: true, released: true },
+  };
+}
+
+function sweepRow(child: number, generation: number, now: number): SubagentRunRecord {
+  const current = generation === 3;
+  return {
+    runId: `bench-sweep-${child}-${generation}`,
+    childSessionKey: `agent:bench:subagent:sweep-${child}`,
+    requesterSessionKey: "agent:bench:main",
+    requesterDisplayKey: "bench",
+    task: `sweep child ${child}`,
+    cleanup: current ? "keep" : "delete",
+    generation,
+    createdAt: now - generation,
+    archiveAtMs: current ? undefined : now - 1,
+    terminalOwner: current ? "interrupted-recovery" : undefined,
+    endedReason: current ? "subagent-error" : undefined,
+    execution: current
+      ? {
+          status: "terminal",
+          startedAt: now - 2_000,
+          endedAt: now - 1_000,
+          outcome: { status: "error", error: "interrupted recovery replay" },
+          suppressSessionEffects: true,
+        }
+      : {
+          status: "terminal",
+          startedAt: now - 2_000,
+          endedAt: now - 1_000,
+          outcome: { status: "error", error: "retired recovery generation" },
+          suppressSessionEffects: true,
+        },
+  };
+}
+
+async function runSweepSample(childCount: number): Promise<Sample> {
+  const [
+    { getSubagentRunsForChildSession, subagentRuns: runs },
+    { createSubagentRegistrySweeper },
+  ] = await Promise.all([
+    import("../src/agents/subagents/registry/subagent-registry-memory.js"),
+    import("../src/agents/subagents/registry/subagent-registry-sweeper.js"),
+  ]);
+  const now = Date.now();
+  runs.clear();
+  for (let child = 0; child < childCount; child += 1) {
+    for (const generation of [3, 2, 1]) {
+      const entry = sweepRow(child, generation, now);
+      runs.set(entry.runId, entry);
+    }
+  }
+  let sessionEffects = 0;
+  let recoveryProjections = 0;
+  let lostContextCompletions = 0;
+  const sweeper = createSubagentRegistrySweeper({
+    runs,
+    resumedRuns: new Set(),
+    persist: () => {},
+    clearPendingLifecycleError: () => {},
+    clearPendingLifecycleTimeout: () => {},
+    clearPendingSubagentRecoveryNotice: () => true,
+    sweepPendingLifecycle: () => {},
+    completeSubagentRunWithRecovery: async () => {
+      lostContextCompletions += 1;
+    },
+    getGatewayRecoveryRuntime: () => undefined,
+    abandonSubagentRestartRecoveryLaunch: () => true,
+    clearAcceptedSubagentRestartRecovery: () => true,
+    resumeSettledSubagentRestartRecovery: () => true,
+    replaceSubagentRunAfterSteer: () => true,
+    markSubagentRestartRecoveryLaunchAttempted: () => undefined,
+    markSubagentRestartRecoveryLaunchAccepted: () => undefined,
+    markSubagentRestartRecoveryLaunchConsumed: () => undefined,
+    reserveSubagentRestartRecoveryLaunch: () => undefined,
+    resetSubagentRestartRecoveryLaunchAttempt: () => true,
+    finalizeInterruptedSubagentRun: async ({ runId, expectedEntry }) => {
+      if (runs.get(runId) !== expectedEntry || expectedEntry?.generation !== 3) {
+        throw new Error(`unexpected recovery projection owner: ${runId}`);
+      }
+      recoveryProjections += 1;
+      return 1;
+    },
+    resumeRequesterSettleWake: () => {},
+    startSubagentAnnounceCleanupFlow: () => true,
+    completeCleanupBookkeeping: () => {},
+    discardTerminalDelivery: () => {},
+    shouldEmitEndedHookForRun: () => false,
+    emitSubagentEndedHookForRun: async () => {},
+    callGateway: (async <T>() => {
+      sessionEffects += 1;
+      return {} as T;
+    }) as typeof import("../src/gateway/call.js").callGateway,
+    cleanupCollectorLaunchResources: async () => true,
+    runContextEngineSubagentEnded: async () => {
+      sessionEffects += 1;
+    },
+    notifyContextEngineSubagentEnded: async () => {
+      sessionEffects += 1;
+    },
+    retireSupersededRun: async () => {},
+    getRunsForChildSession: getSubagentRunsForChildSession,
+    getRunsForCollectorGroup: () => [],
+    warn: () => {},
+  });
+  try {
+    const startedAt = performance.now();
+    await sweeper.sweepOnce();
+    const durationMs = performance.now() - startedAt;
+    const retainedCurrent = [...runs.values()].filter((entry) => entry.generation === 3).length;
+    const removedRows = childCount * 3 - runs.size;
+    const ok =
+      removedRows === childCount * 2 &&
+      retainedCurrent === childCount &&
+      sessionEffects === 0 &&
+      recoveryProjections === childCount &&
+      lostContextCompletions === 0;
+    if (!ok) {
+      throw new Error(
+        `registry sweep invariant failed: ${JSON.stringify({ childCount, removedRows, retainedCurrent, sessionEffects, recoveryProjections, lostContextCompletions })}`,
+      );
+    }
+    return {
+      durationMs,
+      invariant: {
+        ok,
+        seededRows: childCount * 3,
+        removedRows,
+        retainedCurrent,
+        sessionEffects,
+        recoveryProjections,
+        lostContextCompletions,
+      },
+    };
+  } finally {
+    sweeper.reset();
+    runs.clear();
+  }
+}
+
+async function runDedupeSample(childCount: number): Promise<Sample> {
+  const { dedupeLatestChildCompletionRows } =
+    await import("../src/agents/subagents/announce/subagent-announce-output.js");
+  const rowsForOrder = (generations: number[]) =>
+    Array.from({ length: childCount }, (_, child) =>
+      generations.map((generation) => ({
+        runId: `bench-dedupe-${child}-${generation}`,
+        childSessionKey: `agent:bench:subagent:dedupe-${child}`,
+        task: `dedupe child ${child}`,
+        generation,
+        createdAt: generation,
+        execution: { status: "terminal" as const, endedAt: generation },
+      })),
+    ).flat();
+  const newestFirstRows = rowsForOrder([3, 2, 1]);
+  const oldestFirstRows = rowsForOrder([1, 2, 3]);
+  const startedAt = performance.now();
+  const newestFirst = dedupeLatestChildCompletionRows(newestFirstRows);
+  const oldestFirst = dedupeLatestChildCompletionRows(oldestFirstRows);
+  const durationMs = performance.now() - startedAt;
+  const newestFirstSelectedNewest = newestFirst.every((row) => row.generation === 3);
+  const oldestFirstSelectedNewest = oldestFirst.every((row) => row.generation === 3);
+  const ok =
+    newestFirst.length === childCount &&
+    oldestFirst.length === childCount &&
+    newestFirstSelectedNewest &&
+    oldestFirstSelectedNewest;
+  if (!ok) {
+    throw new Error(`completion dedupe invariant failed for ${childCount} children`);
+  }
+  return {
+    durationMs,
+    invariant: {
+      ok,
+      inputRowsPerOrdering: newestFirstRows.length,
+      newestFirstSelectedRows: newestFirst.length,
+      oldestFirstSelectedRows: oldestFirst.length,
+      newestFirstSelectedNewest,
+      oldestFirstSelectedNewest,
+    },
+  };
+}
+
+async function runScenario(options: WorkerOptions, stateDir: string): Promise<WorkerResult> {
+  const timingsMs: number[] = [];
+  let invariant: Record<string, number | boolean> = {};
+  const rssStartBytes = process.memoryUsage().rss;
+  for (let index = 0; index < options.warmup + options.runs; index += 1) {
+    let sample: Sample;
+    if (options.scenario === "spawnPipelineInMemory") {
+      sample = await runSpawnSample(options.size, index, "memory", stateDir);
+    } else if (options.scenario === "spawnPipelineDurable") {
+      sample = await runSpawnSample(options.size, index, "durable", stateDir);
+    } else if (options.scenario === "admission") {
+      sample = await runAdmissionSample(options.size, index);
+    } else if (options.scenario === "recoverySweep") {
+      sample = await runSweepSample(options.size);
+    } else {
+      sample = await runDedupeSample(options.size);
+    }
+    invariant = sample.invariant;
+    if (index >= options.warmup) {
+      timingsMs.push(sample.durationMs);
+    }
+  }
+  return {
+    scenario: options.scenario,
+    size: options.size,
+    timingsMs,
+    memory: {
+      rssStartBytes,
+      rssEndBytes: process.memoryUsage().rss,
+      processMaxRssBytes: processMaxRssBytes(),
+    },
+    invariant,
+  };
+}
+
+async function main(): Promise<void> {
+  const options = parseOptions(process.argv.slice(2));
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-agent-concurrency-worker-"));
+  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+  const previousNodeEnv = process.env.NODE_ENV;
+  let result: WorkerResult | undefined;
+  let failure: unknown;
+  process.env.OPENCLAW_STATE_DIR = stateDir;
+  process.env.NODE_ENV = "test";
+  try {
+    const { pinRuntimePaths } = await import("../src/config/paths.js");
+    pinRuntimePaths();
+    result = await runScenario(options, stateDir);
+  } catch (error) {
+    failure = error;
+  } finally {
+    try {
+      await resetRuntime(false);
+    } catch (error) {
+      failure ??= error;
+    } finally {
+      if (previousStateDir === undefined) {
+        delete process.env.OPENCLAW_STATE_DIR;
+      } else {
+        process.env.OPENCLAW_STATE_DIR = previousStateDir;
+      }
+      if (previousNodeEnv === undefined) {
+        delete process.env.NODE_ENV;
+      } else {
+        process.env.NODE_ENV = previousNodeEnv;
+      }
+      try {
+        fs.rmSync(stateDir, { recursive: true, force: true });
+      } catch (error) {
+        failure ??= error;
+      }
+    }
+  }
+  if (failure) {
+    throw toErrorObject(failure, "Agent concurrency benchmark failed");
+  }
+  if (!result) {
+    throw new Error("benchmark worker completed without a result");
+  }
+  process.stdout.write(`${WORKER_RESULT_SENTINEL}${JSON.stringify(result)}\n`);
+}
+
+export const testing = { drainSpawnSampleActiveWork };
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.stack : String(error));
+    process.exitCode = 1;
+  } finally {
+    if (process.exitCode && process.exitCode !== 0) {
+      console.error(`[bench-agent-concurrency-worker] FAILED (exit ${process.exitCode})`);
+    }
+  }
+}

scripts/bench-agent-concurrency.ts

@@ -0,0 +1,394 @@
+import { pathToFileURL } from "node:url";
+import { isRecord } from "@openclaw/normalization-core/record-coerce";
+import {
+  emitBenchmarkReport,
+  parseBenchmarkInteger,
+  parseBenchmarkIntegerList,
+  parseBenchmarkOptions,
+  parseBenchmarkWorkerResult,
+  runBenchmarkEntrypoint,
+  runBenchmarkJobs,
+  runBenchmarkWorker,
+  summarizeBenchmarkTimings,
+  type BenchmarkTimingSummary,
+  type BenchmarkWorkerProcessResult,
+} from "./lib/benchmark-harness.mts";
+
+const DEFAULT_FANOUT = [1, 8, 32, 64];
+const DEFAULT_SWEEP_ROWS = [32, 128, 512];
+const WORKER_TIMEOUT_MS = 300_000;
+export const WORKER_RESULT_SENTINEL = "[bench-agent-concurrency-result] ";
+
+export type WorkerScenario =
+  | "spawnPipelineInMemory"
+  | "spawnPipelineDurable"
+  | "admission"
+  | "recoverySweep"
+  | "duplicateSuppression";
+
+export type WorkerResult = {
+  scenario: WorkerScenario;
+  size: number;
+  timingsMs: number[];
+  memory: {
+    rssStartBytes: number;
+    rssEndBytes: number;
+    processMaxRssBytes: number;
+  };
+  invariant: Record<string, number | boolean>;
+};
+
+type Options = {
+  runs: number;
+  warmup: number;
+  fanout: number[];
+  sweepRows: number[];
+  output?: string;
+  json: boolean;
+  help: boolean;
+};
+
+const SCENARIO_SPECS: ReadonlyArray<{
+  scenario: WorkerScenario;
+  sizes: "fanout" | "sweepRows";
+}> = [
+  { scenario: "spawnPipelineInMemory", sizes: "fanout" },
+  { scenario: "spawnPipelineDurable", sizes: "fanout" },
+  { scenario: "admission", sizes: "fanout" },
+  { scenario: "recoverySweep", sizes: "sweepRows" },
+  { scenario: "duplicateSuppression", sizes: "sweepRows" },
+];
+
+const REQUIRED_INVARIANT_FIELDS: Record<WorkerScenario, readonly string[]> = {
+  spawnPipelineInMemory: [
+    "ok",
+    "registeredRuns",
+    "reservationsReleased",
+    "blockedWaits",
+    "settledRuns",
+    "settledTasks",
+    "outstandingWaits",
+    "durableSubagentRows",
+    "durableTaskRows",
+    "durableStateFile",
+    "postTeardownRegistryRows",
+    "postTeardownTaskRows",
+    "postTeardownDurableSubagentRows",
+    "postTeardownDurableTaskRows",
+    "postTeardownActiveRootWork",
+  ],
+  spawnPipelineDurable: [
+    "ok",
+    "registeredRuns",
+    "reservationsReleased",
+    "blockedWaits",
+    "settledRuns",
+    "settledTasks",
+    "outstandingWaits",
+    "durableSubagentRows",
+    "durableTaskRows",
+    "durableStateFile",
+    "postTeardownRegistryRows",
+    "postTeardownTaskRows",
+    "postTeardownDurableSubagentRows",
+    "postTeardownDurableTaskRows",
+    "postTeardownActiveRootWork",
+  ],
+  admission: ["ok", "admissionCap", "overflowRejected", "released"],
+  recoverySweep: [
+    "ok",
+    "seededRows",
+    "removedRows",
+    "retainedCurrent",
+    "sessionEffects",
+    "recoveryProjections",
+    "lostContextCompletions",
+  ],
+  duplicateSuppression: [
+    "ok",
+    "inputRowsPerOrdering",
+    "newestFirstSelectedRows",
+    "oldestFirstSelectedRows",
+    "newestFirstSelectedNewest",
+    "oldestFirstSelectedNewest",
+  ],
+};
+
+type BenchmarkRuntime = {
+  runWorker?: typeof runWorker;
+  writeProgress?: (line: string) => void;
+  now?: () => number;
+};
+
+function usage(): string {
+  return `OpenClaw agent concurrency benchmark
+
+Usage:
+  node --import tsx scripts/bench-agent-concurrency.ts [options]
+
+Options:
+  --runs <n>          Measured samples per scenario (default: 5)
+  --warmup <n>        Warmup samples per scenario (default: 1)
+  --fanout <list>     Comma-separated spawn/admission sizes (default: 1,8,32,64)
+  --sweep-rows <list> Comma-separated child counts, with 3 generations each (default: 32,128,512)
+  --output <path>     Write the JSON report to a file
+  --json              Print only the JSON report
+  --help              Show this text
+`;
+}
+
+function parseOptions(argv: string[]): Options {
+  return parseBenchmarkOptions<Options>(
+    argv,
+    {
+      runs: 5,
+      warmup: 1,
+      fanout: DEFAULT_FANOUT,
+      sweepRows: DEFAULT_SWEEP_ROWS,
+      json: false,
+      help: false,
+    },
+    {
+      "--runs": (options, value) => {
+        options.runs = parseBenchmarkInteger(value, "--runs", 1, 100);
+      },
+      "--warmup": (options, value) => {
+        options.warmup = parseBenchmarkInteger(value, "--warmup", 0, 20);
+      },
+      "--fanout": (options, value) => {
+        options.fanout = parseBenchmarkIntegerList(value, "--fanout", 256);
+      },
+      "--sweep-rows": (options, value) => {
+        options.sweepRows = parseBenchmarkIntegerList(value, "--sweep-rows", 4096);
+      },
+      "--output": (options, value) => {
+        options.output = value;
+      },
+    },
+  );
+}
+
+function expectedWorkerKeys(options: Options): string[] {
+  return SCENARIO_SPECS.flatMap(({ scenario, sizes }) =>
+    options[sizes].map((size) => `${scenario}:${size}`),
+  );
+}
+
+function aggregateWorkerResults(
+  options: Options,
+  workers: WorkerResult[],
+  parentMemory = {
+    rssStartBytes: process.memoryUsage().rss,
+    rssEndBytes: process.memoryUsage().rss,
+  },
+) {
+  const expected = expectedWorkerKeys(options);
+  const byKey = new Map(workers.map((worker) => [`${worker.scenario}:${worker.size}`, worker]));
+  if (byKey.size !== workers.length) {
+    throw new Error("worker results contain duplicate scenario/size pairs");
+  }
+  const missing = expected.filter((key) => !byKey.has(key));
+  const unexpected = [...byKey.keys()].filter((key) => !expected.includes(key));
+  if (missing.length > 0 || unexpected.length > 0) {
+    throw new Error(
+      `worker result mismatch: missing=${missing.join(",") || "none"} unexpected=${unexpected.join(",") || "none"}`,
+    );
+  }
+
+  const scenarios = Object.fromEntries(
+    SCENARIO_SPECS.map(({ scenario, sizes }) => [
+      scenario,
+      options[sizes].map((size) => {
+        const worker = byKey.get(`${scenario}:${size}`);
+        if (!worker) {
+          throw new Error(`missing worker result for ${scenario}:${size}`);
+        }
+        return {
+          size,
+          timingsMs: summarizeBenchmarkTimings(worker.timingsMs),
+          memory: worker.memory,
+          invariant: worker.invariant,
+        };
+      }),
+    ]),
+  ) as Record<
+    WorkerScenario,
+    Array<{
+      size: number;
+      timingsMs: BenchmarkTimingSummary;
+      memory: WorkerResult["memory"];
+      invariant: WorkerResult["invariant"];
+    }>
+  >;
+
+  const checks = {
+    spawnPipelineInMemory: scenarios.spawnPipelineInMemory.every(
+      (entry) => entry.invariant.ok === true,
+    ),
+    spawnPipelineDurable: scenarios.spawnPipelineDurable.every(
+      (entry) => entry.invariant.ok === true,
+    ),
+    admissionCapOverflowRelease: scenarios.admission.every((entry) => entry.invariant.ok === true),
+    sweepRecoveryRowsWithoutSessionEffects: scenarios.recoverySweep.every(
+      (entry) => entry.invariant.ok === true,
+    ),
+    dedupeNewestPerChild: scenarios.duplicateSuppression.every(
+      (entry) => entry.invariant.ok === true,
+    ),
+  };
+  const failures = Object.entries(checks)
+    .filter(([, ok]) => !ok)
+    .map(([name]) => name);
+
+  return {
+    schemaVersion: 2,
+    generatedAt: new Date().toISOString(),
+    runtime: { node: process.version, platform: process.platform, arch: process.arch },
+    options: {
+      runs: options.runs,
+      warmup: options.warmup,
+      fanout: options.fanout,
+      sweepRows: options.sweepRows,
+    },
+    memory: {
+      ...parentMemory,
+      workerProcessMaxRssBytes: Math.max(
+        ...workers.map((worker) => worker.memory.processMaxRssBytes),
+      ),
+    },
+    scenarios,
+    invariants: { ok: failures.length === 0, failures, ...checks },
+  };
+}
+
+function assertFiniteNonNegative(value: unknown, field: string): asserts value is number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`worker result field ${field} must be a finite nonnegative number`);
+  }
+}
+
+function validateWorkerResult(
+  value: unknown,
+  expected: { scenario: WorkerScenario; size: number; runs: number },
+): WorkerResult {
+  if (!isRecord(value)) {
+    throw new Error("worker result must be an object");
+  }
+  if (value.scenario !== expected.scenario || value.size !== expected.size) {
+    throw new Error(`worker ${expected.scenario}:${expected.size} returned mismatched identity`);
+  }
+  if (!Array.isArray(value.timingsMs) || value.timingsMs.length !== expected.runs) {
+    throw new Error(
+      `worker ${expected.scenario}:${expected.size} returned ${Array.isArray(value.timingsMs) ? value.timingsMs.length : "invalid"} samples; expected ${expected.runs}`,
+    );
+  }
+  value.timingsMs.forEach((timing, index) =>
+    assertFiniteNonNegative(timing, `timingsMs[${index}]`),
+  );
+  if (!isRecord(value.memory)) {
+    throw new Error("worker result memory must be an object");
+  }
+  assertFiniteNonNegative(value.memory.rssStartBytes, "memory.rssStartBytes");
+  assertFiniteNonNegative(value.memory.rssEndBytes, "memory.rssEndBytes");
+  assertFiniteNonNegative(value.memory.processMaxRssBytes, "memory.processMaxRssBytes");
+  if (!isRecord(value.invariant)) {
+    throw new Error("worker result invariant must be an object");
+  }
+  for (const field of REQUIRED_INVARIANT_FIELDS[expected.scenario]) {
+    const invariantValue = value.invariant[field];
+    if (typeof invariantValue !== "number" && typeof invariantValue !== "boolean") {
+      throw new Error(`worker result invariant.${field} is missing or invalid`);
+    }
+  }
+  if (value.invariant.ok !== true) {
+    throw new Error(`worker ${expected.scenario}:${expected.size} reported a failed invariant`);
+  }
+  return value as WorkerResult;
+}
+
+function parseWorkerProcessResult(
+  result: BenchmarkWorkerProcessResult,
+  expected: { scenario: WorkerScenario; size: number; runs: number },
+): WorkerResult {
+  return parseBenchmarkWorkerResult({
+    result,
+    label: `${expected.scenario}:${expected.size}`,
+    sentinel: WORKER_RESULT_SENTINEL,
+    timeoutMs: WORKER_TIMEOUT_MS,
+    validate: (value) => validateWorkerResult(value, expected),
+  });
+}
+
+function runWorker(options: Options, scenario: WorkerScenario, size: number): WorkerResult {
+  return runBenchmarkWorker({
+    args: [
+      "--import",
+      "tsx",
+      "scripts/bench-agent-concurrency-worker.ts",
+      "--scenario",
+      scenario,
+      "--size",
+      String(size),
+      "--runs",
+      String(options.runs),
+      "--warmup",
+      String(options.warmup),
+    ],
+    label: `${scenario}:${size}`,
+    sentinel: WORKER_RESULT_SENTINEL,
+    timeoutMs: WORKER_TIMEOUT_MS,
+    validate: (value) => validateWorkerResult(value, { scenario, size, runs: options.runs }),
+  });
+}
+
+function benchmark(options: Options, runtime: BenchmarkRuntime = {}) {
+  const rssStartBytes = process.memoryUsage().rss;
+  const jobs = SCENARIO_SPECS.flatMap(({ scenario, sizes }) =>
+    options[sizes].map((size) => ({ scenario, size })),
+  );
+  const run = runtime.runWorker ?? runWorker;
+  const workers = runBenchmarkJobs(jobs, {
+    prefix: "bench-agent-concurrency",
+    describe: ({ scenario, size }) => `scenario=${scenario} size=${size}`,
+    run: ({ scenario, size }) => run(options, scenario, size),
+    now: runtime.now,
+    writeProgress: runtime.writeProgress,
+  });
+  return aggregateWorkerResults(options, workers, {
+    rssStartBytes,
+    rssEndBytes: process.memoryUsage().rss,
+  });
+}
+
+async function main(argv = process.argv.slice(2)): Promise<void> {
+  const options = parseOptions(argv);
+  if (options.help) {
+    process.stdout.write(usage());
+    return;
+  }
+  const report = benchmark(options);
+  emitBenchmarkReport(report, options, (result) => [
+    ...Object.entries(result.scenarios).flatMap(([name, scenarios]) =>
+      scenarios.map((scenario) => {
+        const tail =
+          scenario.timingsMs.p95 === undefined
+            ? ""
+            : ` p95=${scenario.timingsMs.p95.toFixed(3)}ms p99=${scenario.timingsMs.p99?.toFixed(3)}ms`;
+        return `${name} size=${scenario.size} p50=${scenario.timingsMs.p50.toFixed(3)}ms max=${scenario.timingsMs.max.toFixed(3)}ms${tail}`;
+      }),
+    ),
+    `max worker RSS ${(result.memory.workerProcessMaxRssBytes / 1024 / 1024).toFixed(1)} MiB`,
+  ]);
+}
+
+export const testing = {
+  aggregateWorkerResults,
+  benchmark,
+  parseOptions,
+  parseWorkerProcessResult,
+  summarizeTimings: summarizeBenchmarkTimings,
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  await runBenchmarkEntrypoint("bench-agent-concurrency", main);
+}

scripts/bench-cli-startup.ts

@@ -0,0 +1,1747 @@
+// Bench Cli Startup script supports OpenClaw repository automation.
+import { execFileSync, spawn } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { expectDefined } from "../packages/normalization-core/src/expect.js";
+import {
+  assertCompatibleCliStartupExecutionModes,
+  assertCompatibleCliStartupMemoryMetrics,
+  CLI_RUNTIME_MEMORY_METRIC,
+  type CliStartupExecutionMode,
+  cliStartupMemoryMetric,
+} from "./lib/cli-startup-memory-contract.mts";
+import {
+  inspectManagedProcessGroup,
+  terminateManagedChild,
+  waitForManagedProcessGroupExit,
+} from "./lib/managed-child-process.mts";
+
+type CommandCase = {
+  id: string;
+  name: string;
+  args: string[];
+  presets: readonly string[];
+  stateScope?: "case" | "sample";
+  expectedExitCodes?: readonly number[];
+  expectedNonzeroOutputIncludes?: readonly string[];
+  firstOutputBudgetMs?: number;
+  exitBudgetMs?: number;
+};
+
+type Sample = {
+  ms: number;
+  firstOutputMs: number | null;
+  maxRssMb: number | null;
+  memory?: SampleMemory;
+  exitCode: number | null;
+  signal: string | null;
+  startedAt?: string;
+  endedAt?: string;
+  timedOut?: boolean;
+  stdoutTail?: string;
+  stderrTail?: string;
+};
+
+type RssObservation = {
+  pid: number;
+  parentPid: number;
+  matchesArguments: boolean;
+  matchesInvocation: boolean;
+  maxRssBytes: number | null;
+};
+
+type SampleMemory = {
+  runtimePid: number | null;
+  processes: Array<{
+    pid: number;
+    parentPid: number;
+    role: "runtime" | "launcher" | "auxiliary" | "unresolved";
+    metricKind: "process-high-water-rss";
+    maxRssBytes: number | null;
+  }>;
+  error?: string;
+};
+
+type CaseRuns = {
+  warmupSamples: Sample[];
+  samples: Sample[];
+};
+
+type SummaryStats = {
+  avg: number;
+  p50: number;
+  p95: number;
+  min: number;
+  max: number;
+};
+
+type CaseSummary = {
+  sampleCount: number;
+  durationMs: SummaryStats;
+  firstOutputMs: SummaryStats | null;
+  maxRssMb: SummaryStats | null;
+  exitSummary: string;
+};
+
+type SuiteResult = {
+  entry: string;
+  executionMode?: CliStartupExecutionMode;
+  memoryMetric?: string;
+  cases: Array<{
+    id: string;
+    name: string;
+    args: string[];
+    expectedExitCodes?: number[];
+    expectedNonzeroOutputIncludes?: string[];
+    contract: {
+      firstOutputBudgetMs: number | null;
+      exitBudgetMs: number | null;
+    } | null;
+    warmupSamples?: Sample[];
+    samples: Sample[];
+    summary: CaseSummary;
+  }>;
+};
+
+type BenchmarkReport = {
+  primary: SuiteResult;
+  secondary?: SuiteResult | null;
+};
+
+type CaseDelta = {
+  id: string;
+  name: string;
+  durationAvgDeltaMs: number;
+  durationAvgDeltaPct: number;
+  maxRssAvgDeltaMb: number | null;
+  maxRssAvgDeltaPct: number | null;
+};
+
+type BenchmarkComparison = {
+  baseline: string;
+  candidate: string;
+  deltas: CaseDelta[];
+};
+
+type BenchmarkComparisonResult = {
+  baseline: SuiteResult;
+  candidate: SuiteResult;
+  comparison: BenchmarkComparison;
+};
+
+type CliOptions = {
+  cases: CommandCase[];
+  compareBaseline?: string;
+  compareCandidate?: string;
+  entryPrimary: string;
+  entrySecondary?: string;
+  runs: number;
+  warmup: number;
+  timeoutMs: number;
+  runtimeRss: boolean;
+  json: boolean;
+  output?: string;
+  cpuProfDir?: string;
+  heapProfDir?: string;
+};
+
+const DEFAULT_RUNS = 5;
+const DEFAULT_WARMUP = 1;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_TIMEOUT_KILL_GRACE_MS = 1_000;
+const TIMEOUT_KILL_GRACE_MS = resolveTimeoutKillGraceMs(process.env);
+const DEFAULT_ENTRY = "openclaw.mjs";
+const MAX_RSS_MARKER = "__OPENCLAW_MAX_RSS_KB__=";
+
+type SampleTransport = {
+  prefix: string[];
+  binary: string;
+  env: Record<string, string>;
+  cwd: string;
+};
+
+function sampleTransport(): SampleTransport | undefined {
+  const raw = process.env.OPENCLAW_BENCH_TRANSPORT_JSON;
+  if (raw === undefined) {
+    return undefined;
+  }
+  const value: unknown = JSON.parse(raw);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid benchmark transport");
+  }
+  const prefix = "prefix" in value ? value.prefix : undefined;
+  const binary = "binary" in value ? value.binary : undefined;
+  const env = "env" in value ? value.env : undefined;
+  const cwd = "cwd" in value ? value.cwd : undefined;
+  if (
+    !Array.isArray(prefix) ||
+    prefix.length === 0 ||
+    !prefix.every(
+      (part: unknown) => typeof part === "string" && part.length > 0 && !part.includes("\0"),
+    ) ||
+    typeof prefix[0] !== "string" ||
+    !path.isAbsolute(prefix[0]) ||
+    typeof binary !== "string" ||
+    !path.isAbsolute(binary) ||
+    binary.includes("\0") ||
+    !env ||
+    typeof env !== "object" ||
+    Array.isArray(env)
+  ) {
+    throw new Error("Invalid benchmark transport");
+  }
+  const fixedEnv: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(env)) {
+    if (!/^[A-Z_][A-Z0-9_]*$/u.test(key) || typeof entry !== "string" || entry.includes("\0")) {
+      throw new Error("Invalid benchmark transport environment");
+    }
+    fixedEnv[key] = entry;
+  }
+  if (!fixedEnv.HOME || !path.isAbsolute(fixedEnv.HOME) || !fixedEnv.PATH) {
+    throw new Error("Benchmark transport requires fixed HOME and PATH");
+  }
+  const directory = cwd === undefined ? fixedEnv.HOME : cwd;
+  if (typeof directory !== "string" || !path.isAbsolute(directory) || directory.includes("\0")) {
+    throw new Error("Invalid benchmark transport cwd");
+  }
+  return { prefix, binary, env: fixedEnv, cwd: directory };
+}
+
+function transportedCommand(
+  transport: SampleTransport,
+  args: string[],
+  env: Record<string, string> = {},
+  timeoutMs?: number,
+): { command: string; args: string[] } {
+  return {
+    command: expectDefined(transport.prefix[0], "benchmark transport command"),
+    args: [
+      ...transport.prefix.slice(1),
+      "/usr/bin/env",
+      "-C",
+      transport.cwd,
+      "-i",
+      ...Object.entries({ ...transport.env, ...env }).map(([key, value]) => `${key}=${value}`),
+      ...(timeoutMs === undefined
+        ? []
+        : ["/usr/bin/timeout", "--signal=TERM", "--kill-after=1s", `${timeoutMs / 1000}s`]),
+      transport.binary,
+      ...args,
+    ],
+  };
+}
+
+function sampleFilesystem(
+  transport: SampleTransport,
+  operation: "create" | "prepare" | "remove",
+  root?: string,
+  config?: Record<string, unknown> | null,
+  hook?: string,
+): string {
+  // Only the SUT opens these paths. Its replies are never read as paths on the runner.
+  const launch = transportedCommand(transport, [
+    "--input-type=module",
+    "-e",
+    `import fs from "node:fs"; import os from "node:os"; import path from "node:path";
+const {operation,root,config,hook} = JSON.parse(fs.readFileSync(0,"utf8"));
+if (operation === "create") process.stdout.write(fs.mkdtempSync(path.join(os.tmpdir(),"openclaw-cli-bench-home-")));
+else if (operation === "prepare") {
+  fs.mkdirSync(path.join(root,".openclaw"),{recursive:true});
+  if (config) fs.writeFileSync(path.join(root,".openclaw/openclaw.json"),JSON.stringify(config)+"\\n");
+  fs.writeFileSync(path.join(root,"measure-rss.mjs"),hook);
+} else if (operation === "remove") fs.rmSync(root,{recursive:true,force:true});
+else throw new Error("Invalid sample filesystem operation");`,
+  ]);
+  return execFileSync(launch.command, launch.args, {
+    input: JSON.stringify({ operation, root, config, hook }),
+    encoding: "utf8",
+    timeout: 10_000,
+    maxBuffer: 64 * 1024,
+    env: { PATH: process.env.PATH },
+  });
+}
+
+function createSampleRoot(transport?: SampleTransport): string {
+  if (!transport) {
+    return mkdtempSync(path.join(os.tmpdir(), "openclaw-cli-bench-home-"));
+  }
+  const root = sampleFilesystem(transport, "create");
+  if (!path.isAbsolute(root) || /[\0\r\n]/u.test(root)) {
+    throw new Error("Invalid SUT sample directory");
+  }
+  return root;
+}
+
+function removeSampleRoot(root: string, transport?: SampleTransport): void {
+  if (transport) {
+    sampleFilesystem(transport, "remove", root);
+  } else {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function resolveTimeoutKillGraceMs(env: NodeJS.ProcessEnv): number {
+  const raw = env.VITEST ? env.OPENCLAW_TEST_CLI_STARTUP_TIMEOUT_KILL_GRACE_MS : undefined;
+  if (!raw || !/^\d+$/u.test(raw)) {
+    return DEFAULT_TIMEOUT_KILL_GRACE_MS;
+  }
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) ? parsed : DEFAULT_TIMEOUT_KILL_GRACE_MS;
+}
+const VALUE_FLAGS = new Set([
+  "--case",
+  "--compare-baseline",
+  "--compare-candidate",
+  "--cpu-prof-dir",
+  "--entry",
+  "--entry-primary",
+  "--entry-secondary",
+  "--heap-prof-dir",
+  "--output",
+  "--preset",
+  "--runs",
+  "--timeout-ms",
+  "--warmup",
+]);
+const BOOLEAN_FLAGS = new Set(["--help", "--json", "--runtime-rss"]);
+
+const COMMAND_CASES: readonly CommandCase[] = [
+  {
+    id: "version",
+    name: "--version",
+    args: ["--version"],
+    presets: ["startup", "response"],
+    firstOutputBudgetMs: 1_000,
+    exitBudgetMs: 2_000,
+  },
+  {
+    id: "help",
+    name: "--help",
+    args: ["--help"],
+    presets: ["startup", "response"],
+    firstOutputBudgetMs: 1_000,
+    exitBudgetMs: 2_000,
+  },
+  {
+    id: "onboardHelp",
+    name: "onboard --help",
+    args: ["onboard", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "setupHelp",
+    name: "setup --help",
+    args: ["setup", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "configureHelp",
+    name: "configure --help",
+    args: ["configure", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "channelsAddHelp",
+    name: "channels add --help",
+    args: ["channels", "add", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "channelsParent",
+    name: "channels",
+    args: ["channels"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "doctorHelp",
+    name: "doctor --help",
+    args: ["doctor", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "modelsHelp",
+    name: "models --help",
+    args: ["models", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "pluginsHelp",
+    name: "plugins --help",
+    args: ["plugins", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "pluginsParent",
+    name: "plugins",
+    args: ["plugins"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "pluginsListJson",
+    name: "plugins list --json",
+    args: ["plugins", "list", "--json"],
+    presets: ["response", "real"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "gatewayHelp",
+    name: "gateway --help",
+    args: ["gateway", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "agentsHelp",
+    name: "agents --help",
+    args: ["agents", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 3_500,
+    exitBudgetMs: 8_000,
+  },
+  {
+    id: "sessionsHelp",
+    name: "sessions --help",
+    args: ["sessions", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "tasksHelp",
+    name: "tasks --help",
+    args: ["tasks", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "messageHelp",
+    name: "message --help",
+    args: ["message", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "pairingHelp",
+    name: "pairing --help",
+    args: ["pairing", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "authHelp",
+    name: "auth --help",
+    args: ["auth", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "configHelp",
+    name: "config --help",
+    args: ["config", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "secretsHelp",
+    name: "secrets --help",
+    args: ["secrets", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "skillsHelp",
+    name: "skills --help",
+    args: ["skills", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "nodesHelp",
+    name: "nodes --help",
+    args: ["nodes", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 3_500,
+    exitBudgetMs: 8_000,
+  },
+  {
+    id: "directoryHelp",
+    name: "directory --help",
+    args: ["directory", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "sandboxHelp",
+    name: "sandbox --help",
+    args: ["sandbox", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "devicesParent",
+    name: "devices",
+    args: ["devices"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "mcpParent",
+    name: "mcp",
+    args: ["mcp"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "browserHelp",
+    name: "browser --help",
+    args: ["browser", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 1_500,
+    exitBudgetMs: 3_000,
+  },
+  {
+    id: "webhooksHelp",
+    name: "webhooks --help",
+    args: ["webhooks", "--help"],
+    presets: ["response"],
+    firstOutputBudgetMs: 2_500,
+    exitBudgetMs: 6_000,
+  },
+  {
+    id: "health",
+    name: "health",
+    args: ["health"],
+    presets: ["startup", "real"],
+    expectedExitCodes: [0, 1],
+    expectedNonzeroOutputIncludes: ["Gateway target:"],
+  },
+  {
+    id: "healthJson",
+    name: "health --json",
+    args: ["health", "--json"],
+    presets: ["startup"],
+    expectedExitCodes: [0, 1],
+    expectedNonzeroOutputIncludes: ['"ok"', '"gateway_transport_error"'],
+  },
+  {
+    id: "statusJson",
+    name: "status --json",
+    args: ["status", "--json"],
+    presets: ["startup", "real"],
+  },
+  { id: "status", name: "status", args: ["status"], presets: ["startup", "real"] },
+  { id: "sessions", name: "sessions", args: ["sessions"], presets: ["real"] },
+  {
+    id: "sessionsJson",
+    name: "sessions --json",
+    args: ["sessions", "--json"],
+    presets: ["real"],
+  },
+  {
+    id: "tasksJson",
+    name: "tasks --json",
+    args: ["tasks", "--json"],
+    presets: ["real"],
+  },
+  {
+    id: "tasksListJson",
+    name: "tasks list --json",
+    args: ["tasks", "list", "--json"],
+    presets: ["real"],
+  },
+  {
+    id: "tasksAuditJson",
+    name: "tasks audit --json",
+    args: ["tasks", "audit", "--json"],
+    presets: ["real"],
+  },
+  {
+    id: "agentsListJson",
+    name: "agents list --json",
+    args: ["agents", "list", "--json"],
+    presets: ["real"],
+  },
+  {
+    id: "gatewayStatus",
+    name: "gateway status",
+    args: ["gateway", "status"],
+    presets: ["real"],
+  },
+  {
+    id: "gatewayStatusJson",
+    name: "gateway status --json",
+    args: ["gateway", "status", "--json"],
+    presets: ["real"],
+  },
+  {
+    id: "gatewayHealthJson",
+    name: "gateway health --json",
+    args: ["gateway", "health", "--json"],
+    presets: ["real"],
+    expectedExitCodes: [0, 1],
+    expectedNonzeroOutputIncludes: ['"ok"', '"gateway_transport_error"'],
+  },
+  {
+    id: "gatewayHealthJsonWarmState",
+    name: "gateway health --json (warm state)",
+    args: ["gateway", "health", "--json"],
+    presets: [],
+    stateScope: "case",
+  },
+  {
+    id: "gatewayHealthJsonFreshState",
+    name: "gateway health --json (fresh state)",
+    args: ["gateway", "health", "--json"],
+    presets: [],
+    stateScope: "sample",
+  },
+  {
+    id: "configGetGatewayPort",
+    name: "config get gateway.port",
+    args: ["config", "get", "gateway.port"],
+    presets: ["real"],
+    expectedExitCodes: [0, 1],
+    expectedNonzeroOutputIncludes: ["Config path not found: gateway.port"],
+  },
+] as const;
+
+function parseFlagValue(flag: string): string | undefined {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) {
+    return undefined;
+  }
+  const value = process.argv[idx + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+function hasFlag(flag: string): boolean {
+  return process.argv.includes(flag);
+}
+
+function parseRepeatableFlag(flag: string): string[] {
+  const values: string[] = [];
+  for (let i = 0; i < process.argv.length; i += 1) {
+    const value = process.argv[i + 1];
+    if (process.argv[i] === flag && value && !value.startsWith("-")) {
+      values.push(value);
+    }
+  }
+  return values;
+}
+
+function validateCliArgs(argv: readonly string[] = process.argv.slice(2)): void {
+  const seenSingleValueFlags = new Set<string>();
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = expectDefined(argv[index], `CLI benchmark argument at index ${index}`);
+    if (VALUE_FLAGS.has(arg)) {
+      if (arg !== "--case") {
+        if (seenSingleValueFlags.has(arg)) {
+          throw new Error(`${arg} was provided more than once`);
+        }
+        seenSingleValueFlags.add(arg);
+      }
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error(`${arg} requires a value`);
+      }
+      index += 1;
+      continue;
+    }
+    if (BOOLEAN_FLAGS.has(arg)) {
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+}
+
+function parsePositiveInt(raw: string | undefined, fallback: number, label = "value"): number {
+  return parseIntegerOption(raw, fallback, label, 1);
+}
+
+function parseNonNegativeInt(raw: string | undefined, fallback: number, label = "value"): number {
+  return parseIntegerOption(raw, fallback, label, 0);
+}
+
+// This runner is checked out from trusted main beside frozen candidates, whose
+// root dependencies need not include current workspace packages.
+function parseIntegerOption(
+  raw: string | undefined,
+  fallback: number,
+  label: string,
+  min: number,
+): number {
+  const value = raw?.trim();
+  if (!value) {
+    return fallback;
+  }
+  if (!/^\d+$/u.test(value)) {
+    throw new Error(`${label} must be an integer >= ${min}; got ${JSON.stringify(raw)}`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < min) {
+    throw new Error(`${label} must be an integer >= ${min}; got ${JSON.stringify(raw)}`);
+  }
+  return parsed;
+}
+
+function parseGatewayPortEnv(raw: string | undefined): number {
+  const value = raw?.trim();
+  if (!value) {
+    return 32123;
+  }
+  const bracketHostMatch = /^\[[^\]]+\]:(\d+)$/u.exec(value);
+  if (bracketHostMatch) {
+    return parsePositiveInt(bracketHostMatch[1], 32123, "OPENCLAW_GATEWAY_PORT");
+  }
+  if (value.startsWith("[") && value.endsWith("]")) {
+    return 32123;
+  }
+  const colonCount = value.split(":").length - 1;
+  if (colonCount > 1) {
+    return 32123;
+  }
+  const portRaw = colonCount === 1 ? value.split(":")[1] : value;
+  return parsePositiveInt(portRaw, 32123, "OPENCLAW_GATEWAY_PORT");
+}
+
+function parsePresets(raw: string | undefined): string[] {
+  if (!raw) {
+    return ["startup"];
+  }
+  const values = raw
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  if (values.includes("all")) {
+    return ["startup", "real", "response"];
+  }
+  return values.length > 0 ? values : ["startup"];
+}
+
+function resolveCases(options: { presets: string[]; caseIds: string[] }): CommandCase[] {
+  const byId = new Map(COMMAND_CASES.map((commandCase) => [commandCase.id, commandCase]));
+  if (options.caseIds.length > 0) {
+    const seenIds = new Set<string>();
+    return options.caseIds.map((id) => {
+      if (seenIds.has(id)) {
+        throw new Error(`Duplicate --case "${id}"`);
+      }
+      seenIds.add(id);
+      const commandCase = byId.get(id);
+      if (!commandCase) {
+        throw new Error(`Unknown --case "${id}"`);
+      }
+      return commandCase;
+    });
+  }
+  return COMMAND_CASES.filter((commandCase) =>
+    commandCase.presets.some((preset) => options.presets.includes(preset)),
+  );
+}
+
+function median(values: number[]): number {
+  if (values.length === 0) {
+    return 0;
+  }
+  const sorted = [...values].toSorted((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) {
+    return (
+      (expectDefined(sorted[mid - 1], "lower middle CLI benchmark sample") +
+        expectDefined(sorted[mid], "upper middle CLI benchmark sample")) /
+      2
+    );
+  }
+  return expectDefined(sorted[mid], "middle CLI benchmark sample");
+}
+
+function percentile(values: number[], p: number): number {
+  if (values.length === 0) {
+    return 0;
+  }
+  const sorted = [...values].toSorted((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length));
+  return sorted[index] ?? 0;
+}
+
+function summarizeNumbers(values: number[]): SummaryStats {
+  const total = values.reduce((sum, value) => sum + value, 0);
+  const avg = values.length > 0 ? total / values.length : 0;
+  const min = values.length > 0 ? Math.min(...values) : 0;
+  const max = values.length > 0 ? Math.max(...values) : 0;
+  return {
+    avg,
+    p50: median(values),
+    p95: percentile(values, 95),
+    min,
+    max,
+  };
+}
+
+function summarizeSamples(samples: Sample[]): CaseSummary {
+  const durations = summarizeNumbers(samples.map((sample) => sample.ms));
+  const firstOutputValues = samples
+    .map((sample) => sample.firstOutputMs)
+    .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+  const rssValues = samples
+    .map((sample) => sample.maxRssMb)
+    .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+  return {
+    sampleCount: samples.length,
+    durationMs: durations,
+    firstOutputMs: firstOutputValues.length > 0 ? summarizeNumbers(firstOutputValues) : null,
+    maxRssMb: rssValues.length > 0 ? summarizeNumbers(rssValues) : null,
+    exitSummary: collectExitSummary(samples),
+  };
+}
+
+function formatMs(value: number): string {
+  return `${value.toFixed(1)}ms`;
+}
+
+function formatMb(value: number): string {
+  return `${value.toFixed(1)}MiB`;
+}
+
+function collectExitSummary(samples: Sample[]): string {
+  const buckets = new Map<string, number>();
+  for (const sample of samples) {
+    const key =
+      sample.signal != null
+        ? `signal:${sample.signal}`
+        : `code:${sample.exitCode == null ? "null" : String(sample.exitCode)}`;
+    buckets.set(key, (buckets.get(key) ?? 0) + 1);
+  }
+  return [...buckets.entries()].map(([key, count]) => `${key}x${count}`).join(", ");
+}
+
+function buildConfigFixture(commandCase: CommandCase): Record<string, unknown> | null {
+  const usesSharedToken =
+    commandCase.id === "gatewayHealthJsonWarmState" ||
+    commandCase.id === "gatewayHealthJsonFreshState";
+  if (
+    commandCase.id !== "configGetGatewayPort" &&
+    commandCase.id !== "gatewayHealthJson" &&
+    !usesSharedToken &&
+    commandCase.id !== "health" &&
+    commandCase.id !== "healthJson"
+  ) {
+    return null;
+  }
+  const port = parseGatewayPortEnv(process.env.OPENCLAW_GATEWAY_PORT);
+  return {
+    gateway: {
+      auth: { mode: usesSharedToken ? "token" : "none" },
+      bind: "loopback",
+      mode: "local",
+      port,
+    },
+  };
+}
+
+function buildRssHook(tmpDir: string): string {
+  const rssHookPath = path.join(tmpDir, "measure-rss.mjs");
+  writeFileSync(
+    rssHookPath,
+    [
+      "process.on('exit', () => {",
+      "  const usage = typeof process.resourceUsage === 'function' ? process.resourceUsage() : null;",
+      `  if (usage && typeof usage.maxRSS === 'number') console.error('${MAX_RSS_MARKER}' + String(usage.maxRSS));`,
+      "});",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return rssHookPath;
+}
+
+function parseMaxRssMb(stderr: string): number | null {
+  const matches = [...stderr.matchAll(new RegExp(`^${MAX_RSS_MARKER}(\\d+)\\s*$`, "gm"))];
+  const lastMatch = matches.at(-1);
+  if (!lastMatch?.[1]) {
+    return null;
+  }
+  return Number(lastMatch[1]) / 1024;
+}
+
+function buildRuntimeRssHook(tmpDir: string): string {
+  const rssHookPath = path.join(tmpDir, "measure-rss.mjs");
+  writeFileSync(
+    rssHookPath,
+    `import { writeFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { isMainThread } from "node:worker_threads";
+if (isMainThread) {
+  const { directory, entries, args } = JSON.parse(process.env.OPENCLAW_BENCH_MEMORY);
+  let entry;
+  try {
+    if (process.argv[1]) entry = realpathSync(process.argv[1]);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const matchesArguments = JSON.stringify(process.argv.slice(2)) === JSON.stringify(args);
+  const record = {
+    pid: process.pid,
+    parentPid: process.ppid,
+    matchesArguments,
+    matchesInvocation: entries.includes(entry) && matchesArguments,
+    maxRssBytes: null,
+  };
+  const file = join(directory, String(process.pid) + ".json");
+  writeFileSync(file, JSON.stringify(record));
+  process.on("exit", () => {
+    record.maxRssBytes = process.resourceUsage().maxRSS * 1024;
+    writeFileSync(file, JSON.stringify(record));
+  });
+}
+`,
+    "utf8",
+  );
+  return rssHookPath;
+}
+
+function readSampleMemory(directory: string, entryPid: number | undefined): SampleMemory {
+  const memory: SampleMemory = { runtimePid: null, processes: [] };
+  try {
+    const observations: RssObservation[] = readdirSync(directory).map((file) => {
+      const value: unknown = JSON.parse(readFileSync(path.join(directory, file), "utf8"));
+      if (
+        typeof value !== "object" ||
+        value === null ||
+        !("pid" in value) ||
+        typeof value.pid !== "number" ||
+        !Number.isSafeInteger(value.pid) ||
+        value.pid <= 0 ||
+        file !== `${value.pid}.json` ||
+        !("parentPid" in value) ||
+        typeof value.parentPid !== "number" ||
+        !Number.isSafeInteger(value.parentPid) ||
+        value.parentPid < 0 ||
+        !("matchesArguments" in value) ||
+        typeof value.matchesArguments !== "boolean" ||
+        !("matchesInvocation" in value) ||
+        typeof value.matchesInvocation !== "boolean" ||
+        !("maxRssBytes" in value) ||
+        !(
+          value.maxRssBytes === null ||
+          (typeof value.maxRssBytes === "number" &&
+            Number.isSafeInteger(value.maxRssBytes) &&
+            value.maxRssBytes > 0)
+        )
+      ) {
+        throw new Error("invalid process RSS observation");
+      }
+      return {
+        pid: value.pid,
+        parentPid: value.parentPid,
+        matchesArguments: value.matchesArguments,
+        matchesInvocation: value.matchesInvocation,
+        maxRssBytes: value.maxRssBytes,
+      };
+    });
+    memory.processes = observations.map((record) => ({
+      pid: record.pid,
+      parentPid: record.parentPid,
+      role: record.matchesInvocation ? "unresolved" : "auxiliary",
+      metricKind: "process-high-water-rss",
+      maxRssBytes: record.maxRssBytes,
+    }));
+    if (observations.some((record) => record.matchesArguments && !record.matchesInvocation)) {
+      throw new Error("unrecognized CLI entry with matching command arguments");
+    }
+    const invocation = observations.filter((record) => record.matchesInvocation);
+    const entryObservation = invocation.find((record) => record.pid === entryPid);
+    if (!entryObservation) {
+      throw new Error("missing CLI entry process identity");
+    }
+    let current: RssObservation = entryObservation;
+    const lineage = new Set<number>();
+    // Respawns preserve CLI argv and the preload. Follow the unique invocation
+    // chain, not exit order, RSS magnitude, or platform-specific ready flags.
+    while (true) {
+      if (lineage.has(current.pid)) {
+        throw new Error("cyclic CLI process identity");
+      }
+      lineage.add(current.pid);
+      if (current.maxRssBytes === null) {
+        throw new Error(`missing process high-water RSS for CLI PID ${current.pid}`);
+      }
+      const parentPid = current.pid;
+      const children = invocation.filter((record) => record.parentPid === parentPid);
+      if (children.length > 1) {
+        throw new Error("ambiguous CLI runtime identity: multiple matching children");
+      }
+      const child = children[0];
+      if (!child) {
+        break;
+      }
+      current = child;
+    }
+    if (lineage.size !== invocation.length) {
+      throw new Error("disconnected CLI runtime identity");
+    }
+    memory.runtimePid = current.pid;
+    for (const record of memory.processes) {
+      if (lineage.has(record.pid)) {
+        record.role = record.pid === current.pid ? "runtime" : "launcher";
+      }
+    }
+  } catch (error) {
+    memory.error = error instanceof Error ? error.message : String(error);
+  }
+  return memory;
+}
+
+function memoryInvocationEntries(entry: string): string[] {
+  const resolvedEntry = realpathSync(entry);
+  const entries = [resolvedEntry];
+  // The wrapper's compile-cache handoff can enter dist directly.
+  if (path.basename(resolvedEntry) === "openclaw.mjs") {
+    for (const name of ["entry.js", "entry.mjs"]) {
+      try {
+        entries.push(realpathSync(path.join(path.dirname(resolvedEntry), "dist", name)));
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+          throw error;
+        }
+      }
+    }
+  }
+  return entries;
+}
+
+function nodeImportSpecifierForPath(filePath: string): string {
+  return pathToFileURL(filePath).href;
+}
+
+function buildCpuOrHeapFlags(options: { cpuProfDir?: string; heapProfDir?: string }): string[] {
+  const flags: string[] = [];
+  if (options.cpuProfDir) {
+    flags.push("--cpu-prof", "--cpu-prof-dir", options.cpuProfDir);
+  }
+  if (options.heapProfDir) {
+    flags.push("--heap-prof", "--heap-prof-dir", options.heapProfDir);
+  }
+  return flags;
+}
+
+function appendLimited(current: string, chunk: Buffer | string, maxLength: number): string {
+  const next = current + String(chunk);
+  return next.length > maxLength ? next.slice(next.length - maxLength) : next;
+}
+
+async function runSample(params: {
+  entry: string;
+  commandCase: CommandCase;
+  timeoutMs: number;
+  runtimeRss: boolean;
+  cpuProfDir?: string;
+  heapProfDir?: string;
+  rssHookPath: string;
+  runRoot?: string;
+}): Promise<Sample> {
+  const transport = sampleTransport();
+  const runRoot = params.runRoot ?? createSampleRoot(transport);
+  const ownsRunRoot = params.runRoot == null;
+  const stateDir = path.join(runRoot, ".openclaw");
+  const configPath = path.join(stateDir, "openclaw.json");
+  const configFixture = buildConfigFixture(params.commandCase);
+  let rssHookPath = params.rssHookPath;
+  if (transport) {
+    sampleFilesystem(
+      transport,
+      "prepare",
+      runRoot,
+      configFixture,
+      readFileSync(rssHookPath, "utf8"),
+    );
+    rssHookPath = path.join(runRoot, "measure-rss.mjs");
+  } else if (configFixture) {
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(configFixture, null, 2)}\n`, "utf8");
+  }
+  const nodeArgs = [
+    ...(transport
+      ? [
+          "--import",
+          `data:text/javascript,${encodeURIComponent(`process.chdir(${JSON.stringify(path.dirname(params.entry))});`)}`,
+        ]
+      : []),
+    "--import",
+    nodeImportSpecifierForPath(rssHookPath),
+    ...buildCpuOrHeapFlags({
+      cpuProfDir: params.cpuProfDir,
+      heapProfDir: params.heapProfDir,
+    }),
+    params.entry,
+    ...params.commandCase.args,
+  ];
+  const startedAt = new Date();
+  const started = process.hrtime.bigint();
+  let firstOutputMs: number | null = null;
+  let stdout = "";
+  let stderr = "";
+  let settled = false;
+  let timedOut = false;
+  let forceKillAt: number | null = null;
+  let forceKillTimer: ReturnType<typeof setTimeout> | null = null;
+  const maxOutputLength = 32 * 1024 * 1024;
+  const memoryDirectory = params.runtimeRss
+    ? mkdtempSync(path.join(path.dirname(params.rssHookPath), "sample-"))
+    : undefined;
+
+  try {
+    return await new Promise<Sample>((resolve) => {
+      const sampleEnv = {
+        HOME: runRoot,
+        USERPROFILE: runRoot,
+        OPENCLAW_HOME: runRoot,
+        OPENCLAW_STATE_DIR: stateDir,
+        OPENCLAW_CONFIG_PATH: configPath,
+        OPENCLAW_HIDE_BANNER: "1",
+        NO_COLOR: "1",
+        FORCE_COLOR: "0",
+        ...(memoryDirectory
+          ? {
+              OPENCLAW_BENCH_MEMORY: JSON.stringify({
+                directory: memoryDirectory,
+                entries: memoryInvocationEntries(params.entry),
+                args: params.commandCase.args,
+              }),
+            }
+          : {}),
+      };
+      const launch = transport
+        ? transportedCommand(
+            transport,
+            nodeArgs,
+            {
+              ...sampleEnv,
+              ...(process.env.OPENCLAW_GATEWAY_TOKEN
+                ? { OPENCLAW_GATEWAY_TOKEN: process.env.OPENCLAW_GATEWAY_TOKEN }
+                : {}),
+              ...(process.env.OPENCLAW_GATEWAY_PORT
+                ? { OPENCLAW_GATEWAY_PORT: process.env.OPENCLAW_GATEWAY_PORT }
+                : {}),
+            },
+            params.timeoutMs,
+          )
+        : { command: process.execPath, args: nodeArgs };
+      const proc = spawn(launch.command, launch.args, {
+        cwd: process.cwd(),
+        detached: process.platform !== "win32",
+        env: transport ? { PATH: process.env.PATH } : { ...process.env, ...sampleEnv },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+
+      const finish = (sample: Omit<Sample, "ms" | "firstOutputMs" | "maxRssMb">) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (forceKillTimer) {
+          clearTimeout(forceKillTimer);
+          forceKillTimer = null;
+        }
+        const ms = Number(process.hrtime.bigint() - started) / 1e6;
+        const memory = memoryDirectory ? readSampleMemory(memoryDirectory, proc.pid) : undefined;
+        const runtimeRss = memory?.processes.find(
+          (record) => record.role === "runtime",
+        )?.maxRssBytes;
+        resolve({
+          ms,
+          firstOutputMs,
+          maxRssMb: memory
+            ? runtimeRss == null
+              ? null
+              : runtimeRss / 1024 / 1024
+            : parseMaxRssMb(stderr),
+          ...(memory ? { memory } : {}),
+          startedAt: startedAt.toISOString(),
+          endedAt: new Date().toISOString(),
+          ...(timedOut ? { timedOut } : {}),
+          ...sample,
+        });
+      };
+
+      const markFirstOutput = () => {
+        if (firstOutputMs == null) {
+          firstOutputMs = Number(process.hrtime.bigint() - started) / 1e6;
+        }
+      };
+
+      const timeout = setTimeout(() => {
+        timedOut = true;
+        signalSampleProcess(proc, "SIGTERM");
+        forceKillAt = Date.now() + TIMEOUT_KILL_GRACE_MS;
+        forceKillTimer = setTimeout(() => {
+          signalSampleProcess(proc, "SIGKILL");
+        }, TIMEOUT_KILL_GRACE_MS).unref?.();
+      }, params.timeoutMs);
+      timeout.unref?.();
+
+      proc.stdout?.on("data", (chunk) => {
+        markFirstOutput();
+        stdout = appendLimited(stdout, chunk, maxOutputLength);
+      });
+      proc.stderr?.on("data", (chunk) => {
+        markFirstOutput();
+        stderr = appendLimited(stderr, chunk, maxOutputLength);
+      });
+      proc.once("error", (error) => {
+        clearTimeout(timeout);
+        stderr = appendLimited(
+          stderr,
+          error instanceof Error ? error.message : String(error),
+          maxOutputLength,
+        );
+        finish({
+          exitCode: null,
+          signal: null,
+          stdoutTail: tailLines(stdout, 20),
+          stderrTail: tailLines(stderr, 20),
+        });
+      });
+      proc.once("close", (code, signal) => {
+        clearTimeout(timeout);
+        const complete = () =>
+          finish({
+            exitCode: code,
+            signal,
+            ...(code === 0 && signal == null
+              ? {}
+              : {
+                  stdoutTail: tailLines(stdout, 20),
+                  stderrTail: tailLines(stderr, 20),
+                }),
+          });
+        if (timedOut && isSampleProcessGroupAlive(proc)) {
+          void finishAfterTimeoutCleanup({
+            complete,
+            forceKillAt,
+            proc,
+          });
+          return;
+        }
+        complete();
+      });
+    });
+  } finally {
+    if (memoryDirectory) {
+      rmSync(memoryDirectory, { recursive: true, force: true });
+    }
+    if (ownsRunRoot) {
+      removeSampleRoot(runRoot, transport);
+    }
+  }
+}
+
+async function finishAfterTimeoutCleanup(params: {
+  complete: () => void;
+  forceKillAt: number | null;
+  proc: ReturnType<typeof spawn>;
+}): Promise<void> {
+  const graceRemainingMs =
+    params.forceKillAt === null
+      ? TIMEOUT_KILL_GRACE_MS
+      : Math.max(0, params.forceKillAt - Date.now());
+  if (graceRemainingMs > 0) {
+    await waitForSampleProcessGroupExit(params.proc, graceRemainingMs);
+  }
+  if (isSampleProcessGroupAlive(params.proc)) {
+    signalSampleProcess(params.proc, "SIGKILL");
+  }
+  await waitForSampleProcessGroupExit(params.proc, TIMEOUT_KILL_GRACE_MS);
+  params.complete();
+}
+
+function signalSampleProcess(proc: ReturnType<typeof spawn>, signal: NodeJS.Signals): void {
+  if (!proc.pid) {
+    return;
+  }
+  const handleSignalError = (error: unknown) => {
+    const code = (error as NodeJS.ErrnoException | undefined)?.code;
+    if (code !== "ESRCH" && code !== "EPERM") {
+      throw error;
+    }
+  };
+  terminateManagedChild(proc, signal, {
+    onChildSignalError: handleSignalError,
+    onProcessGroupSignalError: handleSignalError,
+    processGroupFallback: "never",
+    useWindowsTaskkill: false,
+  });
+}
+
+function isSampleProcessGroupAlive(proc: ReturnType<typeof spawn>): boolean {
+  return inspectManagedProcessGroup(proc, { errorPolicy: "alive-on-eperm" }) === "live";
+}
+
+function waitForSampleProcessGroupExit(
+  proc: ReturnType<typeof spawn>,
+  timeoutMs: number,
+): Promise<boolean> {
+  return waitForManagedProcessGroupExit(proc, timeoutMs, { errorPolicy: "alive-on-eperm" });
+}
+
+async function runCase(params: {
+  entry: string;
+  commandCase: CommandCase;
+  runs: number;
+  warmup: number;
+  timeoutMs: number;
+  runtimeRss: boolean;
+  cpuProfDir?: string;
+  heapProfDir?: string;
+  rssHookPath: string;
+}): Promise<CaseRuns> {
+  const warmupSamples: Sample[] = [];
+  const samples: Sample[] = [];
+  const totalRuns = params.warmup + params.runs;
+  const transport = sampleTransport();
+  const caseRunRoot =
+    params.commandCase.stateScope === "case" ? createSampleRoot(transport) : undefined;
+  try {
+    for (let i = 0; i < totalRuns; i += 1) {
+      const sample = await runSample({ ...params, runRoot: caseRunRoot });
+      if (i < params.warmup) {
+        warmupSamples.push(sample);
+        continue;
+      }
+      samples.push(sample);
+    }
+    return { warmupSamples, samples };
+  } finally {
+    if (caseRunRoot) {
+      removeSampleRoot(caseRunRoot, transport);
+    }
+  }
+}
+
+function tailLines(value: string, maxLines: number): string {
+  return value.split(/\r?\n/).filter(Boolean).slice(-maxLines).join("\n");
+}
+
+function printSuite(result: SuiteResult): void {
+  console.log(`Entry: ${result.entry}`);
+  console.log(`RSS metric: ${cliStartupMemoryMetric(result)}`);
+  for (const commandCase of result.cases) {
+    const { durationMs, firstOutputMs, maxRssMb, exitSummary } = commandCase.summary;
+    const rssSummary =
+      maxRssMb == null
+        ? "rss=n/a"
+        : `rss(avg=${formatMb(maxRssMb.avg)} p50=${formatMb(maxRssMb.p50)} p95=${formatMb(maxRssMb.p95)})`;
+    const firstOutputSummary =
+      firstOutputMs == null
+        ? "first-output=n/a"
+        : `first-output(avg=${formatMs(firstOutputMs.avg)} p50=${formatMs(
+            firstOutputMs.p50,
+          )} p95=${formatMs(firstOutputMs.p95)})`;
+    console.log(
+      `${commandCase.name.padEnd(24)} avg=${formatMs(durationMs.avg)} p50=${formatMs(
+        durationMs.p50,
+      )} p95=${formatMs(durationMs.p95)} min=${formatMs(durationMs.min)} max=${formatMs(
+        durationMs.max,
+      )} ${firstOutputSummary} ${rssSummary} exits=[${exitSummary}]`,
+    );
+  }
+  console.log("");
+}
+
+function printDelta(primary: SuiteResult, secondary: SuiteResult): void {
+  const deltas = buildCaseDeltas(primary, secondary);
+  console.log("Delta (secondary - primary, avg)");
+  for (const delta of deltas) {
+    const durationDelta = delta.durationAvgDeltaMs;
+    const durationPct = delta.durationAvgDeltaPct;
+    const durationSign = durationDelta > 0 ? "+" : "";
+    let line = `${delta.name.padEnd(24)} ${durationSign}${formatMs(durationDelta)} (${durationSign}${durationPct.toFixed(1)}%)`;
+    if (delta.maxRssAvgDeltaMb != null && delta.maxRssAvgDeltaPct != null) {
+      const rssDelta = delta.maxRssAvgDeltaMb;
+      const rssPct = delta.maxRssAvgDeltaPct;
+      const rssSign = rssDelta > 0 ? "+" : "";
+      line += ` rss ${rssSign}${formatMb(rssDelta)} (${rssSign}${rssPct.toFixed(1)}%)`;
+    }
+    console.log(line);
+  }
+}
+
+function buildCaseDeltas(primary: SuiteResult, secondary: SuiteResult): CaseDelta[] {
+  assertCompatibleCliStartupExecutionModes(primary, secondary);
+  assertCompatibleCliStartupMemoryMetrics(primary, secondary);
+  const primaryById = new Map(primary.cases.map((commandCase) => [commandCase.id, commandCase]));
+  const deltas: CaseDelta[] = [];
+  for (const commandCase of secondary.cases) {
+    const baseline = primaryById.get(commandCase.id);
+    if (!baseline) {
+      continue;
+    }
+    const durationDelta = commandCase.summary.durationMs.avg - baseline.summary.durationMs.avg;
+    const durationPct =
+      baseline.summary.durationMs.avg > 0
+        ? (durationDelta / baseline.summary.durationMs.avg) * 100
+        : 0;
+    const rssDelta =
+      baseline.summary.maxRssMb && commandCase.summary.maxRssMb
+        ? commandCase.summary.maxRssMb.avg - baseline.summary.maxRssMb.avg
+        : null;
+    const rssPct =
+      rssDelta != null && baseline.summary.maxRssMb && baseline.summary.maxRssMb.avg > 0
+        ? (rssDelta / baseline.summary.maxRssMb.avg) * 100
+        : null;
+    deltas.push({
+      id: commandCase.id,
+      name: commandCase.name,
+      durationAvgDeltaMs: durationDelta,
+      durationAvgDeltaPct: durationPct,
+      maxRssAvgDeltaMb: rssDelta,
+      maxRssAvgDeltaPct: rssPct,
+    });
+  }
+  return deltas;
+}
+
+export function collectFailedSamples(result: SuiteResult): string[] {
+  const failures: string[] = [];
+  for (const commandCase of result.cases) {
+    if (commandCase.samples.length === 0) {
+      failures.push(`${result.entry} ${commandCase.id}: no measured samples`);
+    }
+    for (const [sampleKind, samples] of [
+      ["warmup", commandCase.warmupSamples ?? []],
+      ["sample", commandCase.samples],
+    ] as const) {
+      for (const [sampleIndex, sample] of samples.entries()) {
+        const label = `${result.entry} ${commandCase.id} ${sampleKind} ${sampleIndex + 1}`;
+        const expectedExitCodes = new Set(commandCase.expectedExitCodes ?? [0]);
+        if (sample.timedOut === true) {
+          failures.push(`${label}: timed out`);
+        } else if (sample.signal !== null) {
+          failures.push(`${label}: exited via signal ${sample.signal}`);
+        } else if (!expectedExitCodes.has(sample.exitCode ?? -1)) {
+          failures.push(`${label}: exited with code ${String(sample.exitCode)}`);
+        } else if (sample.maxRssMb === null) {
+          failures.push(
+            `${label}: did not report max RSS${sample.memory?.error ? ` (${sample.memory.error})` : ""}`,
+          );
+        } else if (sample.exitCode !== 0) {
+          const output = `${sample.stdoutTail ?? ""}\n${sample.stderrTail ?? ""}`;
+          const missing = (commandCase.expectedNonzeroOutputIncludes ?? []).filter(
+            (snippet) => !output.includes(snippet),
+          );
+          if (missing.length > 0) {
+            failures.push(
+              `${label}: exited with expected code ${String(
+                sample.exitCode,
+              )} but output did not match expected clean-state markers (${missing.join(", ")})`,
+            );
+          }
+        }
+      }
+    }
+  }
+  return failures;
+}
+
+async function buildSuiteResult(params: {
+  entry: string;
+  executionMode: CliStartupExecutionMode;
+  options: CliOptions;
+  rssHookPath: string;
+}): Promise<SuiteResult> {
+  const cases = [];
+  for (const commandCase of params.options.cases) {
+    const { warmupSamples, samples } = await runCase({
+      entry: params.entry,
+      commandCase,
+      runs: params.options.runs,
+      warmup: params.options.warmup,
+      timeoutMs: params.options.timeoutMs,
+      runtimeRss: params.options.runtimeRss,
+      cpuProfDir: params.options.cpuProfDir,
+      heapProfDir: params.options.heapProfDir,
+      rssHookPath: params.rssHookPath,
+    });
+    cases.push({
+      id: commandCase.id,
+      name: commandCase.name,
+      args: commandCase.args,
+      ...(commandCase.expectedExitCodes && commandCase.expectedExitCodes.some((code) => code !== 0)
+        ? { expectedExitCodes: [...commandCase.expectedExitCodes] }
+        : {}),
+      ...(commandCase.expectedNonzeroOutputIncludes
+        ? { expectedNonzeroOutputIncludes: [...commandCase.expectedNonzeroOutputIncludes] }
+        : {}),
+      contract:
+        commandCase.firstOutputBudgetMs != null || commandCase.exitBudgetMs != null
+          ? {
+              firstOutputBudgetMs: commandCase.firstOutputBudgetMs ?? null,
+              exitBudgetMs: commandCase.exitBudgetMs ?? null,
+            }
+          : null,
+      warmupSamples,
+      samples,
+      summary: summarizeSamples(samples),
+    });
+  }
+  return {
+    entry: params.entry,
+    executionMode: params.executionMode,
+    ...(params.options.runtimeRss ? { memoryMetric: CLI_RUNTIME_MEMORY_METRIC } : {}),
+    cases,
+  };
+}
+
+function parseOptions(): CliOptions {
+  const presets = parsePresets(parseFlagValue("--preset"));
+  const cases = resolveCases({
+    presets,
+    caseIds: parseRepeatableFlag("--case"),
+  });
+  return {
+    cases,
+    compareBaseline: parseFlagValue("--compare-baseline"),
+    compareCandidate: parseFlagValue("--compare-candidate"),
+    entryPrimary: parseFlagValue("--entry-primary") ?? parseFlagValue("--entry") ?? DEFAULT_ENTRY,
+    entrySecondary: parseFlagValue("--entry-secondary"),
+    runs: parsePositiveInt(parseFlagValue("--runs"), DEFAULT_RUNS, "--runs"),
+    warmup: parseNonNegativeInt(parseFlagValue("--warmup"), DEFAULT_WARMUP, "--warmup"),
+    timeoutMs: parsePositiveInt(parseFlagValue("--timeout-ms"), DEFAULT_TIMEOUT_MS, "--timeout-ms"),
+    runtimeRss: hasFlag("--runtime-rss"),
+    json: hasFlag("--json"),
+    output: parseFlagValue("--output"),
+    cpuProfDir: parseFlagValue("--cpu-prof-dir"),
+    heapProfDir: parseFlagValue("--heap-prof-dir"),
+  };
+}
+
+function printUsage(): void {
+  console.log(`OpenClaw CLI benchmark
+
+Usage:
+  pnpm tsx scripts/bench-cli-startup.ts [options]
+
+Options:
+  --preset <startup|real|response|all>
+                               Command preset to run (default: startup)
+  --case <id>                  Specific case id to run; repeatable
+  --entry <path>               Primary entry file (default: openclaw.mjs)
+  --entry-secondary <path>     Secondary entry file for avg delta comparison
+  --runs <n>                   Measured runs per case (default: ${DEFAULT_RUNS})
+  --warmup <n>                 Warmup runs per case (default: ${DEFAULT_WARMUP})
+  --timeout-ms <ms>            Per-run timeout (default: ${DEFAULT_TIMEOUT_MS})
+  --output <path>              Write machine-readable JSON to a file
+  --compare-baseline <path>    Read a saved JSON report as the baseline
+  --compare-candidate <path>   Read a saved JSON report as the candidate and print deltas
+  --cpu-prof-dir <dir>         Write V8 CPU profiles for each run
+  --heap-prof-dir <dir>        Write V8 heap profiles for each run
+  --runtime-rss                Attribute RSS to the CLI runtime (default: legacy last marker)
+  --json                       Emit machine-readable JSON
+  --help                       Show this text
+
+Case ids:
+  ${COMMAND_CASES.map((commandCase) => `${commandCase.id} (${commandCase.name})`).join("\n  ")}
+`);
+}
+
+function readBenchmarkReport(filePath: string): BenchmarkReport {
+  return JSON.parse(readFileSync(filePath, "utf8")) as BenchmarkReport;
+}
+
+function writeJsonOutput(filePath: string, value: unknown): void {
+  mkdirSync(path.dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function readBenchmarkComparison(
+  baselinePath: string,
+  candidatePath: string,
+): BenchmarkComparisonResult {
+  const baseline = readBenchmarkReport(baselinePath);
+  const candidate = readBenchmarkReport(candidatePath);
+  return {
+    baseline: baseline.primary,
+    candidate: candidate.primary,
+    comparison: {
+      baseline: baselinePath,
+      candidate: candidatePath,
+      deltas: buildCaseDeltas(baseline.primary, candidate.primary),
+    },
+  };
+}
+
+async function main(): Promise<void> {
+  validateCliArgs();
+  if (hasFlag("--help")) {
+    printUsage();
+    return;
+  }
+
+  const options = parseOptions();
+  const transport = sampleTransport();
+  if (transport && options.runtimeRss) {
+    throw new Error("Cross-user runtime RSS sampling is not supported");
+  }
+  if (transport && (options.cpuProfDir || options.heapProfDir)) {
+    throw new Error(
+      "Cross-user CLI profiles must be collected through the SUT diagnostic exporter",
+    );
+  }
+  if (options.compareBaseline || options.compareCandidate) {
+    if (!options.compareBaseline || !options.compareCandidate) {
+      throw new Error("--compare-baseline and --compare-candidate must be provided together");
+    }
+    const { baseline, candidate, comparison } = readBenchmarkComparison(
+      options.compareBaseline,
+      options.compareCandidate,
+    );
+    if (options.output) {
+      writeJsonOutput(options.output, comparison);
+    }
+    if (options.json) {
+      console.log(JSON.stringify(comparison, null, 2));
+      return;
+    }
+    printDelta(baseline, candidate);
+    return;
+  }
+  const tmpDir = mkdtempSync(path.join(os.tmpdir(), "openclaw-cli-bench-"));
+  const rssHookPath = options.runtimeRss ? buildRuntimeRssHook(tmpDir) : buildRssHook(tmpDir);
+  try {
+    const primary = await buildSuiteResult({
+      entry: options.entryPrimary,
+      executionMode: transport ? "transport" : "native",
+      options,
+      rssHookPath,
+    });
+    const secondary = options.entrySecondary
+      ? await buildSuiteResult({
+          entry: options.entrySecondary,
+          executionMode: transport ? "transport" : "native",
+          options,
+          rssHookPath,
+        })
+      : undefined;
+
+    const report = {
+      node: process.version,
+      runs: options.runs,
+      warmup: options.warmup,
+      timeoutMs: options.timeoutMs,
+      cpuProfDir: options.cpuProfDir ?? null,
+      heapProfDir: options.heapProfDir ?? null,
+      primary,
+      secondary: secondary ?? null,
+    };
+    const failures = [
+      ...collectFailedSamples(primary),
+      ...(secondary ? collectFailedSamples(secondary) : []),
+    ];
+
+    if (options.output) {
+      writeJsonOutput(options.output, report);
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+      if (failures.length > 0) {
+        process.exitCode = 1;
+        for (const failure of failures) {
+          console.error(`[startup-bench] ${failure}`);
+        }
+      }
+      return;
+    }
+
+    console.log(`Node: ${process.version}`);
+    console.log(`Runs per case: ${options.runs}`);
+    console.log(`Warmup runs per case: ${options.warmup}`);
+    console.log(`Timeout: ${options.timeoutMs}ms`);
+    if (options.cpuProfDir) {
+      console.log(`CPU profiles: ${options.cpuProfDir}`);
+    }
+    if (options.heapProfDir) {
+      console.log(`Heap profiles: ${options.heapProfDir}`);
+    }
+    console.log("");
+
+    console.log("Primary entry");
+    printSuite(primary);
+    if (secondary) {
+      console.log("Secondary entry");
+      printSuite(secondary);
+      printDelta(primary, secondary);
+    }
+
+    if (failures.length > 0) {
+      process.exitCode = 1;
+      console.error("\nFailed startup benchmark samples:");
+      for (const failure of failures) {
+        console.error(`- ${failure}`);
+      }
+    }
+  } finally {
+    rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+export const testing = {
+  buildConfigFixture,
+  collectFailedSamples,
+  nodeImportSpecifierForPath,
+  parseGatewayPortEnv,
+  parseNonNegativeInt,
+  parsePositiveInt,
+  validateCliArgs,
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  await main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

scripts/bench-gateway-concurrency.ts

@@ -0,0 +1,2569 @@
+import { spawn, type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
+// Bench Gateway Concurrency script measures gateway probes during synthetic streaming turns.
+import { randomUUID } from "node:crypto";
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { request } from "node:http";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { pathToFileURL } from "node:url";
+import type { ModelsListResult } from "../packages/gateway-protocol/src/schema/agents-models-skills.js";
+import { asFiniteNumber } from "../packages/normalization-core/src/number-coercion.ts";
+import { isRecord } from "../packages/normalization-core/src/record-coerce.ts";
+import { sliceUtf16Safe } from "../packages/normalization-core/src/utf16-slice.ts";
+import type { SessionsListResult } from "../src/gateway/session-utils.types.js";
+import { applyMockOpenAiModelConfig } from "./e2e/lib/fixtures/mock-openai-config.mjs";
+import {
+  startGatewayBrowserProbe,
+  type BrowserSessionClick,
+  type BrowserSessionTarget,
+} from "./lib/gateway-bench-browser.ts";
+import { delay, stopChild } from "./lib/gateway-bench-child.ts";
+import {
+  type GatewayMemorySample,
+  type GatewayRpc,
+  getFreePort,
+  readGatewayMemory,
+  readProcessRssMb,
+} from "./lib/gateway-bench-probes.ts";
+import {
+  controlGatewayProfile,
+  measureGatewayCpuUsage,
+  readGatewayCpuProfile,
+  readGatewayCpuUsage,
+  readGatewayHeapProfile,
+  type GatewayHeapProfile,
+  type GatewayCpuProfile,
+  type GatewayCpuUsage,
+} from "./lib/gateway-bench-profile.ts";
+import {
+  BASE_GATEWAY_BENCH_CONFIG,
+  buildGatewayBenchChildArgs,
+  CliArgumentError,
+  createGatewayBenchEnv,
+  hasFlag,
+  hasHelpFlag,
+  parseFlagValue,
+  parseNonNegativeInt,
+  parsePositiveInt,
+  resolveEntry,
+  resolveOutputPath,
+  validateCliArgs,
+  waitForInitialProbe,
+  writeGatewayBenchConfig,
+  writePluginFixtures,
+} from "./lib/gateway-bench-runtime.ts";
+import { createGatewayWsClient } from "./lib/gateway-ws-client.ts";
+
+type MetricSummary = {
+  count: number;
+  max: number;
+  p50: number;
+  p95: number;
+  p99: number;
+};
+
+type TimedProbe = {
+  atMs: number;
+  error: string | null;
+  latencyMs: number;
+  ok: boolean;
+};
+
+type DiagnosticsTimelineSpan = {
+  durationMs?: number;
+  name?: string;
+};
+
+type ReadyProbe = TimedProbe & {
+  cpuCoreRatio: number | null;
+  degraded: boolean | null;
+  degradedSinceMs: number | null;
+  delayP99Ms: number | null;
+  delayMaxMs: number | null;
+  status: number;
+  utilization: number | null;
+};
+
+type ControlUiProbe = TimedProbe & {
+  status: number;
+};
+
+type GatewaySample = {
+  controlUi: ControlUiProbe;
+  readyz: ReadyProbe;
+  sessionsList: TimedProbe;
+};
+
+type FreshConnectionProbe = {
+  error: string | null;
+  latencyMs: number;
+  ok: boolean;
+};
+
+type GatewayChildExit = {
+  atMonotonicMicros: number;
+  exitCode: number | null;
+  signal: string | null;
+};
+
+type MainProfileArtifacts = {
+  scope: "main-isolate";
+  workersManifestPath: string;
+};
+
+type BenchmarkRun = {
+  agentCoverage?: {
+    configuredAgentIds: string[];
+    activeTurnAgentIds: string[];
+    beforeLoad: Array<{
+      agentId: string;
+      models: ModelsListResult;
+      sessions: SessionsListResult[];
+    }>;
+    completedTurns: Array<{ agentId: string; count: number }>;
+  };
+  browser?: {
+    newPageReadyMs: number;
+    initialSessionReadyMs: number | null;
+    historyMessagesPerTarget: number;
+    inventory: {
+      seededLoadSessions: number;
+      seededClickSessions: number;
+      unarchivedSessions: number;
+      retainedSessions: number;
+    };
+    clicks: BrowserSessionClick[];
+  };
+  heapProfile?: GatewayHeapProfile & MainProfileArtifacts;
+  loadCpuProfile?: GatewayCpuProfile & MainProfileArtifacts;
+  controlPlane: Array<TimedProbe & { method: string }>;
+  controlUi: ControlUiProbe[];
+  cpuUsage: GatewayCpuUsage;
+  durationMs: number;
+  freshConnection: FreshConnectionProbe;
+  gatewayExit?: Awaited<ReturnType<typeof stopChild>>;
+  gatewayProcess?: {
+    pid: number | undefined;
+    exitCode: number | null | undefined;
+    signalCode: string | null | undefined;
+    exitEvent: GatewayChildExit | undefined;
+    closeEvent: GatewayChildExit | undefined;
+  };
+  loadWindow?: { startMonotonicMicros: number; endMonotonicMicros: number };
+  history: Array<TimedProbe & { sessionKey?: string }>;
+  memory: { after: GatewayMemorySample; before: GatewayMemorySample; peakRssMb: number };
+  messageSubscriptions: TimedProbe[];
+  messageSubscriptionsDuringLoad: TimedProbe[];
+  mockRequests: ReturnType<typeof summarizeMockRequests>;
+  turnEvidence: ReturnType<ReturnType<typeof createTurnEvidence>["finish"]>;
+  probeWarmup: {
+    durationMs: number;
+    samples: GatewaySample[];
+  };
+  pluginMetadataScans: ReturnType<typeof summarizePluginMetadataScans>;
+  readyz: ReadyProbe[];
+  sessionSeedDurationMs: number;
+  sessionsList: TimedProbe[];
+  sessionUpdates: TimedProbe[];
+  setupDurationMs: number;
+  turnCount: number;
+  turnsDurationMs: number;
+};
+
+type CliOptions = {
+  agentCount: number;
+  browserHistoryMessages: number;
+  browserSessionClicks: number;
+  cadenceMs: number;
+  concurrency: number;
+  controlPlane: boolean;
+  cpuProfDir?: string;
+  loadCpuProfDir?: string;
+  heapProfDir?: string;
+  diagnosticsTimeline: boolean;
+  entry: string;
+  historyBurst: number;
+  historyClients: number;
+  historyMessages: number;
+  historyMessageChars: number;
+  json: boolean;
+  maxControlMs?: number;
+  maxHandshakeMs?: number;
+  output?: string;
+  pluginCount: number;
+  probeRounds?: number;
+  runs: number;
+  sessionCount: number;
+  sessionUpdateClients: number;
+  sessionUpdates: number;
+  streamChunkDelayMs: number;
+  subscribers: number;
+  timeoutMs: number;
+  toolEvents: boolean;
+  turnsPerSession: number;
+  visibleObserver: boolean;
+  warmup: number;
+  workspaceFanout: boolean;
+};
+
+const DEFAULT_CADENCE_MS = 100;
+const DEFAULT_CONCURRENCY = 8;
+const DEFAULT_ENTRY = "dist/entry.js";
+const DEFAULT_RUNS = 1;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_WARMUP = 0;
+const MOCK_RESPONSE_CHUNK_DELAY_MS = 1_000;
+const MAX_AGENT_COUNT = 128;
+const MAX_CONCURRENCY = 64;
+const MAX_TURNS_PER_SESSION = 100;
+const MAX_PLUGIN_COUNT = 100;
+const MAX_SESSION_COUNT = 10_000;
+const MAX_SESSION_UPDATES = 100_000;
+const MAX_SESSION_SEED_CONCURRENCY = 16;
+const MAX_RUNS = 20;
+const MAX_WARMUP = 10;
+const MAX_SAMPLES_PER_RUN = 2_048;
+const MAX_HTTP_BODY_BYTES = 1_048_576;
+const HTTP_TIMEOUT_MS = 20_000;
+const PROBE_WARMUP_TIMEOUT_MS = 60_000;
+const PROBE_WARMUP_TARGET_MS = 1_000;
+const PROBE_WARMUP_RETRY_DELAY_MS = 100;
+const GATEWAY_STDERR_TAIL_LINES = 20;
+const AGENT_WAIT_RPC_GRACE_MS = 5_000;
+const UTILITY_MODEL_ID = "gateway-bench-utility";
+const OBSERVER_ASSESSMENT = "Synthetic benchmark observation is valid.";
+const MOCK_INGRESS_KEYS = ["responses", "chatCompletions", "embeddings", "other"] as const;
+const MOCK_SELECTION_KEYS = ["model", "global", "automaticTool", "automaticText"] as const;
+type MockRequestSnapshot = {
+  id: string;
+  ingress: Record<(typeof MOCK_INGRESS_KEYS)[number], number>;
+  selections: Record<(typeof MOCK_SELECTION_KEYS)[number], number>;
+  beforeMs: number;
+  afterMs: number;
+};
+const BOOLEAN_FLAGS = new Set([
+  "--help",
+  "-h",
+  "--json",
+  "--control-plane",
+  "--no-diagnostics-timeline",
+  "--tool-events",
+  "--visible-observer",
+  "--workspace-fanout",
+]);
+const VALUE_FLAGS = new Set([
+  "--agent-count",
+  "--browser-history-messages",
+  "--browser-session-clicks",
+  "--cadence-ms",
+  "--concurrency",
+  "--cpu-prof-dir",
+  "--load-cpu-prof-dir",
+  "--heap-prof-dir",
+  "--entry",
+  "--history-burst",
+  "--history-clients",
+  "--history-messages",
+  "--history-message-chars",
+  "--max-control-ms",
+  "--max-handshake-ms",
+  "--output",
+  "--plugin-count",
+  "--probe-rounds",
+  "--runs",
+  "--session-count",
+  "--session-update-clients",
+  "--session-updates",
+  "--stream-chunk-delay-ms",
+  "--subscribers",
+  "--timeout-ms",
+  "--turns-per-session",
+  "--warmup",
+]);
+
+function parseBoundedPositiveInt(
+  raw: string | undefined,
+  fallback: number,
+  label: string,
+  max: number,
+): number {
+  const value = parsePositiveInt(raw, fallback, label);
+  if (value > max) {
+    throw new CliArgumentError(`${label} must be at most ${max}`);
+  }
+  return value;
+}
+
+function parseBoundedNonNegativeInt(
+  raw: string | undefined,
+  fallback: number,
+  label: string,
+  max: number,
+): number {
+  const value = parseNonNegativeInt(raw, fallback, label);
+  if (value > max) {
+    throw new CliArgumentError(`${label} must be at most ${max}`);
+  }
+  return value;
+}
+
+function parseOptions(argv: string[] = process.argv.slice(2)): CliOptions {
+  validateCliArgs(argv, { booleanFlags: BOOLEAN_FLAGS, valueFlags: VALUE_FLAGS });
+  const options = {
+    agentCount: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--agent-count"),
+      1,
+      "--agent-count",
+      MAX_AGENT_COUNT,
+    ),
+    browserHistoryMessages: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--browser-history-messages"),
+      80,
+      "--browser-history-messages",
+      500,
+    ),
+    browserSessionClicks: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--browser-session-clicks"),
+      0,
+      "--browser-session-clicks",
+      20,
+    ),
+    cadenceMs: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--cadence-ms"),
+      DEFAULT_CADENCE_MS,
+      "--cadence-ms",
+      5_000,
+    ),
+    concurrency: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--concurrency"),
+      DEFAULT_CONCURRENCY,
+      "--concurrency",
+      MAX_CONCURRENCY,
+    ),
+    controlPlane: hasFlag(argv, "--control-plane"),
+    cpuProfDir: resolveOutputPath(parseFlagValue(argv, "--cpu-prof-dir")),
+    loadCpuProfDir: resolveOutputPath(parseFlagValue(argv, "--load-cpu-prof-dir")),
+    heapProfDir: resolveOutputPath(parseFlagValue(argv, "--heap-prof-dir")),
+    diagnosticsTimeline: !hasFlag(argv, "--no-diagnostics-timeline"),
+    entry: resolveEntry(parseFlagValue(argv, "--entry"), DEFAULT_ENTRY),
+    historyBurst: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--history-burst"),
+      5,
+      "--history-burst",
+      32,
+    ),
+    historyClients: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--history-clients"),
+      0,
+      "--history-clients",
+      MAX_CONCURRENCY,
+    ),
+    historyMessages: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--history-messages"),
+      0,
+      "--history-messages",
+      500,
+    ),
+    historyMessageChars: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--history-message-chars"),
+      1_024,
+      "--history-message-chars",
+      65_536,
+    ),
+    json: hasFlag(argv, "--json"),
+    maxControlMs: parseFlagValue(argv, "--max-control-ms")
+      ? parseBoundedPositiveInt(
+          parseFlagValue(argv, "--max-control-ms"),
+          2_000,
+          "--max-control-ms",
+          30_000,
+        )
+      : undefined,
+    maxHandshakeMs: parseFlagValue(argv, "--max-handshake-ms")
+      ? parseBoundedPositiveInt(
+          parseFlagValue(argv, "--max-handshake-ms"),
+          2_000,
+          "--max-handshake-ms",
+          30_000,
+        )
+      : undefined,
+    output: resolveOutputPath(parseFlagValue(argv, "--output")),
+    pluginCount: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--plugin-count"),
+      0,
+      "--plugin-count",
+      MAX_PLUGIN_COUNT,
+    ),
+    probeRounds:
+      parseFlagValue(argv, "--probe-rounds") === undefined
+        ? undefined
+        : parseBoundedPositiveInt(
+            parseFlagValue(argv, "--probe-rounds"),
+            1,
+            "--probe-rounds",
+            MAX_SAMPLES_PER_RUN,
+          ),
+    runs: parseBoundedPositiveInt(parseFlagValue(argv, "--runs"), DEFAULT_RUNS, "--runs", MAX_RUNS),
+    sessionCount: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--session-count"),
+      0,
+      "--session-count",
+      MAX_SESSION_COUNT,
+    ),
+    sessionUpdateClients: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--session-update-clients"),
+      4,
+      "--session-update-clients",
+      MAX_CONCURRENCY,
+    ),
+    sessionUpdates: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--session-updates"),
+      0,
+      "--session-updates",
+      MAX_SESSION_UPDATES,
+    ),
+    streamChunkDelayMs: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--stream-chunk-delay-ms"),
+      MOCK_RESPONSE_CHUNK_DELAY_MS,
+      "--stream-chunk-delay-ms",
+      30_000,
+    ),
+    subscribers: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--subscribers"),
+      0,
+      "--subscribers",
+      MAX_CONCURRENCY,
+    ),
+    timeoutMs: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--timeout-ms"),
+      DEFAULT_TIMEOUT_MS,
+      "--timeout-ms",
+      10 * 60_000,
+    ),
+    toolEvents: hasFlag(argv, "--tool-events"),
+    turnsPerSession: parseBoundedPositiveInt(
+      parseFlagValue(argv, "--turns-per-session"),
+      1,
+      "--turns-per-session",
+      MAX_TURNS_PER_SESSION,
+    ),
+    visibleObserver: hasFlag(argv, "--visible-observer"),
+    warmup: parseBoundedNonNegativeInt(
+      parseFlagValue(argv, "--warmup"),
+      DEFAULT_WARMUP,
+      "--warmup",
+      MAX_WARMUP,
+    ),
+    workspaceFanout: hasFlag(argv, "--workspace-fanout"),
+  };
+  if (options.loadCpuProfDir && options.heapProfDir) {
+    throw new CliArgumentError(
+      "--load-cpu-prof-dir and --heap-prof-dir require separate benchmark runs",
+    );
+  }
+  if (options.agentCount > Math.max(options.sessionCount, options.concurrency)) {
+    throw new CliArgumentError("--agent-count must not exceed the total session count");
+  }
+  const historyMessageCount =
+    Math.max(options.sessionCount, options.concurrency) * options.historyMessages +
+    (options.browserSessionClicks > 0
+      ? (options.browserSessionClicks + 1) * options.browserHistoryMessages
+      : 0);
+  if (
+    options.probeRounds !== undefined &&
+    options.probeRounds * options.historyClients * options.historyBurst > MAX_SAMPLES_PER_RUN
+  ) {
+    throw new CliArgumentError("fixed history workload must not exceed 2048 requests per run");
+  }
+  if (
+    historyMessageCount > 100_000 ||
+    historyMessageCount * options.historyMessageChars > 256 * 1024 * 1024
+  ) {
+    throw new CliArgumentError("synthetic history must not exceed 100000 messages or 256 MiB");
+  }
+  return options;
+}
+
+function printUsage(): void {
+  console.log(`OpenClaw Gateway concurrency benchmark
+
+Usage:
+  pnpm test:gateway:concurrency -- [options]
+  node scripts/bench-gateway-concurrency.ts [options]
+
+Options:
+  --agent-count <n> Configured agents sharing the fixed session inventory (default: 1, max: ${MAX_AGENT_COUNT})
+  --browser-history-messages <n> Messages per browser click target, independent of inventory history (default: 80, max: 500)
+  --browser-session-clicks <n> Click n existing sessions and revisit one during load (default: 0, max: 20; requires built UI and Chromium)
+  --concurrency <n>  Concurrent synthetic sessions (default: ${DEFAULT_CONCURRENCY})
+  --turns-per-session <n> Serial turns per session (default: 1, max: ${MAX_TURNS_PER_SESSION})
+  --control-plane   Also probe tasks.list, cron.list, and cron.status during load
+  --history-messages <n> Inject up to 500 synthetic messages per seeded session
+  --history-message-chars <n> Synthetic message size (default: 1024, max: 65536)
+  --cpu-prof-dir <p> Write Gateway V8 CPU profiles to this directory
+  --load-cpu-prof-dir <p> Capture load-phase main/Worker CPU over private IPC, including on Windows
+  --heap-prof-dir <p> Sample load-phase main/Worker allocations, including GC-collected objects
+  --runs <n>         Measured gateway runs (default: ${DEFAULT_RUNS})
+  --warmup <n>       Warmup gateway runs (default: ${DEFAULT_WARMUP})
+  --cadence-ms <ms>  Probe cadence (default: ${DEFAULT_CADENCE_MS})
+  --probe-rounds <n> Run exactly n sampler rounds and n bursts per history client
+  --timeout-ms <ms>  Per-run cap, excluding probe warmup (default: ${DEFAULT_TIMEOUT_MS})
+  --entry <path>     Gateway CLI entry file (default: ${DEFAULT_ENTRY})
+  --session-count <n> Seed up to ${MAX_SESSION_COUNT} distinct sessions before load
+  --session-updates <n> Bounded public sessions.patch mutations during load
+  --session-update-clients <n> Concurrent session mutation clients (default: 4)
+  --history-clients <n> Concurrent dedicated history-prefetch WebSocket clients
+  --history-burst <n> Parallel history requests per prefetch client (default: 5)
+  --subscribers <n> Dedicated session-message subscription clients
+  --stream-chunk-delay-ms <n> Mock-provider delay between stream chunks (default: ${MOCK_RESPONSE_CHUNK_DELAY_MS})
+  --visible-observer Mark subscribed clients visible to exercise session observation
+  --no-diagnostics-timeline Disable diagnostics timeline file writes
+  --plugin-count <n> Configure synthetic plugins through plugins.load.paths (default: 0)
+  --tool-events      Make every synthetic turn execute a tool before replying
+  --workspace-fanout Bind each session to a distinct workspace
+  --max-control-ms   Fail when any load-phase health/control probe exceeds this bound
+  --max-handshake-ms Fail when a fresh authenticated connection exceeds this bound
+  --output <path>    Write machine-readable JSON to a file
+  --json             Emit machine-readable JSON
+  --help, -h         Show this text
+`);
+}
+
+function percentile(sorted: readonly number[], percentileValue: number): number {
+  const index = Math.max(
+    0,
+    Math.min(sorted.length - 1, Math.ceil((percentileValue / 100) * sorted.length) - 1),
+  );
+  return sorted[index] ?? 0;
+}
+
+function summarizeNumbers(values: readonly number[]): MetricSummary | null {
+  const sorted = values.filter(Number.isFinite).toSorted((a, b) => a - b);
+  if (sorted.length === 0) {
+    return null;
+  }
+  return {
+    count: sorted.length,
+    max: sorted.at(-1) ?? 0,
+    p50: percentile(sorted, 50),
+    p95: percentile(sorted, 95),
+    p99: percentile(sorted, 99),
+  };
+}
+
+function summarizePluginMetadataScans(events: readonly DiagnosticsTimelineSpan[]) {
+  const durations = events.flatMap((event) =>
+    event.name === "plugins.metadata.scan" &&
+    typeof event.durationMs === "number" &&
+    Number.isFinite(event.durationMs)
+      ? [event.durationMs]
+      : [],
+  );
+  return {
+    count: durations.length,
+    durationMs: summarizeNumbers(durations),
+    totalDurationMs: durations.reduce((sum, durationMs) => sum + durationMs, 0),
+  };
+}
+
+function readDiagnosticsTimelineSpans(
+  timelinePath: string,
+  window?: { from: number; through: number },
+): DiagnosticsTimelineSpan[] {
+  const contents = readFileSync(timelinePath, "utf8");
+  if (!contents.trim() || !contents.endsWith("\n")) {
+    throw new Error("diagnostics timeline is empty or incomplete");
+  }
+  return contents
+    .split(/\r?\n/u)
+    .filter(Boolean)
+    .flatMap((line) => {
+      const event: unknown = JSON.parse(line);
+      if (
+        !isRecord(event) ||
+        event.schemaVersion !== "openclaw.diagnostics.v1" ||
+        typeof event.timestamp !== "string" ||
+        !Number.isFinite(Date.parse(event.timestamp))
+      ) {
+        throw new Error("invalid diagnostics timeline record");
+      }
+      const timestamp = Date.parse(event.timestamp);
+      if (window && (timestamp < window.from || timestamp > window.through)) {
+        return [];
+      }
+      if (event.type !== "span.end") {
+        return [];
+      }
+      if (
+        typeof event.name !== "string" ||
+        typeof event.durationMs !== "number" ||
+        !Number.isFinite(event.durationMs)
+      ) {
+        throw new Error("invalid diagnostics timeline span");
+      }
+      return [{ name: event.name, durationMs: event.durationMs }];
+    });
+}
+
+function remainingMs(deadlineAt: number): number {
+  return Math.max(0, deadlineAt - performance.now());
+}
+
+function requireRemainingMs(deadlineAt: number, label: string): number {
+  const remaining = remainingMs(deadlineAt);
+  if (remaining <= 0) {
+    throw new Error(`benchmark timed out while ${label}`);
+  }
+  return remaining;
+}
+
+async function requestHttp(params: {
+  accept: string;
+  deadlineAt: number;
+  path: string;
+  port: number;
+}): Promise<{ body: string; latencyMs: number; status: number }> {
+  const startedAt = performance.now();
+  const requestDeadlineAt = Math.min(params.deadlineAt, startedAt + HTTP_TIMEOUT_MS);
+  requireRemainingMs(requestDeadlineAt, `requesting ${params.path}`);
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    const settle = (run: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      run();
+    };
+    const fail = (error: Error) =>
+      settle(() => {
+        req.destroy();
+        reject(error);
+      });
+    const req = request(
+      {
+        headers: { accept: params.accept },
+        host: "127.0.0.1",
+        method: "GET",
+        path: params.path,
+        port: params.port,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        let bytes = 0;
+        res.on("data", (chunk: Buffer) => {
+          bytes += chunk.length;
+          if (bytes > MAX_HTTP_BODY_BYTES) {
+            fail(new Error(`${params.path} response exceeded ${MAX_HTTP_BODY_BYTES} bytes`));
+            return;
+          }
+          chunks.push(chunk);
+        });
+        res.once("aborted", () => fail(new Error(`${params.path} response aborted`)));
+        res.once("error", fail);
+        res.once("end", () =>
+          settle(() =>
+            resolve({
+              body: Buffer.concat(chunks).toString("utf8"),
+              latencyMs: performance.now() - startedAt,
+              status: res.statusCode ?? 0,
+            }),
+          ),
+        );
+      },
+    );
+    req.once("error", fail);
+    // Request/socket timeouts measure inactivity; this timer owns the wall-clock deadline.
+    const timer = setTimeout(
+      () => fail(new Error(`${params.path} request timed out`)),
+      Math.max(1, Math.ceil(remainingMs(requestDeadlineAt))),
+    );
+    timer.unref?.();
+    req.end();
+  });
+}
+
+function describeProbeError(error: unknown): string {
+  return sliceUtf16Safe(error instanceof Error ? error.message : String(error), 0, 500);
+}
+
+function formatProbeResult(name: string, probe: TimedProbe & { status?: number }): string {
+  const status = probe.status === undefined ? "n/a" : probe.status;
+  return `${name}: ok=${probe.ok} status=${status} latencyMs=${probe.latencyMs.toFixed(1)} error=${probe.error ? JSON.stringify(probe.error) : "none"}`;
+}
+
+function formatProbeFailure(sample: GatewaySample): string {
+  return [
+    "gateway probes did not become fast and healthy before concurrent load",
+    formatProbeResult("readyz", sample.readyz),
+    formatProbeResult("sessionsList", sample.sessionsList),
+    formatProbeResult("controlUi", sample.controlUi),
+  ].join("\n  ");
+}
+
+function tailLines(output: string, lineCount: number): string {
+  return output.trimEnd().split(/\r?\n/u).slice(-lineCount).join("\n");
+}
+
+function captureChildOutput(child: ChildProcess): {
+  readOutput: () => string;
+  readStderrTail: () => string;
+} {
+  if (!child.stdout || !child.stderr) {
+    throw new Error("Gateway benchmark children require piped stdout and stderr");
+  }
+  let output = "";
+  let stderr = "";
+  const appendOutput = (chunk: Buffer) => {
+    output = sliceUtf16Safe(`${output}${chunk.toString("utf8")}`, -64 * 1_024);
+  };
+  child.stdout.on("data", appendOutput);
+  child.stderr.on("data", (chunk: Buffer) => {
+    appendOutput(chunk);
+    stderr = sliceUtf16Safe(`${stderr}${chunk.toString("utf8")}`, -64 * 1_024);
+  });
+  return {
+    readOutput: () => output,
+    readStderrTail: () => tailLines(stderr, GATEWAY_STDERR_TAIL_LINES),
+  };
+}
+
+function formatRunFailure(
+  error: unknown,
+  gatewayOutput: { readOutput: () => string; readStderrTail: () => string },
+  mockOutput: { readOutput: () => string },
+): string {
+  return [
+    error instanceof Error ? error.message : String(error),
+    gatewayOutput.readStderrTail()
+      ? `gateway stderr tail:\n${gatewayOutput.readStderrTail()}`
+      : "gateway stderr tail: (empty)",
+    gatewayOutput.readOutput() ? `gateway output tail:\n${gatewayOutput.readOutput()}` : "",
+    mockOutput.readOutput() ? `mock provider output tail:\n${mockOutput.readOutput()}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+async function waitForMockServer(port: number, deadlineAt: number): Promise<void> {
+  let lastError: unknown;
+  while (remainingMs(deadlineAt) > 0) {
+    try {
+      const result = await requestHttp({
+        accept: "application/json",
+        deadlineAt,
+        path: "/health",
+        port,
+      });
+      if (result.status === 200) {
+        return;
+      }
+    } catch (error) {
+      lastError = error;
+    }
+    await delay(Math.min(25, remainingMs(deadlineAt)));
+  }
+  const detail =
+    lastError instanceof Error
+      ? lastError.message
+      : typeof lastError === "string"
+        ? lastError
+        : "timeout";
+  throw new Error(`mock provider did not become healthy: ${detail}`);
+}
+
+async function waitForGatewayDispatchReady(
+  readOutput: () => string,
+  deadlineAt: number,
+): Promise<void> {
+  while (remainingMs(deadlineAt) > 0) {
+    if (readOutput().includes("startup trace: sidecars.ready ")) {
+      return;
+    }
+    await delay(Math.min(25, remainingMs(deadlineAt)));
+  }
+  throw new Error("gateway did not finish dispatch-ready sidecars");
+}
+
+function parseMockRequests(value: unknown, beforeMs: number, afterMs: number): MockRequestSnapshot {
+  if (!isRecord(value) || typeof value.id !== "string" || !value.id || value.id.length > 64) {
+    throw new Error("mock request counter identity is missing");
+  }
+  const counts = <K extends string>(record: unknown, keys: readonly K[]): Record<K, number> => {
+    if (
+      !isRecord(record) ||
+      Object.keys(record).length !== keys.length ||
+      keys.some((key) => !Number.isSafeInteger(record[key]) || (record[key] as number) < 0)
+    ) {
+      throw new Error("mock request counters are invalid");
+    }
+    return Object.fromEntries(keys.map((key) => [key, record[key]])) as Record<K, number>;
+  };
+  return {
+    id: value.id,
+    ingress: counts(value.ingress, MOCK_INGRESS_KEYS),
+    selections: counts(value.selections, MOCK_SELECTION_KEYS),
+    beforeMs,
+    afterMs,
+  };
+}
+
+async function readMockRequests(port: number, deadlineAt: number): Promise<MockRequestSnapshot> {
+  const beforeMs = performance.now();
+  const response = await requestHttp({
+    accept: "application/json",
+    port,
+    path: "/health",
+    deadlineAt,
+  });
+  const afterMs = performance.now();
+  if (response.status !== 200) {
+    throw new Error(`mock request checkpoint failed: HTTP ${response.status}`);
+  }
+  return parseMockRequests(JSON.parse(response.body).requests, beforeMs, afterMs);
+}
+
+function summarizeMockRequests(checkpoints: readonly MockRequestSnapshot[]) {
+  const phases = ["startupAndWarmup", "setup", "loadBracket", "postLoad"] as const;
+  if (checkpoints.length !== phases.length + 1) {
+    throw new Error("mock request checkpoints are incomplete");
+  }
+  const first = checkpoints[0]!;
+  if (
+    [...Object.values(first.ingress), ...Object.values(first.selections)].some(
+      (count) => count !== 0,
+    )
+  ) {
+    throw new Error("mock request counters were not zero before Gateway startup");
+  }
+  for (let index = 0; index < checkpoints.length; index += 1) {
+    const current = checkpoints[index]!;
+    const previous = checkpoints[Math.max(0, index - 1)]!;
+    if (
+      current.id !== first.id ||
+      !Number.isFinite(current.beforeMs) ||
+      !Number.isFinite(current.afterMs) ||
+      current.afterMs < current.beforeMs ||
+      (index > 0 && current.beforeMs < previous.afterMs) ||
+      MOCK_INGRESS_KEYS.some((key) => current.ingress[key] < previous.ingress[key]) ||
+      MOCK_SELECTION_KEYS.some((key) => current.selections[key] < previous.selections[key])
+    ) {
+      throw new Error("mock request checkpoints changed identity or regressed");
+    }
+  }
+  const difference = (after: MockRequestSnapshot, before: MockRequestSnapshot) =>
+    Object.fromEntries(
+      MOCK_INGRESS_KEYS.map((key) => [key, after.ingress[key] - before.ingress[key]]),
+    ) as MockRequestSnapshot["ingress"];
+  return {
+    // Acknowledged HTTP brackets partition ingress, not causal work or exact CPU windows.
+    checkpoints,
+    ingress: {
+      ...Object.fromEntries(
+        phases.map((phase, index) => [
+          phase,
+          difference(checkpoints[index + 1]!, checkpoints[index]!),
+        ]),
+      ),
+      total: difference(checkpoints.at(-1)!, first),
+    },
+    selections: { ...checkpoints.at(-1)!.selections },
+  };
+}
+
+function createTurnEvidence(toolEvents: boolean) {
+  const turns = new Map<
+    string,
+    {
+      sessionKey: string;
+      toolCallId?: string;
+      toolCompleted: boolean;
+      final: boolean;
+      observer: boolean;
+    }
+  >();
+  let invalid = false;
+  return {
+    register(runId: string, sessionKey: string) {
+      if (turns.has(runId)) {
+        throw new Error("duplicate benchmark run identity");
+      }
+      turns.set(runId, { sessionKey, toolCompleted: false, final: false, observer: false });
+    },
+    onEvent(this: void, event: { event: string; payload?: unknown }) {
+      const payload = event.payload;
+      if (!isRecord(payload) || typeof payload.runId !== "string") {
+        return;
+      }
+      const turn = turns.get(payload.runId);
+      if (!turn) {
+        return;
+      }
+      if (event.event === "session.observer") {
+        if (payload.sessionKey === turn.sessionKey && payload.assessment === OBSERVER_ASSESSMENT) {
+          turn.observer = true;
+        }
+        return;
+      }
+      if (!toolEvents || event.event !== "session.tool") {
+        return;
+      }
+      // The WebSocket callback cannot throw into runTurn's promise. Retain bounded
+      // failure state through client teardown, including late duplicate results.
+      const data = payload.data;
+      if (
+        payload.sessionKey !== turn.sessionKey ||
+        !isRecord(data) ||
+        data.name !== "exec" ||
+        typeof data.toolCallId !== "string"
+      ) {
+        invalid = true;
+        return;
+      }
+      if (data.phase === "start") {
+        invalid ||= turn.toolCallId !== undefined;
+        turn.toolCallId = data.toolCallId;
+      } else if (data.phase === "result") {
+        const result = isRecord(data.result) ? data.result : {};
+        const details = isRecord(result.details) ? result.details : {};
+        invalid ||=
+          turn.toolCompleted ||
+          turn.toolCallId !== data.toolCallId ||
+          data.isError !== false ||
+          details.status !== "completed" ||
+          details.exitCode !== 0 ||
+          typeof details.aggregated !== "string" ||
+          !details.aggregated.includes("openclaw-draft-proof");
+        turn.toolCompleted = true;
+      }
+    },
+    complete(runId: string, terminalReply: unknown) {
+      const turn = turns.get(runId);
+      if (
+        !turn ||
+        turn.final ||
+        !isRecord(terminalReply) ||
+        terminalReply.disposition !== "visible" ||
+        terminalReply.text !== "OPENCLAW_E2E_DRAFTPROOF"
+      ) {
+        throw new Error("benchmark tool turn did not produce its expected visible final reply");
+      }
+      turn.final = true;
+    },
+    finish() {
+      if (
+        invalid ||
+        (toolEvents &&
+          [...turns.values()].some(
+            (turn) => !turn.toolCallId || !turn.toolCompleted || !turn.final,
+          ))
+      ) {
+        throw new Error(
+          "benchmark tool lifecycle evidence is missing, duplicated, or unsuccessful",
+        );
+      }
+      return {
+        toolTurns: toolEvents ? turns.size : 0,
+        observerModelDigestTurns: [...turns.values()].filter((turn) => turn.observer).length,
+      };
+    },
+  };
+}
+
+function buildConfig(
+  root: string,
+  mockPort: number,
+  concurrency: number,
+  pluginCount: number,
+  browserSessionClicks: number,
+  agentIds: string[],
+): string {
+  const controlUiRoot = path.join(root, "control-ui");
+  mkdirSync(controlUiRoot, { recursive: true });
+  const checkoutIndex = path.join(process.cwd(), "ui", "index.html");
+  if (browserSessionClicks > 0) {
+    const builtUi = path.join(process.cwd(), "dist", "control-ui");
+    if (!existsSync(path.join(builtUi, "index.html"))) {
+      throw new Error(
+        "--browser-session-clicks requires built Control UI assets; run pnpm ui:build",
+      );
+    }
+    cpSync(builtUi, controlUiRoot, { recursive: true });
+  } else {
+    copyFileSync(
+      existsSync(checkoutIndex)
+        ? checkoutIndex
+        : path.join(process.cwd(), "dist", "control-ui", "index.html"),
+      path.join(controlUiRoot, "index.html"),
+    );
+  }
+
+  const config = structuredClone(BASE_GATEWAY_BENCH_CONFIG) as Record<string, unknown>;
+  config.gateway = {
+    ...(config.gateway as Record<string, unknown>),
+    controlUi: { enabled: true, root: controlUiRoot },
+  };
+  applyMockOpenAiModelConfig(config, {
+    mockPort,
+    modelRef: "openai/gpt-5.6-luna",
+    utilityModelRef: `openai/${UTILITY_MODEL_ID}`,
+  });
+  const agents = config.agents as Record<string, unknown>;
+  agents.defaults = {
+    ...(agents.defaults as Record<string, unknown>),
+    maxConcurrent: concurrency,
+    heartbeat: { every: "0m" },
+  };
+  const pluginFixtures =
+    pluginCount > 0 ? writePluginFixtures(root, { count: pluginCount }) : undefined;
+  const agentList =
+    agentIds.length > 1
+      ? agentIds.map((id, index) => {
+          const workspace = path.join(root, `workspace-${id}`);
+          mkdirSync(workspace, { recursive: true });
+          return { id, default: index === 0, workspace };
+        })
+      : undefined;
+  return writeGatewayBenchConfig(root, config, { agentList, pluginFixtures });
+}
+
+async function readGatewayProtocolVersion(entry: string): Promise<number> {
+  const protocolPath = path.join(
+    path.dirname(path.resolve(entry)),
+    "gateway",
+    "protocol",
+    "index.js",
+  );
+  const protocol: unknown = await import(pathToFileURL(protocolPath).href);
+  if (
+    typeof protocol !== "object" ||
+    protocol === null ||
+    !("PROTOCOL_VERSION" in protocol) ||
+    typeof protocol.PROTOCOL_VERSION !== "number"
+  ) {
+    throw new Error(`Gateway protocol module is missing PROTOCOL_VERSION: ${protocolPath}`);
+  }
+  return protocol.PROTOCOL_VERSION;
+}
+
+async function connectGateway(
+  port: number,
+  deadlineAt: number,
+  protocolVersion: number,
+  subscribeSessions = true,
+  onEvent?: Parameters<typeof createGatewayWsClient>[0]["onEvent"],
+) {
+  let requestDeadlineAt = deadlineAt;
+  const client = createGatewayWsClient({
+    handshakeTimeoutMs: Math.min(8_000, requireRemainingMs(deadlineAt, "connecting WebSocket")),
+    openTimeoutMs: Math.min(8_000, requireRemainingMs(deadlineAt, "opening WebSocket")),
+    url: `ws://127.0.0.1:${port}`,
+    onEvent,
+  });
+  await client.waitOpen();
+
+  const requestRpc = async <T>(
+    method: string,
+    params: unknown,
+    requestedTimeoutMs?: number,
+  ): Promise<T> => {
+    const response = await client.request(
+      method,
+      params,
+      Math.max(
+        1,
+        Math.min(
+          requestedTimeoutMs ?? 65_000,
+          requireRemainingMs(requestDeadlineAt, `waiting for ${method}`),
+        ),
+      ),
+    );
+    if (!response.ok) {
+      const message =
+        response.error && typeof response.error === "object" && "message" in response.error
+          ? String(response.error.message)
+          : JSON.stringify(response.error);
+      throw new Error(`${method} failed: ${message}`);
+    }
+    return response.payload as T;
+  };
+
+  await requestRpc("connect", {
+    minProtocol: protocolVersion,
+    maxProtocol: protocolVersion,
+    client: {
+      id: "gateway-client",
+      displayName: "gateway-concurrency-benchmark",
+      version: "1.0.0",
+      platform: process.platform,
+      mode: "backend",
+    },
+    role: "operator",
+    scopes: ["operator.read", "operator.write", "operator.admin"],
+    caps: [],
+  });
+  if (subscribeSessions) {
+    await requestRpc("sessions.subscribe", {});
+  }
+  return {
+    close: client.close,
+    waitClosed: () =>
+      new Promise<void>((resolve, reject) => {
+        if (client.ws.readyState === client.ws.CLOSED) {
+          resolve();
+          return;
+        }
+        const onClose = () => {
+          clearTimeout(timer);
+          resolve();
+        };
+        const timer = setTimeout(() => {
+          client.ws.off("close", onClose);
+          reject(new Error("benchmark event client did not close"));
+        }, HTTP_TIMEOUT_MS);
+        timer.unref();
+        client.ws.once("close", onClose);
+      }),
+    request: requestRpc,
+    setDeadlineAt: (value: number) => {
+      requestDeadlineAt = value;
+    },
+  };
+}
+
+function readGatewayProcessRssMb(pid: number | undefined): number | null {
+  if (!pid) {
+    return null;
+  }
+  if (process.platform !== "linux") {
+    return readProcessRssMb(pid);
+  }
+  try {
+    const status = readFileSync(`/proc/${pid}/status`, "utf8");
+    const match = /^VmRSS:\s+(\d+)\s+kB$/mu.exec(status);
+    const rssKb = match ? Number(match[1]) : Number.NaN;
+    return Number.isFinite(rssKb) && rssKb > 0 ? rssKb / 1024 : null;
+  } catch {
+    return null;
+  }
+}
+
+async function timeRpcProbe(
+  rpc: GatewayRpc,
+  method: string,
+  params: unknown,
+  runStartedAt: number,
+): Promise<TimedProbe> {
+  const startedAt = performance.now();
+  try {
+    await rpc(method, params);
+    return {
+      atMs: startedAt - runStartedAt,
+      error: null,
+      latencyMs: performance.now() - startedAt,
+      ok: true,
+    };
+  } catch (error) {
+    return {
+      atMs: startedAt - runStartedAt,
+      error: describeProbeError(error),
+      latencyMs: performance.now() - startedAt,
+      ok: false,
+    };
+  }
+}
+
+async function runTurn(
+  rpc: GatewayRpc,
+  index: number,
+  deadlineAt: number,
+  toolEvents = false,
+  options?: {
+    onStarted?: () => void;
+    sessionKey?: string;
+    evidence?: ReturnType<typeof createTurnEvidence>;
+  },
+): Promise<void> {
+  const requestedRunId = randomUUID();
+  const sessionKey = options?.sessionKey ?? `agent:main:gateway-concurrency-${index + 1}`;
+  const evidence = options?.evidence ?? createTurnEvidence(toolEvents);
+  evidence.register(requestedRunId, sessionKey);
+  const started = await rpc<{ runId?: string; status?: string }>("agent", {
+    sessionKey,
+    message: toolEvents
+      ? `OPENCLAW_E2E_DRAFTPROOF benchmark tool stream ${index + 1}.`
+      : `Reply with benchmark stream ${index + 1}.`,
+    deliver: false,
+    idempotencyKey: requestedRunId,
+  });
+  options?.onStarted?.();
+  if (options?.evidence && started.runId !== undefined && started.runId !== requestedRunId) {
+    throw new Error("agent returned a different benchmark run identity");
+  }
+  if (started.status === "ok" && !toolEvents) {
+    return;
+  }
+  if (started.status !== "accepted" && started.status !== "ok") {
+    throw new Error(`agent ${index + 1} was not accepted: ${JSON.stringify(started)}`);
+  }
+  const remaining = requireRemainingMs(deadlineAt, `waiting for agent ${index + 1} completion`);
+  // Agent waits share the load deadline; a shorter observation cap would abort
+  // an active turn while the benchmark still has time to measure completion.
+  const waitTimeoutMs = Math.max(0, Math.floor(remaining - AGENT_WAIT_RPC_GRACE_MS));
+  const rpcTimeoutMs = Math.max(1, Math.ceil(remaining));
+  const runId = started.runId ?? requestedRunId;
+  const completed = await rpc<{ runId?: string; status?: string; terminalReply?: unknown }>(
+    "agent.wait",
+    {
+      runId,
+      timeoutMs: waitTimeoutMs,
+    },
+    rpcTimeoutMs,
+  );
+  if (completed.status !== "ok") {
+    throw new Error(`agent ${index + 1} did not complete: ${JSON.stringify(completed)}`);
+  }
+  if (completed.runId !== runId) {
+    throw new Error("agent.wait returned a different or missing benchmark run identity");
+  }
+  if (toolEvents) {
+    evidence.complete(requestedRunId, completed.terminalReply);
+  }
+}
+
+async function runSessionTurns(
+  rpc: GatewayRpc,
+  index: number,
+  deadlineAt: number,
+  options: {
+    onStarted?: () => void;
+    sessionKey: string;
+    toolEvents: boolean;
+    turnsPerSession: number;
+    evidence?: ReturnType<typeof createTurnEvidence>;
+  },
+): Promise<number> {
+  for (let turn = 0; turn < options.turnsPerSession; turn += 1) {
+    requireRemainingMs(deadlineAt, `starting session ${index + 1} turn ${turn + 1}`);
+    await runTurn(rpc, index * options.turnsPerSession + turn, deadlineAt, options.toolEvents, {
+      sessionKey: options.sessionKey,
+      onStarted: turn === 0 ? options.onStarted : undefined,
+      evidence: options.evidence,
+    });
+  }
+  return options.turnsPerSession;
+}
+
+async function sampleGateway(params: {
+  deadlineAt: number;
+  port: number;
+  rpc: GatewayRpc;
+  runStartedAt: number;
+  serial?: boolean;
+}): Promise<GatewaySample> {
+  const atMs = performance.now() - params.runStartedAt;
+  const safeHttpProbe = async (pathValue: string, accept: string) => {
+    const startedAt = performance.now();
+    try {
+      return {
+        ...(await requestHttp({
+          accept,
+          deadlineAt: params.deadlineAt,
+          path: pathValue,
+          port: params.port,
+        })),
+        error: null,
+        ok: true,
+      };
+    } catch (error) {
+      return {
+        body: "",
+        error: describeProbeError(error),
+        latencyMs: performance.now() - startedAt,
+        ok: false,
+        status: 0,
+      };
+    }
+  };
+  const probeReadyz = () => safeHttpProbe("/readyz", "application/json");
+  const probeControlUi = () => safeHttpProbe("/", "text/html");
+  const probeSessions = async () => {
+    const startedAt = performance.now();
+    try {
+      const payload = await params.rpc(
+        "sessions.list",
+        {},
+        Math.min(HTTP_TIMEOUT_MS, requireRemainingMs(params.deadlineAt, "probing sessions.list")),
+      );
+      return { error: null, latencyMs: performance.now() - startedAt, ok: true, payload };
+    } catch (error) {
+      return {
+        error: describeProbeError(error),
+        latencyMs: performance.now() - startedAt,
+        ok: false,
+        payload: null,
+      };
+    }
+  };
+  const [readyz, controlUi, sessions] = params.serial
+    ? [await probeReadyz(), await probeControlUi(), await probeSessions()]
+    : await Promise.all([probeReadyz(), probeControlUi(), probeSessions()]);
+  const readyBody = (() => {
+    if (readyz.status !== 200) {
+      return {};
+    }
+    try {
+      return JSON.parse(readyz.body) as { eventLoop?: Record<string, unknown> };
+    } catch {
+      return {};
+    }
+  })();
+  const eventLoop = readyBody.eventLoop;
+  return {
+    controlUi: {
+      atMs,
+      error:
+        controlUi.error ??
+        (controlUi.status === 200 && !controlUi.body.includes("<html")
+          ? "response body did not contain <html"
+          : null),
+      latencyMs: controlUi.latencyMs,
+      ok: controlUi.ok && controlUi.status === 200 && controlUi.body.includes("<html"),
+      status: controlUi.status,
+    },
+    readyz: {
+      atMs,
+      error: readyz.error,
+      latencyMs: readyz.latencyMs,
+      ok: readyz.ok && readyz.status === 200,
+      status: readyz.status,
+      degraded: typeof eventLoop?.degraded === "boolean" ? eventLoop.degraded : null,
+      degradedSinceMs: asFiniteNumber(eventLoop?.degradedSinceMs) ?? null,
+      delayP99Ms: asFiniteNumber(eventLoop?.delayP99Ms) ?? null,
+      delayMaxMs: asFiniteNumber(eventLoop?.delayMaxMs) ?? null,
+      utilization: asFiniteNumber(eventLoop?.utilization) ?? null,
+      cpuCoreRatio: asFiniteNumber(eventLoop?.cpuCoreRatio) ?? null,
+    },
+    sessionsList: {
+      atMs,
+      error: sessions.error,
+      latencyMs: sessions.latencyMs,
+      ok: sessions.ok,
+    },
+  };
+}
+
+async function warmGatewayProbes(params: {
+  deadlineAt: number;
+  sample: (deadlineAt: number) => Promise<GatewaySample>;
+  retryDelayMs?: number;
+  targetMs?: number;
+}): Promise<{ durationMs: number; samples: GatewaySample[] }> {
+  const startedAt = performance.now();
+  const samples: GatewaySample[] = [];
+  const targetMs = params.targetMs ?? PROBE_WARMUP_TARGET_MS;
+  while (remainingMs(params.deadlineAt) > 0) {
+    const sample = await params.sample(params.deadlineAt);
+    samples.push(sample);
+    const healthy = sample.readyz.ok && sample.sessionsList.ok && sample.controlUi.ok;
+    const fast =
+      Math.max(
+        sample.readyz.latencyMs,
+        sample.sessionsList.latencyMs,
+        sample.controlUi.latencyMs,
+      ) <= targetMs;
+    const eventLoopSettled = sample.readyz.degraded !== true;
+    if (healthy && fast && eventLoopSettled) {
+      return { durationMs: performance.now() - startedAt, samples };
+    }
+    await delay(
+      Math.min(params.retryDelayMs ?? PROBE_WARMUP_RETRY_DELAY_MS, remainingMs(params.deadlineAt)),
+    );
+  }
+  const lastSample = samples.at(-1);
+  throw new Error(
+    lastSample
+      ? formatProbeFailure(lastSample)
+      : "gateway probes did not run before the warmup deadline",
+  );
+}
+
+async function runProbeRounds(params: {
+  rounds?: number;
+  deadlineAt: number;
+  cadenceMs: number;
+  cadenceFrom: "start" | "completion";
+  runFirst: boolean;
+  shouldContinue: () => boolean;
+  stopped: () => boolean;
+  runRound: (index: number) => Promise<void>;
+}): Promise<number> {
+  let completed = 0;
+  const hasWork = () =>
+    !params.stopped() &&
+    (params.rounds === undefined
+      ? (completed === 0 && params.runFirst) || params.shouldContinue()
+      : completed < params.rounds);
+  while (hasWork()) {
+    requireRemainingMs(params.deadlineAt, "starting gateway probe round");
+    const startedAt = performance.now();
+    await params.runRound(completed);
+    completed += 1;
+    if (!hasWork()) {
+      break;
+    }
+    const elapsed = params.cadenceFrom === "start" ? performance.now() - startedAt : 0;
+    await delay(
+      Math.min(
+        Math.max(0, params.cadenceMs - elapsed),
+        requireRemainingMs(params.deadlineAt, "pacing gateway probes"),
+      ),
+    );
+  }
+  return completed;
+}
+
+async function runGatewaySample(options: {
+  agentCount: number;
+  browserHistoryMessages: number;
+  browserSessionClicks: number;
+  cadenceMs: number;
+  concurrency: number;
+  controlPlane: boolean;
+  deadlineAt: number;
+  diagnosticsTimeline: boolean;
+  entry: string;
+  cpuProfDir?: string;
+  loadCpuProfDir?: string;
+  heapProfDir?: string;
+  historyBurst: number;
+  historyClients: number;
+  historyMessages: number;
+  historyMessageChars: number;
+  pluginCount: number;
+  probeRounds?: number;
+  sessionCount: number;
+  sessionUpdateClients: number;
+  sessionUpdates: number;
+  streamChunkDelayMs: number;
+  subscribers: number;
+  timeoutMs: number;
+  toolEvents: boolean;
+  turnsPerSession: number;
+  visibleObserver: boolean;
+  workspaceFanout: boolean;
+}): Promise<BenchmarkRun> {
+  const root = mkdtempSync(path.join(tmpdir(), "openclaw-gateway-concurrency-"));
+  const [port, mockPort] = await Promise.all([getFreePort(), getFreePort()]);
+  const runStartedAt = performance.now();
+  const agentIds = Array.from({ length: options.agentCount }, (_, index) =>
+    index === 0 ? "main" : `bench-agent-${index + 1}`,
+  );
+  const timelinePath = path.join(root, "diagnostics-timeline.jsonl");
+  const responseControlPath = path.join(root, "mock-provider-responses.json");
+  const heapProfilePath = options.heapProfDir
+    ? path.resolve(options.heapProfDir, `gateway-load-${randomUUID()}.heapprofile`)
+    : undefined;
+  const loadCpuProfilePath = options.loadCpuProfDir
+    ? path.resolve(options.loadCpuProfDir, `gateway-load-${randomUUID()}.cpuprofile`)
+    : undefined;
+  const protocolVersion = await readGatewayProtocolVersion(options.entry);
+  let gateway: ChildProcess | undefined;
+  let mockProvider: ChildProcessWithoutNullStreams | undefined;
+  let client: Awaited<ReturnType<typeof connectGateway>> | undefined;
+  let browserProbe: Awaited<ReturnType<typeof startGatewayBrowserProbe>> | undefined;
+  const auxiliaryClients: Array<Awaited<ReturnType<typeof connectGateway>>> = [];
+  let probesStopped = false;
+  const probeJobs: Promise<unknown>[] = [];
+  let gatewayOutput = { readOutput: () => "", readStderrTail: () => "" };
+  let mockOutput = { readOutput: () => "", readStderrTail: () => "" };
+  let result: Omit<BenchmarkRun, "mockRequests" | "turnEvidence">;
+  const mockCheckpoints: MockRequestSnapshot[] = [];
+  const turnEvidence = createTurnEvidence(options.toolEvents);
+  let gatewayExit: Awaited<ReturnType<typeof stopChild>> | undefined;
+  let gatewayExitEvent: GatewayChildExit | undefined;
+  let gatewayCloseEvent: GatewayChildExit | undefined;
+  const readGatewayProcess = () => ({
+    pid: gateway?.pid,
+    exitCode: gateway?.exitCode,
+    signalCode: gateway?.signalCode,
+    exitEvent: gatewayExitEvent,
+    closeEvent: gatewayCloseEvent,
+  });
+  let timelineWindow: { from: number; through: number } | undefined;
+
+  try {
+    try {
+      const configPath = buildConfig(
+        root,
+        mockPort,
+        options.concurrency,
+        options.pluginCount,
+        options.browserSessionClicks,
+        agentIds,
+      );
+      writeFileSync(
+        responseControlPath,
+        JSON.stringify({
+          models: {
+            [UTILITY_MODEL_ID]: {
+              text: JSON.stringify({
+                headline: "Synthetic benchmark work is progressing.",
+                assessment: OBSERVER_ASSESSMENT,
+                health: "on-track",
+              }),
+            },
+          },
+        }),
+      );
+      mockProvider = spawn(process.execPath, ["scripts/e2e/mock-openai-server.mjs"], {
+        cwd: process.cwd(),
+        detached: process.platform !== "win32",
+        env: {
+          LANG: process.env.LANG ?? "en_US.UTF-8",
+          PATH: process.env.PATH,
+          MOCK_PORT: String(mockPort),
+          MOCK_RESPONSE_CONTROL: responseControlPath,
+          MOCK_RESPONSE_CHUNK_DELAY_MS: String(options.streamChunkDelayMs),
+          SUCCESS_MARKER: "OpenClaw gateway concurrency benchmark streaming response.",
+        },
+      });
+      mockOutput = captureChildOutput(mockProvider);
+      await waitForMockServer(mockPort, options.deadlineAt);
+      mockCheckpoints.push(await readMockRequests(mockPort, options.deadlineAt));
+
+      if (options.cpuProfDir) {
+        mkdirSync(options.cpuProfDir, { recursive: true });
+      }
+      const gatewayArgs = buildGatewayBenchChildArgs(options.entry, port);
+      gatewayArgs.unshift(
+        "--import",
+        new URL("./lib/gateway-bench-profile-preload.ts", import.meta.url).href,
+      );
+      if (heapProfilePath || loadCpuProfilePath) {
+        for (const profilePath of [heapProfilePath, loadCpuProfilePath]) {
+          if (profilePath) {
+            mkdirSync(path.dirname(profilePath), { recursive: true });
+          }
+        }
+      }
+      gateway = spawn(
+        process.execPath,
+        options.cpuProfDir
+          ? ["--cpu-prof", `--cpu-prof-dir=${options.cpuProfDir}`, ...gatewayArgs]
+          : gatewayArgs,
+        {
+          cwd: process.cwd(),
+          detached: process.platform !== "win32",
+          stdio: ["pipe", "pipe", "pipe", "ipc"],
+          env: {
+            ...createGatewayBenchEnv(root, configPath, {
+              caseEnv: {
+                ...(options.diagnosticsTimeline
+                  ? {
+                      OPENCLAW_DIAGNOSTICS: "timeline",
+                      OPENCLAW_DIAGNOSTICS_TIMELINE_PATH: timelinePath,
+                    }
+                  : {}),
+                OPENCLAW_SKIP_CHANNELS: "1",
+              },
+            }),
+            OPENAI_API_KEY: "gateway-concurrency-benchmark",
+          },
+        },
+      );
+      gateway.once("exit", (exitCode, signal) => {
+        gatewayExitEvent = {
+          atMonotonicMicros: Number(process.hrtime.bigint() / 1_000n),
+          exitCode,
+          signal,
+        };
+      });
+      gateway.once("close", (exitCode, signal) => {
+        gatewayCloseEvent = {
+          atMonotonicMicros: Number(process.hrtime.bigint() / 1_000n),
+          exitCode,
+          signal,
+        };
+      });
+      gatewayOutput = captureChildOutput(gateway);
+      const ready = await waitForInitialProbe({
+        deadlineAt: options.deadlineAt,
+        isDone: () => gateway?.exitCode != null || gateway?.signalCode != null,
+        path: "/readyz",
+        port,
+        startAt: runStartedAt,
+      });
+      if (ready.status !== 200) {
+        throw new Error(`gateway did not become ready\n${gatewayOutput.readOutput()}`);
+      }
+      await waitForGatewayDispatchReady(gatewayOutput.readOutput, options.deadlineAt);
+      client = await connectGateway(
+        port,
+        options.deadlineAt,
+        protocolVersion,
+        true,
+        turnEvidence.onEvent,
+      );
+      const rpc = client.request;
+      if (options.visibleObserver) {
+        await rpc("sessions.observer.visibility", { visible: true });
+      }
+      // The first authenticated RPC lazily imports the server-method graph. It measured 6.9s
+      // on an idle M4 Pro (previously 18.4s) and crossed 20s on Linux; hot probes took 15-40ms.
+      // Keep that cold work out of the load-phase deadline and latency distributions.
+      const probeWarmupDeadlineAt = performance.now() + PROBE_WARMUP_TIMEOUT_MS;
+      client.setDeadlineAt(probeWarmupDeadlineAt);
+      const probeWarmup = await warmGatewayProbes({
+        deadlineAt: probeWarmupDeadlineAt,
+        sample: (deadlineAt) =>
+          sampleGateway({
+            deadlineAt,
+            port,
+            rpc,
+            runStartedAt,
+          }),
+      });
+      const setupDeadlineAt = performance.now() + options.timeoutMs;
+      const setupStartedAt = performance.now();
+      mockCheckpoints.push(await readMockRequests(mockPort, setupDeadlineAt));
+      client.setDeadlineAt(setupDeadlineAt);
+      const sessionCount = Math.max(options.concurrency, options.sessionCount);
+      const prepareSessions =
+        options.agentCount > 1 ||
+        options.browserSessionClicks > 0 ||
+        options.workspaceFanout ||
+        options.sessionCount > 0 ||
+        options.historyClients > 0 ||
+        options.historyMessages > 0 ||
+        options.sessionUpdates > 0 ||
+        options.subscribers > 0;
+      const sessionAgents = Array.from(
+        { length: sessionCount },
+        (_, index) => agentIds[index % agentIds.length]!,
+      );
+      const sessionKeys = sessionAgents.map(
+        (agentId, index) => `agent:${agentId}:gateway-concurrency-${index + 1}`,
+      );
+      const sessionSeedStartedAt = performance.now();
+      if (prepareSessions) {
+        let nextSessionIndex = 0;
+        let seededSessionCount = 0;
+        await Promise.all(
+          Array.from({ length: Math.min(MAX_SESSION_SEED_CONCURRENCY, sessionCount) }, async () => {
+            for (;;) {
+              const index = nextSessionIndex++;
+              const sessionKey = sessionKeys[index];
+              if (!sessionKey) {
+                return;
+              }
+              const workspaceDir = options.workspaceFanout
+                ? path.join(root, `workspace-${index + 1}`)
+                : undefined;
+              if (workspaceDir) {
+                mkdirSync(workspaceDir, { recursive: true });
+              }
+              await rpc("sessions.create", {
+                key: sessionKey,
+                agentId: sessionAgents[index],
+                ...(workspaceDir ? { cwd: workspaceDir } : {}),
+              });
+              for (
+                let messageIndex = 0;
+                messageIndex < options.historyMessages;
+                messageIndex += 1
+              ) {
+                const marker = `Synthetic history ${index + 1}/${messageIndex + 1}. `;
+                const message = marker
+                  .repeat(Math.ceil(options.historyMessageChars / marker.length))
+                  .slice(0, options.historyMessageChars);
+                await rpc("chat.inject", { sessionKey, message });
+              }
+              seededSessionCount += 1;
+              if (sessionCount >= 250 && seededSessionCount % 250 === 0) {
+                console.error(
+                  `[bench-gateway-concurrency] seeded ${seededSessionCount}/${sessionCount} sessions`,
+                );
+              }
+            }
+          }),
+        );
+      }
+      const sessionSeedDurationMs = performance.now() - sessionSeedStartedAt;
+      const browserTargets: BrowserSessionTarget[] = [];
+      const browserHistoryMessages = options.browserHistoryMessages;
+      if (options.browserSessionClicks > 0) {
+        for (let index = 0; index <= options.browserSessionClicks; index += 1) {
+          const target = {
+            key: `agent:main:sidebar-click-${index}`,
+            marker: `Sidebar click history ${index}.`,
+          };
+          await rpc("sessions.create", { key: target.key, agentId: "main" });
+          for (let message = 0; message < browserHistoryMessages; message += 1) {
+            const prefix = `## Synthetic message ${message + 1}\n\n${target.marker}\n\n`;
+            const messageText =
+              prefix +
+              "Synthetic **benchmark** paragraph. "
+                .repeat(Math.ceil(options.historyMessageChars / 35))
+                .slice(0, Math.max(0, options.historyMessageChars - prefix.length));
+            await rpc("chat.inject", { sessionKey: target.key, message: messageText });
+          }
+          browserTargets.push(target);
+        }
+        browserProbe = await startGatewayBrowserProbe({
+          port,
+          timeoutMs: requireRemainingMs(setupDeadlineAt, "opening browser"),
+          initial: browserTargets[0]!,
+          visibleSessions: options.concurrency + browserTargets.length,
+        });
+      }
+      let browserInventory: NonNullable<BenchmarkRun["browser"]>["inventory"] | undefined;
+      if (browserProbe) {
+        const [unarchived, retained] = await Promise.all([
+          rpc<{ totalCount: number }>("sessions.list", { limit: 1, archived: false }),
+          rpc<{ totalCount: number }>("sessions.list", { limit: 1, archived: "all" }),
+        ]);
+        browserInventory = {
+          seededLoadSessions: sessionCount,
+          seededClickSessions: browserTargets.length,
+          unarchivedSessions: unarchived.totalCount,
+          retainedSessions: retained.totalCount,
+        };
+      }
+      // Normal inventory maintenance can archive older fixture sessions while seeding.
+      // Active turns and observers use the newest sessions; history still spans the inventory.
+      const turnSessionKeys = sessionKeys.slice(-options.concurrency);
+      const turnAgentIds = sessionAgents.slice(-options.concurrency);
+      const agentCoverage: BenchmarkRun["agentCoverage"] =
+        options.agentCount > 1
+          ? {
+              configuredAgentIds: agentIds,
+              activeTurnAgentIds: [...new Set(turnAgentIds)],
+              beforeLoad: [],
+              completedTurns: [],
+            }
+          : undefined;
+      if (agentCoverage) {
+        for (const agentId of agentIds) {
+          // Require published runtime facts before measuring the configured roster.
+          const models = await rpc<ModelsListResult>("models.list", {
+            agentId,
+            view: "configured",
+            refresh: false,
+          });
+          if (
+            ["gpt-5.6-luna", UTILITY_MODEL_ID].some(
+              (id) =>
+                !models.models.some((model) => model.provider === "openai" && model.id === id),
+            )
+          ) {
+            throw new Error(`Configured benchmark model is not published for ${agentId}`);
+          }
+          const storePath = path.join(
+            root,
+            "state",
+            "agents",
+            agentId,
+            "agent",
+            "openclaw-agent.sqlite",
+          );
+          const sessions: SessionsListResult[] = [];
+          let offset = 0;
+          for (;;) {
+            const page = await rpc<SessionsListResult>("sessions.list", {
+              agentId,
+              archived: "all",
+              limit: 1_000,
+              offset,
+            });
+            if (page.path !== storePath || page.count !== page.sessions.length) {
+              throw new Error(`Benchmark session store or page mismatch for ${agentId}`);
+            }
+            sessions.push(page);
+            if (!page.hasMore) {
+              break;
+            }
+            if (
+              !Number.isSafeInteger(page.nextOffset) ||
+              page.nextOffset == null ||
+              page.nextOffset <= offset ||
+              page.nextOffset > sessionCount + browserTargets.length
+            ) {
+              throw new Error(`Benchmark session pagination did not advance for ${agentId}`);
+            }
+            offset = page.nextOffset;
+          }
+          const expectedKeys = sessionKeys.filter((_, index) => sessionAgents[index] === agentId);
+          const observedRows = sessions.flatMap((page) =>
+            page.sessions.filter((row) => row.key.includes(":gateway-concurrency-")),
+          );
+          const observedKeys = new Set(observedRows.map((row) => row.key));
+          if (
+            observedRows.length !== expectedKeys.length ||
+            observedKeys.size !== expectedKeys.length ||
+            observedRows.some((row) => row.agentId !== agentId) ||
+            expectedKeys.some((key) => !observedKeys.has(key))
+          ) {
+            throw new Error(
+              `Benchmark session inventory or distinct store mismatch for ${agentId}`,
+            );
+          }
+          agentCoverage.beforeLoad.push({ agentId, models, sessions });
+        }
+      }
+      const messageSubscriptions: TimedProbe[] = [];
+      for (let index = 0; index < options.subscribers; index += 1) {
+        const subscriber = await connectGateway(port, setupDeadlineAt, protocolVersion, false);
+        auxiliaryClients.push(subscriber);
+        if (options.visibleObserver) {
+          await subscriber.request("sessions.observer.visibility", { visible: true });
+        }
+        const subscription = await timeRpcProbe(
+          subscriber.request,
+          "sessions.messages.subscribe",
+          { key: turnSessionKeys[index % turnSessionKeys.length] },
+          runStartedAt,
+        );
+        messageSubscriptions.push(subscription);
+        if (!subscription.ok) {
+          throw new Error(`session message subscription failed: ${subscription.error}`);
+        }
+      }
+      const historyClients = await Promise.all(
+        Array.from({ length: options.historyClients }, async () => {
+          const historyClient = await connectGateway(port, setupDeadlineAt, protocolVersion, false);
+          auxiliaryClients.push(historyClient);
+          return historyClient;
+        }),
+      );
+      const sessionUpdateClients = await Promise.all(
+        Array.from(
+          { length: options.sessionUpdates > 0 ? options.sessionUpdateClients : 0 },
+          async () => {
+            const updateClient = await connectGateway(
+              port,
+              setupDeadlineAt,
+              protocolVersion,
+              false,
+            );
+            auxiliaryClients.push(updateClient);
+            return updateClient;
+          },
+        ),
+      );
+      const subscriptionProbeClient =
+        options.subscribers > 0
+          ? await connectGateway(port, setupDeadlineAt, protocolVersion, false)
+          : undefined;
+      if (subscriptionProbeClient) {
+        auxiliaryClients.push(subscriptionProbeClient);
+      }
+      const memoryBefore = await readGatewayMemory(rpc, runStartedAt);
+      mockCheckpoints.push(await readMockRequests(mockPort, setupDeadlineAt));
+      if (loadCpuProfilePath) {
+        await controlGatewayProfile(gateway, "cpu", "start", loadCpuProfilePath, {
+          includeWorkers: true,
+        });
+      }
+      if (heapProfilePath) {
+        await controlGatewayProfile(gateway, "heap", "start", heapProfilePath, {
+          includeWorkers: true,
+        });
+      }
+      const setupDurationMs = performance.now() - setupStartedAt;
+      // Large session fixtures are setup, not benchmarked load. Every measured
+      // run therefore gets its complete timeout after all clients are ready.
+      const loadDeadlineAt = performance.now() + options.timeoutMs;
+      client.setDeadlineAt(loadDeadlineAt);
+      for (const auxiliaryClient of auxiliaryClients) {
+        auxiliaryClient.setDeadlineAt(loadDeadlineAt);
+      }
+      const controlPlane: BenchmarkRun["controlPlane"] = [];
+      const controlUi: ControlUiProbe[] = [];
+      const history: BenchmarkRun["history"] = [];
+      const messageSubscriptionsDuringLoad: TimedProbe[] = [];
+      const readyz: ReadyProbe[] = [];
+      const sessionsList: TimedProbe[] = [];
+      const sessionUpdates: TimedProbe[] = [];
+      let peakRssMb = memoryBefore.rssMb;
+      let lastRssSampleAt = performance.now();
+      let turnsDone = false;
+      let updatesDone = options.sessionUpdates === 0;
+      let browserDone = !browserProbe;
+      const workloadDone = () => turnsDone && updatesDone && browserDone;
+      let startedTurnCount = 0;
+      let resolveAllTurnsStarted!: () => void;
+      const allTurnsStarted = new Promise<void>((resolve) => {
+        resolveAllTurnsStarted = resolve;
+      });
+      const cpuBefore = await readGatewayCpuUsage(gateway);
+      const turnsStartedAt = performance.now();
+      // Keep the live artifact intact: buffered setup writes can arrive after this boundary.
+      // Inclusive millisecond timestamps conservatively include events on the boundary.
+      const timelineFrom = Date.now();
+      const loadStartMonotonicMicros = Number(process.hrtime.bigint() / 1_000n);
+      const turns = Promise.all(
+        turnSessionKeys.map((sessionKey, index) =>
+          runSessionTurns(rpc, index, loadDeadlineAt, {
+            onStarted: () => {
+              startedTurnCount += 1;
+              if (startedTurnCount === options.concurrency) {
+                resolveAllTurnsStarted();
+              }
+            },
+            sessionKey,
+            toolEvents: options.toolEvents,
+            turnsPerSession: options.turnsPerSession,
+            evidence: turnEvidence,
+          }),
+        ),
+      ).finally(() => {
+        turnsDone = true;
+        resolveAllTurnsStarted();
+      });
+      const freshConnection = allTurnsStarted.then(async (): Promise<FreshConnectionProbe> => {
+        const startedAt = performance.now();
+        try {
+          const freshClient = await connectGateway(port, loadDeadlineAt, protocolVersion, false);
+          freshClient.close();
+          return { error: null, latencyMs: performance.now() - startedAt, ok: true };
+        } catch (error) {
+          return {
+            error: describeProbeError(error),
+            latencyMs: performance.now() - startedAt,
+            ok: false,
+          };
+        }
+      });
+      const browserClicks = allTurnsStarted.then(async (): Promise<BrowserSessionClick[]> => {
+        try {
+          if (!browserProbe) {
+            return [];
+          }
+          const clicks: BrowserSessionClick[] = [];
+          const targets = [...browserTargets.slice(1), browserTargets.at(-2)!];
+          for (const [index, target] of targets.entries()) {
+            clicks.push(
+              await browserProbe.click(
+                target,
+                index === targets.length - 1,
+                () => !turnsDone,
+                Math.min(30_000, requireRemainingMs(loadDeadlineAt, "clicking sidebar session")),
+              ),
+            );
+          }
+          return clicks;
+        } finally {
+          browserDone = true;
+        }
+      });
+      const sampler = runProbeRounds({
+        rounds: options.probeRounds,
+        deadlineAt: loadDeadlineAt,
+        cadenceMs: options.cadenceMs,
+        cadenceFrom: "start",
+        runFirst: true,
+        shouldContinue: () => !workloadDone() && readyz.length < MAX_SAMPLES_PER_RUN,
+        stopped: () => probesStopped,
+        runRound: async () => {
+          const subscriptionKey = turnSessionKeys[readyz.length % turnSessionKeys.length];
+          const [sample, subscription, controlProbes] = await Promise.all([
+            sampleGateway({
+              deadlineAt: loadDeadlineAt,
+              port,
+              rpc,
+              runStartedAt,
+            }),
+            subscriptionProbeClient && subscriptionKey
+              ? timeRpcProbe(
+                  subscriptionProbeClient.request,
+                  "sessions.messages.subscribe",
+                  { key: subscriptionKey },
+                  runStartedAt,
+                )
+              : Promise.resolve(undefined),
+            options.controlPlane
+              ? Promise.all(
+                  ["tasks.list", "cron.list", "cron.status"].map(async (method) =>
+                    Object.assign(await timeRpcProbe(rpc, method, {}, runStartedAt), { method }),
+                  ),
+                )
+              : Promise.resolve([]),
+          ]);
+          controlPlane.push(...controlProbes);
+          if (subscription) {
+            messageSubscriptionsDuringLoad.push(subscription);
+            if (subscription.ok) {
+              await subscriptionProbeClient?.request("sessions.messages.unsubscribe", {
+                key: subscriptionKey,
+              });
+            }
+          }
+          readyz.push(sample.readyz);
+          sessionsList.push(sample.sessionsList);
+          controlUi.push(sample.controlUi);
+          if (performance.now() - lastRssSampleAt >= 1_000) {
+            // Linux reads procfs without spawning a process. Non-Linux hosts use
+            // the shared ps fallback at most once per second to bound perturbation.
+            peakRssMb = Math.max(peakRssMb, readGatewayProcessRssMb(gateway?.pid) ?? 0);
+            lastRssSampleAt = performance.now();
+          }
+        },
+      });
+      probeJobs.push(sampler);
+      const historyLoad = Promise.all(
+        historyClients.map((historyClient, clientIndex) => {
+          let offset = clientIndex * options.historyBurst;
+          const job = runProbeRounds({
+            rounds: options.probeRounds,
+            deadlineAt: loadDeadlineAt,
+            cadenceMs: options.cadenceMs,
+            cadenceFrom: "completion",
+            runFirst: false,
+            shouldContinue: () => !workloadDone() && history.length < MAX_SAMPLES_PER_RUN,
+            stopped: () => probesStopped,
+            runRound: async () => {
+              const probes = await Promise.all(
+                Array.from({ length: options.historyBurst }, (_, index) => {
+                  const sessionKey = sessionKeys[(offset + index) % sessionKeys.length]!;
+                  const probe = timeRpcProbe(
+                    historyClient.request,
+                    "chat.history",
+                    { sessionKey },
+                    runStartedAt,
+                  );
+                  return agentCoverage
+                    ? probe.then((sample) => ({ ...sample, sessionKey }))
+                    : probe;
+                }),
+              );
+              history.push(...probes);
+              offset += options.historyBurst;
+            },
+          });
+          probeJobs.push(job);
+          return job;
+        }),
+      );
+      let nextUpdateIndex = 0;
+      const sessionUpdateLoad = Promise.all(
+        sessionUpdateClients.map(async (updateClient) => {
+          for (;;) {
+            const index = nextUpdateIndex++;
+            if (index >= options.sessionUpdates) {
+              return;
+            }
+            const sessionKey = sessionKeys[index % sessionKeys.length];
+            const update = await timeRpcProbe(
+              updateClient.request,
+              "sessions.patch",
+              { key: sessionKey, label: `Benchmark update ${index + 1}` },
+              runStartedAt,
+            );
+            sessionUpdates.push(update);
+            if (!update.ok) {
+              throw new Error(`sessions.patch load probe failed: ${update.error}`);
+            }
+          }
+        }),
+      ).finally(() => {
+        updatesDone = true;
+      });
+      const [freshConnectionResult, sessionTurnCounts, browserClickResults] = await Promise.all([
+        freshConnection,
+        turns,
+        browserClicks,
+        sampler,
+        historyLoad,
+        sessionUpdateLoad,
+      ]);
+      const cpuAfter = await readGatewayCpuUsage(gateway);
+      const loadEndMonotonicMicros = Number(process.hrtime.bigint() / 1_000n);
+      const turnsDurationMs = performance.now() - turnsStartedAt;
+      const memoryAfter = await readGatewayMemory(rpc, runStartedAt);
+      timelineWindow = { from: timelineFrom, through: Date.now() };
+      let loadCpuProfile: BenchmarkRun["loadCpuProfile"];
+      if (loadCpuProfilePath) {
+        await controlGatewayProfile(gateway, "cpu", "stop", loadCpuProfilePath);
+        loadCpuProfile = {
+          ...readGatewayCpuProfile(loadCpuProfilePath),
+          scope: "main-isolate",
+          workersManifestPath: `${loadCpuProfilePath}.workers.json`,
+        };
+      }
+      let heapProfile: BenchmarkRun["heapProfile"];
+      if (heapProfilePath) {
+        await controlGatewayProfile(gateway, "heap", "stop", heapProfilePath);
+        heapProfile = {
+          ...readGatewayHeapProfile(heapProfilePath),
+          scope: "main-isolate",
+          workersManifestPath: `${heapProfilePath}.workers.json`,
+        };
+      }
+      if (options.historyClients > 0 && !history.some((sample) => sample.ok)) {
+        const failure = history[0]?.error ?? "no requests completed before turns finished";
+        throw new Error(`all configured chat.history load probes failed: ${failure}`);
+      }
+      peakRssMb = Math.max(peakRssMb, memoryAfter.rssMb);
+      mockCheckpoints.push(await readMockRequests(mockPort, loadDeadlineAt));
+
+      if (agentCoverage) {
+        agentCoverage.completedTurns = agentIds.map((agentId) => ({
+          agentId,
+          count: sessionTurnCounts.reduce(
+            (total, count, index) => total + (turnAgentIds[index] === agentId ? count : 0),
+            0,
+          ),
+        }));
+      }
+      result = {
+        ...(agentCoverage ? { agentCoverage } : {}),
+        ...(browserProbe && browserInventory
+          ? {
+              browser: {
+                newPageReadyMs: browserProbe.newPageReadyMs,
+                initialSessionReadyMs: browserProbe.initialSessionReadyMs,
+                historyMessagesPerTarget: browserHistoryMessages,
+                inventory: browserInventory,
+                clicks: browserClickResults,
+              },
+            }
+          : {}),
+        ...(heapProfile ? { heapProfile } : {}),
+        ...(loadCpuProfile ? { loadCpuProfile } : {}),
+        controlPlane,
+        controlUi,
+        cpuUsage: measureGatewayCpuUsage(cpuBefore, cpuAfter),
+        durationMs: performance.now() - runStartedAt,
+        freshConnection: freshConnectionResult,
+        history,
+        loadWindow: {
+          startMonotonicMicros: loadStartMonotonicMicros,
+          endMonotonicMicros: loadEndMonotonicMicros,
+        },
+        memory: { after: memoryAfter, before: memoryBefore, peakRssMb },
+        messageSubscriptions,
+        messageSubscriptionsDuringLoad,
+        probeWarmup,
+        pluginMetadataScans: summarizePluginMetadataScans([]),
+        readyz,
+        sessionSeedDurationMs,
+        sessionsList,
+        sessionUpdates,
+        setupDurationMs,
+        turnCount: sessionTurnCounts.reduce((sum, count) => sum + count, 0),
+        turnsDurationMs,
+      };
+    } catch (error) {
+      const detail = formatRunFailure(error, gatewayOutput, mockOutput);
+      throw new Error(detail, { cause: error });
+    } finally {
+      probesStopped = true;
+      try {
+        await browserProbe?.close();
+      } finally {
+        for (const auxiliaryClient of auxiliaryClients) {
+          auxiliaryClient.close();
+        }
+        try {
+          if (gateway) {
+            if (options.cpuProfDir && gateway.exitCode === null && gateway.signalCode === null) {
+              // V8 flushes the main-isolate CPU profile on its normal interrupt path.
+              const profileFlushed = new Promise<void>((resolve) => {
+                gateway!.once("exit", () => {
+                  resolve();
+                });
+              });
+              gateway.kill("SIGINT");
+              await Promise.race([profileFlushed, delay(2_000)]);
+            }
+            gatewayExit = await stopChild(gateway);
+          }
+          // A fatal turn may end Promise.all before fixed probe rounds settle.
+          // Join their closed-client failures before removing the fixture state.
+          await Promise.allSettled(probeJobs);
+        } finally {
+          // Gateway shutdown drains admitted event dispatches before closing sockets.
+          // Keep this client alive through that drain so delayed tool evidence survives.
+          client?.close();
+        }
+      }
+    }
+    // close() initiates a handshake; retain late event evidence until it settles.
+    await client?.waitClosed();
+    mockCheckpoints.push(await readMockRequests(mockPort, performance.now() + HTTP_TIMEOUT_MS));
+    if (options.diagnosticsTimeline) {
+      if (!gatewayExit || gatewayExit.exitCode !== 0 || gatewayExit.signal !== null) {
+        throw new Error(
+          formatRunFailure(
+            new Error(
+              `Gateway did not exit cleanly; diagnostics timeline may be incomplete: ${JSON.stringify({ helper: gatewayExit, child: readGatewayProcess() })}`,
+            ),
+            gatewayOutput,
+            mockOutput,
+          ),
+        );
+      }
+      if (gatewayOutput.readOutput().includes("[diagnostics] failed to write timeline event")) {
+        throw new Error("Gateway reported a diagnostics timeline write failure");
+      }
+      result.pluginMetadataScans = summarizePluginMetadataScans(
+        readDiagnosticsTimelineSpans(timelinePath, timelineWindow),
+      );
+    }
+    return {
+      ...result,
+      mockRequests: summarizeMockRequests(mockCheckpoints),
+      turnEvidence: turnEvidence.finish(),
+      gatewayProcess: readGatewayProcess(),
+      ...(gatewayExit ? { gatewayExit } : {}),
+    };
+  } finally {
+    try {
+      if (mockProvider) {
+        await stopChild(mockProvider);
+      }
+    } finally {
+      rmSync(root, { force: true, maxRetries: 3, recursive: true, retryDelay: 100 });
+    }
+  }
+}
+
+function summarizeRuns(
+  runs: readonly BenchmarkRun[],
+  options: Pick<CliOptions, "maxControlMs" | "maxHandshakeMs"> = {},
+) {
+  const controlPlane = runs.flatMap((run) => run.controlPlane);
+  const browserClicks = runs.flatMap((run) => run.browser?.clicks ?? []);
+  const controlUi = runs.flatMap((run) => run.controlUi);
+  const readyz = runs.flatMap((run) => run.readyz);
+  const sessionsList = runs.flatMap((run) => run.sessionsList);
+  const history = runs.flatMap((run) => run.history);
+  const subscriptions = runs.flatMap((run) => run.messageSubscriptions);
+  const subscriptionsDuringLoad = runs.flatMap((run) => run.messageSubscriptionsDuringLoad);
+  const sessionUpdates = runs.flatMap((run) => run.sessionUpdates);
+  // Setup subscriptions and warmup probes are not load-phase measurements.
+  const controlMethods = ["tasks.list", "cron.list", "cron.status"];
+  const controlMethodProbes = controlMethods.map((method) => ({
+    method,
+    samples: controlPlane.filter((sample) => sample.method === method),
+  }));
+  const budgetViolations = [
+    ...controlMethodProbes.map(({ method, samples }) => ({
+      name: `Gateway ${method} probe`,
+      maxMs: options.maxControlMs,
+      samples,
+    })),
+    {
+      name: "fresh Gateway connection",
+      maxMs: options.maxHandshakeMs,
+      samples: runs.map((run) => run.freshConnection),
+    },
+    ...(
+      [
+        ["readyz", readyz],
+        ["Control UI", controlUi],
+        ["sessions.list", sessionsList],
+        ["chat.history", history],
+        ["sessions.messages.subscribe", subscriptionsDuringLoad],
+        ["sessions.patch", sessionUpdates],
+      ] as const
+    ).map(([name, samples]) => ({
+      name: `Gateway ${name} probe`,
+      maxMs: options.maxControlMs,
+      samples,
+    })),
+  ].flatMap(({ name, maxMs, samples }) => {
+    if (maxMs === undefined) {
+      return [];
+    }
+    const violation = samples.find((sample) => !sample.ok || sample.latencyMs > maxMs);
+    return violation
+      ? [
+          `${name} exceeded ${maxMs}ms: ok=${violation.ok} ` +
+            `latencyMs=${violation.latencyMs.toFixed(1)} error=${violation.error ?? "none"}`,
+        ]
+      : [];
+  });
+  for (const sample of browserClicks) {
+    if (sample.error) {
+      budgetViolations.push(`Browser session ${sample.sessionKey} failed: ${sample.error}`);
+    }
+  }
+  return {
+    ...(browserClicks.length > 0
+      ? {
+          browserSessionClicks: {
+            failedSamples: browserClicks.filter((sample) => sample.error !== null).length,
+            samplesOutsideActiveLoad: browserClicks.filter(
+              (sample) => !sample.activeLoadAtStart || !sample.activeLoadAtFinish,
+            ).length,
+            firstVisitReadyMs: summarizeNumbers(
+              browserClicks.flatMap((sample) =>
+                !sample.revisit && sample.readyMs !== null ? [sample.readyMs] : [],
+              ),
+            ),
+            revisitReadyMs: summarizeNumbers(
+              browserClicks.flatMap((sample) =>
+                sample.revisit && sample.readyMs !== null ? [sample.readyMs] : [],
+              ),
+            ),
+          },
+        }
+      : {}),
+    budgetViolations,
+    gatewayProcessCpuMs: summarizeNumbers(runs.map((run) => run.cpuUsage.process.totalMs)),
+    gatewayProcessCpuMsPerTurn: summarizeNumbers(
+      runs.map((run) => run.cpuUsage.process.totalMs / run.turnCount),
+    ),
+    gatewayMainThreadCpuMs: summarizeNumbers(runs.map((run) => run.cpuUsage.mainThread.totalMs)),
+    gatewayProcessCpuCoreRatio: summarizeNumbers(
+      runs.map((run) => run.cpuUsage.process.totalMs / run.cpuUsage.wallMs),
+    ),
+    gatewaySampledAllocatedBytes: summarizeNumbers(
+      runs.flatMap((run) => (run.heapProfile ? [run.heapProfile.sampledAllocatedBytes] : [])),
+    ),
+    gatewaySampledAllocatedBytesPerTurn: summarizeNumbers(
+      runs.flatMap((run) =>
+        run.heapProfile ? [run.heapProfile.sampledAllocatedBytes / run.turnCount] : [],
+      ),
+    ),
+    controlPlane: Object.fromEntries(
+      controlMethodProbes.map(({ method, samples }) => [
+        method,
+        {
+          failedSamples: samples.filter((sample) => !sample.ok).length,
+          latencyMs: summarizeNumbers(samples.map((sample) => sample.latencyMs)),
+        },
+      ]),
+    ),
+    controlUiFailedSamples: controlUi.filter((sample) => !sample.ok).length,
+    controlUiLatencyMs: summarizeNumbers(controlUi.map((sample) => sample.latencyMs)),
+    cpuCoreRatio: summarizeNumbers(
+      readyz.flatMap((sample) => (sample.cpuCoreRatio == null ? [] : [sample.cpuCoreRatio])),
+    ),
+    degradedSamples: readyz.filter((sample) => sample.degraded === true).length,
+    eventLoopDelayMaxMs: summarizeNumbers(
+      readyz.flatMap((sample) => (sample.delayMaxMs == null ? [] : [sample.delayMaxMs])),
+    ),
+    eventLoopDelayP99Ms: summarizeNumbers(
+      readyz.flatMap((sample) => (sample.delayP99Ms == null ? [] : [sample.delayP99Ms])),
+    ),
+    eventLoopUtilization: summarizeNumbers(
+      readyz.flatMap((sample) => (sample.utilization == null ? [] : [sample.utilization])),
+    ),
+    freshConnectionFailedRuns: runs.filter((run) => !run.freshConnection.ok).length,
+    freshConnectionLatencyMs: summarizeNumbers(runs.map((run) => run.freshConnection.latencyMs)),
+    gatewayUncleanExits: runs.filter(
+      (run) =>
+        run.gatewayExit && (run.gatewayExit.exitCode !== 0 || run.gatewayExit.signal !== null),
+    ).length,
+    gatewayExternalGrowthMb: summarizeNumbers(
+      runs.flatMap((run) => {
+        const before = run.memory.before.externalMb;
+        const after = run.memory.after.externalMb;
+        return before === undefined || after === undefined ? [] : [after - before];
+      }),
+    ),
+    gatewayExternalMb: summarizeNumbers(
+      runs.flatMap((run) =>
+        run.memory.after.externalMb === undefined ? [] : [run.memory.after.externalMb],
+      ),
+    ),
+    gatewayArrayBuffersGrowthMb: summarizeNumbers(
+      runs.flatMap((run) => {
+        const before = run.memory.before.arrayBuffersMb;
+        const after = run.memory.after.arrayBuffersMb;
+        return before === undefined || after === undefined ? [] : [after - before];
+      }),
+    ),
+    gatewayArrayBuffersMb: summarizeNumbers(
+      runs.flatMap((run) =>
+        run.memory.after.arrayBuffersMb === undefined ? [] : [run.memory.after.arrayBuffersMb],
+      ),
+    ),
+    gatewayHeapGrowthMb: summarizeNumbers(
+      runs.map((run) => run.memory.after.heapUsedMb - run.memory.before.heapUsedMb),
+    ),
+    gatewayHeapUsedMb: summarizeNumbers(runs.map((run) => run.memory.after.heapUsedMb)),
+    gatewayPeakRssMb: summarizeNumbers(runs.map((run) => run.memory.peakRssMb)),
+    gatewayRssGrowthMb: summarizeNumbers(
+      runs.map((run) => run.memory.after.rssMb - run.memory.before.rssMb),
+    ),
+    historyFailedSamples: history.filter((sample) => !sample.ok).length,
+    historyLatencyMs: summarizeNumbers(history.map((sample) => sample.latencyMs)),
+    historySampleCount: history.length,
+    messageSubscriptionFailedSamples: subscriptions.filter((sample) => !sample.ok).length,
+    messageSubscriptionLatencyMs: summarizeNumbers(subscriptions.map((sample) => sample.latencyMs)),
+    messageSubscriptionLoadFailedSamples: subscriptionsDuringLoad.filter((sample) => !sample.ok)
+      .length,
+    messageSubscriptionLoadLatencyMs: summarizeNumbers(
+      subscriptionsDuringLoad.map((sample) => sample.latencyMs),
+    ),
+    mockRequestIngress: Object.fromEntries(
+      MOCK_INGRESS_KEYS.map((key) => [
+        key,
+        runs.reduce((count, run) => count + run.mockRequests.ingress.total[key], 0),
+      ]),
+    ),
+    mockResponseSelections: Object.fromEntries(
+      MOCK_SELECTION_KEYS.map((key) => [
+        key,
+        runs.reduce((count, run) => count + run.mockRequests.selections[key], 0),
+      ]),
+    ),
+    toolTurns: runs.reduce((count, run) => count + run.turnEvidence.toolTurns, 0),
+    observerModelDigestTurns: runs.reduce(
+      (count, run) => count + run.turnEvidence.observerModelDigestTurns,
+      0,
+    ),
+    pluginMetadataScanCount: runs.reduce((sum, run) => sum + run.pluginMetadataScans.count, 0),
+    pluginMetadataScanTotalDurationMs: runs.reduce(
+      (sum, run) => sum + run.pluginMetadataScans.totalDurationMs,
+      0,
+    ),
+    readyzLatencyMs: summarizeNumbers(readyz.map((sample) => sample.latencyMs)),
+    readyzFailedSamples: readyz.filter((sample) => !sample.ok).length,
+    sampleCount: readyz.length,
+    sessionSeedDurationMs: summarizeNumbers(runs.map((run) => run.sessionSeedDurationMs)),
+    sessionsListLatencyMs: summarizeNumbers(sessionsList.map((sample) => sample.latencyMs)),
+    sessionsListFailedSamples: sessionsList.filter((sample) => !sample.ok).length,
+    sessionUpdateFailedSamples: sessionUpdates.filter((sample) => !sample.ok).length,
+    sessionUpdateLatencyMs: summarizeNumbers(sessionUpdates.map((sample) => sample.latencyMs)),
+    sessionUpdateSampleCount: sessionUpdates.length,
+    setupDurationMs: summarizeNumbers(runs.map((run) => run.setupDurationMs)),
+    turnCount: runs.reduce((sum, run) => sum + run.turnCount, 0),
+    turnsDurationMs: summarizeNumbers(runs.map((run) => run.turnsDurationMs)),
+  };
+}
+
+async function runBenchmarkSamples(params: {
+  now?: () => number;
+  onProgress?: (message: string) => void;
+  options: CliOptions;
+  runSample?: typeof runGatewaySample;
+}): Promise<BenchmarkRun[]> {
+  const now = params.now ?? performance.now.bind(performance);
+  const runSample = params.runSample ?? runGatewaySample;
+  const runs: BenchmarkRun[] = [];
+  const total = params.options.runs + params.options.warmup;
+  for (let index = 0; index < total; index += 1) {
+    // Each sample gets the same budget so earlier runs cannot shrink later agent waits.
+    // runGatewaySample extends this deadline by its probe warmup before load starts.
+    const deadlineAt = now() + params.options.timeoutMs;
+    const run = await runSample({ ...params.options, deadlineAt });
+    if (index >= params.options.warmup) {
+      runs.push(run);
+      params.onProgress?.(
+        `[bench-gateway-concurrency] run ${runs.length}/${params.options.runs}: turns=${run.turnCount} samples=${run.readyz.length} duration=${run.durationMs.toFixed(1)}ms`,
+      );
+    } else {
+      params.onProgress?.(
+        `[bench-gateway-concurrency] warmup ${index + 1}/${params.options.warmup}: duration=${run.durationMs.toFixed(1)}ms`,
+      );
+    }
+  }
+  return runs;
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+  if (hasHelpFlag(argv)) {
+    printUsage();
+    return;
+  }
+  const options = parseOptions(argv);
+  const runs = await runBenchmarkSamples({ onProgress: console.error, options });
+  const payload = {
+    agentCount: options.agentCount,
+    browserHistoryMessages: options.browserHistoryMessages,
+    browserSessionClicks: options.browserSessionClicks,
+    cadenceMs: options.cadenceMs,
+    concurrency: options.concurrency,
+    controlPlane: options.controlPlane,
+    historyMessages: options.historyMessages,
+    historyMessageChars: options.historyMessageChars,
+    diagnosticsTimeline: options.diagnosticsTimeline,
+    entry: options.entry,
+    generatedAt: new Date().toISOString(),
+    historyBurst: options.historyBurst,
+    historyClients: options.historyClients,
+    mode: "mock-streaming-agent",
+    pluginCount: options.pluginCount,
+    probeWorkload: {
+      mode: options.probeRounds === undefined ? "adaptive" : "fixed-rounds",
+      samplerRoundsPerRun: options.probeRounds ?? null,
+      historyRequestsPerRun:
+        options.probeRounds === undefined
+          ? null
+          : options.probeRounds * options.historyClients * options.historyBurst,
+      peakRssSampling: "sampler-rounds-and-final-memory",
+    },
+    runs,
+    sessionCount: Math.max(options.sessionCount, options.concurrency),
+    sessionUpdateClients: options.sessionUpdates > 0 ? options.sessionUpdateClients : 0,
+    sessionUpdates: options.sessionUpdates,
+    streamChunkDelayMs: options.streamChunkDelayMs,
+    subscribers: options.subscribers,
+    summary: summarizeRuns(runs, options),
+    toolEvents: options.toolEvents,
+    turnsPerSession: options.turnsPerSession,
+    visibleObserver: options.visibleObserver,
+    workspaceFanout: options.workspaceFanout,
+  };
+  if (options.output) {
+    mkdirSync(path.dirname(options.output), { recursive: true });
+    writeFileSync(options.output, `${JSON.stringify(payload, null, 2)}\n`);
+  }
+  if (options.json || !options.output) {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+  if (payload.summary.budgetViolations.length > 0) {
+    throw new Error(payload.summary.budgetViolations.join("\n"));
+  }
+}
+
+export const testing = {
+  parseOptions,
+  parseMockRequests,
+  summarizeMockRequests,
+  createTurnEvidence,
+  formatProbeFailure,
+  formatRunFailure,
+  requestHttp,
+  runBenchmarkSamples,
+  runProbeRounds,
+  runSessionTurns,
+  runTurn,
+  sampleGateway,
+  readDiagnosticsTimelineSpans,
+  summarizePluginMetadataScans,
+  summarizeNumbers,
+  summarizeRuns,
+  tailLines,
+  warmGatewayProbes,
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  void main()
+    .catch((error: unknown) => {
+      console.error(error instanceof CliArgumentError ? error.message : (error as Error)?.stack);
+      process.exitCode = 1;
+    })
+    .finally(() => {
+      if (process.exitCode && process.exitCode !== 0) {
+        console.error(`[bench-gateway-concurrency] FAILED (exit ${process.exitCode})`);
+      }
+    });
+}

scripts/bench-gateway-startup.ts

@@ -0,0 +1,1119 @@
+// Bench Gateway Startup script supports OpenClaw repository automation.
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { pathToFileURL } from "node:url";
+import { listBundledPluginPackArtifacts } from "./lib/bundled-plugin-build-entries.mjs";
+import { delay, stopChild } from "./lib/gateway-bench-child.ts";
+import { getFreePort, readProcessRssMb, readProcessTreeCpuMs } from "./lib/gateway-bench-probes.ts";
+import {
+  BASE_GATEWAY_BENCH_CONFIG,
+  buildGatewayBenchChildArgs,
+  classifyGatewayReadyLog,
+  CliArgumentError,
+  collectOutputLines,
+  collectTraceLine,
+  createGatewayBenchEnv,
+  flushOutputLineBuffers,
+  formatMb,
+  formatMs,
+  formatStats,
+  hasFlag,
+  hasHelpFlag,
+  parseFlagValue,
+  parseNonNegativeInt,
+  parsePositiveInt,
+  parseRepeatableFlag,
+  resolveCases as resolveGatewayBenchCases,
+  resolveEntry as resolveGatewayBenchEntry,
+  resolveOutputPath,
+  STALLED_CATALOG_MODEL_ID,
+  STALLED_CATALOG_PROVIDER_ID,
+  summarizeNumbers,
+  summarizeTraceStats,
+  type InitialProbeResult,
+  type SummaryStats,
+  validateCliArgs as validateGatewayBenchCliArgs,
+  writeGatewayBenchConfig,
+  writePluginFixtures,
+  waitForInitialProbe as waitForProbe,
+} from "./lib/gateway-bench-runtime.ts";
+import { selectSlowStartupTraceDurations } from "./lib/gateway-startup-trace-ranking.js";
+
+type GatewayBenchCase = {
+  agentTopology?: "incident-scale" | "single" | "shared-eleven-plus-distinct-one";
+  completionTracePhase?: string;
+  config: Record<string, unknown>;
+  env?: Record<string, string>;
+  id: string;
+  incidentFixture?: "combined" | "database" | "null-metadata" | "packaged-plugins" | "workspace";
+  name: string;
+  pluginActivationOnStartup?: boolean;
+  pluginCount?: number;
+  providerCatalogStallMs?: number;
+  providerStaticCatalogModelCount?: number;
+  providerStaticCatalogStallMs?: number;
+  runByDefault?: boolean;
+};
+
+type ProbeResult = InitialProbeResult;
+
+type GatewaySample = {
+  completionMs: number | null;
+  cpuCoreRatio: number | null;
+  cpuMs: number | null;
+  exitedBeforeTeardown?: boolean;
+  exitCode: number | null;
+  firstOutputMs: number | null;
+  gatewayReadyLogLine: string | null;
+  gatewayReadyLogMs: number | null;
+  healthz: ProbeResult;
+  httpListenLogLine: string | null;
+  httpListenLogMs: number | null;
+  maxRssMb: number | null;
+  outputTail: string;
+  readyz: ProbeResult;
+  signal: string | null;
+  startupTrace: Record<string, number>;
+};
+
+type CaseResult = {
+  id: string;
+  name: string;
+  samples: GatewaySample[];
+  summary: {
+    completionMs: SummaryStats | null;
+    firstOutputMs: SummaryStats | null;
+    cpuCoreRatio: SummaryStats | null;
+    cpuMs: SummaryStats | null;
+    gatewayReadyLogMs: SummaryStats | null;
+    healthzMs: SummaryStats | null;
+    httpListenLogMs: SummaryStats | null;
+    maxRssMb: SummaryStats | null;
+    readyzMs: SummaryStats | null;
+    startupTrace: Record<string, SummaryStats>;
+  };
+};
+
+type BenchmarkFailure = {
+  id: string;
+  reason: string;
+  sampleIndex: number;
+};
+
+type CliOptions = {
+  cases: GatewayBenchCase[];
+  cpuProfDir?: string;
+  entry: string;
+  heapProfDir?: string;
+  json: boolean;
+  output?: string;
+  runs: number;
+  timeoutMs: number;
+  warmup: number;
+};
+
+const DEFAULT_RUNS = 5;
+const DEFAULT_WARMUP = 1;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_ENTRY = "dist/entry.js";
+const INCIDENT_COMBINED_HEALTHZ_P95_MAX_MS = 30_000;
+const INCIDENT_COMBINED_READYZ_P95_MAX_MS = 60_000;
+const BOOLEAN_FLAGS = new Set(["--help", "-h", "--json"]);
+const VALUE_FLAGS = new Set([
+  "--case",
+  "--cpu-prof-dir",
+  "--entry",
+  "--heap-prof-dir",
+  "--output",
+  "--runs",
+  "--timeout-ms",
+  "--warmup",
+]);
+
+const BASE_CONFIG = BASE_GATEWAY_BENCH_CONFIG;
+const LARGE_PLUGIN_MODEL_AGENT_COUNT = 256;
+const LARGE_PLUGIN_MODEL_COUNT = 58;
+const LARGE_PLUGIN_MODEL_PROVIDER_IDS = ["openai", "google", "minimax"] as const;
+
+function buildLargePluginModelAgentEntries() {
+  const model = {
+    primary: `${LARGE_PLUGIN_MODEL_PROVIDER_IDS[0]}/model-01`,
+    fallbacks: Array.from({ length: LARGE_PLUGIN_MODEL_COUNT - 1 }, (_, offset) => {
+      const index = offset + 1;
+      const provider =
+        index % 3 === 0
+          ? LARGE_PLUGIN_MODEL_PROVIDER_IDS[0]
+          : index % 3 === 1
+            ? LARGE_PLUGIN_MODEL_PROVIDER_IDS[1]
+            : LARGE_PLUGIN_MODEL_PROVIDER_IDS[2];
+      return `${provider}/model-${String(index + 1).padStart(2, "0")}`;
+    }),
+  };
+  return Object.fromEntries(
+    Array.from({ length: LARGE_PLUGIN_MODEL_AGENT_COUNT }, (_, index) => [
+      `agent-${String(index + 1).padStart(4, "0")}`,
+      { model },
+    ]),
+  );
+}
+
+const GATEWAY_CASES: readonly GatewayBenchCase[] = [
+  {
+    id: "default",
+    name: "gateway default",
+    config: BASE_CONFIG,
+  },
+  {
+    id: "skipChannels",
+    name: "gateway, skip channels",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    config: BASE_CONFIG,
+  },
+  {
+    id: "preparedRuntimeCatalogStall",
+    name: "gateway, prepared runtime with CPU-stalling live catalog",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    providerCatalogStallMs: 2_000,
+    config: {
+      ...BASE_CONFIG,
+      agents: {
+        defaults: {
+          model: { primary: `${STALLED_CATALOG_PROVIDER_ID}/${STALLED_CATALOG_MODEL_ID}` },
+          models: {
+            [`${STALLED_CATALOG_PROVIDER_ID}/${STALLED_CATALOG_MODEL_ID}`]: {
+              agentRuntime: { id: "openclaw" },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    id: "preparedRuntimeScaleOne",
+    name: "gateway, prepared runtime scale with one agent",
+    agentTopology: "single",
+    completionTracePhase: "sidecars.ready",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    providerStaticCatalogModelCount: 64,
+    providerStaticCatalogStallMs: 100,
+    config: {
+      ...BASE_CONFIG,
+      agents: {
+        defaults: {
+          model: { primary: `${STALLED_CATALOG_PROVIDER_ID}/${STALLED_CATALOG_MODEL_ID}` },
+          models: {
+            [`${STALLED_CATALOG_PROVIDER_ID}/${STALLED_CATALOG_MODEL_ID}`]: {
+              agentRuntime: { id: "openclaw" },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    id: "preparedRuntimeScaleMany",
+    name: "gateway, prepared runtime scale with 11 shared-workspace agents and one distinct",
+    agentTopology: "shared-eleven-plus-distinct-one",
+    completionTracePhase: "sidecars.ready",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    providerStaticCatalogModelCount: 64,
+    providerStaticCatalogStallMs: 100,
+    config: {
+      ...BASE_CONFIG,
+      agents: {
+        defaults: {
+          model: { primary: `${STALLED_CATALOG_PROVIDER_ID}/${STALLED_CATALOG_MODEL_ID}` },
+          models: {
+            [`${STALLED_CATALOG_PROVIDER_ID}/${STALLED_CATALOG_MODEL_ID}`]: {
+              agentRuntime: { id: "openclaw" },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    id: "oneInternalHook",
+    name: "gateway, one configured internal hook",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    config: {
+      ...BASE_CONFIG,
+      hooks: {
+        internal: {
+          entries: {
+            "session-memory": { enabled: true },
+          },
+        },
+      },
+    },
+  },
+  {
+    id: "allInternalHooks",
+    name: "gateway, all internal hooks",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    config: {
+      ...BASE_CONFIG,
+      hooks: {
+        internal: {
+          enabled: true,
+        },
+      },
+    },
+  },
+  {
+    id: "fiftyPlugins",
+    name: "gateway, 50 manifest plugins",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    pluginActivationOnStartup: true,
+    pluginCount: 50,
+    config: BASE_CONFIG,
+  },
+  {
+    id: "fiftyStartupLazyPlugins",
+    name: "gateway, 50 startup-lazy manifest plugins",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    pluginActivationOnStartup: false,
+    pluginCount: 50,
+    config: BASE_CONFIG,
+  },
+  {
+    id: "largePluginModelConfig",
+    name: `gateway, ${LARGE_PLUGIN_MODEL_AGENT_COUNT} agents with ${LARGE_PLUGIN_MODEL_COUNT} plugin-owned model refs each`,
+    completionTracePhase: "config.snapshot.auto-enable",
+    env: { OPENCLAW_SKIP_CHANNELS: "1" },
+    runByDefault: false,
+    config: {
+      ...BASE_CONFIG,
+      agents: {
+        ownership: "explicit",
+        entries: buildLargePluginModelAgentEntries(),
+      },
+      plugins: {
+        enabled: true,
+        allow: [...LARGE_PLUGIN_MODEL_PROVIDER_IDS],
+      },
+    },
+  },
+  {
+    id: "incidentDatabase",
+    name: "gateway, incident-scale database",
+    incidentFixture: "database",
+    runByDefault: false,
+    config: BASE_CONFIG,
+  },
+  {
+    id: "incidentNullMetadata",
+    name: "gateway, incident-scale NULL metadata repair",
+    incidentFixture: "null-metadata",
+    runByDefault: false,
+    config: BASE_CONFIG,
+  },
+  {
+    id: "incidentWorkspace",
+    name: "gateway, incident-scale workspace",
+    agentTopology: "incident-scale",
+    incidentFixture: "workspace",
+    runByDefault: false,
+    config: BASE_CONFIG,
+  },
+  {
+    id: "incidentPackagedPlugins",
+    name: "gateway, packaged plugin inventory",
+    env: { OPENCLAW_DISABLE_BUNDLED_ENTRY_SOURCE_FALLBACK: "1" },
+    incidentFixture: "packaged-plugins",
+    runByDefault: false,
+    config: BASE_CONFIG,
+  },
+  {
+    id: "incidentCombined",
+    name: "gateway, incident-scale combined load",
+    agentTopology: "incident-scale",
+    env: { OPENCLAW_DISABLE_BUNDLED_ENTRY_SOURCE_FALLBACK: "1" },
+    incidentFixture: "combined",
+    runByDefault: false,
+    config: BASE_CONFIG,
+  },
+] as const;
+
+function validateCliArgs(argv: string[]): void {
+  validateGatewayBenchCliArgs(argv, {
+    booleanFlags: BOOLEAN_FLAGS,
+    repeatableValueFlags: new Set(["--case"]),
+    valueFlags: VALUE_FLAGS,
+  });
+}
+
+function resolveEntry(raw: string | undefined): string {
+  return resolveGatewayBenchEntry(raw, DEFAULT_ENTRY);
+}
+
+function resolveCases(caseIds: string[]): GatewayBenchCase[] {
+  const defaultCases = GATEWAY_CASES.filter((benchCase) => benchCase.runByDefault !== false);
+  return resolveGatewayBenchCases(caseIds, caseIds.length === 0 ? defaultCases : GATEWAY_CASES, {
+    allByDefault: true,
+    validateDuplicatesFirst: true,
+  });
+}
+
+function parseOptions(argv: string[] = process.argv.slice(2)): CliOptions {
+  validateCliArgs(argv);
+  return {
+    cases: resolveCases(parseRepeatableFlag(argv, "--case")),
+    cpuProfDir: parseFlagValue(argv, "--cpu-prof-dir"),
+    entry: resolveEntry(parseFlagValue(argv, "--entry")),
+    heapProfDir: parseFlagValue(argv, "--heap-prof-dir"),
+    json: hasFlag(argv, "--json"),
+    output: resolveOutputPath(parseFlagValue(argv, "--output")),
+    runs: parsePositiveInt(parseFlagValue(argv, "--runs"), DEFAULT_RUNS, "--runs"),
+    timeoutMs: parsePositiveInt(
+      parseFlagValue(argv, "--timeout-ms"),
+      DEFAULT_TIMEOUT_MS,
+      "--timeout-ms",
+    ),
+    warmup: parseNonNegativeInt(parseFlagValue(argv, "--warmup"), DEFAULT_WARMUP, "--warmup"),
+  };
+}
+
+function printUsage(): void {
+  console.log(`OpenClaw Gateway startup benchmark
+
+Usage:
+  pnpm test:startup:gateway -- [options]
+  node --import tsx scripts/bench-gateway-startup.ts [options]
+
+Options:
+  --case <id>          Specific case id to run; repeatable
+  --entry <path>       Gateway CLI entry file (default: ${DEFAULT_ENTRY})
+  --runs <n>           Measured runs per case (default: ${DEFAULT_RUNS})
+  --warmup <n>         Warmup runs per case (default: ${DEFAULT_WARMUP})
+  --timeout-ms <ms>    Per-run timeout (default: ${DEFAULT_TIMEOUT_MS})
+  --cpu-prof-dir <dir> Write one V8 CPU profile per run
+  --heap-prof-dir <dir> Write one V8 heap profile per run
+  --output <path>      Write machine-readable JSON to a file
+  --json               Emit machine-readable JSON
+  --help, -h           Show this text
+
+Case ids:
+  ${GATEWAY_CASES.map((benchCase) => `${benchCase.id} (${benchCase.name})`).join("\n  ")}
+`);
+}
+
+function summarizeCase(benchCase: GatewayBenchCase, samples: GatewaySample[]): CaseResult {
+  const startupTrace = summarizeTraceStats(samples, (sample) => sample.startupTrace);
+  return {
+    id: benchCase.id,
+    name: benchCase.name,
+    samples,
+    summary: {
+      completionMs: summarizeNumbers(
+        samples
+          .map((sample) => sample.completionMs)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      firstOutputMs: summarizeNumbers(
+        samples
+          .map((sample) => sample.firstOutputMs)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      cpuCoreRatio: summarizeNumbers(
+        samples
+          .map((sample) => sample.cpuCoreRatio)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      cpuMs: summarizeNumbers(
+        samples
+          .map((sample) => sample.cpuMs)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      gatewayReadyLogMs: summarizeNumbers(
+        samples
+          .map((sample) => sample.gatewayReadyLogMs)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      healthzMs: summarizeNumbers(
+        samples
+          .map((sample) => sample.healthz.ms)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      httpListenLogMs: summarizeNumbers(
+        samples
+          .map((sample) => sample.httpListenLogMs)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      maxRssMb: summarizeNumbers(
+        samples
+          .map((sample) => sample.maxRssMb)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      readyzMs: summarizeNumbers(
+        samples
+          .map((sample) => sample.readyz.ms)
+          .filter((value): value is number => typeof value === "number"),
+      ),
+      startupTrace,
+    },
+  };
+}
+
+function collectResultFailures(results: CaseResult[]): BenchmarkFailure[] {
+  const failures: BenchmarkFailure[] = [];
+  for (const result of results) {
+    result.samples.forEach((sample, index) => {
+      const missing: string[] = [];
+      if (sample.healthz.status !== 200 || sample.healthz.ms == null) {
+        missing.push("/healthz");
+      }
+      if (sample.readyz.status !== 200 || sample.readyz.ms == null) {
+        missing.push("/readyz");
+      }
+      if (sample.completionMs == null) {
+        missing.push("completion");
+      }
+      if (sample.cpuMs == null || sample.cpuCoreRatio == null) {
+        missing.push("cpu");
+      }
+      if (sample.maxRssMb == null) {
+        missing.push("rss");
+      }
+      if (missing.length > 0) {
+        failures.push({
+          id: result.id,
+          reason: `missing ${missing.join(", ")}`,
+          sampleIndex: index + 1,
+        });
+        return;
+      }
+      if (sample.exitedBeforeTeardown === true) {
+        failures.push({
+          id: result.id,
+          reason:
+            sample.signal == null
+              ? `child exited ${sample.exitCode ?? "before teardown"}`
+              : `child exited by ${sample.signal}`,
+          sampleIndex: index + 1,
+        });
+      }
+    });
+    if (result.id !== "incidentCombined") {
+      continue;
+    }
+    const healthzP95 = result.summary.healthzMs?.p95;
+    if (healthzP95 == null || healthzP95 >= INCIDENT_COMBINED_HEALTHZ_P95_MAX_MS) {
+      failures.push({
+        id: result.id,
+        reason:
+          `/healthz p95 ${healthzP95 == null ? "missing" : formatMs(healthzP95)} ` +
+          `must be under ${formatMs(INCIDENT_COMBINED_HEALTHZ_P95_MAX_MS)}`,
+        sampleIndex: 0,
+      });
+    }
+    const readyzP95 = result.summary.readyzMs?.p95;
+    if (readyzP95 == null || readyzP95 >= INCIDENT_COMBINED_READYZ_P95_MAX_MS) {
+      failures.push({
+        id: result.id,
+        reason:
+          `/readyz p95 ${readyzP95 == null ? "missing" : formatMs(readyzP95)} ` +
+          `must be under ${formatMs(INCIDENT_COMBINED_READYZ_P95_MAX_MS)}`,
+        sampleIndex: 0,
+      });
+    }
+  }
+  return failures;
+}
+
+function printBenchmarkFailures(failures: BenchmarkFailure[]): void {
+  if (failures.length === 0) {
+    return;
+  }
+  console.error(
+    `[gateway-startup-bench] failed: ${failures.length} sample(s) did not produce ready probes or process metrics`,
+  );
+  for (const failure of failures.slice(0, 8)) {
+    console.error(
+      `[gateway-startup-bench] ${failure.id} ${failure.sampleIndex ? `run ${failure.sampleIndex}` : "summary"}: ${failure.reason}`,
+    );
+  }
+  if (failures.length > 8) {
+    console.error(`[gateway-startup-bench] ${failures.length - 8} more sample failure(s) omitted`);
+  }
+}
+
+function formatRatio(value: number | null): string {
+  if (value == null) {
+    return "n/a";
+  }
+  return value.toFixed(3);
+}
+
+async function waitForStartupTracePhase(params: {
+  deadlineAt: number;
+  isDone: () => boolean;
+  phase: string;
+  startupTrace: Record<string, number>;
+}): Promise<number | null> {
+  const totalKey = `${params.phase}.total`;
+  while (performance.now() < params.deadlineAt) {
+    if (Object.hasOwn(params.startupTrace, totalKey)) {
+      return params.startupTrace[totalKey] ?? null;
+    }
+    if (params.isDone()) {
+      return null;
+    }
+    await delay(25);
+  }
+  return null;
+}
+
+function buildBenchAgentList(
+  root: string,
+  topology: GatewayBenchCase["agentTopology"],
+): Array<{ id: string; default?: boolean; workspace: string }> | undefined {
+  if (!topology) {
+    return undefined;
+  }
+  const sharedWorkspace = path.join(root, "shared-workspace");
+  const distinctWorkspace = path.join(root, "distinct-workspace");
+  mkdirSync(sharedWorkspace, { recursive: true });
+  if (topology === "single") {
+    return [{ id: "main", default: true, workspace: sharedWorkspace }];
+  }
+  if (topology === "incident-scale") {
+    return Array.from({ length: 8 }, (_, index) => ({
+      id: `incident-agent-${String(index + 1).padStart(2, "0")}`,
+      default: index === 0,
+      workspace: path.join(root, "workspaces", `agent-${String(index + 1).padStart(2, "0")}`),
+    }));
+  }
+  mkdirSync(distinctWorkspace, { recursive: true });
+  return Array.from({ length: 12 }, (_, index) => ({
+    id: `agent-${String(index + 1).padStart(2, "0")}`,
+    ...(index === 0 ? { default: true } : {}),
+    workspace: index === 11 ? distinctWorkspace : sharedWorkspace,
+  }));
+}
+
+const INCIDENT_AUDIT_ROW_COUNT = 200_000;
+const INCIDENT_WORKSPACE_FILE_BYTES = 10 * 1024;
+const INCIDENT_WORKSPACE_FILE_COUNT = 80_000;
+const INCIDENT_WORKSPACE_COUNT = 8;
+const INCIDENT_WORKSPACE_FILES_PER_DIRECTORY = 1_000;
+
+type IncidentFixtureOptions = {
+  auditRowCount?: number;
+  kind: NonNullable<GatewayBenchCase["incidentFixture"]>;
+  workspaceFileBytes?: number;
+  workspaceFileCount?: number;
+};
+
+function fixtureIncludesDatabase(kind: IncidentFixtureOptions["kind"]): boolean {
+  return kind === "combined" || kind === "database" || kind === "null-metadata";
+}
+
+function fixtureIncludesWorkspace(kind: IncidentFixtureOptions["kind"]): boolean {
+  return kind === "combined" || kind === "workspace";
+}
+
+function fixtureIncludesNullMetadata(kind: IncidentFixtureOptions["kind"]): boolean {
+  return kind === "combined" || kind === "null-metadata";
+}
+
+function fixtureIncludesPackagedPlugins(kind: IncidentFixtureOptions["kind"]): boolean {
+  return kind === "combined" || kind === "packaged-plugins";
+}
+
+function listIncidentPackagedPluginArtifacts(env = process.env): string[] {
+  return listBundledPluginPackArtifacts({
+    env: { ...env, OPENCLAW_BUNDLED_PLUGIN_BUILD_IDS: undefined },
+  });
+}
+
+function assertIncidentPackagedPluginInventory(): void {
+  const missing = listIncidentPackagedPluginArtifacts().filter(
+    (artifact) => !existsSync(path.resolve(process.cwd(), artifact)),
+  );
+  if (missing.length > 0) {
+    throw new Error(
+      `Incident packaged-plugin benchmark requires a built plugin inventory; ${missing.length} required artifact(s) are missing. Run pnpm build first.`,
+    );
+  }
+}
+
+function createIncidentWorkspaces(root: string, options: IncidentFixtureOptions): void {
+  if (!fixtureIncludesWorkspace(options.kind)) {
+    return;
+  }
+  const fileCount = options.workspaceFileCount ?? INCIDENT_WORKSPACE_FILE_COUNT;
+  const fileBytes = options.workspaceFileBytes ?? INCIDENT_WORKSPACE_FILE_BYTES;
+  const contents = Buffer.alloc(fileBytes, "x");
+  for (let index = 0; index < fileCount; index += 1) {
+    const workspaceIndex = index % INCIDENT_WORKSPACE_COUNT;
+    const directoryIndex = Math.floor(index / INCIDENT_WORKSPACE_FILES_PER_DIRECTORY);
+    const directory = path.join(
+      root,
+      "workspaces",
+      `agent-${String(workspaceIndex + 1).padStart(2, "0")}`,
+      "incident-artifacts",
+      `batch-${String(directoryIndex).padStart(3, "0")}`,
+    );
+    mkdirSync(directory, { recursive: true });
+    writeFileSync(path.join(directory, `artifact-${String(index).padStart(6, "0")}.bin`), contents);
+  }
+}
+
+function seedIncidentAuditRows(database: import("node:sqlite").DatabaseSync, count: number): void {
+  const payload = `fixture:${"x".repeat(1024)}`;
+  const insert = database.prepare(
+    `INSERT INTO audit_events (
+       event_id, source_id, source_sequence, occurred_at, kind, action, status, actor_type,
+       actor_id, agent_id, session_key, run_id, channel, target_ref
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  );
+  database.exec("BEGIN IMMEDIATE;");
+  try {
+    for (let index = 0; index < count; index += 1) {
+      const id = `incident-audit-${String(index).padStart(8, "0")}`;
+      insert.run(
+        id,
+        `source-${id}`,
+        index + 1,
+        1_750_000_000_000 + index,
+        "gateway.admission",
+        "accepted",
+        "ok",
+        "system",
+        "incident-fixture",
+        "incident-agent-01",
+        "agent:incident-agent-01:main",
+        `run-${id}`,
+        "fixture",
+        payload,
+      );
+    }
+    database.exec("COMMIT;");
+  } catch (error) {
+    database.exec("ROLLBACK;");
+    throw error;
+  }
+  // Retain half the rows after a large write so the fixture keeps the incident's
+  // high freelist pressure without storing any customer content.
+  database.prepare("DELETE FROM audit_events WHERE source_sequence % 2 = 0").run();
+}
+
+async function writeIncidentFixture(root: string, options: IncidentFixtureOptions): Promise<void> {
+  createIncidentWorkspaces(root, options);
+  if (!fixtureIncludesDatabase(options.kind)) {
+    return;
+  }
+  const env = { OPENCLAW_STATE_DIR: path.join(root, "state") };
+  const [{ DatabaseSync }, agentDatabase, stateDatabase] = await Promise.all([
+    import("node:sqlite"),
+    import("../src/state/openclaw-agent-db.js"),
+    import("../src/state/openclaw-state-db.js"),
+  ]);
+  const state = stateDatabase.openOpenClawStateDatabase({ env });
+  const agents = Array.from({ length: INCIDENT_WORKSPACE_COUNT }, (_, index) =>
+    agentDatabase.openOpenClawAgentDatabase({
+      agentId: `incident-agent-${String(index + 1).padStart(2, "0")}`,
+      env,
+    }),
+  );
+  const statePath = state.path;
+  const agentPaths = agents.map((agent) => agent.path);
+  try {
+    state.db.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+    agents.forEach((agent) => agent.db.exec("PRAGMA wal_checkpoint(TRUNCATE);"));
+  } finally {
+    agentDatabase.closeOpenClawAgentDatabasesForTest();
+    stateDatabase.closeOpenClawStateDatabaseForTest();
+  }
+  const stateHandle = new DatabaseSync(statePath);
+  try {
+    seedIncidentAuditRows(stateHandle, options.auditRowCount ?? INCIDENT_AUDIT_ROW_COUNT);
+    if (fixtureIncludesNullMetadata(options.kind)) {
+      stateHandle
+        .prepare("UPDATE schema_meta SET app_version = NULL WHERE meta_key = 'primary'")
+        .run();
+    }
+    stateHandle.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+  } finally {
+    stateHandle.close();
+  }
+  if (!fixtureIncludesNullMetadata(options.kind)) {
+    return;
+  }
+  for (const agentPath of agentPaths) {
+    const agent = new DatabaseSync(agentPath);
+    try {
+      agent.prepare("UPDATE schema_meta SET app_version = NULL WHERE meta_key = 'primary'").run();
+      agent.exec("PRAGMA wal_checkpoint(TRUNCATE);");
+    } finally {
+      agent.close();
+    }
+  }
+}
+
+async function withGatewayBenchRoot<T>(run: (root: string) => Promise<T>): Promise<T> {
+  const root = mkdtempSync(path.join(tmpdir(), "openclaw-gateway-bench-"));
+  try {
+    return await run(root);
+  } finally {
+    rmSync(root, { force: true, maxRetries: 3, recursive: true, retryDelay: 100 });
+  }
+}
+
+function writeConfig(root: string, benchCase: GatewayBenchCase): string {
+  const hasCatalogFixture =
+    benchCase.providerCatalogStallMs !== undefined ||
+    benchCase.providerStaticCatalogStallMs !== undefined;
+  const pluginCount = hasCatalogFixture ? 1 : benchCase.pluginCount;
+  const pluginFixtures = pluginCount
+    ? writePluginFixtures(root, {
+        activationOnStartup: hasCatalogFixture ? true : benchCase.pluginActivationOnStartup,
+        count: pluginCount,
+        providerCatalogStallMs: benchCase.providerCatalogStallMs,
+        providerStaticCatalogModelCount: benchCase.providerStaticCatalogModelCount,
+        providerStaticCatalogStallMs: benchCase.providerStaticCatalogStallMs,
+      })
+    : null;
+  const agentList = buildBenchAgentList(root, benchCase.agentTopology);
+  return writeGatewayBenchConfig(root, benchCase.config, { agentList, pluginFixtures });
+}
+
+function sanitizedEnv(
+  root: string,
+  configPath: string,
+  benchCase: GatewayBenchCase,
+): NodeJS.ProcessEnv {
+  return createGatewayBenchEnv(root, configPath, { caseEnv: benchCase.env });
+}
+
+function collectStartupTrace(line: string, startupTrace: Record<string, number>): void {
+  collectTraceLine(line, "startup trace", startupTrace);
+}
+
+async function runGatewaySample(options: {
+  benchCase: GatewayBenchCase;
+  cpuProfDir?: string;
+  entry: string;
+  heapProfDir?: string;
+  sampleIndex: number;
+  timeoutMs: number;
+}): Promise<GatewaySample> {
+  return await withGatewayBenchRoot(async (root) => {
+    const port = await getFreePort();
+    const configPath = writeConfig(root, options.benchCase);
+    const env = sanitizedEnv(root, configPath, options.benchCase);
+    if (options.benchCase.incidentFixture) {
+      await writeIncidentFixture(root, { kind: options.benchCase.incidentFixture });
+      if (fixtureIncludesPackagedPlugins(options.benchCase.incidentFixture)) {
+        assertIncidentPackagedPluginInventory();
+      }
+    }
+    const startAt = performance.now();
+    const deadlineAt = startAt + options.timeoutMs;
+    const startupTrace: Record<string, number> = {};
+    const output: string[] = [];
+    const outputBuffers: Record<"stderr" | "stdout", string> = { stderr: "", stdout: "" };
+    let firstOutputMs: number | null = null;
+    let gatewayReadyLogLine: string | null = null;
+    let gatewayReadyLogMs: number | null = null;
+    let httpListenLogLine: string | null = null;
+    let httpListenLogMs: number | null = null;
+    let maxRssMb: number | null = null;
+    let childExited = false;
+    let child: ChildProcessWithoutNullStreams | undefined;
+    let rssTimer: ReturnType<typeof setInterval> | undefined;
+
+    try {
+      const nodeOptions = [
+        ...(options.cpuProfDir
+          ? [
+              "--cpu-prof",
+              "--cpu-prof-dir",
+              options.cpuProfDir,
+              "--cpu-prof-name",
+              `openclaw-gateway-${options.benchCase.id}-${options.sampleIndex}-${Date.now()}.cpuprofile`,
+            ]
+          : []),
+        ...(options.heapProfDir ? ["--heap-prof", "--heap-prof-dir", options.heapProfDir] : []),
+      ];
+      const childArgs = buildGatewayBenchChildArgs(options.entry, port, nodeOptions);
+      child = spawn(process.execPath, childArgs, {
+        cwd: process.cwd(),
+        detached: process.platform !== "win32",
+        env,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      const startedChild = child;
+      const cpuStartMs = readProcessTreeCpuMs(startedChild.pid);
+      const sampleRss = () => {
+        const rssMb = readProcessRssMb(startedChild.pid);
+        if (rssMb != null) {
+          maxRssMb = maxRssMb == null ? rssMb : Math.max(maxRssMb, rssMb);
+        }
+      };
+      sampleRss();
+      rssTimer = setInterval(sampleRss, 100);
+      rssTimer.unref?.();
+      const childExitPromise = new Promise<{ exitCode: number | null; signal: string | null }>(
+        (resolve) => {
+          startedChild.once("exit", (exitCode, signal) => {
+            childExited = true;
+            resolve({ exitCode, signal });
+          });
+        },
+      );
+
+      const onLine = (line: string, nowMs: number) => {
+        const readyLogKind = classifyGatewayReadyLog(line);
+        if (readyLogKind === "http-listen" && httpListenLogMs == null) {
+          httpListenLogMs = nowMs;
+          httpListenLogLine = line;
+        }
+        if (readyLogKind === "gateway-ready" && gatewayReadyLogMs == null) {
+          gatewayReadyLogMs = nowMs;
+          gatewayReadyLogLine = line;
+        }
+        collectStartupTrace(line, startupTrace);
+      };
+      const onChunk = (stream: "stderr" | "stdout", chunk: Buffer) => {
+        if (firstOutputMs == null) {
+          firstOutputMs = performance.now() - startAt;
+        }
+        const text = chunk.toString("utf8");
+        output.push(text);
+        if (output.length > 20) {
+          output.splice(0, output.length - 20);
+        }
+        const parsed = collectOutputLines(outputBuffers[stream], text);
+        outputBuffers[stream] = parsed.carry;
+        const nowMs = performance.now() - startAt;
+        for (const line of parsed.lines) {
+          onLine(line, nowMs);
+        }
+      };
+      startedChild.stdout.on("data", (chunk: Buffer) => onChunk("stdout", chunk));
+      startedChild.stderr.on("data", (chunk: Buffer) => onChunk("stderr", chunk));
+
+      const [healthz, readyz] = await Promise.all([
+        waitForProbe({
+          deadlineAt,
+          isDone: () => childExited,
+          path: "/healthz",
+          port,
+          startAt,
+        }),
+        waitForProbe({
+          deadlineAt,
+          isDone: () => childExited,
+          path: "/readyz",
+          port,
+          startAt,
+        }),
+      ]);
+      const completionMs = options.benchCase.completionTracePhase
+        ? await waitForStartupTracePhase({
+            deadlineAt,
+            isDone: () => childExited,
+            phase: options.benchCase.completionTracePhase,
+            startupTrace,
+          })
+        : performance.now() - startAt;
+      const completedAt = performance.now();
+      const cpuEndMs = readProcessTreeCpuMs(startedChild.pid);
+      const cpuMs =
+        cpuStartMs == null || cpuEndMs == null ? null : Math.max(0, cpuEndMs - cpuStartMs);
+      const cpuCoreRatio = cpuMs == null ? null : cpuMs / Math.max(1, completedAt - startAt);
+      const exit = await stopChild(startedChild);
+      sampleRss();
+      child = undefined;
+      // stopChild is the bounded teardown wait; the raw exit promise may never settle.
+      void childExitPromise.catch(() => null);
+      flushOutputLineBuffers(outputBuffers, onLine, performance.now() - startAt, {
+        flushPartial: true,
+      });
+
+      return {
+        completionMs,
+        cpuCoreRatio,
+        cpuMs,
+        exitedBeforeTeardown: exit.exitedBeforeTeardown,
+        exitCode: exit.exitCode,
+        firstOutputMs,
+        gatewayReadyLogLine,
+        gatewayReadyLogMs,
+        healthz,
+        httpListenLogLine,
+        httpListenLogMs,
+        maxRssMb,
+        outputTail: output.join("").split(/\r?\n/u).slice(-20).join("\n"),
+        readyz,
+        signal: exit.signal,
+        startupTrace,
+      };
+    } finally {
+      if (rssTimer) {
+        clearInterval(rssTimer);
+      }
+      if (child) {
+        await stopChild(child).catch(() => undefined);
+      }
+    }
+  });
+}
+
+async function runCase(options: {
+  benchCase: GatewayBenchCase;
+  cpuProfDir?: string;
+  entry: string;
+  heapProfDir?: string;
+  runs: number;
+  timeoutMs: number;
+  warmup: number;
+}): Promise<CaseResult> {
+  const samples: GatewaySample[] = [];
+  const total = options.runs + options.warmup;
+  for (let index = 0; index < total; index += 1) {
+    const sample = await runGatewaySample({
+      benchCase: options.benchCase,
+      cpuProfDir: options.cpuProfDir,
+      entry: options.entry,
+      heapProfDir: options.heapProfDir,
+      sampleIndex: index + 1,
+      timeoutMs: options.timeoutMs,
+    });
+    if (index >= options.warmup) {
+      samples.push(sample);
+      const heapUsedMb = sample.startupTrace["memory.ready.heapUsedMb"] ?? null;
+      console.log(
+        `[gateway-startup-bench] ${options.benchCase.id} run ${samples.length}/${options.runs}: completion=${formatMs(sample.completionMs)} healthz=${formatMs(sample.healthz.ms)} readyz=${formatMs(sample.readyz.ms)} httpListen=${formatMs(sample.httpListenLogMs)} gatewayReady=${formatMs(sample.gatewayReadyLogMs)} cpu=${formatMs(sample.cpuMs)} cpuCore=${formatRatio(sample.cpuCoreRatio)} rss=${formatMb(sample.maxRssMb)} heap=${formatMb(heapUsedMb)}`,
+      );
+      if (
+        sample.outputTail &&
+        (sample.completionMs == null ||
+          sample.healthz.status !== 200 ||
+          sample.readyz.status !== 200)
+      ) {
+        console.error(
+          `[gateway-startup-bench] ${options.benchCase.id} output tail:\n${sample.outputTail}`,
+        );
+      }
+    } else {
+      const heapUsedMb = sample.startupTrace["memory.ready.heapUsedMb"] ?? null;
+      console.log(
+        `[gateway-startup-bench] ${options.benchCase.id} warmup ${index + 1}/${options.warmup}: healthz=${formatMs(sample.healthz.ms)} readyz=${formatMs(sample.readyz.ms)} cpu=${formatMs(sample.cpuMs)} cpuCore=${formatRatio(sample.cpuCoreRatio)} rss=${formatMb(sample.maxRssMb)} heap=${formatMb(heapUsedMb)}`,
+      );
+    }
+  }
+  return summarizeCase(options.benchCase, samples);
+}
+
+function printResult(result: CaseResult): void {
+  console.log(`\n${result.name} (${result.id})`);
+  console.log(`  completion:   ${formatStats(result.summary.completionMs)}`);
+  console.log(`  first output: ${formatStats(result.summary.firstOutputMs)}`);
+  console.log(`  CPU:          ${formatStats(result.summary.cpuMs)}`);
+  console.log(`  CPU core:     ${formatStats(result.summary.cpuCoreRatio, formatRatio)}`);
+  console.log(`  /healthz:     ${formatStats(result.summary.healthzMs)}`);
+  console.log(`  http listen:  ${formatStats(result.summary.httpListenLogMs)}`);
+  console.log(`  gateway ready: ${formatStats(result.summary.gatewayReadyLogMs)}`);
+  console.log(`  /readyz:      ${formatStats(result.summary.readyzMs)}`);
+  console.log(`  max RSS:      ${formatStats(result.summary.maxRssMb, formatMb)}`);
+  console.log(
+    `  ready memory: rss=${formatStats(result.summary.startupTrace["memory.ready.rssMb"], formatMb)} heap=${formatStats(result.summary.startupTrace["memory.ready.heapUsedMb"], formatMb)} external=${formatStats(result.summary.startupTrace["memory.ready.externalMb"], formatMb)}`,
+  );
+  console.log(
+    `  post-ready memory: rss=${formatStats(result.summary.startupTrace["memory.post-ready.rssMb"], formatMb)} heap=${formatStats(result.summary.startupTrace["memory.post-ready.heapUsedMb"], formatMb)} external=${formatStats(result.summary.startupTrace["memory.post-ready.externalMb"], formatMb)}`,
+  );
+  console.log(
+    `  prepared runtime: agents=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.agentCount"], String)} workspaces=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.workspaceGroupCount"], String)} configuredGroups=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.configuredFactsGroupCount"], String)} configuredModels=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.configuredRuntimeModelCount"], String)} generatedPlugins=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.generatedCatalogPluginCount"], String)} generatedReads=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.generatedCatalogReadCount"], String)} sources=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.catalogSourceCount"], String)} credentials=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.credentialGroupCount"], String)} catalogs=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.catalogGroupCount"], String)} registries=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.runtimeRegistryCount"], String)} workspaceFacts=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.workspaceFactsMs"])} runtimePlugins=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.runtimePluginMs"])} metadata=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.pluginMetadataMs"])} staticProviders=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.staticProviderCatalogMs"])} ambientAuth=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.ambientCredentialsMs"])} agentFacts=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.agentFactsMs"])} configuredProjection=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.configuredProjectionMs"])} sourceMs=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.catalogSourceMs"])} registryMs=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.registryMs"])} sourceLimit=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.sourceConcurrencyLimitCount"], String)} fullCatalogLimit=${formatStats(result.summary.startupTrace["sidecars.model-runtime-build.fullCatalogConcurrencyLimitCount"], String)} staticCatalog=${formatStats(result.summary.startupTrace["benchmark.preparedRuntimeStaticCatalogCallCount"], String)} pluginLoader=${formatStats(result.summary.startupTrace["sidecars.plugin-loader.callsCount"], String)} eventLoopMax=${formatStats(result.summary.startupTrace["sidecars.model-runtime.eventLoopMax"])}`,
+  );
+  const trace = selectSlowStartupTraceDurations(result.summary.startupTrace, 8);
+  if (trace.length > 0) {
+    console.log("  trace top:");
+    for (const [name, stats] of trace) {
+      console.log(`    ${name}: ${formatStats(stats)}`);
+    }
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (hasHelpFlag(argv)) {
+    printUsage();
+    return;
+  }
+
+  const options = parseOptions(argv);
+  if (options.cpuProfDir) {
+    mkdirSync(options.cpuProfDir, { recursive: true });
+  }
+  if (options.heapProfDir) {
+    mkdirSync(options.heapProfDir, { recursive: true });
+  }
+  const results: CaseResult[] = [];
+  for (const benchCase of options.cases) {
+    results.push(
+      await runCase({
+        benchCase,
+        cpuProfDir: options.cpuProfDir,
+        entry: options.entry,
+        heapProfDir: options.heapProfDir,
+        runs: options.runs,
+        timeoutMs: options.timeoutMs,
+        warmup: options.warmup,
+      }),
+    );
+  }
+
+  const payload = {
+    entry: options.entry,
+    generatedAt: new Date().toISOString(),
+    results,
+  };
+  if (options.output) {
+    mkdirSync(path.dirname(options.output), { recursive: true });
+    writeFileSync(options.output, `${JSON.stringify(payload, null, 2)}\n`);
+  }
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    for (const result of results) {
+      printResult(result);
+    }
+  }
+
+  const failures = collectResultFailures(results);
+  if (failures.length > 0) {
+    printBenchmarkFailures(failures);
+    process.exitCode = 1;
+  }
+}
+
+export const testing = {
+  collectResultFailures,
+  collectStartupTrace,
+  listIncidentPackagedPluginArtifacts,
+  parseOptions,
+  sanitizedEnv,
+  summarizeCase,
+  waitForStartupTracePhase,
+  withGatewayBenchRoot,
+  writeIncidentFixture,
+  writeConfig,
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().catch((err: unknown) => {
+    if (err instanceof CliArgumentError) {
+      console.error(err.message);
+      process.exitCode = 1;
+      return;
+    }
+    console.error(err instanceof Error ? err.stack : String(err));
+    process.exitCode = 1;
+  });
+}

scripts/bench-task-registry-sqlite-worker.ts

@@ -0,0 +1,468 @@
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { pathToFileURL } from "node:url";
+import { toErrorObject } from "@openclaw/normalization-core/error-coercion";
+import type { DB as OpenClawStateKyselyDatabase } from "../src/state/openclaw-state-db.generated.js";
+import {
+  WORKER_RESULT_SENTINEL,
+  type MemorySample,
+  type RegistryLifecycleCounts,
+  type RegistrySnapshot,
+  type RetainedMemoryMetrics,
+  type WorkerResult,
+} from "./bench-task-registry-sqlite.js";
+import { classifyBoundedUnsignedDecimal } from "./lib/arg-utils.mts";
+
+type WorkerOptions = {
+  size: number;
+  cycles: number;
+  warmup: number;
+  stateDir: string;
+};
+
+type TimingSample = {
+  registrationMs: number;
+  terminalMs: number;
+  teardownMs: number;
+  registration: RegistrySnapshot;
+  terminal: RegistrySnapshot;
+  teardown: RegistrySnapshot;
+};
+
+type BenchmarkStateDatabase = Pick<
+  OpenClawStateKyselyDatabase,
+  "task_delivery_state" | "task_runs"
+>;
+
+type TaskRecordApi = Pick<
+  typeof import("../src/tasks/task-registry-record-api.js"),
+  "createTaskRecord" | "markTaskTerminalById"
+>;
+
+type TaskRegistryQueryApi = Pick<
+  typeof import("../src/tasks/task-registry-query.js"),
+  "deleteTaskRecordById"
+>;
+
+function parseInteger(raw: string | undefined, flag: string, min: number, max: number): number {
+  const result = classifyBoundedUnsignedDecimal(raw, min, max);
+  if (result.kind === "syntax") {
+    throw new Error(`${flag} must be an integer`);
+  }
+  if (result.kind !== "value") {
+    throw new Error(`${flag} must be between ${min} and ${max}`);
+  }
+  return result.value;
+}
+
+function parseOptions(argv: string[]): WorkerOptions {
+  const values = new Map<string, string>();
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (!flag?.startsWith("--") || !value || value.startsWith("--")) {
+      throw new Error(`invalid worker argument near ${flag ?? "end"}`);
+    }
+    if (values.has(flag)) {
+      throw new Error(`${flag} was provided more than once`);
+    }
+    values.set(flag, value);
+  }
+  const stateDir = values.get("--state-dir");
+  if (!stateDir || !path.isAbsolute(stateDir)) {
+    throw new Error("--state-dir must be an absolute path");
+  }
+  return {
+    size: parseInteger(values.get("--size"), "--size", 1, 4096),
+    cycles: parseInteger(values.get("--cycles"), "--cycles", 1, 200),
+    warmup: parseInteger(values.get("--warmup"), "--warmup", 0, 20),
+    stateDir,
+  };
+}
+
+function processPeakRssBytes(): number {
+  return Math.max(0, Math.round(process.resourceUsage().maxRSS * 1024));
+}
+
+function forceGc(): void {
+  const gc = (globalThis as typeof globalThis & { gc?: () => void }).gc;
+  if (!gc) {
+    throw new Error("benchmark worker requires --expose-gc");
+  }
+  gc();
+  gc();
+}
+
+function readMemorySample(cycle: number): MemorySample {
+  const memory = process.memoryUsage();
+  return {
+    cycle,
+    heapUsedBytes: memory.heapUsed,
+    heapTotalBytes: memory.heapTotal,
+    rssBytes: memory.rss,
+    externalBytes: memory.external,
+    arrayBuffersBytes: memory.arrayBuffers,
+    processPeakRssBytes: processPeakRssBytes(),
+  };
+}
+
+function slope(values: number[]): number {
+  if (values.length < 2) {
+    return 0;
+  }
+  const xMean = (values.length - 1) / 2;
+  const yMean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  let numerator = 0;
+  let denominator = 0;
+  for (let index = 0; index < values.length; index += 1) {
+    const xDelta = index - xMean;
+    numerator += xDelta * ((values[index] ?? 0) - yMean);
+    denominator += xDelta * xDelta;
+  }
+  return denominator === 0 ? 0 : numerator / denominator;
+}
+
+function retainedMemorySlopes(samples: MemorySample[]): RetainedMemoryMetrics {
+  return {
+    heapUsedBytes: slope(samples.map((sample) => sample.heapUsedBytes)),
+    heapTotalBytes: slope(samples.map((sample) => sample.heapTotalBytes)),
+    rssBytes: slope(samples.map((sample) => sample.rssBytes)),
+    externalBytes: slope(samples.map((sample) => sample.externalBytes)),
+    arrayBuffersBytes: slope(samples.map((sample) => sample.arrayBuffersBytes)),
+  };
+}
+
+function retainedMemoryDelta(
+  baseline: MemorySample,
+  finalSample: MemorySample,
+): RetainedMemoryMetrics {
+  return {
+    heapUsedBytes: finalSample.heapUsedBytes - baseline.heapUsedBytes,
+    heapTotalBytes: finalSample.heapTotalBytes - baseline.heapTotalBytes,
+    rssBytes: finalSample.rssBytes - baseline.rssBytes,
+    externalBytes: finalSample.externalBytes - baseline.externalBytes,
+    arrayBuffersBytes: finalSample.arrayBuffersBytes - baseline.arrayBuffersBytes,
+  };
+}
+
+function assertLifecycleCounts(
+  actual: RegistryLifecycleCounts,
+  expected: RegistryLifecycleCounts,
+  phase: string,
+  surface: string,
+): void {
+  for (const field of Object.keys(expected) as Array<keyof RegistryLifecycleCounts>) {
+    if (actual[field] !== expected[field]) {
+      throw new Error(
+        `${phase} ${surface} invariant failed: ${JSON.stringify({ expected, actual })}`,
+      );
+    }
+  }
+}
+
+function assertSnapshot(
+  actual: RegistrySnapshot,
+  expected: RegistryLifecycleCounts,
+  phase: string,
+): void {
+  for (const surface of ["memory", "sqlite"] as const) {
+    assertLifecycleCounts(actual[surface], expected, phase, surface);
+  }
+}
+
+async function createCountReader() {
+  const [{ executeSqliteQuerySync, getNodeSqliteKysely }, stateDb, state] = await Promise.all([
+    import("../src/infra/kysely-sync.js"),
+    import("../src/state/openclaw-state-db.js"),
+    import("../src/tasks/task-registry-state.js"),
+  ]);
+  return (): RegistrySnapshot => {
+    const database = stateDb.openOpenClawStateDatabase();
+    const db = getNodeSqliteKysely<BenchmarkStateDatabase>(database.db);
+    const taskRows = executeSqliteQuerySync(
+      database.db,
+      db.selectFrom("task_runs").select(["status", "delivery_status", "terminal_outcome"]),
+    ).rows;
+    const deliveryRows = executeSqliteQuerySync(
+      database.db,
+      db.selectFrom("task_delivery_state").select(({ fn }) => fn.countAll<number>().as("count")),
+    ).rows[0]?.count;
+    const summarize = (
+      taskRecords: Iterable<{
+        status: string;
+        deliveryStatus: string;
+        terminalOutcome?: string | null;
+      }>,
+      deliveryStateCount: number,
+    ): RegistryLifecycleCounts => {
+      let taskCount = 0;
+      let runningTasks = 0;
+      let succeededTasks = 0;
+      let pendingDeliveryTasks = 0;
+      let succeededTerminalOutcomes = 0;
+      for (const task of taskRecords) {
+        taskCount += 1;
+        runningTasks += task.status === "running" ? 1 : 0;
+        succeededTasks += task.status === "succeeded" ? 1 : 0;
+        pendingDeliveryTasks += task.deliveryStatus === "pending" ? 1 : 0;
+        succeededTerminalOutcomes += task.terminalOutcome === "succeeded" ? 1 : 0;
+      }
+      return {
+        taskCount,
+        deliveryStateCount,
+        runningTasks,
+        succeededTasks,
+        pendingDeliveryTasks,
+        succeededTerminalOutcomes,
+      };
+    };
+    return {
+      memory: summarize(
+        [...state.tasks.values()].map((task) => ({
+          status: task.status,
+          deliveryStatus: task.deliveryStatus,
+          terminalOutcome: task.terminalOutcome,
+        })),
+        state.taskDeliveryStates.size,
+      ),
+      sqlite: summarize(
+        taskRows.map((task) => ({
+          status: task.status,
+          deliveryStatus: task.delivery_status,
+          terminalOutcome: task.terminal_outcome,
+        })),
+        deliveryRows ?? 0,
+      ),
+    };
+  };
+}
+
+async function runCycle(
+  size: number,
+  serial: number,
+  readSnapshot: () => RegistrySnapshot,
+  taskRecordApi: TaskRecordApi,
+  taskRegistryQuery: TaskRegistryQueryApi,
+): Promise<TimingSample> {
+  const taskIds: string[] = [];
+  const startedAt = Date.now();
+  const registrationStartedAt = performance.now();
+  for (let index = 0; index < size; index += 1) {
+    const task = taskRecordApi.createTaskRecord({
+      runtime: "subagent",
+      requesterSessionKey: "agent:benchmark:main",
+      ownerKey: "agent:benchmark:main",
+      scopeKind: "session",
+      requesterOrigin: { channel: "benchmark", to: "task-registry" },
+      childSessionKey: `agent:benchmark:subagent:${serial}:${index}`,
+      runId: `benchmark-task-${serial}-${index}`,
+      task: `durable registration benchmark ${index}`,
+      status: "running",
+      deliveryStatus: "pending",
+      notifyPolicy: "silent",
+      startedAt,
+      lastEventAt: startedAt,
+    });
+    if (!task) {
+      throw new Error(`task registration failed at ${index + 1}/${size}`);
+    }
+    taskIds.push(task.taskId);
+  }
+  const registrationMs = performance.now() - registrationStartedAt;
+  const emptyCounts: RegistryLifecycleCounts = {
+    taskCount: 0,
+    deliveryStateCount: 0,
+    runningTasks: 0,
+    succeededTasks: 0,
+    pendingDeliveryTasks: 0,
+    succeededTerminalOutcomes: 0,
+  };
+  const registration = readSnapshot();
+  assertSnapshot(
+    registration,
+    {
+      ...emptyCounts,
+      taskCount: size,
+      deliveryStateCount: size,
+      runningTasks: size,
+      pendingDeliveryTasks: size,
+    },
+    "registration",
+  );
+
+  const terminalStartedAt = performance.now();
+  for (const taskId of taskIds) {
+    const endedAt = Date.now();
+    const task = taskRecordApi.markTaskTerminalById({
+      taskId,
+      status: "succeeded",
+      endedAt,
+      lastEventAt: endedAt,
+      terminalOutcome: "succeeded",
+    });
+    if (!task) {
+      throw new Error(`terminal transition failed for task ${taskId}`);
+    }
+  }
+  const terminalMs = performance.now() - terminalStartedAt;
+  const terminal = readSnapshot();
+  assertSnapshot(
+    terminal,
+    {
+      ...emptyCounts,
+      taskCount: size,
+      deliveryStateCount: size,
+      succeededTasks: size,
+      pendingDeliveryTasks: size,
+      succeededTerminalOutcomes: size,
+    },
+    "terminal",
+  );
+
+  const teardownStartedAt = performance.now();
+  for (const taskId of taskIds) {
+    if (!taskRegistryQuery.deleteTaskRecordById(taskId)) {
+      throw new Error(`teardown failed for task ${taskId}`);
+    }
+  }
+  const teardownMs = performance.now() - teardownStartedAt;
+  const teardown = readSnapshot();
+  assertSnapshot(teardown, emptyCounts, "teardown");
+  return { registrationMs, terminalMs, teardownMs, registration, terminal, teardown };
+}
+
+async function resetRuntime(persist: boolean): Promise<void> {
+  const [tasks, stateDb] = await Promise.all([
+    import("../src/tasks/task-runtime.test-helpers.js"),
+    import("../src/state/openclaw-state-db.js"),
+  ]);
+  tasks.resetTaskRegistryForTests({ persist });
+  stateDb.closeOpenClawStateDatabaseForTest();
+}
+
+async function runBenchmark(options: WorkerOptions): Promise<WorkerResult> {
+  await resetRuntime(true);
+  // Load lifecycle owners before the baseline so warmup=0 still measures task churn,
+  // not one-time module initialization retained by the worker.
+  const [readSnapshot, taskRecordApi, taskRegistryQuery] = await Promise.all([
+    createCountReader(),
+    import("../src/tasks/task-registry-record-api.js"),
+    import("../src/tasks/task-registry-query.js"),
+  ]);
+  const emptyCounts: RegistryLifecycleCounts = {
+    taskCount: 0,
+    deliveryStateCount: 0,
+    runningTasks: 0,
+    succeededTasks: 0,
+    pendingDeliveryTasks: 0,
+    succeededTerminalOutcomes: 0,
+  };
+  assertSnapshot(readSnapshot(), emptyCounts, "initial");
+  const timingsMs = {
+    registration: [] as number[],
+    terminal: [] as number[],
+    teardown: [] as number[],
+  };
+  const postGcSamples: MemorySample[] = [];
+  let lastSample: TimingSample | undefined;
+  for (let index = 0; index < options.warmup; index += 1) {
+    await runCycle(options.size, index, readSnapshot, taskRecordApi, taskRegistryQuery);
+    forceGc();
+  }
+  forceGc();
+  const postGcBaseline = readMemorySample(-1);
+  for (let index = 0; index < options.cycles; index += 1) {
+    lastSample = await runCycle(
+      options.size,
+      options.warmup + index,
+      readSnapshot,
+      taskRecordApi,
+      taskRegistryQuery,
+    );
+    forceGc();
+    timingsMs.registration.push(lastSample.registrationMs);
+    timingsMs.terminal.push(lastSample.terminalMs);
+    timingsMs.teardown.push(lastSample.teardownMs);
+    postGcSamples.push(readMemorySample(index));
+  }
+  if (!lastSample) {
+    throw new Error("benchmark completed without a cycle");
+  }
+  const finalPostGcSample = postGcSamples.at(-1);
+  if (!finalPostGcSample) {
+    throw new Error("benchmark completed without a post-GC sample");
+  }
+  return {
+    size: options.size,
+    timingsMs,
+    memory: {
+      postGcBaseline,
+      postGcSamples,
+      retainedSlopesBytesPerCycle: retainedMemorySlopes(postGcSamples),
+      retainedDeltasBytes: retainedMemoryDelta(postGcBaseline, finalPostGcSample),
+      processPeakRssBytes: processPeakRssBytes(),
+    },
+    invariant: {
+      ok: true,
+      cyclesValidated: options.warmup + options.cycles,
+      registration: lastSample.registration,
+      terminal: lastSample.terminal,
+      teardown: lastSample.teardown,
+      serializedSharedConnection: true,
+    },
+  };
+}
+
+async function main(): Promise<void> {
+  const options = parseOptions(process.argv.slice(2));
+  const previousStateDir = process.env.OPENCLAW_STATE_DIR;
+  const previousNodeEnv = process.env.NODE_ENV;
+  let result: WorkerResult | undefined;
+  let failure: unknown;
+  process.env.OPENCLAW_STATE_DIR = options.stateDir;
+  process.env.NODE_ENV = "test";
+  try {
+    const { pinRuntimePaths } = await import("../src/config/paths.js");
+    pinRuntimePaths();
+    result = await runBenchmark(options);
+  } catch (error) {
+    failure = error;
+  } finally {
+    try {
+      await resetRuntime(false);
+    } catch (error) {
+      failure ??= error;
+    } finally {
+      if (previousStateDir === undefined) {
+        delete process.env.OPENCLAW_STATE_DIR;
+      } else {
+        process.env.OPENCLAW_STATE_DIR = previousStateDir;
+      }
+      if (previousNodeEnv === undefined) {
+        delete process.env.NODE_ENV;
+      } else {
+        process.env.NODE_ENV = previousNodeEnv;
+      }
+    }
+  }
+  if (failure) {
+    throw toErrorObject(failure, "Task registry SQLite benchmark failed");
+  }
+  if (!result) {
+    throw new Error("benchmark worker completed without a result");
+  }
+  process.stdout.write(`${WORKER_RESULT_SENTINEL}${JSON.stringify(result)}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.stack : String(error));
+    process.exitCode = 1;
+  } finally {
+    if (process.exitCode && process.exitCode !== 0) {
+      console.error(`[bench-task-registry-sqlite-worker] FAILED (exit ${process.exitCode})`);
+    }
+  }
+}

scripts/bench-task-registry-sqlite.ts

@@ -0,0 +1,470 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { isRecord } from "@openclaw/normalization-core/record-coerce";
+import {
+  emitBenchmarkReport,
+  parseBenchmarkInteger,
+  parseBenchmarkIntegerList,
+  parseBenchmarkOptions,
+  parseBenchmarkWorkerResult,
+  runBenchmarkEntrypoint,
+  runBenchmarkJobs,
+  runBenchmarkWorker,
+  summarizeBenchmarkTimings,
+  type BenchmarkWorkerProcessResult,
+  type BenchmarkWorkerSpawner,
+} from "./lib/benchmark-harness.mts";
+
+const DEFAULT_SIZES = [24, 64, 128];
+const WORKER_TIMEOUT_MS = 300_000;
+export const WORKER_RESULT_SENTINEL = "[bench-task-registry-sqlite-result] ";
+
+export type MemorySample = {
+  cycle: number;
+  heapUsedBytes: number;
+  heapTotalBytes: number;
+  rssBytes: number;
+  externalBytes: number;
+  arrayBuffersBytes: number;
+  processPeakRssBytes: number;
+};
+
+export type RetainedMemoryMetrics = Pick<
+  MemorySample,
+  "heapUsedBytes" | "heapTotalBytes" | "rssBytes" | "externalBytes" | "arrayBuffersBytes"
+>;
+
+export type RegistryLifecycleCounts = {
+  taskCount: number;
+  deliveryStateCount: number;
+  runningTasks: number;
+  succeededTasks: number;
+  pendingDeliveryTasks: number;
+  succeededTerminalOutcomes: number;
+};
+
+export type RegistrySnapshot = {
+  memory: RegistryLifecycleCounts;
+  sqlite: RegistryLifecycleCounts;
+};
+
+export type WorkerResult = {
+  size: number;
+  timingsMs: {
+    registration: number[];
+    terminal: number[];
+    teardown: number[];
+  };
+  memory: {
+    postGcBaseline: MemorySample;
+    postGcSamples: MemorySample[];
+    retainedSlopesBytesPerCycle: RetainedMemoryMetrics;
+    retainedDeltasBytes: RetainedMemoryMetrics;
+    processPeakRssBytes: number;
+  };
+  invariant: {
+    ok: boolean;
+    cyclesValidated: number;
+    registration: RegistrySnapshot;
+    terminal: RegistrySnapshot;
+    teardown: RegistrySnapshot;
+    serializedSharedConnection: boolean;
+  };
+};
+
+type Options = {
+  sizes: number[];
+  cycles: number;
+  warmup: number;
+  output?: string;
+  json: boolean;
+  help: boolean;
+};
+
+type WorkerLaunchRuntime = {
+  spawnWorker?: BenchmarkWorkerSpawner;
+};
+
+function usage(): string {
+  return `OpenClaw durable task registry churn benchmark
+
+Usage:
+  node --import tsx scripts/bench-task-registry-sqlite.ts [options]
+
+Options:
+  --sizes <list>  Comma-separated subagent task-record registration burst sizes (default: 24,64,128)
+  --cycles <n>    Measured create/terminal/delete cycles per size (default: 20)
+  --warmup <n>    Warmup cycles per size (default: 3)
+  --output <path> Write the JSON report to a file
+  --json          Print only the JSON report
+  --help          Show this text
+`;
+}
+
+function parseOptions(argv: string[]): Options {
+  return parseBenchmarkOptions<Options>(
+    argv,
+    {
+      sizes: DEFAULT_SIZES,
+      cycles: 20,
+      warmup: 3,
+      json: false,
+      help: false,
+    },
+    {
+      "--sizes": (options, value) => {
+        options.sizes = parseBenchmarkIntegerList(value, "--sizes", 4096);
+      },
+      "--cycles": (options, value) => {
+        options.cycles = parseBenchmarkInteger(value, "--cycles", 1, 200);
+      },
+      "--warmup": (options, value) => {
+        options.warmup = parseBenchmarkInteger(value, "--warmup", 0, 20);
+      },
+      "--output": (options, value) => {
+        options.output = value;
+      },
+    },
+  );
+}
+
+function assertFinite(value: unknown, field: string): asserts value is number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`worker result field ${field} must be finite`);
+  }
+}
+
+function assertFiniteNonNegative(value: unknown, field: string): asserts value is number {
+  assertFinite(value, field);
+  if (value < 0) {
+    throw new Error(`worker result field ${field} must be nonnegative`);
+  }
+}
+
+const MEMORY_FIELDS = [
+  "heapUsedBytes",
+  "heapTotalBytes",
+  "rssBytes",
+  "externalBytes",
+  "arrayBuffersBytes",
+  "processPeakRssBytes",
+] as const;
+
+const RETAINED_MEMORY_FIELDS = [
+  "heapUsedBytes",
+  "heapTotalBytes",
+  "rssBytes",
+  "externalBytes",
+  "arrayBuffersBytes",
+] as const;
+
+const LIFECYCLE_COUNT_FIELDS = [
+  "taskCount",
+  "deliveryStateCount",
+  "runningTasks",
+  "succeededTasks",
+  "pendingDeliveryTasks",
+  "succeededTerminalOutcomes",
+] as const;
+
+function validateMemorySample(
+  value: unknown,
+  expectedCycle: number,
+  field: string,
+): asserts value is MemorySample {
+  if (!isRecord(value) || value.cycle !== expectedCycle) {
+    throw new Error(`worker result ${field} has an invalid cycle`);
+  }
+  for (const memoryField of MEMORY_FIELDS) {
+    assertFiniteNonNegative(value[memoryField], `${field}.${memoryField}`);
+  }
+}
+
+function validateRegistrySnapshot(
+  value: unknown,
+  field: string,
+  expected: RegistryLifecycleCounts,
+): asserts value is RegistrySnapshot {
+  if (!isRecord(value) || !isRecord(value.memory) || !isRecord(value.sqlite)) {
+    throw new Error(`worker result field ${field} must be a registry snapshot`);
+  }
+  for (const surface of ["memory", "sqlite"] as const) {
+    const counts = surface === "memory" ? value.memory : value.sqlite;
+    for (const countField of LIFECYCLE_COUNT_FIELDS) {
+      const count = counts[countField];
+      assertFiniteNonNegative(count, `${field}.${surface}.${countField}`);
+      if (count !== expected[countField]) {
+        throw new Error(`worker result field ${field}.${surface}.${countField} was unexpected`);
+      }
+    }
+  }
+}
+
+function validateWorkerResult(
+  value: unknown,
+  expected: { size: number; cycles: number; warmup: number },
+): WorkerResult {
+  if (!isRecord(value)) {
+    throw new Error("worker result must be an object");
+  }
+  if (value.size !== expected.size) {
+    throw new Error(`worker size ${expected.size} returned mismatched identity`);
+  }
+  if (!isRecord(value.timingsMs)) {
+    throw new Error("worker result timingsMs must be an object");
+  }
+  for (const phase of ["registration", "terminal", "teardown"] as const) {
+    const timings = value.timingsMs[phase];
+    if (!Array.isArray(timings) || timings.length !== expected.cycles) {
+      throw new Error(
+        `worker size ${expected.size} returned ${Array.isArray(timings) ? timings.length : "invalid"} ${phase} samples; expected ${expected.cycles}`,
+      );
+    }
+    timings.forEach((timing, index) =>
+      assertFiniteNonNegative(timing, `timingsMs.${phase}[${index}]`),
+    );
+  }
+  if (!isRecord(value.memory)) {
+    throw new Error("worker result memory must be an object");
+  }
+  const postGcBaseline = value.memory.postGcBaseline;
+  validateMemorySample(postGcBaseline, -1, "memory.postGcBaseline");
+  if (
+    !Array.isArray(value.memory.postGcSamples) ||
+    value.memory.postGcSamples.length !== expected.cycles
+  ) {
+    throw new Error(
+      `worker size ${expected.size} returned invalid post-GC sample count; expected ${expected.cycles}`,
+    );
+  }
+  value.memory.postGcSamples.forEach((sample, index) =>
+    validateMemorySample(sample, index, `memory.postGcSamples[${index}]`),
+  );
+  const postGcSamples = value.memory.postGcSamples as MemorySample[];
+  if (!isRecord(value.memory.retainedSlopesBytesPerCycle)) {
+    throw new Error("worker result retained memory slopes must be an object");
+  }
+  if (!isRecord(value.memory.retainedDeltasBytes)) {
+    throw new Error("worker result retained memory deltas must be an object");
+  }
+  const finalPostGcSample = postGcSamples.at(-1);
+  if (!finalPostGcSample) {
+    throw new Error("worker result must include a final post-GC sample");
+  }
+  for (const field of RETAINED_MEMORY_FIELDS) {
+    assertFinite(
+      value.memory.retainedSlopesBytesPerCycle[field],
+      `memory.retainedSlopesBytesPerCycle.${field}`,
+    );
+    assertFinite(value.memory.retainedDeltasBytes[field], `memory.retainedDeltasBytes.${field}`);
+    const expectedDelta = finalPostGcSample[field] - postGcBaseline[field];
+    if (value.memory.retainedDeltasBytes[field] !== expectedDelta) {
+      throw new Error(
+        `worker result memory.retainedDeltasBytes.${field} must be end minus baseline`,
+      );
+    }
+  }
+  if ("processPeakRssBytes" in value.memory.retainedSlopesBytesPerCycle) {
+    throw new Error("worker result retained memory slopes must exclude process peak RSS");
+  }
+  if ("processPeakRssBytes" in value.memory.retainedDeltasBytes) {
+    throw new Error("worker result retained memory deltas must exclude process peak RSS");
+  }
+  assertFiniteNonNegative(value.memory.processPeakRssBytes, "memory.processPeakRssBytes");
+  if (!isRecord(value.invariant)) {
+    throw new Error("worker result invariant must be an object");
+  }
+  assertFiniteNonNegative(value.invariant.cyclesValidated, "invariant.cyclesValidated");
+  const emptyCounts: RegistryLifecycleCounts = {
+    taskCount: 0,
+    deliveryStateCount: 0,
+    runningTasks: 0,
+    succeededTasks: 0,
+    pendingDeliveryTasks: 0,
+    succeededTerminalOutcomes: 0,
+  };
+  validateRegistrySnapshot(value.invariant.registration, "invariant.registration", {
+    ...emptyCounts,
+    taskCount: expected.size,
+    deliveryStateCount: expected.size,
+    runningTasks: expected.size,
+    pendingDeliveryTasks: expected.size,
+  });
+  validateRegistrySnapshot(value.invariant.terminal, "invariant.terminal", {
+    ...emptyCounts,
+    taskCount: expected.size,
+    deliveryStateCount: expected.size,
+    succeededTasks: expected.size,
+    pendingDeliveryTasks: expected.size,
+    succeededTerminalOutcomes: expected.size,
+  });
+  validateRegistrySnapshot(value.invariant.teardown, "invariant.teardown", emptyCounts);
+  if (
+    value.invariant.ok !== true ||
+    value.invariant.serializedSharedConnection !== true ||
+    value.invariant.cyclesValidated !== expected.cycles + expected.warmup
+  ) {
+    throw new Error(`worker size ${expected.size} reported a failed invariant`);
+  }
+  return value as WorkerResult;
+}
+
+function parseWorkerProcessResult(
+  result: BenchmarkWorkerProcessResult,
+  expected: { size: number; cycles: number; warmup: number },
+): WorkerResult {
+  return parseBenchmarkWorkerResult({
+    result,
+    label: `size ${expected.size}`,
+    sentinel: WORKER_RESULT_SENTINEL,
+    timeoutMs: WORKER_TIMEOUT_MS,
+    validate: (value) => validateWorkerResult(value, expected),
+  });
+}
+
+function runWorker(
+  options: Options,
+  size: number,
+  runtime: WorkerLaunchRuntime = {},
+): WorkerResult {
+  const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-task-registry-bench-"));
+  try {
+    return runBenchmarkWorker({
+      args: [
+        "--expose-gc",
+        "--import",
+        "tsx",
+        "scripts/bench-task-registry-sqlite-worker.ts",
+        "--size",
+        String(size),
+        "--cycles",
+        String(options.cycles),
+        "--warmup",
+        String(options.warmup),
+        "--state-dir",
+        stateDir,
+      ],
+      label: `size ${size}`,
+      sentinel: WORKER_RESULT_SENTINEL,
+      spawnWorker: runtime.spawnWorker,
+      timeoutMs: WORKER_TIMEOUT_MS,
+      validate: (value) =>
+        validateWorkerResult(value, {
+          size,
+          cycles: options.cycles,
+          warmup: options.warmup,
+        }),
+    });
+  } finally {
+    fs.rmSync(stateDir, { recursive: true, force: true });
+  }
+}
+
+function aggregateWorkerResults(options: Options, workers: WorkerResult[]) {
+  const bySize = new Map(workers.map((worker) => [worker.size, worker]));
+  if (bySize.size !== workers.length) {
+    throw new Error("worker results contain duplicate sizes");
+  }
+  const missing = options.sizes.filter((size) => !bySize.has(size));
+  const unexpected = [...bySize.keys()].filter((size) => !options.sizes.includes(size));
+  if (missing.length > 0 || unexpected.length > 0) {
+    throw new Error(
+      `worker result mismatch: missing=${missing.join(",") || "none"} unexpected=${unexpected.join(",") || "none"}`,
+    );
+  }
+  const sizes = options.sizes.map((size) => {
+    const worker = bySize.get(size);
+    if (!worker) {
+      throw new Error(`missing worker result for size ${size}`);
+    }
+    return {
+      size,
+      timingsMs: {
+        registration: summarizeBenchmarkTimings(worker.timingsMs.registration),
+        terminal: summarizeBenchmarkTimings(worker.timingsMs.terminal),
+        teardown: summarizeBenchmarkTimings(worker.timingsMs.teardown),
+      },
+      memory: worker.memory,
+      invariant: worker.invariant,
+    };
+  });
+  const failures = sizes
+    .filter((entry) => !entry.invariant.ok)
+    .map((entry) => `size:${entry.size}`);
+  return {
+    schemaVersion: 1,
+    benchmark: "durable-task-registry-churn",
+    generatedAt: new Date().toISOString(),
+    runtime: { node: process.version, platform: process.platform, arch: process.arch },
+    model: {
+      unit: "subagent task-record registrations",
+      execution:
+        "serialized create, terminal, and delete calls through one process-local shared SQLite connection",
+      isolation: "fresh --expose-gc worker process per size",
+      workload:
+        "all task records start running with pending delivery, transition to succeeded with a succeeded terminal outcome, then delete",
+    },
+    interpretation: {
+      timings: "advisory only; this is not a concurrent SQLite writer benchmark",
+      memory:
+        "post-GC baseline, end-minus-baseline retained deltas, and retained slopes are diagnostic only; they neither claim nor rule out a memory leak",
+    },
+    options: {
+      sizes: options.sizes,
+      cycles: options.cycles,
+      warmup: options.warmup,
+    },
+    memory: {
+      workerProcessPeakRssBytes: Math.max(
+        ...workers.map((worker) => worker.memory.processPeakRssBytes),
+      ),
+    },
+    sizes,
+    invariants: {
+      ok: failures.length === 0,
+      failures,
+      exactRegistrationTerminalAndTeardownState: failures.length === 0,
+      zeroRowsAfterEveryTeardown: failures.length === 0,
+    },
+  };
+}
+
+function benchmark(options: Options) {
+  const workers = runBenchmarkJobs(options.sizes, {
+    prefix: "bench-task-registry-sqlite",
+    describe: (size) => `size=${size}`,
+    run: (size) => runWorker(options, size),
+  });
+  return aggregateWorkerResults(options, workers);
+}
+
+async function main(argv = process.argv.slice(2)): Promise<void> {
+  const options = parseOptions(argv);
+  if (options.help) {
+    process.stdout.write(usage());
+    return;
+  }
+  const report = benchmark(options);
+  emitBenchmarkReport(report, options, (result) => [
+    ...result.sizes.map((entry) => {
+      const registration = entry.timingsMs.registration;
+      const heapSlope = entry.memory.retainedSlopesBytesPerCycle.heapUsedBytes;
+      return `size=${entry.size} registration-p50=${registration.p50.toFixed(3)}ms registration-max=${registration.max.toFixed(3)}ms post-gc-heap-slope=${heapSlope.toFixed(1)}B/cycle`;
+    }),
+    result.interpretation.timings,
+    result.interpretation.memory,
+  ]);
+}
+
+export const testing = {
+  aggregateWorkerResults,
+  parseOptions,
+  parseWorkerProcessResult,
+  runWorker,
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  await runBenchmarkEntrypoint("bench-task-registry-sqlite", main);
+}

scripts/build-diffs-viewer-runtime.mts

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+// Builds browser runtime bundles for the diffs viewer assets.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { build, type Plugin } from "esbuild";
+import { writeGeneratedTextAsset } from "./lib/generated-text-asset.mts";
+
+const modulePath = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(modulePath), "..");
+const pierreDiffsEmptySideEffectNamespace = "openclaw-diffs-empty-side-effect";
+const pierreDiffsEmptySideEffectPath = "pierre-diffs-parse-decorations-side-effect";
+
+const targets = {
+  curated: {
+    entry: "extensions/diffs/src/viewer-client.ts",
+    output: "extensions/diffs/assets/viewer-runtime.js",
+    shikiAlias: "scripts/diffs-shiki-curated.ts",
+    languagePackAvailable: false,
+  },
+  full: {
+    entry: "extensions/diffs/src/viewer-client.ts",
+    output: "extensions/diffs-language-pack/assets/viewer-runtime.js",
+    languagePackAvailable: true,
+  },
+};
+
+function toPosixPath(value: string) {
+  return value.replaceAll("\\", "/");
+}
+
+/**
+ * Creates the esbuild plugin that neutralizes Pierre diffs' browser side-effect import.
+ */
+export function createPierreDiffsSideEffectImportPlugin(): {
+  name: string;
+  setup(buildContext: unknown): void;
+};
+export function createPierreDiffsSideEffectImportPlugin() {
+  return {
+    name: "openclaw-diffs-pierre-side-effect-imports",
+    setup(buildContext) {
+      buildContext.onResolve({ filter: /^diff$/ }, (args) => {
+        const importer = toPosixPath(args.importer);
+        if (!importer.endsWith("/@pierre/diffs/dist/utils/parseDiffDecorations.js")) {
+          return undefined;
+        }
+        return {
+          path: pierreDiffsEmptySideEffectPath,
+          namespace: pierreDiffsEmptySideEffectNamespace,
+          sideEffects: true,
+        };
+      });
+      buildContext.onLoad(
+        {
+          filter: /^pierre-diffs-parse-decorations-side-effect$/,
+          namespace: pierreDiffsEmptySideEffectNamespace,
+        },
+        () => ({
+          contents: "export {};\n",
+          loader: "js",
+        }),
+      );
+    },
+  } satisfies Plugin;
+}
+
+/**
+ * Builds one configured diffs viewer runtime target.
+ */
+async function buildDiffsViewerRuntime(targetName: string | undefined) {
+  const target = Object.entries(targets).find(([name]) => name === targetName)?.[1];
+  if (!target) {
+    throw new Error(
+      `Usage: node --import tsx scripts/build-diffs-viewer-runtime.mts ${Object.keys(targets).join("|")}`,
+    );
+  }
+
+  const outputPath = path.join(repoRoot, target.output);
+  const shikiAlias = "shikiAlias" in target ? target.shikiAlias : undefined;
+  const result = await build({
+    entryPoints: [path.join(repoRoot, target.entry)],
+    bundle: true,
+    platform: "browser",
+    target: "es2020",
+    format: "esm",
+    minify: true,
+    define: {
+      __OPENCLAW_DIFFS_LANGUAGE_PACK__: String(target.languagePackAvailable),
+      NaN: "Number.NaN",
+    },
+    legalComments: "none",
+    outfile: outputPath,
+    write: false,
+    plugins: [
+      createPierreDiffsSideEffectImportPlugin(),
+      ...(shikiAlias
+        ? [
+            {
+              name: "openclaw-diffs-curated-shiki",
+              setup(buildContext) {
+                buildContext.onResolve({ filter: /^shiki$/ }, () => ({
+                  path: path.join(repoRoot, shikiAlias),
+                }));
+              },
+            } satisfies Plugin,
+          ]
+        : []),
+    ],
+  });
+
+  const outputFile = result.outputFiles?.[0];
+  if (!outputFile) {
+    throw new Error(`esbuild did not produce ${target.output}`);
+  }
+
+  const runtime = outputFile.text.replace(/[ \t]+$/gm, "");
+  await writeGeneratedTextAsset(outputPath, runtime);
+}
+
+if (process.argv[1] === modulePath) {
+  await buildDiffsViewerRuntime(process.argv[2]);
+}

scripts/build-plugin-control-ui.mts

@@ -0,0 +1,35 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  buildPluginControlUi,
+  writePluginBuildManifest,
+} from "../src/cli/plugins-control-ui-build.js";
+import { controlUiSource } from "../src/plugins/package-manifest.js";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+
+const rootDir = process.cwd();
+const packageManifest = JSON.parse(await fs.readFile(path.join(rootDir, "package.json"), "utf8"));
+const manifest = JSON.parse(await fs.readFile(path.join(rootDir, "openclaw.plugin.json"), "utf8"));
+if (process.argv.includes("--copy")) {
+  const repoRoot = resolveRepoRoot(import.meta.url);
+  const pluginDir = path.relative(path.join(repoRoot, "extensions"), rootDir);
+  if (!pluginDir || pluginDir.includes(path.sep) || pluginDir.startsWith(".")) {
+    throw new Error("Bundled UI copy must run inside one bundled plugin package.");
+  }
+  const output = path.dirname(manifest.controlUi.entry);
+  if (!/^dist\/control-ui\/[a-f0-9]{64}$/u.test(output)) {
+    throw new Error("Build the plugin's immutable Control UI assets before copying.");
+  }
+  await fs.cp(
+    path.join(rootDir, output),
+    path.join(repoRoot, "dist/extensions", pluginDir, output),
+    { recursive: true },
+  );
+} else {
+  const source = controlUiSource(packageManifest);
+  if (!source) {
+    throw new Error("Missing package.json openclaw.controlUi browser entrypoint.");
+  }
+  manifest.controlUi = await buildPluginControlUi({ rootDir, source });
+  await writePluginBuildManifest(rootDir, manifest);
+}

scripts/bundle-a2ui.mts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+// Runs bundled asset build hooks for the Canvas A2UI runtime.
+import { pathToFileURL } from "node:url";
+import { runBundledPluginAssetHooks } from "./bundled-plugin-assets.mts";
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await runBundledPluginAssetHooks({ phase: "build", plugins: ["canvas"] });
+}

scripts/capture-composer-mic-hover-proof.mts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { chromium } from "playwright";
+// Captures composer mic-hover proof shots: idle vs hovered talk control, plus
+// the mic button's x position in both states (the hover-shift regression).
+import { createControlUiE2eArtifactDir } from "../ui/src/test-helpers/control-ui-e2e-artifacts.ts";
+import {
+  canRunPlaywrightChromium,
+  installMockGateway,
+  resolvePlaywrightChromiumExecutablePath,
+  startControlUiE2eServer,
+} from "../ui/src/test-helpers/control-ui-e2e.ts";
+import { readControlUiProofOption } from "./lib/control-ui-proof-args.mts";
+
+const outputDir = createControlUiE2eArtifactDir(
+  "composer-mic-hover-proof",
+  readControlUiProofOption(process.argv, "output-dir") ??
+    ".artifacts/control-ui-e2e/composer-mic-hover-proof",
+);
+const label = readControlUiProofOption(process.argv, "label") ?? "after";
+const executablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
+if (!canRunPlaywrightChromium(executablePath)) {
+  throw new Error(`Playwright Chromium is unavailable at ${executablePath}`);
+}
+
+const server = await startControlUiE2eServer(undefined, { source: true });
+const browser = await chromium.launch({ executablePath });
+const context = await browser.newContext({
+  colorScheme: "dark",
+  viewport: { width: 1280, height: 800 },
+});
+const page = await context.newPage();
+page.setDefaultTimeout(30_000);
+
+try {
+  await installMockGateway(page);
+  await page.goto(`${server.baseUrl}chat`);
+  const composer = page.locator(".agent-chat__input");
+  await composer.waitFor({ state: "visible" });
+  const voice = page.getByRole("button", { name: "Start voice input" });
+  await voice.waitFor({ state: "visible" });
+
+  await page.mouse.move(10, 10);
+  await page.waitForTimeout(400);
+  const composerBox = await composer.boundingBox();
+  if (!composerBox) {
+    throw new Error("composer has no layout box");
+  }
+  const clip = {
+    x: Math.max(0, composerBox.x - 12),
+    y: Math.max(0, composerBox.y - 12),
+    width: Math.min(1280, composerBox.width + 24),
+    height: composerBox.height + 24,
+  };
+  const idleVoiceBox = await voice.boundingBox();
+  await page.screenshot({ clip, path: path.join(outputDir, `${label}-idle.png`) });
+
+  await voice.hover();
+  await page.waitForTimeout(400);
+  const hoverVoiceBox = await voice.boundingBox();
+  await page.screenshot({ clip, path: path.join(outputDir, `${label}-hover.png`) });
+
+  const picker = page.getByRole("button", { name: "Microphone input" });
+  if (await picker.count()) {
+    await picker.hover();
+    await page.waitForTimeout(400);
+    await page.screenshot({ clip, path: path.join(outputDir, `${label}-hover-chevron.png`) });
+    await picker.click();
+    await page.waitForTimeout(500);
+    await page.screenshot({
+      path: path.join(outputDir, `${label}-picker-open.png`),
+      clip: { ...clip, y: Math.max(0, clip.y - 260), height: clip.height + 260 },
+    });
+    await page.keyboard.press("Escape");
+  }
+
+  if (!idleVoiceBox || !hoverVoiceBox) {
+    throw new Error("voice button has no layout box");
+  }
+  console.log(
+    JSON.stringify(
+      {
+        label,
+        idleVoiceX: idleVoiceBox.x,
+        hoverVoiceX: hoverVoiceBox.x,
+        hoverShiftPx: hoverVoiceBox.x - idleVoiceBox.x,
+        outputDir,
+      },
+      null,
+      2,
+    ),
+  );
+} finally {
+  await context.close();
+  await browser.close();
+  await server.close();
+}

scripts/capture-injected-turn-notice-proof.mts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { chromium } from "playwright";
+// Captures webchat proof that a CLI harness-injected user turn renders as a
+// collapsed system notice while the operator's own message keeps its bubble.
+// Usage: node --import tsx scripts/capture-injected-turn-notice-proof.mts [--mode after|before]
+import { createControlUiE2eArtifactDir } from "../ui/src/test-helpers/control-ui-e2e-artifacts.ts";
+import {
+  canRunPlaywrightChromium,
+  installMockGateway,
+  resolvePlaywrightChromiumExecutablePath,
+  startControlUiE2eServer,
+} from "../ui/src/test-helpers/control-ui-e2e.ts";
+import { readControlUiProofOption } from "./lib/control-ui-proof-args.mts";
+
+const mode = readControlUiProofOption(process.argv, "mode") ?? "after";
+if (mode !== "after" && mode !== "before") {
+  throw new Error(`Expected --mode after|before, received ${mode}`);
+}
+const outputDir = createControlUiE2eArtifactDir(
+  "injected-turn-notice-proof",
+  readControlUiProofOption(process.argv, "output-dir") ??
+    ".artifacts/control-ui-e2e/injected-turn-notice-proof",
+);
+
+const baseTime = Date.parse("2026-08-26T20:37:00.000Z");
+const skillBody = [
+  "Base directory for this skill: /tmp/skills/autoreview",
+  "",
+  "# Auto Review",
+  "",
+  "Run the bundled structured review helper as a closeout check.",
+].join("\n");
+// Mirrors the chat.history payload proven by the gateway integration test:
+// the operator turn is a plain user row; the harness-injected turn carries the
+// provenance recorded by the claude-cli importer. Before the fix the importer
+// dropped that provenance, so --mode before omits it to reproduce the shipped
+// payload.
+const historyMessages = [
+  {
+    role: "user",
+    content: "Run the autoreview skill on this branch.",
+    timestamp: baseTime,
+    __openclaw: { id: "user-1", seq: 1 },
+  },
+  {
+    role: "user",
+    content: [{ type: "text", text: skillBody }],
+    ...(mode === "after"
+      ? { provenance: { kind: "internal_system", sourceTool: "cli_harness_context" } }
+      : {}),
+    timestamp: baseTime + 1_000,
+    __openclaw: {
+      id: "skill-meta-1",
+      importedFrom: "claude-cli",
+      cliSessionId: "cli-session-1",
+      externalId: "skill-meta-1",
+      seq: 2,
+    },
+  },
+  {
+    role: "assistant",
+    content: "Autoreview finished: no findings.",
+    timestamp: baseTime + 2_000,
+    __openclaw: { id: "assistant-1", seq: 3 },
+  },
+];
+
+const executablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
+if (!canRunPlaywrightChromium(executablePath)) {
+  throw new Error(`Playwright Chromium is unavailable at ${executablePath}`);
+}
+
+const server = await startControlUiE2eServer(undefined, { source: true });
+const browser = await chromium.launch({ executablePath });
+try {
+  const context = await browser.newContext({
+    colorScheme: "dark",
+    locale: "en-US",
+    reducedMotion: "reduce",
+    serviceWorkers: "block",
+    viewport: { width: 1280, height: 900 },
+  });
+  const page = await context.newPage();
+  page.setDefaultTimeout(30_000);
+  await installMockGateway(page, { historyMessages });
+  await page.goto(`${server.baseUrl}chat`);
+  await page.getByText("Autoreview finished: no findings.").waitFor({ state: "visible" });
+  await page.getByText("Run the autoreview skill on this branch.").waitFor({ state: "visible" });
+  if (mode === "after") {
+    // The injected turn renders as a collapsed system notice; expand it so the
+    // capture shows the disclosure carrying the skill body.
+    const toggle = page.locator(".chat-notice__toggle");
+    await toggle.waitFor({ state: "visible" });
+    await toggle.click();
+    await page.getByText("Base directory for this skill:", { exact: false }).waitFor({
+      state: "visible",
+    });
+  } else {
+    await page.getByText("Base directory for this skill:", { exact: false }).waitFor({
+      state: "visible",
+    });
+  }
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+    await new Promise<void>((resolve) => {
+      requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+    });
+  });
+  const target = path.join(outputDir, `injected-turn-${mode}.png`);
+  await page.locator(".chat-thread-inner").screenshot({ animations: "disabled", path: target });
+  console.log(`captured ${target}`);
+  await context.close();
+} finally {
+  await browser.close();
+  await server.close();
+}

scripts/capture-where-chip-auto-proof.mts

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// Captures placement, inventory, and context-meter proof in both themes.
+import assert from "node:assert/strict";
+import path from "node:path";
+import { chromium } from "playwright";
+import { createControlUiE2eArtifactDir } from "../ui/src/test-helpers/control-ui-e2e-artifacts.ts";
+import {
+  canRunPlaywrightChromium,
+  installMockGateway,
+  resolvePlaywrightChromiumExecutablePath,
+  startControlUiE2eServer,
+} from "../ui/src/test-helpers/control-ui-e2e.ts";
+
+const captureLabel = process.argv[2] ?? "after";
+const outputDir = createControlUiE2eArtifactDir(
+  "node-slot-pips-proof",
+  process.argv[3] ?? "/tmp/node-slot-pips-proof",
+);
+const remoteExec = process.argv[4] === "remote-exec";
+const executablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
+if (!canRunPlaywrightChromium(executablePath)) {
+  throw new Error(`Playwright Chromium unavailable at ${executablePath}`);
+}
+const server = await startControlUiE2eServer(undefined, { source: true });
+const browser = await chromium.launch({ executablePath });
+const environments = [
+  { id: "idle", label: "Idle runner", workerSlots: { total: 8, available: 8 } },
+  { id: "partial", label: "Busy runner", workerSlots: { total: 8, available: 5 } },
+  { id: "full", label: "Full runner", workerSlots: { total: 8, available: 0 } },
+  { id: "offline", label: "Offline runner", workerSlots: { total: 8, available: 2 } },
+  { id: "large", label: "Large runner", workerSlots: { total: 13, available: 6 } },
+  { id: "exec", label: "Terminal runner" },
+].map(({ id, label, workerSlots }) => ({
+  id: `node:${id}`,
+  label,
+  workerSlots,
+  type: "node",
+  status: id === "offline" ? "unavailable" : "available",
+  sessionHost: true,
+  platform: "linux",
+  capabilities: ["codex.exec-server"],
+  invocableCommands: ["codex.exec-server.stdio.v1"],
+}));
+try {
+  for (const mode of ["dark", "light"] as const) {
+    const context = await browser.newContext({
+      colorScheme: mode,
+      locale: "en-US",
+      viewport: { width: 1280, height: 900 },
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(30_000);
+    const config = { ui: { prefs: { theme: "claw", themeMode: mode } } };
+    await installMockGateway(page, {
+      ...(remoteExec
+        ? {
+            agentModel: "openai/gpt-5.6-luna",
+            models: [
+              {
+                available: true,
+                id: "gpt-5.6-luna",
+                name: "GPT-5.6 Luna",
+                provider: "openai",
+                agentRuntime: {
+                  id: "codex",
+                  devicePlacementSupported: true,
+                  source: "model",
+                  devicePlacement: {
+                    requiredNodeCommands: ["codex.exec-server.stdio.v1"],
+                    consumesWorkerSlot: false,
+                  },
+                },
+              },
+            ],
+          }
+        : {}),
+      methodResponses: {
+        "config.get": { config, hash: "capacity-proof", valid: true, issues: [] },
+        "environments.list": {
+          environments,
+          profiles: [],
+        },
+        "node.list": {
+          nodes: environments.map((entry) => ({
+            nodeId: entry.id.slice(5),
+            displayName: entry.label,
+            platform: entry.platform,
+            paired: true,
+            connected: entry.status === "available",
+            approvalState: "approved",
+            caps: entry.capabilities,
+            commands: entry.invocableCommands,
+            workerSlots: entry.workerSlots,
+          })),
+        },
+        "sessions.list": {
+          count: 4,
+          ts: 0,
+          path: "",
+          defaults: {},
+          sessions: [
+            { label: "Context OK", totalTokens: 40_000 },
+            { label: "Context warning", totalTokens: 140_000 },
+            { label: "Context danger", totalTokens: 180_000 },
+            { label: "Context approximate", totalTokens: 180_000, totalTokensFresh: false },
+          ].map(({ label, totalTokens, totalTokensFresh }, index) => ({
+            label,
+            totalTokens,
+            totalTokensFresh,
+            key: `agent:main:context-${index}`,
+            kind: "direct",
+            updatedAt: 0,
+            contextTokens: 200_000,
+            hasActiveRun: false,
+          })),
+        },
+      },
+    });
+    await page.goto(`${server.baseUrl}new`);
+    const chip = page.getByText("Local", { exact: true }).first();
+    await chip.waitFor();
+    await page.waitForFunction(
+      (themeMode) => document.documentElement.dataset.themeMode === themeMode,
+      mode,
+    );
+    await page.evaluate(() => document.fonts.ready);
+    await chip.click();
+    await page.waitForSelector('[data-value="auto-device"]');
+    await page.locator('[data-value="device:exec"]').waitFor();
+    if (remoteExec) {
+      assert.equal(await page.locator('[data-value="device:full"]').isEnabled(), true);
+      assert.equal(await page.locator('[data-value="device:exec"]').isEnabled(), true);
+    }
+    await page.screenshot({
+      path: path.join(outputDir, `${captureLabel}-${mode}-menu.png`),
+      animations: "disabled",
+    });
+    await page.locator('[data-value="auto-device"]').click();
+    await page.locator('#new-session-where-trigger[data-auto-device="true"]').waitFor();
+    if (remoteExec) {
+      await page.locator("#new-session-where-trigger").click();
+      await page.locator('[data-value="device:full"]').click();
+      await page.locator('#new-session-where-trigger[data-device-id="full"]').waitFor();
+      console.log("SHOT_OK", captureLabel, mode, outputDir);
+      await context.close();
+      continue;
+    }
+    await page.goto(`${server.baseUrl}settings/devices`);
+    await page.getByText("Terminal runner", { exact: true }).waitFor();
+    await page.screenshot({
+      path: path.join(outputDir, `${captureLabel}-${mode}-devices.png`),
+      animations: "disabled",
+    });
+    await page.goto(`${server.baseUrl}sessions`);
+    await page.locator(".session-context-meter").first().waitFor();
+    assert.equal(await page.locator(".session-context-meter").count(), 4);
+    await page.evaluate(() => document.fonts.ready);
+    await page.locator(".data-table-container").screenshot({
+      path: path.join(outputDir, `${captureLabel}-${mode}-sessions.png`),
+      animations: "disabled",
+    });
+    console.log("SHOT_OK", captureLabel, mode, outputDir);
+    await context.close();
+  }
+} finally {
+  await browser.close();
+  await server.close();
+}

scripts/capture-workboard-ui-proof.mts

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { chromium } from "playwright";
+import { createControlUiE2eArtifactDir } from "../ui/src/test-helpers/control-ui-e2e-artifacts.ts";
+import {
+  canRunPlaywrightChromium,
+  resolvePlaywrightChromiumExecutablePath,
+} from "../ui/src/test-helpers/control-ui-e2e.ts";
+import { readControlUiProofOption } from "./lib/control-ui-proof-args.mts";
+const DEFAULT_BASE_URL = "http://127.0.0.1:5187";
+const DEFAULT_OUTPUT_DIR = path.resolve(".artifacts/control-ui-e2e/workboard-proof");
+const WORKBOARD_SESSION_KEY = "agent:main:workboard-proof";
+
+const baseUrl = new URL(readControlUiProofOption(process.argv, "base-url") ?? DEFAULT_BASE_URL);
+const outputDir = createControlUiE2eArtifactDir(
+  "workboard-proof",
+  readControlUiProofOption(process.argv, "output-dir") ?? DEFAULT_OUTPUT_DIR,
+);
+const executablePath = resolvePlaywrightChromiumExecutablePath(chromium.executablePath());
+if (!canRunPlaywrightChromium(executablePath)) {
+  throw new Error(`Playwright Chromium is unavailable at ${executablePath}`);
+}
+
+const browser = await chromium.launch({ executablePath });
+const context = await browser.newContext({
+  colorScheme: "light",
+  reducedMotion: "reduce",
+  viewport: { width: 1440, height: 900 },
+});
+const page = await context.newPage();
+page.setDefaultTimeout(30_000);
+
+const gatewayUrl = new URL(baseUrl);
+gatewayUrl.protocol = gatewayUrl.protocol === "https:" ? "wss:" : "ws:";
+const settingsKey = `openclaw.control.settings.v1:${gatewayUrl.origin}`;
+await page.addInitScript(
+  ({ key, sessionKey }) => {
+    localStorage.setItem(
+      key,
+      JSON.stringify({
+        boardSessionViews: { [sessionKey]: { activeTabId: "main" } },
+        theme: "light",
+      }),
+    );
+  },
+  { key: settingsKey, sessionKey: WORKBOARD_SESSION_KEY },
+);
+
+try {
+  await page.goto(new URL("/workboard/peter-tasks", baseUrl).toString());
+  const automationChip = page.locator(".workboard-automation-chip");
+  await automationChip.waitFor();
+  if ((await automationChip.textContent())?.trim() !== "Automation") {
+    throw new Error("Workboard automation chip did not render its expected label");
+  }
+  await page.getByText("Prepare launch readiness checklist", { exact: true }).waitFor();
+  await page.screenshot({
+    animations: "disabled",
+    path: path.join(outputDir, "workboard-chip.png"),
+  });
+
+  await page.goto(new URL("/dashboard", baseUrl).toString());
+  const widget = page.locator('[data-test-id="workboard-board-widget"]');
+  await widget.waitFor();
+  await widget.getByRole("heading", { name: "Validate onboarding flow", exact: true }).waitFor();
+  await widget.getByRole("heading", { name: "Review accessibility audit", exact: true }).waitFor();
+  await page.locator(".board-session-surface--dock-hidden").waitFor();
+  const columnCount = await widget.locator(".workboard-column").count();
+  if (columnCount !== 6) {
+    throw new Error(`Expected 6 Workboard columns, received ${columnCount}`);
+  }
+  await page.screenshot({
+    animations: "disabled",
+    path: path.join(outputDir, "workboard-widget.png"),
+  });
+} finally {
+  await context.close();
+  await browser.close();
+}
+
+console.log(`[workboard-ui-proof] ${outputDir}`);

scripts/changed-lanes.mjs

@@ -0,0 +1,5 @@
+import { runTsxCliShim } from "./lib/tsx-cli-shim.mjs";
+
+await runTsxCliShim(import.meta.url, {
+  implementation: "./changed-lanes.mts",
+});

scripts/check-built-plugin-control-plane-modules.mts

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+
+// Verifies built plugin control-plane artifacts through Node's native require(esm) path.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type ts from "typescript";
+import { resolveNodeRuntimeExecutable } from "../src/infra/node-runtime-executable.ts";
+import { collectSourceCheckoutPluginBuildEntries } from "./lib/bundled-plugin-build-entries.mjs";
+import { isRecord } from "./lib/record-shared.mjs";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+import { getTypeScript } from "./lib/ts-guard-utils.mts";
+
+type BuiltPluginControlPlaneModule = {
+  pluginId: string;
+  kind: string;
+  relativePath: string;
+};
+
+type BuiltPluginControlPlaneModuleFailure = BuiltPluginControlPlaneModule & {
+  error: string;
+};
+
+type BuiltDoctorContractClosureViolation = BuiltPluginControlPlaneModule & {
+  dependency: string;
+  importerPath: string;
+};
+
+type ProbeParams = {
+  rootDir?: string;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+};
+
+const ROOT = resolveRepoRoot(import.meta.url);
+const DIRECT_CONTRACT_ENTRIES = ["contract-api", "doctor-contract-api"];
+const LEGACY_SETUP_PROPERTIES = new Map<string, string>([
+  ["legacyStateMigrations", "channel-legacy-state-migrations"],
+  ["legacySessionSurface", "channel-legacy-session-surface"],
+  ["legacySessionSurfaces", "channel-legacy-session-surface"],
+]);
+const PROBE_RESULT_MARKER = "__OPENCLAW_PLUGIN_CONTROL_PLANE_PROBE__";
+const DEFAULT_TIMEOUT_MS = 120_000;
+// Doctor enumeration cold-loads every declaring plugin's contract closure, so a
+// doctor artifact must never reach the process-spawn graph. Requiring the artifact
+// cannot prove this: plain Node resolves the whole graph fine, and the cost and the
+// ESM-only transitive deps (execa -> npm-run-path -> unicorn-magic, which has no
+// `require` condition) only surface on source-run hosts whose CJS-flavored resolver
+// rejects them. `doctor-contract-closure-guard.test.ts` owns the same invariant over
+// sources; bundling can merge runtime code into the artifact behind its back, so the
+// built closure is checked here.
+const FORBIDDEN_DOCTOR_CONTRACT_DEPENDENCIES = ["execa"];
+const REQUIRE_PROBE_SOURCE = String.raw`
+const { createRequire } = require("node:module");
+const path = require("node:path");
+const targets = JSON.parse(Buffer.from(process.argv[1], "base64url").toString("utf8"));
+const requireFromRoot = createRequire(path.join(process.cwd(), "package.json"));
+const failures = [];
+for (const target of targets) {
+  try {
+    requireFromRoot(path.resolve(process.cwd(), target.relativePath));
+  } catch (error) {
+    failures.push({
+      ...target,
+      error: error instanceof Error ? (error.stack || error.message) : String(error),
+    });
+  }
+}
+process.stdout.write("\n${PROBE_RESULT_MARKER}" + JSON.stringify({ failures }));
+`;
+
+function propertyNameText(name: ts.PropertyName) {
+  const ts = getTypeScript();
+  return ts.isIdentifier(name) || ts.isStringLiteralLike(name) ? name.text : "";
+}
+
+function listLegacySetupModuleSpecifiers(setupEntryPath: string) {
+  const ts = getTypeScript();
+  const source = fs.readFileSync(setupEntryPath, "utf8");
+  const sourceFile = ts.createSourceFile(setupEntryPath, source, ts.ScriptTarget.Latest, true);
+  const specifiers: Array<{ kind: string; specifier: string }> = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isPropertyAssignment(node) && ts.isObjectLiteralExpression(node.initializer)) {
+      const kind = LEGACY_SETUP_PROPERTIES.get(propertyNameText(node.name));
+      if (kind) {
+        const specifierProperty = node.initializer.properties.find(
+          (property) =>
+            ts.isPropertyAssignment(property) && propertyNameText(property.name) === "specifier",
+        );
+        if (
+          specifierProperty &&
+          ts.isPropertyAssignment(specifierProperty) &&
+          ts.isStringLiteralLike(specifierProperty.initializer)
+        ) {
+          specifiers.push({ kind, specifier: specifierProperty.initializer.text });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return specifiers;
+}
+
+/** Lists exact built doctor, contract, and channel legacy migration artifacts. */
+export function listBuiltPluginControlPlaneModules(
+  params: Pick<ProbeParams, "rootDir" | "env"> = {},
+) {
+  const rootDir = path.resolve(params.rootDir ?? ROOT);
+  const extensionsDir = path.join(rootDir, "dist", "extensions");
+  if (!fs.existsSync(extensionsDir)) {
+    return [];
+  }
+  const sourceEntries = new Map(
+    (fs.existsSync(path.join(rootDir, "extensions"))
+      ? collectSourceCheckoutPluginBuildEntries({ cwd: rootDir, env: params.env })
+      : []
+    ).map((entry) => [entry.id, entry]),
+  );
+  const modules = new Map<string, BuiltPluginControlPlaneModule>();
+  for (const entry of fs
+    .readdirSync(extensionsDir, { withFileTypes: true })
+    .filter((candidate) => candidate.isDirectory())
+    .toSorted((left, right) => left.name.localeCompare(right.name))) {
+    const pluginId = entry.name;
+    const pluginDir = path.join(extensionsDir, pluginId);
+    // Packaged core artifacts use ESM; isolated source-checkout plugins use
+    // the same selected format as their builder and generated metadata.
+    const extension = sourceEntries.get(pluginId)?.runtimeExtension ?? ".js";
+    for (const entryName of DIRECT_CONTRACT_ENTRIES) {
+      const fileName = `${entryName}${extension}`;
+      const modulePath = path.join(pluginDir, fileName);
+      if (fs.existsSync(modulePath)) {
+        const relativePath = path.relative(rootDir, modulePath).split(path.sep).join("/");
+        modules.set(relativePath, {
+          pluginId,
+          kind: entryName === "doctor-contract-api" ? "doctor-contract" : "contract",
+          relativePath,
+        });
+      }
+    }
+    const setupEntryPath = path.join(pluginDir, `setup-entry${extension}`);
+    if (!fs.existsSync(setupEntryPath)) {
+      continue;
+    }
+    for (const { kind, specifier } of listLegacySetupModuleSpecifiers(setupEntryPath)) {
+      const modulePath = path.resolve(pluginDir, specifier);
+      const pluginRelativePath = path.relative(pluginDir, modulePath);
+      if (pluginRelativePath.startsWith(`..${path.sep}`) || path.isAbsolute(pluginRelativePath)) {
+        throw new Error(`${pluginId} setup entry module escapes the plugin root: ${specifier}`);
+      }
+      const relativePath = path.relative(rootDir, modulePath).split(path.sep).join("/");
+      modules.set(relativePath, { pluginId, kind, relativePath });
+    }
+  }
+  return [...modules.values()].toSorted((left, right) =>
+    left.relativePath.localeCompare(right.relativePath),
+  );
+}
+
+/** Loads every selected artifact in one timeout-bounded native-require child. */
+export function probeBuiltPluginControlPlaneModules(
+  modules: BuiltPluginControlPlaneModule[],
+  params: ProbeParams = {},
+) {
+  if (modules.length === 0) {
+    return [];
+  }
+  const rootDir = path.resolve(params.rootDir ?? ROOT);
+  const encodedTargets = Buffer.from(JSON.stringify(modules), "utf8").toString("base64url");
+  const result = spawnSync(
+    resolveNodeRuntimeExecutable() ?? process.execPath,
+    ["-e", REQUIRE_PROBE_SOURCE, encodedTargets],
+    {
+      cwd: rootDir,
+      encoding: "utf8",
+      maxBuffer: 8 * 1024 * 1024,
+      timeout: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    },
+  );
+  if (result.error) {
+    throw new Error(
+      `built plugin control-plane native-require probe failed: ${result.error.message}`,
+    );
+  }
+  const markerIndex = result.stdout.lastIndexOf(PROBE_RESULT_MARKER);
+  if (markerIndex < 0) {
+    throw new Error(
+      `built plugin control-plane native-require probe exited ${String(result.status)} without a result`,
+    );
+  }
+  const payload: unknown = JSON.parse(
+    result.stdout.slice(markerIndex + PROBE_RESULT_MARKER.length),
+  );
+  if (!isRecord(payload) || !Array.isArray(payload.failures)) {
+    return [];
+  }
+  return payload.failures.filter(
+    (failure): failure is BuiltPluginControlPlaneModuleFailure =>
+      isRecord(failure) &&
+      typeof failure.pluginId === "string" &&
+      typeof failure.kind === "string" &&
+      typeof failure.relativePath === "string" &&
+      typeof failure.error === "string",
+  );
+}
+
+// Follow ESM declarations and eager CJS require calls emitted by isolated builds.
+// Dynamic imports and requires inside functions are lazy, not enumeration costs.
+function parseStaticModuleSpecifiers(source: string, filePath: string): string[] {
+  const ts = getTypeScript();
+  const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true);
+  const specifiers: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isFunctionLike(node)) {
+      return;
+    }
+    const moduleSpecifier =
+      ts.isImportDeclaration(node) || ts.isExportDeclaration(node)
+        ? node.moduleSpecifier
+        : ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            /^(?:require|_+require\d*)$/u.test(node.expression.text)
+          ? node.arguments[0]
+          : undefined;
+    if (moduleSpecifier && ts.isStringLiteralLike(moduleSpecifier)) {
+      specifiers.push(moduleSpecifier.text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return specifiers;
+}
+
+function resolveBuiltChunkPath(importerPath: string, specifier: string): string | undefined {
+  const target = path.resolve(path.dirname(importerPath), specifier);
+  // Generated chunk edges carry their exact output suffix, including CJS.
+  return fs.existsSync(target) && fs.statSync(target).isFile() ? target : undefined;
+}
+
+/** Collects the bare dependencies a built artifact reaches through static imports. */
+function collectBuiltModuleStaticDependencies(entryPath: string): Map<string, string> {
+  const dependencies = new Map<string, string>();
+  const visited = new Set<string>();
+  const pending: string[] = [entryPath];
+  while (pending.length > 0) {
+    const filePath = pending.pop();
+    if (!filePath || visited.has(filePath)) {
+      continue;
+    }
+    visited.add(filePath);
+    let source: string;
+    try {
+      source = fs.readFileSync(filePath, "utf8");
+    } catch {
+      continue;
+    }
+    for (const reference of parseStaticModuleSpecifiers(source, filePath)) {
+      if (reference.startsWith(".") || reference.startsWith("/")) {
+        const resolved = resolveBuiltChunkPath(filePath, reference);
+        if (resolved) {
+          pending.push(resolved);
+        }
+        continue;
+      }
+      if (!reference.startsWith("node:") && !dependencies.has(reference)) {
+        dependencies.set(reference, filePath);
+      }
+    }
+  }
+  return dependencies;
+}
+
+/** Fails when a built doctor artifact statically reaches a forbidden runtime dependency. */
+export function collectBuiltDoctorContractClosureViolations(
+  modules: BuiltPluginControlPlaneModule[],
+  params: { rootDir?: string } = {},
+): BuiltDoctorContractClosureViolation[] {
+  const rootDir = path.resolve(params.rootDir ?? ROOT);
+  const violations: BuiltDoctorContractClosureViolation[] = [];
+  for (const module of modules.filter((candidate) => candidate.kind === "doctor-contract")) {
+    const dependencies = collectBuiltModuleStaticDependencies(
+      path.join(rootDir, module.relativePath),
+    );
+    for (const dependency of FORBIDDEN_DOCTOR_CONTRACT_DEPENDENCIES) {
+      const importer = dependencies.get(dependency);
+      if (importer) {
+        violations.push({
+          ...module,
+          dependency,
+          importerPath: path.relative(rootDir, importer).split(path.sep).join("/"),
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+/** Fails the build when a generated plugin control-plane module cannot be required natively. */
+export function verifyBuiltPluginControlPlaneModules(params: ProbeParams = {}) {
+  const modules = listBuiltPluginControlPlaneModules(params);
+  const failures = probeBuiltPluginControlPlaneModules(modules, params);
+  if (failures.length > 0) {
+    const details = failures.map(
+      (failure) =>
+        `- ${failure.pluginId} (${failure.kind}) ${failure.relativePath}: ${failure.error}`,
+    );
+    throw new Error(`built plugin control-plane module load failures:\n${details.join("\n")}`);
+  }
+  const closureViolations = collectBuiltDoctorContractClosureViolations(modules, params);
+  if (closureViolations.length > 0) {
+    const details = closureViolations.map(
+      (violation) =>
+        `- ${violation.pluginId} ${violation.relativePath} statically reaches ${violation.dependency} through ${violation.importerPath}`,
+    );
+    throw new Error(
+      `built doctor contract closures reach forbidden runtime dependencies:\n${details.join("\n")}`,
+    );
+  }
+  console.error(
+    `[plugin-control-plane-loads] verified ${modules.length} built modules with native require and checked doctor closures`,
+  );
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  verifyBuiltPluginControlPlaneModules();
+}

scripts/check-changed.mjs

@@ -0,0 +1,5 @@
+import { runTsxCliShim } from "./lib/tsx-cli-shim.mjs";
+
+await runTsxCliShim(import.meta.url, {
+  implementation: "./check-changed.mts",
+});

scripts/check-changelog-attributions.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runNodeCliShim } from "./lib/tsx-cli-shim.mjs";
+
+await runNodeCliShim(import.meta.url, { implementation: "./check-changelog-attributions.mts" });

scripts/check-channel-agnostic-boundaries.mts

@@ -0,0 +1,368 @@
+#!/usr/bin/env node
+
+// Checks channel-agnostic core surfaces for channel-specific coupling.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { visitModuleSpecifiers } from "./lib/guard-inventory-utils.mjs";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+import {
+  collectTypeScriptFiles,
+  getPropertyNameText,
+  runAsScript,
+  toLine,
+} from "./lib/ts-guard-utils.mts";
+
+const repoRoot = resolveRepoRoot(import.meta.url);
+
+const acpCoreProtectedSources = [
+  path.join(repoRoot, "src", "acp"),
+  path.join(repoRoot, "src", "agents", "subagents", "spawn", "acp-spawn.ts"),
+  path.join(repoRoot, "src", "auto-reply", "reply", "commands-acp"),
+  path.join(repoRoot, "src", "infra", "outbound", "conversation-id.ts"),
+];
+
+const channelCoreProtectedSources = [
+  path.join(repoRoot, "src", "channels", "thread-bindings-policy.ts"),
+  path.join(repoRoot, "src", "channels", "thread-bindings-messages.ts"),
+  path.join(repoRoot, "src", "sessions", "send-policy.ts"),
+  path.join(repoRoot, "src", "sessions", "session-chat-type-shared.ts"),
+  path.join(repoRoot, "src", "utils", "delivery-context.shared.ts"),
+];
+const acpUserFacingTextSources = [
+  path.join(repoRoot, "src", "auto-reply", "reply", "commands-acp"),
+];
+const systemMarkLiteralGuardSources = [
+  path.join(repoRoot, "src", "auto-reply", "reply", "commands-acp"),
+  path.join(repoRoot, "src", "auto-reply", "reply", "dispatch-acp.ts"),
+  path.join(repoRoot, "src", "auto-reply", "reply", "directive-handling.shared.ts"),
+  path.join(repoRoot, "src", "channels", "thread-bindings-messages.ts"),
+];
+
+const channelIds = [
+  "discord",
+  "googlechat",
+  "imessage",
+  "irc",
+  "line",
+  "mattermost",
+  "matrix",
+  "msteams",
+  "nextcloud-talk",
+  "nostr",
+  "qqbot",
+  "signal",
+  "slack",
+  "synology-chat",
+  "telegram",
+  "tlon",
+  "twitch",
+  "web",
+  "whatsapp",
+  "zalo",
+  "zalouser",
+];
+
+const channelIdSet = new Set(channelIds);
+const channelSegmentRe = new RegExp(`(^|[._/-])(?:${channelIds.join("|")})([._/-]|$)`);
+const comparisonOperators: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.EqualsEqualsEqualsToken,
+  ts.SyntaxKind.ExclamationEqualsEqualsToken,
+  ts.SyntaxKind.EqualsEqualsToken,
+  ts.SyntaxKind.ExclamationEqualsToken,
+]);
+
+const allowedViolations = new Set<string>();
+
+type BoundaryViolation = { line: number; reason: string };
+type BoundaryOptions = {
+  checkModuleSpecifiers?: boolean;
+  checkConfigPaths?: boolean;
+  checkChannelComparisons?: boolean;
+  checkChannelAssignments?: boolean;
+  moduleSpecifierMatcher?: (specifier: string) => boolean;
+};
+type ModuleSpecifierVisit = {
+  kind: string;
+  node: ts.Node;
+  specifier: string;
+  specifierNode: ts.Node;
+};
+function isChannelsPropertyAccess(node: ts.Node) {
+  if (ts.isPropertyAccessExpression(node)) {
+    return node.name.text === "channels";
+  }
+  if (ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression)) {
+    return node.argumentExpression.text === "channels";
+  }
+  return false;
+}
+
+function readStringLiteral(node: ts.Node) {
+  if (ts.isStringLiteral(node)) {
+    return node.text;
+  }
+  if (ts.isNoSubstitutionTemplateLiteral(node)) {
+    return node.text;
+  }
+  return null;
+}
+
+function isChannelLiteralNode(node: ts.Node) {
+  const text = readStringLiteral(node);
+  return text ? channelIdSet.has(text) : false;
+}
+
+function matchesChannelModuleSpecifier(specifier: string) {
+  return channelSegmentRe.test(specifier.replaceAll("\\", "/"));
+}
+
+const userFacingChannelNameRe =
+  /\b(?:discord|telegram|slack|signal|imessage|whatsapp|google\s*chat|irc|line|zalo|matrix|msteams)\b/i;
+const systemMarkLiteral = "⚙️";
+
+function isModuleSpecifierStringNode(node: ts.Node) {
+  const parent = node.parent;
+  if (ts.isImportDeclaration(parent) || ts.isExportDeclaration(parent)) {
+    return true;
+  }
+  return (
+    ts.isCallExpression(parent) &&
+    parent.expression.kind === ts.SyntaxKind.ImportKeyword &&
+    parent.arguments[0] === node
+  );
+}
+
+/**
+ * Finds channel-specific references inside channel-agnostic protected sources.
+ */
+export function findChannelAgnosticBoundaryViolations(
+  content: string,
+  fileName = "source.ts",
+  options: BoundaryOptions = {},
+) {
+  const checkModuleSpecifiers = options.checkModuleSpecifiers ?? true;
+  const checkConfigPaths = options.checkConfigPaths ?? true;
+  const checkChannelComparisons = options.checkChannelComparisons ?? true;
+  const checkChannelAssignments = options.checkChannelAssignments ?? true;
+  const moduleSpecifierMatcher = options.moduleSpecifierMatcher ?? matchesChannelModuleSpecifier;
+
+  const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+  const violations: BoundaryViolation[] = [];
+  const moduleViolations = new Map<ts.Node, BoundaryViolation>();
+  if (checkModuleSpecifiers) {
+    visitModuleSpecifiers(
+      ts,
+      sourceFile,
+      ({ kind, node, specifier, specifierNode }: ModuleSpecifierVisit) => {
+        if (moduleSpecifierMatcher(specifier)) {
+          const verb =
+            kind === "export"
+              ? "re-exports"
+              : kind === "dynamic-import"
+                ? "dynamically imports"
+                : "imports";
+          moduleViolations.set(node, {
+            line: toLine(sourceFile, specifierNode),
+            reason: verb + ' channel module "' + specifier + '"',
+          });
+        }
+      },
+      { includeCommonJs: true, includeImportMetaUrl: true, includeImportTypes: true },
+    );
+  }
+
+  const visit = (node: ts.Node): void => {
+    const moduleViolation = moduleViolations.get(node);
+    if (moduleViolation) {
+      violations.push(moduleViolation);
+    }
+
+    if (
+      checkConfigPaths &&
+      ts.isPropertyAccessExpression(node) &&
+      channelIdSet.has(node.name.text)
+    ) {
+      if (isChannelsPropertyAccess(node.expression)) {
+        violations.push({
+          line: toLine(sourceFile, node.name),
+          reason: `references config path "channels.${node.name.text}"`,
+        });
+      }
+    }
+
+    if (
+      checkConfigPaths &&
+      ts.isElementAccessExpression(node) &&
+      ts.isStringLiteral(node.argumentExpression) &&
+      channelIdSet.has(node.argumentExpression.text)
+    ) {
+      if (isChannelsPropertyAccess(node.expression)) {
+        violations.push({
+          line: toLine(sourceFile, node.argumentExpression),
+          reason: `references config path "channels[${JSON.stringify(node.argumentExpression.text)}]"`,
+        });
+      }
+    }
+
+    if (
+      checkChannelComparisons &&
+      ts.isBinaryExpression(node) &&
+      comparisonOperators.has(node.operatorToken.kind)
+    ) {
+      if (isChannelLiteralNode(node.left) || isChannelLiteralNode(node.right)) {
+        const leftText = node.left.getText(sourceFile);
+        const rightText = node.right.getText(sourceFile);
+        violations.push({
+          line: toLine(sourceFile, node.operatorToken),
+          reason: `compares with channel id literal (${leftText} ${node.operatorToken.getText(sourceFile)} ${rightText})`,
+        });
+      }
+    }
+
+    if (checkChannelAssignments && ts.isPropertyAssignment(node)) {
+      const propName = getPropertyNameText(node.name);
+      if (propName === "channel" && isChannelLiteralNode(node.initializer)) {
+        violations.push({
+          line: toLine(sourceFile, node.initializer),
+          reason: `assigns channel id literal to "channel" (${node.initializer.getText(sourceFile)})`,
+        });
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return violations;
+}
+
+/**
+ * Finds reverse dependencies from channel core into plugin/runtime surfaces.
+ */
+export function findChannelCoreReverseDependencyViolations(
+  content: string,
+  fileName = "source.ts",
+) {
+  return findChannelAgnosticBoundaryViolations(content, fileName, {
+    checkModuleSpecifiers: true,
+    checkConfigPaths: false,
+    checkChannelComparisons: false,
+    checkChannelAssignments: false,
+    moduleSpecifierMatcher: matchesChannelModuleSpecifier,
+  });
+}
+
+/**
+ * Finds user-facing channel names in ACP-owned text sources.
+ */
+export function findAcpUserFacingChannelNameViolations(content: string, fileName = "source.ts") {
+  const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+  const violations: BoundaryViolation[] = [];
+
+  const visit = (node: ts.Node): void => {
+    const text = readStringLiteral(node);
+    if (text && userFacingChannelNameRe.test(text) && !isModuleSpecifierStringNode(node)) {
+      violations.push({
+        line: toLine(sourceFile, node),
+        reason: `user-facing text references channel name (${JSON.stringify(text)})`,
+      });
+    }
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return violations;
+}
+
+/**
+ * Finds raw system mark literals where shared constants should be used.
+ */
+export function findSystemMarkLiteralViolations(content: string, fileName = "source.ts") {
+  const sourceFile = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+  const violations: BoundaryViolation[] = [];
+
+  const visit = (node: ts.Node): void => {
+    const text = readStringLiteral(node);
+    if (text && text.includes(systemMarkLiteral) && !isModuleSpecifierStringNode(node)) {
+      violations.push({
+        line: toLine(sourceFile, node),
+        reason: `hardcoded system mark literal (${JSON.stringify(text)})`,
+      });
+    }
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return violations;
+}
+
+const boundaryRuleSets = [
+  {
+    id: "acp-core",
+    sources: acpCoreProtectedSources,
+    scan: findChannelAgnosticBoundaryViolations,
+  },
+  {
+    id: "channel-core-reverse-deps",
+    sources: channelCoreProtectedSources,
+    scan: findChannelCoreReverseDependencyViolations,
+  },
+  {
+    id: "acp-user-facing-text",
+    sources: acpUserFacingTextSources,
+    scan: findAcpUserFacingChannelNameViolations,
+  },
+  {
+    id: "system-mark-literal-usage",
+    sources: systemMarkLiteralGuardSources,
+    scan: findSystemMarkLiteralViolations,
+  },
+];
+
+/**
+ * Runs all channel-agnostic boundary checks.
+ */
+export async function main() {
+  const violations: string[] = [];
+  for (const ruleSet of boundaryRuleSets) {
+    const files = (
+      await Promise.all(
+        ruleSet.sources.map(
+          async (sourcePath) =>
+            await collectTypeScriptFiles(sourcePath, {
+              ignoreMissing: true,
+            }),
+        ),
+      )
+    ).flat();
+    for (const filePath of files) {
+      const relativeFile = path.relative(repoRoot, filePath);
+      if (
+        allowedViolations.has(`${ruleSet.id}:${relativeFile}`) ||
+        allowedViolations.has(relativeFile)
+      ) {
+        continue;
+      }
+      const content = await fs.readFile(filePath, "utf8");
+      for (const violation of ruleSet.scan(content, relativeFile)) {
+        violations.push(`${ruleSet.id} ${relativeFile}:${violation.line}: ${violation.reason}`);
+      }
+    }
+  }
+
+  if (violations.length === 0) {
+    return;
+  }
+
+  console.error("Found channel-specific references in channel-agnostic sources:");
+  for (const violation of violations) {
+    console.error(`- ${violation}`);
+  }
+  console.error(
+    "Move channel-specific logic to channel adapters or add a justified allowlist entry.",
+  );
+  process.exit(1);
+}
+
+runAsScript(import.meta.url, main);

scripts/check-cli-startup-memory.mjs

@@ -0,0 +1,610 @@
+#!/usr/bin/env node
+// Measures CLI startup memory with an isolated home and an in-process bench entry.
+import { spawnSync as defaultSpawnSync } from "node:child_process";
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  ftruncateSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readlinkSync,
+  realpathSync,
+  rmSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+const repoRoot = resolveRepoRoot(import.meta.url);
+const tmpDir = process.env.TMPDIR || process.env.TEMP || process.env.TMP || os.tmpdir();
+const MAX_RSS_MARKER = "__OPENCLAW_MAX_RSS_KB__=";
+const DEFAULT_COMMAND_TIMEOUT_MS = 60_000;
+const STARTUP_MEMORY_SAMPLE_COUNT = 3;
+const STARTUP_MEMORY_RSS_TOLERANCE_MB = 1;
+const COMMAND_TIMEOUT_MS = readPositiveIntEnv(
+  "OPENCLAW_STARTUP_MEMORY_TIMEOUT_MS",
+  DEFAULT_COMMAND_TIMEOUT_MS,
+);
+let tmpHome = null;
+let benchEntryPath = null;
+const PASS = "pass";
+const FAIL = "fail";
+const REPORT_PATH_FILE_ERROR = "--json and --summary must refer to files";
+const REPORT_PATH_CHANGED_ERROR = "--json or --summary changed during startup benchmarks";
+const REPORT_PATH_ALIAS_ERROR = "--json and --summary must refer to different files";
+function readPositiveIntEnv(name, fallback, env = process.env) {
+  const value = readPositiveNumberEnv(name, fallback, env);
+  if (!Number.isSafeInteger(value)) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return value;
+}
+function readPositiveNumberEnv(name, fallback, env = process.env) {
+  const raw = env[name];
+  if (raw === undefined || raw === "") {
+    return fallback;
+  }
+  const text = raw.trim();
+  if (!/^(?:\d+(?:\.\d+)?|\.\d+)$/u.test(text)) {
+    throw new Error(`${name} must be a positive number`);
+  }
+  const value = Number(text);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a positive number`);
+  }
+  return value;
+}
+function readNonEmptyEnv(name) {
+  const value = process.env[name];
+  return value === undefined || value.length === 0 ? null : value;
+}
+function readRequiredPathOption(argv, index, flag) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("-")) {
+    throw new Error(`${flag} requires a path`);
+  }
+  return value;
+}
+function parseArgs(argv) {
+  const options = {
+    jsonPath:
+      readNonEmptyEnv("OPENCLAW_STARTUP_MEMORY_JSON_PATH") ??
+      path.join(repoRoot, ".artifacts", "startup-memory", "startup-memory.json"),
+    summaryPath:
+      readNonEmptyEnv("OPENCLAW_STARTUP_MEMORY_SUMMARY_PATH") ??
+      path.join(repoRoot, ".artifacts", "startup-memory", "summary.md"),
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === undefined) {
+      break;
+    }
+    if (arg === "--json") {
+      const value = readRequiredPathOption(argv, index, "--json");
+      options.jsonPath = path.resolve(value);
+      index += 1;
+      continue;
+    }
+    if (arg === "--summary") {
+      const value = readRequiredPathOption(argv, index, "--summary");
+      options.summaryPath = path.resolve(value);
+      index += 1;
+      continue;
+    }
+    if (arg === "--help") {
+      console.log(
+        "Usage: node scripts/check-cli-startup-memory.mjs [--json <path>] [--summary <path>]",
+      );
+      process.exit(0);
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+  return options;
+}
+const sameFsObject = (left, right) => left.dev === right.dev && left.ino === right.ino;
+function createReportParents(filePath) {
+  const parentPath = path.dirname(filePath);
+  const firstCreated = mkdirSync(parentPath, { recursive: true });
+  if (!firstCreated) {
+    return [];
+  }
+  const created = [];
+  for (let current = parentPath; ; current = path.dirname(current)) {
+    created.push({ identity: lstatSync(current, { bigint: true }), path: current });
+    if (current === firstCreated) {
+      return created;
+    }
+  }
+}
+function resolveReportLeaf(filePath, unresolvedLinks = new Set()) {
+  const physicalParent = realpathSync.native(path.dirname(filePath));
+  const leafPath = path.join(physicalParent, path.basename(filePath));
+  const identity = lstatSync(leafPath, { bigint: true, throwIfNoEntry: false });
+  if (!identity?.isSymbolicLink()) {
+    return leafPath;
+  }
+  if (unresolvedLinks.has(leafPath)) {
+    throw Object.assign(new Error("Symlink cycle while resolving report path"), { code: "ELOOP" });
+  }
+  unresolvedLinks.add(leafPath);
+  const target = readlinkSync(leafPath);
+  const lastComponent = target.slice(target.lastIndexOf(path.sep) + 1);
+  if (lastComponent === "" || lastComponent === "." || lastComponent === "..") {
+    throw new Error(REPORT_PATH_FILE_ERROR);
+  }
+  return resolveReportLeaf(
+    path.isAbsolute(target) ? target : `${physicalParent}${path.sep}${target}`,
+    unresolvedLinks,
+  );
+}
+function openReport(requestedPath) {
+  const resolvedPath = resolveReportLeaf(requestedPath);
+  let created = false;
+  let fd;
+  try {
+    fd = openSync(
+      resolvedPath,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_RDWR,
+      0o600,
+    );
+    created = true;
+  } catch (error) {
+    if (error?.code !== "EEXIST") {
+      throw error;
+    }
+    fd = openSync(resolvedPath, fsConstants.O_RDWR | fsConstants.O_NOFOLLOW);
+  }
+  const identity = fstatSync(fd, { bigint: true });
+  if (!identity.isFile()) {
+    closeSync(fd);
+    throw new Error(REPORT_PATH_FILE_ERROR);
+  }
+  return { created, fd, identity, path: resolvedPath, requestedPath };
+}
+function assertReportReservation(report) {
+  if (sameFsObject(report.identity, statSync(report.requestedPath, { bigint: true }))) {
+    return;
+  }
+  throw new Error(REPORT_PATH_CHANGED_ERROR);
+}
+function cleanupReservation({ reports, parents }) {
+  for (const report of reports.toReversed()) {
+    try {
+      if (!report.created) {
+        continue;
+      }
+      const current = lstatSync(report.path, { bigint: true, throwIfNoEntry: false });
+      if (current?.isFile() && sameFsObject(report.identity, current)) {
+        unlinkSync(report.path);
+      }
+    } catch {}
+  }
+  const deepestFirst = parents.toSorted(
+    (left, right) => right.path.split(path.sep).length - left.path.split(path.sep).length,
+  );
+  for (const parent of deepestFirst) {
+    try {
+      const current = lstatSync(parent.path, { bigint: true, throwIfNoEntry: false });
+      if (current?.isDirectory() && sameFsObject(parent.identity, current)) {
+        rmdirSync(parent.path);
+      }
+    } catch {}
+  }
+}
+function closeReports(reports, index = reports.length - 1) {
+  if (index < 0) {
+    return;
+  }
+  try {
+    closeSync(reports[index].fd);
+  } finally {
+    closeReports(reports, index - 1);
+  }
+}
+function reserveReports(options) {
+  const parents = [];
+  const reports = [];
+  try {
+    for (const filePath of [options.jsonPath, options.summaryPath]) {
+      parents.push(...createReportParents(filePath));
+    }
+    reports.push(openReport(options.jsonPath));
+    reports.push(openReport(options.summaryPath));
+    reports.forEach(assertReportReservation);
+    if (sameFsObject(reports[0].identity, reports[1].identity)) {
+      throw new Error(REPORT_PATH_ALIAS_ERROR);
+    }
+    return { parents, reports };
+  } catch (error) {
+    try {
+      closeReports(reports);
+    } catch {}
+    cleanupReservation({ parents, reports });
+    throw error;
+  }
+}
+function resolveDefaultLimitsMb(platform = process.platform) {
+  return {
+    // Linux CI is the tight startup regression signal. macOS consistently reports
+    // higher RSS for the same launcher path, so keep it supported without hiding
+    // Linux help-path regressions.
+    help: platform === "darwin" ? 300 : 100,
+    // Plugin discovery is heavier than help, but must stay below the doctor/channel
+    // runtime graph that an empty metadata-only invocation must not import.
+    pluginsList: platform === "darwin" ? 500 : 400,
+    // Node 24 status startup reaches ~430 MB on current Linux runner images;
+    // retain useful regression headroom without failing on allocator variance.
+    statusJson: 450,
+    gatewayStatus: 500,
+  };
+}
+const DEFAULT_LIMITS_MB = resolveDefaultLimitsMb();
+const cases = [
+  {
+    id: "help",
+    label: "--help",
+    args: ["openclaw.mjs", "--help"],
+    limitMb: readPositiveNumberEnv("OPENCLAW_STARTUP_MEMORY_HELP_MB", DEFAULT_LIMITS_MB.help),
+  },
+  {
+    id: "pluginsList",
+    label: "plugins list --json",
+    args: ["openclaw.mjs", "plugins", "list", "--json"],
+    limitMb: readPositiveNumberEnv(
+      "OPENCLAW_STARTUP_MEMORY_PLUGINS_LIST_MB",
+      DEFAULT_LIMITS_MB.pluginsList,
+    ),
+  },
+  {
+    id: "statusJson",
+    label: "status --json",
+    args: ["openclaw.mjs", "status", "--json"],
+    limitMb: readPositiveNumberEnv(
+      "OPENCLAW_STARTUP_MEMORY_STATUS_JSON_MB",
+      DEFAULT_LIMITS_MB.statusJson,
+    ),
+  },
+  {
+    id: "gatewayStatus",
+    label: "gateway status",
+    args: ["openclaw.mjs", "gateway", "status"],
+    limitMb: readPositiveNumberEnv(
+      "OPENCLAW_STARTUP_MEMORY_GATEWAY_STATUS_MB",
+      DEFAULT_LIMITS_MB.gatewayStatus,
+    ),
+  },
+];
+function formatFixGuidance(testCase, details) {
+  const command = `node ${testCase.args.join(" ")}`;
+  const guidance = [
+    "[startup-memory] Fix guidance",
+    `Case: ${testCase.label}`,
+    `Command: ${command}`,
+    "Next steps:",
+    `1. Run \`${command}\` locally on the built tree.`,
+    "2. If this is an RSS overage, compare the startup import graph against the last passing commit and look for newly eager imports, bootstrap side effects, or plugin loading on the command path.",
+    "3. If this is a non-zero exit, inspect the first transitive import/config error in stderr and fix that root cause before re-checking memory.",
+    "LLM prompt:",
+    `"OpenClaw startup-memory CI failed for '${testCase.label}'. Analyze this failure, identify the first runtime/import side effect that makes startup heavier or broken, and propose the smallest safe patch. Failure output:\n${details}"`,
+  ];
+  return `${guidance.join("\n")}\n`;
+}
+function formatFailure(testCase, message, details = "") {
+  const trimmedDetails = details.trim();
+  const sections = [message];
+  if (trimmedDetails) {
+    sections.push(trimmedDetails);
+  }
+  sections.push(formatFixGuidance(testCase, trimmedDetails || message));
+  return sections.join("\n\n");
+}
+function failResult(report, testCase, error, details = "") {
+  return {
+    ...report,
+    status: FAIL,
+    error,
+    failureMessage: formatFailure(testCase, error, details),
+  };
+}
+function parseMaxRssMb(stderr) {
+  const matches = [...stderr.matchAll(new RegExp(`^${MAX_RSS_MARKER}(\\d+)\\s*$`, "gm"))];
+  const lastMatch = matches.at(-1);
+  if (!lastMatch) {
+    return null;
+  }
+  const maxRssKb = Number(lastMatch[1]);
+  return Number.isFinite(maxRssKb) && maxRssKb > 0 ? maxRssKb / 1024 : null;
+}
+function formatMb(value) {
+  return typeof value === "number" && Number.isFinite(value) ? `${value.toFixed(1)} MB` : "n/a";
+}
+function formatCaseCommand(testCase) {
+  return `node ${testCase.args.join(" ")}`;
+}
+function nodeImportSpecifierForPath(filePath) {
+  return pathToFileURL(filePath).href;
+}
+function buildBenchEnv(homeDir = tmpHome) {
+  if (!homeDir) {
+    throw new Error("temporary home is not initialized");
+  }
+  const env = {
+    HOME: homeDir,
+    USERPROFILE: homeDir,
+    XDG_CONFIG_HOME: path.join(homeDir, ".config"),
+    XDG_DATA_HOME: path.join(homeDir, ".local", "share"),
+    XDG_CACHE_HOME: path.join(homeDir, ".cache"),
+    PATH: process.env.PATH ?? "",
+    TMPDIR: tmpDir,
+    TEMP: tmpDir,
+    TMP: tmpDir,
+    LANG: process.env.LANG ?? "C.UTF-8",
+    TERM: process.env.TERM ?? "dumb",
+  };
+  if (process.env.LC_ALL) {
+    env.LC_ALL = process.env.LC_ALL;
+  }
+  if (process.env.CI) {
+    env.CI = process.env.CI;
+  }
+  if (process.env.NODE_DISABLE_COMPILE_CACHE) {
+    env.NODE_DISABLE_COMPILE_CACHE = process.env.NODE_DISABLE_COMPILE_CACHE;
+  } else {
+    // Keep the regression check focused on app/runtime startup, not Node's
+    // one-shot compile cache overhead, which varies across runner builds.
+    env.NODE_DISABLE_COMPILE_CACHE = "1";
+  }
+  // Keep the benchmark on a single process so RSS reflects the actual command
+  // path rather than the warning-suppression respawn wrapper.
+  env.OPENCLAW_NO_RESPAWN = "1";
+  return env;
+}
+function runCaseSample(testCase, sampleIndex, params = {}) {
+  if (!benchEntryPath) {
+    throw new Error("bench entry path is not initialized");
+  }
+  if (!tmpHome) {
+    throw new Error("temporary home is not initialized");
+  }
+  const sampleHome = path.join(tmpHome, "homes", `${testCase.id}-${sampleIndex + 1}`);
+  mkdirSync(sampleHome, { recursive: true });
+  const env = buildBenchEnv(sampleHome);
+  const spawn = params.spawnSync ?? defaultSpawnSync;
+  const timeoutMs = params.timeoutMs ?? COMMAND_TIMEOUT_MS;
+  const result = spawn(process.execPath, [benchEntryPath, ...testCase.args.slice(1)], {
+    cwd: repoRoot,
+    env,
+    encoding: "utf8",
+    maxBuffer: 20 * 1024 * 1024,
+    timeout: timeoutMs,
+    killSignal: "SIGKILL",
+  });
+  const stderr = String(result.stderr ?? "");
+  const stdout = String(result.stdout ?? "");
+  const maxRssMb = parseMaxRssMb(stderr);
+  const matrixBootstrapWarning = /matrix: crypto runtime bootstrap failed/i.test(stderr);
+  const report = {
+    id: testCase.id,
+    label: testCase.label,
+    command: formatCaseCommand(testCase),
+    limitMb: testCase.limitMb,
+    rssToleranceMb: STARTUP_MEMORY_RSS_TOLERANCE_MB,
+    effectiveLimitMb: testCase.limitMb + STARTUP_MEMORY_RSS_TOLERANCE_MB,
+    maxRssMb,
+    status: PASS,
+    exitCode: result.status,
+    signal: result.signal ?? null,
+    error: null,
+  };
+  if (result.error) {
+    const timedOut = result.error.code === "ETIMEDOUT";
+    const error = timedOut
+      ? `${testCase.label} timed out after ${timeoutMs}ms`
+      : `${testCase.label} failed to start: ${result.error.message}`;
+    return failResult(report, testCase, error, stderr.trim() || stdout);
+  }
+  if (result.status !== 0) {
+    const exitDetail = result.status ?? result.signal ?? "unknown";
+    const error = `${testCase.label} exited with ${String(exitDetail)}`;
+    return failResult(report, testCase, error, stderr.trim() || stdout);
+  }
+  if (maxRssMb == null) {
+    const error = `${testCase.label} did not report max RSS`;
+    return failResult(report, testCase, error, stderr);
+  }
+  if (matrixBootstrapWarning) {
+    const error = `${testCase.label} triggered Matrix crypto bootstrap during startup`;
+    return failResult(report, testCase, error);
+  }
+  return report;
+}
+function median(values) {
+  const sorted = values.toSorted((left, right) => left - right);
+  const middle = sorted.at(Math.floor(sorted.length / 2));
+  if (middle === undefined) {
+    throw new Error("cannot compute median of an empty sample set");
+  }
+  return middle;
+}
+function formatRssSamples(samplesMb) {
+  return samplesMb.map((value) => value.toFixed(1)).join(", ");
+}
+function runCase(testCase, params = {}) {
+  let report = runCaseSample(testCase, 0, params);
+  if (report.status !== "pass" || report.maxRssMb == null) {
+    return report;
+  }
+  const samples = [report.maxRssMb];
+  // Shared CI runners occasionally produce a single allocator/RSS spike. Independent
+  // homes plus a median keep that outlier from masking regressions; two high samples fail.
+  for (let sampleIndex = 1; sampleIndex < STARTUP_MEMORY_SAMPLE_COUNT; sampleIndex += 1) {
+    const sample = runCaseSample(testCase, sampleIndex, params);
+    if (sample.status !== "pass" || sample.maxRssMb == null) {
+      return sample;
+    }
+    samples.push(sample.maxRssMb);
+    report = sample;
+  }
+  const maxRssMb = median(samples);
+  const result = { ...report, maxRssMb, rssSamplesMb: samples };
+  if (maxRssMb > result.effectiveLimitMb) {
+    const error = `${testCase.label} median max RSS ${maxRssMb.toFixed(1)} MB exceeded effective ceiling ${result.effectiveLimitMb} MB (base limit ${result.limitMb} MB; RSS tolerance ${result.rssToleranceMb} MB; samples: ${formatRssSamples(samples)} MB)`;
+    return failResult(result, testCase, error);
+  }
+  console.log(
+    `[startup-memory] ${testCase.label}: ${maxRssMb.toFixed(1)} MB median max RSS ` +
+      `(base limit ${result.limitMb} MB; RSS tolerance ${result.rssToleranceMb} MB; effective ceiling ${result.effectiveLimitMb} MB; samples ${formatRssSamples(samples)} MB)`,
+  );
+  return result;
+}
+function writeReport(reports, results) {
+  const failed = results.filter((result) => result.status !== "pass");
+  const report = {
+    generatedAt: new Date().toISOString(),
+    platform: process.platform,
+    repoRoot,
+    status: failed.length === 0 ? "pass" : "fail",
+    results: results.map(({ failureMessage: _failureMessage, ...result }) => result),
+  };
+  const lines = [
+    "# OpenClaw Startup Memory",
+    "",
+    `Generated: ${report.generatedAt}`,
+    "",
+    `Status: ${report.status}`,
+    "",
+    ...results.map((result) => {
+      const samples = result.rssSamplesMb
+        ? `; samples: ${result.rssSamplesMb.map(formatMb).join(", ")}`
+        : "";
+      return `- ${result.label}: ${result.status} median max RSS ${formatMb(result.maxRssMb)} (base limit ${formatMb(result.limitMb)}; RSS tolerance ${formatMb(result.rssToleranceMb)}; effective ceiling ${formatMb(result.effectiveLimitMb)}${samples})`;
+    }),
+    "",
+  ];
+  if (failed.length > 0) {
+    lines.push(
+      "## Failures",
+      "",
+      ...failed.map((result) => `- ${result.label}: ${result.error ?? "unknown failure"}`),
+      "",
+    );
+  }
+  for (const [reservation, contents] of [
+    [reports[0], `${JSON.stringify(report, null, 2)}\n`],
+    [reports[1], `${lines.join("\n")}\n`],
+  ]) {
+    assertReportReservation(reservation);
+    ftruncateSync(reservation.fd, 0);
+    writeFileSync(reservation.fd, contents, "utf8");
+    assertReportReservation(reservation);
+  }
+  reports.forEach(assertReportReservation);
+}
+function runStartupMemoryCheck(argv = process.argv.slice(2), params = {}) {
+  const platform = params.platform ?? process.platform;
+  if (platform !== "linux" && platform !== "darwin") {
+    console.log(`[startup-memory] Skipping on unsupported platform: ${platform}`);
+    return { skipped: true, results: [] };
+  }
+  const options = parseArgs(argv);
+  const reservation = reserveReports(options);
+  const results = [];
+  let operationError;
+  let published = false;
+  let outcome;
+  try {
+    tmpHome = mkdtempSync(path.join(os.tmpdir(), "openclaw-startup-memory-"));
+    benchEntryPath = path.join(tmpHome, "bench-entry.mjs");
+    // Run the real launcher in-process so peak RSS is self-reported at exit
+    // without --import/--require flags: the entry declines its dist ESM resolve
+    // fast path when preload hooks may be registered, so an injected hook would
+    // measure a slower non-default resolution configuration instead of what a
+    // plain `node openclaw.mjs ...` invocation pays.
+    const launcherPath = path.join(repoRoot, "openclaw.mjs");
+    writeFileSync(
+      benchEntryPath,
+      [
+        "process.on('exit', () => {",
+        "  const usage = typeof process.resourceUsage === 'function' ? process.resourceUsage() : null;",
+        `  if (usage && typeof usage.maxRSS === 'number') console.error('${MAX_RSS_MARKER}' + String(usage.maxRSS));`,
+        "});",
+        `const launcherPath = ${JSON.stringify(launcherPath)};`,
+        "// The launcher and entry expect argv[1] to be the launcher path itself.",
+        "process.argv[1] = launcherPath;",
+        `await import(${JSON.stringify(nodeImportSpecifierForPath(launcherPath))});`,
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    for (const testCase of cases) {
+      results.push(runCase(testCase, params));
+    }
+    writeReport(reservation.reports, results);
+    published = true;
+    const failure = results.find((result) => result.status !== "pass");
+    if (failure?.failureMessage) {
+      throw new Error(failure.failureMessage);
+    }
+    outcome = { skipped: false, results };
+  } catch (error) {
+    operationError = error;
+  }
+  let cleanupError;
+  try {
+    closeReports(reservation.reports);
+  } catch (error) {
+    cleanupError = error;
+  }
+  if (!published) {
+    cleanupReservation(reservation);
+  }
+  if (tmpHome) {
+    try {
+      rmSync(tmpHome, { recursive: true, force: true });
+    } catch (error) {
+      cleanupError ??= error;
+    } finally {
+      tmpHome = null;
+      benchEntryPath = null;
+    }
+  }
+  if (operationError !== undefined) {
+    throw operationError instanceof Error
+      ? operationError
+      : new Error("startup memory check failed", { cause: operationError });
+  }
+  if (cleanupError !== undefined) {
+    throw cleanupError instanceof Error
+      ? cleanupError
+      : new Error("startup memory cleanup failed", { cause: cleanupError });
+  }
+  return outcome;
+}
+/**
+ * Test-only access to pure startup memory helper functions.
+ */
+export const testing = {
+  cases,
+  parseArgs,
+  readPositiveIntEnv,
+  readPositiveNumberEnv,
+  repoRoot,
+  resolveDefaultLimitsMb,
+  runStartupMemoryCheck,
+  sampleCount: STARTUP_MEMORY_SAMPLE_COUNT,
+};
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    runStartupMemoryCheck();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

scripts/check-composite-action-input-interpolation.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+
+INPUT_INTERPOLATION_RE = re.compile(r"\$\{\{\s*inputs\.")
+RUN_LINE_RE = re.compile(r"^(\s*)run:\s*(.*)$")
+USING_COMPOSITE_RE = re.compile(r"^\s*using:\s*composite\s*$", re.MULTILINE)
+
+
+def indentation(line: str) -> int:
+    return len(line) - len(line.lstrip(" "))
+
+
+def scan_file(path: pathlib.Path) -> list[tuple[int, str]]:
+    text = path.read_text(encoding="utf-8")
+    if not USING_COMPOSITE_RE.search(text):
+        return []
+
+    lines = text.splitlines()
+    violations: list[tuple[int, str]] = []
+    line_count = len(lines)
+    index = 0
+
+    while index < line_count:
+        line = lines[index]
+        match = RUN_LINE_RE.match(line)
+        if not match:
+            index += 1
+            continue
+
+        run_indent = len(match.group(1))
+        run_value = match.group(2).strip()
+        line_no = index + 1
+
+        if run_value and run_value[0] not in ("|", ">"):
+            if INPUT_INTERPOLATION_RE.search(run_value):
+                violations.append((line_no, line.strip()))
+            index += 1
+            continue
+
+        index += 1
+        while index < line_count:
+            script_line = lines[index]
+            if script_line.strip() == "":
+                index += 1
+                continue
+            if indentation(script_line) <= run_indent:
+                break
+            if INPUT_INTERPOLATION_RE.search(script_line):
+                violations.append((index + 1, script_line.strip()))
+            index += 1
+
+    return violations
+
+
+def main() -> int:
+    root = pathlib.Path(".github/actions")
+    files = sorted(root.rglob("action.y*ml"))
+    all_violations: list[tuple[pathlib.Path, int, str]] = []
+
+    for file_path in files:
+        for line_no, line in scan_file(file_path):
+            all_violations.append((file_path, line_no, line))
+
+    if all_violations:
+        print("Disallowed direct inputs interpolation in composite run blocks:")
+        for file_path, line_no, line in all_violations:
+            print(f"- {file_path}:{line_no}: {line}")
+        print("Use env: and reference shell variables instead.")
+        return 1
+
+    print("No direct inputs interpolation found in composite run blocks.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/check-dependency-pins.mts

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+// Audits patched dependency pins for exact versions and drift.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { asRecord } from "@openclaw/normalization-core/record-coerce";
+import YAML from "yaml";
+import { classifyDependencySpec } from "./lib/dependency-spec-policy.mts";
+
+const PACKAGE_DEPENDENCY_SECTIONS = ["dependencies", "devDependencies", "optionalDependencies"];
+const WORKSPACE_DEPENDENCY_SECTIONS = ["overrides"];
+const DEFAULT_GIT_TIMEOUT_MS = 60_000;
+
+type DependencyPinViolation = {
+  file: string;
+  section: string;
+  name: string;
+  spec: unknown;
+};
+
+function runGit(cwd: string, args: string[], timeoutMs = DEFAULT_GIT_TIMEOUT_MS): string {
+  try {
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      // A synchronous child that ignores SIGTERM otherwise keeps its parent blocked.
+      killSignal: "SIGKILL",
+    });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ETIMEDOUT") {
+      throw new Error(
+        `dependency pin guard: git ${args.join(" ")} timed out after ${timeoutMs}ms.`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}
+
+function listTrackedPackageJsonFiles(cwd: string, timeoutMs = DEFAULT_GIT_TIMEOUT_MS): string[] {
+  return runGit(cwd, ["ls-files", "-z", "--", "*package.json"], timeoutMs)
+    .split("\0")
+    .filter(Boolean)
+    .toSorted((left, right) => left.localeCompare(right));
+}
+
+function readJson(filePath: string): Record<string, unknown> {
+  return asRecord(JSON.parse(fs.readFileSync(filePath, "utf8")) as unknown);
+}
+
+function readTrackedJson(
+  cwd: string,
+  relativePath: string,
+  timeoutMs = DEFAULT_GIT_TIMEOUT_MS,
+): Record<string, unknown> {
+  const filePath = path.join(cwd, relativePath);
+  if (fs.existsSync(filePath)) {
+    return readJson(filePath);
+  }
+  return asRecord(JSON.parse(runGit(cwd, ["show", `:${relativePath}`], timeoutMs)) as unknown);
+}
+
+function collectPackageJsonViolations(
+  cwd: string,
+  timeoutMs = DEFAULT_GIT_TIMEOUT_MS,
+): DependencyPinViolation[] {
+  const violations: DependencyPinViolation[] = [];
+  for (const relativePath of listTrackedPackageJsonFiles(cwd, timeoutMs)) {
+    const packageJson = readTrackedJson(cwd, relativePath, timeoutMs);
+    for (const section of PACKAGE_DEPENDENCY_SECTIONS) {
+      for (const [name, spec] of Object.entries(asRecord(packageJson[section]))) {
+        if (!classifyDependencySpec(spec).allowedPinned) {
+          violations.push({ file: relativePath, section, name, spec });
+        }
+      }
+    }
+  }
+  return violations;
+}
+
+function collectDependencyMapViolations(
+  file: string,
+  section: string,
+  dependencyMap: unknown,
+  violations: DependencyPinViolation[],
+): void {
+  for (const [name, spec] of Object.entries(asRecord(dependencyMap))) {
+    if (section === "overrides" && spec === "-") {
+      continue;
+    }
+    if (!classifyDependencySpec(spec).allowedPinned) {
+      violations.push({ file, section, name, spec });
+    }
+  }
+}
+
+function collectWorkspaceViolations(cwd: string): DependencyPinViolation[] {
+  const file = "pnpm-workspace.yaml";
+  const workspacePath = path.join(cwd, file);
+  if (!fs.existsSync(workspacePath)) {
+    return [];
+  }
+  const workspace = asRecord(YAML.parse(fs.readFileSync(workspacePath, "utf8")) as unknown);
+  const violations: DependencyPinViolation[] = [];
+  for (const section of WORKSPACE_DEPENDENCY_SECTIONS) {
+    collectDependencyMapViolations(file, section, workspace?.[section], violations);
+  }
+  for (const [packageName, extension] of Object.entries(asRecord(workspace.packageExtensions))) {
+    collectDependencyMapViolations(
+      file,
+      `packageExtensions.${packageName}.dependencies`,
+      asRecord(extension).dependencies,
+      violations,
+    );
+  }
+  return violations;
+}
+
+/**
+ * Collects dependency pin violations for the current workspace.
+ */
+export function collectDependencyPinViolations(
+  cwd = process.cwd(),
+  { gitTimeoutMs = DEFAULT_GIT_TIMEOUT_MS } = {},
+): DependencyPinViolation[] {
+  return [...collectPackageJsonViolations(cwd, gitTimeoutMs), ...collectWorkspaceViolations(cwd)];
+}
+
+/**
+ * Builds the full dependency pin audit payload.
+ */
+function collectDependencyPinAudit(cwd = process.cwd()) {
+  const packageJsonFiles = listTrackedPackageJsonFiles(cwd);
+  let packageSpecCount = 0;
+  for (const relativePath of packageJsonFiles) {
+    const packageJson = readTrackedJson(cwd, relativePath);
+    for (const section of PACKAGE_DEPENDENCY_SECTIONS) {
+      packageSpecCount += Object.keys(asRecord(packageJson[section])).length;
+    }
+  }
+  const workspaceViolations = collectWorkspaceViolations(cwd);
+  const violations = [...collectPackageJsonViolations(cwd), ...workspaceViolations];
+  return {
+    packageManifestCount: packageJsonFiles.length,
+    packageSpecCount,
+    violations,
+  };
+}
+
+/**
+ * Runs the dependency pin check.
+ */
+export async function main() {
+  const audit = collectDependencyPinAudit();
+  const { violations } = audit;
+  if (violations.length === 0) {
+    process.stdout.write(
+      `PASS direct dependency pin guard: checked ${audit.packageSpecCount} directly declared ` +
+        `dependency specs across ${audit.packageManifestCount} tracked package manifests; ` +
+        "0 violations.\n",
+    );
+    return;
+  }
+
+  console.error(
+    `FAIL direct dependency pin guard: ${violations.length} unpinned directly declared ` +
+      "dependency specs found. Direct dependency specs must be pinned exactly outside peer " +
+      "dependency contracts:",
+  );
+  for (const violation of violations) {
+    console.error(
+      `- ${violation.file}:${violation.section}:${violation.name} -> ${JSON.stringify(violation.spec)}`,
+    );
+  }
+  process.exitCode = 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error: unknown) => {
+    console.error(error);
+    process.exit(1);
+  });
+}

scripts/check-deprecated-jsdoc.mts

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Checks deprecated JSDoc blocks for required migration details.
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import type * as Ts from "typescript";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+
+const require = createRequire(import.meta.url);
+const ts: typeof import("typescript") = require("typescript");
+
+const repoRoot = resolveRepoRoot(import.meta.url);
+const SCAN_ROOTS = ["src", "extensions", "packages"];
+const SOURCE_FILE_RE = /\.(?:ts|tsx)$/;
+const SKIP_PATH_RE =
+  /(?:^|\/)(?:node_modules|dist|build|protocol-generated)(?:\/|$)|(?:\.test|\.spec|\.e2e|\.generated)\.tsx?$/;
+const DEPRECATED_SURFACE_COMMENT_RE =
+  /^(?:back-compat alias|backward-compatible alias(?:es)?|deprecated alias|legacy alias|legacy field|legacy:\s|kept for compatibility with existing imports|keep the legacy helper name exported)\b/i;
+
+function walk(dir: string, files: string[] = []) {
+  if (!fs.existsSync(dir)) {
+    return files;
+  }
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const filePath = path.join(dir, entry.name);
+    const relativePath = path.relative(repoRoot, filePath).replaceAll(path.sep, "/");
+    if (SKIP_PATH_RE.test(relativePath)) {
+      continue;
+    }
+    if (entry.isDirectory()) {
+      walk(filePath, files);
+    } else if (SOURCE_FILE_RE.test(entry.name)) {
+      files.push(filePath);
+    }
+  }
+  return files;
+}
+
+function leadingCommentText(sourceFile: Ts.SourceFile, node: Ts.Node) {
+  return (ts.getLeadingCommentRanges(sourceFile.text, node.pos) ?? [])
+    .map((range) => sourceFile.text.slice(range.pos, range.end))
+    .join("\n");
+}
+
+function normalizeCommentText(comment: string) {
+  return comment
+    .replace(/\/\*\*?/g, "")
+    .replace(/\*\//g, "")
+    .split("\n")
+    .map((line) => line.replace(/^\s*(?:\*|\/\/)\s?/, "").trim())
+    .filter(Boolean)
+    .join(" ");
+}
+
+function lineOf(sourceFile: Ts.SourceFile, node: Ts.Node) {
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}
+
+function isExported(node: Ts.Node) {
+  const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+  return (
+    modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) ||
+    node.parent?.kind === ts.SyntaxKind.SourceFile
+  );
+}
+
+type InspectedNode = Ts.Declaration | Ts.VariableStatement;
+type Violation = { filePath: string; line: number; name: string };
+
+function symbolName(node: InspectedNode) {
+  const declaration = ts.isVariableStatement(node) ? node.declarationList.declarations[0] : node;
+  return ts.getNameOfDeclaration(declaration)?.getText() ?? "<anonymous>";
+}
+
+function shouldInspectNode(node: Ts.Node): node is InspectedNode {
+  if (
+    ts.isFunctionDeclaration(node) ||
+    ts.isClassDeclaration(node) ||
+    ts.isInterfaceDeclaration(node) ||
+    ts.isTypeAliasDeclaration(node) ||
+    ts.isEnumDeclaration(node) ||
+    ts.isVariableStatement(node)
+  ) {
+    return isExported(node);
+  }
+  return (
+    ts.isPropertySignature(node) ||
+    ts.isMethodSignature(node) ||
+    ts.isPropertyDeclaration(node) ||
+    ts.isEnumMember(node)
+  );
+}
+
+function collectViolations(filePath: string) {
+  const sourceText = fs.readFileSync(filePath, "utf8");
+  const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true);
+  const violations: Violation[] = [];
+
+  function visit(node: Ts.Node) {
+    if (shouldInspectNode(node)) {
+      const comment = leadingCommentText(sourceFile, node);
+      const normalizedComment = normalizeCommentText(comment);
+      if (
+        normalizedComment &&
+        DEPRECATED_SURFACE_COMMENT_RE.test(normalizedComment) &&
+        !/@deprecated\b/.test(comment)
+      ) {
+        violations.push({
+          line: lineOf(sourceFile, node),
+          name: symbolName(node),
+          filePath: path.relative(repoRoot, filePath).replaceAll(path.sep, "/"),
+        });
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return violations;
+}
+
+const violations = SCAN_ROOTS.flatMap((root) =>
+  walk(path.join(repoRoot, root)).flatMap(collectViolations),
+);
+
+if (violations.length > 0) {
+  console.error("Deprecated JSDoc guard failed:");
+  for (const violation of violations) {
+    console.error(`- ${violation.filePath}:${violation.line} ${violation.name}`);
+  }
+  console.error(
+    "Add an @deprecated JSDoc tag or reword the comment if the symbol is not deprecated.",
+  );
+  process.exitCode = 1;
+} else {
+  console.log("deprecated JSDoc guard passed");
+}

scripts/check-docker-e2e-boundaries.mts

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// Cheap guard for Docker E2E test boundaries.
+// Docker E2E must test packaged npm tarballs and package-installed images, not
+// the source checkout copied or mounted as the app under test.
+import fs from "node:fs";
+import path from "node:path";
+import packageJson from "../package.json" with { type: "json" };
+import { laneResources, lanesNeedOpenClawPackage, laneWeight } from "./lib/docker-e2e-plan.mts";
+import {
+  allReleasePathLanes,
+  mainLanes,
+  publicInstallerLanes,
+  tailLanes,
+} from "./lib/docker-e2e-scenarios.mts";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+const ROOT_DIR = resolveRepoRoot(import.meta.url);
+const errors: string[] = [];
+const packageScripts = new Set(Object.keys(packageJson.scripts ?? {}));
+// These lanes prove package-installed surfaces against live auth, so they
+// intentionally need both live credentials and a package-backed image.
+const livePackageBackedLanes = new Set([
+  "install-e2e-anthropic",
+  "install-e2e-openai",
+  "live-anthropic-cache",
+  "live-codex-npm-plugin",
+  "live-mcp-code-mode-gateway",
+  "live-plugin-tool",
+  "npm-telegram-live",
+  "openai-chat-tools",
+  "openwebui",
+]);
+// These lanes intentionally build a focused source-checkout image instead of
+// consuming the shared package E2E images.
+const sourceCheckoutImageLanes = new Set([
+  "docker-selected-plugins",
+  "plugin-binding-command-escape",
+]);
+
+function readText(relativePath: string) {
+  return fs.readFileSync(path.join(ROOT_DIR, relativePath), "utf8");
+}
+
+function walk(dir: string, out: string[] = []) {
+  for (const entry of fs.readdirSync(path.join(ROOT_DIR, dir), { withFileTypes: true })) {
+    const relativePath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walk(relativePath, out);
+    } else {
+      out.push(relativePath);
+    }
+  }
+  return out;
+}
+
+function findRelativeModuleSpecifiers(text: string) {
+  const specifiers = new Set<string>();
+  for (const pattern of [
+    /(?:\bfrom\s*|\bimport\s*\()\s*["']([^"']+)["']/gu,
+    /\bimport\s*["']([^"']+)["']/gu,
+  ]) {
+    for (const match of text.matchAll(pattern)) {
+      const specifier = match[1];
+      if (specifier?.startsWith(".")) {
+        specifiers.add(specifier);
+      }
+    }
+  }
+  return [...specifiers];
+}
+
+function isPathWithin(parent: string, candidate: string) {
+  const relative = path.relative(parent, candidate);
+  return (
+    relative === "" ||
+    (!path.isAbsolute(relative) && !relative.startsWith(`..${path.sep}`) && relative !== "..")
+  );
+}
+
+for (const relativePath of walk("scripts/e2e")) {
+  if (!/\.(?:sh|ts|mts|mjs|js)$/u.test(relativePath)) {
+    continue;
+  }
+  const text = readText(relativePath);
+  const sourceImport = findRelativeModuleSpecifiers(text).find((specifier) => {
+    const resolved = path.resolve(ROOT_DIR, path.dirname(relativePath), specifier);
+    return isPathWithin(path.join(ROOT_DIR, "src"), resolved);
+  });
+  if (sourceImport) {
+    errors.push(
+      `${relativePath}: Docker E2E harness must import package exports, not ${sourceImport}`,
+    );
+  }
+  if (/-v\s+["']?\$ROOT_DIR:\/app(?::|["'\s]|$)/u.test(text)) {
+    errors.push(`${relativePath}: do not mount the repo root as /app in Docker E2E`);
+  }
+}
+
+const dockerfile = readText("scripts/e2e/Dockerfile");
+if (/^\s*(?:COPY|ADD)\s+\.\s+\/app(?:\s|$)/imu.test(dockerfile)) {
+  errors.push("scripts/e2e/Dockerfile: do not copy the source checkout into /app");
+}
+
+function validateUniqueLanes(label: string, lanes: readonly (typeof mainLanes)[number][]) {
+  const seen = new Set<string>();
+  for (const lane of lanes) {
+    if (seen.has(lane.name)) {
+      errors.push(`${label}: duplicate Docker E2E lane '${lane.name}'`);
+    }
+    seen.add(lane.name);
+  }
+}
+
+function validateLane(label: string, lane: (typeof mainLanes)[number]) {
+  const resources = laneResources(lane);
+  const sourceCheckoutImageLane = sourceCheckoutImageLanes.has(lane.name);
+  const needsPackage = lanesNeedOpenClawPackage([lane]);
+  const localImageBuild = sourceCheckoutImageLane || (needsPackage && !lane.e2eImageKind);
+  if (!lane.name || typeof lane.name !== "string") {
+    errors.push(`${label}: Docker E2E lane is missing a string name`);
+  }
+  if (!lane.command || typeof lane.command !== "string") {
+    errors.push(`${label}: Docker E2E lane '${lane.name}' is missing a string command`);
+    return;
+  }
+  if (lane.e2eImageKind && lane.e2eImageKind !== "bare" && lane.e2eImageKind !== "functional") {
+    const invalidImageKind =
+      typeof lane.e2eImageKind === "string"
+        ? lane.e2eImageKind
+        : (JSON.stringify(lane.e2eImageKind) ?? "<invalid>");
+    errors.push(
+      `${label}: Docker E2E lane '${lane.name}' has invalid image kind '${invalidImageKind}'`,
+    );
+  }
+  if (lane.live && needsPackage && !livePackageBackedLanes.has(lane.name)) {
+    errors.push(`${label}: live Docker E2E lane '${lane.name}' must not require a package image`);
+  }
+  if (!lane.live && !needsPackage && !sourceCheckoutImageLane) {
+    errors.push(
+      `${label}: package Docker E2E lane '${lane.name}' must request package preparation`,
+    );
+  }
+  if (localImageBuild && !/\bOPENCLAW_SKIP_DOCKER_BUILD=0\b/u.test(lane.command)) {
+    errors.push(
+      `${label}: locally built Docker E2E lane '${lane.name}' must force a local image build`,
+    );
+  }
+  if (laneWeight(lane) < 1) {
+    errors.push(`${label}: Docker E2E lane '${lane.name}' must have positive weight`);
+  }
+  if (!resources.includes("docker")) {
+    errors.push(`${label}: Docker E2E lane '${lane.name}' must include the docker resource`);
+  }
+
+  for (const match of lane.command.matchAll(/\bpnpm\s+([^\s]+)/gu)) {
+    const script = match[1];
+    if (script && !packageScripts.has(script)) {
+      errors.push(
+        `${label}: Docker E2E lane '${lane.name}' references missing package script '${script}'`,
+      );
+    }
+  }
+}
+
+const releasePathLanes = allReleasePathLanes({ includeOpenWebUI: true });
+for (const [label, lanes] of [
+  ["release-path", releasePathLanes],
+  ["public-installer", publicInstallerLanes],
+  ["main", mainLanes],
+  ["tail", tailLanes],
+] as const) {
+  validateUniqueLanes(label, lanes);
+  for (const lane of lanes) {
+    validateLane(label, lane);
+  }
+}
+
+if (errors.length > 0) {
+  console.error(errors.join("\n"));
+  process.exit(1);
+}
+
+console.log("Docker E2E package boundary/catalog guard passed.");

scripts/check-docs-config-examples.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runTsxCliShim } from "./lib/tsx-cli-shim.mjs";
+
+await runTsxCliShim(import.meta.url, {
+  implementation: "./check-docs-config-examples.mts",
+  failureTool: "check-docs-config-examples",
+});

scripts/check-docs-mdx.mts

@@ -0,0 +1,477 @@
+#!/usr/bin/env node
+
+// Validates docs MDX files for syntax and repository-specific conventions.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { compile } from "@mdx-js/mdx";
+import { requireOptionArgument } from "./lib/arg-utils.runtime.mjs";
+import {
+  checkMintlifyAccordionIndentation,
+  MINTLIFY_ACCORDION_INDENT_MESSAGE,
+} from "./lib/mintlify-accordion.mjs";
+
+type DocsCheckError = {
+  type: string;
+  file: string;
+  message: string;
+  line?: number;
+  column?: number;
+};
+
+function validationCache(cacheFile: string) {
+  const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+  const fingerprint = createHash("sha256").update(
+    JSON.stringify([process.version, process.platform, process.arch, process.execArgv]),
+  );
+  // The publish workflow installs with npm ci before invoking this opt-in cache.
+  // Include the installed lock as well as the requested lock; never infer a
+  // successful check from a source commit or translation's source_hash.
+  for (const input of [
+    fileURLToPath(import.meta.url),
+    fileURLToPath(new URL("./lib/arg-utils.runtime.mjs", import.meta.url)),
+    fileURLToPath(new URL("./lib/mintlify-accordion.mjs", import.meta.url)),
+    path.join(root, "package.json"),
+    path.join(root, "package-lock.json"),
+    path.join(root, "node_modules", ".package-lock.json"),
+  ]) {
+    fingerprint.update(fs.readFileSync(input)).update("\0");
+  }
+  const key = fingerprint.digest("hex");
+  let previous = new Map<string, string>();
+  try {
+    const saved = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+    if (
+      saved.key === key &&
+      saved.files &&
+      typeof saved.files === "object" &&
+      !Array.isArray(saved.files)
+    ) {
+      const entries: [string, string][] = [];
+      for (const [file, digest] of Object.entries(saved.files)) {
+        if (typeof digest !== "string" || !/^[a-f0-9]{64}$/.test(digest)) {
+          throw new Error("Invalid validation cache entry");
+        }
+        entries.push([file, digest]);
+      }
+      previous = new Map(entries);
+    }
+  } catch {
+    // Missing, obsolete, or corrupt disposable build artifacts are cold checks.
+  }
+  const checked = new Map<string, string>();
+  return {
+    root,
+    previous,
+    checked,
+    save() {
+      fs.mkdirSync(path.dirname(path.resolve(cacheFile)), { recursive: true });
+      const temporary = `${cacheFile}.${process.pid}.tmp`;
+      fs.writeFileSync(
+        temporary,
+        `${JSON.stringify({ key, files: Object.fromEntries(checked) })}\n`,
+      );
+      fs.renameSync(temporary, cacheFile);
+    },
+  };
+}
+
+const MINTLIFY_LANGUAGE_CODES = new Set([
+  "en",
+  "cn",
+  "zh",
+  "zh-Hans",
+  "zh-Hant",
+  "es",
+  "fr",
+  "fr-CA",
+  "fr-ca",
+  "ja",
+  "jp",
+  "ja-jp",
+  "pt",
+  "pt-BR",
+  "de",
+  "ko",
+  "it",
+  "ru",
+  "ro",
+  "cs",
+  "id",
+  "ar",
+  "tr",
+  "hi",
+  "sv",
+  "no",
+  "lv",
+  "nl",
+  "uk",
+  "vi",
+  "pl",
+  "uz",
+  "he",
+  "ca",
+  "fi",
+  "hu",
+]);
+
+const POISON_TEXT_PATTERNS = [
+  {
+    pattern: /\banalysis\s+to=functions\./iu,
+    message: "Leaked tool-call channel marker.",
+  },
+  {
+    pattern: /\b(?:commentary|final)\s+to=functions\./iu,
+    message: "Leaked tool-call channel marker.",
+  },
+  {
+    pattern: /\bfunctions\.(?:read|write|exec|search|run)\b/iu,
+    message: "Leaked internal tool name.",
+  },
+  {
+    pattern: /\b[A-Za-z_\u3400-\u9fff][\w\u3400-\u9fff-]*_input=\{/u,
+    message: "Leaked tool-call input payload.",
+  },
+  {
+    pattern: /<\/?openclaw_docs_i18n_input>/iu,
+    message: "Leaked docs i18n prompt wrapper.",
+  },
+  {
+    pattern: /\/home\/runner\/work\//u,
+    message: "Leaked GitHub Actions workspace path.",
+  },
+  {
+    pattern: /彩神马争霸/u,
+    message: "Known spam/gambling text from a poisoned translation.",
+  },
+];
+
+function parsePositiveIntegerArg(raw: string | undefined, label: string): number {
+  const text = raw?.trim() ?? "";
+  if (!/^\d+$/u.test(text)) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  const value = Number(text);
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return value;
+}
+
+/**
+ * Parses docs MDX check arguments.
+ */
+export function parseArgs(argv: string[]) {
+  const roots: string[] = [];
+  let jsonOut = "";
+  let maxErrors = 50;
+  let cacheFile = "";
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const part = argv[index];
+    if (part === undefined) {
+      continue;
+    }
+    if (part === "--json-out") {
+      jsonOut = requireOptionArgument(argv, index, "--json-out");
+      index += 1;
+      continue;
+    }
+    if (part === "--cache-file") {
+      cacheFile = requireOptionArgument(argv, index, "--cache-file");
+      index += 1;
+      continue;
+    }
+    if (part === "--max-errors") {
+      maxErrors = parsePositiveIntegerArg(
+        requireOptionArgument(argv, index, "--max-errors"),
+        "--max-errors",
+      );
+      index += 1;
+      continue;
+    }
+    if (part.startsWith("--")) {
+      throw new Error(`unknown arg: ${part}`);
+    }
+    roots.push(part);
+  }
+
+  return {
+    roots: roots.length ? roots : ["docs"],
+    jsonOut,
+    maxErrors,
+    ...(cacheFile ? { cacheFile } : {}),
+  };
+}
+
+function walkMarkdownFiles(entryPath: string, out: string[] = []): string[] {
+  const stat = fs.statSync(entryPath);
+  if (stat.isFile()) {
+    if (/\.mdx?$/i.test(entryPath)) {
+      out.push(path.resolve(entryPath));
+    }
+    return out;
+  }
+
+  for (const entry of fs.readdirSync(entryPath, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === ".git") {
+      continue;
+    }
+    walkMarkdownFiles(path.join(entryPath, entry.name), out);
+  }
+  return out;
+}
+
+function stripFrontmatter(raw: string): string {
+  if (!raw.startsWith("---\n") && !raw.startsWith("---\r\n")) {
+    return raw;
+  }
+
+  const lines = raw.split(/\r?\n/u);
+  for (let index = 1; index < lines.length; index += 1) {
+    if (lines[index] === "---" || lines[index] === "...") {
+      // Preserve source line numbers for both MDX and component diagnostics.
+      return lines.fill("", 0, index + 1).join("\n");
+    }
+  }
+  return raw;
+}
+
+function errorField(error: unknown, key: string): unknown {
+  return error && typeof error === "object" && key in error
+    ? error[key as keyof typeof error]
+    : undefined;
+}
+
+function formatMdxError(filePath: string, error: unknown): DocsCheckError {
+  const reason = errorField(error, "reason");
+  const message = errorField(error, "message");
+  const line = errorField(error, "line");
+  const column = errorField(error, "column");
+  return {
+    type: "mdx",
+    file: filePath,
+    ...(typeof line === "number" ? { line } : {}),
+    ...(typeof column === "number" ? { column } : {}),
+    message: String(reason ?? message ?? error).split("\n")[0] ?? "",
+  };
+}
+
+function checkMintlifyMdxStructure(filePath: string, raw: string): DocsCheckError[] {
+  return checkMintlifyAccordionIndentation(stripFrontmatter(raw)).map((error) => ({
+    type: "mintlify-mdx",
+    file: filePath,
+    line: error.line,
+    column: error.column,
+    message: MINTLIFY_ACCORDION_INDENT_MESSAGE,
+  }));
+}
+
+function lineColumnForIndex(raw: string, offset: number): { line: number; column: number } {
+  const prefix = raw.slice(0, offset);
+  const lines = prefix.split(/\r?\n/u);
+  return {
+    line: lines.length,
+    column: (lines.at(-1) ?? "").length + 1,
+  };
+}
+
+function checkPoisonText(filePath: string, raw: string): DocsCheckError[] {
+  const errors: DocsCheckError[] = [];
+  for (const { pattern, message } of POISON_TEXT_PATTERNS) {
+    const match = pattern.exec(raw);
+    if (!match) {
+      continue;
+    }
+    const location = lineColumnForIndex(raw, match.index);
+    errors.push({
+      type: "poison-text",
+      file: filePath,
+      line: location.line,
+      column: location.column,
+      message,
+    });
+  }
+  return errors;
+}
+
+async function checkMdxFile(filePath: string, raw: string): Promise<DocsCheckError[]> {
+  const poisonErrors = checkPoisonText(filePath, raw);
+  if (poisonErrors.length > 0) {
+    return poisonErrors;
+  }
+  const structureErrors = checkMintlifyMdxStructure(filePath, raw);
+  if (structureErrors.length > 0) {
+    return structureErrors;
+  }
+  await compile({ path: filePath, value: stripFrontmatter(raw) });
+  return [];
+}
+
+function findDocsJsonPaths(roots: string[]): string[] {
+  const paths = new Set<string>();
+  for (const root of roots) {
+    const absolute = path.resolve(root);
+    if (!fs.existsSync(absolute)) {
+      continue;
+    }
+    const stat = fs.statSync(absolute);
+    if (stat.isFile() && path.basename(absolute) === "docs.json") {
+      paths.add(absolute);
+      continue;
+    }
+    if (stat.isDirectory()) {
+      const docsJsonPath = path.join(absolute, "docs.json");
+      if (fs.existsSync(docsJsonPath)) {
+        paths.add(docsJsonPath);
+      }
+    }
+  }
+  return [...paths];
+}
+
+function collectNavigationLanguages(value: unknown, out: string[] = []): string[] {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectNavigationLanguages(item, out);
+    }
+    return out;
+  }
+  if (!value || typeof value !== "object") {
+    return out;
+  }
+  const record = value as Record<string, unknown>;
+  if (typeof record.language === "string") {
+    out.push(record.language);
+  }
+  for (const child of Object.values(record)) {
+    if (child && typeof child === "object") {
+      collectNavigationLanguages(child, out);
+    }
+  }
+  return out;
+}
+
+function checkDocsJson(filePath: string): DocsCheckError[] {
+  const errors: DocsCheckError[] = [];
+  let data: unknown;
+  try {
+    data = JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    return [
+      {
+        type: "docs-json",
+        file: filePath,
+        message: `Invalid JSON: ${String(errorField(error, "message") ?? error)}`,
+      },
+    ];
+  }
+
+  const navigation =
+    data && typeof data === "object" && "navigation" in data ? data.navigation : undefined;
+  const languages = collectNavigationLanguages(navigation);
+  for (const language of languages) {
+    if (!MINTLIFY_LANGUAGE_CODES.has(language)) {
+      errors.push({
+        type: "docs-json",
+        file: filePath,
+        message: `Unsupported Mintlify navigation language: ${language}`,
+      });
+    }
+  }
+  return errors;
+}
+
+function relativize(root: string, filePath: string): string {
+  const relative = path.relative(root, filePath);
+  return relative && !relative.startsWith("..") ? relative : filePath;
+}
+
+async function main(): Promise<void> {
+  const startedAt = Date.now();
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+  const roots = args.roots.map((root) => path.resolve(root));
+  const cache = args.cacheFile ? validationCache(args.cacheFile) : undefined;
+  let cacheHits = 0;
+  const files = [
+    ...new Set(
+      roots.flatMap((root) => {
+        if (!fs.existsSync(root)) {
+          throw new Error(`path does not exist: ${root}`);
+        }
+        return walkMarkdownFiles(root);
+      }),
+    ),
+  ].toSorted((left, right) => left.localeCompare(right));
+
+  const errors: DocsCheckError[] = [];
+  for (const docsJsonPath of findDocsJsonPaths(args.roots)) {
+    errors.push(...checkDocsJson(docsJsonPath));
+  }
+
+  for (const file of files) {
+    try {
+      const raw = fs.readFileSync(file);
+      const relative = cache ? path.relative(cache.root, file).split(path.sep).join("/") : "";
+      const cachePath =
+        relative && !relative.startsWith("../") && !path.isAbsolute(relative) ? relative : "";
+      const digest = cachePath ? createHash("sha256").update(raw).digest("hex") : "";
+      if (cachePath && cache?.previous.get(cachePath) === digest) {
+        cache.checked.set(cachePath, digest);
+        cacheHits += 1;
+        continue;
+      }
+      const pageErrors = await checkMdxFile(file, raw.toString("utf8"));
+      errors.push(...pageErrors);
+      if (cachePath && pageErrors.length === 0) {
+        cache?.checked.set(cachePath, digest);
+      }
+    } catch (error) {
+      errors.push(formatMdxError(file, error));
+      if (errors.length >= args.maxErrors) {
+        break;
+      }
+    }
+  }
+
+  const report = {
+    files: files.length,
+    errors: errors.map((error) => Object.assign({}, error, { file: relativize(cwd, error.file) })),
+    ms: Date.now() - startedAt,
+    ...(cache ? { cacheHits } : {}),
+  };
+
+  if (args.jsonOut) {
+    fs.mkdirSync(path.dirname(path.resolve(args.jsonOut)), { recursive: true });
+    fs.writeFileSync(args.jsonOut, `${JSON.stringify(report, null, 2)}\n`);
+  }
+
+  if (report.errors.length === 0) {
+    cache?.save();
+    console.log(`Docs MDX check passed (${report.files} files, ${report.ms}ms).`);
+    if (cache) {
+      console.log(`Reused ${cacheHits} unchanged successful page check(s).`);
+    }
+    return;
+  }
+
+  console.error(`Docs MDX check failed (${report.errors.length} error(s), ${report.files} files).`);
+  for (const error of report.errors) {
+    const location =
+      error.line && error.column ? `${error.file}:${error.line}:${error.column}` : error.file;
+    console.error(`- ${location}: ${error.message}`);
+  }
+  process.exitCode = 1;
+}
+
+const isMain = process.argv[1] ? fileURLToPath(import.meta.url) === process.argv[1] : false;
+
+if (isMain) {
+  main().catch((error: unknown) => {
+    console.error(errorField(error, "stack") ?? error);
+    process.exit(1);
+  });
+}

scripts/check-file-utils.ts

@@ -0,0 +1,131 @@
+// Check File Utils helper supports OpenClaw script workflows.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const DEFAULT_SKIPPED_DIR_NAMES = new Set(["node_modules", "dist", "coverage", ".generated"]);
+export const REPO_SCAN_ROOTS = ["src", "test", "extensions", "packages", "ui", "scripts"] as const;
+export const REPO_SCAN_SKIPPED_DIR_NAMES: ReadonlySet<string> = new Set([
+  ".artifacts",
+  ".generated",
+  "coverage",
+  "dist",
+  "fixtures",
+  "node_modules",
+  "vendor",
+]);
+// Bound the Git lookup before falling back to direct filesystem traversal.
+const GIT_LS_FILES_TIMEOUT_MS = 30_000;
+const GIT_LS_FILES_MAX_BUFFER = 64 * 1024 * 1024;
+
+export function isCodeFile(filePath: string): boolean {
+  if (filePath.endsWith(".d.ts")) {
+    return false;
+  }
+  return /\.(?:[cm]?ts|[cm]?js|tsx|jsx)$/u.test(filePath);
+}
+
+export function isTestRelatedFile(relativePath: string): boolean {
+  return (
+    /(?:^|[/.])(?:test|spec)\.[cm]?[jt]sx?$/u.test(relativePath) ||
+    /\.(?:e2e|live)\.test\.[cm]?[jt]sx?$/u.test(relativePath) ||
+    /\.(?:test-helpers|test-utils|test-harness|test-support)\.[cm]?[jt]sx?$/u.test(relativePath) ||
+    /-(?:test-helpers|test-utils|test-harness|test-support)\.[cm]?[jt]sx?$/u.test(relativePath) ||
+    /(?:^|\/)(?:test|tests|test-helpers|test-utils|test-harness|test-support)\//u.test(
+      relativePath,
+    ) ||
+    relativePath.startsWith("scripts/e2e/") ||
+    /^scripts\/.*-(?:client|e2e|harness|probe|smoke)\.[cm]?[jt]s$/u.test(relativePath)
+  );
+}
+
+export function collectFilesSync(
+  rootDir: string,
+  options: {
+    includeFile: (filePath: string) => boolean;
+    skipDirNames?: ReadonlySet<string>;
+  },
+): string[] {
+  const skipDirNames = options.skipDirNames ?? DEFAULT_SKIPPED_DIR_NAMES;
+  const files: string[] = [];
+  const stack = [rootDir];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (skipDirNames.has(entry.name)) {
+          continue;
+        }
+        stack.push(fullPath);
+        continue;
+      }
+      if (entry.isFile() && options.includeFile(fullPath)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+export function listRepoFilesSync(
+  repoRoot: string,
+  options: {
+    includeFile: (relativePath: string) => boolean;
+    roots?: readonly string[];
+    skipDirNames?: ReadonlySet<string>;
+  },
+): string[] {
+  const roots = options.roots ?? REPO_SCAN_ROOTS;
+  try {
+    return execFileSync("git", ["-C", repoRoot, "ls-files", "--", ...roots], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: GIT_LS_FILES_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+      maxBuffer: GIT_LS_FILES_MAX_BUFFER,
+    })
+      .split(/\r?\n/u)
+      .filter(Boolean)
+      .map(toPosixPath)
+      .filter(options.includeFile)
+      .toSorted((left, right) => left.localeCompare(right));
+  } catch {
+    return roots
+      .flatMap((root) => {
+        const absoluteRoot = path.join(repoRoot, root);
+        if (!fs.existsSync(absoluteRoot)) {
+          return [];
+        }
+        return collectFilesSync(absoluteRoot, {
+          includeFile: (filePath) =>
+            options.includeFile(toPosixPath(path.relative(repoRoot, filePath))),
+          skipDirNames: options.skipDirNames ?? REPO_SCAN_SKIPPED_DIR_NAMES,
+        }).map((filePath) => toPosixPath(path.relative(repoRoot, filePath)));
+      })
+      .toSorted((left, right) => left.localeCompare(right));
+  }
+}
+
+export function toPosixPath(filePath: string): string {
+  if (path.sep === "/") {
+    return filePath;
+  }
+  return filePath.replaceAll("\\", "/");
+}
+
+export function relativeToCwd(filePath: string): string {
+  const relativePath = path.relative(process.cwd(), filePath) || filePath;
+  return toPosixPath(relativePath);
+}

scripts/check-import-cycles.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Check Import Cycles script supports OpenClaw repository automation.
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import {
+  collectSourceFiles,
+  collectStronglyConnectedComponents,
+  formatCycle,
+} from "./lib/import-cycle-graph.ts";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const scanRoots = ["src", "extensions", "scripts"] as const;
+const sourceExtensions = [".ts", ".tsx", ".mts", ".cts", ".js", ".mjs", ".cjs"] as const;
+const testSourcePattern = /(?:\.test|\.e2e\.test)\.[cm]?[tj]sx?$/;
+const generatedSourcePattern = /\.(?:generated|bundle)\.[tj]s$/;
+const declarationSourcePattern = /\.d\.[cm]?ts$/;
+const ignoredPathPartPattern =
+  /(^|\/)(node_modules|dist|build|coverage|\.artifacts|\.git|assets)(\/|$)/;
+
+function shouldSkipRepoPath(repoPath: string): boolean {
+  return (
+    ignoredPathPartPattern.test(repoPath) ||
+    testSourcePattern.test(repoPath) ||
+    generatedSourcePattern.test(repoPath) ||
+    declarationSourcePattern.test(repoPath)
+  );
+}
+
+function createSourceResolver(files: readonly string[]) {
+  const fileSet = new Set(files);
+  const pathMap = new Map<string, string>();
+  for (const file of files) {
+    const parsed = path.posix.parse(file);
+    const extensionless = path.posix.join(parsed.dir, parsed.name);
+    pathMap.set(extensionless, file);
+    if (file.endsWith(".ts")) {
+      pathMap.set(`${extensionless}.js`, file);
+    } else if (file.endsWith(".tsx")) {
+      pathMap.set(`${extensionless}.jsx`, file);
+    } else if (file.endsWith(".mts")) {
+      pathMap.set(`${extensionless}.mjs`, file);
+    } else if (file.endsWith(".cts")) {
+      pathMap.set(`${extensionless}.cjs`, file);
+    }
+  }
+  return (importer: string, specifier: string): string | null => {
+    if (!specifier.startsWith(".")) {
+      return null;
+    }
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(importer), specifier));
+    if (fileSet.has(base)) {
+      return base;
+    }
+    const mappedBase = pathMap.get(base);
+    if (mappedBase) {
+      return mappedBase;
+    }
+    const candidates = [
+      ...sourceExtensions.map((extension) => `${base}${extension}`),
+      `${base}/index.ts`,
+      `${base}/index.tsx`,
+      `${base}/index.js`,
+      `${base}/index.mjs`,
+    ];
+    for (const candidate of candidates) {
+      if (fileSet.has(candidate)) {
+        return candidate;
+      }
+      const mapped = pathMap.get(candidate);
+      if (mapped) {
+        return mapped;
+      }
+    }
+    return null;
+  };
+}
+
+function importDeclarationHasRuntimeEdge(node: ts.ImportDeclaration): boolean {
+  if (!node.importClause) {
+    return true;
+  }
+  if (node.importClause.isTypeOnly) {
+    return false;
+  }
+  const bindings = node.importClause.namedBindings;
+  if (node.importClause.name || !bindings || ts.isNamespaceImport(bindings)) {
+    return true;
+  }
+  return bindings.elements.some((element) => !element.isTypeOnly);
+}
+
+function exportDeclarationHasRuntimeEdge(node: ts.ExportDeclaration): boolean {
+  if (!node.moduleSpecifier || node.isTypeOnly) {
+    return false;
+  }
+  const clause = node.exportClause;
+  if (!clause || ts.isNamespaceExport(clause)) {
+    return true;
+  }
+  return clause.elements.some((element) => !element.isTypeOnly);
+}
+
+function collectRuntimeStaticImports(
+  file: string,
+  resolveSource: ReturnType<typeof createSourceResolver>,
+) {
+  const sourceFile = ts.createSourceFile(
+    file,
+    readFileSync(path.join(repoRoot, file), "utf8"),
+    ts.ScriptTarget.Latest,
+    false,
+  );
+  const imports: string[] = [];
+  const visit = (node: ts.Node) => {
+    let specifier: string | undefined;
+    let include = false;
+    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+      specifier = node.moduleSpecifier.text;
+      include = importDeclarationHasRuntimeEdge(node);
+    } else if (
+      ts.isExportDeclaration(node) &&
+      node.moduleSpecifier &&
+      ts.isStringLiteral(node.moduleSpecifier)
+    ) {
+      specifier = node.moduleSpecifier.text;
+      include = exportDeclarationHasRuntimeEdge(node);
+    }
+    if (include && specifier) {
+      const resolved = resolveSource(file, specifier);
+      if (resolved) {
+        imports.push(resolved);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return imports.toSorted((left, right) => left.localeCompare(right));
+}
+
+function main(): number {
+  const files = scanRoots.flatMap((root) =>
+    collectSourceFiles(path.join(repoRoot, root), {
+      repoRoot,
+      sourceExtensions,
+      shouldSkipRepoPath,
+    }),
+  );
+  const resolveSource = createSourceResolver(files);
+  const graph = new Map(
+    files.map((file): [string, string[]] => [
+      file,
+      collectRuntimeStaticImports(file, resolveSource),
+    ]),
+  );
+  const components = collectStronglyConnectedComponents(graph);
+
+  console.log(`Import cycle check: ${components.length} runtime value cycle(s).`);
+  if (components.length === 0) {
+    return 0;
+  }
+
+  console.error("\nRuntime value import cycles:");
+  for (const component of components) {
+    console.error(`\n# component size ${component.length}`);
+    console.error(formatCycle(component, graph));
+  }
+  console.error("\nBreak the cycle or convert type-only edges to `import type`.");
+  return 1;
+}
+
+process.exitCode = main();

scripts/check-kysely-guardrails.mts

@@ -0,0 +1,539 @@
+#!/usr/bin/env node
+
+// Enforces Kysely and SQLite guardrails in infrastructure code.
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import type { Expression, ImportDeclaration, Node, SourceFile } from "typescript";
+import { resolveRepoRoot } from "./lib/repo-root.mjs";
+import {
+  collectTypeScriptFilesFromRoots,
+  getPropertyNameText,
+  runAsScript,
+  toLine,
+  unwrapExpression,
+} from "./lib/ts-guard-utils.mts";
+
+const require = createRequire(import.meta.url);
+const ts: typeof import("typescript") = require("typescript");
+
+const repoRoot = resolveRepoRoot(import.meta.url);
+const sourceRoots = [path.join(repoRoot, "src")];
+const nodeSqliteBoundaryRoots = [
+  path.join(repoRoot, "src"),
+  path.join(repoRoot, "extensions"),
+  path.join(repoRoot, "packages"),
+];
+
+const nodeSqliteConstructorOwnerPaths = new Set([
+  "src/infra/node-sqlite.ts",
+  "src/infra/sqlite-runtime-version.ts",
+]);
+
+const kyselyRawAllowPaths = new Set(["src/infra/kysely-sync.ts"]);
+
+const compiledRawAllowPaths = new Set(["src/infra/kysely-node-sqlite.ts"]);
+
+const rawSqliteAllowPathGroups = {
+  "native Kysely adapter and sync execution": [
+    "src/infra/kysely-node-sqlite.ts",
+    "src/infra/kysely-sync-cache-state.ts",
+    "src/infra/kysely-sync.ts",
+  ],
+  "SQLite database lifecycle, schema, transactions, and pragmas": [
+    "src/infra/node-sqlite.ts",
+    "src/infra/sqlite-index-schema.ts",
+    "src/infra/sqlite-integrity.ts",
+    "src/infra/sqlite-pragma.test-support.ts",
+    "src/infra/sqlite-schema-contract.ts",
+    "src/infra/sqlite-strict.ts",
+    "src/infra/sqlite-transaction.ts",
+    "src/infra/sqlite-user-version.ts",
+    "src/infra/sqlite-wal.ts",
+    "src/state/openclaw-agent-db-maintenance.ts",
+    "src/state/openclaw-agent-db-registry.ts",
+    "src/state/openclaw-agent-db-registry-listing.ts",
+    "src/state/openclaw-agent-db-schema-helpers.ts",
+    // Existing schema ownership/version preflight, split from schema-helpers for readers.
+    "src/state/openclaw-agent-db-schema-read.ts",
+    "src/state/openclaw-agent-db-metadata.ts",
+    "src/state/openclaw-agent-db-schema.ts",
+    "src/state/openclaw-agent-db-session-nodes-migration.ts",
+    "src/state/openclaw-agent-db-session-migrations.ts",
+    "src/state/openclaw-agent-db-session-provenance.ts",
+    "src/state/openclaw-agent-db.ts",
+    "src/state/openclaw-state-db-audit-migration.ts",
+    "src/state/openclaw-state-db-delivery-queue-backfill.ts",
+    "src/state/openclaw-state-db-legacy-backfills.ts",
+    "src/state/openclaw-state-db-maintenance.ts",
+    "src/state/openclaw-state-db-operator-approval-migration.ts",
+    "src/state/openclaw-state-db-schema-additive.ts",
+    "src/state/openclaw-state-db-schema-helpers.ts",
+    "src/state/openclaw-state-db-schema-repair.ts",
+    "src/state/openclaw-state-db-schema-v12-foldin.ts",
+    "src/state/openclaw-state-db-schema-v13-widerow.ts",
+    "src/state/openclaw-state-db-startup-checkpoint.ts",
+    "src/state/openclaw-state-db-table-retirements.ts",
+    "src/state/openclaw-state-db-fast-path.ts",
+    "src/state/openclaw-state-db.ts",
+    "src/state/openclaw-state-ownership-operations.ts",
+    "src/transcripts/sqlite-schema.ts",
+    "src/state/sqlite-schema-shape.test-support.ts",
+  ],
+  "cross-process SQLite coordination locks": ["src/infra/sqlite-coordinator.ts"],
+  "backup snapshot maintenance": [
+    "src/commands/backup-verify.ts",
+    "src/infra/backup-create.ts",
+    "src/snapshot/git-backup-codec.ts",
+    "src/snapshot/local-repository.ts",
+  ],
+  "agent auth profile read-only bootstrap": ["src/agents/auth-profiles/sqlite.ts"],
+  "read-only shared state database access": [
+    "src/claws/package-resume.ts",
+    "src/state/openclaw-agent-db-readonly.ts",
+    "src/state/openclaw-state-db-readonly.ts",
+  ],
+  "cold-process read-only relay lookup avoids the shared state writer lifecycle": [
+    "src/agents/harness/native-hook-relay-client.worker.ts",
+  ],
+  "read-only schema preflight and integrity verification access": [
+    "src/state/openclaw-database-preflight.ts",
+    "src/state/openclaw-database-verify.worker.ts",
+    "src/state/openclaw-state-ownership.ts",
+  ],
+  "quarantine store must work when other databases are damaged": [
+    "src/state/openclaw-quarantine-store.ts",
+  ],
+  "read-only SQLite status probes": [
+    "src/commands/doctor-db-bloat.ts",
+    "src/commands/status.scan.shared.ts",
+  ],
+  "doctor SQLite maintenance and legacy state migration": [
+    "src/commands/doctor-agent-memory-schema.ts",
+    "src/commands/doctor/cron/legacy-run-log-migration.ts",
+    "src/commands/doctor/cron/migration-ledger.ts",
+    "src/commands/doctor-sqlite-compact.ts",
+    "src/commands/doctor-session-sqlite.ts",
+    "src/commands/doctor-session-sqlite-readers.ts",
+    "src/commands/doctor-session-sqlite-transcript-readers.ts",
+    "src/commands/doctor-session-sqlite-recover-report.ts",
+    "src/commands/doctor-state-sqlite-compact.ts",
+    // Disposable import planning only; canonical session tables still use Kysely.
+    "src/config/sessions/session-accessor.sqlite-import-stage.ts",
+    "src/infra/state-migrations.task-sidecar-rows.ts",
+    "src/infra/state-migrations.storage.ts",
+    "src/infra/state-migrations.cron-run-logs.ts",
+    "src/infra/state-migrations.debug-proxy.ts",
+    "src/infra/state-migrations.meeting-transcripts-detection.ts",
+    "src/infra/state-migrations.meeting-transcripts-files.ts",
+    "src/infra/state-migrations.meeting-transcripts-verify.ts",
+    "src/infra/state-migrations.media-persistence.ts",
+    "src/infra/state-migrations.transcript-directives-archives.ts",
+    "src/infra/state-migrations.transcript-directives.ts",
+    // Doctor integrity PRAGMAs and lossless native 64-bit orphan-row preservation.
+    "src/state/openclaw-state-db-task-delivery-recovery.ts",
+  ],
+  "session entry cache connection-local validity counters": [
+    "src/config/sessions/session-accessor.sqlite-entry-cache.ts",
+  ],
+  "device pairing cache connection-local validity counters": ["src/infra/device-pairing-store.ts"],
+  "Kysely-backed stores that own a DatabaseSync boundary": [
+    "src/acp/event-ledger.ts",
+    "src/state/user-profiles.ts",
+    "src/cron/store.ts",
+    "src/infra/outbound/current-conversation-bindings.ts",
+    "src/media/store.ts",
+    "src/plugin-sdk/memory-core-host-engine-storage.ts",
+    "src/plugins/installed-plugin-index-record-reader.ts",
+    "src/plugins/installed-plugin-index-store-write.ts",
+    "src/plugin-state/plugin-state-store.sqlite.ts",
+    "src/proxy-capture/store.sqlite.ts",
+    "src/tasks/task-flow-registry.store.sqlite.ts",
+    "src/tasks/task-registry.store.kernel.ts",
+  ],
+};
+
+type GuardViolation = { line: number; message: string };
+
+const rawSqliteAllowPathReasons = new Map<string, string>();
+for (const [reason, paths] of Object.entries(rawSqliteAllowPathGroups)) {
+  for (const allowedPath of paths) {
+    if (rawSqliteAllowPathReasons.has(allowedPath)) {
+      throw new Error(`Duplicate raw SQLite allowlist path: ${allowedPath}`);
+    }
+    rawSqliteAllowPathReasons.set(allowedPath, reason);
+  }
+}
+
+function lineText(sourceFile: SourceFile, node: Node) {
+  const line = toLine(sourceFile, node);
+  return sourceFile.text.split("\n")[line - 1] ?? "";
+}
+
+function hasAllowComment(sourceFile: SourceFile, node: Node, token: string) {
+  const line = lineText(sourceFile, node);
+  if (line.includes(token)) {
+    return true;
+  }
+  const leading = ts.getLeadingCommentRanges(sourceFile.text, node.pos) ?? [];
+  return leading.some((range) => sourceFile.text.slice(range.pos, range.end).includes(token));
+}
+
+function importSource(node: ImportDeclaration) {
+  const moduleSpecifier = node.moduleSpecifier;
+  return ts.isStringLiteral(moduleSpecifier) ? moduleSpecifier.text : "";
+}
+
+function collectImports(sourceFile: SourceFile) {
+  const kyselySqlNames = new Set<string>();
+  const compiledQueryNames = new Set<string>();
+  const syncHelperNames = new Set<string>();
+  let hasKyselyContext = false;
+  let hasSqliteContext = false;
+
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) {
+      continue;
+    }
+    const source = importSource(statement);
+    const clause = statement.importClause;
+    const namedBindings = clause?.namedBindings;
+
+    if (source === "kysely") {
+      hasKyselyContext = true;
+      if (namedBindings && ts.isNamedImports(namedBindings)) {
+        for (const element of namedBindings.elements) {
+          const importedName = element.propertyName?.text ?? element.name.text;
+          if (importedName === "sql") {
+            kyselySqlNames.add(element.name.text);
+          }
+          if (importedName === "CompiledQuery") {
+            compiledQueryNames.add(element.name.text);
+          }
+        }
+      }
+    }
+
+    if (source.endsWith("kysely-sync.js") || source.endsWith("kysely-node-sqlite.js")) {
+      hasKyselyContext = true;
+      if (namedBindings && ts.isNamedImports(namedBindings)) {
+        for (const element of namedBindings.elements) {
+          const importedName = element.propertyName?.text ?? element.name.text;
+          if (
+            importedName === "executeSqliteQuerySync" ||
+            importedName === "executeSqliteQueryTakeFirstSync"
+          ) {
+            syncHelperNames.add(element.name.text);
+          }
+          if (importedName === "getNodeSqliteKysely") {
+            hasKyselyContext = true;
+            hasSqliteContext = true;
+          }
+        }
+      }
+    }
+
+    if (
+      source === "node:sqlite" ||
+      source.endsWith("node-sqlite.js") ||
+      source.endsWith("sqlite-transaction.js") ||
+      source.endsWith("sqlite-wal.js") ||
+      source.endsWith("openclaw-state-db.js")
+    ) {
+      hasSqliteContext = true;
+    }
+  }
+
+  return {
+    compiledQueryNames,
+    hasKyselyContext,
+    hasSqliteContext,
+    kyselySqlNames,
+    syncHelperNames,
+  };
+}
+
+function addViolation(
+  violations: GuardViolation[],
+  sourceFile: SourceFile,
+  node: Node,
+  message: string,
+) {
+  violations.push({
+    line: toLine(sourceFile, node),
+    message,
+  });
+}
+
+function isIdentifierNamed(node: Expression, names: Set<string>) {
+  const unwrapped = unwrapExpression(node);
+  return ts.isIdentifier(unwrapped) && names.has(unwrapped.text);
+}
+
+function isTestPath(relativePath: string) {
+  return (
+    /\.(?:test|spec|e2e)\.ts$/u.test(relativePath) ||
+    relativePath.includes(".test-helpers.") ||
+    relativePath.includes(".test-support.")
+  );
+}
+
+function isSqliteStorePath(relativePath: string) {
+  return relativePath.endsWith(".sqlite.ts") || relativePath.includes(".store.sqlite.ts");
+}
+
+function collectNodeSqliteBoundaryViolations(content: string, relativePath: string) {
+  if (isTestPath(relativePath) || nodeSqliteConstructorOwnerPaths.has(relativePath)) {
+    return [];
+  }
+  const sourceFile = ts.createSourceFile(relativePath, content, ts.ScriptTarget.Latest, true);
+  const constructorNames = new Set<string>();
+
+  function collectConstructorNames(node: Node) {
+    if (ts.isImportDeclaration(node) && importSource(node) === "node:sqlite") {
+      const namedBindings = node.importClause?.namedBindings;
+      if (namedBindings && ts.isNamedImports(namedBindings)) {
+        for (const element of namedBindings.elements) {
+          if ((element.propertyName?.text ?? element.name.text) === "DatabaseSync") {
+            constructorNames.add(element.name.text);
+          }
+        }
+      }
+    }
+    if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name)) {
+      for (const element of node.name.elements) {
+        if (
+          !element.dotDotDotToken &&
+          ts.isIdentifier(element.name) &&
+          (element.propertyName ? getPropertyNameText(element.propertyName) : element.name.text) ===
+            "DatabaseSync"
+        ) {
+          constructorNames.add(element.name.text);
+        }
+      }
+    }
+    ts.forEachChild(node, collectConstructorNames);
+  }
+
+  collectConstructorNames(sourceFile);
+  const violations: GuardViolation[] = [];
+  function visit(node: Node) {
+    if (ts.isNewExpression(node)) {
+      const expression = unwrapExpression(node.expression);
+      const isRawConstructor =
+        (ts.isIdentifier(expression) && constructorNames.has(expression.text)) ||
+        (ts.isPropertyAccessExpression(expression) &&
+          getPropertyNameText(expression.name) === "DatabaseSync");
+      if (isRawConstructor) {
+        addViolation(
+          violations,
+          sourceFile,
+          node,
+          "production node:sqlite connections must use openNodeSqliteDatabase",
+        );
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return violations;
+}
+
+function isLikelySqliteReceiver(expression: Expression) {
+  const unwrapped = unwrapExpression(expression);
+  if (ts.isIdentifier(unwrapped)) {
+    return /^(?:db|database|legacyDb|stateDb|agentDb)$/u.test(unwrapped.text);
+  }
+  return ts.isPropertyAccessExpression(unwrapped) && getPropertyNameText(unwrapped.name) === "db";
+}
+
+function isPersistedRowExpression(expression: Expression) {
+  const unwrapped = unwrapExpression(expression);
+  if (ts.isPropertyAccessExpression(unwrapped)) {
+    const owner = unwrapExpression(unwrapped.expression);
+    return ts.isIdentifier(owner) && /^(?:row|record|entry)$/u.test(owner.text);
+  }
+  if (ts.isElementAccessExpression(unwrapped)) {
+    const owner = unwrapExpression(unwrapped.expression);
+    return ts.isIdentifier(owner) && /^(?:row|record|entry)$/u.test(owner.text);
+  }
+  return false;
+}
+
+function isPersistedStringCastType(typeText: string) {
+  return [
+    /\bTaskRecord\["(?:runtime|scopeKind|status|deliveryStatus|notifyPolicy|terminalOutcome)"\]/u,
+    /\bTaskFlowRecord\["(?:status|notifyPolicy)"\]/u,
+    /\bTaskFlowSyncMode\b/u,
+    /\bVirtualAgentFsEntryKind\b/u,
+    /\b[A-Z][A-Za-z0-9]*(?:Status|Kind|Mode|Policy|Runtime|Outcome)\b/u,
+  ].some((pattern) => pattern.test(typeText));
+}
+
+/**
+ * Collects Kysely/raw SQLite violations from one source file.
+ */
+function collectKyselyGuardrailViolations(content: string, relativePath: string) {
+  const sourceFile = ts.createSourceFile(relativePath, content, ts.ScriptTarget.Latest, true);
+  const imports = collectImports(sourceFile);
+  const violations: GuardViolation[] = [];
+
+  function visit(node: Node) {
+    if (
+      isSqliteStorePath(relativePath) &&
+      (ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)) &&
+      isPersistedStringCastType(node.type.getText(sourceFile)) &&
+      isPersistedRowExpression(node.expression) &&
+      !hasAllowComment(sourceFile, node, "sqlite-allow-persisted-cast")
+    ) {
+      addViolation(
+        violations,
+        sourceFile,
+        node,
+        "persisted SQLite enum-like values must be parsed through closed validators, not cast",
+      );
+    }
+
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      imports.syncHelperNames.has(node.expression.text) &&
+      node.typeArguments?.length &&
+      !hasAllowComment(sourceFile, node, "kysely-allow-raw")
+    ) {
+      addViolation(
+        violations,
+        sourceFile,
+        node,
+        "sync helper row generic at call site; let Kysely infer builder result rows",
+      );
+    }
+
+    if (
+      ts.isTaggedTemplateExpression(node) &&
+      node.typeArguments?.length &&
+      isIdentifierNamed(node.tag, imports.kyselySqlNames) &&
+      !kyselyRawAllowPaths.has(relativePath) &&
+      !hasAllowComment(sourceFile, node, "kysely-allow-raw")
+    ) {
+      addViolation(
+        violations,
+        sourceFile,
+        node,
+        "typed raw sql snippet needs a small helper or allowlisted boundary",
+      );
+    }
+
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      isIdentifierNamed(node.expression.expression, imports.kyselySqlNames) &&
+      ["ref", "table", "id", "raw"].includes(getPropertyNameText(node.expression.name) ?? "") &&
+      !hasAllowComment(sourceFile, node, "kysely-allow-raw")
+    ) {
+      addViolation(
+        violations,
+        sourceFile,
+        node,
+        "raw Kysely identifier helper requires a closed-set validator and local allow comment",
+      );
+    }
+
+    if (
+      imports.hasKyselyContext &&
+      ts.isPropertyAccessExpression(node) &&
+      getPropertyNameText(node.name) === "dynamic" &&
+      !hasAllowComment(sourceFile, node, "kysely-allow-raw")
+    ) {
+      addViolation(
+        violations,
+        sourceFile,
+        node,
+        "Kysely dynamic refs bypass literal reference checking; use only behind closed unions",
+      );
+    }
+
+    if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      isIdentifierNamed(node.expression.expression, imports.compiledQueryNames) &&
+      getPropertyNameText(node.expression.name) === "raw" &&
+      !compiledRawAllowPaths.has(relativePath) &&
+      !hasAllowComment(sourceFile, node, "kysely-allow-raw")
+    ) {
+      addViolation(
+        violations,
+        sourceFile,
+        node,
+        "CompiledQuery.raw is only allowed in the native SQLite dialect/test boundary",
+      );
+    }
+
+    if (
+      imports.hasSqliteContext &&
+      !isTestPath(relativePath) &&
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      ["prepare", "exec"].includes(getPropertyNameText(node.expression.name) ?? "") &&
+      isLikelySqliteReceiver(node.expression.expression) &&
+      !rawSqliteAllowPathReasons.has(relativePath) &&
+      !hasAllowComment(sourceFile, node, "sqlite-allow-raw")
+    ) {
+      addViolation(
+        violations,
+        sourceFile,
+        node,
+        "new raw node:sqlite access requires Kysely or an explicit raw SQLite allowlist entry",
+      );
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return violations;
+}
+
+/**
+ * Collects Kysely guardrail violations across configured source roots.
+ */
+async function collectKyselyGuardrails() {
+  const files = await collectTypeScriptFilesFromRoots(sourceRoots, { includeTests: true });
+  const violations: Array<GuardViolation & { path: string }> = [];
+  for (const filePath of files) {
+    const relativePath = path.relative(repoRoot, filePath).split(path.sep).join("/");
+    const content = await fs.readFile(filePath, "utf8");
+    for (const violation of collectKyselyGuardrailViolations(content, relativePath)) {
+      violations.push({ path: relativePath, ...violation });
+    }
+  }
+  const nodeSqliteFiles = await collectTypeScriptFilesFromRoots(nodeSqliteBoundaryRoots, {
+    includeTests: false,
+  });
+  for (const filePath of nodeSqliteFiles) {
+    const relativePath = path.relative(repoRoot, filePath).split(path.sep).join("/");
+    const content = await fs.readFile(filePath, "utf8");
+    for (const violation of collectNodeSqliteBoundaryViolations(content, relativePath)) {
+      violations.push({ path: relativePath, ...violation });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Runs the Kysely guardrail check.
+ */
+async function main() {
+  const violations = await collectKyselyGuardrails();
+  if (violations.length === 0) {
+    console.log("Kysely guardrails OK");
+    return;
+  }
+  console.error("Kysely guardrail violations:");
+  for (const violation of violations) {
+    console.error(`- ${violation.path}:${violation.line}: ${violation.message}`);
+  }
+  process.exit(1);
+}
+
+runAsScript(import.meta.url, main);

scripts/check-live-cache.ts

@@ -0,0 +1,27 @@
+// Check Live Cache script supports OpenClaw repository automation.
+
+import { LIVE_CACHE_TEST_ENABLED, logLiveCache } from "../src/agents/live-cache-test-support.js";
+import { runLiveCacheRegression } from "../src/agents/test-helpers/live-cache-regression-runner.js";
+
+if (!LIVE_CACHE_TEST_ENABLED) {
+  logLiveCache("skipped; set OPENCLAW_LIVE_TEST=1 and OPENCLAW_LIVE_CACHE_TEST=1");
+  process.exit(0);
+}
+
+const result = await runLiveCacheRegression();
+if (result.warnings.length > 0) {
+  process.stderr.write("\n[live-cache] non-blocking cache observations:\n");
+  for (const warning of result.warnings) {
+    process.stderr.write(`- ${warning}\n`);
+  }
+}
+if (result.regressions.length > 0) {
+  process.stderr.write("\n[live-cache] regressions detected:\n");
+  for (const regression of result.regressions) {
+    process.stderr.write(`- ${regression}\n`);
+  }
+  process.exit(1);
+} else {
+  process.stderr.write("\n[live-cache] all regression floors satisfied\n");
+  process.exit(0);
+}

scripts/check-media-download-helper-roundtrip.mts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Checks extension media downloads keep helper-read/save calls close together.
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+
+const WINDOW_LINES = 80;
+const READ_HELPER_RE = /\b(?:readRemoteMediaBuffer|fetchRemoteMedia)\s*\(/;
+const SAVE_BUFFER_RE = /(?:\.|\b)saveMediaBuffer\s*\(/;
+
+function listTrackedExtensionSources() {
+  return execFileSync("git", ["ls-files", "extensions/**/*.ts"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  })
+    .split("\n")
+    .filter(Boolean)
+    .filter((file) => file.includes("/src/"))
+    .filter((file) => existsSync(file))
+    .filter((file) => !isTestOrFixture(file));
+}
+
+function isTestOrFixture(file: string) {
+  return (
+    file.endsWith(".test.ts") ||
+    file.endsWith(".e2e.test.ts") ||
+    file.endsWith(".test-harness.ts") ||
+    file.endsWith(".test-utils.ts") ||
+    file.endsWith("/test-runtime.ts") ||
+    file.endsWith("/test-helpers.ts") ||
+    file.includes("/test-support/") ||
+    file.includes("/fixtures/")
+  );
+}
+
+const findings: Array<{ file: string; line: number; saveLine: number }> = [];
+
+for (const file of listTrackedExtensionSources()) {
+  const lines = readFileSync(file, "utf8").split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!READ_HELPER_RE.test(lines[index] ?? "")) {
+      continue;
+    }
+    const end = Math.min(lines.length, index + WINDOW_LINES);
+    for (let nextIndex = index; nextIndex < end; nextIndex += 1) {
+      if (!SAVE_BUFFER_RE.test(lines[nextIndex] ?? "")) {
+        continue;
+      }
+      findings.push({
+        file,
+        line: index + 1,
+        saveLine: nextIndex + 1,
+      });
+      break;
+    }
+  }
+}
+
+if (findings.length > 0) {
+  console.error("Avoid remote-media buffer/store round trips in plugin production code.");
+  console.error(
+    "Use saveRemoteMedia(...) for URL-to-store or saveResponseMedia(...) for fetched Response objects.",
+  );
+  for (const finding of findings) {
+    console.error(`- ${finding.file}:${finding.line} -> saveMediaBuffer at ${finding.saveLine}`);
+  }
+  process.exitCode = 1;
+}

scripts/check-memory-fd-repro.mjs

@@ -0,0 +1,5 @@
+import { runTsxCliShim } from "./lib/tsx-cli-shim.mjs";
+
+await runTsxCliShim(import.meta.url, {
+  implementation: "./check-memory-fd-repro.mts",
+});

scripts/check-native-state-schema-version.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { isDirectRunUrl } from "./lib/direct-run.mjs";
+
+const SWIFT_CONTRACT_PATH =
+  "apps/shared/OpenClawKit/Sources/OpenClawNativeState/OpenClawNativeStateSQLite.swift";
+const TYPESCRIPT_CONTRACT_PATH = "src/state/openclaw-state-db-contract.ts";
+
+function extractSingleVersion(source, pattern, label) {
+  const matches = [...source.matchAll(pattern)];
+  if (matches.length !== 1) {
+    throw new Error(`Expected exactly one ${label} declaration; found ${matches.length}`);
+  }
+  return Number(matches[0][1]);
+}
+
+export function compareNativeStateSchemaVersions({ swiftSource, typescriptSource }) {
+  const swiftVersion = extractSingleVersion(
+    swiftSource,
+    /^\s*private static let maximumSupportedSchemaVersion: Int64 = (\d+)\s*$/gmu,
+    "Swift maximumSupportedSchemaVersion",
+  );
+  const typescriptVersion = extractSingleVersion(
+    typescriptSource,
+    /^export const OPENCLAW_STATE_SCHEMA_VERSION = (\d+);\s*$/gmu,
+    "TypeScript OPENCLAW_STATE_SCHEMA_VERSION",
+  );
+  if (swiftVersion !== typescriptVersion) {
+    throw new Error(
+      `Native state schema version drift: Swift supports ${swiftVersion}, TypeScript owns ${typescriptVersion}`,
+    );
+  }
+  return swiftVersion;
+}
+
+export function checkNativeStateSchemaVersion(readFileSync = fs.readFileSync) {
+  return compareNativeStateSchemaVersions({
+    swiftSource: readFileSync(SWIFT_CONTRACT_PATH, "utf8"),
+    typescriptSource: readFileSync(TYPESCRIPT_CONTRACT_PATH, "utf8"),
+  });
+}
+
+if (isDirectRunUrl(process.argv[1], import.meta.url)) {
+  try {
+    const version = checkNativeStateSchemaVersion();
+    console.log(`native state schema version guard passed (v${version})`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

scripts/check-no-conflict-markers.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+// Rejects unresolved merge conflict markers in tracked files.
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CONFLICT_MARKER_GREP_PATTERN = "^(<<<<<<< |\\|\\|\\|\\|\\|\\|\\| |=======$|>>>>>>> )";
+
+/**
+ * Parses output from `git grep -n -z -o -I -E` into violation records.
+ * The record format is:
+ *   path\0line-number\0match-text\n
+ * The path must be read from its NUL delimiter before any newline-based
+ * record splitting: -z reports paths verbatim, and git allows newlines in
+ * tracked filenames, so splitting the output on newlines first would cut a
+ * newline-containing path across two records and silently mangle it.
+ * Keeping parsing to exact grep match records avoids reading candidate files
+ * whole and keeps memory bounded regardless of file size.
+ */
+function parseGitGrepConflictMarkerOutput(stdout) {
+  const byPath = new Map();
+  const output = stdout.toString("utf8");
+  let cursor = 0;
+
+  while (cursor < output.length) {
+    const pathEnd = output.indexOf("\0", cursor);
+    if (pathEnd === -1) {
+      break;
+    }
+    const lineNumberEnd = output.indexOf("\0", pathEnd + 1);
+    if (lineNumberEnd === -1) {
+      break;
+    }
+    // With -o the match text is a single-line match, so the record ends at
+    // the next newline after the line-number field.
+    const matchEnd = output.indexOf("\n", lineNumberEnd + 1);
+    const relativePath = output.slice(cursor, pathEnd);
+    const lineNumber = Number(output.slice(pathEnd + 1, lineNumberEnd));
+    cursor = matchEnd === -1 ? output.length : matchEnd + 1;
+    if (!relativePath || !Number.isFinite(lineNumber) || lineNumber <= 0) {
+      continue;
+    }
+    const existing = byPath.get(relativePath);
+    if (existing) {
+      existing.push(lineNumber);
+    } else {
+      byPath.set(relativePath, [lineNumber]);
+    }
+  }
+
+  const violations = [];
+  for (const [relativePath, lineNumbers] of byPath) {
+    lineNumbers.sort((a, b) => a - b);
+    violations.push({
+      filePath: relativePath,
+      lines: lineNumbers,
+    });
+  }
+  violations.sort((a, b) => a.filePath.localeCompare(b.filePath));
+  return violations;
+}
+
+/**
+ * Uses git grep to find exact conflict-marker matches in tracked files.
+ */
+export function findConflictMarkersInTrackedFiles(cwd = process.cwd()) {
+  const result = spawnSync(
+    "git",
+    ["grep", "--no-color", "-n", "-z", "-o", "-I", "-E", CONFLICT_MARKER_GREP_PATTERN, "--", "."],
+    {
+      cwd,
+      encoding: "buffer",
+    },
+  );
+  if (result.status === 1) {
+    return [];
+  }
+  if (result.status !== 0) {
+    const stderr = result.stderr?.toString("utf8").trim();
+    throw new Error(stderr || `git grep failed with status ${result.status ?? "unknown"}`);
+  }
+  return parseGitGrepConflictMarkerOutput(result.stdout);
+}
+
+/**
+ * Runs the merge conflict marker check.
+ */
+export async function main() {
+  const cwd = process.cwd();
+  const violations = findConflictMarkersInTrackedFiles(cwd);
+  if (violations.length === 0) {
+    return;
+  }
+
+  console.error("Found unresolved merge conflict markers:");
+  for (const violation of violations) {
+    // findConflictMarkersInTrackedFiles already returns paths relative to cwd.
+    console.error(`- ${violation.filePath}:${violation.lines.join(",")}`);
+  }
+  process.exitCode = 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(
+    /** @param {unknown} error */ (error) => {
+      console.error(error);
+      process.exit(1);
+    },
+  );
+}

scripts/check-no-deprecated-channel-access.ts

@@ -0,0 +1,115 @@
+// Check No Deprecated Channel Access script supports OpenClaw repository automation.
+import fs from "node:fs";
+import path from "node:path";
+import { collectFilesSync, isCodeFile, relativeToCwd } from "./check-file-utils.js";
+import { classifyBundledExtensionSourcePath } from "./lib/extension-source-classifier.mts";
+
+type Rule = {
+  label: string;
+  pattern: RegExp;
+};
+
+const RULES: Rule[] = [
+  {
+    label: "deprecated channel runtime",
+    pattern:
+      /\.channel\.(?:reply\.(?:createReplyDispatcherWithTyping|resolveHumanDelayConfig|dispatchReplyFromConfig|finalizeInboundContext|formatInboundEnvelope)|session\.(?:resolveStorePath|recordInboundSession)|inbound\.(?:runPreparedReply|dispatchReply)|media\.fetchRemoteMedia)\b/u,
+  },
+  {
+    label: "caller-owned prepared channel dispatch",
+    pattern: /\b(?:runDispatch|onPreDispatchFailure)\b/u,
+  },
+  {
+    label: "caller-owned reply dispatcher lifecycle",
+    pattern:
+      /\b(?:createReplyDispatcherWithTyping|dispatchInboundMessage(?:WithBufferedDispatcher|WithDispatcher)?|settleReplyDispatcher)\s*\(/u,
+  },
+  {
+    label: "deprecated channel ingress resolver aliases",
+    pattern:
+      /\b(?:resolved|result|directResolved|groupResolved)\.(?:legacyAccess|senderReasonCode|commandAuthorized|shouldBlockControlCommand)\b/u,
+  },
+  {
+    label: "inline deprecated channel ingress legacyAccess projection",
+    pattern: /\)\.legacyAccess\b/u,
+  },
+  {
+    label: "deprecated pairing-store access helper",
+    pattern: /\breadStoreAllowFromForDmPolicy\b/u,
+  },
+  {
+    label: "deprecated DM/group access helper",
+    pattern: /\bresolveDmGroupAccessWith(?:Lists|CommandGate)\b/u,
+  },
+  {
+    label: "deprecated DM/group access reason constants",
+    pattern: /\bDM_GROUP_ACCESS_REASON\b/u,
+  },
+  {
+    label: "deprecated group policy access helper",
+    pattern:
+      /\b(?:resolveSenderScopedGroupPolicy|evaluateSenderGroupAccess(?:ForPolicy)?|evaluateGroupRouteAccessForPolicy|evaluateMatchedGroupAccessForPolicy)\b/u,
+  },
+  {
+    label: "deprecated group access compatibility module",
+    pattern: /from\s+["']openclaw\/plugin-sdk\/group-access["']/u,
+  },
+  {
+    label: "deprecated command authorization helper",
+    pattern: /\bresolveSenderCommandAuthorization(?:WithRuntime)?\b/u,
+  },
+  {
+    label: "deprecated command auth SDK facade",
+    pattern: /from\s+["']openclaw\/plugin-sdk\/command-auth["']/u,
+  },
+];
+
+function collectBundledPluginProductionFiles(): string[] {
+  const extensionsDir = path.join(process.cwd(), "extensions");
+  return collectFilesSync(extensionsDir, {
+    includeFile(filePath) {
+      if (!isCodeFile(filePath)) {
+        return false;
+      }
+      const repoPath = relativeToCwd(filePath);
+      const classified = classifyBundledExtensionSourcePath(repoPath);
+      return classified.isProductionSource;
+    },
+  }).toSorted((left, right) => relativeToCwd(left).localeCompare(relativeToCwd(right)));
+}
+
+function main() {
+  const offenders: Array<{ file: string; line: number; label: string; text: string }> = [];
+  for (const file of collectBundledPluginProductionFiles()) {
+    const content = fs.readFileSync(file, "utf8");
+    const lines = content.split(/\r?\n/u);
+    for (const [index, line] of lines.entries()) {
+      for (const rule of RULES) {
+        if (rule.pattern.test(line)) {
+          offenders.push({
+            file: relativeToCwd(file),
+            line: index + 1,
+            label: rule.label,
+            text: line.trim(),
+          });
+        }
+      }
+    }
+  }
+
+  if (offenders.length > 0) {
+    console.error(
+      "Bundled plugin production code must use modern channel runtime and access seams.",
+    );
+    for (const offender of offenders) {
+      console.error(`- ${offender.file}:${offender.line}: ${offender.label}: ${offender.text}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(
+    "OK: bundled plugin production code avoids deprecated channel runtime and access seams.",
+  );
+}
+
+main();

scripts/check-no-monolithic-plugin-sdk-entry-imports.ts

@@ -0,0 +1,111 @@
+// Check No Monolithic Plugin Sdk Entry Imports script supports OpenClaw repository automation.
+import fs from "node:fs";
+import path from "node:path";
+import { discoverOpenClawPlugins } from "../src/plugins/discovery.js";
+import { collectFilesSync, isCodeFile, relativeToCwd } from "./check-file-utils.js";
+
+const LEGACY_BROAD_SUBPATH_PATTERNS = [
+  {
+    pattern: /["']openclaw\/plugin-sdk\/config-runtime["']/,
+    label: "openclaw/plugin-sdk/config-runtime",
+  },
+  {
+    pattern: /["']openclaw\/plugin-sdk\/infra-runtime["']/,
+    label: "openclaw/plugin-sdk/infra-runtime",
+  },
+] as const;
+
+function findLegacyBroadSubpathImports(content: string): string[] {
+  return LEGACY_BROAD_SUBPATH_PATTERNS.filter(({ pattern }) => pattern.test(content)).map(
+    ({ label }) => label,
+  );
+}
+
+function collectPluginSourceFiles(rootDir: string): string[] {
+  const srcDir = path.join(rootDir, "src");
+  if (!fs.existsSync(srcDir)) {
+    return [];
+  }
+  return collectFilesSync(srcDir, {
+    includeFile: (filePath) => isCodeFile(filePath),
+    skipDirNames: new Set(["node_modules", "dist", ".git", "coverage"]),
+  });
+}
+
+function collectSharedExtensionSourceFiles(): string[] {
+  return collectPluginSourceFiles(path.join(process.cwd(), "extensions", "shared"));
+}
+
+function collectBundledExtensionSourceFiles(): string[] {
+  const extensionsDir = path.join(process.cwd(), "extensions");
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(extensionsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const files: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === "shared") {
+      continue;
+    }
+    for (const srcFile of collectPluginSourceFiles(path.join(extensionsDir, entry.name))) {
+      files.push(srcFile);
+    }
+  }
+  return files;
+}
+
+function main() {
+  const discovery = discoverOpenClawPlugins({});
+  const bundledCandidates = discovery.candidates.filter((c) => c.origin === "bundled");
+  const filesToCheck = new Set<string>();
+  for (const candidate of bundledCandidates) {
+    filesToCheck.add(candidate.source);
+    for (const srcFile of collectPluginSourceFiles(candidate.rootDir)) {
+      filesToCheck.add(srcFile);
+    }
+  }
+  for (const sharedFile of collectSharedExtensionSourceFiles()) {
+    filesToCheck.add(sharedFile);
+  }
+  for (const extensionFile of collectBundledExtensionSourceFiles()) {
+    filesToCheck.add(extensionFile);
+  }
+
+  const legacyBroadSubpathOffenders = new Map<string, string[]>();
+  for (const entryFile of filesToCheck) {
+    let content;
+    try {
+      content = fs.readFileSync(entryFile, "utf8");
+    } catch {
+      continue;
+    }
+    const legacyBroadSubpaths = findLegacyBroadSubpathImports(content);
+    if (legacyBroadSubpaths.length > 0) {
+      legacyBroadSubpathOffenders.set(entryFile, legacyBroadSubpaths);
+    }
+  }
+
+  if (legacyBroadSubpathOffenders.size > 0) {
+    if (legacyBroadSubpathOffenders.size > 0) {
+      console.error(
+        "Bundled plugin source files must not import deprecated broad plugin-sdk subpaths.",
+      );
+      for (const [file, labels] of [...legacyBroadSubpathOffenders.entries()].toSorted(
+        ([left], [right]) => left.localeCompare(right),
+      )) {
+        console.error(`- ${relativeToCwd(file)} (${labels.join(", ")})`);
+      }
+    }
+    console.error("Use focused openclaw/plugin-sdk/<domain> subpaths for bundled plugins.");
+    process.exit(1);
+  }
+
+  console.log(
+    `OK: bundled plugin source files avoid deprecated broad plugin-sdk subpaths (${filesToCheck.size} checked).`,
+  );
+}
+
+main();

scripts/check-package-patches.mts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+// Guards pnpm package patches against unapproved additions.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { asRecord } from "@openclaw/normalization-core/record-coerce";
+import YAML from "yaml";
+import { pnpmLockfileDocuments } from "./lib/pnpm-lockfile-documents.mjs";
+
+const ALLOWED_PATCHED_DEPENDENCIES = new Map([
+  ["@awesome.me/webawesome@3.12.0", "patches/@awesome.me__webawesome@3.12.0.patch"],
+  ["@novnc/novnc@1.7.0", "patches/@novnc__novnc@1.7.0.patch"],
+  ["vitest@5.0.0", "patches/vitest@5.0.0.patch"],
+  ["baileys@7.0.0-rc12", "patches/baileys@7.0.0-rc12.patch"],
+  ["baileys@7.0.0-rc13", "patches/baileys@7.0.0-rc13.patch"],
+  ["matrix-js-sdk@42.3.0", "patches/matrix-js-sdk@42.3.0.patch"],
+]);
+
+const ALLOWED_PATCH_FILES = new Set(["patches/.gitkeep", ...ALLOWED_PATCHED_DEPENDENCIES.values()]);
+
+type PackagePatchViolation = { file: string; kind: string; detail: string };
+
+function listTrackedFiles(cwd: string, patterns: string[]) {
+  return execFileSync("git", ["ls-files", "-z", "--", ...patterns], {
+    cwd,
+    encoding: "utf8",
+  })
+    .split("\0")
+    .filter(Boolean)
+    .toSorted((left, right) => left.localeCompare(right));
+}
+
+function readRecordFile(cwd: string, relativePath: string, parse: (source: string) => unknown) {
+  const filePath = path.join(cwd, relativePath);
+  if (!fs.existsSync(filePath)) {
+    return {};
+  }
+  return asRecord(parse(fs.readFileSync(filePath, "utf8")));
+}
+
+function collectPatchedDependencyViolations(
+  file: string,
+  patchedDependencies: unknown,
+  violations: PackagePatchViolation[],
+  options: { allowAnyValueForLegacy?: boolean } = {},
+) {
+  for (const [specifier, patchPathOrHash] of Object.entries(asRecord(patchedDependencies))) {
+    if (
+      options.allowAnyValueForLegacy === true
+        ? ALLOWED_PATCHED_DEPENDENCIES.has(specifier)
+        : ALLOWED_PATCHED_DEPENDENCIES.get(specifier) === patchPathOrHash
+    ) {
+      continue;
+    }
+    violations.push({
+      file,
+      kind: "patchedDependency",
+      detail: `${specifier} -> ${String(patchPathOrHash)}`,
+    });
+  }
+}
+
+function collectWorkspacePatchViolations(cwd: string, violations: PackagePatchViolation[]) {
+  const workspace = readRecordFile(cwd, "pnpm-workspace.yaml", YAML.parse);
+  collectPatchedDependencyViolations(
+    "pnpm-workspace.yaml",
+    workspace.patchedDependencies,
+    violations,
+  );
+}
+
+function collectLockfilePatchViolations(cwd: string, violations: PackagePatchViolation[]) {
+  const filePath = path.join(cwd, "pnpm-lock.yaml");
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  for (const document of Object.values(pnpmLockfileDocuments(fs.readFileSync(filePath, "utf8")))) {
+    if (document === null) {
+      continue;
+    }
+    const lockfile = asRecord(YAML.parse(document));
+    collectPatchedDependencyViolations("pnpm-lock.yaml", lockfile.patchedDependencies, violations, {
+      allowAnyValueForLegacy: true,
+    });
+  }
+}
+
+function collectPackageJsonPatchViolations(cwd: string, violations: PackagePatchViolation[]) {
+  for (const relativePath of listTrackedFiles(cwd, ["*package.json"])) {
+    const packageJson = readRecordFile(cwd, relativePath, JSON.parse);
+    const patchedDependencies = asRecord(asRecord(packageJson.pnpm).patchedDependencies);
+    for (const [specifier, patchPath] of Object.entries(patchedDependencies)) {
+      violations.push({
+        file: relativePath,
+        kind: "packageJsonPatchedDependency",
+        detail: `${specifier} -> ${String(patchPath)}`,
+      });
+    }
+  }
+}
+
+function collectPatchFileViolations(cwd: string, violations: PackagePatchViolation[]) {
+  for (const relativePath of listTrackedFiles(cwd, ["*.patch"])) {
+    if (!fs.existsSync(path.join(cwd, relativePath))) {
+      continue;
+    }
+    if (ALLOWED_PATCH_FILES.has(relativePath)) {
+      continue;
+    }
+    violations.push({
+      file: relativePath,
+      kind: "patchFile",
+      detail: "new package patch file",
+    });
+  }
+}
+
+/**
+ * Collects disallowed package patch declarations and patch files.
+ */
+export function collectPackagePatchViolations(cwd = process.cwd()) {
+  const violations: PackagePatchViolation[] = [];
+  collectWorkspacePatchViolations(cwd, violations);
+  collectLockfilePatchViolations(cwd, violations);
+  collectPackageJsonPatchViolations(cwd, violations);
+  collectPatchFileViolations(cwd, violations);
+  return violations;
+}
+
+/**
+ * Runs the package patch guard.
+ */
+export async function main() {
+  const violations = collectPackagePatchViolations();
+  if (violations.length === 0) {
+    process.stdout.write(
+      `PASS package patch guard: no new pnpm patches; ${ALLOWED_PATCHED_DEPENDENCIES.size} approved patches allowlisted.\n`,
+    );
+    return;
+  }
+
+  console.error(
+    "FAIL package patch guard: new pnpm package patches are not allowed. Upstream the fix, publish a new package version, then bump the dependency instead.",
+  );
+  for (const violation of violations) {
+    console.error(`- ${violation.file}: ${violation.kind}: ${violation.detail}`);
+  }
+  process.exitCode = 1;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((error: unknown) => {
+    console.error(error);
+    process.exit(1);
+  });
+}

scripts/check-pairing-account-scope.mts

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+// Checks pairing config logic for account-scoped allowlist handling.
+import ts from "typescript";
+import { createPairingGuardContext } from "./lib/pairing-guard-context.mts";
+import {
+  collectFileViolations,
+  getPropertyNameText,
+  runAsScript,
+  toLine,
+} from "./lib/ts-guard-utils.mts";
+
+const { repoRoot, sourceRoots } = createPairingGuardContext(import.meta.url);
+
+function isUndefinedLikeExpression(node: ts.Node) {
+  if (ts.isIdentifier(node) && node.text === "undefined") {
+    return true;
+  }
+  return node.kind === ts.SyntaxKind.NullKeyword;
+}
+
+function hasRequiredAccountIdProperty(node: ts.Node) {
+  if (!ts.isObjectLiteralExpression(node)) {
+    return false;
+  }
+  for (const property of node.properties) {
+    if (ts.isShorthandPropertyAssignment(property) && property.name.text === "accountId") {
+      return true;
+    }
+    if (!ts.isPropertyAssignment(property)) {
+      continue;
+    }
+    if (getPropertyNameText(property.name) !== "accountId") {
+      continue;
+    }
+    if (isUndefinedLikeExpression(property.initializer)) {
+      return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+function findViolations(content: string, filePath: string) {
+  const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+  const violations: { line: number; reason: string }[] = [];
+
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+      const callName = node.expression.text;
+      if (callName === "readChannelAllowFromStore") {
+        const accountIdArgument = node.arguments[2];
+        if (!accountIdArgument || isUndefinedLikeExpression(accountIdArgument)) {
+          violations.push({
+            line: toLine(sourceFile, node),
+            reason: "readChannelAllowFromStore call must pass explicit accountId as 3rd arg",
+          });
+        }
+      } else if (callName === "upsertChannelPairingRequest") {
+        const firstArg = node.arguments[0];
+        if (!firstArg || !hasRequiredAccountIdProperty(firstArg)) {
+          violations.push({
+            line: toLine(sourceFile, node),
+            reason: "upsertChannelPairingRequest call must include accountId in params",
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return violations;
+}
+
+async function main() {
+  const violations = await collectFileViolations({
+    sourceRoots,
+    repoRoot,
+    findViolations,
+  });
+
+  if (violations.length === 0) {
+    return;
+  }
+
+  console.error("Found unscoped pairing-store calls:");
+  for (const violation of violations) {
+    console.error(`- ${violation.path}:${violation.line} (${violation.reason})`);
+  }
+  process.exit(1);
+}
+
+runAsScript(import.meta.url, main);

scripts/check-plugin-gateway-gauntlet.mts

@@ -0,0 +1,1187 @@
+#!/usr/bin/env node
+
+// Runs plugin lifecycle and gateway QA gauntlet probes with timing metrics.
+import type { StdioOptions } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import {
+  MAX_TIMER_TIMEOUT_MS,
+  resolveTimerTimeoutMs,
+} from "../packages/normalization-core/src/number-coercion.ts";
+import { normalizeCsvOrLooseStringList } from "../packages/normalization-core/src/string-normalization.ts";
+import { stripLeadingPackageManagerSeparator } from "./lib/arg-utils.mts";
+import { hasUnjoinedWork, runManagedCommand } from "./lib/managed-child-process.mts";
+import {
+  parseNonNegativeInt,
+  parsePositiveInt,
+  parsePositiveNumber,
+} from "./lib/numeric-options.mjs";
+import {
+  buildGauntletPrebuildEnv,
+  collectGatewayCpuObservations,
+  collectMetricObservations,
+  collectPluginsWithRequiredEntries,
+  collectRequiredPluginEntries,
+  collectQaBaselineRegressionObservations,
+  detectCommandDiagnosticFailure,
+  discoverBundledPluginManifests,
+  readQaSuiteSummary,
+  selectPluginEntries,
+} from "./lib/plugin-gateway-gauntlet.mts";
+// Termination tests import this entrypoint in a child before publishing readiness.
+// Keep its record guard on the dependency-light script seam to avoid startup skew.
+import { isRecord } from "./lib/record-shared.mjs";
+
+const DEFAULT_QA_SCENARIOS = [
+  "channel-chat-baseline",
+  "memory-failure-fallback",
+  "gateway-restart-inflight-run",
+];
+const DEFAULT_CPU_CORE_WARN = 0.9;
+const DEFAULT_HOT_WALL_WARN_MS = 30_000;
+const DEFAULT_MAX_RSS_WARN_MB = 1536;
+const DEFAULT_QA_PLUGIN_CHUNK_SIZE = 12;
+const SINGLE_VALUE_FLAGS = new Set([
+  "--build-timeout-ms",
+  "--command-timeout-ms",
+  "--cpu-core-warn",
+  "--hot-wall-warn-ms",
+  "--limit",
+  "--max-rss-warn-mb",
+  "--output-dir",
+  "--qa-cpu-regression-multiplier",
+  "--qa-plugin-chunk-size",
+  "--qa-timeout-ms",
+  "--qa-wall-regression-multiplier",
+  "--repo-root",
+  "--rss-anomaly-multiplier",
+  "--shard-index",
+  "--shard-total",
+  "--wall-anomaly-multiplier",
+]);
+const COMMAND_OUTPUT_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+const ANSI_PATTERN = new RegExp(String.raw`\u001B\[[0-9;]*m`, "gu");
+
+type ProcessSignal = `SIG${string}`;
+type PluginEntry = ReturnType<typeof discoverBundledPluginManifests>[number];
+type CommandAlias = PluginEntry["cliCommandAliases"][number];
+export type GauntletMeasuredRow = {
+  label: string;
+  phase: string;
+  pluginId: string | null;
+  status: number;
+  diagnosticFailure: string | null;
+  diagnosticDetail?: string;
+  signal: ProcessSignal | null;
+  timedOut: boolean;
+  spawnError: { code: string | null; message: string } | null;
+  logPath: string | null;
+  logWriteError?: string;
+  qaSummaryPath?: string;
+  qaMetrics?: unknown;
+} & ReturnType<typeof parseTimedMetrics>;
+export type GauntletMeasuredCommandParams = {
+  args: string[];
+  command: string;
+  consoleOutputMaxBytes?: number;
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  label: string;
+  logDir: string;
+  maxBufferBytes?: number;
+  phase: string;
+  pluginId?: string;
+  spawnOptions?: { stdio?: StdioOptions };
+  timeoutKillGraceMs?: number;
+  timeoutMs: number;
+  timeMode?: "none";
+};
+type GauntletObservation = Record<string, unknown> & {
+  coldStart?: boolean;
+  kind?: string;
+  phase?: string;
+};
+type GauntletContext = {
+  repoRoot: string;
+  outputDir: string;
+  env: NodeJS.ProcessEnv;
+  matrix: PluginEntry[];
+  plugins: PluginEntry[];
+  rows: GauntletMeasuredRow[];
+  commandTimeoutMs: number;
+  skipSlashHelp: boolean;
+  includePluginOwnedCliAliases: boolean;
+  qaBaseline: boolean;
+  qaScenarios: string[];
+  qaPluginChunkSize: number;
+  qaTimeoutMs: number;
+};
+type QaSummary = NonNullable<ReturnType<typeof readQaSuiteSummary>["summary"]>;
+
+/**
+ * Parses plugin gateway gauntlet CLI arguments and env defaults.
+ */
+export function parseArgs(argv: string[]) {
+  const args = stripLeadingPackageManagerSeparator(argv);
+  const pluginIds: string[] = [];
+  const qaScenarios: string[] = [];
+  const options = {
+    repoRoot: process.cwd(),
+    outputDir: path.join(
+      process.cwd(),
+      ".artifacts",
+      "plugin-gateway-gauntlet",
+      new Date().toISOString().replace(/[:.]/g, "-"),
+    ),
+    pluginIds,
+    shardTotal: readOptionalPositiveIntEnv("OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_TOTAL") ?? 1,
+    shardIndex: readOptionalNonNegativeIntEnv("OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_INDEX") ?? 0,
+    limit: undefined as number | undefined,
+    skipPrebuild: false,
+    skipLifecycle: false,
+    skipQa: false,
+    qaBaseline: false,
+    skipSlashHelp: false,
+    qaScenarios,
+    qaPluginChunkSize: DEFAULT_QA_PLUGIN_CHUNK_SIZE,
+    cpuCoreWarn: DEFAULT_CPU_CORE_WARN,
+    hotWallWarnMs: DEFAULT_HOT_WALL_WARN_MS,
+    maxRssWarnMb: DEFAULT_MAX_RSS_WARN_MB,
+    wallAnomalyMultiplier: 3,
+    rssAnomalyMultiplier: 2.5,
+    qaCpuRegressionMultiplier: 2,
+    qaWallRegressionMultiplier: 2,
+    commandTimeoutMs: 120_000,
+    buildTimeoutMs: 600_000,
+    qaTimeoutMs: 900_000,
+    allowEmpty: false,
+    failOnObservation: process.env.OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_FAIL_ON_OBSERVATION === "1",
+    keepRunRoot: process.env.OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_KEEP_RUN_ROOT === "1",
+  };
+  const envIds = normalizeCsvOrLooseStringList(process.env.OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_IDS);
+  options.pluginIds.push(...envIds);
+  const seenSingleValueFlags = new Set<string>();
+  parseArgv: for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === undefined) {
+      break;
+    }
+    if (SINGLE_VALUE_FLAGS.has(arg)) {
+      if (seenSingleValueFlags.has(arg)) {
+        throw new Error(`${arg} was provided more than once`);
+      }
+      seenSingleValueFlags.add(arg);
+    }
+    const readValue = () => {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error(`Missing value for ${arg}`);
+      }
+      index += 1;
+      return value;
+    };
+    switch (arg) {
+      case "--":
+        break parseArgv;
+      case "--repo-root":
+        options.repoRoot = path.resolve(readValue());
+        break;
+      case "--output-dir":
+        options.outputDir = path.resolve(readValue());
+        break;
+      case "--plugin":
+        options.pluginIds.push(readValue());
+        break;
+      case "--shard-total":
+        options.shardTotal = parsePositiveInt(readValue(), "--shard-total");
+        break;
+      case "--shard-index":
+        options.shardIndex = parseNonNegativeInt(readValue(), "--shard-index");
+        break;
+      case "--limit":
+        options.limit = parsePositiveInt(readValue(), "--limit");
+        break;
+      case "--qa-scenario":
+        options.qaScenarios.push(readValue());
+        break;
+      case "--qa-plugin-chunk-size":
+        options.qaPluginChunkSize = parsePositiveInt(readValue(), "--qa-plugin-chunk-size");
+        break;
+      case "--qa-baseline":
+        options.qaBaseline = true;
+        break;
+      case "--cpu-core-warn":
+        options.cpuCoreWarn = parsePositiveNumber(readValue(), "--cpu-core-warn");
+        break;
+      case "--hot-wall-warn-ms":
+        options.hotWallWarnMs = parsePositiveInt(readValue(), "--hot-wall-warn-ms");
+        break;
+      case "--max-rss-warn-mb":
+        options.maxRssWarnMb = parsePositiveNumber(readValue(), "--max-rss-warn-mb");
+        break;
+      case "--wall-anomaly-multiplier":
+        options.wallAnomalyMultiplier = parsePositiveNumber(
+          readValue(),
+          "--wall-anomaly-multiplier",
+        );
+        break;
+      case "--rss-anomaly-multiplier":
+        options.rssAnomalyMultiplier = parsePositiveNumber(readValue(), "--rss-anomaly-multiplier");
+        break;
+      case "--qa-cpu-regression-multiplier":
+        options.qaCpuRegressionMultiplier = parsePositiveNumber(
+          readValue(),
+          "--qa-cpu-regression-multiplier",
+        );
+        break;
+      case "--qa-wall-regression-multiplier":
+        options.qaWallRegressionMultiplier = parsePositiveNumber(
+          readValue(),
+          "--qa-wall-regression-multiplier",
+        );
+        break;
+      case "--command-timeout-ms":
+        options.commandTimeoutMs = parsePositiveInt(readValue(), "--command-timeout-ms");
+        break;
+      case "--build-timeout-ms":
+        options.buildTimeoutMs = parsePositiveInt(readValue(), "--build-timeout-ms");
+        break;
+      case "--qa-timeout-ms":
+        options.qaTimeoutMs = parsePositiveInt(readValue(), "--qa-timeout-ms");
+        break;
+      case "--skip-prebuild":
+        options.skipPrebuild = true;
+        break;
+      case "--skip-lifecycle":
+        options.skipLifecycle = true;
+        break;
+      case "--skip-qa":
+        options.skipQa = true;
+        break;
+      case "--skip-slash-help":
+        options.skipSlashHelp = true;
+        break;
+      case "--keep-run-root":
+        options.keepRunRoot = true;
+        break;
+      case "--allow-empty":
+        options.allowEmpty = true;
+        break;
+      case "--fail-on-observation":
+        options.failOnObservation = true;
+        break;
+      case "--help":
+        printHelp();
+        process.exit(0);
+        break;
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  if (options.qaScenarios.length === 0) {
+    options.qaScenarios = [...DEFAULT_QA_SCENARIOS];
+  }
+  assertNoDuplicateValues(options.pluginIds, "--plugin");
+  assertNoDuplicateValues(options.qaScenarios, "--qa-scenario");
+  return options;
+}
+
+function printHelp() {
+  console.log(`Usage: pnpm test:plugins:gateway-gauntlet [options]
+
+Runs a shardable bundled-plugin lifecycle, slash inventory, and QA gateway perf gauntlet.
+
+Options:
+  --plugin <id>                  Plugin id to include, repeatable
+  --shard-total <count>          Total plugin shards (default: env or 1)
+  --shard-index <index>          Zero-based shard index (default: env or 0)
+  --limit <count>                Limit selected plugins after sharding
+  --output-dir <path>            Artifact directory
+  --qa-scenario <id>             QA Lab scenario id, repeatable
+  --qa-plugin-chunk-size <count> Plugins enabled per QA run (default: 12)
+  --qa-baseline                  Run a no-extra-plugin QA baseline before plugin chunks
+  --cpu-core-warn <ratio>        Hot CPU threshold (default: 0.9)
+  --hot-wall-warn-ms <ms>        Minimum wall time for hot CPU observations (default: 30000)
+  --max-rss-warn-mb <mb>         Maximum RSS warning threshold (default: 1536)
+  --wall-anomaly-multiplier <n>  Wall-time anomaly multiplier (default: 3)
+  --rss-anomaly-multiplier <n>   RSS anomaly multiplier (default: 2.5)
+  --qa-cpu-regression-multiplier <n>  QA baseline CPU regression multiplier (default: 2)
+  --qa-wall-regression-multiplier <n> QA baseline wall regression multiplier (default: 2)
+  --command-timeout-ms <ms>      Lifecycle/slash command timeout (default: 120000)
+  --build-timeout-ms <ms>        Prebuild command timeout (default: 600000)
+  --qa-timeout-ms <ms>           QA chunk timeout (default: 900000)
+  --skip-prebuild                Skip the upfront build used to avoid per-command rebuild noise
+  --skip-lifecycle              Skip plugin install/inspect/disable/enable/doctor/uninstall
+  --skip-qa                     Skip QA Lab RPC conversation runs
+  --skip-slash-help             Skip CLI help probes for plugin-declared command aliases
+  --allow-empty                 Allow zero-command runs when every active phase is skipped
+  --fail-on-observation         Treat RSS/CPU/wall observation rows as guard failures
+  --keep-run-root               Preserve isolated HOME/state/log temp root after success
+
+Environment:
+  OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_IDS   Comma-separated plugin ids to include
+  OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_TOTAL Total plugin shards
+  OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_INDEX Zero-based shard index
+  OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_FAIL_ON_OBSERVATION=1
+  OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_KEEP_RUN_ROOT=1
+  OPENCLAW_PLUGIN_GATEWAY_GAUNTLET_QA_SUMMARY_MAX_BYTES  QA summary read ceiling
+`);
+}
+
+function assertNoDuplicateValues(values: string[], label: string) {
+  const seen = new Set();
+  for (const value of values) {
+    const normalized = value.trim();
+    if (!normalized) {
+      continue;
+    }
+    if (seen.has(normalized)) {
+      throw new Error(`Duplicate ${label} value: ${normalized}`);
+    }
+    seen.add(normalized);
+  }
+}
+
+function readOptionalPositiveIntEnv(name: string) {
+  const raw = process.env[name];
+  return raw ? parsePositiveInt(raw, name) : undefined;
+}
+
+function readOptionalNonNegativeIntEnv(name: string) {
+  const raw = process.env[name];
+  return raw ? parseNonNegativeInt(raw, name) : undefined;
+}
+
+function shouldPromoteObservationGuardFailure(observation: GauntletObservation) {
+  // Setup and the first cold work command are still reported, but they are not
+  // stable enough to fail the gauntlet's steady-state regression guard.
+  return observation?.phase !== "prebuild" && observation?.coldStart !== true;
+}
+
+export function buildObservationGuardFailures(
+  observations: GauntletObservation[],
+  enabled = false,
+) {
+  if (!enabled) {
+    return [];
+  }
+  return observations
+    .filter((observation) => shouldPromoteObservationGuardFailure(observation))
+    .map((observation) => ({
+      kind: `observation:${observation.kind ?? "unknown"}`,
+      message: `Gauntlet observation threshold exceeded: ${observation.kind ?? "unknown"}`,
+      observation,
+    }));
+}
+
+/**
+ * Builds the command that prepares QA runtime artifacts before gauntlet probes.
+ */
+export function createGauntletPrebuildCommand(repoRoot: string) {
+  return {
+    command: process.execPath,
+    args: ["--import", "tsx", path.join(repoRoot, "scripts", "build-all.mts"), "qaRuntime"],
+  };
+}
+
+function openclawCommand(repoRoot: string, args: string[]) {
+  return {
+    command: process.execPath,
+    args: [path.join(repoRoot, "dist", "entry.js"), ...args],
+  };
+}
+
+function builtEntryPath(repoRoot: string) {
+  return path.join(repoRoot, "dist", "entry.js");
+}
+
+function selectSlashHelpAliases(plugin: PluginEntry, includePluginOwnedCliAliases: boolean) {
+  return includePluginOwnedCliAliases
+    ? plugin.cliCommandAliases
+    : plugin.cliCommandAliases.filter((entry) => !isPluginOwnedCliAlias(entry));
+}
+
+function requiresBuiltEntry(options: ReturnType<typeof parseArgs>, selectedPlugins: PluginEntry[]) {
+  if (selectedPlugins.length === 0) {
+    return false;
+  }
+  if (!options.skipLifecycle) {
+    return true;
+  }
+  if (options.skipSlashHelp) {
+    return false;
+  }
+  return selectedPlugins.some((plugin) => selectSlashHelpAliases(plugin, true).length > 0);
+}
+
+function sourceOpenclawCommand(repoRoot: string, args: string[]) {
+  return {
+    command: process.execPath,
+    args: [path.join(repoRoot, "scripts", "run-node.mjs"), ...args],
+  };
+}
+
+function chunkArray<Value>(values: Value[], chunkSize: number) {
+  const chunks: Value[][] = [];
+  for (let index = 0; index < values.length; index += chunkSize) {
+    chunks.push(values.slice(index, index + chunkSize));
+  }
+  return chunks;
+}
+
+/**
+ * Converts an output path to a repo-relative path, rejecting paths outside the repo.
+ */
+export function toRepoRelativePath(repoRoot: string, absolutePath: string) {
+  const relativePath = path.relative(repoRoot, absolutePath);
+  if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    throw new Error(`Output path must stay inside repo root: ${absolutePath}`);
+  }
+  return relativePath;
+}
+
+function validateOutputDir(options: ReturnType<typeof parseArgs>, repoRoot: string) {
+  if (!options.skipQa) {
+    toRepoRelativePath(repoRoot, path.join(options.outputDir, "qa-suite"));
+  }
+}
+
+function createIsolatedEnv(repoRoot: string, runRoot: string) {
+  const home = path.join(runRoot, "home");
+  const stateDir = path.join(runRoot, "state");
+  const configPath = path.join(stateDir, "openclaw.json");
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(
+    configPath,
+    `${JSON.stringify({ logging: { file: path.join(runRoot, "logs", "openclaw.log") } })}\n`,
+    { encoding: "utf8", mode: 0o600, flag: "wx" },
+  );
+  return {
+    ...process.env,
+    HOME: home,
+    XDG_CONFIG_HOME: path.join(home, ".config"),
+    XDG_CACHE_HOME: path.join(home, ".cache"),
+    XDG_DATA_HOME: path.join(home, ".local", "share"),
+    OPENCLAW_STATE_DIR: stateDir,
+    OPENCLAW_CONFIG_PATH: configPath,
+    OPENCLAW_QA_SUITE_PROGRESS: process.env.OPENCLAW_QA_SUITE_PROGRESS ?? "1",
+    PATH: process.env.PATH,
+    PWD: repoRoot,
+  };
+}
+
+function hasUsrBinTime() {
+  return fs.existsSync("/usr/bin/time");
+}
+
+function timeWrapperArgs(command: string, args: string[]) {
+  if (!hasUsrBinTime()) {
+    return { command, args, mode: "none" };
+  }
+  if (process.platform === "darwin") {
+    return { command: "/usr/bin/time", args: ["-l", command, ...args], mode: "bsd" };
+  }
+  return { command: "/usr/bin/time", args: ["-v", command, ...args], mode: "gnu" };
+}
+
+/**
+ * Parses `/usr/bin/time` output into wall, CPU, and RSS metrics.
+ */
+export function parseTimedMetrics(stderr: string, wallMs: number, mode: string) {
+  let userSeconds: number | null = null;
+  let systemSeconds: number | null = null;
+  let maxRssMb: number | null = null;
+  if (mode === "gnu") {
+    userSeconds = parseLastFloat(stderr, /^\s*User time \(seconds\):\s*([0-9.]+)\s*$/gmu);
+    systemSeconds = parseLastFloat(stderr, /^\s*System time \(seconds\):\s*([0-9.]+)\s*$/gmu);
+    const maxRssKb = parseLastFloat(
+      stderr,
+      /^\s*Maximum resident set size \(kbytes\):\s*([0-9.]+)\s*$/gmu,
+    );
+    maxRssMb = maxRssKb == null ? null : maxRssKb / 1024;
+  } else if (mode === "bsd") {
+    const cpuLine = parseLastMatch(
+      stderr,
+      /^\s*[0-9.]+\s+real\s+([0-9.]+)\s+user\s+([0-9.]+)\s+sys\s*$/gmu,
+    );
+    userSeconds = parseMatchFloat(cpuLine, 1);
+    systemSeconds = parseMatchFloat(cpuLine, 2);
+    const maxRssBytes = parseLastFloat(stderr, /^\s*([0-9]+)\s+maximum resident set size\s*$/gmu);
+    maxRssMb = maxRssBytes == null ? null : maxRssBytes / 1024 / 1024;
+  }
+  const cpuMs =
+    userSeconds == null && systemSeconds == null
+      ? null
+      : ((userSeconds ?? 0) + (systemSeconds ?? 0)) * 1000;
+  return {
+    wallMs,
+    cpuMs,
+    cpuCoreRatio: cpuMs == null || wallMs <= 0 ? null : cpuMs / wallMs,
+    maxRssMb,
+  };
+}
+
+function parseLastMatch(value: string, pattern: RegExp) {
+  let lastMatch: RegExpMatchArray | null = null;
+  for (const match of value.matchAll(pattern)) {
+    lastMatch = match;
+  }
+  return lastMatch;
+}
+
+function parseMatchFloat(match: RegExpMatchArray | null, index: number) {
+  if (!match) {
+    return null;
+  }
+  const parsed = Number(match[index]);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function parseLastFloat(value: string, pattern: RegExp) {
+  return parseMatchFloat(parseLastMatch(value, pattern), 1);
+}
+
+function stripAnsi(value: string) {
+  return value.replace(ANSI_PATTERN, "");
+}
+
+function resolveOptionalTimerTimeoutMs(valueMs: number | undefined) {
+  return valueMs === undefined || valueMs <= 0
+    ? null
+    : resolveTimerTimeoutMs(valueMs, MAX_TIMER_TIMEOUT_MS);
+}
+
+function writeCommandLog(params: {
+  logDir: string;
+  label: string;
+  command: string[];
+  stdout: string;
+  stderr: string;
+}) {
+  const { logDir, label, stdout, stderr } = params;
+  fs.mkdirSync(logDir, { recursive: true });
+  const safeLabel = label.replace(/[^a-zA-Z0-9_.-]+/gu, "_");
+  const logPath = path.join(logDir, `${safeLabel}.log`);
+  fs.writeFileSync(
+    logPath,
+    [`$ ${params.command.join(" ")}`, "", stripAnsi(stdout), stripAnsi(stderr)].join("\n"),
+    "utf8",
+  );
+  return logPath;
+}
+
+/**
+ * Runs one command with optional timing wrapper, bounded output, and log capture.
+ */
+export async function runMeasuredCommand(
+  params: GauntletMeasuredCommandParams,
+): Promise<GauntletMeasuredRow> {
+  const { command, args, mode } =
+    params.timeMode === "none"
+      ? { command: params.command, args: params.args, mode: "none" }
+      : timeWrapperArgs(params.command, params.args);
+  const started = performance.now();
+  let stdout = "";
+  let stderr = "";
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  let stdoutRelayBytes = 0;
+  let stderrRelayBytes = 0;
+  let stdoutTruncated = false;
+  let stderrTruncated = false;
+  let stdoutRelayTruncated = false;
+  let stderrRelayTruncated = false;
+  let spawnError: GauntletMeasuredRow["spawnError"] = null;
+  let timedOut = false;
+  let exitStatus: number | null = null;
+  let exitSignal: ProcessSignal | null = null;
+  let parentTerminationSignal: NodeJS.Signals | undefined;
+  let commandError: unknown;
+  const maxBufferBytes = params.maxBufferBytes ?? COMMAND_OUTPUT_MAX_BUFFER_BYTES;
+  const maxRelayBytes = params.consoleOutputMaxBytes ?? maxBufferBytes;
+  const timeoutMs = resolveOptionalTimerTimeoutMs(params.timeoutMs);
+  const timeoutKillGraceMs = resolveTimerTimeoutMs(
+    params.timeoutKillGraceMs ?? 5_000,
+    MAX_TIMER_TIMEOUT_MS,
+  );
+  const appendCapturedOutput = (streamName: "stdout" | "stderr", chunk: string | Uint8Array) => {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    const currentBytes = streamName === "stdout" ? stdoutBytes : stderrBytes;
+    const alreadyTruncated = streamName === "stdout" ? stdoutTruncated : stderrTruncated;
+    if (alreadyTruncated) {
+      return;
+    }
+    const remainingBytes = maxBufferBytes - currentBytes;
+    const appendTruncation = () => {
+      const message = `\n[${streamName} truncated after ${maxBufferBytes} bytes]\n`;
+      if (streamName === "stdout") {
+        stdout += message;
+        stdoutTruncated = true;
+      } else {
+        stderr += message;
+        stderrTruncated = true;
+      }
+    };
+    if (remainingBytes <= 0) {
+      appendTruncation();
+      return;
+    }
+    const capturedBuffer =
+      buffer.length > remainingBytes ? buffer.subarray(0, remainingBytes) : buffer;
+    if (streamName === "stdout") {
+      stdout += capturedBuffer.toString("utf8");
+      stdoutBytes += capturedBuffer.length;
+    } else {
+      stderr += capturedBuffer.toString("utf8");
+      stderrBytes += capturedBuffer.length;
+    }
+    if (buffer.length > remainingBytes) {
+      appendTruncation();
+    }
+  };
+  const relayOutput = (streamName: "stdout" | "stderr", chunk: string | Uint8Array) => {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    const currentBytes = streamName === "stdout" ? stdoutRelayBytes : stderrRelayBytes;
+    const alreadyTruncated = streamName === "stdout" ? stdoutRelayTruncated : stderrRelayTruncated;
+    if (alreadyTruncated) {
+      return;
+    }
+    const write =
+      streamName === "stdout"
+        ? process.stdout.write.bind(process.stdout)
+        : process.stderr.write.bind(process.stderr);
+    const markTruncated = () => {
+      write(`\n[${streamName} relay truncated after ${maxRelayBytes} bytes]\n`);
+      if (streamName === "stdout") {
+        stdoutRelayTruncated = true;
+      } else {
+        stderrRelayTruncated = true;
+      }
+    };
+    const remainingBytes = maxRelayBytes - currentBytes;
+    if (remainingBytes <= 0) {
+      markTruncated();
+      return;
+    }
+    const relayedBuffer =
+      buffer.length > remainingBytes ? buffer.subarray(0, remainingBytes) : buffer;
+    if (relayedBuffer.length > 0) {
+      write(relayedBuffer.toString("utf8"));
+    }
+    if (streamName === "stdout") {
+      stdoutRelayBytes += relayedBuffer.length;
+    } else {
+      stderrRelayBytes += relayedBuffer.length;
+    }
+    if (buffer.length > remainingBytes) {
+      markTruncated();
+    }
+  };
+  const appendOutput = (streamName: "stdout" | "stderr", chunk: string | Uint8Array) => {
+    relayOutput(streamName, chunk);
+    appendCapturedOutput(streamName, chunk);
+  };
+  try {
+    await runManagedCommand({
+      bin: command,
+      args,
+      cwd: params.cwd,
+      env: params.env,
+      shell: false,
+      stdio: (mode === "none" ? params.spawnOptions?.stdio : undefined) ?? "pipe",
+      timeoutMs: timeoutMs ?? undefined,
+      timeoutKillGraceMs,
+      signalKillGraceMs: timeoutKillGraceMs,
+      // Windows retains the managed owner's ordinary completion contract.
+      requireProcessTreeExit: process.platform !== "win32",
+      onSignal(signal) {
+        parentTerminationSignal ??= signal;
+      },
+      onReady(child) {
+        child.once("exit", (status, signal) => {
+          exitStatus = status;
+          exitSignal = signal;
+        });
+        child.stdout?.on("data", (chunk) => appendOutput("stdout", chunk));
+        child.stderr?.on("data", (chunk) => appendOutput("stderr", chunk));
+      },
+    });
+  } catch (error) {
+    commandError = error;
+    const code =
+      error && typeof error === "object" && "code" in error && typeof error.code === "string"
+        ? error.code
+        : null;
+    spawnError = {
+      code,
+      message: error instanceof Error ? error.message : String(error),
+    };
+    timedOut = code === "ETIMEDOUT";
+  }
+  if (parentTerminationSignal && !hasUnjoinedWork(commandError)) {
+    // Preserve signal termination after cleanup, without admitting another probe.
+    const terminationSignal = parentTerminationSignal;
+    return await new Promise<never>(() => {
+      process.kill(process.pid, terminationSignal);
+    });
+  }
+  const wallMs = performance.now() - started;
+  const finalStatus =
+    spawnError && !timedOut ? 1 : (exitStatus ?? (exitSignal || spawnError ? 1 : 0));
+  const finalStderr = [
+    stderr,
+    spawnError ? `[spawn error] ${spawnError.code ?? "unknown"} ${spawnError.message}` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+  let logPath: string | null = null;
+  let logWriteError: string | null = null;
+  try {
+    logPath = writeCommandLog({
+      logDir: params.logDir,
+      label: params.label,
+      command: [params.command, ...params.args],
+      stdout,
+      stderr: finalStderr,
+    });
+  } catch (error) {
+    logWriteError = error instanceof Error ? error.message : String(error);
+  }
+  if (hasUnjoinedWork(commandError)) {
+    throw commandError;
+  }
+  const outputDiagnosticFailure = detectCommandDiagnosticFailure(stdout, finalStderr);
+  const diagnosticFailure =
+    outputDiagnosticFailure ?? (logWriteError ? "command-log-write-failure" : null);
+  return {
+    label: params.label,
+    phase: params.phase,
+    pluginId: params.pluginId ?? null,
+    status: logWriteError ? 1 : finalStatus,
+    diagnosticFailure,
+    signal: exitSignal,
+    timedOut,
+    spawnError,
+    logPath,
+    ...(logWriteError ? { logWriteError } : {}),
+    ...parseTimedMetrics(finalStderr, wallMs, mode),
+  };
+}
+
+/**
+ * Reports whether gauntlet result rows contain work beyond the prebuild step.
+ */
+export function hasGauntletWorkRows(rows: Array<Pick<GauntletMeasuredRow, "phase">>) {
+  return rows.some((row) => row.phase !== "prebuild");
+}
+
+function isPluginOwnedCliAlias(alias: CommandAlias) {
+  return alias.kind === "runtime-slash" && alias.cliCommand === alias.name;
+}
+
+function buildSlashHelpProbe(
+  params: GauntletContext & {
+    plugin: PluginEntry;
+    alias: CommandAlias;
+  },
+) {
+  const command = params.alias.cliCommand ?? params.alias.name;
+  return {
+    cwd: params.repoRoot,
+    env: params.env,
+    logDir: path.join(params.outputDir, "logs", "slash-help"),
+    ...openclawCommand(params.repoRoot, [command, "--help"]),
+    label: `${params.plugin.id}-slash-${params.alias.name}`,
+    phase: "slash:help",
+    pluginId: params.plugin.id,
+    timeoutMs: params.commandTimeoutMs,
+  };
+}
+
+async function runPluginLifecycleCommand(
+  params: GauntletContext & {
+    logPluginId: string;
+    label: string;
+    phase: string;
+    args: string[];
+    pluginId: string;
+  },
+) {
+  process.stderr.write(`[plugin-gauntlet] ${params.logPluginId} ${params.phase}\n`);
+  params.rows.push(
+    await runMeasuredCommand({
+      cwd: params.repoRoot,
+      env: params.env,
+      logDir: path.join(params.outputDir, "logs", "lifecycle"),
+      ...openclawCommand(params.repoRoot, ["plugins", ...params.args]),
+      label: params.label,
+      phase: `lifecycle:${params.phase}`,
+      pluginId: params.pluginId,
+      timeoutMs: params.commandTimeoutMs,
+    }),
+  );
+}
+
+async function runPluginLifecycle(params: GauntletContext) {
+  for (const plugin of params.plugins) {
+    const requiredPlugins = collectRequiredPluginEntries(params.matrix, [plugin]);
+    for (const requiredPlugin of requiredPlugins) {
+      await runPluginLifecycleCommand({
+        ...params,
+        logPluginId: plugin.id,
+        label: `${plugin.id}-requires-${requiredPlugin.id}-install`,
+        phase: `requires:${requiredPlugin.id}:install`,
+        args: ["install", requiredPlugin.id],
+        pluginId: requiredPlugin.id,
+      });
+    }
+    type LifecycleCommand =
+      | { phase: string; args: string[] }
+      | { phase: string; alias: CommandAlias };
+    const commands = [
+      {
+        phase: "install",
+        args: ["install", plugin.id],
+      },
+      { phase: "inspect", args: ["inspect", plugin.id, "--json"] },
+      ...(params.skipSlashHelp
+        ? []
+        : plugin.cliCommandAliases
+            .filter(isPluginOwnedCliAlias)
+            .map((alias) => ({ phase: `slash-help:${alias.name}`, alias }))),
+      { phase: "disable", args: ["disable", plugin.id] },
+      ...(plugin.hasRequiredConfigFields ? [] : [{ phase: "enable", args: ["enable", plugin.id] }]),
+      { phase: "doctor", args: ["doctor"] },
+      { phase: "uninstall", args: ["uninstall", plugin.id, "--force"] },
+    ] satisfies LifecycleCommand[];
+    for (const command of commands) {
+      if ("alias" in command) {
+        process.stderr.write(`[plugin-gauntlet] ${plugin.id} ${command.phase}\n`);
+        params.rows.push(
+          await runMeasuredCommand({
+            ...buildSlashHelpProbe({
+              ...params,
+              plugin,
+              alias: command.alias,
+            }),
+            label: `${plugin.id}-${command.phase}`,
+          }),
+        );
+        continue;
+      }
+      await runPluginLifecycleCommand({
+        ...params,
+        logPluginId: plugin.id,
+        label: `${plugin.id}-${command.phase}`,
+        phase: command.phase,
+        args: command.args,
+        pluginId: plugin.id,
+      });
+    }
+    for (const requiredPlugin of requiredPlugins.toReversed()) {
+      await runPluginLifecycleCommand({
+        ...params,
+        logPluginId: plugin.id,
+        label: `${plugin.id}-requires-${requiredPlugin.id}-uninstall`,
+        phase: `requires:${requiredPlugin.id}:uninstall`,
+        args: ["uninstall", requiredPlugin.id, "--force"],
+        pluginId: requiredPlugin.id,
+      });
+    }
+  }
+}
+
+async function runSlashHelpProbes(params: GauntletContext) {
+  for (const plugin of params.plugins) {
+    const aliases = selectSlashHelpAliases(plugin, params.includePluginOwnedCliAliases);
+    for (const alias of aliases) {
+      process.stderr.write(`[plugin-gauntlet] ${plugin.id} slash-help /${alias.name}\n`);
+      params.rows.push(
+        await runMeasuredCommand({
+          ...buildSlashHelpProbe({
+            ...params,
+            plugin,
+            alias,
+          }),
+        }),
+      );
+    }
+  }
+}
+
+async function runQaChunks(params: GauntletContext) {
+  const chunks = [
+    ...(params.qaBaseline ? [{ label: "baseline", plugins: [] }] : []),
+    ...chunkArray(params.plugins, params.qaPluginChunkSize).map((plugins, index) => ({
+      label: `chunk-${String(index).padStart(2, "0")}`,
+      plugins,
+    })),
+  ];
+  const summaries: QaSummary[] = [];
+  for (const [index, chunk] of chunks.entries()) {
+    const outputDir = path.join(params.outputDir, "qa-suite", chunk.label);
+    const outputArg = toRepoRelativePath(params.repoRoot, outputDir);
+    const pluginIds = chunk.plugins.map((plugin) => plugin.id);
+    const enabledPluginIds = collectPluginsWithRequiredEntries(params.matrix, chunk.plugins).map(
+      (plugin) => plugin.id,
+    );
+    const pluginIdLabel = pluginIds.length > 0 ? pluginIds.join(",") : "<baseline>";
+    process.stderr.write(
+      `[plugin-gauntlet] qa chunk ${index + 1}/${chunks.length}: ${pluginIdLabel}\n`,
+    );
+    const row = await runMeasuredCommand({
+      cwd: params.repoRoot,
+      env: params.env,
+      logDir: path.join(params.outputDir, "logs", "qa-suite"),
+      ...sourceOpenclawCommand(params.repoRoot, [
+        "qa",
+        "suite",
+        "--provider-mode",
+        "mock-openai",
+        "--concurrency",
+        "1",
+        "--output-dir",
+        outputArg,
+        ...params.qaScenarios.flatMap((scenario) => ["--scenario", scenario]),
+        ...enabledPluginIds.flatMap((pluginId) => ["--enable-plugin", pluginId]),
+      ]),
+      label: `qa-${chunk.label}`,
+      phase: "qa:rpc",
+      timeoutMs: params.qaTimeoutMs,
+    });
+    const summaryPath = path.join(outputDir, "qa-suite-summary.json");
+    const qaSummaryResult = readQaSuiteSummary(summaryPath);
+    const qaDiagnosticFailure =
+      row.status === 0 && !row.timedOut ? qaSummaryResult.diagnosticFailure : null;
+    params.rows.push({
+      ...row,
+      pluginId: pluginIdLabel,
+      qaSummaryPath: summaryPath,
+      ...(qaDiagnosticFailure ? { diagnosticFailure: qaDiagnosticFailure } : {}),
+      ...(qaSummaryResult.diagnosticDetail
+        ? { diagnosticDetail: qaSummaryResult.diagnosticDetail }
+        : {}),
+      ...(qaSummaryResult.summary?.metrics ? { qaMetrics: qaSummaryResult.summary.metrics } : {}),
+    });
+    if (qaSummaryResult.summary) {
+      summaries.push(qaSummaryResult.summary);
+    }
+  }
+  return summaries;
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+  const repoRoot = path.resolve(options.repoRoot);
+  validateOutputDir(options, repoRoot);
+  fs.mkdirSync(options.outputDir, { recursive: true });
+  const runRoot = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-plugin-gauntlet-"));
+  let preserveRunRoot = options.keepRunRoot;
+  try {
+    const env = createIsolatedEnv(repoRoot, runRoot);
+    const matrix = discoverBundledPluginManifests(repoRoot);
+    const selectedPlugins = selectPluginEntries(matrix, {
+      ids: options.pluginIds,
+      shardTotal: options.shardTotal,
+      shardIndex: options.shardIndex,
+      limit: options.limit,
+    });
+    const selectedPluginsWithRequired = collectPluginsWithRequiredEntries(matrix, selectedPlugins);
+    const rows: GauntletMeasuredRow[] = [];
+    const commandEnv = buildGauntletPrebuildEnv(env, {
+      includePrivateQa: !options.skipQa,
+      buildIds: selectedPluginsWithRequired.map((plugin) => plugin.buildId),
+      skipDeclarationBuild: true,
+    });
+    const context = {
+      repoRoot,
+      outputDir: options.outputDir,
+      env: commandEnv,
+      matrix,
+      plugins: selectedPlugins,
+      rows,
+      commandTimeoutMs: options.commandTimeoutMs,
+      skipSlashHelp: options.skipSlashHelp,
+      includePluginOwnedCliAliases: options.skipLifecycle,
+      qaBaseline: options.qaBaseline,
+      qaScenarios: options.qaScenarios,
+      qaPluginChunkSize: options.qaPluginChunkSize,
+      qaTimeoutMs: options.qaTimeoutMs,
+    };
+    if (!options.skipPrebuild && (selectedPlugins.length > 0 || !options.skipQa)) {
+      process.stderr.write("[plugin-gauntlet] prebuild\n");
+      const prebuildCommand = createGauntletPrebuildCommand(repoRoot);
+      rows.push(
+        await runMeasuredCommand({
+          cwd: repoRoot,
+          env: commandEnv,
+          logDir: path.join(options.outputDir, "logs", "prebuild"),
+          command: prebuildCommand.command,
+          args: prebuildCommand.args,
+          label: "prebuild",
+          phase: "prebuild",
+          timeoutMs: options.buildTimeoutMs,
+        }),
+      );
+    }
+    const prebuildFailed = rows.some(
+      (row) => row.phase === "prebuild" && (row.status !== 0 || row.timedOut),
+    );
+    const entryPath = builtEntryPath(repoRoot);
+    const missingSkippedPrebuildEntry =
+      selectedPlugins.length > 0 &&
+      options.skipPrebuild &&
+      requiresBuiltEntry(options, selectedPlugins) &&
+      !fs.existsSync(entryPath);
+    if (!prebuildFailed && !missingSkippedPrebuildEntry && !options.skipLifecycle) {
+      await runPluginLifecycle(context);
+    }
+    if (!prebuildFailed && !missingSkippedPrebuildEntry && !options.skipSlashHelp) {
+      await runSlashHelpProbes(context);
+    }
+    const qaSummaries = options.skipQa || prebuildFailed ? [] : await runQaChunks(context);
+    const metricObservations = collectMetricObservations(rows, {
+      cpuCoreWarn: options.cpuCoreWarn,
+      hotWallWarnMs: options.hotWallWarnMs,
+      maxRssWarnMb: options.maxRssWarnMb,
+      wallAnomalyMultiplier: options.wallAnomalyMultiplier,
+      rssAnomalyMultiplier: options.rssAnomalyMultiplier,
+    });
+    const qaBaselineObservations = collectQaBaselineRegressionObservations(rows, {
+      cpuRegressionMultiplier: options.qaCpuRegressionMultiplier,
+      wallRegressionMultiplier: options.qaWallRegressionMultiplier,
+    });
+    const gatewayObservations = qaSummaries.flatMap((qa) =>
+      collectGatewayCpuObservations({
+        startup: null,
+        qa: isRecord(qa.metrics) ? { metrics: qa.metrics } : undefined,
+        cpuCoreWarn: options.cpuCoreWarn,
+        hotWallWarnMs: options.hotWallWarnMs,
+      }),
+    );
+    const failures = rows.filter(
+      (row) => row.status !== 0 || row.timedOut || row.diagnosticFailure,
+    );
+    const observations = [...metricObservations, ...qaBaselineObservations, ...gatewayObservations];
+    const guardFailures: Array<{ kind: string; message: string }> = [];
+    if (missingSkippedPrebuildEntry) {
+      guardFailures.push({
+        kind: "missing-built-entry",
+        message:
+          `${path.relative(repoRoot, entryPath)} is missing; ` +
+          "run without --skip-prebuild or build the gauntlet runtime first.",
+      });
+    }
+    if (!hasGauntletWorkRows(rows) && !options.allowEmpty && guardFailures.length === 0) {
+      guardFailures.push({
+        kind: "empty-run",
+        message:
+          "No lifecycle, slash-help, or QA gauntlet commands ran; remove a skip flag or pass --allow-empty for intentional dry runs.",
+      });
+    }
+    guardFailures.push(...buildObservationGuardFailures(observations, options.failOnObservation));
+    const hasFailures = failures.length > 0 || guardFailures.length > 0;
+    preserveRunRoot = preserveRunRoot || hasFailures;
+    let cleanupError = null;
+    if (!preserveRunRoot) {
+      try {
+        fs.rmSync(runRoot, { recursive: true, force: true });
+      } catch (error) {
+        cleanupError = error instanceof Error ? error.message : String(error);
+        preserveRunRoot = true;
+      }
+    }
+    const summary = {
+      generatedAt: new Date().toISOString(),
+      repoRoot,
+      outputDir: options.outputDir,
+      isolatedRunRoot: runRoot,
+      isolatedRunRootPreserved: preserveRunRoot,
+      isolatedRunRootCleanupError: cleanupError,
+      selectedPluginCount: selectedPlugins.length,
+      totalPluginCount: matrix.length,
+      options: {
+        pluginIds: options.pluginIds,
+        shardTotal: options.shardTotal,
+        shardIndex: options.shardIndex,
+        limit: options.limit ?? null,
+        qaScenarios: options.qaScenarios,
+        qaPluginChunkSize: options.qaPluginChunkSize,
+        qaBaseline: options.qaBaseline,
+        allowEmpty: options.allowEmpty,
+        failOnObservation: options.failOnObservation,
+        keepRunRoot: options.keepRunRoot,
+        skipLifecycle: options.skipLifecycle,
+        skipQa: options.skipQa,
+        skipSlashHelp: options.skipSlashHelp,
+        skipPrebuild: options.skipPrebuild,
+        thresholds: {
+          cpuCoreWarn: options.cpuCoreWarn,
+          hotWallWarnMs: options.hotWallWarnMs,
+          maxRssWarnMb: options.maxRssWarnMb,
+          wallAnomalyMultiplier: options.wallAnomalyMultiplier,
+          rssAnomalyMultiplier: options.rssAnomalyMultiplier,
+          qaCpuRegressionMultiplier: options.qaCpuRegressionMultiplier,
+          qaWallRegressionMultiplier: options.qaWallRegressionMultiplier,
+        },
+      },
+      matrix,
+      selectedPlugins,
+      rows,
+      observations,
+      failures,
+      guardFailures,
+    };
+    const summaryPath = path.join(options.outputDir, "plugin-gateway-gauntlet-summary.json");
+    fs.writeFileSync(summaryPath, `${JSON.stringify(summary, null, 2)}\n`, "utf8");
+    process.stdout.write(`[plugin-gauntlet] summary: ${summaryPath}\n`);
+    process.stdout.write(
+      `[plugin-gauntlet] plugins=${selectedPlugins.length}/${matrix.length} rows=${rows.length} failures=${failures.length} observations=${summary.observations.length}\n`,
+    );
+    if (preserveRunRoot) {
+      process.stdout.write(`[plugin-gauntlet] isolated run root preserved: ${runRoot}\n`);
+    }
+    for (const failure of failures) {
+      process.stdout.write(
+        `[plugin-gauntlet] failure phase=${failure.phase} plugin=${failure.pluginId ?? "<none>"} status=${failure.status} timedOut=${failure.timedOut} diagnostic=${failure.diagnosticFailure ?? ""} wallMs=${Math.round(failure.wallMs)} log=${failure.logPath}\n`,
+      );
+    }
+    for (const failure of guardFailures) {
+      process.stdout.write(`[plugin-gauntlet] failure ${failure.kind}: ${failure.message}\n`);
+    }
+    for (const observation of summary.observations.slice(0, 20)) {
+      process.stdout.write(`[plugin-gauntlet] observation ${JSON.stringify(observation)}\n`);
+    }
+    if (hasFailures) {
+      process.exitCode = 1;
+    }
+  } catch (error) {
+    const unjoined = hasUnjoinedWork(error);
+    if (unjoined) {
+      process.stderr.write(`[plugin-gauntlet] isolated run root preserved: ${runRoot}\n`);
+    }
+    if (!options.keepRunRoot && !unjoined) {
+      try {
+        fs.rmSync(runRoot, { recursive: true, force: true });
+      } catch (cleanupError) {
+        process.stderr.write(
+          `[plugin-gauntlet] failed to clean isolated run root ${runRoot}: ${
+            cleanupError instanceof Error ? cleanupError.message : String(cleanupError)
+          }\n`,
+        );
+      }
+    }
+    throw error;
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

scripts/check-plugin-sdk-wildcard-reexports.mts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+// Rejects wildcard plugin SDK re-exports in extension API barrels.
+import {
+  createExtensionWildcardReexportScanner,
+  type ExtensionWildcardReexportPolicy,
+} from "./lib/extension-wildcard-reexport-scanner.mts";
+
+const WILDCARD_PLUGIN_SDK_REEXPORT_PATTERN =
+  /^\s*export\s+(?:type\s+)?\*\s+(?:as\s+[$\w]+\s+)?from\s+["']openclaw\/plugin-sdk\//u;
+const policy = {
+  // SDK wildcard exposure is only a public extension-root barrel policy.
+  fileScope: "extension-root-api-files",
+  pattern: WILDCARD_PLUGIN_SDK_REEXPORT_PATTERN,
+  successMessage: "No plugin-sdk wildcard re-exports found in extension API barrels.",
+  findingsMessage: "Found plugin-sdk wildcard re-exports in extension API barrels:",
+  remediationMessage: "Use explicit named exports from the narrow SDK subpath instead.",
+} satisfies ExtensionWildcardReexportPolicy;
+const scanner = createExtensionWildcardReexportScanner(policy);
+
+/**
+ * Finds wildcard plugin SDK re-export lines in an extension API barrel.
+ */
+export const findPluginSdkWildcardReexports = scanner.findLines;
+
+/**
+ * Runs the plugin SDK wildcard re-export guard.
+ */
+export const main = scanner.main;
+
+await scanner.exitIfMain(import.meta.url);