samagotchi 0.62.0 → 0.64.0

data/lib/samagotchi/bundles/loop-guard/plugin.rb

@@ -297,7 +297,7 @@ class Plugin
   def register(chi)
     chi.on(:before_turn) { |_event| reset }
     chi.on(:before_tool_call) { |event, ctx| before(event, ctx) }
-    chi.on(:after_tool_call) { |event| after(event) }
+    chi.on(:after_tool_call) { |event, ctx| after(event, ctx) }
     return unless @thinking["watch"]
 
     chi.on(:before_generation) do |_event|
@@ -377,6 +377,7 @@ class Plugin
     @warned = {}       # key => true once notified this turn
     @denials = 0
     @pending = nil
+    @stop_card = nil   # the stop's card, posted after the denied call
     @thinking_loops = 0
     @good_steps = 0
     @watch = nil
@@ -412,7 +413,8 @@ class Plugin
   # A call's result, paired with the before_tool_call that keyed it. A call
   # that was denied (by us or another voter) ran nothing: no result, or the
   # deny text would become the key's result and the next call would pass.
-  def after(event)
+  def after(event, ctx)
+    post_stop_card(ctx)
     pending = @pending
     @pending = nil
     return unless pending && event[:tool].to_s == pending[:key].first
@@ -426,16 +428,25 @@ class Plugin
     @previews[key] = preview(output)
   end
 
+  # The turn stops now; its card waits for the denied call's
+  # after_tool_call (#post_stop_card), so a UI that prints events in order
+  # shows it under that call's row, not before it.
   def stop(ctx)
     ctx.stop_turn("the model kept repeating the same calls")
     repeated = @attempts.select { |key, n| n > 1 && @last_result[key] && @results[[key, @last_result[key]]] >= @deny_after }
     lines = repeated.map do |key, n|
       "- `#{short_key(key)}`: #{n} times, the same result each time (#{@previews[key]})"
     end
-    ctx.card(title: "loop-guard stopped the turn",
-             body: "The model kept repeating these calls:\n\n#{lines.join("\n")}\n\n" \
-                   "Tell it what to try instead, or where to look.",
-             level: :warn)
+    @stop_card = { title: "loop-guard stopped the turn",
+                   body: "The model kept repeating these calls:\n\n#{lines.join("\n")}\n\n" \
+                         "Tell it what to try instead, or where to look.",
+                   level: :warn }
+  end
+
+  def post_stop_card(ctx)
+    card = @stop_card
+    @stop_card = nil
+    ctx.card(**card) if card
   end
 
   def warn(ctx, key, what)

data/lib/samagotchi/bundles/slow-commands/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: slow-commands
-version: 0.2.1
+version: 0.2.2
 scope: system
 description: "Remembers commands that ran past the execute limit in a project; the next identical execute is denied once a turn with advice to run it with task_create and task_wait; /slow-commands lists and forgets them"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:cc8b9829ae77565d8d47969377e91124cf4c785164e417d3d323daeec1295269
+  sha256: sha256:6bf5da2501a6404cda01c95975b005fce179f756c56222771c5ee857d7ba4b98
 # Execute::HANDED_OVER, read when the plugin loads (0.59.0); after_tool_call's
 # call:, elapsed_ms: and result: (0.57.0)
 requires_chi: ">= 0.59.0"

data/lib/samagotchi/bundles/slow-commands/plugin.rb

@@ -75,9 +75,11 @@ class Plugin
   TIMED_OUT = /\A#{Regexp.escape(Samagotchi::Tools::Execute::TIMEOUT_PREFIX)} (\d+)s/
   # Still running at the limit, handed over as a task (chi >= 0.59.0).
   HANDED_OVER = /\A#{Regexp.escape(Samagotchi::Tools::Execute::HANDED_OVER)} (\d+)s limit/
-  # A stopped command's first words: the user's Stop, or a signal to chi
-  # (chi >= 0.62.0; an older chi has no such text).
-  STOPPED = %i[STOPPED_BY_USER NOT_RUN_ON_STOP STOPPED_BY_SIGNAL NOT_RUN_ON_SIGNAL].filter_map do |name|
+  # A stopped command's first words: the user's Stop, a signal to chi
+  # (chi >= 0.62.0) or a session stop (chi >= 0.64.0); an older chi has no
+  # such text.
+  STOPPED = %i[STOPPED_BY_USER NOT_RUN_ON_STOP STOPPED_BY_SIGNAL NOT_RUN_ON_SIGNAL
+               STOPPED_BY_SESSION_STOP NOT_RUN_ON_SESSION_STOP].filter_map do |name|
     Samagotchi::Tools::Execute.const_get(name) if Samagotchi::Tools::Execute.const_defined?(name)
   end.freeze
   LEX = Samagotchi::Guardrails::ShellLex

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

@@ -57,7 +57,7 @@ Only the nested form is read. An env name used as a top-level key (`SAMAGOTCHI_D
 **Excluded maps** (YAML-only, not part of the flat registry; skipped by scalar loader):
 
 - `model_aliases:` map of alias → model id (`ModelRef.parse`, through `HostRegistry#resolve`). Keys lowercased on write (`ConfigFile.write_model_alias!`). Values may be bare `model` or qualified `host:model` (hybrid; only `:` names a host, `org/model` is an id). Aliases apply once: never point an alias at another alias.
-- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; workers inherit via `SAMAGOTCHI_HOSTS_JSON` (`hosts_json_for_env`, `session_manager.rb`).
+- `hosts:` map of `name → {host, port | url, transport, api, api_key_env, profile, first_token_timeout, vision, sampling, thinking, enabled, models}` (`ConfigFile.hosts_config`, `host_registry.rb` `HostEntry`). Names lowercased; `url:` (http/https, optional path) replaces host/port, never both; `api_key_env:` names the env var holding the API key (never write a key into config.yml); `transport` overrides `server.transport`; `first_token_timeout` (seconds, `0` = off; a negative or non-number warns and is ignored) overrides `server.first_token_timeout` for that host; `models:` (a map of model ids, or a plain list) declares ids the host serves whatever its `/v1/models` lists: no "doesn't list" warning, and a bare id routes there as if listed (`HostModel`); an entry may hold `price: {input, output, cache_read?, cache_write?}` in USD per 1M tokens (`ModelPrice`; an unset cache rate is the input rate), which estimates a cost the provider doesn't report or reports as 0 (`cost_estimate`, shown as `~$`), and `served: [ids] | any`, the models a gateway may answer that id with (no served-model warning for them); model settings stay in the root `models:`; a worker reads `hosts:` from the file as it starts (`SAMAGOTCHI_HOSTS_JSON` replaces it for a process it is set on; `SessionManager.spawn_options` unsets it for workers).
 - `models:` map of model id or alias → `{profile, vision, sampling, thinking, reasoning_history}` (`ConfigFile.model_settings`). `thinking:` (here, on a host, or `thinking.level` for every model) is `off|low|medium|high|default` (`Thinking`; unquoted `off` works, `on` is not a level; `default` = send nothing). Precedence: the session's own level (`/thinking LEVEL`, saved in the session; `chi --thinking` on a session run, `chi send --new --thinking`) > `chi web --thinking`/`SAMAGOTCHI_THINKING_LEVEL` > `models:` > `hosts.<name>.thinking` > `thinking.level` in config.yml > `default`. A `sampling:` key wins over the fields a level sends (`null` drops one); `docs/configuration.md` "Thinking". `reasoning_history:` (here or on a host) is `drop|turn|all`, which of its reasoning a chat host's model gets back. Precedence: the session's own level (`/reasoning-history LEVEL`, saved in the session) > `SAMAGOTCHI_REASONING_HISTORY` > `models:` > `hosts.<name>.reasoning_history` > `turn`; `docs/configuration.md` "Reasoning history". `/thinking` and `/reasoning-history` ask before a change that restarts the prompt cache; `--yes` applies it (`chi send` commands apply directly). `sampling:` (here or on a host) is a map of request fields passed to the provider as written (`temperature`, `top_p`, `presence_penalty`, `repeat_penalty`, …; a model's fields win over its host's per field; `null` = don't send; chi's own fields like `max_tokens`/`stream` are refused with a warning; `docs/configuration.md` "Sampling"). Keys match case-insensitively. `profile` (here or on a host) is `qwen36|gemma4`: the raw prompt format for native hosts. Precedence: `--profile`/`SAMAGOTCHI_MODEL_PROFILE` > `models:` > `hosts.<name>.profile` > the llama.cpp server's chat template > the name (`qwen`/`gemma`) > `qwen36` (`ModelProfile.resolve`). Set one when a model's name hides its family (e.g. a Qwen fine-tune under another name on mlx, which has no template to read).
 - `hooks:` map of `hooks_dir` + per-event lists `{path, on_error}` (`Hooks::Loader.load`). `hooks_dir` may start with `~`.
 - `guardrails:` tool-call rules (`docs/guardrails.md`; read in `Engine#guardrail_rules`, parsed by `Guardrails::Rules.parse`): `enabled` (bool, default true; `false` drops rules and hooks' asks, a deny still applies; config.yml only, like every `guardrails` setting: no env variable), `parent_approvals` (`off`, the default: a parent agent's `chi answer` can only deny an approval; `once`: it may give "Allow once" too; a convention for an honest parent, not a security boundary, and the user's choice: set it only when the user asks), `rules:` (list), `disable:` (a rule id or a list of them, `id` or `bundle:id`, switching off a bundle's or config rule without editing it), `small_models` (`auto`, the default: small = 32B or less read from the name; a glob or list of globs; `[]` for none). A rule takes only `id`, `tool`, `command`, `path`, `git`, `models`, `verdict`, `reason`, `scopes`: `id` required; at least one of `tool` (a name, `shell` = execute + task_create, a `File.fnmatch` glob like `"mcp_*"`, or a list), `command` (a Ruby regex on the shell command), `path` (a glob, or `outside_repo`: outside the session's repo, tmp folders and memory files excepted), `git` (only `outside_repo`: a shell call runs commit/add/reset/… in another checkout); `models` (optional: `small`, a model-name glob, or a list; without it the rule is for every model); `verdict` `ask|deny`; `scopes` (for `ask`) a subset of `once, session, repo, rule`. **Any parse error (an unknown key, a bad regex, no verdict) makes chi deny every tool call** until fixed, so validate with `YAML.safe_load` and keep the list shape. Rules are read again on the next tool call after config.yml or a bundle's rules change: no restart needed. Installed bundles' rule files (`chi bundle install guardrails`) add to them; `/guardrails` lists what loaded.

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.62.0
+version: 0.64.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:dfc19266259a9af1e0d769b7e0f67996b740b0c9921fdf3dadad973f6e5c144a
-  config_modification_protocol.md: sha256:16403da5dd97a335e19d9d15bb1ba4390237bf9f4869e35d63c172a8828b5ae0
-  memory_guide.md: sha256:d16919387c42d229498f470fc4078245a15faee872480ffbeffe2e27897624e4
+  config_modification_protocol.md: sha256:99ad8a596cc0f5129caf82cc00314d597f0ec309be96e2d48ca4fa936b4ae343
+  memory_guide.md: sha256:b0a1ba42c5334d4117b5733c8c26d7477364baca9169b0c0a711de6ac7fc7f3c
   delegated.md: sha256:aedaa1e756a244904c5560fff0424e06fb468bbdcb0358bccefe321d67cd2614

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

@@ -94,7 +94,7 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 - Integrity: each file's sha256 is recorded at install; a hook/plugin/rule file changed afterwards is not loaded (rules: every call denied) until reinstalled. It is an integrity check, not proof of authorship.
 - Installing = trusting its Ruby code (hooks, plugin), like a gem. Install only copies; the code runs at the next session start (`Engine.new`), so a running worker needs a restart to pick it up.
 - A bundle without `*.md` (btw, mcp, loop-guard) adds no line to the prompt's memory index.
-- Profiles are shipped bundles with only `includes:` (bundle names): `core` (loop-guard, check-in, guardrails, slow-commands; `chi bootstrap` installs it) and `dev` (known-names, mcp, btw, skills, source-links, github-pr, coordinator). `chi bundle install core` installs the ones not installed and records them; a bundle the user uninstalled stays out on a later install, upgrade or `chi update`, which install only bundles new to the profile. `chi bundle uninstall core` removes its recorded bundles, then core (`docs/memory.md` "Bundle profiles").
+- Profiles are shipped bundles with only `includes:` (bundle names): `core` (loop-guard, check-in, guardrails, slow-commands; `chi bootstrap` installs it) and `dev` (known-names, mcp, btw, skills, source-links, github-pr, coordinator, claude-peer). `chi bundle install core` installs the ones not installed and records them; a bundle the user uninstalled stays out on a later install, upgrade or `chi update`, which install only bundles new to the profile. `chi bundle uninstall core` removes its recorded bundles, then core (`docs/memory.md` "Bundle profiles").
 
 ### CLI — `chi bundle`
 

data/lib/samagotchi/child_reports.rb

@@ -231,11 +231,16 @@ module Samagotchi
       return nil unless child.parent_id == @session_id
 
       before = @taken[child_id]&.after || Tools::DelegateCursors.get(@session_id, child_id, state_dir: @state_dir)
+      # A follow-up's turn (DelegateCursor#turn) is reported by its own
+      # reply, as delegate_result takes it, not a newer queued turn's.
       wait = ReplyWait.call(child_id, state_dir: @state_dir, cursor: before.reply_file, baseline: before.baseline,
-                                      timeout: 0)
+                                      timeout: 0, turn: before.turn)
       return nil unless reportable?(wait)
 
-      after = before.with(reply_file: wait.status == :done ? wait.file : before.reply_file)
+      # A reported end is the follow-up turn's too (DelegateCursor#turn):
+      # a later wait on it would repeat its reply.
+      after = before.with(reply_file: wait.status == :done ? wait.file : before.reply_file,
+                          turn: wait.status == :waiting_for_answer ? before.turn : nil)
                     .with_baseline(ReplyWait.baseline_of(wait.session))
       text = Tools::DelegateWait.finish(wait, child_id, timeout: 0, report: true)
       Report.new(child_id: child_id, text: text, before: before, after: after, rings: rings)

data/lib/samagotchi/cli/parent_wait.rb

@@ -57,10 +57,17 @@ module Samagotchi
       # report it. Ctrl-C leaves the turn running (130).
       # @param owner_grace [Numeric, nil] seconds with no live worker before
       #   it counts as gone; nil waits for whatever wakes one
+      # @param turn [String, nil] the enqueued_id of the turn waited for
+      #   (ReplyWait's turn:): a queued message's, or the turn an answer or
+      #   a --wait with no message is about (ReplyWait.own_turn)
+      # @param queued [Boolean] +turn+ is a queued message's (ReplyWait's
+      #   queued:)
       # @return [Integer] the exit status
-      def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: self.class::WORKER_GONE_AFTER)
+      def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: self.class::WORKER_GONE_AFTER, turn: nil,
+                         queued: false)
         result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
-                                    owner_grace: owner_grace, poll_interval: self.class::POLL_INTERVAL)
+                                    owner_grace: owner_grace, poll_interval: self.class::POLL_INTERVAL, turn: turn,
+                                    queued: queued)
         result.text = result.text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
         @reported = true
         ParentReport.report(result, session_id: id, stdout: @stdout, stderr: @stderr, command: command_name,

data/lib/samagotchi/composer_route.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "delivery"
+
+module Samagotchi
+  # Where a line typed at a terminal's prompt goes, for both terminals (the
+  # REPL's TerminalUI#steer_line / #run_input_line, the attached
+  # AttachedLoop#submit). It only classifies; each UI keeps what it does
+  # with the answer (the REPL's mid-turn command policy and image lines, the
+  # attached TUI's continue offer and question). The web's composer.js
+  # routeComposerLine decides the same; spec/fixtures/composer_routes.json
+  # holds the cases both answer (docs/testing.md).
+  #
+  # In order:
+  #   1. /cut TEXT, /queue TEXT (.steer_choice), before every command check:
+  #      the bare word is :usage. While a turn runs TEXT is a :deliver with
+  #      its delivery (Delivery::CUT, Delivery::QUEUE); whether the worker
+  #      can queue is the UI's to check. With none running TEXT is routed
+  #      on as a line (step 2), its own /cut not read again.
+  #   2. A line: :empty; a terminal's own word (:local, the registry's
+  #      lookup_local id: :exit, :archive, :detach, :stats, :recap…); a
+  #      session command (:command); a typo of one (:typo, the hint in
+  #      +reply+); else :prompt. A line with images (+images+) is a message:
+  #      no command or typo check.
+  module ComposerRoute
+    CUT_COMMAND = "/cut"
+    QUEUE_COMMAND = "/queue"
+    # The word, then any whitespace and the text (as the registry's
+    # entries match them, so a line Tab or /help knows is never a prompt).
+    STEER_CHOICE = /\A(#{CUT_COMMAND}|#{QUEUE_COMMAND})(?:\s+(.*))?\z/m
+
+    KINDS = %i[empty usage deliver local command typo prompt].freeze
+
+    # @!attribute kind [Symbol] one of KINDS
+    # @!attribute text [String, nil] the line stripped: a /cut's or
+    #   /queue's own text, not the word
+    # @!attribute delivery [String, nil] a :deliver's Delivery value
+    # @!attribute reply [String, nil] a :typo's hint
+    # @!attribute local [Symbol, nil] a :local's registry id
+    # @!attribute choice [Symbol, nil] :cut or :queue when the line was
+    #   typed with that word (an idle one's text routed on keeps it)
+    Route = Data.define(:kind, :text, :delivery, :reply, :local, :choice) do
+      def initialize(kind:, text: nil, delivery: nil, reply: nil, local: nil, choice: nil)
+        super
+      end
+    end
+
+    # @param line [String, nil] as typed
+    # @param running [Boolean] a turn runs
+    # @param registry [Commands::Registry] the session's commands
+    # @param images [Integer] the attachments not in the text (the web's
+    #   chips); a terminal's @path images are its own to handle (0)
+    # @return [Route]
+    def self.call(line, running:, registry:, images: 0)
+      text = line.to_s.strip
+      choice, message = steer_choice(text)
+      return line_route(text, registry: registry, images: images) unless choice
+      return Route.new(kind: :usage, choice: choice) if message.empty?
+      return line_route(message, registry: registry, images: images).with(choice: choice) unless running
+
+      Route.new(kind: :deliver, text: message, delivery: choice == :cut ? Delivery::CUT : Delivery::QUEUE, choice: choice)
+    end
+
+    # The choice a line carries, as [:cut, "TEXT"] or [:queue, "TEXT"]; nil
+    # for any other line. The text is "" when the line named the choice
+    # without one.
+    # @param line [String, nil]
+    # @return [Array(Symbol, String), nil]
+    def self.steer_choice(line)
+      match = STEER_CHOICE.match(line.to_s.strip) or return nil
+
+      [match[1] == CUT_COMMAND ? :cut : :queue, match[2].to_s.strip]
+    end
+
+    def self.line_route(text, registry:, images:)
+      return Route.new(kind: :empty, text: text) if text.empty?
+
+      if images.zero?
+        local = registry.lookup_local(text)&.id
+        return Route.new(kind: :local, text: text, local: local) if local
+        return Route.new(kind: :command, text: text) if registry.command?(text)
+
+        hint = registry.unknown_command_hint(text)
+        return Route.new(kind: :typo, text: text, reply: hint) if hint
+      end
+      Route.new(kind: :prompt, text: text)
+    end
+    private_class_method :line_route
+  end
+end

data/lib/samagotchi/config.rb

@@ -857,7 +857,7 @@ module Samagotchi
     HOST_NAME_RE = /\A[a-z0-9][a-z0-9._-]*\z/i
     ENV_NAME_RE = /\A[A-Za-z_][A-Za-z0-9_]*\z/
 
-    # config.yml's hosts: (or a worker's SAMAGOTCHI_HOSTS_JSON) by lowercased
+    # config.yml's hosts: (or a SAMAGOTCHI_HOSTS_JSON override) by lowercased
     # name; an entry that is disabled or invalid (warned) is left out. No
     # entry left: "default", from server.host/port/transport.
     # @return [Hash{String => HostConfig}]
@@ -914,7 +914,7 @@ module Samagotchi
 
     # The names (lowercased) of the hosts entries with enabled: false, which
     # hosts_config leaves out. Read from the same source: config.yml's
-    # hosts:, or SAMAGOTCHI_HOSTS_JSON in a worker.
+    # hosts:, or a SAMAGOTCHI_HOSTS_JSON override.
     # @return [Array<String>]
     def disabled_host_names(env: ENV, path: global_path(env: env))
       raw = hosts_source(read_yaml(env: env, path: path), env)
@@ -926,7 +926,8 @@ module Samagotchi
     end
 
     # config.yml's hosts: as written, or the SAMAGOTCHI_HOSTS_JSON override
-    # a worker inherits from its parent.
+    # set on this process (specs; SessionManager.spawn_options unsets it for
+    # a worker, which reads the file).
     def hosts_source(data, env)
       raw = data[HOSTS_KEY] if data.is_a?(Hash)
       env_json = env["SAMAGOTCHI_HOSTS_JSON"].to_s.strip
@@ -1041,6 +1042,8 @@ module Samagotchi
       hosts.keys.map { |k| k.to_s.downcase }.include?(prefix) ? nil : prefix
     end
 
+    # hosts_config as a SAMAGOTCHI_HOSTS_JSON override (workers no longer
+    # get one: they read config.yml).
     def hosts_json_for_env(env: ENV, path: global_path(env: env))
       hosts = hosts_config(env: env, path: path)
       # Only serialize if non-default or explicitly configured hosts:

data/lib/samagotchi/context_absorber.rb

@@ -16,8 +16,9 @@ module Samagotchi
   class ContextAbsorber
     # +note+: Engine#add_context_note's hash; +subscription+: the session's
     # Subscription after it (nil: dropped); +wake_note+: the same note with
-    # the wake line, for an update whose source asked to wake (the worker
-    # may start a turn with it), else nil.
+    # the wake line, for an update whose source asked to wake or a session
+    # push source's first text that asked (the worker may start a turn with
+    # it), else nil.
     Delivery = Data.define(:name, :note, :subscription, :wake_note) do
       def initialize(name:, note:, subscription:, wake_note: nil) = super
     end
@@ -93,9 +94,12 @@ module Samagotchi
         "(third-party text, not your user's words):\n> #{quoted}\n#{last_line}"
     end
 
-    def self.attached_text(name:, hint:, why:, summary:)
+    # The attached note's text; a wake turn's (+wake+) ends with the wake
+    # line in place of the background line.
+    def self.attached_text(name:, hint:, why:, summary:, wake: false)
       why_part = why ? " Why: #{why}#{"." unless why.match?(/[.!?]\z/)}" : ""
-      "Attached: #{name}#{" (#{hint})" if hint}.#{why_part}\nSummary: #{summary}\n#{BACKGROUND_LINE} #{read_line(name)}"
+      last_line = wake ? WAKE_LAST_LINE : "#{BACKGROUND_LINE} #{read_line(name)}"
+      "Attached: #{name}#{" (#{hint})" if hint}.#{why_part}\nSummary: #{summary}\n#{last_line}"
     end
 
     def self.read_line(name) = "Read it with context_read(name: \"#{name}\") when your user's request is about it."
@@ -105,6 +109,8 @@ module Samagotchi
     # A source the session sees: attached when it has text and was never
     # noted; updated for a new revision; an error once per run of failures
     # after a success. A source with no text yet waits (nothing to read).
+    # An update that asked to wake carries a wake note, and so does a first
+    # text that asked when #first_text_wakes?.
     def delivery_for(attached, sub, now)
       snapshot = attached.snapshot
       return nil unless snapshot.text?
@@ -112,8 +118,11 @@ module Samagotchi
       name = attached.name
       hint = snapshot.hint || attached.source.hint
       if sub.seen.nil?
-        text = self.class.attached_text(name: name, hint: hint, why: attached.source.why, summary: snapshot.summary)
-        return delivery(name, text_note_id(name, snapshot), text, now, seen(sub, snapshot))
+        args = { name: name, hint: hint, why: attached.source.why, summary: snapshot.summary }
+        found = delivery(name, text_note_id(name, snapshot), self.class.attached_text(**args), now, seen(sub, snapshot))
+        return found unless first_text_wakes?(attached, sub)
+
+        return found.with(wake_note: found.note.merge(text: self.class.attached_text(**args, wake: true)))
       end
       if sub.seen != snapshot.revision
         args = { name: name, hint: hint, summary: snapshot.summary, changes: snapshot.serial - sub.seen_serial }
@@ -131,6 +140,16 @@ module Samagotchi
                sub.with(error_seen: snapshot.error_since))
     end
 
+    # A first text may wake only for a session's pushed source (`chi context
+    # add NAME --push`, attached empty) that asked. Not for a command source
+    # (a URL/provider source has a cmd too): its first fetch runs as it is
+    # attached, while the user is likely looking at the session. Not for a
+    # project source: its first text may predate this session. A blank
+    # Subscription has seen_serial 0, so any revision that asked counts.
+    def first_text_wakes?(attached, sub)
+      attached.source.push? && attached.location.session? && attached.snapshot.wake_serial.to_i > sub.seen_serial
+    end
+
     # A subscription whose source is gone: detached when the session was
     # told of it, dropped quietly otherwise.
     def detached(sub, now)

data/lib/samagotchi/continue_offer.rb

@@ -85,12 +85,17 @@ module Samagotchi
     # Called with the event log held, before the command's command_ran. A
     # Stop runs no turn: last_turn says so (not_continued), so a wait on
     # it ends (chi answer --option Stop).
+    # It carries the offer turn's enqueued_id, so a wait on that turn
+    # (ReplyWait's turn:) ends on it too.
     def announce_resolved(result, command)
       @engine.announce(type: :continue_resolved, decision: result.decision.to_s, client_id: command.client_id)
       return if result.resume
 
       session = @engine.session
-      session.last_turn = LastTurn.new(outcome: NOT_CONTINUED, ended_at: Time.now.iso8601(3)) if session
+      return unless session
+
+      session.last_turn = LastTurn.new(outcome: NOT_CONTINUED, ended_at: Time.now.iso8601(3),
+                                       enqueued_id: offer_turn_id)
     end
 
     # After a command's command_ran and save: a /continue that answered the
@@ -117,9 +122,13 @@ module Samagotchi
     # asks again, one before the turn began too (logged, no :turn_failed).
     # The answer's text is carried into the turn as it begins; a turn that
     # never began leaves it to no other.
+    # The continue turn is the offer turn's: its origin carries that turn's
+    # enqueued_id, so its last_turn, its reply file and its checkpoint mark
+    # do too, and a wait on that turn (chi answer) gets its reply.
     def run_continue_turn(command)
       offer = @turn_flow.offer
       resume_from = @turn_flow.resume_from
+      enqueued_id = offer_turn_id
       close("answered")
       steer = @continue_steer
       @continue_steer = nil
@@ -131,8 +140,8 @@ module Samagotchi
           Log.warn(:worker, "turn_not_begun", continue: true, error: e.class.name, msg: e.message)
           return announce_offer(offer)
         end
-        @run_turn.call(nil, continue: true, origin: { client_id: command.client_id }.compact, resumed: true,
-                            resume_from: resume_from,
+        origin = { client_id: command.client_id, enqueued_id: enqueued_id }.compact
+        @run_turn.call(nil, continue: true, origin: origin, resumed: true, resume_from: resume_from,
                             max_iterations: @max_iterations.call(offer[:no_interrupt])) do |result, error|
           if error
             announce_offer(offer)
@@ -156,6 +165,11 @@ module Samagotchi
 
     private
 
+    # The enqueued_id of the turn the offer stands for: the exhausted
+    # turn's last_turn (a canceled continue turn's carries the same id);
+    # nil when it ran no input (a reminder turn, a delegate's first).
+    def offer_turn_id = @engine.session&.last_turn&.enqueued_id
+
     def announce_offer(offer = @turn_flow.offer)
       @engine.announce(type: :continue_offered, context: offer[:context], no_interrupt: offer[:no_interrupt])
       ask

data/lib/samagotchi/delivery.rb

@@ -23,25 +23,30 @@ module Samagotchi
     # Why a request body's delivery field can't be taken, as {error:,
     # detail:} for a 400, or nil when it can. The Bridge and the web's
     # POST /turn both ask this, so they refuse the same values. A missing
-    # or unknown string is not refused: it is the default (#parse). QUEUE
-    # is refused until a worker runs it (no worker reads it yet, so it
-    # would merge at the next step while the ack said queue).
+    # or unknown string is not refused: it is the default (#parse).
     # @param raw [Object] the wire value
     # @return [Hash, nil]
     def self.refusal(raw)
       return nil if raw.nil?
       return { error: "bad_delivery", detail: "delivery must be a string" } unless raw.is_a?(String)
-      return QUEUE_UNAVAILABLE if raw == QUEUE
 
       nil
     end
 
+    # The worker sidecar feature (Bridge::FEATURES) of a worker that runs
+    # all three values. One without it (before 0.64) ignores QUEUE, or
+    # refuses it with a 400 delivery_unavailable, so a sender checks it
+    # before sending a queue (SessionManager.deliver_turn, the attached TUI).
+    QUEUE_FEATURE = "delivery"
+
+    # The refusal for a queue a worker without QUEUE_FEATURE would steer
+    # (SessionManager.deliver_turn answers it as a 409). P0-P2 workers
+    # answer the same error code for a queue, with their own detail.
     QUEUE_UNAVAILABLE = {
-      error: "delivery_unavailable",
-      detail: "delivery queue isn't available yet; without it the message goes in at the running turn's next step " \
-              "(or runs as a turn when none runs)"
+      "error" => "delivery_unavailable",
+      "detail" => "this session's worker predates queueing, so the message would steer the running turn; " \
+                  "restart it (chi sessions restart ID, or the web's update badge) and send again"
     }.freeze
-    private_constant :QUEUE_UNAVAILABLE
 
     # Whether it is the one every sender defaulting to a step boundary uses.
     def self.next_step?(value) = parse(value) == NEXT_STEP

data/lib/samagotchi/engine.rb

@@ -1433,8 +1433,10 @@ module Samagotchi
                elsif client_id == ClientId::REMINDER then "reminder"
                else "client"
                end
+      enqueued_id = origin.is_a?(Hash) ? origin[:enqueued_id] : nil
       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,
                                        **stop_facts(event))
     end
 

data/lib/samagotchi/host_config.rb

@@ -9,9 +9,9 @@ require_relative "reasoning_history"
 module Samagotchi
   # One config.yml hosts: entry, parsed and checked (ConfigFile.hosts_config
   # holds them by lowercased name; HostRegistry builds its HostEntry from
-  # one). A worker gets its parent's hosts back through
-  # SAMAGOTCHI_HOSTS_JSON: #to_env_h writes every field, and .parse reads
-  # it back to an equal HostConfig.
+  # one). #to_env_h writes every field in the shape of the
+  # SAMAGOTCHI_HOSTS_JSON override (ConfigFile.hosts_json_for_env), and
+  # .parse reads it back to an equal HostConfig.
   #
   # name: the lowercased entry name; host, port, scheme: where it is (from
   # url: when given); url: the configured url, nil when host/port; transport,
@@ -26,7 +26,7 @@ module Samagotchi
       super(**members.to_h { |m| [m, nil] }, models: {}, **fields)
     end
 
-    # A hosts: entry as written (YAML, or a worker's SAMAGOTCHI_HOSTS_JSON),
+    # A hosts: entry as written (YAML, or a SAMAGOTCHI_HOSTS_JSON override),
     # or nil when it is disabled (enabled: false) or invalid. An invalid
     # one warns once, naming the entry, the way each reader of a setting
     # does for a bad value (that value is then unset).
@@ -160,10 +160,10 @@ module Samagotchi
     end
     private_class_method :invalid
 
-    # The entry as a worker's SAMAGOTCHI_HOSTS_JSON carries it (string keys,
+    # The entry as a SAMAGOTCHI_HOSTS_JSON override carries it (string keys,
     # unset fields left out); .parse(name, to_env_h) gives it back. A url
     # entry travels as its url (host/port come from it); the API key stays
-    # in the environment, which workers inherit.
+    # in the environment.
     # @return [Hash{String => Object}]
     def to_env_h
       location = url ? { "url" => url } : { "host" => host, "port" => port }

data/lib/samagotchi/host_model.rb

@@ -104,8 +104,8 @@ module Samagotchi
       end
     end
 
-    # The entry as written back to config (SAMAGOTCHI_HOSTS_JSON for
-    # workers): nil for a bare id.
+    # The entry as written back to config (HostConfig#to_env_h): nil for a
+    # bare id.
     def to_config
       config = { "price" => price&.to_config, "served" => served }.compact
       config unless config.empty?

data/lib/samagotchi/idle_recap.rb

@@ -7,6 +7,7 @@ require "time"
 
 require_relative "idle_client"
 require_relative "idle_target"
+require_relative "image_store"
 require_relative "output_formatter"
 require_relative "steer"
 require_relative "recap_store"
@@ -53,8 +54,6 @@ module Samagotchi
       # separator, while the chat loop writes one message per call.
       TOOL_OUTPUT_SEPARATOR = "\n\n---\n\n"
       TOOL_OUTPUT_HEADER_RE = /\A\[([\w.:-]+)\]/
-      # The text the web sends for a turn of images alone (images.js turnText).
-      IMAGE_ONLY_RE = /\A\s*(?:\[image: [^\]\n]*\]\s*)+\z/
       DELEGATE_REPORT_LINE = "(a delegate session's report, delivered by chi; not the user's words)"
 
       module_function
@@ -76,7 +75,7 @@ module Samagotchi
             # A delegate child's report (ChildReports) is chi's news, not
             # what the user said.
             content = "#{DELEGATE_REPORT_LINE}\n#{content}" if message["source"].to_s == Steer::DELEGATE_REPORT
-            images = IMAGE_ONLY_RE.match?(content) ? [] : image_lines(message["images"])
+            images = ImageRef.placeholder_only?(content) ? [] : image_lines(message["images"])
             [content, *images].reject(&:empty?).join("\n")
           when "model", "assistant"
             strip_thought(message["content"].to_s.gsub(TOOL_CALL_RE, ""))

data/lib/samagotchi/image_store.rb

@@ -159,6 +159,14 @@ module Samagotchi
   # One-line texts about an image ref ({file:, mime:, width:, height:,
   # bytes:, name:, source:}).
   module ImageRef
+    # The text the web sends for a turn of images alone (images.js
+    # turnText): "[image: name]" per image, nothing else.
+    PLACEHOLDER_ONLY_RE = /\A\s*(?:\[image: [^\]\n]*\]\s*)+\z/
+
+    # Whether +text+ is only that placeholder: the images' own lines would
+    # name them a second time.
+    def self.placeholder_only?(text) = PLACEHOLDER_ONLY_RE.match?(text.to_s)
+
     # Claude's rule of thumb (28×28 px per token). About 30% over on the
     # local Qwen, close enough for a label and the context estimate.
     def self.estimated_tokens(ref)

data/lib/samagotchi/interrupted_turn.rb

@@ -9,9 +9,13 @@ module Samagotchi
   #
   # id: the turn's id (nil when unknown); started_at / at: iso8601, when the
   # turn began and when this checkpoint was taken; iteration: the loop
-  # boundaries it had passed (Integer).
-  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration) do
-    def initialize(id: nil, started_at: nil, at: nil, iteration: nil) = super
+  # boundaries it had passed (Integer); enqueued_id: the input the turn
+  # runs (its ack's id, LastTurn#enqueued_id once it ends; a Continue turn
+  # carries its offer turn's), so any process that loads the session can
+  # tell which turn is running (ReplyWait.own_turn); nil when it ran none,
+  # or a worker from before it wrote one.
+  InterruptedTurn = Data.define(:id, :started_at, :at, :iteration, :enqueued_id) do
+    def initialize(id: nil, started_at: nil, at: nil, iteration: nil, enqueued_id: nil) = super
 
     # A saved record (string or symbol keys), an InterruptedTurn as it is;
     # nil for anything else.

data/lib/samagotchi/last_turn.rb

@@ -12,9 +12,12 @@ module Samagotchi
   # children's reports) or "context" (one an attached context source's
   # change started); exhausted/limit: the turn ran out of iterations at
   # limit. The rest are its stop facts (LastTurn::STOP_FACTS), only what is
-  # known. A field may be nil (unset; left out of the file).
+  # known. enqueued_id: the input's id when the turn ran one (a POST /turn
+  # ack's, an input file's), so a wait for a queued message (`chi send
+  # --queue --wait`, ReplyWait's turn:) tells its own turn's end from
+  # another's. A field may be nil (unset; left out of the file).
   LastTurn = Data.define(:outcome, :ended_at, :seconds, :origin, :exhausted, :limit,
-                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by) do
+                         :error_kind, :retryable, :kept_steps, :cancel_reason, :stopped_by, :enqueued_id) do
     def initialize(**fields)
       super(**members.to_h { |m| [m, nil] }, **fields)
     end

data/lib/samagotchi/pending_input_queue.rb

@@ -19,17 +19,24 @@ module Samagotchi
     end
 
     # Append a message to the queue. Nil/empty strings are ignored.
-    def push(text)
+    # +seq+ is the sender's own order number for it (the REPL numbers every
+    # line it takes during a turn, so its leftovers keep send order across
+    # this queue and its after-turn list: #drain_entries).
+    def push(text, seq: nil)
       text = text.to_s
       return if text.empty?
 
-      @mutex.synchronize { @messages << text }
+      @mutex.synchronize { @messages << [seq, text] }
       nil
     end
 
     # Remove and return all queued messages in FIFO order. Non-blocking.
     # @return [Array<String>]
-    def drain
+    def drain = drain_entries.map(&:last)
+
+    # #drain with each message's +seq+ (nil when pushed without one).
+    # @return [Array(Integer|nil, String)]
+    def drain_entries
       @mutex.synchronize do
         drained = @messages
         @messages = []