samagotchi 0.33.0 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca8acdcb161f8d093ab1c860913dd3a1e826083bcfff0165039847e38a26c5ad
-  data.tar.gz: 5c286ada590d84b793e95d9f2dec051132462469aace12c0faf1da0f1c4e3fdf
+  metadata.gz: b598dac8dadadd4dd37861ed690d09d09926520c2295bc998def4d75c3716ea7
+  data.tar.gz: 9d30ebb820024929bbb2dc1267011af7eb5710b33a4ba9625489a74d111edfbd
 SHA512:
-  metadata.gz: 394a942740165c9ea457b3a3043a070ef9338a897c6eb41c387b1101e8426c8e21c938757868d87493216324d84441165a82601b796801be90feef5c8e6c7091
-  data.tar.gz: 29d24ccdb0bd41d027ccdaf4b8c6e0a191d292b636fc3af1e27e994f30b1331192f59d3bf6aa5d858e78ec5d84d32d8760f2df03c8dace2feaad1ac87783c1c6
+  metadata.gz: 2f40ed32d227d1017bc7abcba8ef40f5e38f2f7dd7876aa5f78a9290e5443489b8109183655a151a1345fef1fa3f3f49e5deafbac38059cdba3bec70b0585d71
+  data.tar.gz: 55aca343a9dc45e78791863286768c356e815dc1b9783993f2c4477edb991883a3c88ae208dd642137cab4c6ead58fc1d49228f201fefcd6878dd421c719af70

data/CHANGELOG.md

@@ -8,6 +8,94 @@ 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
+
+- `delegate cwd:` starts a child in another folder of the session's repository: a worktree the model made with
+  `git worktree add`, or a subfolder. Another repository is refused.
+- Plugins: `ctx.sessions.children` lists the session's children (state, branch, last reply and whether the parent
+  was given it), and `ctx.sessions.stop(id)` stops one of its own children.
+- Bundles: a `files:` entry in `manifest.yml` may carry a `description:`, which the install writes into the
+  memory's `index.md` line.
+- The `coordinator` bundle: chi coordinates parallel work. `/coordinate <goal>` (or asking for it) has chi split
+  the work into tasks, each in a child session in its own git worktree, check each report and ask you before each
+  merge. `/children` shows the session's children: state, branch, last reply and whether it was reported, with a
+  Stop button each.
+- Guardrails: a delegate child asks before it changes anything outside its folder (its worktree): a write there,
+  git that changes the main checkout or a sibling worktree, a command run from or naming one of them. It's built in,
+  in every mode and without the guardrails bundle, and answered once or for the child's session.
+
+### Changed
+
+- The `delegate` and `delegate_result` tools tell the model to start a child with `wait: false` unless its turn
+  can't go on without the reply, then end its turn or keep talking with you: the reply comes back by itself as a
+  delegate report. `delegate_result` is only for a reply the turn needs now.
+
+### Fixed
+
+- A wake turn (a context source's change, a delegate's report) that fails no longer tells the model the user's
+  message went unanswered: it says the wake wasn't answered, and that no other wake turn starts until you write.
+  For a delegate's report it adds that the report comes again with your next message.
+- A delegate wait that timed out or was canceled says the child's reply still comes as a delegate report, instead
+  of steering the model into waiting again with `delegate_result`; so does a question's result.
+- `delegate` with `wait: false` in a session that gets no delegate reports (a `--no-shared` REPL, `-p`) says
+  `delegate_result` waits for the reply, instead of promising a report that never comes.
+- In a linked git worktree the system prompt no longer names the repository's main checkout ("Project root"), which
+  led a model to work and commit there: it names this checkout's top and says to work only in it. Project memories
+  and session lists still follow the repository.
+- `delegate` refused for too many running children tells a session that gets delegate reports to end its turn (a
+  report frees a slot), instead of to wait with `delegate_result`.
+- At a repository's root the system prompt names the checkout the project's commands run in, and calls the project
+  memories folder your notes about the project, not its files: a model no longer goes looking for the repository
+  in the memories folder.
+
+Update with `chi update`: it installs the new `coordinator` bundle for the `dev` profile (dev 0.3.0) and updates mcp
+(0.4.5: stops an MCP server through chi's own process-group handling).
+
 ## [0.33.0] - 2026-10-06
 
 ### Changed
@@ -1663,7 +1751,9 @@ 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.33.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
 [0.31.0]: https://github.com/dm1try/samagotchi/compare/v0.30.0...v0.31.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
@@ -145,7 +146,10 @@ never takes orders from. The web and the attached terminal show it as a dim
 a note reaches (`id<TAB>description`). Agents can do the same: `list_sessions`
 finds another session, `send_note` tells it something, and `delegate` hands a
 task to a child session that runs in parallel and reports back only its final
-reply (a normal session: `chi --attach <id>` steers it).
+reply (a normal session: `chi --attach <id>` steers it). With the `coordinator`
+bundle (in `dev`), `/coordinate <goal>` has chi split the work into tasks, each
+in a child session in its own git worktree, check each report and ask you
+before each merge; `/children` shows the children and their state.
 
 `chi send` is the other half: the text goes in as your message, the same as
 typing it in the attached terminal or the web composer, and a turn runs. Piped
@@ -199,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/context.md

@@ -154,6 +154,11 @@ update note, whose last line becomes:
 Every UI labels the turn `context <name> changed`, and the web's
 notifications count it as a finished turn however short.
 
+A wake turn that fails goes back to before it and keeps the update as a
+plain note; the model reads `[SYSTEM: the previous turn failed before any
+answer: … The wake turn for the change in attached context <name> was not
+answered; chi starts no other wake turn until the user writes.]`.
+
 ## GitHub PRs: the github-pr bundle
 
 ```sh

data/docs/guardrails.md

@@ -5,13 +5,14 @@ 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:
 
 1. `before_tool_call` hooks (Ruby; see [Hooks](hooks.md#guardrails-from-a-hook)).
-2. Core checks: a required guardrail that failed to load, then protected paths.
+2. Core checks: a required guardrail that failed to load, then protected paths, then (a delegate child only)
+   [the child boundary](#a-delegate-childs-boundary).
 3. YAML rules: `config.yml`'s `guardrails:` section, then installed bundles' rule files (by bundle name).
 
 The UI shows the tool line first, then the approval under it.
@@ -189,6 +190,35 @@ Built in, for `write`, `edit` and `memory_write` (symlinks resolved):
 `execute` can still reach them; the guardrails bundle asks about shell
 commands that name them.
 
+## A delegate child's boundary
+
+Built in, for [delegate](sessions.md#delegating) children only, in every
+mode (also with `guardrails.enabled: false`) and without the guardrails
+bundle: a child asks before it changes anything outside its folder, the work
+tree top of the folder it was started in (a worktree from `delegate cwd:`,
+else the parent's checkout). Rule `child-boundary`, source `core`; it asks when
+
+- `write` or `edit` names a path outside it (tmp dirs and memory files don't count);
+- `execute` or `task_create` runs mutating git in another dir (`git -C`, `cd`,
+  `GIT_DIR`: what `git: outside_repo` matches), or a command that isn't
+  read-only starts outside it (its `cwd:`) or names a path in the repository's
+  other checkouts (the main one and sibling worktrees, read from
+  `<common git dir>/worktrees/*/gitdir`) or in its common git dir;
+- `execute` or `task_create` runs git that changes what every checkout shares,
+  even from its own worktree: a `git config` write (not `--get`, `--list`,
+  `--worktree`), `update-ref`, `worktree add|remove|move|prune`, `stash
+  drop|clear|pop`, creating or deleting a tag, and deleting, forcing or
+  overwriting a branch other than its own.
+
+Read-only commands (`git -C ../app log`, `cat ../app/x`) and paths elsewhere
+(`/usr/bin`, `~/.gem`) never ask. The answer is once or for the child's
+session only: a repo or rule answer would hold in every worktree, for every
+child, so a stored repo or rule approval doesn't let it through either. Its
+ask goes before the rules, so with the guardrails bundle in strict mode the
+card still names `child-boundary`. The parent (never a delegate), forks and
+ordinary sessions don't get it. Like the rules it reads command text: a
+`sh -c` body, a script or `$(…)` isn't looked into.
+
 ## Rules in config.yml
 
 ```yaml
@@ -397,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,
@@ -420,7 +437,7 @@ stripped of surrounding whitespace, except file text, an edit's
 | `list_sessions` | — | — | `cwd` |
 | `send_note` | `text` | — | `session` |
 | `context_read` | `name` | — | `offset`, `limit` |
-| `delegate` | `task` | — | `model`, `session`, `wait`, `timeout` |
+| `delegate` | `task` | — | `model`, `session`, `cwd`, `wait`, `timeout` |
 | `delegate_result` | — | — | `session`, `timeout` |
 | `ask_user_question` | `question` | — | `question`, `options`, `header`, `multi_select`, `allow_freeform` |
 
@@ -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/memory.md

@@ -102,6 +102,22 @@ for a file another bundle installed.
   `- **memory_guide** · system · 2026-10-03 · 5120 · from samagotchi-system —
   …`. `memory_write`, `write` and `edit` keep it. A bundle installed by chi
   0.16 or earlier gets it on its next install or upgrade.
+- **A bundle can give a memory its index description.** A `files:` entry
+  may be a mapping instead of a sha line:
+
+  ```yaml
+  files:
+    identity.md: sha256:…
+    skill_coordinator.md:
+      sha256: sha256:…
+      description: "Coordinate parallel work: …"
+  ```
+
+  The install writes that description into the memory's `index.md` line
+  (after `— `), so the model can tell what a shipped skill is for from the
+  index alone. The bundle's record keeps it, `chi bundle build` writes the
+  mapping back, and `rake bundles:sha` refreshes the nested sha. A file
+  with a plain sha line keeps the description its line already has.
 - **Uninstall moves, it doesn't delete.** The bundle's memory files go to
   `$XDG_CONFIG_HOME/samagotchi/memories/.bundles/.trash/<bundle>-<YYYYmmdd-HHMMSS>/`,
   and the output names them and the dir:
@@ -133,7 +149,7 @@ profiles, meta bundles that install a set of them:
 | profile | bundles |
 |---|---|
 | `core` | loop-guard, check-in, guardrails: the recommended safety set |
-| `dev` | known-names, mcp, btw, skills, source-links |
+| `dev` | known-names, mcp, btw, skills, source-links, github-pr, coordinator |
 
 `chi bootstrap` installs `core` and, on a terminal, offers `dev`. An existing
 install gets neither by itself: `chi bundle install core` (or `dev`).

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) |
@@ -496,7 +496,7 @@ full label, `plugin.rb (bundle my-bundle)`.
 | `ctx.stop_turn(reason)` | stop the running turn after a warn notice with the reason; true when it stopped one now. In a `:before_tool_call` block it also denies that call |
 | `ctx.stop_generation(reason)` | cut the generation that is streaming: the turn goes on and the model is asked again ([hooks.md](hooks.md#watching-the-stream)). Shows nothing: post your own notice. True when it cut one now |
 | `ctx.ask_model(messages:, prompt:, …)` | a side answer from the session's model: see [Side answers](#side-answers-ctxask_model) |
-| `ctx.sessions` | fork, send to and read other sessions: see [Other sessions](#other-sessions-ctxsessions) |
+| `ctx.sessions` | fork, send to, read, list and stop other sessions: see [Other sessions](#other-sessions-ctxsessions) |
 | `ctx.context` | attach outside text to this session and list it: see [Attached context](#attached-context-ctxcontext) |
 
 The Engine itself is never handed to a plugin.
@@ -608,7 +608,9 @@ llama.cpp serves on a native host too.
 id = ctx.sessions.fork(messages: ctx.messages + [{ role: "user", content: q }, { role: "model", content: a }],
                        title: "btw: #{q}")
 ctx.sessions.send(id, "go on from here")
-ctx.sessions.read(id)  # => {id:, title:, status:, parent_id:, running:, messages:}
+ctx.sessions.read(id)      # => {id:, title:, status:, parent_id:, running:, messages:}
+ctx.sessions.children      # => [{id:, short_id:, state:, branch:, last_reply:, reported:, ...}]
+ctx.sessions.stop(id)      # one of this session's own children
 ```
 
 - `fork(messages:, title: nil, prompt: nil)` starts a child session in its
@@ -629,6 +631,23 @@ ctx.sessions.read(id)  # => {id:, title:, status:, parent_id:, running:, message
 - `read(id)` gives a session now: from its worker when one runs (with a
   running turn so far, `running: true`), else as saved. `messages` has no
   system prompt.
+- `children(all: false)` lists this session's children, newest first, as
+  frozen Hashes: `{id:, short_id:, title:, state:, waiting:, live:,
+  delegate:, cwd:, branch:, last_reply:, last_reply_at:, reported:,
+  updated_at:, archived:}`.
+  - `state` is `waiting` (a question or approval is open; `waiting` says
+    which), `running`, `failed` (the last turn failed or the worker
+    crashed), `stopped`, `done` (the last turn ended with a reply) or `idle`.
+  - `delegate` is true for a `delegate` child, false for a fork. Archived
+    children are listed only with `all: true`.
+  - `branch` is the branch checked out in the child's folder (read from its
+    `HEAD`, a short sha when detached; nil outside git). `last_reply` is the
+    first line of its newest reply, and `reported` says whether this session
+    was already given that reply (a delegate report or a wait).
+  - It reads every session's file: call it on demand, not in a loop.
+- `stop(id)` stops one of this session's own children, as
+  `chi sessions stop` does, and waits up to 2 s for its worker to let go. It
+  returns the child's id. Any other session raises.
 - Each raises `Samagotchi::Plugin::Sessions::Error` with the reason.
 
 ## Attached context: `ctx.context`
@@ -1120,6 +1139,62 @@ and a summary of what changed in counts, authors and states only; it wakes
 the session for a review requesting changes, checks turning red, or the PR
 merged or closed. See [Attached context](context.md#github-prs-the-github-pr-bundle).
 
+## The coordinator bundle
+
+```sh
+chi bundle install coordinator    # in the dev profile
+```
+
+chi as a coordinator of parallel work, the way you would run several agents
+yourself: split the work, one git worktree and child session per task, keep
+talking while they run, check each report, and merge only with your OK. It
+works in a session with a worker (plain `chi`, the web). A `--no-shared` REPL
+or `-p` gets no delegate reports, so the children's replies wouldn't come back
+by themselves there.
+
+- **The skill.** `skill_coordinator` (system scope; its index line says what
+  it is for, from the manifest's `description:`) holds the steps. The model
+  creates each worktree with `execute` (`git worktree add ../<repo>-<task> -b
+  <branch>`), starts a child there with `delegate wait: false, cwd:`, tells
+  you what started and ends its turn. When a child's report comes, it checks
+  the branch (`git log`, `git diff --stat`, the tests the child names) before
+  telling you. It asks before each merge (`ask_user_question`), checks that its
+  own folder is on the default branch and that branch's log first (another
+  agent may have merged the branch already), merges `--ff-only` and never
+  pushes unless you ask. After a merge it stops the
+  child and removes only the worktrees and branches it made.
+- **`/coordinate <goal>`** sends this session a turn asking the model to
+  follow the skill for the goal (in a `--no-shared` REPL it shows the text to
+  send yourself). Asking "do this in parallel" works too: the index line leads
+  the model to the skill.
+- **`/children [all]`** shows the session's children as a card, newest first,
+  one line each: `` `ab12cd34` · running · fix/flaky · "fix the flaky spec" ``,
+  `` `9a8b7c6d` · done · feat/x · reported · "All 12 specs pass" `` (`not
+  reported yet` when the parent wasn't given that reply), `` `77aa66bb` ·
+  waiting (approval) · open it: chi --attach 77aa66bb ``. A fork is marked
+  `fork`; `all` adds archived children. It runs during a turn too. The card
+  has Refresh and a `Stop <id>` per running or waiting child (up to 5);
+  `/children stop <id>` stops one of this session's own children (by session
+  id, as `chi sessions stop` does) and shows the card again.
+- **Children stay in their worktree.** A child asks before it changes
+  anything outside its worktree (your checkout, a sibling's), in every
+  guardrails mode and without the guardrails bundle ([a delegate child's
+  boundary](guardrails.md#a-delegate-childs-boundary)); you answer on its
+  card, or on the parent's while it waits.
+- **Merges.** The parent's merge in its own checkout is a plain `git
+  merge`; to be asked before every merge, add a rule ([Rules in
+  config.yml](guardrails.md#rules-in-configyml)):
+
+  ```yaml
+  guardrails:
+    rules:
+      - id: git-merge
+        tool: shell
+        command: '\bgit\s+merge\b'
+        verdict: ask
+        reason: merging a child's branch
+  ```
+
 ## Shutdown
 
 When the REPL exits, or a session's worker exits (an idle exit, `/exit`, a

data/docs/releasing.md

@@ -13,7 +13,7 @@ can run the whole release; the user approves the notes before the tag and the
   and `rake release:check` enforce it). The system bundle upgrades itself when
   chi starts.
 - **Every other shipped bundle** (btw, check-in, guardrails, known-names,
-  loop-guard, mcp, skills, source-links, github-pr, and the profiles core and dev) has its own semver in its
+  loop-guard, mcp, skills, source-links, github-pr, coordinator, and the profiles core and dev) has its own semver in its
   `manifest.yml` and, when it needs a newer chi, a `requires_chi:` line. They never upgrade by themselves: users run
   `chi update` (all of them, with the gem) or `chi bundle upgrade NAME`. So:
   - a change to a bundle's files bumps that bundle's `version:`