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

package/src/control-plane/docker.ts

@@ -39,10 +39,12 @@ function run(
 
 /**
  * Resolve the Docker Compose project name.
- * Honors COMPOSE_PROJECT_NAME (Docker standard) and OP_PROJECT_NAME (legacy).
+ * Honors OP_PROJECT_NAME first for OpenPalm stacks, then COMPOSE_PROJECT_NAME.
  */
-export function resolveComposeProjectName(): string {
+export function resolveComposeProjectName(envOverrides: Record<string, string> = {}): string {
   return (
+    envOverrides.OP_PROJECT_NAME?.trim() ||
+    envOverrides.COMPOSE_PROJECT_NAME?.trim() ||
     process.env.OP_PROJECT_NAME?.trim() ||
     process.env.COMPOSE_PROJECT_NAME?.trim() ||
     "openpalm"
@@ -87,12 +89,14 @@ export async function checkDockerCompose(): Promise<DockerResult> {
   });
 }
 
-/** Build common prefix: compose -f ... --project-name ... --env-file ... */
-function buildComposeArgs(options: { files: string[]; envFiles?: string[] }): string[] {
-  const args = ["compose", ...options.files.flatMap((f) => ["-f", f]), "--project-name", resolveComposeProjectName()];
+/** Build common prefix: compose -f ... --project-name ... --env-file ... --profile ... */
+function buildComposeArgs(options: { files: string[]; envFiles?: string[]; profiles?: string[] }): string[] {
+  const envOverrides = collectEnvOverrides(options.envFiles);
+  const args = ["compose", ...options.files.flatMap((f) => ["-f", f]), "--project-name", resolveComposeProjectName(envOverrides)];
   for (const ef of options.envFiles ?? []) {
     if (existsSync(ef)) args.push("--env-file", ef);
   }
+  for (const p of options.profiles ?? []) args.push("--profile", p);
   return args;
 }
 
@@ -108,7 +112,7 @@ function collectEnvOverrides(envFiles?: string[]): Record<string, string> {
  * Must be called before any lifecycle mutation (install/apply/update).
  */
 export async function composePreflight(
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<DockerResult> {
   const args = buildComposeArgs(options);
   args.push("config", "--quiet");
@@ -119,22 +123,23 @@ export async function composePreflight(
  * Run compose config preflight validation before any mutation.
  * Skipped when OP_SKIP_COMPOSE_PREFLIGHT is set (tests, CI).
  */
-async function runPreflight(options: { files: string[]; envFiles?: string[] }): Promise<void> {
+async function runPreflight(options: { files: string[]; envFiles?: string[]; profiles?: string[] }): Promise<void> {
   if (options.files.length === 0 || process.env.OP_SKIP_COMPOSE_PREFLIGHT) return;
   const result = await composePreflight(options);
   if (!result.ok) {
-    const project = resolveComposeProjectName();
+    const project = resolveComposeProjectName(collectEnvOverrides(options.envFiles));
     const fileArgs = options.files.map((f) => `-f ${f}`).join(" ");
     const envArgs = (options.envFiles ?? []).map((f) => `--env-file ${f}`).join(" ");
+    const profileArgs = (options.profiles ?? []).map((p) => `--profile ${p}`).join(" ");
     throw new Error(
       `Compose preflight failed: ${result.stderr}\n` +
-      `Resolved command: docker compose ${fileArgs} --project-name ${project} ${envArgs} config --quiet`
+      `Resolved command: docker compose ${fileArgs} --project-name ${project} ${envArgs} ${profileArgs} config --quiet`
     );
   }
 }
 
 export async function composeConfigServices(
-  options: { files: string[]; envFiles?: string[] }
+  options: { files: string[]; envFiles?: string[]; profiles?: string[] }
 ): Promise<{ ok: boolean; services: string[] }> {
   const args = buildComposeArgs(options);
   args.push("config", "--services");
@@ -163,7 +168,6 @@ export async function composeUp(
     return { ok: false, stdout: "", stderr: "Compose file not found", code: 1 };
   }
   const args = buildComposeArgs(options);
-  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("up", "-d");
   if (options.forceRecreate) args.push("--force-recreate");
   if (options.removeOrphans) args.push("--remove-orphans");
@@ -187,7 +191,6 @@ export async function composeDown(
     return { ok: false, stdout: "", stderr: "Compose file not found", code: 1 };
   }
   const args = buildComposeArgs(options);
-  for (const p of options.profiles ?? []) args.push("--profile", p);
   args.push("down");
   if (options.removeVolumes) args.push("-v");
   return run(args, undefined);
@@ -313,7 +316,6 @@ export async function composePullService(
 ): 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, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }
@@ -323,7 +325,6 @@ export async function composePull(
 ): 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, PULL_TIMEOUT_MS, collectEnvOverrides(options.envFiles));
 }

package/src/control-plane/env.test.ts

@@ -86,25 +86,25 @@ describe("quoteEnvValue quoting strategy (via mergeEnvContent)", () => {
 
 describe("mergeEnvContent updates existing keys with special char values", () => {
   it("updates an existing key to a value with =", () => {
-    const input = "export ADMIN_TOKEN=old_value\n";
-    const result = mergeEnvContent(input, { ADMIN_TOKEN: "new=value=here" });
+    const input = "export TEST_VALUE=old_value\n";
+    const result = mergeEnvContent(input, { TEST_VALUE: "new=value=here" });
     const parsed = parseEnvContent(result);
-    expect(parsed.ADMIN_TOKEN).toBe("new=value=here");
+    expect(parsed.TEST_VALUE).toBe("new=value=here");
   });
 
   it("updates an existing key to a value with $", () => {
-    const input = "export ADMIN_TOKEN=old_value\n";
-    const result = mergeEnvContent(input, { ADMIN_TOKEN: "tok$en" });
+    const input = "export TEST_VALUE=old_value\n";
+    const result = mergeEnvContent(input, { TEST_VALUE: "tok$en" });
     const parsed = parseEnvContent(result);
-    expect(parsed.ADMIN_TOKEN).toBe("tok$en");
+    expect(parsed.TEST_VALUE).toBe("tok$en");
   });
 
   it("preserves export prefix when updating with special chars", () => {
-    const input = "export ADMIN_TOKEN=old_value\n";
-    const result = mergeEnvContent(input, { ADMIN_TOKEN: "new#value" });
-    expect(result).toMatch(/^export ADMIN_TOKEN=/m);
+    const input = "export TEST_VALUE=old_value\n";
+    const result = mergeEnvContent(input, { TEST_VALUE: "new#value" });
+    expect(result).toMatch(/^export TEST_VALUE=/m);
     const parsed = parseEnvContent(result);
-    expect(parsed.ADMIN_TOKEN).toBe("new#value");
+    expect(parsed.TEST_VALUE).toBe("new#value");
   });
 });
 

package/src/control-plane/env.ts

@@ -26,7 +26,7 @@ export function expandEnvVars(input: string, vars: Record<string, string>): stri
   return input.replace(/\$\{([^}:]+)(?::-([^}]*))?\}/g, (_, name, def) => vars[name] ?? def ?? '');
 }
 
-function quoteEnvValue(value: string): string {
+export function quoteEnvValue(value: string): string {
   if (value.length === 0) return '';
   const needsQuoting = /[#"'\\\n\r$]/.test(value) || value !== value.trim();
   if (!needsQuoting) return value;
@@ -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/extends-support.test.ts

@@ -1,8 +1,8 @@
 /**
- * Verify that Compose `extends` is supported as an optional addon pattern.
+ * Verify that Compose `extends` is supported in the custom compose file.
  *
  * This is a narrow smoke test proving the canonical compose resolution
- * works when an addon uses Compose `extends` to inherit from a base service.
+ * works when custom.compose.yml uses Compose `extends` to inherit from a base service.
  */
 import { describe, test, expect, beforeAll, afterAll } from "bun:test";
 import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
@@ -15,7 +15,7 @@ describe("compose extends support", () => {
 
   beforeAll(() => {
     fixtureDir = join(tmpdir(), `openpalm-extends-test-${Date.now()}`);
-    mkdirSync(join(fixtureDir, "stack/addons/extended-addon"), { recursive: true });
+    mkdirSync(join(fixtureDir, "stack"), { recursive: true });
 
     // Write a minimal core compose
     writeFileSync(
@@ -30,9 +30,9 @@ describe("compose extends support", () => {
       ].join("\n")
     );
 
-    // Write an addon that uses `extends`
+    // Write custom compose content that uses `extends`
     writeFileSync(
-      join(fixtureDir, "stack/addons/extended-addon/compose.yml"),
+      join(fixtureDir, "stack/custom.compose.yml"),
       [
         "services:",
         "  extended-service:",
@@ -54,16 +54,16 @@ describe("compose extends support", () => {
 
   test("fixture files exist", () => {
     expect(existsSync(join(fixtureDir, "stack/core.compose.yml"))).toBe(true);
-    expect(existsSync(join(fixtureDir, "stack/addons/extended-addon/compose.yml"))).toBe(true);
+    expect(existsSync(join(fixtureDir, "stack/custom.compose.yml"))).toBe(true);
   });
 
-  test("extends addon composes correctly with discoverStackOverlays", async () => {
+  test("extends custom compose works with discoverStackOverlays", async () => {
     const { discoverStackOverlays } = await import("./config-persistence.js");
     const overlays = discoverStackOverlays(join(fixtureDir, "stack"));
 
     expect(overlays.length).toBe(2);
     expect(overlays[0]).toContain("core.compose.yml");
-    expect(overlays[1]).toContain("extended-addon/compose.yml");
+    expect(overlays[1]).toContain("custom.compose.yml");
   });
 
   test.skipIf(skipDockerAssertions)("extends addon passes docker compose config preflight (requires Docker)", async () => {

package/src/control-plane/fs-atomic.ts

@@ -0,0 +1,15 @@
+import { writeFileSync, renameSync } from "node:fs";
+
+/**
+ * Write a file atomically: write to `${path}.tmp` then rename over the target.
+ * The rename is atomic on the same filesystem, so readers never observe a
+ * partially written file. `mode` (e.g. 0o600) is applied on creation.
+ *
+ * Shared by all control-plane writers (setup, akm-sources, …) so config and
+ * secret files are written through one audited path — never hand-rolled.
+ */
+export function writeFileAtomic(path: string, content: string | Uint8Array, mode?: number): void {
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, content, mode !== undefined ? { mode } : {});
+  renameSync(tmp, path);
+}

package/src/control-plane/home.ts

@@ -2,13 +2,12 @@
  * Home directory layout for the OpenPalm control plane (v0.11.0+).
  *
  * Single ~/.openpalm/ root:
- *   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)
+ *   config/    — user-editable config + system config files (akm/)
+ *   config/stack/ — fixed compose files (no stack.env/secrets/stack.yml)
+ *   data/      — persistent service data, logs, backups, rollback
+ *   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, guardian.env, stack.yml)
  */
 import { mkdirSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -34,36 +33,31 @@ export function resolveConfigDir(): string {
 }
 
 export function resolveStashDir(): string {
-  return `${resolveOpenPalmHome()}/stash`;
+  return `${resolveOpenPalmHome()}/knowledge`;
 }
 
 export function resolveWorkspaceDir(): string {
   return `${resolveOpenPalmHome()}/workspace`;
 }
 
-export function resolveCacheDir(): string {
-  return `${resolveOpenPalmHome()}/cache`;
-}
-
-export function resolveStateDir(): string {
-  return `${resolveOpenPalmHome()}/state`;
+export function resolveDataDir(): string {
+  return `${resolveOpenPalmHome()}/data`;
 }
 
 export function resolveStackDir(): string {
   return `${resolveConfigDir()}/stack`;
 }
 
-// Derived from stateDir — used by registry.ts, rollback.ts, backup.ts, core-assets.ts
 export function resolveLogsDir(): string {
-  return `${resolveStateDir()}/logs`;
+  return `${resolveDataDir()}/logs`;
 }
 
 export function resolveBackupsDir(): string {
-  return `${resolveStateDir()}/backups`;
+  return `${resolveDataDir()}/backups`;
 }
 
 export function resolveRegistryDir(): string {
-  return `${resolveStateDir()}/registry`;
+  return `${resolveDataDir()}/registry`;
 }
 
 export function resolveRegistryAddonsDir(): string {
@@ -75,7 +69,7 @@ export function resolveRegistryAutomationsDir(): string {
 }
 
 export function resolveRollbackDir(): string {
-  return `${resolveCacheDir()}/rollback`;
+  return `${resolveDataDir()}/rollback`;
 }
 
 // ── Directory Setup ──────────────────────────────────────────────────
@@ -91,39 +85,33 @@ export function ensureHomeDirs(): void {
     `${home}/config`,
     `${home}/config/assistant`,
     `${home}/config/guardian`,
-    `${home}/config/akm`,           // AKM_CONFIG_DIR — akm setup config.json lives here
-
-    // cache/ — regenerable/semi-persistent data
-    `${home}/cache`,
-    `${home}/cache/akm`,            // akm registry index, downloaded artifacts
-    `${home}/cache/rollback`,       // rollback snapshots
-
-    // state/ — persistent service data
-    `${home}/state`,
-    `${home}/state/assistant`,      // assistant HOME bind mount
-    `${home}/state/admin`,          // admin home bind mount
-    `${home}/state/guardian`,       // guardian runtime data
-    `${home}/state/akm`,            // shared akm operational data (NOT config)
-    `${home}/state/akm/data`,
-    `${home}/state/akm/state`,
-    `${home}/state/logs`,
-    `${home}/state/logs/opencode`,
-    `${home}/state/backups`,
-    `${home}/state/registry`,
-    `${home}/state/registry/addons`,
-    `${home}/state/registry/automations`,
-
-    // stash/ — akm knowledge (skills, vaults, agents); stash/tasks/ for scheduled automations
-    `${home}/stash`,
-    `${home}/stash/vaults`,
-    `${home}/stash/tasks`,
+    `${home}/config/akm`,           // akm XDG config directory
+
+    // data/ — persistent service data
+    `${home}/data`,
+    `${home}/data/assistant`,      // assistant HOME bind mount
+    `${home}/data/assistant/.cache`,
+    `${home}/data/assistant/.local/bin`,
+    `${home}/data/assistant/.local/share/opencode`,
+    `${home}/data/assistant/.local/state/opencode`,
+    `${home}/data/guardian`,       // guardian runtime data
+    `${home}/data/akm/cache`,      // akm cache
+    `${home}/data/akm/data`,       // akm durable data
+    `${home}/data/akm/empty-host-stash`, // always-present /host-stash fallback when host AKM is absent
+    `${home}/data/logs`,           // service logs and audit files
+    `${home}/data/backups`,        // lifecycle backup snapshots
+    `${home}/data/rollback`,       // deploy rollback snapshots
+    // knowledge/ — akm knowledge (skills, env, secrets, agents); knowledge/tasks/ for scheduled automations
+    `${home}/knowledge`,
+    `${home}/knowledge/env`,
+    `${home}/knowledge/secrets`,
+    `${home}/knowledge/tasks`,
 
     // workspace/ — shared assistant work area
     `${home}/workspace`,
 
-    // config/stack/ — compose runtime (addon overlays + stack config files)
+    // config/stack/ — compose runtime + stack config files
     `${home}/config/stack`,
-    `${home}/config/stack/addons`,
   ]) {
     mkdirSync(dir, { recursive: true });
   }

package/src/control-plane/host-akm-sharing.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  enableHostAkmSharing,
+  disableHostAkmSharing,
+  getHostAkmSharingStatus,
+  ensureHostStashEnv,
+  isHostAkmAvailable,
+} from "./host-akm-sharing.js";
+import { HOST_SOURCE_NAME } from "./akm-sources.js";
+import type { ControlPlaneState } from "./types.js";
+
+let root = "";
+let fakeHome = "";
+let state: ControlPlaneState;
+let stackEnv = "";
+let opConfig = "";
+const savedHome = process.env.HOME;
+
+function readJson(p: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(p, "utf-8"));
+}
+/** Make the host look like it has (or hasn't) an initialized AKM. */
+function setHostAkm(available: boolean): void {
+  if (available) {
+    mkdirSync(join(fakeHome, "akm"), { recursive: true });
+    mkdirSync(join(fakeHome, ".config", "akm"), { recursive: true });
+    writeFileSync(join(fakeHome, ".config", "akm", "config.json"), JSON.stringify({ stashDir: join(fakeHome, "akm") }));
+  }
+}
+function opSources(): Array<Record<string, unknown>> {
+  if (!existsSync(opConfig)) return [];
+  return (readJson(opConfig).sources as Array<Record<string, unknown>>) ?? [];
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "host-akm-"));
+  fakeHome = join(root, "home");
+  mkdirSync(fakeHome, { recursive: true });
+  process.env.HOME = fakeHome;
+  const configDir = join(root, "config");
+  const stashDir = join(root, "knowledge");
+  mkdirSync(join(configDir, "akm"), { recursive: true });
+  mkdirSync(join(stashDir, "env"), { recursive: true });
+  state = { configDir, stashDir, dataDir: join(root, "data"), homeDir: root } as ControlPlaneState;
+  stackEnv = join(stashDir, "env", "stack.env");
+  opConfig = join(configDir, "akm", "config.json");
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+  if (savedHome === undefined) delete process.env.HOME;
+  else process.env.HOME = savedHome;
+  delete process.env.OP_HOST_AKM_STASH;
+});
+
+describe("isHostAkmAvailable", () => {
+  it("is false without a personal akm config, true with one", () => {
+    expect(isHostAkmAvailable()).toBe(false);
+    setHostAkm(true);
+    expect(isHostAkmAvailable()).toBe(true);
+  });
+});
+
+describe("ensureHostStashEnv", () => {
+  it("sets OP_HOST_AKM_STASH to ~/akm when available", () => {
+    setHostAkm(true);
+    ensureHostStashEnv(state);
+    expect(readFileSync(stackEnv, "utf-8")).toContain(`OP_HOST_AKM_STASH=${join(fakeHome, "akm")}`);
+  });
+
+  it("removes OP_HOST_AKM_STASH when not available (→ compose empty-dir fallback)", () => {
+    writeFileSync(stackEnv, "OP_HOST_AKM_STASH=/stale/path\nOP_IMAGE_TAG=x\n");
+    ensureHostStashEnv(state);
+    const env = readFileSync(stackEnv, "utf-8");
+    expect(env).not.toContain("OP_HOST_AKM_STASH");
+    expect(env).toContain("OP_IMAGE_TAG=x");
+  });
+});
+
+describe("enableHostAkmSharing", () => {
+  it("sets env + adds the writable host-akm source when available", () => {
+    setHostAkm(true);
+    enableHostAkmSharing(state);
+    expect(readFileSync(stackEnv, "utf-8")).toContain(`OP_HOST_AKM_STASH=${join(fakeHome, "akm")}`);
+    const src = opSources().find((s) => s.name === HOST_SOURCE_NAME);
+    expect(src).toBeDefined();
+    expect(src!.writable).toBe(true);
+    expect(src!.path).toBe("/host-stash");
+  });
+
+  it("throws when host AKM is not available (never writes a source)", () => {
+    expect(() => enableHostAkmSharing(state)).toThrow();
+    expect(opSources()).toHaveLength(0);
+  });
+
+  it("imports host profiles when importProfiles is set", () => {
+    setHostAkm(true);
+    writeFileSync(join(fakeHome, ".config", "akm", "config.json"), JSON.stringify({
+      stashDir: join(fakeHome, "akm"),
+      profiles: { llm: { default: { endpoint: "http://h/v1/chat/completions", model: "qwen" } } },
+      defaults: { llm: "default" },
+    }));
+    const { profilesImported } = enableHostAkmSharing(state, { importProfiles: true });
+    expect(profilesImported).toContain("profiles.llm");
+    expect(((readJson(opConfig).profiles as Record<string, Record<string, Record<string, unknown>>>).llm.default).model).toBe("qwen");
+  });
+
+  it("is idempotent", () => {
+    setHostAkm(true);
+    enableHostAkmSharing(state);
+    enableHostAkmSharing(state);
+    expect(opSources().filter((s) => s.name === HOST_SOURCE_NAME)).toHaveLength(1);
+  });
+});
+
+describe("disableHostAkmSharing", () => {
+  it("removes the host-akm source; never deletes stash content or the personal config", () => {
+    setHostAkm(true);
+    enableHostAkmSharing(state);
+    disableHostAkmSharing(state);
+    expect(opSources().find((s) => s.name === HOST_SOURCE_NAME)).toBeUndefined();
+    // Personal config untouched (D1 — assistant-only).
+    expect(existsSync(join(fakeHome, ".config", "akm", "config.json"))).toBe(true);
+  });
+
+  it("is safe when nothing is enabled", () => {
+    writeFileSync(opConfig, "{}");
+    expect(() => disableHostAkmSharing(state)).not.toThrow();
+  });
+});
+
+describe("getHostAkmSharingStatus", () => {
+  it("reports available+enabled transitions", () => {
+    expect(getHostAkmSharingStatus(state)).toEqual({ available: false, enabled: false, hostStashPath: null });
+    setHostAkm(true);
+    expect(getHostAkmSharingStatus(state)).toEqual({ available: true, enabled: false, hostStashPath: join(fakeHome, "akm") });
+    enableHostAkmSharing(state);
+    expect(getHostAkmSharingStatus(state).enabled).toBe(true);
+    disableHostAkmSharing(state);
+    expect(getHostAkmSharingStatus(state).enabled).toBe(false);
+  });
+});

package/src/control-plane/host-akm-sharing.ts

@@ -0,0 +1,129 @@
+/**
+ * Host AKM sharing (control-plane logic — lives in lib).
+ *
+ * Simplified model (no compose overlay, no file-presence gating):
+ *
+ *  - The assistant ALWAYS mounts `/host-stash` (core.compose.yml). When the host
+ *    has AKM, OP_HOST_AKM_STASH points at the user's personal stash (~/akm);
+ *    otherwise it is unset and compose falls back to an always-present empty dir.
+ *  - "Sharing" is purely a writable SECONDARY source entry named `host-akm` →
+ *    /host-stash in the assistant's config/akm/config.json. Adding it = enabled;
+ *    removing it = disabled. akm resolves writes to the primary unless an explicit
+ *    --target is given, and silently skips a source whose dir is empty/missing —
+ *    so a mounted-but-unconfigured /host-stash is harmless.
+ *  - Host availability is detected from the presence of the user's personal akm
+ *    CONFIG (~/.config/akm/config.json) — the real signal that akm is initialized.
+ *
+ * Decision D1 (2026-06-03): host sharing is assistant-reads-host ONLY by default.
+ * We never write into the user's personal ~/.config/akm here. (Letting the host
+ * akm see OpenPalm's knowledge is a future, explicit opt-in.)
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { writeFileAtomic } from "./fs-atomic.js";
+import { mergeEnvContent, removeEnvKey } from "./env.js";
+import { addHostStashToOpenpalmConfig, removeHostAkmSource, importHostProfiles } from "./akm-sources.js";
+import type { ControlPlaneState } from "./types.js";
+import { createLogger } from "../logger.js";
+
+const logger = createLogger("host-akm-sharing");
+
+const ENV_KEY = "OP_HOST_AKM_STASH";
+
+function userHome(): string {
+  return process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+}
+/** The user's personal akm stash dir (mounted into the assistant at /host-stash). */
+export function hostAkmStashPath(): string {
+  return `${userHome()}/akm`;
+}
+/** The user's personal akm config file — its existence is our availability signal. */
+export function hostAkmConfigPath(): string {
+  return `${userHome()}/.config/akm/config.json`;
+}
+/** True when AKM is initialized on the host (personal config exists). */
+export function isHostAkmAvailable(): boolean {
+  return existsSync(hostAkmConfigPath());
+}
+
+function stackEnvPath(state: ControlPlaneState): string {
+  return `${state.stashDir}/env/stack.env`;
+}
+
+/**
+ * Point OP_HOST_AKM_STASH at the host stash when AKM is available, else unset it
+ * (compose then uses the empty-dir fallback). Pure infrastructure — does NOT
+ * change the source list. Idempotent; safe to call on setup and on deploy.
+ */
+export function ensureHostStashEnv(state: ControlPlaneState): void {
+  const path = stackEnvPath(state);
+  const existing = existsSync(path) ? readFileSync(path, "utf-8") : "";
+  const updated = isHostAkmAvailable()
+    ? mergeEnvContent(existing, { [ENV_KEY]: hostAkmStashPath() })
+    : removeEnvKey(existing, ENV_KEY);
+  if (updated !== existing) writeFileAtomic(path, updated, 0o600);
+}
+
+export type HostAkmSharingStatus = {
+  /** AKM is initialized on the host (personal config present). */
+  available: boolean;
+  /** The host-akm secondary source is present in the assistant config. */
+  enabled: boolean;
+  /** Resolved host stash path when available, else null. */
+  hostStashPath: string | null;
+};
+
+/**
+ * Enable host AKM sharing: ensure OP_HOST_AKM_STASH points at ~/akm and add the
+ * writable `host-akm` secondary source to the assistant config. Optionally import
+ * host LLM/agent profiles (read-only). Throws if host AKM is not available.
+ */
+export function enableHostAkmSharing(
+  state: ControlPlaneState,
+  opts: { writable?: boolean; importProfiles?: boolean } = {},
+): { profilesImported: string[] } {
+  if (!isHostAkmAvailable()) {
+    throw new Error(
+      `Host AKM is not available (no ${hostAkmConfigPath()}). Run \`akm init\` on the host first.`,
+    );
+  }
+  ensureHostStashEnv(state);
+  addHostStashToOpenpalmConfig(state, opts.writable ?? true);
+  let profilesImported: string[] = [];
+  if (opts.importProfiles) {
+    profilesImported = importHostProfiles(state, hostAkmConfigPath()).imported;
+  }
+  logger.info("host akm sharing enabled", { hostStashPath: hostAkmStashPath(), profilesImported });
+  return { profilesImported };
+}
+
+/**
+ * Disable host AKM sharing: remove the `host-akm` secondary source from the
+ * assistant config. Leaves the (harmless) mount and env in place; never deletes
+ * any stash content.
+ */
+export function disableHostAkmSharing(state: ControlPlaneState): void {
+  removeHostAkmSource(state);
+  logger.info("host akm sharing disabled");
+}
+
+/** Report availability + whether the host-akm source is currently configured. */
+export function getHostAkmSharingStatus(state: ControlPlaneState): HostAkmSharingStatus {
+  const available = isHostAkmAvailable();
+  return {
+    available,
+    enabled: openpalmHasHostSource(state),
+    hostStashPath: available ? hostAkmStashPath() : null,
+  };
+}
+
+function openpalmHasHostSource(state: ControlPlaneState): boolean {
+  const path = `${state.configDir}/akm/config.json`;
+  if (!existsSync(path)) return false;
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf-8")) as { sources?: Array<{ name?: string }> };
+    return Array.isArray(cfg.sources) && cfg.sources.some((s) => s?.name === "host-akm");
+  } catch {
+    return false;
+  }
+}