proctolog 0.1.1 → 0.2.0

data/app/models/proctolog/rounds.rb

@@ -46,6 +46,18 @@ module Proctolog
       def newness = [order, Rounds.moment(response[:createdAt])]
     end
 
+    # What came back from an agent on one pull request besides its notes,
+    # which say so themselves once addressed (move_notes): the answers the
+    # owner is to confirm and the questions they are to answer.
+    Returned = Data.define(:to_confirm, :questions) do
+      def initialize(to_confirm: 0, questions: 0) = super
+    end
+
+    # Where a note an agent answered stands in its marks, by where its
+    # request stands: addressed while the answer waits on the owner,
+    # confirmed once they confirmed it, open again once they replied.
+    NOTE_STATES = {owner: "addressed", question: "addressed", closed: "confirmed", agent: "open", out: "open"}.freeze
+
     # A time as a page or an agent wrote it; one that cannot be read is
     # taken for the oldest.
     def self.moment(text)
@@ -93,6 +105,31 @@ module Proctolog
       end
     end
 
+    # What came back to the owner, by pull request.
+    def returned
+      everything.reject { it.dig(:source, :noteId) }.group_by { it[:pr] }.transform_values do |requests|
+        states = requests.group_by { state_of(it) }.tap { it.default = [] }
+        Returned.new(to_confirm: states[:owner].size, questions: states[:question].size)
+      end
+    end
+
+    # Moves each note an agent answered in a handover to where its answer
+    # stands (NOTE_STATES), with the answer as its reply, so the marks say
+    # what Returned work says: to the pages, and to an agent reading them.
+    # A note the owner withdrew stays withdrawn.
+    def move_notes
+      everything.each do |item|
+        id = item.dig(:source, :noteId) or next
+        latest = latest(item) or next
+        to = NOTE_STATES[state_of(item)] or next
+        marks = @burst.marks(item[:pr] || "sitting")
+        note = marks.note(id)
+        next if note.nil? || note.withdrawn? || [note.state, note.reply&.dig("response")] == [to, latest.key]
+
+        marks.move(id, to:, reply: {"text" => latest.result[:summary], "commit" => latest.result[:head]&.first(8), "response" => latest.key}.compact)
+      end
+    end
+
     # What an agent took and has not answered, with the handover it went in.
     def with_agent
       current.select { in_focus?(it[:pr]) && state_of(it) == :out }.map do |item|

data/app/models/proctolog/share/ngrok.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "yaml"
+
+module Proctolog
+  class Share
+    # ngrok: the desk on the internet, at the address ngrok gives the account
+    # (on the free plan, one that stays the same), behind ngrok's sign-in with
+    # Google, which lets in only the addresses the owner allows: their Git
+    # email unless they named others. ngrok runs in the background on its own
+    # until the share is closed, the desk running or not, and keeps its log
+    # beside the share's file. It opens no inspector on this Mac, which would
+    # take 4040 or the port after it, a desk's.
+    class Ngrok
+      DOWNLOAD = "https://ngrok.com/download"
+      AUTHTOKEN = "https://dashboard.ngrok.com/get-started/your-authtoken"
+      WAIT = 20
+
+      def initialize(path: ENV.fetch("PATH", ""))
+        @program = path.split(File::PATH_SEPARATOR).map { File.join(it, "ngrok") }.find { File.executable?(it) }
+      end
+
+      def name = "ngrok"
+
+      def to_param = "ngrok"
+
+      def who = "only #{allowed.to_sentence(two_words_connector: " or ", last_word_connector: ", or ")}, signed in with Google, gets in"
+
+      def allowed = Settings.current.allowed
+
+      # What to do before it can share the desk; nil when nothing.
+      def unready
+        if !@program then "ngrok is not installed: brew install ngrok, or #{DOWNLOAD}"
+        elsif !authtoken? then "ngrok has no authtoken: copy yours from #{AUTHTOKEN}, then run ngrok config add-authtoken TOKEN"
+        elsif allowed.empty? then "ngrok would let nobody in: name yourself with proctolog share --via ngrok --allow EMAIL"
+        end
+      end
+
+      def ready? = unready.nil?
+
+      def open(port)
+        Share.folder.mkpath
+        log = Share.folder.join("#{port}.ngrok.log").tap { it.delete if it.exist? }
+        process = Process.spawn(Outside.environment, @program, "http", "http://localhost:#{port}", "--config", [config, quiet].join(","),
+          "--oauth", "google", *allowed.flat_map { ["--oauth-allow-email", it] }, "--log", log.to_s, "--log-format", "json",
+          in: File::NULL, out: File::NULL, err: File::NULL, pgroup: true)
+        Process.detach(process)
+        Share.new(port:, way: self, address: started(log, process), process:)
+      end
+
+      def close(share) = (stop(share.process) if carrying?(share))
+
+      # Its process is still this share's ngrok, not another program given
+      # the same number since.
+      def carrying?(share)
+        share.process.present? && Open3.capture3("ps", "-o", "command=", "-p", share.process.to_s).first.include?("ngrok http http://localhost:#{share.port} ")
+      end
+
+      private
+
+      # What ngrok logged until its address, or its reason for giving none.
+      def started(log, process)
+        deadline = WAIT.seconds.from_now
+        while Time.current < deadline
+          lines = log.exist? ? log.each_line.filter_map { logged(it) } : []
+          if (tunnel = lines.find { it["msg"] == "started tunnel" }) then return tunnel.fetch("url")
+          elsif (failure = lines.find { it["lvl"] == "crit" }) then raise Refused, said(failure.fetch("err", ""))
+          elsif !alive?(process) then raise Refused, "ngrok stopped before it gave the desk an address: #{log}."
+          end
+          sleep 0.1
+        end
+        stop(process)
+        raise Refused, "ngrok gave the desk no address within #{WAIT} seconds: #{log}."
+      end
+
+      # A line of ngrok's log; nil for one it had not finished writing.
+      def logged(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # ngrok's first sentence, and its error's code, which its docs explain.
+      def said(error) = "ngrok said: #{error.lines.first.to_s.strip.chomp(".")}#{" (#{error[/ERR_NGROK_\d+/]})" if error[/ERR_NGROK_\d+/]}."
+
+      def alive?(process)
+        Process.kill(0, process)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+
+      # The whole group: ngrok, and whatever it started.
+      def stop(process)
+        Process.kill("TERM", -process)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      def authtoken? = ENV["NGROK_AUTHTOKEN"].present? || own_settings.then { it["authtoken"] || it.dig("agent", "authtoken") }.present?
+
+      # ngrok's own configuration, where `ngrok config add-authtoken` wrote.
+      def config
+        @config ||= Open3.capture2e(Outside.environment, @program, "config", "check").first[/configuration file at (.+\.yml)/, 1] ||
+          File.expand_path("~/Library/Application Support/ngrok/ngrok.yml")
+      end
+
+      def own_settings = File.file?(config) ? (YAML.safe_load_file(config) || {}) : {}
+
+      # Read over ngrok's own, in the same version: no inspector.
+      def quiet
+        Share.folder.join("ngrok.yml").tap do |file|
+          file.write((own_settings["version"].to_s == "3") ? {"version" => 3, "agent" => {"web_addr" => false}}.to_yaml : {"version" => "2", "web_addr" => false}.to_yaml)
+        end.to_s
+      end
+    end
+  end
+end

data/app/models/proctolog/share/settings.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Proctolog
+  class Share
+    # What the owner chose about sharing, for every checkout on this Mac: the
+    # way they last named, and the addresses ngrok lets in. Kept in share.yml
+    # beside the desk's secret.
+    class Settings < Data.define(:via, :allow)
+      def self.file = Desk.data.join("share.yml")
+
+      def self.current = new(**(file.file? ? (YAML.safe_load_file(file) || {}) : {}).symbolize_keys.slice(:via, :allow))
+
+      def initialize(via: nil, allow: []) = super(via:, allow: Array(allow).map { it.to_s.strip.downcase }.compact_blank.uniq)
+
+      def save = self.class.file.tap { it.dirname.mkpath }.write({"via" => via, "allow" => allow}.compact_blank.to_yaml)
+
+      # Those named, or the owner as Git knows them, as Google spells an address.
+      def allowed = allow.presence || [Owner.git_email.downcase].compact_blank
+    end
+  end
+end

data/app/models/proctolog/share/tailscale.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "uri"
+
+module Proctolog
+  class Share
+    # Tailscale's serve: the desk at this Mac's own name on the owner's
+    # tailnet, https://mac.tailnet.ts.net, which only the devices signed in to
+    # that tailnet reach. Nothing goes on the internet, and Tailscale is the
+    # sign-in. Tailscale keeps serving it, the desk running or not, until the
+    # share is closed.
+    class Tailscale
+      DOWNLOAD = "https://tailscale.com/download/mac"
+      CERTIFICATES = "https://login.tailscale.com/admin/dns"
+      # The app's own program, for a Mac that never put tailscale on its PATH.
+      APP = "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+      # The first share of a tailnet can wait on its owner turning Serve on, in a browser.
+      WAIT = 20
+
+      def initialize(path: ENV.fetch("PATH", ""), app: APP)
+        @program = path.split(File::PATH_SEPARATOR).map { File.join(it, "tailscale") }.find { File.executable?(it) } ||
+          (app if File.executable?(app))
+      end
+
+      def name = "Tailscale"
+
+      def to_param = "tailscale"
+
+      # By the tailnet's name: one account can be in several, and a phone
+      # signed in to another one never sees this Mac.
+      def who = "only devices signed in to your tailnet#{", #{tailnet}," if tailnet} reach it"
+
+      def tailnet = status.dig("CurrentTailnet", "Name")
+
+      # What to do before it can share the desk; nil when nothing.
+      def unready
+        return "Tailscale is not installed: #{DOWNLOAD}" unless @program
+
+        case status["BackendState"]
+        when "Running" then ("Tailscale gives your tailnet no HTTPS certificates: turn them on at #{CERTIFICATES}" if status["CertDomains"].blank?)
+        when "NeedsLogin", "NeedsMachineAuth" then "Tailscale is signed out: sign in from its icon in the menu bar"
+        else "Tailscale is off: turn it on from its icon in the menu bar"
+        end
+      end
+
+      def ready? = unready.nil?
+
+      # On 443, the tailnet name itself, unless Tailscale serves something
+      # else there; then on the desk's own port.
+      def open(port)
+        https = served.fetch("TCP", {}).key?("443") ? port : 443
+        run("serve", "--bg", "--yes", "--https=#{https}", "http://localhost:#{port}")
+        Share.new(port:, way: self, address: "https://#{status.dig("Self", "DNSName").to_s.chomp(".")}#{":#{https}" unless https == 443}")
+      end
+
+      def close(share) = run("serve", "--https=#{URI(share.address).port}", "off")
+
+      def carrying?(share)
+        address = URI(share.address)
+        served.dig("Web", "#{address.host}:#{address.port}", "Handlers", "/", "Proxy") == "http://localhost:#{share.port}"
+      end
+
+      private
+
+      def status = @status ||= asked("status", "--json")
+
+      def served = asked("serve", "status", "--json")
+
+      # Tailscale's answer as JSON; empty when it gave none, as a stopped one does.
+      def asked(*arguments)
+        output, = Open3.capture3(Outside.environment, @program, *arguments)
+        JSON.parse(output)
+      rescue JSON::ParserError, SystemCallError
+        {}
+      end
+
+      def run(*arguments)
+        Open3.popen3(Outside.environment, @program, *arguments) do |input, output, errors, waiter|
+          input.close
+          said = [output, errors].map { |stream| Thread.new { stream.read } }
+          finished = waiter.join(WAIT)
+          Process.kill("TERM", waiter.pid) unless finished
+          words = said.map(&:value).join
+          raise Refused, refusal(words) unless finished&.value&.success?
+
+          words
+        end
+      end
+
+      # Serve asks a tailnet's owner once to turn it on, at an address it
+      # prints, and waits.
+      def refusal(words)
+        if (address = words[%r{https://login\.tailscale\.com/\S+}])
+          "Tailscale waits for Serve to be turned on for your tailnet: #{address}, then share again."
+        else
+          "Tailscale said: #{words.lines.grep_v(/\AWarning:|TPM/).join(" ").squish.chomp(".").presence || "nothing, and served nothing"}."
+        end
+      end
+    end
+  end
+end

data/app/models/proctolog/share.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "uri"
+require "yaml"
+
+module Proctolog
+  # The desk reached from away from this Mac, by its owner alone: from their
+  # phone, or a computer elsewhere, through whichever of Tailscale or ngrok
+  # this Mac has. Tailscale lets in the devices of the owner's own tailnet
+  # and puts nothing on the internet; ngrok puts the desk there behind its
+  # sign-in with Google, for the addresses the owner allows.
+  #
+  # A share is of the desk on one port, kept as a file in the cache by that
+  # port. It stays open until it is closed, across the desk's restarts, and
+  # while its file says so the desk answers to the share's name as to its own.
+  # `who` is whom it lets in, as it was opened.
+  class Share < Data.define(:port, :way, :address, :who, :process)
+    Refused = Class.new(StandardError)
+
+    def initialize(port:, way:, address:, who: way.who, process: nil) = super
+
+    class << self
+      # The ways this Mac could share the desk, Tailscale first: it puts
+      # nothing on the internet.
+      def ways(path: ENV.fetch("PATH", "")) = [Tailscale.new(path:), Ngrok.new(path:)]
+
+      # The share of the desk on port, while its way still carries it. One
+      # whose way let it go (ngrok ended with the Mac's restart, say) is
+      # forgotten.
+      def at(port, ways: self.ways)
+        kept(port, ways:)&.then do |share|
+          next share if share.way.carrying?(share)
+
+          file(port).delete
+          nil
+        end
+      end
+
+      # As its file says, without asking its way: for every page of a burst,
+      # which says whether the desk is shared.
+      def kept(port, ways: self.ways)
+        record = recorded(port) or return
+        way = ways.find { it.to_param == record["way"] } or return
+
+        new(port:, way:, address: record["address"], who: record.fetch("who") { way.who }, process: record["process"])
+      end
+
+      # Shares the desk on port through the way named, which is remembered,
+      # or the one last named while it is ready, or the first one ready.
+      # `allow` names whom ngrok lets in from now on. A share already open is
+      # only answered. A trial desk, on marks of its own, is never shared: it
+      # tries a change on this Mac, and its settings are the owner's.
+      def open(port, via: nil, allow: nil, ways: self.ways)
+        raise Refused, "A trial desk is not shared: it is for trying a change on this Mac." if Desk.trial?
+
+        Settings.current.with(allow:).save if allow
+        at(port, ways:) || chosen(via, ways).open(port).tap do
+          it.keep
+          Settings.current.with(via:).save if via
+        end
+      end
+
+      # Whether a request came through the desk's share: by the name it was
+      # asked for. Read from the file alone, as every request from away asks.
+      def carries?(request, port: Desk.port) = recorded(port)&.then { URI(it["address"]).host.casecmp?(request.host) } || false
+
+      def folder = Desk.cache.join("shares")
+
+      def file(port) = folder.join("#{port}.yml")
+
+      private
+
+      def recorded(port) = file(port).then { YAML.safe_load_file(it) if it.file? }
+
+      def chosen(via, ways)
+        if via
+          way = ways.find { it.to_param == via } or raise Refused, "The desk is shared through #{ways.map(&:to_param).to_sentence(last_word_connector: " or ", two_words_connector: " or ")}, not #{via}."
+          way.ready? ? way : raise(Refused, "#{way.unready}.")
+        else
+          remembered = Settings.current.via
+          ways.find { it.to_param == remembered && it.ready? } || ways.find(&:ready?) || raise(Refused, unshareable(ways))
+        end
+      end
+
+      def unshareable(ways) = "Neither #{ways.map(&:name).join(" nor ")} can share the desk yet. #{ways.map { "#{it.unready}." }.join(" ")}"
+    end
+
+    def keep = file.tap { it.dirname.mkpath }.write({"way" => way.to_param, "address" => address, "who" => who, "process" => process}.compact.to_yaml)
+
+    def close
+      way.close(self)
+      file.delete if file.exist?
+    end
+
+    def host = URI(address).host
+
+    def file = self.class.file(port)
+
+    def to_s = "The desk is shared at #{address} through #{way.name}: #{who}."
+  end
+end

data/app/models/proctolog/standing.rb

@@ -19,24 +19,43 @@ module Proctolog
     # under it. `scenarios` are the names of this pull request's scenarios, and
     # `named` the preconditions the burst file names for it. `progress` is how
     # far the owner's choices on its decisions are; without one, only the boxes
-    # ticked on GitHub count as reviewed.
-    def initialize(stop:, marks:, progress: nil, under: nil, above: [], scenarios: [], named: [])
-      @stop, @marks, @under, @above, @scenarios, @named = stop, marks, under, above, scenarios, named
+    # ticked on GitHub count as reviewed. `returned` is what came back from an
+    # agent on it.
+    def initialize(stop:, marks:, progress: nil, returned: Rounds::Returned.new, under: nil, above: [], scenarios: [], named: [])
+      @stop, @marks, @returned, @under, @above, @scenarios, @named = stop, marks, returned, under, above, scenarios, named
       @progress = progress || Choices::Progress.of(decisions.index_with(&:ticked))
     end
 
     # Whose move it is: :waiting on something outside, the :agent's, the
-    # :owner's, or nobody's because it is :settled.
+    # :owner's, or nobody's because it is :settled. What came back from the
+    # agent makes it the owner's, whatever else is still with the agent.
     def turn
       if marks.waiting_on then :waiting
+      elsif back_to_owner? then :owner
       elsif for_the_agent.any? then :agent
-      elsif good_to_go? && !changed? && for_the_owner.empty? then :settled
+      elsif good_to_go? && !changed? then :settled
       else :owner
       end
     end
 
     def settled? = turn == :settled
 
+    # What came back from the agent for the owner, in a few words each: the
+    # notes it addressed, its answers to confirm and its questions.
+    def for_the_owner
+      addressed = notes(:addressed).size
+      [*("#{count(addressed, "note")} addressed, to confirm" if addressed.positive?),
+        *("#{@returned.to_confirm} returned, to confirm" if @returned.to_confirm.positive?),
+        *("#{count(@returned.questions, "question")} for you" if @returned.questions.positive?)]
+    end
+
+    def back_to_owner? = for_the_owner.any?
+
+    # Whether it waits for the owner: a blocking decision left, or something
+    # back from the agent. The non-blocking wait for one gesture, and hold
+    # nothing up.
+    def asks_for_owner? = back_to_owner? || progress.blocking_left.positive?
+
     def good_to_go? = marks.good_to_go.present?
 
     # What moved since "good to go" was given: the code, the description, both
@@ -91,8 +110,6 @@ module Proctolog
         *("#{count(stop.open_threads, "review thread")} unresolved" if stop.open_threads.positive?)]
     end
 
-    def for_the_owner = notes(:addressed).any? ? ["#{count(notes(:addressed).size, "note")} addressed, to confirm"] : []
-
     def notes(state) = marks.notes.select { it.state == state.to_s }
 
     def count(number, noun) = "#{number} #{noun.pluralize(number)}"

data/app/views/proctolog/bursts/_line.html.erb

@@ -1,6 +1,6 @@
 <%# locals: (burst:, stop:, standing:) %>
-<%# One pull request of the route, in a line: its number, its title, and at the right whose it is when it is not the owner's, and how far its decisions are. The line the cursor is on opens out: its title in full, what else there is to know of it, and its keys beside it. %>
-<%= tag.li id: "pr-#{stop.number}", data: {stop: "", blocking_left: standing.progress.blocking_left, turn: standing.turn} do %>
+<%# One pull request of the route, in a line: its number, its title, and at the right whether something came back from the agent, or else whose it is when it is not the owner's, and its decisions as beads. The line the cursor is on opens out: its title in full, what else there is to know of it, and its keys beside it. %>
+<%= tag.li id: "pr-#{stop.number}", data: {stop: "", asks: standing.asks_for_owner?, turn: standing.turn} do %>
   <p class="what">
     <%= link_to "##{stop.number}", burst_pull_request_path(burst, stop.number), class: "number" %>
     <%= link_to stop.title, burst_pull_request_path(burst, stop.number), class: "title" %>

data/app/views/proctolog/bursts/_side.html.erb

@@ -1,7 +1,7 @@
 <%# locals: (burst:, at: nil) %>
-<%# The pane at the left of every page of a burst: the plaque the desk is named for, where the desk's pages are, and the route with how far each pull request's decisions are, so the owner always sees where they stand. `at` is the pull request the page is on. Focused on a part, it lists that part, with the key back to the whole burst, and counts what is left in the part against the burst; a pull request opened from outside the part stands apart under it. A page that keeps choices rewrites the counts as they change. data-desk keeps it out of a page's reading order. %>
+<%# The pane at the left of every page of a burst: the plaque the desk is named for, where the desk's pages are, and the route with how far each pull request's decisions are and what came back from the agent, so the owner always sees where they stand. `at` is the pull request the page is on. Focused on a part, it lists that part, with the key back to the whole burst, and counts what is left in the part against the burst; a pull request opened from outside the part stands apart under it. A page that keeps choices rewrites the counts as they change. data-desk keeps it out of a page's reading order. %>
 <% route = burst.route %>
-<% progress = burst.progress(route) %>
+<% standings = burst.standings(route) %>
 <aside class="side" aria-label="The burst" data-desk>
   <div class="head">
     <%= link_to image_tag("/plaque.png", alt: "", class: "plaque"), burst_path(burst), tabindex: -1, aria: {hidden: true} %>
@@ -19,7 +19,7 @@
     <p class="focus">Only <%= focus.part.in_words %> · <%= link_to url_for(part: nil), data: {key: "P"} do %><kbd>P</kbd> the whole burst<% end %></p>
   <% end %>
   <%= tag.p class: "overall", data: {side_overall: "", part_prs: (focus.map(&:number).join(" ") unless focus.whole?)} do %>
-    <%= side_gauge(progress.each_value.sum(Proctolog::Choices::NONE), part: (focus.sum(Proctolog::Choices::NONE) { progress.fetch(it.number) } unless focus.whole?)) %>
+    <%= side_gauge(standings.each_value.sum(Proctolog::Choices::NONE, &:progress), part: (focus.sum(Proctolog::Choices::NONE) { standings.fetch(it).progress } unless focus.whole?)) %>
   <% end %>
   <%# Only how many notices there are: they are read at the head of the route. %>
   <% if (notices = burst.notices).any? %>
@@ -30,14 +30,14 @@
     <h2><%= part_heading(part, route) %></h2>
     <ol class="stops">
       <% route.stops_of(part).each do |stop| %>
-        <%= render "proctolog/bursts/side_stop", burst:, stop:, progress: progress.fetch(stop.number), at: %>
+        <%= render "proctolog/bursts/side_stop", burst:, stop:, standing: standings.fetch(stop), at: %>
       <% end %>
     </ol>
   <% end %>
   <% if (outside = route.at(at)) && !focus.include?(outside) %>
     <h2>Outside this part</h2>
     <ol class="stops">
-      <%= render "proctolog/bursts/side_stop", burst:, stop: outside, progress: progress.fetch(outside.number), at: %>
+      <%= render "proctolog/bursts/side_stop", burst:, stop: outside, standing: standings.fetch(outside), at: %>
     </ol>
   <% end %>
 
@@ -45,5 +45,6 @@
   <%= tag.div class: "read", data: {freshness: burst_freshness_path(burst), read_at: burst.read_at.iso8601} do %>
     <p>GitHub read <%= tag.time read_at_in_words(burst.read_at), datetime: burst.read_at.iso8601 %> · <%= link_to "read again", burst_freshness_path(burst, again: 1, back: request.fullpath), class: "again", data: {key: "r"} %></p>
     <p class="moved" data-moved hidden></p>
+    <%= render "proctolog/shares/line" %>
   <% end %>
 </aside>

data/app/views/proctolog/bursts/_side_stop.html.erb

@@ -1,10 +1,10 @@
-<%# locals: (burst:, stop:, progress:, at:) %>
-<%# One pull request of the pane: its mark, its number, its title and how far its decisions are, marked when the page is about it. Held under the pointer, side.js says the same in words, with its title in full and the way to it on GitHub. %>
+<%# locals: (burst:, stop:, standing:, at:) %>
+<%# One pull request of the pane: ↩ when the agent's answers came back on it, its number, its title and its decisions as beads, marked when the page is about it. Held under the pointer, side.js says the same in words, with its title in full and the way to it on GitHub. %>
 <%= tag.li data: {side_pr: stop.number, github: stop.url}, aria: {current: ("page" if stop.number == at)} do %>
   <%= link_to burst_pull_request_path(burst, stop.number) do %>
-    <span class="mark" data-side-mark><%= side_mark(progress) %></span>
+    <%= side_mark(standing.for_the_owner) %>
     <span class="number"><%= stop.number %></span>
     <span class="title"><%= stop.title %></span>
-    <span class="fraction" data-side-fraction><%= side_fraction(progress) %></span>
+    <span class="decisions" data-side-decisions><%= decision_beads(standing.progress) %></span>
   <% end %>
 <% end %>

data/app/views/proctolog/notes/_card.html.erb

@@ -1,5 +1,5 @@
 <%# locals: (note:, burst:, stop:, where: nil, back: nil, attributes: {}) %>
-<%# One note as a card: what it is, what was said, where it is pinned (`where`), the agent's reply, and the ways to move it along. A press of those comes back to `back` when the page that showed the card gave one. %>
+<%# One note as a card: what it is, what was said, where it is pinned (`where`), the agent's reply, and the ways to move it along. A press of those comes back to `back` when the page that showed the card gave one. A note answered in a handover is confirmed or answered back under Returned work, which moves it (Rounds#move_notes), so it can only be withdrawn here. %>
 <%= tag.li(**{class: "card", data: {kind: note.kind, state: note.state}}.deep_merge(attributes)) do %>
   <p class="meta"><span class="kind"><%= note.kind %></span> <span class="state"><%= note.state %></span></p>
   <p class="text"><%= with_mentions(note.text, burst:) %></p>
@@ -12,8 +12,12 @@
   <% end %>
   <div class="moves">
     <% path = burst_pull_request_note_path(burst, stop.number, note.id) %>
-    <%= button_to "Confirm", path, method: :patch, params: {state: "confirmed", return: back}.compact, class: "quiet" if note.addressed? %>
-    <%= button_to "Reopen", path, method: :patch, params: {state: "open", return: back}.compact, class: "quiet" unless note.open? %>
+    <% if note.answered_in_a_handover? %>
+      <% if note.addressed? %><p class="judged">Confirm it, or answer back, under Returned work.</p><% end %>
+    <% else %>
+      <%= button_to "Confirm", path, method: :patch, params: {state: "confirmed", return: back}.compact, class: "quiet" if note.addressed? %>
+      <%= button_to "Reopen", path, method: :patch, params: {state: "open", return: back}.compact, class: "quiet" unless note.open? %>
+    <% end %>
     <%= button_to "Withdraw", path, method: :patch, params: {state: "withdrawn", return: back}.compact, class: "quiet" unless note.withdrawn? %>
   </div>
 <% end %>

data/app/views/proctolog/open_pull_requests/_side.html.erb

@@ -1,5 +1,5 @@
 <%# locals: (bursts:, read_at:) %>
-<%# The pane at the left where no burst is open: the plaque, where the desk's pages are, and the bursts to open, the newest first, each with how far its decisions are. Those put away stay off it, as on the page. %>
+<%# The pane at the left where no burst is open: the plaque, where the desk's pages are, and the bursts to open, the newest first, each with how many of its decisions wait. Those put away stay off it, as on the page. %>
 <aside class="side" aria-label="The desk" data-desk>
   <div class="head">
     <%= link_to image_tag("/plaque.png", alt: "", class: "plaque"), open_pull_requests_path, tabindex: -1, aria: {hidden: true} %>
@@ -15,10 +15,10 @@
         <% progress = burst.progress(burst.route).each_value.sum(Proctolog::Choices::NONE) %>
         <li>
           <%= link_to burst_path(burst) do %>
-            <span class="mark"><%= side_mark(progress) %></span>
+            <span class="mark"></span>
             <span class="number"></span>
             <span class="title"><%= burst.name %></span>
-            <span class="fraction"><%= side_fraction(progress) %></span>
+            <span class="decisions"><%= decisions_left(progress) %></span>
           <% end %>
         </li>
       <% end %>
@@ -26,5 +26,6 @@
   <% end %>
   <div class="read">
     <p>GitHub read <%= tag.time read_at_in_words(read_at), datetime: read_at.iso8601 %> · <%= link_to "read again", open_pull_requests_path(fresh: 1), class: "again" %></p>
+    <%= render "proctolog/shares/line" %>
   </div>
 </aside>

data/app/views/proctolog/open_pull_requests/_start.html.erb

@@ -0,0 +1,8 @@
+<%# locals: (pick:, repository:, first_time:) %>
+<%# At the head of the page, what to do here: for someone who has not reviewed here yet, or when nothing below has decisions to ask. %>
+<% if (start = pick.start(first_time:)) %>
+  <section class="start" aria-labelledby="start">
+    <h2 id="start">Start here</h2>
+    <%= render "proctolog/open_pull_requests/start/#{start}", pick:, repository: %>
+  </section>
+<% end %>

data/app/views/proctolog/open_pull_requests/index.html.erb

@@ -15,6 +15,8 @@
 </header>
 
 <main class="route pick">
+  <%= render "start", pick: @pick, repository: @repository, first_time: [*@bursts, *@put_away].none?(&:own?) %>
+
   <% if @bursts.any? || @put_away.any? %>
     <h2>Your bursts</h2>
     <ol class="lines">
@@ -36,10 +38,6 @@
     <% end %>
   <% end %>
 
-  <% if @pick.empty? %>
-    <p class="lede">Nothing is open in <%= @repository %>.</p>
-  <% end %>
-
   <% @pick.stacks.each do |stack| %>
     <h2>Stack #<%= stack.number %>, <%= stack.pull_requests.size %> from the bottom up</h2>
     <%= button_to "Review the stack", review_stack_path(stack.number), class: "quiet" %>
@@ -59,7 +57,8 @@
 
   <% if (loose = @pick.loose).any? %>
     <h2><%= @pick.stacks.any? ? "In no stack" : "Pull requests" %></h2>
-    <%= form_with url: bursts_path, method: :post do |form| %>
+    <%# Its "Review alone" buttons post elsewhere, so the form carries the session's token, not one good for bursts_path alone. %>
+    <%= form_with url: bursts_path, method: :post, authenticity_token: form_authenticity_token do |form| %>
       <ol class="lines">
         <% loose.each do |pull_request| %>
           <li>

data/app/views/proctolog/open_pull_requests/start/_first_time.html.erb

@@ -0,0 +1,3 @@
+<%# locals: (pick:, repository:) %>
+<p><%= pluralize(pick.written.size, "pull request") %> below <%= (pick.written.size == 1) ? "is" : "are" %> written for PRoctolog: their facts count the decisions they ask you. Press <b>Review alone</b> on one, <b>Review the stack</b> for a whole stack, or tick a few to review them together.</p>
+<p>Inside, <kbd>?</kbd> shows the keys.</p>

data/app/views/proctolog/open_pull_requests/start/_nothing_open.html.erb

@@ -0,0 +1,3 @@
+<%# locals: (pick:, repository:) %>
+<p>Nothing is open in <%= repository %>, and no branch here waits to be opened.</p>
+<p>The desk reviews pull requests whose descriptions list decisions for you. Ask your agent to “write these PRs for PRoctolog”: it opens them on GitHub, or leaves them on branches here for you to review first. Then <%= link_to "read GitHub again", open_pull_requests_path(fresh: 1) %>.</p>

data/app/views/proctolog/open_pull_requests/start/_nothing_written.html.erb

@@ -0,0 +1,3 @@
+<%# locals: (pick:, repository:) %>
+<p>None of these is written for PRoctolog yet, so the desk has no decisions to ask you. Any of them still opens, to read with its pictures and code.</p>
+<p>For decisions, ask your agent to “rewrite these PRs for PRoctolog”. <code>proctolog check <%= pick.loose.first&.number || pick.stacks.first&.top&.number %></code> says what a description still lacks.</p>

data/app/views/proctolog/shares/_line.html.erb

@@ -0,0 +1,5 @@
+<%# At the foot of the pane at the left: whether the desk is shared, as its file says, and the page to share it or stop. %>
+<% share = Proctolog::Share.kept(Proctolog::Desk.port) %>
+<p class="share">
+  <%= share ? "Shared through #{share.way.name}" : "Only on this Mac" %> · <%= link_to (share ? "see it" : "share it"), share_path(back: request.fullpath), class: "again" %>
+</p>