hecks 7.0.0 → 7.1.0

data/lib/hecks/hecks/adapters/red_flagging.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "git"
+require_relative "console_capture"
+require_relative "red_flag_marker"
+require_relative "red_flag_report"
+require_relative "red_flag_survey"
+
+module Hecks
+  module Adapters
+    # The `Flagging` port's adapter for `RedFlag`: raises, notes, checks in to and lowers the red
+    # flag of a repository, reads its status, and surveys the latest CI run of main to raise or
+    # lower it. The flag is `RedFlagMarker`'s file; nothing else is touched.
+    class RedFlagging
+      # The CI run id in a report such as `abc: CI run 12 failure; failed jobs: a, b`.
+      RUN_ID = /run (\d+)/
+      # The failed jobs in that report.
+      JOBS = /failed jobs: (.*)\z/
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      # @param tune [Hash] `checkout:` the repository, `clock:` and `runner:` (for a spec)
+      def initialize(aggregate: nil, settings: {}, root: nil, **tune)
+        @tune = tune
+      end
+
+      # @param held [Hash] the `RedFlag` record: `commit`, `detail`, `rows`, `checkout`
+      # @return [Hash{Symbol => Hash}] `outcome:` (`raised` or `noted`) and the flag's facts
+      def hoist(**held)
+        detail = pick(held, :detail, :report).to_s
+        facts = { ci_run: detail[RUN_ID, 1], jobs: detail[JOBS, 1], rows: plain(held[:rows]) }
+        state, flag = marker(held).raise!(commit: pick(held, :commit, :landed).to_s, run: facts)
+        answer(state.to_s, flag, facts)
+      end
+
+      # @param held [Hash] the `RedFlag` record: `session`, `taking`, `checkout`
+      # @return [Hash{Symbol => Hash}] `outcome:` (`checked_in`) and the flag's facts
+      # @raise [ConsoleCapture::Failure] when no flag stands
+      def sign_in(**held)
+        flag = marker(held).check_in!(session: plain(held[:session]).to_s, taking: plain(held[:taking]).to_s)
+        raise ConsoleCapture::Failure, "no red flag stands: nothing to check in to" unless flag
+
+        answer("checked_in", flag, session: plain(held[:session]), taking: plain(held[:taking]))
+      end
+
+      # @param held [Hash] the `RedFlag` record: `checkout`
+      # @return [Hash{Symbol => Hash}] `outcome:` (`cleared`, or `idle` when none stood)
+      def lower(**held)
+        flag = marker(held).clear!
+        flag ? answer("cleared", flag, {}) : { outcome: { value: "idle" }, output: { value: "no red flag was standing" } }
+      end
+
+      # Reads the latest completed CI run of main and raises or lowers the flag to match it.
+      #
+      # @param held [Hash] the `RedFlag` record: `checkout`
+      # @return [Hash{Symbol => Hash}] `outcome:` as {#hoist} and {#lower}, or `idle` while a run is
+      #   still going
+      def survey(**held)
+        seen = RedFlagSurvey.new(runner: @tune[:runner], checkout: checkout(held)).latest
+        return hoist(commit: seen[:commit], detail: seen[:detail]) if seen[:verdict] == :red
+        return lower(**held) if seen[:verdict] == :green
+
+        { outcome: { value: "idle" }, output: { value: seen[:detail] } }
+      end
+
+      # @param held [Hash] `checkout`
+      # @return [Hash{Symbol => String}] `text:` the flag in words, or that none stands
+      def status(**held)
+        flag = marker(held).read
+        { text: flag ? "#{RedFlagReport.new(flag).text}\n" : "main is not flagged\n" }
+      end
+
+      private
+
+      def answer(outcome, flag, facts)
+        { outcome: { value: outcome }, flag: { value: flag["id"] }, commit: { value: flag["commit"].to_s },
+          ci_run: { value: facts[:ci_run].to_s }, jobs: { value: facts[:jobs].to_s }, rows: { value: facts[:rows].to_s },
+          session: { value: facts[:session].to_s }, taking: { value: facts[:taking].to_s } }
+      end
+
+      def marker(held) = RedFlagMarker.new(git_dir(held), **@tune.slice(:clock))
+
+      def git_dir(held)
+        ok = Git.new.capture("rev-parse", "--path-format=absolute", "--git-common-dir", chdir: checkout(held))
+        raise ConsoleCapture::Failure, "#{checkout(held)} is not a repository" unless ok.ok?
+
+        ok.out.strip
+      end
+
+      def checkout(held) = plain(held[:checkout]) || @tune[:checkout] || Dir.pwd
+
+      def pick(held, *keys) = plain(held[keys.find { |key| held.key?(key) }])
+
+      def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+    end
+  end
+end

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

@@ -82,7 +82,12 @@ module Hecks
         def answer(edge, report, refused, unchecked)
           rows, total = Rows.from(refused)
           edge_facts(edge).merge(refused_rows: rows, refusal_total: plain(total), parity: report.parity,
-                                 unchecked: unchecked).merge(report.facts)
+                                 unchecked: unchecked).merge(report.facts).merge(record_facts)
+        end
+
+        # The domain and the ledger watermark the copy held: what a mint's record of this rehearsal names.
+        def record_facts
+          { rehearsed_domain: @subject.bluebook_name, watermark: @store.watermark(@subject) }
         end
 
         def flag(value) = plain(value)

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

@@ -84,7 +84,8 @@ module Hecks
 
         private
 
-        # A split target's "before": its source's held records, fanned out one per key the split names,
+        # A split target's "before": its source's held records, fanned out one per key the split
+        # names,
         # carrying the split's fields (ADR 0166). Nil when the aggregate is not a split target.
         def split_before(edge, aggregate)
           source, split = split_source_for(edge, aggregate)
@@ -100,7 +101,8 @@ module Hecks
           []
         end
 
-        # One target record per source record that carries the split's key, holding the split's fields.
+        # One target record per source record that carries the split's key, holding the split's
+        # fields.
         def fanned_out(held, split)
           fields = split.fields.map(&:to_s)
           held.filter_map do |_id, state|
@@ -120,7 +122,8 @@ module Hecks
           held.filter_map { |_id, state| fanned_row(state, split.keyed_by.to_s, fields) }.to_h
         end
 
-        # One target row keyed by the held record's key, a value object's `value` member when it has one.
+        # One target row keyed by the held record's key, a value object's `value` member when it has
+        # one.
         def fanned_row(state, key, fields)
           value = state[key]
           value = value["value"] if value.is_a?(Hash)

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    class SettingsReading
+      # The `event tap` row of `hecks config`: where the runtime's event tap writes, and whether
+      # the `HECKS_EVENT_TAP` variable, the world or neither says.
+      module EventTapRow
+        # @param directory [String] the domain directory
+        # @return [Array(String, String, String)] the row's name, value and source
+        def event_tap(directory)
+          declared = declared_event_log(directory)
+          return ["event tap", "none declared", "default"] if declared.empty?
+          return ["event tap", "off", "world"] if declared[:path].to_s.empty?
+
+          override = Assembly.event_tap_override
+          source = override ? "variable #{Assembly::EVENT_TAP_VARIABLE}" : "world"
+          ["event tap", Runtime::EventTap.path_for(declared, override) || "off", source]
+        rescue StandardError => e
+          ["event tap", "could not be read", first_line(e.message)]
+        end
+
+        private
+
+        # The Hecks world's `event_log` settings, empty when it declares none.
+        def declared_event_log(directory)
+          world = Hecks.describe(directory).registry.world("Hecks")
+          world&.for_verb(Runtime::EventTap::VERB).to_h
+        end
+      end
+    end
+  end
+end

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

@@ -7,6 +7,7 @@ require_relative "settings_reading/stores"
 require_relative "settings_reading/disposable_ledger"
 require_relative "settings_reading/push_nudge"
 require_relative "settings_reading/test_scope"
+require_relative "settings_reading/event_tap_row"
 require_relative "work_limits"
 
 module Hecks
@@ -30,6 +31,7 @@ module Hecks
       include DisposableLedger
       include PushNudge
       include TestScope
+      include EventTapRow
 
       # The first line of a message.
       FIRST_LINE = /\A[^\n]*/
@@ -62,7 +64,7 @@ module Hecks
          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), *stores(directory)]
+         event_tap(directory), registry_source(directory), *stores(directory)]
       end
 
       def line_of(name, value, source) = "#{name}: #{value} (#{source})"

data/lib/hecks/hecks/codebase.behaviors

@@ -207,12 +207,6 @@ Hecks.behaviors "Codebase" do
     expect emits: %w[ClearCachesRequested TestSuiteExamined TestSuiteAccepted TestSuiteAnswered TestSuiteCompleted]
   end
 
-  test "RefreshRuntimeBaseline refuses a run that is not a number" do
-    tests "RefreshRuntimeBaseline", on: "TestSuiteRun"
-    input from_run: { value: "latest" }, run: { value: "baseline" }
-    expect refused: "must match"
-  end
-
   test "RegenerateLegacyFixtures reports what it would rewrite, and rewrites nothing, without confirm" do
     tests "RegenerateLegacyFixtures", on: "TestSuiteRun"
     input run: { value: "fixtures" }

data/lib/hecks/hecks/custodian.behaviors

@@ -66,7 +66,7 @@ Hecks.behaviors "Custodian" do
   test "Board keeps a checkout that is not there as a faulted push" do
     tests "Board", on: "SendTrain"
     input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" }, confirm: { value: true }
-    expect emits: %w[BoardingRequested TrainRefused PushFaulted]
+    expect emits: %w[BoardingRequested TrainRefused PushFaulted OutcomeUnrecorded]
   end
 
   test "Land keeps a checkout that is not there as a refused landing" do
@@ -101,6 +101,27 @@ Hecks.behaviors "Custodian" do
     expect emits: %w[RetirementRequested RemovalRefused RetirementDeclined]
   end
 
+  test "Discard keeps a checkout that is not there as a spared worktree" do
+    tests "Discard", on: "Landing"
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" },
+          reason: { value: "superseded" }, confirm: { value: true }
+    expect emits: %w[DiscardRequested DiscardRefused DiscardDeclined]
+  end
+
+  test "Discard needs confirm" do
+    tests "Discard", on: "Landing"
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" },
+          reason: { value: "superseded" }
+    expect refused: "discards the branch's commits that main lacks needs --confirm; without it this only reports"
+  end
+
+  test "Discard needs a reason" do
+    tests "Discard", on: "Landing"
+    input run: { value: "evening" }, checkout: { value: "/tmp/hecks-behaviors-absent/checkout" },
+          reason: { value: "" }, confirm: { value: true }
+    expect refused: "a discard says why"
+  end
+
   test "Dispatch keeps a directory that is not there as a declined run" do
     tests "Dispatch", on: "AgentRun"
     input run: { value: "evening" }, repo: { value: "/tmp/hecks-behaviors-absent/repo" }, brief: { value: "say ok" }

data/lib/hecks/hecks/delegate/delegate.bluebook

@@ -7,9 +7,10 @@ Hecks.bluebook "Hecks" do
     # 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.
+    # for a flag, the directory must be one the `Agents` port finds and the agent one it lists, and a
+    # job that reports `done`, `stopped` or `failed` has ended while `working` and `blocked` have
+    # not. The port only looks and starts: it finds the directory and the agents, starts the
+    # session, and reports the state its job is in.
 
     aggregate "AgentRun" do
       description "One brief handed to a background Claude session: started and tracked, or refused with the reason."
@@ -22,6 +23,7 @@ Hecks.bluebook "Hecks" do
       attribute :condition, Condition, optional: true
       attribute :refusal,   Report,    optional: true
       attribute :tidied_at, Moment,    optional: true
+      attribute :detail,    Report,    optional: true
       identified_by :run
 
       value_object "RunKey" do
@@ -61,11 +63,18 @@ Hecks.bluebook "Hecks" do
         attribute :value, String
       end
 
+      # The directory a session works in, written with its trailing slash, so a watch that filters
+      # on a checkout's directory matches the checkout and every worktree under it.
+      value_object "Checkout" 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 "Fail"    => "finished", from: "started"
         transition "Tidied"  => "tidied",   from: "finished"
         mark :terminal, "tidied", "refused"
       end
@@ -107,24 +116,63 @@ Hecks.bluebook "Hecks" do
         emits AgentRunDeclined
       end
 
+      # A check reads the job's own state and records a change as one of the four session events
+      # below; a state that did not change records nothing.
       command "Check", from: "started" do
         role "Operator"
-        goal "Ask whether a started session is still working"
+        goal "Read the state a started session's job is in, and record it when it changed"
 
         reference_to AgentRun
 
         emits AgentCheckRequested
       end
 
+      command "Work", from: "started" do
+        role "System"
+        goal "Record that the session is working"
+
+        reference_to AgentRun
+        attribute :condition, Condition, sets: true
+        attribute :checkout,  Checkout
+
+        emits SessionWorking
+      end
+
+      command "Block", from: "started" do
+        role "System"
+        goal "Record that the session waits on a person, and the question it waits on"
+
+        reference_to AgentRun
+        attribute :condition, Condition, sets: true
+        attribute :detail,    Report, sets: true
+        attribute :checkout,  Checkout
+
+        emits SessionBlocked
+      end
+
+      # `done` and `stopped` are a session's two ways of ending well; `failed` is `Fail`.
       command "Finish" do
         role "System"
         goal "Record that the session has ended, and how it ended"
 
         reference_to AgentRun
         attribute :condition, Condition, sets: true
+        attribute :detail,    Report, sets: true
+        attribute :checkout,  Checkout
 
+        emits SessionFinished
+      end
+
+      command "Fail" do
+        role "System"
+        goal "Record that the session failed, and what it said"
 
-        emits AgentRunFinished
+        reference_to AgentRun
+        attribute :condition, Condition, sets: true
+        attribute :detail,    Report, sets: true
+        attribute :checkout,  Checkout
+
+        emits SessionFailed
       end
 
       # A finished run's session is removed only when it ended `done`; a session still `working`,
@@ -181,6 +229,28 @@ Hecks.bluebook "Hecks" do
       end
     end
 
+    # One check of every run still started, for a driver that watches sessions. The launcher also
+    # answers it as `agent_run.check_all!`.
+    aggregate "SessionSweep" do
+      description "One check of every started run's session: each change of state is recorded on its run."
+
+      attribute :run, SweepKey
+      identified_by :run
+
+      value_object "SweepKey" do
+        attribute :value, String, matches: :present
+      end
+
+      command "CheckAll" do
+        role "Operator"
+        goal "Check every run whose session was started and is not known to have ended"
+
+        attribute :run, SweepKey, sets: true
+
+        emits SweepRequested
+      end
+    end
+
     # Filling the Work queue is one run too: the Work rows that may start a session now are chosen
     # from the queue, the machine's load and the freeze, and without `confirm` that is all it does.
     # The choosing and the starting are the port's; whether a start is allowed stays with `Work`.
@@ -292,16 +362,33 @@ Hecks.bluebook "Hecks" do
       ask     :locate, with: { run: :run }
     end
 
-    policy "StartWhenTheRepoIsThere" do
+    # Locating the directory also says whether its `claude` lists the named agent, so a name it
+    # does not know is refused before a session is started; with no agent named, the session runs
+    # `claude`'s default. One look, not two: the reactions after a start stay within the depth limit.
+    policy "StartWhenTheAgentIsListed" do
       on      "AgentRun.RepoLocated"
+      where   { listed != false }
       ask     :start, with: { run: :run }
     end
 
+    policy "RecordTheUnlistedAgent" do
+      on      "AgentRun.RepoLocated"
+      where   { listed == false }
+      trigger AgentRun::Decline, with: { refusal: :note }
+    end
+
     policy "RecordTheSession" do
       on      "AgentRun.AgentStarted"
       trigger AgentRun::Begin, with: { session: :session }
     end
 
+    # A session can die within seconds of its start (an agent that fails to load). Its job is read
+    # once the port has let it settle, so a dead session is recorded failed, never left started.
+    policy "ReadTheNewSession" do
+      on      "AgentRun.AgentRunStarted"
+      ask     :await_job, with: { run: :run }
+    end
+
     policy "RecordTheMissingRepo" do
       on      "AgentRun.RepoMissing"
       trigger AgentRun::Decline, with: { refusal: :refusal }
@@ -312,9 +399,42 @@ Hecks.bluebook "Hecks" do
       trigger AgentRun::Decline, with: { refusal: :refusal }
     end
 
-    policy "AskTheSession" do
+    policy "ReadTheJob" do
       on      "AgentRun.AgentCheckRequested"
-      ask     :examine, with: { run: :run }
+      ask     :read_job, with: { run: :run }
+    end
+
+    # Each check is addressed by the row's key alone: the sweep's own `run` is not passed on.
+    policy "CheckEveryStartedRun" do
+      on       "SessionSweep.SweepRequested"
+      for_each "AgentRun.Running"
+      trigger  AgentRun::Check, with: { agent_run: :agent_run }
+    end
+
+    # A job's state becomes an event only when it differs from the state the run last recorded
+    # (`previous`), so a check that finds nothing new records nothing.
+    policy "RecordTheWorkingSession" do
+      on      "AgentRun.JobRead"
+      where   { state == "working" && previous != state }
+      trigger AgentRun::Work, with: { condition: :state, checkout: :checkout }
+    end
+
+    policy "RecordTheBlockedSession" do
+      on      "AgentRun.JobRead"
+      where   { state == "blocked" && previous != state }
+      trigger AgentRun::Block, with: { condition: :state, detail: :detail, checkout: :checkout }
+    end
+
+    policy "RecordTheEndedSession" do
+      on      "AgentRun.JobRead"
+      where   { (state == "done" || state == "stopped") && previous != state }
+      trigger AgentRun::Finish, with: { condition: :state, detail: :detail, checkout: :checkout }
+    end
+
+    policy "RecordTheFailedSession" do
+      on      "AgentRun.JobRead"
+      where   { state == "failed" && previous != state }
+      trigger AgentRun::Fail, with: { condition: :state, detail: :detail, checkout: :checkout }
     end
 
     # The session is looked at before it is removed; the port says whether a person took it over.
@@ -344,12 +464,5 @@ Hecks.bluebook "Hecks" 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
 end