@abide/abide 0.28.0

package/src/controlServerWorker.ts

@@ -0,0 +1,426 @@
+import { mkdir } from 'node:fs/promises'
+import { bindConnectedFlag } from './lib/bundle/bindConnectedFlag.ts'
+import { bindRequestNavigate } from './lib/bundle/bindRequestNavigate.ts'
+import { listenLocalControlServer } from './lib/bundle/listenLocalControlServer.ts'
+import { probeAbideServer } from './lib/bundle/probeAbideServer.ts'
+import { resolveWebviewLib } from './lib/bundle/resolveWebviewLib.ts'
+import { spawnEmbeddedServer } from './lib/bundle/spawnEmbeddedServer.ts'
+import { stableLocalPort } from './lib/bundle/stableLocalPort.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+import { appDataDir } from './lib/shared/appDataDir.ts'
+import { binaryDirEnvPath } from './lib/shared/binaryDirEnvPath.ts'
+import { clearLastConnection } from './lib/shared/clearLastConnection.ts'
+import { createLivenessWatch } from './lib/shared/createLivenessWatch.ts'
+import { dataDirEnvPath } from './lib/shared/dataDirEnvPath.ts'
+import { readEnvFile } from './lib/shared/readEnvFile.ts'
+import { readLastConnection } from './lib/shared/readLastConnection.ts'
+import { serializeEnv } from './lib/shared/serializeEnv.ts'
+import { writeLastConnection } from './lib/shared/writeLastConnection.ts'
+
+/*
+The bundle's control server, run in a Worker so it owns its own thread.
+
+`webview_run` enters a native UI run loop that blocks the launcher's main thread
+indefinitely (the window owns it until close), which freezes the main thread's
+JS event loop. An in-process `Bun.serve` there can never answer a request, so the
+webview pointed at it would only ever see a hung navigation — a blank window.
+
+Running the control server on this Worker thread keeps it answering the whole time
+the window is open. It owns the pieces that must live beside it: the embedded
+server child it spawns, and its own FFI handle to the native menu flag (set here
+because the main thread can't process a postMessage while blocked in webview_run,
+yet the flag is a process-global the main-thread menu still reads).
+
+Bun does not apply the launcher build's plugins to a worker entry, so this module
+can't import abide's virtual modules (the connect-screen HTML, app title). The
+launcher — which can — passes them in the `init` message; on `shutdown` it has us
+reap the embedded child before the launcher exits.
+
+Once connected it also watches the chosen server's liveness — polling its identity
+endpoint — and, when it stops answering, corrects the menu flag and bounces the
+window back to the connect screen, since a dead server (local crash or remote
+outage) otherwise leaves a frozen page and a menu that still claims connected.
+
+  GET  /                   → the connect screen (title injected at serve time)
+  GET  /__abide/config     → { schema, values } for the first-run config form
+  POST /__abide/config     → persist the form's answers to the data-dir .env
+  POST /connect {url}      → record connected, reply { redirect: url }
+  POST /start              → spawn the server binary, reply { redirect: localUrl }
+  GET  /__abide/disconnect → reap the child, clear connected
+*/
+
+/*
+Init payload from the launcher, plus the per-run state the handlers close over.
+`configSchema` is the JSON Schema derived from the app's BundleWindow.config
+(undefined when none declared), driving the connect screen's first-run form.
+*/
+type Init = {
+    disconnectedHtml: string
+    title: string
+    programName: string
+    configSchema?: Record<string, unknown>
+}
+let disconnectedHtml = ''
+let title = ''
+let programName = ''
+let configSchema: Record<string, unknown> | undefined
+let flag: ReturnType<typeof bindConnectedFlag> | undefined
+let server: ReturnType<typeof listenLocalControlServer> | undefined
+
+// The control-server origin (where the connect screen lives) and the webview
+// handle, forwarded by the launcher — together they let the watch bounce a dead
+// window back to the connect screen.
+let controlOrigin = ''
+let navigate: ReturnType<typeof bindRequestNavigate> | undefined
+let webviewHandle: number | undefined
+
+/*
+Liveness watch over the currently-connected server: the shared state machine
+(createLivenessWatch) driven by the identity-endpoint probe — a couple of
+consecutive misses, tolerating a transient blip or a quick restart, count as
+a death. Stopped whenever we're not connected.
+*/
+const liveness = createLivenessWatch({
+    probe: async (url) => (await probeAbideServer(url)) !== undefined,
+    onLost: handleConnectionLost,
+})
+
+// Embedded-server child, spawned on demand by Start server; undefined when none.
+let serverChild: ReturnType<typeof Bun.spawn> | undefined
+
+// Reaps the embedded server child if one is running.
+function killServerChild(): void {
+    if (serverChild) {
+        serverChild.kill()
+        serverChild = undefined
+    }
+}
+
+/*
+Optional local-assistant bridge, tied to the connected app. Started only when the
+app bundled @abide/claude-code (its UI uses browser/assistant, so the dynamic
+import resolves — an app that doesn't is tolerated by --compile and no-ops) AND
+`claude` is on PATH. The page receives the loopback bridge's port+token through the
+webview URL fragment (withAssistant); no `claude` yields an `unavailable` fragment
+so the page shows an install hint instead of a run-this-command prompt. The bridge
+is loopback-only and torn down with the connection (stopLivenessWatch).
+*/
+let bridge: ReturnType<typeof import('@abide/claude-code/serve')['serve']> | undefined
+let assistantHandshake: string | undefined
+
+async function startBridge(url: string): Promise<void> {
+    const claude = await import('@abide/claude-code/serve').catch(() => undefined)
+    if (!claude) {
+        return
+    }
+    if (!Bun.which('claude')) {
+        assistantHandshake = 'unavailable'
+        return
+    }
+    const token = crypto.randomUUID()
+    const server = claude.serve({ url, allowOrigins: [url], token })
+    bridge = server
+    assistantHandshake = `${server.port}.${token}`
+}
+
+function stopBridge(): void {
+    bridge?.stop(true)
+    bridge = undefined
+    assistantHandshake = undefined
+}
+
+// Append the bridge handshake to a webview URL so the page's assistant() finds its port+token.
+function withAssistant(url: string): string {
+    return assistantHandshake ? `${url}#abide-assistant=${assistantHandshake}` : url
+}
+
+// Begin (or restart) watching `url` for liveness once the window points at it.
+function startLivenessWatch(url: string): void {
+    liveness.watch(url)
+}
+
+// Stop watching — on explicit disconnect, on detected death, or at shutdown.
+function stopLivenessWatch(): void {
+    liveness.stop()
+    // The assistant bridge follows the connection — drop it whenever we disconnect.
+    stopBridge()
+}
+
+/*
+The connected-state transition pair. Connected is three coordinated pieces —
+the native menu flag, the liveness watch, and the assistant bridge — that must
+move together; disconnected additionally reaps any embedded child. Every
+handler routes through these so no path can desync the menu or leave a bridge
+running against a dead server.
+*/
+async function becomeConnected(url: string): Promise<void> {
+    flag?.setConnected(true)
+    startLivenessWatch(url)
+    await startBridge(url)
+}
+
+function becomeDisconnected(): void {
+    stopLivenessWatch()
+    killServerChild()
+    flag?.setConnected(false)
+}
+
+/*
+The connected server stopped answering. Tear the connection down and bounce the
+window back to the connect screen with a `lost` notice. The flag flip alone keeps
+the menu honest even when the navigate is a no-op (off macOS, or no handle yet).
+*/
+function handleConnectionLost(url: string): void {
+    abideLog.warn(`connected server stopped responding: ${url}`)
+    becomeDisconnected()
+    if (webviewHandle !== undefined) {
+        navigate?.requestNavigate(webviewHandle, `${controlOrigin}/?action=lost`)
+    }
+}
+
+/*
+Boots the embedded server via the shared spawn helper and keeps the child so
+killServerChild can reap it. Any previous child is reaped first so only one
+embedded server runs at a time; returns the URL to point the window at.
+*/
+async function startEmbeddedServer(timeoutMs?: number): Promise<string> {
+    killServerChild()
+    const { url, child } = await spawnEmbeddedServer({ programName, timeoutMs })
+    serverChild = child
+    return url
+}
+
+/*
+Where the window should point on launch, resolved before it ever opens so the
+connect screen never flashes. Repeats the last connection from the launcher-owned
+record (which survives relaunch where the embedded server's fresh port can't):
+
+  - embedded, config complete → boot it and point at the live server
+  - embedded, config missing  → the connect screen, so the user can configure
+  - remote url, still alive   → point straight at it
+  - remote url, now dead       → the connect screen with a `lost` notice
+  - nothing recorded           → the connect screen
+
+Boot is bounded by a short ceiling: a failed or slow boot falls back to the
+connect screen rather than leaving the launcher window-less, and reaps the child
+so a half-started server doesn't hold its port.
+*/
+const AUTO_START_CEILING_MS = 3000
+async function resolveLaunchTarget(): Promise<string> {
+    const last = await readLastConnection(programName)
+    if (!last) {
+        return controlOrigin
+    }
+    if (last.kind === 'embedded') {
+        if (await autoStartBlockedByConfig()) {
+            return controlOrigin
+        }
+        try {
+            const url = await startEmbeddedServer(AUTO_START_CEILING_MS)
+            await becomeConnected(url)
+            abideLog.info(`resumed embedded server at ${url}`)
+            return url
+        } catch (error) {
+            killServerChild()
+            abideLog.warn(`embedded server did not resume: ${String(error)}`)
+            return controlOrigin
+        }
+    }
+    const identity = await probeAbideServer(last.url)
+    if (identity) {
+        await becomeConnected(last.url)
+        abideLog.info(`reconnected to ${identity.name} at ${last.url}`)
+        return last.url
+    }
+    abideLog.warn(`saved server did not respond: ${last.url}`)
+    return `${controlOrigin}/?action=lost`
+}
+
+// True when the app declares required config that nothing yet supplies, so an
+// embedded auto-start would only crash for the lack of it — land on the connect
+// screen (and its setup modal) instead.
+async function autoStartBlockedByConfig(): Promise<boolean> {
+    const required = (configSchema?.required as string[] | undefined) ?? []
+    if (required.length === 0) {
+        return false
+    }
+    const values = await resolveConfigValues()
+    return required.some((key) => !values[key])
+}
+
+/*
+Injects the app title into the connect-screen HTML just before serving — the build
+left a `<!--abide:connect-config-->` marker in <head>.
+*/
+function renderConnectScreen(): Response {
+    const script = `<script>window.__ABIDE_TITLE__=${JSON.stringify(title)}</script>`
+    const html = disconnectedHtml.replace('<!--abide:connect-config-->', script)
+    return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } })
+}
+
+/*
+Resolves the value to pre-fill each config field with, following the same
+precedence the server applies below the shell: the user's saved data-dir `.env`,
+then the bundle's shipped binary-dir `.env`, then the schema's own `default`.
+Empty string when nothing supplies it — which is how the form spots an unmet
+required field.
+*/
+async function resolveConfigValues(): Promise<Record<string, string>> {
+    const properties = (configSchema?.properties ?? {}) as Record<string, { default?: unknown }>
+    // Independent reads — fetch together; precedence is applied in the merge below.
+    const [dataDirEnv, binaryDirEnv] = await Promise.all([
+        readEnvFile(dataDirEnvPath(programName)),
+        readEnvFile(binaryDirEnvPath()),
+    ])
+    return Object.fromEntries(
+        Object.keys(properties).map((key) => {
+            const fallback = properties[key]?.default
+            const value =
+                dataDirEnv[key] ??
+                binaryDirEnv[key] ??
+                (fallback === undefined ? '' : String(fallback))
+            return [key, value]
+        }),
+    )
+}
+
+/*
+Persists the form's answers to the data-dir `.env`, merged over any existing
+file so keys the form didn't touch survive. Creates the data dir on first run
+(appDataDir only computes the path).
+*/
+async function writeConfig(values: Record<string, string>): Promise<void> {
+    const path = dataDirEnvPath(programName)
+    const merged = { ...(await readEnvFile(path)), ...values }
+    await mkdir(appDataDir(programName), { recursive: true })
+    await Bun.write(path, serializeEnv(merged))
+}
+
+// GET /__abide/config — the form's schema + current values, or null schema to skip the gate.
+async function handleConfigGet(): Promise<Response> {
+    if (!configSchema) {
+        return Response.json({ schema: null, values: {} })
+    }
+    return Response.json({ schema: configSchema, values: await resolveConfigValues() })
+}
+
+// POST /__abide/config — persist the form's answers to the data-dir `.env`.
+async function handleConfigPost(request: Request): Promise<Response> {
+    const { values } = (await request.json()) as { values: Record<string, string> }
+    await writeConfig(values)
+    return new Response(undefined, { status: 204 })
+}
+
+// POST /connect — point the window at a remote abide server after probing it.
+async function handleConnect(request: Request): Promise<Response> {
+    const { url: target } = (await request.json()) as { url: string }
+    // Verify it's actually a abide server before pointing the window at it.
+    const identity = await probeAbideServer(target)
+    if (!identity) {
+        abideLog.warn(`no abide server responded at ${target}`)
+        return Response.json({ error: `No abide server responded at ${target}` }, { status: 502 })
+    }
+    await becomeConnected(target)
+    // Record the choice so the next launch reconnects here before opening.
+    await writeLastConnection(programName, { kind: 'url', url: target })
+    abideLog.info(`connecting to ${identity.name} at ${target}`)
+    return Response.json({ redirect: withAssistant(target) })
+}
+
+// POST /start — boot the embedded server and point the window at it.
+async function handleStart(): Promise<Response> {
+    try {
+        const localUrl = await startEmbeddedServer()
+        await becomeConnected(localUrl)
+        // Record the choice so the next launch boots the embedded server first.
+        await writeLastConnection(programName, { kind: 'embedded' })
+        abideLog.info(`started embedded server at ${localUrl}`)
+        return Response.json({ redirect: withAssistant(localUrl) })
+    } catch (error) {
+        killServerChild()
+        return Response.json({ error: String(error) }, { status: 500 })
+    }
+}
+
+// GET /__abide/disconnect — tear down the embedded server and forget the auto-resume choice.
+async function handleDisconnect(): Promise<Response> {
+    becomeDisconnected()
+    await clearLastConnection(programName)
+    return new Response(undefined, { status: 204 })
+}
+
+/*
+The control server's routes, keyed by `${method} ${pathname}` (exact match). The
+connect screen owns localStorage + navigation; this worker owns the embedded-
+server process and the native flag.
+*/
+const controlRoutes: Record<string, (request: Request) => Promise<Response> | Response> = {
+    'GET /': () => renderConnectScreen(),
+    'GET /__abide/config': handleConfigGet,
+    'POST /__abide/config': handleConfigPost,
+    'POST /connect': handleConnect,
+    'POST /start': handleStart,
+    'GET /__abide/disconnect': handleDisconnect,
+}
+
+function handleControlRequest(request: Request): Promise<Response> | Response {
+    const { pathname } = new URL(request.url)
+    const route = controlRoutes[`${request.method} ${pathname}`]
+    return route ? route(request) : new Response('not found', { status: 404 })
+}
+
+/*
+Bind the control server to 127.0.0.1 literally (not `localhost`) so the webview
+reaches it without any IPv4/IPv6 name-resolution ambiguity, open the native flag
+handle, then resolve where the window should open before handing back. Resolving
+the launch target here — booting/probing the last connection before `ready` — is
+what lets the launcher open the window straight at the live server, so the
+connect screen never flashes; only an unconfigured, failed, or absent resume
+falls back to it. The launcher gets both `origin` (for the File-menu actions) and
+`target` (where to point the window now).
+*/
+async function start(init: Init): Promise<void> {
+    disconnectedHtml = init.disconnectedHtml
+    title = init.title
+    programName = init.programName
+    configSchema = init.configSchema
+    const libPath = await resolveWebviewLib()
+    flag = bindConnectedFlag(libPath)
+    navigate = bindRequestNavigate(libPath)
+    server = listenLocalControlServer(stableLocalPort(init.programName), handleControlRequest)
+    controlOrigin = `http://127.0.0.1:${server.port}`
+    abideLog.info(`${title} control server listening at ${controlOrigin}`)
+    const target = await resolveLaunchTarget()
+    // Fold in the assistant handshake (when a bridge started) so the page is configured on first load.
+    self.postMessage({ type: 'ready', origin: controlOrigin, target: withAssistant(target) })
+}
+
+// Reap the child + release the server and FFI handles, then confirm so the
+// launcher can exit cleanly.
+function shutdown(): void {
+    stopLivenessWatch()
+    killServerChild()
+    server?.stop(true)
+    flag?.close()
+    navigate?.close()
+    self.postMessage({ type: 'shutdownDone' })
+}
+
+/*
+The launcher drives the lifecycle: `init` (with the data this worker can't import)
+starts the server, `window` forwards the webview handle the liveness watch needs to
+navigate, and `shutdown` tears it all down once the window closes.
+*/
+self.addEventListener('message', (event: MessageEvent) => {
+    const data = event.data as
+        | { type: 'init'; init: Init }
+        | { type: 'window'; handle: number }
+        | { type: 'shutdown' }
+    if (data.type === 'init') {
+        void start(data.init)
+    } else if (data.type === 'window') {
+        webviewHandle = data.handle
+    } else if (data.type === 'shutdown') {
+        shutdown()
+    }
+})

package/src/devEntry.ts

@@ -0,0 +1,250 @@
+import { watch } from 'node:fs'
+import type { Subprocess } from 'bun'
+import { build } from './build.ts'
+import { DEFAULT_PORT } from './lib/server/runtime/DEFAULT_PORT.ts'
+import { DEV_READY_MESSAGE } from './lib/server/runtime/DEV_READY_MESSAGE.ts'
+import { DEV_REBUILD_MESSAGE } from './lib/server/runtime/DEV_REBUILD_MESSAGE.ts'
+import { findOpenPort } from './lib/server/runtime/findOpenPort.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+
+/*
+Dev orchestrator. Replaces `bun --watch` (which only watches the import graph,
+so new files / CSS / public assets never triggered a restart) with an explicit
+loop we own end to end:
+
+  1. Build the client once — uncompressed, unminified (compressing on every
+     rebuild dwarfs the bundle; the server serves the plain bytes when no .gz exists).
+  2. Spawn the server as a child against a fixed dev port and ABIDE_DEV=1, which
+     makes it mount the /__abide/dev live-reload channel.
+  3. Watch src/ recursively. On any change, rebuild then swap the worker: the
+     replacement boots alongside the incumbent (both bind the port via
+     reusePort) and the incumbent is retired only once the replacement reports
+     ready over IPC — the port keeps answering across the whole restart. SSR
+     renders pages through Bun's module cache, so a fresh module graph (a new
+     process) is the reliable way to reflect a source edit — Bun has no stable
+     in-process invalidation. Killing the incumbent drops the browser's
+     live-reload channel; it reconnects straight onto the already-listening
+     replacement and reloads itself.
+
+Restarts are serialized (a build mid-flight queues the next) and the port is
+fixed so the browser tab stays valid across restarts. A failed build — or a
+replacement that dies or hangs while booting — keeps the last-good server
+running rather than tearing the loop down. A worker that crashes while active
+is respawned, bounded so a boot-time crash loop gives up and waits for a save.
+*/
+const cwd = process.cwd()
+const PRELOAD = new URL('./preload.ts', import.meta.url).pathname
+const SERVER_ENTRY = new URL('./serverEntry.ts', import.meta.url).pathname
+const SOURCE_DIR = `${cwd}/src`
+// Coalesce editor save bursts (and multi-file saves) into one rebuild.
+const REBUILD_DEBOUNCE_MS = 60
+// How long a booting replacement gets to report ready before it is discarded.
+const READY_TIMEOUT_MS = 30000
+// Consecutive worker exits with no ready signal in between before the
+// crash-respawn loop gives up and waits for the next save.
+const MAX_EXITS_WITHOUT_READY = 3
+/*
+Generated dir the build itself writes into src/ (route type declarations). It
+must be ignored or each rebuild's write retriggers the watcher — an endless
+rebuild loop.
+*/
+const GENERATED_DIR = '.abide'
+
+// True for paths under src/.abide (the build's own generated output).
+function isGenerated(filename: string): boolean {
+    return filename.split(/[\\/]/).includes(GENERATED_DIR)
+}
+
+// clean:false leaves the live dist in place — each build swaps _app in atomically,
+// so the running server never serves a half-built or emptied bundle.
+const buildOptions = {
+    cwd,
+    minify: false,
+    compress: false,
+    clean: false,
+    exitOnFailure: false,
+} as const
+
+// The worker currently meant to be serving; undefined while crashed or replaced.
+let server: Subprocess | undefined
+let shuttingDown = false
+// Worker exits since the last ready signal — bounds the crash-respawn loop.
+let exitsWithoutReady = 0
+
+/*
+Spawn a server worker against the fixed dev port. `ready` resolves when the
+worker reports its listener is up and init() has run (DEV_READY_MESSAGE) — the
+cue that a replacement may retire its predecessor.
+*/
+function spawnWorker(port: number): { proc: Subprocess; ready: Promise<void> } {
+    const readiness = Promise.withResolvers<void>()
+    const proc = Bun.spawn({
+        cmd: ['bun', '--preload', PRELOAD, SERVER_ENTRY],
+        cwd,
+        env: { ...process.env, PORT: String(port), ABIDE_DEV: '1' },
+        stdio: ['inherit', 'inherit', 'inherit'],
+        // The child's POST /__abide/reload route signals a rebuild over IPC, so the
+        // trigger rides the app's own port instead of a side channel.
+        ipc(message) {
+            if (message === DEV_REBUILD_MESSAGE) {
+                void rebuild(port)
+            }
+            if (message === DEV_READY_MESSAGE) {
+                exitsWithoutReady = 0
+                readiness.resolve()
+            }
+        },
+    })
+    respawnOnUnexpectedExit(proc, port)
+    return { proc, ready: readiness.promise }
+}
+
+/*
+A worker that dies while it is the active server — an app crash, not a swap or
+shutdown — used to leave the port dead until a manual restart. Respawn it,
+giving up after MAX_EXITS_WITHOUT_READY exits in a row so a crash-on-boot
+doesn't spin; the next save retries through rebuild.
+*/
+function respawnOnUnexpectedExit(proc: Subprocess, port: number): void {
+    void proc.exited.then((exitCode) => {
+        if (shuttingDown || server !== proc) {
+            return
+        }
+        server = undefined
+        exitsWithoutReady += 1
+        if (exitsWithoutReady >= MAX_EXITS_WITHOUT_READY) {
+            abideLog.warn(
+                `server keeps exiting (code ${exitCode}) — fix the error and save to retry`,
+            )
+            return
+        }
+        abideLog.warn(`server exited unexpectedly (code ${exitCode}) — restarting`)
+        server = spawnWorker(port).proc
+    })
+}
+
+/* Terminate a worker and wait for it to exit (SIGKILL watchdog for a wedged exit). */
+async function stopWorker(proc: Subprocess): Promise<void> {
+    proc.kill()
+    const watchdog = setTimeout(() => proc.kill('SIGKILL'), 3000)
+    await proc.exited
+    clearTimeout(watchdog)
+}
+
+/*
+Zero-downtime swap. The replacement overlaps the incumbent — both bind the dev
+port via reusePort (see createServer) and the kernel keeps delivering
+connections to the incumbent until it stops — so the port answers throughout
+the new module graph's boot. Only a replacement that reports ready retires the
+incumbent; one that dies or hangs booting is discarded and the last-good server
+keeps serving, mirroring how a failed build is handled.
+*/
+async function replaceServer(port: number): Promise<void> {
+    const previous = server
+    const next = spawnWorker(port)
+    const outcome = await Promise.race([
+        next.ready.then(() => 'ready' as const),
+        next.proc.exited.then(() => 'exited' as const),
+        Bun.sleep(READY_TIMEOUT_MS).then(() => 'timeout' as const),
+    ])
+    if (outcome !== 'ready') {
+        if (outcome === 'timeout') {
+            await stopWorker(next.proc)
+        }
+        abideLog.warn('new server failed to boot — the previous one (if any) keeps serving')
+        return
+    }
+    server = next.proc
+    if (previous) {
+        await stopWorker(previous)
+    }
+}
+
+let building = false
+let queued = false
+
+/*
+Rebuild the client, then (on success) swap in a fresh server child. Serialized:
+a change arriving mid-build sets `queued` so exactly one more rebuild runs
+after, collapsing any further changes in between. A failed build leaves the
+current child untouched — the error is logged and the last-good server keeps
+serving.
+*/
+async function rebuild(port: number): Promise<void> {
+    if (building) {
+        queued = true
+        return
+    }
+    building = true
+    try {
+        const succeeded = await build(buildOptions)
+        if (succeeded) {
+            await replaceServer(port)
+        }
+    } finally {
+        building = false
+        if (queued) {
+            queued = false
+            void rebuild(port)
+        }
+    }
+}
+
+/*
+Pick a free port once and reuse it for every restart, so the browser tab keeps
+pointing at the same address. Scans upward from the shared default so dev lands
+on the same predictable 3000+ address as `bun start`; reusing the number across
+restarts (not re-scanning) is what keeps the tab valid.
+*/
+const port = findOpenPort(DEFAULT_PORT)
+const firstBuild = await build(buildOptions)
+if (!firstBuild) {
+    abideLog.warn('initial build failed — fix the error and save to retry')
+}
+server = spawnWorker(port).proc
+
+/*
+ABIDE_DEV_NO_WATCH=1 skips the fs watcher: rebuild only on demand via POST
+/__abide/reload (always mounted under dev), so a long-lived in-process job — e.g.
+an agent editing the app's own source — isn't yanked mid-run by a save.
+*/
+const manualRebuild = Bun.env.ABIDE_DEV_NO_WATCH === '1'
+
+let debounce: ReturnType<typeof setTimeout> | undefined
+const watcher = manualRebuild
+    ? undefined
+    : watch(SOURCE_DIR, { recursive: true }, (_event, filename) => {
+          if (!filename || isGenerated(filename)) {
+              return
+          }
+          clearTimeout(debounce)
+          debounce = setTimeout(() => void rebuild(port), REBUILD_DEBOUNCE_MS)
+      })
+if (manualRebuild) {
+    abideLog.info(
+        `manual rebuild mode — POST http://localhost:${port}/__abide/reload to apply changes`,
+    )
+}
+
+/* Tear down the watcher and the child on shutdown so neither outlives the orchestrator. */
+const shutdown = async () => {
+    shuttingDown = true
+    watcher?.close()
+    if (server) {
+        await stopWorker(server)
+    }
+    process.exit(0)
+}
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)
+process.on('SIGHUP', shutdown)
+
+/*
+Last-resort sync cleanup: Bun.spawn'd children aren't reaped when the parent
+dies, so a crash (uncaught error, terminal close) would otherwise leave the
+server holding the dev port. 'exit' fires for every exit path; kill is
+synchronous, which is enough to signal the child before we go.
+*/
+process.on('exit', () => {
+    server?.kill()
+})