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

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

@@ -2,7 +2,7 @@
  * Edge-case tests for the OpenPalm install and setup flow.
  *
  * Each test creates its own temp directory tree mimicking the single
- * ~/.openpalm/ root layout (config, vault, data, logs), then runs the
+ * ~/.openpalm/ root layout (config, knowledge, data, logs), then runs the
  * actual library functions against it. No mocks of code under test.
  */
 import { describe, expect, it, beforeEach, afterEach } from "bun:test";
@@ -23,11 +23,10 @@ import {
   performSetup,
   buildSecretsFromSetup,
   buildAuthJsonFromSetup,
-  buildSystemSecretsFromSetup,
 } from "./setup.js";
 import type { SetupSpec, SetupConnection } from "./setup.js";
 import type { ControlPlaneState } from "./types.js";
-import { STACK_SPEC_FILENAME, readStackSpec } from "./stack-spec.js";
+import { readSecret } from './secrets-files.js';
 
 // ── Helpers ──────────────────────────────────────────────────────────────
 
@@ -55,70 +54,69 @@ function makeValidSpec(overrides?: Partial<SetupSpec>): SetupSpec {
 function seedRequiredAssets(homeDir: string): void {
   mkdirSync(join(homeDir, "config", "stack"), { recursive: true });
   writeFileSync(join(homeDir, "config", "stack", "core.compose.yml"), "services:\n  assistant:\n    image: assistant:latest\n");
-  mkdirSync(join(homeDir, "state", "assistant"), { recursive: true });
-  writeFileSync(join(homeDir, "state", "assistant", "opencode.jsonc"), '{"$schema":"https://opencode.ai/config.json"}\n');
-  writeFileSync(join(homeDir, "state", "assistant", "AGENTS.md"), "# Agents\n");
-  mkdirSync(join(homeDir, "state"), { recursive: true });
-  // Automations live in state/registry/automations (shipped catalog) and stash/tasks (user tasks)
-  mkdirSync(join(homeDir, "state", "registry", "automations"), { recursive: true });
-  writeFileSync(join(homeDir, "state", "registry", "automations", "cleanup-logs.md"), "---\nschedule: \"0 4 * * 0\"\ndescription: cleanup logs\n---\n");
-  writeFileSync(join(homeDir, "state", "registry", "automations", "cleanup-data.md"), "---\nschedule: \"0 5 * * 0\"\ndescription: cleanup data\n---\n");
-  writeFileSync(join(homeDir, "state", "registry", "automations", "validate-config.md"), "---\nschedule: \"0 3 * * *\"\ndescription: validate config\n---\n");
+  mkdirSync(join(homeDir, "data", "assistant"), { recursive: true });
+  writeFileSync(join(homeDir, "data", "assistant", "opencode.jsonc"), '{"$schema":"https://opencode.ai/config.json"}\n');
+  writeFileSync(join(homeDir, "data", "assistant", "AGENTS.md"), "# Agents\n");
+  mkdirSync(join(homeDir, "data"), { recursive: true });
+  // Automations live in knowledge/tasks as AKM-owned task files.
+  mkdirSync(join(homeDir, "knowledge", "tasks"), { recursive: true });
+  writeFileSync(join(homeDir, "knowledge", "tasks", "cleanup-logs.yml"), "schedule: \"0 4 * * 0\"\ndescription: cleanup logs\ncommand: [\"echo\",\"clean\"]\n");
+  writeFileSync(join(homeDir, "knowledge", "tasks", "cleanup-data.yml"), "schedule: \"0 5 * * 0\"\ndescription: cleanup data\ncommand: [\"echo\",\"clean\"]\n");
+  writeFileSync(join(homeDir, "knowledge", "tasks", "validate-config.yml"), "schedule: \"0 3 * * *\"\ndescription: validate config\ncommand: [\"echo\",\"clean\"]\n");
 }
 
 // ── Shared test fixture ──────────────────────────────────────────────────
 
 let homeDir: string;
 let configDir: string;
-let stateDir: string;
+let dataDir: string;
 let stackDir: string;
-let cacheDir: string;
 
 const savedEnv: Record<string, string | undefined> = {};
 
 function saveAndSetEnv(): void {
   savedEnv.OP_HOME = process.env.OP_HOME;
+  savedEnv.OP_UI_LOGIN_PASSWORD = process.env.OP_UI_LOGIN_PASSWORD;
+  savedEnv.OP_OPENCODE_PASSWORD = process.env.OP_OPENCODE_PASSWORD;
   process.env.OP_HOME = homeDir;
+  delete process.env.OP_UI_LOGIN_PASSWORD;
+  delete process.env.OP_OPENCODE_PASSWORD;
 }
 
 function restoreEnv(): void {
-  process.env.OP_HOME = savedEnv.OP_HOME;
+  if (savedEnv.OP_HOME === undefined) delete process.env.OP_HOME;
+  else process.env.OP_HOME = savedEnv.OP_HOME;
+  if (savedEnv.OP_UI_LOGIN_PASSWORD === undefined) delete process.env.OP_UI_LOGIN_PASSWORD;
+  else process.env.OP_UI_LOGIN_PASSWORD = savedEnv.OP_UI_LOGIN_PASSWORD;
+  if (savedEnv.OP_OPENCODE_PASSWORD === undefined) delete process.env.OP_OPENCODE_PASSWORD;
+  else process.env.OP_OPENCODE_PASSWORD = savedEnv.OP_OPENCODE_PASSWORD;
 }
 
 /** Create a full directory tree matching ensureHomeDirs() output. */
 function createFullDirTree(): void {
   homeDir = mkdtempSync(join(tmpdir(), "openpalm-edge-"));
   configDir = join(homeDir, "config");
-  stateDir = join(homeDir, "state");
+  dataDir = join(homeDir, "data");
   stackDir = join(configDir, "stack");
-  cacheDir = join(homeDir, "cache");
 
   for (const dir of [
     homeDir,
     configDir,
-    join(homeDir, "state", "registry", "automations"),
     join(configDir, "assistant"),
     join(configDir, "akm"),
-    join(homeDir, "stash"),
+    join(homeDir, "knowledge"),
+    join(homeDir, "knowledge", "env"),
+    join(homeDir, "knowledge", "secrets"),
     join(homeDir, "workspace"),
     stackDir,
-    join(stackDir, "addons"),
-    stateDir,
-    join(stateDir, "assistant"),
-    join(stateDir, "admin"),
-    join(stateDir, "guardian"),
-    join(stateDir, "logs"),
-    join(stateDir, "logs", "opencode"),
-    join(stateDir, "registry"),
-    join(stateDir, "registry", "addons"),
-    join(stateDir, "backups"),
-    join(stateDir, "akm"),
-    join(stateDir, "akm", "data"),
-    join(stateDir, "akm", "state"),
-    cacheDir,
-    join(cacheDir, "akm"),
-    join(cacheDir, "guardian"),
-    join(cacheDir, "rollback"),
+    dataDir,
+    join(dataDir, "assistant"),
+    join(dataDir, "guardian"),
+    join(dataDir, "akm", "cache"),
+    join(dataDir, "akm", "data"),
+    join(dataDir, "logs"),
+    join(dataDir, "backups"),
+    join(dataDir, "rollback"),
   ]) {
     mkdirSync(dir, { recursive: true });
   }
@@ -132,16 +130,10 @@ function seedMinimalEnvFiles(): void {
   mkdirSync(stackDir, { recursive: true });
 
   writeFileSync(
-    join(stackDir, "stack.env"),
+    join(homeDir, "knowledge", "env", "stack.env"),
     [
       "# OpenPalm — Stack Configuration",
-      "OP_UI_LOGIN_PASSWORD=",
-      "OPENAI_API_KEY=",
       "OPENAI_BASE_URL=",
-      "ANTHROPIC_API_KEY=",
-      "GROQ_API_KEY=",
-      "MISTRAL_API_KEY=",
-      "GOOGLE_API_KEY=",
       "OP_OWNER_NAME=",
       "OP_OWNER_EMAIL=",
       "",
@@ -166,16 +158,15 @@ describe("Fresh Install", () => {
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  // Scenario 1: ensureSecrets does NOT seed user.env (see akm-vault) but
+  // Scenario 1: ensureSecrets does NOT seed user.env (see akm-user-env) but
   // does create stack.env with required keys when files do not exist.
-  it("ensureSecrets creates state/stack.env with required keys on fresh install", () => {
+  it("ensureSecrets creates stack.env with required keys on fresh install", () => {
     const state: ControlPlaneState = {
       homeDir,
       configDir,
-      stashDir: join(homeDir, "stash"),
+      stashDir: join(homeDir, "knowledge"),
       workspaceDir: join(homeDir, "workspace"),
-      cacheDir,
-      stateDir,
+      dataDir,
       stackDir,
       services: {},
       artifacts: { compose: "" },
@@ -184,17 +175,18 @@ describe("Fresh Install", () => {
 
     ensureSecrets(state);
 
-    // 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("OP_OWNER_NAME=");
+    // stack.env only carries non-secret setup/config keys.
+    const stackContent = readFileSync(join(homeDir, "knowledge", "env", "stack.env"), "utf-8");
+    expect(stackContent).not.toContain("OPENAI_API_KEY=");
+    expect(stackContent).toContain("OP_SETUP_COMPLETE=false");
+    expect(readSecret(stackDir, 'op_ui_login_password')).toBeNull();
   });
 
   // Scenario 2: isSetupComplete returns false before setup
   it("isSetupComplete returns false when stack.env has OP_SETUP_COMPLETE=false", () => {
-    mkdirSync(stateDir, { recursive: true });
+    mkdirSync(dataDir, { recursive: true });
     writeFileSync(
-      join(stackDir, "stack.env"),
+      join(homeDir, "knowledge", "env", "stack.env"),
       "OP_SETUP_COMPLETE=false\n"
     );
 
@@ -223,7 +215,7 @@ describe("Fresh Install", () => {
 
     await performSetup(makeValidSpec());
 
-    const stackEnv = readFileSync(join(stackDir, "stack.env"), "utf-8");
+    const stackEnv = readFileSync(join(homeDir, "knowledge", "env", "stack.env"), "utf-8");
     const parsed = parseEnvContent(stackEnv);
     // Either entirely absent, or still the seeded "false" — never "true".
     expect(parsed.OP_SETUP_COMPLETE === undefined || parsed.OP_SETUP_COMPLETE === "false").toBe(true);
@@ -246,18 +238,17 @@ describe("Existing Install", () => {
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  // 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_LOGIN_PASSWORD=my-custom-password\n");
+  // Scenario 5: ensureSecrets creates file-based secrets without stack.env tokens
+  it("ensureSecrets creates file-based system secrets", () => {
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(join(homeDir, "knowledge", "env", "stack.env"), "OP_SETUP_COMPLETE=false\n");
 
     const state: ControlPlaneState = {
       homeDir,
       configDir,
-      stashDir: join(homeDir, "stash"),
+      stashDir: join(homeDir, "knowledge"),
       workspaceDir: join(homeDir, "workspace"),
-      cacheDir,
-      stateDir,
+      dataDir,
       stackDir,
       services: {},
       artifacts: { compose: "" },
@@ -266,25 +257,23 @@ describe("Existing Install", () => {
 
     ensureSecrets(state);
 
-    // Existing password must be preserved
-    const afterContent = readFileSync(join(stackDir, "stack.env"), "utf-8");
-    expect(afterContent).toContain("OP_UI_LOGIN_PASSWORD=my-custom-password");
+    const afterContent = readFileSync(join(homeDir, "knowledge", "env", "stack.env"), "utf-8");
+    expect(afterContent).not.toContain("OP_UI_LOGIN_PASSWORD=");
+    expect(readSecret(stackDir, 'op_ui_login_password')).toBeNull();
   });
 
   // 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 () => {
+  it("performSetup re-run rewrites OP_UI_LOGIN_PASSWORD secret file when spec changes", async () => {
     await performSetup(makeValidSpec({ security: { uiLoginPassword: "first-password-12345" } }));
 
-    const afterFirst = readFileSync(join(stackDir, "stack.env"), "utf-8");
-    expect(afterFirst).toContain("OP_UI_LOGIN_PASSWORD=first-password-12345");
+    expect(readSecret(stackDir, 'op_ui_login_password')).toBe("first-password-12345\n");
 
     await performSetup(makeValidSpec({ security: { uiLoginPassword: "second-password-12345" } }));
 
-    const afterSecond = readFileSync(join(stackDir, "stack.env"), "utf-8");
-    expect(afterSecond).toContain("OP_UI_LOGIN_PASSWORD=second-password-12345");
+    expect(readSecret(stackDir, 'op_ui_login_password')).toBe("second-password-12345\n");
   });
 
   // Scenario 7: performSetup must NOT mark OP_SETUP_COMPLETE — see scenario
@@ -294,7 +283,7 @@ describe("Existing Install", () => {
     await performSetup(makeValidSpec());
 
     const stackEnv = readFileSync(
-      join(stackDir, "stack.env"),
+      join(homeDir, "knowledge", "env", "stack.env"),
       "utf-8"
     );
     const parsed = parseEnvContent(stackEnv);
@@ -323,14 +312,8 @@ describe("Existing Install", () => {
       })
     );
 
-    // stack.yml is just a version marker now
-    const specAfterSecond = readStackSpec(stackDir);
-    expect(specAfterSecond).not.toBeNull();
-    expect(specAfterSecond!.version).toBe(2);
-
-    // stack.env should retain both keys
-    const secrets = readFileSync(join(stackDir, "stack.env"), "utf-8");
-    expect(secrets).toContain("GROQ_API_KEY");
+    const auth = JSON.parse(readFileSync(join(homeDir, "knowledge", "secrets", "auth.json"), "utf-8"));
+    expect(auth.groq.key).toBe("gsk-test-key-456");
   });
 });
 
@@ -351,16 +334,15 @@ 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_LOGIN_PASSWORD=existing-password\n");
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(join(homeDir, "knowledge", "env", "stack.env"), "OP_SETUP_COMPLETE=false\n");
 
     const state: ControlPlaneState = {
       homeDir,
       configDir,
-      stashDir: join(homeDir, "stash"),
+      stashDir: join(homeDir, "knowledge"),
       workspaceDir: join(homeDir, "workspace"),
-      cacheDir,
-      stateDir,
+      dataDir,
       stackDir,
       services: {},
       artifacts: { compose: "" },
@@ -369,9 +351,10 @@ describe("Broken/Corrupt State", () => {
 
     ensureSecrets(state);
 
-    // Existing password must be preserved
-    const content = readFileSync(join(stackDir, "stack.env"), "utf-8");
-    expect(content).toContain("OP_UI_LOGIN_PASSWORD=existing-password");
+    // Existing non-secret stack config must be preserved.
+    const content = readFileSync(join(homeDir, "knowledge", "env", "stack.env"), "utf-8");
+    expect(content).toContain("OP_SETUP_COMPLETE=false");
+    expect(content).not.toContain("OP_UI_LOGIN_PASSWORD=");
   });
 
   // Scenario 10: env file with malformed lines
@@ -388,10 +371,10 @@ describe("Broken/Corrupt State", () => {
       "  # indented comment",
     ].join("\n");
 
-    mkdirSync(stateDir, { recursive: true });
-    writeFileSync(join(stateDir, "test.env"), malformedContent);
+    mkdirSync(dataDir, { recursive: true });
+    writeFileSync(join(dataDir, "test.env"), malformedContent);
 
-    const parsed = parseEnvFile(join(stateDir, "test.env"));
+    const parsed = parseEnvFile(join(dataDir, "test.env"));
     expect(parsed.VALID_KEY).toBe("valid_value");
     expect(parsed.EXPORTED_KEY).toBe("exported_value");
     expect(parsed.ANOTHER_VALID).toBe("value");
@@ -400,23 +383,25 @@ describe("Broken/Corrupt State", () => {
   // Scenario 11: stack.env missing OP_SETUP_COMPLETE
   it("isSetupComplete falls back to token check when OP_SETUP_COMPLETE missing", () => {
     // stack.env without OP_SETUP_COMPLETE
-    mkdirSync(stateDir, { recursive: true });
+    mkdirSync(dataDir, { recursive: true });
     writeFileSync(
-      join(stackDir, "stack.env"),
+      join(homeDir, "knowledge", "env", "stack.env"),
       "OP_IMAGE_TAG=latest\n"
     );
 
     expect(isSetupComplete(stackDir)).toBe(false);
   });
 
-  it("isSetupComplete falls back to true when UI login password is set but OP_SETUP_COMPLETE missing", () => {
-    mkdirSync(stateDir, { recursive: true });
+  it("isSetupComplete returns false when OP_UI_LOGIN_PASSWORD is set but OP_SETUP_COMPLETE is missing", () => {
+    mkdirSync(dataDir, { recursive: true });
     writeFileSync(
-      join(stackDir, "stack.env"),
+      join(homeDir, "knowledge", "env", "stack.env"),
       "OP_IMAGE_TAG=latest\nexport OP_UI_LOGIN_PASSWORD=my-real-password\n"
     );
 
-    expect(isSetupComplete(stackDir)).toBe(true);
+    // Password alone is no longer a proxy for setup completion.
+    // Only OP_SETUP_COMPLETE=true counts.
+    expect(isSetupComplete(stackDir)).toBe(false);
   });
 
   // Scenario 12: API key with special characters round-trips
@@ -435,19 +420,13 @@ describe("Broken/Corrupt State", () => {
     }
   });
 
-  // Scenario 13: Missing stack.yml returns null
-  it("readStackSpec returns null when stack.yml missing", () => {
-    const spec = readStackSpec(stackDir);
-    expect(spec).toBeNull();
-  });
-
-  // Scenario 14: stash/tasks dir missing (performSetup should recreate it via ensureHomeDirs)
+  // Scenario 14: knowledge/tasks dir missing (performSetup should recreate it via ensureHomeDirs)
   it("performSetup creates missing subdirectories", async () => {
     // Seed the minimal env files first
     seedMinimalEnvFiles();
 
-    // Remove stash/tasks dir (performSetup should recreate it via ensureHomeDirs)
-    rmSync(join(homeDir, "stash", "tasks"), { recursive: true, force: true });
+    // Remove knowledge/tasks dir (performSetup should recreate it via ensureHomeDirs)
+    rmSync(join(homeDir, "knowledge", "tasks"), { recursive: true, force: true });
 
     const result = await performSetup(
       makeValidSpec()
@@ -458,20 +437,10 @@ describe("Broken/Corrupt State", () => {
     expect(existsSync(join(homeDir, "config", "stack", "core.compose.yml"))).toBe(
       true
     );
-    // stash/tasks dir should be recreated by ensureHomeDirs
-    expect(existsSync(join(homeDir, "stash", "tasks"))).toBe(true);
+    // knowledge/tasks dir should be recreated by ensureHomeDirs
+    expect(existsSync(join(homeDir, "knowledge", "tasks"))).toBe(true);
   });
 
-  // Scenario 15: openpalm.yaml with old version
-  it("readStackSpec returns null for version 1 spec", () => {
-    writeFileSync(
-      join(stackDir, STACK_SPEC_FILENAME),
-      "version: 1\nconnections: []\n"
-    );
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).toBeNull();
-  });
 });
 
 // =====================================================================
@@ -489,15 +458,15 @@ describe("Environment Edge Cases", () => {
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  // Scenario 16: isSetupComplete picks up OP_UI_LOGIN_PASSWORD when set
-  it("isSetupComplete detects OP_UI_LOGIN_PASSWORD", () => {
-    mkdirSync(stateDir, { recursive: true });
+  // Scenario 16: isSetupComplete requires explicit OP_SETUP_COMPLETE=true
+  it("isSetupComplete returns false when only OP_UI_LOGIN_PASSWORD is set", () => {
+    mkdirSync(dataDir, { recursive: true });
     writeFileSync(
-      join(stackDir, "stack.env"),
+      join(homeDir, "knowledge", "env", "stack.env"),
       "SOME_OTHER_KEY=value\nexport OP_UI_LOGIN_PASSWORD=real-password-here\n"
     );
 
-    expect(isSetupComplete(stackDir)).toBe(true);
+    expect(isSetupComplete(stackDir)).toBe(false);
   });
 
   // Scenario 17: export prefix on env vars
@@ -571,10 +540,6 @@ describe("Setup Input Variations", () => {
 
     const result = await performSetup(input);
     expect(result.ok).toBe(true);
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
   });
 
   // Scenario 21: Multiple providers map to correct env vars
@@ -635,12 +600,9 @@ describe("performSetup end-to-end artifacts", () => {
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  it("writes stack.yml and readStackSpec returns v2", async () => {
+  it("does not create a stack.yml (addon state lives in stack.env)", async () => {
     await performSetup(makeValidSpec());
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
+    expect(existsSync(join(stackDir, "stack.yml"))).toBe(false);
   });
 
   it("writes akm config with embedding dims from setup spec", async () => {
@@ -667,11 +629,10 @@ describe("performSetup end-to-end artifacts", () => {
     ).toBe(true);
   });
 
-  it("writes the UI login password to stack.env", async () => {
+  it("writes the UI login password to a secret file", async () => {
     await performSetup(makeValidSpec());
 
-    const secrets = parseEnvFile(join(stackDir, "stack.env"));
-    expect(secrets.OP_UI_LOGIN_PASSWORD).toBe("test-admin-token-12345");
+    expect(readSecret(stackDir, 'op_ui_login_password')).toBe("test-admin-token-12345\n");
   });
 
   it("writes akm config with llm provider and model", async () => {
@@ -679,8 +640,11 @@ describe("performSetup end-to-end artifacts", () => {
 
     const akmConfigPath = join(homeDir, "config", "akm", "config.json");
     const config = JSON.parse(readFileSync(akmConfigPath, "utf-8"));
-    expect(config.llm.provider).toBe("openai");
-    expect(config.llm.model).toBe("gpt-4o");
+    // Canonical akm 0.8.0 shape (I-3): profiles.llm.default + defaults.llm.
+    expect(config.llm).toBeUndefined();
+    expect(config.profiles.llm.default.provider).toBe("openai");
+    expect(config.profiles.llm.default.model).toBe("gpt-4o");
+    expect(config.defaults.llm).toBe("default");
     expect(config.embedding.model).toBe("text-embedding-3-small");
   });
 });

package/src/control-plane/install-lock.ts

@@ -3,7 +3,7 @@
  *
  * Both `performSetup` (config writes) and `startDeploy` (Docker work) need an
  * exclusive lock against concurrent installs. The lock file lives at
- * `<stateDir>/.install.lock` and contains `<pid>\n<timestamp>\n`.
+ * `<dataDir>/.install.lock` and contains `<pid>\n<timestamp>\n`.
  *
  * Self-healing rules:
  *  - On EEXIST, parse the holder PID. If the process is gone (`process.kill(pid, 0)`
@@ -89,23 +89,23 @@ function tryCreate(path: string): boolean {
 }
 
 /**
- * Try to acquire the install lock under `stateDir`. Returns a handle on
+ * Try to acquire the install lock under `dataDir`. Returns a handle on
  * success or null if the lock is held by a live, recent install (or on any
  * unexpected filesystem error — caller should surface "install_in_progress").
  *
  * Callers MUST call `releaseInstallLock()` in a finally block when done.
  */
-export function acquireInstallLock(stateDir: string): InstallLockHandle | null {
+export function acquireInstallLock(dataDir: string): InstallLockHandle | null {
   try {
-    mkdirSync(stateDir, { recursive: true });
+    mkdirSync(dataDir, { recursive: true });
   } catch (err) {
-    logger.warn("failed to ensure state dir for install lock", {
-      stateDir,
+    logger.warn("failed to ensure data dir for install lock", {
+      dataDir,
       error: err instanceof Error ? err.message : String(err),
     });
     return null;
   }
-  const path = join(stateDir, ".install.lock");
+  const path = join(dataDir, ".install.lock");
 
   try {
     if (tryCreate(path)) return { path };