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

package/src/tools/setup/capabilities/react-doctor.ts

@@ -1,88 +1,72 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { getReactDoctorBinPath } from "../../../lib/package-paths";
 import type { CapabilityPlugin, RuntimeContributionsByRuntime, SetupContext } from "../plugin";
-import { removeLegacyOpenCodeSkills } from "../providers/agents-skill-root";
+import { removeLegacyOpenCodeSkills, removeSharedSkills } from "../providers/agents-skill-root";
 import { pruneEmptyAncestors } from "../utils";
 
-const SKILL_NAME = "react-doctor";
+const SKILL_NAME = "mate-react-doctor";
+// The upstream skill earlier releases installed under its own name.
+const LEGACY_SKILL_NAME = "react-doctor";
 
 const SKILL_SRC = path.join(
   import.meta.dirname,
-  "../../../templates/capabilities/react-doctor/skill",
-);
-export const CLAUDE_HOOK_SRC = path.join(
-  import.meta.dirname,
-  "../../../templates/capabilities/react-doctor/claude/hooks/react-doctor.sh",
+  "../../../templates/capabilities/react-doctor/mate-react-doctor",
 );
 
+/** Removes the skill copies earlier releases installed under the upstream name. */
+async function removeLegacySkills(companionPath: string): Promise<void> {
+  const claudeSkillsDir = path.join(companionPath, ".claude", "skills");
+  await fs.rm(path.join(claudeSkillsDir, LEGACY_SKILL_NAME), { recursive: true, force: true });
+  await pruneEmptyAncestors(claudeSkillsDir, companionPath);
+  await removeSharedSkills(companionPath, [LEGACY_SKILL_NAME]);
+  await removeLegacyOpenCodeSkills(companionPath, [LEGACY_SKILL_NAME]);
+}
+
+/** Removes the post-edit hook script earlier releases copied into the companion. */
+async function removeLegacyHookScript(companionPath: string): Promise<void> {
+  const hooksDir = path.join(companionPath, ".claude", "hooks");
+  await fs.rm(path.join(hooksDir, "react-doctor.sh"), { force: true });
+  await pruneEmptyAncestors(hooksDir, companionPath);
+}
+
 export function createReactDoctorPlugin(): CapabilityPlugin {
   return {
     id: "react-doctor",
     kind: "capability",
     label: "React Doctor",
-    description: "Install React Doctor skills and Claude post-edit scans.",
+    description: "Install the mate-react-doctor skill that verifies React changes during apply.",
     defaultSelected: true,
     isEnabled: (config) => (config.capabilities ?? []).some((c) => c.name === "react-doctor"),
-    // Skills, session hooks, and permission pre-seeds are declared and
-    // reconciled by each runtime's Runtime Surface. Only the hook script file
-    // itself is copied imperatively below (script files are not a config
-    // format the surface owns).
-    getRuntimeContributions(ctx: SetupContext): RuntimeContributionsByRuntime {
-      const hookCommand = `sh "${ctx.companionPath}/.claude/hooks/react-doctor.sh"`;
+    // React Doctor runs only when an agent invokes the skill (the shared Mate
+    // verification rule adds it to OpenSpec task lists), so the capability
+    // contributes no hooks: just the skill and its permission pre-seeds.
+    getRuntimeContributions(): RuntimeContributionsByRuntime {
       const skillTrees = [{ name: SKILL_NAME, sourceDir: SKILL_SRC }];
       return {
         claude: {
-          hookGroups: [
-            // Record edits cheaply, then scan once when the edited turn finishes.
-            {
-              event: "PostToolUse",
-              marker: "react-doctor.sh",
-              group: {
-                matcher: "Write|Edit|MultiEdit|NotebookEdit|ApplyPatch",
-                hooks: [{ type: "command", command: hookCommand, timeout: 5 }],
-              },
-            },
-            {
-              event: "Stop",
-              marker: "react-doctor.sh",
-              group: { hooks: [{ type: "command", command: hookCommand, timeout: 45 }] },
-            },
-          ],
-          permissionEntries: [
-            "Skill(react-doctor)",
-            "Bash(npx react-doctor:*)",
-            "Bash(npx react-doctor@latest *)",
-          ],
+          permissionEntries: [`Skill(${SKILL_NAME})`, `Bash(${getReactDoctorBinPath()}:*)`],
           skillTrees,
         },
         opencode: { skillTrees },
       };
     },
     async apply(ctx: SetupContext) {
-      await removeLegacyOpenCodeSkills(ctx.companionPath, [SKILL_NAME]);
+      await removeLegacySkills(ctx.companionPath);
     },
     async teardown(ctx: SetupContext) {
-      await removeLegacyOpenCodeSkills(ctx.companionPath, [SKILL_NAME]);
+      await removeLegacySkills(ctx.companionPath);
     },
+    // Cleanup only: stale hook groups are stripped by settings-sync through the
+    // `react-doctor.sh` managed marker; the script file itself is removed here.
     forProvider: {
       claude: {
         async apply(ctx: SetupContext) {
-          const hookDest = path.join(ctx.companionPath, ".claude", "hooks", "react-doctor.sh");
-          await fs.mkdir(path.dirname(hookDest), { recursive: true });
-          await fs.copyFile(CLAUDE_HOOK_SRC, hookDest);
-          await fs.chmod(hookDest, 0o755);
+          await removeLegacyHookScript(ctx.companionPath);
         },
         async teardown(ctx: SetupContext) {
-          try {
-            await fs.unlink(path.join(ctx.companionPath, ".claude", "hooks", "react-doctor.sh"));
-          } catch {
-            /* not present */
-          }
-          await pruneEmptyAncestors(
-            path.join(ctx.companionPath, ".claude", "hooks"),
-            ctx.companionPath,
-          );
+          await removeLegacyHookScript(ctx.companionPath);
         },
       },
     },

package/src/tools/setup/capabilities/tokensave.ts

@@ -14,6 +14,8 @@ export { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "./tokensave-shared";
 export const TOKENSAVE_SUPPORTED_AGENTS = new Set(["claude", "opencode"]);
 export const TOKENSAVE_STORE_DIR = ".tokensave";
 export const TOKENSAVE_STORE_CONFIG_FILE = "config.json";
+/** The index itself: `tokensave sync` refuses a store without it. */
+const TOKENSAVE_STORE_DATABASE_FILE = "tokensave.db";
 export const TOKENSAVE_MIN_RUST_VERSION = "1.91.0";
 /** Single-graph posture Mate owns in the per-project store config; every other key is left as found. */
 const TOKENSAVE_OWNED_POSTURE = { auto_track: false, suppress_scope_warning: true } as const;
@@ -357,6 +359,15 @@ async function deactivateTokensaveBranchMetadata(repoPath: string): Promise<void
   }
 }
 
+/**
+ * Whether the working repo holds a TokenSave index `tokensave sync` accepts.
+ * The database, not the store folder: an empty or half-initialized
+ * `.tokensave/` must still get `tokensave init`, or every pass fails on sync.
+ */
+export async function isTokensaveIndexed(repoPath: string): Promise<boolean> {
+  return fileExists(path.join(repoPath, TOKENSAVE_STORE_DIR, TOKENSAVE_STORE_DATABASE_FILE));
+}
+
 /**
  * Reconciles Mate's single-graph branching posture into the working repo's
  * git-excluded `.tokensave/config.json` and deactivates existing branch

package/src/tools/setup/contribution-ledger.ts

@@ -0,0 +1,207 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { writeAtomic } from "../../runtime/write-atomic";
+import { instructionBlockKey } from "./context-services";
+import type { CapabilityContributionInput, RuntimeContributions } from "./plugin";
+
+/**
+ * Contribution Ledger: which plugin owns each contribution a persisted pass
+ * applied to the companion, per Agent Runtime. Committed with the companion,
+ * because it describes committed files: a clone that never loaded a plugin
+ * must still be able to remove what another clone committed. It records
+ * identities only (names, block keys, markers, entries), never a value, so it
+ * carries no secret.
+ */
+
+export const CONTRIBUTION_LEDGER_VERSION = 1;
+
+/** The identities one owner applied on one runtime. Absent kinds are none. */
+export interface LedgerIdentities {
+  mcpServers?: string[];
+  guidanceKeys?: string[];
+  skillTrees?: string[];
+  agentDefinitions?: string[];
+  hookMarkers?: string[];
+  permissionEntries?: string[];
+  pluginReferences?: string[];
+}
+
+export interface ContributionLedger {
+  version: number;
+  /** Runtime id → owning plugin id → identities. */
+  runtimes: Record<string, Record<string, LedgerIdentities>>;
+  /** Audience plugin packages the upgrade sweep could not load; retried by every pass. */
+  unswept?: string[];
+}
+
+export function contributionLedgerPath(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "contribution-ledger.json");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+
+const IDENTITY_KINDS = [
+  "agentDefinitions",
+  "guidanceKeys",
+  "hookMarkers",
+  "mcpServers",
+  "permissionEntries",
+  "pluginReferences",
+  "skillTrees",
+] as const satisfies readonly (keyof LedgerIdentities)[];
+
+function sortedUnique(values: Iterable<string>): string[] {
+  return [...new Set(values)].toSorted();
+}
+
+/** Sorted kinds and values, empty kinds dropped; `null` when nothing is left. */
+function normalizeIdentities(identities: LedgerIdentities): LedgerIdentities | null {
+  const normalized: LedgerIdentities = {};
+  for (const kind of IDENTITY_KINDS) {
+    const values = sortedUnique(identities[kind] ?? []);
+    if (values.length > 0) normalized[kind] = values;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : null;
+}
+
+/** Sorted runtimes and owners; empty owners and runtimes dropped. */
+function normalizeLedger(ledger: ContributionLedger): ContributionLedger {
+  const runtimes: ContributionLedger["runtimes"] = {};
+  for (const runtimeId of Object.keys(ledger.runtimes).toSorted()) {
+    const owners: Record<string, LedgerIdentities> = {};
+    for (const owner of Object.keys(ledger.runtimes[runtimeId] ?? {}).toSorted()) {
+      const identities = normalizeIdentities(ledger.runtimes[runtimeId]![owner]!);
+      if (identities) owners[owner] = identities;
+    }
+    if (Object.keys(owners).length > 0) runtimes[runtimeId] = owners;
+  }
+  const unswept = sortedUnique(ledger.unswept ?? []);
+  return {
+    version: CONTRIBUTION_LEDGER_VERSION,
+    runtimes,
+    ...(unswept.length > 0 ? { unswept } : {}),
+  };
+}
+
+/** The companion's ledger; `null` when absent or unreadable, which a pass treats as never recorded. */
+export async function readContributionLedger(
+  companionPath: string,
+): Promise<ContributionLedger | null> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await fs.readFile(contributionLedgerPath(companionPath), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed.runtimes)) return null;
+  const runtimes: ContributionLedger["runtimes"] = {};
+  for (const [runtimeId, owners] of Object.entries(parsed.runtimes)) {
+    if (!isRecord(owners)) continue;
+    runtimes[runtimeId] = {};
+    for (const [owner, identities] of Object.entries(owners)) {
+      if (!isRecord(identities)) continue;
+      const read: LedgerIdentities = {};
+      for (const kind of IDENTITY_KINDS) read[kind] = stringList(identities[kind]);
+      runtimes[runtimeId][owner] = read;
+    }
+  }
+  return normalizeLedger({
+    version: CONTRIBUTION_LEDGER_VERSION,
+    runtimes,
+    unswept: stringList(parsed.unswept),
+  });
+}
+
+/** Writes the ledger in its stable form; an unchanged ledger leaves the file untouched. */
+export async function writeContributionLedger(
+  companionPath: string,
+  ledger: ContributionLedger,
+): Promise<void> {
+  const target = contributionLedgerPath(companionPath);
+  const text = `${JSON.stringify(normalizeLedger(ledger), null, 2)}\n`;
+  const existing = await fs.readFile(target, "utf8").catch(() => null);
+  if (existing === text) return;
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await writeAtomic(target, text);
+}
+
+/** The identities a contribution set applies for `pluginId`. */
+export function identitiesOf(
+  pluginId: string,
+  contributions: RuntimeContributions,
+): LedgerIdentities {
+  return {
+    mcpServers: (contributions.mcpServers ?? []).map((server) => server.name),
+    guidanceKeys: (contributions.guidanceSections ?? []).map((section) =>
+      instructionBlockKey(pluginId, section.content),
+    ),
+    skillTrees: (contributions.skillTrees ?? []).map((tree) => tree.name),
+    agentDefinitions: (contributions.agentDefinitions ?? []).map((agent) => agent.name),
+    hookMarkers: (contributions.hookGroups ?? []).map((hook) => hook.marker),
+    permissionEntries: [...(contributions.permissionEntries ?? [])],
+    pluginReferences: (contributions.pluginReferences ?? []).map((entry) => entry.reference),
+  };
+}
+
+/** The ledger a pass leaves: what its enabled inputs applied, per runtime and owner. */
+export function ledgerFromInputs(
+  inputsByRuntime: ReadonlyMap<string, readonly CapabilityContributionInput[]>,
+  unswept: readonly string[] = [],
+): ContributionLedger {
+  const runtimes: ContributionLedger["runtimes"] = {};
+  for (const [runtimeId, inputs] of inputsByRuntime) {
+    const owners: Record<string, LedgerIdentities> = {};
+    for (const input of inputs) {
+      if (!input.enabled) continue;
+      const identities = identitiesOf(input.pluginId, input.contributions);
+      const merged = owners[input.pluginId] ?? {};
+      for (const kind of IDENTITY_KINDS) {
+        merged[kind] = [...(merged[kind] ?? []), ...(identities[kind] ?? [])];
+      }
+      owners[input.pluginId] = merged;
+    }
+    runtimes[runtimeId] = owners;
+  }
+  return normalizeLedger({ version: CONTRIBUTION_LEDGER_VERSION, runtimes, unswept: [...unswept] });
+}
+
+/**
+ * A disabled input naming every recorded identity of `owner`, so each Runtime
+ * Surface removes them through its existing disabled-input path. Removal keys
+ * on identity only, so no value is needed: guidance is stripped by owner, a
+ * hook group by its marker, a plugin reference by its exact entry.
+ */
+export function ledgerTeardownInput(
+  owner: string,
+  identities: LedgerIdentities,
+): CapabilityContributionInput {
+  return {
+    pluginId: owner,
+    enabled: false,
+    capabilityEnabled: false,
+    contributions: {
+      mcpServers: (identities.mcpServers ?? []).map((name) => ({ name })),
+      guidanceSections: (identities.guidanceKeys ?? []).length > 0 ? [{ content: "" }] : [],
+      skillTrees: (identities.skillTrees ?? []).map((name) => ({ name, sourceDir: "" })),
+      agentDefinitions: (identities.agentDefinitions ?? []).map((name) => ({ name, content: "" })),
+      hookGroups: (identities.hookMarkers ?? []).map((marker) => ({
+        event: "",
+        marker,
+        group: {},
+      })),
+      permissionEntries: [...(identities.permissionEntries ?? [])],
+      pluginReferences: (identities.pluginReferences ?? []).map((reference) => ({
+        reference,
+        isManagedReference: (entry: unknown) => entry === reference,
+      })),
+    },
+  };
+}

package/src/tools/setup/dynamic-plugins/audiences.ts

@@ -4,10 +4,16 @@ import path from "node:path";
 import { parse } from "yaml";
 
 import { FRAMEWORK_NAME } from "../../../framework";
-import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { ConfigError, type PluginDeclaration } from "../../../lib/orchestrator/types";
 
 export const AUDIENCE_ENV = "MATE_AUDIENCE";
 
+/** The reserved audience holding the base set: always applied, never selected or listed. */
+export const BASE_AUDIENCE = "base";
+
+/** The base set's audience-scoped keys; companion-wide keys stay at the root. */
+export const BASE_AUDIENCE_KEYS = ["capabilities", "plugins", "studio"] as const;
+
 export type AudienceResolution =
   | { ok: true; active: string | null }
   | { ok: false; requested: string; declared: string[] };
@@ -17,11 +23,19 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function pluginList(value: unknown): unknown[] {
+  if (
+    isRecord(value) &&
+    isRecord(value.audiences) &&
+    Object.hasOwn(value.audiences, BASE_AUDIENCE)
+  ) {
+    return pluginList(normalizeBaseAudience(value));
+  }
   return isRecord(value) && Array.isArray(value.plugins) ? value.plugins : [];
 }
 
 function audienceEntry(raw: unknown, audience: string | null): unknown {
-  if (audience === null || !isRecord(raw) || !isRecord(raw.audiences)) return undefined;
+  if (audience === null || audience === BASE_AUDIENCE) return undefined;
+  if (!isRecord(raw) || !isRecord(raw.audiences)) return undefined;
   return Object.hasOwn(raw.audiences, audience) ? raw.audiences[audience] : undefined;
 }
 
@@ -32,6 +46,38 @@ function studioAgent(value: unknown): unknown {
   return value.studio.terminal.agent;
 }
 
+/**
+ * The base set at the root, whichever shape the file uses: `audiences.base`
+ * keys are lifted to the root and `base` leaves `audiences`. A file in the
+ * root shape is returned as it is. Throws when a key is declared in both
+ * places, or `audiences.base` holds a key the base set does not have.
+ */
+export function normalizeBaseAudience<T>(raw: T): T {
+  if (!isRecord(raw) || !isRecord(raw.audiences) || !Object.hasOwn(raw.audiences, BASE_AUDIENCE)) {
+    return raw;
+  }
+  const { [BASE_AUDIENCE]: baseEntry, ...others } = raw.audiences;
+  const lifted: Record<string, unknown> = { ...raw };
+  if (isRecord(baseEntry)) {
+    for (const [key, value] of Object.entries(baseEntry)) {
+      if (!(BASE_AUDIENCE_KEYS as readonly string[]).includes(key)) {
+        throw new ConfigError(
+          `audiences.${BASE_AUDIENCE} may contain only ${BASE_AUDIENCE_KEYS.join(", ")}; "${key}" belongs at the root of framework.yaml.`,
+        );
+      }
+      if (Object.hasOwn(raw, key)) {
+        throw new ConfigError(
+          `"${key}" is declared both at the root of framework.yaml and under audiences.${BASE_AUDIENCE}; keep one.`,
+        );
+      }
+      lifted[key] = value;
+    }
+  }
+  if (Object.keys(others).length > 0) lifted.audiences = others;
+  else delete lifted.audiences;
+  return lifted as T;
+}
+
 /** `MATE_AUDIENCE` from the environment; unset, empty or blank means none. */
 export function readAudienceSelection(env: Record<string, string | undefined>): string | null {
   const value = env[AUDIENCE_ENV]?.trim();
@@ -40,11 +86,14 @@ export function readAudienceSelection(env: Record<string, string | undefined>):
 
 /** Audience names declared by raw parsed `framework.yaml`, in declared order. */
 export function declaredAudiences(raw: unknown): string[] {
-  return isRecord(raw) && isRecord(raw.audiences) ? Object.keys(raw.audiences) : [];
+  return isRecord(raw) && isRecord(raw.audiences)
+    ? Object.keys(raw.audiences).filter((name) => name !== BASE_AUDIENCE)
+    : [];
 }
 
+/** `MATE_AUDIENCE=base` selects the base set alone, the same as no audience. */
 export function resolveAudience(raw: unknown, audience: string | null): AudienceResolution {
-  if (audience === null) return { ok: true, active: null };
+  if (audience === null || audience === BASE_AUDIENCE) return { ok: true, active: null };
   const declared = declaredAudiences(raw);
   if (declared.includes(audience)) return { ok: true, active: audience };
   return { ok: false, requested: audience, declared };
@@ -58,6 +107,33 @@ export function effectivePluginDeclarations(raw: unknown, audience: string | nul
   return [...pluginList(raw), ...pluginList(audienceEntry(raw, audience))];
 }
 
+/** One effective declaration and its source: `null` for base, else the audience name. */
+export interface SourcedDeclaration {
+  entry: unknown;
+  audience: string | null;
+}
+
+/** `effectivePluginDeclarations`, each entry marked with the source that declared it. */
+export function effectivePluginDeclarationSources(
+  raw: unknown,
+  audience: string | null,
+): SourcedDeclaration[] {
+  return [
+    ...pluginList(raw).map((entry) => ({ entry, audience: null })),
+    ...pluginList(audienceEntry(raw, audience)).map((entry) => ({ entry, audience })),
+  ];
+}
+
+/** The declarations of one audience only, without base. */
+export function audiencePluginDeclarations(raw: unknown, audience: string): unknown[] {
+  return pluginList(audienceEntry(raw, audience));
+}
+
+/** The raw `audiences.<name>` entry, for fingerprinting what a layer depends on. */
+export function audienceDeclarationEntry(raw: unknown, audience: string): unknown {
+  return audienceEntry(raw, audience);
+}
+
 /**
  * Base plugins followed by every audience's, for installation only: a
  * package shared by audiences appears once since validation guarantees one
@@ -96,24 +172,28 @@ export function installPluginDeclarations(config: unknown): PluginDeclaration[]
  * as found: the caller owns rejecting a value that is not a safe name.
  */
 export function effectiveStudioAgent(raw: unknown, audience: string | null): unknown {
-  return studioAgent(audienceEntry(raw, audience)) ?? studioAgent(raw);
+  return studioAgent(audienceEntry(raw, audience)) ?? studioAgent(normalizeBaseAudience(raw));
 }
 
 /**
- * Raw read of the companion's `framework.yaml`. Deliberately avoids
- * `ConfigStore.load()` — hydration runs on every invocation and must never
- * create or migrate config files as a side effect.
+ * Raw read of the companion's `framework.yaml`, the base set at the root
+ * whichever shape the file uses. Deliberately avoids `ConfigStore.load()` —
+ * hydration runs on every invocation and must never create or migrate config
+ * files as a side effect.
  */
 export async function readFrameworkRaw(companionPath: string): Promise<unknown> {
+  let raw: unknown;
   try {
     const text = await fs.readFile(
       path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
       "utf8",
     );
-    return (parse(text) as unknown) ?? null;
+    raw = (parse(text) as unknown) ?? null;
   } catch {
     return null;
   }
+  /** Outside the catch: a base key in both places is the operator's to fix, never silently base-less. */
+  return normalizeBaseAudience(raw);
 }
 
 export async function readEffectiveDeclarations(

package/src/tools/setup/dynamic-plugins/declarations.ts

@@ -6,13 +6,14 @@ import { parse } from "yaml";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import { normalizeBaseAudience } from "./audiences";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 /**
- * Raw read of the companion's `plugins:` list. Deliberately avoids
+ * Raw read of the companion's base `plugins:` list, from either shape. Deliberately avoids
  * `ConfigStore.load()` — hydration runs on every invocation and must never
  * create or migrate config files as a side effect.
  */
@@ -22,7 +23,7 @@ export async function readDeclarations(companionPath: string): Promise<unknown[]
       path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
       "utf8",
     );
-    const parsed = parse(raw) as unknown;
+    const parsed = normalizeBaseAudience(parse(raw) as unknown);
     if (!isRecord(parsed) || !Array.isArray(parsed.plugins)) return [];
     return parsed.plugins;
   } catch {

package/src/tools/setup/dynamic-plugins/hydrate.ts

@@ -3,13 +3,13 @@ import path from "node:path";
 
 import { getActiveDistribution } from "../../../distribution";
 import { FRAMEWORK_NAME } from "../../../framework";
-import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
+import { CompanionResolver } from "../../../lib/orchestrator/repository-link";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";
 import {
   describeUnknownAudience,
-  effectivePluginDeclarations,
+  effectivePluginDeclarationSources,
   readAudienceSelection,
   readFrameworkRaw,
   resolveAudience,
@@ -71,7 +71,8 @@ function activateDeclaredPlugin(plugin: Plugin): Plugin {
 /**
  * Registers the companion's effective plugins (base plus the active
  * `MATE_AUDIENCE`) into the active registry — compiled-in plugins first
- * (they are already registered), declared order after. Runs before cap-command detection on every invocation. No-op
+ * (they are already registered), declared order after. Each registration is
+ * marked with its source, so persisted passes can keep to base. Runs before cap-command detection on every invocation. No-op
  * without a companion or `plugins:` entries; all diagnostics go to stderr;
  * never throws.
  */
@@ -89,12 +90,12 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
     if (!audience.ok) {
       warn(`${describeUnknownAudience(audience)}; applying the base configuration only`);
     }
-    const entries = effectivePluginDeclarations(raw, audience.ok ? audience.active : null);
+    const entries = effectivePluginDeclarationSources(raw, audience.ok ? audience.active : null);
     if (entries.length === 0) return;
 
     const registry = deps.registry ?? getActiveDistribution().registry;
 
-    for (const entry of entries) {
+    for (const { entry, audience: source } of entries) {
       const { declaration, error } = validateDeclaration(entry);
       if (!declaration) {
         if (error) warn(error);
@@ -122,6 +123,8 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
       registry.register({
         plugin: activateDeclaredPlugin(result.plugin),
         policy: declaration.policy ?? "optional",
+        audience: source,
+        packageName: declaration.package,
       });
       hydratedPackages.add(declaration.package);
     }