@openpalm/ui 0.12.0-rc.1 → 0.12.0-rc.3

package/build/server/chunks/{src-CHZNd5cO.js → src-B7oqi9q_.js}

@@ -1,7 +1,7 @@
 import { _ as __commonJSMin, b as __require } from './chunk-CLZ62Ad-.js';
 import { P as PROVIDER_DEFAULT_URLS, a as PROVIDER_KEY_MAP } from './provider-constants-DPrj3yBX.js';
 import { r as require_dist } from './dist-DOFcG0Zp.js';
-import Vt, { existsSync, readFileSync, copyFileSync, chmodSync, mkdirSync, lstatSync, rmSync, readdirSync, writeFileSync, renameSync, statSync, cpSync, openSync, constants, writeSync, closeSync, chownSync, realpathSync } from 'node:fs';
+import Vt, { existsSync, readFileSync, copyFileSync, chmodSync, mkdirSync, lstatSync, rmSync, readdirSync, writeFileSync, renameSync, statSync, statfsSync, cpSync, openSync, constants, writeSync, closeSync, chownSync, realpathSync } from 'node:fs';
 import or, { join, basename, dirname, resolve, win32, posix } from 'node:path';
 import { Buffer as Buffer$1 } from 'buffer';
 import I from 'fs';
@@ -96,6 +96,84 @@ function timestampDirName(now = /* @__PURE__ */ new Date()) {
 	return now.toISOString().replace(/[:.]/g, "-");
 }
 /**
+* Recursively sum the apparent size (in bytes) of every file under `path`,
+* excluding the existing backups directory (we never back up backups).
+*
+* Cheap enough for a pre-backup estimate; errors on individual entries are
+* skipped (a transient unreadable file should not block the safety copy).
+*/
+function estimateHomeBackupBytes(homeDir) {
+	if (!existsSync(homeDir)) return 0;
+	const backupsDir = join(homeDir, "data", "backups");
+	let total = 0;
+	const walk = (dir) => {
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const full = join(dir, entry.name);
+			if (full === backupsDir) continue;
+			if (entry.isDirectory()) walk(full);
+			else if (entry.isFile()) try {
+				total += statSync(full).size;
+			} catch {}
+		}
+	};
+	walk(homeDir);
+	return total;
+}
+/**
+* Estimate whether a full-home backup would fit safely on disk.
+*
+* Returns a structured result; the caller decides whether to warn, block, or
+* (with explicit confirmation) proceed. This NEVER deletes anything — it only
+* measures. `threshold` is the fraction of currently-free space the backup may
+* consume before it is flagged `insufficient` (default 80%).
+*/
+function checkBackupFreeSpace(homeDir, threshold = .8) {
+	const estimatedBytes = estimateHomeBackupBytes(homeDir);
+	let freeBytes = Number.POSITIVE_INFINITY;
+	try {
+		const stat = statfsSync(homeDir);
+		freeBytes = stat.bavail * stat.bsize;
+	} catch {}
+	const ratio = freeBytes > 0 ? estimatedBytes / freeBytes : Number.POSITIVE_INFINITY;
+	return {
+		estimatedBytes,
+		freeBytes,
+		ratio,
+		insufficient: estimatedBytes > freeBytes * threshold,
+		threshold
+	};
+}
+function formatBytes(bytes) {
+	if (!Number.isFinite(bytes)) return "unknown";
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	let value = bytes;
+	let i = 0;
+	while (value >= 1024 && i < units.length - 1) {
+		value /= 1024;
+		i += 1;
+	}
+	return `${value.toFixed(value >= 10 || i === 0 ? 0 : 1)} ${units[i]}`;
+}
+/**
+* Human-readable, plain-language explanation of a low-free-space situation,
+* suitable for a CLI warning or a UI notice.
+*/
+function describeBackupSpaceShortfall(check) {
+	return `The safety backup is estimated at ${formatBytes(check.estimatedBytes)}, but only ${formatBytes(check.freeBytes)} is free on this disk. Backing up could fill the disk. Free up space (your old backups are under data/backups/ — review them with \`openpalm backups list\`), or re-run with confirmation to proceed anyway. Nothing was changed or deleted.`;
+}
+/**
 * Create a durable backup snapshot of the current OP_HOME contents.
 *
 * The backup is written under OP_HOME/data/backups/<timestamp>/ and excludes
@@ -123,6 +201,62 @@ function backupOpenPalmHome(homeDir) {
 	}
 	return copiedAny ? backupDir : null;
 }
+function listBackupDirs(homeDir) {
+	const backupsDir = join(homeDir, "data", "backups");
+	if (!existsSync(backupsDir)) return [];
+	return readdirSync(backupsDir, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => join(backupsDir, entry.name)).sort((a, b) => b.localeCompare(a));
+}
+function dirSizeBytes(dir) {
+	let total = 0;
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return 0;
+	}
+	for (const entry of entries) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) total += dirSizeBytes(full);
+		else if (entry.isFile()) try {
+			total += statSync(full).size;
+		} catch {}
+	}
+	return total;
+}
+/**
+* Summarize the upgrade backup snapshots for UI visibility (count, total size,
+* last-backup time, per-backup sizes). Read-only — never deletes anything.
+*/
+function summarizeBackups(homeDir) {
+	const backups = listBackupDirs(homeDir).map((path) => {
+		let createdAt = "";
+		try {
+			createdAt = statSync(path).mtime.toISOString();
+		} catch {}
+		return {
+			path,
+			name: path.slice(path.lastIndexOf("/") + 1),
+			sizeBytes: dirSizeBytes(path),
+			createdAt
+		};
+	});
+	const totalBytes = backups.reduce((sum, b) => sum + b.sizeBytes, 0);
+	return {
+		count: backups.length,
+		totalBytes,
+		lastBackupAt: backups[0]?.createdAt || null,
+		backups
+	};
+}
+function pruneBackupDirs(homeDir, keep) {
+	if (!Number.isInteger(keep) || keep < 0) throw new Error("keep must be a non-negative integer");
+	const toDelete = listBackupDirs(homeDir).slice(keep);
+	for (const backupDir of toDelete) rmSync(backupDir, {
+		recursive: true,
+		force: true
+	});
+	return toDelete;
+}
 //#endregion
 //#region ../lib/src/control-plane/install-lock.ts
 var import_dist = require_dist();
@@ -249,6 +383,79 @@ function acquireInstallLock(dataDir) {
 	}
 	return null;
 }
+var INSTALL_LOCK_STALE_AFTER_MS = STALE_AFTER_MS;
+/**
+* Inspect the install lock under `dataDir` without modifying it. Used by the
+* `openpalm unlock` command and the UI "operation stuck?" affordance to decide
+* whether a removal is safe.
+*/
+function inspectInstallLock(dataDir) {
+	const path = join(dataDir, ".install.lock");
+	let content;
+	try {
+		content = readFileSync(path, "utf-8");
+	} catch (err) {
+		if (err.code === "ENOENT") return {
+			present: false,
+			path
+		};
+		let ageMs = null;
+		try {
+			ageMs = Date.now() - statSync(path).mtimeMs;
+		} catch {}
+		return {
+			present: true,
+			path,
+			pid: null,
+			timestamp: null,
+			ageMs,
+			stale: isStale(path)
+		};
+	}
+	const { pid, timestamp } = parseLockContent(content);
+	return {
+		present: true,
+		path,
+		pid,
+		timestamp,
+		ageMs: timestamp !== null ? Date.now() - timestamp : null,
+		stale: isStale(path)
+	};
+}
+/**
+* Remove the install lock ONLY if it is stale (dead holder PID or older than
+* the 30-minute staleness window). Never blind-removes a lock held by a live,
+* recent install. Returns `{ ok: false, reason: "live" }` when the lock is
+* still active so the caller can surface a clear message instead of forcing.
+*/
+function unlockInstallLock(dataDir) {
+	const status = inspectInstallLock(dataDir);
+	if (!status.present) return {
+		ok: true,
+		removed: false,
+		status
+	};
+	if (!status.stale) return {
+		ok: false,
+		reason: "live",
+		status
+	};
+	try {
+		rmSync(status.path, { force: true });
+		logger$11.info("removed stale install lock via unlock", { path: status.path });
+	} catch (err) {
+		logger$11.warn("failed to remove stale install lock during unlock", {
+			path: status.path,
+			error: err instanceof Error ? err.message : String(err)
+		});
+		throw err;
+	}
+	return {
+		ok: true,
+		removed: true,
+		status
+	};
+}
 function releaseInstallLock(handle) {
 	if (!handle) return;
 	try {
@@ -261,7 +468,7 @@ function releaseInstallLock(handle) {
 	}
 }
 //#endregion
-//#region ../lib/src/control-plane/env.ts
+//#region ../lib/package.json
 var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var fs$1 = __require("fs");
 	var path = __require("path");
@@ -529,6 +736,119 @@ var import_main = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports.populate = DotenvModule.populate;
 	module.exports = DotenvModule;
 })))();
+var package_default = {
+	version: "0.12.0-rc.3"};
+//#endregion
+//#region ../lib/src/control-plane/versioning.ts
+var SEMVER_RE = /^v?\d+\.\d+\.\d+(?:[-+].*)?$/;
+/**
+* The canonical control-plane / platform version.
+*
+* This is the ONE source of truth for "which @openpalm/lib (and therefore which
+* RELEASE_MIGRATIONS + lifecycle) is running." It travels with the data/ui
+* build (the published @openpalm/ui inlines this lib), so it self-updates in
+* place — it is NOT the Electron harness version (see
+* packages/electron/src/harness-contract.ts: HARNESS_CONTRACT_VERSION).
+*
+* Stored Docker-canonical (`v`-prefixed) because every consumer that stamps a
+* version into stack.env / a skeleton / a migration target wants the Docker tag
+* form. Use `formatForDisplay` for user-facing strings and `normalizeVersion`
+* for npm-style (no-`v`) comparisons.
+*
+* Replaces the former implicit `v${libPkg.version}` scattered through lifecycle
+* / migrations so the platform version has a single, named home.
+*/
+var PLATFORM_VERSION = formatForDocker(package_default.version);
+function isComparableSemver(version) {
+	return !!version && SEMVER_RE.test(version.trim());
+}
+function parseComparableVersion(version) {
+	const clean = normalizeVersion(version).split("+")[0];
+	const dashIdx = clean.indexOf("-");
+	const main = dashIdx === -1 ? clean : clean.slice(0, dashIdx);
+	const prerelease = dashIdx === -1 ? null : clean.slice(dashIdx + 1);
+	const [major = 0, minor = 0, patch = 0] = main.split(".").map(Number);
+	return {
+		major,
+		minor,
+		patch,
+		prerelease
+	};
+}
+function comparePrerelease(a, b) {
+	const aParts = a.split(".");
+	const bParts = b.split(".");
+	for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+		if (i >= aParts.length) return -1;
+		if (i >= bParts.length) return 1;
+		const aNum = Number(aParts[i]);
+		const bNum = Number(bParts[i]);
+		const aIsNum = !Number.isNaN(aNum);
+		const bIsNum = !Number.isNaN(bNum);
+		if (aIsNum && bIsNum) {
+			if (aNum !== bNum) return aNum > bNum ? 1 : -1;
+			continue;
+		}
+		if (aIsNum !== bIsNum) return aIsNum ? -1 : 1;
+		if (aParts[i] !== bParts[i]) return aParts[i] > bParts[i] ? 1 : -1;
+	}
+	return 0;
+}
+function compareComparableVersions(a, b) {
+	const aParsed = parseComparableVersion(a);
+	const bParsed = parseComparableVersion(b);
+	if (aParsed.major !== bParsed.major) return aParsed.major > bParsed.major ? 1 : -1;
+	if (aParsed.minor !== bParsed.minor) return aParsed.minor > bParsed.minor ? 1 : -1;
+	if (aParsed.patch !== bParsed.patch) return aParsed.patch > bParsed.patch ? 1 : -1;
+	if (aParsed.prerelease === null && bParsed.prerelease !== null) return 1;
+	if (aParsed.prerelease !== null && bParsed.prerelease === null) return -1;
+	if (aParsed.prerelease !== null && bParsed.prerelease !== null) return comparePrerelease(aParsed.prerelease, bParsed.prerelease);
+	return 0;
+}
+function majorVersionOf(version) {
+	if (!isComparableSemver(version)) return null;
+	return parseComparableVersion(version).major;
+}
+function isSameMajorVersion(a, b) {
+	const aMajor = majorVersionOf(a);
+	const bMajor = majorVersionOf(b);
+	return aMajor !== null && bMajor !== null && aMajor === bMajor;
+}
+/**
+* npm/display form: strip a single leading `v` and trim. `v0.12.0` → `0.12.0`.
+* Pass-through for an already-bare version. Empty/whitespace → ''.
+*/
+function normalizeVersion(version) {
+	return (version ?? "").trim().replace(/^v/, "");
+}
+/**
+* Docker-tag form: ensure exactly one leading `v`. `0.12.0` → `v0.12.0`,
+* `v0.12.0` → `v0.12.0`. Empty/whitespace → '' (callers gate on RELEASE_TAG_REGEX
+* before treating a value as a real tag).
+*/
+function formatForDocker(version) {
+	const bare = normalizeVersion(version);
+	return bare ? `v${bare}` : "";
+}
+/**
+* True when `version` carries a semver pre-release segment (`0.12.0-rc.1`).
+* Build metadata (`+build.5`) is NOT a pre-release. Non-semver → false.
+*/
+function isPrerelease(version) {
+	if (!isComparableSemver(version)) return false;
+	return parseComparableVersion(version).prerelease !== null;
+}
+/**
+* User-facing presentation form: drop the leading `v` so the UI shows one
+* canonical spelling regardless of whether the value arrived as a Docker tag or
+* an npm version. Non-semver values are returned trimmed but otherwise untouched
+* (e.g. a moving `latest`/`dev` tag).
+*/
+function formatForDisplay(version) {
+	return normalizeVersion(version);
+}
+//#endregion
+//#region ../lib/src/control-plane/env.ts
 function parseEnvContent(content) {
 	return (0, import_main.parse)(content);
 }
@@ -675,64 +995,6 @@ function buildPlatformImageTagEnv(tag, perImage, pinnedImages = []) {
 	};
 }
 //#endregion
-//#region ../lib/src/control-plane/versioning.ts
-var SEMVER_RE = /^v?\d+\.\d+\.\d+(?:[-+].*)?$/;
-function isComparableSemver(version) {
-	return !!version && SEMVER_RE.test(version.trim());
-}
-function parseComparableVersion(version) {
-	const clean = version.trim().replace(/^v/, "").split("+")[0];
-	const dashIdx = clean.indexOf("-");
-	const main = dashIdx === -1 ? clean : clean.slice(0, dashIdx);
-	const prerelease = dashIdx === -1 ? null : clean.slice(dashIdx + 1);
-	const [major = 0, minor = 0, patch = 0] = main.split(".").map(Number);
-	return {
-		major,
-		minor,
-		patch,
-		prerelease
-	};
-}
-function comparePrerelease(a, b) {
-	const aParts = a.split(".");
-	const bParts = b.split(".");
-	for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
-		if (i >= aParts.length) return -1;
-		if (i >= bParts.length) return 1;
-		const aNum = Number(aParts[i]);
-		const bNum = Number(bParts[i]);
-		const aIsNum = !Number.isNaN(aNum);
-		const bIsNum = !Number.isNaN(bNum);
-		if (aIsNum && bIsNum) {
-			if (aNum !== bNum) return aNum > bNum ? 1 : -1;
-			continue;
-		}
-		if (aIsNum !== bIsNum) return aIsNum ? -1 : 1;
-		if (aParts[i] !== bParts[i]) return aParts[i] > bParts[i] ? 1 : -1;
-	}
-	return 0;
-}
-function compareComparableVersions(a, b) {
-	const aParsed = parseComparableVersion(a);
-	const bParsed = parseComparableVersion(b);
-	if (aParsed.major !== bParsed.major) return aParsed.major > bParsed.major ? 1 : -1;
-	if (aParsed.minor !== bParsed.minor) return aParsed.minor > bParsed.minor ? 1 : -1;
-	if (aParsed.patch !== bParsed.patch) return aParsed.patch > bParsed.patch ? 1 : -1;
-	if (aParsed.prerelease === null && bParsed.prerelease !== null) return 1;
-	if (aParsed.prerelease !== null && bParsed.prerelease === null) return -1;
-	if (aParsed.prerelease !== null && bParsed.prerelease !== null) return comparePrerelease(aParsed.prerelease, bParsed.prerelease);
-	return 0;
-}
-function majorVersionOf(version) {
-	if (!isComparableSemver(version)) return null;
-	return parseComparableVersion(version).major;
-}
-function isSameMajorVersion(a, b) {
-	const aMajor = majorVersionOf(a);
-	const bMajor = majorVersionOf(b);
-	return aMajor !== null && bMajor !== null && aMajor === bMajor;
-}
-//#endregion
 //#region ../lib/src/control-plane/migrations.ts
 /**
 * On-disk layout migration harness.
@@ -767,6 +1029,22 @@ var MigrationError = class extends Error {
 		this.name = "MigrationError";
 	}
 };
+/**
+* Thrown when the pre-backup free-space check estimates the safety backup would
+* exceed a safe fraction of free disk. Surfaced so callers (CLI/UI) can present
+* a plain-language warning and re-run with explicit confirmation. NOTHING is
+* deleted — the migration aborts cleanly with no changes made.
+*/
+var BackupSpaceError = class extends MigrationError {
+	estimatedBytes;
+	freeBytes;
+	constructor(message, guidance, estimatedBytes, freeBytes) {
+		super(message, guidance, null);
+		this.estimatedBytes = estimatedBytes;
+		this.freeBytes = freeBytes;
+		this.name = "BackupSpaceError";
+	}
+};
 var RELEASE_VERSION_KEY = "OP_RELEASE_VERSION";
 function resolveMigrationPaths(homeDir) {
 	return {
@@ -1218,7 +1496,7 @@ var RELEASE_MIGRATIONS = [
 		verify(ctx) {}
 	}
 ];
-var RECOVERY_GUIDANCE = "Your original files were left untouched and a full backup was taken first. To recover, restore the backup (see docs/operations/backup-restore.md) or run `openpalm migrate --dry-run` to preview the current copy-only migration. Full guide: docs/operations/upgrade-0.10-to-0.11.md";
+var RECOVERY_GUIDANCE = "Your original files were left untouched and a full backup was taken first. If something went wrong, run `openpalm rollback` to restore your previous state, or restore the backup manually (see docs/operations/backup-restore.md). You can also run `openpalm migrate --dry-run` to preview the current copy-only migration. Full guide: docs/operations/upgrade-0.10-to-0.11.md";
 function resolveComparableReleaseTarget(rawVersion) {
 	if (!rawVersion) return null;
 	return isComparableSemver(rawVersion) ? rawVersion : null;
@@ -1256,6 +1534,7 @@ function runReleaseMigrations(ctxBase, releaseFrom, targetVersion) {
 function ensureMigrated(opts = {}) {
 	const homeDir = opts.homeDir ? resolve(opts.homeDir) : process.env.OP_HOME ? resolve(process.env.OP_HOME) : resolve(process.env.HOME ?? "", ".openpalm");
 	const dryRun = opts.dryRun ?? false;
+	const confirmLowSpace = opts.confirmLowSpace ?? false;
 	const log = opts.log ?? (() => {});
 	const ctxBase = {
 		...resolveMigrationPaths(homeDir),
@@ -1299,6 +1578,8 @@ function ensureMigrated(opts = {}) {
 			}
 			lock = acquireInstallLock(ctxBase.dataDir);
 			if (!lock) throw new MigrationError("Another install/upgrade is in progress.", RECOVERY_GUIDANCE, null);
+			const spaceCheck = checkBackupFreeSpace(homeDir);
+			if (spaceCheck.insufficient && !confirmLowSpace) throw new BackupSpaceError(describeBackupSpaceShortfall(spaceCheck), RECOVERY_GUIDANCE, spaceCheck.estimatedBytes, spaceCheck.freeBytes);
 			log("Taking a full backup before migrating…");
 			try {
 				backupDir = backupOpenPalmHome(homeDir);
@@ -4734,10 +5015,6 @@ function resolveLocalOpenpalmDir() {
 */
 var NPM_REGISTRY = "https://registry.npmjs.org";
 var UI_PACKAGE = "@openpalm/ui";
-/** Strip a single leading 'v' so a release ref (v1.2.3) becomes an npm version (1.2.3). */
-function toNpmVersion(repoRef) {
-	return repoRef.replace(/^v/, "");
-}
 /**
 * Resolve the npm manifest for `@openpalm/ui` by exact version OR dist-tag.
 * `GET <registry>/@openpalm/ui/<version-or-tag>` returns the abbreviated
@@ -4748,10 +5025,13 @@ async function fetchNpmUiManifest(versionOrTag) {
 	if (!res.ok) throw new Error(`npm registry returned HTTP ${res.status} for ${UI_PACKAGE}@${versionOrTag}`);
 	const m = await res.json();
 	if (!m.version || !m.dist?.tarball) throw new Error(`npm manifest for ${UI_PACKAGE}@${versionOrTag} is missing version/dist.tarball`);
+	const rawMin = typeof m.minHarnessContract === "number" ? m.minHarnessContract : Number(m.minHarnessContract);
+	const minHarnessContract = Number.isFinite(rawMin) && rawMin > 0 ? rawMin : 0;
 	return {
 		version: m.version,
 		tarball: m.dist.tarball,
-		integrity: m.dist.integrity ?? null
+		integrity: m.dist.integrity ?? null,
+		minHarnessContract
 	};
 }
 /**
@@ -4828,7 +5108,7 @@ async function downloadNpmUiBundle(manifest, uiDir, dataDir) {
 async function seedUiBuild(repoRef, dataDir, options) {
 	const uiDir = join(dataDir, "ui");
 	mkdirSync(uiDir, { recursive: true });
-	const manifest = await fetchNpmUiManifest(toNpmVersion(repoRef));
+	const manifest = await fetchNpmUiManifest(normalizeVersion(repoRef));
 	logger$9.debug("downloading UI build from npm", { version: manifest.version });
 	await downloadNpmUiBundle(manifest, uiDir, dataDir);
 }
@@ -5282,20 +5562,84 @@ function writeSystemEnv(state) {
 		if (!hasUsableOperatorId(parsed, "OP_GID")) adminManaged.OP_GID = String(ids.gid);
 	}
 	if (!parsed.OP_HOME) adminManaged.OP_HOME = state.homeDir;
-	base = stripSecretLikeEnvKeys(base);
+	const { content: strippedBase, removed } = stripSecretLikeEnvKeys(base);
+	base = strippedBase;
+	if (removed.length > 0) {
+		logger$7.warn("Removed secret-looking keys from stack.env (they belong in Connections/secrets)", {
+			removedKeys: removed,
+			stackEnvPath: systemEnvPath
+		});
+		recordSecretStripNotice(state, removed);
+	}
 	assertNoSecretLikeStackEnvKeys(parseEnvContent(base));
 	assertNoSecretLikeStackEnvKeys(adminManaged);
 	writeFileSync(systemEnvPath, mergeEnvContent(base, adminManaged, { sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────" }), { mode: 384 });
 	chmodSync(systemEnvPath, 384);
 }
 function stripSecretLikeEnvKeys(content) {
-	return content.split("\n").filter((line) => {
-		let trimmed = line.trim();
-		if (trimmed.startsWith("export ")) trimmed = trimmed.slice(7).trimStart();
-		const eq = trimmed.indexOf("=");
-		if (eq <= 0) return true;
-		return !isSecretLikeStackEnvKey(trimmed.slice(0, eq).trim());
-	}).join("\n");
+	const removed = [];
+	return {
+		content: content.split("\n").filter((line) => {
+			let trimmed = line.trim();
+			if (trimmed.startsWith("export ")) trimmed = trimmed.slice(7).trimStart();
+			const eq = trimmed.indexOf("=");
+			if (eq <= 0) return true;
+			const key = trimmed.slice(0, eq).trim();
+			if (isSecretLikeStackEnvKey(key)) {
+				removed.push(key);
+				return false;
+			}
+			return true;
+		}).join("\n"),
+		removed
+	};
+}
+/**
+* Path of the one-time "secret-looking values were removed from stack.env"
+* notice the UI reads and dismisses.
+*/
+function secretStripNoticePath(state) {
+	return `${state.dataDir}/secret-strip-notice.json`;
+}
+function recordSecretStripNotice(state, newlyRemoved) {
+	const path = secretStripNoticePath(state);
+	let keys = new Set(newlyRemoved);
+	if (existsSync(path)) try {
+		const prior = JSON.parse(readFileSync(path, "utf-8"));
+		if (Array.isArray(prior.keys)) keys = new Set([...prior.keys, ...newlyRemoved]);
+	} catch {}
+	const notice = {
+		keys: [...keys].sort(),
+		at: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		mkdirSync(state.dataDir, { recursive: true });
+		writeFileSync(path, JSON.stringify(notice, null, 2));
+	} catch (e) {
+		logger$7.warn("Could not persist secret-strip notice", { error: e instanceof Error ? e.message : String(e) });
+	}
+}
+/** Read the pending secret-strip notice, or null when there is none. */
+function readSecretStripNotice(state) {
+	const path = secretStripNoticePath(state);
+	if (!existsSync(path)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8"));
+		if (Array.isArray(parsed.keys) && parsed.keys.length > 0 && typeof parsed.at === "string") return {
+			keys: parsed.keys,
+			at: parsed.at
+		};
+	} catch {}
+	return null;
+}
+/** Dismiss (delete) the pending secret-strip notice. */
+function dismissSecretStripNotice(state) {
+	const path = secretStripNoticePath(state);
+	if (existsSync(path)) try {
+		rmSync(path);
+	} catch (e) {
+		logger$7.warn("Could not dismiss secret-strip notice", { error: e instanceof Error ? e.message : String(e) });
+	}
 }
 function generateFallbackSystemEnv(state) {
 	const ids = resolveOperatorIds(state.homeDir);
@@ -6723,8 +7067,6 @@ function writeFileAtomic(path, content, mode) {
 	writeFileSync(tmp, content, mode !== void 0 ? { mode } : {});
 	renameSync(tmp, path);
 }
-var package_default = {
-	version: "0.12.0-rc.1"};
 //#endregion
 //#region ../lib/src/control-plane/rollback.ts
 /**
@@ -6878,9 +7220,12 @@ var DOCKER_REGISTRY_TIMEOUT_MS = 1e4;
 /**
 * Resolve the best Docker image tag from a registry tags payload.
 *
-* Constraints (both optional):
-* - `sameMajorAs`  — only consider tags whose major component matches this tag.
-* - `atOrBelow`    — only consider tags whose version is <= this tag.
+* Constraints (all optional):
+* - `sameMajorAs`    — only consider tags whose major component matches this tag.
+* - `atOrBelow`      — only consider tags whose version is <= this tag.
+* - `skipPrerelease` — ignore prerelease tags (`-rc`, `-beta`, …). Used so a
+*                      STABLE base never auto-jumps onto a prerelease (#494),
+*                      mirroring the UI card's channel gate.
 *
 * With no constraints: returns the first semver tag found, or the first
 * non-"latest" tag as a fallback (mirrors the original resolveNewestDockerTag).
@@ -6889,8 +7234,8 @@ var DOCKER_REGISTRY_TIMEOUT_MS = 1e4;
 function resolveNewestDockerTag(payload, constraints = {}) {
 	const results = payload?.results;
 	if (!Array.isArray(results)) return null;
-	const { sameMajorAs, atOrBelow } = constraints;
-	if (!(sameMajorAs !== void 0 || atOrBelow !== void 0)) {
+	const { sameMajorAs, atOrBelow, skipPrerelease } = constraints;
+	if (!(sameMajorAs !== void 0 || atOrBelow !== void 0 || skipPrerelease === true)) {
 		let fallback = null;
 		for (const entry of results) {
 			const name = typeof entry?.name === "string" ? entry.name.trim() : "";
@@ -6904,6 +7249,7 @@ function resolveNewestDockerTag(payload, constraints = {}) {
 	for (const entry of results) {
 		const name = typeof entry?.name === "string" ? entry.name.trim() : "";
 		if (!isComparableSemver(name)) continue;
+		if (skipPrerelease && isPrerelease(name)) continue;
 		if (sameMajorAs !== void 0 && !isSameMajorVersion(name, sameMajorAs)) continue;
 		if (atOrBelow !== void 0 && compareComparableVersions(name, atOrBelow) > 0) continue;
 		if (!best || compareComparableVersions(name, best) > 0) best = name;
@@ -6913,7 +7259,69 @@ function resolveNewestDockerTag(payload, constraints = {}) {
 function resolvePlatformVersionPolicyBaseTag(state) {
 	const configured = parseEnvFile(`${state.stashDir}/env/stack.env`).OP_IMAGE_TAG?.trim();
 	if (isComparableSemver(configured)) return configured;
-	return `v${package_default.version}`;
+	return PLATFORM_VERSION;
+}
+/**
+* Host-vs-target guard (#492), keyed on the RUNNING control-plane version.
+*
+* The migrations a release needs live inside the @openpalm/lib that is actually
+* executing — i.e. PLATFORM_VERSION (the version of the running data/ui build, or
+* the compiled-in CLI lib). If a user points the stack at a tag NEWER than the
+* control plane they're running, `ensureReleaseMigrated` runs an OLD migration
+* array that doesn't contain that release's migrations → the new images come up
+* against half-migrated files. There is no safe recovery, so this is a HARD block
+* (not a warning): nothing is written before it throws.
+*
+* The thin-harness design (§6.5) makes this satisfiable: the supervisor self-
+* updates data/ui to the current platform BEFORE the UI serves the upgrade
+* request, so "target ≤ running platform" only fails when the user genuinely
+* picks a tag the running control plane cannot migrate to — at which point the
+* fix is to update the app / control plane first, not to proceed.
+*
+* Non-semver targets (a moving `latest`/`dev` tag) are not comparable and are
+* left to the resolver paths that turn them into a concrete release first.
+*/
+/**
+* Downgrade-needs-confirmation signal (#501).
+*
+* Release migrations are forward-only (copy-only, additive); they do NOT run
+* backward. Pointing the stack at an OLDER tag than the one currently running is
+* therefore a data-safety event, not a routine version change: the older images
+* may not understand files the newer release already migrated. We don't block it
+* (a user may legitimately need to roll back), but we require an explicit
+* confirmation so it can't happen by a stray dropdown selection. The UI catches
+* this by `code` and shows a plain warning + confirm; the CLI surfaces the
+* message and a `--confirm`/`--yes` path.
+*/
+var DowngradeConfirmationRequired = class extends Error {
+	code = "downgrade_confirmation_required";
+	currentVersion;
+	targetVersion;
+	constructor(currentVersion, targetVersion) {
+		super(`Version ${formatForDisplay(targetVersion)} is older than the version you're running (${formatForDisplay(currentVersion)}). This is a downgrade. Release migrations don't run backward; your data may not be compatible — restore from backup if needed. Re-run with confirmation to proceed. Nothing was changed.`);
+		this.name = "DowngradeConfirmationRequired";
+		this.currentVersion = currentVersion;
+		this.targetVersion = targetVersion;
+	}
+};
+/**
+* Throw {@link DowngradeConfirmationRequired} when `targetTag` is strictly older
+* than the version currently configured in stack.env, unless the caller passed
+* an explicit confirmation. Non-semver tags (a moving `latest`/`dev` ref, or a
+* first install with no current tag) are not comparable and pass through — the
+* resolver paths turn `latest` into a concrete release before this runs.
+*/
+function assertNotUnconfirmedDowngrade(state, targetTag, confirmDowngrade) {
+	if (confirmDowngrade) return;
+	const currentTag = resolvePlatformVersionPolicyBaseTag(state);
+	if (!isComparableSemver(targetTag) || !isComparableSemver(currentTag)) return;
+	if (compareComparableVersions(targetTag, currentTag) >= 0) return;
+	throw new DowngradeConfirmationRequired(currentTag, targetTag);
+}
+function assertTargetNotNewerThanPlatform(targetTag) {
+	if (!isComparableSemver(targetTag) || !isComparableSemver(PLATFORM_VERSION)) return;
+	if (compareComparableVersions(targetTag, PLATFORM_VERSION) <= 0) return;
+	throw new Error(`Version ${formatForDisplay(targetTag)} is newer than the OpenPalm control plane you're running (${formatForDisplay(PLATFORM_VERSION)}). Update the OpenPalm app / control plane first, then update the stack. Nothing was changed.`);
 }
 function resolveImageNamespace(state) {
 	const namespace = (parseEnvFile(`${state.stashDir}/env/stack.env`).OP_IMAGE_NAMESPACE ?? process.env.OP_IMAGE_NAMESPACE ?? "openpalm").trim().toLowerCase();
@@ -7017,9 +7425,22 @@ async function resolveLatestPlatformTag(namespace) {
 	if (!latestTag) throw new Error("No usable Docker image tag found");
 	return latestTag;
 }
-async function resolveLatestPlatformTagForCurrentMajor(namespace, currentTag) {
-	const latestTag = resolveNewestDockerTag(await fetchDockerTagsPayload(namespace, "assistant"), { sameMajorAs: currentTag });
-	if (!latestTag) throw new Error(`No usable Docker image tag found in major ${currentTag.replace(/^v/, "").split(".")[0]}`);
+/**
+* Resolve the default target version for `openpalm migrate --dry-run`: the
+* newest published platform tag in the current major. Mirrors the resolver the
+* upgrade path uses (same namespace, same base tag, same prerelease policy) so a
+* dry-run preview reflects the exact version `openpalm update` would move to.
+*/
+async function resolveDefaultMigrateTarget(state, opts = {}) {
+	return resolveLatestPlatformTagForCurrentMajor(resolveImageNamespace(state), resolvePlatformVersionPolicyBaseTag(state), { allowPrerelease: opts.allowPrerelease });
+}
+async function resolveLatestPlatformTagForCurrentMajor(namespace, currentTag, opts = {}) {
+	const skipPrerelease = !opts.allowPrerelease && !isPrerelease(currentTag);
+	const latestTag = resolveNewestDockerTag(await fetchDockerTagsPayload(namespace, "assistant"), {
+		sameMajorAs: currentTag,
+		skipPrerelease
+	});
+	if (!latestTag) throw new Error(`No usable Docker image tag found in major ${majorVersionOf(currentTag) ?? currentTag}`);
 	return latestTag;
 }
 async function updateStackEnvToLatestImageTag(state, resolvedTag) {
@@ -7077,11 +7498,12 @@ async function withStackEnvRollback(state, run) {
 *
 * Callers handle their own audit logging and admin self-recreation.
 */
-async function performUpgrade(state) {
+async function performUpgrade(state, opts = {}) {
 	return withStackEnvRollback(state, async () => {
 		const composeOpts = buildComposeOptions(state);
 		const namespace = resolveImageNamespace(state);
-		const imageTag = await resolveLatestPlatformTagForCurrentMajor(namespace, resolvePlatformVersionPolicyBaseTag(state));
+		const imageTag = await resolveLatestPlatformTagForCurrentMajor(namespace, resolvePlatformVersionPolicyBaseTag(state), { allowPrerelease: opts.allowPrerelease });
+		assertTargetNotNewerThanPlatform(imageTag);
 		ensureReleaseMigrated({
 			homeDir: state.homeDir,
 			targetVersion: imageTag
@@ -7112,7 +7534,7 @@ async function performUpgrade(state) {
 * Set a specific image tag in stack.env then pull images and restart containers.
 * Used by the admin "set version" action — skips the auto-detect step in performUpgrade.
 */
-async function applyTagChange(state, tag) {
+async function applyTagChange(state, tag, opts = {}) {
 	return withStackEnvRollback(state, async () => {
 		const namespace = resolveImageNamespace(state);
 		const requested = tag.trim();
@@ -7123,6 +7545,8 @@ async function applyTagChange(state, tag) {
 			const msg = e instanceof Error ? e.message : String(e);
 			throw new Error(`Cannot resolve "latest" to a concrete release: ${msg}. Check your network connection or select a specific version.`);
 		}
+		assertTargetNotNewerThanPlatform(resolvedTag);
+		assertNotUnconfirmedDowngrade(state, resolvedTag, opts.confirmDowngrade ?? false);
 		const stackEnvPath = `${state.stashDir}/env/stack.env`;
 		const currentEnv = parseEnvFile(stackEnvPath);
 		const pinnedImages = parsePinnedImages(currentEnv.OP_PINNED_IMAGES);
@@ -7608,7 +8032,7 @@ async function runDeploy(state, options = {}) {
 	const lock = acquireInstallLock(state.dataDir);
 	if (!lock) {
 		progress.deploying = false;
-		progress.deployError = "install_in_progress: A deploy is already running. Wait for it to finish.";
+		progress.deployError = "install_in_progress: A deploy is already running. Wait for it to finish (the lock clears itself automatically after 30 minutes). If you're sure nothing is running, run 'openpalm unlock' to clear a stale lock.";
 		emitProgress(options, progress);
 		return progress;
 	}
@@ -9282,7 +9706,7 @@ async function performSetup(input, opts) {
 	const lockHandle = acquireInstallLock(state.dataDir);
 	if (lockHandle === null) return {
 		ok: false,
-		error: "install_in_progress: Another install is in progress. Wait for it to finish, or remove state/.install.lock if you're sure no install is running."
+		error: "install_in_progress: Another install is in progress. Wait for it to finish (the lock clears itself automatically after 30 minutes). If you're sure nothing is running, run 'openpalm unlock' to clear a stale lock."
 	};
 	logger.info("performing setup", { connectionCount: connections.length });
 	const updates = buildOwnerEnvFromSetup(owner);
@@ -9768,5 +10192,5 @@ function collectBindAddressWarnings(env) {
 	return warnings;
 }
 
-export { getAddonProfiles as $, AKM_USER_ENV_REF as A, composeStop as B, CORE_SERVICES as C, composeUp as D, createLogger as E, createOpenCodeClient as F, createState as G, deleteUserEnvKey as H, deriveLaunchStatus as I, deriveLocalStackState as J, detectGpu as K, detectHostOpenCode as L, MigrationError as M, detectLocalProviders as N, detectRuntime as O, disableHostAkmSharing as P, enableHostAkmSharing as Q, ensureAkmUserEnv as R, ensureHomeDirs as S, ensureMigrated as T, ensureOpenCodeConfig as U, ensureOpenCodeSystemConfig as V, ensureSecrets as W, executeAutomation as X, fetchProviderModels as Y, getAddonProfileAvailability as Z, getAddonProfileSelection as _, addonProfileId as a, getAddonServiceNames as a0, getAkmStats as a1, getDockerEvents as a2, getHostAkmSharingStatus as a3, getRegistryAddonConfig as a4, hostAkmStashPath as a5, importHostOpenCode as a6, initializeStateSecrets as a7, isAllowedService as a8, isHostAkmAvailable as a9, resolveDataDir as aA, resolveDeployJournalPath as aB, resolveRuntimeFiles as aC, resolveStackDir as aD, runDeploy as aE, seedUiBuild as aF, setAddonEnabled as aG, setAddonProfileSelection as aH, summarizeComposeStderr as aI, useExistingProviderForAssistantCli as aJ, validateProposedState as aK, writeFileAtomic as aL, writeRuntimeFiles as aM, writeSecretFile as aN, writeStackSecretEnv as aO, writeTaskFile as aP, writeUserEnvKey as aQ, writeVoiceVars as aR, isSetupComplete as aa, listAssistantCliTools as ab, listAvailableAddonIds as ac, listEnabledAddonIds as ad, listSecretFiles as ae, loadAutomations as af, mapDockerError as ag, markSetupComplete as ah, parseComposeStderr as ai, parseEnvFile as aj, patchSecretsEnvFile as ak, performSetup as al, performUpgrade as am, readAutomationLogs as an, readDeployJournal as ao, readSecret as ap, readSecretFile as aq, readStackEnv as ar, readStackRuntimeEnv as as, readStackSecretEnv as at, readTaskFile as au, readUserEnvFile as av, recommendSetup as aw, removeSecretFile as ax, removeTaskFile as ay, resolveComposeProjectName as az, annotateAddonProfileAvailability as b, applyInstall as c, applyTagChange as d, applyUninstall as e, applyUpdate as f, assertSafeSecretFilename as g, assertSafeTaskFilename as h, authJsonPath as i, backupSetupInputs as j, buildAkmEndpoint as k, buildAkmEnv as l, buildComposeOptions as m, buildManagedServices as n, checkDocker as o, checkDockerCompose as p, classifyLocalInstall as q, collectBindAddressWarnings as r, composeDown as s, composeLogs as t, composePreflight as u, composePs as v, composePull as w, composeRestart as x, composeStart as y, composeStats as z };
-//# sourceMappingURL=src-CHZNd5cO.js.map
+export { ensureReleaseMigrated as $, AKM_USER_ENV_REF as A, composeStats as B, CORE_SERVICES as C, DowngradeConfirmationRequired as D, composeStop as E, composeUp as F, createLogger as G, createOpenCodeClient as H, INSTALL_LOCK_STALE_AFTER_MS as I, createState as J, deleteUserEnvKey as K, deriveLaunchStatus as L, MigrationError as M, deriveLocalStackState as N, detectGpu as O, PLATFORM_VERSION as P, detectHostOpenCode as Q, detectLocalProviders as R, detectRuntime as S, disableHostAkmSharing as T, dismissSecretStripNotice as U, enableHostAkmSharing as V, ensureAkmUserEnv as W, ensureHomeDirs as X, ensureMigrated as Y, ensureOpenCodeConfig as Z, ensureOpenCodeSystemConfig as _, addonProfileId as a, writeRuntimeFiles as a$, ensureSecrets as a0, executeAutomation as a1, fetchProviderModels as a2, formatForDisplay as a3, getAddonProfileAvailability as a4, getAddonProfileSelection as a5, getAddonProfiles as a6, getAddonServiceNames as a7, getAkmStats as a8, getDockerEvents as a9, readSecret as aA, readSecretFile as aB, readSecretStripNotice as aC, readStackEnv as aD, readStackRuntimeEnv as aE, readStackSecretEnv as aF, readTaskFile as aG, readUserEnvFile as aH, recommendSetup as aI, removeSecretFile as aJ, removeTaskFile as aK, resolveComposeProjectName as aL, resolveDataDir as aM, resolveDefaultMigrateTarget as aN, resolveDeployJournalPath as aO, resolveRuntimeFiles as aP, resolveStackDir as aQ, runDeploy as aR, seedUiBuild as aS, setAddonEnabled as aT, setAddonProfileSelection as aU, summarizeBackups as aV, summarizeComposeStderr as aW, unlockInstallLock as aX, useExistingProviderForAssistantCli as aY, validateProposedState as aZ, writeFileAtomic as a_, getHostAkmSharingStatus as aa, getRegistryAddonConfig as ab, hostAkmStashPath as ac, importHostOpenCode as ad, initializeStateSecrets as ae, inspectInstallLock as af, isAllowedService as ag, isComparableSemver as ah, isHostAkmAvailable as ai, isSetupComplete as aj, listAssistantCliTools as ak, listAvailableAddonIds as al, listBackupDirs as am, listEnabledAddonIds as an, listSecretFiles as ao, loadAutomations as ap, mapDockerError as aq, markSetupComplete as ar, parseComposeStderr as as, parseEnvFile as at, patchSecretsEnvFile as au, performSetup as av, performUpgrade as aw, pruneBackupDirs as ax, readAutomationLogs as ay, readDeployJournal as az, annotateAddonProfileAvailability as b, writeSecretFile as b0, writeStackSecretEnv as b1, writeTaskFile as b2, writeUserEnvKey as b3, writeVoiceVars as b4, applyInstall as c, applyTagChange as d, applyUninstall as e, applyUpdate as f, assertSafeSecretFilename as g, assertSafeTaskFilename as h, authJsonPath as i, backupSetupInputs as j, buildAkmEndpoint as k, buildAkmEnv as l, buildComposeOptions as m, buildManagedServices as n, checkDocker as o, checkDockerCompose as p, classifyLocalInstall as q, collectBindAddressWarnings as r, compareComparableVersions as s, composeDown as t, composeLogs as u, composePreflight as v, composePs as w, composePull as x, composeRestart as y, composeStart as z };
+//# sourceMappingURL=src-B7oqi9q_.js.map