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

package/src/lib/orchestrator/working-repo-projection.ts

@@ -1,22 +1,19 @@
-import { execFile } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { promisify } from "node:util";
 
 import { FRAMEWORK_NAME } from "../../framework";
-import { gitEnvironment } from "../../runtime/companion-git";
 import { readProjectionFile } from "../../runtime/projection";
+import { GlobalConfigStore } from "./global-config-store";
 import { repoLocalDirPath } from "../../runtime/repo-local";
-import type { GlobalConfigStore } from "./global-config-store";
 import { projectionEntries } from "./projection-entries";
 import {
-  isExternalDocument,
-  recordedRuntimeDocuments,
-  removeRuntimeDocuments,
-} from "./projection-runtime-documents";
+  copies as recordedCopies,
+  documents as recordedDocuments,
+  readManifest,
+} from "../../runtime/runtime-document-manifest";
+import { removeRuntimeDocuments } from "./projection-runtime-documents";
 import {
   firstFailure,
-  type RenderedRuntimeDocument,
   type ProjectionDescription,
   type ProjectionEntry,
   type ProjectionEntryOutcome,
@@ -26,10 +23,10 @@ import {
   type ProjectionRemovalResult,
   type ProjectionResult,
   type ProjectionScope,
+  type ProjectionWriteReport,
+  type ProjectionWriteState,
 } from "./projection-types";
-import type { FrameworkConfig, LinkedRepository } from "./types";
-
-const execFileAsync = promisify(execFile);
+import type { LinkedRepository } from "./types";
 
 /**
  * The owner of the Managed Projection: every path Mate places inside a Working
@@ -60,6 +57,22 @@ function outcome(
     state,
     ...(error ? { error } : {}),
     ...(entry.degradable ? { degradable: true } : {}),
+    ...(entry.runtime ? { runtime: entry.runtime } : {}),
+  };
+}
+
+/** One outcome shape for both forms a write may return; empty reports are omitted. */
+function writeOutcome(
+  entry: ProjectionEntry,
+  written: ProjectionWriteState | ProjectionWriteReport,
+): ProjectionEntryOutcome {
+  if (typeof written === "string") return outcome(entry, written);
+  const { state, warnings = [], changed } = written;
+  const anyChanged = changed && (changed.written.length > 0 || changed.removed.length > 0);
+  return {
+    ...outcome(entry, state),
+    ...(warnings.length > 0 ? { warnings } : {}),
+    ...(anyChanged ? { changed } : {}),
   };
 }
 
@@ -74,11 +87,13 @@ export async function project(
   input: ProjectionInput,
 ): Promise<ProjectionResult> {
   const outcomes: ProjectionEntryOutcome[] = [];
+  const runtimes = input.runtimes ? new Set(input.runtimes) : null;
   for (const entry of projectionEntries()) {
     if (!entry.scopes.includes(scope)) continue;
+    if (entry.runtime && runtimes && !runtimes.has(entry.runtime)) continue;
     try {
       // oxlint-disable-next-line no-await-in-loop -- catalogue order is the contract
-      outcomes.push(outcome(entry, await entry.write(input)));
+      outcomes.push(writeOutcome(entry, await entry.write(input))); // react-doctor-disable-line react-doctor/async-await-in-loop
     } catch (error) {
       outcomes.push(outcome(entry, "failed", toError(error)));
     }
@@ -93,7 +108,7 @@ export async function project(
  */
 export async function unproject(input: ProjectionRemovalInput): Promise<ProjectionRemovalResult> {
   const outcomes: ProjectionEntryOutcome[] = [];
-  for (const entry of [...projectionEntries()].reverse()) {
+  for (const entry of projectionEntries().toReversed()) {
     const { removal } = entry;
     if (removal.by === "entry") {
       outcomes.push(outcome(entry, "covered"));
@@ -113,39 +128,42 @@ export async function unproject(input: ProjectionRemovalInput): Promise<Projecti
   return { root: repoLocalDirPath(input.repoPath), outcomes };
 }
 
-/** Removes entries that wrap owns but an unwrap must withdraw independently. */
+/**
+ * Removes entries that wrap owns but an unwrap must withdraw independently.
+ * Sequential: several of them rewrite the manifest, and concurrent rewrites
+ * would restore each other's withdrawn records.
+ */
 async function removeWorkingRepositoryUnwrapEntries(
   repoPath: string,
+  registeredCompanionPaths: string[],
 ): Promise<ProjectionEntryOutcome[]> {
-  const entries = projectionEntries().filter(
-    (entry) => entry.removeOnUnwrap && entry.removal.by === "self",
-  );
-  return Promise.all(
-    entries.map(async (entry) => {
-      const removal = entry.removal;
-      if (removal.by !== "self") return outcome(entry, "failed", new Error("invalid removal"));
-      try {
-        return outcome(entry, await removal.remove({ repoPath }));
-      } catch (error) {
-        return outcome(entry, "failed", toError(error));
-      }
-    }),
-  );
+  const outcomes: ProjectionEntryOutcome[] = [];
+  for (const entry of projectionEntries()) {
+    const removal = entry.removal;
+    if (!entry.removeOnUnwrap || removal.by !== "self") continue;
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- each removal rewrites the manifest
+      outcomes.push(outcome(entry, await removal.remove({ repoPath, registeredCompanionPaths }))); // react-doctor-disable-line react-doctor/async-await-in-loop
+    } catch (error) {
+      outcomes.push(outcome(entry, "failed", toError(error)));
+    }
+  }
+  return outcomes;
 }
 
 /** Reads and reports; writes nothing. Freshness is a verdict above this module. */
 export async function describe(repoPath: string): Promise<ProjectionDescription> {
-  const entries: ProjectionEntryPresence[] = [];
-  for (const entry of projectionEntries()) {
-    const present = entry.present
-      ? // oxlint-disable-next-line no-await-in-loop -- reported in catalogue order
-        await entry.present(repoPath)
-      : await fs
-          .access(path.join(path.resolve(repoPath), entry.path))
-          .then(() => true)
-          .catch(() => false);
-    entries.push({ id: entry.id, path: entry.path, kind: entry.kind, present });
-  }
+  const entries: ProjectionEntryPresence[] = await Promise.all(
+    projectionEntries().map(async (entry) => {
+      const present = await (entry.present
+        ? entry.present(repoPath)
+        : fs
+            .access(path.join(path.resolve(repoPath), entry.path))
+            .then(() => true)
+            .catch(() => false));
+      return { id: entry.id, path: entry.path, kind: entry.kind, present };
+    }),
+  );
   return {
     root: repoLocalDirPath(repoPath),
     entries,
@@ -183,123 +201,12 @@ export async function projectWorkingRepository(
   };
 }
 
-/**
- * The rendered runtime documents, placed. Reported per document because the
- * operator asked for these by name: a failure has to say which one failed while
- * the projection already written stays where it is.
- */
-export type RuntimeDocumentsResult =
-  | { kind: "written" | "current"; documents: string[] }
-  | { kind: "failed"; document: string; error: Error };
-
-/**
- * Which of the given repo-relative paths Git already has in its index.
- * Best-effort by construction: a directory that is no repository, a Git that is
- * not installed, and a `ls-files` that fails for any other reason all answer
- * "nothing tracked" — this feeds a warning, and a warning may not fail a wrap.
- */
-async function trackedDocuments(repoPath: string, documentPaths: string[]): Promise<string[]> {
-  if (documentPaths.length === 0) return [];
-  try {
-    const { stdout } = await execFileAsync("git", ["ls-files", "-z", "--", ...documentPaths], {
-      cwd: path.resolve(repoPath),
-      encoding: "utf8",
-      env: gitEnvironment(),
-      maxBuffer: 64 * 1024 * 1024,
-    });
-    return stdout.split("\0").filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * The managed exclude block only hides a file Git does not already track, so a
- * repository that commits one of these documents keeps it in the index and the
- * regions land in a tracked file. Those regions carry machine-absolute
- * companion paths — keys naming directories under this user's home — so a
- * routine `git add -A` pushes one machine's layout to everyone else. Warn and
- * write anyway: refusing would silently drop the projection the repository was
- * wrapped for.
- *
- * Asked here rather than while rendering because the render also runs on every
- * launch; the wrap pass is the one that is a deliberate act, so this is the
- * scope where saying it once is information rather than noise.
- */
-async function warnAboutTrackedDocuments(
-  repository: LinkedRepository,
-  runtimeDocuments: readonly RenderedRuntimeDocument[],
-): Promise<void> {
-  const tracked = await trackedDocuments(
-    repository.path,
-    runtimeDocuments
-      .map((document) => document.path)
-      .filter((documentPath) => !isExternalDocument(documentPath)),
-  );
-  for (const documentPath of tracked) {
-    console.error(
-      `${FRAMEWORK_NAME}: warning: ${documentPath} is tracked by Git in ${repository.id}; ${FRAMEWORK_NAME} writes machine-absolute companion paths into it, so committing it would push this machine's paths to everyone else on the repository.`,
-    );
-    console.error(
-      `Untrack it with \`git rm --cached ${documentPath}\` if those paths should stay local.`,
-    );
-  }
-}
-
-export async function projectWorkingRuntimeDocuments(
-  companionPath: string,
-  repository: LinkedRepository,
-  config: FrameworkConfig,
-  runtimeDocuments: readonly RenderedRuntimeDocument[],
-  globalConfigStore?: GlobalConfigStore,
-): Promise<RuntimeDocumentsResult> {
-  await warnAboutTrackedDocuments(repository, runtimeDocuments);
-  const result = await project("wrap", {
-    repoPath: repository.path,
-    companionPath: path.resolve(companionPath),
-    repository,
-    config,
-    runtimeDocuments,
-    globalConfigStore,
-  });
-
-  const failure = firstFailure(result.outcomes);
-  if (failure) {
-    return {
-      kind: "failed",
-      document: failure.path,
-      error: failure.error ?? new Error("runtime document write failed"),
-    };
-  }
-
-  /** The destinations the caller handed over; the rest of the pass is scaffolding. */
-  const destinations = new Set(
-    runtimeDocuments.map((document) => document.path.split("/").join(path.sep)),
-  );
-  const outcomes = result.outcomes.filter((outcome) => destinations.has(outcome.path));
-  return {
-    kind: outcomes.some((outcome) => outcome.state === "written") ? "written" : "current",
-    documents: [...new Set(outcomes.map((outcome) => outcome.path))],
-  };
-}
-
-/**
- * Whether `mate wrap` configured this Working Repository. Asked of the runtime
- * document manifest rather than of the Projection Root, because the root is not
- * evidence of a wrap: a launch and every Capability command write the
- * projection pair too. The manifest is written only by a pass that placed a
- * runtime document, and wrapping is the only pass that places one.
- */
-export async function isWorkingRepositoryWrapped(repoPath: string): Promise<boolean> {
-  return (await recordedRuntimeDocuments(repoPath)).length > 0;
-}
-
 export type UnwrapResult =
-  | { kind: "unwrapped" | "absent"; documents: string[] }
+  | { kind: "unwrapped" | "absent"; documents: string[]; copies: string[] }
   | { kind: "failed"; document: string; error: Error };
 
 /**
- * The inverse of {@link projectWorkingRuntimeDocuments}: runtime documents and
+ * The inverse of a wrap's runtime documents: runtime documents and
  * projected Claude skill links are withdrawn while the Projection Root, the
  * Repository Link and the companion link are left exactly as they were. That
  * asymmetry with `mate working cleanup` is the point — cleanup removes Mate's
@@ -311,10 +218,15 @@ export type UnwrapResult =
  * Driven by the manifest, so it withdraws whatever the wrap that ran recorded,
  * including a destination this release no longer renders.
  */
-export async function unwrapWorkingRuntimeDocuments(repoPath: string): Promise<UnwrapResult> {
-  const documents = await recordedRuntimeDocuments(repoPath);
+export async function unwrapWorkingRuntimeDocuments(
+  repoPath: string,
+  globalConfigStore: GlobalConfigStore = new GlobalConfigStore(),
+): Promise<UnwrapResult> {
+  const manifest = await readManifest(repoPath);
+  const documents = recordedDocuments(manifest);
+  const copies = Object.keys(recordedCopies(manifest));
   const removeWrapEntries = async (): Promise<ProjectionEntryOutcome[]> =>
-    removeWorkingRepositoryUnwrapEntries(repoPath);
+    removeWorkingRepositoryUnwrapEntries(repoPath, await globalConfigStore.list());
   if (documents.length === 0) {
     const outcomes = await removeWrapEntries();
     const failure = firstFailure(outcomes);
@@ -326,8 +238,8 @@ export async function unwrapWorkingRuntimeDocuments(repoPath: string): Promise<U
       };
     }
     return outcomes.some((entry) => entry.state === "removed")
-      ? { kind: "unwrapped", documents: [] }
-      : { kind: "absent", documents: [] };
+      ? { kind: "unwrapped", documents: [], copies }
+      : { kind: "absent", documents: [], copies: [] };
   }
 
   /**
@@ -349,7 +261,7 @@ export async function unwrapWorkingRuntimeDocuments(repoPath: string): Promise<U
       error: failure.error ?? new Error("wrap entry removal failed"),
     };
   }
-  return { kind: "unwrapped", documents: removed };
+  return { kind: "unwrapped", documents: removed, copies };
 }
 
 /**

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

@@ -1,7 +1,7 @@
 import path from "node:path";
 
-import { pathIsDirectory } from "./repo-local-registry";
-import { readCompanionRegistry } from "./companion-registry-reader";
+import { pathIsDirectory } from "../fs-utils";
+import { readCompanionRegistry } from "./repository-link";
 import { GlobalConfigStore } from "./global-config-store";
 import type { LinkedRepository } from "./types";
 

package/src/lib/orchestrator/wrap-pass.ts

@@ -0,0 +1,131 @@
+import path from "node:path";
+
+import { renderWorkingRuntimeDocuments } from "../../tools/setup";
+import { readCompanionConfig } from "./config-store";
+import { GlobalConfigStore } from "./global-config-store";
+import { entryFailureMessage, firstFailure, type ProjectionChangedPaths } from "./projection-types";
+import type { WrapRuntime } from "../../runtime/runtime-document-manifest";
+import { readWrapState, type WrapState } from "../../runtime/wrap-state";
+import type { FrameworkConfig, LinkedRepository } from "./types";
+import { project } from "./working-repo-projection";
+
+export interface WrapPassDependencies {
+  renderWorkingRuntimeDocuments: typeof renderWorkingRuntimeDocuments;
+  readCompanionConfig: typeof readCompanionConfig;
+  project: typeof project;
+  /** The registered companions, whose stale skill links a re-pin withdraws; the user's registry when absent. */
+  globalConfigStore?: GlobalConfigStore;
+}
+
+export const wrapPassDeps: WrapPassDependencies = {
+  renderWorkingRuntimeDocuments,
+  readCompanionConfig,
+  project,
+};
+
+export interface WrapPassOptions {
+  /** Reconcile only these runtimes; every active runtime when absent. */
+  runtimes?: readonly WrapRuntime[];
+  /** The companion config the caller already read; read from files otherwise. */
+  config?: FrameworkConfig;
+}
+
+export type WrapPassResult =
+  | {
+      kind: "written" | "current";
+      projectionRoot: string;
+      companionPath: string;
+      /** The runtime documents this pass answered for, written or current. */
+      documents: string[];
+      /** The subset of `documents` this pass wrote. */
+      writtenDocuments: string[];
+      /** Every path an entry reported writing or withdrawing one by one. */
+      changed: ProjectionChangedPaths;
+      /** The render's warnings, then every entry's, for the caller to present. */
+      warnings: string[];
+      /** Active runtimes whose tagged entries this pass ran; never inferred from paths. */
+      runtimes: ReadonlySet<WrapRuntime>;
+      /** The wrap state as this pass left it. */
+      wrapState: WrapState;
+    }
+  | { kind: "failed"; message: string };
+
+/**
+ * One pass of the `wrap` scope, restricted to the requested runtimes by each
+ * entry's runtime tag. Best-effort per entry like every projection: a failed
+ * entry fails the pass while whatever the other entries wrote stays in place.
+ */
+export async function runWrapPass(
+  companionPath: string,
+  repository: LinkedRepository,
+  options: WrapPassOptions = {},
+  deps: WrapPassDependencies = wrapPassDeps,
+): Promise<WrapPassResult> {
+  const resolvedCompanionPath = path.resolve(companionPath);
+  const config = options.config ?? (await deps.readCompanionConfig(resolvedCompanionPath));
+  const rendered = await deps.renderWorkingRuntimeDocuments(
+    resolvedCompanionPath,
+    config,
+    repository.path,
+  );
+  const result = await deps.project("wrap", {
+    repoPath: repository.path,
+    companionPath: resolvedCompanionPath,
+    repository,
+    config,
+    runtimeDocuments: rendered.documents,
+    globalConfigStore: deps.globalConfigStore ?? new GlobalConfigStore(),
+    ...(options.runtimes ? { runtimes: options.runtimes } : {}),
+  });
+
+  const failure = firstFailure(result.outcomes);
+  if (failure) return { kind: "failed", message: entryFailureMessage(failure, repository.id) };
+
+  /** Read once under the caller's lock, so it is exactly what the pass recorded. */
+  let wrapState: WrapState;
+  try {
+    wrapState = await readWrapState(repository.path);
+  } catch (error) {
+    return {
+      kind: "failed",
+      message: `could not read the runtime document manifest for ${repository.id}: ${(error as Error).message}`,
+    };
+  }
+  /** Inactive runtimes' entries run too, to withdraw; that is not covering them. */
+  const active = new Set(config.allowedAgents ?? []);
+  const runtimes = new Set(
+    result.outcomes.flatMap((outcome) =>
+      outcome.runtime && outcome.state !== "skipped" && active.has(outcome.runtime)
+        ? [outcome.runtime]
+        : [],
+    ),
+  );
+
+  /** The destinations the surfaces rendered; the rest of the pass is scaffolding. */
+  const destinations = new Set(
+    rendered.documents.map((document) => document.path.split("/").join(path.sep)),
+  );
+  const placed = result.outcomes.filter((outcome) => destinations.has(outcome.path));
+  const documents = placed.map((outcome) => outcome.path);
+  const writtenDocuments = placed
+    .filter((outcome) => outcome.state === "written")
+    .map((outcome) => outcome.path);
+
+  return {
+    kind: result.outcomes.some((outcome) => outcome.state === "written") ? "written" : "current",
+    projectionRoot: result.root,
+    companionPath: resolvedCompanionPath,
+    documents: [...new Set(documents)],
+    writtenDocuments: [...new Set(writtenDocuments)],
+    changed: {
+      written: result.outcomes.flatMap((outcome) => outcome.changed?.written ?? []),
+      removed: result.outcomes.flatMap((outcome) => outcome.changed?.removed ?? []),
+    },
+    warnings: [
+      ...rendered.warnings,
+      ...result.outcomes.flatMap((outcome) => outcome.warnings ?? []),
+    ],
+    runtimes,
+    wrapState,
+  };
+}

package/src/lib/runtime-directory-refresh.ts

@@ -0,0 +1,186 @@
+import crypto from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { FRAMEWORK_NAME } from "../framework";
+import {
+  runtimeDirectoryPath,
+  runtimeClaudePluginRoot,
+  runtimeMateBin,
+  runtimeOpenCodePluginRoot,
+  runtimeWrapperBinPath,
+} from "../runtime/runtime-directory";
+import { writeAtomic } from "../runtime/write-atomic";
+import { realLinkTarget, realOrResolved } from "./fs-utils";
+import { getClaudePluginRoot, getOpenCodePluginRoot, getWrapperBinPath } from "./package-paths";
+
+export interface RuntimeDirectoryTargets {
+  pluginRoot: string;
+  claudePluginRoot: string;
+  /** The resolved `wrappers/bin`; its parent is what the `wrappers` link names. */
+  wrapperBinPath: string;
+  /** The interpreter running this CLI, written into the launcher. */
+  execPath: string;
+  cliEntry: string;
+}
+
+export interface RuntimeDirectoryRefresh {
+  /** Entries rewritten by this run, relative to the runtime directory. */
+  changed: string[];
+}
+
+/**
+ * `process.execPath` is the resolved, often versioned, binary (Homebrew's
+ * `Cellar/bun/<version>/bin/bun`), which an upgrade deletes. A `PATH` entry of
+ * the same name that is a link to it survives the upgrade; without one the
+ * resolved path is all there is.
+ */
+export function stableInterpreterPath(
+  execPath: string,
+  pathValue: string | undefined = process.env.PATH,
+): string {
+  let real: string;
+  try {
+    real = fsSync.realpathSync(execPath);
+  } catch {
+    return execPath;
+  }
+  const name = path.basename(execPath);
+  for (const dir of (pathValue ?? "").split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(dir, name);
+    if (candidate === real) continue;
+    try {
+      if (fsSync.realpathSync(candidate) === real) return candidate;
+    } catch {
+      /* not on this PATH entry */
+    }
+  }
+  return execPath;
+}
+
+function currentRuntimeDirectoryTargets(): RuntimeDirectoryTargets {
+  return {
+    pluginRoot: getOpenCodePluginRoot(),
+    claudePluginRoot: getClaudePluginRoot(),
+    wrapperBinPath: getWrapperBinPath(),
+    execPath: stableInterpreterPath(process.execPath),
+    cliEntry: path.resolve(process.argv[1] ?? ""),
+  };
+}
+
+/** The link's {@link realLinkTarget}; `""` when not a link, `null` when absent. */
+async function readLinkTarget(linkPath: string): Promise<string | null> {
+  try {
+    const stat = await fs.lstat(linkPath);
+    if (!stat.isSymbolicLink()) return "";
+    return await realLinkTarget(linkPath, await fs.readlink(linkPath));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * Junctions on Windows need no admin rights or Developer Mode. On POSIX a
+ * sibling link renamed over the old one keeps concurrent runs from ever seeing
+ * the entry missing.
+ */
+async function pointLink(linkPath: string, target: string): Promise<boolean> {
+  const [current, wanted] = await Promise.all([readLinkTarget(linkPath), realOrResolved(target)]);
+  if (current === wanted) return false;
+  await fs.mkdir(path.dirname(linkPath), { recursive: true });
+  if (process.platform === "win32") {
+    await fs.rm(linkPath, { recursive: true, force: true });
+    await fs.symlink(target, linkPath, "junction");
+    return true;
+  }
+  /** A rename cannot replace a real directory or file. */
+  if (current === "") await fs.rm(linkPath, { recursive: true, force: true });
+  const tempPath = `${linkPath}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.symlink(target, tempPath, "dir");
+    await fs.rename(tempPath, linkPath);
+  } catch (error) {
+    await fs.rm(tempPath, { force: true }).catch(() => {});
+    throw error;
+  }
+  return true;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+function launcherContent(targets: RuntimeDirectoryTargets, platform: NodeJS.Platform): string {
+  if (platform === "win32") {
+    return `@echo off\r\n"${targets.execPath}" "${targets.cliEntry}" %*\r\n`;
+  }
+  return `#!/bin/sh\nexec ${shellQuote(targets.execPath)} ${shellQuote(targets.cliEntry)} "$@"\n`;
+}
+
+async function writeLauncher(
+  launcherPath: string,
+  targets: RuntimeDirectoryTargets,
+): Promise<boolean> {
+  const next = launcherContent(targets, process.platform);
+  const existing = await fs.readFile(launcherPath, "utf8").catch(() => null);
+  if (existing === next) return false;
+  await fs.mkdir(path.dirname(launcherPath), { recursive: true });
+  await writeAtomic(launcherPath, next, 0o755);
+  return true;
+}
+
+/** Re-points or rewrites only the entries whose target differs from `targets`. */
+export async function refreshRuntimeDirectory(
+  targets: RuntimeDirectoryTargets = currentRuntimeDirectoryTargets(),
+  homeDir?: string,
+): Promise<RuntimeDirectoryRefresh> {
+  const root = runtimeDirectoryPath(homeDir);
+  const launcherPath = runtimeMateBin(homeDir);
+  const changed: string[] = [];
+  if (await pointLink(runtimeOpenCodePluginRoot(homeDir), targets.pluginRoot)) {
+    changed.push("opencode-plugin");
+  }
+  if (await pointLink(runtimeClaudePluginRoot(homeDir), targets.claudePluginRoot)) {
+    changed.push("claude-plugin");
+  }
+  const wrappersLink = path.dirname(runtimeWrapperBinPath(homeDir));
+  if (await pointLink(wrappersLink, path.dirname(targets.wrapperBinPath))) {
+    changed.push("wrappers");
+  }
+  if (await writeLauncher(launcherPath, targets)) {
+    changed.push(path.relative(root, launcherPath).split(path.sep).join("/"));
+  }
+  return { changed };
+}
+
+/** Commands whose output names runtime-directory paths cannot run without it. */
+const RUNTIME_DIRECTORY_COMMANDS = new Set(["wrap", "opencode", "session"]);
+
+function runtimeDirectoryRequired(command: string | undefined): boolean {
+  return command !== undefined && RUNTIME_DIRECTORY_COMMANDS.has(command);
+}
+
+/**
+ * Startup refresh: a failure warns, except for the commands that write or
+ * consume runtime-directory paths, where it is returned as fatal.
+ */
+export async function ensureRuntimeDirectory(
+  command: string | undefined,
+  refresh: () => Promise<RuntimeDirectoryRefresh> = () => refreshRuntimeDirectory(),
+): Promise<boolean> {
+  try {
+    await refresh();
+    return true;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const message = `failed to update ${runtimeDirectoryPath()}: ${detail}`;
+    if (runtimeDirectoryRequired(command)) {
+      console.error(`${FRAMEWORK_NAME}: ${message}`);
+      return false;
+    }
+    console.error(`${FRAMEWORK_NAME}: warning: ${message}`);
+    return true;
+  }
+}

package/src/lib/update-checker.ts

@@ -99,6 +99,11 @@ export function isCanaryVersion(version: string = getCurrentVersion()): boolean
   return version.includes("-canary");
 }
 
+/** Versions packed by `pack-local.sh` (`x.y.z-local.n`) are local test builds. */
+export function isLocalVersion(version: string = getCurrentVersion()): boolean {
+  return version.includes("-local");
+}
+
 export type UpdateChannel = "latest" | "canary";
 
 export function getUpdateChannel(version: string = getCurrentVersion()): UpdateChannel {
@@ -134,6 +139,7 @@ export async function showUpdateBannerIfAvailable(store: UpdateStateStore): Prom
 export async function enforceUpdateIfRequired(store: UpdateStateStore): Promise<boolean> {
   if (isPinnedDeployment()) return false;
   if (!getUpdateConfig().enforce) return false;
+  if (isLocalVersion()) return false;
   try {
     const state = await store.load();
     if (!state.latestVersion) return false;