@oar-sh/oar 0.9.5 → 0.9.6

package/.github/extensions/web-relay/polling/polling-loop.mjs

@@ -6,7 +6,7 @@ import {
 } from "../runtime/send-and-wait-errors.mjs";
 import { getActiveSession } from "../runtime/session-registry.mjs";
 import { DEFAULT_QUESTION_TIMEOUT_MS } from "../../../../shared/question-timeout.mjs";
-import { QUESTION_TIMEOUT_CONTINUATION_TEXT } from "../../../../shared/question-timeout.mjs";
+import { waitForRelayQuestion } from "../../../../shared/question-wait.mjs";
 import { EMPTY_TURN_COMPLETION_NOTE } from "../../../../shared/empty-turn-completion.mjs";
 import { stripPromptContextPrefix } from "../skills/prompt-context.mjs";
 
@@ -473,37 +473,17 @@ export function createPollingLoop({
     return null;
   };
 
-  async function waitForRelayQuestionAnswer(questionId, timeoutMs = DEFAULT_QUESTION_TIMEOUT_MS, pollIntervalMs = 1500) {
-    const started = Date.now();
-    while (true) {
-      const { question } = await api("GET", `/api/relay-question/${questionId}`);
-      if (!question) throw new Error("Relay question missing");
-      if (question.status === "answered") {
-        return {
-          answer: String(question.answer || "").trim(),
-          structuredAnswer: question.structuredAnswer && typeof question.structuredAnswer === "object"
-            ? question.structuredAnswer
-            : null,
-          timedOut: false,
-        };
-      }
-      if (question.status === "timed_out" || question.status === "cancelled") {
-        return {
-          answer: QUESTION_TIMEOUT_CONTINUATION_TEXT,
-          structuredAnswer: null,
-          timedOut: true,
-        };
-      }
-      if (Date.now() - started >= timeoutMs) {
-        await api("POST", `/api/relay-question/${questionId}/timeout`, {}).catch(() => {});
-        return {
-          answer: QUESTION_TIMEOUT_CONTINUATION_TEXT,
-          structuredAnswer: null,
-          timedOut: true,
-        };
-      }
-      await sleep(pollIntervalMs);
-    }
+  // The wait survives a relay that is briefly not there
+  // (shared/question-wait.mjs).
+  function waitForRelayQuestionAnswer(questionId, timeoutMs = DEFAULT_QUESTION_TIMEOUT_MS, pollIntervalMs = 1500) {
+    return waitForRelayQuestion({
+      api,
+      questionId,
+      deadlineMs: timeoutMs,
+      pollMs: pollIntervalMs,
+      sleep,
+      dbg,
+    });
   }
 
   async function processPendingSdkSessionDeletes() {

package/.github/extensions/web-relay/skills/question-bridge.mjs

@@ -1,5 +1,5 @@
 import { getActiveSession } from '../runtime/session-registry.mjs';
-import { QUESTION_TIMEOUT_CONTINUATION_TEXT } from "../../../../shared/question-timeout.mjs";
+import { createRelayQuestion, waitForRelayQuestion } from "../../../../shared/question-wait.mjs";
 import { extractRequestedSchema } from "../../../../shared/question-schema.mjs";
 
 export function createQuestionBridge({
@@ -49,39 +49,18 @@ export function createQuestionBridge({
     return Number.isFinite(fallback) && fallback >= 0 ? fallback : 0;
   }
 
-  async function waitForRelayQuestionAnswer(questionId, timeoutMs = null) {
-    const started = Date.now();
-    const effectiveTimeoutMs = resolveQuestionWaitTimeoutMs(timeoutMs);
-
-    while (true) {
-      const { question } = await api("GET", `/api/relay-question/${questionId}`);
-      if (!question) throw new Error("Relay question missing");
-      if (question.status === "answered") {
-        return {
-          answer: String(question.answer || ""),
-          structuredAnswer: question.structuredAnswer && typeof question.structuredAnswer === "object"
-            ? question.structuredAnswer
-            : null,
-          timedOut: false,
-        };
-      }
-      if (question.status === "timed_out" || question.status === "cancelled") {
-        return {
-          answer: QUESTION_TIMEOUT_CONTINUATION_TEXT,
-          structuredAnswer: null,
-          timedOut: true,
-        };
-      }
-      if (Date.now() - started >= effectiveTimeoutMs) {
-        await api("POST", `/api/relay-question/${questionId}/timeout`, {}).catch(() => {});
-        return {
-          answer: QUESTION_TIMEOUT_CONTINUATION_TEXT,
-          structuredAnswer: null,
-          timedOut: true,
-        };
-      }
-      await sleep(questionPollMs);
-    }
+  // The wait survives a relay that is briefly not there
+  // (shared/question-wait.mjs).
+  function waitForRelayQuestionAnswer(questionId, timeoutMs = null) {
+    return waitForRelayQuestion({
+      api,
+      questionId,
+      deadlineMs: resolveQuestionWaitTimeoutMs(timeoutMs),
+      pollMs: questionPollMs,
+      sleep,
+      trimAnswer: false,
+      dbg,
+    });
   }
 
   async function forwardRelayQuestion(request) {
@@ -112,11 +91,7 @@ export function createQuestionBridge({
       request: serializeRequest(request),
     };
 
-    const created = await api("POST", "/api/relay-question", questionPayload);
-    const questionId = created?.question?.id;
-    if (!questionId) {
-      throw new Error("Relay question could not be created");
-    }
+    const questionId = await createRelayQuestion({ api, payload: questionPayload, sleep, dbg });
 
     dbg(
       "relay question created",

package/CHANGELOG.md

@@ -5,6 +5,174 @@ All notable changes to OAR are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.9.6] — 2026-09-29
+
+Highlights: a Claude turn pauses at the usage limit and carries on after the
+reset, a command that prints nothing no longer fails its turn, and agents on
+paired relays can work with each other for a whole session.
+
+### Added
+
+- The relay keeps a copy of its console in `relay-console.log` in its log
+  folder (`server/logs` unless you moved it), with a time stamp per line. The
+  file is rotated at 5 MB and three older copies are kept. The relay's token is
+  never written to it. Set `OAR_NO_CONSOLE_LOG=1` to switch it off.
+- **Claude usage limit:** a Claude turn that runs into the subscription's
+  usage limit is paused instead of failed. Your message closes with a note,
+  the relay queues a message of its own ("continue where you left off") and
+  sends it a minute after the limit resets. A banner above the composer says
+  when, with **Resume now** and **Cancel**. The pause survives a relay
+  restart. A reset more than six hours away (a weekly limit) waits for you to
+  resume it.
+- A banner warns in Claude conversations when the usage passes 90 % of a
+  limit, with the time of the reset, and can be hidden until the next one.
+
+### Changed
+
+- **Remote relays:** agents on paired relays can now work with each other for
+  a whole session. A relay you mentioned stays in reach whatever prompts arrive
+  later, and a relay whose agent wrote to a conversation is open to it, so the
+  agent that was asked can answer, ask back or report later. Until now a prompt
+  from another relay's agent took the tool away for the rest of the turn, also
+  in a turn you had started yourself. A prompt that crossed two relays is still
+  not passed on to a third relay you did not unlock; reading and waiting are no
+  longer limited. After 30 prompts to other relays' agents without a message
+  from you, the next one asks you first.
+- Subagents are folded to their header inside the running turn, so a turn with
+  many of them stays short to scroll. The header says how many steps the
+  subagent has taken and shows the latest one, as far as there is room. A tap
+  on the header unfolds a subagent and folds it again; what you chose by hand
+  stays. The Stop button of a finished subagent is gone.
+- **Copilot, Cursor, Grok:** how long a turn may stay quiet now depends on what
+  the agent is doing: 2 minutes with nothing in flight, 5 minutes during a model
+  request, 30 minutes while a tool runs. Until now every silence of 2 minutes
+  failed the turn, including a command that simply printed nothing. The failure
+  note says how long the silence was and what was running. The three windows can
+  be set with `OAR_TURN_STALL_IDLE_MS`, `OAR_TURN_STALL_MODEL_MS` and
+  `OAR_TURN_STALL_TOOL_MS`.
+- **Copilot:** a turn kept past 2 minutes of silence is checked: a runtime that
+  no longer answers fails the turn at once. The watchdog also covers the start of
+  a session, where a runtime that did not answer used to hold the message without
+  any failure, and a Stop during that start now takes effect at once.
+- **Cursor:** a stalled run is cancelled, so the next message does not wait for
+  it.
+- A plan board is part of the reply it belongs to: its content and its buttons
+  are shown inside the agent's reply bubble (inside the running turn's bubble
+  until the reply is there) instead of on a card of their own at the end of the
+  transcript. When the reply already is the plan, the plan is shown once, with
+  the buttons below it. After you chose, the plan stays and the bubble says
+  what was chosen.
+- The choice on a plan board also sets the mode of the session: after
+  "Implement in autopilot" the composer says Autopilot, after "Stop here and
+  prompt myself" it says Agent, and the next message carries the work on. The
+  session used to stay in Plan, so the next message planned again. "Stop here"
+  leaves the mode as it is.
+
+### Fixed
+
+- A session worker that was idle and whose process has ended (stopped from
+  outside, or crashed between turns) is no longer listed as ready with its old
+  process id. The next message started a new worker before as well; the list
+  now says what is there, about a minute and a half after the process ended.
+- A reply that quotes or describes a failure note (an agent reporting on a
+  failed test, for example) is no longer taken for a failure itself. The relay
+  cut such a reply off at the quoted error code, put its own advice behind it
+  and stored the turn as failed. Where a failure is known from its text alone,
+  that text is now kept whole.
+- A single `~` in a reply ("about", as in "~35 s … ~7 min") no longer strikes
+  out the text up to the next one. Strikethrough needs two tildes on each side:
+  `~~text~~`. The page now names the version of its Markdown library (15.0.12,
+  the one it was served until now) instead of taking whatever the CDN hands out.
+- **Copilot:** a command the agent had started no longer runs on after its
+  runtime is gone. When the runtime died or was killed in the middle of a turn,
+  the turn failed as it should, but the command kept running with nobody left
+  to read its result. The relay now stops what such a runtime leaves behind
+  (first gently, then by force), and the failure note says that a command that
+  was still running is being stopped, as far as that is known at that moment:
+  the note comes at once and does not wait for the list of processes. A command
+  the agent started to outlive the session (`detach`) is left alone, and so are
+  the commands of a runtime that shuts down in good order.
+- **Grok:** a quiet-turn window that is set for the model request or for a tool
+  is kept when the shared watchdog is switched off by the environment, and the
+  watchdog looks often enough for the shortest window that is set.
+- **Windows:** stopping or deleting a session could end the worker of another
+  session as well. Windows hands the process id of an ended process out again,
+  and a worker whose creator was long gone could so look like a child of the
+  session that was being stopped. A process older than its parent is no longer
+  taken for its child, and the worker of another session never is.
+- **Copilot:** a message sent while a command is running no longer cuts the
+  command short. It waits until the running tool call has ended and is steered
+  in then; the composer reads "Queue" for as long. Sent at once, the message
+  made the runtime push the command to the background: the turn ended early
+  with the answer to the new message alone, or failed with "No response was
+  returned", and the command's result arrived later in a turn of its own.
+- A plan board's action ("Implement in autopilot" and the like) queues its
+  follow-up again. It failed with an error and left the board marked as acted
+  on, without the message that carries the plan out.
+- A finished subagent no longer turns back to "Running" in the running turn
+  when another line of activity arrives or the page reloads.
+- **Previews:** the first page load after a dev server was restarted no longer
+  ends in "The upstream connection failed: ECONNRESET". The preview lane keeps
+  its connections to the dev server, and the one it had kept was closed by the
+  restart. A request without a body is now sent once more on a connection of
+  its own: it reaches the restarted server, or the page says that nothing is
+  listening on the port.
+- Links in the file viewer and in plan boards have a colour that can be read in
+  dark mode; they used the browser's default blue.
+- A question or approval card no longer answers itself when the relay is
+  briefly unreachable, for example while it restarts. One failed check used to
+  end the wait: the agent was told to use its own judgement, or the approval
+  was refused, while the card stayed on screen. The wait now lasts through the
+  outage, for every provider.
+- **Copilot:** a turn that fails is reported at once. The failure used to wait
+  for the runtime to finish stopping, which took three minutes on a runtime that
+  had stopped answering; stopping it is now bounded, and the next message waits
+  for it before a new runtime starts.
+- **Copilot:** a failed turn keeps what the agent had written, above the failure
+  note. The note says how many tool calls ran and that their changes are still in
+  place, and it no longer advises restarting the relay. A message steered into
+  the failed turn gets a short marker with Resend instead of a second copy of
+  the failure.
+- **Copilot:** a slow relay no longer makes a busy runtime look silent.
+- **Copilot:** a reply the relay could not take (it was restarting, the
+  connection was reset) is offered again for up to five minutes. One failed
+  attempt used to put the message back in the queue, which threw the finished
+  answer away and ran the prompt a second time. A reply that cannot be saved at
+  all ends as a failure that says so, and nothing is run twice.
+- **Copilot:** what the agent does by itself after a background task (a
+  continuation) is kept while the relay restarts. Its row was given up after
+  about a second, and the whole reply with it.
+- **Copilot:** a relay that accepts live output and does not answer no longer
+  holds the turn: a live update waits 10 seconds at most, and after one that
+  ran out, live updates are skipped for 30 seconds. Tool lines skipped then are
+  missing from the transcript; the reply is not affected.
+- **Copilot:** Stop works on a turn that is stuck. A runtime that does not
+  answer the Stop within 10 seconds is ended with the turn, and a turn the user
+  stopped ends as stopped even when the runtime died or went silent after it.
+- **Copilot:** a runtime that exits, or stops answering, while the agent works
+  by itself after a background task is cleared away; the next message used to
+  fail on it. A lost connection during a model change is reported as that, not
+  as "pick another model".
+- **Copilot:** a failed turn tells its failure once. A message sent into the
+  turn that the agent had not started on gets the short marker with Resend,
+  like one it had taken in.
+- **Copilot:** background agents and shells are no longer closed with the
+  runtime because its list of them could not be read.
+- **Stop button:** Stop keeps working for a message that waits on a question
+  card while the agent starts and finishes other work, and for a second message
+  stopped while the same turn goes on. It used to do nothing in both cases.
+- **Copilot:** a turn the runtime itself ended with an error no longer tells
+  you to restart the relay. The worker starts a fresh runtime by itself; a
+  restart repairs nothing and costs every other running session.
+- The note under a failed turn no longer advises restarting the relay: a restart
+  repairs nothing there and interrupts every other running session. It now says
+  to send the message again and to include the error code in a report.
+- **Claude:** a turn the Claude account refuses (billing, an expired sign-in,
+  access the organisation has switched off) says to check the account or to sign
+  in again in Settings → Providers → Claude, with a button that opens the panel,
+  instead of "Retry the message". Its error code names the failure, for example
+  `relay.claude-billing-error`; it used to read `relay.claude-success`.
+
 ## [0.9.5] — 2026-09-27
 
 Highlights: a Claude reply on the wrong row no longer blocks the conversation,

package/README.md

@@ -78,7 +78,7 @@ curl -fsSL oar.sh/install | sh
 The script checks for Node.js 22.13 or newer, runs `npm install -g @oar-sh/oar`, and then hands off to `oar setup` (with `--defaults` when there is no terminal to ask questions in). It refuses to run as root, because OAR installs per user. `OAR_VERSION=x.y.z` pins a version, `OAR_CHANNEL=beta` follows the beta channel, and `OAR_DRY_RUN=1` only prints what it would do:
 
 ```bash
-curl -fsSL oar.sh/install | OAR_VERSION=0.9.5 sh
+curl -fsSL oar.sh/install | OAR_VERSION=0.9.6 sh
 ```
 
 Read it before you run it: [oar.sh/install](https://oar.sh/install).
@@ -89,7 +89,7 @@ Read it before you run it: [oar.sh/install](https://oar.sh/install).
 irm oar.sh/install.ps1 | iex
 ```
 
-The PowerShell installer (PowerShell 5 or newer) does the same: it checks Node.js, runs `npm install -g @oar-sh/oar`, then `oar setup`. It reads the same `OAR_VERSION`, `OAR_CHANNEL`, and `OAR_DRY_RUN` variables, for example `$env:OAR_VERSION = '0.9.5'` before the command.
+The PowerShell installer (PowerShell 5 or newer) does the same: it checks Node.js, runs `npm install -g @oar-sh/oar`, then `oar setup`. It reads the same `OAR_VERSION`, `OAR_CHANNEL`, and `OAR_DRY_RUN` variables, for example `$env:OAR_VERSION = '0.9.6'` before the command.
 
 ### npm
 
@@ -326,6 +326,15 @@ Use **🤗 Select Models** to choose which variants show up in the composer, the
 
 ## Highlights
 
+### New in 0.9.6
+
+- **Claude pauses at the usage limit**: a turn that runs into the subscription's usage limit is paused instead of failed. A banner above the composer says when it carries on, with **Resume now** and **Cancel**; after the reset the relay sends a message of its own that quotes what was refused. The pause survives a relay restart, and a reset more than six hours away waits for you. A second banner warns when the usage passes 90 % of a limit.
+- **A quiet command no longer fails its turn** (Copilot, Cursor, Grok): how long a turn may stay silent depends on what the agent is doing: 2 minutes with nothing in flight, 5 minutes during a model request, 30 minutes while a tool runs.
+- **Copilot turns that fail, fail well**: the failure shows at once, what the agent had written stays above the note, Stop works on a stuck turn, a finished reply survives a relay restart, and the commands of a runtime that died are stopped. A message you send while a command runs waits for the command instead of cutting it short.
+- **Agents on paired relays can answer each other**: a relay you mentioned stays in reach for the whole session, and an agent that was asked from another relay can answer, ask back or report later. See [Remote relays](#remote-relays).
+- **Less scrolling in a running turn**: subagents are folded to a one-line header that says what they are doing, and a plan board sits inside the reply it belongs to; its choice also sets the session's mode.
+- **Failure notes that help**: no more advice to restart the relay, and a Claude account problem (billing, sign-in, access) says what to check. The relay keeps its console in `relay-console.log`.
+
 ### New in 0.9.5
 
 - **A misplaced Claude reply no longer blocks the conversation**: when a reply is published as a *background continuation* instead of under your message, the message closes after about 45 seconds of silence with a small note naming that reply, and the next message runs normally. It used to hold every later message for up to 5 minutes.
@@ -677,8 +686,15 @@ locked in a conversation until you mention it in one of your messages: type `@`
 from the list, or write its name or its host name. An IP address or `localhost` never counts as a
 host name; a relay whose name is itself an address is unlocked only with a leading `@`. The
 mention unlocks that relay for the rest of
-the conversation. Prompts that arrive from another relay's agent never unlock anything, and a
-chain of relays prompting relays stops after two hops.
+the conversation, whatever prompts arrive in it later.
+
+**Agents can answer each other.** When an agent on a paired relay writes to a conversation, that
+relay is open to the conversation from then on, within what **Agents may** allows, so the agent
+that was asked can answer, ask back or report later. A prompt from an agent never unlocks any
+other relay. A prompt that already crossed two relays is not passed on to a third one unless you
+unlocked that relay yourself; reading and waiting are never limited. When the agent of a
+conversation has sent 30 prompts to agents on other relays without a message from you, the next
+one asks you first with a question card; **Allow** starts the count again.
 
 **What agents can do.** Every provider gets the same `remote_relay` tool (Claude, Cursor and
 Copilot directly; Grok and the Copilot extension engine through OAR's MCP server). Per paired

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oar-sh/oar",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "type": "module",
   "description": "OAR — Open Agent Relay: drive your local coding agents from any browser",
   "license": "MIT",
@@ -30,6 +30,7 @@
     "server/uploads/image_input.md",
     "shared/",
     "!shared/**/*.test.mjs",
+    "!shared/**/*-test-harness.mjs",
     "!shared/**/fixtures/",
     ".github/extensions/web-relay/",
     "!.github/extensions/web-relay/**/*.test.mjs",

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

@@ -37,6 +37,7 @@ import {
 import { createAskUserBridge } from '../../shared/ask-user-bridge.mjs';
 import { createRemoteRelayToolGate } from '../../shared/remote-relay-tool-core.mjs';
 import { buildRelayStopFailure } from '../../shared/relay-stop-failure.mjs';
+import { createTurnLiveness, resolveTurnStallWindows } from '../../shared/worker-runtime/turn-liveness.mjs';
 import {
   ANSWERED_ELSEWHERE_KIND,
   DELIVERY_ANSWERED_ELSEWHERE_TEXT,
@@ -49,6 +50,7 @@ import {
   stripSlashCommandGuardContent,
   withSlashCommandGuardContent,
 } from '../../shared/slash-command-guard.mjs';
+import { createUsageLimitTracker } from '../../shared/claude-usage-limit.mjs';
 
 /**
  * Which system-prompt append a relay mode gets (claude-sdk-adapter's
@@ -451,6 +453,10 @@ export function createClaudeSessionRunner({
   // next delivery.
   getThinking = () => ({ enabled: null, display: '' }),
   lifecyclePollMs = 5_000,
+  // How long a RUNNING turn may go without a message from the CLI before
+  // that is written to the log. Nothing is failed over it: see
+  // `noteQuietTurn`. `{ model, tool }` in ms; 0 for either turns it off.
+  quietTurnWindowsMs = undefined,
   // A settled task's continuation normally begins within ~1s; when nothing
   // arrives inside this window the notification was silent (skip_transcript)
   // and must stop pinning the process.
@@ -546,6 +552,9 @@ export function createClaudeSessionRunner({
   // fixed per process, and the first delivery can beat the startup GET.
   const remoteRelayGate = remoteRelayToolGate || createRemoteRelayToolGate({ api });
   void remoteRelayGate.refresh();
+  // The subscription's usage limit as the CLI reports it. Runner-level: the
+  // limit is the account's, not the CLI process's.
+  const usageLimit = createUsageLimitTracker();
   const resolveWorkflowSessionDir = resolveWorkflowSessionDirImpl || createDefaultWorkflowSessionDirResolver();
   let claudeNativeSessionId = '';
   let proc = null;
@@ -2475,6 +2484,90 @@ export function createClaudeSessionRunner({
     return 'swallow';
   }
 
+  // ---------------------------------------------------------------------------
+  // A running turn that went quiet
+  //
+  // The other workers fail a turn whose runtime has been silent for too long
+  // (shared/worker-runtime/turn-liveness.mjs). This one only WRITES IT DOWN.
+  // What the CLI sends is known (SDK 0.3.283, measured 2026-09-28): a
+  // `tool_progress` heartbeat every 30 s while a tool runs in silence, for the
+  // Agent call as a whole when the tool runs inside a subagent; a
+  // `thinking_tokens` or stream frame about every second while the model
+  // works. What is not known is how long its silent stretches get in real
+  // sessions: a compaction (133 s seen), the backoff of an API retry, a
+  // request it is waiting on. Failing a turn here also means killing the CLI
+  // and its background tasks. So the windows are generous, the known silent
+  // stretches are holds, and a turn that outlasts them is logged with what
+  // the CLI was doing — the measurements a failing watchdog would need.
+
+  const quietWindows = (() => {
+    const windows = resolveTurnStallWindows({
+      // The CLI gives up on a silent model stream by itself after 300 s and
+      // says so (`api_retry`); a window of the same length would race it.
+      modelMs: quietTurnWindowsMs?.model ?? process.env.OAR_TURN_STALL_MODEL_MS ?? 600_000,
+      toolMs: quietTurnWindowsMs?.tool,
+    });
+    return { idle: 0, model: windows.model, tool: windows.tool };
+  })();
+
+  function observeQuietTurn(sdkMessage) {
+    const liveness = proc?.liveness;
+    if (!liveness) return;
+    const type = String(sdkMessage?.type || '');
+    const agent = String(sdkMessage?.parent_tool_use_id || '').trim() || 'root';
+    if (proc.quietLoggedAt) {
+      dbg(`the CLI spoke again after ${Math.round(liveness.quietMs() / 1000)}s of silence`, type);
+      proc.quietLoggedAt = 0;
+    }
+    liveness.traffic(type === 'system' ? `system/${sdkMessage?.subtype || ''}` : type);
+    const blocks = Array.isArray(sdkMessage?.message?.content) ? sdkMessage.message.content : [];
+    if (type === 'assistant') {
+      for (const block of blocks) {
+        if (block?.type === 'tool_use' && block.id) liveness.begin('tool', `${agent}:${block.id}`, block.name);
+      }
+    } else if (type === 'user') {
+      for (const block of blocks) {
+        if (block?.type !== 'tool_result' || !block.tool_use_id) continue;
+        liveness.end('tool', `${agent}:${block.tool_use_id}`);
+        // The result of an Agent call: whatever that agent had open ended with it.
+        liveness.endAgent(String(block.tool_use_id));
+      }
+    } else if (type === 'stream_event') {
+      const event = String(sdkMessage?.event?.type || '');
+      if (event === 'message_start') liveness.begin('model', agent);
+      else if (event === 'message_stop') liveness.end('model', agent);
+    } else if (type === 'result') {
+      liveness.reset();
+    }
+  }
+
+  /**
+   * Log a running turn the CLI has said nothing in for longer than its phase
+   * allows. Once per silence, and never while the silence has a known reason.
+   */
+  function noteQuietTurn() {
+    const liveness = proc?.liveness;
+    const ctx = proc?.activeCtx;
+    if (!liveness || !ctx || ctx.finalized || proc.closing || proc.quietLoggedAt) return;
+    // A human is deciding, a compaction is running, the relay is slow to take
+    // a publish (the stream is not read meanwhile), or the turn is being
+    // stopped: silence with a reason.
+    if (proc.pendingControlRequests > 0 || isCompacting() || proc.dispatching > 0 || ctx.interrupted) {
+      liveness.traffic('held');
+      return;
+    }
+    // Inside a turn the CLI is waiting for the model unless a tool is open.
+    const phase = liveness.phase() === 'tool' ? 'tool' : 'model';
+    const limitMs = quietWindows[phase];
+    if (!(limitMs > 0) || liveness.quietMs() < limitMs) return;
+    proc.quietLoggedAt = Date.now();
+    dbg(
+      `running turn quiet for ${Math.round(liveness.quietMs() / 1000)}s; left running (the quiet-turn watchdog only observes)`,
+      ctx.message?.id || '(continuation)',
+      liveness.describe(),
+    );
+  }
+
   async function onSdkMessage(processRef, sdkMessage) {
     // A superseded process (push-race respawn, mode-recycle timeout) may still
     // be draining its stream; its late messages must not mutate the state of
@@ -2482,6 +2575,21 @@ export function createClaudeSessionRunner({
     // cleanupProcess when the old stream ends.
     if (!proc || proc !== processRef) return;
     proc.lastEventAt = Date.now();
+    observeQuietTurn(sdkMessage);
+    // Counted for as long as this message is being handled: the stream is
+    // not read meanwhile, so the silence is this worker's, not the CLI's.
+    processRef.dispatching += 1;
+    try {
+      await handleSdkMessage(sdkMessage);
+    } finally {
+      processRef.dispatching -= 1;
+      if (proc === processRef) proc.liveness.traffic('handled');
+    }
+  }
+
+  async function handleSdkMessage(sdkMessage) {
+    const usageLimitReport = usageLimit.observe(sdkMessage);
+    if (usageLimitReport) publisher.publishUsageLimitReport({ conversationId: sdkSessionId, sdkSessionId, report: usageLimitReport });
     const suppressed = maybeSuppressStopFollowUp(sdkMessage);
     if (suppressed === 'swallow') return;
     observeProcessLevel(sdkMessage);
@@ -2502,6 +2610,8 @@ export function createClaudeSessionRunner({
     if (!ctx) return;
     const actions = ctx.normalizer.normalize(sdkMessage);
     for (const action of actions) {
+      // Decided here, while the reports the turn ran under are the latest.
+      if (action.channel === 'result') action.payload.usageLimit = usageLimit.classifyResult(sdkMessage);
       await dispatchToContext(ctx, action);
     }
   }
@@ -2917,6 +3027,7 @@ export function createClaudeSessionRunner({
     if (proc.stopFollowUp && !proc.suppressingTurn && !proc.pendingDelivered.some((entry) => entry.stoppedWithTurn)) {
       proc.stopFollowUp = null;
     }
+    noteQuietTurn();
     reapSilentProvisionalAdoption(now);
     // Before the 5-minute watchdog: a folded steered entry settles as merged
     // within the short fold grace instead of failing over.
@@ -3030,6 +3141,7 @@ export function createClaudeSessionRunner({
           await publisher.publishTurnException({
             message: ctx.message,
             errorText: String(streamError?.message || streamError || 'unknown error'),
+            usageLimit: usageLimit.classifyException(streamError),
           }).catch(() => {});
         }
         continue;
@@ -3132,6 +3244,11 @@ export function createClaudeSessionRunner({
       settleSeqAtContinuationOpen: 0,
       pendingControlRequests: 0,
       lastEventAt: Date.now(),
+      // The quiet-turn log (see noteQuietTurn): what the CLI has in flight,
+      // messages being handled right now, and when the silence was logged.
+      liveness: createTurnLiveness({ windows: quietWindows }),
+      dispatching: 0,
+      quietLoggedAt: 0,
       heldForTasksSince: 0,
       taskSettledAt: 0,
       // Bumped by every task-settle signal; the Stop guard compares it.
@@ -3631,7 +3748,7 @@ export function createClaudeSessionRunner({
       settingsWindowOpen = false;
       const errorText = String(error?.message || error || 'unknown error');
       dbg('claude turn failed', message.id, errorText);
-      await publisher.publishTurnException({ message, errorText });
+      await publisher.publishTurnException({ message, errorText, usageLimit: usageLimit.classifyException(error) });
       return true;
     } finally {
       endAdmission();

package/server/claude-worker/claude-turn-failure.mjs

@@ -0,0 +1,92 @@
+// Why a Claude turn failed: the code the relay prints, and the advice that
+// fits the failure.
+//
+// A turn the API refused ends with a `result` of subtype 'success' and
+// `is_error: true`: the subtype says how the turn ended, not whether it
+// worked, so it names nothing. What names the failure, in this order:
+//
+//   1. the `error` field of the turn's last assistant message (the SDK's
+//      SDKAssistantMessageError: 'billing_error', 'oauth_org_not_allowed', …);
+//   2. the `api_error_status` of the result;
+//   3. the words of the refusal, for an account failure that came with
+//      neither;
+//   4. a subtype other than 'success' ('error_max_turns', …);
+//   5. the `terminal_reason` of the result.
+//
+// The relay prints `claude.<code>` as `relay.claude-<code>`, dashes for
+// underscores.
+
+// The user has to sign in again: a retry cannot succeed before that.
+const SIGN_IN_ERRORS = new Set(['authentication_failed']);
+// The account itself refuses: billing, or access its organisation withholds.
+const ACCOUNT_ERRORS = new Set([
+  'billing_error',
+  'oauth_org_not_allowed',
+  'account_on_hold',
+  'verification_required',
+  'account-access',
+]);
+
+const STATUS_CODES = new Map([
+  [401, 'authentication_failed'],
+  [402, 'billing_error'],
+  [429, 'rate_limit'],
+  [529, 'overloaded'],
+]);
+
+// Checked before the sign-in words: the organisation's refusal mentions an
+// API key too.
+const ACCOUNT_ACCESS_TEXT = /organi[sz]ation has disabled|subscription access|does not have access to claude/i;
+const BILLING_TEXT = /credit balance|billing|payment/i;
+const SIGN_IN_TEXT = /failed to authenticate|authentication_error|invalid api key|not logged in|please run \/login/i;
+
+export const CLAUDE_SIGN_IN_GUIDANCE =
+  'Sign in to Claude again in Settings → Providers → Claude → Relogin (or run `claude` on the relay host), '
+  + 'then send the message again.';
+export const CLAUDE_ACCOUNT_GUIDANCE =
+  'Check the Claude account the relay host is signed in to: its subscription, its payment method, and whether '
+  + 'its organisation allows Claude Code. Settings → Providers → Claude shows the account and signs in to '
+  + 'another one. Then send the message again.';
+export const CLAUDE_MODEL_GUIDANCE = 'Choose another model for this conversation, then send the message again.';
+
+function codeFromText(text) {
+  if (ACCOUNT_ACCESS_TEXT.test(text)) return 'account-access';
+  if (BILLING_TEXT.test(text)) return 'billing_error';
+  if (SIGN_IN_TEXT.test(text)) return 'authentication_failed';
+  return null;
+}
+
+/** The advice for a code, or null where the relay's own default fits. */
+export function claudeFailureGuidance(code) {
+  const token = String(code || '').trim().toLowerCase();
+  if (SIGN_IN_ERRORS.has(token)) return CLAUDE_SIGN_IN_GUIDANCE;
+  if (ACCOUNT_ERRORS.has(token)) return CLAUDE_ACCOUNT_GUIDANCE;
+  if (token === 'model_not_found') return CLAUDE_MODEL_GUIDANCE;
+  return null;
+}
+
+/**
+ * `result` is the normalized result payload of the turn (sdk-message-
+ * normalizer): `{ text, subtype, assistantError, apiErrorStatus,
+ * terminalReason }`. Returns `{ code, stableCode, guidance }`; `guidance` is
+ * null where the relay's default fits.
+ */
+export function classifyClaudeResultFailure(result = {}) {
+  const subtype = String(result?.subtype || '').trim();
+  const assistantError = String(result?.assistantError || '').trim().toLowerCase();
+  const status = Number(result?.apiErrorStatus);
+  const hasStatus = Number.isFinite(status) && status >= 400;
+  const terminalReason = String(result?.terminalReason || '').trim().toLowerCase();
+
+  let code = null;
+  if (assistantError && assistantError !== 'unknown') code = assistantError;
+  else if (hasStatus && STATUS_CODES.has(status)) code = STATUS_CODES.get(status);
+  else code = codeFromText(String(result?.text || ''));
+
+  if (!code && subtype && subtype !== 'success') code = subtype;
+  if (!code && (hasStatus || assistantError === 'unknown' || terminalReason === 'api_error')) code = 'api-error';
+  if (!code && terminalReason && terminalReason !== 'completed') code = terminalReason;
+  if (!code) code = 'turn-error';
+
+  return { code, stableCode: `claude.${code}`, guidance: claudeFailureGuidance(code) };
+}