@smthrs/gateway 0.35.0 → 1.0.0-rc.3

package/docs/installation.md

@@ -0,0 +1,89 @@
+---
+title: "Installation"
+description: "Install @smthrs/gateway, know which Node version it needs, which import forms are public, and which four services a host must supply before the mounts can serve."
+sidebar:
+  order: 1
+---
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/docs/installation.md#install-the-cli).
+
+## Requirements
+
+- Node.js 26.4.0 or later. The Node host uses `node:http` and
+  `@effect/platform-node`, so it does not run in a browser or in a Worker.
+- One copy of `effect` in the resolved tree. A second copy makes a `Layer`
+  built against one fail to satisfy a requirement declared against the other.
+
+`effect` is the only peer, pinned to `4.0.0-rc.115`. Node and Bun adapters
+are bundled privately at the same version, including their shared implementation.
+Hosts need no separate adapter install:
+
+```bash
+pnpm add effect@4.0.0-rc.115
+```
+
+Use `@smthrs/gateway/node/NodeGateway` on Node or
+`@smthrs/gateway/bun/BunGateway` on Bun. The root and protocol subpaths need
+neither native adapter at runtime.
+
+Runtime dependencies install with the package, including
+[`@smthrs/control`](/api/control) and [`@smthrs/sync`](/api/smithers-sync).
+You do not name them separately to compile against this package's API.
+The guides that compose a full host or a test stack say which additional
+packages they import.
+
+## Import forms
+
+The root entry point exports one namespace per module:
+
+```ts
+import { Diagnosis, GatewayError, GatewayProjection, GatewaySchema, GatewayServer, Projections } from "@smthrs/gateway"
+```
+
+Every local module is also importable on its own path, which is what a host
+that only needs one of them should use:
+
+```ts
+import * as GatewayServer from "@smthrs/gateway/GatewayServer"
+import * as NodeGateway from "@smthrs/gateway/node/NodeGateway"
+```
+
+`@smthrs/gateway/package.json` is exported. `@smthrs/gateway/internal/*` and
+nested `@smthrs/gateway/<Module>/index` subpaths are not public and resolve to
+nothing.
+
+The root entry also re-exports `@smthrs/sync` whole as `Sync`, so a host that
+mounts the journal read path does not add a second import:
+
+```ts
+import { Sync } from "@smthrs/gateway"
+
+const server = Sync.SyncServer.layer
+```
+
+## What a host supplies
+
+`NodeGateway.layer` builds the socket, the newline-delimited JSON
+serialization, and the shared-credential authentication. Four services stay the
+caller's, because only a project on disk can provide them:
+
+| Service                       | Comes from                                 | Serves                |
+| ----------------------------- | ------------------------------------------ | --------------------- |
+| `Control` (`@smthrs/control`) | `ControlLive.layer` over a control runtime | `/rpc`, `/rpc/ws`     |
+| `Projections` (this package)  | `Projections.layer`, over that `Control`   | `/projections`        |
+| `SyncServer` (`@smthrs/sync`) | `SyncServer.layer` over a journal          | `/sync`               |
+| `SyncAuth` (`@smthrs/sync`)   | `SyncAuth.layer`                           | `/sync` authorization |
+
+`Projections.layer` reads through the ambient `Control`, so a host that
+composes both gets one control plane rather than two views of one database.
+The full composition, with the storage underneath it, is in
+[Host the gateway in your own process](./guides/host-the-gateway.md).
+
+## Running without composing anything
+
+[`smthrs serve`](/cli/serve) hosts this exact assembly for a project on disk.
+If you want a gateway rather than a library, use the CLI instead. Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/docs/installation.md#install-the-cli).
+
+Then see the [Quickstart](./quickstart.md).

package/docs/quickstart.md

@@ -0,0 +1,200 @@
+---
+title: "Quickstart"
+description: "Serve a workspace gateway on loopback, prove which workspace it belongs to, read a projection snapshot off the wire, and follow one run live."
+sidebar:
+  order: 2
+---
+
+This quickstart brings a real gateway up over a real project and reads it the
+way a client outside the process reads it: over HTTP, off the wire, with no
+library on the other end.
+
+By the end you will have probed `/health`, read a `workspace-runs` snapshot as
+newline-delimited JSON, and followed one run's summary until it settled.
+
+## Before you start
+
+- The `smthrs` executable, installed as described in
+  [Installation](./installation.md).
+- A project with at least one run. If you have none,
+  [the CLI quickstart](/pkg/cli/quickstart) takes an empty directory to a
+  settled run in six commands.
+- `curl` and `jq`, and Node 26.4.0 or later for the last step.
+
+## Serve the workspace
+
+From the project root:
+
+```bash
+smthrs serve
+```
+
+```text
+smthrs serve listening on http://127.0.0.1:3000
+  /rpc              http://127.0.0.1:3000/rpc              control rpc
+  /rpc/ws           ws://127.0.0.1:3000/rpc/ws             control rpc, including watch
+  /projections      http://127.0.0.1:3000/projections      projection snapshots
+  /projections/ws   ws://127.0.0.1:3000/projections/ws     projection subscriptions
+  /sync             http://127.0.0.1:3000/sync             journal sync
+  /sync/ws          ws://127.0.0.1:3000/sync/ws            journal sync stream
+  /health           http://127.0.0.1:3000/health           workspace identity
+  auth  no bearer (loopback Host; loopback browser Origin)
+```
+
+That is `@smthrs/gateway`'s assembly, bound by `NodeGateway.layer`. The bind is
+loopback, so it needs no credential. It accepts only loopback `Host` values,
+and a browser request that carries `Origin` must name `http` or `https` on
+`localhost`, `127.0.0.1`, or `[::1]`; an Origin-less CLI request remains
+accepted. The server lives exactly as long as the command, so leave it running
+and open a second terminal for everything below.
+
+## Ask which workspace it is
+
+```bash
+curl -s http://127.0.0.1:3000/health | jq
+```
+
+```json
+{
+  "workspaceHash": "8f4b2c1d90a37e56",
+  "gatewayId": "cli-4821",
+  "protocolVersion": "1",
+  "version": "1.0.0-rc.0"
+}
+```
+
+`/health` is the one unauthenticated route, and identity is all it carries: no
+token, no run, no path. A supervisor that finds a process already on this port
+asks it this before deciding to keep or replace it.
+
+## Read the workspace's runs
+
+The read path speaks RPC over newline-delimited JSON. One request is one line:
+a `Request` envelope naming the procedure and carrying its payload.
+
+```bash
+curl -s http://127.0.0.1:3000/projections \
+  -H 'content-type: application/json' \
+  --data-binary '{"_tag":"Request","id":1,"tag":"Projection.Snapshot","payload":{"selector":{"_tag":"workspace-runs"}},"headers":[]}
+'
+```
+
+The answer is one `Exit` line. Pull the snapshot out of it:
+
+```bash
+curl -s http://127.0.0.1:3000/projections \
+  -H 'content-type: application/json' \
+  --data-binary '{"_tag":"Request","id":1,"tag":"Projection.Snapshot","payload":{"selector":{"_tag":"workspace-runs"}},"headers":[]}
+' | head -1 | jq '.exit.value.rows[0]'
+```
+
+```json
+{
+  "runId": "run-1",
+  "flowId": "hello",
+  "status": "completed",
+  "statusRollup": {
+    "subjectId": "run:run-1",
+    "state": "completed",
+    "activity": "unknown",
+    "health": "healthy",
+    "attention": "none",
+    "freshness": "unobserved",
+    "updatedAt": 2000
+  },
+  "createdAt": 1000,
+  "updatedAt": 2000,
+  "seat": "anthropic:claude-sonnet-4-5",
+  "turns": 1,
+  "calls": 1,
+  "callsFailed": 0,
+  "editsAttempted": 1,
+  "editsSucceeded": 1,
+  "inputTokens": 0,
+  "outputTokens": 0,
+  "verdict": "completed \u2014 shipped",
+  "diagnosis": "Verdict   completed \u2014 shipped\nRun       run-1 · hello · anthropic:claude-sonnet-4-5 · 5s\nActivity  1 turns · 1 calls (0 refused) · edits 1/1\nTokens    0 in / 0 out\nOutput    shipped",
+  "finalOutput": "shipped"
+}
+```
+
+Nothing in that row is a database column. Every field is either a
+`@smthrs/control` run-summary value or something folded out of that run's
+ordered control events, which is why the same row reaches a browser through a
+relay unchanged. See [Projections](./concepts/projections.md).
+
+The snapshot also carries the cursor its rows were read at. Keep it: it is what
+makes a follower resume without rewinding.
+
+## Follow one run
+
+Copy a `runId` from the listing, then follow that run's summary over the
+subscription socket. Save this as `follow.mjs`:
+
+```js
+const runId = process.argv[2]
+const socket = new WebSocket("ws://127.0.0.1:3000/projections/ws")
+
+socket.addEventListener("open", () => {
+  socket.send(
+    JSON.stringify({
+      _tag: "Request",
+      id: 1,
+      tag: "Projection.Subscribe",
+      payload: { selector: { _tag: "run-summary", runId } },
+      headers: []
+    }) + "\n"
+  )
+})
+
+// The server answers NDJSON. A stream arrives as Chunk messages whose values
+// are the subscription's own frames.
+socket.addEventListener("message", (event) => {
+  for (const line of String(event.data).split("\n").filter((text) => text !== "")) {
+    const message = JSON.parse(line)
+    if (message._tag !== "Chunk") continue
+    for (const frame of message.values) console.log(frame._tag, frame.cursor?.value ?? "")
+  }
+})
+```
+
+```bash
+node follow.mjs run-1
+```
+
+```text
+snapshot-start 6
+row 6
+snapshot-end 6
+heartbeat
+```
+
+Three snapshot frames, then a keepalive because nothing has changed yet.
+Launch or steer that run from another terminal and `delta` frames arrive, each
+one carrying the selector's rows recomputed at a new cursor. The keepalive is
+not decoration: an idle subscription that sent nothing for 600 seconds would
+be cut by a relay, so the server emits one every 30 seconds.
+
+## What just happened
+
+One process served four mounts on one socket. `/health` answered an identity
+question with no credential. `/projections` answered a fold over the control
+plane's own events, framed exactly the way a relay forwards them to a browser.
+The socket turned that same fold into a snapshot plus a live tail, at a cursor
+a client can resume from.
+
+The control plane was there the whole time, on `/rpc`, under the same
+credential rule. That mount is [`@smthrs/control`](/api/control)'s contract
+unchanged: this package mounts it and adds a keepalive, and re-declares none of
+its procedures.
+
+## Next steps
+
+- [Read a projection over HTTP](./guides/read-a-projection.md): every selector,
+  the row each answers with, and how to decode instead of cast.
+- [Follow a run over a WebSocket](./guides/follow-a-run.md): the frame
+  vocabulary, and resuming from a cursor without a second snapshot.
+- [Host the gateway in your own process](./guides/host-the-gateway.md): the
+  composition behind `smthrs serve`.
+- [Serve beyond loopback](./guides/serve-beyond-loopback.md): the two rules
+  that gate a network bind, and the ingress policy behind them.

package/docs/troubleshooting.md

@@ -0,0 +1,355 @@
+---
+title: "Troubleshooting"
+description: "The refusals a gateway answers with, grouped by where they come from: the bind, the ingress guard, the read path, a subscription, and the data a projection can and cannot see."
+---
+
+Every refusal this package produces is a `GatewayError` carrying one of nine
+stable codes. Find the symptom, then the code, then the change.
+
+## The gateway will not bind
+
+### Refusing non-loopback gateway bind
+
+**Symptom**
+
+```text
+Refusing non-loopback gateway bind 0.0.0.0 without an explicit --listen opt-in
+Refusing non-loopback gateway bind 0.0.0.0 without a bearer credential
+```
+
+**Cause** The bind policy, which fails closed. A host other than `127.0.0.1`,
+`::1`, or `localhost` needs both an explicit `listen` opt-in and a bearer
+credential.
+
+**Fix** Supply both, or bind loopback. See
+[Serve beyond loopback](./guides/serve-beyond-loopback.md).
+
+### A setting must be a positive safe integer
+
+**Symptom**
+
+```text
+The gateway keepalive cadence must be a positive safe integer, not 0
+The gateway request body limit must be a positive safe integer, not -1
+```
+
+**Cause** `heartbeatMillis` or `maxRequestBodyBytes` is zero, negative,
+fractional, or outside the safe-integer range. A cadence of zero turns the
+keepalive into a tight loop and a body limit of zero refuses every request, so
+the composition is refused before it binds rather than after it is serving.
+
+**Fix** Pass a positive integer, or omit the field and take the default: 30,000
+milliseconds and 1,048,576 bytes.
+
+### The gateway socket could not be bound
+
+**Symptom** A `bind_failed` `GatewayError` whose message is
+`The gateway socket could not be bound`.
+
+**Cause** The operating system refused the listen: the port is already in use,
+the address is not local, or the port is privileged.
+
+**Fix** Read the server log. The Node host writes one error-level line before
+it sanitizes the failure: `The gateway socket could not be bound`, with the
+requested `host` and `port` and the `ServeError` whose `cause` is the
+operating-system error (`EADDRINUSE`, `EACCES`, `EADDRNOTAVAIL`). The wire error
+deliberately omits all of that, because it reaches every bearer holder. Then
+check what already holds the port. A gateway already serving this workspace
+answers `GET /health` with the workspace hash, which is how a supervisor decides
+whether to keep it.
+
+## The gateway is up but a request is refused
+
+### 421 invalid_host or 403 invalid_origin on a local gateway
+
+**Symptom** A credential-less loopback gateway answers with `invalid_host`, or
+a browser request or WebSocket upgrade answers with `invalid_origin`.
+
+**Cause** Local mode accepts `Host` values naming only `localhost`,
+`127.0.0.1`, or `[::1]`, with an optional port. If an `Origin` header is
+present, it must be a canonical `http` or `https` origin whose host and port
+equal the request's `Host`, in every mode. An app on `http://localhost:5173`
+calling a gateway on `localhost:3000` is refused. This prevents a web page or
+DNS-rebound hostname from acting as the local operator.
+
+**Fix** Connect through the loopback URL the server printed. Serve the browser
+client from that same origin, or put it behind a dev-server proxy that
+forwards to the gateway so the browser only ever talks to one origin. CLI
+clients should omit `Origin`, as usual; an Origin-less request is accepted.
+
+### 401 on /projections or /sync, but /rpc answers something else
+
+**Symptom** `POST /projections`, or any protected socket upgrade, answers HTTP
+401 with this body, while `POST /rpc` with the same missing credential answers
+HTTP 200 carrying a `/control/Unauthorized` in the RPC frame.
+
+```json
+{
+  "_tag": "@smthrs/gateway/GatewayError",
+  "code": "unauthorized",
+  "message": "A valid bearer credential is required"
+}
+```
+
+**Cause** Not a bug. `/rpc` authenticates in band so that a caller sees the
+control plane's own typed refusal, exactly as it would against a control server
+hosting the same procedures. Every other RPC path is checked at the edge,
+because a socket cannot be refused after it is open.
+
+**Fix** Send `Authorization: Bearer <token>` on both. Handle the two shapes:
+`@smthrs/control` `ControlError.Unauthorized` from `/rpc`, and a `GatewayError`
+body under a 401 from the rest. The reasoning is in
+[the trust boundary](./concepts/trust-boundary.md#edge-authentication-and-where-it-deliberately-stops).
+
+### 400 malformed_request: carries no RPC request message
+
+**Symptom**
+
+```json
+{
+  "_tag": "@smthrs/gateway/GatewayError",
+  "code": "malformed_request",
+  "message": "POST /projections carries no RPC request message"
+}
+```
+
+**Cause** The body decoded to something that is not a tagged RPC message:
+`{}`, `[]`, prose, or nothing at all.
+
+**Fix** Send the framed envelope, one JSON object per line:
+
+```text
+{"_tag":"Request","id":1,"tag":"Projection.Snapshot","payload":{"selector":{"_tag":"workspace-runs"}},"headers":[]}
+```
+
+A body naming a procedure that does not exist is _not_ this error. It reaches
+the mount and the RPC protocol reports the defect itself.
+
+### 413 request_too_large
+
+**Symptom** `POST /rpc exceeds the 1048576-byte request limit`.
+
+**Cause** The body is over `maxRequestBodyBytes`, or its declared
+`content-length` is.
+
+**Fix** Send less, or raise the limit at the bind. A declared length over the
+limit is refused without reading the body, so a client that lies low in
+`content-length` is still measured as the body is read. A streaming body has no
+declared size; when it crosses the limit, the Node host destroys the source
+rather than draining attacker-controlled bytes, so the client may observe a
+connection reset instead of the 413 response.
+
+### 400 malformed_request: a body the server could not read
+
+**Symptom** `POST /rpc carries a body the server could not read`.
+
+**Cause** The read failed for a reason that is not size: a truncated body, a
+reset transport. This is deliberately not 413, because the request cannot be
+retried smaller.
+
+**Fix** Retry the request. If it repeats, look at the client's framing and at
+whatever sits between it and the gateway.
+
+### 404 on a path that looks like a mount
+
+**Symptom** `/rpc%2f`, `/%2frpc`, `/rpc%3Bp`, and `/rpc%20` answer 404.
+
+**Cause** A reserved character left percent-encoded is not a separator, to the
+router or to the ingress guard. Those spellings name no mount, exactly as they
+name none to `HttpRouter`.
+
+**Fix** Post to `/rpc`. Aliases the router does resolve, including `/rpc/`,
+`//rpc`, `/RPC`, and `/rpc;p`, are recognized by the guard too, so they are
+authenticated and size-limited rather than slipping past.
+
+## A read is refused
+
+### run_not_found for a run you can see
+
+**Symptom** Every run-scoped selector answers
+`{ "code": "run_not_found", "message": "No run <id>" }`.
+
+**Cause** The control plane does not list that run. The gateway never opens the
+engine database, so a run that exists only there is invisible here. Event reads
+alone cannot distinguish an unknown run from an empty run, so the gateway checks
+existence through `Control.list`. An existing run with no events projects successfully.
+
+**Fix** Confirm the run with `Control.list`, or [`smthrs runs list`](/cli/runs). If the
+run is in the engine database but not the control plane, the launch never
+reached the control plane and the gateway is reporting that correctly.
+
+### resource_limit
+
+**Symptom** A `resource_limit` `GatewayError` on a snapshot or a delta.
+
+**Cause: retained state** A run projection keeps a window of at most 10,000
+events and 4 MiB of retained events plus digest identity state. Older events
+enter a carried digest. Large retained events are clipped to 16 KiB. The read
+fails if the digest's exact identity state cannot fit the 4 MiB budget.
+
+**Cause: oversized graph event** A native `flows.engine.plan-recorded` or
+`flows.engine.subgraph-appended` event exceeds 16 KiB. These events are refused
+instead of clipped, including on `run-events` pages, so graph topology stays
+intact.
+
+**Fix** Inspect raw history through `run-events` snapshots. Each page returns
+at most 1,000 events and 4 MiB, plus a cursor; pass that cursor as `after` until
+a page is empty. Other large events are clipped, while admitted native
+`control.engine.event` payloads remain complete. One event too large for a
+4 MiB page fails with `resource_limit`. Inspect an oversized graph event with
+a bounded `Control.watch` read and keep future graph events within 16 KiB.
+
+**Cause: projected rows** The encoded projected row set exceeds 4 MiB.
+
+**Fix** Narrow the selector to reduce the projected row set, for example
+`node-output` for one node or `run-summary`. This only helps if the selected
+rows fit within the row budget.
+
+A `resource_limit` refusal returns no rows. A successful `run-events` page is a
+bounded part of the history; use its cursor to continue.
+
+### run_unavailable with a cause that says almost nothing
+
+**Symptom**
+
+```json
+{
+  "code": "run_unavailable",
+  "message": "Listing runs failed",
+  "cause": { "_tag": "/control/Unavailable", "code": "unavailable" }
+}
+```
+
+**Cause** A control-plane read failed. The cause carries only the failure's tag
+and stable code.
+
+**Fix** Use the projection log operation identifier and known control error
+tag/code to locate the failing backend operation. Projection logs omit backend
+messages and nested causes, including SQL, credentials, and file paths.
+
+## A subscription misbehaves
+
+### malformed_request when resuming from a cursor
+
+**Symptom** One of:
+
+```text
+A cursor for the run-tree projection cannot resume a run-summary subscription
+A cursor can resume only the exact selector that issued it
+A cursor for run run-2 cannot resume a subscription to run run-1
+A workspace-runs subscription has no resumable cursor, because control journal sequences belong to per-run partitions
+Cursor 12:0 was not issued by run run-1
+Cursor 99:0 cannot resume run run-1 past its last position 12:0
+```
+
+**Cause** The cursor does not belong to this subscription, or names a position
+this run never reached.
+
+**Fix** Send back the cursor exactly as it arrived, from the same selector.
+For a workspace projection there is no resume at all: re-subscribe without
+`after` and take the snapshot again.
+
+### The connection drops after a few minutes of quiet
+
+**Symptom** A follower on a quiet run disconnects and reconnects on a cycle,
+with no error from the gateway.
+
+**Cause** Something between the client and the gateway cuts idle connections
+sooner than the keepalive cadence. The default is one frame every 30 seconds,
+sized for a relay that cuts at 600 seconds.
+
+**Fix** Shorten the cadence at the bind with `heartbeatMillis`, which re-times
+both the `/projections/ws` heartbeat and the `/rpc/ws` `Watch` keepalive, or
+build the read path with `Projections.layerWith({ heartbeatMillis })` to
+shorten the projection heartbeat alone.
+
+### A followed Watch delivers events nothing emitted
+
+**Symptom** `/rpc/ws` `Watch` frames arrive with kind
+`control.gateway.heartbeat` and a `null` payload, repeating the last sequence.
+
+**Cause** That is the gateway's keepalive. `ControlRpcs.Watch` answers
+`ControlEvent` and has no frame of its own for one, so the keepalive is
+published as an event whose kind no emitter uses.
+
+**Fix** Ignore the kind, as every fold in this package does with an unknown
+kind. It repeats the last delivered sequence on purpose, so resuming from the
+last sequence you saw does not rewind.
+
+## A projection is missing something you expected
+
+### The run tree has no nodes, though the run did work
+
+**Cause** `run-tree` folds agent cell calls, from
+`control.agent.cell-call-started` and `control.agent.cell-call-settled`. The
+durable engine's own `flows.engine.*` records live in a different database with
+a different journal, and `Control.watch` reads one run's partition of the
+control journal alone.
+
+**Fix** Nothing to change here. What an engine step did reaches a client as the
+agent call that made it. A run driven by an executor that journals no agent
+events has no tree, correctly.
+
+### The approvals inbox is empty though a run is waiting
+
+**Cause** The unscoped `approvals` selector asks the control plane for runs
+whose status is `waiting-approval` and then keeps only those with a pending
+gate. A run parked for another reason, or one whose gate was already decided,
+is not in the inbox.
+
+**Fix** Use the run-scoped form, `{ _tag: "approvals", runId }`, which lists
+that run's gates including the decided ones. That is what a run card renders.
+
+A human wait held by a NESTED execution is no longer one of these cases. A
+flow that calls another flow parks the child, so a `HumanTask` several
+`.child()` boundaries down used to leave the run an operator opened reading
+`waiting · event` with an empty inbox, the shape run-3 of `coding/request`
+parked in, on a gate named `coding-clarification`. The control plane now rolls
+a run tree's open human waits onto the root as
+`ControlSchema.RunSummary.pendingWaits` and rolls its status up with them, and
+the projection turns each into a pending row of that root. A run still showing
+an empty inbox is waiting on a timer, an event, or a quota, and its
+`waitingReason` says which.
+
+### A question in the inbox cannot be answered
+
+**Cause** A `HumanTask` gate asks for a value, and `decision: "approve"` alone
+carries none. The run stays parked on the wait it opened.
+
+**Fix** Submit the value in `Approval.Submit`'s `answer`, shaped for the
+`kind` the row's `request` declares. The mount routes it to `Control.signal`
+addressed to the row's `runId` and naming its `requestId`, and the control
+plane resolves the wait wherever in the tree it is held. `smthrs runs signal <root
+run> '{"name":"<the question>","payload":…}'` is the same act from a terminal.
+
+### The workspace listing stops at 500 runs
+
+**Cause** `Projections.maxWorkspaceRuns` is 500, matching
+`ControlSchema.maxPageSize` so the control plane can answer the whole allowance
+in one page.
+
+**Fix** Read the runs you care about individually with `run-summary`. There is
+no paging on the workspace projection: a workspace with more runs is answered
+with its newest 500, and a newly created run displaces the oldest one.
+
+## Recovery
+
+### An abandoned run is never resumed
+
+**Cause** The gateway does not supervise runs, so nothing it serves discovers
+or resumes a run whose owner died.
+
+**Fix** Recovery is a reclaim rather than a supervisor. A run becomes
+reclaimable once the heartbeat its owner stopped renewing is older than 30
+seconds, and any running process with the flow registered takes it over. Bring
+up a host composition running the durable engine driver with the relevant flows
+registered, or recover the run explicitly.
+
+### /health answers but every projection fails
+
+**Cause** Startup is deliberately not blocked by a subsystem that failed to
+recover. A gateway whose read path cannot read still comes up, because a
+supervisor still has to be able to ask which workspace this process is.
+
+**Fix** Read the server log for the read path's own failure. The identity
+answer is correct and is not evidence that the rest is healthy.