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

package/src/lib/orchestrator/launcher.ts

@@ -1,28 +1,13 @@
 // oxlint-disable no-underscore-dangle
-import { syncCompanionFiles } from "../../tools/setup";
-import { getActiveDistribution } from "../../distribution";
 import { FRAMEWORK_NAME } from "../../framework";
-import type { CapabilityPlugin, LaunchPreflightContext } from "../../tools/setup/plugin";
-import type { LaunchAdapter, AdapterContext } from "./adapters/base";
+import type { AdapterContext, LaunchAdapter } from "./adapters/base";
 import { ClaudeAdapter } from "./adapters/claude";
 import { OpenCodeAdapter } from "./adapters/opencode";
-import { CompanionStore } from "./companion-store";
-import { syncCompanionGit } from "./companion-git-sync";
+import { CompanionStore } from "./repository-link";
 import { resolveForLaunch, type LaunchContext } from "./framework-context";
-import {
-  firstFailure,
-  type ProjectionEntryOutcome,
-  type ProjectionInput,
-  type ProjectionResult,
-} from "./projection-types";
-import {
-  isWorkingRepositoryWrapped,
-  project,
-  projectWorkingRepositoryBestEffort,
-} from "./working-repo-projection";
+import { prepareSession, type PrepareResult, type PrepareRuntime } from "./session-prepare";
 import {
   RepositoryNotSelectedError,
-  LaunchPreflightError,
   ToolNotAllowedError,
   type FrameworkConfig,
   type LaunchRequest,
@@ -53,60 +38,27 @@ interface ResolvedLaunchState {
 }
 
 export const launcherDeps = {
-  syncCompanionFiles,
-  /** The Managed Projection's launch scope; the working repo is written only here. */
-  projectWorkingRepo: (input: ProjectionInput) => project("launch", input),
-  /**
-   * The Projection Root a launch guarantees for itself. `resolveForLaunch` also
-   * writes it, but only on the branch that resolved a companion from the
-   * Working Repository; asking here makes the guarantee independent of which
-   * branch answered. Best-effort — a launch carries its own configuration.
-   */
-  refreshProjectionRoot: projectWorkingRepositoryBestEffort,
-  syncCompanionGit,
-  isWrapped: isWorkingRepositoryWrapped,
+  prepareSession,
 };
 
-/**
- * A wrapped Working Repository delivers the companion to sessions the operator
- * starts themselves, through documents the Agent Runtime discovers by its own
- * upward walk. A Managed Session loads those *and* everything the launch
- * injects through `--settings`, `--mcp-config` and `--plugin-dir`, which
- * ADR-014 established can never be withdrawn. Two delivery channels that cannot
- * be merged must therefore not both be live for one repository, so wrapping and
- * launching are exclusive rather than reconciled (ADR-015, superseding
- * ADR-014's judgement that the duplication is bounded enough to accept).
- *
- * Raised before every write the launch itself performs: the companion Git sync,
- * the companion file sync, the launch scope's projection and the runtime
- * invocation. Companion resolution has already refreshed the Projection Root by
- * this point — `resolveForLaunch` writes it while resolving — but that write is
- * idempotent and byte-identical to the one `mate wrap` performs, so it cannot
- * change what the repository holds.
- */
-function wrappedRepositoryRefusal(repository: LinkedRepository): string {
-  return [
-    `${FRAMEWORK_NAME}: ${repository.id} is wrapped — \`${FRAMEWORK_NAME} claude\` and \`${FRAMEWORK_NAME} opencode\` do not run in a wrapped working repository.`,
-    "Start the session yourself: `claude` or `opencode` — the wrap delivers the companion guidance.",
-    `Or restore managed launches: \`${FRAMEWORK_NAME} unwrap\`.`,
-  ].join("\n");
-}
-
-/**
- * The shape `projectWorkingRepositoryBestEffort` reports a failed projection
- * in, narrowed to the entry that failed: the launch scope writes several, so
- * "the projection" alone would not tell the operator what to fix.
- */
-function projectionFailure(outcome: ProjectionEntryOutcome, repository: LinkedRepository): string {
-  const error = outcome.error ?? new Error("projection failed");
-  return `failed to write ${outcome.path} for ${repository.id}: ${error.message}`;
+/** The wrap notice is informational: `process.stderr.write`, since Bun renders `console.error` red. */
+function report(result: PrepareResult): void {
+  const wrapped = result.steps.find((step) => step.step === "working-target");
+  if (wrapped?.outcome === "ok" && wrapped.detail !== "current") {
+    const runtime = wrapped.runtimes?.includes("claude") ? "Claude" : "OpenCode";
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: wrapped ${result.repositoryId} for ${runtime}: ${wrapped.detail}\n`,
+    );
+  }
+  for (const warning of result.warnings) {
+    console.error(`${FRAMEWORK_NAME}: warning: ${warning}`);
+  }
 }
 
 export class FrameworkLauncher {
-  private readonly adapters = new Map<string, LaunchAdapter>([
-    ["claude", new ClaudeAdapter()],
-    ["opencode", new OpenCodeAdapter()],
-  ]);
+  private readonly adapters = new Map<string, LaunchAdapter>(
+    [new ClaudeAdapter(), new OpenCodeAdapter()].map((adapter) => [adapter.toolName, adapter]),
+  );
 
   async resolveLaunchPreview(request: LaunchRequest): Promise<LaunchPreview> {
     const state = await this.resolveLaunchState(request);
@@ -119,42 +71,25 @@ export class FrameworkLauncher {
     };
   }
 
+  /**
+   * Session Prepare in its attended mode, then the adapter's share: it words a
+   * failed prepare, plans what the launch delivers, and runs its own checks.
+   * Each launch's plan travels in its own context, never on the adapter.
+   */
   async prepare(request: LaunchRequest): Promise<PreparedLaunch> {
     const state = await this.resolveLaunchState(request);
-    const adapterContext = this.makeAdapterContext(state);
 
-    if (state.repository && (await launcherDeps.isWrapped(state.repository.path))) {
-      throw new LaunchPreflightError(wrappedRepositoryRefusal(state.repository));
-    }
-
-    if (!request.skipGit && state.config.git === "auto") {
-      await launcherDeps.syncCompanionGit(
-        state.companionPath,
-        state.repository?.path,
-        request.interactiveGit ?? false,
-      );
-    }
-    if (state.repository) {
-      await launcherDeps.syncCompanionFiles(
-        state.companionPath,
-        state.config,
-        state.repository.path,
-      );
-    } else {
-      await launcherDeps.syncCompanionFiles(state.companionPath, state.config);
-    }
-    if (state.repository) {
-      this.answerForProjection(
-        await launcherDeps.projectWorkingRepo({
-          repoPath: state.repository.path,
-          companionPath: state.companionPath,
-          config: state.config,
-        }),
-        state.repository,
-      );
-      await launcherDeps.refreshProjectionRoot(state.companionPath, state.repository);
-    }
-    await this.runCapabilityPreflight(state, request.tool);
+    const prepared = await launcherDeps.prepareSession({
+      runtime: request.tool as PrepareRuntime,
+      companionPath: state.companionPath,
+      repository: state.repository,
+      mode: "attended",
+      config: state.config,
+      skipGit: state.skipGit,
+    });
+    report(prepared);
+    if (!prepared.ok) throw state.adapter.launchFailure(prepared);
+    const adapterContext = await state.adapter.planLaunch(this.makeAdapterContext(state), prepared);
     await state.adapter.validateLaunch(adapterContext);
 
     return {
@@ -174,7 +109,7 @@ export class FrameworkLauncher {
       repositoryId,
       repository: localRepository,
     } = await this.resolveConfig(request.scope);
-    const store = new CompanionStore(configStore, workingRepoStore);
+    const store = new CompanionStore(companionPath, workingRepoStore);
     const scope = request.scope ?? "working-repo";
     const repository =
       scope === "companion"
@@ -205,28 +140,6 @@ export class FrameworkLauncher {
     };
   }
 
-  /**
-   * `project` reports its failures rather than throwing, so the launch scope's
-   * caller is the one that has to answer for them. A non-degradable entry is a
-   * guardrail the session was promised — writing the companion into the
-   * runtime's allow-list, for one — so the launch fails instead of starting
-   * without it. A degradable entry warns in the voice
-   * {@link projectWorkingRepositoryBestEffort} uses, and the launch proceeds.
-   */
-  private answerForProjection(result: ProjectionResult, repository: LinkedRepository): void {
-    for (const outcome of result.outcomes) {
-      if (outcome.state !== "failed" || !outcome.degradable) continue;
-      console.error(`${FRAMEWORK_NAME}: warning: ${projectionFailure(outcome, repository)}`);
-    }
-
-    const failure = firstFailure(result.outcomes);
-    if (failure) {
-      throw new LaunchPreflightError(
-        `${FRAMEWORK_NAME}: ${projectionFailure(failure, repository)}`,
-      );
-    }
-  }
-
   private makeAdapterContext(state: ResolvedLaunchState): AdapterContext {
     return {
       repository: state.repository,
@@ -239,54 +152,6 @@ export class FrameworkLauncher {
     };
   }
 
-  private async runCapabilityPreflight(
-    state: ResolvedLaunchState,
-    providerId: string,
-  ): Promise<void> {
-    const context: LaunchPreflightContext = {
-      companionPath: state.companionPath,
-      config: state.config,
-      repository: state.repository,
-      providerId,
-    };
-    const preflights = getActiveDistribution()
-      .registry.getAll()
-      .reduce<
-        Array<{
-          capability: CapabilityPlugin;
-          preflight: NonNullable<NonNullable<CapabilityPlugin["forProvider"]>[string]["preflight"]>;
-        }>
-      >((entries, plugin) => {
-        if (plugin.kind !== "capability" || !plugin.isEnabled(state.config)) return entries;
-        const capability = plugin as CapabilityPlugin;
-        const preflight = capability.forProvider?.[providerId]?.preflight;
-        if (preflight) entries.push({ capability, preflight });
-        return entries;
-      }, []);
-    const results = await Promise.all(
-      preflights.map(async ({ capability, preflight }) => {
-        try {
-          return await preflight(context);
-        } catch (error) {
-          const detail = error instanceof Error ? error.message : String(error);
-          throw new LaunchPreflightError(
-            `Capability preflight failed for ${capability.id} on ${providerId}: ${detail}`,
-            { cause: error },
-          );
-        }
-      }),
-    );
-    const diagnostics = results.flat();
-
-    if (diagnostics.length > 0) {
-      throw new LaunchPreflightError(
-        ["Capability launch preflight failed.", ...diagnostics.map((item) => `- ${item}`)].join(
-          "\n",
-        ),
-      );
-    }
-  }
-
   private async resolveConfig(scope: LaunchScope = "working-repo"): Promise<LaunchContext> {
     return resolveForLaunch(process.cwd(), undefined, scope);
   }

package/src/lib/orchestrator/projection-claude-entry.ts

@@ -11,6 +11,7 @@ import {
   type ClaudeSettings,
 } from "../../tools/setup/providers/claude-format";
 import { isMateGuardHookGroup } from "../../tools/setup/providers/claude-plugin-hooks";
+import { readWrapState, type WrapState } from "../../runtime/wrap-state";
 import { pruneEmptyAncestors } from "../../tools/setup/utils";
 import { GlobalConfigStore } from "./global-config-store";
 
@@ -52,14 +53,21 @@ function parseSettings(raw: string | null): ClaudeSettings {
 }
 
 /**
- * Strips the managed hook groups earlier releases wrote here, but leaves the
- * guard group the `wrap` scope places: that one is managed by another entry,
- * and stripping it would disarm every Unmanaged Session on the next launch.
+ * Strips the managed hook groups earlier releases wrote here, but leaves every
+ * group the `wrap` scope places: those are owned by the wrap's own entry —
+ * Capability groups match a managed marker too — and stripping them would
+ * disarm every Unmanaged Session on the next launch.
  */
-function withoutForeignManagedHookGroups(settings: ClaudeSettings): ClaudeSettings {
+function withoutForeignManagedHookGroups(
+  settings: ClaudeSettings,
+  wrap: WrapState,
+): ClaudeSettings {
   const hooks = filterClaudeHookGroups(
     settings.hooks ?? {},
-    (group) => isMateGuardHookGroup(group) || !isManagedHookGroup(group),
+    (group) =>
+      isMateGuardHookGroup(group) ||
+      wrap.carriesClaudeHookGroup(group) ||
+      !isManagedHookGroup(group),
   );
   const next = { ...settings };
   if (Object.keys(hooks).length > 0) next.hooks = hooks;
@@ -81,7 +89,10 @@ export async function syncWorkingRepoClaudeAdditionalDirectories(
 ): Promise<"written" | "current"> {
   const target = settingsPath(repoPath);
   const raw = await readRaw(target);
-  const existing = withoutForeignManagedHookGroups(parseSettings(raw));
+  const existing = withoutForeignManagedHookGroups(
+    parseSettings(raw),
+    await readWrapState(repoPath),
+  );
   const permissions = { ...existing.permissions };
   const existingAdditionalDirectories = Array.isArray(permissions.additionalDirectories)
     ? permissions.additionalDirectories

package/src/lib/orchestrator/projection-claude-skills.ts

@@ -2,10 +2,23 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { readProjectionFile } from "../../runtime/projection";
+import { realLinkTarget, realOrResolved } from "../fs-utils";
+import {
+  links,
+  readManifest,
+  updateManifest,
+  withLinks,
+  type LinkRecord,
+} from "../../runtime/runtime-document-manifest";
 import { pruneEmptyAncestors } from "../../tools/setup/utils";
 
 const CLAUDE_SKILLS_PATH = path.join(".claude", "skills");
 
+/** The manifest key of a skill link: repo-relative, POSIX separators. */
+function recordKey(name: string): string {
+  return `.claude/skills/${name}`;
+}
+
 async function skillNames(root: string): Promise<string[]> {
   const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
   const names: string[] = [];
@@ -25,13 +38,7 @@ async function skillNames(root: string): Promise<string[]> {
 
 async function linkTarget(link: string): Promise<string | null> {
   const target = await fs.readlink(link).catch(() => null);
-  return target === null ? null : path.resolve(path.dirname(link), target);
-}
-
-async function isManagedSkillLink(link: string, roots: string[]): Promise<boolean> {
-  const target = await linkTarget(link);
-  if (target === null) return false;
-  return roots.some((root) => path.dirname(target) === root);
+  return target === null ? null : realLinkTarget(link, target);
 }
 
 async function registeredSkillRoots(
@@ -45,17 +52,23 @@ async function registeredSkillRoots(
     companionPath ?? "",
     projection?.projection.companionPath ?? "",
   ];
-  return [
-    ...new Set(
-      candidates.filter(Boolean).map((candidate) => path.resolve(candidate, CLAUDE_SKILLS_PATH)),
-    ),
-  ];
+  const roots = await Promise.all(
+    candidates
+      .filter(Boolean)
+      .map((candidate) => realOrResolved(path.resolve(candidate, CLAUDE_SKILLS_PATH))),
+  );
+  return [...new Set(roots)];
 }
 
 async function createSkillLink(target: string, link: string): Promise<void> {
   await fs.symlink(target, link, process.platform === "win32" ? "junction" : "dir");
 }
 
+/**
+ * Recorded link: Mate's while it resolves to its recorded target. Unrecorded:
+ * adopted only when it resolves into a registered, current or projected
+ * companion. Records follow the filesystem, so a partial failure re-adopts.
+ */
 export async function reconcileWorkingRepoClaudeSkillLinks(
   repoPath: string,
   companionPath: string | null,
@@ -65,23 +78,27 @@ export async function reconcileWorkingRepoClaudeSkillLinks(
   const currentRoot = companionPath ? path.resolve(companionPath, CLAUDE_SKILLS_PATH) : null;
   const roots = await registeredSkillRoots(repoPath, companionPath, registeredCompanionPaths);
   const targetRoot = path.join(path.resolve(repoPath), CLAUDE_SKILLS_PATH);
+  const recorded = links(await readManifest(repoPath), "claude");
   const existing = await fs.readdir(targetRoot, { withFileTypes: true }).catch(() => []);
   const sourceNames: Set<string> =
     currentRoot && enabled ? new Set(await skillNames(currentRoot)) : new Set<string>();
+  const records: Record<string, LinkRecord> = {};
   let changed = false;
 
   for (const entry of existing) {
     if (!entry.isSymbolicLink()) continue;
     const link = path.join(targetRoot, entry.name);
-    if (!(await isManagedSkillLink(link, roots))) continue;
-
     const target = await linkTarget(link);
-    if (
-      currentRoot &&
-      enabled &&
-      target === path.join(currentRoot, entry.name) &&
-      sourceNames.has(entry.name)
-    ) {
+    if (target === null) continue;
+    const record = recorded[recordKey(entry.name)];
+    const owned = record
+      ? (await realOrResolved(record.target)) === target
+      : roots.some((root) => path.dirname(target) === root);
+    if (!owned) continue;
+
+    const wanted = currentRoot ? path.join(currentRoot, entry.name) : null;
+    if (wanted && sourceNames.has(entry.name) && (await realOrResolved(wanted)) === target) {
+      records[recordKey(entry.name)] = { runtime: "claude", target: wanted };
       continue;
     }
 
@@ -89,13 +106,15 @@ export async function reconcileWorkingRepoClaudeSkillLinks(
     changed = true;
   }
 
-  if (currentRoot && enabled && sourceNames.size > 0) {
+  if (currentRoot && sourceNames.size > 0) {
     await fs.mkdir(targetRoot, { recursive: true });
     for (const name of sourceNames) {
       const link = path.join(targetRoot, name);
       const existingLink = await fs.lstat(link).catch(() => null);
       if (existingLink) continue;
-      await createSkillLink(path.join(currentRoot, name), link);
+      const target = path.join(currentRoot, name);
+      await createSkillLink(target, link);
+      records[recordKey(name)] = { runtime: "claude", target };
       changed = true;
     }
   }
@@ -103,9 +122,22 @@ export async function reconcileWorkingRepoClaudeSkillLinks(
   if (changed || !enabled) {
     await pruneEmptyAncestors(targetRoot, path.resolve(repoPath));
   }
+  if (JSON.stringify(sortedEntries(records)) !== JSON.stringify(sortedEntries(recorded))) {
+    await updateManifest(repoPath, (manifest) => withLinks(manifest, "claude", records));
+    changed = true;
+  }
   return changed ? "written" : "current";
 }
 
+function sortedEntries(records: Record<string, LinkRecord>): [string, LinkRecord][] {
+  return Object.entries(records)
+    .map(([key, record]): [string, LinkRecord] => [
+      key,
+      { runtime: record.runtime, target: record.target },
+    ])
+    .toSorted(([a], [b]) => a.localeCompare(b));
+}
+
 export async function removeWorkingRepoClaudeSkillLinks(
   repoPath: string,
   registeredCompanionPaths: string[] = [],

package/src/lib/orchestrator/projection-entries.ts

@@ -13,6 +13,11 @@ import {
   repoLocalDirPath,
   repoLocalRegistryPath,
 } from "../../runtime/repo-local";
+import {
+  documentRuntime,
+  documents as recordedDocuments,
+  readManifest,
+} from "../../runtime/runtime-document-manifest";
 import { TOKENSAVE_WORKING_REPO_EXCLUDE_ENTRIES } from "../../tools/setup/capabilities/tokensave-shared";
 import {
   ensureWorkingRepoLocalExcludes,
@@ -26,6 +31,12 @@ import {
   reconcileWorkingRepoClaudeSkillLinks,
   removeWorkingRepoClaudeSkillLinks,
 } from "./projection-claude-skills";
+import {
+  companionCopiesPresent,
+  reconcileCompanionCopies,
+  removeCompanionCopies,
+  withdrawCompanionCopies,
+} from "./projection-opencode-copies";
 import { buildProjection } from "./projection-record";
 import {
   CLAUDE_WORKING_SETTINGS_PATH,
@@ -41,16 +52,22 @@ import {
   CLAUDE_MCP_DOCUMENT,
   CLAUDE_SETTINGS_DOCUMENT,
   OPENCODE_CONFIG_DOCUMENT,
+  isExternalDocument,
   placeRuntimeDocument,
   removeRuntimeDocument,
-  runtimeDocumentPresent,
+  trackedDocumentWarnings,
 } from "./projection-runtime-documents";
 import {
   upsertRepoLocalCompanionPointer,
   upsertRepoLocalLinkedRepository,
   writeRepoLocalFrameworkConfig,
 } from "./repo-local-store";
-import type { ProjectionEntry, ProjectionInput } from "./projection-types";
+import type {
+  ProjectionEntry,
+  ProjectionInput,
+  ProjectionWriteReport,
+  ProjectionWriteState,
+} from "./projection-types";
 
 const WORKSPACE_DOCUMENT_FILE = "workspace.code-workspace";
 
@@ -68,6 +85,11 @@ async function pathExists(candidatePath: string): Promise<boolean> {
   }
 }
 
+/** Present when Mate recorded regions for it, not merely when the file exists. */
+async function runtimeDocumentRecorded(repoPath: string, documentPath: string): Promise<boolean> {
+  return recordedDocuments(await readManifest(repoPath)).includes(documentPath);
+}
+
 async function writeProjectionPairEntry(input: ProjectionInput): Promise<"written" | "current"> {
   const { companionPath, repository } = input;
   const resolvedCompanionPath = path.resolve(companionPath!);
@@ -96,6 +118,26 @@ async function writeProjectionPairEntry(input: ProjectionInput): Promise<"writte
   return "written";
 }
 
+/**
+ * Places one rendered document and, when this pass wrote Mate's regions into a
+ * file inside the repository, asks Git whether it tracks that file. Only a
+ * write is worth the question: an unchanged document was reported when it was
+ * written, and a removal puts no companion path into it.
+ */
+async function writeRuntimeDocumentEntry(
+  input: ProjectionInput,
+  documentPath: string,
+): Promise<ProjectionWriteState | ProjectionWriteReport> {
+  const state = await placeRuntimeDocument(input.repoPath, documentPath, input.runtimeDocuments);
+  const rendered = input.runtimeDocuments?.some((document) => document.path === documentPath);
+  if (state !== "written" || !rendered || isExternalDocument(documentPath)) return state;
+  const repositoryId = input.repository?.id ?? path.basename(path.resolve(input.repoPath));
+  return {
+    state,
+    warnings: await trackedDocumentWarnings(input.repoPath, documentPath, repositoryId),
+  };
+}
+
 function tokensaveEnabled(input: ProjectionInput): boolean {
   return (input.config?.capabilities ?? []).some((capability) => capability.name === "tokensave");
 }
@@ -198,7 +240,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       id: "projection-pair",
       kind: "owned",
       path: path.join(localDir, PROJECTION_YAML_FILE),
-      scopes: ["session"],
+      scopes: ["session", "wrap"],
       write: async (input) =>
         input.companionPath && input.repository ? writeProjectionPairEntry(input) : "skipped",
       removal: { by: "entry", entry: "projection-root" },
@@ -208,6 +250,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       kind: "merged",
       path: path.join(".claude", "skills"),
       scopes: ["wrap"],
+      runtime: "claude",
       removeOnUnwrap: true,
       write: async (input) => {
         if (!input.config) return "skipped";
@@ -236,7 +279,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       id: "capability-excludes",
       kind: "merged",
       path: path.join(".git", "info", "exclude"),
-      scopes: ["launch"],
+      scopes: ["launch", "wrap"],
       write: async (input) => {
         if (!input.config) return "skipped";
         return (await reconcileWorkingRepoCapabilityExcludes(
@@ -259,6 +302,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       kind: "merged",
       path: CLAUDE_WORKING_SETTINGS_PATH,
       scopes: ["launch", "wrap"],
+      runtime: "claude",
       write: async (input) =>
         input.companionPath
           ? syncWorkingRepoClaudeAdditionalDirectories(
@@ -276,14 +320,14 @@ function buildEntries(): readonly ProjectionEntry[] {
     },
     /**
      * Removal-only: Mate never writes this block, an external installer does.
-     * Its `write` is the same strip, so a launch heals a repository the
-     * installer touched without waiting for a cleanup.
+     * Its `write` is the same strip, so a launch or a wrap heals a repository
+     * the installer touched without waiting for a cleanup.
      */
     {
       id: "legacy-tokensave-claude-md",
       kind: "merged",
       path: LEGACY_TOKENSAVE_CLAUDE_MD_PATH,
-      scopes: ["launch"],
+      scopes: ["launch", "wrap"],
       write: async (input) =>
         (await stripTokensaveClaudeMdAppend(input.repoPath)) === "removed" ? "written" : "current",
       removal: { by: "self", remove: (input) => stripTokensaveClaudeMdAppend(input.repoPath) },
@@ -336,6 +380,7 @@ function buildEntries(): readonly ProjectionEntry[] {
       kind: "merged",
       path: CLAUDE_MCP_DOCUMENT,
       scopes: ["launch", "wrap"],
+      runtime: "claude",
       write: async (input) =>
         (await removeRuntimeDocument(input.repoPath, CLAUDE_MCP_DOCUMENT)) === "removed"
           ? "written"
@@ -344,7 +389,7 @@ function buildEntries(): readonly ProjectionEntry[] {
         by: "self",
         remove: (input) => removeRuntimeDocument(input.repoPath, CLAUDE_MCP_DOCUMENT),
       },
-      present: (repoPath) => runtimeDocumentPresent(repoPath, CLAUDE_MCP_DOCUMENT),
+      present: (repoPath) => runtimeDocumentRecorded(repoPath, CLAUDE_MCP_DOCUMENT),
     },
     ...(
       [
@@ -357,15 +402,37 @@ function buildEntries(): readonly ProjectionEntry[] {
       kind: "merged" as const,
       path: documentPath.split("/").join(path.sep),
       scopes: ["launch", "wrap"] as const,
-      write: (input: ProjectionInput) =>
-        placeRuntimeDocument(input.repoPath, documentPath, input.runtimeDocuments),
+      runtime: documentRuntime(documentPath),
+      write: (input: ProjectionInput) => writeRuntimeDocumentEntry(input, documentPath),
       removal: {
         by: "self" as const,
         remove: (input: { repoPath: string }) =>
           removeRuntimeDocument(input.repoPath, documentPath),
       },
-      present: (repoPath: string) => runtimeDocumentPresent(repoPath, documentPath),
+      present: (repoPath: string) => runtimeDocumentRecorded(repoPath, documentPath),
     })),
+    /**
+     * After the OpenCode document, so its copies arrive once the document that
+     * loads them is in place. A companion that dropped OpenCode has the copies
+     * an earlier wrap made withdrawn; the outcome names each copy written or
+     * withdrawn and warns about shadowed and locally edited ones.
+     */
+    {
+      id: "opencode-companion-copies",
+      kind: "merged",
+      path: ".opencode",
+      scopes: ["wrap"],
+      runtime: "opencode",
+      removeOnUnwrap: true,
+      write: async (input) => {
+        if (!input.config || !input.companionPath) return "skipped";
+        return (input.config.allowedAgents?.includes("opencode") ?? false)
+          ? reconcileCompanionCopies(input.repoPath, input.companionPath)
+          : withdrawCompanionCopies(input.repoPath);
+      },
+      removal: { by: "self", remove: (input) => removeCompanionCopies(input.repoPath) },
+      present: companionCopiesPresent,
+    },
   ];
 }