@stigmer/cli 3.18.0-dev.20260918103812 → 3.18.0

package/src/local/bootstrap.ts

@@ -1,133 +1,223 @@
-// What `stigmer up` does once the local server answers: seed it. Two steps,
-// in this order, each best-effort with its own warning, because the stack is
-// already serving by the time either runs and a seeding failure must never
-// tear it down:
+// What makes a backend a ready Stigmer: the system org exists and the
+// official marketplace's default plugins are installed into it, public.
+// `stigmer up` runs this against the local server it just started;
+// `stigmer bootstrap` runs the same two phases against whatever backend the
+// CLI is pointed at, for a raw self-hosted server or the platform's daily
+// lane. One definition, so a laptop, a container and the hosted platform
+// cannot drift in what "ready" means.
 //
-//   1. the seedpack (the system org, the `stigmer` MCP server, the remaining
-//      system agents, skills and workflows), content-hash idempotent;
-//   2. the default plugins the official marketplace names, installed into the
-//      same org as public, idempotent by the server's own digest.
+// Two phases, and the order matters (a third, `up`'s retire, follows them):
 //
-// The seedpack goes first because the plugins install INTO the org it
-// creates and reference the server it holds. When the seedpack retires, this
-// file keeps step 2 and loses step 1, and nothing else moves.
+//   1. prepare: resolve the official marketplace (acquiring `@stigmer/plugins`
+//      at the CLI's version on a release's first run) and prepare every
+//      default. No backend is touched.
+//   2. run: ensure the system org, then push the prepared defaults, each
+//      skipped when the backend already holds it at the same digest.
 //
-// Both `up` shapes (detached and foreground) call this one function, so what
-// a detached `up` seeds and what a container's `up --foreground` seeds cannot
-// drift. Both always seed the local server `up` just started, never the
-// active backend context: a user whose CLI is pointed at cloud must still get
-// their local stack seeded, and must never have system resources applied to
-// their cloud org. The client is pinned to a fresh local config
+// `stigmer up` adds a third phase after them: retiring the seedpack an
+// older release installed. That step deletes rows, so it runs only once
+// every default has LANDED, not merely been prepared: the plugin push adopts
+// the system-content rows it replaces in place (the seedpack's `assistant`
+// keeps its id, its instances and every conversation bound to them), and a
+// row that is now a plugin's member is never a candidate for the retire. A
+// user who upgrades offline and cannot fetch the new catalogue, or whose
+// backend refused a default, keeps the old rows for another day instead of
+// losing them and getting nothing back. The retire lives here and not in
+// `stigmer bootstrap` on purpose: a verb a scheduled lane runs against the
+// platform must never be able to delete rows.
+//
+// Inside `up` every phase is best-effort with its own warning naming the
+// retry, because the stack is already serving by the time any of them runs
+// and a seeding failure must never tear it down. Both `up` shapes (detached
+// and foreground) call this one function, and both seed the local server
+// `up` just started, never the active backend context: a CLI pointed at
+// cloud still gets its local stack seeded, and never has system resources
+// applied to its cloud org. The client is pinned to a fresh local config
 // (localhost:SERVER_PORT) with no auth, the trusted-local identity.
 
+import type { Stigmer } from "@stigmer/sdk";
 import type { BackendClient } from "../client/index.js";
 import { log } from "../logger.js";
+import type { ResolveOfficialOptions } from "../marketplace/official.js";
+import type {
+  DefaultPluginsResult,
+  InstallingVerb,
+  PreparedDefault,
+} from "./plugins/defaults.js";
 import { dataDir } from "./paths.js";
+import { type EnsureSystemOrgOutcome, SYSTEM_ORG } from "./system-org.js";
 
-/** One seeding step: talks to the user through `say`, never throws past its own warning. */
-export type BootstrapStep = (
-  client: BackendClient,
-  home: string,
+export type Say = (line: string) => void;
+
+/** Everything phase 2 needs, gathered without a backend. */
+export interface PreparedBootstrap {
+  readonly defaults: readonly PreparedDefault[];
+}
+
+export interface BootstrapResult {
+  readonly org: EnsureSystemOrgOutcome;
+  readonly plugins: DefaultPluginsResult;
+}
+
+export interface PrepareBootstrapOptions {
+  /** How the official tree is found (injectable for tests). */
+  readonly official?: ResolveOfficialOptions;
+}
+
+/** Phase 1. Throws when the catalogue cannot be resolved or a default cannot be prepared. */
+export async function prepareBootstrap(
+  options: PrepareBootstrapOptions = {},
+): Promise<PreparedBootstrap> {
+  const { prepareDefaultPlugins } = await import("./plugins/defaults.js");
+  return { defaults: await prepareDefaultPlugins(options.official) };
+}
+
+/**
+ * Phase 2. Throws when the system org cannot be ensured; a default that
+ * fails to land is reported in the result, not thrown, so the caller can
+ * name each one. `verb` is the command running this, stamped into each
+ * installed plugin's version message.
+ */
+export async function runBootstrap(
+  stigmer: Stigmer,
+  prepared: PreparedBootstrap,
   say: Say,
-) => Promise<void>;
+  verb: InstallingVerb,
+): Promise<BootstrapResult> {
+  const [{ ensureSystemOrg }, { installPreparedDefaults }] = await Promise.all(
+    [import("./system-org.js"), import("./plugins/defaults.js")],
+  );
+  const org = await ensureSystemOrg(stigmer);
+  if (org === "created") say(`Created the '${SYSTEM_ORG}' organization`);
+  const plugins = await installPreparedDefaults(
+    { stigmer, info: say, verb },
+    prepared.defaults,
+    SYSTEM_ORG,
+  );
+  return { org, plugins };
+}
 
-export type Say = (line: string) => void;
+/** Both phases, against the backend `stigmer` is bound to: what `stigmer bootstrap` runs. */
+export async function bootstrapBackend(
+  stigmer: Stigmer,
+  say: Say,
+  options: PrepareBootstrapOptions = {},
+): Promise<BootstrapResult> {
+  return runBootstrap(
+    stigmer,
+    await prepareBootstrap(options),
+    say,
+    "stigmer bootstrap",
+  );
+}
 
-/** Seams of the bootstrap, injectable for tests; the defaults are the real steps over the real local client. */
+/** Seams of the local bootstrap, injectable for tests; the defaults are the real phases over the real local client. */
 export interface BootstrapDeps {
   readonly client?: BackendClient;
-  readonly seedpack?: BootstrapStep;
-  readonly plugins?: BootstrapStep;
   readonly say?: Say;
+  readonly prepare?: () => Promise<PreparedBootstrap>;
+  readonly retire?: (stigmer: Stigmer, home: string, say: Say) => Promise<void>;
+  readonly run?: (
+    stigmer: Stigmer,
+    prepared: PreparedBootstrap,
+    say: Say,
+  ) => Promise<BootstrapResult>;
 }
 
 const sayToStderr: Say = (line) => {
   process.stderr.write(`${line}\n`);
 };
 
+/** What `stigmer up` does once the local server answers. Never throws past its own warnings. */
 export async function bootstrapLocalBackend(
   home: string,
   deps: BootstrapDeps = {},
 ): Promise<void> {
   const client = deps.client ?? (await freshLocalClient());
   const say = deps.say ?? sayToStderr;
-  await (deps.seedpack ?? applySeedpackBestEffort)(client, home, say);
-  await (deps.plugins ?? installDefaultPluginsBestEffort)(client, home, say);
-}
 
-async function freshLocalClient(): Promise<BackendClient> {
-  const [{ createBackendClient }, { getDefault }] = await Promise.all([
-    import("../client/index.js"),
-    import("../config/config.js"),
-  ]);
-  return createBackendClient({
-    config: getDefault(),
-    getAccessToken: () => null,
-  });
-}
-
-/** Step 1. Idempotent via a content-hash marker, so repeated `up`s are cheap. */
-export async function applySeedpackBestEffort(
-  client: BackendClient,
-  home: string,
-  say: Say,
-): Promise<void> {
+  let prepared: PreparedBootstrap;
   try {
-    const { applySeedpack } = await import("./seedpack/apply.js");
-    const result = await applySeedpack(
-      {
-        controller: client.controller,
-        stigmer: client.stigmer,
-        info: say,
-        warn: say,
-      },
-      { markerDir: dataDir(home), home },
-    );
-    log.debug("seedpack bootstrap complete", {
-      applied: result.applied,
-      hash: result.hash,
-      org: result.org,
-    });
+    prepared = await (deps.prepare ?? prepareBootstrap)();
   } catch (err) {
-    log.warn("seedpack bootstrap failed", { error: String(err) });
+    log.warn("bootstrap preparation failed", { error: String(err) });
     say(
-      "Warning: failed to apply system resources (seedpack). Run 'stigmer seedpack apply' to retry.",
+      "Warning: could not prepare the default plugins, so the local backend was not bootstrapped and nothing was retired. Run 'stigmer up' again to retry.",
     );
+    return;
   }
-}
 
-/**
- * Step 2. Runs even when step 1 warned: the plugins can only fail on their
- * own terms (an org that does not exist fails the push, and the warning
- * names the command that retries it).
- */
-export async function installDefaultPluginsBestEffort(
-  client: BackendClient,
-  _home: string,
-  say: Say,
-): Promise<void> {
+  let result: BootstrapResult;
   try {
-    const [{ installDefaultPlugins }, { resolveSeedpackOrg }] =
-      await Promise.all([
-        import("./plugins/defaults.js"),
-        import("./seedpack/apply.js"),
-      ]);
-    const result = await installDefaultPlugins(
-      { stigmer: client.stigmer, info: say },
-      { org: resolveSeedpackOrg() },
+    result = await (deps.run ?? runLocalBootstrap)(
+      client.stigmer,
+      prepared,
+      say,
     );
-    log.debug("default plugins bootstrap complete", {
-      outcomes: result.outcomes,
-    });
-    for (const name of result.failed) {
+  } catch (err) {
+    log.warn("bootstrap failed", { error: String(err) });
+    say(
+      "Warning: failed to bootstrap the local backend, so nothing was retired. Run 'stigmer up' again to retry.",
+    );
+    return;
+  }
+  log.debug("bootstrap complete", {
+    org: result.org,
+    outcomes: result.plugins.outcomes,
+  });
+  if (result.plugins.failed.length > 0) {
+    for (const name of result.plugins.failed) {
       say(
-        `Warning: failed to install default plugin '${name}'. Run 'stigmer install ${name}' to retry.`,
+        `Warning: failed to install default plugin '${name}'. Run 'stigmer bootstrap' to retry.`,
       );
     }
+    say(
+      "Nothing was retired: the resources an older release installed stay until every default plugin is in place.",
+    );
+    return;
+  }
+
+  try {
+    await (deps.retire ?? retireSeedpack)(client.stigmer, home, say);
   } catch (err) {
-    log.warn("default plugins bootstrap failed", { error: String(err) });
+    log.warn("seedpack retire failed", { error: String(err) });
     say(
-      "Warning: failed to install the default plugins. Run 'stigmer marketplace show stigmer' to see them and 'stigmer install <name>' to retry.",
+      "Warning: failed to retire the resources an older release installed. Run 'stigmer up' again to retry.",
     );
   }
 }
+
+// Phase 2 in the seam's shape, naming the verb: everything this file's
+// local bootstrap installs was installed by `stigmer up`.
+function runLocalBootstrap(
+  stigmer: Stigmer,
+  prepared: PreparedBootstrap,
+  say: Say,
+): Promise<BootstrapResult> {
+  return runBootstrap(stigmer, prepared, say, "stigmer up");
+}
+
+// The retire step in the shape the seam expects; the module is loaded only
+// inside `up`, the one place a retire may run.
+async function retireSeedpack(
+  stigmer: Stigmer,
+  home: string,
+  say: Say,
+): Promise<void> {
+  const { retireSeedpack: retire, renderRetireReport } = await import(
+    "./seedpack-retire.js"
+  );
+  const result = await retire(stigmer, { markerDir: dataDir(home) });
+  renderRetireReport(result, say);
+}
+
+async function freshLocalClient(): Promise<BackendClient> {
+  const [{ createBackendClient }, { getDefault }] = await Promise.all([
+    import("../client/index.js"),
+    import("../config/config.js"),
+  ]);
+  return createBackendClient({
+    config: getDefault(),
+    getAccessToken: () => null,
+  });
+}

package/src/local/daemon/launch.ts

@@ -83,7 +83,7 @@ export interface UpForegroundDeps {
   runDaemon?: (deps: InternalDaemonDeps) => Promise<number>;
   /** Resolves when the stack should shut down (default: the first SIGTERM/SIGINT). */
   waitForShutdown?: () => Promise<void>;
-  /** Post-readiness bootstrap (default: `bootstrapLocalBackend`, the seedpack then the default plugins). */
+  /** Post-readiness bootstrap (default: `bootstrapLocalBackend`: prepare the defaults, retire an older release's seedpack, ensure the org, install). */
   bootstrap?: (home: string) => Promise<void>;
   /** Receives each line the server and runner write (default: a `[component]`-prefixed stdout mirror). */
   mirror?: OutputMirror;

package/src/local/paths.ts

@@ -48,7 +48,7 @@ export function binDir(home: string = homedir()): string {
 
 /**
  * Env var that relocates the acquired-runtimes root. The acquirers (server,
- * runner, seedpack) keep their `<root>/<version>/node_modules/@stigmer/<pkg>`
+ * runner, the official plugin catalogue) keep their `<root>/<version>/node_modules/@stigmer/<pkg>`
  * layout under it, so a root that already holds the packages is used as-is
  * and nothing is downloaded. The all-in-one image bakes exactly that layout
  * read-only off its data volume — a `stigmer up` whose first-run acquisitions

package/src/local/plugins/defaults.test.ts

@@ -1,8 +1,9 @@
-// Pins the default-set step over a real Connect backend: a default absent
-// from the org is pushed public with the CLI's message; one present at the
-// same digest, READY and public is skipped without a push; a changed digest,
-// a non-READY state or a non-public visibility pushes again; the defaults go
-// in the marketplace's order; one failure does not stop the next; and a
+// Pins the default-set step over a real Connect backend: preparation is
+// all-or-nothing and touches no backend; a default absent from the org is
+// pushed public with the CLI's message; one present at the same digest,
+// READY and public is skipped without a push; a changed digest, a non-READY
+// state or a non-public visibility pushes again; the defaults go in the
+// marketplace's order; one push failure does not stop the next; and a
 // second run over a converged backend pushes nothing.
 
 import { createHash } from "node:crypto";
@@ -35,7 +36,7 @@ import type { Stigmer } from "@stigmer/sdk";
 import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 import { writeCursorMarketplace } from "../../marketplace/__fixtures__/cursor-marketplace.js";
 import { preparePluginPush } from "../../resources/plugin.js";
-import { installDefaultPlugins } from "./defaults.js";
+import { installPreparedDefaults, prepareDefaultPlugins } from "./defaults.js";
 
 let backend: Http2Server;
 let stigmer: Stigmer;
@@ -145,15 +146,47 @@ function digestOf(bytes: Uint8Array): string {
 
 const say = (): void => {};
 
-function run() {
-  return installDefaultPlugins(
-    { stigmer, info: say },
-    { org: "stigmer", official: { repoDir: () => official } },
+async function run() {
+  const prepared = await prepareDefaultPlugins({ repoDir: () => official });
+  return installPreparedDefaults(
+    { stigmer, info: say, verb: "stigmer bootstrap" },
+    prepared,
+    "stigmer",
   );
 }
 
-describe("installDefaultPlugins", () => {
-  it("installs every default in order, public, with the CLI's message, on a fresh backend", async () => {
+describe("prepareDefaultPlugins", () => {
+  it("prepares every default in the marketplace's order without touching the backend", async () => {
+    const prepared = await prepareDefaultPlugins({ repoDir: () => official });
+    expect(prepared.map((entry) => [entry.name, entry.push.digest])).toEqual([
+      ["thermos", thermosDigest],
+      ["github", githubDigest],
+    ]);
+    expect(pushes).toHaveLength(0);
+  });
+
+  it("refuses the whole set when one default cannot be prepared", async () => {
+    const broken = mkdtempSync(join(tmpdir(), "stigmer-defaults-broken-"));
+    try {
+      writeFileSync(
+        join(broken, "marketplace.json"),
+        JSON.stringify({
+          name: "stigmer",
+          plugins: [{ name: "missing", source: "./missing" }],
+          defaults: ["missing"],
+        }),
+      );
+      await expect(
+        prepareDefaultPlugins({ repoDir: () => broken }),
+      ).rejects.toThrow(/1 plugin this CLI cannot install/);
+    } finally {
+      rmSync(broken, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("installPreparedDefaults", () => {
+  it("installs every default in order, public, with the invoking verb in the message, on a fresh backend", async () => {
     const result = await run();
     expect(result.outcomes.map((o) => [o.name, o.action])).toEqual([
       ["thermos", "installed"],
@@ -167,7 +200,7 @@ describe("installDefaultPlugins", () => {
       ),
     ).toBe(true);
     expect(pushes[0]?.message).toMatch(
-      /^default plugin, installed by stigmer up \(/,
+      /^default plugin, installed by stigmer bootstrap \(/,
     );
     expect(digestOf(pushes[0]!.artifact)).toBe(thermosDigest);
     expect(digestOf(pushes[1]!.artifact)).toBe(githubDigest);

package/src/local/plugins/defaults.ts

@@ -1,24 +1,31 @@
-// The default plugins a fresh local backend is bootstrapped with: the
-// `defaults` list of the official marketplace, installed in order into the
-// system org as public, so the global default-agent lookup and cross-org
-// references find them exactly where the seedpack used to put them.
+// The default plugins a backend is bootstrapped with: the `defaults` list of
+// the official marketplace, installed in order into the system org as
+// public, so the global default-agent lookup and cross-org references find
+// them.
 //
-// Idempotent by the server's own identity, not a marker file: before each
-// push the entry is prepared (walked, zipped, hashed) and the org's plugin
-// of that name is read back; when its digest equals the prepared archive's,
-// it is READY and it is public, there is nothing to do and nothing is sent.
-// A second `stigmer up` therefore pushes nothing, and a `stigmer up` after
-// an upgrade pushes exactly the entries whose content changed. The record is
-// the server, so any machine that reaches the same backend sees the same
-// answer (the seedpack's cloud-mode rule, made the only rule).
+// Two phases, deliberately separate. Preparing (resolve the official tree,
+// which may acquire `@stigmer/plugins` at the CLI's version; walk, zip and
+// hash every default) needs no backend and is all-or-nothing: the catalogue
+// is ours and validated on CI, so a default that cannot be prepared is a
+// release defect, not a condition to install around. Installing pushes the
+// prepared archives and is best-effort per entry: one default failing to
+// land does not stop the next, and the caller decides how to surface the
+// failures. The split lets `stigmer up` hold every replacement in hand
+// before it retires what the replacement supersedes (local/bootstrap.ts).
 //
-// Best-effort per entry: one default failing to install does not stop the
-// next, and the caller decides how to surface the failures (the daemon
-// launcher warns and names `stigmer install <name>`).
+// Idempotent by the server's own identity, not a marker file: before each
+// push the org's plugin of that name is read back; when its digest equals the
+// prepared archive's, it is READY and it is public, there is nothing to do
+// and nothing is sent. A second `stigmer up` therefore pushes nothing, and a
+// `stigmer up` after an upgrade pushes exactly the entries whose content
+// changed. The record is the server, so any machine that reaches the same
+// backend sees the same answer.
 
 import { type Stigmer, isNotFound } from "@stigmer/sdk";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { PluginState } from "@stigmer/protos/ai/stigmer/agentic/plugin/v1/status_pb";
+import { CliExitError } from "../../errors/cli-exit-error.js";
+import { ExitCode } from "../../errors/exit-codes.js";
 import { log } from "../../logger.js";
 import { VERSION } from "../../version.js";
 import {
@@ -29,21 +36,30 @@ import { readMarketplaceTree } from "../../marketplace/read.js";
 import { prepareEntry } from "../../marketplace/install.js";
 import {
   type PreparedPluginPush,
+  count,
   pushPrepared,
 } from "../../resources/plugin.js";
 
+/**
+ * The command that ran the install, as the plugin's stored version message
+ * names it. Two verbs share the one bootstrap function, and a platform
+ * operator reading the row a year later must see which one wrote it.
+ */
+export type InstallingVerb = "stigmer up" | "stigmer bootstrap";
+
 export interface DefaultPluginsDeps {
   /** The client bound to the backend being bootstrapped. */
   readonly stigmer: Stigmer;
   /** Human progress lines (stderr). */
   readonly info: (line: string) => void;
+  /** Stamped into each installed plugin's version message. */
+  readonly verb: InstallingVerb;
 }
 
-export interface DefaultPluginsOptions {
-  /** The org the defaults are installed into: the seedpack's org, until the seedpack is gone. */
-  readonly org: string;
-  /** How the official tree is found (injectable for tests). */
-  readonly official?: ResolveOfficialOptions;
+/** One default, ready to push: its marketplace name and the prepared archive. */
+export interface PreparedDefault {
+  readonly name: string;
+  readonly push: PreparedPluginPush;
 }
 
 export type DefaultPluginOutcome =
@@ -69,29 +85,56 @@ export interface DefaultPluginsResult {
   readonly failed: readonly string[];
 }
 
-/** Install every default the official marketplace names, in order, skipping what the backend already holds. */
-export async function installDefaultPlugins(
+/**
+ * Phase 1: every default the official marketplace names, prepared in the
+ * marketplace's order. Throws when the tree cannot be resolved, offers less
+ * than it lists (the library drops an entry it cannot install with a
+ * warning, which for a user's marketplace is `show`'s business and for ours
+ * is a broken release), or any default cannot be prepared; nothing is
+ * returned half-ready.
+ */
+export async function prepareDefaultPlugins(
+  official?: ResolveOfficialOptions,
+): Promise<readonly PreparedDefault[]> {
+  const resolved = resolveOfficialMarketplace(official);
+  const tree = readMarketplaceTree(resolved.dir, "the official marketplace");
+  if (tree.warnings.length > 0) {
+    throw new CliExitError(
+      `the official marketplace at ${resolved.dir} lists ${count(tree.warnings.length, "plugin")} this CLI cannot install`,
+      ExitCode.General,
+      tree.warnings.map((finding) => finding.message),
+    );
+  }
+  const prepared: PreparedDefault[] = [];
+  for (const name of tree.marketplace.defaults) {
+    prepared.push({ name, push: await prepareEntry(tree, name) });
+  }
+  return prepared;
+}
+
+/**
+ * Phase 2: install the prepared defaults into `org`, skipping what the
+ * backend already holds. Best-effort per entry.
+ */
+export async function installPreparedDefaults(
   deps: DefaultPluginsDeps,
-  options: DefaultPluginsOptions,
+  prepared: readonly PreparedDefault[],
+  org: string,
 ): Promise<DefaultPluginsResult> {
-  const official = resolveOfficialMarketplace(options.official);
-  const tree = readMarketplaceTree(official.dir, "the official marketplace");
-
   const outcomes: DefaultPluginOutcome[] = [];
-  for (const name of tree.marketplace.defaults) {
+  for (const { name, push } of prepared) {
     try {
-      const prepared = await prepareEntry(tree, name);
-      if (await isAlreadyInstalled(deps.stigmer, options.org, prepared)) {
-        outcomes.push({ name, action: "up-to-date", digest: prepared.digest });
+      if (await isAlreadyInstalled(deps.stigmer, org, push)) {
+        outcomes.push({ name, action: "up-to-date", digest: push.digest });
         continue;
       }
       deps.info(`Installing default plugin '${name}'…`);
-      await pushPrepared(deps.stigmer, prepared, {
-        org: options.org,
+      await pushPrepared(deps.stigmer, push, {
+        org,
         visibility: ApiResourceVisibility.visibility_public,
-        message: `default plugin, installed by stigmer up (${VERSION})`,
+        message: `default plugin, installed by ${deps.verb} (${VERSION})`,
       });
-      outcomes.push({ name, action: "installed", digest: prepared.digest });
+      outcomes.push({ name, action: "installed", digest: push.digest });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       log.warn("default plugin install failed", { name, error: message });

package/src/local/runtime/runtimes-install.test.ts

@@ -36,6 +36,8 @@ describe("isAcquirableRelease", () => {
     expect(isAcquirableRelease("0.5.0-rc.1")).toBe(true);
     expect(isAcquirableRelease("0.0.0-dev")).toBe(false);
     expect(isAcquirableRelease("0.5.0-dev.20260825")).toBe(false);
+    // The bare stamp an unbundled server reports; the substring test this once was let it through.
+    expect(isAcquirableRelease("dev")).toBe(false);
   });
 });
 

package/src/local/runtime/runtimes-install.ts

@@ -7,6 +7,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { isReleaseVersion } from "@stigmer/plugin-package/client";
 import { CliExitError } from "../../errors/cli-exit-error.js";
 import { ExitCode } from "../../errors/exit-codes.js";
 
@@ -64,9 +65,11 @@ export function npmInstallIntoRuntimes(installDir: string, spec: string): void {
   }
 }
 
-// A source build reports "0.0.0-dev" and the dev npm channel stamps
-// "<v>-dev.<stamp>" versions; neither publishes matching runtime packages,
-// so they are not acquirable. Release and rc/next versions are.
+// A source build reports "0.0.0-dev", an unbundled server the bare "dev",
+// and the dev npm channel stamps "<v>-dev.<stamp>"; none publishes matching
+// runtime packages, so none is acquirable. Release and rc/next versions are.
+// The rule is the shared client predicate, so the console's read of the
+// official catalogue and this acquisition agree on every version.
 export function isAcquirableRelease(version: string): boolean {
-  return !version.includes("-dev");
+  return isReleaseVersion(version);
 }