[blove]

Follow-up to #701.

Problem

#701 added B4_E1007 for a route index.ts that exports nothing B4.run recognises, but the throw happens inside the recursive walkRouteTree. An app with several miswired route entries surfaces them one per run: the user fixes one, re-runs, meets the next.

That is inconsistent with this repo's own convention for b4 check diagnostics, which deliberately batch — the edge-capability gate in packages/cli/src/commands/check.ts reports every offending config key and file at once as B4_E1005, and marker-files.ts names every oversized marker file across all routes in one failed build.

Change

packages/core/src/discovery/discover-routes.ts:

• readRouteEntry no longer throws. It returns a RouteEntryScan — { route }, { unrecognised }, or neither — mirroring the scanRouteMarkerFiles shape that collects findings without throwing so a caller can aggregate them.
• walkRouteTree threads an unrecognised[] accumulator alongside discovered[].
• collectRouteDefinitions throws once at the end, before the collision check.
• New explainUnrecognisedRouteEntries builds the message. One entry returns its existing message byte-for-byte, so the single-file UX and every current assertion are untouched; several are bulleted with their per-entry explanations indented underneath. Order is walk order, which is stable because readdir is already sorted.

The B4_E1007 code and the per-file message from explainUnrecognisedRouteExports are unchanged.

Rendered from the built CLI path:

2 route entries have no recognisable export:
  • Route entry /…/src/app/other/index.ts has no recognisable export (found: unrelated).
    A route index.ts must export a default export of `agent(...)`, or exactly one of "agent", "workflow", "graph", or "chain".
    If this directory is not a route, prefix its name with "_" to keep it out of route discovery.
  • Route entry /…/src/app/util/index.ts has no recognisable export (found: helper).
    A route index.ts must export a default export of `agent(...)`, or exactly one of "agent", "workflow", "graph", or "chain".
    If this directory is not a route, prefix its name with "_" to keep it out of route discovery.

Tests

New case in packages/core/test/discover-routes.test.ts with two bad route entries, asserting both paths and both export names appear in one B4AppError carrying B4_E1007.

Docs and #701's changeset get a sentence each — the batching is part of the same unreleased behaviour, so it does not warrant a second changeset.

Verification

Gate	Result
@b4run/core tests	47 files, 542 passed (discover-routes.test.ts 18/18)
@b4run/cli tests	160 files, 1820 passed, 4 skipped — includes check-command.test.ts 12/12 with the built-CLI subprocess test
@b4run/sdk tests	111 passed
@b4run/web tests	631 passed
pnpm lint / pnpm typecheck	28 / 53 tasks green

Editing cli.mdx staled lastmod.generated.json; regenerated with --as-of 2026-09-17.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
b4-run	Ready	Preview	Sep 17, 2026 8:00pm UTC

[github-actions]

Automated approval: this PR received an intelligent (AI) code review. See the review comments on this PR.