@@ -0,0 +1,10 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): `os dev` on an `os init -t app` scaffold no longer composes a second `MetadataPlugin` and warns "Plugin superseded: 'com.objectstack.metadata'"
+
+Clause-②: no — boot diagnostics only; nothing accepted or published changes
+Metadata-protocol: none
+
+The dev artifact door in `os serve` / `os dev` added its own `MetadataPlugin` unless the stack already held one, but it recognised that plugin only by its class name. The published `@objectstack/metadata` bundle names the class `_MetadataPlugin`, so on an installed CLI the check missed the `MetadataPlugin` the standalone stack had already composed, added a second one, and every dev boot of an untouched scaffold printed a "Plugin superseded" diagnostic blaming a composition the user never wrote. The dev door now asks the same question the host-config door asks: a plugin named `com.objectstack.metadata` (or, as before, a class named `MetadataPlugin`) means the stack has one. A host config with no `MetadataPlugin` of its own still gets the dev door, as before.
@@ -0,0 +1,10 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): the empty kernel's own stub declares its protocol range, so `os start` in an empty directory boots with no compatibility warning
+
+Clause-②: no — boot diagnostics only; nothing accepted or published changes
+Metadata-protocol: none
+
+The empty-boot stub `createDefaultHostConfig({ requireArtifact: false })` writes to `~/.objectstack/dist/objectstack.json` (manifest id `com.objectstack.empty`) now declares `engines: { protocol: '^<major>' }`, the major of the runtime that writes it. Before, it declared no range, so the ADR-0087 handshake warned "package 'com.objectstack.empty' declares no engines.protocol range" on the first boot of the docs' one-line Community quickstart (`npm i -g @objectstack/cli && os start`), about a package the user never wrote. A stub already on disk from an older CLI is refreshed in place on the next `os start`, including when the start supervisor hands it down by path (it resolves `<home>/dist/objectstack.json` as an artifact once that file exists): only `manifest.engines.protocol` is rewritten, and only while the file at the home location is still the stub. The same refresh re-stamps a stub written under another protocol major, which would otherwise be refused as `OS_PROTOCOL_INCOMPATIBLE` once the runtime moves to the next major. An artifact that is not the stub, or a file that is not JSON, is left alone.
@@ -71,9 +71,13 @@ describe('#22989 A — `os serve` of a HOST config composes an artifact-less Met
         const gate = source.slice(gateAt, source.indexOf('hostConfigMetadataDoor = new MetadataPlugin({'));
         expect(gate).toContain('!devArtifactDoor');
         expect(gate).toContain('isHostConfig(config)');
-        expect(gate).toContain(
-            "!plugins.some((p: any) => p?.name === 'com.objectstack.metadata' || p?.constructor?.name === 'MetadataPlugin')",
-        );
+        expect(gate).toContain('!hasMetadataPlugin(plugins)');
+        // #29936 — both doors ask the ONE predicate, and no class-name-only
+        // spelling is left: the published bundle names the class
+        // `_MetadataPlugin`, so such a check missed the standalone stack's own
+        // plugin and composed a second one on every `os dev` of a scaffold.
+        expect(count('!hasMetadataPlugin(plugins)')).toBe(2);
+        expect(source).not.toContain("constructor?.name === 'MetadataPlugin'");
         // Decided after the dev door (it reads that value) and before the wrap.
         expect(source.indexOf('let devArtifactDoor: any;')).toBeLessThan(gateAt);
         expect(gateAt).toBeLessThan(
 
@@ -113,9 +113,11 @@ describe('#14397 — `os dev` over a HOST config composes ONE registrar for stac
         expect(source, 'the door decision must be a single named value').toContain(
             'let devArtifactDoor: any;',
         );
-        // The gate is the same one the composition has always used.
+        // The gate asks the one `hasMetadataPlugin` predicate the host-config
+        // door asks too (#29936: a class-name-only spelling missed the
+        // published bundle's `_MetadataPlugin` and composed a second door).
         expect(source).toContain(
-            "if (isDev && flags.server && !plugins.some((p: any) => p?.constructor?.name === 'MetadataPlugin')) {",
+            'if (isDev && flags.server && !hasMetadataPlugin(plugins)) {',
         );
         // Exactly one ARTIFACT door is constructed in this file, and it is that
         // value — a second artifact-door construction site is a second
 
@@ -125,6 +125,7 @@ import {
   resolveStackCollection,
   stackDeclaredCapabilities,
   stackBootPlugins,
+  hasMetadataPlugin,
 } from '../utils/stack-collections.js';
 import { redactConnectionUrl, describeDriverConnection, describeDriverSqliteFile } from '../utils/connection-display.js';
 import { captureServedDatabaseFile, watchServedDatabaseFile } from '../utils/served-database-file.js';
@@ -3511,7 +3512,7 @@ export default class Serve extends Command {
       // points except by the AppPlugin append below, and an AppPlugin is not a
       // MetadataPlugin.
       let devArtifactDoor: any;
-      if (isDev && flags.server && !plugins.some((p: any) => p?.constructor?.name === 'MetadataPlugin')) {
+      if (isDev && flags.server && !hasMetadataPlugin(plugins)) {
         try {
           const { resolveDefaultArtifactPath } = await import('@objectstack/runtime');
           // `os dev` is the only caller that reaches here, and it is a
@@ -3652,7 +3653,7 @@ export default class Serve extends Command {
       if (
         !devArtifactDoor
         && isHostConfig(config)
-        && !plugins.some((p: any) => p?.name === 'com.objectstack.metadata' || p?.constructor?.name === 'MetadataPlugin')
+        && !hasMetadataPlugin(plugins)
       ) {
         const { MetadataPlugin } = await import('@objectstack/metadata');
         hostConfigMetadataDoor = new MetadataPlugin({
 
@@ -155,6 +155,10 @@ const SERVE_ONLY: Record<string, string> = {
     'decides serve\'s artifact-less MetadataPlugin for a host config that no artifact door serves ([#22989]); '
     + 'the one-shot boot boots the standalone data stack, whose MetadataPlugin is always composed, and lays a '
     + 'host config\'s plugins over it (buildSchemaMigrationPlugins)',
+  hasMetadataPlugin:
+    'decides whether serve adds its own MetadataPlugin, the dev artifact door or the artifact-less host-config '
+    + 'door, beside the one a composition already holds ([#29936]); the one-shot boot boots the standalone data '
+    + 'stack, whose MetadataPlugin is always composed, and adds none of its own',
   bundleDeclaresTranslations:
     'decides serve\'s tier-gated i18n service, which the declaration boot does not compose '
     + '(schema-migration-plugins.ts, "What this does NOT compose")',
 
@@ -17,6 +17,7 @@ import {
   artifactObjectNames,
   authoringRuleUnionStack,
   bundleDeclaresTranslations,
+  hasMetadataPlugin,
   resolveStackCollection,
   shouldAutoRegisterObjectQL,
   shouldAutoRegisterStorageDriver,
@@ -268,3 +269,28 @@ describe('#22371 — stackBootPlugins, `os serve`\'s `plugins` and its `--dev` m
     expect(stackBootPlugins(undefined, true)).toEqual([]);
   });
 });
+
+describe('#29936 — hasMetadataPlugin, the one gate both `os serve` metadata doors ask', () => {
+  // The shape the published `@objectstack/metadata` bundle emits (18.3.0
+  // dist/index.js: `var MetadataPlugin = class _MetadataPlugin {`): the class
+  // name is `_MetadataPlugin`, only `name` still says what the plugin is.
+  const BundledMetadataPlugin = class _MetadataPlugin {
+    name = 'com.objectstack.metadata';
+  };
+
+  it('finds the plugin by its name when the bundle renamed the class', () => {
+    const bundled = new BundledMetadataPlugin();
+    expect(bundled.constructor.name).toBe('_MetadataPlugin');
+    expect(hasMetadataPlugin([{ name: 'com.objectstack.runtime.default-datasource' }, bundled])).toBe(true);
+  });
+
+  it('finds the source-built class by its class name', () => {
+    class MetadataPlugin {}
+    expect(hasMetadataPlugin([new MetadataPlugin()])).toBe(true);
+  });
+
+  it('answers false for a stack with no metadata plugin', () => {
+    expect(hasMetadataPlugin([])).toBe(false);
+    expect(hasMetadataPlugin([{ name: 'com.objectstack.engine.objectql' }, null, undefined, 'x'])).toBe(false);
+  });
+});
@@ -122,6 +122,28 @@ function hasObjectQLPlugin(plugins: readonly unknown[]): boolean {
   });
 }
 
+/**
+ * Does `plugins[]` already hold `@objectstack/metadata`'s `MetadataPlugin`?
+ * (`serve.ts`: the dev artifact door and the host-config door both ask.)
+ *
+ * The plugin's `name` (`com.objectstack.metadata`) is the identity; the class
+ * name is only a fallback. ⚠️ A class-name-only check misses the real plugin:
+ * the published `@objectstack/metadata` bundle emits
+ * `var MetadataPlugin = class _MetadataPlugin { … }`, so on an installed CLI
+ * `constructor.name` is `_MetadataPlugin`. Source-run tests never see that
+ * rename. Measured on the published 18.3.0 CLI (#29936): the dev door's
+ * class-name-only gate missed the standalone stack's own `MetadataPlugin`,
+ * composed a second one, and every `os dev` boot of an `os init -t app`
+ * scaffold warned "Plugin superseded: 'com.objectstack.metadata'".
+ */
+export function hasMetadataPlugin(plugins: readonly unknown[]): boolean {
+  return plugins.some((p) => {
+    const plugin = asBag(p);
+    const ctor = (plugin?.constructor as { name?: string } | undefined)?.name;
+    return plugin?.name === 'com.objectstack.metadata' || ctor === 'MetadataPlugin';
+  });
+}
+
 /**
  * Does `plugins[]` already provide a storage driver? (`serve.ts` step 2.)
  *
 
@@ -0,0 +1,160 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+// #29937 — the empty-boot stub (`com.objectstack.empty`) is the platform's own
+// package, written by the runtime that boots it. With no `engines.protocol` the
+// ADR-0087 handshake answered `no-range`, and `os start` in an empty directory
+// (the docs' one-line Community quickstart) printed a compatibility WARN about
+// it as the newcomer's first boot diagnostic. The stub now declares this
+// runtime's major, and a stub an older CLI wrote is refreshed in place.
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PROTOCOL_MAJOR } from '@objectstack/spec/kernel';
+import { checkProtocolCompat } from '@objectstack/metadata-core';
+import { EMPTY_BOOT_STUB_ID, createDefaultHostConfig, ensureEmptyBootStub } from './default-host.js';
+
+const RANGE = `^${PROTOCOL_MAJOR}`;
+
+/** The stub exactly as CLIs up to 18.3.0 wrote it: no `engines`. */
+const LEGACY_STUB = {
+    manifest: {
+        id: EMPTY_BOOT_STUB_ID,
+        name: 'empty',
+        version: '0.0.0',
+        type: 'app',
+        description: 'Empty starter kernel — install apps via the Studio marketplace.',
+    },
+    objects: [],
+    views: [],
+    apps: [],
+    flows: [],
+    requires: [],
+};
+
+let dir: string;
+let stubPath: string;
+
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'os-29937-'));
+    stubPath = join(dir, 'dist', 'objectstack.json');
+});
+
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+});
+
+function readStub(): any {
+    return JSON.parse(readFileSync(stubPath, 'utf8'));
+}
+
+function writeStub(value: unknown): void {
+    mkdirSync(join(dir, 'dist'), { recursive: true });
+    writeFileSync(stubPath, typeof value === 'string' ? value : JSON.stringify(value, null, 2), 'utf8');
+}
+
+describe('ensureEmptyBootStub — the empty kernel declares its own protocol range (#29937)', () => {
+    it('writes a fresh stub that passes the ADR-0087 handshake with no warning', () => {
+        ensureEmptyBootStub(stubPath);
+
+        expect(existsSync(stubPath)).toBe(true);
+        const stub = readStub();
+        expect(stub.manifest.id).toBe(EMPTY_BOOT_STUB_ID);
+        expect(stub.manifest.engines).toEqual({ protocol: RANGE });
+        // `ok` is the only status `assertProtocolCompat` returns from silently.
+        expect(checkProtocolCompat(stub.manifest).status).toBe('ok');
+    });
+
+    it('refreshes a stub an older CLI wrote with no `engines`, keeping everything else', () => {
+        writeStub(LEGACY_STUB);
+        expect(checkProtocolCompat(LEGACY_STUB.manifest).status).toBe('no-range');
+
+        ensureEmptyBootStub(stubPath);
+
+        const stub = readStub();
+        expect(stub).toEqual({
+            ...LEGACY_STUB,
+            manifest: { ...LEGACY_STUB.manifest, engines: { protocol: RANGE } },
+        });
+        expect(checkProtocolCompat(stub.manifest).status).toBe('ok');
+    });
+
+    it('re-stamps a stub a CLI of another major wrote, so a major bump never refuses the empty boot', () => {
+        const otherMajor = `^${PROTOCOL_MAJOR - 1}`;
+        writeStub({ ...LEGACY_STUB, manifest: { ...LEGACY_STUB.manifest, engines: { protocol: otherMajor } } });
+        expect(checkProtocolCompat(readStub().manifest).status).toBe('incompatible');
+
+        ensureEmptyBootStub(stubPath);
+
+        expect(readStub().manifest.engines).toEqual({ protocol: RANGE });
+    });
+
+    it('leaves a current stub byte for byte', () => {
+        ensureEmptyBootStub(stubPath);
+        const before = readFileSync(stubPath, 'utf8');
+
+        ensureEmptyBootStub(stubPath);
+
+        expect(readFileSync(stubPath, 'utf8')).toBe(before);
+    });
+
+    it('never touches an artifact that is not the stub', () => {
+        const foreign = JSON.stringify({ manifest: { id: 'com.example.crm', name: 'crm', version: '1.0.0', type: 'app' } });
+        writeStub(foreign);
+
+        ensureEmptyBootStub(stubPath);
+
+        expect(readFileSync(stubPath, 'utf8')).toBe(foreign);
+    });
+
+    it('never touches a file it cannot read as JSON (the loader reports it)', () => {
+        writeStub('{ not json');
+
+        ensureEmptyBootStub(stubPath);
+
+        expect(readFileSync(stubPath, 'utf8')).toBe('{ not json');
+    });
+});
+
+describe('createDefaultHostConfig — the stub is refreshed on every empty boot, named or not (#29937)', () => {
+    const BOOT_TIMEOUT = 60_000;
+    let savedHome: string | undefined;
+
+    beforeEach(() => {
+        savedHome = process.env.OS_HOME;
+        process.env.OS_HOME = dir;
+    });
+
+    afterEach(() => {
+        if (savedHome === undefined) delete process.env.OS_HOME;
+        else process.env.OS_HOME = savedHome;
+    });
+
+    // `os start` resolves `<home>/dist/objectstack.json` as an artifact rung
+    // once it exists and hands it down as `artifactPath`, so every boot after
+    // the first reaches the stub NAMED, never through the empty-boot branch.
+    it('refreshes a legacy stub handed in as `artifactPath` at the home location', async () => {
+        writeStub(LEGACY_STUB);
+
+        await createDefaultHostConfig({ requireArtifact: true, artifactPath: stubPath, databaseUrl: ':memory:' });
+
+        expect(readStub().manifest.engines).toEqual({ protocol: RANGE });
+    }, BOOT_TIMEOUT);
+
+    it('writes the stub with its range on the empty boot itself', async () => {
+        await createDefaultHostConfig({ requireArtifact: false, databaseUrl: ':memory:' });
+
+        expect(readStub().manifest.engines).toEqual({ protocol: RANGE });
+    }, BOOT_TIMEOUT);
+
+    it('leaves a stub-shaped artifact named anywhere else alone', async () => {
+        const elsewhere = join(dir, 'elsewhere.json');
+        const bytes = JSON.stringify(LEGACY_STUB);
+        writeFileSync(elsewhere, bytes, 'utf8');
+
+        await createDefaultHostConfig({ requireArtifact: true, artifactPath: elsewhere, databaseUrl: ':memory:' });
+
+        expect(readFileSync(elsewhere, 'utf8')).toBe(bytes);
+    }, BOOT_TIMEOUT);
+});