@uniqbit/mate-core 0.18.3 → 0.18.4

package/src/cli/commands/wrap.ts

@@ -33,12 +33,29 @@ function reportChangedPaths(changed: ProjectionChangedPaths): void {
 
 /**
  * `--companion` is consumed by the dispatch gate before the command runs, so it
- * is parsed there too; this only rejects anything else.
+ * is parsed there too. `--audience` names the audience the checkout's bare
+ * sessions get beside base.
  */
-export function parseWrapArgs(argv: string[]): { companion?: string } | { error: string } {
+export function parseWrapArgs(
+  argv: string[],
+): { companion?: string; audience?: string } | { error: string } {
   let companion: string | undefined;
+  let audience: string | undefined;
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]!;
+    if (arg === "--audience") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) return { error: "--audience requires a name" };
+      audience = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--audience=")) {
+      const value = arg.slice("--audience=".length);
+      if (!value) return { error: "--audience requires a name" };
+      audience = value;
+      continue;
+    }
     if (arg === "--companion") {
       const value = argv[index + 1];
       if (!value || value.startsWith("--")) return { error: "--companion requires a path" };
@@ -54,7 +71,10 @@ export function parseWrapArgs(argv: string[]): { companion?: string } | { error:
     }
     return { error: `unknown wrap option: ${arg}` };
   }
-  return companion === undefined ? {} : { companion };
+  return {
+    ...(companion === undefined ? {} : { companion }),
+    ...(audience === undefined ? {} : { audience }),
+  };
 }
 
 /**
@@ -108,8 +128,12 @@ export async function runWrapCommand(
   }
 
   /** Serialized with Session Prepare and every sync, which rewrite the same manifest. */
+  /**
+   * The flag is the only way to give a checkout's bare sessions an audience;
+   * without it the wrap is base and any recorded audience is withdrawn.
+   */
   const locked = await withCompanionLock(companionPath, attendedLockOptions(companionPath), () =>
-    wrap(companionPath, repository),
+    wrap(companionPath, repository, { audience: parsed.audience ?? null }),
   );
   const result: WrapPassResult = locked.acquired
     ? locked.value
@@ -126,6 +150,7 @@ export async function runWrapCommand(
       : `Already wrapped: ${result.projectionRoot}`,
   );
   console.log(`  Companion: ${result.companionPath}`);
+  if (result.audience) console.log(`  Audience:  ${result.audience}`);
   for (const document of result.documents) {
     console.log(`  Runtime:   ${document}`);
   }

package/src/cli/usage.ts

@@ -21,7 +21,7 @@ export function usage(): string {
     ` ${n} companion open`,
     ` ${n} companion tui`,
     ` ${n} working cleanup`,
-    ` ${n} wrap [--companion PATH]`,
+    ` ${n} wrap [--companion PATH] [--audience NAME]`,
     ` ${n} unwrap`,
     ` ${n} session prepare --repo <dir> [--json] [--sync]`,
     ` ${n} hub init [folder]`,
@@ -54,6 +54,7 @@ export function usage(): string {
     "",
     "Wrapped repositories:",
     ` ${n} wrap configures the repository so sessions you start yourself load the companion`,
+    ` ${n} wrap --audience NAME gives those sessions one audience beside base; plain wrap returns to base`,
     ` ${n} claude does not run while a repository is wrapped for Claude`,
     ` ${n} opencode wraps the repository for OpenCode itself, then starts plain \`opencode\``,
     ` ${n} unwrap withdraws the wrap and restores managed launches; the link is kept`,

package/src/hooks/session-guidance.ts

@@ -1,5 +1,8 @@
 // Deliver the companion guidance to a Claude session Mate did not launch.
+import { currentAudienceLayer, readLayerGuidanceSync } from "../runtime/audience-layer";
+import { resolveProjection } from "../runtime/projection";
 import { buildProjectedGuidance } from "../runtime/projected-guidance";
+import { readWrapStateSync } from "../runtime/wrap-state";
 import type { HookEnv } from "./validate-artifact-path";
 
 export interface GuidanceOutcome {
@@ -7,6 +10,19 @@ export interface GuidanceOutcome {
   stdout: string;
 }
 
+/**
+ * The guidance of the audience this checkout is wrapped for, from its layer.
+ * The wrap is the only source: an inherited `MATE_AUDIENCE` selects nothing.
+ */
+function wrappedAudienceGuidance(cwd: string): string {
+  const projection = resolveProjection(cwd);
+  if (!projection) return "";
+  const audience = readWrapStateSync(projection.repoRoot).audience;
+  if (!audience) return "";
+  const layer = currentAudienceLayer(projection.companionPath, audience);
+  return layer ? readLayerGuidanceSync(layer, "CLAUDE.md") : "";
+}
+
 /**
  * `SessionStart.additionalContext` is the file-based form of the managed
  * launch's `--append-system-prompt`: a settings document can declare a hook,
@@ -18,8 +34,10 @@ export interface GuidanceOutcome {
  * repository must read exactly as it did before the hook existed.
  */
 export function buildSessionGuidance(env: HookEnv, cwd: string = process.cwd()): GuidanceOutcome {
-  const guidance = buildProjectedGuidance(env, cwd);
-  if (!guidance) return { exitCode: 0, stdout: "" };
+  const companionGuidance = buildProjectedGuidance(env, cwd);
+  if (!companionGuidance) return { exitCode: 0, stdout: "" };
+  const layer = wrappedAudienceGuidance(cwd);
+  const guidance = layer ? `${companionGuidance}\n\n${layer}` : companionGuidance;
 
   return {
     exitCode: 0,

package/src/lib/orchestrator/adapters/base.ts

@@ -88,7 +88,8 @@ export abstract class LaunchAdapter<C extends AdapterContext = AdapterContext> {
 
   async validateLaunch(_context: C): Promise<void> {}
 
-  extendEnvironment(_context: C): NodeJS.ProcessEnv {
+  /** `args` are the operator's arguments, before `buildArgs` rewrites them. */
+  extendEnvironment(_context: C, _args: string[] = []): NodeJS.ProcessEnv {
     return {};
   }
 
@@ -130,7 +131,7 @@ export abstract class LaunchAdapter<C extends AdapterContext = AdapterContext> {
   async prepareLaunch(context: C, args: string[]): Promise<PreparedLaunch> {
     const builtArgs = this.buildArgs(context, args);
     const baseEnv = this.environment(context);
-    const extendedEnv = this.extendEnvironment(context);
+    const extendedEnv = this.extendEnvironment(context, args);
     const env = { ...baseEnv, ...extendedEnv };
 
     const processPath = process.env.PATH ?? "";

package/src/lib/orchestrator/adapters/claude.ts

@@ -9,6 +9,11 @@ import {
   type ClaudeDeliveryPlan,
   type SessionKind,
 } from "../../../runtime/claude-delivery-plan";
+import {
+  audienceLayerDir,
+  currentAudienceLayer,
+  readLayerGuidanceSync,
+} from "../../../runtime/audience-layer";
 import { hookGroupKey, type ClaudeHookGroup } from "../../../runtime/claude-hook-group";
 import { NOT_WRAPPED } from "../../../runtime/wrap-state";
 import { writeAtomic } from "../../../runtime/write-atomic";
@@ -19,15 +24,31 @@ import {
 import type { ClaudeSettings } from "../../../tools/setup/providers/claude-format";
 import { getContextModePackageRoot, validateContextModePackage } from "../../context-mode-package";
 import { getClaudePluginRoot, validateClaudePluginAssets } from "../../package-paths";
+import type { RenderedAudienceLayer } from "../../../tools/setup/audience-layer";
 import type { PrepareResult } from "../session-prepare";
 import { LaunchPreflightError } from "../types";
 import { type AdapterContext, LaunchAdapter } from "./base";
 
+/** The active audience's layer, attached to this launch only. */
+interface ClaudeLayerDelivery {
+  audience: string;
+  root: string;
+  /** The layer's MCP configuration, when the layer holds one. */
+  mcpConfigPath?: string;
+}
+
 /** The paths are present only where the plan names that channel and the file exists. */
 interface ClaudeDelivery {
   plan: ClaudeDeliveryPlan;
   settingsPath?: string;
   mcpConfigPath?: string;
+  layer?: ClaudeLayerDelivery;
+  /**
+   * The guidance of the audience the checkout is wrapped for. The wrap carries
+   * the rest of that audience; its guidance hook stays silent in a managed
+   * session, so the launch's own system prompt carries this.
+   */
+  wrappedGuidance?: string;
 }
 
 /** A Claude launch's context: the delivery its plan chose, and the files it chose or wrote. */
@@ -35,34 +56,75 @@ interface ClaudeLaunchContext extends AdapterContext {
   delivery: ClaudeDelivery;
 }
 
-/** Where a launch with a Working Repository writes its derived `--settings`; git-ignored. */
-export function launchSettingsPath(companionPath: string, repositoryId: string): string {
-  const safeId = repositoryId.replace(/[^A-Za-z0-9._-]/g, "_");
-  return path.join(companionPath, ".claude", "state", `launch-settings.${safeId}.json`);
+function safeName(value: string): string {
+  return value.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+/**
+ * Where a launch writes its derived `--settings`. Per Working Repository and
+ * audience, so concurrent launches never race; a companion-scoped launch
+ * derives one only for an audience. Without an audience it is git-ignored
+ * under the companion. With one it carries that audience's hooks and
+ * permission entries, so it lives beside the audience's layer, outside the
+ * companion, where no other audience's session can read it.
+ */
+export function launchSettingsPath(
+  companionPath: string,
+  repositoryId: string | null,
+  audience?: string,
+): string {
+  const scope = repositoryId === null ? "companion-scope" : `settings.${safeName(repositoryId)}`;
+  if (audience) {
+    return path.join(audienceLayerDir(companionPath, audience), `launch-${scope}.json`);
+  }
+  return path.join(companionPath, ".claude", "state", `launch-${scope}.json`);
+}
+
+async function readSettings(settingsPath: string): Promise<ClaudeSettings> {
+  if (!existsSync(settingsPath)) return {};
+  return JSON.parse(await fs.readFile(settingsPath, "utf8")) as ClaudeSettings;
 }
 
 /**
- * Companion settings minus `exclude`, so each wrap-carried group runs once. A
- * file, not inline JSON (platform arg limits); per repository, so concurrent
- * launches never race.
+ * Companion settings minus `exclude`, so each wrap-carried group runs once,
+ * plus the layer's hook groups and permission entries. A file, not inline JSON
+ * (platform arg limits). Claude reads one `--settings` file only — a second
+ * one replaces the first — so the layer is merged here, never passed beside.
  */
 async function writeLaunchSettings(
   companionSettingsPath: string,
   target: string,
   exclude: readonly ClaudeHookGroup[],
+  layerSettingsPath?: string,
 ): Promise<void> {
-  const settings = JSON.parse(await fs.readFile(companionSettingsPath, "utf8")) as ClaudeSettings;
+  const settings = await readSettings(companionSettingsPath);
+  const layer = layerSettingsPath ? await readSettings(layerSettingsPath) : {};
   const excluded = new Set(exclude.map(hookGroupKey));
   const hooks: Record<string, ClaudeHookGroup[]> = {};
   for (const [event, groups] of Object.entries(settings.hooks ?? {})) {
     const kept = (groups ?? []).filter((group) => !excluded.has(hookGroupKey(group)));
     if (kept.length > 0) hooks[event] = kept;
   }
+  for (const [event, groups] of Object.entries(layer.hooks ?? {})) {
+    hooks[event] = [...(hooks[event] ?? []), ...(groups ?? [])];
+  }
   const derived: ClaudeSettings = { ...settings, hooks };
   if (Object.keys(hooks).length === 0) delete derived.hooks;
+  const layerAllow = layer.permissions?.allow ?? [];
+  if (layerAllow.length > 0) {
+    const allow = [...new Set([...(settings.permissions?.allow ?? []), ...layerAllow])];
+    derived.permissions = { ...settings.permissions, allow };
+  }
 
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  await writeAtomic(target, `${JSON.stringify(derived, null, 2)}\n`);
+  const text = `${JSON.stringify(derived, null, 2)}\n`;
+  if (layerSettingsPath) {
+    /** Beside the audience's layer: as private as the layer itself. */
+    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    await writeAtomic(target, text, 0o600);
+  } else {
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await writeAtomic(target, text);
+  }
 }
 
 /** The `--settings` file the plan's hook owner calls for, writing it when derived. */
@@ -70,16 +132,38 @@ async function settingsPathFor(
   plan: ClaudeDeliveryPlan,
   companionPath: string,
   repository: AdapterContext["repository"],
+  layer: RenderedAudienceLayer | undefined,
 ): Promise<string | undefined> {
   const companionSettingsPath = getCompanionClaudeSettingsPath(companionPath);
-  if (plan.hooks.owner === "none" || !existsSync(companionSettingsPath)) return undefined;
-  if (plan.hooks.owner === "settings") return companionSettingsPath;
+  if (plan.hooks.owner === "none") return undefined;
+  if (!layer && !existsSync(companionSettingsPath)) return undefined;
+  if (plan.hooks.owner === "settings" && !layer) return companionSettingsPath;
   /** Owner `wrap` is planned only for `managed-repo`, which has a repository. */
-  const settingsPath = launchSettingsPath(companionPath, repository!.id);
-  await writeLaunchSettings(companionSettingsPath, settingsPath, plan.hooks.launchSettingsExclude);
+  const settingsPath = launchSettingsPath(
+    companionPath,
+    plan.hooks.owner === "wrap" ? repository!.id : null,
+    layer?.audience,
+  );
+  await writeLaunchSettings(
+    companionSettingsPath,
+    settingsPath,
+    plan.hooks.launchSettingsExclude,
+    layer ? getCompanionClaudeSettingsPath(layer.root) : undefined,
+  );
   return settingsPath;
 }
 
+/** The layer as this launch attaches it: the directory, and its MCP configuration when present. */
+function layerDelivery(layer: RenderedAudienceLayer | undefined): ClaudeLayerDelivery | undefined {
+  if (!layer) return undefined;
+  const mcpConfigPath = getCompanionClaudeMcpConfigPath(layer.root);
+  return {
+    audience: layer.audience,
+    root: layer.root,
+    ...(existsSync(mcpConfigPath) ? { mcpConfigPath } : {}),
+  };
+}
+
 export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
   readonly toolName = "claude";
   readonly interactive = true;
@@ -100,11 +184,22 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
     }
     const plan = planClaudeDelivery(kind, wrap);
     const mcpConfigPath = getCompanionClaudeMcpConfigPath(companionPath);
-    const settingsPath = await settingsPathFor(plan, companionPath, repository);
+    const settingsPath = await settingsPathFor(
+      plan,
+      companionPath,
+      repository,
+      prepared.audienceLayer,
+    );
+    const layer = layerDelivery(prepared.audienceLayer);
+    const wrappedLayer =
+      !layer && wrap.audience ? currentAudienceLayer(companionPath, wrap.audience) : null;
+    const wrappedGuidance = wrappedLayer ? readLayerGuidanceSync(wrappedLayer, "CLAUDE.md") : "";
     const delivery: ClaudeDelivery = {
       plan,
       ...(plan.mcp === "mcp-config" && existsSync(mcpConfigPath) ? { mcpConfigPath } : {}),
       ...(settingsPath ? { settingsPath } : {}),
+      ...(layer ? { layer } : {}),
+      ...(wrappedGuidance ? { wrappedGuidance } : {}),
     };
     return { ...context, delivery };
   }
@@ -149,15 +244,30 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
    * and context-mode are unconditional: no settings document can carry them.
    */
   buildArgs(context: ClaudeLaunchContext, args: string[]): string[] {
-    const { plan, settingsPath, mcpConfigPath } = context.delivery;
+    const { plan, settingsPath, mcpConfigPath, layer, wrappedGuidance } = context.delivery;
+    const companionGuidance = buildCompanionGuidance(context);
+    const systemPrompt = wrappedGuidance
+      ? `${companionGuidance}\n\n${wrappedGuidance}`
+      : companionGuidance;
     /** Layered on the user's own sources so global skills and plugins still load. */
     const settingsArgs =
       plan.hooks.owner !== "none" && settingsPath
         ? ["--setting-sources", "user,project,local", "--settings", settingsPath]
         : [];
-    const addDirArgs = plan.dirAccess === "add-dir" ? ["--add-dir", context.companionPath] : [];
-    const mcpConfigArgs =
-      plan.mcp === "mcp-config" && mcpConfigPath ? ["--mcp-config", mcpConfigPath] : [];
+    /**
+     * The layer adds its skills, commands, agents and `CLAUDE.md` as one more
+     * directory, and its MCP servers as one more configuration beside every
+     * server the launch delivered before. Both flags are variadic, so each is
+     * followed by another flag, never by the operator's arguments.
+     */
+    const addDirArgs = [
+      ...(plan.dirAccess === "add-dir" ? ["--add-dir", context.companionPath] : []),
+      ...(layer ? ["--add-dir", layer.root] : []),
+    ];
+    const mcpConfigArgs = [
+      ...(plan.mcp === "mcp-config" && mcpConfigPath ? ["--mcp-config", mcpConfigPath] : []),
+      ...(layer?.mcpConfigPath ? ["--mcp-config", layer.mcpConfigPath] : []),
+    ];
     const contextModeArgs = context.capabilities.some(
       (capability) => capability.name === "context-mode",
     )
@@ -167,7 +277,7 @@ export class ClaudeAdapter extends LaunchAdapter<ClaudeLaunchContext> {
     return [
       ...addDirArgs,
       "--append-system-prompt",
-      buildCompanionGuidance(context),
+      systemPrompt,
       ...settingsArgs,
       ...mcpConfigArgs,
       /** The bundled plugin from the running install, beside context-mode's. */

package/src/lib/orchestrator/adapters/opencode.ts

@@ -36,7 +36,32 @@ function parseOpenCodeMajor(output: string | undefined): number | undefined {
   return match ? Number(match[1]) : undefined;
 }
 
-export class OpenCodeAdapter extends LaunchAdapter {
+interface OpenCodeInvocation {
+  command: string | undefined;
+  rest: string[];
+  /**
+   * The launch runs its own private server, where the plugin loads with this
+   * launch's environment: the TUI or `run`, not pointed at a remote server.
+   * Every other invocation may start or reach the shared service, which must
+   * never receive a guidance payload.
+   */
+  hostsPrivateServer: boolean;
+}
+
+function readInvocation(launchWorkingDirectory: string, args: string[]): OpenCodeInvocation {
+  const isTui = args.length === 0 || args[0]?.startsWith("-");
+  const [command, ...rest] = isTui ? [launchWorkingDirectory, ...args] : args;
+  const hostsServer = isTui || command === "run";
+  const choosesRemoteServer = rest.some((arg) => arg === "--server" || arg.startsWith("--server="));
+  return { command, rest, hostsPrivateServer: Boolean(hostsServer) && !choosesRemoteServer };
+}
+
+/** An OpenCode launch's context: the audience layer its prepare rendered, if any. */
+interface OpenCodeLaunchContext extends AdapterContext {
+  audienceLayer?: string;
+}
+
+export class OpenCodeAdapter extends LaunchAdapter<OpenCodeLaunchContext> {
   readonly toolName = "opencode";
   readonly interactive = true;
   private readonly requiredRuntimeAssets = [path.join(".opencode", "opencode.json")] as const;
@@ -59,6 +84,15 @@ export class OpenCodeAdapter extends LaunchAdapter {
     );
   }
 
+  async planLaunch(
+    context: AdapterContext,
+    prepared: PrepareResult,
+  ): Promise<OpenCodeLaunchContext> {
+    return prepared.audienceLayer
+      ? { ...context, audienceLayer: prepared.audienceLayer.root }
+      : context;
+  }
+
   /** A prepared repository reports its failure as one summary, as it always has. */
   launchFailure(prepared: PrepareResult): unknown {
     return prepared.repositoryId
@@ -67,15 +101,13 @@ export class OpenCodeAdapter extends LaunchAdapter {
   }
 
   buildArgs(context: AdapterContext, args: string[]): string[] {
-    const codeDir = context.launchWorkingDirectory;
-    const isTui = args.length === 0 || args[0]?.startsWith("-");
-    const [command, ...rest] = isTui ? [codeDir, ...args] : args;
-    if (!command) return args;
-    const hostsServer = isTui || command === "run";
-    const choosesServer = rest.some(
-      (arg) => arg === "--standalone" || arg === "--server" || arg.startsWith("--server="),
+    const { command, rest, hostsPrivateServer } = readInvocation(
+      context.launchWorkingDirectory,
+      args,
     );
-    return hostsServer && !choosesServer ? [command, STANDALONE_FLAG, ...rest] : [command, ...rest];
+    if (!command) return args;
+    const addsStandalone = hostsPrivateServer && !rest.includes(STANDALONE_FLAG);
+    return addsStandalone ? [command, STANDALONE_FLAG, ...rest] : [command, ...rest];
   }
 
   /**
@@ -84,21 +116,29 @@ export class OpenCodeAdapter extends LaunchAdapter {
    * overlay carried now lives in the wrapped `.opencode/opencode.json`. An
    * inherited `OPENCODE_CONFIG_DIR` or `OPENCODE_CONFIG_CONTENT` passes through.
    */
-  extendEnvironment(context: AdapterContext): NodeJS.ProcessEnv {
+  extendEnvironment(context: OpenCodeLaunchContext, args: string[] = []): NodeJS.ProcessEnv {
+    const { hostsPrivateServer } = readInvocation(context.launchWorkingDirectory, args);
     return {
       // Built fresh per launch from the live capability config; always set so
       // a stale value inherited from an outer Mate session can never leak in.
-      [MATE_ENV.guidanceJson]: JSON.stringify(this.buildGuidance(context)),
+      // Masked unless the launch hosts its own server: a payload that reached
+      // the shared service would apply this session's guidance — and its
+      // audience layer — to every other.
+      [MATE_ENV.guidanceJson]: hostsPrivateServer
+        ? JSON.stringify(this.buildGuidance(context))
+        : "",
     };
   }
 
-  private buildGuidance(context: AdapterContext): MateGuidanceFile {
-    return buildOpenCodeGuidance(context.capabilities, {
+  /** The audience layer travels as a path; the plugin reads it through the surface's reader. */
+  private buildGuidance(context: OpenCodeLaunchContext): MateGuidanceFile {
+    const guidance = buildOpenCodeGuidance(context.capabilities, {
       companionScoped: !context.repository,
     });
+    return context.audienceLayer ? { ...guidance, audienceLayer: context.audienceLayer } : guidance;
   }
 
-  async validateLaunch(context: AdapterContext): Promise<void> {
+  async validateLaunch(context: OpenCodeLaunchContext): Promise<void> {
     this.validateOpenCodeVersion();
 
     const missingAssets = await Promise.all(
@@ -162,7 +202,7 @@ export class OpenCodeAdapter extends LaunchAdapter {
 
   // Self-check the guidance payload this launch is about to inject so a
   // broken playbook template fails preflight instead of inside OpenCode.
-  private validateGuidance(context: AdapterContext): string[] {
+  private validateGuidance(context: OpenCodeLaunchContext): string[] {
     const built = this.buildGuidance(context);
     const { guidance, errors } = validateGuidanceData(built);
 

package/src/lib/orchestrator/config-store.ts

@@ -1,5 +1,14 @@
 import path from "node:path";
 
+import semver from "semver";
+
+import {
+  BASE_AUDIENCE,
+  BASE_AUDIENCE_KEYS,
+  normalizeBaseAudience,
+} from "../../tools/setup/dynamic-plugins/audiences";
+
+import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
 import {
   getDefaultSetupSelections,
@@ -291,19 +300,83 @@ function validateAudiences(config: FrameworkConfig): void {
   }
 }
 
+/**
+ * The release that introduces the `audiences.base` shape. An older Mate would
+ * read a saved file as an empty base plus an audience called `base`, so every
+ * save in the new shape raises the companion's `engines` floor to it — capped
+ * at the running release, so a pre-release build never locks itself out.
+ */
+export const BASE_AUDIENCE_MIN_VERSION = "0.19.0";
+
+/** The floor version a save writes: the introducing release, or the running one when older. */
+export function baseAudienceFloorVersion(
+  runningVersion: string = getActiveDistribution().config.version,
+): string {
+  const running = semver.coerce(runningVersion)?.version;
+  return running && semver.lt(running, BASE_AUDIENCE_MIN_VERSION)
+    ? running
+    : BASE_AUDIENCE_MIN_VERSION;
+}
+
+/** Only companions carry audiences; a hub or a working repository keeps the root shape. */
+function usesAudiences(config: FrameworkConfig): boolean {
+  return config.type === undefined || config.type === "companion";
+}
+
+/** The floor that admits the base audience shape, keeping a higher one. */
+function raisedEngineFloor(range: string | undefined): string {
+  const version = baseAudienceFloorVersion();
+  const floor = `>=${version}`;
+  if (!range || semver.validRange(range) === null) return range ?? floor;
+  const minimum = semver.minVersion(range);
+  return minimum && semver.gte(minimum, version) ? range : floor;
+}
+
+/**
+ * The file shape of a companion config: the base set's audience-scoped keys
+ * under `audiences.base`, first among the audiences. The in-memory config
+ * keeps them at the root, so its readers never see the difference.
+ */
+function toFileShape(config: FrameworkConfig): FrameworkConfig {
+  if (!usesAudiences(config)) return config;
+  const base: Record<string, unknown> = {};
+  const rest: Record<string, unknown> = { ...config };
+  for (const key of BASE_AUDIENCE_KEYS) {
+    if (rest[key] === undefined) continue;
+    base[key] = rest[key];
+    delete rest[key];
+  }
+  if (Object.keys(base).length === 0) return config;
+  return {
+    ...(rest as unknown as FrameworkConfig),
+    audiences: { [BASE_AUDIENCE]: base, ...config.audiences } as FrameworkConfig["audiences"],
+    engines: {
+      ...config.engines,
+      [FRAMEWORK_NAME]: raisedEngineFloor(config.engines?.[FRAMEWORK_NAME]),
+    },
+  };
+}
+
 export class ConfigStore extends YamlFileStore<FrameworkConfig> {
   constructor(configPath = process.env.MATE_CONFIG ?? defaultConfigPath()) {
     super(path.resolve(configPath));
   }
 
+  /** Either file shape loads as the base set at the root; the new shape persists on the next save. */
   override async load(): Promise<FrameworkConfig> {
-    const merged = mergeWithDefaults(migrateProfilesToAllowedAgents(await super.load()));
+    const merged = mergeWithDefaults(
+      migrateProfilesToAllowedAgents(normalizeBaseAudience(await super.load())),
+    );
     validateHubConfig(merged);
     validatePluginDeclarations(merged);
     validateAudiences(merged);
     return merged;
   }
 
+  override async save(config: FrameworkConfig): Promise<void> {
+    await super.save(toFileShape(config));
+  }
+
   protected async onMissing(): Promise<FrameworkConfig> {
     const config = defaultConfig();
     await this.save(config);