@zackbart/connecta 0.37.0 → 0.38.0

package/documentation/code-mode.md

@@ -113,7 +113,8 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 
 1. **Expose each provider as a guest global** whose properties are its `fns`,
    called with the program's arguments and awaited. Connecta supplies `search`,
-   `describe`, `call`, `read`, `result`, `skill`, and `emit`.
+   `describe`, `call`, `read`, `result`, `skill`, and `emit`; the prelude also
+   binds the guest's `skills` alias to `skill`.
 2. **Evaluate `prelude` after the provider globals exist and before the
    program.** It is trusted host code that installs the immutable namespace
    and waits for emission acknowledgements. Capture runner intrinsics first;
@@ -202,7 +203,8 @@ belonged to shortcut dispatch and stay retired; nothing reuses those ids.
 
 ## The surface
 
-Seven functions: `search`, `describe`, `call`, `read`, `result`, `skill`, and `emit`.
+Seven functions: `search`, `describe`, `call`, `read`, `result`, `skill`, and `emit`,
+plus `skills`, an undeclared alias bound to the same host function as `skill`.
 All return awaitable values; emission also works without `await`. The namespace
 has no inherited members. Unknown properties are undefined, and calling them
 fails as a guest `TypeError`. The host also dispatches only own members of `fns`.
@@ -413,7 +415,11 @@ The `get_result` meta-tool is removed.
 top-level `skills`, within the admitted connector view. It reads the registry
 behind native `skills/get` and `resources/read`, including opted-in downstream
 skills. It returns
-`{ name, format: "text", text }`; an unknown name is `not_found`.
+`{ name, format: "text", text }`; an unknown name is `not_found`. It also
+accepts the top-level tool's `{ name }` object, and `connecta.skills` is an
+undeclared alias of `connecta.skill` with the same host-call accounting, because
+models copy the `skills` tool's shape into programs. Any other argument is
+`invalid_args`, with a message naming `connecta.skill("usage")`.
 
 ### Parallel calls
 
@@ -673,11 +679,26 @@ fields. Program-authored projection saved bytes; host heuristics could drop
 deliberately returned fields. Helpers need [#222](https://github.com/zackbart/connecta/issues/222)
 evidence that programs fail to project.
 
-**R2.** The boundary is 24,000 serialized characters (~6k tokens), shared with
-emitted text. An oversized return is stashed as compact JSON through the same
+**R2.** The boundary is `execute.maxResultChars` serialized characters, shared
+with emitted text: 24,000 (~6k tokens) by default, configurable from 4,000 to
+1,000,000. Raise it when agents need large results whole and the model's
+context can afford them, since every paging round trip costs a model step.
+The response carries a return twice (text content and `structuredContent`),
+and Connecta has no response-size limit of its own, so the client's limits
+apply; `admission.requests.maxBodyBytes` bounds request bodies only. Claude Code,
+for one, passes at most 50,000 characters of text and can reject a larger result
+with no content (see [truncated direct-call results](./meta-tools.md#truncated-direct-call-results)),
+so keep the cap below what every client of the deployment accepts. Redaction scans the whole envelope once, so its cost grows with the cap.
+The cap does not change stash paging: pages still obey the stashed call's
+`maxResultBytes` and the 32 KiB bridge ceiling.
+An oversized return is stashed as compact JSON through the same
 result store as direct calls. The returned notice carries `truncated`, `resultId`,
 `totalBytes`, `hint`, `nextOffset: 0`, and an executable `nextAction` that pages
-with `connecta.result`. It also retains `totalChars` and a bounded `preview`.
+with `connecta.result`. Its page size is `floor((maxResultChars - 1024) / 6)`
+bytes, so a page fits the next program's return even when every byte escapes to
+six characters (3,829 bytes by default), at most the stashed call's
+`maxResultBytes` and the 32 KiB bridge ceiling; direct-call notices use the same
+size. It also retains `totalChars` and a bounded `preview`.
 The recovery action and hint precede the preview, so clients that spill results
 after the first 2,000 characters retain the handle and the instruction.
 Small returns pass through unchanged; Connecta does not select fields.
@@ -790,8 +811,8 @@ a successful result, appended to `content` after the JSON envelope, which gains
 response (`R6`). `structuredContent` stays the envelope alone — emission is
 presentation, not a second data channel.
 
-**M3.** Text emission shares `R2`'s 24,000 serialized-character cap, less 512
-characters reserved for the envelope (23,488 for emitted text). Its
+**M3.** Text emission shares `R2`'s `execute.maxResultChars` cap, less 512
+characters reserved for the envelope (23,488 for emitted text by default). Its
 serialized block size reduces the return budget, and oversized text fails with
 `result_too_large`. Image/audio blocks use the separate transport budget and
 reach the model as real MCP media content, including when `emit` is not awaited.
@@ -874,12 +895,24 @@ including discovery. The response returns `executor_cancelled` without awaiting
 a wedged executor or `acquire()` that ignores its signal. It releases the lease;
 a late-granted lease releases on arrival. Nothing request-bound survives the
 request. Whether guest computation stops is the executor's (`X3`).
+Final program-return paging remains request-owned after the executor lease is
+released. Cancellation stops its storage waits and starts no further stash
+operations when a pending storage response arrives. An in-process caller receives
+`executor_cancelled` with any completed writes counted in `writes.succeeded`.
 
 Programs and direct calls use the same invocation deadline and stages. A call's
 `timeoutMs` wins, then `calls.defaultTimeoutMs`, then `execute.hostCallTimeoutMs`
-(default 15,000). A guest may request a longer individual call, but the sandbox
+(default 15,000). `connecta.result`, `connecta.skill` and `connecta.read` always
+use `execute.hostCallTimeoutMs`. The `execute_code` description advertises the
+`connecta.call` default as `<n>s/host call`, or, when `calls.defaultTimeoutMs`
+differs, both deadlines, for example `25s/call (15s result/skill/read)`.
+A guest may request a longer individual call, but the sandbox
 and request ceilings still bound the whole run. Timeout details are agent-facing;
 operator records retain only checked classifications and numeric facts.
+Result processing, including stash reservation, uses the same remaining call
+budget and request cancellation. If it cannot finish after a successful call,
+the error is non-retryable `result_processing_failed`; the write already
+happened and stays successful in program write accounting.
 A dispatched write timeout becomes `write_outcome_unknown` and retains its
 deadline details even when the program catches the failure. A completed
 maintained-provider call that reports a timeout keeps `timeout` when its complete
@@ -905,17 +938,17 @@ deadline past the ceiling means raising the ceiling too.
 **L4.** Per-execution bounds that are contract, identical in both executors
 because connecta enforces them above the sandbox:
 
-| Bound                                                                                   | Value                                                                                                        |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Host calls per execution, shared by every guest call except `emit`                      | 20 by default, `execute.maxHostCalls`                                                                        |
-| Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                           |
-| Deadline per host call                                                                  | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
-| Discovery page                                                                          | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
-| `describe` addresses                                                                    | ≤ 100                                                                                                        |
-| `describe` nearby suggestions                                                           | ≤ 3 canonical addresses per failed entry                                                                     |
-| Caller text echoed by `describe` recovery                                               | ≤ 512 UTF-8 bytes per field, plus `…`                                                                        |
-| Result                                                                                  | 24,000 serialized characters                                                                                 |
-| Logs presented to the model                                                             | 4,000 characters                                                                                             |
+| Bound                                                                                   | Value                                                                                                                                                                                                                                                             |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Host calls per execution, shared by every guest call except `emit`                      | 20 by default, `execute.maxHostCalls`                                                                                                                                                                                                                             |
+| Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                                                                                                                                                                                |
+| Deadline per host call                                                                  | `connecta.call`: its `timeoutMs`, else `calls.defaultTimeoutMs`, else `execute.hostCallTimeoutMs` (15 s); `result`, `skill` and `read`: `execute.hostCallTimeoutMs`. One deadline covers catalog resolution, admission, the connector call, and result processing |
+| Discovery page                                                                          | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                                                                                                                                                                           |
+| `describe` addresses                                                                    | ≤ 100                                                                                                                                                                                                                                                             |
+| `describe` nearby suggestions                                                           | ≤ 3 canonical addresses per failed entry                                                                                                                                                                                                                          |
+| Caller text echoed by `describe` recovery                                               | ≤ 512 UTF-8 bytes per field, plus `…`                                                                                                                                                                                                                             |
+| Result                                                                                  | 24,000 serialized characters by default, `execute.maxResultChars` (4,000–1,000,000)                                                                                                                                                                               |
+| Logs presented to the model                                                             | 4,000 characters                                                                                                                                                                                                                                                  |
 
 For any tool whose output declares `page`, continue while `page.hasMore` is true.
 When approaching the program's host-call limit, return `page.nextCursor` before
@@ -1278,50 +1311,49 @@ Titles name clauses; executor-independent clauses run in both arms.
 `test/codemode-compat.test.ts` pins upstream shape compatibility, minified upstream
 rejection, and branded adapter acceptance across module copies.
 
-| Clauses                | Test                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `P1`, `P5`             | both guest-contract executors (TypeScript syntax, trailing terminators, wrapper recovery), `test/program-source.test.ts` (which semicolons and wrappers are recovered), `test/quickjs-executor.node.test.ts` (`normalizeCode`)                                                                                                                                                                                                                                                                                                  |
-| `P2`, `X5`             | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.node.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.node.test.ts` (a child-process environment holding only `TZ=UTC`), `test/deployment-shapes.node.test.ts` (loader-only Worker construction)                                                                                                                 |
-| `P3`, `X9`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `P4`                   | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution)                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `A1`, `A2`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (canonical addressing), `test/server.test.ts` (bounded live connector inventory)                                                                                                                                                                                                                                                                                                                                                                                      |
-| `S1`, `S1a`, `S2`      | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, unfiltered browse), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools-search.test.ts` (mixed complete/partial ranking, stable pagination, the two safety classes), `test/typescript-signatures.test.ts` (the TypeScript format over provider and pathological schemas, search/describe parity, observed labeling), `test/typescript-signatures-parse.node.test.ts` (every rendering parses) |
-| `S3`                   | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound)                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `S4`                   | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools-search.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds)                                                                                                                                                                                                                                                                       |
-| `S5`, `S6`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`, fail-closed annotations, activity parity)                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `S7`                   | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (parallel calls and shared admission)                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `S8`, `E1`, `X11`      | both guest-contract executors (caught call, discovery, utility, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.node.test.ts` (oversized messages, private transport, forged outcomes)                                                                                                                                                                                                                                                                                                   |
-| `S9`                   | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, failure isolation)                                                                                                                                                                                                                                                                      |
-| `S10`                  | `test/resource-read.test.ts` (qualified routing, whole-connector grants, personal credentials, redaction, admission, timeout, cancellation and downstream MCP reads), both guest-contract executors (successful resource reads and caught/uncaught typed failures)                                                                                                                                                                                                                                                              |
-| `E2`, `E8`             | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts`                                                                                                                                                                                                                             |
-| `E3`, `E4`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/identity-write-journey.node.test.ts` (read-only refusals before validation or dispatch, actual QuickJS)                                                                                                                                                                                                                                                                                                                 |
-| `E5`                   | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                            |
-| `E6`, `X8`             | `test/guest-api-contract.test.ts` (unknown and inherited members, retained error identities), `test/quickjs-executor.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                              |
-| `E7`                   | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `R1`, `R2`, `R3`, `R4` | `test/guest-api-contract.test.ts` and `test/guest-api-contract-quickjs.node.test.ts` (small pass-through, shared return paging and unavailable fallback, no repeated writes, live authority), `test/program-result-cases.ts` (reconstruction, redaction, notice survives a 2,000-character spill)                                                                                                                                                                                                                               |
-| `M6`, `M9`             | verdicts; `R2`'s guard, `M1`'s strict typing, and `M2`'s collect-then-deliver are their enforcement                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `R5`                   | `test/guest-api-contract.test.ts`, `test/quickjs-log-limits.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `R6`–`R8`              | `test/guest-api-contract.test.ts` (normal result keys), `test/execute.test.ts` (opt-in operation aggregates, failure paths, payload exclusion)                                                                                                                                                                                                                                                                                                                                                                                  |
-| `Y1`, `Y2`, `Y3`       | `test/guest-api-contract.test.ts` (one attempt per call, retryable flags by code)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `Y4`                   | `test/meta-tools-call.test.ts`, `test/call-admission.test.ts` (one attempt, retry hints, caller reissue)                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `L1`, `L2`             | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                                                                                       |
-| `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                                                                            |
-| `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors), `test/worker-budget-response.node.test.ts` (native handle disposal and admission recovery across completed HTTP responses)                                                                                                                                                                                                                     |
-| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                                                                                         |
-| `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/kv-to-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                 |
-| `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip)                                                             |
-| `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                 |
-| `W10`, `W12`           | `test/identity-write-journey.node.test.ts` (real HTTP/MCP and QuickJS: write budget, read-only discovery and refusal, named guide, pool inheritance/reopening and connector policy), `test/program-writes.test.ts` (construction refusals and classification drift), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                                           |
-| `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                                                                                   |
-| `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                                                                             |
-| `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                       |
-| `M5`, `M7`             | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `M8`                   | two arms passing one case table, `test/codemode-compat.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `M10`                  | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `X4`                   | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.node.test.ts` (logs before cancellation), `test/quickjs-child-stderr.node.test.ts` (crash, shutdown, deadline, IPC failure, bounded parent retention), `test/quickjs-log-limits.node.test.ts` (unchanged successful logs)                                                                                                                                                                                                                          |
-| `X3`, `X6`             | `test/quickjs-executor.node.test.ts` (cancels a running child, never-settling await), `test/execute.test.ts` (a wedged executor stops being awaited)                                                                                                                                                                                                                                                                                                                                                                            |
-| `X7`                   | `P3`'s tests; the Workers superset is deliberately unused                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-
-The surface itself is checked by `test/server.test.ts` (the exact six-tool list),
-`test/code-first-surface.test.ts` (construction, executor, removed tools, copy, and size),
+| Clauses                | Test                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `P1`, `P5`             | both guest-contract executors (TypeScript syntax, trailing terminators, wrapper recovery), `test/program-source.test.ts` (which semicolons and wrappers are recovered), `test/quickjs-executor.node.test.ts` (`normalizeCode`)                                                                                                                                                                                                                                      |
+| `P2`, `X5`             | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.node.test.ts` (exact absent globals and blocked imports), `test/deployment-shapes.node.test.ts` (loader-only Worker construction)                                                                                                                                                   |
+| `P3`, `X9`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `P4`                   | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution)                                                                                                                                                                                                                                                                                                                                     |
+| `A1`, `A2`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (canonical addressing), `test/server.test.ts` (bounded live connector inventory)                                                                                                                                                                                                                                                                                                                          |
+| `S1`, `S1a`, `S2`      | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, unfiltered browse), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools-search.test.ts` (mixed complete/partial ranking, stable pagination, the two safety classes), `test/typescript-signatures.test.ts` (the TypeScript format over provider and pathological schemas, search/describe parity, observed labeling)               |
+| `S3`                   | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound)                                                                                                                                                                                                                                                                                                                                                      |
+| `S4`                   | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools-search.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds)                                                                                                                                                                                                           |
+| `S5`, `S6`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`, fail-closed annotations, activity parity)                                                                                                                                                                                                                                                                                                                                             |
+| `S7`                   | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (parallel calls and shared admission)                                                                                                                                                                                                                                                                                                                                                                     |
+| `S8`, `E1`, `X11`      | both guest-contract executors (caught call, discovery, utility, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.node.test.ts` (oversized messages, private transport, forged outcomes)                                                                                                                                                                                                                                       |
+| `S9`                   | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, failure isolation)                                                                                                                                                                                                          |
+| `S10`                  | `test/resource-read.test.ts` (qualified routing, whole-connector grants, personal credentials, redaction, admission, timeout, cancellation and downstream MCP reads), both guest-contract executors (successful resource reads and caught/uncaught typed failures)                                                                                                                                                                                                  |
+| `E2`, `E8`             | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts`                                                                                                                                                                 |
+| `E3`, `E4`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/identity-write-journey.node.test.ts` (read-only refusals before validation or dispatch, actual QuickJS)                                                                                                                                                                                                                                                     |
+| `E5`                   | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                |
+| `E6`, `X8`             | `test/guest-api-contract.test.ts` (unknown and inherited members, retained error identities), `test/quickjs-executor.node.test.ts`                                                                                                                                                                                                                                                                                                                                  |
+| `E7`                   | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts`                                                                                                                                                                                                                                                                                                                                                                   |
+| `R1`, `R2`, `R3`, `R4` | `test/guest-api-contract.test.ts` and `test/guest-api-contract-quickjs.node.test.ts` (small pass-through, shared return paging and unavailable fallback, no repeated writes, live authority), `test/program-result-cases.ts` (reconstruction, redaction, notice survives a 2,000-character spill)                                                                                                                                                                   |
+| `M6`, `M9`             | verdicts; `R2`'s guard, `M1`'s strict typing, and `M2`'s collect-then-deliver are their enforcement                                                                                                                                                                                                                                                                                                                                                                 |
+| `R5`                   | `test/guest-api-contract.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `R6`–`R8`              | `test/guest-api-contract.test.ts` (normal result keys), `test/execute.test.ts` (opt-in operation aggregates, failure paths, payload exclusion)                                                                                                                                                                                                                                                                                                                      |
+| `Y1`, `Y2`, `Y3`       | `test/guest-api-contract.test.ts` (one attempt per call, retryable flags by code)                                                                                                                                                                                                                                                                                                                                                                                   |
+| `Y4`                   | `test/meta-tools-call.test.ts`, `test/call-admission.test.ts` (one attempt, retry hints, caller reissue)                                                                                                                                                                                                                                                                                                                                                            |
+| `L1`, `L2`             | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                           |
+| `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                |
+| `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors)                                                                                                                                                                                                                                                                                     |
+| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                             |
+| `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/storage-sql-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message)                                                                              |
+| `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip) |
+| `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                     |
+| `W10`, `W12`           | `test/identity-write-journey.node.test.ts` (real HTTP/MCP and QuickJS: write budget, read-only discovery and refusal, named guide, pool inheritance/reopening and connector policy), `test/program-writes.test.ts` (construction refusals and classification drift), `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                 |
+| `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                       |
+| `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                 |
+| `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                           |
+| `M5`, `M7`             | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched)                                                                                                                                                                                                                                                                                                                                                                      |
+| `M8`                   | two arms passing one case table, `test/codemode-compat.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `M10`                  | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted)                                                                                                                                                                                                                                                                                                                                                                          |
+| `X4`                   | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.node.test.ts` (logs before cancellation)                                                                                                                                                                                                                                                                                                                                               |
+| `X3`, `X6`             | `test/quickjs-executor.node.test.ts` (cancels a running child, never-settling await), `test/execute.test.ts` (a wedged executor stops being awaited)                                                                                                                                                                                                                                                                                                                |
+| `X7`                   | `P3`'s tests; the Workers superset is deliberately unused                                                                                                                                                                                                                                                                                                                                                                                                           |
+
+The surface itself is checked by `test/server.test.ts` (the exact six-tool list)
 and `test/program-writes.test.ts` (deployment policy and classification construction refusals).

package/documentation/deploying.md

@@ -64,12 +64,9 @@ platform, proxy or adapter cap still wins. See
 A Node host serving `connecta.fetch` without `listen()` has no owned sender:
 every maintained-provider write, every reviewed POST read and every remote MCP
 write is refused before sending. Downstream OAuth credential POSTs also require
-that sender; discovery GETs retain native fetch. Resource writes worked in 0.34.1;
-credential POSTs used native fetch through 0.34.1. For example, an `assistant` using
+that sender. For example, an `assistant` using
 `vercel_api_read` to POST `/v1/registrar/domains/availability` needs that
-transport even on a read-only endpoint. A Node deployment using only the root
-entry refuses those requests before sending them. Workers use their native
-fetch transport.
+transport even on a read-only endpoint. Workers use their native fetch transport.
 
 By default, Node's `listen()` handles SIGTERM and SIGINT: it stops accepting
 connections, closes idle connections and accepted sockets without a first HTTP
@@ -81,9 +78,8 @@ keepalive before shutdown is unchanged. Its shutdown deadline defaults to ten se
 (`shutdownTimeoutMs`). For example, retain the template's `listen(connecta, port)` when running it under
 Docker Compose so `docker compose stop` uses this cleanup.
 
-The owned Node sender connects directly by default. To send maintained-provider
-requests (including reads), remote MCP writes and OAuth credential POSTs through an HTTP(S) CONNECT
-proxy, set `proxy` explicitly on `listen`:
+The owned Node sender connects directly by default. For HTTP(S) CONNECT proxy
+egress, set `proxy` explicitly on `listen`:
 
 ```ts
 listen(connecta, { port: 3000, proxy: "http://proxy.example.com:8080" });
@@ -108,9 +104,7 @@ replayed by the sender, including after HTTP 421, a reset or a 503. An uncertain
 refresh requires authorization again; Connecta blocks the spent refresh
 fingerprint rather than redeeming it twice. Once a refresh claim has been
 submitted, that protection remains conservative even if proxy setup later fails.
-Use a fresh authorization flow to reconcile. OAuth discovery remains on native
-fetch and needs its own host proxy policy. These credential POST requirements
-change the native-fetch behavior of 0.34.1.
+Use a fresh authorization flow to reconcile.
 
 ## Start on Workers
 
@@ -136,10 +130,8 @@ verified ingress behavior and the cases that still require verification.
 Agents use `/agent/<pool>`, which connecta authenticates with the `cta_` token
 alone and which ignores Access context entirely
 ([agent endpoints](./auth.md#agent-endpoints)). Behind Access, the edge must
-let those requests through without an Access login or service token. The P0
-probe ([observations](./architecture.md#production-access-bypass-for-agent-endpoints))
-verified this shape on 2026-10-15. The Worker example's `alchemy.run.ts`
-declares both applications:
+let those requests through without an Access login or service token.
+The Worker example's `alchemy.run.ts` declares both applications:
 
 1. Keep the Worker-level application, whose destination is
    `{ "type": "worker", "worker_id": "<the Worker script tag>" }`, exactly as
@@ -170,12 +162,9 @@ declares both applications:
 3. Point each agent at `https://<host>/agent/<pool>` with
    `Authorization: Bearer cta_…` and drop its `CF-Access-Client-Id` and
    `CF-Access-Client-Secret` headers. The pool must list `"agent:<name>"`.
-4. Verify after the change has settled. Access changes took 15–19 seconds to
-   settle in the probe, and while they propagate the edge can answer with
-   transient 500 (`error code: 1104`) or 404 (`error code: 1042` or `1043`)
-   responses, and in one round a 403 on a bypassed path after more than 30
-   seconds. Do not rely on a fixed wait: repeat these checks until they agree
-   for several consecutive rounds. Without credentials, `/agent/<pool>`
+4. Verify after the change has settled. Do not rely on a fixed wait: repeat
+   these checks until they agree for several consecutive rounds. Without
+   credentials, `/agent/<pool>`
    reaches connecta (its 401 carries `WWW-Authenticate: Bearer`, not Access's
    403 page), while `/mcp` and `/` still get Access's refusal. Then run
    `connecta doctor --pool <pool>` with the agent's token.
@@ -185,11 +174,8 @@ Connecta answers there only an issued token of an agent listed in the pool,
 and gives every other spelling of the agent namespace a 404 before auth,
 because Access matches `/agent/*` after resolving dot segments, folding case,
 decoding unreserved escapes, and collapsing a leading `//`, while the Worker
-sees the raw path. Two cases were not tested: a human's `CF_Authorization`
-cookie on a bypassed path, whose `ctx.access` identity is unknown (connecta
-never reads it at `/agent/*`), and Custom Domains, which use the same
-documented hostname-and-path form but were not observed; only `workers.dev`
-was probed. Pinning the Worker-level application's AUD on human routes is
+sees the raw path. Connecta never reads `ctx.access` at `/agent/*`.
+Pinning the Worker-level application's AUD on human routes is
 recommended hardening that connecta does not yet do.
 
 ## Compose capabilities and access
@@ -314,22 +300,16 @@ Bump the exact package pin, read the [changelog](../CHANGELOG.md) for every
 intervening release, and apply the relevant migration before startup. `init`
 does not merge changes into an existing deployment.
 
+Before upgrading past 0.37.1 with pre-0.29 state, follow
+[Retired layout migrations](./migration-retired-layouts.md). Version 0.37.1 is
+the last bridge for KV → D1, JSON → SQLite, and OAuth layout-2 conversions.
+
 For an existing Node deployment, add the Node entry's pinned optional peer
 before starting the upgraded package: `npm install --save-exact undici@6.29.1`.
 The current Node template already declares this dependency.
 
-For 0.35.0, serve Node with `listen` from `@zackbart/connecta/node`, as the
-current template does. Without `listen()`, a host serving `connecta.fetch` has
-no owned sender: every maintained-provider write, every reviewed POST read and
-every remote MCP write is refused before sending, although each worked in 0.34.1.
-Downstream OAuth token, registration and revocation POSTs also require that
-sender. With `listen()`, every maintained-provider request, reads included,
-remote MCP writes and those credential POSTs use the owned sender. Configure
-`listen(..., { proxy })` explicitly for HTTP(S) CONNECT proxy egress; ambient
-`NODE_USE_ENV_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY` and host proxy dispatchers do
-not configure it. Remote MCP reads and OAuth discovery GETs retain native fetch
-and need their own host proxy policy. An uncertain refresh requires fresh
-authorization rather than replaying the spent token. See [Start on Node](#start-on-node).
+For Node upgrades, retain the template's `listen` entrypoint and apply the
+[Node transport and proxy requirements](#start-on-node).
 
 Authenticated MCP bodies now default to 4 MiB through
 `admission.requests.maxBodyBytes`; Node's separate pre-auth buffer also defaults
@@ -354,8 +334,7 @@ and [Eve agents](./meta-tools.md#eve-agents).
 - [Migration to 0.34](./migration-0.34.md) covers the Overview landing page, Endpoints at `/endpoints`, default browser titles, and Workspace discovery in owner-less agent pools. No storage migration or token rotation is needed from 0.33.
 - [Migration to 0.33](./migration-0.33.md) maps every removed access option to `maintainers`, pool `members`, and `agents`, moves agents to `/agent/<pool>`, and covers pool owners, token revisions, operator contract v2 with its operator route changes, and the pre-auth listen fix.
 - [Tokens issued before agents](./auth.md#agent-tokens-and-upgrading-from-earlier-tokens) stop admitting until each machine's token is bound once to a declared agent with `npm run adopt-token -- <token-id> <agent>` (Node) or `AccessTokenManager.adopt`, which keeps its secret. Human-bound tokens stay refused; issue those agents new tokens. Pool members name `"agent:<name>"` instead of matching token record ids.
-- [Node storage from 0.28](../templates/node/README.md#storage) uses `connecta migrate-state` to copy the JSON state into SQLite. Activity JSONL is not imported.
-- [Worker storage from 0.28](../examples/worker/README.md#upgrading-from-028) copies KV into D1 with a one-shot migration.
+- [Retired layout migrations](./migration-retired-layouts.md) requires completing Node JSON → SQLite, Workers KV → D1, and every OAuth layout-2 grant conversion on 0.37.1 before upgrading. The new package no longer supplies those migrations.
 - [Worker deployments on Wrangler](../examples/worker/README.md#moving-a-wrangler-deployed-worker-to-alchemy) move to Alchemy once, adopting the Worker, D1 database, and Access applications so the script tag and Access AUD stay unchanged.
 - [Notion, Vercel, and Cloudflare for 0.29](./provider-migration-0.29.md) records historical defaults and retained API tool names.
 - [Executor wiring](./code-mode.md#deploy-time-capability) requires branded shipped executors or a self-managed custom executor.

package/documentation/integrating.md

@@ -90,6 +90,10 @@ value is validated at construction. Malformed policies, including `false`,
 `null`, `0`, and `""`, throw before serving requests; they never disable
 admission or select a default. Custom connector policies are validated when
 the deployment constructs its registry.
+A queued connector call whose wait reaches `queueTimeoutMs` is refused with a
+concurrency `rate_limited` error, even if timer delivery is delayed. For example,
+with `maxConcurrency: 1` and `queueTimeoutMs: 10`, releasing the occupied slot
+after 40 ms refuses the expired waiter instead of dispatching it.
 
 ## Maintained integrations
 
@@ -215,26 +219,11 @@ failure also reports an unknown outcome with no retry or wait advice; a proven
 unsent failure retains its own recovery advice. Connector `readOnly` remains
 optional and composes with endpoint policy.
 
-On Node, serve with `listen` from `@zackbart/connecta/node`: it installs the
-owned transport that prevents native fetch or a host-configured dispatcher
-from silently resending a remote MCP write. Without that transport, Node
-refuses remote writes before dispatch. A connector with its own `fetch` hands
-writes to that function instead, which owns their single attempt. Downstream OAuth token, registration and
-revocation POSTs also require the owned sender. Read calls and OAuth discovery
-GETs keep native fetch. Workers
-use their native fetch with manual redirects; transport failures after
+On Node, follow the [Node transport and proxy requirements](./deploying.md#start-on-node).
+A connector with its own `fetch` hands writes to that function, which owns their
+single attempt. Workers use native fetch with manual redirects; failures after
 dispatch remain unknown and non-retryable.
 
-The owned sender connects directly by default. For HTTP(S) CONNECT proxy egress,
-configure `listen(connecta, { port: 3000, proxy: "http://proxy.example.com:8080" })`.
-This controls maintained-provider requests, remote MCP writes and OAuth
-credential POSTs; it ignores `NODE_USE_ENV_PROXY`, `HTTP_PROXY`, `HTTPS_PROXY`
-and host proxy dispatchers. Remote MCP reads and OAuth discovery GETs retain
-native fetch and need their own host proxy policy. An uncertain refresh requires
-fresh authorization rather than replaying the spent token. See
-[Node startup](./deploying.md#start-on-node) for the proxy URL, credentials and
-TLS trust rules.
-
 Remote catalogs evolve. Discovery, direct calls, and programs enforce the
 current annotations and `ConnectaConfig.classification` overrides. A leftover
 `classify` option throws at construction and names that map. Provider reviews,
@@ -342,7 +331,7 @@ check shared behavior. Provider-specific tests remain beside each provider.
 
 Use [`@zackbart/connecta-eve`](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
 in the Eve app for an app-owned connection and endpoint instructions refreshed
-once per turn. It requires Node 24 and Eve 0.84.x, and installs separately from
+once per turn. It requires Node 24 and Eve 0.86.x, and installs separately from
 Connecta. Follow its README for the two agent files, token environment variables,
 optional write approval and Vercel OIDC token source. Configure the server's
 [agent and pool membership](./auth.md#issue-rotate-or-revoke-an-agent-token)

package/documentation/meta-tools.md

@@ -221,6 +221,16 @@ act on is the flag: any cap sets `inputSchemaTruncated` or
 `outputSchemaTruncated`, and that means repeat with `includeSchemas: "json"`, or
 describe, when the exact constraints matter.
 
+Repeated searches in one request reuse a private lexical index for the same
+visible catalog and safety filter. Returned schemas and annotations are independent
+copies: changing a result cannot change later discovery or tool classification.
+In-process registry invalidation (including refresh and OAuth connect/disconnect/restart)
+or built-in vault set/clear replaces the retained catalog and its index before the
+next discovery read in that request, without storage reads on unchanged repeats.
+Changes from another process/isolate or direct storage writes need not be observed
+until the next request. Custom vault mutations must also invalidate the registry.
+The index never crosses request or caller/pool boundaries.
+
 ### TypeScript signatures
 
 `includeSchemas: "typescript"` replaces both schema fields with one
@@ -423,6 +433,13 @@ new entries. A later attempt deletes expired entries before reusing their
 capacity; a failed deletion keeps the charge. These bounds cover all processes and Worker isolates sharing the store.
 Compare-and-set reserves each charge in one storage ledger before any chunk
 is written; chunk TTLs cannot exceed the charge deadline.
+The whole stash, including reservation, stops waiting after 45 seconds, or sooner
+when the call's remaining deadline or request cancellation ends result processing.
+A completed call whose result processing is cut off returns the non-retryable
+`result_processing_failed`: any write already happened and must not be repeated
+to recover its result. Programs keep that write in `writes.succeeded`, even if
+paging is cancelled. A full or unavailable stash that answers within the budget
+still returns the ordinary truncated result and paging-unavailable hint.
 
 Results belong to the authenticated subject whenever auth supplies a subject or
 user id, independently of activity configuration, under the provider's namespace
@@ -511,8 +528,10 @@ The default cap sits under both lines with room to spare. Preview plus notice
 stays under 25,000 bytes, which is under 50,000 characters for any text, because
 a character is at least one UTF-8 byte, and under 25,000 tokens for any text,
 because a token covers at least one byte. A `connecta.result` page is bounded by the same
-inline byte cap, and 24,000 matches the program result boundary in
-[code mode](./code-mode.md). A deployment whose
+inline byte cap, and 24,000 matches the default program result boundary in
+[code mode](./code-mode.md) (`execute.maxResultChars`). The `maxBytes` in
+`nextAction` is sized so one page fits that boundary under worst-case JSON
+escaping, capped by the call's own inline cap: 3,829 bytes by default. A deployment whose
 clients take more can raise the cap, and one whose clients take less can lower
 it, per connector if need be; a result between 24,000 and 50,000 bytes that
 used to arrive whole now pages. A client that spills rather than rejects keeps
@@ -1292,7 +1311,7 @@ window, a native `tools/list` carries a 300-second private cache hint, against
 an hour on meta endpoints. This hint does not guarantee that a host refreshes
 its cached annotations; the stale-approval race is accepted on writable pools.
 
-**Listing.** `tools/list` is one page with no cursor (Eve 0.84 reads only the
+**Listing.** `tools/list` is one page with no cursor (Eve 0.86 reads only the
 first page). A pool listing more than 1,000 tools fails `tools/list` with a
 JSON-RPC error asking the operator to narrow the pool; nothing is silently
 dropped. A connector whose catalog cannot load is left out of that listing
@@ -1363,8 +1382,6 @@ listing, and call translation live in
 [search tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-search.test.ts),
 [call tests](https://github.com/zackbart/connecta/blob/main/test/meta-tools-call.test.ts),
 [skills tests](https://github.com/zackbart/connecta/blob/main/test/skills-extension.test.ts),
-[native surface tests](https://github.com/zackbart/connecta/blob/main/test/native-tools.test.ts),
-[surface tests](https://github.com/zackbart/connecta/blob/main/test/code-first-surface.test.ts),
-and [pool description tests](https://github.com/zackbart/connecta/blob/main/test/pool-description.test.ts)
+and [native surface tests](https://github.com/zackbart/connecta/blob/main/test/native-tools.test.ts)
 check the published contract. Guest parity and clause evidence are in
 [code-mode verification](./code-mode.md#verification).

package/documentation/migration-0.33.md

@@ -1,8 +1,7 @@
 # Migration to 0.33
 
-Use this upgrade guide for an existing deployment moving to 0.33.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover the
-general procedure; [the agent index](./README.md) routes other work.
+Apply the [general upgrade procedure](./deploying.md#upgrade-an-existing-deployment)
+when moving from 0.32 to 0.33.
 
 0.33 makes pools the access model.
 Every deployment with inbound auth changes its configuration. Each removed
@@ -338,8 +337,9 @@ pools: {
 
 ## Verify
 
-1. Start the deployment; construction errors name each removed option's
-   replacement.
+1. Start the deployment; 0.33 construction errors name each removed option's
+   replacement. Releases after 0.37.1 use generic unknown-option errors;
+   use this guide for replacements.
 2. Sign in as a maintainer and confirm plain `/mcp` and the operator UI work.
 3. Run `connecta doctor --pool <pool>` with each agent's token, and confirm
    the same token at `/mcp` is refused.

package/documentation/migration-0.34.md

@@ -1,9 +1,7 @@
 # Migration to 0.34
 
-Use this guide when upgrading an existing deployment from 0.33 to 0.34.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover the
-general procedure; [the agent index](./README.md) routes other work. Upgrades
-from earlier versions must also apply the intervening migrations.
+Apply the [general upgrade procedure](./deploying.md#upgrade-an-existing-deployment)
+when moving from 0.33 to 0.34, including intervening migrations for older versions.
 
 No storage migration, token rotation or required configuration field is added.
 Review the following changes before updating the package pin.