@terreno/mcp 57.10.1 → 57.12.0

package/dist/docs/versioned/next/reference/syncdb.md

@@ -10,6 +10,7 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 - [createSyncDb configuration](#createsyncdb-configuration)
 - [SyncDb client methods](#syncdb-client-methods)
 - [React hooks](#react-hooks)
+- [Query windows](#query-windows)
 - [Codegen](#codegen)
 - [Conflict API](#conflict-api)
 - [Sync status API](#sync-status-api)
@@ -25,7 +26,8 @@ Local-first data layer for Terreno frontends. A TinyBase `MergeableStore` on dev
 - `createSyncDb`, `SyncDb`, `SyncDbConfig`, `MutateArgs`
 - `betterAuthAdapter`, `bridgeBetterAuthReactClient`, `AuthProvider`
 - `listConflicts`, `wipeLocalData`, `generateMutationId`
-- React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`, `createCollectionHooks`
+- Queries: `QueryFieldNotAllowedError`, `ListRequestError`, `WhereFilter`, `SortSpec`, `WindowQuery`, `QueryWindowState`, `QueryWindows`, `compileWhere`, `DEFAULT_WINDOW_PAGE_SIZE`
+- React (`@terreno/syncdb/react`): `SyncDbProvider`, `useEntity`, `useQuery`, `useEntityIds`, `useWindowQuery`, `useMutate`, `useSyncStatus`, `useConflicts`, `useSyncDebugLog`, `createCollectionHooks`
 - CLI: `terreno-syncdb-codegen` (generates `SYNC_COLLECTIONS` + friendly hooks from OpenAPI)
 - Testing (`@terreno/syncdb/testing`): `createFakeTransport`
 
@@ -165,6 +167,7 @@ be passed to `betterAuthAdapter` directly.
 | `name` | `string` | — (required) | Persisted database name |
 | `collections` | `string[]` | — (required) | Collection names to sync (local tables + subscriptions) |
 | `windowCollections` | `string[]` | `[]` | Collections that join `{collection}\|admin`, skip snapshots/reconcile, and hydrate only known REST membership ids |
+| `queryCollections` | `Array<string \| {collection, path?, fullSync?}>` | `[]` | Collections too large to sync whole (or `fullSync: true` to keep snapshot sync and add windows). No snapshot/reconcile paging; rows arrive through [query windows](#query-windows) against the `modelRouter` list endpoint (`path`, default `/{collection}`) plus live deltas on the user's normal streams. Each entry must also be in `collections` and not in `windowCollections`. |
 | `organizationIdProvider` | `() => string \| undefined` | — | Read at send time: sets `X-Organization-Id` on HTTP sync calls and `organizationId` on socket mutate payloads |
 | `authProvider` | `AuthProvider` | — (required) | `{getToken, getUserId, onAuthChange, refresh?}` |
 | `baseUrl` | `string` | — | Server origin; required unless both `transport` and `httpChannel` are injected |
@@ -200,6 +203,7 @@ be passed to `betterAuthAdapter` directly.
 | `mutate({collection, operation, id?, data?})` | Optimistic local write + durable outbox enqueue + fire-and-forget replay. Returns `{mutationId, id}`. |
 | `reconcile()` | HTTP snapshot catch-up for every known stream; runs tombstone compaction on success. Also runs automatically on (re)connect, on a rate-limited seq-jump hint, and on the periodic timer; each `sync:subscribed` confirmation additionally pages just the streams it names. |
 | `hydrateWindow({collection, ids, restRows?})` | Admin window upsert: REST rows (optional) land immediately; every requested id is also fetched from `GET /sync/entities` before this resolves so seq/deleted metadata is canonical for immediate update/delete. A `{collection}|admin` delta that lands while the fetch is in flight wins, so hydration never rewinds a row to an older seq. Unknown ids are ignored. |
+| `queryWindows` | Server query windows for `queryCollections`: `fetchWindow({query, nextPage?})`, `getWindow(query)`, `retain(query)` → release, `refetchRetained()`, `pruneUnretained()`, `subscribe(cb)`, `keyFor(query)`. See [Query windows](#query-windows). |
 | `forceResync()` | Purge every known stream locally and re-bootstrap from cursor 0 (outbox/conflicts untouched). Returns `{ok, reason?, streams, purged, repaired}`. After discovery and each stream bootstrap it waits for in-flight `start`/`stop`/auth-change work, then abandons with `reason: "superseded"` when that work switched users or generations. |
 | `replayOutbox()` | Drain queued mutations for the current user now. |
 | `resolveConflict({mutationId, strategy})` | Apply `"useServer"` or `"keepMine"` to a recorded conflict. |
@@ -271,13 +275,26 @@ Subscribe to a single entity. Re-renders when that row changes. `isPending` is t
 
 ```typescript
 const todos = useQuery<Todo>("todos", {
-  filter: (t) => !t.completed,
-  sort: (a, b) => b.created.localeCompare(a.created),
-  includeDeleted: false,
+  where: {completed: false, created: {$gte: since}},
+  sort: "-created",
+  limit: 20,
 });
+
+// Callbacks still work and combine with `where`:
+const mine = useQuery<Todo>("todos", {filter: (t) => t.ownerId === userId, sort: byCreatedDesc});
 ```
 
-Returns decoded entity data arrays. Tombstones excluded unless `includeDeleted: true`. Filter and sort run in JS — memoize callbacks when collections are large.
+Returns decoded entity data arrays from the local store. Tombstones excluded unless `includeDeleted: true`.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `where` | `WhereFilter` | Mongo-style filter: equality, dot paths, `$eq` `$ne` `$gt` `$gte` `$lt` `$lte` `$in` `$nin` `$exists`, `$and` / `$or`. An array field matches when any element equals the value. Compared by value, so inline objects are fine. Throws for operators only the server can run (`$search`, `$regex`). |
+| `filter` | `(data) => boolean` | Arbitrary predicate, applied after `where`. |
+| `sort` | `SortSpec \| comparator` | `"-created name"`, `{created: "descending"}`, or `(a, b) => number`. |
+| `limit` | `number` | Keep the first N rows after filter and sort. |
+| `includeDeleted` | `boolean` | Include tombstones. |
+
+Filter and sort run in JS — memoize `filter`/comparator callbacks when collections are large.
 
 ### `useEntityIds(collection, options?)`
 
@@ -288,6 +305,38 @@ return ids.map((id) => <TodoRow key={id} id={id} />);
 
 Same options as `useQuery`, but returns only ordered ids with **referential stability** — the array identity changes only when membership or order changes, not on field updates. Pair with per-row `useEntity` for large lists.
 
+### `useWindowQuery(collection, options?)`
+
+```typescript
+const {data, isLoading, isFetching, hasMore, fetchNextPage, refetch, total, error} =
+  useWindowQuery<Message>("messages", {
+    where: {threadId, deleted: false},
+    sort: "-created",
+    pageSize: 30,
+  });
+```
+
+Server-filtered list over a `queryCollections` collection. See [Query windows](#query-windows).
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `where` | `WhereFilter` | — | Sent as qs list params (`status[$in][0]=open`). Fields must be in the route's `queryFields`. |
+| `sort` | `SortSpec` | route default | Server `sort`; also orders the local view. |
+| `pageSize` | `number` | `50` | Server `limit` per page (capped by the route's `maxLimit`). |
+| `skip` | `boolean` | `false` | Do not retain or fetch (e.g. a required param is missing). |
+| `liveMatch` | `boolean` | `true` | Show cached rows that newly match `where` inside the loaded range. |
+
+| Result | Description |
+|--------|-------------|
+| `data` / `ids` | This window's rows in view order. |
+| `isLoading` | No membership yet (first fetch in flight). Cached membership renders with `isLoading: false`. |
+| `isFetching` | Any request for this window is in flight. |
+| `isError` / `error` | Last request failed (cached rows still render). |
+| `errorCode` | Server error code of the last failure; `"query-param-not-allowed"` means a `where` field is missing from `queryFields`. |
+| `hasMore` / `total` | From the list response's `more` / `total`. |
+| `fetchNextPage()` | Append the next server page. |
+| `refetch()` | Reload every loaded page in one request, replacing membership. |
+
 ### `useMutate(collection)`
 
 ```typescript
@@ -331,7 +380,7 @@ Returns the `SyncDb` instance from context (escape hatch for imperative calls li
 
 ### `createCollectionHooks`
 
-Factory used by `terreno-syncdb-codegen` and by hand-written custom collections. Returns five operation hooks (`useListQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`). Generated SDKs rename them to friendly names (`useTodos`, `useTodo`, `useCreateTodo`, …). Mutation hooks return `[trigger]`; triggers apply locally and return `{mutationId, id}` synchronously. Optional `retries` maps to `maxAttempts` (`false` → 1, a number → that many, omitted → engine default).
+Factory used by `terreno-syncdb-codegen` and by hand-written custom collections. Returns six operation hooks (`useListQuery`, `useWindowQuery`, `useReadQuery`, `useCreateMutation`, `useUpdateMutation`, `useDeleteMutation`). Generated SDKs rename them to friendly names (`useTodos`, `useTodosWindow`, `useTodo`, `useCreateTodo`, …). `useWindowQuery` works only for collections listed in `queryCollections`. Mutation hooks return `[trigger]`; triggers apply locally and return `{mutationId, id}` synchronously. Optional `retries` maps to `maxAttempts` (`false` → 1, a number → that many, omitted → engine default).
 
 ```typescript
 export const {useListQuery: useNotes, useCreateMutation: useCreateNote} =
@@ -340,6 +389,107 @@ export const {useListQuery: useNotes, useCreateMutation: useCreateNote} =
   });
 ```
 
+## Query windows
+
+Use query windows when a collection is too large to sync whole (messages, events, audit
+rows). They match what an RTK list query did — `where`, `sort`, `limit`, `page`, `more`,
+`total` — but keep the data local-first and deduplicated.
+
+```typescript
+export const syncDb = createSyncDb({
+  collections: ["todos", "messages"],
+  queryCollections: [{collection: "messages", path: "/messages"}],
+  // ...
+});
+```
+
+**Membership, not copies.** A window is one list query against the collection's
+`modelRouter` list endpoint. Its result is an ordered id list stored in the reserved
+`_queryWindows` table. Each row lands once in the collection's entity table, keyed by id.
+Two windows that overlap share those rows:
+
+- A delta, mutation, or refetch for a shared row writes the store once; every window that
+  lists the row re-renders from it.
+- Each window lists only its own members. Window B never shows rows that only window A
+  fetched.
+
+**Live membership.** When `where` is locally evaluable (see `useQuery`'s `where`), a window
+also:
+
+- hides a member whose fields stop matching (an unpinned message leaves the "pinned" window);
+- shows cached rows that newly match (a live delta, or a local create) when they sort inside
+  the loaded range. With more pages unloaded, a row that sorts after the last loaded row
+  waits for `fetchNextPage()`. Without a `sort` and with more pages, only local creates are
+  admitted.
+
+A full fetch also records cached rows that matched `where` locally but that the server did
+not return (deleted, changed, or no longer visible while this device was offline). They stay
+out of the view until a newer delta or a local edit changes them, so stale cached data never
+resurrects a row.
+
+Set `liveMatch: false` to show server membership only. Operators only the server runs
+(`$search`) also fall back to server membership.
+
+**Fetching.** The first `retain` of a window in a session fetches it; persisted membership
+renders meanwhile, so windows work offline. Concurrent fetches of the same window share one
+request; a refetch and a `fetchNextPage()` on one window run one after the other. Retained
+windows refetch on reconnect and after `forceResync()` — query collections
+skip snapshot catch-up, so this is how deltas missed offline are recovered. Windows not on
+screen at that moment refetch the next time they are shown. Window fetches
+started before a `stop()` or user switch are discarded.
+
+**Seq.** List rows that carry `_syncSeq` (the `syncPlugin` field) are written with that seq.
+Rows without it (a `responseHandler` that strips it) are re-read from `GET /sync/entities` so
+a later mutation never sends a stale `baseVersion`. Rows with a pending outbox mutation, or
+with a newer seq from a delta, are never overwritten. A list `responseHandler` must return the
+same shape as the sync serializer; otherwise list rows and delta rows differ.
+
+**Missing `queryFields`.** Every `where` field must be in the route's `queryFields`. The
+server answers 400 `query-param-not-allowed` naming the field, the model, and the allowed
+list. syncdb turns it into `QueryFieldNotAllowedError` (`field`, `allowedQueryFields`,
+`model`), logs it with `console.error`, sets the window's `errorCode` to
+`"query-param-not-allowed"`, and rejects `fetchWindow` / `refetch` / `fetchNextPage` with it.
+Other list failures throw `ListRequestError` (`status`, `code`, `detail`).
+
+```typescript
+import {QueryFieldNotAllowedError} from "@terreno/syncdb";
+
+try {
+  await refetch();
+} catch (error) {
+  if (error instanceof QueryFieldNotAllowedError) {
+    // error.field === "title", error.allowedQueryFields === ["completed", "created", "ownerId"]
+  }
+}
+```
+
+**`maxLimit` and pipelining.** `modelRouter` clamps `limit` to the route's `maxLimit` and
+echoes the applied value. Window requests always send `page` (so the server never logs a
+truncated unpaginated list). When a fetch needs more rows than one request returns — a
+`refetch()` after several `fetchNextPage()` calls, or a `pageSize` above `maxLimit` — syncdb
+learns the cap from the echoed `limit` and splits the range into sequential page requests
+of `maxLimit` rows starting at the aligned page that contains the range, trimming the extra
+rows, so offsets stay exact. Each pipelined fetch logs a
+`console.warn` naming the row count, the cap, and the request count. Fix it by loading fewer
+pages, lowering `pageSize`, or raising `maxLimit` on the route.
+
+**Fully synced collections.** `queryCollections: [{collection: "todos", fullSync: true}]`
+keeps normal snapshot sync and also enables windows, for server-side filtering, paging, and
+totals over a collection that is already local. See `example-frontend/app/todo-windows.tsx`.
+
+**Limits.**
+
+- `refetch()` with several pages loaded reloads `pageSize × pages` rows (see below).
+- Page appends dedupe ids. A delete between page loads can shift offsets and skip one row
+  until the next refetch.
+- `null` in `where` is rejected (qs would send the string `"null"`); use `{$exists: false}`.
+  A top-level `{$in: []}` returns an empty window without a request; an empty array anywhere
+  else throws instead of silently widening the query.
+- Rows stay in the entity table after their windows unmount. `start()` prunes persisted
+  membership of unretained windows not fetched for 7 days (`pruneStale`);
+  `pruneUnretained()` drops all unretained membership. Rows are dropped by leave-purge,
+  tombstone compaction, or a wipe.
+
 ## Codegen
 
 `terreno-syncdb-codegen` is a bin of `@terreno/syncdb`. It reads OpenAPI, discovers list operations with `x-terreno-sync`, and writes typed hooks plus `SYNC_COLLECTIONS`.

package/dist/docs/versioned/next/reference/ui.md

@@ -725,11 +725,20 @@ Master-detail layout. Pass `listViewData` plus `renderListViewItem` for the list
 screens the detail replaces the list until the user goes back.
 
 `desktopChildrenMinWidth` opts into a minimum pixel width for each desktop child when there
-are one or two children. `narrowViewportChildLabels` opts into a labeled full-width pager on
-the narrow viewport. `narrowBelowWidth` uses that viewport when the window is at or below the
-given pixel width; when omitted, the narrow viewport follows `isNarrowViewport()`. These props
-are web only; the native `SplitPage` ignores them. See `SplitPageProps` for when each prop
-applies and what is ignored.
+are one or two children. `childColumnRounding` sets the border radius on each desktop detail
+pane (defaults to `md`, 4px); the list column is excluded. The pane clips to that radius. The
+column inside it scrolls: content taller than the pane scrolls in the column, and a child with
+`height: "100%"` fills the visible pane so a scroll view inside that child scrolls on its own.
+On a narrow web viewport the pager page is height-bounded to that same visible pane. Its rounded
+corners still clip, and a `height: "100%"` child scrolls inside the page. On the labeled pager,
+previous and next sit in fixed left and right slots in a row under the column. A missing direction
+leaves that slot empty, so the other arrow stays put. The column height is the measured pane minus
+top spacing, the navigation row, bottom spacing, and `bottomNavBarHeight`.
+`narrowViewportChildLabels`
+opts into a labeled full-width pager on the narrow viewport. `narrowBelowWidth` uses that
+viewport when the window is at or below the given pixel width; when omitted, the narrow
+viewport follows `isNarrowViewport()`. These props are web only; the native `SplitPage`
+ignores them. See `SplitPageProps` for when each prop applies and what is ignored.
 `IconButton`'s `backgroundOpacity` tints only that button's background.
 
 ```typescript

package/dist/docs/versioned/next/tasks/durable-agent-harness.md

@@ -131,21 +131,23 @@ created in 1.1 and extended by every later task — never deferred.
 
 ## Phase 2 — Multi-instance
 
-- [ ] **Task 2.0**: `InProcessRunner` concurrency
+- [x] **Task 2.0**: `InProcessRunner` concurrency
   - Delivers: `new InProcessRunner({concurrency})` (default 8) runs up to N claimed tasks at once, each with its own lease and heartbeat; a slow phase no longer delays other tasks' wakes; `stop()` waits for all in-flight phases
   - Files: `ai/src/harness/runners/inProcessRunner.ts`, tests
   - Blocked by: 1.12
   - Skills: `terreno-backend-api`
   - Docs: reference "Runners" (concurrency option, ordering guarantees)
   - Acceptance: bun test — a phase blocked on a gate does not prevent a second task from completing; never more than N concurrent; no task runs twice concurrently
+  - Shipped: fake-context cases in `ai/src/harness/runners/inProcessRunner.test.ts` (default 8, gate, peak, stop waits for all, invalid concurrency) and real-Mongo cases in `ai/src/harness/concurrency.test.ts` (blocked task does not hold up a second; 7 two-phase tasks at concurrency 3 peak at exactly 3 with no task running twice). Roast: PASS (2026-10-04; 76 targeted tests, three mutation checks red)
 
-- [ ] **Task 2.1**: `JobsRunner`
+- [x] **Task 2.1**: `JobsRunner`
   - Delivers: `@terreno/ai/harness/jobsRunner` with optional peer `@terreno/jobs`; job `terreno.harness.phase` keyed `taskId:phase:attempt`; harness task lease + heartbeat is the authority; importing the root `@terreno/ai` never loads jobs
   - Files: `ai/src/harness/runners/jobsRunner.ts`, `ai/package.json`, tests
   - Blocked by: 2.0
   - Skills: `terreno-backend-api`
   - Docs: reference "Runners"; how-to "Run on multiple instances"
   - Acceptance: AC11 — two workers race one phase; exactly one commit; stale owner rejected; knip clean without jobs installed
+  - Shipped: `ai/src/harness/runners/jobsRunner.test.ts` (two-worker race, stale-lease commit rejected, re-dispatch of a dead job, root imports never reach `@terreno/jobs`). Drift: the job key is `taskId:phase:attempt:claims` — `claims` (new `HarnessTask` counter) gives a phase revisited by an event wake or crash replay its own job, since jobs idempotency keys are permanent. Built before Task 2.0; it does not depend on `InProcessRunner` concurrency. Roast: PASS (2026-10-04; 17 targeted tests, ai suite 1185/0, knip clean, two mutation checks red)
 
 - [ ] **Task 2.2**: Runs admin screen
   - Delivers: task list/tree with status filters, abort, resolve-interrupted (retry/abort/complete + reason), link to trace

package/package.json

@@ -11,8 +11,8 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@sentry/bun": "^10.39.0",
-    "@terreno/api": "57.10.1",
-    "@terreno/blocks": "57.10.1",
+    "@terreno/api": "57.12.0",
+    "@terreno/blocks": "57.12.0",
     "express": "^5.2.1",
     "luxon": "^3.7.2",
     "minisearch": "^7.2.0",
@@ -105,5 +105,5 @@
     "test:coverage": "bun run ../scripts/check-coverage.ts"
   },
   "type": "module",
-  "version": "57.10.1"
+  "version": "57.12.0"
 }

package/src/docs/upgrades/57.11.0.md

@@ -0,0 +1,80 @@
+# Upgrading to 57.11.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/ai, @terreno/api
+
+## Summary
+
+`InProcessRunner` now runs up to eight harness tasks at once. List filters on a field that is not in `queryFields` return 400 before request validation, so that filter can no longer be stripped and ignored. Slack channel helpers and syncdb query windows are opt-in.
+
+## Breaking changes
+
+### InProcessRunner runs tasks in parallel
+
+**What changed**
+
+`new InProcessRunner()` runs up to 8 claimed tasks at once. Each task has its own lease. `stop()` waits for every in-flight task. Turns inside one conversation stay serial. Model calls run in parallel, so provider rate limits, cost, and stream-counter transaction retries all go up.
+
+**Why**
+
+A single slow model call was blocking every other task on that process.
+
+**Migration**
+
+```typescript
+// Before: one claimed task at a time
+const runner = new InProcessRunner();
+
+// After: keep that behavior
+const runner = new InProcessRunner({concurrency: 1});
+
+// Or accept the new default (8)
+const runner = new InProcessRunner();
+```
+
+### List filters outside queryFields are no longer ignored
+
+**What changed**
+
+`GET` list on `modelRouter` checks every filter against `queryFields` before OpenAPI query validation. A field that is not listed returns 400 `query-param-not-allowed`. The body names the field, the model, and `meta.allowedQueryFields`. `@terreno/syncdb` raises `QueryFieldNotAllowedError` for the same response. Pagination params `limit`, `page`, and `sort` are unchanged.
+
+**Why**
+
+Query validation could strip an unknown filter and still return 200, so the client thought the filter applied.
+
+**Migration**
+
+```typescript
+// Before: ?title=ship could be stripped and the list still returned 200
+modelRouter("/todos", Todo, {queryFields: ["completed", "ownerId"]});
+
+// After: add the field, or stop sending it
+modelRouter("/todos", Todo, {queryFields: ["completed", "ownerId", "title"]});
+```
+
+A 400 looks like:
+
+```json
+{
+  "status": 400,
+  "code": "query-param-not-allowed",
+  "title": "Query parameter not allowed",
+  "meta": {"queryParam": "title", "model": "Todo", "allowedQueryFields": ["completed", "ownerId"]}
+}
+```
+
+## Deprecations
+
+None
+
+## New capabilities
+
+- `JobsRunner` from `@terreno/ai/harness/jobsRunner` runs each harness phase as a `@terreno/jobs` job (`terreno.harness.phase`) so more than one instance can share the work. `@terreno/jobs` is an optional peer. `HarnessTask.claims` defaults to 0 and needs no migration. See `docs/how-to/run-harness-on-multiple-instances.md`.
+- `@terreno/api` Slack helpers use the existing `SLACK_BOT_TOKEN`: `createSlackPrivateChannel`, `inviteSlackUsersToChannel`, `postSlackMessage`, and `findSlackChannelByName`. The bot needs `groups:write`, `groups:write.invites`, `channels:write.invites`, `chat:write`, `channels:read`, and `groups:read`. A taken channel name returns 409.
+- `@terreno/syncdb` query windows: set `queryCollections`, then use `client.queryWindows` or `useWindowQuery` (and generated `use{Collection}Window` hooks) for server-filtered, paged lists. `useQuery` and `useEntityIds` accept the same Mongo-style `where`, string sort, and `limit` for local queries. `fullSync: true` adds windows without turning off snapshot sync.
+
+## Verification
+
+- Apps that construct `InProcessRunner` with no options: confirm parallel model calls are acceptable, or pass `{concurrency: 1}`.
+- Hit one list route with a filter field that is not in `queryFields` and confirm 400 `query-param-not-allowed` instead of a 200 that ignored the filter.
+- `bun run compile` and `bun run lint` at the app root.

package/src/docs/upgrades/57.12.0.md

@@ -0,0 +1,89 @@
+# Upgrading to 57.12.0
+
+**Action required:** Yes
+**Affected packages:** @terreno/ai
+
+## Summary
+
+Harness tasks can record a trace scope, tags, and prompt versions, and `@terreno/ai` publishes official subpath exports. The chat `Project` model registers on first use instead of at import, and harness task HTTP responses no longer include the lease fencing token.
+
+## Breaking changes
+
+### `Project` is no longer registered on import
+
+**What changed**
+
+Importing `@terreno/ai` does not register mongoose model `Project`. The exported `Project` is a lazy proxy. The first property access, `new Project(...)`, or `getProjectModel()` registers the model. Statics and `instanceof Project` still work. These do not:
+
+- `Project === mongoose.models.Project` (and `Project === mongoose.model("Project")`)
+- `Object.keys(Project)` (always empty)
+- reading `Project.prototype` (throws)
+
+`new AiApp()` still mounts `/gpt/projects` and registers the model when those routes load. `new AiApp({projects: false})` skips those routes.
+
+**Why**
+
+An app that imports `@terreno/ai` and owns its own model named `Project` was hitting a mongoose overwrite error at import time.
+
+**Migration**
+
+```typescript
+// Before
+import {Project} from "@terreno/ai";
+
+const project = await Project.findExactlyOne({_id: id});
+if (mongoose.models.Project === Project) {
+  // identity check
+}
+
+// After
+import {getProjectModel} from "@terreno/ai";
+
+const Project = getProjectModel();
+const project = await Project.findExactlyOne({_id: id});
+```
+
+To keep a separate app model named `Project`, do not call `getProjectModel()` or touch the `Project` export, and skip the AI project routes:
+
+```typescript
+new AiApp({aiService, projects: false});
+```
+
+### Harness task HTTP responses omit `lease`
+
+**What changed**
+
+`GET /harness/tasks/:id` no longer includes `lease`. The OpenAPI schema for that response omits it too. Collection list is disabled (`list: []`, 405). The token is still stored on the task document for runners.
+
+**Why**
+
+`lease.token` is the fencing token that decides which runner may commit. It is not a client field.
+
+**Migration**
+
+```typescript
+// Before
+const token = task.lease?.token;
+
+// After
+// Do not read lease from the HTTP task. Runners load it on the server.
+```
+
+Regenerate the OpenAPI SDK after upgrading `@terreno/ai` so generated task types drop `lease`.
+
+## Deprecations
+
+`Project` from `@terreno/ai` still works for `find`, `create`, `new`, and `instanceof`. It is deprecated. Call `getProjectModel()` and use that model. A later major can remove the proxy.
+
+## New capabilities
+
+- `harness.createTask(def, input, {trace: {scope, tags}, prompts})` writes a scope (tenant, workspace), tags, and prompt versions onto the task's `ObsTrace`. Child tasks and subagents share that trace. The admin trace list filters with `?scope=`.
+- `rt.runAgent` accepts `prompts` and a registry `PromptVersionRef` as `instructions`. It runs `body` and records the version on the trace.
+- Subpath exports: `@terreno/ai/admin`, `@terreno/ai/harness/agentLoop`, `@terreno/ai/harness/commit`, `@terreno/ai/harness/events`, `@terreno/ai/harness/internalRuntime`, `@terreno/ai/observability/observabilityApp`, `@terreno/ai/observability/localPlugin`, `@terreno/ai/observability/promptStore`.
+
+## Verification
+
+- Code that imported `Project` from `@terreno/ai`: switch identity checks and `mongoose.models.Project` reads to `getProjectModel()`.
+- An app that owns a model named `Project`: pass `projects: false` and do not call `getProjectModel()`.
+- Harness clients: confirm `GET /harness/tasks/:id` JSON has no `lease`, then regenerate the SDK.
+- `bun run compile` and `bun run lint` at the app root.

package/src/docs/versioned/next/explanation/ai-workflows.md

@@ -49,9 +49,10 @@ Maintains centralized agent guidance and generates the matching configuration fo
 
 Rulesync generates native hooks from `.rulesync/hooks.json`. Biome checks changed files
 after edits and staged files before commits. At agent stop,
-`.rulesync/hooks/quality-check.sh` runs lint, TypeScript compilation, Knip, and
-dependency-cruiser. It keeps stdout machine-readable for each host and prevents
-retry-triggered Stop hooks from rerunning the commands.
+`.rulesync/hooks/quality-check.sh` runs `bun install --frozen-lockfile` when
+`node_modules/typescript` or any workspace package link is missing, then runs lint,
+TypeScript compilation, Knip, and dependency-cruiser. It keeps stdout machine-readable
+for each host and prevents retry-triggered Stop hooks from rerunning the commands.
 
 Existing findings are ratcheted so the checks reject new debt without requiring unrelated
 cleanup. See [Static analysis](static-analysis.md).

package/src/docs/versioned/next/explanation/durable-agent-harness.md

@@ -47,8 +47,11 @@ agents, tools, and conversations (see [The agent loop](#the-agent-loop)), subage
 extensions, hooks, and memos (see [Extensions, hooks, and memos](#extensions-hooks-and-memos)),
 events, waits, and approvals with the admin inbox, the SSE event stream, and version
 pinning. The example backend's `clinic.intakeSummary` runs all of it end to end, including
-a crash drill: [Build a durable workflow](../how-to/build-a-durable-workflow.md). Other
-runners (jobs-backed, concurrent) come in Phase 2.
+a crash drill: [Build a durable workflow](../how-to/build-a-durable-workflow.md).
+
+Phase 2 so far: `InProcessRunner` concurrency (up to 8 tasks at once by
+default) and the `JobsRunner`, which runs each phase as a `@terreno/jobs` job across many
+instances. The Runs admin screen is still to come.
 
 ## Why the audit span shares the checkpoint transaction
 
@@ -237,8 +240,18 @@ tasks. Switching runners needs no data migration.
 
 | Runner | Status | Ownership |
 | --- | --- | --- |
-| `InProcessRunner` | Shipped | One process holds the `HarnessOwner` lease and drains `pending` tasks one at a time; others wait on standby and take over on lease expiry. |
-| `JobsRunner` | Planned (Phase 2) | Each runnable phase becomes a `@terreno/jobs` job. The task lease is the authority. |
+| `InProcessRunner` | Shipped | One process holds the `HarnessOwner` lease and runs up to `concurrency` (default 8) claimed tasks at once, each under its own task lease; others wait on standby and take over on lease expiry. |
+| `JobsRunner` | Shipped | Every instance dispatches runnable tasks as `terreno.harness.phase` jobs; a job claims its task, runs one phase, and hands the task back. The task lease is the authority. |
+
+Why the jobs runner runs **one** phase per job: a phase is the unit that commits, so it is
+the natural unit of work to spread across instances and to bound by a request or job
+timeout. Why the task lease and not the job lock decides who commits: a jobs lock can
+expire while a long phase still runs, and a queue can deliver a job twice. Both are
+harmless here, because the claim is an atomic fenced update and every commit checks the
+lease token. Why the job key carries `claims`: `taskId:phase:attempt` alone repeats when a
+task returns to the same phase without a failure (an event wake or a crash replay), and a
+permanent idempotency key would then swallow the new visit. `claims` changes on every
+claim, so each visit gets one job.
 
 ## Version pinning
 

package/src/docs/versioned/next/explanation/local-first-data.md

@@ -39,6 +39,7 @@ Terreno 57.
 3. **Encryption at rest (web)** — Web persistence uses AES-GCM via the default `createServerKeyProvider`; understand key fetch and `onDecryptFailure` for support flows.
 4. **Key lifecycle on logout** — Call `syncDb.stop()` and consider `wipeLocalData` when the authenticated user changes so one account does not read another's local store.
 5. **Backend sync registration** — Every synced collection needs `syncPlugin`, `isDeletedPlugin`, and a `sync` block on `modelRouter`, plus `SyncApp` and `RealtimeApp` on the server. Optional `sync.adminBroadcast: true` also emits `sync:delta` to `{collection}|admin`. Admin clients subscribe with `mode: "window"` (`createSyncDb({windowCollections})`) so they do not snapshot or reconcile that collection; they call `hydrateWindow` (REST membership ids + `GET /sync/entities`). Pass the same `accessControl` into `SyncApp` that `AdminApp` uses so `{collection}|admin` requires `admin:access`. `AdminApp.register` also installs that model's admin list/read/`queryFilter` on the admin window so hydrate and live `|admin` deltas match `/admin` REST. Without RBAC, `user.admin` is enough for the shell gate. Live deltas on that stream apply only to ids already in the window; Refresh is a REST re-query plus `hydrateWindow`.
+6. **Collections too large to sync whole** — List them in `createSyncDb({queryCollections})`. They skip snapshot bootstrap; screens load server-filtered *query windows* (`useWindowQuery`) from the `modelRouter` list endpoint. A window stores only membership (ordered ids); rows live once in the shared entity table. Overlapping windows therefore share rows — one delta updates both views — while each view lists only its own query's members, plus cached rows that newly match its `where` inside the loaded range. Live deltas still arrive on the user's normal streams; windows on screen refetch on reconnect to cover deltas missed offline.
 
 ## Tradeoffs
 

package/src/docs/versioned/next/explanation/roadmap-process.md

@@ -402,7 +402,7 @@ do not claim completion until done.
 | Workflow | Trigger | Purpose |
 | -------- | ------- | ------- |
 | [`.github/workflows/triage.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/triage.yml) | Issue opened | `status:needs-triage` + `area:*` from package dropdown + `type:*` from Kind when present; `area:*` / `type:*` labels the issue was opened with win, so `roadmap:sync` issues are not asked for an area |
-| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when it changes |
+| [`.github/workflows/roadmap-generate.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-generate.yml) | Daily + manual | `roadmap:sync --check` for board drift, then regenerate `ROADMAP.md` from the board and open a pull request when roadmap content changes. A new **Last updated** timestamp alone does not open a pull request |
 | [`.github/workflows/roadmap-sync.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-sync.yml) | Taxonomy files change on `master` + manual | Apply labels and reconcile the board's fields and items |
 | [`.github/workflows/roadmap-reconcile.yml`](https://github.com/TerrenoLabs/terreno/blob/master/.github/workflows/roadmap-reconcile.yml) | IP or task files change on `master` + manual | Advance status from IP headers, add an entry for every new IP, open its tracking issue, push to the board, regenerate `ROADMAP.md` |
 All three share the `roadmap` concurrency group. They write the same board, and interleaving
@@ -495,4 +495,6 @@ GITHUB_TOKEN=$(gh auth token) TERRENO_PROJECT_NUMBER=... bun run roadmap:generat
 ```
 
 The generator exits non-zero when the project cannot be read, so a bad project number or a
-token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`.
+token without `read:project` fails loudly instead of writing an empty `ROADMAP.md`. When the
+rendered list matches the file already on disk, it keeps that file's **Last updated** stamp
+and does not write. The daily workflow then sees a clean diff and does not open a pull request.

package/src/docs/versioned/next/how-to/README.md

@@ -37,6 +37,7 @@ Problem-oriented, practical steps. Use these when you know what you want to do.
 - [Develop an AI feature](ai-feature-development.md) — Dataset → prompt → evaluators → experiment → production label → live traces (SOP)
 - [Observe LLM calls](observe-llm-calls.md) — Register ObservabilityApp, primaries, price map, sampleRate
 - [Build a durable workflow](build-a-durable-workflow.md) — Phased harness task with an agent, a human sign-off, and a once-only side effect (`clinic.intakeSummary`)
+- [Run the harness on multiple instances](run-harness-on-multiple-instances.md) — `JobsRunner`: harness phases as `@terreno/jobs` jobs on every instance
 - [Ship a new task version](ship-a-new-task-version.md) — Change a durable harness task without stranding in-flight runs
 - [GitHub issue lifecycle](github-issue-lifecycle.md) — Create pick-ready issues, Pick ⇄ Roast, or unattended `status:ready-for-dev` pickup
 - [Call external APIs](call-external-apis.md) — Authenticated HTTP client, retries, and error normalization for third-party integrations

package/src/docs/versioned/next/how-to/call-external-apis.md

@@ -94,7 +94,7 @@ Note the hook's output classification also feeds the client's retry decision —
 
 - **Your own backend's routes** — use the generated `@terreno/rtk` SDK (frontend) or call the function directly (backend).
 - **SDK-managed transport** (Twilio, googleapis) — don't fight the SDK's HTTP layer; adopt only `normalizeApiError`/`withApiErrorHandling` for consistent failure handling.
-- **Webhook notifiers** — `sendToSlack`/`sendToGoogleChat`/`sendToZoom` already exist; see [Webhooks & Notifications](../reference/api.md#webhooks--notifications). Slack @-mentions require a stored Slack member ID (`mentionUserIds` or `formatSlackUserMention`); names and emails in the text do not notify anyone.
+- **Webhook notifiers** — `sendToSlack`/`sendToGoogleChat`/`sendToZoom` post to a fixed webhook. Slack channel creation, invites, and bot posts use `createSlackPrivateChannel`, `inviteSlackUsersToChannel`, and `postSlackMessage` with `SLACK_BOT_TOKEN`. See [Webhooks & Notifications](../reference/api.md#webhooks--notifications).
 
 ## Related
 

package/src/docs/versioned/next/how-to/circleci.md

@@ -254,8 +254,12 @@ the review script so a PR cannot rewrite the reviewer.
 Netlify and GCP jobs **validate their context as the first step** and fail,
 before checkout or `bun install`, listing the missing variables. Preview jobs
 halt earlier on fork PRs, where CircleCI withholds contexts. Docker Layer
-Caching is off (200 credits per job). The docs Netlify target disables
-Docusaurus minification so the build stays within the 8 GB `large` executor.
+Caching is off (200 credits per job). The docs Netlify target builds only the
+current docs tree, disables Docusaurus minification, and pins SSG to one worker
+thread so the build peaks near 3 GB and fits the 4 GB `medium` executor.
+Released versions are not rebuilt: `archive-docs-version` (in `publish-release`,
+`X.Y.0` tags only) builds each one once and uploads it to its GitHub release, and
+`deploy-docs` unpacks those archives under `/<version>/`. See `website/README.md`.
 
 `terreno-gcp` uses CircleCI OIDC (`CIRCLE_OIDC_TOKEN_V2`), never a JSON service
 account key. Set `circleci_org_id`, `circleci_project_id`, and

package/src/docs/versioned/next/how-to/github-actions-ci.md

@@ -7,24 +7,23 @@ describes how they behaved if one is ever re-enabled.
 
 ## Docs site (`docs-deploy.yml`)
 
-`Build docs site` is often the longest PR job because Docusaurus compiles every
-versioned tree under `website/versioned_docs/` and TypeDoc regenerates API
-pages.
+`Build docs site` is often the longest PR job because TypeDoc regenerates API
+pages. The site builds only the current docs tree; `website/versioned_docs/` is
+markdown for the MCP server.
 
 PR builds set `DOCS_PREVIEW=true` and pass `--no-minify`. Both PR and
 `master` use Docusaurus Faster (Rspack/SWC via `@docusaurus/faster`).
 
 | Behavior | PR preview | `master` production |
 | --- | --- | --- |
-| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted (`disableVersioning`) | Built |
+| Versioned docs (`57.1.0`, `0.30.0`, …) | Omitted | Prebuilt archives unpacked under `/<version>/` |
 | JS minify | Off | On |
 | Local search index | Skipped | Built |
 | Generated API + component MDX | Restored from cache when `api`/`rtk`/`ui` hashes match | Same cache, then full generate on miss |
 | TypeDoc workspace `tsc` | Once per generate (api+rtk deps share a process) | Same |
 | Rspack cache (`node_modules/.cache/rspack`) | Restored per `pull_request` vs `push` | Separate production key |
 
-Production still builds every version. Do not rely on `/57.1.0/…` URLs in a
-PR deploy preview.
+Do not rely on `/57.1.0/…` URLs in a PR deploy preview.
 
 ## Other high-cost jobs