@zackbart/connecta 0.40.0 → 0.42.0

package/CHANGELOG.md

@@ -2,6 +2,154 @@
 
 All notable changes to this package are documented here.
 
+## 0.42.0 — 2026-11-05
+
+This release makes Connecta easier for agents to use: shorter served text, failures that name the next step, a read-only program route, and better discovery. Six breaking changes can alter how existing clients or deployments behave, so check them before upgrading.
+
+**Breaking:** A deployment `classification` override to `"read"` no longer applies to a tool whose source declares a write. That tool stays a write on every surface, so its calls prompt on hosts that prompt, a direct `call_tool` is refused, and a read-only pool loses it. Remove the override, or change it to the new `"read-repeatable"` if you have checked that a repeat is harmless. Native pool writes are now named `<connector>__WRITE__<tool>`, or a hashed form of it, so update anything that hardcodes a native write's name, such as host approval rules, allowlists and prompts. `execute.watchdogMs` now defaults to 55 s (was 120 s) and caps direct calls, and `workerExecutor()` defaults to a 50 s timeout and a 40 s queue deadline; raise them only below your clients' own request limit. GitHub answers a resource HTTP 403 as `provider_permission_denied` instead of `auth_required`, without a credential handoff. A `skills` fetch returns its text once, in `content`, not in `structuredContent.text`. `@zackbart/connecta-eve` now requires exactly Eve `1.0.0-rc.4` as its peer; its README lists what that brings to your app, including a default `edit_file` tool to gate wherever `write_file` is gated.
+
+**Reads and programs:** Writable `/mcp` and `/mcp/<pool>` endpoints now list a seventh meta tool, `execute_read_code`, annotated read-only and refusing every write before dispatch, so hosts that gate on annotations can run read-only programs without a write approval. Set `execute: { readRoute: false }` to turn it off, and read the read programs section in `documentation/meta-tools.md` first: such a program runs unprompted on hosts that auto-approve reads, and a read tool that takes a URL or query can carry data out in its arguments. `connecta.result(handleOrId, { all: true })` reads a retained result whole up to 1.5 MiB. A direct read over its inline cap can now answer with a sample in the result's own shape rather than its first bytes, so a client that parses a truncated direct result should not assume the body is a prefix of the result.
+
+**Failures and recovery:** Failure messages now give the exact next step, and anything branching on `nextAction.tool === "authorize_connector"` must also accept the new handoff shapes. A program that may have written warns against rerunning it, program writes report how they failed in `unknownWrites`, and a tool's `isError` text now reaches agents up to 4,096 UTF-8 bytes. Program errors and timeouts arrive as typed failures before MCP clients give up on the request. A QuickJS crash that could cost a run its answer, or the next request, is fixed.
+
+**Discovery:** Served instructions and tool descriptions are shorter, and connector guides now hold only provider-specific facts. Search ranks partial matches by the rarity of the query words they cover, so a hatch's common verb no longer hides a named tool. A connector that does not answer in time keeps its tools in discovery from its last complete catalog, marked `stale: true`. The `execute_code` inventory can show each connector's configured description as a short purpose.
+
+Deployments without these overrides, native write names, longer client timeouts or the Eve helper need no configuration changes.
+
+### Added
+
+- The `execute_code` connector inventory now adds each connector's configured description as a one-line purpose, capped at 60 UTF-8 bytes. Purposes are the first detail dropped under the inventory's 1,024-byte cap, and they never appear in the server instructions.
+- Add an eval-only Eve runner using local ChatGPT subscription models, the Connecta Eve helper, deferred tool traces, and the existing task graders on Node and Workers, across every eval surface, with a configurable connection name and description.
+- Teach Eve agents how to reach Connecta tools: `connectaInstructions` now places an Eve guide before the server's text, with a `connection` option for connections not named `connecta`. `connectaConnection`'s `description` is optional and warns when it carries no domain information, both factories accept `headers`, and the helper warns on release skew. Discovery and `initialize` advertise caller-scoped endpoint facts in `capabilities.extensions["dev.connecta/endpoint"]`.
+- Writable `/mcp` and `/mcp/<pool>` endpoints now list a seventh meta tool, `execute_read_code`, annotated read-only, so hosts that gate on annotations need no write approval for read-only programs. It has the same guest API, sandbox and connector inventory as `execute_code`, and refuses every call whose effective or source class is write before dispatch, with the next step and zero writes, whether or not the program catches the refusal. A tool set to `"read-repeatable"` runs there, since the deployment accepted that hosts may repeat it. Discovery inside it lists writes with `callable: false`. Handles from direct reads and read programs page from it. Read-only endpoints, `/agent/<pool>` and native pools are unchanged. `execute: { readRoute: false }` turns it off. Activity records source `execute_read_code`. A read program runs unprompted on hosts that auto-approve reads, and a read tool that takes a URL or query can carry data out in its arguments: see the read programs section in `documentation/meta-tools.md`.
+- GitHub's reviewed read allowlist now covers check runs, check suites, check-run annotations and commit statuses. These reads require the App to hold Checks read or Commit statuses read; an App without them fails only those reads, with a typed permission failure, until the permission is granted.
+- Add twelve hard-discovery eval tasks over a shared 110-tool catalog, with no-model controls on every arm and target.
+- Add eval arms for host-native search and five meta-tools, deterministic catalog padding, and first-request and discovery efficiency telemetry, per-trial distractor reporting, and an explicit list of tasks the no-code arm cannot be compared on.
+- Add `connecta.result(handleOrId, { all: true })`, which reads a retained result whole as `{ data, format }` for one host call up to a read ceiling of 1.5 MiB (scaled with `cpuTimeMs` on QuickJS, and declared by the new optional `Executor.maxReadBytes`), and throws a catchable `result_too_large` above it. A read's finished transfer now gives its stash back, up to three per run within a one-second budget, leaving the run's unsealed ledger first. Handles within the ceiling now say to read whole. Migration: an oversized program return's `nextAction` now reads whole and marks where to reduce, instead of returning a 3,829-byte page, so code that parses that action's output as a page should read `connecta.result` with `{ offset }` instead.
+- `classification` accepts a new value, `"read-repeatable"`, the migration path for a deployment that overrode a vendor-declared write to `"read"` on purpose. The deployment has checked the tool and accepts that hosts may repeat it, so it serves as a read on every route: read annotations, read-only endpoints, `call_tool`, programs and its plain native name. A host's resend after a connection failure can reach the vendor twice. Connecta still sends it at most once and never replays it after an authorization failure. Plain `"read"` is unchanged: it does not apply over a declared write, so a vendor that later declares one fails safe.
+- Add eval-only native and native-without-code pool arms for Worker comparisons, with native call evidence and surface controls.
+
+### Changed
+
+- Failure messages now give the exact next step in one read. An auth error that carries a handoff says so in `nextAction` (`{ url, purpose }`, or `{ action: "contact_operator", purpose }` when there is no link) instead of sending the agent to `authorize_connector` for the same thing, and its `instructions` address the person opening the link; `authorizationUrl`, `operatorUrl`, `credential` and `instructions` keep their meaning, and anything branching on `nextAction.tool === "authorize_connector"` must also accept the new shapes. A program that finishes with nothing to read gets a `note`, which after a write says not to rerun it; an unawaited read in a program that finished gets the await hint there too. A truncated direct read offers a `connecta.result` loop over the retained result in one program when that fits the host-call budget, and repeats the read otherwise; a paged handle offers that loop on the same terms, counting the calls its program has left, and otherwise bounds the pages per program. Budget, write-outcome, read-only, unknown-tool, empty-search, program-error and direct-call-shape messages name what to do next; `invalid_args` with complete findings no longer sends the agent to search first, and its example uses a named placeholder rather than an empty string. The `usage` paging example no longer sets `maxBytes`, which could exhaust the host-call budget.
+- **Breaking:** Shrink every maintained connector guide to provider-specific facts. Generic paging, `fields`, withheld-value and write-once rules now live in the `cursor`, `page` and `fields` schemas and the `write_outcome_unknown` error; a hatch page that cannot continue adds an incomplete-result warning; and a read-only connection is no longer served its guide's write rules. A `skills` fetch now returns its text once, in `content`, as documented, so a client reading `structuredContent.text` from that fetch must read `content`; the tool advertises no `outputSchema`.
+- **Breaking:** `@zackbart/connecta-eve` now requires exactly Eve `1.0.0-rc.4` as its peer. Update the app to `eve@1.0.0-rc.4`, reinstall, rebuild and test before deploying; helper authoring is unchanged. Eve's own changes reach the app: a deployment from before rc.3 cannot take over sessions rc.3 or later wrote, so plan rollbacks around that; every agent gains a default `edit_file` tool, so gate it wherever `write_file` is gated; and builds now reject `nitro/storage`, `nitro/kv`, `nitro/database` and asset imports that leave the authored package. The helper's README lists them with the release notes.
+- **Breaking:** Answer before MCP clients give up, so an agent gets a typed `timeout` or `write_outcome_unknown` with `hostCalls` and `writes` rather than a transport `The operation timed out`. Claude Code and Codex both give one request 60 s by default. `execute.watchdogMs` now defaults to 55 s (was 120 s), counts from the request's arrival so queueing spends it, and caps direct `call_tool`/`call_destructive_tool` deadlines, including an explicit `timeoutMs` or `calls.defaultTimeoutMs`. `workerExecutor()` now defaults to a 50 s `timeout` (was 60 s) and a 40 s queue deadline (was 60 s); `quickJsExecutor()` keeps 30 s. A run cut short by the ceiling rather than wedged fails as a `timeout` at stage `response ceiling`, retryable unless a write in it landed. Any program error is now non-retryable and drops `retryAfterMs` once a write in the run has landed, because running the program again would repeat it. A run or direct call with no time left is refused unsent, and a call whose time runs out during catalog resolution, admission or auth is refused unsent by a check immediately before dispatch. On Node, the ceiling also counts the request's upload. Storage after a run stops waiting 2 s past the ceiling at most, so a stalled store costs an oversized return its paging, not its answer.
+  
+  Migration: if your clients allow longer requests (`MCP_TOOL_TIMEOUT`, a server's `timeout`, `tool_timeout_sec`) and your programs or direct calls need the time, set `execute.watchdogMs` a margin below that limit, then raise `workerExecutor({ timeout })` or `quickJsExecutor({ timeoutMs })` below it. Construction warns when an executor's deadline is not below `execute.watchdogMs`.
+- End program reads just before the executor's run deadline, so a slow read becomes a catchable, retryable `timeout` and `Promise.allSettled` keeps every result that finished. Executors may publish `deadlineMs`; `quickJsExecutor()` and `workerExecutor()` do, and `execute_code` states it as `<n>s/run`. Writes stay exempt so a drained write's outcome is still learned, and a write that reaches its gate after reads have stopped is refused unsent.
+- Remove the contributor policy limiting Opus agents.
+- A direct read over its inline cap (24,000 bytes unless a connector overrides it) on a surface with `execute_code` can now answer with a sample instead of its first bytes: for rows, the row count, keys and whole first rows as valid JSON in the result's own shape; for text, the line count, head and tail. Its notice says which rows or bytes it holds and that the rest are not shown, and carries `resultId`, the original `totalBytes`, a `nextAction` program over the retained result, and the fallback when that program is refused. A program's value and the paged handle are unchanged. Results at or under the cap return whole, as before. Migration: a client that parses a truncated direct result should not assume the body after the notice is a prefix of the result: `nextOffset` is 0 and the body is a separate view, showing less than first bytes did. Writes, including a source write a deployment overrode to read, value mode, several or non-text blocks, native pools with `executeCode: false`, results with numbers `JSON.parse` would change, and any shape the rule does not cover keep their first bytes. A source write overridden to read now also says its write already ran and is no longer told to repeat the read inside a program. A `fields` miss warning is shorter: `fields/0 matched nothing after filtering, at segment 1; declared there: id, name.`, with at most 160 characters of names, and a later miss at the same place says `same as fields/0`.
+- A program's retained results are now unreadable from other requests until they pass the run's complete secret set. At its end a run waits for its host calls and credential reads to finish within the response's answer-by time, then publishes each entry that passes. A run pays no extra storage, and reads stored bytes back only for entries the set grew past. Stored bytes are never rewritten, so an offset issued during the run stays valid. An entry that matched, or could not be checked or written, stays unreadable: paging it from a later request answers `result_not_retained` with `retryable: false`, a read told to rerun and a write told not to repeat, and the run's response carries a `note` saying so. Paging inside the run is unchanged, and direct-call stashes keep passing their own request's set when stored.
+- `tools/list` now advertises open output schemas for `execute_code`, `search_tools` and `authorize_connector`: required keys and top-level types, with every other field open. Served results are unchanged, and the server still validates each successful one against the full contract before sending it. A client that read the closed schema or `$defs.failure` from `tools/list` finds the failure and handoff shape in `documentation/meta-tools.md`.
+- **Breaking:** A deployment `classification` override to `"read"` no longer applies to a tool whose source explicitly declares a write (`readOnlyHint: false`, `destructiveHint: true`, or contradictory hints). Such a tool stays a write on every surface and is never served read-annotated, because a host may resend a read-annotated call after a connection failure, which duplicated physical writes. Where the source is silent, `"read"` still serves as a read, and setting it asserts the call is safe to repeat.
+  
+  **Migration:** if you overrode a vendor-declared write to `"read"`, an operator warning now names that override once per catalog change. Its calls prompt on hosts that prompt, and a direct `call_tool` is refused with the next step, naming `call_destructive_tool`. Native pools list it as destructive. Read-only endpoints and connectors omit and refuse it, so a read-only pool loses it. Remove the override, or, if you have checked the tool and a repeat is harmless, change it to `"read-repeatable"`. `"write"` and `"hidden"` overrides are unchanged.
+- Shorten the MCP instructions and tool descriptions served to agents. Meta instructions now open with the caller's admitted connector ids; `skills` and `connecta.skill` return a local guide's body without frontmatter; the connector inventory marks required guides with `*` and no longer names optional ones.
+
+### Fixed
+
+- Raise the root bundle cap so main passes after two changes that each fit it alone.
+- Stop the required CI gate failing when the jobs API trails completed matrix legs.
+- Keep the required CI gate waiting while the jobs API still reports finished legs as queued.
+- A declined or cancelled URL elicitation now returns the verified connection handoff, so an agent on a client that refuses prompts automatically can give the user a working `/connect` link. The refusal text no longer implies that a person saw the prompt.
+- Stop eval graders failing correct refusals, handoffs and QuickBooks and CCB routes, and passing a handoff link altered inside a Markdown destination; make the QuickBooks journeys passable by following their prompts; harden Worker restarts against port collisions.
+- Stop build hooks rewriting unchanged generated sources, so they cannot reload a smoke under Wrangler, and report a Worker eval reload as an infrastructure error instead of a lost connection or host authorization failure. Freeze one verified Worker graph per eval batch, refusing a batch or comparison whose served sources differ from its label or its other arm.
+- A `force: true` connection flow now resets once across all of its links. URL elicitation `accept` does not mean a browser opened the link, so every link stays live: the first verified visit performs the reset and later visits continue it, without invalidating the first consent. A visit during a running start returns 409 without spending its link and says to start a new connection request if it persists, and a failed start lets the flow's next visit begin again. A declined or cancelled prompt's link now works alongside the refusal's link instead of being retired. An unforced flow's unspent links are no longer retired at completion, and a refusal whose link could not be issued now tells the agent how to get a new one. A link from an earlier version that names a predecessor link is refused and replaced by a new link.
+- **Breaking:** GitHub answers a resource HTTP 403 as `provider_permission_denied` instead of `auth_required`, without a credential handoff, naming the repository and any permission or scope GitHub reports. The message states possible causes without claiming the credential works or a grant is missing. Rate-limit 403s stay `rate_limited`, a 401 stays `auth_required`, and SAML enforcement is stated without its link. A refused token mint reports the typed gap only when GitHub's installation record lacks the requested permission; otherwise a 422 is `connector_call_failed` with vendor text withheld, and a mint 403 keeps its causes open. Repositories or owners outside the App's installation report `provider_permission_denied`. A 403 on the App's own installation list stays `auth_required`. Programs that branched on `auth_required` for these failures must branch on `provider_permission_denied`, and these failures no longer carry a credential handoff.
+- **Breaking:** A native pool's tool name now binds its classification, so a host resending a call it cached as read-only cannot write. Writes are named `<connector>__WRITE__<tool>`, or a hashed form of it; every read keeps the name it had, and a name stays stable until the tool's classification changes. A read name whose tool is now a write is refused before dispatch with `destructive_tool_requires_approval`, and `nextAction.tool` names the write. To migrate, take native names from `tools/list`, and change anything hardcoding a native write's name, such as host approval rules, allowlists, prompts and recipes, to the `__WRITE__` form. A host's cached list needs a refresh before it can call a write. `nativeToolName` now requires a classification. Addresses (`connector.tool`), programs and meta pools are unchanged.
+- Program writes no longer hide how they failed or leave altered. `write_outcome_unknown` now leads with the tool's words when a tool answered `isError`, and carries `unknownWrites` with each write's address, code and redacted message, plus `toolAnswered: true`; the outcome stays unknown and nothing is sent again. A tool's `isError` text now reaches every agent surface up to 4,096 UTF-8 bytes instead of 512, cut only between tokens and marked, so an approval link or request id arrives usable. A program's report is redacted against the run's final credentials before any cut and bounded per message, in total, and by `execute.maxResultChars`. A program write whose arguments hold a credential the request already sent is refused before dispatch with `invalid_args`, rather than sent with `[redacted]` in place of the match, which could first appear on a program's second call. Program arguments no longer match a credential's public prefix or an identifier sent beside it, so reads and writes naming them leave as written. Maintained providers now declare a header public from the vendor's contract, and only Cloudflare's Global API Key `X-Auth-Email` and Overflow's `x-client-id` are declared: the whole value stays withheld from output, but its fragments no longer match, so such a connection's domain survives in results. Every other header and query parameter stays fully protected whatever its name. Connecta's clips of tool errors, program failures and logs now end between tokens. Operator logs name a tool's own failure `DownstreamToolError` rather than `Error`.
+- Keep a QuickJS child alive when a program's memory grows during a job pass. A bug in `quickjs-emscripten-core` 0.32.0 aborted the child while freeing a finished run's runtime, which cost the run its answer, or the next request when a host call was still open. If freeing a runtime ever fails again, the run keeps its answer, a warning is logged and the child is replaced before it can take another run.
+- Stop a hatch's operation vocabulary hiding partial matches from named tools, and rank on what search shows. Search descriptions are now the first complete sentence with `descriptionTruncated: true` when cut, `connecta.describe` returns full text by default within a 32 KiB budget per call, a description's tail can no longer make a tool a complete match, titles are indexed, and a few abbreviations such as `env`/`environment` match. Partial matches score by the squared share of the query's rarity they cover, so rare words in a hatch's description outrank a common verb in another tool's name, and GitHub's hatch operations now count in main search as other hatches' already do.
+- Keep a slow connector's tools in discovery. When a connector does not answer an unscoped search or native `tools/list` in time, its last complete catalog, up to 24 hours past expiry, is listed and reported with `stale: true` and `ageMs` in `catalogErrors`. Calls still resolve the live catalog. An auth or permission refusal lists nothing and retires the catalog of the credential that attempt sent, in every isolate, until a listing begun after the refusal succeeds. A custom connector refused after its credential changed retires all of that connector's catalogs, since the credential it sent cannot be known. A downstream's retry delay is kept in `retryAfterMs`, and `connecta doctor` fails with "Native discovery degraded" when a native pool lists a connector stale. Cached and authored catalogs no longer wait for a probe slot, a timed-out probe refreshes its catalog in the runtime's tail, and a publish deletes the catalog revision it supersedes.
+
+## 0.41.0 — 2026-11-03
+
+This release fixes a production outage on Workers, tightens auth and network defaults, and makes warm requests cheaper. Three changes can stop an existing deployment at startup or at validation, so check them before upgrading.
+
+**Upgrade if you run Workers on `@cloudflare/codemode` 0.5.5 or later.** On Connecta 0.40.0, those codemode releases make every `execute_code` host call fail with "The code execution finished before this tool call settled". `workerExecutor()` now works with them. Deployments that pinned codemode to 0.5.4 to avoid this can drop the pin after upgrading; deployments that stay on 0.40.0 must keep it.
+
+**Breaking:** `clerkAuth` now requires a resolved `publicUrl`, set on `clerkAuth({ publicUrl })` or `ConnectaConfig.publicUrl`, and no longer falls back to the request origin. A configured vault must have `seal` and `open` when any connector has `startAuth`; use `encryptedCredentialVault(storage, key)` or add both methods, and existing plaintext grants are sealed on first read. Pool descriptions are limited to 500 UTF-16 code units after trimming. The public activity kind union adds `operation`, which affects exhaustive consumers of activity records.
+
+**Security:** learned OAuth URLs on non-public addresses are refused, including transitional IPv6 forms carrying non-public IPv4 addresses, learned Node URL connections are pinned to validated DNS answers, and the Node adapter answers `400` to a malformed `Host`, `X-Forwarded-Proto` or request target before reading the body. Pending OAuth flow records store less: with a sealing vault the consent URL, binding and PKCE verifier are sealed together, and with no vault the record keeps no consent URL, so a repeated start mints fresh consent. Sealed consents pending from 0.40.0 still complete; a legacy no-vault consent restarts fresh.
+
+**Performance:** warm catalog resolution locates manifests, negotiation and generation in one bounded read. Lexical indexes are reused across requests in an isolate, result-stash writes are batched, and last-seen observation skips redundant reads in its sampling window. Local-only skill catalogs now advertise a five-minute private TTL. Node gains a cap on request body bytes held in flight together, set with `listen(..., { maxInFlightBodyBytes })`. It defaults to the larger of 64 MiB and `maxBodyBytes`, and an explicit value must be at least `maxBodyBytes`; past it, requests get `503` with `Retry-After`.
+
+**Reliability and agent guidance:** a rejected Cloudflare Access identity lookup retries once within its original deadline and records payload-free diagnostics. API OAuth status now comes from typed call outcomes fenced by grant revision. Endpoint instructions lead with pool scope and the guide pointer and state the effective write policy, native tools point at connector guides, skills have readable names with legacy aliases, and downstream skill text is labeled with its third-party origin. Typed failures carry recovery steps across host, availability, utility and result-handle errors.
+
+**Opt-in, ignore unless you want them:** `activityHistory({ operations: true })` for payload-free operation history; `timingTraceSampleRate` for sampled payload-free MCP timing logs; QuickBooks `update_unsent_invoice`, enabled with `readOnly: false`, for sparse `DocNumber` updates on observed unsent US-company USD invoices, an inference from Intuit's documented autosend prerequisites and not a vendor no-email guarantee; and, in `@zackbart/connecta-eve`, a caller or turn `when` predicate on `connectaConnection` and `connectaInstructions`, plus `connectaSkill({ name, description, ... })` for deferred connector instructions as Eve skills.
+
+The downstream Skills extension remains Beta, and unknown Skills revisions are now rejected.
+
+### Added
+
+- Add opt-in sparse DocNumber updates for observed unsent US-company USD QuickBooks invoices, refusing unknown delivery state, enabled payments and stale versions.
+- **Breaking:** Opt in to payload-free operation history with activityHistory({ operations: true }). Search, describe, result, skill and whole-program rows use conservative scope and owner disclosure, remain detached from responses, and do not inflate call or friction counts. The public activity kind union adds operation, which may require updates to exhaustive consumers. Typed operation failures retain their checked codes, and activity reuses existing page byte measurements without serializing operation returns.
+- The Eve helper accepts a caller/turn `when` predicate for instructions and connections. False or a policy failure omits the value before fetching guidance or selecting a pool, including when guidance is cached.
+- `listen(..., { maxInFlightBodyBytes })` bounds the request body bytes all in-flight requests hold together on Node. It defaults to 64 MiB, or `maxBodyBytes` when that is larger. Past it a request is answered `503` with `Retry-After` and `Connection: close`. `maxBodyBytes` and its `413` are unchanged, and Workers are unaffected.
+- Point guided native tool descriptions at the connector guide through the serving skills route.
+- Add eval-only guidance delivery interventions for pointer, summary, inline convention and instruction-led fetch comparisons, with deterministic arm controls and guide-fetch metrics. Inline conventions use the advertised guideSummary field, and wire controls list tools first so the SDK validates every arm's output schema.
+- Offer opt-in deferred connector instructions as Eve skills with caller selection before fetching. Network, timeout and malformed-response failures omit the skill while preserving turn cancellation. Successful content is reused only while Eve retains the endpoint/guide/turn memo; failed later turns serve no stale guide.
+- Opt-in sampled payload-free MCP timing logs with request-read cache outcomes and D1 trip/statement totals. Workers durations are I/O-spanning elapsed observations, not CPU attribution; CPU-only catalog stages report counts and decoded bytes. Trace finalization survives throwing downstream cleanup.
+
+### Changed
+
+- **Breaking:** `createConnecta` throws when `clerkAuth` has no resolved `publicUrl`: neither `clerkAuth({ publicUrl })` nor `ConnectaConfig.publicUrl`. Clerk's token `resource` and session `azp` checks no longer fall back to the request origin. To migrate, set either option to the URL clients reach, or name the loopback origin locally, such as `http://localhost:8787`. A `clerkAuth` `publicUrl` that is not an absolute http(s) URL without credentials also throws. The unset-`publicUrl` startup warning now also fires with inbound auth and describes every URL that follows the request origin.
+- **Breaking:** `createConnecta` throws when a configured vault lacks `seal` or `open` and any connector has `startAuth`, replacing a startup warning that left downstream OAuth tokens, client registrations and PKCE verifiers as plaintext beside encrypted credentials. To migrate, use `encryptedCredentialVault(storage, key)` or add both methods to the custom vault; grants already stored as plaintext are sealed on first read. `encryptedCredentialVault`, deployments with no vault, and non-sealing vaults with no OAuth connector are unaffected.
+- Skip redundant last-seen observation reads during the one-minute sampling window while continuing fresh token admission.
+- Raise the root bundle cap to 422,500 B gzip and `examples/worker` to 806,500 B gzip for this release's measured growth, ending the batch's temporary headroom.
+- Locate catalog manifests alongside negotiation and generation in one bounded SQL read, retaining complete chunk verification and a separate fresh acceptance fence.
+  
+  Keep locator layout metadata and key construction in the shared key builders. Prove expired generation/manifest handling and literal punctuation against both SQL drivers, and pin measured combined warm agent read counts after admission observation sampling.
+- Run CI static/package build phases and two isolated Node test shards in parallel, checking complete shard coverage and every matrix leg's completion at the aggregate gate.
+- Prefix downstream skill text with its third-party connector origin on tool and program surfaces while preserving native manifest bytes.
+- Reuse bounded immutable lexical tokens and postings across complete request catalogs while applying visibility on each request.
+- Advertise a five-minute private TTL for local-only skill catalogs and reads; downstream-enabled caller views retain zero TTL.
+- Use pinned native TypeScript for core and operator UI no-emit feedback, with explicit shared result types accepted by both compilers. Keep TypeScript 6 for AST analysis, emitted builds, declarations and installed consumers.
+- Verify sealed pending OAuth consents from 0.40.0 through callback validation, binding, claim, exchange and token persistence. Cover fresh-start recovery for legacy no-vault consents whose discovery URLs include userinfo, queries or fragments.
+- **Breaking:** Put pool scope and the guide pointer before routing rules in meta and native endpoint instructions, preserving unscoped instructions.
+  
+  Pool descriptions are limited to 500 UTF-16 code units after trimming so accepted text fits the instruction budget and first 512 units in every mode. This tightens validation: previously accepted descriptions with at most 500 Unicode code points but more than 500 UTF-16 units (for example, 500 emoji) now fail construction. Shorten those descriptions before upgrading; required routing rules remain intact.
+- Keep server orchestration and Effect out of the QuickJS child startup graph.
+- Use readable skill slugs with legacy aliases, actionable provider summaries and advisory construction warnings for weak guide summaries.
+  
+  Generated readable names resolve on every skill surface; canonical identities take priority over legacy aliases, ambiguous aliases fail explicitly, and generated names avoid configured connector IDs.
+- Batch SQL result-stash trailing chunks before separate header publication, reducing storage trips while preserving expiry and uncertain-write accounting.
+- Strengthen stash fault probes for delayed SQL batch commits and transactional expiry sweeps.
+
+### Fixed
+
+- Clarify that the redaction guarantee excludes occurrences made entirely of reserved replacement text, including runs across the seam between adjacent markers. Settling behavior is unchanged.
+- QuickBooks write evals now explicitly grade the destination and final answer evidence, completing the selftest check classification without weakening outcome checks.
+- Let `eval:selftest`'s D1 latency control accept a timer that fires just under its delay, so the full selftest no longer fails on a 49.8 ms round trip.
+- QuickBooks eval setup now probes personal credential isolation through a program and checks read-only pools using the tools the selected eval surface serves, so code-only selftests retain their safety checks without calling hidden meta-tools.
+- Attribute eval fake dispatches through a per-server transport marker, retaining unrelated loopback probes separately from vendor ledgers.
+- Probe exact-once eval latency on both deployment targets, disabled fault membership, stopped listening sockets, and each D1 round trip. Count D1 batch waits instead of imposing a load-sensitive upper timing bound.
+- Retry a rejected Cloudflare Access identity lookup once within its original deadline and record checked, payload-free lookup failure diagnostics. Identity failures continue to refuse admission.
+- Restrict native eval workerd TCP connections with fail-closed Linux Landlock port rules and raw-socket controls for disallowed ports and the known allowed-port address limit. Add a model-free check of all eligible Worker references. Document the remaining address and UDP limits.
+- Report API OAuth status from typed real-call outcomes fenced by the token grant's revision. Consent and refresh replace their observation atomically, and passive status reads do not write grant state. Later invocations can recover from transient API refusals; Connect starts fresh consent for a refused grant. Maintained provider middleware records initial and replayed outcomes, and unchanged observations do not rewrite grants. Normal Connect preserves concurrent recovery, and oversized 401 responses record refusal without reading their bodies, including after replay.
+- `workerExecutor()` works with `@cloudflare/codemode` 0.5.5 and later. Those releases close a call gate when the SDK's `execute()` settles, and Connecta's inert loader settled it before the real program ran, so every `execute_code` host call failed with "The code execution finished before this tool call settled". The gate now stays open for the whole native run and closes when it ends or its lease is released. Development and CI use codemode 0.5.6.
+- State effective write policy in endpoint instructions and connector guides, and explain that read-only refusals have no write route.
+- Supply schema recovery for typed argument failures without validation details and explicit safe recovery limits for missing resources, unavailable connectors and uncertain writes.
+- Reuse one observation age for stored connector details and their overlays, keeping both fields consistent across a clock rollover.
+- Corrected the Cloudflare Access `identityLookup.inFlight` documentation: it counts lookup attempts still pending, so a hung lookup counts itself, and a rejected lookup or a deadline during retry backoff does not.
+- Prevent eval startup port reservation races, retry child bind collisions before trials start, and protect a checkout's build with crash-released OS locks while allowing concurrent eval readers. Report failed cross-connector reference reads before attempting the answer post.
+  
+  Restore the fake vendor transport before deployment startup yields, preserving containment and physical-write evidence across interleaved trials.
+  
+  Use descriptor-mode locking on Linux and macOS, retaining the lease when the wrapper dies while its command runs. Keep explicit Wrangler inspector/proxy ports for Landlock and retry native startup collisions with fresh ports. Document the lock's reader/writer fairness limit.
+- Retain remote MCP cleanup settlement across owner and connector close, including abandoned leases, so bounded session termination remains owned by runtime deferred work. Await explicit warmup termination in OAuth rotation tests, including cleanup gated before fetch accounting.
+- `eval:selftest` exits after its last check instead of idling on the egress control's unclosed UDP probe socket.
+- Reject unknown downstream Skills revisions and record the extension’s Beta lifecycle.
+- Complete typed host, availability, utility and result-handle recovery, with continuation actions taking precedence over generic retry advice.
+
+### Security
+
+- Pending downstream OAuth flow records store less. With a sealing vault, the consent URL, server and client binding, and PKCE verifier are sealed together. With no vault, the record stores no consent URL and its binding keeps no URL userinfo, query or fragment, so a repeated non-forced start mints a fresh consent instead of reusing the pending URL. `documentation/auth.md` states the narrower no-vault guarantee. Sealed consents already in flight across the upgrade still complete. A no-vault consent whose discovery URL holds userinfo, a query or a fragment fails cleanly and needs a fresh start.
+- Learned OAuth URLs naming reserved or transitional addresses are refused: IPv4 special-purpose ranges (`192.0.0/24`, `198.18/15`, multicast, reserved and broadcast among them), IPv6 outside global unicast, and IPv4 carried in compatible, translated, NAT64 or 6to4 form, judged by the address it carries. A public address in those forms stays public. A `publicUrl` on such an address no longer offers a self-hosted client metadata document.
+- The Node adapter answers `400` for a `Host` that is not a host with an optional port, an `X-Forwarded-Proto` other than `http` or `https`, or a request target that does not start with `/`, before reading any body. No such value can change the path or host routes see. A malformed value used to fail as a `500` or be parsed into another URL.
+- Pin learned Node URL connections to validated DNS addresses while preserving TLS hostname verification.
+
 ## 0.40.0 — 2026-11-02
 
 This release makes warm Connecta calls on Workers cheaper in storage and closes a credential gap on OAuth remote MCP connectors. Deployments need no configuration change or migration, unless they use the Eve helper.

package/bin/connecta.mjs

@@ -2,7 +2,7 @@
 
 import { copyFile, cp, lstat, mkdtemp, readFile, rename, rm, symlink, writeFile } from "node:fs/promises";
 import { CONNECTA_VERSION } from "./version.mjs";
-import { META_TOOL_NAMES } from "./meta-tool-names.mjs";
+import { META_TOOL_NAMES, READ_PROGRAM_TOOL } from "./meta-tool-names.mjs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -245,6 +245,8 @@ async function doctor() {
   let negotiatedVersion;
   let native = false;
   let executeCode = true;
+  let toolCount = META_TOOL_NAMES.length;
+  let readRoute = false;
   try {
     await client.connect(transport);
     negotiatedVersion = client.getNegotiatedProtocolVersion();
@@ -257,15 +259,28 @@ async function doctor() {
       throw new Error(
         `Native catalogs unavailable: ${surface.catalogErrors.join(", ")}. Inspect connector status and authentication.`,
       );
+    // Tools are listed, from an older catalog, so nothing above notices that the connector did not answer.
+    if (native && surface.staleCatalogs?.length)
+      throw new Error(
+        `Native discovery degraded: ${surface.staleCatalogs.join(", ")} did not answer and listed from an older catalog. Inspect connector status.`,
+      );
+    // A writable human endpoint also lists the read program route, unless the deployment turned it off.
+    // An agent endpoint never does, so seven tools there is a wrong surface.
+    readRoute = !native && !agent && actual.includes(READ_PROGRAM_TOOL);
     const expected = native
       ? ["authorize_connector", "skills", executeCode ? "execute_code" : "read_result"].sort()
-      : [...META_TOOL_NAMES].sort();
+      : [...META_TOOL_NAMES, ...(readRoute ? [READ_PROGRAM_TOOL] : [])].sort();
+    toolCount = expected.length;
     if (
       native
         ? expected.some((name) => !actual.includes(name)) ||
-          ["search_tools", "call_tool", "call_destructive_tool", executeCode ? "read_result" : "execute_code"].some(
-            (name) => actual.includes(name),
-          )
+          [
+            "search_tools",
+            "call_tool",
+            "call_destructive_tool",
+            READ_PROGRAM_TOOL,
+            executeCode ? "read_result" : "execute_code",
+          ].some((name) => actual.includes(name))
         : JSON.stringify(actual) !== JSON.stringify(expected)
     ) {
       throw new Error(
@@ -274,20 +289,14 @@ async function doctor() {
       );
     }
 
-    if (executeCode) {
-      const executed = await client.callTool(
-        {
-          name: "execute_code",
-          arguments: { code: "async () => 42" },
-        },
-        undefined,
-        { timeout: DOCTOR_TIMEOUT_MS },
-      );
+    for (const name of executeCode ? ["execute_code", ...(readRoute ? [READ_PROGRAM_TOOL] : [])] : []) {
+      const executed = await client.callTool({ name, arguments: { code: "async () => 42" } }, undefined, {
+        timeout: DOCTOR_TIMEOUT_MS,
+      });
       const executionResult = executed.structuredContent ?? JSON.parse(executed.content?.[0]?.text ?? "null");
       if (executed.isError || executionResult?.result !== 42) {
         throw new Error(
-          `${executorName ? `${executorName} execution` : "execute_code"} check ` +
-            `failed: ${JSON.stringify(executed)}`,
+          `${executorName ? `${executorName} execution` : name} check ` + `failed: ${JSON.stringify(executed)}`,
         );
       }
     }
@@ -298,7 +307,7 @@ async function doctor() {
   console.log(
     `Connecta doctor passed: ${health.connectors} connector(s), ` +
       `${executeCode ? (executorName ? `${executorName} executed` : "code executed") : "code disabled"}, ` +
-      `${native ? "native tool surface" : `prescribed ${META_TOOL_NAMES.length}-tool surface`}, MCP ${negotiatedVersion}, package ${CONNECTA_VERSION}.`,
+      `${native ? "native tool surface" : `prescribed ${toolCount}-tool surface`}, MCP ${negotiatedVersion}, package ${CONNECTA_VERSION}.`,
   );
 }
 

package/bin/meta-tool-names.d.mts

@@ -1,2 +1,4 @@
-/** The complete upward meta-tool set, shared by discovery checks and doctor. */
+/** The upward meta-tool set every meta endpoint lists, shared by discovery checks and doctor. */
 export declare const META_TOOL_NAMES: readonly string[];
+/** A writable `/mcp` or `/mcp/<pool>` endpoint also lists this, unless `execute.readRoute` is false. */
+export declare const READ_PROGRAM_TOOL: string;

package/bin/meta-tool-names.mjs

@@ -1,4 +1,4 @@
-/** The complete upward meta-tool set, shared by discovery checks and doctor. */
+/** The upward meta-tool set every meta endpoint lists, shared by discovery checks and doctor. */
 export const META_TOOL_NAMES = Object.freeze([
   "authorize_connector",
   "call_destructive_tool",
@@ -7,3 +7,6 @@ export const META_TOOL_NAMES = Object.freeze([
   "search_tools",
   "skills",
 ]);
+
+/** A writable `/mcp` or `/mcp/<pool>` endpoint also lists this, unless `execute.readRoute` is false. */
+export const READ_PROGRAM_TOOL = "execute_read_code";

package/bin/version.mjs

@@ -1,3 +1,3 @@
 // Generated from package.json by scripts/generate-version.mjs.
 // Workers-safe: no runtime filesystem read or deployment override.
-export const CONNECTA_VERSION = "0.40.0";
+export const CONNECTA_VERSION = "0.42.0";

package/dist/activity.d.ts

@@ -5,7 +5,7 @@ import type { Logger } from "./types.js";
 export declare function activityClientFact(value: unknown, field: "name" | "version"): string | undefined;
 /** Stored package versions use a bounded release-version grammar, including prereleases. */
 export declare function activityPackageVersion(value: unknown): string | undefined;
-export type ActivityCallSource = "catalog_refresh" | "native" | "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "resume_execution";
+export type ActivityCallSource = "catalog_refresh" | "native" | "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code" | "execute_read_code" | "resume_execution";
 export type ActivityOutcome = "success" | "error" | "timeout" | "cancelled" | "paused" | "approved";
 /** Read-only history: how much one `resume_execution` approved (#672). */
 export type ActivityApproval = "call" | "tool";
@@ -27,7 +27,7 @@ export interface ActivityActor {
     namespace?: string;
 }
 /**
- * Privacy-minimal history of one resolved downstream connector call.
+ * Privacy-minimal history of a resolved call, catalog change or opt-in operation.
  *
  * Arguments, results, generated code, search text, and raw errors are excluded
  * by construction. Deployments that need a safe human summary can add a
@@ -39,6 +39,19 @@ export interface ActivityCatalogChange {
     removedTools: number;
     changedTools: number;
 }
+export type ActivityOperationName = "search" | "describe" | "result" | "skill" | "program";
+export interface ActivityOperation {
+    name: ActivityOperationName;
+    /** Conservative endpoint scope, never caller-supplied addresses. */
+    connectors: string[];
+    personal: boolean;
+    hostCalls?: {
+        attempted: number;
+        admitted: number;
+        succeeded: number;
+        failed: number;
+    };
+}
 /** Integer metadata is checked at every write and read boundary. */
 export declare function activityCount(value: unknown): number | undefined;
 export declare function activityBehaviorFacts(event: {
@@ -46,16 +59,18 @@ export declare function activityBehaviorFacts(event: {
     resultBytes?: unknown;
     kind?: unknown;
     drift?: unknown;
+    operation?: unknown;
     pool?: unknown;
     actorBasis?: unknown;
-}): Pick<ToolCallActivityEvent, "classification" | "resultBytes" | "kind" | "drift" | "pool" | "actorBasis">;
+}): Pick<ToolCallActivityEvent, "classification" | "resultBytes" | "kind" | "drift" | "operation" | "pool" | "actorBasis">;
 export interface ToolCallActivityEvent {
     schemaVersion: 1;
     id: string;
     occurredAt: string;
     requestId: string;
     /** Absent on legacy tool rows. Catalog changes use the same paging envelope. */
-    kind?: "catalog_drift";
+    kind?: "catalog_drift" | "operation";
+    operation?: ActivityOperation | undefined;
     drift?: ActivityCatalogChange;
     /** The final registry verdict captured when resolution succeeded. */
     classification?: "read" | "write";
@@ -162,6 +177,7 @@ export interface CatalogDriftActivityContext {
 }
 /** Request-scoped context shared by direct, batch, and code-mode call paths. */
 export interface ActivityRequestContext {
+    recordOperation?: typeof recordOperationActivity | undefined;
     recordTool?: typeof recordToolActivity | undefined;
     sink: ActivitySink;
     actor: ActivityActor;
@@ -181,7 +197,7 @@ export interface ActivityRequestContext {
     defer?: (promise: Promise<unknown>) => void;
     logger: Logger;
 }
-export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "friction" | "classification" | "resultBytes" | "kind" | "drift"> & {
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "friction" | "classification" | "resultBytes" | "kind" | "drift" | "operation"> & {
     /**
      * A code connecta assigns. Rows written by older deployments may hold
      * others, so the stored event keeps `string`; a new row never does.
@@ -204,8 +220,19 @@ export declare function recordCatalogChangeActivity(context: CatalogDriftActivit
     privateCatalog?: boolean;
 }, request?: ActivityRequestContext): void;
 export interface ActivityHistoryOptions {
+    /** Opt in to one detached storage write per meta operation and program. */
+    operations?: boolean;
     store: ActivityStore;
     deploymentId?: string;
     readGate?: ActivityReadGate;
 }
 export declare function activityHistory(options: ActivityHistoryOptions): ActivityModule;
+/** Operation records reuse the detached sink and accept no payload fields. */
+export declare function recordOperationActivity(context: ActivityRequestContext, input: {
+    operation: ActivityOperation;
+    source?: "execute_read_code" | undefined;
+    durationMs: number;
+    resultBytes?: number | undefined;
+    outcome: ActivityOutcome;
+    errorCode?: ClassificationCode | undefined;
+}): void;

package/dist/activity.js

@@ -1,7 +1,8 @@
+import { checkedActivityOperation } from "./operation-activity.js";
 import { CONNECTA_VERSION } from "./version.js";
 import { assertKnownOptions, keys, optionsOf } from "./config-schema.js";
 import { routeActivity } from "./routes/activity.js";
-import { boundedEchoText, classificationCode } from "./errors.js";
+import { clampedRecordName, classificationCode } from "./errors.js";
 import { failureRecord, logFailure } from "./operator-record.js";
 import { keepErrorName } from "./redaction-identity.js";
 /**
@@ -82,6 +83,7 @@ export function activityBehaviorFacts(event) {
         ...(classification !== undefined ? { classification } : {}),
         ...(resultBytes !== undefined ? { resultBytes } : {}),
         ...(drift ? { kind: "catalog_drift", drift } : {}),
+        ...(event.kind === "operation" ? { kind: "operation", operation: checkedActivityOperation(event.operation) } : {}),
         ...(pool !== undefined ? { pool } : {}),
     };
 }
@@ -106,7 +108,7 @@ export function recordToolActivity(context, input) {
     // Checked here as well as by type: a handler can put any string in a
     // `ConnectorCallError`'s code, and a downstream's own code is not recorded.
     const errorCode = classificationCode(input.errorCode);
-    const friction = input.friction ?? agentFrictionForCode(errorCode);
+    const friction = input.kind === "operation" ? undefined : (input.friction ?? agentFrictionForCode(errorCode));
     // Re-check client grammars at the record boundary; never spread the envelope.
     const clientName = activityClientFact(context.clientInfo?.name, "name");
     const clientVersion = activityClientFact(context.clientInfo?.version, "version");
@@ -121,9 +123,9 @@ export function recordToolActivity(context, input) {
             pool: context.pool,
             actorBasis: input.privateCatalog || (input.personal && context.principalActor) ? "principal" : undefined,
         }),
-        connectorId: boundedEchoText(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
-        toolName: boundedEchoText(input.toolName, MAX_ACTIVITY_NAME_BYTES),
-        address: boundedEchoText(input.address, MAX_ACTIVITY_ADDRESS_BYTES),
+        connectorId: clampedRecordName(input.connectorId, MAX_ACTIVITY_NAME_BYTES),
+        toolName: clampedRecordName(input.toolName, MAX_ACTIVITY_NAME_BYTES),
+        address: clampedRecordName(input.address, MAX_ACTIVITY_ADDRESS_BYTES),
         source: input.source,
         outcome: input.outcome,
         durationMs: Math.max(0, Math.trunc(input.durationMs)),
@@ -176,16 +178,40 @@ export function recordCatalogChangeActivity(context, input, request) {
 }
 /** Attach payload-free history without changing tool results on store failure. */
 /** The closed options activityHistory() accepts; see `assertKnownOptions`. */
-const ACTIVITY_HISTORY_OPTIONS = optionsOf()(keys("store", "deploymentId", "readGate"));
+const ACTIVITY_HISTORY_OPTIONS = optionsOf()(keys("store", "deploymentId", "readGate", "operations"));
 export function activityHistory(options) {
     options = assertKnownOptions(options, "activityHistory()", ACTIVITY_HISTORY_OPTIONS);
     if (!options || typeof options.store?.record !== "function") {
         throw new Error("activityHistory.store must implement record(event)");
     }
+    if (options.operations !== undefined && typeof options.operations !== "boolean")
+        throw new Error("activityHistory.operations must be a boolean");
     return {
         ...options,
+        ...(options.operations ? { recordOperation: recordOperationActivity } : {}),
         handle: routeActivity,
         recordTool: recordToolActivity,
         recordChange: recordCatalogChangeActivity,
     };
 }
+/** Operation records reuse the detached sink and accept no payload fields. */
+export function recordOperationActivity(context, input) {
+    const operation = checkedActivityOperation(input.operation);
+    if (!operation)
+        return;
+    const connectorId = operation.connectors.length === 1 ? operation.connectors[0] : "$operation";
+    recordToolActivity(context, {
+        kind: "operation",
+        operation,
+        connectorId,
+        toolName: operation.name,
+        address: `${connectorId}.${operation.name}`,
+        source: input.source ?? "execute_code",
+        outcome: input.outcome,
+        durationMs: input.durationMs,
+        ...(input.resultBytes !== undefined ? { resultBytes: input.resultBytes } : {}),
+        attempts: 1,
+        ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+        ...(operation.personal ? { privateCatalog: true } : {}),
+    });
+}

package/dist/advertised-schema.js

@@ -51,3 +51,18 @@ export function advertisedSchema(schema) {
         },
     };
 }
+/**
+ * An output schema that advertises less than it enforces. The SDK validates each
+ * non-error result through `~standard.validate`, so the server keeps the full contract and
+ * a client's copy states only what it can use: required keys and top-level types,
+ * with every other field open.
+ */
+export function openOutputSchema(validator, advertised) {
+    const json = deepFreeze(advertised);
+    return {
+        "~standard": {
+            ...validator["~standard"],
+            jsonSchema: { input: () => json, output: () => json },
+        },
+    };
+}

package/dist/agent-observation.js

@@ -5,8 +5,13 @@ import { isAgentName } from "./agent-identity.js";
 import { agentObservationKeys } from "./storage/keys.js";
 import { Storage } from "./runtime/services.js";
 import { storageCompareAndSet, storageGet } from "./runtime/storage.js";
+import { physicalStorageAddress } from "./runtime/request-reads.js";
 const OBSERVATION_TIMEOUT_MS = 500;
 const OBSERVATION_FRESHNESS_MS = 60_000;
+// Only scalar telemetry deadlines survive requests. Weak physical-store ownership
+// and a bounded map prevent agent/config churn from retaining unbounded state.
+const observedUntil = new WeakMap();
+const MAX_OBSERVED_AGENTS = 256;
 function timestamp(raw) {
     if (!raw || raw.length !== 24)
         return null;
@@ -26,14 +31,31 @@ export function observeAgentAdmission(storage, name, at, timeoutMs) {
         return Effect.void;
     return Effect.gen(function* () {
         const key = agentObservationKeys.agent(name);
+        const address = physicalStorageAddress(storage, key) ?? { store: storage, key };
+        const now = Date.parse(at);
+        let observations = observedUntil.get(address.store);
+        if (!observations)
+            observedUntil.set(address.store, (observations = new Map()));
+        if ((observations.get(address.key) ?? -Infinity) > now)
+            return;
+        const remember = (seen) => {
+            const until = Math.min(seen + OBSERVATION_FRESHNESS_MS, now + OBSERVATION_FRESHNESS_MS);
+            if (!observations.has(address.key) && observations.size >= MAX_OBSERVED_AGENTS)
+                observations.delete(observations.keys().next().value);
+            observations.set(address.key, Math.max(observations.get(address.key) ?? -Infinity, until));
+        };
         for (let attempt = 0; attempt < 2; attempt++) {
             const previous = yield* storageGet(key);
             const seen = timestamp(previous);
             // Future and recently sampled observations both need no write.
-            if (seen && Date.parse(at) - Date.parse(seen) < OBSERVATION_FRESHNESS_MS)
+            if (seen && now - Date.parse(seen) < OBSERVATION_FRESHNESS_MS) {
+                remember(Date.parse(seen));
                 return;
-            if (yield* storageCompareAndSet(key, previous, at))
+            }
+            if (yield* storageCompareAndSet(key, previous, at)) {
+                remember(now);
                 return;
+            }
         }
     }).pipe(Effect.provideService(Storage, storage), Effect.catchDefect((error) => Effect.fail(error)), Effect.catch(() => Effect.void), Effect.timeoutOption(Duration.millis(Math.min(timeoutMs, OBSERVATION_TIMEOUT_MS))), Effect.asVoid);
 }