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

package/src/lib/orchestrator/projection-opencode-copies.ts

@@ -0,0 +1,230 @@
+import crypto from "node:crypto";
+import type { Dirent } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  copies,
+  readManifest,
+  updateManifest,
+  withCopies,
+  type CopyRecord,
+} from "../../runtime/runtime-document-manifest";
+import { writeAtomic } from "../../runtime/write-atomic";
+import { pruneEmptyAncestors } from "../../tools/setup/utils";
+import { reconcileWorkingRepoCopyExcludes } from "../../tools/setup/working-repo-local-state";
+import type { ProjectionWriteReport } from "./projection-types";
+
+/**
+ * Copies the companion's `.opencode/` into the Working Repository's own
+ * `.opencode/`, the one slot OpenCode reads beside the user's global config.
+ * Regular files, not links: OpenCode does not live-reload a linked folder.
+ * Mate touches only the files its manifest records as owned.
+ */
+
+const OPENCODE_DIR = ".opencode";
+/** `opencode.json` is merged into the wrapped document instead of copied. */
+const SKIPPED_TOP_LEVEL = new Set(["opencode.json"]);
+const SKIPPED_NAMES = new Set(["node_modules", ".DS_Store"]);
+
+interface CopySource {
+  absolute: string;
+  content: Buffer;
+  sha256: string;
+}
+
+function sha256(content: Buffer): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+async function walk(dir: string, relative: string, into: Map<string, CopySource>): Promise<void> {
+  let entries: Dirent[];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+    if (SKIPPED_NAMES.has(entry.name)) continue;
+    if (relative === "" && SKIPPED_TOP_LEVEL.has(entry.name)) continue;
+    const absolute = path.join(dir, entry.name);
+    const rel = relative ? `${relative}/${entry.name}` : entry.name;
+    // oxlint-disable-next-line no-await-in-loop -- sequential walk keeps the order stable
+    const stat = await fs.stat(absolute).catch(() => null);
+    if (!stat) continue;
+    if (stat.isDirectory()) {
+      // oxlint-disable-next-line no-await-in-loop
+      await walk(absolute, rel, into);
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    // oxlint-disable-next-line no-await-in-loop
+    const content = await fs.readFile(absolute);
+    into.set(`${OPENCODE_DIR}/${rel}`, { absolute, content, sha256: sha256(content) });
+  }
+}
+
+async function companionSources(companionPath: string): Promise<Map<string, CopySource>> {
+  const sources = new Map<string, CopySource>();
+  await walk(path.join(companionPath, OPENCODE_DIR), "", sources);
+  return sources;
+}
+
+function destination(repoPath: string, relativePath: string): string {
+  return path.join(path.resolve(repoPath), ...relativePath.split("/"));
+}
+
+/** `null` when absent; a directory or other non-file reads as a foreign entry. */
+async function readDestination(target: string): Promise<Buffer | "foreign" | null> {
+  const stat = await fs.lstat(target).catch(() => null);
+  if (!stat) return null;
+  if (!stat.isFile()) return "foreign";
+  return fs.readFile(target);
+}
+
+async function writeCopy(target: string, content: Buffer): Promise<void> {
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await writeAtomic(target, content);
+}
+
+async function deleteCopy(repoPath: string, relativePath: string): Promise<void> {
+  const target = destination(repoPath, relativePath);
+  await fs.rm(target, { force: true });
+  await pruneEmptyAncestors(path.dirname(target), path.resolve(repoPath));
+}
+
+interface CopyPlan {
+  write: Array<{ relativePath: string; source: CopySource; warning?: string }>;
+  remove: string[];
+  shadowed: Array<{ relativePath: string; source: CopySource }>;
+  records: Record<string, CopyRecord>;
+  previous: Record<string, CopyRecord>;
+}
+
+async function planCopies(repoPath: string, companionPath: string): Promise<CopyPlan> {
+  const previous = copies(await readManifest(repoPath), "opencode");
+  const sources = await companionSources(companionPath);
+  const plan: CopyPlan = { write: [], remove: [], shadowed: [], records: {}, previous };
+
+  for (const [relativePath, source] of sources) {
+    const owned = previous[relativePath];
+    // oxlint-disable-next-line no-await-in-loop -- one stat per file
+    const current = await readDestination(destination(repoPath, relativePath));
+    if (current === "foreign" || (!owned && current !== null)) {
+      plan.shadowed.push({ relativePath, source });
+      continue;
+    }
+    const currentSha = current === null ? null : sha256(current);
+    const edited = owned !== undefined && currentSha !== null && currentSha !== owned.sha256;
+    /** Local edit survives until its companion source changes. */
+    const keepEdit = edited && source.sha256 === owned.sha256;
+    if (currentSha !== source.sha256 && !keepEdit) {
+      plan.write.push({
+        relativePath,
+        source,
+        warning: edited
+          ? `${relativePath} was edited locally; the edit was replaced from the companion. Edit ${source.absolute} instead.`
+          : undefined,
+      });
+    }
+    plan.records[relativePath] = { runtime: "opencode", sha256: source.sha256 };
+  }
+  for (const relativePath of Object.keys(previous)) {
+    if (!sources.has(relativePath)) plan.remove.push(relativePath);
+  }
+  return plan;
+}
+
+function sameRecords(a: Record<string, CopyRecord>, b: Record<string, CopyRecord>): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+function shadowWarning(relativePath: string, source: CopySource): string {
+  return `${relativePath} in the working repository shadows the companion file ${source.absolute}; the repository file wins.`;
+}
+
+/**
+ * Adds, updates and deletes owned copies; an unowned path is never touched.
+ * Excludes widen and new paths are recorded before any write, so an
+ * interrupted reconcile leaves no unrecorded copy and none Git would list.
+ */
+export async function reconcileCompanionCopies(
+  repoPath: string,
+  companionPath: string,
+): Promise<ProjectionWriteReport> {
+  const plan = await planCopies(repoPath, companionPath);
+  const warnings = plan.shadowed.map(({ relativePath, source }) =>
+    shadowWarning(relativePath, source),
+  );
+
+  const covering = [...new Set([...Object.keys(plan.previous), ...Object.keys(plan.records)])];
+  const excludesWidened = await reconcileWorkingRepoCopyExcludes(repoPath, covering);
+  /** Previous records win: a path not yet rewritten keeps the hash on disk. */
+  const interim = { ...plan.records, ...plan.previous };
+  if (!sameRecords(interim, plan.previous)) {
+    await updateManifest(repoPath, (manifest) => withCopies(manifest, "opencode", interim));
+  }
+
+  for (const { relativePath, source, warning } of plan.write) {
+    // oxlint-disable-next-line no-await-in-loop -- bounded by the companion folder
+    await writeCopy(destination(repoPath, relativePath), source.content);
+    if (warning) warnings.push(warning);
+  }
+  for (const relativePath of plan.remove) {
+    // oxlint-disable-next-line no-await-in-loop
+    await deleteCopy(repoPath, relativePath);
+  }
+
+  const recordsWritten = !sameRecords(plan.records, plan.previous);
+  if (recordsWritten) {
+    await updateManifest(repoPath, (manifest) => withCopies(manifest, "opencode", plan.records));
+  }
+  const excludesNarrowed = await reconcileWorkingRepoCopyExcludes(
+    repoPath,
+    Object.keys(plan.records),
+  );
+
+  const written = plan.write.map(({ relativePath }) => relativePath);
+  return {
+    state:
+      written.length > 0 ||
+      plan.remove.length > 0 ||
+      recordsWritten ||
+      excludesWidened ||
+      excludesNarrowed
+        ? "written"
+        : "current",
+    warnings,
+    changed: { written, removed: plan.remove },
+  };
+}
+
+/**
+ * Deletes every owned copy, then its exclude line, and prunes what that
+ * emptied: a copy is never on disk without the line that hides it.
+ */
+export async function withdrawCompanionCopies(repoPath: string): Promise<ProjectionWriteReport> {
+  const owned = Object.keys(copies(await readManifest(repoPath), "opencode"));
+  for (const relativePath of owned) {
+    // oxlint-disable-next-line no-await-in-loop
+    await deleteCopy(repoPath, relativePath);
+  }
+  if (owned.length > 0) {
+    await updateManifest(repoPath, (manifest) => withCopies(manifest, "opencode", {}));
+  }
+  const excludesChanged = await reconcileWorkingRepoCopyExcludes(repoPath, []);
+  return {
+    state: owned.length > 0 || excludesChanged ? "written" : "current",
+    changed: { written: [], removed: owned },
+  };
+}
+
+export async function removeCompanionCopies(repoPath: string): Promise<"removed" | "absent"> {
+  return (await withdrawCompanionCopies(repoPath)).state === "written" ? "removed" : "absent";
+}
+
+/** Whether any owned copy is recorded. */
+export async function companionCopiesPresent(repoPath: string): Promise<boolean> {
+  return Object.keys(copies(await readManifest(repoPath), "opencode")).length > 0;
+}

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

@@ -10,6 +10,7 @@ import {
   GRAPHIFY_OUTPUT_SUBDIR,
   GRAPHIFY_STORE_SEGMENT,
 } from "../../tools/setup/capabilities/graphify";
+import { runtimeWrapperBinPath } from "../../runtime/runtime-directory";
 import { getReactDoctorBinPath, getWrapperBinPath } from "../package-paths";
 import type { LinkedRepository } from "./types";
 
@@ -25,17 +26,22 @@ const COMPANION_GRAPHIFY_REPOSITORY_ID = "__companion__";
  * Both bin paths and `GRAPHIFY_OUT` are unconditional: a path exists whether or
  * not its Capability is enabled, and enablement is a predicate, read live from
  * the companion rather than cached here.
+ *
+ * The persisted record names the runtime directory so it survives a reinstall;
+ * a launch passes the live install path, since its runtime-directory refresh
+ * may only have warned.
  */
 export function buildProjection(
   companionPath: string,
   repository: LinkedRepository,
+  wrapperBinPath: string = runtimeWrapperBinPath(),
 ): MateProjection {
   return {
     version,
     companionPath,
     repositoryPath: repository.path,
     repositoryId: repository.id,
-    wrapperBinPath: getWrapperBinPath(),
+    wrapperBinPath,
     reactDoctorBinPath: getReactDoctorBinPath(),
     graphifyOut: path.join(
       companionPath,

package/src/lib/orchestrator/projection-runtime-documents.ts

@@ -1,44 +1,38 @@
-import crypto from "node:crypto";
+import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-
-import { repoLocalDirPath } from "../../runtime/repo-local";
+import { promisify } from "node:util";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { gitEnvironment } from "../../runtime/companion-git";
+import {
+  documentRegions,
+  readManifest,
+  updateManifest,
+  withDocument,
+  withoutDocuments,
+  type ManagedRegion,
+  type RenderedRuntimeDocument,
+} from "../../runtime/runtime-document-manifest";
+import { writeAtomic } from "../../runtime/write-atomic";
 import { pruneEmptyAncestors } from "../../tools/setup/utils";
-import type { ManagedRegion, RenderedRuntimeDocument } from "./projection-types";
+
+export {
+  CLAUDE_LOCAL_CONFIG_DOCUMENT,
+  CLAUDE_MCP_DOCUMENT,
+  CLAUDE_SETTINGS_DOCUMENT,
+  OPENCODE_CONFIG_DOCUMENT,
+} from "../../runtime/runtime-document-manifest";
 
 /**
  * Places the documents an Agent Runtime discovers by its own upward walk from
  * the current directory. A Runtime Surface renders one as a value; this module
  * writes it, records the regions it wrote at the Projection Root, and removes
  * exactly those again — which is what makes a working-target document swept by
- * `mate working cleanup` without cleanup holding a list of them.
- */
-
-const MANIFEST_FILE = "runtime-documents.json";
-
-/**
- * The three destinations, repo-relative with POSIX separators. Declared here
- * rather than beside the renderers so the entry catalogue names a destination
- * without reaching into an Agent Runtime's Runtime Surface.
- */
-export const CLAUDE_SETTINGS_DOCUMENT = ".claude/settings.local.json";
-export const CLAUDE_MCP_DOCUMENT = ".mcp.json";
-export const OPENCODE_CONFIG_DOCUMENT = ".opencode/opencode.json";
-
-/**
- * The one destination outside the Working Repository. Claude Code has no
- * project file that declares a pre-approved MCP server: `.mcp.json` servers sit
- * "pending approval" until a human accepts them in a session, and the settings
- * document can only enable a server `.mcp.json` already declares. Local scope —
- * `projects[<repo>].mcpServers` in the user's `~/.claude.json`, what
- * `claude mcp add --scope local` writes — is the only channel that is live on
- * first use.
- *
- * Written `~`-prefixed rather than resolved so the manifest recording it stays
- * machine-independent, and so an external target is identifiable as one.
+ * `mate working cleanup` without cleanup holding a list of them. The manifest
+ * — format, I/O and queries — belongs to `runtime/runtime-document-manifest`.
  */
-export const CLAUDE_LOCAL_CONFIG_DOCUMENT = "~/.claude.json";
 
 /**
  * A document Mate does not own the surroundings of. Mate's regions are stripped
@@ -50,6 +44,38 @@ export function isExternalDocument(documentPath: string): boolean {
   return documentPath.startsWith("~/");
 }
 
+const execFileAsync = promisify(execFile);
+
+/** Whether Git tracks the repo-relative path; any `ls-files` failure reads as untracked. */
+async function gitTracks(repoPath: string, relativePath: string): Promise<boolean> {
+  try {
+    const { stdout } = await execFileAsync("git", ["ls-files", "-z", "--", relativePath], {
+      cwd: path.resolve(repoPath),
+      encoding: "utf8",
+      env: gitEnvironment(),
+    });
+    return stdout.split("\0").includes(relativePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Excludes don't hide tracked files, so regions with machine-absolute paths
+ * would land in a committed document: warn, still write. Best-effort: any
+ * `ls-files` failure reads as "not tracked".
+ */
+export async function trackedDocumentWarnings(
+  repoPath: string,
+  documentPath: string,
+  repositoryId: string,
+): Promise<string[]> {
+  if (!(await gitTracks(repoPath, documentPath))) return [];
+  return [
+    `${documentPath} is tracked by Git in ${repositoryId}; ${FRAMEWORK_NAME} writes machine-absolute companion paths into it, so committing it would push this machine's paths to everyone else on the repository. Untrack it with \`git rm --cached ${documentPath}\` if those paths should stay local.`,
+  ];
+}
+
 /**
  * Injectable so a test never writes to the real `~/.claude.json`. An external
  * target is the one destination outside a temporary fixture, so it is also the
@@ -59,14 +85,6 @@ export const runtimeDocumentDeps = {
   homeDir: (): string => os.homedir(),
 };
 
-interface Manifest {
-  documents: Record<string, ManagedRegion[]>;
-}
-
-function manifestPath(repoPath: string): string {
-  return path.join(repoLocalDirPath(repoPath), MANIFEST_FILE);
-}
-
 function documentPathIn(repoPath: string, documentPath: string): string {
   if (isExternalDocument(documentPath)) {
     return path.join(runtimeDocumentDeps.homeDir(), ...documentPath.slice("~/".length).split("/"));
@@ -97,26 +115,9 @@ async function readRaw(filePath: string): Promise<string | null> {
   }
 }
 
-function parseObject(raw: string | null): Record<string, unknown> {
-  if (raw === null) return {};
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    if (isRecord(parsed)) return parsed;
-  } catch {
-    /* unparseable — start from an empty object */
-  }
-  return {};
-}
-
 /**
- * The same read for a document Mate does not own, where an unparseable one is
- * refused rather than treated as empty. `parseObject`'s fallback is right for
- * the manifest — Mate wrote it and can rebuild it — and ruinous here: a torn
- * read of `~/.claude.json` would be written back as the handful of keys Mate
- * contributes, taking Claude Code's auth, every project's history and its MCP
- * approvals with it, silently and without a backup. Throwing leaves the file
- * as it was and hands the entry catch in `project()` a failed outcome to
- * report, which is the answer an operator can act on.
+ * Unparseable throws, never reads as empty: writing back a torn
+ * `~/.claude.json` would wipe the user's auth and history.
  */
 function parseDocument(raw: string | null, target: string): Record<string, unknown> {
   if (raw === null) return {};
@@ -130,40 +131,6 @@ function parseDocument(raw: string | null, target: string): Record<string, unkno
   return parsed;
 }
 
-/**
- * Writes via a sibling temp file + `fs.rename()` so an interrupted write cannot
- * leave a half-written document behind. A reader racing this one — a Claude
- * Code session holding `~/.claude.json` open — observes the old file or the new
- * one, never a truncated one.
- */
-async function writeAtomic(target: string, contents: string): Promise<void> {
-  const tempPath = `${target}.${crypto.randomUUID()}.tmp`;
-  try {
-    await fs.writeFile(tempPath, contents, "utf8");
-    await fs.rename(tempPath, target);
-  } catch (error) {
-    await fs.rm(tempPath, { force: true }).catch(() => {});
-    throw error;
-  }
-}
-
-async function readManifest(repoPath: string): Promise<Manifest> {
-  const parsed = parseObject(await readRaw(manifestPath(repoPath)));
-  return {
-    documents: isRecord(parsed.documents) ? (parsed.documents as Manifest["documents"]) : {},
-  };
-}
-
-async function writeManifest(repoPath: string, manifest: Manifest): Promise<void> {
-  const target = manifestPath(repoPath);
-  if (Object.keys(manifest.documents).length === 0) {
-    await fs.unlink(target).catch(() => {});
-    return;
-  }
-  await fs.mkdir(path.dirname(target), { recursive: true });
-  await writeAtomic(target, serialize(manifest));
-}
-
 /** The container holding a region's final key, created on demand when writing. */
 function containerFor(
   document: Record<string, unknown>,
@@ -185,6 +152,11 @@ function containerFor(
   return node;
 }
 
+function keyPresent(document: Record<string, unknown>, at: string[]): boolean {
+  const container = containerFor(document, at, false);
+  return container !== null && Object.hasOwn(container, at.at(-1)!);
+}
+
 function applyRegion(document: Record<string, unknown>, region: ManagedRegion): void {
   const container = containerFor(document, region.at, true)!;
   const key = region.at.at(-1)!;
@@ -295,19 +267,22 @@ export async function placeRuntimeDocument(
   const raw = await readRaw(target);
   const document = parseDocument(raw, target);
 
-  const manifest = await readManifest(repoPath);
-  for (const region of manifest.documents[documentPath] ?? []) revertRegion(document, region);
-  for (const region of rendered.regions) applyRegion(document, region);
+  const prior = documentRegions(await readManifest(repoPath), documentPath);
+  for (const region of prior ?? []) revertRegion(document, region);
+  /** After the revert, a key still present is the human's: a yielding region gives way to it. */
+  const applied = rendered.regions.filter(
+    (region) => !(region.kind === "value" && region.yields && keyPresent(document, region.at)),
+  );
+  for (const region of applied) applyRegion(document, region);
   const next = serialize(document);
 
-  const regions = [...rendered.regions] as ManagedRegion[];
-  const recorded = JSON.stringify(manifest.documents[documentPath]) === JSON.stringify(regions);
+  const recorded = JSON.stringify(prior) === JSON.stringify(applied);
   if (next === raw && recorded) return "current";
 
+  /** The file first: a failed write leaves the manifest naming what is really there. */
   await fs.mkdir(path.dirname(target), { recursive: true });
   await writeAtomic(target, next);
-  manifest.documents[documentPath] = regions;
-  await writeManifest(repoPath, manifest);
+  await updateManifest(repoPath, (manifest) => withDocument(manifest, documentPath, applied));
   return "written";
 }
 
@@ -319,13 +294,11 @@ export async function removeRuntimeDocument(
   repoPath: string,
   documentPath: string,
 ): Promise<"removed" | "absent"> {
-  const manifest = await readManifest(repoPath);
-  const regions = manifest.documents[documentPath];
+  const regions = documentRegions(await readManifest(repoPath), documentPath);
   if (!regions) return "absent";
 
   await revertDocumentOnDisk(repoPath, documentPath, regions);
-  delete manifest.documents[documentPath];
-  await writeManifest(repoPath, manifest);
+  await updateManifest(repoPath, (manifest) => withoutDocuments(manifest, [documentPath]));
   return "removed";
 }
 
@@ -358,10 +331,10 @@ async function revertDocumentOnDisk(
 }
 
 /**
- * Withdraws several destinations against a single read and a single write of the
- * manifest. `removeRuntimeDocument` per destination cannot be run concurrently —
- * each rewrites the whole manifest, so the last write restores the keys the
- * others removed — and running it sequentially rewrites the manifest once per
+ * Withdraws several destinations against a single manifest update.
+ * `removeRuntimeDocument` per destination cannot be run concurrently — each
+ * rewrites the whole manifest, so the last write restores the keys the others
+ * removed — and running it sequentially rewrites the manifest once per
  * document. Reverting the files together and recording the outcome once is both
  * safe and one write.
  *
@@ -375,13 +348,13 @@ export async function removeRuntimeDocuments(
   documentPaths: readonly string[],
 ): Promise<{ removed: string[]; absent: string[]; error?: { document: string; error: Error } }> {
   const manifest = await readManifest(repoPath);
-  const recorded = documentPaths.filter((candidate) => manifest.documents[candidate] !== undefined);
-  const absent = documentPaths.filter((candidate) => manifest.documents[candidate] === undefined);
+  const recorded = documentPaths.filter((candidate) => documentRegions(manifest, candidate));
+  const absent = documentPaths.filter((candidate) => !documentRegions(manifest, candidate));
   if (recorded.length === 0) return { removed: [], absent };
 
   const settled = await Promise.allSettled(
     recorded.map((documentPath) =>
-      revertDocumentOnDisk(repoPath, documentPath, manifest.documents[documentPath]!),
+      revertDocumentOnDisk(repoPath, documentPath, documentRegions(manifest, documentPath)!),
     ),
   );
 
@@ -396,29 +369,9 @@ export async function removeRuntimeDocuments(
       };
       continue;
     }
-    delete manifest.documents[documentPath];
     removed.push(documentPath);
   }
 
-  await writeManifest(repoPath, manifest);
+  await updateManifest(repoPath, (current) => withoutDocuments(current, removed));
   return { removed, absent, ...(failure ? { error: failure } : {}) };
 }
-
-/**
- * Every destination the manifest records, in the order it recorded them. This
- * is what makes a Working Repository "wrapped": the manifest is written only by
- * a pass that placed a runtime document, and `mate wrap` is the only pass that
- * places one. Reported as data so neither the launch refusal nor `mate unwrap`
- * holds a list of destinations that the entry catalogue could outgrow.
- */
-export async function recordedRuntimeDocuments(repoPath: string): Promise<string[]> {
-  return Object.keys((await readManifest(repoPath)).documents);
-}
-
-/** Present when Mate recorded regions for it, not merely when the file exists. */
-export async function runtimeDocumentPresent(
-  repoPath: string,
-  documentPath: string,
-): Promise<boolean> {
-  return (await readManifest(repoPath)).documents[documentPath] !== undefined;
-}

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

@@ -1,5 +1,6 @@
 import type { GlobalConfigStore } from "./global-config-store";
 import type { ProjectionFile } from "../../runtime/projection";
+import type { RenderedRuntimeDocument, WrapRuntime } from "../../runtime/runtime-document-manifest";
 import type { CompanionSource, FrameworkConfig, LinkedRepository } from "./types";
 
 /**
@@ -32,38 +33,8 @@ export type ProjectionEntryId =
   | "claude-runtime-document"
   | "claude-local-mcp-document"
   | "mcp-runtime-document"
-  | "opencode-runtime-document";
-
-/**
- * A region of a runtime document that Mate maintains. JSON carries no comment
- * syntax, so the region is recorded rather than marked in the file: `list`
- * appends values not already there, `map` sets entries by key, `value` sets one
- * key — and removal takes back exactly those, leaving anything a human added.
- *
- * `stripPrefix` is the one exception to "removal takes back exactly what was
- * written": it deletes keys Mate never wrote, and removal does not restore
- * them. It exists for keys an older Mate wrote and a current one must not
- * leave behind, so a re-wrap heals a repository an old version configured.
- */
-export type ManagedRegion =
-  | { readonly at: string[]; readonly kind: "list"; readonly values: unknown[] }
-  | {
-      readonly at: string[];
-      readonly kind: "map";
-      readonly entries: Record<string, unknown>;
-      readonly stripPrefix?: string;
-    }
-  | { readonly at: string[]; readonly kind: "value"; readonly value: unknown };
-
-/**
- * What a Runtime Surface hands the Projection Root: the managed content of one
- * document, without a destination. The surface renders; the entry places.
- */
-export interface RenderedRuntimeDocument {
-  /** Repo-relative with POSIX separators, or `~/`-prefixed for a user-global target. */
-  readonly path: string;
-  readonly regions: readonly ManagedRegion[];
-}
+  | "opencode-runtime-document"
+  | "opencode-companion-copies";
 
 export interface ProjectionInput {
   repoPath: string;
@@ -75,6 +46,8 @@ export interface ProjectionInput {
   globalConfigStore?: GlobalConfigStore;
   /** Rendered by the active Runtime Surfaces; placed by the `wrap` scope's entries. */
   runtimeDocuments?: readonly RenderedRuntimeDocument[];
+  /** Restricts runtime-tagged entries to these runtimes; every runtime when absent. */
+  runtimes?: readonly WrapRuntime[];
 }
 
 export interface ProjectionRemovalInput {
@@ -86,6 +59,23 @@ export interface ProjectionRemovalInput {
 export type ProjectionWriteState = "written" | "current" | "skipped";
 export type ProjectionRemoveState = "removed" | "absent" | "retained" | "covered";
 
+/** Repo-relative paths an entry maintaining several files wrote or withdrew. */
+export interface ProjectionChangedPaths {
+  written: string[];
+  removed: string[];
+}
+
+/**
+ * What a write may return instead of a bare state, when it has something to
+ * tell the operator. The entry reports; it never prints — the caller presents
+ * warnings and changed paths without knowing which entry produced them.
+ */
+export interface ProjectionWriteReport {
+  state: ProjectionWriteState;
+  warnings?: string[];
+  changed?: ProjectionChangedPaths;
+}
+
 /**
  * Every entry names its inverse. `self` removes its own path, `entry` is covered
  * by another entry's removal, `retained` is deliberately left behind and says
@@ -105,8 +95,10 @@ export interface ProjectionEntry {
   /** Repo-relative, POSIX separators. An entry spanning siblings names its primary. */
   readonly path: string;
   readonly scopes: readonly ProjectionScope[];
+  /** Set on entries that belong to one Agent Runtime; see {@link ProjectionInput.runtimes}. */
+  readonly runtime?: WrapRuntime;
   /** `skipped` when an input this entry needs was not supplied. */
-  write(input: ProjectionInput): Promise<ProjectionWriteState>;
+  write(input: ProjectionInput): Promise<ProjectionWriteState | ProjectionWriteReport>;
   /**
    * Whether a failed write is reported without failing the operation that
    * triggered the projection. Only for an entry something else already covers:
@@ -132,6 +124,12 @@ export interface ProjectionEntryOutcome {
   state: ProjectionWriteState | ProjectionRemoveState | "failed";
   error?: Error;
   degradable?: boolean;
+  /** The entry's runtime tag; absent for runtime-neutral entries. */
+  runtime?: WrapRuntime;
+  /** Present only when the entry had something to say. */
+  warnings?: string[];
+  /** Present only when the entry wrote or withdrew paths it reports one by one. */
+  changed?: ProjectionChangedPaths;
 }
 
 export interface ProjectionResult {
@@ -163,3 +161,10 @@ export interface ProjectionDescription {
 export function firstFailure(outcomes: ProjectionEntryOutcome[]): ProjectionEntryOutcome | null {
   return outcomes.find((outcome) => outcome.state === "failed" && !outcome.degradable) ?? null;
 }
+
+/** Names the failed entry: "the projection" alone would not say what to fix. */
+export function entryFailureMessage(outcome: ProjectionEntryOutcome, repositoryId: string): string {
+  const reason = outcome.error?.message ?? "projection failed";
+  const target = outcome.id === "projection-pair" ? "the projection" : outcome.path;
+  return `failed to write ${target} for ${repositoryId}: ${reason}`;
+}