@oar-sh/oar 0.9.11 → 0.9.13

package/server/grok-worker/acp-host-services.mjs

@@ -11,6 +11,7 @@
  * If a capability is dropped here, drop it from the initialize payload too.
  */
 import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import fs from 'node:fs/promises';
 import { windowsSystemToolPath } from '../../shared/windows-system-tools.mjs';
 
@@ -36,11 +37,22 @@ export function createAcpHostServices({
   platform = process.platform,
   spawnImpl = spawn,
   spawnSyncImpl = spawnSync,
+  // Full path of a program Windows ships (taskkill, Windows PowerShell), or
+  // its bare name when it is not where Windows keeps it.
+  systemToolPath = windowsSystemToolPath,
   fsImpl = fs,
+  // Told about every terminal's life (grok-background-tasks.mjs publishes
+  // them as background tasks): `started`, `output`, `killed`, `released`,
+  // `exited`. Advisory: an observer that throws never disturbs a terminal.
+  taskObserver = null,
   dbg = () => {},
 } = {}) {
   const terminals = new Map();
   let nextTerminalId = 1;
+  // Terminal ids become task ids and spool file names on the relay side: a
+  // fresh set of host services (the handle is rebuilt after a failed turn)
+  // must not reuse the ids of the one before it.
+  const terminalIdPrefix = `term-${randomBytes(3).toString('hex')}`;
   let inflightRequests = 0;
   let cachedWindowsShell = '';
   let disposed = false;
@@ -56,9 +68,9 @@ export function createAcpHostServices({
         timeout: 10_000,
         stdio: 'ignore',
       });
-      cachedWindowsShell = probe && probe.status === 0 ? 'pwsh' : windowsSystemToolPath('powershell');
+      cachedWindowsShell = probe && probe.status === 0 ? 'pwsh' : systemToolPath('powershell');
     } catch {
-      cachedWindowsShell = windowsSystemToolPath('powershell');
+      cachedWindowsShell = systemToolPath('powershell');
     }
     return cachedWindowsShell;
   }
@@ -77,9 +89,21 @@ export function createAcpHostServices({
     return { file: shell, args: ['-c', command] };
   }
 
+  function tell(hook, ...args) {
+    const fn = taskObserver?.[hook];
+    if (typeof fn !== 'function') return;
+    try {
+      const result = fn(...args);
+      if (result && typeof result.catch === 'function') result.catch(() => {});
+    } catch (error) {
+      dbg('terminal observer failed', hook, error?.message || String(error));
+    }
+  }
+
   function appendOutput(entry, chunk) {
     const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8');
     entry.lastActivityAt = Date.now();
+    tell('output', entry.terminalId, buf);
     entry.chunks.push(buf);
     entry.byteLength += buf.length;
     // ACP truncates from the start of the output: the most recent bytes win.
@@ -101,6 +125,7 @@ export function createAcpHostServices({
     if (entry.exitStatus) return;
     entry.exitStatus = exitStatus;
     for (const resolve of entry.exitWaiters.splice(0)) resolve(exitStatus);
+    tell('exited', entry.terminalId, exitStatus);
   }
 
   function getTerminal(terminalId) {
@@ -125,9 +150,12 @@ export function createAcpHostServices({
       windowsHide: true,
       shell: false,
     });
-    const terminalId = `term-${nextTerminalId++}`;
+    const terminalId = `${terminalIdPrefix}-${nextTerminalId++}`;
     const entry = {
       terminalId,
+      // What the task panel shows for it.
+      command: [command, ...(Array.isArray(params.args) ? params.args.map(String) : [])].join(' '),
+      startedAt: Date.now(),
       proc,
       chunks: [],
       byteLength: 0,
@@ -152,6 +180,12 @@ export function createAcpHostServices({
       });
     });
     terminals.set(terminalId, entry);
+    tell('started', {
+      terminalId,
+      command: entry.command,
+      startedAt: entry.startedAt,
+      kill: () => killEntryProcess(entry),
+    });
     dbg('terminal/create', terminalId, command.slice(0, 160));
     return { terminalId };
   }
@@ -179,7 +213,7 @@ export function createAcpHostServices({
     if (platform === 'win32' && entry.proc.pid) {
       // proc.kill() only reaches the shell; shells leave grandchildren behind.
       try {
-        spawnImpl(windowsSystemToolPath('taskkill'), ['/pid', String(entry.proc.pid), '/t', '/f'], {
+        spawnImpl(systemToolPath('taskkill'), ['/pid', String(entry.proc.pid), '/t', '/f'], {
           stdio: 'ignore',
           windowsHide: true,
         });
@@ -188,15 +222,19 @@ export function createAcpHostServices({
   }
 
   function terminalKill(params = {}) {
-    killEntryProcess(getTerminal(params.terminalId));
+    const entry = getTerminal(params.terminalId);
+    if (!entry.exitStatus) tell('killed', entry.terminalId);
+    killEntryProcess(entry);
     return null;
   }
 
   function terminalRelease(params = {}) {
     const entry = terminals.get(String(params?.terminalId || ''));
     if (!entry) return null;
+    if (!entry.exitStatus) tell('killed', entry.terminalId);
     killEntryProcess(entry);
     terminals.delete(entry.terminalId);
+    tell('released', entry.terminalId);
     return null;
   }
 
@@ -270,7 +308,11 @@ export function createAcpHostServices({
 
   function disposeAll() {
     disposed = true;
-    for (const entry of terminals.values()) killEntryProcess(entry);
+    for (const entry of terminals.values()) {
+      if (!entry.exitStatus) tell('killed', entry.terminalId);
+      killEntryProcess(entry);
+      tell('released', entry.terminalId);
+    }
     terminals.clear();
   }
 

package/server/grok-worker/grok-background-tasks.mjs

@@ -0,0 +1,248 @@
+/**
+ * The Grok worker's background-tasks publisher: every ACP terminal the agent
+ * opens (acp-host-services.mjs) is a shell row in the composer's
+ * background-tasks panel, with a console the relay reads from the session's
+ * spool file (shared/worker-runtime/task-output-spool.mjs), a Stop that kills
+ * the terminal, and a settle notice with the exit code when it ends.
+ *
+ * Same relay contract as the Claude and Copilot workers: the set is posted
+ * whole (REPLACE semantics) with its place in this worker's order
+ * (`{ epoch, seq }`); the heartbeat carries the live ids and the relay asks
+ * for the set again when its own differs; a settle notice the relay was not
+ * there to take is kept and sent again after the next answered heartbeat.
+ */
+import { createKeptPosts } from '../../shared/worker-runtime/kept-posts.mjs';
+import { createTaskOutputSpool } from '../../shared/worker-runtime/task-output-spool.mjs';
+
+const MAX_DESCRIPTION_CHARS = 500;
+// A bound on the post: the relay scrubs the command, then cuts it to 2,000.
+const MAX_COMMAND_CHARS = 8000;
+const SPOOL_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+// Ended terminals remembered for a late exit after their release.
+const MAX_TRACKED_TERMINALS = 200;
+// ACP runs every shell command through a terminal, most of them over in a
+// moment; only one that lives this long becomes a row (and later a settle
+// notice), so a `ls` never crowds the panel's ended rows.
+export const GROK_TERMINAL_PUBLISH_AFTER_MS = 2_000;
+
+export function createGrokTaskPublisher({
+  api,
+  sdkSessionId,
+  spool = null,
+  // The relay dropped the newest set: ask for a heartbeat (the worker wires
+  // it to requestPulse), at most once per ten seconds.
+  onBackgroundTaskSetStale = () => {},
+  publishAfterMs = GROK_TERMINAL_PUBLISH_AFTER_MS,
+  now = () => Date.now(),
+  dbg = () => {},
+} = {}) {
+  const taskSpool = spool || (() => {
+    try { return createTaskOutputSpool({ sessionId: sdkSessionId }); } catch (error) {
+      dbg('task output spool unavailable', error?.message || String(error));
+      return null;
+    }
+  })();
+  // terminalId → { taskId, description, startedAt, kill, live, published,
+  // publishTimer, exited, stopRequested, killRequested }. `live`: in the set.
+  const terminals = new Map();
+  const keptSettles = createKeptPosts({ api, dbg: (...args) => dbg('background task settle:', ...args) });
+  const epoch = now();
+  let seq = 0;
+  let staleNotedAt = 0;
+
+  // Ended tasks' files are kept about an hour for the relay; swept at start
+  // and hourly.
+  const sweep = () => {
+    try { taskSpool?.sweep(); } catch (error) { dbg('task output spool sweep failed', error?.message || String(error)); }
+  };
+  sweep();
+  const sweepTimer = setInterval(sweep, SPOOL_SWEEP_INTERVAL_MS);
+  sweepTimer.unref?.();
+
+  function outputPathFor(taskId) {
+    if (!taskSpool) return '';
+    try { return taskSpool.pathFor(taskId); } catch { return ''; }
+  }
+
+  function rowOf(entry) {
+    const outputPath = outputPathFor(entry.taskId);
+    return {
+      taskId: entry.taskId,
+      taskType: 'local_bash',
+      description: entry.description,
+      ...(entry.command ? { command: entry.command } : {}),
+      startedAt: entry.startedAt,
+      stoppable: true,
+      ...(outputPath ? { outputPath, outputKind: 'spool' } : {}),
+    };
+  }
+
+  function liveEntries() {
+    return [...terminals.values()].filter((entry) => entry.live);
+  }
+
+  function publish({ resync = false } = {}) {
+    const order = { epoch, seq: ++seq };
+    return Promise.resolve()
+      .then(() => api('POST', '/api/background-tasks', {
+        conversationId: sdkSessionId,
+        tasks: liveEntries().map(rowOf),
+        order,
+        ...(resync ? { resync: true } : {}),
+      }))
+      .then((answer) => {
+        // `stale` for the newest post: the relay holds no current set of
+        // this worker. An older one was only overtaken.
+        if (answer?.stale !== true || order.seq !== seq) return;
+        dbg('the relay dropped the newest background task set', answer.reason || '');
+        if (now() - staleNotedAt < 10_000) return;
+        staleNotedAt = now();
+        try { onBackgroundTaskSetStale(); } catch {}
+      })
+      .catch((error) => {
+        dbg('background task publish failed', error?.message || String(error));
+      });
+  }
+
+  function forgetOldest() {
+    while (terminals.size > MAX_TRACKED_TERMINALS) {
+      const oldest = [...terminals.entries()].find(([, entry]) => entry.exited || entry.released);
+      if (!oldest) break;
+      clearTimeout(oldest[1].publishTimer);
+      terminals.delete(oldest[0]);
+    }
+  }
+
+  /** `terminal/create` spawned a process. */
+  function started({ terminalId, command = '', startedAt = now(), kill = () => {} } = {}) {
+    const taskId = String(terminalId || '').trim();
+    if (!taskId) return Promise.resolve();
+    const entry = {
+      taskId,
+      description: String(command || '').trim().slice(0, MAX_DESCRIPTION_CHARS) || 'Terminal',
+      // The whole command line (the description is cut shorter), for the
+      // console's `| tail` marker.
+      command: String(command || '').trim().slice(0, MAX_COMMAND_CHARS),
+      startedAt,
+      kill,
+      live: false,
+      published: false,
+      publishTimer: null,
+      exited: false,
+      released: false,
+      stopRequested: false,
+      killRequested: false,
+    };
+    terminals.set(taskId, entry);
+    forgetOldest();
+    // Output is spooled from the first byte (output() below), so the console
+    // is complete when the row appears.
+    const show = () => {
+      entry.publishTimer = null;
+      if (entry.exited || entry.released) return Promise.resolve();
+      entry.live = true;
+      entry.published = true;
+      return publish();
+    };
+    if (!(publishAfterMs > 0)) return show();
+    entry.publishTimer = setTimeout(show, publishAfterMs);
+    entry.publishTimer.unref?.();
+    return Promise.resolve();
+  }
+
+  /** A chunk of the terminal's stdout/stderr, as it arrives. */
+  function output(terminalId, chunk) {
+    const taskId = String(terminalId || '').trim();
+    if (!taskId || !taskSpool || !terminals.has(taskId)) return;
+    const result = taskSpool.append(taskId, chunk);
+    if (result && result.ok === false) dbg('task output spool append failed', taskId);
+  }
+
+  /** The agent killed its own terminal (terminal/kill or release): a stop, not a failure. */
+  function killed(terminalId) {
+    const entry = terminals.get(String(terminalId || '').trim());
+    if (entry && !entry.exited) entry.killRequested = true;
+  }
+
+  /** `terminal/release`: the agent is done with it; the row goes. */
+  function released(terminalId) {
+    const entry = terminals.get(String(terminalId || '').trim());
+    if (!entry || entry.released) return Promise.resolve();
+    entry.released = true;
+    clearTimeout(entry.publishTimer);
+    entry.publishTimer = null;
+    if (!entry.live) return Promise.resolve();
+    entry.live = false;
+    return publish();
+  }
+
+  /** The process exited: say how, then publish the set without it. */
+  async function exited(terminalId, exitStatus = {}) {
+    const taskId = String(terminalId || '').trim();
+    const entry = terminals.get(taskId);
+    if (!entry || entry.exited) return;
+    entry.exited = true;
+    clearTimeout(entry.publishTimer);
+    entry.publishTimer = null;
+    const wasLive = entry.live;
+    entry.live = false;
+    try { taskSpool?.end?.(taskId); } catch {}
+    // Never shown: nothing to settle (its spool file is swept with the rest).
+    if (!entry.published) return;
+    const exitCode = Number.isInteger(exitStatus?.exitCode) ? exitStatus.exitCode : null;
+    const signal = String(exitStatus?.signal || '').trim();
+    const status = entry.stopRequested || entry.killRequested
+      ? 'stopped'
+      : (exitCode === 0 ? 'completed' : 'failed');
+    const outputPath = outputPathFor(taskId);
+    await keptSettles.post('/api/background-task-settled', {
+      conversationId: sdkSessionId,
+      taskId,
+      toolUseId: null,
+      status,
+      summary: exitCode !== null ? `exit code ${exitCode}` : (signal ? `killed by ${signal}` : null),
+      description: entry.description,
+      ...(entry.command ? { command: entry.command } : {}),
+      taskType: 'local_bash',
+      startedAt: entry.startedAt,
+      // Absent rather than null: a killed process has no exit code.
+      ...(exitCode !== null ? { exitCode } : {}),
+      ...(outputPath ? { outputPath, outputKind: 'spool' } : {}),
+    });
+    if (wasLive) await publish();
+  }
+
+  /** The panel's Stop (worker control `stop_background_task`). */
+  function stop(taskId) {
+    const entry = terminals.get(String(taskId || '').trim());
+    if (!entry || !entry.live || entry.exited) return false;
+    entry.stopRequested = true;
+    try {
+      entry.kill();
+      return true;
+    } catch (error) {
+      dbg('terminal stop failed', entry.taskId, error?.message || String(error));
+      return false;
+    }
+  }
+
+  return {
+    started,
+    output,
+    killed,
+    released,
+    exited,
+    stop,
+    /** The ids of the live terminals, for the heartbeat's digest. */
+    backgroundTaskIds: () => liveEntries().map((entry) => entry.taskId),
+    /** 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. */
+    flushKeptSettles: () => keptSettles.flush(),
+    sweep,
+    close() {
+      clearInterval(sweepTimer);
+      for (const entry of terminals.values()) clearTimeout(entry.publishTimer);
+    },
+  };
+}

package/server/grok-worker/grok-sdk-adapter.mjs

@@ -85,6 +85,8 @@ export async function createGrokAgentHandle({
   model = '',
   AcpClientImpl = AcpClient,
   createHostServicesImpl = createAcpHostServices,
+  // Told about every terminal (the worker's background-tasks publisher).
+  taskObserver = null,
   dbg = () => {},
 } = {}) {
   const client = new AcpClientImpl({
@@ -109,7 +111,7 @@ export async function createGrokAgentHandle({
   // The terminal/fs handlers backing the capabilities initialize() advertises.
   // They must be attached before the first prompt, or the agent's first shell
   // command deadlocks the turn waiting on terminal/create.
-  const hostServices = createHostServicesImpl({ cwd, env, dbg });
+  const hostServices = createHostServicesImpl({ cwd, env, dbg, ...(taskObserver ? { taskObserver } : {}) });
   hostServices.attach(client);
 
   await client.initialize();

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

@@ -16,6 +16,7 @@ import { installWorkerLogFile } from '../../shared/worker-runtime/worker-log-fil
 import { createControlPoller } from '../../shared/control-poller.mjs';
 import { installWorkerCrashGuard } from '../../shared/worker-crash-guard.mjs';
 import { createGrokTurnRunner } from './grok-turn-runner.mjs';
+import { createGrokTaskPublisher } from './grok-background-tasks.mjs';
 
 // Windows console launch: the launcher names the worker log, this copies
 // stdout/stderr into it. A no-op wherever the launcher redirects instead.
@@ -70,6 +71,16 @@ async function main() {
     abortAckNote: 'grok run cancelled',
     dbg,
   });
+  // Late-bound: the heartbeat controller is built after the runner.
+  let heartbeat = null;
+  // The agent's terminals, published as background tasks with a console
+  // (spooled output), a Stop and a settle notice.
+  const taskPublisher = createGrokTaskPublisher({
+    api,
+    sdkSessionId,
+    onBackgroundTaskSetStale: () => heartbeat?.requestPulse(),
+    dbg,
+  });
   const turnRunner = createGrokTurnRunner({
     api,
     sdkSessionId,
@@ -78,17 +89,23 @@ async function main() {
     command,
     alwaysApprove,
     controlPoller,
+    taskPublisher,
     dbg,
   });
 
   let heartbeatTimer = null;
-  const heartbeat = createHeartbeatController({
+  heartbeat = createHeartbeatController({
     api,
     pollMs: HEARTBEAT_MS,
     getSessionReady: () => true,
     getHeartbeatTimer: () => heartbeatTimer,
     setHeartbeatTimer: (timer) => { heartbeatTimer = timer; },
     getActiveQueueMessageId: () => turnRunner.getActiveQueueMessageId(),
+    // The relay holds the task set in memory only: the live terminal ids
+    // ride every beat, and a relay that is out of step asks for the set again.
+    getBackgroundTaskIds: () => turnRunner.backgroundTaskIds(),
+    onResyncBackgroundTasks: () => turnRunner.resyncBackgroundTasks(),
+    onAnswered: () => turnRunner.flushKeptTaskSettles(),
   });
 
   const wsLink = createWorkerWebSocketLink({
@@ -96,6 +113,9 @@ async function main() {
     token,
     dbg,
     getSessionReady: () => true,
+    // A relay that just (re)started learns of the terminals from the digest
+    // on the next beat; ask for it now.
+    onServerHello: () => heartbeat.requestPulse(),
     getSessionId: () => sdkSessionId,
     getPid: () => process.pid,
     onDeliver: async (pending, reason) => {
@@ -111,6 +131,17 @@ async function main() {
         return false;
       }
     },
+    onControl: async (control) => {
+      const type = String(control?.type || '').trim();
+      if (type === 'stop_background_task') {
+        // The panel's Stop on a terminal row: kill its process.
+        const taskId = String(control?.taskId || '').trim();
+        dbg('stop background task control', taskId);
+        turnRunner.stopBackgroundTask(taskId);
+        return;
+      }
+      dbg('unknown worker control ignored', type || '(none)');
+    },
   });
 
   const shutdown = async (signal) => {
@@ -118,6 +149,7 @@ async function main() {
     try { wsLink.stop(); } catch {}
     try { heartbeat.stopHeartbeat(); } catch {}
     try { controlPoller.stop(); } catch {}
+    try { taskPublisher.close(); } catch {}
     // Bounded: a hung ACP agent teardown must never leave the process
     // ignoring the supervisor's SIGTERM.
     try {

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

@@ -122,8 +122,12 @@ export function createGrokTurnRunner({
   // gets through ACP `mcpServers`; undefined builds the default for this
   // worker's conversation, null leaves Grok without it.
   oarMcpServer = undefined,
+  // The terminals' background-task rows (grok-background-tasks.mjs), built
+  // by the worker entry; without one no terminal is published.
+  taskPublisher = null,
   dbg = () => {},
 } = {}) {
+  const terminalTasks = taskPublisher;
   // The OAR MCP server gives Grok the relay's real tools — `preview`, and
   // `remote_relay` when remotes are paired — bound to this conversation.
   // `OAR_MCP_SERVER=0` is the operator's way back to the preview instruction
@@ -203,6 +207,7 @@ export function createGrokTurnRunner({
       alwaysApprove,
       nativeSessionId: resumeId,
       model,
+      ...(terminalTasks ? { taskObserver: terminalTasks } : {}),
       // The adapter builds the ACP client and opens the session in one step,
       // so the client it builds must already carry the MCP servers — for
       // session/new and for session/load alike.
@@ -611,6 +616,12 @@ export function createGrokTurnRunner({
     getActiveQueueAttempt,
     isTurnActive,
     dispose,
+    // The terminals as background tasks: the heartbeat's digest and resync,
+    // the panel's Stop, kept settle notices.
+    backgroundTaskIds: () => terminalTasks?.backgroundTaskIds() || [],
+    resyncBackgroundTasks: () => terminalTasks?.resync(),
+    stopBackgroundTask: (taskId) => terminalTasks?.stop(taskId) || false,
+    flushKeptTaskSettles: () => terminalTasks?.flushKeptSettles(),
     setTurnCeilingMs(value) {
       const ms = Number(value);
       turnCeilingMs = Number.isFinite(ms) && ms >= 0 ? ms : null;

package/server/migrations/0017-conversation-history-indexes.mjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * Migration: two indexes for loading the history of long conversations.
+ *
+ * - `idx_queue_response_message` on `queue(response_message_id)`: the
+ *   sub-agent records of a reply are found through the queue row that
+ *   produced it, one lookup per assistant message on every history page.
+ *   Without the index each lookup scanned the whole queue.
+ * - `idx_messages_conv_order` on `messages(conversation_id, timestamp, id)`:
+ *   a history page is selected in SQL in conversation order (timestamp, then
+ *   id); the index serves that order and the check that a conversation's
+ *   rows can be paged that way, without reading the message rows.
+ *
+ * Additive and idempotent. Safe to run on every boot. An older build ignores
+ * both indexes.
+ *
+ * Usage: node server/migrations/0017-conversation-history-indexes.mjs [path/to/copilot.db]
+ */
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+import process from 'process';
+import Database from 'better-sqlite3';
+
+function tableExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`)
+    .get(name);
+}
+
+function indexExists(db, name) {
+  return !!db
+    .prepare(`SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?`)
+    .get(name);
+}
+
+function columnNames(db, table) {
+  return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((column) => column.name));
+}
+
+export function migrateConversationHistoryIndexes(db) {
+  if (!tableExists(db, 'messages') || !tableExists(db, 'queue')) {
+    throw new Error('messages or queue is missing (the base schema has not run)');
+  }
+  if (!columnNames(db, 'queue').has('response_message_id')) {
+    throw new Error('queue.response_message_id is missing (the base schema has not run)');
+  }
+  let indexesAdded = 0;
+  if (!indexExists(db, 'idx_queue_response_message')) {
+    db.exec(`CREATE INDEX idx_queue_response_message ON queue(response_message_id)`);
+    indexesAdded += 1;
+  }
+  if (!indexExists(db, 'idx_messages_conv_order')) {
+    db.exec(`CREATE INDEX idx_messages_conv_order ON messages(conversation_id, timestamp, id)`);
+    indexesAdded += 1;
+  }
+  return { applied: indexesAdded > 0, 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 {
+    return migrateConversationHistoryIndexes(db);
+  } finally {
+    db.close();
+  }
+}
+
+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 {
+    const result = migrate(dbPath);
+    console.log(`Migration 0017 on ${dbPath}`);
+    console.log(result.applied
+      ? `  conversation history indexes: added ${result.indexesAdded}`
+      : '  skipped: nothing to change');
+    process.exit(0);
+  } catch (err) {
+    console.error(`Migration 0017 failed: ${err?.message || err}`);
+    process.exit(1);
+  }
+}