samagotchi 0.91.0 → 0.92.0

data/lib/samagotchi/worker.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "securerandom"
 
 require_relative "client_id"
 require_relative "config"
@@ -16,6 +15,7 @@ require_relative "worker_idle_exit"
 require_relative "worker_wakes"
 require_relative "worker_inbound"
 require_relative "worker_signals"
+require_relative "worker_task_wakes"
 require_relative "session_manager"
 require_relative "archive_store"
 require_relative "log"
@@ -32,8 +32,6 @@ require_relative "child_reports"
 require_relative "child_move"
 require_relative "context_absorber"
 require_relative "context_poller"
-require_relative "kernel_loop"
-require_relative "task_finish_note"
 require_relative "task_watch"
 require_relative "tools/task_runtime"
 
@@ -248,7 +246,7 @@ module Samagotchi
       # a command queued mid-turn (/thinking, /model, /llm-context) changes
       # what it starts with: no turn-end warm-up then.
       @engine.next_turn_waiting = lambda {
-        !@command_queue.empty? || SessionInbox.find_new_input_files(@session_dir).any? || wake_due? || task_wake_due?
+        !@command_queue.empty? || SessionInbox.find_new_input_files(@session_dir).any? || wake_due? || @task_wakes.due?
       }
       @turn_flow = TurnFlow.new(engine: @engine)
       # Its question's answer is queued as the matching /continue (the
@@ -266,7 +264,10 @@ module Samagotchi
       @turn_end_seq = 0
       # The background tasks this session started and hasn't seen finish:
       # one that finishes unseen wakes the idle session (#run_task_wake).
-      @task_watch = TaskWatch.new
+      @task_wakes = WorkerTaskWakes.new(engine: @engine, session: @session, wakes: @wakes,
+                                        awaiting_continue: -> { @turn_flow.awaiting_continue? },
+                                        idle: -> { nothing_queued? && !@exit_requested },
+                                        save: -> { save_or_log(:task_notes) { save_session } })
       @engine.subscribe(observer: lambda { |event|
         if Events::TURN_END.include?(event[:type])
           @turn_end_seq = event[:event_seq]
@@ -278,7 +279,7 @@ module Samagotchi
           @turn_ending = false
         end
         ring_question(event) if event[:type] == :question_requested
-        watch_tasks(event)
+        @task_wakes.observe(event)
       })
       # This session's own delegate children's news (rings in children/).
       @child_reports = ChildReports.new(session_id: @session_id, state_dir: @state_dir,
@@ -327,8 +328,11 @@ module Samagotchi
         awaiting_continue: -> { @turn_flow.awaiting_continue? },
         running_tasks: -> { Tools::TaskRuntime.running_created_in(@engine.messages_checkpoint) },
         # Only when a finish would wake the session (D3): with queue its end
-        # is just a note, not worth keeping the worker up for.
-        watched_tasks: -> { TaskWatch.mode == "wake" ? @task_watch.running : [] }
+        # is just a note, not worth keeping the worker up for. One that
+        # finished since the pass looked holds too, until the next pass
+        # wakes for it (#run_task_wake).
+        watched_tasks: -> { TaskWatch.mode == "wake" ? @task_wakes.watch.holding : [] },
+        watched_running: -> { TaskWatch.mode == "wake" ? @task_wakes.watch.running : [] }
       )
     end
 
@@ -531,26 +535,14 @@ module Samagotchi
     # A turn nobody typed for a changed source (a context wake): a continue
     # turn from context:<name> whose first message is the wake note already
     # in the conversation (named by +turn_id+), on the same rules as a
-    # delegate report's wake turn: it counts toward session.max_wakes (a
-    # peer's answer toward context.peer_turns too, unless it agrees), and a failure goes back
-    # to before the turn (the note stays, as a plain one:
-    # WorkerInbound#unmark_wake) and pauses wakes until a human's input.
+    # delegate report's wake turn (#run_wake): it counts toward
+    # session.max_wakes (a peer's answer toward context.peer_turns too,
+    # unless it agrees).
     # +context_wake+: a WorkerInbound::ContextWake.
     def run_context_wake_turn(context_wake)
       name = context_wake.name
       Log.info(:worker, "context_wake_turn", name: name, in_a_row: @wakes.count!(peer: context_wake.peer_turn?))
-      @turn_flow.before_prompt_turn
-      run_engine_turn(nil, continue: true, origin: context_wake.origin,
-                           id: context_wake.turn_id, max_iterations: IterationLimit.for) do |result, error|
-        if error
-          kept = @turn_flow.prompt_turn_failed(error: error, wake: "the change in attached context #{name}") == :kept
-          # A turn that got somewhere stays, its wake mark with it.
-          @inbound.unmark_wake(context_wake) unless kept
-          @wakes.pause!
-        else
-          @continue_offer.after_turn(result)
-        end
-      end
+      run_wake(origin: context_wake.origin, failed: "the change in attached context #{name}", mark: context_wake)
     end
 
     # The first prompt (spawn_session's): a delegate child's task, which is
@@ -572,7 +564,7 @@ module Samagotchi
       # A first turn sees the context attached before it, and any turn the
       # background tasks that finished since the last look.
       absorb_context(before_turn: true)
-      absorb_task_notes
+      @task_wakes.absorb
       user_input(origin&.dig(:client_id))
       @continue_offer.drop(origin)
       @turn_flow.before_prompt_turn
@@ -640,177 +632,68 @@ module Samagotchi
 
       @wakes.hand_over(reports)
       Log.info(:worker, "delegate_wake_turn", reports: reports.size, in_a_row: @wakes.count!)
-      @turn_flow.before_prompt_turn
-      restores = @turn_flow.restores
-      run_engine_turn(nil, continue: true, origin: reports.first.origin, max_iterations: IterationLimit.for) do |result, error|
-        if error
-          # Rolled back, the rings stay (settle_child_reports): the user's
-          # next turn takes them. A turn that got somewhere stays, and read them.
-          @turn_flow.prompt_turn_failed(
-            error: error, wake: reports.size == 1 ? "a delegate's report" : "#{reports.size} delegate reports",
-            wake_kept: "chi keeps #{reports.size == 1 ? "the report and brings it" : "the reports and brings them"} " \
-                       "again with the user's next message."
-          )
-          @wakes.pause!
-        else
-          @continue_offer.after_turn(result)
-          # Stopped before it got anywhere (a Stop or a before_turn hook's
-          # cancel before the model call) and restored: its rings stay, and
-          # wait for the user's next message as after a failure, rather
-          # than waking again at once.
-          @wakes.pause! if result.canceled? && @turn_flow.restores != restores
-        end
-      end
+      # Rolled back, the rings stay (settle_child_reports): the user's next
+      # turn takes them. A turn that got somewhere stays, and read them.
+      run_wake(origin: reports.first.origin,
+               failed: reports.size == 1 ? "a delegate's report" : "#{reports.size} delegate reports",
+               kept: "chi keeps #{reports.size == 1 ? "the report and brings it" : "the reports and brings them"} " \
+                     "again with the user's next message.")
       true
     ensure
       @wakes.drop_handed
     end
 
-    # The Engine's raw events feed the task watch (session.task_wakes not
-    # off): a result that started a task or showed its end, a turn's start,
-    # a user's Stop of it (M5).
-    def watch_tasks(event)
-      case event[:type]
-      when :tool_call_completed then @task_watch.observe(event) unless TaskWatch.mode == "off"
-      when :turn_started then @task_watch.turn_started
-      when :turn_canceled then @task_watch.turn_canceled(event[:cancellation_reason])
-      end
-    end
-
-    # Whether a finished task would start a wake turn now: the Engine skips
-    # the turn-end warm-up then (next_turn_waiting).
-    def task_wake_due?
-      TaskWatch.mode == "wake" && @task_watch.any? && @wakes.task_open?(awaiting_continue: @turn_flow&.awaiting_continue?) &&
-        @task_watch.finished?
-    end
-
-    # The background tasks this session started that finished unseen
-    # (TaskWatch#take_finished), each as a TASK FINISHED note
-    # (TaskFinishNote): the first one not note-only starts a wake turn from
-    # task:<id> when session.task_wakes is wake, nothing is queued, no exit
-    # was asked for and the wake budget is open (WorkerWakes#task_open?);
-    # the others, and every one otherwise, are plain notes for the next
-    # turn (M2). A spent budget is announced once.
-    # @return [Boolean] whether a wake turn ran
-    def run_task_wake
-      return false if @wakes.in_grace? || !@task_watch.any?
-
-      finished = take_finished_tasks
-      return false if finished.empty?
-
-      waking = finished.find { |entry, _| !entry.note_only } if task_wake_open?
-      task_wake = note_finished_tasks(finished, waking: waking)
-      return false if task_wake == :failed
-
-      save_or_log(:task_notes) { save_session }
-      unless task_wake
-        task_budget_notice(finished.count { |entry, _| !entry.note_only }) if TaskWatch.mode == "wake" && @wakes.spent?
-        return false
-      end
-
-      run_task_wake_turn(task_wake)
-      true
-    end
-
-    # Before a prompt's turn: the finished tasks join it as plain notes.
-    def absorb_task_notes
-      return unless @task_watch.any?
-
-      finished = take_finished_tasks
-      return if finished.empty?
-      return if note_finished_tasks(finished) == :failed
-
-      save_or_log(:task_notes) { save_session }
-    end
-
-    # Each finished task's note into the conversation: +waking+'s as the
-    # wake turn's start, the others plain. A note that can't be written (a
-    # log that can't be read, say) puts it and the ones after it back in
-    # the watch for the next look.
-    # @return [WorkerInbound::TaskWake, nil, :failed]
-    def note_finished_tasks(finished, waking: nil)
-      written = []
-      (finished - [waking]).each do |entry, record|
-        add_task_note(entry, record)
-        written << entry
-      end
-      waking && add_task_wake_note(*waking)
-    rescue StandardError => e
-      Log.warn(:worker, "task_note_failed", error: e.class.name, msg: e.message)
-      @task_watch.put_back(finished.map(&:first) - written)
-      :failed
-    end
-
-    # Only the tasks the conversation still holds (a !rollback, a restored
-    # turn may have dropped the result that started one). A failure to
-    # read them is logged: they wait for the next look.
-    def take_finished_tasks
-      @task_watch.take_finished(keep: Tools::TaskRuntime.created_ids_in(@engine.messages_checkpoint))
-    rescue StandardError => e
-      Log.warn(:worker, "task_watch_failed", error: e.class.name, msg: e.message)
-      []
-    end
-
-    def task_wake_open?
-      TaskWatch.mode == "wake" && nothing_queued? && !@exit_requested &&
-        @wakes.task_open?(awaiting_continue: @turn_flow.awaiting_continue?)
-    end
-
-    def task_note(entry, record, wake:, turn_id: nil)
-      TaskFinishNote.note(record, limit_sec: entry.limit_sec, wake: wake, turn_id: turn_id,
-                                  cap: KernelLoop.resolve_output_char_cap(nil))
-    end
-
-    def add_task_note(entry, record)
-      @engine.add_context_note(@session, task_note(entry, record, wake: false))
-    end
-
-    # The wake note, in the conversation as the wake turn's first message
-    # (before TurnFlow#before_prompt_turn, so a restore keeps it).
-    # @return [WorkerInbound::TaskWake]
-    def add_task_wake_note(entry, record)
-      turn_id = SecureRandom.uuid
-      @engine.add_context_note(@session, task_note(entry, record, wake: true, turn_id: turn_id))
-      WorkerInbound::TaskWake.new(ids: [entry.id], turn_id: turn_id, plain_note: task_note(entry, record, wake: false))
-    end
-
-    # A turn nobody typed for a finished task: a continue turn from
-    # task:<id> whose first message is the wake note, on the delegate wake's
-    # rules (counted toward session.max_wakes). A failure that kept nothing,
-    # or a Stop that restored the conversation, leaves the note as a plain
-    # one (WorkerInbound#unmark_wake) and pauses wakes until a human's input (M4).
-    def run_task_wake_turn(task_wake)
-      Log.info(:worker, "task_wake_turn", task_id: task_wake.ids.first, in_a_row: @wakes.count!)
+    # A wake turn (a delegate report's, an attached context change's, a
+    # finished task's): a continue turn nobody typed, from +origin+. A
+    # failure goes back to before the turn and pauses wakes until a human's
+    # input (a provider outage doesn't loop); so does a Stop before it got
+    # anywhere (a Stop or a before_turn hook's cancel before the model
+    # call, restored by TurnFlow), rather than waking again at once. Either
+    # way +mark+ (a WorkerInbound::ContextWake or TaskWake: its wake note,
+    # the turn's first message) goes back to a plain note
+    # (WorkerInbound#unmark_wake), unless the failed turn kept its steps.
+    # +failed+ names the wake in the failed turn's note, +kept+ says what
+    # happens to it (TurnFlow#prompt_turn_failed).
+    def run_wake(origin:, failed:, kept: nil, mark: nil)
       @turn_flow.before_prompt_turn
       restores = @turn_flow.restores
-      run_engine_turn(nil, continue: true, origin: task_wake.origin, id: task_wake.turn_id,
+      run_engine_turn(nil, continue: true, origin: origin, id: mark&.turn_id,
                            max_iterations: IterationLimit.for) do |result, error|
         if error
-          kept = @turn_flow.prompt_turn_failed(
-            error: error, wake: "a finished background task (#{task_wake.name.delete_prefix("task ")})",
-            wake_kept: "Its note stays for the user's next message."
-          ) == :kept
-          @inbound.unmark_wake(task_wake) unless kept
+          steps_kept = @turn_flow.prompt_turn_failed(error: error, wake: failed, wake_kept: kept) == :kept
+          @inbound.unmark_wake(mark) if mark && !steps_kept
           @wakes.pause!
         else
           @continue_offer.after_turn(result)
           if result.canceled? && @turn_flow.restores != restores
-            @inbound.unmark_wake(task_wake)
+            @inbound.unmark_wake(mark) if mark
             @wakes.pause!
           end
         end
       end
     end
 
-    # The wake budget is spent: the UIs hear once that finished tasks wait
-    # as notes (one notice per stretch, shared with the other kinds).
-    def task_budget_notice(count)
-      return unless count.positive? && @wakes.notice_budget!
+    # The background tasks this session started that finished unseen, as
+    # notes (WorkerTaskWakes#take), and the wake turn the first one may
+    # start.
+    # @return [Boolean] whether a wake turn ran
+    def run_task_wake
+      task_wake = @task_wakes.take
+      return false unless task_wake
 
-      @engine.announce(type: :hook_notice, hook: "task", level: :info, between_turns: true,
-                       text: "#{count} finished background task#{"s" if count != 1} noted; the model reads " \
-                             "#{count == 1 ? "it" : "them"} with your next message " \
-                             "(#{@wakes.max} wake turn#{"s" if @wakes.max != 1} in a row, #{ChildRing::MAX_WAKES_KEY})")
+      run_task_wake_turn(task_wake)
+      true
+    end
+
+    # A turn nobody typed for a finished task: a continue turn from
+    # task:<id> whose first message is the wake note, on the delegate wake's
+    # rules (#run_wake; counted toward session.max_wakes): a failure that
+    # kept nothing, or a Stop that restored the conversation, leaves the
+    # note as a plain one (M4).
+    def run_task_wake_turn(task_wake)
+      Log.info(:worker, "task_wake_turn", task_id: task_wake.id, in_a_row: @wakes.count!)
+      run_wake(origin: task_wake.origin, failed: "a finished background task (#{task_wake.name.delete_prefix("task ")})",
+               kept: "Its note stays for the user's next message.", mark: task_wake)
     end
 
     # The idle loop's sleep: the fallback tick, or less while reports wait
@@ -1067,7 +950,7 @@ module Samagotchi
     # @param confirm [CacheConfirm::Confirm, nil] the change asks first: the
     #   line that applies it (the TUI's prefill, the web's Apply button)
     def announce_command(command, status:, output:, changed:, anytime: false, confirm: nil)
-      TurnCheckpoint.record_command_outcome(@session_dir, command.enqueued_id)
+      TurnCheckpoint.record_command_outcome(@session_dir, command.enqueued_id, status: status)
       text = output.to_s
       event = { type: :command_ran, **command.event_fields, status: status, output: text[0, COMMAND_OUTPUT_LIMIT],
                 changed: changed.map(&:to_s), model_name: @engine.effective_model_name }
@@ -1366,17 +1249,19 @@ module Samagotchi
     # +delete+: the session is deleted after (/exit --delete), so no recap.
     # +restart+: a new worker takes over (on the newest chi installed), so
     # WorkerIdleExit#hold_for_restart's rules, and no recap or discard.
-    # @return [Symbol, Hash, nil] what keeps the worker up ({reason:
-    #   :background_tasks, tasks:} names the watched tasks still running),
-    #   nil when it will leave
+    # @return [WorkerIdleExit::Hold, nil] what keeps the worker up (for
+    #   :background_tasks, the watched tasks still running), nil when it
+    #   will leave
     def exit_request(client_id, delete: false, restart: false)
       # The Bridge serves before the idle-exit policy exists.
-      return :starting unless @idle_exit
+      return WorkerIdleExit::Hold.new(reason: :starting) unless @idle_exit
 
       hold = restart ? @idle_exit.hold_for_restart : @idle_exit.hold_for_request(requester: client_id)
-      # /exit names the tasks it waits for (D3).
-      return { reason: hold, tasks: @task_watch.running, hint: TASK_STOP_HINT } if hold == :background_tasks && !restart
-      return hold if hold
+      if hold == :background_tasks && !restart
+        # /exit names the tasks it waits for (D3).
+        return WorkerIdleExit::Hold.new(reason: hold, tasks: @task_wakes.watch.running, hint: TASK_STOP_HINT)
+      end
+      return WorkerIdleExit::Hold.new(reason: hold) if hold
 
       @exit_requested = true
       @exit_requested_by = client_id
@@ -1423,10 +1308,17 @@ module Samagotchi
     # A restart keeps even an empty session (a new worker takes it over at
     # once) and leaves the recap to the conversation's next real pause.
     def left(result)
+      deleting = result == :exit_requested && @exit_deletes
+      # The watch goes with this process: a task that finished since the
+      # last look (nothing held the exit for it: queue, a note-only task,
+      # /exit) is a plain note for the next turn, not lost. Not into a
+      # session /exit --delete deletes next: its save could land after the
+      # delete and write the session back.
+      @task_wakes.absorb unless deleting
       return result if result == :restart
 
       @discard = empty_session?
-      write_recap_on_leave unless @discard || (result == :exit_requested && @exit_deletes)
+      write_recap_on_leave unless @discard || deleting
       result
     end
 

data/lib/samagotchi/worker_idle_exit.rb

@@ -14,7 +14,8 @@ module Samagotchi
   #   until the agent cancels them, so an exit would drop them for good;
   # * a continue offer waits for an answer; it too lives only in memory;
   # * a background task the worker watches for a finish wake (TaskWatch)
-  #   still runs: its end would go unnoticed after an exit (D3);
+  #   still runs, or finished and waits for the next pass's wake: its end
+  #   would go unnoticed after an exit (D3);
   # * less than the timeout has passed since the worker started, the Engine's
   #   last activity, or the last client request or disconnect.
   #
@@ -23,6 +24,15 @@ module Samagotchi
   # the timeout and leaves out the asking client's own stream. A restart
   # (POST /exit restart: true) has its own rules, #hold_for_restart.
   class WorkerIdleExit
+    # What keeps the worker up when a client asks it to exit (Worker#exit_request,
+    # the Bridge's 409): +reason+, a #hold_for_request (or #hold_for_restart)
+    # Symbol, or :starting before this policy exists; for :background_tasks
+    # the watched tasks still running ({id:, command:}) and a +hint+ on
+    # stopping them.
+    Hold = Data.define(:reason, :tasks, :hint) do
+      def initialize(reason:, tasks: nil, hint: nil) = super
+    end
+
     # @param engine [Engine] #turn_running?, #last_activity_at, #reminder_store
     # @param bridge [Bridge, nil] #open_streams, #last_client_activity_at; nil
     #   when the worker's Bridge failed to start
@@ -31,11 +41,15 @@ module Samagotchi
     # @param awaiting_continue [#call] true while a continue offer waits
     # @param running_tasks [#call] the background tasks this conversation
     #   started that still run (Tools::TaskRuntime.running_created_in)
-    # @param watched_tasks [#call] the ones a finish wake watches that still
-    #   run (TaskWatch#running): they hold the idle exit and /exit too
+    # @param watched_tasks [#call] the ones a finish wake would wake for,
+    #   running or not yet taken (TaskWatch#holding): they hold the idle exit
+    # @param watched_running [#call] those of them still running
+    #   (TaskWatch#running): they hold /exit (one that finished is a note
+    #   as the worker leaves)
     # @param clock [#call] monotonic seconds, the Engine's and Bridge's clock
     def initialize(engine:, bridge:, timeout_minutes:, input_pending:, awaiting_continue: -> { false },
-                   running_tasks: -> { [] }, watched_tasks: -> { [] }, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+                   running_tasks: -> { [] }, watched_tasks: -> { [] }, watched_running: -> { [] },
+                   clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       @engine = engine
       @bridge = bridge
       @timeout = timeout_minutes.to_f * 60
@@ -43,6 +57,7 @@ module Samagotchi
       @awaiting_continue = awaiting_continue
       @running_tasks = running_tasks
       @watched_tasks = watched_tasks
+      @watched_running = watched_running
       @clock = clock
       @started_at = clock.call
     end
@@ -85,7 +100,7 @@ module Samagotchi
       return :continue_offered if @awaiting_continue.call
       return :client_connected if streams && @bridge && @bridge.open_streams_except(requester).positive?
       return :reminders if @engine.reminder_store&.any?
-      return :background_tasks if @watched_tasks.call.any?
+      return :background_tasks if @watched_running.call.any?
 
       nil
     end

data/lib/samagotchi/worker_inbound.rb

@@ -59,11 +59,11 @@ module Samagotchi
     # A task finish wake turn to run (TaskWatch, TaskFinishNote): its wake
     # note is in the conversation as the start of the turn +turn_id+;
     # +plain_note+ is the same note without the turn start or the ask, which
-    # #unmark_wake puts back after a failed or restored wake turn. +ids+: the
-    # finished tasks it runs for (the first one names it).
-    TaskWake = Data.define(:ids, :turn_id, :plain_note) do
-      def name = "task #{Tools::TaskRecord.short_id(ids.first)}"
-      def origin = { client_id: "#{ClientId::TASK_PREFIX}#{ids.first}" }
+    # #unmark_wake puts back after a failed or restored wake turn. +id+: the
+    # finished task it runs for (the others finished with it are plain notes).
+    TaskWake = Data.define(:id, :turn_id, :plain_note) do
+      def name = "task #{Tools::TaskRecord.short_id(id)}"
+      def origin = { client_id: "#{ClientId::TASK_PREFIX}#{id}" }
       def note = plain_note
     end
 

data/lib/samagotchi/worker_task_wakes.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "child_reports"
+require_relative "kernel_loop"
+require_relative "log"
+require_relative "task_finish_note"
+require_relative "task_watch"
+require_relative "tools/task_runtime"
+require_relative "worker_inbound"
+require_relative "worker_wakes"
+
+module Samagotchi
+  # A worker's finish wake (docs/internals/background-tasks.md, Finish
+  # wake): its TaskWatch, fed by the Engine's raw events (#observe), and
+  # the TASK FINISHED notes for the tasks that finished unseen. #take
+  # writes them and hands back the wake turn to run, which the Worker runs
+  # (Worker#run_wake); #absorb gives them to a prompt's turn as plain notes.
+  # On the loop's thread, like WorkerInbound.
+  class WorkerTaskWakes
+    # @return [TaskWatch]
+    attr_reader :watch
+
+    # @param wakes [WorkerWakes] the wake budget a task's wake asks
+    # @param awaiting_continue [#call] whether a continue offer waits
+    # @param idle [#call] nothing queued and no exit asked for: a finish
+    #   may start a turn
+    # @param save [#call] saves the session (a failure is the callee's to log)
+    def initialize(engine:, session:, wakes:, awaiting_continue:, idle:, save:)
+      @engine = engine
+      @session = session
+      @wakes = wakes
+      @awaiting_continue = awaiting_continue
+      @idle = idle
+      @save = save
+      @watch = TaskWatch.new
+    end
+
+    # The Engine's raw events feed the task watch (session.task_wakes not
+    # off): a result that started a task or showed its end, a turn's start,
+    # a user's Stop of it (M5).
+    def observe(event)
+      case event[:type]
+      when :tool_call_completed then @watch.observe(event) unless TaskWatch.mode == "off"
+      when :turn_started then @watch.turn_started
+      when :turn_canceled then @watch.turn_canceled(event[:cancellation_reason])
+      end
+    end
+
+    # Whether a finished task would start a wake turn now: the Engine skips
+    # the turn-end warm-up then (next_turn_waiting).
+    def due?
+      TaskWatch.mode == "wake" && @watch.any? && @wakes.task_open?(awaiting_continue: @awaiting_continue.call) &&
+        @watch.finished?
+    end
+
+    # The background tasks this session started that finished unseen
+    # (TaskWatch#take_finished), each as a TASK FINISHED note
+    # (TaskFinishNote): the first one not note-only starts a wake turn from
+    # task:<id> when session.task_wakes is wake, nothing is queued, no exit
+    # was asked for and the wake budget is open (WorkerWakes#task_open?);
+    # the others, and every one otherwise, are plain notes for the next
+    # turn (M2). A spent budget is announced once.
+    # @return [WorkerInbound::TaskWake, nil] the wake turn to run now
+    def take
+      return nil if @wakes.in_grace? || !@watch.any?
+
+      finished = take_finished
+      return nil if finished.empty?
+
+      waking = finished.find { |entry, _| !entry.note_only } if wake_open?
+      task_wake = note_finished(finished, waking: waking)
+      return nil if task_wake == :failed
+
+      @save.call
+      return task_wake if task_wake
+
+      budget_notice(finished.count { |entry, _| !entry.note_only }) if TaskWatch.mode == "wake" && @wakes.spent?
+      nil
+    end
+
+    # Before a prompt's turn: the finished tasks join it as plain notes.
+    def absorb
+      return unless @watch.any?
+
+      finished = take_finished
+      return if finished.empty?
+      return if note_finished(finished) == :failed
+
+      @save.call
+    end
+
+    private
+
+    # Each finished task's note into the conversation: +waking+'s as the
+    # wake turn's start, the others plain. A note that can't be written (a
+    # log that can't be read, say) puts it and the ones after it back in
+    # the watch for the next look.
+    # @return [WorkerInbound::TaskWake, nil, :failed]
+    def note_finished(finished, waking: nil)
+      written = []
+      (finished - [waking]).each do |entry, record|
+        add_note(entry, record)
+        written << entry
+      end
+      waking && add_wake_note(*waking)
+    rescue StandardError => e
+      Log.warn(:worker, "task_note_failed", error: e.class.name, msg: e.message)
+      @watch.put_back(finished.map(&:first) - written)
+      :failed
+    end
+
+    # Only the tasks the conversation still holds (a !rollback, a restored
+    # turn may have dropped the result that started one). A failure to
+    # read them is logged and counted (TaskWatch#look_failed: past
+    # TaskWatch::MAX_FAILURES they no longer hold the worker up): they wait
+    # for the next look.
+    def take_finished
+      @watch.take_finished(keep: Tools::TaskRuntime.created_ids_in(@engine.messages_checkpoint))
+    rescue StandardError => e
+      Log.warn(:worker, "task_watch_failed", error: e.class.name, msg: e.message)
+      @watch.look_failed
+      []
+    end
+
+    def wake_open?
+      TaskWatch.mode == "wake" && @idle.call && @wakes.task_open?(awaiting_continue: @awaiting_continue.call)
+    end
+
+    def note(entry, record, wake:, turn_id: nil)
+      TaskFinishNote.note(record, limit_sec: entry.limit_sec, wake: wake, turn_id: turn_id,
+                                  cap: KernelLoop.resolve_output_char_cap(nil))
+    end
+
+    def add_note(entry, record)
+      @engine.add_context_note(@session, note(entry, record, wake: false))
+    end
+
+    # The wake note, in the conversation as the wake turn's first message
+    # (before TurnFlow#before_prompt_turn, so a restore keeps it).
+    # @return [WorkerInbound::TaskWake]
+    def add_wake_note(entry, record)
+      turn_id = SecureRandom.uuid
+      @engine.add_context_note(@session, note(entry, record, wake: true, turn_id: turn_id))
+      WorkerInbound::TaskWake.new(id: entry.id, turn_id: turn_id, plain_note: note(entry, record, wake: false))
+    end
+
+    # The wake budget is spent: the UIs hear once that finished tasks wait
+    # as notes (one notice per stretch, shared with the other kinds).
+    def budget_notice(count)
+      return unless count.positive? && @wakes.notice_budget!
+
+      @engine.announce(type: :hook_notice, hook: "task", level: :info, between_turns: true,
+                       text: "#{count} finished background task#{"s" if count != 1} noted; the model reads " \
+                             "#{count == 1 ? "it" : "them"} with your next message " \
+                             "(#{@wakes.max} wake turn#{"s" if @wakes.max != 1} in a row, #{ChildRing::MAX_WAKES_KEY})")
+    end
+  end
+end

data/lib/samagotchi/worker_wakes.rb

@@ -117,9 +117,6 @@ module Samagotchi
       !@paused && !awaiting_continue && !in_grace? && @in_a_row < max
     end
 
-    # Whether wakes are paused (a failed wake turn) until a human's input.
-    def paused? = @paused
-
     # A wake turn starts; +peer+: for a peer's answer, which counts toward
     # both budgets. @return [Integer] the wake turns in a row now
     def count!(peer: false)