@uniqbit/mate-core 0.18.3-canary.1 → 0.18.4

package/claude-plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Mate hooks — PreToolUse artifact-path guardrail, SessionStart banner and companion guidance",
+  "description": "Mate hooks \u2014 PreToolUse artifact-path guardrail, SessionStart banner, companion guidance and session prepare",
   "hooks": {
     "PreToolUse": [
       {
@@ -28,6 +28,15 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-guidance.mjs\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-prepare.mjs\"",
+            "timeout": 45
+          }
+        ]
       }
     ]
   }

package/claude-plugin/hooks/session-banner.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// Thin shim: hook logic lives in src/hooks/session-banner.ts, loaded through
-// ts-loader.mjs because the installed plugin sits inside node_modules where
-// node's native type stripping is disabled.
+/**
+ * Thin shim for src/hooks/session-banner.ts, loaded through ts-loader.mjs: the installed
+ * plugin sits inside node_modules, where node's native type stripping is off.
+ */
 import "./ts-loader.mjs";
 
 const { run } = await import("../../src/hooks/session-banner.ts");

package/claude-plugin/hooks/session-prepare.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Thin shim for src/hooks/session-prepare.ts, loaded through ts-loader.mjs: the installed
+ * plugin sits inside node_modules, where node's native type stripping is off.
+ */
+import "./ts-loader.mjs";
+
+const { run } = await import("../../src/hooks/session-prepare.ts");
+process.exitCode = await run();

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

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 
 import type { Context } from "@opencode/plugin/promise/plugin";
@@ -5,15 +6,38 @@ 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,
+  runtimeMateBin,
+  runtimeWrapperBinPath,
+} from "../../src/runtime/runtime-directory";
 
 function prependPathEntry(pathValue: string | undefined, entry: string): string {
   const entries = (pathValue ?? "").split(path.delimiter).filter(Boolean);
   return [entry, ...entries.filter((value) => value !== entry)].join(path.delimiter);
 }
 
-function resolveWrapperBinPath(): string {
-  return process.env.MATE_WRAPPER_BIN_PATH ?? "$MATE_WRAPPER_BIN_PATH";
+/**
+ * The launch environment first, then the runtime directory every `mate` run
+ * keeps current. `null` when neither exists: guidance naming an unresolved
+ * placeholder would send the model to a path that is not there.
+ */
+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;
+}
+
+/** The runtime-directory launcher for the Mate CLI; `null` until a `mate` run wrote it. */
+export function resolveMateBin(): string | null {
+  const launcher = runtimeMateBin();
+  return fs.existsSync(launcher) ? launcher : null;
+}
+
+export function missingRuntimeDirectoryMessage(): string {
+  return `Mate runtime directory ${runtimeDirectoryPath()} is missing; run \`mate\` once to repair it.`;
 }
 
 function buildStartupError(details: string[]): Error {
@@ -31,14 +55,17 @@ 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;
 }
 
-function materializeCompanionGuidance(guidance: string, context: CompanionContext): string {
-  const wrapperBinPath = resolveWrapperBinPath();
+function materializeCompanionGuidance(
+  guidance: string,
+  context: CompanionContext,
+  wrapperBinPath: string,
+): string {
   return guidance
     .replaceAll("$MATE_REPO_PATH", context.repositoryPath)
     .replaceAll("$MATE_ARTIFACT_PATH", context.companionPath)
@@ -46,8 +73,13 @@ function materializeCompanionGuidance(guidance: string, context: CompanionContex
     .replaceAll("$MATE_REPO_ID", context.repositoryId);
 }
 
-function buildSystemPrompt(context: CompanionContext, guidance: MateGuidanceFile): string[] {
-  const lines = [materializeCompanionGuidance(guidance.companionGuidance, context)];
+function buildSystemPrompt(
+  context: CompanionContext,
+  guidance: MateGuidanceFile,
+  wrapperBinPath: string,
+  layerGuidance: string,
+): string[] {
+  const lines = [materializeCompanionGuidance(guidance.companionGuidance, context, wrapperBinPath)];
 
   if (guidance.codebaseExplorationGuidance.trim()) {
     lines.push("", guidance.codebaseExplorationGuidance);
@@ -57,6 +89,11 @@ function buildSystemPrompt(context: CompanionContext, guidance: MateGuidanceFile
     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;
 }
 
@@ -70,10 +107,11 @@ function readSystemText(part: unknown): string {
 function applyCompanionShellEnv(
   context: CompanionContext,
   env: Record<string, string | undefined>,
+  wrapperBinPath: string,
+  launchEnv: LaunchEnvironment,
 ): void {
-  const wrapperBinPath = resolveWrapperBinPath();
   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) {
@@ -95,8 +133,7 @@ function applyCompanionShellEnv(
   env.PATH = prependPathEntry(process.env.PATH, wrapperBinPath);
 }
 
-function companionPathsResult(context: CompanionContext) {
-  const wrapperBinPath = resolveWrapperBinPath();
+function companionPathsResult(context: CompanionContext, wrapperBinPath: string) {
   return {
     content: JSON.stringify(
       {
@@ -142,12 +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(env);
+  if (!wrapperBinPath) {
+    console.error(`mate: ${missingRuntimeDirectoryMessage()}`);
+    return;
+  }
 
-  const companion = buildSystemPrompt(context, guidance).join("\n");
+  const companion = buildSystemPrompt(context, guidance, wrapperBinPath, layerGuidance).join("\n");
 
   await api.session.hook("context", (event) => {
     const merged = mergeCompanionSystem(event.system, companion);
@@ -164,7 +216,7 @@ export async function registerCompanion(api: Context, context: CompanionContext)
   });
 
   await api.shell.hook("create.before", (event) => {
-    applyCompanionShellEnv(context, event.env);
+    applyCompanionShellEnv(context, event.env, wrapperBinPath, env);
   });
 
   await api.tool.transform((editor) => {
@@ -173,7 +225,7 @@ export async function registerCompanion(api: Context, context: CompanionContext)
       description: `Return active ${context.frameworkName} companion framework and working repository paths.`,
       input: { type: "object", properties: {}, additionalProperties: false },
       async execute() {
-        return companionPathsResult(context);
+        return companionPathsResult(context, wrapperBinPath);
       },
     });
   });

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

@@ -1,25 +1,77 @@
 import { Plugin } from "@opencode/plugin";
-import { registerCompanionHooks } from "../../src/opencode/companion-hooks";
+import type { Context } from "@opencode/plugin/promise/plugin";
+import {
+  registerCompanionHooks,
+  repositoryWrappedForOpenCode,
+} from "../../src/opencode/companion-hooks";
 import { readContext } from "../../src/opencode/companion-policy";
+import { registerSessionPrepare } from "../../src/opencode/session-prepare";
+import { hasLaunchEnvironment } from "../../src/runtime/env";
+import { spawnPrepareRunner } from "../../src/runtime/session-prepare-runner";
+import { readWrapStateSync } from "../../src/runtime/wrap-state";
 
 import { registerCompanionAccess } from "./add-dir";
-import { registerCompanion } from "./companion";
+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, env: LaunchEnvironment) {
+  if (hasLaunchEnvironment(env)) return undefined;
+  const repoRoot = repositoryWrappedForOpenCode(api.location.directory);
+  if (!repoRoot) return undefined;
+  const mateBin = resolveMateBin();
+  if (!mateBin) {
+    console.error(`mate: ${missingRuntimeDirectoryMessage()}`);
+    return undefined;
+  }
+  return registerSessionPrepare(api, {
+    directory: api.location.directory,
+    repoPath: repoRoot,
+    companionPath,
+    mateServers: readWrapStateSync(repoRoot).openCodeMcpServers,
+    run: spawnPrepareRunner(mateBin, repoRoot),
+  });
+}
 
 /**
  * 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);
-    const cleanup = await registerCompanionHooks(api, context);
-    await registerCompanion(api, context);
-    return cleanup;
+    /**
+     * 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, env);
+    return async () => {
+      await prepareCleanup?.();
+    };
   },
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.18.3-canary.1",
+  "version": "0.18.4",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {
@@ -35,8 +35,8 @@
     "typecheck": "bunx tsc --noEmit -p ../../tsconfig.json",
     "lint": "oxlint src/ opencode-plugin/",
     "lint:fix": "oxlint src/ opencode-plugin/ --fix",
-    "format": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" \"!**/report-assets/**\"",
-    "format:check": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" \"!**/report-assets/**\" --check"
+    "format": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\"",
+    "format:check": "oxfmt src/ opencode-plugin/ \"!**/*.generated.*\" --check"
   },
   "dependencies": {
     "@opencode/plugin": "^2.0.23",

package/src/cli/commands/artifact/finish/openspec.ts

@@ -356,7 +356,7 @@ export async function resolveDriftedSpecs(
       message: `mate: not a canonical spec: ${outside.join(", ")}. Only specs under ${SPECS_RELATIVE_DIR}/ are spec publication targets.`,
     };
   }
-  const driftedPaths = new Set(drifted);
+  const driftedPaths = new Set(drifted.map(withoutTrailingSlash));
   const notDrifted = normalized.filter((candidate) => !driftedPaths.has(candidate));
   if (notDrifted.length > 0) {
     return {