feat(dev): PR 2a — execution parity, provenance, and honest telemetry for Workbench route invocations (#600)

[ScriptedAlchemy]

Part of #600 — PR 2a: execution parity + provenance. Lands the owner audit's P1-A/B/C + P2 items on the PR 1 execution bridge, plus the 19:56 addendum (request model, outcome vs. status, six acceptance fixtures). Acceptance list: #600 (comment). The live trace is PR 2b; host sessions PR 3. No new top-level destination; PR 1's page deletions stand.

What changes

Request model — canonical operation + selected surface. POST /api/routes/invocations takes { routeId, surface?, input? }. routeId is the canonical operation (tool:<server>/<tool>, event:tool/before, cli:<path>, script:<name>); surface selects how it runs: { kind: "mcp" }, { kind: "cli", command, args }, { kind: "event", host?, fixtureId? }, { kind: "script" }, or { kind: "unit-render" }. A tool with a #616 CLI projection is invoked through MCP or through that projection under the same operation id — no duplicate CLI operation (AB8253 mismatched command, AB8254 a projected cli: id used instead of the canonical id). Defaults follow the route kind; unit-render (live-source component preview via the route-unit harness, disposable state) is never a default and is recorded on the result as surface.

Production execution boundary (P1-B). Production surfaces execute the leased published epoch's compiled artifact along the path the generated entries take: the generated hook wrapper's prepareRouteInvocation (validation → canonical props → #618 preflight continue/deny/defer), the generated CLI bin's prepareRouteInvocation (argv, confirmation, .cli.ts mapInput, canonical validation) and its own exit-code decision, the epoch's Flight worker for tools/resources/prompts/rendered scripts (MCP input validated against the compiled inputSchema exactly as the generated server does), compiler aliases/defines, the operator .env layer applied once for every surface, AGENT_BUNDLE_PLUGIN_ROOT=<epoch> and AGENT_BUNDLE_STATE_ROOT=<project>/.agent-bundle/state — the #640 state-root contract, outside the epochs that retirement deletes and shared with the dev MCP session, so session state survives a republish. An event route with a compiled preflight rejects a hostless (canonical) submission with AB8255; the Workbench defaults such routes to the first lifecycle target.

Provenance (P1-C). RouteInvocationService.invoke() acquires the EpochStore lease inside the concurrency slot, revalidates digest/source revision, answers 409 AB8239 when the published revision moved while the request waited, and releases in finally. A request aborted while queued (browser closed the fetch) is removed from the queue and never leases or spawns.

Specifier repair (P1-A). route-module-loader.ts rewrites only real import/export … from/import() specifiers through the TypeScript AST when pointing a .js import at its .tsx source; a rendered string such as './panel.js' is untouched. build/module-imports.ts (#634) is not a dependency.

Telemetry (P2 + addendum). Provider and timing rows come only from what the worker measured: unmeasured phases are omitted, unobserved providers are unobserved, a preflight short-circuit reports no render duration. Execution status (succeeded = the boundary completed) is separate from the application outcome: success, represented-error (projected isError, non-success document, hook deny), or process-exit with the generated bin's exit code — in the envelope, the route.invocation project event, the route workspace, and Trace.

Diagnostics. AB8239, AB8250–AB8255 (docs/diagnostics.md). Docs en+zh: guide/development/workbench.mdx, reference/runtime-environment.mdx, MCP session page. Changeset: one patch for agent-bundle.

Acceptance fixtures (all six)

#	Fixture	Test
1	Preflight continue/deny with a throwing handler → handler never imported or run (marker files); defer → gate once, handler once, selected providers respected	tests/route-invocation-dev-server.test.ts
2	CLI projection renames flags + derives a required input in mapInput → same canonical input and confirmation behaviour as the generated bin (unconfirmed run fails the way the bin does; --yes proceeds)	same
3	Route with compiler alias + define + ./panel.js import + literal './panel.js' text → Workbench mcp projection equals the epoch's generated MCP server's tools/call result byte-for-byte (stableJson)	same + tests/route-unit/route-module-loader.test.ts
4	Two stateful calls → session preserves across a republish (new epoch); unit-render resets	same
5	Slots full, enqueue, republish changed source, release → old epoch's old output or AB8239; abort while queued → no lease, no child	tests/route-invocation-service.test.ts
6	Represented error, non-zero exit, unobserved provider visible in the route workspace at 1440×900 (examples/audiobook-curator, real fixture data, never accepted while loading)	packages/workbench/tests/audiobook-curator.acceptance.e2e.test.ts

Gates (local merge gate, AGENTS.md #662)

Branch contains origin/main at 461a6dc5c9 (#659). Commands, run at the head sha f1eba9ce29 in this order, results:

pnpm build                       # ok
pnpm typecheck                   # ok
pnpm lint                        # success, 1429 files, 88 rules
pnpm test:unit                   # 4242 passed, 0 failed (283 files)
pnpm test:route-unit             # 89 passed
AGENT_BUNDLE_WORKBENCH_PREBUILT=1 AGENT_BUNDLE_PACKAGE_PREBUILT=1 pnpm exec rstest --config rstest.integration.config.ts \
  packages/agent-bundle/tests/mcp-session-service.test.ts packages/agent-bundle/tests/route-invocation-dev-server.test.ts \
  packages/agent-bundle/tests/target-hook-contract.test.ts packages/workbench/tests/audiobook-curator.acceptance.e2e.test.ts \
  packages/workbench/tests/contributor-hmr.e2e.test.ts packages/workbench/tests/discovery.e2e.test.ts \
  packages/workbench/tests/evals-real.e2e.test.ts packages/workbench/tests/examples-real.e2e.test.ts \
  packages/workbench/tests/lifecycles.e2e.test.ts packages/workbench/tests/mcp-app-real.e2e.test.ts \
  packages/workbench/tests/mcp-session-timeout.e2e.test.ts packages/workbench/tests/mcp-tasks.e2e.test.ts \
  packages/workbench/tests/overview.e2e.test.ts
                                 # 13 files, 66 passed, 0 failed (every integration/browser file the diff touches)
pnpm test:packed packages/workbench/tests/packed-release.e2e.test.ts   # 1 passed (at 7f2dd2590a; packed-release.e2e is untouched by the final main merge)
pnpm docs:site:build             # ok (locale parity, no dead links)

Earlier heads: a full pnpm test:integration:run at 55be005b0f passed except one load timeout in the untouched agent-api.test.ts (30 s budget on a machine at load 60), which passed alone; the Workbench browser files audiobook-curator.acceptance, lifecycles, discovery also passed at 7f2dd2590a.

CI failure fixed at the root (Verify (integration-2) on the draft head): the parity fixture's handler wrote its handler-ran marker to the project root; the dev source watcher (which excludes only .agent-bundle, .git, node_modules, output paths) saw it, started a rebuild, and the next request raced the republish and got 409 "source is newer than the published build". The marker now lives under .agent-bundle/ like every other fixture marker, and the test asserts the 200 before reading the envelope so a recurrence names its cause.

#632 folded in: expectHeading(scope, name, timeout?) in packages/workbench/tests/support/workbench-acceptance.ts always passes exact: true; every literal heading locator in the Workbench e2e files (packed-release, overview, discovery, evals-real, mcp-app-real, examples-real, contributor-hmr, mcp-tasks, mcp-session-timeout, audiobook-curator.acceptance) goes through it. Regex heading locators are already unambiguous and stay. Closes #632.

Deslop

Claude (Fable 5.1 thinking), 14 edits across 12 files, behaviour unchanged except one trivial loader fix (rewriteTsxSpecifiers wrote ./foo.jsx for a .tsx sibling; now .tsx, covered by the existing loader test): collapsed a duplicated AB8251 throw, removed an unreachable if (aborted) after throwIfAborted(), dropped the parseCliCommandInput alias of mapGeneratedCliInput (both call sites import the callee), deduplicated the CLI-surface draft literal in route-input-editor.tsx, fixed a stale stateRoot comment and stale <epoch>/state fixture paths, and corrected the en/zh docs sentence that claimed timings show unobserved (they omit unmeasured phases). The as never casts on JsonValue in route-invocation-production.ts and the lease try/catch (converts EPOCH_NOT_FOUND into AB8239) stay.

Self-review

Reviewer: Claude (Fable 5.1 thinking), read-only, against the diff vs origin/main.

Round 1 (db99d4a65) — 10 findings, all fixed in lane A10 (/tmp notes summarised here):

1. HIGH canonical event submission bypassed the compiled preflight → AB8255 + Workbench defaults to a host for preflight routes (tests: service, tree, workspace, dev server).
2. HIGH cancelled-while-queued still executed → AbortSignal through the HTTP route and invoke(), aborted waiters leave the queue, checked again before leasing and spawning (unit tests).
3. MED render 0 ms + empty providers on a gate short-circuit → optional render duration, observed absent → unobserved.
4. MED MCP surface skipped inputSchema validation → validated in the epoch worker as the server does; failure is an MCP error result (represented-error).
5. MED generated bins gated on import.meta.main only → fallback on realpath(argv[1]) === fileURLToPath(import.meta.url); template hashes regenerated.
6. MED operator .env layer applied only for CLI/event → applied once, explicit worker env, for every surface.
7. LOW duplicated epoch formula → generatedRouteArtifactEpoch. 8. LOW lease acquired before manifest construction → reordered. 9. LOW unit-render provenance mislabelled the route kind → real kind. 10. LOW runtime backend violated outcome ⇔ succeeded → emits success.
   Docs: providers sentence corrected (no skipped), runtime-environment state-root sentence made true, PR body refreshed.

Round 2 (55be005b0f) — all 10 round-1 fixes verified in code; 6 new findings:

1. HIGH the flight worker's inputSchema.parse also ran on the generated MCP server path (double parse after the SDK's own) → fixed: the worker validates only when the message carries validateInput: true, which only route-invocation-production.ts sends; changeset reworded; template test asserts the gate.
2. MED the host selector reset to the default mid-run (invocationOf is undefined while running) → fixed: the loaded invocation's host is applied only when defined; the default is computed from [leaf, lifecycle] and, after round 3's residual, only repairs an invalid selection (canonical on a preflight route) instead of overriding a chosen or loaded host.
3. MED invocation.trace has no Workbench consumer → dismissed: it is the kernel EventTraceEvent record the P1-B audit item names ("→ AgentDocument + real trace"), measured not fabricated; the dev-server parity tests assert its sequence (preflight.start … render.finish) and PR 2b's TraceHub (already written on wb600-pr2-trace) publishes it; the strict Workbench decoder must know the field to accept the envelope. Reviewer accepted the server-side record, noted the envelope field stays consumer-less until 2b.
4. MED expectHeading shortened one 30 s budget to 15 s (discovery.e2e) → fixed: passes its browserTimeout.
5. LOW import.meta.main ?? realpathSync(...) fallback is dead on engines >=22.19 and throws for node -e → fixed: deleted with its imports; hashes re-pinned; changeset sentence removed.
6. LOW eventRequestFor third parameter only used by a test → fixed: removed.

Round 3 (a47f9f86de, then 7f2dd2590a) — 1, 2, 4, 5, 6 VERIFIED at file:line; dismissal 3 accepted; the mount-ordering follow-up on 2 (default effect declared first so a loaded host wins the same commit) VERIFIED; the LOW residual (catalog loading → ready re-running the default) fixed by the repair form above.

Trace correlation / security posture

Unchanged from PR 1: the dev server stays an authenticated loopback server; browser argv reaches only the generated bin's bounded argv parser; paths compose from the server-owned epoch id, manifest route ids, and an enum host; the state root is fixed per project. PR 2b will stream execution events from this boundary; PR 3 PTYs reuse 2b's correlation.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[changeset-bot]

🦋 Changeset detected

Latest commit: f1eba9c

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	Patch

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

[pkg-pr-new]

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

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

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/rsc-markdown-stream@643

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

commit: 55be005

[ScriptedAlchemy]

Owner addendum (19:56) folds into this PR before review completes — acceptance list: #600 (comment). Lanes running: A6 request model (canonical operation + selected surface, unit-render explicit), A7 execution status vs. application outcome (represented error / non-zero exit), A9 dev state root outside the epoch (shared with the dev MCP session). Then the six fixtures (A8), reviewer round two, deslop. Draft until then.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.