samagotchi 0.108.0 → 0.110.0

data/lib/samagotchi/reply_wait/poll.rb

@@ -27,7 +27,7 @@ module Samagotchi
         @ended_before = ended_before
         @deadline = timeout && (ReplyWait.monotonic + timeout.to_f)
         @turn = turn.to_s.empty? ? nil : turn.to_s
-        @session_dir = Session.session_dir(id, state_dir: state_dir) if @turn
+        @session_dir = Session.session_dir(id, state_dir: state_dir)
         # Whether the turn's input file has been taken (latched): looked at
         # before each load, so a running session seen after it is that turn
         # or a later one, never the turn that ran when the message was sent.
@@ -40,6 +40,11 @@ module Samagotchi
         @seen_own = false
         @own_base = nil
         @seen_running = false
+        # A turn seen running with its checkpoint mark (a wait with no
+        # turn:): last_turn's ended_at then and the input files claimed
+        # then, so its settle by a next worker (#settled_running) tells
+        # from a turn that ended or an input that runs next.
+        @running_look = nil
         @gone_since = nil
       end
 
@@ -216,8 +221,13 @@ module Samagotchi
 
         if running?(session)
           @seen_running = true
+          note_running(session)
           return nil
         end
+        if (settled = settled_running(session))
+          return settled
+        end
+
         # It ran and is idle again with no new reply: canceled, failed or
         # empty. Before it was ever seen running, idle means a
         # file-delivered message its worker has not picked up yet. With a
@@ -254,6 +264,34 @@ module Samagotchi
         nil
       end
 
+      RunningLook = Data.define(:last_end, :claimed)
+
+      def note_running(session)
+        return unless session.interrupted_turn
+
+        @running_look = RunningLook.new(last_end: session.last_turn&.ended_at,
+                                        claimed: SessionInbox.claimed_input_files(@session_dir))
+      end
+
+      # The turn seen running is gone with no turn's end: its worker died
+      # in it and the next one settled it (TurnCheckpoint.settle: idle, the
+      # mark gone, last_turn left alone), which ends a wait for it (chi
+      # send --wait with no message, a message merged into it as a steer)
+      # as canceled, worker_stopped, rather than at the timeout. Not while
+      # an input waits or a new one was claimed since (the sent message,
+      # unmerged, runs as its own turn next: its end is the answer), nor
+      # for a settle never seen running (a message sent to a session a dead
+      # worker left running goes in after the settle).
+      def settled_running(session)
+        look = @running_look
+        return nil unless look && session.status == Session::STATUS_IDLE && session.interrupted_turn.nil? &&
+                          session.last_turn&.ended_at == look.last_end
+        return nil unless SessionInbox.find_new_input_files(@session_dir).empty?
+        return nil unless (SessionInbox.claimed_input_files(@session_dir) - look.claimed).empty?
+
+        Result.new(status: :no_reply, outcome: "canceled", cancel_reason: TurnCheckpoint::WORKER_STOPPED, session: session)
+      end
+
       def owner_gone(session)
         return nil unless @owner_grace
 

data/lib/samagotchi/run_options.rb

@@ -14,7 +14,7 @@ module Samagotchi
   module RunOptions
     # The flags an underscored spelling is refused for (--recap_base_url),
     # with the config registry's.
-    KNOWN = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --dir --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token].freeze
+    KNOWN = %w[--prompt --resume --attach --shared --no-shared --model --thinking --toolkit --tool --no-tool --set --parent-answers --memory --mute --append-system-prompt --dir --llm-context --llm-context-apply --llm-context-budget --no-interrupt --non-interactive --verbose --no-default-input --port --open --new-token --tunnel].freeze
 
     module_function
 
@@ -219,6 +219,9 @@ module Samagotchi
         opts.on("--port PORT", "Port for `chi web` (default: 4567, env SAMAGOTCHI_WEB_PORT)") { |p| options[:web_port] = p.to_i; cli_overrides["web.port"] = p.to_s }
         opts.on("--open", "Open browser for `chi web`") { options[:web_open] = true }
         opts.on("--new-token", "`chi web`: replace the LAN access token (web.host: lan); links and QR codes made with the old one stop working") { options[:new_token] = true }
+        opts.on("--tunnel PROVIDER", %w[tailscale],
+                "`chi web`: reach it over https from your tailnet through Tailscale Serve (never Funnel), for this run; " \
+                "turned off on exit") { |v| options[:tunnel] = v }
         opts.on("--scope VALUE", %w[project all],
                 "Which sessions `chi web` and `chi sessions list` show: project (the default: this folder's git project; " \
                 "every session outside a repo) or all") { |v| options[:scope] = v }

data/lib/samagotchi/session_access/contract.rb

@@ -150,7 +150,7 @@ module Samagotchi
                         --llm-context-budget --toolkit --tool --no-tool --set --parent-answers --no-interrupt
                         --no-default-input --dir --version -h --help],
         LOCAL_ONLY => %w[--no-shared --non-interactive -v --verbose --append-system-prompt --memory --mute --profile
-                         --port --open --new-token --scope --web-markdown --no-web-markdown]
+                         --port --open --new-token --tunnel --scope --web-markdown --no-web-markdown]
       }.freeze
       # A short run flag's name in a refusal.
       RUN_WORDS = { "-v" => "--verbose" }.freeze

data/lib/samagotchi/session_access/local.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "socket"
+
 require_relative "../session"
 require_relative "../session_access"
 require_relative "../reply_wait"
@@ -18,6 +20,8 @@ require_relative "../participants"
 require_relative "../config"
 require_relative "../web/grants"
 require_relative "../web/info_probe"
+require_relative "../web/public_url"
+require_relative "../web/link_codes"
 require_relative "../web/running"
 
 module Samagotchi
@@ -359,17 +363,25 @@ module Samagotchi
         grants.list(session_id: id).map { |grant| ParticipantView.from_h(grant.public_h(grants.now)) }
       end
 
-      # The link names this machine's chi web: its LAN address and port
-      # when one runs on the LAN (the port it recorded, else web.port),
-      # else 127.0.0.1 (+lan+ false).
+      # The link names this machine's chi web: web.public_url from this
+      # machine's config (never what the port answers) when it is set, or
+      # the one a running chi web --tunnel recorded (the code in the
+      # fragment, as chi web's own invite), else its LAN address
+      # and port when one runs on the LAN (the port it recorded, else
+      # web.port), else 127.0.0.1 (+lan+ false: the link opens on this
+      # machine only).
       # @return [Invitation]
       # @raise [ArgumentError] no such session
       # @raise [BadRequest] a bad name, kind or ttl, an archived session
       def invite(id, name:, kind:, ttl: nil, cap: nil)
         issued = Participants.invite(grants, session_id: id, name: name, kind: kind, ttl: ttl, cap: cap, state_dir: state_dir!)
-        ip, port = local_web
+        public_url = configured_public_url
+        web = public_url ? nil : local_web
+        link = if public_url then public_url.link(link_code(issued), "s=#{id}")
+               else "http://#{web.ip || "127.0.0.1"}:#{web.port}/?token=#{issued.token}#s=#{id}"
+               end
         Invitation.new(participant: ParticipantView.from_h(issued.grant.public_h(grants.now)), token: issued.token,
-                       link: "http://#{ip || "127.0.0.1"}:#{port}/?token=#{issued.token}#s=#{id}", lan: !ip.nil?,
+                       link: link, lan: !public_url.nil? || !web.ip.nil?,
                        warning: ReviewStart.share_warning(Session.load(id, **dir)))
       rescue Web::Grants::Invalid => e
         raise BadRequest.new(e.message, code: "invalid_participant")
@@ -400,18 +412,48 @@ module Samagotchi
       WEB_PORT = 4567
       LOCAL_PROBE_TIMEOUT = 1.0
 
-      # [LAN ip or nil, port] of this machine's chi web (GET /api/info):
-      # the port the running one recorded (Web::Running) when a chi web
-      # answers there, else config's web.port.
+      # Where this machine's chi web answers (GET /api/info): its LAN ip
+      # (nil without one) and the port the running one recorded
+      # (Web::Running) when a chi web answers there, else config's web.port.
+      LocalWeb = Data.define(:ip, :port)
+
+      # The LAN address a probe answered, only if it is one of this
+      # machine's: whatever listens on the port may be another user's
+      # listener naming its own (nil then: the link names 127.0.0.1).
+      def own_address(ip)
+        return nil unless ip.is_a?(String)
+
+        Socket.ip_address_list.any? { |addr| addr.ip_address == ip } ? ip : nil
+      end
+
+      # A one-time code for the grant's link (Web::LinkCodes), until it expires.
+      def link_code(issued)
+        ttl = [Time.iso8601(issued.grant.expires_at) - grants.now, 1].max
+        Web::LinkCodes.for_grants(grants.path).issue(kind: :grant, token: issued.token, ttl: ttl)
+      end
+
+      # web.public_url as this machine's config has it (nil when not a
+      # valid one: chi web refuses to start on that), else the one the
+      # running chi web recorded (chi web --tunnel's), only while that same
+      # process answers on its port (Web::Running.live_public_url).
+      def configured_public_url
+        configured = Config.get("web.public_url")
+        return Web::Running.live_public_url(path: Web::Running.path(state_dir: state_dir!)) if configured.to_s.strip.empty?
+
+        Web::PublicUrl.from_config(url: configured)
+      rescue Web::PublicUrl::Invalid
+        nil
+      end
+
       def local_web
         configured = Config.get("web.port").to_s.to_i
         configured = WEB_PORT unless configured.positive?
         recorded = Web::Running.port(path: Web::Running.path(state_dir: state_dir!))
         [recorded, configured].compact.uniq.each do |port|
           info = Web::InfoProbe.call("127.0.0.1", port, timeout: LOCAL_PROBE_TIMEOUT)
-          return [info["lan"], port] if info.is_a?(Hash)
+          return LocalWeb.new(ip: own_address(info["lan"]), port: port) if info.is_a?(Hash)
         end
-        [nil, configured]
+        LocalWeb.new(ip: nil, port: configured)
       end
 
       def dir = @state_dir ? { state_dir: @state_dir } : {}

data/lib/samagotchi/session_inbox.rb

@@ -371,10 +371,14 @@ module Samagotchi
       claimed_input?(session_dir, id) ? [:claimed, nil] : [:none, nil]
     end
 
-    # Whether a claimed input file (*.json.processing: a turn's, now or
-    # left by a crash, or a removal's before it deletes it) carries +id+.
+    # The claimed input files (*.json.processing: a turn's, now or left by
+    # a crash, or a removal's before it deletes it).
+    # @return [Array<String>] their paths
+    def self.claimed_input_files(session_dir) = Dir.glob(File.join(session_dir, INPUT_DIR, "*.json.processing"))
+
+    # Whether a claimed input file carries +id+.
     def self.claimed_input?(session_dir, id)
-      Dir.glob(File.join(session_dir, INPUT_DIR, "*.json.processing")).any? do |file|
+      claimed_input_files(session_dir).any? do |file|
         data = JSON.parse(File.read(file))
         data.is_a?(Hash) && data["enqueued_id"] == id
       rescue JSON::ParserError, SystemCallError

data/lib/samagotchi/steer.rb

@@ -2,6 +2,7 @@
 
 require_relative "client_id"
 require_relative "participant_name"
+require_relative "message_time"
 
 module Samagotchi
   # A plugin's steer: text a plugin puts into the running turn (Engine#steer),
@@ -53,15 +54,16 @@ module Samagotchi
 
       # The messages it appends: the merged input first (one message per
       # sender run, marked kind input, source: when not the user's), then
-      # each steer.
-      def messages
+      # each steer; all stamped with +at+ (MessageTime::KEY), the drain's
+      # wall time.
+      def messages(at: MessageTime.iso(MessageTime.now))
         list = inputs.map do |input|
           message = { role: "user", kind: INPUT_KIND }
           message[:source] = input[:source] if input[:source]
           message.merge!(input[:mark]) if input[:mark]
           message.merge(content: input[:content], **Steer.author_fields(input[:author], input[:author_name]))
         end
-        list + steers.map { |steer| Steer.message(**steer) }
+        (list + steers.map { |steer| Steer.message(**steer) }).map { |message| MessageTime.stamp(message, at) }
       end
 
       # The :pending_input_merged fields beside iteration and answer;

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -14,6 +14,7 @@ require_relative "line_reader"
 require_relative "question_prompt"
 require_relative "reline_seam"
 require_relative "version_lines"
+require_relative "gap_clock"
 require_relative "participant_commands"
 require_relative "local_link"
 require_relative "../bridge/turn_accumulator"
@@ -100,6 +101,7 @@ module Samagotchi
       # @param default_input [Boolean] type SAMAGOTCHI_DEFAULT_INPUT into
       #   the first read (a new session with no -p, as the REPL)
       # @param clock [#call] monotonic seconds (the Ctrl-C detach window)
+      # @param now [#call] the wall clock, a Time (the gap dividers)
       # @param delete_session [#call] session id -> deletes it (/exit --delete)
       # @param archive_session [#call] session id -> archives it (/archive);
       #   SessionManager.archive_session's result
@@ -114,7 +116,7 @@ module Samagotchi
       #   +client+ and the keywords that make a LocalLink
       def initialize(screen:, client_id:, client: nil, first_prompt: nil, first_command: nil, no_interrupt: false,
                      default_input: false, wait_at_eof: false, as_parent: false,
-                     clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) },
+                     clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }, now: -> { MessageTime.now },
                      delete_session: ->(id) { SessionManager.delete_session(id, stop: true, wait: LocalLink::DELETE_WAIT) },
                      archive_session: ->(id) { SessionManager.archive_session(id, wait: LocalLink::DELETE_WAIT) },
                      installed_version: -> { InstalledVersions.new.newest },
@@ -152,6 +154,8 @@ module Samagotchi
         @no_interrupt = no_interrupt
         @no_default_input = !default_input
         @clock = clock
+        # The session's last activity, for the gap dividers (GapClock).
+        @gaps = GapClock.new(now: now)
         @last_idle_interrupt_at = nil
         @next_input_prefill = nil
         # Prompts this run sent, by enqueued_id: only those come back into
@@ -208,7 +212,12 @@ module Samagotchi
         end
         read = input || method(:read_input_line)
         # A command typed after /unqueue's text echoes as the command alone.
-        echoed_read = ->(prompt, prefill) { RelineSeam.echo_as(method(:prefilled_echo)) { read.call(prompt, prefill) } }
+        # A typed prompt after a quiet gap has its divider above its echo.
+        echoed_read = lambda do |prompt, prefill|
+          RelineSeam.echo_as(method(:prefilled_echo)) do
+            RelineSeam.echo_above(method(:gap_above_echo)) { read.call(prompt, prefill) }
+          end
+        end
         @reader = LineReader.new(queue, prompt: method(:prompt_text), read: echoed_read, prefill: default_input_text).start
         loop do
           kind, payload = next_item(queue)
@@ -280,10 +289,12 @@ module Samagotchi
         when :turn_dequeued then turn_dequeued(event)
         when :turn_started
           @status.take_event(event)
+          mark_activity
           start_turn(event)
         when :turn_completed
           @status.take_event(event)
           complete_turn(event)
+          @gaps.touch
           refresh_children
           own_turn_ended(event)
         # The renderer says how it ended (the REPL's words too).
@@ -291,6 +302,7 @@ module Samagotchi
           @status.take_event(event)
           @renderer.call(event)
           end_turn
+          @gaps.touch
           refresh_children
           own_turn_ended(event)
         when :prompt_restored then restore_prompt(event)
@@ -307,10 +319,14 @@ module Samagotchi
         when :command_ran
           command_ran(event)
           return first_command_ran(event) if @first_command_id && event[:command_id] == @first_command_id
-        when :reminder_injected then @screen.commit(reminder_line(event[:reminders]))
+        when :reminder_injected
+          mark_activity
+          @screen.commit(reminder_line(event[:reminders]))
         # A context note joined the conversation (between turns). One dim
         # line in the scrollback; the notes slot is for question choices.
-        when :context_added then @screen.commit(context_note_line(event[:label], event[:text]))
+        when :context_added
+          mark_activity
+          @screen.commit(context_note_line(event[:label], event[:text]))
         when :continue_offered then offer_continue(event)
         when :continue_resolved then continue_resolved(event)
         # The note comes with the kernel's :pending_input_merged (EventRenderer),
@@ -331,7 +347,7 @@ module Samagotchi
         when :question_relay then question_relayed(event)
         # Written while the session sat idle: shown at the open prompt. One
         # collected just as a turn started describes the chat before it.
-        when :recap_ready then @screen.commit(recap_block(event[:recap])) unless @running || event[:recap].to_s.strip.empty?
+        when :recap_ready then show_recap_ready(event) unless @running || event[:recap].to_s.strip.empty?
         when :guardrail_warning then @screen.commit(EventRenderer.load_warning_line(event))
         # A plugin's slow setup: the activity row turns while it runs; a
         # line when it is done (a failure is a warn card).
@@ -359,6 +375,32 @@ module Samagotchi
 
       private
 
+      # A recap written while idle, with the time it was written.
+      def show_recap_ready(event)
+        mark_activity
+        @screen.commit(recap_block(event[:recap], at: event[:created_at]))
+      end
+
+      # Activity starts now: a gap's divider first when one passed since the
+      # last (none while a turn runs: its steps are no gap).
+      def mark_activity
+        line = @gaps.divider(quiet: @running)
+        @screen.commit(gap_divider(line)) if line
+      end
+
+      # The divider above a typed line's echo (RelineSeam.echo_above, on the
+      # reader thread): a prompt typed after a quiet gap, at an idle prompt.
+      # It marks the activity, so the turn's start marks no second one.
+      def gap_above_echo(text)
+        return nil if @running
+
+        route = ComposerRoute.call(text.to_s.strip, running: false, registry: command_registry)
+        return nil unless %i[prompt deliver].include?(route.kind)
+
+        line = @gaps.divider
+        line && gap_divider(line)
+      end
+
       # The newest chi installed, looked at once, at the join.
       def installed_version
         @link.installed_version
@@ -936,6 +978,9 @@ module Samagotchi
         return own_prompt_failed if images.nil?
 
         running = @running
+        # Off a live region (no echo seam) the divider comes here; after
+        # #gap_above_echo it marks none.
+        mark_activity
         options = { prompt: text, client_id: client_id_for(text) }
         options[:no_interrupt] = true if @no_interrupt
         options[:images] = images unless images.empty?
@@ -1315,8 +1360,9 @@ module Samagotchi
           @attached = true
           # The recap first: what the session was about, then where it stopped.
           saved = snapshot[:saved_recap]
-          @screen.commit(recap_block(saved[:text], turns_since: saved[:turns_since])) if saved && !saved[:text].to_s.strip.empty?
+          @screen.commit(recap_block(saved[:text], turns_since: saved[:turns_since], at: saved[:created_at])) if saved && !saved[:text].to_s.strip.empty?
           render_join_header(Array(snapshot[:messages]))
+          render_join_gap(snapshot, saved)
           @screen.commit("guardrails> #{snapshot[:guardrail_warning]}") if snapshot[:guardrail_warning]
           @screen.commit("plugins> #{snapshot[:plugin_warning]}") if snapshot[:plugin_warning]
           version_line = VersionLines.at_attach(worker: snapshot[:chi_version], installed: installed_version,
@@ -1431,6 +1477,17 @@ module Samagotchi
         end
       end
 
+      # Where the session's last activity was: its newest stamped entry,
+      # else its saved recap's time. A gap ago (and no turn running): one
+      # line after the join block says when.
+      def render_join_gap(snapshot, saved)
+        @gaps.seed(snapshot[:messages], fallback: saved&.dig(:created_at))
+        return if snapshot[:current_turn]
+
+        line = @gaps.join_line
+        @screen.commit(gap_divider(line)) if line
+      end
+
       def render_join_header(messages)
         exchange = messages.select { |m| %w[user model assistant].include?(m[:role].to_s) }
         # The id stays findable: the detach line and chi sessions list show it.
@@ -1537,17 +1594,19 @@ module Samagotchi
       # A saved call's row; "no result" for a call the turn never answered
       # (it ended first). Its status is the saved record's, as live and the
       # web's reload (a guardrail's "blocked" is no error), else read from
-      # its result.
+      # its result (a guardrail's deny text reads blocked too).
       def join_tool_line(part, duration_ms: nil, saved_status: nil)
         output = part[:output]
         command = part.dig(:view, :truncated) ? nil : part.dig(:view, :command)
+        text = ToolActivity.saved_result_text(output) unless output.nil?
         status = if output.nil?
                    "no result"
                  elsif !saved_status.to_s.empty?
                    saved_status.to_s
+                 elsif ToolActivity.guardrail_denied?(text)
+                   "blocked"
                  else
-                   ToolActivity.tool_activity_status(ToolActivity.saved_result_text(output), part[:tool],
-                                                     command: command)
+                   ToolActivity.tool_activity_status(text, part[:tool], command: command)
                  end
         activity = { action: part[:label] || ToolActivity.tool_activity_action(part[:tool]), tool: part[:tool],
                      params: part[:params], status: status,
@@ -1658,6 +1717,8 @@ module Samagotchi
       def show_enqueued(event)
         return if own?(event[:client_id])
 
+        # Another client's prompt shows here, before its turn starts.
+        mark_activity
         @shown_enqueued << event[:enqueued_id]
         line = prompt_line(event[:client_id], event[:prompt], **author_of(event[:author]))
         @screen.commit(event[:delivery] == Delivery::QUEUE ? "#{line} #{QUEUED_NOTE}" : line)

data/lib/samagotchi/terminal_ui/between_turns.rb

@@ -26,7 +26,9 @@ module Samagotchi
       # @param renderer [EventRenderer] draws cards
       # @param turn_running [#call] whether a turn runs now
       # @param quiet [Boolean] a --non-interactive run: no init lines
-      def initialize(surface:, view:, renderer:, turn_running:, quiet: false)
+      # @param gaps [GapClock, nil] the session's last activity: a recap
+      #   after a quiet gap has its divider
+      def initialize(surface:, view:, renderer:, turn_running:, quiet: false, gaps: nil)
         @surface = surface
         @view = view
         @renderer = renderer
@@ -34,6 +36,7 @@ module Samagotchi
         @quiet = quiet
         @cards = Queue.new
         @recap = nil
+        @gaps = gaps
       end
 
       attr_writer :surface
@@ -84,7 +87,7 @@ module Samagotchi
         return unless event[:type] == :recap_ready
         return if event[:recap].to_s.strip.empty? || turn_running?
 
-        @recap = event[:recap].to_s
+        @recap = { text: event[:recap].to_s, at: event[:created_at] }
       end
 
       # Print a recap written while idle (main thread, at the open prompt).
@@ -93,7 +96,9 @@ module Samagotchi
         return unless recap
 
         @recap = nil
-        @surface.commit(recap_block(recap))
+        line = @gaps&.divider
+        @surface.commit(gap_divider(line)) if line
+        @surface.commit(recap_block(recap[:text], at: recap[:at]))
       end
 
       # Print the cards, notices and anytime commands' output kept since the

data/lib/samagotchi/terminal_ui/formatting.rb

@@ -11,6 +11,7 @@ require_relative "../memory_bundle/index_size"
 require_relative "../prompt_note"
 require_relative "../prompt_files"
 require_relative "../session_config"
+require_relative "../message_time"
 require_relative "../tools/task_record"
 require_relative "model_segments_text"
 
@@ -513,19 +514,26 @@ module Samagotchi
 
       private
 
-      # The recap shown on return: dim, one "recap>" block, noting how many
-      # turns came since it was written.
-      def recap_block(text, turns_since: 0)
+      # The recap shown on return: dim, one "recap>" block, with the local
+      # time it was written ("recap 14:32>") when known, noting how many
+      # turns came since.
+      # @param at [String, nil] its created_at (an ISO time, any offset)
+      def recap_block(text, turns_since: 0, at: nil)
         n = turns_since.to_i
         note = if n == 1 then " (before the last turn)"
                elsif n > 1 then " (before the last #{n} turns)"
                else ""
                end
+        clock = MessageTime.clock(at)
+        head = clock ? "recap #{clock}#{note}>" : "recap#{note}>"
         text.to_s.strip.lines.map(&:chomp).each_with_index.map do |line, i|
-          paint(i.zero? ? "recap#{note}> #{line}" : line, 90)
+          paint(i.zero? ? "#{head} #{line}" : line, 90)
         end.join("\n")
       end
 
+      # A quiet gap's divider (MessageTime.gap_line, GapClock#join_line): dim.
+      def gap_divider(text) = paint(text, 2)
+
       RECAP_OFF_TEXT = "recap is off (recap: false in config.yml, or SAMAGOTCHI_RECAP_ENABLED=false; /recap on turns it on here)"
       # Off by the session's own recap.enabled (/recap off, --set recap.enabled=false).
       RECAP_SESSION_OFF_TEXT = "recap is off for this session (/recap on turns it on, /recap default goes back to config.yml)"
@@ -540,7 +548,7 @@ module Samagotchi
 
         saved = saved&.transform_keys(&:to_sym)
         lines = []
-        lines << recap_block(saved[:text], turns_since: saved[:turns_since]) if saved
+        lines << recap_block(saved[:text], turns_since: saved[:turns_since], at: saved[:created_at]) if saved
         lines << case request&.to_sym
                  when :started, :in_flight then "writing a recap…"
                  when :nothing_new then saved ? "(nothing new since this recap)" : "no recap yet: nothing to recap"

data/lib/samagotchi/terminal_ui/gap_clock.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../message_time"
+
+module Samagotchi
+  class TerminalUI
+    # When the session's last activity was, for both TUIs' gap dividers: a
+    # dim "── 14:32 · 47 min later ──" before what comes after a quiet
+    # MessageTime::GAP_SECONDS. Activity is a prompt (typed or another
+    # client's), a reminder, a context note, a recap, and a turn's end; a
+    # gap is measured from the end of one to the start of the next, so a
+    # long turn followed at once by another marks nothing.
+    #
+    # The times are this terminal's wall clock when it saw them (+now+),
+    # seeded at the join from the session's stamped history. Read from the
+    # reader thread too (a typed prompt's divider goes above its echo), so
+    # every read-and-mark is under one lock.
+    class GapClock
+      # @param now [#call] the wall clock (a Time); MessageTime.now, which
+      #   the specs pin, by default
+      def initialize(now: -> { MessageTime.now })
+        @now = now
+        @last = nil
+        @lock = Mutex.new
+      end
+
+      # @return [String] now, as a stamp
+      def now_iso = MessageTime.iso(@now.call)
+
+      # Mark activity starting now.
+      # @param quiet [Boolean] mark only, no divider (a turn runs: its own
+      #   steps are no gap)
+      # @return [String, nil] the divider's text when a gap passed since
+      #   the last activity
+      def divider(quiet: false)
+        @lock.synchronize do
+          now = now_iso
+          line = quiet ? nil : MessageTime.gap_line(@last, now)
+          @last = now
+          line
+        end
+      end
+
+      # Mark activity (a turn's end) without a divider.
+      def touch = divider(quiet: true)
+
+      # Start from the session's last activity (the join, a resume): the
+      # newest stamp in +messages+ (Symbol- or String-keyed), else
+      # +fallback+ (a saved recap's created_at). Nothing known: nothing set.
+      # @return [String, nil] the time it started from
+      def seed(messages, fallback: nil)
+        iso = Array(messages).reverse_each.lazy.filter_map { |m| MessageTime.of(m) }.first || fallback
+        iso = MessageTime.iso_of(iso)
+        @lock.synchronize { @last = iso } if iso
+        iso
+      end
+
+      # The join's line when the last activity is a gap ago:
+      # "── last activity 14:32 · 47 min ago ──" (the date when the local
+      # day changed). Printed, it stands for the gap: the clock moves to now,
+      # so the next prompt marks none.
+      # @return [String, nil]
+      def join_line
+        @lock.synchronize do
+          now = now_iso
+          next nil unless MessageTime.gap_line(@last, now)
+
+          last = Time.iso8601(@last).localtime
+          same_day = last.to_date == Time.iso8601(now).localtime.to_date
+          time = same_day ? MessageTime.clock(@last) : MessageTime.day_clock(@last)
+          line = "── last activity #{time} · #{MessageTime.ago(Time.iso8601(now) - last)} ago ──"
+          @last = now
+          line
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/reline_seam.rb

@@ -77,6 +77,20 @@ module Samagotchi
           Thread.current[:samagotchi_reline_echo] = was
         end
 
+        # Run a read (on this thread) whose submitted line may echo with a
+        # line above it: +above+ is called with the echoed text at Enter, a
+        # String goes above the echo (a gap's divider before a typed
+        # prompt), nil adds nothing. Only a read drawn on a screen; a read
+        # without echo calls nothing.
+        # @param above [#call] (text) -> String or nil
+        def echo_above(above)
+          was = Thread.current[:samagotchi_reline_echo_above]
+          Thread.current[:samagotchi_reline_echo_above] = above
+          yield
+        ensure
+          Thread.current[:samagotchi_reline_echo_above] = was
+        end
+
         # @api private
         attr_writer :reading
 
@@ -228,9 +242,13 @@ module Samagotchi
       def clear_screen(key) = ed_clear_screen(key)
 
       # The typed lines, or the echo's text after the prompt (#echo_as).
+      # A line above them when the read has one (#echo_above).
       def seam_echo_lines
-        text = Thread.current[:samagotchi_reline_echo]&.call(@buffer_of_lines.join("\n"))
-        text ? [Reline::Unicode.strip_non_printing_start_end(prompt_list[0]) + text] : seam_final_lines
+        typed = @buffer_of_lines.join("\n")
+        text = Thread.current[:samagotchi_reline_echo]&.call(typed)
+        lines = text ? [Reline::Unicode.strip_non_printing_start_end(prompt_list[0]) + text] : seam_final_lines
+        above = Thread.current[:samagotchi_reline_echo_above]&.call(text || typed)
+        above ? [above, *lines] : lines
       end
 
       # The prompt and the text as render_finished writes them: one line per