openlanes 3.0.0 → 3.1.0

data/lib/openlanes/execution/prompt.rb

@@ -19,6 +19,16 @@ module OpenLanes
       # whatever release is installed, which can predate `state sign`.
       EXECUTABLE = File.expand_path("../../../exe/openlanes", __dir__)
 
+      # Most journal entries a prompt carries, newest kept. The journal goes
+      # into every round's prompt, resumed or not, so it is paid for in
+      # tokens every round: at {Plans::Journal::TEXT_LIMIT} characters an
+      # entry, 40 is at most about 5k tokens, small beside the agent's own
+      # definition. The newest are the ones kept because a later entry wins
+      # over an earlier one, so what is cut is what was most likely already
+      # overturned or done; the prompt says how many were cut and how to read
+      # them.
+      JOURNAL_LIMIT = 40
+
       # @param agent [OpenLanes::Agents::Agent]
       # @param subject [OpenLanes::Plans::Subject]
       # @param root [String] the checkout the agent works in
@@ -32,8 +42,11 @@ module OpenLanes
       # @param seconds [Integer, nil] the enforced clock
       # @param denied [Array<String>] commands withheld
       # @param granted [Array<String>] commands lifted for this agent
+      # @param rebase [OpenLanes::Vcs::Refresh::Outcome, nil] a rebase stopped
+      #   on conflicts, which this invocation resolves instead of working the plan
       def initialize(agent:, subject:, root:, profile:, round: 1, successor: nil, partners: [], control: nil,
-        instructions: "", max_tokens: nil, fresh_budget: false, seconds: nil, denied: [], granted: [])
+        instructions: "", max_tokens: nil, fresh_budget: false, seconds: nil, denied: [], granted: [], rebase: nil)
+        @rebase = rebase
         @agent = agent
         @subject = subject
         @root = root
@@ -52,6 +65,8 @@ module OpenLanes
 
       # @return [String]
       def to_s
+        return resolution if @rebase
+
         <<~PROMPT
           #{agent.prompt}
 
@@ -65,7 +80,8 @@ module OpenLanes
           Repository root: #{root}
 
           #{"The folder's name is not currently justified: #{subject.violation}" if subject.violation}
-          #{operator_instructions}#{requirements_section}#{completion_section}#{suggestions_section}#{ledger_section(agent, subject, round:, successor:)}#{budget_section}#{time_budget_section(agent)}#{control_section(control, agent, subject)}#{questions_section}#{mailbox_section(agent, subject, partners)}
+          #{snapshot_note}
+          #{operator_instructions}#{requirements_section}#{completion_section}#{suggestions_section}#{journal_section}#{ledger_section(agent, subject, round:, successor:)}#{budget_section}#{time_budget_section(agent)}#{control_section(control, agent, subject)}#{questions_section}#{mailbox_section(agent, subject, partners)}
           ## Boundary — enforced, not requested
 
           You may read anything, and write source, tests and the plan's own
@@ -93,6 +109,77 @@ module OpenLanes
         PROMPT
       end
 
+      # What an agent resolving a stopped rebase is told. Its own definition
+      # comes first, for who it is and what it builds, and so its own
+      # "a rebase stopped" section is read; everything after says this
+      # invocation is not plan work. No ledger section: a signature here would
+      # be read as this round's verdict on the plan, which it is not.
+      #
+      # @return [String]
+      def resolution
+        base = @rebase.base
+        files = @rebase.files.map { "  #{it}" }.join("\n")
+        denied = @denied.map { "  #{it}" }.join("\n")
+        stop = "Your control file is #{control}. Read it between steps: STOP means stage what you resolved and end your turn now."
+        <<~PROMPT
+          #{agent.prompt}
+
+          ---
+
+          ## This invocation: resolve a stopped rebase, and nothing else
+
+          Plan folder    : #{subject.feature.path}
+          Plan number    : #{subject.feature.ordinal}
+          Repository root: #{root}
+
+          The harness rebased this plan's branch onto `#{base}`, so the plan builds
+          on current code, and the rebase stopped on conflicts in:
+
+          #{files}
+
+          This is not plan work. Do not work your plan's units, do not sign the
+          ledger, and do not write `blocked.md`: a conflict is never a question
+          for a person. Do exactly this:
+
+          1. Read what the branch is for (`spec.md` and `plan.md` in the plan
+             folder), the commit being replayed (`git show REBASE_HEAD`), and what
+             landed upstream (`git log --oneline -20 #{base}`).
+          1. Resolve every conflict marker in the files above, keeping the intent
+             of both sides. Where they genuinely contradict each other, favour what
+             landed on `#{base}` and adapt the branch's change to it.
+          1. Record each judgement call, one line per file, with its reason, under
+             `## Rebase decisions` in the plan folder's `plan.md`, so a reviewer
+             sees what was chosen and why.
+          1. Run the tests that cover the files you changed.
+          1. `git add` each file you resolved, then end your turn.
+
+          Never run `git rebase` (`--continue`, `--skip`, `--abort`), `git commit`,
+          or anything else that moves HEAD (`git reset`, `git switch`, `git merge`,
+          `git cherry-pick`, `git checkout <branch>`). The harness continues the
+          rebase after you end; if the next commit conflicts too, you are invoked
+          again for it.
+
+          If you cannot resolve a file, or the tests fail because of the merge and
+          you cannot fix that, leave the file conflicted (`git checkout -m -- <path>`
+          puts the markers back) and end your turn. The harness then hands the
+          rebase on, or aborts it, which restores the branch exactly.
+
+          #{stop if control}
+
+          ## Boundary — enforced, not requested
+
+          #{withheld_preamble(profile)}
+
+          #{denied}
+
+          The harness checks afterwards that HEAD has not moved. Claim each file
+          before you write it, naming yourself:
+
+              AGENT_ID=#{agent.name} alock acquire <path> "<why>"
+              AGENT_ID=#{agent.name} alock release-all
+        PROMPT
+      end
+
       # What a compacted agent is told when its session is resumed (W28). Its
       # own instructions survive in the compacted summary; what it needs is
       # to know that the INTERRUPT it just obeyed is over, and that the
@@ -106,9 +193,9 @@ module OpenLanes
           session and the same round on plan #{subject.feature.ordinal}.
 
           The INTERRUPT you were sent was only to pause you for the compaction.
-          It is over: do not end your turn because of it. Read your RESUME note,
+          It is over: do not end your turn because of it. Read your resume record,
 
-              #{cli} mail read --dir "#{plans_dir}" --plan #{subject.feature.ordinal} --for #{agent.name}
+              #{cli} state show --dir "#{plans_dir}" --plan #{subject.feature.ordinal} | jq '."last-known-state"."#{agent.name}"'
 
           then carry on from its exact next step, as your original instructions
           say, and sign your ledger when the work is done, as before. If you had
@@ -122,6 +209,18 @@ module OpenLanes
 
       attr_reader :agent, :subject, :root, :profile, :round, :successor, :partners, :control
 
+      # In a worktree the repository root holds its own `.plans`, a snapshot
+      # the publisher refreshes for the pull request. An agent that edited or
+      # signed it would be writing to a copy the next publish throws away.
+      #
+      # @return [String, nil]
+      def snapshot_note
+        return nil if File.expand_path(subject.feature.path).start_with?("#{File.expand_path(root)}/")
+
+        "The plan lives only at the plan folder above. Any `.plans` under the repository root is a\n" \
+          "snapshot the harness overwrites when it publishes: never read the plan from it or write to it."
+      end
+
       # Only a CLI that actually refuses the commands may be described as
       # refusing them.
       #
@@ -178,6 +277,80 @@ module OpenLanes
         SECTION
       end
 
+      # The journal (M2): how to keep it, and what it already holds. Said to
+      # every agent, identically, for the same reason as the ledger. What it
+      # holds is put here by the harness, not left for the agent to look up,
+      # so reading it is enforced rather than requested, and a resumed
+      # session, which may have compacted the round that wrote it, gets it too.
+      #
+      # @return [String]
+      def journal_section
+        <<~SECTION
+
+          ## Your journal - record as you go, read before you start
+
+          Keep a journal of this plan, for yourself in later rounds. Record each
+          of these the moment it happens, not at the end, so a round that is
+          killed still leaves everything you printed:
+
+            todo      work you have found that still needs doing
+            done      work you have finished
+            decision  a choice you made, and why
+            question  something you stopped to ask a person
+            override  a decision that overturns an earlier entry, with its number
+            note      anything else you must not forget
+
+          Write nothing to a file and run no command for it. Print each entry in
+          your reply, as one line of JSON on a line of its own; the harness reads
+          your output and keeps it in `state.json`:
+
+              #{Plans::Journal.line("decision", "Store money as integer cents, as the API already does")}
+              #{Plans::Journal.line("override", "Store money as BigDecimal: the spec's B1 answer needs fractions", overrides: 3)}
+
+          Entries are numbered from 1 across all your rounds on this plan, as
+          listed below, and a later entry wins over an earlier one. Keep each to
+          one line under #{Plans::Journal::TEXT_LIMIT} characters.
+          #{journal_so_far}
+        SECTION
+      end
+
+      # @return [String]
+      def journal_so_far
+        rounds = Plans::PlanState.for(subject.feature.path).journal(agent.name)
+        numbered = rounds.flat_map { |r| r.entries.each_with_index.map { |e, i| [r, r.first + i, e] } }
+        return "\nYour journal on this plan is empty: this is your first round to keep one.\n" if numbered.empty?
+
+        overridden = numbered.each_with_object({}) { |(_, n, e), map| map[e.overrides] = n if e.overrides }
+        shown = numbered.last(JOURNAL_LIMIT)
+        cut = numbered.size - shown.size
+        lines = shown.chunk_while { |a, b| a.first.equal?(b.first) }.flat_map do |group|
+          round = group.first.first
+          ["", "  Journal round #{round.number}#{" (#{round.state})" if round.state}:",
+           *group.map { |_, n, e| "    #{n}. #{journal_line(e)}#{"  (overridden by #{overridden[n]})" if overridden[n]}" }]
+        end
+        omitted = if cut.positive?
+                    "\n#{cut} earlier entr#{cut == 1 ? "y is" : "ies are"} not shown; read them with\n\n    " \
+                      "#{cli} state show --dir \"#{File.dirname(subject.feature.path)}\" --plan #{subject.feature.ordinal} " \
+                      "| jq '.memory.\"#{agent.name}\"'\n"
+                  end
+        "\nRead your journal so far before you do anything else. Do not redo what it says is done;\n" \
+          "check the files it names rather than taking it on trust.\n#{lines.join("\n")}\n#{omitted}"
+      rescue OpenLanes::Error
+        "\nYour journal could not be read: state.json is not valid JSON.\n"
+      end
+
+      # @param entry [OpenLanes::Plans::Journal::Entry]
+      # @return [String]
+      def journal_line(entry)
+        label = case entry.kind
+                when "override" then entry.overrides ? "override of #{entry.overrides}" : "override"
+                when "question" then entry.ref ? "question #{entry.ref}" : "question"
+                else entry.kind
+                end
+        answer = entry.answer ? " -> answered: #{entry.answer}" : ""
+        "[#{label}] #{entry.text}#{answer}"
+      end
+
       # The section `run --max-tokens` adds. Stating the number is what lets
       # the agent finish before it, rather than discovering the cap by dying
       # on it with half a file written.
@@ -266,7 +439,13 @@ module OpenLanes
               #{cli} mail read --dir "#{plans_dir}" --plan #{plan} --for #{agent.name}
 
           Pass `--after N`, with the number of the last message you have read,
-          to see only what is new. Write to it when you land an interface your
+          to see only what is new. Right after reading a message addressed to
+          you, ack it by its number, so the page stops warning that it is
+          unread:
+
+              #{cli} mail ack --dir "#{plans_dir}" --plan #{plan} --for #{agent.name} N
+
+          Write to it when you land an interface your
           partner is waiting on, when you amend the contract, when you need
           something from their half, and when you finish:
 
@@ -275,7 +454,7 @@ module OpenLanes
           Every message is appended with a number and a timestamp and never
           edited, so a person can read the exchange after the round. A question
           your partner has not answered within a few steps is not a reason to
-          stop: write your assumption into implementation-plan.md and carry on.
+          stop: write your assumption into contract.md and carry on.
         SECTION
       end
 
@@ -283,9 +462,11 @@ module OpenLanes
       # the advisory clock writes into it whether or not anyone is watching.
       #
       # INTERRUPT is what makes a restart after Ctrl-C safe: the agent that
-      # was cut off leaves a mailbox note to whoever picks the plan up, and
-      # every agent is told to read its mail first, so the next run resumes
-      # from the note rather than redoing work already on disk.
+      # was cut off leaves a resume record (`state resume`, plan 003) for
+      # whoever picks the plan up, and every agent is told to read it first,
+      # so the next run resumes from it rather than redoing work already on
+      # disk. A record, not a mail: fixed fields the next round can act on,
+      # and the harness writes one itself when the agent could not.
       #
       # @param control [String, nil]
       # @param agent [OpenLanes::Agents::Agent]
@@ -307,6 +488,12 @@ module OpenLanes
           finish the essential remainder now. STOP means write what you have,
           sign your ledger entry, and end your turn.
 
+          PAUSE means the run lost touch with the machines it shares work with.
+          Finish the write you are in, start nothing new, and wait: reread this
+          file every thirty seconds until it says anything other than PAUSE.
+          Your time does not run while you wait. RESUME means carry on from
+          where you paused.
+
           HOLD means a person wants to say something to you. Finish the write
           you are in, then read your mail and wait for their next message
           before you do anything else; check every thirty seconds:
@@ -315,30 +502,36 @@ module OpenLanes
 
           INTERRUPT means the operator pressed Ctrl-C and the run will be started
           again later. Start nothing new. Finish the write you are in the middle
-          of, so no file is left half-written, then leave a resume note for
+          of, so no file is left half-written, then leave a resume record for
           whoever runs next — most likely you — saying what is done, what is
-          not, and the exact next step:
+          not, the exact next step and the files you touched:
 
-              #{cli} mail send --dir "#{plans_dir}" --plan #{plan} --from #{agent.name} --to #{agent.name} "RESUME: ..."
+              #{cli} state resume --dir "#{plans_dir}" --plan #{plan} --agent #{agent.name} --round #{round} --done "A,B" --remaining "C" --next-step "..." --files "x.rb,y.rb"
 
           Then sign `--status Interrupted`, with no `--next`, and
           end your turn.
 
-          Before you start, check for such a note from an earlier run:
+          Before you start, check for such a record from an earlier run, and
+          read your mail, where a person may have left a RESUME note:
 
+              #{cli} state show --dir "#{plans_dir}" --plan #{plan} | jq '."last-known-state"."#{agent.name}"'
               #{cli} mail read --dir "#{plans_dir}" --plan #{plan} --for #{agent.name}
 
-          If there is a RESUME note, continue from it and do not redo what it
-          says is done; check the files it names rather than taking it on trust.
+          If there is a record, continue from its next step and do not redo what
+          it says is done; check the files it names rather than taking it on
+          trust. A record whose source is "harness" was written for you after
+          you were stopped: it holds only what the harness saw.
         SECTION
       end
 
-      # How to mark a yes/no question in `blocked.md` (W30). The page offers
-      # Yes and No buttons for exactly the questions marked this way and never
-      # guesses from the wording, so an agent that does not mark one gets a
-      # text box, and one that marks a two-way choice gets a meaningless yes.
-      # Said once here, for every agent that writes `blocked.md`, rather than
-      # in each definition, so the marker cannot drift between them.
+      # How to write a question in `blocked.md` so a person can answer it
+      # with one click (D3): context, then lettered options, one recommended.
+      # The page draws a button per option and always adds a text box, so an
+      # agent that writes the shape gets buttons, and one that does not gets
+      # only the box. Said once here, for every agent that writes
+      # `blocked.md`, rather than in each definition, so the shape cannot
+      # drift between them. {Plans::Choices} reads it, and still reads the
+      # W30 yes/no mark in files written before.
       #
       # @return [String] empty for an agent whose definition never mentions
       #   `blocked.md`, and for the agent that drains it
@@ -347,20 +540,29 @@ module OpenLanes
 
         <<~SECTION
 
-          ## Questions in blocked.md: yes/no questions
+          ## Questions in blocked.md: context, then lettered options
+
+          Write every question for a person in one shape: a short context
+          paragraph saying what you need decided and why, then the options,
+          each on its own line, lettered `a)`, `b)`, `c)`, with exactly one
+          marked `(Recommended)`:
+
+              ## B2 Where the second machine comes from
 
-          When a question can be answered with a plain yes or no, ask it that
-          way and mark it, on its own line straight under its heading:
+              The chat spec needs someone on the other end, and steps 2 to 4 wait on it.
 
-              ## B2 Rebase onto main
-              #{Live::Snapshot::YES_NO_MARK}
+              a) A second demo process on another port, started by just web-e2e. (Recommended)
+              b) The demo answers its own invites. Fewer processes, but the test covers a fake.
+              c) Narrow the spec to steps 1 and 5 and cover the rest in the Ruby suite.
 
-              The pull request conflicts in lib/openlanes/cli.rb. Should I rebase onto main?
+          A yes/no question is `a) yes` and `b) no`. Do not add an option for
+          "something else": the page always offers "Type something instead".
 
           The person answers with a button, and the answer reaches you as the
-          bare word `yes` or `no`, so branch on the word. Mark only a real yes/no
-          question: "Should I start it, or skip the integration specs?" is a
-          choice between two things, and needs words.
+          letter and the option, e.g. `b) The demo answers its own invites. …`,
+          or as the bare word `yes` or `no`; anything else is their own words.
+          A question with no sensible options is a context paragraph alone, and
+          gets a text box.
         SECTION
       end
 
@@ -372,17 +574,17 @@ module OpenLanes
       # @return [String] empty when the spec says neither
       def completion_section
         spec = Plans::Spec.for(subject)
-        return "" if spec.completed_when.empty? && spec.how_to_verify.empty?
+        return "" if spec.completed_when.empty? && spec.how_to_test.empty?
 
-        lists = [["The task is finished when", spec.completed_when], ["How to verify it", spec.how_to_verify]]
+        lists = [["The task is finished when", spec.completed_when], ["How to test it", spec.how_to_test]]
         body = lists.reject { |_, items| items.empty? }.map do |title, items|
-          "#{title}:\n\n#{items.map { |item| "- #{item}" }.join("\n")}\n"
+          "#{title}:\n\n#{items.map { Plans::Spec.list_item(it) }.join("\n")}\n"
         end
 
         "\n## Completion criteria — from the spec's author\n\n" \
           "Do not sign Completed until the first list holds, and run each check in the second. " \
           "If you write plan.md, copy both lists into it verbatim, under `## Task completed when` and " \
-          "`## How to verify`; the harness adds them if you do not. A reviewer rejects work that fails a check.\n\n" \
+          "`#{Lifecycle::Completion::HOW_TO_TEST}`; the harness adds them if you do not. A reviewer rejects work that fails a check.\n\n" \
           "#{body.join("\n")}"
       end
 

data/lib/openlanes/execution/transcript.rb

@@ -57,10 +57,33 @@ module OpenLanes
       # @!attribute [r] session
       #   @return [String, nil] the CLI's session id, from its `init` event,
       #     which is what `--resume` carries the agent on in (W28)
-      Progress = Data.define(:activity, :up, :down, :subagents, :pid, :message, :context, :session) do
-        def initialize(pid: nil, message: nil, context: nil, session: nil, **rest) = super
+      # @!attribute [r] running
+      #   @return [Array<String>] the sub-agents working right now, by name,
+      #     oldest first; empty for a stream that never says (codex, pi)
+      # @!attribute [r] journal
+      #   @return [Array<OpenLanes::Plans::Journal::Entry, OpenLanes::Plans::Journal::Rejection>]
+      #     every journal line (M2) the agent has printed so far, in order. The
+      #     whole list rather than the latest, because a snapshot can be
+      #     skipped by a reader that is busy, and an entry must not be: the
+      #     dispatcher keeps its place in the list and writes what is past it.
+      Progress = Data.define(:activity,
+        :up,
+        :down,
+        :subagents,
+        :pid,
+        :message,
+        :context,
+        :session,
+        :running,
+        :journal) do
+        def initialize(pid: nil, message: nil, context: nil, session: nil, running: [], journal: [], **rest) = super
       end
 
+      # The tools that start a sub-agent. `claude` called it `Task` and renamed
+      # it `Agent`; a transcript that knew only one name would show a run on the
+      # other CLI version with no sub-agents at all.
+      DELEGATES = %w[Task Agent].freeze
+
       # The one kind of line the trace does not keep.
       #
       # `--include-partial-messages` is what makes {#meter} possible, and it
@@ -82,7 +105,7 @@ module OpenLanes
         "Read" => "reading", "Write" => "writing", "Edit" => "editing",
         "MultiEdit" => "editing", "NotebookEdit" => "editing",
         "Bash" => "running", "Grep" => "searching for", "Glob" => "looking for",
-        "Task" => "delegating", "TodoWrite" => "planning",
+        "Task" => "delegating", "Agent" => "delegating", "TodoWrite" => "planning",
         "WebFetch" => "fetching", "WebSearch" => "searching the web for",
         "SendUserMessage" => "saying"
       }.freeze
@@ -114,9 +137,13 @@ module OpenLanes
         @streamed = {}
         @tasks = {}
         @spawned = 0
+        @running = {}
         @context = nil
         @session = nil
         @compacted = nil
+        @journal = []
+        @partial = {}
+        @pending = Hash.new(0)
       end
 
       # Everything sent to the model, which on any turn after the first is
@@ -172,12 +199,25 @@ module OpenLanes
           pid: @pid,
           message: @message,
           context: @context,
-          session: @session)
+          session: @session,
+          running: @running.values,
+          journal: @journal.dup.freeze)
       end
 
+      # The sub-agents started and not yet answered, by name. A count would
+      # have been enough for the meter; the page draws each one beside its
+      # parent, so it needs to know which.
+      #
+      # @return [Array<String>] oldest first
+      def running = @running.values
+
       # @return [String, nil] the session id from the stream's `init` event
       attr_reader :session
 
+      # @return [Array<OpenLanes::Plans::Journal::Entry, OpenLanes::Plans::Journal::Rejection>]
+      #   the journal lines printed so far
+      def journal = @journal.dup
+
       # What a `/compact` reported in its `compact_boundary` event:
       # `pre_tokens`, `post_tokens` and the rest of its `compact_metadata`.
       #
@@ -286,15 +326,78 @@ module OpenLanes
       def handle(event)
         case event["type"]
         when "assistant"
+          grew = capture_journal(event)
           capture_message(event)
           @tools += tool_calls(event)
-          announce(phrase_for(event))
-        when "stream_event" then meter(event)
+          delegate(event)
+          # A journal line is published even when the phrase is the one
+          # already showing: the dispatcher keeps only the snapshots it is
+          # handed, so one held back here is lost if the round is killed
+          # before anything else publishes.
+          published = announce(phrase_for(event))
+          publish if grew && !published
+        when "user" then collect(event)
+        when "stream_event"
+          stream_journal(event)
+          meter(event)
         when "system" then system_event(event)
         when "result" then record_result(event)
         end
       end
 
+      # Journal lines (M2) in the agent's own text. A sub-agent's are left
+      # out: it was not told the format, the journal is its parent's, and a
+      # line it printed reaches the parent as a tool result the parent can
+      # repeat if it matters. Text only, never a tool's input, so a file the
+      # agent writes that happens to hold such a line is not a journal entry.
+      #
+      # @param event [Hash]
+      # @return [Boolean] whether the journal grew
+      def capture_journal(event)
+        return false unless event["parent_tool_use_id"].nil?
+
+        lines = blocks_of(event, "text").flat_map { Plans::Journal.scan(it["text"]) }
+        fresh = lines.reject do |line|
+          next false unless @pending[line].positive?
+
+          @pending[line] -= 1
+          true
+        end
+        @journal.concat(fresh)
+        !fresh.empty?
+      end
+
+      # The finished lines of a text block still being streamed, as they
+      # arrive (`--include-partial-messages`), so an agent killed before the
+      # block's `assistant` event keeps what it printed. {#capture_journal}
+      # then skips them when that event repeats them. Main agent and
+      # `text_delta` only: a sub-agent's text and a tool's input stream too.
+      #
+      # @param event [Hash] a `stream_event`
+      # @return [void]
+      def stream_journal(event)
+        inner = event["event"]
+        return unless event["parent_tool_use_id"].nil? && inner.is_a?(Hash)
+
+        case inner["type"]
+        when "message_start" then @partial = {}
+        when "content_block_start" then @partial[inner["index"]] = { text: +"", taken: 0 }
+        when "content_block_delta"
+          return unless inner.dig("delta", "type") == "text_delta"
+
+          block = (@partial[inner["index"]] ||= { text: +"", taken: 0 })
+          block[:text] << inner.dig("delta", "text").to_s
+          cut = block[:text].rindex("\n") or return
+
+          entries = Plans::Journal.scan(block[:text][0..cut])
+          fresh = entries.drop(block[:taken])
+          block[:taken] = entries.size
+          fresh.each { @pending[it] += 1 }
+          @journal.concat(fresh)
+          publish unless fresh.empty?
+        end
+      end
+
       # `--brief` gives the agent SendUserMessage, and what it sends is the
       # one line on the screen the agent itself chose. It outranks the tool
       # phrase until the agent sends another.
@@ -313,6 +416,50 @@ module OpenLanes
         end
       end
 
+      # A sub-agent is running from the `Task` call that starts it until the
+      # `tool_result` that answers that call. Its name is the `subagent_type`
+      # the call asked for, which is what a person would recognise
+      # ("leah-researcher"), and its `description` only when it named none.
+      # A sub-agent's own calls carry a `parent_tool_use_id` and are read the
+      # same way, so one it starts in turn is a sub-agent too.
+      #
+      # @param event [Hash]
+      # @return [void]
+      def delegate(event)
+        started = blocks_of(event, "tool_use").select { DELEGATES.include?(it["name"]) && it["id"] }
+        return if started.empty?
+
+        started.each do |block|
+          input = block["input"].is_a?(Hash) ? block["input"] : {}
+          name = [input["subagent_type"], input["description"]].map { it.to_s.strip }.find { !it.empty? }
+          @running[block["id"]] = name || "sub-agent"
+        end
+        publish
+      end
+
+      # The `tool_result` that answers a `Task` call is the sub-agent's
+      # return, so it leaves the list there.
+      #
+      # @param event [Hash]
+      # @return [void]
+      def collect(event)
+        done = blocks_of(event, "tool_result").filter_map { it["tool_use_id"] }.select { @running.key?(it) }
+        return if done.empty?
+
+        done.each { @running.delete(it) }
+        publish
+      end
+
+      # @param event [Hash]
+      # @param type [String]
+      # @return [Array<Hash>] the message's content blocks of that type
+      def blocks_of(event, type)
+        blocks = event.dig("message", "content")
+        return [] unless blocks.is_a?(Array)
+
+        blocks.select { it.is_a?(Hash) && it["type"] == type }
+      end
+
       # @param event [Hash]
       # @return [Integer] how many tools this one message called
       def tool_calls(event)
@@ -432,6 +579,9 @@ module OpenLanes
         @error = @result if event["is_error"]
         settle(event["usage"])
         @spawned = [@spawned, event.dig("subagent_stats", "spawned").to_i].max
+        # The invocation is over, so whatever it started is over with it,
+        # answered or not.
+        @running.clear
         publish
       end
 
@@ -512,12 +662,13 @@ module OpenLanes
       end
 
       # @param phrase [String, nil]
-      # @return [void]
+      # @return [Boolean] whether it published
       def announce(phrase)
-        return if phrase.nil? || phrase == @activity
+        return false if phrase.nil? || phrase == @activity
 
         @activity = phrase
         publish
+        true
       end
 
       # Hand the caller a whole snapshot rather than the one field that moved.

data/lib/openlanes/execution.rb

@@ -15,5 +15,26 @@ module OpenLanes
     # @param signals [Array<String>] handled as Ctrl-C is
     # @return [Object] whatever the block returns
     def on_interrupt(signals: %w[INT], &) = Control.on_interrupt(signals, &)
+
+    # `claude` prefers a credential in the environment to a claude.ai login,
+    # so a project `.env` that direnv loads on `cd` can redirect every agent
+    # a run spawns to a key meant for the application itself.
+    #
+    # Said once, before agents start, because the failure arrives three
+    # minutes later, once per agent, and reads like an agent problem rather
+    # than an environment one. Words only: a command or a workflow draws it.
+    #
+    # @return [String, nil] the warning, or nil when no credential shadows the login
+    def credentials_notice
+      names = Executor.foreign_credentials
+      return if names.empty?
+
+      one = names.size == 1
+      "#{names.join(" and ")} #{one ? "is" : "are"} set in this shell, so every agent authenticates " \
+        "with #{one ? "it" : "them"} rather than with your claude.ai login.\n" \
+        "A stale one fails every agent in the run with `401 API key is invalid`, " \
+        "three minutes at a time.\n" \
+        "If it came from a project .env, run `unset #{names.join(" ")}` first."
+    end
   end
 end