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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniqbit/mate-core",
-  "version": "0.15.5-canary.0",
+  "version": "0.15.5-canary.1",
   "description": "Core framework and plugin APIs for Mate.",
   "license": "MIT",
   "files": [

package/src/cli/commands/artifact/finish/openspec.ts

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { parse } from "yaml";
+
 import { hasOpenspecCapability } from "../../../../lib/orchestrator/capabilities";
 import { runIndexCapCommand } from "../../cap/index-cmd";
 import type { ArtifactFinisher, FinishContext } from "./finisher";
@@ -57,6 +59,171 @@ async function commitPathsForArchive(
   ];
 }
 
+const BOM = "";
+
+interface ScopePair {
+  repository: string;
+  area: string;
+}
+
+type ProjectionResult =
+  | { ok: true; repository: string; areas: string[] }
+  | { ok: false; reason: string };
+
+function parseDeltaScopes(source: string): ScopePair[] {
+  const text = source.startsWith(BOM) ? source.slice(BOM.length) : source;
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!match) return [];
+
+  try {
+    const parsed = parse(match[1]) as unknown;
+    if (!parsed || typeof parsed !== "object") return [];
+    const scopes = (parsed as Record<string, unknown>).scopes;
+    if (!Array.isArray(scopes)) return [];
+    return scopes.flatMap((entry) => {
+      if (!entry || typeof entry !== "object") return [];
+      const pair = entry as Record<string, unknown>;
+      return typeof pair.repository === "string" && typeof pair.area === "string"
+        ? [{ repository: pair.repository, area: pair.area }]
+        : [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+function projectDeltaScopes(scopes: ScopePair[]): ProjectionResult {
+  if (scopes.length === 0) return { ok: false, reason: "delta declares no scopes entries" };
+  const repositories = [...new Set(scopes.map((entry) => entry.repository))];
+  if (repositories.length > 1) {
+    return {
+      ok: false,
+      reason: `delta names ${repositories.length} repositories (${repositories.join(", ")}); a spec names exactly one`,
+    };
+  }
+  return {
+    ok: true,
+    repository: repositories[0],
+    areas: [...new Set(scopes.map((entry) => entry.area))],
+  };
+}
+
+async function archivedChangeUsesMateV1(
+  companionPath: string,
+  anchorName: string,
+): Promise<boolean> {
+  try {
+    const metadataPath = path.join(
+      companionPath,
+      "openspec",
+      "changes",
+      "archive",
+      anchorName,
+      ".openspec.yaml",
+    );
+    const parsed = parse(await fs.readFile(metadataPath, "utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object") return false;
+    const schema = (parsed as Record<string, unknown>).schema;
+    return typeof schema === "string" && schema.trim() === "mate-v1";
+  } catch {
+    return false;
+  }
+}
+
+/** Scope keys are omitted when the delta had none — a partial block beats no frontmatter. */
+function renderCanonicalFrontmatter(
+  capability: string,
+  scope: { repository: string; areas: string[] } | null,
+): string {
+  return [
+    "---",
+    "type: spec",
+    `capability: ${capability}`,
+    ...(scope ? [`repository: ${scope.repository}`, `areas: [${scope.areas.join(", ")}]`] : []),
+    "tags: [openspec/spec]",
+    "---",
+    "",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Prepends canonical frontmatter to main specs born during this archive.
+ *
+ * `openspec archive` rebuilds a brand-new main spec from a skeleton with no frontmatter slot,
+ * so scope metadata dies exactly once, at spec birth; existing specs keep theirs because only
+ * requirement blocks are spliced. Best-effort by design — the archive already succeeded, so a
+ * failure here warns rather than stranding the change archived-but-unfinished.
+ */
+async function reconcileMainSpecFrontmatter(
+  companionPath: string,
+  anchorName: string,
+): Promise<string[]> {
+  if (!(await archivedChangeUsesMateV1(companionPath, anchorName))) return [];
+
+  const deltaSpecsDir = path.join(
+    companionPath,
+    "openspec",
+    "changes",
+    "archive",
+    anchorName,
+    "specs",
+  );
+  const reconciled: string[] = [];
+
+  const walk = async (directory: string, relative = ""): Promise<void> => {
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const entryRelative = path.posix.join(relative, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path.join(directory, entry.name), entryRelative);
+        continue;
+      }
+      if (!entry.isFile() || entry.name !== "spec.md") continue;
+
+      const capability = path.posix.dirname(entryRelative);
+      if (capability === ".") continue;
+      const canonicalRelative = path.posix.join("openspec", "specs", entryRelative);
+      const canonicalPath = path.join(companionPath, canonicalRelative);
+
+      try {
+        const canonical = await fs.readFile(canonicalPath, "utf8");
+        if (canonical.replace(BOM, "").startsWith("---")) continue;
+
+        const deltaSource = await fs.readFile(path.join(directory, entry.name), "utf8");
+        const scopes = parseDeltaScopes(deltaSource);
+        const projected = projectDeltaScopes(scopes);
+
+        /** Multi-repository is invalid input, so skip; absent scopes still earn a partial block. */
+        if (!projected.ok && scopes.length > 0) {
+          process.stderr.write(
+            `mate: skipped frontmatter for ${canonicalRelative}: ${projected.reason}\n`,
+          );
+          continue;
+        }
+        const head = renderCanonicalFrontmatter(
+          capability,
+          projected.ok ? { repository: projected.repository, areas: projected.areas } : null,
+        );
+        await fs.writeFile(canonicalPath, head + canonical.replace(BOM, ""), "utf8");
+        reconciled.push(canonicalRelative);
+      } catch (error) {
+        process.stderr.write(
+          `mate: could not reconcile frontmatter for ${canonicalRelative}: ${String(error)}\n`,
+        );
+      }
+    }
+  };
+
+  await walk(deltaSpecsDir);
+  return reconciled;
+}
+
 async function capSync(context: FinishContext): Promise<boolean> {
   const previous = process.exitCode;
   process.exitCode = 0;
@@ -92,7 +259,10 @@ async function capSync(context: FinishContext): Promise<boolean> {
  * to `openspec/`. Resumable detection reads the dated `openspec/changes/archive/` folder
  * openspec actually created so the tag is never a computed date.
  */
-export function openspecFinisher(contextOrPath: FinishContext | string): ArtifactFinisher {
+export function openspecFinisher(
+  contextOrPath: FinishContext | string,
+  runCommand: typeof run = run,
+): ArtifactFinisher {
   const context: FinishContext =
     typeof contextOrPath === "string"
       ? { companionPath: contextOrPath, repositoryId: "" }
@@ -106,7 +276,7 @@ export function openspecFinisher(contextOrPath: FinishContext | string): Artifac
       return hasOpenspecCapability(capabilities);
     },
     async validate(name) {
-      const res = run(companionPath, ["openspec", "validate", name, "--json"]);
+      const res = runCommand(companionPath, ["openspec", "validate", name, "--json"]);
       try {
         const parsed = JSON.parse(res.stdout) as {
           items?: Array<{ id: string; valid: boolean; issues?: Array<{ message: string }> }>;
@@ -124,7 +294,7 @@ export function openspecFinisher(contextOrPath: FinishContext | string): Artifac
       }
     },
     async isComplete(name) {
-      const res = run(companionPath, ["openspec", "list", "--json"]);
+      const res = runCommand(companionPath, ["openspec", "list", "--json"]);
       try {
         const parsed = JSON.parse(res.stdout) as {
           changes?: Array<{ name: string; completedTasks: number; totalTasks: number }>;
@@ -157,13 +327,12 @@ export function openspecFinisher(contextOrPath: FinishContext | string): Artifac
       }
       // Latest dated folder wins if the same change name was ever archived twice.
       const anchorName = matches[matches.length - 1];
-      return {
-        anchorName,
-        commitPaths: await commitPathsForArchive(companionPath, name, anchorName),
-      };
+      const commitPaths = await commitPathsForArchive(companionPath, name, anchorName);
+      await reconcileMainSpecFrontmatter(companionPath, anchorName);
+      return { anchorName, commitPaths };
     },
     async produce(name) {
-      const res = run(companionPath, ["openspec", "archive", name, "--yes"]);
+      const res = runCommand(companionPath, ["openspec", "archive", name, "--yes"]);
       if (res.status !== 0) {
         return {
           ok: false,
@@ -176,12 +345,11 @@ export function openspecFinisher(contextOrPath: FinishContext | string): Artifac
       if (!match) {
         return { ok: false, produced: null, message: "could not detect archived folder name" };
       }
+      const commitPaths = await commitPathsForArchive(companionPath, name, match[1]);
+      await reconcileMainSpecFrontmatter(companionPath, match[1]);
       return {
         ok: true,
-        produced: {
-          anchorName: match[1],
-          commitPaths: await commitPathsForArchive(companionPath, name, match[1]),
-        },
+        produced: { anchorName: match[1], commitPaths },
         message: res.stdout.trim(),
       };
     },

package/src/cli/commands/companion/link.ts

@@ -12,11 +12,9 @@ import {
 import { extractRepoName } from "../artifact/extract-repo-name";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
 import { CompanionResolver } from "../../../lib/orchestrator/companion-resolver";
+import { companionRootedStore } from "../../../lib/orchestrator/companion-store";
 import { inspectSetupPreflight } from "../../../lib/orchestrator/setup-preflight";
-import {
-  findDescendantRepoLocalRegistries,
-  writeRepoLocalRegistryEntry,
-} from "../../../lib/orchestrator/repo-local-registry";
+import { findDescendantRepoLocalRegistries } from "../../../lib/orchestrator/repo-local-registry";
 import { runSetupFlowAtPath } from "../setup";
 import { runInstallCommand } from "../install";
 import type { CompanionSource, LinkedRepository } from "../../../lib/orchestrator/types";
@@ -240,17 +238,15 @@ export async function runCompanionLinkCommandWithDeps(
     path: cwd,
   };
 
+  // Writes both the companion-side registry entry (companionRootedStore, the
+  // source of truth for `mate workspace list`) and the repo-local pointer
+  // (CompanionStore's internal dual write) in one call.
   const registerRepository =
     deps.registerRepository ??
-    (async (nextRepository, options) => {
-      await writeRepoLocalRegistryEntry(
-        nextRepository.path,
-        options.companionPath,
-        nextRepository,
-        options.companionSource,
-      );
-      return nextRepository;
-    });
+    ((nextRepository, options) =>
+      companionRootedStore(options.companionPath).registerRepository(nextRepository, {
+        companionSource: options.companionSource,
+      }));
 
   // Managed companions are git-backed; explicitly pasted paths retain local provenance.
   const persistedSource: CompanionSource = companionSource === "local" ? "local" : "git";

package/src/cli/commands/working/cleanup.ts

@@ -0,0 +1,125 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { parse } from "yaml";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import type { RootKind } from "../../../lib/orchestrator/root-context";
+import {
+  collectWorkspaceInventory,
+  type WorkspaceInventoryV1,
+} from "../../../lib/orchestrator/workspace-inventory";
+import {
+  cleanupWorkingRepository,
+  type WorkingRepoCleanupResult,
+} from "../../../tools/setup/working-repo-cleanup";
+
+const execFileAsync = promisify(execFile);
+
+async function canonicalPath(candidatePath: string): Promise<string> {
+  try {
+    return await fs.realpath(candidatePath);
+  } catch {
+    return path.resolve(candidatePath);
+  }
+}
+
+export interface WorkingCleanupCommandDeps {
+  cwd: string;
+  resolveGitRoot: (cwd: string) => Promise<string | null>;
+  localRootKind: (repoPath: string) => Promise<RootKind | null>;
+  collectInventory: () => Promise<WorkspaceInventoryV1>;
+  cleanup: (
+    repoPath: string,
+    registeredCompanionPaths: string[],
+  ) => Promise<WorkingRepoCleanupResult>;
+}
+
+async function resolveGitRoot(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync("git", ["-C", cwd, "rev-parse", "--show-toplevel"]);
+    return canonicalPath(stdout.trim());
+  } catch {
+    return null;
+  }
+}
+
+async function localRootKind(repoPath: string): Promise<RootKind | null> {
+  try {
+    const raw = await fs.readFile(
+      path.join(repoPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+      "utf8",
+    );
+    const config = parse(raw) as { type?: string } | null;
+    if (config?.type === "working" || config?.type === "hub") return config.type;
+    return "companion";
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    return "companion";
+  }
+}
+
+const defaultDeps: WorkingCleanupCommandDeps = {
+  cwd: process.cwd(),
+  resolveGitRoot,
+  localRootKind,
+  collectInventory: collectWorkspaceInventory,
+  cleanup: cleanupWorkingRepository,
+};
+
+export async function runWorkingCleanupCommand(
+  argv: string[],
+  deps: WorkingCleanupCommandDeps = defaultDeps,
+): Promise<void> {
+  if (argv.length > 0) {
+    process.stderr.write(`${FRAMEWORK_NAME}: usage: ${FRAMEWORK_NAME} working cleanup\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const repoPath = await deps.resolveGitRoot(deps.cwd);
+  if (!repoPath) {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: working cleanup must run from a linked Git working repository\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const kind = await deps.localRootKind(repoPath);
+  if (kind === "companion" || kind === "hub") {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: working cleanup is unavailable in a ${kind} repository\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const inventory = await deps.collectInventory();
+  const resolvedPairings = await Promise.all(
+    inventory.pairings.map(async (pairing) => ({
+      pairing,
+      repositoryPath: await canonicalPath(pairing.repository.path),
+    })),
+  );
+  const matches = resolvedPairings
+    .filter(({ repositoryPath }) => repositoryPath === repoPath)
+    .map(({ pairing }) => pairing);
+  if (matches.length === 0) {
+    process.stderr.write(
+      `${FRAMEWORK_NAME}: working cleanup must run from a linked Git working repository\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const companionPaths = [...new Set(matches.map((pairing) => pairing.companionPath))];
+  const result = await deps.cleanup(repoPath, companionPaths);
+  if (!result.changed) {
+    console.log(`${FRAMEWORK_NAME}: working repository already clean`);
+    return;
+  }
+  const details = [
+    ...(result.removed.length > 0 ? [`removed: ${result.removed.join(", ")}`] : []),
+    ...(result.updated.length > 0 ? [`updated: ${result.updated.join(", ")}`] : []),
+  ];
+  console.log(`${FRAMEWORK_NAME}: cleaned working repository (${details.join("; ")})`);
+}

package/src/cli/commands/working/working.ts

@@ -0,0 +1,15 @@
+import { usage } from "../../usage";
+import { runWorkingCleanupCommand } from "./cleanup";
+
+export async function runWorkingCommand(
+  subcommand: string | undefined,
+  argv: string[],
+): Promise<void> {
+  if (subcommand === "cleanup") {
+    await runWorkingCleanupCommand(argv);
+    return;
+  }
+  console.error(`Unknown working command: ${subcommand ?? ""}`);
+  console.error(usage());
+  process.exitCode = 1;
+}

package/src/cli/commands/workspace/list.ts

@@ -0,0 +1,25 @@
+import { collectWorkspaceInventory } from "../../../lib/orchestrator/workspace-inventory";
+import { writeJsonStdout } from "../../write-json-stdout";
+
+export const workspaceListCommandDeps = {
+  collectWorkspaceInventory: () => collectWorkspaceInventory(),
+};
+
+/**
+ * @command mate workspace list
+ * @description Prints the aggregate inventory of registered companions and
+ * their linked working-repository pairings as one JSON document. Runs
+ * without a linked working repository or any active companion context.
+ * @flags
+ * - `--json` — required; this command only supports JSON output.
+ */
+export async function runWorkspaceListCommand(argv: string[] = []): Promise<void> {
+  if (!argv.includes("--json")) {
+    process.stderr.write("mate: `workspace list` requires --json.\n");
+    process.exitCode = 1;
+    return;
+  }
+
+  const inventory = await workspaceListCommandDeps.collectWorkspaceInventory();
+  await writeJsonStdout(inventory);
+}

package/src/cli/commands/workspace/materialize.ts

@@ -0,0 +1,46 @@
+import { materializeWorkspace } from "../../../lib/orchestrator/workspace-materialize";
+import { writeJsonStdout } from "../../write-json-stdout";
+
+export const workspaceMaterializeCommandDeps = {
+  materializeWorkspace: (repositoryId: string, companionPath: string) =>
+    materializeWorkspace({ repositoryId, companionPath }),
+};
+
+function readFlag(argv: string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : undefined;
+}
+
+/**
+ * @command mate workspace materialize
+ * @description Validates an explicit repository/companion pairing, writes
+ * the generated `.mate/workspace.code-workspace` file, and prints its path
+ * and folder order as one JSON document. Never spawns or focuses an editor.
+ * @flags
+ * - `--repository <id>` — required; the linked repository id to pair.
+ * - `--companion <path>` — required; the companion path that must link it.
+ * - `--json` — required; this command only supports JSON output.
+ */
+export async function runWorkspaceMaterializeCommand(argv: string[] = []): Promise<void> {
+  const repositoryId = readFlag(argv, "--repository");
+  const companionPath = readFlag(argv, "--companion");
+
+  if (!repositoryId || !companionPath || !argv.includes("--json")) {
+    process.stderr.write(
+      "mate: `workspace materialize` requires --repository <id>, --companion <path>, and --json.\n",
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const result = await workspaceMaterializeCommandDeps.materializeWorkspace(
+      repositoryId,
+      companionPath,
+    );
+    await writeJsonStdout(result);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/cli/commands/workspace/workspace.ts

@@ -0,0 +1,22 @@
+import { usage } from "../../usage";
+import { runWorkspaceListCommand } from "./list";
+import { runWorkspaceMaterializeCommand } from "./materialize";
+
+/** Dispatches `mate workspace <subcommand>`. Distinct from `mate companion open`. */
+export async function runWorkspaceCommand(
+  subcommand: string | undefined,
+  argv: string[],
+): Promise<void> {
+  switch (subcommand) {
+    case "list":
+      await runWorkspaceListCommand(argv);
+      return;
+    case "materialize":
+      await runWorkspaceMaterializeCommand(argv);
+      return;
+    default:
+      console.error(`Unknown workspace command: ${subcommand ?? ""}`);
+      console.error(usage());
+      process.exitCode = 1;
+  }
+}

package/src/cli/main.ts

@@ -17,6 +17,8 @@ import { runLaunchOpenCodeCommand } from "./commands/launch/opencode";
 import { runPluginCommand } from "./commands/plugin/plugin";
 import { runReportCommand } from "./commands/report";
 import { runUpdateCommand } from "./commands/update";
+import { runWorkspaceCommand } from "./commands/workspace/workspace";
+import { runWorkingCommand } from "./commands/working/working";
 import { runInstallCommand } from "./commands/install";
 import { inspectInstallPreflight } from "../lib/install";
 import { resolveRootContext } from "../lib/orchestrator/root-context";
@@ -78,12 +80,19 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
   const isPluginCommand =
     command === "cap" && findPluginCliCommand(subcommand, rest[0]) !== undefined;
 
+  // `workspace list`/`workspace materialize` are machine-JSON contracts an
+  // editor extension may poll frequently; their stdout must be pure JSON,
+  // and the un-awaited scheduleBackgroundCheck() has been observed to race
+  // a large final stdout write against process exit, truncating it. Both
+  // reasons put them in the same stdout-owning bucket as plugin commands.
+  const ownsStdout = isPluginCommand || command === "workspace";
+
   // Every dispatch case opens with a gate() call declaring what the command
   // needs before it may run. Declared gates run in fixed order — update
   // enforcement, companion selection, install preflight — and a blocked gate
   // sets the exit code, so callers only need `if (!(await gate(...))) return`.
   const gate = async (needs: GateNeeds): Promise<boolean> => {
-    if (!isPluginCommand) {
+    if (!ownsStdout) {
       const updateStore = new UpdateStateStore();
       scheduleBackgroundCheck(updateStore);
       if (needs.updateGuard && (await enforceUpdateIfRequired(updateStore))) {
@@ -206,6 +215,16 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       if (!(await gate({}))) return;
       await runUpdateCommand(argv.slice(3));
       return;
+    case "workspace":
+      // list/materialize are context-independent: no companion, install, or
+      // update gating — an editor extension may call these frequently.
+      if (!(await gate({}))) return;
+      await runWorkspaceCommand(subcommand, rest);
+      return;
+    case "working":
+      if (!(await gate({}))) return;
+      await runWorkingCommand(subcommand, rest);
+      return;
     default:
       // Unknown commands fail fast: no case matched, so no gate ever ran.
       console.error(`Unknown command: ${command}`);

package/src/cli/usage.ts

@@ -16,6 +16,9 @@ export function usage(): string {
     ` ${n} companion list`,
     ` ${n} companion open`,
     ` ${n} companion tui`,
+    ` ${n} workspace list --json`,
+    ` ${n} workspace materialize --repository ID --companion PATH --json`,
+    ` ${n} working cleanup`,
     ` ${n} hub init [folder]`,
     ` ${n} hub add [source] [--id ID] [--path PATH]`,
     ` ${n} hub sync [--json] (companions + hub plugins)`,
@@ -33,6 +36,11 @@ export function usage(): string {
     ` ${n} update`,
     ` ${n} update --check`,
     "",
+    "Working repository state:",
+    " linked repositories locally exclude root .claude/, .opencode/, and .agents/ directories",
+    ` ${n} working cleanup removes Mate-owned local integration without resetting product work`,
+    " tracked files and capability data remain untouched; link or launch recreates required state",
+    "",
     "Doctor states:",
     " linked-working-repository — cwd is inside a registered working repository",
     " companion-repository — cwd is the companion repository itself",

package/src/cli/write-json-stdout.ts

@@ -0,0 +1,14 @@
+/**
+ * Writes one JSON document to stdout and resolves only once the underlying
+ * write completes. `console.log`/bare `process.stdout.write` on a large
+ * payload can be truncated when stdout is a pipe and the process exits
+ * before the write flushes (observed at exactly the 64KB pipe boundary) —
+ * awaiting the write callback is what actually guarantees delivery.
+ */
+export function writeJsonStdout(data: unknown): Promise<void> {
+  return new Promise((resolve, reject) => {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}\n`, (error) =>
+      error ? reject(error) : resolve(),
+    );
+  });
+}

package/src/lib/orchestrator/companion-registry-reader.ts

@@ -0,0 +1,37 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import type { LinkedRepository } from "./types";
+
+export function companionRegistryPath(companionPath: string): string {
+  return path.join(path.resolve(companionPath), `.${FRAMEWORK_NAME}`, "config", "registry.yaml");
+}
+
+export interface CompanionRegistryReadResult {
+  repos: LinkedRepository[];
+}
+
+/**
+ * Parses a companion's `registry.yaml` without the writes {@link
+ * CompanionRegistryStore.load} performs (legacy-field migration, stale-pointer
+ * cleanup). Callers that must not mutate registry state on a read (e.g.
+ * inventory, materialization) use this instead. Throws ENOENT when the file
+ * doesn't exist; throws on unparsable YAML.
+ */
+export async function readCompanionRegistry(
+  companionPath: string,
+): Promise<CompanionRegistryReadResult> {
+  const raw = await fs.readFile(companionRegistryPath(companionPath), "utf8");
+  const parsed = parse(raw) as { repos?: unknown } | null;
+  const rawRepos = Array.isArray(parsed?.repos) ? parsed.repos : [];
+  const repos = rawRepos
+    .filter(
+      (entry): entry is LinkedRepository =>
+        Boolean(entry) && typeof entry.id === "string" && typeof entry.path === "string",
+    )
+    .map(({ id, path: repoPath }) => ({ id, path: repoPath }));
+  return { repos };
+}