@kitlangton/motel 0.1.3 → 0.2.1

package/AGENTS.md

@@ -28,6 +28,11 @@
 - Build the web UI: `bun run web:build`
 - Dev the web UI (with hot reload): `bun run web:dev`
 - Typecheck: `bun run typecheck`
+- Effect LSP diagnostics over the whole project: `bunx effect-language-service diagnostics --project tsconfig.json --format text`
+- Effect LSP interactive setup wizard: `bunx effect-language-service setup`
+
+## Effect LSP
+The repo is wired up with `@effect/language-service` as a `tsconfig.json` `plugins` entry. Editors that pick up the TypeScript workspace plugin (Zed, VSCode, Cursor, NVim via vtsls) will surface Effect-specific diagnostics, quick fixes, and refactors inline. In Zed this requires selecting the workspace TypeScript version — it does so automatically when `node_modules/typescript` is present.
 
 ## Verification
 - The built-in verification step is `bun run typecheck`.
@@ -146,7 +151,12 @@
 - `[` / `]`: switch services
 - `s`: cycle sort mode (recent → slowest → errors)
 - `t`: cycle theme (motel-default → tokyo-night → catppuccin)
-- `/`: enter filter mode (type to match on root operation name; `:error` restricts to failing traces)
+- `/`: enter filter mode.
+  - **In the trace list (L0)** the input matches against the root operation name. Composable modifiers:
+    - `:error` — restrict to traces with at least one failed span (client-side)
+    - `:ai <query>` — FTS5-backed search against LLM prompt/response/tool content (`AI_FTS_KEYS`) across every span in the trace. Tokens are prefix-matched and implicitly AND'd. Debounced 250ms.
+    - Modifiers compose: `/ :ai rate limit :error`
+  - **In the waterfall (L1/L2)** the input runs a client-side substring match against each span's operation name and tag values. Non-matching spans are dimmed; the filter bar shows the live match count. `enter` commits (dim persists while you navigate); `esc` clears.
 - `f`: open attribute filter picker (browse span-attribute keys → values for the current service; `backspace` walks back to keys; `esc` in the trace list clears the active filter)
 - `a`: pause or resume auto-refresh
 - `r`: refresh now

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitlangton/motel",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "A local OpenTelemetry ingest + TUI viewer for development, backed by SQLite.",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
   },
   "scripts": {
     "clear-motel-debug": "bun run skills/motel-debug/scripts/clear-motel-debug.ts",
-    "dev": "bun run src/motel.ts tui",
+    "dev": "MOTEL_OTEL_ENABLED=true bun run src/motel.ts tui",
     "start": "bun run src/motel.ts tui",
     "daemon": "bun run src/motel.ts daemon",
     "status": "bun run src/motel.ts status",
@@ -67,10 +67,12 @@
     "log-stats": "bun run src/cli.ts log-stats",
     "web:dev": "cd web && npx vite",
     "web:build": "cd web && npx vite build",
+    "story:chat": "bun run src/storybook/aiChatStory.tsx",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run web:build"
   },
   "devDependencies": {
+    "@effect/language-service": "^0.85.1",
     "@types/bun": "^1.3.12",
     "@types/react": "^19.2.14",
     "typescript": "^6.0.2"
@@ -78,7 +80,7 @@
   "dependencies": {
     "@effect/atom-react": "^4.0.0-beta.49",
     "@effect/opentelemetry": "^4.0.0-beta.49",
-    "@effect/platform-bun": "^4.0.0-beta.49",
+    "@effect/platform-bun": "^4.0.0-beta.50",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-logs-otlp-http": "^0.214.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.211.0",

package/src/App.tsx

@@ -8,19 +8,173 @@ import { useAppLayout } from "./ui/app/useAppLayout.ts"
 import { useTraceScreenData } from "./ui/app/useTraceScreenData.ts"
 import { TraceWorkspace } from "./ui/app/TraceWorkspace.tsx"
 import {
+	type AttrFacetState,
 	attrPickerIndexAtom,
 	attrPickerInputAtom,
 	attrPickerModeAtom,
 	attrFacetStateAtom,
+	chatDetailChunkIdAtom,
+	chatDetailScrollOffsetAtom,
 	noticeAtom,
 	persistSelectedTheme,
+	selectedAttrIndexAtom,
+	selectedChatChunkIdAtom,
 	selectedThemeAtom,
+	waterfallFilterModeAtom,
+	waterfallFilterTextAtom,
 } from "./ui/state.ts"
+import type { ThemeName } from "./ui/theme.ts"
 import { applyTheme, colors, SEPARATOR, themeLabel } from "./ui/theme.ts"
-import { getVisibleSpans } from "./ui/Waterfall.tsx"
 import { useKeyboardNav } from "./ui/useKeyboardNav.ts"
 import { AttrFilterModal } from "./ui/AttrFilterModal.tsx"
 import { useAttrFilterPicker } from "./ui/useAttrFilterPicker.ts"
+import { getVisibleSpans } from "./ui/Waterfall.tsx"
+
+const NOTICE_TIMEOUT_MS = 2500
+
+const buildHeaderModel = ({
+	headerFooterWidth,
+	selectedTraceService,
+	activeAttrKey,
+	activeAttrValue,
+	autoRefresh,
+	fetchedAt,
+	status,
+}: {
+	readonly headerFooterWidth: number
+	readonly selectedTraceService: string | null
+	readonly activeAttrKey: string | null
+	readonly activeAttrValue: string | null
+	readonly autoRefresh: boolean
+	readonly fetchedAt: Date | null
+	readonly status: string
+}) => {
+	const serviceLabel = selectedTraceService ?? "none"
+	const autoLabel = autoRefresh ? "● live" : "○ paused"
+	const attrFilterLabel = activeAttrKey && activeAttrValue
+		? `  [${activeAttrKey}=${activeAttrValue.length > 20 ? `${activeAttrValue.slice(0, 19)}…` : activeAttrValue}]`
+		: ""
+	const right = fetchedAt
+		? `${autoLabel}  ${formatTimestamp(fetchedAt)}`
+		: status === "loading"
+			? "loading traces..."
+			: ""
+	const leftLength = "MOTEL".length + SEPARATOR.length + serviceLabel.length + attrFilterLabel.length
+	const gap = Math.max(2, headerFooterWidth - leftLength - right.length)
+
+	return {
+		serviceLabel,
+		attrFilterLabel,
+		right,
+		gap,
+	} as const
+}
+
+const AppHeader = ({
+	serviceLabel,
+	attrFilterLabel,
+	gap,
+	right,
+}: {
+	readonly serviceLabel: string
+	readonly attrFilterLabel: string
+	readonly gap: number
+	readonly right: string
+}) => (
+	<box paddingLeft={1} paddingRight={1} flexDirection="column">
+		<TextLine>
+			<span fg={colors.muted} attributes={TextAttributes.BOLD}>MOTEL</span>
+			<span fg={colors.separator}>{SEPARATOR}</span>
+			<span fg={colors.muted}>{serviceLabel}</span>
+			{attrFilterLabel ? <span fg={colors.accent} attributes={TextAttributes.BOLD}>{attrFilterLabel}</span> : null}
+			<span fg={colors.muted}>{" ".repeat(gap)}</span>
+			<span fg={colors.muted} attributes={TextAttributes.BOLD}>{right}</span>
+		</TextLine>
+	</box>
+)
+
+const AppFooter = ({
+	showSplit,
+	footerHeight,
+	contentWidth,
+	leftPaneWidth,
+	rightPaneWidth,
+	footerNotice,
+	spanNavActive,
+	detailView,
+	autoRefresh,
+	headerFooterWidth,
+}: {
+	readonly showSplit: boolean
+	readonly footerHeight: number
+	readonly contentWidth: number
+	readonly leftPaneWidth: number
+	readonly rightPaneWidth: number
+	readonly footerNotice: string | null
+	readonly spanNavActive: boolean
+	readonly detailView: "waterfall" | "span-detail" | "service-logs"
+	readonly autoRefresh: boolean
+	readonly headerFooterWidth: number
+}) => {
+	if (footerHeight <= 0) return null
+
+	return (
+		<>
+			{showSplit
+				? <SplitDivider leftWidth={leftPaneWidth} junction={"┴"} rightWidth={rightPaneWidth} />
+				: <Divider width={contentWidth} />}
+			<box paddingLeft={1} paddingRight={1} flexDirection="column" height={footerHeight}>
+				{footerNotice ? (
+					<PlainLine text={footerNotice} fg={colors.count} />
+				) : (
+					<FooterHints spanNavActive={spanNavActive} detailView={detailView} autoRefresh={autoRefresh} width={headerFooterWidth} />
+				)}
+			</box>
+		</>
+	)
+}
+
+const AppOverlays = ({
+	width,
+	height,
+	showHelp,
+	autoRefresh,
+	selectedTheme,
+	setShowHelp,
+	pickerMode,
+	pickerInput,
+	pickerIndex,
+	activeAttrKey,
+	attrFacets,
+}: {
+	readonly width: number
+	readonly height: number
+	readonly showHelp: boolean
+	readonly autoRefresh: boolean
+	readonly selectedTheme: ThemeName
+	readonly setShowHelp: (value: boolean) => void
+	readonly pickerMode: "off" | "keys" | "values"
+	readonly pickerInput: string
+	readonly pickerIndex: number
+	readonly activeAttrKey: string | null
+	readonly attrFacets: AttrFacetState
+}) => (
+	<>
+		{showHelp ? <HelpModal width={width} height={height} autoRefresh={autoRefresh} themeLabel={themeLabel(selectedTheme)} onClose={() => setShowHelp(false)} /> : null}
+		{pickerMode !== "off" ? (
+			<AttrFilterModal
+				width={width}
+				height={height}
+				mode={pickerMode}
+				input={pickerInput}
+				selectedIndex={pickerIndex}
+				selectedKey={activeAttrKey}
+				state={attrFacets}
+				onClose={() => { /* handled via keyboard */ }}
+			/>
+		) : null}
+	</>
+)
 
 export const App = () => {
 	const { width, height } = useTerminalDimensions()
@@ -52,11 +206,19 @@ export const App = () => {
 		selectedTraceSummary,
 		selectedTrace,
 		filteredTraces,
+		aiCallDetailState,
+		aiChatChunks,
 	} = useTraceScreenData()
 	const [pickerMode] = useAtom(attrPickerModeAtom)
 	const [pickerInput] = useAtom(attrPickerInputAtom)
 	const [pickerIndex] = useAtom(attrPickerIndexAtom)
 	const [attrFacets] = useAtom(attrFacetStateAtom)
+	const [waterfallFilterMode] = useAtom(waterfallFilterModeAtom)
+	const [waterfallFilterText] = useAtom(waterfallFilterTextAtom)
+	const [selectedAttrIndex] = useAtom(selectedAttrIndexAtom)
+	const [selectedChatChunkId, setSelectedChatChunkId] = useAtom(selectedChatChunkIdAtom)
+	const [chatDetailChunkId, setChatDetailChunkId] = useAtom(chatDetailChunkIdAtom)
+	const [chatDetailScrollOffset, setChatDetailScrollOffset] = useAtom(chatDetailScrollOffsetAtom)
 	useAttrFilterPicker(activeAttrKey)
 
 	const layout = useAppLayout({ width, height, notice, detailView, selectedSpanIndex })
@@ -86,7 +248,7 @@ export const App = () => {
 		setNotice(message)
 		noticeTimeoutRef.current = globalThis.setTimeout(() => {
 			setNotice((current) => (current === message ? null : current))
-		}, 2500)
+		}, NOTICE_TIMEOUT_MS)
 	}
 
 	useEffect(() => () => {
@@ -102,6 +264,7 @@ export const App = () => {
 	const { spanNavActive } = useKeyboardNav({
 		selectedTrace,
 		filteredTraces,
+		aiChatChunks,
 		isWideLayout,
 		wideBodyLines,
 		narrowBodyLines,
@@ -110,30 +273,41 @@ export const App = () => {
 		flashNotice,
 	})
 
-	const headerServiceLabel = selectedTraceService ?? "none"
-	const autoLabel = autoRefresh ? "● live" : "○ paused"
-	const attrFilterLabel = activeAttrKey && activeAttrValue
-		? `  [${activeAttrKey}=${activeAttrValue.length > 20 ? `${activeAttrValue.slice(0, 19)}…` : activeAttrValue}]`
-		: ""
-	const headerRight = traceState.fetchedAt
-		? `${autoLabel}  ${formatTimestamp(traceState.fetchedAt)}`
-		: traceState.status === "loading"
-			? "loading traces..."
-			: ""
-	const headerLeftLen = "MOTEL".length + SEPARATOR.length + headerServiceLabel.length + attrFilterLabel.length
-	const headerGap = Math.max(2, headerFooterWidth - headerLeftLen - headerRight.length)
-	const visibleFooterNotice = footerNotice
+	const headerModel = buildHeaderModel({
+		headerFooterWidth,
+		selectedTraceService,
+		activeAttrKey,
+		activeAttrValue,
+		autoRefresh,
+		fetchedAt: traceState.fetchedAt,
+		status: traceState.status,
+	})
 
 	const selectTraceById = useCallback((traceId: string) => {
 		const index = traceState.data.findIndex((trace) => trace.traceId === traceId)
 		if (index >= 0) setSelectedTraceIndex(index)
 	}, [setSelectedTraceIndex, traceState.data])
 
+	const visibleSpans = useMemo(
+		() => selectedTrace ? getVisibleSpans(selectedTrace.spans, collapsedSpanIds) : [],
+		[selectedTrace, collapsedSpanIds],
+	)
+
+	const openChatChunkDetail = useCallback((chunkId: string) => {
+		setSelectedChatChunkId(chunkId)
+		setChatDetailChunkId(chunkId)
+		setChatDetailScrollOffset(0)
+	}, [setSelectedChatChunkId, setChatDetailChunkId, setChatDetailScrollOffset])
+
+	const closeChatChunkDetail = useCallback(() => {
+		setChatDetailChunkId(null)
+		setChatDetailScrollOffset(0)
+	}, [setChatDetailChunkId, setChatDetailScrollOffset])
+
 	const selectSpan = useCallback((index: number) => {
-		if (!selectedTrace) return
-		const visibleCount = getVisibleSpans(selectedTrace.spans, collapsedSpanIds).length
-		setSelectedSpanIndex(Math.max(0, Math.min(index, visibleCount - 1)))
-	}, [collapsedSpanIds, selectedTrace, setSelectedSpanIndex])
+		if (visibleSpans.length === 0) return
+		setSelectedSpanIndex(Math.max(0, Math.min(index, visibleSpans.length - 1)))
+	}, [setSelectedSpanIndex, visibleSpans])
 
 	const traceListProps = useMemo(() => ({
 		traces: filteredTraces,
@@ -150,27 +324,23 @@ export const App = () => {
 		onSelectTrace: selectTraceById,
 	} as const), [filteredTraces, selectedTraceSummary?.traceId, traceState.status, traceState.error, leftContentWidth, traceState.services, selectedTraceService, spanNavActive, filterText, traceSort, traceState.data.length, selectTraceById])
 
-	const filteredSpans = selectedTrace ? getVisibleSpans(selectedTrace.spans, collapsedSpanIds) : []
-	const selectedSpan = selectedSpanIndex !== null ? filteredSpans[selectedSpanIndex] ?? null : null
+	const selectedSpan = selectedSpanIndex !== null ? visibleSpans[selectedSpanIndex] ?? null : null
 	const selectedSpanLogs = useMemo(
 		() => selectedSpan ? logState.data.filter((log) => log.spanId === selectedSpan.spanId) : [],
 		[selectedSpan, logState.data],
 	)
 
-	const showSplit = isWideLayout
+	// Top/bottom frame dividers only render junction glyphs (`┬` / `┴`)
+	// when there's actually a vertical SeparatorColumn in the workspace
+	// below/above them to meet. Service-logs view is wide but single-pane,
+	// so its frame dividers must be plain — otherwise the junction floats
+	// above an empty column and leaves a visible stale sliver when
+	// toggling tab back and forth with the trace view.
+	const showSplit = isWideLayout && detailView !== "service-logs"
 
 	return (
 		<box width={width ?? 100} height={height ?? 24} flexGrow={1} flexDirection="column" backgroundColor={RGBA.fromHex(colors.screenBg)}>
-			<box paddingLeft={1} paddingRight={1} flexDirection="column">
-				<TextLine>
-					<span fg={colors.muted} attributes={TextAttributes.BOLD}>MOTEL</span>
-					<span fg={colors.separator}>{SEPARATOR}</span>
-					<span fg={colors.muted}>{headerServiceLabel}</span>
-					{attrFilterLabel ? <span fg={colors.accent} attributes={TextAttributes.BOLD}>{attrFilterLabel}</span> : null}
-					<span fg={colors.muted}>{" ".repeat(headerGap)}</span>
-					<span fg={colors.muted} attributes={TextAttributes.BOLD}>{headerRight}</span>
-				</TextLine>
-			</box>
+			<AppHeader {...headerModel} />
 			{showSplit
 				? <SplitDivider leftWidth={leftPaneWidth} junction={"┬"} rightWidth={rightPaneWidth} />
 				: <Divider width={contentWidth} />}
@@ -179,6 +349,8 @@ export const App = () => {
 				detailView={detailView}
 				filterMode={filterMode}
 				filterText={filterText}
+				waterfallFilterMode={waterfallFilterMode}
+				waterfallFilterText={waterfallFilterText}
 				traceListProps={traceListProps}
 				selectedTraceService={selectedTraceService}
 				serviceLogState={serviceLogState}
@@ -193,35 +365,43 @@ export const App = () => {
 				viewLevel={viewLevel}
 				selectedSpan={selectedSpan}
 				selectedSpanLogs={selectedSpanLogs}
+				selectedAttrIndex={selectedAttrIndex}
+				aiCallDetailState={aiCallDetailState}
+				aiChatChunks={aiChatChunks}
+				selectedChatChunkId={selectedChatChunkId}
+				onSelectChatChunk={setSelectedChatChunkId}
+				chatDetailChunkId={chatDetailChunkId}
+				onOpenChatChunkDetail={openChatChunkDetail}
+				onCloseChatChunkDetail={closeChatChunkDetail}
+				chatDetailScrollOffset={chatDetailScrollOffset}
+				onSetChatDetailScrollOffset={(updater) => setChatDetailScrollOffset(updater)}
 				selectSpan={selectSpan}
 			/>
-			{footerHeight > 0 ? (
-				<>
-					{showSplit
-						? <SplitDivider leftWidth={leftPaneWidth} junction={"┴"} rightWidth={rightPaneWidth} />
-						: <Divider width={contentWidth} />}
-					<box paddingLeft={1} paddingRight={1} flexDirection="column" height={footerHeight}>
-						{visibleFooterNotice ? (
-							<PlainLine text={visibleFooterNotice} fg={colors.count} />
-						) : (
-							<FooterHints spanNavActive={spanNavActive} detailView={detailView} autoRefresh={autoRefresh} width={headerFooterWidth} />
-						)}
-					</box>
-				</>
-			) : null}
-			{showHelp ? <HelpModal width={width ?? 100} height={height ?? 24} autoRefresh={autoRefresh} themeLabel={themeLabel(selectedTheme)} onClose={() => setShowHelp(false)} /> : null}
-			{pickerMode !== "off" ? (
-				<AttrFilterModal
-					width={width ?? 100}
-					height={height ?? 24}
-					mode={pickerMode}
-					input={pickerInput}
-					selectedIndex={pickerIndex}
-					selectedKey={activeAttrKey}
-					state={attrFacets}
-					onClose={() => { /* handled via keyboard */ }}
-				/>
-			) : null}
+			<AppFooter
+				showSplit={showSplit}
+				footerHeight={footerHeight}
+				contentWidth={contentWidth}
+				leftPaneWidth={leftPaneWidth}
+				rightPaneWidth={rightPaneWidth}
+				footerNotice={footerNotice}
+				spanNavActive={spanNavActive}
+				detailView={detailView}
+				autoRefresh={autoRefresh}
+				headerFooterWidth={headerFooterWidth}
+			/>
+			<AppOverlays
+				width={width ?? 100}
+				height={height ?? 24}
+				showHelp={showHelp}
+				autoRefresh={autoRefresh}
+				selectedTheme={selectedTheme}
+				setShowHelp={setShowHelp}
+				pickerMode={pickerMode}
+				pickerInput={pickerInput}
+				pickerIndex={pickerIndex}
+				activeAttrKey={activeAttrKey}
+				attrFacets={attrFacets}
+			/>
 		</box>
 	)
 }

package/src/daemon.test.ts

@@ -4,23 +4,70 @@ import * as fs from "node:fs"
 import * as os from "node:os"
 import * as path from "node:path"
 import { createDaemonManager } from "./daemon.js"
+import { MOTEL_SERVICE_ID } from "./registry.js"
 
 const repoRoot = path.resolve(import.meta.dir, "..")
 
 const randomPort = () => 29000 + Math.floor(Math.random() * 2000)
 
-const makeHarness = () => {
+interface Harness {
+	readonly runtimeDir: string
+	readonly port: number
+	readonly databasePath: string
+	readonly manager: ReturnType<typeof createDaemonManager>
+}
+
+const makeHarness = (): Harness => {
 	const runtimeDir = fs.mkdtempSync(path.join(os.tmpdir(), "motel-daemon-test-"))
+	const port = randomPort()
+	const databasePath = path.join(runtimeDir, "telemetry.sqlite")
 	const manager = createDaemonManager({
 		repoRoot,
 		runtimeDir,
-		databasePath: path.join(runtimeDir, "telemetry.sqlite"),
-		port: randomPort(),
+		databasePath,
+		port,
 	})
-	return {
-		runtimeDir,
-		manager,
-	}
+	return { runtimeDir, port, databasePath, manager }
+}
+
+/**
+ * Start a motel-shaped HTTP server on a test port that answers
+ * /api/health with an arbitrary delay. Used to simulate a real daemon
+ * that's alive + holding the port but currently slow — the exact
+ * scenario that makes `bun dev` fail with EADDRINUSE when the
+ * supervisor's health probe times out and it tries to spawn a
+ * duplicate. Returns a stop() that releases the port.
+ */
+const startFakeDaemon = (opts: {
+	readonly port: number
+	readonly databasePath: string
+	readonly delayMs: number
+}) => {
+	const startedAt = new Date().toISOString()
+	const server = Bun.serve({
+		port: opts.port,
+		hostname: "127.0.0.1",
+		async fetch(req) {
+			const url = new URL(req.url)
+			if (url.pathname !== "/api/health") {
+				return new Response("not found", { status: 404 })
+			}
+			if (opts.delayMs > 0) {
+				await new Promise((resolve) => setTimeout(resolve, opts.delayMs))
+			}
+			return Response.json({
+				ok: true,
+				service: MOTEL_SERVICE_ID,
+				databasePath: opts.databasePath,
+				pid: process.pid,
+				url: `http://127.0.0.1:${opts.port}`,
+				workdir: process.cwd(),
+				startedAt,
+				version: "0.0.0-test",
+			})
+		},
+	})
+	return { stop: () => server.stop(true) }
 }
 
 const activeHarnesses: Array<ReturnType<typeof makeHarness>> = []
@@ -33,6 +80,96 @@ afterEach(async () => {
 })
 
 describe("daemon manager", () => {
+	test("warm-start via registry is fast even when HTTP health is slow", async () => {
+		// The failure mode we're preventing: a fully-healthy motel daemon
+		// is alive for our cwd, but its /api/health response queues
+		// behind heavy OTLP ingest traffic and takes >1s (seen on this
+		// machine: /api/health taking 4s under real load). With an
+		// HTTP-only probe the TUI would stall for seconds on every
+		// launch; the registry-based fast path should close in <100ms.
+		const harness = makeHarness()
+		activeHarnesses.push(harness)
+
+		// Scope the motel registry to the harness's runtime dir so we
+		// neither read nor pollute the user's real ~/.local/state/motel.
+		const registryRoot = path.join(harness.runtimeDir, "state")
+		const originalXdg = process.env.XDG_STATE_HOME
+		process.env.XDG_STATE_HOME = registryRoot
+		const registryInstancesDir = path.join(registryRoot, "motel", "instances")
+		fs.mkdirSync(registryInstancesDir, { recursive: true })
+
+		// Seed an entry that points at THIS test process. It's alive
+		// (we're executing), so isAlive(pid) will report true — the
+		// supervisor's fast path will adopt without ever issuing an
+		// HTTP request.
+		const entryPath = path.join(registryInstancesDir, `${process.pid}.json`)
+		fs.writeFileSync(entryPath, JSON.stringify({
+			pid: process.pid,
+			url: `http://127.0.0.1:${harness.port}`,
+			workdir: process.cwd(),
+			startedAt: new Date().toISOString(),
+			version: "0.0.0-test",
+			databasePath: harness.databasePath,
+		}), "utf8")
+
+		// Park a real-but-slow listener on the port. If the supervisor
+		// ever falls back to HTTP we'd wait out the 5s delay; a passing
+		// test proves the fast path took over.
+		const fake = startFakeDaemon({
+			port: harness.port,
+			databasePath: harness.databasePath,
+			delayMs: 5_000,
+		})
+
+		try {
+			const start = performance.now()
+			const status = await Effect.runPromise(harness.manager.ensure)
+			const elapsed = performance.now() - start
+			expect(status.running).toBe(true)
+			expect(status.managed).toBe(true)
+			expect(status.pid).toBe(process.pid)
+			// Generous — real-world is <10ms. Primarily guarding against
+			// a future regression that silently reintroduces an HTTP probe
+			// on the hot path.
+			expect(elapsed).toBeLessThan(500)
+		} finally {
+			fake.stop()
+			fs.rmSync(entryPath, { force: true })
+			if (originalXdg === undefined) delete process.env.XDG_STATE_HOME
+			else process.env.XDG_STATE_HOME = originalXdg
+		}
+	})
+
+	test("adopts a slow-to-respond healthy daemon instead of spawning a duplicate", async () => {
+		// Reproduces the `bun dev` EADDRINUSE flake. A real daemon is alive
+		// and holds the port, but its /api/health response takes longer
+		// than the supervisor's 750ms fetch timeout (e.g. the daemon is
+		// backfilling FTS or the SQLite writer lock is held). The buggy
+		// behaviour: supervisor thinks the port is free, spawns a fresh
+		// daemon child, the child tries to bind() → EADDRINUSE → child
+		// exits → supervisor throws "exited before becoming healthy".
+		//
+		// Correct behaviour: supervisor retries the health probe with a
+		// longer budget before declaring the port empty, finds the
+		// (slow) healthy motel on it, and adopts.
+		const harness = makeHarness()
+		activeHarnesses.push(harness)
+		const fake = startFakeDaemon({
+			port: harness.port,
+			databasePath: harness.databasePath,
+			delayMs: 1_500,
+		})
+		try {
+			const status = await Effect.runPromise(harness.manager.ensure)
+			expect(status.running).toBe(true)
+			expect(status.managed).toBe(true)
+			// PID belongs to the fake test server, not a newly-spawned daemon.
+			expect(status.pid).toBe(process.pid)
+		} finally {
+			fake.stop()
+		}
+	})
+
 	test("starts once, reuses the same daemon, and stops cleanly", async () => {
 		const harness = makeHarness()
 		activeHarnesses.push(harness)