@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/client/hooks/workspace/file-tabs.ts

@@ -52,24 +52,37 @@ export function useFileTabs(
     [sessionId],
   );
 
-  const activeRootRef = useRef<string | null | undefined>(undefined);
+  /** The last root a wipe was performed FOR; `null` until one is known. */
+  const wipedRootRef = useRef<string | null>(null);
   const { ready: layoutReady } = useSessionStateContext();
-  const wipedRootRef = useRef<string | null | undefined>(undefined);
 
   useEffect(() => {
-    if (activeRootRef.current === activeProjectPath) return;
-    activeRootRef.current = activeProjectPath;
-    if (!layoutReady || wipedRootRef.current === activeProjectPath) return;
+    // Only a CHANGE from one known root to another closes the previous
+    // workspace's tabs.
+    //
+    // Two rules, and each was a bug first. A root that is not known yet is not a
+    // root that changed: the path is derived from the sidebar's folder list,
+    // which is empty for a beat on every load (and again whenever the structure
+    // topic re-subscribes), so treating `null` as a root wiped the tabs a user
+    // had just opened. And the FIRST known root is not a change either — it is
+    // the workspace the page was already showing, so wiping on it discarded the
+    // tabs the session blob had just restored (measured: the e2e specs had to
+    // gate every tree click on the `/state` response to survive it, and a click
+    // that lost that race left the editor reading "Select a file to open" over
+    // the file the user had opened).
+    if (!activeProjectPath || !layoutReady) return;
+    const previous = wipedRootRef.current;
     wipedRootRef.current = activeProjectPath;
+    if (previous === null || previous === activeProjectPath) return;
     // The tabs are dropped, but their scroll offsets deliberately are NOT: this
-    // wipe is not a user closing a tab. It fires on every load (the root is null
-    // until the folder resolves), so dropping here erased the offset the session
-    // blob had just restored — measured: the offset persisted as `900`, and came
-    // back as `{}` after a reload. The entry is keyed by the file's path hash, so
-    // it is reused when that file is opened again, which is the point.
+    // wipe is not a user closing a tab. Dropping here erased the offset the
+    // session blob had just restored — measured: the offset persisted as `900`,
+    // and came back as `{}` after a reload. The entry is keyed by the file's
+    // path hash, so it is reused when that file is opened again, which is the
+    // point.
     setOpenedFiles([]);
     setActiveFileId(null);
-  }, [activeProjectPath, sessionId, layoutReady, setOpenedFiles, setActiveFileId]);
+  }, [activeProjectPath, layoutReady, setOpenedFiles, setActiveFileId]);
 
   const handleOpenFile = useCallback((file: OpenFileInput) => {
     const fileEntry: OpenedFile = {

package/src/client/hooks/workspace/navbar-session-actions.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The navbar's session menu, resolved from the session ON SCREEN.
+ *
+ * A hook rather than three statements in the layout because the lookup has a
+ * rule of its own: the session's row may live in a folder that is not expanded
+ * in the sidebar (or not visible at all), so it is found by id across every
+ * folder instead of by walking the visible list. No row means no menu — a
+ * session the sidebar does not know (a chat running outside every registered
+ * workspace) gets nothing rather than dead items.
+ *
+ * The pending `new-…` refusal lives here too: such a chat has no transcript
+ * anywhere yet, so the server refuses rename and delete, and the menu hides
+ * them the way the sidebar does.
+ */
+
+import { useMemo } from 'preact/hooks';
+import { useSidebarData } from '@/client/hooks/chat/omp/session-list';
+import { useSessionActions } from '@/client/hooks/workspace/session-actions';
+import { useSessionDelete, type SessionDeleteActions } from '@/client/hooks/workspace/session-delete';
+import type { WorkspaceFolderData } from '@/shared/types';
+
+/** What `TopNavbar` needs to draw its title menu. */
+export interface NavbarSessionMenu {
+  isArchived: boolean;
+  onRename?: (name: string) => void;
+  onRenameWithAi?: () => void;
+  onArchive: () => void;
+  onDelete?: () => void;
+}
+
+export interface NavbarSessionActions {
+  menu: NavbarSessionMenu | undefined;
+  /** The delete confirmation's own state machine, which the layout renders. */
+  sessionDelete: SessionDeleteActions;
+}
+
+export function useNavbarSessionActions(
+  folders: WorkspaceFolderData[],
+  sessionId: string | null,
+  report: (message: string, tone?: 'success' | 'error') => void,
+): NavbarSessionActions {
+  const sidebar = useSidebarData();
+  const actions = useSessionActions(sidebar.refresh, report);
+  const sessionDelete = useSessionDelete();
+
+  const activeSession = useMemo(() => {
+    if (!sessionId) return null;
+    for (const folder of folders) {
+      const found = (folder.sessions || []).find((s) => String(s.id) === String(sessionId));
+      if (found) return found;
+    }
+    return null;
+  }, [folders, sessionId]);
+
+  const pending = Boolean(sessionId && sessionId.startsWith('new-'));
+  const menu: NavbarSessionMenu | undefined = activeSession
+    ? {
+        isArchived: activeSession.is_archived === 1,
+        onRename: pending ? undefined : (name: string) => void actions.handleRename(activeSession, name),
+        onRenameWithAi: pending ? undefined : () => void actions.handleRenameWithAi(activeSession),
+        onArchive: () => actions.handleArchive(activeSession),
+        onDelete: pending ? undefined : () => sessionDelete.requestDelete(activeSession),
+      }
+    : undefined;
+
+  return { menu, sessionDelete };
+}

package/src/client/hooks/workspace/worktree/index.ts

@@ -58,7 +58,7 @@ async function readFailure(response: Response): Promise<never> {
 export function useWorktrees(scope: WorktreeRequestScope, enabled: boolean) {
   const [payload, setPayload] = useState<WorktreeListPayload | null>(null);
   const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+  const [failure, setFailure] = useState<WorktreeFailure | null>(null);
 
   const refresh = useCallback(async () => {
     if (!enabled) return;
@@ -67,11 +67,18 @@ export function useWorktrees(scope: WorktreeRequestScope, enabled: boolean) {
       const response = await fetch(`/api/worktrees${queryFor(scope)}`);
       if (!response.ok) await readFailure(response);
       setPayload((await response.json()) as WorktreeListPayload);
-      setError(null);
+      setFailure(null);
     } catch (cause) {
       // Kept apart from the payload: an empty list and a failed read are
-      // different answers, and only one of them means nothing is there.
-      setError(cause instanceof Error ? cause.message : String(cause));
+      // different answers, and only one of them means nothing is there. The
+      // CODE travels too, because "this folder is not a repository" and "git
+      // could not answer" are different states to draw — and the first one is
+      // how a caller knows to offer no worktree control at all.
+      setFailure(
+        cause instanceof WorktreeRequestError
+          ? cause.failure
+          : { code: 'create_failed', message: cause instanceof Error ? cause.message : String(cause) },
+      );
     } finally {
       setLoading(false);
     }
@@ -84,10 +91,18 @@ export function useWorktrees(scope: WorktreeRequestScope, enabled: boolean) {
   return {
     payload,
     worktrees: payload?.worktrees ?? ([] as WorktreeInfo[]),
+    /**
+     * Whether the project is a git repository at all. `null` while it is still
+     * unknown: a caller that draws a worktree control must wait for the answer
+     * rather than offer one a plain folder can never satisfy.
+     */
+    isRepo: payload ? payload.isRepo : null,
     /** The resolved parent directory a create would use. */
     base: payload?.base ?? '',
     loading,
-    error,
+    failure,
+    /** The failure's message, for the surfaces that only print one. */
+    error: failure?.message ?? null,
     refresh,
   };
 }

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

@@ -30,6 +30,14 @@
 export interface DesktopInfo {
   platform: string;
   shellVersion: string;
+  /**
+   * The machine's architecture, in the canonical vocabulary (`arm64` / `x64`).
+   *
+   * Every desktop artifact is per-architecture, so without this the console can
+   * only offer the release page. Absent on a shell too old to report it, which
+   * degrades the offer to that page rather than breaking it.
+   */
+  arch?: string;
   /** True when the shell hides the native title bar and the page draws it. */
   overlayTitlebar: boolean;
   /**
@@ -156,3 +164,40 @@ export function windowToggleMaximize(): Promise<void> {
 export function windowClose(): Promise<void> {
   return call<void>('window_close');
 }
+
+/**
+ * What the shell did with an update it was handed.
+ *
+ * The shell owns the whole run — download, verify, replace, relaunch — because
+ * only it can do any of those things: a page cannot replace the executable it is
+ * running inside, and a page's "download" leaves a file in a folder the user has
+ * to find. This is the report it sends back.
+ *
+ * `relaunching` is the honest terminal state on success: the shell is about to
+ * quit, so a caller that keeps a spinner going is describing a page that is
+ * already gone.
+ */
+export interface ShellUpdateOutcome {
+  success: boolean;
+  /** The version the shell installed, when it could read one. */
+  version?: string | null;
+  /** A sentence for the user — the shell's own, never a generic failure. */
+  message: string;
+  relaunching?: boolean;
+}
+
+/**
+ * Ask the shell to install the build it just offered.
+ *
+ * `url` and `version` are the console's answer, passed through rather than
+ * re-derived: the shell has no release list of its own, and asking it to fetch
+ * one would be a second reader of the same GitHub endpoint.
+ *
+ * The shell VERIFIES the bytes before installing them (the platform's own check —
+ * a code signature, an archive shape, a version floor). A console that is
+ * compromised can therefore make the shell download, but not make it run
+ * something the platform will not vouch for.
+ */
+export function applyShellUpdate(url: string, version: string): Promise<ShellUpdateOutcome> {
+  return call<ShellUpdateOutcome>('update_apply', { url, version });
+}

package/src/client/lib/search-reveal.ts

@@ -23,7 +23,7 @@
  * editor can decide by equality whether the request is for the file it holds.
  */
 
-import type { FindOptions } from '@/shared/lib/code/editor/find';
+import type { FindOptions } from '@/shared/lib/code/editor/find-scan';
 
 export interface SearchRevealRequest {
   /** Workspace-relative path of the file the match lives in. */

package/src/client/main.tsx

@@ -1,6 +1,7 @@
 import { hydrate } from 'preact';
 import { App } from '@/client/App';
 import { bootSyntax } from '@/shared/lib/code/highlighter';
+import { warmSyntaxTokenizers } from '@/shared/lib/code/highlighter-warmup';
 import { primeKabmoSettings } from '@/shared/lib/settings/client';
 import { initDocumentTheme } from '@/client/hooks/ui/theme';
 import { primeWindowChrome } from '@/client/hooks/ui/window-chrome';
@@ -70,7 +71,10 @@ installFileLaunchHandler((result) => {
 });
 
 // Fire-and-forget: warms the Shiki highlighter in parallel with hydration.
-bootSyntax();
+// Once the eager grammars land, each is tokenized once on a tiny sample during
+// idle time — loading a grammar is not compiling it, and the compile used to be
+// paid inside the first tool card the reader expanded.
+void bootSyntax().then(() => warmSyntaxTokenizers());
 
 if (root) {
   hydrate(

package/src/client/tailwind.css

@@ -384,6 +384,43 @@
 .shiki span { color: var(--shiki-light); }
 html[data-theme-variant="dark"] .shiki span { color: var(--shiki-dark); }
 
+/* No per-token underline in a diff.
+ *
+ * `@codemirror/merge` wraps the characters that changed in `.cm-changedText`
+ * (and a deleted chunk's in `.cm-deletedText`) and its BASE THEME paints a 2px
+ * gradient along the bottom of each fragment. A word-level change is usually
+ * several fragments — `2` → `22` is one — so the reader got a run of short
+ * coloured bars under the code that reads as a second, broken baseline rather
+ * than as emphasis. The row's own band and the gutter marker already say which
+ * side a row belongs to.
+ *
+ * Three facts about how this has to be written, each measured:
+ *
+ * 1. **It cannot be suppressed from the panel's own `EditorView.theme`.** That
+ *    theme rejects the `&light`/`&dark` selectors the package's rules are spelled
+ *    with (`RangeError: Unsupported selector: &light`, which took the whole
+ *    merge view down and left an empty host).
+ * 2. **A plain `.cm-changedText { background: none }` LOSES.** The package's rule
+ *    is `.ͼ2.cm-merge-b .cm-changedText` — two classes on the root plus one on the
+ *    span, i.e. specificity (0,3,0) — and CodeMirror mounts its style modules
+ *    after this sheet, so document order is against us as well.
+ * 3. **So the selector carries three class-level parts of its own** (`.cm-editor`
+ *    + `.cm-merge-b`/`.cm-merge-a` + the span class), which wins on specificity
+ *    rather than by `!important` — an `!important` here would also beat a
+ *    future theme that legitimately wants a different treatment, and this is a
+ *    cosmetic suppression, not a hard override.
+ *
+ * `diff-panel.e2e.ts` asserts the computed `background-image` on a real changed
+ * token, so a package bump that reintroduces the bar fails there rather than in
+ * a screenshot review. */
+.cm-editor.cm-merge-a .cm-changedText,
+.cm-editor.cm-merge-b .cm-changedText,
+.cm-editor.cm-merge-a .cm-deletedChunk .cm-deletedText,
+.cm-editor.cm-merge-b .cm-deletedChunk .cm-deletedText,
+.cm-editor .cm-deletedChunk .cm-deletedText {
+  background: none;
+}
+
 /* Find matches, painted inside the token spans the highlighter emits. An
  * inline <mark> colours a background without moving a glyph, which is what
  * keeps the transparent <textarea> above aligned with this layer — a block or
@@ -400,14 +437,6 @@ html[data-theme-variant="dark"] .shiki span { color: var(--shiki-dark); }
   color: inherit;
   background: color-mix(in srgb, var(--theme-warning) 32%, transparent);
 }
-/* An extra ⌘D selection: same geometry as a find match, different ink. The
- * caret can only live in the primary range, so the two must not look alike —
- * the user has to see where their keystrokes will land. */
-.shiki .find-match[data-occurrence] {
-  background: color-mix(in srgb, var(--theme-info) 30%, transparent);
-  border-top: 1px solid color-mix(in srgb, var(--theme-info) 55%, transparent);
-  border-bottom: 1px solid color-mix(in srgb, var(--theme-info) 55%, transparent);
-}
 .shiki .find-match[data-find-current] {
   background: color-mix(in srgb, var(--theme-warning) 55%, transparent);
   border-top: 1px solid color-mix(in srgb, var(--theme-warning) 75%, transparent);

package/src/server/lib/auth/guard.test.ts

@@ -30,6 +30,18 @@ describe('public paths', () => {
     expect(isPublicPath('/login')).toBe(true);
   });
 
+  /**
+   * The two shells ask their update check from native code, which has no
+   * session cookie — and the button is for a shell so stale it may not be able
+   * to load the console at all. Gating these answered `401` to every shell on a
+   * password-protected console, which the settings screen could only report as
+   * "Could not ask the server" (measured against a real install).
+   */
+  test('the native shells can ask what is published without a session', () => {
+    expect(isPublicPath('/api/updates/android')).toBe(true);
+    expect(isPublicPath('/api/updates/ios')).toBe(true);
+  });
+
   test('the assets the login screen is built from are public', () => {
     for (const path of [
       '/_dev-assets/client/index-abc.js',
@@ -153,6 +165,22 @@ describe('authentication is per run, never inherited from disk', () => {
     expect(response?.status).toBe(401);
   });
 
+  /**
+   * The bug this pins: both shells ask their update check from NATIVE code,
+   * which carries no cookie, so a password-protected console answered `401` and
+   * the settings screen could only say "Could not ask the server" (measured on a
+   * real install). The desktop route stays gated because the CONSOLE asks it,
+   * and the console is behind the login.
+   */
+  test('a password does not gate the native shells\u2019 update check', async () => {
+    useTempDataDir();
+    await initAuth('correct-horse');
+
+    expect(authGate(new Request('http://localhost/api/updates/android'))).toBeUndefined();
+    expect(authGate(new Request('http://localhost/api/updates/ios'))).toBeUndefined();
+    expect(authGate(new Request('http://localhost/api/updates/desktop?kind=macos'))?.status).toBe(401);
+  });
+
   test('a document request is redirected to the login screen, not answered 401', async () => {
     useTempDataDir();
     await initAuth('correct-horse');

package/src/server/lib/auth/guard.ts

@@ -41,6 +41,16 @@ const LOGIN_PATH = '/login';
 /** Paths that never require a session, because they ARE the way in. */
 const PUBLIC_EXACT = new Set([
   '/api/health',
+  // The native shells' own update check. Android and iOS ask these from
+  // NATIVE code (`AppUpdateCheck.kt`, `SettingsViewController.fetchRelease`),
+  // which carries no WebView cookie — and the button exists precisely for a
+  // shell too stale to load the console, so it cannot depend on a session
+  // either. Both answer GitHub's public release list (a version and a download
+  // URL), which is the same data an unauthenticated browser can read from
+  // github.com; `/api/updates/desktop` stays gated because only the CONSOLE
+  // asks it, and the console is behind the login.
+  '/api/updates/android',
+  '/api/updates/ios',
   '/api/auth/state',
   '/api/auth/login',
   '/api/auth/logout',

package/src/server/lib/fs/worktree/create.ts

@@ -45,7 +45,7 @@ import {
   resolveConfiguredWorktreeRoot,
   resolveTargetDirectory,
 } from '@/server/lib/fs/worktree/location';
-import { findBranchInUse, refExists } from '@/server/lib/fs/worktree/list';
+import { findBranchInUse, isWorkTree, refExists } from '@/server/lib/fs/worktree/list';
 import { resolveProjectId } from '@/server/lib/fs/worktree/project-id';
 
 /**
@@ -113,8 +113,7 @@ export async function planWorktree(
   deps: Pick<CreateWorktreeDeps, 'identityFor' | 'dataDir' | 'configuredDirectory'>,
 ): Promise<{ primaryRoot: string; projectId: string; root: string; name: string; directory: string; branch: string; startRef: string }> {
   const projectPath = path.resolve(input.projectPath);
-  const insideWorkTree = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd: projectPath });
-  if (insideWorkTree.exitCode !== 0 || insideWorkTree.stdout.trim() !== 'true') {
+  if (!(await isWorkTree(projectPath))) {
     throw new WorktreeError('not_a_repo', 'This folder is not a Git repository.');
   }
 

package/src/server/lib/fs/worktree/list.ts

@@ -116,6 +116,19 @@ export async function listWorktrees(cwd: string): Promise<WorktreeEntry[]> {
   return entries;
 }
 
+/**
+ * Whether `cwd` is inside a work tree at all.
+ *
+ * The check a plain directory fails, and the one every caller here needs before
+ * it may talk about worktrees: `git worktree list` in a non-repository exits
+ * non-zero, so without this a notes folder bound as a workspace reads as a
+ * BROKEN repository rather than as one that has none.
+ */
+export async function isWorkTree(cwd: string): Promise<boolean> {
+  const probe = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd });
+  return probe.exitCode === 0 && probe.stdout.trim() === 'true';
+}
+
 /** Whether `branch` is checked out in any worktree of this repository, and where. */
 export async function findBranchInUse(cwd: string, branch: string): Promise<{ path: string } | null> {
   const entries = await listWorktrees(cwd);

package/src/server/lib/fs/worktree/remove.ts

@@ -23,7 +23,7 @@ import { canonicalPath, pathHolds } from '@/server/lib/fs/canonical';
 import { runGit } from '@/server/lib/fs/git-run';
 import { resolveProjectRoot } from '@/server/lib/omp/core/worktree';
 import { WorktreeError } from '@/server/lib/fs/worktree/errors';
-import { listWorktrees } from '@/server/lib/fs/worktree/list';
+import { isWorkTree, listWorktrees } from '@/server/lib/fs/worktree/list';
 
 /** Changed + untracked count in `directory`; 0 when git cannot answer. */
 export async function dirtyCount(directory: string): Promise<number> {
@@ -85,8 +85,8 @@ export async function removeWorktree(
   const requested = path.resolve(input.worktreePath);
   const insideManagedRoot = input.managedRoot ? await pathHolds(input.managedRoot, requested) : false;
 
-  const insideWorkTree = await runGit(['rev-parse', '--is-inside-work-tree'], { cwd: input.projectPath });
-  if (insideWorkTree.exitCode !== 0 || insideWorkTree.stdout.trim() !== 'true') {
+  const insideWorkTree = await isWorkTree(input.projectPath);
+  if (!insideWorkTree) {
     throw new WorktreeError('not_a_repo', 'This folder is not a Git repository.');
   }
 

package/src/server/lib/lifecycle/claim-port.test.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `claimPort` — the bind decision, and its whole value is in the failure path:
+ * a starter that loses must fail with a message that names the real situation
+ * instead of a bare `EADDRINUSE`.
+ *
+ * The cases drive real listeners on OS-assigned ports, because the question is
+ * about sockets. One of them is the reported bug: `localhost` stands for two
+ * addresses, the guard asked about only the one Bun would bind, and a stale
+ * instance kept the other — two servers on one port, and a browser landing on
+ * whichever family it resolved.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { testPosix } from '@/test-support/platform';
+
+import { claimPort, PortInUseError } from '@/server/lib/lifecycle/port-guard';
+import { createLoopbackHarness, ipv6Loopback, realFetch } from '@/test-support/loopback';
+
+const harness = createLoopbackHarness();
+const { occupy, occupyAt, freePort, freePortBothFamilies, livePid, spawnChamberHolder } = harness;
+
+let tempDir: string;
+let originalDataDir: string | undefined;
+
+beforeEach(() => {
+  // The instance record and the port lock both live under the data directory;
+  // pointing it at a temp dir keeps a test from reading (or writing) the real
+  // `~/.kabmo/run`.
+  originalDataDir = Bun.env.KABMO_DATA_DIR;
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'kabmo-test-claim-port-'));
+  Bun.env.KABMO_DATA_DIR = tempDir;
+  globalThis.fetch = realFetch;
+});
+
+afterEach(async () => {
+  await harness.dispose();
+  if (originalDataDir === undefined) delete Bun.env.KABMO_DATA_DIR;
+  else Bun.env.KABMO_DATA_DIR = originalDataDir;
+  fs.rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('claimPort', () => {
+  test('binds a free port through the injected listen', async () => {
+    const port = await freePort();
+    let binds = 0;
+
+    await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } });
+
+    expect(binds).toBe(1);
+  });
+
+  test('re-binds when the occupant is this very process', async () => {
+    // `bun run --hot` re-evaluates the entry inside the running process, so the
+    // port is held by us and Bun swaps the handler on the next listen. Killing
+    // the dev loop on every save is the failure this prevents.
+    const { port } = occupy(() => Response.json({ service: 'kabmo', pid: process.pid }));
+    let binds = 0;
+
+    await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } });
+
+    expect(binds).toBe(1);
+  });
+
+  testPosix('names a Kabmo occupant held by another process', async () => {
+    const holder = await spawnChamberHolder();
+    const { port } = occupy(() => Response.json({ service: 'kabmo', pid: holder.pid, version: '9.9.9' }));
+    let binds = 0;
+
+    const error = await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } })
+      .then(() => null, (thrown: unknown) => thrown);
+
+    expect(error).toBeInstanceOf(PortInUseError);
+    const message = (error as Error).message;
+    expect(message).toContain(`Port ${port} is already served by Kabmo`);
+    expect(message).toContain(`pid ${holder.pid}`);
+    expect(message).toContain('v9.9.9');
+    expect(message).toContain('Nothing was stopped');
+    // A starting instance never binds over an identified one.
+    expect(binds).toBe(0);
+  });
+
+  test('names a foreign listener as not Kabmo, without a bind error', async () => {
+    // Nothing answers `/api/health` and nothing identifies itself, so the probe
+    // fails first and `listen` is never attempted.
+    const { port } = occupy(() => new Response('not kabmo'));
+    let binds = 0;
+
+    const error = await claimPort({ port, host: '127.0.0.1', listen: async () => { binds += 1; } })
+      .then(() => null, (thrown: unknown) => thrown);
+
+    expect(error).toBeInstanceOf(PortInUseError);
+    const message = (error as Error).message;
+    expect(message).toContain(`Port ${port} is in use by another process`);
+    expect(message).toContain(`lsof -nP -iTCP:${port} -sTCP:LISTEN`);
+    expect(message).not.toContain('Bind error');
+    expect(binds).toBe(0);
+  });
+
+  test.skipIf(!ipv6Loopback)('refuses a name whose OTHER address is held', async () => {
+    // The reported bug: a stale instance held `127.0.0.1:3000`, `bun run dev`
+    // probed only `localhost`'s other family (`::1`), found it free, and bound
+    // it. Two servers, one port, and a browser landing on whichever family it
+    // resolved — the stale one, serving a different data mode.
+    const port = await freePortBothFamilies();
+    // A listener reporting OUR pid is read as this process re-binding, so the
+    // occupant has to name another live process to be refused.
+    const holder = await livePid();
+    const held = occupyAt(port, '127.0.0.1', () => Response.json({ service: 'kabmo', pid: holder }));
+    let binds = 0;
+
+    const error = await claimPort({ port, host: 'localhost', listen: async () => { binds += 1; } })
+      .then(() => null, (thrown: unknown) => thrown);
+
+    expect(error).toBeInstanceOf(PortInUseError);
+    const message = (error as Error).message;
+    expect(message).toContain(`Port ${port} is already served by Kabmo`);
+    // The address clause is the actionable half: `lsof` lists both sockets, so
+    // a bare "port busy" does not say which one has to be freed.
+    expect(message).toContain('on 127.0.0.1');
+    expect(binds).toBe(0);
+
+    held.stop(true);
+  });
+
+  test.skipIf(!ipv6Loopback)('binds a name whose addresses are both free', async () => {
+    const port = await freePortBothFamilies();
+    let binds = 0;
+
+    await claimPort({ port, host: 'localhost', listen: async () => { binds += 1; } });
+
+    expect(binds).toBe(1);
+  });
+
+  test('carries the bind error when the port looked free', async () => {
+    // The probe is only a short-circuit; when `listen` fails anyway, the real
+    // reason must survive into the error rather than being replaced by a guess.
+    const port = await freePort();
+
+    const error = await claimPort({
+      port,
+      host: '127.0.0.1',
+      listen: async () => { throw new Error('EADDRINUSE: address already in use'); },
+    }).then(() => null, (thrown: unknown) => thrown);
+
+    expect(error).toBeInstanceOf(PortInUseError);
+    expect((error as Error).message).toContain('Bind error: EADDRINUSE: address already in use');
+  });
+});