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

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,38 @@ 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 (no stack.yml)", () => {
     expect(existsSync(join(SKELETON_DIR, "config", "stack", "core.compose.yml"))).toBe(true);
-    expect(existsSync(join(SKELETON_DIR, "config", "stack", "stack.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);
+    // stack.yml removed in 0.11.0 — addon enablement lives in stack.env.
+    expect(existsSync(join(SKELETON_DIR, "config", "stack", "stack.yml"))).toBe(false);
   });
 
-  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 +75,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 { SPEC_DEFAULTS } from "./defaults.js";
+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.
+ * Derive the system.env key-value pairs from the setup spec + defaults.
  * 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/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();
+  });
+});

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

@@ -0,0 +1,51 @@
+/**
+ * Raw file access for the Automations admin tab — a plain editor for the akm
+ * task files in the assistant tasks dir (/stash/tasks = knowledge/tasks).
+ *
+ * akm task files are YAML (`.yml`/`.yaml`) or markdown (`.md`). Names are always
+ * basenames within the tasks dir; the guard rejects path separators and `..`.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TASK_FILENAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}\.(ya?ml|md)$/;
+
+export function assertSafeTaskFilename(name: string): void {
+  if (!TASK_FILENAME_RE.test(name) || name.includes('..')) {
+    throw new Error(`Invalid task file name: ${name} (expected a .yml/.yaml/.md basename)`);
+  }
+}
+
+/** The assistant tasks dir for a given stash dir (knowledge). Created if absent. */
+export function resolveTasksDir(stashDir: string): string {
+  const dir = join(stashDir, 'tasks');
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export type TaskFileInfo = { name: string; size: number };
+
+/** List the task files (.yml/.yaml/.md) in the tasks dir, with byte sizes. */
+export function listTaskFiles(stashDir: string): TaskFileInfo[] {
+  const dir = resolveTasksDir(stashDir);
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && TASK_FILENAME_RE.test(e.name) && !e.name.includes('..'))
+    .map((e) => ({ name: e.name, size: statSync(join(dir, e.name)).size }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function readTaskFile(stashDir: string, name: string): string | null {
+  assertSafeTaskFilename(name);
+  const path = join(resolveTasksDir(stashDir), name);
+  return existsSync(path) ? readFileSync(path, 'utf-8') : null;
+}
+
+export function writeTaskFile(stashDir: string, name: string, content: string): void {
+  assertSafeTaskFilename(name);
+  writeFileSync(join(resolveTasksDir(stashDir), name), content, { mode: 0o644 });
+}
+
+export function removeTaskFile(stashDir: string, name: string): void {
+  assertSafeTaskFilename(name);
+  rmSync(join(resolveTasksDir(stashDir), name), { force: true });
+}

package/src/control-plane/types.ts

@@ -27,10 +27,9 @@ export type ArtifactMeta = {
 export type ControlPlaneState = {
   homeDir: string;
   configDir: string;
-  stashDir: string;      // homeDir/stash
+  stashDir: string;      // homeDir/knowledge
   workspaceDir: string;  // homeDir/workspace
-  cacheDir: string;      // homeDir/cache (regenerable/semi-persistent data)
-  stateDir: string;      // homeDir/state (service data + system state)
+  dataDir: string;       // homeDir/data (service data + operational files)
   stackDir: string;      // configDir/stack (compose runtime + stack config)
   services: Record<string, "running" | "stopped">;
   artifacts: {
@@ -48,4 +47,3 @@ export const CORE_SERVICES: CoreServiceName[] = [
   "assistant",
   "guardian",
 ];
-