samagotchi 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a970676ddf9dacd7bd644f66dcdf28f68a49c6cb24caf2bc785656cb6a2d286
-  data.tar.gz: 8babf6d8562a213f07c3053b7efde79aae43ba4d51fef8ce16b933d17894acd0
+  metadata.gz: 15887ec5fe31be3f32d3e1bfa15b9cf5ca73b03e2101f6416eb2cfad4c2f477a
+  data.tar.gz: 2226f5343806c3171babc66d075fc57498af03d313f180458e4f6ee1801c7384
 SHA512:
-  metadata.gz: 9727a14cff5153a0a061d9e787aebd0e0ea7494781e63386405b261fb4391d04bef56d4fefa346c9d0f2081d49fe7eddeadc3f6bb1b4ef8edc6478f5d273db6f
-  data.tar.gz: 3dc9840ef7eba85ea3160bb2ac84412e9be6219c4e9bdbabc89796d2ee677adeb7903d4ef1002d82cae12daefac3ca6545f1f6519466bcfda164e2c126fd699e
+  metadata.gz: 8986ea963bda07138d6874b9024a031c5c6c000d03bad8281c9c24f57a079234fab5de68efe08305dd38ea4f138bf7ef7b02637e310e69f061182bb17d01d8a3
+  data.tar.gz: d9e07e7a5bacd114b8916a538fa2265bbd5b43ed78373fc306766455788b75ef5c1b0eb21d054288887483c93385063293150339abf4e3d02284bc1320cd9509

data/CHANGELOG.md

@@ -8,6 +8,29 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.37.0] - 2026-10-07
+
+### Added
+
+- For plugin authors: a tool's `targets:` may return `acts_as:` (the tool a call stands for, like an MCP tool behind
+  a dispatcher), `args:` (the arguments it acts with) and `label:` (the name the approval question shows). A guardrail
+  rule's `tool:` then matches either name, and "allow this call" is keyed by both names and those arguments. It can't
+  name one of chi's own tools or another bundle's (dropped and logged). See [docs/plugins.md](docs/plugins.md#guardrails).
+- `chi broadcast` asks a small triage model about the sessions no tag matched, instead of skipping them: it reads the
+  note and each session's scope card and answers yes or no ("model: yes (p 0.91)" when the host gives logprobs,
+  graded by `broadcast.threshold`). The model is `broadcast.triage_model` (with `triage_host_ref` or
+  `triage_base_url`), else the recap's, else `default.model`; a ~9B instruct model or larger works well. Up to
+  `broadcast.triage_parallel` (4) requests run at once, all within `broadcast.triage_deadline` (20 s): a session not
+  judged by then, or whose request failed, gets the note anyway, and the summary line counts it ("1 unchecked: triage
+  deadline"). A first line naming one project ("shopfront/checkout") keeps the note to that project's sessions.
+  `--dry-run` runs triage too. See [docs/broadcast.md](docs/broadcast.md#triage).
+- `chi broadcast` prints the broadcast's id and logs each recipient's verdict (`~/.local/state/samagotchi/broadcast/log.jsonl`,
+  rotated at 2 MiB). `chi broadcast log [--last N] [--format json]` shows the last broadcasts and who got them, and
+  `chi broadcast deliver BROADCAST_ID ID...` gives one to sessions it skipped, after all. See
+  [docs/broadcast.md](docs/broadcast.md#the-triage-log).
+
+Update with `chi update` (mcp 0.5.1).
+
 ## [0.36.0] - 2026-10-07
 
 ### Added
@@ -1782,7 +1805,8 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.36.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.37.0...HEAD
+[0.37.0]: https://github.com/dm1try/samagotchi/compare/v0.36.0...v0.37.0
 [0.36.0]: https://github.com/dm1try/samagotchi/compare/v0.35.0...v0.36.0
 [0.35.0]: https://github.com/dm1try/samagotchi/compare/v0.34.0...v0.35.0
 [0.34.0]: https://github.com/dm1try/samagotchi/compare/v0.33.0...v0.34.0

data/README.md

@@ -120,7 +120,7 @@ chi web --open                            # web UI: this project's sessions (--s
 chi web --web-host lan                    # the web UI on your phone too: scan the QR code it prints
 chi sessions list                         # this project's saved sessions (--scope=all: every one)
 pbpaste | chi note --source slack <id>    # background context for a session (no turn)
-chi broadcast -m "payments API is down"   # the same for every session it concerns (a shared ticket, PR or link)
+chi broadcast -m "payments API is down"   # the same for every session it concerns (a shared tag, or a triage model says so)
 chi context add <PR URL> <id>             # attached context: chi keeps it fresh, the agent hears when it changes
 pbpaste | chi send -m "same bug?" <id>    # a message to a session, the clipboard quoted above it
 chi send --new --wait -m "review feat/x"  # a new session you can watch in the web; prints the answer
@@ -203,7 +203,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Memory](docs/memory.md): scopes and model-specific overlays
 - [Sessions](docs/sessions.md): storage, retention, `chi sessions`
 - [Attached context](docs/context.md): `chi context`, sources, scopes, waking, the github-pr bundle, safety
-- [Broadcast](docs/broadcast.md): `chi broadcast`, who a note reaches, tags, what a session gets
+- [Broadcast](docs/broadcast.md): `chi broadcast`, who a note reaches, tags, triage, what a session gets, the triage log
 - [chi as a sub-agent](docs/sub-agent.md): `chi send --wait --format json`, `chi answer`, instructions for a parent agent
 - [Desktop helper](docs/desktop.md): `chi desktop`, the macOS "Send to chi" Service and hotkey
 - [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals

data/bin/chi

@@ -97,7 +97,7 @@ parser = OptionParser.new do |opts|
            chi web [--port PORT] [--open] [--scope=all]   the web UI
            chi sessions <list|stop|archive|unarchive|delete|prune|clean>
            chi note [--source NAME] [-m TEXT] ID...|--all   background context for sessions
-           chi broadcast [-m TEXT] [--all] [--dry-run]   a note for every session it may concern
+           chi broadcast [-m TEXT] [--all] [--dry-run] | log | deliver   a note for every session it may concern
            chi context <add|push|ls|show|refresh|rm|mute|unmute>   live external text attached to sessions
            chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
            chi answer ID --question QID --option N   answer a question a session waits on

data/docs/broadcast.md

@@ -12,6 +12,8 @@ chi broadcast -m "payments API returns 500 since 14:00 (PAY-123)"
 pbpaste | chi broadcast              # the note from stdin
 chi broadcast --dry-run -m "…"       # who would get it and why; nothing is delivered
 chi broadcast --all -m "deploy freeze until 18:00"   # every recipient, tag or not
+chi broadcast log                    # the last broadcasts and who got them
+chi broadcast deliver b-7f3a1c9e c0ffee12   # one it skipped, after all
 ```
 
 To tell one session or a few you picked, use `chi note ID...` instead.
@@ -47,30 +49,69 @@ so `acme/shop#42` doesn't match `acme/other#42`; `PR #42` with no repo matches
 pull request 42 of any repo. Words the default ticket pattern would take that
 are no ticket (`UTF-8`, `SHA-256`, `ISO-8601`, `GPT-4`, …) are left out.
 
-A session that shares no tag is skipped for now, listed as "no tag match (not
-checked: no triage yet)": a small triage model that reads the note and each
-session's scope card is the next step. Until then, `--all` reaches them all.
+A session that shares no tag goes to triage.
+
+## Triage
+
+A small model reads the note and each other recipient's scope card (below)
+and answers yes or no: would the agent working there want to know? A yes
+delivers the note, a no skips the session ("model: no"). `--all` skips tags
+and triage and reaches every recipient.
+
+- **The model:** `broadcast.triage_model` (with `broadcast.triage_host_ref` or
+  `broadcast.triage_base_url`, as the `recap.*` settings take them); with none
+  of them set, the [recap's](sessions.md) model, else `default.model`. A ~9B
+  dense instruct model or larger works well (qwen3.5-9b missed no session in
+  our tests and sent about one extra note per broadcast of 20 sessions);
+  4B-class models say yes to nearly everything. A local model keeps the
+  cards (your prompts, recaps) on your machine; a remote triage host is your
+  explicit choice. Thinking is off, and each answer is a word.
+- **A score, when the host gives one:** with logprobs (OpenAI, OpenRouter
+  for some models), the verdict is P(yes) of the answer's first token, shown as
+  "model: yes (p 0.83)", and a session needs `broadcast.threshold` (0.5). A
+  higher threshold drops real "this blocks you" notes first. A host that
+  refuses logprobs (llama.cpp's, some gateways) is asked again without them:
+  the plain answer counts as 1 or 0.
+- **A scope line:** when the note's first line names exactly one of the
+  recipients' projects as a word (`shopfront/checkout`, `infra / ci`), the
+  other projects' sessions, and sessions outside any project, are skipped:
+  "scope line names shopfront". Anything fuzzier ("for payments folks") is the
+  model's job; it sees the line too. A one-line note counts as its own first
+  line: with a project named after a common word (`web`, `docs`), "the web
+  composer docs moved" names it and keeps the note there.
+- **Fail open:** at most `broadcast.triage_parallel` (4) requests run at a
+  time, all within `broadcast.triage_deadline` (20 s; a local server's first
+  request after a pause can take 10 s). A session not judged by then, one
+  whose request failed, or one the model answered with neither yes nor no
+  gets the note anyway, "unchecked: triage deadline", and the summary line
+  counts them: a missed session is worse than an extra note. Without a
+  triage model to ask (settings that don't resolve) every such session gets
+  it unchecked, and chi says why.
 
 ## What it prints
 
 One line per recipient, the ones that got it first, then a summary:
 
 ```
-broadcast  "payments API returns 500 since 14:00 (PAY-123)"
+broadcast b-7f3a1c9e  "payments API returns 500 since 14:00 (PAY-123)"
 3f2a1c9e  delivered  ticket PAY-123 matches (branch)
 91ab02c4  delivered  link notion.so/team/checkout-v2 matches (messages); waits for its next start
-c0ffee12  skipped    no tag match (not checked: no triage yet)
+5e1f0a77  delivered  model: yes (p 0.91)
+77aa0b3c  delivered  unchecked: triage deadline
+c0ffee12  skipped    model: no
 d00dad00  skipped    open in a chi REPL
-delivered 2 · skipped 2
+delivered 4 · skipped 2 · 1 unchecked: triage deadline
 ```
 
-A session a worker runs adds the note within a few seconds (after a running
+The first line names the broadcast (`b-7f3a1c9e`): `chi broadcast log` and
+`chi broadcast deliver` take it. A session a worker runs adds the note within a few seconds (after a running
 turn); one with no worker gets it at its next start ("waits for its next
 start"). Nothing starts a turn anywhere.
 
 `--dry-run` prints the note's tags, each recipient's verdict ("would get it" or
-"skipped") and its scope card: what chi knows about it from local state, and
-what a triage model will read.
+"skipped"; triage runs) and its scope card: what chi knows about it from local
+state, and what the triage model reads. A line before them names the triage model
+and the setting it came from.
 
 ```
 3f2a1c9e  would get it  ticket PAY-123 matches (branch)
@@ -83,7 +124,8 @@ what a triage model will read.
 ```
 
 Exit status: 0 when it ran (skipped sessions included), 1 when it was refused,
-no session is active or a delivery failed, 2 for a usage error.
+no session is active or a delivery failed, 2 for a usage error. `chi broadcast
+deliver` exits 0 when every session named has the note now, 1 otherwise.
 
 ## What a session gets
 
@@ -96,7 +138,8 @@ payments API returns 500 since 14:00 (PAY-123)
 [END NOTE]
 ```
 
-With `--all` the line says "with every active session". The date is there
+With `--all` the line says "with every active session"; one that triage
+delivered says "with the sessions it may concern." and no reason. The date is there
 because a session with no worker may read it days later. The system prompt
 tells the model what a note from `broadcast` is: if it affects its current
 work, it says so briefly in its next answer, otherwise it ignores it, and it
@@ -107,9 +150,37 @@ plain note can't pass for a broadcast.
 The note and its line together are capped at 16 KiB like any note; the text
 may take up to 15872 bytes.
 
+## The triage log
+
+Each broadcast (not a `--dry-run`) leaves one line in
+`$XDG_STATE_HOME/samagotchi/broadcast/log.jsonl` (`~/.local/state/…`): its
+id, time, your text, the note's tags and each recipient's verdict (result,
+reason, P(yes), who decided, the session's tags). Scope cards are not kept:
+they quote your prompts. Past 2 MiB the file becomes `log.jsonl.1`, one old
+file kept. Sessions don't read it: a broadcast stays fire-and-forget.
+
+```sh
+chi broadcast log                  # the last 5 broadcasts
+chi broadcast log --last 20 --format json
+```
+
+```
+b-7f3a1c9e  2026-10-06 14:20  "payments API returns 500 since 14:00 (PAY-123)"
+  3f2a1c9e  delivered  ticket PAY-123 matches (branch)
+  c0ffee12  skipped    model: no
+  delivered 1 · skipped 1
+  2026-10-06 14:31 delivered anyway: c0ffee12
+```
+
+When triage skipped a session that needed the note, `chi broadcast deliver
+BROADCAST_ID ID...` (an id or the start of one, for both) gives it the logged
+text, dated when it was shared and saying you passed it on. A session that
+got it already is left alone. The log keeps it as a correction: labels for
+tuning `broadcast.threshold`, or for a classifier later.
+
 ## For you, not for an agent
 
-`chi broadcast` refuses to run inside a chi session (where
+`chi broadcast` (`log` and `deliver` too) refuses to run inside a chi session (where
 `SAMAGOTCHI_PARENT_SESSION` is set): "chi broadcast is for your user, not an
 agent". With the guardrails bundle, the `chi-broadcast` rule also asks before
 any shell command that runs it, once at a time, and only you may allow it
@@ -121,9 +192,17 @@ any shell command that runs it, once at a time, and only you may allow it
 |---|---|---|
 | `broadcast.active_hours` | `8` | A session with no worker or REPL counts when its last turn ended within this many hours. |
 | `broadcast.ticket_pattern` | `\b[A-Z][A-Z0-9]+-\d+\b` | A Ruby regex for ticket ids; an invalid one warns and the default is used. |
+| `broadcast.triage_model` | recap's, else `default.model` | The triage model, a model ref (`box:qwen3.5-9b`). |
+| `broadcast.triage_host_ref` | none | A `hosts:` name for it. |
+| `broadcast.triage_base_url` | none | An OpenAI API base for it instead. |
+| `broadcast.triage_parallel` | `4` | Triage requests at a time. |
+| `broadcast.triage_deadline` | `20` | Seconds triage may take in all; the rest get the note unchecked. |
+| `broadcast.threshold` | `0.5` | The P(yes) a session needs when the host gives logprobs. |
 
 ```yaml
 broadcast:
   active_hours: 12
   ticket_pattern: '\b(?:PAY|OPS)-\d+\b'
+  triage_model: box:qwen3.5-9b
+  triage_deadline: 30
 ```

data/docs/configuration.md

@@ -742,7 +742,8 @@ One record is one line, plus indented payload lines at debug level:
   control characters (terminal colours in tool output) are escaped.
 - Tags: `turn` (a session's event trail), `http` (model requests),
   `worker`, `bridge`, `web`, `attached`, `repl`, `idle`, `recap`, `hooks`,
-  `plugins`, `guardrails`, `config`, `memory`, `model` (debug dumps), `context` (attached context fetches).
+  `plugins`, `guardrails`, `config`, `memory`, `model` (debug dumps), `context` (attached context fetches),
+  `broadcast` (chi broadcast's triage).
 - The format is parsed by `Samagotchi::LogLine` (`parse`, `each_record`);
   keep tools that read it on that parser.
 
@@ -884,6 +885,12 @@ described in their own sections.
 | `recap.sentences` | `2-4` | yes | Recap length, `N` or `N-M` (1–10). |
 | `broadcast.active_hours` | `8` | | `chi broadcast` reaches a session a worker or a chi REPL runs, or whose last turn ended within this many hours. See [Broadcast](broadcast.md). |
 | `broadcast.ticket_pattern` | `\b[A-Z][A-Z0-9]+-\d+\b` | | A Ruby regex for ticket ids; one in the note and in a session's branch (any case) or prompts delivers the broadcast there. See [Broadcast](broadcast.md). |
+| `broadcast.triage_model` | recap's | | The model that judges a recipient no tag matched (a model ref, as `recap.model`); unset: the recap's model, else `default.model`. A ~9B dense instruct model or larger; 4B-class ones say yes to nearly everything. See [Broadcast](broadcast.md#triage). |
+| `broadcast.triage_host_ref` | none | | A `hosts:` name for the triage model. |
+| `broadcast.triage_base_url` | none | | An OpenAI API base for the triage model instead (`http://h:8081/v1`). |
+| `broadcast.triage_parallel` | `4` | | Triage requests at a time. |
+| `broadcast.triage_deadline` | `20` | | Seconds triage may take in all; a recipient not judged by then gets the note unchecked. |
+| `broadcast.threshold` | `0.5` | | The P(yes) a recipient needs, when the triage host gives logprobs; a plain yes or no is 1 or 0. |
 | `session.shared` | `true` | | Plain `chi` runs its session in a worker and attaches; `--no-shared` per run. |
 | `session.idle_exit_minutes` | `30` | yes | An unused worker exits after this; `0` = never. |
 | `session.keep_empty` | `false` | | Keep sessions nothing happened in. |

data/docs/guardrails.md

@@ -292,6 +292,21 @@ A plugin tool whose `targets:` name no command or path (an MCP tool) is asked
 about with its arguments (`mcp_x_sum: a=20 b=22`), and an approval of "this
 call" is keyed by them.
 
+A plugin tool that runs other tools for the model (a dispatcher such as
+`mcp_call`) can say, in its `targets:`, which tool a call acts as (`acts_as:`)
+and with which arguments (`args:`). A rule's `tool:` then matches the call's
+own name **or** the tool it acts as: `tool: mcp_github_*` fires for an
+`mcp_call` that acts as `mcp_github_merge_pull_request`, and `tool: mcp_call`
+fires whatever it acts as. The question names the tool it acts as (by the
+`label:` its `targets:` gives, if any: display only) and shows its arguments, and an approval of "this call" is keyed by the real name, the
+alias and those arguments (`/guardrails` lists it as
+`mcp_call>mcp_github_merge_pull_request:number=7 …`), so it never covers a
+direct call of that tool, nor a direct call's approval it. A tool can't act as
+one of chi's own tools or another bundle's tool: that `acts_as:` is dropped
+(and logged as `plugin_acts_as_dropped`), and the call is matched by its own
+name only. Hooks and loop-guard's `ignore_tools` still see the call's own
+name.
+
 ```yaml
     - id: mcp-ask
       tool: "mcp_*"          # every MCP tool (the mcp bundle's mcp_<server>_<tool>)

data/docs/plugins.md

@@ -162,8 +162,8 @@ in the chat path's `tools:`, after chi's own tools.
   it raises, the default is shown. Both are saved with the call's result, so
   a web page reloaded later shows the same row: the web server doesn't run
   plugins.
-- `targets`: `->(args) { { paths: [...], command: "…", cwd: "…" } }`, each
-  key optional, says what a call acts on, for [guardrails](#guardrails).
+- `targets`: `->(args) { { paths: [...], command: "…", cwd: "…", acts_as: "…", args: {…}, label: "…" } }`,
+  each key optional, says what a call acts on, for [guardrails](#guardrails).
 
 The block returns the result text. If it starts with `Error:`, it counts as
 a failure. If it raises, the model gets `Error: <message>`. To return images
@@ -234,6 +234,27 @@ is what `targets:` says:
   paths (chi's config, …) match them.
 - `command:`: a shell command the call runs; `command:` rules match it.
 - `cwd:`: where it runs, for the repo root and relative paths.
+- `acts_as:`: the tool a call stands for, when the tool runs other tools
+  (the mcp bundle's `mcp_call`). Rules keyed by that tool's name match the
+  call too, as well as rules on the tool's own name. It can't be one of
+  chi's own tools or another bundle's tool: that is dropped (and logged).
+- `args:`: the arguments it acts with (a Hash), when they aren't the call's
+  own (a dispatcher's inner arguments). A call with no `command:` or
+  `paths:` is asked about with them, and "allow this call" is keyed by them.
+- `label:`: what the approval question names the call by (`github: x`), in
+  place of the tool's `label` (or, with `acts_as:`, that tool's). Display
+  only: rules and approvals don't read it. One line of at most 80
+  characters, else it is ignored (and logged).
+
+```ruby
+targets: ->(args) { { acts_as: "mcp_#{args["server"]}_#{args["tool"]}", args: args["args"],
+                      label: "#{args["server"]}: #{args["tool"]}" } }
+```
+
+An approval of an `acts_as:` call keys on the tool's own name as well
+(`mcp_call>mcp_github_x:…`), so it never stands in for an approval of the
+tool it acts as, nor that one for it. Hooks see the call's own name, and so
+does loop-guard's `ignore_tools`.
 
 A tool without `targets:` is matched by its name only. A `targets:` that
 raises counts as nothing (it is logged). See [guardrails.md](guardrails.md).

data/lib/samagotchi/broadcast/triage.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require_relative "../idle_client"
+require_relative "../idle_target"
+require_relative "../cancellation_controller"
+require_relative "../log"
+require_relative "tags"
+
+module Samagotchi
+  module Broadcast
+    # Whether a broadcast concerns a recipient its tags didn't match: a
+    # small model reads the note and the session's ScopeCard and answers
+    # yes or no (Triage::LLM). Many recipients are judged in parallel under
+    # one deadline (Triage.judge_all); whatever isn't judged by then, or
+    # fails, is delivered unchecked (fail open: a missed recipient is worse
+    # than an extra note).
+    module Triage
+      # One recipient's verdict.
+      # @!attribute relevant [Boolean] it gets the note
+      # @!attribute p [Float, nil] the model's P(yes) from its logprobs,
+      #   1.0 or 0.0 from a plain answer, nil when no model judged it
+      # @!attribute reason [String] why, for the output and the log
+      # @!attribute by [String] who decided: "tags" (a shared tag),
+      #   "model", "fallback" (delivered unchecked: deadline, error, an
+      #   answer that is no yes or no), "scope" (the note's first line
+      #   names another project), "all" (--all) or "repl" (a chi REPL owns
+      #   it: no notes)
+      # @!attribute match [Match, nil] the shared tag (by "tags")
+      Verdict = Data.define(:relevant, :p, :reason, :by, :match) do
+        def initialize(match: nil, **) = super
+
+        def unchecked? = by == "fallback"
+      end
+
+      # The spike's prompt (plain yes/no beat JSON with a p and a reason
+      # for every model tried: writing a reason pushes towards "relevant").
+      SYSTEM = <<~TEXT
+        You route short notes that a developer broadcasts to their running coding-agent sessions.
+        You get one note and one session's card (project, branch, title, what the session was started for, its latest recap, the last request).
+        Decide whether the note may affect THIS session's current work: would the agent working on it want to know?
+        A note can start with an informal scope line (a project, a component, a team); use it as a hint.
+        Notes about things unrelated to the session's work (social, other projects, other components) are not relevant.
+        Answer with exactly one word: yes or no.
+      TEXT
+
+      DEFAULT_PARALLEL = 4
+      DEFAULT_DEADLINE = 20.0
+      DEFAULT_THRESHOLD = 0.5
+      # How long threads still asking get to stop once the deadline passed.
+      JOIN_GRACE = 1.0
+
+      module_function
+
+      # @return [Verdict] delivered unchecked, +why+ in the reason
+      def unchecked(why) = Verdict.new(relevant: true, p: nil, reason: "unchecked: #{why}", by: "fallback")
+
+      # The messages a model judges +note+ for +card+ by.
+      def messages(note, card)
+        [{ role: "system", content: SYSTEM }, { role: "user", content: "NOTE:\n#{note}\n\nSESSION CARD:\n#{card}" }]
+      end
+
+      # The one project the note's first line names, as a whole word (any
+      # case), among +projects+ (the recipients' project names); nil when it
+      # names none or several. A scope line ("shopfront/checkout", "agentd
+      # web") then keeps the note to that project's sessions; anything
+      # fuzzier is the model's job.
+      # @param projects [Array<String>]
+      # @return [String, nil]
+      def scope_project(note, projects)
+        line = note.to_s.lines.first.to_s.downcase
+        named = projects.compact.uniq.select do |project|
+          line.match?(/(?<![[:alnum:]_-])#{Regexp.escape(project.downcase)}(?![[:alnum:]_-])/)
+        end
+        named.one? ? named.first : nil
+      end
+
+      # Every card's verdict: a shared tag delivers (Tags.match); a note
+      # whose first line names one of the projects (scope_project) skips
+      # the other projects' sessions; the model judges the rest
+      # (judge_all, +judge+ its keywords).
+      # @param cards [Array<ScopeCard>]
+      # @param note_tags [Array<Tag>]
+      # @return [Hash{String => Verdict}] by card id, in +cards+' order
+      def verdicts(note, cards, note_tags:, new_backend:, **judge)
+        scope = scope_project(note, cards.map(&:project))
+        decided = cards.to_h do |card|
+          match = Tags.match(note_tags, card.tags)
+          verdict = if match
+                      Verdict.new(relevant: true, p: nil, reason: match.reason, by: "tags", match: match)
+                    elsif scope && card.project != scope
+                      Verdict.new(relevant: false, p: nil, reason: "scope line names #{scope}", by: "scope")
+                    end
+          [card.id, verdict]
+        end
+        judged = judge_all(note, cards.reject { |card| decided[card.id] }, new_backend: new_backend, **judge)
+        cards.to_h { |card| [card.id, decided[card.id] || judged.fetch(card.id)] }
+      end
+
+      # Judges +cards+ with at most +parallel+ backends at a time, one per
+      # thread (a backend keeps per-host state), all under +deadline+
+      # seconds. A card not judged by then is delivered unchecked; the
+      # requests still running are cancelled.
+      # @param new_backend [#call] (CancellationController) → a backend:
+      #   #judge(note, card) → Verdict
+      # @param cards [Array<ScopeCard>]
+      # @return [Hash{String => Verdict}] by card id
+      def judge_all(note, cards, new_backend:, parallel: DEFAULT_PARALLEL, deadline: DEFAULT_DEADLINE,
+                    clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+        return {} if cards.empty?
+
+        queue = Queue.new
+        cards.each { |card| queue << card }
+        queue.close
+        results = {}
+        lock = Mutex.new
+        changed = ConditionVariable.new
+        cancel = CancellationController.new
+        ends = clock.call + deadline.to_f
+        finished = 0
+        threads = Array.new(parallel.to_i.clamp(1, cards.size)) do
+          Thread.new do
+            card = nil
+            backend = new_backend.call(cancel)
+            while (card = queue.pop)
+              verdict = judge_one(backend, note, card)
+              lock.synchronize do
+                results[card.id] = verdict unless cancel.cancelled?
+                changed.broadcast
+              end
+              card = nil
+            end
+          rescue StandardError => e
+            # No backend (or a bug around it): this thread's card and the
+            # ones it takes from here on are delivered unchecked at once,
+            # so nobody waits for the deadline.
+            Log.exception(:broadcast, "triage_thread_failed", e)
+            failed = unchecked("triage failed (#{e.class})")
+            lock.synchronize { results[card.id] ||= failed if card }
+            while (card = queue.pop)
+              lock.synchronize { results[card.id] ||= failed }
+            end
+          ensure
+            lock.synchronize do
+              finished += 1
+              changed.broadcast
+            end
+          end
+        end
+        lock.synchronize do
+          loop do
+            break if results.size == cards.size || finished == threads.size
+
+            left = ends - clock.call
+            break if left <= 0
+
+            changed.wait(lock, left)
+          end
+          cancel.cancel!(:deadline)
+          queue.clear
+        end
+        threads.each { |thread| thread.join(JOIN_GRACE) || thread.kill }
+        cards.to_h { |card| [card.id, results[card.id] || unchecked("triage deadline")] }
+      end
+
+      def judge_one(backend, note, card)
+        backend.judge(note, card)
+      rescue Samagotchi::LLM::RequestCancelled
+        unchecked("triage deadline")
+      rescue StandardError => e
+        Log.exception(:broadcast, "triage_failed", e)
+        unchecked("triage failed (#{e.class})")
+      end
+      private_class_method :judge_one
+
+      # A triage model on an OpenAI-compatible host (an IdleTarget), asked
+      # through its own IdleClient: thinking off, a few tokens, the first
+      # token's logprobs when the host gives them. P(yes) / (P(yes) +
+      # P(no)) from those is graded against +threshold+; a plain yes or no
+      # is 1.0 or 0.0.
+      class LLM
+        MAX_TOKENS = 16
+        TOP_LOGPROBS = 5
+        LOGPROB_OPTIONS = { logprobs: true, top_logprobs: TOP_LOGPROBS }.freeze
+        # Hosts (base urls) that refused logprobs with a 400: asked without
+        # them from then on, in this process.
+        @no_logprobs = Set.new
+        @no_logprobs_lock = Mutex.new
+
+        class << self
+          def logprobs?(base_url) = @no_logprobs_lock.synchronize { !@no_logprobs.include?(base_url) }
+
+          def no_logprobs!(base_url) = @no_logprobs_lock.synchronize { @no_logprobs << base_url }
+
+          # Specs: forget the hosts that refused.
+          def reset_logprobs! = @no_logprobs_lock.synchronize { @no_logprobs.clear }
+        end
+
+        # @param target [IdleTarget]
+        # @param timeout [Numeric] each request's
+        # @param client [IdleClient, nil] specs inject one
+        def initialize(target:, timeout:, threshold: DEFAULT_THRESHOLD, cancel_controller: nil, client: nil)
+          @target = target
+          @threshold = threshold.to_f
+          @cancel = cancel_controller
+          @client = client || IdleClient.for(target, timeout: timeout, purpose: "broadcast")
+        end
+
+        # @return [Verdict]
+        # @raise [Samagotchi::LLM::RequestCancelled] the deadline passed
+        def judge(note, card)
+          answer = ask(Triage.messages(note, card))
+          word = self.class.word(answer.text)
+          return Triage.unchecked("the model answered #{answer.text.to_s.strip[0, 40].inspect}") unless word
+
+          p = self.class.logprob_p(answer.top_logprobs, word: word)
+          relevant = p ? p >= @threshold : word == "yes"
+          reason = "model: #{relevant ? "yes" : "no"}#{format(" (p %.2f)", p) if p}"
+          Verdict.new(relevant: relevant, p: p || (word == "yes" ? 1.0 : 0.0), reason: reason, by: "model")
+        rescue IdleClient::SummarizeError => e
+          Triage.unchecked("the model failed (#{e.message[0, 120]})")
+        end
+
+        # "yes" or "no": the answer's first such word (thinking left out),
+        # nil when it has neither.
+        def self.word(text)
+          text.to_s.gsub(%r{<think>.*?</think>}m, "").strip.downcase[/\A\W*(yes|no)\b/, 1]
+        end
+
+        # P(yes) / (P(yes) + P(no)) over the first token's alternatives
+        # ("Yes", " yes" count as yes), when that token is the answer +word+
+        # itself: its likeliest alternative is yes or no and agrees with
+        # +word+. nil otherwise (an answer starting "**", "<think>" or a
+        # quote: those alternatives say nothing about yes or no).
+        # @param top [Array<Samagotchi::LLM::TokenLogprob>]
+        # @return [Float, nil]
+        def self.logprob_p(top, word:)
+          first = top.max_by(&:logprob)
+          return nil unless first && first.token.strip.downcase == word
+
+          sum = ->(want) { top.select { |t| t.token.strip.downcase == want }.sum { |t| Math.exp(t.logprob) } }
+          yes = sum.call("yes")
+          no = sum.call("no")
+          (yes / (yes + no)).round(4)
+        end
+
+        private
+
+        def ask(messages)
+          base_url = @target.base_url
+          options = self.class.logprobs?(base_url) ? LOGPROB_OPTIONS : {}
+          begin
+            @client.ask(messages, max_tokens: MAX_TOKENS, cancel_controller: @cancel, kind: "broadcast", options: options)
+          rescue IdleClient::SummarizeError => e
+            raise unless !options.empty? && e.cause.is_a?(Samagotchi::LLM::BadRequest)
+
+            # The host won't give logprobs (a server that refuses "n and
+            # logprobs"): ask again without, and leave them out from now on.
+            self.class.no_logprobs!(base_url)
+            Log.info(:broadcast, "logprobs_refused", model: @target.label, detail: e.cause.message.to_s[0, 200])
+            options = {}
+            retry
+          end
+        end
+      end
+    end
+  end
+end