@cnstra/devtools-server 3.0.0 → 3.5.0

package/dist/index.cjs

@@ -1,12 +1,258 @@
 'use strict';
 
 var devtoolsDto = require('@cnstra/devtools-dto');
+var persistDto = require('@cnstra/persist-dto');
 var persist = require('@cnstra/persist');
+var crypto = require('crypto');
+var http = require('http');
+var fs = require('fs');
+var path = require('path');
+var module$1 = require('module');
+var ws = require('ws');
 
 // src/index.ts
-var CNSDevToolsServer = class {
-  constructor(repository, stimulationRepository = new persist.CNSInMemoryStimulationRepository()) {
+
+// src/pollingTransport.ts
+var createSession = () => {
+  let queued = [];
+  let wake;
+  const session = {
+    client: {
+      // `readyState` 1 is what `liveSockets` checks before routing an action
+      // to a participant: a polling session is reachable as long as it has
+      // not expired, and expiry removes it outright.
+      readyState: 1,
+      send(data) {
+        queued.push(data);
+        wake?.();
+      }
+    },
+    take() {
+      const out = queued;
+      queued = [];
+      return out;
+    },
+    async wait(timeoutMs) {
+      if (queued.length) return session.take();
+      await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          wake = void 0;
+          resolve();
+        }, timeoutMs);
+        wake = () => {
+          clearTimeout(timer);
+          wake = void 0;
+          resolve();
+        };
+      });
+      return session.take();
+    },
+    lastSeenAt: Date.now()
+  };
+  return session;
+};
+var CNSDevToolsPollingTransport = class {
+  constructor(server, options = {}) {
+    this.server = server;
+    this.sessions = /* @__PURE__ */ new Map();
+    this.waitMs = options.waitMs ?? 25e3;
+    this.sessionTtlMs = options.sessionTtlMs ?? 6e4;
+  }
+  /** Sessions currently held. Exposed so a leak is observable in tests. */
+  get sessionCount() {
+    return this.sessions.size;
+  }
+  /** Deliver one message from a participant. */
+  async post(sessionId, body) {
+    const session = this.session(sessionId);
+    await this.server.handleMessage(session.client, body);
+  }
+  /** Drain what is queued for a participant, parking if nothing is. */
+  async poll(sessionId) {
+    const session = this.session(sessionId);
+    return session.wait(this.waitMs);
+  }
+  /** Forget a participant and take it out of the server's routing. */
+  close(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+    this.sessions.delete(sessionId);
+    this.server.removeClient(session.client);
+  }
+  session(sessionId) {
+    this.sweep();
+    const existing = this.sessions.get(sessionId);
+    if (existing) {
+      existing.lastSeenAt = Date.now();
+      return existing;
+    }
+    const created = createSession();
+    this.sessions.set(sessionId, created);
+    return created;
+  }
+  /** Drop sessions that stopped polling. Silence is the only signal they give. */
+  sweep() {
+    const cutoff = Date.now() - this.sessionTtlMs;
+    for (const [id, session] of this.sessions) {
+      if (session.lastSeenAt < cutoff) {
+        this.sessions.delete(id);
+        this.server.removeClient(session.client);
+      }
+    }
+  }
+};
+var _require = module$1.createRequire(path.join(process.cwd(), "package.json"));
+function findPanelUIDir() {
+  try {
+    const pkg = _require.resolve("@cnstra/devtools-panel-ui/package.json");
+    return path.join(path.dirname(pkg), "dist");
+  } catch {
+  }
+  try {
+    const here = path.dirname(_require.resolve("@cnstra/devtools-server/package.json"));
+    const monorepoPath = path.join(here, "..", "..", "devtools-panel-ui", "dist");
+    if (fs.existsSync(path.join(monorepoPath, "index.html"))) return monorepoPath;
+  } catch {
+  }
+  return null;
+}
+var MIME = {
+  html: "text/html",
+  js: "application/javascript",
+  css: "text/css",
+  svg: "image/svg+xml",
+  png: "image/png",
+  woff2: "font/woff2"
+};
+function serveStatic(panelUIDir) {
+  return (_req, res) => {
+    const safe = (_req.url ?? "/").split("?")[0].replace(/\.\./g, "");
+    const file = safe === "/" ? "/index.html" : safe;
+    const full = path.join(panelUIDir, file);
+    if (fs.existsSync(full) && full.startsWith(panelUIDir)) {
+      const ext = full.split(".").pop() ?? "";
+      res.writeHead(200, { "Content-Type": MIME[ext] ?? "text/plain" });
+      res.end(fs.readFileSync(full));
+    } else {
+      const idx = path.join(panelUIDir, "index.html");
+      if (fs.existsSync(idx)) {
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(fs.readFileSync(idx));
+      } else {
+        res.writeHead(503);
+        res.end("DevTools UI not built. Run: npm run build --workspace=@cnstra/devtools-panel-ui");
+      }
+    }
+  };
+}
+async function startCNSDevTools(cns, registry, options = {}) {
+  const port = options.port ?? 3141;
+  const appId = options.appId ?? "app";
+  const logEnabled = options.consoleLogEnabled ?? false;
+  const panelUIDir = findPanelUIDir();
+  if (!panelUIDir) {
+    console.warn(
+      "\n\u26A0\uFE0F  CNStra DevTools UI not found.\n   WebSocket server will start but the UI will not be served.\n   Install @cnstra/devtools-panel-ui or build it from the monorepo.\n"
+    );
+  }
+  const { CNSDevToolsServerRepositoryInMemory } = await import('@cnstra/devtools-server-repository-in-memory');
+  const dtServer = new CNSDevToolsServer(
+    new CNSDevToolsServerRepositoryInMemory(),
+    options.stimulationRepository,
+    options.actions,
+    options.ui,
+    options.scheduledStimulationReader
+  );
+  const polling = new CNSDevToolsPollingTransport(dtServer, options.polling);
+  const staticHandler = panelUIDir ? serveStatic(panelUIDir) : (_, res) => {
+    res.writeHead(503);
+    res.end("DevTools UI not available.");
+  };
+  const readBody = (req) => new Promise((resolve) => {
+    let body = "";
+    req.on("data", (chunk) => body += chunk);
+    req.on("end", () => resolve(body));
+  });
+  const httpServer = http.createServer(
+    async (req, res) => {
+      if (req.url?.startsWith("/__cnstra/poll")) {
+        res.setHeader("access-control-allow-origin", "*");
+        res.setHeader("access-control-allow-methods", "GET,POST,DELETE,OPTIONS");
+        res.setHeader("access-control-allow-headers", "content-type");
+        if (req.method === "OPTIONS") {
+          res.writeHead(204);
+          return res.end();
+        }
+        const url2 = new URL(req.url, "http://localhost");
+        const sessionId = url2.searchParams.get("sessionId");
+        if (!sessionId) {
+          res.writeHead(400);
+          return res.end("sessionId required");
+        }
+        if (req.method === "POST") {
+          const body = await readBody(req);
+          await polling.post(sessionId, body);
+          res.writeHead(204);
+          return res.end();
+        }
+        if (req.method === "DELETE") {
+          polling.close(sessionId);
+          res.writeHead(204);
+          return res.end();
+        }
+        const messages = await polling.poll(sessionId);
+        res.writeHead(200, { "content-type": "application/json" });
+        return res.end(JSON.stringify({ messages }));
+      }
+      return staticHandler(req, res);
+    }
+  );
+  const wss = new ws.WebSocketServer({ server: httpServer });
+  wss.on("connection", (ws) => {
+    ws.on("message", async (data) => {
+      try {
+        await dtServer.handleMessage(ws, data.toString());
+      } catch {
+      }
+    });
+    ws.on("close", () => dtServer.removeClient(ws));
+  });
+  await new Promise((resolve) => httpServer.listen(port, resolve));
+  const url = `http://localhost:${port}`;
+  const { CNSDevTools } = await import('@cnstra/devtools');
+  const { CNSDevToolsTransportWs } = await import('@cnstra/devtools-transport-ws');
+  const transport = new CNSDevToolsTransportWs({ url: `ws://localhost:${port}` });
+  const devtools = new CNSDevTools(appId, transport, {
+    appName: appId,
+    consoleLogEnabled: logEnabled
+  });
+  devtools.registerCNS(cns, registry);
+  if (logEnabled || process.stdout.isTTY) {
+    console.log(`
+\u{1F9E0} CNStra DevTools: ${url}
+`);
+  }
+  const shouldOpen = options.open ?? process.stdout.isTTY;
+  if (shouldOpen) {
+    const { exec } = await import('child_process');
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    exec(`${cmd} ${url}`);
+  }
+  return {
+    url,
+    stop: () => {
+      dtServer.stop();
+      wss.close();
+      httpServer.close();
+    }
+  };
+}
+
+// src/index.ts
+var CNSDevToolsServer = class _CNSDevToolsServer {
+  constructor(repository, stimulationRepository = new persist.CNSInMemoryStimulationRepository(), actions = [], ui = {}, scheduledStimulationReader) {
     this.repository = repository;
+    this.scheduledStimulationReader = scheduledStimulationReader;
     /** WebSocket → appId (for app clients) */
     this.appSockets = /* @__PURE__ */ new Map();
     /** appId → WebSocket[] (one app may have multiple CNS instances) */
@@ -16,6 +262,60 @@ var CNSDevToolsServer = class {
     this.lastCpuUsage = process.cpuUsage();
     this.lastCpuTime = Date.now();
     this.stimulationRepository = stimulationRepository;
+    this.actions = [...actions, this.createSocketAction()];
+    this.ui = ui;
+  }
+  /**
+   * Run an action through the chain and flatten the three outcomes into one
+   * value: `true` acted, `false` nobody took it, a string is the reason a link
+   * failed. A link that throws must not escape into the socket's message
+   * handler, where nothing answers the panel.
+   */
+  async carryOut(action) {
+    try {
+      return await persistDto.runCNSDevToolsAction(this.actions, action) || false;
+    } catch (error) {
+      return error instanceof Error ? error.message : String(error);
+    }
+  }
+  /**
+   * The fallback link: forward the action to the app over its own socket. This
+   * is what reaches a CNS running in-process with no queue behind it — and it
+   * is why the chain always ends here rather than rejecting.
+   */
+  createSocketAction() {
+    return async (action, next) => {
+      if (action.type === "command") return next();
+      const appSockets = await this.resolveScopeApp(action.scopeName);
+      if (!appSockets) return next();
+      const payload = action.type === "resume" ? JSON.stringify({
+        type: "cns.stimulation.resume",
+        requestId: action.requestId,
+        scopeName: action.scopeName,
+        stimulationId: action.stimulationId,
+        stimulationAttemptId: action.stimulationAttemptId,
+        attemptNumber: action.attemptNumber,
+        entry: action.entry,
+        progress: action.progress,
+        replayOf: action.replayOf,
+        options: action.options
+      }) : JSON.stringify({
+        type: "cns.stimulation.launch",
+        requestId: action.requestId,
+        scopeName: action.scopeName,
+        stimulationId: action.stimulationId,
+        stimulationAttemptId: action.stimulationAttemptId,
+        entry: action.entry,
+        replayOf: action.replayOf,
+        options: action.options
+      });
+      for (const appWs of appSockets) {
+        try {
+          appWs.send(payload);
+        } catch {
+        }
+      }
+    };
   }
   // ─── Message entry point ─────────────────────────────────────────────────
   async handleMessage(ws, raw) {
@@ -49,9 +349,6 @@ var CNSDevToolsServer = class {
       case "topology.query":
         await this.handleTopologyQuery(ws, msg.requestId, msg.cnsId, msg.appId);
         break;
-      case "replay.start":
-        await this.handleReplayStart(ws, msg);
-        break;
       case "stimulation.retry":
         await this.handleStimulationRetry(ws, msg);
         break;
@@ -70,6 +367,15 @@ var CNSDevToolsServer = class {
       case "cns.stimulation.detail":
         await this.handleStimulationDetail(ws, msg);
         break;
+      case "cns.scheduled.list":
+        await this.handleScheduledStimulationsList(ws, msg);
+        break;
+      case "stimulation.command":
+        await this.handleStimulationCommand(ws, msg);
+        break;
+      case "stimulation.launch":
+        await this.handleStimulationLaunch(ws, msg);
+        break;
     }
   }
   /**
@@ -90,8 +396,8 @@ var CNSDevToolsServer = class {
     const limit = typeof msg.limit === "number" ? msg.limit : 50;
     const opts = { cursor: msg.cursor, limit };
     const store = this.stimulationRepository;
-    const page = persist.supportsRosterQuery(store) ? await store.queryRoster(filter, opts) : persist.keysetPage(
-      (await persist.loadRosterEntries(store, filter)).map((e) => e.row),
+    const page = persist.supportsCNSRosterQuery(store) ? await store.queryRoster(filter, opts) : persist.cnsKeysetPage(
+      (await persist.loadCNSRosterEntries(store, filter)).map((e) => e.row),
       opts
     );
     this.send(ws, {
@@ -105,7 +411,7 @@ var CNSDevToolsServer = class {
   async handleStimulationsFacets(ws, msg) {
     const filter = this.toRosterFilter(msg.scopeName, msg.filter);
     const store = this.stimulationRepository;
-    const facets = persist.supportsRosterQuery(store) ? await store.queryFacets(filter, { metricPath: msg.metricPath }) : persist.computeRosterFacets(await persist.loadRosterEntries(store, filter), {
+    const facets = persist.supportsCNSRosterQuery(store) ? await store.queryFacets(filter, { metricPath: msg.metricPath }) : persist.computeCNSRosterFacets(await persist.loadCNSRosterEntries(store, filter), {
       metricPath: msg.metricPath
     });
     this.send(ws, {
@@ -114,17 +420,62 @@ var CNSDevToolsServer = class {
       facets
     });
   }
+  async handleStimulationLaunch(ws, msg) {
+    const newStimulationId = `${msg.entry.collateralName}-${crypto.randomUUID()}`;
+    const handled = await this.carryOut({
+      type: "launch",
+      requestId: msg.requestId,
+      stimulationId: newStimulationId,
+      stimulationAttemptId: devtoolsDto.buildCNSAttemptId(newStimulationId, 1),
+      entry: msg.entry
+    });
+    if (handled === true) {
+      this.send(ws, { type: "stimulation.launch.accepted", requestId: msg.requestId, newStimulationId });
+      return;
+    }
+    this.send(ws, {
+      type: "stimulation.launch.rejected",
+      requestId: msg.requestId,
+      reason: handled === false ? "no runtime accepted the launch" : handled
+    });
+  }
+  async handleStimulationCommand(ws, msg) {
+    const handled = await this.carryOut({
+      type: "command",
+      requestId: msg.requestId,
+      stimulationId: msg.stimulationId,
+      command: msg.command
+    });
+    if (handled === true) {
+      this.send(ws, { type: "stimulation.command.accepted", requestId: msg.requestId, stimulationId: msg.stimulationId });
+      return;
+    }
+    this.send(ws, {
+      type: "stimulation.command.rejected",
+      requestId: msg.requestId,
+      stimulationId: msg.stimulationId,
+      reason: handled === false ? `no runtime accepted the ${msg.command.name} command` : handled
+    });
+  }
+  async handleScheduledStimulationsList(ws, msg) {
+    const reader = this.scheduledStimulationReader;
+    const page = reader ? await reader.list(msg.filter ?? {}, msg.cursor ?? null, msg.limit ?? 50) : { rows: [], schedules: [], types: [], nextCursor: null };
+    this.send(ws, {
+      type: "cns.scheduled.list.result",
+      requestId: msg.requestId,
+      available: reader !== void 0,
+      ...page
+    });
+  }
   async handleStimulationDetail(ws, msg) {
     const attempts = await this.stimulationRepository.getAttempts(
       msg.stimulationId
     );
-    const tasks = [];
-    for (const a of attempts) {
-      const ts = await this.stimulationRepository.getTasks(
-        a.stimulationAttemptId
-      );
-      tasks.push(...ts);
-    }
+    const attemptIds = attempts.map((a) => a.stimulationAttemptId);
+    const store = this.stimulationRepository;
+    const tasks = store.getTasksFor ? await store.getTasksFor(attemptIds) : (await Promise.all(
+      attemptIds.map((id) => store.getTasks(id))
+    )).flat();
     this.send(ws, {
       type: "cns.stimulation.detail.result",
       requestId: msg.requestId,
@@ -142,18 +493,17 @@ var CNSDevToolsServer = class {
     const filter = this.toRosterFilter(msg.scopeName, msg.filter);
     const store = this.stimulationRepository;
     const limit = typeof msg.limit === "number" ? msg.limit : 200;
-    const page = persist.supportsRosterQuery(store) ? await store.queryRoster(filter, { limit }) : persist.keysetPage(
-      (await persist.loadRosterEntries(store, filter)).map((e) => e.row),
+    const page = persist.supportsCNSRosterQuery(store) ? await store.queryRoster(filter, { limit }) : persist.cnsKeysetPage(
+      (await persist.loadCNSRosterEntries(store, filter)).map((e) => e.row),
       { limit }
     );
-    const attempts = [];
-    const tasks = [];
-    for (const row of page.rows) {
-      const as = await store.getAttempts(row.stimulationId);
-      attempts.push(...as);
-      for (const a of as)
-        tasks.push(...await store.getTasks(a.stimulationAttemptId));
-    }
+    const skip = new Set(
+      Array.isArray(msg.skipDetailFor) ? msg.skipDetailFor : []
+    );
+    const ids = page.rows.map((row) => row.stimulationId).filter((id) => !skip.has(id));
+    const attempts = store.getAttemptsFor ? await store.getAttemptsFor(ids) : (await Promise.all(ids.map((id) => store.getAttempts(id)))).flat();
+    const attemptIds = attempts.map((a) => a.stimulationAttemptId);
+    const tasks = store.getTasksFor ? await store.getTasksFor(attemptIds) : (await Promise.all(attemptIds.map((id) => store.getTasks(id)))).flat();
     this.send(ws, {
       type: "cns.stimulations.snapshot.result",
       requestId: msg.requestId,
@@ -168,11 +518,27 @@ var CNSDevToolsServer = class {
   }
   removeClient(ws) {
     this.uiClients.delete(ws);
+    const appId = this.appSockets.get(ws);
     this.appSockets.delete(ws);
+    if (appId !== void 0) {
+      const sockets = this.appWsByAppId.get(appId);
+      if (sockets) {
+        sockets.delete(ws);
+        if (sockets.size === 0) this.appWsByAppId.delete(appId);
+      }
+    }
     if (this.uiClients.size === 0) this.stopMetrics();
   }
   async getActiveApps() {
-    return this.repository.listApps();
+    return _CNSDevToolsServer.appsOf(await this.repository.getTopology());
+  }
+  static appsOf(snapshots) {
+    const latest = /* @__PURE__ */ new Map();
+    for (const snapshot of snapshots) {
+      const known = latest.get(snapshot.appId);
+      if (!known || snapshot.timestamp > known.timestamp) latest.set(snapshot.appId, snapshot);
+    }
+    return [...latest.values()].map((snapshot) => ({ id: snapshot.appId, name: snapshot.appName, version: snapshot.version }));
   }
   stop() {
     this.stopMetrics();
@@ -201,16 +567,6 @@ var CNSDevToolsServer = class {
   }
   async handleTopology(ws, msg) {
     const { appId, cnsId, appName, version, timestamp, neurons, collaterals, dendrites } = msg;
-    const now = Date.now();
-    const app = {
-      id: appId,
-      name: appName,
-      version,
-      connectedAt: now,
-      lastSeenAt: now
-    };
-    await this.repository.upsertApp(app);
-    await this.repository.addCnsToApp(appId, cnsId);
     await this.repository.saveTopology({ appId, cnsId, appName, version, timestamp, neurons, collaterals, dendrites });
     this.appSockets.set(ws, appId);
     if (!this.appWsByAppId.has(appId)) this.appWsByAppId.set(appId, /* @__PURE__ */ new Set());
@@ -220,45 +576,31 @@ var CNSDevToolsServer = class {
       requestId: "__broadcast__",
       snapshots: await this.repository.getTopology(cnsId)
     };
-    this.broadcast({ type: "app.connected", app, topology: { cnsId, neurons, collaterals, dendrites } });
+    this.broadcast({ type: "app.connected", app: { id: appId, name: appName, version }, topology: { cnsId, neurons, collaterals, dendrites } });
     this.broadcastRaw(JSON.stringify(topologyBroadcast));
   }
   // ─── UI client query handlers ─────────────────────────────────────────────
   async handleClientConnect(ws) {
     this.addClient(ws);
-    this.send(ws, { type: "apps.result", requestId: "__init__", items: await this.repository.listApps() });
     this.send(ws, {
-      type: "topology.result",
-      requestId: "__init__",
-      snapshots: await this.repository.getTopology()
+      type: "ui.config",
+      // Five minutes unless told otherwise: the panel opens on what is
+      // happening now, not on everything that ever happened.
+      defaultWindowMs: this.ui.defaultWindowMs ?? 5 * 6e4,
+      ...this.ui
     });
+    const snapshots = await this.repository.getTopology();
+    this.send(ws, { type: "apps.result", requestId: "__init__", items: _CNSDevToolsServer.appsOf(snapshots) });
+    this.send(ws, { type: "topology.result", requestId: "__init__", snapshots });
   }
   async handleAppsQuery(ws, requestId) {
-    const items = await this.repository.listApps();
-    this.send(ws, { type: "apps.result", requestId, items });
+    this.send(ws, { type: "apps.result", requestId, items: await this.getActiveApps() });
   }
   async handleTopologyQuery(ws, requestId, cnsId, appId) {
     let snapshots = await this.repository.getTopology(cnsId);
     if (appId) snapshots = snapshots.filter((s) => s.appId === appId);
     this.send(ws, { type: "topology.result", requestId, snapshots });
   }
-  async handleReplayStart(ws, msg) {
-    const appId = msg.appId ?? (msg.cnsId ? await this.repository.findAppByCns(msg.cnsId) : void 0);
-    const appSockets = appId ? this.appWsByAppId.get(appId) : void 0;
-    if (!appSockets || appSockets.size === 0) {
-      this.send(ws, { type: "replay.rejected", replayId: msg.replayId, reason: "App not connected" });
-      return;
-    }
-    const newStimulationId = `${msg.stimulationId}-replay-${Date.now()}`;
-    this.send(ws, { type: "replay.accepted", replayId: msg.replayId, newStimulationId });
-    const payload = JSON.stringify(msg);
-    for (const appWs of appSockets) {
-      try {
-        appWs.send(payload);
-      } catch {
-      }
-    }
-  }
   // ─── Resumable actions (retry / clone), Phase 2b-2 ──────────────────────────────
   //
   // The UI's request is thin (a stimulationId). The CNS + name→ref registry live in
@@ -268,8 +610,22 @@ var CNSDevToolsServer = class {
   /** Resolve the app that owns a stimulation's scope, or reject if unreachable. */
   async resolveScopeApp(scopeName) {
     const appId = scopeName ? await this.repository.findAppByCns(scopeName) : void 0;
-    const sockets = appId ? this.appWsByAppId.get(appId) : void 0;
-    return sockets && sockets.size > 0 ? sockets : void 0;
+    return appId ? this.liveSockets(appId) : void 0;
+  }
+  /**
+   * Sockets of `appId` that can still receive a command, or `undefined` when
+   * none can. `close` is not always dispatched before we route (a half-dead
+   * socket, an embedding that never calls `removeClient`), so being registered
+   * is not proof of being reachable — readyState is.
+   */
+  liveSockets(appId) {
+    const sockets = this.appWsByAppId.get(appId);
+    if (!sockets || sockets.size === 0) return void 0;
+    const open = /* @__PURE__ */ new Set();
+    for (const ws of sockets) {
+      if (ws.readyState === 1) open.add(ws);
+    }
+    return open.size > 0 ? open : void 0;
   }
   async handleStimulationRetry(ws, msg) {
     const reject = (reason) => this.send(ws, {
@@ -282,19 +638,15 @@ var CNSDevToolsServer = class {
     if (!stim) return reject("unknown stimulation");
     if (stim.progress.tasks.length === 0)
       return reject("nothing to resume (empty frontier)");
-    const appSockets = await this.resolveScopeApp(stim.scopeName);
-    if (!appSockets) return reject("app not connected");
     const attempts = await this.stimulationRepository.getAttempts(msg.stimulationId);
-    const nextAttempt = attempts.length + 1;
-    const stimulationAttemptId = devtoolsDto.buildAttemptId(msg.stimulationId, nextAttempt);
-    this.send(ws, {
-      type: "stimulation.retry.accepted",
-      requestId: msg.requestId,
-      stimulationId: msg.stimulationId,
-      newStimulationAttemptId: stimulationAttemptId
-    });
-    const payload = JSON.stringify({
-      type: "cns.stimulation.resume",
+    const latest = attempts.reduce(
+      (max, a) => !max || a.attemptNumber > max.attemptNumber ? a : max,
+      void 0
+    );
+    const nextAttempt = (latest?.attemptNumber ?? 0) + 1;
+    const stimulationAttemptId = devtoolsDto.buildCNSAttemptId(msg.stimulationId, nextAttempt);
+    const handled = await this.carryOut({
+      type: "resume",
       requestId: msg.requestId,
       scopeName: stim.scopeName,
       stimulationId: msg.stimulationId,
@@ -302,14 +654,21 @@ var CNSDevToolsServer = class {
       attemptNumber: nextAttempt,
       entry: stim.entry,
       progress: stim.progress,
+      // Provenance: which attempt this retry continues from.
+      replayOf: latest?.stimulationAttemptId,
       options: msg.options
     });
-    for (const appWs of appSockets) {
-      try {
-        appWs.send(payload);
-      } catch {
-      }
+    if (handled !== true) {
+      return reject(
+        handled === false ? "no runtime accepted the retry" : `retry failed: ${handled}`
+      );
     }
+    this.send(ws, {
+      type: "stimulation.retry.accepted",
+      requestId: msg.requestId,
+      stimulationId: msg.stimulationId,
+      newStimulationAttemptId: stimulationAttemptId
+    });
   }
   async handleStimulationClone(ws, msg) {
     const reject = (reason) => this.send(ws, {
@@ -320,32 +679,39 @@ var CNSDevToolsServer = class {
     });
     const stim = await this.stimulationRepository.getStimulation(msg.stimulationId);
     if (!stim) return reject("unknown stimulation");
-    const appSockets = await this.resolveScopeApp(stim.scopeName);
-    if (!appSockets) return reject("app not connected");
-    const newStimulationId = devtoolsDto.buildCloneId(msg.stimulationId);
-    const stimulationAttemptId = devtoolsDto.buildAttemptId(newStimulationId, 1);
-    this.send(ws, {
-      type: "stimulation.clone.accepted",
-      requestId: msg.requestId,
-      stimulationId: msg.stimulationId,
-      newStimulationId,
-      newStimulationAttemptId: stimulationAttemptId
-    });
-    const payload = JSON.stringify({
-      type: "cns.stimulation.launch",
+    const newStimulationId = devtoolsDto.buildCNSCloneId(msg.stimulationId);
+    const stimulationAttemptId = devtoolsDto.buildCNSAttemptId(newStimulationId, 1);
+    const sourceAttempts = await this.stimulationRepository.getAttempts(
+      msg.stimulationId
+    );
+    const replayOf = sourceAttempts.reduce(
+      (max, a) => !max || a.attemptNumber > max.attemptNumber ? a : max,
+      void 0
+    )?.stimulationAttemptId;
+    const handled = await this.carryOut({
+      type: "launch",
       requestId: msg.requestId,
       scopeName: stim.scopeName,
       stimulationId: newStimulationId,
       stimulationAttemptId,
       entry: stim.entry,
+      // A clone gets a NEW stimulationId, so this is the ONLY link back to
+      // the run it came from.
+      replayOf,
       options: msg.options
     });
-    for (const appWs of appSockets) {
-      try {
-        appWs.send(payload);
-      } catch {
-      }
+    if (handled !== true) {
+      return reject(
+        handled === false ? "no runtime accepted the clone" : `clone failed: ${handled}`
+      );
     }
+    this.send(ws, {
+      type: "stimulation.clone.accepted",
+      requestId: msg.requestId,
+      stimulationId: msg.stimulationId,
+      newStimulationId,
+      newStimulationAttemptId: stimulationAttemptId
+    });
   }
   // ─── Broadcast helpers ────────────────────────────────────────────────────
   broadcast(message) {
@@ -394,6 +760,8 @@ var CNSDevToolsServer = class {
   }
 };
 
+exports.CNSDevToolsPollingTransport = CNSDevToolsPollingTransport;
 exports.CNSDevToolsServer = CNSDevToolsServer;
+exports.startCNSDevTools = startCNSDevTools;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map