@zackbart/connecta 0.37.1 → 0.39.0

package/documentation/migration-0.33.md

@@ -1,8 +1,7 @@
 # Migration to 0.33
 
-Use this upgrade guide for an existing deployment moving to 0.33.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover the
-general procedure; [the agent index](./README.md) routes other work.
+Apply the [general upgrade procedure](./deploying.md#upgrade-an-existing-deployment)
+when moving from 0.32 to 0.33.
 
 0.33 makes pools the access model.
 Every deployment with inbound auth changes its configuration. Each removed
@@ -41,6 +40,10 @@ the sections in order, then [verify](#verify).
 | `DELETE /ui/credentials/<id>` on an empty slot answering 204                          | 409 `{ "problem": "credential_required" }`                                                                                              |
 | The `agent_not_maintainer` denial reason                                              | Removed; agents are refused at human endpoints before admission                                                                         |
 
+This guide records the 0.33 migration. Current versions require every pool to
+list only people or only agents. If a 0.33 deployment combined them, follow
+[Split mixed pools](./pool-membership-upgrade.md) as well.
+
 ## Maintainers and pool members
 
 0.32 combined an identity resolver, a top-level `grant`, and pool `grant`
@@ -338,8 +341,9 @@ pools: {
 
 ## Verify
 
-1. Start the deployment; construction errors name each removed option's
-   replacement.
+1. Start the deployment; 0.33 construction errors name each removed option's
+   replacement. Releases after 0.37.1 use generic unknown-option errors;
+   use this guide for replacements.
 2. Sign in as a maintainer and confirm plain `/mcp` and the operator UI work.
 3. Run `connecta doctor --pool <pool>` with each agent's token, and confirm
    the same token at `/mcp` is refused.
@@ -349,4 +353,4 @@ pools: {
    absent: search finds none of their tools and a call fails
    `unknown_address`. The same holds in any pool without an owner, even one
    that lists a Workspace connector with a subject mapping.
-6. Confirm each `<agent>-<user>` pool lists no other person in `members`.
+6. Confirm each `<agent>-<user>` pool lists only the agent in `members` (the current construction rule).

package/documentation/migration-0.34.md

@@ -1,9 +1,7 @@
 # Migration to 0.34
 
-Use this guide when upgrading an existing deployment from 0.33 to 0.34.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover the
-general procedure; [the agent index](./README.md) routes other work. Upgrades
-from earlier versions must also apply the intervening migrations.
+Apply the [general upgrade procedure](./deploying.md#upgrade-an-existing-deployment)
+when moving from 0.33 to 0.34, including intervening migrations for older versions.
 
 No storage migration, token rotation or required configuration field is added.
 Review the following changes before updating the package pin.
@@ -41,7 +39,9 @@ If an agent needs to act as Alice, put that access in her personal pool and set
 to use. Confirm the pool's tools and members before adding an owner. Follow
 [the agent pool layout](./auth.md#organizing-an-agents-pools) for the full
 configuration. People in the same pool, agents in owned pools and connectors
-with a fixed `subject` address keep their behavior.
+with a fixed `subject` address keep their behavior. Current versions also
+require each pool to list only people or only agents; see
+[Split mixed pools](./pool-membership-upgrade.md).
 
 ## Optional settings and development tooling
 

package/documentation/migration-retired-layouts.md

@@ -0,0 +1,74 @@
+# Migrate before past-layout support is removed
+
+Use this guide before upgrading to the release that removes the pre-0.29
+storage and OAuth layout migrations. [Deployment upgrades](./deploying.md#upgrade-an-existing-deployment)
+cover the general procedure; [the agent index](./README.md) routes other work.
+Apply intervening configuration and provider migrations too.
+
+**0.37.1 is the last bridge release containing these migrations.** A deployment
+with Workers KV, a JSON state file, or OAuth layout-2 grants must first upgrade
+to exactly `@zackbart/connecta@0.37.1` and finish the relevant migrations there.
+Installing the bridge release alone does not migrate unused grants or storage.
+Deployments already using D1 or SQLite with layout-3 grants need no conversion.
+Keep the existing database, connector ids, owner partitions, and vault key.
+
+## Before updating the package pin
+
+1. Back up the source state and destination database securely, including expiry
+   metadata, and preserve the credential encryption key. Stop traffic and all
+   background writers; drain OAuth callbacks and refreshes. Keep a recoverable
+   0.37.1 deployment and its installed package until verification completes.
+2. For Workers KV, use 0.37.1's installed
+   `examples/worker/scripts/copy-kv-to-d1.mjs` and `kv-to-d1.wrangler.jsonc`.
+   Follow that version's `examples/worker/README.md#upgrading-from-028`:
+   wait for stable KV, run `--maintenance`, resolve invalid entries and
+   conflicts, run `--maintenance --verify`, switch to D1 under maintenance,
+   verify, then run `--maintenance --mark-live` before reopening traffic.
+   The underlying API is `copyKvToD1(kv, db, { source })` from
+   `@zackbart/connecta/d1`; finish every returned cursor, verify hashes and
+   expiries, and call `markKvToD1Live(db, source)` before cutover. Never copy
+   stale KV over a database that has accepted new writes.
+3. For Node's pre-SQLite JSON state, stop the server and run the bridge CLI:
+
+   ```sh
+   npx --yes --package=@zackbart/connecta@0.37.1 connecta migrate-state .connecta-state.json .connecta.sqlite
+   ```
+
+   It copies live entries with their expiry, keeps existing destination keys,
+   and leaves the JSON file unchanged. The old activity JSONL is not imported.
+   Use the destination SQLite file for subsequent starts.
+
+4. While still running 0.37.1 over the SQL destination, open **every OAuth
+   grant once, for every connector and owner partition** through its normal
+   authorized connection. This includes dormant personal grants. The first
+   grant read converts layout 2 to the single layout-3 `oauth:grant` record
+   and deletes historical keys. Merely listing configuration is insufficient.
+   Grants too old to have issuer binding, invalid ciphertext, and pending
+   consents require fresh authorization on the bridge release.
+5. Verify each existing OAuth connection, vault credential and agent token,
+   including every personal owner. Confirm layout-3 grant records and no
+   pending layout-2 cleanup using trusted storage tooling without printing
+   credential bodies. Only then upgrade the package pin to the removing release.
+
+## Removed interfaces and stale state
+
+| Removed path                                                                                                                       | Behavior after upgrading                                                                                                                                                                                                                                                                                                | Recovery                                                                                                                                       |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| OAuth layout-2 reader and cleanup                                                                                                  | An owner with only old keys has no usable grant. Reads return absent, credentials are never opened or copied, and a warning says to authorize again or migrate on 0.37.1. Calls require consent. Old keys remain untouched. Existing layout-3 grants, including those with an obsolete cleanup marker, remain readable. | Connect again. To preserve an old grant instead, restore a consistent pre-upgrade backup and run the bridge procedure.                         |
+| `copyKvToD1`, `markKvToD1Live`, their types/error, and copy script/config                                                          | Named imports fail; no KV copy runs. A KV adapter without atomic compare-and-set is refused at construction. A fresh D1 database contains none of the old credentials or tokens. The `/d1` subpath still exports `d1Storage` and `d1ActivityStore`.                                                                     | Stop writers and restore a consistent backup with 0.37.1, then copy and verify before cutover.                                                 |
+| `importStateFile`, `StateFileImport`, and `connecta migrate-state`                                                                 | Named imports fail; the CLI command exits nonzero with usage. The SQLite adapter never reads the JSON file, so a fresh database has no old credentials or tokens.                                                                                                                                                       | Import on 0.37.1 while stopped, then point the deployment at that SQLite file.                                                                 |
+| Retired `execute.resumableWrites`, `execute.pausedRunTtlSeconds`, `identity`, `grant`, and deployment/pool `trust` migration hints | Construction still rejects these as ordinary unknown configuration options. It no longer expands identity keys or prints replacement instructions. Pool `grant` is also rejected.                                                                                                                                       | Remove obsolete options. Follow [migration to 0.33](./migration-0.33.md) for `maintainers`, pool `members`, `agents`, and explicit `readOnly`. |
+
+A rollback after accepting new SQL writes can resurrect revoked credentials or
+spent refresh tokens. Recover from a consistent backup under maintenance rather
+than merging old KV/JSON state into a live database. If preserving old auth is
+unnecessary, reconnect credentials and issue fresh agent tokens in the current
+SQL deployment; revoke superseded credentials at their providers.
+
+## Verify
+
+Run `connecta doctor --pool <pool>` with each agent's token. Open each shared
+and personal OAuth connection and make a controlled read. Confirm authorization
+works without an unsupported-layout warning, the intended SQL database is used,
+and the operator UI shows expected credentials and activity. Remove one-shot
+migration routes and bindings after successful cutover.

package/documentation/operator-tests.md

@@ -24,24 +24,17 @@ committed through the deployment's own store, so the contract's `agents` and
 last seen are fixed. The restricted state is the member fixture from
 `test/fixtures/operator-contract-v2.ts`, and the endpoint and matrix variants
 use its maintainer fixture, which covers every runs-as kind and agent pools,
-with `test/fixtures/operator-console.ts` crowding the team pool so its avatar
+with `test/fixtures/operator-console.ts` crowding the people-only team pool so its avatar
 stack collapses to "+3".
-Collections use their corresponding browser types.
-`test/operator-visual-fixtures.test.ts` validates contract versions, connector
-IDs, granted tools, matrix cells, classification, provenance, and secret
-exclusion on Node and Workers, and runs `expectMemberViewWithholds` on the
-member body. A fixture's config cannot silently become a stale copy of the
-server serializer.
+Collections use their corresponding browser types. Real contract serialization,
+member projection and secret withholding are exercised through
+`test/operator-contract.test.ts` and `test/operator-contract-server.test.ts`.
 
 `test/browser/operator-visual.spec.ts` intercepts API reads and serves the real
-hashed assets and HTML with the production CSP. Loading responses wait on an
-explicit gate. Error responses use fixed HTTP failures. The map trace focuses its
-node instead of hovering it: the capture scrolls to the top first, which would
-move the node out from under a pointer and drop the highlight, so the test waits
-for `.map-svg.tracing` before capturing. Screenshots use a fixed
-clock, UTC, en-US, locally hosted fonts, disabled animations, hidden carets,
-and a 1280 × 900 viewport. Narrow fixtures use 390 × 844. Every test waits for
-its state and fonts before capturing.
+hashed assets and HTML with the production CSP. It captures populated Overview
+and connector Connection pages in light and dark themes: four screenshots.
+Each capture waits for the heading, page content and fonts, with a fixed clock,
+and resets scrolling before the full-page image.
 
 ## Loading and recovery probes
 
@@ -52,115 +45,22 @@ The suite also checks default v2 compatibility, the unchanged member projection,
 blocked custom connectors and bounded essential token-slot failure.
 `test/ui.test.ts` checks complete detail schemas and independent sibling scope cleanup.
 
-`test/oauth-stored-observation.test.ts` covers absent, disconnected, tokenless,
-sealed/unreadable and issuer-mismatched grants, owner isolation, both built-in
-connector paths and custom connectors. Storage spies require zero auth mutations,
-including migration and resealing. `test/operator-store.test.ts` counts scoped
-refresh/focus/mutation/poll requests, coalescing and bounded retries, and verifies
-stale admission blocks privileged reads, connection writes and token actions while
+`test/operator-store.test.ts` counts scoped refresh/focus/mutation/poll requests,
+coalescing and bounded retries, and verifies stale admission blocks privileged reads, connection writes and token actions while
 retaining the snapshot. Late reads, role/identity changes and concurrent polls
 exercise publication fences. Browser recovery and flow suites use real routes to
 check a usable shell with a stalled connector, OAuth return and scoped Refresh.
 
-## Page and state matrix
-
-Each row runs empty, loading, error, populated, and restricted-viewer fixtures
-in both light and dark themes, for 90 screenshots. The restricted viewer is a
-pool member, who gets the member page, with no tabs, on every path.
-
-| Page or tab          | Empty state                          | Loading/error request | Restricted viewer (member)          |
-| -------------------- | ------------------------------------ | --------------------- | ----------------------------------- |
-| Overview             | No connectors: nothing to map        | Config                | Member page at `/`                  |
-| Endpoints            | Root endpoint without tools          | Config                | Member page: endpoints, accounts    |
-| Connectors           | No connectors                        | Config                | Member page, no connector request   |
-| Connector Tools      | Empty catalog                        | Config                | Member page, no connector request   |
-| Connector Connection | Deployment-managed auth              | Config                | Member page, no connector request   |
-| Connector Activity   | No calls                             | Activity              | Member page, no activity request    |
-| Tokens               | No declared agents                   | Token list            | Member page, no token request       |
-| Activity             | No calls                             | Activity              | Member page, no activity request    |
-| Settings             | Snapshot without connectors or pools | Config                | Member page, no configuration facts |
-
-Populated Overview has a failing connector, auth and credential problems
-and a tokenless agent in its attention list. Populated Endpoints shows who can use each endpoint; populated Tokens has one
-agent per slot state, with pools and last seen.
-
-Another 60 screenshots cover the Overview map on the frozen v2 maintainer, one
-person's trace, and the narrow map list; configured, mismatched, unreadable and multifield
-credentials; all three OAuth client mechanisms; clean and unobserved drift;
-historical Activity; client setup; schema dialog; read/write filters; narrow
-Settings; narrow sign-in and Connection; deployment branding; `/mcp`
-and an agent pool expanded with every runs-as kind; command search; narrow
-endpoints; the connector × endpoint matrix, one cell's open popover, and the
-narrow matrix; a new token's one-time secret dialog; and the member page, wide
-and narrow. `endpoints-expanded` and `narrow-endpoints` include the team row
-collapsed to "+3". The base
-populated Activity fixture includes grouped calls, an ungrouped legacy row,
-classification/result size/client facts, and a catalog-change event.
-
-`test/browser/operator-matrix.spec.ts` serves the frozen v2 fixtures to the
-real shell. It covers the matrix's table semantics, cell names, status dots,
-runs-as labels in each kind's popover, popover keyboard behavior, placement at a short viewport, the in-flow
-fallback without CSS anchors, and the absence of `style` attributes, agent URLs on Endpoints, the member page (its
-received body checked with `expectMemberViewWithholds`, `/ui/data` answering 404
-and never requested, no maintainer fact rendered, no maintainer request sent),
-the 401 sign-in and 404 no-access gates on `/ui/api/config` with no maintainer
-navigation, the shared recovery banner on Tokens and Activity through a failed
-refresh that stalls past its deadline (one focusable Retry, no maintainer
-request until Retry succeeds), an open client setup drawer closed by a failed
-refresh with focus on Retry, Tokens under recovery (an open rotate question
-closes with focus on Retry and nothing sent; an unseen secret dialog stays open
-over the banner until dismissed), payload sentinels, CSP, and the refusal of a v1 body. Matrix coverage excludes retired grants from
-its live counts and pie, keeps their names inspectable in the popover, and
-renders an unavailable catalog as a dashed empty ring with "?" and an unknown
-accessible name. Cell names distinguish equal grants against different live
-catalog sizes. `test/operator-endpoints.test.ts` covers those view-model cases,
-including a known empty catalog versus an unavailable one.
-`test/operator-connection-map.test.ts` also checks that a failed or unobserved
-catalog counts no tools, which the map draws as a muted dash, while a known
-empty catalog counts zero.
-`test/browser/operator-overview.spec.ts` covers the Overview on the frozen v2
-fixtures: the status pill, stat labels and numbers, map columns, dashed read-only grants and dotted
-tokenless access; attention rows with their fix links, a copied fix prompt equal
-to the catalogue's text, config order through a staggered full refresh, prototype-named
-connector IDs during loading and failure, and stable single-card height when
-its catalog empties. A single long-id, long-title card at 320, 390, 1024 and
-1440px covers all eight status labels, both auth scopes, with and without the
-Read-only badge, tools and an action. Text rows stay single-line, full text
-remains accessible, links stay focusable, and the detail header and Overview
-attention rows retain their height; the hover
-sentence replacing the legend, and dimming; keyboard focus in column order with each node's sentence
-as its accessible name, Enter opening an endpoint's row and a connector; the
-narrow list, whose caller chips link where their map nodes do; an empty deployment; and a member at `/` getting the member page
-with no maintainer read, plus CSP and no `style` attributes.
-`test/browser/operator-console.spec.ts` covers UI-3: who-can-use chips by
-label, raw id and agent mark and "+N" from the keyboard; Tokens rows,
-issue with the once-only secret dialog, in-row rotate and revoke questions,
-503, 499 and 409 failures that send exactly one request, slots missing from
-the list or left unresolved shown with disabled controls until Refresh; and the
-member page (its received body checked with `expectMemberViewWithholds`, no
-tabs, Search or maintainer fact, OAuth Connect, Reconnect and Disconnect sent as
-`?mode=continue`, `?mode=restart` and `DELETE`, the credential `actions`
-shapes, a refresh that drops an action closing its confirmation, a failed or
-stalled refresh keeping member chrome with Retry, a consent that outlasts the
-OAuth poll window), plus keyboard, sentinels, CSP and no `style` attributes.
-`test/operator-console.test.ts` covers the chip, slot-row and member-page view
-models. `test/browser/operator-scheme.spec.ts` holds the main bundle and checks the
-first painted background: saved dark on a light system paints dark, a pinned
-light deployment paints light over saved dark, and throwing storage keeps the
-system scheme while the released bundle settles on the normal bearer gate, and a
-sign-in there raises no error. The real-route token test in `test/browser/operator-ui.spec.ts` serves
-the contract, `/ui/data` and the slot routes from one real v2 deployment and
-checks that each mutation sent a distinct 22-character `expect`.
-`test/operator-store.test.ts` serves `/ui/api/config` from its own mock, so
-each test's data and detail answers stay separate, and covers role changes: a
-maintainer demoted after a failed refresh keeps no maintainer state and sends
-no maintainer request, and a promoted member loads maintainer data fresh. It
-also drives UI-3's slot fence with a session-token read held open: reloads and
-contract refreshes that move or drop a slot before dispatch, late results that
-cannot overwrite newer evidence, unknown and unreadable outcomes that only a
-later list read settles, revisions sent as `expect` and compared with the
-contract, an identity change that leaves the next identity's fence alone, and
-member actions whose `manage` a refresh changes.
+## Browser behavior evidence
+
+| Suite                                    | Assertions                                                                                                                                                                                 |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `test/browser/operator-matrix.spec.ts`   | Members see their own page on every path, get scoped setup links, and never request maintainer data.                                                                                       |
+| `test/browser/operator-overview.spec.ts` | Overview health, counts and map edges; per-caller status and principal-refusal copy without secret fix prompts.                                                                            |
+| `test/browser/operator-console.spec.ts`  | Token issue/rotate/revoke confirmations and once-only secret display; member credential fields and OAuth connect/reconnect/disconnect controls.                                            |
+| `test/browser/operator-pages.spec.ts`    | Resolved read/write filters, inert schema text, Activity history/grouping, and legacy URL redirects.                                                                                       |
+| `test/browser/operator-shell.spec.ts`    | Clerk loader and child-script behavior under CSP, with inline and foreign scripts blocked.                                                                                                 |
+| `test/browser/operator-ui.spec.ts`       | Identity changes cancel reads and close popups, OAuth polling stays scoped, token mutations use real routes and distinct revisions, and declared agents show scoped credentials and usage. |
 
 Screenshots cover presentation. Keep unit and server tests for INV-6 sentinels,
 secret disclosure, auth and grant boundaries, CSRF, identity fences, cancellation,

package/documentation/operator-ui.md

@@ -113,6 +113,12 @@ Pool endpoint rows show the effective surface (`meta` or `native`) and whether
 code is on. These are read-only facts from deployment configuration; change
 `surface` and `executeCode` in deployment code.
 
+Plain `/mcp` is routed by sign-in: the `/mcp` row and matrix column show the
+whole catalog maintainers receive, and a pool row shows what its people
+receive at both `/mcp/<pool>` and, when they belong to no other pool, plain
+`/mcp`. A note above the rows says so. People in several pools appear in
+`config.peopleInSeveralPools`; plain `/mcp` refuses them.
+
 One row each for `/mcp` and every pool: the path, a read-only pill on a
 read-only endpoint, a copyable URL, who can use it, its connectors as colored
 monograms (four, then "+N"), its tool count over a read and write bar, and a
@@ -121,7 +127,9 @@ Setup button.
 - Who can use it is `root.maintainers` on `/mcp` and the pool's `members`
   elsewhere, as an avatar stack named on hover and to screen readers (label,
   raw id when the label is null, or agent name). Four show, then a "+N"
-  button. A pool with agent members labels its two URLs People and Agents.
+  button. A pool lists only people or only agents. An agent pool's row
+  still shows two URLs labeled People and Agents; the People URL
+  (`/mcp/<pool>`) admits no one, because the pool has no people.
 - Expanding a row lists everyone by name, then each connector with what it
   runs as and its tools, write tools amber with a pencil. Runs-as comes from
   the endpoint's matrix cell: "Shared · saved <date>", "Shared · connected
@@ -194,8 +202,9 @@ tabs:
   annotation badges (Destructive, Open world), filtered by search and All,
   Read and Write. A tool opens its schema in a side drawer.
 - **Connection.** An Authentication card (mode, OAuth client mechanism, who
-  manages it, OAuth actions, and the credential card with masked last four,
-  field states, and Replace, Test and Remove); a Diagnostics card of tiles
+  manages it, the last verification, OAuth actions, and the credential card
+  with masked last four, field states, and Replace, Test and Remove); a
+  Diagnostics card of tiles
   (catalog age and last call) with a fix prompt beside each
   problem; and a Configuration card. Its badges name the kind (Remote MCP,
   HTTP API or Custom), provider, auth scope, endpoint host and usage guide.
@@ -340,10 +349,12 @@ connections**, has no tabs; its heading shows the signed-in email when the
 sign-in exposes one (Clerk's primary email), and its top bar shows branding and
 an **Account** button with Sign out or Change token. It lists:
 
-- **Your endpoints**: one card per admitted `/mcp/<pool>` URL with a copy button
-  and **Client setup**. For example, Bob in pool `team` copies
-  `https://connecta.example.com/mcp/team` into an MCP client and authenticates
-  as Bob.
+- **Your endpoints**: one card per address with a copy button and **Client
+  setup**. A member of exactly one pool sees one card for plain `/mcp`, named
+  after the pool it serves; a member of several pools sees one
+  `/mcp/<pool>` card per pool. For example, Bob, only in pool `team`, copies
+  `https://connecta.example.com/mcp` into an MCP client and authenticates as
+  Bob.
 - **Your accounts**: the personal connectors in their pools, each with a
   monogram, tool count, one status badge in an aligned column, and only the
   controls its `manage.actions` lists. A saved credential that no longer fits
@@ -415,7 +426,8 @@ without this capability contribute an unconfirmed count of zero. For example,
 The maintainer view carries:
 
 - `config`, the construction-time `describeConfig()` snapshot, including
-  `maintainers` and each pool's `members`, and `configSources`, which labels
+  `maintainers`, each pool's `members`, `peopleInSeveralPools` (non-maintainer
+  people plain `/mcp` refuses because they are in several pools), and `configSources`, which labels
   each serialized leaf as `default` or `config` from option presence rather
   than equality with the default. Factory descriptions carry relative
   `optionSources` paths so resolved module and transport defaults retain their
@@ -488,7 +500,9 @@ The maintainer view carries:
 The member view is exactly that member's projection: `config`,
 `configSources` and `root` are `null`, `live.connectors`, `agents` and
 `matrix` are empty, and `live.activity` is `"forbidden"`. `pools` lists only
-their pools, each with `owner: null` and `members: []`. `connectors` lists
+their pools, each with `owner: null` and `members: []`. With exactly one pool,
+its `humanPath` is `/mcp`, the address that serves them that pool, and the
+member's catalog reads carry that pool as plain `/mcp` would. `connectors` lists
 each connector in those pools with its title, the member's pools that serve
 it, its auth scope, the tools those pools grant with their classification,
 `connection` (their own partition's state and problem code for a personal
@@ -556,6 +570,58 @@ the config snapshot, and never treats a `per_caller` overlay as an error.
 complete classified tools with input/output schemas, registration path, catalog
 age, and activity-derived last-call facts under the reader's disclosure policy.
 A failed or timed-out connector releases its own scope; siblings finish independently.
+The status and catalog observation has its own deadline: 8 seconds, or
+`discovery.probeTimeoutMs` when that is shorter, in which case the whole row
+uses that one deadline. The 8-second value is fixed, not configured; agent
+discovery keeps the full `discovery.probeTimeoutMs`. When the deadline ends
+first, the downstream read is aborted and the row returns `status: "error"`
+with `problem: "connector_timeout"` in the row and its overlay. The row still
+carries its credential card and auth permissions, so a slow connector's slot
+stays manageable. Any other failure keeps `connector_unavailable`. The
+connector renders as **Not responding**, with fixed copy, a fix prompt and
+Refresh.
+**Stored status.** Each live `GET /ui/connectors/:id` records one status
+observation for that connector and viewer partition before it answers: its
+state, problem code, tool count and observation time. Authored static catalogs
+such as `api()` connectors are recorded too, since their status still checks
+auth. The record lives in the `connector-health:v1:` family under the same
+owner partition as the catalog cache (principal, subject, caller identity and
+pool, endpoint, described configuration and package version), so a personal
+connector's observation is one person's. It also carries the catalog
+generation read before the probe, through the request's read memo that the
+catalog listing reuses. It holds no tools, schemas, status prose or
+credential facts. It expires 120 seconds after it was observed, and lapses at
+once when a credential change, OAuth connect or disconnect, or invalidation
+rotates the generation. A read that ends at the row's own deadline, including
+a configured `discovery.probeTimeoutMs` shorter than 8 seconds, records
+`connector_timeout` before it answers. An observation is written only while
+the caller is still waiting: a request its caller has already left starts no
+write. A write that has started is never raced against a deadline or
+detached, because a storage write cannot be withdrawn once sent. The request,
+whether it times out or its caller leaves meanwhile, settles only after that
+write does, bounded by the storage layer like every other awaited write, so
+nothing commits after the request ends.
+
+`GET /ui/connectors/:id?observation=stored` answers from a current observation
+without probing the downstream. The row and overlay carry `observedAgeMs`, the
+stored `status`, `problem` and `toolCount`, and `tools: []`; the tools stay in
+the catalog cache. The credential card, drift, permissions and any
+authorization link are computed fresh on every request. Without a current
+observation the route does the live read and records it, with no
+`observedAgeMs`. Nothing is refreshed after the response: no deferred work and
+no `ctx.waitUntil`.
+
+The browser asks each connector for its stored observation on the page load
+that follows admission, and fixes the observation time once as each stored
+row lands. The list card and the connector page mark a stored row the same
+way, "Stored status, checked … ago", with an age that keeps counting, and
+show its tools as awaiting the live read rather than as none. The browser then
+sends one plain live read per stored row, through the same queue of eight
+detail reads. A stored `connector_timeout` row is not read again on its own;
+its mark says to Refresh, and it waits for Refresh like a live timeout.
+Refresh, a single connector's read, recovery retries and OAuth polls always
+read live.
+
 The summary and each detail carry `viewerKey` for the principal admitted to that
 request. The browser publishes the detail and overlay atomically only when that
 key matches admission. A changed viewer key, including an Access switch between
@@ -568,7 +634,7 @@ screen. The first answer for the new viewer triggers readmission, which clears
 everything retained.
 Config observations never
 overwrite a completed detail row. Each connector opens at most one live observation
-per page load; the summary `/ui/data` performs no downstream probes.
+per page load, after its stored read; the summary `/ui/data` performs no downstream probes.
 
 `GET /ui/api/config?connector=<id>` narrows the same contract to one connector
 before status and catalog probes. For a maintainer, config, provenance, live
@@ -628,8 +694,23 @@ bounded at 2, 2, 4 and 8 seconds; a later focus return can try again after backo
 
 Connector Refresh, focus recovery and mutation follow-ups read only affected
 connectors. Focus probes unhealthy rows, never healthy siblings. All detail reads
-share a four-request limit and coalesce per connector. Failures retry only their
+in one tab share an eight-request limit and coalesce per connector, so a page of
+up to eight connectors loads in one round. The limit is fixed, not configured.
+It bounds how many connectors one tab waits on at once; a tab still reads each
+connector once per load, so the limit adds no requests to any one connector.
+Detail reads do not consume `admission.requests` permits, which govern `/mcp`
+only. They still share isolate CPU and memory, D1, and downstream account quotas
+with agent traffic; each tab adds up to eight concurrent downstream reads, and
+several connectors on one vendor account share that vendor's rate limit. Over HTTP/1.1 the browser itself allows about six
+connections per origin.
+Failures retry only their
 connector with the same bounded backoff; recovery never replays a mutation.
+A `connector_timeout` row is parked instead. It spends its automatic retry
+budget, and focus and visibility returns skip it. Only Refresh, a full refresh
+or a mutation follow-up reads it again, so an outage holds a detail slot once
+per explicit request, never repeatedly. An OAuth start's consent-return poll is
+the exception: a timeout during its 30-second window keeps polling, and success
+still stops it.
 Mutations cancel affected reads and advance their publication fence both at
 dispatch and on settlement, including failure. Follow-ups require an observation
 started after settlement, so a Refresh or retry started during the write cannot
@@ -638,9 +719,21 @@ while identity and full refresh revisions fence the complete view. An explicit
 OAuth start polls only that connector every two seconds for up to 30 seconds.
 Concurrent authorizations retain independent cancellation and publication. Success,
 failed reads, disconnect, navigation, unmount and identity reset stop the matching
-poll. Recovery never starts authorization. A scoped result cannot confirm identity,
+poll; a `connector_timeout` result does not. Recovery never starts authorization. A scoped result cannot confirm identity,
 role, token slots or any other deployment-wide admission fact.
 
+A credential connector's `/ui/data` and `/ui/connectors/<id>` row carries
+`verification: { outcome, observedAt }` when a record of the stored save
+exists (see [last verification](./auth.md#test-then-save-and-last-verification)).
+The auth facts show it as **Last verified**: Verified, Saved without a test,
+Rejected, Missing permission, Service unreachable, Test timed out or Test
+failed, with its time. A maintainer's credential form on a testable connector
+saves through **Test and save** (`verify: "test"`). A failed test leaves the
+form open with fixed copy for its failure class, and adds **Save without
+testing**, a save without `verify`. Test shows the same per-class copy and reloads
+the connector so its last verification updates. The member page's
+credential form saves without a test and offers Test once a value is stored.
+
 Unreadable credential metadata uses `configured: null`, including named fields,
 and renders as unavailable with a retry prompt. It does not claim that the slot
 is empty. Overview, Endpoints, Connectors, connector
@@ -699,10 +792,9 @@ the page's styles.
 
 `src/operator-ui/config-summary.ts` maps the snapshot and its provenance to
 those tiles: one table of limit labels, the formatters, and the walk that turns
-an unmapped key into an Other tile. `app/config-tiles.tsx` draws them, and
-`test/operator-config-summary.test.ts` checks formatting, provenance, unknown
-keys, an empty deployment, and that a real deployment's snapshot leaves no key
-unmapped.
+an unmapped key into an Other tile. `app/config-tiles.tsx` draws them.
+`test/browser/operator-flows.spec.ts` checks Settings provenance through the
+production UI and real routes.
 
 The contract type is [contract.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/contract.ts).
 [UI routes](https://github.com/zackbart/connecta/blob/main/src/routes/ui.ts) and

package/documentation/pool-membership-upgrade.md

@@ -0,0 +1,44 @@
+# Split mixed pools
+
+Every pool must list only people or only `agent:` references. A mixed pool
+throws `ConfigError` at construction naming the pool, for example
+`ConnectaConfig.pools.team.members mixes people and agents; list only one kind.`
+This also applies to personal pools with or without `owner`. Pool names and
+connector ids do not decide membership type. People-only pools may retain an
+`owner`; it never changes the account a person uses.
+
+Before upgrading, inspect every pool's `members`, including generated lists.
+For each mixed team pool, define its tool list once and create two pools:
+
+```ts
+const teamTools = ["crm", "tickets"];
+const pools = {
+  team: { tools: teamTools, members: ["user_alice", "user_bob"] },
+  "assistant-team": { tools: teamTools, members: ["agent:assistant"] },
+};
+```
+
+Keep the original human pool name when possible so people's existing
+`/mcp/team` address stays valid. Point the agent harness at
+`/agent/assistant-team` and update its tier list to that name. Copy the
+original `readOnly`, `surface`, `executeCode` and `description` settings
+to both new pools as appropriate so each preserves its intended behavior.
+If the mixed pool set `owner`, keep `owner` on the agent pool: it is the
+Workspace address the agent acts as, and without it Workspace connectors with
+a mapping `subject` disappear for the agent. People never use `owner`; they
+always act as themselves, so the people pool does not need it. Agent pools
+never count toward a person's plain `/mcp` routing, so a person who was in
+one mixed pool and no other still reaches the people pool at plain `/mcp`.
+
+For personal `assistant-alice` pools, keep only `"agent:assistant"` in
+`members` and retain the owner's Workspace address and tools. Give people
+their own people-only pools. Workspace mapping connectors act as each person;
+shared-auth connectors act as their saved account for every member, so review
+those grants before copying personal tool lists.
+
+An agent can still belong to many pools with one token. Tokens, credentials,
+`poolFor` tier selection logic and the Eve helper need no changes beyond pool
+names in client configuration. Rebuild and restart the deployment, then verify
+people and agents can each open their intended endpoints. See
+[Organizing an agent's pools](./auth.md#organizing-an-agents-pools) for the
+complete layout.

package/documentation/provider-auth-migration.md

@@ -1,15 +1,9 @@
 # Provider auth migration
 
-Hosted selections described in this historical migration are now removed.
-For Stripe, Vercel, Cloudflare, Notion, Mixpanel, and GitHub hosted connections,
-use the [current hosted MCP migration guide](./hosted-mcp-migration.md).
-The API migrations below remain applicable.
-
-Use this upgrade guide when moving a Stripe, Vercel, or Cloudflare
-deployment from 0.30 to 0.31, where `auth` selects each provider's
-implementation.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
-version changes; [integrating services](./integrating.md) covers new connectors.
+This guide covers the 0.30-to-0.31 change to auth-selected implementations.
+For current versions, follow [deployment upgrades](./deploying.md#upgrade-an-existing-deployment)
+and [hosted MCP migration](./hosted-mcp-migration.md); hosted selectors below
+are historical.
 
 A dual provider requires `auth`. `{ type: "oauth" }` connects the vendor's
 hosted MCP server, OAuth only. A key type connects Connecta's REST connector

package/documentation/provider-migration-0.29.md

@@ -1,20 +1,9 @@
 # Notion, Vercel and Cloudflare migration for 0.29
 
-Hosted selections described in this historical migration are now removed.
-For Stripe, Vercel, Cloudflare, Notion, Mixpanel, and GitHub hosted connections,
-use the [current hosted MCP migration guide](./hosted-mcp-migration.md).
-The API migrations below remain applicable.
-
-Use this upgrade guide for an existing deployment.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
-version changes; [integrating services](./integrating.md) covers new connectors.
-[The agent index](./README.md) routes package maintenance separately.
-
-This was the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709),
-which shipped as 0.29.0.
-Deployments that use Notion or Cloudflare must check their actual grants and
-connector ids in deployment configuration before that release.
-The provider audit establishes available auth modes, not production OAuth grants.
+This guide records the 0.29 Notion, Vercel and Cloudflare option changes.
+For upgrades to current versions, use [deployment upgrades](./deploying.md#upgrade-an-existing-deployment)
+and [hosted MCP migration](./hosted-mcp-migration.md); the hosted selectors below
+are historical and cannot be used in current configuration.
 
 Cloudflare's part of this guide is superseded: `cloudflare()` now selects its
 implementation by `auth` and its key connector is complete on its own. Follow