samagotchi 0.32.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9af1ef94626f6ec7c44f8a7a0ad46421eca3c770b9b0bc6dab78664ec3a9cd9
-  data.tar.gz: bb2db5c510efa064f5c377335d83b6df450a67f0bafa8c70e4160ef97dc2d874
+  metadata.gz: c6f812c6128ae3ffaf91d9cc04716a77d351fb57793a7d9a4863e675f1f2337f
+  data.tar.gz: 25e7600fe6dc335b7d28320795a03ea9e8527185f6a0dd918787777458402f39
 SHA512:
-  metadata.gz: af61e4ce113e2dea9a3ecf9bedc4d7335aa35f7aca81e37734a952e150f79930e9a6451e1c22c507762caafa76c29fd324fe3544e901cf70fa6783547cf5924e
-  data.tar.gz: fd9ca3f931a144e48e8a120202000cf845806aaaedb676d3dde3a094e03432bc19f79eadac054363f7248c257bec7fe74ba3ae99f8b682492215dae64a4e7392
+  metadata.gz: 322e9f5a5b553f7ed1f2955307b8d5bd8c901a355ac3ffcdff6b3fcb5013b28011c7c330d9496486338c77d2c0f58e2854393d4cb40ec33d00ed2516a38bd066
+  data.tar.gz: f6048763f53d9b865858842acaf60587d5e57a365aaba759c3c85fcf69532227c4b201fe0f878da3e48191dd43856637dad29537203a3dfd7159756caac6f778

data/CHANGELOG.md

@@ -8,6 +8,78 @@ 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
+
+- Input from a client chi doesn't know (a script calling the web API with its own id, say) is no longer taken
+  for the user's: the model reads it as automatic input, not your message, and it never cuts in on a thinking
+  model. The TUI and the web label a prompt by its sender: "chi send", "chi answer", "plugin", or "automatic";
+  "user" is left for your own lines.
+
+### Fixed
+
+- `task_stop` no longer signals a process group chi didn't start: a missing or reused pid in a task record could
+  stop chi or other processes.
+- A delegate child that crashes still wakes its idle parent.
+- `chi send <id> --wait` to a stopped session with attached context prints the answer instead of "no answer".
+- `chi bundle build` keeps a bundle's `scripts:` and `context_providers:`, so a rebuilt bundle still attaches its URLs.
+- A context source's wake is no longer lost when a later update that doesn't ask to wake comes in before the
+  session reads it.
+- A failed wake turn leaves a plain note in the conversation; a reload no longer draws an empty turn for it.
+- Web: the info bar no longer swallows a click on "copy chi --attach" or Restart while a turn runs, and its
+  tooltips stay up.
+- Web: an image the server refuses shows why; a 409 that isn't "open in a chi REPL" no longer switches the page to
+  the REPL notice.
+- Web: an answer equal to an earlier turn's ("Done." twice) is shown.
+
+Update with `chi update`.
+
 ## [0.32.0] - 2026-10-06
 
 ### Added
@@ -1636,7 +1708,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.32.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
 [0.30.0]: https://github.com/dm1try/samagotchi/compare/v0.29.0...v0.30.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

@@ -135,7 +135,9 @@ attaches a URL; the web never adds a command.
 A change can start a turn by itself, so the agent tells you about it while
 you're away from the terminal. All of these must hold:
 
-- the source asked (`"wake": true`; a plain-text source never does);
+- the source asked (`"wake": true`; a plain-text source never does), in
+  any change since the session last heard of it: a later change that doesn't
+  ask doesn't take the wake back;
 - `context.wake` is on (default `true`);
 - the session's worker is up and idle: no turn running, nothing queued, no
   question or continue offer waiting, not just started;
@@ -152,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

@@ -122,9 +122,12 @@ Its `source` is the hook's bundle (a config or turn hook's label otherwise).
 Lines typed into a running turn are saved as `{role: "user", kind: "input",
 content: "…"}`: part of that turn, not a turn of their own. They carry a
 `source` when they are not the user's own: `chi_send` (`chi send -m`),
-`parent_agent` (a delegate's follow-up) or `plugin_send` (`ctx.sessions.send`).
-The model reads them with the same kind of header (`[Steer from the user, …]`,
-`[Steer sent with chi send, …]`, and so on).
+`parent_agent` (a delegate's follow-up), `plugin_send` (`ctx.sessions.send`),
+or `automatic:<client id>` for a client id chi doesn't know (an unknown sender
+is never taken for the user). The model reads them with the same kind of
+header (`[Steer from the user, …]`, `[Steer sent with chi send, …]`, and so
+on; `[Automatic input from <client id>, sent mid-task; not your user's
+message. …]` for an unknown one).
 
 Timing: a notice from `:after_turn` or `:session_end` shows after the turn's
 end line. A question from `:before_tool_call` shows **before** the tool
@@ -417,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
@@ -1181,7 +1256,8 @@ gem.
 - `chi bundle diff <name> [plugin.rb]`: shows the installed base and the
   file on disk.
 - `chi bundle build --name <name>`: puts the installed plugin (and
-  `requires_chi`) into the built bundle.
+  `requires_chi`, its `scripts/` and `context_providers:`) into the built
+  bundle.
 - `chi bundle uninstall <name>`: removes the plugin with the bundle.
 
 ## Not yet

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:`
@@ -49,7 +49,8 @@ as the GitHub release body.
 | Task | What it does |
 | --- | --- |
 | `rake bundles:sha` | Recomputes the sha256 lines of every shipped bundle manifest (`files:`, `hooks:`, `plugin:`). |
-| `rake bundles:check` | Sha lines match; a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: raise it if the change uses anything new. |
+| `rake bundles:check` | Sha lines match; a bundle changed since the last `v*` tag has a higher version (skipped, with a note, before the first tag). Warns (doesn't fail) when such a bundle's `requires_chi` still admits the tagged chi: raise it if the change uses anything new. The release workflow and `release:check` run it in full. |
+| `rake 'bundles:check[ci]'` | The CI workflow's (every push and PR): the same, except the version check leaves out the system bundle, which is changed and unbumped between releases (`release:bump` moves its version with VERSION). A task argument, not `CI=1`: GitHub sets `CI` in the release workflow too. |
 | `rake release:draft_changelog` | A draft Unreleased section from the commit subjects since the last tag, grouped. Stdout only. |
 | `rake release:bump[X.Y.Z]` | VERSION, the system manifest, Gemfile.lock, CHANGELOG. No commit. |
 | `rake release:check` | Clean tracked tree, VERSION == system bundle, a CHANGELOG section, `bundles:check`, `rake lint` (RuboCop), rspec + npm test, `gem build`, then a clean install into a temp GEM_HOME that runs `chi --version`, `chi self` and `chi bundle list` with a temp HOME. Needs the network (gem dependencies). |

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/answer_command.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "client_id"
 require_relative "session"
 require_relative "session_manager"
 require_relative "bridge_client"
@@ -189,7 +190,7 @@ module Samagotchi
                   client.dismiss_question(id: qid)
                 else
                   client.answer(id: qid, selected: selected, freeform: options[:text],
-                                client_id: Guardrails::ParentApprovals::CLIENT_ID)
+                                client_id: ClientId::CLI_ANSWER)
                 end
         break unless reply.status == 408
       end

data/lib/samagotchi/archive_store.rb

@@ -17,12 +17,6 @@ module Samagotchi
   # file from memory (and bumps updated_at) at every turn.
   module ArchiveStore
     FILE = "archived"
-    # Input a human typed: a web tab, a chi TUI, `chi send`, and nil (a
-    # worker's initial prompt; a web client may send none). Delegates,
-    # plugins and reminders are not (an allowlist, so a new automatic
-    # origin stays out).
-    USER_CLIENT_PREFIXES = %w[web: tui:].freeze
-    USER_CLIENT_IDS = ["cli:send"].freeze
 
     # @return [Hash, nil] the marker (string keys), nil when none or unreadable
     def self.read(session_dir)
@@ -57,15 +51,7 @@ module Samagotchi
       write(session_id, { "unarchived_at" => Time.now.iso8601(3) }, state_dir: state_dir)
     end
 
-    # Whether +client_id+ (a turn's origin) is a human's input.
-    def self.user_input?(client_id)
-      return true if client_id.nil?
-
-      id = client_id.to_s
-      USER_CLIENT_IDS.include?(id) || USER_CLIENT_PREFIXES.any? { |prefix| id.start_with?(prefix) }
-    end
-
-    # A human's input came into the session: it is back in the lists. Its
+    # A human's input (ClientId.human?) came into the session: it is back in the lists. Its
     # children stay archived. Never raises.
     # @return [Boolean] whether it was archived
     def self.user_input(session_id, state_dir:)

data/lib/samagotchi/bridge.rb

@@ -55,6 +55,8 @@ module Samagotchi
     CANCEL_REASONS = %w[manual user ctrl_c].freeze
     # How long #stop waits for requests it is answering (not open streams).
     REQUEST_GRACE_SECONDS = 1.0
+    # How long #stop waits for each killed RelayWatcher thread to end.
+    RELAY_WATCHER_JOIN_SECONDS = 1.0
     # The largest request body read (images travel as refs, never bytes).
     MAX_BODY_BYTES = 1_000_000
     # A request's deadline (see #handle_post_turn) that isn't epoch seconds.
@@ -198,7 +200,9 @@ module Samagotchi
       await_answers(REQUEST_GRACE_SECONDS)
       @connection_threads.each { |t| t.kill rescue nil }
       @connection_threads.clear
-      @mutex.synchronize { @relay_watchers&.each { |t| t.kill rescue nil } }
+      # Its relay watchers (RelayWatcher) end with it.
+      watchers = @mutex.synchronize { (@relay_watchers || []).tap { @relay_watchers = [] } }
+      watchers.each { |thread| thread.kill.join(RELAY_WATCHER_JOIN_SECONDS) }
       @accept_thread&.join(2)
       remove_sidecar
       nil
@@ -839,8 +843,9 @@ module Samagotchi
       return [{}, 500, { error: "enqueue_failed", detail: "could not write turn input" }] unless enqueued
 
       # Queued (outside the event lock): a running generation that has only
-      # been thinking for long is cut for it, unless a plugin sent it. An
-      # image input never merges mid-turn, so it never cuts.
+      # been thinking for long is cut for it, unless a plugin or a client
+      # chi doesn't know sent it. An image input never merges mid-turn, so
+      # it never cuts.
       @engine.cut_for_steer(Steer.source_for_client(client_id), epoch: epoch) if images.empty?
       [{}, 202, { status: "accepted", enqueued_id: enqueued_id, session_id: @session_id }]
     end

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"