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

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

@@ -3,58 +3,54 @@
  *
  * Writes and derives live runtime files (compose, env, schemas).
  * Files are validated in-place before writing; rollback is handled by
- * the rollback module (snapshot to ~/.cache/openpalm/rollback/).
+ * the rollback module (snapshot to OP_HOME/data/rollback/).
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, chmodSync } from "node:fs";
-import { dirname } from "node:path";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
 import { parse as yamlParse } from "yaml";
-import { parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
+import { parseEnvContent, parseEnvFile, mergeEnvContent, expandEnvVars } from './env.js';
+import { assertNoSecretLikeStackEnvKeys, isSecretLikeStackEnvKey } from './secrets.js';
+import { ensureSecret } from './secrets-files.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 { SPEC_DEFAULTS } from "./defaults.js";
+import { CURRENT_LAYOUT_VERSION } from "./migrations.js";
 
 import {
   readCoreCompose,
+  readBundledStackAsset,
 } from "./core-assets.js";
 export { sha256, randomHex } from "./crypto.js";
 import { sha256, randomHex } from "./crypto.js";
 
-const DEFAULT_IMAGE_TAG = process.env.OP_IMAGE_TAG ?? "latest";
+const DEFAULT_IMAGE_TAG = "latest";
 
 // ── Env File Management ──────────────────────────────────────────────
 
 /**
  * Return the env files used for docker compose --env-file args.
- * These are the live vault env files.
  *
- * Order: stack.env -> guardian.env
- *
- * Note: `vault/user/user.env` is no longer a
- * compose env_file. User-managed env secrets live in the akm
- * `vault:user` store and are sourced by the assistant entrypoint at
- * container startup. The legacy file is migrated into akm and deleted
- * on upgrade; subsequent `docker compose` invocations must not reference
- * it (compose interpolates `${VAR}` against the merged --env-file
- * contents, and a stale user.env would shadow the akm-sourced values).
+ * Only `knowledge/env/stack.env` (non-secret system config). Secret values
+ * live in `knowledge/secrets/<ENV_KEY>` and are granted to services as Compose
+ * file secrets. The user env (`knowledge/env/user.env`) is NOT a compose
+ * env_file — it is sourced by the assistant entrypoint at container startup.
  */
 export function buildEnvFiles(state: ControlPlaneState): string[] {
   return [
-    `${state.stackDir}/stack.env`,
-    `${state.stackDir}/guardian.env`,
+    `${state.stashDir}/env/stack.env`,
   ].filter(existsSync);
 }
 
 /**
- * Write system-managed values to config/stack/stack.env.
+ * Write system-managed values to knowledge/env/stack.env.
  *
- * Channel HMAC secrets are NOT written here — they belong in guardian.env.
- * Use writeChannelSecrets() for channel secrets.
+ * Secret-like keys are NOT written here — they belong in knowledge/secrets/.
+ * Use ensureChannelSecret() for channel secrets.
  */
 export function writeSystemEnv(state: ControlPlaneState): void {
-  mkdirSync(state.stackDir, { recursive: true });
-
-  const systemEnvPath = `${state.stackDir}/stack.env`;
+  const systemEnvPath = `${state.stashDir}/env/stack.env`;
+  mkdirSync(`${state.stashDir}/env`, { recursive: true, mode: 0o700 });
 
   let base = "";
   if (existsSync(systemEnvPath)) {
@@ -63,11 +59,12 @@ export function writeSystemEnv(state: ControlPlaneState): void {
     base = generateFallbackSystemEnv(state);
   }
 
-  // Preserve existing OP_SETUP_COMPLETE=true
-  const alreadyComplete = /^OP_SETUP_COMPLETE=true$/mi.test(base);
-
+  // Preserve the existing OP_SETUP_COMPLETE flag as-is.
+  // Only the wizard completion path (buildSystemSecretsFromSetup) writes "true".
+  // Defaulting to "false" here ensures a fresh install always shows the wizard.
+  const parsed = parseEnvFile(systemEnvPath);
   const adminManaged: Record<string, string> = {
-    OP_SETUP_COMPLETE: alreadyComplete ? "true" : "false"
+    OP_SETUP_COMPLETE: parsed.OP_SETUP_COMPLETE === "true" ? "true" : "false",
   };
 
   // Backfill OP_UID/OP_GID when the existing stack.env was written by an
@@ -76,13 +73,20 @@ export function writeSystemEnv(state: ControlPlaneState): void {
   // 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);
   }
 
+  // Backfill OP_HOME when missing — compose files reference ${OP_HOME}
+  // for all volume mounts. Without this, Docker Compose defaults to blank.
+  if (!parsed.OP_HOME) adminManaged.OP_HOME = state.homeDir;
+
+  base = stripSecretLikeEnvKeys(base);
+  assertNoSecretLikeStackEnvKeys(parseEnvContent(base));
+  assertNoSecretLikeStackEnvKeys(adminManaged);
+
   const content = mergeEnvContent(base, adminManaged, {
     sectionHeader: "# ── Admin-managed ──────────────────────────────────────────────────"
   });
@@ -91,6 +95,19 @@ export function writeSystemEnv(state: ControlPlaneState): void {
   chmodSync(systemEnvPath, 0o600);
 }
 
+function stripSecretLikeEnvKeys(content: string): string {
+  return content
+    .split('\n')
+    .filter((line) => {
+      let trimmed = line.trim();
+      if (trimmed.startsWith('export ')) trimmed = trimmed.slice(7).trimStart();
+      const eq = trimmed.indexOf('=');
+      if (eq <= 0) return true;
+      return !isSecretLikeStackEnvKey(trimmed.slice(0, eq).trim());
+    })
+    .join('\n');
+}
+
 function generateFallbackSystemEnv(state: ControlPlaneState): string {
   // 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
@@ -104,12 +121,6 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     "# OpenPalm — System Configuration (managed by CLI/admin)",
     "# Auto-generated fallback.",
     "",
-    "# ── Authentication ──────────────────────────────────────────────────",
-    `OP_UI_LOGIN_PASSWORD=\${OP_UI_LOGIN_PASSWORD}`,
-    "",
-    "# ── Service Auth ─────────────────────────────────────────────────────",
-    "OP_OPENCODE_PASSWORD=",
-    "",
     "# ── Paths ──────────────────────────────────────────────────────────",
     `OP_HOME=${state.homeDir}`,
     ...idLines,
@@ -118,12 +129,17 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
     `OP_IMAGE_NAMESPACE=${process.env.OP_IMAGE_NAMESPACE ?? "openpalm"}`,
     `OP_IMAGE_TAG=${DEFAULT_IMAGE_TAG}`,
     "",
+    "# ── Layout (on-disk schema version; managed by the migration harness) ──",
+    `OP_LAYOUT_VERSION=${CURRENT_LAYOUT_VERSION}`,
+    "",
+    "# ── Enabled addons (comma-separated; managed via the Add-ons UI / CLI) ──",
+    "OP_ENABLED_ADDONS=",
+    "",
     "# ── 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_ASSISTANT_PORT=${SPEC_DEFAULTS.ports.assistant}`,
+    `OP_HOST_UI_PORT=${SPEC_DEFAULTS.ports.hostUi}`,
     ""
   ].join("\n");
 }
@@ -131,37 +147,25 @@ function generateFallbackSystemEnv(state: ControlPlaneState): string {
 // ── Stack Overlay Discovery ────────────────────────────────────────────
 
 /**
- * Discover compose overlays from the stack directory.
- * Returns full paths: [stack/core.compose.yml, stack/addons/{name}/compose.yml].
+ * Discover active compose overlays.
+ * Returns the fixed compose stack: core, services, channels, and custom.
+ * First-party services are profile-gated inside services.compose.yml and
+ * channels.compose.yml.
+ *
+ * Host AKM sharing is NOT a compose overlay: the assistant always mounts
+ * `/host-stash` (core.compose.yml, with an empty-dir fallback), and "sharing"
+ * is purely a writable secondary source entry in config/akm/config.json. No
+ * conditional overlay file is involved.
  */
-export function discoverStackOverlays(stackDir: string): string[] {
+export function discoverStackOverlays(stackDir: string, _homeDir?: string): string[] {
   const files: string[] = [];
 
   const coreYml = `${stackDir}/core.compose.yml`;
   if (existsSync(coreYml)) files.push(coreYml);
 
-  const addonsDir = `${stackDir}/addons`;
-  if (existsSync(addonsDir)) {
-    const entries = readdirSync(addonsDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .sort((a, b) => a.name.localeCompare(b.name));
-    for (const entry of entries) {
-      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}`);
-    }
+  for (const name of ['services.compose.yml', 'channels.compose.yml', 'custom.compose.yml']) {
+    const composePath = `${stackDir}/${name}`;
+    if (existsSync(composePath)) files.push(composePath);
   }
 
   return files;
@@ -192,79 +196,38 @@ export function buildRuntimeFileMeta(artifacts: {
 }
 
 // ── Channel Secrets ────────────────────────────────────────────────────
-// Channel HMAC secrets live exclusively in vault/stack/guardian.env.
-
-const CHANNEL_SECRET_RE = /^CHANNEL_([A-Z0-9_]+)_SECRET$/;
-
-/** Extract channel secrets from parsed env entries. */
-function extractChannelSecrets(parsed: Record<string, string>): Record<string, string> {
-  const result: Record<string, string> = {};
-  for (const [key, value] of Object.entries(parsed)) {
-    const match = key.match(CHANNEL_SECRET_RE);
-    if (match?.[1] && value) result[match[1].toLowerCase()] = value;
-  }
-  return result;
-}
 
-/**
- * Read channel HMAC secrets from config/stack/guardian.env.
- */
-export function readChannelSecrets(stackDir: string): Record<string, string> {
-  return extractChannelSecrets(parseEnvFile(`${stackDir}/guardian.env`));
+export function channelSecretName(addon: string): string {
+  return `channel_${addon.replace(/-/g, '_')}_secret`;
 }
 
-/**
- * Write channel HMAC secrets to state/guardian.env.
- * Merges with existing content; does not overwrite unrelated entries.
- */
-export function writeChannelSecrets(stackDir: string, secrets: Record<string, string>): void {
-  const guardianPath = `${stackDir}/guardian.env`;
-  mkdirSync(stackDir, { recursive: true });
-
-  let base = "";
-  if (existsSync(guardianPath)) {
-    base = readFileSync(guardianPath, "utf-8");
-  } else {
-    base = "# Guardian channel HMAC secrets — managed by openpalm\n";
-  }
-
-  const updates: Record<string, string> = {};
-  for (const [ch, secret] of Object.entries(secrets)) {
-    updates[`CHANNEL_${ch.toUpperCase()}_SECRET`] = secret;
-  }
-
-  const content = mergeEnvContent(base, updates);
-  writeFileSync(guardianPath, content, { mode: 0o600 });
-  // Ensure correct permissions even if file already existed with wrong mode
-  chmodSync(guardianPath, 0o600);
+export function ensureChannelSecret(stackDir: string, addon: string): string {
+  return ensureSecret(stackDir, channelSecretName(addon), () => randomHex(16));
 }
 
 // ── Volume Mount Targets ───────────────────────────────────────────────
 
 /**
- * Parse all enabled compose files and pre-create every host-side volume
- * mount target as the current user. This prevents Docker from creating
- * them as root-owned, which causes EACCES inside non-root containers.
- *
- * For file mounts (basename contains a `.`), creates an empty file.
- * For directory mounts (basename has no `.`), creates the directory.
- *
- * Heuristic: a basename containing a `.` is treated as a file. This
- * intentionally includes leading-dot files (e.g. `.env`) because Docker
- * bind mounts to them must be regular files. Bare directory names like
- * `stack` or `addons` lack extensions and are created as directories.
+ * Parse enabled compose files and pre-create host-side volume mount
+ * targets under OP_HOME as the current user. This prevents Docker from
+ * creating them as root-owned, which causes EACCES inside non-root
+ * containers.
  *
  * Only mount sources under `state.homeDir` are touched; external paths
  * (e.g. `/var/run/docker.sock`) are left alone.
+ *
+ * The file-vs-directory distinction is best-effort and only applies to
+ * explicit OP_HOME paths.
  */
 export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
-  const composeFiles = discoverStackOverlays(state.stackDir);
+  const composeFiles = discoverStackOverlays(state.stackDir, state.homeDir);
   if (composeFiles.length === 0) return;
 
   const envVars: Record<string, string> = {
     ...(process.env as Record<string, string>),
-    ...parseEnvFile(`${state.stackDir}/stack.env`),
+    ...parseEnvFile(`${state.stashDir}/env/stack.env`),
   };
+  const homeRoot = resolvePath(state.homeDir);
 
   for (const file of composeFiles) {
     let doc: Record<string, unknown>;
@@ -291,18 +254,20 @@ export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
 
         const hostPath = expandEnvVars(rawSource, envVars);
         if (!hostPath || !hostPath.startsWith('/')) continue;
-        if (existsSync(hostPath)) continue;
+        const resolvedHostPath = resolvePath(hostPath);
+        if (!resolvedHostPath.startsWith(`${homeRoot}/`) && resolvedHostPath !== homeRoot) continue;
+        if (existsSync(resolvedHostPath)) continue;
 
-        // A basename containing a `.` (anywhere, including leading) is a file.
-        // Bare names like `stack` or `data` are directories.
-        const basename = hostPath.split('/').pop() ?? '';
+        // Only create mounts under OP_HOME. For now, treat existing explicit
+        // file paths as files and directory paths as directories.
+        const basename = resolvedHostPath.split('/').pop() ?? '';
         const isFile = basename.includes('.');
 
         if (isFile) {
-          mkdirSync(dirname(hostPath), { recursive: true });
-          writeFileSync(hostPath, '');
+          mkdirSync(dirname(resolvedHostPath), { recursive: true });
+          writeFileSync(resolvedHostPath, '');
         } else {
-          mkdirSync(hostPath, { recursive: true });
+          mkdirSync(resolvedHostPath, { recursive: true });
         }
       }
     }
@@ -322,24 +287,25 @@ export function writeRuntimeFiles(
     writeFileSync(composePath, state.artifacts.compose);
   }
 
-  // Load persisted channel HMAC secrets from guardian.env,
-  // then generate new ones for new channel addons.
-  const channelSecrets = readChannelSecrets(state.stackDir);
+  for (const name of ['services.compose.yml', 'channels.compose.yml', 'custom.compose.yml']) {
+    const path = `${state.stackDir}/${name}`;
+    if (!existsSync(path)) writeFileSync(path, readBundledStackAsset(name));
+  }
+
   for (const addon of listEnabledAddonIds(state.homeDir)) {
-    const composePath = `${state.stackDir}/addons/${addon}/compose.yml`;
-    if (isChannelAddon(composePath) && !channelSecrets[addon]) {
-      channelSecrets[addon] = randomHex(16);
+    if (['api', 'chat', 'discord', 'slack'].includes(addon)) {
+      for (const channel of ['api', 'chat', 'discord', 'slack']) {
+        ensureChannelSecret(state.stackDir, channel);
+      }
+      break;
     }
   }
 
-  // Write channel secrets to guardian.env (the canonical source)
-  writeChannelSecrets(state.stackDir, channelSecrets);
-
-  // Write system.env (no channel secrets — those live in guardian.env)
+  // Write stack.env (no secrets — those live in knowledge/secrets/)
   writeSystemEnv(state);
 
   // Ensure state directory exists
-  mkdirSync(state.stateDir, { recursive: true });
+  mkdirSync(state.dataDir, { recursive: true });
 
   state.artifactMeta = buildRuntimeFileMeta(state.artifacts);
 }

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

@@ -5,19 +5,24 @@
  *   stack/              — compose runtime assets (core.compose.yml)
  *
  * This module manages runtime-owned core files only.
- * Registry catalog refresh is handled separately in registry.ts.
+ * Addon compose bundle generation and registry catalog refresh are handled
+ * separately in registry.ts.
  * Env validation has moved to `akm vault` + the in-house redactor — the
  * historical `.env.schema` files (varlock format) were retired in #391.
  */
 import { mkdirSync, writeFileSync, readFileSync, existsSync, copyFileSync } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveStateDir, resolveOpenPalmHome, resolveBackupsDir, resolveStashDir } from "./home.js";
+import { resolveDataDir, resolveOpenPalmHome, resolveBackupsDir } from "./home.js";
 import { createLogger } from "../logger.js";
 import { sha256 } from "./crypto.js";
 
 const logger = createLogger("core-assets");
 
+function bundledAssetPath(relPath: string): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '../../../../.openpalm', relPath);
+}
+
 // ── Core Compose (stack/) ─────────────────────────────────────────────
 
 export function ensureCoreCompose(): string {
@@ -27,90 +32,69 @@ export function ensureCoreCompose(): string {
 }
 
 export function readCoreCompose(): string {
-  return readFileSync(`${resolveOpenPalmHome()}/config/stack/core.compose.yml`, "utf-8");
+  const livePath = `${resolveOpenPalmHome()}/config/stack/core.compose.yml`;
+  if (existsSync(livePath)) {
+    return readFileSync(livePath, 'utf-8');
+  }
+  return readFileSync(bundledAssetPath('config/stack/core.compose.yml'), 'utf-8');
+}
+
+export function readBundledStackAsset(name: string): string {
+  return readFileSync(bundledAssetPath(`config/stack/${name}`), 'utf-8');
 }
 
 // ── OpenCode System Config ──────────────────────────────────────────
 
 export function ensureOpenCodeSystemConfig(): void {
-  const dir = `${resolveStateDir()}/assistant`;
+  const dir = `${resolveDataDir()}/assistant`;
   mkdirSync(dir, { recursive: true });
 }
 
 // ── Shared akm stash (skills / commands / agents) ────────────────────
 
-/**
- * Seed the shared akm stash with built-in skills / commands / agents.
- *
- * Idempotent: **never overwrites** an existing file — user edits to a
- * seeded asset always win, which preserves the same "config doesn't
- * overwrite user edits" contract that governs the rest of OP_HOME.
- *
- * Returns the list of stash-relative paths that were actually written
- * (empty on re-run when every seed already exists on disk).
- *
- * `seeds` is a map of stash-relative path → file content. Keys MUST be
- * forward-slash relative paths that stay inside `data/stash/`; any key
- * that escapes the stash directory after canonicalization throws,
- * preventing a malicious caller from writing arbitrary files. Source of
- * truth for the seeded files lives at `.openpalm/stash/` in the
- * repo; the CLI embeds them at build time and passes the embedded
- * record directly.
- */
-export function seedStashAssets(seeds: Record<string, string>): string[] {
-  const stashDir = resolveStashDir();
-  const normalizedStash = resolve(stashDir);
-  const written: string[] = [];
-  for (const [relPath, content] of Object.entries(seeds)) {
-    const targetPath = join(stashDir, relPath);
-    const normalizedTarget = resolve(targetPath);
-    if (
-      normalizedTarget !== normalizedStash &&
-      !normalizedTarget.startsWith(normalizedStash + sep)
-    ) {
-      throw new Error(`Seed path escapes stash dir: ${relPath}`);
-    }
-    if (existsSync(targetPath)) continue;
-    mkdirSync(dirname(targetPath), { recursive: true });
-    writeFileSync(targetPath, content);
-    written.push(relPath);
-  }
-  return written;
-}
-
 // ── Asset Refresh (GitHub download) ──────────────────────────────────
 
 const REPO = "itlackey/openpalm";
 
-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")
+// The version to download assets for is ALWAYS passed in by the caller (the
+// upgrade flow resolves the canonical platform tag — the newest published
+// `openpalm/assistant` Docker tag, e.g. "v0.11.0-rc.6" — and threads it here).
+// This module intentionally does NOT resolve the version itself: no env var, no
+// `import.meta.url` package.json read (which breaks when the lib is bundled into
+// the UI/electron), and never a silent "main" fallback (main's asset layout can
+// differ from a released install). Bundler-agnostic by construction.
+
+function normalizeAssetRef(version: string): string {
+  const v = version.trim();
+  if (!v) {
+    throw new Error(
+      "Cannot download OpenPalm stack assets: no version provided. " +
+      "The caller must pass the target release tag (e.g. \"v0.11.0-rc.6\")."
     );
-    return `v${pkgJson.version}`;
-  } catch {
-    return "main";
   }
+  // GitHub release/raw refs are `vX.Y.Z`; accept a bare semver and add the `v`.
+  return /^\d/.test(v) ? `v${v}` : v;
 }
-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/stack/services.compose.yml", githubFilename: ".openpalm/config/stack/services.compose.yml" },
+  { relPath: "config/stack/channels.compose.yml", githubFilename: ".openpalm/config/stack/channels.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" },
+  { relPath: "config/stack/custom.compose.yml", githubFilename: ".openpalm/config/stack/custom.compose.yml" },
 ];
 
-async function downloadAsset(filename: string): Promise<string> {
-  const releaseUrl = `https://github.com/${REPO}/releases/download/${VERSION}/${filename}`;
-  const rawUrl = `https://raw.githubusercontent.com/${REPO}/${VERSION}/${filename}`;
+async function downloadAsset(filename: string, version: string): Promise<string> {
+  const releaseUrl = `https://github.com/${REPO}/releases/download/${version}/${filename}`;
+  const rawUrl = `https://raw.githubusercontent.com/${REPO}/${version}/${filename}`;
 
   for (const url of [releaseUrl, rawUrl]) {
     try {
@@ -120,19 +104,20 @@ async function downloadAsset(filename: string): Promise<string> {
       // try next URL
     }
   }
-  throw new Error(`Failed to download ${filename} from GitHub (tried release and raw URLs for version "${VERSION}")`);
+  throw new Error(`Failed to download ${filename} from GitHub (tried release and raw URLs for version "${version}")`);
 }
 
-export async function refreshCoreAssets(): Promise<{
+export async function refreshCoreAssets(version: string): Promise<{
   backupDir: string | null;
   updated: string[];
 }> {
+  const ref = normalizeAssetRef(version);
   const homeDir = resolveOpenPalmHome();
   const updated: string[] = [];
   let backupDir: string | null = null;
 
   for (const asset of MANAGED_ASSETS) {
-    const freshContent = await downloadAsset(asset.githubFilename);
+    const freshContent = await downloadAsset(asset.githubFilename, ref);
     const targetPath = join(homeDir, asset.relPath);
 
     if (existsSync(targetPath)) {
@@ -158,7 +143,7 @@ export async function refreshCoreAssets(): Promise<{
   for (const asset of SEEDED_ASSETS) {
     const targetPath = join(homeDir, asset.relPath);
     if (existsSync(targetPath)) continue;
-    const freshContent = await downloadAsset(asset.githubFilename);
+    const freshContent = await downloadAsset(asset.githubFilename, ref);
     mkdirSync(dirname(targetPath), { recursive: true });
     writeFileSync(targetPath, freshContent);
     updated.push(asset.relPath);

package/src/control-plane/defaults.ts

@@ -0,0 +1,16 @@
+/**
+ * Stack defaults (ports + image). Formerly in stack-spec.ts; kept after the
+ * stack.yml removal because these are the canonical fallback values used when a
+ * key is absent from stack.env.
+ */
+export const SPEC_DEFAULTS = {
+  ports: {
+    assistant: 3800,
+    hostUi: 3880,
+    assistantSsh: 2222,
+  },
+  image: {
+    namespace: "openpalm",
+    tag: "latest",
+  },
+} as const;