docs(workbench): AB8255 is the public refusal of a host-less preflight route; AB8252 is the child's guard

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

Author: cursoragent

.changeset/680-workbench-exact-executable-binding.md

@@ -2,4 +2,4 @@
 "agent-bundle": patch
 ---
 
-Bind Workbench production route invocations to the exact executables the epoch's `agent-bundle.manifest.json` names — `executables.bins[]`, `executables.scripts[]`, `executables.mcpServers[].launch.worker`, the host's `executables.hooks[]` wrapper row and the worker its `routes.events[].execution` selects — before anything runs, instead of listing `*-flight.mjs` candidates and hopping to the next worker on a missing-route error. The binding fails closed: a root without a readable manifest is `AB8250`; a route the manifest does not compile, a hosted event with no wrapper row, or a shared-runtime event with several candidate servers and no named owner is `AB8251`; a canonical submission of an event route whose preflight only a host wrapper can run, or a bound bin or wrapper missing its preparation export, is `AB8252` — the handler is never reached, and a handler failure inside the bound worker never runs another executable (#680)
+Bind Workbench production route invocations to the exact executables the epoch's `agent-bundle.manifest.json` names — `executables.bins[]`, `executables.scripts[]`, `executables.mcpServers[].launch.worker`, the host's `executables.hooks[]` wrapper row and the worker its `routes.events[].execution` selects (`hooks/hooks-flight.mjs` standalone, otherwise the first compiled server reaching the host, the one the compiler gave the shared event runtime) — before anything runs, instead of listing `*-flight.mjs` candidates and hopping to the next worker on a missing-route error. The binding fails closed: a root without a readable manifest is `AB8250`; a route the manifest does not compile, a hosted event with no wrapper row for that host, or a bin, script, or server without a worker is `AB8251`; a bound bin or wrapper missing its preparation export, or a preflight route that reaches the child without a host (`AB8255` at the service), is `AB8252` — the handler is never reached, and a handler failure inside the bound worker never runs another executable (#680)

docs/diagnostics.md

@@ -49,7 +49,7 @@ even when no error diagnostic was reported.
 | `AB8240`–`AB8242` | Workbench unified trace routes (`/api/trace`, `/api/trace/stream`): `AB8240` invalid `after` cursor (400), `AB8241` cursor ahead of the current trace sequence (409), and `AB8242` trace routes unavailable before composition or during shutdown (404/503). |
 | `AB8247`–`AB8249` | Workbench hook receipt route (`POST /api/trace/receipts`, posted by a generated hook wrapper of the dev plugin): `AB8247` receipt refused — peer not loopback, `Origin` header present, missing or wrong bearer token (403), or receipts closed (409); `AB8248` malformed receipt — query string, non-object body, unknown key, out-of-range enum, or unbounded field (400, the message names the field); `AB8249` receipt over the 16 KiB limit (413). |
 | `AB8239` | Workbench route invocation service (`/api/routes/invocations`): the published manifest digest or source revision moved while the request waited for a concurrency slot (409). Retry against the current revision so the recorded `manifestDigest`/`sourceRevision` cannot describe a different build than the one that ran. |
-| `AB8250`–`AB8255` | Workbench production route execution, bound from the epoch's `agent-bundle.manifest.json` before anything runs: `AB8250` no published compiler artifact is available or the epoch root has no readable manifest, `AB8251` the manifest binds no executable to the selected route (a route it does not compile, a hosted event with no `executables.hooks[]` wrapper row for that host, a shared-runtime event several compiled servers could host and no named runtime owner among them, a rendered route whose bin, script, or server carries no worker), `AB8252` compiled CLI projection or event preflight preparation failed — including a canonical submission of a route whose preflight only a host wrapper can run, and a bound bin or wrapper without its preparation export — `AB8253` a selected CLI command does not project onto the canonical operation id, `AB8254` a projected `cli:<command>` id was used instead of its canonical `tool:<server>/<tool>` id plus CLI surface, and `AB8255` an event route with compiled preflight was submitted without a concrete host surface. The handler is never reached for any of these, and a failure inside the bound worker never runs another executable. Rebuild the project for `AB8250`/`AB8251`; fix the reported projection or preflight failure for `AB8252`; use the command or canonical operation named by `AB8253`/`AB8254`; select a generated host wrapper for `AB8255`. |
+| `AB8250`–`AB8255` | Workbench production route execution, bound from the epoch's `agent-bundle.manifest.json` before anything runs: `AB8250` no published compiler artifact is available or the epoch root has no readable manifest, `AB8251` the manifest binds no executable to the selected route (a route it does not compile, a hosted event with no `executables.hooks[]` wrapper row for that host, a shared-runtime event no compiled server reaching the host can run, a rendered route whose bin, script, or server carries no worker), `AB8252` compiled CLI projection or event preflight preparation failed — including a bound bin or wrapper without its preparation export, and a preflight route that reached the child without a host (the service refuses that first as `AB8255`) — `AB8253` a selected CLI command does not project onto the canonical operation id, `AB8254` a projected `cli:<command>` id was used instead of its canonical `tool:<server>/<tool>` id plus CLI surface, and `AB8255` an event route with compiled preflight was submitted without a concrete host surface. The handler is never reached for any of these, and a failure inside the bound worker never runs another executable. Rebuild the project for `AB8250`/`AB8251`; fix the reported projection or preflight failure for `AB8252`; use the command or canonical operation named by `AB8253`/`AB8254`; select a generated host wrapper for `AB8255`. |
 | `AB8256` | Workbench route invocation cancellation (`POST /api/routes/invocations/<id>/cancel`): the invocation is already final (409). Reload the final invocation instead of cancelling it. |
 | `AB8260` | Workbench host sessions: `@lydell/node-pty` could not be resolved from the project or loaded (503). Install the PTY module in the project workspace and restart `agent-bundle dev`. |
 | `AB8261` | Workbench host sessions: a request body, path, query, dimension, input, or live-session delete is malformed (400/409). Send only the documented `/api/sessions` fields and forget sessions only after they exit. |

website/docs/en/guide/development/workbench.mdx

@@ -359,14 +359,15 @@ routed CLI bin and worker from `executables.bins[]`, the rendered script's worke
 `executables.scripts[]`, the owning compiled server's `launch.worker` from
 `executables.mcpServers[]`, and, for an event route, the host's wrapper row from
 `executables.hooks[]` plus the worker its `routes.events[].execution` selects
-(`hooks/hooks-flight.mjs` for a standalone runtime, the shared runtime owner's worker
-otherwise). The binding fails closed: a root without a readable manifest is `AB8250`, a route
-the manifest does not compile, a hosted event with no wrapper row, or a shared-runtime event
-with several candidate servers and no named owner is `AB8251`, and a canonical submission of a
-route whose preflight only a host wrapper can run, or a bound bin or wrapper missing its
-preparation export, is `AB8252` — in every case before the handler is reached. A failure
-inside the bound worker, a handler throw included, is the invocation's failure; no other
-executable runs.
+(`hooks/hooks-flight.mjs` for a standalone runtime, otherwise the worker of the first compiled
+server reaching the host — the same server the compiler gave the shared event runtime). The
+binding fails closed: a root without a readable manifest is `AB8250`; a route the manifest does
+not compile, a hosted event with no wrapper row for that host, or a bin, script, or server
+without a worker is `AB8251`; a bound bin or wrapper missing its preparation export is
+`AB8252`. A preflight route submitted without a host is refused by the service as `AB8255`
+before it is queued, and the child refuses it again as `AB8252` should it ever reach it — in
+every case before the handler is reached. A failure inside the bound worker, a handler throw
+included, is the invocation's failure; no other executable runs.
 Production state lives at `<project>/.agent-bundle/state`, outside the published epochs that
 retirement removes. It is shared with dev MCP sessions through `AGENT_BUNDLE_STATE_ROOT`, so it
 survives a successful republish; `unit-render` still uses a fresh temporary state root per run.

website/docs/zh/guide/development/workbench.mdx

@@ -302,11 +302,12 @@ providers、持久状态、CLI `mapInput` 与确认、事件 preflight 以及渲
 worker 取自 `executables.scripts[]`，所属已编译服务器的 `launch.worker` 取自
 `executables.mcpServers[]`；事件路由则取该宿主在 `executables.hooks[]` 中的包装层行，加上其
 `routes.events[].execution` 选定的 worker（standalone 运行时为 `hooks/hooks-flight.mjs`，否则为
-共享运行时所有者的 worker）。绑定失败即关闭：缺少可读 manifest 的根报告 `AB8250`；manifest 未编译
-的路由、没有包装层行的宿主事件，或有多个候选服务器却未指明所有者的共享运行时事件报告 `AB8251`；
-以 Canonical 方式提交只有宿主包装层才能运行其 preflight 的路由，或绑定到的 bin / 包装层缺少准备导出，
-报告 `AB8252`——所有情况都发生在到达处理函数之前。绑定 worker 内部的失败（包括处理函数抛错）即为
-该次调用的失败；不会再运行其他可执行项。
+到达该宿主的第一个已编译服务器的 worker——也就是编译器交付共享事件运行时的那台服务器）。绑定失败
+即关闭：缺少可读 manifest 的根报告 `AB8250`；manifest 未编译的路由、该宿主没有包装层行的宿主事件，
+或没有 worker 的 bin / 脚本 / 服务器报告 `AB8251`；绑定到的 bin / 包装层缺少准备导出报告 `AB8252`。
+未指定宿主提交带 preflight 的路由会在排队前被服务以 `AB8255` 拒绝，若它仍到达子进程，子进程会再次
+以 `AB8252` 拒绝——所有情况都发生在到达处理函数之前。绑定 worker 内部的失败（包括处理函数抛错）
+即为该次调用的失败；不会再运行其他可执行项。
 生产状态位于 `<project>/.agent-bundle/state`，在 retirement 会移除的已发布 epoch 之外。它通过
 `AGENT_BUNDLE_STATE_ROOT` 与开发期 MCP 会话共享，因此能跨一次成功的重新发布保留；`unit-render`
 仍为每次运行使用新的临时状态根。