@uniqbit/mate-core 0.15.4 → 0.15.5-canary.1

package/src/lib/orchestrator/{working-repo-store.ts → companion-registry-store.ts}

@@ -3,18 +3,25 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../framework";
 import { migrateRegistryData } from "./migration";
 import { YamlFileStore } from "./yaml-file-store";
-import { ConfigError, type WorkingRepoConfig } from "./types";
+import { ConfigError, type CompanionRegistryConfig } from "./types";
 
-export function getDefaultWorkingRepoPath(): string {
+export function getDefaultCompanionRegistryPath(): string {
   return `.${FRAMEWORK_NAME}/config/registry.yaml`;
 }
 
-export class WorkingRepoStore extends YamlFileStore<WorkingRepoConfig> {
-  constructor(configPath = getDefaultWorkingRepoPath()) {
+/**
+ * Companion-side reverse index (`{ repos: [...] }`) at
+ * `<companion>/.mate/config/registry.yaml` — distinct from the repo-local
+ * cache ({@link RepoLocalRegistryStore}) despite the shared "registry.yaml"
+ * filename. Renamed from `WorkingRepoStore`: every call site pointed this
+ * at a companion's config dir, never an actual working repo.
+ */
+export class CompanionRegistryStore extends YamlFileStore<CompanionRegistryConfig> {
+  constructor(configPath = getDefaultCompanionRegistryPath()) {
     super(path.resolve(configPath));
   }
 
-  override async load(): Promise<WorkingRepoConfig> {
+  override async load(): Promise<CompanionRegistryConfig> {
     await migrateRegistryData(this.configPath);
     const config = await super.load();
     // Silently drop legacy per-repo policy fields (profile/overrides); the
@@ -25,13 +32,13 @@ export class WorkingRepoStore extends YamlFileStore<WorkingRepoConfig> {
     };
   }
 
-  protected async onMissing(): Promise<WorkingRepoConfig> {
+  protected async onMissing(): Promise<CompanionRegistryConfig> {
     throw new ConfigError(
       `Working repo config not found. Please run \`${FRAMEWORK_NAME} companion setup\` to initialize the framework.`,
     );
   }
 
-  static defaultConfig(): WorkingRepoConfig {
+  static defaultConfig(): CompanionRegistryConfig {
     return { repos: [] };
   }
 }

package/src/lib/orchestrator/companion-resolver.ts

@@ -3,10 +3,12 @@ import path from "node:path";
 
 import { parse } from "yaml";
 
+import { readCompanionRegistry } from "./companion-registry-reader";
 import type { GlobalConfigStore } from "./global-config-store";
 import {
   findRepoLocalRegistryFile,
   pathIsDirectory,
+  repoLocalRegistryPath,
   type RepoLocalCompanionPointer,
   RepoLocalRegistryStore,
 } from "./repo-local-registry";
@@ -36,7 +38,7 @@ export interface CompanionResolutionResult {
 }
 
 export class CompanionResolver {
-  constructor(_globalConfigStore: GlobalConfigStore) {}
+  constructor(private readonly globalConfigStore: GlobalConfigStore) {}
 
   async resolve(cwd: string): Promise<CompanionMatch | null> {
     return (await this.resolveWithDiagnostics(cwd, { logFailures: true })).match;
@@ -49,7 +51,53 @@ export class CompanionResolver {
     const resolvedCwd = path.resolve(cwd);
 
     const repoLocalResult = await this.resolveFromRepoLocalRegistry(resolvedCwd, options);
-    return repoLocalResult ?? { match: null, ambiguousMatches: [], failures: [] };
+    if (repoLocalResult) return repoLocalResult;
+
+    return this.resolveFromGlobalRegistry(resolvedCwd);
+  }
+
+  /**
+   * Fallback for when the repo-local cache is missing or unusable: scans
+   * every companion the global registry knows about and matches by
+   * repository path. A single match self-heals the repo-local cache so the
+   * fast path succeeds on the next resolution without repeating this scan.
+   */
+  private async resolveFromGlobalRegistry(resolvedCwd: string): Promise<CompanionResolutionResult> {
+    const candidates = await this.globalConfigStore.list();
+    const found = await Promise.all(
+      candidates.map(async (candidate) => {
+        const companionPath = path.resolve(candidate);
+        try {
+          const { repos } = await readCompanionRegistry(companionPath);
+          const repo = repos.find((r) => path.resolve(r.path) === resolvedCwd);
+          return repo ? { companionPath, repositoryId: repo.id } : null;
+        } catch {
+          return null;
+        }
+      }),
+    );
+
+    const seenCompanionPaths = new Set<string>();
+    const matches = found.filter((match): match is CompanionMatch => {
+      if (!match || seenCompanionPaths.has(match.companionPath)) return false;
+      seenCompanionPaths.add(match.companionPath);
+      return true;
+    });
+
+    if (matches.length === 0) return { match: null, ambiguousMatches: [], failures: [] };
+
+    if (matches.length === 1) {
+      const store = new RepoLocalRegistryStore(repoLocalRegistryPath(resolvedCwd));
+      await store.save({
+        companions: [{ path: matches[0]!.companionPath, repositoryId: matches[0]!.repositoryId }],
+      });
+    }
+
+    return {
+      match: matches[0]!,
+      ambiguousMatches: matches.length > 1 ? matches : [],
+      failures: [],
+    };
   }
 
   /**

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

@@ -1,15 +1,25 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { FRAMEWORK_NAME } from "../../framework";
+import { CompanionRegistryStore } from "./companion-registry-store";
 import { ConfigStore } from "./config-store";
-import { writeRepoLocalRegistryEntry } from "./repo-local-registry";
+import { pathIsDirectory, writeRepoLocalRegistryEntry } from "./repo-local-registry";
 import { type CompanionSource, ConfigError, type LinkedRepository } from "./types";
-import { WorkingRepoStore } from "./working-repo-store";
+
+/** Builds a {@link CompanionStore} whose config/registry files live under `<companionPath>/.mate/config`, regardless of `process.cwd()`. */
+export function companionRootedStore(companionPath: string): CompanionStore {
+  const configDir = path.join(path.resolve(companionPath), `.${FRAMEWORK_NAME}`, "config");
+  return new CompanionStore(
+    new ConfigStore(path.join(configDir, "framework.yaml")),
+    new CompanionRegistryStore(path.join(configDir, "registry.yaml")),
+  );
+}
 
 export class CompanionStore {
   constructor(
     private readonly configStore = new ConfigStore(),
-    private readonly workingRepoStore = new WorkingRepoStore(),
+    private readonly companionRegistryStore = new CompanionRegistryStore(),
   ) {}
 
   async registerRepository(
@@ -23,14 +33,33 @@ export class CompanionStore {
       );
     }
 
-    const working = await this.workingRepoStore.load();
-    const existing = working.repos.findIndex((r) => r.id === repository.id);
+    // A companion's registry.yaml may not exist yet (its first-ever link):
+    // that is not a real error here, unlike a working repo reading its own
+    // missing config, so fall back to an empty registry instead of throwing.
+    const working = await this.companionRegistryStore.load().catch((error) => {
+      if (error instanceof ConfigError) return CompanionRegistryStore.defaultConfig();
+      throw error;
+    });
+
+    // Prune dead entries (path no longer a directory) as part of this same
+    // write, piggybacking on the load/save that registration already does
+    // rather than adding a separate scan; never runs on a read-only list.
+    const checked = await Promise.all(
+      working.repos.map(async (repo) => ({ repo, exists: await pathIsDirectory(repo.path) })),
+    );
+    const survivors: LinkedRepository[] = [];
+    for (const entry of checked) {
+      if (entry.exists) survivors.push(entry.repo);
+    }
+
+    const existing = survivors.findIndex((r) => r.id === repository.id);
     if (existing >= 0) {
-      working.repos[existing] = repository;
+      survivors[existing] = repository;
     } else {
-      working.repos.push(repository);
+      survivors.push(repository);
     }
-    await this.workingRepoStore.save(working);
+    working.repos = survivors;
+    await this.companionRegistryStore.save(working);
 
     // Repo-local registry write is a cache, not the source of truth: the
     // companion-side write above already succeeded, so a failure here (e.g. a
@@ -54,12 +83,12 @@ export class CompanionStore {
   }
 
   async getRepository(repositoryId: string): Promise<LinkedRepository | undefined> {
-    const working = await this.workingRepoStore.load();
+    const working = await this.companionRegistryStore.load();
     return working.repos.find((r) => r.id === repositoryId);
   }
 
   async listRepositories(): Promise<LinkedRepository[]> {
-    const working = await this.workingRepoStore.load();
+    const working = await this.companionRegistryStore.load();
     return working.repos;
   }
 }

package/src/lib/orchestrator/editor.ts

@@ -140,6 +140,39 @@ export function detectEditorWorkspaceState(
   }
 }
 
+export interface WorkspaceDocument {
+  workspacePath: string;
+  folders: [string, string];
+}
+
+/**
+ * Writes the generated `.mate/workspace.code-workspace` file (working
+ * repository first, companion second) and returns its path and folder
+ * order. Shared by editor-launching `injectEditorFolder` and the
+ * non-launching `workspace materialize` command — both must produce the
+ * same document for the same pairing.
+ */
+export async function writeWorkspaceDocument(
+  companionPath: string,
+  repoPath: string,
+): Promise<WorkspaceDocument> {
+  const folders: [string, string] = [path.resolve(repoPath), path.resolve(companionPath)];
+  const workspacePath = editorWorkspacePath(repoPath);
+  await fs.mkdir(path.dirname(workspacePath), { recursive: true });
+  await fs.writeFile(
+    workspacePath,
+    `${JSON.stringify(
+      {
+        folders: folders.map((candidate) => ({ path: candidate })),
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  return { workspacePath, folders };
+}
+
 export async function injectEditorFolder(
   companionPath: string,
   repoPath: string,
@@ -163,20 +196,9 @@ export async function injectEditorFolder(
 
   const { cli: resolvedCli, binary } = resolved;
 
-  const workspaceFolders = [path.resolve(repoPath), path.resolve(companionPath)];
-
-  const workspacePath = editorWorkspacePath(repoPath);
-  await fs.mkdir(path.dirname(workspacePath), { recursive: true });
-  await fs.writeFile(
-    workspacePath,
-    `${JSON.stringify(
-      {
-        folders: workspaceFolders.map((candidate) => ({ path: candidate })),
-      },
-      null,
-      2,
-    )}\n`,
-    "utf8",
+  const { workspacePath, folders: workspaceFolders } = await writeWorkspaceDocument(
+    companionPath,
+    repoPath,
   );
 
   if (detectWorkspace(workspacePath, resolvedCli) === "open") return true;

package/src/lib/orchestrator/framework-context.ts

@@ -3,7 +3,10 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../framework";
 import { parse } from "yaml";
+import { CompanionRegistryStore } from "./companion-registry-store";
 import { CompanionResolver } from "./companion-resolver";
+import { companionRootedStore } from "./companion-store";
+import { readCompanionRegistry } from "./companion-registry-reader";
 import { ConfigStore } from "./config-store";
 import { GlobalConfigStore } from "./global-config-store";
 import { findRepoLocalLinkedRepository } from "./repo-local-registry";
@@ -16,11 +19,10 @@ import {
   RepositoryNotFoundError,
   WorkingRepoRequiredError,
 } from "./types";
-import { WorkingRepoStore } from "./working-repo-store";
 
 export interface FrameworkContext {
   configStore: ConfigStore;
-  workingRepoStore: WorkingRepoStore;
+  workingRepoStore: CompanionRegistryStore;
   companionPath: string;
   repository?: LinkedRepository;
   contextKind: "env" | "working-repo" | "companion-root" | "hub";
@@ -52,7 +54,7 @@ function makeContext(
   const configDir = path.join(companionPath, `.${FRAMEWORK_NAME}`, "config");
   return {
     configStore: new ConfigStore(path.join(configDir, "framework.yaml")),
-    workingRepoStore: new WorkingRepoStore(path.join(configDir, "registry.yaml")),
+    workingRepoStore: new CompanionRegistryStore(path.join(configDir, "registry.yaml")),
     companionPath,
     repository,
     contextKind,
@@ -212,6 +214,9 @@ export async function resolveForLaunch(
 
   if (resolution.match) {
     const repository = (await findRepoLocalLinkedRepository(cwd)) ?? undefined;
+    if (repository) {
+      await backfillCompanionRegistration(resolution.match.companionPath, repository);
+    }
     const context = await withResolvedHub(
       makeContext(resolution.match.companionPath, "working-repo", repository),
     );
@@ -224,6 +229,31 @@ export async function resolveForLaunch(
   throw new WorkingRepoRequiredError();
 }
 
+/**
+ * Self-heals repos linked before the companion-side registry write existed
+ * (or whose companion registry was reset): backfills the companion-side
+ * entry from the already-trusted repo-local pointer on every launch
+ * resolution. Best-effort — never blocks a launch.
+ */
+async function backfillCompanionRegistration(
+  companionPath: string,
+  repository: LinkedRepository,
+): Promise<void> {
+  try {
+    const { repos } = await readCompanionRegistry(companionPath).catch(() => ({ repos: [] }));
+    const existing = repos.find((repo) => repo.id === repository.id);
+    if (existing?.path === repository.path) return;
+
+    await companionRootedStore(companionPath).registerRepository(repository);
+  } catch (error) {
+    console.error(
+      `${FRAMEWORK_NAME}: warning: failed to backfill companion registry for ${repository.id}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+}
+
 // Resolves context for `mate cap` commands. Unlike resolveForLaunch, this allows
 // running from the companion directory itself — cap commands manage companion state
 // and don't need a working-repo cwd. resolveForLaunch intentionally lacks this

package/src/lib/orchestrator/global-config-store.ts

@@ -2,6 +2,7 @@ import os from "node:os";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../framework";
+import { pathIsDirectory } from "./repo-local-registry";
 import { YamlFileStore } from "./yaml-file-store";
 
 interface CompanionEntry {
@@ -50,4 +51,28 @@ export class GlobalConfigStore extends YamlFileStore<GlobalConfig> {
       await this.save(config);
     }
   }
+
+  /**
+   * One-time/idempotent hygiene pass: drops entries whose path is not a
+   * directory on disk (stale test-fixture pollution, removed companions).
+   * Safe to call repeatedly — a clean registry is left unchanged and unsaved.
+   */
+  async prune(): Promise<{ removed: string[] }> {
+    const config = await this.load();
+    const checked = await Promise.all(
+      config.companions.map(async (c) => ({ path: c.path, exists: await pathIsDirectory(c.path) })),
+    );
+
+    const removed: string[] = [];
+    const kept: CompanionEntry[] = [];
+    for (const entry of checked) {
+      if (entry.exists) kept.push({ path: entry.path });
+      else removed.push(entry.path);
+    }
+    if (removed.length === 0) return { removed };
+
+    config.companions = kept;
+    await this.save(config);
+    return { removed };
+  }
 }

package/src/lib/orchestrator/repo-local-registry.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import { parse, stringify } from "yaml";
 
 import { FRAMEWORK_NAME } from "../../framework";
-import { resolveGitInfoExcludePath } from "../../tools/setup/git-utils";
+import { ensureWorkingRepoLocalExcludes } from "../../tools/setup/working-repo-local-state";
 import { YamlFileStore } from "./yaml-file-store";
 import type { CompanionSource, LinkedRepository } from "./types";
 
@@ -20,7 +20,6 @@ export interface RepoLocalRegistry {
 }
 
 const repoLocalDirName = () => `.${FRAMEWORK_NAME}`;
-const repoLocalExcludeEntry = () => `${repoLocalDirName()}/`;
 const repoLocalScanSkipDirNames = () =>
   new Set([
     ".git",
@@ -59,26 +58,7 @@ export class RepoLocalRegistryStore extends YamlFileStore<RepoLocalRegistry> {
  * never needs a tracked `.gitignore` entry, mirroring `ensureTokensaveStoreExcluded`.
  */
 export async function ensureRepoLocalDirExcluded(repoPath: string): Promise<void> {
-  const excludePath = await resolveGitInfoExcludePath(repoPath);
-  if (!excludePath) return;
-
-  let existing = "";
-  try {
-    existing = await fs.readFile(excludePath, "utf8");
-  } catch {
-    // Fresh repos may not have created info/exclude yet.
-  }
-
-  const lines = existing
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-
-  if (lines.includes(repoLocalExcludeEntry())) return;
-
-  lines.push(repoLocalExcludeEntry());
-  await fs.mkdir(path.dirname(excludePath), { recursive: true });
-  await fs.writeFile(excludePath, lines.join("\n") + "\n", "utf8");
+  await ensureWorkingRepoLocalExcludes(repoPath);
 }
 
 /** Writes `.mate/config/framework.yaml` with `type: "working"` if it does not already exist. */

package/src/lib/orchestrator/types.ts

@@ -123,7 +123,7 @@ export interface FrameworkConfig {
   engines?: EngineConstraints;
 }
 
-export interface WorkingRepoConfig {
+export interface CompanionRegistryConfig {
   repos: LinkedRepository[];
 }
 

package/src/lib/orchestrator/workspace-inventory.ts

@@ -0,0 +1,149 @@
+import path from "node:path";
+
+import { pathIsDirectory } from "./repo-local-registry";
+import { readCompanionRegistry } from "./companion-registry-reader";
+import { GlobalConfigStore } from "./global-config-store";
+import type { LinkedRepository } from "./types";
+
+/** Envelope version for `mate workspace list --json`; bump on any breaking shape change. */
+export const WORKSPACE_INVENTORY_SCHEMA_VERSION = 1;
+
+export type CompanionInventoryHealth = "ready" | "missing" | "unreadable";
+export type PairingInventoryHealth =
+  | "ready"
+  | "missing-companion"
+  | "missing-repository"
+  | "unreadable";
+
+export interface WorkspaceInventoryCompanionEntry {
+  path: string;
+  health: CompanionInventoryHealth;
+  diagnostic?: string;
+}
+
+export interface WorkspaceInventoryPairingEntry {
+  companionPath: string;
+  repository: LinkedRepository;
+  health: PairingInventoryHealth;
+  ambiguous: boolean;
+  diagnostic?: string;
+}
+
+export interface WorkspaceInventoryV1 {
+  schemaVersion: 1;
+  companions: WorkspaceInventoryCompanionEntry[];
+  pairings: WorkspaceInventoryPairingEntry[];
+}
+
+export interface WorkspaceInventoryDeps {
+  listCompanionPaths: () => Promise<string[]>;
+  isDirectory: (candidatePath: string) => Promise<boolean>;
+  readCompanionRegistry: typeof readCompanionRegistry;
+}
+
+export function defaultWorkspaceInventoryDeps(
+  globalConfigStore = new GlobalConfigStore(),
+): WorkspaceInventoryDeps {
+  return {
+    listCompanionPaths: () => globalConfigStore.list(),
+    isDirectory: pathIsDirectory,
+    readCompanionRegistry,
+  };
+}
+
+interface CompanionScanResult {
+  companionPath: string;
+  health: CompanionInventoryHealth;
+  diagnostic?: string;
+  repos: LinkedRepository[];
+}
+
+async function scanCompanion(
+  companionPath: string,
+  deps: WorkspaceInventoryDeps,
+): Promise<CompanionScanResult> {
+  if (!(await deps.isDirectory(companionPath))) {
+    return { companionPath, health: "missing", repos: [] };
+  }
+
+  try {
+    const { repos } = await deps.readCompanionRegistry(companionPath);
+    return { companionPath, health: "ready", repos };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { companionPath, health: "ready", repos: [] };
+    }
+    return {
+      companionPath,
+      health: "unreadable",
+      diagnostic: error instanceof Error ? error.message : String(error),
+      repos: [],
+    };
+  }
+}
+
+/**
+ * Read-only aggregate over the global companion registry and each
+ * companion's own linked-repository registry. Never migrates, repairs, or
+ * removes registry state — partial failures are reported as data.
+ */
+export async function collectWorkspaceInventory(
+  deps: WorkspaceInventoryDeps = defaultWorkspaceInventoryDeps(),
+): Promise<WorkspaceInventoryV1> {
+  const companionPaths = [
+    ...new Set((await deps.listCompanionPaths()).map((p) => path.resolve(p))),
+  ];
+
+  const scans = await Promise.all(
+    companionPaths.map((companionPath) => scanCompanion(companionPath, deps)),
+  );
+
+  const repoPathsByCompanion = new Map<string, Set<string>>();
+  for (const scan of scans) {
+    for (const repo of scan.repos) {
+      const repoPath = path.resolve(repo.path);
+      const companions = repoPathsByCompanion.get(repoPath) ?? new Set<string>();
+      companions.add(scan.companionPath);
+      repoPathsByCompanion.set(repoPath, companions);
+    }
+  }
+
+  const repoExistence = new Map<string, boolean>();
+  await Promise.all(
+    [...repoPathsByCompanion.keys()].map(async (repoPath) => {
+      repoExistence.set(repoPath, await deps.isDirectory(repoPath));
+    }),
+  );
+
+  const companions: WorkspaceInventoryCompanionEntry[] = scans.map((scan) => ({
+    path: scan.companionPath,
+    health: scan.health,
+    ...(scan.diagnostic ? { diagnostic: scan.diagnostic } : {}),
+  }));
+
+  const pairings: WorkspaceInventoryPairingEntry[] = scans.flatMap((scan) =>
+    scan.repos.map((repo) => {
+      const repoPath = path.resolve(repo.path);
+      const ambiguous = (repoPathsByCompanion.get(repoPath)?.size ?? 0) > 1;
+      const health: PairingInventoryHealth = repoExistence.get(repoPath)
+        ? "ready"
+        : "missing-repository";
+      return {
+        companionPath: scan.companionPath,
+        repository: { id: repo.id, path: repoPath },
+        health,
+        ambiguous,
+      };
+    }),
+  );
+
+  companions.sort((a, b) => a.path.localeCompare(b.path));
+  pairings.sort(
+    (a, b) =>
+      a.companionPath.localeCompare(b.companionPath) ||
+      a.repository.id.localeCompare(b.repository.id) ||
+      a.repository.path.localeCompare(b.repository.path),
+  );
+
+  return { schemaVersion: WORKSPACE_INVENTORY_SCHEMA_VERSION, companions, pairings };
+}

package/src/lib/orchestrator/workspace-materialize.ts

@@ -0,0 +1,80 @@
+import path from "node:path";
+
+import { readCompanionRegistry } from "./companion-registry-reader";
+import { pathIsDirectory } from "./repo-local-registry";
+import { MateError } from "./types";
+import { writeWorkspaceDocument } from "./editor";
+
+/** Envelope version for `mate workspace materialize --json`. */
+export const MATERIALIZED_WORKSPACE_SCHEMA_VERSION = 1;
+
+export interface MaterializedWorkspaceV1 {
+  schemaVersion: 1;
+  workspacePath: string;
+  folders: [string, string];
+}
+
+export class WorkspacePairingNotFoundError extends MateError {
+  constructor(repositoryId: string, companionPath: string) {
+    super(`mate: repository "${repositoryId}" is not linked by companion: ${companionPath}`);
+  }
+}
+
+export class WorkspaceRootUnavailableError extends MateError {
+  constructor(
+    readonly root: "companion" | "repository",
+    readonly rootPath: string,
+  ) {
+    super(`mate: ${root} path does not exist: ${rootPath}`);
+  }
+}
+
+export interface MaterializeWorkspaceRequest {
+  repositoryId: string;
+  companionPath: string;
+}
+
+export interface MaterializeWorkspaceDeps {
+  isDirectory: (candidatePath: string) => Promise<boolean>;
+  readCompanionRegistry: typeof readCompanionRegistry;
+  writeWorkspaceDocument: typeof writeWorkspaceDocument;
+}
+
+export function defaultMaterializeWorkspaceDeps(): MaterializeWorkspaceDeps {
+  return { isDirectory: pathIsDirectory, readCompanionRegistry, writeWorkspaceDocument };
+}
+
+/**
+ * Resolves an explicit companion-path/repository-id pairing, validates both
+ * roots exist, and writes the shared workspace document — without touching
+ * the registry or spawning an editor. Distinct from `injectEditorFolder`,
+ * which additionally launches/reloads an editor CLI.
+ */
+export async function materializeWorkspace(
+  request: MaterializeWorkspaceRequest,
+  deps: MaterializeWorkspaceDeps = defaultMaterializeWorkspaceDeps(),
+): Promise<MaterializedWorkspaceV1> {
+  const companionPath = path.resolve(request.companionPath);
+
+  if (!(await deps.isDirectory(companionPath))) {
+    throw new WorkspaceRootUnavailableError("companion", companionPath);
+  }
+
+  const { repos } = await deps.readCompanionRegistry(companionPath).catch(() => ({ repos: [] }));
+  const repository = repos.find((repo) => repo.id === request.repositoryId);
+  if (!repository) {
+    throw new WorkspacePairingNotFoundError(request.repositoryId, companionPath);
+  }
+
+  const repositoryPath = path.resolve(repository.path);
+  if (!(await deps.isDirectory(repositoryPath))) {
+    throw new WorkspaceRootUnavailableError("repository", repositoryPath);
+  }
+
+  const { workspacePath, folders } = await deps.writeWorkspaceDocument(
+    companionPath,
+    repositoryPath,
+  );
+
+  return { schemaVersion: MATERIALIZED_WORKSPACE_SCHEMA_VERSION, workspacePath, folders };
+}