openclaw
diff --git a/‎scripts/AGENTS.md‎
Lines changed: 5 additions & 0 deletions b/‎scripts/AGENTS.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎scripts/pr-gates-lock.mjs‎
Lines changed: 75 additions & 0 deletions b/‎scripts/pr-gates-lock.mjs‎
Lines changed: 75 additions & 0 deletions
@@ -18,6 +18,11 @@ This directory owns local tooling, script wrappers, and generated-artifact helpe
 - Metadata-only or explicitly narrow commands may skip the lock when the existing helper logic says that is safe.
 - If you change the lock heuristics, add or update the narrow tests under `test/scripts/`.
 
+## PR Prepare Gates
+
+- `scripts/pr prepare-gates` holds the heavy-check lock for its whole local gate block (`scripts/pr-gates-lock.mjs`), so concurrent gate runs across `.worktrees` queue as units instead of dying on child lock timeouts or vitest no-output watchdog kills.
+- `OPENCLAW_PR_GATES_REMOTE=testbox` runs the full-suite `pnpm test` gate on a Blacksmith Testbox through `scripts/crabbox-wrapper.mjs` (same delegation as `check:changed`); `pnpm build`/`pnpm check` stay local. The `tbx_` lease id and Actions run URL land in `.local/gates.env` (`REMOTE_GATES_*`) and `.local/prep.md`. Use it for reviewed trusted code when a loaded host makes the local 88-shard run stall-kill; contributor/fork code stays on secretless CI or sanitized AWS unless a maintainer explicitly approves credentialed execution.
+
 ## Generated Outputs
 
 - If a script writes generated artifacts, keep the source-of-truth generator, the package script, and the matching verification/check command aligned.
 
@@ -0,0 +1,75 @@
+// Holds the shared local heavy-check lock for a whole scripts/pr gate block so
+// concurrent gate runs across .worktrees serialize before their first command
+// instead of dying mid-test on child lock timeouts or no-output watchdog kills.
+import fs from "node:fs";
+import {
+  acquireLocalHeavyCheckLockSync,
+  resolveLocalHeavyCheckEnv,
+} from "./lib/local-heavy-check-runtime.mjs";
+
+// A queued gate block legitimately waits out another full gate run; the
+// 10-minute per-command default in the lock runtime is far too short for that.
+const DEFAULT_GATE_LOCK_TIMEOUT_MS = 2 * 60 * 60 * 1000;
+const PARENT_WATCH_INTERVAL_MS = 2_000;
+
+function parseArgs(argv) {
+  const args = { statusFile: "" };
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--status-file") {
+      args.statusFile = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${argv[index]}`);
+  }
+  if (!args.statusFile) {
+    throw new Error("Usage: node scripts/pr-gates-lock.mjs --status-file <path>");
+  }
+  return args;
+}
+
+function main() {
+  const { statusFile } = parseArgs(process.argv.slice(2));
+  const baseEnv = resolveLocalHeavyCheckEnv(process.env);
+  const env = baseEnv.OPENCLAW_HEAVY_CHECK_LOCK_TIMEOUT_MS
+    ? baseEnv
+    : { ...baseEnv, OPENCLAW_HEAVY_CHECK_LOCK_TIMEOUT_MS: String(DEFAULT_GATE_LOCK_TIMEOUT_MS) };
+
+  const parentPid = process.ppid;
+  const release = acquireLocalHeavyCheckLockSync({
+    cwd: process.cwd(),
+    env,
+    toolName: "pr-gates",
+  });
+  let released = false;
+  const releaseOnce = () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    release();
+  };
+
+  process.on("exit", releaseOnce);
+  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => {
+      releaseOnce();
+      process.exit(0);
+    });
+  }
+
+  fs.writeFileSync(statusFile, "acquired\n");
+
+  // The owner-pid reclaim in the lock runtime already covers a SIGKILLed
+  // holder; this watch releases promptly when the gate shell dies mid-block.
+  // ppid 1 also counts as dead: orphans reparent to init/launchd, and a
+  // helper that started orphaned has no gate block to hold the lock for.
+  setInterval(() => {
+    if (process.ppid !== parentPid || process.ppid === 1) {
+      releaseOnce();
+      process.exit(0);
+    }
+  }, PARENT_WATCH_INTERVAL_MS);
+}
+
+main();