stream_weaver 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 27698ae0fafbcbb9fbbea4b2f18f2215b43fc13e8c04acfe0b01a6bec722ab3c
-  data.tar.gz: 43b573368d680cd1c663b8e8c8935e883db51dd605cd25434424f94be2d19c29
+  metadata.gz: 71c5865a49a8746b8592689941d1b1bd4b0d813add49bb60ee8fab85182c1f64
+  data.tar.gz: 3c08461ec552647cb288bef820d35eaf05dd7cb79284710f9d830d9cbb25d493
 SHA512:
-  metadata.gz: 2035acdd6c8d7c98111b67ac8c3e6f3df008440cdf61072ac65749395b78c0ee05f63f9c80ec901c4e9496afe445e5edaeca4e3164600ba37513a61d85356dfb
-  data.tar.gz: '080f167accb1d0244c7bab518f236e3ddd4ddc04066abe23b2a8459fc36be8631096e863eb5820256cef5ecd72471e4342e51cafa1041ce889f2c09ca23ac6de'
+  metadata.gz: 70eefa999d7ab6b8569e15f4713e60ff29693855ca789c2be276fb3d1211ede33abb819d8af3c096098ec7ac1eb1304ddc5c60da02de5ca4e2df7bd1d71dc417
+  data.tar.gz: 9452bac8a36c5769132e0eddac60289128b311fd515e1185f3e428c64123e661721db0d2e3eaf644ca1c080df6b63d5c1d730c035211f86e884d33b7cf2c47ef

data/CHANGELOG.md

@@ -5,7 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.1] - 2026-09-11
+
+### Added
+- **Canvas bridge auto-heal** - every canvas command now detects a bridge left running on older code (after a gem upgrade or a dev `rake install`) and transparently restarts it, preserving all sessions via snapshot/restore. One line on stderr says it happened; `SW_NO_AUTO_RESTART=1` opts out. Ends the "stale bridge" class of 500s.
+- **University artifact lifecycle — the course cleans up after itself** - StreamWeaver University now keeps a manifest of everything it creates (saved docs, exported `.org` files, gists, demo canvas sessions) and can take it all back. `streamweaver university-cleanup` prints the grouped inventory and confirms per group — gists one at a time, showing each URL, since a gist is the only artifact that left your machine — with `--dry-run` to look without being asked anything; the completion recap grew the same offer as buttons, where a delete always takes two clicks (the first only asks, and the confirmation names exactly what will go). `streamweaver university-stop` puts the course down without throwing anything away: it stops the listener, closes the demo canvas sessions and the two iTerm2 windows `get-started` opened, and keeps your progress. Recording is invisible — docs and sessions record themselves; `streamweaver university-artifact add <ref>` is the one manual door, for the gist URL only your agent ever sees. Nothing outside the manifest is ever deleted: a ref it does not record is refused, sessions are re-checked against the same allowlist `university-reset` closes by, and the course's own state files are matched by exact name rather than swept out of a directory in your home. `--scan` covers the runs that predate the manifest: it finds artifacts by the course's own deterministic names only (`university-doc` / `doc-demo-<stamp>` files in the canvas doc stores, gists whose file is one of those, and the demo sessions the bridge is actually serving) and *adopts* them into the manifest rather than deleting anything directly, so the same allowlisted deletion path — and every guard on it — still governs what can go. `--scan --dry-run` previews and writes nothing at all. `streamweaver university-artifact remove <ref>` drops an entry from the manifest without touching the thing it names, so an adoption you did not want is undone in one command.
+
+### Fixed
+- **Canvas bridge 500s on multibyte content when spawned from a locale-less env** - a bridge (or the University listener) spawned detached from a parent process whose env lacked `LANG`/`LC_ALL`/`LC_CTYPE` — e.g. the staleness auto-heal's restart — booted with `Encoding.default_external` falling back to `US-ASCII`, so any push containing an em-dash, checkmark, or other multibyte text raised `Encoding::CompatibilityError` on every render. Both spawn paths now force UTF-8 at boot (`-E UTF-8` plus an explicit encoding preamble) and pass a sane locale to anything they shell out to.
+- **No more "Web Browser" profile dependency for the iTerm2 canvas window** - a fresh macOS/iTerm2 install (only the "Default" profile present) previously failed `open_browser_window`/`panel`'s split with `INVALID_PROFILE_NAME`, and the old remediation text wrongly told a tester on iTerm2 3.6+ to "update iTerm2" when the real fix was to manually create a profile. StreamWeaver no longer needs a saved profile at all: it turns any pane into a browser pane itself by overriding `"Custom Command" => "Browser"` in the split's `profile_customizations` (the exact property iTerm2's own built-in "Web Browser" profile is defined with). The `browser_profile` dependency probe, its dependency-report row, and the "profile not found" remediation hints are removed as no longer applicable.
+- **Dependency check now names iTerm2's Browser Plugin and its Advanced setting, the two prerequisites the profile override can't bypass** - a second field report showed a tester who'd installed the plugin still couldn't get browser panes: iTerm2's own docs confirm the Profile Type / browser feature is gated on the separately-downloaded Browser Plugin (`iterm2.com/browser-plugin.html`) and an "Enable browser-style profiles" Advanced setting (ships enabled). `get-started`'s dependency report gained two more advisory probes (`ITerm.browser_plugin_available?`, detected the same way iTerm2 itself locates the plugin, by bundle identifier via `mdfind`; `ITerm.browser_style_profiles_enabled?`, reading the Advanced setting's preference key directly) plus matching remediation text and a targeted fallback hint when the controller window can't open.
 
 ## [0.3.0] - 2026-09-04
 

data/README.md

@@ -27,6 +27,7 @@ That's it. No HTML. No CSS. No JavaScript. No webpack.
 A few things worth being explicit about:
 
 - `streamweaver panel` and the worker-tab automation it drives are **macOS + iTerm2 only** — they script iTerm2's Python API.
+- The premier `get-started` experience also needs iTerm2 3.6.0 or newer — that's the release that added native browser panes, which is what the canvas window renders in, plus iTerm2's Browser Plugin (a one-time download — iTerm2 offers it in Settings, or grab it from https://iterm2.com/browser-plugin.html and drop it in /Applications). No saved profile setup is required: StreamWeaver turns any pane into a browser pane itself (a profile-customization override), so there's nothing to create or rename in Settings → Profiles. An older iTerm2 without browser-pane support still runs `get-started`; the canvas window just falls back to a plain browser tab.
 - `canvas-read` is a plain local web server. It's the most portable piece of StreamWeaver and doesn't need iTerm2, Chrome, or `gh` — see [docs/canvas-read.md](docs/canvas-read.md).
 - The Chrome extension and the `gh` CLI are enhancers for *sharing* docs (Gist links that render nicely), not requirements for reading them locally.
 - Never assume a port. Every command that starts a server prints the URL it actually bound — StreamWeaver auto-increments past busy ports.
@@ -141,6 +142,14 @@ through a short interactive course, next to your own terminal. On macOS + iTerm2
 experience; anywhere else it falls back to a browser tab automatically (or jump straight there with
 `streamweaver get-started --degraded`). See [Platform support](#platform-support) above.
 
+The course tracks everything it creates -- the docs it saves, the `.org` files exported from them,
+the gists published, the demo canvas sessions it opens -- and takes it all back on request:
+
+```bash
+streamweaver university-cleanup            # confirm group by group; gists one at a time
+streamweaver university-cleanup --scan     # also adopt artifacts from a run before the manifest
+```
+
 Prefer to explore on your own first?
 
 ```bash

data/docs/canvas-panel-workflow.md

@@ -36,6 +36,14 @@ streamweaver canvas-close myapp
 | `canvas-reset <name>` | Reset session state (keep connections) |
 | `canvas-list` | List all canvas sessions |
 
+## Upgrading StreamWeaver under a running bridge
+
+The canvas bridge is a long-lived process holding its classes in memory, so a `gem update` or `rake install` underneath it leaves it serving the old code -- pushed canvas source calling a brand-new method used to fail with a bare `NameError`. It now heals itself: the bridge stamps the StreamWeaver version and a fingerprint of the code it loaded into `~/.streamweaver/canvas.pid` at boot, every canvas command compares that stamp against its own before talking to the bridge, and on a mismatch it restarts the bridge in place -- snapshot, stop, start, restore -- so open sessions keep their content, then carries on with the command you actually ran. You see one line on stderr (stdout stays clean for `canvas-wait`'s JSON): `StreamWeaver: canvas bridge was running older code — restarting it (sessions preserved)…`. It speaks up again, on the same stream, if anything about that claim needs qualifying: a session it could not read before stopping the old bridge, a restore that failed, or a restarted bridge that landed on a different port -- which means the tab you have open is pointing at a dead one and wants a reload.
+
+Two things it deliberately will not do. It never restarts twice within a minute: a second mismatch that soon means two callers disagree about which code is current -- a dev checkout and the installed gem, typically -- and restarting again would just hand the bridge back and forth, taking your sessions with it each time. And it does not notice a single edited file deep in a dev checkout, because the fingerprint tracks `stream_weaver.rb`, which an install rewrites and a targeted edit does not. Both cases print a warning naming `streamweaver canvas-restart`, which is the answer.
+
+Set `SW_NO_AUTO_RESTART=1` to be warned instead of healed everywhere; the command then continues against the old bridge.
+
 ## Multi-Step Workflows
 
 Use `canvas_continue` to show a spinner after submit instead of "You can close this window":

data/docs/university/send-to-coworker.md

@@ -20,14 +20,17 @@ Two versions below, depending on who's getting it. Pick one and paste it as-is.
 > The full experience puts the course in an iTerm2 window of its own and your agent in a fresh tab
 > beside your work -- set iTerm2 up first, then install the gem and run the door command.
 
-**1. Prerequisites** (macOS + iTerm2 only -- skip if you're on another OS or terminal, you'll just
-get a browser tab instead):
+**1. Prerequisites** (macOS + iTerm2 3.6.0+ only -- skip if you're on another OS, terminal, or an
+older iTerm2, you'll just get a browser tab instead):
 
 ```bash
 gem install iterm2_ruby
 ```
 
-Then in iTerm2: **Settings → General → Magic → Enable Python API**.
+Then in iTerm2: **Settings → General → Magic → Enable Python API**, and install the **iTerm2 Browser Plugin** when Settings offers it (or from https://iterm2.com/browser-plugin.html into /Applications) — it powers the canvas window. iTerm2 3.6.0 (September 2025)
+is the version that added native browser panes, which is what the canvas window renders in --
+no profile setup needed, StreamWeaver turns any pane into a browser pane itself. An older iTerm2
+without that support just falls back to a browser tab automatically.
 
 **2. Install the gem:**
 
@@ -75,3 +78,25 @@ The gist link already renders as readable text without the extension -- the exte
 look exactly like it did in the original canvas: sidebar navigation, callouts, cards, tables, and
 live Mermaid diagrams, all in the browser, no install beyond the one-click extension. The extension
 is Chrome/Chromium only -- other browsers just see the plain org text, which is still readable.
+
+## Cleaning up afterwards
+
+The course tracks everything it creates -- saved docs, exported `.org` files, published gists, and
+the demo canvas sessions it opens -- so you never have to remember what a run left behind:
+
+```bash
+streamweaver university-artifact list      # what the course has created
+streamweaver university-cleanup            # offer to take it all back
+streamweaver university-cleanup --dry-run  # show the same inventory, delete nothing
+streamweaver university-cleanup --scan     # also adopt artifacts from a run before the manifest existed
+streamweaver university-artifact remove <ref>   # drop one from the list, leaving the file itself alone
+```
+
+Cleanup confirms group by group, and gists **one at a time showing each URL** -- a gist is the only
+thing here that left your machine. Mind this page's own subject when you answer: the link you sent
+your coworker IS one of those gists, and deleting it breaks the link for them. Keep it until they've
+read it.
+
+`university-cleanup` and `university-reset` compose and do different jobs: cleanup deletes what the
+course created, reset starts the course over (progress and demo sessions). Run both, in either
+order, and nothing of the course is left on the machine.

data/lib/stream_weaver/canvas/bridge_server.rb

@@ -5,6 +5,7 @@ require 'json'
 require 'socket'
 require 'fileutils'
 require_relative 'protocol'
+require_relative 'code_stamp'
 require_relative 'scroll_top_hint'
 require_relative 'session'
 require_relative 'bridge'
@@ -288,7 +289,7 @@ module StreamWeaver
             <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/styles/github.min.css">
             <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0/build/highlight.min.js"></script>
             <!-- Mermaid zoom/pan engine — always present so canvas-push with mermaid works on first push -->
-            <script>#{File.read(File.join(__dir__, '..', 'assets', 'js', 'sw-mermaid-zoom.js'))}</script>
+            <script>#{File.read(File.join(__dir__, '..', 'assets', 'js', 'sw-mermaid-zoom.js'), encoding: 'UTF-8')}</script>
             <!-- Kick off CDN fetch immediately so mermaid is ready before first push arrives -->
             <script>if (window.swMermaidPreload) window.swMermaidPreload();</script>
           </head>
@@ -613,10 +614,13 @@ module StreamWeaver
         # For HTTP polling mode, browsers will get updates on next poll
       end
 
-      # Write PID file
+      # Write PID file. The version/code stamp records which StreamWeaver
+      # code this process loaded, so a later CLI invocation can tell that the
+      # bridge it is about to talk to predates an install (disc-171).
       def self.write_pid_file
         FileUtils.mkdir_p(File.dirname(pid_file_path))
-        File.write(pid_file_path, "pid=#{Process.pid}\nport=#{@port || DEFAULT_PORT}\n")
+        File.write(pid_file_path,
+                   "pid=#{Process.pid}\nport=#{@port || DEFAULT_PORT}\n#{CodeStamp.pid_file_stanza}")
       end
 
       # Cleanup on shutdown

data/lib/stream_weaver/canvas/client.rb

@@ -4,6 +4,8 @@ require 'socket'
 require 'json'
 require 'fileutils'
 require_relative 'protocol'
+require_relative 'code_stamp'
+require_relative 'staleness_guard'
 
 module StreamWeaver
   module Canvas
@@ -17,7 +19,37 @@ module StreamWeaver
       PID_FILE_PATH = File.expand_path('~/.streamweaver/canvas.pid')
       DEFAULT_TIMEOUT = 300 # 5 minutes
 
+      # A bridge spawned detached (e.g. the staleness heal's restart) inherits
+      # whatever LANG/LC_ALL its parent process happened to have. When those
+      # are missing -- true for some launchers -- Ruby's Encoding.default_external
+      # falls back to US-ASCII, and any push containing multibyte characters
+      # blows up render_canvas_page with Encoding::CompatibilityError, 500ing
+      # every request for that session. This preamble is the entry-level fix:
+      # force UTF-8 before the bridge does its first read, independent of the
+      # env it was spawned with. Shared with the university listener's spawn
+      # (also detached, also multibyte-capable), so it lives here once.
+      ENCODING_PREAMBLE = <<~RUBY
+        Encoding.default_external = Encoding::UTF_8
+        Encoding.default_internal = nil
+      RUBY
+
       class << self
+        UTF8_LOCALE = 'en_US.UTF-8'
+
+        # Belt-and-suspenders alongside ENCODING_PREAMBLE: forces the child
+        # LANG/LC_ALL to a UTF-8 locale so shelled-out tools (e.g. gist
+        # publishing's `gh` calls) inherit sane behavior too. Only preserves
+        # the caller's own value when it's already UTF-8 -- a caller running
+        # under LANG=C is exactly the case this exists to fix, so passing
+        # that through unchanged would defeat the point.
+        def utf8_locale_env
+          %w[LANG LC_ALL].to_h { |key| [key, utf8_locale?(ENV[key]) ? ENV[key] : UTF8_LOCALE] }
+        end
+
+        def utf8_locale?(locale)
+          locale.to_s.match?(/utf-?8\z/i)
+        end
+
         # STREAMWEAVER_CANVAS_SOCKET / _PID redirect the whole bridge --
         # socket, pid file, and (because the bridge is spawned with the
         # environment it inherits) the server half too. This exists so a
@@ -62,6 +94,7 @@ module StreamWeaver
         # @param timeout [Integer] Timeout in seconds
         # @return [Hash, nil] Response message or nil
         def send_message(message, timeout: 5)
+          StalenessGuard.ensure_current!
           raise NotRunningError, "Canvas bridge is not running" unless bridge_running?
 
           socket = UNIXSocket.new(socket_path)
@@ -93,6 +126,7 @@ module StreamWeaver
         # @param timeout [Integer] Timeout in seconds
         # @return [Hash, nil] Event message or nil
         def send_and_wait(message, event_type:, timeout: DEFAULT_TIMEOUT)
+          StalenessGuard.ensure_current!
           raise NotRunningError, "Canvas bridge is not running" unless bridge_running?
 
           socket = UNIXSocket.new(socket_path)
@@ -138,6 +172,7 @@ module StreamWeaver
         # @param name [String, nil] session to filter on; nil yields all
         # @yield [Hash] each event message
         def each_event(name = nil)
+          StalenessGuard.ensure_current!
           raise NotRunningError, "Canvas bridge is not running" unless bridge_running?
 
           socket = UNIXSocket.new(socket_path)
@@ -170,6 +205,8 @@ module StreamWeaver
         # Start the bridge process if not running
         # @return [Hash] { pid: Integer, port: Integer }
         def ensure_bridge_running
+          StalenessGuard.ensure_current!
+
           if bridge_running?
             info = read_bridge_info
             # Verify HTTP server is actually responding
@@ -206,8 +243,11 @@ module StreamWeaver
           # Get the lib path
           lib_path = File.expand_path('../..', __dir__)
 
-          # Create startup script
+          # Create startup script. ENCODING_PREAMBLE goes first, before the
+          # requires, so nothing the bridge loads or renders can run under
+          # the wrong default_external.
           script = <<~RUBY
+            #{ENCODING_PREAMBLE}
             $LOAD_PATH.unshift('#{lib_path}')
             require 'stream_weaver'
             require 'stream_weaver/canvas/bridge_server'
@@ -221,9 +261,11 @@ module StreamWeaver
           # Log file
           log_file = File.join(File.dirname(pid_file_path), 'canvas.log')
 
-          # Spawn the bridge process
-          pid = spawn(
-            RbConfig.ruby, script_file,
+          # Spawn the bridge process. -E fixes the interpreter's own default
+          # encodings before ENCODING_PREAMBLE even runs; utf8_locale_env
+          # fixes the locale for anything the bridge shells out to.
+          pid = Process.spawn(
+            *bridge_spawn_command(script_file),
             out: [log_file, 'a'],
             err: [log_file, 'a'],
             pgroup: true
@@ -253,8 +295,16 @@ module StreamWeaver
           read_bridge_info || { pid: pid, port: BridgeServer::DEFAULT_PORT }
         end
 
+        # The argv (env hash + command) start_bridge hands to Process.spawn.
+        # Broken out so a spec can assert on it directly instead of stubbing
+        # Process.spawn and waiting out the readiness poll above.
+        def bridge_spawn_command(script_file)
+          [utf8_locale_env, RbConfig.ruby, '-E', 'UTF-8', script_file]
+        end
+
         # Read bridge info from PID file
-        # @return [Hash] { pid: Integer, port: Integer }
+        # @return [Hash] { pid: Integer, port: Integer, version: String, code: String }
+        #   version/code are nil for a bridge started before the stamp existed
         def read_bridge_info
           return nil unless File.exist?(pid_file_path)
 
@@ -262,7 +312,7 @@ module StreamWeaver
           pid = content[/pid=(\d+)/, 1]&.to_i
           port = content[/port=(\d+)/, 1]&.to_i || Bridge::DEFAULT_PORT
 
-          { pid: pid, port: port }
+          { pid: pid, port: port }.merge(CodeStamp.parse(content))
         end
 
         # Stop the bridge process

data/lib/stream_weaver/canvas/code_stamp.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../version'
+
+module StreamWeaver
+  module Canvas
+    # Identity of the StreamWeaver code a process has loaded: stamped into the
+    # bridge's pid file at boot, re-computed by every CLI invocation that talks
+    # to the bridge, and compared by StalenessGuard.ensure_current!.
+    #
+    # A canvas bridge is long-lived and keeps its classes in memory, so a
+    # `rake install` or `gem update` underneath it leaves it serving code the
+    # caller no longer has -- pushed canvas source calls a method the running
+    # bridge has never heard of and NameErrors (disc-171, hit three times
+    # live). Version alone does not catch it: the trap fires hardest on a
+    # same-version reinstall, which is why the mtime of the loaded
+    # stream_weaver.rb is half the stamp.
+    #
+    # It deliberately fingerprints that one file rather than walking lib/: any
+    # install rewrites stream_weaver.rb along with everything else, so every
+    # install is caught, while editing a file deeper in lib/ in a dev checkout
+    # is not and still wants an explicit `canvas-restart`.
+    module CodeStamp
+      module_function
+
+      def version
+        StreamWeaver::VERSION
+      end
+
+      # The stream_weaver.rb above this file -- resolved from __dir__ rather
+      # than $LOADED_FEATURES so a process that required only the canvas
+      # subtree still fingerprints the library it is actually running.
+      def library_path
+        File.expand_path('../../stream_weaver.rb', __dir__)
+      end
+
+      def fingerprint
+        fingerprint_for(library_path)
+      end
+
+      def fingerprint_for(path)
+        return nil unless File.file?(path)
+
+        "#{path}:#{File.mtime(path).to_i}"
+      rescue SystemCallError
+        nil
+      end
+
+      # Appended to the bridge's pid file; the existing pid=/port= lines are
+      # parsed by regex, so extra lines are invisible to older readers.
+      def pid_file_stanza
+        "version=#{version}\ncode=#{fingerprint}\n"
+      end
+
+      def parse(content)
+        { version: content[/^version=(.*)$/, 1], code: content[/^code=(.*)$/, 1] }
+      end
+
+      # True when the stamp read from a running bridge's pid file does not
+      # describe the code THIS process loaded. No stamp at all means a bridge
+      # started before this existed -- precisely the upgrade case, so it counts
+      # as stale. Unknowable on our own side (no library file to stat) never
+      # counts: a false positive restarts a developer's live bridge mid-session,
+      # which is worse than the staleness it would be curing.
+      def stale?(stamped)
+        mine = fingerprint
+        return false if mine.nil?
+
+        stamped ||= {}
+        stamped[:version] != version || stamped[:code] != mine
+      end
+    end
+  end
+end

data/lib/stream_weaver/canvas/reader.rb

@@ -200,7 +200,11 @@ module StreamWeaver
         end
       end
 
-      MERMAID_ZOOM_JS = File.read(File.expand_path('../assets/js/sw-mermaid-zoom.js', __dir__))
+      # Explicit encoding rather than relying on default_external: this loads
+      # at class-load time in whatever process requires reader.rb, not just
+      # a bridge booted via Client.start_bridge's UTF-8 fix, and the file
+      # itself is always UTF-8 regardless of the host process's locale.
+      MERMAID_ZOOM_JS = File.read(File.expand_path('../assets/js/sw-mermaid-zoom.js', __dir__), encoding: 'UTF-8')
       private_constant :MERMAID_ZOOM_JS
 
       configure do

data/lib/stream_weaver/canvas/staleness_guard.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'stringio'
+require_relative 'code_stamp'
+
+module StreamWeaver
+  module Canvas
+    # Detects a canvas bridge left running on code the caller no longer has,
+    # and restarts it in place (disc-171).
+    #
+    # A bridge outlives the shells that talk to it and holds its classes in
+    # memory, so `rake install` or `gem update` underneath one leaves it
+    # serving the old code: pushed canvas source calls a brand-new method and
+    # the bridge dies with a bare NameError, with nothing on screen saying
+    # why. Client calls ensure_current! before every socket conversation, so
+    # every command that reaches the bridge is covered by one check rather
+    # than N call sites.
+    #
+    # The whole design leans away from acting: a spurious restart takes down
+    # every session the developer has open in a browser, which is worse than
+    # the staleness it would be curing. Hence the once-per-process latch, the
+    # cross-process cooldown, and CodeStamp.stale?'s refusal to guess.
+    module StalenessGuard
+      # Long enough that a checkout/gem pair alternating on one bridge stops
+      # after the first restart instead of thrashing on every command; short
+      # enough that a genuine second upgrade in the same session still heals.
+      COOLDOWN_SECONDS = 60
+
+      module_function
+
+      def pending?
+        !@checked
+      end
+
+      # For canvas-stop and canvas-restart, which are the manual spelling of
+      # this same cure -- healing inside them is a restart within a restart.
+      def disable!
+        @checked = true
+      end
+
+      # Specs only: the latch is process-global and RSpec is one process.
+      def reset!
+        @checked = false
+      end
+
+      def ensure_current!
+        return unless pending?
+
+        @checked = true
+
+        return unless Client.bridge_running?
+        return unless CodeStamp.stale?(Client.read_bridge_info)
+
+        if auto_restart_disabled?
+          warn_only("canvas bridge is running older code")
+        elsif recently_healed?
+          # Two installs cannot land inside a minute; a second mismatch this
+          # soon means two callers disagree about which code is current
+          # (a dev checkout and the installed gem, say), and restarting again
+          # would just hand the bridge back and forth forever. Naming
+          # canvas-restart here would be advice to resume the fight, so this
+          # branch points at the off switch instead.
+          $stderr.puts "StreamWeaver: canvas bridge still looks like older code, but was just restarted — two installs disagree about which code is current; set SW_NO_AUTO_RESTART=1 to stop the restarts."
+        else
+          heal!
+        end
+      end
+
+      def auto_restart_disabled?
+        !ENV['SW_NO_AUTO_RESTART'].to_s.empty?
+      end
+
+      def warn_only(reason)
+        $stderr.puts "StreamWeaver: #{reason} — run `streamweaver canvas-restart` to pick it up."
+      end
+
+      # Announced on stderr, not stdout: canvas-wait and friends emit JSON for
+      # a script to parse, and a line of narration in front of it is a parse
+      # error on the other end.
+      #
+      # The restart lives in the CLI, which owns snapshot/restore; required
+      # here rather than at the top of the file because the CLI requires the
+      # canvas client back. Its narration is swallowed so the heal costs the
+      # caller one line; anything it could not preserve, or could not do at
+      # all, still speaks -- with the manual command.
+      def heal!
+        require_relative '../cli'
+
+        $stderr.puts "StreamWeaver: canvas bridge was running older code — restarting it (sessions preserved)…"
+        record_heal!
+
+        result = silently { StreamWeaver::CLI.restart_bridge_preserving_sessions }
+        report(result)
+        result
+      rescue StandardError => e
+        # A cure that cannot finish must not take down the command it was
+        # trying to help: the caller only wanted to push a canvas.
+        $stderr.puts "StreamWeaver: automatic bridge restart failed (#{e.class}: #{e.message}) — run `streamweaver canvas-restart`."
+        { ok: false, dir: nil, unconfirmed: [] }
+      end
+
+      # Everything that qualifies the "sessions preserved" the announcement
+      # already promised: a session the snapshot never read, a bridge that came
+      # back on a different port (every open tab is now pointing at a dead one
+      # -- canvas-restart warns about this in stars, and an automatic restart
+      # owes at least as much), and a restore that did not finish.
+      def report(result)
+        unconfirmed = result[:unconfirmed] || []
+        unless unconfirmed.empty?
+          $stderr.puts "StreamWeaver: could not capture #{unconfirmed.join(', ')} before the restart — snapshot at #{result[:dir]}"
+        end
+
+        if result[:old_port] && result[:port] && result[:old_port] != result[:port]
+          $stderr.puts "StreamWeaver: bridge moved from port #{result[:old_port]} to #{result[:port]} — reload any canvas tab you have open."
+        end
+
+        return if result[:ok]
+
+        $stderr.puts "StreamWeaver: automatic bridge restart did not complete — snapshot at #{result[:dir]}; run `streamweaver canvas-restart` if sessions look wrong."
+      end
+
+      def silently
+        original = $stdout
+        $stdout = StringIO.new
+        yield
+      ensure
+        $stdout = original
+      end
+
+      # Written BEFORE the restart, so a second process arriving mid-heal
+      # backs off rather than snapshotting a half-restored bridge.
+      def heal_marker_path
+        File.join(File.dirname(Client.pid_file_path), 'canvas.heal')
+      end
+
+      def recently_healed?
+        Time.now - File.mtime(heal_marker_path) < COOLDOWN_SECONDS
+      rescue SystemCallError
+        false
+      end
+
+      # Silent on failure by design: an unwritable marker only costs the next
+      # invocation its cooldown, and the heal itself is worth doing anyway --
+      # there is nothing here to tell the operator to act on.
+      def record_heal!
+        FileUtils.mkdir_p(File.dirname(heal_marker_path))
+        File.write(heal_marker_path, Time.now.to_i.to_s)
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end