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

package/src/cli/commands/artifact/pending/discovery.ts

@@ -109,28 +109,32 @@ function changeKindFor(
   );
 }
 
+/**
+ * Every file beneath `directory`, as POSIX paths under `relativeRoot`. Reads directory
+ * entry names only, never file contents. Throws when `directory` cannot be read.
+ */
+async function filesUnder(directory: string, relativeRoot: string): Promise<string[]> {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const entryRelative = path.posix.join(relativeRoot, entry.name);
+      if (entry.isDirectory()) return filesUnder(path.join(directory, entry.name), entryRelative);
+      return entry.isFile() ? [entryRelative] : [];
+    }),
+  );
+  return nested.flat();
+}
+
 /**
  * Canonical specs the change's delta specs applied to. Only directory entry names under
  * the archive's `specs/` tree are read — never any file contents — so archived prose
  * cannot influence discovery.
  */
 async function canonicalSpecsFor(companionPath: string, anchor: string): Promise<string[]> {
-  const collectDeltaSpecFiles = async (directory: string, relative = ""): Promise<string[]> => {
-    const entries = await fs.readdir(directory, { withFileTypes: true });
-    const nested = await Promise.all(
-      entries.map(async (entry) => {
-        const entryRelative = path.posix.join(relative, entry.name);
-        if (entry.isDirectory()) {
-          return collectDeltaSpecFiles(path.join(directory, entry.name), entryRelative);
-        }
-        return entry.isFile() ? [path.posix.join(SPECS_RELATIVE_DIR, entryRelative)] : [];
-      }),
-    );
-    return nested.flat();
-  };
   try {
-    const specs = await collectDeltaSpecFiles(
+    const specs = await filesUnder(
       path.join(companionPath, ARCHIVE_RELATIVE_DIR, anchor, "specs"),
+      SPECS_RELATIVE_DIR,
     );
     return specs.toSorted();
   } catch {
@@ -216,6 +220,32 @@ async function attributionIndex(
   );
 }
 
+/**
+ * The canonical spec files behind one uncommitted path. Porcelain collapses an untracked
+ * directory to `dir/`, so a collapsed path at or above a capability directory is expanded
+ * into the files beneath it, every one of them new; publish narrows by file, never by
+ * directory. Expansion reads directory entry names only, so spec prose cannot influence
+ * discovery.
+ */
+async function specFilesFor(
+  companionPath: string,
+  worktreePath: string,
+  changeKinds: Readonly<Record<string, WorkingTreeChange>>,
+): Promise<Array<{ path: string; kind: WorkingTreeChange }>> {
+  if (!worktreePath.endsWith("/")) {
+    return [{ path: worktreePath, kind: changeKindFor(worktreePath, changeKinds) }];
+  }
+  const collapsed = withoutTrailingSlash(worktreePath);
+  const root = collapsed.startsWith(`${SPECS_RELATIVE_DIR}/`) ? collapsed : SPECS_RELATIVE_DIR;
+  try {
+    const files = await filesUnder(path.join(companionPath, root), root);
+    return files.map((file) => ({ path: file, kind: "new" as const }));
+  } catch {
+    // A collapsed ancestor such as `openspec/` need not contain a spec tree at all.
+    return [];
+  }
+}
+
 /**
  * Uncommitted canonical specs that no pending change accounts for, each attributed to
  * every archive whose delta specs name it. An attributed spec belongs to a change whose
@@ -230,18 +260,27 @@ export async function unattributedSpecs(
   archives: ArchiveEntry[],
   changeKinds: Readonly<Record<string, WorkingTreeChange>> = {},
 ): Promise<UnattributedSpec[]> {
-  const claimed = new Set(pendingArchives(archives).flatMap((entry) => entry.uncommittedSpecs));
-  const specPaths = uncommittedPaths
-    .filter(
-      (worktreePath) => touches(worktreePath, SPECS_RELATIVE_DIR) && !claimed.has(worktreePath),
-    )
-    .toSorted();
+  const claimed = pendingArchives(archives).flatMap((entry) => entry.uncommittedSpecs);
+  const reported = await Promise.all(
+    uncommittedPaths.flatMap((worktreePath) =>
+      touches(worktreePath, SPECS_RELATIVE_DIR)
+        ? [specFilesFor(companionPath, worktreePath, changeKinds)]
+        : [],
+    ),
+  );
+  const driftKinds = new Map<string, WorkingTreeChange>();
+  for (const spec of reported.flat()) {
+    if (!claimed.some((claimedPath) => touches(claimedPath, spec.path))) {
+      driftKinds.set(spec.path, spec.kind);
+    }
+  }
+  const specPaths = [...driftKinds.keys()].toSorted();
   if (specPaths.length === 0) return [];
 
   const index = await attributionIndex(companionPath, archives);
   return specPaths.map((specPath) => ({
     path: specPath,
-    kind: changeKindFor(specPath, changeKinds),
+    kind: driftKinds.get(specPath) ?? "modified",
     touchedByArchives: index.flatMap(({ anchor, state, specs }) =>
       specs.some((spec) => touches(specPath, spec)) ? [{ anchor, state }] : [],
     ),

package/src/cli/commands/cap/index-cmd.ts

@@ -1,6 +1,3 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
 import {
   hasGraphifyCapability,
   hasTokensaveCapability,
@@ -10,7 +7,7 @@ import type { CapabilityConfig } from "../../../lib/orchestrator/types";
 import {
   ensureTokensaveBranchingPosture,
   ensureTokensaveStoreExcluded,
-  TOKENSAVE_STORE_DIR,
+  isTokensaveIndexed,
 } from "../../../tools/setup/capabilities/tokensave";
 import { ensureUnambiguousCompanion } from "../shared/companion-selection";
 import { runGraphifyCapCommand } from "./graphify";
@@ -43,13 +40,7 @@ async function defaultIsTokensaveInitialized(): Promise<boolean> {
   const repo =
     repository ?? (await workingRepoStore.load()).repos.find((entry) => entry.id === repositoryId);
   if (!repo) return false;
-
-  try {
-    const stat = await fs.stat(path.join(repo.path, TOKENSAVE_STORE_DIR));
-    return stat.isDirectory();
-  } catch {
-    return false;
-  }
+  return isTokensaveIndexed(repo.path);
 }
 
 // The reused cap commands (runGraphifyCapCommand / runTokensaveCapCommand) signal

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

@@ -10,10 +10,12 @@ import {
 } from "../../companion-link-wizard";
 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 {
+  CompanionResolver,
+  companionRootedStore,
+  findDescendantRepoLocalRegistries,
+} from "../../../lib/orchestrator/repository-link";
 import { inspectSetupPreflight } from "../../../lib/orchestrator/setup-preflight";
-import { findDescendantRepoLocalRegistries } from "../../../lib/orchestrator/repo-local-registry";
 import { runSetupFlowAtPath } from "../setup";
 import { runInstallCommand } from "../install";
 import type { CompanionSource, LinkedRepository } from "../../../lib/orchestrator/types";
@@ -164,14 +166,15 @@ export async function runCompanionLinkCommandWithDeps(
     if (!inputs.companionPaths?.length) {
       exitWithError("mate: no existing companion was selected.");
     }
-    companionPaths = [];
-    for (const rawCompanionPath of inputs.companionPaths) {
-      const resolvedCompanionPath = path.resolve(rawCompanionPath);
-      const existingTarget = await stat(resolvedCompanionPath).catch(() => null);
-      if (!existingTarget?.isDirectory()) {
-        exitWithError(`mate: existing companion must be a directory: ${resolvedCompanionPath}`);
-      }
-      companionPaths.push(resolvedCompanionPath);
+    companionPaths = inputs.companionPaths.map((rawCompanionPath) =>
+      path.resolve(rawCompanionPath),
+    );
+    const targets = await Promise.all(
+      companionPaths.map((companionPath) => stat(companionPath).catch(() => null)),
+    );
+    const notADirectory = companionPaths.find((_, index) => !targets[index]?.isDirectory());
+    if (notADirectory) {
+      exitWithError(`mate: existing companion must be a directory: ${notADirectory}`);
     }
   } else {
     const rawCompanionPath = inputs.localPath?.trim();
@@ -205,6 +208,7 @@ export async function runCompanionLinkCommandWithDeps(
   // Managed companions are git-backed; explicitly pasted paths retain local provenance.
   const persistedSource: CompanionSource = companionSource === "local" ? "local" : "git";
 
+  /* oxlint-disable no-await-in-loop -- each companion is set up, linked and installed in turn; a declined install stops the rest */
   for (const companionPath of companionPaths) {
     const preflight = await inspectPreflight(companionPath);
     if (companionSource === "git" && preflight.kind !== "existing-companion") {
@@ -216,6 +220,7 @@ export async function runCompanionLinkCommandWithDeps(
     await invalidateInstallState({ kind: "companion", companionPath });
     if ((await installCompanion(companionPath)) === false) return;
   }
+  /* oxlint-enable no-await-in-loop */
 
   let shadowedPaths: string[] = [];
   try {

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

@@ -1,4 +1,4 @@
-import { CompanionStore } from "../../../lib/orchestrator/companion-store";
+import { CompanionStore } from "../../../lib/orchestrator/repository-link";
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
 import { renderRepoListTable } from "../../repo-list-table";
 import { writeJsonStdout } from "../../write-json-stdout";
@@ -13,14 +13,13 @@ import { writeJsonStdout } from "../../write-json-stdout";
  * TTY (e.g. piped into another command).
  */
 export async function runCompanionListCommand(argv: string[] = []): Promise<void> {
-  const { configStore, workingRepoStore, repository, contextKind } = await resolveFrameworkContext(
-    process.cwd(),
-  );
+  const { companionPath, workingRepoStore, repository, contextKind } =
+    await resolveFrameworkContext(process.cwd());
   const repositories = repository
     ? [repository]
     : contextKind === "companion-root"
       ? []
-      : await new CompanionStore(configStore, workingRepoStore).listRepositories();
+      : await new CompanionStore(companionPath, workingRepoStore).listRepositories();
   const forceJson = argv.includes("--json");
 
   if (forceJson || !process.stdout.isTTY) {

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

@@ -1,4 +1,4 @@
-import { CompanionStore } from "../../../lib/orchestrator/companion-store";
+import { CompanionStore } from "../../../lib/orchestrator/repository-link";
 import { resolveForLaunch } from "../../../lib/orchestrator/framework-context";
 import { injectEditorFolder, getPreferredEditorCli } from "../../../lib/orchestrator/editor";
 import { ensureUnambiguousCompanion } from "../launch/shared";
@@ -7,9 +7,9 @@ export const workspaceOpenCommandDeps = {
   ensureUnambiguousCompanion: () => ensureUnambiguousCompanion(),
   resolveLaunchContext: () => resolveForLaunch(process.cwd()),
   createStore: (
-    configStore: ConstructorParameters<typeof CompanionStore>[0],
+    companionPath: ConstructorParameters<typeof CompanionStore>[0],
     workingRepoStore: ConstructorParameters<typeof CompanionStore>[1],
-  ) => new CompanionStore(configStore, workingRepoStore),
+  ) => new CompanionStore(companionPath, workingRepoStore),
   getPreferredEditorCli: () => getPreferredEditorCli(),
   injectEditorFolder,
 };
@@ -35,13 +35,12 @@ export async function runWorkspaceOpenCommand(): Promise<void> {
     companionPath,
     repositoryId,
     repository: localRepository,
-    configStore,
     workingRepoStore,
   } = await workspaceOpenCommandDeps.resolveLaunchContext();
   const repository =
     localRepository ??
     (await workspaceOpenCommandDeps
-      .createStore(configStore, workingRepoStore)
+      .createStore(companionPath, workingRepoStore)
       .getRepository(repositoryId));
 
   if (!repository) {

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

@@ -4,7 +4,7 @@ import { accessSync } from "node:fs";
 import { getActiveDistribution } from "../../../distribution";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { resolveFrameworkContext } from "../../../lib/orchestrator/framework-context";
-import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repo-local-registry";
+import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repository-link";
 import { ensureUnambiguousCompanion } from "../launch/shared";
 
 export function renderBanner(repoPath: string, companionPath: string): string {

package/src/cli/commands/doctor.ts

@@ -3,10 +3,11 @@ import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../framework";
 import { gitEnvironment } from "../../runtime/companion-git";
+import { readWrapStateSync } from "../../runtime/wrap-state";
 import { getActiveDistribution } from "../../distribution";
 import { checkEngineRequirement } from "../../lib/orchestrator/engine-guard";
 import type { GlobalConfigStore } from "../../lib/orchestrator/global-config-store";
-import { pathIsDirectory } from "../../lib/orchestrator/repo-local-registry";
+import { pathIsDirectory } from "../../lib/fs-utils";
 import { resolveRootContext, type RootContext } from "../../lib/orchestrator/root-context";
 import type { CapabilityConfig, FrameworkConfig, HubMember } from "../../lib/orchestrator/types";
 import {
@@ -19,7 +20,12 @@ import {
   type PluginInspection,
   type PluginVerificationFailure,
 } from "../../tools/setup/dynamic-plugins/verify";
+import {
+  inspectAudienceIsolation,
+  type AudienceIsolationReport,
+} from "../../tools/setup/isolation-diagnostics";
 import { getRequiredPluginDrift } from "../../tools/setup/policy";
+import type { PluginRegistry } from "../../tools/setup/registry";
 import { resolveCommandOnPath } from "../../tools/setup/utils";
 import { writeJsonStdout } from "../write-json-stdout";
 import { printSection, renderKeyValueTable, renderTable } from "./status";
@@ -33,6 +39,8 @@ interface DoctorDeps {
   inspectPlugins?: (companionPath: string) => Promise<PluginInspection>;
   /** Environment `MATE_AUDIENCE` is read from; defaults to the process environment. */
   env?: Record<string, string | undefined>;
+  /** The hydrated registry; the active distribution's when absent. */
+  registry?: PluginRegistry;
 }
 
 export type DoctorKind = "core" | "working" | "companion" | "hub";
@@ -66,10 +74,15 @@ export interface DoctorReport {
   toolInstallations?: DoctorToolInstallation[];
   requiredPluginDrift?: Array<{ pluginId: string; kind: string; reason: string }>;
   pluginFailures?: PluginVerificationFailure[];
-  /** Present for a companion that declares audiences or has one selected. */
-  audiences?: { declared: string[]; active: string | null };
+  /**
+   * Present for a companion that declares audiences or has one selected.
+   * `wrapped` is the audience the working repository is wrapped for, when any.
+   */
+  audiences?: { declared: string[]; active: string | null; wrapped?: string };
   /** Set when `MATE_AUDIENCE` names an audience the companion does not declare. */
   audienceError?: string;
+  /** Present when an audience's contributions reached a persisted surface, or a launch layer cannot deliver part of one. */
+  audienceIsolation?: AudienceIsolationReport;
   /** IDs of the capabilities the verified plugins provide. */
   pluginCapabilities?: string[];
   engineRequirement?: { range: string; ok: boolean; detail: string };
@@ -230,12 +243,18 @@ function collectAudiences(
   report: DoctorReport,
   config: FrameworkConfig,
   env: Record<string, string | undefined>,
+  repositoryPath: string | null,
 ): void {
   const declared = Object.keys(config.audiences ?? {});
   const requested = readAudienceSelection(env);
   if (declared.length === 0 && requested === null) return;
   const resolution = resolveAudience(config, requested);
-  report.audiences = { declared, active: resolution.ok ? resolution.active : null };
+  const wrapped = repositoryPath ? readWrapStateSync(repositoryPath).audience : null;
+  report.audiences = {
+    declared,
+    active: resolution.ok ? resolution.active : null,
+    ...(wrapped ? { wrapped } : {}),
+  };
   if (!resolution.ok) report.audienceError = describeUnknownAudience(resolution);
 }
 
@@ -274,7 +293,16 @@ export async function collectDoctorReport(deps: DoctorDeps = {}): Promise<Doctor
 
   const env = deps.env ?? process.env;
   if (root.rootPath && root.config && kind !== "hub") {
-    collectAudiences(report, root.config, env);
+    collectAudiences(report, root.config, env, root.linkedRepository?.path ?? null);
+    const isolation = await inspectAudienceIsolation(
+      root.rootPath,
+      root.config,
+      deps.registry ?? getActiveDistribution().registry,
+      report.audiences?.active ?? null,
+    );
+    if (isolation.leaked.length + isolation.unswept.length + isolation.undelivered.length > 0) {
+      report.audienceIsolation = isolation;
+    }
   }
 
   if (root.rootPath && root.config) {
@@ -325,6 +353,49 @@ function renderHubMembers(members: DoctorHubMember[]): string {
   );
 }
 
+function renderAudienceIsolation(isolation: AudienceIsolationReport): string {
+  const parts: string[] = [];
+  if (isolation.leaked.length > 0) {
+    parts.push(
+      "Contributions on persisted surfaces that no base plugin owns; the next sync removes them:",
+      renderTable(
+        ["Surface", "Kind", "Entry", "Owner"],
+        isolation.leaked.map((entry) => [
+          entry.surface,
+          entry.kind,
+          entry.identity ?? "",
+          entry.owner,
+        ]),
+      ),
+    );
+  }
+  if (isolation.unswept.length > 0) {
+    parts.push(
+      `Audience plugins not swept (could not be loaded); run \`MATE_AUDIENCE=<audience> ${FRAMEWORK_NAME} install --yes\` with their credentials:`,
+      renderList(isolation.unswept, ""),
+    );
+  }
+  if (isolation.undelivered.length > 0) {
+    parts.push(
+      "Active audience plugins contribute declaratively only; these parts are not delivered:",
+      renderList(
+        isolation.undelivered.map(
+          (entry) =>
+            `${entry.pluginId}: ${entry.parts
+              .map((part) =>
+                part === "pluginReferences"
+                  ? "OpenCode plugin references are not delivered"
+                  : `${part} is not run`,
+              )
+              .join("; ")}`,
+        ),
+        "",
+      ),
+    );
+  }
+  return parts.join("\n\n");
+}
+
 function renderHumanReport(report: DoctorReport): void {
   console.log("Mate Doctor");
   console.log("");
@@ -371,9 +442,20 @@ function renderHumanReport(report: DoctorReport): void {
       renderKeyValueTable([
         ["Declared", report.audiences.declared.join(", ") || "none"],
         ["Active", report.audiences.active ?? "none"],
+        ...(report.audiences.wrapped
+          ? [
+              ["Wrapped", `${report.audiences.wrapped} (bare sessions of this checkout)`] as [
+                string,
+                string,
+              ],
+            ]
+          : []),
       ]),
     );
   }
+  if (report.audienceIsolation) {
+    printSection("Audience Isolation", renderAudienceIsolation(report.audienceIsolation));
+  }
   if (report.hub) printSection("Hub Members", renderHubMembers(report.hub.members));
   // Companions with no drift produce no section at all: required plugins are
   // silent when healthy.

package/src/cli/commands/install.ts

@@ -1,5 +1,8 @@
+import path from "node:path";
+
 import { confirm } from "../confirm";
 import { FRAMEWORK_NAME } from "../../framework";
+import { ConfigStore } from "../../lib/orchestrator/config-store";
 import {
   buildInstallPlan,
   inspectInstallPlan,
@@ -176,6 +179,11 @@ export async function runInstallCommand(argv: string[], cwd = process.cwd()): Pr
   }
 
   try {
+    if (!frozen && context.kind === "companion" && context.companionPath) {
+      await new ConfigStore(
+        path.join(context.companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml"),
+      ).save(context.config);
+    }
     await reconcileInstalledCompanion(plan);
     await saveCompleteInstallState(plan, execution.results);
   } catch (error) {

package/src/cli/commands/report/renderer.ts

@@ -1,6 +1,3 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
 import { reportDataToDocument } from "./adapter";
 import { validateReportDocument } from "./contract";
 import { highlightInline, highlightStyleBlock } from "./highlight";
@@ -14,26 +11,19 @@ import type {
   ReportValue,
 } from "./types";
 
-const MERMAID_RUNTIME_PATH = join(
-  import.meta.dirname,
-  "../../../templates/report-assets/mermaid.min.js",
-);
+/**
+ * Pinned and integrity-checked, so a CDN cannot serve other code. Offline, the
+ * script fails to load and each diagram stays readable as its escaped source.
+ */
+export const MERMAID_RUNTIME_URL =
+  "https://cdn.jsdelivr.net/npm/mermaid@12.0.0/dist/mermaid.min.js";
+const MERMAID_RUNTIME_INTEGRITY =
+  "sha384-xzghz1GQ5u9HCpVskeDPqMsdogD1yvuMQbEK53+wi+G70+6J1AG0L2cfi9PHjDWI";
 
 const MERMAID_RUNTIME_ID = "mermaid-runtime";
 
 const CODE_BLOCK_SELECTOR = "pre.report-code";
 
-let mermaidRuntime: string | undefined;
-
-/** A literal `</script` inside the bundle would close the inline element, so it is neutralised. */
-function readMermaidRuntime(): string {
-  mermaidRuntime ??= readFileSync(MERMAID_RUNTIME_PATH, "utf8").replaceAll(
-    "</script",
-    String.raw`<\/script`,
-  );
-  return mermaidRuntime;
-}
-
 const carriesMermaid = (sections: ReportSection[]): boolean =>
   sections.some((section) => section.type === "diagram" && section.mermaid !== undefined);
 
@@ -384,7 +374,7 @@ export function renderHTML(input: RenderInput): string {
     ? `\n  <style>${highlightStyleBlock(CODE_BLOCK_SELECTOR)}${VISUAL_SECTION_CSS}</style>`
     : "";
   const diagramRuntime = carriesMermaid(data.sections)
-    ? `\n  <script id="${MERMAID_RUNTIME_ID}">${readMermaidRuntime()}</script>\n  <script>mermaid.initialize({ startOnLoad: true, securityLevel: "strict" });</script>`
+    ? `\n  <script id="${MERMAID_RUNTIME_ID}" src="${MERMAID_RUNTIME_URL}" integrity="${MERMAID_RUNTIME_INTEGRITY}" crossorigin="anonymous"></script>\n  <script>window.mermaid?.initialize({ startOnLoad: true, securityLevel: "strict" });</script>`
     : "";
 
   return `<!doctype html>

package/src/cli/commands/session/prepare.ts

@@ -0,0 +1,119 @@
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../../../framework";
+import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repository-link";
+import { prepareSession, type PrepareResult } from "../../../lib/orchestrator/session-prepare";
+import { readProjectionFile } from "../../../runtime/projection";
+import { readWrapState, WRAP_RUNTIMES } from "../../../runtime/wrap-state";
+import { writeJsonStdout } from "../../write-json-stdout";
+import { launchAmbiguityDeps } from "../shared/companion-selection";
+
+export interface SessionPrepareArgs {
+  repo: string;
+  json: boolean;
+  /** Fast-forward the companion first, then the local phase when it moved. */
+  sync: boolean;
+}
+
+const USAGE = `Usage: ${FRAMEWORK_NAME} session prepare --repo <dir> [--json] [--sync]`;
+
+function fail(message: string, usage = false): null {
+  console.error(`${FRAMEWORK_NAME}: ${message}`);
+  if (usage) console.error(USAGE);
+  process.exitCode = 1;
+  return null;
+}
+
+export function parseSessionPrepareArgs(
+  argv: string[],
+  cwd: string = process.cwd(),
+): SessionPrepareArgs | { error: string } {
+  const args: SessionPrepareArgs = { repo: cwd, json: false, sync: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    const [flag, inline] = arg.startsWith("--") && arg.includes("=") ? arg.split(/=(.*)/s) : [arg];
+    if (flag === "--json") {
+      args.json = true;
+    } else if (flag === "--repo") {
+      const repo = inline ?? argv[++index];
+      if (!repo) return { error: "--repo requires a directory" };
+      args.repo = path.resolve(cwd, repo);
+    } else if (flag === "--sync") {
+      args.sync = true;
+    } else {
+      return { error: `unknown session prepare option: ${arg}` };
+    }
+  }
+  return args;
+}
+
+export const sessionPrepareCommandDeps = {
+  findRepoLocalLinkedRepository,
+  prepareSession,
+  resolveLinkedCompanions: launchAmbiguityDeps.resolveLinkedCompanions,
+};
+
+async function resolveCompanionPath(repoPath: string): Promise<string | undefined> {
+  const projected = readProjectionFile(repoPath)?.projection.companionPath;
+  if (projected) return projected;
+  return (await sessionPrepareCommandDeps.resolveLinkedCompanions(repoPath))[0]?.companionPath;
+}
+
+function printHuman(result: PrepareResult): void {
+  for (const step of result.steps) {
+    const detail = step.detail ? ` — ${step.detail}` : "";
+    const runtimes = step.runtimes ? ` (${step.runtimes.join(", ")})` : "";
+    console.log(`  ${step.step}${runtimes}: ${step.outcome}${detail}`);
+  }
+  for (const warning of result.warnings) {
+    console.error(`${FRAMEWORK_NAME}: warning: ${warning}`);
+  }
+}
+
+/**
+ * `mate session prepare`: a launch's preparation for each runtime the
+ * repository is wrapped for, without the launch. Without `--sync` it touches no remote; with it,
+ * it fast-forwards the companion and re-projects only when the companion moved.
+ * Non-zero when the repository is not wrapped or a step failed; a Git conflict
+ * or an offline remote is only a warning.
+ */
+export async function runSessionPrepareCommand(
+  argv: string[],
+  cwd: string = process.cwd(),
+): Promise<PrepareResult | null> {
+  const parsed = parseSessionPrepareArgs(argv, cwd);
+  if ("error" in parsed) return fail(parsed.error, true);
+
+  const deps = sessionPrepareCommandDeps;
+  const repository = await deps.findRepoLocalLinkedRepository(parsed.repo);
+  const wrapped = repository ? (await readWrapState(repository.path)).runtimes : new Set();
+  const runtimes = WRAP_RUNTIMES.filter((runtime) => wrapped.has(runtime));
+  if (!repository || runtimes.length === 0) {
+    return fail(`${parsed.repo} is not wrapped. Run \`${FRAMEWORK_NAME} wrap\` there first.`);
+  }
+
+  const companionPath = await resolveCompanionPath(repository.path);
+  if (!companionPath) return fail(`no companion is linked to ${repository.id}.`);
+
+  const result = await deps.prepareSession({
+    runtime: runtimes[0]!,
+    runtimes,
+    companionPath,
+    repository,
+    mode: parsed.sync ? "sync" : "local",
+  });
+  /** The failure's own error and the wrap state are for an in-process caller; the JSON names steps. */
+  const { failure: _failure, wrapState: _wrapState, ...reported } = result;
+  if (parsed.json) await writeJsonStdout(reported);
+  else printHuman(result);
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}
+
+export async function runSessionCommand(subcommand: string | undefined, rest: string[]) {
+  if (subcommand === "prepare") {
+    await runSessionPrepareCommand(rest);
+    return;
+  }
+  fail(`unknown session subcommand: ${subcommand ?? ""}`.trimEnd(), true);
+}

package/src/cli/commands/shared/companion-selection.ts

@@ -4,9 +4,9 @@ import { FRAMEWORK_NAME } from "../../../framework";
 import {
   CompanionResolver,
   type CompanionMatch,
-} from "../../../lib/orchestrator/companion-resolver";
+  findRepoLocalLinkedRepository,
+} from "../../../lib/orchestrator/repository-link";
 import { GlobalConfigStore } from "../../../lib/orchestrator/global-config-store";
-import { findRepoLocalLinkedRepository } from "../../../lib/orchestrator/repo-local-registry";
 import { projectWorkingRepositoryBestEffort } from "../../../lib/orchestrator/working-repo-projection";
 import { resolveProjection } from "../../../runtime/projection";
 import { selectCompanion } from "../../companion-selector";

package/src/cli/commands/studio/reports.ts

@@ -10,7 +10,6 @@ export const REPORT_LIMITS = {
   reports: 20,
   bytes: 50 * 1024 * 1024,
   ageMs: 7 * 24 * 60 * 60 * 1000,
-  /** The bundled inlined Mermaid runtime alone is about 5.3 MiB. */
   uploadBytes: 10 * 1024 * 1024,
 };