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

package/src/cli/commands/studio/views/client.ts

@@ -91,7 +91,11 @@ export const STUDIO_CLIENT_SCRIPT = `(function () {
   }
 
   function copy(text, label) {
-    return navigator.clipboard.writeText(text).then(
+    if (typeof navigator === "undefined" || !navigator.clipboard || typeof navigator.clipboard.writeText !== "function") {
+      announce("copying is blocked in this browser");
+      return Promise.resolve();
+    }
+    return Promise.resolve().then(function () { return navigator.clipboard.writeText(text); }).then(
       function () {
         announce("copied " + label);
       },
@@ -194,4 +198,140 @@ export const STUDIO_CLIENT_SCRIPT = `(function () {
       if (text) copy(text, node.getAttribute("data-copy-label") || "prompt");
     });
   });
+
+  var savePromise = null;
+  function editor() { return document.getElementById("vault-editor"); }
+  function status(message) {
+    var node = document.getElementById("vault-status");
+    if (node) node.textContent = message;
+  }
+  function dirty() {
+    var node = editor();
+    return !!node && node.value !== (node.getAttribute("data-vault-original") || "");
+  }
+  function setIncoming(event) {
+    var box = document.getElementById("vault-incoming");
+    var content = document.getElementById("vault-incoming-content");
+    var recover = document.getElementById("vault-recover");
+    if (!box || !content || !recover) return;
+    box.hidden = false;
+    content.textContent = event.content || "";
+    recover.setAttribute("data-vault-content", event.content || "");
+    recover.setAttribute("data-vault-token", event.token || "");
+  }
+  function acceptIncoming(event) {
+    var node = editor();
+    if (!node) return;
+    node.value = event.content || "";
+    node.setAttribute("data-vault-original", node.value);
+    if (event.token) node.setAttribute("data-vault-token", event.token);
+    var box = document.getElementById("vault-incoming");
+    if (box) box.hidden = true;
+    status("incoming version loaded into the editor");
+  }
+  function askBeforeNavigation() {
+    return !dirty() || window.confirm("Discard unsaved changes?");
+  }
+  function waitForSave() {
+    return savePromise ? savePromise.then(function (result) { return result; }) : Promise.resolve(true);
+  }
+  function navigate(url) {
+    waitForSave().then(function (allowed) {
+      if (allowed && askBeforeNavigation()) location.assign(url);
+    });
+  }
+  function navigationUrl(form, submitter) {
+    var target = new URL(form.action || location.href, location.href);
+    new FormData(form).forEach(function (value, key) {
+      if (typeof value === "string") target.searchParams.append(key, value);
+    });
+    if (submitter && submitter.name && submitter.value) target.searchParams.set(submitter.name, submitter.value);
+    return target.toString();
+  }
+  function wireNavigation() {
+    document.querySelectorAll('form[method="get"]').forEach(function (form) {
+      form.addEventListener("submit", function (event) {
+        event.preventDefault();
+        navigate(navigationUrl(form, event.submitter));
+      });
+      form.querySelectorAll("select").forEach(function (select) {
+        select.addEventListener("change", function () { navigate(navigationUrl(form)); });
+      });
+    });
+  }
+  function wireVault() {
+    var node = editor();
+    var root = document.querySelector("[data-vault-root]");
+    if (!node || !root) return;
+    node.setAttribute("data-vault-original", node.value);
+    var save = document.getElementById("vault-save");
+    if (save) save.addEventListener("click", function () {
+      if (savePromise) return;
+      var companion = document.querySelector("[data-companion]");
+      var body = {
+        companion: companion ? companion.getAttribute("data-companion") : "",
+        path: node.getAttribute("data-vault-path"),
+        content: node.value,
+        token: node.getAttribute("data-vault-token"),
+      };
+      savePromise = fetch("/api/vault/save", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+      }).then(function (response) {
+        return response.json().then(function (result) {
+          if (!response.ok) {
+            if (response.status === 409) setIncoming(result);
+            status(result.reason || "save refused");
+            return false;
+          }
+          node.setAttribute("data-vault-token", result.token || "");
+          node.setAttribute("data-vault-original", node.value);
+          status("saved");
+          return true;
+        });
+      }).catch(function () {
+        status("save failed");
+        return false;
+      }).finally(function () { savePromise = null; });
+    });
+    var recover = document.getElementById("vault-recover");
+    if (recover) recover.addEventListener("click", function () {
+      acceptIncoming({ content: recover.getAttribute("data-vault-content") || "", token: recover.getAttribute("data-vault-token") || "" });
+    });
+    var companion = document.querySelector("[data-companion]");
+    var path = node.getAttribute("data-vault-path");
+    if (companion && path && typeof EventSource !== "undefined") {
+      var events = new EventSource("/api/vault/events?companion=" + encodeURIComponent(companion.getAttribute("data-companion") || "") + "&path=" + encodeURIComponent(path));
+      events.onmessage = function (message) {
+        var event;
+        try { event = JSON.parse(message.data); } catch (error) { return; }
+        if (event.kind === "overwritten") {
+          setIncoming(event);
+          status("a version was overwritten; its content is available below");
+          return;
+        }
+        if (event.kind === "removed") {
+          status("this file no longer exists on disk");
+          return;
+        }
+        if (dirty()) {
+          setIncoming(event);
+          status("the file changed on disk; unsaved content is still in the editor");
+          return;
+        }
+        node.value = event.content || "";
+        node.setAttribute("data-vault-original", node.value);
+        if (event.token) node.setAttribute("data-vault-token", event.token);
+        status("updated from disk");
+      };
+    }
+  }
+  if (typeof window !== "undefined") window.addEventListener("beforeunload", function (event) {
+      if (!dirty()) return;
+      event.preventDefault();
+      event.returnValue = "";
+    });
+  wireNavigation();
+  wireVault();
 })();`;

package/src/cli/commands/studio/views/companion-selector.tsx

@@ -25,7 +25,7 @@ export function CompanionSelector({ inventory, selection }: CompanionSelectorPro
         <input type="hidden" name="view" value={selection.view} />
       )}
       {/* eslint-disable-next-line react/no-unknown-property -- raw HTML attribute: hono/jsx server-renders this inline handler */}
-      <select name="companion" aria-label="Companion Repository" onchange="this.form.submit()">
+      <select name="companion" aria-label="Companion Repository">
         <PlaceholderOption companionCount={companions.length} selected={selected} />
         {companions.map((companion) => {
           const digest = companionDigest(companion.path);

package/src/cli/commands/studio/views/document.tsx

@@ -1,12 +1,13 @@
 /** @jsxImportSource hono/jsx */
 
-import { companionDigest, REFRESH_PARAM, type StudioSelection } from "../selection";
+import { companionDigest, FILE_PARAM, REFRESH_PARAM, type StudioSelection } from "../selection";
 import { STUDIO_CLIENT_SCRIPT, STUDIO_PREPAINT_SCRIPT } from "./client";
 import { CompanionPicker } from "./companion-picker";
 import { CompanionSelector } from "./companion-selector";
 import { Dashboard } from "./dashboard/index";
 import { CompanionError } from "./error";
-import { formatCollectedAt, type StudioPage } from "./model";
+import { formatCollectedAt, type StudioPage, type StudioVaultPage } from "./model";
+import type { VaultTreeNode } from "../vault";
 import { Specs } from "./specs/index";
 import { STUDIO_STYLES } from "./styles";
 import { Skills } from "./skills/index";
@@ -31,6 +32,10 @@ const VIEW_DETAILS = {
     eyebrow: "Agent guidance",
     title: "Skills",
   },
+  vault: {
+    eyebrow: "Companion files",
+    title: "Vault",
+  },
 } as const;
 
 /**
@@ -86,6 +91,7 @@ function Content({ page }: { page: StudioPage }) {
   if (page.error) {
     return <CompanionError companionPath={page.error.companionPath} reason={page.error.reason} />;
   }
+  if (page.selection.view === "vault") return <Vault page={page} />;
   if (!page.payload) {
     return (
       <section className="panel">
@@ -153,7 +159,7 @@ function ViewNav({ selection }: { selection: StudioSelection }) {
     <nav className="sidebar-nav" aria-label="Studio views">
       <span className="sidebar-label">Views</span>
       <form method="get" action="/">
-        <SelectionFields selection={selection} omit="view" />
+        <SelectionFields selection={selection} omit="view" dropOpenPath />
         <div className="sidebar-nav-list">
           <button
             type="submit"
@@ -163,6 +169,9 @@ function ViewNav({ selection }: { selection: StudioSelection }) {
           >
             <span>Overview</span>
           </button>
+          <button type="submit" name="view" value="vault" aria-pressed={selection.view === "vault"}>
+            <span>Vault</span>
+          </button>
           <button type="submit" name="view" value="specs" aria-pressed={selection.view === "specs"}>
             <span>Specs</span>
           </button>
@@ -239,9 +248,11 @@ function Footer({ page }: { page: StudioPage }) {
 function SelectionFields({
   selection,
   omit,
+  dropOpenPath = false,
 }: {
   selection: StudioSelection;
   omit?: keyof StudioSelection;
+  dropOpenPath?: boolean;
 }) {
   return (
     <>
@@ -251,6 +262,129 @@ function SelectionFields({
       {selection.view !== "dashboard" && omit !== "view" ? (
         <input type="hidden" name="view" value={selection.view} />
       ) : null}
+      {selection.view === "vault" && selection.openPath && !dropOpenPath ? (
+        <input type="hidden" name={FILE_PARAM} value={selection.openPath} />
+      ) : null}
     </>
   );
 }
+
+function Vault({ page }: { page: StudioPage }) {
+  const vault = page.vault;
+  if (!vault)
+    return (
+      <section className="panel">
+        <p className="empty">No vault state collected.</p>
+      </section>
+    );
+  return (
+    <section className="vault-layout">
+      <div className="panel vault-tree-panel">
+        <div className="section-header">
+          <div>
+            <h3>Markdown files</h3>
+            <p className="section-note">
+              {vault.tree.length === 0
+                ? "This companion has no markdown files."
+                : "Every non-ignored markdown file in this companion."}
+            </p>
+          </div>
+          {!vault.watching ? (
+            <form method="get" action="/" data-studio-navigation>
+              <SelectionFields selection={page.selection} />
+              <input type="hidden" name={REFRESH_PARAM} value="1" />
+              <button type="submit">Refresh tree</button>
+            </form>
+          ) : null}
+        </div>
+        {vault.warning ? (
+          <p className="note vault-warning">{vault.warning}. The tree may be out of date.</p>
+        ) : null}
+        <nav aria-label="Markdown files">
+          {vault.tree.map((node) => (
+            <VaultNode key={node.path} node={node} selection={page.selection} />
+          ))}
+        </nav>
+      </div>
+      <VaultEditor page={page} vault={vault} />
+    </section>
+  );
+}
+
+function VaultNode({ node, selection }: { node: VaultTreeNode; selection: StudioSelection }) {
+  if (node.kind === "directory") {
+    return (
+      <details open className="vault-directory">
+        <summary>{node.name}</summary>
+        <div className="vault-children">
+          {node.children?.map((child) => (
+            <VaultNode key={child.path} node={child} selection={selection} />
+          ))}
+        </div>
+      </details>
+    );
+  }
+  return (
+    <form method="get" action="/" className="vault-file" data-studio-navigation>
+      <SelectionFields selection={selection} dropOpenPath />
+      <input type="hidden" name={FILE_PARAM} value={node.path} />
+      <button type="submit" aria-current={selection.openPath === node.path ? "page" : undefined}>
+        {node.name}
+      </button>
+    </form>
+  );
+}
+
+function VaultEditor({ page, vault }: { page: StudioPage; vault: StudioVaultPage }) {
+  if (!vault.open) {
+    return (
+      <div className="panel vault-editor-panel">
+        <h3>{vault.refusal ? "File refused" : "Open a markdown file"}</h3>
+        <p className={vault.refusal ? "note vault-warning" : "empty"}>
+          {vault.refusal ?? "Choose a file from the tree to begin."}
+        </p>
+      </div>
+    );
+  }
+  return (
+    <div
+      className="panel vault-editor-panel"
+      data-vault-root
+      data-vault-writable={page.writable ? "true" : "false"}
+    >
+      <div className="section-header">
+        <div>
+          <h3>{vault.open.path}</h3>
+          <p className="section-note">
+            {page.writable
+              ? "Changes stay in the editor until you save."
+              : "Read-only mode. Start Studio with --writable to save."}
+          </p>
+        </div>
+        {page.writable ? (
+          <button type="button" id="vault-save">
+            Save
+          </button>
+        ) : null}
+      </div>
+      <textarea
+        id="vault-editor"
+        data-vault-editor
+        data-vault-path={vault.open.path}
+        data-vault-token={vault.open.token}
+        {...(page.writable ? {} : { readOnly: true })}
+        spellCheck={false}
+      >
+        {vault.open.content}
+      </textarea>
+      <p id="vault-status" className="note" aria-live="polite" />
+      <div id="vault-incoming" className="vault-incoming" hidden>
+        <strong id="vault-incoming-title">Incoming version</strong>
+        <pre id="vault-incoming-content" />
+        <button type="button" id="vault-recover">
+          Put incoming content back
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/cli/commands/studio/views/model.ts

@@ -1,6 +1,7 @@
 import type { StudioInventory, StudioInventoryCompanion } from "../inventory";
 import type { StudioCompanionPayload } from "../payload";
 import type { StudioSelection } from "../selection";
+import type { VaultFile, VaultTreeNode } from "../vault";
 
 /**
  * Everything one rendered document is derived from. `payload` and `error` are
@@ -15,6 +16,18 @@ export interface StudioPage {
   payload: StudioCompanionPayload | null;
   error: { companionPath: string; reason: string } | null;
   collectedAt: number | null;
+  writable: boolean;
+  vault: StudioVaultPage | null;
+}
+
+export interface StudioVaultPage {
+  tree: VaultTreeNode[];
+  open: VaultFile | null;
+  refusal: string | null;
+  incoming: VaultFile | null;
+  overwritten: VaultFile | null;
+  watching: boolean;
+  warning: string | null;
 }
 
 /**

package/src/cli/commands/studio/views/styles.ts

@@ -360,6 +360,23 @@ ul.plain li:last-child { border-bottom: 0; }
 .workflow-option small { color: var(--muted); font-size: .65rem; line-height: 1.35; }
 .workflow-option .runway-step-copy { justify-self: start; }
 
+.vault-layout { display: grid; grid-template-columns: minmax(190px, .34fr) minmax(0, 1fr); gap: 16px; align-items: start; }
+.vault-tree-panel, .vault-editor-panel { min-width: 0; }
+.vault-tree-panel nav { display: grid; gap: 2px; }
+.vault-directory { color: var(--muted); font-family: var(--mono); font-size: .75rem; }
+.vault-directory summary { cursor: pointer; padding: 5px 4px; }
+.vault-children { display: grid; gap: 2px; padding-left: 12px; }
+.vault-file { display: contents; }
+.vault-file button { width: 100%; overflow: hidden; padding: 6px 8px; border-color: transparent; background: transparent; color: var(--text); font-family: var(--mono); font-size: .72rem; text-overflow: ellipsis; white-space: nowrap; }
+.vault-file button:hover, .vault-file button[aria-current="page"] { border-color: var(--border); background: var(--accent-soft); color: var(--accent); }
+.vault-warning { color: var(--warn); }
+#vault-editor { display: block; width: 100%; min-height: 62vh; resize: vertical; padding: 16px; border: 1px solid var(--border); border-radius: 8px; background: var(--prompt-bg); color: var(--prompt-text); font-family: var(--mono); font-size: .86rem; line-height: 1.6; }
+#vault-editor:focus { outline: 2px solid var(--accent); outline-offset: 2px; }
+#vault-editor[readonly] { cursor: default; opacity: .85; }
+.vault-incoming { display: grid; gap: 8px; margin-top: 16px; padding: 12px; border: 1px solid var(--warn); border-radius: 8px; background: var(--warn-soft); }
+.vault-incoming pre { max-height: 220px; overflow: auto; margin: 0; white-space: pre-wrap; font-family: var(--mono); font-size: .78rem; }
+@media (max-width: 800px) { .vault-layout { grid-template-columns: 1fr; } }
+
 @media (max-width: 650px) {
   .workflow-console-header { grid-template-columns: 1fr auto; }
   .workflow-console-context, .workflow-console-tabs { margin-left: 0; }

package/src/cli/commands/studio/views/workflow/steps.ts

@@ -240,13 +240,20 @@ export function workflowPlan(
       profile: "mate-minimal",
       label: "mate-minimal",
       description:
-        "Short path that creates only specs and tasks for one-Area, low-risk changes; switch to mate-v1 when uncertain.",
+        "Short path that explores first, then creates only specs and tasks for one-Area, low-risk changes; switch to mate-v1 when uncertain.",
       steps: [
+        skillStep(
+          "explore",
+          "explore",
+          "Resolves repository evidence, unknowns, options, and direction without adding a planning artifact.",
+          "It gives the minimal proposal step an agreed direction while keeping the output to specs and tasks.",
+          "mate-minimal",
+        ),
         skillStep(
           "propose",
           "propose",
-          "Creates the concise, parser-compatible behavior change.",
-          "OpenSpec generates the minimal specs and tasks artifacts from the agreed direction.",
+          "Creates the concise, parser-compatible specs and tasks from the explored direction.",
+          "OpenSpec turns the agreed direction into only the minimal profile's specs and tasks; proposal and design artifacts are intentionally omitted.",
           "mate-minimal",
         ),
         reviewStep(

package/src/cli/commands/update.ts

@@ -1,4 +1,3 @@
-import path from "node:path";
 import { spawnSync } from "node:child_process";
 
 import { FRAMEWORK_NAME } from "../../framework";
@@ -14,6 +13,7 @@ import {
   isNewer,
 } from "../../lib/update-checker";
 import { confirmPrompt } from "../../lib/components/confirm-prompt";
+import { resolvePackageRoot } from "../../lib/package-root";
 
 type InstallResult = ReturnType<typeof installPublicPackageSync>;
 
@@ -38,11 +38,11 @@ export const updateCommandDeps = {
   getCurrentVersion,
   isNewer,
   confirmPrompt,
-  isNpmManagedInstall: () =>
-    isPackageInstalledAtNpmGlobalRoot(
-      path.resolve(import.meta.dirname, "../../.."),
-      getUpdateConfig().packageName,
-    ),
+  isNpmManagedInstall: () => {
+    const packageName = getUpdateConfig().packageName;
+    const packageRoot = resolvePackageRoot(process.argv[1], packageName);
+    return packageRoot !== undefined && isPackageInstalledAtNpmGlobalRoot(packageRoot, packageName);
+  },
   installLatest: (latest: string): InstallResult => {
     const { packageName, registry } = getUpdateConfig();
     return installPublicPackageSync(`${packageName}@${latest}`, registry);

package/src/cli/main.ts

@@ -22,6 +22,7 @@ import { runUnwrapCommand } from "./commands/unwrap";
 import { parseWrapArgs, runWrapCommand } from "./commands/wrap";
 import { runWorkingCommand } from "./commands/working/working";
 import { runInstallCommand } from "./commands/install";
+import { parseDirectLaunchArgs } from "./commands/launch/shared";
 import {
   inspectInstallPreflight,
   isRepairableInstallPreflight,
@@ -191,6 +192,14 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
         case "link":
           if (!(await gate({ notHubRoot: true }))) return;
           break;
+        // Registration names its target explicitly, so it needs no companion
+        // context and no root classification of the current directory.
+        case "register":
+        // Preparation names its bundle and its target explicitly, and runs
+        // before a companion is usable at all.
+        case "prepare":
+          if (!(await gate({ updateGuard: true }))) return;
+          break;
         // Hub commands establish and operate on a local hub root directly;
         // they must not require a linked working repository or installation —
         // but companions are never hubs.
@@ -215,21 +224,64 @@ export async function main(argv = process.argv, deps: MainDeps = mainDeps): Prom
       await runHubCommand(subcommand ? [subcommand, ...rest] : []);
       return;
     case "claude":
-      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
+      if (
+        !(await gate({
+          updateGuard: true,
+          companion:
+            parseDirectLaunchArgs(argv.slice(3)).scope === "companion"
+              ? { persistSelection: false }
+              : true,
+          install: true,
+        }))
+      )
+        return;
       await runLaunchClaudeCommand(argv.slice(3), { directPassthrough: true });
       return;
     case "opencode":
-      if (!(await gate({ updateGuard: true, companion: true, install: true }))) return;
+      if (
+        !(await gate({
+          updateGuard: true,
+          companion:
+            parseDirectLaunchArgs(argv.slice(3)).scope === "companion"
+              ? { persistSelection: false }
+              : true,
+          install: true,
+        }))
+      )
+        return;
       await runLaunchOpenCodeCommand(argv.slice(3), { directPassthrough: true });
       return;
+    case "launch": {
+      const launchArgs = argv.slice(4);
+      const companion = parseDirectLaunchArgs(launchArgs).scope === "companion";
+      if (subcommand !== "claude" && subcommand !== "opencode") {
+        console.error(`${FRAMEWORK_NAME}: expected launch claude or launch opencode.`);
+        process.exitCode = 1;
+        return;
+      }
+
+      const launchCommand =
+        subcommand === "claude" ? runLaunchClaudeCommand : runLaunchOpenCodeCommand;
+      if (
+        !(await gate({
+          updateGuard: true,
+          companion: companion ? { persistSelection: false } : true,
+          install: true,
+        }))
+      )
+        return;
+
+      await launchCommand(launchArgs, { directPassthrough: true });
+      return;
+    }
     case "report":
       if (!(await gate({ updateGuard: true, install: true }))) return;
       await runReportCommand(argv.slice(3));
       return;
     case "studio":
       /**
-       * Serves the machine-wide inventory read-only, so it resolves no
-       * companion context and stays runnable from any directory.
+       * Serves the machine-wide inventory without companion context, so it
+       * stays runnable from any directory. Writes remain opt-in.
        */
       if (!(await gate({ updateGuard: true }))) return;
       await runStudioCommand(argv.slice(3));

package/src/cli/usage.ts

@@ -13,6 +13,8 @@ export function usage(): string {
     ` ${n} install [--yes]`,
     ` ${n} companion link`,
     ` ${n} companion setup`,
+    ` ${n} companion register [path]`,
+    ` ${n} companion prepare --from <bundle> [path]`,
     ` ${n} companion list`,
     ` ${n} companion sync`,
     ` ${n} companion open`,
@@ -28,10 +30,11 @@ export function usage(): string {
     ` ${n} artifact pending [--json]`,
     ` ${n} doctor`,
     ` ${n} report [--days N] [--input FILE|-] [--json]`,
-    ` ${n} studio`,
+    ` ${n} studio [--writable]`,
+    ` ${n} studio serve --port <port> [--host <host>] [--writable]`,
     ` ${n} config`,
-    ` ${n} claude [args...] (use -- --no-git to bypass companion Git sync)`,
-    ` ${n} opencode [args...] (use -- --no-git to bypass companion Git sync)`,
+    ` ${n} claude [args...] (after --: --no-git, --companion, --yes no-op)`,
+    ` ${n} opencode [args...] (after --: --no-git, --companion, --yes no-op)`,
     ` ${n} cap openspec <subcommand> [args...]`,
     ` ${n} cap graphify <subcommand> [args...]`,
     ` ${n} cap index [--graphify] [--tokensave]`,

package/src/index.ts

@@ -54,4 +54,5 @@ export type {
   HubMemberSource,
   PluginDeclaration,
   PluginDeclarationPolicy,
+  LaunchScope,
 } from "./lib/orchestrator/types";

package/src/lib/context-mode-package.ts

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 
+import { isPreinstalledPluginPath } from "./preinstalled-plugins";
 import { PUBLIC_NPM_REGISTRY } from "./public-npm";
 
 export const CONTEXT_MODE_PACKAGE_NAME = "context-mode";
@@ -12,11 +13,13 @@ export function getContextModePackageReference(): string {
   return `${CONTEXT_MODE_PACKAGE_NAME}@${CONTEXT_MODE_VERSION}`;
 }
 
+/** Matches the published reference and a reference bound to an installed copy alike. */
 export function isContextModePackageReference(value: unknown): value is string {
-  return (
-    typeof value === "string" &&
-    (value === CONTEXT_MODE_PACKAGE_NAME || value.startsWith(`${CONTEXT_MODE_PACKAGE_NAME}@`))
-  );
+  if (typeof value !== "string") return false;
+  if (value === CONTEXT_MODE_PACKAGE_NAME || value.startsWith(`${CONTEXT_MODE_PACKAGE_NAME}@`)) {
+    return true;
+  }
+  return isPreinstalledPluginPath(value, CONTEXT_MODE_PACKAGE_NAME);
 }
 
 export function getContextModeInstallDir(companionPath: string): string {

package/src/lib/node-engine-version.ts

@@ -0,0 +1,15 @@
+/**
+ * The Node.js version an `engines.node` range may be enforced against, or null
+ * where there is none to enforce.
+ *
+ * Under Bun, `process.versions.node` is a compatibility claim rather than an
+ * installed Node release: it trails upstream on Bun's own schedule, and Bun
+ * ignores `engines` when loading a package anyway. Comparing a real range such
+ * as `^24.15.0` against that claim refuses graphs the runtime loads perfectly
+ * well, so there is nothing meaningful to compare and the check is skipped.
+ */
+export function enforceableNodeVersion(
+  versions: NodeJS.ProcessVersions = process.versions,
+): string | null {
+  return versions.bun === undefined ? versions.node : null;
+}

package/src/lib/opencode-plugin-package.ts

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
+import { isPreinstalledPluginPath } from "./preinstalled-plugins";
 import { PUBLIC_NPM_REGISTRY } from "./public-npm";
 import { getCurrentVersion } from "./update-checker";
 
@@ -18,11 +19,16 @@ export function getOpenCodePluginPackageReference(version: string = getCurrentVe
   return `${OPENCODE_PLUGIN_PACKAGE_NAME}@${version}`;
 }
 
+/** Matches the published reference and a reference bound to an installed copy alike. */
 export function isMateOpenCodePluginReference(value: unknown): boolean {
-  return (
-    typeof value === "string" &&
-    (value === OPENCODE_PLUGIN_PACKAGE_NAME || value.startsWith(`${OPENCODE_PLUGIN_PACKAGE_NAME}@`))
-  );
+  if (typeof value !== "string") return false;
+  if (
+    value === OPENCODE_PLUGIN_PACKAGE_NAME ||
+    value.startsWith(`${OPENCODE_PLUGIN_PACKAGE_NAME}@`)
+  ) {
+    return true;
+  }
+  return isPreinstalledPluginPath(value, OPENCODE_PLUGIN_PACKAGE_NAME);
 }
 
 export function getOpenCodeCacheDir(env: NodeJS.ProcessEnv = process.env): string {