@openpalm/lib 0.11.0-beta.9 → 0.11.0-rc.18

package/src/control-plane/ui-assets.ts

@@ -4,21 +4,22 @@
  * These functions are consumed by both the CLI and the Electron shell — they
  * must use only Node.js-compatible APIs (no Bun.spawn, Bun.write, etc.).
  *
- * Source resolution order (same for UI build and .openpalm/):
+ * Source resolution order (UI build and .openpalm/ skeleton):
  *   1. OPENPALM_REPO_ROOT env var — explicit dev override
  *   2. Relative to import.meta.url — works for `bun run` / source installs
  *   3. Relative to process.execPath — works for compiled Bun binary in repo
- *   4. null → GitHub release download
+ *   4. null → remote download (the UI build from the @openpalm/ui npm registry
+ *      tarball; the .openpalm skeleton from the GitHub repo tarball)
  */
 import {
   existsSync, mkdirSync, readdirSync, copyFileSync,
-  readFileSync, writeFileSync, rmSync, realpathSync, renameSync,
+  writeFileSync, readFileSync, rmSync, realpathSync, renameSync,
 } from 'node:fs';
 import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
 import { x as tarExtract } from 'tar';
-import { resolveStateDir } from './home.js';
+import { resolveBackupsDir, resolveDataDir } from './home.js';
 import { createLogger } from '../logger.js';
 
 const logger = createLogger('lib:ui-assets');
@@ -87,13 +88,15 @@ export function resolveLocalOpenpalmDir(): string | null {
     () => process.env.OPENPALM_REPO_ROOT
       ? join(process.env.OPENPALM_REPO_ROOT, '.openpalm')
       : null,
-    // 2. Relative to this source file (dev / bun run)
+    // 2. Electron extraResources — openpalm-skeleton/ placed alongside the asar
+    () => process.env.OPENPALM_SKELETON_DIR ?? null,
+    // 3. Relative to this source file (dev / bun run)
     () => {
       const meta = fileURLToPath(import.meta.url);
       if (meta.startsWith('/$bunfs/')) return null;
       return join(dirname(meta), '..', '..', '..', '..', '.openpalm');
     },
-    // 3. Relative to the compiled binary on disk
+    // 4. Relative to the compiled binary on disk
     () => join(dirname(realpathSync(process.execPath)), '..', '..', '..', '.openpalm'),
   );
 }
@@ -105,18 +108,44 @@ export function resolveLocalOpenpalmDir(): string | null {
  * Falls back to downloading the repo tarball from GitHub when no local
  * skeleton is found (production binary, packaged Electron app).
  */
+/** Version stamp recording which skeleton version OP_HOME was last seeded from. */
+export const SKELETON_VERSION_STAMP = '.skeleton-version';
+
+/**
+ * Seed the bundled `.openpalm/` skeleton into OP_HOME — ONCE PER VERSION.
+ *
+ * Electron calls this on every launch; without a guard it re-copied the entire
+ * skeleton tree each time (wasteful, and it re-materialized files a user/process
+ * had deliberately removed). We stamp OP_HOME/.skeleton-version with `repoRef`
+ * after a successful seed and skip the copy when it already matches — so a given
+ * version seeds once and an upgrade re-seeds (skipExisting still preserves any
+ * user edits). To force a re-seed, delete the stamp.
+ */
 export async function seedOpenPalmDir(
   repoRef: string,
   homeDir: string,
   _configDir: string,
-  _stateDir: string,
+  _dataDir: string,
 ): Promise<void> {
+  const stampPath = join(homeDir, SKELETON_VERSION_STAMP);
+  if (existsSync(stampPath)) {
+    try {
+      if (readFileSync(stampPath, 'utf-8').trim() === repoRef.trim()) {
+        logger.debug('skeleton already seeded for this version — skipping', { repoRef });
+        return;
+      }
+    } catch { /* unreadable stamp → re-seed */ }
+  }
+
+  const stamp = (): void => {
+    try { writeFileSync(stampPath, `${repoRef}\n`); } catch { /* best-effort */ }
+  };
+
   const local = resolveLocalOpenpalmDir();
   if (local) {
-    logger.debug('seeding .openpalm from local source', { src: local });
+    logger.debug('seeding .openpalm from local source', { src: local, repoRef });
     copyTree(local, homeDir, { skipExisting: true });
-    // Registry is system-managed — always refresh so addon overlays stay current.
-    copyTree(join(local, 'state', 'registry'), join(homeDir, 'state', 'registry'));
+    stamp();
     return;
   }
 
@@ -137,8 +166,7 @@ export async function seedOpenPalmDir(
     const srcOpenpalm = join(tmpDir, '.openpalm');
     if (!existsSync(srcOpenpalm)) throw new Error('.openpalm/ not found in tarball');
     copyTree(srcOpenpalm, homeDir, { skipExisting: true });
-    // Registry is system-managed — always refresh so addon overlays stay current.
-    copyTree(join(srcOpenpalm, 'state', 'registry'), join(homeDir, 'state', 'registry'));
+    stamp();
   } finally {
     rmSync(tmpDir, { recursive: true, force: true });
   }
@@ -148,7 +176,7 @@ export async function seedOpenPalmDir(
 
 /**
  * Locate the compiled SvelteKit UI build on disk.
- * Returns null when not found — triggers GitHub download in seedUiBuild.
+ * Returns null when not found — triggers the npm registry download in seedUiBuild.
  */
 export function resolveLocalUiBuild(): string | null {
   return resolveLocalCandidate(
@@ -179,140 +207,258 @@ export function resolveLocalUiBuild(): string | null {
   );
 }
 
-function readUiVersionFile(dir: string): string | null {
-  try { return readFileSync(join(dir, 'version.txt'), 'utf-8').trim(); } catch { return null; }
-}
-
 /**
  * Resolve the best available UI build directory at runtime.
  *
  * Priority:
- *   1. OP_HOME/state/ui/ — if its version.txt is NEWER than the bundled build
- *   2. Bundled / local build (Electron extraResources, source checkout)
- *   3. OP_HOME/state/ui/ — fallback when no bundled build exists
+ *   1. OP_HOME/data/ui/ — user-installed or auto-updated build
+ *   2. Bundled / local build (Electron extraResources, OPENPALM_REPO_ROOT, source checkout)
+ */
+/** Filename of the build-time version stamp written into the UI build root. */
+export const UI_VERSION_STAMP = '.openpalm-ui-version';
+
+/** Read the stamped UI version from a build dir, or null if absent/unreadable. */
+export function readUiBuildVersion(dir: string): string | null {
+  try {
+    const v = readFileSync(join(dir, UI_VERSION_STAMP), 'utf-8').trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve which UI build to run.
+ *
+ * Two channels exist: the bundled build (shipped inside the AppImage / source
+ * tree) and `data/ui` (operator-updatable, seeded from the @openpalm/ui npm
+ * registry tarball). To fix
+ * the stale-`data/ui` shadowing bug AND stay forward-compatible with updating the
+ * UI without shipping a new app (D5), selection is VERSION-AWARE:
  *
- * This means GitHub-downloaded updates are applied automatically (disk wins
- * when newer), but a fresh AppImage install always works without a download.
+ *   - If only one channel has a build → use it.
+ *   - If both exist → use `data/ui` ONLY when it is strictly NEWER than the
+ *     bundled build (per the version stamp); otherwise prefer the bundled build.
+ *     An unstamped/older `data/ui` never shadows a newer bundled build.
+ *
+ * This means a fresh app runs its bundled UI, and a future "update UI only" flow
+ * (seed a newer-stamped build into data/ui) is picked up automatically — no app
+ * reinstall required.
  */
 export function resolveUiBuildDir(): string {
-  const stateBuild = join(resolveStateDir(), 'ui');
-  const localBuild = resolveLocalUiBuild();
-
-  if (existsSync(join(stateBuild, 'index.js')) && localBuild) {
-    const diskVer    = readUiVersionFile(stateBuild);
-    const bundledVer = readUiVersionFile(localBuild);
-    if (diskVer && bundledVer && compareVersionTags(diskVer, bundledVer) > 0) {
-      return stateBuild;
-    }
-    return localBuild;
+  const dataBuild = join(resolveDataDir(), 'ui');
+  const hasData = existsSync(join(dataBuild, 'index.js'));
+  // resolveLocalUiBuild()'s env/resourcesPath candidates only check the dir
+  // exists, not that it holds a runnable build — require index.js before trusting it.
+  const bundledRaw = resolveLocalUiBuild();
+  const bundled = bundledRaw && existsSync(join(bundledRaw, 'index.js')) ? bundledRaw : null;
+
+  if (hasData && bundled) {
+    const dataVer = readUiBuildVersion(dataBuild);
+    const bundledVer = readUiBuildVersion(bundled);
+    // data/ui wins only when we can prove it's strictly newer.
+    if (dataVer && bundledVer && compareVersionTags(dataVer, bundledVer) > 0) return dataBuild;
+    return bundled;
   }
+  if (hasData) return dataBuild;
+  if (bundled) return bundled;
+  return dataBuild; // nothing present yet → caller triggers seedUiBuild
+}
 
-  if (localBuild) return localBuild;
-  return stateBuild;
+/**
+ * The UI ships as `@openpalm/ui` on npm — a self-contained `adapter-node`
+ * bundle (only `build/` is published; no `node_modules` is needed at runtime,
+ * because the build bundles every dependency). The desktop and host updaters
+ * fetch the registry TARBALL over plain HTTPS and verify its integrity hash;
+ * they never invoke a package manager (the Electron runtime has none). npm gives
+ * us, for free, the four things the GitHub-release path forced us to hand-roll:
+ * an independent version line, `latest`/`next` dist-tag channels (prerelease-
+ * aware — unlike `releases/latest`, which silently excludes prereleases),
+ * immutable versions, and a sha512 integrity we verify fail-closed.
+ */
+const NPM_REGISTRY = 'https://registry.npmjs.org';
+const UI_PACKAGE   = '@openpalm/ui';
+
+interface NpmUiManifest {
+  version: string;
+  tarball: string;
+  /** Subresource-integrity string ("sha512-<base64>"); null if the registry omitted it. */
+  integrity: string | null;
+}
+
+/** Strip a single leading 'v' so a release ref (v1.2.3) becomes an npm version (1.2.3). */
+function toNpmVersion(repoRef: string): string {
+  return repoRef.replace(/^v/, '');
 }
 
 /**
- * Install the UI build to OP_HOME/state/ui/.
- *
- * Copies from local packages/ui/build/ when running from source,
- * otherwise downloads ui-build.tar.gz from the GitHub release.
- * Called during install and update; always replaces existing content.
- *
- * state/ui/ is automatically included in backups because
- * backupOpenPalmHome() copies all of OP_HOME/state/.
+ * The npm dist-tag channel a release stream tracks: prereleases ride `next`,
+ * stable rides `latest`. `@openpalm/ui` is independently versioned (it publishes
+ * on its own `publish-ui.yml` workflow, like the channel adapters), so the
+ * desktop/host updaters can't compare a UI version against the app version —
+ * they pick the CHANNEL from the app's release stream and then resolve the
+ * newest UI on that channel.
  */
-/** SHA-256 hex digest of arbitrary bytes. */
-function sha256Hex(data: Uint8Array): string {
-  return createHash('sha256').update(data).digest('hex');
+export function uiUpdateChannel(appVersion: string): 'latest' | 'next' {
+  return appVersion.includes('-') ? 'next' : 'latest';
 }
 
 /**
- * Parse a `sha256sum`-format checksums file into a filename→hash map.
- * Each line is: `<hash>  <filename>` (one or two spaces).
+ * Resolve the npm manifest for `@openpalm/ui` by exact version OR dist-tag.
+ * `GET <registry>/@openpalm/ui/<version-or-tag>` returns the abbreviated
+ * manifest (version + dist.tarball + dist.integrity). Throws on non-OK.
  */
-function parseChecksumsFile(content: string): Map<string, string> {
-  const map = new Map<string, string>();
-  for (const line of content.trim().split('\n')) {
-    const parts = line.trim().split(/\s+/);
-    if (parts.length >= 2) {
-      map.set(parts[parts.length - 1], parts[0]);
-    }
+async function fetchNpmUiManifest(versionOrTag: string): Promise<NpmUiManifest> {
+  const url = `${NPM_REGISTRY}/${UI_PACKAGE}/${versionOrTag}`;
+  const res = await fetchWithRetry(url);
+  if (!res.ok) throw new Error(`npm registry returned HTTP ${res.status} for ${UI_PACKAGE}@${versionOrTag}`);
+  const m = await res.json() as { version?: string; dist?: { tarball?: string; integrity?: string } };
+  if (!m.version || !m.dist?.tarball) {
+    throw new Error(`npm manifest for ${UI_PACKAGE}@${versionOrTag} is missing version/dist.tarball`);
   }
-  return map;
+  return { version: m.version, tarball: m.dist.tarball, integrity: m.dist.integrity ?? null };
 }
 
-export function readCurrentUiBuildVersion(stateDir: string): string | null {
-  const versionFile = join(stateDir, 'ui', 'version.txt');
-  if (!existsSync(versionFile)) return null;
-  return readFileSync(versionFile, 'utf-8').trim() || null;
+/**
+ * Verify a Subresource-Integrity string against the bytes. FAIL-CLOSED: a
+ * present-but-wrong hash throws (the corruption / tamper case). A registry that
+ * omits the hash entirely (legacy metadata) is logged and allowed — modern npm
+ * always provides one, so this only affects pathological registry responses.
+ */
+function verifyNpmIntegrity(data: Uint8Array, integrity: string): void {
+  const entries = integrity.trim().split(/\s+/);
+  const entry = entries.find(e => e.startsWith('sha512-')) ?? entries.find(e => e.startsWith('sha256-'));
+  if (!entry) throw new Error(`unrecognized integrity format: ${integrity}`);
+  const dash = entry.indexOf('-');
+  const algo = entry.slice(0, dash);
+  const expected = entry.slice(dash + 1);
+  const actual = createHash(algo).update(data).digest('base64');
+  if (actual !== expected) throw new Error(`UI bundle integrity mismatch (${algo})`);
 }
 
-export async function seedUiBuild(repoRef: string, stateDir: string, options?: { forceRemote?: boolean }): Promise<void> {
-  const uiDir = join(stateDir, 'ui');
+/**
+ * Download `@openpalm/ui`'s npm tarball, verify integrity, and install its
+ * `build/` contents into `uiDir`. npm tarballs nest everything under `package/`
+ * and we publish `files: ["build"]`, so the bundle lives at `package/build/**` —
+ * strip 2 path components and filter to that subtree.
+ *
+ * FAIL-CLOSED + non-destructive: we throw if integrity is missing or mismatched
+ * (the contract is that npm always provides a sha512), and we extract into a
+ * STAGING dir and validate it has a runnable `index.js` before swapping it over
+ * `uiDir` — so a truncated download or bad tarball never leaves `uiDir` empty.
+ */
+async function downloadNpmUiBundle(manifest: NpmUiManifest, uiDir: string, dataDir: string): Promise<void> {
+  const res = await fetchWithRetry(manifest.tarball);
+  if (!res.ok) throw new Error(`Failed to download UI bundle (HTTP ${res.status})`);
+  const data = new Uint8Array(await res.arrayBuffer());
+
+  // Verify BEFORE touching anything. Fail closed: a missing hash is treated as a
+  // verification failure, not a warning — modern npm always supplies dist.integrity,
+  // so its absence means a non-canonical/altered registry response.
+  if (!manifest.integrity) {
+    throw new Error(`npm manifest for ${UI_PACKAGE}@${manifest.version} has no integrity hash — refusing to install unverified`);
+  }
+  verifyNpmIntegrity(data, manifest.integrity);
+  logger.debug('UI bundle integrity verified', { version: manifest.version });
+
+  const tmpTar  = join(dataDir, '.ui-build.tgz.tmp');
+  const staging = join(dataDir, '.ui-build.staging');
+  try {
+    rmSync(staging, { recursive: true, force: true });
+    mkdirSync(staging, { recursive: true });
+    writeFileSync(tmpTar, data);
+    await tarExtract({
+      file: tmpTar,
+      cwd: staging,
+      strip: 2,
+      filter: (p) => p.startsWith('package/build/'),
+    });
+    // Validate the staged build is runnable before destroying the live one.
+    if (!existsSync(join(staging, 'index.js'))) {
+      throw new Error('downloaded UI bundle is missing build/index.js');
+    }
+    // Swap: only now do we remove the existing build and move staging into place.
+    rmSync(uiDir, { recursive: true, force: true });
+    renameSync(staging, uiDir);
+  } finally {
+    rmSync(tmpTar, { force: true });
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Install the UI build to OP_HOME/data/ui/.
+ *
+ * Copies from the local/bundled `packages/ui/build/` when available, otherwise
+ * downloads the `@openpalm/ui` bundle from npm (by exact version; `repoRef` may
+ * be a tag like `latest`/`next` via the admin route). Always replaces existing
+ * content. data/ui/ is included in backups because backupOpenPalmHome() copies
+ * all of OP_HOME/data/.
+ */
+export async function seedUiBuild(repoRef: string, dataDir: string, options?: { forceRemote?: boolean }): Promise<void> {
+  const uiDir = join(dataDir, 'ui');
   mkdirSync(uiDir, { recursive: true });
 
   const local = options?.forceRemote ? null : resolveLocalUiBuild();
   if (local) {
     logger.debug('seeding UI build from local source', { src: local });
     copyTree(local, uiDir);
-    writeFileSync(join(uiDir, 'version.txt'), repoRef.replace(/^v/, ''));
+    // The build script (stamp-version.mjs) writes .openpalm-ui-version into build/.
+    // A local build missing it would seed an UNSTAMPED data/ui, which makes the
+    // update check unable to read the running UI version. Surface it loudly rather
+    // than silently degrade update behavior.
+    if (!readUiBuildVersion(uiDir)) {
+      logger.warn('seeded UI build has no version stamp — auto-update comparison will be unreliable', { src: local });
+    }
     return;
   }
 
-  const base         = `https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/download/${repoRef}`;
-  const tarballUrl   = `${base}/ui-build.tar.gz`;
-  const checksumUrl  = `${base}/checksums-sha256.txt`;
-  logger.debug('downloading UI build', { url: tarballUrl });
-
-  const tmpTar = join(stateDir, '.ui-build.tar.gz.tmp');
-  try {
-    // Download tarball and checksums file in parallel (checksums best-effort)
-    const [tarRes, csRes] = await Promise.all([
-      fetchWithRetry(tarballUrl),
-      fetchWithRetry(checksumUrl).catch(() => null),
-    ]);
-    if (!tarRes.ok) throw new Error(`Failed to download UI build (HTTP ${tarRes.status})`);
-
-    const tarData = new Uint8Array(await tarRes.arrayBuffer());
-
-    // Verify SHA-256 if the checksums file was available
-    if (csRes?.ok) {
-      const checksums = parseChecksumsFile(await csRes.text());
-      const expected  = checksums.get('ui-build.tar.gz');
-      if (expected) {
-        const actual = sha256Hex(tarData);
-        if (actual !== expected) {
-          throw new Error(`UI build checksum mismatch (expected ${expected}, got ${actual})`);
-        }
-        logger.debug('UI build checksum verified', { sha256: actual });
-      }
-    }
-
-    writeFileSync(tmpTar, tarData);
-
-    // Clear stale files before extracting so old build files don't persist
-    rmSync(uiDir, { recursive: true, force: true });
-    mkdirSync(uiDir, { recursive: true });
-    // Cross-platform extraction via the `tar` npm package — no shell dependency
-    await tarExtract({ file: tmpTar, cwd: uiDir, strip: 1 });
-    writeFileSync(join(uiDir, 'version.txt'), repoRef.replace(/^v/, ''));
-  } finally {
-    rmSync(tmpTar, { force: true });
-  }
+  const manifest = await fetchNpmUiManifest(toNpmVersion(repoRef));
+  logger.debug('downloading UI build from npm', { version: manifest.version });
+  await downloadNpmUiBundle(manifest, uiDir, dataDir);
 }
 
 // ── UI update check ──────────────────────────────────────────────────────────
 
-const GITHUB_API = 'https://api.github.com';
-
-/** Returns 1 if a > b, -1 if a < b, 0 if equal. Strips leading 'v'. */
+/** Returns 1 if a > b, -1 if a < b, 0 if equal. Strips leading 'v'. Handles pre-release tags. */
 function compareVersionTags(a: string, b: string): number {
-  const parse = (v: string) => v.replace(/^v/, '').split('.').map(Number);
-  const [aM, am, ap] = parse(a);
-  const [bM, bm, bp] = parse(b);
+  const parse = (v: string): [number, number, number, string | null] => {
+    const clean = v.replace(/^v/, '');
+    const dashIdx = clean.indexOf('-');
+    const main = dashIdx === -1 ? clean : clean.slice(0, dashIdx);
+    const pre = dashIdx === -1 ? null : clean.slice(dashIdx + 1);
+    const parts = main.split('.').map(Number);
+    return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0, pre];
+  };
+  const comparePre = (x: string, y: string): number => {
+    const xp = x.split('.');
+    const yp = y.split('.');
+    for (let i = 0; i < Math.max(xp.length, yp.length); i++) {
+      if (i >= xp.length) return -1;
+      if (i >= yp.length) return 1;
+      const xn = Number(xp[i]);
+      const yn = Number(yp[i]);
+      const xIsNum = !isNaN(xn);
+      const yIsNum = !isNaN(yn);
+      if (xIsNum && yIsNum) {
+        if (xn !== yn) return xn > yn ? 1 : -1;
+      } else if (xIsNum !== yIsNum) {
+        return xIsNum ? -1 : 1; // numeric < alphanumeric per semver
+      } else {
+        if (xp[i] !== yp[i]) return xp[i]! > yp[i]! ? 1 : -1;
+      }
+    }
+    return 0;
+  };
+  const [aM, am, ap, aPre] = parse(a);
+  const [bM, bm, bp, bPre] = parse(b);
   if (aM !== bM) return aM > bM ? 1 : -1;
   if (am !== bm) return am > bm ? 1 : -1;
   if (ap !== bp) return ap > bp ? 1 : -1;
+  // Same numeric version: stable > pre-release (semver spec)
+  if (aPre === null && bPre !== null) return 1;
+  if (aPre !== null && bPre === null) return -1;
+  if (aPre !== null && bPre !== null) return comparePre(aPre, bPre);
   return 0;
 }
 
@@ -323,58 +469,60 @@ export interface UiBuildUpdateResult {
 }
 
 /**
- * Check GitHub for a newer UI build and apply it if one exists.
+ * Check npm for a newer `@openpalm/ui` build and apply it if one exists.
+ *
+ * `@openpalm/ui` is INDEPENDENTLY versioned, so we do NOT compare against the
+ * app/platform version. We pick the dist-tag CHANNEL from the app's release
+ * stream (`appVersion`: prerelease → `next`, stable → `latest`) and compare the
+ * newest UI on that channel against the version actually on disk (the stamp in
+ * the resolved build). This tracks prerelease UIs for prerelease apps and fixes
+ * the `releases/latest`-excludes-prereleases blind spot.
  *
  * When an update is available:
- *   1. Move state/ui/ → state/backups/ui-{timestamp}/ (preserves the old build)
- *   2. Download ui-build.tar.gz from the latest release and extract to state/ui/
+ *   1. Move data/ui/ → data/backups/ui-{timestamp}/ (preserves the old build)
+ *   2. Download the npm bundle (integrity-verified) and extract to data/ui/
  *
  * Non-fatal: any network or extraction error returns { updated: false, error }.
  * The caller should proceed with the existing build on failure.
  */
 export async function checkAndUpdateUiBuild(
-  currentVersion: string,
-  stateDir: string,
+  appVersion: string,
+  dataDir: string,
 ): Promise<UiBuildUpdateResult> {
   try {
-    const res = await fetch(
-      `${GITHUB_API}/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest`,
-      {
-        headers: { 'User-Agent': `OpenPalm/${currentVersion}` },
-        signal: AbortSignal.timeout(10_000),
-      },
-    );
-    if (!res.ok) {
-      return { updated: false, latestVersion: null, error: `GitHub API returned ${res.status}` };
-    }
-
-    const release = await res.json() as {
-      tag_name: string;
-      assets: Array<{ name: string }>;
-    };
-    const latestTag     = release.tag_name;           // e.g. "v0.11.0"
-    const latestVersion = latestTag.replace(/^v/, '');
-
-    if (compareVersionTags(latestTag, currentVersion) <= 0) {
-      logger.debug('UI build is up to date', { current: currentVersion, latest: latestVersion });
+    const channel  = uiUpdateChannel(appVersion);
+    const manifest = await fetchNpmUiManifest(channel);
+    const latestVersion = manifest.version;
+
+    // Compare against the UI build currently on disk, NOT the app version — the
+    // UI floats on its own version line, so the platform/app version is not
+    // comparable. If the build is unstamped (e.g. a legacy data/ui seeded by the
+    // old GitHub-asset path before npm distribution), we cannot compare, so we
+    // refresh once from npm — the npm bundle is stamped, so it self-heals to the
+    // normal compare path on the next launch. Do NOT fall back to appVersion:
+    // comparing two independent version lines silently suppresses real updates.
+    const currentUiVersion = readUiBuildVersion(resolveUiBuildDir());
+
+    if (currentUiVersion && compareVersionTags(latestVersion, currentUiVersion) <= 0) {
+      logger.debug('UI build is up to date', { currentUi: currentUiVersion, latest: latestVersion, channel });
       return { updated: false, latestVersion };
     }
-
-    if (!release.assets.some(a => a.name === 'ui-build.tar.gz')) {
-      return { updated: false, latestVersion, error: 'Latest release has no ui-build.tar.gz' };
+    if (!currentUiVersion) {
+      logger.debug('UI build is unstamped — refreshing from npm to re-establish a known version', { latest: latestVersion, channel });
     }
 
-    // Back up the existing UI build before replacing it
-    const uiDir = join(stateDir, 'ui');
+    // Back up the existing UI build before replacing it. (Automatic rollback on
+    // a failed start is deferred — see ui-distribution-gap-analysis.md G1.)
+    const uiDir = join(dataDir, 'ui');
     if (existsSync(join(uiDir, 'index.js'))) {
-      const backupDir = join(stateDir, 'backups', `ui-${Date.now()}`);
-      mkdirSync(join(stateDir, 'backups'), { recursive: true });
+      const backupDir = join(resolveBackupsDir(), `ui-${Date.now()}`);
+      mkdirSync(resolveBackupsDir(), { recursive: true });
       renameSync(uiDir, backupDir);
       logger.debug('backed up UI build before update', { backup: backupDir });
     }
 
-    await seedUiBuild(latestTag, stateDir);
-    logger.debug('UI build updated', { from: currentVersion, to: latestVersion });
+    await downloadNpmUiBundle(manifest, uiDir, dataDir);
+    logger.debug('UI build updated', { from: currentUiVersion ?? '(unstamped)', to: latestVersion });
 
     return { updated: true, latestVersion };
   } catch (err) {

package/src/control-plane/validate.ts

@@ -2,26 +2,26 @@
  * Runtime configuration validation for the OpenPalm control plane.
  *
  * Validation is a presence check on the canonical env keys we expect in
- * the live config/stack/stack.env file. The
+ * the live config/stack files. The
  * historical schema files and external validation binary were retired in
  * #391; everything advisory is surfaced as a non-blocking warning. The
  * function never shells out and never reads schemas.
  */
 import { existsSync } from "node:fs";
-import { readStackEnv } from "./secrets.js";
+import { readStackRuntimeEnv } from "./secrets.js";
 import { getCoreSecretMappings } from "./secret-mappings.js";
 import type { ControlPlaneState } from "./types.js";
 
 // Stack-scoped env keys that must always exist and carry a non-empty value
 // for the platform to boot. Keep this list small — anything optional
 // belongs in the warning bucket instead.
-const REQUIRED_STACK_KEYS = ["OP_UI_LOGIN_PASSWORD"] as const;
+const REQUIRED_SECRET_KEYS = ["OP_UI_LOGIN_PASSWORD"] as const;
 
 /**
  * Validate the live configuration files.
  *
  * Checks:
- * 1. config/stack/stack.env exists and carries every required key with a
+ * 1. knowledge/env/stack.env exists and carries every required key with a
  *    non-empty value.
  * 2. Every secret env key in getCoreSecretMappings() is present (key only
  *    — blank values are warned about, never erred on, because operators
@@ -38,32 +38,30 @@ export async function validateProposedState(state: ControlPlaneState): Promise<{
   const errors: string[] = [];
   const warnings: string[] = [];
 
-  const stackEnvPath = `${state.stackDir}/stack.env`;
+  const stackEnvPath = `${state.stashDir}/env/stack.env`;
 
   if (!existsSync(stackEnvPath)) {
     errors.push(`ERROR: stack env file missing at ${stackEnvPath}`);
     return { ok: false, errors, warnings };
   }
 
-  const stackEnv = readStackEnv(state.stackDir);
-  const userEnv: Record<string, string> = {};
+  const runtimeEnv = readStackRuntimeEnv(state.stackDir);
 
-  for (const key of REQUIRED_STACK_KEYS) {
-    const value = stackEnv[key];
+  for (const key of REQUIRED_SECRET_KEYS) {
+    const value = runtimeEnv[key];
     if (!value || value.trim().length === 0) {
-      errors.push(`ERROR: required key ${key} is missing or empty in config/stack/stack.env`);
+      errors.push(`ERROR: required secret ${key} is missing or empty in knowledge/secrets/${key.toLowerCase()}`);
     }
   }
 
   // Every canonical secret should at least appear as a key somewhere in
   // the env files so the operator sees the slot. Missing slots warn (not
   // error) since not every provider is in use on every install.
-  for (const mapping of getCoreSecretMappings(stackEnv)) {
-    const inStack = Object.prototype.hasOwnProperty.call(stackEnv, mapping.envKey);
-    const inUser = Object.prototype.hasOwnProperty.call(userEnv, mapping.envKey);
-    if (!inStack && !inUser) {
+  for (const mapping of getCoreSecretMappings(runtimeEnv)) {
+    const inRuntime = Object.prototype.hasOwnProperty.call(runtimeEnv, mapping.envKey);
+    if (!inRuntime) {
       warnings.push(
-        `WARN: ${mapping.envKey} (akm ${mapping.secretKey}) is not declared in config/stack/stack.env`,
+        `WARN: ${mapping.envKey} (akm ${mapping.secretKey}) is not declared in knowledge/secrets/${mapping.envKey.toLowerCase()}`,
       );
     }
   }