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

package/src/tools/setup/engine.ts

@@ -1,9 +1,16 @@
 // oxlint-disable no-await-in-loop
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
-import type { RenderedRuntimeDocument } from "../../lib/orchestrator/projection-types";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import type { RenderedRuntimeDocument } from "../../runtime/runtime-document-manifest";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
+import {
+  ledgerFromInputs,
+  ledgerTeardownInput,
+  readContributionLedger,
+  writeContributionLedger,
+  type ContributionLedger,
+} from "./contribution-ledger";
 import type {
   CapabilityContributionInput,
   CapabilityPlugin,
@@ -13,8 +20,10 @@ import type {
 } from "./plugin";
 import { reconcileClaudeContributions } from "./providers/claude";
 import { reconcileOpenCodeContributions } from "./providers/opencode";
-import { renderDocumentsForTarget } from "./runtime-documents";
+import { mergeCompanionOpenCodeConfig, renderDocumentsForTarget } from "./runtime-documents";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
+import { surfaceRoot } from "./surface-target";
+import { removeForeignGuidanceBlocks, sweepAudienceDeclarations } from "./upgrade-sweep";
 
 export interface SetupInstallationPlanAction {
   phase: Plugin["kind"];
@@ -35,11 +44,23 @@ export interface SetupInstallationOutcome {
   warnings: string[];
 }
 
+/**
+ * The registrations a pass that writes a persisted surface may reconcile:
+ * base only. An audience registration takes part in no such pass — neither
+ * its lifecycle hooks nor its declared contributions — whatever audience is
+ * active; its contributions reach sessions only through the launch layer.
+ */
+export function persistedRegistrations(
+  registrations: PluginRegistration[],
+): NormalizedRegistration[] {
+  return registrations.map(normalizeRegistration).filter((entry) => entry.audience === null);
+}
+
 export function buildSetupInstallationPlan(
   config: FrameworkConfig,
   registrations: PluginRegistration[],
 ): SetupInstallationPlan {
-  const entries = registrations.map(normalizeRegistration);
+  const entries = persistedRegistrations(registrations);
   // Required plugins are always treated as enabled: saved selections cannot
   // deselect them and deselection never produces a teardown action.
   const isEntryEnabled = (entry: NormalizedRegistration) =>
@@ -109,7 +130,7 @@ export async function executeSetupInstallationPlan(
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
 ): Promise<SetupInstallationOutcome> {
-  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
+  const plugins = persistedRegistrations(registrations).map((entry) => entry.plugin);
   const pluginById = new Map(plugins.map((plugin) => [plugin.id, plugin]));
   const executedActions: SetupInstallationPlanAction[] = [];
   const skippedActions: SetupInstallationPlanAction[] = [];
@@ -176,13 +197,22 @@ export async function executeSetupInstallationPlan(
 
   await mediator.finalize();
 
-  await reconcileCapabilityContributions(ctx, plugins, plan);
+  const reconcileWarnings = await reconcileCapabilityContributions(
+    ctx,
+    plugins,
+    plan,
+    registrations.map(normalizeRegistration),
+  );
+  for (const warning of reconcileWarnings) {
+    warnings.push(warning);
+    process.stderr.write(`${warning}\n`);
+  }
 
   return { executedActions, skippedActions, warnings };
 }
 
 // The Runtime Surface of each active Agent Runtime, by runtime id.
-const RUNTIME_SURFACE_RECONCILERS: Record<
+export const RUNTIME_SURFACE_RECONCILERS: Record<
   string,
   (ctx: SetupContext, inputs: CapabilityContributionInput[]) => Promise<void>
 > = {
@@ -243,13 +273,110 @@ async function reconcileCapabilityContributions(
   ctx: SetupContext,
   plugins: Plugin[],
   plan: SetupInstallationPlan,
-): Promise<void> {
+  registrations: NormalizedRegistration[],
+): Promise<string[]> {
   const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
+  const ledgerRoot = surfaceRoot(ctx);
+  const ledger = await readContributionLedger(ledgerRoot);
+  const warnings: string[] = [];
+  let unswept = ledger?.unswept ?? [];
+  if (!ledger || unswept.length > 0) {
+    if (!ledger) {
+      await removeForeignGuidanceBlocks(ledgerRoot, new Set(plugins.map((plugin) => plugin.id)));
+    }
+    const sweep = await sweepAudienceDeclarations(ctx, {
+      registrations,
+      ...(ledger ? { packages: new Set(unswept) } : {}),
+    });
+    prependTeardown(inputsByRuntime, sweep.teardown);
+    unswept = sweep.unswept;
+    warnings.push(...sweep.warnings);
+  }
+  prependLedgerTeardown(inputsByRuntime, ledger);
   for (const [runtimeId, inputs] of inputsByRuntime) {
     const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
     if (!reconcile || inputs.length === 0) continue;
     await reconcile(ctx, inputs);
   }
+  await writeContributionLedger(ledgerRoot, ledgerFromInputs(inputsByRuntime, unswept));
+  return warnings;
+}
+
+/**
+ * Disabled inputs placed first, skipping any owner that is an enabled input
+ * of the pass on that runtime: removal runs before enabled inputs apply.
+ */
+function prependTeardown(
+  inputsByRuntime: Map<string, CapabilityContributionInput[]>,
+  teardownByRuntime: ReadonlyMap<string, readonly CapabilityContributionInput[]>,
+): void {
+  for (const [runtimeId, teardown] of teardownByRuntime) {
+    const inputs = inputsByRuntime.get(runtimeId) ?? [];
+    const enabled = new Set(inputs.filter((input) => input.enabled).map((input) => input.pluginId));
+    const kept = teardown.filter((input) => !enabled.has(input.pluginId));
+    if (kept.length > 0) inputsByRuntime.set(runtimeId, [...kept, ...inputs]);
+  }
+}
+
+/**
+ * Every recorded owner that is not an enabled input of this pass, as a
+ * disabled input placed first: its entries are removed before enabled inputs
+ * apply, so an identity another plugin still declares is re-applied after.
+ * Entries the ledger does not record are never named, so they survive.
+ */
+function prependLedgerTeardown(
+  inputsByRuntime: Map<string, CapabilityContributionInput[]>,
+  ledger: ContributionLedger | null,
+): void {
+  prependTeardown(
+    inputsByRuntime,
+    new Map(
+      Object.entries(ledger?.runtimes ?? {}).map(([runtimeId, owners]) => [
+        runtimeId,
+        Object.entries(owners).map(([owner, identities]) => ledgerTeardownInput(owner, identities)),
+      ]),
+    ),
+  );
+}
+
+/**
+ * The declared contributions of one audience's plugins, as enabled inputs per
+ * active runtime. No plugin phase and no lifecycle hook runs: an audience
+ * plugin contributes declaratively only. OpenCode plugin references are
+ * dropped — the Mate plugin has no way to load another plugin.
+ */
+export async function collectAudienceInputs(
+  ctx: SetupContext,
+  registrations: PluginRegistration[],
+  audience: string,
+): Promise<Map<string, CapabilityContributionInput[]>> {
+  const inputsByRuntime = new Map<string, CapabilityContributionInput[]>();
+  for (const entry of registrations.map(normalizeRegistration)) {
+    if (entry.audience !== audience || entry.plugin.kind !== "capability") continue;
+    const capability = entry.plugin as CapabilityPlugin;
+    if (!capability.getRuntimeContributions) continue;
+    if (entry.policy !== "required" && !capability.isEnabled(ctx.config)) continue;
+    const byRuntime = await capability.getRuntimeContributions(ctx);
+    for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
+      if (!contributions || !ctx.activeProviders.includes(runtimeId)) continue;
+      const { pluginReferences: _dropped, ...declarative } = contributions;
+      const inputs = inputsByRuntime.get(runtimeId) ?? [];
+      inputs.push({
+        pluginId: capability.id,
+        enabled: true,
+        capabilityEnabled: true,
+        contributions: declarative,
+      });
+      inputsByRuntime.set(runtimeId, inputs);
+    }
+  }
+  return inputsByRuntime;
+}
+
+/** What a render returns: its warnings are data for the caller, never printed here. */
+export interface RenderedRuntimeDocuments {
+  documents: RenderedRuntimeDocument[];
+  warnings: string[];
 }
 
 /**
@@ -261,7 +388,22 @@ export async function renderRuntimeDocuments(
   ctx: SetupContext,
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
-): Promise<RenderedRuntimeDocument[]> {
-  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
-  return renderDocumentsForTarget(ctx, await collectContributionInputs(ctx, plugins, plan));
+  wrapped?: { audience: string; registrations: PluginRegistration[] },
+): Promise<RenderedRuntimeDocuments> {
+  const plugins = persistedRegistrations(registrations).map((entry) => entry.plugin);
+  const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
+  /** A checkout wrapped for an audience carries it beside base; no other audience ever. */
+  if (wrapped) {
+    const audienceInputs = await collectAudienceInputs(
+      ctx,
+      wrapped.registrations,
+      wrapped.audience,
+    );
+    for (const [runtimeId, inputs] of audienceInputs) {
+      inputsByRuntime.set(runtimeId, [...(inputsByRuntime.get(runtimeId) ?? []), ...inputs]);
+    }
+  }
+  const documents = renderDocumentsForTarget(ctx, inputsByRuntime);
+  if (ctx.target !== "working") return { documents, warnings: [] };
+  return mergeCompanionOpenCodeConfig(ctx.companionPath, documents);
 }

package/src/tools/setup/isolation-diagnostics.ts

@@ -0,0 +1,139 @@
+// oxlint-disable no-await-in-loop
+import path from "node:path";
+
+import type { FrameworkConfig } from "../../lib/orchestrator/types";
+import {
+  readContributionLedger,
+  type ContributionLedger,
+  type LedgerIdentities,
+} from "./contribution-ledger";
+import type { CapabilityPlugin, SetupContext } from "./plugin";
+import type { PluginRegistry } from "./registry";
+import { managedGuidanceOwners } from "./upgrade-sweep";
+
+/**
+ * What `mate doctor` reports about audience isolation: contributions on the
+ * companion's persisted surfaces that no base plugin owns, audience plugins
+ * the upgrade sweep could not load, and the active audience's plugins whose
+ * imperative parts a launch layer cannot deliver.
+ */
+
+export interface LeakedContribution {
+  /** Companion-relative file or directory. */
+  surface: string;
+  kind: string;
+  /** The entry's name; absent where the surface entry is the owner's block. */
+  identity?: string;
+  owner: string;
+}
+
+export interface UndeliveredAudiencePlugin {
+  pluginId: string;
+  /** `apply`, `teardown`, `forProvider` or `pluginReferences`. */
+  parts: string[];
+}
+
+export interface AudienceIsolationReport {
+  leaked: LeakedContribution[];
+  unswept: string[];
+  undelivered: UndeliveredAudiencePlugin[];
+}
+
+/** Ledger kinds by where each runtime keeps them; guidance is read from the files themselves. */
+const LEDGER_SURFACES: Record<string, Partial<Record<keyof LedgerIdentities, string>>> = {
+  claude: {
+    mcpServers: ".mcp.json",
+    skillTrees: path.join(".claude", "skills"),
+    agentDefinitions: path.join(".claude", "agents"),
+    hookMarkers: path.join(".claude", "settings.local.json"),
+    permissionEntries: path.join(".claude", "settings.local.json"),
+  },
+  opencode: {
+    mcpServers: path.join(".opencode", "opencode.json"),
+    pluginReferences: path.join(".opencode", "opencode.json"),
+    skillTrees: path.join(".agents", "skills"),
+    agentDefinitions: path.join(".opencode", "agents"),
+  },
+};
+
+function leakedLedgerContributions(
+  ledger: ContributionLedger | null,
+  baseIds: ReadonlySet<string>,
+): LeakedContribution[] {
+  const leaked: LeakedContribution[] = [];
+  for (const [runtimeId, owners] of Object.entries(ledger?.runtimes ?? {})) {
+    for (const [owner, identities] of Object.entries(owners)) {
+      if (baseIds.has(owner)) continue;
+      for (const [kind, surface] of Object.entries(LEDGER_SURFACES[runtimeId] ?? {})) {
+        for (const identity of identities[kind as keyof LedgerIdentities] ?? []) {
+          leaked.push({ surface: surface!, kind, identity, owner });
+        }
+      }
+    }
+  }
+  return leaked;
+}
+
+/**
+ * Whether a lifecycle hook does anything. `apply` and `teardown` are required
+ * members, so a declarative plugin carries empty ones; only a body counts.
+ */
+function hasBody(hook: unknown): boolean {
+  if (typeof hook !== "function") return false;
+  const source = Function.prototype.toString.call(hook);
+  const open = source.indexOf("{");
+  const close = source.lastIndexOf("}");
+  if (open === -1 || close <= open) return true;
+  const body = source
+    .slice(open + 1, close)
+    .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "")
+    .trim();
+  return body.length > 0;
+}
+
+async function undeliveredParts(plugin: CapabilityPlugin, ctx: SetupContext): Promise<string[]> {
+  const parts: string[] = [];
+  if (hasBody(plugin.apply)) parts.push("apply");
+  if (hasBody(plugin.teardown)) parts.push("teardown");
+  if (plugin.forProvider && Object.keys(plugin.forProvider).length > 0) parts.push("forProvider");
+  try {
+    const byRuntime = (await plugin.getRuntimeContributions?.(ctx)) ?? {};
+    if (Object.values(byRuntime).some((runtime) => (runtime?.pluginReferences ?? []).length > 0)) {
+      parts.push("pluginReferences");
+    }
+  } catch {
+    /** A plugin whose declarations fail is the plugin checks' finding, not this one. */
+  }
+  return parts;
+}
+
+export async function inspectAudienceIsolation(
+  companionPath: string,
+  config: FrameworkConfig,
+  registry: PluginRegistry,
+  activeAudience: string | null,
+): Promise<AudienceIsolationReport> {
+  const baseIds = new Set(registry.baseRegistrations().map((entry) => entry.plugin.id));
+  const leaked: LeakedContribution[] = [];
+
+  for (const [surface, owners] of await managedGuidanceOwners(companionPath)) {
+    for (const owner of owners) {
+      if (!baseIds.has(owner)) leaked.push({ surface, kind: "guidance", owner });
+    }
+  }
+
+  const ledger = await readContributionLedger(companionPath);
+  leaked.push(...leakedLedgerContributions(ledger, baseIds));
+
+  const undelivered: UndeliveredAudiencePlugin[] = [];
+  if (activeAudience) {
+    const ctx: SetupContext = { companionPath, config, mode: "sync", activeProviders: [] };
+    for (const { plugin } of registry.audienceRegistrations(activeAudience)) {
+      if (plugin.kind !== "capability") continue;
+      const parts = await undeliveredParts(plugin as CapabilityPlugin, ctx);
+      if (parts.length > 0) undelivered.push({ pluginId: plugin.id, parts });
+    }
+  }
+
+  return { leaked, unswept: ledger?.unswept ?? [], undelivered };
+}

package/src/tools/setup/mate.ts

@@ -81,7 +81,7 @@ A \`diff\` section carries a unified diff patch as produced by \`git diff\`. The
 { "id": "changes", "title": "Changes", "type": "diff", "patch": "diff --git a/src/acme.ts b/src/acme.ts\\n..." }
 \`\`\`
 
-A report carrying a mermaid payload inlines the diagram runtime; a report without one does not. Either way the page stays a single self-contained file that makes no network request.
+A report carrying a mermaid payload loads the pinned, integrity-checked diagram runtime from a CDN; a report without one does not. Offline, each diagram stays readable as its source. Otherwise the page stays a single self-contained file.
 
 ## Invocation
 

package/src/tools/setup/plugin.ts

@@ -7,9 +7,10 @@ export type SetupScope = "companion" | "hub";
 /**
  * Where a reconcile pass lands its documents. `companion` writes the material's
  * own repository; `working` renders the documents an Agent Runtime discovers by
- * its own upward walk and leaves the placing to the Projection Root.
+ * its own upward walk and leaves the placing to the Projection Root;
+ * `audience-layer` writes one audience's launch layer, outside every repository.
  */
-export type ProjectionTarget = "companion" | "working";
+export type ProjectionTarget = "companion" | "working" | "audience-layer";
 
 export interface SetupContext {
   companionPath: string;
@@ -22,6 +23,14 @@ export interface SetupContext {
   repoPath?: string;
   /** Defaults to `companion`, so a caller that names no target is unchanged. */
   target?: ProjectionTarget;
+  /** The audience an `audience-layer` pass renders; required by that target only. */
+  audience?: string;
+  /**
+   * Where an `audience-layer` pass writes: the staging directory a render is
+   * built in before it is renamed into place. The audience's layer directory
+   * when absent.
+   */
+  layerRoot?: string;
   /**
    * Provider-mediated context services. Always populated when the engine
    * executes a plugin; optional so hand-built contexts (tests, direct calls)
@@ -122,9 +131,15 @@ export type PluginPolicy = "required" | "default" | "optional";
 
 /**
  * A plugin registration entry. Bare plugins derive their policy from
- * `defaultSelected` (`true` → "default", `false` → "optional").
+ * `defaultSelected` (`true` → "default", `false` → "optional"). `audience` is
+ * the source of a declared plugin: `null` (or absent) for compiled-in plugins
+ * and top-level `plugins` declarations, the audience name for a declaration
+ * under `audiences.<name>.plugins`. `packageName` names the declared package a
+ * dynamic plugin was loaded from.
  */
-export type PluginRegistration = Plugin | { plugin: Plugin; policy: PluginPolicy };
+export type PluginRegistration =
+  | Plugin
+  | { plugin: Plugin; policy: PluginPolicy; audience?: string | null; packageName?: string };
 
 /**
  * A hook group a Capability contributes to a runtime's settings. `marker` is

package/src/tools/setup/plugins/gitignore.ts

@@ -97,7 +97,13 @@ export function createGitignorePlugin(
 ): Plugin {
   // Resolve lazily so plugin sets can be built before a distribution is active.
   const resolveName = typeof frameworkName === "function" ? frameworkName : () => frameworkName;
-  const resolvePlugins = allPlugins ?? (() => getActiveDistribution().registry.getAll());
+  /** Base only: an audience plugin's entries would reach the committed `.gitignore`. */
+  const resolvePlugins =
+    allPlugins ??
+    (() =>
+      getActiveDistribution()
+        .registry.baseRegistrations()
+        .map((entry) => entry.plugin));
   return {
     id: "gitignore",
     kind: "root",

package/src/tools/setup/providers/claude-format.ts

@@ -1,6 +1,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { hookGroupKey, type ClaudeHookGroup } from "../../../runtime/claude-hook-group";
+
 // Structurally matches `McpServerDescriptor` from ../plugin; declared here so
 // the format module stays dependency-free of the plugin contract (which
 // imports hook types from this module).
@@ -17,17 +19,11 @@ export interface McpEntryDescriptor {
 // groups are Mate-managed lives here too, because the companion-side reconcile
 // and the working-repo projection entry must strip the same set.
 
-export interface ClaudeHookCommand {
-  type?: string;
-  command?: string;
-  args?: string[];
-  timeout?: number;
-}
-
-export interface ClaudeHookGroup {
-  matcher?: string;
-  hooks?: ClaudeHookCommand[];
-}
+export {
+  hookGroupKey,
+  type ClaudeHookCommand,
+  type ClaudeHookGroup,
+} from "../../../runtime/claude-hook-group";
 
 export type ClaudeHookMap = Record<string, ClaudeHookGroup[]>;
 
@@ -43,10 +39,6 @@ export interface ClaudeMcpConfig {
   [key: string]: unknown;
 }
 
-function hookGroupKey(group: ClaudeHookGroup): string {
-  return JSON.stringify(group);
-}
-
 /** Append incoming hook groups per event, skipping structurally identical ones. */
 export function mergeClaudeHookGroups(
   existingHooks: ClaudeHookMap,
@@ -84,9 +76,10 @@ export function filterClaudeHookGroups(
 
 // Command substrings that mark a hook group as Mate-managed. The mate plugin
 // hooks (validate-artifact-path, mate-session-banner) now ship in the bundled
-// Claude plugin, and the retired mate-artifact-finish.sh archive hook is gone
-// entirely; their markers are retained migration-only so stale managed groups
-// written by earlier releases keep being stripped, and are never re-added.
+// Claude plugin, and the retired mate-artifact-finish.sh archive hook and
+// react-doctor.sh post-edit scan are gone entirely; their markers are retained
+// migration-only so stale managed groups written by earlier releases keep being
+// stripped, and are never re-added.
 const MANAGED_HOOK_MARKERS = [
   "validate-artifact-path",
   "mate-session-banner",

package/src/tools/setup/providers/claude-plugin-hooks.ts

@@ -3,7 +3,8 @@ import path from "node:path";
 
 import { PROJECTED_BANNER_FLAG } from "../../../hooks/session-banner";
 import { getClaudePluginRoot } from "../../../lib/package-paths";
-import type { ClaudeHookGroup } from "./claude-format";
+import { runtimeClaudePluginRoot } from "../../../runtime/runtime-directory";
+import { hookGroupKey, type ClaudeHookGroup } from "./claude-format";
 
 /**
  * The bundled Claude plugin's hook wiring, read as a value. A managed launch
@@ -17,11 +18,16 @@ import type { ClaudeHookGroup } from "./claude-format";
  * environment is present and so cannot double the prompt the launch already
  * appended; and the banner, whose carried copy is marked so it defers to the
  * launch's.
+ *
+ * The wiring is read from the installed plugin, but every command names
+ * `<mate home>/runtime/claude-plugin`, so a reinstall or Node switch does not
+ * strand a wrapped repository.
  */
 
 const GUARD_HOOK_SHIM = "validate-artifact-path.mjs";
 const GUIDANCE_HOOK_SHIM = "session-guidance.mjs";
 const BANNER_HOOK_SHIM = "session-banner.mjs";
+const PREPARE_HOOK_SHIM = "session-prepare.mjs";
 const PLUGIN_ROOT_TOKEN = "${CLAUDE_PLUGIN_ROOT}";
 
 interface PluginHookWiring {
@@ -50,26 +56,24 @@ function resolveCommands(group: ClaudeHookGroup, pluginRoot: string): ClaudeHook
   };
 }
 
-function runsShim(shim: string): (group: ClaudeHookGroup) => boolean {
-  return (group) => (group.hooks ?? []).some((hook) => (hook.command ?? "").includes(shim));
+function runsShim(group: ClaudeHookGroup, shim: string): boolean {
+  return (group.hooks ?? []).some((hook) => (hook.command ?? "").includes(shim));
 }
 
-function groupsFor(
-  event: string,
-  shim: string,
-  pluginRoot: string = getClaudePluginRoot(),
-): ClaudeHookGroup[] {
-  return (readPluginHookWiring(pluginRoot).hooks?.[event] ?? [])
-    .filter(runsShim(shim))
-    .map((group) => resolveCommands(group, pluginRoot));
+function groupsFor(event: string, shim: string, commandRoot: string): ClaudeHookGroup[] {
+  return (readPluginHookWiring(getClaudePluginRoot()).hooks?.[event] ?? []).flatMap((group) =>
+    runsShim(group, shim) ? [resolveCommands(group, commandRoot)] : [],
+  );
 }
 
 /**
  * The guard's `PreToolUse` groups with `${CLAUDE_PLUGIN_ROOT}` resolved against
- * the running installation, so the command works with no launch environment.
+ * the runtime link, so the command works with no launch environment.
  */
-export function mateGuardHookGroups(pluginRoot: string = getClaudePluginRoot()): ClaudeHookGroup[] {
-  return groupsFor("PreToolUse", GUARD_HOOK_SHIM, pluginRoot);
+export function mateGuardHookGroups(
+  commandRoot: string = runtimeClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return groupsFor("PreToolUse", GUARD_HOOK_SHIM, commandRoot);
 }
 
 /**
@@ -79,9 +83,9 @@ export function mateGuardHookGroups(pluginRoot: string = getClaudePluginRoot()):
  * flag.
  */
 export function mateGuidanceHookGroups(
-  pluginRoot: string = getClaudePluginRoot(),
+  commandRoot: string = runtimeClaudePluginRoot(),
 ): ClaudeHookGroup[] {
-  return groupsFor("SessionStart", GUIDANCE_HOOK_SHIM, pluginRoot);
+  return groupsFor("SessionStart", GUIDANCE_HOOK_SHIM, commandRoot);
 }
 
 /**
@@ -91,9 +95,9 @@ export function mateGuidanceHookGroups(
  * would print the banner twice.
  */
 export function mateBannerHookGroups(
-  pluginRoot: string = getClaudePluginRoot(),
+  commandRoot: string = runtimeClaudePluginRoot(),
 ): ClaudeHookGroup[] {
-  return groupsFor("SessionStart", BANNER_HOOK_SHIM, pluginRoot).map((group) => ({
+  return groupsFor("SessionStart", BANNER_HOOK_SHIM, commandRoot).map((group) => ({
     ...group,
     hooks: (group.hooks ?? []).map((hook) => ({
       ...hook,
@@ -102,16 +106,49 @@ export function mateBannerHookGroups(
   }));
 }
 
+/**
+ * The session-prepare `SessionStart` group, resolved the same way. Its declared
+ * `timeout` sits above the shim's own bound, so Claude Code never kills a
+ * prepare the shim has not given up on. Inert under a launch environment.
+ */
+export function mateSessionPrepareHookGroups(
+  commandRoot: string = runtimeClaudePluginRoot(),
+): ClaudeHookGroup[] {
+  return groupsFor("SessionStart", PREPARE_HOOK_SHIM, commandRoot);
+}
+
+function mateOwnHookGroups(commandRoot: string): ClaudeHookGroup[] {
+  return [
+    ...mateGuardHookGroups(commandRoot),
+    ...mateGuidanceHookGroups(commandRoot),
+    ...mateBannerHookGroups(commandRoot),
+    ...mateSessionPrepareHookGroups(commandRoot),
+  ];
+}
+
+const ownGroupKeys = new Map<string, ReadonlySet<string>>();
+
+/** Memoized per plugin-root pair; hooks are short-lived, so a refresh mid-process is not tracked. */
+function mateOwnHookGroupKeys(runtimeRoot: string, installRoot: string): ReadonlySet<string> {
+  const memoKey = `${runtimeRoot}\0${installRoot}`;
+  let keys = ownGroupKeys.get(memoKey);
+  if (!keys) {
+    keys = new Set(
+      [...mateOwnHookGroups(runtimeRoot), ...mateOwnHookGroups(installRoot)].map(hookGroupKey),
+    );
+    ownGroupKeys.set(memoKey, keys);
+  }
+  return keys;
+}
+
 /**
  * Whether a hook group is one the working target placed. It matches a managed
  * marker, so the entry that strips managed groups from a Working Repository has
- * to be told to leave these alone.
+ * to be told to leave these alone. Both the runtime-link form and the
+ * install-path form an older release wrote are recognized.
  */
 export function isMateGuardHookGroup(group: ClaudeHookGroup): boolean {
-  const own = new Set(
-    [...mateGuardHookGroups(), ...mateGuidanceHookGroups(), ...mateBannerHookGroups()].map(
-      (candidate) => JSON.stringify(candidate),
-    ),
+  return mateOwnHookGroupKeys(runtimeClaudePluginRoot(), getClaudePluginRoot()).has(
+    hookGroupKey(group),
   );
-  return own.has(JSON.stringify(group));
 }