@oar-sh/oar 0.9.19 → 0.9.21

package/server/migrations/0036-token-usage.mjs

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * Migration: tokens per turn for every provider, and their daily sums
+ * (services/token-usage-service.mjs, the Tokens sections in Check Usage and
+ * the About panel).
+ *
+ * `turn_token_usage`: one row per turn, run and model, kept with the chat
+ * and deleted with it.
+ * - `conversation_id`; `turn_id`: the queue row id (the user message's id);
+ *   no foreign key, as queue rows are pruned.
+ * - `run_id`: the worker process or attempt ('' for none), so a re-run after
+ *   a crash keeps the first attempt's row.
+ * - `model`: lower case, without `[1m]`. `provider`: the relay's provider
+ *   kind. `billing`: '' or `byok-<provider type>` (Copilot's own key).
+ * - `native_session_id`, `response_message_id`: NULL when not known.
+ * - `at`: the turn's first report (ISO); `day`: its relay local date
+ *   (`YYYY-MM-DD`), fixed at the first report.
+ * - `input_tokens` (fresh input, no cache), `output_tokens`,
+ *   `cache_write_tokens`, `cache_read_tokens`, `reasoning_tokens` (part of
+ *   output): NULL when the provider did not report the field; 0 when it
+ *   reported zero.
+ * - `cost_usd` (NULL when not known), `cost_source` (`claude-code`,
+ *   `provider`, `oar-deepseek-table`), `cost_unknown`.
+ *
+ * `token_usage_days`: the sums per day, provider, billing, model and source
+ * (`turns`, or `backfill` for the copy below). Its rows survive the chats.
+ * A token field stays NULL until some turn reports it, then it is a sum.
+ *
+ * Backfill, in the transaction that creates the tables (a `token_usage_days`
+ * table that exists means it ran): the Claude API totals (0034, local days)
+ * and DeepSeek's days (0025, UTC days, kept as they are) are copied with
+ * `source='backfill'`. Their `miss_tokens` become `input_tokens` (cache
+ * writes included: the views say so), `hit_tokens` `cache_read_tokens`, and
+ * `cache_write_tokens` stays NULL. Model ids are normalised as above, and
+ * rows that meet on one key are summed. DeepSeek's `cost_usd` is the token
+ * estimate alone (its tools cost stays on the DeepSeek card; a NULL stays
+ * NULL), and its days keep no seen times, so the day's bounds stand in. A
+ * source that 0034's or 0025's own check finds missing or partial (its
+ * migration failed this boot) makes this one throw, so the schema boot logs
+ * it and retries on the next boot once the source is there.
+ *
+ * Additive and idempotent. Safe to run on every boot.
+ *
+ * Usage: node server/migrations/0036-token-usage.mjs [path/to/oar.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+import { cliDbPath } from '../services/database-file.mjs';
+
+import { CLAUDE_API_USAGE_TOTALS_TABLE, claudeApiUsageTotalsProblem } from './0034-claude-api-usage-totals.mjs';
+import { DEEPSEEK_USAGE_DAYS_TABLE, deepseekUsageRequestsDailyProblem } from './0025-deepseek-usage-requests-daily.mjs';
+
+export const TURN_TOKEN_USAGE_TABLE = 'turn_token_usage';
+export const TOKEN_USAGE_DAYS_TABLE = 'token_usage_days';
+export const TURN_TOKEN_USAGE_INDEXES = Object.freeze([
+  'idx_turn_token_usage_conversation',
+  'idx_turn_token_usage_native_session',
+]);
+
+export const TURN_TOKEN_USAGE_COLUMNS = Object.freeze([
+  'conversation_id',
+  'turn_id',
+  'run_id',
+  'model',
+  'provider',
+  'billing',
+  'native_session_id',
+  'response_message_id',
+  'at',
+  'day',
+  'input_tokens',
+  'output_tokens',
+  'cache_write_tokens',
+  'cache_read_tokens',
+  'reasoning_tokens',
+  'cost_usd',
+  'cost_source',
+  'cost_unknown',
+  'updated_at',
+]);
+
+export const TOKEN_USAGE_DAYS_COLUMNS = Object.freeze([
+  'day',
+  'provider',
+  'billing',
+  'model',
+  'source',
+  'input_tokens',
+  'output_tokens',
+  'cache_write_tokens',
+  'cache_read_tokens',
+  'reasoning_tokens',
+  'cost_usd',
+  'unknown_cost_tokens',
+  'turn_count',
+  'first_seen_at',
+  'last_seen_at',
+  'updated_at',
+]);
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function missingColumns(db, table, expected) {
+  const present = new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+  return expected.filter((name) => !present.has(name));
+}
+
+/** What keeps the service from using the tables: '' when nothing does. */
+export function tokenUsageProblem(db) {
+  for (const [table, expected] of [
+    [TURN_TOKEN_USAGE_TABLE, TURN_TOKEN_USAGE_COLUMNS],
+    [TOKEN_USAGE_DAYS_TABLE, TOKEN_USAGE_DAYS_COLUMNS],
+  ]) {
+    if (!tableExists(db, table)) return `no ${table} table`;
+    const missing = missingColumns(db, table, expected);
+    if (missing.length) return `${table} lacks ${missing.join(', ')}`;
+  }
+  return '';
+}
+
+// The tables' model id: lower case, without the `[1m]` suffix
+// (shared/turn-token-usage.mjs), in SQL.
+const BOOKED_MODEL_SQL = `CASE WHEN LOWER(TRIM(model)) LIKE '%[1m]' THEN SUBSTR(LOWER(TRIM(model)), 1, LENGTH(TRIM(model)) - 4) ELSE LOWER(TRIM(model)) END`;
+
+// Two source rows can land on one key once their model ids are normalised:
+// they are summed, null-aware.
+const BACKFILL_UPSERT = `
+  ON CONFLICT (day, provider, billing, model, source) DO UPDATE SET
+    input_tokens = CASE WHEN excluded.input_tokens IS NULL THEN input_tokens ELSE COALESCE(input_tokens, 0) + excluded.input_tokens END,
+    output_tokens = CASE WHEN excluded.output_tokens IS NULL THEN output_tokens ELSE COALESCE(output_tokens, 0) + excluded.output_tokens END,
+    cache_read_tokens = CASE WHEN excluded.cache_read_tokens IS NULL THEN cache_read_tokens ELSE COALESCE(cache_read_tokens, 0) + excluded.cache_read_tokens END,
+    cost_usd = CASE WHEN excluded.cost_usd IS NULL THEN cost_usd ELSE COALESCE(cost_usd, 0) + excluded.cost_usd END,
+    unknown_cost_tokens = unknown_cost_tokens + excluded.unknown_cost_tokens,
+    turn_count = turn_count + excluded.turn_count,
+    first_seen_at = MIN(first_seen_at, excluded.first_seen_at),
+    last_seen_at = MAX(last_seen_at, excluded.last_seen_at)
+`;
+
+export function migrateTokenUsage(db, { now = () => new Date().toISOString() } = {}) {
+  return db.transaction(() => {
+    let tablesAdded = 0;
+    const backfilled = { claudeApi: 0, deepseek: 0 };
+    // Done means both tables exist, checked inside the transaction.
+    if (tableExists(db, TOKEN_USAGE_DAYS_TABLE) && tableExists(db, TURN_TOKEN_USAGE_TABLE)) {
+      return { applied: false, tablesAdded, backfilled };
+    }
+    if (!tableExists(db, TURN_TOKEN_USAGE_TABLE)) {
+      db.exec(`
+        CREATE TABLE ${TURN_TOKEN_USAGE_TABLE} (
+          conversation_id      TEXT NOT NULL,
+          turn_id              TEXT NOT NULL,
+          run_id               TEXT NOT NULL DEFAULT '',
+          model                TEXT NOT NULL,
+          provider             TEXT NOT NULL,
+          billing              TEXT NOT NULL DEFAULT '',
+          native_session_id    TEXT,
+          response_message_id  TEXT,
+          at                   TEXT NOT NULL,
+          day                  TEXT NOT NULL,
+          input_tokens         INTEGER,
+          output_tokens        INTEGER,
+          cache_write_tokens   INTEGER,
+          cache_read_tokens    INTEGER,
+          reasoning_tokens     INTEGER,
+          cost_usd             REAL,
+          cost_source          TEXT,
+          cost_unknown         INTEGER NOT NULL DEFAULT 0,
+          updated_at           TEXT NOT NULL,
+          PRIMARY KEY (turn_id, run_id, model)
+        );
+        CREATE INDEX IF NOT EXISTS ${TURN_TOKEN_USAGE_INDEXES[0]} ON ${TURN_TOKEN_USAGE_TABLE} (conversation_id, at);
+        CREATE INDEX IF NOT EXISTS ${TURN_TOKEN_USAGE_INDEXES[1]} ON ${TURN_TOKEN_USAGE_TABLE} (native_session_id);
+      `);
+      tablesAdded += 1;
+    }
+    if (!tableExists(db, TOKEN_USAGE_DAYS_TABLE)) {
+      // The copy needs both sources as 0034 and 0025 leave them; a missing or
+      // partial one (its migration failed this boot) waits for the next boot.
+      for (const problem of [claudeApiUsageTotalsProblem(db), deepseekUsageRequestsDailyProblem(db)]) {
+        if (problem) throw new Error(`cannot backfill yet: ${problem}`);
+      }
+      db.exec(`
+        CREATE TABLE ${TOKEN_USAGE_DAYS_TABLE} (
+          day                  TEXT NOT NULL,
+          provider             TEXT NOT NULL,
+          billing              TEXT NOT NULL DEFAULT '',
+          model                TEXT NOT NULL,
+          source               TEXT NOT NULL,
+          input_tokens         INTEGER,
+          output_tokens        INTEGER,
+          cache_write_tokens   INTEGER,
+          cache_read_tokens    INTEGER,
+          reasoning_tokens     INTEGER,
+          cost_usd             REAL,
+          unknown_cost_tokens  INTEGER NOT NULL DEFAULT 0,
+          turn_count           INTEGER NOT NULL DEFAULT 0,
+          first_seen_at        TEXT NOT NULL,
+          last_seen_at         TEXT NOT NULL,
+          updated_at           TEXT NOT NULL,
+          PRIMARY KEY (day, provider, billing, model, source)
+        )
+      `);
+      tablesAdded += 1;
+      const at = now();
+      const columns = `
+        day, provider, billing, model, source,
+        input_tokens, output_tokens, cache_write_tokens, cache_read_tokens, reasoning_tokens,
+        cost_usd, unknown_cost_tokens, turn_count, first_seen_at, last_seen_at, updated_at
+      `;
+      // `WHERE true`: SQLite's parser needs it before an upsert on a SELECT.
+      backfilled.claudeApi = db.prepare(`
+        INSERT INTO ${TOKEN_USAGE_DAYS_TABLE} (${columns})
+        SELECT day, 'claude-api', '', ${BOOKED_MODEL_SQL}, 'backfill',
+          miss_tokens, output_tokens, NULL, hit_tokens, NULL,
+          cost_usd, COALESCE(unknown_cost_tokens, 0), COALESCE(turn_count, 0), first_seen_at, last_seen_at, ?
+        FROM ${CLAUDE_API_USAGE_TOTALS_TABLE} WHERE true
+        ${BACKFILL_UPSERT}
+      `).run(at).changes;
+      // DeepSeek's days keep no seen times: the day's start and end stand in
+      // (UTC days). Its token estimate only, in dollars; no unknown tokens.
+      backfilled.deepseek = db.prepare(`
+        INSERT INTO ${TOKEN_USAGE_DAYS_TABLE} (${columns})
+        SELECT day, 'deepseek', '', ${BOOKED_MODEL_SQL}, 'backfill',
+          miss_tokens, output_tokens, NULL, hit_tokens, NULL,
+          cost_usd, 0, COALESCE(turn_count, 0), day || 'T00:00:00.000Z', day || 'T23:59:59.999Z', ?
+        FROM ${DEEPSEEK_USAGE_DAYS_TABLE} WHERE true
+        ${BACKFILL_UPSERT}
+      `).run(at).changes;
+    }
+    return { applied: true, tablesAdded, backfilled };
+  })();
+}
+
+export function migrate(dbPath, options = {}) {
+  const db = new Database(dbPath, options);
+  try {
+    return migrateTokenUsage(db);
+  } finally {
+    db.close();
+  }
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    // The given path, else the database in server/data (oar.db, else the
+    // name before 0.9.20); never a new one.
+    const dbPath = cliDbPath(process.argv[2], new URL('..', import.meta.url));
+    const result = migrate(dbPath);
+    console.log(`Migration 0036 on ${dbPath}`);
+    console.log(result.applied
+      ? `  token usage: tables added ${result.tablesAdded}, backfilled days: claude api ${result.backfilled.claudeApi}, deepseek ${result.backfilled.deepseek}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0036 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}

package/server/public/app/about-ui.js

@@ -1,4 +1,4 @@
-// ⋯ → About OAR: the menu entry's label and the modal (about-view.mjs builds
+// ︙ → About OAR: the menu entry's label and the modal (about-view.mjs builds
 // its HTML from GET /api/about).
 
 import {

package/server/public/app/about-view.mjs

@@ -13,9 +13,18 @@ const STATE_LABELS = Object.freeze({
 
 const USAGE_LABELS = Object.freeze({
   github: 'GitHub Copilot',
+  claude: 'Claude',
+  'claude-api': 'Claude API',
+  'claude-cloud': 'Claude Cloud',
   cursor: 'Cursor',
   grok: 'Grok',
-  'claude-cloud': 'Claude Cloud',
+  deepseek: 'DeepSeek',
+});
+
+const OWN_KEY_LABELS = Object.freeze({
+  'byok-openai': 'OpenAI',
+  'byok-anthropic': 'Anthropic',
+  'byok-azure': 'Azure OpenAI',
 });
 
 function esc(value) {
@@ -133,11 +142,67 @@ function providerState(provider) {
   return `<span class="about-state" data-state="${esc(state)}">${esc(STATE_LABELS[state])}</span>${esc(count)}`;
 }
 
+// A token count of the token booking: "—" where no turn reported it.
+function knownCount(value) {
+  return value === null || value === undefined || value === '' ? null : finite(value);
+}
+
+function tokenAmount(value) {
+  return knownCount(value) === null ? '—' : formatAmount(value);
+}
+
+/**
+ * "Oct 29, 2026" for a `YYYY-MM-DD` day, as Check Usage writes it, joined
+ * by no-break spaces so a phone never wraps inside it.
+ */
+export function aboutDayLabel(day) {
+  const date = new Date(`${day}T00:00:00.000Z`);
+  if (!day || Number.isNaN(date.getTime())) return String(day || '');
+  return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric', timeZone: 'UTC' }).replace(/ /g, '\u00a0');
+}
+
+/**
+ * The all-time tokens: their sum, and the four kinds with the first day.
+ * Days copied at the upgrade (Claude API, DeepSeek) hold cache writes inside
+ * input, and the hint says until when.
+ */
+function tokenRow(label, tokens) {
+  const fields = [tokens.inputTokens, tokens.outputTokens, tokens.cacheWriteTokens, tokens.cacheReadTokens];
+  const known = fields.map(knownCount).filter((value) => value !== null);
+  const total = known.length ? known.reduce((sum, value) => sum + value, 0) : null;
+  const parts = [`in ${tokenAmount(tokens.inputTokens)} · out ${tokenAmount(tokens.outputTokens)} · cache w ${tokenAmount(tokens.cacheWriteTokens)} · cache r ${tokenAmount(tokens.cacheReadTokens)}`];
+  if (tokens.since) parts.push(`since ${aboutDayLabel(tokens.since)}`);
+  if (tokens.backfilled) {
+    parts.push(tokens.firstTurnsDay
+      ? `input includes cache writes before ${aboutDayLabel(tokens.firstTurnsDay)}`
+      : 'input includes cache writes (days from before the upgrade)');
+  }
+  // One unbroken part: on a phone the unit stays with its number (the
+  // section's values otherwise wrap anywhere, for paths).
+  return row(label, `<span class="plan-usage-detail-part">${esc(tokenAmount(total))}</span>`, { hint: parts.join(' · ') });
+}
+
+function tokenRows(usage) {
+  const rows = [];
+  if (usage.tokens) rows.push(tokenRow('Tokens (all time)', usage.tokens));
+  for (const entry of Array.isArray(usage.ownKeyTokens) ? usage.ownKeyTokens : []) {
+    const key = OWN_KEY_LABELS[entry.billing] || String(entry.billing || '').replace(/^byok-/, '') || 'own';
+    rows.push(tokenRow(`Tokens (all time), own ${key} key`, entry));
+  }
+  return rows;
+}
+
 function usageRows(id, usage) {
+  return [...providerUsageRows(id, usage), ...tokenRows(usage)];
+}
+
+function providerUsageRows(id, usage) {
   if (id === 'github') {
+    if (usage.premiumRequests === undefined) return [];
     return [row('Premium requests', esc(formatAmount(usage.premiumRequests)), { hint: `over ${formatCount(usage.turns)} replies` })];
   }
   if (id === 'cursor') {
+    if (usage.totalTokens === undefined) return [];
     return [
       row('Tokens', esc(formatAmount(usage.totalTokens)), {
         hint: `${formatAmount(usage.inputTokens)} in · ${formatAmount(usage.outputTokens)} out · ${formatAmount((finite(usage.cacheReadTokens) || 0) + (finite(usage.cacheWriteTokens) || 0))} cache`,
@@ -146,12 +211,14 @@ function usageRows(id, usage) {
     ];
   }
   if (id === 'grok') {
+    if (usage.totalTokens === undefined) return [];
     return [
       row('Tokens', esc(formatAmount(usage.totalTokens)), { hint: `${formatAmount(usage.inputTokens)} in · ${formatAmount(usage.outputTokens)} out` }),
       row('Cost', esc(formatUsd(usage.costUsd)), { hint: `over ${formatCount(usage.turns)} turns` }),
     ];
   }
   if (id === 'claude-cloud') {
+    if (usage.costUsd === undefined) return [];
     return [row('Cost', esc(formatUsd(usage.costUsd)), { hint: `over ${formatCount(usage.sessions)} cloud sessions` })];
   }
   return [];
@@ -173,6 +240,39 @@ function buildUpdateSection(update, formatDateTime) {
   ));
 }
 
+// The database backups: the last result (time, size or why not), how many of
+// how many are kept, and the folder.
+function backupsRow(backups, formatDateTime) {
+  const last = backups.lastResult || null;
+  let value = 'none yet';
+  if (last?.status === 'written') value = `${formatDateTime(last.at)} · ${formatBytes(last.bytes)}`;
+  else if (last?.status === 'skipped') value = `skipped ${formatDateTime(last.at)}: ${last.reason || ''}`;
+  else if (last?.status === 'failed') value = `failed ${formatDateTime(last.at)}: ${last.reason || ''}`;
+  else if (last?.status === 'busy') value = `busy ${formatDateTime(last.at)}: ${last.reason || ''}`;
+  const kept = `${formatCount(backups.kept)} kept of ${formatCount(backups.keep)}`;
+  const hint = backups.enabled === false
+    ? `at start: off (dbBackups.enabled); ${kept}`
+    : [kept, backups.problem || backups.dir].filter(Boolean).join(' · ');
+  return row('Backups', esc(value), { hint });
+}
+
+/**
+ * The running workers and how many still run the code before the last deploy
+ * (the relay recycles those once idle): "14, all on this build", "14, 3 on an
+ * older build", or the bare count when the relay cannot tell. Empty when no
+ * worker runs, so the row is left out.
+ */
+export function workersBuildText(workers) {
+  const total = finite(workers?.total) || 0;
+  if (total <= 0) return '';
+  const count = formatCount(total);
+  // Number(null) is 0: an unknown count must not read as "all on this build".
+  const other = workers?.onOtherBuild === null || workers?.onOtherBuild === undefined ? null : finite(workers.onOtherBuild);
+  if (other === null) return count;
+  if (other <= 0) return total === 1 ? `${count}, on this build` : `${count}, all on this build`;
+  return `${count}, ${formatCount(other)} on an older build`;
+}
+
 /**
  * @param {object} about the GET /api/about payload
  * @param {object} [options]
@@ -187,8 +287,10 @@ export function buildAboutModalHtml(about = {}, {
 
   const commit = String(about.commit || '').trim();
   const install = about.installMethod === 'git-checkout' ? 'git checkout' : (about.installMethod === 'npm-global' ? 'npm package' : '');
+  const workersText = workersBuildText(about.workers);
   sections.push(section('build', 'OAR', table([
     row('Version', esc(about.version || '–'), install ? { hint: install } : {}),
+    ...(workersText ? [row('Workers', esc(workersText))] : []),
     ...(commit ? [row('Commit', `<code>${esc(commit.slice(0, 7))}</code>`, { title: commit })] : []),
     row('Started', esc(about.startedAt ? formatDateTime(about.startedAt) : '–')),
     row('Uptime', esc(formatUptime(about.uptimeSeconds))),
@@ -217,13 +319,14 @@ export function buildAboutModalHtml(about = {}, {
   sections.push(section('usage', 'Usage', (usageIds.length
     ? usageIds.map((id) => `<div class="about-usage-provider">${esc(USAGE_LABELS[id])}</div>${table(usageRows(id, usage[id]))}`).join('')
     : note('No provider has reported usage yet.'))
-    + note('What the providers report and this relay keeps: Copilot premium requests per reply, Cursor and Grok tokens and cost per billing cycle, Claude Cloud cost per session. Claude Code and OpenAI turns keep no usage here.')));
+    + note('What the providers report and this relay keeps: Copilot premium requests per reply, Cursor and Grok tokens and cost per billing cycle, Claude Cloud cost per session, and every provider\'s tokens of all time: fresh input, output, cache writes and cache reads, "—" where no turn reported one. On Claude API and DeepSeek the days from before the upgrade have cache writes inside input. The tokens stay when a chat is deleted; Check Usage shows them by day and model.')));
 
   const relay = about.relay || {};
   sections.push(section('relay', 'Relay', table([
     row('Uptime', esc(formatUptime(relay.uptimeSeconds))),
-    row('Database', esc(formatBytes(relay.dbBytes)), { hint: `${formatBytes(relay.dbFileBytes)} + ${formatBytes(relay.walBytes)} WAL` }),
+    row('Database', esc(relay.dbPath ? `${relay.dbPath} · ${formatBytes(relay.dbBytes)}` : formatBytes(relay.dbBytes)), { hint: `${formatBytes(relay.dbFileBytes)} + ${formatBytes(relay.walBytes)} WAL` }),
     row('Running workers', esc(formatCount(relay.runningWorkers))),
+    ...(about.backups ? [backupsRow(about.backups, formatDateTime)] : []),
   ])));
 
   sections.push(buildUpdateSection(about.update || {}, formatDateTime));

package/server/public/app/action-confirmations.js

@@ -107,7 +107,7 @@ export async function confirmKillCurrentSession() {
   }
 }
 
-// ⋯ → Restart web relay first shows what the restart would wait for and
+// ︙ → Restart web relay first shows what the restart would wait for and
 // leave running (relay-restart-ui.js); its buttons land in
 // confirmRestartWebRelay below or in confirmRestartRelayNow.
 export { openRestartRelayConfirmation };

package/server/public/app/api-client.js

@@ -982,7 +982,9 @@ export async function loadConversation(id, options = {}) {
   const aroundMessageId = String(options.aroundMessageId || '').trim();
   if (aroundMessageId) params.set('aroundMessageId', aroundMessageId);
   const query = params.toString();
-  return apiFetch(`/api/conversation/${convId}${query ? `?${query}` : ''}`);
+  // `onErrorResponse` tells a conversation the relay does not know (404) from a failed load.
+  const onErrorResponse = typeof options.onErrorResponse === 'function' ? options.onErrorResponse : undefined;
+  return apiFetch(`/api/conversation/${convId}${query ? `?${query}` : ''}`, onErrorResponse ? { onErrorResponse } : undefined);
 }
 
 export async function refreshConversationHistory(id, options = {}) {
@@ -1247,7 +1249,7 @@ export async function createConversationShareLink(id) {
   });
 }
 
-// Share management (Settings → Shared conversations, the ⋯ menu). These throw
+// Share management (Settings → Shared conversations, the ︙ menu). These throw
 // with the relay's reason, so the caller can say why an action failed.
 export async function listConversationShares() {
   return apiFetchOrThrow('/api/shares');
@@ -1709,13 +1711,14 @@ export async function loadRelayBoard(boardId) {
   return apiFetch(`/api/relay-board/${encodeURIComponent(id)}`);
 }
 
-export async function submitRelayBoardAction(boardId, actionId) {
+export async function submitRelayBoardAction(boardId, actionId, { onErrorResponse } = {}) {
   const id = String(boardId || '').trim();
   const action = String(actionId || '').trim();
   if (!id || !action) return null;
   return apiFetch(`/api/relay-board/${encodeURIComponent(id)}/action`, {
     method: 'POST',
     body: JSON.stringify({ actionId: action }),
+    onErrorResponse,
   });
 }
 

package/server/public/app/ask-user-view.js

@@ -17,6 +17,7 @@ import { questionCardHeadLabel } from './conversation-provider-indicator.mjs';
 import { questionAcceptsFreeText } from './question-answer-rule.mjs';
 import { beginOwnSend, followsTranscriptEnd, refreshJumpButton, scrollAfterOwnSend } from './transcript-jump-bottom-view.mjs';
 import { renderSessionAskCards } from './inbox-ui.js';
+import { isConversationAutoOpenHeld } from './session-history-ui.js';
 
 let relayQuestionRenderHash = '';
 let renderedRelayQuestionIds = new Set();
@@ -124,13 +125,20 @@ export async function loadRelayQuestions(conversationId) {
   window.renderConvList?.();
   window.syncComposerButtonState?.();
 
-  if (!conversationId && pending.length) {
+  // Nothing open: the latest question's conversation opens. Not from the
+  // Inbox or Status, which show nothing open too: they are being read. And
+  // in place of the empty screen, not as a step of its own in history. Nor
+  // after a link the relay did not know: its notice keeps the screen empty
+  // until the reader opens something.
+  const readingAView = document.body?.classList?.contains('inbox-view-active')
+    || document.body?.classList?.contains('status-view-active');
+  if (!conversationId && pending.length && !readingAView && !isConversationAutoOpenHeld()) {
     const latest = pending
       .slice()
       .sort((a, b) => new Date(b.createdAt || 0) - new Date(a.createdAt || 0))[0];
     const targetConversationId = String(latest?.conversationId || '').trim();
     if (targetConversationId && targetConversationId !== currentConvId && conversations[targetConversationId]) {
-      await window.openConversation?.(targetConversationId);
+      await window.openConversation?.(targetConversationId, { history: 'replace' });
       return;
     }
   }
@@ -171,10 +179,16 @@ export function updatePendingQuestionBanner() {
   banner.dataset.targetQuestionId = String(latest?.id || '').trim();
   const count = pending.length;
   const currentCount = currentConvId ? pending.filter((q) => q?.conversationId === currentConvId).length : 0;
-  const convTitle = escHtml(conversations[targetConversationId]?.title || targetConversationId || 'conversation');
-  banner.innerHTML = currentCount > 0
-    ? `❓ ${count} open question${count === 1 ? '' : 's'}`
-    : `❓ ${count} open question${count === 1 ? '' : 's'} · latest in ${convTitle}`;
+  const rawTitle = String(conversations[targetConversationId]?.title || targetConversationId || 'conversation');
+  const countText = `❓ ${count} open question${count === 1 ? '' : 's'}`;
+  const tailText = currentCount > 0 ? '' : ` · latest in ${rawTitle}`;
+  // The full text, and the compact chip "❓ N" the header fit switches to
+  // (data-compact) where the row is short. Either way the button's name and
+  // tooltip are the full text.
+  banner.innerHTML = `<span class="pending-question-full"><span class="pending-question-count">${escHtml(countText)}</span>${tailText ? `<span class="pending-question-tail">${escHtml(tailText)}</span>` : ''}</span>`
+    + `<span class="pending-question-compact" aria-hidden="true">❓ ${count}</span>`;
+  banner.title = `${countText}${tailText}`;
+  banner.setAttribute('aria-label', `${countText}${tailText}`);
   banner.classList.add('visible');
   banner.disabled = false;
 }

package/server/public/app/attachments-view.js

@@ -277,7 +277,7 @@ export function renderAttachmentPreview() {
     const annotatable = att.isImage && att.previewUrl && isAnnotatableImageType(att.type);
     const thumb = att.isImage && att.previewUrl
       ? `<img src="${escHtml(att.previewUrl)}" alt="${escHtml(att.name)}"${annotatable ? ` onclick="openAnnotateEditorForPending(${idx})" title="Annotate ${escHtml(att.name)}" style="cursor: pointer;"` : ''}>`
-      : `<div class="attachment-preview-meta" style="height:88px;display:flex;align-items:center;justify-content:center">📎</div>`;
+      : `<div class="attachment-preview-meta" style="height:calc(88px * var(--ui-scale));display:flex;align-items:center;justify-content:center">📎</div>`;
     const annotateBadge = annotatable
       ? `<span class="attachment-preview-annotate" aria-hidden="true">🖍️</span>`
       : '';

package/server/public/app/back-guard.mjs

@@ -9,7 +9,26 @@
 
 export const BACK_GUARD_FLOOR = 'oarBackGuardFloor';
 export const BACK_GUARD_APP = 'oarApp';
-const FIRST_INTERACTION_EVENTS = ['pointerdown', 'keydown', 'touchstart'];
+// Every entry the app writes carries its place in the stack, so a pop tells
+// back from forward (session-history.mjs, viewer-history.mjs).
+export const HISTORY_POSITION = 'oarPos';
+// The visit's base (the floor, the phone's session list) is laid: a reload
+// on any later entry must not lay it again.
+export const VISIT_LAID = 'oarLaid';
+// The place in the stack of the visit's lowest own entry (the phone's list,
+// else the first session): back from above it stays in the app.
+export const VISIT_BASE = 'oarBase';
+export const FIRST_INTERACTION_EVENTS = Object.freeze(['pointerdown', 'keydown', 'touchstart']);
+
+/** The marks every later entry of the visit carries over from the one below. */
+export function inheritedVisitMarks(state) {
+  const marks = {};
+  if (!state || typeof state !== 'object') return marks;
+  if (state[BACK_GUARD_APP]) marks[BACK_GUARD_APP] = true;
+  if (state[VISIT_LAID]) marks[VISIT_LAID] = state[VISIT_LAID];
+  if (Number.isFinite(state[VISIT_BASE])) marks[VISIT_BASE] = state[VISIT_BASE];
+  return marks;
+}
 
 /**
  * Lay the floor at the first touch or key, not at start-up: an entry a page
@@ -19,13 +38,13 @@ const FIRST_INTERACTION_EVENTS = ['pointerdown', 'keydown', 'touchstart'];
  * interaction nothing a page does keeps back from leaving; from then on
  * the floor holds.
  */
-export function armBackGuardOnFirstInteraction({ history, enabled = true, target, onFloor = null } = {}) {
+export function armBackGuardOnFirstInteraction({ history, enabled = true, target, onFloor = null, entryAgain = null } = {}) {
   if (!enabled || !history || !target) return null;
   const state = { guard: null };
   const arm = () => {
     for (const eventName of FIRST_INTERACTION_EVENTS) target.removeEventListener(eventName, arm, true);
     if (state.guard) return;
-    state.guard = installBackGuard({ history, enabled: true, onFloor });
+    state.guard = installBackGuard({ history, enabled: true, onFloor, entryAgain });
     target.addEventListener('popstate', () => state.guard.onPopState());
   };
   for (const eventName of FIRST_INTERACTION_EVENTS) target.addEventListener(eventName, arm, true);
@@ -38,8 +57,12 @@ export function armBackGuardOnFirstInteraction({ history, enabled = true, target
  * lets the next back leave unless the user touches the app in between:
  * one swallowed press, then the app closes — the pattern phones use, and
  * the moment to say "press back again to close".
+ *
+ * `entryAgain` names the entry pushed back above the floor: `{ state, url }`
+ * (the session list on a phone, else the session on screen). Without it a
+ * bare app entry goes back up.
  */
-export function installBackGuard({ history, enabled = true, onFloor = null } = {}) {
+export function installBackGuard({ history, enabled = true, onFloor = null, entryAgain = null } = {}) {
   if (!enabled || !history) return null;
   const current = history.state && typeof history.state === 'object' ? history.state : {};
   // After a reload on the app's entry the floor already lies beneath it.
@@ -51,7 +74,10 @@ export function installBackGuard({ history, enabled = true, onFloor = null } = {
     /** Feed every popstate here. */
     onPopState() {
       if (!history.state?.[BACK_GUARD_FLOOR]) return;
-      history.pushState({ [BACK_GUARD_APP]: true }, '');
+      const again = typeof entryAgain === 'function' ? entryAgain() : null;
+      if (again?.state && again.url) history.pushState({ ...again.state, [BACK_GUARD_APP]: true }, '', again.url);
+      else if (again?.state) history.pushState({ ...again.state, [BACK_GUARD_APP]: true }, '');
+      else history.pushState({ [BACK_GUARD_APP]: true }, '');
       onFloor?.();
     },
   };