@oar-sh/oar 0.9.13 → 0.9.15

package/server/relay-tools.md

@@ -2,51 +2,54 @@
 
 For any user-facing question or clarification, use the ask_user tool so the web relay can render question cards and buttons. Never ask questions in plain assistant text.
 
-When using ask_user, ALWAYS include a `choices` array with 2-6 answer options so the web relay can render clickable buttons. Example:
+When using ask_user, ALWAYS include a `choices` array with 2-8 answer options so the web relay can render clickable buttons. The relay keeps the first 8 choices and drops the rest. Example:
 ```json
 {
-  "question": "<QUIZ_QUESTION_TEXT>",
-  "choices": ["<CHOICE_A>", "<CHOICE_B>", "<CHOICE_C>", "<CHOICE_D>"]
+  "question": "The login test fails because the session cookie expires too early. How should I fix it?",
+  "choices": ["Fix the cookie lifetime in the code", "Update the test to match the code", "Leave it and only report it"]
 }
 ```
-At runtime, inject the question and choices from a random item in your quiz pool.
 Only omit choices when the question genuinely requires freeform text input (e.g., "What is your name?").
 
 When the user may pick several of the choices (they are not mutually exclusive), set `"multi_select": true` if your ask_user tool offers that field; otherwise begin the question with "Select all that apply:". Either way, expect an answer that lists several choices separated by ", ".
 
 In autopilot, still call ask_user when user input is truly blocking, because the relay bridge can surface the question even when the direct SDK question hook is bypassed.
 
-For relay restarts in extension-managed mode, require explicit user permission first, then use the authenticated localhost API `POST /api/relay/shutdown`. Do not restart by killing processes or using respawn scripts.
+For a relay restart or shutdown, require explicit user permission first, then use the authenticated localhost API `POST /api/relay/shutdown`. Do not restart by killing processes or using respawn scripts.
 
-Note: shutdown is queued and only completes when the current turn finishes, so it is pointless to wait for it to interrupt an active turn.
+Note: the request is queued. The relay only shuts down or restarts once no turn is running on it, your own included (after a maximum wait it asks the user), and it holds new messages until then, so end your turn instead of waiting for the restart. The answer names the sessions it waits for (`waitingFor`), the messages it holds (`held`) and the background tasks (`backgroundTasks`, each with whether it `survives`): tell the user.
 
 Use `restart: true` in the request body when the user wants a real relay restart rather than a plain shutdown. Example request body: `{ "reason": "manual-restart", "requestedBy": "localhost-api", "restart": true }`.
 
 Never pass `immediate` in that request body: it restarts without waiting for the running turns, which only the user may decide, with Restart now in the web UI.
 
+To go on with your work once the relay is back, subscribe first with `remote_relay` `{"action":"subscribe","events":["relay_restarted"],"once":true}` (no sessions needed), then request the restart: your own timers and scheduled jobs may not survive it. A restart requested while a turn that `relay_restarted` woke is still running does not wake that conversation (a `once` subscription ends with it).
+
 ## Preview servers
 
-Publish a local web server or a static directory on a public preview URL so the user can open it from any device, or list/close existing previews. Use this whenever the user wants to see, try, or share something with a web UI — never ask them to open localhost or forward a port. For a dev server: call this FIRST with {action:"create", port} to get the basePath, then start the server configured to serve under that basePath (Vite --base, Next basePath, Express mount prefix); the proxy forwards X-Forwarded-Prefix but does not rewrite bodies, so root-absolute asset paths will not work. For plain files or a build output: pass {action:"create", dir} instead and the relay serves the directory itself — no dev server needed. Always tell the user the returned URL and that the link is public: anyone who has it can reach the app without logging in. Publishing the same port or directory again in this conversation returns the same link. Previews never expire and survive a relay restart (a port preview until the machine reboots); close them with {action:"close"} when the user is done.
+Publish a local web server or a static directory on a public preview URL so the user can open it from any device, or list/close this conversation's previews. Use this whenever the user wants to see, try, or share something with a web UI — never ask them to open localhost or forward a port. For a dev server: call this FIRST with {action:"create", port} to get the basePath, then start the server configured to serve under that basePath (Vite --base, Next basePath, Express mount prefix); the proxy forwards X-Forwarded-Prefix but does not rewrite bodies, so root-absolute asset paths will not work. For plain files or a build output: pass {action:"create", dir} instead and the relay serves the directory itself — no dev server needed. Always tell the user the returned URL and that the link is public: anyone who has it can reach the app without logging in. Publishing the same port or directory again in this conversation returns the same link. Previews never expire and survive a relay restart (a port preview until the machine reboots); close them with {action:"close"} when the user is done.
 
-If you have a `preview` tool, use it. Otherwise use the authenticated localhost API (same auth as `POST /api/relay/shutdown`): `POST /api/previews` with `{ "conversationId": "<conv>", "port": 5173, "label": "web app" }` (or `"dir": "./dist"` instead of the port) publishes, `GET /api/previews` lists, `DELETE /api/previews/:token` closes the link without touching the dev server behind it. A 503 with `details` means the preview lane is disabled or misconfigured — surface those details, they are the operator's fix. See `docs/preview-servers.md`.
+If you have a `preview` tool, use it. Otherwise use the authenticated localhost API (same auth as `POST /api/relay/shutdown`): `POST /api/previews` with `{ "conversationId": "<conv>", "port": 5173, "label": "web app" }` (or `"dir": "./dist"` instead of the port) publishes, `GET /api/previews?conversationId=<conv>` lists this conversation's previews, `DELETE /api/previews/:token?conversationId=<conv>` closes one of them without touching the dev server behind it. Always pass the conversation: you may list and close only this conversation's previews, another conversation's is refused (403), and the relay-wide list is the user's (Settings → Previews). A 503 with `details` means the preview lane is disabled or misconfigured — surface those details, they are the operator's fix. See `docs/preview-servers.md`.
 
 ## Remote relays
 
 If you have a `remote_relay` tool, it works with sessions on OAR relays: the other relays this relay is paired with and, when its owner allows it, this relay itself. It lists and reads sessions, prompts a session, starts a new one and waits for its reply. Start with `{"action":"list_relays"}`.
 
-A paired relay stays locked until the user mentions it in this conversation (`@name` or its plain name); a locked relay refuses everything except `list_relays`, so ask the user to mention it rather than retrying. Use a paired relay only when the user asks for work there or mentions it.
+A paired relay stays locked until the user mentions it in this conversation (`@name` or its plain name) or an agent on that relay writes to this conversation; a locked relay refuses everything except `list_relays`, so ask the user to mention it rather than retrying. Use a paired relay only when the user asks for work there or mentions it, or to answer an agent on it that wrote to this conversation.
 
 This relay itself is listed with "self": true when its owner switched agent sessions on, and is addressed by its name or as "this"; it needs no mention. Use it to hand parts of your task to other sessions:
 
 - `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". 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).
 - 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. Agents only read groups, the user arranges them.
-- A "model" for `create_session` or `send` must be an id `relay_info` lists for the provider (Claude also takes "opus", "sonnet", "haiku"). An unknown id is refused with the close matches ("unknown model 'gpt-5-4' for Copilot; did you mean 'gpt-5.4'?") and nothing is created or sent: pick from the list instead of guessing. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
+- A "model" for `create_session` or `send` must be an id `relay_info` lists for the provider (Claude also takes "opus", "sonnet", "haiku"). An unknown id is refused with the close matches and the valid ids (`Unknown model 'gpt-5-4' for Copilot on relay "…"; did you mean 'gpt-5.4'? Valid ids: … Nothing was sent.`), and nothing is created or sent: pick from the list instead of guessing. If the answer has a "modelNote" saying the model could not be checked, the relay had no model list yet.
 - A new session knows nothing of this conversation: write a self-contained prompt. A Claude Cloud session works on a fresh clone in a sandbox at Anthropic, so name the branch it should work on and push.
 - Follow each session with `wait` (the message id comes back from `create_session` and `send`) and `read_session`; "wait_seconds" is limited to the maximum set on the relay (default 600).
 - Sessions run on the relay owner's accounts and cost their usage: start only what the task needs.
 - `read_task_output` ("session", "task_id" from `read_session`'s tasks, optional "lines") reads the end of a background shell or Monitor task's output, also for an hour after it ended: the last lines, minutes since its last output, and pass/fail counts for a test run. Credentials are scrubbed out.
 
-On this relay and on a paired one, `subscribe` wakes you when something happens in the sessions you watch, instead of polling them. Leave "events" out unless you need more: the default (question_asked, error, turn_end, subagent_finished, task_failed, stalled, all_idle) wakes you for questions, errors, replies, finished sub-agents, failed tasks (a non-zero exit included), stalls and all_idle, but not for each shell command that ended well. To get those too, pass that list plus "task_finished" (and "task_started" for the starts); each one costs you a turn, so do it only if you must follow every command.
+On this relay and on a paired one, `subscribe` ("sessions": ids, or ["all"]) wakes you when something happens in the sessions you watch, instead of polling them. Leave "events" out unless you need more: the default (question_asked, error, turn_end, subagent_finished, task_failed, stalled, all_idle) wakes you for questions, errors, replies, finished sub-agents, failed tasks (a non-zero exit included), stalls and all_idle, but not for each shell command that ended well. To get those too, pass that list plus "task_finished" (and "task_started" for the starts); each one costs you a turn, so do it only if you must follow every command. "relay_restarted" (this relay only, never in the default) wakes you when the relay runs again after a restart, with who requested it and why; named alone it needs no sessions.
+
+The first `subscribe` of a conversation on a relay, and any to "all", shows the user an approval card. `unsubscribe` ends one ("subscription_id" from `subscribe` or `list_subscriptions`, or "all"), `list_subscriptions` lists this conversation's subscriptions (or another's, with "watcher"), and `transfer_subscriptions` ("from": a conversation id) moves another conversation's subscriptions to this one after the user approves. `usage` shows what each provider plan of a relay has left and whether a Claude usage limit has paused turns there: check it before you start work that costs. `stop` stops a session's running turn and `archive` archives a session. The `remote_relay` tool's own description is the full reference for every action and field.
 
 Write actions may first wait for the user's approval. If a result lists `pendingQuestions`, the other agent is waiting for an answer: ask the user (unless they told you to decide), then pass it on with `answer_question`. Always tell the user which relay and session you worked on.

package/server/repositories/message-repository.mjs

@@ -18,6 +18,25 @@ export function createMessageRepository(db) {
     const notHeldForUsageLimit = (alias = '') => (queueHasUsageLimitPause
         ? `AND NOT (${alias}usage_limit_pause IS NOT NULL AND ${alias}status = 'pending' AND ${alias}next_attempt_at IS NOT NULL AND ${alias}next_attempt_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`
         : '');
+    // When a processing row is due for the stale sweep; one rule for the
+    // listings and the requeue, so the UPDATE can never take a row the
+    // listing did not. Inactivity is measured from the last heartbeat, the
+    // ceiling (@ceilingBefore, NULL = no limit) from the later of the turn's
+    // start and its last answered question, and a turn waiting on an
+    // unanswered question is never due. The comments at the statements say why.
+    const staleProcessingSql = `(
+              (
+                COALESCE(owner_last_claimed_at, processing_at, timestamp) < @inactiveBefore
+                OR (
+                  @ceilingBefore IS NOT NULL
+                  AND MAX(
+                    COALESCE(processing_at, timestamp),
+                    COALESCE((SELECT MAX(answered_at) FROM relay_questions WHERE queue_id = queue.id), '')
+                  ) < @ceilingBefore
+                )
+              )
+              AND id NOT IN (SELECT queue_id FROM relay_questions WHERE status = 'pending')
+            )`;
     const messageColumns = new Set(db.prepare(`PRAGMA table_info(messages)`).all().map((column) => column.name));
     const messagesHaveSourceId = messageColumns.has('source_message_id');
     const messagesHaveResendOf = messageColumns.has('resend_of_message_id');
@@ -369,18 +388,13 @@ export function createMessageRepository(db) {
           FROM queue
           WHERE status = 'processing'
             AND COALESCE(kind, '') != 'continuation'
-            AND (
-              COALESCE(owner_last_claimed_at, processing_at, timestamp) < @inactiveBefore
-              OR (
-                @ceilingBefore IS NOT NULL
-                AND MAX(
-                  COALESCE(processing_at, timestamp),
-                  COALESCE((SELECT MAX(answered_at) FROM relay_questions WHERE queue_id = queue.id), '')
-                ) < @ceilingBefore
-              )
-            )
-            AND id NOT IN (SELECT queue_id FROM relay_questions WHERE status = 'pending')
+            AND ${staleProcessingSql}
         `),
+        // Requeues one row listRecoverableProcessing returned, so the caller
+        // knows exactly which rows it requeued and announces only those. The
+        // sweep runs synchronously, so nothing changes between listing and
+        // requeue; re-checking the same rule here is a safeguard that keeps
+        // this statement from ever taking a row the listing would not.
         recoverProcessingBefore: db.prepare(`
           UPDATE queue
           SET status = 'pending',
@@ -390,14 +404,11 @@ export function createMessageRepository(db) {
               owner_lease_expires_at = NULL,
               owner_last_claimed_at = NULL,
               retry_count = retry_count + 1
-          WHERE status = 'processing'
+          WHERE id = @id
+            AND status = 'processing'
             AND COALESCE(kind, '') != 'continuation'
             AND consumed_at IS NULL
-            AND (
-              COALESCE(owner_last_claimed_at, processing_at, timestamp) < @inactiveBefore
-              OR (@ceilingBefore IS NOT NULL AND COALESCE(processing_at, timestamp) < @ceilingBefore)
-            )
-            AND id NOT IN (SELECT queue_id FROM relay_questions WHERE status = 'pending')
+            AND ${staleProcessingSql}
         `),
         // Dead-worker recovery: the owner's process is provably gone, so its
         // in-flight rows go back to pending — owner intact (the primer
@@ -467,17 +478,7 @@ export function createMessageRepository(db) {
           FROM queue
           WHERE status = 'processing'
             AND kind = 'continuation'
-            AND (
-              COALESCE(owner_last_claimed_at, processing_at, timestamp) < @inactiveBefore
-              OR (
-                @ceilingBefore IS NOT NULL
-                AND MAX(
-                  COALESCE(processing_at, timestamp),
-                  COALESCE((SELECT MAX(answered_at) FROM relay_questions WHERE queue_id = queue.id), '')
-                ) < @ceilingBefore
-              )
-            )
-            AND id NOT IN (SELECT queue_id FROM relay_questions WHERE status = 'pending')
+            AND ${staleProcessingSql}
         `),
         listQueueForPauseDrop: db.prepare(`SELECT id, conversation_id FROM queue WHERE status IN ('pending', 'processing', 'parked')`),
         // Authoritative "is a turn in flight" signal for the conversation list.

package/server/repositories/subagent-timeline-statements.mjs

@@ -47,6 +47,8 @@ export function createSubagentTimelineStatements(db) {
     // The column list every run read uses, so the header travels with the
     // run wherever runs are listed (conversation payload, in-flight snapshot).
     subagentRunSelectColumns,
+    // A run that runs again (a resumed agent): no end time while it runs.
+    reopenSubagentRun: db.prepare(`UPDATE subagent_runs SET status = 'running', updated_at = ?, completed_at = NULL WHERE id = ?`),
     updateSubagentRunHeader: null,
     setSubagentRunTruncated: null,
     listChildSubagentRuns: null,

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

@@ -3,6 +3,7 @@
 import { createAskUserRoutingService } from '../services/ask-user-routing-service.mjs';
 import { admitRemoteRelayRequest, readRemoteRelayRequest } from '../services/remote-relay-inbound.mjs';
 import { isRemoteRelayApprovalQuestion } from '../../shared/remote-relay-contract.mjs';
+import { closedQuestionAnswer, questionAcceptsFreeText } from '../../shared/question-answer-rule.mjs';
 import {
   extractRequestedSchema,
   normalizeSchema,
@@ -35,19 +36,39 @@ function firstKnownValue(source, keyPaths = []) {
   return null;
 }
 
+function parseRowJson(value) {
+  try {
+    return JSON.parse(String(value || ''));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * A stored question row that is this relay's Allow / Deny card for one of its
  * own agent's calls to another relay (remote-relay-caller-context.mjs). The
  * context lives in the row's request envelope.
  */
 function isRemoteRelayApprovalRow(row) {
-  let envelope = null;
-  try {
-    envelope = JSON.parse(String(row?.request || ''));
-  } catch {
-    return false;
-  }
-  return isRemoteRelayApprovalQuestion(envelope);
+  const envelope = parseRowJson(row?.request);
+  return envelope ? isRemoteRelayApprovalQuestion(envelope) : false;
+}
+
+/**
+ * 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
+ * runtime's formatQuestionRow reads it for the card view), or null for a
+ * card that takes any reply.
+ */
+function closedQuestionOfRow(row) {
+  const envelope = parseRowJson(row?.request);
+  const parsedChoices = parseRowJson(row?.choices);
+  const choices = Array.isArray(parsedChoices) ? parsedChoices.map((choice) => String(choice ?? '')) : [];
+  const allowFreeform = envelope && typeof envelope === 'object' && typeof envelope.allowFreeform === 'boolean'
+    ? envelope.allowFreeform
+    : null;
+  if (questionAcceptsFreeText({ allowFreeform, choices })) return null;
+  return { choices, multiSelect: envelope?.context?.multiSelect === true };
 }
 
 function extractContinuationOwnership(rawRequest) {
@@ -297,6 +318,19 @@ export function registerAskUserRoutes(app, deps) {
       flatText = summarizeStructuredAnswer(schema, structured) || flatText;
     } else if (!flatText) {
       return res.status(400).json({ error: 'Empty answer' });
+    } else {
+      // A card that takes no typed text is answered by its choices only.
+      // Anything else is refused and the card stays open: it must not pass
+      // for an answer (an approval reader would take it for a denial).
+      const closed = closedQuestionOfRow(row);
+      if (closed) {
+        const accepted = closedQuestionAnswer(closed, flatText);
+        if (!accepted) {
+          console.warn(`[${ts()}] QUESTION  reject id=${id.slice(0, 8)} reason=not-a-choice`);
+          return res.status(400).json({ error: 'This question takes one of its choices, not typed text', choices: closed.choices });
+        }
+        flatText = accepted;
+      }
     }
 
     const result = askUserRoutingService.routeAnswer({

package/server/routes/messages-routes.mjs

@@ -64,7 +64,7 @@ import {
   sanitizeRunHeaderPatch,
   TIMELINE_READ_DEFAULT_LIMIT,
 } from '../services/subagent-timeline-service.mjs';
-import { normalizeSubagentRunStatus } from '../../shared/subagent-timeline.mjs';
+import { SUBAGENT_TASK_TYPES, isTerminalSubagentRunStatus, normalizeSubagentRunStatus } from '../../shared/subagent-timeline.mjs';
 import { RELAY_EVENT_MESSAGE_KIND } from '../../shared/relay-events.mjs';
 import { isRelayShutdownQueued, relayShutdownGateReply } from '../services/relay-shutdown-gate.mjs';
 import { createStaleAttemptLogLimiter } from '../services/stale-attempt-log-limiter.mjs';
@@ -1431,6 +1431,9 @@ function isOpenAIImageAttachment(raw) {
 export function resolveOpenAIImageEditAttachment(rawAttachments, {
   maxImageBytes = 20 * 1024 * 1024,
   allowedRootPath = '',
+  // Folders of earlier versions that uploads are still read from: only a
+  // sha256-named blob directly inside one counts.
+  allowedBlobRootPaths = [],
   allowedGeneratedImagesRootPath = '',
 } = {}) {
   const attachments = Array.isArray(rawAttachments) ? rawAttachments : [];
@@ -1451,8 +1454,11 @@ export function resolveOpenAIImageEditAttachment(rawAttachments, {
     const filePath = String(firstImage.path || '').trim();
     if (!filePath) throw new Error('Image attachment is missing file path or data URL');
     const allowedRoot = String(allowedRootPath || '').trim();
+    const blobRoots = (Array.isArray(allowedBlobRootPaths) ? allowedBlobRootPaths : [])
+      .map((root) => String(root || '').trim())
+      .filter(Boolean);
     const generatedImagesRoot = String(allowedGeneratedImagesRootPath || '').trim();
-    if (allowedRoot || generatedImagesRoot) {
+    if (allowedRoot || blobRoots.length || generatedImagesRoot) {
       const resolvedPath = path.resolve(filePath);
       const isWithinRoot = (rootPath) => {
         if (!rootPath) return false;
@@ -1467,7 +1473,11 @@ export function resolveOpenAIImageEditAttachment(rawAttachments, {
           && relativeParts[0] !== '..'
           && relativeParts[1] === 'generated-images';
       })();
-      if (!isWithinRoot(allowedRoot) && !isGeneratedImagePath) {
+      const isOldUploadBlob = blobRoots.some((root) => (
+        path.dirname(resolvedPath) === path.resolve(root)
+        && /^[a-f0-9]{64}$/.test(path.basename(resolvedPath))
+      ));
+      if (!isWithinRoot(allowedRoot) && !isOldUploadBlob && !isGeneratedImagePath) {
         throw new Error('Image attachment path is outside the upload directory');
       }
     }
@@ -1747,6 +1757,7 @@ export function registerMessagesRoutes(app, deps) {
     MAX_UPLOAD_BYTES,
     MAX_UPLOAD_ATTACHMENTS,
     uploadsDir,
+    uploadReadDirs = [uploadsDir],
     MAX_REPO_TREE_NODES,
     MAX_REQUEUE_RETRIES,
     MAX_IMAGE_DATA_URL_LENGTH,
@@ -1896,6 +1907,21 @@ export function registerMessagesRoutes(app, deps) {
     return tasks.find((task) => (task?.toolUseId && task.toolUseId === runId) || (taskId && task?.taskId === taskId)) || null;
   }
 
+  // A conversation's sub-agent run by its task id. A Claude agent resumed by
+  // a new message keeps its task id, and the CLI names the call that resumed
+  // it (SendMessage) as the task's tool use, an id no run row carries: its
+  // run is the one the task id leads to.
+  function subagentRunOfTask(conversationId, taskId) {
+    const conversation = String(conversationId || '').trim();
+    const task = String(taskId || '').trim().slice(0, 200);
+    if (!conversation || !task) return null;
+    try {
+      return stmts.getSubagentRunByTaskId?.get?.(conversation, task) || null;
+    } catch {
+      return null;
+    }
+  }
+
   // Stop is offered while a run is running: a background run through its
   // task, a foreground run through the sub-agent cancel route.
   function isSubagentRunStoppable(run) {
@@ -4791,9 +4817,9 @@ export function registerMessagesRoutes(app, deps) {
       ? (pinnedGrokModel || String(configuredGrok?.model || '').trim())
       : '';
     // Claude Cloud conversations resolve models against the cloud provider's
-    // own list (plain ids, no "[1m]" tier). The model is part of the cloud
-    // session's configuration: it can still change before the first message
-    // creates that session, and is locked afterwards.
+    // own list (plain ids, no "[1m]" tier). The first message creates the
+    // cloud session with the conversation's model; a later change is applied
+    // by the worker before the next message (see below).
     const configuredClaudeCloud = runtimeUsesClaudeCloud ? getClaudeCloudProviderSettings() : null;
     const pinnedClaudeCloudModel = runtimeUsesClaudeCloud
       ? stripModelTierSuffix(existingRuntimeSession?.provider_model)
@@ -6971,6 +6997,7 @@ export function registerMessagesRoutes(app, deps) {
         editAttachment = resolveOpenAIImageEditAttachment(requestBody.attachments, {
           maxImageBytes: MAX_UPLOAD_BYTES,
           allowedRootPath: uploadsDir,
+          allowedBlobRootPaths: uploadReadDirs.slice(1),
           allowedGeneratedImagesRootPath: resolveSessionStateRoot?.() || '',
         });
       } catch (error) {
@@ -7830,6 +7857,8 @@ export function registerMessagesRoutes(app, deps) {
     sessionActivityTracker?.noteTaskSettled?.(conversationId, {
       taskId,
       toolUseId: sanitizeSubagentRunId(req.body?.toolUseId) || null,
+      // Which run ended (a resumed agent runs again under the same task id).
+      ...(req.body?.taskRunId ? { taskRunId: String(req.body.taskRunId).trim().slice(0, 200) } : {}),
       status: String(req.body?.status || '').trim().slice(0, 40) || 'completed',
       summary: cleanTaskText(String(req.body?.summary || ''), 500) || null,
       exitCode: exitCode ?? null,
@@ -7886,6 +7915,9 @@ export function registerMessagesRoutes(app, deps) {
         // The spawning tool_use id: the sub-agent run this task is. The panel
         // opens the run's viewer from it.
         toolUseId: sanitizeSubagentRunId(task?.toolUseId) || undefined,
+        // Which run of the task this is (the SDK's run id): a resumed agent
+        // keeps its task id and runs again under a new one.
+        taskRunId: String(task?.taskRunId || '').trim().slice(0, 200) || undefined,
         // The console (shell and Monitor tasks): the file holding the
         // output, how it is obtained ('none': the provider has none to give).
         ...taskOutputFields(task),
@@ -7894,6 +7926,15 @@ export function registerMessagesRoutes(app, deps) {
         exitCode: wholeNumber(task?.exitCode),
       }))
       .filter((task) => task.taskId);
+    // A resumed agent's row names the call that resumed it, which no run
+    // carries: it opens the run of its task instead (a worker that remembers
+    // the spawn sends that already).
+    const runConversationId = resolveTaskConversationId(conversationId);
+    for (const task of tasks) {
+      if (!task.toolUseId || !SUBAGENT_TASK_TYPES.has(task.taskType) || stmts.getSubagentRun?.get?.(task.toolUseId)) continue;
+      const run = subagentRunOfTask(runConversationId, task.taskId);
+      if (run) task.toolUseId = String(run.id);
+    }
     // The first path a task names wins: a later post cannot point a live
     // task's console at another file.
     for (const task of tasks) {
@@ -8563,12 +8604,14 @@ export function registerMessagesRoutes(app, deps) {
   // Fenced by the run row, not by an open turn: a background agent keeps
   // writing after its turn ended, and its entries belong to that turn. A run
   // the relay does not know yet but whose parent it does (an agent spawned
-  // inside another) is created under the parent's turn; anything else is a
-  // 404 the worker retries once the spawn has landed.
+  // inside another) is created under the parent's turn; a run of a task the
+  // relay knows by its task id (a resumed agent: same task, new tool use) is
+  // that task's run; anything else is a 404 the worker retries once the spawn
+  // has landed.
   app.post('/api/subagent-timeline', auth, (req, res) => {
     touchCli();
     const conversationId = String(req.body?.conversationId || '').trim();
-    const runId = sanitizeSubagentRunId(req.body?.subagentRunId);
+    let runId = sanitizeSubagentRunId(req.body?.subagentRunId);
     if (!conversationId || !runId) {
       return res.status(400).json({ error: 'Missing conversationId or subagentRunId' });
     }
@@ -8577,6 +8620,17 @@ export function registerMessagesRoutes(app, deps) {
     }
     const rawHeader = req.body?.header && typeof req.body.header === 'object' ? req.body.header : {};
     let run = stmts.getSubagentRun?.get?.(runId) || null;
+    // A finished run that a later run of its task (posted under another id)
+    // sets running again: the relay marks where it resumed, once per id.
+    let resumedNote = null;
+    if (!run) {
+      run = subagentRunOfTask(conversationId, req.body?.taskId || rawHeader.taskId);
+      if (run && isTerminalSubagentRunStatus(normalizeSubagentRunStatus(run.status))
+        && rawHeader.status && normalizeSubagentRunStatus(rawHeader.status) === 'running') {
+        resumedNote = { key: `relay:resumed:${runId}`, kind: 'note', text: 'Resumed with a new message', metadata: { resumed: true } };
+      }
+      if (run) runId = String(run.id);
+    }
     let created = false;
     if (!run) {
       const parentId = sanitizeSubagentRunId(rawHeader.parentSubagentId);
@@ -8599,7 +8653,8 @@ export function registerMessagesRoutes(app, deps) {
     if (patch) run = subagentTimeline.applyHeader(runId, patch) || run;
     let stored;
     try {
-      stored = subagentTimeline.applyEntries(run, req.body?.entries);
+      const entries = Array.isArray(req.body?.entries) ? req.body.entries : [];
+      stored = subagentTimeline.applyEntries(run, resumedNote ? [resumedNote, ...entries] : entries);
     } catch (error) {
       return res.status(500).json({ error: error?.message || 'Failed to store the timeline' });
     }

package/server/routes/preview-routes.mjs

@@ -4,9 +4,46 @@
 // listener itself has no routes and no way to register anything. Creating or
 // closing a preview therefore always requires the relay token, even though the
 // resulting URL is public.
+//
+// Conversation scope. A preview's token is its only credential, so an agent's
+// preview tool must not see or close another conversation's. A request that
+// names a conversation — the `conversationId` query, else the
+// `X-Relay-Conversation-Id` header every worker and the OAR MCP server send —
+// is scoped to it: GET lists only its previews, DELETE refuses another
+// conversation's with a 403. Only a request with neither (the web UI's
+// Settings → Previews) gets the relay-wide view. Agent-side callers present the
+// same relay token as the owner, so this is a boundary for the tools, not
+// against a caller that deliberately leaves both out.
 
 import { validateStaticRoot } from '../services/preview-static-handler.mjs';
 
+/**
+ * The conversation ids a named scope covers: the id itself, and — when it
+ * names a conversation by its id or by its session id — that conversation's id
+ * and session id. They differ after a placeholder rekey, and a worker's or
+ * tool server's own identity is the session id. A lookup that fails narrows
+ * the scope to the named id rather than failing the request.
+ */
+export function createPreviewScopeResolver({
+  getConversation = () => null,
+  getConversationBySdkSessionId = () => null,
+} = {}) {
+  return function resolveConversationScope(id) {
+    const named = String(id || '').trim();
+    if (!named) return [];
+    const ids = new Set([named]);
+    let conversation = null;
+    try {
+      conversation = getConversation(named) || getConversationBySdkSessionId(named) || null;
+    } catch {}
+    for (const value of [conversation?.id, conversation?.sdk_session_id]) {
+      const text = String(value || '').trim();
+      if (text) ids.add(text);
+    }
+    return [...ids];
+  };
+}
+
 export function registerPreviewRoutes(app, deps) {
   const {
     auth,
@@ -20,6 +57,8 @@ export function registerPreviewRoutes(app, deps) {
     // publishes stay panel-only — the transcript records the conversation, not
     // panel actions).
     recordPreviewCard = () => {},
+    // (scope id) => the conversation ids it covers; createPreviewScopeResolver.
+    resolveConversationScope = (id) => (id ? [id] : []),
   } = deps;
 
   function laneUnavailable(res) {
@@ -36,13 +75,27 @@ export function registerPreviewRoutes(app, deps) {
     });
   }
 
-  // GET /api/previews — every live preview, or one conversation's when filtered.
-  // Unfiltered is what the settings "Live previews" list uses: nothing expires
-  // on its own, so there has to be one place that shows everything.
+  // The conversation ids a request is scoped to, or null for the owner's
+  // view. The query wins over the header: the header is the worker's own
+  // session, while a worker can be handed a row of another conversation (a
+  // placeholder rekey, or the shared fallback of the worker's pending lookup)
+  // and its tool names the conversation of the turn it is running.
+  function requestScope(req) {
+    const named = String(req.query?.conversationId || '').trim()
+      || String(req.headers?.['x-relay-conversation-id'] || '').trim();
+    if (!named) return null;
+    const ids = resolveConversationScope(named);
+    return Array.isArray(ids) && ids.length ? ids : [named];
+  }
+
+  // GET /api/previews — one conversation's live previews when scoped (see the
+  // top of the file), else every one. Unscoped is what the settings "Live
+  // previews" list uses: nothing expires on its own, so there has to be one
+  // place that shows everything.
   app.get('/api/previews', auth, (req, res) => {
-    const conversationId = String(req.query?.conversationId || '').trim();
-    const previews = conversationId
-      ? previewRegistry.listForConversation(conversationId)
+    const scope = requestScope(req);
+    const previews = scope
+      ? previewRegistry.list().filter((entry) => scope.includes(entry.conversationId))
       : previewRegistry.list();
     res.json({
       previews,
@@ -107,8 +160,21 @@ export function registerPreviewRoutes(app, deps) {
   });
 
   // DELETE /api/previews/:token — the link stops resolving immediately. The dev
-  // server behind it is untouched; it is a separate background task.
+  // server behind it is untouched; it is a separate background task. A scoped
+  // request may close only its own conversation's previews.
   app.delete('/api/previews/:token', auth, (req, res) => {
+    const scope = requestScope(req);
+    if (scope) {
+      const token = String(req.params?.token || '').trim();
+      // list() also holds the stored previews a restart could not check yet.
+      const target = previewRegistry.list().find((entry) => entry.token === token);
+      if (target && !scope.includes(target.conversationId)) {
+        return res.status(403).json({
+          error: 'This preview belongs to another conversation; a conversation can close only its own previews. '
+            + 'The owner can close it in Settings → Previews.',
+        });
+      }
+    }
     const closed = previewRegistry.close(req.params?.token);
     if (!closed.ok) return res.status(closed.status || 404).json({ error: closed.error });
     res.json({ ok: true, preview: closed.preview });