samagotchi 0.60.0 → 0.61.0

data/lib/samagotchi/session.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 require_relative "atomic_file"
 require_relative "context_note"
+require_relative "interrupted_turn"
 require_relative "last_turn"
 require_relative "llm_context_override"
 require_relative "session_setup"
@@ -107,6 +108,26 @@ module Samagotchi
     def last_turn=(value)
       @last_turn = LastTurn.from_file(value)
     end
+
+    # The mark of a turn a worker checkpointed and never finished
+    # (InterruptedTurn), as loaded; the next worker settles it and sets it
+    # to nil. While a turn runs, #turn_checkpoint's marker is saved instead.
+    attr_reader :interrupted_turn
+
+    # @param value [InterruptedTurn, Hash, nil]
+    def interrupted_turn=(value)
+      @interrupted_turn = InterruptedTurn.from_file(value)
+    end
+
+    # The running turn's checkpoint (TurnCheckpoint): {messages:, marker:}
+    # (marker an InterruptedTurn). While +status+ is running, every save
+    # writes these messages and the marker instead of #messages and
+    # #interrupted_turn, so a save in the middle of the turn (a question
+    # asked, the checkpoint's own) keeps the turn so far on disk; #messages
+    # itself is never touched. The turn's end sets status idle before it
+    # saves, so that save writes the real messages, without a marker. Not
+    # saved; the worker clears it after each turn.
+    attr_accessor :turn_checkpoint
     # The session's own llm_context values (LLMContextOverride: strategy,
     # apply rule, budget), before the model's; nil when it has none.
     # Saved, so a --resume and a respawned worker keep them; a plugin's
@@ -191,7 +212,8 @@ module Samagotchi
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
-                   continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [])
+                   continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
+                   interrupted_turn: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -220,6 +242,8 @@ module Samagotchi
       self.thinking = thinking
       self.reasoning_history = reasoning_history
       self.appended_prompt_files = appended_prompt_files
+      self.interrupted_turn = interrupted_turn
+      @turn_checkpoint = nil
       @archived = false
     end
 
@@ -363,7 +387,8 @@ module Samagotchi
       "continues" => nil,
       "thinking" => nil,
       "reasoning_history" => nil,
-      "appended_prompt_files" => []
+      "appended_prompt_files" => [],
+      "interrupted_turn" => nil
     }.freeze
 
     # A session from a parsed session file. +messages+ false leaves the
@@ -475,11 +500,15 @@ module Samagotchi
       self
     end
 
-    # The session as #save writes it (FIELDS, in their order).
+    # The session as #save writes it (FIELDS, in their order); a running
+    # turn's checkpoint (#turn_checkpoint) in place of its messages.
     def to_h
+      checkpoint = checkpointed
       FIELDS.keys.to_h do |key|
         value = case key
-                when "messages" then @messages.map { |msg| scrub_utf8(stringify_message_keys(msg)) }
+                when "messages"
+                  (checkpoint ? checkpoint[:messages] : @messages).map { |msg| scrub_utf8(stringify_message_keys(msg)) }
+                when "interrupted_turn" then (checkpoint ? checkpoint[:marker] : @interrupted_turn)&.to_file
                 when "pending_question" then @pending_question && scrub_utf8(stringify_message_keys(@pending_question))
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
@@ -496,6 +525,13 @@ module Samagotchi
       end
     end
 
+    # The running turn's checkpoint, while the turn runs (#turn_checkpoint).
+    def checkpointed
+      checkpoint = @turn_checkpoint
+      checkpoint if checkpoint && @status == STATUS_RUNNING
+    end
+    private :checkpointed
+
     # Mark a session as errored.
     def self.mark_error(session_id, reason:, state_dir: default_state_dir)
       session = load(session_id, state_dir: state_dir)

data/lib/samagotchi/session_manager.rb

@@ -22,6 +22,7 @@ require_relative "turn_note"
 require_relative "owner_lock"
 require_relative "bridge_client"
 require_relative "worker_sidecar"
+require_relative "worker_signals"
 require_relative "log"
 require_relative "log_path"
 require_relative "model_profile"
@@ -210,7 +211,8 @@ module Samagotchi
     # wakes the worker picks which config.yml it reads (docs/guardrails.md).
     private_class_method def self.spawn_options(session)
       # Own process group: workers outlive `chi web`, and a Ctrl-C in its
-      # terminal must not reach them.
+      # terminal must not reach them (the worker then leaves the process
+      # tree too: WORKER_DETACH_ENV).
       opts = { out: File::NULL, err: File::NULL, pgroup: true }
       # The worker's tools (and `!cmd`) run in the session's directory, not
       # in the cwd of whoever woke it (`chi web`, another terminal).
@@ -253,6 +255,10 @@ module Samagotchi
       SESSION_MARKER_ENV.each { |key| child_env[key] = nil }
       # A smoke's fake "newest installed" is for this process's notices only.
       child_env[InstalledVersions::ENV_KEY] = nil
+      # A worker process: run_session_loop traps signals, and leaves this
+      # process's tree.
+      child_env[WORKER_PROCESS_ENV] = "1"
+      child_env[WORKER_DETACH_ENV] = "1"
       # A gem-mode worker activates the newest installed chi itself: under
       # `bundle exec` (a Gemfile that has samagotchi) Bundler's RUBYOPT would
       # hold it to the bundle's version, and its badge would never clear.
@@ -688,8 +694,8 @@ module Samagotchi
     # so a resume right after spawns a fresh worker instead of finding the
     # dying one.
     # A turn still running is canceled first (STOP_CANCEL_WAIT), as the
-    # web's Cancel does: its Engine saves the prompt, which the TERM alone
-    # would lose with the worker.
+    # web's Cancel does: its worker saves it. The TERM stops (and saves)
+    # what still runs (WorkerSignals), with a short grace after the marker.
     # @return [Boolean, nil] with +wait+: whether the owner was gone in time
     # @raise [OwnedByTUI] when the interactive TUI owns the session
     def self.stop_session(session_id, state_dir: nil, wait: nil)
@@ -930,7 +936,8 @@ module Samagotchi
     # @param idle_exit_minutes [Numeric, nil] nil: session.idle_exit_minutes
     # @param poll_interval [Numeric, nil] seconds between the loop's fallback
     #   ticks (nil: Worker::FALLBACK_TICK_SECONDS); queued turns wake it at once
-    # A stopped session's worker exits 0 and a crashed one 1, there.
+    # A stopped session's worker exits 0 (a signalled one too) and a
+    # crashed one 1, there.
     # @return [Symbol] :idle_exit, :exit_requested or :restart
     def self.run_session_loop(session_id, state_dir: nil, owner_wait: OwnerLock::DEFAULT_WAIT,
                               idle_exit_minutes: nil, poll_interval: nil)
@@ -942,6 +949,12 @@ module Samagotchi
       Log.configure(stderr: false)
       Log.session_id = session_id
       session_dir = Session.session_dir(session_id, state_dir: sd)
+      # Read (and taken out of ENV, so nothing the worker runs inherits it)
+      # before anything else: set by spawn_options for a spawned worker.
+      spawned = ENV.delete(WORKER_PROCESS_ENV) == "1"
+      # Out of the spawner's process tree before the lock (it records this
+      # process's pid) and before any thread starts.
+      detach_from_spawner(session_dir) if ENV.delete(WORKER_DETACH_ENV) == "1"
       # Kept in a class ivar so the lock's File lives as long as the worker.
       @owner_lock = OwnerLock.acquire(session_dir, kind: "worker", wait: owner_wait)
       exit(0) unless @owner_lock
@@ -949,8 +962,11 @@ module Samagotchi
       fallback = ENV.delete(BOOT_FALLBACK_ENV)
       Log.info(:worker, "start", cwd: Dir.pwd, version: VERSION)
       Log.warn(:worker, "boot_fallback", version: VERSION, error: fallback) if fallback
+      # A spawned worker stops its turn on TERM/HUP/INT and saves it; a
+      # loop run in-process (specs) traps nothing.
+      signals = spawned ? WorkerSignals.new.install! : WorkerSignals::NONE
       worker = Worker.new(session_id: session_id, state_dir: sd, session_dir: session_dir,
-                          idle_exit_minutes: idle_exit_minutes, poll_interval: poll_interval)
+                          idle_exit_minutes: idle_exit_minutes, poll_interval: poll_interval, signals: signals)
       result = begin
         worker.run
       rescue StandardError, ScriptError => e
@@ -959,11 +975,19 @@ module Samagotchi
         raise
       ensure
         @owner_lock.release
+        # A signal from here on ends the process as Ruby's default does.
+        signals.restore!
       end
       Log.info(:worker, "stop", reason: result)
       # A stopped session is left as it is: no resume for input that came
-      # in, no discard.
+      # in, no discard. One whose worker a signal stopped isn't discarded
+      # either; input that came in (queued behind the turn it stopped)
+      # wakes a new worker, as after an idle exit.
       exit(0) if result == :stopped
+      if result == :signal
+        resume_session(session_id, state_dir: sd) unless SessionInbox.find_new_input_files(session_dir).empty?
+        exit(0)
+      end
       exit(1) if result == :crashed
       # Only after the release: a writer that still saw this worker as the
       # owner may have queued input since the last check. Either it finds no
@@ -981,6 +1005,31 @@ module Samagotchi
       result
     end
 
+    # A spawned worker leaves its spawner's process tree: a killer that
+    # walks the tree by parent pid (a terminal closing, a tool's teardown
+    # of a `chi send --wait` it ran in the background) no longer reaches it.
+    # This process (the spawner's child, which its Process.detach waits on)
+    # forks the worker, which starts a session of its own (setsid: no
+    # controlling terminal, no SIGHUP from one) and returns to run the loop;
+    # this one waits until the worker holds the session's OwnerLock, or has
+    # exited, or WORKER_START_GRACE passed, and exits: the spawner's waiter
+    # stays alive exactly while the worker starts (#still_starting?). The
+    # worker is reparented to init (launchd), which reaps it.
+    private_class_method def self.detach_from_spawner(session_dir)
+      worker = Process.fork
+      unless worker
+        Process.setsid
+        return
+      end
+
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + WORKER_START_GRACE
+      until Process.waitpid(worker, Process::WNOHANG) || OwnerLock.owner(session_dir)&.pid == worker ||
+            Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+        sleep(OwnerLock::RETRY_INTERVAL)
+      end
+      Process.exit!(0)
+    end
+
     # Delete a session its worker left empty. Checked again now the lock is
     # free: a note or input may have come in since the worker looked, and a
     # worker woken meanwhile owns it (delete_session refuses). A `chi send`
@@ -1024,6 +1073,13 @@ module Samagotchi
     # format are read by a NEWER chi than the one writing them. Change them
     # only additively (spec/worker_contract_spec.rb).
     BOOT_FALLBACK_ENV = "SAMAGOTCHI_BOOT_FALLBACK"
+    # "1" in a worker spawn_options started: it traps signals (WorkerSignals).
+    # run_session_loop deletes it from ENV as it reads it.
+    WORKER_PROCESS_ENV = "SAMAGOTCHI_WORKER_PROCESS"
+    # "1" in a worker spawn_options started: run_session_loop leaves the
+    # spawner's process tree first (detach_from_spawner); deleted from ENV
+    # as it is read, so an rspec run by the worker's execute never forks.
+    WORKER_DETACH_ENV = "SAMAGOTCHI_WORKER_DETACH"
 
     def self.worker_command(session_id, state_dir:, gem_spec: InstalledGem.spec)
       boot = "require 'samagotchi/session_manager'; " \
@@ -1046,6 +1102,8 @@ module Samagotchi
       command = worker_command(session.id, state_dir: state_dir)
       pid = env ? Process.spawn(env, *command, **opts) : Process.spawn(*command, **opts)
       # Reaped when it exits: a long-lived spawner (chi web) keeps no zombies.
+      # +pid+ is the worker's starter, which exits once the worker it forked
+      # holds the lock (detach_from_spawner): the lock's pid is the worker's.
       note_spawn(session.id, state_dir: state_dir, waiter: Process.detach(pid))
       Log.info(:worker, "spawn", sid: session.id, child_pid: pid)
       pid

data/lib/samagotchi/terminal_ui.rb

@@ -9,6 +9,7 @@ require_relative "client_id"
 require_relative "iteration_limit"
 require_relative "model_profile"
 require_relative "turn_note"
+require_relative "turn_checkpoint"
 require_relative "config"
 require_relative "context_note"
 require_relative "cancellation_controller"
@@ -277,6 +278,9 @@ module Samagotchi
         session.save if @resume_session
       end
       claim_session!(session.id) unless @owner_lock
+      # A turn a worker died in (TurnCheckpoint): ended as canceled, with its
+      # note, before this REPL's first turn appends after it.
+      session.save if @resume_session && TurnCheckpoint.settle(session)
       keep_cards(session)
       # Saved at once, so a process killed before its first turn leaves a
       # file the sweep knows to delete.

data/lib/samagotchi/turn_checkpoint.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "interrupted_turn"
+require_relative "log"
+require_relative "session"
+require_relative "steer"
+require_relative "turn_note"
+
+module Samagotchi
+  # A worker's running turn, kept on disk at the loop's iteration
+  # boundaries, so a worker killed mid-turn (SIGKILL, a crash of the
+  # process) loses at most INTERVAL seconds of it instead of all of it.
+  #
+  # At each boundary (Worker#pending_input_drain, on the turn's thread) the
+  # turn's live conversation (Engine#live_conversation) is copied, with the
+  # lines that boundary merges (their input files are deleted as they are
+  # claimed), into the session's overlay (Session#turn_checkpoint), marked
+  # with an InterruptedTurn. Every save while the turn runs writes the
+  # overlay instead of the session's messages: this one's, written at the
+  # first boundary (the prompt reaches the disk) and then at most every
+  # INTERVAL (or when the boundary merged input), and any other save in the
+  # turn (a question asked). The session's in-memory messages never change
+  # (a Bridge snapshot shows the turn in progress or in the messages, never
+  # both). The turn's end saves the real messages without a marker.
+  #
+  # The copy is what a Stop at that boundary would keep, minus its note, so
+  # the history before the turn is never rewritten (prompt caching); later
+  # steps of the same turn may still edit their own entries in place.
+  class TurnCheckpoint
+    INTERVAL = 10.0
+
+    # A session loaded with an InterruptedTurn mark (its worker died in the
+    # turn): the turn ends now, as canceled. Its note goes at the tail
+    # (append-only: the model reads on its next turn that the previous one
+    # was cut, after how long), the status goes idle and the mark goes. The
+    # dead turn is not run again. The caller saves.
+    #
+    # last_turn is left as it was: a new last_turn saved idle here, before
+    # the turn a `chi send --wait` started this worker for, would end that
+    # wait at once as the sent turn's (ReplyWait compares last_turn), with
+    # the dead turn's outcome.
+    # @return [InterruptedTurn, nil] the mark settled, nil when there was none
+    def self.settle(session)
+      mark = session.interrupted_turn
+      return nil unless mark
+
+      messages = Array(session.messages)
+      # How long it ran up to its last checkpoint (it died later); none
+      # when that was its first boundary ("after 0s" would mislead).
+      seconds = mark.seconds
+      seconds = nil if seconds && seconds < 1
+      note = TurnNote.cancelled(:worker_stopped, seconds: seconds, shown: TurnNote.interrupted_tail?(messages))
+      session.messages = messages + [note]
+      session.status = Session::STATUS_IDLE if session.status == Session::STATUS_RUNNING
+      session.interrupted_turn = nil
+      mark
+    end
+
+    # @param session [Session] the worker's session (saved as a whole)
+    # @param clock [#call] monotonic seconds (specs)
+    def initialize(session:, state_dir:, interval: INTERVAL, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+      @session = session
+      @state_dir = state_dir
+      @interval = interval
+      @clock = clock
+      @boundaries = 0
+      @written_at = nil
+      @started_at = nil
+    end
+
+    # A turn begins (before Engine#run_turn and the worker's running save):
+    # the overlay starts as the history plus +prompt+ (text only: no
+    # images, no turn id), marked at iteration 0, so a worker killed before
+    # the loop's first boundary leaves the prompt and a mark the next one
+    # settles. A continue turn (no prompt) is the history, marked.
+    # @param prompt [String, nil]
+    def begin_turn(prompt: nil)
+      @boundaries = 0
+      @written_at = nil
+      @started_at = Time.now.iso8601(3)
+      messages = Array(@session.messages).dup
+      messages << { role: "user", content: prompt } unless prompt.to_s.empty?
+      @session.turn_checkpoint = { messages: messages, marker: InterruptedTurn.new(started_at: @started_at, at: @started_at, iteration: 0) }
+    end
+
+    # The turn ended (or never began): the session saves its own messages.
+    def end_turn
+      @session.turn_checkpoint = nil
+    end
+
+    # An iteration boundary of the running turn.
+    # @param conversation [Array<Hash>, nil] the loop's live conversation;
+    #   nil (no turn): nothing
+    # @param merging [Array<Steer::Line>] the lines this boundary merges
+    #   (appended after the conversation, as Steer.inject! will)
+    # @param turn_id [String, nil]
+    # @return [Boolean] whether the session file was written
+    def boundary(conversation, merging: [], turn_id: nil)
+      return false unless conversation
+
+      @boundaries += 1
+      merged = merging.empty? ? [] : Steer.merge(merging).messages
+      # One level deep: the loop may edit an entry in place later (a
+      # forget stub) while a save on another thread serializes this one.
+      messages = conversation.map { |message| message.is_a?(Hash) ? message.dup : message } + merged
+      marker = InterruptedTurn.new(id: turn_id, started_at: @started_at, at: Time.now.iso8601(3), iteration: @boundaries)
+      @session.turn_checkpoint = { messages: messages, marker: marker }
+      return false unless due? || !merged.empty?
+
+      write
+    end
+
+    private
+
+    def due? = @written_at.nil? || @clock.call - @written_at >= @interval
+
+    def write
+      @session.save(state_dir: @state_dir)
+      @written_at = @clock.call
+      true
+    rescue StandardError => e
+      # The turn goes on; the next boundary tries again.
+      Log.warn(:worker, "checkpoint_failed", error: e.class.name, msg: e.message)
+      false
+    end
+  end
+end

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.60.0"
+  VERSION = "0.61.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end

data/lib/samagotchi/web/app.rb

@@ -13,6 +13,7 @@ require_relative "../analytics_file"
 require_relative "../client_id"
 require_relative "../delivery"
 require_relative "../answer_tail"
+require_relative "../answer_refs"
 require_relative "../bridge_client"
 require_relative "../bridge/bounded_queue"
 require_relative "../bridge/card_store"
@@ -1907,6 +1908,10 @@ module Samagotchi
             message[:display] = shown unless shown.strip.empty?
             rendered = message[:display] || stripped
             message[:html] = @markdown_renderer.render(rendered) if !rendered.empty? && @markdown_renderer.available?
+            # The refs after_turn hooks attached (AnswerRefs), checked again:
+            # a stored file is never trusted. Never raises.
+            refs = Samagotchi::AnswerRefs.for_display(m[:display_refs] || m["display_refs"])
+            message[:display_refs] = refs unless refs.empty?
           end
           message[:parts] = did if did
           filtered << message

data/lib/samagotchi/web/public/answer_refs.js

@@ -0,0 +1,217 @@
+// The refs a plugin attached to an answer (the message's display_refs,
+// traceable refs P5b): each {match, kind, target, label?, actions} is
+// paired with the answer's bubble, then bound to what it stands for
+// (refs.js bindRef), so its actions join the ref's menu.
+//
+// A bubble knows its message's refs through setAnswerRefs (a reload's
+// render, a turn-end read's re-render); pairAnswerRefs pairs them once per
+// setAnswerRefs. Three passes over all the refs, strongest evidence
+// first, so a weak text match of one ref never takes another's link:
+//   1. a link whose href is one of the ref's action URLs;
+//   2. a link whose text is the match;
+//   3. the match as a whole token inside one plain text node (not in pre,
+//      a link, inline code or another ref), or an inline code that is the
+//      match alone.
+// A ref binds every occurrence its first finding pass finds; a ref no
+// pass finds is dropped. A label that differs from the element's text is
+// its hover title (unless the element has one: a markdown link's).
+// The match and label are a plugin's text: they only ever go through
+// textContent, setAttribute and bindRef, never markup or a RegExp.
+
+import { COPY_SOURCE_ATTR, copySource, showsAnswer } from "./copy.js";
+import { bindRef, boundRef, httpUrl, refKindOk } from "./refs.js";
+
+// bubble → {refs, paired}. A WeakMap: a dropped bubble takes its refs with
+// it; the stage hand-off moves the bubble, so they move along.
+const ANSWER_REFS = new WeakMap();
+
+// Text never paired: code blocks, links (passes 1 and 2 are theirs), a ref
+// already made, inline code (only as the match alone).
+const SKIP = "pre, a, [data-ref-kind]";
+
+// A token boundary, as the `path:line` scanner's (ref_scan.js REF): not
+// after a path-ish character, not before a word character or a slash.
+const BEFORE = /[\w./@+~-]/;
+const AFTER = /[\w/]/;
+
+// +bubble+'s refs are +refs+ (a message's display_refs: entries with a
+// match and a kind bindRef binds); a non-array or one without a usable
+// entry clears them. They pair on the next
+// pairAnswerRefs, even when the same ones were paired before.
+export function setAnswerRefs(bubble, refs) {
+  if (!bubble) return;
+  const list = (Array.isArray(refs) ? refs : []).filter(
+    (ref) => ref && typeof ref === "object" && refKindOk(ref.kind) && typeof ref.match === "string" && ref.match.trim(),
+  );
+  if (list.length) ANSWER_REFS.set(bubble, { refs: list, paired: false });
+  else ANSWER_REFS.delete(bubble);
+}
+
+// +bubble+'s refs (setAnswerRefs'), or null.
+export function answerRefsOf(bubble) {
+  return ANSWER_REFS.get(bubble)?.refs || null;
+}
+
+// The turn's final answer on its bubble (a turn-end read's +messages+):
+// the last assistant message with text, its bubble the last of +bubbles+
+// that shows it (copy.js showsAnswer, with +normalize+). Its rendered html
+// replaces the bubble's when it has one (not with web.markdown off or no
+// renderer: the text stays); its refs are the bubble's either way (a
+// later read without any clears them). The bubble, or null.
+export function applyFinalAnswer(messages, bubbles, normalize) {
+  const message = [...(Array.isArray(messages) ? messages : [])].reverse().find(
+    (item) => item?.role === "assistant" && (typeof item.html === "string" || String(item.content ?? "").trim()),
+  );
+  const bubble = message && [...bubbles].reverse().find((item) => showsAnswer(item, message, normalize));
+  if (!bubble) return null;
+  if (typeof message.html === "string") {
+    bubble.classList.add("markdown");
+    bubble.setAttribute(COPY_SOURCE_ATTR, copySource(message));
+    bubble.innerHTML = message.html;
+  }
+  setAnswerRefs(bubble, message.display_refs);
+  return bubble;
+}
+
+// Pairs +bubble+'s refs with its links and text and binds them (once per
+// setAnswerRefs; again a no-op).
+export function pairAnswerRefs(bubble) {
+  const entry = bubble && ANSWER_REFS.get(bubble);
+  if (!entry || entry.paired) return;
+  entry.paired = true;
+  let left = entry.refs;
+  left = left.filter((ref) => !pairByHref(bubble, ref));
+  left = left.filter((ref) => !pairByLinkText(bubble, ref));
+  pairByText(bubble, left);
+}
+
+// The links a ref may take: not inside a code block or another ref, not
+// bound by a plugin's ref already (a link the regex scanner adopted has
+// attributes only: it may be bound).
+function freeLinks(bubble) {
+  return [...bubble.querySelectorAll("a[href]")].filter((a) => !boundRef(a) && !a.parentElement?.closest("pre, [data-ref-kind]"));
+}
+
+// Pass 1: true when +ref+ took a link to one of its action URLs.
+function pairByHref(bubble, ref) {
+  const urls = new Set((Array.isArray(ref.actions) ? ref.actions : []).map((action) => httpUrl(action?.url)).filter(Boolean));
+  if (!urls.size) return false;
+  const links = freeLinks(bubble).filter((a) => urls.has(httpUrl(a.getAttribute("href"))));
+  return bindAll(links, ref);
+}
+
+// Pass 2: true when +ref+ took a link whose text is its match. The link
+// goes somewhere the ref doesn't name (the model's URL): the ref's actions
+// join its menu, but its label isn't the link's title.
+function pairByLinkText(bubble, ref) {
+  const match = ref.match.trim();
+  return bindAll(freeLinks(bubble).filter((a) => a.textContent.trim() === match), ref, { label: false });
+}
+
+// Pass 3, for all the +refs+ left at once: a ref the path:line scan made
+// (attributes only, no plugin data) whose text is a match is bound in
+// place (the scan ran first on a bubble that wasn't re-rendered: an answer
+// without html); an inline code that is a match alone is wrapped whole;
+// then each text node's hits (refs in list order, a hit overlapping an
+// earlier one dropped) are wrapped in one go.
+function pairByText(bubble, refs) {
+  if (!refs.length) return;
+  const doc = bubble.ownerDocument;
+  const matching = (el) => {
+    const text = el.textContent.trim();
+    return refs.find((candidate) => candidate.match.trim() === text);
+  };
+  for (const scanned of [...bubble.querySelectorAll("[data-ref-kind]:not(a)")]) {
+    if (boundRef(scanned) || scanned.parentElement?.closest("pre, a, [data-ref-kind]")) continue;
+    const ref = matching(scanned);
+    if (ref) bindAll([scanned], ref);
+  }
+  for (const code of [...bubble.querySelectorAll("code")]) {
+    if (code.closest(SKIP)) continue;
+    const ref = matching(code);
+    if (!ref) continue;
+    const span = refSpan(doc, ref);
+    if (!span) continue;
+    code.replaceWith(span);
+    span.append(code);
+    labelOn(span, ref);
+  }
+  const walker = doc.createTreeWalker(bubble, 4 /* NodeFilter.SHOW_TEXT */);
+  const nodes = [];
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const skip = node.parentElement?.closest(`${SKIP}, code`);
+    if (!skip || !bubble.contains(skip)) nodes.push(node);
+  }
+  const hits = new Map();
+  for (const ref of refs) {
+    const match = ref.match.trim();
+    for (const node of nodes) {
+      for (const [start, end] of tokenHits(node.data, match)) {
+        const list = hits.get(node) || [];
+        if (list.some(([s, e]) => start < e && end > s)) continue;
+        list.push([start, end, ref]);
+        hits.set(node, list);
+      }
+    }
+  }
+  for (const [node, list] of hits) wrap(node, list.sort((a, b) => a[0] - b[0]));
+}
+
+// [start, end] of each whole-token +match+ in +text+ (indexOf: the match
+// is a plugin's text, never a pattern).
+function tokenHits(text, match) {
+  const found = [];
+  for (let at = text.indexOf(match); at >= 0; at = text.indexOf(match, at + 1)) {
+    const end = at + match.length;
+    if (at > 0 && BEFORE.test(text[at - 1])) continue;
+    if (end < text.length && AFTER.test(text[end])) continue;
+    found.push([at, end]);
+    at = end - 1;
+  }
+  return found;
+}
+
+function wrap(node, hits) {
+  const doc = node.ownerDocument;
+  const frag = doc.createDocumentFragment();
+  let pos = 0;
+  for (const [start, end, ref] of hits) {
+    const span = refSpan(doc, ref);
+    if (!span) continue;
+    if (start > pos) frag.append(node.data.slice(pos, start));
+    span.textContent = node.data.slice(start, end);
+    labelOn(span, ref);
+    frag.append(span);
+    pos = end;
+  }
+  if (!pos) return;
+  if (pos < node.data.length) frag.append(node.data.slice(pos));
+  node.replaceWith(frag);
+}
+
+// A span bound to +ref+, or null when bindRef refuses it (a bad kind).
+function refSpan(doc, ref) {
+  const span = doc.createElement("span");
+  bindRef(span, ref);
+  return boundRef(span) ? span : null;
+}
+
+// Binds each of +els+ to +ref+; true when one took it.
+function bindAll(els, ref, { label = true } = {}) {
+  let bound = false;
+  for (const el of els) {
+    bindRef(el, ref);
+    if (!boundRef(el)) continue;
+    if (label) labelOn(el, ref);
+    bound = true;
+  }
+  return bound;
+}
+
+// The ref's label as the element's hover title, when it says more than
+// the element's text and the element has no title of its own.
+function labelOn(el, ref) {
+  const label = typeof ref.label === "string" ? ref.label.trim() : "";
+  if (!label || label === el.textContent.trim() || el.hasAttribute("title")) return;
+  el.setAttribute("title", label);
+}