throughline 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -10,6 +10,30 @@ shipped to npm but were not individually tagged on GitHub.
 
 ## [Unreleased]
 
+## [0.8.3] — 2026-07-20
+
+### Fixed
+
+- Codex fresh-thread handoffs now detect when they were launched from Codex
+  Desktop and open the new local task with the app's
+  `codex://threads/<thread-id>` deep link instead of spawning a Terminal
+  `codex resume` session. `--open-host desktop` is available explicitly;
+  VS Code and CLI opening behavior is unchanged.
+- Concurrent CLI and Codex hook processes now configure a bounded SQLite busy
+  timeout and avoid reapplying WAL mode when it is already active. A transient
+  writer or WAL recovery lock no longer makes DB initialization fail
+  immediately, and a failed initialization is never retained as the singleton.
+
+## [0.8.2] — 2026-07-20
+
+### Fixed
+
+- Windows native Codex hook commands now prefix quoted Node executables with the
+  PowerShell call operator `&`. POSIX command strings are unchanged, and the
+  existing managed-hook detector continues to recognize the canonical commands.
+
+## [0.8.1] — 2026-07-19
+
 ### Fixed
 
 - **Native factory diagnostics now report the database compatibility label from
@@ -1109,7 +1133,10 @@ two attempts, instrument first instead of patching again.
 
 ---
 
-[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.3...HEAD
+[0.8.3]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.2...v0.8.3
+[0.8.2]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.1...v0.8.2
+[0.8.1]: https://github.com/kitepon-rgb/Throughline/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/kitepon-rgb/Throughline/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.3...v0.7.0
 [0.6.3]: https://github.com/kitepon-rgb/Throughline/compare/v0.6.2...v0.6.3

package/README.md

@@ -304,7 +304,7 @@ throughline codex-summarize --session codex:<thread-id> --json
 throughline codex-resume --session codex:<thread-id>
 throughline codex-resume --session codex:<thread-id> --format handoff
 throughline codex-handoff-start --session codex:<thread-id>
-throughline codex-handoff-start --session codex:<thread-id> --execute --open-host vscode
+throughline codex-handoff-start --session codex:<thread-id> --execute --open-host desktop
 throughline codex-handoff-smoke --session codex:<thread-id>
 throughline codex-handoff-model-smoke --session codex:<thread-id> --dry-run --json
 THROUGHLINE_EXPERIMENTAL_CODEX_HANDOFF_MODEL_SMOKE=1 \
@@ -567,7 +567,9 @@ live model smoke, and can include the prompt with `--print-prompt`. With
 `--memo-stdin`, it also propagates `--memo-stdin` into the replay commands and
 reminds you to pipe the same memo when using them separately. Add `--execute`
 to create a new Codex app-server thread, inject the handoff memory as a
-developer item, and open it with `--open-host auto|vscode|cli|none`. The
+developer item, and open it with `--open-host auto|desktop|vscode|cli|none`. `auto`
+opens the new task in Codex Desktop when invoked there, while preserving the
+existing VS Code and CLI routes. The
 individual commands remain available: validate the fresh-thread handoff with
 `throughline codex-handoff-smoke --session codex:<thread-id>`, optionally audit
 the model-smoke boundary with
@@ -785,7 +787,7 @@ aggregate は collection が既定OFFで、canonical dotagents config の
 | `throughline codex-summarize --session codex:<id>` | Summarize captured Codex L2 into L1 with the Codex CLI backend |
 | `throughline codex-resume --session codex:<id>` | Render Codex active-work context from a captured Codex session |
 | `throughline codex-resume --session codex:<id> --format handoff` | Render a concise fresh-thread handoff prompt without mutating the current thread |
-| `throughline codex-handoff-start --session codex:<id>` | Guided start plan for moving handoff memory into a new Codex thread; add `--execute` to create the thread through app-server, inject developer memory, and open it with `--open-host auto\|vscode\|cli\|none`; use `--print-prompt` to include the prompt and `--memo-stdin` to carry a current-work memo |
+| `throughline codex-handoff-start --session codex:<id>` | Guided start plan for moving handoff memory into a new Codex thread; add `--execute` to create the thread through app-server, inject developer memory, and open it with `--open-host auto\|desktop\|vscode\|cli\|none`; `auto` keeps Codex Desktop handoffs in the Desktop app; use `--print-prompt` to include the prompt and `--memo-stdin` to carry a current-work memo |
 | `throughline codex-handoff-smoke --session codex:<id>` | Read-only validation that the fresh-thread handoff prompt is pasteable before starting a new thread |
 | `throughline codex-handoff-model-smoke --session codex:<id>` | Experimental marker smoke for the handoff prompt. `--dry-run` checks readiness / command boundary without starting Codex exec; `--memo-stdin` carries a current-work memo; live `codex exec --ephemeral --sandbox read-only` requires explicit env opt-in |
 | `throughline codex-visibility-smoke --session codex:<id>` | Experimental Codex app-server marker smoke; injects memory and starts a model turn |

package/bin/throughline.mjs

@@ -248,7 +248,7 @@ Usage:
                               render command, optional --print-prompt, and
                               --memo-stdin replay guidance. Use --execute to
                               create a new app-server thread, inject handoff
-                              memory, and open it with --open-host auto|vscode|cli|none
+                              memory, and open it with --open-host auto|desktop|vscode|cli|none
   throughline codex-visibility-smoke
                               Experimental: inject Codex active-work memory and
                               start a marker-check model turn. Requires

package/docs/05_codex_first_roadmap.md

@@ -271,7 +271,7 @@ Phase 3 implementation result (2026-05-06):
 - [x] `throughline codex-resume --format handoff` は current thread を mutate せず、新規 Codex thread に貼る短い handoff prompt を返す。handoff view は L2 件数 / 本文長 / detail refs を cap し、full active-work context は通常 text renderer に残す。
 - [x] `throughline codex-handoff-smoke --session codex:<thread_id>` は新規 thread handoff prompt を read-only に検査し、prompt size / required sections / mutation boundary / detail command dedupe を固定する。
 - [x] `throughline codex-handoff-model-smoke --session codex:<thread_id>` は明示 opt-in 時だけ `codex exec --ephemeral --ignore-user-config --ignore-rules --sandbox read-only` で handoff prompt の marker model smoke を行う。`--dry-run` は env なしで readiness / command boundary を監査し、`--print-prompt` で結合 prompt を出せる。`--memo-stdin` で Codex-primary current-work memo も同じ prompt に含める。structural handoff smoke が ready でなければ拒否し、current thread は mutate しない。
-- [x] `throughline codex-handoff-start --session codex:<thread_id>` は safe continuation の guided entrypoint として、structural smoke / model smoke dry-run / handoff render / optional live smoke / `--print-prompt` をまとめて表示する。`--execute` では app-server `thread/start` + `thread/inject_items` で新 thread に developer memory を注入し、`--open-host auto|vscode|cli|none` で表示を開く。`--memo-stdin` 時は replay 用コマンドにも `--memo-stdin` を伝播し、same memo を pipe する注意を出す。
+- [x] `throughline codex-handoff-start --session codex:<thread_id>` は safe continuation の guided entrypoint として、structural smoke / model smoke dry-run / handoff render / optional live smoke / `--print-prompt` をまとめて表示する。`--execute` では app-server `thread/start` + `thread/inject_items` で新 thread に developer memory を注入し、`--open-host auto|desktop|vscode|cli|none` で表示を開く。`auto` は Codex Desktop 起点（`CODEX_INTERNAL_ORIGINATOR_OVERRIDE="Codex Desktop"` または `__CFBundleIdentifier=com.openai.codex`）を CLI より先に識別し、Desktop の `codex://threads/<thread-id>` deep link で新 thread を同アプリ内に開く。VS Code と CLI の既存経路は維持する。`--memo-stdin` 時は replay 用コマンドにも `--memo-stdin` を伝播し、same memo を pipe する注意を出す。
 - [x] `throughline codex-resume --format item-json` は Codex developer message item JSON を返す。
 - [x] `codex-resume` は explicit session を受け取れる。省略時は cwd の最新 `codex:%` session だけを対象にし、Claude session を混ぜない。
 - [x] `src/codex-handoff.test.mjs` / `src/codex-resume.test.mjs` で renderer と CLI shape を固定した。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "throughline",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "type": "module",
   "description": "Claude Code hooks plugin for structured context compression (/clear-safe persistent memory)",
   "keywords": [

package/src/cli/codex-handoff-start.mjs

@@ -79,8 +79,8 @@ function parseArgs(args) {
       out.execute = true;
     } else if (arg === '--open-host') {
       const value = args[++i];
-      if (!['auto', 'vscode', 'cli', 'none'].includes(value)) {
-        throw new Error('--open-host must be auto, vscode, cli, or none');
+      if (!['auto', 'desktop', 'vscode', 'cli', 'none'].includes(value)) {
+        throw new Error('--open-host must be auto, desktop, vscode, cli, or none');
       }
       out.openHost = value;
     } else if (arg === '--codex-app-server-bin') {
@@ -247,6 +247,7 @@ function renderTextResult(result) {
   }
   if (result.open) {
     lines.push(`  open status:       ${result.open.status}`);
+    lines.push(`  desktop url:       ${result.open.desktopUrl}`);
     lines.push(`  vscode url:        ${result.open.vscodeUrl}`);
     lines.push(`  resume command:    ${result.open.resumeCommand}`);
   }
@@ -268,21 +269,34 @@ function renderTextResult(result) {
   return lines.join('\n');
 }
 
-function resolveOpenHost(host) {
+function isCodexDesktopEnvironment(env) {
+  const originator = env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE?.trim()
+    .toLowerCase()
+    .replace(/[_-]+/g, ' ');
+  return originator === 'codex desktop' || env.__CFBundleIdentifier === 'com.openai.codex';
+}
+
+function resolveOpenHost(host, env = process.env) {
   if (host !== 'auto') return host;
+  if (isCodexDesktopEnvironment(env)) return 'desktop';
   if (
-    process.env.VSCODE_IPC_HOOK_CLI ||
-    process.env.VSCODE_IPC_HOOK ||
-    process.env.TERM_PROGRAM === 'vscode' ||
-    process.env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE === 'codex_vscode'
+    env.VSCODE_IPC_HOOK_CLI ||
+    env.VSCODE_IPC_HOOK ||
+    env.TERM_PROGRAM === 'vscode' ||
+    env.CODEX_INTERNAL_ORIGINATOR_OVERRIDE === 'codex_vscode'
   ) {
     return 'vscode';
   }
   return 'cli';
 }
 
+function buildCodexDesktopUrl(threadId) {
+  return `codex://threads/${encodeURIComponent(threadId)}`;
+}
+
 function openStartedCodexThread({ threadId, host, cwd }) {
   const resolvedHost = resolveOpenHost(host);
+  const desktopUrl = buildCodexDesktopUrl(threadId);
   const vscodeUrl = `vscode://openai.chatgpt/local/${encodeURIComponent(threadId)}`;
   const resumeCommand = `codex resume ${threadId} --no-alt-screen`;
   if (resolvedHost === 'none') {
@@ -290,23 +304,26 @@ function openStartedCodexThread({ threadId, host, cwd }) {
       status: 'skipped',
       reason: 'open_host_none',
       host: resolvedHost,
+      desktopUrl,
       vscodeUrl,
       resumeCommand,
     };
   }
 
-  if (resolvedHost === 'vscode') {
+  if (resolvedHost === 'desktop' || resolvedHost === 'vscode') {
+    const url = resolvedHost === 'desktop' ? desktopUrl : vscodeUrl;
     const result =
       process.platform === 'darwin'
-        ? spawnSync('open', [vscodeUrl], { encoding: 'utf8' })
+        ? spawnSync('open', [url], { encoding: 'utf8' })
         : process.platform === 'win32'
-          ? spawnSync('cmd.exe', ['/c', 'start', '', vscodeUrl], { encoding: 'utf8' })
-          : spawnSync('xdg-open', [vscodeUrl], { encoding: 'utf8' });
+          ? spawnSync('cmd.exe', ['/c', 'start', '', url], { encoding: 'utf8' })
+          : spawnSync('xdg-open', [url], { encoding: 'utf8' });
     if (result.status !== 0) {
       return {
         status: 'failed',
-        reason: 'vscode_deep_link_open_failed',
+        reason: `${resolvedHost}_deep_link_open_failed`,
         host: resolvedHost,
+        desktopUrl,
         vscodeUrl,
         resumeCommand,
         error: (result.stderr || result.stdout || '').trim(),
@@ -314,8 +331,9 @@ function openStartedCodexThread({ threadId, host, cwd }) {
     }
     return {
       status: 'opened',
-      reason: 'vscode_deep_link_opened',
+      reason: `${resolvedHost}_deep_link_opened`,
       host: resolvedHost,
+      desktopUrl,
       vscodeUrl,
       resumeCommand,
     };
@@ -337,6 +355,7 @@ end tell
           status: 'failed',
           reason: 'terminal_open_failed',
           host: resolvedHost,
+          desktopUrl,
           vscodeUrl,
           resumeCommand,
           error: (result.stderr || result.stdout || '').trim(),
@@ -346,6 +365,7 @@ end tell
         status: 'opened',
         reason: 'terminal_resume_opened',
         host: resolvedHost,
+        desktopUrl,
         vscodeUrl,
         resumeCommand,
       };
@@ -354,6 +374,7 @@ end tell
       status: 'manual',
       reason: 'cli_auto_open_unsupported_on_platform',
       host: resolvedHost,
+      desktopUrl,
       vscodeUrl,
       resumeCommand,
     };
@@ -363,6 +384,7 @@ end tell
     status: 'failed',
     reason: 'unsupported_open_host',
     host: resolvedHost,
+    desktopUrl,
     vscodeUrl,
     resumeCommand,
   };
@@ -460,6 +482,9 @@ export async function run(args) {
 }
 
 export const _internal = {
+  buildCodexDesktopUrl,
+  isCodexDesktopEnvironment,
   parseArgs,
   renderTextResult,
+  resolveOpenHost,
 };

package/src/cli/codex-handoff-start.test.mjs

@@ -5,9 +5,43 @@ import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'nod
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { _internal } from './codex-handoff-start.mjs';
 
 const REPO_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 
+test('codex-handoff-start recognizes desktop as an explicit open host', () => {
+  assert.equal(_internal.parseArgs(['--open-host', 'desktop']).openHost, 'desktop');
+});
+
+test('codex-handoff-start auto-selects Codex Desktop before inherited VS Code signals', () => {
+  assert.equal(
+    _internal.resolveOpenHost('auto', {
+      CODEX_INTERNAL_ORIGINATOR_OVERRIDE: 'Codex Desktop',
+      VSCODE_IPC_HOOK_CLI: '/tmp/stale-vscode.sock',
+    }),
+    'desktop',
+  );
+  assert.equal(
+    _internal.resolveOpenHost('auto', { __CFBundleIdentifier: 'com.openai.codex' }),
+    'desktop',
+  );
+});
+
+test('codex-handoff-start keeps VS Code and CLI auto-open behavior', () => {
+  assert.equal(
+    _internal.resolveOpenHost('auto', { CODEX_INTERNAL_ORIGINATOR_OVERRIDE: 'codex_vscode' }),
+    'vscode',
+  );
+  assert.equal(_internal.resolveOpenHost('auto', {}), 'cli');
+});
+
+test('codex-handoff-start builds the Codex Desktop local thread deep link', () => {
+  assert.equal(
+    _internal.buildCodexDesktopUrl('019f78e8-77ec-7d73-aee4-fb8e3869200a'),
+    'codex://threads/019f78e8-77ec-7d73-aee4-fb8e3869200a',
+  );
+});
+
 function makeTempHome() {
   return mkdtempSync(join(tmpdir(), 'tl-codex-handoff-start-home-'));
 }
@@ -256,6 +290,10 @@ test('codex-handoff-start execute creates a new app-server thread and can skip o
     assert.equal(payload.newThread.injectSent, true);
     assert.equal(payload.newThread.turnStatus, 'not-started');
     assert.equal(payload.open.status, 'skipped');
+    assert.equal(
+      payload.open.desktopUrl,
+      'codex://threads/019e2000-0000-7000-8000-000000000001',
+    );
     assert.equal(payload.open.vscodeUrl, 'vscode://openai.chatgpt/local/019e2000-0000-7000-8000-000000000001');
     assert.match(payload.open.resumeCommand, /codex resume 019e2000-0000-7000-8000-000000000001/);
 

package/src/cli/help.test.mjs

@@ -49,7 +49,7 @@ test('CLI help exposes guided Codex handoff and guarded execute semantics', () =
   }
   assert.match(result.stdout, /Fresh-thread Codex handoff start plan/);
   assert.match(result.stdout, /Use --execute to/);
-  assert.match(result.stdout, /--open-host auto\|vscode\|cli\|none/);
+  assert.match(result.stdout, /--open-host auto\|desktop\|vscode\|cli\|none/);
   assert.match(result.stdout, /throughline trim --execute/);
   assert.match(result.stdout, /injectable DB memory/);
   assert.match(result.stdout, /matching/);

package/src/cli/install.mjs

@@ -101,22 +101,30 @@ export function resolveCodexHookNodePath({
 export function buildCodexStopHookCommand({
   nodePath = resolveCodexHookNodePath(),
   cliScriptPath = join(PACKAGE_ROOT, 'bin', 'throughline.mjs'),
+  platform = process.platform,
 } = {}) {
-  return `${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} codex-hook stop`;
+  return buildCodexHookCommand('stop', { nodePath, cliScriptPath, platform });
 }
 
 export function buildCodexUserPromptSubmitHookCommand({
   nodePath = resolveCodexHookNodePath(),
   cliScriptPath = join(PACKAGE_ROOT, 'bin', 'throughline.mjs'),
+  platform = process.platform,
 } = {}) {
-  return `${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} codex-hook user-prompt-submit`;
+  return buildCodexHookCommand('user-prompt-submit', { nodePath, cliScriptPath, platform });
 }
 
 export function buildCodexPostToolUseHookCommand({
   nodePath = resolveCodexHookNodePath(),
   cliScriptPath = join(PACKAGE_ROOT, 'bin', 'throughline.mjs'),
+  platform = process.platform,
 } = {}) {
-  return `${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} codex-hook post-tool-use`;
+  return buildCodexHookCommand('post-tool-use', { nodePath, cliScriptPath, platform });
+}
+
+function buildCodexHookCommand(event, { nodePath, cliScriptPath, platform }) {
+  const prefix = platform === 'win32' ? '& ' : '';
+  return `${prefix}${quoteCommandPath(nodePath)} ${quoteCommandPath(cliScriptPath)} codex-hook ${event}`;
 }
 
 export function isThroughlineCodexHookCommand(command) {

package/src/cli/install.test.mjs

@@ -8,6 +8,7 @@ import {
   buildCodexPostToolUseHookCommand,
   buildCodexStopHookCommand,
   buildCodexUserPromptSubmitHookCommand,
+  isThroughlineCodexHookCommand,
   resolveCodexHookNodePath,
   run,
   resolveThroughlineOnPath,
@@ -141,6 +142,27 @@ test('global install registers Codex session hooks and enables hooks features',
   }
 });
 
+test('Codex hook builders use the PowerShell call operator on Windows only', () => {
+  const options = {
+    nodePath: String.raw`C:\Program Files\nodejs\node.exe`,
+    cliScriptPath: String.raw`C:\Users\Kite\App Data\Roaming\npm\node_modules\throughline\bin\throughline.mjs`,
+  };
+  assert.equal(
+    buildCodexStopHookCommand({ ...options, platform: 'win32' }),
+    String.raw`& "C:\Program Files\nodejs\node.exe" "C:\Users\Kite\App Data\Roaming\npm\node_modules\throughline\bin\throughline.mjs" codex-hook stop`,
+  );
+  assert.equal(
+    buildCodexUserPromptSubmitHookCommand({ ...options, platform: 'win32' }),
+    String.raw`& "C:\Program Files\nodejs\node.exe" "C:\Users\Kite\App Data\Roaming\npm\node_modules\throughline\bin\throughline.mjs" codex-hook user-prompt-submit`,
+  );
+  assert.equal(
+    buildCodexPostToolUseHookCommand({ ...options, platform: 'win32' }),
+    String.raw`& "C:\Program Files\nodejs\node.exe" "C:\Users\Kite\App Data\Roaming\npm\node_modules\throughline\bin\throughline.mjs" codex-hook post-tool-use`,
+  );
+  assert.equal(buildCodexStopHookCommand({ ...options, platform: 'linux' }).startsWith('& '), false);
+  assert.equal(isThroughlineCodexHookCommand(buildCodexStopHookCommand({ ...options, platform: 'win32' })), true);
+});
+
 test('global install copies Throughline Codex skill to ~/.codex/skills/', async () => {
   const home = makeTempHome();
   if (home.resolved !== home.dir) {

package/src/db-contention.test.mjs

@@ -0,0 +1,95 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const DB_MODULE_URL = pathToFileURL(fileURLToPath(new URL('./db.mjs', import.meta.url))).href;
+
+function waitForLine(stream, expected) {
+  return new Promise((resolve, reject) => {
+    let output = '';
+    const onData = (chunk) => {
+      output += chunk;
+      if (output.includes(expected)) {
+        stream.off('data', onData);
+        resolve();
+      }
+    };
+    stream.on('data', onData);
+    stream.once('error', reject);
+  });
+}
+
+function waitForExit(child) {
+  return new Promise((resolve, reject) => {
+    let stderr = '';
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.once('error', reject);
+    child.once('close', (code) => resolve({ code, stderr }));
+  });
+}
+
+test('getDb configures a bounded SQLite busy timeout for concurrent hook processes', () => {
+  const home = mkdtempSync(join(tmpdir(), 'throughline-db-timeout-'));
+  try {
+    const result = spawnSync(process.execPath, ['--input-type=module', '-e', `
+      import { getDb } from ${JSON.stringify(DB_MODULE_URL)};
+      const db = getDb();
+      process.stdout.write(String(db.prepare('PRAGMA busy_timeout').get().timeout));
+      db.close();
+    `], {
+      env: { ...process.env, HOME: home, USERPROFILE: home },
+      encoding: 'utf8',
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, '5000');
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('getDb reuses an existing WAL database while another process owns the writer lock', async () => {
+  const home = mkdtempSync(join(tmpdir(), 'throughline-db-contention-'));
+  const env = { ...process.env, HOME: home, USERPROFILE: home };
+  const initialize = spawn(process.execPath, ['--input-type=module', '-e', `
+    import { getDb } from ${JSON.stringify(DB_MODULE_URL)};
+    getDb().close();
+  `], { env, stdio: ['ignore', 'ignore', 'pipe'] });
+  assert.deepEqual(await waitForExit(initialize), { code: 0, stderr: '' });
+
+  const holder = spawn(process.execPath, ['--input-type=module', '-e', `
+    import { DatabaseSync } from 'node:sqlite';
+    import { join } from 'node:path';
+    const db = new DatabaseSync(join(process.env.HOME, '.throughline', 'throughline.db'));
+    db.exec('CREATE TABLE IF NOT EXISTS contention_probe (value TEXT)');
+    db.exec("BEGIN IMMEDIATE; INSERT INTO contention_probe VALUES ('held')");
+    process.stdout.write('locked\\n');
+    setTimeout(() => {
+      db.exec('COMMIT');
+      db.close();
+    }, 500);
+  `], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  await waitForLine(holder.stdout, 'locked\n');
+
+  const contender = spawn(process.execPath, ['--input-type=module', '-e', `
+    import { getDb } from ${JSON.stringify(DB_MODULE_URL)};
+    const db = getDb();
+    const mode = db.prepare('PRAGMA journal_mode').get().journal_mode;
+    db.close();
+    if (String(mode).toLowerCase() !== 'wal') process.exit(2);
+  `], { env, stdio: ['ignore', 'ignore', 'pipe'] });
+
+  const [holderResult, contenderResult] = await Promise.all([
+    waitForExit(holder),
+    waitForExit(contender),
+  ]);
+  try {
+    assert.deepEqual(holderResult, { code: 0, stderr: '' });
+    assert.deepEqual(contenderResult, { code: 0, stderr: '' });
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});

package/src/db.mjs

@@ -9,6 +9,7 @@ import { join } from 'path';
 
 const DB_DIR = join(homedir(), '.throughline');
 const DB_PATH = join(DB_DIR, 'throughline.db');
+const DB_BUSY_TIMEOUT_MS = 5_000;
 export const CURRENT_VERSION = 9;
 
 let _db = null;
@@ -248,11 +249,19 @@ export function getDb() {
 
   mkdirSync(DB_DIR, { recursive: true });
 
-  _db = new DatabaseSync(DB_PATH);
-  _db.exec('PRAGMA journal_mode = WAL');
-  _db.exec('PRAGMA foreign_keys = ON');
-
-  initSchema(_db);
-
-  return _db;
+  const db = new DatabaseSync(DB_PATH);
+  try {
+    db.exec(`PRAGMA busy_timeout = ${DB_BUSY_TIMEOUT_MS}`);
+    const journalMode = db.prepare('PRAGMA journal_mode').get().journal_mode;
+    if (String(journalMode).toLowerCase() !== 'wal') {
+      db.exec('PRAGMA journal_mode = WAL');
+    }
+    db.exec('PRAGMA foreign_keys = ON');
+    initSchema(db);
+    _db = db;
+    return _db;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
 }