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

package/src/lib/orchestrator/openspec-store.ts

@@ -1,15 +1,11 @@
-import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { promisify } from "node:util";
 
 import { parse as parseYaml } from "yaml";
 
-import { MATE_ENV } from "../../runtime/env-names";
-import { runtimeWrapperBinPath } from "../../runtime/runtime-directory";
-import { resolveCommandOnPath } from "../../tools/setup/utils";
-import { getWrapperBinPath } from "../package-paths";
+import { pathIsDirectory } from "../fs-utils";
+import { runOpenSpec } from "../openspec-cli";
 
 /**
  * The Companion Repository as an OpenSpec store. OpenSpec reports the Working
@@ -22,31 +18,16 @@ import { getWrapperBinPath } from "../package-paths";
  * register, which OpenSpec answers authoritatively.
  */
 
-const execFileAsync = promisify(execFile);
-
 /** OpenSpec's one id grammar, shared by store and change ids. */
 const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 
 const STORE_METADATA_FILE = path.join(".openspec-store", "store.yaml");
 
-/** Injectable so the suite never touches the developer's registry or binary. */
+/** Injectable so the suite never touches the developer's registry; the CLI is `openSpecCliDeps`. */
 export const openSpecStoreDeps = {
   env: (): NodeJS.ProcessEnv => process.env,
   platform: (): NodeJS.Platform => process.platform,
   homedir: (): string => os.homedir(),
-  /** Mate's own `openspec` wrappers, which must never answer a registration. */
-  wrapperBinDirs: (): string[] => {
-    const launched = openSpecStoreDeps.env()[MATE_ENV.wrapperBinPath];
-    return [getWrapperBinPath(), runtimeWrapperBinPath(), ...(launched ? [launched] : [])];
-  },
-  resolveBinary: (): string | undefined => {
-    const excluded = new Set(openSpecStoreDeps.wrapperBinDirs().map((dir) => path.resolve(dir)));
-    const searchPath = (openSpecStoreDeps.env().PATH ?? "")
-      .split(path.delimiter)
-      .filter((dir) => dir && !excluded.has(path.resolve(dir)))
-      .join(path.delimiter);
-    return resolveCommandOnPath("openspec", searchPath);
-  },
 };
 
 export type StoreRegistrationCheck =
@@ -67,13 +48,6 @@ async function canonicalPath(candidate: string): Promise<string> {
   return fs.realpath(candidate).catch(() => path.resolve(candidate));
 }
 
-async function isDirectory(candidate: string): Promise<boolean> {
-  return fs
-    .stat(candidate)
-    .then((stats) => stats.isDirectory())
-    .catch(() => false);
-}
-
 function sanitizeStoreId(name: string): string {
   return name
     .toLowerCase()
@@ -157,23 +131,14 @@ export async function checkStoreRegistration(
     : { state: "conflict", path: localPath };
 }
 
-function commandOutput(error: unknown): string {
-  const { stderr, stdout, message } = error as {
-    stderr?: string;
-    stdout?: string;
-    message: string;
-  };
-  return (stderr || stdout || message).trim();
-}
-
 /**
  * Registers the companion when the registry lacks it. A conflicting id fails
- * rather than silently picking another one; OpenSpec without stores, or a
+ * rather than silently picking another one; a missing bundled CLI, or a
  * companion that is no OpenSpec root, is skipped.
  */
 export async function ensureStoreRegistration(companionPath: string): Promise<StoreRegistration> {
   const companion = await canonicalPath(companionPath);
-  if (!(await isDirectory(path.join(companion, "openspec")))) {
+  if (!(await pathIsDirectory(path.join(companion, "openspec")))) {
     return { state: "skipped", reason: `${companion} is not an OpenSpec root` };
   }
   const id = await deriveStoreId(companion);
@@ -183,20 +148,15 @@ export async function ensureStoreRegistration(companionPath: string): Promise<St
     throw new Error(`OpenSpec store id "${id}" is already registered at ${check.path}`);
   }
 
-  const bin = openSpecStoreDeps.resolveBinary();
-  if (!bin) return { state: "skipped", reason: "the openspec CLI is not on PATH" };
-  try {
-    await execFileAsync(bin, ["store", "register", companion, "--id", id, "--yes"], {
-      cwd: companion,
-      env: openSpecStoreDeps.env(),
-      timeout: 30_000,
-    });
-  } catch (error) {
-    const output = commandOutput(error);
-    if (/unknown command/i.test(output)) {
-      return { state: "skipped", reason: "the openspec CLI does not support stores" };
-    }
-    throw new Error(`openspec store register failed: ${output}`, { cause: error });
+  const run = await runOpenSpec(["store", "register", companion, "--id", id, "--yes"], {
+    cwd: companion,
+    env: openSpecStoreDeps.env(),
+    timeout: 30_000,
+  });
+  if (run.missing) return { state: "skipped", reason: run.stderr };
+  if (run.code !== 0) {
+    const output = (run.stderr || run.stdout).trim() || `exit code ${run.code ?? "unknown"}`;
+    throw new Error(`openspec store register failed: ${output}`);
   }
   return { state: "written", id };
 }

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

@@ -0,0 +1,36 @@
+import fs from "node:fs/promises";
+
+import {
+  reconcileClaudeLinks,
+  removeClaudeLinks,
+  type ClaudeLinkRoot,
+} from "./projection-claude-links";
+
+/**
+ * A companion command directory (e.g. `acme/`) holds at least one
+ * `.md` file. Loose command files are not linked: a file symlink needs
+ * elevation on Windows, a directory junction does not.
+ */
+const COMMANDS: ClaudeLinkRoot = {
+  dir: "commands",
+  eligible: async (entryPath) => {
+    const entries = await fs.readdir(entryPath).catch(() => []);
+    return entries.some((name) => name.endsWith(".md"));
+  },
+};
+
+export function reconcileWorkingRepoClaudeCommandLinks(
+  repoPath: string,
+  companionPath: string | null,
+  enabled: boolean,
+  registeredCompanionPaths: string[] = [],
+): Promise<"written" | "current"> {
+  return reconcileClaudeLinks(COMMANDS, repoPath, companionPath, enabled, registeredCompanionPaths);
+}
+
+export function removeWorkingRepoClaudeCommandLinks(
+  repoPath: string,
+  registeredCompanionPaths: string[] = [],
+): Promise<"removed" | "absent"> {
+  return removeClaudeLinks(COMMANDS, repoPath, registeredCompanionPaths);
+}

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

@@ -0,0 +1,159 @@
+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";
+
+/**
+ * A `.claude/<dir>` folder whose companion entries Mate links one by one into
+ * the Working Repository, e.g. `skills` or `commands`.
+ */
+export interface ClaudeLinkRoot {
+  /** Folder name under `.claude/`. */
+  dir: string;
+  /** Whether a companion entry, given by absolute path, is linked. */
+  eligible: (entryPath: string) => Promise<boolean>;
+}
+
+function rootPath(root: ClaudeLinkRoot): string {
+  return path.join(".claude", root.dir);
+}
+
+/** The manifest key prefix of a root's links: repo-relative, POSIX separators. */
+function keyPrefix(root: ClaudeLinkRoot): string {
+  return `.claude/${root.dir}/`;
+}
+
+async function eligibleNames(sourceRoot: string, root: ClaudeLinkRoot): Promise<string[]> {
+  const entries = await fs.readdir(sourceRoot, { withFileTypes: true }).catch(() => []);
+  const names: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (await root.eligible(path.join(sourceRoot, entry.name))) names.push(entry.name);
+  }
+  return names;
+}
+
+async function linkTarget(link: string): Promise<string | null> {
+  const target = await fs.readlink(link).catch(() => null);
+  return target === null ? null : realLinkTarget(link, target);
+}
+
+async function registeredRoots(
+  root: ClaudeLinkRoot,
+  repoPath: string,
+  companionPath: string | null,
+  registeredCompanionPaths: string[],
+): Promise<string[]> {
+  const projection = readProjectionFile(repoPath);
+  const candidates = [
+    ...registeredCompanionPaths,
+    companionPath ?? "",
+    projection?.projection.companionPath ?? "",
+  ];
+  const roots = await Promise.all(
+    candidates
+      .filter(Boolean)
+      .map((candidate) => realOrResolved(path.resolve(candidate, rootPath(root)))),
+  );
+  return [...new Set(roots)];
+}
+
+async function createDirectoryLink(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.
+ * Only this root's records are read and replaced.
+ */
+export async function reconcileClaudeLinks(
+  root: ClaudeLinkRoot,
+  repoPath: string,
+  companionPath: string | null,
+  enabled: boolean,
+  registeredCompanionPaths: string[] = [],
+): Promise<"written" | "current"> {
+  const scope = { prefix: keyPrefix(root) };
+  const recordKey = (name: string): string => `${scope.prefix}${name}`;
+  const currentRoot = companionPath ? path.resolve(companionPath, rootPath(root)) : null;
+  const roots = await registeredRoots(root, repoPath, companionPath, registeredCompanionPaths);
+  const targetRoot = path.join(path.resolve(repoPath), rootPath(root));
+  const recorded = links(await readManifest(repoPath), "claude", scope);
+  const existing = await fs.readdir(targetRoot, { withFileTypes: true }).catch(() => []);
+  const sourceNames: Set<string> =
+    currentRoot && enabled ? new Set(await eligibleNames(currentRoot, root)) : 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);
+    const target = await linkTarget(link);
+    if (target === null) continue;
+    const record = recorded[recordKey(entry.name)];
+    const owned = record
+      ? (await realOrResolved(record.target)) === target
+      : roots.some((candidate) => path.dirname(target) === candidate);
+    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;
+    }
+
+    await fs.unlink(link);
+    changed = true;
+  }
+
+  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;
+      const target = path.join(currentRoot, name);
+      await createDirectoryLink(target, link);
+      records[recordKey(name)] = { runtime: "claude", target };
+      changed = true;
+    }
+  }
+
+  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, scope));
+    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 removeClaudeLinks(
+  root: ClaudeLinkRoot,
+  repoPath: string,
+  registeredCompanionPaths: string[] = [],
+): Promise<"removed" | "absent"> {
+  const result = await reconcileClaudeLinks(root, repoPath, null, false, registeredCompanionPaths);
+  return result === "written" ? "removed" : "absent";
+}

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

@@ -1,205 +1,34 @@
-// oxlint-disable no-await-in-loop
 import fs from "node:fs/promises";
 import path from "node:path";
 
-import { CURRENT_LAYER_LINK } from "../../runtime/audience-layer";
-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[] = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-    const skillPath = path.join(root, entry.name, "SKILL.md");
-    if (
-      await fs
-        .stat(skillPath)
-        .then(() => true)
-        .catch(() => false)
-    )
-      names.push(entry.name);
-  }
-  return names;
-}
-
-async function linkTarget(link: string): Promise<string | null> {
-  const target = await fs.readlink(link).catch(() => null);
-  return target === null ? null : realLinkTarget(link, target);
-}
-
-async function registeredSkillRoots(
-  repoPath: string,
-  companionPath: string | null,
-  registeredCompanionPaths: string[],
-): Promise<string[]> {
-  const projection = readProjectionFile(repoPath);
-  const candidates = [
-    ...registeredCompanionPaths,
-    companionPath ?? "",
-    projection?.projection.companionPath ?? "",
-  ];
-  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");
-}
-
-const CLAUDE_AGENTS_PATH = path.join(".claude", "agents");
-
-/** The manifest key of an agent link: repo-relative, POSIX separators. */
-function agentKey(file: string): string {
-  return `.claude/agents/${file}`;
-}
-
-async function agentFiles(root: string): Promise<string[]> {
-  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
-  return entries
-    .filter((entry) => (entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md"))
-    .map((entry) => entry.name);
-}
-
-/**
- * Every link the wrap wants, by manifest key: the companion's skills, then the
- * wrapped audience's skills and agents. An audience link targets the layer
- * through its `current` link, so a re-rendered layer never strands it. A
- * companion skill wins a name both provide.
- */
-async function wantedLinks(
-  currentRoot: string | null,
-  layerRoot: string | null,
-): Promise<Map<string, string>> {
-  const wanted = new Map<string, string>();
-  if (currentRoot) {
-    for (const name of await skillNames(currentRoot)) {
-      wanted.set(recordKey(name), path.join(currentRoot, name));
-    }
-  }
-  if (layerRoot) {
-    const layerSkills = path.join(layerRoot, "skills");
-    for (const name of await skillNames(layerSkills)) {
-      if (!wanted.has(recordKey(name))) wanted.set(recordKey(name), path.join(layerSkills, name));
-    }
-    const layerAgents = path.join(layerRoot, "agents");
-    for (const file of await agentFiles(layerAgents)) {
-      wanted.set(agentKey(file), path.join(layerAgents, file));
-    }
-  }
-  return wanted;
-}
-
-/**
- * Recorded link: Mate's while it resolves to its recorded target. Unrecorded:
- * a skill link is adopted only when it resolves into a registered, current or
- * projected companion; an agent link never is. Records follow the filesystem,
- * so a partial failure re-adopts.
- */
-export async function reconcileWorkingRepoClaudeSkillLinks(
+  reconcileClaudeLinks,
+  removeClaudeLinks,
+  type ClaudeLinkRoot,
+} from "./projection-claude-links";
+
+/** A companion skill is a directory holding `SKILL.md`. */
+const SKILLS: ClaudeLinkRoot = {
+  dir: "skills",
+  eligible: (entryPath) =>
+    fs
+      .stat(path.join(entryPath, "SKILL.md"))
+      .then(() => true)
+      .catch(() => false),
+};
+
+export function reconcileWorkingRepoClaudeSkillLinks(
   repoPath: string,
   companionPath: string | null,
   enabled: boolean,
   registeredCompanionPaths: string[] = [],
-  audienceLayerDir: string | null = null,
 ): Promise<"written" | "current"> {
-  const repoRoot = path.resolve(repoPath);
-  const currentRoot = companionPath ? path.resolve(companionPath, CLAUDE_SKILLS_PATH) : null;
-  const layerRoot =
-    audienceLayerDir && enabled ? path.join(audienceLayerDir, CURRENT_LAYER_LINK, ".claude") : null;
-  const roots = await registeredSkillRoots(repoPath, companionPath, registeredCompanionPaths);
-  const recorded = links(await readManifest(repoPath), "claude");
-  const wanted = await wantedLinks(enabled ? currentRoot : null, layerRoot);
-  const records: Record<string, LinkRecord> = {};
-  let changed = false;
-
-  const linkDirs = [
-    { dir: path.join(repoRoot, CLAUDE_SKILLS_PATH), keyOf: recordKey, adoptable: true },
-    { dir: path.join(repoRoot, CLAUDE_AGENTS_PATH), keyOf: agentKey, adoptable: false },
-  ];
-  for (const { dir, keyOf, adoptable } of linkDirs) {
-    const existing = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
-    for (const entry of existing) {
-      if (!entry.isSymbolicLink()) continue;
-      const link = path.join(dir, entry.name);
-      const target = await linkTarget(link);
-      if (target === null) continue;
-      const key = keyOf(entry.name);
-      const record = recorded[key];
-      const owned = record
-        ? (await realOrResolved(record.target)) === target
-        : adoptable && roots.some((root) => path.dirname(target) === root);
-      if (!owned) continue;
-
-      const want = wanted.get(key);
-      if (want && (await realOrResolved(want)) === target) {
-        records[key] = { runtime: "claude", target: want };
-        continue;
-      }
-
-      await fs.unlink(link);
-      changed = true;
-    }
-  }
-
-  for (const [key, target] of wanted) {
-    const link = path.join(repoRoot, ...key.split("/"));
-    const existingLink = await fs.lstat(link).catch(() => null);
-    if (existingLink) continue;
-    await fs.mkdir(path.dirname(link), { recursive: true });
-    if (key.startsWith(".claude/agents/")) await fs.symlink(target, link, "file");
-    else await createSkillLink(target, link);
-    records[key] = { runtime: "claude", target };
-    changed = true;
-  }
-
-  if (changed || !enabled) {
-    for (const { dir } of linkDirs) await pruneEmptyAncestors(dir, repoRoot);
-  }
-  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));
+  return reconcileClaudeLinks(SKILLS, repoPath, companionPath, enabled, registeredCompanionPaths);
 }
 
-export async function removeWorkingRepoClaudeSkillLinks(
+export function removeWorkingRepoClaudeSkillLinks(
   repoPath: string,
   registeredCompanionPaths: string[] = [],
 ): Promise<"removed" | "absent"> {
-  const result = await reconcileWorkingRepoClaudeSkillLinks(
-    repoPath,
-    null,
-    false,
-    registeredCompanionPaths,
-  );
-  return result === "written" ? "removed" : "absent";
+  return removeClaudeLinks(SKILLS, repoPath, registeredCompanionPaths);
 }

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

@@ -27,6 +27,10 @@ import {
   workingRepoCapabilityExcludesPresent,
 } from "../../tools/setup/working-repo-local-state";
 import { companionLinkPresent, linkCompanion, unlinkCompanion } from "./projection-companion-link";
+import {
+  reconcileWorkingRepoClaudeCommandLinks,
+  removeWorkingRepoClaudeCommandLinks,
+} from "./projection-claude-commands";
 import {
   reconcileWorkingRepoClaudeSkillLinks,
   removeWorkingRepoClaudeSkillLinks,
@@ -147,6 +151,23 @@ async function writeRuntimeDocumentEntry(
   };
 }
 
+/** Links a companion `.claude/` folder's entries when the companion allows Claude. */
+async function writeClaudeLinkEntry(
+  input: ProjectionInput,
+  reconcile: typeof reconcileWorkingRepoClaudeSkillLinks,
+): Promise<ProjectionWriteState> {
+  if (!input.config) return "skipped";
+  const registeredCompanionPaths = input.globalConfigStore
+    ? await input.globalConfigStore.list()
+    : [];
+  return reconcile(
+    input.repoPath,
+    input.companionPath ?? null,
+    input.config.allowedAgents?.includes("claude") ?? false,
+    registeredCompanionPaths,
+  );
+}
+
 function tokensaveEnabled(input: ProjectionInput): boolean {
   return (input.config?.capabilities ?? []).some((capability) => capability.name === "tokensave");
 }
@@ -297,25 +318,32 @@ function buildEntries(): readonly ProjectionEntry[] {
       scopes: ["wrap"],
       runtime: "claude",
       removeOnUnwrap: true,
-      write: async (input) => {
-        if (!input.config) return "skipped";
-        const registeredCompanionPaths = input.globalConfigStore
-          ? await input.globalConfigStore.list()
-          : [];
-        return reconcileWorkingRepoClaudeSkillLinks(
-          input.repoPath,
-          input.companionPath ?? null,
-          input.config.allowedAgents?.includes("claude") ?? false,
-          registeredCompanionPaths,
-          input.audienceLayerDir ?? null,
-        );
-      },
+      write: (input) => writeClaudeLinkEntry(input, reconcileWorkingRepoClaudeSkillLinks),
       removal: {
         by: "self",
         remove: (input) =>
           removeWorkingRepoClaudeSkillLinks(input.repoPath, input.registeredCompanionPaths ?? []),
       },
     },
+    /**
+     * A wrapped repository reaches its companion through
+     * `permissions.additionalDirectories`, from which Claude loads no commands,
+     * so the companion's commands must be linked in like the skills.
+     */
+    {
+      id: "claude-command-links",
+      kind: "merged",
+      path: path.join(".claude", "commands"),
+      scopes: ["wrap"],
+      runtime: "claude",
+      removeOnUnwrap: true,
+      write: (input) => writeClaudeLinkEntry(input, reconcileWorkingRepoClaudeCommandLinks),
+      removal: {
+        by: "self",
+        remove: (input) =>
+          removeWorkingRepoClaudeCommandLinks(input.repoPath, input.registeredCompanionPaths ?? []),
+      },
+    },
     /**
      * Deliberately outside the managed block, so a Capability's exclusion
      * survives a core-block rewrite — and therefore survives `unproject` too,
@@ -385,9 +413,11 @@ function buildEntries(): readonly ProjectionEntry[] {
       path: path.join(localDir, WORKSPACE_DOCUMENT_FILE),
       scopes: ["workspace"],
       write: async (input) => {
-        if (!input.companionPath) return "skipped";
+        const companionPaths =
+          input.workspaceCompanionPaths ?? (input.companionPath ? [input.companionPath] : []);
+        if (companionPaths.length === 0) return "skipped";
         const target = workspaceDocumentPath(input.repoPath);
-        const folders = [path.resolve(input.repoPath), path.resolve(input.companionPath)];
+        const folders = [input.repoPath, ...companionPaths].map((folder) => path.resolve(folder));
         const next = `${JSON.stringify({ folders: folders.map((candidate) => ({ path: candidate })) }, null, 2)}\n`;
         if ((await fs.readFile(target, "utf8").catch(() => null)) === next) return "current";
         await fs.mkdir(path.dirname(target), { recursive: true });

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

@@ -165,14 +165,19 @@ function applyRegion(document: Record<string, unknown>, region: ManagedRegion):
     return;
   }
   if (region.kind === "map") {
-    const found = isRecord(container[key]) ? (container[key] as Record<string, unknown>) : {};
+    const present = isRecord(container[key]);
+    const found = present ? (container[key] as Record<string, unknown>) : {};
     /** Keys an older Mate wrote here, dropped before this Mate's own are set. */
     const existing = region.stripPrefix
       ? Object.fromEntries(
           Object.entries(found).filter(([name]) => !name.startsWith(region.stripPrefix!)),
         )
       : found;
-    container[key] = { ...existing, ...region.entries };
+    const next = { ...existing, ...region.entries };
+    /** A map only stripped is not created, and one stripped bare is not left as `{}`. */
+    if (Object.keys(next).length > 0) container[key] = next;
+    else if (present && Object.keys(found).length > 0) delete container[key];
+    else if (!present) pruneEmptyContainers(document, region.at);
     return;
   }
   const existing = Array.isArray(container[key]) ? (container[key] as unknown[]) : [];
@@ -212,10 +217,14 @@ function revertRegion(document: Record<string, unknown>, region: ManagedRegion):
     }
   }
 
-  /** An emptied container Mate created is not left behind as `{}`. */
-  for (let depth = region.at.length - 1; depth > 0; depth -= 1) {
-    const parent = containerFor(document, region.at.slice(0, depth), false);
-    const parentKey = region.at[depth - 1];
+  pruneEmptyContainers(document, region.at);
+}
+
+/** An emptied container Mate created is not left behind as `{}`. */
+function pruneEmptyContainers(document: Record<string, unknown>, at: string[]): void {
+  for (let depth = at.length - 1; depth > 0; depth -= 1) {
+    const parent = containerFor(document, at.slice(0, depth), false);
+    const parentKey = at[depth - 1];
     const node = parent?.[parentKey];
     if (parent && isRecord(node) && Object.keys(node).length === 0) delete parent[parentKey];
   }