@uniqbit/mate-core 0.18.3 → 0.18.5

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;
 }
@@ -101,9 +102,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,12 +173,20 @@ 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,
+): 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;
@@ -199,7 +209,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

@@ -12,14 +12,15 @@ import { readWrapStateSync } from "../../src/runtime/wrap-state";
 
 import { registerCompanionAccess } from "./add-dir";
 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 +40,22 @@ 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);
+    await registerCompanionHooks(api, context, env);
+    await registerCompanion(api, context, env);
     /** 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.5",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "repository": {

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

@@ -73,9 +73,12 @@ type ProjectionResult =
   | { ok: true; repository: string; areas: string[] }
   | { ok: false; reason: string };
 
+/** A leading `---` block; group 1 is its YAML, the match ends after the closing line. */
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
 function parseDeltaScopes(source: string): ScopePair[] {
   const text = source.startsWith(BOM) ? source.slice(BOM.length) : source;
-  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  const match = FRONTMATTER_PATTERN.exec(text);
   if (!match) return [];
 
   try {
@@ -95,6 +98,26 @@ function parseDeltaScopes(source: string): ScopePair[] {
   }
 }
 
+const DELTA_TAGS = new Set(["openspec/change", "openspec/delta"]);
+
+/**
+ * A header an agent copied from a delta: it declares `type: delta-spec`, carries a
+ * `change` key, or a delta tag. A nested `scopes` key alone does not count, since
+ * legacy canonical specs carry one.
+ */
+function isDeltaShapedFrontmatter(yamlSource: string): boolean {
+  try {
+    const parsed = parse(yamlSource) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+    const header = parsed as Record<string, unknown>;
+    if (header.type === "delta-spec" || "change" in header) return true;
+    const tags = Array.isArray(header.tags) ? header.tags : [header.tags];
+    return tags.some((tag) => typeof tag === "string" && DELTA_TAGS.has(tag));
+  } catch {
+    return false;
+  }
+}
+
 function projectDeltaScopes(scopes: ScopePair[]): ProjectionResult {
   if (scopes.length === 0) return { ok: false, reason: "delta declares no scopes entries" };
   const repositories = [...new Set(scopes.map((entry) => entry.repository))];
@@ -133,7 +156,10 @@ async function archivedChangeUsesMateSchema(
   }
 }
 
-/** Scope keys are omitted when the delta had none — a partial block beats no frontmatter. */
+/**
+ * The block through its closing line. Scope keys are omitted when the delta had
+ * none — a partial block beats no frontmatter.
+ */
 function renderCanonicalFrontmatter(
   capability: string,
   scope: { repository: string; areas: string[] } | null,
@@ -146,14 +172,14 @@ function renderCanonicalFrontmatter(
     "tags: [openspec/spec]",
     "---",
     "",
-    "",
   ].join("\n");
 }
 
 /**
  * Repairs `openspec archive` output: prepends canonical frontmatter to main specs the
- * archive run created bare. Publish does not archive, so this runs the first time publish
- * resolves that archive, however the archive was made.
+ * archive run created bare, and replaces a delta-shaped header an agent copied onto one.
+ * Publish does not archive, so this runs the first time publish resolves that archive,
+ * however the archive was made.
  *
  * `openspec archive` rebuilds a brand-new main spec from a skeleton with no frontmatter slot,
  * so scope metadata dies exactly once, at spec birth; existing specs keep theirs because only
@@ -197,8 +223,14 @@ async function reconcileMainSpecFrontmatter(
       const canonicalPath = path.join(companionPath, canonicalRelative);
 
       try {
-        const canonical = await fs.readFile(canonicalPath, "utf8");
-        if (canonical.replace(BOM, "").startsWith("---")) continue;
+        const canonical = (await fs.readFile(canonicalPath, "utf8")).replace(BOM, "");
+        /** The body that follows the written block: the whole file, or what trails a delta-shaped header. */
+        let body = `\n${canonical}`;
+        if (canonical.startsWith("---")) {
+          const header = FRONTMATTER_PATTERN.exec(canonical);
+          if (!header || !isDeltaShapedFrontmatter(header[1])) continue;
+          body = canonical.slice(header[0].length);
+        }
 
         const deltaSource = await fs.readFile(path.join(directory, entry.name), "utf8");
         const scopes = parseDeltaScopes(deltaSource);
@@ -215,7 +247,7 @@ async function reconcileMainSpecFrontmatter(
           capability,
           projected.ok ? { repository: projected.repository, areas: projected.areas } : null,
         );
-        await fs.writeFile(canonicalPath, head + canonical.replace(BOM, ""), "utf8");
+        await fs.writeFile(canonicalPath, head + body, "utf8");
         reconciled.push(canonicalRelative);
       } catch (error) {
         process.stderr.write(

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

@@ -1,9 +1,13 @@
 import { execFileSync } from "node:child_process";
+import fs from "node:fs/promises";
 import path from "node:path";
 
+import { parse as parseYaml } from "yaml";
+
 import { FRAMEWORK_NAME } from "../../framework";
 import { gitEnvironment } from "../../runtime/companion-git";
 import { getActiveDistribution } from "../../distribution";
+import { hasOpenspecCapability } from "../../lib/orchestrator/capabilities";
 import { checkEngineRequirement } from "../../lib/orchestrator/engine-guard";
 import type { GlobalConfigStore } from "../../lib/orchestrator/global-config-store";
 import { pathIsDirectory } from "../../lib/fs-utils";
@@ -73,6 +77,8 @@ export interface DoctorReport {
   /** IDs of the capabilities the verified plugins provide. */
   pluginCapabilities?: string[];
   engineRequirement?: { range: string; ok: boolean; detail: string };
+  /** Present when the companion's `openspec/config.yaml` has `rules` keys OpenSpec ignores. */
+  openspecRuleWarnings?: Array<{ key: string; message: string }>;
   hub?: { members: DoctorHubMember[] };
   resolutionFailures: Array<{ companionPath: string; message: string }>;
 }
@@ -239,6 +245,70 @@ function collectAudiences(
   if (!resolution.ok) report.audienceError = describeUnknownAudience(resolution);
 }
 
+/** Artifact IDs of OpenSpec's built-in `spec-driven` schema. */
+const BUILT_IN_OPENSPEC_ARTIFACTS = ["proposal", "specs", "design", "tasks"];
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Built-in IDs plus every `artifacts[].id` from a `schema.yaml` under the companion's `openspec/schemas/`. */
+async function knownOpenSpecArtifactIds(companionPath: string): Promise<Set<string>> {
+  const schemasDir = path.join(companionPath, "openspec", "schemas");
+  let schemaNames: string[] = [];
+  try {
+    schemaNames = await fs.readdir(schemasDir);
+  } catch {
+    /* no companion schemas */
+  }
+  const schemaIds = await Promise.all(
+    schemaNames.map(async (name) => {
+      try {
+        const schema = asRecord(
+          parseYaml(await fs.readFile(path.join(schemasDir, name, "schema.yaml"), "utf8")),
+        );
+        const artifacts: unknown[] = Array.isArray(schema?.artifacts) ? schema.artifacts : [];
+        return artifacts.flatMap((artifact) => {
+          const id = asRecord(artifact)?.id;
+          return typeof id === "string" ? [id] : [];
+        });
+      } catch {
+        return []; // not a readable schema
+      }
+    }),
+  );
+  return new Set([...BUILT_IN_OPENSPEC_ARTIFACTS, ...schemaIds.flat()]);
+}
+
+/**
+ * OpenSpec ignores a `rules` key that names no artifact, warning only on stderr
+ * of the command that reads it. Read-only; a missing or unparseable config is silent.
+ */
+async function collectOpenSpecRuleWarnings(
+  companionPath: string,
+): Promise<NonNullable<DoctorReport["openspecRuleWarnings"]>> {
+  let rules: Record<string, unknown> | undefined;
+  try {
+    const config = parseYaml(
+      await fs.readFile(path.join(companionPath, "openspec", "config.yaml"), "utf8"),
+    );
+    rules = asRecord(asRecord(config)?.rules);
+  } catch {
+    return [];
+  }
+  if (!rules) return [];
+
+  const known = await knownOpenSpecArtifactIds(companionPath);
+  return Object.keys(rules)
+    .filter((key) => !known.has(key))
+    .map((key) => ({
+      key,
+      message: `rules.${key} matches no OpenSpec artifact and is ignored; put workflow guidance in operations.apply.guidance or operations.archive.guidance`,
+    }));
+}
+
 export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<DoctorReport> {
   const cwd = path.resolve(deps.cwd ?? process.cwd());
   const pathValue = deps.pathValue ?? process.env.PATH ?? "";
@@ -277,6 +347,15 @@ export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<Doctor
     collectAudiences(report, root.config, env);
   }
 
+  if (
+    root.rootPath &&
+    (kind === "working" || kind === "companion") &&
+    hasOpenspecCapability(root.config?.capabilities)
+  ) {
+    const warnings = await collectOpenSpecRuleWarnings(root.rootPath);
+    if (warnings.length > 0) report.openspecRuleWarnings = warnings;
+  }
+
   if (root.rootPath && root.config) {
     const inspect =
       deps.inspectPlugins ?? ((companionPath) => inspectDeclaredPlugins(companionPath, { env }));
@@ -398,6 +477,15 @@ function renderHumanReport(report: DoctorReport): void {
   if (report.engineRequirement) {
     printSection("Version Requirement", report.engineRequirement.detail);
   }
+  if (report.openspecRuleWarnings) {
+    printSection(
+      "OpenSpec Config",
+      renderList(
+        report.openspecRuleWarnings.map((warning) => warning.message),
+        "",
+      ),
+    );
+  }
 
   printSection(
     "Resolution Failures",

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/opencode.ts

@@ -36,6 +36,26 @@ function parseOpenCodeMajor(output: string | undefined): number | undefined {
   return match ? Number(match[1]) : undefined;
 }
 
+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 };
+}
+
 export class OpenCodeAdapter extends LaunchAdapter {
   readonly toolName = "opencode";
   readonly interactive = true;
@@ -67,15 +87,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,11 +102,16 @@ 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: AdapterContext, 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 to every other.
+      [MATE_ENV.guidanceJson]: hostsPrivateServer
+        ? JSON.stringify(this.buildGuidance(context))
+        : "",
     };
   }
 

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

@@ -1,5 +1,7 @@
 import path from "node:path";
 
+import { normalizeBaseAudience } from "../../tools/setup/dynamic-plugins/audiences";
+
 import { FRAMEWORK_NAME } from "../../framework";
 import {
   getDefaultSetupSelections,
@@ -296,8 +298,11 @@ export class ConfigStore extends YamlFileStore<FrameworkConfig> {
     super(path.resolve(configPath));
   }
 
+  /** Either file shape loads as the base set at the root; the next save writes the root shape. */
   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);