fix(cli): dev restarts the serve child after each rebuild — no more silent artifact/server divergence (#5148) (#6150)

The dev watcher rebuilt dist/objectstack.json and printed "server will
auto-reload", but the running serve child only partially receives a rebuilt
artifact: MetadataPlugin's artifact watcher re-ingests the registry, syncs
DDL + seeds for NEW objects and broadcasts the SSE HMR event, while hook
bodies and already-registered view metadata from the compiled bundle are
applied at boot only. #5148 measured both staying stale — every dev
edit/verify loop could produce a false conclusion in either direction.

Boot-time load is the one path that applies the whole artifact, so dev now
supervises its serve child nodemon-style via ServeRestartCoordinator
(packages/cli/src/utils/dev-restart.ts):

- after each successful rebuild: SIGTERM the child (kernel shuts down
  gracefully), spawn a replacement on exit; requests during teardown
  coalesce; SIGKILL escalation after 8s; a failed respawn is loud and
  exits dev; parent SIGINT/SIGTERM is forwarded and a process-exit hook
  guarantees no orphaned server.
- --no-restart keeps the rebuild-only behavior but says on EVERY rebuild
  that the running server keeps the build it booted with; the watch
  banner states the active mode instead of implying hot reload.
- startup variant (#5148 comment 2026-08-05): when objectstack.config.ts
  / src/** are newer than the artifact at boot, warn loudly (newest
  source + remedy) without gating the boot. The staleness walk shares
  the watcher's ignore list so both judge the same source surface.

Seams unit-tested (22 cases): staleness assessment on real tmpdirs,
coordinator state machine with a fake child (restart sequencing,
coalescing, self-exit follow, shutdown-beats-respawn, force-kill,
spawn failure, orphan guard, late exit events).


Claude-Session: https://claude.ai/code/session_015a5qkLzpGXhLL2F5gvJ7dD

Co-authored-by: Claude <noreply@anthropic.com>

Author: hotlong

.changeset/dev-watcher-restart-honesty.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `objectstack dev` restarts the server after each rebuild — the running server can no longer silently disagree with `dist/objectstack.json` (#5148)
+
+The dev watcher rebuilt `dist/objectstack.json` on every source change and
+printed `✓ recompiled — server will auto-reload`, but the running serve child
+only **partially** received the rebuilt artifact: MetadataPlugin's own
+artifact watcher re-ingests the metadata registry, syncs DDL + seeds for
+newly-appearing objects and broadcasts the SSE HMR event — while hook bodies
+and already-registered view metadata from the compiled bundle are applied at
+**boot only**. #5148 measured both staying stale: the old hook kept executing
+and `/api/v1/meta/views` kept serving the old view after a confirmed on-disk
+rebuild, with no error and no warning. That made every dev edit/verify loop
+capable of a false conclusion in either direction ("my fix doesn't work" /
+"this code isn't load-bearing").
+
+`objectstack dev` now supervises its serve child nodemon-style:
+
+- **Auto-restart (default-on).** After a rebuild lands on disk, the serve
+  child is SIGTERMed (the kernel shuts down gracefully), and a replacement is
+  spawned once it exits — boot-time load is the one path that applies the
+  whole artifact. Restarts coalesce (rapid saves produce one restart), a
+  child that ignores SIGTERM is force-killed after 8s, a replacement that
+  fails to come up is loud and exits dev, and parent SIGINT/SIGTERM is
+  forwarded to the child so no orphan server outlives dev.
+- **`--no-restart` opt-out.** The watcher then only rebuilds the artifact —
+  and every rebuild now says explicitly that the running server keeps the
+  build it booted with. The watch banner states the active mode instead of
+  implying a hot reload the runtime only partially performs.
+- **Boot-time staleness warning (#5148 startup variant).** When
+  `objectstack.config.ts` / `src/**` are newer than the artifact at boot
+  (edited while the server was down), dev warns loudly that the boot serves
+  the stale build, names the newest source file and the remedy
+  (`objectstack build`, `--compile`, or save a watched file). The boot is
+  never gated — the silence is removed, not the start.

content/docs/getting-started/your-first-project.mdx

@@ -179,7 +179,7 @@ Postgres / MySQL / MongoDB for production — [no code changes](/docs/data-model
 ## 3. Run it
 
 ```bash
-npm run dev            # objectstack dev — hot reload
+npm run dev            # objectstack dev — rebuild + server restart on change
 ```
 
 Or with the visual Console (data browser, metadata explorer, API docs):