@oar-sh/oar 0.9.19 → 0.9.20

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

@@ -523,6 +523,14 @@ export function createCopilotSdkSessionRunner({
   // The in-flight ingest POST, exposed only as a test seam. Never awaited by
   // the turn path — that is the entire point of it.
   let usagePostChain = Promise.resolve();
+  // The token booking's post (POST /api/turn-token-usage), a chain and a test
+  // seam like `usagePostChain`. Its run is the row's attempt (a row
+  // delivered again is another run of the turn); a row without one (an older
+  // relay) is booked under this process's own id, so a turn requeued onto a
+  // restarted worker is a second run of it, not the same row.
+  let tokenPostChain = Promise.resolve();
+  const postedTurnTokens = new WeakSet();
+  const tokenRunId = randomUUID();
   // The last catalog content this worker POSTed to `/api/models/snapshot`,
   // as a serialized signature. Identity of CONTENT, not of session: an idle
   // shutdown and resume onto the same catalog must not re-publish it.
@@ -1330,6 +1338,7 @@ export function createCopilotSdkSessionRunner({
       conversationId: message.conversationId,
       sdkSessionId,
       messageId: message.id,
+      attemptId: message.attemptId || null,
       model: result?.model || appliedModel() || defaultModel || '',
       usage,
       contextUsage,
@@ -1352,6 +1361,7 @@ export function createCopilotSdkSessionRunner({
       hasQuotaSnapshots: !!usage?.quotaSnapshots,
       cfiOverage: usage?.quotaSnapshots?.cfi_overage ?? null,
     }));
+    return lastTurnUsage;
   }
 
   /**
@@ -1372,9 +1382,10 @@ export function createCopilotSdkSessionRunner({
    * row still open — for as long as the socket stayed up. The result is unused
    * and the failure is already swallowed, so there was nothing to wait for.
    *
-   * BYOK sessions do not post at all: they spend the user's own OpenAI key
+   * BYOK sessions do not post here: they spend the user's own OpenAI key
    * rather than Copilot quota, and their usage events report `cost: 0`, so
-   * their numbers would only mislead on a card about the Copilot plan.
+   * their numbers would only mislead on a card about the Copilot plan. Their
+   * tokens still go to the token booking (postTurnTokens).
    */
   function postTurnUsage() {
     if (byokProvider || !lastTurnUsage || lastTurnUsage === postedTurnUsage) return;
@@ -1385,6 +1396,39 @@ export function createCopilotSdkSessionRunner({
       .catch((error) => { dbg('usage ingest failed', error?.message || String(error)); });
   }
 
+  /**
+   * Report a turn's own captured tokens per model to the token booking,
+   * from that turn's capture: a continuation that captured its
+   * usage meanwhile cannot take the turn's place. Fire-and-forget like the plan usage, but BYOK sessions post
+   * too, under their own billing (`byok-<provider type>`), which the relay
+   * keeps apart from the plan's. No cost: the plan bills in AI units, not
+   * dollars, and an own key's calls report 0.
+   */
+  function postTurnTokens(capture) {
+    if (!capture || postedTurnTokens.has(capture)) return;
+    postedTurnTokens.add(capture);
+    const models = (capture.usage?.models || []).map((entry) => ({
+      model: entry.model,
+      inputTokens: entry.inputTokens,
+      outputTokens: entry.outputTokens,
+      cacheWriteTokens: entry.cacheWriteTokens,
+      cacheReadTokens: entry.cacheReadTokens,
+      reasoningTokens: entry.reasoningTokens,
+    }));
+    if (!models.length || !capture.messageId) return;
+    const billing = byokProvider ? `byok-${String(byokProvider.type || 'openai').trim().toLowerCase()}` : '';
+    tokenPostChain = api('POST', '/api/turn-token-usage', {
+      conversationId: capture.conversationId,
+      turnId: capture.messageId,
+      runId: capture.attemptId || tokenRunId,
+      provider: 'github',
+      billing,
+      ...(sdkSessionId ? { nativeSessionId: sdkSessionId } : {}),
+      at: capture.capturedAt,
+      models,
+    }).catch((error) => { dbg('turn token ingest failed', error?.message || String(error)); });
+  }
+
   /**
    * Publish the session's model catalog to `/api/models/snapshot` (Phase 5A:
    * with the extension retired, worker snapshots and the server-side discovery
@@ -3161,7 +3205,14 @@ export function createCopilotSdkSessionRunner({
       model: '',
       // The runner's cross-turn knowledge of background agents rides in, so a
       // later turn's normalizer opens no lane for an agent spawned earlier.
-      normalizer: createNormalizerImpl({ isBackgroundAgent: (agentId) => agentDetails.has(agentId) }),
+      normalizer: createNormalizerImpl({
+        isBackgroundAgent: (agentId) => agentDetails.has(agentId),
+        // The raw counts of every model call, for checking the token rule
+        // against a real provider (counts only).
+        ...(String(env?.OAR_DEBUG_TOKEN_USAGE || '').trim() === '1'
+          ? { debugTokenUsage: (fields) => dbg('token usage', JSON.stringify(fields)) }
+          : {}),
+      }),
       result: null,
       failure: null,
       settled: false,
@@ -3730,7 +3781,7 @@ export function createCopilotSdkSessionRunner({
     const failure = turn.failure;
     // Capture only. The POST fires from driveTurn's `finally`, after the rows
     // have been published.
-    captureTurnUsage(turn.primaryEntry.message, result);
+    turn.usageCapture = captureTurnUsage(turn.primaryEntry.message, result) || null;
 
     const pending = turn.entries.filter((entry) => !entry.settled && entry.turn === turn);
     if (!pending.length) return;
@@ -4166,6 +4217,7 @@ export function createCopilotSdkSessionRunner({
       syncDeliveryReadiness();
       // The ingest is advisory, never awaited, and must never be able to
       // delay a reply that is already written.
+      postTurnTokens(turn.usageCapture);
       postTurnUsage();
     }
   }
@@ -5024,6 +5076,7 @@ export function createCopilotSdkSessionRunner({
     // never awaits this, which is what keeps a slow relay from holding a
     // finished reply.
     whenUsagePosted: () => usagePostChain,
+    whenTokensPosted: () => tokenPostChain,
     // The in-flight model-catalog snapshot POST — the same kind of seam.
     whenModelSnapshotPosted: () => modelSnapshotChain,
     // The in-flight queued-lane read — same kind of seam.

package/server/cursor-worker/cursor-turn-runner.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { buildCursorUserMessage } from './cursor-attachments.mjs';
 import { buildCursorContextUsage } from './cursor-context-usage.mjs';
 import { createSdkMessageNormalizer } from './sdk-message-normalizer.mjs';
@@ -23,6 +24,7 @@ import { renderMediaEmbedInstructionBlock } from '../../shared/media-embed-instr
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
 import { resolveFallbackContextLimitTokens } from '../../shared/context-window-fallbacks.mjs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
+import { PLAN_BOARD_ACTIONS } from '../../shared/plan-board-actions.mjs';
 import { explainLaunchFailure, missingWorkingDirectoryError } from '../../shared/worker-runtime/working-directory.mjs';
 
 // Stale-auth recovery budget per turn: expiry is routine on long-lived
@@ -34,12 +36,6 @@ const MAX_STALE_AUTH_RETRIES = 2;
 // exchanged auth goes stale around the 4h mark while the API key stays valid.
 const STALE_HANDLE_IDLE_MS = 30 * 60_000;
 
-const PLAN_BOARD_ACTIONS = [
-  { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
-  { id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' },
-  { id: 'exit_only', label: 'Stop here', mode: 'agent' },
-];
-
 // The Cursor SDK's SendOptions carries only model/mode/callbacks — there is
 // no per-turn instruction channel — so ask/autopilot steering rides on the
 // user message text, mirroring the Copilot extension's prompt-context
@@ -447,6 +443,45 @@ export function createCursorTurnRunner({
     });
   }
 
+  // A process without the row's attempt id names its run once (POST
+  // /api/turn-token-usage): a turn requeued onto a restarted worker is a
+  // second run of it.
+  const tokenRunId = randomUUID();
+
+  /**
+   * Ship the turn's tokens to the token booking: the SDK's usage
+   * for the turn, all its model calls together, under the turn's model.
+   * Cursor counts fresh input apart from the cache (cursor-context-usage.mjs
+   * adds the three up). No cost: the SDK prices no single turn. A field the
+   * SDK left out stays out, and the relay keeps it unknown. Fire-and-forget:
+   * it never throws and the turn does not wait on it.
+   */
+  async function publishTurnTokens(message, state, model, normalizer) {
+    try {
+      const usage = state.lastUsage || normalizer?.lastUsage || null;
+      const turnModel = state.responseModel || model || '';
+      if (!usage || typeof usage !== 'object' || !turnModel || !message?.id) return;
+      await api('POST', '/api/turn-token-usage', {
+        conversationId: message.conversationId,
+        turnId: String(message.id),
+        runId: message.attemptId || tokenRunId,
+        provider: 'cursor',
+        ...(agentHandle?.agentId ? { nativeSessionId: agentHandle.agentId } : {}),
+        at: new Date().toISOString(),
+        models: [{
+          model: turnModel,
+          inputTokens: usage.inputTokens,
+          outputTokens: usage.outputTokens,
+          cacheWriteTokens: usage.cacheWriteTokens,
+          cacheReadTokens: usage.cacheReadTokens,
+          reasoningTokens: usage.reasoningTokens,
+        }],
+      });
+    } catch (error) {
+      dbg('turn token publish failed', error?.message || String(error));
+    }
+  }
+
   /**
    * Report the agent's cumulative billed usage so the relay can book this
    * turn's increase against the configured monthly allowance. The model is
@@ -704,6 +739,7 @@ export function createCursorTurnRunner({
       // (the auth retry swaps it), so a discarded attempt's usage is not
       // republished over the retry's.
       await publishContextUsage(message, state, model, normalizer);
+      void publishTurnTokens(message, state, model, normalizer);
       await publishPlanUsage(message, state, model);
     }
 

package/server/db-schema.mjs

@@ -40,6 +40,8 @@ import { migrateQueueProvider } from './migrations/0031-queue-provider.mjs';
 import { migrateRuntimeSessionBillingSwitch } from './migrations/0032-runtime-session-billing-switch.mjs';
 import { migrateClaudeApiUsageCheckpoints } from './migrations/0033-claude-api-usage-checkpoints.mjs';
 import { migrateClaudeApiUsageTotals } from './migrations/0034-claude-api-usage-totals.mjs';
+import { migrateConversationPlanOnly } from './migrations/0035-conversation-plan-only.mjs';
+import { migrateTokenUsage } from './migrations/0036-token-usage.mjs';
 import { migrateImageConversationSchema } from './repositories/image-conversation-repository.mjs';
 
 // Mirrors DEFAULT_RELAY_MODE in server-runtime.mjs; used only by the one-time
@@ -1059,6 +1061,22 @@ try {
   console.warn(`[claude-api-usage] migration 0034 failed; retrying on next boot: ${error?.message || error}`);
 }
 
+// A plan-only conversation, handled like 0020.
+try {
+  migrateConversationPlanOnly(db);
+} catch (error) {
+  console.warn(`[plan-only] migration 0035 failed; retrying on next boot: ${error?.message || error}`);
+}
+
+// Tokens per turn and per day for every provider, with a one-time
+// copy of the Claude API and DeepSeek days. After 0025 and 0034: a missing
+// source throws here, so it is logged and retried next boot like 0034.
+try {
+  migrateTokenUsage(db);
+} catch (error) {
+  console.warn(`[token-usage] migration 0036 failed; retrying on next boot: ${error?.message || error}`);
+}
+
 const conversationColumns = db.prepare(`PRAGMA table_info(conversations)`).all().map((c) => c.name);
 if (!conversationColumns.includes('archived')) {
   db.exec(`ALTER TABLE conversations ADD COLUMN archived INTEGER NOT NULL DEFAULT 0`);

package/server/deepseek-worker/deepseek-claude-backend.mjs

@@ -35,6 +35,7 @@
 // (api-docs.deepseek.com, quick_start/agent_integrations/claude_code).
 
 import { deepseekAnthropicBaseUrl } from '../../shared/deepseek-api.mjs';
+import { estimateCost } from '../../shared/deepseek-pricing.mjs';
 import { isHostClaudeSessionVariable } from '../../shared/host-claude-session-env.mjs';
 import { CLAUDE_CLI_KEY_CHAT_SETTINGS, claudeCliPinnedEnv } from '../claude-worker/claude-cli-pinned-env.mjs';
 import {
@@ -262,6 +263,19 @@ export function createDeepSeekClaudeBackend({ env = process.env } = {}) {
     // relay's model ids (relayModel); the relay books what each report adds.
     // Claude Code's `total_cost_usd` is at Claude's prices and is not sent.
     usageRoute: '/api/deepseek-plan-usage',
+    // A turn's tokens (POST /api/turn-token-usage) are priced at DeepSeek's
+    // own rates for the time, as the card's estimate is: cache writes and
+    // fresh input are both misses. Null for a model the table has no price for.
+    turnTokenCost: (entry, at) => {
+      const costUsd = estimateCost({
+        model: entry.model,
+        at,
+        hitTokens: entry.cacheReadTokens,
+        missTokens: entry.inputTokens + entry.cacheWriteTokens,
+        outputTokens: entry.outputTokens,
+      });
+      return { costUsd, costSource: costUsd === null ? null : 'oar-deepseek-table' };
+    },
 
     // A Claude id is not a model of DeepSeek's to request, only one it may
     // have served (relayModel).

package/server/grok-worker/grok-turn-runner.mjs

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import {
   createGrokAgentHandle,
   startGrokTurn,
@@ -11,15 +12,10 @@ import { createPreviewInstructionsProvider } from '../../shared/preview-instruct
 import { fetchRemoteRelayInflight } from '../../shared/remote-relay-tool-core.mjs';
 import { renderMediaEmbedInstructionBlock } from '../../shared/media-embed-instructions.mjs';
 import { countPlanLikeLines } from '../../shared/plan-lines.mjs';
+import { PLAN_BOARD_ACTIONS } from '../../shared/plan-board-actions.mjs';
 import { EMPTY_TURN_COMPLETION_NOTE } from '../../shared/empty-turn-completion.mjs';
 import { explainLaunchFailure, missingWorkingDirectoryError } from '../../shared/worker-runtime/working-directory.mjs';
 
-const PLAN_BOARD_ACTIONS = [
-  { id: 'autopilot', label: 'Implement in autopilot', mode: 'autopilot' },
-  { id: 'interactive', label: 'Stop here and prompt myself', mode: 'agent' },
-  { id: 'exit_only', label: 'Stop here', mode: 'agent' },
-];
-
 // Grok has no exit-plan tool, so the only board source is the plan-mode
 // text-shape fallback; the payload matches the Claude/Cursor workers'.
 export function buildGrokPlanReadyBoardPayload({
@@ -352,6 +348,47 @@ export function createGrokTurnRunner({
     });
   }
 
+  // A process without the row's attempt id names its run once (POST
+  // /api/turn-token-usage): a turn requeued onto a restarted worker is a
+  // second run of it.
+  const tokenRunId = randomUUID();
+
+  /**
+   * Ship the turn's tokens to the token booking: per model where
+   * the agent breaks them down, else the turn's totals under its model, with
+   * the agent's own cost. Grok counts fresh input apart from the cache
+   * (grok-context-usage.mjs adds the three up). Advisory, fire-and-forget.
+   */
+  async function publishTurnTokens(message, state, model) {
+    const usage = state.turnUsage;
+    if (!usage || !message?.id) return;
+    const entry = (source, entryModel) => ({
+      model: entryModel,
+      inputTokens: source.inputTokens,
+      outputTokens: source.outputTokens,
+      cacheWriteTokens: source.cacheCreationTokens,
+      cacheReadTokens: source.cachedReadTokens,
+      reasoningTokens: source.reasoningTokens,
+      ...(source.costUsd !== null && source.costUsd !== undefined ? { costUsd: source.costUsd, costSource: 'provider' } : {}),
+    });
+    const turnModel = state.responseModel || usage.modelId || model || '';
+    const models = Array.isArray(usage.modelUsage) && usage.modelUsage.length
+      ? usage.modelUsage.map((item) => entry(item, item.model))
+      : (turnModel ? [entry(usage, turnModel)] : []);
+    if (!models.length) return;
+    await api('POST', '/api/turn-token-usage', {
+      conversationId: message.conversationId,
+      turnId: String(message.id),
+      runId: message.attemptId || tokenRunId,
+      provider: 'grok',
+      ...(sdkSessionId ? { nativeSessionId: sdkSessionId } : {}),
+      at: usage.capturedAt || new Date().toISOString(),
+      models,
+    }).catch((error) => {
+      dbg('turn token publish failed', error?.message || String(error));
+    });
+  }
+
   /**
    * Ship per-turn token/cost totals for the Check Usage Grok card. Advisory:
    * failures never disturb the turn reply.
@@ -521,6 +558,7 @@ export function createGrokTurnRunner({
       // awaits made it false.
       void publishContextUsage(message, state, model).catch(() => {});
       void publishPlanUsage(message, state).catch(() => {});
+      void publishTurnTokens(message, state, model).catch(() => {});
     }
 
     if (aborted) {

package/server/migrations/0001-add-structured-answer.mjs

@@ -12,13 +12,14 @@
  * Safe to run repeatedly (idempotent) and against a live database — ADD COLUMN
  * only takes a brief write lock and new columns default to NULL.
  *
- * Usage: node server/migrations/0001-add-structured-answer.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0001-add-structured-answer.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';
 
 const NEW_COLUMNS = [
   { name: 'structured_answer', ddl: 'ALTER TABLE relay_questions ADD COLUMN structured_answer TEXT' },
@@ -56,15 +57,12 @@ export function migrate(dbPath) {
   }
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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);
     const applied = result.applied.length ? result.applied.join(', ') : '(none)';
     const skipped = result.skipped.length ? result.skipped.join(', ') : '(none)';

package/server/migrations/0002-recent-workspace-roots-path-key.mjs

@@ -18,7 +18,7 @@
  *
  * Idempotent: re-running once path_key exists is a no-op.
  *
- * Usage: node server/migrations/0002-recent-workspace-roots-path-key.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0002-recent-workspace-roots-path-key.mjs [path/to/oar.db]
  */
 
 import { fileURLToPath } from 'url';
@@ -27,6 +27,7 @@ import process from 'process';
 import Database from 'better-sqlite3';
 
 import { normalizeWorkspaceRootKey } from '../services/workspace-root-path-policy.mjs';
+import { cliDbPath } from '../services/database-file.mjs';
 
 /**
  * Rebuild against an already-open database handle.
@@ -97,15 +98,12 @@ export function migrate(dbPath, options = {}) {
   }
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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 0002 on ${dbPath}`);
     if (result.applied) {

package/server/migrations/0003-push-subscriptions.mjs

@@ -14,13 +14,14 @@
  * databases; this module exists so existing databases upgrade at startup and
  * so the migration can be run offline against a db file.
  *
- * Usage: node server/migrations/0003-push-subscriptions.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0003-push-subscriptions.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';
 
 export const PUSH_SUBSCRIPTIONS_SCHEMA = `
   CREATE TABLE IF NOT EXISTS push_subscriptions (
@@ -67,15 +68,12 @@ export function migrate(dbPath) {
   }
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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 0003 on ${dbPath}`);
     console.log(result.applied ? '  created push_subscriptions' : `  skipped: ${result.reason}`);

package/server/migrations/0004-steer-settle-markers.mjs

@@ -20,7 +20,7 @@
  * Idempotent: the column is added once, the backfill only fills NULLs, and the
  * kind rewrite matches nothing once applied. Safe to run on every boot.
  *
- * Usage: node server/migrations/0004-steer-settle-markers.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0004-steer-settle-markers.mjs [path/to/oar.db]
  */
 
 import { fileURLToPath } from 'url';
@@ -29,6 +29,7 @@ import process from 'process';
 import Database from 'better-sqlite3';
 
 import { STEER_FOLDED_TEXT } from '../../shared/steer-settle-markers.mjs';
+import { cliDbPath } from '../services/database-file.mjs';
 
 function tableExists(db, name) {
   return !!db
@@ -97,15 +98,12 @@ export function migrate(dbPath) {
   }
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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 0004 on ${dbPath}`);
     console.log(result.applied

package/server/migrations/0005-remote-relays.mjs

@@ -15,13 +15,14 @@
  *
  * Additive and idempotent. Safe to run on every boot.
  *
- * Usage: node server/migrations/0005-remote-relays.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0005-remote-relays.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';
 
 function tableExists(db, name) {
   return !!db
@@ -68,15 +69,12 @@ export function migrate(dbPath) {
   }
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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 0005 on ${dbPath}`);
     console.log(result.applied

package/server/migrations/0006-workspace-root-settings.mjs

@@ -11,13 +11,14 @@
  *
  * Additive and idempotent. Safe to run on every boot.
  *
- * Usage: node server/migrations/0006-workspace-root-settings.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0006-workspace-root-settings.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';
 
 function tableExists(db, name) {
   return !!db
@@ -38,11 +39,6 @@ export function migrateWorkspaceRootSettings(db) {
   return { applied: !existed, tableCreated: !existed };
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 export function migrate(dbPath, options = {}) {
   const db = new Database(dbPath, options);
   try {
@@ -54,8 +50,10 @@ export function migrate(dbPath, options = {}) {
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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 0006 on ${dbPath}`);
     console.log(result.applied ? '  workspace_root_settings table created' : '  skipped: nothing to change');

package/server/migrations/0007-claude-cloud.mjs

@@ -17,13 +17,14 @@
  *
  * Additive and idempotent. Safe to run on every boot.
  *
- * Usage: node server/migrations/0007-claude-cloud.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0007-claude-cloud.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';
 
 const COLUMNS = Object.freeze([
   Object.freeze({ table: 'runtime_sessions', name: 'claude_cloud_session_id', type: 'TEXT' }),
@@ -53,11 +54,6 @@ export function migrateClaudeCloud(db) {
   return { applied: columnsAdded > 0, columnsAdded };
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 export function migrate(dbPath, options = {}) {
   const db = new Database(dbPath, options);
   try {
@@ -69,8 +65,10 @@ export function migrate(dbPath, options = {}) {
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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 0007 on ${dbPath}`);
     console.log(result.applied ? `  claude cloud columns added: ${result.columnsAdded}` : '  skipped: nothing to change');

package/server/migrations/0008-message-pins.mjs

@@ -11,13 +11,14 @@
  *
  * Additive and idempotent. Safe to run on every boot.
  *
- * Usage: node server/migrations/0008-message-pins.mjs [path/to/copilot.db]
+ * Usage: node server/migrations/0008-message-pins.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';
 
 function tableExists(db, name) {
   return !!db
@@ -54,11 +55,6 @@ export function migrateMessagePins(db) {
   return { applied: columnsAdded + indexesAdded > 0, columnsAdded, indexesAdded };
 }
 
-function defaultDbPath() {
-  const here = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(here, '..', 'data', 'copilot.db');
-}
-
 export function migrate(dbPath, options = {}) {
   const db = new Database(dbPath, options);
   try {
@@ -70,8 +66,10 @@ export function migrate(dbPath, options = {}) {
 
 const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isMain) {
-  const dbPath = process.argv[2] ? path.resolve(process.argv[2]) : defaultDbPath();
   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 0008 on ${dbPath}`);
     console.log(result.applied