samagotchi 0.103.0 → 0.105.0

data/docs/testing.md

@@ -22,6 +22,9 @@ with two rules only, `no-undef` (a name used but never imported or declared: a d
 style pass: add a rule only for a bug class it would have caught. It runs in about 2 s, in CI's `npm test` job and in
 `rake release:check`; `rake lint` stays RuboCop alone (CI's rubocop job has no node). A name that is also a browser
 global (`name`, `status`, `open`…) passes even when its import is gone: give an export such a name only with care.
+It also checks `spec/e2e/` for one thing, the Playwright twin of `Samagotchi/SpecSleep`: no `page.waitForTimeout`.
+Wait for the state (a locator's `expect`, `data-phase`, an animation's end through `waitForFunction`); a pause that
+is the behaviour (a pointer's dwell) carries `// eslint-disable-line no-restricted-syntax -- why`.
 
 CI's e2e job keeps the tests, chi and the fake model on the runner but runs Chromium in Playwright's image
 (`mcr.microsoft.com/playwright:v<version>-noble`, `playwright run-server` on the host network); the tests connect
@@ -66,11 +69,89 @@ either router adds its row there; a row where a UI differs on purpose (or a foun
 `repl` override and a `note`. The Ruby side runs each row with every core command (a new one fails its
 `CORE_ROUTES` check until listed there); a row's names that core lacks stand for plugin commands.
 
-A spec that waits for something uses `wait_until(timeout:)`, or `wait_until!(what, timeout:)` where no check
-follows (stubs, helper threads: it raises "timed out after N s waiting for <what>") — never a loop with no deadline.
+## Waiting and time
+
+A spec waits *for* something and never sleeps to wait: a fixed pause is too short on a loaded runner (a parallel
+run, CI) and too long on a fast one. The contract a new spec follows:
+
+1. **Never `sleep` to wait.** Wait for the condition: `wait_for("what") { condition }`, or
+   `eventually { expect(…) }` for a value. A `sleep` that *is* the behaviour (slowness, holding a connection,
+   separating mtimes) carries `# sleep-ok: why` on its line or the line above (for a call over several lines, its
+   first line). A bounded best-effort `wait_until`
+   whose timeout is fine ("at most 0.5 s, fine to cut short") carries `# wait-ok: why`; it must not become
+   `wait_for`, which would raise where the code moves on. A `Timeout.timeout` is a wait too (use `pop!`, `join!` or
+   `wait_for`); one that only guards a call that returns by itself against a hang carries `# timeout-ok: why`.
+2. **Time logic takes seams.** Intervals, graces and deadlines in lib take `clock:` / `sleeper:` / `interval:`
+   constructor arguments, and the unit spec moves the clock itself (`SessionAccess::Remote` is the model;
+   `IdleScheduler.new(interval:)`). Real time is used only in one smoke example per class. Two sessions or inbox
+   files that must sort apart get distinct times, not a pause: `Session.new_session(now:)`, `Session#save(now:)` and
+   `SessionInbox.write_input` / `write_note` / `write_output(now:)` take `now: next_stamp` (spec/support/stamps.rb:
+   a millisecond later on each call, starting a second in the past).
+3. **What a spec starts, it stops and waits for** before teardown: `join!(thread, what)`, `with_task_dir { … }`
+   (spec/support/task_dirs.rb: a tasks' folder of its own, its tasks stopped and their exit-status recorders joined
+   with `TaskRuntime.quiesce!`), a `stop` that joins (`IdleScheduler#stop`). Never only `Thread#kill`.
+4. **"Nothing happens" is shown by counting passes** (the worker's loop rounds, spec/support/worker_loop_rounds.rb;
+   a class's ticks), not by a pause.
+5. **A wall-clock bound** only as "not the full N s", with at least 5× headroom measured on the slow (x86) laptop.
+
+The helpers are the bundle test kit's (`Samagotchi::Testing::Waiting`, [plugins.md](plugins.md#testing-a-bundle-experimental)),
+so core and bundle specs share one copy; `SpecWaiting` (spec/support/waiting.rb) includes them in every example
+group and also answers them as module calls (`SpecWaiting.pop!`, for a stubbed lib thread):
+
+- `wait_for(what, timeout: 5, interval: 0.01, seen: nil) { … }` returns the block's first truthy value, or raises
+  `Waiting::TimedOut`. `seen:` (a callable) shows what the condition last saw, since a falsy block value tells
+  nothing.
+- `join!(thread, what, timeout: 5)` and `pop!(queue, what, timeout: 5)`: `Thread#join` and `Queue#pop` with the
+  same deadline and message. A gate a stubbed lib thread waits on takes `timeout: 30`: it only ends a hang.
+- `wait_until(timeout:) { … }` returns the block's last value (falsy at the deadline): for a value the example
+  checks after, or a `wait-ok` wait.
+- `eventually(timeout: 5) { expect(…) }` (spec only) retries until the expectations hold, then re-raises the last
+  failure prefixed `still failing after 5 s:`, so the matcher's own expected/got is in the message.
+
+One formatter builds the failure text of `wait_for`, `join!` (which adds "to finish") and `pop!`:
+
+```
+timed out after 5 s waiting for task 20261023-0a1b to end
+timed out after 10.0 s (5 s × SPEC_TIME_SCALE 2) waiting for task 20261023-0a1b to end; last saw: "running"
+```
+
+**`SPEC_TIME_SCALE`** (default 1, at least 1; CI's `rspec`, `rspec-macos` and `bundles` jobs set 2) multiplies
+every helper deadline, explicit `timeout:` values included: a positive wait only gets more headroom, and a passing
+run is no slower. Set it locally to reproduce a CI timing (`SPEC_TIME_SCALE=2 bundle exec rspec FILE`). It does not
+scale the lib's own timeouts a spec passes in (`wait: 0.05`, `grace: 0.1`): those are the code's deadlines, and a
+flaky one gets a `clock:` seam instead. A helper's own spec pins the scale (stub `Waiting.time_scale`). Keep
+explicit helper timeouts at 30 or below: 60 s on CI, under the per-example limit.
+
 Every example also runs under a 120 s limit (`spec_helper`'s `around`; `integration`, `macos_build`, `warmup` and
 `recap` examples are exempt), so a hang fails its example instead of the run. `SPEC_EXAMPLE_TIMEOUT=N` changes the
-limit, `0` turns it off (a debugger session).
+limit, `0` turns it off (a debugger session). The limit is not scaled.
+
+**The cops.** `Samagotchi/SpecSleep` (an untagged `sleep` in a spec) and `Samagotchi/SilentWait` (a `wait_until`
+whose value is dropped, an example's last line included, `expect(wait_until { … }).to be(true)`, or an untagged
+`Timeout.timeout`) live in `rubocop/` and run in `rake lint`, so CI fails on them. RSpec counts `wait_for`,
+`eventually`, `join!` and `pop!` as an example's expectation (`RSpec/NoExpectationExample`), so a wait can be an
+example's last line. What the cops can't see, `script/affected-specs` hints at (`timing:`, below).
+
+### Flakes
+
+When `parallel_rspec` fails in CI's `rspec` or `rspec-macos` job, the next step (`script/rerun_failures.rb`) reruns
+only the failed examples, once, with plain `rspec`. It reads their ids from `tmp/parallel_failures.log`
+(`.rspec_parallel`'s `FailuresLogger`) and writes the job summary: **Flaky: passed on rerun** or **Failed twice**,
+with the example ids, the Ruby version and the job. It skips the rerun when no ids were logged (a load error) or more
+than 20 failed (a real breakage). The job fails either way: a flake is a bug to fix, not a pass.
+
+Every flake is classified into one of the four patterns, each with its own fix:
+
+1. **A settle sleep**: the spec paused for "long enough". Wait for the condition (`wait_for`, `eventually`).
+2. **A live loop racing the spec's own drive of it** (a worker loop, a scheduler tick the spec also calls). Count
+   passes, or stop the loop before driving it by hand.
+3. **Teardown before background work stops**: a thread, task or process still running when the example's `after`
+   removes its folder. Stop it and wait for it (`join!`, `with_task_dir`, a joining `stop`).
+4. **A lib deadline on the real clock** (`wait: 0.05`, `grace: 0.1`) too short on a loaded runner. Give the class a
+   `clock:` / `sleeper:` seam and move the clock in the spec.
+
+A second flake of the same pattern at a new site means that pattern needs a seam in lib there (for example an `on_*:`
+callback the spec can wait on), not another local fix in the spec.
 
 ## Bundle specs: the test kit
 
@@ -140,7 +221,11 @@ words the REPL prints, pick it by a rule), then the other name matches (a spec n
 `toolkit.rb`; then one beside the file, so `plugin/context.rb` picks `spec/samagotchi/plugin/*context*` before
 `spec/guardrails/context_spec.rb`), then the specs that name a changed file's class. The default range is the merge-base with main (or origin/main) plus uncommitted and untracked files.
 The Ruby specs go to stdout; the node tests to run (`npm test` targets), "web changed: also run npm run e2e" (with `npm run lint` too when a frontend module changed) and a
-hint for a hub class (named in too many specs to list) go to stderr. Nothing printed means nothing matched.
+hint for a hub class (named in too many specs to list) go to stderr, and so do the `timing:` hints, from the lines a
+changed spec adds (`git diff -U0` against the base; an untracked spec, all its lines): a `Thread.new`, `.start`,
+`spawn` or `fork` with no `join!`, `wait_for`, `with_task_dir` or `Process.wait` added in the same file, and a
+sub-second `be < 0.x` bound ([Waiting and time](#waiting-and-time), rules 3 and 5). Nothing printed means nothing
+matched.
 
 It finds a change's own specs, not the regressions it causes elsewhere. So before committing, run the full suite
 (`bundle exec parallel_rspec -n 8 spec lib/samagotchi/bundles/*/spec`), unless your task says the coordinator runs it; the coordinator runs it at merge

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -236,13 +236,14 @@ module Samagotchi
         case type
         when :command_queued
           # A card's action shows as its card, never as a line (the UIs skip it live).
-          @queued_commands << event.slice(:command_id, :client_id, :line) if event[:waits] && !event[:card]
+          @queued_commands << event.slice(:command_id, :client_id, :line, :author) if event[:waits] && !event[:card]
         when :command_ran
           @queued_commands.reject! { |entry| entry[:command_id] == event[:command_id] } if event[:queued]
         when :turn_enqueued
           queued = { enqueued_id: event[:enqueued_id], client_id: event[:client_id], prompt: event[:prompt] }
           queued[:images] = event[:images] if event[:images]
           queued[:delivery] = event[:delivery] if event[:delivery]
+          queued[:author] = event[:author] if event[:author]
           @queued << queued
         # Taken back before it ran (Bridge#handle_dequeue_turn).
         when :turn_dequeued

data/lib/samagotchi/bridge.rb

@@ -322,11 +322,12 @@ module Samagotchi
     # @param after_file [String, nil] the input file it came in (its
     #   basename): it runs once that file is taken (Worker#on_command)
     # @return [String] its command_id
-    def queue_command(line, client_id: nil, card: false, after_file: nil, enqueued_id: nil)
+    def queue_command(line, client_id: nil, card: false, after_file: nil, enqueued_id: nil, author: nil)
       # A card's action (the step-limit question's answer): the UIs leave
       # its line out. +enqueued_id+: a file-delivered command's input, whose
-      # sender's wait its command_ran settles.
-      command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card).with(enqueued_id: enqueued_id)
+      # sender's wait its command_ran settles. +author+: its input's.
+      command = QueuedCommand.mint(line.to_s.strip, client_id: client_id, card: card, author: author)
+                             .with(enqueued_id: enqueued_id)
       @engine.synchronize_events { queue_command_locked(command, after_file: after_file) }
       command.command_id
     end
@@ -792,10 +793,11 @@ module Samagotchi
 
     # Queues +line+ (a session command) for the worker and announces its
     # :command_queued, unless +deadline+ has passed. Returns [headers,
-    # status, body]: 202 with its command_id, or 408.
-    def queue_command_request(session_id, line, client_id:, deadline: nil, card: false)
+    # status, body]: 202 with its command_id, or 408. +author+: a POST
+    # /turn's (a /word sent as a message).
+    def queue_command_request(session_id, line, client_id:, deadline: nil, card: false, author: nil)
       # A card's action: the UIs leave its line out (the card is the echo).
-      command = QueuedCommand.mint(line, client_id: client_id, card: card)
+      command = QueuedCommand.mint(line, client_id: client_id, card: card, author: author)
       queued = @engine.synchronize_events do
         raise IntakeClosed if stopped?
         next false if expired?("command_expired", deadline, sid: session_id, client_id: command.client_id)
@@ -892,6 +894,10 @@ module Samagotchi
       client_id = fetched(parsed, "client_id")
       # --no-interrupt: the turn runs with the raised iteration limit.
       no_interrupt = fetched(parsed, "no_interrupt") == true
+      # Who wrote it when it isn't the owner (chi web stamps it from the
+      # request's principal; the Bridge is loopback and trusts its caller).
+      author = fetched(parsed, "author")
+      author = nil unless author.is_a?(String) && !author.empty?
       if sid.to_s.strip.empty? || prompt.to_s.strip.empty?
         return [{ "Allow" => "POST" }, 400,
                 { error: "missing_fields", detail: "session_id and prompt are required" }]
@@ -916,7 +922,7 @@ module Samagotchi
       # TUI; an unknown /word stays a prompt. Not with images: those are
       # for the model.
       if images.empty? && @on_command && command_registry.command?(prompt.to_s)
-        return queue_command_request(sid, prompt.to_s.strip, client_id: client_id, deadline: deadline)
+        return queue_command_request(sid, prompt.to_s.strip, client_id: client_id, deadline: deadline, author: author)
       end
 
       enqueued_id = SecureRandom.uuid
@@ -935,12 +941,13 @@ module Samagotchi
 
         queued_behind_turn = Delivery.queue?(delivery) && !@accumulator.current_turn.nil?
         enqueue_turn(prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                     no_interrupt: no_interrupt, images: images, delivery: delivery).tap do |ok|
+                     no_interrupt: no_interrupt, images: images, delivery: delivery, author: author).tap do |ok|
           next unless ok
 
           enqueued_event = { type: :turn_enqueued, enqueued_id: enqueued_id, client_id: client_id, prompt: prompt.to_s }
           enqueued_event[:images] = images unless images.empty?
           enqueued_event[:delivery] = Delivery::QUEUE if queued_behind_turn
+          enqueued_event[:author] = author if author
           @engine.announce(enqueued_event)
           @on_input&.call
         end
@@ -1082,9 +1089,9 @@ module Samagotchi
 
     # Write a turn into this session's input dir, reusing the file IPC the
     # worker polls. Never calls run_turn across the boundary.
-    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil)
+    def enqueue_turn(prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, images: [], delivery: nil, author: nil)
       SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
-                                            no_interrupt: no_interrupt, images: images, delivery: delivery)
+                                            no_interrupt: no_interrupt, images: images, delivery: delivery, author: author)
     end
 
     # ── HTTP plumbing ────────────────────────────────────────────────────────

data/lib/samagotchi/bridge_client/event_stream.rb

@@ -31,8 +31,9 @@ module Samagotchi
     # WebBridgeClient), where the client stays the same object across
     # workers: +epoch_watch+ (a frame whose id has another epoch than the
     # cursor's is a new worker: worker_changed first, the client's key
-    # updated), +announce_retries+ (stream_retrying once a reconnect fails,
-    # stream_resumed at the next frame), +idle_timeout+ (no byte, not even
+    # updated), +announce_retries+ (stream_retrying once a reconnect fails
+    # and rediscovery neither moved nor ended the stream, stream_resumed
+    # once a stream answers again), +idle_timeout+ (no byte, not even
     # the Bridge's 15 s ping, for that long: a half-open connection,
     # reconnected with the cursor).
     class EventStream
@@ -125,7 +126,8 @@ module Samagotchi
             next
           end
 
-          announce_retry
+          # Rediscovery first: a stopped session or a new worker is no
+          # retry to announce (a stop prints its line alone).
           case rediscover_worker
           when :moved
             failures = 0
@@ -133,6 +135,7 @@ module Samagotchi
             next
           when :gone then return finish(@reason || "unreachable")
           end
+          announce_retry
 
           failures += 1
           return finish(@reason || "unreachable") if failures > @reconnect_delays.size
@@ -153,6 +156,9 @@ module Samagotchi
         return :unknown_session if status == 404
         return :unreachable unless status == 200
 
+        # Back as soon as the stream answers: a replay may bring nothing
+        # (the session was quiet), and the next frame could be minutes away.
+        announce_resumed
         yielded = false
         parser = SSEParser.new
         loop do
@@ -163,7 +169,6 @@ module Samagotchi
             event = parse(frame[:data])
             next unless event
 
-            announce_resumed
             watch_epoch(frame[:id]) if @epoch_watch
             @last_event_id = frame[:id] if frame[:id]
             yielded = true

data/lib/samagotchi/bridge_client.rb

@@ -165,9 +165,12 @@ module Samagotchi
     # @param no_interrupt [Boolean] run the turn with the raised iteration limit
     # @param images [Array<Hash>] refs ({file:, name:}) to images already in
     #   the session's images/
-    def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil)
+    # @param author [String, nil] who wrote it when it isn't the session's
+    #   owner; sent only when given (SessionManager.deliver_turn)
+    def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil, author: nil)
       body = { session_id: @session_id, prompt: prompt, client_id: client_id }
       body[:no_interrupt] = true if no_interrupt
+      body[:author] = author if author
       body[:images] = images if images && !images.empty?
       body[:delivery] = delivery unless delivery.nil? || Delivery.next_step?(delivery)
       body[:deadline] = deadline

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

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.103.0
+version: 0.105.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/chi_invocation.rb

@@ -2,12 +2,10 @@
 
 module Samagotchi
   # How the follow-up commands chi prints (ParentReport's chi answer and
-  # chi send --wait, a stop's chi --resume) are spelled so that they work
-  # when pasted: on this machine plain chi, against a remote (chi --remote
-  # NAME, CHI_REMOTE=NAME alike) chi --remote NAME. What runs on this
-  # machine only (--attach, --resume: remote attach is its own phase) has
-  # no remote form: #attach and #resume are nil there, and #open_it and
-  # #shows name the remote's chi web instead.
+  # chi send --wait, a stop's chi --resume, the attached TUI's re-attach
+  # lines) are spelled so that they work when pasted: on this machine plain
+  # chi, against a remote (chi --remote NAME, CHI_REMOTE=NAME alike) chi
+  # --remote NAME. A remote's chi web is named where the page is meant.
   # @!attribute remote [String, nil] the remote's name; nil: this machine
   ChiInvocation = Data.define(:remote) do
     def remote? = !remote.nil?
@@ -18,19 +16,18 @@ module Samagotchi
     # +words+ after #chi: command("answer ID …").
     def command(words) = "#{chi} #{words}"
 
-    # chi --attach ID; nil remotely.
-    def attach(id) = ("chi --attach #{id}" unless remote?)
+    # chi --attach ID (chi --remote NAME --attach ID).
+    def attach(id) = command("--attach #{id}")
 
-    # chi --resume ID; nil remotely.
-    def resume(id) = ("chi --resume #{id}" unless remote?)
+    # chi --resume ID (chi --remote NAME --resume ID).
+    def resume(id) = command("--resume #{id}")
 
-    # What shows the session ("… shows it"): chi --attach ID, or the
-    # remote's chi web.
-    def shows(id) = attach(id) || web
+    # What shows the session ("… shows it"): its attach.
+    def shows(id) = attach(id)
 
-    # Where the user opens it ("open it: …"): chi --attach ID or the web,
-    # or the remote's chi web.
-    def open_it(id) = remote? ? web : "#{attach(id)} or the web"
+    # Where the user opens it ("open it: …"): its attach, or the web (the
+    # remote's chi web).
+    def open_it(id) = "#{attach(id)} or #{remote? ? web : "the web"}"
 
     # The remote's chi web, by name.
     def web = "chi web on #{remote}"

data/lib/samagotchi/config.rb

@@ -306,7 +306,7 @@ module Samagotchi
       Entry.new(key: "web.view",                 yaml_path: %w[web view],                 type: :enum,    default: "stage",        expose: %i[env config cli], enum_values: %w[stage turn], lifecycle: :web_start),
       # The stage view's working set (files, memories and URLs the turn brought into context): a rail in the stage, a
       # footprint under each finished turn and a "set N" chip in place of the mem chip; ?working_set=1|0 overrides it per page load.
-      Entry.new(key: "web.working_set",          yaml_path: %w[web working_set],          type: :bool,    default: false,           expose: %i[env config cli], lifecycle: :web_start),
+      Entry.new(key: "web.working_set",          yaml_path: %w[web working_set],          type: :bool,    default: true,            expose: %i[env config cli], lifecycle: :web_start),
       # Quick replies next to Annotate in the page's selection bubble, "|"-separated (a YAML list works too); "" leaves only Annotate.
       Entry.new(key: "web.annotate_presets",     yaml_path: %w[web annotate_presets],     type: :string, default: "Agreed|Could you please elaborate?", expose: %i[env config cli], lifecycle: :web_start),
       # What a file ref (a tool row's file, a diff line) opens on this machine: a preset (vscode, vscode-insiders, cursor, zed, none) or a URL template with {path} and an optional {line} (Web::Editor).

data/lib/samagotchi/context_status.rb

@@ -116,13 +116,20 @@ module Samagotchi
     #   last status line's bucket is where rises count from)
     # @param llm_context [LLMContextStrategy::Resolved, nil] the turn's
     #   strategy (its budget)
-    def initialize(conversation: [], llm_context: nil)
+    # @param counted_chars_per_token [Float, nil] the last turn's
+    #   #counted_chars_per_token: the turn's estimate before its first count
+    #   uses it instead of the configured ratio, so the value doesn't dip at
+    #   a turn's start (the chat loop's chars leave out the tool schemas the
+    #   server counts)
+    def initialize(conversation: [], llm_context: nil, counted_chars_per_token: nil)
       @budget = llm_context&.budget_tokens
       @forget = llm_context&.forget? || false
       @offered = self.class.last_line(conversation).to_s.include?(OFFER_TOOL)
       @enabled = self.class.enabled?
       chars_per_token = Config.get("context.chars_per_token").to_f
       @chars_per_token = chars_per_token.positive? ? chars_per_token : DEFAULT_CHARS_PER_TOKEN
+      @estimate_chars_per_token = counted_chars_per_token.to_f.positive? ? counted_chars_per_token.to_f : @chars_per_token
+      @counted_chars_per_token = nil
       parsed = Config.get("context.status_thresholds").to_s.split(",").map { |value| value.strip.to_i }
                      .select { |value| value.between?(1, 99) }.uniq.sort
       @thresholds = parsed.empty? ? DEFAULT_THRESHOLDS : parsed
@@ -137,6 +144,10 @@ module Samagotchi
     # @return [Hash, nil] the status line's value ({est_pct:, bucket:});
     #   nil with context.status off or before the first request
     attr_reader :display
+    # @return [Float, nil] the chars per token of the last request the
+    #   server counted (its prompt chars over its prompt tokens, images
+    #   aside), for the next turn's tracker; nil before a count
+    attr_reader :counted_chars_per_token
 
     def enabled? = @enabled
 
@@ -212,6 +223,8 @@ module Samagotchi
 
       @counted = { chars: prompt_chars, image_tokens: image_tokens }
       @edited = false
+      text_tokens = usage[:prompt_tokens].to_i - image_tokens.to_i
+      @counted_chars_per_token = prompt_chars.to_f / text_tokens if prompt_chars.positive? && text_tokens.positive?
       value = display_for(used_tokens: usage[:total_tokens], window_tokens: usage[:context_window_tokens] || window&.tokens)
       @display = value if value
     end
@@ -243,7 +256,7 @@ module Samagotchi
         source = "server"
       else
         window_tokens = counted_against(window.tokens)
-        used_tokens = (prompt_chars / @chars_per_token).ceil + image_tokens
+        used_tokens = (prompt_chars / @estimate_chars_per_token).ceil + image_tokens
         source = "estimate"
       end
 

data/lib/samagotchi/engine.rb

@@ -85,6 +85,7 @@ require_relative "guardrail_wiring"
 require_relative "plugin_tasks"
 require_relative "prompt_warmup"
 require_relative "working_set"
+require_relative "session_participants"
 
 module Samagotchi
   # Engine owns the core agent logic: system prompt construction, tool
@@ -218,6 +219,11 @@ module Samagotchi
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = build_system_prompt(memories, appended_prompt_files)
+      # The session's participants (participants.json), read at each turn's
+      # start: their names for the messages they wrote.
+      @participants = SessionParticipants.new(state_dir: -> { session_state_dir })
+      # Whether the system prompt carries the participants line.
+      @participants_line = false
       @session = nil
       @session_observer = SessionObserver.new
       @metrics = SessionMetrics.new
@@ -414,7 +420,8 @@ module Samagotchi
       SystemPrompt.new(profile: -> { profile }, tools: -> { @tools }, session: -> { @session },
                        thinking: -> { turn_thinking }, model: -> { model_identity },
                        model_notes: -> { model_notes }, memories: memories,
-                       muted_memory_names: @muted_memory_names, appended_files: appended_prompt_files)
+                       muted_memory_names: @muted_memory_names, appended_files: appended_prompt_files,
+                       participants: -> { @participants_line })
     end
     private :build_system_prompt
 
@@ -1462,9 +1469,35 @@ module Samagotchi
       session.last_turn = LastTurn.new(outcome: outcome, ended_at: Time.now.iso8601(3), seconds: seconds.round(1),
                                        origin: source, exhausted: limit ? true : nil, limit: limit,
                                        enqueued_id: enqueued_id.to_s.empty? ? nil : enqueued_id.to_s,
+                                       author: Steer.sender_author(origin.is_a?(Hash) ? origin[:author] : nil),
                                        **stop_facts(event))
     end
 
+    # Reads the session's participants at a turn's start; the first to join
+    # and the last to leave rebuild the system prompt (its participants
+    # line), once each: a turn in between sends the same prefix.
+    def refresh_participants!(session)
+      active = @participants.refresh!(session).active?
+      return if active == @participants_line
+
+      @participants_line = active
+      @prompt_builder.reset!
+    end
+    private :refresh_participants!
+
+    # The author fields a message +author+ wrote carries (Steer.author_fields:
+    # author:, and author_name: from participants.json), {} for the owner.
+    # The worker's drain names a participant's merged lines with it, and
+    # its running save a participant's prompt.
+    # @param origin [Hash, String, nil] a turn's origin, or an author
+    # @param session [Session, nil] the session it is for (the turn's)
+    def author_fields(origin, session: @session)
+      author = origin.is_a?(Hash) ? origin[:author] : origin
+      return {} unless Steer.participant_author?(author)
+
+      Steer.author_fields(author, @participants.name_for(author, session: session))
+    end
+
     # Why a turn stopped, from its end event (LastTurn::STOP_FACTS), for a
     # parent agent's wait (ReplyWait): a provider error's kind and whether
     # a retry may help, a cancel's reason and the hook that stopped it.
@@ -1858,6 +1891,11 @@ module Samagotchi
       @recap&.write_now(on_start: on_start)
     end
 
+    # The longest #write_recap_now waits (recap.timeout), nil when no recap
+    # is set up.
+    # @return [Float, nil]
+    def recap_timeout = @recap&.timeout
+
     # Ask for a recap now (/recap), without waiting for the idle window.
     # @return [Symbol] IdleRecap#request_now's answer, or :off
     def request_recap
@@ -1887,9 +1925,12 @@ module Samagotchi
       self
     end
 
-    # Stop the shared idle scheduler (TerminalUI calls this when the REPL exits).
-    def stop_idle
-      @idle_scheduler&.stop
+    # Stop the shared idle scheduler (TerminalUI calls this when the REPL
+    # exits). +join+: wait for a tick under way (IdleScheduler#stop); a
+    # caller holding #synchronize_events passes false, since a recap's emit
+    # in that tick waits for the same lock.
+    def stop_idle(join: true)
+      @idle_scheduler&.stop(join: join)
       self
     end
 
@@ -1947,9 +1988,11 @@ module Samagotchi
     #   run it resumes started (ModelResult#run_start, kept in the offer by
     #   TurnFlow), so it keeps that run's reasoning; nil starts cold (a
     #   model change while the offer stood, every other turn).
-    # @param origin [Hash, nil] who queued the turn ({client_id:, enqueued_id:});
-    #   when given, the turn's boundary events (:turn_started, :turn_completed,
-    #   :turn_canceled, :turn_failed) carry it as `origin:`
+    # @param origin [Hash, nil] who queued the turn ({client_id:, enqueued_id:},
+    #   and author: when someone other than the session's owner wrote it, from
+    #   its input file; absent for the owner); when given, the turn's boundary
+    #   events (:turn_started, :turn_completed, :turn_canceled, :turn_failed)
+    #   carry it as `origin:`, and GuardrailWiring#begin_turn gets it
     # @param images [Array<Hash>] the prompt's images: {path:} (a file on this
     #   machine; in-process and attached-TUI callers only) or {file:, name:}
     #   (already in the session's images/, e.g. a web upload). They are
@@ -2093,6 +2136,7 @@ module Samagotchi
       # prompt built next declares, unchanged until the next turn's start.
       apply_staged_tools!
       apply_toolkit!(session, turn.on_event)
+      refresh_participants!(session)
       # A Stop during the wait above: the turn ends here,
       # before the hooks run or a reminder is used up.
       return false if turn.controller.cancelled?
@@ -2221,7 +2265,7 @@ module Samagotchi
       end
 
       unless turn.continue
-        user_message = { role: "user", content: turn.prompt, turn_id: turn.id }
+        user_message = { role: "user", content: turn.prompt, turn_id: turn.id, **author_fields(turn.origin) }
         user_message[:images] = image_refs unless image_refs.empty?
         turn.messages << user_message
         session.last_prompt = turn.prompt

data/lib/samagotchi/guardrail_wiring.rb

@@ -83,12 +83,18 @@ module Samagotchi
       @protected = nil
     end
 
-    # A turn starts: its origin, and the git facts read afresh.
+    # A turn starts: its origin (Engine#run_turn's: {client_id:,
+    # enqueued_id:, author:}, each optional), and the git facts read afresh.
     def begin_turn(origin)
       @origin = origin
       @git = Guardrails::GitInfo.new
     end
 
+    # Who wrote the running turn when it isn't the session's owner (its
+    # origin's author); nil for the owner's turns and every other origin.
+    # @return [String, nil]
+    def turn_author = @origin.is_a?(Hash) ? @origin[:author] : nil
+
     # The gate every tool call asks first.
     # @return [Guardrails::Gate]
     def gate

data/lib/samagotchi/idle_recap.rb

@@ -254,7 +254,7 @@ module Samagotchi
     end
 
     # @return [Array(Integer, Integer)] the recap length range, e.g. [2, 4]
-    attr_reader :generation, :inactivity, :min_user_turns, :sentences
+    attr_reader :generation, :inactivity, :min_user_turns, :sentences, :timeout
 
     # @param callable [#call] true while a continue offer waits for an
     #   answer (the Worker's or the REPL's TurnFlow); read at each attempt

data/lib/samagotchi/idle_scheduler.rb

@@ -18,23 +18,37 @@ module Samagotchi
   # raises is logged and isolated — the remaining jobs keep polling.
   class IdleScheduler
     POLL_INTERVAL_SECONDS = 0.5
+    # How long #stop waits for the thread to finish its tick before it
+    # kills it.
+    STOP_JOIN_SECONDS = 1.0
+    THREAD_NAME = "idle_scheduler"
 
-    attr_reader :engine, :jobs
+    attr_reader :engine, :jobs, :interval
 
-    def initialize(engine:, jobs: [])
+    # +interval+: the pause between ticks (a spec passes a long one, so its
+    # own #tick is the only one after the first).
+    def initialize(engine:, jobs: [], interval: POLL_INTERVAL_SECONDS)
       raise ArgumentError, "IdleScheduler requires an engine" unless engine
 
       @engine = engine
       @jobs = jobs.compact.freeze
+      @interval = interval
+      # The loop's pause: a pop with the interval as its timeout, which
+      # #stop ends at once by pushing.
+      @wake = Queue.new
       @thread = nil
+      # The thread a stop(join: false) left to finish its tick.
+      @unjoined = nil
       @stopped = false
     end
 
     # Spawn the polling thread (idempotent; no-op when there are no jobs).
+    # A stopped scheduler doesn't start again.
     def start
       return self if running? || @jobs.empty?
 
       @thread = Thread.new { run_loop }
+      @thread.name = THREAD_NAME
       self
     end
 
@@ -42,11 +56,24 @@ module Samagotchi
       !@thread.nil? && @thread.alive? && !@stopped
     end
 
-    # Stop the polling thread (idempotent).
-    def stop
+    # Stop the polling thread (idempotent): it ticks no more and its pause
+    # ends at once. +join+: wait up to STOP_JOIN_SECONDS for a tick under
+    # way to finish, then kill the thread. A caller holding a lock a tick
+    # may take (Worker#leave_idle holds the event log, which a recap's emit
+    # takes) passes join: false: the thread finishes its tick and exits by
+    # itself, and a later joining stop (Engine#shutdown, the worker's
+    # teardown) still joins it. From the scheduler's own thread (a job's
+    # tick) it never joins.
+    def stop(join: true)
       @stopped = true
-      @thread&.kill
+      @wake << :stop
+      thread = @thread || @unjoined
       @thread = nil
+      @unjoined = join ? nil : thread
+      return if thread.nil? || !join || thread == Thread.current
+
+      thread.kill unless thread.join(STOP_JOIN_SECONDS)
+      nil
     end
 
     # Swap the job +old+ for +new+ (Engine#session= rebuilding the recap):
@@ -78,11 +105,9 @@ module Samagotchi
     private
 
     def run_loop
-      loop do
-        break if @stopped
-
+      until @stopped
         tick
-        sleep(POLL_INTERVAL_SECONDS)
+        @wake.pop(timeout: @interval)
       end
     rescue StandardError => e
       Log.exception(:idle, "scheduler_crashed", e, echo: "[IdleScheduler] scheduler thread crashed: #{e.class}: #{e.message}")