@oar-sh/oar 0.9.21 → 0.9.22

package/CHANGELOG.md

@@ -3,6 +3,119 @@
 All notable changes to OAR are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow semver.
 
+## [0.9.22] — 2026-11-05
+
+Highlights: questions that don't block move into the chat header. A **📓**
+icon with a count opens them, urgent ones first, and the turn that asked
+keeps one line, "📓 Question for you", in place of the card. Settings →
+General reads as five headed sections, with three new choices: whether
+thoughts start open while an agent works, how many tool lines a working
+agent shows, counted per agent so a busy sub-agent no longer pushes out the
+main agent's lines, and a stream view that shows a turn's thoughts and tool
+calls in the order they happened. While a turn runs, the page's poll leaves
+out what it already holds, and an idle relay and its workers wake far less
+often. Claude sessions now ask you in a **Safety check** card, which only
+you can answer, before removals and other asks Claude Code marks as
+person-only.
+
+### Changed
+
+- **📓 Questions in the chat header.** A conversation's questions that don't
+  block sit behind a 📓 icon with a count, first among the header icons (in
+  ︙ when the header runs out of room). It opens a list under it with the
+  full cards, urgent ones first with their details open, and what was
+  answered in the last day below; answering keeps the list open. On a phone
+  the list spans the width over a dimmed page, with half-width buttons. While
+  an urgent question waits, 📓 and the Inbox show the urgent count in red.
+  The Inbox's link to a session opens it with 📓 at that question. Each ask
+  now remembers the turn that asked it (migration 0037).
+- **A question leaves one line in the turn that asked it.** The cards of
+  questions that don't block no longer sit at the end of the conversation;
+  the reply of the turn that asked shows a one-line "📓 Question for you"
+  instead (live while it runs, "Answered: …" once answered), and a tap opens
+  📓 at that question. A question asked for another session, carried over by
+  a compaction or from before this version stands as one line at the end
+  while it waits.
+- **Settings → General in headed sections.** The tab reads as five groups,
+  Appearance, Reading, Turns and tasks, This relay and Updates, instead of
+  one long column. Each relay-wide row now says it is a setting of this
+  relay; the per-browser rows keep "Saved in this browser."
+- **Thoughts open or closed by your choice.** Settings → General →
+  Appearance has "Expand thoughts while an agent works" (on by default), with
+  a 💭 Thoughts mirror in the 🧠 modal. It decides whether thoughts start open
+  in the live turn, in live sub-agent bubbles and in the sub-agent viewer,
+  finished thoughts there included. An open live thought keeps a one-line
+  header to fold it by; a thought you fold or open by hand stays that way
+  while more text streams in. A finished reply's 💭 fold stays closed as
+  before.
+- **The main agent's tool lines stay while sub-agents work.** The live
+  bubble's tool list is capped per agent now, the main agent and each
+  sub-agent apart, so a busy sub-agent no longer pushes the main agent's
+  lines out. Settings → General → Appearance has "Tool lines shown while an
+  agent works": 50 by default, 10 to 500 or no limit. The relay sends the
+  running turn's newest lines per agent as the page's setting asks (50 when
+  it does not say, 500 at most), and for a finished turn the main agent's
+  newest 200 and each sub-agent's newest 50 (it sent the first 48 of the
+  whole turn). A sub-agent bubble that holds as many lines as the setting
+  shows "50+ steps".
+- **Stream view: a turn in the order it happened.** Settings → General →
+  Appearance has "Stream view" (off by default), with a 🧵 mirror in the 🧠
+  modal. When it is on, an agent turn's thoughts and tool calls show as one
+  list in the order they happened, live and in the finished message, with
+  the reply last. For Copilot, Cursor and Grok, tools and thoughts stream in
+  arrival order and the reply comes after them. The relay now numbers a
+  turn's thoughts and tool lines in one sequence (migration 0038); turns
+  recorded before that keep the grouped layout. A finished turn whose main
+  agent ran more than 200 tool lines says how many earlier ones it left out.
+- **The live poll leaves out what the page already has.** While a turn
+  runs, the page asks for its conversation about once a second. It now
+  names the finished replies whose tool lines and thoughts it already holds,
+  and the relay leaves those out unless they changed since (a busy window:
+  about 6 KB per poll instead of over 200 KB). Opening a conversation,
+  paging back and every other load still get everything.
+- **An idle relay and its workers wake far less often.** The relay no
+  longer polls its queue twice a second: a write that makes a message
+  deliverable wakes delivery at once, through triggers on the queue table.
+  A retry or a usage-limit hold gets a timer for the moment it ends, and a
+  10 s poll stays as a backstop. A gate lifting (relay resumed, restart
+  cancelled, tunnel connected, a kill's grace over, a worker replacement
+  done) wakes delivery too. The CLI status, the share-viewer prune and the
+  worker prime run only while there is something for them to do. Each
+  worker has one keepalive instead of two 10 s timers, and it beats every
+  30 s while idle, on a relay that supports it. A silent worker now counts
+  as gone after 90 s instead of 30 s. Workers and relays of older versions
+  keep working with the new ones.
+- **Claude sessions ask you before removals and other asks Claude Code
+  marks as person-only, instead of allowing them.** Such an ask, for
+  example an `rm -rf` of the working folder, used to be approved by the
+  relay like every other ask. Now a **Safety check** card, in the session
+  and in the Inbox, shows Claude Code's reason
+  and then the whole command, each line behind `│`, with hidden or
+  reordering characters shown as `\u{…}`. It offers **Allow once** and
+  **Deny**, takes no typed reply, and only you can answer it: no agent,
+  of this relay or another, sees it among a session's questions or may
+  answer it. It allows only that one call and adds no rule. A denial, no
+  answer within the question timeout, a stopped turn or a relay that
+  cannot show the card all leave the command unrun, and a command too long
+  to show is refused without a card. Other asks are still allowed as
+  before.
+
+### Upgrade notes
+
+- **Two small migrations.** 0037 adds the asking turn to each ask and 0038
+  the sequence number to a turn's thoughts and tool lines, with an index;
+  neither rewrites the rows already there. As before, the relay copies its
+  database to the backups folder before the first start of a new version.
+- **Every session worker is replaced once after the update,** as in
+  0.9.21: once its session is idle and its CLI has ended, usually some 10
+  minutes after its last turn. A Claude session shows the **Safety check**
+  card once its worker runs 0.9.22. Nothing needs to be done.
+- **Mixed versions work together.** A 0.9.21 worker on a 0.9.22 relay keeps
+  its 10 s beat, and a 0.9.22 worker on a 0.9.21 relay beats every 10 s.
+  Paired relays of both versions keep working with each other.
+- **No new dependency.** Going back to 0.9.21 needs no database step: it
+  leaves the new columns and the index alone.
+
 ## [0.9.21] — 2026-11-01
 
 Highlights: the chat screen is more compact. The mode, model, effort,

package/README.md

@@ -45,29 +45,29 @@ flowchart LR
 <table>
 <tr>
 <td width="42%" rowspan="4" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.21" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-mobile.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-mobile.png?v=0.9.22" alt="OAR on a phone: a finished agent turn in a conversation, with the composer below"></picture></a>
 <br><sub>On a phone: the same conversations, installable as an app.</sub>
 </td>
 <td width="58%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.21" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-agents.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-agents.png?v=0.9.22" alt="Background subagents running in parallel in the task panel, each with live token counts, elapsed time, and its own Stop button"></picture></a>
 <br><sub>Agents working in parallel, each with live token counts and its own Stop.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.21" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-question.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-question.png?v=0.9.22" alt="A question card in the middle of a turn: the agent offers several choices and a free-text reply"></picture></a>
 <br><sub>When the agent needs a decision, it asks, and waits for your answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.21" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
+<a href="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pingcf-thoughts.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/pingcf-thoughts.png?v=0.9.22" alt="An expanded Thoughts block showing the agent's reasoning above its reply"></picture></a>
 <br><sub>Read the reasoning, not just the answer.</sub>
 </td>
 </tr>
 <tr>
 <td valign="top">
-<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.21" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
+<a href="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-watching.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/pagewright-watching.png?v=0.9.22" alt="A session watching two other sessions: a finished reply arrives as a compact relay-event row, the watching 2 sessions list is open with Unsubscribe, and a request to also watch a session on a paired relay waits on an Allow / Deny card"></picture></a>
 <br><sub>Agents that watch agents: woken by events, approving nothing.</sub>
 </td>
 </tr>
@@ -118,11 +118,11 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 <table>
 <tr>
 <td width="62%" valign="top">
-<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.21" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
+<a href="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/cfmail-steering.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/cfmail-steering.png?v=0.9.22" alt="A running Claude turn with a message steered into it mid-turn, the reply streaming with its tool calls, and the Steer button in the composer"></picture></a>
 <br><sub>Send a message while the agent works, and it steers the running turn.</sub>
 </td>
 <td width="38%" valign="top">
-<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.21" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
+<a href="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/usage-copilot-compact.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/usage-copilot-compact.png?v=0.9.22" alt="The GitHub Copilot card in Check Usage: premium requests and plan quota with reset dates, and the cost of the last turn"></picture></a>
 <br><sub>What each plan has left, in one place.</sub>
 </td>
 </tr>
@@ -139,7 +139,7 @@ API keys are entered in **⚙️ Settings** and stay on the relay host. The Clau
 - **Share** a conversation as a read-only link, hide single messages and the host's paths from it, and see when it was opened ([Sharing](docs/web-ui.md#sharing)).
 - **On your phone**: install OAR as an app and get push notifications; back walks through the conversations you opened, a pinch zooms the whole app, and held sideways it keeps a phone's layout ([Notifications and the app](docs/web-ui.md#notifications-and-the-app), [back and forward](docs/web-ui.md#back-and-forward), [zoom](docs/web-ui.md#zoom), [a phone held sideways](docs/web-ui.md#a-phone-held-sideways)).
 
-The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.21](CHANGELOG.md#0921--2026-11-01) as the latest.
+The full tour is in [Using the web UI](docs/web-ui.md); every setting and config key is in [Settings and configuration](docs/configuration.md). What changed in each release is in the [changelog](CHANGELOG.md), with [0.9.22](CHANGELOG.md#0922--2026-11-05) as the latest.
 
 ## Remote access
 
@@ -190,7 +190,7 @@ flowchart LR
 
 You stay in charge: per paired relay you decide whether agents may only read, also prompt, or do everything, and in the `ask` and `plan` modes every write asks you first. A subscription only notifies; it approves nothing.
 
-<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.21"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.21"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.21" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
+<p><a href="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.22"><picture><source media="(prefers-color-scheme: light)" srcset="https://oar.sh/assets/shots/pagewright-cross-relay.light.png?v=0.9.22"><img src="https://oar.sh/assets/shots/pagewright-cross-relay.png?v=0.9.22" alt="A session watching two sessions on a paired relay: a reply arrives as a relay-event row, and after a short outage the events the other relay kept arrive as one replayed row" width="720"></picture></a></p>
 
 How pairing, permissions and limits work is in [Agents working together](docs/agents-together.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.21",
+  "version": "0.9.22",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",

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

@@ -14,6 +14,7 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { createWorkerKeepalive } from '../../shared/worker-runtime/worker-keepalive.mjs';
 import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
@@ -124,8 +125,13 @@ async function main() {
     getSteeringState: () => buildClaudeCloudSteeringState(runner),
   });
 
+  // One timer for the heartbeat and the socket's readiness refresh: 10 s
+  // while working, 30 s while idle on a relay that allows it.
+  let keepalive = null;
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
+    readyRefreshMs: 0,
+    onRelayFrame: () => keepalive?.nudge(),
     token,
     dbg,
     buildId,
@@ -142,10 +148,12 @@ async function main() {
       }
     },
   });
+  keepalive = createWorkerKeepalive({ heartbeat, link: wsLink, busyMs: HEARTBEAT_MS });
 
   const shutdown = async (signal) => {
     dbg(`shutting down (${signal})`);
     try { wsLink.stop(); } catch {}
+    try { keepalive.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
     // The cloud session is left as it is: a turn in flight keeps running
@@ -162,7 +170,7 @@ async function main() {
   });
 
   dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
-  heartbeat.startHeartbeat();
+  keepalive.start();
   wsLink.start();
   // Not awaited: deliveries wait for it inside the runner, and a relay that
   // cannot say which cloud session this is leaves the binding to the first

package/server/claude-worker/claude-sdk-adapter.mjs

@@ -2,6 +2,7 @@ import { createSdkMcpServer, query } from '@anthropic-ai/claude-agent-sdk';
 
 import { formatClaudeBackgroundCommandLimitLabel } from '../../shared/claude-background-command-limit.mjs';
 import { parseThinkingDisplay } from '../../shared/claude-thinking.mjs';
+import { PERSON_ONLY_QUESTION_SOURCE } from '../../shared/relay-asks.mjs';
 import { MEDIA_EMBED_INSTRUCTION_TEXT } from '../../shared/media-embed-instructions.mjs';
 import { REMOTE_RELAY_TOOL_CALL_TIMEOUT_MS } from '../../shared/remote-relay-tool-core.mjs';
 import { createPreviewToolDefinition } from './claude-preview-tool.mjs';
@@ -631,11 +632,151 @@ export async function readPlanUsage(turn, dbg = () => {}, { timeoutMs = 10000 }
   }
 }
 
+// Asks Claude Code marks as person-only: a removal of a workspace or system
+// directory, a target it cannot resolve. No rule, mode or automatic approval
+// may answer them, so allow-all parity stops here. The SDK does not forward
+// the wire's `classifier_approvable`, so the safety-check kinds count only
+// together with `suppressAlwaysAllowRule`; a sensitive-file safety check
+// (an edit under .git/ or .claude/) carries no such flag and stays allowed.
+// A user's `permissions.ask` rule (`matchedAskRule`) changes nothing: the
+// flags decide, and an ask that rule forced without them stays allowed.
+const PERSON_ONLY_REASON_TYPES = new Set(['safetyCheck', 'subcommandResults']);
+export const PERSON_ONLY_ALLOW_CHOICE = 'Allow once';
+export const PERSON_ONLY_DENY_CHOICE = 'Deny';
+export { PERSON_ONLY_QUESTION_SOURCE };
+// The card's first line is fixed text: the relay's console log prints the
+// first 60 characters of a question, and the command must not reach it.
+const PERSON_ONLY_QUESTION_LEAD = 'Claude Code marks this as person-only: no rule or automatic approval may allow it. Allow it once?';
+const PERSON_ONLY_RATIONALE = 'Claude Code needs a person to approve this before it runs. Nothing runs until you choose.';
+// The card shows the whole command or nothing: a cut could hide the removal.
+export const PERSON_ONLY_COMMAND_MAX = 8000;
+export const PERSON_ONLY_TOO_LONG_MESSAGE = 'Not run: too long to show for approval; issue the removal as a short command of its own.';
+const PERSON_ONLY_REASON_MAX = 400;
+const PERSON_ONLY_TYPED_ANSWER_MAX = 500;
+
+export function isPersonOnlyAsk(options) {
+  if (!options || typeof options !== 'object') return false;
+  if (options.defaultToNo === true) return true;
+  return PERSON_ONLY_REASON_TYPES.has(options.decisionReasonType)
+    && options.suppressAlwaysAllowRule === true;
+}
+
+// Characters that hide or reorder text: C0 and C1 controls, bidi controls,
+// zero-width characters and the Unicode line separators. On the card each
+// one shows as a visible \u{XXXX} escape (the body is pre-wrap plain text).
+const INVISIBLE_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u061c\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g;
+
+function escapeInvisible(text) {
+  return String(text ?? '').replace(INVISIBLE_CHARACTERS, (char) => (
+    `\\u{${char.codePointAt(0).toString(16).toUpperCase().padStart(4, '0')}}`
+  ));
+}
+
+// The CLI's reason may carry ANSI colour (sdk.d.ts): drop well-formed
+// sequences, then escape what is left, newlines included (one line).
+function reasonLine(value) {
+  const text = String(value ?? '')
+    .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .trim();
+  return capText(escapeInvisible(text), PERSON_ONLY_REASON_MAX);
+}
+
+function capText(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}… (${text.length - max} more characters)`;
+}
+
+function personOnlySubject(input) {
+  if (typeof input?.command === 'string') return { label: 'command', text: input.command };
+  for (const key of ['file_path', 'notebook_path', 'path']) {
+    if (typeof input?.[key] === 'string') return { label: 'path', text: input[key] };
+  }
+  let json = '';
+  try { json = JSON.stringify(input ?? {}); } catch { json = ''; }
+  return { label: 'input', text: json };
+}
+
+// Each line escaped and behind "│ ", each line break marked "⏎", so no line
+// of the command can pass for the card's own text.
+function subjectLines(text) {
+  return String(text ?? '').split('\n').map(escapeInvisible);
+}
+
+function subjectTooLong(input) {
+  return subjectLines(personOnlySubject(input).text).join('\n').length > PERSON_ONLY_COMMAND_MAX;
+}
+
+export function personOnlyQuestionText(toolName, input, decisionReason) {
+  const subject = personOnlySubject(input);
+  const lines = subjectLines(subject.text);
+  const parts = [PERSON_ONLY_QUESTION_LEAD];
+  const reason = reasonLine(decisionReason);
+  if (reason) parts.push(`Reason: ${reason}`);
+  const count = lines.length > 1 ? `, ${lines.length} lines` : '';
+  parts.push(`${toolName || 'Tool'} ${subject.label}${count}:\n│ ${lines.join(' ⏎\n│ ')}`);
+  return parts.join('\n\n');
+}
+
+function personOnlyDenyMessage(decisionReason, why) {
+  const reason = reasonLine(decisionReason);
+  return `Not run: Claude Code marks this as person-only${reason ? ` (${reason})` : ''}, and ${why}. `
+    + 'Do not work around it by splitting, scripting or re-issuing it through another tool.';
+}
+
+// Allow/Deny card over the question bridge, no typed replies. Only the exact
+// "Allow once" allows, and never with `updatedPermissions`: the next such ask
+// asks again.
+async function askPersonOnly({ askUserBridge, toolName, input, options, signal, dbg }) {
+  const reason = options?.decisionReason;
+  const kind = options?.decisionReasonType || 'defaultToNo';
+  const deny = (why, outcome) => {
+    dbg('person-only ask', toolName, kind, outcome);
+    return { behavior: 'deny', message: personOnlyDenyMessage(reason, why) };
+  };
+  if (signal?.aborted) return deny('the turn was stopped', 'aborted');
+  if (subjectTooLong(input)) {
+    dbg('person-only ask', toolName, kind, 'too-long');
+    return { behavior: 'deny', message: PERSON_ONLY_TOO_LONG_MESSAGE };
+  }
+  if (!askUserBridge) return deny('the relay could not show the question', 'no-bridge');
+  const question = personOnlyQuestionText(toolName, input, reason);
+  let result;
+  try {
+    result = await askUserBridge.handleAskUserQuestion({
+      questions: [{
+        question,
+        header: 'Safety check',
+        options: [{ label: PERSON_ONLY_ALLOW_CHOICE }, { label: PERSON_ONLY_DENY_CHOICE }],
+      }],
+    }, {
+      signal,
+      source: PERSON_ONLY_QUESTION_SOURCE,
+      rationale: PERSON_ONLY_RATIONALE,
+      allowFreeform: false,
+    });
+  } catch (error) {
+    if (signal?.aborted) return deny('the turn was stopped', 'aborted');
+    dbg('person-only ask bridge failed', error?.message || String(error));
+    return deny('the relay could not show the question', 'bridge-failed');
+  }
+  if (signal?.aborted) return deny('the turn was stopped', 'aborted');
+  if (result?.timedOut) return deny('no answer came before the timeout', 'timed-out');
+  const answer = String(result?.answers?.[question] ?? '').trim();
+  if (answer === PERSON_ONLY_ALLOW_CHOICE) {
+    dbg('person-only ask', toolName, kind, 'allowed');
+    return { behavior: 'allow', updatedInput: input };
+  }
+  if (!answer || answer === PERSON_ONLY_DENY_CHOICE) return deny('the user denied it', 'denied');
+  return deny(`the user denied it: ${capText(escapeInvisible(answer), PERSON_ONLY_TYPED_ANSWER_MAX)}`, 'denied-other');
+}
+
 /**
  * Build the `canUseTool` callback for one turn. Everything is auto-allowed
- * (parity with the Copilot workers' `--allow-all` posture); the only
- * interceptions are AskUserQuestion (bridged to relay question cards) and
- * ExitPlanMode (surfaces the plan_ready board).
+ * (parity with the Copilot workers' `--allow-all` posture) except the asks
+ * Claude Code marks as person-only (an Allow/Deny relay card, see
+ * isPersonOnlyAsk); the other interceptions are AskUserQuestion (bridged to
+ * relay question cards) and ExitPlanMode (surfaces the plan_ready board).
  *
  * ExitPlanMode is DENIED after the board is posted: allowing it tells the CLI
  * the user approved the plan, and the same turn rolls straight into
@@ -658,8 +799,12 @@ export function createCanUseTool({
   onExitPlanMode,
   dbg = () => {},
 } = {}) {
-  return async function canUseTool(toolName, input, { signal } = {}) {
+  return async function canUseTool(toolName, input, options = {}) {
+    const signal = options?.signal;
     const normalizedToolName = String(toolName || '').trim();
+    if (isPersonOnlyAsk(options)) {
+      return askPersonOnly({ askUserBridge, toolName: normalizedToolName, input, options, signal, dbg });
+    }
     try {
       if (normalizedToolName === 'AskUserQuestion' && askUserBridge) {
         const { answers } = await askUserBridge.handleAskUserQuestion(input, { signal });

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

@@ -18,6 +18,7 @@ import { createClaudeSessionRootResolver } from '../services/claude-session-root
 import {
   startClaudeSession,
   createCanUseTool,
+  isPersonOnlyAsk,
   readContextUsage,
   readPlanUsage,
   normalizeClaudeEffort,
@@ -2354,9 +2355,10 @@ export function createClaudeSessionRunner({
     // nothing else is left: the cap exists to bound a retry storm's chatter,
     // while a structured entry carries transcript geometry no later line can
     // restore (a compaction boundary buffered between turns, then 50 task
-    // notifications, used to lose its break row silently). The client's
-    // capRelayActivityEntries protects structured rows too, but head-caps the
-    // prose it keeps; here the newest lines are the informative ones.
+    // notifications, used to lose its break row silently). The relay's
+    // capRelayActivityEntries protects structured rows too and keeps the
+    // newest prose of each thread; here too the newest lines are the
+    // informative ones.
     while (proc.pendingActivities.length > MAX_PENDING_ACTIVITIES) {
       const proseIndex = proc.pendingActivities.findIndex((carried) => typeof carried === 'string');
       proc.pendingActivities.splice(proseIndex === -1 ? 0 : proseIndex, 1);
@@ -3806,8 +3808,9 @@ export function createClaudeSessionRunner({
         // denied. Register a continuation turn first: it is born processing,
         // gives the card a real queue row, and the flow's eventual top-level
         // result (or stream end) closes it like any other continuation.
+        // A person-only safety ask is a question card too.
         if (
-          toolName === 'AskUserQuestion'
+          (toolName === 'AskUserQuestion' || isPersonOnlyAsk(options))
           && proc === processRef
           && !processRef.activeCtx
           && !processRef.pendingDelivered.length
@@ -4582,6 +4585,8 @@ export function createClaudeSessionRunner({
     backgroundTaskIds,
     resyncBackgroundTasks,
     flushKeptTaskSettles,
+    // Settle notices still kept for the relay: the keepalive stays busy.
+    keptTaskSettleCount: () => keptTaskSettles.size(),
     shutdown,
     // Test seams / observability.
     _getProcess: () => proc,

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

@@ -14,6 +14,7 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { createWorkerKeepalive } from '../../shared/worker-runtime/worker-keepalive.mjs';
 import { resolveBuildId } from '../../shared/build-id.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { resolveDeliveredAutoCompactWindow } from '../../shared/auto-compact-window.mjs';
@@ -174,10 +175,16 @@ export async function runClaudeSessionWorker({
     getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
     onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
     onAnswered: () => turnRunner.flushKeptTaskSettles(),
+    getKeptPostCount: () => turnRunner.keptTaskSettleCount?.() || 0,
   });
 
+  // One timer for the heartbeat and the socket's readiness refresh: 10 s
+  // while working, 30 s while idle on a relay that allows it.
+  let keepalive = null;
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
+    readyRefreshMs: 0,
+    onRelayFrame: () => keepalive?.nudge(),
     token,
     dbg,
     getSessionReady: () => true,
@@ -239,6 +246,7 @@ export async function runClaudeSessionWorker({
       dbg('unknown worker control ignored', type || '(none)');
     },
   });
+  keepalive = createWorkerKeepalive({ heartbeat, link: wsLink, busyMs: HEARTBEAT_MS });
   linkBridge.attach(wsLink);
 
   let shuttingDown = false;
@@ -247,6 +255,7 @@ export async function runClaudeSessionWorker({
     shuttingDown = true;
     dbg(`shutting down (${signal})`);
     try { wsLink.stop(); } catch {}
+    try { keepalive.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
     // Consumed steers still settling must fail, not be left for dead-worker
@@ -271,6 +280,6 @@ export async function runClaudeSessionWorker({
   });
 
   dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'}${backend ? ` backend=${backend.id}` : ''} build=${buildId || 'unknown'}`);
-  heartbeat.startHeartbeat();
+  keepalive.start();
   wsLink.start();
 }

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

@@ -5133,6 +5133,7 @@ export function createCopilotSdkSessionRunner({
     resyncBackgroundTasks,
     // The relay answered a heartbeat: settle notices kept for it go out.
     flushKeptTaskSettles: () => keptTaskSettles.flush(),
+    keptTaskSettleCount: () => keptTaskSettles.size(),
     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

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

@@ -20,6 +20,7 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { createWorkerKeepalive } from '../../shared/worker-runtime/worker-keepalive.mjs';
 import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import {
@@ -158,10 +159,16 @@ async function main() {
     onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
     // The relay answered: settle notices it missed go out.
     onAnswered: () => turnRunner.flushKeptTaskSettles?.(),
+    getKeptPostCount: () => turnRunner.keptTaskSettleCount?.() || 0,
   });
 
+  // One timer for the heartbeat and the socket's readiness refresh: 10 s
+  // while working, 30 s while idle on a relay that allows it.
+  let keepalive = null;
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
+    readyRefreshMs: 0,
+    onRelayFrame: () => keepalive?.nudge(),
     token,
     dbg,
     buildId,
@@ -213,11 +220,13 @@ async function main() {
       dbg('worker control ignored (unsupported by the SDK worker)', type || '(none)');
     },
   });
+  keepalive = createWorkerKeepalive({ heartbeat, link: wsLink, busyMs: HEARTBEAT_MS });
   linkBridge.attach(wsLink);
 
   const shutdown = async (signal) => {
     dbg(`shutting down (${signal})`);
     try { wsLink.stop(); } catch {}
+    try { keepalive.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
     // Rows whose prompt the runtime consumed and whose settle marker has not
@@ -246,7 +255,7 @@ async function main() {
   });
 
   dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
-  heartbeat.startHeartbeat();
+  keepalive.start();
   wsLink.start();
 }
 

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

@@ -13,6 +13,7 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { createWorkerKeepalive } from '../../shared/worker-runtime/worker-keepalive.mjs';
 import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
@@ -110,8 +111,13 @@ async function main() {
     getSteeringState: () => buildCursorSteeringState(turnRunner),
   });
 
+  // One timer for the heartbeat and the socket's readiness refresh: 10 s
+  // while working, 30 s while idle on a relay that allows it.
+  let keepalive = null;
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
+    readyRefreshMs: 0,
+    onRelayFrame: () => keepalive?.nudge(),
     token,
     dbg,
     buildId,
@@ -128,10 +134,12 @@ async function main() {
       }
     },
   });
+  keepalive = createWorkerKeepalive({ heartbeat, link: wsLink, busyMs: HEARTBEAT_MS });
 
   const shutdown = async (signal) => {
     dbg(`shutting down (${signal})`);
     try { wsLink.stop(); } catch {}
+    try { keepalive.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
     // The agent handle owns a SQLite store; close it before exiting — but
@@ -158,7 +166,7 @@ async function main() {
   });
 
   dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
-  heartbeat.startHeartbeat();
+  keepalive.start();
   wsLink.start();
 }