samagotchi 0.35.0 → 0.37.0

data/lib/samagotchi/broadcast_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "securerandom"
 require_relative "config"
 require_relative "session"
 require_relative "session_inbox"
@@ -7,6 +8,9 @@ require_relative "note_delivery"
 require_relative "broadcast/recipients"
 require_relative "broadcast/scope_card"
 require_relative "broadcast/tags"
+require_relative "broadcast/triage"
+require_relative "broadcast/triage_model"
+require_relative "broadcast/triage_log"
 require_relative "cli/command"
 require_relative "cli/flags"
 
@@ -14,8 +18,11 @@ module Samagotchi
   # `chi broadcast`: share a note with every session it may concern,
   # without picking them. Each recipient (Broadcast::Recipients) that shares
   # a tag with the note (Broadcast::Tags) gets it as a context note from
-  # "broadcast"; --all gives it to every recipient. The rest are listed as
-  # skipped, with why. For the user only: refused inside a chi session.
+  # "broadcast", and a triage model judges the rest (Broadcast::Triage);
+  # --all gives it to every recipient. The rest are listed as skipped, with
+  # why. Each broadcast's verdicts go to Broadcast::TriageLog (`chi
+  # broadcast log`), and `chi broadcast deliver` gives one to sessions it
+  # skipped. For the user only: refused inside a chi session.
   class BroadcastCommand
     include CLI::Command
 
@@ -31,6 +38,8 @@ module Samagotchi
 
     USAGE = <<~TEXT
       Usage: chi broadcast [-m TEXT] [--all] [--dry-run]
+             chi broadcast log [--last N] [--format json]
+             chi broadcast deliver BROADCAST_ID (ID|PREFIX)...
         Shares TEXT (or stdin) with the sessions it may concern, as a context
         note from "broadcast": background the model sees on its next turn,
         not a prompt. It starts no turn.
@@ -39,10 +48,20 @@ module Samagotchi
         the last broadcast.active_hours (8). One gets the note when it shares
         a tag with it: a ticket id (PAY-123) in its branch or your prompts
         there, a pull request (PR #42, its URL) attached to it, a link in
-        your prompts there or its attached context. The rest are skipped.
+        your prompts there or its attached context. A triage model
+        (broadcast.triage_model, else the recap's, else default.model) reads
+        the note and each other session's scope card and says whether it
+        concerns it; one it can't judge in broadcast.triage_deadline (20 s)
+        gets it unchecked. A first line naming one project keeps the note to
+        that project's sessions.
         -m TEXT    the note; without it, stdin is read
-        --all      every recipient, tag or not
+        --all      every recipient, no tags or triage
         --dry-run  show each recipient's scope card, tags and verdict; deliver nothing
+        It prints the broadcast's id (b-7f3a1c9e), then a line per recipient.
+        log: the last N broadcasts (5) and each recipient's verdict, from
+        the triage log; --format json for a script.
+        deliver: the broadcast to sessions it skipped, after all (kept in
+        the log as a correction).
         For you, not for an agent: refused inside a chi session.
         One session or a few by id: chi note. See docs/broadcast.md.
     TEXT
@@ -53,17 +72,33 @@ module Samagotchi
       f.value "-m", "--message", key: :text
     end
 
-    # One recipient's verdict. +match+: the tag that delivers it (nil with
-    # --all or none); +skip+: why it is skipped, else nil.
-    Verdict = Data.define(:recipient, :match, :skip) do
-      def deliver? = skip.nil?
+    LOG_FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS, args: false) do |f|
+      f.value "--last"
+      f.value "--format"
+    end
+
+    DELIVER_FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS)
+
+    # The broadcasts `chi broadcast log` shows by default.
+    LOG_LAST = 5
+
+    # One recipient and its Broadcast::Triage::Verdict.
+    Decision = Data.define(:recipient, :verdict) do
+      def deliver? = verdict.relevant
     end
 
     # @param argv [Array<String>] the arguments after "broadcast"
     # @param active_hours [Numeric, nil] broadcast.active_hours (config)
     # @param ticket_pattern [String, nil] broadcast.ticket_pattern (config)
+    # @param triage [#call, nil] (CancellationController) → a triage
+    #   backend (#judge(note, card) → Verdict); nil: Triage::LLM on
+    #   Broadcast::TriageModel's model
+    # @param log [Broadcast::TriageLog, nil] nil: the default path's
     def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, env: ENV, now: Time.now,
-                   active_hours: Config.get("broadcast.active_hours"), ticket_pattern: Config.get("broadcast.ticket_pattern"))
+                   active_hours: Config.get("broadcast.active_hours"), ticket_pattern: Config.get("broadcast.ticket_pattern"),
+                   triage: nil, triage_parallel: Config.get("broadcast.triage_parallel"),
+                   triage_deadline: Config.get("broadcast.triage_deadline"), threshold: Config.get("broadcast.threshold"),
+                   log: nil)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
@@ -73,18 +108,24 @@ module Samagotchi
       @now = now
       @active_hours = active_hours || 8
       @ticket = Broadcast::Tags.ticket_regexp(ticket_pattern, warn: ->(line) { @stderr.puts("chi broadcast: #{line}") })
+      @triage = triage
+      @triage_parallel = (triage_parallel || Broadcast::Triage::DEFAULT_PARALLEL).to_i
+      @triage_deadline = (triage_deadline || Broadcast::Triage::DEFAULT_DEADLINE).to_f
+      @threshold = (threshold || Broadcast::Triage::DEFAULT_THRESHOLD).to_f
+      @log = log || Broadcast::TriageLog.new
     end
 
     # @return [Integer] exit status: 0 done (skipped sessions included),
     #   1 refused, nothing to send to or a delivery failed, 2 usage
     def run
+      case @argv.first
+      when "log" then return run_log(@argv.drop(1))
+      when "deliver" then return run_deliver(@argv.drop(1))
+      end
+
       options = parse
       return options if options.is_a?(Integer)
-
-      unless @env[PARENT_ENV].to_s.empty?
-        error_line("chi broadcast: chi broadcast is for your user, not an agent")
-        return 1
-      end
+      return refused if agent?
 
       text = utf8(options[:text] || read_stdin)
       return usage_error("no note text: pass -m TEXT or pipe it in") unless text
@@ -113,6 +154,15 @@ module Samagotchi
       parsed.is_a?(Integer) ? parsed : parsed.options
     end
 
+    # Inside a chi session (any SAMAGOTCHI_PARENT_SESSION, "chi" included):
+    # an agent runs it.
+    def agent? = !@env[PARENT_ENV].to_s.empty?
+
+    def refused
+      error_line("chi broadcast: chi broadcast is for your user, not an agent")
+      1
+    end
+
     # @return [Integer] exit status
     def broadcast(text, all:, dry_run:)
       recipients = Broadcast::Recipients.list(state_dir: @state_dir, active_hours: @active_hours, now: @now)
@@ -124,73 +174,245 @@ module Samagotchi
 
       note_tags = Broadcast::Tags.of_text(text, from: "note", ticket: @ticket)
       cards = recipients.to_h { |r| [r.id, Broadcast::ScopeCards.build(r, state_dir: @state_dir, ticket: @ticket)] }
-      verdicts = recipients.map { |r| verdict(r, cards.fetch(r.id), note_tags, all: all) }
-      verdicts = verdicts.select(&:deliver?) + verdicts.reject(&:deliver?)
-
-      @stdout.puts("broadcast#{" (dry run: nothing is delivered)" if dry_run}  #{headline(text)}")
+      id = "b-#{SecureRandom.hex(4)}" unless dry_run
+      @stdout.puts("broadcast #{id || "(dry run: nothing is delivered)"}  #{headline(text)}")
       @stdout.puts("note tags: #{note_tags.empty? ? "none" : note_tags.map(&:label).join(" · ")}") if dry_run
-      return dry_run(verdicts, cards) if dry_run
+      @stdout.flush
+      decisions = decide(text, recipients, cards, note_tags, all: all)
+      decisions = decisions.select(&:deliver?) + decisions.reject(&:deliver?)
+      @stdout.puts("triage model: #{@triage_choice.target&.label || "none"} (#{@triage_choice.setting})") if dry_run && @triage_choice
+      return dry_run(decisions, cards) if dry_run
+
+      deliver_all(Broadcast::TriageLog::Record.new(id: id, at: @now, text: text, note_tags: note_tags.map(&:label),
+                                                   triage_model: @triage_choice&.target&.label, recipients: [],
+                                                   corrections: []), decisions, cards)
+    end
+
+    # Every recipient's verdict: a chi REPL takes no notes, --all takes the
+    # rest, else Broadcast::Triage (tags, the scope line, the model).
+    # @return [Array<Decision>] in +recipients+' order
+    def decide(text, recipients, cards, note_tags, all:)
+      fixed = recipients.to_h do |r|
+        verdict = if r.repl?
+                    Broadcast::Triage::Verdict.new(relevant: false, p: nil, reason: "open in a chi REPL", by: "repl")
+                  elsif all
+                    Broadcast::Triage::Verdict.new(relevant: true, p: nil, reason: "--all", by: "all")
+                  end
+        [r.id, verdict]
+      end
+      judged = recipients.reject { |r| fixed[r.id] }.map { |r| cards.fetch(r.id) }
+      triaged = Broadcast::Triage.verdicts(text, judged, note_tags: note_tags, new_backend: method(:triage_backend),
+                                                         parallel: @triage_parallel, deadline: @triage_deadline)
+      recipients.map { |r| Decision.new(recipient: r, verdict: fixed[r.id] || triaged.fetch(r.id)) }
+    end
+
+    # One triage backend for a thread (Triage.judge_all): the injected
+    # one, or Triage::LLM on the triage model, resolved once; with no
+    # model to ask, one that delivers unchecked and says why.
+    def triage_backend(cancel)
+      return @triage.call(cancel) if @triage
 
-      deliver_all(verdicts, text)
+      choice = triage_choice
+      return UncheckedBackend.new("no triage model: #{choice.problem}") unless choice.target
+
+      Broadcast::Triage::LLM.new(target: choice.target, timeout: @triage_deadline, threshold: @threshold,
+                                 cancel_controller: cancel)
     end
 
-    def verdict(recipient, card, note_tags, all:)
-      return Verdict.new(recipient: recipient, match: nil, skip: "open in a chi REPL") if recipient.repl?
+    def triage_choice
+      (@triage_lock ||= Mutex.new).synchronize do
+        @triage_choice ||= Broadcast::TriageModel.resolve.tap do |choice|
+          error_line("chi broadcast: no triage model: #{choice.problem}; delivering unchecked") unless choice.target
+        end
+      end
+    end
 
-      match = Broadcast::Tags.match(note_tags, card.tags)
-      skip = "no tag match (not checked: no triage yet)" unless all || match
-      Verdict.new(recipient: recipient, match: match, skip: skip)
+    # A triage backend with no model: every card it gets is delivered
+    # unchecked, +why+ in the reason.
+    UncheckedBackend = Data.define(:why) do
+      def judge(_note, _card) = Broadcast::Triage.unchecked(why)
     end
 
-    def dry_run(verdicts, cards)
-      verdicts.each do |v|
-        @stdout.puts(line(v.recipient, v.deliver? ? "would get it" : "skipped", reason(v), width: 12))
-        @stdout.puts(cards.fetch(v.recipient.id).to_s.gsub(/^/, "          "))
+    def dry_run(decisions, cards)
+      decisions.each do |d|
+        @stdout.puts(line(d.recipient, d.deliver? ? "would get it" : "skipped", d.verdict.reason, width: 12))
+        @stdout.puts(cards.fetch(d.recipient.id).to_s.gsub(/^/, "          "))
       end
-      delivered = verdicts.count(&:deliver?)
-      @stdout.puts("would deliver #{delivered} · skipped #{verdicts.size - delivered}")
+      delivered = decisions.count(&:deliver?)
+      @stdout.puts("would deliver #{delivered} · skipped #{decisions.size - delivered}#{unchecked_summary(decisions)}")
       0
     end
 
-    def deliver_all(verdicts, text)
+    # Delivers +broadcast+ (a TriageLog::Record with no recipients yet) per
+    # +decisions+, prints a line per recipient and the summary, and logs it.
+    def deliver_all(broadcast, decisions, cards)
       ok = true
-      lines = verdicts.map do |v|
-        next [v.recipient, false, "skipped", v.skip] unless v.deliver?
+      lines = decisions.map do |d|
+        next [d, "skipped", d.verdict.reason] unless d.deliver?
 
-        result = NoteDelivery.deliver(v.recipient.id, text: body(text, v.match), source: SOURCE, state_dir: @state_dir)
-        next [v.recipient, false, "skipped", "open in a chi REPL"] unless result.delivered?
+        result = NoteDelivery.deliver(d.recipient.id, text: body(broadcast.text, d.verdict), source: SOURCE,
+                                                      state_dir: @state_dir)
+        next [d, "skipped", "open in a chi REPL"] unless result.delivered?
 
-        [v.recipient, true, "delivered", "#{reason(v)}#{"; waits for its next start" if result.status == :waits}"]
+        [d, "delivered", "#{d.verdict.reason}#{"; waits for its next start" if result.status == :waits}"]
       rescue SessionInbox::NoteRejected, SystemCallError => e
         ok = false
-        [v.recipient, false, "failed", e.message]
+        [d, "failed", e.message]
       end
-      lines.sort_by.with_index { |(_, delivered), i| [delivered ? 0 : 1, i] }.each do |recipient, _, word, why|
-        @stdout.puts(line(recipient, word, why))
+      lines.sort_by.with_index { |(_, word), i| [word == "delivered" ? 0 : 1, i] }.each do |d, word, why|
+        @stdout.puts(line(d.recipient, word, why))
       end
-      delivered = lines.count { |_, d| d }
-      @stdout.puts("delivered #{delivered} · skipped #{lines.size - delivered}")
+      delivered = lines.count { |_, word| word == "delivered" }
+      @stdout.puts("delivered #{delivered} · skipped #{lines.size - delivered}#{unchecked_summary(decisions)}")
+      write_log(broadcast, lines, cards)
       ok ? 0 : 1
     end
 
+    # The broadcast's verdicts into the triage log; a log that can't be
+    # written is a warning, not a failed broadcast.
+    def write_log(broadcast, lines, cards)
+      entries = lines.map do |d, word, why|
+        verdict = d.verdict
+        Broadcast::TriageLog::Entry.new(session: d.recipient.id, result: word, p: verdict.p, reason: why, by: verdict.by,
+                                        tags: cards.fetch(d.recipient.id).tags.map(&:label))
+      end
+      @log.append_broadcast(id: broadcast.id, at: broadcast.at, text: broadcast.text, note_tags: broadcast.note_tags,
+                            triage_model: broadcast.triage_model, recipients: entries)
+    rescue SystemCallError => e
+      error_line("chi broadcast: the triage log #{@log.path} couldn't be written: #{e.message}")
+    end
+
+    # `chi broadcast log`. @return [Integer] exit status
+    def run_log(argv)
+      parsed = parse_flags(LOG_FLAGS, argv)
+      return parsed if parsed.is_a?(Integer)
+      return refused if agent?
+
+      options = parsed.options
+      last = options[:last] ? Integer(options[:last], exception: false) : LOG_LAST
+      return usage_error("--last takes a positive number") unless last&.positive?
+      return usage_error("--format takes json") unless [nil, "json"].include?(options[:format])
+
+      records = @log.records.last(last)
+      if options[:format] == "json"
+        @stdout.puts(JSON.pretty_generate(records.map(&:to_json_hash)))
+        return 0
+      end
+      @stdout.puts("no broadcasts in the log yet (#{@log.path})") if records.empty?
+      records.each { |record| print_record(record) }
+      0
+    end
+
+    def print_record(record)
+      @stdout.puts("#{record.id}  #{record.at.localtime.strftime("%Y-%m-%d %H:%M")}  #{headline(record.text)}")
+      record.recipients.each { |e| @stdout.puts("  #{e.session[0, 8]}  #{e.result.ljust(9)}  #{e.reason}") }
+      delivered = record.recipients.count { |e| e.result == "delivered" }
+      @stdout.puts("  delivered #{delivered} · skipped #{record.recipients.size - delivered}")
+      record.corrections.each do |c|
+        sessions = c.sessions.map { |d| "#{d.session[0, 8]}#{" (#{d.result})" unless d.result == "delivered"}" }
+        @stdout.puts("  #{c.at.localtime.strftime("%Y-%m-%d %H:%M")} delivered anyway: #{sessions.join(", ")}")
+      end
+    end
+
+    # `chi broadcast deliver BROADCAST_ID SESSION...`: the logged note to
+    # sessions it skipped. @return [Integer] exit status
+    def run_deliver(argv)
+      parsed = parse_flags(DELIVER_FLAGS, argv)
+      return parsed if parsed.is_a?(Integer)
+      return refused if agent?
+
+      given, *sessions = parsed.args
+      return usage_error("give a broadcast id and the sessions to deliver it to") if given.nil? || sessions.empty?
+
+      record = begin
+        @log.find(given)
+      rescue Broadcast::TriageLog::NotFound => e
+        error_line("chi broadcast: #{e.message}")
+        return 1
+      end
+      ids = sessions.map { |given| resolve_session(given) }
+      results = ids.compact.uniq.map { |id| deliver_anyway(record, id) }
+      unless results.empty?
+        begin
+          @log.append_correction(id: record.id, at: @now, sessions: results)
+        rescue SystemCallError => e
+          error_line("chi broadcast: the triage log #{@log.path} couldn't be written: #{e.message}")
+        end
+      end
+      # Done when every session named has the note now.
+      ids.all? && results.all? { |d| ["delivered", "had it"].include?(d.result) } ? 0 : 1
+    end
+
+    # The full id +given+ names (an id or the start of one), or nil after
+    # saying why there is none.
+    def resolve_session(given)
+      id = Session.resolve_id(given, state_dir: @state_dir)
+      Session.load(id, state_dir: @state_dir) # raises ArgumentError when there is no such session
+      id
+    rescue ArgumentError => e
+      error_line("chi broadcast: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      nil
+    rescue SystemCallError => e
+      error_line("chi broadcast: session #{given} can't be read: #{e.message}")
+      nil
+    end
+
+    # @param id [String] a full session id (#resolve_session)
+    # @return [Broadcast::TriageLog::Delivery]
+    def deliver_anyway(record, id)
+      if record.delivered?(id)
+        @stdout.puts(line_for(id, "skipped", "it got #{record.id} already"))
+        return Broadcast::TriageLog::Delivery.new(session: id, result: "had it")
+      end
+
+      result = NoteDelivery.deliver(id, text: passed_on_body(record), source: SOURCE, state_dir: @state_dir)
+      unless result.delivered?
+        @stdout.puts(line_for(id, "skipped", "open in a chi REPL"))
+        return Broadcast::TriageLog::Delivery.new(session: id, result: "refused")
+      end
+
+      @stdout.puts(line_for(id, "delivered", "by hand#{"; waits for its next start" if result.status == :waits}"))
+      Broadcast::TriageLog::Delivery.new(session: id, result: "delivered")
+    rescue SessionInbox::NoteRejected, SystemCallError => e
+      @stdout.puts(line_for(id, "failed", e.message))
+      Broadcast::TriageLog::Delivery.new(session: id, result: "failed")
+    end
+
+    # A logged broadcast passed on by hand: as #body words it, dated when
+    # it was shared.
+    def passed_on_body(record)
+      shared = "Shared by your user on #{record.at.localtime.strftime("%Y-%m-%d %H:%M")}"
+      "#{record.text}\n(#{shared} with the sessions it may concern; your user passed it on to this session.)"
+    end
+
+    def line_for(id, word, why) = "#{id[0, 8]}  #{word.ljust(9)}  #{why}"
+
+    # " · 2 unchecked: triage deadline" when some were delivered without a
+    # verdict (the desktop helper shows only this line), else "".
+    def unchecked_summary(decisions)
+      unchecked = decisions.map(&:verdict).select(&:unchecked?)
+      return "" if unchecked.empty?
+
+      whys = unchecked.map { |v| v.reason.delete_prefix("unchecked: ").sub(/\s*[("].*\z/m, "") }.uniq
+      " · #{unchecked.size} unchecked: #{whys.join(", ")}"
+    end
+
     # What a recipient gets: the user's text first (the terminal's "note
     # from broadcast: …" line shows its start), then a line saying when it
     # was shared (a session with no worker may read it days later; the
-    # note's header has the time only) and why it reached this session. No
-    # instruction: the system prompt says what a broadcast note asks.
-    def body(text, match)
+    # note's header has the time only) and, for a tag match, why it reached
+    # this session. No instruction: the system prompt says what a broadcast
+    # note asks.
+    def body(text, verdict)
       shared = "Shared by your user on #{@now.localtime.strftime("%Y-%m-%d %H:%M")}"
-      return "#{text}\n(#{shared} with every active session.)" unless match
+      return "#{text}\n(#{shared} with every active session.)" if verdict.by == "all"
+      return "#{text}\n(#{shared} with the sessions it may concern.)" unless verdict.match
 
-      because = match.because
+      because = verdict.match.because
       because = "#{because[0, BECAUSE_CHARS - 1]}…" if because.length > BECAUSE_CHARS
       "#{text}\n(#{shared} with the sessions it may concern; it reached you because #{because}.)"
     end
 
-    def reason(verdict)
-      verdict.skip || verdict.match&.reason || "--all"
-    end
-
     def line(recipient, word, why, width: 9) = "#{recipient.short_id}  #{word.ljust(width)}  #{why}"
 
     # The note's first line, quoted and cut, for the output's head.
@@ -206,23 +428,5 @@ module Samagotchi
       value = hours.to_f
       "#{value == value.round ? value.round : value} #{value == 1 ? "hour" : "hours"}"
     end
-
-    # Only a pipe or a file is read, as chi note does: a terminal or a
-    # socket a launcher passes down may never close.
-    def read_stdin
-      return nil if @stdin.respond_to?(:tty?) && @stdin.tty?
-
-      if @stdin.respond_to?(:stat)
-        stat = @stdin.stat
-        return nil unless stat.pipe? || stat.file?
-      end
-
-      @stdin.read
-    end
-
-    # The note as UTF-8 whatever the locale says (see NoteCommand#utf8).
-    def utf8(text)
-      text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
-    end
   end
 end

data/lib/samagotchi/bundles/coordinator/manifest.yml

@@ -1,14 +1,15 @@
 ---
 name: coordinator
-version: 0.1.2
+version: 0.2.0
 scope: system
-description: "Coordinate parallel work: the coordinator skill (split the work, one worktree and child session per task, check each report, ask before each merge), /coordinate <goal> and /children"
+description: "Coordinate parallel work: the coordinator skill (split the work, one worktree and child session per task, check each report, ask before each merge, a handoff memory to resume from), /coordinate <goal>, /coordinate resume and /children"
 trust_level: reviewed
 files:
   skill_coordinator.md:
-    sha256: sha256:b21067c3f152c8dfd1b1f70001c6654ad1911616543a36b625727fb13d4ce3f6
-    description: "Coordinate parallel work: split it, delegate each task wait:false in its own worktree (cwd:), check each report, ask the user before each merge"
+    sha256: sha256:a24b91ae27737027125cc0d627bf31edbacdd1be842f4daf82ddf062c9160413
+    description: "Coordinate parallel work: split it, delegate each task wait:false in its own worktree (cwd:), check each report, ask the user before each merge; resume from a handoff_* memory"
 plugin:
   file: plugin.rb
-  sha256: sha256:5173faeb6311984ad4f2a40b9052dcc577a90790fc5c5a8409b95d4f114e66a7
-requires_chi: ">= 0.34.0"
+  sha256: sha256:2b11a24f22398f4d00132c2342f7c02eacfc6cec0e517e8241a17241affc8ca7
+# the handoff memory needs memory_write's description-only form and remove: (0.36.0)
+requires_chi: ">= 0.36.0"

data/lib/samagotchi/bundles/coordinator/plugin.rb

@@ -18,6 +18,13 @@
 # for the goal. A REPL session (--no-shared) takes no messages: the request
 # is shown for the user to send.
 #
+# /coordinate resume picks up a coordinator handoff: the open handoff_*
+# memories of this project (an index line whose description doesn't start
+# with DONE, its file there). One: the model is asked to resume it (the
+# skill's step 0); several: a card with a Resume action each
+# (/coordinate resume <name>); none: says so. It reads the project's
+# memories folder, nothing else.
+#
 # A child is asked before it changes anything outside its worktree by chi
 # itself (the core child-boundary guardrail), in every mode: nothing to set up.
 class Plugin
@@ -27,7 +34,12 @@ class Plugin
   STOPPABLE = %w[running waiting].freeze
   TEXT_CHARS = 80
   USAGE = "usage: /children [all] | /children stop <id>"
-  COORDINATE_USAGE = "usage: /coordinate <goal> — chi splits it into tasks, one child session and worktree each"
+  COORDINATE_USAGE = "usage: /coordinate <goal> — chi splits it into tasks, one child session and worktree each; " \
+                     "/coordinate resume [name] — pick up an open handoff"
+  RESUME_CARD_ID = "coordinate-resume"
+  # A card takes 6 actions.
+  MAX_RESUMES = 6
+  HANDOFF_LINE = /^- \*\*(handoff_[^*\s]+)\*\*(.*)$/
 
   def initialize(_settings = {}); end
 
@@ -36,7 +48,8 @@ class Plugin
                 anytime: true do |args, ctx|
       children_command(args.to_s.strip, ctx)
     end
-    chi.command "/coordinate", "run work in parallel: chi splits <goal> into tasks, each in a child session and worktree",
+    chi.command "/coordinate", "run work in parallel: chi splits <goal> into tasks, each in a child session and worktree; " \
+                               "resume: pick up an open handoff",
                 anytime: true do |args, ctx|
       coordinate(args.to_s.strip, ctx)
     end
@@ -97,13 +110,68 @@ class Plugin
   def coordinate(goal, ctx)
     return COORDINATE_USAGE if goal.empty?
 
-    request = "Read the skill_coordinator memory and follow it for this goal:\n\n#{goal}"
+    verb, rest = goal.split(/\s+/, 2)
+    # "resume" and at most a name; "resume the old work" is a goal.
+    return resume(rest.to_s.strip, ctx) if verb == "resume" && !rest.to_s.strip.match?(/\s/)
+
+    ask(ctx, "Read the skill_coordinator memory and follow it for this goal:\n\n#{goal}",
+        "asked chi to coordinate it; a running turn gets it at its next step")
+  end
+
+  # /coordinate resume [name]
+  def resume(name, ctx)
+    open = open_handoffs(ctx)
+    if name.empty?
+      return "no open coordinator handoff (handoff_* memory) in this project" if open.empty?
+      return resume_card(open, ctx) if open.size > 1
+
+      name = open.first[:name]
+    end
+    name = "handoff_#{name}" unless name.start_with?("handoff_")
+    unless open.any? { |handoff| handoff[:name] == name }
+      return "/coordinate resume: no open handoff #{name} in this project (#{open.empty? ? "none is open" : "open: #{open.map { |h| h[:name] }.join(", ")}"})"
+    end
+
+    ask(ctx, "Read the skill_coordinator memory and resume the coordinator handoff #{name}: follow the skill's " \
+             "Resume (step 0) before anything else.",
+        "asked chi to resume #{name}; a running turn gets it at its next step")
+  end
+
+  def resume_card(open, ctx)
+    body = open.map { |handoff| "- #{handoff[:name]}#{" — #{handoff[:description]}" unless handoff[:description].empty?}" }
+    actions = open.first(MAX_RESUMES).map do |handoff|
+      { label: "Resume #{handoff[:name].delete_prefix("handoff_")}", command: "/coordinate resume #{handoff[:name]}" }
+    end
+    ctx.card(id: RESUME_CARD_ID, title: "open handoffs (#{open.size})", body: body.join("\n"), actions: actions)
+    nil
+  end
+
+  # The project's handoff_* memories whose index line isn't DONE, in index
+  # order: [{name:, description:}]. A line without its file is left out.
+  def open_handoffs(ctx)
+    dir = Samagotchi::MemoryPaths.scope_dir("project", cwd: ctx.cwd)
+    index = File.join(dir.to_s, "index.md")
+    return [] unless File.file?(index)
+
+    File.read(index, encoding: "UTF-8").each_line.filter_map do |line|
+      match = line.chomp.match(HANDOFF_LINE) or next
+      description = match[2].split(" — ", 2)[1].to_s.strip
+      next if description.match?(/\ADONE\b/i)
+      next unless File.file?(File.join(dir, "#{match[1]}.md"))
+
+      { name: match[1], description: description }
+    end
+  rescue SystemCallError
+    []
+  end
+
+  def ask(ctx, request, done)
     begin
       ctx.sessions.send(ctx.session_id, request)
     rescue Samagotchi::Plugin::Sessions::Error => e
       return "/coordinate: #{e.message}. Send this yourself:\n\n#{request}"
     end
-    "asked chi to coordinate it; a running turn gets it at its next step"
+    done
   end
 
   def quote(text)