@oar-sh/oar 0.9.10 → 0.9.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.10",
+  "version": "0.9.11",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -50,20 +50,20 @@
     "test:e2e:raw": "node ./node_modules/@playwright/test/cli.js test --config tests/playwright.config.mjs"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.292",
-    "@cursor/sdk": "^1.0.36",
-    "@github/copilot-sdk": "^1.0.17",
-    "better-sqlite3": "^12.10.0",
-    "express": "^4.18.2",
-    "qrcode-terminal": "^0.12.0",
-    "socket.io": "^4.7.5",
-    "uuid": "^14.0.0",
-    "web-push": "^3.6.7",
-    "ws": "^8.18.0",
-    "zod": "^4.4.3"
+    "@anthropic-ai/claude-agent-sdk": "0.3.292",
+    "@cursor/sdk": "1.0.36",
+    "@github/copilot-sdk": "1.0.17",
+    "better-sqlite3": "12.11.1",
+    "express": "4.22.3",
+    "qrcode-terminal": "0.12.0",
+    "socket.io": "4.8.3",
+    "uuid": "14.0.1",
+    "web-push": "3.6.7",
+    "ws": "8.21.3",
+    "zod": "4.4.3"
   },
   "optionalDependencies": {
-    "tty-console": "^1.0.4"
+    "tty-console": "1.0.4"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",

package/server/README.md

@@ -212,12 +212,18 @@ at confirm time). While a suspend is queued every connected client shows a
 banner with the blockers or the countdown and a **Cancel** button, the menu entry
 reads **💤 Suspend pending…**, and reopening the modal offers to cancel. A relay
 restart drops the queued suspend; a push notification (event **Host suspend**)
-reports both the actual suspend and such a drop. A queued **🌄 Restart web relay**
+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.
 
 API: `GET /api/host/suspend` (state plus current blockers), `POST /api/host/suspend`,
 `POST /api/host/suspend/cancel`, and `POST /api/relay/shutdown/cancel`
-(localhost-only). Set `OAR_HOST_SUSPEND_DRY_RUN=1` to log instead of sleeping.
+(token only, like the restart itself). Set `OAR_HOST_SUSPEND_DRY_RUN=1` to log instead of sleeping;
+`OAR_BOOT_REPORTING_WINDOW_MS` changes the 45 seconds (0 to 600000; test relays
+pin `0`, which switches the wait off; a negative value is ignored); an override in effect is
+logged at start.
 
 You can also hide the **💤 Suspend host** action from **⚙️ Settings** with the
 **Show Suspend host action** checkbox. This only controls the menu entry; the
@@ -371,6 +377,41 @@ that started them. The live task set is posted to `POST /api/background-tasks` (
 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.
 
+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
+truth, and the relay asks:
+
+- **Digest and resync.** A worker's heartbeat carries `backgroundTasks: { count, digest }`, a digest
+  of its sorted task ids (`shared/worker-runtime/background-task-digest.mjs`). When it differs from
+  the set held for that worker (a restart, or a lost post either way round), the heartbeat answer
+  says `resyncBackgroundTasks: true` and the worker posts its full set with `resync: true`; the
+  request repeats on every beat until the two agree. A task restored this way keeps its start time
+  and is not announced as started again. Every post of a set carries `order: { epoch, seq }` (the
+  worker process and its count of set posts): two posts can overtake each other on the way, and the
+  relay drops one that is older than the newest it applied from that process, or that comes from a
+  process other than the one whose heartbeat came last for the session. A drop is logged and
+  answered `stale: true` with a `reason`; a worker told so for its newest set asks for a heartbeat,
+  on which the relay asks for the set again. `epoch` only names the process and is never compared
+  as a time. A task that ended only because a set did not list it comes back, without a second
+  start, when a later set lists it, unless a settle notice or its run's status has confirmed the
+  end meanwhile. A worker that sends no digest (Cursor, Grok, Claude Cloud, or a worker on older
+  code) has no opinion and is never asked.
+- **Placeholder.** A live Claude worker on older code cannot answer, but its heartbeat says whether
+  background work holds its process (`steering.autoCompactWindow.backgroundWork`). While this
+  runtime has not heard from that worker about its tasks, the session reads `background_only` with
+  one task "background work, details not reported since the relay restarted (Kill session in its ⋯
+  menu ends it)", the panel shows the
+  same row without a Stop button, and a host suspend waits. It is derived on read
+  (`services/background-work-view.mjs`), raises no event, and goes when the set arrives, the flag
+  goes false or the worker is gone.
+- **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.
+- **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
+  is left out of the session state, `all_idle` and the suspend blockers.
+
 Tasks of type `local_workflow` carry an extra `workflowProgress` digest, because the SDK exposes no
 workflow-progress surface — the worker reads it off disk:
 
@@ -517,7 +558,7 @@ conversation that speaks the usual worker contracts (WebSocket link, heartbeat,
 crash guard) but runs no agent: it sends the user's messages to the cloud session and follows the
 session's event stream (`claude-cloud-session-process.mjs`, `claude-cloud-event-normalizer.mjs`).
 The user-facing description, including what the provider does with the Claude CLI's login, is in
-the [README](../README.md#claude-cloud); the tracker is
+the [providers guide](../docs/providers.md#claude-cloud); the tracker is
 [docs/feature-tracker/claude-cloud.md](../docs/feature-tracker/claude-cloud.md).
 
 ### The cloud client and the login
@@ -845,7 +886,12 @@ posts it from `task_notification`), the sub-agent run statuses and the activity,
 timeline posts (the activity clock). A task that leaves the set without word ends after 5 s with
 its run's status, else `completed` with `statusReported: false`; an exit code is read from the task
 summary when it names one (the SDK has no field for it). Memory only: a restart forgets the recently
-finished tasks and starts the clock at boot.
+finished tasks and starts the clock at boot. Running tasks come back when the workers send their
+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.
 
 `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;
@@ -871,18 +917,19 @@ socket event (the whole active list after every change).
 ### Folded agent exchanges
 
 A prompt another agent sent the session (a paired relay's, or one of this relay's own: a user row
-with `origin`) and the session's reply to it fold into one row, `note from <relay> · <session> ·
-replied` (`working…`, `failed`, `stopped`, `no reply yet`), which opens to both as they render
-otherwise. Presentation only (`agent-exchange-fold-view.mjs` decides, `syncAgentExchangeFolds` in
+with `origin`) folds into one row, `note from <relay> · <session> · answered below` (`working…`,
+`failed`, `stopped`, `no reply yet`), which opens to the prompt as it renders otherwise.
+Presentation only (`agent-exchange-fold-view.mjs` decides, `syncAgentExchangeFolds` in
 `conversation-view.js` applies it as one more idempotent pass after every render and update, beside
 the separator and steering passes); the transcript data is unchanged. Nothing addressed to the user
-folds away: not a turn a message was steered into (the reply `absorbed`, or another message folded
-into or stopped with it), not an agent prompt that was itself steered into a turn, not an answer on
-a continuation row, and, while the page lives, not a turn that had an open question, approval card
-or plan board, or ran while a message of the user's waited. A folded exchange shows open while its
-turn is `working…` and closes by itself once it is replied, failed or stopped
-(`agentExchangeFoldOpen`); the user's own toggle, kept by prompt id, always wins over that, and a
-jump to a message inside (search, pins, image parent) opens it.
+folds away: the fold covers the agent's prompt alone. The session's reply to it can hold a line for
+the user, so the reply, the live bubble of the running turn and the turn's question, approval and
+plan cards always show, as for a message of the user's own; they are read for the row's status
+only. One prompt is left unfolded: an agent's prompt that was itself steered into a running turn,
+which renders as part of that turn's flow. A folded prompt shows open while its turn is `working…`
+and closes by itself once it is replied, failed or stopped (`agentExchangeFoldOpen`); the user's
+own toggle, kept by prompt id, always wins over that, and a jump to the prompt (search, pins, image
+parent) opens it.
 
 ## Image conversations (OpenAI BYOK)
 
@@ -911,6 +958,24 @@ images, calling the OpenAI Images API directly rather than going through a CLI w
 - The control appears on message hover; already-hidden messages keep their label visible so the state
   is never silently lost.
 - `POST /api/shared/:token/presence` tracks shared-viewer presence, surfaced as a watcher count.
+  `sharedPresenceMaxPerConversation` and `sharedPresenceMaxGlobal` cap how many viewers that count
+  tracks; they do not limit who can read a link.
+- A revoked or renewed token answers a plain 404 on every shared route, the `/shared/:token` page
+  included, exactly like a token that never existed. An open shared page stops at its next poll.
+- Settings → Sharing lists the active shares (`GET /api/shares`) with **Copy link**, **Renew link**
+  and **Stop sharing**, and each share's access log. Renewing adds a token to the share's lineage
+  (`conversation_shares.lineage_id`, migration 0016) and revokes the old one, so the log, keyed to
+  the lineage, carries over. Stopping a share or deleting the conversation deletes its log; nothing
+  else prunes it.
+- The access log (`conversation_share_opens`) has one row per open, not per poll: the shared page's
+  first fetch carries `open=1` and counts unless the same viewer opened it in the last 10 s; a
+  fetch without the flag counts only when that viewer has not fetched the share for 30 minutes
+  (a page back from the background, a script). A row keeps the time, the IP address (unless
+  **Store viewer IP addresses** is off), the user agent, the country from `cf-ipcountry` (only when
+  the request came through a proxy the `trustProxy` setting trusts) and a viewer key: an HMAC of
+  address and user agent under a per-relay secret, which counts distinct viewers without the
+  address. The address is the one Express derives through `trustProxy`; a forwarded header from an
+  untrusted peer is ignored.
 
 ## Pinned messages
 
@@ -1219,14 +1284,15 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | POST | `/api/stream` | (CLI) Push in-flight assistant text stream for current pending message |
 | POST | `/api/relay/pause` | Pause dequeueing and drop currently queued messages |
 | POST | `/api/relay/resume` | Resume dequeueing after pause |
-| POST | `/api/relay/shutdown` | Queue a localhost-only authenticated relay shutdown or self-restart |
+| POST | `/api/relay/shutdown` | Queue an authenticated relay shutdown or self-restart |
 | 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/:id/timeout` | (CLI/UI) Mark a relay question timed out |
-| POST | `/api/heartbeat` | (CLI) Keep CLI status alive |
+| 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 |
+| GET | `/api/about` | The About OAR modal: `version`, `commit` (the checkout's HEAD read from `.git`, else a `gitHead` stamp in package.json, else `null`), `startedAt` and `uptimeSeconds` of the relay process; `providers[]` (enabled ones only: `cliVersion` from the CLI probe cache, never a new probe, `sdkVersion` from node_modules, `state` `online`/`offline` for the relay CLI that runs Copilot's extension engine and OpenAI, `online`/`idle` with `runningWorkers` for the others); `stats` (conversations, messages, turns = replies, `turnsByProvider`, `firstConversationAt`); `usage` (only what is stored: Copilot premium requests, Cursor and Grok tokens and cost, Claude Cloud cost); `relay` (`dbBytes` = database + WAL, `runningWorkers`); `update` (latest version only while the opt-in check is on). The totals are read in rowid ranges of 10 000 messages with the event loop free in between, and kept for 60 s |
 | GET | `/api/models` | Live/cached model catalog used by the UI picker |
 | POST | `/api/models/snapshot` | (CLI/relay) Publish discovered model snapshot |
 | POST | `/api/conversation/:id/refresh-history` | Re-import an existing conversation's history through the local Copilot SDK |
@@ -1256,9 +1322,14 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | POST | `/api/conversation/:conversationId/subagent/:subagentRunId/cancel` | Request cancellation of one subagent run (unsupported by the Claude runtime) |
 | 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` | Create or update the conversation's read-only share token |
-| GET | `/api/shared/:token` | Read-only shared conversation view (hidden messages filtered out) |
-| POST | `/api/shared/:token/presence` | Report shared-viewer presence for the watcher count |
+| 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` |
+| POST | `/api/conversation/:id/share/renew` | A new token for the active share; the old one answers 404 from then on and the access log carries over. Sends `share_renewed`; 404 without an active share |
+| DELETE | `/api/conversation/:id/share` | Stop sharing: revokes every token of the conversation and deletes its access log → `{ revokedAt, revokedCount, opensDeleted }`. Sends `share_revoked`; 404 without an active share |
+| GET | `/api/shares` | Every active share: `{ shares: [{ conversationId, title, archived, token, shareUrl, path, sharedSince, renewedAt, lastOpenedAt, openCount, viewerCount }], storeViewerIp, accessLog }` |
+| GET | `/api/conversation/:id/share/opens` | The active share's access log, newest first: `?limit=<n>` (default 200, max 1000) → `{ opens: [{ openedAt, ip, country, userAgent, viewer }], total, limit }` |
+| GET/POST | `/api/settings/shares` | `{ storeViewerIp }`: whether new access log entries (and the status events of shared reads) keep the viewer's IP address; on by default. A change sends `share_settings_changed` |
+| GET | `/api/shared/:token` | (No auth) Read-only shared conversation view (hidden messages filtered out). `?open=1` marks the page's first fetch, which the access log counts as an open |
+| POST | `/api/shared/:token/presence` | (No auth) Report shared-viewer presence for the watcher count |
 | POST | `/api/openai/images/generate` | Generate images for an OpenAI Image conversation |
 | POST | `/api/image-operations/:operationId/execute` | Execute a queued image generation/edit operation |
 | GET | `/api/generated-image/:conversationId/:messageId/:imageId/content` | Stream a generated image blob |
@@ -1275,7 +1346,7 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 | 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? }` (Claude worker, from `task_notification`) |
+| 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) |
 | 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 |
@@ -1283,7 +1354,8 @@ Queue metrics include `parkedCount` for turns deferred behind restart/rebind gat
 
 ### Manual relay shutdown / self-restart
 
-- `POST /api/relay/shutdown` is localhost-only even when the relay is otherwise reachable on the network.
+- `POST /api/relay/shutdown`, `POST /api/relay/shutdown/cancel` and `POST /api/queue/empty` need the
+  token and nothing else: the browser app calls them from a phone, over a tunnel and over the LAN.
 - The request body accepts:
   - `reason` (optional string)
   - `requestedBy` (optional string)
@@ -1671,7 +1743,8 @@ service).
 | `cloudflaredTunnel.token` | — | Tunnel token from the router panel (never logged) |
 | `cloudflaredTunnel.binary` | `cloudflared` | Path or command name of the `cloudflared` you installed (OAR ships none); defaults to `cloudflared` on `PATH`. Without one the tunnel stays off and the status says how to install it |
 | `cloudflaredTunnel.extraArgs` | `[]` | Extra arguments appended to `cloudflared tunnel run` |
-| `tunnelMarkerHeaders` | `[]` | Extra edge-injected header names that mark tunnel traffic for the session-worker path guard |
+| `tunnelMarkerHeaders` | `[]` | Extra edge-injected header names that mark tunnel traffic; merged with `COPILOT_TUNNEL_MARKER_HEADERS` and `cf-ray` (an empty list does not switch the env value off). A request carrying one is never "from this machine" (session-worker path guard, image-operation run, sign-in lockout exemption) |
+| `allowedOrigins` | `[]` | Extra browser origins the Socket.IO channel accepts besides the relay's own origin |
 
 ### SDK auto-detection behavior
 

package/server/claude-worker/claude-session-process.mjs

@@ -43,6 +43,7 @@ import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
 import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import { buildRelayStopFailure } from '../../shared/relay-stop-failure.mjs';
 import { createTurnLiveness, resolveTurnStallWindows } from '../../shared/worker-runtime/turn-liveness.mjs';
+import { createKeptPosts } from '../../shared/worker-runtime/kept-posts.mjs';
 import {
   ANSWERED_ELSEWHERE_KIND,
   DELIVERY_ANSWERED_ELSEWHERE_TEXT,
@@ -546,6 +547,10 @@ export function createClaudeSessionRunner({
   // the socket link: a hold withdraws the relay's readiness, and its end
   // re-arms it at once so a held message steers into the resumed turn.
   onDeliveryReadinessChange = () => {},
+  // The relay turned this worker's newest task set away (`stale`): the
+  // worker asks for a heartbeat, on which the relay learns which process
+  // holds the session and asks for the set again.
+  onBackgroundTaskSetStale = () => {},
   // Whether CLI processes carry the relay's `remote_relay` tool
   // (shared/remote-relay-tool-core.mjs). Default: ask the relay.
   remoteRelayToolGate = null,
@@ -604,6 +609,34 @@ export function createClaudeSessionRunner({
   // id → terminalError for settling rows the worker gave up posting; reported
   // in the heartbeat's `settleFailed` until the relay confirms it failed them.
   const settleFailedTerminals = new Map();
+  // Settle notices of background tasks whose post failed (the relay was
+  // away): sent again after the next heartbeat it answers.
+  // Every post of the task set carries its place in this worker's order:
+  // two posts can overtake each other on the way, and the relay applies the
+  // newer one only. `epoch` tells this process from one before it.
+  const taskSetEpoch = Date.now();
+  let taskSetSeq = 0;
+  const nextTaskSetOrder = () => ({ epoch: taskSetEpoch, seq: ++taskSetSeq });
+  let taskSetStaleNotedAt = 0;
+  /**
+   * The relay's answer to a set post. `stale` for the newest one means the
+   * relay holds no current set of this worker; an older one was simply
+   * overtaken. At most one extra heartbeat per ten seconds: the periodic
+   * beat repeats the request anyway.
+   */
+  function noteTaskSetAnswer(answer, order) {
+    if (answer?.stale !== true || order.seq !== taskSetSeq) return;
+    dbg('the relay dropped the newest background task set', answer.reason || '');
+    if (Date.now() - taskSetStaleNotedAt < 10_000) return;
+    taskSetStaleNotedAt = Date.now();
+    try { onBackgroundTaskSetStale(); } catch {}
+  }
+  const postTaskSet = (body) => {
+    const order = nextTaskSetOrder();
+    return api('POST', '/api/background-tasks', { conversationId: sdkSessionId, ...body, order })
+      .then((answer) => noteTaskSetAnswer(answer, order));
+  };
+  const keptTaskSettles = createKeptPosts({ api, dbg: (...args) => dbg('background task settle:', ...args) });
   // Row id → the latest in-flight /api/queue-consumed POST touching it.
   const consumedMarkChains = new Map();
 
@@ -1694,10 +1727,19 @@ export function createClaudeSessionRunner({
    * which renders it as the composer's background-tasks panel. Membership
    * changes post immediately; chatty progress updates are trailing-edge
    * throttled. Advisory: failures must never disturb the stream consumer.
+   *
+   * `resync`: the relay asked for the set again on a heartbeat, because its
+   * own set for this worker differs (it restarted, or a post was lost). The
+   * same set, flagged, and "no tasks" is an answer too. Returns the post.
    */
-  function publishBackgroundTasks({ throttled = false } = {}) {
+  function publishBackgroundTasks({ throttled = false, resync = false } = {}) {
     const processRef = proc;
-    if (!processRef) return;
+    if (!processRef) {
+      if (!resync) return Promise.resolve();
+      return postTaskSet({ tasks: [], resync: true }).catch((error) => {
+        dbg('background task resync failed', error?.message || String(error));
+      });
+    }
     const send = () => {
       processRef.taskPublishTimer = null;
       const tasks = [...processRef.liveTasks.entries()].map(([taskId, task]) => {
@@ -1729,7 +1771,7 @@ export function createClaudeSessionRunner({
           ...(task.workflowProgress ? { workflowProgress: task.workflowProgress } : {}),
         };
       });
-      api('POST', '/api/background-tasks', { conversationId: sdkSessionId, tasks }).catch((error) => {
+      return postTaskSet({ tasks, ...(resync ? { resync: true } : {}) }).catch((error) => {
         dbg('background task publish failed', error?.message || String(error));
       });
     };
@@ -1738,12 +1780,12 @@ export function createClaudeSessionRunner({
         clearTimeout(processRef.taskPublishTimer);
         processRef.taskPublishTimer = null;
       }
-      send();
-      return;
+      return send();
     }
-    if (processRef.taskPublishTimer) return;
+    if (processRef.taskPublishTimer) return Promise.resolve();
     processRef.taskPublishTimer = setTimeout(send, 2_000);
     processRef.taskPublishTimer.unref?.();
+    return Promise.resolve();
   }
 
   // ---------------------------------------------------------------------------
@@ -2441,7 +2483,12 @@ export function createClaudeSessionRunner({
       // capture a settling workflow's final digest for the transcript card
       // (the notification then refines the status when it lands).
       for (const [taskId, task] of previous) {
-        if (!proc.liveTasks.has(taskId)) bufferSettledWorkflowRun(taskId, task);
+        if (proc.liveTasks.has(taskId)) continue;
+        bufferSettledWorkflowRun(taskId, task);
+        // What the task was, for its settle notice: the row is gone by the
+        // time the notification says how it ended.
+        proc.departedTasks.set(taskId, task);
+        if (proc.departedTasks.size > 50) proc.departedTasks.delete(proc.departedTasks.keys().next().value);
       }
       syncWorkflowPoller(proc);
       publishBackgroundTasks();
@@ -2491,14 +2538,24 @@ export function createClaudeSessionRunner({
       // this session (the live set only says it is gone). Ambient tasks are
       // not activity. Advisory: a failed post never disturbs the stream.
       if (taskId && sdkMessage.ambient !== true) {
-        api('POST', '/api/background-task-settled', {
+        // A task that was in the published set is described too, so that a
+        // relay which no longer knows it (it restarted meanwhile) can still
+        // tell its watchers the end. A failed post is kept and sent again.
+        const published = proc.liveTasks.get(taskId) || proc.departedTasks.get(taskId) || null;
+        proc.departedTasks.delete(taskId);
+        void keptTaskSettles.post('/api/background-task-settled', {
           conversationId: sdkSessionId,
           taskId,
-          toolUseId: String(sdkMessage.tool_use_id || '').trim() || null,
+          toolUseId: String(sdkMessage.tool_use_id || published?.toolUseId || '').trim() || null,
           status: String(sdkMessage.status || '').trim() || 'completed',
           summary: String(sdkMessage.summary || '').trim().slice(0, 500) || null,
           ...(sdkMessage.reason ? { reason: String(sdkMessage.reason).slice(0, 40) } : {}),
-        }).catch((error) => dbg('background task settle publish failed', error?.message || String(error)));
+          ...(published?.description ? {
+            description: String(published.description).slice(0, 500),
+            taskType: String(published.taskType || ''),
+            startedAt: published.startedAt || null,
+          } : {}),
+        });
       }
       // A settled session-level task means the CLI is about to dequeue a
       // continuation turn — the process must not idle out under it. The SDK
@@ -3249,7 +3306,7 @@ export function createClaudeSessionRunner({
     if (processRef.liveTasks.size) {
       processRef.liveTasks = new Map();
       if (wasCurrent) {
-        api('POST', '/api/background-tasks', { conversationId: sdkSessionId, tasks: [] }).catch(() => {});
+        postTaskSet({ tasks: [] }).catch(() => {});
       }
     }
     // Steers pushed into a turn the user stopped: if the Stop fell back to
@@ -3331,6 +3388,9 @@ export function createClaudeSessionRunner({
       permissionMode: permissionModeForRelayMode(relayMode),
       liveTasks: new Map(),
       knownTasks: new Set(),
+      // taskId → the row of a task that left the live set, until its
+      // notification arrives.
+      departedTasks: new Map(),
       // taskId → { runId, labels, digestJson } for live local_workflow tasks;
       // pruned by syncWorkflowPoller when a task leaves the live set.
       workflowStates: new Map(),
@@ -4034,6 +4094,21 @@ export function createClaudeSessionRunner({
     return false;
   }
 
+  /** The ids of the live background tasks, for the heartbeat's digest. */
+  function backgroundTaskIds() {
+    return proc ? [...proc.liveTasks.keys()] : [];
+  }
+
+  /** The relay asked for the task set again (heartbeat answer). */
+  function resyncBackgroundTasks() {
+    return publishBackgroundTasks({ resync: true });
+  }
+
+  /** The relay answered a heartbeat: settle notices kept for it go out. */
+  function flushKeptTaskSettles() {
+    return keptTaskSettles.flush();
+  }
+
   return {
     handlePendingPayload,
     canAcceptSteering,
@@ -4046,6 +4121,9 @@ export function createClaudeSessionRunner({
     isTurnActive,
     stopBackgroundTask,
     stopBackgroundTaskByToolUseId,
+    backgroundTaskIds,
+    resyncBackgroundTasks,
+    flushKeptTaskSettles,
     shutdown,
     // Test seams / observability.
     _getProcess: () => proc,

package/server/claude-worker/claude-session-worker.mjs

@@ -119,6 +119,7 @@ async function main() {
     // A readiness flip is a hold starting or ending (question card,
     // compaction, a turn-opening delivery): the steering snapshot changed
     // with it, so it goes out now rather than on the next 10 s heartbeat.
+    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
     onDeliveryReadinessChange: (ready) => {
       linkBridge.onDeliveryReadinessChange(ready);
       heartbeat?.requestPulse();
@@ -147,6 +148,12 @@ async function main() {
     // Consumed rows the runner could not fail itself; the relay fails them.
     getSettleFailed: () => turnRunner.getSettleFailed(),
     onSettleFailedHandled: (ids) => turnRunner.acknowledgeSettleFailed(ids),
+    // The relay holds the task set in memory only: the digest of the live
+    // task ids rides every beat, and a relay that is out of step (it
+    // restarted, a post was lost) asks for the set again.
+    getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
+    onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
+    onAnswered: () => turnRunner.flushKeptTaskSettles(),
   });
 
   const wsLink = createWorkerWebSocketLink({
@@ -164,7 +171,8 @@ async function main() {
     // even between deliveries — a delivery drawn into it is only handed back.
     getDeliveryHeld: () => turnRunner.isDeliveryHeld(),
     // A relay that just (re)started knows nothing of this worker until it
-    // heartbeats; the composer's steering snapshot rides that beat.
+    // heartbeats; the composer's steering snapshot rides that beat, and so
+    // does the digest that makes the relay ask for the background tasks.
     onServerHello: () => heartbeat.requestPulse(),
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,

package/server/copilot-worker/copilot-sdk-session-process.mjs

@@ -461,6 +461,10 @@ export function createCopilotSdkSessionRunner({
   // heartbeat snapshot, and a 10 s wait would often outlast the window in
   // which the runtime still holds the message (live check 2026-09-25).
   onCancellableChange = () => {},
+  // The relay turned this worker's newest task set away (`stale`): the
+  // worker asks for a heartbeat, on which the relay learns which process
+  // holds the session and asks for the set again.
+  onBackgroundTaskSetStale = () => {},
   dbg = () => {},
 } = {}) {
   let client = null;
@@ -628,7 +632,15 @@ export function createCopilotSdkSessionRunner({
   let taskRefreshQueued = 0;
   let lastTaskRefreshAt = 0;
   let taskPublishTimer = null;
+  // The last set the relay took, as JSON, and the one on its way to it.
   let lastPublishedTasksSignature = '';
+  let inFlightTasksSignature = null;
+  let taskPublishSeq = 0;
+  // Every post of the set carries its place in this worker's order
+  // (`epoch` tells this process from one before it): posts can overtake
+  // each other on the way, and the relay applies the newer one only.
+  const taskSetEpoch = Date.now();
+  let taskSetStaleNotedAt = 0;
   // Cap expiry is bounded: a task whose cancel the runtime refuses (or that
   // keeps failing) this many times is abandoned — dropped from the live set so
   // it stops pinning the runtime — rather than held forever.
@@ -1570,27 +1582,77 @@ export function createCopilotSdkSessionRunner({
    * semantics, the same route the Claude worker publishes on). Set changes
    * publish at once; enrichment-only changes (a tool call, tokens) ride a
    * trailing throttle. Advisory: a failed post never disturbs events.
+   *
+   * A set equal to the last one the relay TOOK (or to the one on its way)
+   * is not sent again: the signature is recorded when the post succeeds, so
+   * a failed post is retried by the next publish instead of being
+   * remembered as sent.
+   * `resync`: the relay asked for the set again on a heartbeat (it
+   * restarted, or a post was lost); that goes out whatever the signature
+   * says, flagged. Returns the post.
    */
-  function publishBackgroundTasks({ immediate = false } = {}) {
+  function publishBackgroundTasks({ immediate = false, resync = false } = {}) {
     const run = () => {
       if (taskPublishTimer) {
         clearTimeout(taskPublishTimer);
         taskPublishTimer = null;
       }
-      const tasks = sessionRpc.tasks ? registryCards() : shellTrackerCards();
+      const tasks = currentTaskCards();
       const signature = JSON.stringify(tasks);
-      if (signature === lastPublishedTasksSignature) return;
-      lastPublishedTasksSignature = signature;
-      api('POST', '/api/background-tasks', { conversationId: sdkSessionId, tasks })
-        .catch((error) => dbg('background task publish failed', error?.message || String(error)));
+      const unchanged = inFlightTasksSignature === null
+        ? signature === lastPublishedTasksSignature
+        : signature === inFlightTasksSignature;
+      if (!resync && unchanged) return Promise.resolve();
+      const seq = ++taskPublishSeq;
+      inFlightTasksSignature = signature;
+      return api('POST', '/api/background-tasks', {
+        conversationId: sdkSessionId,
+        tasks,
+        order: { epoch: taskSetEpoch, seq },
+        ...(resync ? { resync: true } : {}),
+      })
+        .then((answer) => {
+          // Only the newest post says what the relay holds now.
+          if (seq !== taskPublishSeq) return;
+          inFlightTasksSignature = null;
+          if (answer?.stale === true) {
+            // Turned away, not taken: nothing is recorded as sent, and a
+            // heartbeat is asked for (at most one per ten seconds; the
+            // periodic beat repeats the relay's request anyway).
+            dbg('the relay dropped the newest background task set', answer.reason || '');
+            if (Date.now() - taskSetStaleNotedAt < 10_000) return;
+            taskSetStaleNotedAt = Date.now();
+            try { onBackgroundTaskSetStale(); } catch {}
+            return;
+          }
+          lastPublishedTasksSignature = signature;
+        })
+        .catch((error) => {
+          // Not taken: the signature stays at what the relay last took, so
+          // the next publish of this set is sent, not skipped.
+          if (seq === taskPublishSeq) inFlightTasksSignature = null;
+          dbg('background task publish failed', error?.message || String(error));
+        });
     };
-    if (immediate || !(taskPublishThrottleMs > 0)) {
-      run();
-      return;
-    }
-    if (taskPublishTimer) return;
+    if (resync || immediate || !(taskPublishThrottleMs > 0)) return run();
+    if (taskPublishTimer) return Promise.resolve();
     taskPublishTimer = setTimeout(run, taskPublishThrottleMs);
     taskPublishTimer.unref?.();
+    return Promise.resolve();
+  }
+
+  function currentTaskCards() {
+    return sessionRpc.tasks ? registryCards() : shellTrackerCards();
+  }
+
+  /** The ids of the live background tasks, for the heartbeat's digest. */
+  function backgroundTaskIds() {
+    return currentTaskCards().map((task) => task.taskId);
+  }
+
+  /** The relay asked for the task set again (heartbeat answer). */
+  function resyncBackgroundTasks() {
+    return publishBackgroundTasks({ resync: true });
   }
 
   // ------------------------------------------------------- background tasks --
@@ -4700,6 +4762,8 @@ export function createCopilotSdkSessionRunner({
     steeringState,
     getSettleFailed,
     acknowledgeSettleFailed,
+    backgroundTaskIds,
+    resyncBackgroundTasks,
     cancelPushedMessage,
     // The task panel's per-card Stop (`rpc.tasks.cancel`); also what a
     // subagent lane's Stop tries — the runtime tracks sync agents in the same
@@ -4726,6 +4790,7 @@ export function createCopilotSdkSessionRunner({
       ? new Promise((resolve) => { setTimeout(resolve, taskRefreshMs + 5); }).then(() => taskRefreshChain)
       : taskRefreshChain),
     // Test seams / observability.
+    _publishBackgroundTasks: publishBackgroundTasks,
     _getState: () => ({
       hasClient: !!client,
       hasSession: !!session,

package/server/copilot-worker/copilot-sdk-session-worker.mjs

@@ -121,6 +121,7 @@ async function main() {
     // A message became (or stopped being) cancellable: report it now rather
     // than on the next 10 s heartbeat (coalesced by the controller).
     onCancellableChange: () => heartbeat?.requestPulse(),
+    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
     canHandBackHeldDelivery: () => linkBridge.canHandBackHeldDelivery(),
     dbg,
   });
@@ -144,6 +145,11 @@ async function main() {
     getSteeringState: () => turnRunner.steeringState(),
     getSettleFailed: () => turnRunner.getSettleFailed(),
     onSettleFailedHandled: (ids) => turnRunner.acknowledgeSettleFailed(ids),
+    // The relay holds the task set in memory only: the digest of the live
+    // task ids rides every beat, and a relay that is out of step (it
+    // restarted, a post was lost) asks for the set again.
+    getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
+    onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
   });
 
   const wsLink = createWorkerWebSocketLink({