samagotchi 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca8acdcb161f8d093ab1c860913dd3a1e826083bcfff0165039847e38a26c5ad
-  data.tar.gz: 5c286ada590d84b793e95d9f2dec051132462469aace12c0faf1da0f1c4e3fdf
+  metadata.gz: c6f812c6128ae3ffaf91d9cc04716a77d351fb57793a7d9a4863e675f1f2337f
+  data.tar.gz: 25e7600fe6dc335b7d28320795a03ea9e8527185f6a0dd918787777458402f39
 SHA512:
-  metadata.gz: 394a942740165c9ea457b3a3043a070ef9338a897c6eb41c387b1101e8426c8e21c938757868d87493216324d84441165a82601b796801be90feef5c8e6c7091
-  data.tar.gz: 29d24ccdb0bd41d027ccdaf4b8c6e0a191d292b636fc3af1e27e994f30b1331192f59d3bf6aa5d858e78ec5d84d32d8760f2df03c8dace2feaad1ac87783c1c6
+  metadata.gz: 322e9f5a5b553f7ed1f2955307b8d5bd8c901a355ac3ffcdff6b3fcb5013b28011c7c330d9496486338c77d2c0f58e2854393d4cb40ec33d00ed2516a38bd066
+  data.tar.gz: f6048763f53d9b865858842acaf60587d5e57a365aaba759c3c85fcf69532227c4b201fe0f878da3e48191dd43856637dad29537203a3dfd7159756caac6f778

data/CHANGELOG.md

@@ -8,6 +8,51 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [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 +1708,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.33.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.34.0...HEAD
+[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

@@ -145,7 +145,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

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

@@ -11,7 +11,8 @@ 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

data/docs/hooks.md

@@ -420,7 +420,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` |
 

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

@@ -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:`

data/docs/sessions.md

@@ -120,6 +120,9 @@ system message marked `kind: turn_note` (the UIs don't show it; they showed the
   before any answer: network error after 2 attempts (host main: Errno::ECONNREFUSED). The message went back to
   the user, who may send it again.]` in the REPL and attached mode, where the prompt is given back;
   `… The user's last message was not answered.]` after `-p`, where the prompt stays in the session;
+  `… The wake turn for the change in attached context pr-7 was not answered; chi starts no other wake turn until
+  the user writes.]` after a wake turn chi started (a context source's change, a delegate's report), not the user
+  (for a delegate's report it adds `chi keeps the report and brings it again with the user's next message.`);
 - cancelled (Ctrl-C, the web's stop): `[SYSTEM: the previous turn was cancelled (ctrl-c) after 12s; the reply
   above ends where it was cut off.]` (an answer or only narration had streamed), or `…; no answer had been shown.]` when only thinking had streamed;
 - ended with nothing visible: `[SYSTEM: the previous turn ended with no visible answer (thinking only, or
@@ -181,8 +184,10 @@ chi send --wait 3fa2                                   # sends nothing: waits fo
 
 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.
 
-- `delegate(task, model:, session:, wait:, timeout:)`: starts a child and, by default, waits for its reply (`wait: false` returns at once, so several children can run side by side, and the reply comes back by itself as a *delegate report*, below; `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.
-- `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one.
+- `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.
+- `delegate_result(session:, timeout:)`: waits for a child's next reply: the one named, or the newest running child (`timeout` as for `delegate`: 0 checks once and returns at once). The reply comes back once; a later call waits for the next one. After `wait: false` it isn't needed: the report brings the reply.
+- A wait that timed out or was canceled still gets its delegate report: neither moves the parent's cursor, so the child's reply comes as a report when its turn ends. The result says so (`chi brings its reply here by itself as a delegate report …`; with `queue`, that it joins the next step or turn) and that `delegate_result` waits again only if the turn needs the reply now. A parent that gets no reports (`session.delegate_reports: off`, a `--no-shared` REPL, `--non-interactive`) is told `delegate_result <id> waits again` instead, and `wait: false`'s result says `delegate_result waits for its reply`.
 - What a wait returns, `session: <id>` then `status:` and the text, with the status words `chi send --wait --format json` uses: `answered` with the reply after a `---` line; `question` as soon as the child opens a question (the model's own, or a hook's), with the question's text, options and the `chi answer` command for it (nothing is answered for it: `chi answer`, attach or use the web, then wait again); `failed`, `canceled` or `no_answer` when the child's turn ended with nothing to say (its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `worker_gone` when the child has had no worker for 15 seconds (it crashed without saying so, or idle-exited): `delegate` with `session:` starts it again; `running` on timeout, or when the parent's own turn is canceled (the child keeps running; the next turn can wait again). A reply saved before the child's worker idle-exited is returned at once.
 - **A child's step-limit question goes back to the parent model**, not to its user: `delegate_result` returns `status: question` with the `chi answer` commands for Continue and Stop, and says the model may instead send a narrower follow-up (`delegate session:`, which drops the question) or report back. A parent's `chi answer` follows `turn.parent_continue` (see [chi as a sub-agent](sub-agent.md#the-step-limit)).
 - **A child's approvals go to the parent's user** (the approval relay). While the parent waits (`delegate`, `delegate_result`), a guardrail approval the child opens reopens as the parent session's own approval: the same card in the parent's web page and attached terminal, with the same facts and diff, a line naming the delegate and its task (`delegate ab12 · fix the flaky spec…`, linked to its session) and the header `Approve delegate ab12's tool call?`. The options are the child's, by index; "for the session" says it is the delegate's session (the session scope keys on the child; repo and rule approvals are one shared store). The user answers once there; the parent's model never sees the approval, only one line per relayed approval in the tool's result, before the reply: `approval relayed to your user: execute: git push origin main → allowed once` (or `denied ("why")`, `dismissed (denied)`, `answered on the child`, `not delivered (the child's worker is gone)`, `refused by the child …`, `still open (your turn was stopped)`). The time the card is open doesn't count against `timeout`. While the parent waits on one child, its other running children's approvals are relayed too, oldest first, one card at a time (`+1 more delegate waiting`); each outcome comes in that child's next result.
@@ -194,9 +199,10 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
   - Parent mid-turn: the report joins the turn at its next iteration boundary (a "delegate report" bubble in the web, `delegate report> ab12cd34 answered: …` in the attached terminal).
   - Parent idle: it runs a turn for the report (a *wake turn*, `last_turn.origin: "delegate_report"`) within the worker's 5 s tick, or wakes a worker for it when the parent's has idle-exited. Several reports that wait together are one turn and one message. A stopped, archived or scratch parent, or one open in a `--no-shared` REPL, is not woken: the rings wait on disk and join the next turn it runs (the user's message first). A worker just started (`chi send` to a stopped parent) runs no wake turn in its first 2 s, so the message it was started for goes first.
   - The parent's cursor per child (the newest reply it was given and the child as it was then) is in its `delegates.json`, shared with `delegate_result` and `wait: true`: a reply the model already had is never reported again, also after the parent's worker restarts. A ring is deleted only when the turn that took its report is kept; a turn that fails leaves it for the next one (and the report isn't handed back to the composer).
-  - Limits: `session.max_wakes` (default `10`) wake turns in a row with no human input; past it the reports wait for the next message and the UIs show `N delegate reports waiting; they join your next message`. A wake turn that fails pauses wakes until the next human input. A continue offer waiting in the parent takes the reports into its continue turn instead.
+  - Limits: `session.max_wakes` (default `10`) wake turns in a row with no human input; past it the reports wait for the next message and the UIs show `N delegate reports waiting; they join your next message`. A wake turn that fails pauses wakes until the next human input; its reports' rings stay, so they join that input's turn, and the failure note tells the model so. A continue offer waiting in the parent takes the reports into its continue turn instead.
   - `session.delegate_reports`: `wake` (default), `queue` (no wake turns: reports join the parent's next turn) or `off` (no rings; only `delegate_result` asks, as before). Env `SAMAGOTCHI_SESSION_DELEGATE_REPORTS`, `SAMAGOTCHI_SESSION_MAX_WAKES`.
   - The web's bell rings at a wake turn's end however short (nobody started it, so nobody watched it). The text a model writes about a report mid-turn, before its next tool call, stays visible after the report's bubble once the turn ends.
 - 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.

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

@@ -0,0 +1,14 @@
+---
+name: coordinator
+version: 0.1.2
+scope: system
+description: "Coordinate parallel work: the coordinator skill (split the work, one worktree and child session per task, check each report, ask before each merge), /coordinate <goal> and /children"
+trust_level: reviewed
+files:
+  skill_coordinator.md:
+    sha256: sha256:b21067c3f152c8dfd1b1f70001c6654ad1911616543a36b625727fb13d4ce3f6
+    description: "Coordinate parallel work: split it, delegate each task wait:false in its own worktree (cwd:), check each report, ask the user before each merge"
+plugin:
+  file: plugin.rb
+  sha256: sha256:5173faeb6311984ad4f2a40b9052dcc577a90790fc5c5a8409b95d4f114e66a7
+requires_chi: ">= 0.34.0"

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+# The coordinator bundle (docs/plugins.md, The coordinator bundle): chi as a
+# coordinator of parallel work. Its skill_coordinator memory holds the steps
+# (split the work, one worktree and a wait: false delegate per task, check
+# each report, ask before each merge); this plugin adds two commands.
+#
+# /children [all] shows this session's children as a card, newest first:
+# state, branch, the last reply and whether it was reported (ChildrenStatus
+# through ctx.sessions.children), with a Stop button per running or waiting
+# child and Refresh. `all` adds archived children. The card has one id, so
+# Refresh and Stop replace it. It is read on demand: no thread, no polling.
+#
+# /children stop <id> stops one of this session's own children
+# (ctx.sessions.stop, by session id) and shows the card again.
+#
+# /coordinate <goal> asks the model, in this session, to follow the skill
+# for the goal. A REPL session (--no-shared) takes no messages: the request
+# is shown for the user to send.
+#
+# A child is asked before it changes anything outside its worktree by chi
+# itself (the core child-boundary guardrail), in every mode: nothing to set up.
+class Plugin
+  CARD_ID = "children"
+  # A card takes 6 actions: Refresh and up to 5 Stops.
+  MAX_STOPS = 5
+  STOPPABLE = %w[running waiting].freeze
+  TEXT_CHARS = 80
+  USAGE = "usage: /children [all] | /children stop <id>"
+  COORDINATE_USAGE = "usage: /coordinate <goal> — chi splits it into tasks, one child session and worktree each"
+
+  def initialize(_settings = {}); end
+
+  def register(chi)
+    chi.command "/children", "this session's child sessions: state, branch, last reply; all, stop <id>",
+                anytime: true do |args, ctx|
+      children_command(args.to_s.strip, ctx)
+    end
+    chi.command "/coordinate", "run work in parallel: chi splits <goal> into tasks, each in a child session and worktree",
+                anytime: true do |args, ctx|
+      coordinate(args.to_s.strip, ctx)
+    end
+  end
+
+  private
+
+  def children_command(args, ctx)
+    verb, rest = args.split(/\s+/, 2)
+    case verb
+    when nil then show(ctx, all: false)
+    when "all" then rest.to_s.empty? ? show(ctx, all: true) : USAGE
+    when "stop" then rest.to_s.strip.empty? ? USAGE : stop(rest.strip, ctx)
+    else USAGE
+    end
+  end
+
+  # The card, made or replaced; nil, so the command adds no text of its own.
+  def show(ctx, all:, note: nil)
+    children = ctx.sessions.children(all: all)
+    title = "children of #{ctx.session_id.to_s[0, 8]}"
+    title += " (#{children.size})" unless children.empty?
+    body = children.empty? ? "no children" : children.map { |child| line(child) }.join("\n")
+    body = "#{note}\n\n#{body}" if note
+    refresh = all ? "/children all" : "/children"
+    stops = children.select { |child| STOPPABLE.include?(child[:state]) }.first(MAX_STOPS)
+                    .map { |child| { label: "Stop #{child[:short_id]}", command: "/children stop #{child[:short_id]}" } }
+    ctx.card(id: CARD_ID, title: title, body: body, actions: [{ label: "Refresh", command: refresh }, *stops])
+    nil
+  end
+
+  # - `ab12cd34` · running · fix/flaky · "fix the flaky spec…"
+  # - `9a8b7c6d` · done · feat/x · reported · "All 12 specs pass…"
+  # - `77aa66bb` · waiting (approval) · open it: chi --attach 77aa66bb
+  def line(child)
+    parts = ["`#{child[:short_id]}`", child[:waiting] ? "waiting (#{child[:waiting]})" : child[:state]]
+    parts << child[:branch] if child[:branch]
+    parts << "fork" unless child[:delegate]
+    parts << "archived" if child[:archived]
+    if child[:waiting]
+      parts << "open it: chi --attach #{child[:short_id]}"
+    elsif child[:last_reply]
+      parts << (child[:reported] ? "reported" : "not reported yet")
+      parts << quote(child[:last_reply])
+    elsif !child[:title].to_s.strip.empty?
+      parts << quote(child[:title])
+    end
+    "- #{parts.join(" · ")}"
+  end
+
+  def stop(id, ctx)
+    stopped = ctx.sessions.stop(id)
+    show(ctx, all: false, note: "stopped #{stopped[0, 8]}")
+  rescue Samagotchi::Plugin::Sessions::Error => e
+    "/children stop: #{e.message}"
+  end
+
+  def coordinate(goal, ctx)
+    return COORDINATE_USAGE if goal.empty?
+
+    request = "Read the skill_coordinator memory and follow it for this goal:\n\n#{goal}"
+    begin
+      ctx.sessions.send(ctx.session_id, request)
+    rescue Samagotchi::Plugin::Sessions::Error => e
+      return "/coordinate: #{e.message}. Send this yourself:\n\n#{request}"
+    end
+    "asked chi to coordinate it; a running turn gets it at its next step"
+  end
+
+  def quote(text)
+    line = text.to_s.gsub(/\s+/, " ").strip
+    line = "#{line[0, TEXT_CHARS - 1]}…" if line.length > TEXT_CHARS
+    "\"#{line}\""
+  end
+end

data/lib/samagotchi/bundles/coordinator/skill_coordinator.md

@@ -0,0 +1,60 @@
+# Skill: coordinator
+
+Use when the user hands over work with several independent parts, or asks to "run it in parallel",
+"delegate", "coordinate". The user decides; you do the legwork and keep them in the loop briefly.
+
+## Steps
+1. Find the repository's default branch, <default> below: `git symbolic-ref --short
+   refs/remotes/origin/HEAD` (drop the `origin/`), else `main` or `master`, whichever exists; ask the
+   user if unsure. Split the work into independent tasks (at most session.max_children at once,
+   default 4). Tell the user the split in a few lines and go on unless they object.
+2. For each task: from your own folder, `git worktree add ../<repo>-<task> -b <type>/<task>` with
+   execute; then `delegate` with `wait: false`, `cwd:` that worktree's absolute path, and a
+   self-contained task. The task starts with "Work only in <absolute worktree path>: every cd, read,
+   write, test and commit goes there, never the project root" and says what to report (the result,
+   evidence: commands and what they printed, what isn't done) and "commit on the branch, don't merge,
+   don't push".
+3. Tell the user what started (one line per child: its id, branch and task) and end your turn or keep
+   talking. Don't call delegate_result: chi brings each child's reply as a delegate report, also when
+   you are idle.
+4. On each report, check it before telling the user: `git -C <worktree> log --oneline <default>..` and
+   `git diff --stat <default>...<branch>`; run the tests the child names (execute with cwd: the worktree).
+   Say the result in one or two lines: done and verified / done with doubts / failed.
+5. Then one of: a follow-up (`delegate session: <id>`, narrower, `wait: false`; then end your turn:
+   its report comes by itself, so don't wait for it with delegate_result or task_wait), stop it
+   (`chi sessions stop <session id>` with execute; task_stop is for task ids, not children; the user
+   can use /children), or tell the user it is ready to merge.
+6. Merging is the user's call: ask (ask_user_question) per branch, "Merge <branch> into <default>?".
+   Before merging, in your own folder: `git branch --show-current` must print <default> (if it
+   doesn't, stop and ask the user; don't switch branches yourself); then check <default>:
+   `git log --oneline -3 <default>` and `git merge-base --is-ancestor <branch> <default>`; if the branch is already in, say so and don't merge
+   again. Merge with `git merge --ff-only <branch>` yourself, in your own folder. If that fails, ask the
+   child to rebase its branch on <default> (a follow-up that says "rebase only, don't merge") or ask the
+   user; don't rebase it from here (the branch is checked out in the child's worktree). Children
+   never merge. Never push unless asked.
+7. Clean up only a branch that was merged or that the user said to drop: stop its child
+   (`chi sessions stop <session id>`), then `git worktree remove ../<repo>-<task>`, then
+   `git branch -d <branch>` (in that order: a branch checked out in a worktree can't be deleted). If
+   `-d` refuses, say why to the user; never `-D` unless they say so. Remove only worktrees and
+   branches you created in this session. Every other branch stays as it is, its child, worktree and
+   branch too (the user said "keep it", or didn't say): leave them and tell the user they remain.
+8. When all are done, report: what merged, what didn't and why, what you cleaned up and what remains,
+   follow-ups found but not fixed. Report only what the commands' output showed: a step you planned
+   but didn't run, or whose output you didn't see, is not done; say so.
+
+## Gotchas
+- Children are asked before changing anything outside their worktree (your checkout, a sibling's):
+  the user approves it on the child's card. Still check where commits landed (step 4).
+- Never kill processes by a pid from a file or an old note; stop children with `chi sessions stop
+  <session id>` (execute) and background tasks with task_stop (task ids only: it doesn't stop a child).
+- A child's tool approvals go to the user on the child's card; tell the user when a report says a
+  child waits for one.
+- A report is the child's claim: verify it (step 4) before telling the user it is done, and check
+  where its commits landed: `git log --oneline <default>..<branch>` has them and `git status` in your own
+  folder is clean. A child that worked in your folder instead of its worktree: tell the user.
+- Don't send a follow-up to a child that is still running; wait for its report.
+- Don't start more children than the user asked for.
+
+## Changelog
+- 2026-10-06 created (coordinator bundle 0.1.0)
+- 2026-10-06 clean up only merged or dropped branches; report only what commands showed (0.1.2)

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

@@ -1,10 +1,10 @@
 ---
 name: dev
-version: 0.2.0
+version: 0.3.0
 scope: system
 description: "Developer tools"
 trust_level: reviewed
-requires_chi: ">= 0.32.0"
+requires_chi: ">= 0.34.0"
 includes:
 - known-names
 - mcp
@@ -12,3 +12,4 @@ includes:
 - skills
 - source-links
 - github-pr
+- coordinator

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

@@ -1,11 +1,11 @@
 ---
 name: mcp
-version: 0.4.4
+version: 0.4.5
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session, its tools are mcp_<server>_<tool>; /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:05543038e2950a5391655184f57a1028133eda8ca05f9e46e5cd2eddc3e9e608
-requires_chi: ">= 0.8.0"
+  sha256: sha256:1ebedc86cd21c918766c794015b6bd16c397c0f7e2734d939d8310d446b8a9a1
+requires_chi: ">= 0.33.0"

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

@@ -31,6 +31,7 @@
 require "digest"
 require "json"
 require "open3"
+require "samagotchi/process_group"
 require "time"
 require "shellwords"
 require "tmpdir"
@@ -59,6 +60,9 @@ class Plugin
     class Dead < Error; end
 
     POLL_SECONDS = 0.1
+    # How long close waits for the server after closing its stdin, after
+    # TERM, and after KILL.
+    STOP_GRACE_SECONDS = 1
 
     attr_reader :pid
 
@@ -136,14 +140,15 @@ class Plugin
     end
 
     # End the process: stdin closed first (most servers leave then), then
-    # TERM and KILL to its process group.
+    # TERM and KILL to its process group (chi's ProcessGroup), a second's
+    # grace each.
     def close
       @mutex.synchronize { @closing = true }
       [@stdin].each { |io| io.close unless io.closed? }
-      unless @wait.join(1)
-        signal("TERM")
-        signal("KILL") unless @wait.join(1)
-        @wait.join(1)
+      unless @wait.join(STOP_GRACE_SECONDS)
+        Samagotchi::ProcessGroup.stop(@pid, grace: STOP_GRACE_SECONDS, poll: STOP_GRACE_SECONDS,
+                                            stopped: -> { !@wait.alive? }, wait: ->(seconds) { @wait.join(seconds) })
+        @wait.join(STOP_GRACE_SECONDS)
       end
       [@stdout, @stderr].each { |io| io.close unless io.closed? }
       [@reader, @err_reader].each { |t| t.join(1) }
@@ -234,12 +239,6 @@ class Plugin
       @on_exit&.call(reason) unless closing
     end
 
-    def signal(name)
-      Process.kill(name, -@pid)
-    rescue Errno::ESRCH, Errno::EPERM
-      nil
-    end
-
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
   end