fix(build): stamp runtime postbuild artifacts

scripts/build-all.mjs

@@ -20,6 +20,11 @@ export const BUILD_ALL_STEPS = [
   },
   { label: "runtime-postbuild", kind: "node", args: ["scripts/runtime-postbuild.mjs"] },
   { label: "build-stamp", kind: "node", args: ["scripts/build-stamp.mjs"] },
+  {
+    label: "runtime-postbuild-stamp",
+    kind: "node",
+    args: ["scripts/runtime-postbuild-stamp.mjs"],
+  },
   {
     label: "build:plugin-sdk:dts",
     kind: "pnpm",
@@ -99,6 +104,7 @@ export const BUILD_ALL_PROFILES = {
     "check-cli-bootstrap-imports",
     "runtime-postbuild",
     "build-stamp",
+    "runtime-postbuild-stamp",
     "build:plugin-sdk:dts",
     "write-plugin-sdk-entry-dts",
     "check-plugin-sdk-exports",
@@ -109,7 +115,13 @@ export const BUILD_ALL_PROFILES = {
     "write-cli-startup-metadata",
     "write-cli-compat",
   ],
-  gatewayWatch: ["tsdown", "check-cli-bootstrap-imports", "runtime-postbuild", "build-stamp"],
+  gatewayWatch: [
+    "tsdown",
+    "check-cli-bootstrap-imports",
+    "runtime-postbuild",
+    "build-stamp",
+    "runtime-postbuild-stamp",
+  ],
 };
 
 export function resolveBuildAllSteps(profile = "full") {

scripts/build-stamp.d.mts

@@ -1,22 +1 @@
-export function resolveGitHead(params?: {
-  cwd?: string;
-  spawnSync?: (
-    cmd: string,
-    args: string[],
-    options: unknown,
-  ) => { status: number | null; stdout?: string | null };
-}): string | null;
-
-export function writeBuildStamp(params?: {
-  cwd?: string;
-  fs?: {
-    mkdirSync(path: string, options?: { recursive?: boolean }): void;
-    writeFileSync(path: string, data: string, encoding?: string): void;
-  };
-  now?: () => number;
-  spawnSync?: (
-    cmd: string,
-    args: string[],
-    options: unknown,
-  ) => { status: number | null; stdout?: string | null };
-}): string;
+export { BUILD_STAMP_FILE, resolveGitHead, writeBuildStamp } from "./lib/local-build-metadata.mjs";

scripts/build-stamp.mjs

@@ -1,44 +1,9 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
+import { writeBuildStamp } from "./lib/local-build-metadata.mjs";
 
-export function resolveGitHead(params = {}) {
-  const cwd = params.cwd ?? process.cwd();
-  const spawnSyncImpl = params.spawnSync ?? spawnSync;
-  try {
-    const result = spawnSyncImpl("git", ["rev-parse", "HEAD"], {
-      cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    });
-    if (result.status !== 0) {
-      return null;
-    }
-    const head = (result.stdout ?? "").trim();
-    return head || null;
-  } catch {
-    return null;
-  }
-}
-
-export function writeBuildStamp(params = {}) {
-  const cwd = params.cwd ?? process.cwd();
-  const fsImpl = params.fs ?? fs;
-  const now = params.now ?? Date.now;
-  const distRoot = path.join(cwd, "dist");
-  const buildStampPath = path.join(distRoot, ".buildstamp");
-  const head = resolveGitHead({
-    cwd,
-    spawnSync: params.spawnSync,
-  });
-
-  fsImpl.mkdirSync(distRoot, { recursive: true });
-  fsImpl.writeFileSync(buildStampPath, `${JSON.stringify({ builtAt: now(), head })}\n`, "utf8");
-  return buildStampPath;
-}
+export { BUILD_STAMP_FILE, resolveGitHead, writeBuildStamp } from "./lib/local-build-metadata.mjs";
 
 if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
   try {

scripts/check-gateway-watch-regression.mjs

@@ -7,7 +7,11 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
-import { writeBuildStamp } from "./build-stamp.mjs";
+import {
+  BUILD_STAMP_FILE,
+  writeBuildStamp,
+  writeRuntimePostBuildStamp,
+} from "./lib/local-build-metadata.mjs";
 import { resolveBuildRequirement } from "./run-node.mjs";
 
 const DEFAULTS = {
@@ -594,7 +598,7 @@ function buildRunNodeDeps(env) {
     spawnSync,
     distRoot: path.join(cwd, "dist"),
     distEntry: path.join(cwd, "dist", "/entry.js"),
-    buildStampPath: path.join(cwd, "dist", ".buildstamp"),
+    buildStampPath: path.join(cwd, "dist", BUILD_STAMP_FILE),
     sourceRoots: ["src", "extensions"].map((sourceRoot) => ({
       name: sourceRoot,
       path: path.join(cwd, sourceRoot),
@@ -613,19 +617,25 @@ export function shouldRefreshBuildStampForRestoredArtifacts(params) {
   );
 }
 
+export function writeBuildAndRuntimePostBuildStamps(params = {}) {
+  const cwd = params.cwd ?? process.cwd();
+  writeBuildStamp({ cwd });
+  writeRuntimePostBuildStamp({ cwd });
+}
+
 async function main() {
   const options = parseArgs(process.argv.slice(2));
   ensureDir(options.outputDir);
   if (!options.skipBuild) {
     runCheckedCommand("node", ["scripts/build-all.mjs", "gatewayWatch"]);
     // The watch harness must start from a completed dist/runtime baseline.
-    // Refresh the build stamp after the gateway build finishes so run-node
-    // does not spuriously rebuild inside the bounded watch window.
-    writeBuildStamp({ cwd: process.cwd() });
+    // Refresh both stamps after the gateway build finishes so run-node does not
+    // leave stale local artifact metadata after the bounded watch window.
+    writeBuildAndRuntimePostBuildStamps();
   } else {
     // Restored CI artifacts can be older than the fresh checkout mtimes.
-    // Refresh only the stamp so run-node trusts the already-built dist.
-    writeBuildStamp({ cwd: process.cwd() });
+    // Refresh the local artifact stamps so run-node trusts the already-built dist.
+    writeBuildAndRuntimePostBuildStamps();
   }
 
   let preflightBuildRequirement = resolveBuildRequirement(buildRunNodeDeps(process.env));
@@ -636,9 +646,9 @@ async function main() {
     })
   ) {
     // CI's skip-build path restores a built dist artifact after checkout.
-    // Refresh the stamp so checkout mtimes for package/config files do not
+    // Refresh the stamps so checkout mtimes for package/config files do not
     // force a duplicate build during the bounded gateway:watch window.
-    writeBuildStamp({ cwd: process.cwd() });
+    writeBuildAndRuntimePostBuildStamps();
     preflightBuildRequirement = resolveBuildRequirement(buildRunNodeDeps(process.env));
   }
   if (

scripts/check-openclaw-package-tarball.mjs

@@ -4,6 +4,7 @@
 // prebuilt package artifact with dist inventory, not a source checkout.
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
+import { LOCAL_BUILD_METADATA_DIST_PATHS } from "./lib/local-build-metadata-paths.mjs";
 
 function usage() {
   return "Usage: node scripts/check-openclaw-package-tarball.mjs <openclaw.tgz>";
@@ -39,6 +40,7 @@ const entrySet = new Set(normalized);
 const errors = [];
 const warnings = [];
 const LEGACY_PACKAGE_ACCEPTANCE_COMPAT_MAX = { year: 2026, month: 4, day: 25 };
+const FORBIDDEN_LOCAL_BUILD_METADATA_FILES = new Set(LOCAL_BUILD_METADATA_DIST_PATHS);
 
 const LEGACY_OMITTED_PRIVATE_QA_INVENTORY_PREFIXES = [
   "dist/extensions/qa-channel/",
@@ -121,6 +123,11 @@ if (!entrySet.has("package.json")) {
 if (!normalized.some((entry) => entry.startsWith("dist/"))) {
   errors.push("missing dist/ entries");
 }
+for (const forbiddenEntry of FORBIDDEN_LOCAL_BUILD_METADATA_FILES) {
+  if (entrySet.has(forbiddenEntry)) {
+    errors.push(`forbidden local build metadata tar entry ${forbiddenEntry}`);
+  }
+}
 if (!entrySet.has("dist/postinstall-inventory.json")) {
   errors.push("missing dist/postinstall-inventory.json");
 }

scripts/lib/local-build-metadata-paths.d.mts

@@ -0,0 +1,7 @@
+export const BUILD_STAMP_FILE: ".buildstamp";
+export const RUNTIME_POSTBUILD_STAMP_FILE: ".runtime-postbuildstamp";
+export const LOCAL_BUILD_METADATA_DIST_PATHS: readonly [
+  "dist/.buildstamp",
+  "dist/.runtime-postbuildstamp",
+];
+export function isLocalBuildMetadataDistPath(relativePath: string): boolean;

scripts/lib/local-build-metadata-paths.mjs

@@ -0,0 +1,13 @@
+export const BUILD_STAMP_FILE = ".buildstamp";
+export const RUNTIME_POSTBUILD_STAMP_FILE = ".runtime-postbuildstamp";
+
+export const LOCAL_BUILD_METADATA_DIST_PATHS = Object.freeze([
+  `dist/${BUILD_STAMP_FILE}`,
+  `dist/${RUNTIME_POSTBUILD_STAMP_FILE}`,
+]);
+
+const LOCAL_BUILD_METADATA_DIST_PATH_SET = new Set(LOCAL_BUILD_METADATA_DIST_PATHS);
+
+export function isLocalBuildMetadataDistPath(relativePath) {
+  return LOCAL_BUILD_METADATA_DIST_PATH_SET.has(relativePath);
+}

scripts/lib/local-build-metadata.d.mts

@@ -0,0 +1,43 @@
+export {
+  BUILD_STAMP_FILE,
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  isLocalBuildMetadataDistPath,
+} from "./local-build-metadata-paths.mjs";
+
+export function resolveGitHead(params?: {
+  cwd?: string;
+  spawnSync?: (
+    cmd: string,
+    args: string[],
+    options: unknown,
+  ) => { status: number | null; stdout?: string | null };
+}): string | null;
+
+export function writeBuildStamp(params?: {
+  cwd?: string;
+  fs?: {
+    mkdirSync(path: string, options?: { recursive?: boolean }): void;
+    writeFileSync(path: string, data: string, encoding?: string): void;
+  };
+  now?: () => number;
+  spawnSync?: (
+    cmd: string,
+    args: string[],
+    options: unknown,
+  ) => { status: number | null; stdout?: string | null };
+}): string;
+
+export function writeRuntimePostBuildStamp(params?: {
+  cwd?: string;
+  fs?: {
+    mkdirSync(path: string, options?: { recursive?: boolean }): void;
+    writeFileSync(path: string, data: string, encoding?: string): void;
+  };
+  now?: () => number;
+  spawnSync?: (
+    cmd: string,
+    args: string[],
+    options: unknown,
+  ) => { status: number | null; stdout?: string | null };
+}): string;

scripts/lib/local-build-metadata.mjs

@@ -0,0 +1,79 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import {
+  BUILD_STAMP_FILE,
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  isLocalBuildMetadataDistPath,
+} from "./local-build-metadata-paths.mjs";
+
+export {
+  BUILD_STAMP_FILE,
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  isLocalBuildMetadataDistPath,
+};
+
+export function resolveGitHead(params = {}) {
+  const cwd = params.cwd ?? process.cwd();
+  const spawnSyncImpl = params.spawnSync ?? spawnSync;
+  try {
+    const result = spawnSyncImpl("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (result.status !== 0) {
+      return null;
+    }
+    const head = (result.stdout ?? "").trim();
+    return head || null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeBuildStamp(params = {}) {
+  const cwd = params.cwd ?? process.cwd();
+  const fsImpl = params.fs ?? fs;
+  const now = params.now ?? Date.now;
+  const distRoot = path.join(cwd, "dist");
+  const buildStampPath = path.join(distRoot, BUILD_STAMP_FILE);
+  const head = resolveGitHead({
+    cwd,
+    spawnSync: params.spawnSync,
+  });
+
+  fsImpl.mkdirSync(distRoot, { recursive: true });
+  fsImpl.writeFileSync(buildStampPath, `${JSON.stringify({ builtAt: now(), head })}\n`, "utf8");
+  return buildStampPath;
+}
+
+export function writeRuntimePostBuildStamp(params = {}) {
+  const cwd = params.cwd ?? process.cwd();
+  const fsImpl = params.fs ?? fs;
+  const now = params.now ?? Date.now;
+  const distRoot = path.join(cwd, "dist");
+  const stampPath = path.join(distRoot, RUNTIME_POSTBUILD_STAMP_FILE);
+  const head = resolveGitHead({
+    cwd,
+    spawnSync: params.spawnSync,
+  });
+
+  fsImpl.mkdirSync(distRoot, { recursive: true });
+  fsImpl.writeFileSync(
+    stampPath,
+    `${JSON.stringify(
+      {
+        syncedAt: now(),
+        ...(head ? { head } : {}),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  return stampPath;
+}

scripts/openclaw-cross-os-release-checks.ts

@@ -20,6 +20,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve, win32 as pathWin32 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { assertNoBundledRuntimeDepsStagingDebris } from "../src/infra/package-dist-inventory.ts";
+import { isLocalBuildMetadataDistPath } from "./lib/local-build-metadata-paths.mjs";
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PUBLISHED_INSTALLER_BASE_URL = "https://openclaw.ai";
@@ -479,6 +480,9 @@ function isPackagedDistPath(relativePath) {
   if (relativePath === PACKAGE_DIST_INVENTORY_RELATIVE_PATH) {
     return false;
   }
+  if (isLocalBuildMetadataDistPath(relativePath)) {
+    return false;
+  }
   if (relativePath.endsWith(".map")) {
     return false;
   }

scripts/openclaw-npm-release-check.ts

@@ -5,6 +5,7 @@ import { readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
+  LOCAL_BUILD_METADATA_DIST_PATHS,
   PACKAGE_DIST_INVENTORY_RELATIVE_PATH,
   writePackageDistInventory,
 } from "../src/infra/package-dist-inventory.ts";
@@ -69,6 +70,11 @@ const REQUIRED_PACKED_PATHS = [
 ];
 const CONTROL_UI_ASSET_PREFIX = "dist/control-ui/assets/";
 const FORBIDDEN_PACKED_PATH_RULES = [
+  ...LOCAL_BUILD_METADATA_DIST_PATHS.map((prefix) => ({
+    prefix,
+    describe: (packedPath: string) =>
+      `npm package must not include local build metadata "${packedPath}".`,
+  })),
   {
     prefix: "docs/.generated/",
     describe: (packedPath: string) =>

scripts/release-check.ts

@@ -16,6 +16,7 @@ import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
   isBundledRuntimeDepsInstallStagePath,
+  LOCAL_BUILD_METADATA_DIST_PATHS,
   PACKAGE_DIST_INVENTORY_RELATIVE_PATH,
   writePackageDistInventory,
 } from "../src/infra/package-dist-inventory.ts";
@@ -77,6 +78,7 @@ const requiredPathGroups = [
   "dist/control-ui/index.html",
 ];
 const forbiddenPrefixes = [
+  ...LOCAL_BUILD_METADATA_DIST_PATHS,
   "dist-runtime/",
   "dist/OpenClaw.app/",
   "dist/extensions/qa-channel/",

scripts/run-node.mjs

@@ -4,11 +4,17 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { pathToFileURL } from "node:url";
-import { resolveGitHead, writeBuildStamp as writeDistBuildStamp } from "./build-stamp.mjs";
 import {
   BUNDLED_PLUGIN_PATH_PREFIX,
   BUNDLED_PLUGIN_ROOT_DIR,
 } from "./lib/bundled-plugin-paths.mjs";
+import {
+  BUILD_STAMP_FILE,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  resolveGitHead,
+  writeBuildStamp as writeDistBuildStamp,
+  writeRuntimePostBuildStamp as writeDistRuntimePostBuildStamp,
+} from "./lib/local-build-metadata.mjs";
 import { runRuntimePostBuild } from "./runtime-postbuild.mjs";
 
 const buildScript = "scripts/tsdown-build.mjs";
@@ -17,12 +23,14 @@ const compilerArgs = [buildScript, "--no-clean"];
 const runNodeSourceRoots = ["src", BUNDLED_PLUGIN_ROOT_DIR];
 const runNodeConfigFiles = ["tsconfig.json", "package.json", "tsdown.config.ts"];
 export const runNodeWatchedPaths = [...runNodeSourceRoots, ...runNodeConfigFiles];
-const runtimePostBuildStampFile = ".runtime-postbuildstamp";
 const runtimePostBuildWatchedPaths = [
   "scripts/copy-bundled-plugin-metadata.mjs",
   "scripts/copy-plugin-sdk-root-alias.mjs",
   "scripts/lib",
+  "scripts/lib/local-build-metadata.mjs",
+  "scripts/lib/local-build-metadata-paths.mjs",
   "scripts/npm-runner.mjs",
+  "scripts/runtime-postbuild-stamp.mjs",
   "scripts/runtime-postbuild-shared.mjs",
   "scripts/runtime-postbuild.mjs",
   "scripts/stage-bundled-plugin-runtime-deps.mjs",
@@ -756,20 +764,11 @@ const syncRuntimeArtifacts = async (deps) => {
 
 const writeRuntimePostBuildStamp = (deps) => {
   try {
-    deps.fs.mkdirSync(path.dirname(deps.runtimePostBuildStampPath), { recursive: true });
-    const head = resolveGitHead(deps);
-    deps.fs.writeFileSync(
-      deps.runtimePostBuildStampPath,
-      `${JSON.stringify(
-        {
-          syncedAt: Date.now(),
-          ...(head ? { head } : {}),
-        },
-        null,
-        2,
-      )}\n`,
-      "utf8",
-    );
+    writeDistRuntimePostBuildStamp({
+      cwd: deps.cwd,
+      fs: deps.fs,
+      spawnSync: deps.spawnSync,
+    });
   } catch (error) {
     logRunner(
       `Failed to write runtime postbuild stamp: ${error?.message ?? "unknown error"}`,
@@ -827,8 +826,8 @@ export async function runNodeMain(params = {}) {
 
   deps.distRoot = path.join(deps.cwd, "dist");
   deps.distEntry = path.join(deps.distRoot, "/entry.js");
-  deps.buildStampPath = path.join(deps.distRoot, ".buildstamp");
-  deps.runtimePostBuildStampPath = path.join(deps.distRoot, runtimePostBuildStampFile);
+  deps.buildStampPath = path.join(deps.distRoot, BUILD_STAMP_FILE);
+  deps.runtimePostBuildStampPath = path.join(deps.distRoot, RUNTIME_POSTBUILD_STAMP_FILE);
   deps.sourceRoots = runNodeSourceRoots.map((sourceRoot) => ({
     name: sourceRoot,
     path: path.join(deps.cwd, sourceRoot),

scripts/runtime-postbuild-stamp.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { writeRuntimePostBuildStamp } from "./lib/local-build-metadata.mjs";
+
+export {
+  RUNTIME_POSTBUILD_STAMP_FILE,
+  writeRuntimePostBuildStamp,
+} from "./lib/local-build-metadata.mjs";
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  try {
+    writeRuntimePostBuildStamp();
+  } catch (error) {
+    console.error(error);
+    process.exit(1);
+  }
+}