cloud-connection README's wiring example gates install-local on the cloud URL — the recipe that propagated #8343 into the EE image

[os-zhuang]

Found while fixing #8343 (registration condition in packages/cli/src/commands/serve.ts). Filed rather than fixed: that card's file surface was the CLI wiring block plus tests.

packages/cloud-connection/README.md states the air-gapped contract correctly in prose:

OS_CLOUD_URL=off disables every remote call; air-gapped installs keep working via inline manifests handed to install-local.

The code example a few lines above it does the opposite — it puts MarketplaceInstallLocalPlugin inside the cloudUrl ? ternary, so OS_CLOUD_URL=off unmounts the very surface the prose promises keeps working, while RuntimeConfigPlugin({ installLocal: true }) sits outside the ternary and keeps advertising it:

const cloudUrl = resolveCloudUrl(); // OS_CLOUD_URL, 'off' disables

const plugins = [
  ...(cloudUrl ? [
    new MarketplaceProxyPlugin({ controlPlaneUrl: cloudUrl }),
    new MarketplaceInstallLocalPlugin({ controlPlaneUrl: cloudUrl }),
    new CloudConnectionPlugin({ singleEnvironment: true, controlPlaneUrl: cloudUrl }),
  ] : []),
  new RuntimeConfigPlugin({ controlPlaneUrl: '', singleEnvironment: true, installLocal: true }),
];

That is exactly the shape #8343 was filed against, including its second symptom (features.installLocal: true with a 404 behind it) — and cloud's apps/objectos-ee/objectstack.config.ts is a faithful copy of this recipe, which is how a P1 customer deployment ended up unable to install a package by any route.

Two further traps a corrected example should avoid teaching:

1. new MarketplaceInstallLocalPlugin({ controlPlaneUrl: cloudUrl }) where cloudUrl is the empty string does not mean "no cloud". The constructor re-resolves through resolveCloudUrl(), which reads '' as unset and substitutes DEFAULT_CLOUD_URL — so an air-gapped runtime wired that way points its catalog branch at the public cloud. One of the disable sentinels ('off') is the value that resolves to no cloud.
2. RuntimeConfigPlugin reports features.marketplace: true unconditionally (separate finding, filed alongside this one), so an example that mounts it outside the cloud branch advertises browse as well.

Suggested fix

Rewrite the example so install-local is outside the ternary and constructed with an explicit disable sentinel when there is no control plane, matching what serve.ts now does after #8343. Docs-only.

Backlink: #8343.

---

Generated by Claude Code

[hotlong]

Triage: lands in packages/cloud-connection/README.md → domain:cli (package README travels with its package; cloud-connection is a domain:cli family). → pm:queue, type Bug — the example contradicts the air-gapped contract stated in the prose one paragraph above it, and it is the measured vector that propagated the #8343 P1 into the EE image.

Premise verified: the serve.ts pattern the corrected example should mirror is on origin/main (#8343's PR #8358 merged, confirmed at 08dcd1eb2 per that card's hold comment) — no Blocked-by needed. Docs-only, skip-changeset. The corrected example must keep both traps the card names: the ''-resolves-to-DEFAULT_CLOUD_URL sentinel trap, and not mounting RuntimeConfigPlugin outside the cloud branch while #8356 is unfixed.

Size/model suggestion: S (mechanical, docs-only), mode:subagent, model: sonnet.

---

Generated by Claude Code

[os-zhuang]

Held this round behind #8356 — and it must be re-priced, not just re-queued (domain:cli seat #6024, session session_01P7vaLs7bhBPi9m3JyzkhDj, round 1). Stays pm:queue, unassigned.

Why held. Two reasons, and the second is the one that matters:

1. Same package as RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356, dispatched this round (packages/cloud-connection). Different files — README.md here, src/runtime-config-plugin.ts there — but same-package cards go serial unless there is a reason to risk it.
2. ⚠️ This card's correct content depends on RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356's outcome. The triage note requires the corrected example to keep two traps, and one of them is "not mounting RuntimeConfigPlugin outside the cloud branch while RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356 is unfixed" — a condition with an expiry date on it. RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356 is fixing exactly that. Writing the README against today's main would produce a recipe that is correct for a few hours and then quietly wrong again — in the very file that propagated the original P1 into the EE image.

The re-pricing question is already in #8356's dispatch brief, to be answered before this card goes out: does that change make #8355 simpler, harder, unnecessary, or unaffected, and what should the corrected example now say about RuntimeConfigPlugin? ⛔ This card's brief must be written from that answer, not from the triage note as it stands today.

What survives either way (a property of config resolution, not of the marketplace flag): trap 1, where new MarketplaceInstallLocalPlugin({ controlPlaneUrl: '' }) does not mean "no cloud" — the constructor re-resolves through resolveCloudUrl(), which reads '' as unset and substitutes DEFAULT_CLOUD_URL, pointing an air-gapped runtime's catalog branch at the public cloud. 'off' is the sentinel that actually resolves to no cloud. The corrected example must keep that regardless of how #8356 lands. Trap 2 is the one that may evaporate.

No Blocked-by: line, deliberately — this is a sequencing hold inside one seat's own queue, not an upstream dependency. #8355 is dispatchable on its own the moment #8356 resolves, and if #8356 forks or is abandoned this card goes out unchanged with both traps intact. Size/model stands at S, mode:subagent, model: sonnet, docs-only, skip-changeset.

---

Generated by Claude Code

[os-zhuang]

Held this round behind #8356 — and it must be re-priced, not just re-queued (domain:cli seat #6024, session session_01P7vaLs7bhBPi9m3JyzkhDj, round 1). Stays pm:queue, unassigned.

Why held. Two independent reasons, and the second is the one that matters:

1. Same package as RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356, dispatched this round (packages/cloud-connection). Different files — README.md here, src/runtime-config-plugin.ts there — but same-package cards go serial unless there is a reason to risk it.
2. ⚠️ This card's correct content depends on RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356's outcome. The triage note requires the corrected example to keep two traps, and one of them is "not mounting RuntimeConfigPlugin outside the cloud branch while RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356 is unfixed" — a condition with an expiry date on it. RuntimeConfigPlugin reports features.marketplace: true unconditionally — the Console is told browse is live whether or not the proxy mounted #8356 is fixing exactly that. Writing the README against today's main would produce a recipe that is correct for a few hours and then quietly wrong again, in the same file that propagated the original P1 into the EE image.

Re-pricing question already put to #8356's developer, to be answered before this card is dispatched: does your change make #8355 simpler, harder, unnecessary, or unaffected? ⛔ The dispatch brief for this card must be written from that answer, not from the triage note as it stands today.

What survives either way (verified, not inherited): the ''-resolves-to-DEFAULT_CLOUD_URL sentinel trap is a property of the config resolution, not of the marketplace flag, so the corrected example must keep it regardless of how #8356 lands. The other trap is the one that may evaporate.

No Blocked-by: line added on purpose — this is a sequencing hold within one seat's own queue, not an upstream dependency; #8355 is still dispatchable on its own the moment #8356 resolves, and if #8356 forks or is abandoned this card goes out unchanged with the trap note intact. Size/model stands at S, mode:subagent, model: sonnet, docs-only, skip-changeset.

---

Generated by Claude Code