docs(solutions): gateway image packaging crash-loop learning

[marcusrbrown]

Captures the root cause and fix for the gateway Docker image crash-loop (ERR_MODULE_NOT_FOUND for @fro-bot/runtime) as a searchable solution doc under docs/solutions/build-errors/.

The learning covers: why externalizing a workspace package whose published entry points at uncompiled src/ breaks a deployable image, why host-checkout tests can't catch it, the noExternal inlining fix, and the CI image build+boot smoke that guards the regression class going forward. Cross-linked with the versioned-tool and tool-binary-caching solution docs.

[fro-bot]

Verdict: PASS

Documentation-only PR adding a solution learning doc under docs/solutions/build-errors/. I verified every technical claim against the live codebase and all cross-links resolve. The learning is accurate, well-scoped, and captures a genuinely non-obvious failure class (workspace package externalized but pointing at uncompiled src/, invisible to host-checkout tests).

Verification performed:

• packages/gateway/tsdown.config.ts — noExternal predicate matches the doc snippet exactly (exact-or-subpath match for @fro-bot/runtime).
• Root tsdown.config.ts:223 — confirms the action tier inlines @fro-bot/runtime, matching the "mirrors the action tier" claim.
• .github/workflows/ci.yaml:231-274 (gateway-smoke job) — build-time grep invariant, image build, boot smoke with 60s timeout, exit-124 hang guard, DISCORD_TOKEN config-load assertion, and ERR_MODULE_NOT_FOUND regression check all present as described.
• Both cross-linked docs exist at the given relative paths.

Blocking issues

None.

Non-blocking concerns

• Line 88 (smoke snippet) is not faithful to the actual CI logic. The doc shows:

  echo "$output" | grep -q "ERR_MODULE_NOT_FOUND" && { echo "REGRESSION: module resolution failed"; exit 1; } || true

  The real workflow (ci.yaml:270-273) uses a plain if ... grep -q ...; then ... exit 1; fi with no trailing || true. The || true in the doc would neutralize the exit 1, making a copy-paste of the snippet a silent no-op that defeats the regression guard. Since solution docs are meant to be reference material, consider matching the real if form (or dropping || true) so a future reader doesn't copy a defanged check.
• Minor: line 84's snippet sets status=$? immediately after the assignment, which under set -e would capture the assignment's status rather than docker run's; the real workflow correctly wraps this in set +e/set -e. Not worth blocking, but the abbreviated snippet omits that nuance.

Missing tests

None — documentation change, no executable behavior. The regression guard this doc describes is itself the test, and it already exists in ci.yaml.

Risk assessment (LOW): docs-only change, single new file, no code paths touched. Zero regression or security exposure; blast radius limited to the docs tree.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	26706929696
Cache	hit
Session	ses_182fc9113ffe73pzMozaM36cBe