runsheets 0.0.1

data/lib/runsheets/redactor.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # Replaces secret input values in captured output before it is stored.
+  #
+  # Plain string replacement: a secret that a command prints base64-encoded,
+  # URL-encoded or split across lines is not caught. Output arrives in
+  # chunks, so #feed holds back any tail that could be the start of a
+  # secret until the next chunk (or #flush) settles it, so however the
+  # output is split, no whole secret gets through.
+  class Redactor
+    # The redactor for a run: every secret input that has a value.
+    def self.for(inputs, runbook)
+      secrets = inputs.to_h.select { |name, value| runbook.input(name)&.secret? && !value.to_s.empty? }
+      new(secrets)
+    end
+
+    attr_reader :secrets
+
+    # +secrets+ maps an input name to its value.
+    def initialize(secrets)
+      @secrets = secrets.to_h { |name, value| [name.to_s, value.to_s.b] }.reject { |_, v| v.empty? }.freeze
+      @values  = @secrets.sort_by { |_, v| -v.bytesize }.freeze
+      @names   = @values.reverse.to_h(&:reverse).freeze # value => name, the first name winning a shared value
+      @pattern = Redactor.pattern(@values.map(&:last))
+      @pending = +"".b
+    end
+
+    # One binary Regexp matching any of +values+, longest first, so a secret
+    # that contains another is matched whole.
+    def self.pattern(values) = values.empty? ? nil : Regexp.new(values.map { Regexp.escape(it) }.join("|").b)
+
+    def empty? = @secrets.empty?
+
+    # Longest tail of a chunk that could still be the start of a secret.
+    def hold_back = @values.map { |_, v| v.bytesize }.max.to_i - 1
+
+    # Every occurrence of every secret replaced, in one left-to-right pass.
+    def redact(text)
+      return text if empty?
+
+      text.b.gsub(@pattern) { "[redacted #{@names[it]}]" }.force_encoding(text.encoding)
+    end
+
+    # Streaming: returns the part of the output so far that is safe to
+    # write, keeping back a tail that may be a partial secret.
+    def feed(chunk)
+      return chunk if empty?
+
+      @pending << chunk.b
+      settled = last_match_end(@pending)
+      keep    = partial_secret_length(@pending.byteslice(settled..))
+      safe    = @pending.byteslice(0, @pending.bytesize - keep)
+      @pending = @pending.byteslice(@pending.bytesize - keep, keep) || +"".b
+      redact(safe)
+    end
+
+    # Whatever #feed was holding back, redacted. Call at end of stream.
+    def flush
+      out = redact(@pending)
+      @pending = +"".b
+      out
+    end
+
+    # Where the last secret #redact would replace in +text+ ends, or 0.
+    # Matches are found left to right as #redact finds them, so one that
+    # overlaps an earlier match is not counted.
+    def last_match_end(text)
+      at = 0
+      ends = 0
+      while (match = @pattern.match(text, at))
+        ends = at = match.end(0)
+      end
+      ends
+    end
+
+    # Length of the longest suffix of +text+ that is a proper prefix of
+    # some secret.
+    def partial_secret_length(text)
+      limit = [hold_back, text.bytesize].min
+      limit.downto(1) do |k|
+        tail = text.byteslice(-k, k)
+        return k if @values.any? { |_, v| v.bytesize > k && v.start_with?(tail) }
+      end
+      0
+    end
+  end
+end

data/lib/runsheets/renderer.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require "securerandom"
+require "kramdown"
+require "kramdown-parser-gfm"
+require "rouge"
+
+module Runsheets
+  # Markdown to HTML, with executable blocks wrapped in the markup the page's
+  # JavaScript needs (data attributes, toolbar, output area).
+  module Renderer
+    Result = Data.define(:html, :blocks)
+
+    ROUGE_THEME = "base16.monokai.dark"
+
+    # A random value for this process, stamped on every block wrapper and
+    # control the page's script may act on. Raw HTML in markdown can copy the
+    # markup of a Run button, but not this value, so the script ignores it.
+    MARK = SecureRandom.hex(16)
+
+    # Rouge formatter that wraps block output the way kramdown's layout
+    # expects (<div class="highlight"><pre class="highlight"><code>) without
+    # going through the deprecated HTMLLegacy formatter. kramdown passes
+    # wrap: false for inline code spans.
+    class CodeFormatter < Rouge::Formatters::HTML
+      def initialize(opts = {})
+        super()
+        @css_class = opts[:css_class] || "highlight"
+        @wrap      = opts[:wrap] != false
+      end
+
+      def stream(tokens, &)
+        return super unless @wrap
+
+        yield %(<div class="#{@css_class}"><pre class="#{@css_class}"><code>)
+        super
+        yield "</code></pre></div>"
+      end
+    end
+
+    KRAMDOWN_OPTIONS = {
+      input:                   "GFM",
+      hard_wrap:               false,
+      syntax_highlighter:      "rouge",
+      syntax_highlighter_opts: { css_class: "highlight", formatter: CodeFormatter }
+    }.freeze
+
+    # kramdown HTML converter that recognises the "lang?rs=N" marker Fences
+    # plants and wraps the Nth block.
+    class HtmlConverter < Kramdown::Converter::Html
+      public_class_method :new
+
+      MARKER = /\A(.*?)\?rs=(\d+)\z/
+
+      attr_accessor :blocks
+
+      def convert_codeblock(el, indent)
+        match = el.options[:lang].to_s.match(MARKER)
+        block = match && blocks&.[](match[2].to_i)
+        return super unless block
+
+        if match[1].empty?
+          el.options.delete(:lang)
+          el.attr.delete("class")
+        else
+          el.options[:lang]  = match[1]
+          el.attr["class"]   = "language-#{match[1]}"
+        end
+
+        Renderer.wrap_block(block, super, indent)
+      end
+    end
+
+    # Render markdown. Blocks get ids "#{id_prefix}-1", "#{id_prefix}-2", ...
+    # +interpreters+ decides which languages can execute.
+    def self.render(markdown, id_prefix:, interpreters: Block::INTERPRETERS)
+      rewritten, fences = Fences.extract(markdown)
+      blocks = fences.map.with_index do |fence, i|
+        Block.new(id: "#{id_prefix}-#{i + 1}", index: i, info: fence.info, code: fence.code, line: fence.line, interpreters:)
+      end
+      link_expectations(blocks)
+
+      doc       = Kramdown::Document.new(rewritten, **KRAMDOWN_OPTIONS)
+      options   = Kramdown::Options.merge(doc.options.merge(doc.root.options[:options] || {}))
+      converter = HtmlConverter.new(doc.root, options)
+      converter.blocks = blocks
+
+      Result.new(html: strip_meta(converter.convert(doc.root)), blocks:)
+    end
+
+    # Render markdown as plain HTML: nothing is executable, so no block is
+    # wrapped. For prose outside a runbook, such as a library folder's README.
+    def self.render_plain(markdown) = strip_meta(Kramdown::Document.new(markdown, **KRAMDOWN_OPTIONS).to_html)
+
+    # Remove <meta> tags from rendered markdown. A meta refresh would
+    # navigate the page wherever the markdown says, and no Content-Security-
+    # Policy stops one; a runbook has no use for any other <meta>.
+    def self.strip_meta(html) = html.gsub(/<meta\b[^>]*>/i, "")
+
+    def self.h(value) = CGI.escapeHTML(value.to_s)
+
+    # The attribute that marks an element as the page's own (see MARK).
+    def self.mark_attr = %( data-rs-mark="#{MARK}")
+
+    # An expect block illustrates the nearest executable block above it.
+    def self.link_expectations(blocks)
+      last = nil
+      blocks.each do |block|
+        if block.executable?
+          last = block
+        elsif block.expect? && last
+          block.expect_for = last.id
+        end
+      end
+      blocks
+    end
+
+    # The <div class="rs-block"> wrapper around a highlighted code block.
+    def self.wrap_block(block, code_html, indent = 0)
+      pad     = " " * indent
+      classes = ["rs-block", "rs-#{block.kind}"]
+      classes << "rs-executable" if block.executable?
+      classes << "rs-warned" if block.warnings.any?
+      attrs = %(id="block-#{h block.id}"#{mark_attr} data-block="#{h block.id}" data-kind="#{block.kind}" ) +
+              %(data-digest="#{block.digest}" data-lang="#{h block.lang}")
+      attrs += %( data-expect-for="#{h block.expect_for}") if block.expect_for
+
+      <<~HTML
+        #{pad}<div class="#{classes.join(' ')}" #{attrs}>
+        #{pad}<div class="rs-toolbar">#{toolbar(block)}</div>
+        #{code_html.chomp}
+        #{pad}<div class="rs-result" hidden><div class="rs-panes"><div class="rs-pane rs-actual"><div class="rs-pane-title">output</div><pre class="rs-output" data-role="output"></pre></div><div class="rs-pane rs-expected" data-role="expected" hidden><div class="rs-pane-title">expected</div><pre></pre></div></div><div class="rs-exit" data-role="exit"></div></div>
+        #{pad}</div>
+      HTML
+    end
+
+    NOTES = {
+      terminal:   "run this in your own terminal, then confirm",
+      expect:     "expected output",
+      background: "runs until stopped or the run ends"
+    }.freeze
+
+    def self.toolbar(block)
+      parts = ["<span class=\"rs-badge rs-#{block.kind}\">#{h block.label}</span>"]
+      block.warnings.each { parts << "<span class=\"rs-warning\" title=\"authoring warning\">#{h it}</span>" }
+      if block.expect_for
+        parts << "<span class=\"rs-note\">expected output of <a href=\"#block-#{h block.expect_for}\">#{h block.expect_for}</a></span>"
+      elsif NOTES.key?(block.kind)
+        parts << "<span class=\"rs-note\">#{h NOTES[block.kind]}</span>"
+      end
+      parts << '<span class="rs-spacer"></span>'
+      parts << '<button type="button" class="rs-btn rs-copy" data-action="copy" title="Copy to clipboard">Copy</button>'
+      parts.concat(action_buttons(block))
+      parts << '<span class="rs-status" data-role="status" role="status" aria-live="polite"></span>'
+      parts.join
+    end
+
+    # The buttons that act on a block: Start and Stop, Run, or I ran this,
+    # each labelled with the block id for screen readers.
+    def self.action_buttons(block)
+      id = h(block.id)
+      if block.background?
+        [%(<button type="button" class="rs-btn rs-run" data-action="execute" aria-label="Start #{id}">Start</button>),
+         %(<button type="button" class="rs-btn rs-stop" data-action="stop" hidden>Stop</button>)]
+      elsif block.executable?
+        label = block.destructive? ? "Run (destructive)" : "Run"
+        style = block.destructive? ? "rs-btn rs-run rs-danger" : "rs-btn rs-run"
+        [%(<button type="button" class="#{style}" data-action="execute" aria-label="#{label} #{id}">#{label}</button>)]
+      elsif block.acknowledgeable?
+        [%(<button type="button" class="rs-btn rs-ack" data-action="acknowledge" aria-label="I ran #{id}">I ran this</button>)]
+      else
+        []
+      end
+    end
+
+    # The first level-one heading of a markdown document, or nil.
+    def self.title_of(markdown) = without_fences(markdown)[/^#[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*\r?$/, 1]
+
+    # Markdown with its fenced code blocks taken out.
+    def self.without_fences(markdown) = markdown.to_s.gsub(/^ {0,3}(`{3,}|~{3,})[^\n]*\n.*?^ {0,3}\1[`~]*[ \t]*\r?$/m, "")
+
+    # Point relative <img src> and <a href> values at the /files/ route so
+    # assets that sit next to a markdown file resolve, and links (not images)
+    # to markdown files at the /docs/ route, which renders them. base_dir is the file's
+    # directory relative to the runbook root ('' for the root).
+    def self.rewrite_relative_urls(html, base_dir, prefix: "/files")
+      html.gsub(/(<(img|a)\b[^>]*\b(?:src|href)=")([^"]*)(")/) do
+        before, tag, url, after = Regexp.last_match.captures
+        if url.match?(%r{\A([a-z][a-z0-9+.-]*:|/|#|\?)}i)
+          "#{before}#{url}#{after}"
+        else
+          joined = join_relative(base_dir, url)
+          route  = tag == "a" && markdown_path?(joined.to_s) ? "/docs" : prefix
+          "#{before}#{joined ? "#{route}/#{joined}" : url}#{after}"
+        end
+      end
+    end
+
+    def self.markdown_path?(path) = path.match?(/\.md(?:[#?]|\z)/i)
+
+    # Make every /docs/ link in +html+ that leads to a plain document under
+    # +root+ open in a new tab; links to a runbook or one of its files stay
+    # in the tab, since they navigate the runbooks rather than open
+    # reference reading.
+    def self.open_documents_in_new_tab(html, root)
+      html.gsub(%r{(<a\b[^>]*\bhref="/docs/([^"#?]*)[^"]*")}) do
+        link, path = Regexp.last_match.captures
+        Runbook.plain_document?(File.join(root, CGI.unescapeURIComponent(path)), root) ? %(#{link} target="_blank" rel="noopener") : link
+      end
+    end
+
+    # Join a relative href onto a base directory, resolving '.' and '..'.
+    # Returns nil if the href climbs above the root.
+    def self.join_relative(base_dir, href)
+      parts = base_dir.to_s.split("/").reject { it.empty? || it == "." }
+      href.to_s.split("/").each do |part|
+        case part
+        when "", "." then next
+        when ".."    then parts.pop.nil? and return nil
+        else parts << part
+        end
+      end
+      parts.join("/")
+    end
+
+    def self.code_stylesheet = Rouge::Theme.find(ROUGE_THEME).render(scope: ".highlight")
+  end
+end

data/lib/runsheets/run.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+module Runsheets
+  # One runbook's part of a session: the run the engineer established by
+  # selecting the runbook, its inputs (secrets included, in memory only),
+  # its record, and the executions it started. A run stays open until the
+  # session ends; there is no finishing it by hand.
+  #
+  # Everything it does is written to the run's record and the session log.
+  # It knows nothing about HTTP.
+  class Run
+    # Raised when a destructive block is executed without the typed
+    # confirmation. Carries the code the operator has to type.
+    class ConfirmationRequired < RunError
+      attr_reader :challenge, :block_id
+
+      def initialize(block_id, challenge)
+        @block_id  = block_id
+        @challenge = challenge
+        super("destructive block #{block_id} needs confirmation: type #{challenge}")
+      end
+    end
+
+    STOP_WAIT = Executor::GRACE + 1.0
+
+    attr_reader :session, :runbook, :record, :inputs
+
+    # Establish the run: resolve +given+ inputs, write the record's first
+    # version under the session's id, and log it.
+    def initialize(session:, runbook:, inputs: {})
+      @session    = session
+      @runbook    = runbook
+      @executions = {}
+      @challenges = {}
+      @mutex      = Mutex.new
+      @closing    = false
+      @inputs     = Run.resolve_inputs(runbook, inputs, carried: session.carried_inputs)
+      @redactor   = Redactor.for(@inputs, runbook)
+      @record     = RunRecord.start(session.runs_root, runbook, session_id: session.id, inputs: @inputs)
+      log_opened
+    end
+
+    # Inputs as they will be exported. For each declared input: the value
+    # given, else one given for the same name earlier in the session
+    # (+carried+, never a secret), else the environment, else the default.
+    def self.resolve_inputs(runbook, given = {}, carried: {})
+      given = given.to_h.transform_keys(&:to_s)
+      runbook.inputs.to_h do |input|
+        name   = input.name
+        values = [given[name], (carried[name] unless input.secret?), ENV[name], input.default]
+        [name, Run.clean(values.find { !it.to_s.empty? })]
+      end
+    end
+
+    # An input value as it can be exported and recorded: valid UTF-8, no NUL.
+    def self.clean(value) = value.to_s.dup.force_encoding("UTF-8").scrub.delete("\u0000")
+
+    # +given+ with every blank secret filled from +current+.
+    def self.keep_blank_secrets(runbook, given, current)
+      runbook.inputs.select(&:secret?).each_with_object(given.dup) do |input, out|
+        out[input.name] = current[input.name] if out[input.name].to_s.empty?
+      end
+    end
+
+    def slug = runbook.slug
+    def open? = record.active?
+
+    # Raise unless the run is still open.
+    def ensure_open!
+      raise RunError, "the run for #{slug} has ended" if @closing || !open?
+    end
+
+    # The runbook reloaded from disk (see Session#refresh_runbook!).
+    def runbook=(runbook)
+      @mutex.synchronize { @runbook = runbook }
+    end
+
+    # Change the inputs partway. Recorded and logged; secrets as "[secret]".
+    # A secret left blank keeps its current value.
+    def change_inputs(given)
+      given = Run.keep_blank_secrets(runbook, given.to_h.transform_keys(&:to_s), @inputs)
+      @mutex.synchronize do
+        @inputs   = Run.resolve_inputs(runbook, given, carried: {})
+        @redactor = Redactor.for(@inputs, runbook)
+        record.change_inputs(@inputs, runbook)
+        record.write!
+      end
+      log.info("inputs changed #{inputs_text}", tags: [slug])
+      self
+    end
+
+    # Names of secret inputs that have a value, for display as "set".
+    def secret_inputs_set = runbook.inputs.select(&:secret?).map(&:name).reject { @inputs[it].to_s.empty? }
+
+    # Start executing a block. Returns the Execution.
+    #
+    # A destructive block needs +confirm+ to equal the challenge issued for
+    # it; the first attempt without one raises ConfirmationRequired carrying
+    # the challenge. +digest+, when given, is the Block#digest the page
+    # showed; a block that no longer matches it is refused.
+    def execute(block_id, confirm: nil, digest: nil)
+      @mutex.synchronize do
+        step, block = executable_block!(block_id)
+        Run.same_block!(block, digest)
+        if block.destructive? && !confirmed?(block_id, confirm)
+          log.warn("destructive block #{block_id} refused: #{confirm.nil? ? 'needs' : 'wrong'} confirmation code", tags: [slug, step.slug])
+          raise ConfirmationRequired.new(block_id, challenge_for(block_id))
+        end
+
+        execution = build_execution(step, block)
+        record.record_execution(execution, step:, confirmed: block.destructive?)
+        @executions[execution.id] = execution
+        log_execute(execution, step, block)
+        execution.on_end { ended(it) }
+        session.executor.start(execution, code: block.code, env: environment_for(execution), cwd: working_directory(step),
+redactor: Redactor.new(@redactor.secrets))
+        record.write!
+        execution
+      end
+    end
+
+    # The step and block for an id, or a RunError saying why it cannot run.
+    def executable_block!(block_id)
+      ensure_open!
+
+      step, block = runbook.find_block(block_id)
+      raise RunError, "unknown block #{block_id}" unless block
+      raise RunError, "block #{block_id} is not executable (#{block.kind})" unless block.executable?
+
+      blank = blank_inputs(block)
+      raise RunError, "blank input#{'s' if blank.size > 1} referenced by block: #{blank.join(', ')}" if blank.any?
+
+      [step, block]
+    end
+
+    # A pending Execution for a block, with its files allocated in the run.
+    def build_execution(step, block)
+      cmd_path, log_path = record.paths_for(block)
+      id = SecureRandom.hex(6)
+      Execution.new(
+        id:, block_id: block.id, step_slug: step.slug,
+        command: runbook.interpreter_for(block.lang), cmd_path:, log_path:,
+        timeout: block.background? ? nil : step.timeout, background: block.background?,
+        tee: log.output_stream(["##{id}"])
+      )
+    end
+
+    # The confirmation code currently expected for a destructive block,
+    # issuing one if none is outstanding.
+    def challenge_for(block_id) = @challenges[block_id] ||= SecureRandom.hex(2)
+
+    # Stop a running execution. Returns the Execution; the state changes to
+    # :stopped once the reaper has ended the process group.
+    def stop(execution_id)
+      execution = @executions[execution_id] or raise RunError, "no execution #{execution_id}"
+      log.info("stop requested", tags: [slug, execution.step_slug, "##{execution.id}"])
+      session.executor.stop(execution)
+      execution
+    end
+
+    # Record that the operator ran a terminal block themselves.
+    def acknowledge(block_id, note: nil, digest: nil)
+      note = Run.note(note)
+      ack = @mutex.synchronize do
+        ensure_open!
+
+        step, block = runbook.find_block(block_id)
+        raise RunError, "unknown block #{block_id}" unless block
+        raise RunError, "block #{block_id} is not a terminal block (#{block.kind})" unless block.acknowledgeable?
+
+        Run.same_block!(block, digest)
+
+        record.acknowledge(block, step:, note:)
+        record.write!
+        record.acks[block.id]
+      end
+      log.info("confirmed terminal block #{block_id} run by hand#{": #{note}" if note}", tags: [slug, ack[:step]])
+      ack
+    end
+
+    def ack(block_id) = record.acks[block_id]
+
+    # A live execution of this run by id, or nil.
+    def execution(id) = @executions[id]
+
+    def executions         = @executions.values
+    def running_executions = executions.select(&:running?)
+
+    # Only numbered steps can be marked: the landing page and the extra
+    # documents are not part of the procedure's progress.
+    def mark_step(step_slug, status:, note: nil)
+      note = Run.note(note)
+      @mutex.synchronize do
+        ensure_open!
+
+        step = runbook.step(step_slug) or raise RunError, "unknown step #{step_slug}"
+        raise RunError, "#{step_slug} is not a numbered step" unless step.position
+
+        record.mark_step(step, status:, note:)
+        record.write!
+      end
+      log.info("marked #{status}#{": #{note}" if note}", tags: [slug, step_slug])
+    end
+
+    def step_status(step_slug) = record.step_status[step_slug]
+
+    # End the run with the session: stop whatever it left running, and
+    # close the record with the status worked out from what was done.
+    # Returns that status.
+    def close!
+      @mutex.synchronize { @closing = true }
+      stop_all
+      status = record.closing_status(runbook.steps.map(&:slug))
+      record.finish!(status:)
+      status
+    end
+
+    # Declared inputs the block refers to that have no value.
+    def blank_inputs(block)
+      declared = runbook.inputs.map(&:name)
+      (block.referenced_variables & declared).select { @inputs[it].to_s.empty? }
+    end
+
+    def environment_for(execution)
+      @inputs.merge(
+        "RUNSHEETS_SESSION_ID" => session.id,
+        "RUNSHEETS_RUN_ID"     => record.id,
+        "RUNSHEETS_RUN_DIR"    => record.dir,
+        "RUNSHEETS_RUNBOOK"    => slug,
+        "RUNSHEETS_STEP"       => execution.step_slug,
+        "RUNSHEETS_BLOCK"      => execution.block_id
+      )
+    end
+
+    def working_directory(step)
+      step.cwd ? File.expand_path(step.cwd, runbook.dir) : runbook.dir
+    end
+
+    # Raise RunError unless +block+ is still the one whose Block#digest the
+    # page sent. No digest (a script calling the API) skips the check.
+    def self.same_block!(block, digest)
+      return if digest.nil? || digest == block.digest
+
+      raise RunError, "block #{block.id} changed on disk since this page loaded; reload the page"
+    end
+
+    # A note as recorded: stripped, nil when blank.
+    def self.note(text)
+      text = text.to_s.strip
+      text.empty? ? nil : text
+    end
+
+    # The inputs as the log shows them: NAME=value, secrets as [secret].
+    def inputs_text
+      runbook.inputs.map { "#{it.name}=#{it.secret? ? '[secret]' : @inputs[it.name]}" }.join(" ")
+    end
+
+    # How an ended execution reads in the log, and at what level.
+    def self.ending(execution)
+      took = execution.duration ? format(" in %.2fs", execution.duration) : ""
+      case execution.state
+      when :finished
+        execution.exit_status.zero? ? ["info", "finished exit 0#{took}"] : ["warn", "finished exit #{execution.exit_status}#{took}"]
+      when :timed_out then ["warn", "timed out after #{execution.timeout}s"]
+      when :stopped   then ["info", "stopped#{took}"]
+      else ["error", "failed to start: #{execution.error}"]
+      end
+    end
+
+    private
+
+    def log = session.log
+
+    def log_opened
+      log.info("run opened #{inputs_text}".strip, tags: [slug])
+      runbook.warnings.each { log.warn("authoring warning: #{it}", tags: [slug]) }
+    end
+
+    def log_execute(execution, step, block)
+      tags = [slug, step.slug, "##{execution.id}"]
+      log.info("execute #{block.lang} via #{execution.command.join(' ')}#{' (confirmed)' if block.destructive?}#{' (background)' if block.background?}", tags:)
+      log.info(block.code.chomp.lines.map { "$ #{it.chomp}" }.join("\n"), tags: ["##{execution.id}"])
+      log.debug("environment #{environment_text(execution)}", tags:)
+    end
+
+    def environment_text(execution)
+      secrets = runbook.inputs.select(&:secret?).map(&:name)
+      environment_for(execution).map { |k, v| "#{k}=#{secrets.include?(k) ? '[secret]' : v}" }.join(" ")
+    end
+
+    # Runs on the reaper thread once an execution has ended: log how it
+    # ended and save the record.
+    def ended(execution)
+      level, text = Run.ending(execution)
+      log.add(level, text, tags: ["##{execution.id}"])
+      record.write!
+    rescue StandardError => e
+      log.error("could not save the record after #{execution.id}: #{e.class}: #{e.message}", tags: [slug])
+    end
+
+    public
+
+    # Ask everything still running to stop, without waiting: the session
+    # does this for every run before closing them, so they stop together.
+    def stop_running! = running_executions.each { session.executor.stop(it) }
+
+    private
+
+    # Does +confirm+ match the code issued for this block? A match retires
+    # the code.
+    def confirmed?(block_id, confirm)
+      return false unless confirm.is_a?(String) && confirm.strip == challenge_for(block_id)
+
+      @challenges.delete(block_id)
+      true
+    end
+
+    # Stop every running execution and wait for the reapers, briefly.
+    def stop_all
+      running = running_executions
+      running.each { session.executor.stop(it) }
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + STOP_WAIT
+      running.each do |execution|
+        left = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        execution.wait(left) if left.positive?
+      end
+      record.write!
+    end
+  end
+end