@openpalm/lib 0.10.1 → 0.11.0-beta.1

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

@@ -0,0 +1,157 @@
+/**
+ * Self-healing install lock for the setup wizard phase.
+ *
+ * Both `performSetup` (config writes) and `startDeploy` (Docker work) need an
+ * exclusive lock against concurrent installs. The lock file lives at
+ * `<stateDir>/.install.lock` and contains `<pid>\n<timestamp>\n`.
+ *
+ * Self-healing rules:
+ *  - On EEXIST, parse the holder PID. If the process is gone (`process.kill(pid, 0)`
+ *    throws ESRCH) the lock is stale and we remove + retry once.
+ *  - If the timestamp is older than STALE_AFTER_MS the lock is stale and we
+ *    remove + retry once.
+ *  - If the file is unparseable (e.g. written by an older version) fall back to
+ *    mtime > STALE_AFTER_MS.
+ *
+ * On any unexpected error (permissions, ENOSPC, etc.) we return null so the
+ * caller surfaces "install_in_progress" rather than silently fake-acquiring.
+ */
+import { openSync, writeSync, closeSync, readFileSync, statSync, rmSync, mkdirSync, constants } from "node:fs";
+import { join } from "node:path";
+import { createLogger } from "../logger.js";
+
+const logger = createLogger("install-lock");
+
+const STALE_AFTER_MS = 30 * 60 * 1000; // 30 minutes
+
+export type InstallLockHandle = {
+  path: string;
+};
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH = no such process. EPERM = process exists but we don't own it.
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function parseLockContent(content: string): { pid: number | null; timestamp: number | null } {
+  const lines = content.split("\n");
+  const pid = Number.parseInt(lines[0] ?? "", 10);
+  const timestamp = Number.parseInt(lines[1] ?? "", 10);
+  return {
+    pid: Number.isFinite(pid) && pid > 0 ? pid : null,
+    timestamp: Number.isFinite(timestamp) && timestamp > 0 ? timestamp : null,
+  };
+}
+
+function isStale(path: string): boolean {
+  let content = "";
+  try {
+    content = readFileSync(path, "utf-8");
+  } catch {
+    // Can't read — assume held; caller will surface error.
+    return false;
+  }
+  const { pid, timestamp } = parseLockContent(content);
+  if (pid !== null) {
+    if (!isProcessAlive(pid)) return true;
+    if (timestamp !== null && Date.now() - timestamp > STALE_AFTER_MS) return true;
+    return false;
+  }
+  // Unparseable — fall back to mtime.
+  try {
+    const stat = statSync(path);
+    return Date.now() - stat.mtimeMs > STALE_AFTER_MS;
+  } catch {
+    return false;
+  }
+}
+
+function tryCreate(path: string): boolean {
+  const content = `${process.pid}\n${Date.now()}\n`;
+  try {
+    const fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o644);
+    try {
+      writeSync(fd, content);
+    } finally {
+      try { closeSync(fd); } catch { /* best-effort */ }
+    }
+    return true;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") return false;
+    // Unexpected error — propagate so caller returns null.
+    throw err;
+  }
+}
+
+/**
+ * Try to acquire the install lock under `stateDir`. Returns a handle on
+ * success or null if the lock is held by a live, recent install (or on any
+ * unexpected filesystem error — caller should surface "install_in_progress").
+ *
+ * Callers MUST call `releaseInstallLock()` in a finally block when done.
+ */
+export function acquireInstallLock(stateDir: string): InstallLockHandle | null {
+  try {
+    mkdirSync(stateDir, { recursive: true });
+  } catch (err) {
+    logger.warn("failed to ensure state dir for install lock", {
+      stateDir,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+  const path = join(stateDir, ".install.lock");
+
+  try {
+    if (tryCreate(path)) return { path };
+  } catch (err) {
+    logger.warn("unexpected error acquiring install lock", {
+      path,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+
+  // EEXIST — check whether the existing lock is stale.
+  if (!isStale(path)) return null;
+
+  logger.info("removing stale install lock and retrying acquire", { path });
+  try {
+    rmSync(path, { force: true });
+  } catch (err) {
+    logger.warn("failed to remove stale install lock", {
+      path,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+
+  try {
+    if (tryCreate(path)) return { path };
+  } catch (err) {
+    logger.warn("unexpected error re-acquiring install lock", {
+      path,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+  // Lost the race with another acquirer.
+  return null;
+}
+
+export function releaseInstallLock(handle: InstallLockHandle | null): void {
+  if (!handle) return;
+  try {
+    rmSync(handle.path, { force: true });
+  } catch (err) {
+    logger.warn("failed to release install lock", {
+      path: handle.path,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/control-plane/lifecycle.ts

@@ -1,30 +1,32 @@
 /** Lifecycle helpers — state factory, apply transitions, compose file list. */
-import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { parseEnvFile, mergeEnvContent } from "./env.js";
-import type { ControlPlaneState, CallerType } from "./types.js";
+import type { ControlPlaneState, CallerType, AuditContext } from "./types.js";
 import { CORE_SERVICES } from "./types.js";
 import {
   resolveOpenPalmHome,
   resolveConfigDir,
-  resolveVaultDir,
-  resolveDataDir,
-  resolveLogsDir,
-  resolveCacheHome,
+  resolveStashDir,
+  resolveWorkspaceDir,
+  resolveCacheDir,
+  resolveStateDir,
+  resolveStackDir,
 } from "./home.js";
 import { ensureSecrets, readStackEnv, updateSystemSecretsEnv } from "./secrets.js";
 import {
   resolveRuntimeFiles,
   writeRuntimeFiles,
-  randomHex,
   buildEnvFiles,
   discoverStackOverlays,
+  ensureComposeVolumeTargets,
 } from "./config-persistence.js";
 import { readStackSpec } from "./stack-spec.js";
-import { refreshCoreAssets, ensureMemoryDir } from "./core-assets.js";
+import { refreshCoreAssets } from "./core-assets.js";
 import { isSetupComplete } from "./setup-status.js";
 import { snapshotCurrentState } from "./rollback.js";
 import { checkDocker, composePreflight, composePull, composeUp, composeConfigServices, resolveComposeProjectName } from "./docker.js";
 import { acquireLock, releaseLock } from "./lock.js";
+import { appendAudit } from "./audit.js";
 import { listEnabledAddonIds } from "./registry.js";
 
 const IMAGE_NAMESPACE_RE = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
@@ -36,27 +38,27 @@ export function createState(
 ): ControlPlaneState {
   const homeDir = resolveOpenPalmHome();
   const configDir = resolveConfigDir();
-  const vaultDir = resolveVaultDir();
-  const dataDir = resolveDataDir();
-  const logsDir = resolveLogsDir();
-  const cacheDir = resolveCacheHome();
+  const stashDir = resolveStashDir();
+  const workspaceDir = resolveWorkspaceDir();
+  const cacheDir = resolveCacheDir();
+  const stateDir = resolveStateDir();
+  const stackDir = resolveStackDir();
 
   const services: Record<string, "running" | "stopped"> = {};
   for (const name of CORE_SERVICES) {
     services[name] = "stopped";
   }
 
-  const setupToken = randomHex(16);
   const bootstrapState: ControlPlaneState = {
-    adminToken: adminToken ?? process.env.OP_ADMIN_TOKEN ?? "",
+    adminToken: adminToken ?? process.env.OP_UI_TOKEN ?? "",
     assistantToken: "",
-    setupToken,
     homeDir,
     configDir,
-    vaultDir,
-    dataDir,
-    logsDir,
+    stashDir,
+    workspaceDir,
     cacheDir,
+    stateDir,
+    stackDir,
     services,
     artifacts: { compose: "" },
     artifactMeta: [],
@@ -65,35 +67,21 @@ export function createState(
 
   ensureSecrets(bootstrapState);
 
-  const stackEnv = readStackEnv(vaultDir);
+  const stackEnv = readStackEnv(stackDir);
   // Precedence: explicit parameter > stack.env > process.env.
   bootstrapState.adminToken =
     adminToken
-      ?? stackEnv.OP_ADMIN_TOKEN
-      ?? process.env.OP_ADMIN_TOKEN
+      ?? stackEnv.OP_UI_TOKEN
+      ?? process.env.OP_UI_TOKEN
       ?? "";
   bootstrapState.assistantToken =
     stackEnv.OP_ASSISTANT_TOKEN
       ?? process.env.OP_ASSISTANT_TOKEN
       ?? "";
 
-  writeSetupTokenFile(bootstrapState);
-
   return bootstrapState;
 }
 
-export function writeSetupTokenFile(state: ControlPlaneState): void {
-  const tokenPath = `${state.dataDir}/setup-token.txt`;
-  const setupComplete = isSetupComplete(state.vaultDir);
-
-  if (setupComplete) {
-    try { unlinkSync(tokenPath); } catch { /* already gone */ }
-  } else {
-    mkdirSync(state.dataDir, { recursive: true });
-    writeFileSync(tokenPath, state.setupToken + "\n", { mode: 0o600 });
-  }
-}
-
 
 async function reconcileCore(
   state: ControlPlaneState,
@@ -102,10 +90,9 @@ async function reconcileCore(
   if (opts.activateServices) {
     for (const s of CORE_SERVICES) state.services[s] = "running";
   }
-  ensureMemoryDir(state.dataDir);
 
   for (const addonName of listEnabledAddonIds(state.homeDir)) {
-    mkdirSync(`${state.dataDir}/${addonName}`, { recursive: true });
+    mkdirSync(`${state.stateDir}/${addonName}`, { recursive: true });
   }
 
   const active: string[] = [];
@@ -155,28 +142,46 @@ async function reconcileCore(
   return active;
 }
 
-export async function applyInstall(state: ControlPlaneState): Promise<void> {
+export async function applyInstall(state: ControlPlaneState, ctx?: AuditContext): Promise<void> {
   const lock = acquireLock(state.homeDir, "install");
   try {
     await reconcileCore(state, { activateServices: true });
+    // Pre-create host-side volume mount targets as the current user so
+    // Docker doesn't create them root-owned (which causes EACCES inside
+    // non-root containers).
+    ensureComposeVolumeTargets(state);
+    if (ctx) appendAudit(state, ctx.actor, "install", {}, true, ctx.requestId ?? "", ctx.callerType ?? "unknown");
+  } catch (err) {
+    if (ctx) appendAudit(state, ctx.actor, "install", { error: String(err) }, false, ctx.requestId ?? "", ctx.callerType ?? "unknown");
+    throw err;
   } finally {
     releaseLock(lock);
   }
 }
 
-export async function applyUpdate(state: ControlPlaneState): Promise<{ restarted: string[] }> {
+export async function applyUpdate(state: ControlPlaneState, ctx?: AuditContext): Promise<{ restarted: string[] }> {
   const lock = acquireLock(state.homeDir, "update");
   try {
-    return { restarted: await reconcileCore(state, {}) };
+    const result = { restarted: await reconcileCore(state, {}) };
+    if (ctx) appendAudit(state, ctx.actor, "update", { restarted: result.restarted }, true, ctx.requestId ?? "", ctx.callerType ?? "unknown");
+    return result;
+  } catch (err) {
+    if (ctx) appendAudit(state, ctx.actor, "update", { error: String(err) }, false, ctx.requestId ?? "", ctx.callerType ?? "unknown");
+    throw err;
   } finally {
     releaseLock(lock);
   }
 }
 
-export async function applyUninstall(state: ControlPlaneState): Promise<{ stopped: string[] }> {
+export async function applyUninstall(state: ControlPlaneState, ctx?: AuditContext): Promise<{ stopped: string[] }> {
   const lock = acquireLock(state.homeDir, "uninstall");
   try {
-    return { stopped: await reconcileCore(state, { deactivateServices: true }) };
+    const result = { stopped: await reconcileCore(state, { deactivateServices: true }) };
+    if (ctx) appendAudit(state, ctx.actor, "uninstall", { stopped: result.stopped }, true, ctx.requestId ?? "", ctx.callerType ?? "unknown");
+    return result;
+  } catch (err) {
+    if (ctx) appendAudit(state, ctx.actor, "uninstall", { error: String(err) }, false, ctx.requestId ?? "", ctx.callerType ?? "unknown");
+    throw err;
   } finally {
     releaseLock(lock);
   }
@@ -203,7 +208,7 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
   namespace: string;
   tag: string;
 }> {
-  const systemEnvPath = `${state.vaultDir}/stack/stack.env`;
+  const systemEnvPath = `${state.stackDir}/stack.env`;
   const parsed = parseEnvFile(systemEnvPath);
   const namespace = (parsed.OP_IMAGE_NAMESPACE ?? process.env.OP_IMAGE_NAMESPACE ?? "openpalm").trim().toLowerCase();
 
@@ -273,22 +278,18 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
   const files = buildComposeFileList(state);
   const envFiles = buildEnvFiles(state);
 
-  // 1. Preflight: validate compose merge before any mutation
-  if (files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
-    const preflight = await composePreflight({ files, envFiles });
-    if (!preflight.ok) {
-      throw new Error(`Compose preflight failed: ${preflight.stderr}`);
-    }
-  }
+  // Compose preflight runs inside `applyUpgrade` -> `reconcileCore`, so we
+  // skip the redundant top-level call. Any merge failure aborts before
+  // mutation just the same.
 
-  // 2. Snapshot stack.env for rollback on failure
-  const stackEnvPath = `${state.vaultDir}/stack/stack.env`;
+  // 1. Snapshot stack.env for rollback on failure
+  const stackEnvPath = `${state.stackDir}/stack.env`;
   let originalStackEnv: string | null = null;
   try {
     originalStackEnv = readFileSync(stackEnvPath, "utf-8");
   } catch { /* stack.env may not exist yet */ }
 
-  // 3. Update image tag + refresh core assets
+  // 2. Update image tag + refresh core assets
   let imageTag: string;
   let namespace: string;
   let upgradeResult: { backupDir: string | null; updated: string[]; restarted: string[] };
@@ -305,13 +306,13 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
     throw e;
   }
 
-  // 4. Pull images
+  // 3. Pull images
   const pullResult = await composePull({ files, envFiles });
   if (!pullResult.ok) {
     throw new Error(`Failed to pull images: ${pullResult.stderr}`);
   }
 
-  // 5. Recreate containers
+  // 4. Recreate containers
   const services = await buildManagedServices(state);
   const upResult = await composeUp({ files, envFiles, services, removeOrphans: true });
   if (!upResult.ok) {
@@ -328,7 +329,7 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
 }
 
 export function buildComposeFileList(state: ControlPlaneState): string[] {
-  return discoverStackOverlays(`${state.homeDir}/stack`);
+  return discoverStackOverlays(state.stackDir);
 }
 
 export async function buildManagedServices(state: ControlPlaneState): Promise<string[]> {

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

@@ -0,0 +1,200 @@
+/**
+ * AKM markdown task parser.
+ *
+ * Task files are markdown with YAML frontmatter. The frontmatter defines the
+ * schedule and target; for inline-prompt tasks the markdown body is the prompt.
+ *
+ * Supported target types:
+ *   command  — `command: [...]` YAML array (argv), run via Bun.spawn / akm tasks run
+ *   prompt   — `prompt: inline` + markdown body as the prompt text
+ *   workflow — `workflow: workflow:<ref>` + optional `params` map
+ */
+import { parse as parseYaml } from "yaml";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AutomationConfig } from "./scheduler.js";
+import { createLogger } from "../logger.js";
+
+const logger = createLogger("markdown-task");
+
+// ── Types ─────────────────────────────────────────────────────────────────
+
+export interface MarkdownTask {
+  id: string;
+  schedule: string;
+  enabled: boolean;
+  description?: string;
+  tags?: string[];
+  timeoutMs?: number;
+  target: MarkdownTaskTarget;
+  source: { path: string };
+}
+
+export type MarkdownTaskTarget =
+  | { kind: "command"; cmd: string[] }
+  | { kind: "prompt"; profile?: string; body: string }
+  | { kind: "workflow"; ref: string; params: Record<string, unknown> };
+
+// ── Frontmatter splitter ──────────────────────────────────────────────────
+
+interface ParsedFile {
+  frontmatter: string;
+  body: string;
+}
+
+function splitFrontmatter(content: string): ParsedFile | null {
+  // Must start with ---
+  if (!content.startsWith("---")) return null;
+  const after = content.slice(3);
+  const end = after.indexOf("\n---");
+  if (end === -1) return null;
+  return {
+    frontmatter: after.slice(0, end).trim(),
+    body: after.slice(end + 4).trim(),
+  };
+}
+
+// ── Parser ────────────────────────────────────────────────────────────────
+
+export function parseMarkdownTask(filePath: string): MarkdownTask | null {
+  const id = filePath.replace(/.*[\\/]/, "").replace(/\.md$/, "");
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    logger.warn("failed to read task file", { filePath, error: String(err) });
+    return null;
+  }
+
+  const parts = splitFrontmatter(raw);
+  if (!parts) {
+    logger.warn("task file missing frontmatter delimiters", { filePath });
+    return null;
+  }
+
+  let fm: Record<string, unknown>;
+  try {
+    fm = parseYaml(parts.frontmatter) as Record<string, unknown>;
+  } catch (err) {
+    logger.warn("failed to parse task frontmatter", { filePath, error: String(err) });
+    return null;
+  }
+
+  if (!fm || typeof fm !== "object") {
+    logger.warn("task frontmatter is not an object", { filePath });
+    return null;
+  }
+
+  const schedule = fm.schedule;
+  if (typeof schedule !== "string" || !schedule.trim()) {
+    logger.warn("task missing or empty 'schedule'", { filePath });
+    return null;
+  }
+
+  // Resolve target type from frontmatter
+  let target: MarkdownTaskTarget;
+
+  if (fm.command !== undefined) {
+    const cmd = Array.isArray(fm.command)
+      ? fm.command.map(String)
+      : typeof fm.command === "string"
+        ? [fm.command]
+        : null;
+    if (!cmd || cmd.length === 0) {
+      logger.warn("task 'command' must be a non-empty array", { filePath });
+      return null;
+    }
+    target = { kind: "command", cmd };
+  } else if (fm.prompt !== undefined) {
+    if (fm.prompt !== "inline") {
+      // Future: handle asset-ref and file-path prompt sources
+      logger.warn("task 'prompt' supports only 'inline' currently", { filePath });
+      return null;
+    }
+    if (!parts.body) {
+      logger.warn("prompt:inline task has no markdown body", { filePath });
+      return null;
+    }
+    target = {
+      kind: "prompt",
+      profile: typeof fm.profile === "string" ? fm.profile : undefined,
+      body: parts.body,
+    };
+  } else if (fm.workflow !== undefined) {
+    if (typeof fm.workflow !== "string") {
+      logger.warn("task 'workflow' must be a string ref", { filePath });
+      return null;
+    }
+    target = {
+      kind: "workflow",
+      ref: fm.workflow,
+      params: (fm.params && typeof fm.params === "object" && !Array.isArray(fm.params))
+        ? fm.params as Record<string, unknown>
+        : {},
+    };
+  } else {
+    logger.warn("task must have one of: command, prompt, workflow", { filePath });
+    return null;
+  }
+
+  return {
+    id,
+    schedule: schedule.trim(),
+    enabled: fm.enabled !== false,
+    description: typeof fm.description === "string" ? fm.description : undefined,
+    tags: Array.isArray(fm.tags) ? fm.tags.map(String) : undefined,
+    timeoutMs: typeof fm.timeoutMs === "number" ? fm.timeoutMs : undefined,
+    target,
+    source: { path: filePath },
+  };
+}
+
+export function loadMarkdownTasks(stashDir: string): MarkdownTask[] {
+  const dir = join(stashDir, "tasks");
+  if (!existsSync(dir)) return [];
+
+  const tasks: MarkdownTask[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const task = parseMarkdownTask(join(dir, entry.name));
+    if (task) tasks.push(task);
+  }
+  return tasks;
+}
+
+// ── AutomationConfig adapter ──────────────────────────────────────────────
+// Keeps the GET /admin/automations response shape compatible so the existing
+// UI does not require changes.
+
+export function taskToAutomationConfig(task: MarkdownTask): AutomationConfig {
+  const { target } = task;
+
+  let actionType: "shell" | "assistant" | "workflow" | "api" | "http";
+  let content: string | undefined;
+  let agent: string | undefined;
+
+  if (target.kind === "command") {
+    actionType = "shell";
+  } else if (target.kind === "prompt") {
+    actionType = "assistant";
+    content = target.body;
+    agent = target.profile;
+  } else {
+    actionType = "workflow";
+  }
+
+  return {
+    name: task.id,
+    description: task.description ?? "",
+    schedule: task.schedule,
+    timezone: "",
+    enabled: task.enabled,
+    action: {
+      type: actionType,
+      content,
+      agent,
+    },
+    on_failure: "log",
+    fileName: `${task.id}.md`,
+  };
+}

package/src/control-plane/paths.ts

@@ -0,0 +1,75 @@
+/**
+ * Authoritative path resolution for the OpenPalm control plane.
+ *
+ * Every consumer imports from here instead of concatenating paths inline.
+ * When the directory layout changes, update this file only.
+ *
+ * Layout:
+ *   config/        — user-editable config + system config files (auth.json, akm/)
+ *   config/stack/  — compose runtime + stack config (stack.env, guardian.env, stack.yml, addons/)
+ *   cache/         — regenerable/semi-persistent data (akm cache, guardian cache, rollback)
+ *   state/         — persistent service data (assistant, admin, guardian, logs, backups, registry)
+ *   stash/         — akm knowledge (skills, vaults, agents)
+ *   workspace/     — shared work area
+ */
+import type { ControlPlaneState } from "./types.js";
+
+// ── Config directory — user + system config ─────────────────────────────────
+
+/** OpenCode auth token store */
+export const authJsonPath          = (s: ControlPlaneState): string => `${s.configDir}/auth.json`;
+/** akm setup config directory (AKM_CONFIG_DIR) */
+export const akmConfigDir          = (s: ControlPlaneState): string => `${s.configDir}/akm`;
+/** akm setup config file (written by admin on capability save) */
+export const akmConfigPath         = (s: ControlPlaneState): string => `${s.configDir}/akm/config.json`;
+export const tasksDir              = (s: ControlPlaneState): string => `${s.stashDir}/tasks`;
+export const assistantConfigDir    = (s: ControlPlaneState): string => `${s.configDir}/assistant`;
+
+// ── Config/stack directory — compose runtime + stack config ─────────────────
+
+/** System env: capabilities, secrets, tokens */
+export const stackEnvPath          = (s: ControlPlaneState): string => `${s.stackDir}/stack.env`;
+/** Guardian HMAC channel secrets */
+export const guardianEnvPath       = (s: ControlPlaneState): string => `${s.stackDir}/guardian.env`;
+/** Stack spec: capability assignments */
+export const stackSpecFilePath     = (s: ControlPlaneState): string => `${s.stackDir}/stack.yml`;
+
+// ── Cache directory — regenerable/semi-persistent ───────────────────────────
+
+export const akmCacheDir           = (s: ControlPlaneState): string => `${s.cacheDir}/akm`;
+export const guardianCacheDir      = (s: ControlPlaneState): string => `${s.cacheDir}/guardian`;
+export const rollbackDir           = (s: ControlPlaneState): string => `${s.cacheDir}/rollback`;
+
+// ── State directory — persistent service data ───────────────────────────────
+
+export const assistantServiceDir   = (s: ControlPlaneState): string => `${s.stateDir}/assistant`;
+export const adminServiceDir       = (s: ControlPlaneState): string => `${s.stateDir}/admin`;
+export const guardianServiceDir    = (s: ControlPlaneState): string => `${s.stateDir}/guardian`;
+export const guardianStashDir      = (s: ControlPlaneState): string => `${s.stateDir}/guardian/stash`;
+export const guardianAkmDir        = (s: ControlPlaneState): string => `${s.stateDir}/guardian/akm`;
+/** Shared akm operational data (data/, state/ — NOT config, which lives in config/akm/) */
+export const akmStateDir           = (s: ControlPlaneState): string => `${s.stateDir}/akm`;
+export const taskLogDir            = (s: ControlPlaneState, id: string): string => `${s.cacheDir}/akm/tasks/logs/${id}`;
+export const taskLogsRootDir       = (s: ControlPlaneState): string => `${s.cacheDir}/akm/tasks/logs`;
+export const logsDir               = (s: ControlPlaneState): string => `${s.stateDir}/logs`;
+export const adminAuditPath        = (s: ControlPlaneState): string => `${s.stateDir}/logs/admin-audit.jsonl`;
+export const guardianAuditPath     = (s: ControlPlaneState): string => `${s.stateDir}/logs/guardian-audit.log`;
+export const backupsDir            = (s: ControlPlaneState): string => `${s.stateDir}/backups`;
+export const registryDir           = (s: ControlPlaneState): string => `${s.stateDir}/registry`;
+export const registryAddonsDir     = (s: ControlPlaneState): string => `${s.stateDir}/registry/addons`;
+export const registryAutomationsDir = (s: ControlPlaneState): string => `${s.stateDir}/registry/automations`;
+export const secretsDir            = (s: ControlPlaneState): string => `${s.stateDir}/secrets`;
+export const secretProviderPath    = (s: ControlPlaneState): string => `${s.stateDir}/secrets/provider.json`;
+export const secretsIndexPath      = (s: ControlPlaneState): string => `${s.stateDir}/secrets/plaintext-index.json`;
+export const passStoreDir          = (s: ControlPlaneState): string => `${s.stateDir}/secrets/pass-store`;
+
+// ── Stash directory ─────────────────────────────────────────────────────────
+
+/** akm vault:user file — lives in the stash */
+export const akmUserVaultPath      = (s: ControlPlaneState): string => `${s.stashDir}/vaults/user.env`;
+
+// ── Stack directory ─────────────────────────────────────────────────────────
+
+export const coreComposePath       = (s: ControlPlaneState): string => `${s.stackDir}/core.compose.yml`;
+export const addonsStackDir        = (s: ControlPlaneState): string => `${s.stackDir}/addons`;
+export const addonComposePath      = (s: ControlPlaneState, name: string): string => `${s.stackDir}/addons/${name}/compose.yml`;