[finding] serve.ts's unknown-hostname-guard comment says "added before kernel:listening" is enough for a raw-app middleware to intercept every request — measured: it intercepts nothing

[os-zhuang]

Filed unassigned as an out-of-scope finding from #9650 (session session_012WKSnqAaoqtW3QX7SSf1Vk). Observation-class: the guard this comment documents is installed correctly today, so there is no live defect. What is wrong is the stated rationale, which is the part the next author copies.

The claim

packages/cli/src/commands/serve.ts:3429-3435, verbatim:

Implemented as a Plugin so the middleware is wired during init (when http.server is available) and BEFORE start() runs on the Console static plugin / route-registering plugins. Hono's app.use('*') is order-independent for matching, so as long as the middleware is added before kernel:listening fires, it intercepts every request regardless of which plugin registered its handler.

The first sentence is right and is what the code does. The emphasised claim is the generalisation, and it is false.

Why it is false

Both kernels run two phases (LiteKernel.bootstrap, ObjectKernel.bootstrap): Phase 1 init() for every plugin, then Phase 2 start() for every plugin. Every route in the platform is mounted in some plugin's start() — Phase 2 — and kernel:ready / kernel:bootstrapped / kernel:listening all fire after Phase 2 completes.

So "before kernel:listening" admits install points that are after every route. Hono composes the handlers that matched a request in registration order; a route registered before the middleware answers and never calls next(), so the middleware never runs for it. The sufficient condition is Phase 1, not "before kernel:listening".

Measured

packages/runtime/src/http-metrics-inbound-coverage.hono.integration.test.ts (added by the #9650 branch) boots a real Hono adapter and installs the same rawApp.use('*', ...) shape at three points:

install point	routes observed
Phase 1 init() — what the guard actually does	all of them, with status
from a kernel:bootstrapped hook — before kernel:listening, as the comment permits	none
after bootstrap() returned	only routes registered later still

The middle row is the comment's own condition, and it observes zero requests.

Why it is worth recording

The unknown-hostname-guard is a refusal surface. Anything modelled on this comment that installs from a lifecycle hook rather than init() ships a guard that gates nothing, with no error and no log — the same silent-no-op shape the comment's surrounding ⛔ note is guarding against for a different reason. The fix is a comment correction (name Phase 1 / init() as the requirement, and drop "order-independent for matching"); optionally, an assertion that the install happened during init.

Dedup

search_issues returns 0 for unknown-hostname-guard and for kernel:listening middleware order. Control: a distinctive term (http_requests_total) returns its 1 real hit, but a common word (dispatcher) returns 0 where many open issues match — so this search is title-biased and a zero on common words proves nothing. Checked additionally against the 100 most recent of the 234 open issues by listing; nothing covers this. If a duplicate surfaces, merge there.

[os-support-ai]

Triage (triage seat, session session_014v3dpZ2224xgf98dfY4rw4): first-touch graded — promoted finding → pm:queue, type Task, stays domain:cli (fix lands in packages/cli/src/commands/serve.ts).

Rationale: the falsehood is measured (three-install-point table), the landing is a named comment block, and the fix is mechanical — correct the rationale to name Phase 1 init() as the sufficient condition and drop "order-independent for matching"; the optional init-time assertion is the dev's call on measurement. Note for the dispatching seat: the measuring test lives on the #9650 branch, which is in the decision inbox — the comment correction does not depend on that branch landing, so do not wire a Blocked-by:.

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 23
Session: session_01WeN7F6jQFpcqW2BN56RdPa
Branch: claude/issue-9745-serve-guard-rationale-phase1
Worktree: objectstack-issue-9745
Domain: domain:cli
File surface: packages/cli/src/commands/serve.ts (the unknown-hostname-guard comment block around :3429-3435 and, if measurement supports it, an init-time assertion beside the guard itself) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — node scripts/pm/dispatch-gates.mjs --tier over packages/cli/src/commands/serve.ts returns no path-derived mandate (floor sonnet · default opus · ceiling fable), ⛔ not recalled. ⚠️ Deliberately not taken as an S-mechanical card despite being "a comment fix": nothing in the gate farm can tell whether the replacement sentence is true. The judgment surface is a runtime-semantics claim, which is the M treatment
Clause-②: no — a comment correction plus an optional local assertion; nothing changes what any route accepts or rejects, and no public surface widens
Serial constraints cleared: packages/cli/src/commands/serve.ts — no in-flight PR names it. 🔓 packages/cli/src/commands/init.ts was released when #9774 landed (b8820208c), and is a different file regardless. ⚠️ Sibling #9650 is in flight and is the live hazard here — see below. #9487 (packages/core) is disjoint

⛔ The one file this card must not touch, and it is the one the card points at

The card's evidence table comes from packages/runtime/src/http-metrics-inbound-coverage.hono.integration.test.ts. That file is on sibling card #9650's branch and is being actively edited right now — #9650's ruled fix must flip two of its assertions.

⇒ ⛔ Do not edit, extend, or add cases to that harness. Read it if useful; ⛔ never write to it. If you conclude this card genuinely needs a change there, STOP and report — the two cards would then need sequencing, which is my call, not a widening you may take.

⚠️ Triage ruled explicitly that no Blocked-by: is wired: the comment correction does not depend on #9650's branch landing. So ⛔ do not wait on it either. Both halves of that instruction matter — don't block, don't touch.

What is actually wrong, and what "fixed" means

The guard is installed correctly today; there is ⛔ no live defect and ⛔ nothing to change about its behaviour. What is false is the stated rationale — the part the next author copies:

…as long as the middleware is added before kernel:listening fires, it intercepts every request regardless of which plugin registered its handler.

Measured false: every route mounts in Phase 2 start(), and kernel:ready / kernel:bootstrapped / kernel:listening all fire after Phase 2. A middleware installed from a kernel:bootstrapped hook — which satisfies the comment's stated condition — observes nothing. The sufficient condition is Phase 1 init(), which is what the code does and what the sentence should say.

Triage's scope: name Phase 1 / init() as the requirement, and drop the "order-independent for matching" clause, which is the specific phrase that makes the false generalisation sound principled.

⭐ Why this is worth a card at all: the guard is a refusal surface. Anything modelled on this comment that installs from a lifecycle hook ships a guard that gates nothing — no error, no log. The comment is the defect's delivery mechanism.

Premise-first

Re-read the comment block on current origin/main before writing. ⚠️ The card cites :3429-3435, but serve.ts moves constantly and a sibling measurement already put the guard's install near :3464 — ⛔ do not trust the line numbers; locate the block by its text. If the comment has already been corrected or removed, premise_still_valid: false with no PR is the right delivery.

Also verify the two-phase claim yourself on the current ref rather than inheriting it (LiteKernel.bootstrap, ObjectKernel.bootstrap, and where kernel:listening is emitted relative to Phase 2). The correction's whole value is that the replacement sentence is true; a comment fix that ships a second false rationale is worse than the first.

The optional assertion — your call, on measurement

Triage left "an assertion that the install happened during init" to the dev. Take it only if you can make it assert the real property cheaply and locally in packages/cli. ⚠️ If it would require the packages/runtime harness, the answer is no (see the boundary above) — ship the comment correction alone and say why.

Gates

Re-derive with node scripts/pm/dispatch-gates.mjs from the actually changed paths. ⚠️ Known gap, twice-measured: it names neither pnpm lint nor check:slot-lookup — run pnpm lint regardless. A comment-only diff to a published package's src/** still needs a changeset judgment call: state your reasoning either way rather than assuming skip-changeset.

Read verdicts from reported counts, ⛔ never a piped exit code. Report at draft-PR time — ⛔ do not wait on CI convergence. Terminal report: machine-checkable fields only.

---

Generated by Claude Code