@uniqbit/mate-core 0.18.3 → 0.18.4

package/src/lib/orchestrator/session-prepare.ts

@@ -7,8 +7,14 @@ import {
   syncCompanionUnattended,
   type UnattendedSyncOutcome,
 } from "../../runtime/companion-sync";
-import type { WrapState } from "../../runtime/wrap-state";
+import { readWrapStateSync, type WrapState } from "../../runtime/wrap-state";
 import { syncCompanionFiles } from "../../tools/setup";
+import { renderAudienceLayer, type RenderedAudienceLayer } from "../../tools/setup/audience-layer";
+import {
+  readAudienceSelection,
+  resolveAudience,
+} from "../../tools/setup/dynamic-plugins/audiences";
+import { buildSetupInstallationPlan } from "../../tools/setup/engine";
 import type { CapabilityPlugin, LaunchPreflightContext } from "../../tools/setup/plugin";
 import { attendedLockOptions, syncCompanionGit } from "./companion-git-sync";
 import { readCompanionConfig } from "./config-store";
@@ -34,7 +40,8 @@ export type PrepareStepName =
   | "file-sync"
   | "launch-projection"
   | "working-target"
-  | "preflight";
+  | "preflight"
+  | "audience-layer";
 
 export interface PrepareStep {
   step: PrepareStepName;
@@ -61,6 +68,8 @@ export interface PrepareResult {
   failure?: unknown;
   /** The wrap state the `working-target` step's pass left; a launch reads no manifest itself. */
   wrapState?: WrapState;
+  /** The active audience's layer, rendered for an attended prepare only. */
+  audienceLayer?: RenderedAudienceLayer;
 }
 
 export interface PrepareSessionInput {
@@ -89,9 +98,10 @@ const SYNC_LOCK_TIMEOUT_MS = 5 * 60_000;
  */
 async function runCapabilityPreflight(context: LaunchPreflightContext): Promise<void> {
   const { config, providerId } = context;
+  /** Base only: an audience plugin's `forProvider` hooks never run. */
   const preflights = getActiveDistribution()
-    .registry.getAll()
-    .flatMap((plugin) => {
+    .registry.baseRegistrations()
+    .flatMap(({ plugin }) => {
       if (plugin.kind !== "capability" || !plugin.isEnabled(config)) return [];
       const capability = plugin as CapabilityPlugin;
       const preflight = capability.forProvider?.[providerId]?.preflight;
@@ -137,6 +147,11 @@ export const sessionPrepareDeps = {
   withCompanionLock,
   /** As the launch decides it: Git may prompt only with a terminal on both ends. */
   isInteractiveTerminal: () => !!(process.stdin.isTTY && process.stdout.isTTY),
+  /** The launch's `MATE_AUDIENCE`; read by an attended prepare only. */
+  audienceSelection: () => readAudienceSelection(process.env),
+  /** The audience a checkout is wrapped for, from its manifest; `null` for base. */
+  wrappedAudience: (repoPath: string) => readWrapStateSync(repoPath).audience,
+  renderAudienceLayer,
 };
 
 function message(error: unknown): string {
@@ -149,6 +164,7 @@ class StepLog {
   readonly warnings: string[] = [];
   failure: unknown;
   wrapState: WrapState | undefined;
+  audienceLayer: RenderedAudienceLayer | undefined;
   stopped = false;
   companionChanged = false;
 
@@ -321,12 +337,71 @@ async function runLocal(
   });
 }
 
+/**
+ * The active audience's launch layer, after the base prepare. Only a managed
+ * launch reaches here: a bare session's prepare never renders one, whatever
+ * `MATE_AUDIENCE` its environment carries. An audience the companion does not
+ * declare renders nothing; hydration already warned about it.
+ */
+async function renderLayer(
+  input: PrepareSessionInput,
+  config: FrameworkConfig,
+  run: StepLog,
+): Promise<void> {
+  const deps = sessionPrepareDeps;
+  /** Adopted from the wrap: the wrap delivers it, so the launch renders no layer of its own. */
+  const wrapped = input.repository ? deps.wrappedAudience(input.repository.path) : null;
+  if (wrapped) {
+    run.push({ step: "audience-layer", outcome: "ok", detail: `${wrapped}: from the wrap` });
+    return;
+  }
+  const audience = resolveAudience(config, deps.audienceSelection());
+  if (!audience.ok || audience.active === null) return;
+  try {
+    const registry = getActiveDistribution().registry;
+    const layer = await deps.renderAudienceLayer({
+      companionPath: input.companionPath,
+      config,
+      audience: audience.active,
+      activeProviders: buildSetupInstallationPlan(config, registry.baseRegistrations())
+        .activeProviders,
+      registrations: registry.audienceRegistrations(audience.active),
+    });
+    run.audienceLayer = layer;
+    run.push({
+      step: "audience-layer",
+      outcome: "ok",
+      detail: `${layer.audience}: ${layer.rendered ? "rendered" : "current"}`,
+    });
+  } catch (error) {
+    run.fail("audience-layer", error);
+  }
+}
+
+/**
+ * A checkout wrapped for one audience refuses a launch for another before
+ * anything runs: the wrap's on-disk content would reach that session.
+ */
+function audienceConflict(input: PrepareSessionInput, config: FrameworkConfig): string | null {
+  if (!input.repository) return null;
+  const wrapped = sessionPrepareDeps.wrappedAudience(input.repository.path);
+  if (!wrapped) return null;
+  const selected = resolveAudience(config, sessionPrepareDeps.audienceSelection());
+  if (!selected.ok || selected.active === null || selected.active === wrapped) return null;
+  return `${FRAMEWORK_NAME}: ${input.repository.id} is wrapped for audience "${wrapped}", but MATE_AUDIENCE selects "${selected.active}". Run \`${FRAMEWORK_NAME} wrap --audience ${selected.active}\` in ${input.repository.path}, or launch from another worktree wrapped for "${selected.active}".`;
+}
+
 async function runAttended(
   input: PrepareSessionInput,
   config: FrameworkConfig,
   run: StepLog,
 ): Promise<void> {
   const deps = sessionPrepareDeps;
+  const conflict = audienceConflict(input, config);
+  if (conflict) {
+    run.fail("audience-layer", new LaunchPreflightError(conflict));
+    return;
+  }
   if (input.skipGit) {
     run.push({ step: "git-sync", outcome: "skipped", detail: "--no-git" });
   } else if (config.git !== "auto") {
@@ -347,6 +422,8 @@ async function runAttended(
     }
   }
   await runLocal(input, config, run);
+  if (run.stopped) return;
+  await renderLayer(input, config, run);
 }
 
 /** The sync's own config read: only a fast-forward can have changed it. */
@@ -401,6 +478,7 @@ export async function prepareSession(input: PrepareSessionInput): Promise<Prepar
     ...(run.companionChanged ? { companionChanged: true as const } : {}),
     ...(run.failure === undefined ? {} : { failure: run.failure }),
     ...(run.wrapState ? { wrapState: run.wrapState } : {}),
+    ...(run.audienceLayer ? { audienceLayer: run.audienceLayer } : {}),
   });
 
   const locked = await deps.withCompanionLock(input.companionPath, lockOptions(input), async () => {

package/src/lib/orchestrator/working-repo-projection.ts

@@ -120,7 +120,8 @@ export async function unproject(input: ProjectionRemovalInput): Promise<Projecti
     }
     try {
       // oxlint-disable-next-line no-await-in-loop -- reverse catalogue order is the contract
-      outcomes.push(outcome(entry, await removal.remove(input)));
+      const removed = outcome(entry, await removal.remove(input));
+      outcomes.push(removal.retains ? { ...removed, retains: removal.retains } : removed);
     } catch (error) {
       outcomes.push(outcome(entry, "failed", toError(error)));
     }

package/src/lib/orchestrator/wrap-pass.ts

@@ -1,11 +1,24 @@
 import path from "node:path";
 
 import { renderWorkingRuntimeDocuments } from "../../tools/setup";
+import { renderAudienceLayer } from "../../tools/setup/audience-layer";
+import { loadAudienceRegistrations } from "../../tools/setup/audience-registrations";
+import { declaredAudiences } from "../../tools/setup/dynamic-plugins/audiences";
+import { buildSetupInstallationPlan } from "../../tools/setup/engine";
+import { getActiveDistribution } from "../../distribution";
+import { audienceLayerDir } from "../../runtime/audience-layer";
+import {
+  readManifest,
+  recordedAudience,
+  updateManifest,
+  withAudience,
+} from "../../runtime/runtime-document-manifest";
 import { readCompanionConfig } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
 import { entryFailureMessage, firstFailure, type ProjectionChangedPaths } from "./projection-types";
 import type { WrapRuntime } from "../../runtime/runtime-document-manifest";
 import { readWrapState, type WrapState } from "../../runtime/wrap-state";
+import type { NormalizedRegistration } from "../../tools/setup/registry";
 import type { FrameworkConfig, LinkedRepository } from "./types";
 import { project } from "./working-repo-projection";
 
@@ -13,6 +26,8 @@ export interface WrapPassDependencies {
   renderWorkingRuntimeDocuments: typeof renderWorkingRuntimeDocuments;
   readCompanionConfig: typeof readCompanionConfig;
   project: typeof project;
+  loadAudienceRegistrations: typeof loadAudienceRegistrations;
+  renderAudienceLayer: typeof renderAudienceLayer;
   /** The registered companions, whose stale skill links a re-pin withdraws; the user's registry when absent. */
   globalConfigStore?: GlobalConfigStore;
 }
@@ -21,6 +36,8 @@ export const wrapPassDeps: WrapPassDependencies = {
   renderWorkingRuntimeDocuments,
   readCompanionConfig,
   project,
+  loadAudienceRegistrations,
+  renderAudienceLayer,
 };
 
 export interface WrapPassOptions {
@@ -28,6 +45,12 @@ export interface WrapPassOptions {
   runtimes?: readonly WrapRuntime[];
   /** The companion config the caller already read; read from files otherwise. */
   config?: FrameworkConfig;
+  /**
+   * The audience to wrap the checkout for: a name records it, `null` withdraws
+   * it, absent keeps the one the manifest records. Never read from the
+   * environment: it is the only source of a bare session's audience.
+   */
+  audience?: string | null;
 }
 
 export type WrapPassResult =
@@ -47,9 +70,21 @@ export type WrapPassResult =
       runtimes: ReadonlySet<WrapRuntime>;
       /** The wrap state as this pass left it. */
       wrapState: WrapState;
+      /** The audience the checkout is wrapped for after this pass. */
+      audience: string | null;
     }
   | { kind: "failed"; message: string };
 
+/** An audience a checkout may be wrapped for: declared by the companion, never the reserved base. */
+function wrappableAudience(config: FrameworkConfig, audience: string): boolean {
+  return audience !== "base" && declaredAudiences(config).includes(audience);
+}
+
+function describeUnwrappable(config: FrameworkConfig, audience: string): string {
+  const declared = declaredAudiences(config).filter((name) => name !== "base");
+  return `audience "${audience}" cannot be wrapped: the companion declares ${declared.length > 0 ? declared.join(", ") : "no audiences"}.`;
+}
+
 /**
  * One pass of the `wrap` scope, restricted to the requested runtimes by each
  * entry's runtime tag. Best-effort per entry like every projection: a failed
@@ -63,10 +98,50 @@ export async function runWrapPass(
 ): Promise<WrapPassResult> {
   const resolvedCompanionPath = path.resolve(companionPath);
   const config = options.config ?? (await deps.readCompanionConfig(resolvedCompanionPath));
+
+  const audienceWarnings: string[] = [];
+  let audience: string | null;
+  if (options.audience === undefined) {
+    const recorded = recordedAudience(await readManifest(repository.path));
+    /** A recorded audience the companion no longer declares falls back to base, never fails a prepare. */
+    if (recorded && !wrappableAudience(config, recorded)) {
+      audienceWarnings.push(
+        `${describeUnwrappable(config, recorded)} ${repository.id} is wrapped for base only.`,
+      );
+      audience = null;
+    } else {
+      audience = recorded;
+    }
+  } else {
+    audience = options.audience;
+    if (audience && !wrappableAudience(config, audience)) {
+      return { kind: "failed", message: describeUnwrappable(config, audience) };
+    }
+  }
+
+  let wrapped: { audience: string; registrations: NormalizedRegistration[] } | undefined;
+  if (audience) {
+    const loaded = await deps.loadAudienceRegistrations(resolvedCompanionPath, config, audience);
+    audienceWarnings.push(...loaded.warnings);
+    await deps.renderAudienceLayer({
+      companionPath: resolvedCompanionPath,
+      config,
+      audience,
+      activeProviders: buildSetupInstallationPlan(
+        config,
+        getActiveDistribution().registry.baseRegistrations(),
+      ).activeProviders,
+      registrations: loaded.registrations,
+    });
+    wrapped = { audience, registrations: loaded.registrations };
+  }
+
   const rendered = await deps.renderWorkingRuntimeDocuments(
     resolvedCompanionPath,
     config,
     repository.path,
+    undefined,
+    wrapped,
   );
   const result = await deps.project("wrap", {
     repoPath: repository.path,
@@ -74,6 +149,7 @@ export async function runWrapPass(
     repository,
     config,
     runtimeDocuments: rendered.documents,
+    audienceLayerDir: audience ? audienceLayerDir(resolvedCompanionPath, audience) : null,
     globalConfigStore: deps.globalConfigStore ?? new GlobalConfigStore(),
     ...(options.runtimes ? { runtimes: options.runtimes } : {}),
   });
@@ -81,6 +157,12 @@ export async function runWrapPass(
   const failure = firstFailure(result.outcomes);
   if (failure) return { kind: "failed", message: entryFailureMessage(failure, repository.id) };
 
+  const before = recordedAudience(await readManifest(repository.path));
+  const audienceChanged = before !== audience;
+  if (audienceChanged) {
+    await updateManifest(repository.path, (manifest) => withAudience(manifest, audience));
+  }
+
   /** Read once under the caller's lock, so it is exactly what the pass recorded. */
   let wrapState: WrapState;
   try {
@@ -112,7 +194,10 @@ export async function runWrapPass(
     .map((outcome) => outcome.path);
 
   return {
-    kind: result.outcomes.some((outcome) => outcome.state === "written") ? "written" : "current",
+    kind:
+      audienceChanged || result.outcomes.some((outcome) => outcome.state === "written")
+        ? "written"
+        : "current",
     projectionRoot: result.root,
     companionPath: resolvedCompanionPath,
     documents: [...new Set(documents)],
@@ -122,10 +207,16 @@ export async function runWrapPass(
       removed: result.outcomes.flatMap((outcome) => outcome.changed?.removed ?? []),
     },
     warnings: [
+      ...audienceWarnings,
       ...rendered.warnings,
       ...result.outcomes.flatMap((outcome) => outcome.warnings ?? []),
+      /** A degradable failure does not fail the pass, but it is never silent. */
+      ...result.outcomes
+        .filter((outcome) => outcome.state === "failed" && outcome.degradable)
+        .map((outcome) => entryFailureMessage(outcome, repository.id)),
     ],
     runtimes,
     wrapState,
+    audience,
   };
 }

package/src/opencode/companion-hooks.ts

@@ -99,6 +99,7 @@ export async function guardToolInput(
   context: CompanionContext,
   tool: string,
   input: unknown,
+  env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   const args = (input ?? {}) as Record<string, unknown>;
   const filePaths =
@@ -113,25 +114,27 @@ export async function guardToolInput(
       throw new Error(buildArtifactError(context, filePath));
     }
     // oxlint-disable-next-line no-await-in-loop -- the first refusal wins
-    await refuseForkedCompanionWrite(context, filePath);
+    await refuseForkedCompanionWrite(context, filePath, env);
   }
 }
 
 /**
  * Registers the companion guardrails on an OpenCode V2 plugin context.
- * The caller resolves `context` and skips this when no companion resolved.
+ * The caller resolves `context` and skips this when no companion resolved;
+ * `env` is the launch environment the caller decided to trust.
  */
 export async function registerCompanionHooks(
   api: Context,
   context: CompanionContext,
+  env: Record<string, string | undefined> = process.env,
 ): Promise<void> {
   /**
    * Anything escaping the repair would cost the session every guardrail
    * below to save a synchronization that is optional by design.
    */
-  await repairCompanionGitOnce(context, process.env, api.location.directory).catch(() => []);
+  await repairCompanionGitOnce(context, env, api.location.directory).catch(() => []);
 
   await api.tool.hook("execute.before", (event) =>
-    guardToolInput(context, event.tool, event.input),
+    guardToolInput(context, event.tool, event.input, env),
   );
 }

package/src/opencode/projected-guidance.ts

@@ -1,14 +1,13 @@
 import { buildOpenCodeGuidance } from "../runtime/companion-guidance";
 import { MATE_ENV } from "../runtime/env-names";
-import { hasLaunchEnvironment } from "../runtime/env";
 import { parseGuidanceContent, type MateGuidanceFile } from "../runtime/guidance";
 import { readCompanionPolicy } from "../runtime/policy";
 import { resolveProjection } from "../runtime/projection";
 
 /**
  * `null` guidance with no errors is the inert case — no companion resolves, so
- * the plugin contributes nothing. Errors are startup failures: a managed launch
- * that failed to inject its payload is broken and must say so.
+ * the plugin contributes nothing. Errors are startup failures: a payload that
+ * does not parse, or projected guidance that cannot be built.
  */
 export interface OpenCodeGuidanceResolution {
   guidance: MateGuidanceFile | null;
@@ -26,9 +25,10 @@ export interface OpenCodeGuidanceResolution {
  * means a Capability toggled after a wrap changes the guidance on the next
  * session with no re-wrap.
  *
- * A missing payload while a launch environment *is* present stays a hard error.
- * That combination means a managed launch failed to inject, which the projection
- * must not paper over.
+ * Without a payload the projection decides, whatever other `MATE_*` variables
+ * `env` carries: those are inherited by every descendant of a Mate session and
+ * do not mark a managed launch. A present but malformed payload stays a hard
+ * error.
  */
 export function resolveOpenCodeGuidance(
   env: Record<string, string | undefined> = process.env,
@@ -40,13 +40,6 @@ export function resolveOpenCodeGuidance(
     return { guidance: errors.length > 0 ? null : guidance, errors };
   }
 
-  if (hasLaunchEnvironment(env)) {
-    return {
-      guidance: null,
-      errors: [`missing ${MATE_ENV.guidanceJson} in the launch environment`],
-    };
-  }
-
   const projection = resolveProjection(cwd);
   if (!projection) return { guidance: null, errors: [] };
 

package/src/runtime/audience-layer.ts

@@ -0,0 +1,84 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "./framework";
+import { mateHome } from "./runtime-directory";
+
+/**
+ * Audience Layer locations. A layer holds one audience's plugin contributions
+ * for one companion, rendered for managed launches only. It lives under Mate's
+ * machine-local state, never inside a repository: a layer inside the companion
+ * would be readable by every session with companion access, and could carry
+ * values resolved from plugin configuration.
+ *
+ *   <state>/audience-layers/<companion-key>/<audience>/
+ *     <fingerprint>/   one complete render; never changed once renamed into place
+ *     current          symlink to the newest complete render
+ *
+ * A launch attaches the fingerprint directory itself, so a later re-render
+ * never changes what a running session reads.
+ */
+
+/** Mirrors `AUDIENCE_NAME_PATTERN`; repeated here because `runtime/` imports nothing from core. */
+const SAFE_AUDIENCE = /^[a-z][a-z0-9-]{0,63}$/;
+
+export const CURRENT_LAYER_LINK = "current";
+
+export function audienceLayersRoot(homeDir?: string): string {
+  return path.join(mateHome(homeDir), "state", "audience-layers");
+}
+
+/** A short, stable key for one companion checkout: a hash of its resolved path. */
+export function companionLayerKey(companionPath: string): string {
+  return crypto.createHash("sha256").update(path.resolve(companionPath)).digest("hex").slice(0, 16);
+}
+
+/** The directory holding one audience's layers for one companion. */
+export function audienceLayerDir(
+  companionPath: string,
+  audience: string,
+  homeDir?: string,
+): string {
+  if (!SAFE_AUDIENCE.test(audience)) {
+    throw new Error(`"${audience}" is not a valid audience name for a layer directory`);
+  }
+  return path.join(audienceLayersRoot(homeDir), companionLayerKey(companionPath), audience);
+}
+
+/** The newest complete layer of `audience`, or `null` when none was rendered on this machine. */
+export function currentAudienceLayer(
+  companionPath: string,
+  audience: string,
+  homeDir?: string,
+): string | null {
+  try {
+    const dir = audienceLayerDir(companionPath, audience, homeDir);
+    const layer = path.join(dir, fs.readlinkSync(path.join(dir, CURRENT_LAYER_LINK)));
+    return fs.existsSync(layer) ? layer : null;
+  } catch {
+    return null;
+  }
+}
+
+const MANAGED_MARKER = new RegExp(
+  `^<!-- ${FRAMEWORK_NAME}:managed:[^\\n]* (?:start|end) -->$`,
+  "gm",
+);
+
+/** A layer guidance document's text, managed-block markers removed; empty when absent. */
+export function layerGuidanceText(text: string): string {
+  return text
+    .replace(MANAGED_MARKER, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/** `file` (`CLAUDE.md`, `AGENTS.md`) of the layer at `root`, markers removed; empty when absent. */
+export function readLayerGuidanceSync(root: string, file: string): string {
+  try {
+    return layerGuidanceText(fs.readFileSync(path.join(root, file), "utf8"));
+  } catch {
+    return "";
+  }
+}

package/src/runtime/guidance.ts

@@ -1,3 +1,5 @@
+import path from "node:path";
+
 /**
  * Versioned companion guidance contract. The CLI builds the guidance data
  * from its playbooks at launch time and delivers it through the
@@ -16,6 +18,12 @@ export type MateGuidanceFile = {
   companionGuidance: string;
   codebaseExplorationGuidance: string;
   errors: string[];
+  /**
+   * The active audience's layer, for a launch that hosts its own server only.
+   * The plugin applies it only from a payload it trusts; a masked payload
+   * carries none, so the shared service and bare sessions never see one.
+   */
+  audienceLayer?: string;
 };
 
 export type GuidanceValidation = {
@@ -76,12 +84,21 @@ export function validateGuidanceData(value: unknown): GuidanceValidation {
     errors.push("injected codebase exploration guidance is malformed");
   }
 
+  const audienceLayer =
+    typeof value.audienceLayer === "string" && path.isAbsolute(value.audienceLayer)
+      ? value.audienceLayer
+      : undefined;
+  if (value.audienceLayer !== undefined && audienceLayer === undefined) {
+    errors.push("injected audience layer is not an absolute path");
+  }
+
   return {
     guidance: {
       version: GUIDANCE_FILE_VERSION,
       companionGuidance,
       codebaseExplorationGuidance,
       errors,
+      ...(audienceLayer ? { audienceLayer } : {}),
     },
     errors,
   };