samagotchi 0.3.0 → 0.4.0

data/docs/desktop.md

@@ -1,6 +1,7 @@
 # Desktop helper (macOS)
 
-`chi desktop` installs **Chi Helper**, a small native app. It sends text you selected in any app to a chi session,
+`chi desktop` installs **Chi Helper**, a small native app. It sends text you selected in any app (or a screenshot,
+an image: see [Images](#images)) to a chi session,
 either with a question as [your message](sessions.md#sending-a-message) (a turn runs, and the answer shows in the
 attached terminal or web page), or as a [context note](sessions.md#context-notes) (the model sees it on its next
 turn, and no turn starts).
@@ -35,6 +36,32 @@ note needs a session. After the send the panel shows `started <id>…` for 3 s.
 
 A session open in a `chi --no-shared` REPL isn't listed: it takes no notes or messages.
 
+## Images
+
+The panel also sends images, as attachments of the message (`chi send --image`, see
+[Sending a message](sessions.md#sending-a-message)):
+
+- **A screenshot:** ⌃⇧⌘4 (a region to the clipboard), then ⌃⌥⌘N. The panel shows it as a thumbnail, named
+  `clipboard.png`; the context box stays empty.
+- **Finder:** right-click image files → Services → **Send to chi** (the same Service as for text, so its shortcut
+  works here too), or ⌘C on them and ⌃⌥⌘N. Up to 20 at once.
+- **Other apps:** a picture selected in Preview, Safari's Copy Image, anything that puts image data on the clipboard.
+- **Drop** image files or the floating screenshot thumbnail (⇧⌘4 to a file) anywhere on the open panel: they are
+  added to the ones there.
+
+When the clipboard holds both text and a picture (cells copied in Numbers or Excel), the text wins, as before. The
+thumbnails sit under the message line, 48 px high, the file name as a tooltip; hover one for its ✕.
+
+- A message is required with images: the line says "Say something about the image…", and ⏎ does nothing until
+  there is text (the context box counts).
+- Notes are text only: ⌘⏎ with images beeps and says "Notes are text only: ⏎ sends the image as a message".
+- The session's model must see images. A text-only one fails the turn in the session (the attached terminal or the
+  web shows why); the panel has already said it was sent.
+- A session busy with a turn runs the image message as its next turn: the line says `(runs after the current turn)`.
+- Clipboard and dropped image data goes to temp files under `$TMPDIR/chi-helper`, deleted after the send or when
+  the panel closes; files from Finder are sent as they are, never touched. A send with images may take up to 30 s
+  (converting, a worker starting) before the panel gives up.
+
 ## Install
 
 ```sh
@@ -53,16 +80,22 @@ don't break it. From a checkout it runs **that** checkout's `bin/chi`; installin
 warning, because the helper stops working once that worktree is removed. After switching between a checkout and a
 gem install, run `chi desktop upgrade` from the one you now use.
 
+`chi update` keeps it current: it rebuilds and restarts the helper only when its Swift sources changed since the
+build (`launch.json` records their digest) or the Ruby it runs moved. A new chi that left the sources alone only
+rewrites `launch.json`, which the app reads at each send, so the app keeps its older version number and that's fine.
+
 ## Commands
 
 | Command | Does |
 |---|---|
 | `chi desktop install [--force] [--login]` | builds, installs and starts it; `--force` replaces an existing copy |
-| `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting |
+| `chi desktop upgrade` | rebuilds it for this chi and restarts it, keeping the login setting (always; `chi update` does it only when needed) |
 | `chi desktop uninstall` | quits it and removes the app, its login item, launch file and settings |
 | `chi desktop status` | version against chi's, how it runs chi, state dirs, Service, hotkey, process, login item |
 
-`chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (chi is 0.1.x: chi desktop upgrade)` or `not installed`.
+`chi self` has a `desktop` line: `0.1.x (matches)`, `0.1.w (up to date for chi 0.1.x)` (an older build whose sources
+haven't changed), `0.1.w (chi is 0.1.x: chi update)` (a rebuild is due) or `not installed`. `chi desktop status`
+says the same.
 
 ## How it runs chi
 
@@ -92,7 +125,7 @@ Each call is stopped after 10 s. A stopped `chi note` says the note may be partl
 ## Troubleshooting
 
 - **"chi not found at …, run `chi desktop upgrade`"**: the Ruby or checkout in `launch.json` moved (a Ruby upgrade,
-  a removed worktree). Run `chi desktop upgrade` from the chi you use now.
+  a removed worktree). Run `chi desktop upgrade` (or `chi update`) from the chi you use now.
 - **No "Send to chi" in the Services menu:** check `chi desktop status` (service). Try
   `/System/Library/CoreServices/pbs -update`, start the app again, or log out and back in. It must be ticked in
   System Settings → Keyboard → Keyboard Shortcuts… → Services → Text.
@@ -100,4 +133,6 @@ Each call is stopped after 10 s. A stopped `chi note` says the note may be partl
   restarts or you log out: macOS caches Services.
 - **⌃⌥⌘N does nothing:** `status` says whether another app holds it. macOS doesn't report clashes with its own
   shortcuts.
+- **"Send to chi" missing on images in Finder or Preview** after an upgrade: the Services cache still has the old
+  (text-only) entry; `/System/Library/CoreServices/pbs -update`, restart the helper, or log out and back in.
 - **"No live sessions":** start one with `chi` in a terminal; `chi sessions list --live --scope=all` shows the same list.

data/docs/guardrails.md

@@ -38,6 +38,17 @@ once it closes. On a short terminal the list shrinks (the hint row, then the `in
 lines, then the header go, then the options fold onto fewer rows). Once answered, one
 line stays in the scrollback: `! execute: git push origin main → Allow once`.
 
+An `edit` or `write` also shows the change it would make, computed without
+touching the file: a `change: +3 −1` line in the question (`new file, 12 lines`;
+`would fail: old text not found in …` when the edit can't apply), and the
+unified diff itself. The web card shows the diff under the path (20 lines,
+then "show all"); the terminals print it above the question, green and red,
+40 lines at most (the rest is on the web). Binary files and files over 1 MB
+say so instead of a diff. After the call runs, its row shows what really
+changed: `diff +3 −1` under the row on the web (closed, it survives a
+reload) and ` +3 −1` at the end of the terminal's tool line. The model never
+sees these diffs.
+
 Who answers:
 
 - REPL (`chi --no-shared`, `-p` without `--non-interactive`): at the `? ` prompt.

data/docs/hooks.md

@@ -386,9 +386,11 @@ in a markdown link's label when the target names the same ref
 and `[fix for JIRA-123](https://github.com/o/r/pull/9)` still link. A ref
 glued to URL punctuation (`/browse/JIRA-1`, `?key=JIRA-1`, `JIRA-1/foo`) is
 skipped too; `Ticket:JIRA-5` and `#JIRA-123` are ordinary plain text and do
-link. Refs are deduped within the turn (case-insensitively) and listed in
-first-occurrence order, whatever order the sources are configured in. With no
-sources configured the hook is a silent no-op.
+link. The line names each URL once (compared case-insensitively: `#12` and
+`dm1try/samagotchi#12` may be one issue, and with `case_insensitive: true`
+`JIRA-1` and `jira-1` are one ticket), in first-occurrence order, whatever
+order the sources are configured in. With no sources configured the hook is a
+silent no-op.
 
 ```yaml
 bundles:
@@ -417,9 +419,8 @@ keeps the web links.
 
 The `prefix:` form compiles to `\b<prefix>-(\d+)\b` and the URL is
 `base_url` + the full ref text (`JIRA-123`). The `pattern:` form takes a
-regex; `{match}` in `url` is replaced with the first capture group (or the
-full match when the pattern has none). `case_insensitive: true` adds the
-`/i` flag. Past `max` refs the line ends with `… +N more`.
+regex and a `url:` template with placeholders (below). `case_insensitive:
+true` adds the `/i` flag. Past `max` refs the line ends with `… +N more`.
 
 Each regex is compiled with a per-regex timeout (0.5 s, per match attempt),
 so a catastrophic pattern is abandoned instead of hanging the turn: that
@@ -428,3 +429,84 @@ and the others still report. An entry with neither `prefix:` nor `pattern:`,
 or a pattern that does not compile, is skipped with a warning at load. The
 hook is `on_error: log`: a bug in it warns and the turn is unaffected. As with
 every bundle hook, a running worker picks it up after its next start.
+
+### Placeholders, and the project's own repo
+
+A `url:` template (the `pattern:` form only; `base_url:` is always
+`base_url` + the ref) can use:
+
+| placeholder | value | when it can't be filled |
+|---|---|---|
+| `{match}` | the first capture group, else the whole ref | never: it falls back to the ref |
+| `{1}` … `{9}` | a numbered capture group | the group didn't take part: the ref is **not linked** |
+| `{name}` | a named capture group `(?<name>…)` | the group didn't take part: **not linked** |
+| `{repo}`, `{host}` | the named group `repo` / `host` when the pattern has one and it took part; else the project's git remote | neither: **not linked** |
+
+A ref with a placeholder that can't be filled is left out of both the line
+and the answer: no URL is built with a hole in it (another source on the same
+ref can still link it). A `{word}` or `{N}` that is none of the above (not a
+group of the pattern, or `{7}` in a two-group pattern) stays as literal text,
+with one warning when the source is loaded. Every value is percent-encoded
+(everything outside `A-Za-z0-9-._~`, `/` included), except that `{repo}`
+keeps its `/` between segments (GitLab's `group/sub/proj`); a `{repo}` with an
+empty, `.` or `..` segment counts as unfilled.
+
+So one source links both `#12` in this project and a cross-repo ref:
+
+```yaml
+bundles:
+  source-links:
+    sources:
+      - name: GitHub
+        # `#12` → this project's repo; `owner/repo#12` → that repo
+        pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w))?#(?<num>\d+)\b'
+        url: 'https://github.com/{repo}/issues/{num}'
+        remote_host: github.com
+```
+
+```
+sources: GitHub #12 → https://github.com/dm1try/samagotchi/issues/12, GitHub rails/rails#5 → https://github.com/rails/rails/issues/5
+```
+
+GitHub redirects `/issues/N` to `/pull/N` and back, so one URL covers issues
+and pull requests. The lookbehind keeps `&#123;`, `x/#1` and a partial
+`b/c#1` inside `a/b/c#1` out; code and URLs are skipped as always. `PR #12`
+links, `PR#12` doesn't (a `#` right after a letter). The pattern is loose on
+purpose: a bare `#\d+` also matches "step #2", and `and/or#5` or `TCP/IP#3`
+read as qualified refs. A stricter variant wants `PR #`, `issue #` or a
+qualified ref:
+
+```yaml
+        pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w)#|\b(?:PR|[Ii]ssue) #)(?<num>\d+)\b'
+```
+
+**Where `{repo}` and `{host}` come from.** Without a named group that took
+part, they come from `git remote get-url <remote>` run in the session's
+working directory (the worker's; the in-process REPL's is the terminal's
+current directory). `remote:` picks the remote, default `origin` — a fork
+sets `remote: upstream`. Git applies `insteadOf` rewrites and includes, and a
+worktree reports its main repo's remote. The URL forms understood are
+`https://`, `http://`, `ssh://`, `git://` (credentials and port dropped) and
+scp-like `[user@]host:owner/repo`; the repo is the path without a trailing
+`.git` or `/`. A local path, `file://`, no git, no repo or no such remote
+leaves the ref unlinked, silently (a debug log line only). Git is asked only
+when a hit needs it — a JIRA source or a qualified ref never runs it — and
+the answer, even "none", is remembered for the worker's life: a remote
+changed mid-session counts after the worker's next start.
+
+`remote_host:` (a host or a list, compared case-insensitively) applies the
+remote-derived links only when the remote's host is one of them, so a
+`https://github.com/{repo}/…` template never points a GitLab project's `#12`
+at github.com. A qualified ref is linked whatever the local remote is. An SSH
+alias (`git@github-work:o/r.git` from a multi-account `~/.ssh/config`) or an
+`insteadOf` mirror reports its own host; list it too:
+`remote_host: [github.com, github-work]`.
+
+Two Ruby regex notes. With named groups in a pattern, a plain `(…)` doesn't
+capture and gets no number, so `{1}` is the first *named* group, and so is
+`{match}` (in the example above `{match}` is the repo part): use either named
+or numbered groups in one pattern, and named placeholders with named groups.
+And a pattern with a `host` (or `repo`) group lets the model's text choose the
+link's domain (or repo): the escaping rules out URL injection, but the choice
+of the target is the model's.
+

data/docs/releasing.md

@@ -15,13 +15,13 @@ can run the whole release; the user approves the notes before the tag and the
 - **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:
+  `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:`
     (`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.
+  - the release notes say "run `chi update`" and name the bundles whose
+    version moved (what changed in each), not per-bundle upgrade steps.
 - 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.
 
@@ -58,9 +58,9 @@ 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`).
+   `## [Unreleased]` in CHANGELOG.md into short user-facing lines. End with
+   "Update with `chi update`", naming the 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`.

data/docs/sessions.md

@@ -58,6 +58,21 @@ chi sessions clean --dry-run --days 7            # test sessions older than 7 da
 
 `--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, project, updated_at, live, busy, owner, recap, parent_id, archived, scratch, ctx_pct}]` (`owner`: `"worker"`, `"tui"` for a plain REPL, which takes no notes or messages, or null; `recap`: the first sentence of the session's recap, or null), `--format tsv` one `id<TAB>desc` line per session, where `desc` is `<folder> · <last prompt>` cut to 60 characters (the text form of `--live`/`--cwd` shows `<folder> · <recap>` when there is one; tsv and json keep `desc`).
 
+**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 start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first command line (`/model …`) still starts the session as its `prompt`. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`.
+- Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
+- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`). 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.
+- A `chi scratch` session (`"scratch": true`) is deleted when its REPL ends; one a killed process left behind is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it. `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
+- 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.
+
 ## Context notes
 
 A context note is text pushed into a session as background: not a prompt, and it starts no turn.
@@ -120,8 +135,9 @@ cancel during its thinking, it said it had never been asked.
 `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 TEXT] [--image PATH]... (ID|PREFIX)...
 chi send -m "is this the same bug?" 3fa2           # a message
+chi send --image shot.png -m "why is this red?" 3fa2  # with an image
 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
 ```
@@ -130,7 +146,8 @@ pbpaste | chi send 3fa2                             # the clipboard is the messa
 - 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`.
+- `--image PATH` (repeatable, up to 20) sends images with the message, as the web composer's chips do. Each file is read once before anything is sent (bmp, tiff and heic converted to png, large ones downscaled, as for `@path`); a missing file or one that isn't an image is a usage error (exit 2) and nothing is sent. Each session gets its own copy in `<session>/images/`. Text is still required (`-m` or stdin; context alone counts), also with `--wait`. The session's model must see images: a text-only one fails the turn in the session (the line here still says `sent`). A running turn doesn't take images mid-turn: the message runs as the next turn, and the line says `(runs after the current turn)`. With `--new` the session starts idle with the message as its preview, then the message goes in as its first turn once its worker is up (`<id>  started with 1 image`); if the worker doesn't come up in 5 s the session is kept, with its id on the `failed:` line.
+- One line per session: `sent`, `sent with 2 images`, `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)`.
 
@@ -164,18 +181,3 @@ The `delegate` tool hands a task to a **child session**: an ordinary chi session
 - Every child starts with the shipped `delegated` system memory preloaded (`preloaded_memory_names: ["system/delegated"]`; `--mute delegated` would hide it): put everything in the final reply, don't delegate further, don't write memories or change config, stay in the folder. Its system prompt also says `Delegated by session <parent id>`. The parent's own `--mute` list does not carry over.
 - 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 start page's first message goes as later ones do: `POST /api/sessions` with `idle: true` and `preview` (the message, which names the session until its turn is saved), then `POST /api/sessions/:id/turn`, so a failed first turn puts its prompt back in the composer too; a first command line (`/model …`) still starts the session as its `prompt`. The browser remembers the last choice; a running session's model is in the info bar and changes only with `/model`.
-- Web notifications: when a session needs you while the tab is hidden or behind another window (a question or a guardrail approval, a plugin card with buttons during a turn such as check-in's, a failed turn, a turn done after 10 s or more; a delegated session only for its questions, a canceled turn never), the page title counts it, `(N) Chi`, until you come back to the tab. The bell at the right of the top bar also turns on OS notifications ("needs an answer", "needs approval", "needs you", "turn failed", "done in 42 s", under the session's first message; a click opens the session): its first click asks the browser for the permission, and the choice is kept per browser. Any session of the page's scope counts, not only the open one. What was already so when the page loaded never counts, and several chi tabs show one notification per event. A chi tab in front tells the others (a `BroadcastChannel`), so while you look at one, the ones behind neither notify nor count what it shows; coming back to a tab clears those events in the other tabs' titles too. The hub's `session` frames carry what this needs: `pending_question` (`{id, kind}`, kind `question` or `approval`), `pending_card` (`{id, bundle}`: the running turn's card with actions, from `pending_card.json` that the worker keeps in the session's folder while one is open; a card without actions, such as loop-guard's, never counts) and `last_turn` (`{outcome, ended_at, seconds, origin}`, saved in the session's JSON as the engine ends each turn).
-- The web frontend is a zero-build ES-module stack in `lib/samagotchi/web/public/`: `data.js` (retrieval, typed SSE `openStream` for a session and `openEvents` for the session list), `sessions_list.js` (the list as a pure reducer over `GET /api/events`: a snapshot replaces it, an upsert keeps a known card in place, a removal drops it), `notify.js` (which of those events needs the user, for the notifications), `app.js` (presentation/state; a session with no live stream gets one when its `session` event says `bridge_up`, after one re-read: `event_seq` starts over in each worker, so a dropped stream is never resumed with its old cursor), `format.js` (pure formatters such as `previewOf`). 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.
-- A `chi scratch` session (`"scratch": true`) is deleted when its REPL ends; one a killed process left behind is deleted by the next sweep, `prune` or `clean`, whatever its age or status, once nobody owns it. `list` shows it as `[scratch]` (every text form; `scratch: true` in `--format json`); `chi web` never shows one. See [CLI: Scratch sessions](cli.md#scratch-sessions).
-- 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/turn_accumulator.rb

@@ -159,6 +159,7 @@ module Samagotchi
           tool[:output] = capped ? output[0, @max_output_chars] : output.dup
           tool[:output_truncated] = capped || !!event[:output_truncated]
           tool[:images] = event[:images] if event[:images]
+          tool[:diff] = event[:diff] if event[:diff]
         when :pending_input_merged
           # A steer-only merge (count 0) has no user part: the origins stay
           # for the user lines' own merge.

data/lib/samagotchi/bridge.rb

@@ -19,6 +19,7 @@ require_relative "engine"
 require_relative "session_commands"
 require_relative "image_store"
 require_relative "log"
+require_relative "version"
 
 module Samagotchi
   # Bridge is an optional HTTP transport that lets an external web / desktop
@@ -961,7 +962,9 @@ module Samagotchi
         "port" => @port,
         "bind" => @bind,
         "session_id" => @session_id,
-        "started_at" => Time.now.iso8601(3)
+        "started_at" => Time.now.iso8601(3),
+        # The chi this worker runs (chi update reports older ones).
+        "version" => Samagotchi::VERSION
       }
       record["input_format"] = @input_format if @input_format
       path = File.join(session_dir, SIDECAR_FILE)

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+# Loaded through module_eval: it requires what it uses.
+require "open3"
+
 # An after_turn hook that links the source refs the model's answer
 # mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
 # web, each ref in the answer becomes a link (`[JIRA-123](https://…)`,
@@ -22,10 +25,24 @@
 #           pattern: '\bGH-(\d+)\b'   # full form: a regex
 #           url: 'https://github.com/org/repo/issues/{match}'
 #           case_insensitive: false   # optional, default false
+#         - name: Issues              # `#12` → this project's repo,
+#                                     # `owner/repo#12` → that repo
+#           pattern: '(?<![\w/&])(?:(?<repo>[A-Za-z0-9][\w-]*/[\w.-]*\w))?#(?<num>\d+)\b'
+#           url: 'https://github.com/{repo}/issues/{num}'
+#           remote: origin            # optional: the git remote {repo}/{host}
+#                                     # come from, default origin
+#           remote_host: github.com   # optional: a host or a list; else a
+#                                     # remote on another host links nothing
 #       max: 10                       # optional: refs per line, default 10
 #       note: false                   # optional: no sources line (the web
 #                                     # links stay), default true
 #
+# A `url:` template takes {match} (group 1, else the whole ref), {1}…{9}
+# (numbered groups), {name} (named groups), and {repo}/{host}: the named
+# group when it took part, else the project's (Dir.pwd's) git remote, asked
+# of git once per worker. A ref with a placeholder that can't be filled is
+# not linked; a `{word}` that is none of these stays text (warned at load).
+#
 # The note is not stored in the conversation: it is an event, replayed by a
 # UI only while the session's worker lives (a reload keeps it; a stopped
 # worker loses it). The links are stored as the answer's display. A ref in
@@ -47,6 +64,32 @@ class SourceLinks
   MARKDOWN_LINK = /\[([^\]]*)\]\(([^)]*)\)/
   # A fenced code block's opening line (up to 3 spaces, then ``` or ~~~).
   FENCE_OPEN = /\A {0,3}(`{3,}|~{3,})/
+  # A `{word}` or `{N}` placeholder in a `url:` template.
+  PLACEHOLDER = /\{(\w+)\}/
+  # Placeholders every pattern has: {match} (group 1, else the whole ref),
+  # and {repo}/{host} (a named group, else the project's git remote).
+  BUILTIN_PLACEHOLDERS = %w[match repo host].freeze
+  # `git remote get-url` output: a URL with a scheme, `[user[:pw]@]host[:port]/path`.
+  REMOTE_URL = %r{\A(?:https?|ssh|git)://(?:[^/]*@)?(\[[^\]]*\]|[^/:@]+)(?::[^/]*)?(/.*)?\z}i
+  # scp-like `[user@]host:path`: a colon before any slash; a leading `/` or
+  # `.` is a local path.
+  REMOTE_SCP = %r{\A(?:[^@/:]+@)?([^/:.@][^/:@]*):(.*)\z}
+
+  # The {host:, repo:} a git remote URL names, or nil (a local path,
+  # `file://`, an empty path, or a path with an empty or dot segment).
+  def self.parse_remote_url(url)
+    url = url.to_s.strip
+    # Any other scheme (file://, a transport helper's) is not a web host.
+    match = url.include?("://") ? url.match(REMOTE_URL) : url.match(REMOTE_SCP)
+    return nil unless match
+
+    host = match[1]
+    repo = match[2].to_s.sub(%r{\A/+}, "").sub(%r{/+\z}, "").sub(/\.git\z/, "").sub(%r{/+\z}, "")
+    segments = repo.split("/", -1)
+    return nil if host.empty? || segments.empty? || segments.any? { |segment| ["", ".", ".."].include?(segment) }
+
+    { host: host, repo: repo }
+  end
 
   def initialize(settings = {})
     settings = {} unless settings.is_a?(Hash)
@@ -54,6 +97,9 @@ class SourceLinks
     max = settings["max"].to_i
     @max = max.positive? ? max : DEFAULT_MAX
     @note = settings["note"] != false
+    # [Dir.pwd, remote name] => {host:, repo:} or nil, for the worker's life.
+    @remotes = {}
+    @host_mismatch_logged = {}
   end
 
   def call(event)
@@ -115,9 +161,12 @@ class SourceLinks
           next if inside_markdown_link?(links, text, match)
           next if url_adjacent?(text, match)
 
+          # An unresolved placeholder: no link, from this source.
+          url = source[:url].call(match[0], match)
+          next if url.nil?
+
           quiet = inside_any?(code, start, finish) || inside_any?(labels, start, finish)
-          hits << { start: start, finish: finish, name: source[:name], ref: match[0],
-                    url: source[:url].call(match[0], match), quiet: quiet }
+          hits << { start: start, finish: finish, name: source[:name], ref: match[0], url: url, quiet: quiet }
         end
       rescue Regexp::TimeoutError
         Samagotchi::Log.warn(:hooks, "source_links_timeout",
@@ -131,11 +180,12 @@ class SourceLinks
   end
 
   # [name, ref, url] for the note: first-occurrence order, deduped by the
-  # ref text case-insensitively.
+  # URL case-insensitively (`#12` and `o/r#12` may name one issue; with
+  # case_insensitive, `JIRA-1` and `jira-1` are one ticket).
   def collect(hits)
     seen = {}
     hits.filter_map do |hit|
-      key = hit[:ref].downcase
+      key = hit[:url].downcase
       next if seen.key?(key)
 
       seen[key] = true
@@ -336,7 +386,12 @@ class SourceLinks
       name = "source" if name.empty?
       regex = Regexp.new(pattern, flags, timeout: REGEX_TIMEOUT)
       template = entry["url"].to_s
-      { name: name, regex: regex, url: ->(ref, match) { template.gsub("{match}", escape_url(match[1] || ref)) } }
+      known = known_placeholders(name, template, regex)
+      remote = entry["remote"].to_s.strip
+      remote = "origin" if remote.empty?
+      hosts = Array(entry["remote_host"]).map { |host| host.to_s.strip.downcase }.reject(&:empty?)
+      source = { name: name, remote: remote, remote_hosts: hosts }
+      source.merge(regex: regex, url: ->(ref, match) { render_url(template, known, match, ref, source) })
     else
       warn_invalid("a source needs a prefix: or a pattern:")
       nil
@@ -346,6 +401,124 @@ class SourceLinks
     nil
   end
 
+  # The placeholders of +template+ this pattern can fill: {match}, {repo},
+  # {host}, its named groups and {1}…{N} for its N groups. Any other
+  # `{word}` stays as text, with one warning here, at compile time.
+  def known_placeholders(name, template, regex)
+    used = template.scan(PLACEHOLDER).flatten.uniq
+    groups = group_count(regex)
+    known, unknown = used.partition do |word|
+      if word.match?(/\A\d+\z/)
+        groups.nil? || (word.to_i.between?(1, groups))
+      else
+        BUILTIN_PLACEHOLDERS.include?(word) || regex.names.include?(word)
+      end
+    end
+    unless unknown.empty?
+      list = unknown.map { |word| "{#{word}}" }.join(", ")
+      Samagotchi::Log.warn(:hooks, "source_links_unknown_placeholder",
+                           echo: "[samagotchi:hooks] source-links: #{name}: #{list}: no such group in its pattern; " \
+                                 "left as text")
+    end
+    known
+  end
+
+  # How many groups +regex+ captures (with named groups, only those), found
+  # by matching an always-empty alternative; nil when that fails.
+  def group_count(regex)
+    probe = Regexp.new("(?:#{regex.source}\n)|", regex.options, timeout: REGEX_TIMEOUT)
+    probe.match("").size - 1
+  rescue RegexpError, Regexp::TimeoutError
+    nil
+  end
+
+  # The URL for one hit: +template+ with its +known+ placeholders filled, or
+  # nil when one can't be (a group that didn't take part, a {repo} with an
+  # empty or dot segment, no remote): we never build a URL with a hole.
+  def render_url(template, known, match, ref, source)
+    unresolved = false
+    url = template.gsub(PLACEHOLDER) do
+      word = Regexp.last_match(1)
+      next Regexp.last_match(0) unless known.include?(word)
+
+      value = placeholder_value(word, match, ref, source)
+      unresolved = true if value.nil?
+      value.to_s
+    end
+    unresolved ? nil : url
+  end
+
+  # One placeholder's escaped value, or nil when it is unresolved.
+  def placeholder_value(word, match, ref, source)
+    case word
+    when "match" then escape_url(match[1] || ref)
+    when /\A\d+\z/ then match[word.to_i]&.then { |value| escape_url(value) }
+    when "repo", "host"
+      value = match.names.include?(word) ? match[word] : nil
+      value ||= remote_value(word, source)
+      word == "repo" ? escape_repo(value) : value&.then { |host| escape_url(host) }
+    else match[word]&.then { |value| escape_url(value) }
+    end
+  end
+
+  # {repo} / {host} from the project's git remote (the source's `remote:`,
+  # default origin); nil when there is none, or when its host is not one of
+  # the source's `remote_host:` list.
+  def remote_value(word, source)
+    remote = project_remote(source[:remote])
+    return nil unless remote
+
+    hosts = source[:remote_hosts]
+    unless hosts.empty? || hosts.include?(remote[:host].downcase)
+      key = [source[:name], remote[:host]]
+      unless @host_mismatch_logged[key]
+        @host_mismatch_logged[key] = true
+        Samagotchi::Log.debug(:hooks, "source_links_remote_host_mismatch", source: source[:name],
+                                                                          host: remote[:host], remote_host: hosts.join(","))
+      end
+      return nil
+    end
+    remote[word.to_sym]
+  end
+
+  # The project's (Dir.pwd's) remote +name+ as {host:, repo:}, or nil.
+  # Asked of git lazily (only a hit that needs it) and remembered, nil too,
+  # per [Dir.pwd, name]: git applies insteadOf rewrites and includes, and a
+  # worktree reports its main repo's remote.
+  def project_remote(name)
+    key = [Dir.pwd, name]
+    return @remotes[key] if @remotes.key?(key)
+
+    @remotes[key] = read_remote(key[0], name)
+  end
+
+  def read_remote(dir, name)
+    out, status = Open3.capture2({ "GIT_DIR" => nil, "GIT_WORK_TREE" => nil },
+                                 "git", "-C", dir, "remote", "get-url", name, err: File::NULL)
+    unless status.success?
+      Samagotchi::Log.debug(:hooks, "source_links_no_remote", remote: name, exit: status.exitstatus)
+      return nil
+    end
+    remote = self.class.parse_remote_url(out)
+    Samagotchi::Log.debug(:hooks, "source_links_remote", remote: name, host: remote&.dig(:host), repo: remote&.dig(:repo))
+    remote
+  rescue SystemCallError => e
+    Samagotchi::Log.debug(:hooks, "source_links_no_remote", remote: name, error: e.class.name)
+    nil
+  end
+
+  # A repo path with each `/`-separated segment escaped and the `/` kept
+  # (GitLab's `group/sub/proj`); nil for an empty, `.` or `..` segment, which
+  # a browser would resolve out of the path.
+  def escape_repo(value)
+    return nil if value.nil?
+
+    segments = value.split("/", -1)
+    return nil if segments.empty? || segments.any? { |segment| ["", ".", ".."].include?(segment) }
+
+    segments.map { |segment| escape_url(segment) }.join("/")
+  end
+
   def warn_invalid(reason)
     Samagotchi::Log.warn(:hooks, "source_links_invalid_source",
                          echo: "[samagotchi:hooks] source-links: skipping a source: #{reason}")

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,14 +1,14 @@
 ---
 name: source-links
-version: 0.2.0
+version: 0.3.0
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
 files:
-  source_links.md: sha256:0fb30311603c60f062740917ad0670904e022e8975b1d0eafe3df9e2904f2fe0
+  source_links.md: sha256:aebd37f1e25491780994ecc4afc20ed6e8db32b724dc038302bb050177efada8
 hooks:
   source_links.rb:
-    sha256: sha256:5f2b8d5248efc7e0a98185d9e53a47e6a3edfe7c43ee5bf0ebe44d07f18d61aa
+    sha256: sha256:0ee86a932efc90d81777855c81dea16510710d7371fe8b6b146a5a16b29794c2
     event: after_turn
     on_error: log
     priority: 90

data/lib/samagotchi/bundles/source-links/source_links.md

@@ -2,4 +2,4 @@
 
 The `source-links` bundle's `after_turn` hook links the source refs (a JIRA ticket, a GitHub issue, …) in your answers. In the web, each ref in the answer becomes a link; that is how the answer is **shown**, not what you wrote: your own message keeps the plain ref. A `sources: NAME ref → url, …` line right after an answer is the same hook's note, which every UI shows (the terminals only see this line). The line is **not part of the conversation**: it is an event, so it is not in the session file and you cannot refer back to it. A UI replays it while the session's worker lives (a page reload keeps it; a stopped worker loses it).
 
-The refs come from the `bundles: source-links:` section of config.yml: each source is a `prefix:` + `base_url:` pair (simple) or a `pattern:` regex + `url:` template (full form), plus an optional `max:` for refs per line and `note: false` to drop the line (the web links stay). With no sources configured the hook does nothing. A ref already inside a URL is not linked again, and a ref in code or in a markdown link is not linked in the answer.
+The refs come from the `bundles: source-links:` section of config.yml: each source is a `prefix:` + `base_url:` pair (simple) or a `pattern:` regex + `url:` template (full form), plus an optional `max:` for refs per line and `note: false` to drop the line (the web links stay). A `url:` template can take the project's own repo from its git remote, so a bare `#12` links to this project's issue and `owner/repo#12` to that repo's. With no sources configured the hook does nothing. A ref already inside a URL is not linked again, and a ref in code or in a markdown link is not linked in the answer.