@openpalm/lib 0.11.0-beta.1 → 0.11.0-beta.11

package/README.md

@@ -3,6 +3,8 @@
 Shared control-plane library for OpenPalm.
 CLI, admin, and scheduler use this package so stack behavior stays consistent.
 
+> **Bun required.** This package ships TypeScript source and relies on Bun's native TS execution. It does not compile to JavaScript and is not compatible with Node.js.
+
 The current model is direct-write over `~/.openpalm/` plus native Docker Compose.
 Compose files in `stack/` and env files in `vault/` are the live runtime inputs.
 

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.11.0-beta.1",
+  "version": "0.11.0-beta.11",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "scripts": {
     "test": "bun test"
   },
+  "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./provider-constants": "./src/provider-constants.ts",

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

@@ -21,19 +21,16 @@ import type { ControlPlaneState } from "./types.js";
 
 function makeState(homeDir: string): ControlPlaneState {
   return {
-    adminToken: "test-admin",
-    assistantToken: "test-assistant",
     homeDir,
     configDir: join(homeDir, "config"),
     stashDir: join(homeDir, "stash"),
     workspaceDir: join(homeDir, "workspace"),
-    servicesDir: join(homeDir, "services"),
+    cacheDir: join(homeDir, "cache"),
     stateDir: join(homeDir, "state"),
     stackDir: join(homeDir, "stack"),
     services: {},
     artifacts: { compose: "" },
     artifactMeta: [],
-    audit: [],
   };
 }
 

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

@@ -244,7 +244,11 @@ export async function deleteAkmVaultKey(
   const vaultPath = await ensureAkmUserVault(state, env);
   if (!vaultPath) return false;
   try {
-    await execAkm(["vault", "unset", AKM_USER_VAULT_REF, key], env);
+    // --yes: newer akm versions require explicit confirmation for any
+    // destructive operation in non-interactive mode. Without this flag
+    // the command exits with NON_INTERACTIVE_REQUIRES_YES and our
+    // delete looks like a hard failure instead of an idempotent unset.
+    await execAkm(["vault", "unset", "--yes", AKM_USER_VAULT_REF, key], env);
   } catch (err) {
     // `unset` of a missing key is a benign no-op; many akm versions exit 0
     // anyway. If akm hard-fails (non-zero, non-empty stderr) we surface it.

package/src/control-plane/channels.ts

@@ -19,9 +19,11 @@ function isValidChannelName(name: string): boolean {
 // ── Channel Discovery ─────────────────────────────────────────────────
 
 /**
- * Check if a compose file defines a channel service (has CHANNEL_NAME or GUARDIAN_URL).
- * This is compose-derived: we parse the actual compose content rather than
- * relying on filename patterns or directory naming conventions.
+ * Check if a compose file defines a channel service (has CHANNEL_NAME).
+ * Compose-derived: we parse the actual compose content rather than rely on
+ * filename or directory naming conventions. (GUARDIAN_URL used to be a
+ * fallback signal — it's been removed since channels-sdk now hardcodes the
+ * in-network guardian URL.)
  */
 export function isChannelAddon(composePath: string): boolean {
   try {
@@ -36,9 +38,9 @@ export function isChannelAddon(composePath: string): boolean {
       const env = (svcDef as Record<string, unknown>).environment;
       if (typeof env === "object" && env !== null) {
         if (Array.isArray(env)) {
-          if (env.some((e: unknown) => typeof e === "string" && (e.startsWith("CHANNEL_NAME=") || e.startsWith("GUARDIAN_URL=")))) return true;
+          if (env.some((e: unknown) => typeof e === "string" && e.startsWith("CHANNEL_NAME="))) return true;
         } else {
-          if ("CHANNEL_NAME" in (env as Record<string, unknown>) || "GUARDIAN_URL" in (env as Record<string, unknown>)) return true;
+          if ("CHANNEL_NAME" in (env as Record<string, unknown>)) return true;
         }
       }
     }
@@ -51,7 +53,7 @@ export function isChannelAddon(composePath: string): boolean {
 /**
  * Discover installed channels by scanning stack/addons/ for channel addons.
  * A channel addon is identified by compose-derived truth: its compose.yml
- * defines services with CHANNEL_NAME or GUARDIAN_URL environment variables.
+ * defines services with a CHANNEL_NAME environment variable.
  *
  * Non-channel addons (admin, ollama, etc.) are excluded.
  *

package/src/control-plane/compose-args.test.ts

@@ -6,7 +6,6 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import {
-  COMPOSE_PROJECT_NAME,
   buildComposeOptions,
   buildComposeCliArgs,
 } from "./compose-args.js";
@@ -17,8 +16,6 @@ let tempDir: string;
 function makeState(overrides: Partial<ControlPlaneState> = {}): ControlPlaneState {
   const configDir = join(tempDir, "config");
   return {
-    adminToken: "test",
-    assistantToken: "test",
     homeDir: tempDir,
     configDir,
     stashDir: join(tempDir, "stash"),
@@ -29,7 +26,6 @@ function makeState(overrides: Partial<ControlPlaneState> = {}): ControlPlaneStat
     services: {},
     artifacts: { compose: "" },
     artifactMeta: [],
-    audit: [],
     ...overrides,
   };
 }
@@ -66,14 +62,6 @@ afterEach(() => {
   rmSync(tempDir, { recursive: true, force: true });
 });
 
-// ── COMPOSE_PROJECT_NAME ─────────────────────────────────────────────────
-
-describe("COMPOSE_PROJECT_NAME", () => {
-  it("is 'openpalm'", () => {
-    expect(COMPOSE_PROJECT_NAME).toBe("openpalm");
-  });
-});
-
 // ── buildComposeOptions ──────────────────────────────────────────────────
 
 describe("buildComposeOptions", () => {

package/src/control-plane/compose-args.ts

@@ -11,10 +11,6 @@ import { buildComposeFileList } from "./lifecycle.js";
 import { buildEnvFiles } from "./config-persistence.js";
 import { resolveComposeProjectName } from "./docker.js";
 
-// ── Constants ────────────────────────────────────────────────────────────
-
-export const COMPOSE_PROJECT_NAME = "openpalm";
-
 // ── Types ────────────────────────────────────────────────────────────────
 
 export type ComposeOptions = {

package/src/control-plane/compose-errors.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+import {
+  parseComposeStderr,
+  summarizeComposeStderr,
+} from "./compose-errors.js";
+
+describe("parseComposeStderr", () => {
+  it("returns empty for empty input", () => {
+    expect(parseComposeStderr("")).toEqual([]);
+    expect(parseComposeStderr("\n\n")).toEqual([]);
+  });
+
+  it("extracts pull access denied for a single service", () => {
+    const stderr = [
+      " Network openpalm_default  Created",
+      " voice Pulling",
+      " voice Error pull access denied for openpalm/voice, repository does not exist or may require 'docker login'",
+      "Error response from daemon: pull access denied for openpalm/voice, repository does not exist or may require 'docker login': denied: requested access to the resource is denied",
+    ].join("\n");
+
+    const failures = parseComposeStderr(stderr);
+    expect(failures.length).toBeGreaterThanOrEqual(1);
+    expect(failures[0].service).toBe("voice");
+    expect(failures[0].reason).toMatch(/pull access denied/);
+  });
+
+  it("handles spinner / status prefix glyphs", () => {
+    const stderr = " ⠿ voice Error    pull access denied for openpalm/voice";
+    const failures = parseComposeStderr(stderr);
+    expect(failures).toHaveLength(1);
+    expect(failures[0].service).toBe("voice");
+    expect(failures[0].reason).toMatch(/pull access denied/);
+  });
+
+  it("captures quoted Service failed lines", () => {
+    const stderr =
+      'Service "discord" failed to build: failed to solve: process did not complete';
+    const failures = parseComposeStderr(stderr);
+    expect(failures).toHaveLength(1);
+    expect(failures[0].service).toBe("discord");
+    expect(failures[0].reason).toMatch(/failed to solve/);
+  });
+
+  it("deduplicates identical (service, reason) pairs", () => {
+    const stderr = [
+      "voice Error pull access denied for openpalm/voice",
+      "voice Error pull access denied for openpalm/voice",
+    ].join("\n");
+    const failures = parseComposeStderr(stderr);
+    expect(failures).toHaveLength(1);
+  });
+
+  it("returns multiple distinct failures", () => {
+    const stderr = [
+      "voice Error pull access denied for openpalm/voice",
+      "discord Error no such image: openpalm/discord:latest",
+    ].join("\n");
+    const failures = parseComposeStderr(stderr);
+    expect(failures).toHaveLength(2);
+    expect(failures.map((f) => f.service).sort()).toEqual(["discord", "voice"]);
+  });
+
+  it("falls back to image name when only daemon error is present", () => {
+    const stderr =
+      "Error response from daemon: pull access denied for openpalm/voice, repository does not exist";
+    const failures = parseComposeStderr(stderr);
+    expect(failures).toHaveLength(1);
+    expect(failures[0].service).toBe("openpalm/voice");
+    expect(failures[0].reason).toMatch(/pull access denied/);
+  });
+
+  it("ignores non-error noise (Pulling/Created/Started)", () => {
+    const stderr = [
+      " Network openpalm_default  Created",
+      " Container openpalm-guardian-1  Started",
+      " assistant Pulling",
+    ].join("\n");
+    expect(parseComposeStderr(stderr)).toEqual([]);
+  });
+
+  it("does not treat 'Error response from daemon' as a service name", () => {
+    const stderr = "Error response from daemon: something bad happened";
+    // No service-prefixed line, no pull access denied, no quoted service —
+    // parser should NOT invent a service called "Error".
+    expect(parseComposeStderr(stderr)).toEqual([]);
+  });
+});
+
+describe("summarizeComposeStderr", () => {
+  it("returns first non-empty line", () => {
+    expect(summarizeComposeStderr("\n\n  hello world  \nnext line")).toBe(
+      "hello world"
+    );
+  });
+
+  it("truncates long lines", () => {
+    const long = "x".repeat(800);
+    const out = summarizeComposeStderr(long, 100);
+    expect(out.length).toBe(100);
+    expect(out.endsWith("…")).toBe(true);
+  });
+
+  it("returns empty string for empty input", () => {
+    expect(summarizeComposeStderr("")).toBe("");
+  });
+});

package/src/control-plane/compose-errors.ts

@@ -0,0 +1,117 @@
+/**
+ * Parse `docker compose` stderr for per-service failures.
+ *
+ * `docker compose up -d` reports its progress on stderr — one or more
+ * status lines per service, plus a daemon-level "Error response from daemon"
+ * summary. When a single addon service fails to pull or start, the rest of
+ * the stack often comes up fine, so the only signal that anything is wrong
+ * is whatever appears on stderr. This helper extracts the per-service
+ * failure messages so callers can surface them to operators.
+ */
+export type ComposeServiceFailure = {
+  service: string;
+  reason: string;
+};
+
+/**
+ * Lines we recognise as per-service failure indicators. The compose CLI
+ * has rendered these in a few different shapes across versions:
+ *
+ *   "voice Error pull access denied for openpalm/voice ..."
+ *   " ⠿ voice Error    pull access denied for openpalm/voice ..."
+ *   "Service \"voice\" failed to build: ..."
+ *
+ * We also pick up the bare daemon error and attribute it to the service
+ * named in nearby lines when no service-prefixed line is present.
+ */
+const SERVICE_ERROR_RE = /^[\s⠦⠧⠇⠏⠋⠙⠹⠸⠼⠴⠿✔✘×]*\s*([A-Za-z0-9._-]+)\s+(Error|Failed|failed)\s+(.+)$/;
+const SERVICE_FAILED_QUOTED_RE = /Service\s+["']([A-Za-z0-9._-]+)["']\s+failed[^:]*:\s*(.+)$/i;
+const SERVICE_NOT_FOUND_RE = /no such service:\s*([A-Za-z0-9._-]+)/i;
+const PULL_ACCESS_DENIED_RE = /pull access denied for\s+([^\s,]+)/i;
+
+function pushUnique(
+  failures: ComposeServiceFailure[],
+  entry: ComposeServiceFailure
+): void {
+  const trimmed = { service: entry.service.trim(), reason: entry.reason.trim() };
+  if (!trimmed.service || !trimmed.reason) return;
+  const dup = failures.find(
+    (f) => f.service === trimmed.service && f.reason === trimmed.reason
+  );
+  if (!dup) failures.push(trimmed);
+}
+
+/**
+ * Best-effort extraction of failures from compose stderr.
+ *
+ * - Returns one entry per (service, reason) pair, in stderr order.
+ * - Does NOT fabricate service names: if a daemon error appears without
+ *   any nearby service-prefixed line, the caller's intended-services list
+ *   is used by the route, not this parser.
+ */
+export function parseComposeStderr(stderr: string): ComposeServiceFailure[] {
+  const failures: ComposeServiceFailure[] = [];
+  if (!stderr) return failures;
+
+  const lines = stderr.split(/\r?\n/);
+
+  for (const raw of lines) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line.trim()) continue;
+
+    const quoted = SERVICE_FAILED_QUOTED_RE.exec(line);
+    if (quoted) {
+      pushUnique(failures, { service: quoted[1], reason: quoted[2] });
+      continue;
+    }
+
+    const m = SERVICE_ERROR_RE.exec(line);
+    if (m) {
+      // Skip generic prefixes that look like services but aren't
+      // (e.g. "Error response from daemon ..." would match if the parser
+      // is too lenient — the verb word would be the second token).
+      const candidate = m[1];
+      if (candidate.toLowerCase() === "error") continue;
+      pushUnique(failures, { service: candidate, reason: m[3] });
+      continue;
+    }
+
+    const notFound = SERVICE_NOT_FOUND_RE.exec(line);
+    if (notFound) {
+      pushUnique(failures, {
+        service: notFound[1],
+        reason: `no such service: ${notFound[1]}`,
+      });
+      continue;
+    }
+  }
+
+  // If we still found nothing but the stderr clearly mentions a pull
+  // access denied, surface the offending image as the "service" identifier
+  // — better than swallowing the failure entirely.
+  if (failures.length === 0) {
+    const denied = PULL_ACCESS_DENIED_RE.exec(stderr);
+    if (denied) {
+      pushUnique(failures, {
+        service: denied[1],
+        reason: `pull access denied for ${denied[1]}`,
+      });
+    }
+  }
+
+  return failures;
+}
+
+/**
+ * Summarise compose stderr in a single short line, suitable for log
+ * envelopes / API error messages when no per-service parse succeeded.
+ * Returns the first non-empty stderr line, capped.
+ */
+export function summarizeComposeStderr(stderr: string, maxLen = 500): string {
+  if (!stderr) return "";
+  const first = stderr
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .find((l) => l.length > 0) ?? "";
+  return first.length > maxLen ? first.slice(0, maxLen - 1) + "…" : first;
+}

package/src/control-plane/config-persistence.ts

@@ -12,6 +12,7 @@ import { parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
 import type { ControlPlaneState, ArtifactMeta } from "./types.js";
 import { isChannelAddon } from "./channels.js";
 import { listEnabledAddonIds } from "./registry.js";
+import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
 
 import {
   readCoreCompose,
@@ -69,42 +70,60 @@ export function writeSystemEnv(state: ControlPlaneState): void {
     OP_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
   };
 
+  // Backfill OP_UID/OP_GID when the existing stack.env was written by an
+  // older code path that hard-coded 1000, or when the file was created
+  // with missing/zero values. We only override when the current value is
+  // missing or zero — an operator who manually set OP_UID=2000 (e.g.
+  // because they're running on a host with a non-1000 service account)
+  // must not be silently changed.
+  const parsed = parseEnvFile(systemEnvPath);
+  const ids = resolveOperatorIds(state.homeDir);
+  if (ids) {
+    if (!hasUsableOperatorId(parsed, "OP_UID")) adminManaged.OP_UID = String(ids.uid);
+    if (!hasUsableOperatorId(parsed, "OP_GID")) adminManaged.OP_GID = String(ids.gid);
+  }
+
   const content = mergeEnvContent(base, adminManaged, {
     sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────"
   });
 
-  writeFileSync(systemEnvPath, content);
+  writeFileSync(systemEnvPath, content, { mode: 0o600 });
+  chmodSync(systemEnvPath, 0o600);
 }
 
 function generateFallbackSystemEnv(state: ControlPlaneState): string {
-  const uid = typeof process.getuid === "function" ? (process.getuid() ?? 1000) : 1000;
-  const gid = typeof process.getgid === "function" ? (process.getgid() ?? 1000) : 1000;
+  // Operator UID/GID — auto-detect from OP_HOME owner (or process UID).
+  // Skipped on Windows where containers run in WSL2 and OP_UID has no
+  // meaning on the host process.
+  const ids = resolveOperatorIds(state.homeDir);
+  const idLines: string[] = ids
+    ? [`OP_UID=${ids.uid}`, `OP_GID=${ids.gid}`]
+    : [];
 
   return [
     "# OpenPalm — System Configuration (managed by CLI/admin)",
     "# Auto-generated fallback.",
     "",
     "# ── Authentication ──────────────────────────────────────────────────",
-    `OP_UI_TOKEN=\${OP_UI_TOKEN}`,
-    `OP_ASSISTANT_TOKEN=\${OP_ASSISTANT_TOKEN}`,
+    `OP_UI_LOGIN_PASSWORD=\${OP_UI_LOGIN_PASSWORD}`,
     "",
     "# ── Service Auth ─────────────────────────────────────────────────────",
     "OP_OPENCODE_PASSWORD=",
     "",
     "# ── Paths ──────────────────────────────────────────────────────────",
     `OP_HOME=${state.homeDir}`,
-    `OP_UID=${uid}`,
-    `OP_GID=${gid}`,
+    ...idLines,
     "",
     "# ── Images ──────────────────────────────────────────────────────────",
     `OP_IMAGE_NAMESPACE=${process.env.OP_IMAGE_NAMESPACE ?? "openpalm"}`,
     `OP_IMAGE_TAG=${DEFAULT_IMAGE_TAG}`,
     "",
     "# ── Ports (38XX range) ──────────────────────────────────────────────",
+    "# Guardian is network-only (no host port) — channels reach it via",
+    "# http://guardian:8080 over the channel_lan Docker network.",
     `OP_ASSISTANT_PORT=3800`,
     `OP_ADMIN_PORT=3880`,
     `OP_ADMIN_OPENCODE_PORT=3881`,
-    `OP_GUARDIAN_PORT=3899`,
     ""
   ].join("\n");
 }
@@ -127,8 +146,21 @@ export function discoverStackOverlays(stackDir: string): string[] {
       .filter((e) => e.isDirectory())
       .sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
-      const addonCompose = `${addonsDir}/${entry.name}/compose.yml`;
-      if (existsSync(addonCompose)) files.push(addonCompose);
+      const dir = `${addonsDir}/${entry.name}`;
+      // Pick up compose.yml plus any compose.<variant>.yml sibling
+      // overlays (e.g. compose.cdi.yml generated by /admin/voice on
+      // CDI hosts). Stable sort: compose.yml first, then siblings
+      // alphabetically, so the base file's keys are the defaults and
+      // overlays merge on top in deterministic order.
+      const overlays = readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && /^compose(\.[A-Za-z0-9_-]+)?\.ya?ml$/.test(e.name))
+        .map((e) => e.name)
+        .sort((a, b) => {
+          if (a === "compose.yml" || a === "compose.yaml") return -1;
+          if (b === "compose.yml" || b === "compose.yaml") return 1;
+          return a.localeCompare(b);
+        });
+      for (const name of overlays) files.push(`${dir}/${name}`);
     }
   }
 
@@ -226,7 +258,7 @@ export function writeChannelSecrets(stackDir: string, secrets: Record<string, st
  * (e.g. `/var/run/docker.sock`) are left alone.
  */
 export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
-  const composeFiles = discoverStackOverlays(`${state.homeDir}/stack`);
+  const composeFiles = discoverStackOverlays(state.stackDir);
   if (composeFiles.length === 0) return;
 
   const envVars: Record<string, string> = {
@@ -282,9 +314,13 @@ export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
 export function writeRuntimeFiles(
   state: ControlPlaneState
 ): void {
-  // Write core compose to config/stack/
+  // Write core compose to config/stack/ only on first install —
+  // refreshCoreAssets() is the canonical writer on update.
   mkdirSync(state.stackDir, { recursive: true });
-  writeFileSync(`${state.stackDir}/core.compose.yml`, state.artifacts.compose);
+  const composePath = `${state.stackDir}/core.compose.yml`;
+  if (!existsSync(composePath)) {
+    writeFileSync(composePath, state.artifacts.compose);
+  }
 
   // Load persisted channel HMAC secrets from guardian.env,
   // then generate new ones for new channel addons.

package/src/control-plane/core-assets.ts

@@ -11,6 +11,7 @@
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveStateDir, resolveOpenPalmHome, resolveBackupsDir, resolveStashDir } from "./home.js";
 import { createLogger } from "../logger.js";
 import { sha256 } from "./crypto.js";
@@ -80,15 +81,31 @@ export function seedStashAssets(seeds: Record<string, string>): string[] {
 // ── Asset Refresh (GitHub download) ──────────────────────────────────
 
 const REPO = "itlackey/openpalm";
-const VERSION = process.env.OP_ASSET_VERSION ?? "main";
 
-// Stash seeds are intentionally NOT in this list — they use seedStashAssets()
-// which never overwrites existing files (user edits win on re-install).
+function resolveAssetVersion(): string {
+  if (process.env.OP_ASSET_VERSION) return process.env.OP_ASSET_VERSION;
+  try {
+    const pkgJson = JSON.parse(
+      readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../package.json"), "utf-8")
+    );
+    return `v${pkgJson.version}`;
+  } catch {
+    return "main";
+  }
+}
+const VERSION = resolveAssetVersion();
+
+// Persona files (openpalm.md, system.md), stash seeds, and user-editable config
+// files are intentionally NOT in this list. They are seeded once (never
+// overwritten) via seedOpenPalmDir (skipExisting) or SEEDED_ASSETS below.
 const MANAGED_ASSETS: { relPath: string; githubFilename: string }[] = [
-  { relPath: "config/stack/core.compose.yml",        githubFilename: ".openpalm/config/stack/core.compose.yml" },
-  { relPath: "config/assistant/opencode.jsonc",      githubFilename: ".openpalm/config/assistant/opencode.jsonc" },
-  { relPath: "config/assistant/openpalm.md",         githubFilename: ".openpalm/config/assistant/openpalm.md" },
-  { relPath: "config/assistant/system.md",           githubFilename: ".openpalm/config/assistant/system.md" },
+  { relPath: "config/stack/core.compose.yml", githubFilename: ".openpalm/config/stack/core.compose.yml" },
+];
+
+// Seeded once — written only when the file does not exist yet.
+// User edits always win; upgrade never touches these files.
+const SEEDED_ASSETS: { relPath: string; githubFilename: string }[] = [
+  { relPath: "config/assistant/opencode.jsonc", githubFilename: ".openpalm/config/assistant/opencode.jsonc" },
 ];
 
 async function downloadAsset(filename: string): Promise<string> {
@@ -137,5 +154,44 @@ export async function refreshCoreAssets(): Promise<{
     updated.push(asset.relPath);
   }
 
+  // Seed user-editable assets only when missing — never overwrite.
+  for (const asset of SEEDED_ASSETS) {
+    const targetPath = join(homeDir, asset.relPath);
+    if (existsSync(targetPath)) continue;
+    const freshContent = await downloadAsset(asset.githubFilename);
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, freshContent);
+    updated.push(asset.relPath);
+  }
+
   return { backupDir, updated };
 }
+
+// ── Assistant Persona File Seeding ────────────────────────────────────
+
+/**
+ * Seed assistant persona files (openpalm.md, system.md) into OP_HOME.
+ *
+ * Idempotent: **never overwrites** an existing file — user edits always
+ * win. This preserves the "config/ is user-owned" contract: persona files
+ * are seeded once on first install and never touched again on update.
+ *
+ * `seeds` maps relative path keys (e.g. `"config/assistant/openpalm.md"`)
+ * to file content. Each file is written to `resolveOpenPalmHome()/<relPath>`
+ * only if the file does not already exist.
+ *
+ * Returns the list of relative paths that were actually written (empty on
+ * re-run when every seed already exists on disk).
+ */
+export function seedAssistantPersonaFiles(seeds: Record<string, string>): string[] {
+  const homeDir = resolveOpenPalmHome();
+  const written: string[] = [];
+  for (const [relPath, content] of Object.entries(seeds)) {
+    const targetPath = join(homeDir, relPath);
+    if (existsSync(targetPath)) continue;
+    mkdirSync(dirname(targetPath), { recursive: true });
+    writeFileSync(targetPath, content);
+    written.push(relPath);
+  }
+  return written;
+}

package/src/control-plane/docker.ts

@@ -295,26 +295,37 @@ export async function composeLogs(
   return run(args, undefined);
 }
 
+// 60-minute pull timeout. Voice addon ships a ~2.4 GB image (CPU) /
+// ~7.6 GB (CUDA); on a 1-2 Mbps home connection these legitimately take
+// 30+ minutes. The previous 5-min cap silently killed pulls mid-stream
+// on first install, surfacing as an opaque "pull failed". The wizard's
+// retry layer wraps this, so an actually-hung pull is bounded by the
+// outer retry budget; this just gives any progressing pull room to
+// finish on slow connections.
+const PULL_TIMEOUT_MS = 60 * 60_000;
+
 /**
  * Pull image for a single service.
  */
 export async function composePullService(
   service: string,
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<DockerResult> {
   await runPreflight(options);
   const args = buildComposeArgs(options);
+  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("pull", service);
-  return run(args, undefined, 300_000, collectEnvOverrides(options.envFiles));
+  return run(args, undefined, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }
 
 export async function composePull(
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<DockerResult> {
   await runPreflight(options);
   const args = buildComposeArgs(options);
+  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("pull");
-  return run(args, undefined, 300_000, collectEnvOverrides(options.envFiles));
+  return run(args, undefined, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }
 
 /**

package/src/control-plane/env.ts

@@ -1,5 +1,5 @@
 import { parse as dotenvParse } from 'dotenv';
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, copyFileSync } from 'node:fs';
 
 export function parseEnvContent(content: string): Record<string, string> {
   return dotenvParse(content);
@@ -10,6 +10,9 @@ export function parseEnvFile(filePath: string): Record<string, string> {
   try {
     return dotenvParse(readFileSync(filePath, 'utf-8'));
   } catch {
+    // File is unreadable or malformed — back it up before returning empty so
+    // the next write doesn't silently discard all existing values.
+    try { copyFileSync(filePath, `${filePath}.corrupt-${Date.now()}`); } catch { /* best-effort */ }
     return {};
   }
 }