OS_CLOUD_URL=off unmounts the air-gapped install-local endpoint — the offline install path is gated on the cloud URL it is designed not to need

[baozhoutao]

os package install ./dist/objectstack.json is documented as the air-gapped path — "the compiled artifact is read locally and sent inline — no catalog round-trip, works fully offline" (packages/cli/src/commands/package/install.ts). The plugin that serves it agrees: marketplace-install-local-plugin.ts:463 — "Bypass the cloud-fetch entirely; no OS_CLOUD_URL required".

But the plugin is only registered when a cloud URL exists (packages/cli/src/commands/serve.ts:1652):

const marketplaceUrl = resolveCloudUrl();
if (marketplaceUrl) {
 await kernel.use(new MarketplaceProxyPlugin({ controlPlaneUrl: marketplaceUrl }));
 await kernel.use(new MarketplaceInstallLocalPlugin({ controlPlaneUrl: marketplaceUrl }));
 …
 await kernel.use(new RuntimeConfigPlugin({ controlPlaneUrl: '', singleEnvironment: true, installLocal: true }));
}

With OS_CLOUD_URL=off — the value the self-hosted EE compose file documents as "完全自托管填 off" — resolveCloudUrl() is empty, the whole block is skipped, and the endpoint never mounts. So the deployment that most needs offline install is the one that cannot have it.

Measured

objectos-ee-deploy (image ghcr.io/objectstack-ai/objectos-ee@sha256:c93b4937…, tag 4.0.5-rc.1), OS_CLOUD_URL=off, container command node node_modules/@objectstack/cli/bin/run.js start (which forks serve):

GET /api/v1/marketplace/install-local → 404 {"error":"Not found"}
POST /api/v1/marketplace/install-local → 404 {"error":"Not found"}

There is no other package-install surface: the served OpenAPI document contains no path matching package|marketplace|install, and the container mounts only /data (the artifact is baked into the image at OS_ARTIFACT_PATH=/repo/cloud/apps/objectos-ee/dist/objectstack.json). OS_ARTIFACT_PATH takes a single artifact, not a directory or a list (packages/runtime/src/default-host.ts:49), so there is also no "drop another bundle in" workaround. The deployment simply cannot install a package by any route.

Second symptom: the Console is told the feature is live

GET /api/v1/runtime/config on the same deployment returns:

{"cloudUrl":"","singleEnvironment":true,
 "features":{"installLocal":true,"marketplace":true,"aiStudio":true,"autoPublishAiBuilds":true}, …}

installLocal: true with no endpoint behind it. Whatever supplies runtime-config in the EE image is not the RuntimeConfigPlugin from the skipped block, so the flag and the route now disagree — the Console will offer an install affordance that 404s.

Expected

Registration of MarketplaceInstallLocalPlugin should not depend on resolveCloudUrl(). Only the catalog branch needs a control plane, and it already degrades correctly on its own (marketplace-install-local-plugin.ts:494 → 503 MARKETPLACE_UNAVAILABLE, "OS_CLOUD_URL not configured."). Mounting it unconditionally therefore costs nothing and restores the documented offline path; MarketplaceProxyPlugin (a pure cloud proxy) can stay behind the URL check.

And whichever component reports features.installLocal should report what is actually mounted.

Impact

This is the blocking issue for installing any first-party or customer application into a self-hosted EE deployment — the concrete case here was installing HotCRM (app.objectstack.hotcrm) into a running multi-org EE stack, for which no supported path currently exists.

Environment

objectos-ee-deploy (Caddy → app → postgres:16), NODE_ENV=production, OS_TENANCY_POSTURE=isolated, OS_MODE=standalone, OS_CLOUD_URL=off, on http://localhost:8080, observed 2026-08-13. Source references are the current framework main checkout.

[os-zhuang]

Claim: PM loop round 3
Session: session_016pY4Xb2iDecfDtT3CWoiTW
Branch: claude/issue-8343-install-local-offline-gate
Worktree: objectstack-issue-8343
Domain: domain:cli
File surface: packages/cli/src/commands/serve.ts (the marketplace/cloud-connection wiring block only) + its test coverage (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Serial constraints cleared: nothing in flight touches packages/cli. Lane siblings #8039 / #8264 land in packages/rest, #8087 in packages/runtime + packages/types — all disjoint. No open PR touches serve.ts at claim time.

Authorization — maintainer direct-dispatch channel. This card carried no pm-state (triage had not queued it), so it was not dispatchable under the ordinary rule. The maintainer directed it in a live PM session, verbatim:

派

Under the 2026-08-10 standing authorization, a maintainer-directed PM session routes directly, with the instruction quoted in the audit comment; this applies only to the card explicitly directed. pm:dispatched here therefore comes from that instruction, not from a triage grading — the triage seat should still record its own type/grading judgement if it disagrees. priority:p1 is left exactly as filed; ⛔ this seat does not produce priority labels.

Premise re-verified on origin/main @ cb43296ef. The gating block is real and reads as the card describes, but the card's line number has moved (:1652 → the block now sits at :1725-1736), so the arm must be located by text.

⚠️ Two findings from the premise check that change what this card is, both handed to the dev as falsifiable assumptions rather than conclusions:

1. There is a SECOND skip condition the card does not mention, and it is checked first. if (!isRuntimeHostKernel) wraps the entire block — the wiring is skipped outright when ObjectOSEnvironmentPlugin is present, because "the cloud distribution (objectos-stack) wires its own MarketplaceProxyPlugin on the host kernel, so auto-wiring here would double-mount". The measured deployment is objectos-ee, which may well be exactly that. If so, OS_CLOUD_URL=off is not the cause, the diagnosis on this card is wrong, and the fix is somewhere else entirely — possibly in the cloud repo. That question is the dev's first task, before any edit.
2. "Mounting it unconditionally therefore costs nothing" is contradicted by the code's own comment. The gate is documented as deliberate: OS_CLOUD_URL=off -> nothing mounts, preserving the vanilla marketplace-less objectstack dev``. And each plugin "self-registers its own Setup nav bundle in start()" — so unconditional mounting adds a Setup nav entry to every plain `objectstack dev` app. That is a real cost on a surface the card did not weigh, and the fix has to reconcile the offline-install need with the vanilla-dev intent rather than assume no conflict.

Also noted: the second symptom (features.installLocal: true with no endpoint) cannot come from the skipped RuntimeConfigPlugin — that plugin lives in packages/cloud-connection and is registered inside the skipped block. Whatever serves /runtime/config in the EE image is a different producer, plausibly in the cloud repo. If it lands there it is a separate card in that repo with a Blocked-by: link, ⛔ not folded in here.

---

Generated by Claude Code

[os-zhuang]

{
 "issue": 8343,
 "status": "done",
 "branch": "claude/issue-8343-install-local-offline-gate",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8358",
 "premise_still_valid": true,
 "summary": "Assumption 1 checked FIRST and falsified: the second guard did not fire. ObjectOSEnvironmentPlugin is constructed only by createObjectOSStack, which apps/objectos-ee/objectstack.config.ts calls only on its OS_MULTI_TENANT branch; the measured box is OS_MODE=standalone multi-ORG (a different axis), so it takes the single-environment branch and isRuntimeHostKernel is false. Corroborated from the field data rather than by reading alone: the measured autoPublishAiBuilds:true can only come from the cloud-wired RuntimeConfigPlugin subclass (the open plugin's static default for that key is false), and only that single-env branch mounts it — which also proves the branch ran. So the cloud-URL guard is the one that skipped the mount and the card's diagnosis is correct. Fix: split the registration condition by what each surface needs — cloud clients (proxy, cloud-connection, runtime-config) still require a resolved URL; install-local mounts regardless, via a new pure Serve.planMarketplaceWiring() static. Assumption 2 is PARTLY falsified and that changed the design: a plain objectstack dev sets no OS_CLOUD_URL, resolveCloudUrl() then returns DEFAULT_CLOUD_URL (truthy), so vanilla dev already mounts install-local and its Setup nav entry today and is byte-identical after this change; only explicit opt-outs (off/none/local/disabled) are affected, and for them marketplace-ui.ts's 'the entry lives and dies with the capability, no dead page' rule is satisfied, not violated. Two traps found and pinned: passing the empty marketplaceUrl already in scope would have resolved to the PUBLIC DEFAULT_CLOUD_URL (resolveCloudUrl reads '' as unset), pointing an air-gapped box at cloud.objectos.ai — so the mount passes an 'off' sentinel held in a named constant; and kernel.use keys by name, so an unguarded mount would silently replace a host config's own URL-configured install-local, hence a providesCapability presence check on the new arm.",
 "tests": "Build closure first (pnpm --filter '<pkg>^...' build) — required, and later required AGAIN at full scope: check:type-check-debt REFUSED to run against an incomplete closure ('--re-measure cannot run: 1 workspace dependenc(ies) ... have no built type entry point on disk -- @objectstack/service-knowledge'); after 'turbo run build --filter=./packages/* --filter=./packages/*/*' (70 successful) it returned 'OK — 33 ledger entr(ies) re-measured in 187.3s, 1969 raw tsc error(s) total, none above its recorded number'. NEW TESTS: packages/cli/test/serve-marketplace-offline-install.test.ts + packages/cli/test/serve-capability-identity.test.ts => 'Test Files 2 passed (2) / Tests 62 passed (62)'. packages/cloud-connection full suite (incl. new marketplace-install-local-offline-degradation.test.ts) => 'Test Files 17 passed (17) / Tests 115 passed (115)'. FULL @objectstack/cli suite => 'Test Files 116 passed (116) / Tests 1265 passed (1265)'. typecheck: pnpm --filter @objectstack/cli typecheck => 'tsc --noEmit' clean (cloud-connection ships no typecheck script; it sits in the DEBT ledger). REVERSE VERIFICATION, direction predicted BEFORE running and done from the COMMITTED state: (a) restoring the pre-fix rule (offlineInstallLocal:false) => predicted exactly 1 of 9 red, observed 'Tests 1 failed | 8 passed (9)', failure = 'THE REGRESSION — OS_CLOUD_URL=off still mounts the offline install surface ... expected false to be true'; (b) constant changed to '' => predicted the trap pin red, observed 'Tests 1 failed | 8 passed (9)' with \"expected 'https://cloud.objectos.ai' to be ''\" — the air-gapped-box-dials-out failure made visible. Restored via git checkout from the branch; 'git diff HEAD --stat' empty, byte-identical. GATES: the four named at dispatch all green (check:cross-package-test-inputs 'OK: 9 package(s) read outside themselves, all declared'; check:startup-registry-verdict 'OK — 40 startup/open-registry seam(s) ... none recording a verdict the boot can contradict'; check:type-check-coverage 'OK — 64/77 packages type-checked'; check:type-check-debt as above), plus check:nul-bytes 'OK (scanned 7575 text file(s) ... no raw ASCII control bytes)' and a grep -naP control-char self-scan (clean). RE-DERIVED against the final diff with node scripts/pm/dispatch-gates.mjs AFTER the changeset existed — it surfaced three families the dispatch list did not name: check:changeset-gate-self-tests, check:objectui-changeset, check:query-options-erasure (all triggered by .changeset/ + the new test files). All three run, all EXIT=0.",
 "open_questions": [
 {
 "question": "Should a cloud-less runtime also be able to TELL the Console that install-local is live? It now has a working route the Console cannot discover, because mounting RuntimeConfigPlugin on the offline arm would have asserted a browse capability that is definitively absent.",
 "options": [
 "A — leave as shipped here (route works, no runtime-config on the offline arm) and fix the flag at its source under #8356, deriving features.marketplace from what is actually mounted",
 "B — mount RuntimeConfigPlugin on the offline arm now and accept that it reports features.marketplace: true with no proxy behind it",
 "C — add a marketplace?: boolean config knob to RuntimeConfigPlugin and have every host keep it in step with its own mounting"
 ],
 "recommendation": "A. B trades the reported bug for its mirror image — the card's own complaint is a flag advertising a route that 404s, and B would ship exactly that one key over, which is why I did not take it even though it would have closed the card's closing line in this PR. C repeats the mistake one layer up: 'every host must remember' is precisely what the EE config and the package README both failed to do, and hosts forgetting is the mechanism that produced this P1. A puts the answer in the component that knows it (declared = enforced, AGENTS.md #10 corollary) and is filed with an acceptance list at #8356."
 },
 {
 "question": "Is `Part of #8343` the right closing keyword, leaving this P1 card open after the fix lands?",
 "options": [
 "A — Part of (chosen): the card's closing line 'whichever component reports features.installLocal should report what is actually mounted' was excluded by dispatch scope and went to cloud#1287 + #8356",
 "B — Fixes: the blocking symptom (no install route on a self-hosted box) is fully resolved, so the card has served its purpose"
 ],
 "recommendation": "A, per the dispatch contract's explicit rule for a half excluded by scope. Flagging it because the practical effect is that a P1 stays open after its blocking symptom is fixed — if the PM prefers the card closed on merge, switching the body to `Fixes` is a one-line edit and cloud#1287 / #8356 already carry the remainder independently."
 }
 ],
 "out_of_scope_findings": [
 "filed as #8355: packages/cloud-connection/README.md's wiring example gates install-local on the cloud URL, contradicting its own prose one paragraph below — and cloud's apps/objectos-ee/objectstack.config.ts is a faithful copy of that recipe, i.e. this README is the vector that propagated this P1 into the EE image (unlabeled, concrete defect)",
 "filed as #8356: RuntimeConfigPlugin hardcodes features.marketplace: true, so the Console is told browse is live whether or not MarketplaceProxyPlugin mounted — the same declared-is-not-enforced shape as this card's second symptom, one key over; this is the live constraint that shaped the fix above (unlabeled, concrete defect)",
 "filed as #8357: serve.ts's cloud-connected arm can silently replace a host config's own marketplace plugins (kernel.use keys by name); benign today only because objectos-ee and the CLI construct them with identical arguments (labeled `finding`, observation-class)",
 "filed as objectstack-ai/cloud#1287 with Blocked-by: this card — the second symptom's producer, identified conclusively: apps/objectos-ee/objectstack.config.ts mounts RuntimeConfigPlugin({installLocal:true}) OUTSIDE the ternary that holds MarketplaceInstallLocalPlugin. Also records a documentation conflict found in passing: that image's Dockerfile comment claims 'start never falls back to compiling objectstack.config.ts at boot', but the measured autoPublishAiBuilds:true proves the TS config did load"
 ]
}

Correction made to the card's own wording, worth recording: the body quotes the EE compose file as documenting OS_CLOUD_URL=off for 完全自托管. That phrase appears nowhere in the cloud repo — it is a paraphrase. What the file actually says is stronger and checkable: OS_CLOUD_URL: ${OS_CLOUD_URL:-off}, i.e. off is the shipped default, so the blast radius is every self-hosted stack that does not override it, not only those that chose off. A second commit removed the paraphrased quotation from the code comment.

---

Generated by Claude Code

[os-zhuang]

ACCEPT — PR #8358

Reviewed against the diff and origin/main, not the report. 4 files, 476 insertions / 6 deletions; the six deletions are the condition lines being split. Scope is exactly the claimed surface plus tests.

Both dispatch doubts were tested first, and both moved the work — which is the point of writing them down.

1. My "maybe the other guard fired" doubt: falsified, and not by reading alone. ObjectOSEnvironmentPlugin is constructed only by createObjectOSStack, called only on the EE config's OS_MULTI_TENANT branch; the measured box is OS_MODE=standalone multi-org, a different axis, so isRuntimeHostKernel is false. Then corroborated from the field data: the measured autoPublishAiBuilds: true can only come from the cloud-wired RuntimeConfigPlugin subclass (the open plugin's static default is false), which only the single-environment branch mounts — so the branch demonstrably ran. Two independent routes to the same conclusion, one of them using the reporter's own evidence. The card's diagnosis stands.
2. My "unconditional mounting costs a nav entry" doubt: partly falsified, and it changed the design. A plain objectstack dev sets no OS_CLOUD_URL, so resolveCloudUrl() returns the truthy DEFAULT_CLOUD_URL — vanilla dev has been mounting install-local and its nav entry all along and is byte-identical after this change. Only explicit opt-outs (off/none/local/disabled) are affected, which is precisely the population the card is about. My concern was worth raising and empirically empty; the honest version of the vanilla-dev intent is preserved rather than overridden.

The trap it found is worth more than the fix. The obvious spelling — reuse the empty marketplaceUrl already in scope — would have been silently catastrophic: resolveCloudUrl() reads '' as unset and substitutes the public DEFAULT_CLOUD_URL, so an air-gapped runtime's catalog branch would have been pointed at cloud.objectos.ai, the exact opposite of what off requested, invisible until a box with no egress hangs. static readonly OFFLINE_CONTROL_PLANE = 'off' is a named constant specifically so a test asserts the property instead of a comment claiming it — verified in the diff, along with the pin that turns red when it is changed back to ''. The second guard (kernel.use keys by name, so an unguarded mount would silently replace a host's own URL-configured install-local) is the same class of catch.

Reverse verification, direction predicted before running, from the committed state: restoring the pre-fix rule turns exactly 1 of 9 red (the offline-mount pin) with 8 green; changing the sentinel to '' turns the trap pin red reporting expected 'https://cloud.objectos.ai' to be ''. Both observed as predicted, then restored byte-identically.

All four filed cards verified to exist, not merely described: #8355 (the README wiring example that propagated this P1 into the EE config — the vector, which is the most useful of the four), #8356, #8357 (finding), and objectstack-ai/cloud#1287 with a Blocked-by link, which is the contract-first cross-repo split done correctly.

---

Ruling on open question 1 — option A, as shipped.

features.marketplace stays out of this PR; the fix lands at its source in #8356. Your reasoning is right and I am adopting it rather than restating it: B trades the reported bug for its mirror image — this card's own complaint is a flag advertising a route that 404s, and B would ship exactly that one key over. C repeats the mechanism that caused the P1: "every host must remember to keep the flag in step" is what the EE config and the package README both failed to do. A puts the answer in the component that can actually know it. Not a maintainer-floor call — it widens no contract and adds no public surface; it restores declared = enforced.

Consequence stated plainly so it is not discovered later: a cloud-less framework runtime now has a working install-local route the Console cannot yet discover. That is a strictly better state than the reported one (route missing entirely) and is tracked with an acceptance list at #8356.

Ruling on open question 2 — Part of stays, and this card does NOT close on merge.

You applied the rule correctly and were right to flag the consequence. My answer is not "switch to Fixes":

This card's shape is the same as #7644's — the fix is at HEAD, and the reporter measured a published image. objectos-ee runs ghcr.io/objectstack-ai/objectos-ee@sha256:c93b4937… (4.0.5-rc.1); nothing this PR does reaches that deployment until an image carries it. Closing on merge would tell the filer their blocked HotCRM install is unblocked when the box they measured is byte-identical to before.

So on merge I move this to pm:on-hold with a mechanically checkable restart condition — an EE image built from a CLI containing this change — rather than either closing it or leaving it in the dispatchable pool. That keeps the P1 honest: the code half is done and reviewed, the verification half is waiting on a release, and it is nobody's dispatchable work in between. The residual scope items are independently carried by cloud#1287 and #8356 regardless.

Landing: path face clean (no docs/adr/**, no skills/**) → normal route. Ready-flip and queue once the gate jobs converge.

---

Generated by Claude Code