@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.3

package/src/agent/loop.ts

@@ -10,27 +10,22 @@ import {
   estimateToolsTokens,
   getCalibrationProviderKey,
 } from "../context/token-estimator.js";
-import type { ContextWindowResult } from "../context/window-manager.js";
 import type { InboundActorContext } from "../daemon/conversation-runtime-assembly.js";
 import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { stripHistoricalWebSearchResults } from "../daemon/web-search-history.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import type {
-  AssistantMessageContext,
+  PostModelCallContext,
   PostToolUseContext,
   PreModelCallContext,
   StopContext,
 } from "../plugin-api/types.js";
-import {
-  DEFAULT_COMPACTION_PLUGIN_NAME,
-  defaultCompact,
-} from "../plugins/defaults/compaction/compact.js";
-import { getContextWindowManager } from "../plugins/defaults/compaction/manager-store.js";
+import { defaultCompact } from "../plugins/defaults/compaction/compact.js";
+import type { ContextWindowResult } from "../plugins/defaults/compaction/window-manager.js";
 import postCompact from "../plugins/defaults/memory-retrieval/hooks/post-compact.js";
 import { runHook } from "../plugins/pipeline.js";
 import type { CompactionCircuitEvent } from "../plugins/types.js";
-import { PluginExecutionError } from "../plugins/types.js";
 import { normalizeThinkingConfigForWire } from "../providers/thinking-config.js";
 import type {
   ContentBlock,
@@ -730,17 +725,8 @@ export class AgentLoop {
     // Record the history-stripped marker right after stripping, before the
     // pipeline runs.
     await onEvent({ type: "history_stripped" });
-    // The compaction module owns the per-conversation manager; resolve it from
-    // the store rather than holding a handle on the loop. Absent for callers
-    // without a compaction path (agent wakes, standalone unit tests), which
-    // never reach this gate.
-    const manager = getContextWindowManager(this.conversationId);
-    if (manager == null) {
-      throw new PluginExecutionError(
-        `default-compaction: no ContextWindowManager registered for conversation ${this.conversationId} — the compaction store must construct one before compaction runs`,
-        DEFAULT_COMPACTION_PLUGIN_NAME,
-      );
-    }
+    // The compaction module owns the per-conversation manager; pass the
+    // conversation id and let `defaultCompact` resolve it from the store.
     // The mid-loop budget gate is reached only when this turn decides to
     // compact in place, so `force` past the auto-threshold check.
     // `actorTrustClass` comes from the turn's trust snapshot (the actor whose
@@ -748,7 +734,7 @@ export class AgentLoop {
     // guardian-only attachments for untrusted actors. `overrideProfile` is the
     // turn's resolved inference-profile override for the summary call.
     const compactResult = await defaultCompact({
-      manager,
+      conversationId: this.conversationId,
       messages: rawHistory,
       signal,
       force: true,
@@ -1114,7 +1100,7 @@ export class AgentLoop {
 
         // A `pre-model-call` hook (below) can defer this turn's assistant
         // output; when set, the live text stream is held so an
-        // `assistant-message` hook can emit the finalized (transformed) text
+        // `post-model-call` hook can emit the finalized (transformed) text
         // instead. Reset per model call.
         let deferAssistantOutput = false;
 
@@ -1128,7 +1114,7 @@ export class AgentLoop {
           onEvent: (event) => {
             if (event.type === "text_delta") {
               // Held when the turn's output is deferred — the final text is
-              // emitted once, after the `assistant-message` hook runs.
+              // emitted once, after the `post-model-call` hook runs.
               if (deferAssistantOutput) return;
               // Apply sensitive-output placeholder substitution (chunk-safe)
               if (substitutionMap.size > 0) {
@@ -1298,7 +1284,7 @@ export class AgentLoop {
           streamingPending = "";
         }
 
-        // Run the `assistant-message` hook on a finalized message and, when
+        // Run the `post-model-call` hook on a finalized message and, when
         // output was deferred, emit the finalized text once (with sensitive-output
         // substitution applied, matching the live stream). Fail-open: the hook
         // receives a clone, so a throw — even mid in-place mutation — leaves the
@@ -1308,19 +1294,19 @@ export class AgentLoop {
         ): Promise<Message> => {
           let finalized = message;
           try {
-            const ctx: AssistantMessageContext = {
+            const ctx: PostModelCallContext = {
               conversationId: this.conversationId,
               callSite,
               content: structuredClone(message.content),
               stopReason: response.stopReason,
               logger: rlog,
             };
-            const result = await runHook(HOOKS.ASSISTANT_MESSAGE, ctx);
+            const result = await runHook(HOOKS.POST_MODEL_CALL, ctx);
             finalized = { role: "assistant", content: result.content };
           } catch (assistantMessageError) {
             rlog.error(
               { err: assistantMessageError },
-              "assistant-message hook failed — keeping the original content",
+              "post-model-call hook failed — keeping the original content",
             );
             finalized = message;
           }
@@ -1460,7 +1446,7 @@ export class AgentLoop {
           }
         }
 
-        // Run the `assistant-message` hook + emit any deferred final text.
+        // Run the `post-model-call` hook + emit any deferred final text.
         // On a no-tool turn this point is reached only after the `stop` hook
         // resolves to "stop" (a `continue` already re-queried above), so a
         // re-queried reply is never transformed-then-discarded.

package/src/cli/lib/__tests__/install-from-github.test.ts

@@ -31,7 +31,9 @@ import {
   InvalidPluginNameError,
   PluginAlreadyInstalledError,
   PluginNotFoundError,
+  PluginPostinstallError,
   PluginSourceUnavailableError,
+  type PostinstallRunner,
   sanitizePluginName,
 } from "../install-from-github.js";
 
@@ -54,6 +56,13 @@ const DOWNLOAD_HOST = "https://files.test/";
 function makeContentsFetch(opts: {
   tree: Record<string, Uint8Array | string | null>;
   manifest?: unknown;
+  /**
+   * HTTP status to answer the manifest fetch with. Defaults to 200 (when
+   * `manifest` is provided) or 404 (when omitted). Set to a transient status
+   * (e.g. 500) to simulate a marketplace lookup that fails rather than being
+   * absent — exercising the degrade-to-first-party path.
+   */
+  manifestStatus?: number;
 }): FetchLike {
   const MANIFEST_URL = `https://api.github.com/repos/${CANON_REPO}/contents/experimental/plugins/marketplace.json`;
   const CONTENTS = `https://api.github.com/repos/${CANON_REPO}/contents/`;
@@ -90,6 +99,11 @@ function makeContentsFetch(opts: {
     const url = typeof input === "string" ? input : input.toString();
 
     if (url.startsWith(MANIFEST_URL)) {
+      if (opts.manifestStatus !== undefined && opts.manifestStatus !== 200) {
+        return new Response("manifest unavailable", {
+          status: opts.manifestStatus,
+        });
+      }
       if (opts.manifest === undefined) {
         return new Response("not found", { status: 404 });
       }
@@ -182,6 +196,33 @@ const unusedGitRunner: GitRunner = async (args) => {
   );
 };
 
+/**
+ * Read the real, committed caveman adapter stub from the repo so the
+ * integration test exercises the adapter that ships rather than a fixture
+ * copy that could drift from it. Returns every stub file keyed by its
+ * Contents-API path (`experimental/plugins/caveman/<rel>`) so the fetch fake
+ * serves the whole stub — package.json, the adapter, and its templates — to
+ * the real postinstall runner. Resolves the stub relative to this test file.
+ */
+function readRealCavemanStub(): Record<string, string> {
+  const repoRel = "experimental/plugins/caveman";
+  const stubDir = join(import.meta.dir, "../../../../../", repoRel);
+  const tree: Record<string, string> = {};
+  const walk = (relDir: string): void => {
+    const absDir = relDir ? join(stubDir, relDir) : stubDir;
+    for (const entry of readdirSync(absDir, { withFileTypes: true })) {
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(rel);
+        continue;
+      }
+      tree[`${repoRel}/${rel}`] = readFileSync(join(stubDir, rel), "utf-8");
+    }
+  };
+  walk("");
+  return tree;
+}
+
 describe("installPlugin — first-party", () => {
   let ws: string;
   let pluginsDir: string;
@@ -495,7 +536,7 @@ describe("installPlugin — marketplace resolution", () => {
         source: {
           source: "github",
           repo: "JuliusBrussee/caveman",
-          ref: "v1.8.2",
+          ref: "63a91ecadbf4c4719a4602a5abb00883f9966034",
         },
         description: "Ultra-compressed communication mode.",
       },
@@ -503,7 +544,7 @@ describe("installPlugin — marketplace resolution", () => {
   };
 
   test("installs a whitelisted plugin by shallow-cloning its pinned repo + ref", async () => {
-    // GIVEN a marketplace whitelisting caveman at its repo root, pinned to a tag
+    // GIVEN a marketplace whitelisting caveman at its repo root, pinned to a commit SHA
     const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
     const calls: string[][] = [];
     const runGit = fakeGitRunner({
@@ -513,7 +554,7 @@ describe("installPlugin — marketplace resolution", () => {
         ".claude-plugin": null,
         ".claude-plugin/plugin.json": "{}",
       },
-      commit: "1111111222222233333334444444555555666666",
+      commit: "63a91ecadbf4c4719a4602a5abb00883f9966034",
       calls,
     });
 
@@ -528,8 +569,8 @@ describe("installPlugin — marketplace resolution", () => {
     // result reports the pinned ref and resolved commit, and `.git` is dropped
     const target = join(pluginsDir, "caveman");
     expect(result.target).toBe(target);
-    expect(result.ref).toBe("v1.8.2");
-    expect(result.commit).toBe("1111111222222233333334444444555555666666");
+    expect(result.ref).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+    expect(result.commit).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
     expect(result.fileCount).toBe(3);
     expect(readFileSync(join(target, "package.json"), "utf-8")).toBe(
       '{"name":"caveman"}',
@@ -541,7 +582,7 @@ describe("installPlugin — marketplace resolution", () => {
 
     // AND the clone fetched the pinned ref from the pinned repo URL.
     const fetchCall = calls.find((c) => c[0] === "fetch");
-    expect(fetchCall).toContain("v1.8.2");
+    expect(fetchCall).toContain("63a91ecadbf4c4719a4602a5abb00883f9966034");
     const remoteCall = calls.find((c) => c[0] === "remote");
     expect(remoteCall?.at(-1)).toBe(
       "https://github.com/JuliusBrussee/caveman.git",
@@ -553,8 +594,31 @@ describe("installPlugin — marketplace resolution", () => {
     );
     expect(manifest.source.kind).toBe("external");
     expect(manifest.source.owner).toBe("JuliusBrussee");
-    expect(manifest.source.ref).toBe("v1.8.2");
-    expect(manifest.commit).toBe("1111111222222233333334444444555555666666");
+    expect(manifest.source.ref).toBe(
+      "63a91ecadbf4c4719a4602a5abb00883f9966034",
+    );
+    expect(manifest.commit).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+  });
+
+  test("refuses to install when the checked-out commit differs from the pinned SHA", async () => {
+    // GIVEN a clone whose resolved HEAD does not match the manifest's pinned
+    // commit SHA — i.e. the upstream object served something unexpected
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({
+      tree: { "package.json": '{"name":"caveman"}' },
+      commit: "deadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+    });
+
+    // WHEN we install
+    // THEN the integrity check fails closed rather than materializing and
+    // later `import()`-ing code from an unexpected revision, and nothing lands
+    await expect(
+      installPlugin(
+        { name: "caveman", ref: "main" },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginSourceUnavailableError);
+    expect(readdirSync(pluginsDir)).toEqual([]);
   });
 
   test("a missing remote ref surfaces a clean not-found", async () => {
@@ -563,7 +627,8 @@ describe("installPlugin — marketplace resolution", () => {
     const runGit = fakeGitRunner({
       tree: {},
       fetchError: Object.assign(new Error("git fetch failed"), {
-        stderr: "fatal: couldn't find remote ref v1.8.2",
+        stderr:
+          "fatal: couldn't find remote ref 63a91ecadbf4c4719a4602a5abb00883f9966034",
       }),
     });
 
@@ -618,39 +683,177 @@ describe("installPlugin — marketplace resolution", () => {
     });
   });
 
-  test("first-party plugin wins a name collision with the marketplace", async () => {
-    // GIVEN a manifest whitelisting "caveman" externally
-    // AND an in-repo first-party plugin that also claims the name "caveman"
+  test("overlays a curated adapter stub and runs its postinstall transform", async () => {
+    // GIVEN caveman is whitelisted externally
+    // AND we curate an adapter stub for it at experimental/plugins/caveman —
+    // the real, committed stub (package.json + postinstall.ts + templates), so
+    // this test exercises the adapter that ships, not a fixture copy of it
     const fetch = makeContentsFetch({
+      tree: readRealCavemanStub(),
+      manifest: CAVEMAN_MANIFEST,
+    });
+    // AND the upstream clone is a Claude Code plugin: a name-mismatched
+    // package.json, the `.claude-plugin/plugin.json` manifest, and the
+    // terse-mode ruleset in skills/caveman/SKILL.md
+    const runGit = fakeGitRunner({
       tree: {
-        "experimental/plugins/caveman/package.json":
-          '{"name":"@vellumai/caveman"}',
-        "experimental/plugins/caveman/hooks": null,
-        "experimental/plugins/caveman/hooks/init.ts": "// first-party",
+        "package.json": '{"name":"caveman-installer"}',
+        ".claude-plugin/plugin.json": JSON.stringify({
+          name: "caveman",
+          description: "Ultra-compressed communication mode.",
+        }),
+        "skills/caveman/SKILL.md":
+          "---\nname: caveman\ndescription: terse mode\n---\n\nCAVEMAN MODE. Drop filler words. Keep technical substance.",
       },
-      manifest: CAVEMAN_MANIFEST,
+      commit: "63a91ecadbf4c4719a4602a5abb00883f9966034",
     });
 
-    // WHEN we install by the colliding name (git must NOT run — the in-repo
-    // plugin is served entirely from the Contents API)
+    // WHEN we install (real postinstall runner — no injected stub)
     const result = await installPlugin(
       { name: "caveman", ref: "main" },
-      { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
     );
 
-    // THEN the in-repo plugin is installed (matching what the search catalog
-    // advertises for the name), not the external repo — the marketplace is
-    // additive and never overrides a first-party plugin
+    // THEN the materialized tree is a valid Vellum plugin: package.json `name`
+    // matches the directory and declares the @vellumai/plugin-api peer dep
+    // (fixing both loader warnings), and the upstream installer name is gone
     const target = join(pluginsDir, "caveman");
-    expect(result.ref).toBe("main");
-    expect(result.commit).toBeNull();
-    expect(readFileSync(join(target, "package.json"), "utf-8")).toBe(
-      '{"name":"@vellumai/caveman"}',
+    expect(result.commit).toBe("63a91ecadbf4c4719a4602a5abb00883f9966034");
+    const pkg = JSON.parse(readFileSync(join(target, "package.json"), "utf-8"));
+    expect(pkg.name).toBe("caveman");
+    expect(pkg.peerDependencies["@vellumai/plugin-api"]).toBeString();
+    expect(pkg.scripts?.postinstall).toBeUndefined();
+
+    // AND a pre-model-call hook is synthesized carrying the upstream ruleset,
+    // so caveman actually runs (terse mode injected on the user-facing call)
+    const hook = readFileSync(
+      join(target, "hooks", "pre-model-call.ts"),
+      "utf-8",
+    );
+    expect(hook).toContain("PreModelCallContext");
+    expect(hook).toContain('ctx.callSite !== "mainAgent"');
+    expect(hook).toContain("CAVEMAN MODE. Drop filler words.");
+    // AND the ruleset is sourced verbatim — the YAML frontmatter is stripped
+    expect(hook).not.toContain("description: terse mode");
+  });
+
+  test("does not run a postinstall for a raw clone without an adapter stub", async () => {
+    // GIVEN caveman is whitelisted but we curate NO adapter stub for it
+    // (the Contents API has no experimental/plugins/caveman directory)
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({
+      tree: { "package.json": '{"name":"caveman"}', "hooks/init.ts": "//" },
+      commit: "63a91ecadbf4c4719a4602a5abb00883f9966034",
+    });
+    // AND a postinstall runner that fails the test if it is ever invoked
+    const runPostinstall: PostinstallRunner = async () => {
+      throw new Error("postinstall must not run for a stubless raw clone");
+    };
+
+    // WHEN we install
+    await installPlugin(
+      { name: "caveman", ref: "main" },
+      { fetch, runGit, runPostinstall, workspacePluginsDir: pluginsDir },
     );
-    expect(readFileSync(join(target, "hooks", "init.ts"), "utf-8")).toBe(
-      "// first-party",
+
+    // THEN the clone is installed verbatim — no transform ran
+    const target = join(pluginsDir, "caveman");
+    expect(readFileSync(join(target, "package.json"), "utf-8")).toBe(
+      '{"name":"caveman"}',
     );
   });
+
+  test("aborts and rolls back when the adapter's postinstall fails", async () => {
+    // GIVEN a whitelisted plugin with a curated stub declaring a postinstall
+    const fetch = makeContentsFetch({
+      tree: {
+        "experimental/plugins/caveman/package.json": JSON.stringify({
+          name: "caveman",
+          scripts: { postinstall: "bun ./postinstall.ts" },
+        }),
+        "experimental/plugins/caveman/postinstall.ts": "// adapter",
+      },
+      manifest: CAVEMAN_MANIFEST,
+    });
+    const runGit = fakeGitRunner({
+      tree: { "package.json": '{"name":"caveman-installer"}' },
+      commit: "63a91ecadbf4c4719a4602a5abb00883f9966034",
+    });
+    // AND its adapter exits non-zero
+    const runPostinstall: PostinstallRunner = async () => {
+      throw new Error("adapter blew up");
+    };
+
+    // WHEN we install
+    // THEN it surfaces a PluginPostinstallError and nothing is materialized —
+    // better to fail loudly than ship a half-transformed plugin
+    await expect(
+      installPlugin(
+        { name: "caveman", ref: "main" },
+        { fetch, runGit, runPostinstall, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginPostinstallError);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("rejects a stub whose postinstall is not a single bun invocation", async () => {
+    // GIVEN a curated stub whose postinstall is an arbitrary shell command
+    // rather than the supported `bun <script>` adapter convention
+    const fetch = makeContentsFetch({
+      tree: {
+        "experimental/plugins/caveman/package.json": JSON.stringify({
+          name: "caveman",
+          scripts: { postinstall: "rm -rf /" },
+        }),
+      },
+      manifest: CAVEMAN_MANIFEST,
+    });
+    const runGit = fakeGitRunner({
+      tree: { "package.json": '{"name":"caveman-installer"}' },
+      commit: "63a91ecadbf4c4719a4602a5abb00883f9966034",
+    });
+
+    // WHEN we install (the default runner is never reached — resolution rejects
+    // the command before anything executes)
+    // THEN it surfaces a PluginPostinstallError and nothing is materialized
+    await expect(
+      installPlugin(
+        { name: "caveman", ref: "main" },
+        { fetch, runGit, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginPostinstallError);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
+
+  test("refuses to install an adapter stub as first-party when the marketplace lookup fails", async () => {
+    // GIVEN the marketplace lookup fails transiently (e.g. rate-limit / 5xx)
+    // rather than being absent, so resolution degrades to the first-party path
+    // AND the same-named in-repo directory is an adapter stub (a package.json
+    // with a postinstall + adapter script, but no hooks/tools of its own)
+    const fetch = makeContentsFetch({
+      tree: {
+        "experimental/plugins/caveman/package.json": JSON.stringify({
+          name: "caveman",
+          scripts: { postinstall: "bun ./postinstall.ts" },
+        }),
+        "experimental/plugins/caveman/postinstall.ts": "// adapter",
+      },
+      manifestStatus: 500,
+    });
+
+    // WHEN we install the name (git never runs — there is no external source to
+    // clone because the marketplace that would have named it was unreadable)
+    // THEN it fails loudly with a PluginPostinstallError instead of
+    // materializing the bare stub as a non-functional standalone plugin, and
+    // nothing is left behind on disk
+    await expect(
+      installPlugin(
+        { name: "caveman", ref: "main" },
+        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
+      ),
+    ).rejects.toBeInstanceOf(PluginPostinstallError);
+    expect(readdirSync(pluginsDir)).toEqual([]);
+  });
 });
 
 describe("sanitizePluginName", () => {

package/src/cli/lib/__tests__/plugin-details.test.ts

@@ -116,7 +116,7 @@ describe("getPluginDetails", () => {
             source: {
               source: "github",
               repo: "example-org/caveman",
-              ref: "v1",
+              ref: "1111111111111111111111111111111111111111",
             },
             description: "manifest description",
             homepage: "https://example.com/caveman",
@@ -152,7 +152,7 @@ describe("getPluginDetails", () => {
     expect(details.source).toEqual({
       kind: "github",
       repo: "example-org/caveman",
-      ref: "v1",
+      ref: "1111111111111111111111111111111111111111",
     });
     expect(details.installed).toBe(false);
     expect(details.readme).toContain("Grug brain plugin");
@@ -176,7 +176,7 @@ describe("getPluginDetails", () => {
           source: {
             source: "github",
             repo: "example-org/caveman",
-            ref: "v1.8.2",
+            ref: "2222222222222222222222222222222222222222",
           },
         },
       ],
@@ -215,16 +215,20 @@ describe("getPluginDetails", () => {
     );
 
     // THEN the external repo is read at the plugin's pinned ref, not `main`
-    expect(contentsRefs.get("external")).toBe("v1.8.2");
-    // AND the first-party collision probe still uses the catalog ref
-    expect(contentsRefs.get("first-party")).toBe("main");
+    expect(contentsRefs.get("external")).toBe(
+      "2222222222222222222222222222222222222222",
+    );
+    // AND the marketplace entry owns the name, so the first-party directory is
+    // never probed (its same-named in-repo dir would be the adapter stub)
+    expect(contentsRefs.has("first-party")).toBe(false);
     // AND the README from the pinned ref is surfaced
     expect(details.readme).toContain("Caveman");
   });
 
-  test("first-party directory wins a name also claimed by the marketplace", async () => {
-    // GIVEN both a marketplace entry AND a first-party in-repo directory for
-    // the same name
+  test("a marketplace entry owns a name shared by an in-repo stub dir", async () => {
+    // GIVEN a marketplace entry for "simple-memory"
+    // AND a same-named in-repo directory — caveman-style, this is the plugin's
+    // adapter stub, not a standalone first-party plugin
     const fetch = makeFetch({
       marketplace: {
         name: "vellum",
@@ -234,17 +238,17 @@ describe("getPluginDetails", () => {
             source: {
               source: "github",
               repo: "example-org/simple-memory",
-              ref: "v9",
+              ref: "9999999999999999999999999999999999999999",
             },
           },
         ],
       },
       listings: {
-        "vellum-ai/vellum-assistant/experimental/plugins/simple-memory": [
-          fileEntry("README.md", "raw://fp/readme"),
+        "example-org/simple-memory": [
+          fileEntry("README.md", "raw://ext/readme"),
         ],
       },
-      raw: { "raw://fp/readme": "# Simple Memory (first-party)" },
+      raw: { "raw://ext/readme": "# Simple Memory (external)" },
     });
 
     // WHEN we resolve the detail view
@@ -253,9 +257,14 @@ describe("getPluginDetails", () => {
       { fetch, workspacePluginsDir: workspace },
     );
 
-    // THEN the first-party source is used, not the external one
-    expect(details.source).toEqual({ kind: "first-party" });
-    expect(details.readme).toContain("first-party");
+    // THEN the external marketplace source is used — the stub dir is an
+    // adapter overlay for the clone, so it does not override the claim
+    expect(details.source).toEqual({
+      kind: "github",
+      repo: "example-org/simple-memory",
+      ref: "9999999999999999999999999999999999999999",
+    });
+    expect(details.readme).toContain("external");
   });
 
   test("prefers an installed copy's README and package.json over the repo", async () => {
@@ -278,7 +287,7 @@ describe("getPluginDetails", () => {
             source: {
               source: "github",
               repo: "example-org/caveman",
-              ref: "v1",
+              ref: "1111111111111111111111111111111111111111",
             },
             description: "manifest description",
           },
@@ -330,7 +339,7 @@ describe("getPluginDetails", () => {
             source: {
               source: "github",
               repo: "example-org/caveman",
-              ref: "v1",
+              ref: "1111111111111111111111111111111111111111",
             },
             description: "manifest description",
             license: "MIT",
@@ -353,7 +362,7 @@ describe("getPluginDetails", () => {
     expect(details.source).toEqual({
       kind: "github",
       repo: "example-org/caveman",
-      ref: "v1",
+      ref: "1111111111111111111111111111111111111111",
     });
   });