@uniqbit/mate-core 0.15.4-canary.8 → 0.15.4

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

@@ -1 +1,7 @@
 export const TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES = [".tokensave/"];
+
+// Marker that identifies the tokensave installer's CLAUDE.md append block.
+// Declared here (capability-owned) and consumed by the Claude Runtime Surface
+// when reconciling working-repo files at launch.
+export const TOKENSAVE_CLAUDE_MD_MARKER =
+  "## MANDATORY: No Explore Agents When Tokensave Is Available";

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

@@ -3,29 +3,20 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { resolveGitInfoExcludePath } from "../git-utils";
-import type { CapabilityPlugin } from "../plugin";
-import { isCommandOnPath, runCommand, runShellCommand } from "../utils";
+import type { CapabilityPlugin, RuntimeContributionsByRuntime } from "../plugin";
+import { isCommandOnPath, resolveCommandOnPath, runCommand, runShellCommand } from "../utils";
+import { TOKENSAVE_CLAUDE_MD_MARKER } from "./tokensave-shared";
 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_MIN_RUST_VERSION = "1.91.0";
-const TOKENSAVE_CLAUDE_MD_MARKER = "## MANDATORY: No Explore Agents When Tokensave Is Available";
 const TOKENSAVE_STORE_EXCLUDE_ENTRY = `${TOKENSAVE_STORE_DIR}/`;
 const TOKENSAVE_BREW_INSTALL_CMD = "brew install aovestdipaperino/tap/tokensave";
 const TOKENSAVE_CARGO_INSTALL_CMD = "cargo install --locked tokensave";
 const TOKENSAVE_SCOOP_INSTALL_CMD =
   "scoop bucket add tokensave https://github.com/aovestdipaperino/scoop-bucket && scoop install tokensave";
 
-interface CompanionOpenCodeSettings {
-  mcp?: Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-function getCompanionOpenCodeConfigPath(companionPath: string): string {
-  return path.join(companionPath, ".opencode", "opencode.json");
-}
-
 export interface TokensaveRunResult {
   ok: boolean;
   stderr: string;
@@ -34,10 +25,14 @@ export interface TokensaveRunResult {
 
 export const tokensaveDeps = {
   run(args: string[], cwd: string): TokensaveRunResult {
+    // env is passed explicitly: bun's spawnSync otherwise resolves the binary
+    // against the process's original PATH, ignoring in-process PATH changes
+    // (which test stubs and shell-integration wrappers rely on).
     const result = spawnSync("tokensave", args, {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
     });
     return {
       ok: result.status === 0 && !result.error,
@@ -58,6 +53,7 @@ export const tokensaveDeps = {
     const result = spawnSync("rustc", ["--version"], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
+      env: process.env,
     });
     return {
       ok: result.status === 0 && !result.error,
@@ -73,41 +69,6 @@ export const tokensaveDeps = {
   },
 };
 
-async function readCompanionOpenCodeSettings(
-  companionPath: string,
-): Promise<CompanionOpenCodeSettings> {
-  try {
-    const parsed = JSON.parse(
-      await fs.readFile(getCompanionOpenCodeConfigPath(companionPath), "utf8"),
-    ) as unknown;
-    if (parsed && typeof parsed === "object") {
-      return parsed as CompanionOpenCodeSettings;
-    }
-  } catch {
-    /* absent or malformed */
-  }
-  return {};
-}
-
-async function removeOpenCodeMcpServer(companionPath: string): Promise<void> {
-  const configPath = getCompanionOpenCodeConfigPath(companionPath);
-  const settings = await readCompanionOpenCodeSettings(companionPath);
-  if (!settings.mcp || typeof settings.mcp !== "object") {
-    return;
-  }
-
-  const mcp = { ...settings.mcp };
-  delete mcp.tokensave;
-  if (Object.keys(mcp).length > 0) {
-    settings.mcp = mcp;
-  } else {
-    delete settings.mcp;
-  }
-
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  await fs.writeFile(configPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-}
-
 async function cleanupRepoLocalTokensaveArtifacts(repoPath: string): Promise<void> {
   const claudeMdPath = path.join(repoPath, "CLAUDE.md");
   try {
@@ -314,22 +275,55 @@ export function createTokensavePlugin(): CapabilityPlugin {
         },
       ];
     },
+    // MCP access, session hooks, and permission pre-seeds are declared below
+    // and reconciled by each runtime's Runtime Surface. The bare `tokensave`
+    // command name in the MCP entry is resolved against PATH at spawn time by
+    // each provider, so it never pins a since-moved/upgraded binary.
+    getRuntimeContributions(): RuntimeContributionsByRuntime {
+      const mcpServers = [{ name: "tokensave", command: "tokensave", args: ["serve"] }];
+      // Hook commands pin the resolved binary path (hooks run without the
+      // launch environment's PATH guarantees).
+      const tokensaveCommandPath =
+        resolveCommandOnPath("tokensave", process.env.PATH ?? "") ?? "tokensave";
+      const hookGroups = [
+        {
+          event: "PreToolUse",
+          marker: "tokensave",
+          group: {
+            matcher: "Agent|Grep|Bash",
+            hooks: [
+              { type: "command", command: tokensaveCommandPath, args: ["hook-pre-tool-use"] },
+            ],
+          },
+        },
+        {
+          event: "UserPromptSubmit",
+          marker: "tokensave",
+          group: {
+            hooks: [
+              { type: "command", command: tokensaveCommandPath, args: ["hook-prompt-submit"] },
+            ],
+          },
+        },
+        {
+          event: "Stop",
+          marker: "tokensave",
+          group: {
+            hooks: [{ type: "command", command: tokensaveCommandPath, args: ["hook-stop"] }],
+          },
+        },
+      ];
+      return {
+        claude: { mcpServers, hookGroups, permissionEntries: ["mcp__tokensave__*"] },
+        opencode: { mcpServers },
+      };
+    },
     async apply(ctx) {
       // Presence only: make sure the tokensave binary is installed so the graph can be
       // built later. The graph build itself (init/sync) lives in `mate cap index`, never
       // in setup or launch-time sync — keeping launch fast and indexing an explicit step.
       if (ctx.activeProviders.filter((p) => TOKENSAVE_SUPPORTED_AGENTS.has(p)).length === 0) return;
 
-      // MCP access is provider-mediated: every active hosting provider gets the
-      // server in its native config, and teardown bookkeeping removes it again.
-      // The bare command name is resolved against PATH at spawn time by each
-      // provider, so the registration never pins a since-moved/upgraded binary.
-      await ctx.mcp?.register({
-        name: "tokensave",
-        command: "tokensave",
-        args: ["serve"],
-      });
-
       const targetPath = ctx.repoPath ?? ctx.companionPath;
       if (!(await ensureTokensaveInstalled(targetPath))) {
         return;
@@ -342,20 +336,5 @@ export function createTokensavePlugin(): CapabilityPlugin {
       if (!ctx.repoPath) return;
       await teardownDriver(ctx.repoPath, ctx.activeProviders);
     },
-    forProvider: {
-      claude: {
-        async apply(_ctx) {},
-        async teardown(_ctx) {},
-      },
-      opencode: {
-        // Registration goes through ctx.mcp now. Teardown stays as a legacy
-        // prune for entries written by releases that predate the bookkeeping
-        // manifest.
-        async apply(_ctx) {},
-        async teardown(ctx) {
-          await removeOpenCodeMcpServer(ctx.companionPath);
-        },
-      },
-    },
   };
 }

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

@@ -99,6 +99,35 @@ export async function upsertManagedBlock(
   await fs.writeFile(filePath, existing + (existing ? separator : "") + block, "utf8");
 }
 
+/**
+ * Remove every managed block a plugin owns in `filePath`, except blocks whose
+ * key is in `keepKeys`. Used by contribution reconciliation: current sections
+ * are upserted (content-hashed keys), then stale keys are swept here.
+ */
+export async function removeManagedBlocksForPlugin(
+  filePath: string,
+  frameworkName: string,
+  pluginId: string,
+  keepKeys: Set<string> = new Set(),
+): Promise<void> {
+  let existing: string;
+  try {
+    existing = await fs.readFile(filePath, "utf8");
+  } catch {
+    return;
+  }
+  const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const keyPattern = new RegExp(
+    `<!-- ${escape(frameworkName)}:managed:(${escape(pluginId)}:[0-9a-f]+) start -->`,
+    "g",
+  );
+  const keys = [...existing.matchAll(keyPattern)].map((match) => match[1]);
+  for (const key of keys) {
+    if (keepKeys.has(key)) continue;
+    await removeManagedBlock(filePath, frameworkName, key);
+  }
+}
+
 /** Remove a marker-delimited block if present. No-op when file or block is absent. */
 export async function removeManagedBlock(
   filePath: string,

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

@@ -9,6 +9,7 @@ import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver"
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { PLUGIN_DECLARATION_POLICIES } from "../../../lib/orchestrator/config-store";
 import type { PluginDeclaration } from "../../../lib/orchestrator/types";
+import type { Plugin } from "../plugin";
 import type { PluginRegistry } from "../registry";
 import { loadDynamicPlugin, type DynamicPluginLoadDeps } from "./loader";
 
@@ -89,6 +90,16 @@ function validateDeclaration(entry: unknown): { declaration?: PluginDeclaration;
   return { declaration: entry as unknown as PluginDeclaration };
 }
 
+/**
+ * A framework declaration is the activation switch for a dynamic plugin.
+ * Own-property override rather than a spread: class-instance plugins keep
+ * their prototype members.
+ */
+function activateDeclaredPlugin(plugin: Plugin): Plugin {
+  plugin.isEnabled = () => true;
+  return plugin;
+}
+
 /**
  * Registers the companion's declared plugins into the active registry —
  * compiled-in plugins first (they are already registered), declared order
@@ -135,7 +146,10 @@ export async function hydrateDynamicPlugins(deps: HydrateDynamicPluginsDeps = {}
         );
       }
 
-      registry.register({ plugin: result.plugin, policy: declaration.policy ?? "optional" });
+      registry.register({
+        plugin: activateDeclaredPlugin(result.plugin),
+        policy: declaration.policy ?? "optional",
+      });
       hydratedPackages.add(declaration.package);
     }
   } catch (error) {

package/src/tools/setup/engine.ts

@@ -1,8 +1,17 @@
+// oxlint-disable no-await-in-loop
 import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
 import type { FrameworkConfig } from "../../lib/orchestrator/types";
 import { collectHostingProviders, ContextServiceMediator } from "./context-services";
-import type { CapabilityPlugin, Plugin, PluginRegistration, SetupContext } from "./plugin";
+import type {
+  CapabilityContributionInput,
+  CapabilityPlugin,
+  Plugin,
+  PluginRegistration,
+  SetupContext,
+} from "./plugin";
+import { reconcileClaudeContributions } from "./providers/claude";
+import { reconcileOpenCodeContributions } from "./providers/opencode";
 import { normalizeRegistration, type NormalizedRegistration } from "./registry";
 
 export interface SetupInstallationPlanAction {
@@ -117,6 +126,8 @@ export async function executeSetupInstallationPlan(
   });
 
   for (const action of plan.actions) {
+    if (ctx.scope === "hub" && action.phase !== "provider") continue;
+
     const plugin = pluginById.get(action.pluginId);
     if (!plugin) {
       continue;
@@ -151,5 +162,61 @@ export async function executeSetupInstallationPlan(
 
   await mediator.finalize();
 
+  await reconcileCapabilityContributions(ctx, plugins, plan);
+
   return { executedActions, skippedActions, warnings };
 }
+
+// The Runtime Surface of each active Agent Runtime, by runtime id.
+const RUNTIME_SURFACE_RECONCILERS: Record<
+  string,
+  (ctx: SetupContext, inputs: CapabilityContributionInput[]) => Promise<void>
+> = {
+  claude: reconcileClaudeContributions,
+  opencode: reconcileOpenCodeContributions,
+};
+
+/**
+ * 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.
+ */
+async function reconcileCapabilityContributions(
+  ctx: SetupContext,
+  plugins: Plugin[],
+  plan: SetupInstallationPlan,
+): Promise<void> {
+  // The plan already resolved enablement (policy, saved selection, package
+  // manager requirements); mirror it instead of recomputing.
+  const enabledByPluginId = new Map(
+    plan.actions
+      .filter((action) => action.phase === "capability" && action.providerId === undefined)
+      .map((action) => [action.pluginId, action.action === "apply"]),
+  );
+
+  const inputsByRuntime = new Map<string, CapabilityContributionInput[]>();
+  for (const plugin of plugins) {
+    if (plugin.kind !== "capability") continue;
+    const capability = plugin as CapabilityPlugin;
+    if (!capability.getRuntimeContributions) continue;
+    const enabled = enabledByPluginId.get(capability.id) ?? false;
+    const byRuntime = await capability.getRuntimeContributions(ctx);
+    for (const [runtimeId, contributions] of Object.entries(byRuntime)) {
+      if (!contributions) continue;
+      // Inactive runtimes still reconcile — with everything disabled — so a
+      // deselected runtime's managed entries (skill trees, guidance blocks)
+      // are torn down. The surfaces never create files for disabled inputs.
+      const runtimeActive = plan.activeProviders.includes(runtimeId);
+      const inputs = inputsByRuntime.get(runtimeId) ?? [];
+      inputs.push({ pluginId: capability.id, enabled: enabled && runtimeActive, contributions });
+      inputsByRuntime.set(runtimeId, inputs);
+    }
+  }
+
+  for (const [runtimeId, inputs] of inputsByRuntime) {
+    const reconcile = RUNTIME_SURFACE_RECONCILERS[runtimeId];
+    if (!reconcile || inputs.length === 0) continue;
+    await reconcile(ctx, inputs);
+  }
+}

package/src/tools/setup/mate.ts

@@ -4,7 +4,12 @@ import path from "node:path";
 import { pruneEmptyAncestors } from "./utils";
 
 export const MATE_ARTIFACT_SKILLS = ["mate-artifact-finish"] as const;
-export const MATE_SKILLS = ["mate-artifact-finish", "mate-create-report"] as const;
+export const MATE_SKILLS = [
+  "mate-artifact-finish",
+  "mate-create-report",
+  "mate-openspec-backfill",
+] as const;
+const LEGACY_MATE_SKILLS = ["mate-openspec-artifact-finish"] as const;
 
 const MATE_SKILLS_SOURCE = path.join(
   import.meta.dirname,
@@ -98,6 +103,9 @@ async function resolveMateSkillSource(skill: string, tool: string): Promise<stri
 }
 
 export async function applyMateSkills(skillsDir: string, tool: string): Promise<void> {
+  for (const skill of LEGACY_MATE_SKILLS) {
+    await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
+  }
   for (const skill of MATE_SKILLS) {
     const destination = path.join(skillsDir, skill);
     if (skill === "mate-create-report") {
@@ -110,7 +118,7 @@ export async function applyMateSkills(skillsDir: string, tool: string): Promise<
 }
 
 export async function teardownMateSkills(skillsDir: string, companionPath: string): Promise<void> {
-  for (const skill of MATE_SKILLS) {
+  for (const skill of [...MATE_SKILLS, ...LEGACY_MATE_SKILLS]) {
     try {
       await fs.rm(path.join(skillsDir, skill), { recursive: true, force: true });
     } catch {

package/src/tools/setup/plugin.ts

@@ -1,11 +1,16 @@
 import type { FrameworkConfig, LinkedRepository } from "../../lib/orchestrator/types";
 import type { InstallRequirement, InstallRequirementContext } from "./install-contract";
+import type { ClaudeHookGroup } from "./providers/claude-format";
+
+export type SetupScope = "companion" | "hub";
 
 export interface SetupContext {
   companionPath: string;
   config: FrameworkConfig;
   mode: "setup" | "sync";
   activeProviders: string[];
+  /** Hub setup runs providers but excludes companion-only surfaces. */
+  scope?: SetupScope;
   /** Working repository path when syncing from a linked repo (e.g. during launch). */
   repoPath?: string;
   /**
@@ -112,9 +117,109 @@ export type PluginPolicy = "required" | "default" | "optional";
  */
 export type PluginRegistration = Plugin | { plugin: Plugin; policy: PluginPolicy };
 
+/**
+ * A hook group a Capability contributes to a runtime's settings. `marker` is
+ * the command substring that identifies the group as Mate-managed (D4 marker
+ * scheme): reconciliation strips every group whose command contains any
+ * declared marker before re-adding the groups of enabled Capabilities.
+ */
+export interface HookGroupContribution {
+  event: string;
+  marker: string;
+  group: ClaudeHookGroup;
+}
+
+/** A skill directory copied into `<runtime dir>/skills/<name>`. */
+export interface SkillTreeContribution {
+  name: string;
+  sourceDir: string;
+}
+
+/**
+ * A managed guidance section in the runtime's agent instruction file
+ * (CLAUDE.md / AGENTS.md). Reconciled as a framework-managed block; on
+ * teardown a section in a file shared with another active runtime is only
+ * stripped together with the last runtime using that file.
+ */
+export interface GuidanceSectionContribution {
+  content: string;
+}
+
+/**
+ * A plugin reference entry in the runtime's config (OpenCode `plugin` array).
+ * `isManagedReference` identifies entries this contribution owns so stale
+ * variants (e.g. older pins) are replaced and teardown removes only them.
+ */
+export interface PluginReferenceContribution {
+  reference: string;
+  isManagedReference(entry: unknown): boolean;
+  /** Config files to reconcile, relative to the runtime dir. Defaults to both OpenCode configs. */
+  configFiles?: string[];
+}
+
+/**
+ * A real, provider-native agent definition file, written to
+ * `<runtime dir>/agents/<name>.md` and selectable via `--agent <name>`.
+ * Unlike a guidance section, the whole file is managed content (no merge with
+ * unmanaged text) — the Capability pre-renders `content` per runtime, since
+ * frontmatter shape (Claude's `name`/`hidden`, OpenCode's `mode`) differs.
+ * Reconciled in both companion and hub scope: an agent definition is exactly
+ * the kind of artifact a repo-less hub needs.
+ */
+export interface AgentDefinitionContribution {
+  /** Agent name; the file is written to `<runtime dir>/agents/<name>.md`. */
+  name: string;
+  /** Full file content, including frontmatter, ready to write as-is. */
+  content: 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.
+ */
+export interface RuntimeContributions {
+  mcpServers?: McpServerDescriptor[];
+  hookGroups?: HookGroupContribution[];
+  permissionEntries?: string[];
+  guidanceSections?: GuidanceSectionContribution[];
+  skillTrees?: SkillTreeContribution[];
+  pluginReferences?: PluginReferenceContribution[];
+  agentDefinitions?: AgentDefinitionContribution[];
+}
+
+/**
+ * Contributions keyed by runtime id ("claude", "opencode"). Keyed-by-runtime
+ * because the payload shapes are runtime-specific (hook groups are
+ * Claude-shaped, plugin references OpenCode-shaped); a runtime-agnostic
+ * declaration would only push translation into every capability.
+ */
+export type RuntimeContributionsByRuntime = Partial<Record<string, RuntimeContributions>>;
+
+/**
+ * One Capability's contributions for one runtime, as handed to that runtime's
+ * Runtime Surface reconciliation. Disabled Capabilities participate too: their
+ * declarations define the managed entries to strip.
+ */
+export interface CapabilityContributionInput {
+  pluginId: string;
+  enabled: boolean;
+  contributions: RuntimeContributions;
+}
+
 export interface CapabilityPlugin extends Plugin {
   kind: "capability";
   requires?: { packageManagers: string[] };
+  /**
+   * Declare Agent Runtime contributions as data. Called on every setup/sync
+   * pass for all registered Capabilities — enabled ones contribute their
+   * entries, disabled ones only widen the managed strip set so their previous
+   * entries are removed. May be async (e.g. reading a companion-local
+   * override file) — the engine always awaits the result.
+   */
+  getRuntimeContributions?(
+    ctx: SetupContext,
+  ): RuntimeContributionsByRuntime | Promise<RuntimeContributionsByRuntime>;
   forProvider?: Record<
     string,
     {

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

@@ -61,12 +61,15 @@ export async function writeManagedGitignoreBlock(
 
 export function collectManagedGitignoreEntries(ctx: SetupContext, plugins: Plugin[]): string[] {
   // Baseline for every companion: node_modules never versions wherever a tool
-  // materializes it, and everything directly under the dependencies tree
-  // (context-mode, future consumers) is regenerated by setup/install —
-  // version pins live in .mate/config and in code, never in the tree itself.
+  // materializes it, and the machine-local distribution-dependencies workspace
+  // (.mate/plugins/.local/ — context-mode, future consumers) is regenerated by
+  // setup/install in full — version pins live in .mate/config and in code,
+  // never in the tree itself. This is distinct from the committed dynamic-
+  // plugins workspace at .mate/plugins/, whose package.json and lockfile stay
+  // trackable.
   const entries = [
     "node_modules/",
-    `.${FRAMEWORK_NAME}/dependencies/*`,
+    `.${FRAMEWORK_NAME}/plugins/.local/`,
     ".mcp.json*",
     ...plugins
       .filter((p) => p.kind !== "root" && (p.isEnabled(ctx.config) || p.persistGitignoreEntries))

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

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
-import { removeGraphifySection } from "../capabilities/graphify";
+import { removeGraphifySection } from "../capabilities/graphify-shared";
 
 // Marker names derive from the framework identity, never the invocation name.
 const upperName = () => FRAMEWORK_NAME.toUpperCase();

package/src/tools/setup/providers/agent-file-sections.ts

@@ -0,0 +1,78 @@
+// Shared markdown section primitives for agent instruction files (CLAUDE.md,
+// AGENTS.md), plus a thin file-level wrapper for stripping sections in place.
+
+import fs from "node:fs/promises";
+
+export interface RemoveHeadingSectionOptions {
+  /** Matches the heading line that opens the section to remove. */
+  isHeading(line: string): boolean;
+  /** Exact lines (e.g. HTML comment markers) stripped wherever they appear. */
+  markerLines?: string[];
+}
+
+/**
+ * Remove a heading-delimited section (heading line up to the next `#`/`##`
+ * heading or EOF), collapsing leftover blank runs. Marker lines are stripped
+ * even when no section heading is present.
+ */
+export function removeHeadingSection(
+  content: string,
+  options: RemoveHeadingSectionOptions,
+): string {
+  const markerLines = new Set(options.markerLines ?? []);
+  const normalizedLines = content.split("\n").filter((line) => !markerLines.has(line));
+
+  const start = normalizedLines.findIndex(options.isHeading);
+  if (start === -1) {
+    const strippedMarkersOnly = normalizedLines.join("\n");
+    return strippedMarkersOnly === content ? content : strippedMarkersOnly;
+  }
+
+  let end = normalizedLines.length;
+  for (let i = start + 1; i < normalizedLines.length; i++) {
+    if (normalizedLines[i].startsWith("## ") || normalizedLines[i].startsWith("# ")) {
+      end = i;
+      break;
+    }
+  }
+
+  const remaining = [...normalizedLines.slice(0, start), ...normalizedLines.slice(end)].join("\n");
+  const collapsed = remaining.replace(/\n{3,}/g, "\n\n").trim();
+  return collapsed ? collapsed + "\n" : "";
+}
+
+/**
+ * Cut everything from `marker` to EOF. Returns the content unchanged when the
+ * marker is absent, and "" when nothing but whitespace precedes it (callers
+ * typically delete the file then).
+ */
+export function cutFromMarker(content: string, marker: string): string {
+  const idx = content.indexOf(marker);
+  if (idx === -1) return content;
+
+  const before = content.slice(0, idx).replace(/\s+$/, "");
+  return before.length > 0 ? before + "\n" : "";
+}
+
+/**
+ * Strip a heading-delimited section from a file in place. Absent files are a
+ * no-op; a file left without content is deleted.
+ */
+export async function stripSectionFromFile(
+  filePath: string,
+  options: RemoveHeadingSectionOptions,
+): Promise<void> {
+  let content: string;
+  try {
+    content = await fs.readFile(filePath, "utf8");
+  } catch {
+    return;
+  }
+  const stripped = removeHeadingSection(content, options);
+  if (stripped === content) return;
+  if (!stripped.trim()) {
+    await fs.unlink(filePath);
+  } else {
+    await fs.writeFile(filePath, stripped, "utf8");
+  }
+}