@oar-sh/oar 0.9.12 → 0.9.14

package/server/README.md

@@ -216,7 +216,8 @@ reports both the actual suspend and such a drop. For the first 45 seconds after
 a relay start the check lists one more blocker, "the relay just started,
 sessions are still reporting": the workers that outlived the previous runtime
 may not have reported their background work yet. A queued **🌄 Restart web relay**
-gets the same banner and can be cancelled from it too.
+gets a banner of its own, with the sessions it waits for, **Restart now** and
+**Cancel restart** (see [Manual relay shutdown / self-restart](#manual-relay-shutdown--self-restart)).
 
 API: `GET /api/host/suspend` (state plus current blockers), `POST /api/host/suspend`,
 `POST /api/host/suspend/cancel`, and `POST /api/relay/shutdown/cancel`
@@ -254,21 +255,68 @@ Behavior notes:
 - In extension-managed mode, the relay still switches model per message and
   reports the active model used in the response.
 
-### OpenAI API key
+### A message without a model, an effort or a mode
+
+The composer always sends all three. A client that leaves one out of
+`POST /api/message` (a script, an agent on this relay) gets the conversation's
+own, never the relay-wide default:
+
+- **Model**, for an existing Copilot conversation: the conversation's saved
+  `preferred_model`, then the runtime session's `provider_model`, then its
+  `model`, then the model of the latest user message (`auto` skipped in each);
+  only a conversation with none of these runs on the catalog's current model.
+  A saved model the catalog no longer lists is refused with
+  `409 CONVERSATION_MODEL_UNAVAILABLE` (`model`, `supportedModels`) instead of
+  being replaced; the composer shows that text in its banner. An explicit
+  `auto` is unchanged (new conversations only). Claude, Cursor, Grok, Claude
+  Cloud and OpenAI conversations keep their pinned `provider_model`, as before.
+- **Effort**: for Copilot, an effort the model's variant id carries, else the
+  conversation's `preferred_reasoning_effort`, clamped to the nearest level the
+  model offers (`nearestSupportedReasoningEffort`, the composer's rule); with
+  nothing to keep, the model's lowest level that is not `none`, so `none` is
+  chosen only when the conversation asked for it or the model has no other
+  level. OpenAI, Claude, Cursor and Grok conversations take the conversation's
+  effort the same way; with no effort stored, or one that neither matches nor
+  clamps (an `ultracode` on a model without it), they keep the provider's own
+  default as before (`none`, `low` for an OpenAI o-series model; for Claude,
+  Cursor and Grok `none` means the model's default). A Claude Cloud conversation always runs with `none`: the
+  cloud takes no effort. A board action's follow-up takes the conversation's
+  effort as well.
+- **Mode**: a send that names no `relayMode`/`mode` runs in the
+  conversation's saved `preferred_relay_mode`, not the relay default.
+- **Preferences**: a send to an existing conversation saves only what it named.
+  A model it named is saved (with its effort only when that was named too, else
+  the stored effort stays); an effort alone is saved against the stored model,
+  and a conversation with no saved model runs with that effort but saves
+  nothing; a send that named neither writes nothing. The mode saved with them
+  is the one the turn runs in, so a send without a mode leaves the stored mode
+  as it is. A send from another relay's agent never writes them, as before.
+
+A text repeat inside the duplicate window answers `200` with `duplicate: true`
+and `queued: false`, and nothing runs. A message whose turn **failed** no
+longer counts: sending it again queues it.
 
-Open **Settings → OpenAI API key** to save an OpenAI key and exact model ID
-(`gpt-4o` by default). Use the provider toggle to switch new conversations
-between OpenAI and GitHub Copilot without re-entering the saved key. While
-enabled, newly created extension-managed conversation workers start with Copilot
-CLI BYOK environment variables pointing to `https://api.openai.com/v1`.
-Zero-message conversations follow provider changes; started conversations keep
-their original provider and lock the composer to their assigned model.
+### OpenAI API key
 
-GPT-5 and OpenAI reasoning-model sessions use the Responses API automatically;
-other OpenAI models retain the broader-compatible Chat Completions wire format.
-OpenAI BYOK sessions currently use reasoning effort `none`; GitHub Copilot
-reasoning choices remain separate even when both providers expose the same model
-ID.
+Open **Settings → Providers → OpenAI** to save an OpenAI API key, the default model ID (`gpt-4o`
+if none) and an optional **Base URL** (`https://api.openai.com/v1` when empty; any
+OpenAI-compatible endpoint, or the capture proxy `server/tools/capture-proxy.mjs`). **Enable OpenAI
+API key for New Chat model selection** makes OpenAI selectable in New Chat without re-entering the
+key. An OpenAI conversation runs on the Copilot engine the relay has selected, extension or SDK:
+the worker is started with `COPILOT_PROVIDER_TYPE=openai`, `COPILOT_PROVIDER_BASE_URL` (the saved
+base URL), `COPILOT_PROVIDER_API_KEY`, `COPILOT_PROVIDER_WIRE_API` and `COPILOT_MODEL`
+(`applyOpenAIProviderEnvironment`); the CLI reads them on the extension engine, the SDK worker
+turns them into the session's provider (`copilot-worker/copilot-byok-provider.mjs`). Started
+conversations keep their provider and lock the composer to their model.
+
+GPT-5, `codex-*` and the o1/o3/o4 models use the Responses API; other OpenAI models use Chat
+Completions (`resolveOpenAIWireApi`). The reasoning efforts follow the model family
+(`shared/openai-reasoning.mjs`): GPT-5 and `codex` offer `none`, `low`, `medium`, `high` and
+`xhigh`, the o-series `low`, `medium` and `high`, other models only `none` (image models take
+`auto`, `low`, `medium` and `high` as their quality). An effort the model does not offer is refused
+with `400`; with none named the conversation's own applies (clamped to the model's levels), else
+`none`, or `low` on a model without `none`. GitHub Copilot's reasoning choices stay separate even when both providers list the
+same model ID.
 
 Saving or re-enabling the key refreshes OpenAI's `/v1/models` list and adds
 candidate OpenAI model IDs to the composer picker. The Settings model-variant
@@ -280,11 +328,13 @@ the Settings model is only the default. Starting a chat from a locked OpenAI
 conversation opens an independent model chooser without changing the active
 conversation.
 
-Disabling OpenAI retains the key and cached model list. Removing the key is a
-separate destructive action and makes subsequent conversations use GitHub
-Copilot.
-An existing OpenAI-assigned conversation can continue while its worker remains
-running, but cannot launch a replacement worker until an OpenAI key is configured.
+Disabling OpenAI retains the key and cached model list. **Remove saved key** deletes the key and the
+cached list and switches OpenAI off, and it is refused with `409 openai-key-removal-blocked`
+(`activeConversationCount`, `startedConversationCount`, `activeQueueConversationCount`) while any
+OpenAI conversation that is not deleted, image conversations and archived ones included, has a
+message or a pending, processing or parked queue row (`setOpenAIProviderSettings` in
+`server-runtime.mjs`). Disable OpenAI instead, or delete those conversations first. A removal that
+goes through moves the OpenAI conversations without a message to GitHub Copilot.
 
 ### Claude models
 
@@ -375,10 +425,14 @@ cached in the worker after the server accepts it, so a failed persist is retried
 The worker keeps one persistent CLI process per conversation, so background tasks survive the reply
 that started them. The live task set is posted to `POST /api/background-tasks` (REPLACE semantics)
 and broadcast as the `background_tasks` socket event; the composer's task panel renders it and can
-stop an individual task over a `worker.control` push.
+stop an individual task over a `worker.control` push. The conversation payload carries the set too
+(`backgroundTasks`, `endedBackgroundTasks`); the page's live poll and refresh leave it out when a
+`background_tasks` event for the conversation arrived while their request was on its way, as the
+event's set is at least as new.
 
 The relay holds the task sets in memory (`services/background-task-store.mjs`), so a relay restart
-starts without them while the workers and their tasks keep running. The worker is the source of
+starts without them while the workers and their tasks keep running (the console rows are stored;
+see below). The worker is the source of
 truth, and the relay asks:
 
 - **Digest and resync.** A worker's heartbeat carries `backgroundTasks: { count, digest }`, a digest
@@ -407,6 +461,43 @@ truth, and the relay asks:
 - **Ends.** The Claude worker keeps a settle notice whose post failed (the newest 20, for 10
   minutes) and sends it again after the next heartbeat the relay answers; such a post is given up
   after 10 s without an answer.
+- **The console rows.** What the task console needs of a shell or Monitor task (its `outputPath`
+  and `outputKind`, the ended row with status, exit code and `endedAt`, how a task ended when the
+  settle came before the set dropped it) is kept in `background_task_rows` (migration 0018,
+  `services/background-task-persistence.mjs`), written only when that part of a set changes, not on
+  every progress post. At boot the store restores the ended rows still inside their hour, and holds
+  the live ones (`restored`): the output route and the console's live room find a held task (the
+  route answers it with `status: 'held'`, `held: true` and `stoppable: false`; the console says it
+  waits for its worker), but `get()` and with it the panel, the session state and the suspend check
+  do not count it as running, and the stop route only pushes the stop to the worker. The worker's next set settles it (a task in the set is live again, with the
+  path it had; one not in it becomes an ended row, with the status the runtime before was told), a
+  settle sent again for it ends it, and while a key has held tasks its heartbeat digest never
+  counts as in step, so the relay asks for the set. Tasks of a worker that sends no set within twice
+  the boot reporting window (at least 15 s; 90 s by default) are ended with status `unknown` and the
+  pages get the `background_tasks` event (`endUnconfirmed`); a later set that lists one brings it
+  back. A held task's end time is when the runtime before last knew it running: a stored live row's
+  `updated_at` is written with the set and confirmed at most every 30 minutes while the worker's
+  digest agrees, and a live row not confirmed for 6 hours (a worker that went away in an earlier
+  runtime without an empty set) is deleted at boot instead of restored. Health readings are not
+  stored: the poller reads the files again within 10 s, the ended rows once. A runner's counts come
+  from the last 64 KB when its closing summary is there. A live log that outgrew that window is read
+  whole by a per-task runner scan (`services/task-output-service.mjs`): it looks for a runner's
+  header (a test run after a long install or build prints its header once) and counts from there,
+  reads on from where it stopped as the file grows, and starts over on a new file under the path
+  (shorter, another inode, an older mtime). The scans live in memory and share 4 MB per tick, each
+  tick starting at another task, so after a restart a long log is caught up over a few ticks (the
+  window's reading stands until then) and one busy log cannot keep the others waiting. An ended row
+  never starts a scan, so the rows a restart brings back are read in their window only. What a
+  worker says about a task (description, summary, last tool call, and a shell row's `command`, which
+  the Claude worker takes from the Bash or Monitor call that started the task, Copilot from the
+  shell tool's arguments or the task registry, Grok from the terminal) goes through `cleanTaskText`
+  on the publish and settle routes: control codes and colours out, credentials scrubbed as in the
+  output, then cut (a command at 2,000 characters; a Grok description is its command line). It is
+  stored with the console rows, so a held or ended row keeps it; share links carry no task rows. The
+  `none` answers of the output route use the page's texts (`TASK_OUTPUT_NONE_MESSAGES` in
+  `public/app/task-console-render.mjs`). Rows go with their hour, the 20-per-key limit, a set that
+  drops them or the conversation's delete. Without the table (a failed migration) the store works in
+  memory as before.
 - **Run rows left `running`.** A background sub-agent's row whose end was never written would count
   as running work for a day. For a Claude worker that has reported its task set in this runtime, a
   `running` background row that the set does not list and that nothing has updated for 15 minutes
@@ -458,12 +549,20 @@ runs in the background, and who writes its timeline.
   outlives the turn that spawned it, so its frames arrive between turns and during later turns;
   they go to its own record, never to a later turn's live lanes. A background launch's receipt
   (`tool_use_result.status: 'async_launched'`) leaves the run running; its `task_notification`
-  ends it. Spawns carry `timelineOwner: 'worker'`.
+  ends it. Spawns carry `timelineOwner: 'worker'`. A finished background agent that the session
+  sends a new message (SendMessage) runs again as the same task: `task_started` names its task id
+  again, with a new `run_id` and the SendMessage call as `tool_use_id`. The recorder leads that id
+  back to the agent's first run, so the record goes on under the same run (a note marks where it
+  resumed, and the run reads `running` again until its next `task_notification`); the task panel
+  row, the settle notice and a targeted stop name that run too. Every timeline post also names the
+  run's `taskId`, for a worker that did not see the first run (see the route below).
 - **Copilot and Cursor** publish their sub-agents on the live lanes only (`/api/activity`,
   `/api/thought`, `/api/stream` with a `subagentRunId`); the relay copies each frame into the run's
   timeline, uncut. Fields they do not report (model, tokens) stay blank.
 - `POST /api/background-tasks` copies model, type, task id and tokens onto the run whose id is the
-  task's `toolUseId`, so the row keeps them after the in-memory task set is cleared.
+  task's `toolUseId`, so the row keeps them after the in-memory task set is cleared. A sub-agent
+  task whose `toolUseId` is no run (a resumed agent from a worker that did not see its first run)
+  gets the id of the conversation's run that carries its task id, so the row opens that record.
 - Every `subagent_status` event carries the whole header and the run's own turn (`messageId`). A
   turn that fails closes its foreground runs; background runs are closed by their worker, or by the
   relay when the worker dies.
@@ -621,13 +720,15 @@ transaction as the conversation. Nothing is created at Anthropic here. `POST /ap
 `providerType: 'claude-cloud'` on a conversation of another provider is `409
 CLAUDE_CLOUD_REQUIRES_NEW_CONVERSATION`.
 
-`POST /api/message` accepts another model of the list until the first message has created the
-cloud session, and stores it on the runtime session; after that a different model is `409
-CLAUDE_CLOUD_MODEL_REQUIRES_NEW_CONVERSATION`. The worker, however, creates the session with the
-model it was launched with: `resolveModel` prefers `CLAUDE_CLOUD_RELAY_MODEL` over the delivered
-`providerModel`, so a change made after the worker started only takes effect if the worker is
-launched again before the first message. Reasoning effort is always `none` and the context tier
-always `default`, whatever the request says.
+`POST /api/message` accepts any model of the list, before and after the first message, and stores
+it on the runtime session; a model outside the list is `400 CLAUDE_CLOUD_MODEL_UNAVAILABLE`. The
+delivery carries the conversation's model as `providerModel`, which the worker's `resolveModel`
+prefers over the message's own model and over `CLAUDE_CLOUD_RELAY_MODEL` (the launch model). The
+first message creates the session with it; before a later message whose model is not the one the
+worker last gave the sandbox, the worker sends a `set_model` control request (`applyModel`; after a
+worker restart once, since it cannot know). A `set_model` the API refuses costs the switch, not the
+turn. Reasoning effort is always `none` and the context tier always `default`, whatever the request
+says.
 
 ### Delivery, binding and resume
 
@@ -701,8 +802,10 @@ Per-turn behavior:
   as a terminal error result even though the API key is still valid, so the worker recreates the
   handle and retries a single time; a second auth failure is treated as a real key problem.
 - **Session root** — the worker keeps its per-session agent store at
-  `$CURSOR_AGENT_STORE_DIR` or `server/data/cursor-agents/<sdkSessionId>`, created on the first turn.
-  The explorer's Session root resolves to it via `resolveCursorSessionRoot`.
+  `$CURSOR_AGENT_STORE_DIR/<sdkSessionId>`, else `cursor-agents/<sdkSessionId>` in the relay's data
+  dir (`~/.oar/data` on a global install, `server/data` in a checkout), created on the first turn. A
+  session with a store at the earlier default `server/data/cursor-agents` keeps using it there when
+  it has none in the data dir, or when its `agent.db` there changed last. The explorer's Session root resolves to it via `resolveCursorSessionRoot`.
 - Cursor turns are skipped by `fetchUsageSummary` like OpenAI and Claude turns — no Copilot usage
   line is attached.
 
@@ -717,12 +820,27 @@ carries its own expiry.
    began. A turn that legitimately runs for hours of tool calls keeps pushing the cutoff forward.
    `processing_at` is only the fallback for rows with no owner (session-worker routing disabled).
    While the CLI is offline the window shrinks to 45 s.
-2. **Absolute ceiling (Settings → Max turn duration, default 60 min).** Measured from `processing_at`.
-   `0` disables it; the slider range is 0–600 minutes in 5-minute steps. This is a backstop for a
-   worker that has hung while still heartbeating, and is stored in the DB app setting
-   `turn_ceiling_minutes` — not in `config.json`. Shared bounds and formatting live in
+2. **Absolute ceiling (Settings → Max turn duration, default 60 min).** Measured from the later of
+   `processing_at` and the turn's last answered question (`relay_questions.answered_at`): answering
+   a question restarts the clock, so a long interview is not cut off the moment its last answer
+   arrives. `0` disables it; the slider range is 0–600 minutes in 5-minute steps. This is a
+   backstop for a worker that has hung while still heartbeating, and is stored in the DB app
+   setting `turn_ceiling_minutes` — not in `config.json`. Shared bounds and formatting live in
    `shared/turn-ceiling.mjs`.
 
+Both guards are one SQL rule in `message-repository.mjs`, shared by the listing
+(`listRecoverableProcessing`) and the requeue (`recoverProcessingBefore`, one row at a time,
+re-checking the rule as a safeguard; the sweep runs synchronously, so nothing changes between
+the two). The sweep (`services/stale-turn-recovery.mjs`) applies the retry budget to the listed
+rows, requeues the rest and announces each one it requeued with `message_status`.
+
+The sweep has no provider filter, so Grok rows are requeued by the rule above too. The Grok worker
+also enforces the ceiling itself (delivered with each queue message, `grok-worker/acp-client.mjs`
+`sessionPrompt`): counted from when it sent the prompt, it cancels the turn and fails it as
+`grok.turn-stalled`. That check does not pause for question cards (on Grok: remote-relay approval
+cards through the OAR MCP server), and an answer does not restart its clock. Whichever trips first
+ends the turn.
+
 ## Subagent runs and live streaming
 
 - `POST /api/stream` and `POST /api/activity` / `POST /api/thought` accept an optional
@@ -762,6 +880,9 @@ be on, as for every local action; a paired relay: see [Across paired relays](#ac
   watched. The first subscribe of a conversation shows the user an approval card naming the
   sessions; a subscription to `all` is always named on a card (asked again after an Allow that did
   not cover it). The Allow is remembered as unlock rows `self:watch` / `self:watch-all`.
+  `events: ["relay_restarted"]` alone needs no sessions, watches none and shows no card (see
+  [relay_restarted](#relay_restarted-woken-when-the-relay-runs-again)); on a paired relay it is
+  refused, by the tool and by that relay's subscribe route.
 - `unsubscribe {subscription_id | "all"}`, `list_subscriptions {watcher?}` (another conversation's
   subscriptions, to inspect before a transfer).
 - `transfer_subscriptions {from}` — moves every active subscription of another conversation, with
@@ -773,10 +894,22 @@ be on, as for every local action; a paired relay: see [Across paired relays](#ac
 **Events** (`shared/relay-events.mjs`): `question_asked` (prompt, options, question id; an approval
 card is marked as one only the user can answer), `error` (`turn_failed`, `usage_limit`,
 `worker_died`), `turn_end` (status `done` or `stopped`, reply preview), `task_finished` /
-`task_failed` (background sub-agents and shell tasks: kind, status, exit code where known),
-`stalled` (no activity for `stalled_minutes`, default 15, while a turn or task runs and no
-question waits for an answer), `all_idle`
-(nothing runs in the watched set any more). `task_started` only when named in `events`. With
+`task_failed` (background sub-agents and shell tasks: kind, status, exit code where known; a
+non-zero exit is `task_failed`), `stalled` (no activity for `stalled_minutes`, default 15, while a
+turn or task runs and no question waits for an answer), `all_idle`
+(nothing runs in the watched set any more). `task_started` only when named in `events`.
+`subagent_finished` is no event of its own but a narrower `task_finished` a subscription can name
+(`RELAY_EVENT_SUBSCRIBABLE_TYPES`): the end of a task that is not a shell command, delivered as a
+`task_finished` line. The default (`events` left out) is every type but `task_started` and
+`task_finished` (and `relay_restarted`), with `subagent_finished`: a shell command that ended well wakes only a watcher
+that names `task_finished`, which takes every task end. A busy worker ends a shell command every
+minute or so, and each was a wake-up, a model turn on the watcher's whole context. A subscription
+whose stored list is exactly the old default (every type but `task_started`, in any order) named no
+events and is read as the new default (`effectiveRelayEventTypes`, at read time, the row is never
+rewritten, so an older relay reading the same database sees what it stored); any other list,
+including the old default plus more, is the watcher's choice and stays. A subscribe that names
+exactly the old default list stores `subagent_finished` with it, so it is never read as the default. A mirror shows the paired
+relay's list as that relay returned it. With
 `heartbeat_minutes` a `heartbeat` event comes at that interval while the watched set has work
 running, none while it is idle. `match` (a case-insensitive regular expression) filters `turn_end`
 and task events by their text; other events pass. `once` ends a subscription after its first event,
@@ -824,6 +957,49 @@ touched for a day is not counted as running meanwhile.
 and the background-only worker death (worker_died), `/api/relay-question` and the approval card's
 notify (question_asked), the activity tracker's task edges, and the archive and delete routes.
 
+### relay_restarted: woken when the relay runs again
+
+`relay_restarted` is an event of this relay, not of a session (`RELAY_EVENT_RELAY_LEVEL_TYPES`):
+a subscription gets it only when it names it, never by default, and one that names nothing else
+needs no sessions. An agent that is about to request a restart subscribes with `once: true` first:
+`POST /api/relay/shutdown` has no caller identity (agents call it with the token, `requestedBy` is
+free text, and agents do not know their conversation id), while the tool knows the calling conversation.
+
+- **How the run before ended.** A clean end of the runtime writes one `app_settings` row
+  (`relay_last_exit`: `action`, `reason`, `requested`, `requestedBy`, `requestedAt`, `stoppedAt`,
+  `noWake`): the queued (or `immediate`) request from the restart queue's `startShutdown`, else
+  `shutdownRuntime` (a signal, the owner process gone). The first note of a runtime wins; a runtime
+  stopped before it listened writes none, so the record of the run before stays for the next start.
+- **At startup** (`noteRelayStarted`, once the HTTP server listens: a start that fails to bind
+  leaves the row for the next one) the relay reads and deletes that row in the same transaction
+  that records one `relay_restarted` event for every active subscription of this relay's live
+  watchers that names it (not a paired relay's, not a mirror), so each start is told once; a
+  `once` subscription ends with it. Without a row the line says the relay did not record how it
+  stopped (for example a crash, a forced stop or a reboot). On Windows a stop by the supervisor or
+  the CLI extension ends the process without its signal handler, so an ordinary stop there may read
+  like that too. A row older than 30 days (`RELAY_LAST_EXIT_MAX_AGE_MS`) is not taken as the run
+  just before (an older OAR, which neither writes nor takes it, may have run in between): it is
+  dropped, its `noWake` with it. A younger one is used; the line shows its stop time, so a relay
+  stopped over a weekend still says how. Delivery is that of every event: coalesced for 30 s (the workers
+  report back first), counted toward the hourly cap, written into an event row that is still
+  pending.
+- **Loop guard.** On every `POST /api/relay/shutdown` (`noteRestartRequested`) the relay notes the
+  conversations whose processing turn answers a `relay_restarted` event (its queue row's
+  `relay_events`); they go into `noWake` and are not woken by that restart (logged), so a woken
+  turn that restarts again ends the chain. That holds for any restart requested while such a turn
+  runs (the button, an update, another agent): the API cannot tell who asked. The line says so up
+  front. A cancelled (or never queued) request forgets them. A held-back `once` subscription ends
+  (`held-back`, logged): that restart was the one it was for, and a later one would wake it with a
+  stale "carry on". If it also watches sessions, that ends with it: their events stop too. One
+  without `once` stays, and a later restart requested while no such turn
+  runs wakes it again. `heartbeat_minutes` on a subscription without sessions is refused (nothing
+  runs in an empty set).
+- The line: `[relay event] relay_restarted: the relay runs again since <time>, after a restart
+  requested by "<requestedBy>" at <time> (reason "<reason>"). Timers and jobs your CLI scheduled
+  before may be gone: check what you were waiting for and carry on. A restart requested while this
+  turn runs does not wake you again.` A stop by signal reads `after it was stopped (SIGTERM) at
+  <time>` (a process id in the runtime's own reason is left out).
+
 ### Across paired relays
 
 The watching relay (**A**, it holds the watcher) and the watched one (**B**) each keep a row of the
@@ -890,8 +1066,11 @@ finished tasks and starts the clock at boot. Running tasks come back when the wo
 sets again (see [Background tasks and workflow progress](#background-tasks-and-workflow-progress)):
 a task that started before this runtime did is not announced as started a second time, and the end
 of a task this runtime never knew is still an event when the settle notice describes the task
-(`description`, `taskType`, `startedAt`). `all_idle` waits out the first 45 seconds after a relay
-start, like the suspend check.
+(`description`, `taskType`, `startedAt`). A task that ended stays ended when a later set lists it
+again, unless the set names another run of it (`taskRunId`, the SDK's `run_id`): a resumed Claude
+sub-agent keeps its task id, so its new run is a start (and later an end) of its own, and a settle
+notice of the earlier run that arrives late does not end it. `all_idle` waits out the first 45
+seconds after a relay start, like the suspend check.
 
 `GET /api/conversations` and `GET /api/conversation/:id` carry `sessionState` (`running_turn`: a
 turn processing, or queued and not held by a usage-limit pause; `background_only`: tasks running;
@@ -900,8 +1079,10 @@ turn processing, or queued and not held by a usage-limit pause; `background_only
 `completed` | `failed` | `stopped`, `exitCode`, `summary`, `endedAt`) and `lastActivityAt`.
 `remote_relay`'s `list_sessions` and `read_session` pass them on as `state`, `tasks` and
 `lastActivityAt`; `active` stays and is true for background work too. `read_session` adds to each
-task its `taskId`, `output` (whether it has output to read) and, for a task with an output file,
-`health` (`minutesSinceOutput`, `quiet`, `quietAfterMinutes`, test-run `counts`);
+task its `taskId`, `output` (whether it has output to read), a shell task's `command` (its command
+line where the worker reports one, scrubbed of credentials and cut at 2,000 characters by the relay
+when the worker posts it, shown to at most 500) and, for a task with an output file, `health`
+(`minutesSinceOutput`, `quiet`, `quietAfterMinutes`, test-run `counts`);
 `read_task_output {session, task_id, lines?}` (read permission; default 200 lines, at most 500 or
 32 KB) reads the end of that output through `GET /api/conversation/:id/background-task/:taskId/output`,
 scrubbed of credentials.
@@ -1011,7 +1192,8 @@ The composer also includes a per-message mode picker:
 
 Mode is stored with each queued message so the relay can change behavior per turn.
 Clarification prompts from the CLI are forwarded back into the browser as question
-cards with a reply box.
+cards with a reply box; a card created with `allowFreeform: false` (approval and
+permission cards) has none and is answered with its choices.
 
 `plan` mode behavior:
 - Draft a concise implementation plan only (no implementation output).
@@ -1091,60 +1273,92 @@ Question bridge rule:
 
 ## Session Worker Management
 
-Session workers are long-running CLI processes that execute turns for Copilot agent sessions. The relay manages a pool of workers to enable:
-- Parallel execution (multiple sessions can run simultaneously)
-- Session persistence (a worker stays alive across turns for a given session)
-- Graceful restarts (degraded workers are replaced without losing queued work)
-
-### Worker Lifecycle States
-
-1. **Spawned** — Worker process created, initializing CLI connection
-2. **Ready** — Worker opened WebSocket to relay, registered in worker pool, ready to accept turns
-3. **Processing** — Worker actively executing a turn (streaming activity to browser)
-4. **Degraded** — Worker failed heartbeat or reported errors; relay moves pending work to other workers or restarts
-5. **Dead/Exited** — Worker process terminated; polling loop will spawn replacement if turns still pending
-
-### Worker Heartbeat & Health Check
-
-- Workers send keep-alive pings every 30 seconds (default) to `/api/workers/{id}/heartbeat`
-- Relay tracks last heartbeat time for each worker
-- If a worker misses 2+ consecutive heartbeats (~60 seconds), it's marked "degraded"
-- Degraded workers don't receive new turns; existing work is reassigned
-- Polling loop detects degraded workers and respawns them if they're still needed
-
-### Supervisor Service
-
-The **session-worker-supervisor-service** tracks all active workers:
-
-- Maintains registry: `workers[sdkSessionId] = { id, process, sdkSessionId, status, lastHeartbeat }`
-- Monitors process health: checks if process is still running, collects exit codes
-- Handles restarts: when a worker fails, spawns a replacement with exponential backoff
-- Cleans up: removes dead workers from registry after TTL (default 5 minutes)
-
-### Environment & Workspace
-
-Session workers inherit:
-
-- `COPILOT_WORKSPACE_ROOT` — Target workspace directory (from turn metadata or session config)
-- `INIT_CWD` — Initial working directory (fallback for workspace resolution)
-- `COPILOT_REMOTE_*` — All relay config via environment variables
-- CLI session state from the last known good checkpoint
-
-### Restart Orchestration
-
-When a worker needs restart:
-
-1. **Graceful shutdown** — Send SIGTERM, wait up to 5 seconds for clean exit
-2. **Kill if needed** — Force SIGKILL if SIGTERM timeout
-3. **Backoff** — Wait before respawn (start at 1s, double up to 30s max)
-4. **Reassign work** — Any pending turns for that session are placed back in queue for the new worker
-5. **Report status** — Relay broadcasts worker status to browser UI (shows "reconnecting..." briefly)
-
-### Platform-Specific Behavior
-
-- **macOS/Linux:** Workers prefer `tmux` sessions for better isolation and debugging (can attach with `tmux attach -t {sessionId}`)
-- **Windows:** Workers launch in a new Terminal window (TTY-Console if available, otherwise cmd)
-- Both: Worker inherits relay's environment and runs from relay repo root so project-local extensions are discoverable
+Each conversation has its own worker process, keyed by the conversation's SDK session id: one
+worker per session, and a session's turns never move to another worker. A Copilot conversation on
+the *Extension* engine runs the `copilot` CLI with the web-relay extension; every other one
+(Claude, Claude Cloud, Cursor, Grok, and Copilot on the *SDK* engine; OpenAI conversations run on
+whichever Copilot engine is selected) runs a plain Node worker (`NODE_WORKER_DESCRIPTORS` in
+`services/session-worker-launch-service.mjs`). The supervisor
+(`services/session-worker-supervisor-service.mjs`) keeps the lifecycle, health and restart limits,
+the launch service spawns, `services/session-worker-stop-service.mjs` stops, and the dead-worker
+recovery lives in `server-runtime.mjs`. Most of it acts only while the
+`SESSION_WORKER_ROUTING_ENABLED` feature flag is on.
+
+### Lifecycle and health
+
+- Registry status: `starting` → `ready` ⇄ `processing`, and `error`. A send, the primer for queued
+  messages and `POST /api/session-worker/:sdkSessionId/launch` call `ensureWorker`, which reuses a
+  live process of the session (found in the process list, or the tmux pane) and launches one
+  otherwise.
+- Heartbeats: every worker posts `POST /api/heartbeat` every 10 s, and any frame on its worker
+  socket counts as one too. The supervisor uses them only at the start: a launched worker that has
+  sent none within 90 s (`heartbeatTimeoutMs`; a Copilot CLI takes about 35 s to boot) is degraded
+  as `startup-heartbeat-timeout`. After its first heartbeat a worker is judged by its pid, not by
+  missed beats.
+- Health (`uiState`, in `/api/status` with the worker list): `green` healthy, `red` a question card
+  waits, `yellow` degraded, `white` nothing known. `degradedReason` is `startup-heartbeat-timeout`,
+  `stale-pid` (the pid is gone while a turn or a question waits for the worker), `spawn-failed`,
+  `restart-exhausted` or the worker's own last error. Yellow clears after 10 s of a healthy worker
+  without a new failure (`degradedRecoveryGraceMs`).
+- An idle (`ready`) worker whose process is gone and that has not heartbeated for 90 s leaves the
+  list; the next message launches a new one. A live idle worker is never evicted by time
+  (`idleEvictionMs` is 0).
+
+### A worker that dies
+
+- When a worker's socket closes while its session owns a processing row, holds the composer or has
+  background sub-agents running, the relay checks 15 s later (`WORKER_DEATH_GRACE_MS`) whether the
+  process is still alive. A sweep every 30 s checks the owners of all processing rows the same way.
+- `recoverDeadWorkerProcessingRows` then drops a continuation row, fails a row the worker had
+  already consumed or that is over `maxRequeueRetries` (5), and puts the others back to `pending`
+  (2 s later, same owner session, one retry more). The session counts a failure (`markError`), the
+  dead worker's sub-agent runs are closed, and the primer launches a new worker for the waiting rows.
+- A worker that is alive but has had no socket for 60 s while a message waits is replaced (see
+  [Worker link reconnects](#worker-link-reconnects)).
+
+### Launch failures and backoff
+
+A launch that throws, a worker that died or a queue row it failed counts a failure: the next launch
+of that session waits 1 s, doubling per failure (1, 2, 4, 8, 16 s; capped at 30 s), for 5 retries (`maxRestartRetries`).
+Then the session is `restart-exhausted`: one more launch is allowed 60 s after the last failure,
+for up to 10 minutes after the first exhaustion, and after that only when a launch is asked for
+(the conversation's Retry, the launch or kill route, a relay restart). While a session's worker
+cannot be started the conversation shows a note (`services/worker-launch-note-service.mjs`). A
+successful launch resets the count.
+
+### Stopping a worker
+
+`stopSessionWorkerProcesses` serves **☠️ Kill session** (`POST /api/session-worker/:sdkSessionId/kill`),
+the CWD relaunch, a provider rebind and the replacement of a worker without a socket. It reads the
+session's processes from a fresh process list and checks that they are gone: on Linux and macOS
+SIGTERM to each and `tmux kill-session`, up to 3 s, then SIGKILL to the survivors and up to 2 s
+more; on Windows `Stop-Process -Force` on the process tree, leaf first; processes still alive after 3 s
+are stopped once more, with any new ones on a fresh list, and get up to 2 s more. A process list that cannot be read stops nothing (`process-list-unreadable`), and processes
+that survive are an error (`409` from the kill route). The kill route fails the rows the worker
+owned and blocks launches of the session for 3 s (`killBlockGraceMs`), so the primer does not
+start it again at once; the launch route clears that block.
+
+### Launch modes and environment
+
+- **Linux/macOS with `tmux`:** a detached tmux session named after the SDK session id
+  (`tmux attach -t <sdk-session-id>`), running `sh -lc`: the extension engine's CLI under `script`
+  for a pseudo-TTY, a Node worker with its output appended to its worker log.
+- **Linux/macOS without tmux:** a detached child process, a Node worker's output into its log.
+- **Windows:** `cmd /c start` opens one console window per worker, titled `<Kind> Worker <first 8
+  characters of the session id>`; the extension engine runs `gh copilot -- --allow-all
+  --session-id <id>`.
+
+The launch environment is the relay's own, taken once at boot (`buildSessionWorkerLaunchEnv`), plus
+per launch the conversation's working directory as `COPILOT_WORKSPACE_ROOT` and `INIT_CWD`,
+`SESSION_ID`, `COPILOT_ALLOW_ALL`, and the bound provider's worker kind, model and credentials
+(`buildSessionWorkerLaunchEnvForSession`). The detached and Windows launches pass all of it. Under
+tmux the worker's login shell gets only the variables `buildTmuxWorkerShellCommand` exports, and
+the secrets (`COPILOT_PROVIDER_API_KEY`, `CURSOR_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN` for cloud
+workers) through an owner-only file it reads and deletes; any other variable, such as
+`OAR_TURN_STALL_*_MS`, `CLAUDE_CODE_AUTO_COMPACT_WINDOW` or `XAI_API_KEY`, only from the tmux
+server's environment or the login profile (see [Session workers under
+tmux](../docs/configuration.md#environment-variables)). `COPILOT_WEB_RELAY_DISABLE_CLI_SPAWN` makes
+every launch fail (`cli-spawn-disabled`), for test relays.
 
 ## How It Works
 
@@ -1163,6 +1377,7 @@ After launching the server, the CLI opens a worker WebSocket link:
 - Identifies itself with the bound SDK session id and worker pid
 - Receives queued turns over `ws(s)://.../api/session-worker/ws`
 - Reconnects starting at 1 second, with exponential backoff capped at 8 seconds
+  (see [Worker link reconnects](#worker-link-reconnects))
 - Falls back to `GET /api/pending` only while the worker socket is unavailable
 - Processes any message with full PC access (file system, commands, etc.)
 - Posts the response back
@@ -1177,6 +1392,33 @@ After launching the server, the CLI opens a worker WebSocket link:
 - Answered relay question cards stay visible in the conversation journal, including
   the answer you submitted.
 
+### Worker link reconnects
+
+Every session worker (Copilot SDK, Claude, Claude Cloud, Cursor, Grok) and the Copilot CLI extension
+use the same link, `shared/worker-runtime/worker-websocket-link.mjs`. Its reconnect rules:
+
+- A connection counts as made at the relay's first `server.hello`, which the relay sends as soon as it
+  accepts the socket. A socket still connecting, or open without that hello, after 15 seconds
+  (`connectTimeoutMs`) is given up and retried: a relay hung in its shutdown can hold a socket in
+  either state without ever ending it.
+- The link ends a socket on whichever comes first of an error, a close, that deadline, a stale
+  connection (30 seconds without a server frame) and the relay's `server.draining`, and schedules
+  the next attempt from there; later events from the same socket are ignored. It never waits for a
+  close event, which Node 22 does not fire for a socket closed while connecting, and a socket whose
+  constructor throws is retried too.
+- There is at most one pending reconnect and one socket at a time. The delay starts at 1 second and
+  doubles up to 8 seconds, plus up to 250 ms of jitter; it starts over only after a completed
+  handshake, so a relay that accepts and drops the socket is not retried every second.
+- Each failed attempt logs one `worker ws disconnected <reason> attempt=<n> retryInMs=<ms>` line in
+  the worker log for the first three, then at most one a minute, with `notLogged=<n>` counting the
+  ones in between.
+- `stop()` (worker shutdown) clears the pending reconnect and the deadline and closes the socket
+  without scheduling another attempt.
+
+The relay's detached-worker watch (`services/detached-worker-watch-service.mjs`) is the safety net
+behind this: it replaces a worker that has had no socket for 60 seconds while a message waits, but
+never while a turn or background work of that session runs, so the link has to reconnect by itself.
+
 ### Session activation behavior (important)
 
 In extension-managed mode, the web server can already be running while the CLI is still
@@ -1205,11 +1447,11 @@ If a conversation is still unbound when the CLI first sees it, the extension now
 
 ### Worker Launcher
 
-- Workers on Windows launch via a **stable Terminal window** (when available).
-- If TTY-Console (optional dependency) is installed, workers use an interactive terminal for debugging.
-- Otherwise, workers spawn in a new `cmd` or PowerShell window.
-- Window name is workspace-based so repeated worker restarts reuse the same window instead of opening duplicates.
-- Claude workers open a `Claude Worker <id>` window running `node claude-session-worker.mjs` directly, instead of the `gh copilot` launch path.
+- Each worker opens its own console window through `cmd /c start`, titled `<Kind> Worker <first 8
+  characters of the session id>` (`Copilot Worker`, `Claude Worker`, `Cursor Worker`, `Grok Worker`,
+  `Claude Cloud Worker`, `Copilot SDK Worker`); a relaunch opens a new window.
+- Node workers run `node <kind>-session-worker.mjs --session-id <id>` directly; the extension engine
+  runs `gh copilot -- --allow-all --session-id <id>`.
 
 ### Path Handling
 
@@ -1290,10 +1532,13 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | POST | `/api/relay/pause` | Pause dequeueing and drop currently queued messages |
 | POST | `/api/relay/resume` | Resume dequeueing after pause |
 | POST | `/api/relay/shutdown` | Queue an authenticated relay shutdown or self-restart |
+| GET | `/api/relay/shutdown` | The queued request's state (as `relay_shutdown_state`), plus `preview`: what a restart asked now would wait for and leave running (`?action=shutdown` for a shutdown). See [Manual relay shutdown / self-restart](#manual-relay-shutdown--self-restart) |
+| POST | `/api/relay/shutdown/keep-waiting` | Answer to the max-wait question: the queued request waits another full period, counted from now → `{ ok, extended, …state }` |
+| POST | `/api/relay/shutdown/cancel` | Withdraw a queued (not yet started) shutdown or restart; held messages go out at once |
 | GET | `/api/relay-questions` | (CLI/UI) List relay questions by `status` (for example `pending` or `answered`) |
 | GET | `/api/relay-question/:id` | (CLI) Fetch a single relay question |
-| POST | `/api/relay-question` | (CLI) Create a relay question for the browser |
-| POST | `/api/relay-question/:id/answer` | (UI) Submit an answer for a relay question |
+| POST | `/api/relay-question` | (CLI) Create a relay question for the browser. `allowFreeform` defaults to `false` when `choices` are given (to `true` without): such a card has no reply box and takes only its choices |
+| POST | `/api/relay-question/:id/answer` | (UI) Submit an answer for a relay question. A card created with `allowFreeform: false` and choices (approval and permission cards) takes only its choices, matched trimmed and in any case and stored as the card's label (several, `", "`-joined, on a multi-select card); anything else is refused with `400` and `choices`, and the card stays open |
 | POST | `/api/relay-question/:id/timeout` | (CLI/UI) Mark a relay question timed out |
 | POST | `/api/heartbeat` | (CLI) Keep CLI status alive. A session worker may send `backgroundTasks: { count, digest }`; the answer carries `resyncBackgroundTasks: true` when the relay's set for that worker differs |
 | GET | `/api/status` | Overall status |
@@ -1314,6 +1559,8 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | POST | `/api/settings/cursor` | Set/remove the Cursor API key, default model, or enabled model subset; key changes reset discovered models and effort tiers |
 | GET | `/api/settings/turn-ceiling` | Read the max turn duration plus slider bounds (`minMinutes`, `maxMinutes`, `stepMinutes`, `defaultMinutes`) |
 | POST | `/api/settings/turn-ceiling` | Set the max turn duration in minutes (`0` = no limit) |
+| GET | `/api/settings/relay-restart-max-wait` | How long a queued relay restart waits before it asks: `{ maxWaitMinutes, choices: [5, 10, 15, 30, 60, 120, 240, 0], defaultMinutes: 30, overrideMs }`; `0` = no limit; `overrideMs` is `OAR_RELAY_RESTART_MAX_WAIT_MS` when set |
+| POST | `/api/settings/relay-restart-max-wait` | `{ maxWaitMinutes }` → the GET body; anything but one of `choices` is `400`. A queued request measures its current period against the new value at once |
 | GET | `/api/settings/subagent-record-retention` | How long sub-agent records keep tool inputs and output: `{ retentionDays, choices: [0, 7, 14, 30, 90], defaultDays: 90 }`; `0` = keep for good |
 | POST | `/api/settings/subagent-record-retention` | `{ retentionDays }` → the GET body; anything but one of `choices` is `400`. Runs a retention sweep 5 s later |
 | POST | `/api/claude-native-session` | (Claude worker) Persist the native Agent SDK session id for resume |
@@ -1322,9 +1569,9 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | POST | `/api/claude-cloud-session` | (Claude Cloud worker) Report the cloud session a conversation is bound to: `{ conversationId, cloudSessionId, sessionUrl?, lastSequence, pushedBranch?, costUsd?, model? }` → `{ ok, cloud }`. Sent after the session was created, after every `result` and on a push; emits `claude_cloud_session`. `404` without a runtime session, `409` for a conversation that is not a cloud one |
 | POST | `/api/cursor-plan-usage` | (Cursor worker) Report the agent's cumulative billed usage; the relay diffs it against a per-agent checkpoint and books the increase into the current billing cycle under the pool implied by the turn's model |
 | POST | `/api/subagent-run` | (Worker) Register/update a subagent run. A new run needs the spawning turn's `messageId`; an update to a known run may omit it (a background agent's end arrives between turns). Optional header fields: `subagentType`, `model`, `modelInherited`, `taskId`, `background`, `timelineOwner`; a post without `status` leaves the run's state alone. Emits `subagent_status` with the whole header |
-| POST | `/api/subagent-timeline` | (Worker) `{ conversationId, subagentRunId, entries: [{ key, kind, text, done?, toolName?, toolUseId?, metadata? }], header? }` → `{ ok, stored, truncated }`. Kinds: `thought`, `tool_call`, `tool_result`, `text`, `child`, `note`. Fenced by the run row, not by an open turn; an unknown run whose `header.parentSubagentId` is known is created under the parent's turn, anything else is `404 unknown_run`. Sends `subagent_timeline` `{ conversationId, messageId, subagentRunId, entries, truncated }`, volatile, only to the pages watching the run (`subagent_viewer_watch`) |
+| POST | `/api/subagent-timeline` | (Worker) `{ conversationId, subagentRunId, taskId?, entries: [{ key, kind, text, done?, toolName?, toolUseId?, metadata? }], header? }` → `{ ok, stored, truncated }`. Kinds: `thought`, `tool_call`, `tool_result`, `text`, `child`, `note`. Fenced by the run row, not by an open turn; an unknown run whose `header.parentSubagentId` is known is created under the parent's turn, an unknown run whose `taskId` (or `header.taskId`) a run of the conversation carries is written to that run (a resumed agent; when the post sets that finished run `running` again, the relay adds a note where it resumed), anything else is `404 unknown_run`. `header.status: 'running'` clears the run's end time. Sends `subagent_timeline` `{ conversationId, messageId, subagentRunId, entries, truncated }`, volatile, only to the pages watching the run (`subagent_viewer_watch`) |
 | GET | `/api/conversation/:conversationId/subagent/:subagentRunId` | One run's record for the viewer: `?after=<seq>&limit=<n>` (default 500, max 2000) → `{ run, entries, children, nextAfter, complete }`. `entries` are those after `after` plus any still open; `run.legacy` marks a record rebuilt from the lane rows |
-| POST | `/api/conversation/:conversationId/subagent/:subagentRunId/cancel` | Request cancellation of one subagent run (unsupported by the Claude runtime) |
+| POST | `/api/conversation/:conversationId/subagent/:subagentRunId/cancel` | Queue an `abort_subagent` control for the session's worker (`{ parentMessageId?, clientId? }` → `{ ok, queued, acknowledgement }`; `not-found`, `message-mismatch`, `already-cancelled` and `already-finished` queue nothing). The Claude worker stops a background sub-agent (`stopTask`), the Copilot SDK worker a background agent (`rpc.tasks.cancel`), the extension engine tries the SDK session's abort methods; any other run, or worker, answers "not supported". Workers read controls only while a turn runs. Whole-turn **Stop** always works |
 | PATCH | `/api/conversation/:id/message/:messageId/share-visibility` | Hide or unhide a single message from shared views |
 | PATCH | `/api/conversation/:id/message/:messageId/pin` | `{ pinned }` → pin or unpin a single message; answers with the conversation's pin list and broadcasts `conversation_pins_updated` |
 | POST | `/api/conversation/:id/share` | The conversation's read-only share link, made if it has none (one active share per conversation): `{ token, shareUrl, path, created }`; a new one sends `share_created` |
@@ -1346,12 +1593,12 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | POST | `/api/remote-relays/:id/check` | Probe a paired relay now |
 | POST | `/api/remote-relays/pair` | (Relay to relay) Another relay introduces itself after the user paired it there |
 | GET | `/api/remote-relays/summary` | (Worker) `{ count, online, localEnabled }`: the number of paired relays, how many of them are online, and whether agent sessions are switched on. Workers register `remote_relay` when `count` is above zero or `localEnabled` is `true` |
-| POST | `/api/remote-relays/tool` | (Worker) One `remote_relay` tool call: `{ conversationId, action, args }`. For a paired relay the relay checks the mention unlock, the permission, the hop limit and (ask/plan mode) the user's approval, then forwards the call to the remote. For this relay itself (named by its name or `this`; refused with `REMOTE_RELAY_LOCAL_DISABLED` while agent sessions are off) it checks instead that the call does not aim at the caller's own conversation (`REMOTE_RELAY_OWN_SESSION`) and, for `create_session`, that the caller was not created by an agent (`REMOTE_RELAY_NESTED_SESSION`), that fewer than 4 sessions it created have a turn queued or running (`REMOTE_RELAY_SESSION_LIMIT`) and that the user allowed it once for the conversation; the call then runs against this relay's own routes in-process. `wait_seconds` is cut to the `maxWaitSeconds` setting for every target |
+| POST | `/api/remote-relays/tool` | (Worker) One `remote_relay` tool call: `{ conversationId, action, args }`. For a paired relay the relay checks the mention unlock, the permission, the hop limit and (ask/plan mode) the user's approval, then forwards the call to the remote. For this relay itself (named by its name or `this`; refused with `REMOTE_RELAY_LOCAL_DISABLED` while agent sessions are off) it checks instead that the call does not aim at the caller's own conversation (`REMOTE_RELAY_OWN_SESSION`) and, for `create_session`, that the caller was not created by an agent (`REMOTE_RELAY_NESTED_SESSION`), that fewer than 4 sessions it created have a turn queued or running (`REMOTE_RELAY_SESSION_LIMIT`) and that the user allowed it once for the conversation; the call then runs against this relay's own routes in-process. A `model` in `create_session` or `send` is checked first, before any approval card, against the list New Chat offers for the provider on the target (`/api/models` for Copilot and OpenAI, the provider settings routes for Claude, Cursor, Grok and Claude Cloud): one it does not list is refused with `REMOTE_RELAY_UNKNOWN_MODEL`, `suggestions` (the close matches) and `models`, and nothing is created or sent. Casing follows the list; a Claude alias (`opus`, `sonnet`, `haiku`, with an optional `[1m]`) resolves to the newest listed model of its family by version number (a date suffix ignored, the undated id first, `[1m]` ids only when the alias asks and they are listed); a `[1m]` id with only its base listed runs as the base, with a note; a Copilot id with its effort (`gpt-5.4-high`) goes to the bootstrap and the first prompt as the listed id plus `reasoningEffort` (an explicit `effort` wins, and a note says so), but only when the catalogue lists that effort for the id (`reasoningByModel`): `gpt-5.1-codex-max` with only `gpt-5.1-codex` listed is unknown, with the base suggested; `auto` passes. `send` also takes the provider's whole discovered list (`availableModels`) and the session's own model, as the message route does. Without a list (discovery has not run, the route did not answer; `auto` alone is no list) the model goes on unchecked and `modelNote` says so, as it does when the bootstrap binds another model than the one asked. A provider not set up there answers `REMOTE_RELAY_PROVIDER_UNAVAILABLE` before its model is looked at. The bootstrap route itself checks a Copilot model from an agent against Copilot's own models: an unknown one is refused (`COPILOT_MODEL_UNAVAILABLE`, with `supportedModels` and `suggestedModels`; another provider's model gets that provider's answer), a listed one is bound in the list's casing, an effort-suffixed one as the listed id plus that effort when `reasoningByModel` lists it; the browser's New Chat keeps its fallback to the current model. `wait_seconds` is cut to the `maxWaitSeconds` setting for every target |
 | GET | `/api/relay-events/subscriptions` | Every active [relay event subscription](#relay-event-subscriptions) (`{ available, subscriptions }`); refused to other relays' agents |
 | DELETE | `/api/relay-events/subscriptions/:id` | The user's Unsubscribe (a paired relay's subscription too: it learns with its next fetch); refused to other relays' agents |
 | POST | `/api/relay-events/remote/subscribe` | (Relay to relay) A paired relay's agent subscribes to sessions here: `{ watcher: { conversationId, title }, subscriber: { name }, scope, sessions, events?, once?, match?, stalled_minutes?, heartbeat_minutes?, dry_run? }` → `{ ok, subscription }`. Another relay's request only, inbound switch on; see [Across paired relays](#across-paired-relays) |
 | POST | `/api/relay-events/remote/pull` | (Relay to relay) That relay fetches its events: `{ after, subscriptions: [{ id, watcher }], ended: [ids] }` → `{ ok, events, cursor, more, subscriptions, ended, dropped }` |
-| POST | `/api/background-task-settled` | (Worker) How a background task ended: `{ conversationId, taskId, toolUseId?, status, summary?, reason?, description?, taskType?, startedAt? }` (Claude worker, from `task_notification`; the last three describe a task that was in its published set) |
+| POST | `/api/background-task-settled` | (Worker) How a background task ended: `{ conversationId, taskId, toolUseId?, taskRunId?, status, summary?, reason?, description?, taskType?, startedAt? }` (Claude worker, from `task_notification`; the last three describe a task that was in its published set) |
 | GET | `/api/remote-relays/inflight` | (Worker) Number of `remote_relay` calls running for `conversationId` |
 | GET/POST | `/api/settings/remote-relays` | This relay's `publicUrl` and `inboundEnabled` (accept prompts from other relays' agents) |
 | GET | `/api/settings/agent-sessions` | Agent sessions: `{ enabled, maxWaitSeconds, limits: { minWaitSeconds: 120, maxWaitSeconds: 3600, stepSeconds: 60 }, maxActiveSessions: 4 }`. `enabled` (default `false`) lets this relay's agents start and use sessions on it through `remote_relay`; `maxWaitSeconds` (default `600`) is the longest wait of one `remote_relay` call, for this relay and paired ones |
@@ -1365,6 +1612,7 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
   - `reason` (optional string)
   - `requestedBy` (optional string)
   - `restart` (optional boolean-ish flag; `true` queues self-restart instead of plain shutdown)
+  - `immediate` (optional boolean-ish flag; `true` does not wait for the running turns)
 - Example restart request:
 
 ```json
@@ -1381,14 +1629,61 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
   - `restart`: boolean mirror of the action
   - `requestedAt`, `reason`, `requestedBy`
   - `queue`: current `pendingCount` / `processingCount` / `parkedCount`
-- The relay waits until no turn is processing before acting; this API is not an interrupt or cancel mechanism. While the request is queued no pending message is handed to a worker (a turn started meanwhile would postpone the restart again); pending and parked rows stay in the database and run after the restart.
+  - `waitingFor`, `held`, `backgroundTasks`, `survival`, `maxWaitMs`, `deadlineAt`, `immediate` (below)
+- A conversation that subscribed to `relay_restarted` is woken when the relay runs again, with who requested it, when and why ([relay_restarted](#relay_restarted-woken-when-the-relay-runs-again)); one whose turn answered that event when the request came is not woken by it.
+- The relay waits until no turn is processing before acting. While the request is queued no pending message is handed to a worker (a turn started meanwhile would postpone the restart again); pending and parked rows stay in the database and run after the restart.
+- `immediate: true` (boolean-ish, like `restart`) starts it at once, running turns or not: the banner's **Restart now**. The answer still names what it did not wait for.
+- Maximum wait (`services/relay-restart-queue.mjs`): after **Ask after a queued relay restart has waited** (`relay_restart_max_wait_minutes`, 30 by default, 5–240 or `0` = no limit; `OAR_RELAY_RESTART_MAX_WAIT_MS` overrides it in ms, for test relays) the request stays queued and sets `question: { askedAt }`; the relay pushes one notification (titled *Relay restart waiting*; switch **Queued relay restart waited its maximum time**, `relayRestart`) and never restarts while turns run; it still goes ahead as soon as the last turn ends, question or not. A raised maximum (or none) that moves the deadline into the future withdraws the question; `/keep-waiting` without a question does nothing (`extended: false`). An `immediate` request may name the queued request it was shown (`expectRequestedAt`, its `requestedAt`); when that request is gone the answer is `accepted: false, stale: true` and nothing starts. Agents are told never to send `immediate` (`relay-tools.md`). The user answers with `immediate`, `/keep-waiting` (another full period from now; counted in `keptWaiting`) or `/cancel`. With no limit the request, and the messages it holds, wait until the turns end or someone decides.
+- What it waits for, holds and leaves running (`services/relay-restart-picture.mjs`), in the answer, in `GET /api/relay/shutdown`, in `/api/status` → `relayShutdown` and in the `relay_shutdown_state` socket event (sent on every change and on connect):
+  - `waitingFor`: `[{ conversationId, title, turns }]`, the sessions with a processing turn
+  - `held`: `{ count, conversations: [{ conversationId, title, count }] }`, pending and parked messages
+  - `backgroundTasks`: `[{ conversationId, title, count, detail, survives, why }]`, sessions with running background work of a live worker (the task panel's sets and running sub-agent runs, through `background-work-view.mjs`), then sessions with console tasks held since the last restart (`background-task-store.mjs` `listRestored`), which no worker has confirmed yet: `survives: null`
+  - `survival`: `{ action, workersSurvive, summary }`. Workers are separate processes (tmux, detached, a console window) and outlive a restart, which the relay's supervisor or the CLI extension takes; they outlive a shutdown too, except under a systemd service (detected from `INVOCATION_ID` and a `.service` cgroup), whose stop may take the workers with it (`survives: false`, shown as "may stop"; a worker in a tmux session the service did not start survives, which the relay cannot tell). A Claude Cloud session runs at Anthropic and always survives
+  - while queued also `holdsNewTurns`, `maxWaitMs`, `waitingSince` (start of the current period), `deadlineAt` (`null` without a limit), `question`, `keptWaiting`
 - Ownership after an intentional restart follows the argv role, so exactly one supervisor acts on exit 75:
   - `server.js --supervised` exits 75 and relaunches under `.github/extensions/web-relay/server-lifecycle/managed-server.mjs`
   - bare `node server/server.js` keeps its supervisor attached, respawns the `--relay-runtime` child, and keeps the same terminal session alive
 
+### Interrupted turns after a restart
+
+`services/restart-resume-service.mjs` implements **After a relay restart, tell interrupted sessions
+to carry on** (`app_settings` `restart_resume_notes`, `'1'` on, off when absent; `GET/POST
+/api/settings/restart-resume` `{ enabled }`, a boolean, 400 otherwise). At boot it notes the queue
+rows that are `processing` (the turns the runtime before left) and follows them through the
+recovery paths, which report each outcome (`noteRestartTurnOutcome`):
+
+| Path | `cut` (cannot run again) | `requeued` | `failed` |
+| --- | --- | --- | --- |
+| stale sweep (`recoverProcessingOlderThan`) | stale continuation dropped; consumed row failed | requeued | over the retry budget |
+| dead worker (`recoverDeadWorkerProcessingRows`) | continuation dropped; consumed row failed | requeued | over the retry budget |
+| owner heartbeat idle (`recoverOwnedProcessingRowsForSession`) | continuation dropped; consumed row failed; a started turn failed as `turn-replay-blocked` | requeued | |
+
+A heartbeat that lists a row (`activeQueueMessageId(s)`) claims it: its worker lived through the
+restart and has the turn, so whatever ends it later is not put down to the restart, and the
+session gets no note. A row that leaves `processing` another way is read from the queue: back in `pending` or `parked` is
+`requeued`, anything else (a reply from a worker that lived through the restart) is settled. Once
+none of a conversation's rows of the boot is processing, it gets a note when one was `cut` and none
+was `requeued`, `claimed` or `failed`; the stale sweep's 15 s tick decides the ones that settled on their own,
+and the watch ends 30 minutes after the boot. The note is a message of the relay's (role `user`,
+`kind = 'relay-restart-resume'`) with a pending queue row on the interrupted turn's model, mode and
+owner, queued at the time it is written (behind a message the user queued meanwhile), as the
+usage-limit follow-up is; the primer then starts the worker. No note when the setting is off at
+that moment, for a deleted or archived conversation, while the conversation holds a usage-limit
+follow-up, or a second time in the same runtime. The browser renders it as a compact relay row
+(`relay-restart-note-view.mjs`).
+
 ### Upload storage model
 
-- Physical blobs are stored in `server/uploads/<sha256>` (content-addressed).
+- Physical blobs are stored in `<data dir>/uploads/<sha256>` (content-addressed) when
+  `COPILOT_WEB_RELAY_DATA_DIR` or the config's `dataDir` chose the data dir, else in
+  `server/uploads/<sha256>` (`resolveUploadDir` in `services/data-dir-resolution.mjs`).
+- Blobs earlier versions left elsewhere are read in place: `server/uploads` (a config
+  `dataDir` did not move uploads before 0.9.14) and `uploads/` in the folder that holds the
+  data dir (state migrations before 0.9.14 copied a checkout's uploads there).
+  `resolveUploadReadDirs` lists them after the upload dir; a blob is read from the first
+  copy whose size is the recorded one (two of that size that are not alike, i.e. differ in
+  their first or last 64 KiB: the one whose content hashes to its name, decided once per blob). New uploads are written to the upload dir only, and
+  the unreferenced-upload sweep and a cache wipe delete only there.
 - Metadata (`original_name`, `mime_type`, `size_bytes`) is stored in SQLite.
 - Message/conversation references are tracked in SQLite; when a conversation is deleted,
   unreferenced blobs are garbage-collected from disk automatically.
@@ -1412,16 +1707,18 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 - Images over ~2 MB are downscaled client-side to a 2560 px longest edge and re-encoded
   to **JPEG** before upload. GIF and SVG are never re-encoded, and a re-encode that fails,
   grows the file, or yields anything other than JPEG/PNG falls back to the original bytes.
-- The output format is deliberately restricted to JPEG/PNG: Copilot's image-input docs call
-  these "the most widely supported formats". WebP compresses better and previews correctly
-  in the browser, but arrives at the model unreadable.
+- The output format is deliberately restricted to JPEG/PNG (`image-downscale.mjs`): Copilot's
+  image-input docs call these "the most widely supported formats". The composer converts for
+  every provider alike, although the Claude workers, local and cloud, would take a WebP as it is
+  (`claude-attachments.mjs` inlines JPEG, PNG, GIF and WebP).
 - Re-encoding therefore has two triggers, tracked by `reencodeReason()`:
   - `'size'` — the image is over the byte threshold. Abandoned if the result is no smaller.
   - `'format'` — the source is not PNG/JPEG/GIF (e.g. WebP, AVIF, HEIC), so it is converted
     at its original dimensions **regardless of size**, and kept even if the result is larger:
     a bigger image the model can read beats a smaller one it cannot.
 - Without the `'format'` trigger a WebP small enough to skip the size threshold would reach
-  the model invisible.
+  the model in a format outside that pair. An image that does not come through the composer
+  (`POST /api/upload` from a script) is stored as it is.
 - Attachments upload **eagerly** on selection rather than on Send. Chips show an
   uploading spinner, and a failed upload becomes a clickable retry.
 - Send is disabled while any upload is in flight. Failed uploads are deliberately not
@@ -1483,7 +1780,7 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 - Use `/api/repo/list?path=<repo-relative-dir>&includeHidden=0|1&includeHeavy=0|1` for lazy-loaded workspace directory browsing.
 - Use `/api/drives/roots` + `/api/drives/list?path=<path>&includeHidden=0|1` for lazy-loaded drive/root browsing (separate from workspace heavy mode).
 - Use `/api/drives/file?path=<path>` and `/api/drives/files-preview?path=<path>` for drive/root file raw/preview access.
-- Use `/api/session-root/list?path=<sessionRootPath>&includeHidden=0|1` for the explorer's Session root. Child directories below it lazy-load through `/api/drives/list` as usual. The Claude Agent SDK creates a session's directory lazily — only once the session writes `subagents/` or `tool-results/` files — so the root is served as an empty folder until then rather than 404ing, and the transcript that lives one level up in the project directory is listed as a child of it. Cursor sessions resolve their Session root the same lazy way: the worker's per-session agent store (`$CURSOR_AGENT_STORE_DIR` or `server/data/cursor-agents/<sdkSessionId>`) exists only after the session's first turn, and the Session button stays disabled until it does.
+- Use `/api/session-root/list?path=<sessionRootPath>&includeHidden=0|1` for the explorer's Session root. Child directories below it lazy-load through `/api/drives/list` as usual. The Claude Agent SDK creates a session's directory lazily — only once the session writes `subagents/` or `tool-results/` files — so the root is served as an empty folder until then rather than 404ing, and the transcript that lives one level up in the project directory is listed as a child of it. Cursor sessions resolve their Session root the same lazy way: the worker's per-session agent store (`$CURSOR_AGENT_STORE_DIR` or `cursor-agents/<sdkSessionId>` in the relay's data dir) exists only after the session's first turn, and the Session button stays disabled until it does.
 - Requests are auth-protected and restricted to files inside the workspace root.
 - **Platform split** — the drives API adapts automatically based on the server OS:
   - **Windows:** drive roots are discovered via `fsutil.exe`; paths use Windows drive-letter format (`C:/foo/bar`); directory listing uses PowerShell.
@@ -1667,8 +1964,18 @@ The migration `server/migrations/0001-add-structured-answer.mjs` creates the `st
 
 ## Relay Tool Guidance
 
-The CLI extension (`.github/extensions/web-relay/extension.mjs`) loads `relay-tools.md`
-for shared tool guidance.
+The CLI extension (`.github/extensions/web-relay/extension.mjs`) and the Copilot SDK worker
+(`copilot-worker/copilot-prompt-context.mjs`) load `relay-tools.md` (`COPILOT_WEB_RELAY_TOOLS`
+overrides the path) for shared tool guidance.
+
+How to embed media in a reply (a markdown image naming the file's absolute host path; the page
+renders images and turns video and audio into players) is one text,
+`shared/media-embed-instructions.mjs`. The Claude worker appends it to the system prompt, the
+Copilot SDK worker to its relay guidance, the Cursor and Grok workers put it in front of the first
+prompt each worker process sends. The
+Copilot extension engine's prompt builder (`shared/worker-runtime/prompt-context.mjs`) does not add
+it and `relay-tools.md` does not contain it, and a Claude Cloud session gets no relay guidance at
+all, so those two are not told.
 
 The browser UI keeps the usage button in the sidebar header, and that button continues to
 call `/api/usage` directly. It now renders the unified plan-usage report — one card per
@@ -1684,7 +1991,6 @@ service).
   "authToken": "<your-token>",
   "port": 3333,
   "localhostOnly": true,
-  "pollIntervalMs": 3000,
   "processingTimeoutMs": 600000,
   "conversationSessionMode": "isolated",
   "contextIndicatorMode": "default",
@@ -1714,17 +2020,31 @@ service).
 
 | Key | Default | Description |
 |---|---|---|
-| `authToken` | *(required)* | Token for all API / UI access |
-| `port` | `3333` | HTTP/WebSocket listen port |
+| `authToken` | generated if empty | Token for all API / UI access. Empty or missing: a random token on every start, printed to the log and not saved (`--token <value>` sets one for the run) |
+| `port` | `3333` | HTTP/WebSocket listen port (`--port <n>` for the run) |
 | `localhostOnly` | `true` | Bind only to loopback (`127.0.0.1`) and block LAN/WAN access |
-| `pollIntervalMs` | `3000` | CLI poll interval (ms) |
+| `host` | `127.0.0.1` | Read by the workers only: the address they connect to the relay on (`0.0.0.0`, `::` and `localhost` mean `127.0.0.1`) |
+| `dataDir` | `data/` beside the server | Database, the relay's lock file, uploads (`uploads/` inside it) and Cursor agent stores (`cursor-agents`); relative to the config file's folder; `COPILOT_WEB_RELAY_DATA_DIR` wins. Without either, a checkout keeps its uploads in `server/uploads`; uploads made there before `dataDir` was set stay there and are still read |
+| `pollIntervalMs` | — | Read by nothing; new config files still get `3000` |
 | `processingTimeoutMs` | `600000` | Worker-inactivity window before a turn is treated as stale (ms) — see [Turn recovery](#turn-recovery-and-the-max-turn-duration) |
-| `conversationSessionMode` | `isolated` | SDK session strategy (`isolated` or `shared`) |
-| `contextIndicatorMode` | `default` | Input context indicator style (`default` shimmer line or `bar` fill indicator) |
+| `maxRequeueRetries` | `5` | Retries of a recovered queue row before it fails |
+| `conversationSessionMode` | `isolated` | `isolated` or `shared`; recorded as `runtime_sessions.strategy` and reported in `/api/status`, with no effect on behaviour |
+| `contextIndicatorMode` | `default` | Composer context indicator: `default`, a line across the composer's top edge whose colour runs from green to red as the context fills, or `bar`, a line as long as the share in use; anything else is `default`. Sent to the page in `/api/status` |
+| `remotePath` | `""` | URL path prefix when the relay is served under a subpath (PWA URLs, socket.io path) |
+| `trustProxy` | `"loopback"` | Express `trust proxy`: which proxies may set `X-Forwarded-*` |
+| `workspaceRootAllowList` | unset | Folders conversations may start in; see [Changing the launch CWD](#changing-the-launch-cwd) |
+| `publicHostnames` | `[]` | The relay's own public hostnames; the preview lane refuses them |
+| `previews.enabled`, `.port`, `.bindHost`, `.allowPublicBind`, `.publicBaseUrl`, `.allowedTargetHosts`, `.maxLive` | `false`, `port + 1`, `127.0.0.1`, `false`, —, `[]`, `8` | The preview listener (`services/preview-registry-service.mjs`, [docs/preview-servers.md](../docs/preview-servers.md)) |
+| `pushVapidSubject` | `mailto:copilot-remote@example.com` | Contact URI sent to push services |
+| `sharedPresenceMaxPerConversation`, `sharedPresenceMaxGlobal` | `200`, `5000` | Caps of the shared-view watcher count |
+| `cliBinaries` | *(written by the relay)* | Provider CLI paths resolved by an install from Settings, applied at startup |
+| `cliPort` | `4445` | Port of the standalone `relay.mjs`; the preview lane refuses it |
+| `features` | — | Legacy: moved into the database once at startup, then the **Features** tab |
 | `sdkVersion` | *(latest detected)* | Optional semver pin (for example `1.0.63`) used by relay SDK auto-detection |
 | `sdkPath` | *(auto-detected)* | Optional absolute override for Copilot SDK entry path (`.../copilot-sdk/index.js`) |
 | `cliPath` | *(auto-detected)* | Optional absolute override for Copilot CLI app path (`.../app.js`) |
 | `restartGracefulTimeoutMs` | `8000` | Graceful shutdown wait before force fallback |
+| `restartReadyCooldownMs` | `1000` | How long the worker restart orchestrator still holds dequeue after a restart transaction is ready |
 | `restartShutdownTimeoutMs` | `45000` | Drain timeout while waiting for active queue jobs |
 | `restartSpawnTimeoutMs` | `18000` | Max wait for resume process to leave online state |
 | `restartRebindTimeoutMs` | `20000` | Max wait for session-sync rebind confirmation |
@@ -1891,23 +2211,18 @@ reported as `relayShutdown`.
 
 ## Database Migrations
 
-The relay uses a simple SQL migration system to evolve the SQLite schema over time.
-
-**Migration File Location:** `server/migrations/`
-
-**Migration Lifecycle:**
-
-1. On server startup, relay checks the database for applied migrations
-2. Unapplied migrations (in filename order) are executed automatically
-3. Each migration file exports a `up()` function that creates/alters tables
-4. After successful execution, migration is recorded in the database metadata
-5. Migrations are idempotent: re-running a migration is safe (no duplicates)
-
-**Currently Deployed Migration:**
-
-- **`0001-add-structured-answer.mjs`** — Adds `structured_answer` and `request_schema` columns to the `relay_questions` table to support multi-field elicitation forms (see [Structured Answers and Multi-Field Elicitation](#structured-answers-and-multi-field-elicitation) section).
-  - `request_schema` (TEXT/JSON) — JSON schema defining form fields and validation
-  - `structured_answer` (TEXT/JSON) — User's submitted multi-field response object
+There is no migration runner and no record of applied migrations. At every start
+`applySchema(db)` (`server/db-schema.mjs`, the same code the tests build their databases with) runs
+`SCHEMA_SQL` (`CREATE TABLE IF NOT EXISTS` for a fresh database), then the upgrade sequence:
+guarded `ALTER TABLE … ADD COLUMN` statements (each runs only when `PRAGMA table_info` lacks the
+column) and, among them, the functions of `server/migrations/0002-…` to `0018-…` in order. Each of those checks the
+schema itself and does nothing when its change is already there, so all of them run on every boot.
+From 0004 on a failure is logged (`migration 00NN failed; retrying on next boot`) and the boot goes
+on. Every file can also be run by hand against a database: `node server/migrations/<file>.mjs
+[path/to/copilot.db]`. `0001-add-structured-answer.mjs` (the `structured_answer` and
+`request_schema` columns of `relay_questions`, see [Structured Answers and Multi-Field
+Elicitation](#structured-answers-and-multi-field-elicitation)) is only such a script: the boot adds
+those columns with its own guarded `ALTER TABLE`.
 
 **In-place column additions:**
 
@@ -1951,6 +2266,13 @@ any length. A conversation with a row whose timestamp is not the relay's ISO for
 (`YYYY-MM-DDTHH:MM:SS.mmmZ`) or whose id is not lowercase letters, digits and dashes is paged the
 old way: every row loaded, the page cut afterwards.
 
+`0018-background-task-rows.mjs` adds `background_task_rows` (`store_key`, `task_id`, `state`
+`live` | `ended`, `row_json`, `ended_at`, `updated_at`; one row per key and task): the task
+console's rows across a relay restart (see
+[Background tasks and workflow progress](#background-tasks-and-workflow-progress)). Additive and
+idempotent; a failure is logged and retried on the next boot, and the store keeps its rows in
+memory meanwhile. An older build ignores the table.
+
 `0007-claude-cloud.mjs` adds the storage of [Claude Cloud](#claude-cloud-provider) conversations.
 It is additive and idempotent, runs on every boot, and a failure is logged and retried on the next
 one:
@@ -1964,26 +2286,26 @@ one:
 - `conversations.cloud_source_json` (TEXT/JSON) — `{ repoUrl, branch, environmentId, sessionUrl,
   pushedBranches: [{ branch, at }] }`
 
-New tables are likewise created at startup with `CREATE TABLE IF NOT EXISTS` in both the fresh-schema
-and migration blocks — most recently `workflow_runs` (final workflow digest per assistant message,
+Older tables are created at startup with `CREATE TABLE IF NOT EXISTS` in `SCHEMA_SQL` (`db-schema.mjs`),
+for example `workflow_runs` (final workflow digest per assistant message,
 keyed on `response_message_id`, cascade-deleted with the conversation; see
-[Background tasks and workflow progress](#background-tasks-and-workflow-progress)).
+[Background tasks and workflow progress](#background-tasks-and-workflow-progress)); newer ones, such as
+`background_task_rows`, come from a migration only (see below).
 
 Statements that depend on these columns are prepared conditionally, so an older database keeps
 working with the corresponding feature inert rather than crashing at startup.
 
-**To Deploy New Migrations:**
-
-1. Create file `server/migrations/000N-description.mjs` (increment the number)
-2. Export an async `up()` function that receives the database connection
-3. Write SQL alterations:
-   ```javascript
-   export async function up(db) {
-     await db.exec(`ALTER TABLE some_table ADD COLUMN new_col TEXT;`);
-   }
-   ```
-4. Restart the relay; migration runs automatically
-5. Verify: check relay logs for `[migrations] Applying 000N-description`
+**Adding a migration:**
+
+1. Create `server/migrations/00NN-description.mjs` with the next number, exporting a synchronous
+   `migrateSomething(db)` that checks the schema (`sqlite_master`, `PRAGMA table_info`) and changes
+   only what is missing, plus a `migrate(dbPath)` and an `isMain` block for running it by hand
+   (`0018-background-task-rows.mjs` is a small example).
+2. Call it from `applySchema` after the previous one, inside `try`/`catch` with a
+   `migration 00NN failed; retrying on next boot` warning. It runs on a fresh database too, so
+   what it creates needs no entry in `SCHEMA_SQL`.
+3. Prepare statements that need the change conditionally, so a database the migration has not
+   reached keeps the feature inert instead of failing at startup.
 
 ## Files