@kabmo-labs/kabmo 0.3.0 → 0.4.0

package/src/client/hooks/chat/waiting/hold.test.ts

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The hold path: what makes a prompt deferred instead of sent.
+ *
+ * Three behaviours are pinned, and each is a decision rather than an
+ * implementation detail:
+ *
+ *   - a stale pick (the session finished while the draft was written) SENDS,
+ *     and says so — a wait created on it would be released by the next sweep;
+ *   - a refusal KEEPS the draft, because the user's text is the one thing that
+ *     cannot be recovered from anywhere else;
+ *   - a success writes the pending row's cue, which is what keeps the sidebar
+ *     row on screen until the dispatch adopts it.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { holdPromptForDependency, type HoldDeps } from '@/client/hooks/chat/waiting/hold';
+import {
+  listPendingSessions,
+  releasePendingSession,
+  startPendingSession,
+} from '@/client/hooks/chat/omp/pending-sessions';
+import { pendingSessionWait } from '@/client/hooks/chat/omp/pending-waiting';
+import type { WaitingCandidate } from '@/client/components/workspace/chat-timeline/chat-input/WaitingDependencyPicker';
+import type { Attachment } from '@/shared/types/chat';
+
+const DEPENDENCY: WaitingCandidate = { id: 'sess-a', title: 'Refactor parser', folderName: 'alpha' };
+
+interface Recorded {
+  drafts: string[];
+  attachments: Attachment[][];
+  errors: string[];
+  cleared: number;
+  posted: Record<string, unknown>[];
+}
+
+const nativeFetch = globalThis.fetch;
+/** The id `startPendingSession` minted for this case; the store owns the clock. */
+let pendingId = '';
+
+function harness(overrides: Partial<HoldDeps> = {}): { deps: HoldDeps; recorded: Recorded } {
+  const recorded: Recorded = { drafts: [], attachments: [], errors: [], cleared: 0, posted: [] };
+  const deps: HoldDeps = {
+    sessionId: pendingId,
+    folders: [{ id: 1, name: 'alpha', project_path: '/tmp/alpha', isExpanded: true, hasMore: false, totalSessions: 0, sessions: [] }],
+    selectedFolderId: 1,
+    composerModelRef: { current: { provider: 'anthropic', modelId: 'claude', thinkingLevel: 'high' } },
+    accessModeRef: { current: 'always-ask' },
+    spawnModesRef: { current: { plan: false, goal: false } },
+    streamStatusMap: { 'sess-a': 'stream' },
+    setInputValue: (value) => recorded.drafts.push(value),
+    setAttachments: (value) => recorded.attachments.push(value),
+    reportActionError: (message) => recorded.errors.push(message),
+    clearChoice: () => { recorded.cleared += 1; },
+    ...overrides,
+  };
+  return { deps, recorded };
+}
+
+beforeEach(() => {
+  pendingId = startPendingSession(1);
+  (globalThis as Record<string, unknown>).fetch = async (_input: unknown, init?: { body?: string }) => {
+    const body = init?.body ? JSON.parse(init.body) : {};
+    createdBody = body;
+    return new Response(JSON.stringify({ prompt: { id: 'wait-1', ...body, status: 'waiting' } }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  };
+});
+
+let createdBody: Record<string, unknown> = {};
+
+afterEach(() => {
+  globalThis.fetch = nativeFetch;
+  for (const entry of listPendingSessions()) releasePendingSession(entry.id);
+  createdBody = {};
+});
+
+describe('holdPromptForDependency', () => {
+  test('writes the row and marks the pending chat as waiting', async () => {
+    const { deps, recorded } = harness();
+    const held = await holdPromptForDependency(deps, DEPENDENCY, 'summarise it', []);
+
+    expect(held).toBe(true);
+    expect(recorded.drafts).toEqual(['']);
+    expect(recorded.attachments).toEqual([[]]);
+    expect(recorded.cleared).toBe(1);
+    expect(createdBody).toMatchObject({
+      dependsOn: 'sess-a',
+      dependsOnTitle: 'Refactor parser',
+      prompt: 'summarise it',
+      cwd: '/tmp/alpha',
+      folderId: 1,
+      model: { provider: 'anthropic', modelId: 'claude', thinkingLevel: 'high', accessMode: 'always-ask' },
+    });
+    expect(pendingSessionWait(pendingId)).toMatchObject({ waitId: 'wait-1', dependsOn: 'sess-a' });
+  });
+
+  test('no pick means the caller sends normally', async () => {
+    const { deps, recorded } = harness();
+    expect(await holdPromptForDependency(deps, null, 'hello', [])).toBe(false);
+    expect(recorded.drafts).toEqual([]);
+  });
+
+  // The dropdown was opened while the dependency was running; by the time the
+  // user hit send it had finished. Holding would be a wait of zero length.
+  test('a dependency that finished meanwhile sends instead, and says so', async () => {
+    const { deps, recorded } = harness({ streamStatusMap: { 'sess-a': 'finish' } });
+    expect(await holdPromptForDependency(deps, DEPENDENCY, 'hello', [])).toBe(false);
+    expect(recorded.errors).toEqual(['"Refactor parser" has already finished — sending now instead of waiting.']);
+    expect(recorded.cleared).toBe(1);
+    expect(recorded.drafts).toEqual([]);
+  });
+
+  test('a refused request keeps the draft and reports the server reason', async () => {
+    (globalThis as Record<string, unknown>).fetch = async () =>
+      new Response(JSON.stringify({ error: 'That session has already finished' }), {
+        status: 409,
+        headers: { 'content-type': 'application/json' },
+      });
+    const { deps, recorded } = harness();
+    expect(await holdPromptForDependency(deps, DEPENDENCY, 'hello', [])).toBe(false);
+    expect(recorded.errors).toEqual(['That session has already finished']);
+    expect(recorded.drafts).toEqual([]);
+    expect(pendingSessionWait(pendingId)).toBeNull();
+  });
+
+  test('a chat with no workspace is refused before anything is written', async () => {
+    const { deps, recorded } = harness({ folders: [], selectedFolderId: null });
+    expect(await holdPromptForDependency(deps, DEPENDENCY, 'hello', [])).toBe(false);
+    expect(recorded.errors).toEqual(['Pick a workspace before holding this prompt.']);
+    expect(createdBody).toEqual({});
+  });
+});

package/src/client/hooks/chat/waiting/hold.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Sending a NEW chat's prompt into a wait instead of dispatching it now.
+ *
+ * The prompt never reaches omp from here: the row is written server-side and a
+ * sweep spawns the session when the dependency finishes. That is why this path
+ * clears the composer and marks the pending row, and why it does NOT arm the
+ * generating state — nothing is running yet, and a spinner would say otherwise.
+ *
+ * The dependency is re-checked against the live status map at send time. A
+ * dropdown opened a minute ago can name a session that has since finished, and
+ * a prompt held on it would be released by the very next sweep: the user asked
+ * to wait, so the honest outcome is to send it now and say so.
+ */
+
+import type { Attachment } from '@/shared/types/chat';
+import type { WorkspaceFolderData } from '@/shared/types/workspace';
+import { prepareQueuedAttachments } from '@/shared/lib/chat/attachments';
+import { createWaitingPromptRequest } from '@/client/hooks/chat/waiting/store';
+import { markPendingSessionWaiting } from '@/client/hooks/chat/omp/pending-waiting';
+import type { WaitingCandidate } from '@/client/components/workspace/chat-timeline/chat-input/WaitingDependencyPicker';
+
+/**
+ * The slice of the composer's deps record a hold needs.
+ *
+ * Structural, not an import of the actions record: the caller passes that whole
+ * record and TypeScript checks it against this, so the two stay decoupled and
+ * this module never depends on the send hook's shape.
+ */
+export interface ComposerHoldDeps {
+  sessionId: string | null;
+  folders: WorkspaceFolderData[];
+  selectedFolderId: number | null;
+  composerModelRef: { current: { provider: string; modelId: string; thinkingLevel: string } | null };
+  accessModeRef: { current: string };
+  spawnSelectionRef?: { current: { plan: boolean; goal: boolean } | null };
+  streamStatusMap?: Record<string, string | undefined>;
+  setInputValue: (value: string) => void;
+  setInputAttachments: (attachments: Attachment[] | ((prev: Attachment[]) => Attachment[])) => void;
+  reportActionError: (message: string) => void;
+  clearWaitingDependency?: () => void;
+  waitingDependencyRef?: { current: WaitingCandidate | null };
+}
+
+/**
+ * The composer's own entry point: hold the draft if a dependency is picked and
+ * the chat is idle, else answer false and let the normal send proceed.
+ *
+ * Idle is part of the condition rather than the caller's business: a chat with
+ * a run in flight queues its follow-up (or steers), which is a different
+ * decision made further down the send path.
+ */
+export async function holdFromComposer(
+  deps: ComposerHoldDeps,
+  text: string,
+  attachments: Attachment[],
+  busy: boolean,
+): Promise<boolean> {
+  const choice = deps.waitingDependencyRef?.current ?? null;
+  if (!choice || busy) return false;
+  return holdPromptForDependency({
+    sessionId: deps.sessionId,
+    folders: deps.folders,
+    selectedFolderId: deps.selectedFolderId,
+    composerModelRef: deps.composerModelRef,
+    accessModeRef: deps.accessModeRef,
+    spawnModesRef: deps.spawnSelectionRef ?? { current: null },
+    streamStatusMap: deps.streamStatusMap ?? {},
+    setInputValue: deps.setInputValue,
+    setAttachments: (next) => deps.setInputAttachments(next),
+    reportActionError: deps.reportActionError,
+    clearChoice: () => deps.clearWaitingDependency?.(),
+  }, choice, text, attachments);
+}
+
+export interface HoldDeps {
+  sessionId: string | null;
+  folders: WorkspaceFolderData[];
+  selectedFolderId: number | null;
+  composerModelRef: { current: { provider: string; modelId: string; thinkingLevel: string } | null };
+  accessModeRef: { current: string };
+  spawnModesRef: { current: { plan: boolean; goal: boolean } | null };
+  streamStatusMap: Record<string, string | undefined>;
+  setInputValue: (value: string) => void;
+  setAttachments: (attachments: Attachment[]) => void;
+  reportActionError: (message: string) => void;
+  /** The dependency pick, cleared once the prompt is held. */
+  clearChoice: () => void;
+}
+
+/**
+ * Hold `text` until `dependency` finishes.
+ *
+ * Returns true when the prompt was held — the caller must then do nothing else.
+ * A false return means the caller should fall through to a normal send: either
+ * there is no dependency, or it is no longer running.
+ */
+export async function holdPromptForDependency(
+  deps: HoldDeps,
+  dependency: WaitingCandidate | null,
+  text: string,
+  attachments: Attachment[],
+): Promise<boolean> {
+  if (!dependency) return false;
+  if (deps.streamStatusMap[dependency.id] !== 'stream') {
+    // Stale pick: the session finished while the draft was being written. Send
+    // normally rather than creating a wait that releases on the next sweep.
+    deps.reportActionError(`"${dependency.title}" has already finished — sending now instead of waiting.`);
+    deps.clearChoice();
+    return false;
+  }
+  const folder = deps.folders.find((entry) => String(entry.id) === String(deps.selectedFolderId));
+  const cwd = folder?.project_path || folder?.name;
+  if (!cwd) {
+    deps.reportActionError('Pick a workspace before holding this prompt.');
+    return false;
+  }
+
+  // Attachments become the persisted shape here, while the live `File` handles
+  // still exist: the server sends the prompt hours later, from the row.
+  const prepared = await prepareQueuedAttachments(attachments);
+  const composerPick = deps.composerModelRef.current;
+  try {
+    const created = await createWaitingPromptRequest({
+      pendingId: deps.sessionId,
+      dependsOn: dependency.id,
+      dependsOnTitle: dependency.title,
+      prompt: text,
+      attachments: prepared,
+      model: composerPick ? { ...composerPick, accessMode: deps.accessModeRef.current } : null,
+      modes: deps.spawnModesRef.current,
+      cwd,
+      folderId: folder ? Number(folder.id) : null,
+    });
+    if (deps.sessionId) {
+      markPendingSessionWaiting(deps.sessionId, {
+        waitId: created.id,
+        dependsOn: dependency.id,
+        dependsOnTitle: dependency.title,
+      });
+    }
+    deps.setInputValue('');
+    deps.setAttachments([]);
+    deps.clearChoice();
+    return true;
+  } catch (error) {
+    // The draft is KEPT: a refusal that also threw away the prompt would be the
+    // worst of both outcomes, and the composer still holds what the user wrote.
+    deps.reportActionError(error instanceof Error ? error.message : String(error));
+    return false;
+  }
+}

package/src/client/hooks/chat/waiting/store.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client view of the waiting prompts (`waiting_prompts`, owned by the server).
+ *
+ * The panel is a VIEW, exactly like the follow-up queue: the server holds the
+ * clock, the row is the state, and this hook reads it off the `waiting` topic.
+ * The HTTP route is the fallback for a socket that is down.
+ */
+
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import { useRealtimeTopic } from '@/client/hooks/ui/realtime';
+import { TOPIC_WAITING } from '@/shared/lib/realtime/protocol';
+import type { WaitingPrompt } from '@/shared/types/waiting';
+
+export interface WaitingPromptsState {
+  prompts: WaitingPrompt[];
+  /**
+   * Whether the list has been READ from the server.
+   *
+   * Load-bearing for anything that CLEARS state from an absence: before the
+   * first payload, "no row names this wait" is not a fact, it is a page that
+   * has not loaded yet. Clearing on it deleted a cue the user had just created —
+   * the controller's effect runs on the render the hold triggers, one frame
+   * before the topic's first snapshot.
+   */
+  loaded: boolean;
+  /** Ask the server for a fresh snapshot (a manual refresh). */
+  refresh: () => void;
+}
+
+export function useWaitingPrompts(): WaitingPromptsState {
+  const topic = useRealtimeTopic<WaitingPrompt[]>(TOPIC_WAITING);
+  const [fallback, setFallback] = useState<WaitingPrompt[]>([]);
+  const [loadedFallback, setLoadedFallback] = useState(false);
+
+  // The topic is the source; the HTTP read only fills in before the first frame
+  // lands, or when the socket is down (a phone that just woke).
+  useEffect(() => {
+    if (Array.isArray(topic.data)) return;
+    let active = true;
+    fetch('/api/waiting')
+      .then((response) => (response.ok ? response.json() : null))
+      .then((data) => {
+        if (!active || !Array.isArray(data?.prompts)) return;
+        setFallback(data.prompts as WaitingPrompt[]);
+        setLoadedFallback(true);
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, [topic.data]);
+
+  const fromTopic = Array.isArray(topic.data);
+  const prompts = fromTopic ? (topic.data as WaitingPrompt[]) : fallback;
+  const refresh = useCallback(() => topic.refresh(), [topic]);
+  return {
+    prompts,
+    // The HTTP read counts too: it is the same list, and a socket that is down
+    // must not leave every consumer believing the server holds nothing.
+    loaded: fromTopic || loadedFallback,
+    refresh,
+  };
+}
+
+/** Create a held prompt. Throws the server's own reason on a refusal. */
+export async function createWaitingPromptRequest(input: {
+  pendingId: string | null;
+  dependsOn: string;
+  dependsOnTitle: string | null;
+  prompt: string;
+  attachments: unknown[];
+  model: unknown;
+  modes: { plan: boolean; goal: boolean } | null;
+  cwd: string;
+  folderId: number | null;
+}): Promise<WaitingPrompt> {
+  const response = await fetch('/api/waiting', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+  });
+  const data = await response.json().catch(() => null);
+  if (!response.ok || !data?.prompt) {
+    throw new Error(typeof data?.error === 'string' ? data.error : `HTTP ${response.status}`);
+  }
+  return data.prompt as WaitingPrompt;
+}
+
+/** Cancel a held prompt. Returns the server's refusal rather than swallowing it. */
+export async function cancelWaitingPromptRequest(id: string): Promise<{ ok: boolean; error?: string }> {
+  const response = await fetch(`/api/waiting?id=${encodeURIComponent(id)}`, { method: 'DELETE' });
+  if (response.ok) return { ok: true };
+  const data = await response.json().catch(() => null);
+  return { ok: false, error: typeof data?.error === 'string' ? data.error : `HTTP ${response.status}` };
+}

package/src/client/hooks/workspace/left-dock.ts

@@ -0,0 +1,132 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The left dock's state, as the desktop layout and its bar read it.
+ *
+ * Backed by the GLOBAL `app_settings.omp_left_panels` (see
+ * `shared/lib/workspace/left-dock.ts`), not by `layout.*` session state: the
+ * dock lists the same views in every chat, so a placement stored per session
+ * would move the user's arrangement when they picked another session.
+ *
+ * The read is synchronous from the primed settings snapshot, so the first render
+ * already knows whether the bar is drawn. A write notifies every reader on
+ * screen, because they all resolve against this one module-level cache.
+ *
+ * The snapshot is compared by IDENTITY of the stored value: `writeSetting`
+ * replaces it with the exact object a write handed it, so a reference comparison
+ * is both correct and free — a rebuilt object would make
+ * `useSyncExternalStore` see a change on every render and loop.
+ */
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import { useSyncExternalStore } from 'preact/compat';
+import { readKabmoSetting } from '@/shared/lib/settings/client';
+import {
+  LEFT_DOCK_SETTING_KEY,
+  readLeftDock,
+  setPanelSide as persistPanelSide,
+  writeLeftDock,
+  type LeftDockState,
+  type PanelSide,
+} from '@/shared/lib/workspace/left-dock';
+import { resolveLeftDockWidth, saveLeftDockWidth } from '@/shared/lib/workspace/left-dock-width';
+
+const listeners = new Set<() => void>();
+
+/** The stored value the cache was built from, and the state it produced. */
+let lastSource: unknown;
+let cached: LeftDockState = { enabled: false, panels: [] };
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function snapshot(): LeftDockState {
+  const source = readKabmoSetting<unknown>(LEFT_DOCK_SETTING_KEY);
+  if (source === lastSource) return cached;
+  lastSource = source;
+  cached = readLeftDock();
+  return cached;
+}
+
+function publish(): void {
+  lastSource = undefined;
+  for (const listener of listeners) listener();
+}
+
+export interface LeftDockHandle extends LeftDockState {
+  /** Draw the dock's activity bar. Off by default. */
+  setEnabled: (enabled: boolean) => void;
+  /**
+   * Place a plugin panel on the left, or send it back to the right.
+   *
+   * Placing a panel TURNS THE RAIL ON. The rail exists to reach the panels on
+   * it, so leaving it off after a successful placement would be a move with no
+   * button, no view and no way to undo it from the bar — the settings row would
+   * be the only control, which is exactly the state a user reads as broken.
+   * Moving a panel back to the right does NOT turn the rail off: that is the
+   * user's switch, and the dock may still be worth showing.
+   */
+  setSide: (panelId: string, side: PanelSide) => void;
+  /** The width this view opens at, and the writer a drag commits through. */
+  widthOf: (viewId: string) => number;
+  commitWidth: (viewId: string, px: number) => void;
+}
+
+export function useLeftDock(): LeftDockHandle {
+  const state = useSyncExternalStore(subscribe, snapshot);
+
+  const setEnabled = useCallback((enabled: boolean) => {
+    writeLeftDock({ enabled });
+    publish();
+  }, []);
+
+  const setSide = useCallback((panelId: string, side: PanelSide) => {
+    // The coupling — placing a panel also shows the rail — lives in the store,
+    // so a second caller cannot produce a placement nobody can reach.
+    persistPanelSide(panelId, side);
+    publish();
+  }, []);
+
+  const commitWidth = useCallback((viewId: string, px: number) => {
+    saveLeftDockWidth(viewId, px);
+    publish();
+  }, []);
+
+  return {
+    ...state,
+    setEnabled,
+    setSide,
+    widthOf: resolveLeftDockWidth,
+    commitWidth,
+  };
+}
+
+/**
+ * The dock's width for ONE view.
+ *
+ * Per view because a session list reads at 280px and a plugin's table does not:
+ * a column that snapped to the list's width the moment the user switched views
+ * would be a column with one width that is wrong for every second view.
+ */
+export function useLeftDockWidth(viewId: string): [number, (px: number) => void] {
+  const dock = useLeftDock();
+  const [width, setWidth] = useState(() => dock.widthOf(viewId));
+
+  useEffect(() => {
+    setWidth(dock.widthOf(viewId));
+  }, [viewId, dock]);
+
+  const commitWidth = useCallback(
+    (px: number) => {
+      dock.commitWidth(viewId, px);
+      setWidth(dock.widthOf(viewId));
+    },
+    [dock, viewId],
+  );
+
+  return [width, commitWidth];
+}

package/src/client/hooks/workspace/panel-registry.ts

@@ -123,6 +123,19 @@ export function seedPanelRegistry(payload: PanelRegistryPayload): void {
   adoptPanelRegistry(payload);
 }
 
+/**
+ * Forget the adopted payload — a test seam, and nothing else.
+ *
+ * The store is anchored on `globalThis` (a `bun --hot` reload must not lose it),
+ * which is also why it survives between test files in one `bun test` process: a
+ * suite that adopts a payload with a plugin in it leaves every later suite
+ * drawing that plugin's button. A file that adopts one has to put the store
+ * back.
+ */
+export function resetPanelRegistry(): void {
+  globalThis.__kabmoPanelRegistry = undefined;
+}
+
 /**
  * Re-read the marketplace from disk, bypassing the server's scan cache.
  *

package/src/client/tailwind.css

@@ -182,6 +182,28 @@
   overflow-y: auto;
 }
 
+/* The composer reads at the transcript's own size — 13px — EXCEPT on iOS.
+ *
+ * Every message row in the timeline is `text-[13px] leading-relaxed`, and a
+ * draft written at 16px looked like a different document pasted under the
+ * conversation. The size itself is a utility on the textarea; this rule exists
+ * for the one platform where 13px is not allowed to apply.
+ *
+ * iOS Safari ZOOMS the viewport when a text control below 16px takes focus,
+ * and it does not zoom back out — the page is left wider than the screen with
+ * the composer half off it. So iOS keeps 16px and every other platform reads
+ * at the transcript's size. `-webkit-touch-callout` is the standard
+ * iOS-only probe (it is a Safari-only property), and it cannot be expressed as
+ * a Tailwind variant, which is why this is a class rather than a utility.
+ *
+ * The PLACEHOLDER needs no rule of its own: `::placeholder` inherits
+ * `font-size` from its textarea, so both move together. */
+@supports (-webkit-touch-callout: none) {
+  textarea.composer-type {
+    font-size: 16px;
+  }
+}
+
 /* Reveal-on-hover controls are written `opacity-0 group-hover:opacity-100`
  * (or `hidden group-hover:flex`), and Tailwind v4 emits every one of those
  * variants inside `@media (hover: hover)` — verified in the emitted

package/src/server/db.server.test.ts

@@ -33,7 +33,7 @@ import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import * as path from 'node:path';
 
-import { getDatabasePath, getDb } from '@/server/db.server';
+import { closeDb, getDatabasePath, getDb } from '@/server/db.server';
 import { removeDir } from '@/test-support/remove-dir';
 
 const saved = {
@@ -151,3 +151,54 @@ describe('a failed open is not cached', () => {
     }
   });
 });
+
+describe('closeDb', () => {
+  test('retires an open that is still in flight, and closes its handle', async () => {
+    // The bug this pins, measured on the Release gate: `releaseDb` cleared the
+    // slot while `getDb()` was still opening, so the continuation assigned
+    // `resolved` on the DROPPED slot object. Nothing could reach that handle
+    // again, and on Windows its temp directory stayed locked — `EBUSY … a
+    // handle outlived its test`, reported against the two PRECEDING cases.
+    const savedSlot = globalThis.__kabmoDb;
+    try {
+      Bun.env.KABMO_DB_PATH = path.join(tempRoot(), 'in-flight', 'db.sqlite');
+      globalThis.__kabmoDb = undefined;
+
+      // Start the open and retire the slot in the SAME tick, so the async
+      // continuation is still pending when `closeDb` runs.
+      const pending = getDb();
+      const retired = globalThis.__kabmoDb as { disposed?: boolean } | undefined;
+      closeDb();
+      expect(retired?.disposed).toBe(true);
+
+      // The open settles as a refusal rather than handing back a handle whose
+      // owner is gone, and the slot stays clear for the next caller.
+      await expect(pending).rejects.toThrow(/retired/);
+      expect(globalThis.__kabmoDb ?? null).toBeNull();
+
+      // A later open under a NEW path works, which is what a test isolating
+      // itself between cases needs.
+      Bun.env.KABMO_DB_PATH = path.join(tempRoot(), 'after', 'db.sqlite');
+      const db = await getDb();
+      expect(db).toBeDefined();
+      closeDb();
+    } finally {
+      globalThis.__kabmoDb = savedSlot;
+    }
+  });
+
+  test('closes a resolved handle and clears the slot', async () => {
+    const savedSlot = globalThis.__kabmoDb;
+    try {
+      Bun.env.KABMO_DB_PATH = path.join(tempRoot(), 'resolved', 'db.sqlite');
+      globalThis.__kabmoDb = undefined;
+      const db = await getDb();
+      closeDb();
+      expect(globalThis.__kabmoDb ?? null).toBeNull();
+      // A closed handle refuses further work rather than silently succeeding.
+      expect(() => db.raw.exec('SELECT 1')).toThrow();
+    } finally {
+      globalThis.__kabmoDb = savedSlot;
+    }
+  });
+});