botholomew 0.18.5 → 0.18.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.18.5",
+  "version": "0.18.7",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.95.2",
-    "@evantahler/mcpx": "0.21.7",
+    "@evantahler/mcpx": "0.21.8",
     "ansis": "^4.3.0",
     "commander": "^14.0.0",
     "gray-matter": "^4.0.3",
@@ -36,7 +36,7 @@
     "ink-spinner": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "istextorbinary": "^9.5.0",
-    "membot": "^0.15.0",
+    "membot": "^0.15.4",
     "nanospinner": "^1.2.2",
     "react": "^19.2.6",
     "uuid": "^14.0.0",

package/src/tools/mcp/exec.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formatCallToolResult } from "../../mcpx/client.ts";
 import { fakeMcpExec, isCaptureMode } from "../../worker/fake-mcp.ts";
-import type { ToolDefinition } from "../tool.ts";
+import { getTool, type ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
   server: z.string().describe("MCP server name"),
@@ -82,6 +82,18 @@ export const mcpExecTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
+    // Guard: the agent sometimes routes a top-level Botholomew tool through
+    // mcp_exec (e.g. read_large_result on a payload that originated from an
+    // MCP server). Bounce with a clear redirect rather than forwarding to a
+    // server that doesn't have the tool.
+    if (getTool(input.tool)) {
+      return {
+        result: `\`${input.tool}\` is a top-level Botholomew tool, not an MCP tool. Call it directly by name instead of routing it through mcp_exec.`,
+        is_error: true,
+        error_kind: "input_error" as const,
+        hint: `Re-emit a tool_use block with name="${input.tool}" and its own input schema. Do not wrap it in mcp_exec.`,
+      };
+    }
     if (isCaptureMode()) {
       const canned = fakeMcpExec(input.server, input.tool, input.args);
       if (canned) {

package/src/tools/membot/adapter.ts

@@ -34,13 +34,14 @@ type MembotMethodName =
   | "move"
   | "remove"
   | "refresh"
-  | "prune";
+  | "prune"
+  | "sources";
 
 /**
- * Map an Operation's exposed name (`membot_add`, `membot_delete`, …) to the
- * `MembotClient` method that actually runs it. The two diverge in a couple
- * of spots — `membot_delete` calls `client.remove`, `membot_move` calls
- * `client.move` — so we keep the routing explicit rather than guessing.
+ * Map an Operation's exposed name (`membot_add`, `membot_remove`, …) to the
+ * `MembotClient` method that actually runs it. Mostly 1:1 with the op name
+ * minus the `membot_` prefix; kept explicit so a renamed/added op fails
+ * loudly at registration instead of silently misrouting.
  */
 const METHOD_BY_OP_NAME: Record<string, MembotMethodName> = {
   membot_add: "add",
@@ -54,9 +55,10 @@ const METHOD_BY_OP_NAME: Record<string, MembotMethodName> = {
   membot_diff: "diff",
   membot_write: "write",
   membot_move: "move",
-  membot_delete: "remove",
+  membot_remove: "remove",
   membot_refresh: "refresh",
   membot_prune: "prune",
+  membot_sources: "sources",
 };
 
 /**

package/src/tools/membot/edit.ts

@@ -32,7 +32,7 @@ const outputSchema = z.object({
 export const membotEditTool = {
   name: "membot_edit",
   description:
-    "[[ bash equivalent command: patch ]] Apply line-range edits to a stored file: reads the current version, applies bottom-up patches, and writes the result back as a new version. Prefer this over membot_write when you only need to change part of a file — the diff is small and the change_note travels with the new version. To replace the whole body, use membot_write. To delete the file, use membot_delete.",
+    "[[ bash equivalent command: patch ]] Apply line-range edits to a stored file: reads the current version, applies bottom-up patches, and writes the result back as a new version. Prefer this over membot_write when you only need to change part of a file — the diff is small and the change_note travels with the new version. To replace the whole body, use membot_write. To delete the file, use membot_remove.",
   group: "membot",
   inputSchema,
   outputSchema,

package/src/tools/util/read_large_result.ts

@@ -38,7 +38,7 @@ const outputSchema = z.object({
 
 export const readLargeResultTool = {
   name: "read_large_result",
-  description: `[[ bash equivalent command: sed -n '<page>p' ]] Read one page of a large tool result that was cached because its inline payload exceeded the response budget. Use the id from the "Paginated for LLM" stub. Pages are 1-based and ~${PAGE_SIZE_CHARS} chars each; loop from page=1 to total_pages.`,
+  description: `[[ bash equivalent command: sed -n '<page>p' ]] Read one page of a large tool result that Botholomew cached because its inline payload exceeded the response budget. This is a TOP-LEVEL Botholomew tool — call it directly by name, do NOT route it through mcp_exec (it is not an MCP tool, even if the originating result came from an MCP server). Use the id from the "Paginated for LLM" stub. Pages are 1-based and ~${PAGE_SIZE_CHARS} chars each; loop from page=1 to total_pages.`,
   group: "util",
   inputSchema,
   outputSchema,

package/src/tui/components/ContextPanel.tsx

@@ -29,15 +29,48 @@ interface ContextEntry {
   description: string | null;
 }
 
+interface SearchHit {
+  logical_path: string;
+  version_id: string;
+  chunk_index: number;
+  snippet: string;
+  score: number;
+}
+
+type SidebarRow =
+  | {
+      kind: "dir";
+      name: string;
+      full_path: string;
+      child_count: number;
+    }
+  | { kind: "file"; entry: ContextEntry }
+  | { kind: "hit"; hit: SearchHit };
+
+type ViewMode = "tree" | "search";
+
 const SIDEBAR_WIDTH = 40;
 const PAGE_SCROLL_LINES = 10;
+const LIST_LIMIT = 1000;
+const SEARCH_LIMIT = 50;
 
 /**
- * Browse the membot knowledge store. Each row is a current-version entry; the
- * detail pane shows the cleaned markdown surrogate. Membot has no real
- * directories — `logical_path` segments are just slashes — so this is a flat
- * paginated list rather than a tree drill-in. Use `botholomew membot tree` /
- * `botholomew membot search` for hierarchical or content-based discovery.
+ * Browse the membot knowledge store. Two modes share the panel:
+ *
+ *   tree   — sidebar shows the immediate children (directories + files)
+ *            of a `currentPrefix` segment of the logical-path namespace.
+ *            `→` on a directory drills in; `←` from the list pops one
+ *            segment back up. Directories are synthesised from `/`
+ *            separators in `logical_path` (membot has no real folders).
+ *
+ *   search — `/` or `s` opens an inline input; `Enter` runs hybrid
+ *            semantic + BM25 search via `mem.search()` and replaces the
+ *            sidebar with ranked hits + snippets. `Esc` returns to tree.
+ *
+ * The DuckDB lock is opened per op (`scopedWithMem`) — never held for the
+ * panel's mount lifetime — so concurrent workers / chat turns / the
+ * membot CLI can claim the shared `~/.membot` store while this panel
+ * sits idle.
  */
 export const ContextPanel = memo(function ContextPanel({
   projectDir,
@@ -46,10 +79,6 @@ export const ContextPanel = memo(function ContextPanel({
   const { rows: termRows, cols: termCols } = useTerminalSize();
   const detailWidth = Math.max(1, termCols - SIDEBAR_WIDTH - 5);
 
-  // Open a fresh membot client per op (list/read/delete) instead of holding
-  // one for the panel's lifetime. Holding the DuckDB file lock for the panel
-  // mount would block other Botholomew processes (workers, chat turns, the
-  // membot CLI) from the shared `~/.membot` store while this panel sits idle.
   const [membotDir, setMembotDir] = useState<string | null>(null);
   useEffect(() => {
     let cancelled = false;
@@ -67,7 +96,14 @@ export const ContextPanel = memo(function ContextPanel({
     [membotDir],
   );
 
+  const [mode, setMode] = useState<ViewMode>("tree");
+  const [currentPrefix, setCurrentPrefix] = useState("");
   const [entries, setEntries] = useState<ContextEntry[]>([]);
+  const [searching, setSearching] = useState(false);
+  const [searchQuery, setSearchQuery] = useState("");
+  const [searchResults, setSearchResults] = useState<SearchHit[]>([]);
+  const [searchError, setSearchError] = useState<string | null>(null);
+  const [searchRunning, setSearchRunning] = useState(false);
   const [selectedIndex, setSelectedIndex] = useState(0);
   const [sidebarScrollOffset, setSidebarScrollOffset] = useState(0);
   const [detailScroll, setDetailScroll] = useState(0);
@@ -79,31 +115,74 @@ export const ContextPanel = memo(function ContextPanel({
 
   const visibleRows = Math.max(1, termRows - 6);
 
-  const refresh = useCallback(async () => {
-    if (!withMem) return;
-    try {
-      const out = await withMem((mem) => mem.list({ limit: 500 }));
-      const list = out.entries.map((e) => ({
-        logical_path: e.logical_path,
-        version_id: e.version_id,
-        size_bytes: e.size_bytes,
-        mime_type: e.mime_type,
-        description: e.description,
-      }));
-      list.sort((a, b) => a.logical_path.localeCompare(b.logical_path));
-      setEntries(list);
-      setSelectedIndex(0);
-      setSidebarScrollOffset(0);
-    } catch {
-      setEntries([]);
+  const loadTree = useCallback(
+    async (prefix: string) => {
+      if (!withMem) return;
+      try {
+        const out = await withMem((mem) =>
+          mem.list({ prefix: prefix || undefined, limit: LIST_LIMIT }),
+        );
+        setEntries(
+          out.entries.map((e) => ({
+            logical_path: e.logical_path,
+            version_id: e.version_id,
+            size_bytes: e.size_bytes,
+            mime_type: e.mime_type,
+            description: e.description,
+          })),
+        );
+      } catch {
+        setEntries([]);
+      }
       setSelectedIndex(0);
       setSidebarScrollOffset(0);
-    }
-  }, [withMem]);
+    },
+    [withMem],
+  );
 
   useEffect(() => {
-    refresh();
-  }, [refresh]);
+    if (mode === "tree") loadTree(currentPrefix);
+  }, [mode, currentPrefix, loadTree]);
+
+  // Derived: immediate children at `currentPrefix`. Directories are
+  // grouped by their first remaining segment; files are entries whose
+  // suffix has no further `/`.
+  const treeRows: SidebarRow[] = useMemo(() => {
+    const dirs = new Map<string, number>();
+    const files: ContextEntry[] = [];
+    for (const e of entries) {
+      if (!e.logical_path.startsWith(currentPrefix)) continue;
+      const suffix = e.logical_path.slice(currentPrefix.length);
+      if (!suffix) continue;
+      const slash = suffix.indexOf("/");
+      if (slash < 0) {
+        files.push(e);
+      } else {
+        const name = suffix.slice(0, slash);
+        dirs.set(name, (dirs.get(name) ?? 0) + 1);
+      }
+    }
+    const dirRows: SidebarRow[] = [...dirs.entries()]
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([name, count]) => ({
+        kind: "dir",
+        name,
+        full_path: currentPrefix + name,
+        child_count: count,
+      }));
+    const fileRows: SidebarRow[] = files
+      .sort((a, b) => a.logical_path.localeCompare(b.logical_path))
+      .map((entry) => ({ kind: "file", entry }));
+    return [...dirRows, ...fileRows];
+  }, [entries, currentPrefix]);
+
+  const searchRows: SidebarRow[] = useMemo(
+    () => searchResults.map((hit) => ({ kind: "hit", hit })),
+    [searchResults],
+  );
+
+  const rows = mode === "tree" ? treeRows : searchRows;
+  const selectedRow = rows[selectedIndex];
 
   useEffect(() => {
     if (selectedIndex < sidebarScrollOffset) {
@@ -113,75 +192,259 @@ export const ContextPanel = memo(function ContextPanel({
     }
   }, [selectedIndex, sidebarScrollOffset, visibleRows]);
 
-  const selectedEntry = entries[selectedIndex];
+  // Fetch detail content for the selected row.
+  const selectedReadPath = useMemo(() => {
+    if (!selectedRow) return null;
+    if (selectedRow.kind === "file") return selectedRow.entry.logical_path;
+    if (selectedRow.kind === "hit") return selectedRow.hit.logical_path;
+    return null; // directory rows have no readable body
+  }, [selectedRow]);
 
   useEffect(() => {
     let cancelled = false;
-    if (!selectedEntry || !withMem) {
+    if (!selectedReadPath || !withMem) {
       setFileContent(null);
       setDetailScroll(0);
       return;
     }
     setDetailScroll(0);
-    withMem((mem) => mem.read({ logical_path: selectedEntry.logical_path }))
+    withMem((mem) => mem.read({ logical_path: selectedReadPath }))
       .then((result) => {
         if (cancelled) return;
         setFileContent({
-          logical_path: selectedEntry.logical_path,
+          logical_path: selectedReadPath,
           content: result.content ?? "",
         });
       })
       .catch(() => {
         if (cancelled) return;
         setFileContent({
-          logical_path: selectedEntry.logical_path,
+          logical_path: selectedReadPath,
           content: "(failed to read this entry — it may have been removed)",
         });
       });
     return () => {
       cancelled = true;
     };
-  }, [withMem, selectedEntry]);
+  }, [withMem, selectedReadPath]);
 
   const detailLines = useMemo(() => {
-    if (!fileContent || !selectedEntry) return [];
+    if (!selectedRow) return [];
+    if (selectedRow.kind === "dir") {
+      const body = `📁 ${selectedRow.full_path}/\n\n${selectedRow.child_count} item${selectedRow.child_count === 1 ? "" : "s"} under this prefix.\n\nPress → to drill in.`;
+      return wrapDetailLines(body, detailWidth);
+    }
+    if (!fileContent) return [];
+    const snippetHeader =
+      selectedRow.kind === "hit"
+        ? `🔍 match (score=${selectedRow.hit.score.toFixed(3)}, chunk #${selectedRow.hit.chunk_index})\n${selectedRow.hit.snippet}\n\n---\n\n`
+        : "";
     const body = isMarkdownPath(fileContent.logical_path)
-      ? renderMarkdown(fileContent.content)
+      ? renderMarkdown(fileContent.content, detailWidth)
       : fileContent.content;
-    return wrapDetailLines(body, detailWidth);
-  }, [fileContent, selectedEntry, detailWidth]);
+    return wrapDetailLines(snippetHeader + body, detailWidth);
+  }, [selectedRow, fileContent, detailWidth]);
 
   const visibleDetailRows = Math.max(1, visibleRows - 2);
   const maxDetailScroll = Math.max(0, detailLines.length - visibleDetailRows);
 
   const visibleItems = useMemo(
-    () => entries.slice(sidebarScrollOffset, sidebarScrollOffset + visibleRows),
-    [entries, sidebarScrollOffset, visibleRows],
+    () => rows.slice(sidebarScrollOffset, sidebarScrollOffset + visibleRows),
+    [rows, sidebarScrollOffset, visibleRows],
   );
 
-  const itemCountRef = useLatestRef(entries.length);
+  const itemCountRef = useLatestRef(rows.length);
   const maxDetailScrollRef = useLatestRef(maxDetailScroll);
-  const selectedEntryRef = useLatestRef(selectedEntry);
+  const selectedRowRef = useLatestRef(selectedRow);
   const focusRef = useLatestRef(focus);
+  const modeRef = useLatestRef(mode);
+  const currentPrefixRef = useLatestRef(currentPrefix);
+  const searchingRef = useLatestRef(searching);
+
+  const refresh = useCallback(async () => {
+    if (modeRef.current === "tree") {
+      await loadTree(currentPrefixRef.current);
+    }
+    // Search results are a snapshot of a user-issued query; ^R doesn't
+    // re-run the query (it might be expensive and the user can re-press
+    // `/` and Enter).
+  }, [loadTree, modeRef, currentPrefixRef]);
+
+  const runSearch = useCallback(
+    async (query: string) => {
+      if (!withMem) return;
+      const trimmed = query.trim();
+      if (!trimmed) return;
+      // Flip into search mode synchronously so the sidebar shows the
+      // "🔍 query (searching…)" state immediately — otherwise the user
+      // sees no visible change between pressing Enter and the embedding
+      // round-trip completing.
+      setMode("search");
+      setSearchResults([]);
+      setSearchRunning(true);
+      setSearchError(null);
+      setSelectedIndex(0);
+      setSidebarScrollOffset(0);
+      try {
+        const out = await withMem((mem) =>
+          mem.search({ query: trimmed, pattern: trimmed, limit: SEARCH_LIMIT }),
+        );
+        setSearchResults(
+          out.hits.map((h) => ({
+            logical_path: h.logical_path,
+            version_id: h.version_id,
+            chunk_index: h.chunk_index,
+            snippet: h.snippet,
+            score: h.score,
+          })),
+        );
+      } catch (err) {
+        setSearchResults([]);
+        setSearchError(err instanceof Error ? err.message : String(err));
+      } finally {
+        setSearchRunning(false);
+      }
+    },
+    [withMem],
+  );
+
+  const exitSearch = useCallback(() => {
+    setMode("tree");
+    setSearchResults([]);
+    setSearchQuery("");
+    setSearchError(null);
+    setSelectedIndex(0);
+    setSidebarScrollOffset(0);
+  }, []);
+
+  // Debounced live search. While the user is in search-typing mode (or
+  // has committed a non-empty query and we're still on the search view),
+  // any change to `searchQuery` schedules a `mem.search()` 300ms later.
+  // Subsequent keystrokes within the window reset the timer, so a fast
+  // typist makes at most one DB-lock round-trip per pause. The 300ms
+  // figure keeps the DB lock available to workers / chat between bursts
+  // without feeling laggy to the user.
+  useEffect(() => {
+    if (mode !== "search") return;
+    const trimmed = searchQuery.trim();
+    if (!trimmed) {
+      setSearchResults([]);
+      setSearchError(null);
+      setSearchRunning(false);
+      return;
+    }
+    const handle = setTimeout(() => {
+      runSearch(trimmed);
+    }, 300);
+    return () => clearTimeout(handle);
+  }, [mode, searchQuery, runSearch]);
+
+  const drillIn = useCallback((dirFullPath: string) => {
+    setCurrentPrefix(`${dirFullPath}/`);
+    setSelectedIndex(0);
+    setSidebarScrollOffset(0);
+    setFocus("list");
+  }, []);
+
+  const popPrefix = useCallback(() => {
+    const prefix = currentPrefixRef.current;
+    if (!prefix) return false;
+    // prefix always ends in "/"; strip it, then remove the last segment.
+    const trimmed = prefix.replace(/\/$/, "");
+    const slash = trimmed.lastIndexOf("/");
+    const next = slash < 0 ? "" : `${trimmed.slice(0, slash)}/`;
+    setCurrentPrefix(next);
+    setSelectedIndex(0);
+    setSidebarScrollOffset(0);
+    return true;
+  }, [currentPrefixRef]);
 
   const deleteConfirm = useDeleteConfirm(() => {
-    const entry = selectedEntryRef.current;
-    if (!entry || !withMem) return;
-    const path = entry.logical_path;
+    const row = selectedRowRef.current;
+    if (!row || !withMem) return;
+    if (row.kind === "dir") {
+      const path = row.full_path;
+      (async () => {
+        try {
+          await withMem((mem) =>
+            mem.remove({ paths: [path], recursive: true }),
+          );
+        } catch {
+          // ignore — refresh will reflect any partial state
+        }
+        await refresh();
+      })();
+      return;
+    }
+    const path =
+      row.kind === "file" ? row.entry.logical_path : row.hit.logical_path;
     (async () => {
       try {
         await withMem((mem) => mem.remove({ paths: [path] }));
       } catch {
         // ignore — refresh will reflect any partial state
       }
-      refresh();
+      if (modeRef.current === "search") {
+        // Drop the deleted hit from the local results so the list updates.
+        setSearchResults((prev) => prev.filter((h) => h.logical_path !== path));
+        setSelectedIndex((i) =>
+          Math.max(0, Math.min(i, searchRows.length - 2)),
+        );
+      } else {
+        await refresh();
+      }
     })();
   });
 
   useInput(
     (input, key) => {
+      // Search-typing mode: capture characters; the debounced effect on
+      // `searchQuery` does the actual `mem.search()` call. Enter closes
+      // the input bar but leaves results visible. Esc cancels back to
+      // tree. Arrow keys and other navigation fall through to
+      // handleListDetailKey below so the user can ↑↓ through results
+      // while the input is still open.
+      if (searchingRef.current) {
+        if (key.escape) {
+          setSearching(false);
+          exitSearch();
+          return;
+        }
+        if (key.return) {
+          setSearching(false);
+          return;
+        }
+        if (key.backspace || key.delete) {
+          setSearchQuery((q) => q.slice(0, -1));
+          return;
+        }
+        const isNavKey =
+          key.upArrow ||
+          key.downArrow ||
+          key.leftArrow ||
+          key.rightArrow ||
+          key.pageUp ||
+          key.pageDown ||
+          key.tab;
+        if (!isNavKey && input && !key.ctrl && !key.meta) {
+          // Flip to search mode on the first keystroke so the sidebar
+          // header updates immediately and the debounced effect runs.
+          if (modeRef.current !== "search") setMode("search");
+          setSearchQuery((q) => q + input);
+          return;
+        }
+        if (!isNavKey) return;
+        // fall through to handleListDetailKey for nav keys
+      }
+
       if (input !== "d") deleteConfirm.cancel();
 
+      // Esc in search-results mode returns to the tree view.
+      if (key.escape && modeRef.current === "search") {
+        exitSearch();
+        return;
+      }
+
       if (
         handleListDetailKey(input, key, {
           focusRef,
@@ -191,21 +454,50 @@ export const ContextPanel = memo(function ContextPanel({
           setSelectedIndex,
           setDetailScroll,
           pageScrollLines: PAGE_SCROLL_LINES,
+          onRightArrow: () => {
+            if (focusRef.current !== "list") return false;
+            const row = selectedRowRef.current;
+            if (row?.kind === "dir") {
+              drillIn(row.full_path);
+              return true;
+            }
+            return false;
+          },
+          onLeftArrow: () => {
+            if (focusRef.current !== "list") return false;
+            if (modeRef.current === "search") {
+              exitSearch();
+              return true;
+            }
+            return popPrefix();
+          },
         })
       ) {
         return;
       }
 
       if (input === "d") {
-        const entry = selectedEntryRef.current;
-        if (!entry) return;
-        deleteConfirm.pressDelete(entry.logical_path);
+        const row = selectedRowRef.current;
+        if (!row) return;
+        const label =
+          row.kind === "dir"
+            ? `${row.full_path}/ (${row.child_count} items)`
+            : row.kind === "file"
+              ? row.entry.logical_path
+              : row.hit.logical_path;
+        deleteConfirm.pressDelete(label);
         return;
       }
       if (key.ctrl && (input === "r" || input === "R")) {
         refresh();
         return;
       }
+      if (input === "/" || input === "s") {
+        setSearching(true);
+        setSearchQuery("");
+        setSearchError(null);
+        return;
+      }
     },
     { isActive },
   );
@@ -215,6 +507,11 @@ export const ContextPanel = memo(function ContextPanel({
     detailScroll + visibleDetailRows,
   );
 
+  const sidebarHeader =
+    mode === "search"
+      ? `🔍 "${searchQuery || "(empty)"}" (${searchResults.length})`
+      : `membot · /${currentPrefix} (${rows.length})`;
+
   return (
     <Box flexGrow={1} height={visibleRows + 1} overflow="hidden">
       <Box
@@ -231,26 +528,50 @@ export const ContextPanel = memo(function ContextPanel({
       >
         <Box paddingX={1}>
           <Text bold dimColor wrap="truncate-end">
-            membot ({entries.length})
+            {sidebarHeader}
           </Text>
         </Box>
-        {entries.length === 0 ? (
+        {searching && (
+          <Box paddingX={1}>
+            <Text color={theme.info}>🔍 </Text>
+            <Text color={theme.info}>{searchQuery}</Text>
+            <Text color={theme.info}>▌</Text>
+          </Box>
+        )}
+        {rows.length === 0 ? (
           <Box paddingX={1}>
-            <Text dimColor>(empty — try `botholomew membot add …`)</Text>
+            <Text dimColor>
+              {mode === "search"
+                ? searchRunning
+                  ? "(searching…)"
+                  : searchError
+                    ? `(error: ${searchError})`
+                    : "(no hits — Esc to return)"
+                : currentPrefix
+                  ? "(empty — ← to go back)"
+                  : "(empty — try `botholomew membot add …`)"}
+            </Text>
           </Box>
         ) : (
-          visibleItems.map((entry, vi) => {
+          visibleItems.map((row, vi) => {
             const i = vi + sidebarScrollOffset;
             const isSelected = i === selectedIndex;
+            const label = renderRowLabel(row);
+            const key =
+              row.kind === "dir"
+                ? `d:${row.full_path}`
+                : row.kind === "file"
+                  ? `f:${row.entry.logical_path}`
+                  : `h:${row.hit.logical_path}:${row.hit.chunk_index}`;
             return (
-              <Box key={entry.logical_path} paddingX={1}>
+              <Box key={key} paddingX={1}>
                 <Text
                   backgroundColor={isSelected ? theme.selectionBg : undefined}
                   color={isSelected ? theme.info : undefined}
                   bold={isSelected}
                   wrap="truncate-end"
                 >
-                  {isSelected ? "▸" : " "} {entry.logical_path}
+                  {isSelected ? "▸" : " "} {label}
                 </Text>
               </Box>
             );
@@ -266,9 +587,9 @@ export const ContextPanel = memo(function ContextPanel({
         {...detailPaneBorderProps(focus)}
         overflow="hidden"
       >
-        {selectedEntry ? (
+        {selectedRow ? (
           <>
-            <ContextDetailHeader entry={selectedEntry} />
+            <ContextDetailHeader row={selectedRow} />
             <Box flexDirection="row" flexGrow={1} overflow="hidden">
               <Box flexDirection="column" flexGrow={1} overflow="hidden">
                 {detailVisible.map((line, i) => {
@@ -300,7 +621,11 @@ export const ContextPanel = memo(function ContextPanel({
           <Text dimColor>
             {focus === "detail"
               ? "↑↓ scroll · ⇧↑↓ page · g/G top/bot · ← back to list"
-              : "↑↓ select · → detail · d delete (×2) · ^R refresh"}
+              : mode === "search"
+                ? "↑↓ select · → detail · Esc/← back to tree · d delete (×2) · / new search"
+                : currentPrefix
+                  ? "↑↓ select · → drill/detail · ← up · / search · d delete (×2) · ^R refresh"
+                  : "↑↓ select · → drill/detail · / search · d delete (×2) · ^R refresh"}
           </Text>
         </Box>
       </Box>
@@ -308,6 +633,22 @@ export const ContextPanel = memo(function ContextPanel({
   );
 });
 
+function renderRowLabel(row: SidebarRow): string {
+  if (row.kind === "dir") {
+    return `📁 ${row.name}/`;
+  }
+  if (row.kind === "file") {
+    return `📄 ${lastSegment(row.entry.logical_path)}`;
+  }
+  // search hit: show path + score
+  return `${row.hit.score.toFixed(2)} ${row.hit.logical_path}`;
+}
+
+function lastSegment(path: string): string {
+  const i = path.lastIndexOf("/");
+  return i < 0 ? path : path.slice(i + 1);
+}
+
 function formatSize(bytes: number | null): string {
   if (bytes === null) return "-";
   if (bytes < 1024) return `${bytes} B`;
@@ -315,27 +656,78 @@ function formatSize(bytes: number | null): string {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
-function ContextDetailHeader({ entry }: { entry: ContextEntry }) {
+function ContextDetailHeader({ row }: { row: SidebarRow }) {
+  if (row.kind === "dir") {
+    return (
+      <Box flexDirection="column" width="100%">
+        <Box>
+          <Text
+            bold
+            color="cyan"
+            backgroundColor={theme.headerBg}
+            wrap="truncate-end"
+          >
+            📁 {row.full_path}/
+          </Text>
+        </Box>
+        <Box>
+          <Text dimColor backgroundColor={theme.headerBg} wrap="truncate-end">
+            directory · {row.child_count} item
+            {row.child_count === 1 ? "" : "s"}
+          </Text>
+        </Box>
+      </Box>
+    );
+  }
+  if (row.kind === "file") {
+    const entry = row.entry;
+    return (
+      <Box flexDirection="column" width="100%">
+        <Box>
+          <Text
+            bold
+            color="cyan"
+            backgroundColor={theme.headerBg}
+            wrap="truncate-end"
+          >
+            📄 {entry.logical_path}
+          </Text>
+        </Box>
+        <Box>
+          <Text dimColor backgroundColor={theme.headerBg} wrap="truncate-end">
+            {entry.mime_type ?? "?"} · {formatSize(entry.size_bytes)} · v=
+            {entry.version_id}
+          </Text>
+        </Box>
+        {entry.description ? (
+          <Box>
+            <Text dimColor backgroundColor={theme.headerBg} wrap="truncate-end">
+              {entry.description}
+            </Text>
+          </Box>
+        ) : null}
+      </Box>
+    );
+  }
+  const hit = row.hit;
   return (
-    <Box flexDirection="column" width="100%" backgroundColor={theme.headerBg}>
+    <Box flexDirection="column" width="100%">
       <Box>
-        <Text bold color="cyan" wrap="truncate-end">
-          📄 {entry.logical_path}
+        <Text
+          bold
+          color="cyan"
+          backgroundColor={theme.headerBg}
+          wrap="truncate-end"
+        >
+          📄 {hit.logical_path}
         </Text>
       </Box>
       <Box>
-        <Text dimColor wrap="truncate-end">
-          {entry.mime_type ?? "?"} · {formatSize(entry.size_bytes)} · v=
-          {entry.version_id}
+        <Text dimColor backgroundColor={theme.headerBg} wrap="truncate-end">
+          hit · score={hit.score.toFixed(3)} · chunk #{hit.chunk_index} · v=
+          {hit.version_id}
         </Text>
       </Box>
-      {entry.description ? (
-        <Box>
-          <Text dimColor wrap="truncate-end">
-            {entry.description}
-          </Text>
-        </Box>
-      ) : null}
     </Box>
   );
 }

package/src/tui/components/SchedulePanel.tsx

@@ -350,14 +350,19 @@ export const SchedulePanel = memo(function SchedulePanel({
 function ScheduleDetailHeader({ schedule }: { schedule: Schedule }) {
   const enabledKey = String(schedule.enabled);
   return (
-    <Box flexDirection="column" width="100%" backgroundColor={theme.headerBg}>
+    <Box flexDirection="column" width="100%">
       <Box>
-        <Text bold color={theme.info} wrap="truncate-end">
+        <Text
+          bold
+          color={theme.info}
+          backgroundColor={theme.headerBg}
+          wrap="truncate-end"
+        >
           {schedule.name}
         </Text>
       </Box>
       <Box>
-        <Text wrap="truncate-end">
+        <Text backgroundColor={theme.headerBg} wrap="truncate-end">
           <Text color={ENABLED_COLORS[enabledKey]}>
             {ENABLED_ICONS[enabledKey]} {ENABLED_LABELS[enabledKey]}
           </Text>

package/src/tui/components/TaskPanel.tsx

@@ -387,14 +387,19 @@ export const TaskPanel = memo(function TaskPanel({
 
 function TaskDetailHeader({ task }: { task: Task }) {
   return (
-    <Box flexDirection="column" width="100%" backgroundColor={theme.headerBg}>
+    <Box flexDirection="column" width="100%">
       <Box>
-        <Text bold color={theme.info} wrap="truncate-end">
+        <Text
+          bold
+          color={theme.info}
+          backgroundColor={theme.headerBg}
+          wrap="truncate-end"
+        >
           {task.name}
         </Text>
       </Box>
       <Box>
-        <Text wrap="truncate-end">
+        <Text backgroundColor={theme.headerBg} wrap="truncate-end">
           <Text color={STATUS_COLORS[task.status]}>
             {STATUS_ICONS[task.status]} {task.status}
           </Text>

package/src/tui/components/ThreadPanel.tsx

@@ -594,9 +594,9 @@ function ThreadDetailHeader({
   isActiveThread: boolean;
 }) {
   return (
-    <Box flexDirection="column" width="100%" backgroundColor={theme.headerBg}>
+    <Box flexDirection="column" width="100%">
       <Box>
-        <Text wrap="truncate-end">
+        <Text backgroundColor={theme.headerBg} wrap="truncate-end">
           <Text bold italic color={theme.info}>
             {thread.title || "(untitled)"}
           </Text>
@@ -608,7 +608,7 @@ function ThreadDetailHeader({
         </Text>
       </Box>
       <Box>
-        <Text wrap="truncate-end">
+        <Text backgroundColor={theme.headerBg} wrap="truncate-end">
           <Text color={TYPE_COLORS[thread.type]}>
             {TYPE_ICONS[thread.type]} {TYPE_LABELS[thread.type]}
           </Text>

package/src/tui/markdown.ts

@@ -1,6 +1,49 @@
-export function renderMarkdown(text: string): string {
+import { extractTableBlocks, renderTable } from "./markdownTables.ts";
+
+/**
+ * Render markdown to ANSI for a TUI detail pane. When `width` is provided,
+ * GFM tables are pulled out and rendered ourselves at that width before
+ * handing the rest off to `Bun.markdown.ansi` — Bun's renderer ignores any
+ * width hint and emits tables at their natural width, which `wrap-ansi` then
+ * shreds mid-cell.
+ */
+export function renderMarkdown(text: string, width?: number): string {
   if (!text) return "";
-  return Bun.markdown.ansi(text).trimEnd();
+  if (width === undefined || width <= 0) {
+    return Bun.markdown.ansi(text).trimEnd();
+  }
+
+  const blocks = extractTableBlocks(text);
+  if (blocks.length === 0) {
+    return Bun.markdown.ansi(text).trimEnd();
+  }
+
+  const lines = text.split("\n");
+  const rendered: string[] = blocks.map((b) =>
+    renderTable(b.rows, b.aligns, width),
+  );
+  // Bun.markdown.ansi mangles NUL bytes (→ U+FFFD), so use a plain alphanumeric
+  // sentinel that survives the markdown pass intact. Wrap each block's
+  // line-range with a single sentinel line, then splice the pre-rendered
+  // table back in after Bun finishes styling the rest of the document.
+  const sentinel = (i: number) => `BHTBLSENTINEL${i}BHTBLEND`;
+  const out = lines.slice();
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    const b = blocks[i];
+    if (!b) continue;
+    out.splice(b.start, b.end - b.start + 1, sentinel(i));
+  }
+  const piped = Bun.markdown.ansi(out.join("\n")).trimEnd();
+  let stitched = piped;
+  for (let i = 0; i < blocks.length; i++) {
+    // Bun wraps each paragraph with a trailing reset (`\x1b[0m`). Strip any
+    // SGR escapes that hug the sentinel so the table doesn't inherit them.
+    const re = new RegExp(
+      `(?:\\x1b\\[[0-9;]*m)*${sentinel(i)}(?:\\x1b\\[[0-9;]*m)*`,
+    );
+    stitched = stitched.replace(re, rendered[i] ?? "");
+  }
+  return stitched;
 }
 
 export function isMarkdownPath(path: string): boolean {

package/src/tui/markdownTables.ts

@@ -0,0 +1,288 @@
+/**
+ * GFM table extraction + width-aware ANSI rendering.
+ *
+ * `Bun.markdown.ansi` renders tables at their natural width and ignores the
+ * caller's column budget, so wide tables get hard-wrapped mid-cell by
+ * `wrap-ansi` in the detail pane. We pre-extract table blocks, render them
+ * ourselves at a width that fits, and let `Bun.markdown.ansi` handle the rest.
+ */
+
+export type Align = "left" | "center" | "right";
+
+export interface TableBlock {
+  /** First line index (inclusive) of the table in the original text. */
+  start: number;
+  /** Last line index (inclusive). */
+  end: number;
+  /** First row is the header. */
+  rows: string[][];
+  aligns: Align[];
+}
+
+const DIM_ON = "\x1b[2m";
+const BOLD_ON = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+const SEPARATOR_CELL_RE = /^\s*:?-{1,}:?\s*$/;
+const FENCE_RE = /^\s{0,3}(```|~~~)/;
+
+export function extractTableBlocks(text: string): TableBlock[] {
+  const lines = text.split("\n");
+  const blocks: TableBlock[] = [];
+  let inFence = false;
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      i++;
+      continue;
+    }
+    if (inFence || !looksLikePipeRow(line)) {
+      i++;
+      continue;
+    }
+    const sep = lines[i + 1] ?? "";
+    if (!looksLikePipeRow(sep)) {
+      i++;
+      continue;
+    }
+    const sepCells = splitRow(sep);
+    if (!sepCells.every((c) => SEPARATOR_CELL_RE.test(c))) {
+      i++;
+      continue;
+    }
+    const header = splitRow(line);
+    const colCount = Math.max(header.length, sepCells.length);
+    const aligns: Align[] = sepCells.slice(0, colCount).map(parseAlignCell);
+    while (aligns.length < colCount) aligns.push("left");
+
+    const rows: string[][] = [normalizeRow(header, colCount)];
+    let j = i + 2;
+    while (j < lines.length) {
+      const body = lines[j] ?? "";
+      if (!looksLikePipeRow(body)) break;
+      // A new separator (consecutive tables) terminates this one.
+      if (splitRow(body).every((c) => SEPARATOR_CELL_RE.test(c))) break;
+      rows.push(normalizeRow(splitRow(body), colCount));
+      j++;
+    }
+
+    blocks.push({ start: i, end: j - 1, rows, aligns });
+    i = j;
+  }
+  return blocks;
+}
+
+export function renderTable(
+  rows: string[][],
+  aligns: Align[],
+  width: number,
+): string {
+  if (rows.length === 0) return "";
+  const colCount = rows[0]?.length ?? 0;
+  if (colCount === 0) return "";
+
+  const plain = rows.map((r) => r.map(stripInlineMarkdown));
+
+  // Per-column natural width (max visible width across all cells).
+  const naturalWidths: number[] = [];
+  for (let c = 0; c < colCount; c++) {
+    let w = 1;
+    for (const row of plain) {
+      const cell = row[c] ?? "";
+      if (visibleWidth(cell) > w) w = visibleWidth(cell);
+    }
+    naturalWidths.push(w);
+  }
+
+  // Overhead: leading "│ " + trailing " │" + " │ " between cols.
+  const borderOverhead = colCount * 3 + 1;
+  const naturalTotal =
+    naturalWidths.reduce((a, b) => a + b, 0) + borderOverhead;
+
+  let colWidths: number[];
+  if (naturalTotal <= width || width <= 0) {
+    colWidths = naturalWidths;
+  } else {
+    colWidths = shrinkColumns(naturalWidths, width - borderOverhead);
+  }
+
+  const lines: string[] = [];
+  lines.push(borderLine("┌", "┬", "┐", colWidths));
+  for (let r = 0; r < plain.length; r++) {
+    const cells = plain[r] ?? [];
+    const isHeader = r === 0;
+    lines.push(dataLine(cells, aligns, colWidths, isHeader));
+    if (isHeader) {
+      lines.push(borderLine("├", "┼", "┤", colWidths));
+    }
+  }
+  lines.push(borderLine("└", "┴", "┘", colWidths));
+  return lines.join("\n");
+}
+
+function looksLikePipeRow(line: string): boolean {
+  // A GFM table row contains at least one unescaped pipe and (after trimming
+  // surrounding whitespace + optional pipes) is non-empty.
+  const stripped = line.trim();
+  if (stripped === "") return false;
+  if (!stripped.includes("|")) return false;
+  return true;
+}
+
+function splitRow(line: string): string[] {
+  let s = line.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|") && !s.endsWith("\\|")) s = s.slice(0, -1);
+  const cells: string[] = [];
+  let buf = "";
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "\\" && s[i + 1] === "|") {
+      buf += "|";
+      i++;
+      continue;
+    }
+    if (ch === "|") {
+      cells.push(buf.trim());
+      buf = "";
+      continue;
+    }
+    buf += ch;
+  }
+  cells.push(buf.trim());
+  return cells;
+}
+
+function parseAlignCell(cell: string): Align {
+  const c = cell.trim();
+  const left = c.startsWith(":");
+  const right = c.endsWith(":");
+  if (left && right) return "center";
+  if (right) return "right";
+  return "left";
+}
+
+function normalizeRow(cells: string[], colCount: number): string[] {
+  const out = cells.slice(0, colCount);
+  while (out.length < colCount) out.push("");
+  return out;
+}
+
+function shrinkColumns(natural: number[], budget: number): number[] {
+  const MIN = 3;
+  const n = natural.length;
+  if (budget < n * MIN) {
+    // Not enough room even for ellipsis everywhere — give each column MIN
+    // and let the caller deal with overflow. (Detail pane minimum is much
+    // wider than this in practice.)
+    return new Array(n).fill(MIN);
+  }
+  const total = natural.reduce((a, b) => a + b, 0) || 1;
+  const raw = natural.map((w) => (w * budget) / total);
+  const floored = raw.map((v) => Math.max(MIN, Math.floor(v)));
+  let used = floored.reduce((a, b) => a + b, 0);
+  // Distribute the remainder to columns with the largest fractional part.
+  const remainders = raw
+    .map((v, i) => ({ i, frac: v - Math.floor(v) }))
+    .sort((a, b) => b.frac - a.frac);
+  let k = 0;
+  while (used < budget && k < remainders.length * 4) {
+    const idx = remainders[k % remainders.length]?.i ?? 0;
+    floored[idx] = (floored[idx] ?? MIN) + 1;
+    used++;
+    k++;
+  }
+  // If we overshot due to MIN clamping, trim from the widest column(s).
+  while (used > budget) {
+    let widest = 0;
+    for (let i = 1; i < n; i++) {
+      if ((floored[i] ?? 0) > (floored[widest] ?? 0)) widest = i;
+    }
+    if ((floored[widest] ?? 0) <= MIN) break;
+    floored[widest] = (floored[widest] ?? 0) - 1;
+    used--;
+  }
+  return floored;
+}
+
+function borderLine(
+  left: string,
+  mid: string,
+  right: string,
+  widths: number[],
+): string {
+  const segs = widths.map((w) => "─".repeat(w + 2));
+  return DIM_ON + left + segs.join(mid) + right + RESET;
+}
+
+function dataLine(
+  cells: string[],
+  aligns: Align[],
+  widths: number[],
+  bold: boolean,
+): string {
+  const parts: string[] = [];
+  parts.push(`${DIM_ON}│${RESET}`);
+  for (let i = 0; i < widths.length; i++) {
+    const w = widths[i] ?? 0;
+    const align = aligns[i] ?? "left";
+    const raw = cells[i] ?? "";
+    const fitted = padCell(raw, w, align);
+    const styled = bold ? `${BOLD_ON}${fitted}${RESET}` : fitted;
+    parts.push(` ${styled} `);
+    parts.push(`${DIM_ON}│${RESET}`);
+  }
+  return parts.join("");
+}
+
+function padCell(text: string, width: number, align: Align): string {
+  const truncated = truncateToWidth(text, width);
+  const pad = width - visibleWidth(truncated);
+  if (pad <= 0) return truncated;
+  if (align === "right") return " ".repeat(pad) + truncated;
+  if (align === "center") {
+    const l = Math.floor(pad / 2);
+    const r = pad - l;
+    return " ".repeat(l) + truncated + " ".repeat(r);
+  }
+  return truncated + " ".repeat(pad);
+}
+
+function truncateToWidth(text: string, width: number): string {
+  if (width <= 0) return "";
+  if (visibleWidth(text) <= width) return text;
+  if (width === 1) return "…";
+  const chars = Array.from(text);
+  let out = "";
+  let used = 0;
+  for (const ch of chars) {
+    if (used + 1 > width - 1) break;
+    out += ch;
+    used++;
+  }
+  return `${out}…`;
+}
+
+function visibleWidth(text: string): number {
+  // Cell text has no ANSI (we strip markdown markers before measuring), so
+  // codepoint count is sufficient. East-Asian double-width chars would be
+  // undercounted; out of scope for v1.
+  return Array.from(text).length;
+}
+
+function stripInlineMarkdown(text: string): string {
+  // Strip a small set of inline markers so cell width measurement matches what
+  // the user sees. Order matters: longer markers first.
+  let s = text;
+  s = s.replace(/`([^`]+)`/g, "$1");
+  s = s.replace(/\*\*([^*]+)\*\*/g, "$1");
+  s = s.replace(/__([^_]+)__/g, "$1");
+  s = s.replace(/~~([^~]+)~~/g, "$1");
+  s = s.replace(/(^|[^*])\*([^*\n]+)\*/g, "$1$2");
+  s = s.replace(/(^|[^_])_([^_\n]+)_/g, "$1$2");
+  // Collapse \| escapes that survived splitRow.
+  s = s.replace(/\\\|/g, "|");
+  return s;
+}

package/src/worker/large-results.ts

@@ -80,7 +80,7 @@ export function buildResultStub(
     preview,
     preview.length < content.length ? "..." : "",
     "",
-    `Use read_large_result with id="${id}" and page=<n> (1–${totalPages}) to read it in ~${PAGE_SIZE_CHARS}-char pages.`,
+    `To read the full result, call the top-level Botholomew tool \`read_large_result\` (NOT via mcp_exec — it is not an MCP tool) with id="${id}" and page=<n> (1–${totalPages}). Each page is ~${PAGE_SIZE_CHARS} chars.`,
   ].join("\n");
 }