@oar-sh/oar 0.9.19 → 0.9.21

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

@@ -20,6 +20,7 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import {
   createRunnerLinkBridge,
@@ -52,6 +53,10 @@ async function main() {
 
   const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
     || path.resolve(__dirname, '..', 'config.json');
+  // The code this process started on, read once from the repo root and kept
+  // for its whole life: the relay recycles a worker whose build differs from
+  // its own, and a tree that moves on under us must not change our answer.
+  const buildId = resolveBuildId(path.resolve(__dirname, '..', '..')).id;
   // Two reads of the same small file. Collapsing them to one would mean
   // re-implementing `resolveRelayServerUrl`'s env override, host
   // normalisation and port defaulting inside this worker — a live contract
@@ -129,6 +134,7 @@ async function main() {
   let heartbeatTimer = null;
   heartbeat = createHeartbeatController({
     api,
+    buildId,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
     getHeartbeatTimer: () => heartbeatTimer,
@@ -158,6 +164,7 @@ async function main() {
     serverUrl,
     token,
     dbg,
+    buildId,
     getSessionReady: () => true,
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
@@ -238,7 +245,7 @@ async function main() {
     getActiveQueueMessageIds: () => turnRunner.getActiveQueueMessageIds(),
   });
 
-  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'}`);
+  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
   heartbeat.startHeartbeat();
   wsLink.start();
 }

package/server/cursor-worker/cursor-session-worker.mjs

@@ -13,10 +13,12 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createCursorTurnRunner } from './cursor-turn-runner.mjs';
+import { buildCursorSteeringState } from './cursor-worker-steering.mjs';
 import { resolveCursorSessionStoreDir } from '../services/cursor-session-root-service.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
@@ -48,6 +50,10 @@ async function main() {
 
   const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
     || path.resolve(__dirname, '..', 'config.json');
+  // The code this process started on, read once from the repo root and kept
+  // for its whole life: the relay recycles a worker whose build differs from
+  // its own, and a tree that moves on under us must not change our answer.
+  const buildId = resolveBuildId(path.resolve(__dirname, '..', '..')).id;
   const serverUrl = resolveRelayServerUrl({ configPath });
   const token = loadTokenFromConfig(configPath);
   const cwd = String(process.env.COPILOT_WORKSPACE_ROOT || '').trim() || process.cwd();
@@ -93,17 +99,22 @@ async function main() {
   let heartbeatTimer = null;
   const heartbeat = createHeartbeatController({
     api,
+    buildId,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
     getHeartbeatTimer: () => heartbeatTimer,
     setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
     getActiveQueueMessageId: () => turnRunner.getActiveQueueMessageId(),
+    // No steering here; the snapshot tells the relay when it may replace
+    // this worker: between turns (the agent handle is rebuilt on demand).
+    getSteeringState: () => buildCursorSteeringState(turnRunner),
   });
 
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
     token,
     dbg,
+    buildId,
     getSessionReady: () => true,
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
@@ -146,7 +157,7 @@ async function main() {
     getActiveQueueMessageIds: () => [turnRunner.getActiveQueueAttempt()],
   });
 
-  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'}`);
+  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
   heartbeat.startHeartbeat();
   wsLink.start();
 }

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/cursor-worker/cursor-worker-steering.mjs

@@ -0,0 +1,20 @@
+/**
+ * The Cursor worker's heartbeat steering snapshot, from its turn runner
+ * (cursor-turn-runner.mjs). A module of its own so it can be tested: the
+ * worker main runs at import.
+ *
+ * Only a turn holds the release. The Cursor SDK tells the runner of no work
+ * that outlives a run: whether a sub-agent or a background shell can keep
+ * running after the run's result is not something its types say, and the
+ * runner sees neither of them, so there is no background count to send. The
+ * relay's quiet rule (10 minutes without a delivery or a turn end) covers
+ * what the SDK does not say.
+ */
+import { buildSimpleSteeringState } from '../../shared/worker-runtime/simple-steering-state.mjs';
+
+export function buildCursorSteeringState(turnRunner) {
+  return buildSimpleSteeringState({
+    activeAttempt: turnRunner.getActiveQueueAttempt(),
+    turnActive: turnRunner.isTurnActive(),
+  });
+}

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-background-tasks.mjs

@@ -235,6 +235,15 @@ export function createGrokTaskPublisher({
     stop,
     /** The ids of the live terminals, for the heartbeat's digest. */
     backgroundTaskIds: () => liveEntries().map((entry) => entry.taskId),
+    /**
+     * Terminals whose process runs and that the agent has not released, from
+     * the moment they start: a superset of the live ids, which wait out the
+     * publish grace first. What may die with the worker, so the relay must
+     * not replace it while any is open (the steering snapshot's count); a
+     * `sleep 600` started a second before a recycle is as live as one the
+     * panel already shows.
+     */
+    openTerminalCount: () => [...terminals.values()].filter((entry) => !entry.exited && !entry.released).length,
     /** The relay asked for the set again (heartbeat answer). */
     resync: () => publish({ resync: true }),
     /** The relay answered a heartbeat: settle notices kept for it go out. */

package/server/grok-worker/grok-session-worker.mjs

@@ -12,10 +12,12 @@ import {
 import { createApiClient } from '../../shared/worker-runtime/api-client.mjs';
 import { createWorkerWebSocketLink } from '../../shared/worker-runtime/worker-websocket-link.mjs';
 import { createHeartbeatController } from '../../shared/worker-runtime/heartbeat.mjs';
+import { resolveBuildId } from '../../shared/build-id.mjs';
 import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-file.mjs';
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createGrokTurnRunner } from './grok-turn-runner.mjs';
+import { buildGrokSteeringState } from './grok-worker-steering.mjs';
 import { createGrokTaskPublisher } from './grok-background-tasks.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
@@ -47,6 +49,10 @@ async function main() {
 
   const configPath = String(process.env.COPILOT_WEB_RELAY_CONFIG || '').trim()
     || path.resolve(__dirname, '..', 'config.json');
+  // The code this process started on, read once from the repo root and kept
+  // for its whole life: the relay recycles a worker whose build differs from
+  // its own, and a tree that moves on under us must not change our answer.
+  const buildId = resolveBuildId(path.resolve(__dirname, '..', '..')).id;
   const serverUrl = resolveRelayServerUrl({ configPath });
   const token = loadTokenFromConfig(configPath);
   const cwd = String(process.env.COPILOT_WORKSPACE_ROOT || '').trim() || process.cwd();
@@ -96,6 +102,7 @@ async function main() {
   let heartbeatTimer = null;
   heartbeat = createHeartbeatController({
     api,
+    buildId,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
     getHeartbeatTimer: () => heartbeatTimer,
@@ -106,12 +113,16 @@ async function main() {
     getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
     onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
     onAnswered: () => turnRunner.flushKeptTaskSettles(),
+    // No steering here; the snapshot tells the relay when it may replace
+    // this worker: no turn, and no open terminal (they end with the worker).
+    getSteeringState: () => buildGrokSteeringState(turnRunner),
   });
 
   const wsLink = createWorkerWebSocketLink({
     serverUrl,
     token,
     dbg,
+    buildId,
     getSessionReady: () => true,
     // A relay that just (re)started learns of the terminals from the digest
     // on the next beat; ask for it now.
@@ -171,7 +182,7 @@ async function main() {
     getActiveQueueMessageIds: () => [turnRunner.getActiveQueueAttempt()],
   });
 
-  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'}`);
+  dbg(`starting session=${sdkSessionId.slice(0, 8)} server=${serverUrl} cwd=${cwd} model=${defaultModel || 'default'} build=${buildId || 'unknown'}`);
   heartbeat.startHeartbeat();
   wsLink.start();
 }

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) {
@@ -629,6 +667,9 @@ export function createGrokTurnRunner({
     // The terminals as background tasks: the heartbeat's digest and resync,
     // the panel's Stop, kept settle notices.
     backgroundTaskIds: () => terminalTasks?.backgroundTaskIds() || [],
+    // Every terminal that runs and is not released, published or not yet:
+    // the steering snapshot's background count (grok-worker-steering.mjs).
+    openTerminalCount: () => terminalTasks?.openTerminalCount?.() || 0,
     resyncBackgroundTasks: () => terminalTasks?.resync(),
     stopBackgroundTask: (taskId) => terminalTasks?.stop(taskId) || false,
     flushKeptTaskSettles: () => terminalTasks?.flushKeptSettles(),

package/server/grok-worker/grok-worker-steering.mjs

@@ -0,0 +1,23 @@
+/**
+ * The Grok worker's heartbeat steering snapshot, from its turn runner
+ * (grok-turn-runner.mjs). A module of its own so it can be tested: the worker
+ * main runs at import.
+ *
+ * A turn holds the release, then any open terminal: it dies with the worker.
+ * Counted from the terminal's start (`openTerminalCount`), not from when it
+ * becomes a panel row (`backgroundTaskIds`, after a 2 s grace), so a command
+ * started just before a recycle sweep still holds it.
+ */
+import { buildSimpleSteeringState } from '../../shared/worker-runtime/simple-steering-state.mjs';
+
+export function buildGrokSteeringState(turnRunner) {
+  const open = Number(turnRunner.openTerminalCount?.()) || 0;
+  // The live ids are open terminals too; the larger count wins should the two
+  // ever disagree.
+  const listed = turnRunner.backgroundTaskIds?.().length || 0;
+  return buildSimpleSteeringState({
+    activeAttempt: turnRunner.getActiveQueueAttempt(),
+    turnActive: turnRunner.isTurnActive(),
+    backgroundTaskCount: Math.max(open, listed),
+  });
+}

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