samagotchi 0.52.0 → 0.54.0

data/docs/internals/context-telemetry.md

@@ -5,7 +5,7 @@ web/SSE clients) as a `:context_status` stream event. The telemetry itself is
 not injected into the model's conversation; what the model gets is one short
 line, as a tail system message (`kind: context`), when usage rises into a bucket
 whose guidance asks it to change how it works (from the second threshold, 40%
-by default, up; never on a fall or a cadence tick, and not again for a bucket a
+by default, up; never on a fall, and not again for a bucket a
 resumed session's line already names):
 
 `[CONTEXT: about 55% of the context window is in use (estimated; bucket=40plus). context moderate — prefer targeted and range reads over full-file dumps]`
@@ -19,8 +19,12 @@ carries a `status` string using this prefix:
 
 Emission behavior:
 
-- A status is emitted when estimated usage crosses configured threshold buckets.
-- Optional cadence-based updates can also be enabled every N rounds.
+- The estimate is emitted on every request (both loops, before each request),
+  so the web and the attached TUI get a fresh number each time.
+- The model's own `[CONTEXT: …]` line is still gated: it is left only on a rise
+  into a guidance bucket (from the second threshold up), never on a fall or a
+  cadence tick, and not again for a bucket a resumed session's line already
+  names.
 - This is warn-only behavior (no automatic history truncation).
 - When the model server reports real `usage` fields in the stream payload, the
   telemetry uses those actual token counts (prefixed `src=server`) instead of the
@@ -55,5 +59,4 @@ Configuration:
 - `SAMAGOTCHI_CONTEXT_STATUS` (`true` by default): set to `false` or `0` to disable telemetry.
 - `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` / `context.window_tokens`: context window size for when the server doesn't report one. chi asks llama.cpp for its real window first (`/props`, the per-slot `n_ctx`); this setting only fills in when it can't (mlx, oMLX, server down), and 256000 is the last resort.
 - `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN` (default `4.0`): heuristic ratio for char-to-token estimation.
-- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` (default `20,40,60,80`): comma-separated threshold percentages.
-- `SAMAGOTCHI_CONTEXT_STATUS_CADENCE` (default `0`): emit every N rounds in addition to threshold crossings.
+- `SAMAGOTCHI_CONTEXT_STATUS_THRESHOLDS` (default `20,40,60,80`): comma-separated threshold percentages. The buckets' guidance still gates the model's own `[CONTEXT: …]` line; nothing else reads `context.status_cadence` (it was removed once the event streamed on every request).

data/docs/internals/engine.md

@@ -212,6 +212,13 @@ One iteration with tool calls:
   than that line). The model (both loops), the event and the after_tool_call hook get that text.
 - Emits `:tool_call_completed` {iteration, call_count, call_index, tool, output, output_truncated, activity,
   images, diff, waited_ms, view}, then fires `:after_tool_call` {iteration, tool, output, status}.
+- The activity's status (`ToolActivity#tool_activity_status`): `error` for an `Error:` result and for an
+  execute that exited non-zero, except a grep-family search that found nothing (`ToolActivity.no_match?`:
+  exit 1, no stderr block, the last step is grep/egrep/fgrep/rg/ag/pgrep, no `&&` after a step that can fail
+  silently or sends output to /dev/null, no background `&`, no earlier exit/return or `set -e`; when unsure,
+  not a no-match). That one stays `ok` with `no_match: true` on the activity, which SessionMetrics keeps on the tool
+  record and the Bridge's TurnAccumulator on the part, for the web row's "no match" word. The model's text is
+  unchanged.
 
 A denied call gets denial text in place of its output; the rest of the batch still runs. After a hook's
 `stop_turn`, the gate denies every remaining call of the batch.
@@ -292,7 +299,7 @@ Turn events (the main ones; `Events` in `events.rb` keeps the shared sets):
 |---|---|---|
 | `:turn_started` | `prepare_turn` | `{session_id, prompt, turn_id, continue?, images?}` |
 | `:reminder_injected` | due reminders went into the turn | `{reminders}` |
-| `:context_status` | the window's fill crossed a bucket | `{iteration, ...}` |
+| `:context_status` | every request, the current estimate before it | `{iteration, ...}` |
 | `:generation_started` | a request begins | `{iteration, context_window_tokens, context_window_source}` (native adds `profile`, `profile_source`) |
 | `:generation_chunk` | each streamed chunk | `{iteration, content, text, thinking, payload, tool_call?}` |
 | `:generation_retrying` | the transport retries the request, or the chat loop asks again for a step whose stream dropped mid-answer (`restarted: true`: what the step streamed is void, and the web's live step, the TUI's activity line, the Bridge's TurnAccumulator and the stream hooks' watch start it over) | `{iteration, attempt, max_retries, next_delay, error_class, error_message, status, restarted?}` |
@@ -331,14 +338,14 @@ Engine initialization (in this order, among other things):
   @host_registry, @effective_model_name; @client = @host_registry.resolve(...).client
   @given_profile = profile or nil (resolved on first need, so building an Engine makes no network call)
   @guardrail_wiring, @question_desk
-  @hooks = load_hooks_from_config (config.yml hooks), then load_hooks_from_bundles
-  @tools = Tools::Builtins.registry; the bundles' plugins load (load_plugins)
-  @kernel = KernelLoop.new(client:, profile:, hooks:, reminder_store:, tools:)
+  @extension_load = ExtensionLoad.new; @hooks = @extension_load.hooks (config.yml's, then the bundles')
+  @tools = Tools::Builtins.registry; the bundles' plugins load (load_plugins → ExtensionLoad#load_plugins)
+  wire_kernel: @kernel = KernelLoop.new(client:, profile:, hooks:, reminder_store:, tools:)
   @kernel.guardrail_gate = @guardrail_wiring.gate; @kernel.warmup = PromptWarmup.new
   @hooks.runtime = hook_runtime
   @native_backend = LLM::NativeBackend.new(kernel: @kernel)
   @prompt_builder = SystemPrompt.new(...)
-  @session_observer with the metrics, the log subscriber and the thinking tails subscribed
+  @session_observer with the metrics, the log subscriber and the thinking tails subscribed (subscribe_session_observers)
 
 Model switching, Engine#switch_model!(model_name, persist_default:, typed:):
   → checks the host (ModelProfile.check_host!), sets @effective_model_name
@@ -430,8 +437,9 @@ Both loops:
   with its own nudge; when it is used up, the turn ends cancelled (`:hook`). A steer's cut asks again with the
   steer and spends nothing.
 - **Steering**: queued input goes in at iteration boundaries (`Steer.inject!`, `:pending_input_merged`).
-- **Context status**: an estimate of the window's fill before each request (`:context_status`), with a guidance
-  line on the tail when it rises far enough.
+- **Context status**: an estimate of the window's fill before each request,
+  emitted on every request (`:context_status`) so the UI always has a current
+  number, with a guidance line on the tail only when it rises far enough.
 - **Cancel**: text streamed before a cancel stays, marked `[interrupted]`.
 - **The same events**: generation events, tool dispatch and tool call events, and the before/after generation
   and tool call hooks.
@@ -476,6 +484,7 @@ Paths are under `lib/samagotchi/`.
 | `tools/registry.rb` | The tools a session offers: schemas, handlers, order |
 | `system_prompt.rb` | System prompt construction (stable part, volatile tail) |
 | `hooks/registry.rb` | Hook registry, fire order, `Hooks::Runtime` |
+| `extension_load.rb` | What an Engine loads at start: config.yml and bundle hooks, plugins, `bundles:` settings; events held while plugins load |
 | `guardrail_wiring.rb`, `guardrails/gate.rb` | The gate's context and approvals; the verdict per call |
 | `events.rb` | Event type sets shared by the Worker, the Bridge, the TUI and the web |
 | `cancellation_controller.rb` | A turn's cancel signal, and a generation's child controller |

data/docs/internals/tool-guardrails.md

@@ -2,7 +2,7 @@
 
 ## Read Tool Size Guardrails
 
-The `read` tool now applies adaptive limits to avoid accidental context exhaustion
+The `read` tool applies adaptive limits to avoid accidental context exhaustion
 when opening very large files (for example, VCR cassettes).
 
 Behavior:
@@ -11,7 +11,8 @@ Behavior:
 - Large files: return a head+tail preview plus truncation metadata.
 - Extremely large files: return an error indicating the hard size limit.
 
-Configuration:
+Configuration (each is also a config.yml key, `read.truncate_at_bytes` and so on, and a CLI
+flag such as `--read-truncate-at-bytes`; see docs/configuration.md):
 
 - `SAMAGOTCHI_READ_TRUNCATE_AT_BYTES` (default `65536`): files above this size return a preview instead of full content.
 - `SAMAGOTCHI_READ_PREVIEW_BYTES` (default `12288`): total preview budget split across head and tail.
@@ -23,8 +24,8 @@ Optional preview telemetry:
 
 Telemetry uses existing context estimation settings:
 
-- `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS`
-- `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN`
+- `SAMAGOTCHI_CONTEXT_WINDOW_TOKENS` (`context.window_tokens`)
+- `SAMAGOTCHI_CONTEXT_CHARS_PER_TOKEN` (`context.chars_per_token`)
 
 ## Execute Tool Output Guardrails
 
@@ -33,13 +34,14 @@ The `execute` tool applies the same guardrail model to command output:
 - Small stdout/stderr: returned in full.
 - Large stdout/stderr: returned as head+tail previews with truncation metadata.
 
-Configuration:
+Configuration (config.yml `execute.*` keys and CLI flags too, as for `read`):
 
 - `SAMAGOTCHI_EXECUTE_TRUNCATE_AT_BYTES` (default `65536`): output above this size is truncated.
 - `SAMAGOTCHI_EXECUTE_PREVIEW_BYTES` (default `12288`): total preview budget split across head and tail.
 - `SAMAGOTCHI_EXECUTE_TELEMETRY_THRESHOLD_PCT` (default `80`): include estimated output token impact only when threshold is crossed.
+- `SAMAGOTCHI_EXECUTE_TIMEOUT_SEC` (`execute.timeout_sec`, default `120`): a command running longer is stopped and answers `Error: command timed out after …s`.
 
 Implementation note:
 
-- Shared logic lives in `lib/samagotchi/tools/output_guardrails.rb` and is used by both `read` and `execute`.
+- Shared logic lives in `lib/samagotchi/tools/output_guardrails.rb` and is used by `read` and `execute`, and by `edit` (its env switches) and `delegate_wait` (the head+tail preview of a child's long reply).
 - Additional tools that can emit large payloads should rely on this shared helper for consistent behavior.

data/docs/plugins.md

@@ -1210,7 +1210,8 @@ A plain read keeps no version.
 **The nudge** (`nudge: true`). Some models, finding a skill's step broken,
 skip it and go on without fixing the skill. In a turn that read a skill
 (`memory_read` of a `skill_*` name, or `read` of its file), the first failing
-tool call after it (an `execute` that exited non-zero, a tool error) steers
+tool call after it (an `execute` that exited non-zero, except a grep-family
+search that found nothing, a tool error) steers
 the model once (a call a guardrail or the user denied doesn't count as a
 failed step): *"A step of skill release failed. Find out why before skipping
 it; if the skill is out of date, fix it now: edit the step that changed in

data/docs/releasing.md

@@ -79,9 +79,12 @@ The agent does each step and stops where the user has to say yes.
 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.
+   It doesn't run the suites again: it checks that the CI workflow succeeded
+   on the tagged commit as a push to main (waiting while that run is still
+   going, stopping if it failed or never ran) and runs the full
+   `bundles:check`. Then 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)

data/docs/sessions.md

@@ -204,7 +204,7 @@ A session can **continue** an earlier one: "the next day of the same routine" (a
 - **The carry note:** the new link starts with a context note from `session chain` (shown in its transcript as `note from session chain`), queued before its worker spawns, so its first turn sees it: `This session continues 3fa2c1d0 (2026-10-08), the previous link of its chain. Its recap, as of 2026-10-08 18:02:` and the previous link's recap (`recap.json`; cut at 8000 characters). No recap (fewer user turns than a recap needs, recaps off, none written in time): `… It left no recap.` Never more than the recap: no transcript. An idle new link holding only the note is kept, not discarded as empty.
 - **The recap first:** a previous link with a live worker is asked for a recap (the Bridge's `POST /recap`) and given up to 30 s to write it; one with none wrote its recap when its worker left.
 - **The previous link is archived** before the new one starts, by the archive's own rules (see *Archiving a session*): a turn running, a prompt queued or the step-limit question refuse it, a live idle worker is stopped, a plain REPL's session is refused. Its finished delegates are archived with it, as any archive does.
-- **Its open delegates move to the new link** instead: each direct delegate that is running, waiting for an answer, has a live worker or a reply its parent wasn't given, or has such a delegate below it (checked again after the recap wait, so one delegated meanwhile moves too). It moves with its own delegates, stays unarchived, and from then on is the new link's: its card folds under the new link, its reports ring the new link (an idle one runs a wake turn for them, as for its own delegates), `delegate_result` and the `⑂` chip count it there, and what its parent was already told (`delegates.json`) and any report still waiting come along, so nothing is reported twice. A moved delegate gets a context note from `session chain`, `Your parent session is now 4b7e9a01 (…), the next link of its session chain: …`, as its system prompt keeps naming the parent it started with. The move writes `<child>/parent.json` (`{parent_id, from, at}`) beside the child's session file, never the file itself, so a live child worker saving its own copy changes nothing; every reader applies it (a later move overwrites it; it is never removed). A continue is **refused for an open delegate that can't move** (`ContinueRefused`, naming it): one whose live worker runs an older chi (`older chi worker 0.46.1; restart it`: `chi sessions restart <id>`, or stop it) or that is open in a chi REPL (close it there). An older `chi web` or CLI still running shows a moved delegate under the archived link until it is restarted.
+- **Its open delegates move to the new link** instead: each direct delegate that is running, waiting for an answer, has a live worker or a reply its parent wasn't given, or has such a delegate below it (checked again after the recap wait, so one delegated meanwhile moves too). It moves with its own delegates, stays unarchived, and from then on is the new link's: its card folds under the new link, its reports ring the new link (an idle one runs a wake turn for them, as for its own delegates), `delegate_result` and the `⑂` chip count it there, and what its parent was already told (`delegates.json`) and any report still waiting come along, so nothing is reported twice. A moved delegate gets a context note from `session chain`, `Your parent session is now 4b7e9a01 (…), the next link of its session chain: …`, as its system prompt keeps naming the parent it started with. The move writes `<child>/parent.json` (`{parent_id, from, at}`) beside the child's session file, never the file itself, so a live child worker saving its own copy changes nothing; every reader applies it (a later move overwrites it; it is never removed). A continue is **refused for an open delegate that can't move** (`SessionContinue::Refused`, naming it): one whose live worker runs an older chi (`older chi worker 0.46.1; restart it`: `chi sessions restart <id>`, or stop it) or that is open in a chi REPL (close it there). An older `chi web` or CLI still running shows a moved delegate under the archived link until it is restarted.
 - **If the continue fails part-way:** a new link that fails to start gives its moved delegates back before it is deleted (each gets a note saying so; its worker is stopped first, if one started, and a worker that won't stop is reported, the link left), with any report one of them rang it with meanwhile; the previous link, back in the lists, is woken for reports waiting. A continue that dies in the middle leaves a `move.json` in the new link's folder: the new link's next worker finishes that move (only the delegates it names, and without a second note to one already told) as it starts. Until the new link's own worker holds it, a ring from a moved delegate doesn't start another (a `starting` marker in its folder, which that worker removes; a stale one, over 60 s old or from a process that is gone, is ignored). An open delegate below an archived delegate refuses the continue (`under archived …`): unarchive that one, or archive this one.
 - **Refused too:** a link that is continued already (naming the link that continues it; continue that one, or `last:<id>`), a previous link whose folder is gone, and one whose model names a host config.yml no longer has. A refusal starts nothing and archives nothing; a new link that fails to start puts back what was archived. Every refusal that can be known up front (the archive's ones included) comes before the recap wait. One continue of a session runs at a time (a lock in its folder; other chains don't wait), so a double click finds the first one's link and is refused, while a `last:<id>` continue that waited follows the chain to its new end.
 - **Web:** `POST /api/sessions` takes `continues: "<id, prefix or last:id>"`, with `idle: true` (a new link waiting for its first message, previewed by the previous link's, or `preview`) or a `prompt`, and not `dir`, `model` or `llm_context` (400 `invalid_continues`: the previous link's are taken). 201 is the new session's summary, `continues` set, with `moved`: the ids of the delegates that moved to it (`[]` for none); 404 `not_found`; 400 `ambiguous_id` for a prefix of several sessions, `invalid_model` for a model whose host is gone; 409 `continued` with `next_id` (the link that continues it already, which the page opens instead), `open_children` with `ids` (open delegates that can't move), `folder_gone`, `busy`, `scratch` or `owned_by_tui`. Every session summary carries `continues`.

data/docs/testing.md

@@ -15,9 +15,11 @@ bug) or a broken spec: fix it, or disable that line with the reason (`# rubocop:
 No spec reads your own setup. The suite points `XDG_CONFIG_HOME` and `XDG_STATE_HOME` at temp folders,
 clears your `SAMAGOTCHI_*` environment, and keeps every spec off the network (WebMock).
 
-The web specs run in plain node. One that renders with lit-html (`turn_view.js`, `vendor/lit-html.js`) needs a DOM:
-`import "./dom_shim.js";` as its first import (happy-dom, a devDependency only, never shipped; about 0.3 s per spec
-file that loads it). The shim's `htmlOf(nodes)` and `canon(html)` compare markup without lit's marker comments.
+The web specs run in plain node. One that renders with lit-html (`turn_view.js`, `thinking_chip.js`,
+`vendor/lit-html.js`) needs a DOM: `import "./dom_shim.js";` as its first import (happy-dom, a devDependency only,
+never shipped; about 0.3 s per spec file that loads it). The shim's `htmlOf(nodes)` and `canon(html)` compare markup
+without lit's marker comments. happy-dom 20 picks the wrong option of a `<select>` whose options lit inserted with
+`?selected`: read the option marked `selected` (`option[selected]`), not `select.value`; the browser follows the mark.
 
 ## Worktrees
 

data/lib/samagotchi/analytics_file.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Samagotchi
+  # A session's analytics.json: the SessionMetrics snapshot with every turn
+  # and tool record, saved next to the session file (<session dir>/
+  # analytics.json). SessionMetrics#persist writes it; the session lists,
+  # `chi sessions stats`, the web's timing and a collector loading an earlier
+  # process's records read it. The records stay string-keyed hashes as
+  # saved: their keys grow over versions and every reader treats each one
+  # as optional.
+  module AnalyticsFile
+    NAME = "analytics.json"
+
+    module_function
+
+    # @param session_dir [String]
+    # @return [String]
+    def path(session_dir)
+      File.join(session_dir, NAME)
+    end
+
+    # The parsed file, string-keyed; nil when it is missing, unreadable,
+    # not JSON or not an object (an older or broken file reads as none).
+    # @param session_dir [String]
+    # @return [Hash, nil]
+    def read(session_dir)
+      data = JSON.parse(File.read(path(session_dir)))
+      data.is_a?(Hash) ? data : nil
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+  end
+end

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -169,6 +169,7 @@ module Samagotchi
 
         activity = { tool: part[:tool], status: part[:status], params: part[:params], **title }
         activity[:action] = part[:action] if part[:action]
+        activity[:no_match] = true if part[:no_match]
         completed = { type: :tool_call_completed, **call, output: part[:output], output_truncated: !!part[:output_truncated],
                       activity: activity }
         completed[:duration_ms] = part[:duration_ms] unless part[:duration_ms].nil?
@@ -288,6 +289,7 @@ module Samagotchi
           output = event[:output].to_s
           capped = output.length > @max_output_chars
           tool[:status] = (event.dig(:activity, :status) || "ok").to_s
+          tool[:no_match] = true if event.dig(:activity, :no_match)
           tool[:output] = capped ? output[0, @max_output_chars] : output.dup
           tool[:output_truncated] = capped || !!event[:output_truncated]
           tool[:images] = event[:images] if event[:images]

data/lib/samagotchi/bundle_command.rb

@@ -293,8 +293,8 @@ module Samagotchi
         @stderr.puts "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
         return CLI::Exit::USAGE
       end
-      data = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).read
-      return uninstall_profile(bundle_name, force: force) if Samagotchi::MemoryBundle::Profile.installed_meta?(bundle_name, data)
+      record = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).record
+      return uninstall_profile(bundle_name, force: force) if Samagotchi::MemoryBundle::Profile.installed_meta?(bundle_name, record)
 
       uninstaller = Samagotchi::MemoryBundle::Uninstaller.new(name: bundle_name, scope: scope, force: force)
       begin
@@ -370,7 +370,7 @@ module Samagotchi
           @stdout.puts "Bundle '#{name}' not installed."
           return 0
         end
-        @stdout.puts "Bundle: #{name} v#{st[:provenance][:version]} scope=#{status_scope(st)} installed=#{st[:provenance][:installed_at]}"
+        @stdout.puts "Bundle: #{name} v#{st[:provenance].version} scope=#{status_scope(st)} installed=#{st[:provenance].installed_at}"
         if st[:scope_error]
           @stdout.puts "Target: (unknown scope: this chi can't resolve it; upgrade chi or reinstall the bundle)"
         else
@@ -380,7 +380,7 @@ module Samagotchi
           next @stdout.puts("  #{k}: unchecked") if info[:unchecked]
 
           mods = []
-          mods << "conflict (kept your edits over v#{st[:provenance][:version]}: chi bundle diff #{name} #{k})" if info[:conflict]
+          mods << "conflict (kept your edits over v#{st[:provenance].version}: chi bundle diff #{name} #{k})" if info[:conflict]
           mods << "modified" if info[:modified]
           mods << "missing" if info[:missing]
           mods << "no-index" unless info[:index_present] || info[:overlay]
@@ -389,23 +389,19 @@ module Samagotchi
           @stdout.puts "  #{k}: #{label}"
         end
         # Hooks
-        hooks = st[:provenance][:hooks] || {}
-        trust = st[:provenance][:trust_level] || "experimental"
-        commit = st[:provenance][:source_commit]
+        hooks = st[:provenance].hooks
+        trust = st[:provenance].trust_level || "experimental"
+        commit = st[:provenance].source_commit
         @stdout.puts "  trust_level: #{trust}" if hooks.any? || trust
         @stdout.puts "  source_commit: #{commit}" if commit
         if hooks.any?
           @stdout.puts "  Hooks (#{hooks.size}):"
-          hooks.each do |hk, meta|
-            m = meta.is_a?(Hash) ? meta.transform_keys(&:to_s) : {}
-            event = m["event"] || ""
-            on_error = m["on_error"] || "skip"
-            prio = m["priority"] || 100
-            hook_path = File.join(Samagotchi::MemoryBundle::Provenance.new(name: name).hooks_dir, hk.to_s)
+          hooks.each do |hk, hook|
+            hook_path = File.join(Samagotchi::MemoryBundle::Provenance.new(name: name).hooks_dir, hk)
             exists = File.exist?(hook_path) ? "ok" : "missing"
-            @stdout.puts "    #{hk}: event=#{event} on_error=#{on_error} priority=#{prio} [#{exists}]"
+            @stdout.puts "    #{hk}: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
           end
-          @stdout.puts "    requires_chi: #{st[:provenance][:requires_chi]}" if st[:hooks_requires_failure]
+          @stdout.puts "    requires_chi: #{st[:provenance].requires_chi}" if st[:hooks_requires_failure]
           @stdout.puts "    not loaded: #{st[:hooks_requires_failure]}" if st[:hooks_requires_failure]
         end
         if (plugin = st[:plugin])
@@ -415,28 +411,28 @@ module Samagotchi
           @stdout.puts "    not loaded: #{plugin[:requires_failure]}" if plugin[:requires_failure]
         end
         st[:needs].each { |need| @stdout.puts "  #{Samagotchi::MemoryBundle::Status.need_line(need)}" }
-        (st[:provenance][:includes] || []).each do |member|
-          state = Samagotchi::MemoryBundle::Provenance.new(name: member.to_s).installed? ? "installed" : "not installed: chi bundle install #{member}"
+        (st[:provenance].includes || []).each do |member|
+          state = Samagotchi::MemoryBundle::Provenance.new(name: member).installed? ? "installed" : "not installed: chi bundle install #{member}"
           @stdout.puts "  includes #{member} [#{state}]"
         end
       else
         bundles = Samagotchi::MemoryBundle::Provenance.each_installed.to_a
         @stdout.puts "No installed bundles." if bundles.empty?
-        bundles.each do |bname, data|
-          next @stdout.puts("  #{bname} (manifest.json unreadable)") if data[:error]
+        bundles.each do |bname, record|
+          next @stdout.puts("  #{bname} (manifest.json unreadable)") if record.error?
 
           st = Samagotchi::MemoryBundle::Status.bundle_status(bname)
           mods = st[:files].values.count { |v| v[:modified] || v[:missing] }
-          hooks_count = (st[:provenance][:hooks] || {}).size
+          hooks_count = st[:provenance].hooks.size
           hook_info = hooks_count > 0 ? " hooks=#{hooks_count}" : ""
           plugin = st[:plugin]
           mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
           mods += 1 if st[:hooks_requires_failure]
           mods += 1 if st[:scope_error]
           plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
-          includes = st[:provenance][:includes]
+          includes = st[:provenance].includes
           includes_info = includes ? " includes=#{includes.join(",")}" : ""
-          @stdout.puts "  #{bname} v#{st[:provenance][:version]} scope=#{status_scope(st)} files=#{st[:files].size}#{hook_info}#{plugin_info}#{includes_info} issues=#{mods}"
+          @stdout.puts "  #{bname} v#{st[:provenance].version} scope=#{status_scope(st)} files=#{st[:files].size}#{hook_info}#{plugin_info}#{includes_info} issues=#{mods}"
         end
       end
       0
@@ -453,19 +449,19 @@ module Samagotchi
         @stderr.puts "Usage: chi bundle diff <bundle> [file]"; return CLI::Exit::USAGE
       end
       prov = Samagotchi::MemoryBundle::Provenance.new(name: bname)
-      data = prov.read
-      unless data
+      record = prov.record
+      unless record
         @stderr.puts "Bundle '#{bname}' not installed"; return 1
       end
-      scope = data[:scope]&.to_s || "system"
+      scope = record.effective_scope
       begin
         target_dir = Samagotchi::MemoryPaths.scope_dir!(scope)
       rescue ArgumentError => e
         @stderr.puts "Bundle '#{bname}': #{e.message}"; return 1
       end
-      files = data[:files] || {}
-      hooks = data[:hooks] || {}
-      plugin_path = prov.plugin_path(data)
+      files = record.files
+      hooks = record.hooks
+      plugin_path = prov.plugin_path(record)
       plugin_file = plugin_path && File.basename(plugin_path)
       show_plugin = lambda do
         @stdout.puts "=== plugin/#{plugin_file} ==="
@@ -474,11 +470,11 @@ module Samagotchi
         @stdout.puts File.exist?(base) ? File.read(base) : "(no base)"
         @stdout.puts "--- current (on-disk) ---"
         @stdout.puts File.exist?(plugin_path) ? File.read(plugin_path) : "(missing)"
-        @stdout.puts "--- metadata: sha256=#{data[:plugin][:sha256]}#{" requires_chi=#{data[:requires_chi]}" if data[:requires_chi]}"
+        @stdout.puts "--- metadata: sha256=#{record.plugin.sha256}#{" requires_chi=#{record.requires_chi}" if record.requires_chi}"
       end
       if file_arg
         # Try file first, then hook
-        if files.key?(file_arg.to_sym) || files.key?(file_arg)
+        if record.owns?(file_arg)
           base = prov.base_path(file_arg)
           cur = File.join(target_dir, file_arg)
           @stdout.puts "=== #{file_arg} ==="
@@ -486,7 +482,7 @@ module Samagotchi
           @stdout.puts File.exist?(base) ? File.read(base) : "(no base)"
           @stdout.puts "--- current (on-disk) ---"
           @stdout.puts File.exist?(cur) ? File.read(cur) : "(missing)"
-        elsif hooks.key?(file_arg.to_sym) || hooks.key?(file_arg)
+        elsif hooks.key?(file_arg)
           base = prov.base_path(file_arg)
           cur = File.join(prov.hooks_dir, file_arg)
           @stdout.puts "=== hooks/#{file_arg} ==="
@@ -495,11 +491,7 @@ module Samagotchi
           @stdout.puts "--- current (on-disk) ---"
           @stdout.puts File.exist?(cur) ? File.read(cur) : "(missing)"
           # Show hook metadata
-          meta = hooks[file_arg.to_sym] || hooks[file_arg]
-          if meta
-            m = meta.transform_keys(&:to_s)
-            @stdout.puts "--- metadata: event=#{m["event"]} on_error=#{m["on_error"]} priority=#{m["priority"]} sha256=#{m["sha256"]}"
-          end
+          @stdout.puts hook_metadata_line(hooks[file_arg])
         elsif plugin_file && [plugin_file, "plugin/#{plugin_file}"].include?(file_arg)
           show_plugin.call
         else
@@ -508,8 +500,7 @@ module Samagotchi
         end
         @stdout.puts ""
       else
-        keys = files.keys.map(&:to_s)
-        keys.each do |k|
+        files.each_key do |k|
           base = prov.base_path(k)
           cur = File.join(target_dir, k)
           @stdout.puts "=== #{k} ==="
@@ -520,7 +511,7 @@ module Samagotchi
           @stdout.puts ""
         end
         # Hooks diff
-        hooks.keys.map(&:to_s).each do |k|
+        hooks.each do |k, hook|
           base = prov.base_path(k)
           cur = File.join(prov.hooks_dir, k)
           @stdout.puts "=== hooks/#{k} ==="
@@ -528,11 +519,7 @@ module Samagotchi
           @stdout.puts File.exist?(base) ? File.read(base) : "(no base)"
           @stdout.puts "--- current (on-disk) ---"
           @stdout.puts File.exist?(cur) ? File.read(cur) : "(missing)"
-          meta = hooks[k.to_sym] || hooks[k]
-          if meta
-            m = meta.transform_keys(&:to_s)
-            @stdout.puts "--- metadata: event=#{m["event"]} on_error=#{m["on_error"]} priority=#{m["priority"]} sha256=#{m["sha256"]}"
-          end
+          @stdout.puts hook_metadata_line(hook)
           @stdout.puts ""
         end
         if plugin_file
@@ -586,6 +573,10 @@ module Samagotchi
       "includes=#{here.join(",")}#{"  left out=#{gone.join(",")}" unless gone.empty?}"
     end
 
+    def hook_metadata_line(hook)
+      "--- metadata: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} sha256=#{hook.sha256}"
+    end
+
     def build(rest)
       parsed = parse_flags(BUILD_FLAGS, rest, "build", help: BUILD_HELP)
       return parsed if parsed.is_a?(Integer)

data/lib/samagotchi/bundle_needs.rb

@@ -65,19 +65,18 @@ module Samagotchi
     # entry name → marker, for the installed bundles of +scope+ with a
     # missing need. A manifest.json or needs: that doesn't parse is skipped.
     def self.entry_markers(scope, path:, bundles_dir:)
-      MemoryBundle::Provenance.each_installed(dir: bundles_dir).each_with_object({}) do |(_name, data), acc|
-        next if data[:error] || data[:scope].to_s != scope.to_s
-        next unless data[:needs].is_a?(Array) && !data[:needs].empty?
+      MemoryBundle::Provenance.each_installed(dir: bundles_dir).each_with_object({}) do |(_name, bundle), acc|
+        next if bundle.error? || bundle.effective_scope != scope.to_s || !bundle.needs?
 
         needs = begin
-          MemoryBundle::Manifest.parse_needs(data[:needs])
+          MemoryBundle::Manifest.parse_needs(bundle.needs)
         rescue MemoryBundle::Manifest::ValidationError
           next
         end
         marker = marker(missing(needs, path: path))
         next unless marker
 
-        (data[:files].is_a?(Hash) ? data[:files].keys : []).each do |key|
+        bundle.files.each_key do |key|
           name = MutedMemories.normalize(key)
           acc[name] ||= marker if name
         end

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

@@ -1,10 +1,10 @@
 ---
 name: skills
-version: 0.1.6
+version: 0.1.7
 scope: system
 description: "Skills (skill_<name> memories, the steps of a task done together): /skill save, list, show and diff; older versions kept with a short diff line on every update; a nudge when a followed skill's step fails"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:16aefdff7d7702a5feb9b2bafb9d975ceaa47f2864ad40f6df3624f4ba714136
+  sha256: sha256:42f535eb1dd616bdf2e027031538c9419767c531e2b52e2baa8f1cc83accaba7
 requires_chi: ">= 0.11.0"

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

@@ -25,7 +25,8 @@
 # fixing the skill: in a turn that read a skill (memory_read of a skill_*
 # name, or a read of its file), the first failing tool call after it (an
 # execute with "exit: N", N ≠ 0, or with no exit line an Error: line near
-# the top; any tool's "[tool] Error: …") steers the model once to find out
+# the top; any tool's "[tool] Error: …"; not a grep that found nothing,
+# which core counts ok) steers the model once to find out
 # why and fix the skill, unless a skill read was changed already (by any
 # tool, see above). A call a guardrail or the user denied (its first line
 # "[tool] Error: blocked by guardrail: …", "… denied by guardrail (…): …" or

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -18,7 +18,7 @@ Single registry `Samagotchi::Config` (`Config::ENTRIES` in `lib/samagotchi/confi
 
 Sections forbid `_`/`-` (`SECTION_RE` `/\A[a-z0-9]+\z/`); leaves keep `snake_case` in YAML (`base_url`) and become kebab in CLI (`base-url`) via registry derivation — no generic string split, registry lookup avoids flat vs nested collision.
 
-**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line`, `context.status/window_tokens/chars_per_token/status_thresholds/status_cadence`, `memory.index_warn_tokens`, `thinking.turn_preamble`, `default.max_tokens`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
+**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/transport/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line`, `context.status/window_tokens/chars_per_token/status_thresholds`, `memory.index_warn_tokens`, `thinking.turn_preamble`, `default.max_tokens`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
 
 Example `config.yml` (new nested form, preferred):
 

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.52.0
+version: 0.54.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:dfc19266259a9af1e0d769b7e0f67996b740b0c9921fdf3dadad973f6e5c144a
-  config_modification_protocol.md: sha256:a7a6352c03979db69d98955bee8f36eb468a6cf68904d418b7f3ddb788c83e7b
+  config_modification_protocol.md: sha256:45064ac6b19863e1646d15891d0e9cc7a8f10ab981a0d25d6e13891591538b8a
   memory_guide.md: sha256:15cd3b24eda853cc458371c6c75809a2d4b5352311d075aaa4384926b5221c27
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

data/lib/samagotchi/child_move.rb

@@ -14,6 +14,8 @@ module Samagotchi
   # Loaded on first use: session_manager requires terminal_ui, which
   # requires KernelLoop and so the tools (a require cycle otherwise).
   autoload :SessionManager, File.expand_path("session_manager", __dir__)
+  # SessionContinue::OpenChild, the rows a plan refuses: loaded on first use too.
+  autoload :SessionContinue, File.expand_path("session_continue", __dir__)
 
   # A continue moving the previous link's open delegates to the chain's new
   # link (SessionManager.continue_session), instead of archiving them with
@@ -45,7 +47,7 @@ module Samagotchi
     # What a continue does with the previous link's children: +move+ the
     # direct children whose subtree has an open node (they go to the new
     # link, their subtrees with them), +refuse+ the open ones it can't move
-    # (SessionManager::OpenChild, why: an older chi worker or a chi REPL).
+    # (SessionContinue::OpenChild, why: an older chi worker or a chi REPL).
     Plan = Data.define(:move, :refuse)
     # A move under way: from the session, the children moved, and those
     # already sent their note (so a move finished again notes no one twice).
@@ -55,8 +57,8 @@ module Samagotchi
 
     module_function
 
-    # @param open [Array<SessionManager::OpenChild>] the previous link's open
-    #   nodes, at any depth (SessionManager.open_children)
+    # @param open [Array<SessionContinue::OpenChild>] the previous link's open
+    #   nodes, at any depth (SessionContinue.open_children)
     # @return [Plan]
     def plan(prev_id, open:, state_dir:)
       open_ids = open.map(&:id)
@@ -77,7 +79,7 @@ module Samagotchi
 
         why = unmovable(row[:id], state_dir: state_dir)
         if why
-          refuse << SessionManager::OpenChild.new(id: row[:id], short_id: row[:id][0, 8], why: why)
+          refuse << SessionContinue::OpenChild.new(id: row[:id], short_id: row[:id][0, 8], why: why)
         else
           move << row[:id]
         end

data/lib/samagotchi/config.rb

@@ -156,7 +156,6 @@ module Samagotchi
       # (MemoryBundle::IndexSize); 0: no note. `memory:` is its own section, not the `memories:` preload list.
       Entry.new(key: "memory.index_warn_tokens", yaml_path: %w[memory index_warn_tokens], type: :integer, default: 2500,            expose: %i[env config cli]),
       Entry.new(key: "context.status_thresholds", yaml_path: %w[context status_thresholds], type: :string, default: "20,40,60,80",    expose: %i[env config cli]),
-      Entry.new(key: "context.status_cadence",   yaml_path: %w[context status_cadence],   type: :integer, default: 0,               expose: %i[env config cli]),
       # Attached context (ContextSources): how often a source's command runs when it names no --every (seconds; less
       # than 30 counts as 30).
       Entry.new(key: "context.every_seconds",    yaml_path: %w[context every_seconds],    type: :integer, default: 300,             expose: %i[env config]),

data/lib/samagotchi/context_command.rb

@@ -22,7 +22,7 @@ module Samagotchi
     USAGE = <<~TEXT
       Usage: chi context <add|push|ls|show|refresh|rm|mute|unmute> [options] [TARGET]
         add NAME (--cmd CMD | --push) [--every SECONDS] [--why TEXT] [--hint TEXT] TARGET
-        add URL [--why TEXT] TARGET         a URL an installed bundle's provider knows (github-pr: a PR)
+        add URL [--why TEXT] [--hint TEXT] TARGET   a URL an installed bundle's provider knows (github-pr: a PR)
               a source: CMD prints its text (plain, or JSON {"text", "summary", "wake", "hint"});
               --push: text comes from chi context push. --every: how often CMD runs
               (seconds, at least 30; default context.every_seconds). --why: why it's attached;