stream_weaver 0.3.0 → 0.3.1

data/lib/stream_weaver/cli.rb

@@ -115,6 +115,12 @@ module StreamWeaver
         university_demo(args)
       when 'university-done'
         university_done(args)
+      when 'university-artifact'
+        university_artifact(args)
+      when 'university-cleanup'
+        university_cleanup(args)
+      when 'university-stop'
+        university_stop(args)
       when 'focus-me'
         focus_me
       when 'get-started'
@@ -720,6 +726,25 @@ module StreamWeaver
           streamweaver university-done <N>        Mark step N done (same as clicking Mark done) and bring
                                                      the University window forward. What every step's own
                                                      closing ritual runs -- no click required from you.
+          streamweaver university-artifact        The course's record of what it created -- saved docs,
+                       [list | add <ref>]            exported .org files, gists, demo canvas sessions.
+                       [--step N] [--type T]         Docs and sessions record themselves; `add` is for a
+                                                     gist URL, which only your agent ever sees.
+          streamweaver university-cleanup         Offer to delete everything the course created, group by
+                       [--scan] [--dry-run]          group (gists one at a time, showing each URL). Only
+                                                     ever touches what the manifest above records; --scan
+                                                     first adopts artifacts from a run that predates it,
+                                                     found by the course's own file, gist and session
+                                                     names (and adoption sticks, even if you then decline
+                                                     every delete -- `university-artifact remove` undoes
+                                                     one).
+                                                     Composes with reset: cleanup takes back what the
+                                                     course made, reset starts it over -- both, in either
+                                                     order, leave nothing behind.
+          streamweaver university-stop            Put the course down: stop the listener, close its demo
+                                                     canvas sessions and the two iTerm2 windows
+                                                     get-started opened. Keeps your progress and the
+                                                     artifact manifest.
           streamweaver focus-me                   Bring the calling terminal's own iTerm2 pane to the
                                                      front. Silent no-op outside iTerm2/darwin.
       HELP
@@ -1537,6 +1562,7 @@ module StreamWeaver
     # Stop the canvas bridge
     def self.canvas_stop
       require_relative 'canvas/client'
+      Canvas::StalenessGuard.disable!
 
       if Canvas::Client.stop_bridge
         puts "Canvas bridge stopped"
@@ -1814,6 +1840,7 @@ module StreamWeaver
     # to blow away), asks for confirmation before stopping unless --yes.
     def self.canvas_restart(args = [])
       require_relative 'canvas/client'
+      Canvas::StalenessGuard.disable!
 
       auto_yes = args.include?('--yes') || args.include?('-y')
 
@@ -1865,6 +1892,36 @@ module StreamWeaver
       exit 1 unless ok
     end
 
+    # The programmatic core of canvas-restart: snapshot -> stop -> start ->
+    # wait -> restore, with none of the command's narration, prompting or exit
+    # codes. Returns { ok:, dir:, unconfirmed:, old_port:, port: } -- `ok` is
+    # true iff every session that needed restoring came back, `unconfirmed`
+    # names the sessions the snapshot could not read at all, and the two ports
+    # let the caller say so when the bridge moved. All three are things the
+    # caller owes the operator: it cannot honestly claim to have preserved a
+    # session it never read, or to have healed anything if every open tab is
+    # now pointing at a dead port (the ps84 port-squat gotcha, which
+    # canvas-restart itself warns about in stars).
+    #
+    # Used by the staleness auto-heal (disc-171), which runs in the middle of
+    # some other command: it must not exit that command, and must not stop to
+    # ask a question nobody is sitting there to answer.
+    def self.restart_bridge_preserving_sessions
+      require_relative 'canvas/client'
+      Canvas::StalenessGuard.disable!
+
+      old_port = Canvas::Client.bridge_running? ? Canvas::Client.read_bridge_info&.dig(:port) : nil
+
+      dir = default_snapshot_dir
+      snapshot = do_canvas_snapshot(dir)
+      Canvas::Client.stop_bridge
+      new_port = Canvas::Client.ensure_bridge_running[:port]
+      wait_for_bridge_ready
+
+      { ok: do_canvas_restore(dir, force: false), dir: dir,
+        unconfirmed: snapshot[:unconfirmed] || [], old_port: old_port, port: new_port }
+    end
+
     # Bounded-wait retry on the bridge's liveness, called right after
     # ensure_bridge_running in canvas-restart before handing off to
     # do_canvas_restore (stream_weaver-f568, a canvas-restart fix cycle
@@ -2293,8 +2350,8 @@ module StreamWeaver
     # Usage: streamweaver panel [session-name] [--fresh]
     #
     # Panel never opens an external browser - the point is to have the browser
-    # inline in a split pane. If iTerm2 Web Browser profile isn't available,
-    # we just print the URL for the user to open manually.
+    # inline in a split pane. If the split itself couldn't be made, we just
+    # print the URL for the user to open manually.
     def self.panel(args)
       # See canvas_session for why this require comes before the guard.
       require_relative 'iterm'
@@ -2764,6 +2821,28 @@ module StreamWeaver
       ITerm.python_api_reachable?
     end
 
+    # Advisory, not blocking: a missing Browser Plugin still lets get-started
+    # run, it just falls back to opening the canvas in a regular browser tab
+    # instead of an iTerm2 window (get_started_premier does that fallback
+    # itself). Kept out of get_started_premier_ok?'s gate on purpose -- see
+    # there. Field report: a fresh macOS tester who'd installed the plugin
+    # but still lacked a saved "Web Browser" profile is no longer relevant
+    # to whether panes render (StreamWeaver never needs that saved profile
+    # -- see BROWSER_TYPE_PROPERTY in iterm.rb) but the plugin itself is a
+    # real, separate download this cannot substitute for.
+    def self.get_started_premier_browser_plugin?
+      require_relative 'iterm'
+      ITerm.browser_plugin_available?
+    end
+
+    # Advisory, same reasoning as browser_plugin above. Ships enabled, so
+    # this only ever fails for someone who went looking in Settings →
+    # Advanced and switched it off.
+    def self.get_started_premier_browser_style_enabled?
+      require_relative 'iterm'
+      ITerm.browser_style_profiles_enabled?
+    end
+
     # `gh` is only needed by course step 5 (pushing a doc to a gist), long
     # after get-started has already opened the door -- advisory, never a
     # blocker, same spirit as the "no agent CLI" warning above.
@@ -2810,16 +2889,23 @@ module StreamWeaver
             darwin: get_started_premier_darwin?,
             in_iterm: get_started_premier_in_iterm?,
             gem_loadable: get_started_premier_gem_loadable?,
-            python_api: get_started_premier_python_api?
+            python_api: get_started_premier_python_api?,
+            browser_plugin: get_started_premier_browser_plugin?,
+            browser_style_enabled: get_started_premier_browser_style_enabled?
           }
         else
-          { darwin: nil, in_iterm: nil, gem_loadable: nil, python_api: nil }
+          { darwin: nil, in_iterm: nil, gem_loadable: nil, python_api: nil,
+            browser_plugin: nil, browser_style_enabled: nil }
         end
       }
     end
 
+    # browser_plugin / browser_style_enabled are deliberately excluded: both
+    # are advisory (see get_started_premier_browser_plugin? and its sibling),
+    # never a reason to fall back to the fully degraded (non-iTerm2)
+    # experience.
     def self.get_started_premier_ok?(report)
-      report[:premier].values.all?
+      %i[darwin in_iterm gem_loadable python_api].all? { |k| report[:premier][k] }
     end
 
     # --- Reporting ---
@@ -2849,6 +2935,21 @@ module StreamWeaver
       puts "    #{get_started_check_mark(report[:premier][:in_iterm])} running inside iTerm2"
       puts "    #{get_started_check_mark(report[:premier][:gem_loadable])} iterm2_ruby gem installed"
       puts "    #{get_started_check_mark(report[:premier][:python_api])} iTerm2 Python API reachable"
+      if report[:premier][:browser_plugin] == false
+        puts "    ❌ iTerm2 Browser Plugin"
+        puts "        Not installed — download from https://iterm2.com/browser-plugin.html and unzip " \
+             "into /Applications (no need to run it). Never blocks: get-started falls back to opening " \
+             "the canvas in your regular browser tab."
+      else
+        puts "    #{get_started_check_mark(report[:premier][:browser_plugin])} iTerm2 Browser Plugin"
+      end
+      if report[:premier][:browser_style_enabled] == false
+        puts "    ❌ iTerm2 \"Enable browser-style profiles\" (Settings → Advanced, Experimental Features)"
+        puts "        Off — turn it on and restart iTerm2. Never blocks: same browser-tab fallback as above."
+      else
+        puts "    #{get_started_check_mark(report[:premier][:browser_style_enabled])} " \
+             "iTerm2 \"Enable browser-style profiles\" (Advanced setting)"
+      end
       # `.dig` -- :course is absent from a hand-built report (a caller that
       # only wants the premier-tier printing, e.g. an old/partial report),
       # and neither entry here ever blocks get-started. Distinguished from
@@ -2953,6 +3054,332 @@ module StreamWeaver
       end
     end
 
+    # `streamweaver university-artifact add <ref>` / `list`: the manual door
+    # onto the course's artifact manifest, for the one artifact nothing can
+    # record on its own. A saved doc records itself (growing_doc) and a demo
+    # canvas session records itself (Listener.warm_up!), but a gist exists
+    # only inside the worker's own `gh gist create` output -- step 5's
+    # prompt has the worker run this the moment it has the URL.
+    #
+    # The manifest is what `university-cleanup` is allowed to delete, so
+    # `add` is deliberately narrow: a ref whose type can't be determined is
+    # refused rather than recorded under a guess.
+    def self.university_artifact(args)
+      require_relative 'university/artifacts'
+      case (args.first || 'list')
+      when 'list' then university_artifact_list
+      when 'add' then university_artifact_add(args.drop(1))
+      when 'remove' then university_artifact_remove(args.drop(1))
+      else
+        $stderr.puts "Usage: streamweaver university-artifact " \
+                     "[list | add <ref> [--step N] [--type doc|org|gist|session] | remove <ref> [--type T]]"
+        exit 1
+      end
+    end
+
+    def self.university_artifact_list
+      grouped = University::Artifacts.grouped
+      if grouped.empty?
+        puts "No University artifacts recorded yet."
+        return
+      end
+
+      grouped.each do |type, entries|
+        puts "#{University::Artifacts.label(type)} (#{entries.size}):"
+        entries.each do |entry|
+          step = entry['step'] ? " [step #{entry['step']}]" : ''
+          puts "  #{entry['ref']}#{step}"
+        end
+      end
+    end
+
+    def self.university_artifact_add(args)
+      step = flag_value(args, '--step')
+      type = flag_value(args, '--type')
+      ref = positional(args, valued_flags: %w[--step --type])
+
+      unless ref
+        $stderr.puts "Usage: streamweaver university-artifact add <ref> [--step N] [--type doc|org|gist|session]"
+        exit 1
+      end
+
+      entry = University::Artifacts.record!(ref, type: type, step: step)
+      unless entry
+        $stderr.puts "Not recorded: could not tell what kind of artifact #{ref} is."
+        $stderr.puts "Pass one explicitly: --type #{University::Artifacts::TYPES.join('|')}"
+        exit 1
+      end
+
+      puts "Recorded #{entry['type']}: #{entry['ref']}#{entry['step'] ? " (step #{entry['step']})" : ''}"
+    end
+
+    # Drops one entry from the manifest WITHOUT deleting the thing it names
+    # -- the counterweight to `add` and to `--scan`'s adoption. Recording is
+    # what makes an artifact destroyable, so "I did not mean to record that"
+    # needs an answer that isn't hand-editing artifacts.yml; without one, a
+    # mistaken adoption is offered by every cleanup run forever.
+    def self.university_artifact_remove(args)
+      type = flag_value(args, '--type')
+      ref = positional(args, valued_flags: %w[--type])
+
+      unless ref
+        $stderr.puts "Usage: streamweaver university-artifact remove <ref> [--type doc|org|gist|session]"
+        exit 1
+      end
+
+      # A doc/org ref is stored expanded, so match what the user typed AND
+      # what it resolves to from here -- otherwise a relative path they can
+      # see in `list` is one they cannot remove. File.identical? is the last
+      # of the three because it is the only one that sees through a symlink
+      # (on macOS `Dir.pwd` reports /private/var where the recorded path
+      # says /var, and string comparison alone misses that).
+      candidates = [ref, File.expand_path(ref)].uniq
+      matches = University::Artifacts.all.select do |entry|
+        next false unless type.nil? || entry['type'] == type
+
+        candidates.include?(entry['ref']) ||
+          (File.exist?(entry['ref']) && File.exist?(ref) && File.identical?(entry['ref'], ref))
+      end
+
+      if matches.empty?
+        $stderr.puts "Not in the manifest: #{ref}"
+        exit 1
+      end
+
+      matches.each do |entry|
+        University::Artifacts.forget!(entry['type'], entry['ref'])
+        puts "Removed #{entry['type']} from the manifest: #{entry['ref']}"
+      end
+      puts "(the #{matches.size == 1 ? 'artifact itself is' : 'artifacts themselves are'} untouched on disk)"
+    end
+
+    # `--flag value` or `--flag=value`, or nil. Local to the university
+    # artifact commands, which are the only ones here taking optional
+    # valued flags.
+    def self.flag_value(args, flag)
+      inline = args.grep(/\A#{Regexp.escape(flag)}=/) { |a| a.split('=', 2).last }.first
+      return inline if inline
+
+      idx = args.index(flag)
+      idx ? args[idx + 1] : nil
+    end
+
+    # The first real argument, with flags AND the values of the separated
+    # `--flag value` forms skipped. Not just "the first thing not starting
+    # with a dash": `university-artifact add --type doc /tmp/a.rb` would
+    # otherwise record the literal ref "doc", and a relative ref like that
+    # is precisely what cleanup would later resolve against some other
+    # process's working directory. Flags-before-positional is exactly the
+    # shape an agent produces, and step 5's prompt hands this command to one.
+    def self.positional(args, valued_flags: [])
+      skip_next = false
+      args.find do |arg|
+        if skip_next
+          skip_next = false
+          next false
+        end
+        skip_next = valued_flags.include?(arg)
+        !arg.start_with?('-')
+      end
+    end
+
+    # `streamweaver university-cleanup`: the course offers to take back
+    # everything it left on the machine -- the docs it saved, the .org files
+    # exported from them, the gists published, the demo canvas sessions it
+    # opened, and its own state files.
+    #
+    # Confirmed per GROUP, except gists, which are confirmed one at a time
+    # showing the URL: a gist is the only artifact here that left the
+    # machine and cannot be undeleted. Every delete goes through
+    # University::Cleanup, the same module the canvas's own delete buttons
+    # use, so "what may be deleted" is answered in exactly one place.
+    def self.university_cleanup(args)
+      require_relative 'university/cleanup'
+      dry_run = args.include?('--dry-run')
+      # A dry-run scan previews without adopting, so what it found is NOT in
+      # the inventory below. Carried here so the two can't contradict each
+      # other -- listing a found artifact and then saying there is nothing to
+      # clean up is the one transcript this command must never print.
+      scanned = args.include?('--scan') ? print_cleanup_scan(dry_run) : []
+      inventory = University::Cleanup.inventory
+
+      if University::Cleanup.empty?(inventory)
+        return puts("Nothing to clean up -- StreamWeaver University has not recorded any artifacts.") if
+          scanned.empty?
+      else
+        print_cleanup_inventory(inventory)
+      end
+
+      if dry_run
+        puts ""
+        puts "--dry-run: nothing was deleted."
+        return
+      end
+
+      puts ""
+      # get_started_confirm? answers "no" for every question when there is
+      # no tty to ask at, which is the right default for a destructive
+      # command and a baffling transcript without this line -- every group
+      # comes back "Kept" for no visible reason.
+      puts "(no terminal to confirm at -- everything will be kept)" unless $stdin.tty?
+      cleanup_group('doc', inventory['doc'], "Delete #{inventory['doc'].size} saved doc file(s)?")
+      cleanup_group('org', inventory['org'], "Delete #{inventory['org'].size} exported .org file(s)?")
+      cleanup_gists(inventory['gist'])
+      cleanup_group('session', inventory['session'],
+                    "Close #{inventory['session'].size} course canvas session(s)?")
+      cleanup_state_files(inventory[University::Cleanup::STATE])
+      puts ""
+      puts "Cleanup done."
+    end
+
+    # `--scan`: find artifacts from a run that predates the manifest, by the
+    # course's own deterministic names, and adopt them into it so the
+    # ordinary grouped confirm can offer them. Adoption is a write, so
+    # `--dry-run` reports the same findings and records nothing -- a flag
+    # that promises to change nothing must not quietly change the manifest.
+    def self.print_cleanup_scan(dry_run)
+      refs = if dry_run
+               University::Cleanup.scan_unrecorded.values.flatten
+             else
+               University::Cleanup.adopt_scan!.map { |entry| entry['ref'] }
+             end
+
+      if refs.empty?
+        puts "--scan: nothing on this machine matches the course's own file, session or gist names."
+      else
+        puts "--scan #{dry_run ? 'found' : 'adopted'} #{refs.size} artifact(s) the manifest did not record:"
+        refs.each { |ref| puts "  #{ref}" }
+      end
+      puts ""
+      refs
+    end
+
+    def self.print_cleanup_inventory(inventory)
+      puts "StreamWeaver University created these:"
+      print_cleanup_files(University::Artifacts.label('doc'), inventory['doc'])
+      print_cleanup_files(University::Artifacts.label('org'), inventory['org'])
+      print_cleanup_refs(University::Artifacts.label('gist'), inventory['gist'])
+      print_cleanup_refs(University::Artifacts.label('session'), inventory['session'])
+      print_cleanup_files("University state files", inventory[University::Cleanup::STATE])
+    end
+
+    def self.print_cleanup_files(label, entries)
+      return if entries.empty?
+
+      puts ""
+      puts "#{label} (#{entries.size}):"
+      entries.each do |entry|
+        detail = entry[:exists] ? "#{entry[:size]} bytes" : "missing (already deleted)"
+        puts "  #{entry[:ref]} -- #{detail}"
+      end
+    end
+
+    def self.print_cleanup_refs(label, entries)
+      return if entries.empty?
+
+      puts ""
+      puts "#{label} (#{entries.size}):"
+      entries.each { |entry| puts "  #{entry[:ref]}" }
+    end
+
+    # One y/N for a whole group. Declining leaves every entry in the
+    # manifest, so a later run can still offer them. Deletes through
+    # `delete_refs!` rather than looping `delete_entry!` here: that is where
+    # a refusal becomes a reported outcome instead of an exception, and a
+    # backtrace halfway through a destructive command -- with some files
+    # already gone and the remaining groups never offered -- is the one
+    # failure mode this command must not have.
+    def self.cleanup_group(type, entries, question)
+      return if entries.empty?
+      return puts("Kept: #{University::Artifacts.label(type).downcase}.") unless
+        get_started_confirm?(question, default: false)
+
+      University::Cleanup.delete_refs!(type, entries.map { |entry| entry[:ref] })
+                         .each { |outcome| puts "  #{outcome.message}" }
+    end
+
+    # Per ITEM, showing the URL. A gist is public, remote, and gone for
+    # good -- the one thing here worth asking about individually.
+    def self.cleanup_gists(entries)
+      return if entries.empty?
+
+      unless University::Cleanup.gh_available?
+        puts ""
+        puts "gh is not installed, so gists cannot be deleted from here. Delete these yourself:"
+        entries.each { |entry| puts "  #{entry[:ref]}" }
+        return
+      end
+
+      entries.each do |entry|
+        if get_started_confirm?("Delete gist #{entry[:ref]}?", default: false)
+          University::Cleanup.delete_refs!('gist', [entry[:ref]])
+                             .each { |outcome| puts "  #{outcome.message}" }
+        else
+          puts "  Kept #{entry[:ref]}"
+        end
+      end
+    end
+
+    def self.cleanup_state_files(entries)
+      return if entries.empty?
+
+      question = "Delete #{entries.size} University state file(s) " \
+                 "(progress, artifact manifest, worker/listener records)?"
+      return puts("Kept: University state files.") unless get_started_confirm?(question, default: false)
+
+      University::Cleanup.delete_state_files!.each { |outcome| puts "  #{outcome.message}" }
+    end
+
+    # `streamweaver university-stop`: put the course down without throwing
+    # any of it away. Stops the listener, closes the demo canvas sessions and
+    # the two iTerm2 surfaces `get-started` opened (the agent's worker tab
+    # and the controller window), and keeps every file -- progress and the
+    # artifact manifest both. Deleting is `university-cleanup`'s job;
+    # starting over is `university-reset`'s. This is neither.
+    #
+    # Never touches a session or window the course did not open: the canvas
+    # sessions come from the same allowlist `university-reset` closes by, and
+    # the two iTerm2 sessions are the exact ids `get-started` recorded in
+    # worker.json.
+    def self.university_stop(_args = [])
+      require_relative 'canvas/client'
+      require_relative 'university/artifacts'
+
+      puts(University::Listener.stop! ? "Stopped the University listener." : "University listener was not running.")
+
+      if Canvas::Client.bridge_running?
+        # clear_state: false -- stopping is not starting over, so step 4's
+        # growing doc must still remember what it had when the user returns.
+        University::Listener.close_demo_sessions!(clear_state: false)
+        puts "Closed the course demo canvas sessions: #{University::Listener::DEMO_SESSION_NAMES.join(', ')}"
+      else
+        puts "(canvas bridge not running -- no demo sessions to close)"
+      end
+
+      close_university_iterm_sessions
+      puts "Kept your progress (#{University::Progress.path})"
+      puts "Kept the artifact manifest (#{University::Artifacts.path}) -- `streamweaver university-cleanup` removes what the course created."
+    end
+
+    # Closes the worker tab and the controller window `get-started` recorded,
+    # and nothing else. A session that is already gone (or was never
+    # recorded, on the degraded path) is skipped silently -- both are the
+    # ordinary case, not a failure worth reporting.
+    def self.close_university_iterm_sessions
+      require_relative 'iterm'
+      recorded = University::Runner.worker or return
+
+      {
+        'session_id' => 'worker tab',
+        'controller_session_id' => 'University canvas window'
+      }.each do |key, label|
+        id = recorded[key]
+        next unless id && ITerm.session_alive?(id)
+
+        puts "Closed the #{label}." if ITerm.close_pane(id)
+      end
+    end
+
     # Print the absolute path of a canned course demo inside the installed
     # gem. Every Getting Started prompt runs its demo through this rather
     # than naming a path, so the course works from a plain `gem install`
@@ -3099,6 +3526,22 @@ module StreamWeaver
         # Forrest's Law: don't hand the user a URL and a chore. The degraded
         # path already opens the browser itself; do the same here.
         $stderr.puts "Could not open the canvas window in iTerm2 — opening it in your browser instead."
+        # Print WHY, honestly -- ITerm.open_browser_window used to swallow
+        # its exception entirely (rescue StandardError; nil), which left a
+        # tester with no way to tell what went wrong. last_error surfaces
+        # the underlying exception; browser_plugin_available? gives the one
+        # targeted hint worth naming explicitly, since a missing Browser
+        # Plugin is the failure this path is most likely to hit and has a
+        # known fix -- guarded on `available?` so a broader connectivity
+        # failure (already explained by last_error above) doesn't get
+        # misreported as a missing plugin.
+        if (err = ITerm.last_error)
+          $stderr.puts "    (#{err.class}: #{err.message})"
+        end
+        if ITerm.available? && !ITerm.browser_plugin_available?
+          $stderr.puts "    iTerm2's Browser Plugin isn't installed — download it from " \
+                       "https://iterm2.com/browser-plugin.html and unzip into /Applications."
+        end
         open_browser(canvas_url)
       end
       puts "Recorded: #{path}"

data/lib/stream_weaver/iterm.rb

@@ -8,8 +8,40 @@ module StreamWeaver
   # (`gem install iterm2_ruby` — https://rubygems.org/gems/iterm2_ruby).
   # Falls back to system browser when iTerm2 API is unavailable.
   class ITerm
-    # iTerm2's built-in profile that renders a web view instead of a shell.
-    BROWSER_PROFILE = "Web Browser"
+    # A pane renders a web view instead of a shell when its profile's
+    # "Custom Command" property is the literal string "Browser" -- this is
+    # exactly how iTerm2's own built-in "Web Browser" profile is defined
+    # (confirmed by reading it out of `defaults read com.googlecode.iterm2
+    # "New Bookmarks"`). Passing it as a profile_customizations override on
+    # split_pane/create_tab produces a genuine browser pane from ANY base
+    # profile -- verified live (title came back as the loaded page's own
+    # <title>, not a shell prompt) -- so nothing here depends on a
+    # "Web Browser" profile actually being installed. A fresh macOS/iTerm2
+    # install with only "Default" in its profile list works identically.
+    #
+    # This still needs iTerm2's own browser feature to be usable, which
+    # (per iterm2.com/documentation-preferences-profiles-general.html) is
+    # gated on TWO things this override cannot bypass: the separately
+    # downloaded Browser Plugin (browser_plugin_available? below), and the
+    # "Enable browser-style profiles" Advanced setting (enabled by default;
+    # browser_style_profiles_enabled? below). The live verification above
+    # ran on a machine with both already satisfied -- a fresh install
+    # lacking the plugin needs it installed regardless of this override.
+    BROWSER_TYPE_PROPERTY = { "Custom Command" => "Browser" }.freeze
+
+    # iTerm2's bundle identifier for its own separately-downloaded Browser
+    # Plugin (iterm2.com/browser-plugin.html: unzip into /Applications,
+    # "you don't need to run it; iTerm2 will locate it automatically").
+    # Matches the plugin's own Info.plist CFBundleIdentifier, confirmed on
+    # a machine that has it installed.
+    BROWSER_PLUGIN_BUNDLE_ID = "com.googlecode.iterm2.iTermBrowserPlugin"
+
+    # The Advanced setting's persisted preference key (found in the app
+    # binary's strings: "advancedSettingsModelDictionary_browserProfiles" /
+    # "browserProfilesUserDefaultsKey", labeled in Settings → Advanced as
+    # "Experimental Features: Enable browser-style profiles?"). Unset on a
+    # machine that has never touched it -- iTerm2 defaults it to enabled.
+    BROWSER_STYLE_PROFILES_PREF_KEY = "browserProfiles"
 
     # Default window frames (points) for the two windows this class ever
     # creates from scratch -- the University controller (narrow, tall) and a
@@ -56,6 +88,41 @@ module StreamWeaver
           !ENV["ITERM_SESSION_ID"].to_s.empty?
       end
 
+      # True when iTerm2's Browser Plugin is installed -- checked the same
+      # way iTerm2 itself locates it (by bundle identifier via Launch
+      # Services/Spotlight, not a fixed path), so this is accurate
+      # regardless of which folder the user unzipped it into. Needs no
+      # Python API connection at all -- darwin-only, since mdfind is a
+      # macOS tool. False on any doubt (not darwin, mdfind missing/erroring,
+      # timeout), same spirit as every other probe in this file.
+      def browser_plugin_available?
+        return false unless RbConfig::CONFIG["host_os"].match?(/darwin/)
+
+        with_timeout(5, default: false) do
+          out = `mdfind "kMDItemCFBundleIdentifier == '#{BROWSER_PLUGIN_BUNDLE_ID}'" 2>/dev/null`
+          !out.strip.empty?
+        end
+      rescue StandardError
+        false
+      end
+
+      # True unless the user has explicitly turned off iTerm2's "Enable
+      # browser-style profiles" Advanced setting -- an "Experimental
+      # Features" toggle that ships enabled, so an unset preference (the
+      # common case) reads as enabled rather than disabled. Reads the
+      # plist directly via `defaults`, not the Python API -- this is a
+      # plain macOS preference, no RPC involved.
+      def browser_style_profiles_enabled?
+        return false unless RbConfig::CONFIG["host_os"].match?(/darwin/)
+
+        with_timeout(5, default: true) do
+          out = `defaults read com.googlecode.iterm2 #{BROWSER_STYLE_PROFILES_PREF_KEY} 2>/dev/null`.strip
+          out != "0"
+        end
+      rescue StandardError
+        true
+      end
+
       # Split a browser pane with the URL into `target_session` (any session
       # id, e.g. a just-created worker tab's session -- not necessarily the
       # calling pane). Defaults to the calling session (current_session_guid)
@@ -99,6 +166,7 @@ module StreamWeaver
       def open_browser_window(url)
         return nil unless available?
 
+        @last_error = nil
         with_timeout(10, default: nil) do
           connect do |c|
             created = c.create_tab
@@ -119,10 +187,22 @@ module StreamWeaver
             pane
           end
         end
-      rescue StandardError
+      rescue StandardError => e
+        @last_error = e
         nil
       end
 
+      # The exception that made the most recent open_browser_window call
+      # fall back to nil, or nil if that call succeeded (or hasn't run
+      # yet). Reset at the start of every open_browser_window call, so a
+      # caller committed to the honest-fallback message (get-started's
+      # premier path, cli.rb) can report WHY the canvas window couldn't
+      # open instead of the silent nil this class returned before --
+      # rather than parse it out of a swallowed rescue.
+      def last_error
+        @last_error
+      end
+
       def close_pane(pane_id)
         return false unless available? && pane_id
         connect { |c| c.close_session(pane_id, force: true) }
@@ -298,15 +378,17 @@ module StreamWeaver
       # The browser pane for `url`, or nil. The real client raises on a
       # failed split (and returns nil only for an OK response with no
       # session), so both spellings of failure are caught here rather than
-      # unwinding past the shell cleanup above.
+      # unwinding past the shell cleanup above. No profile_name: the split
+      # inherits whatever profile `shell` already has, and BROWSER_TYPE_PROPERTY
+      # overrides it into a browser pane regardless (see that constant).
       def browser_pane_in(client, shell, url)
         client.split_pane(
           shell,
           vertical: true,
-          profile_name: BROWSER_PROFILE,
-          profile_customizations: { "Initial URL" => url }
+          profile_customizations: BROWSER_TYPE_PROPERTY.merge("Initial URL" => url)
         )
-      rescue StandardError
+      rescue StandardError => e
+        @last_error = e
         nil
       end
 
@@ -441,8 +523,7 @@ module StreamWeaver
             c.split_pane(
               guid,
               vertical: !horizontal,
-              profile_name: BROWSER_PROFILE,
-              profile_customizations: { "Initial URL" => url }
+              profile_customizations: BROWSER_TYPE_PROPERTY.merge("Initial URL" => url)
             )
           end
         end