@kitlangton/motel 0.2.0 → 0.2.1

package/src/mcp.ts

@@ -13,6 +13,13 @@ const Attributes = Schema.optional(
 	}),
 )
 
+const AttributeContains = Schema.optional(
+	Schema.Record(Schema.String, Schema.String).annotate({
+		description:
+			"Case-insensitive substring attribute filters. Key is the attribute name WITHOUT the 'attrContains.' prefix (it is added for you). Values must be strings.",
+	}),
+)
+
 const Lookback = Schema.optional(
 	Schema.String.annotate({
 		description:
@@ -42,6 +49,12 @@ const Status = Schema.optional(
 	}),
 )
 
+const Severity = Schema.optional(
+	Schema.String.annotate({
+		description: "Filter by log severity, e.g. TRACE, DEBUG, INFO, WARN, ERROR, FATAL.",
+	}),
+)
+
 const StatusTool = Tool.make("motel_status", {
 	description:
 		"Check which motel instance this shim is connected to. Call this FIRST if any other tool errors, to confirm the connection. Returns url, version, workdir, whether the cwd matches, and how many motel instances are running on this machine.",
@@ -123,11 +136,65 @@ const GetTraceLogsTool = Tool.make("motel_get_trace_logs", {
 	success: Schema.Unknown,
 }).annotate(Tool.Readonly, true)
 
+const GetTraceSpansTool = Tool.make("motel_get_trace_spans", {
+	description:
+		"Fetch the flat span list for a specific trace. Use this when you already know the traceId and want to inspect span durations, status, parents, and raw attributes without the nested trace wrapper.",
+	parameters: Schema.Struct({
+		traceId: Schema.String.annotate({ description: "Full 32-character hex trace ID." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const SearchSpansTool = Tool.make("motel_search_spans", {
+	description:
+		"Search spans directly by service, traceId, operation, parentOperation, status, time window, and raw OTel attributes. Use this when traces are too coarse and you need to find the exact span or suspicious operation first.",
+	parameters: Schema.Struct({
+		service: ServiceParam,
+		traceId: Schema.optional(
+			Schema.String.annotate({ description: "Scope search to a single trace ID." }),
+		),
+		operation: Schema.optional(
+			Schema.String.annotate({ description: "Substring match on span operation name." }),
+		),
+		parentOperation: Schema.optional(
+			Schema.String.annotate({ description: "Substring match on parent operation name." }),
+		),
+		status: Status,
+		attributes: Attributes,
+		attributeContains: AttributeContains,
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetSpanTool = Tool.make("motel_get_span", {
+	description:
+		"Fetch a single span by its 16-character hex spanId. Use this after motel_search_spans to inspect one span's full payload, parent trace, raw tags, and events.",
+	parameters: Schema.Struct({
+		spanId: Schema.String.annotate({ description: "Full 16-character hex span ID." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetSpanLogsTool = Tool.make("motel_get_span_logs", {
+	description:
+		"Fetch log records correlated with a specific span. Use this after motel_get_span when you need the exact logs emitted from that one span, not the entire trace.",
+	parameters: Schema.Struct({
+		spanId: Schema.String.annotate({ description: "Full 16-character hex span ID." }),
+		lookback: Lookback,
+		limit: Limit,
+		cursor: Cursor,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
 const SearchLogsTool = Tool.make("motel_search_logs", {
 	description:
 		"Search logs by service, trace/span correlation, body substring, time window, and arbitrary OTel attributes. Returns log entries with a nextCursor. For logs tied to a known traceId, prefer motel_get_trace_logs — it is more focused.",
 	parameters: Schema.Struct({
 		service: ServiceParam,
+		severity: Severity,
 		traceId: Schema.optional(
 			Schema.String.annotate({ description: "Filter by trace ID." }),
 		),
@@ -138,6 +205,7 @@ const SearchLogsTool = Tool.make("motel_search_logs", {
 			Schema.String.annotate({ description: "Substring match on log body (case-sensitive)." }),
 		),
 		attributes: Attributes,
+		attributeContains: AttributeContains,
 		lookback: Lookback,
 		limit: Limit,
 		cursor: Cursor,
@@ -145,6 +213,79 @@ const SearchLogsTool = Tool.make("motel_search_logs", {
 	success: Schema.Unknown,
 }).annotate(Tool.Readonly, true)
 
+const SearchAiCallsTool = Tool.make("motel_search_ai_calls", {
+	description:
+		"Search normalized AI calls such as streamText and generateText by session, provider, model, functionId, operation, duration, status, or free-text prompt/response content. Use this for LLM-specific investigations rather than raw span search.",
+	parameters: Schema.Struct({
+		service: ServiceParam,
+		traceId: Schema.optional(Schema.String.annotate({ description: "Filter by trace ID." })),
+		sessionId: Schema.optional(Schema.String.annotate({ description: "Filter by normalized AI sessionId." })),
+		functionId: Schema.optional(Schema.String.annotate({ description: "Filter by AI functionId, e.g. session.llm." })),
+		provider: Schema.optional(Schema.String.annotate({ description: "Filter by provider, e.g. openai.responses." })),
+		model: Schema.optional(Schema.String.annotate({ description: "Filter by model ID." })),
+		operation: Schema.optional(Schema.String.annotate({ description: "Filter by normalized AI operation, e.g. streamText." })),
+		status: Status,
+		minDurationMs: Schema.optional(Schema.Number.annotate({ description: "Only return AI calls slower than this (ms)." })),
+		text: Schema.optional(Schema.String.annotate({ description: "Case-insensitive substring match across prompt, response, and tool content." })),
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetAiCallTool = Tool.make("motel_get_ai_call", {
+	description:
+		"Fetch the full detail for one AI call by spanId, including complete prompt messages, response payloads, tool calls, token usage, provider metadata, and correlated logs.",
+	parameters: Schema.Struct({
+		spanId: Schema.String.annotate({ description: "The span ID of the AI call." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const AiStatsTool = Tool.make("motel_ai_stats", {
+	description:
+		"Aggregate AI call statistics grouped by provider, model, functionId, sessionId, or status. Use this before paging raw AI calls when you want to understand which models are slowest or which functions consume the most tokens.",
+	parameters: Schema.Struct({
+		groupBy: Schema.Literals(["provider", "model", "functionId", "sessionId", "status"]),
+		agg: Schema.Literals(["count", "avg_duration", "p95_duration", "total_input_tokens", "total_output_tokens"]),
+		service: ServiceParam,
+		traceId: Schema.optional(Schema.String),
+		sessionId: Schema.optional(Schema.String),
+		functionId: Schema.optional(Schema.String),
+		provider: Schema.optional(Schema.String),
+		model: Schema.optional(Schema.String),
+		operation: Schema.optional(Schema.String),
+		status: Status,
+		minDurationMs: Schema.optional(Schema.Number),
+		lookback: Lookback,
+		limit: Limit,
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const DocsIndexTool = Tool.make("motel_docs_index", {
+	description:
+		"List the documentation pages bundled with motel, such as the debug workflow and Effect guide. Use this before motel_get_doc if you are unsure which docs are available.",
+	parameters: Tool.EmptyParams,
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const GetDocTool = Tool.make("motel_get_doc", {
+	description:
+		"Fetch a bundled motel documentation page as markdown text. Useful for giving an agent the exact debug workflow or Effect instrumentation guidance without leaving MCP.",
+	parameters: Schema.Struct({
+		name: Schema.String.annotate({ description: "Document name, e.g. 'debug' or 'effect'." }),
+	}),
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
+const OpenApiTool = Tool.make("motel_openapi", {
+	description:
+		"Fetch motel's OpenAPI JSON document. Use this when you need the authoritative HTTP API surface or want to compare MCP coverage against the server routes.",
+	parameters: Tool.EmptyParams,
+	success: Schema.Unknown,
+}).annotate(Tool.Readonly, true)
+
 const TraceStatsTool = Tool.make("motel_traces_stats", {
 	description:
 		"Aggregate statistics across traces: count, average duration, p95 duration, or error rate, grouped by a field like service, operation, status, or attr.<key>. Use this BEFORE paginating raw traces when you want to understand the shape of the data — for example 'what tools are the slowest' or 'which services are erroring'.",
@@ -189,9 +330,19 @@ const MotelToolkit = Toolkit.make(
 	SearchTracesTool,
 	GetTraceTool,
 	GetTraceLogsTool,
+	GetTraceSpansTool,
+	SearchSpansTool,
+	GetSpanTool,
+	GetSpanLogsTool,
 	SearchLogsTool,
+	SearchAiCallsTool,
+	GetAiCallTool,
+	AiStatsTool,
 	TraceStatsTool,
 	LogStatsTool,
+	DocsIndexTool,
+	GetDocTool,
+	OpenApiTool,
 )
 
 const asResult = <A>(effect: Effect.Effect<A, { readonly message: string }>) =>
@@ -234,11 +385,32 @@ const ToolHandlers = MotelToolkit.toLayer(
 			motel_get_trace_logs: ({ traceId, lookback, limit, cursor }) =>
 				asResult(client.getTraceLogs(traceId, { lookback, limit, cursor })),
 
+			motel_get_trace_spans: ({ traceId }) => asResult(client.getTraceSpans(traceId)),
+
+			motel_search_spans: (input) => asResult(client.searchSpans(input)),
+
+			motel_get_span: ({ spanId }) => asResult(client.getSpan(spanId)),
+
+			motel_get_span_logs: ({ spanId, lookback, limit, cursor }) =>
+				asResult(client.getSpanLogs(spanId, { lookback, limit, cursor })),
+
 			motel_search_logs: (input) => asResult(client.searchLogs(input)),
 
+			motel_search_ai_calls: (input) => asResult(client.searchAiCalls(input)),
+
+			motel_get_ai_call: ({ spanId }) => asResult(client.getAiCall(spanId)),
+
+			motel_ai_stats: (input) => asResult(client.aiCallStats(input)),
+
 			motel_traces_stats: (input) => asResult(client.traceStats(input)),
 
 			motel_logs_stats: (input) => asResult(client.logStats(input)),
+
+			motel_docs_index: () => asResult(client.docs),
+
+			motel_get_doc: ({ name }) => asResult(Effect.map(client.getDoc(name), (data) => ({ data }))),
+
+			motel_openapi: () => asResult(client.openapi),
 		}
 	}),
 )

package/src/motelClient.ts

@@ -13,6 +13,7 @@ export class MotelHttpError extends Error {
 
 type QueryValue = string | number | boolean | null | undefined
 type Query = Readonly<Record<string, QueryValue>>
+type AttributeFilters = Readonly<Record<string, string>>
 
 const appendQuery = (url: URL, query: Query | undefined) => {
 	if (!query) return url
@@ -23,14 +24,20 @@ const appendQuery = (url: URL, query: Query | undefined) => {
 	return url
 }
 
-const appendAttributes = (url: URL, attributes: Readonly<Record<string, string>> | undefined) => {
+const appendAttributes = (url: URL, prefix: "attr" | "attrContains", attributes: AttributeFilters | undefined) => {
 	if (!attributes) return url
 	for (const [key, value] of Object.entries(attributes)) {
-		url.searchParams.set(`attr.${key}`, value)
+		url.searchParams.set(`${prefix}.${key}`, value)
 	}
 	return url
 }
 
+const appendAllAttributes = (
+	url: URL,
+	attributes: AttributeFilters | undefined,
+	attributeContains: AttributeFilters | undefined,
+) => appendAttributes(appendAttributes(url, "attr", attributes), "attrContains", attributeContains)
+
 export type SearchTracesInput = {
 	readonly service?: string
 	readonly operation?: string
@@ -39,18 +46,33 @@ export type SearchTracesInput = {
 	readonly lookback?: string
 	readonly limit?: number
 	readonly cursor?: string
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
+}
+
+export type SearchSpansInput = {
+	readonly service?: string
+	readonly traceId?: string
+	readonly operation?: string
+	readonly parentOperation?: string
+	readonly status?: "ok" | "error"
+	readonly lookback?: string
+	readonly limit?: number
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
 }
 
 export type SearchLogsInput = {
 	readonly service?: string
+	readonly severity?: string
 	readonly traceId?: string
 	readonly spanId?: string
 	readonly body?: string
 	readonly lookback?: string
 	readonly limit?: number
 	readonly cursor?: string
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
+	readonly attributeContains?: AttributeFilters
 }
 
 export type TraceStatsInput = {
@@ -62,7 +84,7 @@ export type TraceStatsInput = {
 	readonly minDurationMs?: number
 	readonly lookback?: string
 	readonly limit?: number
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
 }
 
 export type LogStatsInput = {
@@ -73,32 +95,77 @@ export type LogStatsInput = {
 	readonly body?: string
 	readonly lookback?: string
 	readonly limit?: number
-	readonly attributes?: Readonly<Record<string, string>>
+	readonly attributes?: AttributeFilters
 }
 
 export type FacetsInput = {
 	readonly type: "traces" | "logs"
 	readonly field: string
+	readonly key?: string
 	readonly service?: string
 	readonly lookback?: string
 	readonly limit?: number
 }
 
+export type TraceLogOptions = {
+	readonly lookback?: string
+	readonly limit?: number
+	readonly cursor?: string
+}
+
+export type AiCallSearchInput = {
+	readonly service?: string
+	readonly traceId?: string
+	readonly sessionId?: string
+	readonly functionId?: string
+	readonly provider?: string
+	readonly model?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly text?: string
+	readonly lookback?: string
+	readonly limit?: number
+}
+
+export type AiCallStatsInput = {
+	readonly groupBy: "provider" | "model" | "functionId" | "sessionId" | "status"
+	readonly agg: "count" | "avg_duration" | "p95_duration" | "total_input_tokens" | "total_output_tokens"
+	readonly service?: string
+	readonly traceId?: string
+	readonly sessionId?: string
+	readonly functionId?: string
+	readonly provider?: string
+	readonly model?: string
+	readonly operation?: string
+	readonly status?: "ok" | "error"
+	readonly minDurationMs?: number
+	readonly lookback?: string
+	readonly limit?: number
+}
+
 export class MotelClient extends Context.Service<
 	MotelClient,
 	{
 		readonly searchTraces: (input: SearchTracesInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchSpans: (input: SearchSpansInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly getTrace: (traceId: string) => Effect.Effect<unknown, MotelHttpError>
-		readonly getTraceLogs: (
-			traceId: string,
-			options: { readonly lookback?: string; readonly limit?: number; readonly cursor?: string },
-		) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTraceSpans: (traceId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getTraceLogs: (traceId: string, options: TraceLogOptions) => Effect.Effect<unknown, MotelHttpError>
+		readonly getSpan: (spanId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly getSpanLogs: (spanId: string, options: TraceLogOptions) => Effect.Effect<unknown, MotelHttpError>
 		readonly searchLogs: (input: SearchLogsInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly searchAiCalls: (input: AiCallSearchInput) => Effect.Effect<unknown, MotelHttpError>
+		readonly getAiCall: (spanId: string) => Effect.Effect<unknown, MotelHttpError>
+		readonly aiCallStats: (input: AiCallStatsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly traceStats: (input: TraceStatsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly logStats: (input: LogStatsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly facets: (input: FacetsInput) => Effect.Effect<unknown, MotelHttpError>
 		readonly services: Effect.Effect<unknown, MotelHttpError>
 		readonly health: Effect.Effect<unknown, MotelHttpError>
+		readonly docs: Effect.Effect<unknown, MotelHttpError>
+		readonly getDoc: (name: string) => Effect.Effect<string, MotelHttpError>
+		readonly openapi: Effect.Effect<unknown, MotelHttpError>
 	}
 >()("motel/MotelClient") {}
 
@@ -107,13 +174,18 @@ export const MotelClientLive = Layer.effect(
 	Effect.gen(function* () {
 		const locator = yield* Locator
 
-		const get = <A = unknown>(path: string, query?: Query, attributes?: Readonly<Record<string, string>>) =>
+		const get = <A = unknown>(
+			path: string,
+			query?: Query,
+			attributes?: AttributeFilters,
+			attributeContains?: AttributeFilters,
+		) =>
 			Effect.gen(function* () {
 				const { url } = yield* Effect.mapError(
 					locator.resolve,
 					(err) => new MotelHttpError(0, err.message),
 				)
-				const target = appendAttributes(appendQuery(new URL(path, url), query), attributes)
+				const target = appendAllAttributes(appendQuery(new URL(path, url), query), attributes, attributeContains)
 				return yield* Effect.tryPromise({
 					try: async () => {
 						const res = await fetch(target, { signal: AbortSignal.timeout(5000) })
@@ -138,10 +210,23 @@ export const MotelClientLive = Layer.effect(
 					lookback: input.lookback,
 					limit: input.limit,
 					cursor: input.cursor,
-				}, input.attributes),
+				}, input.attributes, input.attributeContains),
+
+			searchSpans: (input) =>
+				get("/api/spans/search", {
+					service: input.service,
+					traceId: input.traceId,
+					operation: input.operation,
+					parentOperation: input.parentOperation,
+					status: input.status,
+					lookback: input.lookback,
+					limit: input.limit,
+				}, input.attributes, input.attributeContains),
 
 			getTrace: (traceId) => get(`/api/traces/${encodeURIComponent(traceId)}`),
 
+			getTraceSpans: (traceId) => get(`/api/traces/${encodeURIComponent(traceId)}/spans`),
+
 			getTraceLogs: (traceId, options) =>
 				get(`/api/traces/${encodeURIComponent(traceId)}/logs`, {
 					lookback: options.lookback,
@@ -149,16 +234,61 @@ export const MotelClientLive = Layer.effect(
 					cursor: options.cursor,
 				}),
 
+			getSpan: (spanId) => get(`/api/spans/${encodeURIComponent(spanId)}`),
+
+			getSpanLogs: (spanId, options) =>
+				get(`/api/spans/${encodeURIComponent(spanId)}/logs`, {
+					lookback: options.lookback,
+					limit: options.limit,
+					cursor: options.cursor,
+				}),
+
 			searchLogs: (input) =>
 				get("/api/logs/search", {
 					service: input.service,
+					severity: input.severity,
 					traceId: input.traceId,
 					spanId: input.spanId,
 					body: input.body,
 					lookback: input.lookback,
 					limit: input.limit,
 					cursor: input.cursor,
-				}, input.attributes),
+				}, input.attributes, input.attributeContains),
+
+			searchAiCalls: (input) =>
+				get("/api/ai/calls", {
+					service: input.service,
+					traceId: input.traceId,
+					sessionId: input.sessionId,
+					functionId: input.functionId,
+					provider: input.provider,
+					model: input.model,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					text: input.text,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
+
+			getAiCall: (spanId) => get(`/api/ai/calls/${encodeURIComponent(spanId)}`),
+
+			aiCallStats: (input) =>
+				get("/api/ai/stats", {
+					groupBy: input.groupBy,
+					agg: input.agg,
+					service: input.service,
+					traceId: input.traceId,
+					sessionId: input.sessionId,
+					functionId: input.functionId,
+					provider: input.provider,
+					model: input.model,
+					operation: input.operation,
+					status: input.status,
+					minDurationMs: input.minDurationMs,
+					lookback: input.lookback,
+					limit: input.limit,
+				}),
 
 			traceStats: (input) =>
 				get("/api/traces/stats", {
@@ -188,6 +318,7 @@ export const MotelClientLive = Layer.effect(
 				get("/api/facets", {
 					type: input.type,
 					field: input.field,
+					key: input.key,
 					service: input.service,
 					lookback: input.lookback,
 					limit: input.limit,
@@ -196,6 +327,27 @@ export const MotelClientLive = Layer.effect(
 			services: get("/api/services"),
 
 			health: get("/api/health"),
+
+			docs: get("/api/docs"),
+
+			getDoc: (name) =>
+				Effect.gen(function* () {
+					const { url } = yield* Effect.mapError(locator.resolve, (err) => new MotelHttpError(0, err.message))
+					return yield* Effect.tryPromise({
+						try: async () => {
+							const res = await fetch(new URL(`/api/docs/${encodeURIComponent(name)}`, url), {
+								signal: AbortSignal.timeout(5000),
+							})
+							const body = await res.text()
+							if (!res.ok) throw new MotelHttpError(res.status, body)
+							return body
+						},
+						catch: (err) =>
+							err instanceof MotelHttpError ? err : new MotelHttpError(0, (err as Error).message),
+					}).pipe(Effect.tapError((err) => (err.status === 0 ? locator.invalidate : Effect.void)))
+				}),
+
+			openapi: get("/openapi.json"),
 		}
 	}),
 )

package/src/registry.ts

@@ -16,23 +16,18 @@ export type RegistryEntry = {
 	readonly workdir: string
 	readonly startedAt: string
 	readonly version: string
+	/**
+	 * The SQLite database path the daemon is serving. Optional because
+	 * older daemon builds omit it; consumers should treat a missing
+	 * value as "unknown" and fall back to whatever validation path
+	 * they would have used before this field existed (typically an
+	 * HTTP /api/health probe).
+	 */
+	readonly databasePath?: string
 }
 
 const entryPath = (pid: number) => path.join(registryDir(), `${pid}.json`)
 
-let currentEntryPath: string | null = null
-let signalHandlersRegistered = false
-
-const cleanup = () => {
-	if (!currentEntryPath) return
-	try {
-		fs.unlinkSync(currentEntryPath)
-	} catch {
-		// already gone — ignore
-	}
-	currentEntryPath = null
-}
-
 export const isAlive = (pid: number): boolean => {
 	try {
 		process.kill(pid, 0)
@@ -72,15 +67,23 @@ export const writeRegistryEntry = (entry: RegistryEntry) => {
 	fs.mkdirSync(registryDir(), { recursive: true })
 	const file = entryPath(entry.pid)
 	fs.writeFileSync(file, JSON.stringify(entry, null, 2), "utf8")
-	currentEntryPath = file
-	if (!signalHandlersRegistered) {
-		signalHandlersRegistered = true
-		process.on("exit", cleanup)
-		for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-			process.on(sig, () => {
-				cleanup()
-				process.exit(0)
-			})
-		}
+}
+
+/**
+ * Remove this daemon's registry entry. Intended to be called from a
+ * Layer release so the scope-managed server shutdown removes the entry
+ * in the same finalizer chain that stops the socket. Historically this
+ * was done via ad-hoc process-signal handlers installed here that ran
+ * `process.exit(0)` — which races with the Effect runtime's own SIGINT
+ * handling and short-circuits the Bun server's graceful stop. The
+ * server (via BunRuntime.runMain) now owns signal handling; registry
+ * cleanup rides along on scope release.
+ */
+export const removeRegistryEntry = (pid: number) => {
+	try {
+		fs.unlinkSync(entryPath(pid))
+	} catch {
+		// Already gone — another cleanup path won the race, or the entry
+		// was never written.
 	}
 }

package/src/runtime.ts

@@ -6,7 +6,7 @@ import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base"
 import { Layer, ManagedRuntime } from "effect"
 import { config } from "./config.js"
 import { LogQueryServiceLive } from "./services/LogQueryService.js"
-import { TelemetryStoreLive } from "./services/TelemetryStore.js"
+import { TelemetryStoreLive, TelemetryStoreReadonlyLive } from "./services/TelemetryStore.js"
 import { TraceQueryServiceLive } from "./services/TraceQueryService.js"
 
 const telemetryLayer = NodeSdk.layer(() => ({
@@ -30,9 +30,15 @@ const telemetryLayer = NodeSdk.layer(() => ({
 	},
 }))
 
-const QueryServicesLive = Layer.mergeAll(TraceQueryServiceLive, LogQueryServiceLive).pipe(Layer.provideMerge(TelemetryStoreLive))
+// TUI-side services are readonly — a daemon/worker writer owns the DB
+// lock while ingests are in flight, and trying to grab the write lock
+// for schema init on startup causes "database is locked" on bun dev.
+const QueryServicesLive = Layer.mergeAll(TraceQueryServiceLive, LogQueryServiceLive).pipe(Layer.provideMerge(TelemetryStoreReadonlyLive))
 
 const QueryRuntimeLive = config.otel.enabled ? Layer.mergeAll(QueryServicesLive, telemetryLayer) : QueryServicesLive
 
 export const queryRuntime = ManagedRuntime.make(QueryRuntimeLive)
+// `storeRuntime` is the full writer runtime, exposed for the telemetry
+// test suite (and any future tooling that needs the ingest side). The
+// TUI itself only consumes `queryRuntime`, which is readonly.
 export const storeRuntime = ManagedRuntime.make(TelemetryStoreLive)

package/src/server.ts

@@ -1,10 +1,11 @@
-import { config } from "./config.js"
-import { startLocalServer } from "./localServer.js"
+import { BunRuntime } from "@effect/platform-bun"
+import { Layer } from "effect"
+import { ServerLive } from "./localServer.js"
 
-await startLocalServer()
-
-console.log(`motel local telemetry server listening on ${config.otel.queryUrl}`)
-
-await new Promise(() => {
-	// keep process alive
-})
+// `BunRuntime.runMain` installs signal handlers that interrupt the root
+// fiber on SIGINT/SIGTERM; `Layer.launch` holds the scope open until
+// then. On interruption the scope closes top-down: RegistryLayer's
+// release removes the daemon's registry entry, BunHttpServer's release
+// calls server.stop(), SQLite connections close — all through layer
+// finalizers instead of ad-hoc process.exit handlers.
+Layer.launch(ServerLive).pipe(BunRuntime.runMain)