@antelopejs/dms 0.5.1 → 0.5.2

package/frontend-vue/layers/dms-core/app/composables/realtime/useUserRealtime.ts

@@ -1,4 +1,8 @@
-import { isUnauthorizedStreamError, openSseStream } from "./useSseStream";
+import {
+  isUnauthorizedStreamError,
+  openSseStream,
+  type SseStreamHandle,
+} from "./useSseStream";
 
 const REALTIME_USER_PATH = "/api/realtime/user";
 const REALTIME_SUBSCRIBE_PATH_PREFIX = "/api/realtime/subscribe/";
@@ -117,57 +121,109 @@ const handleEvent =
     }
   };
 
+interface ConnectionCallbacks {
+  onConnected: () => void;
+  onDisconnected: () => void;
+  refreshSession: () => Promise<boolean>;
+  redirectToAuth: () => Promise<void>;
+}
+
+interface Reconnector {
+  isCancelled(): boolean;
+  schedule(open: () => void): void;
+  resetDelay(): void;
+  cancel(): void;
+}
+
+const createReconnector = (): Reconnector => {
+  let isCancelled = false;
+  let delay = RECONNECT_INITIAL_DELAY_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return {
+    isCancelled: () => isCancelled,
+    schedule: (open) => {
+      // A pending reconnect absorbs concurrent triggers: one stream per tab.
+      if (isCancelled || timer) return;
+      timer = setTimeout(() => {
+        timer = undefined;
+        open();
+      }, delay);
+      delay = Math.min(delay * RECONNECT_MULTIPLIER, RECONNECT_MAX_DELAY_MS);
+    },
+    resetDelay: () => {
+      delay = RECONNECT_INITIAL_DELAY_MS;
+    },
+    cancel: () => {
+      isCancelled = true;
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+    },
+  };
+};
+
+const recoverFromError = (
+  error: unknown,
+  reconnect: () => void,
+  callbacks: ConnectionCallbacks,
+): void => {
+  if (!isUnauthorizedStreamError(error)) {
+    reconnect();
+    return;
+  }
+  void callbacks.refreshSession().then((isRefreshed) => {
+    if (isRefreshed) {
+      reconnect();
+    } else {
+      void callbacks.redirectToAuth();
+    }
+  }, reconnect);
+};
+
+/**
+ * Keeps one user stream open until cancelled. The server ends the stream when
+ * it stops (a dev reload included), so a clean EOF reconnects just like an
+ * error does: the user stream has no business completion.
+ */
 const connectWithBackoff = (
   url: string,
   state: UserRealtimeState,
-  onConnected: () => void,
-  refreshSession: () => Promise<boolean>,
-  redirectToAuth: () => Promise<void>,
+  callbacks: ConnectionCallbacks,
 ): (() => void) => {
-  let cancelled = false;
-  let delay = RECONNECT_INITIAL_DELAY_MS;
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let activeHandle: { close(): void } | undefined;
+  const reconnector = createReconnector();
   const dispatch = handleEvent(state);
+  let activeHandle: SseStreamHandle | undefined;
   const open = () => {
-    if (cancelled) return;
-    activeHandle = openSseStream({
+    if (reconnector.isCancelled()) return;
+    activeHandle?.close();
+    const handle: SseStreamHandle = openSseStream({
       url,
       onEvent: (eventName, data) => {
-        if (cancelled) return;
-        delay = RECONNECT_INITIAL_DELAY_MS;
+        if (handle !== activeHandle) return;
+        reconnector.resetDelay();
         dispatch(eventName, data);
-        if (eventName === HELLO_EVENT) onConnected();
+        if (eventName === HELLO_EVENT) callbacks.onConnected();
       },
       onError: (error) => {
-        if (cancelled) return;
-        state.appliedPageId.value = null;
-        const scheduleReconnect = () => {
-          if (cancelled) return;
-          timer = setTimeout(open, delay);
-          delay = Math.min(
-            delay * RECONNECT_MULTIPLIER,
-            RECONNECT_MAX_DELAY_MS,
-          );
-        };
-        if (isUnauthorizedStreamError(error)) {
-          void refreshSession().then((refreshed) => {
-            if (refreshed) {
-              scheduleReconnect();
-            } else {
-              void redirectToAuth();
-            }
-          }, scheduleReconnect);
-          return;
-        }
-        scheduleReconnect();
+        if (!retire(handle)) return;
+        recoverFromError(error, reconnect, callbacks);
+      },
+      onClose: (reason) => {
+        if (reason !== "eof" || !retire(handle)) return;
+        reconnect();
       },
     });
+    activeHandle = handle;
+  };
+  const reconnect = () => reconnector.schedule(open);
+  const retire = (handle: SseStreamHandle): boolean => {
+    if (handle !== activeHandle || reconnector.isCancelled()) return false;
+    activeHandle = undefined;
+    callbacks.onDisconnected();
+    return true;
   };
   open();
   return () => {
-    cancelled = true;
-    if (timer) clearTimeout(timer);
+    reconnector.cancel();
     activeHandle?.close();
     activeHandle = undefined;
   };
@@ -196,14 +252,29 @@ const reconcilePage = async (
   baseUrl: string,
 ): Promise<void> => {
   const desired = state.pageId.value ?? null;
+  const sessionId = state.sessionId.value;
   if (state.appliedPageId.value === desired) return;
-  if (!state.sessionId.value) return;
+  if (!sessionId) return;
   await callPageEndpoint(state, desired, baseUrl);
+  // A reconnect during the call replaced the session: the page is applied to
+  // the dead one, and the new one still needs it.
+  if (state.sessionId.value !== sessionId) return;
   if ((state.pageId.value ?? null) === desired) {
     state.appliedPageId.value = desired;
   }
 };
 
+/**
+ * Forgets what the server held for the closed session. The next greeting
+ * brings a new session id, which re-applies the page topics here and lets the
+ * components holding presence re-acquire it.
+ */
+const resetSession = (state: UserRealtimeState): void => {
+  state.sessionId.value = undefined;
+  state.appliedPageId.value = null;
+  state.snapshots.clear();
+};
+
 const buildApi = (): UserRealtimeApi => {
   const sessionId = useDmsState<string | undefined>(
     SESSION_STATE_KEY,
@@ -232,19 +303,20 @@ const buildApi = (): UserRealtimeApi => {
       (isLoggedIn) => {
         state.cancelConnect?.();
         state.cancelConnect = undefined;
-        state.sessionId.value = undefined;
+        resetSession(state);
         state.menuTopics.value = [];
-        state.appliedPageId.value = null;
-        state.snapshots.clear();
         if (!isLoggedIn) return;
         state.cancelConnect = connectWithBackoff(
           `${baseUrl}${REALTIME_USER_PATH}`,
           state,
-          () => {
-            void reconcilePage(state, baseUrl);
+          {
+            onConnected: () => {
+              void reconcilePage(state, baseUrl);
+            },
+            onDisconnected: () => resetSession(state),
+            refreshSession,
+            redirectToAuth,
           },
-          refreshSession,
-          redirectToAuth,
         );
       },
       { immediate: true },

package/frontend-vue/layers/dms-layout/app/pages/[...slug].vue

@@ -1,6 +1,8 @@
 <script setup lang="ts">
 import { withoutTrailingSlash } from "ufo";
 
+defineOptions({ inheritAttrs: false });
+
 // Dev-only: created behind the flag so the key never reaches a production
 // SSR payload.
 const devReloading = import.meta.env.DEV ? useDevReloading() : ref(false);

package/frontend-vue/layers/dms-ui/app/plugins/shortcuts.ts

@@ -1,4 +1,4 @@
-import aggregatedShortcuts from "../config/shortcuts-registry";
+import aggregatedShortcuts from "#shortcuts-aggregated";
 export default defineDmsPlugin(() => {
   const { registerShortcut } = useShortcutRegistry();
 

package/frontend-vue/layers/dms-ui/app/types/shortcuts-aggregated.d.ts

@@ -0,0 +1,8 @@
+// Generated by the renderer in the workspace: every module's
+// `app/config/shortcuts-registry.ts`, spread in priority order.
+declare module "#shortcuts-aggregated" {
+  import type { ComponentShortcuts } from "#dms-ui/app/types/shortcuts";
+
+  const aggregatedShortcuts: ComponentShortcuts[];
+  export default aggregatedShortcuts;
+}

package/frontend-vue/tests/realtime-reconnect.test.ts

@@ -0,0 +1,215 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { nextTick, ref, watch } from "vue";
+import type { UserRealtimeApi } from "../layers/dms-core/app/composables/realtime/useUserRealtime";
+
+const BASE_URL = "http://api";
+const USER_STREAM_URL = `${BASE_URL}/api/realtime/user`;
+const SUBSCRIBE_URL_PREFIX = `${BASE_URL}/api/realtime/subscribe/`;
+const SESSION_HEADER = "x-realtime-session";
+const PAGE_ID = "orders";
+const INITIAL_DELAY_MS = 500;
+const SECOND_DELAY_MS = 1000;
+const LONG_WAIT_MS = 120_000;
+
+interface FakeStream {
+  signal: AbortSignal;
+  end(): void;
+  isOpen(): boolean;
+}
+
+interface PageSubscription {
+  pageId: string;
+  sessionId: string;
+}
+
+interface FakeServer {
+  streams: FakeStream[];
+  subscriptions: PageSubscription[];
+  maxOpenStreams: number;
+  isDown: boolean;
+}
+
+const encoder = new TextEncoder();
+
+const helloFrame = (sessionId: string): Uint8Array =>
+  encoder.encode(`event: hello\ndata: ${JSON.stringify({ sessionId })}\n\n`);
+
+const openStreamCount = (server: FakeServer): number =>
+  server.streams.filter((stream) => stream.isOpen()).length;
+
+const openUserStream = (server: FakeServer, signal: AbortSignal) => {
+  let controller!: ReadableStreamDefaultController<Uint8Array>;
+  let isOpen = true;
+  const body = new ReadableStream<Uint8Array>({
+    start(streamController) {
+      controller = streamController;
+    },
+    cancel() {
+      isOpen = false;
+    },
+  });
+  signal.addEventListener("abort", () => {
+    isOpen = false;
+  });
+  server.streams.push({
+    signal,
+    end: () => {
+      isOpen = false;
+      controller.close();
+    },
+    isOpen: () => isOpen && !signal.aborted,
+  });
+  server.maxOpenStreams = Math.max(
+    server.maxOpenStreams,
+    openStreamCount(server),
+  );
+  controller.enqueue(helloFrame(`session-${server.streams.length}`));
+  return { ok: true, status: 200, body };
+};
+
+const installFetch = (server: FakeServer): void => {
+  globalThis.fetch = vi.fn(async (url: string, init?: RequestInit) => {
+    if (url === USER_STREAM_URL) {
+      if (server.isDown) throw new Error("connection refused");
+      return openUserStream(server, init!.signal!);
+    }
+    const headers = init?.headers as Record<string, string>;
+    server.subscriptions.push({
+      pageId: url.slice(SUBSCRIBE_URL_PREFIX.length),
+      sessionId: headers[SESSION_HEADER]!,
+    });
+    return { ok: true, status: 200 };
+  }) as unknown as typeof fetch;
+};
+
+const settle = async (): Promise<void> => {
+  await vi.advanceTimersByTimeAsync(0);
+  await nextTick();
+  await vi.advanceTimersByTimeAsync(0);
+};
+
+const realFetch = globalThis.fetch;
+let loggedIn = ref(false);
+let server: FakeServer;
+
+const loadApi = async (): Promise<UserRealtimeApi> => {
+  const module = await import(
+    "../layers/dms-core/app/composables/realtime/useUserRealtime"
+  );
+  return module.useUserRealtime();
+};
+
+const lastStream = (): FakeStream => server.streams[server.streams.length - 1]!;
+
+beforeEach(() => {
+  vi.resetModules();
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  vi.stubEnv("SSR", false);
+  vi.stubGlobal("ref", ref);
+  vi.stubGlobal("watch", watch);
+  vi.stubGlobal("useDmsState", (_key: string, init: () => unknown) =>
+    ref(init()),
+  );
+  vi.stubGlobal("useDmsRuntimeConfig", () => ({
+    public: { dms: { baseURL: BASE_URL } },
+  }));
+  vi.stubGlobal("useUserSession", () => ({ loggedIn }));
+  vi.stubGlobal("useSessionRecovery", () => ({
+    refreshSession: async () => true,
+    redirectToAuth: async () => {},
+  }));
+  server = { streams: [], subscriptions: [], maxOpenStreams: 0, isDown: false };
+  installFetch(server);
+  // Fresh per test: the singleton of a previous test keeps watching its own.
+  loggedIn = ref(true);
+});
+
+afterEach(async () => {
+  loggedIn.value = false;
+  await settle();
+  globalThis.fetch = realFetch;
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+});
+
+describe("useUserRealtime reconnection", () => {
+  it("reconnects with backoff when the server ends the stream, then resubscribes the page", async () => {
+    const api = await loadApi();
+    await settle();
+    await api.setPage(PAGE_ID);
+    expect(api.sessionId.value).toBe("session-1");
+    expect(server.subscriptions).toEqual([
+      { pageId: PAGE_ID, sessionId: "session-1" },
+    ]);
+
+    lastStream().end();
+    await settle();
+    expect(api.sessionId.value).toBeUndefined();
+    await vi.advanceTimersByTimeAsync(INITIAL_DELAY_MS - 1);
+    expect(server.streams).toHaveLength(1);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await settle();
+    expect(server.streams).toHaveLength(2);
+    expect(api.sessionId.value).toBe("session-2");
+    expect(server.subscriptions).toEqual([
+      { pageId: PAGE_ID, sessionId: "session-1" },
+      { pageId: PAGE_ID, sessionId: "session-2" },
+    ]);
+  });
+
+  it("backs off further while the server stays unreachable", async () => {
+    await loadApi();
+    await settle();
+    server.isDown = true;
+
+    lastStream().end();
+    await settle();
+    await vi.advanceTimersByTimeAsync(INITIAL_DELAY_MS);
+    await settle();
+    expect(vi.mocked(globalThis.fetch)).toHaveBeenCalledTimes(2);
+
+    server.isDown = false;
+    await vi.advanceTimersByTimeAsync(SECOND_DELAY_MS - 1);
+    expect(server.streams).toHaveLength(1);
+    await vi.advanceTimersByTimeAsync(1);
+    await settle();
+    expect(server.streams).toHaveLength(2);
+    expect(lastStream().isOpen()).toBe(true);
+  });
+
+  it("does not reconnect after an intentional close", async () => {
+    await loadApi();
+    await settle();
+    const stream = lastStream();
+
+    loggedIn.value = false;
+    await settle();
+    expect(stream.signal.aborted).toBe(true);
+
+    await vi.advanceTimersByTimeAsync(LONG_WAIT_MS);
+    await settle();
+    expect(server.streams).toHaveLength(1);
+  });
+
+  it("never holds more than one stream at a time", async () => {
+    await loadApi();
+    await settle();
+
+    for (let cycle = 0; cycle < 3; cycle += 1) {
+      lastStream().end();
+      await settle();
+      await vi.advanceTimersByTimeAsync(INITIAL_DELAY_MS);
+      await settle();
+    }
+    loggedIn.value = false;
+    await settle();
+    loggedIn.value = true;
+    await settle();
+
+    expect(server.streams).toHaveLength(5);
+    expect(server.maxOpenStreams).toBe(1);
+    expect(openStreamCount(server)).toBe(1);
+  });
+});

package/frontend-vue/tests/shortcuts-aggregate.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const finderShortcut = {
+  id: "finder.open",
+  keys: ["enter"],
+  description: "Open",
+};
+
+vi.mock("#shortcuts-aggregated", () => ({
+  default: [
+    {
+      component: "Tab",
+      shortcuts: [{ id: "tab.next", keys: ["ctrl", "tab"], description: "" }],
+    },
+    { component: "Finder", shortcuts: [finderShortcut] },
+  ],
+}));
+
+describe("the shortcuts plugin", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("registers every module's registry from the aggregate, not only dms-ui's", async () => {
+    const registered: Array<[string, unknown]> = [];
+    vi.stubGlobal("defineDmsPlugin", (setup: () => void) => setup);
+    vi.stubGlobal("useShortcutRegistry", () => ({
+      registerShortcut: (component: string, shortcut: unknown) =>
+        registered.push([component, shortcut]),
+    }));
+    const { default: setup } = await import(
+      "../layers/dms-ui/app/plugins/shortcuts"
+    );
+    (setup as () => void)();
+    expect(registered.map(([component]) => component)).toEqual([
+      "Tab",
+      "Finder",
+    ]);
+    expect(registered[1]?.[1]).toEqual(finderShortcut);
+  });
+});

package/frontend-vue/vitest.config.ts

@@ -9,6 +9,10 @@ export default defineConfig({
       "#dms-core": resolve(__dirname, "layers/dms-core"),
       "#dms-ui": resolve(__dirname, "layers/dms-ui"),
       "#dms-layout": resolve(__dirname, "layers/dms-layout"),
+      "#shortcuts-aggregated": resolve(
+        __dirname,
+        "layers/dms-ui/app/config/shortcuts-registry.ts",
+      ),
     },
   },
   esbuild: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/dms.git"
@@ -36,7 +36,7 @@
     "@antelopejs/interface-data-api": ">=0.1.9 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.3.2 <0.4.0",
+    "@antelopejs/interface-dms": ">=0.3.3 <0.4.0",
     "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.3 <1.0.0",
     "archiver": "^7.0.1",

package/skills/dms-dev/SKILL.md

@@ -3,7 +3,7 @@ name: dms-dev
 description: Starts, stops, or restarts the AntelopeJS DMS backend and Inertia frontend.
 category: tooling
 tags: [dev-server, restart, backend, inertia, workflow]
-allowed-tools: Bash(bash:*), Bash(pkill:*), Bash(pgrep:*), Bash(tail:*), Bash(curl:*), Read, Write
+allowed-tools: Bash(bash:*), Bash(pgrep:*), Bash(tail:*), Bash(curl:*), Read, Write
 ---
 
 # dms-dev
@@ -14,6 +14,15 @@ Owns the dev-server lifecycle for an AntelopeJS DMS project. Ships with the
 resolve the project path. For authoring see the sibling **dms**, **dms-module**,
 **dms-pages**, and **dms-auth** skills.
 
+## Never from inside the DMS
+
+An agent that runs inside the DMS -- the dms-ai assistant, whose sidecar the backend
+spawns, or any process started by these dev servers -- must **not** run `stop`, `restart`
+or `start`: stopping the backend takes the agent down with it. Rely on hot reload (the
+backend's `-w` watcher and the frontend's live layer resync) and, when a change needs a
+full restart, ask the user to run it. The script refuses to stop a process tree that
+contains the shell calling it.
+
 ## Choose the process manager
 
 In an Amp orb, use the repository's `.amp/services.yaml` with `amp orb services ensure`,
@@ -21,18 +30,18 @@ or `amp orb service start` for a one-off service. Inspect readiness with service
 HTTP checks; share the returned portal URL for browser review. The bundled detached-shell
 script is for local shells, not managed orbs: its processes do not survive orb updates.
 
-## Why full restart, not hot reload
+## Hot reload first, restart when it cannot apply
 
 The DMS has two coupled processes, both started from the DMS backend package directory:
 
-- **Backend**: the AntelopeJS project — `ajs project dev -w` (`ajs project run` is the legacy alias). Listens on `http://localhost:5010`. Ready when the log emits `Server started, listening on http://localhost:5010`.
-- **Frontend**: the `@antelopejs/dms-frontend` loader — `ajs dms dev`. It auto-discovers the running backend via `.antelope/dev.json`, so `-b <backend-url>` is optional. Listens on `http://localhost:3001`. Ready when the log emits `Local: http://localhost:3001/`.
+- **Backend**: the AntelopeJS project — `ajs project dev -w` (`ajs project run` is the legacy alias). Ready when the log emits `Server started, listening on <url>`; the real endpoint is recorded in the project's `.antelope/dev.json` (`servers.api.endpoints`), `http://localhost:5010` by default.
+- **Frontend**: the `@antelopejs/dms-frontend` loader — `ajs dms dev`. It auto-discovers the running backend via `.antelope/dev.json`, so `-b <backend-url>` is optional. Ready when the log emits `Server ready on <url>` (`http://localhost:3001` by default).
 
 By default the script runs each via the project's `pnpm dev` / `pnpm frontend:dev` scripts — a convention our playground projects adopt that expands to the two commands above. Those script names aren't shipped by the DMS, so if a project starts its servers differently, override the actual commands with the `DMS_BACK_CMD` / `DMS_FRONT_CMD` env vars (the script reads them; readiness detection and process cleanup already cover `ajs`, `ajs dms`, and the loader's Node entry point directly).
 
 Order matters: start the backend first and wait for ready, **then** start the frontend. The frontend materializes the backend's layers into a `~/.antelopejs/dms-frontend/` workspace at startup; starting it before the backend is up produces stale or empty layer copies.
 
-The docs claim dev-mode watchers normally propagate edits (backend `-w` recompile, live layer resync into `~/.antelopejs/dms-frontend/`) — and they often do. But the failure modes are silent: `RegisterModule` can throw "already registered" on rebuild, and a missed resync serves a stale layer copy that *looks* like your bug. The documented troubleshooting recipe — and this skill's contract as an agent — is: **full restart both, backend first, before verifying any change**. A 60-second restart beats debugging a phantom.
+Dev-mode watchers propagate most edits (backend `-w` recompile, live layer resync into `~/.antelopejs/dms-frontend/`). Their failure modes are silent, though: `RegisterModule` can throw "already registered" on rebuild, and a missed resync serves a stale layer copy that *looks* like your bug. So restart only when hot reload cannot apply the change -- a new module or dependency, a config edit, a backend log showing a failed rebuild, or a behaviour that still looks stale after the watcher reported the rebuild -- and then restart both, backend first. Never restart from inside the DMS (see above).
 
 ## Resolving the backend path (do this FIRST, eagerly)
 
@@ -71,27 +80,29 @@ bundled script lives at `scripts/dms-dev.sh` under it. Subcommands:
 
 | Command           | Use when                                                                |
 |-------------------|-------------------------------------------------------------------------|
-| `restart`         | After any source edit, or unconditionally if you don't know the state.  |
+| `restart`         | When hot reload cannot apply a change, or the state is unknown. Never from inside the DMS. |
 | `start`           | When you're sure nothing is running (fresh shell / after `stop`).       |
-| `stop`            | Before walking away, before destructive operations, on session cleanup. |
+| `stop`            | Before walking away, before destructive operations, on session cleanup. Never from inside the DMS. |
 | `status`          | Quickly check what's running.                                           |
 | `back-log [N]`    | Read the last N (default 60) backend log lines. Use to diagnose boot.   |
 | `front-log [N]`   | Same for the frontend log.                                              |
 
-The script writes the long-running server logs to `/tmp/dms-back.log` and `/tmp/dms-front.log`. The `Bash` tool invocation completes as soon as both servers print their ready strings (or after a 180 s timeout per server — worst case ~6 minutes for a restart; override with `DMS_DEV_TIMEOUT`). The servers themselves keep running detached via `setsid nohup` so they survive the Bash call exiting.
+The script writes the long-running server logs to `/tmp/dms-back.log` and `/tmp/dms-front.log`. The `Bash` tool invocation completes as soon as both servers print their ready strings, and reports the URLs they really listen on. It fails fast when a server process exits before becoming ready, and otherwise after a 180 s timeout per server (override with `DMS_DEV_TIMEOUT`). The servers keep running detached in their own session (`setsid`, or perl's `POSIX::setsid` on macOS) so they survive the Bash call exiting.
+
+`stop` and `restart` only touch the project in `DMS_BACK_DIR`: the pids the script starts are recorded in `DMS_BACK_DIR/.antelope/dms-dev.pid`, and without that file it only matches dev processes whose working directory or command line lies under `DMS_BACK_DIR`. Each process gets SIGTERM, then SIGKILL after `DMS_DEV_STOP_GRACE` seconds (default 10). Other projects' dev servers on the machine are never signalled.
 
 ## When to reach for the subcommands
 
-- The user edits any `.ts` or `.vue` file under the DMS backend package or under a DMS module's `src/` or `frontend-vue/` and then wants to test the change live. Run `restart` unconditionally — don't try hot reload.
-- The user says "restart the dms", "restart servers", "reload", or "test it now". Run `restart`.
+- The user edits a `.ts` or `.vue` file under the DMS backend package or under a DMS module's `src/` or `frontend-vue/` and wants to test the change live. Let hot reload apply it first; run `restart` only when it cannot (see above). From inside the DMS, never run it.
+- The user says "restart the dms", "restart servers", "reload", or "test it now". Run `restart` -- unless you run inside the DMS, in which case say so and let the user restart.
 - A browser smoke test fails in a way that looks like stale state. Run `restart` before diagnosing.
 - The user asks "is the dms running?". Run `status`.
-- A boot fails (backend never prints "Server started" or frontend never prints "Local:"). Print the relevant `back-log` / `front-log` tail to diagnose; common causes include `RegisterModule … already registered` (a previous stop failed — run `stop` then `restart`), port already in use (kill the listed PID), or a missing dependency (run `pnpm install` in the offending module).
-- **You are handing off to the user for manual testing** (e.g. a plan phase whose acceptance criterion is "user verifies in browser"). Run `restart` yourself first, wait for both ready strings, and only *then* tell the user what to click. Never ask the user to start the servers themselves — that's the whole reason this skill exists.
+- A boot fails (backend never prints "Server started" or frontend never prints "Server ready on"). Print the relevant `back-log` / `front-log` tail to diagnose; common causes include `RegisterModule … already registered` (a previous stop failed — run `stop` then `restart`), port already in use (kill the listed PID), or a missing dependency (run `pnpm install` in the offending module).
+- **You are handing off to the user for manual testing** (e.g. a plan phase whose acceptance criterion is "user verifies in browser"). Run `restart` yourself first, wait for both ready strings, and only *then* tell the user what to click. Never ask the user to start the servers themselves — that's the whole reason this skill exists. The one exception is an agent running inside the DMS, which already runs on live servers.
 
 ## Common pitfalls
 
-- **Zombie frontend processes.** The frontend CLI can spawn child processes that survive `pkill ajs`. The script's `stop` does an automatic second-pass kill via `pgrep | xargs kill -9` to catch them. If `start` reports servers already running, run `stop` and check that `status` shows `(none)` before starting again.
+- **Zombie frontend processes.** The frontend CLI spawns child processes. The script's `stop` signals the whole session and process tree it started, and SIGKILLs whatever survives the grace period. If `start` reports servers already running, run `stop` and check that `status` shows `(none)` before starting again.
 - **Backend exits with "Module already registered".** Means a previous instance is still holding the registration. Run `stop` to clear it, then `restart`.
 - **Frontend's "auth redirect" 302** on `/modules/...` URLs is **normal** — it's the auth-protected admin routes. The frontend layer is loaded correctly even when curl returns 302. Don't restart on this alone; have the user log in.
 - **Don't run `start` or `restart` more than once concurrently** in a single session — the second invocation will hit a port/lock conflict. If multiple background Bash tasks are queued, use the foreground `restart`.
@@ -101,7 +112,8 @@ The script writes the long-running server logs to `/tmp/dms-back.log` and `/tmp/
 
 ## Don't
 
-- Don't try to hot-reload by editing files and refreshing the browser without `restart`. It will work intermittently and waste debugging cycles on phantom issues.
-- Don't `pkill -9 node` — it kills unrelated processes. The script targets specific patterns (`antelope-runner`, `ajs project run|dev`, `ajs dms dev`, and paths ending in `dms-frontend/dist/index.js dev`).
+- Don't keep debugging a behaviour that looks stale after hot reload: that is the case for `restart` (from outside the DMS).
+- Don't run `stop`, `restart` or `start` from an agent running inside the DMS (e.g. dms-ai): it would stop its own host.
+- Don't `pkill` dev servers by name (`pkill -9 node`, `pkill -f antelope-runner`): other projects on the machine run the same processes. Use the script, which only signals the processes of `DMS_BACK_DIR`.
 - Don't hardcode a backend path into a session. Always resolve via memory-or-prompt so the skill works across projects.
-- Don't ask the user to start or restart the servers themselves before manual testing. You have the script — run it, wait for ready, then hand off. Asking the user to do it defeats the point of the skill and breaks the testing loop.
+- Don't ask the user to start or restart the servers themselves before manual testing. You have the script — run it, wait for ready, then hand off. Asking the user to do it defeats the point of the skill and breaks the testing loop. (An agent inside the DMS is the exception: it never restarts its own host.)