@oar-sh/oar 0.9.19 → 0.9.21

package/server/services/oar-cli-helpers.mjs

@@ -7,6 +7,7 @@ import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { formatMegabytes } from './db-backup-service.mjs';
 
 export function generateAuthToken() {
   return randomBytes(32).toString('base64url');
@@ -66,21 +67,22 @@ export function describeRelayAddress({ config, lanAddress = null, wslNat = false
   return { url, lines, qrUrl, tunnelUrl };
 }
 
-const VALUE_OPTIONS = ['--port', '--migrate-from', '--to', '--autostart'];
+const VALUE_OPTIONS = ['--port', '--migrate-from', '--to', '--autostart', '--reason'];
 const LAUNCHER_FLAGS = ['--install-extension', '--no-install-extension', '--migrate-from'];
 const COMMAND_OPTIONS = { '--setup': 'setup', '--start': 'start', '--stop': 'stop', '--status': 'status' };
 const CLI_COMMANDS = {
   menu: {},
   start: {},
-  stop: {},
-  restart: {},
+  stop: { flags: ['--now'] },
+  restart: { flags: ['--now'] },
   status: {},
   url: {},
   doctor: {},
+  backup: { values: ['--reason'] },
   help: {},
   version: {},
   setup: { flags: ['--lan', '--local', '--new-token', '--defaults', '--start'], values: ['--port', '--migrate-from', '--autostart'] },
-  service: { words: ['install', 'remove', 'status'] },
+  service: { words: ['install', 'remove', 'status'], flags: ['--replace'] },
   autostart: { words: ['signin', 'boot', 'off', 'status'], flags: ['--replace'] },
   uninstall: { flags: ['--purge'] },
   update: { flags: ['--beta'], values: ['--to'] },
@@ -93,8 +95,8 @@ export function usageText() {
     '',
     '  oar                    Menu in a terminal; status and this text elsewhere',
     '  oar start              Start the relay in the background',
-    '  oar stop               Stop the relay (waits for running turns)',
-    '  oar restart            Restart the relay (waits for running turns)',
+    '  oar stop [--now]       Stop the relay (waits for running turns; --now does not)',
+    '  oar restart [--now]    Restart the relay (waits for running turns; --now does not)',
     '  oar status             Is the relay running, on which port, as a service',
     '  oar url                Relay URL, with a QR code when a phone can reach it',
     '  oar setup              Auth token, access, port and autostart; asks, or takes',
@@ -103,13 +105,16 @@ export function usageText() {
     '  oar autostart signin | boot | off | status [--replace]',
     '                         Start the relay at sign-in or at boot (Windows: boot asks for an admin once);',
     '                         --replace replaces hand-made entries, keeping a copy',
-    '  oar service install | remove | status',
-    '                         Start the relay at login',
+    '  oar service install | remove | status [--replace]',
+    '                         Start the relay at boot and keep it running (Linux: a systemd user service);',
+    '                         --replace replaces a hand-made unit, keeping a copy',
     '  oar uninstall [--purge]',
     '                         Remove autostart and the package; the data stays (--purge deletes it)',
     '  oar copilot [--port <port>] [--install-extension] [--no-install-extension] [-- gh copilot args...]',
     '                         Relay plus a Copilot terminal session',
     '  oar doctor             Check the install and the provider CLIs',
+    '  oar backup [--reason <text>]',
+    '                         A copy of the database into the backup folder (safe while the relay runs)',
     '  oar update [--beta] [--to <version>]',
     '  oar help               This text',
     '  oar --version',
@@ -178,15 +183,75 @@ export function parseCliArgs(argv = []) {
   return { command, args: [...args, ...forwarded] };
 }
 
+// The first systemd version with RestartSteps= and RestartMaxDelaySec=.
+const SYSTEMD_BACKOFF_VERSION = 254;
+const UNIT_MARKER = /^# Generated by `oar service install` for (.*)\.$/m;
+
+/** The version `systemctl --version` prints first (`systemd 257 (257.9-1)`), or null. */
+export function parseSystemdVersion(text) {
+  const version = Number(String(text || '').match(/^systemd (\d+)/m)?.[1]);
+  return Number.isInteger(version) && version > 0 ? version : null;
+}
+
 /**
  * A systemd *user* unit for the relay server. The launcher is not used here —
- * the service runs server.js directly with the same env the launcher would set,
- * so a `gh copilot` session is not tied to the unit's lifetime.
+ * the service runs server.js directly, so a `gh copilot` session is not tied
+ * to the unit's lifetime. A global install pins its state paths; a git
+ * checkout (`checkout`) runs in the checkout and finds its config, data and
+ * logs as `npm start` does. Crashes are restarted with a backoff that never
+ * gives up; a systemd older than 254 (or one whose version is unknown) has no
+ * backoff, and gets a longer fixed delay instead.
  */
-export function buildSystemdUnit({ nodeBin, packageRoot, configPath, dataDir, logDir, pathEnv = '' }) {
-  // systemd units are Linux-only, so the path inside the unit is always
+export function buildSystemdUnit({
+  nodeBin, packageRoot, configPath, dataDir, logDir, pathEnv = '', checkout = false, systemdVersion = null,
+}) {
+  // systemd units are Linux-only, so the paths inside the unit are always
   // posix-joined — host-platform path.join would write backslashes when this
   // template is exercised on Windows (tests; the CLI never writes it there).
+  const backoff = Number(systemdVersion) >= SYSTEMD_BACKOFF_VERSION;
+  return [
+    `# Generated by \`oar service install\` for ${packageRoot}.`,
+    '# OAR rewrites this file; put settings of your own in oar.service.d/*.conf next to it.',
+    '[Unit]',
+    'Description=OAR — Open Agent Relay',
+    'After=network-online.target',
+    'StartLimitIntervalSec=0',
+    '',
+    '[Service]',
+    `ExecStart=${systemdExecWord(nodeBin)} ${systemdExecWord(path.posix.join(packageRoot, 'server', 'server.js'))}`,
+    ...(checkout
+      ? [`WorkingDirectory=${String(packageRoot).replace(/%/g, '%%')}`]
+      : [
+        systemdEnvironmentLine('COPILOT_WEB_RELAY_CONFIG', configPath),
+        systemdEnvironmentLine('COPILOT_WEB_RELAY_DATA_DIR', dataDir),
+        systemdEnvironmentLine('COPILOT_WEB_RELAY_LOG_DIR', logDir),
+      ]),
+    // A user service starts with systemd's bare PATH: without this line the
+    // relay's sessions find neither the provider CLIs in ~/.local/bin nor, on
+    // an install with a private Node, `node` and `npm` themselves.
+    ...(pathEnv ? [`Environment="PATH=${escapeSystemdValue(pathEnv)}"`] : []),
+    // The supervisor alone gets the SIGTERM of a stop, and stops its runtime
+    // itself; whatever is left then gets SIGKILL. Session workers run in
+    // scopes of their own and are not part of the unit.
+    'KillMode=mixed',
+    'Restart=on-failure',
+    // 78 (RELAY_STOP_EXIT_CODE): the relay stopped on purpose, its database
+    // or data folder needs a decision; restarting it cannot help.
+    '# 78: stopped on purpose (database or data folder needs a decision).',
+    'RestartPreventExitStatus=78',
+    ...(backoff ? ['RestartSec=2', 'RestartSteps=8', 'RestartMaxDelaySec=300'] : ['RestartSec=10']),
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The unit 0.9.19 wrote, frozen: a unit with this text is OAR's own, of an
+ * earlier version (classifySystemdUnit). Never change it.
+ */
+export function buildSystemdUnit0919({ nodeBin, packageRoot, configPath, dataDir, logDir, pathEnv = '' }) {
   return [
     '[Unit]',
     'Description=OAR — Open Agent Relay',
@@ -219,6 +284,102 @@ function escapeSystemdValue(value) {
   return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%');
 }
 
+// Characters that end or change a word of an unquoted systemd value.
+const SYSTEMD_NEEDS_QUOTES = /[\s"'\\]/;
+
+// One word of ExecStart=: quoted when it has to be; `%` and `$` (a specifier,
+// a variable) are doubled either way.
+function systemdExecWord(value) {
+  const text = String(value).replace(/\$/g, '$$$$');
+  return SYSTEMD_NEEDS_QUOTES.test(text) ? `"${escapeSystemdValue(text)}"` : text.replace(/%/g, '%%');
+}
+
+// `Environment=KEY=value`, quoted only when the value has to be: a path
+// without a space is written as 0.9.19 wrote it.
+function systemdEnvironmentLine(name, value) {
+  const text = String(value);
+  return SYSTEMD_NEEDS_QUOTES.test(text)
+    ? `Environment="${name}=${escapeSystemdValue(text)}"`
+    : `Environment=${name}=${text.replace(/%/g, '%%')}`;
+}
+
+// The first word of a unit's ExecStart= line: `written` as it stands, `value`
+// unquoted and unescaped as systemdExecWord wrote it.
+function readExecStartNode(text) {
+  const line = String(text || '').match(/^ExecStart=(.*)$/m)?.[1] || '';
+  if (line.startsWith('"')) {
+    const written = line.match(/^"((?:[^"\\]|\\.)*)"/)?.[0] || '';
+    const value = written.slice(1, -1).replace(/\\(.)/g, '$1').replace(/%%/g, '%').replace(/\$\$/g, '$');
+    return { written, value };
+  }
+  const written = line.split(' ')[0];
+  return { written, value: written.replace(/%%/g, '%').replace(/\$\$/g, '$') };
+}
+
+// The words of a unit's ExecStart= line, unquoted and unescaped.
+function readExecStartWords(text) {
+  const line = String(text || '').match(/^ExecStart=(.*)$/m)?.[1] || '';
+  const words = [];
+  for (const match of line.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)) {
+    const word = match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1') : match[2];
+    words.push(word.replace(/%%/g, '%').replace(/\$\$/g, '$'));
+  }
+  return words;
+}
+
+/**
+ * Whether a unit without OAR's marker runs the relay of the checkout at
+ * `root`: its ExecStart names `<root>/server/server.js`. A unit that only
+ * runs in `<root>` (WorkingDirectory) does not count: it may start anything
+ * there. A hand-made unit of another install is not a checkout's service.
+ */
+export function systemdUnitRunsCheckout(text, root) {
+  const resolve = (value) => path.posix.resolve(String(value));
+  const server = path.posix.join(resolve(root), 'server', 'server.js');
+  return readExecStartWords(text).some((word) => word.startsWith('/') && resolve(word) === server);
+}
+
+/** The install a unit's marker names, or ''. */
+export function systemdUnitMarkerRoot(text) {
+  return String(text || '').match(UNIT_MARKER)?.[1] || '';
+}
+
+/**
+ * Whose a unit is, for this install (`{ nodeBin, packageRoot, configPath,
+ * dataDir, logDir, checkout }`): 'generated' (the text this version writes for
+ * it, with the Node of its own ExecStart and for either systemd variant),
+ * 'generated-earlier' (the text 0.9.19 wrote for it), 'other-install' (OAR's
+ * marker for another install path), or 'hand-made' (anything else, a
+ * generated unit edited by hand too). The PATH line does not count: it is the
+ * PATH of the shell that ran the install.
+ */
+export function classifySystemdUnit({ text, install }) {
+  const strip = (unit) => String(unit).replace(/\r\n/g, '\n').split('\n')
+    .filter((line) => !line.startsWith('Environment="PATH=')).join('\n').trim();
+  const given = strip(text);
+  const node = readExecStartNode(text);
+  const args = { ...install, nodeBin: node.value || install.nodeBin };
+  if ([null, SYSTEMD_BACKOFF_VERSION].some((systemdVersion) => strip(buildSystemdUnit({ ...args, systemdVersion })) === given)) {
+    return 'generated';
+  }
+  if (!install.checkout && strip(buildSystemdUnit0919({ ...install, nodeBin: node.written || install.nodeBin })) === given) {
+    return 'generated-earlier';
+  }
+  const root = systemdUnitMarkerRoot(text);
+  if (root && path.posix.resolve(root) !== path.posix.resolve(String(install.packageRoot))) return 'other-install';
+  return 'hand-made';
+}
+
+/** The drop-ins next to the unit (`oar.service.d/*.conf`), sorted; OAR never writes or deletes them. */
+export function listSystemdDropIns(homeDir, { fsImpl = fs } = {}) {
+  const dir = path.join(homeDir, '.config', 'systemd', 'user', 'oar.service.d');
+  try {
+    return fsImpl.readdirSync(dir).filter((name) => name.endsWith('.conf')).sort().map((name) => path.join(dir, name));
+  } catch {
+    return [];
+  }
+}
+
 /**
  * The PATH a relay service gets: the PATH `oar setup` ran with (the user's
  * shell, so their tools), with two directories added when they are not on it:
@@ -287,6 +448,42 @@ export const DOCTOR_PROBES = Object.freeze([
   { id: 'grok', binary: 'grok', args: ['--version'] },
 ]);
 
+
+function doctorAge(at, now) {
+  const ms = now - Date.parse(String(at || ''));
+  if (!Number.isFinite(ms)) return 'unknown age';
+  const hours = Math.floor(ms / 3_600_000);
+  return hours < 1 ? 'less than an hour ago' : (hours < 48 ? `${hours} h ago` : `${Math.floor(hours / 24)} days ago`);
+}
+
+// The backup lines of `oar doctor` (db-backup-service.mjs describeBackups).
+function renderBackupLines(backups, now) {
+  const pad = '                  ';
+  const lines = [`  backups       : ${backups.dir || '(no folder)'}${backups.problem ? `  (${backups.problem})` : ''}`];
+  lines.push(`${pad}at start: ${backups.enabled ? 'on' : 'off (dbBackups.enabled is false)'}, keep ${backups.keep}`);
+  for (const warning of backups.warnings || []) lines.push(`${pad}warning: ${warning}`);
+  const last = backups.lastResult;
+  if (last) {
+    const what = last.status === 'written' ? `written ${last.file} (${formatMegabytes(last.bytes)})` : `${last.status}: ${last.reason || ''}`;
+    lines.push(`${pad}last: ${what}, ${doctorAge(last.at, now)}`);
+  }
+  if (backups.own?.length) {
+    lines.push(`${pad}this relay's (${backups.own.length} of ${backups.keep}):`);
+    for (const entry of backups.own) lines.push(`${pad}  ${entry.file}  ${formatMegabytes(entry.bytes)}, ${doctorAge(entry.at, now)}`);
+  } else {
+    lines.push(`${pad}this relay's: none yet`);
+  }
+  if (backups.changed?.length) {
+    lines.push(`${pad}changed since written, not rotated:`);
+    for (const entry of backups.changed) lines.push(`${pad}  ${entry.file}  ${formatMegabytes(entry.bytes)}`);
+  }
+  if (backups.others?.length) {
+    lines.push(`${pad}other files here (not rotated):`);
+    for (const entry of backups.others) lines.push(`${pad}  ${entry.name}${entry.folder ? '/' : ''}  ${formatMegabytes(entry.bytes)}`);
+  }
+  return lines;
+}
+
 export function renderDoctorReport({
   version,
   nodeVersion,
@@ -296,6 +493,9 @@ export function renderDoctorReport({
   config,
   dbPath,
   dbSizeBytes,
+  databaseNotes = [],
+  backups = null,
+  now = Date.now(),
   probes = [],
   warnings = [],
   tunnel = '',
@@ -318,6 +518,8 @@ export function renderDoctorReport({
     lines.push(`  tunnel        : ${tunnel || configured}`);
   }
   lines.push(`  database      : ${dbSizeBytes !== null ? `${dbPath} (${(dbSizeBytes / 1048576).toFixed(1)} MB)` : `${dbPath} (not created yet)`}`);
+  for (const note of databaseNotes) lines.push(`                  ${note}`);
+  if (backups) lines.push(...renderBackupLines(backups, now));
   lines.push('  provider CLIs :');
   for (const probe of probes) {
     lines.push(`    ${probe.id.padEnd(14)}: ${probe.ok ? probe.version || 'installed' : 'not found'}`);

package/server/services/oar-cli-menu.mjs

@@ -76,6 +76,7 @@ const SERVICE_TEXT = {
   active: 'installed, running',
   installed: 'installed',
   none: 'not installed',
+  other: 'another OAR install\'s',
   unavailable: 'not available here',
 };
 

package/server/services/oar-state-migration-service.mjs

@@ -23,10 +23,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
+import { DB_FILE_NAMES, LEGACY_DB_FILE_NAME, resolveDatabaseFile, sideFiles } from './database-file.mjs';
 import { createRelaySingletonGuard } from './relay-singleton-guard.mjs';
 
 export const MIGRATION_MARKER = '.migrated';
-const DB_FILE = 'copilot.db';
 const MAX_LOGS_BYTES = 50 * 1024 * 1024;
 
 export function resolveOarRoot(env = process.env, platform = process.platform) {
@@ -257,16 +257,23 @@ export async function migrateStateToOarRoot({
   const markerPath = path.join(root, MIGRATION_MARKER);
   if (!repoServerDir && fs.existsSync(markerPath)) return { status: 'already-migrated', root };
 
-  const targetDbFiles = [DB_FILE, `${DB_FILE}-wal`, `${DB_FILE}-shm`].map((name) => path.join(dataDir, name));
+  // A database there under either name, and the -wal/-shm of each.
+  const targetDbFiles = DB_FILE_NAMES.flatMap(sideFiles).map((name) => path.join(dataDir, name));
+  const takenTargetDbs = () => DB_FILE_NAMES.map((name) => path.join(dataDir, name)).filter((file) => pathTaken(file));
   const targetLock = path.join(dataDir, 'relay-server.lock');
   // The same checkout once more (a repeated command, an alias): nothing to
   // do while the database it brought is still there.
-  if (repoServerDir && pathTaken(targetDbFiles[0]) && wasMigratedFrom(root, repoServerDir)) {
+  if (repoServerDir && takenTargetDbs().length && wasMigratedFrom(root, repoServerDir)) {
     return { status: 'already-migrated', root, source: repoServerDir };
   }
 
   const sourceData = repoServerDir ? path.join(repoServerDir, 'data') : null;
-  const sourceDb = sourceData ? path.join(sourceData, DB_FILE) : null;
+  // The database keeps its name; with both names there the other comes
+  // along as it is, and the relay's next start compares the two.
+  const sourceFile = sourceData ? resolveDatabaseFile(sourceData) : null;
+  const sourceDb = sourceFile && !sourceFile.created ? sourceFile.path : null;
+  const sourceOther = sourceFile?.both ? path.join(sourceData, LEGACY_DB_FILE_NAME) : null;
+  const targetDb = sourceDb ? path.join(dataDir, path.basename(sourceDb)) : null;
   const sourceRepoConfig = repoServerDir ? path.join(repoServerDir, 'config.json') : null;
   const sourceManagedConfig = managedConfigDir ? path.join(managedConfigDir, 'config.json') : null;
 
@@ -305,20 +312,28 @@ export async function migrateStateToOarRoot({
   const refusedWithConversations = () => ({
     status: 'refused-existing-database',
     root,
-    error: `The state root already has a database with conversations (${targetDbFiles[0]}); `
+    error: `The state root already has a database with conversations (${takenTargetDbs().join(', ')}); `
       + `a migration never overwrites one. To bring ${repoServerDir} over instead: `
       + `stop the relay (oar stop), move ${dataDir} aside, then run the migration again.`,
   });
+  const anyTargetNotFresh = async () => {
+    const Database = await loadDatabase(DatabaseImpl);
+    return takenTargetDbs().some((file) => !isFreshDatabase(Database, file));
+  };
   if (hasDb && existingDbFiles().length) {
-    if (!pathTaken(targetDbFiles[0])) {
+    // A -wal or -shm whose database is not there.
+    const orphans = DB_FILE_NAMES.filter((name) => !pathTaken(path.join(dataDir, name)))
+      .flatMap((name) => sideFiles(name).slice(1).map((side) => path.join(dataDir, side)))
+      .filter((file) => pathTaken(file));
+    if (orphans.length) {
       return {
         status: 'refused-existing-database',
         root,
-        error: `The state root has database files without copilot.db (${existingDbFiles().join(', ')}); `
+        error: `The state root has database files without their database (${orphans.join(', ')}); `
           + 'a migration never mixes a database with them. Move them aside, then run the migration again.',
       };
     }
-    if (!isFreshDatabase(await loadDatabase(DatabaseImpl), targetDbFiles[0])) return refusedWithConversations();
+    if (await anyTargetNotFresh()) return refusedWithConversations();
   }
 
   const copied = [];
@@ -355,7 +370,7 @@ export async function migrateStateToOarRoot({
     }
     // Asked again under the lock: a relay that ran between the first look and
     // the lock may have written conversations into the database meanwhile.
-    if (pathTaken(targetDbFiles[0]) && !isFreshDatabase(await loadDatabase(DatabaseImpl), targetDbFiles[0])) {
+    if (await anyTargetNotFresh()) {
       try { guard.release(); } catch {}
       removeCreated(created);
       return refusedWithConversations();
@@ -384,9 +399,14 @@ export async function migrateStateToOarRoot({
         // Checkpoint first so recent writes leave the WAL, then copy all three
         // files anyway — a hot -wal must never be dropped on the floor.
         sourceCounts = readDbCounts(Database, sourceDb, { checkpoint: true });
-        copyIfExists(sourceDb, targetDbFiles[0], copied, created, skipped);
-        copyIfExists(`${sourceDb}-wal`, targetDbFiles[1], copied, created, skipped);
-        copyIfExists(`${sourceDb}-shm`, targetDbFiles[2], copied, created, skipped);
+        copyIfExists(sourceDb, targetDb, copied, created, skipped);
+        copyIfExists(`${sourceDb}-wal`, `${targetDb}-wal`, copied, created, skipped);
+        copyIfExists(`${sourceDb}-shm`, `${targetDb}-shm`, copied, created, skipped);
+        if (sourceOther) {
+          for (const name of sideFiles(path.basename(sourceOther))) {
+            copyIfExists(path.join(sourceData, name), path.join(dataDir, name), copied, created, skipped);
+          }
+        }
         copyIfExists(path.join(sourceData, 'cursor-agents'), path.join(dataDir, 'cursor-agents'), copied, created, skipped);
       }
 
@@ -410,7 +430,7 @@ export async function migrateStateToOarRoot({
 
       if (hasDb) {
         const Database = await loadDatabase(DatabaseImpl);
-        const targetCounts = readDbCounts(Database, targetDbFiles[0]);
+        const targetCounts = readDbCounts(Database, targetDb);
         const mismatch = targetCounts.integrity !== 'ok'
           || targetCounts.conversations !== sourceCounts.conversations
           || targetCounts.messages !== sourceCounts.messages;

package/server/services/package-data-rescue.mjs

@@ -17,17 +17,19 @@ import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 
+import { DB_FILE_NAMES, sideFiles } from './database-file.mjs';
 import { RESCUE_DIR_NAME, copyMissing, isRetiredName } from './earlier-database-service.mjs';
 import { resolveRelayStateDirs, resolveStateLayout } from './oar-state-layout.mjs';
 
-const DB_FILES = ['copilot.db', 'copilot.db-wal', 'copilot.db-shm'];
+// Old packages only ever held the name before 0.9.20; a later one may hold oar.db.
+const DB_FILES = DB_FILE_NAMES.flatMap(sideFiles);
 
 // What a relay left in a package's server folder; a folder that cannot be
 // read throws (no copy failure: nothing was detected yet).
 function hasRelayData(fsImpl, serverDir) {
   const has = (...parts) => fsImpl.existsSync(path.join(serverDir, ...parts));
   const anyUpload = (...parts) => has(...parts) && fsImpl.readdirSync(path.join(serverDir, ...parts)).some((name) => /^[a-f0-9]{64}$/.test(name));
-  return has('data', 'copilot.db') || has('data', 'cursor-agents') || has('config.json') || anyUpload('uploads') || anyUpload('data', 'uploads');
+  return DB_FILE_NAMES.some((name) => has('data', name)) || has('data', 'cursor-agents') || has('config.json') || anyUpload('uploads') || anyUpload('data', 'uploads');
 }
 
 /** Where npm's reify moves a package it replaces (@npmcli/arborist retire-path.js). */

package/server/services/plan-usage-claude-api.mjs

@@ -326,20 +326,7 @@ export function buildClaudeApiPlanCard({
       note: 'Claude API turns on this relay only; the Console has every request on the key.',
       open: true,
     }));
-    details.push(buildDetailSection({
-      id: 'claude-api-tokens-by-model',
-      label: 'Tokens by model, this month',
-      rows: month.models.map((entry) => {
-        const input = entry.hitTokens + entry.missTokens;
-        return {
-          label: modelLabel(entry.model, settings),
-          value: `cache read ${formatTokens(entry.hitTokens)} · other input ${formatTokens(entry.missTokens)} · output ${formatTokens(entry.outputTokens)}`,
-          hint: input > 0 ? `${Math.round((entry.hitTokens / input) * 100)}% of input from the cache` : null,
-        };
-      }),
-      note: 'Other input includes the writes to the prompt cache.',
-      open: true,
-    }));
+    // Tokens by model: the Tokens sections every tab gets (plan-usage-tokens.mjs).
   }
 
   return buildProviderCard({
@@ -395,7 +382,19 @@ export function createClaudeApiPlanUsage({
     return buildClaudeApiPlanCard({ settings, spend, resetAt, timeZone: zoneName, error });
   }
 
-  return { readSpend, getCapState, buildCard };
+  /**
+   * A model's name as the card shows it: the Console's display name, else
+   * the Claude label for the id (the Tokens sections use it too).
+   */
+  function labelModel(model) {
+    try {
+      return modelLabel(model, getSettings());
+    } catch {
+      return null;
+    }
+  }
+
+  return { readSpend, getCapState, buildCard, modelLabel: labelModel };
 }
 
 /**

package/server/services/plan-usage-contract.mjs

@@ -260,7 +260,10 @@ export function buildCardNote({ id, text, link = null, hours = null, label = nul
   };
 }
 
-/** A collapsible block of label/value rows shown under the meters. */
+/**
+ * A collapsible block of label/value rows shown under the meters. A row may
+ * carry a `title`, shown when pointing at it (the model ids behind one name).
+ */
 export function buildDetailSection({ id, label, rows = [], note = null, open = false } = {}) {
   const sectionId = toTrimmedString(id);
   const sectionLabel = toTrimmedString(label);
@@ -270,7 +273,8 @@ export function buildDetailSection({ id, label, rows = [], note = null, open = f
       const rowLabel = toTrimmedString(row?.label);
       const rowValue = row?.value === 0 ? '0' : toTrimmedString(row?.value);
       if (!rowLabel || rowValue === null) return null;
-      return { label: rowLabel, value: rowValue, hint: toTrimmedString(row?.hint) };
+      const rowTitle = toTrimmedString(row?.title);
+      return { label: rowLabel, value: rowValue, hint: toTrimmedString(row?.hint), ...(rowTitle ? { title: rowTitle } : {}) };
     })
     .filter(Boolean);
   if (!normalizedRows.length) return null;

package/server/services/plan-usage-deepseek.mjs

@@ -877,7 +877,7 @@ export function buildDeepSeekPlanCard({
     }));
     details.push(buildDetailSection({
       id: 'deepseek-tokens-by-model',
-      label: 'Tokens by model',
+      label: 'Priced tokens by model',
       rows: spend.models.map((entry) => {
         const input = entry.hitTokens + entry.missTokens;
         return {