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

package/src/control-plane/host-opencode.test.ts

@@ -14,8 +14,6 @@ import type { ControlPlaneState } from "./types.js";
 
 function makeState(homeDir: string): ControlPlaneState {
   return {
-    adminToken: "test-admin",
-    assistantToken: "test-assistant",
     homeDir,
     configDir: join(homeDir, "config"),
     stashDir: join(homeDir, "stash"),
@@ -26,7 +24,6 @@ function makeState(homeDir: string): ControlPlaneState {
     services: {},
     artifacts: { compose: "" },
     artifactMeta: [],
-    audit: [],
   };
 }
 

package/src/control-plane/install-edge-cases.test.ts

@@ -36,7 +36,7 @@ function makeValidSpec(overrides?: Partial<SetupSpec>): SetupSpec {
     version: 2,
     llm: { provider: "openai", model: "gpt-4o", baseUrl: "https://api.openai.com/v1" },
     embedding: { provider: "openai", model: "text-embedding-3-small", dims: 1536, baseUrl: "https://api.openai.com/v1" },
-    security: { adminToken: "test-admin-token-12345" },
+    security: { uiLoginPassword: "test-admin-token-12345" },
     owner: { name: "Test User", email: "test@example.com" },
     connections: [
       {
@@ -135,16 +135,15 @@ function seedMinimalEnvFiles(): void {
     join(stackDir, "stack.env"),
     [
       "# OpenPalm — Stack Configuration",
-      "OP_UI_TOKEN=",
-      "OP_ASSISTANT_TOKEN=",
+      "OP_UI_LOGIN_PASSWORD=",
       "OPENAI_API_KEY=",
       "OPENAI_BASE_URL=",
       "ANTHROPIC_API_KEY=",
       "GROQ_API_KEY=",
       "MISTRAL_API_KEY=",
       "GOOGLE_API_KEY=",
-      "OWNER_NAME=",
-      "OWNER_EMAIL=",
+      "OP_OWNER_NAME=",
+      "OP_OWNER_EMAIL=",
       "",
     ].join("\n")
   );
@@ -171,8 +170,6 @@ describe("Fresh Install", () => {
   // does create stack.env with required keys when files do not exist.
   it("ensureSecrets creates state/stack.env with required keys on fresh install", () => {
     const state: ControlPlaneState = {
-      adminToken: "",
-      assistantToken: "",
       homeDir,
       configDir,
       stashDir: join(homeDir, "stash"),
@@ -183,7 +180,6 @@ describe("Fresh Install", () => {
       services: {},
       artifacts: { compose: "" },
       artifactMeta: [],
-      audit: [],
     };
 
     ensureSecrets(state);
@@ -191,7 +187,7 @@ describe("Fresh Install", () => {
     // API keys and owner info are seeded in state/stack.env.
     const stackContent = readFileSync(join(stackDir, "stack.env"), "utf-8");
     expect(stackContent).toContain("OPENAI_API_KEY=");
-    expect(stackContent).toContain("OWNER_NAME=");
+    expect(stackContent).toContain("OP_OWNER_NAME=");
   });
 
   // Scenario 2: isSetupComplete returns false before setup
@@ -253,11 +249,9 @@ describe("Existing Install", () => {
   // Scenario 5: ensureSecrets does NOT overwrite existing stack.env
   it("ensureSecrets does not overwrite existing stack.env tokens", () => {
     mkdirSync(stateDir, { recursive: true });
-    writeFileSync(join(stackDir, "stack.env"), "OP_UI_TOKEN=my-custom-token\nOP_ASSISTANT_TOKEN=existing-token\n");
+    writeFileSync(join(stackDir, "stack.env"), "OP_UI_LOGIN_PASSWORD=my-custom-password\n");
 
     const state: ControlPlaneState = {
-      adminToken: "",
-      assistantToken: "",
       homeDir,
       configDir,
       stashDir: join(homeDir, "stash"),
@@ -268,57 +262,29 @@ describe("Existing Install", () => {
       services: {},
       artifacts: { compose: "" },
       artifactMeta: [],
-      audit: [],
     };
 
     ensureSecrets(state);
 
-    // Existing tokens must be preserved
+    // Existing password must be preserved
     const afterContent = readFileSync(join(stackDir, "stack.env"), "utf-8");
-    expect(afterContent).toContain("OP_UI_TOKEN=my-custom-token");
-    expect(afterContent).toContain("OP_ASSISTANT_TOKEN=existing-token");
+    expect(afterContent).toContain("OP_UI_LOGIN_PASSWORD=my-custom-password");
   });
 
-  // Scenario 6: performSetup re-run preserves OP_ASSISTANT_TOKEN
-  it("performSetup re-run preserves OP_ASSISTANT_TOKEN from first run", async () => {
-    // First setup
-    await performSetup(makeValidSpec());
+  // Scenario 6: performSetup re-run rewrites OP_UI_LOGIN_PASSWORD when the
+  // operator supplies a new one in the spec. This is intentional — the
+  // wizard "rerun" path is how an operator rotates the password. The
+  // legacy OP_ASSISTANT_TOKEN preservation test was removed with the token.
+  it("performSetup re-run rewrites OP_UI_LOGIN_PASSWORD when spec changes", async () => {
+    await performSetup(makeValidSpec({ security: { uiLoginPassword: "first-password-12345" } }));
 
-    const secretsAfterFirst = readFileSync(
-      join(stackDir, "stack.env"),
-      "utf-8"
-    );
-    const firstMatch = secretsAfterFirst.match(
-      /OP_ASSISTANT_TOKEN=([a-f0-9]+)/
-    );
-    expect(firstMatch).not.toBeNull();
-    const firstToken = firstMatch![1];
+    const afterFirst = readFileSync(join(stackDir, "stack.env"), "utf-8");
+    expect(afterFirst).toContain("OP_UI_LOGIN_PASSWORD=first-password-12345");
 
-    // Second setup (re-run with different API key)
-    await performSetup(
-      makeValidSpec({
-        connections: [
-          {
-            id: "openai-main",
-            name: "OpenAI",
-            provider: "openai",
-            baseUrl: "https://api.openai.com",
-            apiKey: "sk-different-key-999",
-          },
-        ],
-      })
-    );
+    await performSetup(makeValidSpec({ security: { uiLoginPassword: "second-password-12345" } }));
 
-    const secretsAfterSecond = readFileSync(
-      join(stackDir, "stack.env"),
-      "utf-8"
-    );
-    const secondMatch = secretsAfterSecond.match(
-      /OP_ASSISTANT_TOKEN=([a-f0-9]+)/
-    );
-    expect(secondMatch).not.toBeNull();
-    // OP_ASSISTANT_TOKEN should be preserved across setups
-    expect(secondMatch![1]).toBe(firstToken);
+    const afterSecond = readFileSync(join(stackDir, "stack.env"), "utf-8");
+    expect(afterSecond).toContain("OP_UI_LOGIN_PASSWORD=second-password-12345");
   });
 
   // Scenario 7: performSetup must NOT mark OP_SETUP_COMPLETE — see scenario
@@ -386,11 +352,9 @@ describe("Broken/Corrupt State", () => {
   // Scenario 9: ensureSecrets is idempotent on repeated calls
   it("ensureSecrets is idempotent — second call does not overwrite existing stack.env", () => {
     mkdirSync(stateDir, { recursive: true });
-    writeFileSync(join(stackDir, "stack.env"), "OP_UI_TOKEN=existing-token\nOP_ASSISTANT_TOKEN=existing-assistant\n");
+    writeFileSync(join(stackDir, "stack.env"), "OP_UI_LOGIN_PASSWORD=existing-password\n");
 
     const state: ControlPlaneState = {
-      adminToken: "",
-      assistantToken: "",
       homeDir,
       configDir,
       stashDir: join(homeDir, "stash"),
@@ -401,15 +365,13 @@ describe("Broken/Corrupt State", () => {
       services: {},
       artifacts: { compose: "" },
       artifactMeta: [],
-      audit: [],
     };
 
     ensureSecrets(state);
 
-    // Existing tokens must be preserved
+    // Existing password must be preserved
     const content = readFileSync(join(stackDir, "stack.env"), "utf-8");
-    expect(content).toContain("OP_UI_TOKEN=existing-token");
-    expect(content).toContain("OP_ASSISTANT_TOKEN=existing-assistant");
+    expect(content).toContain("OP_UI_LOGIN_PASSWORD=existing-password");
   });
 
   // Scenario 10: env file with malformed lines
@@ -447,11 +409,11 @@ describe("Broken/Corrupt State", () => {
     expect(isSetupComplete(stackDir)).toBe(false);
   });
 
-  it("isSetupComplete falls back to true when admin token is set but OP_SETUP_COMPLETE missing", () => {
+  it("isSetupComplete falls back to true when UI login password is set but OP_SETUP_COMPLETE missing", () => {
     mkdirSync(stateDir, { recursive: true });
     writeFileSync(
       join(stackDir, "stack.env"),
-      "OP_IMAGE_TAG=latest\nexport OP_UI_TOKEN=my-real-token\n"
+      "OP_IMAGE_TAG=latest\nexport OP_UI_LOGIN_PASSWORD=my-real-password\n"
     );
 
     expect(isSetupComplete(stackDir)).toBe(true);
@@ -527,12 +489,12 @@ describe("Environment Edge Cases", () => {
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  // Scenario 16: Commented-out ADMIN_TOKEN but OP_UI_TOKEN set
-  it("isSetupComplete detects OP_UI_TOKEN when ADMIN_TOKEN is commented out", () => {
+  // Scenario 16: isSetupComplete picks up OP_UI_LOGIN_PASSWORD when set
+  it("isSetupComplete detects OP_UI_LOGIN_PASSWORD", () => {
     mkdirSync(stateDir, { recursive: true });
     writeFileSync(
       join(stackDir, "stack.env"),
-      "SOME_OTHER_KEY=value\nexport OP_UI_TOKEN=real-token-here\n"
+      "SOME_OTHER_KEY=value\nexport OP_UI_LOGIN_PASSWORD=real-password-here\n"
     );
 
     expect(isSetupComplete(stackDir)).toBe(true);
@@ -705,13 +667,11 @@ describe("performSetup end-to-end artifacts", () => {
     ).toBe(true);
   });
 
-  it("writes admin and assistant tokens to stack.env", async () => {
+  it("writes the UI login password to stack.env", async () => {
     await performSetup(makeValidSpec());
 
     const secrets = parseEnvFile(join(stackDir, "stack.env"));
-    expect(secrets.OP_UI_TOKEN).toBe("test-admin-token-12345");
-    expect(typeof secrets.OP_ASSISTANT_TOKEN).toBe("string");
-    expect(secrets.OP_ASSISTANT_TOKEN).not.toBe("test-admin-token-12345");
+    expect(secrets.OP_UI_LOGIN_PASSWORD).toBe("test-admin-token-12345");
   });
 
   it("writes akm config with llm provider and model", async () => {

package/src/control-plane/lifecycle.ts

@@ -1,7 +1,7 @@
 /** Lifecycle helpers — state factory, apply transitions, compose file list. */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { parseEnvFile, mergeEnvContent } from "./env.js";
-import type { ControlPlaneState, CallerType, AuditContext } from "./types.js";
+import type { ControlPlaneState, CallerType } from "./types.js";
 import { CORE_SERVICES } from "./types.js";
 import {
   resolveOpenPalmHome,
@@ -12,7 +12,7 @@ import {
   resolveStateDir,
   resolveStackDir,
 } from "./home.js";
-import { ensureSecrets, readStackEnv, updateSystemSecretsEnv } from "./secrets.js";
+import { ensureSecrets } from "./secrets.js";
 import {
   resolveRuntimeFiles,
   writeRuntimeFiles,
@@ -20,22 +20,18 @@ import {
   discoverStackOverlays,
   ensureComposeVolumeTargets,
 } from "./config-persistence.js";
-import { readStackSpec } from "./stack-spec.js";
 import { refreshCoreAssets } from "./core-assets.js";
 import { isSetupComplete } from "./setup-status.js";
 import { snapshotCurrentState } from "./rollback.js";
 import { checkDocker, composePreflight, composePull, composeUp, composeConfigServices, resolveComposeProjectName } from "./docker.js";
-import { acquireLock, releaseLock } from "./lock.js";
-import { appendAudit } from "./audit.js";
+import { acquireInstallLock, releaseInstallLock } from "./install-lock.js";
 import { listEnabledAddonIds } from "./registry.js";
 
 const IMAGE_NAMESPACE_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
 const SEMVER_TAG_RE = /^v\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 
 
-export function createState(
-  adminToken?: string
-): ControlPlaneState {
+export function createState(): ControlPlaneState {
   const homeDir = resolveOpenPalmHome();
   const configDir = resolveConfigDir();
   const stashDir = resolveStashDir();
@@ -50,8 +46,6 @@ export function createState(
   }
 
   const bootstrapState: ControlPlaneState = {
-    adminToken: adminToken ?? process.env.OP_UI_TOKEN ?? "",
-    assistantToken: "",
     homeDir,
     configDir,
     stashDir,
@@ -62,23 +56,10 @@ export function createState(
     services,
     artifacts: { compose: "" },
     artifactMeta: [],
-    audit: [],
   };
 
   ensureSecrets(bootstrapState);
 
-  const stackEnv = readStackEnv(stackDir);
-  // Precedence: explicit parameter > stack.env > process.env.
-  bootstrapState.adminToken =
-    adminToken
-      ?? stackEnv.OP_UI_TOKEN
-      ?? process.env.OP_UI_TOKEN
-      ?? "";
-  bootstrapState.assistantToken =
-    stackEnv.OP_ASSISTANT_TOKEN
-      ?? process.env.OP_ASSISTANT_TOKEN
-      ?? "";
-
   return bootstrapState;
 }
 
@@ -142,48 +123,37 @@ async function reconcileCore(
   return active;
 }
 
-export async function applyInstall(state: ControlPlaneState, ctx?: AuditContext): Promise<void> {
-  const lock = acquireLock(state.homeDir, "install");
+export async function applyInstall(state: ControlPlaneState): Promise<void> {
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
     await reconcileCore(state, { activateServices: true });
     // Pre-create host-side volume mount targets as the current user so
     // Docker doesn't create them root-owned (which causes EACCES inside
     // non-root containers).
     ensureComposeVolumeTargets(state);
-    if (ctx) appendAudit(state, ctx.actor, "install", {}, true, ctx.requestId ?? "", ctx.callerType ?? "unknown");
-  } catch (err) {
-    if (ctx) appendAudit(state, ctx.actor, "install", { error: String(err) }, false, ctx.requestId ?? "", ctx.callerType ?? "unknown");
-    throw err;
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 
-export async function applyUpdate(state: ControlPlaneState, ctx?: AuditContext): Promise<{ restarted: string[] }> {
-  const lock = acquireLock(state.homeDir, "update");
+export async function applyUpdate(state: ControlPlaneState): Promise<{ restarted: string[] }> {
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
-    const result = { restarted: await reconcileCore(state, {}) };
-    if (ctx) appendAudit(state, ctx.actor, "update", { restarted: result.restarted }, true, ctx.requestId ?? "", ctx.callerType ?? "unknown");
-    return result;
-  } catch (err) {
-    if (ctx) appendAudit(state, ctx.actor, "update", { error: String(err) }, false, ctx.requestId ?? "", ctx.callerType ?? "unknown");
-    throw err;
+    return { restarted: await reconcileCore(state, {}) };
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 
-export async function applyUninstall(state: ControlPlaneState, ctx?: AuditContext): Promise<{ stopped: string[] }> {
-  const lock = acquireLock(state.homeDir, "uninstall");
+export async function applyUninstall(state: ControlPlaneState): Promise<{ stopped: string[] }> {
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
-    const result = { stopped: await reconcileCore(state, { deactivateServices: true }) };
-    if (ctx) appendAudit(state, ctx.actor, "uninstall", { stopped: result.stopped }, true, ctx.requestId ?? "", ctx.callerType ?? "unknown");
-    return result;
-  } catch (err) {
-    if (ctx) appendAudit(state, ctx.actor, "uninstall", { error: String(err) }, false, ctx.requestId ?? "", ctx.callerType ?? "unknown");
-    throw err;
+    return { stopped: await reconcileCore(state, { deactivateServices: true }) };
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 
@@ -250,13 +220,14 @@ export async function applyUpgrade(
   updated: string[];
   restarted: string[];
 }> {
-  const lock = acquireLock(state.homeDir, "upgrade");
+  const lock = acquireInstallLock(state.stateDir);
+  if (!lock) throw new Error("Another install is already in progress");
   try {
     const { backupDir, updated } = await refreshCoreAssets();
     const restarted = await reconcileCore(state, {});
     return { backupDir, updated, restarted };
   } finally {
-    releaseLock(lock);
+    releaseInstallLock(lock);
   }
 }
 
@@ -328,6 +299,24 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
   };
 }
 
+/**
+ * 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.
+ */
+export async function applyTagChange(state: ControlPlaneState, tag: string): Promise<UpgradeResult> {
+  const stackEnvPath = `${state.stackDir}/stack.env`;
+  const currentContent = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
+  writeFileSync(stackEnvPath, mergeEnvContent(currentContent, { OP_IMAGE_TAG: tag }, { uncomment: true }));
+  const upgradeResult = await applyUpgrade(state);
+  return {
+    imageTag: tag,
+    namespace: "openpalm",
+    backupDir: upgradeResult.backupDir,
+    assetsUpdated: upgradeResult.updated,
+    restarted: upgradeResult.restarted,
+  };
+}
+
 export function buildComposeFileList(state: ControlPlaneState): string[] {
   return discoverStackOverlays(state.stackDir);
 }

package/src/control-plane/migrate-0110.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Tests for the 0.11.0 auth-migration shim.
+ */
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  chmodSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { migrateAuth0110 } from "./migrate-0110.js";
+import type { ControlPlaneState } from "./types.js";
+
+function makeState(homeDir: string): ControlPlaneState {
+  return {
+    homeDir,
+    configDir: join(homeDir, "config"),
+    stashDir: join(homeDir, "stash"),
+    workspaceDir: join(homeDir, "workspace"),
+    cacheDir: join(homeDir, "cache"),
+    stateDir: join(homeDir, "state"),
+    stackDir: join(homeDir, "config", "stack"),
+    services: {},
+    artifacts: { compose: "" },
+    artifactMeta: [],
+  };
+}
+
+function seedStackEnv(stackDir: string, content: string): string {
+  mkdirSync(stackDir, { recursive: true });
+  const path = join(stackDir, "stack.env");
+  writeFileSync(path, content, { encoding: "utf-8", mode: 0o600 });
+  chmodSync(path, 0o600);
+  return path;
+}
+
+describe("migrateAuth0110", () => {
+  let homeDir: string;
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), "openpalm-migrate-0110-"));
+  });
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it("no-ops on a fresh install (no stack.env)", () => {
+    const state = makeState(homeDir);
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(false);
+    expect(result.reason).toContain("fresh install");
+  });
+
+  it("promotes OP_UI_TOKEN → OP_UI_LOGIN_PASSWORD and removes legacy keys", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "# header",
+        "OP_UI_TOKEN=legacy-token-value",
+        "OP_ASSISTANT_TOKEN=some-assistant-token",
+        "OP_OPENCODE_PASSWORD=opencode-secret",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    expect(result.reason).toContain("promoted OP_UI_TOKEN");
+    expect(result.reason).toContain("removed OP_UI_TOKEN");
+    expect(result.reason).toContain("removed OP_ASSISTANT_TOKEN");
+
+    const after = readFileSync(stackEnvPath, "utf-8");
+    expect(after).toContain("OP_UI_LOGIN_PASSWORD=legacy-token-value");
+    expect(after).not.toMatch(/^OP_UI_TOKEN=/m);
+    expect(after).not.toMatch(/^OP_ASSISTANT_TOKEN=/m);
+    // Unrelated keys preserved
+    expect(after).toContain("OP_OPENCODE_PASSWORD=opencode-secret");
+
+    // Perms preserved
+    expect(statSync(stackEnvPath).mode & 0o777).toBe(0o600);
+
+    // Migration log appended
+    const logPath = join(state.stateDir, "logs", "migration-0.11.0.log");
+    expect(existsSync(logPath)).toBe(true);
+    const log = readFileSync(logPath, "utf-8");
+    expect(log).toContain("migrate-auth-0110");
+    expect(log).toContain("promoted OP_UI_TOKEN");
+  });
+
+  it("does not overwrite an existing OP_UI_LOGIN_PASSWORD", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_LOGIN_PASSWORD=new-password",
+        "OP_UI_TOKEN=legacy-value",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    expect(result.reason).not.toContain("promoted");
+    expect(result.reason).toContain("removed OP_UI_TOKEN");
+
+    const after = readFileSync(stackEnvPath, "utf-8");
+    expect(after).toContain("OP_UI_LOGIN_PASSWORD=new-password");
+    expect(after).not.toMatch(/^OP_UI_TOKEN=/m);
+  });
+
+  it("removes OP_ASSISTANT_TOKEN even when only it is present", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_LOGIN_PASSWORD=pw",
+        "OP_ASSISTANT_TOKEN=stale",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    expect(result.reason).toContain("removed OP_ASSISTANT_TOKEN");
+    expect(readFileSync(stackEnvPath, "utf-8")).not.toMatch(/^OP_ASSISTANT_TOKEN=/m);
+  });
+
+  it("is idempotent: second run reports already-migrated", () => {
+    const state = makeState(homeDir);
+    seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_TOKEN=t",
+        "OP_ASSISTANT_TOKEN=t2",
+        "",
+      ].join("\n"),
+    );
+
+    const first = migrateAuth0110(state);
+    expect(first.migrated).toBe(true);
+
+    const second = migrateAuth0110(state);
+    expect(second.migrated).toBe(false);
+    expect(second.reason).toContain("already migrated");
+  });
+
+  it("treats an empty OP_UI_TOKEN value as not-set (no promotion)", () => {
+    const state = makeState(homeDir);
+    const stackEnvPath = seedStackEnv(
+      state.stackDir,
+      [
+        "OP_UI_TOKEN=",
+        "OP_ASSISTANT_TOKEN=foo",
+        "",
+      ].join("\n"),
+    );
+
+    const result = migrateAuth0110(state);
+    expect(result.migrated).toBe(true);
+    // Empty-string OP_UI_TOKEN should NOT be promoted as a password.
+    expect(result.reason).not.toContain("promoted");
+
+    const after = readFileSync(stackEnvPath, "utf-8");
+    // The empty OP_UI_TOKEN line is still removed.
+    expect(after).not.toMatch(/^OP_UI_TOKEN=/m);
+    // No OP_UI_LOGIN_PASSWORD added (would be an empty value).
+    expect(after).not.toMatch(/^OP_UI_LOGIN_PASSWORD=/m);
+  });
+});

package/src/control-plane/migrate-0110.ts

@@ -0,0 +1,99 @@
+/**
+ * One-shot migration for the 0.11.0 auth refactor.
+ *
+ * Existing installs have OP_UI_TOKEN and OP_ASSISTANT_TOKEN in
+ * config/stack/stack.env. The 0.11.0 refactor (auth-and-proxy-refactor-plan.md)
+ * replaces them with a single OP_UI_LOGIN_PASSWORD. If we don't migrate,
+ * operators get locked out the moment they run the new UI build because the
+ * login route compares the cookie against process.env.OP_UI_LOGIN_PASSWORD,
+ * which is empty on existing installs.
+ *
+ * Migration logic (idempotent):
+ *   - If OP_UI_LOGIN_PASSWORD is unset AND OP_UI_TOKEN is set, copy
+ *     OP_UI_TOKEN's value into OP_UI_LOGIN_PASSWORD.
+ *   - Remove OP_UI_TOKEN and OP_ASSISTANT_TOKEN from stack.env (they're
+ *     no longer used).
+ *   - Append a one-line summary to state/logs/migration-0.11.0.log.
+ *   - If OP_UI_LOGIN_PASSWORD is already set, leave it alone — the operator
+ *     already migrated or set up fresh.
+ *
+ * Called from ensureSecrets so it runs before any auth-required code path
+ * gets a chance to see the half-migrated state.
+ */
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  chmodSync,
+  appendFileSync,
+  mkdirSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { parseEnvContent, removeEnvKey, upsertEnvValue } from "./env.js";
+import { migration0110LogPath } from "./paths.js";
+import type { ControlPlaneState } from "./types.js";
+
+export type MigrateAuth0110Result = {
+  /** True if any change was written to stack.env. */
+  migrated: boolean;
+  /** Human-readable description of what changed (or why nothing did). */
+  reason: string;
+};
+
+export function migrateAuth0110(state: ControlPlaneState): MigrateAuth0110Result {
+  const stackEnvPath = `${state.stackDir}/stack.env`;
+  if (!existsSync(stackEnvPath)) {
+    return { migrated: false, reason: "no stack.env yet (fresh install)" };
+  }
+
+  const before = readFileSync(stackEnvPath, "utf-8");
+  const parsed = parseEnvContent(before);
+  const hasLoginPw = typeof parsed.OP_UI_LOGIN_PASSWORD === "string" && parsed.OP_UI_LOGIN_PASSWORD.length > 0;
+  const hasUiToken = typeof parsed.OP_UI_TOKEN === "string" && parsed.OP_UI_TOKEN.length > 0;
+  const hasAssistantToken = "OP_ASSISTANT_TOKEN" in parsed;
+  const hasUiTokenLine = "OP_UI_TOKEN" in parsed;
+
+  if (hasLoginPw && !hasUiTokenLine && !hasAssistantToken) {
+    return { migrated: false, reason: "already migrated" };
+  }
+
+  let content = before;
+  const changes: string[] = [];
+
+  if (!hasLoginPw && hasUiToken) {
+    content = upsertEnvValue(content, "OP_UI_LOGIN_PASSWORD", parsed.OP_UI_TOKEN);
+    changes.push("promoted OP_UI_TOKEN → OP_UI_LOGIN_PASSWORD");
+  }
+  if (hasUiTokenLine) {
+    content = removeEnvKey(content, "OP_UI_TOKEN");
+    changes.push("removed OP_UI_TOKEN");
+  }
+  if (hasAssistantToken) {
+    content = removeEnvKey(content, "OP_ASSISTANT_TOKEN");
+    changes.push("removed OP_ASSISTANT_TOKEN");
+  }
+
+  if (changes.length === 0) {
+    return { migrated: false, reason: "no changes needed" };
+  }
+
+  // Preserve the 0600 mode the existing file should already have.
+  writeFileSync(stackEnvPath, content, { encoding: "utf-8", mode: 0o600 });
+  try { chmodSync(stackEnvPath, 0o600); } catch { /* best-effort */ }
+
+  // Best-effort audit line. The migration log is small and append-only;
+  // if it fails (perm error, fs full), we don't roll back the migration.
+  try {
+    const logPath = migration0110LogPath(state);
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(
+      logPath,
+      `${new Date().toISOString()} migrate-auth-0110 ${changes.join("; ")}\n`,
+      "utf-8",
+    );
+  } catch {
+    /* best-effort */
+  }
+
+  return { migrated: true, reason: changes.join("; ") };
+}