npm - postgresai - Versions diffs - 0.15.0-rc.6 → 0.15.0-rc.8 - Mend

postgresai 0.15.0-rc.6 → 0.15.0-rc.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -10,9 +10,9 @@ Command-line interface for PostgresAI monitoring and database management.
 npm install -g postgresai
 ```
-Or install the latest beta release explicitly:
+For reproducible installs, pin the 0.15 release explicitly:
 ```bash
-npm install -g postgresai@beta
+npm install -g postgresai@0.15.0
 ```
 Note: in this repository, `cli/package.json` uses a placeholder version (`0.0.0-dev.0`). The real published version is set by the git tag in CI when publishing to npm.

package/bin/postgres-ai.ts CHANGED Viewed

@@ -590,6 +590,208 @@ async function ensureDefaultMonitoringProject(): Promise<PathResolution> {
   return { fs, path, projectDir, composeFile, instancesFile };
 }
+/**
+ * Sanitize a PGAI_TAG value before it is interpolated into the compose backup
+ * filename (`docker-compose.yml.bak-<tag>-<hash8>`). The value flows straight
+ * into a filename via path.resolve, so it is quote-stripped and validated
+ * against a conservative charset: a malformed or hostile tag (e.g.
+ * `../../../tmp/x`, or one carrying a path separator) is rejected to null so it
+ * can never escape projectDir or otherwise poison the backup path. Callers fall
+ * back to a timestamp suffix when this returns null.
+ *
+ * Applied centrally to BOTH tag sources — the .env read (readDeployedTag) and
+ * the OLD tag passed in by callers that rewrite .env first (e.g. local-install)
+ * — so neither path can bypass the validation.
+ */
+function sanitizeTagForBackup(tag: string | null | undefined): string | null {
+  if (tag == null) return null;
+  const stripped = stripMatchingQuotes(tag);
+  return /^[A-Za-z0-9._-]{1,64}$/.test(stripped) ? stripped : null;
+}
+/**
+ * Read the deployed PGAI_TAG out of a project's .env (returns null if absent or
+ * if the value fails {@link sanitizeTagForBackup}). Used only to compute the
+ * compose backup file suffix; callers fall back to a timestamp when this is null.
+ */
+function readDeployedTag(projectDir: string): string | null {
+  const envFile = path.resolve(projectDir, ".env");
+  if (!fs.existsSync(envFile)) return null;
+  const m = fs.readFileSync(envFile, "utf8").match(/^PGAI_TAG=(.+)$/m);
+  return m ? sanitizeTagForBackup(m[1]) : null;
+}
+/**
+ * Validate that a freshly fetched payload is genuinely a postgres_ai
+ * docker-compose.yml, NOT an HTML login/captcha/proxy/maintenance page that a
+ * 200 response can still carry. `downloadText` only checks `response.ok`, so a
+ * non-compose 200 body would otherwise silently clobber a working compose with
+ * junk — strictly worse than keeping the stale-but-valid one.
+ *
+ * Requires:
+ *   - non-empty, and not an obvious HTML document (<!DOCTYPE / <html ...);
+ *   - parseable YAML resolving to an object;
+ *   - a `services` map that contains the keystone `sink-prometheus` service
+ *     (the very service whose VM_AUTH wiring this refresh exists to deliver).
+ */
+function isValidComposeYaml(text: string): boolean {
+  const trimmed = text.trim();
+  if (!trimmed) return false;
+  // Cheap early reject for HTML error/login/proxy pages served with a 200.
+  if (/^<(?:!doctype|html|\?xml)\b/i.test(trimmed)) return false;
+  let doc: unknown;
+  try {
+    doc = yaml.load(trimmed);
+  } catch {
+    return false;
+  }
+  if (!doc || typeof doc !== "object") return false;
+  const services = (doc as { services?: unknown }).services;
+  if (!services || typeof services !== "object") return false;
+  // The keystone service must be present — this is what carries the VM_AUTH_*
+  // wiring that the whole refresh exists to deliver.
+  return Object.prototype.hasOwnProperty.call(services, "sink-prometheus");
+}
+/**
+ * Fetch the target docker-compose.yml for a given list of candidate refs.
+ *
+ * Test-only seam (PGAI_COMPOSE_SOURCE): when NODE_ENV === "test" AND the var is
+ * set to a local file path, the compose is read from disk instead of fetched
+ * over the network — keeping the refresh hermetically testable offline without
+ * exposing a local-file→compose injection surface in a normal user environment.
+ * The production path (GitLab raw fetch) is otherwise unchanged.
+ *
+ * Returns null if nothing could be obtained.
+ */
+async function fetchTargetCompose(refs: string[]): Promise<string | null> {
+  const localSource = process.env.PGAI_COMPOSE_SOURCE;
+  if (process.env.NODE_ENV === "test" && localSource && localSource.trim()) {
+    try {
+      return fs.readFileSync(localSource.trim(), "utf8");
+    } catch {
+      return null;
+    }
+  }
+  for (const ref of refs) {
+    const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
+    try {
+      return await downloadText(url);
+    } catch {
+      // try next ref
+    }
+  }
+  return null;
+}
+/**
+ * Compare two compose documents ignoring trailing-whitespace-only differences,
+ * so a lone trailing-newline delta doesn't trigger needless churn + a backup.
+ */
+function composeContentEqual(a: string, b: string): boolean {
+  return a.replace(/\s+$/, "") === b.replace(/\s+$/, "");
+}
+/**
+ * Refresh the bundled, CLI-owned docker-compose.yml for NON-GIT installs when it
+ * is stale relative to the target stack version (the CLI's own pkg.version).
+ *
+ * Why this exists: docker-compose.yml is a version-coupled static asset. 0.15
+ * added VM basic auth, wiring VM_AUTH_* into the sink-prometheus (VictoriaMetrics)
+ * service and the Grafana datasource. `mon update` already refreshes the compose
+ * for git checkouts via `git pull`, and green-field installs fetch it once via
+ * ensureDefaultMonitoringProject(). But npx / global-npm upgrades are non-git and
+ * only advance PGAI_TAG — leaving the OLD compose in place. That mismatch crashes
+ * sink-prometheus (`missing "VM_AUTH_USERNAME" env var`) and blanks all dashboards.
+ *
+ * Contract:
+ *   - No-op for git checkouts (.git present) — they refresh via `git pull`.
+ *   - No-op when there is no deployed compose yet (bootstrap path handles it).
+ *   - No-op when the deployed compose content already matches the target.
+ *   - No-op (treated exactly like a fetch failure) when the fetched payload does
+ *     not validate as a real compose — keep the existing compose, no backup,
+ *     warn, return false. Prevents an HTML/proxy 200 body from clobbering a
+ *     working compose with junk.
+ *   - Backs up the prior compose before overwriting and NEVER overwrites an
+ *     existing backup, so the first/pristine compose is always preserved across
+ *     repeated runs (the backup name is uniquified by old-content hash).
+ *   - Touches ONLY docker-compose.yml. Never .env / instances.yml / .pgwatch-config.
+ *   - Best-effort: a fetch/validation failure warns and keeps the existing
+ *     compose (the upgrade still proceeds) — we must not turn a metrics-only
+ *     outage into a hard CLI failure.
+ *
+ * @param projectDir monitoring project directory.
+ * @param oldTag the PGAI_TAG of the *deployed* (pre-upgrade) compose, used to
+ *   label the backup. Callers that rewrite .env's PGAI_TAG before this runs
+ *   (e.g. local-install) MUST pass the captured OLD tag here so the backup
+ *   reflects the OLD version. When omitted, it is read from the project's .env.
+ * @returns true if the compose was refreshed, false otherwise.
+ */
+async function refreshBundledComposeIfStale(projectDir: string, oldTag?: string | null): Promise<boolean> {
+  // Git checkouts manage docker-compose.yml via the repo itself (`git pull`).
+  if (fs.existsSync(path.resolve(projectDir, ".git"))) return false;
+  const composeFile = path.resolve(projectDir, "docker-compose.yml");
+  // Nothing deployed yet -> the green-field bootstrap path handles fetching it.
+  if (!fs.existsSync(composeFile)) return false;
+  const refs = [
+    process.env.PGAI_PROJECT_REF,
+    pkg.version,
+    `v${pkg.version}`,
+  ].filter((v): v is string => Boolean(v && v.trim()));
+  const fetched = await fetchTargetCompose(refs);
+  // Validate BEFORE doing anything destructive: an empty body, a fetch failure,
+  // or a non-compose 200 (HTML login/proxy/maintenance page) are all treated
+  // identically — keep the existing compose, write no backup, warn, no-op.
+  if (!fetched || !isValidComposeYaml(fetched)) {
+    console.error(`⚠ Could not refresh docker-compose.yml to ${pkg.version} (no valid compose was retrieved).`);
+    console.error("  Keeping the existing compose. If dashboards are blank after upgrade, re-run this command once network is available.");
+    return false;
+  }
+  // Compare on-disk CONTENT against the freshly fetched target (whitespace-only
+  // diffs ignored). This is correct regardless of when PGAI_TAG was rewritten in
+  // .env (local-install rewrites it before this runs), so we never rely on a
+  // possibly-stale tag heuristic.
+  const existing = fs.readFileSync(composeFile, "utf8");
+  if (composeContentEqual(existing, fetched)) return false; // already current
+  // Label the backup with the OLD (deployed) tag. Callers that already rewrote
+  // .env pass it in (raw); otherwise read it from .env. Sanitize centrally so the
+  // caller-supplied oldTag (e.g. local-install's previousTag) cannot bypass the
+  // filename validation — a hostile/malformed tag falls back to the timestamp.
+  const deployedTag = sanitizeTagForBackup(oldTag ?? readDeployedTag(projectDir));
+  const tagPart = deployedTag ?? new Date().toISOString().replace(/[:.]/g, "-");
+  // Uniquify with a short hash of the OLD content so repeated runs (e.g.
+  // update-config, where PGAI_TAG never advances) cannot overwrite the first,
+  // pristine backup. Always preserve the original compose.
+  const oldHash = crypto.createHash("sha256").update(existing).digest("hex").slice(0, 8);
+  const backup = path.resolve(projectDir, `docker-compose.yml.bak-${tagPart}-${oldHash}`);
+  let backupName: string | null = null;
+  try {
+    // "wx" => fail if the backup already exists, so we never clobber a prior
+    // backup. If this exact old content was already backed up, that's fine —
+    // the pristine copy is already on disk under the same name.
+    fs.writeFileSync(backup, existing, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    backupName = path.basename(backup);
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e && e.code === "EEXIST") {
+      // Identical old content already backed up under this name — keep it.
+      backupName = path.basename(backup);
+    }
+    // Any other error: non-fatal, proceed with the refresh even without a backup.
+  }
+  fs.writeFileSync(composeFile, fetched, { encoding: "utf8", mode: 0o600 });
+  const backupNote = backupName ? ` (backup: ${backupName})` : "";
+  console.log(`✓ Refreshed docker-compose.yml to ${pkg.version}${backupNote}`);
+  return true;
+}
 /**
  * Get configuration from various sources
  * @param opts - Command line options
@@ -2427,10 +2629,15 @@ mon
     let existingReplicatorPassword: string | null = null;
     let existingVmAuthUsername: string | null = null;
     let existingVmAuthPassword: string | null = null;
+    // Capture the OLD (deployed) tag BEFORE we rewrite PGAI_TAG below, so the
+    // compose-refresh backup is labeled with the version being upgraded FROM.
+    let previousTag: string | null = null;
     if (fs.existsSync(envFile)) {
       const existingEnv = fs.readFileSync(envFile, "utf8");
       // Extract existing values (except tag - always use CLI version)
+      const previousTagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
+      if (previousTagMatch) previousTag = previousTagMatch[1].trim();
       const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
       if (registryMatch) existingRegistry = registryMatch[1].trim();
       const pwdMatch = existingEnv.match(/^GF_SECURITY_ADMIN_PASSWORD=(.+)$/m);
@@ -2463,6 +2670,14 @@ mon
     envLines.push(`VM_AUTH_PASSWORD=${existingVmAuthPassword || crypto.randomBytes(18).toString("base64")}`);
     fs.writeFileSync(envFile, envLines.join("\n") + "\n", { encoding: "utf8", mode: 0o600 });
+    // Non-git upgrade safety: bring the CLI-owned compose up to the target version
+    // so newly-required service wiring (e.g. VM_AUTH_* on sink-prometheus) is present.
+    // Compares deployed compose CONTENT against the target, so it's correct even
+    // though PGAI_TAG was just rewritten above. No-op for git checkouts / when current.
+    // Pass the OLD tag (captured before the .env rewrite) so the backup is labeled
+    // with the version we're upgrading FROM, not the new one.
+    await refreshBundledComposeIfStale(projectDir, previousTag);
     if (opts.tag) {
       console.log(`Using image tag: ${imageTag}\n`);
     }
@@ -3069,6 +3284,12 @@ mon
       console.log("(existing values were preserved; missing keys filled with safe defaults)\n");
     }
+    // Non-git installs: refresh the CLI-owned compose so it matches the target
+    // stack version. Otherwise newly-required service wiring (e.g. VM_AUTH_* on
+    // sink-prometheus, added in 0.15) is missing and VictoriaMetrics crashes.
+    // No-op for git checkouts and when the compose already matches.
+    await refreshBundledComposeIfStale(projectDir);
     const code = await runCompose(["run", "--rm", "sources-generator"]);
     if (code !== 0) process.exitCode = code;
   });
@@ -3120,7 +3341,14 @@ mon
         const { stdout: pullOut } = await execFilePromise("git", ["pull", "origin", currentBranch]);
         console.log(pullOut);
       } else {
-        console.log("(not a git checkout — skipping git fetch/pull and going straight to image pull)");
+        // npx / global-npm installs are non-git: `git pull` can't refresh the
+        // compose, so bring the CLI-owned docker-compose.yml up to the target
+        // version in place (with a backup). This is what wires VM_AUTH_* into
+        // sink-prometheus for users upgrading from a pre-0.15 (no-VM-auth) stack.
+        // The helper logs only when it actually refreshes/warns, so don't
+        // pre-announce a refresh that may turn out to be a no-op.
+        console.log("(not a git checkout — checking bundled docker-compose.yml)");
+        await refreshBundledComposeIfStale(projectDir);
       }
       // Step 3: pull new images.
@@ -5068,6 +5296,16 @@ mcp
     }
   });
-program.parseAsync(process.argv).finally(() => {
-  closeReadline();
-});
+// Only parse argv when run as the CLI entrypoint (npx / `bun postgres-ai.ts`).
+// When the module is imported (e.g. unit tests exercising the exported helpers),
+// skip the auto-parse so importing doesn't kick off the whole command tree.
+// `import.meta.main` is honored both under bun and in the node-targeted build.
+if (import.meta.main) {
+  program.parseAsync(process.argv).finally(() => {
+    closeReadline();
+  });
+}
+// Exported for unit tests (the CLI surface above is unaffected; these are the
+// same functions used by the `mon` commands).
+export { refreshBundledComposeIfStale, readDeployedTag, isValidComposeYaml };

package/dist/bin/postgres-ai.js CHANGED Viewed

@@ -13423,7 +13423,7 @@ var {
 // package.json
 var package_default = {
   name: "postgresai",
-  version: "0.15.0-rc.6",
+  version: "0.15.0-rc.8",
   description: "postgres_ai CLI",
   license: "Apache-2.0",
   private: false,
@@ -16254,7 +16254,7 @@ var Result = import_lib.default.Result;
 var TypeOverrides = import_lib.default.TypeOverrides;
 var defaults = import_lib.default.defaults;
 // package.json
-var version = "0.15.0-rc.6";
+var version = "0.15.0-rc.8";
 var package_default2 = {
   name: "postgresai",
   version,
@@ -33887,6 +33887,91 @@ async function ensureDefaultMonitoringProject() {
   }
   return { fs: fs8, path: path7, projectDir, composeFile, instancesFile };
 }
+function sanitizeTagForBackup(tag) {
+  if (tag == null)
+    return null;
+  const stripped = stripMatchingQuotes(tag);
+  return /^[A-Za-z0-9._-]{1,64}$/.test(stripped) ? stripped : null;
+}
+function readDeployedTag(projectDir) {
+  const envFile = path7.resolve(projectDir, ".env");
+  if (!fs8.existsSync(envFile))
+    return null;
+  const m = fs8.readFileSync(envFile, "utf8").match(/^PGAI_TAG=(.+)$/m);
+  return m ? sanitizeTagForBackup(m[1]) : null;
+}
+function isValidComposeYaml(text) {
+  const trimmed = text.trim();
+  if (!trimmed)
+    return false;
+  if (/^<(?:!doctype|html|\?xml)\b/i.test(trimmed))
+    return false;
+  let doc2;
+  try {
+    doc2 = load(trimmed);
+  } catch {
+    return false;
+  }
+  if (!doc2 || typeof doc2 !== "object")
+    return false;
+  const services = doc2.services;
+  if (!services || typeof services !== "object")
+    return false;
+  return Object.prototype.hasOwnProperty.call(services, "sink-prometheus");
+}
+async function fetchTargetCompose(refs) {
+  const localSource = process.env.PGAI_COMPOSE_SOURCE;
+  if (false) {}
+  for (const ref of refs) {
+    const url = `https://gitlab.com/postgres-ai/postgres_ai/-/raw/${encodeURIComponent(ref)}/docker-compose.yml`;
+    try {
+      return await downloadText(url);
+    } catch {}
+  }
+  return null;
+}
+function composeContentEqual(a, b) {
+  return a.replace(/\s+$/, "") === b.replace(/\s+$/, "");
+}
+async function refreshBundledComposeIfStale(projectDir, oldTag) {
+  if (fs8.existsSync(path7.resolve(projectDir, ".git")))
+    return false;
+  const composeFile = path7.resolve(projectDir, "docker-compose.yml");
+  if (!fs8.existsSync(composeFile))
+    return false;
+  const refs = [
+    process.env.PGAI_PROJECT_REF,
+    package_default.version,
+    `v${package_default.version}`
+  ].filter((v) => Boolean(v && v.trim()));
+  const fetched = await fetchTargetCompose(refs);
+  if (!fetched || !isValidComposeYaml(fetched)) {
+    console.error(`\u26A0 Could not refresh docker-compose.yml to ${package_default.version} (no valid compose was retrieved).`);
+    console.error("  Keeping the existing compose. If dashboards are blank after upgrade, re-run this command once network is available.");
+    return false;
+  }
+  const existing = fs8.readFileSync(composeFile, "utf8");
+  if (composeContentEqual(existing, fetched))
+    return false;
+  const deployedTag = sanitizeTagForBackup(oldTag ?? readDeployedTag(projectDir));
+  const tagPart = deployedTag ?? new Date().toISOString().replace(/[:.]/g, "-");
+  const oldHash = crypto2.createHash("sha256").update(existing).digest("hex").slice(0, 8);
+  const backup = path7.resolve(projectDir, `docker-compose.yml.bak-${tagPart}-${oldHash}`);
+  let backupName = null;
+  try {
+    fs8.writeFileSync(backup, existing, { encoding: "utf8", mode: 384, flag: "wx" });
+    backupName = path7.basename(backup);
+  } catch (err) {
+    const e = err;
+    if (e && e.code === "EEXIST") {
+      backupName = path7.basename(backup);
+    }
+  }
+  fs8.writeFileSync(composeFile, fetched, { encoding: "utf8", mode: 384 });
+  const backupNote = backupName ? ` (backup: ${backupName})` : "";
+  console.log(`\u2713 Refreshed docker-compose.yml to ${package_default.version}${backupNote}`);
+  return true;
+}
 function getConfig(opts) {
   let apiKey = opts.apiKey || process.env.PGAI_API_KEY || "";
   if (!apiKey) {
@@ -35329,8 +35414,12 @@ mon.command("local-install").description("install local monitoring stack (genera
   let existingReplicatorPassword = null;
   let existingVmAuthUsername = null;
   let existingVmAuthPassword = null;
+  let previousTag = null;
   if (fs8.existsSync(envFile)) {
     const existingEnv = fs8.readFileSync(envFile, "utf8");
+    const previousTagMatch = existingEnv.match(/^PGAI_TAG=(.+)$/m);
+    if (previousTagMatch)
+      previousTag = previousTagMatch[1].trim();
     const registryMatch = existingEnv.match(/^PGAI_REGISTRY=(.+)$/m);
     if (registryMatch)
       existingRegistry = registryMatch[1].trim();
@@ -35361,6 +35450,7 @@ mon.command("local-install").description("install local monitoring stack (genera
   fs8.writeFileSync(envFile, envLines.join(`
 `) + `
 `, { encoding: "utf8", mode: 384 });
+  await refreshBundledComposeIfStale(projectDir, previousTag);
   if (opts.tag) {
     console.log(`Using image tag: ${imageTag}
 `);
@@ -35878,6 +35968,7 @@ mon.command("update-config").description("apply monitoring services configuratio
     console.log(`(existing values were preserved; missing keys filled with safe defaults)
 `);
   }
+  await refreshBundledComposeIfStale(projectDir);
   const code = await runCompose(["run", "--rm", "sources-generator"]);
   if (code !== 0)
     process.exitCode = code;
@@ -35915,7 +36006,8 @@ mon.command("update").description("update monitoring stack (migrate .env, pull i
       const { stdout: pullOut } = await execFilePromise("git", ["pull", "origin", currentBranch]);
       console.log(pullOut);
     } else {
-      console.log("(not a git checkout \u2014 skipping git fetch/pull and going straight to image pull)");
+      console.log("(not a git checkout \u2014 checking bundled docker-compose.yml)");
+      await refreshBundledComposeIfStale(projectDir);
     }
     console.log(`
 Updating Docker images...`);
@@ -37417,6 +37509,13 @@ mcp.command("install [client]").description("install MCP server configuration fo
     process.exitCode = 1;
   }
 });
-program2.parseAsync(process.argv).finally(() => {
-  closeReadline();
-});
+if (__require.main == __require.module) {
+  program2.parseAsync(process.argv).finally(() => {
+    closeReadline();
+  });
+}
+export {
+  refreshBundledComposeIfStale,
+  readDeployedTag,
+  isValidComposeYaml
+};

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "postgresai",
-  "version": "0.15.0-rc.6",
+  "version": "0.15.0-rc.8",
   "description": "postgres_ai CLI",
   "license": "Apache-2.0",
   "private": false,

package/test/upgrade.test.ts CHANGED Viewed

@@ -543,3 +543,514 @@ describe("in-place upgrade env migration (mon update / update-config)", () => {
     expect(envContent).not.toMatch(/PGAI_TAG=0\.14\.0VM_AUTH_USERNAME/);
   }, { timeout: TEST_TIMEOUT });
 });
+describe("in-place upgrade compose refresh (non-git npx upgrade)", () => {
+  /**
+   * Regression tests for the GA-blocking 0.14 -> 0.15 npx-upgrade gap (#186).
+   *
+   * The documented npx upgrade (`npm i -g postgresai@latest` then `pgai mon update`)
+   * only ever refreshed docker-compose.yml for *git* checkouts (via `git pull`).
+   * npx/global-npm installs are non-git, so the OLD 0.14 docker-compose.yml was
+   * retained while PGAI_TAG advanced to 0.15. VM basic auth is new in 0.15, so the
+   * retained 0.14 compose never wires VM_AUTH_* into the sink-prometheus
+   * (VictoriaMetrics) service. The 0.15 configs image ships a prometheus.yml that
+   * templates %{VM_AUTH_USERNAME}, so VictoriaMetrics aborts on boot:
+   *
+   *   Exited (255): missing "VM_AUTH_USERNAME" env var
+   *
+   * -> all dashboards are dataless after upgrade. This hits every existing npx
+   * self-hosted user and blocks 0.15.0 GA.
+   *
+   * The fix: for NON-GIT installs, refresh the CLI-owned docker-compose.yml from the
+   * target ref when it is stale, backing up the prior compose first, and never
+   * touching user-owned files (.env / instances.yml).
+   *
+   * Hermetic seam: PGAI_COMPOSE_SOURCE points the refresh at a local fixture file
+   * (instead of fetching over the network) so these tests are offline-safe. The
+   * seam is only honored when NODE_ENV === "test" (bun sets this automatically;
+   * we also set it explicitly), so it is never reachable in a user environment.
+   */
+  // A valid target 0.15 compose fixture: it carries the VM_AUTH_* wiring that the
+  // stale 0.14 compose lacks AND the keystone `sink-prometheus` service the
+  // validator requires. Self-contained so the test doesn't depend on the live
+  // repo compose changing under it.
+  const TARGET_0_15_COMPOSE = [
+    "version: '3.8'",
+    "services:",
+    "  sink-prometheus:",
+    "    image: victoriametrics/victoria-metrics:v1.140.0",
+    "    container_name: sink-prometheus",
+    "    environment:",
+    "      - VM_AUTH_USERNAME=${VM_AUTH_USERNAME:-}",
+    "      - VM_AUTH_PASSWORD=${VM_AUTH_PASSWORD:-}",
+    "  grafana:",
+    "    image: grafana/grafana:11.0.0",
+    "",
+  ].join("\n");
+  // A 0.14-shaped compose: a real-ish stack with ZERO VM_AUTH wiring.
+  const STALE_0_14_COMPOSE = [
+    "version: '3.8'",
+    "services:",
+    "  sink-prometheus:",
+    "    image: victoriametrics/victoria-metrics:v1.115.0",
+    "    container_name: sink-prometheus",
+    "    ports:",
+    '      - "9090:8428"',
+    "  grafana:",
+    "    image: grafana/grafana:11.0.0",
+    "",
+  ].join("\n");
+  let tempDir: string;
+  // Path to a written-out copy of TARGET_0_15_COMPOSE, used as the fetch fixture.
+  let targetComposePath: string;
+  const listBackups = (dir: string): string[] =>
+    fs.readdirSync(dir).filter((f) => f.startsWith("docker-compose.yml.bak")).sort();
+  beforeAll(() => {
+    tempDir = fs.mkdtempSync(resolve(os.tmpdir(), "pgai-upgrade-compose-refresh-"));
+    targetComposePath = resolve(tempDir, "fixture-target-compose.yml");
+    fs.writeFileSync(targetComposePath, TARGET_0_15_COMPOSE);
+  });
+  afterAll(() => {
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+  test("non-git upgrade refreshes a stale docker-compose.yml to the target version (VM_AUTH wiring), preserves instances.yml, and writes a backup labeled with the OLD tag", () => {
+    const testDir = resolve(tempDir, "update-config-stale-compose");
+    fs.mkdirSync(testDir, { recursive: true });
+    // Arrange: a 0.14-shaped, NON-GIT install. Old compose has no VM_AUTH wiring.
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(
+      resolve(testDir, "instances.yml"),
+      "# PostgreSQL instances to monitor\n- name: keep-me\n  conn_str: postgresql://m:p@h:5432/db\n",
+    );
+    // Sanity: the stale compose really lacks VM_AUTH wiring before the upgrade.
+    expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).not.toMatch(/VM_AUTH_USERNAME/);
+    // Act: documented in-place upgrade step on a non-git install. The compose `run`
+    // will fail (no Docker in CI), but the compose refresh runs first. Point the
+    // refresh at the local fixture so the test is hermetic (no network).
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    // Assert: deployed compose is REFRESHED to the target version (VM_AUTH wired).
+    const after = fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8");
+    expect(after).toMatch(/VM_AUTH_USERNAME/);
+    expect(after).toMatch(/sink-prometheus/);
+    // Assert: instances.yml is PRESERVED (user-owned file untouched).
+    expect(fs.readFileSync(resolve(testDir, "instances.yml"), "utf8")).toMatch(/keep-me/);
+    // Assert: exactly one backup, labeled with the OLD (0.14.0) tag, containing
+    // the pristine pre-upgrade compose. Name is `bak-<oldtag>-<hash8>`.
+    const backups = listBackups(testDir);
+    expect(backups.length).toBe(1);
+    expect(backups[0]).toMatch(/^docker-compose\.yml\.bak-0\.14\.0-[0-9a-f]{8}$/);
+    expect(fs.readFileSync(resolve(testDir, backups[0]!), "utf8")).toBe(STALE_0_14_COMPOSE);
+  }, { timeout: TEST_TIMEOUT });
+  test("non-git upgrade via `mon update` also refreshes a stale docker-compose.yml", () => {
+    const testDir = resolve(tempDir, "update-stale-compose");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n- name: keep-me\n");
+    runCliInDir(["mon", "update"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    const after = fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8");
+    expect(after).toMatch(/VM_AUTH_USERNAME/);
+    expect(fs.readFileSync(resolve(testDir, "instances.yml"), "utf8")).toMatch(/keep-me/);
+    const backups = listBackups(testDir);
+    expect(backups.length).toBe(1);
+    expect(backups[0]).toMatch(/^docker-compose\.yml\.bak-0\.14\.0-[0-9a-f]{8}$/);
+  }, { timeout: TEST_TIMEOUT });
+  test("git checkouts are left untouched (compose managed by git pull)", () => {
+    const testDir = resolve(tempDir, "git-checkout-no-refresh");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.mkdirSync(resolve(testDir, ".git"), { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    // Compose must be unchanged for git checkouts, and no backup written.
+    expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(STALE_0_14_COMPOSE);
+    expect(listBackups(testDir)).toEqual([]);
+  }, { timeout: TEST_TIMEOUT });
+  test("already-current compose is not rewritten and no backup is created (idempotent)", () => {
+    const testDir = resolve(tempDir, "already-current-compose");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), TARGET_0_15_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    // Content already matches target -> no rewrite, no backup.
+    expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(TARGET_0_15_COMPOSE);
+    expect(listBackups(testDir)).toEqual([]);
+  }, { timeout: TEST_TIMEOUT });
+  test("a trailing-newline-only difference is NOT treated as stale (no churn, no backup)", () => {
+    const testDir = resolve(tempDir, "trailing-newline-noop");
+    fs.mkdirSync(testDir, { recursive: true });
+    // Deployed compose == target but with extra trailing whitespace/newlines.
+    const deployed = TARGET_0_15_COMPOSE + "\n\n";
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), deployed);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    // Whitespace-only delta must not trigger a rewrite or a backup.
+    expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(deployed);
+    expect(listBackups(testDir)).toEqual([]);
+  }, { timeout: TEST_TIMEOUT });
+  describe("fetched payload validation (BLOCKER #186 hardening)", () => {
+    /**
+     * A 200 response can still carry a NON-compose body (HTML login/captcha/
+     * proxy/maintenance page) or an empty/garbage body. Such a payload must
+     * NEVER clobber a working docker-compose.yml — that would be strictly worse
+     * than keeping the stale-but-valid one. The refresh must validate the fetched
+     * text and, on failure, behave EXACTLY like a clean fetch failure: keep the
+     * existing compose, write NO backup, warn, no-op.
+     */
+    test("an HTML (non-compose) 200 body leaves the deployed compose UNCHANGED, writes NO backup, and warns", () => {
+      const testDir = resolve(tempDir, "garbage-html-body");
+      fs.mkdirSync(testDir, { recursive: true });
+      // The "fetched" payload is an HTML login/proxy page served with a 200.
+      const htmlBody = "<!DOCTYPE html>\n<html><head><title>Sign in</title></head>\n<body>Please log in to continue.</body></html>\n";
+      const htmlSource = resolve(testDir, "html-source.html");
+      fs.writeFileSync(htmlSource, htmlBody);
+      fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+      fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+      fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+      const result = runCliInDir(["mon", "update-config"], testDir, {
+        NODE_ENV: "test",
+        PGAI_TAG: undefined,
+        PGAI_COMPOSE_SOURCE: htmlSource,
+      });
+      // The working compose must be left intact — NOT clobbered with HTML.
+      expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(STALE_0_14_COMPOSE);
+      // No backup is written when nothing is refreshed.
+      expect(listBackups(testDir)).toEqual([]);
+      // The user is warned that no valid compose was retrieved.
+      expect(result.stderr).toMatch(/Could not refresh docker-compose\.yml/);
+    }, { timeout: TEST_TIMEOUT });
+    test("a YAML body WITHOUT a sink-prometheus service is rejected (compose untouched, no backup)", () => {
+      const testDir = resolve(tempDir, "yaml-missing-keystone");
+      fs.mkdirSync(testDir, { recursive: true });
+      // Valid YAML, has services, but lacks the keystone sink-prometheus service.
+      const wrongCompose = "version: '3.8'\nservices:\n  grafana:\n    image: grafana/grafana:11.0.0\n";
+      const wrongSource = resolve(testDir, "wrong-compose.yml");
+      fs.writeFileSync(wrongSource, wrongCompose);
+      fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+      fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+      fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+      runCliInDir(["mon", "update-config"], testDir, {
+        NODE_ENV: "test",
+        PGAI_TAG: undefined,
+        PGAI_COMPOSE_SOURCE: wrongSource,
+      });
+      expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(STALE_0_14_COMPOSE);
+      expect(listBackups(testDir)).toEqual([]);
+    }, { timeout: TEST_TIMEOUT });
+    test("an empty fetched body leaves the deployed compose intact and writes NO backup", () => {
+      const testDir = resolve(tempDir, "empty-body");
+      fs.mkdirSync(testDir, { recursive: true });
+      const emptySource = resolve(testDir, "empty.yml");
+      fs.writeFileSync(emptySource, "");
+      fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+      fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+      fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+      runCliInDir(["mon", "update-config"], testDir, {
+        NODE_ENV: "test",
+        PGAI_TAG: undefined,
+        PGAI_COMPOSE_SOURCE: emptySource,
+      });
+      expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(STALE_0_14_COMPOSE);
+      expect(listBackups(testDir)).toEqual([]);
+    }, { timeout: TEST_TIMEOUT });
+  });
+  test("repeated update-config runs preserve the FIRST/pristine backup (no overwrite)", () => {
+    const testDir = resolve(tempDir, "backup-collision");
+    fs.mkdirSync(testDir, { recursive: true });
+    // PGAI_TAG stays 0.14.0 across update-config runs (it doesn't advance there).
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    // First run: refreshes to target, backs up the pristine 0.14 compose.
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    const afterFirst = listBackups(testDir);
+    expect(afterFirst.length).toBe(1);
+    const pristineBackup = afterFirst[0]!;
+    expect(fs.readFileSync(resolve(testDir, pristineBackup), "utf8")).toBe(STALE_0_14_COMPOSE);
+    // Now the deployed compose IS the target. Simulate a second drift back to a
+    // (different) stale compose, then run update-config again with the SAME tag.
+    const SECOND_STALE = STALE_0_14_COMPOSE.replace("v1.115.0", "v1.116.0");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), SECOND_STALE);
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    // The FIRST/pristine backup must still be intact (not overwritten), and the
+    // second distinct old content gets its own backup (unique by content hash).
+    expect(fs.readFileSync(resolve(testDir, pristineBackup), "utf8")).toBe(STALE_0_14_COMPOSE);
+    const afterSecond = listBackups(testDir);
+    expect(afterSecond.length).toBe(2);
+    expect(afterSecond).toContain(pristineBackup);
+  }, { timeout: TEST_TIMEOUT });
+  test("local-install labels the backup with the OLD tag, not the new CLI version", () => {
+    const testDir = resolve(tempDir, "local-install-old-tag-backup");
+    fs.mkdirSync(testDir, { recursive: true });
+    // 0.14 install. local-install rewrites .env PGAI_TAG to the CLI version
+    // BEFORE the compose refresh; the backup must still reflect the OLD (0.14.0)
+    // tag, not the new one.
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    runCliInDir(
+      ["mon", "local-install", "--db-url", "postgresql://u:p@h:5432/d", "--yes"],
+      testDir,
+      {
+        NODE_ENV: "test",
+        PGAI_TAG: undefined,
+        PGAI_COMPOSE_SOURCE: targetComposePath,
+      },
+    );
+    // .env PGAI_TAG was advanced to the new CLI version...
+    const envAfter = fs.readFileSync(resolve(testDir, ".env"), "utf8");
+    expect(envAfter).not.toMatch(/PGAI_TAG=0\.14\.0/);
+    // ...but the backup of the OLD compose must be labeled with 0.14.0, NOT the
+    // new tag, and must contain the pristine pre-upgrade compose.
+    const backups = listBackups(testDir);
+    expect(backups.length).toBe(1);
+    expect(backups[0]).toMatch(/^docker-compose\.yml\.bak-0\.14\.0-[0-9a-f]{8}$/);
+    expect(fs.readFileSync(resolve(testDir, backups[0]!), "utf8")).toBe(STALE_0_14_COMPOSE);
+  }, { timeout: TEST_TIMEOUT });
+  test("a fetch failure (no payload retrieved) leaves the deployed compose intact, writes NO backup, warns, and does not crash", () => {
+    // Contract bullet: "Best-effort — a fetch failure warns and keeps the
+    // existing compose." Force fetchTargetCompose() -> null hermetically by
+    // pointing the test seam at a path that does not exist. This is the network
+    // -down / GitLab-5xx branch: it must NOT turn a metrics-only outage into a
+    // hard CLI failure, and must never clobber the stale-but-valid compose.
+    const testDir = resolve(tempDir, "fetch-failure-null");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    const result = runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      // Nonexistent fixture path -> fetchTargetCompose() returns null.
+      PGAI_COMPOSE_SOURCE: resolve(testDir, "does-not-exist.yml"),
+    });
+    // The working compose must be untouched, and no backup written.
+    expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(STALE_0_14_COMPOSE);
+    expect(listBackups(testDir)).toEqual([]);
+    // The user is warned, and the CLI does not crash on the env-migration step.
+    expect(result.stderr).toMatch(/Could not refresh docker-compose\.yml/);
+  }, { timeout: TEST_TIMEOUT });
+  test("no deployed compose yet is a clean no-op: returns false, writes nothing, no backup", async () => {
+    // Guard: `if (!fs.existsSync(composeFile)) return false` keeps the refresh
+    // from racing with the green-field bootstrap path. NOTE: this branch is not
+    // reachable through the black-box `mon update-config` flow — resolveOrInitPaths
+    // bootstraps (fetches) a compose BEFORE the refresh runs, so by then the file
+    // always exists. We therefore exercise the guard directly against the exported
+    // helper, which is the only faithful, hermetic way to cover it.
+    const { refreshBundledComposeIfStale } = await import("../bin/postgres-ai.ts");
+    const testDir = resolve(tempDir, "no-deployed-compose");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    // Intentionally NO docker-compose.yml.
+    process.env.NODE_ENV = "test";
+    process.env.PGAI_COMPOSE_SOURCE = targetComposePath;
+    const refreshed = await refreshBundledComposeIfStale(testDir);
+    // No compose on disk -> no-op: returns false, materializes no compose, and
+    // writes no backup. The bootstrap path owns the first fetch.
+    expect(refreshed).toBe(false);
+    expect(fs.existsSync(resolve(testDir, "docker-compose.yml"))).toBe(false);
+    expect(listBackups(testDir)).toEqual([]);
+  }, { timeout: TEST_TIMEOUT });
+  test("git checkout is a no-op even with a stale compose (direct helper guard)", async () => {
+    // Companion guard: `.git` present -> the repo manages the compose via
+    // `git pull`, so the helper must return false and touch nothing. Covered
+    // black-box too (below), but pinned here against the exported helper.
+    const { refreshBundledComposeIfStale } = await import("../bin/postgres-ai.ts");
+    const testDir = resolve(tempDir, "git-checkout-helper-noop");
+    fs.mkdirSync(resolve(testDir, ".git"), { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=0.14.0\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    process.env.NODE_ENV = "test";
+    process.env.PGAI_COMPOSE_SOURCE = targetComposePath;
+    const refreshed = await refreshBundledComposeIfStale(testDir);
+    expect(refreshed).toBe(false);
+    expect(fs.readFileSync(resolve(testDir, "docker-compose.yml"), "utf8")).toBe(STALE_0_14_COMPOSE);
+    expect(listBackups(testDir)).toEqual([]);
+  }, { timeout: TEST_TIMEOUT });
+  test("backup falls back to a timestamp suffix when .env has no PGAI_TAG line", () => {
+    // When readDeployedTag() returns null (no PGAI_TAG to label the backup with),
+    // the backup name falls back to an ISO-8601 timestamp suffix
+    // (`bak-<YYYY-MM-DDTHH-MM-SS-mmmZ>-<hash8>`). Every other test seeds
+    // PGAI_TAG=0.14.0, so this branch was previously unexercised.
+    const testDir = resolve(tempDir, "timestamp-suffix-fallback");
+    fs.mkdirSync(testDir, { recursive: true });
+    // .env exists (non-git install) but carries NO PGAI_TAG line.
+    fs.writeFileSync(resolve(testDir, ".env"), "GRAFANA_PASSWORD=secret\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    // The compose was refreshed, and the single backup is labeled with a
+    // timestamp suffix (NOT a tag), still uniquified by the content hash.
+    const backups = listBackups(testDir);
+    expect(backups.length).toBe(1);
+    expect(backups[0]).toMatch(/^docker-compose\.yml\.bak-\d{4}-\d{2}-\d{2}T[\dZ-]+-[0-9a-f]{8}$/);
+    expect(fs.readFileSync(resolve(testDir, backups[0]!), "utf8")).toBe(STALE_0_14_COMPOSE);
+  }, { timeout: TEST_TIMEOUT });
+  test("a malformed/hostile PGAI_TAG is rejected and the backup falls back to a timestamp suffix (no path traversal)", () => {
+    // readDeployedTag() validates the tag against a conservative charset before
+    // it flows into the backup filename, so a path-traversal-shaped value cannot
+    // escape projectDir; it falls back to the timestamp suffix instead.
+    const testDir = resolve(tempDir, "hostile-tag-rejected");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), "PGAI_TAG=../../../../tmp/evil\n");
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    runCliInDir(["mon", "update-config"], testDir, {
+      NODE_ENV: "test",
+      PGAI_TAG: undefined,
+      PGAI_COMPOSE_SOURCE: targetComposePath,
+    });
+    // The single backup stays inside projectDir with a timestamp suffix — the
+    // traversal value never reaches the filename.
+    const backups = listBackups(testDir);
+    expect(backups.length).toBe(1);
+    expect(backups[0]).toMatch(/^docker-compose\.yml\.bak-\d{4}-\d{2}-\d{2}T[\dZ-]+-[0-9a-f]{8}$/);
+    // Nothing was written outside projectDir.
+    expect(fs.existsSync("/tmp/evil")).toBe(false);
+  }, { timeout: TEST_TIMEOUT });
+  test("local-install sanitizes the OLD tag it passes in: a hostile PGAI_TAG falls back to a timestamp suffix", () => {
+    // local-install captures the OLD .env PGAI_TAG and passes it to the refresh as
+    // `oldTag`, BYPASSING readDeployedTag. Sanitization must therefore happen
+    // centrally inside the helper so a hostile tag on THIS path also cannot escape
+    // projectDir or land literal `/`/quote chars in the backup filename.
+    const testDir = resolve(tempDir, "local-install-hostile-old-tag");
+    fs.mkdirSync(testDir, { recursive: true });
+    fs.writeFileSync(resolve(testDir, ".env"), 'PGAI_TAG="../../../../tmp/evil"\n');
+    fs.writeFileSync(resolve(testDir, "docker-compose.yml"), STALE_0_14_COMPOSE);
+    fs.writeFileSync(resolve(testDir, "instances.yml"), "# instances\n");
+    runCliInDir(
+      ["mon", "local-install", "--db-url", "postgresql://u:p@h:5432/d", "--yes"],
+      testDir,
+      {
+        NODE_ENV: "test",
+        PGAI_TAG: undefined,
+        PGAI_COMPOSE_SOURCE: targetComposePath,
+      },
+    );
+    // The hostile oldTag never reaches the filename: the single backup stays
+    // inside projectDir with a timestamp suffix, and nothing escapes to /tmp.
+    const backups = listBackups(testDir);
+    expect(backups.length).toBe(1);
+    expect(backups[0]).toMatch(/^docker-compose\.yml\.bak-\d{4}-\d{2}-\d{2}T[\dZ-]+-[0-9a-f]{8}$/);
+    expect(fs.existsSync("/tmp/evil")).toBe(false);
+  }, { timeout: TEST_TIMEOUT });
+});