@uniqbit/mate-core 0.18.5 → 1.0.0-canary.0

package/src/tools/setup/context-services.ts

@@ -3,6 +3,8 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { managedBlockMarkers, managedBlockStartPattern } from "../../runtime/managed-block";
+import { removeEmptiedFile, writeAtomicThroughLink } from "../../runtime/write-atomic";
 import type {
   InstructionsService,
   McpServerDescriptor,
@@ -63,13 +65,6 @@ async function saveManifest(
 // Managed instruction blocks
 // ---------------------------------------------------------------------------
 
-function blockMarkers(frameworkName: string, blockKey: string): { start: string; end: string } {
-  return {
-    start: `<!-- ${frameworkName}:managed:${blockKey} start -->`,
-    end: `<!-- ${frameworkName}:managed:${blockKey} end -->`,
-  };
-}
-
 export function instructionBlockKey(pluginId: string, content: string): string {
   const hash = crypto.createHash("sha256").update(content).digest("hex").slice(0, 12);
   return `${pluginId}:${hash}`;
@@ -82,7 +77,7 @@ export async function upsertManagedBlock(
   blockKey: string,
   content: string,
 ): Promise<void> {
-  const { start, end } = blockMarkers(frameworkName, blockKey);
+  const { start, end } = managedBlockMarkers(frameworkName, blockKey);
   let existing = "";
   try {
     existing = await fs.readFile(filePath, "utf8");
@@ -93,7 +88,8 @@ export async function upsertManagedBlock(
   if (existing.includes(start)) return;
   const separator = existing.length === 0 || existing.endsWith("\n\n") ? "" : "\n";
   await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, existing + (existing ? separator : "") + block, "utf8");
+  /** A session-start hook may read the file while another session's prepare rewrites it. */
+  await writeAtomicThroughLink(filePath, existing + (existing ? separator : "") + block);
 }
 
 /**
@@ -113,11 +109,7 @@ export async function removeManagedBlocksForPlugin(
   } catch {
     return;
   }
-  const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const keyPattern = new RegExp(
-    `<!-- ${escape(frameworkName)}:managed:(${escape(pluginId)}:[0-9a-f]+) start -->`,
-    "g",
-  );
+  const keyPattern = managedBlockStartPattern(frameworkName, pluginId);
   const keys = [...existing.matchAll(keyPattern)].map((match) => match[1]);
   for (const key of keys) {
     if (keepKeys.has(key)) continue;
@@ -131,7 +123,7 @@ async function removeManagedBlock(
   frameworkName: string,
   blockKey: string,
 ): Promise<void> {
-  const { start, end } = blockMarkers(frameworkName, blockKey);
+  const { start, end } = managedBlockMarkers(frameworkName, blockKey);
   let existing: string;
   try {
     existing = await fs.readFile(filePath, "utf8");
@@ -146,10 +138,10 @@ async function removeManagedBlock(
   const after = existing.slice(endIdx + end.length).replace(/^\n+/, "\n");
   const next = (before + after).replace(/^\n+/, "");
   if (!next.trim()) {
-    await fs.unlink(filePath).catch(() => {});
+    await removeEmptiedFile(filePath).catch(() => {});
     return;
   }
-  await fs.writeFile(filePath, next, "utf8");
+  await writeAtomicThroughLink(filePath, next);
 }
 
 // ---------------------------------------------------------------------------

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

@@ -26,45 +26,40 @@ export interface PluginInstallResult {
   error?: string;
 }
 
-/** Runs `npm install` for the shared plugin workspace, honoring the user's ambient registry/auth config. */
-function defaultNpmInstall(workspaceRoot: string): { ok: boolean; detail?: string } {
-  const result = spawnSync("npm", ["install", "--no-audit", "--no-fund", "--silent"], {
-    cwd: workspaceRoot,
-    encoding: "utf8",
-  });
+/**
+ * Runs `npm <command>` in the shared plugin workspace, honoring the user's ambient
+ * registry/auth config. `--loglevel=error` keeps npm's own error in stderr for the report.
+ */
+function runNpm(
+  workspaceRoot: string,
+  command: string,
+  args: string[] = [],
+): { ok: boolean; detail?: string } {
+  const result = spawnSync(
+    "npm",
+    [command, "--no-audit", "--no-fund", "--loglevel=error", ...args],
+    { cwd: workspaceRoot, encoding: "utf8" },
+  );
   if (result.error || result.status !== 0) {
     return {
       ok: false,
       detail:
         result.error?.message ??
-        result.stderr?.trim() ??
-        `npm install exited with ${result.status}`,
+        (result.stderr?.trim() || `npm ${command} exited with ${result.status}`),
     };
   }
   return { ok: true };
 }
 
+/** Runs `npm install` for the shared plugin workspace. */
+const defaultNpmInstall: NpmInstallRunner = (workspaceRoot) => runNpm(workspaceRoot, "install");
+
 /** Version literals treated as moving targets: re-resolved via `npm update` on every run. */
 const MOVING_VERSION_TAGS = new Set(["latest", "canary"]);
 
 /** Runs `npm update <pkg...>` to force re-resolution of moving-tag-declared plugins every run. */
-function defaultNpmUpdate(
-  workspaceRoot: string,
-  packages: string[],
-): { ok: boolean; detail?: string } {
-  const result = spawnSync("npm", ["update", "--no-audit", "--no-fund", "--silent", ...packages], {
-    cwd: workspaceRoot,
-    encoding: "utf8",
-  });
-  if (result.error || result.status !== 0) {
-    return {
-      ok: false,
-      detail:
-        result.error?.message ?? result.stderr?.trim() ?? `npm update exited with ${result.status}`,
-    };
-  }
-  return { ok: true };
-}
+const defaultNpmUpdate: NpmUpdateRunner = (workspaceRoot, packages) =>
+  runNpm(workspaceRoot, "update", packages);
 
 async function readInstalledVersion(packageRoot: string): Promise<string | null> {
   try {
@@ -155,14 +150,15 @@ export async function installDeclaredPlugins(
 
   await writeWorkspaceManifest(workspaceRoot, desired);
   const installOutcome = await runNpmInstall(workspaceRoot);
+  // Failure is decided from `ok`, so an empty detail can never read as success.
   const installFailure = installOutcome.ok
     ? undefined
-    : (installOutcome.detail ?? "npm install failed");
+    : installOutcome.detail || "npm install failed";
 
   let updateFailure: string | undefined;
   if (movingPackages.length > 0) {
     const updateOutcome = await runNpmUpdate(workspaceRoot, movingPackages);
-    updateFailure = updateOutcome.ok ? undefined : (updateOutcome.detail ?? "npm update failed");
+    updateFailure = updateOutcome.ok ? undefined : updateOutcome.detail || "npm update failed";
   }
 
   const resolvedVersions = await Promise.all(
@@ -174,7 +170,7 @@ export async function installDeclaredPlugins(
   return sorted.map((declaration, index) => {
     const isMoving = MOVING_VERSION_TAGS.has(declaration.version);
     const failure = installFailure ?? (isMoving ? updateFailure : undefined);
-    if (failure) {
+    if (failure !== undefined) {
       return { package: declaration.package, status: "failed", error: failure };
     }
     const resolvedVersion = resolvedVersions[index];

package/src/tools/setup/engine.ts

@@ -2,19 +2,29 @@
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
-import type { RenderedRuntimeDocument } from "../../runtime/runtime-document-manifest";
+import { getClaudePluginRoot } from "../../lib/package-paths";
+import type { RenderedRuntimeDocuments } from "../../runtime/runtime-document-manifest";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
 import type {
   CapabilityContributionInput,
   CapabilityPlugin,
   Plugin,
   PluginRegistration,
+  RuntimeContributionsByRuntime,
   SetupContext,
 } from "./plugin";
-import { reconcileClaudeContributions } from "./providers/claude";
-import { reconcileOpenCodeContributions } from "./providers/opencode";
-import { mergeCompanionOpenCodeConfig, renderDocumentsForTarget } from "./runtime-documents";
+import { reconcileClaudeContributions, renderClaudeWorkingDocuments } from "./providers/claude";
+import {
+  inspectClaudePluginFolders,
+  publishClaudePluginFolders,
+  type ClaudePluginFolders,
+} from "./providers/claude-plugin-folders";
+import {
+  reconcileOpenCodeContributions,
+  renderOpenCodeWorkingDocuments,
+} from "./providers/opencode";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
+import { projectionRepoRoot } from "./surface-target";
 
 export interface SetupInstallationPlanAction {
   phase: Plugin["kind"];
@@ -33,6 +43,11 @@ export interface SetupInstallationOutcome {
   executedActions: SetupInstallationPlanAction[];
   skippedActions: SetupInstallationPlanAction[];
   warnings: string[];
+  /**
+   * Enabled Capabilities' Claude plugin folders, published outside a hub (a hub
+   * has no wrap for plain sessions to load them through); never printed here.
+   */
+  claudePluginFolders: ClaudePluginFolders;
 }
 
 export function buildSetupInstallationPlan(
@@ -176,9 +191,15 @@ export async function executeSetupInstallationPlan(
 
   await mediator.finalize();
 
-  await reconcileCapabilityContributions(ctx, plugins, plan);
+  const inputsByRuntime = await reconcileCapabilityContributions(ctx, plugins, plan);
+  const claudeInputs = inputsByRuntime.get("claude") ?? [];
+  const folderOptions = { bundledPluginRoot: getClaudePluginRoot() };
+  const claudePluginFolders =
+    ctx.scope === "hub"
+      ? await inspectClaudePluginFolders(claudeInputs, folderOptions)
+      : await publishClaudePluginFolders(claudeInputs, folderOptions);
 
-  return { executedActions, skippedActions, warnings };
+  return { executedActions, skippedActions, warnings, claudePluginFolders };
 }
 
 // The Runtime Surface of each active Agent Runtime, by runtime id.
@@ -190,6 +211,18 @@ const RUNTIME_SURFACE_RECONCILERS: Record<
   opencode: reconcileOpenCodeContributions,
 };
 
+/**
+ * The working-target render of each Runtime Surface, by runtime id, in the
+ * order its documents are rendered.
+ */
+const RUNTIME_SURFACE_WORKING_RENDERERS: Record<
+  string,
+  (ctx: SetupContext, inputs: CapabilityContributionInput[]) => Promise<RenderedRuntimeDocuments>
+> = {
+  claude: renderClaudeWorkingDocuments,
+  opencode: renderOpenCodeWorkingDocuments,
+};
+
 /**
  * The declared Capability contributions of one pass, keyed by runtime. Shared
  * by both targets: what a companion pass writes is what a working pass renders.
@@ -198,6 +231,7 @@ async function collectContributionInputs(
   ctx: SetupContext,
   plugins: Plugin[],
   plan: SetupInstallationPlan,
+  onContributionError?: ContributionErrorHandler,
 ): Promise<Map<string, CapabilityContributionInput[]>> {
   // The plan already resolved enablement (policy, saved selection, package
   // manager requirements); mirror it instead of recomputing.
@@ -213,7 +247,14 @@ async function collectContributionInputs(
     const capability = plugin as CapabilityPlugin;
     if (!capability.getRuntimeContributions) continue;
     const enabled = enabledByPluginId.get(capability.id) ?? false;
-    const byRuntime = await capability.getRuntimeContributions(ctx);
+    let byRuntime: RuntimeContributionsByRuntime;
+    try {
+      byRuntime = await capability.getRuntimeContributions(ctx);
+    } catch (error) {
+      if (!onContributionError) throw error;
+      onContributionError(capability.id, error);
+      continue;
+    }
     for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
       if (!contributions) continue;
       // Inactive runtimes still reconcile — with everything disabled — so a
@@ -237,42 +278,77 @@ async function collectContributionInputs(
  * Reconcile declared Capability contributions through every active runtime's
  * Runtime Surface (spec: plugin-engine). Runs after all plugin phases, so
  * providers are always done first. Disabled capabilities participate with
- * `enabled: false` and drive teardown of their managed entries.
+ * `enabled: false` and drive teardown of their managed entries. Returns the
+ * inputs it reconciled, so the pass derives launch-only data from the same ones.
  */
 async function reconcileCapabilityContributions(
   ctx: SetupContext,
   plugins: Plugin[],
   plan: SetupInstallationPlan,
-): Promise<void> {
+): Promise<Map<string, CapabilityContributionInput[]>> {
   const inputsByRuntime = await collectContributionInputs(ctx, plugins, plan);
   for (const [runtimeId, inputs] of inputsByRuntime) {
     const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
     if (!reconcile || inputs.length === 0) continue;
     await reconcile(ctx, inputs);
   }
+  return inputsByRuntime;
 }
 
-/** What a render returns: its warnings are data for the caller, never printed here. */
-export interface RenderedRuntimeDocuments {
-  documents: RenderedRuntimeDocument[];
-  warnings: string[];
+/** Receives one Capability's rejected contributions; that Capability then contributes nothing. */
+export type ContributionErrorHandler = (capabilityId: string, error: unknown) => void;
+
+/**
+ * One pass's declared Capability contributions by runtime, collected without a
+ * reconcile. A rejecting Capability fails the collection unless
+ * `onContributionError` takes its error; only diagnostics should pass one.
+ */
+export async function collectRuntimeContributionInputs(
+  ctx: SetupContext,
+  registrations: PluginRegistration[],
+  plan: SetupInstallationPlan,
+  onContributionError?: ContributionErrorHandler,
+): Promise<Map<string, CapabilityContributionInput[]>> {
+  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
+  return collectContributionInputs(ctx, plugins, plan, onContributionError);
 }
 
 /**
  * The same declarations, rendered rather than written: a working-target pass
  * produces the documents and the Projection Root places them, so no Runtime
- * Surface reaches inside a Working Repository.
+ * Surface reaches inside a Working Repository. Refuses before anything renders
+ * when the context has no Working Repository: every document is addressed by it.
+ * Its warnings are data for the caller, never printed here.
  */
 export async function renderRuntimeDocuments(
   ctx: SetupContext,
   registrations: PluginRegistration[],
   plan: SetupInstallationPlan,
 ): Promise<RenderedRuntimeDocuments> {
-  const plugins = registrations.map((entry) => normalizeRegistration(entry).plugin);
-  const documents = renderDocumentsForTarget(
-    ctx,
-    await collectContributionInputs(ctx, plugins, plan),
-  );
-  if (ctx.target !== "working") return { documents, warnings: [] };
-  return mergeCompanionOpenCodeConfig(ctx.companionPath, documents);
+  projectionRepoRoot(ctx);
+  const inputsByRuntime = await collectRuntimeContributionInputs(ctx, registrations, plan);
+  const rendered: RenderedRuntimeDocuments = { documents: [], warnings: [] };
+  for (const [runtimeId, render] of Object.entries(RUNTIME_SURFACE_WORKING_RENDERERS)) {
+    if (!ctx.activeProviders.includes(runtimeId)) continue;
+    const { documents, warnings } = await render(ctx, inputsByRuntime.get(runtimeId) ?? []);
+    rendered.documents.push(...documents);
+    rendered.warnings.push(...warnings);
+  }
+  return rendered;
+}
+
+/**
+ * Publishes the enabled Claude plugin folders for a wrap pass, before it
+ * renders: writes Mate's marketplace files and removes those of disabled
+ * Capabilities. Runs no plugin phase.
+ */
+export async function publishRuntimeClaudePluginMarketplaces(
+  ctx: SetupContext,
+  registrations: PluginRegistration[],
+  plan: SetupInstallationPlan,
+): Promise<ClaudePluginFolders> {
+  const inputsByRuntime = await collectRuntimeContributionInputs(ctx, registrations, plan);
+  return publishClaudePluginFolders(inputsByRuntime.get("claude") ?? [], {
+    bundledPluginRoot: getClaudePluginRoot(),
+  });
 }

package/src/tools/setup/managed-output.ts

@@ -0,0 +1,51 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import type {
+  ManagedOutputEntry,
+  ManagedOutputOwner,
+  ManagedOutputRecorder,
+  ManagedOutputReport,
+} from "./plugin";
+
+export interface ManagedOutputCollector {
+  recorder: ManagedOutputRecorder;
+  /** Entries inside the companion, deduplicated, as companion-relative POSIX paths. */
+  report(): ManagedOutputReport;
+}
+
+export function createManagedOutputCollector(companionPath: string): ManagedOutputCollector {
+  const entries: ManagedOutputEntry[] = [];
+  return {
+    recorder: { record: (entry) => entries.push(entry) },
+    report() {
+      const seen = new Set<string>();
+      const report: ManagedOutputEntry[] = [];
+      for (const entry of entries) {
+        const relative = path.relative(companionPath, entry.path);
+        if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) continue;
+        const posix = relative.split(path.sep).join("/");
+        const key = `${entry.change}\0${entry.owner}\0${posix}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        report.push({ ...entry, path: posix });
+      }
+      return report;
+    },
+  };
+}
+
+/** Removes `target` and records it, only when it existed: a no-op removal claims nothing. */
+export async function removeRecorded(
+  target: string,
+  owner: ManagedOutputOwner,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
+  const existed = await fs.lstat(target).then(
+    () => true,
+    () => false,
+  );
+  if (!existed) return;
+  await fs.rm(target, { recursive: true, force: true });
+  recorder?.record({ path: target, change: "removed", owner });
+}

package/src/tools/setup/mate.ts

@@ -1,13 +1,20 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { removeRecorded } from "./managed-output";
+import type { ManagedOutputRecorder } from "./plugin";
 import { pruneEmptyAncestors } from "./utils";
+import { readFrontmatter } from "../../lib/frontmatter";
 
-export const MATE_ARTIFACT_SKILLS = ["mate-artifact-publish"] as const;
 export const MATE_SKILLS = [
-  "mate-artifact-publish",
+  "mate-clarify-intent",
+  "mate-explore-change",
+  "mate-propose-change",
+  "mate-apply-change",
+  "mate-archive-change",
+  "mate-publish-artifact",
+  "mate-backfill-spec",
   "mate-create-report",
-  "mate-openspec-backfill",
   "mate-interview-me",
   "mate-grill-me",
   "mate-grilling",
@@ -17,8 +24,11 @@ export const MATE_SKILLS = [
   "mate-simplify-code",
 ] as const;
 const LEGACY_MATE_SKILLS = ["mate-artifact-finish", "mate-openspec-artifact-finish"] as const;
-/** Every Mate-owned skill name a skill root may hold, current or retired. */
-export const MANAGED_MATE_SKILL_NAMES = [...MATE_SKILLS, ...LEGACY_MATE_SKILLS] as const;
+/**
+ * Renamed without aliases: removed only when Mate wrote them (`metadata.author: mate`),
+ * so a user-authored skill that happens to share a retired name is left alone.
+ */
+const RETIRED_MATE_SKILLS = ["mate-artifact-publish", "mate-openspec-backfill"] as const;
 
 const MATE_SKILLS_SOURCE = path.join(import.meta.dirname, "../../templates/mate-skills");
 
@@ -83,13 +93,41 @@ A \`diff\` section carries a unified diff patch as produced by \`git diff\`. The
 
 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.
 
+## Presentation Fields
+
+These fields are optional. A document without them stays valid and renders with the defaults.
+
+- \`tone\` on a status item: \`ok\`, \`warn\`, \`error\`, \`info\`, or \`neutral\`. It sets the marker's colour and shape. When absent, the tone is inferred from well-known status words such as \`passed\`, \`stale\`, or \`failed\`, and any other text is \`neutral\`.
+
+  \`\`\`json
+  { "label": "Build", "status": "flaky", "tone": "warn" }
+  \`\`\`
+
+- \`format\` on a \`text\` section: \`plain\` (default, shown verbatim with its line breaks) or \`markdown\`.
+
+  \`\`\`json
+  { "id": "notes", "title": "Notes", "type": "text", "format": "markdown", "content": "- **Renderer** owns layout\\n- See \`highlight.ts\`" }
+  \`\`\`
+
+- \`caption\` on a \`diagram\` or \`diff\` section: a non-empty Markdown note shown beneath the visual, in the same section and without a heading of its own.
+
+  \`\`\`json
+  { "id": "changes", "title": "Changes", "type": "diff", "patch": "...", "caption": "Moves validation into \`contract.ts\`." }
+  \`\`\`
+
+Markdown supports paragraphs, \`#\` headings, one-level \`-\`, \`*\`, or \`1.\` lists, \`**strong**\`, \`*emphasis*\`, \`\` \`code\` \`\`, fenced code blocks with syntax highlighting, and \`[text](https://…)\` links. Raw HTML is shown as text, links other than \`http\` or \`https\` are shown as plain text, and any other syntax stays literal.
+
+The page follows the reader's colour scheme: Mate brand colours on white in light mode, and on a dark background in dark mode, with highlighted code and mermaid diagrams following the same scheme. It always prints as dark text on white.
+
+To mark mermaid nodes, apply the theme classes \`added\`, \`changed\`, and \`removed\` with \`class\` or \`:::\`; they follow the colour scheme. Lines that fix a colour with \`classDef\`, \`style\`, or \`linkStyle\` are dropped from the dark copy, because a fill chosen for a white page hides the labels there.
+
 ## Invocation
 
 1. Serialize the complete document to a temporary file or pipe it to stdin.
 2. Run \`mate report --input <file-or->\`.
 3. Add \`--json\` when the caller needs normalized JSON instead of browser delivery.
 
-The CLI chooses the delivery surface; deliver only through \`mate report\`, never a hand-written file, server, or browser launch. Inside a Studio terminal it hosts the report in Studio and prints a full link only when Studio has a public address, otherwise it tells the operator to open Studio → Reports; relay that output. Elsewhere, or when Studio is unreachable, it writes self-contained HTML to a unique OS temporary directory and opens it in the default browser. The report includes a visible "Print / Save as PDF" control that calls the browser's native print dialog. If HTML delivery fails, the CLI warns on stderr and emits the complete report document as JSON on stdout.
+The CLI chooses the delivery surface; deliver only through \`mate report\`, never a hand-written file, server, or browser launch. Inside a Studio terminal it hosts the report in Studio and prints a full link only when Studio has a public address, otherwise it tells the operator to open Studio → Reports; relay that output. Elsewhere, or when Studio is unreachable, it writes self-contained HTML to a unique OS temporary directory and opens it in the default browser. The report header carries an icon-only print control, named "Print / Save as PDF", that calls the browser's native print dialog. If HTML delivery fails, the CLI warns on stderr and emits the complete report document as JSON on stdout.
 
 The built-in \`mate report\` path collects Mate usage data and adapts it to the same contract and renderer.
 `;
@@ -133,10 +171,41 @@ async function resolveMateSkillSource(skill: string, tool: string): Promise<stri
   throw new Error(`Mate skill source not found: ${skill}`);
 }
 
-export async function applyMateSkills(skillsDir: string, tool: string): Promise<void> {
+/** The `metadata.author` a skill directory's SKILL.md declares, if any. */
+export async function readSkillAuthor(skillDir: string): Promise<unknown> {
+  let source: string;
+  try {
+    source = await fs.readFile(path.join(skillDir, "SKILL.md"), "utf8");
+  } catch {
+    return undefined;
+  }
+  const metadata = readFrontmatter(source)?.metadata as { author?: unknown } | null | undefined;
+  return metadata?.author;
+}
+
+async function isMateAuthored(skillDir: string): Promise<boolean> {
+  return (await readSkillAuthor(skillDir)) === "mate";
+}
+
+export async function removeRetiredMateSkills(
+  skillsDir: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
+  for (const skill of RETIRED_MATE_SKILLS) {
+    const dir = path.join(skillsDir, skill);
+    if (await isMateAuthored(dir)) await removeRecorded(dir, "mate", recorder);
+  }
+}
+
+export async function applyMateSkills(
+  skillsDir: string,
+  tool: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
   for (const skill of LEGACY_MATE_SKILLS) {
-    await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+    await removeRecorded(path.join(skillsDir, skill), "mate", recorder);
   }
+  await removeRetiredMateSkills(skillsDir, recorder);
   for (const skill of MATE_SKILLS) {
     const destination = path.join(skillsDir, skill);
     if (skill === "mate-create-report") {
@@ -145,13 +214,19 @@ export async function applyMateSkills(skillsDir: string, tool: string): Promise<
     } else {
       await deployMateSkillDir(await resolveMateSkillSource(skill, tool), destination);
     }
+    recorder?.record({ path: destination, change: "written", owner: "mate" });
   }
 }
 
-export async function teardownMateSkills(skillsDir: string, companionPath: string): Promise<void> {
-  for (const skill of MANAGED_MATE_SKILL_NAMES) {
+export async function teardownMateSkills(
+  skillsDir: string,
+  companionPath: string,
+  recorder?: ManagedOutputRecorder,
+): Promise<void> {
+  await removeRetiredMateSkills(skillsDir, recorder);
+  for (const skill of [...MATE_SKILLS, ...LEGACY_MATE_SKILLS]) {
     try {
-      await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+      await removeRecorded(path.join(skillsDir, skill), "mate", recorder);
     } catch {
       /* not present */
     }

package/src/tools/setup/plugin.ts

@@ -1,4 +1,5 @@
 import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/types";
+import type { SessionKind } from "../../runtime/session-kind";
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
 import type { ClaudeHookGroup } from "./providers/claude-format";
 
@@ -22,6 +23,11 @@ export interface SetupContext {
   repoPath?: string;
   /** Defaults to `companion`, so a caller that names no target is unchanged. */
   target?: ProjectionTarget;
+  /**
+   * Asks the OpenSpec capability to regenerate its CLI output in `sync` mode.
+   * Only `mate companion update` sets it; launches leave committed output alone.
+   */
+  regenerateOpenSpec?: boolean;
   /**
    * Provider-mediated context services. Always populated when the engine
    * executes a plugin; optional so hand-built contexts (tests, direct calls)
@@ -30,13 +36,34 @@ export interface SetupContext {
   mcp?: McpService;
   instructions?: InstructionsService;
   templates?: TemplatesService;
+  /** Collects the managed output a sync pass touched; absent outside one. */
+  managedOutput?: ManagedOutputRecorder;
+}
+
+export type ManagedOutputOwner = "mate" | "openspec";
+
+/** One path a pass wrote or removed, with the side that owns it. */
+export interface ManagedOutputEntry {
+  /** Absolute when recorded; companion-relative POSIX in a {@link ManagedOutputReport}. */
+  path: string;
+  change: "written" | "removed";
+  owner: ManagedOutputOwner;
 }
 
+export interface ManagedOutputRecorder {
+  record(entry: ManagedOutputEntry): void;
+}
+
+/** What a sync pass reports it touched, as companion-relative POSIX paths. */
+export type ManagedOutputReport = readonly ManagedOutputEntry[];
+
 export interface LaunchPreflightContext {
   companionPath: string;
   config: FrameworkConfig;
   repository?: LinkedRepository;
   providerId: string;
+  /** The session the prepare answers for, so a check can skip what that session does not load. */
+  sessionKind: SessionKind;
 }
 
 /** Provider-agnostic description of an MCP server to register. */
@@ -188,10 +215,17 @@ export interface AgentDefinitionContribution {
   content: string;
 }
 
+/** A Claude Code plugin folder, declared under the `claude` key. Launch-only: never written to a file. */
+export interface PluginDirectoryContribution {
+  /** Absolute path of the folder holding `.claude-plugin/plugin.json`. */
+  path: string;
+}
+
 /**
  * Declarative Agent Runtime contributions of one Capability for one runtime.
  * The runtime's Runtime Surface reconciles these symmetrically: applied while
  * the Capability is enabled, removed when it is not, idempotent across runs.
+ * `pluginDirectories` is the exception: gathered for the launch, written nowhere.
  */
 export interface RuntimeContributions {
   mcpServers?: McpServerDescriptor[];
@@ -201,6 +235,7 @@ export interface RuntimeContributions {
   skillTrees?: SkillTreeContribution[];
   pluginReferences?: PluginReferenceContribution[];
   agentDefinitions?: AgentDefinitionContribution[];
+  pluginDirectories?: PluginDirectoryContribution[];
 }
 
 /**