samagotchi 0.2.0

data/docs/releasing.md

@@ -0,0 +1,135 @@
+# Releasing
+
+samagotchi is published to rubygems.org as the gem `samagotchi` (command `chi`)
+by GitHub Actions when a `v*` tag is pushed. Nothing publishes from a laptop:
+there is no API key anywhere, and bundler's `rake release` is removed. An agent
+can run the whole release; the user approves the notes before the tag and the
+`release` environment after it.
+
+## Versions
+
+- **The gem and the system bundle share one version.** `lib/samagotchi/version.rb`
+  and `lib/samagotchi/bundles/system/manifest.yml` are bumped together (a spec
+  and `rake release:check` enforce it). The system bundle upgrades itself when
+  chi starts.
+- **Every other shipped bundle** (btw, guardrails, known-names, loop-guard,
+  mcp) 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 bundle upgrade NAME`. So:
+  - a change to a bundle's files bumps that bundle's `version:`
+    (`rake bundles:check` fails otherwise, once there's a tag to compare with);
+  - a bundle that uses something new in chi raises its `requires_chi` in the
+    same change; `release:bump` never touches `requires_chi`;
+  - the release notes list the `chi bundle upgrade NAME` steps for every
+    bundle whose version moved.
+- Pre-1.0: config and commands may change in a minor version (0.2 → 0.3); a
+  patch version (0.2.0 → 0.2.1) is fixes only.
+
+## CHANGELOG.md
+
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/): user-facing lines
+under `## [Unreleased]`, grouped as `### Added`, `### Changed`, `### Fixed`
+(and `### Removed` / `### Security` when needed). Write them for someone who
+uses chi, not for someone who reads the diff: what changed for them, in one
+line each. A merge with a user-visible change adds its line; anything missed is
+drafted at release time (`rake release:draft_changelog`). Internal refactors,
+specs and docs-only changes don't get a line.
+
+`rake release:bump[X.Y.Z]` turns `## [Unreleased]` into `## [X.Y.Z] - date`
+under a fresh empty Unreleased, and updates the compare links at the bottom.
+The release workflow uses that section, as printed by `rake release:notes[X.Y.Z]`,
+as the GitHub release body.
+
+## Tasks
+
+| 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). |
+| `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`, 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). |
+| `rake release:notes[X.Y.Z]` | Prints the CHANGELOG section (default: the current VERSION). |
+
+## Runbook
+
+The agent does each step and stops where the user has to say yes.
+
+1. **Start from main, up to date and green.** `git checkout main && git pull`;
+   CI on main is green.
+2. **Draft the notes.** `bundle exec rake release:draft_changelog`, then edit
+   `## [Unreleased]` in CHANGELOG.md into short user-facing lines. Add the
+   `chi bundle upgrade NAME` steps for bundles whose version moved since the
+   last tag (`git diff vPREV -- lib/samagotchi/bundles/*/manifest.yml`).
+   Pick the version: fixes only → patch, anything else → minor.
+3. **The user approves the notes and the version.** Show them the section.
+4. **Bump.** `bundle exec rake "release:bump[X.Y.Z]"`, review `git diff`.
+5. **Check.** Commit first (the check wants a clean tree), then run it:
+   `git commit -am "Release X.Y.Z"` and `bundle exec rake release:check`.
+   Fix anything it finds in new commits and run it again.
+6. **Push main.** `git push origin main`; wait for CI to go green.
+7. **Tag and push the tag.**
+   `git tag -a vX.Y.Z -m "samagotchi X.Y.Z" && git push origin vX.Y.Z`
+   (push the tag alone; never `--tags`, `--all` or `--mirror`).
+8. **The user approves the `release` environment** in the Actions run
+   (Review deployments → Approve).
+9. **Watch the run.** `gh run watch` (or `gh run list --workflow release.yml`).
+   It checks that the tag is `v` + VERSION and on main, builds the gem, pushes
+   it with a trusted-publishing token and creates the GitHub release with the
+   notes and the .gem attached.
+10. **Verify the published gem** in a clean GEM_HOME:
+    ```sh
+    tmp=$(mktemp -d)
+    GEM_HOME=$tmp GEM_PATH=$tmp gem install samagotchi -v X.Y.Z --no-document
+    HOME=$tmp/home XDG_CONFIG_HOME=$tmp/home/.config XDG_STATE_HOME=$tmp/home/.local/state \
+      GEM_HOME=$tmp GEM_PATH=$tmp $tmp/bin/chi --version    # chi X.Y.Z
+    ```
+    and `chi self` the same way. Then tell the user; on their machine
+    `gem update samagotchi` (and `chi desktop upgrade` if they use the desktop
+    helper).
+
+If the run fails before `gem push`, fix it on main, delete the tag
+(`git push origin :refs/tags/vX.Y.Z && git tag -d vX.Y.Z`) and tag again. A
+version that reached rubygems.org can never be pushed again: fix forward with
+the next patch version.
+
+## One-time setup
+
+Done once, before the first release, in one sitting (the pending publisher
+expires):
+
+1. **rubygems.org**: an account with MFA on. Profile → Trusted Publishers →
+   *Create a pending trusted publisher* (the gem doesn't exist yet):
+   gem name `samagotchi`, repository owner `dm1try`, repository name
+   `samagotchi`, workflow filename `release.yml`, environment `release`;
+   leave *workflow repository* blank. **A pending publisher expires 12 hours
+   after it's created**: push the first tag within that window, or create it
+   again. After the first push it becomes the gem's trusted publisher for good.
+2. **GitHub, Settings → Environments → New environment `release`**: required
+   reviewer = the maintainer; deployment branches and tags → selected, the tag
+   pattern `v*`.
+3. **GitHub, Settings → Rules → Rulesets → New tag ruleset**: target `v*`,
+   restrict creations, updates and deletions to the maintainer (and the agent's
+   credentials if they push tags), block force pushes.
+
+## Yanking
+
+A broken release is yanked, then fixed forward:
+
+```sh
+gem yank samagotchi -v X.Y.Z    # needs a rubygems.org login with MFA (an API key with the yank scope)
+```
+
+Yanking hides the version from installs; it can't be pushed again. Mark the
+GitHub release as such (`gh release edit vX.Y.Z --prerelease` or edit its
+notes: "yanked: …"), add a `### Fixed` line under Unreleased, and release the
+next patch version.
+
+## Known CI gaps
+
+Some examples pass on macOS but fail on Linux CI. They carry `:ci_todo` and are
+skipped when `CI` is set: `chi send`/`chi note` subprocess specs (a child
+`ruby` without the bundle can't load nokogiri), `--all` on a peer list, the
+desktop fields in `chi self` (Linux has no helper), and KernelLoop's
+`send_note`. `spec/gem_contents_spec.rb` is skipped on Ruby 3.3 under CI
+(`Zlib::BufError` from `Gem::Package.build`). Fix these, then drop the tags.

data/docs/sessions.md

@@ -0,0 +1,155 @@
+# Sessions
+
+Sessions are plain files — no DB. Each session is `~/.local/state/samagotchi/sessions/<uuid>.json` (XDG-aware via `XDG_STATE_HOME`) plus a sidecar dir `<uuid>/` with `input/`/`notes/`/`output/`/`pid`/`bridge.json` (`Session.session_dir`). Besides the messages and turn state, the JSON keeps `used_memory_names` (what the session read), `preloaded_memory_names` (`--memory`) and `muted_memory_names` (`--mute`), the last two written before the worker starts so a respawn builds the same prompt, and `parent_id`, the session that delegated this one (see *Delegating*; `null` otherwise); files from before those keys read as empty lists and no parent.
+
+**Retention (file-based, opt-out via env):**
+
+| Env | Default | Purpose |
+|-----|---------|---------|
+| `SAMAGOTCHI_SESSION_RETENTION_DAYS` | `14` (`0`=forever) | Delete if `updated_at` older than N days |
+| `SAMAGOTCHI_SESSION_MAX_COUNT` | `500` (`0`=uncapped) | Keep newest N, prune overflow |
+| `SAMAGOTCHI_SESSION_KEEP_STATUS` | (none) | CSV of statuses never auto-pruned |
+| `SAMAGOTCHI_SESSION_SWEEP_INTERVAL_HOURS` | `24` | Throttle lazy sweep |
+
+A session is deleted if **expired by age OR overflow by count** (unless `keep_status` or the live-owner guard: a session a worker or `chi` still has open is never pruned). A session's `status` is its turn state (`idle`/`running`), not whether a worker is alive. Orphan dirs without a `*.json` are never deleted, except skeleton-only ones (see *Empty sessions*). Deletion removes both `*.json` and sidecar dir atomically. Set both `DAYS=0` and `MAX=0` to retain forever.
+
+**Worker idle exit:** a background worker (plain `chi`, Web UI sessions) exits after `SAMAGOTCHI_SESSION_IDLE_EXIT_MINUTES` (`session.idle_exit_minutes`, default `30`, `0`=never) with no turn running or queued, no client on its stream (an open web tab or attached terminal keeps it), no reminder registered and no continue offer waiting for an answer. It removes `bridge.json` and frees `owner.lock`; the next prompt or `--attach` wakes a new worker (`WorkerIdleExit`, `SessionManager.run_session_loop`). A client can also ask the worker to exit right away (Bridge `POST /session/:id/exit`; `/exit` in an attached terminal does, `/detach` doesn't): the same rules apply without the timeout (even with `0`), and the asker's own stream doesn't count. The reply names what keeps it up. The session's status stays as it was, not `stopped`.
+
+**Empty sessions:** a session nothing happened in is deleted when it is left, so `chi` → `/exit` leaves no trace. Empty means: no messages, no turn tried (a failed turn leaves a `last_prompt` and keeps it), no memory used, no pending question, nothing in `input/`, `notes/` or `images/`, nothing in its dir beyond the worker's skeleton, mode `assist`, and the default model. A session on another model (`/model`, `--model`) counts as prepared and stays (`SessionManager.empty_session?`). The worker checks as it idle-exits or leaves on a client's request and deletes it once its lock is free, checking again first. The attached `/exit` then says `Detached; the session was empty, so it is discarded.` The REPL (`--no-shared`) does the same at `/exit` or Ctrl-D. The retention sweep catches those killed first: empty sessions over an hour old with no live owner, whatever `DAYS`/`MAX`, and skeleton-only dirs with no `*.json`. `session.keep_empty: true` (env `SAMAGOTCHI_SESSION_KEEP_EMPTY`) turns all of it off.
+
+**Attached by default:** plain `chi` and `chi --resume ID` run their session in a background worker and attach to it (`session.shared`, default `true`; env `SAMAGOTCHI_SESSION_SHARED`). The worker runs in the session's `working_directory`, so `!commands` and tools see the directory the session was started in. `session.shared: false` keeps the in-process REPL, `--no-shared` does for one run; a session the REPL has open can't be attached ("close it there first"). See [CLI: Sharing a session](cli.md#sharing-a-session).
+
+**Stopping a worker:** `chi sessions stop ID` marks the session stopped, sends its worker TERM and waits (up to 10 s) until the worker has let go of `owner.lock`, so a `chi --resume ID` right after spawns a fresh worker. That is also how to restart a worker still running an older chi, which the attached terminal and the web report when a command or a question dismiss gets a 404 (`BridgeClient.stale_worker_message`). The web's `POST /api/sessions/:id/stop` waits the same way, for 2 s.
+
+**Deleting a session:** `chi sessions delete ID...`, `/exit --delete` in a terminal and the Web UI's delete all go through `SessionManager.delete_session`: it resolves a unique prefix, removes `<id>.json` and the whole `<id>/` dir, and returns what it removed. A session a plain REPL has open (`owner.lock` kind `tui`) is always refused. One a worker runs is refused unless the caller asks to stop it: then it stops the worker as `chi sessions stop` does and deletes once `owner.lock` is free (`--force` on the CLI, 10 s; the web always, 2 s; `/exit --delete` after the worker agreed to exit, 10 s). A worker that outlives the wait leaves the session in place. The web's route is `DELETE /api/sessions/:id` (200 `{status: "deleted", session_id, stopped}`; 409 `owned_by_tui` or `still_stopping`; 404).
+
+**Lazy sweep:** automatic prune runs at most once per 24h on `GET /api/sessions` (Web). No background thread or cron. Manual prune is always available.
+
+**CLI:**
+
+```sh
+chi sessions list [--sort updated_at|created_at] [--order desc|asc] [--limit N] [--scope=all]
+chi sessions list [--live] [--cwd PATH] [--limit N] [--format text|json|tsv] [--scope=all]
+chi sessions stop ID
+chi sessions delete [--force] ID...                    # for good; --force stops a live worker first
+chi sessions prune [--dry-run] [--days N] [--keep N] [--keep-status running,...] [--test-only]
+chi sessions clean [--dry-run] [--days N]             # test sessions: all, or older than N days
+```
+
+Examples:
+
+```sh
+chi sessions list --sort updated_at --order desc --limit 20
+chi sessions prune --dry-run --days 14 --keep 500
+chi sessions prune --days 14 --keep 500          # actually delete
+chi sessions clean --dry-run                     # every test session, whatever its age
+chi sessions clean --dry-run --days 7            # test sessions older than 7 days
+```
+
+`--dry-run` is the safe preview. Web has no prune endpoint; use the CLI.
+
+`chi sessions list` shows each session's saved recap, its first sentence without the "The user was…" opening (as on the web cards), in place of its last prompt, cut to 60 characters; a session with no recap shows its last prompt. A delegated session's row ends with `↳ <parent's short id>` (plain and `--live`; `--format json` has `parent_id`); rows keep their `updated_at` order, so a parent may be on another page than its children.
+
+**Projects:** a session belongs to the git project it was started in: the repository, whichever worktree or subfolder of it (the same project root memories use). `chi sessions list` (with `--live` and `--format` too) and `chi web` show the current folder's project; `--scope=all` shows every session, and so does a folder in no repo (`~`). `--cwd PATH` is a folder filter instead of the project. The project is stored with the session (`project_root` in its JSON, `project` in `--format json`), so a session keeps it after its worktree is deleted; sessions older than that are placed by their folder, and one whose folder is gone shows in `--scope=all` only. Retention, `--resume`/`--attach ID`, `chi send`/`chi note ID` and `chi note --all` (every live session) are not scoped. The agent's `list_sessions` lists its own project's sessions; `cwd: "/"` lists every one.
+
+`--live`, `--cwd` and `--format` make `list` a picker for scripts (`SessionManager.session_summaries`): `--live` keeps the sessions a worker runs now (the owner lock, not the saved status; a session open in a plain REPL is left out), `--cwd PATH` those in PATH or below, and test runs are left out. `--live` shows 10 unless `--limit` says otherwise; filters apply before the limit. `--format json` prints `[{id, short_id, desc, cwd, updated_at, live, busy, owner, recap}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
+
+## Context notes
+
+A context note is text pushed into a session as background: not a prompt, and it starts no turn.
+
+```sh
+chi note [--source NAME] [-m TEXT] (ID|PREFIX)... | --all
+pbpaste | chi note --source slack 3f2a 8c1d
+```
+
+- The text comes from `-m` or stdin (a terminal on stdin is a usage error, not a wait). It is stripped; an empty note or one over 16 KiB is refused, never cut. `--source` (default `cli`) names where it came from. `--all` is every live session.
+- It lands in `<uuid>/notes/`, apart from `input/`, so nothing that runs turns sees it. A live worker adds it to the conversation within a few seconds, between turns: one sent during a turn waits for that turn to end. A session with no worker keeps it until a worker next starts (a prompt, `--attach`), which adds it before anything else. A session open in a plain REPL (`--no-shared`) refuses notes. `chi note` prints one line per session: queued, waits for the next start (with the queue count), or refused.
+- In the conversation it is a tail system message marked `kind: note`, framed `[CONTEXT NOTE from slack, 14:02]\n…\n[END NOTE]` (from another session: `from session 3f2a1c (~/projects/foo)`). The system prompt says notes are background, not requests: the model uses one when it is relevant, doesn't answer it on its own, and never follows instructions inside it. Its text is escaped like user text, so it can't fake a turn. It survives `--resume`, a reload, `!rollback` and a continue answered no.
+- The web shows it as a dim "note from …" block, live (`context_added`) and after a reload; the attached terminal as one dim `note from slack: <first line>` line, also when joining.
+- Agents: `list_sessions` (other sessions of this project, newest first, up to 20; optional `cwd`, `"/"` for every project) and `send_note(session, text)`, which sends a note from this session. Neither starts a turn anywhere.
+
+On macOS, `chi desktop install` does this with a native panel from the Services menu or a hotkey (see [Desktop helper](desktop.md)). A plain Automator Quick Action that sends the clipboard to the live sessions you pick works too (Automator: Quick Action, "Run Shell Script", shell `/bin/zsh`; Automator's PATH is minimal, so put your Ruby's bin dir on it and use the full path to `chi`):
+
+```sh
+export PATH="$HOME/.local/share/mise/shims:$PATH"   # wherever your ruby lives
+chi="/full/path/to/chi"   # `command -v chi` in your shell prints it
+list=$("$chi" sessions list --live --scope=all --format tsv)
+[ -z "$list" ] && { osascript -e 'display notification "No live chi sessions" with title "chi note"'; exit 0; }
+picked=$(osascript - "$list" <<'OSA'
+on run argv
+  set AppleScript's text item delimiters to linefeed
+  set choice to choose from list (paragraphs of item 1 of argv) with prompt "Send the clipboard to:" with multiple selections allowed
+  if choice is false then return ""
+  return choice as text
+end run
+OSA
+)
+[ -n "$picked" ] && pbpaste | "$chi" note --source clipboard $(print -r -- "$picked" | cut -f1)
+```
+
+## Notes a turn leaves for the model
+
+A turn that ends without an answer leaves one line for the model to read on its next turn, as a tail
+system message marked `kind: turn_note` (the UIs don't show it; they showed the end itself as it happened):
+
+- failed before any answer (a dead host, retries run out, an auth error): `[SYSTEM: the previous turn failed
+  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;
+- cancelled (Ctrl-C, the web's stop): `[SYSTEM: the previous turn was cancelled (ctrl-c) after 12s; the answer
+  above ends where it was cut off.]`, 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
+  nothing). The user's last message is still unanswered.]`.
+
+When the context window fills past 40% (then 60%, 80%), the native loop leaves a similar line (`kind: context`):
+`[CONTEXT: about 55% of the context window is in use (estimated; bucket=40plus). context moderate — prefer targeted
+and range reads over full-file dumps]`, once per rise; see [context telemetry](internals/context-telemetry.md).
+
+Failed retries replace the note, they don't pile up. The note's text is escaped like user text (an error may
+quote what a server sent). A cancelled continue turn and `!rollback` go back to before the turn, note included.
+Without it, the model saw an unanswered user message and no reason: asked "did your last answer finish?" after a
+cancel during its thinking, it said it had never been asked.
+
+## Sending a message
+
+`chi send` is the other half of `chi note`: the text goes in as your message, the same as typing it in the attached terminal or the web composer, so a turn runs.
+
+```sh
+chi send [-m TEXT] (ID|PREFIX)...
+chi send -m "is this the same bug?" 3fa2           # a message
+pbpaste | chi send -m "is this the same bug?" 3fa2  # the clipboard quoted above the message
+pbpaste | chi send 3fa2                             # the clipboard is the message
+```
+
+- With both stdin and `-m`, stdin is context: each line becomes a `> ` quote (as web annotations quote a selection), then a blank line, then the message. With only one, it goes in as is. A terminal on stdin is ignored. Both empty is a usage error; over 16 KiB is refused, never cut.
+- It goes through the same path as the web composer (`SessionManager.deliver_turn`): the worker's Bridge when it is up, so every attached UI shows it as your message (client id `cli:send`, shown like any user message); the input file when the worker is on its way out. During a running turn it is merged into that turn at the next step, like a message typed then.
+- A session with no worker gets one started (like `--attach` or the web composer). A session open in a plain REPL (`--no-shared`) refuses it. Only sessions on this machine: Bridges listen on 127.0.0.1.
+- Fire and forget: it returns once the message is queued and never prints the answer; that shows in whatever is attached. A guardrail "ask" waits for a UI to answer it, so with nothing attached the turn stalls there until one attaches (`chi --attach ID`).
+- One line per session: `sent`, `sent (the running turn picks it up)`, `sent (started its worker)`, `refused: …` or `failed: …`. Exit 0 when all were sent, 1 when any was refused, failed or not found, 2 for a usage error. There is no `--all`.
+
+The Automator action above works for messages too: swap its last line for `pbpaste | "$chi" send -m "what do you make of this?" $(print -r -- "$picked" | cut -f1)`.
+
+## Delegating
+
+The `delegate` tool hands a task to a **child session**: an ordinary chi session in a worker of its own, started in the parent's `working_directory` with the task, verbatim, as its first user message, on the parent's model unless the call names one (`model:` takes a name or an alias, resolved as `--model` is; nothing checks the host serves it, so an unknown one fails the child's first turn). 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; `timeout`, default 600 s, leaves a slow child running). 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. The reply comes back once; a later call waits for the next one.
+- What a wait returns, `session: <id>` then `status:` and the text: `done` with the reply after a `---` line; `waiting_for_answer` as soon as the child opens a question or a guardrail approval (nothing is answered for it: attach or use the web, then wait again); `canceled` when the parent's own turn is canceled (the child keeps running; the next turn can wait again); `no_reply` when the child's turn ended with nothing to say (canceled, failed or empty: its session shows what happened); `error` (its worker crashed) or `stopped` (`chi sessions stop`) at once; `running` on timeout. A reply saved before the child's worker idle-exited is returned at once.
+- 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.
+- 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; `GET /api/sessions` and `/api/sessions/:id` carry it, and `SessionManager.children_of` lists a parent's children.
+
+**Ordering:**
+
+- `Session.list` / `SessionManager.list_sessions` / `GET /api/sessions?sort=&order=&limit=&offset=` default to `updated_at desc` (newest activity first). Also supports `created_at`, `asc`. `X-Total-Count` header when paginated.
+- Web UI (`chi web`): the page's scope is in its URL. Started in a git repo, `chi web` opens `/?dir=<that folder>`: that project's sessions, and new chats start in that folder; the header chip says `<project> · all`, and `all` opens the same place without `?dir` (every session; a new chat there starts in the server's own folder, shown on the start page, and cards name their folder; `← <project>` goes back to the project view it came from, or to the server's own project). One server serves every project: a second `chi web` (from another repo) finds it through `GET /api/info` and prints (with `--open`, opens) its page for its own folder instead of starting another. The 3 latest sessions sit above the chat; "All sessions" (or `/`) opens every session at `#/sessions`, with a search over preview, id and status (Esc or Back returns). The open session is in the URL (`#/s/<id>`), so a reload or a copied link opens it again; the chi logo top left goes back to the empty start for a new chat. The message box grows with its text; drag its top edge to keep it taller (double-click resets). The info bar copies `chi --attach <id>` for a terminal. The start page's model picker (bottom left of the composer, `host:model ▾`) chooses the model a new chat starts on: `GET /api/models` lists the hosts' models as chi spells them (`{default, models: [{name, host, id}], warning?}`; bare for the default host, `host:model` for the others, from the same cached lists as `/models`, a bounded wait, a host that is down noted in `warning`), and `POST /api/sessions` takes `model` (blank means the default). The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`.
+- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`). Unit-tested via `npm test` (`node --test spec/web/public/*.test.js`).
+- Selecting a session in the web UI is read-only: `GET /api/sessions/:id` never spawns a worker (it reads a live worker's snapshot when one runs, else the session file). A prompt (`POST /turn`) or a command (`POST /command`) wakes the worker, and `/stream` briefly waits for a freshly-spawned bridge before answering. A caught-up SSE reconnect holds the stream open; `reset` markers are only sent for reconnects behind the ring window, or with a cursor from another worker (event ids are `<event_seq>-<epoch>`, one epoch per worker).
+
+**Test-session hygiene:**
+
+- New sessions set `test_run:true` when `SAMAGOTCHI_ENV=test` or `RACK_ENV=test` or `CI` is set (explicit flag, `metadata_version` 2). Old sessions without the flag load as `test_run:false`.
+- Test runs are tagged and obey the same retention. `chi sessions clean` deletes every test session whatever its age (`--days N`: only those older than N days); a live worker or a `keep_status` status still keeps one. `chi sessions prune --test-only` applies the usual age and count rules to test sessions only.
+- For ad-hoc manual QA use `SAMAGOTCHI_ENV=test XDG_STATE_HOME=/tmp/chi-test-$USER chi ...` to isolate from real state; the flag also marks sessions that `chi web` or an attached `chi` spawn (their workers inherit the environment), so `clean` finds them if they land in the real state.

data/lib/samagotchi/bridge/bounded_queue.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module Samagotchi
+  class Bridge
+    # A thread-safe bounded FIFO used to decouple the turn thread (which
+    # enqueues SSE events from inside `Engine#emit_event`) from the dedicated
+    # writer thread that serialises frames onto the socket.
+    #
+    # Enqueue (#push) is O(1) and never blocks the turn, even if the writer
+    # thread is blocked on a slow / hung client socket. When the buffer is
+    # full the oldest entry is dropped and an overflow marker is pushed in its
+    # place so the writer can surface a reset to the client rather than
+    # growing memory without bound.
+    class BoundedQueue
+      def initialize(capacity:)
+        @capacity = [1, capacity].max
+        @mutex = Mutex.new
+        @cv = ConditionVariable.new
+        @items = []
+        @overflow_dropped = false
+      end
+
+      # Enqueue an item. Non-blocking; drops the oldest entry on overflow and
+      # records that overflow happened.
+      def push(item)
+        @mutex.synchronize do
+          @items << item
+          @overflow_dropped = false if @items.size == 1
+          while @items.size > @capacity
+            @items.shift
+            @overflow_dropped = true
+          end
+          @cv.broadcast
+          nil
+        end
+      end
+
+      # Pop the oldest item, waiting up to +timeout+ seconds (nil → block).
+      # Returns nil on timeout or when drained.
+      def pop(timeout)
+        @mutex.synchronize do
+          @cv.wait(@mutex, timeout) if timeout && @items.empty?
+
+          @items.shift
+        end
+      end
+
+      # @return [Boolean] true when an overflow has dropped entries since the
+      #   last successful drain to empty.
+      def overflow_dropped?
+        @mutex.synchronize { @overflow_dropped }
+      end
+
+      # Clear the overflow flag after a consumer has handled it.
+      def clear_overflow!
+        @mutex.synchronize { @overflow_dropped = false }
+      end
+
+      def size
+        @mutex.synchronize { @items.size }
+      end
+
+      def empty?
+        @mutex.synchronize { @items.empty? }
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge/card_store.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Bridge
+    # The last cards (Engine#show_card) and hook notices (:hook_notice),
+    # for a UI that joins later: the Bridge's snapshot[:cards]. A
+    # persistent observer, like TurnAccumulator.
+    #
+    # A turn's own notice (no between_turns) is in_turn like a turn's card,
+    # with the step it came in: +iteration+ and +calls+, the calls of that
+    # iteration started before it (a before_tool_call hook's notice comes
+    # before its call's row, so the web puts it above row calls + 1).
+    #
+    # A card with an earlier card's id replaces it where it was. Each entry
+    # says where it belongs as the recap does: +turns_since+, the turns
+    # completed after it (after its own turn for a card shown during one),
+    # and +current+ for a card of the turn running now. Turns count from
+    # this worker's start; the ones before it are in no entry. A card that
+    # isn't the turn's but comes while one runs (an anytime command's, such
+    # as /btw) goes after that turn: its prompt is already in the history.
+    # A failed turn leaves no prompt, so its cards stay before the next one.
+    class CardStore
+      CAPACITY = 20
+      # A failed turn's prompt goes back to the composer: no turn in the
+      # conversation.
+      TURN_ENDS = %i[turn_completed turn_canceled].freeze
+
+      def initialize(capacity: CAPACITY)
+        @capacity = capacity
+        @mutex = Mutex.new
+        @entries = []
+        @turns_done = 0
+        @running = false
+        @iteration = nil
+        @calls = 0
+      end
+
+      def call(event)
+        @mutex.synchronize { fold(event) }
+      rescue StandardError
+        nil # never break the running turn
+      end
+
+      # @return [Array<Hash>] oldest first: the card's (or notice's) fields
+      #   plus turns_since: and current:, and during: true for a card that
+      #   came while the running turn runs but isn't that turn's (it goes
+      #   after the running turn's prompt)
+      def list
+        @mutex.synchronize do
+          @entries.map do |entry|
+            turns = entry[:turns]
+            current = entry[:in_turn] && @running && turns == @turns_done
+            since = @turns_done - turns - (entry[:in_turn] && !current ? 1 : 0)
+            listed = entry.except(:turns, :during).merge(turns_since: [since, 0].max, current: current ? true : false)
+            listed[:during] = true if entry[:during]
+            listed
+          end
+        end
+      end
+
+      private
+
+      def fold(event)
+        case event[:type]
+        when :turn_started
+          @running = true
+          @iteration = nil
+          @calls = 0
+        when :generation_started
+          @iteration = event[:iteration]
+          @calls = 0
+        when :tool_call_started
+          @iteration = event[:iteration]
+          @calls = event[:call_index].to_i
+        when :turn_failed
+          @running = false
+          settle_during(after_turn: false)
+        when *TURN_ENDS
+          @running = false
+          @turns_done += 1
+          settle_during(after_turn: true)
+        when :card then add_card(event)
+        when :hook_notice then add_notice(event)
+        end
+      end
+
+      def add_card(event)
+        card = event.slice(:type, :id, :source, :title, :body, :level, :actions)
+        index = @entries.index { |entry| entry[:type] == :card && entry[:id] == card[:id] }
+        if index
+          # Replaced where it was: the first one's place stays.
+          old = @entries[index]
+          @entries[index] = card.merge(updated: true, **old.slice(:in_turn, :turns, :during))
+        else
+          entry = card.merge(in_turn: event[:in_turn] ? true : false, turns: @turns_done)
+          entry[:during] = true if @running && !event[:in_turn]
+          push(entry)
+        end
+      end
+
+      # The turn a :during card came in has ended: it counts as after that
+      # turn when the turn is in the history.
+      def settle_during(after_turn:)
+        @entries.each do |entry|
+          next unless entry.delete(:during)
+
+          entry[:turns] = @turns_done if after_turn
+        end
+      end
+
+      def add_notice(event)
+        notice = event.slice(:type, :hook, :text, :level)
+        if event[:between_turns] || !@running
+          push(notice.merge(in_turn: false, turns: @turns_done))
+        else
+          push(notice.merge(in_turn: true, turns: @turns_done, iteration: @iteration, calls: @calls).compact)
+        end
+      end
+
+      def push(entry)
+        @entries << entry
+        @entries.shift while @entries.size > @capacity
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge/event_id.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Bridge
+    # The SSE id of an event: `<seq>-<epoch>`, the seq first so that a reader
+    # taking it as a number (`to_i`, `parseInt`) still gets the seq.
+    module EventId
+      PATTERN = /\A(\d+)(?:-([0-9A-Za-z]+))?\z/
+
+      module_function
+
+      # @return [String] "<seq>-<epoch>", or the bare seq without an epoch
+      def format(seq, epoch)
+        epoch ? "#{seq}-#{epoch}" : seq.to_s
+      end
+
+      # @return [Array(Integer, String|nil)] the seq and the epoch (nil for a
+      #   plain seq). Anything else reads with `to_i`, as before.
+      def parse(cursor)
+        m = PATTERN.match(cursor.to_s.strip)
+        m ? [m[1].to_i, m[2]] : [cursor.to_s.to_i, nil]
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge/ring_buffer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Samagotchi
+  class Bridge
+    # A bounded, thread-safe in-memory ring buffer of emitted events, keyed by
+    # the Engine's monotonic `event_seq`. One shared instance per bridge
+    # (owned by the capture observer) so that any client reconnecting from a
+    # given `Last-Event-ID` can replay the same window. Oldest entries are
+    # dropped past the capacity, which is what makes a too-old reconnect
+    # replay nothing and fall back to a reset marker.
+    #
+    # This is in-memory sequence (ordering + short reconnect), not durable
+    # cross-process resume — durable resume is a staged next step.
+    class RingBuffer
+      def initialize(capacity: 256)
+        @capacity = [1, capacity].max
+        @mutex = Monitor.new
+        @events = [] # Array<{seq:, data:}>
+      end
+
+      # Append +data+ keyed by +seq+ (drop oldest beyond capacity).
+      def push(seq:, data:)
+        @mutex.synchronize do
+          @events << { seq: seq, data: data }
+          @events.shift until @events.size <= @capacity
+          nil
+        end
+      end
+
+      # Buffered events with seq in the half-open range (after_seq, to_seq].
+      # Returns shallow copies so callers may serialise without holding the
+      # lock (or retaining the structure).
+      def events_in_range(after_seq:, to_seq:)
+        return [] if to_seq <= after_seq
+
+        @mutex.synchronize do
+          @events.select { |e| e[:seq] > after_seq && e[:seq] <= to_seq }.map { |e| e.dup }
+        end
+      end
+
+      # Whether any buffered event could satisfy a reconnect from +from_seq+.
+      def has_any_after?(from_seq:)
+        @mutex.synchronize { @events.any? { |e| e[:seq] > from_seq } }
+      end
+
+      # @return [Integer, nil] the highest seq buffered so far.
+      def last_seq
+        @mutex.synchronize { @events.last&.[](:seq) }
+      end
+
+      # @return [Integer, nil] the lowest seq buffered so far.
+      def oldest_seq
+        @mutex.synchronize { @events.first&.[](:seq) }
+      end
+
+      def empty?
+        @mutex.synchronize { @events.empty? }
+      end
+    end
+  end
+end