@openpalm/lib 0.11.0-rc.6 → 0.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpalm/lib",
-  "version": "0.11.0-rc.6",
+  "version": "0.11.1",
   "license": "MPL-2.0",
   "type": "module",
   "description": "Shared control-plane library for OpenPalm — lifecycle, staging, secrets, channels, connections, scheduler",

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

@@ -47,7 +47,9 @@ function seedAddon(name: string): void {
   const stackDir = join(tempDir, "config", "stack");
   mkdirSync(stackDir, { recursive: true });
   writeFileSync(join(stackDir, "channels.compose.yml"), `services:\n  ${name}:\n    profiles: [\"addon.${name}\"]\n    image: test\n`);
-  writeFileSync(join(stackDir, "stack.yml"), `version: 2\naddons:\n  - ${name}\n`);
+  const envDir = join(tempDir, "knowledge", "env");
+  mkdirSync(envDir, { recursive: true });
+  writeFileSync(join(envDir, "stack.env"), `OP_ENABLED_ADDONS=${name}\n`);
 }
 
 beforeEach(() => {
@@ -70,7 +72,7 @@ describe("buildComposeOptions", () => {
     expect(opts.files[0]).toContain("core.compose.yml");
   });
 
-  it("includes fixed channel compose and profile from stack.yml", () => {
+  it("includes fixed channel compose and profile from OP_ENABLED_ADDONS", () => {
     seedCoreCompose();
     seedAddon("chat");
 

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

@@ -10,9 +10,8 @@ import type { ControlPlaneState } from "./types.js";
 import { buildComposeFileList } from "./lifecycle.js";
 import { buildEnvFiles } from "./config-persistence.js";
 import { resolveComposeProjectName } from "./docker.js";
-import { parseEnvFile } from "./env.js";
+import { parseEnvFile, parseEnabledAddons } from "./env.js";
 import { canonicalAddonProfileSelection } from "./profile-ids.js";
-import { listStackSpecAddons } from "./stack-spec.js";
 
 // ── Types ────────────────────────────────────────────────────────────────
 
@@ -45,7 +44,7 @@ export function resolveActiveProfiles(state: ControlPlaneState): string[] {
     if (ollamaProfile) profiles.push(ollamaProfile);
   }
 
-  for (const addon of listStackSpecAddons(state.stackDir)) {
+  for (const addon of parseEnabledAddons(env.OP_ENABLED_ADDONS)) {
     if (addon === 'voice') {
       profiles.push(canonicalAddonProfileSelection('voice', env.OP_VOICE_PROFILE ?? '') || 'addon.voice.cpu');
     } else if (addon === 'ollama') {

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

@@ -5,16 +5,18 @@
  * Files are validated in-place before writing; rollback is handled by
  * the rollback module (snapshot to OP_HOME/data/rollback/).
  */
-import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, chownSync } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
 import { parse as yamlParse } from "yaml";
+import { createLogger } from "../logger.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 { listEnabledAddonIds } from "./registry.js";
-import { resolveOperatorIds, hasUsableOperatorId } from "./operator-ids.js";
-import { SPEC_DEFAULTS } from "./stack-spec.js";
+import { resolveOperatorIds, hasUsableOperatorId, type OperatorIds } from "./operator-ids.js";
+import { SPEC_DEFAULTS } from "./defaults.js";
+import { CURRENT_LAYOUT_VERSION } from "./migrations.js";
 
 import {
   readCoreCompose,
@@ -25,6 +27,8 @@ import { sha256, randomHex } from "./crypto.js";
 
 const DEFAULT_IMAGE_TAG = "latest";
 
+const logger = createLogger("config-persistence");
+
 // ── Env File Management ──────────────────────────────────────────────
 
 /**
@@ -128,6 +132,12 @@ 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.",
@@ -216,6 +226,13 @@ export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
   const composeFiles = discoverStackOverlays(state.stackDir, state.homeDir);
   if (composeFiles.length === 0) return;
 
+  // Resolve the operator UID/GID compose runs containers as (`user:`), so we
+  // can chown the dirs we pre-create to match. Without this, dirs created by
+  // a root-running install (or a host UID that differs from the forced
+  // container UID) are unwritable inside the non-root container — on OrbStack
+  // real UIDs are preserved, so e.g. ollama's mkdir is denied (issue #452).
+  const operatorIds = resolveOperatorIds(state.homeDir);
+
   const envVars: Record<string, string> = {
     ...(process.env as Record<string, string>),
     ...parseEnvFile(`${state.stashDir}/env/stack.env`),
@@ -257,16 +274,40 @@ export function ensureComposeVolumeTargets(state: ControlPlaneState): void {
         const isFile = basename.includes('.');
 
         if (isFile) {
-          mkdirSync(dirname(resolvedHostPath), { recursive: true });
+          const parent = dirname(resolvedHostPath);
+          mkdirSync(parent, { recursive: true });
           writeFileSync(resolvedHostPath, '');
+          chownVolumeTarget(parent, operatorIds);
+          chownVolumeTarget(resolvedHostPath, operatorIds);
         } else {
           mkdirSync(resolvedHostPath, { recursive: true });
+          chownVolumeTarget(resolvedHostPath, operatorIds);
         }
       }
     }
   }
 }
 
+/**
+ * chown a just-created bind-mount target to the operator UID/GID so the
+ * non-root container (`user: ${OP_UID}:${OP_GID}`) can write to it.
+ *
+ * No-op on Windows (chown is meaningless there) or when no operator can be
+ * resolved. A failure (e.g. not the owner) is logged and swallowed — the
+ * mkdir already succeeded and Docker Desktop's gRPC-FUSE masks ownership
+ * anyway, so a chown failure must not abort the install.
+ */
+function chownVolumeTarget(path: string, operatorIds: OperatorIds | null): void {
+  if (process.platform === "win32" || !operatorIds) return;
+  try {
+    chownSync(path, operatorIds.uid, operatorIds.gid);
+  } catch (error) {
+    logger.warn(
+      `Could not chown volume target ${path} to ${operatorIds.uid}:${operatorIds.gid}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
 // ── Persistence (direct-write to live paths) ────────────────────────
 
 export function writeRuntimeFiles(

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

@@ -56,18 +56,25 @@ export function ensureOpenCodeSystemConfig(): void {
 
 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
@@ -85,9 +92,9 @@ const SEEDED_ASSETS: { relPath: string; githubFilename: string }[] = [
   { 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 {
@@ -97,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)) {
@@ -135,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;

package/src/control-plane/env.ts

@@ -82,6 +82,21 @@ export function upsertEnvValue(content: string, key: string, value: string): str
   return `${content}${suffix}${line}\n`;
 }
 
+/** Addon name shape (matches the former stack.yml validation). */
+export const ADDON_NAME_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+
+/**
+ * Parse the `OP_ENABLED_ADDONS` stack.env value (comma-separated) into a
+ * validated, de-duplicated, sorted list of addon ids. Replaces the former
+ * stack.yml `addons[]` array as the authoritative enabled-addon record.
+ */
+export function parseEnabledAddons(value: string | undefined): string[] {
+  if (!value) return [];
+  return [...new Set(
+    value.split(',').map((v) => v.trim()).filter((v) => ADDON_NAME_RE.test(v)),
+  )].sort();
+}
+
 export const RELEASE_TAG_REGEX = /^v?\d+\.\d+\.\d+(?:[-+](?:[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*))?$/;
 
 /**

package/src/control-plane/hardware-detect.ts

@@ -0,0 +1,114 @@
+// Host GPU / VRAM detection for setup recommendations.
+//
+// Data-driven on purpose: each entry in GPU_PROBES is a vendor + a command to
+// run + a pure parser. Adding a new accelerator (Intel Arc, Apple Metal, a new
+// rocm/CUDA query, etc.) is a one-entry change here — nothing downstream needs to
+// know. detectGpu() runs every probe, ignores the ones whose tool is absent, and
+// returns the single best (highest-VRAM) result, or null when no GPU is found.
+
+import { execFile } from "node:child_process";
+import { createLogger } from "../logger.js";
+
+const logger = createLogger("hardware-detect");
+
+export type GpuVendor = "nvidia" | "amd" | "unknown";
+
+export type GpuInfo = {
+  vendor: GpuVendor;
+  /** Human-readable adapter name, e.g. "NVIDIA GeForce RTX 4090". */
+  name: string;
+  /** Total VRAM in MiB. 0 when the tool reported the GPU but not its memory. */
+  vramMb: number;
+};
+
+type GpuProbe = {
+  vendor: GpuVendor;
+  command: string;
+  args: string[];
+  /** Pure parser: tool stdout -> detected GPUs. Must not throw. */
+  parse: (stdout: string) => GpuInfo[];
+};
+
+/** Parse `nvidia-smi --query-gpu=name,memory.total --format=csv,noheader,nounits`. */
+export function parseNvidiaSmi(stdout: string): GpuInfo[] {
+  return stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line): GpuInfo | null => {
+      // "NVIDIA GeForce RTX 4090, 24564"
+      const idx = line.lastIndexOf(",");
+      if (idx === -1) return null;
+      const name = line.slice(0, idx).trim();
+      const vramMb = Number.parseInt(line.slice(idx + 1).trim(), 10);
+      if (!name || !Number.isFinite(vramMb)) return null;
+      return { vendor: "nvidia", name, vramMb };
+    })
+    .filter((g): g is GpuInfo => g !== null);
+}
+
+/** Parse `rocm-smi --showmeminfo vram --showproductname --json`. */
+export function parseRocmSmi(stdout: string): GpuInfo[] {
+  let doc: Record<string, Record<string, string>>;
+  try {
+    doc = JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+  const out: GpuInfo[] = [];
+  for (const card of Object.values(doc)) {
+    if (!card || typeof card !== "object") continue;
+    // rocm-smi key names drift across versions — match loosely.
+    const vramKey = Object.keys(card).find((k) => /vram total memory/i.test(k));
+    const nameKey = Object.keys(card).find((k) => /product name|card series|gfx/i.test(k));
+    const bytes = vramKey ? Number.parseInt(String(card[vramKey]).trim(), 10) : NaN;
+    const vramMb = Number.isFinite(bytes) ? Math.round(bytes / (1024 * 1024)) : 0;
+    out.push({ vendor: "amd", name: nameKey ? String(card[nameKey]).trim() : "AMD GPU", vramMb });
+  }
+  return out;
+}
+
+const GPU_PROBES: GpuProbe[] = [
+  {
+    vendor: "nvidia",
+    command: "nvidia-smi",
+    args: ["--query-gpu=name,memory.total", "--format=csv,noheader,nounits"],
+    parse: parseNvidiaSmi,
+  },
+  {
+    vendor: "amd",
+    command: "rocm-smi",
+    args: ["--showmeminfo", "vram", "--showproductname", "--json"],
+    parse: parseRocmSmi,
+  },
+];
+
+function run(command: string, args: string[], timeoutMs = 3_000): Promise<string | null> {
+  return new Promise((resolve) => {
+    execFile(command, args, { timeout: timeoutMs }, (err, stdout) => {
+      // ENOENT (tool not installed) and any non-zero exit -> not available.
+      resolve(err ? null : stdout?.toString() ?? "");
+    });
+  });
+}
+
+/**
+ * Detect the host's best GPU. Returns the highest-VRAM adapter across all probes,
+ * or null when none is found. Never throws.
+ */
+export async function detectGpu(): Promise<GpuInfo | null> {
+  const found: GpuInfo[] = [];
+  await Promise.all(
+    GPU_PROBES.map(async (probe) => {
+      const stdout = await run(probe.command, probe.args);
+      if (stdout === null) return;
+      try {
+        found.push(...probe.parse(stdout));
+      } catch (error) {
+        logger.debug("gpu probe parse failed", { vendor: probe.vendor, error: String(error) });
+      }
+    }),
+  );
+  if (found.length === 0) return null;
+  return found.reduce((best, g) => (g.vramMb > best.vramMb ? g : best));
+}

package/src/control-plane/home.ts

@@ -3,11 +3,11 @@
  *
  * Single ~/.openpalm/ root:
  *   config/    — user-editable config + system config files (akm/)
- *   config/stack/ — compose runtime + stack config (stack.env, stack.yml, auth.json, fixed compose files)
+ *   config/stack/ — fixed compose files (no stack.env/secrets/stack.yml)
  *   data/      — persistent service data, logs, backups, rollback
- *   knowledge/ — akm knowledge (env, secrets, tasks)
+ *   knowledge/ — akm knowledge (env, secrets, tasks); env/stack.env is the
+ *                authoritative stack composition + versions record
  *   workspace/ — shared assistant work area
- *   config/stack/ — compose runtime assets + stack config (stack.env, stack.yml)
  */
 import { mkdirSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";

package/src/control-plane/install-edge-cases.test.ts

@@ -26,7 +26,6 @@ import {
 } from "./setup.js";
 import type { SetupSpec, SetupConnection } from "./setup.js";
 import type { ControlPlaneState } from "./types.js";
-import { STACK_SPEC_FILENAME, readStackSpec } from "./stack-spec.js";
 import { readSecret } from './secrets-files.js';
 
 // ── Helpers ──────────────────────────────────────────────────────────────
@@ -313,11 +312,6 @@ describe("Existing Install", () => {
       })
     );
 
-    // stack.yml is just a version marker now
-    const specAfterSecond = readStackSpec(stackDir);
-    expect(specAfterSecond).not.toBeNull();
-    expect(specAfterSecond!.version).toBe(2);
-
     const auth = JSON.parse(readFileSync(join(homeDir, "knowledge", "secrets", "auth.json"), "utf-8"));
     expect(auth.groq.key).toBe("gsk-test-key-456");
   });
@@ -426,12 +420,6 @@ describe("Broken/Corrupt State", () => {
     }
   });
 
-  // Scenario 13: Missing stack.yml returns null
-  it("readStackSpec returns null when stack.yml missing", () => {
-    const spec = readStackSpec(stackDir);
-    expect(spec).toBeNull();
-  });
-
   // Scenario 14: knowledge/tasks dir missing (performSetup should recreate it via ensureHomeDirs)
   it("performSetup creates missing subdirectories", async () => {
     // Seed the minimal env files first
@@ -453,16 +441,6 @@ describe("Broken/Corrupt State", () => {
     expect(existsSync(join(homeDir, "knowledge", "tasks"))).toBe(true);
   });
 
-  // Scenario 15: openpalm.yaml with old version
-  it("readStackSpec returns null for version 1 spec", () => {
-    writeFileSync(
-      join(stackDir, STACK_SPEC_FILENAME),
-      "version: 1\nconnections: []\n"
-    );
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).toBeNull();
-  });
 });
 
 // =====================================================================
@@ -562,10 +540,6 @@ describe("Setup Input Variations", () => {
 
     const result = await performSetup(input);
     expect(result.ok).toBe(true);
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
   });
 
   // Scenario 21: Multiple providers map to correct env vars
@@ -626,12 +600,9 @@ describe("performSetup end-to-end artifacts", () => {
     rmSync(homeDir, { recursive: true, force: true });
   });
 
-  it("writes stack.yml and readStackSpec returns v2", async () => {
+  it("does not create a stack.yml (addon state lives in stack.env)", async () => {
     await performSetup(makeValidSpec());
-
-    const spec = readStackSpec(stackDir);
-    expect(spec).not.toBeNull();
-    expect(spec!.version).toBe(2);
+    expect(existsSync(join(stackDir, "stack.yml"))).toBe(false);
   });
 
   it("writes akm config with embedding dims from setup spec", async () => {

package/src/control-plane/lifecycle.ts

@@ -172,10 +172,7 @@ function resolveNewestDockerTag(payload: unknown): string | null {
   return fallback;
 }
 
-export async function updateStackEnvToLatestImageTag(state: ControlPlaneState): Promise<{
-  namespace: string;
-  tag: string;
-}> {
+function resolveImageNamespace(state: ControlPlaneState): string {
   const systemEnvPath = `${state.stashDir}/env/stack.env`;
   const parsed = parseEnvFile(systemEnvPath);
   const namespace = (parsed.OP_IMAGE_NAMESPACE ?? process.env.OP_IMAGE_NAMESPACE ?? "openpalm").trim().toLowerCase();
@@ -183,11 +180,21 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
   if (!IMAGE_NAMESPACE_RE.test(namespace)) {
     throw new Error(`Invalid image namespace in system.env: ${namespace}`);
   }
+  return namespace;
+}
 
-  // `assistant` is the version-of-record image: all platform images
-  // (assistant, guardian, channel, voice) are published in lockstep under the
-  // same OP_IMAGE_TAG, so its newest tag is the canonical platform version.
-
+/**
+ * Resolve the newest published platform tag from the Docker registry.
+ *
+ * `assistant` is the version-of-record image: all platform images
+ * (assistant, guardian, channel, voice) are published in lockstep under the
+ * same OP_IMAGE_TAG, so its newest tag is the canonical platform version.
+ *
+ * Used both to auto-detect during "Update now" and to resolve a requested
+ * `latest` selection into a concrete release tag before fetching stack assets
+ * (GitHub has no asset tree at a `latest` ref).
+ */
+export async function resolveLatestPlatformTag(namespace: string): Promise<string> {
   let response: Response;
   try {
     response = await fetch(
@@ -207,6 +214,16 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
   if (!latestTag) {
     throw new Error("No usable Docker image tag found");
   }
+  return latestTag;
+}
+
+export async function updateStackEnvToLatestImageTag(state: ControlPlaneState): Promise<{
+  namespace: string;
+  tag: string;
+}> {
+  const systemEnvPath = `${state.stashDir}/env/stack.env`;
+  const namespace = resolveImageNamespace(state);
+  const latestTag = await resolveLatestPlatformTag(namespace);
 
   const currentContent = existsSync(systemEnvPath) ? readFileSync(systemEnvPath, "utf-8") : "";
   const updatedContent = mergeEnvContent(currentContent, { OP_IMAGE_TAG: latestTag }, { uncomment: true });
@@ -216,7 +233,9 @@ export async function updateStackEnvToLatestImageTag(state: ControlPlaneState):
 }
 
 export async function applyUpgrade(
-  state: ControlPlaneState
+  state: ControlPlaneState,
+  /** Release tag whose stack assets to fetch (e.g. "v0.11.0-rc.6"). Caller-supplied. */
+  version: string
 ): Promise<{
   backupDir: string | null;
   updated: string[];
@@ -225,7 +244,7 @@ export async function applyUpgrade(
   const lock = acquireInstallLock(state.dataDir);
   if (!lock) throw new Error("Another install is already in progress");
   try {
-    const { backupDir, updated } = await refreshCoreAssets();
+    const { backupDir, updated } = await refreshCoreAssets(version);
     const restarted = await reconcileCore(state, {});
     return { backupDir, updated, restarted };
   } finally {
@@ -269,7 +288,9 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
     const tagResult = await updateStackEnvToLatestImageTag(state);
     imageTag = tagResult.tag;
     namespace = tagResult.namespace;
-    upgradeResult = await applyUpgrade(state);
+    // The resolved platform tag IS the version whose stack assets we fetch —
+    // keeps compose files and images in lockstep.
+    upgradeResult = await applyUpgrade(state, imageTag);
   } catch (e) {
     // Restore stack.env on failure
     if (originalStackEnv !== null) {
@@ -284,9 +305,14 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
     throw new Error(`Failed to pull images: ${pullResult.stderr}`);
   }
 
-  // 4. Recreate containers (includes profiles for voice addon)
+  // 4. Recreate containers (includes profiles for voice addon).
+  // forceRecreate is REQUIRED: channel adapters are installed at container
+  // startup from npm dist-tags (CHANNEL_PACKAGE, e.g. @openpalm/channel-discord@latest),
+  // so an unchanged compose config would leave those containers running on the
+  // old adapter. --force-recreate guarantees guardian + channel containers
+  // restart and re-resolve their dist-tag adapters (issue #450).
   const services = await buildManagedServices(state);
-  const upResult = await composeUp({ ...composeOpts, services, removeOrphans: true });
+  const upResult = await composeUp({ ...composeOpts, services, forceRecreate: true, removeOrphans: true });
   if (!upResult.ok) {
     throw new Error(`Images pulled but failed to recreate containers: ${upResult.stderr}`);
   }
@@ -305,13 +331,34 @@ export async function performUpgrade(state: ControlPlaneState): Promise<UpgradeR
  * Used by the admin "set version" action — skips the auto-detect step in performUpgrade.
  */
 export async function applyTagChange(state: ControlPlaneState, tag: string): Promise<UpgradeResult> {
+  const namespace = resolveImageNamespace(state);
+
+  // "latest" (or an empty selection) is not a real GitHub ref — there are no
+  // `.openpalm/...` stack assets at a `latest` tag, so refreshCoreAssets would
+  // fail with a raw download error. Resolve it to the concrete newest published
+  // platform tag BEFORE writing the env or fetching assets, so images and
+  // stack assets stay in lockstep on a real release tag.
+  const requested = tag.trim();
+  let resolvedTag = requested;
+  if (requested === "" || requested.toLowerCase() === "latest") {
+    try {
+      resolvedTag = await resolveLatestPlatformTag(namespace);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(
+        `Cannot resolve "latest" to a concrete release: ${msg}. ` +
+        "Check your network connection or select a specific version."
+      );
+    }
+  }
+
   const stackEnvPath = `${state.stashDir}/env/stack.env`;
   const currentContent = existsSync(stackEnvPath) ? readFileSync(stackEnvPath, "utf-8") : "";
-  writeFileSync(stackEnvPath, mergeEnvContent(currentContent, { OP_IMAGE_TAG: tag }, { uncomment: true }));
-  const upgradeResult = await applyUpgrade(state);
+  writeFileSync(stackEnvPath, mergeEnvContent(currentContent, { OP_IMAGE_TAG: resolvedTag }, { uncomment: true }));
+  const upgradeResult = await applyUpgrade(state, resolvedTag);
   return {
-    imageTag: tag,
-    namespace: "openpalm",
+    imageTag: resolvedTag,
+    namespace,
     backupDir: upgradeResult.backupDir,
     assetsUpdated: upgradeResult.updated,
     restarted: upgradeResult.restarted,
@@ -325,20 +372,27 @@ export function buildComposeFileList(state: ControlPlaneState): string[] {
 export async function buildManagedServices(state: ControlPlaneState): Promise<string[]> {
   const composeOpts = buildComposeOptions(state);
 
+  // Always force-recreate the core services (assistant + guardian) on upgrade,
+  // regardless of how the service set is discovered. getAddonServiceNames
+  // deliberately EXCLUDES guardian, so a fallback that relied on it alone would
+  // drop guardian from the recreated set when channel profiles are active —
+  // leaving guardian on stale state (issue #450).
+  const services = new Set<string>(CORE_SERVICES);
+
   // Prefer compose-derived service list when Docker is available
   if (composeOpts.files.length > 0 && !process.env.OP_SKIP_COMPOSE_PREFLIGHT) {
     const result = await composeConfigServices(composeOpts);
     if (result.ok && result.services.length > 0) {
-      return result.services;
+      for (const s of result.services) services.add(s);
+      return [...services];
     }
   }
 
   // Fallback: static inference from CORE_SERVICES + active addon overlays
-  const services: string[] = [...CORE_SERVICES];
   for (const addon of listEnabledAddonIds(state.homeDir)) {
-    services.push(...getAddonServiceNames(state.homeDir, addon));
+    for (const s of getAddonServiceNames(state.homeDir, addon)) services.add(s);
   }
-  return services;
+  return [...services];
 }