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

package/src/control-plane/skeleton-guardrail.test.ts

@@ -15,9 +15,8 @@ const SKELETON_DIR = join(REPO_ROOT, ".openpalm");
 // Allowed top-level dirs in .openpalm/ — mirrors the OP_HOME runtime layout
 const ALLOWED_SOURCE_DIRS = new Set([
   "config",     // seed files for config/ (assistant, guardian, stack/, akm/)
-  "stash",      // stash source assets: skills/ and vaults/
-  "state",      // state/registry/ + empty service dirs (.gitkeep)
-  "cache",      // empty cache dirs (.gitkeep — regenerable at runtime)
+  "knowledge",      // knowledge source assets: skills/, env/, secrets/, tasks/
+  "data",       // empty service dirs (.gitkeep)
   "workspace",  // empty workspace dir (.gitkeep)
 ]);
 
@@ -37,25 +36,37 @@ describe("skeleton: .openpalm/ top-level directories", () => {
     expect(existsSync(join(SKELETON_DIR, "stack"))).toBe(false);
   });
 
-  test("registry/ no longer exists (moved to state/registry/)", () => {
+  test("registry/ no longer exists", () => {
     expect(existsSync(join(SKELETON_DIR, "registry"))).toBe(false);
   });
 
-  test("stash-seeds/ no longer exists (moved to stash/)", () => {
+  test("stash-seeds/ no longer exists (moved to knowledge/)", () => {
     expect(existsSync(join(SKELETON_DIR, "stash-seeds"))).toBe(false);
   });
 });
 
+// ── power-user helper scripts ─────────────────────────────────────────
+
+describe("skeleton: helper scripts", () => {
+  test("openpalm.sh and openpalm.ps1 ship at the skeleton root", () => {
+    expect(existsSync(join(SKELETON_DIR, "openpalm.sh"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "openpalm.ps1"))).toBe(true);
+  });
+});
+
 // ── config/ subdirectory ──────────────────────────────────────────────
 
 describe("skeleton: .openpalm/config/ structure", () => {
-  test("config/stack/ exists with core.compose.yml and stack.yml", () => {
+  test("config/stack/ exists with fixed compose files and stack.yml", () => {
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "core.compose.yml"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "services.compose.yml"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "channels.compose.yml"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "custom.compose.yml"))).toBe(true);
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "stack.yml"))).toBe(true);
   });
 
-  test("config/stack/addons/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "config", "stack", "addons"))).toBe(true);
+  test("config/stack/addons/ does not exist", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "addons"))).toBe(false);
   });
 
   test("config/akm/ exists", () => {
@@ -63,86 +74,84 @@ describe("skeleton: .openpalm/config/ structure", () => {
   });
 
   test("config/assistant/ has seed files", () => {
-    expect(existsSync(join(SKELETON_DIR, "config", "assistant", "opencode.json"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "config", "assistant", "opencode.jsonc"))).toBe(true);
   });
-});
-
-// ── state/registry/ subdirectory ─────────────────────────────────────
 
-describe("skeleton: .openpalm/state/registry/ structure", () => {
-  test("state/registry/addons/ exists with addon subdirectories", () => {
-    const addonsDir = join(SKELETON_DIR, "state", "registry", "addons");
-    expect(existsSync(addonsDir)).toBe(true);
-    const addons = readdirSync(addonsDir);
-    expect(addons).toContain("chat");
-    expect(addons).toContain("api");
-    expect(addons).toContain("discord");
+  test("config/guardian/ has the OpenCode global config (mounted at /etc/opencode)", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "guardian", "opencode.jsonc"))).toBe(true);
   });
 
-  test("state/registry/automations/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "registry", "automations"))).toBe(true);
+  test("config/guardian/ ships the message-moderation instructions", () => {
+    expect(existsSync(join(SKELETON_DIR, "config", "guardian", "instructions", "moderation.md"))).toBe(true);
   });
+});
 
-  test("each addon has compose.yml", () => {
-    const addonsDir = join(SKELETON_DIR, "state", "registry", "addons");
-    const addons = readdirSync(addonsDir).filter(e => {
-      try { return statSync(join(addonsDir, e)).isDirectory(); } catch { return false; }
-    });
-    for (const addon of addons) {
-      expect(existsSync(join(addonsDir, addon, "compose.yml"))).toBe(true);
-    }
+// ── no runtime registry ───────────────────────────────────────────────
+
+describe("skeleton: no runtime registry", () => {
+  test("data/registry/ does not exist", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "registry"))).toBe(false);
   });
 });
 
-// ── stash/ subdirectory ───────────────────────────────────────────────
+// ── knowledge/ subdirectory ───────────────────────────────────────────────
+
+describe("skeleton: .openpalm/knowledge/ structure", () => {
+  test("knowledge/skills/ exists with config-diagnostics skill", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "skills", "config-diagnostics", "SKILL.md"))).toBe(true);
+  });
 
-describe("skeleton: .openpalm/stash/ structure", () => {
-  test("stash/skills/ exists with config-diagnostics skill", () => {
-    expect(existsSync(join(SKELETON_DIR, "stash", "skills", "config-diagnostics", "SKILL.md"))).toBe(true);
+  test("knowledge/env/ exists with user.env seed", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "env", "user.env"))).toBe(true);
   });
 
-  test("stash/vaults/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "stash", "vaults"))).toBe(true);
+  test("knowledge/secrets/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "secrets"))).toBe(true);
   });
 
-  test("stash/tasks/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "stash", "tasks"))).toBe(true);
+  test("knowledge/tasks/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "knowledge", "tasks"))).toBe(true);
   });
 });
 
-// ── state/ service dirs ───────────────────────────────────────────────
+// ── data/ service dirs ────────────────────────────────────────────────
 
-describe("skeleton: .openpalm/state/ service directories", () => {
-  const serviceDirs = ["assistant", "admin", "guardian", "logs", "backups"];
+describe("skeleton: .openpalm/data/ service directories", () => {
+  const serviceDirs = ["assistant", "guardian"];
 
   for (const dir of serviceDirs) {
-    test(`state/${dir}/ exists`, () => {
-      expect(existsSync(join(SKELETON_DIR, "state", dir))).toBe(true);
+    test(`data/${dir}/ exists`, () => {
+      expect(existsSync(join(SKELETON_DIR, "data", dir))).toBe(true);
     });
   }
 
-  test("state/akm/data/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "akm", "data"))).toBe(true);
+  test("data/akm/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "akm"))).toBe(true);
   });
 
-  test("state/akm/state/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "akm", "state"))).toBe(true);
+  test("data/akm/cache and data/akm/data exist", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "akm", "cache"))).toBe(true);
+    expect(existsSync(join(SKELETON_DIR, "data", "akm", "data"))).toBe(true);
   });
 
-  test("state/logs/opencode/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "state", "logs", "opencode"))).toBe(true);
+  test("data/logs/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "logs"))).toBe(true);
   });
 });
 
-// ── cache/ and workspace/ ─────────────────────────────────────────────
+// ── data/rollback and workspace/ ──────────────────────────────────────
+
+describe("skeleton: .openpalm/data/rollback and workspace/", () => {
+  test("cache/ does not exist in the skeleton", () => {
+    expect(existsSync(join(SKELETON_DIR, "cache"))).toBe(false);
+  });
 
-describe("skeleton: .openpalm/cache/ and workspace/", () => {
-  test("cache/akm/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "cache", "akm"))).toBe(true);
+  test("data/backups/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "backups"))).toBe(true);
   });
 
-  test("cache/rollback/ exists", () => {
-    expect(existsSync(join(SKELETON_DIR, "cache", "rollback"))).toBe(true);
+  test("data/rollback/ exists", () => {
+    expect(existsSync(join(SKELETON_DIR, "data", "rollback"))).toBe(true);
   });
 
   test("workspace/ exists", () => {

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

@@ -4,8 +4,6 @@ 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,34 +16,41 @@ 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_HOST_UI_PORT).toBe("3880");
+  });
+
+  test("does not emit the retired OP_ADMIN_PORT/OP_ADMIN_OPENCODE_PORT vars", () => {
+    const result = deriveSystemEnvFromSpec("/home/op");
+    expect(result.OP_ADMIN_PORT).toBeUndefined();
+    expect(result.OP_ADMIN_OPENCODE_PORT).toBeUndefined();
   });
 
   test("does not emit OP_GUARDIAN_PORT (guardian is network-only, no host mapping)", () => {
-    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, "/home/op");
+    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();
   });
@@ -57,61 +62,93 @@ describe("deriveSystemEnvFromSpec", () => {
     // hard-coded constant.
     if (process.platform === "win32") return;
     const expected = statSync(tempDir);
-    const result = deriveSystemEnvFromSpec(MINIMAL_SPEC, tempDir);
+    const result = deriveSystemEnvFromSpec(tempDir);
     expect(result.OP_UID).toBe(String(expected.uid));
     expect(result.OP_GID).toBe(String(expected.gid));
   });
 });
 
 describe("writeVoiceVars", () => {
+  // writeVoiceVars takes a stackDir (<home>/config/stack) and writes the env
+  // to <home>/knowledge/env/stack.env. Build that layout per test.
+  let stackDir = "";
+  let stackEnv = "";
+  beforeEach(() => {
+    stackDir = join(tempDir, "config", "stack");
+    stackEnv = join(tempDir, "knowledge", "env", "stack.env");
+    mkdirSync(stackDir, { recursive: true });
+    mkdirSync(join(tempDir, "knowledge", "env"), { recursive: true });
+  });
+
   test("writes TTS vars to stack.env", () => {
-    mkdirSync(tempDir, { recursive: true });
-    writeFileSync(join(tempDir, "stack.env"), "# stack env\n");
+    writeFileSync(stackEnv, "# stack env\n");
 
     writeVoiceVars({
       tts: { baseURL: "https://tts.example.com/v1", model: "tts-1", voice: "alloy" },
-    }, tempDir);
+    }, stackDir);
 
-    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     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", () => {
-    mkdirSync(tempDir, { recursive: true });
-    writeFileSync(join(tempDir, "stack.env"), "# stack env\n");
+    writeFileSync(stackEnv, "# stack env\n");
 
     writeVoiceVars({
       stt: { baseURL: "https://stt.example.com/v1", model: "whisper-1", language: "en" },
-    }, tempDir);
+    }, stackDir);
 
-    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     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", () => {
-    mkdirSync(tempDir, { recursive: true });
-
     writeVoiceVars({
       tts: { baseURL: "https://tts.example.com/v1", model: "tts-1" },
-    }, tempDir);
+    }, stackDir);
 
-    const content = readFileSync(join(tempDir, "stack.env"), "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     expect(content).toContain("OP_TTS_BASE_URL=https://tts.example.com/v1");
   });
 
   test("is a no-op when no vars are provided", () => {
-    mkdirSync(tempDir, { recursive: true });
-    const stackEnvPath = join(tempDir, "stack.env");
-    writeFileSync(stackEnvPath, "EXISTING=value\n");
+    writeFileSync(stackEnv, "EXISTING=value\n");
 
-    writeVoiceVars({}, tempDir);
+    writeVoiceVars({}, stackDir);
 
     // File should be unchanged
-    const content = readFileSync(stackEnvPath, "utf-8");
+    const content = readFileSync(stackEnv, "utf-8");
     expect(content).toBe("EXISTING=value\n");
   });
+
+  test("auto-fills baseURL/model/voice for openpalm-voice engine (setup wizard path)", () => {
+    // Reproduces the bug: setup wizard sends engine only, no baseURL.
+    // writeVoiceVars must fill in OP_TTS_BASE_URL / OP_STT_BASE_URL.
+    writeVoiceVars({
+      tts: { engine: "openpalm-voice" },
+      stt: { engine: "openpalm-voice" },
+    }, stackDir);
+
+    const content = readFileSync(stackEnv, "utf-8");
+    expect(content).toContain("OP_TTS_ENGINE=openpalm-voice");
+    expect(content).toMatch(/OP_TTS_BASE_URL=http:\/\/127\.0\.0\.1:\d+/);
+    expect(content).toContain("OP_TTS_MODEL=kokoro");
+    expect(content).toContain("OP_TTS_VOICE=bf_isabella");
+    expect(content).toContain("OP_STT_ENGINE=openpalm-voice");
+    expect(content).toMatch(/OP_STT_BASE_URL=http:\/\/127\.0\.0\.1:\d+/);
+    expect(content).toContain("OP_STT_MODEL=whisper-1");
+  });
+
+  test("does not overwrite explicit baseURL when engine is openpalm-voice", () => {
+    writeVoiceVars({
+      tts: { engine: "openpalm-voice", baseURL: "http://192.168.1.50:8880" },
+    }, stackDir);
+
+    const content = readFileSync(stackEnv, "utf-8");
+    expect(content).toContain("OP_TTS_BASE_URL=http://192.168.1.50:8880");
+  });
 });

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

@@ -5,20 +5,19 @@
  * 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 { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { mergeEnvContent } from "./env.js";
 import { resolveOperatorIds } from "./operator-ids.js";
+import { assertNoSecretLikeStackEnvKeys } from './secrets.js';
+import { stackEnvPathFromStackDir } from './paths.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> {
+export function deriveSystemEnvFromSpec(homeDir: string): Record<string, string> {
   const ports = SPEC_DEFAULTS.ports;
   const image = SPEC_DEFAULTS.image;
 
@@ -43,12 +42,9 @@ export function deriveSystemEnvFromSpec(
   // 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_HOST_UI_PORT"] = String(ports.hostUi);
   result["OP_ASSISTANT_SSH_PORT"] = String(ports.assistantSsh);
 
-  void spec; // spec reserved for future use; ports/image come from SPEC_DEFAULTS
-
   return result;
 }
 
@@ -75,13 +71,47 @@ export type VoiceVarsConfig = {
   };
 };
 
+// Authoritative defaults for the bundled openpalm/voice addon.
+const OPENPALM_VOICE_TTS_MODEL = "kokoro";
+const OPENPALM_VOICE_STT_MODEL = "whisper-1";
+const OPENPALM_VOICE_DEFAULT_VOICE = "bf_isabella";
+
+function openpalmVoiceBaseURL(): string {
+  const raw = (process.env["OP_VOICE_PORT_HOST"] ?? "").trim();
+  const n = raw ? Number(raw) : NaN;
+  const port = Number.isFinite(n) && n > 0 ? n : 8880;
+  return `http://127.0.0.1:${port}`;
+}
+
+/**
+ * For `engine === 'openpalm-voice'`, fill in baseURL/model/voice with the
+ * addon's preset defaults when not already provided by the caller.
+ * Mutates the section in place.
+ */
+function applyOpenPalmVoicePreset(
+  section: NonNullable<VoiceVarsConfig["tts"]> | NonNullable<VoiceVarsConfig["stt"]>,
+  kind: "tts" | "stt"
+): void {
+  if (section.engine !== "openpalm-voice") return;
+  if (!section.baseURL?.trim()) section.baseURL = openpalmVoiceBaseURL();
+  if (!section.model?.trim()) {
+    section.model = kind === "tts" ? OPENPALM_VOICE_TTS_MODEL : OPENPALM_VOICE_STT_MODEL;
+  }
+  if (kind === "tts" && !(section as NonNullable<VoiceVarsConfig["tts"]>).voice?.trim()) {
+    (section as NonNullable<VoiceVarsConfig["tts"]>).voice = OPENPALM_VOICE_DEFAULT_VOICE;
+  }
+}
+
 /**
  * Write TTS/STT env vars to stack.env for the voice channel container.
  * `engine` always writes (even if it's the only field) so picking an
  * engine without filling in URL/model still persists.
+ * For `engine === 'openpalm-voice'`, missing baseURL/model/voice are
+ * auto-filled from the addon's preset so setup wizard callers don't need
+ * to know the defaults.
  */
 export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void {
-  const stackEnvPath = `${stackDir}/stack.env`;
+  const stackEnvPath = stackEnvPathFromStackDir(stackDir);
   const base = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
   const vars: Record<string, string> = {};
 
@@ -90,7 +120,12 @@ export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void
   // 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;
+  const tts = config.tts ? { ...config.tts } : undefined;
+  const stt = config.stt ? { ...config.stt } : undefined;
+
+  if (tts) applyOpenPalmVoicePreset(tts, "tts");
+  if (stt) applyOpenPalmVoicePreset(stt, "stt");
+
   if (tts?.enabled !== false) {
     if (tts?.engine) vars["OP_TTS_ENGINE"] = tts.engine;
     if (tts?.provider) vars["OP_TTS_PROVIDER"] = tts.provider;
@@ -107,10 +142,12 @@ export function writeVoiceVars(config: VoiceVarsConfig, stackDir: string): void
   }
 
   if (Object.keys(vars).length === 0) return;
+  assertNoSecretLikeStackEnvKeys(vars);
 
   let content = mergeEnvContent(base, vars, {
     sectionHeader: "# ── Voice Channel (TTS/STT) ──────────────────────────────────────────",
   });
   if (!content.endsWith("\n")) content += "\n";
+  mkdirSync(dirname(stackEnvPath), { recursive: true, mode: 0o700 });
   writeFileSync(stackEnvPath, content, { mode: 0o600 });
 }

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";
 
@@ -37,12 +36,16 @@ describe("readStackSpec / writeStackSpec round-trip", () => {
     expect(read!.version).toBe(2);
   });
 
+  it("round-trips enabled addons", () => {
+    writeStackSpec(configDir, { version: 2, addons: ['chat', 'api'] });
+    expect(readStackSpec(configDir)).toEqual({ version: 2, addons: ['api', 'chat'] });
+  });
+
   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", () => {
@@ -79,16 +82,17 @@ describe("readStackSpec edge cases", () => {
     expect(spec).not.toBeNull();
     expect(spec!.version).toBe(2);
   });
-});
-
-// ── stackSpecPath / STACK_SPEC_FILENAME ──────────────────────────────────
 
-describe("stackSpecPath", () => {
-  it("returns stackDir/stack.yml", () => {
-    expect(stackSpecPath("/foo/config/stack")).toBe("/foo/config/stack/stack.yml");
+  it("ignores malformed addon names", () => {
+    writeFileSync(join(configDir, STACK_SPEC_FILENAME), "version: 2\naddons:\n  - chat\n  - ../bad\n  - API\n");
+    expect(readStackSpec(configDir)).toEqual({ version: 2, addons: ['chat'] });
   });
+});
+
+// ── 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

@@ -14,8 +14,11 @@ import { stringify as yamlStringify, parse as yamlParse } from "yaml";
 
 export type StackSpec = {
   version: 2;
+  addons?: string[];
 };
 
+const ADDON_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
 // ── Constants ───────────────────────────────────────────────────────────
 
 export const STACK_SPEC_FILENAME = "stack.yml";
@@ -23,9 +26,7 @@ export const STACK_SPEC_FILENAME = "stack.yml";
 export const SPEC_DEFAULTS = {
   ports: {
     assistant: 3800,
-    admin: 3880,
-    adminOpencode: 3881,
-    guardian: 3899,
+    hostUi: 3880,
     assistantSsh: 2222,
   },
   image: {
@@ -36,14 +37,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 +48,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;
@@ -63,5 +60,29 @@ export function readStackSpec(configDir: string): StackSpec | null {
   if (typeof raw !== "object" || raw === null) return null;
   const obj = raw as Record<string, unknown>;
   if (obj.version !== 2) return null;
-  return { version: 2 };
+  const spec: StackSpec = { version: 2 };
+  if (Array.isArray(obj.addons)) {
+    const addons = obj.addons
+      .filter((value): value is string => typeof value === 'string' && ADDON_NAME_RE.test(value))
+      .filter((value, index, all) => all.indexOf(value) === index)
+      .sort();
+    if (addons.length > 0) spec.addons = addons;
+  }
+  return spec;
+}
+
+export function listStackSpecAddons(configDir: string): string[] {
+  return readStackSpec(configDir)?.addons ?? [];
+}
+
+export function setStackSpecAddon(configDir: string, name: string, enabled: boolean): void {
+  if (!ADDON_NAME_RE.test(name)) throw new Error(`Invalid addon name: ${name}`);
+  const current = readStackSpec(configDir) ?? { version: 2 };
+  const addons = new Set(current.addons ?? []);
+  if (enabled) addons.add(name);
+  else addons.delete(name);
+  const next: StackSpec = { version: 2 };
+  const sorted = [...addons].sort();
+  if (sorted.length > 0) next.addons = sorted;
+  writeStackSpec(configDir, next);
 }

package/src/control-plane/task-files.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import {
+  resolveTasksDir, listTaskFiles, readTaskFile, writeTaskFile, removeTaskFile, assertSafeTaskFilename,
+} from './task-files.js';
+
+let stashDir = '';
+
+beforeEach(() => { stashDir = mkdtempSync(join(tmpdir(), 'op-tasks-')); });
+afterEach(() => { rmSync(stashDir, { recursive: true, force: true }); });
+
+describe('task-files', () => {
+  it('lists only .yml/.yaml/.md files with sizes', () => {
+    const dir = resolveTasksDir(stashDir);
+    writeFileSync(join(dir, 'health-check.yml'), 'enabled: false\n');
+    writeFileSync(join(dir, 'notes.md'), '# notes\n');
+    writeFileSync(join(dir, 'ignore.txt'), 'x');
+    const files = listTaskFiles(stashDir);
+    const names = files.map((f) => f.name);
+    expect(names).toContain('health-check.yml');
+    expect(names).toContain('notes.md');
+    expect(names).not.toContain('ignore.txt');
+    expect(files.find((f) => f.name === 'health-check.yml')!.size).toBe('enabled: false\n'.length);
+  });
+
+  it('reads, writes (0644), and removes a task file', () => {
+    writeTaskFile(stashDir, 'my-task.yml', "schedule: '0 9 * * *'\nenabled: true\n");
+    expect(statSync(join(resolveTasksDir(stashDir), 'my-task.yml')).mode & 0o777).toBe(0o644);
+    expect(readTaskFile(stashDir, 'my-task.yml')).toContain('enabled: true');
+    removeTaskFile(stashDir, 'my-task.yml');
+    expect(readTaskFile(stashDir, 'my-task.yml')).toBeNull();
+  });
+
+  it('rejects traversal and non-task extensions', () => {
+    expect(() => assertSafeTaskFilename('../escape.yml')).toThrow();
+    expect(() => assertSafeTaskFilename('a/b.yml')).toThrow();
+    expect(() => assertSafeTaskFilename('secrets.txt')).toThrow();
+    expect(() => assertSafeTaskFilename('config.json')).toThrow();
+    expect(() => assertSafeTaskFilename('ok.yml')).not.toThrow();
+    expect(() => assertSafeTaskFilename('ok.yaml')).not.toThrow();
+    expect(() => assertSafeTaskFilename('ok.md')).not.toThrow();
+  });
+});