samagotchi 0.142.0 → 0.143.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +66 -7
  3. data/README.md +1 -0
  4. data/docs/architecture.md +13 -6
  5. data/docs/bundle-authoring.md +6 -6
  6. data/docs/bundles.md +1232 -0
  7. data/docs/cli.md +36 -6
  8. data/docs/configuration.md +11 -12
  9. data/docs/context.md +10 -10
  10. data/docs/guardrails.md +7 -9
  11. data/docs/hooks.md +19 -2
  12. data/docs/internals/attached-context.md +2 -3
  13. data/docs/internals/bundles.md +5 -3
  14. data/docs/internals/engine.md +9 -3
  15. data/docs/internals/prompt-caching.md +12 -12
  16. data/docs/internals/web-push.md +1 -1
  17. data/docs/memory.md +2 -2
  18. data/docs/plugins.md +26 -1251
  19. data/docs/sessions.md +2 -2
  20. data/docs/sub-agent.md +6 -6
  21. data/docs/system-one.md +2 -2
  22. data/lib/samagotchi/bundle_command/api_calls.rb +132 -0
  23. data/lib/samagotchi/bundle_command/check.rb +50 -34
  24. data/lib/samagotchi/bundle_command/installed_check.rb +86 -0
  25. data/lib/samagotchi/bundle_command/scaffold.rb +1 -0
  26. data/lib/samagotchi/bundle_settings_check.rb +58 -0
  27. data/lib/samagotchi/bundles/agents-md/manifest.yml +4 -2
  28. data/lib/samagotchi/bundles/agents-md/plugin.rb +1 -1
  29. data/lib/samagotchi/bundles/btw/manifest.yml +4 -2
  30. data/lib/samagotchi/bundles/btw/plugin.rb +1 -1
  31. data/lib/samagotchi/bundles/check-in/manifest.yml +7 -6
  32. data/lib/samagotchi/bundles/check-in/plugin.rb +7 -14
  33. data/lib/samagotchi/bundles/claude-peer/manifest.yml +3 -3
  34. data/lib/samagotchi/bundles/claude-peer/plugin.rb +1 -1
  35. data/lib/samagotchi/bundles/claude-peer/scripts/pair +1 -1
  36. data/lib/samagotchi/bundles/codex-peer/manifest.yml +2 -2
  37. data/lib/samagotchi/bundles/codex-peer/plugin.rb +1 -1
  38. data/lib/samagotchi/bundles/coordinator/manifest.yml +2 -2
  39. data/lib/samagotchi/bundles/coordinator/plugin.rb +1 -1
  40. data/lib/samagotchi/bundles/core/manifest.yml +2 -2
  41. data/lib/samagotchi/bundles/cost-cap/manifest.yml +6 -3
  42. data/lib/samagotchi/bundles/cost-cap/plugin.rb +5 -7
  43. data/lib/samagotchi/bundles/github-pr/manifest.yml +3 -1
  44. data/lib/samagotchi/bundles/known-names/manifest.yml +3 -1
  45. data/lib/samagotchi/bundles/loop-guard/manifest.yml +4 -2
  46. data/lib/samagotchi/bundles/loop-guard/plugin.rb +1 -1
  47. data/lib/samagotchi/bundles/mcp/manifest.yml +4 -2
  48. data/lib/samagotchi/bundles/mcp/plugin.rb +2 -2
  49. data/lib/samagotchi/bundles/ruby/manifest.yml +2 -2
  50. data/lib/samagotchi/bundles/ruby/plugin.rb +1 -1
  51. data/lib/samagotchi/bundles/skills/manifest.yml +4 -2
  52. data/lib/samagotchi/bundles/skills/plugin.rb +1 -1
  53. data/lib/samagotchi/bundles/slow-commands/manifest.yml +4 -2
  54. data/lib/samagotchi/bundles/slow-commands/plugin.rb +1 -1
  55. data/lib/samagotchi/bundles/source-links/manifest.yml +3 -1
  56. data/lib/samagotchi/bundles/system/config_modification_protocol.md +1 -1
  57. data/lib/samagotchi/bundles/system/manifest.yml +3 -3
  58. data/lib/samagotchi/bundles/system/self_map.md +2 -2
  59. data/lib/samagotchi/bundles/work-cap/manifest.yml +6 -3
  60. data/lib/samagotchi/bundles/work-cap/plugin.rb +11 -13
  61. data/lib/samagotchi/context_candidate_choice.rb +12 -3
  62. data/lib/samagotchi/context_candidates.rb +4 -1
  63. data/lib/samagotchi/context_candidates_log.rb +11 -0
  64. data/lib/samagotchi/context_status.rb +1 -2
  65. data/lib/samagotchi/engine.rb +33 -68
  66. data/lib/samagotchi/extension_load.rb +8 -2
  67. data/lib/samagotchi/hook_routes.rb +37 -2
  68. data/lib/samagotchi/hooks/bundle_loader.rb +20 -4
  69. data/lib/samagotchi/hooks/registry.rb +23 -5
  70. data/lib/samagotchi/host_model.rb +3 -3
  71. data/lib/samagotchi/host_registry.rb +14 -7
  72. data/lib/samagotchi/kernel_loop.rb +7 -2
  73. data/lib/samagotchi/llm/chat_loop.rb +5 -0
  74. data/lib/samagotchi/llm/stray_tool_call.rb +23 -16
  75. data/lib/samagotchi/memory_bundle/builder.rb +4 -2
  76. data/lib/samagotchi/memory_bundle/installed_bundle.rb +9 -2
  77. data/lib/samagotchi/memory_bundle/installed_copy.rb +92 -0
  78. data/lib/samagotchi/memory_bundle/installer.rb +2 -0
  79. data/lib/samagotchi/memory_bundle/manifest.rb +23 -13
  80. data/lib/samagotchi/memory_bundle/provenance.rb +4 -1
  81. data/lib/samagotchi/memory_bundle/shipped_update.rb +13 -1
  82. data/lib/samagotchi/model_catalog.rb +3 -2
  83. data/lib/samagotchi/models_command.rb +1 -1
  84. data/lib/samagotchi/plugin/api.rb +14 -11
  85. data/lib/samagotchi/plugin/context.rb +10 -0
  86. data/lib/samagotchi/plugin/loader.rb +4 -2
  87. data/lib/samagotchi/plugin/peer.rb +17 -22
  88. data/lib/samagotchi/plugin_session_state.rb +32 -5
  89. data/lib/samagotchi/prompt_warmup.rb +1 -9
  90. data/lib/samagotchi/session_access/local.rb +1 -1
  91. data/lib/samagotchi/session_access/remote.rb +3 -3
  92. data/lib/samagotchi/session_archive_command.rb +3 -3
  93. data/lib/samagotchi/session_commands.rb +4 -4
  94. data/lib/samagotchi/session_config.rb +9 -3
  95. data/lib/samagotchi/session_continue.rb +1 -1
  96. data/lib/samagotchi/session_manager.rb +15 -6
  97. data/lib/samagotchi/system_one/judgments.rb +8 -25
  98. data/lib/samagotchi/system_one/log.rb +21 -0
  99. data/lib/samagotchi/system_one/recording.rb +1 -1
  100. data/lib/samagotchi/terminal_ui/attach_link.rb +2 -2
  101. data/lib/samagotchi/terminal_ui/attached_loop/exit_commands.rb +1 -1
  102. data/lib/samagotchi/terminal_ui/attached_loop.rb +1 -1
  103. data/lib/samagotchi/terminal_ui/local_link.rb +1 -1
  104. data/lib/samagotchi/terminal_ui/remote_link.rb +1 -2
  105. data/lib/samagotchi/testing/judgments.rb +0 -9
  106. data/lib/samagotchi/update_command.rb +49 -16
  107. data/lib/samagotchi/version.rb +1 -1
  108. data/lib/samagotchi/web/app.rb +1 -0
  109. data/lib/samagotchi/web/auto_update.rb +79 -49
  110. data/lib/samagotchi/web/auto_update_record.rb +59 -0
  111. data/lib/samagotchi/web/public/app.js +8 -4
  112. data/lib/samagotchi/web/public/hash_intent.js +24 -0
  113. data/lib/samagotchi/web/public/index.html +3 -1
  114. data/lib/samagotchi/web/public/revise_stack.js +14 -5
  115. data/lib/samagotchi/web/session_control.rb +3 -3
  116. data/lib/samagotchi/web/update_check.rb +7 -6
  117. data/lib/samagotchi/web/update_ops.rb +80 -25
  118. metadata +8 -1
data/docs/cli.md CHANGED
@@ -34,9 +34,9 @@
34
34
  - `chi desktop install|upgrade|uninstall|status` — the macOS "Send to chi" helper: a Service and a ⌃⌥⌘N hotkey that send text or images to a session (live, stopped or new) as a message (⏎, a turn runs) or a context note (⌘⏎) (see [Desktop helper](desktop.md))
35
35
  - `chi models [--format text|json] [--timeout S] [TEXT]` — list the models every configured host offers, as the names `--model` takes (see [Listing the models](#listing-the-models))
36
36
  - `chi self` — print version, source dir (checkout or installed gem), config/memory/session paths, model/host and bundles. Run by a session's `execute`, the `model` row (and host, loop, profile, thinking, served model) is **that session's** model, labelled `(this session <id8>; default …)`; elsewhere it is the default, `(default)`. `model key` is the memory overlay key (`<name>.<key>.md`), and `big memories` the memories over `memory.entry_warn_tokens` ([Memory](memory.md#a-memorys-size)), and `model notes` the model notes a prompt of that model loads (`model_notes_deepseek (system, 612 chars)`, `none`; inside a session its `--mute` list is left out). `chi self --model` prints only the model a new session starts on, an alias resolved to its target (the desktop helper's hint)
37
- - `chi update [--dry-run] [--to VERSION] [--json] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, in one table (see [Updating](#updating))
37
+ - `chi update [--dry-run] [--to VERSION] [--json] [--no-gem] [--no-bundles] [--no-desktop]` — update an installed chi: the gem, the system bundle, the shipped bundles you installed and the desktop helper, and check the bundles from elsewhere, in one table (see [Updating](#updating))
38
38
  - `chi home`, `chi home set [--ruby PATH]`, `chi home doctor` — the chi home: the one Ruby (and its gem path) every chi launch boots, whoever launches it. `chi home` shows it (its Ruby, the newest chi in it, gem home and path, `mise`, when and by which chi it was set, and the chi you ran when that is another one; exit 1 with the problem when it can't boot chi), `set` records this chi's Ruby and gem path (or `--ruby PATH`'s own; it must have samagotchi), `doctor` checks it and what should follow it, one row each with `ok`, `warn` or `fail` and what to run (exit 1 on a `fail`; see [Checking it](configuration.md#checking-it-chi-home-doctor)). At a terminal, a chi on another Ruby than the home's says so in one dim line a day. This machine only (see [The chi home](configuration.md#the-chi-home))
39
- - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev), [Guardrails](guardrails.md), [Plugins](plugins.md#the-btw-bundle), [the mcp bundle](plugins.md#the-mcp-bundle) [the loop-guard bundle](plugins.md#the-loop-guard-bundle), [the check-in bundle](plugins.md#the-check-in-bundle) and [the skills bundle](plugins.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
39
+ - `chi bundle install|upgrade|uninstall|status|diff|list|build|trash|new|test|check` — manage memory bundles (see [Bundle hooks](hooks.md#bundle-hooks-unified-workflow-bundle)); `list` shows the installed ones and the ones shipped with chi, which `install <name>` installs; `core` and `dev` are profiles that install a set of them (see [Bundle profiles](memory.md#bundle-profiles-core-and-dev), [Guardrails](guardrails.md), [Bundles](bundles.md#the-btw-bundle), [the mcp bundle](bundles.md#the-mcp-bundle) [the loop-guard bundle](bundles.md#the-loop-guard-bundle), [the check-in bundle](bundles.md#the-check-in-bundle) and [the skills bundle](bundles.md#the-skills-bundle)). `trash` lists and empties the bundle trash (moved files from uninstalls/upgrades). A usage error (an unknown subcommand or flag, a missing argument, a bad `build --scope`) exits 2, as for the other subcommands. Plain `chi` and `chi web` exit 1 on an unknown flag, a flag missing its value or a stray argument. `new`, `test` and `check` are for writing one: see [Writing a bundle](#writing-a-bundle-new-test-check)
40
40
 
41
41
  - `chi guardrails replay [--dry-run] [--threshold T] [--model M]` — seed System 1's record from the approvals this machine's sessions already answered: each ask is judged by the configured model and written to `guardrails/judgments.jsonl` with the answer the user gave, then a per-rule table prints (asks, allowed, denied, would-be auto-allows, false allows, asks with no judgment). A parent agent's answer is not the user's: only its deny is replayed, and only where the parent could have allowed. `--dry-run` judges without writing, `--threshold` overrides `guardrails.system_one.threshold` for the table, `--model` the configured model for this run. Exit 2 when `guardrails.system_one.mode` is off or no `host` is set; a usage error exits 2 (see [System 1](guardrails.md#system-1-experimental))
42
42
  - `chi judgments ls` / `chi judgments report NAME [--days N]` — what [System 1's saved runs](system-one.md) hold: each judgment's digests, runs, labels, failures, models and size; one judgment's counts, p histogram and labels by value. Reads only; local only; `--days` must be a positive whole number.
@@ -153,7 +153,9 @@ The loop for a bundle you're writing (the whole path: [bundle-authoring.md](bund
153
153
  then forces), `install` (each Installer warning, a `needs` one as warn, and each plugin or hook load failure at
154
154
  the source `file:line`; skipped while a placeholder sha is unfilled), `registered` (info: each command, tool,
155
155
  hook with its priority, init, toolkit, tool source and peer source), `hook-event` (warn: a `chi.on` event chi
156
- never fires), `boundary` (warn: a `Samagotchi::` name outside "Stable for bundles"; a shipped bundle's listed
156
+ never fires), `settings` (warn: a `--set` the manifest's `settings:` rules out, as config.yml's `bundles:` is told), `api` (warn: a `ctx.*` / `chi.*` call or a keyword this chi's API lacks, read from the source with
157
+ Prism against the API's own classes, on a path that never runs too; written on a local `ctx` / `chi` itself, so a
158
+ `s = ctx.sessions` variable isn't followed; a name the plugin guards with `respond_to?` is left), `boundary` (warn: a `Samagotchi::` name outside "Stable for bundles"; a shipped bundle's listed
157
159
  exceptions aside) and `tests` (info: how to run them, or "no tests"). `--set KEY=VALUE` (repeatable, typed as
158
160
  `chi --set`) goes to `bundles: <name>:` in the sandbox's config.yml.
159
161
 
@@ -229,8 +231,10 @@ btw 0.1.1 up to date
229
231
  known-names 0.1.0 0.1.1 updated
230
232
  core 0.1.0 0.2.0 updated (+ new-bundle)
231
233
  infra_tools 1.0.0 skipped (not from chi)
234
+ infra_tools warn api plugin.rb:3: ctx.old_name isn't in chi 0.3.0's plugin API (fix: docs/plugins.md has the API)
232
235
  Chi Helper 0.2.0 up to date (launch file refreshed)
233
236
  workers 2 live on 0.2.0: they keep it until restarted (chi sessions restart 2ea8c1f0 91b0d2aa); or they idle out after 30 min with nothing attached
237
+ Bundles not from chi are left as they are: their author's next version, or chi bundle upgrade NAME, is what changes them
234
238
  Also shipped, not installed: dev (mcp, skills, source-links) (chi bundle install NAME)
235
239
  done
236
240
  ```
@@ -239,8 +243,10 @@ done
239
243
  newest release. It must be newer than the running chi; an equal or older
240
244
  version is refused.
241
245
  - `--json` writes the component rows as one JSON array on stdout. Each row has
242
- `component`, `from`, `to`, `status`, `failed` and `kept` fields; `kept` is an
243
- array of edited filenames. Install progress is written to stderr.
246
+ `component`, `from`, `to`, `status`, `failed`, `kept` and `level` fields;
247
+ `kept` is an array of edited filenames, and `level` is `warn` or `error` on a
248
+ re-check's row (below), `null` on the others. Install progress is written to
249
+ stderr.
244
250
 
245
251
  - **chi web update notices.** By default, chi web checks RubyGems about 30
246
252
  seconds after it starts and every 24 hours after that. Once a stable release
@@ -302,6 +308,30 @@ done
302
308
  A bundle of the same name from elsewhere (a zip, git) is skipped ("not from
303
309
  chi"), a newer installed one is left, one whose new version needs a newer
304
310
  chi is skipped, and bundles you didn't install stay uninstalled.
311
+ - **Bundles not from chi** are never changed, but the chi the update leaves
312
+ checks what is installed of them (the plugin, hooks and rules as they are,
313
+ not their source, which may be gone) with `chi bundle check`'s own checks,
314
+ and each warning or error is a row under the bundle's name: `requires_chi`
315
+ ruling this chi out, a plugin or hook that no longer loads, a hook on an event
316
+ chi no longer fires, a `ctx`/`chi` call the API lacks, a reference to chi's
317
+ internals, a name chi now ships, or a hook or plugin edited since it was installed (it
318
+ doesn't load). What only an author can act on (shas, unlisted files, tests, a
319
+ missing `requires_chi`, its floor, `trust_level`) is left out, and so are
320
+ profiles. A clean bundle gets no row beyond its `skipped (not from chi)`.
321
+ - **They fail nothing:** an error row too has `failed: false` and leaves the exit
322
+ status 0, chi web's **Update** and `update.auto` done. A warning repeats on
323
+ every run until the bundle changes, and a second run still says `everything is up to date`.
324
+ - **Each runs in a child process**, with your config.yml `bundles: <name>:`
325
+ settings in a sandbox: its code runs, as in any session. One that exits or
326
+ doesn't answer in 30 s is an `error check` row of its own; the rest go on.
327
+ - **Under the new chi:** the check runs in the update handed over to, so the new
328
+ API is what it's held against. When that hasn't happened, a row says
329
+ `external bundles … not checked (…)` instead of an answer about the old
330
+ API: `--dry-run` with a newer gem to install (without one, a dry run checks,
331
+ against this chi), and a gem installed with no way to hand over (run `chi
332
+ update` again). A failed gem install checks against this chi, since it stays.
333
+ - `--no-bundles` (`update.bundles: false`) leaves these out too: no check, no row
334
+ but `bundles skipped`.
305
335
  - **Profiles** (`core`, `dev`): an installed one installs the bundles a new
306
336
  chi added to it (`updated (+ name)`), even at the same version, and retries
307
337
  one that failed before; one you uninstalled stays out. See [Bundle
@@ -1500,7 +1530,7 @@ chi --remote work sessions list
1500
1530
 
1501
1531
  SSH can forward a Unix socket as well, which is how claude-peer's pairing makes
1502
1532
  a Claude session on this laptop reachable from chi on that machine
1503
- (`pair --inbox-socket <path>`): see [plugins.md](plugins.md), "chi on another
1533
+ (`pair --inbox-socket <path>`): see [bundles.md](bundles.md#the-claude-peer-bundle), "chi on another
1504
1534
  machine".
1505
1535
 
1506
1536
  How it works inside (`SessionAccess`, chi web's routes, where each check runs):
@@ -127,7 +127,7 @@ own subsystems: `hosts:` (below), `models:` (see "Prompt profile" and
127
127
  `guardrails:` (see [Guardrails](guardrails.md)), `bundles:` (a bundle's
128
128
  settings for its hooks, see [Hooks: Settings](hooks.md#settings); a session's own
129
129
  `--set BUNDLE.KEY=VALUE`, for a key the bundle's manifest lists in `session_settings:`, lays over them, see
130
- [Per-session settings](plugins.md#per-session-settings); `--set KEY=VALUE` does the same for a few core keys,
130
+ [Per-session settings](plugins.md#per-session-settings); a name no installed bundle has, or a key its manifest's `settings:` rules out, warns at a session's start; `--set KEY=VALUE` does the same for a few core keys,
131
131
  see "Per-session settings" below),
132
132
  `memories:` and `append_system_prompt:` (see "Appended prompt files"). Their entry names (host names, model ids, aliases) are yours to
133
133
  choose. The `memories:` list is the persistent baseline for preloaded memory entries —
@@ -1452,7 +1452,7 @@ To skip loading AGENTS.md (all of the chain), set `skip_agents_md: true` at the
1452
1452
 
1453
1453
  Nested `AGENTS.md` files (in directories the session doesn't run in) are
1454
1454
  steered into the conversation on first touch by the `agents-md` bundle
1455
- ([The agents-md bundle](plugins.md#the-agents-md-bundle)); `skip_agents_md`
1455
+ ([The agents-md bundle](bundles.md#the-agents-md-bundle)); `skip_agents_md`
1456
1456
  disables that steering too.
1457
1457
 
1458
1458
  ## Appended prompt files
@@ -1547,9 +1547,7 @@ toolkit:
1547
1547
  says `from this turn`, and that request re-reads the whole prompt (system prompt, tools and conversation, which
1548
1548
  the defer limits keep small) without `/toolkit`'s cache confirmation. `/toolkit` or `ctx.use_toolkit` marks the
1549
1549
  toolkit chosen, and nothing is suggested after that; a `/toolkit` sent during a turn runs after it and replaces
1550
- that turn's suggestion. When System 1's host is the model's own local server (the same `hosts:` name or server
1551
- root, as audit checks), on mode asks only on a session's first turn, never on the deferred path, and sends no
1552
- warm-up (one info line). Otherwise an idle worker for an eligible session sends one warm-up ask with the real
1550
+ that turn's suggestion. An idle worker for an eligible session sends one warm-up ask with the real
1553
1551
  question and a stand-in prompt so the server has its prefix cached; its answer is dropped and never logged, and
1554
1552
  the first real ask stops a warm-up still running. Each answered ask's line in `toolkit_suggestions.jsonl` adds
1555
1553
  `did`: `suggested`, `default`, `defer`, `chosen` (the toolkit was no longer the default), `unavailable` (the
@@ -1796,9 +1794,8 @@ context:
1796
1794
  mode: audit
1797
1795
  ```
1798
1796
 
1799
- A remote host is asked beside the turn. A System 1 host that is the model's own local server is asked after the
1800
- turn's last request, and the turn-end warm-up follows them, re-warming the prefix they evicted (see
1801
- [prompt caching](internals/prompt-caching.md)).
1797
+ The asks run beside the turn, on any host: they cost the session's cached prompt nothing on the model's own Splash
1798
+ either (see [prompt caching](internals/prompt-caching.md)).
1802
1799
 
1803
1800
 
1804
1801
  ## Bundles' judgments
@@ -2150,17 +2147,19 @@ Both are read when chi web starts (restart it to apply a change). What it does,
2150
2147
  it pushes the failed row's reason and stays quiet until a newer release (or you, with the button) tries again.
2151
2148
  3. **Restarts** (`update.restart: idle`). Stale workers first, only those whose session is idle and untouched for
2152
2149
  10 minutes (so nobody who is about to type loses their worker), and each worker still refuses by itself when
2153
- something holds it ([sessions](sessions.md)); the ones left are tried again for a day, then wait for their own
2154
- idle exit or the session's **Restart**. Then chi web itself, once no turn runs anywhere: it first runs the
2150
+ something holds it ([sessions](sessions.md)). Then chi web itself, once no turn runs anywhere: it first runs the
2155
2151
  restart's own command with `--version` (20 s at most) and restarts only if the newest chi answers with the
2156
2152
  release's version; otherwise chi web stays up and the phone hears "chi X is installed; chi web didn't restart".
2157
2153
  The restart is the **Restart chi web** one: same port, same token, same Tailscale Serve handler, the open page's
2158
2154
  streams reconnect in a few seconds and a Reload toast follows. It doesn't wait for a page in front: the page isn't
2159
2155
  reloaded by itself, so a draft in the composer stays. A **Send** or **Allow** pressed in those few seconds fails
2160
2156
  with its error and leaves the text in the composer: press it again.
2157
+ The workers left are tried again every 5 minutes, by the same rule and from the restarted chi web too, for a day from
2158
+ the install; after that they wait for their own idle exit or the session's **Restart**. A newer release in that day
2159
+ installs as usual and takes them over.
2161
2160
  4. **Says so.** The restarted chi web pushes "chi updated to X" ("chi web and 3 sessions restarted; 1 restarts when
2162
- idle. Kept your edits in 2 files."). With `update.restart: never` the push is "chi X is installed" and chi web and
2163
- the workers move over when you restart them (the page's toast offers it). The push needs the phone set up
2161
+ idle. Kept your edits in 2 files."); the later restarts of those sessions push nothing more. With
2162
+ `update.restart: never` the push is "chi X is installed" and chi web and the workers move over when you restart them (the page's toast offers it). The push needs the phone set up
2164
2163
  ([Phone notifications](#phone-notifications-web-push)); without it the page's toasts and
2165
2164
  `$XDG_STATE_HOME/samagotchi/update_check.json` (`auto`) are the record.
2166
2165
 
data/docs/context.md CHANGED
@@ -126,10 +126,10 @@ pbpaste | chi context push clip --project
126
126
  ```
127
127
 
128
128
  A Claude Code session can be a pushed source too: the
129
- [claude-peer bundle](plugins.md#the-claude-peer-bundle)'s `pair` script attaches
129
+ [claude-peer bundle](bundles.md#the-claude-peer-bundle)'s `pair` script attaches
130
130
  `claude-inbox` (Claude's inbox socket as the hint) and `claude-outbox`, where
131
131
  Claude pushes its answers as JSON with `wake: true`. The
132
- [codex-peer bundle](plugins.md#the-codex-peer-bundle)'s does the same for a
132
+ [codex-peer bundle](bundles.md#the-codex-peer-bundle)'s does the same for a
133
133
  Codex session: `codex-inbox` (Codex's thread id as the hint) and
134
134
  `codex-outbox`.
135
135
 
@@ -273,7 +273,7 @@ back the same way, its note plain, and pauses wakes too.
273
273
 
274
274
  ### Peer sources: the peer loop
275
275
 
276
- The claude-peer and codex-peer bundles ([Plugins](plugins.md)) pair the
276
+ The claude-peer and codex-peer bundles ([Bundles](bundles.md#the-claude-peer-bundle)) pair the
277
277
  session with a Claude Code or Codex session; the peer's answers come back as
278
278
  the `claude-outbox` / `codex-outbox` pushed source (the peer's `scripts/pair`
279
279
  attaches it). The bundle declares that source a peer's (`chi.peer_source`,
@@ -358,7 +358,7 @@ An archived session that nobody continued takes pushes as before.
358
358
 
359
359
  ### Peers and a continue
360
360
 
361
- A peer's pairing ([claude-peer, codex-peer](plugins.md#the-claude-peer-bundle):
361
+ A peer's pairing ([claude-peer, codex-peer](bundles.md#the-claude-peer-bundle):
362
362
  `<peer>-inbox` and `<peer>-outbox`, both pushed) stays with the old session,
363
363
  and the peer pairs again with the new one. The continue keeps what stayed in
364
364
  the new session (`left.json` beside its sources: each name, its last pushed
@@ -462,11 +462,8 @@ What it asks, and when:
462
462
  (a first "hi" doesn't count against it).
463
463
  - **After a judged ask:** one re-ask once `reask_after_turns` more prompts of
464
464
  yours came, with the conversation grown; then it is done.
465
- - **Where it runs:** on a remote System 1 host (Jev) beside your turn; on the
466
- model's own local server (System 1 on the same Splash) after your turn
467
- ends, so it never competes with the turn's prefill; the turn-end warm-up
468
- waits for those asks and restores the cached prompt they pushed out. One
469
- session's asks run one batch at a time.
465
+ - **Where it runs:** beside your turn, on any System 1 host. One session's
466
+ asks run one batch at a time.
470
467
 
471
468
  ### On mode
472
469
 
@@ -503,7 +500,10 @@ none at the thresholds then, with your prompts cut to 200 characters),
503
500
  `p`), `attached` / `declined` with `by: "command"` (`/context attach|decline`,
504
501
  the card's buttons), `attached` / `declined` / `detached` with `by: "user"`
505
502
  (what you did otherwise, seen at your next turn's start; removing a source
506
- declines it) and `withdrawn`.
503
+ declines it) and `withdrawn`. `chi sessions delete` drops a session's lines
504
+ from this log too, so the prompts it cut to 200 characters go with it; the
505
+ log's own size cap (5 MB, keeping the newest half) is what ages everything
506
+ else.
507
507
 
508
508
  `chi context report [--days N]` counts it, with no prompts in the output
509
509
  (this machine only):
data/docs/guardrails.md CHANGED
@@ -11,7 +11,10 @@ are offered.
11
11
  Who votes, in order:
12
12
 
13
13
  1. `before_tool_call` hooks (Ruby; see [Hooks](hooks.md#guardrails-from-a-hook)).
14
- 2. Core checks: a required guardrail that failed to load, then protected paths, then (a delegate child only)
14
+ 2. Core checks (`GuardrailWiring#checks`): a required guardrail that failed to load, then (a participant's turn only)
15
+ [the review boundary](#a-participants-review-boundary) or, for a pair turn,
16
+ [the pair boundary](#a-participants-pair-boundary), then protected paths, then (a `chi scratch` session only)
17
+ writes to the memories folder (rule `scratch-session`), then (a delegate child only)
15
18
  [the child boundary](#a-delegate-childs-boundary).
16
19
  3. YAML rules: `config.yml`'s `guardrails:` section, then installed bundles' rule files (by bundle name).
17
20
 
@@ -1086,12 +1089,8 @@ not `guardrails.system_one.mode`. Audit never changes the session's toolkit;
1086
1089
  on mode's turn waits for the answer (at most `timeout_ms`, cut by a Stop)
1087
1090
  and may start the session on the suggested kit (configuration.md, Toolkits).
1088
1091
  Its warnings use the `toolkit` tag and its records are written to
1089
- `toolkit_suggestions.jsonl` beside the guardrail logs. To avoid competing
1090
- with the session's model, audit skips (one info line) when
1091
- the System 1 host is the model's local host: the same `hosts:` name, or
1092
- another entry for the same server root (scheme, host and port). There is no
1093
- reliable single-slot signal, so this host-identity check is the available
1094
- contention guard. The session's own checks come first; the kits and the
1092
+ `toolkit_suggestions.jsonl` beside the guardrail logs. The session's own
1093
+ checks come first; the kits and the
1095
1094
  suggestion log are read only for a session that can be asked, the log only
1096
1095
  after an earlier `undecided`.
1097
1096
 
@@ -1101,8 +1100,7 @@ questions per proposed candidate, "Is this session's work about the
1101
1100
  candidate?" and "Has the user stated a task yet?", on the same host and
1102
1101
  model, gated by its own mode alone. It logs to `context_candidates.jsonl`
1103
1102
  with the `context` tag; in on mode `ContextCandidateChoice` acts on the
1104
- answer (attach, card, or nothing). Unlike the toolkit's audit it doesn't skip a shared
1105
- local host: it asks after the turn ends there. Both side judgments run
1103
+ answer (attach, card, or nothing). Both side judgments run
1106
1104
  through `SideJudgments` (one ask in flight per kind, a failure is one warn,
1107
1105
  shutdown waits up to a second).
1108
1106
 
data/docs/hooks.md CHANGED
@@ -228,7 +228,7 @@ turn. Don't ask questions or call the model from it: `event[:ask_user]`
228
228
  returns nil at once here, and `ctx.ask_model` would hold the stream for its
229
229
  whole answer. A hook that never returns hangs the turn, as any hook does. A
230
230
  plugin's block that raises is logged (`plugin_hook_failed`) at most once a
231
- minute.
231
+ minute, and its first failure in a worker shows once in every UI.
232
232
 
233
233
  Two ways to act:
234
234
 
@@ -472,6 +472,23 @@ once in the UI.
472
472
  Hook failures never break the engine loop — each hook is wrapped in its own
473
473
  try/catch.
474
474
 
475
+ A bundle's `hooks/*.rb` file that **raises** tells you once per hook in a
476
+ worker, on the plugins' surface, whatever its `on_error` (the same notice a
477
+ `chi.on` handler gets):
478
+
479
+ ```
480
+ plugins> guardrail guardrails.rb (bundle known-names) before_tool_call hook failed (RuntimeError: boom):
481
+ it denies every tool call it guards, and its next failures are in each denial's reason
482
+ ```
483
+
484
+ The label names the file, the bundle and the event, so one line per hook: a
485
+ hook on a stream can't nag. `on_error` still decides what happens at every
486
+ firing — `skip` logs nothing, `log` warns each time (a stream hook at most
487
+ once a minute), a fail_closed `before_tool_call` hook denies the call — the
488
+ notice is only added on top. A config hook (config.yml's own files) keeps its
489
+ behaviour: no notice, just the log. A UI that joins later reads the same lines
490
+ from `Engine#plugin_warning`.
491
+
475
492
  ## Runtime Hook Registration
476
493
 
477
494
  You can also register hooks programmatically during a turn (they are cleared
@@ -688,7 +705,7 @@ Notes:
688
705
  - Ordering: bundle hooks fire by `(priority, bundle_name, hook_name)` (lower priority first), then plain `config.yml` hooks in registration order.
689
706
  - Settings: a hook class with `initialize(settings = {})` gets the bundle's section of `config.yml` `bundles:` (see [Settings](#settings)).
690
707
  - A bundle can also ship a `plugin.rb` whose `chi.on(event)` blocks are bundle hooks too, next to commands and tools; see [Plugins](plugins.md). There `ctx.notify`, `ctx.steer` and the other `ctx` helpers act as this page's `event[:notify]`… do for the event the block runs for.
691
- - Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Plugins](plugins.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Plugins](plugins.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Plugins](plugins.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Plugins](plugins.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Plugins](plugins.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Plugins](plugins.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Plugins](plugins.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Plugins](plugins.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Plugins](plugins.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Plugins](plugins.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Plugins](plugins.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Plugins](plugins.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Plugins](plugins.md#the-claude-peer-bundle)) and `chi bundle install model-notes` (memories: reviewed model notes, see [Plugins](plugins.md#the-model-notes-bundle)).
708
+ - Shipped bundles (each in a profile: `core` or `dev`, see [Bundle profiles](memory.md#bundle-profiles-core-and-dev)): `chi bundle install guardrails` (rules, see [Guardrails](guardrails.md#the-guardrails-bundle)) and `chi bundle install known-names` (a hook, see [Guardrails](guardrails.md#the-known-names-bundle)), `chi bundle install source-links` (a hook: announces source refs, see [The source-links bundle](#the-source-links-bundle)), `chi bundle install btw` (a plugin: `/btw`, see [Bundles](bundles.md#the-btw-bundle)), `chi bundle install mcp` (a plugin: tools from MCP servers, see [Bundles](bundles.md#the-mcp-bundle)) `chi bundle install loop-guard` (a plugin: breaks tool-call loops, see [Bundles](bundles.md#the-loop-guard-bundle)), `chi bundle install check-in` (a plugin: checks on a long turn, see [Bundles](bundles.md#the-check-in-bundle)), `chi bundle install slow-commands` (a plugin: commands that ran past the execute limit are run as tasks next time, see [Bundles](bundles.md#the-slow-commands-bundle)), `chi bundle install agents-md` (a plugin: a nested AGENTS.md is steered into the conversation on the first touch under its directory, see [Bundles](bundles.md#the-agents-md-bundle)), `chi bundle install cost-cap` (a plugin: a per-session $ cap, `/cap`, see [Bundles](bundles.md#the-cost-cap-bundle)), `chi bundle install work-cap` (a plugin: a per-session cap on tool calls and active minutes, `/workcap`, see [Bundles](bundles.md#the-work-cap-bundle)), `chi bundle install ruby` (a plugin: an RSpec run with no examples at all, a hint, see [Bundles](bundles.md#the-ruby-bundle)) `chi bundle install skills` (a plugin: `/skill`, versions of skills, see [Bundles](bundles.md#the-skills-bundle)), `chi bundle install github-pr` (attached context: the branch's open PR, see [Bundles](bundles.md#the-github-pr-bundle)), `chi bundle install coordinator` (a plugin: parallel work in worktrees and child sessions, see [Bundles](bundles.md#the-coordinator-bundle)), `chi bundle install claude-peer` / `codex-peer` (a plugin: talk to a Claude Code or Codex session, see [Bundles](bundles.md#the-claude-peer-bundle)) and `chi bundle install model-notes` (memories: reviewed model notes, see [Bundles](bundles.md#the-model-notes-bundle)).
692
709
  - Installing a bundle executes its hook code at `Engine` startup. Only install bundles you trust, as you would a gem. Hooks are **not** executed at install time (copy-only); they are `module_eval`'d at `Engine.new` inside per-bundle `Samagotchi::Bundles::<name>` namespaces (no top-level `require` collisions). Keep hook files side-effect-free at load time; do work in `#call` — top-level side effects (require, IO, `at_exit`, global assignment) run once per `Engine.new` (class redefinition is idempotent).
693
710
 
694
711
  Lifecycle:
@@ -144,9 +144,8 @@ nothing, so the next owner prompt asks again.
144
144
  The driver is the Engine, not the judge: `Engine#start_context_judge` (an owner turn's start; skipped for participants,
145
145
  review sessions and a Continue) and `judge_late_candidates` (a proposal after the prompts) call `context_judge_pass`.
146
146
  It first logs status changes (`ContextCandidatesLog.look`), returns at `mode: off`, builds the due `Job`s, and hands
147
- them to `SideJudgments` (`:context` kind: one thread, one batch per session at a time). On the model's own local
148
- server (`system_one_shares_local_host?`) the pass is held in `@context_judge_after_turn` and started after the turn
149
- (before the prompt warm-up, which waits for it); any other host is asked at once.
147
+ them to `SideJudgments` (`:context` kind: one thread, one batch per session at a time), asked at once on any host,
148
+ the model's own server too.
150
149
 
151
150
  `ContextCandidateChoice.after_judged` acts on `fields["would"]` in `on` mode only: *attach* → `judge_attach` (a
152
151
  session source with `JUDGE_WHY`, no probability in the model-visible why), *offer* → one card (`offer_card`, buttons
@@ -3,7 +3,7 @@
3
3
  How `lib/samagotchi/memory_bundle/` turns a bundle (a dir, git URL, zip or tar holding `manifest.yml`, `*.md`
4
4
  memories and optional `hooks/`, `guardrails/`, a plugin file and `scripts/`) into installed state, and back. The
5
5
  user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memory.md#what-a-bundle-owns) and
6
- [plugins.md](../plugins.md).
6
+ [plugins.md](../plugins.md) and [bundles.md](../bundles.md).
7
7
 
8
8
  ## Where things live
9
9
 
@@ -25,6 +25,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
25
25
  | `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check/try` (`install --dev`: the Installer's `dev:`, links and `Provenance::DEV_SHA`); runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it) |
26
26
  | `BundleCommand::Check` (bundle_command/check.rb) | `chi bundle check [PATH] [--fix] [--set K=V]`: a bundle being written, checked as an install takes it (docs/cli.md lists the codes); parses the manifest from `Shas.parseable` (a placeholder sha is a `sha` finding, not a YAML error), reads the user's installed bundles only for `clash`, and installs and loads through `Testing::Install` in a `Testing::Sandbox` with `force: true`, the log's echoes swallowed |
27
27
  | `BundleCommand::Try` (`bundle_command/try/`) | `chi bundle try PATH -p TEXT`: `Command` (its flags, help and checks) drives the rest and `Render` prints the trace; a filtered-config `Sandbox` (its folders a `SandboxLayout`, the layout `Testing::Sandbox` uses too) installs the tried bundle and shipped `guardrails` / `cost-cap` in a separate child, then `Run` starts one non-interactive chi process from its realpath work dir; `TraceReader` reads that session's analytics, cards (`Bridge::CardStore.saved`, as the web does) and session JSON by id (never `Session.list`), joining timing and tool args for text or experimental JSON output (a turn a `--timeout` interrupt cut keeps its calls like a Ctrl-C, the one cut short answered as interrupted, so its rows come from the saved calls too; `Run::Result#timed_out` becomes `timed_out`). `Sandbox#child_env` is a Hash, never an ENV mutation; it keeps ordinary user model settings and Keychain access while dropping the spawner's session/guardrail/worker markers (`ChildEnv`, the scrub a session's worker spawn uses too). The child runs in its own process group: a `--timeout` sends it INT, then `ProcessGroup.stop` (the groups its processes started too); after any exit the group is signalled only while a straggler is still in it, never a reaped group. `Sandbox#stop_leftovers` (before the trace, and in `cleanup`) stops what left the child's tree, found by the sandbox's own records: a delegate's worker by its session's `owner.lock`, a task by its running `task.json` whose pid still leads its group. |
28
+ | `BundleCommand::ApiCalls` (bundle_command/api_calls.rb) | what a plugin's source calls of the API, by Prism: `#findings` (a call or keyword the API's classes lack, `check`'s `api`), `#keywords` (the floor check's `call(keyword:)`). Its only list is `MEMBERS`, which object a member gives (`ctx.sessions` → `Plugin::Sessions`); a new such object joins it |
28
29
  | `BundleCommand::Scaffold` (bundle_command/scaffold.rb) | `chi bundle new NAME`: the starting files (block-form `plugin:` entry, `requires_chi` at this chi, a kit test that passes as written); the manifest's shas are filled through `Shas.refresh` |
29
30
  | `BundleCommand::TestRun` (bundle_command/test_run.rb) | `chi bundle test`: `RbConfig.ruby -I <chi's lib>` on `test/**/*_test.rb` (Minitest) or `spec/` (RSpec, as `rake bundles:specs`), under `Bundler.with_unbundled_env` when Bundler's runtime is loaded |
30
31
  | `Shas` (shas.rb) | a manifest's `sha256:` lines: `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / hook / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |
@@ -32,7 +33,7 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
32
33
  | `SourceIdentity` (source.rb) | what a source is, for comparing two installs of one name: `shipped:<dir>` (any gem or checkout), `git:<url>` (no `#ref`, trailing `/` or `.git`), `path:<realpath>`; nil when it can't place one |
33
34
  | `PreparedSource` (source.rb) | one source normalized once (dir, owned, git commit): `BundleCommand` reads the bundle's name from its `manifest.yml` (the name for every kind of source, a git URL too) and hands it to the Installer (`prepared:`), so a source is cloned or extracted once per command |
34
35
  | `MemoryFiles` | which top-level `*.md` files of a bundle are its memories (`.select`: the `files:` list, else all but README/LICENSE and the like), `.unshipped` (listed, not shipped) and `.symlinks` (skipped: a symlink is never a memory) |
35
- | `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `SessionConfig` to check) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
36
+ | `Manifest` | parses/validates `manifest.yml` (`name:` is the bundle's name and a directory under `.bundles/`, so a path such as `../x`, `a/b`, `.` or `..` is refused: `name: … is not a bundle name`; YAML that doesn't parse or isn't a mapping is a `ValidationError` too; files, hooks as `BundleHook`, plugin, scripts, needs, requires_chi, includes, context_providers, session_settings: the keys a session's `chi --set` may give, a list or a mapping of them to types (`SESSION_SETTING_TYPES`), recorded at install in `manifest.json` (`session_settings`, `session_setting_types`) for `SessionConfig` to check; settings: the keys config.yml's `bundles: <name>:` may have, the same shape, recorded as `settings` (nil when the manifest has none) and `setting_types` for `BundleSettingsCheck`, whose warnings the Engine holds for the first turn and `SessionConfig`'s refusals share the words of) and writes it (`Manifest.write`, for Builder). It ignores `requires_chi_next`, a shipped bundle's release-time marker (`script/release/release_tools.rb`, docs/releasing.md) |
36
37
  | `Installer` | one install/upgrade/dry run of one bundle (below) |
37
38
  | `AssetInstaller` | the parts that live in `.bundles/<name>/`: hooks, guardrail rules, plugin, scripts; returns `AssetInstaller::Installed` (the paths the record keeps) |
38
39
  | `Merger` | 3-way classification per file: `install`, `fast_forward`, `keep`, `noop`, `conflict` |
@@ -40,7 +41,8 @@ user-facing side (what a bundle owns, profiles, needs) is in [memory.md](../memo
40
41
  | `InstalledBundle`, `BundleHook`, `PluginRef` | value objects for the record; tolerant of older records (missing keys read as empty). `BundleHook#events` is the manifest's `event:` or its `events:` list (written back as `event:` for one, as an older chi reads it); `Hooks::BundleLoader#load_hook_file` builds the hook once and registers it under each |
41
42
  | `Builder` | `chi bundle build`: memories (+ the installed bundle's hooks, rules, plugin, scripts) → zip/tar/dir |
42
43
  | `Profile` | meta bundles (`includes:`): install the members, record which; `InstallResult#kept_own` names a new member's memory files the user already had, with other bytes (`kept_own_line`, printed by `chi bundle`, `chi update` and `chi bootstrap`); a dry run runs each member's Installer as a dry run too, so it names them as well |
43
- | `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true` |
44
+ | `SystemBundle`, `ShippedUpdate` | the built-in system bundle (`ensure!` at Engine start, `sync` in `chi update`) and `chi update`'s upgrade of shipped bundles; both drive the Installer with `upgrade: true`. `ShippedUpdate.external` is the rest: what `chi update` only checks |
45
+ | `InstalledCopy`, `BundleCommand::InstalledCheck` | `chi update`'s re-check of the bundles chi didn't ship ([docs/cli.md](../cli.md#updating)). `InstalledCopy` lays a record and its installed files out as a source folder (manifest.yml from `Manifest.write`, the files' own shas, memories from `bases/`); `InstalledCheck` forks per bundle (a plugin's `exit` or hang is that bundle's row; stdio to /dev/null, so `--json` stays parseable; `TIMEOUT`, then KILL of its group) and runs `Check.new(dir, installed: true)` there, which leaves out what only suits a source tree. The fork is the point: `Sandbox` swaps ENV and the plugin's code is arbitrary. `UpdateCommand#external_rows` makes the rows (`level`, never `failed`) and holds the check back while a newer gem is yet to take over (`@not_checked`), since a fork is this chi's code |
44
46
  | `Uninstaller`, `Trash`, `Status`, `Listing` | remove, keep removed files, `chi bundle status`, `chi bundle list` |
45
47
  | `IndexUpdater`, `IndexSync` | the managed `index.md` lines (Installer; and the write/edit tools for memories) |
46
48
  | `EntrySize` | one memory's size in tokens: `memory.entry_warn_tokens`' crossing note after a memory write, `chi self`'s `big memories` row |
@@ -742,7 +742,11 @@ step's text ([architecture.md](../architecture.md), the `display_refs` paragraph
742
742
  - **Turn-scoped hooks** (`Engine#register_hook`, `Registry#register`) are cleared by `clear_hooks` in
743
743
  `release_turn`.
744
744
  - Order of a fire: bundle hooks (by priority, bundle, hook name), then config hooks, then turn-scoped hooks.
745
- - A hook that raises is logged; it never breaks the turn.
745
+ - A hook that raises is logged; it never breaks the turn. A plugin's `chi.on` handler and a bundle's `hooks/*.rb`
746
+ file also tell the user, once per label in this Engine (`Hooks.wrap(on_failure:)` → `HookRoutes#plugin_hook_failed`: a
747
+ `:guardrail_warning` labelled `plugins`, with `Engine#plugin_warning` for a UI that joins later). The Engine hands
748
+ that callback to the hook files through `ExtensionLoad.new(hook_failed:)` → `Hooks::BundleLoader.load(hook_failed:)`;
749
+ a config hook (config.yml's own files) has none, and the test kit's sandbox gives none.
746
750
  - A notice from a hook goes to the running turn's sink and the observers. Outside a turn it is announced with
747
751
  `between_turns: true`; while the plugins load it is held and announced after. `EventRoutes#route` decides it, the
748
752
  same routes as a card's (`Engine#show_card`), with their own marks (`NOTICE_MARKS`, `CARD_MARKS`); a guardrails
@@ -795,8 +799,10 @@ Engine
795
799
  Both loops:
796
800
 
797
801
  - <a id="a-reply-that-is-only-a-tool-call"></a>**A reply that is only a tool call** (`LLM::StrayToolCall`, `LLM::ChatLoop` only): a reply with no tool
798
- calls whose whole text is one closed tool-call block, which the host couldn't read, isn't an answer. A reply opening with prose or a fence stays
799
- an answer, and the check is one string test on a normal one. Nothing is guessed from the block and it never enters the history (`:generation_completed`
802
+ calls whose whole text is one tool-call block closed by the tag that opened it (`<function=` by `</function>`, `<parameter=` by `</parameter>` or
803
+ `</function>`, `<tool_call>` by `</tool_call>`), with nothing else in it — the block need not carry inner tags — isn't an answer. A reply
804
+ opening with prose or a fence, or saying anything after the close, stays an answer, and the check is one string test on a normal one. Nothing is
805
+ guessed from the block and it never enters the history (`:generation_completed`
800
806
  and `:after_generation` have already seen the text): `:generation_retrying` with `restarted` voids the streamed text, `:empty_answer_retry` with
801
807
  `malformed` goes out, and a hidden `TurnNote.malformed_retry` asks again at the retry temperature. It has its own budget, so `retry.empty_answer: 0`
802
808
  doesn't turn it off, and a real tool call resets it. Two in a row fail the turn with `LLM::MalformedGeneration`, keeping its earlier steps. Each is
@@ -80,19 +80,18 @@ right-hand column happens.
80
80
  `toolkit.suggest.defer_turns` / `defer_tokens`) is engine-side, so `/toolkit`'s CacheConfirm doesn't apply: it
81
81
  changes the declared tools at the front of the request, and the server re-reads **system prompt + tools +
82
82
  conversation** on that turn. The defer bound keeps that conversation small; its notice says "from this turn".
83
- When System 1 runs on the model's own single-slot local server (`Engine#system_one_shares_local_host?`), any
84
- ask takes the slot and evicts its cached prefix: a first-turn ask costs that cache even when nothing switches
85
- (there is little cached on a session's first turn), so on mode asks only there, skips the deferred path, and
86
- sends no worker warm-up.
87
83
  - The candidate judge (`context.candidates.mode`, `ContextJudge`) adds nothing to the model's request: its asks
88
84
  go to System 1 only, and nothing it answers enters the running turn's history: on mode's attach writes only the
89
- session's context folder, and its note comes with the between-turn delivery (`ContextAbsorber`), never mid-turn. On a shared local server it asks after the turn's last request, not skipped: a
90
- completed turn starts the asks right before its turn-end warm-up, and the warm-up waits for them
91
- (`PromptWarmup#start`'s `after:`, `AFTER_SECONDS` at most), so it re-warms the prefix the asks evicted and the
92
- next turn prefills only its own message. A turn that ended otherwise (a Stop, a failure: no warm-up) starts them
93
- from `Engine#run_turn`'s ensure, and its next turn re-reads its prompt. Where no warm-up runs (`cache.warmup:
94
- off`, a chat host) the asks still evict the prefix. Bounded either way: at most two judged asks per candidate (one
95
- re-ask after `reask_after_turns` owner prompts), plus a deferred ask per owner prompt before a task is stated.
85
+ session's context folder, and its note comes with the between-turn delivery (`ContextAbsorber`), never mid-turn.
86
+ Its asks start beside the turn on any host. Bounded: at most two judged asks per candidate (one re-ask after
87
+ `reask_after_turns` owner prompts), plus a deferred ask per owner prompt before a task is stated.
88
+ - System 1's asks (`SystemOne::Client`, `/v1/systemone`) go beside the turn on any host, the model's own Splash too,
89
+ because they don't cost the session its cached prompt there. Measured 2026-11-01 on a local Splash with a 60k-token
90
+ session: the next request still had 60,064 tokens cached in 0.13 s after 3 asks (0.09 s with none), and 60,160 cached
91
+ in 0.18 s after 10 asks during generation; asks answered in 108-158 ms during a turn, and those 10 took the
92
+ generation from 2.87 s to 4.43 s. An earlier guard skipped or deferred them on the assumption that an ask takes the
93
+ slot and evicts the prefix, never measured there; don't rebuild it from that assumption. Not measured: a prefix past
94
+ Splash's cache capacity (262144 tokens).
96
95
  - A kit's prompt text (`toolkit.kits.<name>.prompt:`, `chi.toolkit … prompt:`) sits after the appended files and
97
96
  before the memory indexes (`SystemPrompt#kit_prompt_section`): one prefix per kit, never per-session text, so
98
97
  sessions on the kit share it; a memory write (the indexes after it) doesn't move it. It is part of the
@@ -275,7 +274,8 @@ is prefilled once. The native and the chat loop use the same plan.
275
274
  ## Server-side settings worth knowing
276
275
 
277
276
  - **Splash:** `--persistent-cache` (with `--max-cache-disk`) keeps restore points across restarts. Splash learns
278
- a new branch point on the 2nd session, so the 3rd one gets the full reuse.
277
+ a new branch point on the 2nd session, so the 3rd one gets the full reuse. System 1's asks on the same server leave
278
+ a session's cached prefix alone (measured 2026-11-01, above).
279
279
  - **llama.cpp:** `--cache-ram` (the host-memory prompt cache, 8 GiB by default in recent builds) is what keeps
280
280
  sessions apart: when a task starts on a slot, the idle slots' state goes to that cache, and an unpinned request
281
281
  restores the best match on whatever slot it gets. So a recap or another session between two turns costs
@@ -188,7 +188,7 @@ from saying it twice across restarts). The key's `chi:` prefix keeps sw.js from
188
188
 
189
189
  `updated` is sent by the **restarted** chi web (its AutoUpdate finds the run at `phase: web`): the exec ends the
190
190
  old process, and `Notifier#stop` does not flush the shows still in their hold, so a push queued just before it would
191
- be lost. Sending from the new process also proves it came up.
191
+ be lost. Sending from the new process also proves it came up. The workers left then restart without another show.
192
192
 
193
193
  **Seeding**: `Notifier#start(hub)` subscribes with `snapshot: true` and takes the summaries as the seed, so what is
194
194
  open already never pushes. The hub's projection is empty before its first scan, so `Server.start` runs `hub.scan`
data/docs/memory.md CHANGED
@@ -182,7 +182,7 @@ Working habits for this model:
182
182
  `model_notes_deepseek` (`models: *deepseek-v4*`) and `model_notes_tone`
183
183
  (`models: *`, concise answers for every model). Each note's provenance
184
184
  and evidence is in the bundle's `notes/README.md`, and its spec pins which
185
- model ids load which note ([Plugins](plugins.md#the-model-notes-bundle)).
185
+ model ids load which note ([Bundles](bundles.md#the-model-notes-bundle)).
186
186
  - **Your own note of the same name wins.** The install skips a
187
187
  `model_notes_<name>.md` you already have and never owns it, so your note
188
188
  is what loads, the two never stack, and upgrades leave it alone.
@@ -320,7 +320,7 @@ A skill is plain Markdown, no frontmatter:
320
320
 
321
321
  It is a memory like any other: `memory_read`, `chi --mute skill_release`,
322
322
  `chi bundle build` share it. The optional `skills` bundle (`chi bundle install
323
- skills`, [docs/plugins.md](plugins.md#the-skills-bundle)) adds `/skill save`,
323
+ skills`, [docs/bundles.md](bundles.md#the-skills-bundle)) adds `/skill save`,
324
324
  `/skill list`, `/skill show`, `/skill diff`, keeps older versions with a
325
325
  one-line diff after each update, and nudges a model that skips a failing
326
326
  step instead of fixing the skill.