samagotchi 0.35.0 → 0.37.0

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

@@ -3,6 +3,43 @@
 Use when the user hands over work with several independent parts, or asks to "run it in parallel",
 "delegate", "coordinate". The user decides; you do the legwork and keep them in the loop briefly.
 
+## Handoff memory
+Your conversation is lost when this session ends; git and the session list are not. Keep a handoff in a
+project-scope memory named `handoff_<epic-slug>` (the epic or goal in a few lowercase words joined by
+`-`, e.g. `handoff_calc-v2`). Create it with memory_write (scope: project). Its description is the status:
+one line under 200 characters that names its owner and says where things stand, never what to do (every
+session in this repo sees it, children too): "OPEN coordinator handoff calc-v2 (session <your id>): 2/3
+merged, docs kept (user)", later "DONE: …". Change the body with `edit` on the memory's file (in the
+Project memories folder), and after every change of state change the status with memory_write name,
+scope and description only (no content). It holds ONLY what git and the session list can't rebuild:
+- Goal: the goal in one line and the split (task → branch, worktree, child session id).
+- Decisions: what the user said per branch (merge / keep / drop / "don't touch X"), their words short.
+- Verdicts: your verdict per report (verified / doubts / failed) and why, in one line.
+- Follow-ups: found but not fixed.
+Not commit lists, diffs, test output or anything a git command shows again. Update it right after:
+the split started (step 3), each verdict (step 4), each user decision (an ask_user_question answer or a
+plain message: save it before you act on it), each merge or cleanup (steps 6, 7). Before you end a turn
+in which any of these changed, check the memory and its description have it. Short: under 40 lines.
+One handoff per epic: never write another epic's handoff_* memory.
+
+## Resume (step 0)
+Before step 1, look at the project memory index for `handoff_*` entries not marked DONE (`/coordinate
+resume` picks one for the user). If one is open and the user's request continues it, or doesn't name new
+work ("hi", "what's next?", "where were we?"), do all of this before you answer:
+1. Read this skill if you haven't in this session, and memory_read the handoff: its body is the state,
+   not the index line (that line is from when this session started). Then rebuild the truth:
+   `git worktree list`, `git branch --list`, for each branch in it `git log --oneline <default>..<branch>`
+   and `git merge-base --is-ancestor <branch> <default>`, and the list_sessions tool for the child ids
+   on record (not listed is not proof a child is gone).
+2. Git and the sessions are the truth; the memory is your notes. Tell the user, per branch: its state
+   now, the decision and verdict on record, and every mismatch (merged by hand, worktree gone, branch
+   deleted, a child that ended without a verdict on record), in one short list.
+3. Update the memory and its description to match the truth (keep the decisions; mark the mismatches;
+   the owner is now you), then go on from the first open step. Don't redo a merge or cleanup git shows
+   done.
+If the request is a new goal, say which handoffs are open (one line each) and go on with a new
+`handoff_<slug>` of its own; don't touch the others.
+
 ## Steps
 1. Find the repository's default branch, <default> below: `git symbolic-ref --short
    refs/remotes/origin/HEAD` (drop the `origin/`), else `main` or `master`, whichever exists; ask the
@@ -13,34 +50,43 @@ Use when the user hands over work with several independent parts, or asks to "ru
    self-contained task. The task starts with "Work only in <absolute worktree path>: every cd, read,
    write, test and commit goes there, never the project root" and says what to report (the result,
    evidence: commands and what they printed, what isn't done) and "commit on the branch, don't merge,
-   don't push".
+   don't push, don't write or edit any handoff_* memory".
 3. Tell the user what started (one line per child: its id, branch and task) and end your turn or keep
    talking. Don't call delegate_result: chi brings each child's reply as a delegate report, also when
    you are idle.
 4. On each report, check it before telling the user: `git -C <worktree> log --oneline <default>..` and
    `git diff --stat <default>...<branch>`; run the tests the child names (execute with cwd: the worktree).
-   Say the result in one or two lines: done and verified / done with doubts / failed.
-5. Then one of: a follow-up (`delegate session: <id>`, narrower, `wait: false`; then end your turn:
-   its report comes by itself, so don't wait for it with delegate_result or task_wait), stop it
+   Say the result in one or two lines: done and verified / done with doubts / failed. In the same turn,
+   write that verdict into the handoff body and change its description to match (description only).
+5. Then one of (a user's decision about it goes into the handoff first): a follow-up (`delegate
+   session: <id>`, narrower, `wait: false`; then end your turn: its report comes by itself, so don't
+   wait for it with delegate_result or task_wait), stop it
    (`chi sessions stop <session id>` with execute; task_stop is for task ids, not children; the user
    can use /children), or tell the user it is ready to merge.
-6. Merging is the user's call: ask (ask_user_question) per branch, "Merge <branch> into <default>?".
+6. Merging is the user's call: ask (ask_user_question) per branch, "Merge <branch> into <default>?", and
+   save the answer in the handoff before you act on it.
    Before merging, in your own folder: `git branch --show-current` must print <default> (if it
    doesn't, stop and ask the user; don't switch branches yourself); then check <default>:
    `git log --oneline -3 <default>` and `git merge-base --is-ancestor <branch> <default>`; if the branch is already in, say so and don't merge
    again. Merge with `git merge --ff-only <branch>` yourself, in your own folder. If that fails, ask the
    child to rebase its branch on <default> (a follow-up that says "rebase only, don't merge") or ask the
    user; don't rebase it from here (the branch is checked out in the child's worktree). Children
-   never merge. Never push unless asked.
-7. Clean up only a branch that was merged or that the user said to drop: stop its child
-   (`chi sessions stop <session id>`), then `git worktree remove ../<repo>-<task>`, then
+   never merge. Never push unless asked. Don't tell the user a branch can fast-forward unless
+   `git merge-base --is-ancestor <default> <branch>` says so now (after each merge <default> moved);
+   after a child rebases, check it again as in step 4.
+7. Clean up only a branch that was merged or that the user said to drop (that decision saved in the
+   handoff first): stop its child (`chi sessions stop <session id>`), then `git worktree remove
+   ../<repo>-<task>`, then
    `git branch -d <branch>` (in that order: a branch checked out in a worktree can't be deleted). If
-   `-d` refuses, say why to the user; never `-D` unless they say so. Remove only worktrees and
-   branches you created in this session. Every other branch stays as it is, its child, worktree and
+   `-d` refuses, say why to the user; never `-D` unless they say so. If `git worktree remove` refuses
+   over untracked or ignored files, show `git -C <worktree> status --short --ignored` and ask; never
+   `rm -rf`. Remove only worktrees and branches you created in this session. Every other branch stays as it is, its child, worktree and
    branch too (the user said "keep it", or didn't say): leave them and tell the user they remain.
 8. When all are done, report: what merged, what didn't and why, what you cleaned up and what remains,
    follow-ups found but not fixed. Report only what the commands' output showed: a step you planned
-   but didn't run, or whose output you didn't see, is not done; say so.
+   but didn't run, or whose output you didn't see, is not done; say so. Then set the handoff's
+   description to "DONE: …" and ask the user whether to remove it (memory_write name, scope and
+   remove: true).
 
 ## Gotchas
 - Children are asked before changing anything outside their worktree (your checkout, a sibling's):
@@ -58,3 +104,5 @@ Use when the user hands over work with several independent parts, or asks to "ru
 ## Changelog
 - 2026-10-06 created (coordinator bundle 0.1.0)
 - 2026-10-06 clean up only merged or dropped branches; report only what commands showed (0.1.2)
+- 2026-10-07 handoff memory with its status in the description, resume (step 0, /coordinate resume),
+  save decisions first, fast-forward and worktree-remove checks, remove the handoff when done (0.2.0)

data/lib/samagotchi/bundles/github-pr/manifest.yml

@@ -1,8 +1,8 @@
 ---
 name: github-pr
-version: 0.1.0
+version: 0.2.0
 scope: system
-description: Attaches the branch's open GitHub pull request to a session as context (and any PR URL with chi context add or the web's "+ URL"); the agent gets a note when reviews, comments, checks or its state change
+description: Attaches the branch's open GitHub pull request to a session as context (and any PR URL with chi context add or the web's "+ URL"); the agent gets a note when reviews, comments, checks or its state change; in the web, a path:line in an answer links to that line of the PR
 trust_level: reviewed
 requires_chi: ">= 0.32.0"
 needs:
@@ -11,7 +11,7 @@ needs:
   hint: brew install gh, then gh auth login
 plugin:
   file: plugin.rb
-  sha256: sha256:b825731983a402d0cd006a17236794ef03e31ab1b160e853756f4d63b295f664
+  sha256: sha256:f8b9794f84681f3a16a4d49da3b857a59fec3ccdc2d0a2b16d1192fd2a26bdf3
 scripts:
   pr_context.rb: sha256:a883d2780e89c68c0d7b6d5e0fcb22c273f17bb167e79064e0e99db6bd2ee6f0
 context_providers:

data/lib/samagotchi/bundles/github-pr/plugin.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
 require "open3"
+require "tmpdir"
 
 # github-pr: a session on a branch with an open GitHub PR gets the PR
 # attached as context (docs/context.md) when its worker starts: a quiet
@@ -10,12 +12,46 @@ require "open3"
 # serves `chi context add <PR URL>` and the web's "+ URL"). Nothing for a
 # scratch session or a delegate child (D12), and nothing, quietly, without
 # gh, its login, a repo or an open PR.
+#
+# Line links: in the web, a `lib/foo.rb:28` (or `lib/foo.rb:28-34`, in
+# inline code too) in the model's answer links to that line of the PR the
+# session reviews: the PR's Files changed view when the lines are in a
+# hunk, else the file at the PR's head. The PRs are the session's attached
+# github-pr sources and the PR URLs in the user's messages (a delegate
+# child's task is its first one). Display only (event[:present]): the
+# model's text stays as it was. The after_turn hook links from a per-PR
+# cache and never runs gh (the web holds the answer until the hooks are
+# done); before_turn, before_generation and the init task fill the cache
+# off the turn's thread. `bundles: github-pr: line_links: false` turns it
+# off.
 class Plugin
   # gh and git each get this long (a network hang must not keep a thread).
   COMMAND_SECONDS = 20
+  # before_generation looks for a newly attached PR at most this often.
+  GENERATION_CHECK_SECONDS = 30
+
+  def initialize
+    @cache = PrCache.new
+    @generation_checked_at = nil
+  end
 
   def register(chi)
-    chi.init("Looking for this branch's pull request", quiet: true) { |ctx| attach_branch_pr(ctx) }
+    chi.init("Looking for this branch's pull request", quiet: true) do |ctx|
+      summary = attach_branch_pr(ctx)
+      # Inline (an init task has its own thread), whatever the attach
+      # returned (attached already, a child, a scratch session), and after
+      # it, so a PR it just attached is warm for the first answer.
+      refresh(ctx, attached_prs(ctx)) if line_links?(ctx)
+      summary
+    end
+    chi.on(:before_turn) do |event, ctx|
+      # The prompt too: messages is the history before this turn, and a
+      # delegate child's task is its first prompt.
+      kick(ctx, attached_prs(ctx) + PrRef.from_messages(event[:messages], prompt: event[:prompt])) if line_links?(ctx)
+    end
+    chi.on(:before_generation) { |_event, ctx| check_attached(ctx) }
+    # After source-links (90): its links are in the display this one gets.
+    chi.on(:after_turn, priority: 100) { |event, ctx| link_answer(event, ctx) }
   end
 
   # @return [String] what it did (the init task's summary)
@@ -41,11 +77,102 @@ class Plugin
     "no pull request attached"
   end
 
+  # The after_turn handler: links the answer's `path:line` refs from the
+  # PRs' cached data. Never runs gh: nothing cached yet links nothing.
+  def link_answer(event, ctx)
+    return unless line_links?(ctx) && event[:status].to_s == "completed" && event[:present]
+
+    text = LineLinker.last_model_text(event[:messages])
+    return if text.nil? || !text.match?(LineLinker::QUICK)
+
+    prs = (attached_prs(ctx) + PrRef.from_messages(event[:messages])).uniq
+    cached = prs.filter_map { |pr| (data = @cache[pr]) && [pr, data] }
+    return if cached.empty?
+
+    event[:present].call { |display| LineLinker.new(cached).link(display) }
+  end
+
+  # Fetches the PRs in +prs+ whose cache entry is missing or old, on this
+  # thread, unless a refresh runs already (the init task; #kick's thread).
+  def refresh(ctx, prs)
+    stale = @cache.stale(prs.uniq, now)
+    return if stale.empty? || !@cache.claim
+
+    begin
+      stale.each { |pr| fetch(ctx, pr) }
+    ensure
+      @cache.release
+    end
+  end
+
   private
 
+  def line_links?(ctx) = ctx.settings["line_links"] != false
+
+  def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+  # #refresh on its own thread (a raw one, docs/plugins.md), when there is
+  # something to fetch and no refresh runs. Process exit ends it; a gh
+  # still running then finishes alone.
+  def kick(ctx, prs)
+    prs = prs.uniq
+    return if prs.empty? || @cache.refreshing? || @cache.stale(prs, now).empty?
+
+    thread = Thread.new { refresh(ctx, prs) }
+    thread.report_on_exception = false
+  end
+
+  # A PR attached while the turn runs (a parent attaching it right after
+  # `delegate wait: false`), checked at most every GENERATION_CHECK_SECONDS.
+  def check_attached(ctx)
+    return unless line_links?(ctx)
+    return if @generation_checked_at && now - @generation_checked_at < GENERATION_CHECK_SECONDS
+
+    @generation_checked_at = now
+    kick(ctx, attached_prs(ctx))
+  end
+
+  # The session's attached github-pr sources, as PrRefs.
+  def attached_prs(ctx)
+    ctx.context.list.filter_map { |source| PrRef.parse(source[:hint]) if source[:provider] == "github-pr" }
+  rescue StandardError => e
+    ctx.log.debug(:pr_lines_no_sources, error: e.class.name)
+    []
+  end
+
+  # The PR's head and base, and its files when the head moved (or none
+  # are cached). A failure is remembered, so the next kicks wait.
+  def fetch(ctx, pr)
+    shas = run(ctx, "gh", "api", "repos/#{pr.owner}/#{pr.repo}/pulls/#{pr.number}", "--jq",
+               '.head.sha + " " + .base.sha', chdir: Dir.tmpdir).to_s.split
+    return failed(ctx, pr, "no pull request data") unless shas.size == 2
+
+    cached = @cache[pr]
+    files = cached.files if cached && cached.head_sha == shas[0]
+    files ||= fetch_files(ctx, pr) or return failed(ctx, pr, "no file list")
+    @cache.store(pr, PrData.new(head_sha: shas[0], base_sha: shas[1], files: files, fetched_at: now))
+    ctx.log.debug(:pr_lines_fetched, pr: pr.url, files: files.size)
+  rescue StandardError => e
+    failed(ctx, pr, "#{e.class.name}: #{e.message.to_s[0, 200]}")
+  end
+
+  # The PR's files, one JSON object a line (--jq), every page.
+  def fetch_files(ctx, pr)
+    out = run(ctx, "gh", "api", "--paginate", "repos/#{pr.owner}/#{pr.repo}/pulls/#{pr.number}/files?per_page=100",
+              "--jq", ".[] | {filename, status, previous_filename, patch}", chdir: Dir.tmpdir) or return nil
+    out.each_line.filter_map { |line| PrFile.from_api(JSON.parse(line)) unless line.strip.empty? }
+  end
+
+  # Logged once per PR until a fetch of it succeeds (no gh, no login, no
+  # network: every kick would say it again).
+  def failed(ctx, pr, why)
+    ctx.log.info(:pr_lines_not_fetched, pr: pr.url, why: why) if @cache.fail(pr, now)
+    nil
+  end
+
   # stdout of a command that succeeded within COMMAND_SECONDS, else nil.
-  def run(ctx, *command)
-    Open3.popen2(*command, chdir: ctx.cwd, err: File::NULL, pgroup: true) do |stdin, stdout, wait|
+  def run(ctx, *command, chdir: ctx.cwd)
+    Open3.popen2(*command, chdir: chdir, err: File::NULL, pgroup: true) do |stdin, stdout, wait|
       stdin.close
       reader = Thread.new { stdout.read }
       unless wait.join(COMMAND_SECONDS)
@@ -63,3 +190,317 @@ class Plugin
     nil
   end
 end
+
+# A GitHub pull request, by its URL.
+PrRef = Data.define(:owner, :repo, :number)
+
+class PrRef
+  # A PR URL anywhere in a text (trailing text allowed, like the provider's
+  # match: `…/pull/42/files`).
+  URL = %r{https://github\.com/([\w.-]+)/([\w.-]+)/pull/(\d+)}
+  # PRs taken from the user's messages, newest first.
+  FROM_MESSAGES = 3
+
+  # @return [PrRef, nil]
+  def self.parse(text)
+    match = text.to_s.match(URL) or return nil
+    new(owner: match[1], repo: match[2], number: match[3].to_i)
+  end
+
+  # The PRs the user's messages (and +prompt+, the turn's own) name, newest
+  # first, up to FROM_MESSAGES distinct. Not tool results or answers: `gh pr
+  # list` output, logs or a CHANGELOG name unrelated PRs.
+  def self.from_messages(messages, prompt: nil)
+    texts = Array(messages).filter_map do |message|
+      next unless message.is_a?(Hash)
+
+      role = message.key?(:role) ? message[:role] : message["role"]
+      (message.key?(:content) ? message[:content] : message["content"]).to_s if role.to_s == "user"
+    end
+    texts << prompt.to_s if prompt
+    found = []
+    texts.reverse_each do |text|
+      text.scan(URL).reverse_each do |owner, repo, number|
+        pr = new(owner: owner, repo: repo, number: number.to_i)
+        found << pr unless found.include?(pr)
+        return found if found.size >= FROM_MESSAGES
+      end
+    end
+    found
+  end
+
+  def url = "https://github.com/#{owner}/#{repo}/pull/#{number}"
+end
+
+# One file of a PR: its path (the new name), a rename's old one, its status
+# ("added", "modified", "removed", "renamed", …) and its hunks as line
+# ranges on each side (none: a binary file or too large a diff).
+PrFile = Data.define(:path, :previous_path, :status, :new_hunks, :old_hunks)
+
+class PrFile
+  # A hunk header: `@@ -a,b +c,d @@` (a count left out is 1).
+  HUNK = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
+
+  # @param file [Hash] one entry of the PR files API
+  # @return [PrFile, nil]
+  def self.from_api(file)
+    return nil unless file.is_a?(Hash) && file["filename"].is_a?(String)
+
+    old_hunks = []
+    new_hunks = []
+    file["patch"].to_s.scan(HUNK) do |old_start, old_count, new_start, new_count|
+      old_hunks << span(old_start, old_count)
+      new_hunks << span(new_start, new_count)
+    end
+    new(path: file["filename"], previous_path: file["previous_filename"], status: file["status"].to_s,
+        new_hunks: new_hunks.compact, old_hunks: old_hunks.compact)
+  end
+
+  # A hunk side's lines, or nil for none (`+0,0`: a removed file).
+  def self.span(start, count)
+    count = (count || 1).to_i
+    count.zero? ? nil : start.to_i..(start.to_i + count - 1)
+  end
+
+  def removed? = status == "removed"
+end
+
+# What the cache holds of a PR.
+PrData = Data.define(:head_sha, :base_sha, :files, :fetched_at)
+
+# The PRs' data, per PR, shared by the hooks' threads and the refresh's.
+class PrCache
+  # An entry (or a failed fetch) younger than this isn't fetched again.
+  FRESH_SECONDS = 60
+
+  def initialize
+    @mutex = Mutex.new
+    @entries = {}
+    @failed = {}
+    @refreshing = false
+  end
+
+  # @return [PrData, nil]
+  def [](pr) = @mutex.synchronize { @entries[pr] }
+
+  def store(pr, data)
+    @mutex.synchronize do
+      @entries[pr] = data
+      @failed.delete(pr)
+    end
+  end
+
+  # Remembers a failed fetch; true the first time since the last success.
+  def fail(pr, time)
+    @mutex.synchronize do
+      first = !@failed.key?(pr)
+      @failed[pr] = time
+      first
+    end
+  end
+
+  # The PRs whose entry is missing or older than FRESH_SECONDS (a recent
+  # failure counts as fresh).
+  def stale(prs, time)
+    @mutex.synchronize do
+      prs.reject do |pr|
+        fetched = [@entries[pr]&.fetched_at, @failed[pr]].compact.max
+        fetched && time - fetched < FRESH_SECONDS
+      end
+    end
+  end
+
+  # Takes the one refresh slot: false when a refresh runs.
+  def claim
+    @mutex.synchronize do
+      next false if @refreshing
+
+      @refreshing = true
+    end
+  end
+
+  def release = @mutex.synchronize { @refreshing = false }
+
+  def refreshing? = @mutex.synchronize { @refreshing }
+end
+
+# Links an answer's `path:line` and `path:line-line` refs to the PRs'
+# lines. A ref in inline code links when the code is the ref alone
+# (`` `foo.rb:28` `` becomes ``[`foo.rb:28`](url)``); fenced blocks,
+# markdown links and bare URLs are left alone.
+class LineLinker
+  # The answer is scanned only up to this many characters.
+  MAX_SCAN = 20_000
+  # A path (no spaces), a line, an optional end line and an optional
+  # column (kept in the link's text, not used).
+  REF = %r{(?<![\w./@+~-])(?<path>[\w./@+~-]*[\w@+~-]):(?<from>\d+)(?:-(?<to>\d+))?(?::\d+)?(?![\w/])}
+  REF_ALONE = /\A#{REF}\z/
+  # Whether an answer may hold a ref at all.
+  QUICK = /\S:\d/
+  URL_SPAN = %r{[a-z][a-z0-9+.-]*://\S+}i
+  MARKDOWN_LINK = /\[[^\]]*\]\([^)]*\)/
+  # A fenced code block's opening line (up to 3 spaces, then ``` or ~~~).
+  FENCE_OPEN = /\A {0,3}(`{3,}|~{3,})/
+
+  # The content of the last model message, or nil (string or symbol keys).
+  def self.last_model_text(messages)
+    Array(messages).reverse_each do |message|
+      next unless message.is_a?(Hash)
+      next unless (message.key?(:role) ? message[:role] : message["role"]).to_s == "model"
+
+      return (message.key?(:content) ? message[:content] : message["content"]).to_s
+    end
+    nil
+  end
+
+  # @param prs [Array<Array(PrRef, PrData)>]
+  def initialize(prs)
+    @prs = prs
+  end
+
+  # +text+ with each ref that names exactly one PR's file as a markdown
+  # link; the part beyond MAX_SCAN stays as it is.
+  def link(text)
+    head = text[0, MAX_SCAN]
+    out = +""
+    pos = 0
+    hits(head).each do |start, finish, url|
+      out << head[pos...start] << "[#{head[start...finish]}](#{url})"
+      pos = finish
+    end
+    return text if pos.zero?
+
+    out << head[pos..] << text[MAX_SCAN..].to_s
+  end
+
+  # The URL for +path+'s lines +from+..+to+ (+to+ nil: one line), or nil:
+  # no PR has the file, or more than one does.
+  def url_for(path, from, to = nil)
+    found = @prs.filter_map do |pr, data|
+      file = resolve(data.files, path)
+      [pr, data, file] if file
+    end
+    return nil unless found.size == 1
+
+    line_url(*found.first, from, to)
+  end
+
+  private
+
+  # [start, finish, url] for each ref to link, by offset.
+  def hits(text)
+    fences = fenced_blocks(text)
+    skipped = fences + spans(text, URL_SPAN) + spans(text, MARKDOWN_LINK)
+    code = inline_code(text, fences)
+    found = []
+    code.each do |start, finish, inner|
+      next if inside_any?(skipped, start, finish)
+
+      match = inner.strip.match(REF_ALONE) or next
+      url = ref_url(match) and found << [start, finish, url]
+    end
+    text.scan(REF) do
+      match = Regexp.last_match
+      start = match.begin(0)
+      finish = match.end(0)
+      next if inside_any?(skipped, start, finish) || inside_any?(code, start, finish)
+
+      url = ref_url(match) and found << [start, finish, url]
+    end
+    found.sort_by(&:first)
+  end
+
+  # A path has a `/` or an extension (`10:30` is a time, `host:8080` a port).
+  def ref_url(match)
+    path = match[:path]
+    return nil unless path.include?("/") || path.match?(/\.[A-Za-z0-9]+\z/)
+
+    from = match[:from].to_i
+    to = match[:to]&.to_i
+    to = nil if to && to <= from
+    from.zero? ? nil : url_for(path, from, to)
+  end
+
+  # The PR file +path+ names: the path (or a rename's old one) exactly,
+  # after a leading `./`; else the longest PR path +path+ ends with on a
+  # `/` boundary (an absolute path into a worktree); else the one PR path
+  # that ends with +path+ (a bare `foo.rb`). nil: none, or several.
+  def resolve(files, path)
+    path = path.sub(%r{\A(?:\./)+}, "")
+    exact = files.find { |file| file.path == path } || files.find { |file| file.previous_path == path }
+    return exact if exact
+
+    longer = files.select { |file| path.end_with?("/#{file.path}") }.max_by { |file| file.path.length }
+    return longer if longer
+
+    shorter = files.select { |file| file.path.end_with?("/#{path}") }
+    shorter.one? ? shorter.first : nil
+  end
+
+  # The PR's Files changed anchor when the lines are inside one hunk (the
+  # new side; a removed file's old side), else the file at the PR's head
+  # (a removed one: at its base), which has every line.
+  def line_url(pr, data, file, from, to)
+    last = to || from
+    hunks, side = file.removed? ? [file.old_hunks, "L"] : [file.new_hunks, "R"]
+    if hunks.any? { |hunk| hunk.cover?(from) && hunk.cover?(last) }
+      anchor = "#{side}#{from}#{"-#{side}#{to}" if to}"
+      return "#{pr.url}/files#diff-#{Digest::SHA256.hexdigest(file.path)}#{anchor}"
+    end
+
+    sha = file.removed? ? data.base_sha : data.head_sha
+    path = file.path.split("/").map { |segment| segment.gsub(/[^\w.~-]/) { |c| c.bytes.map { |b| format("%%%02X", b) }.join } }
+    "https://github.com/#{pr.owner}/#{pr.repo}/blob/#{sha}/#{path.join("/")}#L#{from}#{"-L#{to}" if to}"
+  end
+
+  # [start, finish, inner] for each inline code span outside +fences+: a
+  # run of backticks to the next run of the same length.
+  def inline_code(text, fences)
+    runs = []
+    text.scan(/`+/) { runs << [Regexp.last_match.begin(0), Regexp.last_match.end(0)] }
+    runs.reject! { |start, finish| inside_any?(fences, start, finish) }
+    by_length = Hash.new { |hash, key| hash[key] = [] }
+    runs.each_with_index { |(start, finish), index| by_length[finish - start] << index }
+    found = []
+    index = 0
+    while index < runs.size
+      start, finish = runs[index]
+      closing = by_length[finish - start].bsearch { |other| other > index }
+      if closing
+        found << [start, runs[closing][1], text[finish...runs[closing][0]]]
+        index = closing + 1
+      else
+        index += 1
+      end
+    end
+    found
+  end
+
+  def fenced_blocks(text)
+    blocks = []
+    open = nil
+    offset = 0
+    text.each_line do |line|
+      marker = line[FENCE_OPEN, 1]
+      if open.nil? && marker
+        open = [offset, marker]
+      elsif open && marker && marker[0] == open[1][0] && marker.length >= open[1].length && line.strip == marker
+        blocks << [open[0], offset + line.length]
+        open = nil
+      end
+      offset += line.length
+    end
+    blocks << [open[0], text.length] if open
+    blocks
+  end
+
+  def spans(text, regex)
+    found = []
+    text.scan(regex) { found << [Regexp.last_match.begin(0), Regexp.last_match.end(0)] }
+    found
+  end
+
+  def inside_any?(spans, start, finish)
+    spans.any? { |span_start, span_end| start >= span_start && finish <= span_end }
+  end
+end

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -60,6 +60,17 @@ rules:
     verdict: ask
     reason: rm -rf on a path outside the working tree
 
+  # memory_write remove: true moves a memory into the bundle trash. Memory
+  # files don't count as outside the repo, so nothing else asks; a delegate
+  # child could otherwise take its parent's handoff away. Every removal
+  # asks, once at a time.
+  - id: memory-remove
+    tool: memory_write
+    memory: remove
+    verdict: ask
+    scopes: [once]
+    reason: removes a memory (it goes to the bundle trash, which chi bundle trash lists)
+
   # ── running code from the network ──────────────────────────────────────
   - id: pipe-to-shell
     tool: shell

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

@@ -1,11 +1,12 @@
 ---
 name: guardrails
-version: 0.7.0
+version: 0.8.0
 scope: system
-description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
+description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer, removing a memory; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed
 # models: in small-models.yml (guardrails.small_models) needs 0.8.1; git: in rules.yml needs 0.17.0;
-# skip_read_only:, touches:, rm: and modes: need 0.20.0
-requires_chi: ">= 0.20.0"
+# a rule's memory: key (memory-remove) needs 0.36.0: an older chi refuses the rule set (unknown key), so every
+# guarded call would be refused
+requires_chi: ">= 0.36.0"
 files:
   guardrails.md: sha256:04207fd1738aeeeef3b7a8053fc57597565bddd7862f01acaba784419cbd909b

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

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