@kabmo-labs/kabmo 0.5.2 → 0.6.0

package/src/client/lib/desktop/bridge.ts

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The desktop shell's bridge, and the reason every other module asks this one
+ * whether it is running inside the shell.
+ *
+ * THREE shells install the same transport, and that is the point of this module:
+ *
+ * - `packages/macos` (macOS, Swift + WKWebView)
+ * - `packages/windows` (.NET + WPF + WebView2)
+ * - `packages/linux` (Rust + GTK 3 + WebKitGTK 4.1)
+ *
+ * Each installs ONE transport before the page's own scripts run:
+ * `window.__kabmoCall(method, params)` posts `{ id, method, params }` to a host
+ * message handler named `kabmo`, and the shell answers by evaluating
+ * `window.__kabmoReply(id, ok, payload)`. There is no capability file and no
+ * per-origin allowance — the shell owns the webview, so the page cannot be
+ * anything but one this window chose to load.
+ *
+ * This module must be safe in a BROWSER too: every function rejects with "not
+ * inside the shell" when there is no bridge, and the navbar draws no server
+ * control at all. A browser tab has no shell to control, and a control that
+ * opened onto "not available" would be a button that never works.
+ */
+
+/** What the shell reports about itself. */
+export interface DesktopInfo {
+  platform: string;
+  shellVersion: string;
+  /** True when the shell hides the native title bar and the page draws it. */
+  overlayTitlebar: boolean;
+  /**
+   * macOS: the width of the traffic lights, which float over the page's LEFT
+   * edge. Absent on a platform whose window controls are not on the left.
+   */
+  trafficLightInset?: string;
+  /**
+   * True when the shell is borderless and has NO controls of its own, so the
+   * page must draw minimise / maximise / close.
+   *
+   * Windows and Linux. macOS gets its traffic lights from the system over a
+   * full-size content view; a borderless Windows window has nothing at all, and
+   * the webview there is an HWND — a WPF element cannot be drawn on top of it
+   * (the airspace problem) — so the page is the only surface that can. Linux
+   * could draw native buttons in a `GtkOverlay` (measured: an overlay child does
+   * receive clicks over a WebView), but the page's set already exists, is tested,
+   * and is the one every other shell's users see.
+   */
+  windowControls?: boolean;
+}
+
+/** One server in the shell's list, or one found on this machine. */
+export interface DesktopServer {
+  id: string;
+  label: string;
+  url: string;
+  kind: 'remote' | 'managed';
+  port?: number;
+  running: boolean;
+  /** This shell started it (as opposed to a server found on the machine). */
+  owned: boolean;
+  version?: string;
+  mode?: string;
+  pid?: number;
+  startedAt?: string;
+  /** `stored` for the list, `record` for a local instance found on disk. */
+  source: 'stored' | 'record';
+}
+
+export interface DesktopServersState {
+  entries: DesktopServer[];
+  /** Local instances this shell did NOT start — a `kabmo serve`, a dev server. */
+  detected: DesktopServer[];
+  activeId?: string;
+  activeUrl?: string;
+}
+
+declare global {
+  interface Window {
+    __kabmoCall?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+    __kabmoDesktop?: DesktopInfo;
+    __kabmoReply?: (id: number, ok: boolean, payload: unknown) => void;
+  }
+}
+
+/** True when this page is inside the desktop shell. */
+export function isDesktopShell(): boolean {
+  return typeof window !== 'undefined' && typeof window.__kabmoCall === 'function';
+}
+
+async function call<T>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+  const invoke = typeof window === 'undefined' ? undefined : window.__kabmoCall;
+  if (!invoke) throw new Error('Not running inside the Kabmo desktop shell.');
+  return (await invoke(method, params)) as T;
+}
+
+export function desktopInfo(): Promise<DesktopInfo | null> {
+  if (!isDesktopShell()) return Promise.resolve(null);
+  const injected = typeof window === 'undefined' ? undefined : window.__kabmoDesktop;
+  // The shell injects this before the page's first script, so the navbar's first
+  // paint is already correct; the command is only a fallback for a shell that
+  // did not (an older build).
+  if (injected) return Promise.resolve(injected);
+  return call<DesktopInfo>('desktop_info');
+}
+
+export function readServers(): Promise<DesktopServersState> {
+  return call<DesktopServersState>('servers_state');
+}
+
+export function addRemoteServer(label: string, url: string): Promise<DesktopServersState> {
+  return call<DesktopServersState>('servers_add', { label, url });
+}
+
+export function removeServer(id: string): Promise<DesktopServersState> {
+  return call<DesktopServersState>('servers_remove', { id });
+}
+
+/** Point the window at a server. The shell navigates, so this page goes away. */
+export function activateServer(id: string): Promise<DesktopServersState> {
+  return call<DesktopServersState>('servers_activate', { id });
+}
+
+/** Start a local server as the shell's child, then navigate to it. */
+export function startLocalServer(port?: number, label?: string): Promise<DesktopServersState> {
+  return call<DesktopServersState>('servers_start', { port: port ?? null, label: label ?? null });
+}
+
+export function stopLocalServer(id: string): Promise<DesktopServersState> {
+  return call<DesktopServersState>('servers_stop', { id });
+}
+
+/**
+ * A refused command's message.
+ *
+ * The shell sends its own sentence (a refused URL, a server that exited), which
+ * is what the UI shows. Nothing is stripped: a message that genuinely starts with
+ * "Error" would lose its first word.
+ */
+export function bridgeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Minimise, maximise/restore and close, for a shell that draws no controls. */
+export function windowMinimize(): Promise<void> {
+  return call<void>('window_minimize');
+}
+
+export function windowToggleMaximize(): Promise<void> {
+  return call<void>('window_maximize');
+}
+
+export function windowClose(): Promise<void> {
+  return call<void>('window_close');
+}

package/src/client/lib/desktop/titlebar.test.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shell's title-bar contract, evaluated against both shells and a browser.
+ *
+ * Two shells wrap this app, and they put their controls on OPPOSITE edges — or
+ * nowhere at all. A single "inset" would have to say which edge it means at
+ * every call site, and the cost of getting it wrong is a dead strip of window
+ * with no control in it, which is exactly the macOS 76px bug stated in
+ * `src/shared/lib/ui/titlebar.ts`.
+ *
+ * Three properties are load-bearing, and each fails silently:
+ *
+ * 1. macOS floats traffic lights over the page's LEFT edge, so the left inset is
+ *    the shell's reported width and nothing is reserved on the right;
+ * 2. Windows is borderless with no controls of its own — its webview is an HWND,
+ *    so a host element cannot be painted over it — which is why the PAGE draws
+ *    the three buttons there (`drawsWindowControls`), and why it reserves no
+ *    inset on either edge;
+ * 3. a BROWSER, or an older shell that injects no identity, gets the caller's
+ *    own resolved padding (the PWA's Window Controls Overlay arithmetic).
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+
+type Shell = {
+  __kabmoCall?: (method: string, params?: Record<string, unknown>) => Promise<unknown>;
+  __kabmoDesktop?: Record<string, unknown>;
+};
+
+const scope = () => globalThis as unknown as { window?: Shell };
+
+async function titlebar() {
+  return import('@/client/lib/desktop/titlebar');
+}
+
+function shell(identity: Record<string, unknown> | null) {
+  scope().window = identity === null
+    ? { __kabmoCall: async () => null }
+    : { __kabmoCall: async () => null, __kabmoDesktop: identity };
+}
+
+const MACOS = { platform: 'macos', shellVersion: '0.1.0', overlayTitlebar: true, trafficLightInset: '5rem' };
+const WINDOWS = { platform: 'windows', shellVersion: '0.1.0', overlayTitlebar: true, windowControls: true };
+
+describe('shell title-bar contract', () => {
+  afterEach(() => {
+    delete scope().window;
+  });
+
+  test('a browser reserves nothing for a shell it is not in', async () => {
+    scope().window = {};
+    const bar = await titlebar();
+    expect(bar.overlayTitlebar()).toBe(false);
+    expect(bar.dragRegionProps()).toEqual({});
+    expect(bar.titlebarInsetLeft('1rem')).toBe('1rem');
+    expect(bar.drawsWindowControls()).toBe(false);
+  });
+
+  test('macOS reserves the traffic lights on the left and draws no controls', async () => {
+    shell(MACOS);
+    const bar = await titlebar();
+    expect(bar.dragRegionProps()).toEqual({ 'data-drag-region': '' });
+    expect(bar.titlebarInsetLeft('1rem')).toBe('5rem');
+    // The system owns the traffic lights: a page-drawn set would be a second one.
+    expect(bar.drawsWindowControls()).toBe(false);
+  });
+
+  test('Windows reserves nothing and draws the three buttons itself', async () => {
+    shell(WINDOWS);
+    const bar = await titlebar();
+    expect(bar.dragRegionProps()).toEqual({ 'data-drag-region': '' });
+    // Nothing floats over the page on a borderless Windows window.
+    expect(bar.titlebarInsetLeft('1rem')).toBe('1rem');
+    expect(bar.drawsWindowControls()).toBe(true);
+  });
+
+  /** An older shell injects no identity at all; nothing may be invented. */
+  test('a shell that reports no identity keeps the resolved padding', async () => {
+    shell(null);
+    const bar = await titlebar();
+    expect(bar.overlayTitlebar()).toBe(true);
+    expect(bar.titlebarInsetLeft('1rem')).toBe('1rem');
+    expect(bar.drawsWindowControls()).toBe(false);
+  });
+
+  /** A shell that draws its own native bar must not mark a drag region. */
+  test('overlayTitlebar false marks no drag region and no controls', async () => {
+    shell({ platform: 'windows', shellVersion: '0.1.0', overlayTitlebar: false, windowControls: true });
+    const bar = await titlebar();
+    expect(bar.overlayTitlebar()).toBe(false);
+    expect(bar.dragRegionProps()).toEqual({});
+    // The native bar owns the buttons when it is visible.
+    expect(bar.drawsWindowControls()).toBe(false);
+  });
+});

package/src/client/lib/desktop/titlebar.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Making the page's own header act as the desktop window's title bar.
+ *
+ * Three facts, and the third is why this module is shared by three shells.
+ *
+ * 1. **The window controls float OVER the content**, because the window is
+ *    built with a transparent title bar over a full-size content view. WHICH
+ *    EDGE they occupy is the platform's choice, and getting it wrong is a dead
+ *    strip of window with no control in it: macOS puts its traffic lights on
+ *    the LEFT, so the leftmost ~76px of the page is behind them and a wordmark
+ *    drawn at the normal 16px inset sits under the close button.
+ *
+ *    - Windows is borderless too, but draws nothing over the page: its webview
+ *      is an HWND, so a host element cannot be painted on top of it. The page
+ *      draws its own minimise / maximise / close instead (`windowControls`), so
+ *      the only edge it reserves anything for is the one macOS owns. Linux is
+ *      the same: borderless, page-drawn controls, no reserved edge.
+ *
+ *    The inset is therefore REPORTED by the shell (`trafficLightInset`), and a
+ *    shell that reports none gets the caller's own resolved padding.
+ *
+ * 2. **The drag region is decided by the SHELL, from a selector** — not by CSS.
+ *    macOS asks the page whether the press landed on `[data-drag-region]`
+ *    (`ShellWindow.sendEvent`); Windows lets WebView2 do the same with
+ *    `IsNonClientRegionSupportEnabled`, which is what makes `app-region: drag`
+ *    mean the title bar there. The page's only job is to MARK its header.
+ *
+ * 3. **The inset must survive a page that has not asked yet.** The shells inject
+ *    their identity before the first script runs, so the first paint is already
+ *    correct; a shell that did not (an older build) leaves this module with no
+ *    identity, and the answer is the caller's own padding rather than a guess.
+ */
+
+import { isDesktopShell } from '@/client/lib/desktop/bridge';
+
+/** Width macOS reserves for its traffic lights, plus the gap after them. */
+export const TRAFFIC_LIGHT_INSET = '5rem';
+
+/** The shell's own report, or null in a browser (and in an older shell). */
+function shellInfo(): { overlayTitlebar: boolean; trafficLightInset?: string; windowControls?: boolean } | null {
+  if (typeof window === 'undefined') return null;
+  const injected = window.__kabmoDesktop;
+  return injected ?? null;
+}
+
+/** True when the shell hid the native title bar and the page draws it. */
+export function overlayTitlebar(): boolean {
+  if (!isDesktopShell()) return false;
+  // The injected identity is authoritative when present: a shell that reports
+  // `overlayTitlebar: false` draws its own native bar and the page must not
+  // reserve anything for controls it does not have.
+  const injected = shellInfo();
+  return injected ? injected.overlayTitlebar : true;
+}
+
+/**
+ * The attribute that marks an element as a window drag handle.
+ *
+ * `data-drag-region` is read by the macOS shell's own hit test. It is an
+ * ATTRIBUTE rather than a class so it cannot be reordered away by a utility
+ * class and does not read as styling.
+ */
+export function dragRegionProps(): Record<string, string> {
+  return overlayTitlebar() ? { 'data-drag-region': '' } : {};
+}
+
+/**
+ * The left inset the first header on the strip must carry.
+ *
+ * macOS: the traffic lights' width — the caller's own padding would be *inside*
+ * them. Windows and Linux: the caller's own padding, because the caption
+ * buttons are on the other edge (or drawn by the page) and reserving here would
+ * leave a hole. Everywhere else it is what the caller already resolved, which is
+ * the PWA's Window Controls Overlay arithmetic (`titlebar-area-x`).
+ */
+export function titlebarInsetLeft(resolved: string): string {
+  if (!overlayTitlebar()) return resolved;
+  return shellInfo()?.trafficLightInset ?? resolved;
+}
+
+/**
+ * True when the page must draw the window's own controls.
+ *
+ * The Windows and Linux shells answer true: both are borderless, and Windows'
+ * webview is an HWND that no host element can be drawn over, so the three
+ * buttons the macOS shell gets from the system have to come from the page there.
+ * Linux COULD draw them (`GtkOverlay` children do receive clicks over a WebView,
+ * measured), but the page's set already exists and is tested.
+ */
+export function drawsWindowControls(): boolean {
+  return overlayTitlebar() && shellInfo()?.windowControls === true;
+}

package/src/client/lib/plugins/slots.test.ts

@@ -19,6 +19,7 @@ import { definePluginApp } from '@kabmo-labs/kabmo-sdk/app';
 import {
   failPluginBundle,
   headerDropdownOf,
+  headerOpensPanelOf,
   headerTriggerOf,
   panelOf,
   pluginSlotState,
@@ -80,6 +81,59 @@ describe('registerPluginBundle', () => {
     expect(headerDropdownOf(slots)).toBeUndefined();
   });
 
+  test('an opensPanel header keeps the slot it opens, and no dropdown', () => {
+    // The navbar resolves this to `plugin:<id>:<slot>` and the layout decides
+    // the COLUMN, so the store has to carry the slot and nothing else.
+    registerPluginBundle('demo', {
+      default: definePluginApp((app) => {
+        app.rightPanel({ id: 'r', component: Noop });
+        app.headerPanel({ id: 'h', component: Noop, opensPanel: 'rightPanel' });
+      }),
+    });
+
+    const slots = pluginSlotState().slots.get('demo')!;
+    expect(headerOpensPanelOf(slots)).toBe('rightPanel');
+    expect(headerDropdownOf(slots)).toBeUndefined();
+  });
+
+  test('a header may not declare both a dropdown and opensPanel', () => {
+    // One click cannot open two things. Refused at registration rather than
+    // drawing a button that silently does one of them.
+    registerPluginBundle('demo', {
+      default: definePluginApp((app) =>
+        app.headerPanel({ id: 'h', component: Noop, opensPanel: 'panel', dropdown: { component: Noop } }),
+      ),
+    });
+
+    const failure = pluginSlotState().failures.find((entry) => entry.pluginId === 'demo');
+    expect(failure?.reason).toContain('both a dropdown and opensPanel');
+    expect(pluginSlotState().slots.has('demo')).toBe(false);
+  });
+
+  test('an opensPanel naming a panel the plugin never registered is refused', () => {
+    // A header that opens a panel this bundle did not contribute is a click
+    // with nothing behind it, so the registration is refused by name.
+    registerPluginBundle('demo', {
+      default: definePluginApp((app) => app.headerPanel({ id: 'h', component: Noop, opensPanel: 'panel' })),
+    });
+
+    const failure = pluginSlotState().failures.find((entry) => entry.pluginId === 'demo');
+    expect(failure?.reason).toContain('names a panel this plugin did not register');
+    expect(pluginSlotState().slots.has('demo')).toBe(false);
+  });
+
+  test('the panel may be registered AFTER the header that opens it', () => {
+    registerPluginBundle('demo', {
+      default: definePluginApp((app) => {
+        app.headerPanel({ id: 'h', component: Noop, opensPanel: 'rightPanel' });
+        app.rightPanel({ id: 'r', component: Noop });
+      }),
+    });
+
+    expect(pluginSlotState().failures).toEqual([]);
+    expect(headerOpensPanelOf(pluginSlotState().slots.get('demo')!)).toBe('rightPanel');
+  });
+
   test('refuses a second registration in the same slot, with the slot named', () => {
     registerPluginBundle('demo', {
       default: definePluginApp((app) => {

package/src/client/lib/plugins/slots.ts

@@ -65,6 +65,17 @@ export interface PluginSlots {
    * dropdown is a static readout rather than a broken button.
    */
   headerDropdown?: unknown;
+  /**
+   * The panel a header trigger OPENS, when it declared `opensPanel`.
+   *
+   * Held here rather than on `components` for the same reason the dropdown is:
+   * it is a property of the header registration, and the surface that draws the
+   * button (the navbar) is not the surface that draws the panel. The host
+   * resolves it to `plugin:<id>:<slot>` at the moment of the click, so the
+   * placement rules (left dock, right column, editor column, phone drawer) all
+   * apply exactly as they do for the activity bar's own button.
+   */
+  headerOpensPanel?: 'rightPanel' | 'panel';
 }
 
 /** One plugin's bundle could not be loaded, or refused to register. */
@@ -119,6 +130,11 @@ export function headerDropdownOf(slots: PluginSlots): ComponentType<HeaderDropdo
   return slots.headerDropdown as ComponentType<HeaderDropdownProps> | undefined;
 }
 
+/** The panel a header trigger opens, when it declared `opensPanel`. */
+export function headerOpensPanelOf(slots: PluginSlots): 'rightPanel' | 'panel' | undefined {
+  return slots.headerOpensPanel;
+}
+
 export function settingsSectionOf(slots: PluginSlots): ComponentType<SettingsSectionProps> | undefined {
   return slots.components.settingsSection as ComponentType<SettingsSectionProps> | undefined;
 }
@@ -142,6 +158,7 @@ export function registerPluginBundle(pluginId: string, module: unknown): void {
   const titles: PluginSlots['titles'] = {};
   const sizing: PluginSlots['sizing'] = {};
   let headerDropdown: unknown;
+  let headerOpensPanel: 'rightPanel' | 'panel' | undefined;
 
   // A bundle re-imported under a new URL (a rebuild) registers AGAIN, and the
   // list slots refuse a duplicate id — so the previous rows go first. Doing it
@@ -171,9 +188,15 @@ export function registerPluginBundle(pluginId: string, module: unknown): void {
       register('rightPanel', component, id, title, { minWidth, defaultFraction }),
     panel: ({ id, title, component, minWidth, defaultFraction }) =>
       register('panel', component, id, title, { minWidth, defaultFraction }),
-    headerPanel: ({ id, title, component, dropdown }) => {
+    headerPanel: ({ id, title, component, dropdown, opensPanel }) => {
       register('headerPanel', component, id, title);
+      if (dropdown && opensPanel) {
+        throw new Error(
+          `headerPanel "${id}" declares both a dropdown and opensPanel — a trigger has one click, so it can open one of them`,
+        );
+      }
       if (dropdown) headerDropdown = dropdown.component;
+      if (opensPanel) headerOpensPanel = opensPanel;
     },
     settingsSection: ({ id, title, component }) => register('settingsSection', component, id, title),
     // The list slots: each is a keyed registration that RETURNS its own
@@ -205,6 +228,18 @@ export function registerPluginBundle(pluginId: string, module: unknown): void {
     return;
   }
 
+  // Checked AFTER `setup`, because a plugin may register the header before the
+  // panel it names. A button that opens a panel this bundle never contributed
+  // is a click with nothing behind it, so it is refused by name rather than
+  // drawn.
+  if (headerOpensPanel && !components[headerOpensPanel]) {
+    failPluginBundle(
+      pluginId,
+      `headerPanel opensPanel "${headerOpensPanel}" names a panel this plugin did not register`,
+    );
+    return;
+  }
+
   const slots = new Map(state.slots);
   slots.set(pluginId, {
     pluginId,
@@ -212,6 +247,7 @@ export function registerPluginBundle(pluginId: string, module: unknown): void {
     titles,
     sizing,
     ...(headerDropdown ? { headerDropdown } : {}),
+    ...(headerOpensPanel ? { headerOpensPanel } : {}),
   });
   publish({ slots, failures: state.failures.filter((entry) => entry.pluginId !== pluginId) });
 }

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

@@ -168,7 +168,7 @@ describe('closeDb', () => {
       // continuation is still pending when `closeDb` runs.
       const pending = getDb();
       const retired = globalThis.__kabmoDb as { disposed?: boolean } | undefined;
-      closeDb();
+      await closeDb();
       expect(retired?.disposed).toBe(true);
 
       // The open settles as a refusal rather than handing back a handle whose
@@ -181,7 +181,7 @@ describe('closeDb', () => {
       Bun.env.KABMO_DB_PATH = path.join(tempRoot(), 'after', 'db.sqlite');
       const db = await getDb();
       expect(db).toBeDefined();
-      closeDb();
+      await closeDb();
     } finally {
       globalThis.__kabmoDb = savedSlot;
     }
@@ -193,7 +193,7 @@ describe('closeDb', () => {
       Bun.env.KABMO_DB_PATH = path.join(tempRoot(), 'resolved', 'db.sqlite');
       globalThis.__kabmoDb = undefined;
       const db = await getDb();
-      closeDb();
+      await closeDb();
       expect(globalThis.__kabmoDb ?? null).toBeNull();
       // A closed handle refuses further work rather than silently succeeding.
       expect(() => db.raw.exec('SELECT 1')).toThrow();
@@ -201,4 +201,45 @@ describe('closeDb', () => {
       globalThis.__kabmoDb = savedSlot;
     }
   });
+
+  test('the returned promise settles only once the in-flight handle is closed', async () => {
+    // The bug this pins is a RACE, and it is the one the Release gate hit:
+    // retiring the slot is synchronous, but an open already in flight still
+    // reaches `createDb` and OPENS a file. A caller that deleted the temp
+    // directory on the strength of a synchronous return raced a handle that did
+    // not exist yet — and could never win, because `removeDir` retries with
+    // `Bun.sleepSync`, which blocks the very continuation that closes it.
+    //
+    // Asserted on the observable the caller needs: after `await closeDb()`, no
+    // handle is open and none is about to be. A database file that was opened
+    // and closed again reports no further work through it, and the slot is
+    // clear, so the next open uses whatever path is configured by then.
+    const savedSlot = globalThis.__kabmoDb;
+    try {
+      const dir = tempRoot();
+      Bun.env.KABMO_DB_PATH = path.join(dir, 'settle', 'db.sqlite');
+      globalThis.__kabmoDb = undefined;
+
+      const pending = getDb();
+      const retiring = closeDb();
+
+      // A synchronous return is the bug, not a detail: it is what let a caller
+      // delete the directory while the open was still about to create a file.
+      expect(retiring).toBeInstanceOf(Promise);
+
+      // Both settle, and the retirement is what decides when the caller may
+      // touch the directory — so it must not resolve before the open has been
+      // closed. The open's own rejection is expected and is not an error.
+      await expect(pending).rejects.toThrow(/retired/);
+      await expect(retiring).resolves.toBeUndefined();
+      expect(globalThis.__kabmoDb ?? null).toBeNull();
+
+      // The proof the caller needs: the directory can be removed the moment the
+      // promise settles, with no retry window spent.
+      removeDir(dir);
+      expect(existsSync(dir)).toBe(false);
+    } finally {
+      globalThis.__kabmoDb = savedSlot;
+    }
+  });
 });

package/src/server/db.server.ts

@@ -73,11 +73,25 @@ function slot(): DbSlot {
  * a lifecycle one: a handle must never outlive the configuration it was opened
  * under. An in-flight open is marked `disposed` rather than awaited, and the
  * continuation closes its own handle — see {@link DbSlot.disposed}.
+ *
+ * **The returned promise is the contract, and it is not decoration.** Marking
+ * the slot `disposed` does not stop an open that is already running: the
+ * continuation still reaches `createDb`, which OPENS a file. A caller that
+ * deleted the temp directory on the strength of a synchronous return therefore
+ * raced a handle that did not exist yet — measured on the Release gate, where
+ * `releaseDb` failed with `EBUSY … a handle outlived its test` after burning
+ * the whole retry window, and the continuation's own rejection surfaced as
+ * "Unhandled error between tests". The retry could not win, and the reason is
+ * worth stating: `removeDir` spins with `Bun.sleepSync`, which BLOCKS the event
+ * loop, so the very continuation that would close the handle could never
+ * progress while the delete was being retried.
+ *
+ * Awaiting this promise means "no handle is open, and none is about to be".
  */
-export function closeDb(): void {
+export function closeDb(): Promise<void> {
   const state = globalThis.__kabmoDb;
   globalThis.__kabmoDb = undefined;
-  if (!state) return;
+  if (!state) return Promise.resolve();
   state.disposed = true;
   try {
     state.resolved?.raw.close();
@@ -85,7 +99,17 @@ export function closeDb(): void {
     // Already closed by a failed open; the slot is gone either way.
   }
   state.resolved = null;
+  const pending = state.promise;
   state.promise = null;
+  // Swallowed deliberately: the caller is RETIRING this handle, so the
+  // continuation's "retired before it finished" rejection is the expected
+  // outcome rather than an error. Letting it escape here would resurrect the
+  // unhandled-rejection noise this await exists to remove.
+  return pending ? pending.then(noop, noop) : Promise.resolve();
+}
+
+function noop(): void {
+  // See `closeDb`: the settlement is the signal, not the value.
 }
 
 export async function getDatabasePath(): Promise<string> {

package/src/server/lib/bundler/build-errors.test.ts

@@ -66,12 +66,6 @@ describe('describeShellBuildFailure', () => {
     expect(await describeShellBuildFailure(root)).toBeNull();
   });
 
-  test('returns null when there is no shell entrypoint to build', async () => {
-    rmSync(join(root, 'index.html'));
-
-    expect(await describeShellBuildFailure(root)).toBeNull();
-  });
-
   test('loads the plugins named in bunfig.toml, as the route does', async () => {
     // A plugin that fails a file the route would bundle: if the probe ignored
     // bunfig it would report a clean build and hide the real failure.