@terreno/mcp 57.10.1 → 57.12.0

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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
 

package/dist/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -152,7 +152,37 @@ import {useQuery} from "@terreno/syncdb/react";
 const todos = useQuery<Todo>("todos", {filter: (t) => !t.completed});
 ```
 
-`filter` / `sort` run in JS — there are no server query params. Tombstones are excluded unless `{includeDeleted: true}`.
+`where` / `filter` / `sort` / `limit` run in JS over the local store. Tombstones are excluded unless `{includeDeleted: true}`.
+
+### Filtered, sorted, and paged list args
+
+RTK list args map to the same syntax. Pick the hook by collection size:
+
+| RTK | Whole collection synced (`collections`) | Too large to sync whole (`queryCollections`) |
+|-----|------------------------------------------|----------------------------------------------|
+| `useGetMessagesQuery({threadId})` | `useQuery("messages", {where: {threadId}})` | `useWindowQuery("messages", {where: {threadId}})` |
+| `{status: {$in: ["open", "pending"]}}` | `where: {status: {$in: [...]}}` | same |
+| `{sort: "-created"}` | `sort: "-created"` | same |
+| `{limit: 20}` | `limit: 20` | `pageSize: 20` |
+| `{page: 2}` / load more | grow `limit` | `fetchNextPage()` |
+| `data.more` / `data.total` | — | `hasMore` / `total` |
+| `isLoading` / `isFetching` / `refetch` | not needed | `isLoading` / `isFetching` / `refetch` |
+| `{skip: !threadId}` | not needed | `skip: !threadId` |
+
+```typescript
+import {useWindowQuery} from "@terreno/syncdb/react";
+
+const {data: messages, hasMore, fetchNextPage, isLoading} = useWindowQuery<Message>("messages", {
+  where: {threadId},
+  sort: "-created",
+  pageSize: 30,
+  skip: !threadId,
+});
+```
+
+Windows with different filters keep separate result lists but share one local row per
+document, so an edit to a message shown in two windows updates once. See
+[Query windows](../reference/syncdb.md#query-windows).
 
 ### Delete this RTK read code
 

package/dist/docs/versioned/next/how-to/preview-demo.md

@@ -1,7 +1,11 @@
 # Preview a component demo
 
-Open a component demo and change the shareable query. The preview bar is on demo and
-dev component routes. `?embed=1` applies the same query and hides the bar.
+Open a component demo and change the shareable query. The preview controls sit in the
+navigation header on demo and dev component routes: dropdowns for theme, viewport, and
+background, plus a settings button (sliders icon) that opens a modal for right-to-left,
+reduced motion, locale, and the share query. In windows narrower than 768px every
+preview control moves into that modal; the Dev/Demo mode link stays in the header. `?embed=1` applies the same query and hides
+the controls.
 
 ```text
 /demo/Button?theme=dark&viewport=375&background=inverse&locale=en-US&rtl=1&reducedMotion=1
@@ -16,4 +20,4 @@ dev component routes. `?embed=1` applies the same query and hides the bar.
 | `rtl` | `1` sets document direction to `rtl` on web |
 | `reducedMotion` | `1` sets `data-reduced-motion="1"` on the document element |
 
-Reload keeps the query. The bar shows the current query when any value is not the default. Choosing a control's default removes that key from the URL. Leaving the component route restores the app theme and, on web, document direction and reduced motion. Custom palettes stay on `/palette`.
+Reload keeps the query. The settings modal shows the current query when any value is not the default. Choosing a control's default removes that key from the URL. Leaving the component route restores the app theme and, on web, document direction and reduced motion. Custom palettes stay on `/palette`.

package/dist/docs/versioned/next/how-to/run-harness-on-multiple-instances.md

@@ -0,0 +1,93 @@
+# Run the harness on multiple instances
+
+Run durable harness tasks on every instance of a scaled-out backend (for example several
+Cloud Run instances). Swap the default `InProcessRunner`, where one process drains every
+task, for `JobsRunner`, which runs each phase as a `@terreno/jobs` job. API:
+[AI harness reference → JobsRunner](../reference/ai-harness.md#jobsrunner). Why it is safe:
+[Durable agent harness → Runners](../explanation/durable-agent-harness.md#runners).
+
+You need a working harness (see [Build a durable workflow](build-a-durable-workflow.md)) and
+a MongoDB replica set. Task data does not change, so you can switch runners without a
+migration.
+
+## 1. Install the jobs package (1 minute)
+
+`@terreno/jobs` is an optional peer of `@terreno/ai`. Add it to the app:
+
+```bash
+bun add @terreno/jobs
+```
+
+## 2. Open the harness with a JobsRunner (5 minutes)
+
+Create the `JobsApp` first, hand it to the runner, and register it on the app. Build the
+app before the harness starts: `harness.start()` throws when no `JobsApp` is registered.
+The runner defines the `terreno.harness.phase` job on it.
+
+```typescript
+import {Harness} from "@terreno/ai/harness";
+import {JobsRunner} from "@terreno/ai/harness/jobsRunner";
+import {TerrenoApp} from "@terreno/api";
+import {JobsApp} from "@terreno/jobs";
+
+const jobs = new JobsApp();
+const harness = await Harness.open({
+  registry: [intakeSummary, summarizer],
+  runner: new JobsRunner({jobs}),
+});
+
+const app = new TerrenoApp({userModel: User}).register(jobs);
+// ...register HarnessApp and your routes, then build or start the server.
+app.start();
+
+await harness.start();
+await jobs.startWorker();
+```
+
+Shut down in the reverse order so phases in flight finish:
+
+```typescript
+await harness.stop(); // stops dispatching, waits for this instance's phases
+await jobs.stopWorker();
+```
+
+## 3. Run the same code on every instance
+
+Every instance runs the same startup. Each one:
+
+- scans for runnable tasks and enqueues one job per runnable phase (duplicates collapse on
+  the job's idempotency key),
+- runs phase jobs from the shared jobs queue, and
+- sweeps task leases that expired because an instance died.
+
+No instance is special, and none waits on standby.
+
+## 4. Check it works (2 minutes)
+
+1. Start two backend processes against the same database (different `PORT`s).
+2. Create a task (for the example backend, run `startClinicalIntake`).
+3. Open the admin **Jobs** screen. Each phase shows as its own `terreno.harness.phase` job
+   with payload `{taskId}`.
+4. Kill one process mid-phase. Within one lease (`leaseDuration`, default 30 s) the other
+   process replays a `replay: "safe"` phase, or parks any other phase as `interrupted`.
+
+## Tune it
+
+| Want | Set |
+| --- | --- |
+| Faster pickup of new work | `new JobsRunner({jobs, pollInterval: {milliseconds: 200}})` and `new JobsApp({pollIntervalMs: 200})` |
+| Faster crash recovery | A shorter `leaseDuration` with `heartbeatInterval` about a third of it |
+| Phases longer than the jobs lock TTL | Nothing: the task lease, renewed by heartbeats, decides who commits |
+
+## Troubleshoot
+
+- **Jobs fail with `harness-runner-stopped`.** A jobs worker runs on an instance whose
+  harness is not started. Start the harness before `jobs.startWorker()`. The jobs worker
+  retries the job, so no task is lost.
+- **`harness.start()` throws "JobsRunner needs a registered JobsApp".** The dispatcher
+  enqueues through the registered jobs service, and `TerrenoApp` registers plugins when it
+  builds. Call `app.start()` (or `build()`) before `harness.start()`.
+- **A task stays `pending`.** Check that its `name@version` is in the registry of the
+  running instances. A runner only dispatches registered versions.
+- **Pick one runner per database.** Mixing them is safe (every claim and commit is fenced),
+  but an `InProcessRunner` owner then claims tasks itself and runs them to a stop.

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

@@ -140,7 +140,7 @@ On resume, a task whose status is `running` with an expired lease was interrupte
 | Runner | Ownership | Use |
 |---|---|---|
 | `InProcessRunner` (default) | One process holds the `HarnessOwner` lease (heartbeat). A second process gets `standby` and takes over on lease expiry. Polls runnable tasks; wakes on `runAt` and events. | Local agents, single-instance apps, tests |
-| `JobsRunner` (`@terreno/ai/harness/jobsRunner`, optional peer `@terreno/jobs`) | Each runnable phase → job `terreno.harness.phase`, idempotency key `taskId:phase:attempt`. Handler acquires the task lease (fenced, heartbeat) and runs one phase. The task lease, not the job lock, is the authority. | Multi-instance Cloud Run |
+| `JobsRunner` (`@terreno/ai/harness/jobsRunner`, optional peer `@terreno/jobs`) | Each runnable phase → job `terreno.harness.phase`, idempotency key `taskId:phase:attempt:claims` (`claims` counts claims, so a phase revisited by an event wake or crash replay gets a new job; jobs idempotency keys are permanent). Handler acquires the task lease (fenced, heartbeat) and runs one phase. The task lease, not the job lock, is the authority. | Multi-instance Cloud Run |
 
 ### Ownership tree