@openpalm/lib 0.11.0-beta.1 → 0.11.0-beta.11

package/src/control-plane/setup.ts

@@ -7,7 +7,6 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
 import { join } from "node:path";
-import { randomBytes } from "node:crypto";
 import { createLogger } from "../logger.js";
 import {
   PROVIDER_KEY_MAP,
@@ -18,12 +17,11 @@ import { acquireInstallLock, releaseInstallLock, type InstallLockHandle } from "
 import {
   ensureSecrets,
   updateSecretsEnv,
-  updateSystemSecretsEnv,
+  patchSecretsEnvFile,
   ensureOpenCodeConfig,
   readStackEnv,
   writeAuthJsonProviderKeys,
 } from "./secrets.js";
-import { ensureOpenCodeSystemConfig } from "./core-assets.js";
 import { createState } from "./lifecycle.js";
 import { writeStackSpec } from "./stack-spec.js";
 import { writeVoiceVars } from "./spec-to-env.js";
@@ -70,7 +68,12 @@ export type SetupSpec = {
   embedding?: { provider: string; model: string; dims: number; baseUrl?: string };
   tts?: { enabled?: boolean; engine?: string; provider?: string; baseURL?: string; model?: string; voice?: string };
   stt?: { enabled?: boolean; engine?: string; provider?: string; baseURL?: string; model?: string; language?: string };
-  security: { adminToken: string };
+  /**
+   * Operator-supplied UI login password. Persisted to stack.env as
+   * `OP_UI_LOGIN_PASSWORD`. Replaces the legacy `adminToken` field
+   * (Phase 4 of docs/technical/auth-and-proxy-refactor-plan.md).
+   */
+  security: { uiLoginPassword: string };
   owner?: { name?: string; email?: string };
   connections: SetupConnection[];
   channelCredentials?: Record<string, Record<string, string>>;
@@ -94,8 +97,8 @@ export function buildSecretsFromSetup(
   const updates: Record<string, string> = {};
   const ownerName = (owner?.name?.trim() ?? "").replace(/[\r\n\0]/g, "").slice(0, 200);
   const ownerEmail = (owner?.email?.trim() ?? "").replace(/[\r\n\0]/g, "").slice(0, 200);
-  if (ownerName) updates.OWNER_NAME = ownerName;
-  if (ownerEmail) updates.OWNER_EMAIL = ownerEmail;
+  if (ownerName) updates.OP_OWNER_NAME = ownerName;
+  if (ownerEmail) updates.OP_OWNER_EMAIL = ownerEmail;
   void connections;
   return updates;
 }
@@ -121,41 +124,26 @@ export function buildAuthJsonFromSetup(
 }
 
 /**
- * Build the system-secret env update.
+ * Build the system-secret env update for the wizard / CLI install path.
  *
- * `OP_ASSISTANT_TOKEN` is critical: rotating it on a running stack would
- * invalidate every container's auth. We therefore distinguish three cases:
- *  - existing system env has a non-empty token → reuse it (idempotent rerun).
- *  - existing system env explicitly contains `OP_ASSISTANT_TOKEN=` (blank)  →
- *    throw rather than silently rotate. This means a user edited stack.env
- *    or a previous run wrote it blank; either way silent rotation breaks the
- *    running stack.
- *  - the key is absent entirely → generate a fresh token (first install).
+ * Phase 4 of the auth/proxy refactor collapsed the legacy
+ * `OP_UI_TOKEN` / `OP_ASSISTANT_TOKEN` pair into a single operator login
+ * secret (`OP_UI_LOGIN_PASSWORD`). The browser stores the cookie value =
+ * password; `requireAdmin()` compares the cookie against
+ * `process.env.OP_UI_LOGIN_PASSWORD` via the existing `safeTokenCompare`.
  *
- * If you legitimately need to rotate the token, delete the OP_ASSISTANT_TOKEN
- * line from stack.env (rather than blanking it) before re-running setup.
+ * `OP_OPENCODE_PASSWORD` is generated by `ensureSystemSecrets()` on first
+ * run and persists across reruns — it is not regenerated here.
+ *
+ * `existingSystemEnv` is unused now but the parameter is kept so callers
+ * compile unchanged. It can be removed in a follow-up cleanup.
  */
 export function buildSystemSecretsFromSetup(
-  adminToken: string,
-  existingSystemEnv: Record<string, string> = {}
+  uiLoginPassword: string,
+  _existingSystemEnv: Record<string, string> = {}
 ): Record<string, string> {
-  const hasKey = Object.prototype.hasOwnProperty.call(existingSystemEnv, "OP_ASSISTANT_TOKEN");
-  const existing = existingSystemEnv.OP_ASSISTANT_TOKEN;
-  let token: string;
-  if (existing) {
-    token = existing;
-  } else if (hasKey) {
-    throw new Error(
-      "OP_ASSISTANT_TOKEN is present but blank in config/stack/stack.env. " +
-      "Refusing to silently rotate the token (it would break the running stack). " +
-      "Restore the previous value or remove the line entirely to generate a fresh one.",
-    );
-  } else {
-    token = randomBytes(32).toString("hex");
-  }
   return {
-    OP_UI_TOKEN: adminToken,
-    OP_ASSISTANT_TOKEN: token,
+    OP_UI_LOGIN_PASSWORD: uiLoginPassword,
   };
 }
 
@@ -205,7 +193,7 @@ export async function performSetup(
   if (!validation.valid) return { ok: false, error: validation.errors.join("; ") };
 
   const { llm, embedding, tts, stt, security, owner, connections, channelCredentials, addons, imageTag, hostAkm } = input;
-  const state = opts?.state ?? createState(security.adminToken);
+  const state = opts?.state ?? createState();
 
   // Acquire install lock to prevent two concurrent setup runs from racing on
   // the same config directory. The lock lives in stateDir so it is co-located
@@ -238,7 +226,7 @@ export async function performSetup(
         }
       }
       updateSecretsEnv(state, updates);
-      updateSystemSecretsEnv(state, buildSystemSecretsFromSetup(security.adminToken, existingSystemEnv));
+      patchSecretsEnvFile(state.stackDir, buildSystemSecretsFromSetup(security.uiLoginPassword, existingSystemEnv));
       // Provider API keys land in OpenCode's auth.json (bind-mounted into
       // the assistant container) — never in stack.env.
       writeAuthJsonProviderKeys(state, providerKeys);
@@ -248,9 +236,6 @@ export async function performSetup(
       return { ok: false, error: `Failed to persist setup outputs: ${message}` };
     }
 
-    state.adminToken = security.adminToken;
-    state.assistantToken = readStackEnv(state.stackDir).OP_ASSISTANT_TOKEN ?? state.assistantToken;
-
     // Everything from here through the OP_SETUP_COMPLETE write is wrapped in a
     // single try/catch so that a disk-full or permission-denied mid-way returns a
     // clean error rather than leaving a broken half-installed ~/.openpalm/.
@@ -325,7 +310,6 @@ export async function performSetup(
       }
 
       ensureOpenCodeConfig();
-      ensureOpenCodeSystemConfig();
 
       // Seed default automation into the AKM stash. Idempotent — existing files
       // are left alone so user edits survive re-install and upgrade.

package/src/control-plane/spec-to-env.test.ts

@@ -1,11 +1,9 @@
 import { describe, test, expect, beforeEach, afterEach } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { deriveSystemEnvFromSpec, writeVoiceVars } from "./spec-to-env.js";
 
-const MINIMAL_SPEC = { version: 2 as const };
-
 let tempDir = "";
 
 beforeEach(() => {
@@ -18,33 +16,49 @@ afterEach(() => {
 
 describe("deriveSystemEnvFromSpec", () => {
   test("produces OP_HOME", () => {
-    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    const result = deriveSystemEnvFromSpec("/home/op");
     expect(result.OP_HOME).toBe("/home/op");
   });
 
   test("produces default port values", () => {
-    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    const result = deriveSystemEnvFromSpec("/home/op");
     expect(result.OP_ASSISTANT_PORT).toBe("3800");
-    expect(result.OP_GUARDIAN_PORT).toBe("3899");
+  });
+
+  test("does not emit OP_GUARDIAN_PORT (guardian is network-only, no host mapping)", () => {
+    const result = deriveSystemEnvFromSpec("/home/op");
+    expect(result.OP_GUARDIAN_PORT).toBeUndefined();
   });
 
   test("does not include the retired memory service port", () => {
-    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    const result = deriveSystemEnvFromSpec("/home/op");
     const retired = "OP_" + "MEMORY_PORT";
     expect(result[retired]).toBeUndefined();
   });
 
   test("does not include LLM provider in system env", () => {
-    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    const result = deriveSystemEnvFromSpec("/home/op");
     expect(result.SYSTEM_LLM_PROVIDER).toBeUndefined();
     expect(result.SYSTEM_LLM_MODEL).toBeUndefined();
   });
 
   test("does not include removed feature flags", () => {
-    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    const result = deriveSystemEnvFromSpec("/home/op");
     expect(result.OP_OLLAMA_ENABLED).toBeUndefined();
     expect(result.OP_ADMIN_ENABLED).toBeUndefined();
   });
+
+  test("auto-detects OP_UID/OP_GID from the homeDir owner (not hard-coded 1000)", () => {
+    // tempDir is owned by the test process, which on a CI runner or
+    // dev box is typically NOT root and NOT necessarily UID 1000. The
+    // assertion that matters: we read the value off statSync, not a
+    // hard-coded constant.
+    if (process.platform === "win32") return;
+    const expected = statSync(tempDir);
+    const result = deriveSystemEnvFromSpec(tempDir);
+    expect(result.OP_UID).toBe(String(expected.uid));
+    expect(result.OP_GID).toBe(String(expected.gid));
+  });
 });
 
 describe("writeVoiceVars", () => {
@@ -57,9 +71,9 @@ describe("writeVoiceVars", () => {
     }, tempDir);
 
     const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
-    expect(content).toContain("TTS_BASE_URL=https://tts.example.com/v1");
-    expect(content).toContain("TTS_MODEL=tts-1");
-    expect(content).toContain("TTS_VOICE=alloy");
+    expect(content).toContain("OP_TTS_BASE_URL=https://tts.example.com/v1");
+    expect(content).toContain("OP_TTS_MODEL=tts-1");
+    expect(content).toContain("OP_TTS_VOICE=alloy");
   });
 
   test("writes STT vars to stack.env", () => {
@@ -71,9 +85,9 @@ describe("writeVoiceVars", () => {
     }, tempDir);
 
     const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
-    expect(content).toContain("STT_BASE_URL=https://stt.example.com/v1");
-    expect(content).toContain("STT_MODEL=whisper-1");
-    expect(content).toContain("STT_LANGUAGE=en");
+    expect(content).toContain("OP_STT_BASE_URL=https://stt.example.com/v1");
+    expect(content).toContain("OP_STT_MODEL=whisper-1");
+    expect(content).toContain("OP_STT_LANGUAGE=en");
   });
 
   test("creates stack.env if it does not exist", () => {
@@ -84,7 +98,7 @@ describe("writeVoiceVars", () => {
     }, tempDir);
 
     const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
-    expect(content).toContain("TTS_BASE_URL=https://tts.example.com/v1");
+    expect(content).toContain("OP_TTS_BASE_URL=https://tts.example.com/v1");
   });
 
   test("is a no-op when no vars are provided", () => {

package/src/control-plane/spec-to-env.ts

@@ -5,22 +5,16 @@
  * Voice channel vars (TTS/STT) are written separately via writeVoiceVars.
  */
 
-import type { StackSpec } from "./stack-spec.js";
 import { SPEC_DEFAULTS } from "./stack-spec.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { mergeEnvContent } from "./env.js";
+import { resolveOperatorIds } from "./operator-ids.js";
 
 /**
  * Derive the system.env key-value pairs from the StackSpec.
  * Secrets (tokens, API keys, HMAC) are NOT included — the caller merges them.
  */
-export function deriveSystemEnvFromSpec(
-  spec: StackSpec,
-  homeDir: string,
-): Record<string, string> {
-  const uid = typeof process.getuid === "function" ? (process.getuid() ?? 1000) : 1000;
-  const gid = typeof process.getgid === "function" ? (process.getgid() ?? 1000) : 1000;
-
+export function deriveSystemEnvFromSpec(homeDir: string): Record<string, string> {
   const ports = SPEC_DEFAULTS.ports;
   const image = SPEC_DEFAULTS.image;
 
@@ -28,21 +22,27 @@ export function deriveSystemEnvFromSpec(
 
   // Paths
   result["OP_HOME"] = homeDir;
-  result["OP_UID"] = String(uid);
-  result["OP_GID"] = String(gid);
+
+  // Operator UID/GID — auto-detect from OP_HOME owner (or process UID
+  // as fallback). Skipped on Windows where containers run in WSL2 and
+  // OP_UID has no meaning on the host process.
+  const ids = resolveOperatorIds(homeDir);
+  if (ids) {
+    result["OP_UID"] = String(ids.uid);
+    result["OP_GID"] = String(ids.gid);
+  }
   // Image
   result["OP_IMAGE_NAMESPACE"] = image.namespace;
   result["OP_IMAGE_TAG"] = image.tag;
 
-  // Ports
+  // Ports — only the services that publish to the host. Guardian is
+  // network-only (no host port mapping) so OP_GUARDIAN_PORT is no longer
+  // emitted; channels reach it via Docker DNS at http://guardian:8080.
   result["OP_ASSISTANT_PORT"] = String(ports.assistant);
   result["OP_ADMIN_PORT"] = String(ports.admin);
   result["OP_ADMIN_OPENCODE_PORT"] = String(ports.adminOpencode);
-  result["OP_GUARDIAN_PORT"] = String(ports.guardian);
   result["OP_ASSISTANT_SSH_PORT"] = String(ports.assistantSsh);
 
-  void spec; // spec reserved for future use; ports/image come from SPEC_DEFAULTS
-
   return result;
 }
 
@@ -51,12 +51,18 @@ export function deriveSystemEnvFromSpec(
 export type VoiceVarsConfig = {
   tts?: {
     enabled?: boolean;
+    /** Engine name (e.g. "kokoro", "elevenlabs", "browser"). */
+    engine?: string;
+    /** Optional sub-provider qualifier when an engine fronts multiple providers. */
+    provider?: string;
     baseURL?: string;
     model?: string;
     voice?: string;
   };
   stt?: {
     enabled?: boolean;
+    engine?: string;
+    provider?: string;
     baseURL?: string;
     model?: string;
     language?: string;
@@ -65,23 +71,33 @@ export type VoiceVarsConfig = {
 
 /**
  * Write TTS/STT env vars to stack.env for the voice channel container.
- * Only vars with non-empty values are written; missing values are left unchanged.
+ * `engine` always writes (even if it's the only field) so picking an
+ * engine without filling in URL/model still persists.
  */
 export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void {
   const stackEnvPath = `${stackDir}/stack.env`;
   const base = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
   const vars: Record<string, string> = {};
 
+  // OP_ prefix is mandatory: unprefixed TTS_*/STT_* names collide with
+  // other tooling (OpenAI clients, kokoro-fastapi, etc.) commonly set in
+  // operator shells. The UI server only reads OP_-prefixed vars from
+  // process.env, so a leaked host TTS_VOICE can't silently override the
+  // saved selection.
   const { tts, stt } = config;
   if (tts?.enabled !== false) {
-    if (tts?.baseURL) vars["TTS_BASE_URL"] = tts.baseURL;
-    if (tts?.model) vars["TTS_MODEL"] = tts.model;
-    if (tts?.voice) vars["TTS_VOICE"] = tts.voice;
+    if (tts?.engine) vars["OP_TTS_ENGINE"] = tts.engine;
+    if (tts?.provider) vars["OP_TTS_PROVIDER"] = tts.provider;
+    if (tts?.baseURL) vars["OP_TTS_BASE_URL"] = tts.baseURL;
+    if (tts?.model) vars["OP_TTS_MODEL"] = tts.model;
+    if (tts?.voice) vars["OP_TTS_VOICE"] = tts.voice;
   }
   if (stt?.enabled !== false) {
-    if (stt?.baseURL) vars["STT_BASE_URL"] = stt.baseURL;
-    if (stt?.model) vars["STT_MODEL"] = stt.model;
-    if (stt?.language) vars["STT_LANGUAGE"] = stt.language;
+    if (stt?.engine) vars["OP_STT_ENGINE"] = stt.engine;
+    if (stt?.provider) vars["OP_STT_PROVIDER"] = stt.provider;
+    if (stt?.baseURL) vars["OP_STT_BASE_URL"] = stt.baseURL;
+    if (stt?.model) vars["OP_STT_MODEL"] = stt.model;
+    if (stt?.language) vars["OP_STT_LANGUAGE"] = stt.language;
   }
 
   if (Object.keys(vars).length === 0) return;

package/src/control-plane/stack-spec.test.ts

@@ -11,7 +11,6 @@ import {
   readStackSpec,
   writeStackSpec,
   STACK_SPEC_FILENAME,
-  stackSpecPath,
 } from "./stack-spec.js";
 import type { StackSpec } from "./stack-spec.js";
 
@@ -40,9 +39,8 @@ describe("readStackSpec / writeStackSpec round-trip", () => {
   it("writes to the canonical filename", () => {
     writeStackSpec(configDir, MINIMAL_SPEC);
     const expectedPath = join(configDir, STACK_SPEC_FILENAME);
-    const read = readStackSpec(configDir);
-    expect(read).not.toBeNull();
-    expect(stackSpecPath(configDir)).toBe(expectedPath);
+    expect(expectedPath).toBe(join(configDir, "stack.yml"));
+    expect(readStackSpec(configDir)).not.toBeNull();
   });
 
   it("ignores legacy capabilities fields on read", () => {
@@ -81,14 +79,10 @@ describe("readStackSpec edge cases", () => {
   });
 });
 
-// ── stackSpecPath / STACK_SPEC_FILENAME ──────────────────────────────────
-
-describe("stackSpecPath", () => {
-  it("returns stackDir/stack.yml", () => {
-    expect(stackSpecPath("/foo/config/stack")).toBe("/foo/config/stack/stack.yml");
-  });
+// ── STACK_SPEC_FILENAME ───────────────────────────────────────────────────
 
-  it("uses STACK_SPEC_FILENAME constant", () => {
+describe("STACK_SPEC_FILENAME", () => {
+  it("is stack.yml", () => {
     expect(STACK_SPEC_FILENAME).toBe("stack.yml");
   });
 });

package/src/control-plane/stack-spec.ts

@@ -36,14 +36,10 @@ export const SPEC_DEFAULTS = {
 
 // ── Read / Write ────────────────────────────────────────────────────────
 
-export function stackSpecPath(configDir: string): string {
-  return `${configDir}/${STACK_SPEC_FILENAME}`;
-}
-
 export function writeStackSpec(configDir: string, spec: StackSpec): void {
   mkdirSync(configDir, { recursive: true });
   const content = yamlStringify(spec, { indent: 2 });
-  writeFileSync(stackSpecPath(configDir), content);
+  writeFileSync(`${configDir}/${STACK_SPEC_FILENAME}`, content);
 }
 
 /**
@@ -51,7 +47,7 @@ export function writeStackSpec(configDir: string, spec: StackSpec): void {
  * Only the version field is checked; legacy capability fields are ignored.
  */
 export function readStackSpec(configDir: string): StackSpec | null {
-  const path = stackSpecPath(configDir);
+  const path = `${configDir}/${STACK_SPEC_FILENAME}`;
   if (!existsSync(path)) return null;
 
   let raw: unknown;

package/src/control-plane/types.ts

@@ -8,15 +8,8 @@ export type CoreServiceName =
   | "assistant"
   | "guardian";
 
-export type OptionalServiceName = never;
-
 export type AccessScope = "host" | "lan";
 export type CallerType = "assistant" | "cli" | "ui" | "system" | "test" | "unknown";
-export type AuditContext = {
-  actor: string;
-  requestId?: string;
-  callerType?: CallerType;
-};
 
 /** Info about a discovered channel */
 export type ChannelInfo = {
@@ -24,16 +17,6 @@ export type ChannelInfo = {
   ymlPath: string;
 };
 
-export type AuditEntry = {
-  at: string;
-  requestId: string;
-  actor: string;
-  callerType: CallerType;
-  action: string;
-  args: Record<string, unknown>;
-  ok: boolean;
-};
-
 export type ArtifactMeta = {
   name: string;
   sha256: string;
@@ -42,8 +25,6 @@ export type ArtifactMeta = {
 };
 
 export type ControlPlaneState = {
-  adminToken: string;
-  assistantToken: string;
   homeDir: string;
   configDir: string;
   stashDir: string;      // homeDir/stash
@@ -56,7 +37,6 @@ export type ControlPlaneState = {
     compose: string;
   };
   artifactMeta: ArtifactMeta[];
-  audit: AuditEntry[];
 };
 
 // ── Constants ──────────────────────────────────────────────────────────
@@ -69,5 +49,3 @@ export const CORE_SERVICES: CoreServiceName[] = [
   "guardian",
 ];
 
-export const OPTIONAL_SERVICES: OptionalServiceName[] = [];
-

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

@@ -12,7 +12,7 @@
  */
 import {
   existsSync, mkdirSync, readdirSync, copyFileSync,
-  writeFileSync, rmSync, realpathSync, renameSync,
+  readFileSync, writeFileSync, rmSync, realpathSync, renameSync,
 } from 'node:fs';
 import { join, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -156,7 +156,13 @@ export function resolveLocalUiBuild(): string | null {
     () => process.env.OPENPALM_REPO_ROOT
       ? join(process.env.OPENPALM_REPO_ROOT, 'packages', 'ui', 'build')
       : null,
-    // 2. Relative to this source file (dev / bun run)
+    // 2. Electron extraResources — ui-build/ is placed alongside the asar
+    () => {
+      const rp = (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath;
+      if (!rp) return null;
+      return join(rp, 'ui-build');
+    },
+    // 3. Relative to this source file (dev / bun run)
     () => {
       const meta = fileURLToPath(import.meta.url);
       if (meta.startsWith('/$bunfs/')) return null;
@@ -164,7 +170,7 @@ export function resolveLocalUiBuild(): string | null {
       const candidate = join(dirname(meta), '..', '..', '..', '..', 'packages', 'ui', 'build');
       return existsSync(join(candidate, 'index.js')) ? candidate : null;
     },
-    // 3. Relative to compiled binary / Electron executable
+    // 4. Relative to compiled binary / Electron executable
     () => {
       const binDir = dirname(realpathSync(process.execPath));
       const candidate = join(binDir, '..', '..', '..', 'packages', 'ui', 'build');
@@ -173,17 +179,36 @@ 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/ — installed by seedUiBuild (production)
- *   2. Local packages/ui/build/ — dev / source install fallback
+ *   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
+ *
+ * This means GitHub-downloaded updates are applied automatically (disk wins
+ * when newer), but a fresh AppImage install always works without a download.
  */
 export function resolveUiBuildDir(): string {
   const stateBuild = join(resolveStateDir(), 'ui');
-  if (existsSync(join(stateBuild, 'index.js'))) return stateBuild;
-  return resolveLocalUiBuild() ?? stateBuild; // fall back even if missing (error surfaces later)
+  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;
+  }
+
+  if (localBuild) return localBuild;
+  return stateBuild;
 }
 
 /**
@@ -216,14 +241,21 @@ function parseChecksumsFile(content: string): Map<string, string> {
   return map;
 }
 
-export async function seedUiBuild(repoRef: string, stateDir: string): Promise<void> {
+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;
+}
+
+export async function seedUiBuild(repoRef: string, stateDir: string, options?: { forceRemote?: boolean }): Promise<void> {
   const uiDir = join(stateDir, 'ui');
   mkdirSync(uiDir, { recursive: true });
 
-  const local = resolveLocalUiBuild();
+  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/, ''));
     return;
   }
 
@@ -258,8 +290,12 @@ export async function seedUiBuild(repoRef: string, stateDir: string): Promise<vo
 
     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 });
   }

package/src/control-plane/validate.ts

@@ -15,7 +15,7 @@ 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_TOKEN", "OP_ASSISTANT_TOKEN"] as const;
+const REQUIRED_STACK_KEYS = ["OP_UI_LOGIN_PASSWORD"] as const;
 
 /**
  * Validate the live configuration files.