feat: compile route-graph IR and inspect focus (#93)

[ScriptedAlchemy]

Towards #93. Refs #107 and #105.

Wave 1 Lane B PR-1: the conventional route tree compiles into one immutable route-graph IR. This PR is consumer-invisible — discovery attaches nothing for route-free projects, packaging is unchanged, and the route config extractor follows in PR-2 (so Fixes #93 deliberately does not apply yet).

Route compiler (packages/agent-bundle/src/routes/)

• graph.ts compiles the conventional roots with the same glob discipline as config/discover.ts (absolute, cwd, dot, followSymbolicLinks: false, onlyFiles):
  • MCP: src/mcp/<server>/{tools,resources,prompts,apps}/*.{ts,tsx} (direct children per kind), ids tool:<server>/<name> etc., serverId: mcp:<server>.
  • Events: src/events/<family>/*.{ts,tsx} → event:<family>/<name>.
  • Providers: src/providers/*.{ts,tsx} as a separate CompiledProvider collection, not a route kind.
  • CLI/scripts: src/cli/** and src/scripts/** with nested identity (cli:library/audit).
  • Project ignore rules, private _/. segments, and *.d.ts files are skipped.
• The conventional-entry probe is a documented local copy: importing config/normalize.ts would close the cycle discover.ts → routes/graph.ts → normalize.ts → discover.ts.
• The graph is deep-frozen, every route carries the shared frozen config: {} (emptyRouteConfig), and digest covers project-relative identity only, so equal trees hash equally on every machine.
• Collision errors — the compiler never chooses silently:
  • AB4800 routed server vs src/mcp/<id>.ts or a declared entry/command/url;
  • AB4801 src/cli.ts vs src/cli/;
  • AB4802 duplicate route id;
  • AB4803 unsafe identity segment (^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$ per segment);
  • AB4804 invalid routes mode override.
• Power-tier overrides ride the config index signature (types.ts unchanged): routes.servers.<id> = 'generated'|'custom'|'command'|'remote', routes.cli = 'generated'|'conventional'. Explicit custom/command/remote omits that server's routes; explicit generated keeps them and is never an error against leftover files. A conflict without a mode keeps the discovered routes in conflict mode and errors — discovery is not a packaging choice.
• types.ts defines CompiledAgentRoute, RouteProvenance, CapabilityState/CapabilityEvidence (exported, not populated — Compile capability-aware host component bundles #100), CompiledProvider, CompiledServerSurface (generated|custom|command|remote|conflict), CompiledCliSurface, CompiledRouteGraph, and emptyRouteConfig.
• inspect.ts is the dump facade (RouteGraphInspection = CompiledRouteGraph), index.ts re-exports.

Wiring (additive)

• config/discover.ts: discoverProject compiles the graph and spreads routeGraph only when isEmptyRouteGraph is false.
• config/validate.ts: validateSource appends discovered.routeGraph?.diagnostics ?? [], so route collisions hard-fail inspect/build.
• api.ts: focus?: 'bundler'|'hooks'|'routes'|'skills'; on focus === 'routes' it runs loadConfig + compileRouteGraph + inspectRouteGraph into selected.routes; routes surface re-exported from the advanced API.
• cli.ts: inspect --routes with the existing at-most-one-focus rule; the human writer dumps the graph JSON like the bundler focus.

Lane D riding this PR

• docs/superpowers/specs/2026-08-26-…-parity-design.md: the filesystem-router non-goal is marked superseded (2026-08-31) by Compile filesystem routes into the Agent Bundle meta-framework #93; public authoring waits for the wave-3 renderer join (meta-framework: execution plan and sequencing #107); the rest of the non-goals are unchanged.
• docs/superpowers/specs/2026-08-25-capability-aware-workbench-design.md: status note that the nine-page Workbench is in tree, remaining work is tracked in Add an interactive Agent Workbench with local host discovery and lifecycle replay #105, and the spec is not the live execution plan (Status: proposed left as-is).
• docs/diagnostics.md: new AB4800–AB4804 table.

Tests

packages/agent-bundle/tests/route-graph.test.ts (unit pool, mkdtemp fixtures, not added to rstest.integration-tests.ts): 12 cases covering conventional discovery (frozen IR, machine-independent digest, config: {}), skip rules, all five diagnostic codes, generated/custom override behavior, the missing routeGraph key on skill-only projects, the routes inspect focus, and the in-process CLI --routes --json dump plus the ambiguous-focus rejection.

Verified locally: unit pool 1793 passed / 0 failed (includes the 12 new cases), rslint clean, tsc typecheck clean.

Do not merge.

  

[changeset-bot]

🦋 Changeset detected

Latest commit: 6654dcc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agent-bundle	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-01T01:19:31.731395Z	d4e22a5	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d4e22a52f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[ScriptedAlchemy]

Deslop/simplify audit (orchestrated): reviewed this PR's full diff against the deslop rubric. No commits pushed — the branch head is untouched for the lander's exact-head gate; findings only. One item worth folding in before merge, three post-merge cleanups. Everything else checked clean: the conventional-entry probe copy is properly documented with its cycle rationale, CapabilityState/CapabilityEvidence are exported types only (no dead runtime code, per the #107 stage plan), route diagnostics ride the existing validateSource plumbing, and the glob discipline matches config/discover.ts rather than reimplementing it.

Worth fixing before merge

1. src/routes/graph.ts:295-303 — the local deepFreeze reimplements the shared deepFreeze already exported from src/core/freeze.ts (added in 122e0b5 exactly to end these copies). graph.ts already imports from core/ (diagnostics, digest, strict-json, types) and core/freeze.ts imports nothing, so import { deepFreeze } from '../core/freeze.ts' is cycle-free — unlike the documented conventionalEntryAt copy, this duplication has no cycle justification. Behavior is equivalent for the fresh plain-object IR (the shared version is additionally cycle-safe and symbol-aware). Net −9 lines. (config/normalize.ts:585 carries the same pre-existing local copy this was likely pasted from; unifying that one is out of scope for this PR.)

Post-merge cleanup

2. src/routes/graph.ts:175 — configClaimedSources is exported but nothing outside graph.ts consumes it (not api.ts, not routes/index.ts, not the tests). Drop the export keyword until PR-2 actually needs it, or re-export it from the barrel deliberately.
3. src/dev/project-service.ts:751-767 — appending routeGraph as the 16th positional parameter of preparedProject forces the invalid-source call site to pass five consecutive undefined placeholders. The parameter train predates this PR, but it has now crossed the readability threshold; an options-object signature would make both call sites self-describing.
4. src/api.ts:12-13 — two consecutive export {…} from './routes/graph.ts' statements; fold into one.

Not flagged (checked, judged deliberate): the inspectRouteGraph identity facade with the RouteGraphInspection alias (documented contract-stability seam), the currently unconsumed routes/index.ts barrel (matches the consumed config/dev/eval barrel convention, though public-api.test.ts does not cover the new barrel), and the try/catch in the entry probe (faithful to the normalize.ts original it documents copying).

[ScriptedAlchemy]

Deslop audit triage (Lane B lander):

• Item 1 (local deepFreeze) — fixed in 055b004: graph.ts now imports the shared cycle-safe deepFreeze from core/freeze.ts; the local copy is deleted.
• Item 4 (duplicate api.ts re-export) — folded into one statement in the same commit (trivial, and a push was happening anyway).
• Item 2 (configClaimedSources export) — acknowledged, deliberately left exported: PR-2 (the static config-export extractor) builds directly on this seam; will re-export it from the barrel there or drop the keyword if plans change.
• Item 3 (preparedProject positional train) — acknowledged as post-merge cleanup; the train predates this PR and an options-object refactor touches call sites beyond this diff, so it stays out of the exact-head gate.

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@119

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@119

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/rsc-runtime@119

commit: d9a2bb0