cli: server-ready banner prints container-internal `http://localhost:<port>` URLs, ignoring resolved `OS_AUTH_URL` / `OS_BASE_URL`

[os-zhuang]

Origin: moved from objectstack-ai/cloud#1507 (EE 4.1.0 published-image acceptance) — the fix lands in packages/cli, so the card lives here (file-at-destination); the source card is closed as moved.

Symptom (measured, EE 4.1.0 compose stack)

The boot banner prints the container-internal address:

 ➜ API: http://localhost:3000/
 ➜ Console: http://localhost:3000/_console/
 ➜ MCP: http://localhost:3000/api/v1/mcp
 connect an AI client (Claude Code, Cursor, …) · skill: http://localhost:3000/api/v1/mcp/skill

while the published entry point is Caddy on :80 (the deploy README's step 5 is open http://localhost), and OS_AUTH_URL is already resolved to http://localhost by compose. :3000 is an expose-only container port — unreachable from the host (no ports: mapping; even less so under --scale app=N).

Impact: following the banner's Console link fails outright; after moving to a domain (per the README's HTTPS step) the banner still says localhost:3000; the MCP line is the address customers copy into AI clients, and it can never connect.

PM 建议的路线(可选,实测优先)

Resolve the banner's external base through the runtime's existing precedence chain (OS_AUTH_URL → OS_BASE_URL → http://localhost:<port> fallback) — the same chain the compose template documents; when no external base can be determined, prefer printing no absolute URL over a wrong one.

Landing spot: packages/cli/src/utils/format.ts:583 area (server-ready banner assembly) and its call site in serve.

[os-elon]

Claim: domain:cli lane execution seat
Session: session_019bmVFqoQPq63zhKrxdYG1r
Branch: claude/issue-10646-banner-external-base-url
Worktree: objectstack-issue-10646
Domain: domain:cli
File surface: the server-ready banner assembly (packages/cli/src/utils/format.ts, around :583 — ⛔ re-derive, the card's anchor is from 2026-08-21 07:23Z) and its call site in serve, plus tests.
Container & model: M, mode:subagent, model: opus
Clause-②: no — this changes what the banner prints. No request is accepted or refused differently and nothing published widens.
Serial constraints cleared: measured, not assumed — all 19 open PRs listed and checked; none touches format.ts or serve.ts. ⚠️ But see the freshness warning below: serve.ts changed minutes ago.

⚠️ serve.ts was modified in the last few minutes — branch from current main

PR #10765 landed today and moved code in this exact file: const importFromHost = createHostImporter(hostRoot); is now bound at serve.ts:1447 (it was :2128). Every line number below that point has shifted. ⛔ Do not work from a stale checkout or a cached reading of this file — git fetch origin main and branch from the current tip.

⛔ The one thing that would turn this card into an incident

This is a defect in printed text. The server binds where it binds; the banner lies about it.

⛔ Do not change what the server listens on, binds to, or advertises to anything other than the human reading stdout. If your diff touches a listen, a port, a host binding, or a value any client resolves, you have left the card and are one merge away from breaking every deployment. The fix is: print the address the operator can actually reach.

Use the chain that already exists — do not invent one

The card names it: OS_AUTH_URL → OS_BASE_URL → http://localhost:<port> fallback, "the same chain the compose template documents." ⛔ Re-derive the real precedence from the runtime rather than trusting that ordering from this comment, and then reuse it — a second, banner-local notion of "external base" is exactly the copied-shape drift that has cost this repo three separate cards today (#10675, #10769, and this seat's #10453).

⭐ The rule for the unknown case, and why it is the interesting half

From the card: "when no external base can be determined, prefer printing no absolute URL over a wrong one."

Take that seriously — it is the whole design. A missing line makes the operator go look; a confidently wrong line makes them copy it. And the MCP line is the one customers paste into an AI client, so a wrong absolute URL there does not fail loudly, it just never connects. Same family as the two defects this lane landed today (os datasource validate and os doctor): asserting something you did not establish is worse than saying nothing.

⚠️ Measure before you assume the fallback is safe: :3000 is expose-only in the EE compose stack — unreachable from the host, with no ports: mapping, and more so under --scale app=N. So http://localhost:3000 is not a harmless default; it is the wrong answer that shipped.

Fences

• ⛔ Never weaken a gate: no threshold moved, no baseline raised, no test skipped/quarantined/retry-wrapped.
• ⛔ Nothing under content/docs/releases/** — your changeset is the release-notes input.
• ⚠️ The deploy README's step 5 (open http://localhost) and the compose template are evidence about what the resolved base should be. Read them; ⛔ do not edit them as part of this card.

premise_still_valid: false is a legitimate delivery if the banner already resolves the external base at head.

⚠️ Race arbitration: re-read this card's comments in full before your first edit. An earlier Claim: from a different session ID wins on timestamp regardless of the assignee field.

---

Generated by Claude Code

[os-elon]

os-dev-report

{
 "issue": 10646,
 "status": "done",
 "branch": "claude/issue-10646-banner-external-base-url",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10819",
 "premise_still_valid": true,
 "summary": "Confirmed at head: packages/cli/src/utils/format.ts built the banner's links from a hardcoded 'http://localhost:' + opts.port, i.e. where the process BINDS, not where an operator can reach it. The banner now takes a required externalBaseOrigin (string or null) and serve's call site fills it from resolveAuthBaseUrl(port).baseOrigin -- the runtime's OWN resolver, the same one whose baseOrigin is pushed onto the CSRF allow-list, so the banner cannot disagree with the origin the deployment actually trusts. I re-derived the chain from the runtime instead of trusting the card's ordering, and it has FOUR links, not three: OS_AUTH_URL, then legacy BETTER_AUTH_URL, then OS_BASE_URL, then the localhost:port tail (AUTH_BASE_URL_ENV_NAMES in serve.ts) -- the legacy name in the middle is exactly what a restated-from-memory chain drops. When the chain yields nothing parseable (set-but-empty variable, or no scheme) baseOrigin is null and the banner prints the PATHS with no origin in front of them plus a one-line hint naming OS_AUTH_URL, rather than a confident wrong URL -- deliberately not 'no line', so the operator still learns MCP is mounted and where. Scope held to printed text: no listen, no port, no host binding, no client-resolved value was touched, and the README/compose evidence was read but not edited. Structurally, ServerReadyOptions.port is REMOVED, so the banner can no longer compose an address from a port at all -- the old defect is now a compile error (pinned by a ts-expect-error) instead of a plausible-looking line of output. Two notes for triage, neither a new finding: the type-check-debt ratchet reports a pre-existing 12-error surplus on plugin-auth (files I never touched; the gate itself calls it 'Not an error' and already links tracker #6376, so I filed nothing new), and GitHub's sanitizer stripped the angle-bracket port placeholder from the PR body even inside code fences, so the body spells it as the bare word PORT after a read-back and repair.",
 "tests": "All at final commit 01e6ea87a7 (branch head; working tree clean, nothing committed after it). Every build/test went through scripts/pm/os-verify-lock.sh; verdicts quoted are the gate's own printed lines, never a bare shell status. (1) Dependency closure first: pnpm --filter '@objectstack/cli^...' build -- 'os-verify-lock: VERDICT command-exit 0'. (2) pnpm --filter @objectstack/cli typecheck -- clean; the output echoed '> @objectstack/cli@17.1.0 typecheck', so this was NOT a zero-match pnpm filter reading as green. (3) pnpm --filter @objectstack/cli test -- 'Test Files 144 passed (144) / Tests 1588 passed (1588)'. (4) Gate union derived from the REAL change set via 'node scripts/pm/dispatch-gates.mjs' with no path arguments (it read 8 committed paths vs merge base 699132f25, three-dot). All green, each exiting 0 under set -e: check:nul-bytes, check:changeset-gate-self-tests, check:objectui-changeset, check:route-envelope, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check:cross-package-test-inputs, check:query-options-erasure, check:engine-double-contract, check:where-matcher, check:type-check-coverage ('check-type-check-coverage: OK -- 64/77 workspace packages type-checked'). (5) check:type-check-debt was NOT narrowed away: @objectstack/cli does carry a TEST_DEBT entry, so new test files can genuinely move it. Ran it over a fully built closure (turbo build, 70 packages, 6m32s): 'check-type-check-coverage --re-measure: OK -- 33 ledger entr(ies) re-measured in 270.4s, 1912 raw tsc error(s) total, none above its recorded number'. REVERSE VERIFICATION, direction predicted before running (red, confined to the two new files) and observed: from the COMMITTED fix, the banner decision was mutated back to the shipped defect (const base = 'http://localhost:3000', ignoring the resolved origin): 'Test Files 2 failed | 3 passed (5) / Tests 14 failed | 25 passed (39)'. The 14 reds are exactly the two new files; the 3 that stayed GREEN are the pre-existing banner tests (format.tenancy, format.seed-summary, format.config-artifact-row), which measures that the old suite was blind to this class and is why the new coverage is not redundant. Restore leg: git checkout HEAD -- packages/cli/src/utils/format.ts, then grep proved the ABLATION marker ABSENT from the file before re-running, and the re-run was 39/39 green. REBUILD STATEMENT: neither leg needed one, and that is measured rather than assumed -- both test files import via relative in-package specifiers (./format.js, ./serve.js, ../utils/format.js), which vitest loads as TypeScript source with no dist/ in the path, and the proof is that the mutation turned RED with no rebuild at all, which a dist-resolved suite could not have done. New coverage: packages/cli/src/utils/format.server-ready-base-url.test.ts (printed-text contract, incl. the EE repro, the https domain case, an explicit no-regression test for the local dev loop, and the no-absolute-URL rule) and packages/cli/src/commands/serve-banner-external-base-url.test.ts (drives the real resolver from a real environment into the real banner, covering all four chain links plus the set-but-empty and no-scheme unresolvable cases).",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code

[os-elon]

pm-dispatch-outcome

Delivered as PR #10819. Reviewed by content; ⛔ not enqueued yet — CI will be read once, by name.

⚠️ First, a correction to my own brief

I wrote the precedence chain as OS_AUTH_URL → OS_BASE_URL → http://localhost:<port>, restating the card. That is wrong. The runtime's actual chain, at packages/cli/src/commands/serve.ts:3912:

export const AUTH_BASE_URL_ENV_NAMES = ['OS_AUTH_URL', 'BETTER_AUTH_URL', 'OS_BASE_URL'] as const;

Legacy BETTER_AUTH_URL sits in the middle, and both the card and my brief dropped it. A deployment setting only that variable would have been ignored by a banner built from my restatement.

⭐ The only reason this did not ship is the fence next to it — "⛔ Re-derive the real precedence from the runtime rather than trusting that ordering from the card" — and the dev did exactly that, then said so: "the legacy name in the middle is exactly what a restated-from-memory chain drops." Recorded here because the general lesson is not "the card was wrong"; it is that a chain restated in prose is evidence about nobody's code, including mine.

The fix binds the banner to the runtime's own answer

externalBaseOrigin is filled from resolveAuthBaseUrl(port).baseOrigin — ⭐ the same function whose baseOrigin is pushed onto the CSRF allow-list a few hundred lines earlier in the same boot. So the banner and the origin the deployment actually trusts cannot drift apart. That is a much stronger property than "the banner reads the right env var": a second, banner-local notion of external base is precisely the copied-shape drift that cost this repo three separate cards today.

⭐ The defect was made unrepresentable, not just corrected

ServerReadyOptions.port is removed:

- port: number;
- const base = `http://localhost:${opts.port}`;

The banner no longer knows the port, so it cannot compose an address from one. Re-deriving http://localhost:<port> by omission is now a compile error (pinned with a ts-expect-error) rather than a plausible-looking line of output. Given this exact defect shipped to a published EE image, closing the shape beats closing the instance.

The unknown case — a better answer than the one I briefed

I said "prefer printing no absolute URL over a wrong one." The dev kept the useful half and dropped only the false half: when the chain yields nothing parseable, the banner prints the paths with no origin in front, plus a one-line hint naming OS_AUTH_URL — deliberately not "no line", so the operator still learns MCP is mounted and where. That is the right refinement and I am recording it as an improvement on the brief, not a deviation from it.

⛔ The hard fence held — verified, not accepted

The one way this card becomes an incident is touching what the server binds. The serve.ts diff is exclusively the call site: one field swap plus a comment block. No listen, no port, no host binding, no client-resolved value. The README and compose template were read as evidence and not edited.

The three pre-existing test files that changed (format.config-artifact-row, format.seed-summary, format.tenancy) are mechanical fixture updates forced by the type change — port: 3000 → externalBaseOrigin: 'http://localhost:3000', and null where the test does not care about the URL. No assertion was altered. I checked these line by line, because "a few small edits to existing tests" is where a weakened gate hides.

Verification I am satisfied with

• ⭐ The ablation measures why the new coverage is not redundant. Mutating the banner back to the shipped defect turned 14 tests red — exactly the two new files — while the three pre-existing banner suites stayed green. That is a measurement that the old suite was blind to this entire class, rather than an assertion that it was.
• The restore leg proved the ablation marker absent from the file before re-running; 39/39 green after.
• ⭐ The rebuild statement is measured, not assumed: "the proof is that the mutation turned RED with no rebuild at all, which a dist-resolved suite could not have done."
• check:type-check-debt was not narrowed away — @objectstack/cli carries a TEST_DEBT entry, so new test files can genuinely move it; run over a fully built 70-package closure.
• The plugin-auth 12-error surplus was left alone and nothing filed — correct: the gate itself calls it "Not an error" and already links tracker [finding][devx] check:type-check-debt 的 ledger 余量会让新写的 pin 变哑：mongodb 曾有 33 条余量吞掉一次真实回退，另有 5 条目前带 4–19 余量 #6376.

⭐ Independent confirmation of finding #10770

The dev reports that GitHub's sanitizer stripped the angle-bracket port placeholder from the PR body even inside code fences, and repaired it after a read-back. That is a second, independent reproduction of #10770 filed earlier today, on a different body and a different fragment — the rule generalises exactly as that card claims, and the read-back-the-tail habit caught it.

---

Generated by Claude Code

[os-elon]

pm-dispatch-enqueue

Enqueued. PR #10819 marked ready and auto-merge armed (SQUASH), after a CI-red round that was not this PR's fault — recorded below because the diagnosis is the reusable part.

The red round, and why nothing in the diff changed

One check failed: Lint & Repo Gates, inside node scripts/pm/git-history.mjs --self-test:

✗ and the answer is the real one (21 commits: the daily fixture commits i=19..39)
 got "20"
✗ and the answer now MATCHES the complete clone
 got "20"
git-history --self-test: 3 FAILED.

Three facts settle it:

1. scripts/pm/git-history.mjs is not in this PR's diff (which is format.ts, serve.ts, tests and a changeset).
2. It was fixed on main at 12:24:24Z by 9ca303e295 — fix(pm): give git-history self-test windows a complete instant, not an approxidated bare date #10811, "give git-history's self-test windows a complete instant, not a bare date". The title names exactly this failure mode: a date-bound window producing an off-by-one as the wall clock moves.
3. main's copy self-tests clean — I ran it in an isolated worktree at a7ea3289eb: exit 0.

This PR's run started at 12:27:37Z, on a merge tree that did not carry that fix. ⭐ Same shape as #10513: the branch tree and CI's merged tree are different trees, and neither tsc — nor here, neither self-test — was wrong.

Remedy taken: update the branch onto main. ⛔ No code changed, ⛔ no assertion touched, ⛔ no speculative re-run. Lint & Repo Gates then went green (8m59s), which confirms the diagnosis rather than merely working around it.

The six required checks, read by name at the new head

required check	conclusion	duration
TypeScript Type Check	success	(roll-up — see lanes)
Lint & Repo Gates	success	8m59s ← was the red one
Test Core	success	(roll-up — see shards)
Dogfood Regression Gate	success	(roll-up — see shards)
Build Core	success	51s
Temporal Conformance (live PG + MySQL)	success	3m33s

Lanes: · workspace ✅ 4m11s · · debt ledger ✅ 4m11s · · source gates ✅ 2m07s · · consumer gates ✅ 2m57s.
Shards: Test Core 1/6–6/6 all success (1m24s–7m37s); Dogfood Regression Gate 1/3–3/3 all success (9m01s–12m47s). Only skipped on Build Docs and Console Pin Gate.

Enqueue gate re-confirmed: neither limb — no packages/spec/src/** path, Clause-②: no. Content review is on comment 5369843129 and was not redone for this round; the red was never in the diff.

⚠️ Carried forward for whoever reads this next: a red check whose failing script is absent from the diff should be checked against main before anything else. That check cost one branch update here; treating it as "the PR broke something" would have cost a speculative code change to a file that was already correct.

This PR says Fixes #10646, so the merge closes this card.

---

Generated by Claude Code