samagotchi 0.159.0 → 0.161.0

data/lib/samagotchi/session_continue.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
+require "securerandom"
+require_relative "atomic_file"
 require_relative "session"
 require_relative "session_setup"
 require_relative "session_inbox"
@@ -9,6 +12,7 @@ require_relative "objectives"
 require_relative "child_move"
 require_relative "starting_marker"
 require_relative "context_move"
+require_relative "note_move"
 require_relative "archive_store"
 require_relative "recap_store"
 require_relative "bridge_client"
@@ -56,6 +60,8 @@ module Samagotchi
     RECAP_WAIT = 30.0
     # In the previous link's folder: one continue of a session at a time.
     LOCK = "continue.lock"
+    # A durable record in the previous link's folder, written before archive.
+    CONTINUE_INTENT = "continue.json"
     # How often a last:<id> continue looks again when another continue
     # moved the chain's end while it waited for the lock.
     TRIES = 3
@@ -67,6 +73,29 @@ module Samagotchi
     # (ChildMove::Plan) and the new link's model (ModelChoice).
     Checked = Data.define(:plan, :choice)
 
+    # Repair an interrupted continue before showing sessions or starting
+    # another continue. An active continue holds LOCK, so its intent is left
+    # alone; after a crash, an unsaved successor means the previous link is
+    # unarchived.
+    def self.repair_interrupted(state_dir:)
+      return unless Dir.exist?(state_dir)
+
+      paths = Dir.glob(File.join(state_dir, "*", CONTINUE_INTENT))
+      return if paths.empty?
+
+      sessions = Session.list(state_dir: state_dir, include_archived: true)
+      by_id = sessions.to_h { |session| [session.id, session] }
+      paths.each do |path|
+        id = File.basename(File.dirname(path))
+        session = by_id[id]
+        if session
+          repair_intent(session, state_dir, path, sessions)
+        else
+          quarantine_intent(path, id, message: "session file could not be loaded")
+        end
+      end
+    end
+
     # Start the next link of a chain: a new session that continues
     # +id_or_ref+ (Session#continues) in its folder, on its model (the name
     # it was typed as, so an alias holds) and with its own setup (SessionSetup),
@@ -91,6 +120,9 @@ module Samagotchi
     # @param prompt [String, nil] its first message (nil: it starts idle)
     # @param preview [String, nil] what the lists show before the first turn;
     #   by default the prompt, else the previous link's preview
+    # @param client_id [String, nil] who sends +prompt+ when no person does
+    #   (a schedule's chain firing: ClientId.schedule), the first turn's
+    #   origin (spawn_session's client_id:)
     # @return [Session] the new link (#model_warning as spawn_session's,
     #   #moved_children: the delegates it took over, #moved_context: the
     #   attached context it took (ContextMove), #opener:
@@ -99,8 +131,10 @@ module Samagotchi
     # @raise [Refused] continued already, delegates open that can't
     #   move, or its folder is gone
     # @raise [ArchiveRefused, OwnedByTUI] as archive_session
-    def self.run(id_or_ref, prompt: nil, preview: nil, model: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5)
+    def self.run(id_or_ref, prompt: nil, preview: nil, model: nil, state_dir: nil, recap_wait: RECAP_WAIT, archive_wait: 5,
+                 client_id: nil)
       sd = state_dir || Session.default_state_dir
+      repair_interrupted(state_dir: sd)
       TRIES.times do |try|
         id = SessionChain.resolve(id_or_ref, state_dir: sd)
         result = with_lock(id, sd) do
@@ -108,7 +142,7 @@ module Samagotchi
           next :moved if follow && SessionChain.next_of(id, state_dir: sd)
 
           run_locked(id, prompt: prompt, preview: preview, model: model, state_dir: sd, recap_wait: recap_wait,
-                         archive_wait: archive_wait)
+                         archive_wait: archive_wait, client_id: client_id)
         end
         return result unless result == :moved
       end
@@ -123,7 +157,7 @@ module Samagotchi
       end
     end
 
-    private_class_method def self.run_locked(id, prompt:, preview:, model:, state_dir:, recap_wait:, archive_wait:)
+    private_class_method def self.run_locked(id, prompt:, preview:, model:, state_dir:, recap_wait:, archive_wait:, client_id:)
       previous = Session.load(id, state_dir: state_dir)
       checked = check!(previous, state_dir, model: model)
       plan = checked.plan
@@ -136,24 +170,100 @@ module Samagotchi
       already = [id, *SessionManager.descendant_ids(id, state_dir, except: plan.move)].select do |sid|
         ArchiveStore.archived?(Session.session_dir(sid, state_dir: state_dir))
       end
+      successor_id = SecureRandom.uuid
+      intent_path = continue_intent_path(id, state_dir)
+      intent_data = { successor_id: successor_id, previously_archived: already }
+      AtomicFile.write(intent_path, "#{JSON.generate(intent_data)}\n", perm: 0o600)
       archive = SessionManager.archive_session(id, state_dir: state_dir, wait: archive_wait, except: plan.move)
       archived = archive.archived - already
+      intent_data[:archived_ids] = archived
+      AtomicFile.write(intent_path, "#{JSON.generate(intent_data)}\n", perm: 0o600)
+      # The notes the new link took from this one (NoteMove.move).
+      notes = []
       begin
-        spawn_continuation(previous, prompt: prompt, preview: preview, choice: checked.choice, state_dir: state_dir,
-                                     move: plan.move)
-      rescue StandardError
+        link = spawn_continuation(previous, prompt: prompt, preview: preview, choice: checked.choice, state_dir: state_dir,
+                                  move: plan.move, client_id: client_id, notes: notes, session_id: successor_id)
+      rescue StandardError, Interrupt
         # Nothing started: the delegates go back, what this archived goes
         # back to the lists, and a new link saved before its worker failed
         # to spawn goes (left, it would hold the chain: "continued already",
-        # last: to it).
-        undo_move(id, state_dir, moved: plan.move)
-        begin
-          discard_failed_link(id, state_dir)
-        ensure
-          archived.each { |sid| ArchiveStore.unarchive(sid, state_dir: state_dir) }
-          wake_for_rings(id, state_dir) unless plan.move.empty?
+        # last: to it), its notes given back first.
+        undo_failed_continue(id, state_dir, moved: plan.move, archived: archived) do
+          discard_failed_link(id, state_dir, notes: notes)
         end
+        FileUtils.rm_f(intent_path)
         raise
+      else
+        FileUtils.rm_f(intent_path)
+        link
+      end
+    end
+
+    private_class_method def self.continue_intent_path(id, state_dir)
+      File.join(Session.session_dir(id, state_dir: state_dir), CONTINUE_INTENT)
+    end
+
+    private_class_method def self.repair_intent(session, state_dir, path, sessions)
+      lock_path = File.join(Session.session_dir(session.id, state_dir: state_dir), LOCK)
+      File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+        next unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+        next unless File.file?(path)
+
+        intent = JSON.parse(File.read(path))
+        intent = {} unless intent.is_a?(Hash)
+        successor_id = intent["successor_id"]
+        successor_path = Session.session_file(successor_id, state_dir: state_dir) if Session.valid_id?(successor_id)
+        successor = JSON.parse(File.read(successor_path)) if successor_path && File.file?(successor_path)
+        unless successor.is_a?(Hash) && successor["continues"] == session.id
+          previously_archived = Array(intent["previously_archived"]).select { |id| Session.valid_id?(id) }
+          archived = if intent["archived_ids"].is_a?(Array)
+                       intent["archived_ids"].select { |id| Session.valid_id?(id) }
+                     else
+                       archived_descendants(session.id, sessions, state_dir) - previously_archived
+                     end
+          undo_failed_continue(session.id, state_dir, moved: [], archived: archived)
+        end
+        FileUtils.rm_f(path)
+      end
+    rescue JSON::ParserError => e
+      quarantine_intent(path, session.id, error: e)
+    rescue Errno::ENOENT
+      nil
+    end
+
+    private_class_method def self.quarantine_intent(path, session_id, error: nil, message: nil)
+      File.rename(path, "#{path}.bad")
+      Log.warn(:worker, "continue_repair_failed", sid: session_id, path: path,
+                                                    error: error&.class&.name || "SessionUnavailable",
+                                                    msg: (message || error.message).to_s[0, 200])
+    rescue Errno::ENOENT
+      nil
+    end
+
+    private_class_method def self.archived_descendants(id, sessions, state_dir)
+      children = sessions.group_by(&:parent_id)
+      queue = [id]
+      descendants = []
+      until queue.empty?
+        children.fetch(queue.shift, []).each do |child|
+          next if descendants.include?(child.id)
+
+          descendants << child.id
+          queue << child.id
+        end
+      end
+      [id, *descendants].select do |session_id|
+        ArchiveStore.archived?(Session.session_dir(session_id, state_dir: state_dir))
+      end
+    end
+
+    private_class_method def self.undo_failed_continue(id, state_dir, moved:, archived:)
+      undo_move(id, state_dir, moved: moved)
+      begin
+        yield if block_given?
+      ensure
+        archived.each { |sid| ArchiveStore.unarchive(sid, state_dir: state_dir) }
+        wake_for_rings(id, state_dir) unless moved.empty?
       end
     end
 
@@ -171,10 +281,16 @@ module Samagotchi
     # The link a failed #run saved (no other continues +id+:
     # check! made sure under the lock): its worker stopped if one
     # started, then the rings a moved delegate wrote into it just before
-    # the undo go back to +id+, then the link goes. A worker that outlives
-    # the stop is raised (SessionManager::DeleteRefused): the link stays,
-    # and the caller hears it.
-    private_class_method def self.discard_failed_link(id, state_dir)
+    # the undo go back to +id+. Then its session file goes first, so the
+    # link is out of the chain (a note to +id+ stays there:
+    # SessionInbox::Head) and a writer that resolved it before finds it gone,
+    # then the notes it moved there (+notes+) go back with any sent to it
+    # meanwhile (NoteMove.give_back), then the link's folder goes, and one
+    # last look gives back a note an older chi wrote after the delete
+    # (its write_note recreates the folder). A worker that outlives the
+    # stop is raised (SessionManager::DeleteRefused): the link stays, and
+    # the caller hears it.
+    private_class_method def self.discard_failed_link(id, state_dir, notes:)
       orphan = SessionChain.next_of(id, state_dir: state_dir) or return
       if SessionManager.refuse_tui!(orphan, state_dir: state_dir) &&
          !SessionManager.stop_session(orphan, state_dir: state_dir, wait: SessionManager::STOP_WAIT)
@@ -182,13 +298,26 @@ module Samagotchi
       end
 
       ChildMove.return_rings(from: orphan, to: id, state_dir: state_dir)
-      SessionManager.delete_session(orphan, state_dir: state_dir)
+      FileUtils.rm_f(Session.session_file(orphan, state_dir: state_dir))
+      NoteMove.give_back(from: orphan, to: id, moved: notes, state_dir: state_dir)
+      SessionManager.delete_session(orphan, state_dir: state_dir, allow_scheduled: true)
+      give_back_strays(orphan, id, state_dir)
     rescue SessionManager::DeleteRefused
       raise
     rescue StandardError => e
       Log.warn(:worker, "continue_cleanup_failed", sid: id, error: e.class.name, msg: e.message)
     end
 
+    # A failed link's folder an older chi's note brought back after its
+    # delete: the note goes back to +id+, the folder goes again.
+    private_class_method def self.give_back_strays(orphan, id, state_dir)
+      dir = Session.session_dir(orphan, state_dir: state_dir)
+      return unless Dir.exist?(dir) && !Session.exist?(orphan, state_dir: state_dir)
+
+      NoteMove.give_back(from: orphan, to: id, moved: [], state_dir: state_dir)
+      FileUtils.rm_rf(dir)
+    end
+
     # A failed continue's previous link, back in the lists, with rings that
     # came in meanwhile: wake it for them, as the ring's own wake would have.
     private_class_method def self.wake_for_rings(id, state_dir)
@@ -199,26 +328,35 @@ module Samagotchi
       Log.warn(:worker, "continue_wake_failed", sid: id, error: e.class.name, msg: e.message)
     end
 
-    # The new link, holding off any worker but its own (StartingMarker.fresh?)
-    # while +move+ goes to it.
-    private_class_method def self.spawn_continuation(previous, prompt:, preview:, choice:, state_dir:, move:)
+    # The new link, holding off any worker but its own while +move+ goes to
+    # it (spawn_session marks it starting before its file is saved:
+    # StartingMarker.fresh?).
+    # @param notes [Array<String>] gets the names of the notes moved to it
+    private_class_method def self.spawn_continuation(previous, prompt:, preview:, choice:, state_dir:, move:, notes:,
+                                                     session_id:, client_id: nil)
       recap = RecapStore.read(Session.session_dir(previous.id, state_dir: state_dir))
       start = prompt.to_s.strip.empty? ? nil : prompt
       preview = previous.first_preview if preview.to_s.strip.empty? && start.nil?
       moved_context = nil
       before_spawn = lambda do |link|
-        StartingMarker.mark(link.id, state_dir: state_dir)
         ChildMove.apply(move, from: previous.id, to: link.id, state_dir: state_dir)
         # Its movable context too, with a note saying what moved and stayed.
         moved_context = ContextMove.call(from: previous.id, to: link.id, mode: :continue, state_dir: state_dir)
-        # Its objectives last: the list reads as the latest word.
+        # Its objectives: the list reads as the latest word.
         Objectives.carry(previous, to: link.id, state_dir: state_dir)
+        # Its waiting notes last: the carry above read a pending /objectives
+        # edit from them first. They keep their names, so they still sort
+        # ahead of the link's own notes. A note sent to the previous link
+        # from here on goes to this one (SessionInbox::Head), and a
+        # straggler is adopted by its worker (NoteMove.adoption).
+        notes.concat(NoteMove.move(from: previous.id, to: link.id, state_dir: state_dir))
       end
       link = SessionManager.spawn_session(
         prompt: start, preview: preview, title: previous.title, working_directory: previous.working_directory,
         model_name: choice.model, setup: SessionSetup.of(previous), review: previous.review,
         continues: previous.id, note: SessionChain.note_text(previous, recap: recap, state_dir: state_dir),
-        note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn
+        note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn, client_id: client_id,
+        session_id: session_id
       )
       link.moved_children = move
       link.moved_context = moved_context

data/lib/samagotchi/session_delete_command.rb

@@ -70,7 +70,9 @@ module Samagotchi
       @stdout.puts("#{short}  refused: it is #{OwnerLock::TUI_BUSY}; let it finish first")
       false
     rescue SessionManager::DeleteRefused => e
-      line = if e.reason == :still_stopping then "its worker is still shutting down; try again in a moment"
+      line = case e.reason
+             when :still_stopping then "its worker is still shutting down; try again in a moment"
+             when :scheduled then e.message
              else "its worker is running (--force stops it first)"
              end
       @stdout.puts("#{short}  refused: #{line}")

data/lib/samagotchi/session_inbox.rb

@@ -44,6 +44,20 @@ module Samagotchi
     # NOTE_MAX_BYTES.
     class NoteRejected < ArgumentError; end
 
+    # The one delivery path (session_inbox_delivery.rb), loaded on first
+    # use: the bundle test kit's load budget stays as it was.
+    delivery = File.expand_path("session_inbox_delivery", __dir__)
+    %i[Dispatch Delivered Head Resolved WakePolicy].each { |name| autoload name, delivery }
+
+    # A delivery of +kind+ to session +target+ (Dispatch.deliver: resolve,
+    # refuse, the block's write, one presence read, the WakePolicy's wake).
+    # @return [Delivered]
+    def self.deliver(kind, target, **, &) = Dispatch.deliver(kind, target, **, &)
+
+    # The wake half of #deliver alone (Dispatch.wake).
+    # @return [Delivered]
+    def self.wake(kind, target, **) = Dispatch.wake(kind, target, **)
+
     # Queue a turn's input file: JSON with the prompt and the sender's ids.
     # +delivery+ is only written when it is "queue": a step-boundary
     # message is the default an older worker assumes, and a cut is done by
@@ -89,11 +103,17 @@ module Samagotchi
     # @param now [Time] the time the file is named and stamped by (a spec's clock)
     # @return [String] the note file's path
     # @raise [NoteRejected] for an empty note or one over 16 KiB (never cut)
+    # @raise [Session::NotFound] for a session that is gone: no file and no
+    #   folder (deleted since the writer resolved it), which a note would
+    #   otherwise bring back as a stray folder (as Session#save skips one)
     def self.write_note(session_id, text:, source: "cli", from_session: nil, from_cwd: nil, state_dir: nil,
                         objectives: nil, now: Time.now)
       body = checked_text(text)
       sd = state_dir || Session.default_state_dir
-      notes_dir = File.join(Session.session_dir(session_id, state_dir: sd), NOTES_DIR)
+      session_dir = Session.session_dir(session_id, state_dir: sd)
+      raise Session::NotFound, session_id unless Dir.exist?(session_dir) || Session.exist?(session_id, state_dir: sd)
+
+      notes_dir = File.join(session_dir, NOTES_DIR)
       FileUtils.mkdir_p(notes_dir)
 
       # The random part keeps two writers in one nanosecond apart; the
@@ -203,6 +223,11 @@ module Samagotchi
     # An id that is safe in a file name (a Bridge's or deliver_turn's
     # uuid); anything else leaves the name bare.
     ENQUEUED_ID_NAME = /\A[A-Za-z0-9_-]{1,64}\z/
+    ENQUEUED_ID_UUID = /\A[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}\z/i
+
+    def self.new_enqueued_id = SecureRandom.uuid
+
+    def self.valid_enqueued_id?(id) = id.is_a?(String) && ENQUEUED_ID_UUID.match?(id)
 
     def self.output_name(timestamp, enqueued_id)
       id = enqueued_id.to_s
@@ -221,6 +246,21 @@ module Samagotchi
       Dir.children(dir).select { |f| f.end_with?(suffix) }.max
     end
 
+    # Evidence that a prior worker took this input: a saved or interrupted
+    # turn, its reply, or a mid-turn merge record. A restarted worker's
+    # in-memory id ledger cannot cover these deliveries.
+    def self.input_taken?(session_dir, session, enqueued_id)
+      id = enqueued_id.to_s
+      return false if id.empty?
+      return true if [session.last_turn&.enqueued_id, session.interrupted_turn&.enqueued_id].include?(id)
+      return true if reply_for(session_dir, id)
+
+      require_relative "turn_checkpoint"
+      return true if TurnCheckpoint.settled_turn(session_dir, id)
+
+      !merged_into(session_dir, id).nil?
+    end
+
     # The output files' text, oldest first; with +since_time+ only files
     # modified after it.
     def self.read_outputs(session_dir, since_time: nil)

data/lib/samagotchi/session_inbox_delivery.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_inbox"
+require_relative "archive_store"
+require_relative "worker_presence"
+
+module Samagotchi
+  # Loaded on first use: this autoload keeps SessionManager and its ~80
+  # files unloaded until a delivery starts a worker.
+  autoload :SessionManager, File.expand_path("session_manager", __dir__)
+
+  # The session inbox's one delivery path (SessionInbox.deliver): which link
+  # a delivery goes to (Head), whether it is refused, its write (the kind's
+  # own writer, unchanged), one read of the worker's presence after it, and
+  # what that means for a worker (WakePolicy). Loaded on first use, from
+  # session_inbox.rb's autoloads: the bundle test kit's load budget
+  # (spec/samagotchi/testing/sandbox_spec.rb) stays as it was.
+  module SessionInbox
+    # Where a delivery for +asked+ goes: +id+, reached +via+ :pinned (the
+    # kind never follows a chain), :same (followed, nothing to follow) or
+    # :head (a later link of +asked+'s chain).
+    Resolved = Data.define(:id, :asked, :via)
+
+    # A delivery's outcome.
+    # @!attribute kind [Symbol] the WakePolicy row
+    # @!attribute id [String] the session whose worker the outcome is about
+    #   (a ring's file stays with +asked+: WakePolicy#resolves :reader)
+    # @!attribute asked [String] the id the caller named
+    # @!attribute via [Symbol] Resolved#via
+    # @!attribute status [Symbol] :refused (nothing written), :queued (a
+    #   worker sees it: one runs, is starting or was started) or :waits (no
+    #   worker comes: it waits for the next start)
+    # @!attribute wake [Symbol] WakePolicy#decide's outcome, :woken for a
+    #   start made, or the refusal (:gone, :owned: a one-turn chi run's,
+    #   :scratch)
+    # @!attribute queued [Integer, nil] notes waiting (a note kind's), nil else
+    Delivered = Data.define(:kind, :id, :asked, :via, :status, :wake, :queued) do
+      def initialize(kind:, id:, asked:, via:, status:, wake:, queued: nil) = super
+
+      def refused? = status == :refused
+    end
+
+    # What a delivery of one kind may do to a session's worker: one frozen
+    # row per kind (ROWS), decided on WorkerPresence's predicates alone, in
+    # one order for every kind (#decide).
+    # @!attribute kind [Symbol] :send, :note, :push, :ring, :fresh_verdict or
+    #   :leave (WorkerBoot's respawn, not a delivery)
+    # @!attribute resolves [Symbol] which link it goes to (Head.resolve):
+    #   :pinned the id named; :head the chain's newest link from it; :reader
+    #   the link that reads the named one's file (a ring: the file stays with
+    #   the parent parent.json names, ChildReports reads its predecessor's
+    #   rings, so the wake goes one hop at most)
+    # @!attribute starts [Boolean] it may start a worker
+    # @!attribute unstops [Boolean] it starts a stopped session (a resume
+    #   clears the stop): send only
+    # @!attribute starts_archived [Boolean] it starts an archived link
+    #   (input from a person un-archives it): send only
+    # @!attribute refuse_tui [Boolean] a one-turn chi run's session refuses it
+    # @!attribute refuse_scratch [Boolean] a chi scratch session refuses it
+    WakePolicy = Data.define(:kind, :resolves, :starts, :unstops, :starts_archived, :refuse_tui, :refuse_scratch) do
+      # @return [WakePolicy]
+      # @raise [ArgumentError] no such kind
+      def self.for(kind) = WakePolicy::ROWS.fetch(kind) { raise ArgumentError, "no inbox kind #{kind.inspect}" }
+
+      # Why the delivery is refused before anything is written, else nil:
+      # :gone (no session), :owned (a one-turn chi run's), :scratch.
+      # @param load [#call, nil] the session, read only when the scratch
+      #   flag decides (nil: not a scratch session)
+      # @return [Symbol, nil]
+      def refusal(presence, load: nil)
+        return :gone unless presence.exists?
+        return :owned if refuse_tui && presence.tui_owned?
+
+        :scratch if refuse_scratch && scratch?(load)
+      end
+
+      # What the delivery means for the session's worker, in this order:
+      # :gone, :owned (a one-turn chi run's), :live (a worker holds it: it
+      # sees the delivery), :stopped (the stop marker: the only "stopped",
+      # the file's status never decides), :archived, :starting (a worker is
+      # being started: it reads the store on its first pass), :none (the
+      # kind never starts one), :off (+wake+ false: none was asked),
+      # :scratch (its terminal's alone; the file is read last, only here),
+      # :start (start one).
+      # @param wake [Boolean] the delivery asks for a worker (a ring in wake
+      #   mode, a push with wake)
+      # @return [Symbol]
+      def decide(presence, wake: true, load: nil)
+        return :gone unless presence.exists?
+        return :owned if presence.tui_owned?
+        return :live if presence.owned?
+        return :stopped if presence.stop_marked? && !unstops
+        return :archived if presence.archived? && !starts_archived
+        # A stop cancels a start's hold-off for a kind that clears it
+        # (WorkerPresence#start_pending?).
+        return :starting if unstops ? presence.start_pending? : presence.starting?
+        return :none unless starts
+        return :off unless wake
+        return :scratch if scratch?(load)
+
+        :start
+      end
+
+      private def scratch?(load) = load ? load.call.scratch == true : false
+    end
+
+    WakePolicy::ROWS = {
+      send: WakePolicy.new(kind: :send, resolves: :pinned, starts: true, unstops: true, starts_archived: true,
+                           refuse_tui: true, refuse_scratch: true),
+      note: WakePolicy.new(kind: :note, resolves: :head, starts: false, unstops: false, starts_archived: false,
+                           refuse_tui: true, refuse_scratch: true),
+      push: WakePolicy.new(kind: :push, resolves: :pinned, starts: true, unstops: false, starts_archived: false,
+                           refuse_tui: false, refuse_scratch: false),
+      ring: WakePolicy.new(kind: :ring, resolves: :reader, starts: true, unstops: false, starts_archived: false,
+                           refuse_tui: false, refuse_scratch: false),
+      fresh_verdict: WakePolicy.new(kind: :fresh_verdict, resolves: :pinned, starts: false, unstops: false,
+                                    starts_archived: false, refuse_tui: false, refuse_scratch: false),
+      # Not a delivery: a worker's own leave starting its successor for
+      # what waits (input, rings) or a restart (WorkerBoot, after the
+      # lock's release). A stop wins; an archived session's input still
+      # starts it, as a send's would have.
+      leave: WakePolicy.new(kind: :leave, resolves: :pinned, starts: true, unstops: false, starts_archived: true,
+                            refuse_tui: false, refuse_scratch: false)
+    }.freeze
+
+    # Which link of a chain a delivery goes to.
+    module Head
+      module_function
+
+      # +id+ for a pinned kind, or for an id not archived (the cheap check
+      # first: only an archived id is walked, with one Session.list).
+      # Else the walk forward over archived links that have a successor:
+      # to the first link not archived, or the last (a loop a hand-edited
+      # file could make ends where it started); a :reader kind goes one hop
+      # at most.
+      # @return [Resolved]
+      def resolve(kind, id, state_dir:)
+        how = WakePolicy.for(kind).resolves
+        return Resolved.new(id: id, asked: id, via: :pinned) if how == :pinned
+
+        same = Resolved.new(id: id, asked: id, via: :same)
+        return same unless archived?(id, state_dir)
+
+        nexts = successors(state_dir)
+        seen = [id]
+        while (following = nexts[seen.last]) && !seen.include?(following)
+          seen << following
+          break if how == :reader || !archived?(following, state_dir)
+        end
+        seen.size == 1 ? same : Resolved.new(id: seen.last, asked: id, via: :head)
+      end
+
+      def archived?(id, state_dir)
+        Session.valid_id?(id) && ArchiveStore.archived?(Session.session_dir(id, state_dir: state_dir))
+      end
+
+      # id → the session that continues it (SessionChain.next_of's: the
+      # earliest one, archived ones too).
+      def successors(state_dir)
+        Session.list(state_dir: state_dir, sort: "created_at", order: "asc", include_archived: true)
+               .each_with_object({}) { |s, nexts| nexts[s.continues] ||= s.id if s.continues }
+      end
+    end
+
+    # SessionInbox.deliver and SessionInbox.wake.
+    module Dispatch
+      # What a start each kind makes is logged as (SessionManager.start_for_inbox).
+      START_EVENTS = { ring: :delegate_woke_parent, push: :context_woke_session }.freeze
+
+      module_function
+
+      # Deliver one +kind+ of thing to session +target+, in this order:
+      # resolve the link (Head.resolve), refuse (WakePolicy#refusal: before
+      # any write), write (the block: the kind's own writer, given the id
+      # it writes under), read the presence once, then decide and apply
+      # (#wake).
+      # @param wake [Boolean] the delivery may ask for a worker; the block's
+      #   value says whether it does (truthy: asks)
+      # @param pin [Boolean] write under +target+ itself, whatever the kind's
+      #   row resolves (a writer whose text is +target+'s own: an
+      #   /objectives list built from its conversation)
+      # @param resolved [Resolved, nil] the link, as the caller resolved it
+      #   already (Head.resolve for this kind): not walked again
+      # @param owner [#call, nil] (id) the owner lock's holder (a stand-in
+      #   manager's session_owner); nil: SessionManager.session_owner
+      # @param start [#call, nil] (id) starts a worker, returns :woken (or
+      #   why not); nil: SessionManager.start_for_inbox
+      # @yieldparam id [String] the session it is written under
+      # @yieldreturn [Boolean] whether it asks for a worker
+      # @return [Delivered]
+      def deliver(kind, target, state_dir: nil, wake: true, pin: false, resolved: nil, owner: nil, start: nil)
+        sd = state_dir || Session.default_state_dir
+        policy = WakePolicy.for(kind)
+        resolved = Resolved.new(id: target, asked: target, via: :pinned) if pin
+        resolved ||= Head.resolve(kind, target, state_dir: sd)
+        at = policy.resolves == :reader ? resolved.asked : resolved.id
+        if (why = refusal(policy, at, sd, owner))
+          return Delivered.new(kind: kind, id: resolved.id, asked: resolved.asked, via: resolved.via, status: :refused,
+                               wake: why)
+        end
+
+        asks = yield(at)
+        apply(policy, resolved, sd, wake: wake && asks ? true : false, owner: owner, start: start)
+      end
+
+      # The wake half of #deliver alone, for a delivery already on disk (a
+      # failed continue's previous link with rings that came meanwhile).
+      # @return [Delivered]
+      def wake(kind, target, state_dir: nil, owner: nil, start: nil)
+        sd = state_dir || Session.default_state_dir
+        apply(WakePolicy.for(kind), Head.resolve(kind, target, state_dir: sd), sd, wake: true, owner: owner,
+                                                                                    start: start)
+      end
+
+      def refusal(policy, id, state_dir, owner)
+        return :gone unless Session.exist?(id, state_dir: state_dir)
+        return nil unless policy.refuse_tui || policy.refuse_scratch
+
+        policy.refusal(presence(id, state_dir, owner), load: -> { Session.load(id, state_dir: state_dir) })
+      end
+
+      def apply(policy, resolved, state_dir, wake:, owner:, start:)
+        id = resolved.id
+        outcome = policy.decide(presence(id, state_dir, owner), wake: wake, load: -> { Session.load(id, state_dir: state_dir) })
+        if outcome == :start
+          outcome = if start
+                      start.call(id)
+                    else
+                      SessionManager.start_for_inbox(id, state_dir: state_dir,
+                                                                                                    event: START_EVENTS.fetch(policy.kind))
+                    end
+        end
+        status = %i[live woken starting].include?(outcome) ? :queued : :waits
+        Delivered.new(kind: policy.kind, id: id, asked: resolved.asked, via: resolved.via, status: status,
+                      wake: outcome, queued: notes_waiting(policy, status, id, state_dir))
+      end
+
+      # A note's count of the notes waiting for a start (0 when a worker
+      # sees them); nil for the other kinds.
+      def notes_waiting(policy, status, id, state_dir)
+        return nil unless policy.kind == :note
+        return 0 unless status == :waits
+
+        SessionInbox.find_new_note_files(Session.session_dir(id, state_dir: state_dir)).size
+      end
+
+      def presence(id, state_dir, owner)
+        reader = owner ? -> { owner.call(id) } : -> { SessionManager.session_owner(id, state_dir: state_dir) }
+        WorkerPresence.read(id, state_dir: state_dir, owner: reader)
+      end
+    end
+  end
+end