@zackbart/connecta 0.24.4 → 0.26.0

package/documentation/code-mode.md

@@ -16,10 +16,16 @@ identifiers (`A1`, `E3`, …) are stable and cited by [Verification](#verificati
 ## Deploy-time capability
 
 The `executor` passed to `createConnecta()` is required. `tools/list` is exactly
-seven — `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
-`authorize_connector`, `get_result`, and `skills`. Construction fails when the
-executor is missing, and the removed `surface` option is rejected rather than
-ignored ([#273](https://github.com/zackbart/connecta/issues/273)).
+eight — `execute_code`, `resume_execution`, `search_tools`, `call_tool`,
+`call_destructive_tool`, `authorize_connector`, `get_result`, and `skills`.
+Construction fails when the executor is missing, and the removed `surface`
+option is rejected rather than ignored
+([#273](https://github.com/zackbart/connecta/issues/273)).
+
+[Resumable writes](#pausing-and-resuming) need storage with `compareAndSet`:
+omitted, `execute.resumableWrites` is on exactly when the storage has it (not
+Cloudflare KV, which warns once at startup), `true` without it refuses to
+construct, and `/health` reports which.
 
 On Node, install the optional `quickjs-emscripten` peer and use the package's
 QuickJS subpath:
@@ -90,7 +96,9 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 5. **Capture `console.log`, `console.warn`, and `console.error`** into `logs` in
    call order (`R5`), bounding what it retains.
 6. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`), staying
-   inside the tested `P2`/`X5` boundary.
+   inside the tested `P2`/`X5` boundary. Settle `execute()` on your own
+   deadline: connecta stops waiting at `execute.watchdogMs` and reports the
+   sandbox unresponsive (`L3`).
 7. **Grant no ambient authority of its own.** Never back this with `eval` or
    `node:vm`: the sandbox is a containment layer on top of connecta's boundary,
    not a replacement for it, and every capability arrives through `fns`.
@@ -105,11 +113,15 @@ is just another provider function (`M8`).
 
 ## The program
 
-**P1.** A program is one JavaScript `async` arrow-function expression, evaluated
-once; its resolved value is the result. Both executors also accept
-markdown-fenced code and a bare statement body, normalizing those differently —
-a courtesy to model output, not contract, so anything else may be accepted,
-rejected, or reinterpreted.
+**P1.** A program is one JavaScript `async` arrow expression, evaluated once;
+its resolved value is the result. Before either executor sees it, `execute_code`
+removes trailing semicolons (and retains comments) so parenthesized evaluation
+works on both. `async () => 1; 2` is still more than one expression. The host
+also recovers one JavaScript fence, even when prose surrounds it, `export default`
+around an async arrow, or one named `async function` declaration with simple
+parameters. The result remains one async arrow. Multiple fences, extra
+statements, and bare statement bodies are outside host recovery. QuickJS may
+wrap a bare body when driven directly; that is outside the portable contract.
 
 **P2.** The only capabilities in the contract are `connecta.search`,
 `connecta.describe`, `connecta.call`, `connecta.emit`, and `console.log` /
@@ -129,12 +141,34 @@ storage carried to the next program, and no request-bound object outliving its
 request. Within one execution, host calls share one downstream request scope.
 `S9`'s output observation is host-owned catalog metadata, not guest memory — a
 later program receives a labeled field/type schema through discovery, never a
-prior value or object.
+prior value or object. A run paused at a write leaves a bounded, expiring
+journal (`W3`) for `resume_execution` to replay — host-owned data, not guest
+state: the replay gets back exactly the answers the first play got.
 
 **P5.** Plain JavaScript only; TypeScript syntax is a syntax error. Portable
 code does not import: QuickJS blocks imports, Dynamic Workers expose the `X5`
 runtime modules, and neither exposes `require`.
 
+**P6.** A run's clock and randomness are pinned. `Date.now()`, `new Date()`,
+and `Date()` read one instant the host takes at run start, and it does not
+advance; `Date` with arguments, `Date.parse`, and `Date.UTC` are the native
+ones. `Math.random()` is sfc32 seeded from the host's CSPRNG per run. On a
+Dynamic Worker (QuickJS has neither, `X5`), `crypto.getRandomValues` and
+`randomUUID` draw from the same stream and `performance.now()` stays at 0, on
+the objects and their prototypes — so a Workers-only program replays too,
+which makes none of them contract (`P2`). An `Intl` formatter asked for "now"
+formats the pinned instant, and local time is UTC on both executors (the
+QuickJS child runs with `TZ=UTC`). The replacements are trusted prelude,
+locked like `Error` (`X11`), and the native constructor's `now` and prototype
+`constructor` read the same instant; QuickJS lets `defineProperty` replace a
+locked *global* binding, but the replacement is the program's own code. The
+reason is replay (`W6`): a program that branched on a moving clock would take
+another branch the second time and diverge (`W8`), and pinning every run means
+none can tell whether it is replayed. A program cannot time itself; `R7`
+measures from the host. The pin is best-effort beyond these: a program that
+depends on a source it misses, such as the order Workers timers fire in, is
+not portable (`P2`) and fails a replay as divergence.
+
 ## Addressing
 
 **A1.** A tool has one canonical address, `<connectorId>.<toolName>`, exactly as
@@ -164,7 +198,7 @@ const page = await connecta.search({
   limit: 8,                         // 1–100, default 8
   offset: 0,
   fullDescriptions: false,
-  includeSchemas: "compact",        // or "json"
+  includeSchemas: "compact",        // or "json" / "typescript"
   includeSchemaKeys: true,          // default true in code mode
 });
 ```
@@ -192,6 +226,7 @@ bounds:
 
 | Bound | Value |
 | --- | --- |
+| `execute_code` source | ≤ 65,536 UTF-8 bytes, checked before executor admission; over-limit source returns `invalid_args` |
 | Rendered shape | 1,024 UTF-8 bytes each |
 | Work per shape | 2,000 visits across schema nodes, property and required names, literal values, any constraint-free retry, and its key-only fallback |
 | Each enum node | 256 of those bytes |
@@ -211,13 +246,27 @@ truncation flag; `$dynamicRef` resolves a same-named definition like `$ref`, and
 an unresolved one becomes `unknown` with the flag. For omitted exact constraints
 use `format: "json"` or JSON search.
 
+`includeSchemas: "typescript"` spends those same bounds on a different
+rendering: one `signature` string in place of `inputSchema` and
+`outputSchema`, reading `(args: { runId: number }) => Promise<Run>` for the
+value `connecta.call` returns. It is documentation for the program's author —
+the program itself is still JavaScript, and a type annotation copied into it
+is a syntax error (`P5`). Truncation keeps compact's flags and
+turns what compact would print as a name or raw JSON into a marked `unknown`;
+an observed output opens with `/* observed, not declared */`. The dialect and
+its degradation rules are specified once, under
+[TypeScript signatures](./meta-tools.md#typescript-signatures), and the
+signature is byte-identical to the one `search_tools` returns.
+
 **S1a.** `connector` loads only the named catalog; omit it only when the
 integration is ambiguous, because an unscoped search fans out across every
-configured connector. `safety: "readOnly"` returns exactly the tools available
-through `connecta.call`; `"approvalRequired"` returns the complementary
-fail-closed class, including false, missing, and contradictory annotations;
-omitted or `"all"` preserves the complete catalog. These filters grant no
-authority and change no admission decision.
+configured connector. `safety: "readOnly"` returns exactly the tools
+`connecta.call` runs unasked; `"approvalRequired"` returns the complementary
+fail-closed class, false, missing, and contradictory annotations included,
+whose calls pause (`W1`) unless config exempts them (`W12`), which a row marks
+with `approval: "exempt"` without moving it out of that class; omitted or
+`"all"` preserves the complete catalog, as a program that means to write needs.
+These filters grant no authority and change no admission decision.
 
 **S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`
 (declared properties only), and `outputKeys`: the names the rendered schema
@@ -249,7 +298,7 @@ hint and the stable `code`, `retryable`, and `details` fields (`E1`).
 const one = await connecta.describe({ address: "ci.get_run" });
 const many = await connecta.describe({
   addresses: ["ci.get_run", "ci.get_job_logs"],  // ≤ 100
-  format: "compact",                             // or "json"
+  format: "compact",                             // or "json" / "typescript"
   fullDescriptions: false,
 });
 ```
@@ -265,8 +314,11 @@ canonical addresses. More than 100 addresses is `invalid_args`, and the same
 256,000-byte ceiling applies. Compact describe keeps property prose within a
 separate 8,192-byte UTF-8 shape cap and shares search's 2,000-visit budget; a
 capped shape sets `inputSchemaTruncated` or `outputSchemaTruncated`, and
-`format: "json"` gives the exact schema. A success whose output shape came from
-`S9` carries `outputSchemaSource: "observed"`.
+`format: "json"` gives the exact schema. `format: "typescript"` returns a
+`signature` instead of both schema fields, under the same 8,192-byte cap per
+half with property prose as JSDoc. A success whose output shape came from
+`S9` carries `outputSchemaSource: "observed"`, and a TypeScript signature also
+says so inside its `Promise<…>`.
 
 ### connecta.call
 
@@ -282,7 +334,9 @@ is treated as `{}`.
 
 **S6.** Every call goes through the same catalog, fail-closed read-only
 predicate, admission, credential containment, timeout classification, health
-accounting, and activity recording as an ordinary meta-tool call. The sandbox is
+accounting, and activity recording as an ordinary meta-tool call. The predicate
+decides whether a call runs or pauses (`W1`); nothing a program does decides
+it. The sandbox is
 an additional containment layer, not a second implementation of the boundary,
 and nothing a program does widens what it can reach.
 
@@ -359,10 +413,11 @@ caller what to do next, and never invents a cause it was not told.
 | --- | --- | --- |
 | `unknown_address` | no connector owns the address | false |
 | `unknown_tool` | the connector has no such tool | false |
-| `destructive_tool_requires_approval` | the tool is not explicitly read-only | false |
+| `destructive_tool_requires_approval` | the tool is not explicitly read-only and the deployment has no resumable writes (`E4`) | false |
 | `auth_required` | the credential is missing, expired, or rejected | false |
 | `invalid_args` | arguments or discovery bounds were rejected | false |
 | `not_found` | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap | false |
+| `conflict` | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | false |
 | `input_required_unsupported` | a downstream asked for mid-call input | false |
 | `rate_limited` | the downstream reported a rate limit | true |
 | `unavailable` | the downstream is down or unreachable; optional sanitized `details.host` and `details.code` describe the transport failure without paths, queries, credentials, or provider prose | true |
@@ -372,7 +427,20 @@ caller what to do next, and never invents a cause it was not told.
 | `catalog_lookup_failed` | the connector's catalog could not be loaded | per cause |
 | `result_processing_failed` | the result could not be prepared | per message |
 | `result_too_large` | a discovery response exceeded its byte bound | false |
-| `budget_exceeded` | the run exhausted a host-call or emitted-output budget | false |
+| `budget_exceeded` | the run exhausted a host-call, write, or emitted-output budget | false |
+| `execution_paused` | the run already stopped at a write that needs approval; no further call is made (`W1`) | false |
+| `pending_write_too_large` | a write's arguments are over 16 KiB serialized, too large to hold for approval (`W2`) | false |
+| `journal_too_large` | the run's source and recorded calls are over 4 MiB, too much to pause (`W3`) | false |
+| `write_outcome_unknown` | a write was sent and no answer came back; it is never sent again (`W9`) | false |
+| `execution_interrupted` | a resumed play sent writes and then ended without pausing, or storage failed under it; the run cannot be resumed (`W5`) | false |
+| `execution_diverged` | a replay stopped matching its journal (`W8`) | false |
+| `execution_claim_lost` | another `resume_execution` took the run over mid-play (`W5`) | false |
+| `approval_mismatch` | `resume_execution` did not repeat the paused write exactly (`W4`) | false |
+| `execution_token_stale` | the token names an earlier pause of a run that has moved on (`W4`) | false |
+| `execution_in_progress` | another `resume_execution` is playing the run (`W5`) | true |
+| `execution_expired` | the paused run outlived `execute.pausedRunTtlSeconds`, or reached another write after it (`W3`) | false |
+| `execution_not_found` | no paused run matches the token in this caller's partition and pool (`W3`) | false |
+| `resumable_writes_unavailable` | the deployment has no resumable writes, so nothing can be resumed (`W11`) | false |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -380,17 +448,20 @@ caller what to do next, and never invents a cause it was not told.
 sentence. A program cannot recover credentials — only an operator can — so stop
 and let the failure reach the model.
 
-**E4.** An unannotated, write-capable, or destructive tool stays refused with
-`destructive_tool_requires_approval`; `nextAction` carries its canonical address
-to `call_destructive_tool`, plus the original arguments when they fit the
-512-byte echo budget — whole or not at all, since a clipped copy is a different
-call. The model's short `reason` for the human reviewer grants no authority,
-never goes downstream, and generated code cannot mint the capability.
+**E4.** An unannotated, write-capable, or destructive tool never runs unasked:
+it pauses the run (`W1`), or, without resumable writes, is refused with
+`destructive_tool_requires_approval`, `nextAction` carrying its canonical
+address to `call_destructive_tool` plus the original arguments when they fit
+the 512-byte echo budget — whole or not at all, since a clipped copy is a
+different call. The model's short `reason` grants no authority and never goes
+downstream, and generated code can neither mint the capability nor approve its
+own write.
 
 **E5.** Failures of the *execution*, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
 `retryAfterMs`), cancellation (`executor_cancelled`), shutdown
-(`executor_closed`), deadline expiry, and sandbox crashes end the run and reach
+(`executor_closed`), deadline expiry, an executor that never settles (`L3`),
+and sandbox crashes end the run and reach
 the model as an error result. One seam: a host call still in flight when the run
 is cancelled fails with `cancelled`, catchable on the way out but never worth
 acting on (`Y3`). When shutdown tears down a program that had already started,
@@ -582,12 +653,25 @@ block runs — a cancelled QuickJS child is terminated outright. Write programs
 that need no cleanup.
 
 **L2.** What cancellation guarantees: in-flight host calls abort, no further
-host call is admitted, the admission lease is released, and nothing
-request-bound survives the request.
+host call is admitted — `search` and `describe` included, which fail
+`cancelled` rather than go on loading catalogs — the response returns
+`executor_cancelled` without waiting for the executor to settle, or for an
+`acquire()` that ignores the signal to grant, the admission lease is released
+(a lease granted after the run gave up is released on arrival), and nothing
+request-bound survives the request. Whether the program itself stops is the
+executor's (`X3`).
 
 **L3.** Every execution runs under a wall-clock deadline that includes time
 spent waiting on host calls. Expiry ends the run with an execution error and no
-partial result; the deadline's length is executor configuration (`X1`).
+partial result; the deadline's length is executor configuration (`X1`). Above
+it sits a ceiling connecta enforces outside the sandbox, `execute.watchdogMs`
+(120 s by default, above both executors' own deadlines), because an executor's
+deadline may live inside the sandbox it is meant to stop: a wedged Dynamic
+Worker never fires its in-isolate timer. A run whose executor has not settled
+by the ceiling ends as a non-retryable `executor_failed` whose message calls
+the sandbox unresponsive, with no partial result, and its admission lease is
+released, so wedged runs cannot fill the code pool. Raising an executor's
+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:
@@ -595,6 +679,7 @@ because connecta enforces them above the sandbox:
 | Bound | Value |
 | --- | --- |
 | Host calls per execution, shared by `search`, `describe`, and `call` | 20 by default, `execute.maxHostCalls` |
+| Writes per run, 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 |
@@ -609,7 +694,10 @@ unknown tools, catalog failures, and other pre-dispatch refusals cost what a
 successful call costs; catching a refusal does not refund it. `search` and
 `describe` likewise spend on entry. Exhausting the budget fails that call with
 non-retryable `budget_exceeded` (`E2`) and a message naming the budget. No
-connector is reached, and the budget does not refill inside one execution.
+connector is reached, and the budget does not refill inside one execution. A
+replay (`W6`) spends both budgets again for every call it answers from the
+journal, so one play's totals are the run's totals and nothing is counted
+twice.
 
 **L5.** The guest is memory-, stack-, and CPU-bounded, and a program that
 exhausts a bound ends the run with an error instead of degrading the host. The
@@ -651,9 +739,12 @@ refuses that attempt above the invocation path, so it is charged but records no
 event.
 
 **V2.** Each event carries `connectorId`, `toolName`, `address`, `source`,
-`outcome` (`success`, `error`, `timeout`, `cancelled`), `durationMs`,
-`attempts`, and `errorCode` when the call *failed* — plus request, actor, and
-server identity. Typed codes derive an optional `friction`: `tool_not_found`,
+`outcome` (`success`, `error`, `timeout`, `cancelled`, `paused`, `approved`),
+`durationMs`, `attempts`, and `errorCode` when the call *failed* — plus
+request, actor, and server identity. `paused` and `approved` name the write a
+run stopped at and the one `resume_execution` approved, with zero attempts;
+an approval adds `approval: "call" | "tool"`, never the arguments. A resumed
+play's live calls carry `source: "resume_execution"`. Typed codes derive an optional `friction`: `tool_not_found`,
 `schema_retry`, `destructive_reroute`, or `auth_required`. The fifth class,
 `result_too_large`, cannot reach an `execute_code` event: it belongs to a
 `call_tool` result too large to return inline, and a program's own return is
@@ -674,6 +765,114 @@ payload-free *by construction* means the event has nowhere to put a payload.
 distinctive artifact is the program source — exactly what a payload-free history
 must never keep.
 
+**V5.** A replayed call records nothing: it was recorded when it happened, and
+a second event would count one call twice. Nor does a call refused because its
+run had already stopped, which was never an attempt.
+
+## Pausing and resuming
+
+A program pauses host-side at its first write needing approval;
+`resume_execution` repeats that write to approve it, and the run replays from a
+journal to send it and carry on. A paused run is data, not a held program, so a
+restart loses nothing
+([#565](https://github.com/zackbart/connecta/issues/565)); `ExecuteResult` and
+the executor duties are unchanged.
+
+**W1.** A call to a tool not explicitly read-only reaches the run's write gate
+after validation and before admission, so nobody approves arguments the schema
+rejects and a pause costs no permit. Unless an approval covers it, it is not
+sent: it rejects `execution_paused`, as does every later host call —
+unjournaled, unrecorded — while calls in flight finish and are journaled; one
+of those turning unknown fails the run instead (`W9`). The program's result is
+discarded, and a write that reaches the gate after it settles is not sent.
+Calls are numbered in issue order and a write decides only after every
+lower-numbered call has, so the pause point is reproducible.
+
+**W2.** The pause is a success: `{ paused: { address, args, token, expiresAt,
+nextAction, hint } }`, `address` canonical and `args` whole, because the host
+shows the human exactly those; `nextAction` is the resume call. Arguments over
+16 KiB stop the run `pending_write_too_large`, nothing journaled; non-object
+arguments keep `E4`; a `__proto__` key is refused `invalid_args`, since a layer
+between program, host, and human could drop it and approve a different write.
+
+**W3.** The journal lives in the caller's result storage — the `get_result`
+stash's partition and trust level — and records the `/mcp/<pool>`: source,
+every host call and its answer, the `P6` clock and seed, and one header, the
+only key compared-and-set. Over 4 MiB fails `journal_too_large`. It expires
+`execute.pausedRunTtlSeconds` (default 1,800) after the first pause, and later
+pauses keep that deadline, so no replay mixes old reads with new. Another
+subject or pool finds no run.
+
+**W4.** `resume_execution` takes `token`, `address`, `args`, optional
+`approval`, and a dropped `reason`. Address and args must match the pending
+write as JSON, key order aside, with no `__proto__` key; otherwise it returns
+`approval_mismatch`. That, `execution_token_stale` (current pause),
+`execution_in_progress` (live claim), `execution_expired` (counts if writes
+were sent), and `execution_not_found` refuse before the claim, spending nothing.
+A repeat returns the ended run's answer past expiry; oversized text or emitted blocks get a completion receipt instead.
+
+**W5.** An approved write is sent at most once. Resuming claims the run by
+compare-and-set; a racing resume gets `execution_in_progress`. Each live write
+is first marked `sending` on the header, and a claim found moved sends nothing
+further and stops `execution_claim_lost`. The header outlives `expiresAt` while
+a claim is live, and by 30 minutes once a write was sent. A storage call over
+its deadline (the host call's, at least 5 s) fails: before dispatch nothing is
+sent, after it the run stops with the write counted. Replay picks up only at a
+pause: a play ended otherwise — executor failure (admission, cancellation, the
+`L3` watchdog) or a lapsed claim — returns to its pause only if it sent no
+write; a write left `sending` fails `write_outcome_unknown`, and sent writes
+fail `execution_interrupted`, the reads after them never journaled.
+
+**W6.** A replay runs from the top on the journal's clock and seed. A recorded
+call — matched by operation, address as written, and canonical arguments, in
+first issue order per key — is answered before the rest of the call path: no
+catalog, permit, connector, or activity (`V5`). A hit is never the pending
+call, which is not journaled. The approved write and everything after it go
+live. `emit` is not journaled; only the completing play delivers.
+
+**W7.** `approval: "call"`, the default, covers that one write; `"tool"` covers
+every later call to that canonical address for the run. Approvals live in the
+header, a retry's replacing one that sent nothing; nothing else grants one.
+
+**W8.** A replay fails `execution_diverged`, never replayed again, when (a) a
+call has no record before the approved write is repeated, (b) the program
+finishes without repeating it, or (c) without repeating a write already sent.
+
+**W9.** A write sent and never answered fails the run `write_outcome_unknown`
+wherever it is found — beside a pause, after the program returned, at a
+takeover — with its address, its args within the 512-byte echo budget, and
+`writes: { succeeded, failed, unknown }`; a failed run is never replayed. Only
+a refusal (`auth_required`, `invalid_args`, `not_found`, `rate_limited`,
+`conflict`) or the
+tool's own `isError` answers; an `isError` reading as a timeout does not, and
+`connector_call_failed` — an oversized body, a refused redirect — may come
+after the write landed. Every error from a resumed play carries `writes`, and
+once one landed or may have, `nextAction` says to check first; a program that
+throws after writing ends the run `failed` with them.
+
+**W10.** `execute.maxWrites` (default 10) bounds a run's writes beyond the host
+calls they spend, checked at the gate — so an over-budget write fails
+`budget_exceeded` instead of asking — and spent at dispatch.
+
+**W11.** Without resumable writes — storage without `compareAndSet`, or
+`execute.resumableWrites: false` — `E4` stands and `resume_execution` answers
+`resumable_writes_unavailable`.
+
+**W12.** Config may exempt a write from asking, and nothing else may
+([#566](https://github.com/zackbart/connecta/issues/566)). `execute.approval`
+maps connector ids and `connector.tool` addresses to `"never"` or `"ask"`; the
+address wins over the connector entry, which wins over a connector's own
+built-in default (reserved for connectors connecta ships), which wins over
+`"ask"`. An exempt call is decided at the same gate as `W1` and dispatches
+instead of pausing, with everything else an approved write gets: the write
+budget (`W10`), the write-ahead mark (`W5`), the journal, a `V1` event. Without
+resumable writes, other writes keep `E4`; an exempt one still finishes after
+the program returns, never hiding an unknown outcome (`W9`). Exempt is never
+read-only: no read-only tool is reported exempt, discovery keeps an exempt tool
+approval-required, `call_tool` refuses it, and no annotation grants it, or a
+downstream could exempt itself. Unknown connectors and `api()` addresses its
+tools lack refuse to construct; an unserved remote address never matches.
+
 ## Executor exceptions
 
 Documented divergences, with reasons. Everything else must match.
@@ -688,10 +887,15 @@ and guest-CPU limits (`L5`); the Dynamic Worker has no such knobs, so workerd's
 isolate limits apply untuned. A specific heap ceiling is a Node-only option.
 
 **X3. Mid-flight cancellation.** The QuickJS pool receives the request's
-`AbortSignal` and kills the child. The Dynamic Worker executor's `execute()`
-takes no signal, so a cancelled request's program runs on until its host calls
-fail or the deadline expires. `L2` holds either way — the calls abort, the
-response does not wait — but "the run ends" is best-effort on Workers.
+`AbortSignal` and kills the child — SIGTERM, then SIGKILL if it has not exited
+within a second — and releasing a lease whose child is still running recycles
+that child, so a run the watchdog abandons (`L3`) ends too.
+The Dynamic Worker executor's `execute()` takes no signal, so a cancelled or
+abandoned program runs on in its isolate until its host calls fail or its own
+deadline expires. `L2` and `L3` hold either way — the calls abort, connecta
+stops awaiting the executor and frees the admission slot — but "the run ends"
+is best-effort on Workers, and for that tail the code pool bounds what
+connecta is waiting on, not what the platform is still running.
 
 **X4. Log rendering and capture.** QuickJS JSON-stringifies non-string arguments
 and captures `log`, `info`, `warn`, `error`, and `debug`; the Dynamic Worker
@@ -708,8 +912,8 @@ starts has no guest logs to recover.
 
 **X5. Leftover authority.** QuickJS blocks imports and has no `fetch`,
 `process`, timers, `crypto`, or `WebSocket`, and its Node child starts with an
-explicitly empty process environment rather than inheriting deployment variables
-or `NODE_OPTIONS`. A Dynamic Worker has those globals plus a non-contract set of
+explicit environment holding only `TZ=UTC` (`P6`) rather than inheriting
+deployment variables or `NODE_OPTIONS`. A Dynamic Worker has those globals plus a non-contract set of
 runtime builtins through `import()` and `process.getBuiltinModule()`, including
 `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`,
 and `cloudflare:workers`; the upstream set drifts, so that is not an allowlist.
@@ -753,6 +957,12 @@ none, because that boundary is an isolate-to-isolate call rather than a
 one tool call therefore fails on Node and may succeed on Workers — reduce inside
 the program either way (`R1`).
 
+**X12. A paused sandbox.** QuickJS stops: releasing the lease with the child
+still running recycles it (`X3`). A Dynamic Worker cannot be interrupted, so a
+paused program runs on until it settles or its deadline expires, every host
+call failing `execution_paused`. Connecta stops awaiting it at the pause and
+discards whatever it returns.
+
 **X11. Typed host rejection.** Both executors rebuild Connecta's authenticated
 host-failure frame as a thrown guest `Error` (`E1`). The per-run secret stays in
 the trusted prelude closure and the prelude locks `globalThis.Error`, so guest
@@ -776,20 +986,21 @@ passing one table is also the check on the executor duties above, with
 
 | Clauses | Test |
 | --- | --- |
-| `P1`, `P5` | `test/guest-api-contract.test.ts` (TypeScript syntax), `test/quickjs-executor.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.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.test.ts` (empty child-process environment), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
+| `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.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.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.test.ts` (a child-process environment holding only `TZ=UTC`), `test/deployment-shapes.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) |
+| `P6` | `test/guest-api-contract.test.ts` (a frozen clock across host calls, the seeded sfc32 stream against a reference, locked replacements, Workers `crypto` and `performance` pinned directly and through their prototypes, `Intl` "now" and UTC local time on both executors, a fresh pair per run, and a replay drawing the same values), `test/resumable-restart.test.ts` (the same draws after a restart) |
 | `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) |
+| `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.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, budget, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.test.ts` (oversized messages, private transport, forged frames) |
 | `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) |
-| `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery), `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) |
+| `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/resumable.test.ts` (the refusal without resumable writes) |
 | `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.test.ts` (mid-run shutdown) |
 | `E6`, `X8` | `test/guest-api-contract.test.ts` (unknown and inherited members, wrapped-message precedence), `test/quickjs-executor.test.ts` |
 | `E7` | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts` |
@@ -799,12 +1010,21 @@ passing one table is also the check on the executor duties above, with
 | `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) |
-| `L3`, `X1` | `test/guest-api-contract.test.ts` (short-deadline executors) |
+| `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) |
 | `L5`, `L7`, `X2` | `test/quickjs-executor.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue) |
 | `L6`, `X10` | `test/quickjs-executor.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.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) |
+| `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, `paused` and `approved` events), `test/activity.test.ts` (the shared code → friction table, the identity clamp, zero-attempt pauses and approvals) |
+| `V5` | `test/resumable.test.ts` (replay adds only the approval and the live write), `test/guest-api-contract.test.ts` |
+| `W1`, `W2` | `test/guest-api-contract.test.ts` (nothing after a pause gets through, a `__proto__` write refused, on both executors), `test/resumable.test.ts` (the pause shape, reproducible pause points, oversized pending writes, a write gated after the program returned), `test/invocation-pipeline.test.ts` (the gate after validation) |
+| `W3`, `W4` | `test/resumable.test.ts` (header layout, byte bound, expiry, not-found, pool isolation, exact-match refusals that consume nothing, a `__proto__` repetition through the MCP schema, a repeated resume and emitted-content receipt, an expired run's counts) |
+| `W5` | `test/resumable.test.ts` (two resumes racing for a pause, a crashed claimant's `sending` write never sent, a lapsed claim taken over, a claim lost mid-play and the write it sent reported, executor failure returning to the pause, a cut-short or lapsed play that sent writes failing `execution_interrupted`, a claim outliving `expiresAt`, a live or lapsed claim checked before expiry, a failed takeover's answer stored with it, storage that never answers before and after dispatch, a deadline between mark and dispatch) |
+| `W6`, `W7` | `test/guest-api-contract.test.ts` (replay on both executors), `test/resumable.test.ts` (no catalog, connector, or activity traffic for replayed calls; call and tool scope, a retry's scope replacing an unused approval, a hit never taken for the pending call), `test/resumable-restart.test.ts` (across a restart) |
+| `W8`–`W10` | `test/resumable.test.ts` (divergence (a)–(c), each unknown-outcome path never re-sent — beside a concurrent pause, after the program returned, a post-response connector error — a known failure the program handles, the classification table, check-first advice once a write landed, the write budget) |
+| `W11` | `test/code-first-surface.test.ts`, `test/resumable.test.ts` (construction, the default, `/health`, the unavailable answer) |
+| `W12` | `test/resumable.test.ts` (an exempt write runs where the same program otherwise pauses, precedence and a connector default switched off, the write budget, resumable writes off, an unawaited exempt write finished and its unknown outcome reported, journaled and never re-sent, an exempt write's count past expiry, `call_tool` still refusing, search and describe markers, construction refusals), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge) |
+| `X12` | `test/guest-api-contract.test.ts` (a program that keeps calling after the pause, on both executors) |
 | `M1` | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (every rejected shape) |
 | `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.test.ts` (mid-run shutdown) |
@@ -812,10 +1032,8 @@ passing one table is also the check on the executor duties above, with
 | `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.test.ts` (logs before cancellation), `test/quickjs-child-stderr.test.ts` (crash, shutdown, deadline, IPC failure, bounded parent retention), `test/quickjs-log-limits.test.ts` (unchanged successful logs) |
-| `X3`, `X6` | `test/quickjs-executor.test.ts` (cancels a running child, never-settling await) |
+| `X3`, `X6` | `test/quickjs-executor.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 seven-tool
-list) and `test/code-first-surface.test.ts` (the fold's construction rules, the
-required executor, the refusals a removed top-level tool now gets, copy, and
-measured size).
+The surface itself is checked by `test/server.test.ts` (the exact eight-tool list) and
+`test/code-first-surface.test.ts` (construction, executor, removed tools, copy, and size).