openpalm 0.10.2 → 0.11.0-beta.2

package/src/install-flow.test.ts

@@ -20,13 +20,13 @@ import {
 import { tmpdir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parse as yamlParse } from 'yaml';
-import { readStackSpec } from '@openpalm/lib';
+import { readStackSpec, parseEnvFile, expandEnvVars } from '@openpalm/lib';
 
 // ── Helpers ───────────────────────────────────────────────────────────────
 
 const REPO_ROOT = resolve(import.meta.dir, '../../..');
 const OPENPALM_SRC = join(REPO_ROOT, '.openpalm');
-const ASSISTANT_SRC = join(REPO_ROOT, 'core/assistant/opencode');
+const ASSISTANT_SRC = join(OPENPALM_SRC, 'config', 'assistant');
 const SKIP_INSTALL_FLOW_IN_CI = process.env.CI === 'true';
 
 /** Copy a directory tree using cp -a (preserves structure, fast). */
@@ -39,42 +39,28 @@ function cpTree(src: string, dest: string): void {
 /** Seed the OP_HOME directory from the local repo (no network). */
 function seedFromLocal(homeDir: string, enabledAddons: string[] = []): void {
   const configDir = join(homeDir, 'config');
-  const vaultDir = join(homeDir, 'vault');
-  const dataDir = join(homeDir, 'data');
+  const stateDir = join(homeDir, 'state');
+  const stackDir = join(configDir, 'stack');
 
-  // stack/ — seed core compose only
-  mkdirSync(join(homeDir, 'stack'), { recursive: true });
-  Bun.spawnSync(['cp', join(OPENPALM_SRC, 'stack', 'core.compose.yml'), join(homeDir, 'stack', 'core.compose.yml')]);
+  // config/stack/ — seed core compose only
+  mkdirSync(stackDir, { recursive: true });
+  Bun.spawnSync(['cp', join(OPENPALM_SRC, 'config', 'stack', 'core.compose.yml'), join(stackDir, 'core.compose.yml')]);
 
-  // registry/ — shipped catalog source
-  cpTree(join(OPENPALM_SRC, 'registry', 'addons'), join(homeDir, 'registry', 'addons'));
-  cpTree(join(OPENPALM_SRC, 'registry', 'automations'), join(homeDir, 'registry', 'automations'));
+  // state/registry/ — shipped catalog source
+  cpTree(join(OPENPALM_SRC, 'state', 'registry', 'addons'), join(stateDir, 'registry', 'addons'));
+  cpTree(join(OPENPALM_SRC, 'state', 'registry', 'automations'), join(stateDir, 'registry', 'automations'));
 
-  // stack/addons/ — enabled runtime overlays only
+  // config/stack/addons/ — enabled runtime overlays only
   for (const addon of enabledAddons) {
-    cpTree(join(OPENPALM_SRC, 'registry', 'addons', addon), join(homeDir, 'stack', 'addons', addon));
+    cpTree(join(OPENPALM_SRC, 'state', 'registry', 'addons', addon), join(stackDir, 'addons', addon));
   }
 
-  // config/automations/ — enabled only (start empty)
-  mkdirSync(join(configDir, 'automations'), { recursive: true });
-
-  // vault/ — schemas only
-  for (const sub of ['user', 'stack']) {
-    const srcDir = join(OPENPALM_SRC, 'vault', sub);
-    const destDir = join(vaultDir, sub);
-    mkdirSync(destDir, { recursive: true });
-    if (existsSync(srcDir)) {
-      for (const f of readdirSync(srcDir)) {
-        if (f.endsWith('.schema')) {
-          const content = readFileSync(join(srcDir, f));
-          Bun.spawnSync(['cp', join(srcDir, f), join(destDir, f)]);
-        }
-      }
-    }
-  }
+  // stash/tasks/ — active AKM task files (populated by setup)
+  mkdirSync(join(homeDir, 'stash', 'tasks'), { recursive: true });
 
-  // data/assistant/ — opencode config
-  const assistantDir = join(dataDir, 'assistant');
+  // config/assistant/ — opencode project config (opencode.jsonc, openpalm.md, system.md)
+  // OPENCODE_CONFIG_DIR points at this directory inside the container.
+  const assistantDir = join(configDir, 'assistant');
   mkdirSync(assistantDir, { recursive: true });
   if (existsSync(ASSISTANT_SRC)) {
     for (const f of readdirSync(ASSISTANT_SRC)) {
@@ -83,31 +69,32 @@ function seedFromLocal(homeDir: string, enabledAddons: string[] = []): void {
   }
 
   // Seed file-based volume mount targets (CLI bootstrapInstall does this)
-  const stackVault = join(vaultDir, 'stack');
-  mkdirSync(stackVault, { recursive: true });
-  if (!existsSync(join(stackVault, 'guardian.env'))) {
-    Bun.spawnSync(['touch', join(stackVault, 'guardian.env')]);
+  mkdirSync(stackDir, { recursive: true });
+  if (!existsSync(join(stackDir, 'guardian.env'))) {
+    Bun.spawnSync(['touch', join(stackDir, 'guardian.env')]);
   }
-  if (!existsSync(join(stackVault, 'auth.json'))) {
-    writeFileSync(join(stackVault, 'auth.json'), '{}\n');
+  if (!existsSync(join(configDir, 'auth.json'))) {
+    writeFileSync(join(configDir, 'auth.json'), '{}\n');
   }
 
   // Create required directories
   for (const dir of [
     configDir,
     join(configDir, 'assistant'),
-    join(configDir, 'guardian'),
-    join(vaultDir, 'user'),
-    join(vaultDir, 'stack'),
-    dataDir,
-    join(dataDir, 'admin'),
-    join(dataDir, 'memory'),
-    join(dataDir, 'guardian'),
-    join(dataDir, 'stash'),
-    join(dataDir, 'workspace'),
-    join(homeDir, 'logs'),
-    join(homeDir, 'logs/opencode'),
-    join(homeDir, 'backups'),
+    join(configDir, 'akm'),
+    stackDir,
+    join(stackDir, 'addons'),
+    stateDir,
+    join(stateDir, 'assistant'),
+    join(stateDir, 'admin'),
+    join(stateDir, 'guardian'),
+    join(homeDir, 'stash'),
+    join(homeDir, 'workspace'),
+    join(homeDir, 'cache'),
+    join(homeDir, 'cache', 'akm'),
+    join(stateDir, 'logs'),
+    join(stateDir, 'logs', 'opencode'),
+    join(stateDir, 'backups'),
   ]) {
     mkdirSync(dir, { recursive: true });
   }
@@ -116,13 +103,9 @@ function seedFromLocal(homeDir: string, enabledAddons: string[] = []): void {
 function makeSetupSpec(): Record<string, unknown> {
   return {
     version: 2,
-    capabilities: {
-      llm: 'ollama/qwen2.5-coder:3b',
-      embeddings: { provider: 'ollama', model: 'nomic-embed-text:latest', dims: 768 },
-      memory: { userId: 'testuser', customInstructions: '' },
-      slm: 'ollama/qwen2.5-coder:3b',
-    },
-    security: { adminToken: 'test-admin-token-12345' },
+    llm: { provider: 'ollama', model: 'qwen2.5-coder:3b', baseUrl: 'http://host.docker.internal:11434' },
+    embedding: { provider: 'ollama', model: 'nomic-embed-text:latest', dims: 768, baseUrl: 'http://host.docker.internal:11434' },
+    security: { uiLoginPassword: 'test-admin-token-12345' },
     owner: { name: 'Test', email: 'test@test.com' },
     connections: [{
       id: 'ollama',
@@ -134,22 +117,6 @@ function makeSetupSpec(): Record<string, unknown> {
   };
 }
 
-/** Parse env vars from stack.env for compose variable substitution. */
-function parseEnvFile(path: string): Record<string, string> {
-  const vars: Record<string, string> = {};
-  if (!existsSync(path)) return vars;
-  for (const line of readFileSync(path, 'utf-8').split('\n')) {
-    const m = line.match(/^(?:export\s+)?([A-Z_][A-Z0-9_]*)=(.*)$/);
-    if (m) vars[m[1]] = m[2];
-  }
-  return vars;
-}
-
-/** Resolve ${VAR:-default} patterns in a string. */
-function resolveVars(str: string, vars: Record<string, string>): string {
-  return str.replace(/\$\{([^}:]+)(?::-([^}]*))?\}/g, (_, name, def) => vars[name] ?? def ?? '');
-}
-
 /** Extract all host-side volume mount paths from compose files. */
 function extractVolumeMountPaths(
   composeFiles: string[],
@@ -166,10 +133,10 @@ function extractVolumeMountPaths(
       for (const vol of svc.volumes) {
         const raw = typeof vol === 'string' ? vol.split(':')[0] : (vol?.source ?? '');
         if (!raw || typeof raw !== 'string') continue;
-        const resolved = resolveVars(raw, vars);
+        const resolved = expandEnvVars(raw, vars);
         if (!resolved.startsWith('/')) continue;
         const basename = resolved.split('/').pop() ?? '';
-        const isFile = basename.includes('.') && !basename.startsWith('.');
+        const isFile = basename.includes('.');
         results.push({ path: resolved, isFile });
       }
     }
@@ -191,13 +158,13 @@ describe('install flow — tier 1 (file validation)', () => {
     if (homeDir) rmSync(homeDir, { recursive: true, force: true });
   });
 
-  tier1Test('seed + performSetup produces complete file structure for admin+chat', async () => {
+  tier1Test('seed + performSetup produces complete file structure for chat addon', async () => {
     homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
     process.env.OP_HOME = homeDir;
-    process.env.OP_WORK_DIR = join(homeDir, 'data/workspace');
+    process.env.OP_WORK_DIR = join(homeDir, 'workspace');
 
     // Step 1: Seed from local .openpalm/
-    seedFromLocal(homeDir, ['admin', 'chat']);
+    seedFromLocal(homeDir, ['chat']);
 
     // Step 2: Run performSetup
     const { performSetup } = await import('@openpalm/lib');
@@ -207,76 +174,62 @@ describe('install flow — tier 1 (file validation)', () => {
 
     // ── Validate stack.yml via lib parser ─────────────────────────
     const configDir = join(homeDir, 'config');
-    const stackSpec = readStackSpec(configDir);
+    const stackSpec = readStackSpec(join(homeDir, 'config', 'stack'));
     expect(stackSpec).not.toBeNull();
     expect(stackSpec!.version).toBe(2);
-    expect(stackSpec!.capabilities.llm).toBe('ollama/qwen2.5-coder:3b');
+    // stack.yml carries only { version: 2 } — LLM config lives in akm config.json
+    const akmConfigPath = join(homeDir, 'config/akm/config.json');
+    expect(existsSync(akmConfigPath)).toBe(true);
+    const akmConfig = JSON.parse(readFileSync(akmConfigPath, 'utf-8'));
+    expect(akmConfig.llm?.provider).toBe('ollama');
+    expect(akmConfig.llm?.model).toBe('qwen2.5-coder:3b');
 
     // ── Validate compose files exist ─────────────────────────────────
-    expect(existsSync(join(homeDir, 'stack/core.compose.yml'))).toBe(true);
-    expect(existsSync(join(homeDir, 'stack/addons/admin/compose.yml'))).toBe(true);
-    expect(existsSync(join(homeDir, 'stack/addons/chat/compose.yml'))).toBe(true);
+    expect(existsSync(join(homeDir, 'config/stack/core.compose.yml'))).toBe(true);
+    expect(existsSync(join(homeDir, 'config/stack/addons/chat/compose.yml'))).toBe(true);
 
-    expect(existsSync(join(homeDir, 'registry/addons/admin/compose.yml'))).toBe(true);
-    expect(existsSync(join(homeDir, 'registry/addons/chat/compose.yml'))).toBe(true);
-    expect(existsSync(join(homeDir, 'registry/automations/cleanup-logs.yml'))).toBe(true);
+    expect(existsSync(join(homeDir, 'state/registry/addons/chat/compose.yml'))).toBe(true);
+    expect(existsSync(join(homeDir, 'state/registry/automations/cleanup-logs.md'))).toBe(true);
 
     // ── Validate vault files are regular files (not directories) ─────
+    // Note: vault/user/user.env is no longer
+    // seeded — user-managed env secrets live in akm vault:user
+    // (data/stash/vaults/user.env) and the assistant entrypoint sources
+    // it directly. The compose env_file mount for vault/user/user.env
+    // has been removed too.
     for (const relPath of [
-      'vault/stack/stack.env',
-      'vault/stack/guardian.env',
-      'vault/stack/auth.json',
-      'vault/user/user.env',
+      'config/stack/stack.env',
+      'config/stack/guardian.env',
+      'config/auth.json',
     ]) {
       const fullPath = join(homeDir, relPath);
       expect(existsSync(fullPath)).toBe(true);
       expect(statSync(fullPath).isFile()).toBe(true);
     }
 
-    // ── Validate vault schemas ───────────────────────────────────────
-    for (const relPath of [
-      'vault/user/user.env.schema',
-      'vault/stack/stack.env.schema',
-    ]) {
-      const fullPath = join(homeDir, relPath);
-      expect(existsSync(fullPath)).toBe(true);
-      expect(statSync(fullPath).isFile()).toBe(true);
-      expect(readFileSync(fullPath, 'utf-8').length).toBeGreaterThan(0);
-    }
-
     // ── Validate all volume mount targets exist as user-owned ────────
     const stackEnvVars = {
-      ...parseEnvFile(join(homeDir, 'vault/stack/stack.env')),
+      ...parseEnvFile(join(homeDir, 'config/stack/stack.env')),
       ...process.env as Record<string, string>,
     };
     // OP_HOME must resolve to absolute path
     stackEnvVars.OP_HOME = homeDir;
 
     const allComposeFiles = [
-      join(homeDir, 'stack/core.compose.yml'),
-      join(homeDir, 'stack/addons/admin/compose.yml'),
-      join(homeDir, 'stack/addons/chat/compose.yml'),
+      join(homeDir, 'config/stack/core.compose.yml'),
+      join(homeDir, 'config/stack/addons/chat/compose.yml'),
     ];
     const mounts = extractVolumeMountPaths(allComposeFiles, stackEnvVars);
     expect(mounts.length).toBeGreaterThan(0);
 
-    // Ensure they all exist first (this is what ensureVolumeMountTargets does)
-    const { ensureVolumeMountTargets } = await import('./commands/install.ts') as any;
-    // Can't import private function, so replicate the check
-    // Only check mounts inside homeDir (ignore Docker socket, etc.)
+    // Ensure they all exist first via the canonical lib helper. Only mounts
+    // under homeDir are touched; external paths (Docker socket, etc.) are left
+    // alone by ensureComposeVolumeTargets itself, but we also filter the
+    // verification loop below to homeDir to keep the assertion local.
+    const { ensureComposeVolumeTargets, createState } = await import('@openpalm/lib');
+    ensureComposeVolumeTargets(createState());
     const homeMounts = mounts.filter(m => m.path.startsWith(homeDir));
 
-    for (const mount of homeMounts) {
-      if (!existsSync(mount.path)) {
-        if (mount.isFile) {
-          mkdirSync(join(mount.path, '..'), { recursive: true });
-          Bun.spawnSync(['touch', mount.path]);
-        } else {
-          mkdirSync(mount.path, { recursive: true });
-        }
-      }
-    }
-
     for (const mount of homeMounts) {
       expect(existsSync(mount.path)).toBe(true);
       const stat = lstatSync(mount.path);
@@ -294,56 +247,64 @@ describe('install flow — tier 1 (file validation)', () => {
     const rootFiles = new TextDecoder().decode(rootOwned.stdout).trim();
     expect(rootFiles).toBe('');
 
-    // ── Validate data directories ────────────────────────────────────
-    for (const dir of ['admin', 'assistant', 'memory', 'guardian', 'stash', 'workspace']) {
-      expect(existsSync(join(homeDir, `data/${dir}`))).toBe(true);
+    // ── Validate state and stash directories ────────────────────────────────────
+    for (const dir of ['state/admin', 'state/assistant', 'state/guardian', 'stash', 'workspace']) {
+      expect(existsSync(join(homeDir, dir))).toBe(true);
     }
 
-    // ── Validate active automations dir exists but catalog is separate ──
-    expect(existsSync(join(homeDir, 'config/automations'))).toBe(true);
-    const automations = readdirSync(join(homeDir, 'config/automations'));
-    expect(automations.length).toBe(0);
+    // ── Validate akm-improve is seeded into stash/tasks/ ──
+    // performSetup seeds the akm-improve maintenance automation on first
+    // install as an AKM markdown task; everything else stays in the registry
+    // catalog until enabled.
+    const tasksDir = join(homeDir, 'stash/tasks');
+    expect(existsSync(tasksDir)).toBe(true);
+    const tasks = readdirSync(tasksDir).sort();
+    expect(tasks).toEqual(['akm-improve.md']);
+
+    const akmImprovePath = join(homeDir, 'stash/tasks/akm-improve.md');
+    const akmImproveContent = readFileSync(akmImprovePath, 'utf-8');
+    expect(akmImproveContent).toContain('akm');
+    expect(akmImproveContent).toContain('improve');
+    // Confirm we're on the 0.8.0+ command, not the removed `index --enrich`.
+    expect(akmImproveContent).not.toMatch(/--enrich\b/);
+
+    // ── Re-run setup: user edits to akm-improve.md must survive ─────
+    const userEdited = '---\nschedule: "0 9 * * *"\nenabled: false\ncommand: ["akm","improve","--auto-accept","safe"]\n---\n';
+    writeFileSync(akmImprovePath, userEdited);
+    const reSetup = await performSetup(spec as any);
+    expect(reSetup.ok).toBe(true);
+    expect(readFileSync(akmImprovePath, 'utf-8')).toBe(userEdited);
   }, 30_000);
 
   tier1Test('compose config validates with selected addons', async () => {
     homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
     process.env.OP_HOME = homeDir;
-    process.env.OP_WORK_DIR = join(homeDir, 'data/workspace');
+    process.env.OP_WORK_DIR = join(homeDir, 'workspace');
 
-    seedFromLocal(homeDir, ['admin', 'chat']);
+    seedFromLocal(homeDir, ['chat']);
 
     const { performSetup } = await import('@openpalm/lib');
     const result = await performSetup(makeSetupSpec() as any);
     expect(result.ok).toBe(true);
 
     // Ensure all volume mount targets exist so compose doesn't complain
-    const stackEnv = join(homeDir, 'vault/stack/stack.env');
-    const vars = { ...parseEnvFile(stackEnv), OP_HOME: homeDir };
+    const stackEnv = join(homeDir, 'config/stack/stack.env');
     const composeFiles = [
-      join(homeDir, 'stack/core.compose.yml'),
-      join(homeDir, 'stack/addons/admin/compose.yml'),
-      join(homeDir, 'stack/addons/chat/compose.yml'),
+      join(homeDir, 'config/stack/core.compose.yml'),
+      join(homeDir, 'config/stack/addons/chat/compose.yml'),
     ];
-    for (const mount of extractVolumeMountPaths(composeFiles, vars)) {
-      if (!mount.path.startsWith(homeDir)) continue; // skip Docker socket etc.
-      if (!existsSync(mount.path)) {
-        if (mount.isFile) {
-          mkdirSync(join(mount.path, '..'), { recursive: true });
-          Bun.spawnSync(['touch', mount.path]);
-        } else {
-          mkdirSync(mount.path, { recursive: true });
-        }
-      }
-    }
+    const { ensureComposeVolumeTargets, createState } = await import('@openpalm/lib');
+    ensureComposeVolumeTargets(createState());
 
     // Run docker compose config --quiet
+    // Note: vault/user/user.env is no longer a
+    // compose env_file. Only stack.env (and guardian.env, when present)
+    // are passed to compose.
     const proc = Bun.spawnSync([
       'docker', 'compose', '--project-name', 'openpalm-test',
       '-f', composeFiles[0],
       '-f', composeFiles[1],
-      '-f', composeFiles[2],
       '--env-file', stackEnv,
-      '--env-file', join(homeDir, 'vault/user/user.env'),
       'config', '--quiet',
     ], { stdout: 'pipe', stderr: 'pipe', env: { ...process.env, OP_HOME: homeDir } });
 
@@ -354,10 +315,48 @@ describe('install flow — tier 1 (file validation)', () => {
     expect(proc.exitCode).toBe(0);
   }, 30_000);
 
+  tier1Test('seedOpenPalmDir copies the built-in stash skill on first install', async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
+    process.env.OP_HOME = homeDir;
+    process.env.OP_WORK_DIR = join(homeDir, 'workspace');
+
+    const { seedOpenPalmDir } = await import('./lib/io.ts');
+    await seedOpenPalmDir('local', homeDir, join(homeDir, 'config'), join(homeDir, 'state'));
+
+    // The shipped config-diagnostics skill must land on disk with valid frontmatter.
+    const skillPath = join(homeDir, 'stash/skills/config-diagnostics/SKILL.md');
+    expect(existsSync(skillPath)).toBe(true);
+    const skill = readFileSync(skillPath, 'utf-8');
+    expect(skill).toContain('name: config-diagnostics');
+    expect(skill).toContain('type: skill');
+    expect(skill.startsWith('---')).toBe(true);
+  }, 30_000);
+
+  tier1Test('seedOpenPalmDir preserves user edits to seeded stash assets', async () => {
+    homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
+    process.env.OP_HOME = homeDir;
+    process.env.OP_WORK_DIR = join(homeDir, 'workspace');
+
+    const { seedOpenPalmDir } = await import('./lib/io.ts');
+
+    // First install seeds the asset.
+    await seedOpenPalmDir('local', homeDir, join(homeDir, 'config'), join(homeDir, 'state'));
+    const skillPath = join(homeDir, 'stash/skills/config-diagnostics/SKILL.md');
+    expect(existsSync(skillPath)).toBe(true);
+
+    // User edits the seeded skill.
+    const userEdit = '# User-edited skill — do not clobber\n';
+    writeFileSync(skillPath, userEdit);
+
+    // Re-install must not overwrite the user's edit (skipExisting).
+    await seedOpenPalmDir('local', homeDir, join(homeDir, 'config'), join(homeDir, 'state'));
+    expect(readFileSync(skillPath, 'utf-8')).toBe(userEdit);
+  }, 30_000);
+
   tier1Test('performSetup with no addons produces only core services', async () => {
     homeDir = mkdtempSync(join(tmpdir(), 'openpalm-install-test-'));
     process.env.OP_HOME = homeDir;
-    process.env.OP_WORK_DIR = join(homeDir, 'data/workspace');
+    process.env.OP_WORK_DIR = join(homeDir, 'workspace');
 
     seedFromLocal(homeDir);
 
@@ -365,21 +364,21 @@ describe('install flow — tier 1 (file validation)', () => {
     const result = await performSetup(makeSetupSpec() as any);
     expect(result.ok).toBe(true);
 
-    const noAddonSpec = readStackSpec(join(homeDir, 'config'));
+    const noAddonSpec = readStackSpec(join(homeDir, 'config', 'stack'));
     expect(noAddonSpec).not.toBeNull();
 
-    // Core compose only, no addon files in the compose list
-    const stackEnv = join(homeDir, 'vault/stack/stack.env');
+    // Core compose only, no addon files in the compose list.
+    // Only state/stack.env is needed for `compose config`.
+    const stackEnv = join(homeDir, 'config/stack/stack.env');
     const proc = Bun.spawnSync([
       'docker', 'compose', '--project-name', 'openpalm-test',
-      '-f', join(homeDir, 'stack/core.compose.yml'),
+      '-f', join(homeDir, 'config/stack/core.compose.yml'),
       '--env-file', stackEnv,
-      '--env-file', join(homeDir, 'vault/user/user.env'),
       'config', '--services',
-    ], { stdout: 'pipe', stderr: 'pipe' });
+    ], { stdout: 'pipe', stderr: 'pipe', env: { ...process.env, OP_HOME: homeDir } });
 
     const services = new TextDecoder().decode(proc.stdout).trim().split('\n').sort();
-    expect(services).toEqual(['assistant', 'guardian', 'init', 'memory', 'scheduler']);
+    expect(services).toEqual(['assistant', 'guardian']);
   }, 30_000);
 });
 

package/src/lib/admin-skills/index.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from "bun:test";
+import {
+  validateContainerOp,
+  validateDestructiveOp,
+  validatePathArg,
+  validateAddonName,
+} from "./index.ts";
+
+describe("validateContainerOp", () => {
+  it("rejects path traversal in service name", () => {
+    const r = validateContainerOp("../../etc/passwd");
+    expect(r.ok).toBe(false);
+  });
+
+  it("rejects unknown service name", () => {
+    const r = validateContainerOp("evil-service");
+    expect(r.ok).toBe(false);
+  });
+
+  it("accepts a valid core service name", () => {
+    // CORE_SERVICES contains "assistant"
+    const r = validateContainerOp("assistant");
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe("validateDestructiveOp", () => {
+  it("rejects empty confirmation", () => {
+    const r = validateDestructiveOp("");
+    expect(r.ok).toBe(false);
+  });
+
+  it("rejects wrong confirmation string", () => {
+    const r = validateDestructiveOp("yes");
+    expect(r.ok).toBe(false);
+  });
+
+  it("accepts correct confirmation", () => {
+    const r = validateDestructiveOp("yes-i-am-sure");
+    expect(r.ok).toBe(true);
+  });
+});
+
+describe("validatePathArg", () => {
+  it("rejects path traversal", () => {
+    expect(validatePathArg("../../secrets").ok).toBe(false);
+  });
+
+  it("rejects shell injection characters", () => {
+    expect(validatePathArg("foo$(rm -rf /)").ok).toBe(false);
+  });
+
+  it("accepts a normal relative path", () => {
+    expect(validatePathArg("stash/tasks/my-task.md").ok).toBe(true);
+  });
+});
+
+describe("validateAddonName", () => {
+  it("rejects names with slashes", () => {
+    expect(validateAddonName("../../admin").ok).toBe(false);
+  });
+
+  it("rejects names with spaces", () => {
+    expect(validateAddonName("my addon").ok).toBe(false);
+  });
+
+  it("accepts a clean addon name", () => {
+    expect(validateAddonName("voice-channel").ok).toBe(true);
+  });
+});

package/src/lib/admin-skills/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Admin skills allowlist.
+ *
+ * Validates arguments for every admin skill call before they reach the admin API
+ * or lib functions. This is the security boundary between the assistant subprocess
+ * and the control plane.
+ *
+ * Four invariants enforced:
+ *   1. No ".." in path arguments (path traversal).
+ *   2. Service names must be in CORE_SERVICES.
+ *   3. Destructive operations require confirmation: "yes-i-am-sure".
+ *   4. No raw shell strings (sub-shell expansions, pipes, redirects).
+ */
+import { CORE_SERVICES } from "@openpalm/lib";
+
+// ── Invariant helpers ────────────────────────────────────────────────────
+
+/** INV-1: No path traversal */
+function assertNoPathTraversal(value: string, field: string): string | null {
+  if (value.includes("..")) {
+    return `${field}: path traversal ("..") is not allowed`;
+  }
+  return null;
+}
+
+/** INV-2: Service name must be in CORE_SERVICES */
+function assertValidServiceName(value: string, field: string): string | null {
+  const valid = new Set<string>(CORE_SERVICES);
+  if (!valid.has(value as never)) {
+    return `${field}: "${value}" is not a valid service name (allowed: ${[...valid].join(", ")})`;
+  }
+  return null;
+}
+
+/** INV-3: Destructive ops require explicit confirmation */
+function assertConfirmation(confirmation: unknown, field = "confirmation"): string | null {
+  if (confirmation !== "yes-i-am-sure") {
+    return `${field}: destructive operation requires confirmation === "yes-i-am-sure"`;
+  }
+  return null;
+}
+
+/** INV-4: No shell special characters in string arguments */
+const SHELL_INJECTION_RE = /[$`|&;<>(){}[\]\\!]/;
+function assertNoShellInjection(value: string, field: string): string | null {
+  if (SHELL_INJECTION_RE.test(value)) {
+    return `${field}: shell special characters are not allowed in admin skill arguments`;
+  }
+  return null;
+}
+
+// ── Public validation entry points ───────────────────────────────────────
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; error: string };
+
+/**
+ * Validate arguments for a container operation (up/down/restart/start/stop).
+ *
+ * @param serviceName  The name of the service to act on
+ */
+export function validateContainerOp(serviceName: string): ValidationResult {
+  const err =
+    assertNoPathTraversal(serviceName, "serviceName") ??
+    assertValidServiceName(serviceName, "serviceName") ??
+    assertNoShellInjection(serviceName, "serviceName");
+  if (err) return { ok: false, error: err };
+  return { ok: true };
+}
+
+/**
+ * Validate arguments for a destructive operation (uninstall, wipe, etc.).
+ *
+ * @param confirmation  Must equal "yes-i-am-sure"
+ */
+export function validateDestructiveOp(confirmation: unknown): ValidationResult {
+  const err = assertConfirmation(confirmation);
+  if (err) return { ok: false, error: err };
+  return { ok: true };
+}
+
+/**
+ * Validate a filesystem path argument passed to any admin skill.
+ *
+ * @param path  The path string to validate
+ */
+export function validatePathArg(path: string): ValidationResult {
+  const err =
+    assertNoPathTraversal(path, "path") ??
+    assertNoShellInjection(path, "path");
+  if (err) return { ok: false, error: err };
+  return { ok: true };
+}
+
+/**
+ * Validate an addon name (same rules as service name but addons are not in CORE_SERVICES;
+ * still must not contain shell characters or path traversal).
+ *
+ * @param name  The addon name
+ */
+export function validateAddonName(name: string): ValidationResult {
+  // Addon names are not fixed like CORE_SERVICES, but must be clean identifiers.
+  const ADDON_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+  if (!ADDON_NAME_RE.test(name)) {
+    return { ok: false, error: `name: "${name}" is not a valid addon name (alphanumeric, _ and - only)` };
+  }
+  const err =
+    assertNoPathTraversal(name, "name") ??
+    assertNoShellInjection(name, "name");
+  if (err) return { ok: false, error: err };
+  return { ok: true };
+}