hecks 4.0.0 → 6.0.0

data/lib/hecks/hecks/adapters/rehearsal/postgres_census.rb

@@ -59,17 +59,17 @@ module Hecks
                      counts: empty_counts, elsewhere: lineage)
         end
 
-        def empty_counts = @subject.bluebook.aggregates.map { |a| Census::Count.new(aggregate: a.name, head: 0, journal: 0) }
+        def empty_counts = @subject.aggregates.map { |a| Census::Count.new(aggregate: a.name, head: 0, journal: 0) }
 
         def counted(db, name, source, elsewhere)
-          lineage = PostgresEra::Lineage.new(db, @subject.bluebook.name)
+          lineage = PostgresEra::Lineage.new(db, @subject.bluebook_name)
           Census.new(schema: name, source: source, present: true, eras: eras(db), counts: counts(db, lineage),
                      journal_entries: rows(db, lineage.journal), elsewhere: elsewhere)
         end
 
         def counts(db, lineage)
           live = latest(db, lineage)
-          @subject.bluebook.aggregates.map do |aggregate|
+          @subject.aggregates.map do |aggregate|
             Census::Count.new(aggregate: aggregate.name, head: rows(db, lineage.head_view(aggregate.storage_name)),
                               journal: live.fetch(aggregate.storage_name, 0))
           end
@@ -78,7 +78,7 @@ module Hecks
         def eras(db)
           return 0 unless relation?(db, "hecks_eras")
 
-          db.exec_params("SELECT count(*) FROM hecks_eras WHERE domain = $1", [@subject.bluebook.name])[0]["count"].to_i
+          db.exec_params("SELECT count(*) FROM hecks_eras WHERE domain = $1", [@subject.bluebook_name])[0]["count"].to_i
         end
 
         def latest(db, lineage)

data/lib/hecks/hecks/adapters/rehearsal/postgres_reading.rb

@@ -48,14 +48,14 @@ module Hecks
           return [[@declaration.schema, "world"]] if @declaration.schema
           return [[ENV.fetch("HECKS_SCHEMA"), "HECKS_SCHEMA"]] if ENV.fetch("HECKS_SCHEMA", "") != ""
 
-          [[Naming.snake(subject.bluebook.name), "derived"], %w[public default]]
+          [[Naming.snake(subject.bluebook_name), "derived"], %w[public default]]
         end
 
         def reading(subject)
           subject.held.read_from(url)
-          db = PostgresEra.connect_for(subject.bluebook.name, subject.held.settings)
+          db = PostgresEra.connect_for(subject.bluebook_name, subject.settings)
           db.exec("SET default_transaction_read_only = on") if @declaration.mode == "readonly_copy"
-          yield PostgresEra::Lineage.new(db, subject.bluebook.name)
+          yield PostgresEra::Lineage.new(db, subject.bluebook_name)
         ensure
           db&.close
         end

data/lib/hecks/hecks/adapters/rehearsal/postgres_store.rb

@@ -22,6 +22,9 @@ module Hecks
         PREFIX = "hecks_rehearsal_"
         NAME = /\A#{PREFIX}[0-9a-f]{16}\z/
 
+        # A Postgres connection URL, by its scheme.
+        POSTGRES_URL = %r{\Apostgres(ql)?://}
+
         # @param declaration [Declaration] a `postgres` declaration
         # @param run [String] the rehearsal's key
         # @param protected_databases [Array<String>] databases the domain's own world names
@@ -85,7 +88,7 @@ module Hecks
 
         def server_url
           value = @declaration.connection
-          return value if value.match?(%r{\Apostgres(ql)?://})
+          return value if value.match?(POSTGRES_URL)
 
           raise Refused, "#{@declaration.connection_env} must hold a postgres:// URL"
         end

data/lib/hecks/hecks/adapters/rehearsal/rust_audit.rb

@@ -68,7 +68,7 @@ module Hecks
           Result.new(ran: true, violations: refusals(out), note: "ran over #{rows} rows", rows: rows)
         end
 
-        def ir = Projector::Exporter.call(@subject.held.registry).fetch(@subject.bluebook.name)
+        def ir = Projector::Exporter.call(@subject.registry).fetch(@subject.bluebook_name)
 
         def case_for(name, id, state)
           { "aggregate" => name, "id" => id, "state" => JSON.parse(JSON.generate(state)) }

data/lib/hecks/hecks/adapters/rehearsal/subject.rb

@@ -23,7 +23,8 @@ module Hecks
         def self.open(path)
           environment = choose_environment(path)
           held = load(path, environment)
-          new(held, Declaration.from_world(held.registry.world(held.bluebook.name), held.directory), environment)
+          bluebook = held.bluebook
+          new(held, Declaration.from_world(held.registry.world(bluebook.name), held.directory), environment)
         end
 
         # Whatever stops a domain from loading is a reason it cannot boot, a script error included.
@@ -60,7 +61,8 @@ module Hecks
             loading.load_library
             loading.load_each(directory, %w[*.world])
           end
-          registry.worlds.values.filter_map { |world| world.for_verb("rehearsed_by")[:environment] }.first
+          worlds = registry.worlds.values
+          worlds.filter_map { |world| world.for_verb("rehearsed_by")[:environment] }.first
         rescue StandardError, ScriptError
           nil
         end
@@ -75,9 +77,36 @@ module Hecks
           @environment = environment
         end
 
-        # @return [Bluebook::Chapter] the domain's bluebook as it stands
+        # @return [Bluebook::Declaration] the domain's bluebook as it stands
         def bluebook = held.bluebook
 
+        # @return [String] the name of the domain's bluebook
+        def bluebook_name = bluebook.name
+
+        # @return [Array<Bluebook::Behaviour::Aggregate>] the aggregates the bluebook declares
+        def aggregates = bluebook.aggregates
+
+        # @return [Runtime::Registry] the registry the domain was loaded into
+        def registry = held.registry
+
+        # @return [Array<String>] the names of every bluebook the registry holds
+        def bluebook_names = registry.bluebooks.values.map(&:name)
+
+        # @return [String] the persistence adapter the domain's journal store is bound to
+        def adapter_name = held.adapter_name
+
+        # @return [Hash] the settings the domain's journal store is connected with
+        def settings = held.settings
+
+        # @return [Hash] what the rehearsal reports about the overlay it loaded
+        def environment_facts = environment.facts
+
+        # @return [String] the kind of store the world's `rehearsed_by` names
+        def store_kind = declaration.kind
+
+        # @return [String] the copy mode the world's `rehearsed_by` names
+        def copy_mode = declaration.mode
+
         # @return [String] the label the shape a mint would hold has
         def label = Runtime::StorageShape.mint_label(bluebook)
 
@@ -89,13 +118,13 @@ module Hecks
         # @param from [String] the held era's label
         # @return [Bluebook::Translation, nil] the edge; nil when none is declared
         def edge_from(from)
-          held.registry.translations.find { |t| t.domain == bluebook.name && t.from == from && t.to == label }
+          registry.translations.find { |t| t.domain == bluebook.name && t.from == from && t.to == label }
         end
 
         # @return [Array<String>] the persisted databases the domain's own world names, which a
         #   rehearsal must never be pointed at
         def declared_databases
-          blocks = held.registry.world(bluebook.name)&.settings || {}
+          blocks = registry.world(bluebook.name)&.settings || {}
           blocks.select { |key, _| key.to_s.start_with?("persisted_by") }.values.filter_map { |block| block[:database] }
         end
       end

data/lib/hecks/hecks/adapters/rust_toolchain.rb

@@ -70,7 +70,9 @@ module Hecks
       # @return [Hash{Symbol => Hash}] `output:` where the module was written
       # @raise [ConsoleCapture::Failure] when the wasm target or the build is missing
       def wasm(**held)
-        child(:wasm, [plain(held[:domain])])
+        argv = [plain(held[:domain])]
+        argv << "--profile=#{plain(held[:profile])}" if plain(held[:profile])
+        child(:wasm, argv)
       end
 
       # Generates the domain, compiles it to a `wasm32-wasip1` module, builds the host binary from
@@ -85,6 +87,7 @@ module Hecks
         argv = [plain(held[:domain])]
         argv << "--target=#{plain(held[:target])}" if plain(held[:target])
         argv << "--stage=#{plain(held[:stage_dir])}" if plain(held[:stage_dir])
+        argv << "--no-prebuilt" if plain(held[:prebuilt]) == false
         child(:host, argv)
       end
 
@@ -185,8 +188,7 @@ module Hecks
 
       def run(ask, argv)
         space = self.class.workspace || RustWorkspace.new
-        env = space.environment
-        (self.class.runner || RustBuild).capture(TOOLS.fetch(ask), argv, env: env)
+        (self.class.runner || RustBuild).capture(TOOLS.fetch(ask), argv, env: space.environment)
       rescue RustWorkspace::Unavailable => e
         raise ConsoleCapture::Failure, e.message
       end

data/lib/hecks/hecks/adapters/settings_reading.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/settings_reading"
+
+Hecks.adapter "SettingsReading" do
+  port "Settings"
+end

data/lib/hecks/hecks/adapters/settings_reading.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "hecks"
+require_relative "console_capture"
+
+module Hecks
+  module Adapters
+    # The `Settings` port's adapter for `Checkout`: what a copy resolves for each setting that can
+    # come from a variable, the copy's own world or a default, and which of the three supplied it.
+    # It reads and never writes, and prints no secret: a database URL's password is hidden.
+    #
+    # The query takes `domain`, a domain directory (the current directory when absent), and
+    # answers `text:`, one `name: value (source)` line each, then any deprecated variable that is
+    # set. A setting the domain cannot resolve is shown as such, not left out.
+    class SettingsReading
+      # The variables no code reads; one that is set is reported as ignored.
+      RETIRED = %w[HECKS_PRE_PUSH_GATE HECKS_EVAL HECKS_FUZZ_SCHEMA].freeze
+
+      # The first line of a message.
+      FIRST_LINE = /\A[^\n]*/
+
+      # A URL's password: `user:secret@` becomes `user:***@`.
+      PASSWORD = %r{(://[^:/@\s]+):[^@\s]+@}
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # @param held [Hash] `domain`, a domain directory
+      # @return [Hash{Symbol => String}] `text:` the resolved settings
+      # @raise [ConsoleCapture::Failure] when the directory is not there
+      def settings(**held)
+        directory = plain(held[:domain]) || Dir.pwd
+        raise ConsoleCapture::Failure, "#{directory} is not a directory" unless File.directory?(directory)
+
+        { text: (rows(directory).map { |row| line_of(*row) } + deprecated).join("\n") }
+      end
+
+      private
+
+      def rows(directory)
+        [environment, database(directory), mint_eras(directory), schema, project_environment,
+         variable_or_default("cache directory", "HECKS_CACHE_DIR", usage_cache_directory),
+         variable_or_default("rust workspace", "HECKS_RUST_DIR", RustBuild.rust_dir),
+         registry_source(directory)]
+      end
+
+      def line_of(name, value, source) = "#{name}: #{value} (#{source})"
+
+      def environment
+        named = ENV.fetch("HECKS_ENVIRONMENT", "")
+        named.empty? ? ["environment", "none", "default"] : ["environment", named, "variable HECKS_ENVIRONMENT"]
+      end
+
+      # The world's `default_database`, and which of a local world or the world itself supplied it.
+      def database(directory)
+        value = declared_database(directory) || "none declared"
+        ["database", hide_password(value), database_source(directory)]
+      rescue StandardError => e
+        ["database", "could not be read", first_line(e.message)]
+      end
+
+      def database_source(directory) = local_world(directory) || "world"
+
+      # The copy's own world that can supply the database: `environments/local.world`, else a
+      # `<bluebook>.local.world` beside the domain or in the working directory.
+      def local_world(directory)
+        return "environments/local.world" if File.exist?(File.join(directory, "environments", "local.world"))
+
+        found = [directory, Dir.pwd].uniq.flat_map { |where| Dir[File.join(where, "*.local.world")] }.first
+        found && File.basename(found)
+      end
+
+      def declared_database(directory)
+        registry = Hecks.describe(directory).registry
+        name = registry.first_domain_name
+        name && registry.default_database_for(name)
+      end
+
+      def first_line(text) = text.to_s[FIRST_LINE].strip
+
+      # Whether this copy may migrate its database to a newer storage shape, and whether the world
+      # says so or the default does.
+      def mint_eras(directory)
+        registry = Hecks.describe(directory).registry
+        declared = registry.binding_settings(registry.first_domain_name, Ports::Persistence::VERB, "PostgresEra")
+        ["mint eras", mint_wording(declared), declared.key?(:mint_eras) ? "world" : "default"]
+      rescue StandardError => e
+        ["mint eras", "could not be read", first_line(e.message)]
+      end
+
+      def mint_wording(declared)
+        require "hecks/adapters/driven/postgres_era"
+        default = PostgresEra::LineageManager::EraResolver::MINT_BY_DEFAULT
+        [true, "true"].include?(declared.fetch(:mint_eras, default)) ? "allowed" : "refused"
+      end
+
+      def schema
+        return ["schema", ENV.fetch("HECKS_SCHEMA"), "variable HECKS_SCHEMA"] unless ENV.fetch("HECKS_SCHEMA", "").empty?
+
+        ["schema", "the world's, else one derived from the domain's name", "default"]
+      end
+
+      def project_environment
+        named = ENV.fetch("HECKS_PROJECT_ENVIRONMENT", "")
+        return ["project environment", "none", "default"] if named.empty?
+
+        ["project environment", named, "variable HECKS_PROJECT_ENVIRONMENT"]
+      end
+
+      def usage_cache_directory
+        require "hecks/adapters/driving/usage_cache"
+        Hecks::Adapters::Driving::UsageCache.directory
+      end
+
+      def registry_source(directory)
+        require "hecks/embryonaut_bluebook/vendor_cli"
+        found = Hecks::EmbryonautBluebook::VendorCli.default_source(directory)
+        return ["registry source", "none found", "default"] unless found
+
+        named = ENV.fetch("EMBRYONAUT_BLUEBOOKS_SRC", nil)
+        ["registry source", found, named ? "variable EMBRYONAUT_BLUEBOOKS_SRC" : "beside the project"]
+      end
+
+      def variable_or_default(name, variable, value)
+        [name, value, ENV.fetch(variable, nil) ? "variable #{variable}" : "default"]
+      end
+
+      def deprecated
+        set = RETIRED.select { |name| ENV.fetch(name, nil) }
+        set.empty? ? [] : ["retired variables set, and ignored: #{set.join(", ")}"]
+      end
+
+      def hide_password(url) = url.to_s.gsub(PASSWORD, '\1:***@')
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

data/lib/hecks/hecks/adapters/shell.rb

@@ -21,6 +21,9 @@ module Hecks
       Result = Struct.new(:out, :err, :status) do
         # @return [Boolean] whether the program ended with status 0
         def ok? = status.success?
+
+        # @return [Integer, nil] the status the program ended with, or nil when a signal ended it
+        def exit_code = status.exitstatus
       end
 
       # Accepts the arguments every driven adapter is built with and keeps none of them.

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -131,9 +131,9 @@ module Hecks
 
       # The project's checked edge, read the way `project_site` reads it.
       def edge_of(root, template = nil)
-        registry, chapter, table = read_table(root)
+        registry, declaration, table = read_table(root)
         site = Projections::Site
-        site::Edge.read(chapter, table: table, template: template, vocabulary: site::Table.vocabulary(registry)) ||
+        site::Edge.read(declaration, table: table, template: template, vocabulary: site::Table.vocabulary(registry)) ||
           raise(ConsoleCapture::Failure, "#{root} declares no Edge rows")
       end
 
@@ -149,11 +149,11 @@ module Hecks
         registry
       end
 
-      # The registry, chapter and checked table of the project at `root`.
+      # The registry, bluebook and checked table of the project at `root`.
       def read_table(root)
         registry = registry_of(root)
-        chapter = Projections::Site::Table.chapter(registry)
-        [registry, chapter, Projections::Site::Table.read(chapter, registry: registry)]
+        declaration = Projections::Site::Table.declaration(registry)
+        [registry, declaration, Projections::Site::Table.read(declaration, registry: registry)]
       rescue Projections::Site::Table::Invalid => e
         raise ConsoleCapture::Failure, e.message
       end
@@ -164,7 +164,7 @@ module Hecks
         text = file ? read_saved(file) : fetch(id)
         JSON.parse(text)
       rescue JSON::ParserError => e
-        raise ConsoleCapture::Failure, "the live configuration is not JSON: #{e.message.lines.first.strip}"
+        raise ConsoleCapture::Failure, "the live configuration is not JSON: #{Text.first_line(e.message)}"
       end
 
       def read_saved(path)
@@ -181,11 +181,11 @@ module Hecks
         raise ConsoleCapture::Failure, "aws cloudfront get-distribution-config failed: #{message_of(result)}"
       end
 
-      def words(argument) = plain(argument).to_s.split(",").map(&:strip).reject(&:empty?)
+      def words(argument) = Text.comma_list(plain(argument))
 
       def message_of(result)
         text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
-        text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text
+        text.empty? ? "the tool ended with status #{result.exit_code}" : text
       end
 
       # The tool runs from the tool's own root, so a path the caller gave relative to where they

data/lib/hecks/hecks/adapters/world_clearing.rb

@@ -56,7 +56,8 @@ module Hecks
       # @return [String] the sentence as comment lines inside the block, folded under 100 columns
       def self.comment(indent, note)
         width = 96 - indent.size
-        note.scan(/(.{1,#{width}})(?:\s+|\z)/).flatten.map { |line| "#{indent}  # #{line}\n" }.join
+        lines = note.scan(/(.{1,#{width}})(?:\s+|\z)/).flatten
+        lines.map { |line| "#{indent}  # #{line}\n" }.join
       end
 
       private_class_method :empty, :note, :comment

data/lib/hecks/hecks/agents.bluebook

@@ -0,0 +1,246 @@
+Hecks.bluebook "Hecks" do
+  # Agents: handing one brief to a background Claude session (ADR 0141). A dispatch is a run like
+  # the Custodian `*Run`s: it is requested, the outside is asked, and what came back is judged by
+  # the givens and reactions below.
+  #
+  # The bluebook decides everything: a brief must say something, an agent name cannot be mistaken
+  # for a flag, the directory must be one the `Agents` port finds, and a session that reports
+  # `done` or `stopped` has finished while `busy` and `idle` have not. The port only looks and
+  # starts: it finds a directory, starts the session, and reports the state the session is in.
+
+  aggregate "AgentRun" do
+    description "One brief handed to a background Claude session: started and tracked, or refused with the reason."
+
+    attribute :run,       RunKey
+    attribute :repo,      Path
+    attribute :brief,     Brief
+    attribute :agent,     AgentName, optional: true
+    attribute :session,   SessionId, optional: true
+    attribute :condition, Condition, optional: true
+    attribute :refusal,   Report,    optional: true
+    attribute :tidied_at, Moment,    optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, matches: :present
+    end
+
+    # The directory the session works in.
+    value_object "Path" do
+      attribute :value, String, matches: :not_empty
+    end
+
+    # What the session is asked to do. It may span lines; the dispatch refuses one that is blank.
+    value_object "Brief" do
+      attribute :value, String
+    end
+
+    # A custom agent's name. It starts with a letter or digit, so it cannot be taken for a flag.
+    value_object "AgentName" do
+      attribute :value, String, pattern: '\A[A-Za-z0-9][A-Za-z0-9._-]*\z'
+    end
+
+    value_object "SessionId" do
+      attribute :value, String, matches: :present
+    end
+
+    # What a session reported about itself the last time it was asked.
+    value_object "Condition" do
+      attribute :value, String
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # When the outside removed a session, as the port reports it.
+    value_object "Moment" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "refused"
+      transition "Begin"   => "started",  from: "requested"
+      transition "Decline" => "refused",  from: "requested"
+      transition "Finish"  => "finished", from: "started"
+      transition "Tidied"  => "tidied",   from: "finished"
+      mark :terminal, "tidied", "refused"
+    end
+
+    command "Dispatch" do
+      role "Operator"
+      goal "Hand one brief to a background Claude session working in a directory"
+
+      attribute :run,   RunKey, sets: true
+      attribute :repo,  Path, sets: true
+      attribute :brief, Brief, sets: true
+      attribute :agent, AgentName, optional: true, sets: true
+
+      given("a brief says something") { !brief.value.to_s.strip.empty? }
+
+
+      emits AgentRunRequested
+    end
+
+    command "Begin" do
+      role "System"
+      goal "Record the session the directory's agent started"
+
+      reference_to AgentRun
+      attribute :session, SessionId, sets: true
+
+
+      emits AgentRunStarted
+    end
+
+    command "Decline" do
+      role "System"
+      goal "Record why no session was started"
+
+      reference_to AgentRun
+      attribute :refusal, Report, sets: true
+
+
+      emits AgentRunDeclined
+    end
+
+    command "Check", from: "started" do
+      role "Operator"
+      goal "Ask whether a started session is still working"
+
+      reference_to AgentRun
+
+      emits AgentCheckRequested
+    end
+
+    command "Finish" do
+      role "System"
+      goal "Record that the session has ended, and how it ended"
+
+      reference_to AgentRun
+      attribute :condition, Condition, sets: true
+
+
+      emits AgentRunFinished
+    end
+
+    # A finished run's session is removed only when it ended `done`; a session still `working`,
+    # `blocked` or `stopped` is kept, and so is one a person has taken over (the port says so).
+    command "Tidy", from: "finished" do
+      role "Operator"
+      goal "Remove the finished session of one run, unless it is unfinished or a person took it over"
+
+      reference_to AgentRun
+
+      given("the session ended done: a working, blocked or stopped session is kept") { condition.value == "done" }
+
+      emits TidyRequested
+    end
+
+    command "Tidied" do
+      role "System"
+      goal "Record that the session was removed, and when"
+
+      reference_to AgentRun
+      attribute :tidied_at, Moment, sets: true
+
+
+      emits AgentRunTidied
+    end
+
+    command "Retain" do
+      role "System"
+      goal "Record why a finished session was kept"
+
+      reference_to AgentRun
+      attribute :refusal, Report, sets: true
+
+
+      emits AgentRunRetained
+    end
+
+    query "Tidyable" do
+      description "Every finished run, oldest key first; `Tidy` keeps those that did not end done."
+      where(status: "finished")
+      order_by :run
+    end
+
+    query "Running" do
+      description "Every run whose session was started and is not known to have ended, oldest key first."
+      where(status: "started")
+      order_by :run
+    end
+
+    query "Declined" do
+      description "Every run that no session was started for, with the reason."
+      where(status: "refused")
+      order_by :run
+    end
+  end
+
+  # The directory is looked for first, so a brief is never handed to a session that has nowhere to work.
+  policy "LocateTheRepo" do
+    on      "AgentRun.AgentRunRequested"
+    ask     :locate, with: { run: :run }
+  end
+
+  policy "StartWhenTheRepoIsThere" do
+    on      "AgentRun.RepoLocated"
+    ask     :start, with: { run: :run }
+  end
+
+  policy "RecordTheSession" do
+    on      "AgentRun.AgentStarted"
+    trigger AgentRun::Begin, with: { session: :session }
+  end
+
+  policy "RecordTheMissingRepo" do
+    on      "AgentRun.RepoMissing"
+    trigger AgentRun::Decline, with: { refusal: :refusal }
+  end
+
+  policy "RecordTheRefusedStart" do
+    on      "AgentRun.StartRefused"
+    trigger AgentRun::Decline, with: { refusal: :refusal }
+  end
+
+  policy "AskTheSession" do
+    on      "AgentRun.AgentCheckRequested"
+    ask     :examine, with: { run: :run }
+  end
+
+  # The session is looked at before it is removed; the port says whether a person took it over.
+  policy "ReviewBeforeTidy" do
+    on      "AgentRun.TidyRequested"
+    ask     :review, with: { run: :run }
+  end
+
+  policy "RemoveWhenNobodyTookOver" do
+    on      "AgentRun.SessionReviewed"
+    where   { taken_over == false }
+    ask     :remove, with: { run: :run }
+  end
+
+  policy "KeepWhenAPersonTookOver" do
+    on      "AgentRun.SessionReviewed"
+    where   { taken_over != false }
+    trigger AgentRun::Retain, with: { refusal: :note }
+  end
+
+  policy "RecordTheRemoval" do
+    on      "AgentRun.SessionRemoved"
+    trigger AgentRun::Tidied, with: { tidied_at: :removed_at }
+  end
+
+  policy "RecordTheKeptSession" do
+    on      "AgentRun.RemoveRefused"
+    trigger AgentRun::Retain, with: { refusal: :refusal }
+  end
+
+  # `done` and `stopped` are a session's two ways of ending; `busy` and `idle` are not.
+  policy "FinishWhenTheSessionEnded" do
+    on      "AgentRun.SessionChecked"
+    where   { condition == "done" || condition == "stopped" }
+    trigger AgentRun::Finish, with: { condition: :condition }
+  end
+end