samagotchi 0.34.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6f812c6128ae3ffaf91d9cc04716a77d351fb57793a7d9a4863e675f1f2337f
-  data.tar.gz: 25e7600fe6dc335b7d28320795a03ea9e8527185f6a0dd918787777458402f39
+  metadata.gz: b598dac8dadadd4dd37861ed690d09d09926520c2295bc998def4d75c3716ea7
+  data.tar.gz: 9d30ebb820024929bbb2dc1267011af7eb5710b33a4ba9625489a74d111edfbd
 SHA512:
-  metadata.gz: 322e9f5a5b553f7ed1f2955307b8d5bd8c901a355ac3ffcdff6b3fcb5013b28011c7c330d9496486338c77d2c0f58e2854393d4cb40ec33d00ed2516a38bd066
-  data.tar.gz: f6048763f53d9b865858842acaf60587d5e57a365aaba759c3c85fcf69532227c4b201fe0f878da3e48191dd43856637dad29537203a3dfd7159756caac6f778
+  metadata.gz: 2f40ed32d227d1017bc7abcba8ef40f5e38f2f7dd7876aa5f78a9290e5443489b8109183655a151a1345fef1fa3f3f49e5deafbac38059cdba3bec70b0585d71
+  data.tar.gz: 55aca343a9dc45e78791863286768c356e815dc1b9783993f2c4477edb991883a3c88ae208dd642137cab4c6ead58fc1d49228f201fefcd6878dd421c719af70

data/CHANGELOG.md

@@ -8,6 +8,49 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.35.0] - 2026-10-06
+
+### Added
+
+- `chi broadcast -m TEXT` (or stdin) shares a note with every session it may concern, without picking them: your
+  own sessions a worker or a chi REPL runs, or that ended a turn in the last 8 hours (`broadcast.active_hours`),
+  delegate children and scratch sessions left out. One gets it when the note shares a tag with it: a ticket id
+  (`broadcast.ticket_pattern`) in its branch or your prompts there, a pull request attached to it, a link. The rest
+  are listed as skipped; `--all` reaches every one, `--dry-run` shows who would get it and why. The model mentions a
+  broadcast briefly when it affects its current work and doesn't act on it unless asked. For you, not for an agent:
+  refused inside a session, and the guardrails bundle's `chi-broadcast` rule asks. See
+  [docs/broadcast.md](docs/broadcast.md).
+- `chi sessions list --format json` has `delegate`: true for a child the `delegate` tool started, false for a fork.
+- A parent session shows its delegate children at a glance: a `⑂ 3` chip in its web info bar (how many run, wait,
+  are done or failed in the tooltip; the waiting ones in the attention colour; a click opens all sessions), and
+  `⑂ 2 running · 1 waiting` in the terminal's status row.
+- A hook's `event[:notify]` and a plugin's `ctx.notify` take `fallback_for: :display`: the line repeats what the
+  answer's display (`event[:present]`) shows, so a UI that renders the display leaves it out. The web with markdown
+  on does; the REPL, the attached TUI, `chi -p` and the web with markdown off still show it. See
+  [docs/hooks.md](docs/hooks.md#what-a-hook-can-do-the-runtime).
+- Web, all sessions: each card has an archive button (unarchive on an archived one), and Select picks many cards
+  (click, Shift-click a range, "Select all shown") for Archive N / Unarchive M. A session with a running turn is
+  skipped with the reason on its card; one toast at the end has Undo.
+
+### Changed
+
+- source-links 0.4.0 (needs chi 0.35.0; run `chi update`): with markdown on, the web no longer shows the
+  `sources:` line under an answer that links every ref it names; it still shows when a ref is only in code or
+  markdown is off, and the terminals print it as before.
+- `chi note --source broadcast` is refused: that source is `chi broadcast`'s.
+- Web: a parent's delegates fold into its card, on the strip and in all sessions, instead of being cards of their
+  own. A `▸ 3 delegates · 1 live · 1 waiting` chip opens their list (in the card in all sessions, a popover on the
+  strip); it opens by itself while one of them waits on you, and the card then wears the warning colour. A family
+  takes one strip slot, a search finds a parent by its delegates, and select mode picks cards. A fork and a delegate
+  whose parent isn't listed stay cards of their own.
+- guardrails 0.7.0: the `chi-broadcast` rule asks before an agent runs `chi broadcast`.
+
+### Fixed
+
+- Web: a tool row shows how long the call took while you watch the turn, as it does after a reload.
+
+Update with `chi update` (guardrails 0.7.0, source-links 0.4.0).
+
 ## [0.34.0] - 2026-10-06
 
 ### Added
@@ -1708,7 +1751,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.34.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.35.0...HEAD
+[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
 [0.33.0]: https://github.com/dm1try/samagotchi/compare/v0.32.0...v0.33.0
 [0.32.0]: https://github.com/dm1try/samagotchi/compare/v0.31.0...v0.32.0

data/README.md

@@ -120,6 +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 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
@@ -202,6 +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
 - [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

@@ -40,6 +40,8 @@ SUBCOMMANDS = {
   "sessions" => ["samagotchi/sessions_command", "SessionsCommand"],
   # a context note for sessions (-m, --source, --all)
   "note" => ["samagotchi/note_command", "NoteCommand"],
+  # a note for every session it may concern (-m, --all, --dry-run)
+  "broadcast" => ["samagotchi/broadcast_command", "BroadcastCommand"],
   # live external text attached to sessions (add, push, ls, show, rm, mute)
   "context" => ["samagotchi/context_command", "ContextCommand"],
   # a message into sessions as the user's (-m)
@@ -95,6 +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 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

@@ -0,0 +1,129 @@
+# Broadcast
+
+`chi broadcast` shares one piece of information with every session it may
+concern, without picking them: "payments API returns 500 since 14:00 (PAY-123)",
+"the PRD for checkout v2 changed: no guest checkout". Each session it reaches
+gets it as a [context note](sessions.md#context-notes) from `broadcast`, and
+that session's agent decides whether it affects its work. Sessions it doesn't
+concern never see it.
+
+```sh
+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
+```
+
+To tell one session or a few you picked, use `chi note ID...` instead.
+
+## Who it reaches
+
+The recipients are your own sessions, in every project:
+
+- a worker or a chi REPL runs them now, or their last turn ended within
+  `broadcast.active_hours` (default 8). A session with no turn yet counts
+  by its last save;
+- not a delegate child: its parent relays what concerns it (the
+  `coordinator`'s builders included). A fork is your session and counts;
+- not a `chi scratch` session, not an archived one, and not a test run
+  (unless `chi broadcast` itself runs as one, `SAMAGOTCHI_ENV=test`).
+
+A session open in a plain chi REPL (`--no-shared`) can't take notes: it is
+listed as skipped, "open in a chi REPL".
+
+## Tags: which sessions it concerns
+
+A recipient gets the note when the note and the session share a tag:
+
+| Tag | In the note | About the session |
+|---|---|---|
+| ticket | an id like `PAY-123` (`broadcast.ticket_pattern`) | its branch (any case: `feat/pay-123-retry`), your prompts there |
+| pr | `PR #42`, a GitHub pull request URL | an attached `pr-42` source (the github-pr bundle), a PR URL in your prompts there |
+| link | a URL, by host and path | a URL in your prompts there or in an attached context source's hint |
+
+A link is compared without its scheme, `www.`, query, fragment or trailing
+slash; a bare host (`https://github.com/`) is no tag. A PR URL names its repo,
+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.
+
+## 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)"
+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)
+d00dad00  skipped    open in a chi REPL
+delivered 2 · skipped 2
+```
+
+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.
+
+```
+3f2a1c9e  would get it  ticket PAY-123 matches (branch)
+          project: shop (folder ../shop-pay, branch feat/pay-123-retry)
+          title:   shop-pay · now the retry spec
+          tags:    ticket PAY-123 · pr acme/shop#42
+          started: Fix the payments retry …
+          recap:   Fixing the payments retry. Specs next.
+          recent:  now the retry spec
+```
+
+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.
+
+## What a session gets
+
+The note is your text, then one line chi adds:
+
+```
+[CONTEXT NOTE from broadcast, 14:20]
+payments API returns 500 since 14:00 (PAY-123)
+(Shared by your user on 2026-10-06 14:20 with the sessions it may concern; it reached you because ticket PAY-123 matches your branch.)
+[END NOTE]
+```
+
+With `--all` the line says "with every active session". 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
+doesn't act on it unless you ask. Other notes keep their rule (background,
+not mentioned on their own). `chi note --source broadcast` is refused, so a
+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.
+
+## For you, not for an agent
+
+`chi broadcast` 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
+(a parent agent's `chi answer` can't). See [Guardrails](guardrails.md).
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| `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. |
+
+```yaml
+broadcast:
+  active_hours: 12
+  ticket_pattern: '\b(?:PAY|OPS)-\d+\b'
+```

data/docs/cli.md

@@ -790,11 +790,19 @@ changes:
 
 ```
 status> model=Qwen3.6-35B | ↳ 3f2a1c9e | ctx=12.3% (under20) | mem: notes, cli_usage | muted: gh-helper
+status> model=Qwen3.6-35B | ⑂ 2 running · 1 waiting | ctx=8.1% (under20) | mem: skill_coordinator
 ```
 
 - `model=`: the model in use, `(default: …)` beside it when it isn't the config's default, and
   `model=<served> (served; asked <name>)` when the server said it served another model.
 - `↳ <id>`: the session that delegated this one.
+- `⑂ …`: this session's delegate children (forks aren't counted): how many run and how many wait
+  for an answer; only the counts there are, nothing when none does (`/children` has the rest:
+  done, failed, whether a reply was reported). The terminal reads them from the children's files
+  (the delegates in the session's `delegates.json`): an attached one when it joins, when a turn
+  ends and when a delegate's report merges into a turn, the REPL whenever it draws the row. A
+  child that starts waiting on an approval (which doesn't wake the parent) shows at the next of
+  those.
 - `ctx=`: the kernel's context estimate and its bucket, updated during a turn (on hosts that
   report none, `api: openai`, at the turn's end).
 - `mem:`: the memories the session read, with its `--memory` list; `muted:` its `--mute` list.

data/docs/configuration.md

@@ -882,6 +882,8 @@ described in their own sections.
 | `recap.timeout` | `30` | yes | Seconds a recap request may take. |
 | `recap.min_user_turns` | `2` | yes | Prompts a session needs before it gets a recap. |
 | `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). |
 | `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

@@ -5,7 +5,7 @@ loops (native and chat hosts). The verdict is **allow**, **ask** or
 **deny**; the strictest vote wins, and a deny can't be undone by a later
 voter. Of two asks the first one names the rule, except a rule only the
 user may allow (`chi-config`, `chi-hooks`, `shell-touches-chi`,
-`chi-context-cmd`): it takes over, and only the scopes both asks offer
+`chi-context-cmd`, `chi-broadcast`): it takes over, and only the scopes both asks offer
 are offered.
 
 Who votes, in order:
@@ -427,7 +427,9 @@ hooks, approvals, bundles or attached context sources, or a `.git/hooks`
 (`shell-touches-chi`, `touches: chi_dirs`), unless they only read
 (`skip_read_only`); `chi context add … --cmd` (`chi-context-cmd`, once at a
 time: a command chi will run every few minutes outside the guardrails; see
-[Attached context](context.md#safety)); and answering chi's
+[Attached context](context.md#safety)); `chi broadcast` (`chi-broadcast`,
+once at a time and only by the user: it is the user's command, which also
+refuses to run inside a session; see [Broadcast](broadcast.md)); and answering chi's
 questions around `chi answer`: `chi --attach` or `chi -p` with stdin from a
 pipe, a here-string or a file (`chi-answer-piped`), and `curl`/`wget` to a
 session's `/answer` route (`chi-answer-http`), both once or for the session.

data/docs/hooks.md

@@ -82,6 +82,8 @@ class Watchful
     when :after_generation
       # One line in the REPL, the attached TUI and the web ("<bundle>> text",
       # or "hook> text" for a config hook); level: :warn colours it.
+      # fallback_for: :display marks a line a UI that renders the answer's
+      # display may leave out (below).
       event[:notify].call("the model repeated itself", level: :warn)
     when :before_tool_call
       # A single-select question through the question flow (REPL, attached
@@ -114,6 +116,21 @@ end
 known-names)` for a bundle hook, `audit.rb (config)` for a config hook,
 `turn hook` for one registered at runtime.
 
+`event[:notify]` also takes `fallback_for:`, what the line stands in for, so
+that a UI that already shows it can leave the line out. The one value is
+`:display`: the line repeats what the hook's
+[`event[:present]`](#presenting-the-answer-display-only) display shows (its
+links), for a UI that doesn't render that display. The hook never names a UI;
+each decides by what it renders. The web with markdown on (`web.markdown` and
+the commonmarker gem) leaves such a line out, live and after a reload; with
+markdown off it shows, as it does in the REPL, the attached TUI and
+`chi -p`, which print the answer as text. The log keeps the line with
+`fallback_for=display`. Another value, or none, shows the line everywhere.
+Mark a line only when the display really shows all of it (source-links marks
+its note only when the answer links every URL the note names). It needs chi
+0.35.0: an older chi's `event[:notify]` raises `ArgumentError` on the keyword,
+so a bundle that passes it sets `requires_chi: ">= 0.35.0"`.
+
 A steer is saved in the session as `{role: "user", kind: "steer", source:
 "<bundle>", content: "…"}`, its text raw. The model reads it as a user turn
 led by one line naming the sender: `[Steer from the <bundle> plugin,
@@ -504,8 +521,8 @@ sources: JIRA JIRA-123 → https://myjira.com/browse/JIRA-123, JIRA JIRA-10 →
 ```
 
 The note is **not part of the conversation**: it is an event shown to the
-user, never stored in the session file. A UI replays it while the session's
-worker lives (a page reload keeps it; a stopped worker loses it). Only the
+user, never stored in the session file. A UI replays it with the session's
+cards (a page reload keeps it, after the worker stopped too). Only the
 model's final answer is scanned (the last `role: "model"` message), and only
 the first 20 000 characters of it. A ref that is already a link is skipped —
 inside a bare URL (`https://x.com/JIRA-123`), in a markdown link's target, or
@@ -543,7 +560,11 @@ text stays as it was, and the links survive a reload and a stopped worker
 apply, and a ref in code (a `` `span` `` or a fenced block) or anywhere in a
 markdown link is left as it is; past the first 20 000 characters the answer
 is unchanged. The terminals see only the line; `note: false` drops it and
-keeps the web links.
+keeps the web links. With markdown on, the web leaves the line out when the
+answer links every URL it names, since it would only repeat them as plain
+text ([`fallback_for: :display`](#what-a-hook-can-do-the-runtime)); it shows
+when it names one the answer doesn't link (a ref only in code, two sources on
+one ref) and whenever markdown is off. Bundle 0.4.0 needs chi 0.35.0 for that.
 
 The `prefix:` form compiles to `\b<prefix>-(\d+)\b` and the URL is
 `base_url` + the full ref text (`JIRA-123`). The `pattern:` form takes a

data/docs/plugins.md

@@ -488,7 +488,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.log` | `ctx.log.info(:event, key: value)`: debug-log records tagged `plugins`, with `bundle=<bundle>` |
 | `ctx.messages` | the conversation, as a frozen copy, without the system prompt. While a turn runs, a session worker's (attached, web) adds that turn so far: its prompt, the model's text and the lines merged into it (no tool calls or thinking); the REPL's is the conversation before that turn |
 | `ctx.messages_partial?` | whether `ctx.messages` leaves out a running turn (the REPL mid-turn), so a plugin can say what its answer is about |
-| `ctx.notify(text, level: :info)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command) |
+| `ctx.notify(text, level: :info, fallback_for: nil)` | one line to the user, labelled by the bundle (`my-bundle> …`). Every UI shows it, during a turn (a tool, a hook) or between turns (a command). `fallback_for: :display` marks a line that repeats the answer's display (`event[:present]`), which a UI that renders the display leaves out: see [Hooks](hooks.md#what-a-hook-can-do-the-runtime). The keyword needs chi 0.35.0 (it raises on an older chi) |
 | `ctx.card(title:, body: "", actions: [], level: :info, id: nil)` | a card in every UI, returning its id: see [Cards](#cards) |
 | `ctx.ask_user(question:, options:, header: nil, allow_freeform: false)` | a single-select question through the question flow: `{selected:, freeform:, selected_indices:}`, or nil (no one to ask, cancelled, bad options) |
 | `ctx.cancelled?` | whether the running turn was cancelled (a long tool should stop) |

data/docs/sessions.md

@@ -60,14 +60,14 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 
 **Projects:** a session belongs to the git project it was started in: the repository, whichever worktree or subfolder of it (the same project root memories use). `chi sessions list` (with `--live` and `--format` too) and `chi web` show the current folder's project; `--scope=all` shows every session, and so does a folder in no repo (`~`). `--cwd PATH` is a folder filter instead of the project. The project is stored with the session (`project_root` in its JSON, `project` in `--format json`), so a session keeps it after its worktree is deleted; sessions older than that are placed by their folder, and one whose folder is gone shows in `--scope=all` only. Retention, `--resume`/`--attach ID`, `chi send`/`chi note ID` and `chi note --all` (every live session) are not scoped. The agent's `list_sessions` lists its own project's sessions; `cwd: "/"` lists every one.
 
-`--live`, `--cwd` and `--format` make `list` a picker for scripts (`SessionManager.session_summaries`): `--live` keeps the sessions a worker runs now (the owner lock, not the saved status; a session open in a plain REPL is left out), `--cwd PATH` those in PATH or below, and test runs are left out unless the list is itself run as one (`SAMAGOTCHI_ENV=test`, `RACK_ENV=test` or `CI` set: then they show, marked `[test]`; `chi note --all` likewise). `--live` shows 10 unless `--limit` says otherwise; filters apply before the limit. `--format json` prints `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap, parent_id, archived, scratch, ctx_pct}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
+`--live`, `--cwd` and `--format` make `list` a picker for scripts (`SessionManager.session_summaries`): `--live` keeps the sessions a worker runs now (the owner lock, not the saved status; a session open in a plain REPL is left out), `--cwd PATH` those in PATH or below, and test runs are left out unless the list is itself run as one (`SAMAGOTCHI_ENV=test`, `RACK_ENV=test` or `CI` set: then they show, marked `[test]`; `chi note --all` likewise). `--live` shows 10 unless `--limit` says otherwise; filters apply before the limit. `--format json` prints `[{id, short_id, desc, cwd, project, updated_at, live, busy, owner, recap, parent_id, delegate, archived, scratch, ctx_pct}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null; `delegate`: true for a child the `delegate` tool started, false for a fork, which has a `parent_id` too), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
 
 **Ordering:**
 
 - `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
-- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again); "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only. The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first; typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, sampling?}], warning?}`; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat (`hide ▴` puts them away behind a `▾ N sessions` pill, remembered; in a window under 900 px wide, where the strip scrolls sideways, `▴ hide` sits in the top bar where the pill comes back; a window under 700 px tall hides them by itself, so a question or approval card in the stage keeps room, and the pill shows them until the window is tall again). A parent and its delegates are one card there: its `▸ 2 delegates · 1 live · 1 waiting` chip (the waiting part in the attention colour, the card's border too) opens their rows in a popover under it (a row per delegate at any depth, indented; a click opens that one, Esc or a click outside closes it, and the strip's order holds while it is open). A fork is a card of its own, and so is a delegate whose parent isn't listed (archived, another project), with its `↳ <parent>` chip; the pill counts cards, and every live or waiting session. "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). There a parent's card holds its delegates the same way, the chip opening their rows inside the card (each with an archive button on hover), open by itself while one of them waits on you; the count says `14 (+7 delegates)`, a search that matches a delegate shows its parent's card with the list open and the matching rows marked, and select mode picks cards (archiving a parent takes its delegates). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. It shows the context used (`ctx 42%`) and the last generation's decode speed (`87 tok/s`, `~64 tok/s` when estimated; see `/stats` in [cli.md](cli.md#session-commands)); hovering `ctx` there or on a session card lists the session's tokens in (summed over every request, with the cached share), out (with reasoning) and the cost when the provider reports one, for this session only. The start page's model picker (bottom left of the composer, the chosen name `▾`) chooses the model a new chat starts on; it opens a search list over the conversation (↓ or a click; downward when the start page leaves no room above): an empty search shows the last 5 picks (Recent) and then each host's model ids A–Z under the host, the default host first; typed words must each match the host or the id (a substring, else for 3+ characters the letters in order, so `deepseek4.1 fla` finds `openrouter · deepseek/deepseek-v4.1-flash`), ⏎ picks, Esc/Tab close, a pick puts the focus in the message box: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id, sampling?}], warning?}`; `sampling` is the model's configured request parameters as `/model` words them, the row's tooltip in the list; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first line that is one of the new session's commands (`/model …`) goes to `POST /api/sessions/:id/command` instead, as later ones do. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`. In the composer a line is a command when it is `!…` or starts with one of the session's command names (its `commands` list; `/stats`, `/exit` and the other terminal words get the page's own reply); an unknown `/word` (`/usr/bin/env is missing`) goes to the model as a prompt, as in a terminal; a one-word `/word` no command answers (`/modle`) is not sent: the page shows `Unknown command /modle. Did you mean /model? /help lists the commands.` (the "Did you mean" part only when a name is close). A `POST /turn` (or a session's first `prompt`) that is one of the worker's commands runs as that command too (`202 {status, command_id, session_id}`), so `chi send`, `chi -p` and a page whose command list lags all get the command. ↑/↓ in the composer walk the prompt history the TUI's ↑ walks ([Persistent Prompt History](cli.md#persistent-prompt-history)): ↑ with the caret on the first line, ↓ from the last line while browsing, ↓ past the newest brings the draft back; `GET /api/history` returns `{entries: [...]}`, oldest first (the page fetches it on focus and after each send). The server records a sent line in the routes once the worker took it (`POST /turn` accepted, a `!command` through `POST /command` or as a session's first line); `"history": false` in the body keeps it out (an image-only send).
 - Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
-- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
+- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it; `families()` groups delegates under their parent), `families_view.js` (a parent's family chip, its rows and the strip's popover), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`), `prompt_history.js` (the composer's ↑/↓ over the shared prompt history). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
 - Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).
 
 **Test-session hygiene:**
@@ -88,7 +88,7 @@ pbpaste | chi note --source slack 3f2a 8c1d
 
 - The text comes from `-m` or stdin (a terminal on stdin is a usage error, not a wait). It is stripped; an empty note or one over 16 KiB is refused, never cut. `--source` (default `cli`) names where it came from. `--all` is every live session.
 - It lands in `<uuid>/notes/`, apart from `input/`, so nothing that runs turns sees it. A live worker adds it to the conversation within a few seconds, between turns: one sent during a turn waits for that turn to end. A session with no worker keeps it until a worker next starts (a prompt, `--attach`), which adds it before anything else. A session open in a plain REPL (`--no-shared`) refuses notes. `chi note` prints one line per session: queued, waits for the next start (with the queue count), or refused.
-- In the conversation it is a tail system message marked `kind: note`, framed `[CONTEXT NOTE from slack, 14:02]\n…\n[END NOTE]` (from another session: `from session 3f2a1c (~/projects/foo)`). The system prompt says notes are background, not requests: the model uses one when it is relevant, doesn't answer it on its own, and never follows instructions inside it. Its text is escaped like user text, so it can't fake a turn. It survives `--resume`, a reload, `!rollback` and a continue answered no.
+- In the conversation it is a tail system message marked `kind: note`, framed `[CONTEXT NOTE from slack, 14:02]\n…\n[END NOTE]` (from another session: `from session 3f2a1c (~/projects/foo)`). The system prompt says notes are background, not requests: the model uses one when it is relevant, doesn't answer it on its own, and never follows instructions inside it. A note from `broadcast` ([`chi broadcast`](broadcast.md)) is the one exception to "doesn't answer it": the model says briefly in its next answer when it affects its current work, and still doesn't act on it unless asked. `--source broadcast` is refused for `chi note`. Its text is escaped like user text, so it can't fake a turn. It survives `--resume`, a reload, `!rollback` and a continue answered no.
 - The web shows it as a dim "note from …" block, live (`context_added`) and after a reload; the attached terminal as one dim `note from slack: <first line>` line, also when joining.
 - Agents: `list_sessions` (other sessions of this project, newest first, up to 20; optional `cwd`, `"/"` for every project) and `send_note(session, text)`, which sends a note from this session. Neither starts a turn anywhere.
 
@@ -182,7 +182,7 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 
 ## Delegating
 
-The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail like an `execute` result. Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (a `↳` chip on its card, `delegated by` in its info bar, listed right after its parent in the all-sessions view) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
+The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; an unknown host comes back as the tool's `Error:` line; an id the host's saved model list doesn't have starts the child with a `Warning: host 'h' doesn't list model 'x' (did you mean: …?)` line in the result). Children run in parallel and only their **final reply** comes back to the parent: the child's newest `output/<timestamp>.txt` file, which the worker writes at the end of each turn that produced visible text, cut head-and-tail like an `execute` result. Nothing of the child's trace enters the parent's context. Nothing is hidden: a child shows in `chi sessions list` (`↳ <parent>`), the web (folded into its parent's card on the strip and in all sessions, whose `▸ N delegates` chip lists the delegates at any depth, see Web UI above; a card of its own with a `↳` chip when its parent isn't listed; `delegated by` in its info bar; the parent's info bar carries a `⑂ N` chip counting its delegates, with how many run, wait, are done, failed, stopped or idle in the tooltip and the waiting ones named in the attention colour; a click opens all sessions), the terminal's status row (a parent's `⑂ 2 running · 1 waiting`, see [Status Line](cli.md#status-line)) and the `list_sessions` tool (`child`; the parent shows as `parent` in the child's own list); the user can `chi --attach <child id>` and steer it mid-run, and `chi send` and `send_note` reach it like any session.
 
 - `delegate(task, model:, session:, cwd:, wait:, timeout:)`: starts a child and, by default, waits for its reply. `wait: false` is the usual way for work that takes a while, several children side by side, or to keep talking with the user: it returns at once, the parent ends its turn or works on, and the reply comes back by itself as a *delegate report* (below), in a turn of its own if the parent is idle. The tool descriptions tell the model so, and to wait (`wait: true`, `delegate_result`) only when its turn can't go on without the reply. `timeout`, default 600 s, leaves a slow child running; 0 checks once without waiting. With `session:` (a child's id or prefix) the task goes to that child as a follow-up instead, delivered like `chi send` (client id `delegate:<parent short id>`, shown as `delegate>` in the child's UIs); only this session's children take one.
 - `cwd:` starts the child in another folder of the parent's repository: a linked worktree (`git worktree add ../<repo>-<task> -b <branch>`, which the model runs with `execute` first, under guardrails; chi runs no git here) or a subfolder; a relative path is taken from the parent's folder. The folder must exist, have the parent's project root (the same common git dir, `MemoryPaths.project_root`) and be in a work tree: a git dir (`.git`, `.git/objects`, a bare layout's `.bare`) or a bare layout's container is refused (`git rev-parse --is-inside-work-tree`, read-only, decides). Outside git only a subfolder of the parent's folder is allowed. Otherwise the tool returns `Error: cwd must be a folder of this session's repository …` or `… is not in a work tree …`. A follow-up (`session:`) refuses `cwd:`: the child keeps its folder. The child's guardrails measure from its own worktree, and project memories, `list_sessions` and the web's project are the same as the parent's.
@@ -205,4 +205,4 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - Every child starts with the shipped `delegated` system memory preloaded (`preloaded_memory_names: ["system/delegated"]`; `--mute delegated` would hide it): put everything in the final reply, don't delegate further, don't write memories or change config, stay in the folder. Its system prompt also says `Delegated by session <parent id>`. The parent's own `--mute` list does not carry over.
 - **A child asks before it changes anything outside its folder** (the work tree top of the folder it started in): a write or edit there, mutating git in another checkout, a command that isn't read-only run from outside it or naming the main checkout or a sibling worktree. It's a core guardrail, on in every mode and without the guardrails bundle, and answered once or for the child's session ([Guardrails](guardrails.md#a-delegate-childs-boundary)); the approval relays to the parent's user as any other.
 - Limits: a child cannot `delegate` (depth 1; the tool refuses), and one session may have at most `session.max_children` (default `4`, env `SAMAGOTCHI_SESSION_MAX_CHILDREN`) children running at a time, counted from the session files (a finished or idle-exited child does not count; one whose worker is still starting does, for 15 s). A refused call creates no session. Nothing stops children with the parent: `chi sessions stop ID` does.
-- The link is the session's `parent_id`, written before the worker starts, so a respawn keeps it (and `delegate: true`, which a fork's `parent_id` doesn't come with; a child saved before that field is known by its `system/delegated` memory); `GET /api/sessions` and `/api/sessions/:id` carry it, and `SessionManager.children_of` lists a parent's children.
+- The link is the session's `parent_id`, written before the worker starts, so a respawn keeps it (and `delegate: true`, which a fork's `parent_id` doesn't come with; a child saved before that field is known by its `system/delegated` memory); `GET /api/sessions`, `/api/sessions/:id` and the web hub's `session` frames carry it and `delegate` (a fork is `false`; the web parent's children chip counts delegates only); `SessionManager.children_of` lists a parent's children.

data/lib/samagotchi/bridge/card_store.rb

@@ -201,7 +201,7 @@ module Samagotchi
       end
 
       def add_notice(event)
-        notice = event.slice(:type, :hook, :text, :level)
+        notice = event.slice(:type, :hook, :text, :level, :fallback_for)
         if event[:between_turns] || !@running
           push(notice.merge(in_turn: false, turns: @turns_done))
         else

data/lib/samagotchi/bridge/turn_notice.rb

@@ -10,7 +10,7 @@ module Samagotchi
     # here, and draw it with the handler that drew it live, where it was.
     module TurnNotice
       FIELDS = {
-        hook_notice: %i[hook text level],
+        hook_notice: %i[hook text level fallback_for],
         empty_answer_retry: %i[iteration attempt of stopped_by malformed],
         steer_cut: %i[iteration source],
         question_requested: %i[pending_question],

data/lib/samagotchi/broadcast/recipients.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../session"
+
+module Samagotchi
+  # Loaded on first use: session_manager requires terminal_ui, which
+  # requires KernelLoop and so the tools (a require cycle otherwise).
+  autoload :SessionManager, File.expand_path("../session_manager", __dir__)
+
+  module Broadcast
+    # A session a broadcast may concern.
+    # @!attribute project [String, nil] its git project's root
+    # @!attribute live [Boolean] a worker runs it now
+    # @!attribute owner [String, nil] "worker", "tui" (a chi REPL, which
+    #   takes no notes) or nil
+    Recipient = Data.define(:id, :short_id, :project, :cwd, :desc, :live, :owner) do
+      def repl? = owner == "tui"
+    end
+
+    # Who a broadcast goes to: the user's own sessions, not delegate
+    # children (their parent relays what concerns them) and not scratch
+    # ones, that a worker or a chi REPL runs now or that ended a turn in
+    # the last +active_hours+. Forks count: they are the user's sessions.
+    # Archived sessions don't; test runs only when chi runs as one.
+    module Recipients
+      module_function
+
+      # @return [Array<Recipient>] newest first
+      def list(state_dir:, active_hours:, include_tests: Session.test_session_env?, now: Time.now)
+        cutoff = now - (active_hours.to_f * 3600)
+        SessionManager.session_summaries(include_tests: include_tests, state_dir: state_dir).filter_map do |row|
+          next if row[:delegate] || row[:scratch]
+          next unless row[:live] || row[:owner] == "tui" || active_since?(row, cutoff, state_dir)
+
+          Recipient.new(id: row[:id], short_id: row[:short_id], project: row[:project], cwd: row[:cwd],
+                        desc: row[:desc], live: row[:live], owner: row[:owner])
+        end
+      end
+
+      # The user's last turn there ended after +cutoff+. updated_at moves on
+      # every save (a note absorbed, a resume), so it counts only for a
+      # session with no turn recorded; it is never older than the last
+      # turn's end, so an older one rules the session out unread.
+      def active_since?(row, cutoff, state_dir)
+        return false unless (time(row[:updated_at]) || Time.at(0)) >= cutoff
+
+        session = Session.summary_from_file(Session.session_file(row[:id], state_dir: state_dir))
+        last_turn = session&.last_turn
+        ended = last_turn.is_a?(Hash) ? time(last_turn["ended_at"] || last_turn[:ended_at]) : nil
+        (ended || time(row[:updated_at])) >= cutoff
+      end
+      private_class_method :active_since?
+
+      def time(value)
+        value && Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+      private_class_method :time
+    end
+  end
+end

data/lib/samagotchi/broadcast/scope_card.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../session"
+require_relative "../context_note"
+require_relative "../context_sources"
+require_relative "../git_head"
+require_relative "../recap_store"
+require_relative "tags"
+
+module Samagotchi
+  module Broadcast
+    # What a broadcast knows about one recipient, from local state only:
+    # where it works, what it was started for, its recap, its last prompt
+    # and its tags. Built fresh for each broadcast, never stored; P2's
+    # triage model reads #to_s.
+    # @!attribute folder [String, nil] the session's folder relative to its
+    #   project ("../app-fix" for a worktree), nil when it is the project
+    #   root; outside a project the whole path, ~ for home
+    # @!attribute tags [Array<Tag>]
+    ScopeCard = Data.define(:id, :project, :folder, :branch, :title, :tags, :started, :recap, :recent) do
+      def to_s
+        where = [("folder #{folder}" if folder), ("branch #{branch}" if branch)].compact.join(", ")
+        lines = ["project: #{project || "none"}#{" (#{where})" unless where.empty?}"]
+        lines << "title:   #{title}" unless title.to_s.empty?
+        lines << "tags:    #{tags.map(&:label).join(" · ")}" unless tags.empty?
+        lines << "started: #{started}" unless started.to_s.empty?
+        lines << "recap:   #{recap}" unless recap.to_s.empty?
+        lines << "recent:  #{recent}" unless recent.to_s.empty?
+        lines.join("\n")
+      end
+    end
+
+    # Builds a ScopeCard for a Recipient.
+    module ScopeCards
+      STARTED_CHARS = 300
+      RECAP_CHARS = 400
+      RECENT_CHARS = 200
+
+      module_function
+
+      # @param recipient [Recipient]
+      # @param ticket [Regexp] the ticket pattern (Tags.ticket_regexp)
+      # @return [ScopeCard]
+      def build(recipient, state_dir:, ticket:)
+        session = Session.load(recipient.id, state_dir: state_dir)
+        prompts = user_texts(session.messages)
+        branch = GitHead.branch(session.working_directory)
+        sources = ContextSources.attached(session.id, project_root: session.project_root, state_dir: state_dir)
+                                .map { |attached| [attached.name, attached.source.hint] }
+        ScopeCard.new(id: session.id, project: recipient.project && File.basename(recipient.project),
+                      folder: folder(session.working_directory, recipient.project), branch: branch,
+                      title: recipient.desc, tags: Tags.of_session(branch: branch, messages: prompts, sources: sources,
+                                                                   ticket: ticket),
+                      started: cut(prompts.first, STARTED_CHARS),
+                      recap: cut(RecapStore.read(Session.session_dir(session.id, state_dir: state_dir))&.dig(:text),
+                                 RECAP_CHARS),
+                      recent: cut(session.last_prompt, RECENT_CHARS))
+      end
+
+      # The user's own messages, as text (an image part leaves its text).
+      def user_texts(messages)
+        messages.filter_map do |message|
+          next unless message[:role].to_s == "user"
+
+          content = message[:content]
+          text = if content.is_a?(Array)
+                   content.filter_map { |part| part.is_a?(Hash) ? part[:text] || part["text"] : nil }.join("\n")
+                 else
+                   content.to_s
+                 end
+          text unless text.strip.empty?
+        end
+      end
+      private_class_method :user_texts
+
+      def folder(cwd, project)
+        return ContextNote.home_relative(cwd) if project.nil?
+        return nil if cwd.to_s == project.to_s
+
+        Pathname.new(cwd.to_s).relative_path_from(Pathname.new(project.to_s)).to_s
+      rescue ArgumentError
+        cwd
+      end
+      private_class_method :folder
+
+      def cut(text, limit)
+        line = text.to_s.gsub(/\s+/, " ").strip
+        line.length > limit ? "#{line[0, limit - 1]}…" : line
+      end
+      private_class_method :cut
+    end
+  end
+end