@uniqbit/mate-core 0.18.3 → 0.18.4

package/opencode-plugin/src/add-dir.ts

@@ -1,15 +1,8 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 
 import type { Context } from "@opencode/plugin/promise/plugin";
 
-type CompanionSkill = {
-  id: string;
-  name: string;
-  description?: string;
-  path: string;
-  content: string;
-};
+import { loadSkillInfos } from "../../src/runtime/opencode-audience-layer";
 
 function companionSkillPaths(companionPath: string): string[] {
   return [
@@ -23,87 +16,28 @@ function isWithin(root: string, candidate: string): boolean {
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
 }
 
-function parseFrontmatter(content: string): { name?: string; description?: string } {
-  const match = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
-  if (!match) return {};
-
-  const scalar = (key: string) => {
-    const value = match[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim();
-    return value?.replace(
-      /^(?:"([\s\S]*)"|'([\s\S]*)')$/,
-      (_all, doubleQuoted, singleQuoted) => doubleQuoted ?? singleQuoted,
-    );
-  };
-
-  return { name: scalar("name"), description: scalar("description") };
-}
-
-async function findSkillFiles(directory: string): Promise<string[]> {
-  try {
-    const entries = await fs.readdir(directory, { withFileTypes: true });
-    const files: string[] = [];
-    const subdirectories: Promise<string[]>[] = [];
-    for (const entry of entries) {
-      const entryPath = path.join(directory, entry.name);
-      if (entry.isFile() && entry.name === "SKILL.md") files.push(entryPath);
-      else if (entry.isDirectory()) subdirectories.push(findSkillFiles(entryPath));
-    }
-    const nested = await Promise.all(subdirectories);
-    return [...files, ...nested.flat()];
-  } catch {
-    return [];
-  }
-}
-
-function skillID(name: string): string {
-  return (
-    name
-      .toLowerCase()
-      .replace(/[^a-z0-9_-]+/g, "-")
-      .replace(/^-+|-+$/g, "") || "mate-skill"
-  );
-}
-
-async function loadCompanionSkills(companionPath: string): Promise<CompanionSkill[]> {
-  const files = (await Promise.all(companionSkillPaths(companionPath).map(findSkillFiles))).flat();
-  const skills = await Promise.all(
-    files.map(async (filePath): Promise<CompanionSkill | null> => {
-      try {
-        const content = await fs.readFile(filePath, "utf8");
-        const metadata = parseFrontmatter(content);
-        const name = metadata.name || path.basename(path.dirname(filePath));
-        return {
-          id: skillID(name),
-          name,
-          ...(metadata.description ? { description: metadata.description } : {}),
-          path: filePath,
-          content,
-        };
-      } catch {
-        /** An unreadable companion skill must not prevent the session from loading. */
-        return null;
-      }
-    }),
-  );
-  return skills.filter((skill) => skill !== null);
-}
-
 /**
  * Grants the session access to the companion and registers its skills. The
  * permission hook only widens access for companion resources; every other
  * evaluation keeps OpenCode's own verdict.
  */
-export async function registerCompanionAccess(api: Context, companionPath: string): Promise<void> {
+export async function registerCompanionAccess(
+  api: Context,
+  companionPath: string,
+  extraRoots: readonly string[] = [],
+): Promise<void> {
   const permissionRoot = path.resolve(companionPath);
+  /** An audience layer's files are as readable as the companion's, for this launch only. */
+  const allowedRoots = [permissionRoot, ...extraRoots.map((root) => path.resolve(root))];
 
   await api.permission.hook("evaluate", (event) => {
-    if (event.resources.some((resource) => isWithin(permissionRoot, resource))) {
+    if (event.resources.some((resource) => allowedRoots.some((root) => isWithin(root, resource)))) {
       event.effect = "allow";
       delete event.message;
     }
   });
 
-  const skills = await loadCompanionSkills(permissionRoot);
+  const skills = await loadSkillInfos(companionSkillPaths(permissionRoot));
   if (skills.length === 0) return;
 
   await api.skill.transform((editor) => {

package/opencode-plugin/src/audience-layer.ts

@@ -0,0 +1,91 @@
+import type { Context } from "@opencode/plugin/promise/plugin";
+
+import { repositoryWrappedForOpenCode } from "../../src/opencode/companion-hooks";
+import { currentAudienceLayer } from "../../src/runtime/audience-layer";
+import { MATE_ENV } from "../../src/runtime/env";
+import { parseGuidanceContent } from "../../src/runtime/guidance";
+import {
+  readOpenCodeAudienceLayer,
+  type OpenCodeLayerContents,
+} from "../../src/runtime/opencode-audience-layer";
+import { readWrapStateSync } from "../../src/runtime/wrap-state";
+import type { LaunchEnvironment } from "./launch-environment";
+
+export interface TrustedAudienceLayer {
+  root: string;
+  contents: OpenCodeLayerContents;
+}
+
+/**
+ * The audience layer named by a payload the plugin trusts. `env` is the
+ * launch environment `pluginLaunchEnvironment` decided on, so a masked
+ * payload, a bare session and the shared service all read as `{}` here and
+ * never apply a layer.
+ */
+export async function readTrustedAudienceLayer(
+  env: LaunchEnvironment,
+): Promise<TrustedAudienceLayer | null> {
+  const payload = env[MATE_ENV.guidanceJson];
+  if (!payload?.trim()) return null;
+  const root = parseGuidanceContent(payload).guidance.audienceLayer;
+  if (!root) return null;
+  return { root, contents: await readOpenCodeAudienceLayer(root) };
+}
+
+/**
+ * The layer of the audience the session's checkout is wrapped for. The wrap is
+ * resolved from the session's own directory, so the shared service serves each
+ * checkout its own audience; the environment never selects one.
+ */
+export async function readWrappedAudienceLayer(
+  directory: string,
+  companionPath: string,
+): Promise<TrustedAudienceLayer | null> {
+  const repoRoot = repositoryWrappedForOpenCode(directory);
+  if (!repoRoot) return null;
+  const audience = readWrapStateSync(repoRoot).audience;
+  if (!audience) return null;
+  const root = currentAudienceLayer(companionPath, audience);
+  return root ? { root, contents: await readOpenCodeAudienceLayer(root) } : null;
+}
+
+/**
+ * Applies a layer's MCP servers, skills and agents through the plugin API. A
+ * new agent id is created by updating it; its prompt goes in `system`.
+ */
+export async function registerAudienceLayer(
+  api: Context,
+  layer: OpenCodeLayerContents,
+): Promise<void> {
+  if (layer.mcpServers.length > 0) {
+    await api.mcp.transform((editor) => {
+      for (const server of layer.mcpServers) editor.set(server.name, server.config as never);
+    });
+  }
+
+  if (layer.skills.length > 0) {
+    await api.skill.transform((editor) => {
+      for (const skill of layer.skills) {
+        if (editor.get(skill.id)) {
+          editor.update(skill.id, (current) => Object.assign(current, skill));
+        } else {
+          editor.add(skill as never);
+        }
+      }
+    });
+  }
+
+  if (layer.agents.length > 0) {
+    await api.agent.transform((editor) => {
+      for (const agent of layer.agents) {
+        editor.update(agent.id, (current) => {
+          const target = current as Record<string, unknown>;
+          target.name ??= agent.id;
+          if (agent.description) target.description = agent.description;
+          target.mode = agent.mode;
+          target.system = agent.system;
+        });
+      }
+    });
+  }
+}

package/opencode-plugin/src/companion.ts

@@ -6,6 +6,7 @@ import { MATE_ENV } from "../../src/runtime/env";
 import { COMPANION_POLICY_MARKER, type MateGuidanceFile } from "../../src/runtime/guidance";
 
 import type { CompanionContext } from "../../src/opencode/companion-policy";
+import type { LaunchEnvironment } from "./launch-environment";
 import { resolveOpenCodeGuidance } from "../../src/opencode/projected-guidance";
 import {
   runtimeDirectoryPath,
@@ -23,8 +24,8 @@ function prependPathEntry(pathValue: string | undefined, entry: string): string
  * keeps current. `null` when neither exists: guidance naming an unresolved
  * placeholder would send the model to a path that is not there.
  */
-function resolveWrapperBinPath(): string | null {
-  if (process.env.MATE_WRAPPER_BIN_PATH) return process.env.MATE_WRAPPER_BIN_PATH;
+function resolveWrapperBinPath(env: LaunchEnvironment): string | null {
+  if (env.MATE_WRAPPER_BIN_PATH) return env.MATE_WRAPPER_BIN_PATH;
   const runtime = runtimeWrapperBinPath();
   return fs.existsSync(runtime) ? runtime : null;
 }
@@ -54,8 +55,8 @@ function buildStartupError(details: string[]): Error {
  * an Unmanaged Session in a wrapped repository builds the same payload from the
  * companion the projection names, with the Capability names read live.
  */
-function loadGuidance(directory: string): MateGuidanceFile | null {
-  const { guidance, errors } = resolveOpenCodeGuidance(process.env, directory);
+function loadGuidance(env: LaunchEnvironment, directory: string): MateGuidanceFile | null {
+  const { guidance, errors } = resolveOpenCodeGuidance(env, directory);
   if (errors.length > 0) throw buildStartupError(errors);
   return guidance;
 }
@@ -76,6 +77,7 @@ function buildSystemPrompt(
   context: CompanionContext,
   guidance: MateGuidanceFile,
   wrapperBinPath: string,
+  layerGuidance: string,
 ): string[] {
   const lines = [materializeCompanionGuidance(guidance.companionGuidance, context, wrapperBinPath)];
 
@@ -87,6 +89,11 @@ function buildSystemPrompt(
     lines.push("", `<agents.md>${context.agentsMd.trim()}</agents.md>`);
   }
 
+  /** The audience's guidance follows the companion's, never replaces it. */
+  if (layerGuidance.trim()) {
+    lines.push("", layerGuidance.trim());
+  }
+
   return lines;
 }
 
@@ -101,9 +108,10 @@ function applyCompanionShellEnv(
   context: CompanionContext,
   env: Record<string, string | undefined>,
   wrapperBinPath: string,
+  launchEnv: LaunchEnvironment,
 ): void {
   env.MATE_NAME = context.frameworkName;
-  env.MATE_VERSION = process.env.MATE_VERSION ?? "unknown";
+  env.MATE_VERSION = launchEnv.MATE_VERSION ?? "unknown";
   env.MATE_ARTIFACT_PATH = context.companionPath;
   env.MATE_WRAPPER_BIN_PATH = wrapperBinPath;
   if (context.repositoryPath) {
@@ -171,18 +179,27 @@ function mergeCompanionSystem(system: unknown[], companion: string): string[] {
   return parts.length > 0 ? [parts.join("\n\n")] : [];
 }
 
-/** Registers guidance, compaction context, shell env, and `companion_paths`. */
-export async function registerCompanion(api: Context, context: CompanionContext): Promise<void> {
-  const guidance = loadGuidance(api.location.directory);
+/**
+ * Registers guidance, compaction context, shell env, and `companion_paths`.
+ * `env` is the launch environment the caller decided to trust; `{}` resolves
+ * everything from the Projection Root.
+ */
+export async function registerCompanion(
+  api: Context,
+  context: CompanionContext,
+  env: LaunchEnvironment = process.env,
+  layerGuidance = "",
+): Promise<void> {
+  const guidance = loadGuidance(env, api.location.directory);
   if (!guidance) return;
   /** Reported, not thrown: the guardrails registered before this must stay live. */
-  const wrapperBinPath = resolveWrapperBinPath();
+  const wrapperBinPath = resolveWrapperBinPath(env);
   if (!wrapperBinPath) {
     console.error(`mate: ${missingRuntimeDirectoryMessage()}`);
     return;
   }
 
-  const companion = buildSystemPrompt(context, guidance, wrapperBinPath).join("\n");
+  const companion = buildSystemPrompt(context, guidance, wrapperBinPath, layerGuidance).join("\n");
 
   await api.session.hook("context", (event) => {
     const merged = mergeCompanionSystem(event.system, companion);
@@ -199,7 +216,7 @@ export async function registerCompanion(api: Context, context: CompanionContext)
   });
 
   await api.shell.hook("create.before", (event) => {
-    applyCompanionShellEnv(context, event.env, wrapperBinPath);
+    applyCompanionShellEnv(context, event.env, wrapperBinPath, env);
   });
 
   await api.tool.transform((editor) => {

package/opencode-plugin/src/launch-environment.ts

@@ -0,0 +1,29 @@
+import { MATE_ENV } from "../../src/runtime/env";
+
+export type LaunchEnvironment = Record<string, string | undefined>;
+
+/**
+ * True inside OpenCode's shared background service (`opencode serve --service`),
+ * which hosts plugins in-process for every bare `opencode` session. Its
+ * environment belongs to whichever process started it, not to any session.
+ */
+export function runsInSharedService(argv: readonly string[]): boolean {
+  return argv.includes("serve") && argv.includes("--service");
+}
+
+/**
+ * The environment the plugin may treat as a Mate launch environment: `env`
+ * itself for a managed launch, `{}` otherwise so every reader falls back to
+ * the Projection Root.
+ *
+ * Inherited `MATE_*` variables prove nothing — every shell under a Mate session
+ * carries them. The guidance payload does: only `mate opencode` sets it, and
+ * the plugin masks it in every shell it configures.
+ */
+export function pluginLaunchEnvironment(
+  env: LaunchEnvironment,
+  argv: readonly string[],
+): LaunchEnvironment {
+  const managed = Boolean(env[MATE_ENV.guidanceJson]?.trim()) && !runsInSharedService(argv);
+  return managed ? env : {};
+}

package/opencode-plugin/src/server.ts

@@ -11,15 +11,21 @@ import { spawnPrepareRunner } from "../../src/runtime/session-prepare-runner";
 import { readWrapStateSync } from "../../src/runtime/wrap-state";
 
 import { registerCompanionAccess } from "./add-dir";
+import {
+  readTrustedAudienceLayer,
+  readWrappedAudienceLayer,
+  registerAudienceLayer,
+} from "./audience-layer";
 import { missingRuntimeDirectoryMessage, registerCompanion, resolveMateBin } from "./companion";
+import { pluginLaunchEnvironment, type LaunchEnvironment } from "./launch-environment";
 
 /**
  * Only a location in a repository wrapped for OpenCode prepares, and only
  * without a launch environment: `mate opencode` has already prepared the
  * session it starts.
  */
-async function registerPrepare(api: Context, companionPath: string) {
-  if (hasLaunchEnvironment(process.env)) return undefined;
+async function registerPrepare(api: Context, companionPath: string, env: LaunchEnvironment) {
+  if (hasLaunchEnvironment(env)) return undefined;
   const repoRoot = repositoryWrappedForOpenCode(api.location.directory);
   if (!repoRoot) return undefined;
   const mateBin = resolveMateBin();
@@ -39,19 +45,30 @@ async function registerPrepare(api: Context, companionPath: string) {
 /**
  * Mate OpenCode server plugin (OpenCode 2.x). Loaded through the package's
  * `./server` export; stays inert when no companion resolves from the launch
- * environment or a Projection Root above the session directory.
+ * environment or a Projection Root above the session directory. The launch
+ * environment is decided once here: outside a managed launch every reader
+ * gets `{}`, so an environment inherited by the shared service never counts.
  */
 export const MateOpenCodePlugin = Plugin.define({
   id: "mate-opencode-plugin",
   async setup(api) {
-    const context = readContext(process.env, api.location.directory);
+    const env = pluginLaunchEnvironment(process.env, process.argv);
+    const context = readContext(env, api.location.directory);
     if (!context.companionPath) return;
 
-    await registerCompanionAccess(api, context.companionPath);
-    await registerCompanionHooks(api, context);
-    await registerCompanion(api, context);
+    /**
+     * A layer comes from a payload this launch trusts, else from the wrap of
+     * the session's checkout; an inherited environment never names one.
+     */
+    const layer =
+      (await readTrustedAudienceLayer(env)) ??
+      (await readWrappedAudienceLayer(api.location.directory, context.companionPath));
+    await registerCompanionAccess(api, context.companionPath, layer ? [layer.root] : []);
+    await registerCompanionHooks(api, context, env);
+    await registerCompanion(api, context, env, layer?.contents.guidance);
+    if (layer) await registerAudienceLayer(api, layer.contents);
     /** Last: the guardrails above are live while the local phase holds `setup`. */
-    const prepareCleanup = await registerPrepare(api, context.companionPath);
+    const prepareCleanup = await registerPrepare(api, context.companionPath, env);
     return async () => {
       await prepareCleanup?.();
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.3",
+  "version": "0.18.4",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {

package/src/cli/commands/cap/index-cmd.ts

@@ -1,6 +1,3 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
 import {
   hasGraphifyCapability,
   hasTokensaveCapability,
@@ -10,7 +7,7 @@ import type { CapabilityConfig } from "../../../lib/orchestrator/types";
 import {
   ensureTokensaveBranchingPosture,
   ensureTokensaveStoreExcluded,
-  TOKENSAVE_STORE_DIR,
+  isTokensaveIndexed,
 } from "../../../tools/setup/capabilities/tokensave";
 import { ensureUnambiguousCompanion } from "../shared/companion-selection";
 import { runGraphifyCapCommand } from "./graphify";
@@ -43,13 +40,7 @@ async function defaultIsTokensaveInitialized(): Promise<boolean> {
   const repo =
     repository ?? (await workingRepoStore.load()).repos.find((entry) => entry.id === repositoryId);
   if (!repo) return false;
-
-  try {
-    const stat = await fs.stat(path.join(repo.path, TOKENSAVE_STORE_DIR));
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
+  return isTokensaveIndexed(repo.path);
 }
 
 // The reused cap commands (runGraphifyCapCommand / runTokensaveCapCommand) signal

package/src/cli/commands/doctor.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../framework";
 import { gitEnvironment } from "../../runtime/companion-git";
+import { readWrapStateSync } from "../../runtime/wrap-state";
 import { getActiveDistribution } from "../../distribution";
 import { checkEngineRequirement } from "../../lib/orchestrator/engine-guard";
 import type { GlobalConfigStore } from "../../lib/orchestrator/global-config-store";
@@ -19,7 +20,12 @@ import {
   type PluginInspection,
   type PluginVerificationFailure,
 } from "../../tools/setup/dynamic-plugins/verify";
+import {
+  inspectAudienceIsolation,
+  type AudienceIsolationReport,
+} from "../../tools/setup/isolation-diagnostics";
 import { getRequiredPluginDrift } from "../../tools/setup/policy";
+import type { PluginRegistry } from "../../tools/setup/registry";
 import { resolveCommandOnPath } from "../../tools/setup/utils";
 import { writeJsonStdout } from "../write-json-stdout";
 import { printSection, renderKeyValueTable, renderTable } from "./status";
@@ -33,6 +39,8 @@ interface DoctorDeps {
   inspectPlugins?: (companionPath: string) => Promise<PluginInspection>;
   /** Environment `MATE_AUDIENCE` is read from; defaults to the process environment. */
   env?: Record<string, string | undefined>;
+  /** The hydrated registry; the active distribution's when absent. */
+  registry?: PluginRegistry;
 }
 
 export type DoctorKind = "core" | "working" | "companion" | "hub";
@@ -66,10 +74,15 @@ export interface DoctorReport {
   toolInstallations?: DoctorToolInstallation[];
   requiredPluginDrift?: Array<{ pluginId: string; kind: string; reason: string }>;
   pluginFailures?: PluginVerificationFailure[];
-  /** Present for a companion that declares audiences or has one selected. */
-  audiences?: { declared: string[]; active: string | null };
+  /**
+   * Present for a companion that declares audiences or has one selected.
+   * `wrapped` is the audience the working repository is wrapped for, when any.
+   */
+  audiences?: { declared: string[]; active: string | null; wrapped?: string };
   /** Set when `MATE_AUDIENCE` names an audience the companion does not declare. */
   audienceError?: string;
+  /** Present when an audience's contributions reached a persisted surface, or a launch layer cannot deliver part of one. */
+  audienceIsolation?: AudienceIsolationReport;
   /** IDs of the capabilities the verified plugins provide. */
   pluginCapabilities?: string[];
   engineRequirement?: { range: string; ok: boolean; detail: string };
@@ -230,12 +243,18 @@ function collectAudiences(
   report: DoctorReport,
   config: FrameworkConfig,
   env: Record<string, string | undefined>,
+  repositoryPath: string | null,
 ): void {
   const declared = Object.keys(config.audiences ?? {});
   const requested = readAudienceSelection(env);
   if (declared.length === 0 && requested === null) return;
   const resolution = resolveAudience(config, requested);
-  report.audiences = { declared, active: resolution.ok ? resolution.active : null };
+  const wrapped = repositoryPath ? readWrapStateSync(repositoryPath).audience : null;
+  report.audiences = {
+    declared,
+    active: resolution.ok ? resolution.active : null,
+    ...(wrapped ? { wrapped } : {}),
+  };
   if (!resolution.ok) report.audienceError = describeUnknownAudience(resolution);
 }
 
@@ -274,7 +293,16 @@ export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<Doctor
 
   const env = deps.env ?? process.env;
   if (root.rootPath && root.config && kind !== "hub") {
-    collectAudiences(report, root.config, env);
+    collectAudiences(report, root.config, env, root.linkedRepository?.path ?? null);
+    const isolation = await inspectAudienceIsolation(
+      root.rootPath,
+      root.config,
+      deps.registry ?? getActiveDistribution().registry,
+      report.audiences?.active ?? null,
+    );
+    if (isolation.leaked.length + isolation.unswept.length + isolation.undelivered.length > 0) {
+      report.audienceIsolation = isolation;
+    }
   }
 
   if (root.rootPath && root.config) {
@@ -325,6 +353,49 @@ function renderHubMembers(members: DoctorHubMember[]): string {
   );
 }
 
+function renderAudienceIsolation(isolation: AudienceIsolationReport): string {
+  const parts: string[] = [];
+  if (isolation.leaked.length > 0) {
+    parts.push(
+      "Contributions on persisted surfaces that no base plugin owns; the next sync removes them:",
+      renderTable(
+        ["Surface", "Kind", "Entry", "Owner"],
+        isolation.leaked.map((entry) => [
+          entry.surface,
+          entry.kind,
+          entry.identity ?? "",
+          entry.owner,
+        ]),
+      ),
+    );
+  }
+  if (isolation.unswept.length > 0) {
+    parts.push(
+      `Audience plugins not swept (could not be loaded); run \`MATE_AUDIENCE=<audience> ${FRAMEWORK_NAME} install --yes\` with their credentials:`,
+      renderList(isolation.unswept, ""),
+    );
+  }
+  if (isolation.undelivered.length > 0) {
+    parts.push(
+      "Active audience plugins contribute declaratively only; these parts are not delivered:",
+      renderList(
+        isolation.undelivered.map(
+          (entry) =>
+            `${entry.pluginId}: ${entry.parts
+              .map((part) =>
+                part === "pluginReferences"
+                  ? "OpenCode plugin references are not delivered"
+                  : `${part} is not run`,
+              )
+              .join("; ")}`,
+        ),
+        "",
+      ),
+    );
+  }
+  return parts.join("\n\n");
+}
+
 function renderHumanReport(report: DoctorReport): void {
   console.log("Mate Doctor");
   console.log("");
@@ -371,9 +442,20 @@ function renderHumanReport(report: DoctorReport): void {
       renderKeyValueTable([
         ["Declared", report.audiences.declared.join(", ") || "none"],
         ["Active", report.audiences.active ?? "none"],
+        ...(report.audiences.wrapped
+          ? [
+              ["Wrapped", `${report.audiences.wrapped} (bare sessions of this checkout)`] as [
+                string,
+                string,
+              ],
+            ]
+          : []),
       ]),
     );
   }
+  if (report.audienceIsolation) {
+    printSection("Audience Isolation", renderAudienceIsolation(report.audienceIsolation));
+  }
   if (report.hub) printSection("Hub Members", renderHubMembers(report.hub.members));
   // Companions with no drift produce no section at all: required plugins are
   // silent when healthy.

package/src/cli/commands/install.ts

@@ -1,5 +1,8 @@
+import path from "node:path";
+
 import { confirm } from "../confirm";
 import { FRAMEWORK_NAME } from "../../framework";
+import { ConfigStore } from "../../lib/orchestrator/config-store";
 import {
   buildInstallPlan,
   inspectInstallPlan,
@@ -176,6 +179,11 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
 
   try {
+    if (!frozen && context.kind === "companion" && context.companionPath) {
+      await new ConfigStore(
+        path.join(context.companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+      ).save(context.config);
+    }
     await reconcileInstalledCompanion(plan);
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {

package/src/cli/commands/studio/terminal-launch.ts

@@ -3,9 +3,11 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { ConfigStore, mergeWithDefaults } from "../../../lib/orchestrator/config-store";
+import { currentAudienceLayer } from "../../../runtime/audience-layer";
 import {
   effectiveStudioAgent,
   readAudienceSelection,
+  resolveAudience,
 } from "../../../tools/setup/dynamic-plugins/audiences";
 import type { StudioInventory, StudioInventoryCompanion } from "./inventory";
 import { findAction, promptArgs, skillInstalledFor, SUBJECT_PATTERN } from "./actions";
@@ -51,7 +53,8 @@ export interface DefaultAgentOutcome {
 /**
  * The companion's effective default agent for one provider: the active
  * audience's `studio.terminal.agent` (Studio's own `MATE_AUDIENCE`, never the
- * browser's), else the base one. Never throws and never echoes the configured
+ * browser's), else the base one. Its definition may come from the companion
+ * or from the active audience's rendered layer. Never throws and never echoes the configured
  * value into the notice.
  */
 export async function defaultAgentFor(
@@ -62,11 +65,13 @@ export async function defaultAgentFor(
   const configPath = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
   if (!fs.existsSync(configPath)) return {};
   let name: unknown;
+  let layer: string | null = null;
   try {
-    name = effectiveStudioAgent(
-      await new ConfigStore(configPath).load(),
-      readAudienceSelection(env),
-    );
+    const config = await new ConfigStore(configPath).load();
+    const audience = resolveAudience(config, readAudienceSelection(env));
+    const active = audience.ok ? audience.active : null;
+    name = effectiveStudioAgent(config, active);
+    if (active) layer = currentAudienceLayer(companionPath, active);
   } catch {
     return {};
   }
@@ -76,8 +81,12 @@ export async function defaultAgentFor(
       notice: "Default agent not applied: studio.terminal.agent is not a valid agent name.",
     };
   }
-  const definition = path.join(companionPath, AGENT_DEFINITION_DIRS[agent], `${name}.md`);
-  if (!fs.existsSync(definition)) {
+  /** The audience's own agents live in its launch layer, which the terminal's launch attaches. */
+  const roots = layer ? [companionPath, layer] : [companionPath];
+  const defined = roots.some((root) =>
+    fs.existsSync(path.join(root, AGENT_DEFINITION_DIRS[agent], `${name}.md`)),
+  );
+  if (!defined) {
     return {
       notice: `Default agent "${name}" not applied: this companion has no ${agent} definition for it.`,
     };