@nanobpm/urban 0.12.0 → 0.13.0

package/dist/cli.js

@@ -4,12 +4,12 @@
 //   urban check          load + validate the manifest, report issues
 //   urban gen            derive generated artifacts (migrations, worker I/O)
 //   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
-//   urban dev            like run (hot-reload is not yet implemented; documented below)
+//   urban dev            like run, plus watch sources and hot-reload on change
 //   urban deploy         deploy models only, then exit
 //
 // Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
 //               --port <n>, -h/--help, -v/--version.
-import { collectManifestIssues, loadManifest, runFromEnv, selectHost, } from "./runtime/index.js";
+import { collectManifestIssues, installSignalHandlers, loadManifest, runDev, runFromEnv, selectHost, } from "./runtime/index.js";
 import { scaffold, slugify } from "create-urban-app";
 import { createNodeGenIO, runGen } from "./toolkit/index.js";
 import { pathToFileURL } from "node:url";
@@ -72,7 +72,7 @@ Usage:
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban run                         materialize + serve the app
-  urban dev                         run (hot-reload not yet implemented)
+  urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
 
 Global flags:
@@ -128,6 +128,11 @@ async function cmdRun(f, mount) {
     console.log(`▲ ${info.name} — surfaces on :${info.httpPort ?? "n/a"} (Ctrl-C to stop)`);
     return -1; // keep the process alive; signal handlers stop it
 }
+async function cmdDev(f) {
+    const dev = await runDev({ root: f.root, manifestPath: f.manifest, port: f.port });
+    installSignalHandlers(() => dev.stop());
+    return -1; // keep the process alive; signal handlers stop the dev server
+}
 async function cmdDeploy(f) {
     const app = await runFromEnv({
         root: f.root,
@@ -183,8 +188,7 @@ export async function main(argv) {
         case "run":
             return cmdRun(f);
         case "dev":
-            console.log("urban dev: hot-reload is not yet implemented; running once.");
-            return cmdRun(f);
+            return cmdDev(f);
         case "deploy":
             return cmdDeploy(f);
         default:

package/dist/runtime/adapters/deno.d.ts

@@ -2,5 +2,7 @@ import type { HostContext } from "../core/host.ts";
 export interface DenoHostOptions {
     cwd?: string;
     log?: HostContext["log"];
+    /** See NodeHostOptions.importNonce — appended as `?v=<nonce>` to dynamic imports. */
+    importNonce?: string;
 }
 export declare function createDenoHost(opts?: DenoHostOptions): HostContext;

package/dist/runtime/adapters/deno.js

@@ -51,10 +51,42 @@ export function createDenoHost(opts = {}) {
             const db = new DatabaseSync(abs(path));
             return wrapSqlite(db);
         },
-        importModule: (p) => import(__rewriteRelativeImportExtension(pathToFileURL(abs(p)).href)),
+        importModule: (p) => {
+            const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+            return import(__rewriteRelativeImportExtension(href));
+        },
         async serveHttp(port, handler) {
             return startDenoServer(port, handler);
         },
+        watch(onChange) {
+            const w = Deno.watchFs(cwd, { recursive: true });
+            let closed = false;
+            (async () => {
+                try {
+                    for await (const ev of w) {
+                        for (const p of ev.paths)
+                            onChange(p);
+                    }
+                }
+                catch (err) {
+                    // Deno.watchFs throws when close() is called mid-await — expected on shutdown.
+                    // Any other failure (permissions, path removed, …) silently disables hot reload,
+                    // so surface it instead of swallowing it.
+                    if (!closed)
+                        log("warn", "file watch error — hot reload may be disabled", {
+                            error: String(err),
+                        });
+                }
+            })();
+            return {
+                close: () => {
+                    if (closed)
+                        return;
+                    closed = true;
+                    w.close();
+                },
+            };
+        },
         now: () => Date.now(),
         log,
     };

package/dist/runtime/adapters/detect.d.ts

@@ -4,6 +4,8 @@ export declare function isDeno(): boolean;
 export interface SelectHostOptions {
     cwd?: string;
     log?: HostContext["log"];
+    /** Dev-only import-cache-busting nonce; forwarded to the chosen adapter. */
+    importNonce?: string;
 }
 /** Select and construct the host for the current runtime. */
 export declare function selectHost(opts?: SelectHostOptions): HostContext;

package/dist/runtime/adapters/node.d.ts

@@ -3,5 +3,11 @@ export interface NodeHostOptions {
     /** Base directory relative paths resolve against. Default process.cwd(). */
     cwd?: string;
     log?: HostContext["log"];
+    /**
+     * When set, appended as a `?v=<nonce>` query to dynamic import URLs so a changed
+     * handler/worker module is re-evaluated instead of served from the ESM cache. The
+     * dev server bumps this on every reload; production leaves it unset.
+     */
+    importNonce?: string;
 }
 export declare function createNodeHost(opts?: NodeHostOptions): HostContext;

package/dist/runtime/adapters/node.js

@@ -9,6 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { readFile, readdir, stat } from "node:fs/promises";
+import { watch as fsWatch } from "node:fs";
 import { createServer } from "node:http";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -47,10 +48,36 @@ export function createNodeHost(opts = {}) {
             const db = new DatabaseSync(abs(path));
             return wrapNodeSqlite(db);
         },
-        importModule: (p) => import(__rewriteRelativeImportExtension(pathToFileURL(abs(p)).href)),
+        importModule: (p) => {
+            const href = pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+            return import(__rewriteRelativeImportExtension(href));
+        },
         async serveHttp(port, handler) {
             return await startNodeServer(port, handler);
         },
+        watch(onChange) {
+            const onFsEvent = (_event, filename) => {
+                if (filename)
+                    onChange(String(filename));
+            };
+            // Recursive watch is supported on macOS, Windows, and — since Node 19.1.0 — Linux.
+            // This package requires Node >=22.6, so the recursive path is available on all three;
+            // the try/catch only trips on an unusual platform, where we degrade honestly to a
+            // non-recursive root watch (and warn) rather than silently miss nested changes.
+            let w;
+            try {
+                w = fsWatch(cwd, { recursive: true }, onFsEvent);
+            }
+            catch (err) {
+                log("warn", "recursive file watch unavailable — nested changes may be missed", {
+                    error: String(err),
+                });
+                w = fsWatch(cwd, onFsEvent);
+            }
+            // A watcher error (e.g. the dir is removed) must not crash the dev server.
+            w.on("error", (err) => log("warn", "file watch error", { error: String(err) }));
+            return { close: () => w.close() };
+        },
         now: () => Date.now(),
         log,
     };

package/dist/runtime/core/host.d.ts

@@ -21,6 +21,10 @@ export interface HttpServer {
     readonly port: number;
     stop(): Promise<void>;
 }
+/** A handle to an active filesystem watch; call close() to stop watching. */
+export interface WatchHandle {
+    close(): void;
+}
 /** A tiny synchronous SQLite handle — the subset the runtime needs. */
 export interface SqliteDb {
     /** Execute one or more statements with no result (DDL, PRAGMA, migrations). */
@@ -58,6 +62,13 @@ export interface HostContext {
     importModule(path: string): Promise<Record<string, unknown>>;
     /** Start an HTTP server. Routing is done by the caller inside `handler`. */
     serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
+    /**
+     * Recursively watch the app root for file changes, invoking `onChange` with the
+     * changed path (app-root-relative when the runtime reports it that way). Optional:
+     * hosts that cannot watch omit it, and callers fall back to run-once. Returns a
+     * handle whose close() stops watching.
+     */
+    watch?(onChange: (path: string) => void): WatchHandle;
     /** Current wall-clock time in ms since epoch (seam for tests). */
     now(): number;
     /** Structured log sink. */

package/dist/runtime/devserver.d.ts

@@ -0,0 +1,36 @@
+import type { HostContext } from "./core/host.ts";
+import type { UrbanApp } from "./core/runtime.ts";
+/** True when a changed path should trigger a dev reload. Pure, so it is unit-tested.
+ *  `manifestFile` (the app's configured manifest, default nano.app.json) always triggers,
+ *  so `urban dev --manifest other.json` reloads on edits to that file too. */
+export declare function shouldReload(rawPath: string, manifestFile?: string): boolean;
+export interface DevOptions {
+    root?: string;
+    manifestPath?: string;
+    port?: number;
+    /** Quiet-period after the last change before reloading, in ms. Default 150. */
+    debounceMs?: number;
+    /** Log sink (default console.log). */
+    log?: (msg: string) => void;
+}
+/** Injectable seams so the loop is testable without a live engine or filesystem. */
+export interface DevDeps {
+    makeHost(nonce: string): HostContext;
+    startApp(host: HostContext, o: {
+        manifestPath: string;
+        port?: number;
+    }): Promise<UrbanApp>;
+    regenerate(root: string, manifestFile: string): Promise<{
+        count: number;
+    }>;
+    now(): number;
+}
+export interface DevServer {
+    stop(): Promise<void>;
+}
+/**
+ * Start the dev server: gen once, start the app, then watch + hot-reload. Returns a handle
+ * whose stop() tears the watcher and the running app down. Never rejects on a reload error —
+ * a bad edit logs and leaves the previous app running.
+ */
+export declare function runDev(opts?: DevOptions, deps?: Partial<DevDeps>): Promise<DevServer>;

package/dist/runtime/devserver.js

@@ -0,0 +1,173 @@
+// `urban dev` — a hot-reload dev server. It runs the derivers once, starts the app, then
+// watches the app root and, on a relevant source change, regenerates artifacts and restarts
+// the app in-process. A per-reload import nonce busts the module cache so changed worker/
+// action handlers are re-evaluated. main.ts is NOT re-run in dev (the CLI drives the runtime
+// directly), so main.ts edits don't need a reload.
+//
+// The reload strategy is a full in-process restart: regenerate + build a fresh host, then
+// stop the old app and start the new one. Regenerating first means a bad edit (invalid
+// manifest/model) fails before the running app is torn down, so it keeps serving. It is the
+// same start path as a fresh `urban run`, so every change kind — manifest, BPMN/DMN, forms,
+// migrations/types, worker code — is picked up. A finer-grained surface remount + browser
+// live-reload can layer on later behind this same seam.
+import { runFromEnv } from "./run.js";
+import { selectHost } from "./adapters/detect.js";
+import { createNodeGenIO, runGen } from "../toolkit/index.js";
+const SOURCE_EXT = [".bpmn", ".dmn", ".form", ".ts", ".js", ".mjs", ".sql"];
+// Directories whose churn must never trigger a reload: generated output (gen writes here —
+// watching it would loop forever), dependencies, VCS, and build output.
+const IGNORE_SEGMENTS = ["nano-generated", "node_modules", ".git", "dist"];
+/** True when a changed path should trigger a dev reload. Pure, so it is unit-tested.
+ *  `manifestFile` (the app's configured manifest, default nano.app.json) always triggers,
+ *  so `urban dev --manifest other.json` reloads on edits to that file too. */
+export function shouldReload(rawPath, manifestFile = "nano.app.json") {
+    const norm = (s) => s.replace(/\\/g, "/").replace(/^\.\//, "");
+    const p = norm(rawPath);
+    if (p === "")
+        return false;
+    for (const seg of IGNORE_SEGMENTS) {
+        if (p === seg || p.startsWith(`${seg}/`) || p.includes(`/${seg}/`))
+            return false;
+    }
+    // Ignore SQLite database files and their WAL/SHM/journal sidecars — they change on every
+    // write and would otherwise wedge the server in a reload loop.
+    if (/\.(db|sqlite|sqlite3)(-wal|-shm|-journal)?$/i.test(p))
+        return false;
+    const mf = norm(manifestFile);
+    const base = p.slice(p.lastIndexOf("/") + 1);
+    if (p === mf || base === mf.slice(mf.lastIndexOf("/") + 1))
+        return true;
+    return SOURCE_EXT.some((e) => p.toLowerCase().endsWith(e));
+}
+function defaultDeps(root) {
+    return {
+        makeHost: (nonce) => selectHost({ cwd: root, importNonce: nonce }),
+        startApp: (host, o) => 
+        // The host is anchored at `root`; runFromEnv keeps its own root at "." accordingly.
+        runFromEnv({ host, manifestPath: o.manifestPath, port: o.port, handleSignals: false }),
+        regenerate: async (r, mf) => {
+            const res = await runGen({ root: r, io: createNodeGenIO(), manifestFile: mf });
+            return { count: res.artifacts.length };
+        },
+        now: () => Date.now(),
+    };
+}
+/**
+ * Start the dev server: gen once, start the app, then watch + hot-reload. Returns a handle
+ * whose stop() tears the watcher and the running app down. Never rejects on a reload error —
+ * a bad edit logs and leaves the previous app running.
+ */
+export async function runDev(opts = {}, deps) {
+    const root = opts.root ?? ".";
+    const manifestFile = opts.manifestPath ?? "nano.app.json";
+    const debounceMs = opts.debounceMs ?? 150;
+    const log = opts.log ?? ((m) => console.log(m));
+    const d = { ...defaultDeps(root), ...deps };
+    // Monotonic reload counter, mixed into the import nonce so it is unique per reload even when
+    // two reloads land in the same millisecond (d.now() can repeat).
+    let reloadSeq = 0;
+    const startCycle = async () => {
+        const host = await prepareHost();
+        const app = await d.startApp(host, { manifestPath: manifestFile, port: opts.port });
+        return { host, app };
+    };
+    // Derive artifacts and build a fresh host (with a new import nonce). This is pure/FS work
+    // that does NOT touch the running app, so it can run *before* a reload tears the old app
+    // down — most bad edits (invalid manifest/model) fail here, leaving the app serving.
+    const prepareHost = async () => {
+        const nonce = `${d.now()}-${reloadSeq++}`;
+        const { count } = await d.regenerate(root, manifestFile);
+        if (count > 0)
+            log(`  derived ${count} artifact(s)`);
+        return d.makeHost(nonce);
+    };
+    let { host, app } = await startCycle();
+    let reloading = false;
+    let queued = false;
+    let stopped = false;
+    let appRunning = true;
+    let inFlight;
+    let timer;
+    const reload = async () => {
+        try {
+            log("↻ change detected — reloading…");
+            // Regenerate + rebuild the host BEFORE stopping the running app, so a bad edit
+            // throws here and the current app keeps serving untouched.
+            const nextHost = await prepareHost();
+            if (stopped)
+                return; // shutdown began mid-prepare: leave the running app to stop()
+            await app.stop();
+            appRunning = false;
+            // Re-check after the async stop: if shutdown began while we were tearing the old
+            // app down, don't start a replacement just to have stop() immediately kill it.
+            if (stopped)
+                return;
+            app = await d.startApp(nextHost, { manifestPath: manifestFile, port: opts.port });
+            appRunning = true;
+            host = nextHost;
+            log("✔ reloaded");
+        }
+        catch (err) {
+            // Keep the dev server alive on a bad edit; the next save will retry.
+            log(`✖ reload failed: ${String(err?.message ?? err)}`);
+        }
+        finally {
+            reloading = false;
+            if (queued && !stopped) {
+                queued = false;
+                schedule();
+            }
+        }
+    };
+    // Owns the single-flight guard and `inFlight` bookkeeping: only an *actually running*
+    // reload is tracked in `inFlight`, so stop() always awaits the real in-flight reload
+    // (never an already-resolved no-op promise) before final teardown.
+    const trigger = () => {
+        if (stopped)
+            return;
+        if (reloading) {
+            queued = true; // the active reload's finally re-schedules the next cycle
+            return;
+        }
+        reloading = true;
+        inFlight = reload();
+    };
+    const schedule = () => {
+        if (stopped)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            trigger();
+        }, debounceMs);
+    };
+    let watcher;
+    if (host.watch) {
+        watcher = host.watch((path) => {
+            if (shouldReload(path, manifestFile))
+                schedule();
+        });
+        log("▲ dev server ready — watching for changes (Ctrl-C to stop)");
+    }
+    else {
+        log("▲ dev server ready — file watching is not supported on this host; running once " +
+            "(no hot reload, Ctrl-C to stop)");
+    }
+    return {
+        async stop() {
+            // Order matters: flag first so a queued/in-flight reload won't start a new app, cancel
+            // any pending debounce, stop watching, then let any in-flight reload settle before the
+            // final teardown so we stop exactly the app that is (or ends up) current.
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            watcher?.close();
+            await inFlight?.catch(() => { });
+            if (appRunning)
+                await app.stop();
+        },
+    };
+}

package/dist/runtime/index.d.ts

@@ -4,7 +4,7 @@ export { expandEnv, expandEnvString, loadManifest, parseManifest, workerJobType,
 export type { ActionDecl, AppManifest, DataSource, DomainType, LlmBinding, SurfaceDecl, TriggerDecl, TypeField, WorkerDecl, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
 export type { ValidationIssue } from "./core/validate.ts";
-export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WorkerSubscription, } from "./core/host.ts";
+export type { EngineClient, EngineJob, HostContext, HttpHandler, HttpRequest, HttpResponse, HttpServer, JobHandler, SqliteDb, WatchHandle, WorkerSubscription, } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
 export { DataLayer, TypeRepo } from "./core/modules/datasource.ts";
 export type { ProvisionedSource } from "./core/modules/datasource.ts";
@@ -25,5 +25,7 @@ export { isDeno, selectHost } from "./adapters/detect.ts";
 export { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.ts";
 export type { NanoSdkClient, NanoSdkEngineOptions, NanoSdkJobWorker, NanoSdkJobWorkerConfig, } from "./engine/nanosdk.ts";
 export type { EngineSdkClient } from "./engine/sdk.ts";
-export { runFromEnv } from "./run.ts";
+export { installSignalHandlers, runFromEnv } from "./run.ts";
 export type { RunOptions } from "./run.ts";
+export { runDev, shouldReload } from "./devserver.ts";
+export type { DevDeps, DevOptions, DevServer } from "./devserver.ts";

package/dist/runtime/index.js

@@ -18,4 +18,5 @@ export { createNodeHost } from "./adapters/node.js";
 export { createDenoHost } from "./adapters/deno.js";
 export { isDeno, selectHost } from "./adapters/detect.js";
 export { createNanoSdkEngineClient, SdkEngineClient } from "./engine/nanosdk.js";
-export { runFromEnv } from "./run.js";
+export { installSignalHandlers, runFromEnv } from "./run.js";
+export { runDev, shouldReload } from "./devserver.js";

package/dist/runtime/run.d.ts

@@ -15,3 +15,4 @@ export interface RunOptions extends Partial<CreateUrbanAppOptions> {
     handleSignals?: boolean;
 }
 export declare function runFromEnv(opts?: RunOptions): Promise<UrbanApp>;
+export declare function installSignalHandlers(stop: () => Promise<void>): void;

package/dist/runtime/run.js

@@ -32,7 +32,7 @@ export async function runFromEnv(opts = {}) {
         installSignalHandlers(() => app.stop());
     return app;
 }
-function installSignalHandlers(stop) {
+export function installSignalHandlers(stop) {
     let stopping = false;
     const onSignal = () => {
         if (stopping)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/urban",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
   "license": "Apache-2.0",
   "type": "module",
@@ -61,7 +61,7 @@
     "@nanobpm/nano-sdk": "^1.2.0",
     "@nanobpm/workflow": "^0.7.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2",
-    "create-urban-app": "^0.3.0"
+    "create-urban-app": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",

package/src/cli.ts

@@ -4,7 +4,7 @@
 //   urban check          load + validate the manifest, report issues
 //   urban gen            derive generated artifacts (migrations, worker I/O)
 //   urban run            materialize + serve the app (deploy, data, workers, surfaces, triggers)
-//   urban dev            like run (hot-reload is not yet implemented; documented below)
+//   urban dev            like run, plus watch sources and hot-reload on change
 //   urban deploy         deploy models only, then exit
 //
 // Global flags: --root <dir> (default "."), --manifest <file> (default nano.app.json),
@@ -12,7 +12,9 @@
 
 import {
   collectManifestIssues,
+  installSignalHandlers,
   loadManifest,
+  runDev,
   runFromEnv,
   selectHost,
 } from "./runtime/index.ts";
@@ -82,7 +84,7 @@ Usage:
   urban check                       validate the manifest
   urban gen [--check]               derive artifacts (migrations, worker-io)
   urban run                         materialize + serve the app
-  urban dev                         run (hot-reload not yet implemented)
+  urban dev                         run + watch sources, hot-reload on change
   urban deploy                      deploy models only, then exit
 
 Global flags:
@@ -139,6 +141,12 @@ async function cmdRun(f: Flags, mount?: Record<string, boolean>): Promise<number
   return -1; // keep the process alive; signal handlers stop it
 }
 
+async function cmdDev(f: Flags): Promise<number> {
+  const dev = await runDev({ root: f.root, manifestPath: f.manifest, port: f.port });
+  installSignalHandlers(() => dev.stop());
+  return -1; // keep the process alive; signal handlers stop the dev server
+}
+
 async function cmdDeploy(f: Flags): Promise<number> {
   const app = await runFromEnv({
     root: f.root,
@@ -194,8 +202,7 @@ export async function main(argv: string[]): Promise<number> {
     case "run":
       return cmdRun(f);
     case "dev":
-      console.log("urban dev: hot-reload is not yet implemented; running once.");
-      return cmdRun(f);
+      return cmdDev(f);
     case "deploy":
       return cmdDeploy(f);
     default:

package/src/runtime/adapters/deno.ts

@@ -18,12 +18,16 @@ interface DenoHttpServer {
   finished: Promise<void>;
   shutdown(): Promise<void>;
 }
+interface DenoFsWatcher extends AsyncIterable<{ kind: string; paths: string[] }> {
+  close(): void;
+}
 interface DenoGlobal {
   env: { get(name: string): string | undefined };
   cwd(): string;
   readTextFile(path: string): Promise<string>;
   readDir(path: string): AsyncIterable<{ name: string; isFile: boolean }>;
   stat(path: string): Promise<unknown>;
+  watchFs(paths: string | string[], options?: { recursive?: boolean }): DenoFsWatcher;
   serve(
     opts: { port: number; onListen?: (a: { port: number }) => void },
     handler: (req: Request) => Response | Promise<Response>,
@@ -34,6 +38,8 @@ declare const Deno: DenoGlobal;
 export interface DenoHostOptions {
   cwd?: string;
   log?: HostContext["log"];
+  /** See NodeHostOptions.importNonce — appended as `?v=<nonce>` to dynamic imports. */
+  importNonce?: string;
 }
 
 export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
@@ -75,10 +81,39 @@ export function createDenoHost(opts: DenoHostOptions = {}): HostContext {
       const db = new DatabaseSync(abs(path));
       return wrapSqlite(db);
     },
-    importModule: (p) => import(pathToFileURL(abs(p)).href) as Promise<Record<string, unknown>>,
+    importModule: (p) => {
+      const href =
+        pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+      return import(href) as Promise<Record<string, unknown>>;
+    },
     async serveHttp(port, handler) {
       return startDenoServer(port, handler);
     },
+    watch(onChange) {
+      const w = Deno.watchFs(cwd, { recursive: true });
+      let closed = false;
+      (async () => {
+        try {
+          for await (const ev of w) {
+            for (const p of ev.paths) onChange(p);
+          }
+        } catch (err) {
+          // Deno.watchFs throws when close() is called mid-await — expected on shutdown.
+          // Any other failure (permissions, path removed, …) silently disables hot reload,
+          // so surface it instead of swallowing it.
+          if (!closed) log("warn", "file watch error — hot reload may be disabled", {
+            error: String(err),
+          });
+        }
+      })();
+      return {
+        close: () => {
+          if (closed) return;
+          closed = true;
+          w.close();
+        },
+      };
+    },
     now: () => Date.now(),
     log,
   };

package/src/runtime/adapters/detect.ts

@@ -14,6 +14,8 @@ export function isDeno(): boolean {
 export interface SelectHostOptions {
   cwd?: string;
   log?: HostContext["log"];
+  /** Dev-only import-cache-busting nonce; forwarded to the chosen adapter. */
+  importNonce?: string;
 }
 
 /** Select and construct the host for the current runtime. */

package/src/runtime/adapters/node.ts

@@ -2,6 +2,7 @@
 // (with deno.ts) allowed to touch a concrete runtime.
 
 import { readFile, readdir, stat } from "node:fs/promises";
+import { watch as fsWatch, type FSWatcher } from "node:fs";
 import { createServer } from "node:http";
 import { isAbsolute, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -12,12 +13,19 @@ import type {
   HttpRequest,
   HttpServer,
   SqliteDb,
+  WatchHandle,
 } from "../core/host.ts";
 
 export interface NodeHostOptions {
   /** Base directory relative paths resolve against. Default process.cwd(). */
   cwd?: string;
   log?: HostContext["log"];
+  /**
+   * When set, appended as a `?v=<nonce>` query to dynamic import URLs so a changed
+   * handler/worker module is re-evaluated instead of served from the ESM cache. The
+   * dev server bumps this on every reload; production leaves it unset.
+   */
+  importNonce?: string;
 }
 
 export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
@@ -56,10 +64,35 @@ export function createNodeHost(opts: NodeHostOptions = {}): HostContext {
       const db = new DatabaseSync(abs(path));
       return wrapNodeSqlite(db);
     },
-    importModule: (p) => import(pathToFileURL(abs(p)).href) as Promise<Record<string, unknown>>,
+    importModule: (p) => {
+      const href =
+        pathToFileURL(abs(p)).href + (opts.importNonce ? `?v=${opts.importNonce}` : "");
+      return import(href) as Promise<Record<string, unknown>>;
+    },
     async serveHttp(port, handler) {
       return await startNodeServer(port, handler);
     },
+    watch(onChange) {
+      const onFsEvent = (_event: unknown, filename: string | Buffer | null) => {
+        if (filename) onChange(String(filename));
+      };
+      // Recursive watch is supported on macOS, Windows, and — since Node 19.1.0 — Linux.
+      // This package requires Node >=22.6, so the recursive path is available on all three;
+      // the try/catch only trips on an unusual platform, where we degrade honestly to a
+      // non-recursive root watch (and warn) rather than silently miss nested changes.
+      let w: FSWatcher;
+      try {
+        w = fsWatch(cwd, { recursive: true }, onFsEvent);
+      } catch (err) {
+        log("warn", "recursive file watch unavailable — nested changes may be missed", {
+          error: String(err),
+        });
+        w = fsWatch(cwd, onFsEvent);
+      }
+      // A watcher error (e.g. the dir is removed) must not crash the dev server.
+      w.on("error", (err) => log("warn", "file watch error", { error: String(err) }));
+      return { close: () => w.close() } satisfies WatchHandle;
+    },
     now: () => Date.now(),
     log,
   };

package/src/runtime/core/host.ts

@@ -30,6 +30,11 @@ export interface HttpServer {
   stop(): Promise<void>;
 }
 
+/** A handle to an active filesystem watch; call close() to stop watching. */
+export interface WatchHandle {
+  close(): void;
+}
+
 /** A tiny synchronous SQLite handle — the subset the runtime needs. */
 export interface SqliteDb {
   /** Execute one or more statements with no result (DDL, PRAGMA, migrations). */
@@ -65,6 +70,13 @@ export interface HostContext {
   importModule(path: string): Promise<Record<string, unknown>>;
   /** Start an HTTP server. Routing is done by the caller inside `handler`. */
   serveHttp(port: number, handler: HttpHandler): Promise<HttpServer>;
+  /**
+   * Recursively watch the app root for file changes, invoking `onChange` with the
+   * changed path (app-root-relative when the runtime reports it that way). Optional:
+   * hosts that cannot watch omit it, and callers fall back to run-once. Returns a
+   * handle whose close() stops watching.
+   */
+  watch?(onChange: (path: string) => void): WatchHandle;
   /** Current wall-clock time in ms since epoch (seam for tests). */
   now(): number;
   /** Structured log sink. */

package/src/runtime/devserver.test.ts

@@ -0,0 +1,330 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runDev, shouldReload, type DevDeps } from "./devserver.ts";
+import type { HostContext } from "./core/host.ts";
+import type { UrbanApp } from "./core/runtime.ts";
+
+const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+test("shouldReload triggers on source files and the manifest", () => {
+  for (const p of [
+    "nano.app.json",
+    "processes/greet.bpmn",
+    "decisions/route.dmn",
+    "forms/greet.form",
+    "workers/greet.ts",
+    "workers/greet.js",
+    "db/migrations/001_init.sql",
+    "./processes/greet.bpmn",
+  ]) {
+    assert.equal(shouldReload(p), true, `expected reload for ${p}`);
+  }
+});
+
+test("shouldReload ignores generated output, deps, VCS and db churn", () => {
+  for (const p of [
+    "nano-generated/greeting.schema.sql",
+    "nano-generated/urban-workers.d.ts",
+    "node_modules/left-pad/index.js",
+    ".git/index",
+    "dist/index.js",
+    "db/app.db",
+    "db/app.db-wal",
+    "db/app.db-shm",
+    "db/app.sqlite-journal",
+    "README.md",
+    "notes.txt",
+    "",
+  ]) {
+    assert.equal(shouldReload(p), false, `expected no reload for ${p}`);
+  }
+});
+
+test("shouldReload honours a custom manifest filename", () => {
+  assert.equal(shouldReload("config/app.json", "config/app.json"), true, "custom manifest reloads");
+  assert.equal(shouldReload("app.config.json", "app.config.json"), true, "by basename too");
+  // A .json that is NOT the configured manifest is not a source file.
+  assert.equal(shouldReload("tsconfig.json"), false, "unrelated json ignored");
+  assert.equal(shouldReload("config/app.json"), false, "custom manifest ignored under default");
+});
+
+test("stop() cancels a pending debounced reload", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  let clock = 1;
+  let watch!: ReturnType<typeof fakeHost>;
+  const deps: DevDeps = {
+    makeHost: () => ((watch = fakeHost()), watch.host),
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+  const dev = await runDev({ debounceMs: 50, log: () => {} }, deps);
+  watch.fire("workers/x.ts"); // schedules a reload 50ms out
+  await dev.stop(); // stop before the debounce fires
+  await delay(80);
+  assert.equal(starts.length, 1, "pending reload was cancelled by stop()");
+  assert.equal(watch.closed(), true, "watcher closed");
+  assert.deepEqual(stops, ["a0"], "the running app was stopped exactly once");
+});
+
+test("stop() during an in-flight reload does not start a replacement app", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  let clock = 1;
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  // Gate the boot app's stop() so we can flip shutdown mid-reload, in the window
+  // between the old app being stopped and the new one starting.
+  let releaseStop!: () => void;
+  const stopGate = new Promise<void>((r) => (releaseStop = r));
+
+  const deps: DevDeps = {
+    makeHost: () => {
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      if (id === "a0") {
+        return {
+          ...fakeApp(stops, id),
+          async stop() {
+            await stopGate; // block the first reload inside app.stop()
+            stops.push(id);
+          },
+        } as UrbanApp;
+      }
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 5, log: () => {} }, deps);
+  hosts[0].fire("workers/x.ts"); // triggers a reload; it will block inside app.stop()
+  await delay(20);
+  const stopping = dev.stop(); // flips `stopped` while the reload is parked in app.stop()
+  releaseStop(); // let the old app finish stopping; reload must now bail, not start a0's replacement
+  await stopping;
+
+  assert.deepEqual(starts, ["a0"], "no replacement app started during teardown");
+  assert.deepEqual(stops, ["a0"], "the running app was stopped exactly once");
+  assert.equal(hosts[0].closed(), true, "watcher closed");
+});
+
+test("import nonce is unique per reload even within the same millisecond", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  const nonces: string[] = [];
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  const deps: DevDeps = {
+    makeHost: (nonce) => {
+      nonces.push(nonce);
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => 42, // frozen clock: nonce uniqueness must come from the reload counter
+  };
+  const dev = await runDev({ debounceMs: 1, log: () => {} }, deps);
+  // The watcher is registered on the boot host only; fire both changes through it.
+  hosts[0].fire("workers/a.ts");
+  await delay(15);
+  hosts[0].fire("workers/b.ts");
+  await delay(15);
+  await dev.stop();
+  assert.equal(nonces.length, 3, "boot + two reloads built three hosts");
+  assert.equal(new Set(nonces).size, 3, "every import nonce is distinct");
+});
+
+test("a change during an in-flight reload doesn't detach stop() from it", async () => {
+  // Regression: schedule() used to overwrite `inFlight` with reload()'s already-resolved
+  // no-op promise when a reload was already running, so stop() wouldn't await the real
+  // reload and could tear down while it started a replacement app (a leak).
+  const starts: string[] = [];
+  const stops: string[] = [];
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  let clock = 1;
+  // Gate a1's start so reload #1 parks *past* the shutdown checks, inside startApp.
+  let releaseStart!: () => void;
+  const startGate = new Promise<void>((r) => (releaseStart = r));
+
+  const deps: DevDeps = {
+    makeHost: () => {
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      if (id === "a1") await startGate; // park reload #1 inside startApp
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 5, log: () => {} }, deps);
+  hosts[0].fire("workers/a.ts"); // reload #1: stops a0, then parks starting a1
+  await delay(20);
+  hosts[0].fire("workers/b.ts"); // a second change lands while reload #1 is in flight
+  await delay(20);
+
+  const stopping = dev.stop(); // must await the real reload #1, not a stale resolved promise
+  releaseStart(); // let reload #1 finish starting a1
+  await stopping;
+
+  assert.deepEqual(starts, ["a0", "a1"], "reload #1 started its replacement app");
+  assert.deepEqual(stops, ["a0", "a1"], "stop() awaited reload #1 and stopped a1 (no leak)");
+});
+
+// A minimal fake host: runDev only calls host.watch on it.
+function fakeHost(): { host: HostContext; fire: (p: string) => void; closed: () => boolean } {
+  let cb: ((p: string) => void) | undefined;
+  let closed = false;
+  const host = {
+    watch(onChange: (p: string) => void) {
+      cb = onChange;
+      return { close: () => (closed = true) };
+    },
+  } as unknown as HostContext;
+  return { host, fire: (p) => cb?.(p), closed: () => closed };
+}
+
+function fakeApp(stops: string[], id: string): UrbanApp {
+  return {
+    manifest: { id } as UrbanApp["manifest"],
+    root: ".",
+    async start() {},
+    async stop() {
+      stops.push(id);
+    },
+    inspect: () => ({ app: id }),
+    data: undefined,
+    security: undefined,
+    httpPort: undefined,
+  };
+}
+
+test("runDev derives + starts once, then hot-reloads on a relevant change", async () => {
+  const gens: string[] = [];
+  const starts: string[] = [];
+  const stops: string[] = [];
+  const nonces: string[] = [];
+  const hosts: ReturnType<typeof fakeHost>[] = [];
+  let clock = 1000;
+
+  const deps: DevDeps = {
+    makeHost: (nonce) => {
+      nonces.push(nonce);
+      const h = fakeHost();
+      hosts.push(h);
+      return h.host;
+    },
+    startApp: async (_host) => {
+      const id = `app#${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async (root, mf) => {
+      gens.push(`${root}:${mf}`);
+      return { count: 2 };
+    },
+    now: () => clock++,
+  };
+
+  const logs: string[] = [];
+  const dev = await runDev(
+    { root: ".", manifestPath: "nano.app.json", debounceMs: 5, log: (m) => logs.push(m) },
+    deps,
+  );
+
+  assert.deepEqual(gens, [".:nano.app.json"], "gen ran once at boot");
+  assert.deepEqual(starts, ["app#0"], "app started once at boot");
+  assert.equal(stops.length, 0, "nothing stopped yet");
+
+  // runDev registers the watcher on the boot host only; fire through it.
+  const bootWatch = hosts[0];
+
+  // An irrelevant change (the sqlite db) must NOT reload.
+  bootWatch.fire("db/app.db");
+  await delay(20);
+  assert.equal(starts.length, 1, "db churn did not reload");
+
+  // A relevant change reloads: stop old, regen, start new with a fresh nonce.
+  bootWatch.fire("processes/greet.bpmn");
+  await delay(20);
+  assert.deepEqual(stops, ["app#0"], "old app stopped");
+  assert.equal(gens.length, 2, "gen reran on reload");
+  assert.deepEqual(starts, ["app#0", "app#1"], "new app started");
+  assert.notEqual(nonces[0], nonces[1], "import nonce changed across reload");
+
+  await dev.stop();
+  assert.equal(bootWatch.closed(), true, "watcher closed on stop");
+  assert.deepEqual(stops, ["app#0", "app#1"], "current app stopped on shutdown");
+});
+
+test("runDev coalesces a burst of changes into a single reload (debounce)", async () => {
+  const starts: string[] = [];
+  const stops: string[] = [];
+  let clock = 1;
+  let watch!: ReturnType<typeof fakeHost>;
+
+  const deps: DevDeps = {
+    makeHost: () => ((watch = fakeHost()), watch.host),
+    startApp: async () => {
+      const id = `a${starts.length}`;
+      starts.push(id);
+      return fakeApp(stops, id);
+    },
+    regenerate: async () => ({ count: 0 }),
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 15, log: () => {} }, deps);
+  for (const p of ["workers/a.ts", "workers/b.ts", "forms/c.form"]) watch.fire(p);
+  await delay(40);
+  assert.equal(starts.length, 2, "three rapid edits produced exactly one reload");
+  await dev.stop();
+});
+
+test("runDev survives a failing reload and keeps the previous app running", async () => {
+  const stops: string[] = [];
+  let boom = false;
+  let clock = 1;
+  let watch!: ReturnType<typeof fakeHost>;
+  const logs: string[] = [];
+
+  const deps: DevDeps = {
+    makeHost: () => ((watch = fakeHost()), watch.host),
+    startApp: async () => fakeApp(stops, "app"),
+    regenerate: async () => {
+      if (boom) throw new Error("bad manifest");
+      return { count: 1 };
+    },
+    now: () => clock++,
+  };
+
+  const dev = await runDev({ debounceMs: 5, log: (m) => logs.push(m) }, deps);
+  boom = true;
+  watch.fire("nano.app.json");
+  await delay(20);
+  assert.ok(
+    logs.some((l) => l.includes("reload failed")),
+    "a failed reload is reported, not thrown",
+  );
+  await dev.stop();
+});

package/src/runtime/devserver.ts

@@ -0,0 +1,199 @@
+// `urban dev` — a hot-reload dev server. It runs the derivers once, starts the app, then
+// watches the app root and, on a relevant source change, regenerates artifacts and restarts
+// the app in-process. A per-reload import nonce busts the module cache so changed worker/
+// action handlers are re-evaluated. main.ts is NOT re-run in dev (the CLI drives the runtime
+// directly), so main.ts edits don't need a reload.
+//
+// The reload strategy is a full in-process restart: regenerate + build a fresh host, then
+// stop the old app and start the new one. Regenerating first means a bad edit (invalid
+// manifest/model) fails before the running app is torn down, so it keeps serving. It is the
+// same start path as a fresh `urban run`, so every change kind — manifest, BPMN/DMN, forms,
+// migrations/types, worker code — is picked up. A finer-grained surface remount + browser
+// live-reload can layer on later behind this same seam.
+
+import { runFromEnv } from "./run.ts";
+import { selectHost } from "./adapters/detect.ts";
+import type { HostContext, WatchHandle } from "./core/host.ts";
+import type { UrbanApp } from "./core/runtime.ts";
+import { createNodeGenIO, runGen } from "../toolkit/index.ts";
+
+const SOURCE_EXT = [".bpmn", ".dmn", ".form", ".ts", ".js", ".mjs", ".sql"] as const;
+// Directories whose churn must never trigger a reload: generated output (gen writes here —
+// watching it would loop forever), dependencies, VCS, and build output.
+const IGNORE_SEGMENTS = ["nano-generated", "node_modules", ".git", "dist"] as const;
+
+/** True when a changed path should trigger a dev reload. Pure, so it is unit-tested.
+ *  `manifestFile` (the app's configured manifest, default nano.app.json) always triggers,
+ *  so `urban dev --manifest other.json` reloads on edits to that file too. */
+export function shouldReload(rawPath: string, manifestFile = "nano.app.json"): boolean {
+  const norm = (s: string) => s.replace(/\\/g, "/").replace(/^\.\//, "");
+  const p = norm(rawPath);
+  if (p === "") return false;
+  for (const seg of IGNORE_SEGMENTS) {
+    if (p === seg || p.startsWith(`${seg}/`) || p.includes(`/${seg}/`)) return false;
+  }
+  // Ignore SQLite database files and their WAL/SHM/journal sidecars — they change on every
+  // write and would otherwise wedge the server in a reload loop.
+  if (/\.(db|sqlite|sqlite3)(-wal|-shm|-journal)?$/i.test(p)) return false;
+  const mf = norm(manifestFile);
+  const base = p.slice(p.lastIndexOf("/") + 1);
+  if (p === mf || base === mf.slice(mf.lastIndexOf("/") + 1)) return true;
+  return SOURCE_EXT.some((e) => p.toLowerCase().endsWith(e));
+}
+
+export interface DevOptions {
+  root?: string;
+  manifestPath?: string;
+  port?: number;
+  /** Quiet-period after the last change before reloading, in ms. Default 150. */
+  debounceMs?: number;
+  /** Log sink (default console.log). */
+  log?: (msg: string) => void;
+}
+
+/** Injectable seams so the loop is testable without a live engine or filesystem. */
+export interface DevDeps {
+  makeHost(nonce: string): HostContext;
+  startApp(host: HostContext, o: { manifestPath: string; port?: number }): Promise<UrbanApp>;
+  regenerate(root: string, manifestFile: string): Promise<{ count: number }>;
+  now(): number;
+}
+
+function defaultDeps(root: string): DevDeps {
+  return {
+    makeHost: (nonce) => selectHost({ cwd: root, importNonce: nonce }),
+    startApp: (host, o) =>
+      // The host is anchored at `root`; runFromEnv keeps its own root at "." accordingly.
+      runFromEnv({ host, manifestPath: o.manifestPath, port: o.port, handleSignals: false }),
+    regenerate: async (r, mf) => {
+      const res = await runGen({ root: r, io: createNodeGenIO(), manifestFile: mf });
+      return { count: res.artifacts.length };
+    },
+    now: () => Date.now(),
+  };
+}
+
+export interface DevServer {
+  stop(): Promise<void>;
+}
+
+/**
+ * Start the dev server: gen once, start the app, then watch + hot-reload. Returns a handle
+ * whose stop() tears the watcher and the running app down. Never rejects on a reload error —
+ * a bad edit logs and leaves the previous app running.
+ */
+export async function runDev(opts: DevOptions = {}, deps?: Partial<DevDeps>): Promise<DevServer> {
+  const root = opts.root ?? ".";
+  const manifestFile = opts.manifestPath ?? "nano.app.json";
+  const debounceMs = opts.debounceMs ?? 150;
+  const log = opts.log ?? ((m: string) => console.log(m));
+  const d: DevDeps = { ...defaultDeps(root), ...deps };
+
+  // Monotonic reload counter, mixed into the import nonce so it is unique per reload even when
+  // two reloads land in the same millisecond (d.now() can repeat).
+  let reloadSeq = 0;
+
+  const startCycle = async (): Promise<{ host: HostContext; app: UrbanApp }> => {
+    const host = await prepareHost();
+    const app = await d.startApp(host, { manifestPath: manifestFile, port: opts.port });
+    return { host, app };
+  };
+
+  // Derive artifacts and build a fresh host (with a new import nonce). This is pure/FS work
+  // that does NOT touch the running app, so it can run *before* a reload tears the old app
+  // down — most bad edits (invalid manifest/model) fail here, leaving the app serving.
+  const prepareHost = async (): Promise<HostContext> => {
+    const nonce = `${d.now()}-${reloadSeq++}`;
+    const { count } = await d.regenerate(root, manifestFile);
+    if (count > 0) log(`  derived ${count} artifact(s)`);
+    return d.makeHost(nonce);
+  };
+
+  let { host, app } = await startCycle();
+
+  let reloading = false;
+  let queued = false;
+  let stopped = false;
+  let appRunning = true;
+  let inFlight: Promise<void> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  const reload = async (): Promise<void> => {
+    try {
+      log("↻ change detected — reloading…");
+      // Regenerate + rebuild the host BEFORE stopping the running app, so a bad edit
+      // throws here and the current app keeps serving untouched.
+      const nextHost = await prepareHost();
+      if (stopped) return; // shutdown began mid-prepare: leave the running app to stop()
+      await app.stop();
+      appRunning = false;
+      // Re-check after the async stop: if shutdown began while we were tearing the old
+      // app down, don't start a replacement just to have stop() immediately kill it.
+      if (stopped) return;
+      app = await d.startApp(nextHost, { manifestPath: manifestFile, port: opts.port });
+      appRunning = true;
+      host = nextHost;
+      log("✔ reloaded");
+    } catch (err) {
+      // Keep the dev server alive on a bad edit; the next save will retry.
+      log(`✖ reload failed: ${String((err as Error)?.message ?? err)}`);
+    } finally {
+      reloading = false;
+      if (queued && !stopped) {
+        queued = false;
+        schedule();
+      }
+    }
+  };
+
+  // Owns the single-flight guard and `inFlight` bookkeeping: only an *actually running*
+  // reload is tracked in `inFlight`, so stop() always awaits the real in-flight reload
+  // (never an already-resolved no-op promise) before final teardown.
+  const trigger = (): void => {
+    if (stopped) return;
+    if (reloading) {
+      queued = true; // the active reload's finally re-schedules the next cycle
+      return;
+    }
+    reloading = true;
+    inFlight = reload();
+  };
+
+  const schedule = (): void => {
+    if (stopped) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = undefined;
+      trigger();
+    }, debounceMs);
+  };
+
+  let watcher: WatchHandle | undefined;
+  if (host.watch) {
+    watcher = host.watch((path) => {
+      if (shouldReload(path, manifestFile)) schedule();
+    });
+    log("▲ dev server ready — watching for changes (Ctrl-C to stop)");
+  } else {
+    log(
+      "▲ dev server ready — file watching is not supported on this host; running once " +
+        "(no hot reload, Ctrl-C to stop)",
+    );
+  }
+
+  return {
+    async stop() {
+      // Order matters: flag first so a queued/in-flight reload won't start a new app, cancel
+      // any pending debounce, stop watching, then let any in-flight reload settle before the
+      // final teardown so we stop exactly the app that is (or ends up) current.
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      watcher?.close();
+      await inFlight?.catch(() => {});
+      if (appRunning) await app.stop();
+    },
+  };
+}

package/src/runtime/index.ts

@@ -47,6 +47,7 @@ export type {
   HttpServer,
   JobHandler,
   SqliteDb,
+  WatchHandle,
   WorkerSubscription,
 } from "./core/host.ts";
 export type { AppApi, Mounted, RuntimeContext } from "./core/context.ts";
@@ -97,5 +98,7 @@ export type {
   NanoSdkJobWorkerConfig,
 } from "./engine/nanosdk.ts";
 export type { EngineSdkClient } from "./engine/sdk.ts";
-export { runFromEnv } from "./run.ts";
+export { installSignalHandlers, runFromEnv } from "./run.ts";
 export type { RunOptions } from "./run.ts";
+export { runDev, shouldReload } from "./devserver.ts";
+export type { DevDeps, DevOptions, DevServer } from "./devserver.ts";

package/src/runtime/run.ts

@@ -56,7 +56,7 @@ export async function runFromEnv(opts: RunOptions = {}): Promise<UrbanApp> {
   return app;
 }
 
-function installSignalHandlers(stop: () => Promise<void>): void {
+export function installSignalHandlers(stop: () => Promise<void>): void {
   let stopping = false;
   const onSignal = () => {
     if (stopping) return;