@launchsecure/launch-kit 0.0.36 → 0.0.37

package/dist/server/init-entry.js

@@ -617,6 +617,17 @@ async function cf(opts) {
 function isNotFound(env) {
   return !env.success && (env.errors ?? []).some((e) => e.code === 7003 || e.code === 1001 || e.code === 81044);
 }
+async function findTunnelByName(input) {
+  const q = new URLSearchParams({ name: input.tunnelName, is_deleted: "false" }).toString();
+  const res = await cf({
+    apiToken: input.apiToken,
+    method: "GET",
+    path: `/accounts/${input.accountId}/cfd_tunnel?${q}`
+  });
+  if (!res.success || !Array.isArray(res.result)) return null;
+  const live = res.result.find((t) => t.name === input.tunnelName && !t.deleted_at);
+  return live?.id ?? null;
+}
 function loadState(path6) {
   if (!(0, import_node_fs2.existsSync)(path6)) return null;
   try {
@@ -648,16 +659,26 @@ async function ensureTunnel(input, knownTunnelId) {
       throw new Error(`[cf] tunnel GET failed: ${JSON.stringify(got.errors)}`);
     }
   }
+  const existing = await findTunnelByName(input);
+  if (existing) {
+    console.log(`[cf] adopted existing tunnel "${input.tunnelName}" (${existing}) \u2014 local state was missing`);
+    return existing;
+  }
   const created = await cf({
     apiToken: input.apiToken,
     method: "POST",
     path: `/accounts/${input.accountId}/cfd_tunnel`,
     body: { name: input.tunnelName, config_src: "cloudflare" }
   });
-  if (!created.success || !created.result) {
-    throw new Error(`[cf] tunnel create failed: ${JSON.stringify(created.errors)}`);
+  if (created.success && created.result) return created.result.id;
+  if ((created.errors ?? []).some((e) => e.code === 1013)) {
+    const adopted = await findTunnelByName(input);
+    if (adopted) {
+      console.log(`[cf] tunnel "${input.tunnelName}" already existed (1013) \u2014 adopted ${adopted}`);
+      return adopted;
+    }
   }
-  return created.result.id;
+  throw new Error(`[cf] tunnel create failed: ${JSON.stringify(created.errors)}`);
 }
 async function fetchConnectorToken(input, tunnelId) {
   const res = await cf({
@@ -942,6 +963,60 @@ function run2(cmd, args, stdio = "inherit") {
   const r = (0, import_node_child_process2.spawnSync)(cmd, args, { stdio });
   return r.status ?? 1;
 }
+function readCrashState() {
+  try {
+    const s = JSON.parse((0, import_node_fs4.readFileSync)(CRASH_STATE_FILE, "utf8"));
+    return typeof s?.count === "number" && s.count >= 0 ? s : null;
+  } catch {
+    return null;
+  }
+}
+function bumpCrashCount() {
+  const prev = readCrashState();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const next = {
+    count: (prev?.count ?? 0) + 1,
+    firstAt: prev?.firstAt ?? now,
+    lastAt: now
+  };
+  try {
+    (0, import_node_fs4.mkdirSync)(LAUNCHPOD_DIR, { recursive: true });
+    (0, import_node_fs4.writeFileSync)(CRASH_STATE_FILE, JSON.stringify(next, null, 2));
+  } catch (err) {
+    console.warn(`[entrypoint] could not persist boot-crash counter (continuing unprotected): ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return next.count;
+}
+function clearCrashCount() {
+  try {
+    if ((0, import_node_fs4.existsSync)(CRASH_STATE_FILE)) (0, import_node_fs4.writeFileSync)(CRASH_STATE_FILE, JSON.stringify({ count: 0, firstAt: "", lastAt: "" }));
+  } catch {
+  }
+}
+async function parkAfterCrashLoop(count) {
+  const lines = [
+    "==================================================================",
+    `[entrypoint] CRASH-LOOP HALT \u2014 ${count} consecutive failed boots (cap ${MAX_BOOT_CRASHES}).`,
+    "[entrypoint] Refusing to restart again. Container is now PARKED (idle, not",
+    "[entrypoint] exiting) so it stops thrashing CF APIs and logs. Fix the root",
+    "[entrypoint] cause, clear the counter, then restart the container:",
+    `[entrypoint]   rm ${CRASH_STATE_FILE} && docker restart <container>`,
+    "=================================================================="
+  ];
+  for (const l of lines) console.error(l);
+  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.on(sig, () => {
+      console.log(`[entrypoint] received ${sig} while parked \u2014 exiting`);
+      process.exit(0);
+    });
+  }
+  setInterval(() => {
+    console.error(`[entrypoint] still parked after crash-loop halt \u2014 clear ${CRASH_STATE_FILE} and restart to retry`);
+  }, 15 * 6e4);
+  await new Promise(() => {
+  });
+  throw new Error("unreachable");
+}
 async function setupFromCloud() {
   const pat = requireEnv("LS_PAT");
   const orgSlug = requireEnv("LS_ORG_SLUG");
@@ -1226,6 +1301,12 @@ function spawnServiceGroup(services) {
   }).finally(removeSignals);
 }
 async function main() {
+  const priorCrashes = readCrashState()?.count ?? 0;
+  if (priorCrashes >= MAX_BOOT_CRASHES) await parkAfterCrashLoop(priorCrashes);
+  const bootAttempt = bumpCrashCount();
+  if (bootAttempt > 1) {
+    console.warn(`[entrypoint] boot attempt ${bootAttempt}/${MAX_BOOT_CRASHES} \u2014 prior boot(s) crashed before becoming stable`);
+  }
   for (const k of REQUIRED_ENV) requireEnv(k);
   const bundle = await setupFromCloud();
   setupClaudeCredentials();
@@ -1257,15 +1338,22 @@ async function main() {
       console.warn(`[entrypoint] \u26A0 first service is "${first.name}", not "radar" \u2014 quick tunneling is owned by the radar agent today, so NO external URL will be available.`);
     }
   }
+  const stableTimer = setTimeout(() => {
+    clearCrashCount();
+    console.log(`[entrypoint] services stable for ${Math.round(STABLE_AFTER_MS / 1e3)}s \u2014 boot-crash counter cleared`);
+  }, STABLE_AFTER_MS);
+  stableTimer.unref?.();
   try {
     await spawnServiceGroup(services);
+    clearTimeout(stableTimer);
     process.exit(0);
   } catch (err) {
+    clearTimeout(stableTimer);
     console.error(`[entrypoint] ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
   }
 }
-var import_node_child_process2, import_node_fs4, import_node_path4, REQUIRED_ENV, GATED_SERVICES;
+var import_node_child_process2, import_node_fs4, import_node_path4, REQUIRED_ENV, LAUNCHPOD_DIR, CRASH_STATE_FILE, MAX_BOOT_CRASHES, STABLE_AFTER_MS, GATED_SERVICES;
 var init_radar_docker_init_entry = __esm({
   "src/server/radar-docker-init-entry.ts"() {
     "use strict";
@@ -1282,6 +1370,10 @@ var init_radar_docker_init_entry = __esm({
       "LS_ORG_SLUG",
       "LS_PROJECT_SLUG"
     ];
+    LAUNCHPOD_DIR = "/workspace/.launchpod";
+    CRASH_STATE_FILE = (0, import_node_path4.join)(LAUNCHPOD_DIR, ".boot-crash.json");
+    MAX_BOOT_CRASHES = 5;
+    STABLE_AFTER_MS = 3e4;
     GATED_SERVICES = {
       // Claude web terminal — live drivable shell ⇒ RCE surface ⇒ short session.
       bot: { strict: true },

package/dist/server/radar-docker-init-entry.js

@@ -286,6 +286,17 @@ async function cf(opts) {
 function isNotFound(env) {
   return !env.success && (env.errors ?? []).some((e) => e.code === 7003 || e.code === 1001 || e.code === 81044);
 }
+async function findTunnelByName(input) {
+  const q = new URLSearchParams({ name: input.tunnelName, is_deleted: "false" }).toString();
+  const res = await cf({
+    apiToken: input.apiToken,
+    method: "GET",
+    path: `/accounts/${input.accountId}/cfd_tunnel?${q}`
+  });
+  if (!res.success || !Array.isArray(res.result)) return null;
+  const live = res.result.find((t) => t.name === input.tunnelName && !t.deleted_at);
+  return live?.id ?? null;
+}
 function loadState(path) {
   if (!(0, import_node_fs2.existsSync)(path)) return null;
   try {
@@ -317,16 +328,26 @@ async function ensureTunnel(input, knownTunnelId) {
       throw new Error(`[cf] tunnel GET failed: ${JSON.stringify(got.errors)}`);
     }
   }
+  const existing = await findTunnelByName(input);
+  if (existing) {
+    console.log(`[cf] adopted existing tunnel "${input.tunnelName}" (${existing}) \u2014 local state was missing`);
+    return existing;
+  }
   const created = await cf({
     apiToken: input.apiToken,
     method: "POST",
     path: `/accounts/${input.accountId}/cfd_tunnel`,
     body: { name: input.tunnelName, config_src: "cloudflare" }
   });
-  if (!created.success || !created.result) {
-    throw new Error(`[cf] tunnel create failed: ${JSON.stringify(created.errors)}`);
+  if (created.success && created.result) return created.result.id;
+  if ((created.errors ?? []).some((e) => e.code === 1013)) {
+    const adopted = await findTunnelByName(input);
+    if (adopted) {
+      console.log(`[cf] tunnel "${input.tunnelName}" already existed (1013) \u2014 adopted ${adopted}`);
+      return adopted;
+    }
   }
-  return created.result.id;
+  throw new Error(`[cf] tunnel create failed: ${JSON.stringify(created.errors)}`);
 }
 async function fetchConnectorToken(input, tunnelId) {
   const res = await cf({
@@ -595,6 +616,64 @@ function run(cmd, args, stdio = "inherit") {
   const r = (0, import_node_child_process.spawnSync)(cmd, args, { stdio });
   return r.status ?? 1;
 }
+var LAUNCHPOD_DIR = "/workspace/.launchpod";
+var CRASH_STATE_FILE = (0, import_node_path4.join)(LAUNCHPOD_DIR, ".boot-crash.json");
+var MAX_BOOT_CRASHES = 5;
+var STABLE_AFTER_MS = 3e4;
+function readCrashState() {
+  try {
+    const s = JSON.parse((0, import_node_fs4.readFileSync)(CRASH_STATE_FILE, "utf8"));
+    return typeof s?.count === "number" && s.count >= 0 ? s : null;
+  } catch {
+    return null;
+  }
+}
+function bumpCrashCount() {
+  const prev = readCrashState();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const next = {
+    count: (prev?.count ?? 0) + 1,
+    firstAt: prev?.firstAt ?? now,
+    lastAt: now
+  };
+  try {
+    (0, import_node_fs4.mkdirSync)(LAUNCHPOD_DIR, { recursive: true });
+    (0, import_node_fs4.writeFileSync)(CRASH_STATE_FILE, JSON.stringify(next, null, 2));
+  } catch (err) {
+    console.warn(`[entrypoint] could not persist boot-crash counter (continuing unprotected): ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return next.count;
+}
+function clearCrashCount() {
+  try {
+    if ((0, import_node_fs4.existsSync)(CRASH_STATE_FILE)) (0, import_node_fs4.writeFileSync)(CRASH_STATE_FILE, JSON.stringify({ count: 0, firstAt: "", lastAt: "" }));
+  } catch {
+  }
+}
+async function parkAfterCrashLoop(count) {
+  const lines = [
+    "==================================================================",
+    `[entrypoint] CRASH-LOOP HALT \u2014 ${count} consecutive failed boots (cap ${MAX_BOOT_CRASHES}).`,
+    "[entrypoint] Refusing to restart again. Container is now PARKED (idle, not",
+    "[entrypoint] exiting) so it stops thrashing CF APIs and logs. Fix the root",
+    "[entrypoint] cause, clear the counter, then restart the container:",
+    `[entrypoint]   rm ${CRASH_STATE_FILE} && docker restart <container>`,
+    "=================================================================="
+  ];
+  for (const l of lines) console.error(l);
+  for (const sig of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+    process.on(sig, () => {
+      console.log(`[entrypoint] received ${sig} while parked \u2014 exiting`);
+      process.exit(0);
+    });
+  }
+  setInterval(() => {
+    console.error(`[entrypoint] still parked after crash-loop halt \u2014 clear ${CRASH_STATE_FILE} and restart to retry`);
+  }, 15 * 6e4);
+  await new Promise(() => {
+  });
+  throw new Error("unreachable");
+}
 async function setupFromCloud() {
   const pat = requireEnv("LS_PAT");
   const orgSlug = requireEnv("LS_ORG_SLUG");
@@ -885,6 +964,12 @@ function spawnServiceGroup(services) {
   }).finally(removeSignals);
 }
 async function main() {
+  const priorCrashes = readCrashState()?.count ?? 0;
+  if (priorCrashes >= MAX_BOOT_CRASHES) await parkAfterCrashLoop(priorCrashes);
+  const bootAttempt = bumpCrashCount();
+  if (bootAttempt > 1) {
+    console.warn(`[entrypoint] boot attempt ${bootAttempt}/${MAX_BOOT_CRASHES} \u2014 prior boot(s) crashed before becoming stable`);
+  }
   for (const k of REQUIRED_ENV) requireEnv(k);
   const bundle = await setupFromCloud();
   setupClaudeCredentials();
@@ -916,10 +1001,17 @@ async function main() {
       console.warn(`[entrypoint] \u26A0 first service is "${first.name}", not "radar" \u2014 quick tunneling is owned by the radar agent today, so NO external URL will be available.`);
     }
   }
+  const stableTimer = setTimeout(() => {
+    clearCrashCount();
+    console.log(`[entrypoint] services stable for ${Math.round(STABLE_AFTER_MS / 1e3)}s \u2014 boot-crash counter cleared`);
+  }, STABLE_AFTER_MS);
+  stableTimer.unref?.();
   try {
     await spawnServiceGroup(services);
+    clearTimeout(stableTimer);
     process.exit(0);
   } catch (err) {
+    clearTimeout(stableTimer);
     console.error(`[entrypoint] ${err instanceof Error ? err.message : String(err)}`);
     process.exit(1);
   }

package/dist/server/rover-entry.js

@@ -61,6 +61,17 @@ async function cf(opts) {
 function isNotFound(env) {
   return !env.success && (env.errors ?? []).some((e) => e.code === 7003 || e.code === 1001 || e.code === 81044);
 }
+async function findTunnelByName(input) {
+  const q = new URLSearchParams({ name: input.tunnelName, is_deleted: "false" }).toString();
+  const res = await cf({
+    apiToken: input.apiToken,
+    method: "GET",
+    path: `/accounts/${input.accountId}/cfd_tunnel?${q}`
+  });
+  if (!res.success || !Array.isArray(res.result)) return null;
+  const live = res.result.find((t) => t.name === input.tunnelName && !t.deleted_at);
+  return live?.id ?? null;
+}
 function loadState(path) {
   if (!(0, import_node_fs.existsSync)(path)) return null;
   try {
@@ -92,16 +103,26 @@ async function ensureTunnel(input, knownTunnelId) {
       throw new Error(`[cf] tunnel GET failed: ${JSON.stringify(got.errors)}`);
     }
   }
+  const existing = await findTunnelByName(input);
+  if (existing) {
+    console.log(`[cf] adopted existing tunnel "${input.tunnelName}" (${existing}) \u2014 local state was missing`);
+    return existing;
+  }
   const created = await cf({
     apiToken: input.apiToken,
     method: "POST",
     path: `/accounts/${input.accountId}/cfd_tunnel`,
     body: { name: input.tunnelName, config_src: "cloudflare" }
   });
-  if (!created.success || !created.result) {
-    throw new Error(`[cf] tunnel create failed: ${JSON.stringify(created.errors)}`);
+  if (created.success && created.result) return created.result.id;
+  if ((created.errors ?? []).some((e) => e.code === 1013)) {
+    const adopted = await findTunnelByName(input);
+    if (adopted) {
+      console.log(`[cf] tunnel "${input.tunnelName}" already existed (1013) \u2014 adopted ${adopted}`);
+      return adopted;
+    }
   }
-  return created.result.id;
+  throw new Error(`[cf] tunnel create failed: ${JSON.stringify(created.errors)}`);
 }
 async function fetchConnectorToken(input, tunnelId) {
   const res = await cf({
@@ -587,7 +608,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@launchsecure/launch-kit",
-      version: "0.0.36",
+      version: "0.0.37",
       description: "LaunchSecure toolkit \u2014 launch-sequencer (pipeline runner + terminal bridge), launch-radar (feedback webhook receiver), launch-chart (project graph MCP), launch-deck (visual playground MCP), launch-kit-beacon (feedback Web Component), launch-recall (file-watcher backup). launch-pod is the container image these run inside.",
       license: "MIT",
       author: "LaunchSecure - AutomateWithUs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@launchsecure/launch-kit",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "description": "LaunchSecure toolkit — launch-sequencer (pipeline runner + terminal bridge), launch-radar (feedback webhook receiver), launch-chart (project graph MCP), launch-deck (visual playground MCP), launch-kit-beacon (feedback Web Component), launch-recall (file-watcher backup). launch-pod is the container image these run inside.",
   "license": "MIT",
   "author": "LaunchSecure - AutomateWithUs",
@@ -59,24 +59,6 @@
     "launch-rover": "./dist/server/rover-entry.js",
     "launch-bot": "./dist/server/launch-bot-entry.js"
   },
-  "scripts": {
-    "build": "pnpm build:client && pnpm build:chart-client && pnpm build:deck-client && pnpm build:council-client && pnpm build:beacon && pnpm build:server",
-    "build:beacon": "vite build --config vite.beacon.config.ts && tsc -p tsconfig.beacon.json --emitDeclarationOnly --outDir dist/beacon/types",
-    "test:beacon": "vitest run --config vite.beacon.config.ts",
-    "test:radar": "vitest run --config vite.radar.config.ts",
-    "test:chart": "vitest run --config vite.chart.test.config.ts",
-    "build:deck-client": "vite build --config vite.deck.config.ts",
-    "build:council-client": "vite build --config vite.council.config.ts",
-    "build:client": "vite build",
-    "build:chart-client": "vite build --config vite.chart.config.ts",
-    "build:server": "esbuild src/server/cli.ts src/server/fb-wizard.ts src/server/graph-mcp-entry.ts src/server/chart-serve.ts src/server/deck-mcp-entry.ts src/server/deck-serve.ts src/server/council-entry.ts src/server/council-serve.ts src/server/recall-entry.ts src/server/init-entry.ts src/server/orbit-entry.ts src/server/course-entry.ts src/server/beacon-monitor-entry.ts src/server/parse-worker-entry.ts src/server/radar-teardown-entry.ts src/server/radar-docker-init-entry.ts src/server/launch-radar-entry.ts src/server/rover-entry.ts src/server/launch-bot-entry.ts --bundle --platform=node --target=node18 --outdir=dist/server --external:node-pty --external:ws --external:typescript --external:web-tree-sitter --external:tree-sitter-typescript --external:cloudflared --external:pg --external:pg-native --external:pgsql-parser --external:libpg-query && rm -rf dist/server/public && cp -r ../claude-code-web/src/public dist/server/public && rm -rf dist/server/graph/queries && mkdir -p dist/server/graph && cp -r src/server/graph/queries dist/server/graph/queries",
-    "dev:client": "vite",
-    "dev:deck-serve": "cd ../.. && tsx watch packages/cli/src/server/deck-mcp-entry.ts serve",
-    "dev:chart": "pnpm build:server && pnpm build:chart-client && node dist/server/graph-mcp-entry.js serve",
-    "dev:server": "pnpm build:server && node dist/server/cli.js",
-    "dev": "pnpm build:server && concurrently -k -n client,server -c cyan,magenta \"vite\" \"node dist/server/cli.js\"",
-    "prepublishOnly": "pnpm build"
-  },
   "files": [
     "dist",
     "prompts",
@@ -97,8 +79,6 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@launchsecure/claude-code-web": "workspace:*",
-    "@launchsecure/ui": "workspace:*",
     "@types/node": "^20.0.0",
     "@types/pg": "^8.11.10",
     "@types/react": "^18.3.12",
@@ -122,6 +102,25 @@
     "react-router-dom": "^6.28.0",
     "tailwindcss": "^3.4.19",
     "vite": "^5.4.11",
-    "vitest": "^1.6.0"
+    "vitest": "^1.6.0",
+    "@launchsecure/claude-code-web": "0.0.1",
+    "@launchsecure/ui": "0.0.1"
+  },
+  "scripts": {
+    "build": "pnpm build:client && pnpm build:chart-client && pnpm build:deck-client && pnpm build:council-client && pnpm build:beacon && pnpm build:server",
+    "build:beacon": "vite build --config vite.beacon.config.ts && tsc -p tsconfig.beacon.json --emitDeclarationOnly --outDir dist/beacon/types",
+    "test:beacon": "vitest run --config vite.beacon.config.ts",
+    "test:radar": "vitest run --config vite.radar.config.ts",
+    "test:chart": "vitest run --config vite.chart.test.config.ts",
+    "build:deck-client": "vite build --config vite.deck.config.ts",
+    "build:council-client": "vite build --config vite.council.config.ts",
+    "build:client": "vite build",
+    "build:chart-client": "vite build --config vite.chart.config.ts",
+    "build:server": "esbuild src/server/cli.ts src/server/fb-wizard.ts src/server/graph-mcp-entry.ts src/server/chart-serve.ts src/server/deck-mcp-entry.ts src/server/deck-serve.ts src/server/council-entry.ts src/server/council-serve.ts src/server/recall-entry.ts src/server/init-entry.ts src/server/orbit-entry.ts src/server/course-entry.ts src/server/beacon-monitor-entry.ts src/server/parse-worker-entry.ts src/server/radar-teardown-entry.ts src/server/radar-docker-init-entry.ts src/server/launch-radar-entry.ts src/server/rover-entry.ts src/server/launch-bot-entry.ts --bundle --platform=node --target=node18 --outdir=dist/server --external:node-pty --external:ws --external:typescript --external:web-tree-sitter --external:tree-sitter-typescript --external:cloudflared --external:pg --external:pg-native --external:pgsql-parser --external:libpg-query && rm -rf dist/server/public && cp -r ../claude-code-web/src/public dist/server/public && rm -rf dist/server/graph/queries && mkdir -p dist/server/graph && cp -r src/server/graph/queries dist/server/graph/queries",
+    "dev:client": "vite",
+    "dev:deck-serve": "cd ../.. && tsx watch packages/cli/src/server/deck-mcp-entry.ts serve",
+    "dev:chart": "pnpm build:server && pnpm build:chart-client && node dist/server/graph-mcp-entry.js serve",
+    "dev:server": "pnpm build:server && node dist/server/cli.js",
+    "dev": "pnpm build:server && concurrently -k -n client,server -c cyan,magenta \"vite\" \"node dist/server/cli.js\""
   }
-}
+}

package/scaffolds/ls-marketplace/plugins/kit/skills/deploy-check/SKILL.md

@@ -80,6 +80,11 @@ Run `BUILD_CMD` (the project's real build, so the check matches CI). Skip if `--
 
 **DB-safety guard (only when the build touches a DB).** If the detected `BUILD_CMD` runs migrations as part of the build (e.g. a Node build script that chains `prisma migrate deploy`, or any build that applies `MIGRATION_TOOL` migrations — detect by scanning the build script / target), then a prod DB connection string must NOT be used. If the relevant connection env (`DATABASE_URL`, `DB_URL`, etc.) looks production-y (matches `neon.tech`, `rds.amazonaws.com`, `supabase.co`, a `vercel.app` proxy host, etc.), refuse the build step: `⚠ build skipped — build applies migrations and DATABASE_URL looks production-y (<host>); re-run with a dev DB or pass --skip=build`. If the build does NOT touch a DB (most stacks), skip this guard.
 
+**Build-cache hygiene (avoid stale-cache false positives).** Incremental-cache frameworks reuse a build cache across runs, and a cache left over from a prior build/dev run on a different commit can make a *clean-tree* build fail with a stale-manifest error even though CI (which always builds clean) succeeds. The classic signature is Next.js's `PageNotFoundError: Cannot find module for page: <route>` / `Failed to collect page data for <route>` (often `ENOENT` pointing into `.next/`) — observed on `.well-known/*` and other dynamic routes that build fine in CI. To keep the build check faithful to CI:
+
+1. **Clear the framework cache before building** when the project uses a cache-based framework. Remove only the framework's own *regenerable, gitignored* cache dir if it exists — `.next/` (Next.js) · `.nuxt/` + `.output/` (Nuxt) · `.svelte-kit/` (SvelteKit) · `.astro/` (Astro) · `.turbo/` (Turborepo/Turbopack). **Never** remove `dist/`, `build/`, `out/`, `node_modules/`, or anything git-tracked — confirm the dir is gitignored before deleting. Non-cache stacks: skip this, there is nothing to clear.
+2. **Retry-once backstop.** If a build still fails AND the stderr matches a stale-cache signature (`Cannot find module for page`, `Failed to collect page data`, or an `ENOENT` referencing the cache dir), clear the cache (step 1) and re-run `BUILD_CMD` exactly once. Report ✗ only if the clean rebuild also fails; if the rebuild passes, report ✓ and note `(first attempt failed on a stale-cache artifact — passed clean)`. This prevents a regenerable-cache quirk from producing a NO-GO.
+
 ### 5. schema_drift (only when MIGRATION_TOOL supports it)
 
 Schema-vs-migrations consistency, using the tool's own drift command: