@uniqbit/mate-core 0.16.0 → 0.17.0-canary.1

package/src/lib/orchestrator/adapters/base.ts

@@ -1,23 +1,39 @@
 import { spawn } from "node:child_process";
+import os from "node:os";
 import path from "node:path";
 
 import { FRAMEWORK_NAME } from "../../../framework";
 import { MATE_ENV } from "../../../runtime/env-names";
-import { buildProjection, projectionEnvironment } from "../projection-record";
+import { buildProjection, companionEnvironment, projectionEnvironment } from "../projection-record";
 import type { CapabilityConfig, GitModeProfile, LinkedRepository } from "../types";
 
 export interface AdapterContext {
-  repository: LinkedRepository;
+  repository?: LinkedRepository;
+  launchWorkingDirectory: string;
   allowedAgents: string[];
   companionPath: string;
   capabilities: CapabilityConfig[];
   git?: GitModeProfile;
+  skipGit?: boolean;
 }
 
 export interface AdapterResult {
   exitCode: number;
   stdout: string;
   stderr: string;
+  /** Set when the agent process ended on a signal rather than its own exit. */
+  signal?: NodeJS.Signals | null;
+}
+
+/** Forwarded from the launch to the agent so a supervisor above it can stop a session. */
+const FORWARDED_SIGNALS: NodeJS.Signals[] = ["SIGINT", "SIGTERM"];
+
+/**
+ * The shell convention: a signalled stop reads as 128 + the signal number, so a
+ * caller can tell it from an ordinary non-zero exit.
+ */
+export function signalExitCode(signal: NodeJS.Signals): number {
+  return 128 + (os.constants.signals[signal] ?? 0);
 }
 
 export interface PreparedLaunch {
@@ -50,19 +66,26 @@ export abstract class LaunchAdapter {
    */
   environment(context: AdapterContext): NodeJS.ProcessEnv {
     const reactDoctorEnabled = context.capabilities.some((c) => c.name === "react-doctor");
-    const projection = buildProjection(context.companionPath, context.repository);
+    const projection = context.repository
+      ? projectionEnvironment(buildProjection(context.companionPath, context.repository))
+      : companionEnvironment(context.companionPath);
     const env: NodeJS.ProcessEnv = {
       ...process.env,
-      ...projectionEnvironment(projection),
+      ...projection,
       MATE_NAME: FRAMEWORK_NAME,
-      PATH: prependPathEntry(process.env.PATH, projection.wrapperBinPath),
+      PATH: prependPathEntry(process.env.PATH, projection[MATE_ENV.wrapperBinPath] ?? ""),
       MATE_GRAPHIFY_ENABLED: context.capabilities.some((c) => c.name === "graphify") ? "1" : "0",
       MATE_OPENSPEC_ENABLED: context.capabilities.some((c) => c.name === "openspec") ? "1" : "0",
       MATE_REACT_DOCTOR_ENABLED: reactDoctorEnabled ? "1" : "0",
-      MATE_GIT_AUTO_MODE: context.git === "auto" ? "1" : "0",
+      MATE_GIT_AUTO_MODE: context.git === "auto" && !context.skipGit ? "1" : "0",
       MATE_POLICY_JSON: JSON.stringify({ allowedAgents: context.allowedAgents }),
     };
 
+    if (!context.repository) {
+      delete env[MATE_ENV.repositoryPath];
+      delete env[MATE_ENV.repositoryId];
+    }
+
     /** The one field where a launch still narrows the projection rather than materializing it. */
     if (!reactDoctorEnabled) delete env[MATE_ENV.reactDoctorBinPath];
 
@@ -87,12 +110,22 @@ export abstract class LaunchAdapter {
     return { command: this.toolName, args: builtArgs, env };
   }
 
+  /**
+   * A terminal delivers `SIGINT` to the whole foreground process group, so an
+   * interactive launch at a TTY must not forward it as well — the agent would
+   * be stopped twice. Where the signal reaches the launch alone (a supervisor,
+   * a container entrypoint), forwarding is the only way it reaches the agent.
+   */
+  protected forwardsSignals(): boolean {
+    return !(this.interactive && process.stdin.isTTY);
+  }
+
   async run(context: AdapterContext, args: string[]): Promise<AdapterResult> {
     const launch = await this.prepareLaunch(context, args);
 
     return new Promise((resolve, reject) => {
       const child = spawn(launch.command, launch.args, {
-        cwd: context.repository.path,
+        cwd: context.launchWorkingDirectory,
         env: launch.env,
         stdio: this.interactive ? "inherit" : "pipe",
       });
@@ -109,12 +142,34 @@ export abstract class LaunchAdapter {
         });
       }
 
-      child.on("error", reject);
-      child.on("close", (exitCode) => {
+      const forward = this.forwardsSignals();
+      const handlers = new Map<NodeJS.Signals, () => void>();
+      for (const signal of FORWARDED_SIGNALS) {
+        const handler = () => {
+          /** Installing a handler at all is what keeps the launch alive to wait for the agent. */
+          if (forward && child.exitCode === null && child.signalCode === null) {
+            child.kill(signal);
+          }
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+      }
+      const removeHandlers = () => {
+        for (const [signal, handler] of handlers) process.off(signal, handler);
+        handlers.clear();
+      };
+
+      child.on("error", (error) => {
+        removeHandlers();
+        reject(error);
+      });
+      child.on("close", (exitCode, signal) => {
+        removeHandlers();
         resolve({
-          exitCode: exitCode ?? 1,
+          exitCode: exitCode ?? (signal ? signalExitCode(signal) : 1),
           stdout,
           stderr,
+          signal: signal ?? null,
         });
       });
     });

package/src/lib/orchestrator/adapters/opencode.ts

@@ -29,7 +29,7 @@ export class OpenCodeAdapter extends LaunchAdapter {
   ] as const;
 
   buildArgs(context: AdapterContext, args: string[]): string[] {
-    const codeDir = context.repository.path;
+    const codeDir = context.launchWorkingDirectory;
     return args.length === 0 || args[0]?.startsWith("-") ? [codeDir, ...args] : args;
   }
 
@@ -55,7 +55,9 @@ export class OpenCodeAdapter extends LaunchAdapter {
   }
 
   private buildGuidance(context: AdapterContext): MateGuidanceFile {
-    return buildOpenCodeGuidance(context.capabilities);
+    return buildOpenCodeGuidance(context.capabilities, {
+      companionScoped: !context.repository,
+    });
   }
 
   async validateLaunch(context: AdapterContext): Promise<void> {

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

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { parse } from "yaml";
+
+import { FRAMEWORK_NAME } from "../../framework";
+import { GlobalConfigStore } from "./global-config-store";
+import type { FrameworkType } from "./types";
+
+export type CompanionRegistrationResult =
+  | { ok: true; companionPath: string; alreadyRegistered: boolean }
+  | { ok: false; companionPath: string; reason: string };
+
+export interface RegisterConfiguredCompanionDeps {
+  globalConfigStore?: Pick<GlobalConfigStore, "list" | "register">;
+  readFile?: typeof fs.readFile;
+}
+
+function configPathFor(companionPath: string): string {
+  return path.join(companionPath, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
+}
+
+/**
+ * Registration for a Companion Repository that already carries its own
+ * configuration: never presents a selection, never reads stdin, and never
+ * writes the companion's configuration — only the global registry entry.
+ */
+export async function registerConfiguredCompanion(
+  rawCompanionPath: string,
+  deps: RegisterConfiguredCompanionDeps = {},
+): Promise<CompanionRegistrationResult> {
+  const companionPath = path.resolve(rawCompanionPath);
+  const readFile = deps.readFile ?? fs.readFile;
+  const store = deps.globalConfigStore ?? new GlobalConfigStore();
+
+  let raw: string;
+  try {
+    raw = await readFile(configPathFor(companionPath), "utf8");
+  } catch {
+    return {
+      ok: false,
+      companionPath,
+      reason: `${companionPath} carries no companion configuration (${path.join(`.${FRAMEWORK_NAME}`, "config", "framework.yaml")} is missing); there is nothing to register.`,
+    };
+  }
+
+  let declaredType: FrameworkType | undefined;
+  try {
+    declaredType = (parse(raw) as { type?: FrameworkType } | null)?.type;
+  } catch {
+    return {
+      ok: false,
+      companionPath,
+      reason: `${companionPath} carries an unreadable companion configuration; there is nothing to register.`,
+    };
+  }
+
+  /** A missing type predates the field and is a companion; anything else is not one. */
+  if (declaredType !== undefined && declaredType !== "companion") {
+    return {
+      ok: false,
+      companionPath,
+      reason: `${companionPath} is a "${declaredType}" framework, not a companion; there is nothing to register.`,
+    };
+  }
+
+  const alreadyRegistered = (await store.list()).some(
+    (entry) => path.resolve(entry) === companionPath,
+  );
+  await store.register(companionPath);
+
+  return { ok: true, companionPath, alreadyRegistered };
+}

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

@@ -17,6 +17,7 @@ import {
   type FrameworkConfig,
   type HubConfig,
   type LinkedRepository,
+  type LaunchScope,
   RepositoryNotFoundError,
   WorkingRepoRequiredError,
 } from "./types";
@@ -187,14 +188,18 @@ export async function resolveFrameworkContext(
 // Resolution order:
 // 1. MATE_ARTIFACT_PATH + MATE_REPO_ID env vars (agent-launched sessions)
 // 2. CompanionResolver — cwd inside a linked working repo
-// Does NOT fall back to local config — launching from the companion root is invalid.
-// Use resolveForCapability if the caller may run from the companion directory.
+// A companion-scoped launch may also resolve the local companion config from cwd.
 export async function resolveForLaunch(
   cwd: string,
   globalConfigStore = new GlobalConfigStore(),
+  scope: LaunchScope = "working-repo",
 ): Promise<LaunchContext> {
   const envCompanionPath = process.env.MATE_ARTIFACT_PATH;
   if (envCompanionPath) {
+    if (scope === "companion") {
+      const context = await withResolvedHub(makeContext(path.resolve(envCompanionPath), "env"));
+      return { ...context, repositoryId: "" };
+    }
     const repository = repositoryFromEnvironment() ?? (await findRepoLocalLinkedRepository(cwd));
     const repositoryId = process.env.MATE_REPO_ID ?? repository?.id ?? "";
     const context = await withResolvedHub(
@@ -215,6 +220,12 @@ export async function resolveForLaunch(
 
   if (resolution.match) {
     const repository = (await findRepoLocalLinkedRepository(cwd)) ?? undefined;
+    if (scope === "companion") {
+      const context = await withResolvedHub(
+        makeContext(resolution.match.companionPath, "working-repo"),
+      );
+      return { ...context, repositoryId: "" };
+    }
     if (repository) {
       await backfillCompanionRegistration(resolution.match.companionPath, repository);
       await projectWorkingRepositoryBestEffort(resolution.match.companionPath, repository);
@@ -228,6 +239,21 @@ export async function resolveForLaunch(
     };
   }
 
+  if (scope === "companion") {
+    const localConfigPath = path.join(cwd, `.${FRAMEWORK_NAME}`, "config", "framework.yaml");
+    let localConfig: Partial<FrameworkConfig> | null;
+    try {
+      localConfig = parse(await fs.readFile(localConfigPath, "utf8")) as Partial<FrameworkConfig>;
+    } catch {
+      localConfig = null;
+    }
+    if (localConfig?.type !== "companion") {
+      throw new RepositoryNotFoundError(`No companion found for current directory: ${cwd}`);
+    }
+    const context = await withResolvedHub(makeContext(cwd, "companion-root"));
+    return { ...context, repositoryId: "" };
+  }
+
   throw new WorkingRepoRequiredError();
 }
 
@@ -259,7 +285,7 @@ async function backfillCompanionRegistration(
 // 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
-// fallback because launching an agent from the companion root is not a valid scenario.
+// fallback because its implicit launch scope still requires a Working Repository.
 export async function resolveForCapability(
   cwd: string,
   globalConfigStore = new GlobalConfigStore(),

package/src/lib/orchestrator/launcher.ts

@@ -28,12 +28,13 @@ import {
   type LaunchRequest,
   type LaunchResult,
   type LinkedRepository,
+  type LaunchScope,
 } from "./types";
 
 export interface LaunchPreview {
   tool: string;
-  repositoryId: string;
-  repositoryPath: string;
+  repositoryId?: string;
+  repositoryPath?: string;
   companionPath: string;
 }
 
@@ -45,7 +46,10 @@ interface ResolvedLaunchState {
   adapter: LaunchAdapter;
   companionPath: string;
   config: FrameworkConfig;
-  repository: LinkedRepository;
+  repository?: LinkedRepository;
+  scope: LaunchScope;
+  launchWorkingDirectory: string;
+  skipGit: boolean;
 }
 
 export const launcherDeps = {
@@ -108,9 +112,10 @@ export class FrameworkLauncher {
     const state = await this.resolveLaunchState(request);
     return {
       tool: request.tool,
-      repositoryId: state.repository.id,
-      repositoryPath: state.repository.path,
       companionPath: state.companionPath,
+      ...(state.repository
+        ? { repositoryId: state.repository.id, repositoryPath: state.repository.path }
+        : {}),
     };
   }
 
@@ -118,27 +123,37 @@ export class FrameworkLauncher {
     const state = await this.resolveLaunchState(request);
     const adapterContext = this.makeAdapterContext(state);
 
-    if (await launcherDeps.isWrapped(state.repository.path)) {
+    if (state.repository && (await launcherDeps.isWrapped(state.repository.path))) {
       throw new LaunchPreflightError(wrappedRepositoryRefusal(state.repository));
     }
 
     if (!request.skipGit && state.config.git === "auto") {
       await launcherDeps.syncCompanionGit(
         state.companionPath,
-        state.repository.path,
+        state.repository?.path,
         request.interactiveGit ?? false,
       );
     }
-    await launcherDeps.syncCompanionFiles(state.companionPath, state.config, state.repository.path);
-    this.answerForProjection(
-      await launcherDeps.projectWorkingRepo({
-        repoPath: state.repository.path,
-        companionPath: state.companionPath,
-        config: state.config,
-      }),
-      state.repository,
-    );
-    await launcherDeps.refreshProjectionRoot(state.companionPath, state.repository);
+    if (state.repository) {
+      await launcherDeps.syncCompanionFiles(
+        state.companionPath,
+        state.config,
+        state.repository.path,
+      );
+    } else {
+      await launcherDeps.syncCompanionFiles(state.companionPath, state.config);
+    }
+    if (state.repository) {
+      this.answerForProjection(
+        await launcherDeps.projectWorkingRepo({
+          repoPath: state.repository.path,
+          companionPath: state.companionPath,
+          config: state.config,
+        }),
+        state.repository,
+      );
+      await launcherDeps.refreshProjectionRoot(state.companionPath, state.repository);
+    }
     await this.runCapabilityPreflight(state, request.tool);
     await state.adapter.validateLaunch(adapterContext);
 
@@ -158,10 +173,14 @@ export class FrameworkLauncher {
       companionPath,
       repositoryId,
       repository: localRepository,
-    } = await this.resolveConfig();
+    } = await this.resolveConfig(request.scope);
     const store = new CompanionStore(configStore, workingRepoStore);
-    const repository = localRepository ?? (await store.getRepository(repositoryId));
-    if (!repository) {
+    const scope = request.scope ?? "working-repo";
+    const repository =
+      scope === "companion"
+        ? undefined
+        : (localRepository ?? (await store.getRepository(repositoryId)));
+    if (scope === "working-repo" && !repository) {
       throw new RepositoryNotSelectedError(`Linked repository not found: ${repositoryId}`);
     }
 
@@ -180,6 +199,9 @@ export class FrameworkLauncher {
       companionPath,
       config,
       repository,
+      scope,
+      launchWorkingDirectory: scope === "companion" ? companionPath : repository!.path,
+      skipGit: request.skipGit ?? false,
     };
   }
 
@@ -210,8 +232,10 @@ export class FrameworkLauncher {
       repository: state.repository,
       allowedAgents: state.config.allowedAgents,
       companionPath: state.companionPath,
+      launchWorkingDirectory: state.launchWorkingDirectory,
       capabilities: state.config.capabilities ?? [],
       git: state.config.git,
+      skipGit: state.skipGit,
     };
   }
 
@@ -263,7 +287,7 @@ export class FrameworkLauncher {
     }
   }
 
-  private async resolveConfig(): Promise<LaunchContext> {
-    return resolveForLaunch(process.cwd());
+  private async resolveConfig(scope: LaunchScope = "working-repo"): Promise<LaunchContext> {
+    return resolveForLaunch(process.cwd(), undefined, scope);
   }
 }

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

@@ -13,6 +13,8 @@ import {
 import { getReactDoctorBinPath, getWrapperBinPath } from "../package-paths";
 import type { LinkedRepository } from "./types";
 
+export const COMPANION_GRAPHIFY_REPOSITORY_ID = "__companion__";
+
 /**
  * The one derivation of the projected paths. Both the Projection Root and a
  * managed launch materialize this record, so neither can hold its own copy of a
@@ -54,3 +56,25 @@ export function projectionEnvironment(projection: MateProjection): NodeJS.Proces
     PROJECTION_FIELDS.map((field) => [PROJECTION_ENV_NAMES[field], projection[field]]),
   );
 }
+
+/** Materializes the path-only subset used by a launch without a repository. */
+export function companionEnvironment(companionPath: string): NodeJS.ProcessEnv {
+  const values: Record<keyof MateProjection, string> = {
+    version,
+    companionPath,
+    repositoryPath: "",
+    repositoryId: "",
+    wrapperBinPath: getWrapperBinPath(),
+    reactDoctorBinPath: getReactDoctorBinPath(),
+    graphifyOut: path.join(
+      companionPath,
+      GRAPHIFY_STORE_SEGMENT,
+      COMPANION_GRAPHIFY_REPOSITORY_ID,
+      GRAPHIFY_OUTPUT_SUBDIR,
+    ),
+  };
+
+  return Object.fromEntries(
+    PROJECTION_FIELDS.map((field) => [PROJECTION_ENV_NAMES[field], values[field]]),
+  );
+}

package/src/lib/orchestrator/types.ts

@@ -35,6 +35,12 @@ export class WorkingRepoRequiredError extends MateError {
         "    mate companion link",
         "",
         "  To see linked repositories: mate companion list",
+        ...(command === "launch"
+          ? [
+              "",
+              "  To launch from the companion itself: `mate claude -- --companion` or `mate opencode -- --companion`",
+            ]
+          : []),
       ].join("\n"),
     );
   }
@@ -131,9 +137,12 @@ export interface CompanionRegistryConfig {
   repos: LinkedRepository[];
 }
 
+export type LaunchScope = "working-repo" | "companion";
+
 export interface LaunchRequest {
   tool: string;
   args: string[];
+  scope?: LaunchScope;
   skipGit?: boolean;
   interactiveGit?: boolean;
 }
@@ -142,4 +151,6 @@ export interface LaunchResult {
   exitCode: number;
   stdout: string;
   stderr: string;
+  /** Set when the agent process ended on a signal rather than its own exit. */
+  signal?: NodeJS.Signals | null;
 }

package/src/lib/prebuilt-workspace-prepare.ts

@@ -0,0 +1,152 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { PREBUILT_BUNDLE_MARKER as BUNDLE_MARKER } from "./preinstalled-plugins";
+import {
+  currentTarget,
+  getLocalWorkspaceDir,
+  validatePrebuiltWorkspace,
+  type PrebuiltWorkspaceTarget,
+} from "./prebuilt-workspace";
+
+export type PreparePrebuiltWorkspaceResult =
+  | { ok: true; workspacePath: string; reused: boolean; packages: Record<string, string> }
+  | { ok: false; workspacePath: string; failures: string[] };
+
+export const prebuiltWorkspaceDeps = {
+  /** Filesystem-only: a plain recursive copy, never a package manager or an install script. */
+  copy: (source: string, destination: string) =>
+    fs.cp(source, destination, { recursive: true, force: true, errorOnExist: false }),
+};
+
+/**
+ * Content identity of an installed tree: a version match is not enough, since
+ * two bundles can pin the same versions and still differ.
+ */
+export async function fingerprintWorkspace(root: string): Promise<string> {
+  const hash = crypto.createHash("sha256");
+  const walk = async (dir: string, prefix: string): Promise<void> => {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of [...entries].sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (prefix === "" && entry.name === BUNDLE_MARKER) continue;
+      const full = path.join(dir, entry.name);
+      const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) {
+        hash.update(`d:${relative}\n`);
+        await walk(full, relative);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        hash.update(`l:${relative}:${await fs.readlink(full).catch(() => "")}\n`);
+        continue;
+      }
+      hash.update(`f:${relative}:`);
+      hash.update(await fs.readFile(full));
+      hash.update("\n");
+    }
+  };
+  await walk(path.resolve(root), "");
+  return hash.digest("hex");
+}
+
+async function readBundleMarker(workspacePath: string): Promise<string | null> {
+  try {
+    const marker = JSON.parse(
+      await fs.readFile(path.join(workspacePath, BUNDLE_MARKER), "utf8"),
+    ) as { fingerprint?: string };
+    return marker.fingerprint ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function samePackages(a: Record<string, string>, b: Record<string, string>): boolean {
+  const names = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const name of names) if (a[name] !== b[name]) return false;
+  return true;
+}
+
+async function exists(target: string): Promise<boolean> {
+  return fs.access(target).then(
+    () => true,
+    () => false,
+  );
+}
+
+/**
+ * Copies a validated prebuilt workspace into the companion's machine-local
+ * workspace. Presents nothing, waits for nothing, reads no selection and
+ * writes none. A changed bundle is staged and validated before it replaces the
+ * framework-owned generated workspace; any failure leaves the existing
+ * workspace exactly as it was.
+ */
+export async function preparePrebuiltWorkspace(
+  companionPath: string,
+  bundlePath: string,
+  target: PrebuiltWorkspaceTarget = currentTarget(),
+): Promise<PreparePrebuiltWorkspaceResult> {
+  const workspacePath = getLocalWorkspaceDir(companionPath);
+  const source = path.resolve(bundlePath);
+
+  const bundle = await validatePrebuiltWorkspace(source, target);
+  if (!bundle.ok) return { ok: false, workspacePath, failures: bundle.failures };
+
+  const fingerprint = await fingerprintWorkspace(source);
+  if (await exists(workspacePath)) {
+    const existing = await validatePrebuiltWorkspace(workspacePath, target);
+    if (
+      existing.ok &&
+      samePackages(existing.packages, bundle.packages) &&
+      (await readBundleMarker(workspacePath)) === fingerprint
+    ) {
+      return { ok: true, workspacePath, reused: true, packages: existing.packages };
+    }
+  }
+
+  const staging = `${workspacePath}.staging`;
+  const previous = `${workspacePath}.previous`;
+  await fs.rm(staging, { recursive: true, force: true });
+  await fs.rm(previous, { recursive: true, force: true });
+
+  try {
+    await fs.mkdir(path.dirname(workspacePath), { recursive: true });
+    await prebuiltWorkspaceDeps.copy(source, staging);
+  } catch (error) {
+    await fs.rm(staging, { recursive: true, force: true });
+    return {
+      ok: false,
+      workspacePath,
+      failures: [`${source}: copying the bundle failed: ${(error as Error).message}`],
+    };
+  }
+
+  const staged = await validatePrebuiltWorkspace(staging, target);
+  if (!staged.ok) {
+    await fs.rm(staging, { recursive: true, force: true });
+    return { ok: false, workspacePath, failures: staged.failures };
+  }
+
+  await fs.writeFile(
+    path.join(staging, BUNDLE_MARKER),
+    `${JSON.stringify({ fingerprint, packages: staged.packages }, null, 2)}\n`,
+    "utf8",
+  );
+
+  const hadExisting = await exists(workspacePath);
+  try {
+    if (hadExisting) await fs.rename(workspacePath, previous);
+    await fs.rename(staging, workspacePath);
+  } catch (error) {
+    await fs.rm(staging, { recursive: true, force: true });
+    if (hadExisting && !(await exists(workspacePath))) await fs.rename(previous, workspacePath);
+    return {
+      ok: false,
+      workspacePath,
+      failures: [`${workspacePath}: replacing the workspace failed: ${(error as Error).message}`],
+    };
+  }
+  await fs.rm(previous, { recursive: true, force: true });
+
+  return { ok: true, workspacePath, reused: false, packages: staged.packages };
+}