@openpalm/lib 0.11.0-beta.8 → 0.11.0-rc.1

package/README.md

@@ -21,7 +21,7 @@ Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
 ## Important context
 
 - Some filenames still use legacy names like `staging`; those modules now support the direct-write compose model
-- `config/` is user-owned, `config/stack/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
+- `config/` is user-owned, `knowledge/env/stack.env` is system-managed, `registry/` is catalog-only, and `stack/addons/` contains enabled runtime overlays
 - New reusable control-plane logic belongs here, not duplicated in consumers
 
 ## Main module areas

package/package.json

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

package/src/control-plane/akm-sources.test.ts

@@ -0,0 +1,206 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  HOST_SOURCE_NAME,
+  addHostStashToOpenpalmConfig,
+  removeHostAkmSource,
+  importHostProfiles,
+} from "./akm-sources.js";
+import type { ControlPlaneState } from "./types.js";
+
+let root = "";
+let state: ControlPlaneState;
+let opConfigPath = "";
+let hostConfigPath = "";
+
+function readJson(p: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(p, "utf-8"));
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "akm-sources-"));
+  const configDir = join(root, "config");
+  mkdirSync(join(configDir, "akm"), { recursive: true });
+  opConfigPath = join(configDir, "akm", "config.json");
+  state = { configDir, stashDir: join(root, "knowledge") } as ControlPlaneState;
+  hostConfigPath = join(root, "home", ".config", "akm", "config.json");
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("addHostStashToOpenpalmConfig (assistant side, parse-tolerant)", () => {
+  it("adds a writable /host-stash secondary with no primary/defaultWriteTarget", () => {
+    addHostStashToOpenpalmConfig(state, true);
+    const cfg = readJson(opConfigPath);
+    const sources = cfg.sources as Array<Record<string, unknown>>;
+    expect(sources).toHaveLength(1);
+    expect(sources[0]).toEqual({ type: "filesystem", path: "/host-stash", name: HOST_SOURCE_NAME, writable: true, enabled: true });
+    expect(cfg.defaultWriteTarget).toBeUndefined();
+    expect(cfg.stashDir).toBeUndefined();
+    expect("primary" in sources[0]).toBe(false);
+  });
+
+  it("is idempotent — upserts by name, never duplicates", () => {
+    addHostStashToOpenpalmConfig(state, true);
+    addHostStashToOpenpalmConfig(state, false);
+    const sources = readJson(opConfigPath).sources as Array<Record<string, unknown>>;
+    expect(sources).toHaveLength(1);
+    expect(sources[0].writable).toBe(false);
+  });
+
+  it("preserves unrelated existing sources and config keys", () => {
+    writeFileSync(opConfigPath, JSON.stringify({
+      embedding: { model: "nomic-embed-text", dimension: 768 },
+      sources: [{ type: "filesystem", path: "/other", name: "other", enabled: true }],
+    }));
+    addHostStashToOpenpalmConfig(state, true);
+    const cfg = readJson(opConfigPath);
+    expect((cfg.embedding as Record<string, unknown>).dimension).toBe(768);
+    const names = (cfg.sources as Array<Record<string, unknown>>).map((s) => s.name);
+    expect(names).toContain("other");
+    expect(names).toContain(HOST_SOURCE_NAME);
+  });
+
+  it("recovers from a corrupt OpenPalm config (parse-tolerant → starts from {})", () => {
+    writeFileSync(opConfigPath, "{ this is not json");
+    addHostStashToOpenpalmConfig(state, true);
+    expect((readJson(opConfigPath).sources as unknown[]).length).toBe(1);
+  });
+
+  it("writes mode 0600", () => {
+    addHostStashToOpenpalmConfig(state, true);
+    expect(statSync(opConfigPath).mode & 0o777).toBe(0o600);
+  });
+});
+
+describe("removeHostAkmSource (assistant side only — never touches personal config)", () => {
+  it("removes the host-akm source, leaving other sources intact", () => {
+    writeFileSync(opConfigPath, JSON.stringify({
+      sources: [
+        { type: "filesystem", path: "/host-stash", name: HOST_SOURCE_NAME },
+        { type: "filesystem", path: "/keep", name: "keep" },
+      ],
+    }));
+    removeHostAkmSource(state);
+    expect((readJson(opConfigPath).sources as Array<Record<string, unknown>>).map((s) => s.name)).toEqual(["keep"]);
+  });
+
+  it("is idempotent when no host-akm source exists", () => {
+    writeFileSync(opConfigPath, JSON.stringify({ sources: [{ name: "keep", type: "filesystem", path: "/k" }] }));
+    expect(() => removeHostAkmSource(state)).not.toThrow();
+    expect((readJson(opConfigPath).sources as unknown[]).length).toBe(1);
+  });
+});
+
+describe("importHostProfiles (read-only snapshot of host profiles)", () => {
+  function seedHostConfig(obj: Record<string, unknown>): string {
+    mkdirSync(join(root, "home", ".config", "akm"), { recursive: true });
+    const original = JSON.stringify(obj, null, 2);
+    writeFileSync(hostConfigPath, original);
+    return original;
+  }
+
+  it("copies llm/agent/improve profiles + defaults + embedding into an empty config", () => {
+    seedHostConfig({
+      profiles: {
+        llm: { default: { endpoint: "http://h/v1/chat/completions", model: "qwen", provider: "ollama" } },
+        agent: { default: { platform: "opencode" } },
+        improve: { thorough: { limit: 50 } },
+      },
+      defaults: { llm: "default", agent: "default", improve: "thorough" },
+      embedding: { provider: "ollama", model: "nomic-embed-text", dimension: 768 },
+    });
+    writeFileSync(opConfigPath, "{}");
+    const { imported } = importHostProfiles(state, hostConfigPath);
+    expect(imported).toContain("profiles.llm");
+    expect(imported).toContain("profiles.agent");
+    expect(imported).toContain("profiles.improve");
+    expect(imported).toContain("defaults.llm");
+    expect(imported).toContain("defaults.improve");
+    expect(imported).toContain("embedding");
+    const cfg = readJson(opConfigPath);
+    const profiles = cfg.profiles as Record<string, Record<string, Record<string, unknown>>>;
+    expect(profiles.llm.default.model).toBe("qwen");
+    expect(profiles.improve.thorough.limit).toBe(50);
+    expect((cfg.defaults as Record<string, unknown>).improve).toBe("thorough");
+    expect((cfg.embedding as Record<string, unknown>).model).toBe("nomic-embed-text");
+    expect((cfg.embedding as Record<string, unknown>).dimension).toBe(768);
+    expect(cfg.llm).toBeUndefined();
+  });
+
+  it("is ADDITIVE — never overwrites existing profiles, defaults, or embedding fields", () => {
+    seedHostConfig({
+      profiles: {
+        llm: {
+          default: { endpoint: "http://host/v1/chat/completions", model: "host-model" }, // conflicts with existing
+          "host-only": { endpoint: "http://host/v1/chat/completions", model: "extra" },  // new → added
+        },
+      },
+      defaults: { llm: "host-only" }, // existing already has defaults.llm → must NOT change
+      embedding: { provider: "ollama", model: "host-emb", dimension: 768, batchSize: 32 }, // model conflicts; batchSize new
+    });
+    writeFileSync(opConfigPath, JSON.stringify({
+      profiles: { llm: { default: { endpoint: "http://op/v1/chat/completions", model: "op-model" } } },
+      defaults: { llm: "default" },
+      embedding: { provider: "openai", model: "op-emb", dimension: 1536 },
+    }));
+
+    const { imported } = importHostProfiles(state, hostConfigPath);
+    const cfg = readJson(opConfigPath);
+    const profiles = cfg.profiles as Record<string, Record<string, Record<string, unknown>>>;
+    // Existing 'default' profile is preserved untouched.
+    expect(profiles.llm.default.model).toBe("op-model");
+    // Host-only profile is added.
+    expect(profiles.llm["host-only"].model).toBe("extra");
+    expect(imported).toContain("profiles.llm");
+    // Existing default selection is NOT overwritten.
+    expect((cfg.defaults as Record<string, unknown>).llm).toBe("default");
+    expect(imported).not.toContain("defaults.llm");
+    // Embedding: existing fields win; only the new field (batchSize) is added.
+    const emb = cfg.embedding as Record<string, unknown>;
+    expect(emb.model).toBe("op-emb");
+    expect(emb.provider).toBe("openai");
+    expect(emb.dimension).toBe(1536);
+    expect(emb.batchSize).toBe(32);
+    expect(imported).toContain("embedding");
+  });
+
+  it("does not report a namespace as imported when it adds nothing new", () => {
+    seedHostConfig({
+      profiles: { llm: { default: { endpoint: "x", model: "host" } } },
+      defaults: { llm: "default" },
+    });
+    writeFileSync(opConfigPath, JSON.stringify({
+      profiles: { llm: { default: { endpoint: "y", model: "op" } } },
+      defaults: { llm: "default" },
+    }));
+    const { imported } = importHostProfiles(state, hostConfigPath);
+    expect(imported).not.toContain("profiles.llm"); // 'default' already present, nothing added
+    expect(imported).not.toContain("defaults.llm");
+    // existing values untouched
+    const cfg = readJson(opConfigPath);
+    expect((cfg.profiles as Record<string, Record<string, Record<string, unknown>>>).llm.default.model).toBe("op");
+  });
+
+  it("reads the host config READ-ONLY (host file unchanged byte-for-byte)", () => {
+    const original = seedHostConfig({ profiles: { llm: { default: { endpoint: "x", model: "m" } } }, defaults: { llm: "default" } });
+    writeFileSync(opConfigPath, "{}");
+    importHostProfiles(state, hostConfigPath);
+    expect(readFileSync(hostConfigPath, "utf-8")).toBe(original);
+  });
+
+  it("imports nothing (and does not throw) when host has no profiles", () => {
+    seedHostConfig({ stashDir: "/home/u/akm" });
+    writeFileSync(opConfigPath, "{}");
+    expect(importHostProfiles(state, hostConfigPath).imported).toEqual([]);
+  });
+
+  it("throws (fails closed) when the personal config is missing", () => {
+    writeFileSync(opConfigPath, "{}");
+    expect(() => importHostProfiles(state, hostConfigPath)).toThrow();
+  });
+});

package/src/control-plane/akm-sources.ts

@@ -0,0 +1,234 @@
+/**
+ * Host ↔ Assistant AKM source wiring (control-plane logic — lives in lib).
+ *
+ * Implements the "symmetric writable secondary" design
+ * (docs/technical/akm-host-assistant-integration-proposal.md §8).
+ *
+ * Each akm instance keeps its OWN primary stash, data dir, and cache. Sharing
+ * is done purely by adding the other instance's stash as a *secondary* source
+ * in `config.sources[]`:
+ *   - The OpenPalm/container config gains a `host-akm` source → /host-stash
+ *     (the user's personal ~/akm, bind-mounted by the host-akm.compose.yml overlay).
+ *   - The personal config gains an `openpalm` source → OP_HOME/knowledge.
+ *
+ * VERIFIED against akm 0.8.0-rc.13:
+ *  - `SourceConfigEntrySchema` (config-schema.ts:259) accepts
+ *    { type, path?, url?, name?, enabled?, writable?, primary?, options?, wikiName? }.
+ *  - The indexer's `resolveSourceEntries` (search-source.ts:56) ALWAYS injects the
+ *    env-resolved primary stash (AKM_STASH_DIR) as sources[0], then appends
+ *    config.sources[] deduped by path. So a secondary entry can never strand or
+ *    displace the primary — provided we NEVER set `primary:true` and NEVER set
+ *    `config.stashDir`.
+ *  - Writes resolve to the primary unless an explicit `--target` is given
+ *    (write-source.ts) and `defaultWriteTarget` is left unset, so a writable
+ *    secondary is safe by construction.
+ *
+ * Invariants (enforced + unit-tested):
+ *  - Only ever appends/updates a NAMED source (idempotent upsert by name).
+ *  - NEVER sets `primary`, NEVER sets `defaultWriteTarget`, NEVER sets `stashDir`.
+ *  - Atomic 0600 writes.
+ *  - The OpenPalm config is parse-tolerant (we own it: corrupt → start from {}).
+ *  - The PERSONAL config FAILS CLOSED (corrupt/unreadable → throw, never overwrite
+ *    the user's file). This asymmetry is the host-data-loss guard.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "./fs-atomic.js";
+import type { ControlPlaneState } from "./types.js";
+
+/** Source entry name added to the OpenPalm/container config (points at /host-stash). */
+export const HOST_SOURCE_NAME = "host-akm";
+
+/** A filesystem source entry as akm persists it in config.sources[]. */
+type FilesystemSourceEntry = {
+  type: "filesystem";
+  path: string;
+  name: string;
+  writable: boolean;
+  enabled: boolean;
+};
+
+type AkmConfigObject = Record<string, unknown>;
+
+function readConfigTolerant(configPath: string): AkmConfigObject {
+  if (!existsSync(configPath)) return {};
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+    return parsed && typeof parsed === "object" ? (parsed as AkmConfigObject) : {};
+  } catch {
+    // We own the OpenPalm config — a corrupt file is recoverable by rewriting.
+    return {};
+  }
+}
+
+function readConfigFailClosed(configPath: string): AkmConfigObject {
+  // The PERSONAL config belongs to the user. If it doesn't exist there is
+  // nothing to share into and creating one silently would be surprising;
+  // if it's corrupt we must NOT overwrite it. Both cases throw.
+  if (!existsSync(configPath)) {
+    throw new Error(
+      `Personal akm config not found at ${configPath}; refusing to create it. ` +
+        `Run \`akm init\`/\`akm setup\` first, then enable host AKM sharing.`,
+    );
+  }
+  let text: string;
+  try {
+    text = readFileSync(configPath, "utf-8");
+  } catch (err) {
+    throw new Error(`Unable to read personal akm config at ${configPath}: ${(err as Error).message}`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(
+      `Personal akm config at ${configPath} is not valid JSON; refusing to overwrite it. ` +
+        `Fix the file by hand, then retry.`,
+    );
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`Personal akm config at ${configPath} is not a JSON object; refusing to overwrite it.`);
+  }
+  return parsed as AkmConfigObject;
+}
+
+/**
+ * Upsert a named filesystem source into `config.sources[]` by name. Idempotent.
+ * NEVER touches `primary`, `defaultWriteTarget`, or `stashDir`.
+ */
+function upsertSource(config: AkmConfigObject, entry: FilesystemSourceEntry): AkmConfigObject {
+  const sources = Array.isArray(config.sources) ? [...(config.sources as unknown[])] : [];
+  const idx = sources.findIndex(
+    (s) => s && typeof s === "object" && (s as Record<string, unknown>).name === entry.name,
+  );
+  if (idx >= 0) {
+    // Preserve any unrelated fields the user set (e.g. options), override ours.
+    sources[idx] = { ...(sources[idx] as Record<string, unknown>), ...entry };
+  } else {
+    sources.push(entry);
+  }
+  return { ...config, sources };
+}
+
+function removeSource(config: AkmConfigObject, name: string): AkmConfigObject {
+  if (!Array.isArray(config.sources)) return config;
+  const sources = (config.sources as unknown[]).filter(
+    (s) => !(s && typeof s === "object" && (s as Record<string, unknown>).name === name),
+  );
+  return { ...config, sources };
+}
+
+function assertNoPrimaryEscalation(entry: FilesystemSourceEntry): void {
+  // Defense in depth: the type forbids `primary`, but assert at runtime too —
+  // a secondary that became primary would change the write target.
+  if ((entry as Record<string, unknown>).primary !== undefined) {
+    throw new Error("akm-sources: refusing to write a source entry carrying `primary`.");
+  }
+}
+
+function openpalmConfigPath(state: ControlPlaneState): string {
+  return join(state.configDir, "akm", "config.json");
+}
+
+/**
+ * Container/OpenPalm side: add the personal stash (mounted at /host-stash) as a
+ * secondary source. Parse-tolerant (we own this config). Writable by default so
+ * the assistant can contribute back via an explicit `--target host-akm`.
+ */
+export function addHostStashToOpenpalmConfig(state: ControlPlaneState, writable = true): void {
+  const configPath = openpalmConfigPath(state);
+  const entry: FilesystemSourceEntry = {
+    type: "filesystem",
+    path: "/host-stash",
+    name: HOST_SOURCE_NAME,
+    writable,
+    enabled: true,
+  };
+  assertNoPrimaryEscalation(entry);
+  const config = readConfigTolerant(configPath);
+  const updated = upsertSource(config, entry);
+  writeFileAtomic(configPath, JSON.stringify(updated, null, 2), 0o600);
+}
+
+/**
+ * Remove the `host-akm` secondary source from the assistant config (disable
+ * sharing). Parse-tolerant; never touches the user's personal config (D1 —
+ * host sharing is assistant-reads-host only). Idempotent.
+ */
+export function removeHostAkmSource(state: ControlPlaneState): void {
+  const opPath = openpalmConfigPath(state);
+  const opConfig = readConfigTolerant(opPath);
+  writeFileAtomic(opPath, JSON.stringify(removeSource(opConfig, HOST_SOURCE_NAME), null, 2), 0o600);
+}
+
+/**
+ * Read-only snapshot import of the host's reusable akm config into the OpenPalm
+ * config. Reads the personal config READ-ONLY; never writes back to the host.
+ *
+ * ADDITIVE MERGE: existing OpenPalm values ALWAYS win — the host only fills gaps.
+ * A profile name, default selection, or embedding field that OpenPalm already has
+ * is never overwritten; host-only profiles/fields are added. Covers the
+ * LLM/agent/improve PROFILES (+ their `defaults.*`) and the top-level `embedding`
+ * connection. Returns which sections actually gained values.
+ *
+ * Writes the canonical akm 0.8.0 shape (profiles.* + defaults.* + embedding) —
+ * never the legacy top-level `llm` (see I-3). NEVER touches `sources`, `stashDir`,
+ * `registries`, or `installed`.
+ */
+export function importHostProfiles(
+  state: ControlPlaneState,
+  hostConfigPath: string,
+): { imported: string[] } {
+  const host = readConfigFailClosed(hostConfigPath);
+  const hostProfiles = (host.profiles as Record<string, unknown> | undefined) ?? {};
+  const hostDefaults = (host.defaults as Record<string, unknown> | undefined) ?? {};
+
+  const opPath = openpalmConfigPath(state);
+  const op = readConfigTolerant(opPath);
+  const opProfiles = (op.profiles as Record<string, unknown> | undefined) ?? {};
+  const opDefaults = (op.defaults as Record<string, unknown> | undefined) ?? {};
+
+  const imported: string[] = [];
+
+  // ADDITIVE MERGE — existing OpenPalm values always win; the host fills only
+  // gaps. Never overwrite a profile, default selection, or embedding field the
+  // operator/wizard already set. `imported` lists what was actually added.
+  const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+  // All three profile namespaces akm supports (config-schema.ts ProfilesSchema).
+  for (const ns of ["llm", "agent", "improve"] as const) {
+    if (isObj(hostProfiles[ns])) {
+      const existing = isObj(opProfiles[ns]) ? (opProfiles[ns] as Record<string, unknown>) : {};
+      // host first, existing last → existing wins; only host-only profile names are added.
+      const merged: Record<string, unknown> = { ...(hostProfiles[ns] as Record<string, unknown>), ...existing };
+      const added = Object.keys(merged).length - Object.keys(existing).length;
+      opProfiles[ns] = merged;
+      if (added > 0) imported.push(`profiles.${ns}`);
+    }
+    // Only adopt a host default selection when OpenPalm has none.
+    if (typeof hostDefaults[ns] === "string" && typeof opDefaults[ns] !== "string") {
+      opDefaults[ns] = hostDefaults[ns];
+      imported.push(`defaults.${ns}`);
+    }
+  }
+
+  // Top-level embedding connection (EmbeddingConnectionConfigSchema). Per-field
+  // additive: existing OpenPalm fields win; host fills only missing fields.
+  let embedding: Record<string, unknown> | undefined;
+  if (isObj(host.embedding)) {
+    const existing = isObj(op.embedding) ? (op.embedding as Record<string, unknown>) : {};
+    const merged: Record<string, unknown> = { ...(host.embedding as Record<string, unknown>), ...existing };
+    if (Object.keys(merged).length > Object.keys(existing).length) {
+      embedding = merged;
+      imported.push("embedding");
+    }
+  }
+
+  if (imported.length === 0) return { imported };
+
+  const updated: AkmConfigObject = { ...op, profiles: opProfiles, defaults: opDefaults };
+  if (embedding !== undefined) updated.embedding = embedding;
+  delete (updated as Record<string, unknown>).llm; // never persist the legacy key
+  writeFileAtomic(opPath, JSON.stringify(updated, null, 2), 0o600);
+  return { imported };
+}

package/src/control-plane/akm-user-env.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Tests for the akm user-env helpers (`env:user`).
+ *
+ * akm (>= 0.8.0) no longer manages individual env entries, so OpenPalm owns the
+ * `knowledge/env/user.env` file directly. Writes/deletes are plain atomic .env
+ * edits — no akm subprocess — so these tests run everywhere (no akm-on-PATH gate).
+ */
+import { describe, expect, it, beforeEach, afterEach } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, readFileSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ensureAkmUserEnv,
+  readUserEnvSync,
+  writeUserEnvKey,
+  deleteUserEnvKey,
+  userEnvPathSync,
+  AKM_USER_ENV_REF,
+  buildAkmEnv,
+  assertAkmEnvComplete,
+  AKM_ENV_KEYS,
+} from "./akm-user-env.js";
+import type { ControlPlaneState } from "./types.js";
+
+function makeState(homeDir: string): ControlPlaneState {
+  return {
+    homeDir,
+    configDir: join(homeDir, "config"),
+    stashDir: join(homeDir, "knowledge"),
+    workspaceDir: join(homeDir, "workspace"),
+    dataDir: join(homeDir, "data"),
+    stackDir: join(homeDir, "config", "stack"),
+    services: {},
+    artifacts: { compose: "" },
+    artifactMeta: [],
+  };
+}
+
+describe("akm user-env helpers", () => {
+  let homeDir: string;
+  let state: ControlPlaneState;
+
+  beforeEach(() => {
+    homeDir = mkdtempSync(join(tmpdir(), "openpalm-akm-env-"));
+    state = makeState(homeDir);
+    mkdirSync(state.stashDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(homeDir, { recursive: true, force: true });
+  });
+
+  it("ensureAkmUserEnv creates env/user.env (mode 0600) and returns its path", () => {
+    const path = ensureAkmUserEnv(state);
+    expect(path).toBe(userEnvPathSync(state));
+    expect(path).toBe(join(state.stashDir, "env", "user.env"));
+    expect(existsSync(path)).toBe(true);
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+  });
+
+  it("writeUserEnvKey upserts a key, readUserEnvSync reads it back", () => {
+    writeUserEnvKey(state, "TOKEN", "secret-9988");
+    expect(readUserEnvSync(state).TOKEN).toBe("secret-9988");
+
+    // Upsert replaces in place rather than appending a duplicate.
+    writeUserEnvKey(state, "TOKEN", "rotated");
+    const parsed = readUserEnvSync(state);
+    expect(parsed.TOKEN).toBe("rotated");
+    const lines = readFileSync(userEnvPathSync(state), "utf-8").split("\n").filter((l) => l.startsWith("TOKEN="));
+    expect(lines.length).toBe(1);
+  });
+
+  it("writeUserEnvKey single-quotes values with spaces/special chars (shell-source-safe, dotenv round-trips)", () => {
+    writeUserEnvKey(state, "TOKEN", "sk-simple123");
+    writeUserEnvKey(state, "OWNER", "Ada Lovelace");
+    writeUserEnvKey(state, "URL", "https://x.example/p?a=1&b=2");
+    writeUserEnvKey(state, "NOTE", "a#b$c");
+
+    // dotenv round-trip (what akm env run / the admin endpoint parse).
+    const parsed = readUserEnvSync(state);
+    expect(parsed.OWNER).toBe("Ada Lovelace");
+    expect(parsed.URL).toBe("https://x.example/p?a=1&b=2");
+    expect(parsed.NOTE).toBe("a#b$c");
+
+    // Raw lines: simple tokens stay bare; anything with spaces/shell-meta is
+    // POSIX single-quoted so the entrypoint's `set -a; . user.env` is safe
+    // (no word-splitting, no `&`/`$` interpretation, no injection).
+    const raw = readFileSync(userEnvPathSync(state), "utf-8");
+    expect(raw).toContain("TOKEN=sk-simple123\n");
+    expect(raw).toContain("OWNER='Ada Lovelace'\n");
+    expect(raw).toContain("URL='https://x.example/p?a=1&b=2'\n");
+  });
+
+  it("deleteUserEnvKey removes only the named key", () => {
+    writeUserEnvKey(state, "TOKEN_A", "value-a");
+    writeUserEnvKey(state, "TOKEN_B", "value-b");
+    deleteUserEnvKey(state, "TOKEN_A");
+    const parsed = readUserEnvSync(state);
+    expect(parsed.TOKEN_A).toBeUndefined();
+    expect(parsed.TOKEN_B).toBe("value-b");
+  });
+
+  it("deleteUserEnvKey is idempotent on a missing key", () => {
+    expect(() => deleteUserEnvKey(state, "NEVER_SET_KEY")).not.toThrow();
+  });
+
+  it("readUserEnvSync returns {} when no file exists yet", () => {
+    expect(readUserEnvSync(state)).toEqual({});
+  });
+});
+
+describe("AKM_USER_ENV_REF", () => {
+  it("exports the canonical akm ref string", () => {
+    expect(AKM_USER_ENV_REF).toBe("env:user");
+  });
+});
+
+describe("assertAkmEnvComplete (I-6 guard)", () => {
+  it("passes for the env produced by buildAkmEnv", () => {
+    const env = buildAkmEnv({ stashDir: "/k", configDir: "/c", dataDir: "/d" } as ControlPlaneState);
+    expect(() => assertAkmEnvComplete(env)).not.toThrow();
+  });
+
+  it("throws when any of the four AKM_* dirs is missing", () => {
+    for (const omit of AKM_ENV_KEYS) {
+      const env: NodeJS.ProcessEnv = {
+        AKM_STASH_DIR: "/s",
+        AKM_CONFIG_DIR: "/c",
+        AKM_CACHE_DIR: "/ca",
+        AKM_DATA_DIR: "/d",
+      };
+      delete env[omit];
+      expect(() => assertAkmEnvComplete(env)).toThrow(omit);
+    }
+  });
+
+  it("throws when a key is present but blank", () => {
+    expect(() =>
+      assertAkmEnvComplete({ AKM_STASH_DIR: "/s", AKM_CONFIG_DIR: "  ", AKM_CACHE_DIR: "/ca", AKM_DATA_DIR: "/d" }),
+    ).toThrow("AKM_CONFIG_DIR");
+  });
+});