@fabrika/daemon-kit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contember Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @fabrika/daemon-kit
+
+Bun daemon infrastructure without canvas or browser dependencies:
+
+- `createNotificationChannel`, `browserFrame`: topic-based WebSocket routing.
+- `waitForEvent`, `WaitError`: CLI waiting, reconnects and deadlines.
+- `createDaemonLifecycle`, `DaemonStartError`: process startup, health and shutdown.
+- `dispatch`, `Route`: HTTP routing.
+- `jsonResponse`, `corsHeaders`: HTTP response helpers.
+
+Import runtime functions and types from `@fabrika/daemon-kit`.
+The host supplies its domain-specific frame vocabulary and persistence.
+Canvas session/compile/upload paths remain in `@fabrika/canvas-kernel/server`.

package/index.ts

@@ -0,0 +1,28 @@
+export { browserFrame, createNotificationChannel } from './src/channel'
+export type {
+	BrowserFrameHandler,
+	ChannelRole,
+	ChannelSocket,
+	NotificationChannel,
+	NotificationChannelOptions,
+	RelayOptions,
+	TopicChannel,
+} from './src/channel'
+export { corsHeaders, jsonResponse } from './src/http-utils'
+export { createDaemonLifecycle, DaemonStartError } from './src/lifecycle'
+export type {
+	DaemonEvent,
+	DaemonHealth,
+	DaemonHealthDown,
+	DaemonHealthUp,
+	DaemonLifecycle,
+	DaemonLifecycleConfig,
+	DaemonPid,
+	DaemonStopReason,
+	DaemonStopResult,
+	DaemonTimeouts,
+} from './src/lifecycle'
+export { dispatch } from './src/router'
+export type { Route, RouteHandler } from './src/router'
+export { WaitError, waitForEvent } from './src/waiter'
+export type { WaiterSocket, WaitFailure, WaitMessages, WaitOptions, WaitVerdict } from './src/waiter'

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@fabrika/daemon-kit",
+	"version": "0.2.0",
+	"type": "module",
+	"description": "Bun daemon lifecycle, HTTP routing, WebSocket channels and CLI waiters.",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/contember/fabrika-platform.git",
+		"directory": "packages/daemon-kit"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"index.ts",
+		"src",
+		"!src/**/*.test.ts"
+	],
+	"exports": {
+		".": {
+			"bun": "./index.ts",
+			"types": "./index.ts",
+			"default": "./index.ts"
+		}
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"test": "bun test"
+	}
+}

package/src/channel.ts

@@ -0,0 +1,265 @@
+// Hosts own frame vocabulary and delivery policy; topics are opaque to the channel.
+
+export type ChannelRole = 'browser' | 'wait'
+
+/** The minimum a host socket must offer; `Bun.ServerWebSocket` satisfies it. */
+export interface ChannelSocket {
+	send(message: string): unknown
+	close(): void
+	ping(): unknown
+}
+
+export interface RelayOptions {
+	/**
+	 * Close every waiter the message was handed to and drop the topic's waiter
+	 * set. Defaults to the channel's `waiterPolicy`.
+	 */
+	close?: boolean
+}
+
+/** Channel operations bound to one topic. */
+export interface TopicChannel {
+	readonly topic: string
+	/** Send to every browser on the topic. */
+	broadcast(message: unknown): void
+	/** Send to every waiter on the topic; `false` when there was none. */
+	relayToWaiters(message: unknown, options?: RelayOptions): boolean
+	hasWaiter(): boolean
+	/** Announce current waiter presence to the topic's browsers. */
+	broadcastPresence(): void
+}
+
+export interface BrowserFrameHandler {
+	/** The bound work when the frame is this handler's, `undefined` otherwise. */
+	bind(frame: unknown, channel: TopicChannel): (() => void | Promise<void>) | undefined
+}
+
+/**
+ * Register one frame of a host's vocabulary. Matching is synchronous so the
+ * socket's `message` handler stays synchronous; handling may be async.
+ */
+export function browserFrame<T>(
+	match: (frame: unknown) => frame is T,
+	handle: (frame: T, channel: TopicChannel) => void | Promise<void>,
+): BrowserFrameHandler {
+	return {
+		bind: (frame, channel) => (match(frame) ? () => handle(frame, channel) : undefined),
+	}
+}
+
+export interface NotificationChannelOptions<S extends ChannelSocket> {
+	/** Which registry a socket belongs to. */
+	roleOf(socket: S): ChannelRole
+	/** The socket's routing key — a canvas session id, a Figma file key, … */
+	topicOf(socket: S): string
+	/** The host's browser-frame vocabulary, tried in order; first match wins. */
+	frames?: readonly BrowserFrameHandler[]
+	/** Builds the presence frame. Presence is not announced when omitted. */
+	presenceFrame?(hasWaiter: boolean, topic: string): unknown
+	/** What a relay does to the waiters it reached. Default `"keep-open"`. */
+	waiterPolicy?: 'close-on-delivery' | 'keep-open'
+	/**
+	 * Runs after a waiter is registered and before presence is announced, so a
+	 * host that buffers events for an absent waiter can flush them here.
+	 */
+	onWaiterOpen?(channel: TopicChannel): void
+	/** Frame handler failures. Dropped when omitted. */
+	onError?(error: unknown): void
+	/** Liveness sweep period; `false` leaves the sweep to the host. */
+	pingIntervalMs?: number | false
+}
+
+export interface NotificationChannel<S extends ChannelSocket> {
+	handlers: {
+		open(socket: S): void
+		message(socket: S, message: string | Buffer): void
+		pong(socket: S): void
+		close(socket: S): void
+	}
+	broadcast(topic: string, message: unknown): void
+	relayToWaiters(topic: string, message: unknown, options?: RelayOptions): boolean
+	hasWaiter(topic: string): boolean
+	broadcastPresence(topic: string): void
+	/** The topic-bound view handed to frame handlers. */
+	topic(topic: string): TopicChannel
+	/** One liveness sweep — ping live waiters, evict the ones that never ponged. */
+	pingWaiters(): void
+	/** Stop the liveness timer. */
+	stop(): void
+}
+
+const DEFAULT_PING_INTERVAL_MS = 5_000
+
+function parseFrame(message: string | Buffer): unknown {
+	const text = typeof message === 'string' ? message : new TextDecoder().decode(message)
+	try {
+		return JSON.parse(text)
+	} catch {
+		return undefined
+	}
+}
+
+export function createNotificationChannel<S extends ChannelSocket>(
+	options: NotificationChannelOptions<S>,
+): NotificationChannel<S> {
+	const { roleOf, topicOf } = options
+	const frames = options.frames ?? []
+	const closeOnDelivery = (options.waiterPolicy ?? 'keep-open') === 'close-on-delivery'
+	const browserSockets = new Map<string, Set<S>>()
+	const waitSockets = new Map<string, Set<S>>()
+	const pongReceived = new WeakSet<S>()
+
+	function registry(role: ChannelRole): Map<string, Set<S>> {
+		return role === 'browser' ? browserSockets : waitSockets
+	}
+
+	function hasWaiter(topic: string): boolean {
+		return (waitSockets.get(topic)?.size ?? 0) > 0
+	}
+
+	function broadcast(topic: string, message: unknown): void {
+		const sockets = browserSockets.get(topic)
+		if (!sockets || sockets.size === 0) return
+		const payload = JSON.stringify(message)
+		for (const socket of sockets) socket.send(payload)
+	}
+
+	function presencePayload(topic: string): string | undefined {
+		if (!options.presenceFrame) return undefined
+		return JSON.stringify(options.presenceFrame(hasWaiter(topic), topic))
+	}
+
+	function broadcastPresence(topic: string): void {
+		const payload = presencePayload(topic)
+		if (payload === undefined) return
+		const sockets = browserSockets.get(topic)
+		if (!sockets) return
+		for (const socket of sockets) socket.send(payload)
+	}
+
+	function relayToWaiters(topic: string, message: unknown, relay: RelayOptions = {}): boolean {
+		const sockets = waitSockets.get(topic)
+		if (!sockets || sockets.size === 0) return false
+		const close = relay.close ?? closeOnDelivery
+		if (close) waitSockets.delete(topic)
+		const payload = JSON.stringify(message)
+		for (const socket of sockets) {
+			socket.send(payload)
+			if (close) socket.close()
+		}
+		return true
+	}
+
+	function topicChannel(topic: string): TopicChannel {
+		return {
+			topic,
+			broadcast: (message) => broadcast(topic, message),
+			relayToWaiters: (message, relay) => relayToWaiters(topic, message, relay),
+			hasWaiter: () => hasWaiter(topic),
+			broadcastPresence: () => broadcastPresence(topic),
+		}
+	}
+
+	function reportError(error: unknown): void {
+		options.onError?.(error)
+	}
+
+	function dropWaiter(topic: string, socket: S): void {
+		const sockets = waitSockets.get(topic)
+		if (sockets) {
+			sockets.delete(socket)
+			if (sockets.size === 0) waitSockets.delete(topic)
+		}
+		try {
+			socket.close()
+		} catch {}
+		broadcastPresence(topic)
+	}
+
+	// A dead socket never fires `close`, so presence would stay stuck on `true`
+	// until the daemon restarts — sweep for the missing pong instead.
+	function pingWaiters(): void {
+		for (const [topic, sockets] of waitSockets) {
+			for (const socket of sockets) {
+				if (!pongReceived.has(socket)) {
+					dropWaiter(topic, socket)
+					continue
+				}
+				pongReceived.delete(socket)
+				try {
+					socket.ping()
+				} catch {
+					dropWaiter(topic, socket)
+				}
+			}
+		}
+	}
+
+	const interval = options.pingIntervalMs === false
+		? undefined
+		: setInterval(pingWaiters, options.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS)
+	interval?.unref()
+
+	const handlers = {
+		open(socket: S): void {
+			const topic = topicOf(socket)
+			const role = roleOf(socket)
+			const sockets = registry(role).get(topic) ?? new Set<S>()
+			sockets.add(socket)
+			registry(role).set(topic, sockets)
+
+			if (role === 'browser') {
+				const payload = presencePayload(topic)
+				if (payload !== undefined) socket.send(payload)
+				return
+			}
+			pongReceived.add(socket) // free pass on the first sweep
+			options.onWaiterOpen?.(topicChannel(topic))
+			broadcastPresence(topic)
+		},
+
+		message(socket: S, message: string | Buffer): void {
+			if (roleOf(socket) !== 'browser') return
+			const frame = parseFrame(message)
+			if (frame === undefined) return
+			const channel = topicChannel(topicOf(socket))
+			for (const handler of frames) {
+				const run = handler.bind(frame, channel)
+				if (!run) continue
+				try {
+					const result = run()
+					if (result instanceof Promise) result.catch(reportError)
+				} catch (error) {
+					reportError(error)
+				}
+				return
+			}
+		},
+
+		pong(socket: S): void {
+			if (roleOf(socket) === 'wait') pongReceived.add(socket)
+		},
+
+		close(socket: S): void {
+			const topic = topicOf(socket)
+			const role = roleOf(socket)
+			const sockets = registry(role).get(topic)
+			sockets?.delete(socket)
+			if (sockets && sockets.size === 0) registry(role).delete(topic)
+			if (role === 'wait') broadcastPresence(topic)
+		},
+	}
+
+	return {
+		handlers,
+		broadcast,
+		relayToWaiters,
+		hasWaiter,
+		broadcastPresence,
+		topic: topicChannel,
+		pingWaiters,
+		stop() {
+			if (interval) clearInterval(interval)
+		},
+	}
+}

package/src/http-utils.ts

@@ -0,0 +1,14 @@
+export function jsonResponse(data: unknown, status = 200): Response {
+	return new Response(JSON.stringify(data), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}
+
+export function corsHeaders(port: number): Record<string, string> {
+	return {
+		'Access-Control-Allow-Origin': 'http://localhost:' + port,
+		'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+		'Access-Control-Allow-Headers': 'Content-Type',
+	}
+}

package/src/lifecycle.ts

@@ -0,0 +1,304 @@
+/**
+ * Daemon process lifecycle: is it up, start it, stop it, keep it in step with
+ * the CLI that talks to it.
+ *
+ * The kernel owns the algorithm — health probing, the concurrent-start race,
+ * which pid may be signalled — and the host owns every location: base URL, pid
+ * file, spawn argv, log file, health shape, timeouts.
+ *
+ * The daemon's own pid, reported through `/health`, is the only pid this module
+ * will signal. A pid file is written at spawn and read only to notice that
+ * *someone* is already booting a daemon; a stale file or a reused pid must
+ * never let the CLI kill an unrelated process.
+ */
+
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { dirname } from 'path'
+
+/** Every host health shape must carry the daemon's own pid. */
+export interface DaemonPid {
+	pid: number
+}
+
+export type DaemonHealthUp<H extends DaemonPid> = { status: 'up'; ok: true; url: string } & H
+
+export interface DaemonHealthDown {
+	status: 'down'
+	ok: false
+	url: string
+	error?: string
+}
+
+export type DaemonHealth<H extends DaemonPid> = DaemonHealthUp<H> | DaemonHealthDown
+
+export type DaemonStopReason =
+	| 'stopped'
+	| 'not-running'
+	/** Nothing was running; a pid file left behind was cleaned up. */
+	| 'stale-pid'
+	/** A daemon answered `/health`, but signalling its pid failed. */
+	| 'signal-failed'
+	| 'refused-self'
+
+export interface DaemonStopResult {
+	stopped: boolean
+	/** The daemon's own pid, or the stale pid-file value that was cleaned up. */
+	pid?: number
+	reason: DaemonStopReason
+	message: string
+}
+
+/** Progress worth telling a user about; the host writes the words. */
+export type DaemonEvent =
+	| { type: 'version-mismatch'; running: string; expected: string }
+	| { type: 'starting'; command: readonly string[] }
+	| { type: 'started'; pid: number }
+	| { type: 'stopped'; pid: number }
+
+export interface DaemonTimeouts {
+	/** Per `/health` request. Default 1000. */
+	health?: number
+	/** Wait for a daemon this process spawned. Default 3000. */
+	start?: number
+	/** Wait for a daemon another process is already starting. Default 1000. */
+	concurrentStart?: number
+	/** Wait for a signalled daemon to go down. Default 2000. */
+	stop?: number
+}
+
+export interface DaemonLifecycleConfig<H extends DaemonPid> {
+	/** Daemon origin, e.g. `http://localhost:19400`. */
+	baseUrl: string
+	/** Health endpoint path. Default `/health`. */
+	healthPath?: string
+	/** Narrows the `/health` body; `undefined` means "not a daemon we can talk to". */
+	parseHealth(body: unknown): H | undefined
+	/** Written at spawn, so a concurrent start can see a daemon that is still booting. */
+	pidFile: string
+	/** argv of the daemon process, e.g. `[process.execPath, entry, "serve"]`. */
+	command: readonly string[]
+	/** Working directory of the spawned daemon. Defaults to the current one. */
+	cwd?: string
+	/** File the daemon's stdout and stderr are appended to. */
+	logFile: string
+	/** Restart the daemon when its version differs from this CLI's. Off when omitted. */
+	versionCheck?: {
+		expected: string
+		of(health: H): string | undefined
+	}
+	/** Removed with the pid file when the daemon stops (auth tokens, sockets, …). */
+	cleanupFiles?: readonly string[]
+	timeouts?: DaemonTimeouts
+	onEvent?(event: DaemonEvent): void
+}
+
+export class DaemonStartError extends Error {
+	constructor(message: string, readonly logFile: string, readonly logTail: string) {
+		super(message)
+		this.name = 'DaemonStartError'
+	}
+}
+
+export interface DaemonLifecycle<H extends DaemonPid> {
+	health(timeoutMs?: number): Promise<DaemonHealth<H>>
+	isRunning(): Promise<boolean>
+	start(): Promise<DaemonHealthUp<H>>
+	/** A healthy daemon of the expected version, starting or restarting one if needed. */
+	ensure(): Promise<DaemonHealthUp<H>>
+	stop(): Promise<DaemonStopResult>
+	restart(): Promise<DaemonHealthUp<H>>
+}
+
+const LOG_TAIL_BYTES = 4096
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+export function createDaemonLifecycle<H extends DaemonPid>(
+	config: DaemonLifecycleConfig<H>,
+): DaemonLifecycle<H> {
+	const healthUrl = `${config.baseUrl}${config.healthPath ?? '/health'}`
+	const timeouts = {
+		health: config.timeouts?.health ?? 1_000,
+		start: config.timeouts?.start ?? 3_000,
+		concurrentStart: config.timeouts?.concurrentStart ?? 1_000,
+		stop: config.timeouts?.stop ?? 2_000,
+	}
+
+	function emit(event: DaemonEvent): void {
+		config.onEvent?.(event)
+	}
+
+	async function health(timeoutMs: number = timeouts.health): Promise<DaemonHealth<H>> {
+		const url = config.baseUrl
+		try {
+			const response = await fetch(healthUrl, { signal: AbortSignal.timeout(timeoutMs) })
+			if (!response.ok) return { status: 'down', ok: false, url, error: `HTTP ${response.status}` }
+			const parsed = config.parseHealth(await response.json())
+			if (!parsed) return { status: 'down', ok: false, url, error: 'invalid health response' }
+			return { status: 'up', ok: true, url, ...parsed }
+		} catch (error) {
+			return { status: 'down', ok: false, url, error: errorMessage(error) }
+		}
+	}
+
+	async function pollHealthy(timeoutMs: number): Promise<DaemonHealth<H>> {
+		const deadline = Date.now() + timeoutMs
+		let last = await health()
+		while (last.status === 'down' && Date.now() < deadline) {
+			await sleep(100)
+			last = await health()
+		}
+		return last
+	}
+
+	function readPid(): number | undefined {
+		try {
+			const pid = Number(readFileSync(config.pidFile, 'utf-8').trim())
+			return Number.isInteger(pid) && pid > 0 ? pid : undefined
+		} catch {
+			return undefined
+		}
+	}
+
+	function processIsAlive(pid: number): boolean {
+		try {
+			process.kill(pid, 0)
+			return true
+		} catch {
+			return false
+		}
+	}
+
+	function cleanupFiles(): void {
+		for (const file of [config.pidFile, ...(config.cleanupFiles ?? [])]) {
+			try {
+				rmSync(file, { force: true })
+			} catch {}
+		}
+	}
+
+	function readLogTail(): string {
+		if (!existsSync(config.logFile)) return ''
+		try {
+			const log = readFileSync(config.logFile, 'utf-8')
+			return log.slice(-LOG_TAIL_BYTES).trim()
+		} catch {
+			return ''
+		}
+	}
+
+	function spawnDaemon(): number {
+		mkdirSync(dirname(config.logFile), { recursive: true })
+		appendFileSync(config.logFile, `--- daemon start ${new Date().toISOString()}\n`)
+		const stdout = openSync(config.logFile, 'a')
+		const stderr = openSync(config.logFile, 'a')
+		try {
+			const child = Bun.spawn([...config.command], {
+				cwd: config.cwd ?? process.cwd(),
+				stdin: 'ignore',
+				stdout,
+				stderr,
+				detached: true,
+			})
+			child.unref()
+			mkdirSync(dirname(config.pidFile), { recursive: true })
+			writeFileSync(config.pidFile, `${child.pid}\n`)
+			return child.pid
+		} finally {
+			closeSync(stdout)
+			closeSync(stderr)
+		}
+	}
+
+	async function start(): Promise<DaemonHealthUp<H>> {
+		emit({ type: 'starting', command: config.command })
+		spawnDaemon()
+		const started = await pollHealthy(timeouts.start)
+		if (started.status === 'up') {
+			emit({ type: 'started', pid: started.pid })
+			return started
+		}
+		throw new DaemonStartError(
+			`Daemon did not become healthy within ${timeouts.start}ms.`,
+			config.logFile,
+			readLogTail(),
+		)
+	}
+
+	async function stop(): Promise<DaemonStopResult> {
+		const current = await health()
+
+		if (current.status === 'down') {
+			const stale = readPid()
+			if (stale === undefined) return { stopped: false, reason: 'not-running', message: 'Daemon is not running.' }
+			cleanupFiles()
+			return { stopped: false, pid: stale, reason: 'stale-pid', message: `Daemon is not running; removed stale pid ${stale}.` }
+		}
+
+		const pid = current.pid
+		if (pid === process.pid) {
+			return { stopped: false, pid, reason: 'refused-self', message: `Daemon pid ${pid} is this process; refusing to stop self.` }
+		}
+
+		try {
+			process.kill(pid, 'SIGTERM')
+		} catch {
+			cleanupFiles()
+			return { stopped: false, pid, reason: 'signal-failed', message: `Daemon pid ${pid} could not be signalled.` }
+		}
+
+		const deadline = Date.now() + timeouts.stop
+		while (Date.now() < deadline && (await health()).status === 'up') {
+			await sleep(100)
+		}
+		cleanupFiles()
+		emit({ type: 'stopped', pid })
+		return { stopped: true, pid, reason: 'stopped', message: `Stopped daemon pid ${pid}.` }
+	}
+
+	async function ensure(): Promise<DaemonHealthUp<H>> {
+		const current = await health()
+		if (current.status === 'up') {
+			const check = config.versionCheck
+			const running = check?.of(current)
+			if (check && running && running !== check.expected) {
+				emit({ type: 'version-mismatch', running, expected: check.expected })
+				await stop()
+				return await start()
+			}
+			return current
+		}
+
+		// Someone else may be mid-spawn: a live pid with no health yet is a daemon
+		// still booting, and racing it would put a second one on the same port.
+		const pid = readPid()
+		if (pid !== undefined && processIsAlive(pid)) {
+			const starting = await pollHealthy(timeouts.concurrentStart)
+			if (starting.status === 'up') return starting
+		}
+
+		return await start()
+	}
+
+	async function restart(): Promise<DaemonHealthUp<H>> {
+		await stop()
+		return await start()
+	}
+
+	return {
+		health,
+		async isRunning() {
+			return (await health()).status === 'up'
+		},
+		start,
+		ensure,
+		stop,
+		restart,
+	}
+}

package/src/router.ts

@@ -0,0 +1,16 @@
+export type RouteHandler = (req: Request, url: URL, match: URLPatternResult) => Response | Promise<Response>
+
+export interface Route {
+	method: string
+	pattern: URLPattern
+	handler: RouteHandler
+}
+
+export function dispatch(routes: Route[], req: Request, url: URL): Response | Promise<Response> | null {
+	for (const route of routes) {
+		if (route.method !== req.method) continue
+		const match = route.pattern.exec(url)
+		if (match) return route.handler(req, url, match)
+	}
+	return null
+}

package/src/waiter.ts

@@ -0,0 +1,188 @@
+/**
+ * The CLI half of the notification channel: connect to a daemon's wait socket
+ * and block until the host says the wait is over.
+ *
+ * What settles the wait is a host predicate, so one helper covers "feedback
+ * arrived", "screens confirmed" and "a run was requested". The socket factory
+ * is injectable, which is what makes the retry and settle logic testable
+ * without a live daemon.
+ */
+
+/** The slice of `WebSocket` a waiter uses; a real `WebSocket` satisfies it. */
+export interface WaiterSocket {
+	close(): void
+	onopen: ((event: Event) => void) | null
+	onmessage: ((event: MessageEvent) => void) | null
+	onerror: ((event: Event) => void) | null
+	onclose: ((event: CloseEvent) => void) | null
+}
+
+/** What a frame means to the waiter; `undefined` means "not mine, keep waiting". */
+export type WaitVerdict<T> =
+	| { type: 'settle'; value: T }
+	| { type: 'fail'; error: Error }
+	/** Wake the probe — the frame announces state the waiter has to read back. */
+	| { type: 'recheck' }
+
+export interface WaitMessages {
+	/** Deadline passed. Default: "Timed out waiting." */
+	timeout?: string
+	/** Socket closed before the wait settled. Default: "Connection closed before the wait settled." */
+	closed?: string
+	/** The socket errored. Default: "WebSocket connection failed." */
+	connectionFailed?: string
+	/**
+	 * `createSocket` threw, so no socket ever existed; the factory's own message
+	 * is appended after a colon. Default: "Could not create the WebSocket".
+	 */
+	socketCreateFailed?: string
+}
+
+export interface WaitOptions<T> {
+	/** The daemon's wait socket, e.g. `ws://localhost:19400/ws/wait/<topic>`. */
+	url: string
+	/** Reads a frame; returns how it settles the wait, if at all. */
+	onFrame(frame: unknown): WaitVerdict<T> | undefined
+	/**
+	 * Fast path against server state. Runs before connecting (unless the caller
+	 * already did that read — see `alreadyProbed`), again once the socket opens —
+	 * closing the race where the event lands between the two — and whenever a
+	 * frame asks for a recheck. A probe that rejects is dropped: the socket, not
+	 * the probe, is what the wait ultimately hangs on.
+	 */
+	probe?(): Promise<{ value: T } | undefined>
+	/**
+	 * The caller has already made the probe's read itself and it came up empty,
+	 * so the wait starts at the socket. Set it when that read is the caller's own
+	 * error channel — a probe that rejects is dropped here, so a caller that must
+	 * report *why* the read failed has to make it before calling. The on-open
+	 * re-read still runs; it is what closes the subscribe race.
+	 */
+	alreadyProbed?: boolean
+	createSocket?(url: string): WaiterSocket
+	/** Deadline for the whole wait, spanning reconnects. */
+	timeoutMs: number
+	reconnect?: {
+		/** Reconnects after a dropped connection. Default 0. */
+		attempts?: number
+		/** Delay before a reconnect, capped by the remaining deadline. Default 1000. */
+		delayMs?: number
+	}
+	messages?: WaitMessages
+}
+
+/** Why the wait ended without an answer; hosts map these onto their own errors. */
+export type WaitFailure =
+	| 'timeout'
+	| 'closed'
+	/** The socket was created, then errored. */
+	| 'connection-failed'
+	/** `createSocket` threw — nothing was ever connected to. */
+	| 'socket-create-failed'
+
+export class WaitError extends Error {
+	constructor(
+		message: string,
+		readonly reason: WaitFailure,
+		readonly retryable: boolean,
+		options?: ErrorOptions,
+	) {
+		super(message, options)
+		this.name = 'WaitError'
+	}
+}
+
+const DEFAULT_MESSAGES: Required<WaitMessages> = {
+	timeout: 'Timed out waiting.',
+	closed: 'Connection closed before the wait settled.',
+	connectionFailed: 'WebSocket connection failed.',
+	socketCreateFailed: 'Could not create the WebSocket',
+}
+
+function parseFrame(data: unknown): unknown {
+	if (typeof data !== 'string') return undefined
+	try {
+		return JSON.parse(data)
+	} catch {
+		return undefined
+	}
+}
+
+function connectAndWait<T>(
+	options: WaitOptions<T>,
+	createSocket: (url: string) => WaiterSocket,
+	messages: Required<WaitMessages>,
+	remainingMs: number,
+): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		let socket: WaiterSocket
+		try {
+			socket = createSocket(options.url)
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error)
+			const message = `${messages.socketCreateFailed}: ${detail}`
+			reject(new WaitError(message, 'socket-create-failed', true, { cause: error }))
+			return
+		}
+
+		let settled = false
+		// The value is wrapped so a settling `T` of any shape stays distinguishable.
+		const finish = (outcome: { value: T } | Error) => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			socket.close()
+			if (outcome instanceof Error) reject(outcome)
+			else resolve(outcome.value)
+		}
+
+		const timer = setTimeout(() => finish(new WaitError(messages.timeout, 'timeout', false)), remainingMs)
+
+		const runProbe = () => {
+			if (!options.probe) return
+			options.probe().then((result) => {
+				if (result) finish(result)
+			}).catch(() => {})
+		}
+
+		socket.onopen = () => runProbe()
+
+		socket.onmessage = (event) => {
+			const frame = parseFrame(event.data)
+			if (frame === undefined) return
+			const verdict = options.onFrame(frame)
+			if (!verdict) return
+			if (verdict.type === 'settle') finish({ value: verdict.value })
+			else if (verdict.type === 'fail') finish(verdict.error)
+			else runProbe()
+		}
+
+		socket.onerror = () => finish(new WaitError(messages.connectionFailed, 'connection-failed', true))
+		socket.onclose = () => finish(new WaitError(messages.closed, 'closed', true))
+	})
+}
+
+export async function waitForEvent<T>(options: WaitOptions<T>): Promise<T> {
+	const createSocket = options.createSocket ?? ((url: string) => new WebSocket(url))
+	const messages = { ...DEFAULT_MESSAGES, ...options.messages }
+	const attempts = options.reconnect?.attempts ?? 0
+	const delayMs = options.reconnect?.delayMs ?? 1_000
+	const deadline = Date.now() + options.timeoutMs
+
+	if (!options.alreadyProbed) {
+		const known = await options.probe?.().catch(() => undefined)
+		if (known) return known.value
+	}
+
+	for (let attempt = 0;; attempt++) {
+		const remainingMs = deadline - Date.now()
+		if (remainingMs <= 0) throw new WaitError(messages.timeout, 'timeout', false)
+
+		try {
+			return await connectAndWait(options, createSocket, messages, remainingMs)
+		} catch (error) {
+			if (!(error instanceof WaitError) || !error.retryable || attempt >= attempts) throw error
+			await Bun.sleep(Math.min(delayMs, Math.max(0, deadline - Date.now())))
+		}
+	}
+}