fix(build): stamp runtime postbuild artifacts

test/helpers/gateway-e2e-harness.ts

@@ -5,6 +5,10 @@ import { request as httpRequest } from "node:http";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
+import {
+  BUILD_STAMP_FILE,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+} from "../../scripts/lib/local-build-metadata-paths.mjs";
 import { GatewayClient } from "../../src/gateway/client.js";
 import { connectGatewayClient } from "../../src/gateway/test-helpers.e2e.js";
 import { loadOrCreateDeviceIdentity } from "../../src/infra/device-identity.js";
@@ -46,8 +50,8 @@ const GATEWAY_ENTRYPOINT_PREPARE_TIMEOUT_MS = 120_000;
 let gatewayEntrypointPromise: Promise<string[]> | null = null;
 
 async function resolveBuiltGatewayEntrypoint(cwd: string): Promise<string[] | null> {
-  const buildStampPath = path.join(cwd, "dist", ".buildstamp");
-  const runtimePostBuildStampPath = path.join(cwd, "dist", ".runtime-postbuildstamp");
+  const buildStampPath = path.join(cwd, "dist", BUILD_STAMP_FILE);
+  const runtimePostBuildStampPath = path.join(cwd, "dist", RUNTIME_POSTBUILD_STAMP_FILE);
   for (const entrypoint of ["dist/index.js", "dist/index.mjs"]) {
     try {
       await Promise.all([

test/openclaw-npm-release-check.test.ts

@@ -20,7 +20,10 @@ import {
   shouldSkipPackedTarballValidation,
   utcCalendarDayDistance,
 } from "../scripts/openclaw-npm-release-check.ts";
-import { PACKAGE_DIST_INVENTORY_RELATIVE_PATH } from "../src/infra/package-dist-inventory.ts";
+import {
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  PACKAGE_DIST_INVENTORY_RELATIVE_PATH,
+} from "../src/infra/package-dist-inventory.ts";
 
 const REQUIRED_PACKED_PATHS = [
   PACKAGE_DIST_INVENTORY_RELATIVE_PATH,
@@ -326,6 +329,15 @@ describe("collectForbiddenPackedPathErrors", () => {
     ]);
   });
 
+  it("rejects local build metadata in npm pack output", () => {
+    expect(
+      collectForbiddenPackedPathErrors(["dist/index.js", ...LOCAL_BUILD_METADATA_DIST_PATHS]),
+    ).toEqual([
+      'npm package must not include local build metadata "dist/.buildstamp".',
+      'npm package must not include local build metadata "dist/.runtime-postbuildstamp".',
+    ]);
+  });
+
   it("rejects private qa artifacts in npm pack output", () => {
     expect(
       collectForbiddenPackedPathErrors([

test/release-check.test.ts

@@ -1,4 +1,4 @@
-import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { bundledDistPluginFile, bundledPluginFile } from "openclaw/plugin-sdk/test-fixtures";
@@ -24,7 +24,10 @@ import {
   packageNameFromSpecifier,
   resolveMissingPackBuildHint,
 } from "../scripts/release-check.ts";
-import { PACKAGE_DIST_INVENTORY_RELATIVE_PATH } from "../src/infra/package-dist-inventory.ts";
+import {
+  LOCAL_BUILD_METADATA_DIST_PATHS,
+  PACKAGE_DIST_INVENTORY_RELATIVE_PATH,
+} from "../src/infra/package-dist-inventory.ts";
 
 function makeItem(shortVersion: string, sparkleVersion: string): string {
   return `<item><title>${shortVersion}</title><sparkle:shortVersionString>${shortVersion}</sparkle:shortVersionString><sparkle:version>${sparkleVersion}</sparkle:version></item>`;
@@ -433,6 +436,19 @@ describe("collectForbiddenPackPaths", () => {
     ]);
   });
 
+  it("blocks local build metadata from npm pack output", () => {
+    expect(
+      collectForbiddenPackPaths(["dist/index.js", ...LOCAL_BUILD_METADATA_DIST_PATHS]),
+    ).toEqual([...LOCAL_BUILD_METADATA_DIST_PATHS]);
+  });
+
+  it("keeps local build metadata excluded by package files", () => {
+    const pkg = JSON.parse(readFileSync("package.json", "utf8")) as { files?: string[] };
+    expect(pkg.files).toEqual(
+      expect.arrayContaining(LOCAL_BUILD_METADATA_DIST_PATHS.map((entry) => `!${entry}`)),
+    );
+  });
+
   it("blocks legacy runtime dependency stamps from npm pack output", () => {
     expect(
       collectForbiddenPackPaths([

test/scripts/build-all.test.ts

@@ -134,6 +134,7 @@ describe("resolveBuildAllSteps", () => {
       "check-cli-bootstrap-imports",
       "runtime-postbuild",
       "build-stamp",
+      "runtime-postbuild-stamp",
       "build:plugin-sdk:dts",
       "write-plugin-sdk-entry-dts",
       "check-plugin-sdk-exports",
@@ -152,9 +153,20 @@ describe("resolveBuildAllSteps", () => {
       "check-cli-bootstrap-imports",
       "runtime-postbuild",
       "build-stamp",
+      "runtime-postbuild-stamp",
     ]);
   });
 
+  it("writes the runtime postbuild stamp after the build stamp", () => {
+    expect(resolveBuildAllSteps("full").map((step) => step.label)).toEqual(
+      expect.arrayContaining(["runtime-postbuild", "build-stamp", "runtime-postbuild-stamp"]),
+    );
+    const labels = resolveBuildAllSteps("full").map((step) => step.label);
+    expect(labels.indexOf("runtime-postbuild-stamp")).toBeGreaterThan(
+      labels.indexOf("build-stamp"),
+    );
+  });
+
   it("does not cache plugin-sdk entry shims over compiled JS", () => {
     const step = BUILD_ALL_STEPS.find((entry) => entry.label === "write-plugin-sdk-entry-dts");
     expect(step).toBeTruthy();

test/scripts/check-gateway-watch-regression.test.ts

@@ -1,9 +1,17 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   hasGatewayReadyLog,
   isIgnoredDistRuntimeWatchPath,
   shouldRefreshBuildStampForRestoredArtifacts,
+  writeBuildAndRuntimePostBuildStamps,
 } from "../../scripts/check-gateway-watch-regression.mjs";
+import {
+  BUILD_STAMP_FILE,
+  RUNTIME_POSTBUILD_STAMP_FILE,
+} from "../../scripts/lib/local-build-metadata-paths.mjs";
 
 describe("check-gateway-watch-regression", () => {
   it("ignores top-level dist-runtime extension dependency repairs", () => {
@@ -50,4 +58,22 @@ describe("check-gateway-watch-regression", () => {
       }),
     ).toBe(false);
   });
+
+  it("refreshes runtime postbuild stamps after build stamps", () => {
+    const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-gateway-watch-stamps-"));
+    try {
+      fs.mkdirSync(path.join(rootDir, ".git"), { recursive: true });
+      writeBuildAndRuntimePostBuildStamps({ cwd: rootDir });
+
+      const buildStampPath = path.join(rootDir, "dist", BUILD_STAMP_FILE);
+      const runtimeStampPath = path.join(rootDir, "dist", RUNTIME_POSTBUILD_STAMP_FILE);
+      expect(fs.existsSync(buildStampPath)).toBe(true);
+      expect(fs.existsSync(runtimeStampPath)).toBe(true);
+      expect(fs.statSync(runtimeStampPath).mtimeMs).toBeGreaterThanOrEqual(
+        fs.statSync(buildStampPath).mtimeMs,
+      );
+    } finally {
+      fs.rmSync(rootDir, { recursive: true, force: true });
+    }
+  });
 });

test/scripts/check-openclaw-package-tarball.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
+import { LOCAL_BUILD_METADATA_DIST_PATHS } from "../../scripts/lib/local-build-metadata-paths.mjs";
 
 const CHECK_SCRIPT = "scripts/check-openclaw-package-tarball.mjs";
 
@@ -83,4 +84,25 @@ describe("check-openclaw-package-tarball", () => {
       },
     );
   });
+
+  it("rejects local build metadata entries in package tarballs", () => {
+    withTarball(
+      ["dist/index.js", ...LOCAL_BUILD_METADATA_DIST_PATHS],
+      {
+        "dist/index.js": "export {};\n",
+        ...Object.fromEntries(LOCAL_BUILD_METADATA_DIST_PATHS.map((entry) => [entry, "{}\n"])),
+      },
+      (tarball) => {
+        const result = spawnSync("node", [CHECK_SCRIPT, tarball], { encoding: "utf8" });
+
+        expect(result.status).not.toBe(0);
+        expect(result.stderr).toContain(
+          "forbidden local build metadata tar entry dist/.buildstamp",
+        );
+        expect(result.stderr).toContain(
+          "forbidden local build metadata tar entry dist/.runtime-postbuildstamp",
+        );
+      },
+    );
+  });
 });

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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { describe, expect, it } from "vitest";
+import { LOCAL_BUILD_METADATA_DIST_PATHS } from "../../scripts/lib/local-build-metadata-paths.mjs";
 import {
   agentOutputHasExpectedOkMarker,
   buildReleaseOnboardArgs,
@@ -541,6 +542,33 @@ describe("scripts/openclaw-cross-os-release-checks", () => {
     }
   });
 
+  it("omits local build metadata from candidate package inventories", async () => {
+    const packageRoot = mkdtempSync(join(tmpdir(), "openclaw-cross-os-local-stamps-"));
+    try {
+      mkdirSync(join(packageRoot, "dist"), { recursive: true });
+      writeFileSync(
+        join(packageRoot, "package.json"),
+        JSON.stringify({ name: "openclaw-fixture", version: "0.0.0", files: ["dist/"] }),
+        "utf8",
+      );
+      writeFileSync(join(packageRoot, "dist", "index.js"), "export {};\n", "utf8");
+      for (const relativePath of LOCAL_BUILD_METADATA_DIST_PATHS) {
+        writeFileSync(join(packageRoot, relativePath), "{}\n", "utf8");
+      }
+
+      await writePackageDistInventoryForCandidate({
+        sourceDir: packageRoot,
+        logPath: join(packageRoot, "npm-pack-dry-run.log"),
+      });
+
+      expect(
+        JSON.parse(readFileSync(join(packageRoot, "dist", "postinstall-inventory.json"), "utf8")),
+      ).toEqual(["dist/index.js"]);
+    } finally {
+      rmSync(packageRoot, { recursive: true, force: true });
+    }
+  });
+
   it("accepts a git main dev-channel update status payload", () => {
     expect(() =>
       verifyDevUpdateStatus(

test/scripts/runtime-postbuild-stamp.test.ts

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { RUNTIME_POSTBUILD_STAMP_FILE } from "../../scripts/lib/local-build-metadata-paths.mjs";
+import { writeRuntimePostBuildStamp } from "../../scripts/runtime-postbuild-stamp.mjs";
+
+describe("runtime-postbuild-stamp script", () => {
+  it("writes dist/.runtime-postbuildstamp with the current git head", () => {
+    const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-runtime-postbuild-stamp-"));
+    try {
+      const stampPath = writeRuntimePostBuildStamp({
+        cwd: rootDir,
+        now: () => 123,
+        spawnSync: () => ({ status: 0, stdout: "abc123\n" }),
+      });
+
+      expect(path.relative(rootDir, stampPath)).toBe(
+        path.join("dist", RUNTIME_POSTBUILD_STAMP_FILE),
+      );
+      expect(JSON.parse(fs.readFileSync(stampPath, "utf8"))).toEqual({
+        syncedAt: 123,
+        head: "abc123",
+      });
+    } finally {
+      fs.rmSync(rootDir, { recursive: true, force: true });
+    }
+  });
+});