chalkbridge 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # chalkbridge
 
+## 1.0.3
+
+**An upgrade now actually arrives, a bridge can be stopped, and it ends when you are
+done with it.**
+
+(1.0.2 was built and verified but never published — everything below shipped as 1.0.3.)
+
+The bridge is spawned detached and outlives the session that started it — deliberately,
+because writes have to succeed with no browser connected. But `ensureBridge` reused
+whatever was already listening without ever checking its version, so `npx -y chalkbridge
+mcp` would fetch a new package, find the **old** bridge still answering, and reuse it.
+Every fix would ship and none would arrive, silently. If 1.0.1 seemed not to change
+anything for you, that is why.
+
+- **A bridge from another build is replaced.** It is asked to stop first, so its pending
+  `.excalidraw` write still reaches the disk.
+- **`chalkbridge stop`** ends the bridge for the current repo, flushing anything unsaved.
+  Until now the only options were a reboot or hunting the pid.
+- **`POST /api/shutdown`** is what both use — a request rather than a signal, because on
+  Windows a signal from another process terminates outright and the flush never happens.
+- **A pid fallback for bridges built before this release.** 1.0.0 and 1.0.1 have no
+  shutdown endpoint, so the polite path is unavailable for exactly the bridges an upgrade
+  has to replace. Without it, upgrading from either would leave the new build unable to
+  start at all. Found by running the published 1.0.1 against a local build.
+
+**And it ends when you are done with it.** Until now a bridge ran until the machine
+restarted — one per repo, forever — which is not what anybody expects after closing a chat
+and a tab. It now exits when nothing is watching *and* nothing is asking, for 90 seconds:
+
+| | |
+|---|---|
+| chat closed, tab closed | exits |
+| tab refreshed | reconnects in about a second, so it stays |
+| chat closed, tab still open | stays — somebody is looking at the canvas |
+| Claude drawing with no tab open | every tool call counts, so it stays |
+| two chats on one repo | activity keeps it alive |
+
+One rule, no session counting. `CHALK_IDLE_TIMEOUT` tunes it and `0` restores the old
+behaviour.
+
+**A tool call now survives its own bridge.** That is what makes the above invisible: if a
+bridge has given up, the next call re-runs the bootstrap — spawning one and reopening the
+canvas — instead of failing. Previously a bridge lost mid-session meant every call failed
+until Claude Code was restarted.
+
+After this release, updating really is just restarting Claude Code.
+
 ## 1.0.1
 
 **Arrows are drawn where they belong, the first time.**

package/README.md

@@ -53,10 +53,26 @@ reach loopback. Do not work around it by binding a wider address.
 ```bash
 chalkbridge health              # what is running for this repository
 chalkbridge serve               # start the bridge by hand
+chalkbridge stop                # end it, flushing anything unsaved
 chalkbridge icons list          # what is in the machine-wide icon catalog
 chalkbridge icons install devicon
 ```
 
+**The bridge is spawned detached and outlives your session** — deliberately, because
+writes have to succeed with no browser connected. It ends when nothing is watching *and*
+nothing is asking:
+
+| | |
+|---|---|
+| chat closed, tab closed | exits after 90 seconds |
+| tab refreshed | reconnects in about a second, so it stays |
+| chat closed, tab still open | stays — you are still looking at the canvas |
+| Claude drawing with no tab | every tool call counts, so it stays |
+
+If it has already given up, the next tool call brings it back and reopens the canvas, so
+you never have to think about it. `chalkbridge stop` ends one now; `CHALK_IDLE_TIMEOUT`
+tunes the ninety seconds, and `0` keeps it up forever.
+
 `CHALK_NO_AUTOSTART=1` and `CHALK_NO_OPEN=1` turn off the two automatic behaviours;
 `CHALK_PORT` pins the port; `CHALK_DATA_DIR` moves the icon catalog.
 

package/dist/{chunk-SHJT5BF3.js → chunk-VTFAXWQJ.js}

@@ -1248,6 +1248,14 @@ var bridgeUnreachable = (port) => port === null ? err("BRIDGE_UNREACHABLE", "no
   hint: "the bridge may have exited \u2014 `chalkbridge health` reports what is running",
   detail: { port }
 });
+var bridgeVersionMismatch = (running, ours, port) => err(
+  "BRIDGE_VERSION_MISMATCH",
+  `a Chalkbridge ${running} bridge is running on 127.0.0.1:${port} and this is ${ours}`,
+  {
+    hint: "it did not stop when asked \u2014 run `chalkbridge stop` in this repo, or end that process, and try again",
+    detail: { running, ours, port }
+  }
+);
 var portUnavailable = (from, tried) => err("PORT_UNAVAILABLE", `no free port between ${from} and ${from + tried - 1}`, {
   hint: "something is occupying the whole range \u2014 set CHALK_PORT to pick a different one",
   detail: { from, tried }
@@ -1495,6 +1503,6 @@ var stable = (element) => {
   return rest;
 };
 
-export { AnnotateInput, AnnotateOutput, ApiError, ArrangeOutput, ArrangeToolInput, BINDING_FIELDS, ClientMessage, ConnectOutput, ConnectToolInput, CreateElementsInput, CreateElementsOutput, DebugElementRequest, DeleteElementsInput, DeleteElementsOutput, DescribeSceneInput, DescribeSceneOutput, DetailLevel, EXCALIDRAW_FILE_TYPE, EXCALIDRAW_FILE_VERSION, ElementId, EmbedInput, EmbedOutput, ExcalidrawFile, ExportImageInput, ExportImageOutput, ExportSceneInput, ExportSceneOutput, FLAG_GLYPH, FileId, FocusInput, FocusOutput, FrameId, FrameInput, FrameOutput, GUIDE_TOPICS, GetElementsInput, GetElementsOutput, GetSelectionInput, GetSelectionOutput, GroupId, GroupInput, GroupOutput, GuideTopic, HOUSE, HealthResponse, IconId, IconItem, ImportSceneInput, ImportSceneOutput, Index, InstallPackInput, InstallPackOutput, KIND_ABBREVIATION, ListPacksInput, ListPacksOutput, ListScenesInput, ListScenesOutput, PROTOCOL_VERSION, PackKind, PackName, PackRecipe, PlaceIconInput, PlaceIconOutput, ROUNDNESS, RawElementsInput, RawElementsOutput, ReadMeInput, ReadMeOutput, RemovePackInput, RemovePackOutput, RestoreSnapshotInput, RestoreSnapshotOutput, SERVER_MANAGED_FIELDS, STALE_SELECTION_MS, Scene, SceneElement, SceneId, SceneSettingsInput, SceneSettingsOutput, ScreenshotInput, ScreenshotOutput, ScreenshotResponse, SearchIconsInput, SearchIconsOutput, SnapshotId, SnapshotInput, SnapshotOutput, UngroupInput, UngroupOutput, UpdateElementsInput, UpdateElementsOutput, assertNever, bridgeSpawnFailed, bridgeUnreachable, catalogUnavailable, createNodeSkeletonExpander, deepEqual, describeThrown, diskConflict, emptySelection, expansionFailed, exportFailed, exportTimedOut, fail, frameIdOf, iconIdOf, idCollision, isFail, isOk, noBoundLabel, noBrowser, noScenes, notAPack, notARepo, ok, packInstallFailed, partition, pathOutsideRepo, point, portUnavailable, refusedFieldMessage, sceneFileMissing, staleVersion, storeUnavailable, unknownElement, unknownIcon, unknownScene, unknownSnapshot, unreadableSceneFile };
-//# sourceMappingURL=chunk-SHJT5BF3.js.map
-//# sourceMappingURL=chunk-SHJT5BF3.js.map
+export { AnnotateInput, AnnotateOutput, ApiError, ArrangeOutput, ArrangeToolInput, BINDING_FIELDS, ClientMessage, ConnectOutput, ConnectToolInput, CreateElementsInput, CreateElementsOutput, DebugElementRequest, DeleteElementsInput, DeleteElementsOutput, DescribeSceneInput, DescribeSceneOutput, DetailLevel, EXCALIDRAW_FILE_TYPE, EXCALIDRAW_FILE_VERSION, ElementId, EmbedInput, EmbedOutput, ExcalidrawFile, ExportImageInput, ExportImageOutput, ExportSceneInput, ExportSceneOutput, FLAG_GLYPH, FileId, FocusInput, FocusOutput, FrameId, FrameInput, FrameOutput, GUIDE_TOPICS, GetElementsInput, GetElementsOutput, GetSelectionInput, GetSelectionOutput, GroupId, GroupInput, GroupOutput, GuideTopic, HOUSE, HealthResponse, IconId, IconItem, ImportSceneInput, ImportSceneOutput, Index, InstallPackInput, InstallPackOutput, KIND_ABBREVIATION, ListPacksInput, ListPacksOutput, ListScenesInput, ListScenesOutput, PROTOCOL_VERSION, PackKind, PackName, PackRecipe, PlaceIconInput, PlaceIconOutput, ROUNDNESS, RawElementsInput, RawElementsOutput, ReadMeInput, ReadMeOutput, RemovePackInput, RemovePackOutput, RestoreSnapshotInput, RestoreSnapshotOutput, SERVER_MANAGED_FIELDS, STALE_SELECTION_MS, Scene, SceneElement, SceneId, SceneSettingsInput, SceneSettingsOutput, ScreenshotInput, ScreenshotOutput, ScreenshotResponse, SearchIconsInput, SearchIconsOutput, SnapshotId, SnapshotInput, SnapshotOutput, UngroupInput, UngroupOutput, UpdateElementsInput, UpdateElementsOutput, assertNever, bridgeSpawnFailed, bridgeUnreachable, bridgeVersionMismatch, catalogUnavailable, createNodeSkeletonExpander, deepEqual, describeThrown, diskConflict, emptySelection, expansionFailed, exportFailed, exportTimedOut, fail, frameIdOf, iconIdOf, idCollision, isFail, isOk, noBoundLabel, noBrowser, noScenes, notAPack, notARepo, ok, packInstallFailed, partition, pathOutsideRepo, point, portUnavailable, refusedFieldMessage, sceneFileMissing, staleVersion, storeUnavailable, unknownElement, unknownIcon, unknownScene, unknownSnapshot, unreadableSceneFile };
+//# sourceMappingURL=chunk-VTFAXWQJ.js.map
+//# sourceMappingURL=chunk-VTFAXWQJ.js.map

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { SceneElement, PackName, PackKind, IconId, SceneId, Scene, SnapshotId, SERVER_MANAGED_FIELDS, BINDING_FIELDS, GUIDE_TOPICS, DetailLevel, createNodeSkeletonExpander, ok, fail, bridgeSpawnFailed, bridgeUnreachable, GuideTopic, storeUnavailable, describeThrown, unreadableSceneFile, pathOutsideRepo, packInstallFailed, sceneFileMissing, notAPack, PackRecipe, portUnavailable, DescribeSceneOutput, DescribeSceneInput, GetSelectionOutput, GetSelectionInput, GetElementsOutput, GetElementsInput, ListScenesOutput, ListScenesInput, SceneSettingsOutput, SceneSettingsInput, SearchIconsOutput, SearchIconsInput, ScreenshotOutput, ScreenshotInput, ReadMeOutput, ReadMeInput, PlaceIconOutput, PlaceIconInput, SnapshotOutput, SnapshotInput, RestoreSnapshotOutput, RestoreSnapshotInput, ExportSceneOutput, ExportSceneInput, ImportSceneOutput, ImportSceneInput, ExportImageOutput, ExportImageInput, InstallPackOutput, InstallPackInput, notARepo, ScreenshotResponse, RemovePackOutput, ListPacksOutput, RawElementsOutput, FocusOutput, EmbedOutput, AnnotateOutput, FrameOutput, UngroupOutput, GroupOutput, ArrangeOutput, DeleteElementsOutput, UpdateElementsOutput, ConnectOutput, CreateElementsOutput, HealthResponse, iconIdOf, unknownScene, unknownSnapshot, exportFailed, unknownIcon, HOUSE, FileId, ElementId, diskConflict, refusedFieldMessage, idCollision, expansionFailed, emptySelection, unknownElement, frameIdOf, GroupId, staleVersion, noBoundLabel, deepEqual, exportTimedOut, noBrowser, DebugElementRequest, CreateElementsInput, ConnectToolInput, UpdateElementsInput, DeleteElementsInput, ArrangeToolInput, GroupInput, UngroupInput, FrameInput, AnnotateInput, EmbedInput, FocusInput, RawElementsInput, ListPacksInput, RemovePackInput, Index, ROUNDNESS, STALE_SELECTION_MS, noScenes, ClientMessage, assertNever, PROTOCOL_VERSION, ApiError, EXCALIDRAW_FILE_VERSION, EXCALIDRAW_FILE_TYPE, point, FLAG_GLYPH, KIND_ABBREVIATION, catalogUnavailable, FrameId, IconItem, ExcalidrawFile } from './chunk-SHJT5BF3.js';
+import { SceneElement, PackName, PackKind, IconId, SceneId, Scene, SnapshotId, SERVER_MANAGED_FIELDS, BINDING_FIELDS, GUIDE_TOPICS, DetailLevel, createNodeSkeletonExpander, ok, fail, bridgeSpawnFailed, bridgeVersionMismatch, bridgeUnreachable, GuideTopic, storeUnavailable, describeThrown, unreadableSceneFile, pathOutsideRepo, packInstallFailed, sceneFileMissing, notAPack, PackRecipe, portUnavailable, DescribeSceneOutput, DescribeSceneInput, GetSelectionOutput, GetSelectionInput, GetElementsOutput, GetElementsInput, ListScenesOutput, ListScenesInput, SceneSettingsOutput, SceneSettingsInput, SearchIconsOutput, SearchIconsInput, ScreenshotOutput, ScreenshotInput, ReadMeOutput, ReadMeInput, PlaceIconOutput, PlaceIconInput, SnapshotOutput, SnapshotInput, RestoreSnapshotOutput, RestoreSnapshotInput, ExportSceneOutput, ExportSceneInput, ImportSceneOutput, ImportSceneInput, ExportImageOutput, ExportImageInput, InstallPackOutput, InstallPackInput, notARepo, ScreenshotResponse, RemovePackOutput, ListPacksOutput, RawElementsOutput, FocusOutput, EmbedOutput, AnnotateOutput, FrameOutput, UngroupOutput, GroupOutput, ArrangeOutput, DeleteElementsOutput, UpdateElementsOutput, ConnectOutput, CreateElementsOutput, HealthResponse, iconIdOf, unknownScene, unknownSnapshot, exportFailed, unknownIcon, HOUSE, FileId, ElementId, diskConflict, refusedFieldMessage, idCollision, expansionFailed, emptySelection, unknownElement, frameIdOf, GroupId, staleVersion, noBoundLabel, deepEqual, exportTimedOut, noBrowser, DebugElementRequest, CreateElementsInput, ConnectToolInput, UpdateElementsInput, DeleteElementsInput, ArrangeToolInput, GroupInput, UngroupInput, FrameInput, AnnotateInput, EmbedInput, FocusInput, RawElementsInput, ListPacksInput, RemovePackInput, Index, ROUNDNESS, STALE_SELECTION_MS, noScenes, ClientMessage, assertNever, PROTOCOL_VERSION, ApiError, EXCALIDRAW_FILE_VERSION, EXCALIDRAW_FILE_TYPE, point, FLAG_GLYPH, KIND_ABBREVIATION, catalogUnavailable, FrameId, IconItem, ExcalidrawFile } from './chunk-VTFAXWQJ.js';
 import './chunk-7D4SUZUM.js';
 import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -1046,6 +1046,7 @@ var KNOWN_CODES = /* @__PURE__ */ new Set([
   "BRIDGE_SPAWN_FAILED",
   "BRIDGE_UNREACHABLE",
   "PORT_UNAVAILABLE",
+  "BRIDGE_VERSION_MISMATCH",
   "STALE_VERSION",
   "ID_COLLISION",
   "UNKNOWN_ELEMENT",
@@ -1099,23 +1100,48 @@ function createBridgeClient() {
         return null;
       }
     },
-    connect(port) {
-      const base = `http://127.0.0.1:${port}`;
-      async function call(path, schema, init, timeoutMs = DEFAULT_API_TIMEOUT_MS) {
-        let response;
+    async shutdown(port, timeoutMs = DEFAULT_HEALTH_TIMEOUT_MS) {
+      try {
+        await fetch(`http://127.0.0.1:${port}/api/shutdown`, {
+          method: "POST",
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch {
+      }
+      const deadline = Date.now() + timeoutMs * 4;
+      while (Date.now() < deadline) {
+        if (await this.health(port, timeoutMs) === null) return true;
+        await new Promise((resolve6) => setTimeout(resolve6, 100));
+      }
+      return false;
+    },
+    connect(port, reconnect) {
+      let current = port;
+      async function attempt(path, init, timeoutMs) {
         try {
-          response = await fetch(`${base}${path}`, {
+          return await fetch(`http://127.0.0.1:${current}${path}`, {
             ...init,
             signal: AbortSignal.timeout(timeoutMs)
           });
         } catch {
-          return fail(bridgeUnreachable(port));
+          return null;
         }
+      }
+      async function call(path, schema, init, timeoutMs = DEFAULT_API_TIMEOUT_MS) {
+        let response = await attempt(path, init, timeoutMs);
+        if (response === null && reconnect !== void 0) {
+          const revived = await reconnect();
+          if (revived !== null) {
+            current = revived;
+            response = await attempt(path, init, timeoutMs);
+          }
+        }
+        if (response === null) return fail(bridgeUnreachable(current));
         const body = await response.json().catch(() => null);
-        if (!response.ok) return fail(toChalkError(body, port));
+        if (!response.ok) return fail(toChalkError(body, current));
         const parsed = schema.safeParse(body);
         if (!parsed.success) {
-          return fail(bridgeUnreachable(port));
+          return fail(bridgeUnreachable(current));
         }
         return ok(parsed.data);
       }
@@ -1726,6 +1752,24 @@ function createBridgeLauncher(options, deps) {
         await sleep(pollIntervalMs);
       }
       return fail(bridgeSpawnFailed(`it did not start listening within ${readyTimeoutMs}ms`));
+    },
+    async stop(pid) {
+      try {
+        process.kill(pid, "SIGTERM");
+      } catch {
+        return false;
+      }
+      const deadline = Date.now() + 5e3;
+      while (Date.now() < deadline) {
+        try {
+          process.kill(pid, 0);
+        } catch {
+          return true;
+        }
+        await sleep(pollIntervalMs);
+      }
+      deps.logger.warn("a bridge did not exit after being signalled", { pid });
+      return false;
     }
   };
 }
@@ -1734,6 +1778,48 @@ function createBridgeLauncher(options, deps) {
 function createClock() {
   return { now: () => Date.now() };
 }
+
+// src/adapters/system/idle-watch.ts
+var intervalFor = (timeoutMs) => Math.max(1e3, Math.min(1e4, Math.floor(timeoutMs / 3)));
+function createIdleWatch(options, deps) {
+  let lastActivity = deps.clock.now();
+  let timer = null;
+  let fired = false;
+  return {
+    touch() {
+      lastActivity = deps.clock.now();
+    },
+    start({ isWatched, onIdle }) {
+      const timeoutMs = options.timeoutMs;
+      if (timeoutMs === null) {
+        deps.logger.debug("idle shutdown is disabled", { reason: "CHALK_IDLE_TIMEOUT=0" });
+        return;
+      }
+      if (timer !== null) return;
+      const every = options.checkIntervalMs ?? intervalFor(timeoutMs);
+      timer = setInterval(() => {
+        if (fired) return;
+        if (isWatched()) {
+          lastActivity = deps.clock.now();
+          return;
+        }
+        if (deps.clock.now() - lastActivity < timeoutMs) return;
+        fired = true;
+        deps.logger.info("idle \u2014 nothing watching and nothing asking", {
+          idleMs: deps.clock.now() - lastActivity
+        });
+        onIdle();
+      }, every);
+      timer.unref?.();
+      deps.logger.debug("watching for idle", { timeoutMs, every });
+    },
+    stop() {
+      if (timer === null) return;
+      clearInterval(timer);
+      timer = null;
+    }
+  };
+}
 var ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
 var shortId = (length) => {
   let out = "";
@@ -2427,7 +2513,20 @@ function ensureBridge(deps) {
     const repoRoot = await deps.projectDir.findRepoRoot(options.cwd);
     if (!repoRoot.ok) return repoRoot;
     const existingPort = await deps.projectDir.readPort(repoRoot.value);
-    const existing = existingPort === null ? null : await deps.client.health(existingPort);
+    let existing = existingPort === null ? null : await deps.client.health(existingPort);
+    if (existing !== null && existingPort !== null && existing.version !== deps.version) {
+      deps.logger.info("replacing a bridge from another build", {
+        running: existing.version,
+        ours: deps.version,
+        port: existingPort
+      });
+      const stopped = await deps.client.shutdown(existingPort) || await deps.launcher.stop(existing.pid);
+      if (!stopped) {
+        return fail(bridgeVersionMismatch(existing.version, deps.version, existingPort));
+      }
+      await deps.projectDir.clearPort(repoRoot.value);
+      existing = null;
+    }
     let port = existing === null ? null : existingPort;
     let health = existing;
     let spawned = false;
@@ -4371,6 +4470,7 @@ function printLine(line) {
 }
 var DEFAULT_PORT = 7180;
 var PORT_SCAN_RANGE = 32;
+var DEFAULT_IDLE_SECONDS = 90;
 var truthy = (value) => value !== void 0 && value !== "" && value !== "0" && value.toLowerCase() !== "false";
 var EnvSchema = z.object({
   CHALK_PORT: z.coerce.number().int().min(1).max(65535).optional(),
@@ -4383,12 +4483,18 @@ var EnvSchema = z.object({
    * icon pack into the developer real data directory would be a test that changed the
    * machine it ran on.
    */
-  CHALK_DATA_DIR: z.string().min(1).optional()
+  CHALK_DATA_DIR: z.string().min(1).optional(),
+  /**
+   * Seconds a bridge may sit with no browser client and no tool call before it exits.
+   * `0` keeps it up forever, which is what every version before v1.0.2 did.
+   */
+  CHALK_IDLE_TIMEOUT: z.coerce.number().int().min(0).max(86400).optional()
 });
 function readEnv(source) {
   const parsed = EnvSchema.safeParse(source);
   const env = parsed.success ? parsed.data : {};
   const explicit2 = env.CHALK_PORT ?? null;
+  const idleSeconds = env.CHALK_IDLE_TIMEOUT ?? DEFAULT_IDLE_SECONDS;
   return {
     listenFrom: explicit2 ?? DEFAULT_PORT,
     listenTries: explicit2 === null ? PORT_SCAN_RANGE : 1,
@@ -4396,12 +4502,13 @@ function readEnv(source) {
     autoStart: !truthy(env.CHALK_NO_AUTOSTART),
     autoOpen: !truthy(env.CHALK_NO_OPEN),
     dataDir: env.CHALK_DATA_DIR ?? null,
+    idleTimeoutMs: idleSeconds === 0 ? null : idleSeconds * 1e3,
     logLevel: env.CHALK_LOG_LEVEL ?? "info"
   };
 }
 
 // src/composition/container.ts
-var PACKAGE_VERSION = "1.0.1";
+var PACKAGE_VERSION = "1.0.3";
 function readRuntime() {
   return {
     env: process.env,
@@ -4465,6 +4572,7 @@ function buildCommandContext(runtime = readRuntime()) {
       if (!opened.ok) return opened;
       const store = opened.value;
       const broadcaster = createBroadcaster(idGen, logger);
+      const idleWatch = createIdleWatch({ timeoutMs: config.idleTimeoutMs }, { clock, logger });
       const presenceTracker = createPresenceTracker();
       const expander = createNodeSkeletonExpander();
       const repoWriter = createRepoWriter({ repoRoot }, { store, logger });
@@ -4472,6 +4580,7 @@ function buildCommandContext(runtime = readRuntime()) {
       const diskWatcher = createDiskWatcher({ logger });
       const commit = commitScene({ store, repoWriter });
       const repoFiles = createRepoFiles({ repoRoot });
+      let onShutdown = null;
       const exportBroker = createExportBroker({}, { broadcaster, idGen, logger });
       const globalPaths = globalPathsOf(runtime, config);
       let catalog = null;
@@ -4635,6 +4744,10 @@ function buildCommandContext(runtime = readRuntime()) {
         // logic in `app/`, and a lifecycle command has no more business holding a store
         // than a route does.
         sceneFilePaths: () => store.list().map((scene) => scene.repoPath).filter((path) => path !== null).map((path) => resolve(repoRoot, path)),
+        idleWatch,
+        onShutdownRequest: (handler) => {
+          onShutdown = handler;
+        },
         close: () => {
           repoWriter.cancel();
           exportBroker.abandon();
@@ -4675,6 +4788,7 @@ function buildCommandContext(runtime = readRuntime()) {
           importScene: usecases.importScene,
           broadcaster,
           identity,
+          requestShutdown: () => onShutdown?.(),
           logger
         },
         ws: {
@@ -4698,24 +4812,42 @@ function buildCommandContext(runtime = readRuntime()) {
         { cliEntry: runtime.entryPath, execPath: runtime.execPath, env: runtime.env },
         { projectDir, client, logger }
       );
+      const bootstrap = ensureBridge({
+        // Compared against whatever is already listening: an upgrade that reused an
+        // older detached bridge would ship every fix and deliver none of them.
+        version: runtime.version,
+        projectDir,
+        client,
+        launcher,
+        opener: createBrowserOpener(logger),
+        logger
+      });
       return {
         logger,
         projectDir,
         client,
+        launcher,
         // A7 — the tool handlers never see a port, a URL, or a `fetch`. They see the
         // bridge's read surface and a shelf of markdown, and nothing else exists to
         // tempt them into caching a scene (invariant 1).
+        //
+        // The `reconnect` argument is what makes a session survive its own bridge. One
+        // now exits when nothing is watching and nothing is asking, so "the port this
+        // session started with" stops being true the moment the user closes the tab and
+        // walks away. Re-running the bootstrap puts a bridge *and a tab* back, which is
+        // what the session's first call did, so a tool call after a break just works.
         createToolDeps: (port) => ({
-          bridge: client.connect(port),
+          bridge: client.connect(port, async () => {
+            const revived = await bootstrap({
+              cwd: runtime.cwd,
+              autoStart: config.autoStart,
+              autoOpen: config.autoOpen
+            });
+            return revived.ok ? revived.value.port : null;
+          }),
           guides: createGuideLibrary({ dir: resolveGuidesDir() }, { logger })
         }),
-        ensureBridge: ensureBridge({
-          projectDir,
-          client,
-          launcher,
-          opener: createBrowserOpener(logger),
-          logger
-        })
+        ensureBridge: bootstrap
       };
     }
   };
@@ -5702,6 +5834,8 @@ var STATUS = {
   BRIDGE_SPAWN_FAILED: 500,
   BRIDGE_UNREACHABLE: 503,
   PORT_UNAVAILABLE: 500,
+  // 409: something is there, it is simply not the build this process belongs to.
+  BRIDGE_VERSION_MISMATCH: 409,
   // 409 for both: a stale version and a file that changed underneath us are the same
   // shape of problem — the caller's view of the world is out of date, and re-reading is
   // the way forward.
@@ -5960,6 +6094,20 @@ var sessionRoutes = [
   })
 ];
 
+// src/interfaces/http/routes/shutdown.ts
+var shutdownRoute = {
+  name: "shutdown",
+  register(app, deps) {
+    app.post("/api/shutdown", async (_request, reply) => {
+      const identity = deps.identity();
+      deps.logger.info("shutdown requested over the API", { pid: identity.pid });
+      await reply.send({ stopping: true, pid: identity.pid, version: identity.version });
+      setTimeout(() => deps.requestShutdown(), 0);
+      return reply;
+    });
+  }
+};
+
 // src/interfaces/http/routes/write.ts
 var writeRoutes = [
   postRoute({
@@ -6045,6 +6193,7 @@ var ROUTES = [
   elementsRoute,
   settingsRoute,
   debugElementRoute,
+  shutdownRoute,
   ...writeRoutes,
   ...sessionRoutes
 ];
@@ -6058,6 +6207,9 @@ async function createHttpServer(deps) {
     bodyLimit: 32 * 1024 * 1024
   });
   await app.register(websocket);
+  app.addHook("onRequest", async () => {
+    deps.touch();
+  });
   for (const route of ROUTES) {
     route.register(app, deps.routes);
     deps.logger.debug("registered route", { route: route.name });
@@ -6067,6 +6219,7 @@ async function createHttpServer(deps) {
     const send = (message) => {
       socket.send(JSON.stringify(message));
     };
+    deps.touch();
     const handle = deps.broadcaster.register(send);
     const session = { handle, send };
     socket.on("message", (data) => {
@@ -6147,7 +6300,8 @@ ${built.error.hint ?? ""}
       ws: services.ws,
       broadcaster: services.broadcaster,
       logger: services.logger,
-      uiDistPath: services.uiDistPath
+      uiDistPath: services.uiDistPath,
+      touch: () => services.idleWatch.touch()
     });
     const listening = await listenOnFirstFreePort(app, {
       host: "127.0.0.1",
@@ -6174,6 +6328,7 @@ ${built.error.hint ?? ""}
     await new Promise((resolve6) => {
       const shutdown = async (signal) => {
         services.logger.info("shutting down", { signal });
+        services.idleWatch.stop();
         await services.diskWatcher.stop();
         const flushed = await services.repoWriter.flushAll();
         if (flushed.length > 0) {
@@ -6184,18 +6339,75 @@ ${built.error.hint ?? ""}
         services.close();
         resolve6();
       };
+      services.idleWatch.start({
+        isWatched: () => services.broadcaster.clientCount() > 0,
+        onIdle: () => void shutdown("idle")
+      });
       process.once("SIGINT", () => void shutdown("SIGINT"));
       process.once("SIGTERM", () => void shutdown("SIGTERM"));
+      services.onShutdownRequest(() => void shutdown("api"));
     });
     return 0;
   }
 };
 
+// src/interfaces/cli/commands/stop.ts
+var stopCommand = {
+  name: "stop",
+  summary: "stop the bridge running for this repo, flushing anything unsaved",
+  detail: [
+    "Ends the bridge for the repository containing the working directory.",
+    "",
+    "The bridge flushes every pending .excalidraw write, stops watching the repo, and",
+    "clears its port file on the way out \u2014 so nothing drawn in the last two seconds is",
+    "lost. Nothing is started; the next Claude Code session starts a fresh one."
+  ].join("\n"),
+  async run(context) {
+    const services = context.createClientServices({ prefix: "[stop]" });
+    const repoRoot = await services.projectDir.findRepoRoot(context.runtime.cwd);
+    if (!repoRoot.ok) {
+      context.print(repoRoot.error.message);
+      if (repoRoot.error.hint !== void 0) context.print(`  ${repoRoot.error.hint}`);
+      return 1;
+    }
+    const port = await services.projectDir.readPort(repoRoot.value);
+    if (port === null) {
+      context.print(`no bridge is running for ${repoRoot.value}`);
+      return 0;
+    }
+    const health = await services.client.health(port);
+    if (health === null) {
+      await services.projectDir.clearPort(repoRoot.value);
+      context.print(`nothing was listening on 127.0.0.1:${port} \u2014 cleared the stale port file`);
+      return 0;
+    }
+    context.print(
+      `stopping chalkbridge ${health.version} on 127.0.0.1:${port} (pid ${health.pid})`
+    );
+    if (await services.client.shutdown(port)) {
+      context.print("  stopped \u2014 pending scene writes were flushed");
+      return 0;
+    }
+    context.print("  it has no shutdown endpoint (built before v1.0.2) \u2014 ending it by pid");
+    if (await services.launcher.stop(health.pid)) {
+      await services.projectDir.clearPort(repoRoot.value);
+      context.print(`  stopped pid ${health.pid}`);
+      return 0;
+    }
+    context.print("  it would not stop \u2014 end it yourself:");
+    context.print(
+      context.runtime.platform === "win32" ? `    taskkill /PID ${health.pid} /F` : `    kill ${health.pid}`
+    );
+    return 1;
+  }
+};
+
 // src/interfaces/cli/registry.ts
 var COMMANDS = [
   serveCommand,
   mcpCommand,
   healthCommand,
+  stopCommand,
   iconsCommand
 ];
 

package/dist/index.js

@@ -1,4 +1,4 @@
-export { createNodeSkeletonExpander, fail, isFail, isOk, ok, partition } from './chunk-SHJT5BF3.js';
+export { createNodeSkeletonExpander, fail, isFail, isOk, ok, partition } from './chunk-VTFAXWQJ.js';
 import './chunk-7D4SUZUM.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chalkbridge",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "Self-hosted Excalidraw canvas for Claude Code to draw and reason on architecture diagrams.",
   "license": "MIT",