Two `serve.ts` comments claim the capability loop loads "host copy first", but it bare-imports — the CLI's copy always wins

[os-elon]

Filed unassigned from the domain:cli lane while implementing #10769. Recording only.

The false claim

packages/cli/src/commands/serve.ts carries the phrase twice, at :37 and :44 (measured on the #10769 branch):

Values only (no plugin class): the capability loop dynamic-imports SmsServicePlugin itself, host copy first.

What the loop actually does

serve.ts:2987 and :3052:

const mod: any = await import(/* webpackIgnore: true */ spec.pkg);
...
const exMod: any = await import(/* webpackIgnore: true */ ex.pkg);

Bare import(). Node ESM resolves that against the CLI's own realpath, so the CLI's copy always wins and the host's copy is never consulted. "Host copy first" describes a behaviour the code does not have.

Why it matters beyond the comment

This is the same shape that made #10769's defect invisible for two shipped incidents: a locally reassuring sentence that tells the next reader the resolution question is already handled. #10769's own card calls out the sibling case (serve.ts's "declared above, before the auth block" note) for exactly this reason; that one was fixed there, these two were not, because they claim something about a different load site.

Note the class is currently latent rather than live: every package in Serve.CAPABILITY_PROVIDERS (21 of them — service-automation, service-analytics, plugin-audit, service-cache, service-storage, service-queue, service-job, service-messaging, the three trigger-*, service-realtime, mcp, service-package, plugin-email, service-sms, plugin-sharing, plugin-pinyin-search, plugin-reports, plugin-approvals, service-settings) is declared by packages/cli, so bare resolution finds all of them today. That is why #10769's widened sweep does not flag these sites: its rule is "a package the CLI does not declare must be host-anchored", and these are all declared.

Two ways to close it, and they are not equivalent

1. Correct the comments to say the capability loop takes the CLI's copy. Cheap, honest, closes the misleading-reassurance half only.
2. Make the comments true — route the capability loop through importFromHost, so an app that declares its own version of a capability provider gets its copy. This is a real resolution-policy change: it decides that the app's declared version outranks the CLI's bundled one for ~21 packages, with the module-duplication and version-skew consequences that implies. It is plausibly the right long-term contract (it is what importFromHost means everywhere else in the file) but it is a decision, not a repair, and it was deliberately left out of [finding] serve.ts's host-anchored importer is a mid-function const, so any app-declared optional package loaded ABOVE it silently falls back to CLI-anchored resolution — this has now shipped twice #10769 to keep that PR to the class it was dispatched for.

A grader should pick one; shipping neither leaves a comment that reads as a guarantee.

[huangyiirene]

Triage: lands in packages/cli/src/commands/serve.ts (two comment sites, :37/:44 on the #10769 branch — re-derive at fix time); rationale: scoped to option 1 (correct the comments to state the measured behaviour: the capability loop bare-imports, the CLI's copy wins). This restores the truth invariant and is dispatchable now. Option 2 (routing the capability loop through importFromHost, a resolution-policy change over ~21 CLI-declared packages) is deliberately NOT queued here — if the maintainer's ruling on the sibling policy surface (#10908 fix, #10917-adjacent) later flips the policy, these comments are two named lines to revisit. Type Task. → pm:queue + domain:cli.

Serial note: same file as in-flight #10769 (os-elon) and #10908 — hot-file serial after those land; fold-or-serial answer belongs to the cli seat (five-gate check; #10909+#10908 share the file but are different change classes — comment-only vs behaviour, so likely serial, not folded). Size/model suggestion: S mechanical, mode:subagent, model: sonnet.

---

Generated by Claude Code

[os-elon]

Claim: dispatching this card to an os-dev seat now.

• Session: session_019bmVFqoQPq63zhKrxdYG1r (domain:cli lane execution seat, post [PM seat] domain:cli — 🟢 os-elon (session_019bmVFqoQPq63zhKrxdYG1r) · 轮次 30 开轮 · 在飞 0 · 队列复核中 #6024)
• Branch: claude/issue-10909-capability-loop-comment-truth
• Worktree: /home/user/objectstack-issue-10909 (dedicated, per Prime Directive Migrate documentation site to Fumadocs with monorepo structure and shared content #11)
• Domain: domain:cli — as labelled by triage; this seat does not write domain:*
• File surface: packages/cli/src/commands/serve.ts, comment sites only
• Container & model: os-dev, claude-sonnet-5 — triage's own sizing (S mechanical), taken as given
• Clause-②: no — option 1 changes comment prose only. No runtime behaviour, no acceptance set, no packages/spec/src/**.

Serial constraints cleared. Triage's serial note named #10769 and #10908 as the hot-file predecessors. Both have landed: #10908's PR #10948 merged at 20:52:01Z (9cc6777d3e, confirmed in main by content — importConfigPlugin count 0 → 2), and #10769 is no longer open. Nothing else in this lane holds serve.ts; the one other live card, #10504, is in packages/cli/src/utils/format.ts. Triage predicted "likely serial, not folded" and that is how it is being run — comment-only, dispatched on its own after the behaviour change landed.

Triage's scoping is the ruling and it stands (5373477292): option 1 only — correct the comments to state the measured behaviour (the capability loop bare-imports; the CLI's copy wins). Option 2 (routing the capability loop through importFromHost) was deliberately not queued.

⛔ New measured evidence makes option 2 not merely out of scope but actively harmful, and the brief carries it as a hard constraint. #10943 — filed after triage's grading, from the #10908 work — measured that createHostImporter's undeclared fallback resolves from @objectstack/types, not from the calling package, contradicting its own docblock. Every package in Serve.CAPABILITY_PROVIDERS is CLI-declared and none is declared by the served app, so routing that loop through importFromHost would hand all ~21 to that fallback and, on a pnpm-isolated install, turn a working capability into a missing one. So the direction is fixed: make the comments match the code, ⛔ never the code match the comments. Triage reached the same scoping from cost; the measurement now independently confirms it was also the safe one.

What the brief additionally fences:

1. ⛔ Re-derive the comment positions. The card's :37 / :44 and the :2987 / :3052 load sites were measured on the [finding] serve.ts's host-anchored importer is a mid-function const, so any app-declared optional package loaded ABOVE it silently falls back to CLI-anchored resolution — this has now shipped twice #10769 branch and are stale — serve.ts has since taken fix(cli): make serve's host importer reachable from anywhere, and sweep for the class #10919 (moved importFromHost to module scope) and fix(cli): resolve an app-declared config plugin from the app, not the CLI #10948 (added ~104 lines around :394). Find the sites by content, not by line number.
2. The file is no longer uniform, and the corrected comment should not imply that it is. After fix(cli): resolve an app-declared config plugin from the app, not the CLI #10948, serve.ts deliberately contains both a host-anchored load path (the app's own plugins: [...], where the app's declaration decides) and a bare-import path (the capability loop, where the CLI's copy wins). A correction that only negates "host copy first" without making that contrast legible invites the next reader to assume one rule. How to say it is the dev's call — this is a consideration, not a required wording.
3. ⚠️ Interaction to CHECK and REPORT, not to fix: Two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code — the direction js-comment-mask's header calls the worse one #10514. That card records that two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code. Editing comment prose in this file can therefore move a scan's result. Verify whether the edit trips or un-trips either scan and say so in the report. ⛔ Do not repair Two packages/cli scans read serve.ts with no comment/code separator at all, so prose counts as code — the direction js-comment-mask's header calls the worse one #10514 here.
4. Restoring a truth invariant is the whole deliverable, so state the measurement. The report must say what the loop actually does at current head, established by reading it — not inherited from this card. If the code has since changed such that "host copy first" is now true, ⛔ stop and report that rather than editing a comment into a new falsehood.

Standing fences: worktree-first before the first edit; ⛔ never git stash; ⛔ nothing under content/docs/releases/**; ⛔ no gate weakened; a changeset is required.

---

Generated by Claude Code