fix(cli): honour host-wired marketplace plugins on the cloud-connected serve arm (#8357)

[os-zhuang]

Fixes#8357

What changed

objectstack serve auto-wires four surfaces whenever resolveCloudUrl() resolves and the kernel is not a runtime host kernel: MarketplaceProxyPlugin, MarketplaceInstallLocalPlugin, the same-origin cloud-connection surface, and RuntimeConfigPlugin. All four mounts were unconditional — the block never asked what the loaded host config had already wired.

Each is now guarded on its own Serve.providesCapability presence check, the idiom the offline arm has carried since the install-local change in #8343. planMarketplaceWiring reports one flag per surface (cloudProxy, cloudInstallLocal, cloudConnection, cloudRuntimeConfig), so a host composing any subset keeps exactly what it wired and the CLI supplies only the rest. Two new identity registries — MARKETPLACE_PROXY_IDENTITIES and CLOUD_CONNECTION_IDENTITIES — join the two the offline arm already declared.

cloudSurfaces keeps its name and its existing assertions, with its meaning tightened in the doc comment: it is the arm selector (does this boot take the cloud-connected arm at all), not a mount decision.

Per the grading round, Kernel.use() is not touched. Making it refuse or warn on a duplicate name was the card's alternative option and was explicitly rejected there — engine-core blast radius, and its own card if anyone wants it.

The sentinel trap the card documents is avoided: the check keys off each plugin's own identity, never off ObjectOSEnvironmentPlugin. The EE single-environment branch — the host this card is about — never constructs one; only the OS_MULTI_TENANT branch does, via createObjectOSStack. A rule hung off that sentinel would not fire for the exact host it was written for.

Premise re-verification — one part of the card is inverted

#8526 (artifact-pinned boot) landed in serve.ts after this card was written, so everything below was re-measured on this branch rather than taken from the card.

Confirmed as stated:

• ObjectKernel.use() is this.plugins.set(pluginMeta.name, meta) (packages/core/src/kernel.ts) — a Map keyed by plugin.name. No error, no dedupe, last write wins. PluginLoader.loadPlugin has no duplicate check either.
• The cloud-connected arm mounted all four surfaces with no check of the host.
• The offline arm's Serve.providesCapability check is still there to mirror.

Not confirmed — the direction of the replacement. The CLI's marketplace block runs at serve.ts:1957; the loop that registers config.plugins runs at serve.ts:2474, roughly five hundred lines later. Since the later set wins, today the host's instance is the survivor and the CLI's four are constructed, registered, and dropped. The card's "a host that mounts its own therefore has it replaced by the CLI's instance" is backwards on this tree.

That does not weaken the graded scope, it sharpens it. The host winning is an accident of where two blocks sit in one 4000-line file, neither of which mentions the other; nothing states it and nothing pinned it. It inverts silently if either block moves, and on a kernel whose use rejects duplicates (LiteKernel throws) it is the host's registration that fails instead. This change makes the outcome independent of all of that, and stops the CLI constructing four plugins it is about to discard.

Severity — read this before reviewing it as a bug fix

There is no measured user impact today, and the card says so. Both sides currently construct their instances from the same resolveCloudUrl() value, so the mounts are interchangeable; combined with the ordering above, nothing observable differs. This is precedence and config-authority restoration, not a live-bug fix. It becomes real the moment a host passes an argument the CLI cannot: a private control plane, a custom install storageDir, a credential path, white-label branding.

The test, and why it is shaped the way it is

Because both sides build identical instances today, the naive test — "does the app still boot?" — passes before and after and proves nothing. Every host fixture in packages/cli/test/serve-marketplace-cloud-host-precedence.test.ts is therefore constructed with something the CLI's auto-wiring cannot produce, and each case asserts the survivor carries the host's value:

surface	host fixture is distinguishable by
browse proxy	controlPlaneUrl: https://control-plane.internal.example + cacheMaxEntries: 4096
install-local	the same private control plane + storageDir: /srv/objectos/installed-packages
cloud-connection	credentialPath: /srv/objectos/cloud-connection.json
runtime-config	productName: Contoso Operations (white-label branding)

19 tests over three layers: the planner rule per surface and for the whole EE shape; drift guards that the declared identities still match the real classes; and a kernel layer that registers into a real ObjectKernel and reads back which instance survived. A precondition assertion pairs with each identity check, so if a construction argument is ever renamed the test goes red rather than vacuously green.

The kernel layer runs both registration orders on purpose. cli-then-host is the order serve.ts really runs in — and it passes with or without this change, so on its own it cannot tell a fixed build from a broken one. host-then-cli is the order in which the missing guard bites. Passing both is the property being claimed: the host's composition wins because it is a rule, not because of block placement.

Reverse verification

Ablation: replace the four !Serve.providesCapability(...) guards in the cloud branch with literal true — the pre-change behaviour, with the flag shape kept so the tests still compile. The fix was committed first, so the restore came out of a real commit.

Predicted before running (recorded ahead of the run, and deliberately not the template's presumption that everything goes red): 6 red, 13 green — the four per-surface tests, the whole-EE-shape test, and host-then-cli. cli-then-host predicted to stay GREEN, because the host already wins in that order without any guard; that green is the evidence for the inverted direction above.

Measured: exactly that split — 6 failed, 13 passed, cli-then-host green and host-then-cli red:

✓ EE single-environment host keeps its own four instances (cli-then-host)
× EE single-environment host keeps its own four instances (host-then-cli)
AssertionError: marketplace browse proxy: the surviving instance must be the HOST's
- Expected
+ Received
"cache": LruTtlCache {
- "max": 4096,
+ "max": 200,
},
- "cloudUrl": "https://control-plane.internal.example",

Restored with git restore --source=HEAD, git status --porcelain empty.

Verification

• pnpm --filter @objectstack/cli typecheck — clean
• pnpm --filter @objectstack/cli exec vitest run — 120 files, 1316 tests, all passing
• Full workspace build, then pnpm check:type-check-debt (--self-test && --re-measure, the strict job CI runs) — OK, 33 ledger entries re-measured, none above its recorded number. No ledger entry was raised. The only note is a pre-existing surplus in @objectstack/lint (records 20, measures 19), untouched by this branch.
• Gates re-derived against the actual changed paths with scripts/pm/dispatch-gates.mjs, which surfaced several the dispatch prompt did not name; all run and green: check:changeset-gate-self-tests, check:objectui-changeset, check:cross-package-test-inputs, check:query-options-erasure, check:type-check-coverage, check:nul-bytes, plus check-adr-0087-registration.mjs, check-changeset-no-major.mjs, check-empty-changeset.mjs.

Changeset: .changeset/cloud-arm-host-marketplace-precedence.md (patch, @objectstack/cli).

Out of scope — filed as its own finding, not changed here

#8645 remains open and is not addressed by this PR. While writing the drift guard, the built MarketplaceProxyPlugin measured as _MarketplaceProxyPlugin: esbuild renames a class that references itself by name, so the class-name limb of these identity registries matches nothing against the shipped package for that plugin. The registered-name limb carries every guard, so there is no impact and the change here is correct as landed, but the redundancy is dead and the existing drift test cannot see it (it compares the registry against its own spec string, never against Ctor.name). The new test compares modulo one leading underscore and says why.

Release freeze

Opened as a draft and staying that way. No auto-merge armed, not enqueued.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 14, 2026 7:10am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli.

17 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx(via packages/cli)
• content/docs/api/client-sdk.mdx(via @objectstack/cli)
• content/docs/api/data-flow.mdx(via @objectstack/cli)
• content/docs/api/environment-routing.mdx(via @objectstack/cli)
• content/docs/api/error-catalog.mdx(via @objectstack/cli)
• content/docs/automation/hook-bodies.mdx(via packages/cli)
• content/docs/deployment/backup-restore.mdx(via @objectstack/cli)
• content/docs/deployment/cli.mdx(via @objectstack/cli)
• content/docs/deployment/self-hosting.mdx(via @objectstack/cli)
• content/docs/getting-started/your-first-project.mdx(via @objectstack/cli)
• content/docs/kernel/runtime-services/data-service.mdx(via @objectstack/cli)
• content/docs/kernel/runtime-services/index.mdx(via packages/cli)
• content/docs/permissions/authentication.mdx(via @objectstack/cli)
• content/docs/plugins/index.mdx(via @objectstack/cli)
• content/docs/plugins/packages.mdx(via @objectstack/cli)
• content/docs/protocol/kernel/plugin-spec.mdx(via @objectstack/cli)
• content/docs/protocol/kernel/realtime-protocol.mdx(via @objectstack/cli)

⛔ 3 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/cli)
• content/docs/releases/v16.mdx(via @objectstack/cli)
• content/docs/releases/v17.mdx(via @objectstack/cli)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.