@codeyam-editor/codeyam-editor 0.1.5 → 0.1.7

package/npm/fleet-destroy-safety.js

@@ -11,27 +11,161 @@
 //
 // Pure logic only — no I/O, no env reads, no clock, no global state.
 
+// Concurrent-gcloud count above which a pile-up is itself evidence that the
+// operator plane is resource-throttled rather than credential-broken. Measured
+// 2026-07-29: 16 concurrent gcloud processes at load 8.49 with the cgroup near
+// MemoryHigh, against a steady state of 0-2. Set well above steady state so a
+// couple of ordinary in-flight polls never read as a pile-up.
+const GCLOUD_PILEUP_THRESHOLD = 8;
+
+// Fraction of the cgroup's memory.high at which memory counts as throttling
+// pressure. MUST stay below the 0.874 that actually occurred on 2026-07-29, or
+// the incident goes undetected and this whole change is inert — there is a
+// regression test pinning exactly that.
+//
+// Deliberately NOT fleet-memory.decideMemoryDrain, which looks superficially like
+// the same decision and is the wrong signal twice over:
+//   1. WRONG QUANTITY. It reads process.memoryUsage().rss — the node process
+//      alone. memory.current is the whole CGROUP, including the 16 gcloud
+//      subprocesses. Under a fork storm the pressure lives precisely in what RSS
+//      excludes, so RSS systematically under-reads this condition.
+//   2. WRONG THRESHOLD. Its soft cap is 1500 MB = 97.7% of the observed
+//      memory.high, but the incident sat at 87.4% — it returns false at the
+//      measured value.
+// The two coexist because they answer different questions: decideMemoryDrain
+// asks "should I admit another heavy job?", this asks "is the plane too starved
+// to trust its own probes?".
+const MEMORY_PRESSURE_RATIO = 0.85;
+
+// The recovery for a resource-throttled operator plane. Named once here so the
+// refusal message, the log line, and the tests can never drift apart.
+const THROTTLE_NEXT_ACTION = 'systemctl restart codeyam-dashboard';
+
+// Classify whether the operator plane is RESOURCE-THROTTLED (starved) rather
+// than credential-broken, from the cheap local pressure signals server.js reads.
+// Neither input spawns a subprocess — which matters, because spawning one is
+// exactly what fails when this condition holds.
+//   memoryCurrent       the cgroup's memory.current, in bytes
+//   memoryHigh          the cgroup's memory.high, in bytes ('max' when the cgroup
+//                       is unlimited, which yields no ratio and so no signal)
+//   gcloudProcessCount  concurrent gcloud processes on the host
+// Returns { throttled, signals }: `signals` names the evidence, so the refusal
+// message can cite WHY it concluded throttling instead of asserting it. An absent
+// or unreadable signal contributes nothing rather than defaulting to pressure —
+// fabricating pressure would relabel a REAL auth break as a memory problem, which
+// is the same class of misdiagnosis in the opposite direction.
+function classifyOperatorThrottle({ memoryCurrent, memoryHigh, gcloudProcessCount } = {}) {
+  const signals = [];
+  const cur = Number(memoryCurrent);
+  const high = Number(memoryHigh);
+  if (Number.isFinite(cur) && Number.isFinite(high) && high > 0) {
+    const ratio = cur / high;
+    if (ratio >= MEMORY_PRESSURE_RATIO) {
+      signals.push(`${Math.round(ratio * 100)}% of the cgroup memory throttle`);
+    }
+  }
+  const procs = Number(gcloudProcessCount);
+  if (Number.isFinite(procs) && procs >= GCLOUD_PILEUP_THRESHOLD) {
+    signals.push(`${procs} concurrent gcloud processes`);
+  }
+  return { throttled: signals.length > 0, signals };
+}
+
 // Classify whether a destructive removal (hard destroy or --shrink) must be
-// REFUSED because the operator's own side is faulted, from the two booleans
-// server.js computes. Returns { blocked, reason }: blocked is true when the
-// operator's gcloud auth is degraded OR a fleet-wide unreachable spike is in
-// progress — the signature of a laptop-side fault (which makes EVERY VM read
-// unreachable), NOT N genuinely-dead VMs. authDegraded takes precedence in the
-// reason because it is the upstream cause (a broken operator auth is what
-// produces the fleet-wide false-unreachable spike in the first place), so the
-// message points at the thing to fix.
-//   authDegraded  state.operatorAuthDegraded — operator gcloud auth is broken
-//   fleetWide     fleetWideUnreachableNow() — N+ VMs unreachable at once
-function classifyDestroyBlock({ authDegraded, fleetWide } = {}) {
+// REFUSED because the operator's own side is faulted, from the facts server.js
+// computes. Returns { blocked, kind, reason, nextAction }: blocked is true when
+// the operator's plane is faulted (auth degraded) OR a fleet-wide unreachable
+// spike is in progress — the signature of a host-side fault (which makes EVERY VM
+// read unreachable), NOT N genuinely-dead VMs.
+//
+// The `kind` split exists because a throttled plane and a broken credential have
+// OPPOSITE recoveries, and reporting the wrong one is the 2026-07-29 defect: the
+// banner sent the operator to fix an SA binding that was perfectly healthy, or to
+// reach for override-safety — punching through the one guard that exists because
+// a false-unreachable cascade permanently deleted VM2/3/4 on 2026-06-26. The
+// correct action, restarting the dashboard, was named nowhere.
+//
+// A throttled verdict requires BOTH halves of the evidence: the auth probe
+// produced no answer (authProbeFailed — a failed invocation, not a failed
+// credential) AND local pressure corroborates it. Empty probe output on its own
+// stays inconclusive and keeps the auth reason, so a transient hiccup is never
+// relabeled a memory problem; a genuine auth ERROR is never reclassified at all,
+// no matter how loaded the host is.
+//
+// What this does NOT do is let anything through. Every degraded classification
+// returns blocked: true — the refusal was correct, only its diagnosis was wrong.
+//   authDegraded      state.operatorAuthDegraded — the operator plane is faulted
+//   authProbeFailed   the auth verdict's kind was 'probe-failed' (empty output,
+//                     no error message) rather than 'auth'
+//   memoryCurrent     the cgroup's memory.current in bytes (see
+//   memoryHigh        the cgroup's memory.high in bytes    classifyOperatorThrottle)
+//   gcloudProcessCount concurrent gcloud processes on the host
+//   fleetWide         fleetWideUnreachableNow() — N+ VMs unreachable at once
+function classifyDestroyBlock({ authDegraded, authProbeFailed, memoryCurrent, memoryHigh, gcloudProcessCount, fleetWide } = {}) {
   if (authDegraded) {
-    return { blocked: true, reason: 'operator gcloud auth degraded' };
+    const pressure = classifyOperatorThrottle({ memoryCurrent, memoryHigh, gcloudProcessCount });
+    if (authProbeFailed && pressure.throttled) {
+      return {
+        blocked: true,
+        kind: 'throttled',
+        reason: `operator plane resource-exhausted (${pressure.signals.join(', ')}) — the auth probe was starved, not denied`,
+        nextAction: THROTTLE_NEXT_ACTION,
+      };
+    }
+    return {
+      blocked: true,
+      kind: 'auth',
+      reason: 'operator gcloud auth degraded',
+      nextAction: 'resolve auth (SA binding) — scripts/operator/setup-service-account.sh',
+    };
   }
   if (fleetWide) {
-    return { blocked: true, reason: 'fleet-wide unreachable spike in progress (operator-side fault signature)' };
+    return {
+      blocked: true,
+      kind: 'fleet-wide',
+      reason: 'fleet-wide unreachable spike in progress (operator-side fault signature)',
+      nextAction: 'wait out the spike',
+    };
   }
+  // The NOT-blocked shape stays exactly { blocked, reason } — `kind` and
+  // `nextAction` describe a fault, and there is no fault here to describe.
   return { blocked: false, reason: null };
 }
 
+// Classify a non-Force destroy's unpushed-commit INTENT decision from the WARM
+// ahead-count the dashboard reads off /api/session-info, mirroring the pure
+// decision shape of classifyDestroyBlock. The three outcomes:
+//   ahead number > 0        → REFUSE: unpushed work exists (Force-recoverable)
+//   ahead number === 0      → PROCEED: verified clean
+//   ahead null / undefined  → REFUSE: could NOT verify (editor unreachable /
+//                             field absent) — a DISTINCT refusal, never conflated
+//                             with "VM down", and Force-recoverable
+// Returns { refuse, forceable, outcome, msg }: `outcome` is the
+// logDestroyDecision attribution token (null when proceeding); `msg` is the
+// operator-facing refusal text (null when proceeding). Pure — the caller owns the
+// warm probe, the cached fallback, the logging, and the return; this only maps
+// ahead → decision so it is unit-testable in isolation (the way the cold-SSH
+// version never was).
+function classifyUnpushedDestroy({ n, ahead } = {}) {
+  if (typeof ahead === 'number' && ahead > 0) {
+    return {
+      refuse: true,
+      forceable: true,
+      outcome: 'REFUSED:unpushed',
+      msg: `VM-${n} has ${ahead} unpushed commit(s) — not destroying. Use Force to override.`,
+    };
+  }
+  if (ahead === 0) {
+    return { refuse: false, forceable: false, outcome: null, msg: null };
+  }
+  return {
+    refuse: true,
+    forceable: true,
+    outcome: 'REFUSED:unverifiable',
+    msg: `VM-${n} — could not verify unpushed commits (editor unreachable). Use Force to destroy anyway.`,
+  };
+}
+
 // Build the single attributable destroy-decision log line. Mirrors the
 // performAutoReset "confirmed … not fleet-wide" template so every destroy —
 // proceed OR refused, across every trigger source — is diagnosable from one
@@ -49,7 +183,90 @@ function formatDestroyDecision(info = {}) {
   );
 }
 
+// Build the ENTRY line for a destroy request, emitted before any probe runs —
+// the third sibling of formatDestroyDecision (the up-front DECISION) and
+// formatDestroyOutcome (the terminal JOB fate). Without it a request that died
+// mid-flight left NO record at all: on 2026-07-29 two destroy POSTs both ended in
+// HTTP 000 and the log's last entry was an earlier refusal, so the operator could
+// not tell whether a delete had started against their VM — the worst possible
+// answer to "did you delete it?".
+//
+// It keeps the `destroy-decision:` prefix so ONE grep still finds a request's
+// whole life, and carries only what is known at entry. It deliberately does NOT
+// render authDegraded/fleetWide/hasSession: those are not measured yet, and
+// printing `false` for an unmeasured verdict would read as "auth was fine" —
+// exactly the false diagnosis this change exists to remove.
+function formatDestroyAttempt(info = {}) {
+  const remote = info.remote ? `${info.remote.ip || '?'}/${info.remote.ua || '?'}` : 'n/a';
+  return (
+    `destroy-decision: VM-${info.n} attempt source=${info.source} force=${!!info.force} ` +
+    `override=${!!info.overrideSafety} remote=${remote}`
+  );
+}
+
+// Render the operator-facing REFUSAL for a blocked destructive removal, pairing
+// the verdict's reason with its verdict-specific recovery. Extracted from
+// server.js so the "a throttled refusal never sends the operator at auth"
+// property is assertable at the MESSAGE level, not just on the reason field.
+//
+// The recovery renders as the greppable `Next valid action:` contract (CLAUDE.md
+// CLI error conventions) rather than as prose. override-safety is mentioned LAST
+// and never as the primary fix: it bypasses the guard that exists because a
+// false-unreachable cascade permanently deleted VM2/3/4 on 2026-06-26, and
+// putting it beside the real recovery is what made two operators reach for it
+// within one session. `detail` lets the shrink path swap the wording while
+// keeping an identical recovery contract, so the two destructive paths that share
+// operatorFaultVerdict can never give conflicting advice for one fault.
+function formatDestroyRefusal({ n, reason, nextAction, detail } = {}) {
+  const what = detail || `refusing to destroy VM-${n}`;
+  return (
+    `REFUSED: ${reason} — ${what}; a false-unreachable storm can delete healthy VMs.\n` +
+    `Next valid action: ${nextAction}\n` +
+    'If this destructive action is genuinely intended right now, pass override-safety.'
+  );
+}
+
+// Render the refusal for a destroy whose DECISION exceeded its wall-clock budget.
+// HTTP 000 is the worst possible answer to "did you delete my VM?" — it is
+// indistinguishable from a delete that started and lost its response, and it is
+// what two destroy POSTs returned on 2026-07-29 after 150s and 240s.
+//
+// The wording is deliberately "no verdict" and "no delete CONFIRMED dispatched",
+// not "nothing happened": the in-flight decision may still resolve after the
+// bound elapses, so claiming otherwise would be a second false certainty. It
+// points at the `destroy-decision:` grep instead, which the entry-time attempt
+// line guarantees is populated.
+function formatDestroyBoundExceeded({ n, budgetMs } = {}) {
+  return (
+    `REFUSED: no destroy verdict for VM-${n} within ${Math.round(budgetMs / 1000)}s — ` +
+    'the dashboard is not answering, which usually means it is resource-throttled.\n' +
+    `Next valid action: ${THROTTLE_NEXT_ACTION}\n` +
+    `No delete was confirmed dispatched; grep the log for \`destroy-decision: VM-${n}\` to see how far this request got.`
+  );
+}
+
+// Build the single TERMINAL-OUTCOME journal line for a completed destroy JOB —
+// the sibling of formatDestroyDecision, which records the up-front DECISION. The
+// decision line alone was a blind spot: diagnosing the VM-8 silent refusal
+// surfaced only `destroy-decision … → proceed:delete`, nothing about how the job
+// itself ended, so a job that refused/errored after the decision was invisible.
+// With this line a completed destroy's fate is one `grep destroy-outcome` away.
+// `outcome` is the caller-computed terminal string: `done`, `refused:<kind>`, or
+// `error code=<n>`. Pure format only — the caller owns the classification.
+function formatDestroyOutcome(info = {}) {
+  return `destroy-outcome: VM-${info.n} ${info.outcome}`;
+}
+
 module.exports = {
+  GCLOUD_PILEUP_THRESHOLD,
+  MEMORY_PRESSURE_RATIO,
+  THROTTLE_NEXT_ACTION,
   classifyDestroyBlock,
+  classifyOperatorThrottle,
+  classifyUnpushedDestroy,
+  formatDestroyAttempt,
+  formatDestroyBoundExceeded,
   formatDestroyDecision,
+  formatDestroyOutcome,
+  formatDestroyRefusal,
 };

package/npm/fleet-early-roster.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// npm/fleet-early-roster.js — decides WHEN an in-flight `add` earns its roster
+// entry.
+//
+// Background (vm--batch-add-must-roster-and-wire-each-vm): rostering used to
+// happen in exactly one place on the live add path — `startJob`'s onSuccess
+// callback — which only fires when the whole ~28-minute add script exits 0. A
+// VM whose container came up but whose add later failed (wiring, reachability,
+// a dashboard SIGKILL) was therefore never rostered, and an unrostered VM is
+// invisible to `reconcile-ingress`, which skips it. That produced a deadlock:
+//
+//   not rostered → reconcile skips → no backend service → LB 503 →
+//   not reachable → bootstrap recovery retries → exhausted → still not rostered
+//
+// Observed live 2026-07-20 provisioning VM-4..VM-11: the roster stayed `[1,2,3]`
+// for a `count=8` add even though every container was `Up` and serving 200
+// locally. The only recovery was to destroy and re-add one at a time.
+//
+// The fix is to roster EARLY — as soon as the instance exists and the container
+// gate has passed — so a later-stage failure leaves a *rostered, reconcilable*
+// VM that the periodic sweep can finish wiring, rather than an invisible one.
+// The add script announces that moment by printing a marker line; `startJob`
+// taps the child's stdout and hands the accumulated text here.
+//
+// This module is PURE (no fs, no network, no roster writes) so the "has this VM
+// earned its roster entry yet" rule is unit-testable without a live VM. The
+// actual `addToRoster` write stays in server.js.
+
+// The marker the add script prints once its container gate passes. Chosen to
+// match the existing `CY_DEGRADED` marker convention that `startJob` already
+// scans for, so both live in the same namespace and are equally greppable in a
+// job log.
+const ROSTER_MARKER = 'CY_ROSTER';
+
+// Build the marker line the add script emits. Kept here (rather than inlined in
+// server.js) so the emitter and the parser can never drift apart — a test that
+// round-trips `parseRosterMarkers(rosterMarkerLine(n))` pins them together.
+function rosterMarkerLine(n) {
+  return `${ROSTER_MARKER} ${n}`;
+}
+
+// Extract every VM number announced by a roster marker in `text`.
+//
+// Scans the FULL accumulated buffer rather than a single chunk: child stdout
+// arrives in arbitrary chunks that can split a line mid-marker, so a
+// chunk-local parse would miss (or double-count) a marker straddling a
+// boundary. Re-parsing the whole buffer is idempotent and cheap relative to the
+// ~28-minute job it rides along with.
+//
+// Returns unique numbers in ascending order. Junk (`CY_ROSTER abc`,
+// `CY_ROSTER 1.5`, a bare `CY_ROSTER`) is dropped — the roster is a set of
+// VM-number integers, so a malformed marker must never poison it.
+function parseRosterMarkers(text) {
+  if (typeof text !== 'string' || text === '') return [];
+  const out = new Set();
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t.startsWith(`${ROSTER_MARKER} `)) continue;
+    const rest = t.slice(ROSTER_MARKER.length + 1).trim();
+    // Reject anything that is not a plain positive integer. `Number()` alone
+    // would accept '1.5', '0x2', and ' 3 '; the regex gate keeps it strict.
+    if (!/^\d+$/.test(rest)) continue;
+    const n = Number(rest);
+    if (Number.isInteger(n) && n > 0) out.add(n);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+// Should VM `n` be rostered right now, given the job output so far?
+//
+// `alreadyRostered` is the caller's own latch — server.js flips it after the
+// first successful write so a marker sitting in the buffer for the rest of the
+// job doesn't re-trigger a write on every subsequent chunk. (The roster write
+// is itself idempotent, so this is an efficiency guard, not a correctness one.)
+function shouldEarlyRoster({ text, vmNumber, alreadyRostered } = {}) {
+  if (alreadyRostered) return false;
+  if (!Number.isInteger(vmNumber) || vmNumber <= 0) return false;
+  return parseRosterMarkers(text).includes(vmNumber);
+}
+
+module.exports = {
+  ROSTER_MARKER,
+  rosterMarkerLine,
+  parseRosterMarkers,
+  shouldEarlyRoster,
+};

package/npm/fleet-effect-poll.js

@@ -0,0 +1,110 @@
+'use strict';
+// Self-healing cycle guard for the Fleet Dashboard's slow effect poll
+// (scripts/operator/fleet-dashboard/server.js requires this). No gcloud/SSH
+// I/O — this module owns the control-flow guarantee ONLY; the server keeps its
+// gather edges and worker pools.
+//
+// The bug this fixes: `pollEffects` guards against overlap with a
+// `effectPollRunning` flag (two concurrent full cycles would double the gcloud
+// load), releasing it in a `finally` that runs only AFTER
+// `await Promise.all(...)` of the reachable + launcher-strand sweeps. On
+// 2026-07-09 a single probe's callback never fired (an SSH/docker-exec against
+// VM-8, whose GCP instance had been deleted mid-session), so that awaited
+// promise never resolved, the `finally` never ran, and `effectPollRunning`
+// stayed `true` forever — every subsequent 45s tick early-returned and fleet
+// readiness (iapAccess, backendHealth, readiness, launcher-strand self-heal)
+// froze fleet-wide until the dashboard was restarted.
+//
+// Two guarantees make that freeze impossible:
+//   makeGuardedCycle — the no-overlap guard is kept (it's correct), but its
+//     release is made unconditional: the returned promise ALWAYS settles, either
+//     when the tasks finish or when a whole-cycle watchdog fires, and the guard
+//     flag is cleared in a `finally` either way. A hung task can no longer strand
+//     the next tick.
+//   withTimeout — wraps a single probe promise so a never-firing callback
+//     resolves to a safe fallback verdict instead of hanging the sweep.
+
+// Wrap a promise so it can never hang the caller: resolve to `fallback` if
+// `promise` has not settled within `ms`, and also on rejection (a probe that
+// throws must degrade gracefully, never reject the whole sweep). `ms <= 0`
+// disables the timeout and just awaits the promise (rejections still fold to
+// `fallback`), so a caller can opt a leg out without branching. Whichever of
+// (settle, timeout) happens first wins; the other is a no-op.
+function withTimeout(promise, ms, fallback) {
+  const settled = Promise.resolve(promise).catch(() => fallback);
+  if (!(ms > 0)) return settled;
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (val) => { if (!done) { done = true; resolve(val); } };
+    // NOT unref'd: this timer is load-bearing — it resolves the promise the
+    // caller awaits, so letting the event loop exit before it fires would leave
+    // the await hung. It is cleared the instant the real promise settles, so it
+    // holds the loop open only for the (short) timeout window.
+    const timer = setTimeout(() => finish(fallback), ms);
+    settled.then((val) => { clearTimeout(timer); finish(val); });
+  });
+}
+
+// Build a guarded cycle runner. `run(tasks)` executes an array of zero-arg async
+// task factories (or bare promises) under a no-overlap guard:
+//   - while a cycle is in flight, a second `run(...)` returns `{ skipped: true }`
+//     immediately without launching the tasks — the no-overlap contract.
+//   - the returned promise ALWAYS settles: when the tasks finish, or — if
+//     `watchdogMs > 0` — when the whole-cycle watchdog fires first (returning
+//     `{ wedged: true }`). Either way the guard flag is cleared in a `finally`,
+//     so the NEXT tick can always run. A never-resolving task therefore cannot
+//     permanently wedge the loop (the 2026-07-09 freeze).
+// `onWedge(elapsedMs)` (optional) is called when the watchdog fires, so the
+// caller can log a wedge warning. A task that rejects is swallowed (one bad probe
+// must not fail the whole cycle); the caller composes concurrency/ordering.
+function makeGuardedCycle(opts) {
+  const o = opts || {};
+  const watchdogMs = o.watchdogMs > 0 ? o.watchdogMs : 0;
+  const onWedge = typeof o.onWedge === 'function' ? o.onWedge : null;
+  let running = false;
+  const run = async (tasks) => {
+    if (running) return { skipped: true };
+    running = true;
+    try {
+      const work = Promise.all((tasks || []).map((t) => (typeof t === 'function' ? t() : t)))
+        .then(() => false, () => false); // settle to `wedged=false`; swallow a rejecting probe
+      let wedged = false;
+      if (watchdogMs > 0) {
+        wedged = await new Promise((resolve) => {
+          // NOT unref'd: this watchdog resolves the promise the caller awaits, so
+          // it must keep the loop alive until it fires (or the work settles first
+          // and clears it). Unref'ing it would let a standalone await hang.
+          const timer = setTimeout(() => resolve(true), watchdogMs);
+          work.then((w) => { clearTimeout(timer); resolve(w); });
+        });
+      } else {
+        await work;
+      }
+      if (wedged && onWedge) { try { onWedge(watchdogMs); } catch (e) { /* logging must never re-wedge */ } }
+      return { skipped: false, wedged };
+    } finally {
+      // Unconditional release — the whole point. Whether the tasks finished or
+      // the watchdog fired, the guard is cleared so the next tick proceeds. Any
+      // still-pending task keeps running detached, but holds no guard.
+      running = false;
+    }
+  };
+  return { run };
+}
+
+// A roster entry whose Add errored out is an `add-failed` ghost: its GCP instance
+// may be half-created or already reconciled away, so an SSH/docker-exec strand
+// probe against it is the exact call that hung the 2026-07-09 sweep (VM-8). The
+// strand selection skips it — a failed Add is owned by the reachable / vanish
+// reconcilers, not the launcher-strand self-heal. `withTimeout` (above) is the
+// general backstop for any hung probe; this removes the doomed probe at the
+// source for the named trigger.
+function isAddFailedGhost(job) {
+  return !!(job && job.state === 'error' && job.action === 'add');
+}
+
+module.exports = {
+  withTimeout,
+  makeGuardedCycle,
+  isAddFailedGhost,
+};

package/npm/fleet-env.js

@@ -99,6 +99,89 @@ function envToDict(text) {
   return dict;
 }
 
+// Canonicalize a git repo URL for identity comparison. Strips any embedded
+// credentials (`user@` / `user:pass@`), normalizes the two forms GitHub emits
+// — `git@host:owner/repo` (scp-like) and `https://host/owner/repo` — to a
+// single `host/owner/repo` shape, drops a trailing `.git` and trailing
+// slashes, and lowercases the result. Returns '' for null/empty. This makes
+// `https://github.com/sfpatchworks/back-office.git` equal to
+// `git@github.com:sfpatchworks/back-office`, so the per-slot env tag matches
+// the fleet repo regardless of which URL form each was recorded in.
+function normalizeRepoUrl(url) {
+  let s = String(url == null ? '' : url).trim();
+  if (s === '') return '';
+  // scp-like `user@host:owner/repo` → `host/owner/repo` (only when there is no
+  // `://` scheme; `[^@/:]+@[^:/]+:` guarantees a single `host:` colon, not a
+  // scheme's `://`).
+  const scp = s.match(/^[^@/:]+@([^:/]+):(.+)$/);
+  if (scp) {
+    s = `${scp[1]}/${scp[2]}`;
+  } else {
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, ''); // strip scheme
+    s = s.replace(/^[^@/]+@/, '');                       // strip credentials
+  }
+  s = s.replace(/\/+$/, '').replace(/\.git$/i, '');
+  return s.toLowerCase();
+}
+
+// Classify whether a slot's persisted env may be re-applied to the repo the
+// slot now serves. Returns one of:
+//   'apply'         — metaRepo is non-empty and normalizes equal to currentRepo
+//   'skip-mismatch' — metaRepo is non-empty but normalizes differently
+//   'skip-untagged' — metaRepo is empty/absent (a legacy file with no meta
+//                     sidecar; treated as unattributed and never replayed)
+// This is the guard that stops a prior project's env from silently bleeding
+// onto a new, unrelated project that reuses the same VM slot number.
+function classifyEnvApplicability({ metaRepo, currentRepo } = {}) {
+  const tagged = normalizeRepoUrl(metaRepo);
+  if (tagged === '') return 'skip-untagged';
+  return tagged === normalizeRepoUrl(currentRepo) ? 'apply' : 'skip-mismatch';
+}
+
+// Prisma datasource providers we know how to scheme-check a `DATABASE_URL`
+// against. Used to skip the generator block's `provider = "prisma-client-js"`
+// and match only the datasource `provider`.
+const DB_PROVIDERS = new Set([
+  'sqlite', 'postgresql', 'postgres', 'mysql', 'sqlserver', 'mongodb', 'cockroachdb',
+]);
+
+// Advisory: detect a Prisma datasource provider vs `DATABASE_URL` scheme
+// mismatch. Returns a short, actionable warning string, or null. Only fires
+// when `schemaText` declares a recognized datasource `provider` AND `envText`
+// declares a `DATABASE_URL` whose scheme is incompatible with it — currently
+// the two directions that actually broke a live project: provider `sqlite`
+// with a `postgresql`/`postgres` URL, or provider `postgresql`/`postgres`
+// with a `file:` (SQLite) URL. Returns null when there is no schema, no
+// recognized datasource provider, no `DATABASE_URL`, or they agree — so
+// non-Prisma / no-DB projects are a silent no-op. Pure: both texts are passed
+// in by the I/O caller.
+function detectDbProviderMismatch(envText, schemaText) {
+  const schema = String(schemaText == null ? '' : schemaText);
+  let provider = null;
+  const re = /provider\s*=\s*"([^"]+)"/g;
+  let m;
+  while ((m = re.exec(schema)) !== null) {
+    const p = m[1].toLowerCase();
+    if (DB_PROVIDERS.has(p)) { provider = p; break; }
+  }
+  if (!provider) return null;
+  const dict = envToDict(envText) || {};
+  const url = dict.DATABASE_URL;
+  if (!url) return null;
+  const scheme = (String(url).match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/) || [])[1];
+  if (!scheme) return null;
+  const s = scheme.toLowerCase();
+  const isPostgres = s === 'postgresql' || s === 'postgres';
+  const isSqlite = s === 'file';
+  if (provider === 'sqlite' && isPostgres) {
+    return `DATABASE_URL scheme "${scheme}" is a Postgres URL but the Prisma schema declares provider = "sqlite" — the app will fail to open its database. Re-enter env with a file: URL, or fix the schema provider.`;
+  }
+  if ((provider === 'postgresql' || provider === 'postgres') && isSqlite) {
+    return `DATABASE_URL scheme "file" is a SQLite URL but the Prisma schema declares provider = "${provider}" — the app expects a Postgres connection string. Re-enter env accordingly.`;
+  }
+  return null;
+}
+
 // Wrap a parsed launch-form env dict in the cloud:up bootstrap-child-env
 // shape: spreads `envDict` so the keys land in the child's `process.env`, and
 // sets `CY_FORWARD_ENV_KEYS` to the comma-separated key list so
@@ -120,6 +203,9 @@ module.exports = {
   envHasSetupTrigger,
   envToDict,
   buildBootstrapChildEnv,
+  normalizeRepoUrl,
+  classifyEnvApplicability,
+  detectDbProviderMismatch,
   FORWARD_ENV_KEYS_ENV,
   KEY_RE,
 };