@oar-sh/oar 0.9.20 → 0.9.22

package/server/relay-tools.md

@@ -42,6 +42,7 @@ This relay itself is listed with "self": true when its owner switched agent sess
 - `create_session` starts a session with any provider that `relay_info` lists: a local one in a folder ("cwd"), or provider "claude-cloud" with "repo" (a GitHub URL or owner/repo) and an optional "branch". The provider ids are the target relay's, as `relay_info` shows them; an id it does not know is refused with the list it has. A session started before a relay update can use providers the update added, without a restart. Without "mode" the new session gets your session's relay mode. At most 4 sessions you started may work at the same time; a fifth is refused until one finishes.
 - The first `create_session` on this relay shows the user an approval card, once per conversation. A session that an agent created cannot create sessions itself (one level only), unless the owner allowed it for that session: `list_sessions` and `read_session` then show "mayCreateSessions": true. Only the owner sets that.
 - Sessions you start here are grouped under this session in the user's sidebar. `list_sessions` lists in the sidebar's order (a group sorts by its newest session, head first) and shows the group as a "group" field (id, name, role); `read_session` adds the group's live members with their state. `create_session` takes "group" (a group id, or its name in any case, from `relay_info`'s "groups") to put the new session into an existing group instead, here or on a paired relay; an unknown group is refused with the groups listed and nothing is created, and the result carries the "group". Renaming and dissolving groups is the user's.
+- `list_sessions` and `read_session` show a session's worker process, while it has one, as "worker" (kind, buildId, stale); "stale": true means it runs older code than that relay, which replaces it by itself once the session is idle, so there is nothing to do about it.
 - `update_session` ("session" plus any of "model", "effort", "mode", "auto_compact_window", "title", "group", "thinking_enabled", "thinking_display", "cwd", "planOnly") changes another session's settings for its next turns without prompting it, here or on a paired relay, and answers the settings and "changed"; a group name that does not exist makes one, "none" takes the session out (a group the user made stays, even empty; one update_session made goes once empty), a new "cwd" restarts its CLI there (refused while it works), "auto_compact_window" 0 is the model default. The model is checked as for `send`. A failed call still lists in "changed" what it wrote before the failing step. A mode set this way lasts until the next `update_session` that names another mode; a `send` that names a mode runs only that turn in it, and one without "mode" leaves the session in its own mode.
 - "planOnly": true makes a plan-only session: agents can't take it out of plan mode. Set it only when the user asks; plan mode alone never sets it. `create_session` with "planOnly": true and no "mode" starts in plan; with another mode named it is refused and nothing is created. A target relay too old for planOnly creates the session without the lock and says so in "planOnlyWarning". `update_session` with "planOnly": true sets it on an existing session (with "mode": "plan" unless it is in plan already). While it is set, a `send` or `update_session` that names another mode is refused with 409, code "plan_only" ("This session is plan-only; agents can't change its mode. Clear planOnly first, or ask the user."); a `send` without "mode" runs in the session's saved mode. To clear it, pass "planOnly": false in the same `update_session` that names the new mode (`{"planOnly":false,"mode":"agent"}`); alone, or with "mode": "plan", it is ignored, and on a plan-only session the answer notes "planOnly unchanged: clear it in the same call as the new mode." Use `update_session` for all this, not the preferences route (it refuses an agent's mode change with 409 and any planOnly change with 403). `list_sessions` and `read_session` show "planOnly": true. In a plan-only conversation you count as a plan-mode caller, also in the one agent turn after "Approve plan": your `create_session` defaults to plan and your write actions ask the user first.
 - Only a session your conversation started may be updated freely; any other (the user's, another agent's, the one that started you) needs the user's approval card once per conversation and relay (refused: `REMOTE_RELAY_PERMISSION`); never your own conversation.

package/server/repositories/message-repository.mjs

@@ -361,6 +361,16 @@ export function createMessageRepository(db) {
           LIMIT ?
         `),
         countStatus:    db.prepare(`SELECT status, COUNT(*) as cnt FROM queue WHERE status IN ('pending','processing','parked') ${notHeldForUsageLimit()} GROUP BY status`),
+        // Stale recovery has nothing to look at while no row is processing.
+        hasProcessingRow: db.prepare(`SELECT 1 AS present FROM queue WHERE status = 'processing' LIMIT 1`),
+        // The earliest future retry time of a pending row (a backoff, a
+        // usage-limit hold): the relay wakes its queue then. A hold until the
+        // user resumes (year 9999) is no time.
+        nextPendingAttemptAt: db.prepare(`
+          SELECT MIN(next_attempt_at) AS due FROM queue
+          WHERE status = 'pending' AND next_attempt_at IS NOT NULL
+            AND next_attempt_at > ? AND next_attempt_at < '9999'
+        `),
         // Deferred host suspend: which conversations still hold live turns.
         listActiveQueueCountsByConversation: db.prepare(`
           SELECT q.conversation_id, COUNT(*) AS cnt, MAX(c.title) AS title
@@ -461,6 +471,29 @@ export function createMessageRepository(db) {
           WHERE status = 'processing'
             AND NULLIF(owner_sdk_session_id, '') = ?
         `),
+        // The worker recycle's quiet window (worker-recycle-service.mjs): the
+        // last time the session had a delivery or a turn end, as an ISO
+        // string, or NULL when the queue holds no row of it. Over the rows the
+        // session owns: a row is stamped with its owner at enqueue under
+        // session-worker routing and at the latest by its claim, and a
+        // conversation rebound to another session leaves its old rows with the
+        // session that ran them. The queue keeps no completion time
+        // (setDone clears processing_at), so a turn's end is its response
+        // message's timestamp; the claim and the heartbeat lease
+        // (owner_last_claimed_at) and the assignment stand for the delivery.
+        // Each column is COALESCEd: SQLite's multi-argument MAX() is NULL as
+        // soon as one argument is.
+        getOwnerLastActivityAt: db.prepare(`
+          SELECT MAX(NULLIF(MAX(
+            COALESCE(q.processing_at, ''),
+            COALESCE(q.owner_assigned_at, ''),
+            COALESCE(q.owner_last_claimed_at, ''),
+            COALESCE(m.timestamp, '')
+          ), '')) AS last_activity_at
+          FROM queue q
+          LEFT JOIN messages m ON m.id = q.response_message_id
+          WHERE NULLIF(q.owner_sdk_session_id, '') = ?
+        `),
         recoverProcessingRowKeepOwner: db.prepare(`
           UPDATE queue
           SET status = 'pending',

package/server/repositories/question-repository.mjs

@@ -1,12 +1,48 @@
 'use strict';
 
 import { createSubagentTimelineStatements } from './subagent-timeline-statements.mjs';
+import { hasTurnSeqColumn } from '../migrations/0038-turn-seq.mjs';
+
+const nextTurnSeqStatements = new WeakMap();
+
+/**
+ * The next number of a turn's shared order (migration 0038): one more than
+ * the highest turn_seq of its thoughts and tool lines together, 1 for a turn
+ * that has none. Call it inside the write transaction that inserts the row
+ * (BEGIN IMMEDIATE takes the write lock before this read), so two writers
+ * never get the same number.
+ */
+export function nextTurnSeq(db, queueMessageId) {
+    let statement = nextTurnSeqStatements.get(db);
+    if (!statement) {
+        statement = db.prepare(`
+          SELECT MAX(
+            COALESCE((SELECT MAX(turn_seq) FROM relay_activity WHERE queue_message_id = @id AND turn_seq IS NOT NULL), 0),
+            COALESCE((SELECT MAX(turn_seq) FROM relay_thought WHERE queue_message_id = @id AND turn_seq IS NOT NULL), 0)
+          ) AS max_seq
+        `);
+        nextTurnSeqStatements.set(db, statement);
+    }
+    return Math.max(0, Number(statement.get({ id: String(queueMessageId) })?.max_seq || 0)) + 1;
+}
 
 export function createQuestionRepository(db) {
     const subagentTimeline = createSubagentTimelineStatements(db);
     const runColumns = subagentTimeline.subagentRunSelectColumns;
     const runColumnsAs = (alias) => runColumns.split(', ').map((column) => `${alias}.${column}`).join(', ');
+    // Migration 0038 may have failed (it is retried next boot): without the
+    // column, rows are written without a number and read back without one,
+    // and every turn keeps the grouped layout.
+    const turnSeq = hasTurnSeqColumn(db, 'relay_activity') && hasTurnSeqColumn(db, 'relay_thought');
+    // The insert statements take turn_seq as their last value, which a caller
+    // may leave out (null); a database without the column drops it.
+    const fitValues = (statement, count) => ({
+        run: (...values) => statement.run(...values.slice(0, count), ...Array(Math.max(0, count - values.length)).fill(null)),
+    });
     return {
+        hasTurnSeq: turnSeq,
+        // The next turn_seq of a queue message, or null without the column.
+        nextTurnSeq: (queueMessageId) => (turnSeq ? nextTurnSeq(db, queueMessageId) : null),
         ...subagentTimeline,
         // relay questions
         insertQuestion: db.prepare(`INSERT INTO relay_questions (id, queue_id, conversation_id, message_id, relay_mode, prompt, choices, request, request_schema, status, answer, structured_answer, sdk_session_id, owner_worker_id, continuation_id, continuation_question_id, created_at, answered_at, expires_at, attempt_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, ?, ?, ?, ?, ?, NULL, ?, ?)`),
@@ -27,10 +63,14 @@ export function createQuestionRepository(db) {
         expireQuestions: db.prepare(`UPDATE relay_questions SET status = 'timed_out' WHERE status = 'pending' AND expires_at < ? RETURNING id, created_at`),
 
         // relay activity
-        insertActivity: db.prepare(`INSERT INTO relay_activity (queue_message_id, response_message_id, conversation_id, relay_mode, text, created_at, subagent_run_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`),
+        // (queue_message_id, response_message_id, conversation_id, relay_mode,
+        // text, created_at, subagent_run_id, metadata_json, turn_seq)
+        insertActivity: turnSeq
+            ? fitValues(db.prepare(`INSERT INTO relay_activity (queue_message_id, response_message_id, conversation_id, relay_mode, text, created_at, subagent_run_id, metadata_json, turn_seq) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`), 9)
+            : fitValues(db.prepare(`INSERT INTO relay_activity (queue_message_id, response_message_id, conversation_id, relay_mode, text, created_at, subagent_run_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`), 8),
         linkActivityToResponse: db.prepare(`UPDATE relay_activity SET response_message_id = ? WHERE queue_message_id = ? AND response_message_id IS NULL`),
-        listActivityByResponse: db.prepare(`SELECT text, subagent_run_id, metadata_json FROM relay_activity WHERE response_message_id = ? ORDER BY id ASC`),
-        listActivityByQueueMessage: db.prepare(`SELECT text, subagent_run_id, metadata_json FROM relay_activity WHERE queue_message_id = ? ORDER BY id ASC`),
+        listActivityByResponse: db.prepare(`SELECT text, subagent_run_id, metadata_json${turnSeq ? ', turn_seq' : ''} FROM relay_activity WHERE response_message_id = ? ORDER BY id ASC`),
+        listActivityByQueueMessage: db.prepare(`SELECT text, subagent_run_id, metadata_json${turnSeq ? ', turn_seq' : ''} FROM relay_activity WHERE queue_message_id = ? ORDER BY id ASC`),
         // When a queue row last produced output — its newest stream snapshot
         // (rows are rewritten in place and re-stamped per update) or activity
         // line. The live-turn picker compares rows by this, never by the
@@ -73,8 +113,12 @@ export function createQuestionRepository(db) {
 
         // relay thoughts (agent reasoning)
         getLastThoughtSeqByQueueMessage: db.prepare(`SELECT COALESCE(MAX(seq), 0) AS max_seq FROM relay_thought WHERE queue_message_id = ?`),
-        getThoughtByQueueAndReasoning: db.prepare(`SELECT seq FROM relay_thought WHERE queue_message_id = ? AND reasoning_id = ? LIMIT 1`),
-        insertThought: db.prepare(`INSERT INTO relay_thought (queue_message_id, response_message_id, conversation_id, relay_mode, reasoning_id, seq, text, done, created_at, subagent_run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        getThoughtByQueueAndReasoning: db.prepare(`SELECT seq${turnSeq ? ', turn_seq' : ''} FROM relay_thought WHERE queue_message_id = ? AND reasoning_id = ? LIMIT 1`),
+        // (queue_message_id, response_message_id, conversation_id, relay_mode,
+        // reasoning_id, seq, text, done, created_at, subagent_run_id, turn_seq)
+        insertThought: turnSeq
+            ? fitValues(db.prepare(`INSERT INTO relay_thought (queue_message_id, response_message_id, conversation_id, relay_mode, reasoning_id, seq, text, done, created_at, subagent_run_id, turn_seq) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`), 11)
+            : fitValues(db.prepare(`INSERT INTO relay_thought (queue_message_id, response_message_id, conversation_id, relay_mode, reasoning_id, seq, text, done, created_at, subagent_run_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`), 10),
         updateThoughtByQueueAndReasoning: db.prepare(`
           UPDATE relay_thought
           SET response_message_id = COALESCE(response_message_id, ?),
@@ -88,8 +132,8 @@ export function createQuestionRepository(db) {
             AND reasoning_id = ?
         `),
         linkThoughtsToResponse: db.prepare(`UPDATE relay_thought SET response_message_id = ? WHERE queue_message_id = ? AND response_message_id IS NULL`),
-        listThoughtsByResponse: db.prepare(`SELECT reasoning_id, seq, text, done, created_at, subagent_run_id FROM relay_thought WHERE response_message_id = ? ORDER BY seq ASC, id ASC`),
-        listThoughtsByQueueMessage: db.prepare(`SELECT reasoning_id, seq, text, done, created_at, subagent_run_id FROM relay_thought WHERE queue_message_id = ? ORDER BY seq ASC, id ASC`),
+        listThoughtsByResponse: db.prepare(`SELECT reasoning_id, seq, text, done, created_at, subagent_run_id${turnSeq ? ', turn_seq' : ''} FROM relay_thought WHERE response_message_id = ? ORDER BY seq ASC, id ASC`),
+        listThoughtsByQueueMessage: db.prepare(`SELECT reasoning_id, seq, text, done, created_at, subagent_run_id${turnSeq ? ', turn_seq' : ''} FROM relay_thought WHERE queue_message_id = ? ORDER BY seq ASC, id ASC`),
         deleteConvThoughts: db.prepare(`DELETE FROM relay_thought WHERE conversation_id = ?`),
 
         // subagent runs

package/server/repositories/relay-turn-rows.mjs

@@ -0,0 +1,56 @@
+// A turn's stored thought and tool-line rows as the browser receives them
+// (the message payload and the in-flight snapshot). Pure, so the payload
+// shape is tested without booting the relay (server-runtime.mjs uses these).
+
+export function sanitizeActivityText(value) {
+  const text = String(value || '').trim();
+  if (!text) return '';
+  return text.slice(0, 200);
+}
+
+// A row's place in its turn's order (migration 0038), or null: a row from
+// before it, or a database without the column.
+function rowTurnSeq(row) {
+  if (row?.turn_seq === null || row?.turn_seq === undefined) return null;
+  const value = Number(row.turn_seq);
+  return Number.isInteger(value) && value > 0 ? value : null;
+}
+
+export function mapRelayActivityRow(row) {
+  const text = sanitizeActivityText(row?.text);
+  if (!text) return null;
+  const subagentRunId = row?.subagent_run_id ? String(row.subagent_run_id).trim() : null;
+  // Structured rows (compaction boundaries) carry their payload alongside the
+  // prose so the transcript can promote them to a break row; junk JSON is
+  // simply dropped back to a prose-only entry.
+  let metadata = null;
+  if (row?.metadata_json) {
+    try {
+      const parsed = JSON.parse(String(row.metadata_json));
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) metadata = parsed;
+    } catch { metadata = null; }
+  }
+  // Only a numbered row says so: the payload of an unnumbered one is as before.
+  const turnSeq = rowTurnSeq(row);
+  return {
+    text,
+    subagentRunId: subagentRunId || null,
+    ...(metadata ? { metadata } : {}),
+    ...(turnSeq !== null ? { turnSeq } : {}),
+  };
+}
+
+export function mapRelayThoughtRow(row) {
+  const seq = Math.max(0, Math.trunc(Number(row?.seq || 0)));
+  const subagentRunId = row?.subagent_run_id ? String(row.subagent_run_id).trim() : null;
+  const turnSeq = rowTurnSeq(row);
+  return {
+    reasoningId: row?.reasoning_id ? String(row.reasoning_id) : null,
+    seq,
+    text: String(row?.text || ''),
+    done: Number(row?.done || 0) === 1,
+    timestamp: row?.created_at || null,
+    subagentRunId: subagentRunId || null,
+    ...(turnSeq !== null ? { turnSeq } : {}),
+  };
+}

package/server/repositories/session-repository.mjs

@@ -100,6 +100,25 @@ export function createSessionRepository(db) {
         getRuntimeSessionBySdkSessionId: db.prepare(`SELECT * FROM runtime_sessions WHERE sdk_session_id = ?`),
         getRuntimeSessionById: db.prepare(`SELECT * FROM runtime_sessions WHERE id = ?`),
         listRuntimeSessions: db.prepare(`SELECT rs.*, c.title AS conversation_title, c.updated_at AS conversation_updated_at FROM runtime_sessions rs LEFT JOIN conversations c ON c.id = rs.conversation_id ORDER BY rs.last_used_at DESC`),
+        // The session ids of archived conversations: the worker sweep at relay
+        // start stops what still runs for them. A runtime session id is unique
+        // (idx_runtime_sessions_sdk_session_id), but a conversation's own
+        // sdk_session_id is not: an id that a conversation in use (not
+        // archived, not deleted) names too is left out, so that
+        // conversation's worker is never stopped for an archived one.
+        listArchivedRuntimeSessionIds: db.prepare(`
+          SELECT DISTINCT rs.sdk_session_id AS sdk_session_id
+          FROM runtime_sessions rs
+          JOIN conversations c ON c.id = rs.conversation_id
+          WHERE c.archived = 1
+            AND NULLIF(rs.sdk_session_id, '') IS NOT NULL
+            AND NOT EXISTS (
+              SELECT 1 FROM conversations live_c
+              WHERE live_c.sdk_session_id = rs.sdk_session_id
+                AND COALESCE(live_c.archived, 0) = 0
+                AND live_c.status != 'deleted'
+            )
+        `),
         insertRuntimeSession: db.prepare(runtimeSessionsSupportProviders
           ? `INSERT INTO runtime_sessions (id, conversation_id, strategy, runtime_key, model, status, created_at, last_used_at, sdk_session_id, provider_type, provider_model) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)`
           : `INSERT INTO runtime_sessions (id, conversation_id, strategy, runtime_key, model, status, created_at, last_used_at, sdk_session_id) VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?)`),

package/server/routes/ask-user-routes.mjs

@@ -3,8 +3,8 @@
 import { createAskUserRoutingService } from '../services/ask-user-routing-service.mjs';
 import { admitRemoteRelayRequest, readRemoteRelayRequest } from '../services/remote-relay-inbound.mjs';
 import { REMOTE_RELAY_ERROR_CODES, isRemoteRelayApprovalQuestion } from '../../shared/remote-relay-contract.mjs';
-import { isRelayAskId, relayQuestionKind } from '../../shared/relay-asks.mjs';
-import { sendRelayAskError } from './relay-ask-routes.mjs';
+import { isPersonOnlyQuestion, isRelayAskId, relayQuestionKind } from '../../shared/relay-asks.mjs';
+import { askForPairedRelay, sendRelayAskError } from './relay-ask-routes.mjs';
 import { closedQuestionAnswer, questionAcceptsFreeText } from '../../shared/question-answer-rule.mjs';
 import {
   extractRequestedSchema,
@@ -56,6 +56,23 @@ function isRemoteRelayApprovalRow(row) {
   return envelope ? isRemoteRelayApprovalQuestion(envelope) : false;
 }
 
+/**
+ * A stored question row that is a Claude session's Safety check card: an
+ * ask Claude Code marks as person-only. Only the user answers it, never an
+ * agent of this relay (the loopback client counts as remote) or another.
+ */
+function isPersonOnlyRow(row) {
+  const envelope = parseRowJson(row?.request);
+  return envelope ? isPersonOnlyQuestion(envelope.context) : false;
+}
+
+const PERSON_ONLY_ANSWER_REFUSAL = 'This card is the user\'s to answer: Claude Code marks the call as person-only, so no agent may answer it.';
+
+/** A card no agent may list or answer. */
+function isUserOnlyRow(row) {
+  return isRemoteRelayApprovalRow(row) || isPersonOnlyRow(row);
+}
+
 /**
  * The choices of a stored card that takes no typed text (approval and
  * permission cards, and a card with choices that stored no flag, as the
@@ -167,13 +184,17 @@ export function registerAskUserRoutes(app, deps) {
     const conversationId = req.query.conversationId ? String(req.query.conversationId) : null;
     const status = String(req.query.status || 'pending').trim() || 'pending';
     let rows = stmts.listQuestions.all(status, conversationId, conversationId);
-    if (fromRemoteRelay(req)) rows = rows.filter((row) => !isRemoteRelayApprovalRow(row));
+    if (fromRemoteRelay(req)) rows = rows.filter((row) => !isUserOnlyRow(row));
     const questions = rows.map(formatQuestionRow).map((question) => ({ ...question, kind: relayQuestionKind(question) }));
     // Questions that don't block, on request (read_session's pendingQuestions):
     // the cards' own readers take only what a turn waits on.
     if (String(req.query.includeAsks || '') === '1' && relayAskService?.isAvailable?.() && status === 'pending') {
       const asks = conversationId ? relayAskService.listOf(conversationId) : relayAskService.listHere();
-      questions.push(...asks.filter((ask) => !ask.relayId && ask.status === 'pending' && (!conversationId || ask.conversationId === conversationId)));
+      // A paired relay's read_session never learns the asking turn's queue id.
+      const shown = fromRemoteRelay(req) ? askForPairedRelay : (ask) => ask;
+      questions.push(...asks
+        .filter((ask) => !ask.relayId && ask.status === 'pending' && (!conversationId || ask.conversationId === conversationId))
+        .map(shown));
     }
     res.json({ questions });
   });
@@ -181,7 +202,8 @@ export function registerAskUserRoutes(app, deps) {
   app.get('/api/relay-question/:id', auth, (req, res) => {
     if (isRelayAskId(req.params.id)) {
       const ask = relayAskService?.get?.(req.params.id) || null;
-      return ask ? res.json({ question: ask }) : res.status(404).json({ error: 'Not found' });
+      if (!ask) return res.status(404).json({ error: 'Not found' });
+      return res.json({ question: fromRemoteRelay(req) ? askForPairedRelay(ask) : ask });
     }
     const row = stmts.getQuestion.get(req.params.id);
     if (!row || (isRemoteRelayApprovalRow(row) && fromRemoteRelay(req))) {
@@ -343,6 +365,10 @@ export function registerAskUserRoutes(app, deps) {
       console.warn(`[${ts()}] QUESTION  reject id=${id.slice(0, 8)} reason=remote-relay-approval-from-remote`);
       return res.status(403).json({ error: 'Only this relay\'s user can answer a remote relay approval' });
     }
+    if (isPersonOnlyRow(row) && fromRemoteRelay(req)) {
+      console.warn(`[${ts()}] QUESTION  reject id=${id.slice(0, 8)} reason=person-only-from-agent`);
+      return res.status(403).json({ error: PERSON_ONLY_ANSWER_REFUSAL, code: REMOTE_RELAY_ERROR_CODES.forbidden });
+    }
     if (row.status !== 'pending') return res.status(409).json({ error: `Question already ${row.status}` });
 
     const schema = parseQuestionRequest(row.request_schema);
@@ -418,6 +444,9 @@ export function registerAskUserRoutes(app, deps) {
     if (isRemoteRelayApprovalRow(row) && fromRemoteRelay(req)) {
       return res.status(403).json({ error: 'Only this relay\'s user can answer a remote relay approval' });
     }
+    if (isPersonOnlyRow(row) && fromRemoteRelay(req)) {
+      return res.status(403).json({ error: PERSON_ONLY_ANSWER_REFUSAL, code: REMOTE_RELAY_ERROR_CODES.forbidden });
+    }
     if (row.status !== 'pending') return res.json({ ok: true, question: formatQuestionRow(row) });
 
     const result = stmts.timeoutQuestion.run(row.id);

package/server/routes/claude-cloud-routes.mjs

@@ -6,6 +6,9 @@
 //                                     environment, account, login state
 //   POST /api/settings/claude-cloud   { enabled?, defaultModel?, environmentId? }
 //   POST /api/claude-cloud-session    the worker's binding report
+//   GET  /api/claude-cloud-session    `?conversationId=` (or the sdk session
+//                                     id) → the stored binding a starting
+//                                     worker attaches to
 //   GET  /api/claude-cloud/repos      the repositories New Chat may suggest
 //                                     (`?refresh=1` reads them afresh)
 //   GET  /api/claude-cloud/branches   `?repo=<owner/name or URL>` → its branches
@@ -77,6 +80,22 @@ export function registerClaudeCloudRoutes(app, deps = {}) {
       if (!result.ok) return res.status(result.statusCode || 400).json({ error: result.error });
       return res.json({ ok: true, cloud: result.cloud });
     });
+
+    // GET /api/claude-cloud-session?conversationId=<id> — a starting Claude
+    // Cloud worker asks which cloud session it is bound to and from which
+    // sequence to read on, so it opens the event stream before any delivery
+    // (a relaunched worker follows the turns the session starts by itself
+    // from its start). The id may be the conversation id or the sdk session
+    // id. `{ ok, sessionId, lastSequence }`, `sessionId: null` when there is
+    // no cloud session; 404 only for an unknown conversation.
+    app.get('/api/claude-cloud-session', auth, (req, res) => {
+      touchCli();
+      const raw = req.query?.conversationId ?? req.query?.sdkSessionId;
+      const id = Array.isArray(raw) ? raw[0] : raw;
+      const result = claudeCloudSessionService.describeStoredBinding(typeof id === 'string' ? id : '');
+      if (!result.ok) return res.status(result.statusCode || 400).json({ error: result.error });
+      return res.json({ ok: true, sessionId: result.sessionId, lastSequence: result.lastSequence });
+    });
   }
 
   if (claudeCloudLoginStatus) {

package/server/routes/messages-routes.mjs

@@ -45,6 +45,7 @@ import { DEFAULT_CLAUDE_REASONING_EFFORTS } from '../services/provider-reasoning
 import { claudeBaseModelId, claudeLongContextModelId } from '../../shared/model-id.mjs';
 import { sanitizeSubagentRunId } from '../../shared/subagent-run-id.mjs';
 import { normalizeBackgroundTaskDigest } from '../../shared/worker-runtime/background-task-digest.mjs';
+import { normalizeBuildId } from '../../shared/build-id.mjs';
 import {
   DEFAULT_TASK_STALL_MINUTES,
   TASK_OUTPUT_LIMITS,
@@ -112,7 +113,9 @@ const OPAQUE_RESPONSE_TEXT_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-
 const OPAQUE_RESPONSE_RECOVERY_WAIT_MS = 600_000;
 const OPAQUE_RESPONSE_RECOVERY_POLL_MS = 250;
 const STRANDED_SESSION_PRIME_COOLDOWN_MS = 10_000;
-const STRANDED_SESSION_HEARTBEAT_FRESH_MS = 15_000;
+// An idle worker beats every 30 s (shared/worker-runtime/worker-keepalive.mjs):
+// its last beat may be that old and still prove it alive.
+export const STRANDED_SESSION_HEARTBEAT_FRESH_MS = 45_000;
 // Hold finalization after a relay question is answered so the SDK has time to fire the next
 // onUserInputRequest (multi-step ask_user). Without this, the transcript is used prematurely and
 // the queue row is marked done while additional questions are still pending.
@@ -1201,6 +1204,12 @@ export async function dequeuePendingMessageForWorkerLoop({
   workerKind = null,
   onBillingFence = null,
   claudeApiClaimCheck = null,
+  // () → true while the replacement fence (services/worker-replacement.mjs)
+  // is up for the requesting process. The caller asks it before calling; it
+  // is asked again before every claim, since ensureWorker and a transient
+  // error's backoff both wait, and the worker recycle can raise the fence
+  // meanwhile.
+  isReplacementFenced = null,
 } = {}) {
   const requesterSid = normalizeSessionWorkerId(requesterSessionId);
   const routingWithWorker = routingEnabled && requesterSid;
@@ -1275,6 +1284,18 @@ export async function dequeuePendingMessageForWorkerLoop({
 
   let attempt = 0;
   while (attempt <= retryLimit) {
+    // The process asking is being replaced: no row is claimed for it, the
+    // same answer as the caller's own fence check gives.
+    if (routingWithWorker && typeof isReplacementFenced === 'function' && isReplacementFenced() === true) {
+      return {
+        message: null,
+        blockedReason: 'worker-replacement',
+        worker: supervisor?.getWorkerState?.(requesterSid) || null,
+        lifecycle: supervisor?.getLifecycleState?.(requesterSid) || null,
+        fallbackRestart: null,
+        attempts: attempt,
+      };
+    }
     const currentIso = String(nowIso || '').trim() || new Date().toISOString();
     try {
       const message = dequeuePendingMessage({
@@ -2065,6 +2086,9 @@ export function registerMessagesRoutes(app, deps) {
     // killTmuxSessionImpl). Tests must inject these instead of relying on the
     // host OS, so the suite behaves identically on Windows and POSIX.
     sessionWorkerStopOverrides = null,
+    // The replacement fence (services/worker-replacement.mjs): a worker
+    // process the recycle is replacing is handed no work by /api/pending.
+    workerReplacementFence = null,
     resolveSessionStateRoot,
     fetchUsageSummary = null,
     planUsageService = null,
@@ -6245,7 +6269,10 @@ export function registerMessagesRoutes(app, deps) {
           // Whether a billing swap may replace the worker now, and why not.
           || (stored.releasable ?? null) !== (steering.releasable ?? null)
           || (stored.releaseHold || null) !== (steering.releaseHold || null)
-          || (stored.backgroundTaskCount || 0) !== (steering.backgroundTaskCount || 0);
+          || (stored.backgroundTaskCount || 0) !== (steering.backgroundTaskCount || 0)
+          // Whether the worker's CLI child still runs: the worker recycle
+          // waits for it to be gone, so a flip must be stored.
+          || (stored.cliAlive ?? null) !== (steering.cliAlive ?? null);
         if (workerForSteering && changed) {
           sessionWorkerRegistry?.upsertWorker?.({ ...workerForSteering, steering });
           // Pushed rather than left for the clients' status poll: the
@@ -6263,6 +6290,16 @@ export function registerMessagesRoutes(app, deps) {
           sessionWorkerRegistry?.upsertWorker?.({ ...workerForKind, kind: heartbeatKind });
         }
       }
+      // The build id of the code the worker started on, recorded the same way:
+      // only when it says one and the registry has another, so quiet
+      // heartbeats stay write-free.
+      const heartbeatBuildId = normalizeBuildId(req.body?.buildId);
+      if (heartbeatBuildId) {
+        const workerForBuild = sessionWorkerRegistry?.getWorker?.(requesterSessionId) || null;
+        if (workerForBuild && workerForBuild.buildId !== heartbeatBuildId) {
+          sessionWorkerRegistry?.upsertWorker?.({ ...workerForBuild, buildId: heartbeatBuildId });
+        }
+      }
       sessionWorkerSupervisor?.noteSessionHeartbeat?.(requesterSessionId);
       // The worker's digest of its live background-task ids against the set
       // held for it (keyed as the worker posts, by its session id). They
@@ -7009,6 +7046,24 @@ export function registerMessagesRoutes(app, deps) {
           restartOrchestrator: relayRestartOrchestrator?.getState?.() || null,
         });
       }
+      // The process asking is being replaced (the worker recycle): no work,
+      // as for a killed session, so no turn starts on the pid being stopped.
+      // Unlike the killed marker, the fence outlives the marker's grace and
+      // every clearRestartSchedule; the new worker has another pid and takes
+      // what waited meanwhile.
+      if (workerReplacementFence?.isHeld?.(requesterSessionId, requester?.pid) === true) {
+        return res.json({
+          message: null,
+          routing: {
+            enabled: true,
+            requesterSessionId,
+            blockedReason: 'worker-replacement',
+            lifecycle: sessionWorkerSupervisor?.getLifecycleState?.(requesterSessionId) || null,
+            fallbackRestart: null,
+          },
+          restartOrchestrator: relayRestartOrchestrator?.getState?.() || null,
+        });
+      }
       sessionWorkerSupervisor?.noteSessionHeartbeat?.(requesterSessionId);
     }
     if (runtimeState.relayPaused) return res.json({ message: null, paused: true });
@@ -7103,6 +7158,8 @@ export function registerMessagesRoutes(app, deps) {
         workerKind: httpPendingWorkerKind(requesterSessionId),
         claudeApiClaimCheck,
         onBillingFence: onClaudeBillingFence,
+        // The fence check above, asked again before every claim.
+        isReplacementFenced: () => workerReplacementFence?.isHeld?.(requesterSessionId, requester?.pid) === true,
         telemetry: (payload = {}) => {
           if (!sessionWorkerRoutingEnabled) return;
           emitSessionWorkerTelemetry(payload.event, {
@@ -7323,6 +7380,7 @@ export function registerMessagesRoutes(app, deps) {
                 workerKind: httpPendingWorkerKind(requesterSessionId),
                 claudeApiClaimCheck,
                 onBillingFence: onClaudeBillingFence,
+                isReplacementFenced: () => workerReplacementFence?.isHeld?.(requesterSessionId, requester?.pid) === true,
               });
               if (recoveryDequeue?.message) {
                 msg = recoveryDequeue.message;
@@ -9123,16 +9181,28 @@ export function registerMessagesRoutes(app, deps) {
     const responseMessageId = q?.response_message_id || null;
     const normalizedSubagentRunId = subagentRunId ? String(subagentRunId).trim() : null;
     const normalizedMetadata = sanitizeActivityMetadata(metadata);
-    const activityRow = stmts.insertActivity.run(
-      messageId,
-      responseMessageId,
-      conversationId,
-      normalizeRelayMode(mode) || DEFAULT_RELAY_MODE,
-      activityText,
-      new Date().toISOString(),
-      normalizedSubagentRunId,
-      normalizedMetadata ? JSON.stringify(normalizedMetadata) : null,
-    );
+    // The row's place in the turn's order (thoughts and tool lines share
+    // it): numbered and written in one IMMEDIATE transaction, so two writers
+    // on the same turn never get the same number.
+    let turnSeq = null;
+    const insertActivityRow = () => {
+      turnSeq = stmts.nextTurnSeq?.(messageId) ?? null;
+      return stmts.insertActivity.run(
+        messageId,
+        responseMessageId,
+        conversationId,
+        normalizeRelayMode(mode) || DEFAULT_RELAY_MODE,
+        activityText,
+        new Date().toISOString(),
+        normalizedSubagentRunId,
+        normalizedMetadata ? JSON.stringify(normalizedMetadata) : null,
+        turnSeq,
+      );
+    };
+    const insertActivityTx = typeof db?.transaction === 'function' ? db.transaction(insertActivityRow) : null;
+    const activityRow = typeof insertActivityTx?.immediate === 'function'
+      ? insertActivityTx.immediate()
+      : insertActivityRow();
     if (normalizedSubagentRunId) {
       // The lane keeps the capped line; the timeline copy keeps what came in.
       mirrorSubagentFrame({
@@ -9150,6 +9220,7 @@ export function registerMessagesRoutes(app, deps) {
       timestamp: new Date().toISOString(),
       subagentRunId: normalizedSubagentRunId || undefined,
       ...(normalizedMetadata ? { metadata: normalizedMetadata } : {}),
+      ...(turnSeq !== null ? { turnSeq } : {}),
     });
     res.json({ ok: true });
   });
@@ -9307,6 +9378,9 @@ export function registerMessagesRoutes(app, deps) {
     const relayMode = normalizeRelayMode(mode) || DEFAULT_RELAY_MODE;
     const normalizedReasoningId = String(reasoningId || '').trim() || null;
     let seq = null;
+    // The thought's place in the turn's order: given on its first write and
+    // kept by every update, so a thought sits where its first chunk arrived.
+    let turnSeq = null;
     const shouldPersistThought = !!done || !!normalizedReasoningId;
     if (shouldPersistThought) {
       const isThoughtSeqConstraintError = (error) => {
@@ -9341,12 +9415,13 @@ export function registerMessagesRoutes(app, deps) {
                 messageId,
                 normalizedReasoningId,
               );
-              return existingSeq;
+              return { seq: existingSeq, turnSeq: existingThought.turn_seq == null ? null : Number(existingThought.turn_seq) };
             }
           }
           const row = stmts.getLastThoughtSeqByQueueMessage?.get(messageId);
           const maxSeq = Math.max(0, Number(row?.max_seq || 0));
           const nextSeq = maxSeq + 1;
+          const nextTurn = stmts.nextTurnSeq?.(messageId) ?? null;
           stmts.insertThought?.run(
             messageId,
             responseMessageId,
@@ -9358,8 +9433,9 @@ export function registerMessagesRoutes(app, deps) {
             done ? 1 : 0,
             now,
             normalizedSubagentRunId,
+            nextTurn,
           );
-          return nextSeq;
+          return { seq: nextSeq, turnSeq: nextTurn };
         });
         const runInsertThought = typeof insertThoughtTx?.immediate === 'function'
           ? insertThoughtTx.immediate.bind(insertThoughtTx)
@@ -9367,7 +9443,7 @@ export function registerMessagesRoutes(app, deps) {
         const maxRetries = 4;
         for (let attempt = 1; attempt <= maxRetries; attempt += 1) {
           try {
-            seq = runInsertThought();
+            ({ seq, turnSeq } = runInsertThought());
             break;
           } catch (error) {
             if (error?.code === 'THOUGHT_CONVERSATION_MISMATCH') {
@@ -9402,6 +9478,7 @@ export function registerMessagesRoutes(app, deps) {
       seq,
       timestamp: now,
       subagentRunId: normalizedSubagentRunId || undefined,
+      ...(turnSeq !== null ? { turnSeq } : {}),
     });
     res.json({ ok: true, seq });
   });

package/server/routes/relay-ask-routes.mjs

@@ -151,6 +151,16 @@ export function inboxItemOfPlanBoard(board, session, { forRemote = false } = {})
   };
 }
 
+/**
+ * An ask as a paired relay gets it: without `queueId`, the queue row of the
+ * turn that asked here, which means nothing there.
+ */
+export function askForPairedRelay(ask) {
+  if (!ask || typeof ask !== 'object') return ask;
+  const { queueId, ...rest } = ask;
+  return rest;
+}
+
 /** One Inbox item of an ask (relay-ask-service.mjs shape). */
 export function inboxItemOfAsk(ask) {
   const {
@@ -322,7 +332,7 @@ export function registerRelayAskRoutes(app, deps) {
     if (!relayAskService?.isAvailable?.()) return res.json({ available: false, asks: [], pending: 0 });
     const conversationId = toText(req.query.conversationId);
     const asks = conversationId
-      ? relayAskService.listOf(conversationId).filter((ask) => !ask.relayId && ask.conversationId === conversationId)
+      ? relayAskService.listIn(conversationId).filter((ask) => !ask.relayId && ask.conversationId === conversationId)
       : relayAskService.listHere();
     res.json({ available: true, asks, pending: relayAskService.pendingCount() });
   });
@@ -411,7 +421,7 @@ export function registerRelayAskRoutes(app, deps) {
         detail: body.detail,
         urgency: body.urgency,
       });
-      res.json({ ok: true, ask });
+      res.json({ ok: true, ask: askForPairedRelay(ask) });
     } catch (error) {
       sendRelayAskError(res, error, 'The ask');
     }
@@ -433,7 +443,7 @@ export function registerRelayAskRoutes(app, deps) {
     const caller = admitPairedRelay(req, res);
     if (!caller || !available(res)) return;
     try {
-      res.json({ ok: true, ask: relayAskService.withdraw(toText(asObject(req.body).id), { byRelayId: caller.relayId }) });
+      res.json({ ok: true, ask: askForPairedRelay(relayAskService.withdraw(toText(asObject(req.body).id), { byRelayId: caller.relayId })) });
     } catch (error) {
       sendRelayAskError(res, error, 'The withdrawal');
     }
@@ -447,7 +457,7 @@ export function registerRelayAskRoutes(app, deps) {
     const caller = admitPairedRelay(req, res, body.via);
     if (!caller || !available(res)) return;
     try {
-      res.json({ ok: true, ask: relayAskService.answer(toText(body.id), { answer: String(body.answer ?? ''), choice: String(body.choice ?? ''), via: caller.name }) });
+      res.json({ ok: true, ask: askForPairedRelay(relayAskService.answer(toText(body.id), { answer: String(body.answer ?? ''), choice: String(body.choice ?? ''), via: caller.name })) });
     } catch (error) {
       sendRelayAskError(res, error, 'The answer');
     }
@@ -458,7 +468,7 @@ export function registerRelayAskRoutes(app, deps) {
     const caller = admitPairedRelay(req, res, body.via);
     if (!caller || !available(res)) return;
     try {
-      res.json({ ok: true, ask: relayAskService.dismiss(toText(body.id), { via: caller.name }) });
+      res.json({ ok: true, ask: askForPairedRelay(relayAskService.dismiss(toText(body.id), { via: caller.name })) });
     } catch (error) {
       sendRelayAskError(res, error, 'The dismissal');
     }