@oar-sh/oar 0.9.19 → 0.9.20

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-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,22 @@ 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 });
+}
+
 /**
  * @param {object} about the GET /api/about payload
  * @param {object} [options]
@@ -217,13 +300,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/api-client.js

@@ -1709,13 +1709,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/bootstrap.js

@@ -242,6 +242,7 @@ import {
   autoCompactWindowNotes,
   renderAutoCompactControlHtml,
   renderAgentSessionsControlHtml,
+  renderPlanOnlyControlHtml,
   renderAutoCompactNotesHtml,
   renderContextUsageHtml,
   renderThinkingControlHtml,
@@ -441,6 +442,7 @@ import {
   dismissUpdateOutcome,
 } from './update-ui.js';
 import { shouldAutofocusComposerOnLoad } from './composer-keyboard.mjs';
+import { planOnlyModeHint } from './plan-board-shared.mjs';
 
 const MODEL_STORAGE_KEY = 'copilot_selected_model';
 // The New Chat modal used to keep its own model key, so a selection made there
@@ -2068,6 +2070,21 @@ function updateModeSelectorForProvider() {
   select.value = modes.includes(selectedBefore)
     ? selectedBefore
     : (modes.includes(FALLBACK_MODE) ? FALLBACK_MODE : modes[0]);
+  syncModeSelectPlanOnlyHint();
+}
+
+// A plan-only session's mode select says so; the owner may still
+// pick any mode.
+function syncModeSelectPlanOnlyHint() {
+  const select = document.getElementById('mode-select');
+  if (!select) return;
+  const planOnly = conversations[String(currentConvId || '').trim()]?.planOnly === true;
+  const hint = planOnlyModeHint(planOnly);
+  select.title = hint.title;
+  if (planOnly) select.dataset.planOnly = 'true';
+  else delete select.dataset.planOnly;
+  const planOption = Array.from(select.options).find((option) => option.value === 'plan');
+  if (planOption) planOption.textContent = planOnly ? hint.planLabel : (RELAY_MODE_LABELS.plan || hint.planLabel);
 }
 
 function modeOptions() {
@@ -2086,6 +2103,8 @@ async function persistCurrentConversationPreferences() {
   if (!modeSelect || !modelSelect) return;
   const mode = String(modeSelect.value || '').trim() || FALLBACK_MODE;
   const model = String(modelSelect.value || '').trim();
+  // Steer or Queue: a mode across plan from the live turn's queues.
+  syncComposerButtonState();
   // The raw value, not selectedReasoningEffortValue(): a model with no reasoning
   // options leaves the selector empty, and that helper's 'none' fallback would
   // record an effort the user never picked when they only changed the mode.
@@ -2203,6 +2222,7 @@ function applyConversationPreferences({
   } finally {
     suppressConversationPreferenceSync = false;
   }
+  syncModeSelectPlanOnlyHint();
   // Nothing is written to the shared "last used" storage here. Applying a
   // conversation's stored preferences is not a choice: it runs on every open,
   // on the ~1s live poll, on a catalog refresh and on another client's edit,
@@ -3536,6 +3556,12 @@ function initAgentSessionsControl() {
   if (!body || body.dataset.agentSessionsControlBound === 'true') return;
   body.dataset.agentSessionsControlBound = 'true';
   body.addEventListener('change', async (event) => {
+    // Plan-only, for every session.
+    const planOnlyBox = event.target?.closest?.('#ctx-plan-only');
+    if (planOnlyBox) {
+      await changePlanOnly(planOnlyBox);
+      return;
+    }
     const box = event.target?.closest?.('#ctx-may-create-sessions');
     if (!box) return;
     const convId = String(box.dataset.conversationId || '').trim();
@@ -3562,6 +3588,31 @@ function initAgentSessionsControl() {
   });
 }
 
+async function changePlanOnly(box) {
+  const convId = String(box.dataset.conversationId || '').trim();
+  if (!convId || agentSessionsControlUpdateInFlight) return;
+  const wanted = box.checked === true;
+  agentSessionsControlUpdateInFlight = true;
+  box.disabled = true;
+  try {
+    const response = await updateConversationPreferences(convId, { clientId: CLIENT_ID, planOnly: wanted });
+    if (!response) throw new Error('The relay refused the change');
+    const stored = response.planOnly === true;
+    if (conversations[convId]) conversations[convId] = { ...conversations[convId], planOnly: stored };
+    box.checked = stored;
+    if (convId === String(currentConvId || '').trim()) syncModeSelectPlanOnlyHint();
+    showTransientRelayNotice(stored
+      ? 'Plan only: agents can no longer take this session out of plan mode.'
+      : 'Plan only is off: agents may switch this session to another mode.');
+  } catch (error) {
+    box.checked = !wanted;
+    showTransientRelayNotice(`Could not change the setting: ${error?.message || error}`);
+  } finally {
+    box.disabled = false;
+    agentSessionsControlUpdateInFlight = false;
+  }
+}
+
 function initThinkingControl() {
   const body = document.getElementById('summary-modal-body');
   if (!body || body.dataset.thinkingBound === '1') return;
@@ -3741,9 +3792,11 @@ async function loadContextSummaryAndRender(convId) {
   // sessions? Only meaningful there, so only shown there.
   const settingsConversationId = String(payload.resolvedConversationId || trimmedConvId || '').trim();
   const settingsConversation = settingsConversationId ? conversations[settingsConversationId] : null;
-  const agentSessionsHtml = settingsConversation?.origin
+  const agentSessionsHtml = (settingsConversation?.origin
     ? renderAgentSessionsControlHtml({ conversationId: settingsConversationId, mayCreateSessions: settingsConversation.mayCreateSessions === true })
-    : '';
+    : '')
+    // Plan-only, for every session.
+    + (settingsConversationId ? renderPlanOnlyControlHtml({ conversationId: settingsConversationId, planOnly: settingsConversation?.planOnly === true }) : '');
   const detailText = String(payload.text || '').trim();
   // The structured breakdown is the answer; the runtime's own text dump stays
   // available underneath for the details it carries that categories don't.

package/server/public/app/composer-control-state.mjs

@@ -19,6 +19,9 @@ export function hasUploadingAttachments(attachments = []) {
   return countUploadingAttachments(attachments) > 0;
 }
 
+// A message whose mode is on the other side of plan mode from the live turn's.
+export const PLAN_BOUNDARY_QUEUE_TITLE = 'Queued behind the running turn: plan mode and the writing modes do not steer into each other';
+
 // Why a message sent right now queues instead of steering — worker-reported
 // hold reasons mapped to a human title. Stopping a turn lives on the message
 // bubbles, never here, so every state below is a Send/Steer/Queue shape.
@@ -49,6 +52,10 @@ export function deriveComposerControlState({
   // the relay holds the message and it steers in once the hold clears.
   steeringHeld = false,
   steeringHoldReason = null,
+  // The composer's mode is on the other side of plan mode from the live turn's:
+  // the relay queues such a message behind the turn instead of steering it in
+  // (a steer would switch what the running turn may do).
+  crossesPlanMode = false,
   // An archived conversation: its worker is stopped and it is out of the
   // live list; sending would start it again behind the user's back.
   archived = false,
@@ -83,10 +90,13 @@ export function deriveComposerControlState({
   // The label/title/action for a draft typed during a live turn: steer into it
   // where the provider supports that (queued while steering is held), queue
   // behind it otherwise.
-  const steerNow = !!steeringSupported && !held;
+  const crossing = active && !!crossesPlanMode;
+  const steerNow = !!steeringSupported && !held && !crossing;
   const midTurnAction = steerNow ? 'steer' : 'queue';
   const midTurnLabel = steerNow ? 'Steer' : 'Queue';
-  const midTurnTitle = held
+  const midTurnTitle = crossing
+    ? PLAN_BOUNDARY_QUEUE_TITLE
+    : held
     ? (STEERING_HOLD_TITLES[String(steeringHoldReason || '').trim()]
       || 'Will steer in once steering resumes')
     : (steeringSupported

package/server/public/app/context-usage-view.mjs

@@ -367,6 +367,22 @@ export function renderAgentSessionsControlHtml({ conversationId = '', mayCreateS
   `;
 }
 
+/**
+ * The owner's plan-only switch, for every session: agents cannot take it out
+ * of plan mode while it is on (the owner still changes the mode freely).
+ */
+export function renderPlanOnlyControlHtml({ conversationId = '', planOnly = false } = {}) {
+  return `
+    <div class="ctx-agent-sessions ctx-plan-only">
+      <label class="ctx-agent-sessions-row">
+        <input type="checkbox" id="ctx-plan-only" data-conversation-id="${escapeHtml(conversationId)}"${planOnly === true ? ' checked' : ''}>
+        <span>Plan only: agents can't take this session out of plan mode</span>
+      </label>
+      <div class="ctx-thinking-note">While this is on, an agent's message or settings change that names another mode is refused; you can still change the mode yourself. "Approve plan" runs one turn with write access and the session plans again after it. Agents may switch it off.</div>
+    </div>
+  `;
+}
+
 // A model limit is a round figure: 1M rather than 1.0M.
 function formatModelLimit(value) {
   const n = toNullableNumber(value);

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

@@ -612,6 +612,15 @@ function steeringHoldForConversation(conversationId) {
   return { held: false, reason: null };
 }
 
+// Plan mode on one side, the writing modes on the other (a turn's mode not yet
+// known crosses nothing).
+function modesCrossPlan(turnMode, composerMode) {
+  const turn = String(turnMode || '').trim().toLowerCase();
+  const composer = String(composerMode || '').trim().toLowerCase();
+  if (!turn || !composer) return false;
+  return (turn === 'plan') !== (composer === 'plan');
+}
+
 function syncSendButtonState() {
   const btn = document.getElementById('send-btn');
   if (!btn) return;
@@ -631,6 +640,7 @@ function syncSendButtonState() {
     steeringSupported: conversationSupportsSteering(currentConvId),
     steeringHeld: steeringHold.held,
     steeringHoldReason: steeringHold.reason,
+    crossesPlanMode: modesCrossPlan(currentTurn?.mode, document.getElementById('mode-select')?.value),
     archived: conversations[String(currentConvId || '').trim()]?.archived === true,
     setupRequired: !String(currentConvId || '').trim() && isProviderSetupRequired(),
   });
@@ -1202,10 +1212,15 @@ function setConversationTurnState(conversationId, state = null) {
     syncSendButtonState();
     return;
   }
+  const messageId = String(state.messageId || '').trim();
+  const previous = activeTurnsByConversation.get(conversationKey);
   activeTurnsByConversation.set(conversationKey, {
-    messageId: String(state.messageId || '').trim(),
+    messageId,
     status: String(state.status || 'processing').trim().toLowerCase() || 'processing',
     cancelRequested: state.cancelRequested === true,
+    // The live turn's relay mode (the in-flight snapshot carries it); a status
+    // update for the same turn keeps the one already known.
+    mode: String(state.mode || (previous?.messageId === messageId ? previous.mode : '') || '').trim().toLowerCase(),
   });
   syncSendButtonState();
 }
@@ -2293,7 +2308,7 @@ export function restoreInFlightThinking(inFlight, autoScroll = true) {
   const liveStreamSeq = relayStreamStateByMessageId.get(messageId)?.seq || 0;
   const liveStreamText = relayStreamTextByMessageId.get(messageId);
   clearRelayStreamState();
-  setConversationTurnState(currentConvId, { messageId, status: 'processing' });
+  setConversationTurnState(currentConvId, { messageId, status: 'processing', mode: inFlight?.mode });
   const activities = mergeRelayActivityTexts(
     relayActivities.get(messageId) || [],
     Array.isArray(inFlight.activities) ? inFlight.activities : [],