@openpalm/lib 0.11.0-rc.2 → 0.11.0-rc.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.11.0-rc.2",
+  "version": "0.11.0-rc.6",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",

package/src/control-plane/registry.ts

@@ -574,14 +574,18 @@ function execFileNoThrow(
 /**
  * Compute the openpalm/voice image ref for a given GPU variant, matching
  * the substitution chain in the addon compose file:
- *   ${OP_IMAGE_NAMESPACE:-openpalm}/voice:${OP_VOICE_IMAGE_TAG:-${OP_IMAGE_TAG:-latest}-<variant>}
+ *   ${OP_IMAGE_NAMESPACE:-openpalm}/voice:${OP_VOICE_IMAGE_TAG:-latest-<variant>}
+ *
+ * Voice images are published OUT OF BAND (publish-voice.yml), decoupled from the
+ * platform OP_IMAGE_TAG — they are heavy and rarely change. So the default is
+ * the moving `latest-<variant>` voice tag; operators pin a specific build by
+ * setting OP_VOICE_IMAGE_TAG (e.g. `v1.0.0-cpu`).
  */
 function voiceImageRef(variant: 'cpu' | 'cu121' | 'rocm6'): string {
   const namespace = process.env.OP_IMAGE_NAMESPACE?.trim() || 'openpalm';
   const explicit = process.env.OP_VOICE_IMAGE_TAG?.trim();
   if (explicit) return `${namespace}/voice:${explicit}`;
-  const baseTag = process.env.OP_IMAGE_TAG?.trim() || 'latest';
-  return `${namespace}/voice:${baseTag}-${variant}`;
+  return `${namespace}/voice:latest-${variant}`;
 }
 
 /**

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

@@ -1,9 +1,14 @@
-import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { describe, it, expect, beforeEach, afterEach, spyOn, mock } from "bun:test";
 import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
-import { resolveUiBuildDir, readUiBuildVersion, UI_VERSION_STAMP, seedOpenPalmDir, SKELETON_VERSION_STAMP } from "./ui-assets.js";
+import { createHash } from "node:crypto";
+import {
+  resolveUiBuildDir, readUiBuildVersion, UI_VERSION_STAMP,
+  seedOpenPalmDir, SKELETON_VERSION_STAMP,
+  uiUpdateChannel, checkAndUpdateUiBuild,
+} from "./ui-assets.js";
 
 let root = "";
 let opHome = "";
@@ -128,3 +133,201 @@ describe("seedOpenPalmDir — version guard (P2)", () => {
     expect(readFileSync(stamp(), "utf-8").trim()).toBe("v2");
   });
 });
+
+// ── uiUpdateChannel ───────────────────────────────────────────────────────────
+
+describe("uiUpdateChannel", () => {
+  it("returns 'latest' for a stable version", () => {
+    expect(uiUpdateChannel("0.11.0")).toBe("latest");
+    expect(uiUpdateChannel("1.0.0")).toBe("latest");
+  });
+
+  it("returns 'next' for a prerelease version (contains '-')", () => {
+    expect(uiUpdateChannel("0.11.0-rc.2")).toBe("next");
+    expect(uiUpdateChannel("0.11.0-beta.5")).toBe("next");
+    expect(uiUpdateChannel("1.0.0-alpha.1")).toBe("next");
+  });
+});
+
+// ── npm integrity verification (via checkAndUpdateUiBuild) ────────────────────
+//
+// We mock globalThis.fetch to avoid real network calls.  The integrity paths
+// are exercised through checkAndUpdateUiBuild → downloadNpmUiBundle (for the
+// missing-integrity and mismatch cases) and through checkAndUpdateUiBuild
+// returning {updated:false} early (for the up-to-date case).
+
+/** Build a correct sha512 SRI string for the given bytes. */
+function makeSri(data: Uint8Array): string {
+  const digest = createHash("sha512").update(data).digest("base64");
+  return `sha512-${digest}`;
+}
+
+describe("npm integrity verification (fail-closed)", () => {
+  let savedFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    savedFetch = globalThis.fetch;
+    // Set forceRemote context: no local build available for these tests.
+    // (data/ui has no index.js, bundledUi dir exists but is empty → no local build)
+  });
+
+  afterEach(() => {
+    globalThis.fetch = savedFetch;
+  });
+
+  it("throws when the manifest has no integrity hash (fail-closed)", async () => {
+    // manifest fetch returns a version with no integrity
+    globalThis.fetch = async (_url: string | URL | Request) => {
+      const url = String(typeof _url === "string" ? _url : (_url as Request).url ?? _url);
+      if (url.includes("registry.npmjs.org")) {
+        return new Response(
+          JSON.stringify({
+            version: "0.11.0",
+            dist: { tarball: "https://registry.npmjs.org/tarball.tgz" },
+            // integrity intentionally omitted
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+      // tarball fetch — should NOT be reached because we throw before it
+      return new Response("not-reached", { status: 200 });
+    };
+
+    const result = await checkAndUpdateUiBuild("0.11.0-beta.1", join(dataUi, ".."));
+    // Missing integrity → non-fatal error path
+    expect(result.updated).toBe(false);
+    expect(result.error).toMatch(/no integrity hash/i);
+  });
+
+  it("throws when the tarball bytes do not match the stated integrity hash", async () => {
+    const fakeData = new Uint8Array([1, 2, 3, 4]);
+    const wrongSri = `sha512-${Buffer.from("wrong").toString("base64")}`;
+
+    globalThis.fetch = async (_url: string | URL | Request) => {
+      const url = String(typeof _url === "string" ? _url : (_url as Request).url ?? _url);
+      if (url.includes("registry.npmjs.org") && !url.includes("tarball")) {
+        return new Response(
+          JSON.stringify({
+            version: "0.99.0",  // newer than anything on disk
+            dist: { tarball: "https://registry.npmjs.org/tarball.tgz", integrity: wrongSri },
+          }),
+          { status: 200, headers: { "Content-Type": "application/json" } }
+        );
+      }
+      // tarball response — bytes deliberately do NOT match wrongSri
+      return new Response(fakeData, { status: 200 });
+    };
+
+    const result = await checkAndUpdateUiBuild("0.11.0", join(dataUi, ".."));
+    expect(result.updated).toBe(false);
+    expect(result.error).toMatch(/integrity mismatch/i);
+  });
+});
+
+// ── checkAndUpdateUiBuild ─────────────────────────────────────────────────────
+
+describe("checkAndUpdateUiBuild", () => {
+  let savedFetch: typeof globalThis.fetch;
+
+  beforeEach(() => {
+    savedFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = savedFetch;
+  });
+
+  /** Make a minimal npm manifest response for a given version. */
+  function manifestResponse(version: string, integrity?: string) {
+    return new Response(
+      JSON.stringify({
+        version,
+        dist: {
+          tarball: "https://registry.npmjs.org/tarball.tgz",
+          ...(integrity !== undefined ? { integrity } : {}),
+        },
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } }
+    );
+  }
+
+  it("returns {updated:false} when the npm channel version is not newer than on-disk stamp", async () => {
+    // Seed data/ui with a stamped build
+    makeBuild(dataUi, "0.11.0");
+
+    globalThis.fetch = async () => manifestResponse("0.11.0"); // same version
+    const result = await checkAndUpdateUiBuild("0.11.0", join(opHome, "data"));
+    expect(result.updated).toBe(false);
+    expect(result.latestVersion).toBe("0.11.0");
+    expect(result.error).toBeUndefined();
+  });
+
+  it("returns {updated:false} when the npm channel version is older than on-disk stamp", async () => {
+    makeBuild(dataUi, "0.12.0");
+
+    globalThis.fetch = async () => manifestResponse("0.11.0"); // older
+    const result = await checkAndUpdateUiBuild("0.12.0", join(opHome, "data"));
+    expect(result.updated).toBe(false);
+    expect(result.latestVersion).toBe("0.11.0");
+  });
+
+  it("returns {updated:false, error} when the manifest fetch rejects (non-fatal)", async () => {
+    globalThis.fetch = async () => { throw new Error("network failure"); };
+
+    const result = await checkAndUpdateUiBuild("0.11.0", join(opHome, "data"));
+    expect(result.updated).toBe(false);
+    expect(result.latestVersion).toBeNull();
+    expect(result.error).toMatch(/network failure/i);
+  });
+
+  it("returns {updated:false, error} when the registry returns a non-OK status", async () => {
+    globalThis.fetch = async () => new Response("not found", { status: 404 });
+
+    const result = await checkAndUpdateUiBuild("0.11.0", join(opHome, "data"));
+    expect(result.updated).toBe(false);
+    expect(result.error).toBeDefined();
+  });
+
+  it("attempts an update when the on-disk build is unstamped (legacy data/ui)", async () => {
+    // Unstamped data/ui — cannot compare, so it should try to refresh from npm.
+    // We give it a manifest with missing integrity so it fails non-fatally
+    // (avoids needing a real tarball), but we confirm it DID attempt the download.
+    makeBuild(dataUi, null); // unstamped
+
+    let manifestFetched = false;
+    globalThis.fetch = async (_url: string | URL | Request) => {
+      const url = String(typeof _url === "string" ? _url : (_url as Request).url ?? _url);
+      if (url.includes("registry.npmjs.org")) {
+        manifestFetched = true;
+        // Return a manifest without integrity so downloadNpmUiBundle throws
+        return manifestResponse("0.11.1");
+      }
+      return new Response("", { status: 200 });
+    };
+
+    const result = await checkAndUpdateUiBuild("0.11.0", join(opHome, "data"));
+    expect(manifestFetched).toBe(true);
+    // non-fatal: missing integrity → error path
+    expect(result.updated).toBe(false);
+    expect(result.error).toBeDefined();
+  });
+
+  it("attempts an update when npm has a newer version than the on-disk stamp", async () => {
+    makeBuild(dataUi, "0.11.0");
+
+    let manifestFetched = false;
+    globalThis.fetch = async (_url: string | URL | Request) => {
+      const url = String(typeof _url === "string" ? _url : (_url as Request).url ?? _url);
+      if (url.includes("registry.npmjs.org")) {
+        manifestFetched = true;
+        return manifestResponse("0.12.0"); // newer — no integrity → non-fatal error
+      }
+      return new Response("", { status: 200 });
+    };
+
+    const result = await checkAndUpdateUiBuild("0.11.0", join(opHome, "data"));
+    expect(manifestFetched).toBe(true);
+    expect(result.updated).toBe(false);
+    expect(result.error).toMatch(/no integrity hash/i);
+  });
+});

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

@@ -4,11 +4,12 @@
  * 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,
@@ -175,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(
@@ -230,7 +231,8 @@ export function readUiBuildVersion(dir: string): string | 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 GitHub releases). To fix
+ * 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:
  *
@@ -264,35 +266,135 @@ export function resolveUiBuildDir(): string {
 }
 
 /**
- * Install the UI build to OP_HOME/data/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.
- *
- * data/ui/ is automatically included in backups because
- * backupOpenPalmHome() copies all of OP_HOME/data/.
+ * 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/, '');
+}
+
+/**
+ * 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 { version: m.version, tarball: m.dist.tarball, integrity: m.dist.integrity ?? 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})`);
+}
+
+/**
+ * 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 });
   }
-  return map;
 }
 
+/**
+ * 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 });
@@ -301,54 +403,23 @@ export async function seedUiBuild(repoRef: string, dataDir: string, options?: {
   if (local) {
     logger.debug('seeding UI build from local source', { src: local });
     copyTree(local, uiDir);
+    // 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(dataDir, '.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 });
-  } 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'. Handles pre-release tags. */
 function compareVersionTags(a: string, b: string): number {
   const parse = (v: string): [number, number, number, string | null] => {
@@ -398,48 +469,50 @@ 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 data/ui/ → data/backups/ui-{timestamp}/ (preserves the old build)
- *   2. Download ui-build.tar.gz from the latest release and extract to data/ui/
+ *   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,
+  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
+    // 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(resolveBackupsDir(), `ui-${Date.now()}`);
@@ -448,8 +521,8 @@ export async function checkAndUpdateUiBuild(
       logger.debug('backed up UI build before update', { backup: backupDir });
     }
 
-    await seedUiBuild(latestTag, dataDir);
-    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/index.ts

@@ -380,4 +380,5 @@ export {
   resolveUiBuildDir,
   seedUiBuild,
   checkAndUpdateUiBuild,
+  uiUpdateChannel,
 } from "./control-plane/ui-assets.js";