@askexenow/exe-os 0.9.348 → 0.9.350

package/dist/{stack-release-HGFFFCGC.js → stack-release-NUITUMB4.js}

@@ -1,49 +1,181 @@
 #!/usr/bin/env node
+import {
+  writeSignedStackManifest
+} from "./chunk-HCRUMO4B.js";
+import "./chunk-KZ7BANUM.js";
 import {
   assertPreflightGate,
   runPreflightOnManifest
 } from "./chunk-3QWOO74G.js";
+import "./chunk-JO6RMHMW.js";
+import "./chunk-IMGD6PW3.js";
+import "./chunk-BCZF3AGJ.js";
+import "./chunk-HSGBZSCA.js";
 import "./chunk-MLKGABMK.js";
 
 // src/bin/stack-release.ts
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "fs";
 import { execFile as execFileCb } from "child_process";
 import { promisify } from "util";
-import path from "path";
+import path2 from "path";
 import { createInterface } from "readline";
+
+// src/lib/release-lock.ts
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { homedir, hostname as osHostname } from "os";
+import path from "path";
+import process2 from "process";
+var DEFAULT_RELEASE_LOCK_TTL_MS = 2 * 60 * 60 * 1e3;
+function defaultReleaseLockPath() {
+  return path.join(homedir(), ".exe-os", "release.lock");
+}
+function defaultIsPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process2.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
+    return code === "EPERM";
+  }
+}
+function readLock(lockPath) {
+  const raw = readFileSync(lockPath, "utf8");
+  const parsed = JSON.parse(raw);
+  if (typeof parsed.pid !== "number" || typeof parsed.startedAt !== "string" || typeof parsed.targetVersion !== "string" || typeof parsed.branch !== "string" || typeof parsed.hostname !== "string") {
+    throw new Error("lock file is missing required fields");
+  }
+  return parsed;
+}
+function writeLockAtomic(lockPath, lock) {
+  mkdirSync(path.dirname(lockPath), { recursive: true });
+  const fd = openSync(lockPath, "wx", 384);
+  try {
+    writeFileSync(fd, JSON.stringify(lock, null, 2) + "\n", "utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+function sameLock(a, b) {
+  return a.pid === b.pid && a.startedAt === b.startedAt && a.targetVersion === b.targetVersion && a.branch === b.branch && a.hostname === b.hostname;
+}
+function acquireReleaseLock(opts) {
+  const lockPath = opts.lockPath ?? defaultReleaseLockPath();
+  const ttlMs = opts.ttlMs ?? DEFAULT_RELEASE_LOCK_TTL_MS;
+  const now = opts.now ?? /* @__PURE__ */ new Date();
+  const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
+  const logNote = opts.log ?? (() => {
+  });
+  if (existsSync(lockPath)) {
+    let existing = null;
+    try {
+      existing = readLock(lockPath);
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      if (!opts.force) {
+        throw new Error(
+          `release lock exists but cannot be read safely (${detail}); re-run with --force to override: ${lockPath}`
+        );
+      }
+      unlinkSync(lockPath);
+      logNote(`release lock force-cleared unreadable lock at ${lockPath}`);
+    }
+    if (existing) {
+      const startedMs = Date.parse(existing.startedAt);
+      if (!Number.isFinite(startedMs) && !opts.force) {
+        throw new Error(
+          `release lock exists with an invalid timestamp (${existing.startedAt}); re-run with --force to override: ${lockPath}`
+        );
+      }
+      const ageMs = Number.isFinite(startedMs) ? now.getTime() - startedMs : Number.POSITIVE_INFINITY;
+      const pidAlive = isPidAlive(existing.pid);
+      const fresh = ageMs < ttlMs && pidAlive;
+      if (fresh && !opts.force) {
+        throw new Error(
+          `release already in progress: pid ${existing.pid} started ${existing.startedAt}; re-run with --force to override`
+        );
+      }
+      unlinkSync(lockPath);
+      if (fresh) {
+        logNote(`release lock force-cleared: pid ${existing.pid} started ${existing.startedAt}`);
+      } else {
+        const reason = !pidAlive ? "pid is not alive" : `older than ${Math.round(ttlMs / 6e4)}m TTL`;
+        logNote(`stale release lock cleared: pid ${existing.pid} started ${existing.startedAt} (${reason})`);
+      }
+    }
+  }
+  const lock = {
+    pid: opts.pid ?? process2.pid,
+    startedAt: now.toISOString(),
+    targetVersion: opts.targetVersion,
+    branch: opts.branch,
+    hostname: opts.hostname ?? osHostname()
+  };
+  try {
+    writeLockAtomic(lockPath, lock);
+  } catch (err) {
+    const code = err && typeof err === "object" && "code" in err ? String(err.code) : "";
+    if (code === "EEXIST") {
+      throw new Error(`release lock was acquired by another process; re-run when it completes: ${lockPath}`);
+    }
+    throw err;
+  }
+  return {
+    lockPath,
+    lock,
+    release: () => {
+      if (!existsSync(lockPath)) return;
+      try {
+        const current = readLock(lockPath);
+        if (sameLock(current, lock)) unlinkSync(lockPath);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/bin/stack-release.ts
 var execFile = promisify(execFileCb);
 function findExeOsRoot() {
   const envRoot = process.env.EXE_OS_ROOT;
-  if (envRoot && existsSync(envRoot)) return path.resolve(envRoot);
-  let dir = path.dirname(new URL(import.meta.url).pathname);
+  if (envRoot && existsSync2(envRoot)) return path2.resolve(envRoot);
+  let dir = path2.dirname(new URL(import.meta.url).pathname);
   for (let i = 0; i < 5; i++) {
-    const pkgPath = path.join(dir, "package.json");
-    if (existsSync(pkgPath)) {
+    const pkgPath = path2.join(dir, "package.json");
+    if (existsSync2(pkgPath)) {
       try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
         if (pkg.name === "@askexenow/exe-os") return dir;
       } catch {
       }
     }
-    dir = path.dirname(dir);
+    dir = path2.dirname(dir);
   }
-  return path.resolve(path.dirname(new URL(import.meta.url).pathname), "..", "..");
+  return path2.resolve(path2.dirname(new URL(import.meta.url).pathname), "..", "..");
 }
 var EXE_OS_ROOT = findExeOsRoot();
-var PARENT_DIR = path.dirname(EXE_OS_ROOT);
-var MANIFEST_PATH = path.join(EXE_OS_ROOT, "deploy", "stack-manifests", "v0.9.json");
+var PARENT_DIR = path2.dirname(EXE_OS_ROOT);
+var MANIFEST_PATH = path2.join(EXE_OS_ROOT, "deploy", "stack-manifests", "v0.9.json");
 function applyRootOverride(rootPath) {
-  const resolved = path.resolve(rootPath);
-  if (!existsSync(resolved)) {
+  const resolved = path2.resolve(rootPath);
+  if (!existsSync2(resolved)) {
     throw new Error(`--root path does not exist: ${resolved}`);
   }
   EXE_OS_ROOT = resolved;
-  PARENT_DIR = path.dirname(EXE_OS_ROOT);
-  MANIFEST_PATH = path.join(EXE_OS_ROOT, "deploy", "stack-manifests", "v0.9.json");
+  PARENT_DIR = path2.dirname(EXE_OS_ROOT);
+  MANIFEST_PATH = path2.join(EXE_OS_ROOT, "deploy", "stack-manifests", "v0.9.json");
 }
 function resolveRepoPath(dirName) {
-  const direct = path.join(PARENT_DIR, dirName);
-  if (existsSync(direct)) return direct;
+  const direct = path2.join(PARENT_DIR, dirName);
+  if (existsSync2(direct)) return direct;
   const aliases = {
     "exe-crm": ["openclaw", "exe-crm"],
     "exe-wiki": ["ink", "exe-wiki"]
@@ -51,8 +183,8 @@ function resolveRepoPath(dirName) {
   const candidates = aliases[dirName];
   if (candidates) {
     for (const alias of candidates) {
-      const p = path.join(PARENT_DIR, alias);
-      if (existsSync(p)) return p;
+      const p = path2.join(PARENT_DIR, alias);
+      if (existsSync2(p)) return p;
     }
   }
   return direct;
@@ -146,7 +278,8 @@ function parseReleaseArgs(argv) {
     root: null,
     forceBuild: false,
     canary: false,
-    allowDirty: false
+    allowDirty: false,
+    force: false
   };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -159,6 +292,7 @@ function parseReleaseArgs(argv) {
     else if (arg === "--allow-red") flags.allowRed = true;
     else if (arg === "--allow-dirty") flags.allowDirty = true;
     else if (arg === "--canary") flags.canary = true;
+    else if (arg === "--force") flags.force = true;
     else if (arg === "--repos" && argv[i + 1]) {
       flags.repos = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg.startsWith("--repos=")) {
@@ -167,7 +301,7 @@ function parseReleaseArgs(argv) {
       flags.root = argv[++i];
     } else if (arg.startsWith("--root=")) {
       flags.root = arg.slice("--root=".length);
-    } else if (arg === "--force" || arg === "--force-build") {
+    } else if (arg === "--force-build") {
       flags.forceBuild = true;
     }
   }
@@ -214,6 +348,61 @@ async function ghRun(args) {
   const { stdout } = await execFile("gh", args);
   return stdout.trim();
 }
+async function assertReleaseFreshness(opts) {
+  const runGit = opts.gitRunner ?? git;
+  const logFn = opts.log ?? log;
+  const originRef = `origin/${opts.defaultBranch}`;
+  logFn("info", `Freshness gate: fetching origin ${opts.defaultBranch} before publish...`);
+  await runGit(opts.repoPath, "fetch", "origin", opts.defaultBranch);
+  const missing = (await runGit(opts.repoPath, "log", `${opts.releaseCommit}..${originRef}`, "--oneline")).trim();
+  if (missing) {
+    throw new Error(
+      `Freshness gate failed: ${originRef} contains commits not included in release commit ${opts.releaseCommit}.
+Missing-PR list:
+${missing}
+Abort: rebase/re-cut the release from current ${originRef} before publishing.`
+    );
+  }
+  try {
+    await runGit(opts.repoPath, "merge-base", "--is-ancestor", originRef, opts.releaseCommit);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `Freshness gate failed: release commit ${opts.releaseCommit} is not a descendant of ${originRef}. Abort: rebase/re-cut the release from current ${originRef} before publishing. (${detail})`
+    );
+  }
+  logFn("ok", `Freshness gate passed: release commit contains current ${originRef}`);
+}
+async function printOpenPrGate(opts) {
+  const baseBranch = opts.baseBranch ?? "main";
+  const runGh = opts.ghRunner ?? ghRun;
+  const logFn = opts.log ?? log;
+  try {
+    const output = await runGh([
+      "pr",
+      "list",
+      "--repo",
+      opts.ghRepo,
+      "--base",
+      baseBranch,
+      "--json",
+      "number,title"
+    ]);
+    const prs = JSON.parse(output);
+    if (prs.length === 0) {
+      logFn("info", `Open PR gate: no open PRs targeting ${baseBranch} in ${opts.ghRepo}`);
+      return;
+    }
+    logFn("warn", `Open PR gate: ${prs.length} open PR(s) targeting ${baseBranch} in ${opts.ghRepo}:`);
+    for (const pr of prs) {
+      const number = typeof pr.number === "number" ? `#${pr.number}` : "#?";
+      logFn("warn", `  ${number} ${pr.title ?? "(untitled)"}`);
+    }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    logFn("warn", `Open PR gate: unable to list open PRs for ${opts.ghRepo} targeting ${baseBranch}; continuing (${detail})`);
+  }
+}
 function bumpVersion(version, mode) {
   const parts = version.split(".").map(Number);
   if (parts.length < 3) throw new Error(`Invalid version: ${version}`);
@@ -229,16 +418,16 @@ function bumpVersion(version, mode) {
   }
 }
 function readPackageVersion(repoPath) {
-  const pkgPath = path.join(repoPath, "package.json");
-  if (!existsSync(pkgPath)) {
+  const pkgPath = path2.join(repoPath, "package.json");
+  if (!existsSync2(pkgPath)) {
     throw new Error(`Missing package.json at ${pkgPath}`);
   }
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
   return pkg.version;
 }
 function readPackageVersionOrNull(repoPath) {
-  const pkgPath = path.join(repoPath, "package.json");
-  if (!existsSync(pkgPath)) return null;
+  const pkgPath = path2.join(repoPath, "package.json");
+  if (!existsSync2(pkgPath)) return null;
   return readPackageVersion(repoPath);
 }
 function repoName(repo) {
@@ -251,15 +440,15 @@ function warnMissingRepoPackage(repo) {
   );
 }
 function hasPackageJson(repo) {
-  return existsSync(path.join(repo.localPath, "package.json"));
+  return existsSync2(path2.join(repo.localPath, "package.json"));
 }
 function deriveCloneUrl(repo) {
   return `https://github.com/${repo.ghRepo}.git`;
 }
 function isCloneTargetSafe(targetPath, parentDir) {
-  const resolvedParent = path.resolve(parentDir);
-  const resolvedTarget = path.resolve(targetPath);
-  return resolvedTarget === resolvedParent || resolvedTarget.startsWith(resolvedParent + path.sep);
+  const resolvedParent = path2.resolve(parentDir);
+  const resolvedTarget = path2.resolve(targetPath);
+  return resolvedTarget === resolvedParent || resolvedTarget.startsWith(resolvedParent + path2.sep);
 }
 var defaultCloneRunner = async (url, targetPath) => {
   await execFile("git", ["clone", url, targetPath]);
@@ -284,9 +473,9 @@ async function ensureRepoCloned(repo, parentDir = PARENT_DIR, runClone = default
   return true;
 }
 function readStackReleaseJson(repoPath) {
-  const p = path.join(repoPath, "stack.release.json");
-  if (!existsSync(p)) return null;
-  return JSON.parse(readFileSync(p, "utf8"));
+  const p = path2.join(repoPath, "stack.release.json");
+  if (!existsSync2(p)) return null;
+  return JSON.parse(readFileSync2(p, "utf8"));
 }
 async function detectChanges(repos) {
   const changes = [];
@@ -338,10 +527,10 @@ async function bumpVersions(changes, mode, dryRun) {
       log("dry", `${change.repo.serviceKey}: ${change.currentVersion} -> ${newVersion}`);
       continue;
     }
-    const pkgPath = path.join(change.repo.localPath, "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const pkgPath = path2.join(change.repo.localPath, "package.json");
+    const pkg = JSON.parse(readFileSync2(pkgPath, "utf8"));
     pkg.version = newVersion;
-    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+    writeFileSync2(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
     const srf = readStackReleaseJson(change.repo.localPath);
     if (srf) {
       srf.version = newVersion;
@@ -363,8 +552,8 @@ async function bumpVersions(changes, mode, dryRun) {
           }
         }
       }
-      writeFileSync(
-        path.join(change.repo.localPath, "stack.release.json"),
+      writeFileSync2(
+        path2.join(change.repo.localPath, "stack.release.json"),
         JSON.stringify(srf, null, 2) + "\n"
       );
     }
@@ -374,6 +563,7 @@ async function bumpVersions(changes, mode, dryRun) {
   }
 }
 async function landViaPR(repoPath, ghRepo, defaultBranch, branch, title) {
+  const pushedSha = await git(repoPath, "rev-parse", "HEAD");
   await git(repoPath, "push", "--force-with-lease", "origin", `HEAD:refs/heads/${branch}`);
   try {
     await ghRun([
@@ -392,13 +582,41 @@ async function landViaPR(repoPath, ghRepo, defaultBranch, branch, title) {
     ]);
   } catch {
   }
-  await ghRun(["pr", "merge", branch, "--repo", ghRepo, "--auto", "--squash"]);
   const deadline = Date.now() + 30 * 60 * 1e3;
+  let releasePr;
+  for (; ; ) {
+    try {
+      const output = await ghRun([
+        "pr",
+        "list",
+        "--repo",
+        ghRepo,
+        "--head",
+        branch,
+        "--state",
+        "all",
+        "--json",
+        "number,state,headRefOid"
+      ]);
+      releasePr = findPullRequestForHeadSha(JSON.parse(output), pushedSha);
+    } catch {
+    }
+    if (releasePr) break;
+    if (Date.now() > deadline) {
+      throw new Error(
+        `No PR on ${ghRepo} (${branch}) matches released commit ${pushedSha.slice(0, 12)} within 30m \u2014 failing closed rather than attributing another PR's verdict. Aborting release; ${defaultBranch} left untouched.`
+      );
+    }
+    await sleep(15e3);
+  }
+  if (releasePr.state !== "MERGED") {
+    await ghRun(["pr", "merge", String(releasePr.number), "--repo", ghRepo, "--auto", "--squash"]);
+  }
   for (; ; ) {
     const state = (await ghRun([
       "pr",
       "view",
-      branch,
+      String(releasePr.number),
       "--repo",
       ghRepo,
       "--json",
@@ -409,10 +627,10 @@ async function landViaPR(repoPath, ghRepo, defaultBranch, branch, title) {
     if (state === "MERGED") break;
     if (Date.now() > deadline) {
       throw new Error(
-        `Release PR ${ghRepo} (${branch}) did not merge within 30m \u2014 required CI likely red. Aborting release; ${defaultBranch} left untouched.`
+        `Release PR ${ghRepo}#${releasePr.number} (${branch} @ ${pushedSha.slice(0, 12)}) did not merge within 30m \u2014 required CI likely red. Aborting release; ${defaultBranch} left untouched.`
       );
     }
-    await new Promise((r) => setTimeout(r, 3e4));
+    await sleep(3e4);
   }
   await git(repoPath, "fetch", "origin", defaultBranch);
   await git(repoPath, "checkout", defaultBranch);
@@ -432,9 +650,16 @@ async function tagAndTriggerCI(changes, dryRun) {
       branch,
       `chore: bump ${change.tag} for stack release`
     );
+    change.releaseSha = await git(change.repo.localPath, "rev-parse", "HEAD");
+    await assertReleaseFreshness({
+      repoPath: change.repo.localPath,
+      defaultBranch: change.repo.defaultBranch,
+      releaseCommit: change.releaseSha
+    });
+    await printOpenPrGate({ ghRepo: change.repo.ghRepo, baseBranch: "main" });
     await git(change.repo.localPath, "tag", change.tag);
     await git(change.repo.localPath, "push", "origin", change.tag);
-    log("ok", `Landed ${change.repo.serviceKey} ${change.tag} via PR + tagged (green-CI gated)`);
+    log("ok", `Landed ${change.repo.serviceKey} ${change.tag} via PR + tagged ${change.releaseSha.slice(0, 12)} (green-CI gated)`);
   }
 }
 async function rollbackFailedReleases(changes, ciStatuses, dryRun) {
@@ -472,6 +697,26 @@ async function rollbackFailedReleases(changes, ciStatuses, dryRun) {
     }
   }
 }
+function workflowRunHeadSha(run) {
+  return run.headSha ?? run.head_sha;
+}
+function findPullRequestForHeadSha(prs, pushedSha) {
+  const normalizedSha = pushedSha.toLowerCase();
+  return prs.find((pr) => pr.headRefOid?.toLowerCase() === normalizedSha);
+}
+function findWorkflowRunForHeadSha(runs, releaseSha) {
+  const normalizedReleaseSha = releaseSha.toLowerCase();
+  return runs.find((run) => workflowRunHeadSha(run)?.toLowerCase() === normalizedReleaseSha);
+}
+async function resolveReleaseSha(change) {
+  if (change.releaseSha) return change.releaseSha;
+  try {
+    change.releaseSha = await git(change.repo.localPath, "rev-parse", `${change.tag}^{}`);
+    return change.releaseSha;
+  } catch {
+    return void 0;
+  }
+}
 async function waitForCI(changes, dryRun) {
   if (dryRun) {
     return changes.map((c) => ({
@@ -495,6 +740,10 @@ async function waitForCI(changes, dryRun) {
     if (pending.length === 0) break;
     for (const st of pending) {
       try {
+        const change = changes.find((c) => c.repo.serviceKey === st.repo.serviceKey && c.tag === st.tag);
+        if (!change) continue;
+        const releaseSha = await resolveReleaseSha(change);
+        if (!releaseSha) continue;
         const output = await ghRun([
           "run",
           "list",
@@ -503,17 +752,17 @@ async function waitForCI(changes, dryRun) {
           "--workflow",
           st.repo.releaseWorkflow,
           "--limit",
-          "1",
+          "50",
           "--json",
-          "status,conclusion,url"
+          "status,conclusion,url,headSha"
         ]);
         const runs = JSON.parse(output);
-        const latest = runs[0];
-        if (!latest) continue;
-        if (latest.status === "completed") {
+        const releaseRun = findWorkflowRunForHeadSha(runs, releaseSha);
+        if (!releaseRun) continue;
+        if (releaseRun.status === "completed") {
           st.status = "completed";
-          st.conclusion = latest.conclusion ?? "unknown";
-          st.url = latest.url;
+          st.conclusion = releaseRun.conclusion ?? "unknown";
+          st.url = releaseRun.url;
           if (st.conclusion === "success") {
             log("ok", `CI passed: ${st.repo.serviceKey} ${st.tag}`);
           } else {
@@ -748,7 +997,7 @@ function printImageVerification(results) {
   console.log("");
 }
 async function updateStackManifest(changes, ciStatuses, dryRun, imageResults, canary = false) {
-  const manifest = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+  const manifest = JSON.parse(readFileSync2(MANIFEST_PATH, "utf8"));
   const currentLatest = manifest.latest;
   const currentParts = currentLatest.split(".").map(Number);
   const newStackVersion = `${currentParts[0]}.${currentParts[1]}.${(currentParts[2] ?? 0) + 1}`;
@@ -812,7 +1061,7 @@ async function updateStackManifest(changes, ciStatuses, dryRun, imageResults, ca
   }
   manifest.stacks[newStackVersion] = newEntry;
   if (canary) {
-    writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + "\n");
+    writeSignedStackManifest(MANIFEST_PATH, manifest, { warn: (msg) => log("warn", msg) });
     log("ok", `Stack manifest updated: added CANARY ${newStackVersion} (latest unchanged: ${currentLatest})`);
     log("warn", `${newStackVersion} is a CANARY release. Deploy to a designated canary host with:`);
     log("warn", `  exe-os stack-update --target ${newStackVersion} --yes`);
@@ -820,7 +1069,7 @@ async function updateStackManifest(changes, ciStatuses, dryRun, imageResults, ca
     log("warn", `  exe-os stack-promote --version ${newStackVersion} --yes`);
   } else {
     manifest.latest = newStackVersion;
-    writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + "\n");
+    writeSignedStackManifest(MANIFEST_PATH, manifest, { warn: (msg) => log("warn", msg) });
     log("ok", `Stack manifest updated: ${currentLatest} -> ${newStackVersion}`);
   }
   return newStackVersion;
@@ -828,18 +1077,18 @@ async function updateStackManifest(changes, ciStatuses, dryRun, imageResults, ca
 function gatePublishWithPreflight(newStackVersion, dryRun, allowRed) {
   let manifest;
   try {
-    manifest = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+    manifest = JSON.parse(readFileSync2(MANIFEST_PATH, "utf8"));
   } catch (err) {
     throw new Error(`Preflight gate: cannot read manifest ${MANIFEST_PATH}: ${err instanceof Error ? err.message : String(err)}`);
   }
-  const composeDir = path.join(EXE_OS_ROOT, "deploy", "compose");
+  const composeDir = path2.join(EXE_OS_ROOT, "deploy", "compose");
   const report = runPreflightOnManifest({
     manifest,
     stackVersion: newStackVersion,
     label: `${MANIFEST_PATH} (stack ${newStackVersion})`,
-    envExamplePath: path.join(composeDir, ".env.example"),
-    composePath: path.join(composeDir, "docker-compose.yml"),
-    monitorComposePath: path.join(EXE_OS_ROOT, "deploy", "monitor", "docker-compose.hub.yml")
+    envExamplePath: path2.join(composeDir, ".env.example"),
+    composePath: path2.join(composeDir, "docker-compose.yml"),
+    monitorComposePath: path2.join(EXE_OS_ROOT, "deploy", "monitor", "docker-compose.hub.yml")
   });
   log("info", "Running static preflight gate against the freshly-written manifest...");
   if (dryRun) {
@@ -861,7 +1110,7 @@ function gatePublishWithPreflight(newStackVersion, dryRun, allowRed) {
 function gatePreMutationStructure(changes, dryRun, allowRed) {
   let baseManifest;
   try {
-    baseManifest = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+    baseManifest = JSON.parse(readFileSync2(MANIFEST_PATH, "utf8"));
   } catch (err) {
     throw new Error(`Pre-mutation gate: cannot read manifest ${MANIFEST_PATH}: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -880,14 +1129,14 @@ function gatePreMutationStructure(changes, dryRun, allowRed) {
     latest: simVersion,
     stacks: { [simVersion]: { version: simVersion, services } }
   };
-  const composeDir = path.join(EXE_OS_ROOT, "deploy", "compose");
+  const composeDir = path2.join(EXE_OS_ROOT, "deploy", "compose");
   const report = runPreflightOnManifest({
     manifest: simManifest,
     stackVersion: simVersion,
     label: `pre-mutation simulated manifest (stack ${simVersion})`,
-    envExamplePath: path.join(composeDir, ".env.example"),
-    composePath: path.join(composeDir, "docker-compose.yml"),
-    monitorComposePath: path.join(EXE_OS_ROOT, "deploy", "monitor", "docker-compose.hub.yml")
+    envExamplePath: path2.join(composeDir, ".env.example"),
+    composePath: path2.join(composeDir, "docker-compose.yml"),
+    monitorComposePath: path2.join(EXE_OS_ROOT, "deploy", "monitor", "docker-compose.hub.yml")
   });
   const adjusted = {
     ...report,
@@ -929,6 +1178,13 @@ async function commitAndTagExeOs(newStackVersion, _exeOsChange, dryRun) {
     log("ok", `Committed stack manifest v${newStackVersion} (via PR)`);
   }
   const stackTag = `stack-v${newStackVersion}`;
+  const releaseCommit = await git(EXE_OS_ROOT, "rev-parse", "HEAD");
+  await assertReleaseFreshness({
+    repoPath: EXE_OS_ROOT,
+    defaultBranch: "main",
+    releaseCommit
+  });
+  await printOpenPrGate({ ghRepo: "AskExe/exe-os", baseBranch: "main" });
   try {
     await git(EXE_OS_ROOT, "tag", stackTag);
     await git(EXE_OS_ROOT, "push", "origin", stackTag);
@@ -997,9 +1253,25 @@ async function confirm(message) {
     });
   });
 }
+function nextStackVersionForLock() {
+  try {
+    const manifest = JSON.parse(readFileSync2(MANIFEST_PATH, "utf8"));
+    const parts = String(manifest.latest ?? "0.9.0").split(".").map(Number);
+    return `stack-v${parts[0] ?? 0}.${parts[1] ?? 9}.${(parts[2] ?? 0) + 1}`;
+  } catch {
+    return "stack-vunknown";
+  }
+}
+async function currentReleaseBranch() {
+  try {
+    return await git(EXE_OS_ROOT, "branch", "--show-current") || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 async function runStackRelease(flags) {
   if (!flags.stack) {
-    console.error("Usage: exe-os release --stack [--dry-run] [--repos <list>] [--yes] [--skip-image-verify] [--allow-red] [--allow-dirty] [--canary] [--root <path>] [--force]");
+    console.error("Usage: exe-os release --stack [--dry-run] [--repos <list>] [--yes] [--skip-image-verify] [--allow-red] [--allow-dirty] [--canary] [--root <path>] [--force] [--force-build]");
     process.exit(1);
   }
   if (flags.root) {
@@ -1010,133 +1282,156 @@ async function runStackRelease(flags) {
     console.warn("  \x1B[33m   Docker images will be built WITHOUT requiring green CI.\x1B[0m");
     console.warn("  \x1B[33m   Use only for break-glass emergencies.\x1B[0m\n");
   }
-  await assertCleanWorkingTree({ allowDirty: flags.allowDirty || flags.dryRun });
-  console.log(`
+  if (flags.force) {
+    console.warn("\n  \x1B[33;1m\u26A0  --force: release mutex override is ACTIVE\x1B[0m");
+    console.warn("  \x1B[33m   This only overrides ~/.exe-os/release.lock; freshness and publish gates still apply.\x1B[0m");
+    console.warn("  \x1B[33m   Use only after verifying no other release is actually running.\x1B[0m\n");
+  }
+  let releaseLock;
+  if (!flags.dryRun) {
+    releaseLock = acquireReleaseLock({
+      targetVersion: nextStackVersionForLock(),
+      branch: await currentReleaseBranch(),
+      force: flags.force,
+      log: (message) => log("warn", message)
+    });
+    log("ok", `Acquired release lock: ${releaseLock.lockPath}`);
+  }
+  try {
+    await assertCleanWorkingTree({ allowDirty: flags.allowDirty || flags.dryRun });
+    console.log(`
   \x1B[1mexe-os stack release\x1B[0m${flags.dryRun ? " (dry run)" : ""}
 `);
-  const allRepos = buildRepoConfigs();
-  let repos;
-  if (flags.repos) {
-    repos = [];
-    for (const name of flags.repos) {
-      const match = allRepos.find(
-        (r) => r.serviceKey === name || r.ghRepo.endsWith(`/${name}`) || r.ghRepo === name
-      );
-      if (match) {
-        repos.push(match);
-      } else {
-        log("warn", `Unknown repo: ${name} \u2014 skipping`);
+    const allRepos = buildRepoConfigs();
+    let repos;
+    if (flags.repos) {
+      repos = [];
+      for (const name of flags.repos) {
+        const match = allRepos.find(
+          (r) => r.serviceKey === name || r.ghRepo.endsWith(`/${name}`) || r.ghRepo === name
+        );
+        if (match) {
+          repos.push(match);
+        } else {
+          log("warn", `Unknown repo: ${name} \u2014 skipping`);
+        }
       }
+      if (repos.length === 0) {
+        throw new Error("No valid repos specified.");
+      }
+    } else {
+      repos = allRepos;
     }
-    if (repos.length === 0) {
-      console.error("No valid repos specified.");
-      process.exit(1);
-    }
-  } else {
-    repos = allRepos;
-  }
-  repos = repos.filter((repo) => {
-    if (hasPackageJson(repo)) return true;
-    warnMissingRepoPackage(repo);
-    return false;
-  });
-  log("info", "Detecting changes across repos...");
-  const changes = await detectChanges(repos);
-  if (changes.length === 0) {
-    console.log("\n  No changes detected since last tags. Nothing to release.\n");
-    return;
-  }
-  const bumpMode = flags.major ? "major" : flags.minor ? "minor" : "patch";
-  for (const change of changes) {
-    const newVersion = bumpVersion(change.currentVersion, bumpMode);
-    change.newVersion = newVersion;
-    change.tag = `v${newVersion}`;
-  }
-  console.log("\n  Planned releases:");
-  for (const change of changes) {
-    console.log(
-      `    ${change.repo.serviceKey.padEnd(14)} ${change.currentVersion} -> ${change.newVersion}  (${change.commits.length} commit${change.commits.length === 1 ? "" : "s"})`
-    );
-  }
-  gatePreMutationStructure(changes, flags.dryRun, flags.allowRed);
-  if (!flags.yes && !flags.dryRun) {
-    const ok = await confirm("Proceed with release?");
-    if (!ok) {
-      console.log("  Aborted.\n");
+    repos = repos.filter((repo) => {
+      if (hasPackageJson(repo)) return true;
+      warnMissingRepoPackage(repo);
+      return false;
+    });
+    log("info", "Detecting changes across repos...");
+    const changes = await detectChanges(repos);
+    if (changes.length === 0) {
+      console.log("\n  No changes detected since last tags. Nothing to release.\n");
       return;
     }
-  }
-  await bumpVersions(changes, bumpMode, flags.dryRun);
-  log("info", "Tagging repos and triggering CI...");
-  await tagAndTriggerCI(changes, flags.dryRun);
-  const ciStatuses = await waitForCI(changes, flags.dryRun);
-  const ciFailures = ciStatuses.filter(
-    (s) => s.status !== "completed" || s.conclusion !== "success"
-  );
-  if (ciFailures.length > 0 && !flags.dryRun) {
-    await rollbackFailedReleases(changes, ciStatuses, flags.dryRun);
-    const ciSuccesses = ciStatuses.filter(
-      (s) => s.status === "completed" && s.conclusion === "success"
-    );
-    if (ciSuccesses.length === 0) {
-      log("fail", "All CI builds failed. Release aborted, all bumps rolled back.");
-      process.exit(1);
+    const bumpMode = flags.major ? "major" : flags.minor ? "minor" : "patch";
+    for (const change of changes) {
+      const newVersion = bumpVersion(change.currentVersion, bumpMode);
+      change.newVersion = newVersion;
+      change.tag = `v${newVersion}`;
     }
-    log("warn", `${ciFailures.length} CI build(s) failed and were rolled back. Continuing with ${ciSuccesses.length} successful build(s).`);
-  }
-  let imageResults = [];
-  if (flags.skipImageVerify) {
-    log("warn", "Image verification skipped (--skip-image-verify)");
-  } else {
-    imageResults = await verifyImages(changes, ciStatuses, flags.dryRun);
-    const failed = imageResults.filter((r) => (r.ghcr === "missing" || r.ghcr === "error") && r.proxy !== "ok");
-    if (failed.length > 0 && !flags.dryRun) {
-      for (const m of failed) {
-        log("fail", `${shortImageName(m.repo.imageName)}:${m.tag} \u2014 GHCR status: ${m.ghcr}, proxy: ${m.proxy} \u2014 cannot release`);
-      }
-      log("fail", "Aborting: images not verified. Fix GHCR auth/CI or use --skip-image-verify to override.");
-      process.exit(1);
+    console.log("\n  Planned releases:");
+    for (const change of changes) {
+      console.log(
+        `    ${change.repo.serviceKey.padEnd(14)} ${change.currentVersion} -> ${change.newVersion}  (${change.commits.length} commit${change.commits.length === 1 ? "" : "s"})`
+      );
     }
-    const pending = imageResults.filter((r) => r.proxy === "pending");
-    if (pending.length > 0) {
-      for (const p of pending) {
-        log("warn", `${shortImageName(p.repo.imageName)}:${p.tag} \u2014 proxy cache pending`);
+    gatePreMutationStructure(changes, flags.dryRun, flags.allowRed);
+    if (!flags.yes && !flags.dryRun) {
+      const ok = await confirm("Proceed with release?");
+      if (!ok) {
+        console.log("  Aborted.\n");
+        return;
       }
-      if (!flags.dryRun) {
-        log("fail", "Aborting: proxy cache not ready for all images. Wait for proxy propagation or use --skip-image-verify.");
-        process.exit(1);
+    }
+    await bumpVersions(changes, bumpMode, flags.dryRun);
+    log("info", "Tagging repos and triggering CI...");
+    await tagAndTriggerCI(changes, flags.dryRun);
+    const ciStatuses = await waitForCI(changes, flags.dryRun);
+    const ciFailures = ciStatuses.filter(
+      (s) => s.status !== "completed" || s.conclusion !== "success"
+    );
+    if (ciFailures.length > 0 && !flags.dryRun) {
+      await rollbackFailedReleases(changes, ciStatuses, flags.dryRun);
+      const ciSuccesses = ciStatuses.filter(
+        (s) => s.status === "completed" && s.conclusion === "success"
+      );
+      if (ciSuccesses.length === 0) {
+        log("fail", "All CI builds failed. Release aborted, all bumps rolled back.");
+        throw new Error("All CI builds failed. Release aborted, all bumps rolled back.");
       }
+      log("warn", `${ciFailures.length} CI build(s) failed and were rolled back. Continuing with ${ciSuccesses.length} successful build(s).`);
     }
-    printImageVerification(imageResults);
-  }
-  log("info", "Updating stack manifest...");
-  const newStackVersion = await updateStackManifest(changes, ciStatuses, flags.dryRun, imageResults, flags.canary);
-  gatePublishWithPreflight(newStackVersion, flags.dryRun, flags.allowRed);
-  const exeOsChange = changes.find((c) => c.repo.serviceKey === "exe-os");
-  await commitAndTagExeOs(newStackVersion, exeOsChange, flags.dryRun);
-  printSummary(changes, ciStatuses, newStackVersion, flags.dryRun);
-  if (!flags.skipImageVerify && !flags.dryRun && imageResults.length > 0) {
-    const pendingImages = imageResults.filter((r) => r.proxy === "pending");
-    if (pendingImages.length > 0) {
-      log("info", "Re-checking proxy availability for pending images...");
-      for (const r of pendingImages) {
-        const shortName = shortImageName(r.repo.imageName);
-        const proxyRepo = `askexe/${shortName}`;
-        const proxyToken = process.env.EXE_REGISTRY_PROXY_PULL_TOKEN ?? void 0;
-        const recheck = await checkRegistryManifest(PROXY_REGISTRY, proxyRepo, r.tag, proxyToken);
-        if (recheck.ok) {
-          r.proxy = "ok";
+    let imageResults = [];
+    if (flags.skipImageVerify) {
+      log("warn", "Image verification skipped (--skip-image-verify)");
+    } else {
+      imageResults = await verifyImages(changes, ciStatuses, flags.dryRun);
+      const failed = imageResults.filter((r) => (r.ghcr === "missing" || r.ghcr === "error") && r.proxy !== "ok");
+      if (failed.length > 0 && !flags.dryRun) {
+        for (const m of failed) {
+          log("fail", `${shortImageName(m.repo.imageName)}:${m.tag} \u2014 GHCR status: ${m.ghcr}, proxy: ${m.proxy} \u2014 cannot release`);
+        }
+        log("fail", "Aborting: images not verified. Fix GHCR auth/CI or use --skip-image-verify to override.");
+        throw new Error("Aborting: images not verified. Fix GHCR auth/CI or use --skip-image-verify to override.");
+      }
+      const pending = imageResults.filter((r) => r.proxy === "pending");
+      if (pending.length > 0) {
+        for (const p of pending) {
+          log("warn", `${shortImageName(p.repo.imageName)}:${p.tag} \u2014 proxy cache pending`);
+        }
+        if (!flags.dryRun) {
+          log("fail", "Aborting: proxy cache not ready for all images. Wait for proxy propagation or use --skip-image-verify.");
+          throw new Error("Aborting: proxy cache not ready for all images. Wait for proxy propagation or use --skip-image-verify.");
         }
       }
       printImageVerification(imageResults);
     }
+    log("info", "Updating stack manifest...");
+    const newStackVersion = await updateStackManifest(changes, ciStatuses, flags.dryRun, imageResults, flags.canary);
+    gatePublishWithPreflight(newStackVersion, flags.dryRun, flags.allowRed);
+    const exeOsChange = changes.find((c) => c.repo.serviceKey === "exe-os");
+    await commitAndTagExeOs(newStackVersion, exeOsChange, flags.dryRun);
+    printSummary(changes, ciStatuses, newStackVersion, flags.dryRun);
+    if (!flags.skipImageVerify && !flags.dryRun && imageResults.length > 0) {
+      const pendingImages = imageResults.filter((r) => r.proxy === "pending");
+      if (pendingImages.length > 0) {
+        log("info", "Re-checking proxy availability for pending images...");
+        for (const r of pendingImages) {
+          const shortName = shortImageName(r.repo.imageName);
+          const proxyRepo = `askexe/${shortName}`;
+          const proxyToken = process.env.EXE_REGISTRY_PROXY_PULL_TOKEN ?? void 0;
+          const recheck = await checkRegistryManifest(PROXY_REGISTRY, proxyRepo, r.tag, proxyToken);
+          if (recheck.ok) {
+            r.proxy = "ok";
+          }
+        }
+        printImageVerification(imageResults);
+      }
+    }
+  } finally {
+    releaseLock?.release();
+    if (releaseLock) log("ok", `Released release lock: ${releaseLock.lockPath}`);
   }
 }
 export {
   assertCleanWorkingTree,
+  assertReleaseFreshness,
   deriveCloneUrl,
   ensureRepoCloned,
+  findPullRequestForHeadSha,
+  findWorkflowRunForHeadSha,
   isCloneTargetSafe,
   parseReleaseArgs,
+  printOpenPrGate,
   runStackRelease
 };